Merge pull request #2793 from ronimuliawan/main

chore: adding path details to avoid confusion.

docs/ANTIGRAVITY-GUIDE.md

@@ -4,14 +4,31 @@ Google Antigravity 2.0 discovers workspace customizations from the project-local
 `.agents/` directory. ECC's Antigravity target installs native rules, workflows,
 skills, and custom agents into that directory.
 
+Native Antigravity 2.0 installation requires ECC 2.2.0 or newer. ECC 2.1.0 uses
+the legacy `.agent/` adapter and does not provide the native layout described
+below.
+
 ## Quick start
 
 ```bash
+# Run every command below from the project you want to configure.
+# Keep the ECC source checkout separate and use its absolute path.
+ECC_ROOT="/absolute/path/to/ECC"
+
 # Install the minimal profile
-./install.sh --profile minimal --target antigravity
+"$ECC_ROOT/install.sh" --profile minimal --target antigravity
 
 # Compatibility syntax: common rules plus only these language packs
-./install.sh --target antigravity typescript python go
+"$ECC_ROOT/install.sh" --target antigravity typescript python go
+```
+
+PowerShell uses the same project-root working-directory contract:
+
+```powershell
+$EccRoot = "C:\absolute\path\to\ECC"
+
+& "$EccRoot\install.ps1" --profile minimal --target antigravity
+& "$EccRoot\install.ps1" --target antigravity typescript python go
 ```
 
 Start a new Antigravity conversation after installing so the agent receives the
@@ -55,13 +72,24 @@ your-project/
 
 ## Verify the installation
 
+macOS and Linux:
+
 ```bash
-node scripts/list-installed.js --target antigravity
-node scripts/doctor.js --target antigravity
+node "$ECC_ROOT/scripts/list-installed.js" --target antigravity
+node "$ECC_ROOT/scripts/doctor.js" --target antigravity
 rg --files .agents/skills -g 'SKILL.md'
 rg --files .agents/agents -g '*.md'
 ```
 
+PowerShell:
+
+```powershell
+node "$EccRoot\scripts\list-installed.js" --target antigravity
+node "$EccRoot\scripts\doctor.js" --target antigravity
+Get-ChildItem .agents\skills -Recurse -Filter SKILL.md
+Get-ChildItem .agents\agents -Recurse -Filter *.md
+```
+
 In Antigravity, open **Settings > Customizations**, confirm that workspace
 skills appear, start a new conversation, and request one by its exact name.
 
@@ -78,10 +106,20 @@ owned by the valid legacy state. Modified and unmanaged files remain in
 
 Preview lifecycle operations before applying them when desired:
 
+macOS and Linux:
+
 ```bash
-node scripts/doctor.js --target antigravity
-node scripts/repair.js --target antigravity --dry-run
-node scripts/uninstall.js --target antigravity --dry-run
+node "$ECC_ROOT/scripts/doctor.js" --target antigravity
+node "$ECC_ROOT/scripts/repair.js" --target antigravity --dry-run
+node "$ECC_ROOT/scripts/uninstall.js" --target antigravity --dry-run
+```
+
+PowerShell:
+
+```powershell
+node "$EccRoot\scripts\doctor.js" --target antigravity
+node "$EccRoot\scripts\repair.js" --target antigravity --dry-run
+node "$EccRoot\scripts\uninstall.js" --target antigravity --dry-run
 ```
 
 ## Troubleshooting

tests/docs/antigravity-guide.test.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const guidePath = path.join(repoRoot, 'docs', 'ANTIGRAVITY-GUIDE.md');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed++;
+  }
+}
+
+console.log('\n=== Testing Antigravity guide commands ===\n');
+
+const guide = fs.readFileSync(guidePath, 'utf8');
+
+test('guide requires an installer with native Antigravity 2.0 support', () => {
+  assert.ok(
+    guide.includes('ECC 2.2.0 or newer'),
+    'Guide should state the minimum ECC version that installs into .agents'
+  );
+});
+
+test('guide keeps the target project as the working directory', () => {
+  assert.ok(
+    guide.includes('Run every command below from the project you want to configure'),
+    'Guide should make the project-root working-directory contract explicit'
+  );
+  assert.ok(
+    guide.includes('ECC_ROOT="/absolute/path/to/ECC"'),
+    'Guide should define an absolute ECC source path separately from the target project'
+  );
+  assert.ok(
+    guide.includes('$EccRoot = "C:\\absolute\\path\\to\\ECC"'),
+    'Guide should define the equivalent absolute source path for PowerShell users'
+  );
+});
+
+test('guide installs through dependency-bootstrapping wrappers', () => {
+  assert.ok(guide.includes('"$ECC_ROOT/install.sh" --profile minimal --target antigravity'));
+  assert.ok(guide.includes('& "$EccRoot\\install.ps1" --profile minimal --target antigravity'));
+  assert.ok(
+    !guide.includes('node "$ECC_ROOT/scripts/install-apply.js"'),
+    'Fresh source installs should not bypass the wrapper dependency bootstrap'
+  );
+});
+
+test('guide invokes every post-install lifecycle script through the absolute ECC source path', () => {
+  for (const script of ['list-installed.js', 'doctor.js', 'repair.js', 'uninstall.js']) {
+    assert.ok(
+      guide.includes(`node "$ECC_ROOT/scripts/${script}"`),
+      `Guide should invoke ${script} through ECC_ROOT`
+    );
+    assert.ok(
+      guide.includes(`node "$EccRoot\\scripts\\${script}"`),
+      `Guide should invoke ${script} through EccRoot in PowerShell`
+    );
+  }
+
+  assert.ok(!guide.includes('./install.sh'), 'Guide should not target the current project through a relative ECC installer path');
+  assert.ok(!/node scripts\/(?:list-installed|doctor|repair|uninstall)\.js/.test(guide));
+});
+
+test('repository has no accidental nested ECC gitlink', () => {
+  assert.ok(
+    !fs.existsSync(path.join(repoRoot, 'ECC')),
+    'The documentation PR should not add an ECC gitlink without .gitmodules metadata'
+  );
+});
+
+console.log(`\nPassed: ${passed}`);
+console.log(`Failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);

tests/scripts/install-ps1.test.js

@@ -91,19 +91,20 @@ function runTests() {
 
   if (!powerShellCommand) {
     console.log('  - skipped delegation test; PowerShell is not available in PATH');
-  } else if (test('delegates to the Node installer and preserves dry-run output', () => {
+  } else if (test('delegates to the Antigravity installer while preserving the project cwd', () => {
     const homeDir = createTempDir('install-ps1-home-');
     const projectDir = createTempDir('install-ps1-project-');
 
     try {
-      const result = run(powerShellCommand, ['--target', 'cursor', '--dry-run', 'typescript'], {
+      const result = run(powerShellCommand, ['--target', 'antigravity', '--dry-run', 'typescript'], {
         cwd: projectDir,
         homeDir,
       });
 
       assert.strictEqual(result.code, 0, result.stderr);
       assert.ok(result.stdout.includes('Dry-run install plan'));
-      assert.ok(!fs.existsSync(path.join(projectDir, '.cursor', 'hooks.json')));
+      assert.ok(result.stdout.includes(path.join(projectDir, '.agents')));
+      assert.ok(!fs.existsSync(path.join(projectDir, '.agents')));
     } finally {
       cleanup(homeDir);
       cleanup(projectDir);

tests/scripts/install-sh.test.js

@@ -22,10 +22,11 @@ function run(args = [], options = {}) {
   const env = {
     ...process.env,
     HOME: options.homeDir || process.env.HOME,
+    ...(options.env || {}),
   };
 
   try {
-    const stdout = execFileSync('bash', [SCRIPT, ...args], {
+    const stdout = execFileSync('bash', [options.scriptPath || SCRIPT, ...args], {
       cwd: options.cwd,
       env,
       encoding: 'utf8',
@@ -86,6 +87,49 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('absolute wrapper bootstraps a fresh source while preserving the target project cwd', () => {
+    const sourceDir = createTempDir('install-sh-source-');
+    const projectDir = createTempDir('install-sh-target-');
+    const binDir = path.join(sourceDir, 'test-bin');
+    const scriptsDir = path.join(sourceDir, 'scripts');
+    const npmCwdPath = path.join(sourceDir, 'npm-cwd.txt');
+    const fixtureScript = path.join(sourceDir, 'install.sh');
+
+    try {
+      fs.mkdirSync(binDir, { recursive: true });
+      fs.mkdirSync(scriptsDir, { recursive: true });
+      fs.copyFileSync(SCRIPT, fixtureScript);
+      fs.writeFileSync(
+        path.join(binDir, 'npm'),
+        `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p "$PWD/node_modules"\nprintf '%s\\n' "$PWD" > "$ECC_TEST_NPM_CWD"\n`,
+        { mode: 0o755 }
+      );
+      fs.writeFileSync(
+        path.join(scriptsDir, 'install-apply.js'),
+        'console.log(JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2) }));\n'
+      );
+
+      const result = run(['--target', 'antigravity', '--dry-run', 'typescript'], {
+        cwd: projectDir,
+        scriptPath: fixtureScript,
+        env: {
+          ECC_TEST_NPM_CWD: npmCwdPath,
+          PATH: `${binDir}${path.delimiter}${process.env.PATH}`,
+        },
+      });
+
+      assert.strictEqual(result.code, 0, result.stderr);
+      const payload = JSON.parse(result.stdout.trim().split('\n').at(-1));
+      assert.strictEqual(payload.cwd, fs.realpathSync(projectDir));
+      assert.deepStrictEqual(payload.args, ['--target', 'antigravity', '--dry-run', 'typescript']);
+      assert.strictEqual(fs.readFileSync(npmCwdPath, 'utf8').trim(), sourceDir);
+      assert.ok(fs.existsSync(path.join(sourceDir, 'node_modules')));
+    } finally {
+      cleanup(sourceDir);
+      cleanup(projectDir);
+    }
+  })) passed++; else failed++;
+
   if (test('exposes the corrected Claude target help text', () => {
     const result = run(['--help']);
     assert.strictEqual(result.code, 0, result.stderr);