antigravity-sidecar-kit 1.0.1 → 1.0.3

package/README.md

@@ -13,13 +13,14 @@ Google Antigravity's built-in `sidecar_sdk` provides a minimal `SidecarApp` loop
 Generate a complete, Hangar-compatible Antigravity Auxiliary Pane sidecar in one command:
 
 ```bash
-# Using npx create-* shorthand
-npx create-antigravity-sidecar my-sidecar
-
-# Or via the CLI binary directly
-npx agy-sidecar-kit init my-sidecar
+npx antigravity-sidecar-kit init my-sidecar
+cd antigravity-my-sidecar
+npm install
+npm run setup
 ```
 
+Options: `--dir <target-dir>` to choose the output folder, `--force` to overwrite an existing scaffold.
+
 What gets generated:
 - `package.json` — ESM configuration with `setup`, `start`, `uninstall`, and `test` scripts.
 - `sidecar.json` — Antigravity `SidecarManager` manifest (`SIDECAR_UI_ENTRYPOINT_AUX_PANE`).
@@ -87,8 +88,8 @@ await manageSidecar('my-sidecar', 'SIDECAR_ACTION_RESTART');
 const customRes = await callLsRpc('GetMcpServerStates', {});
 ```
 
-- **Automatic Credential Persistence**: When imported inside a running sidecar daemon (`ANTIGRAVITY_SIDECAR_WEB_PORT` + `ANTIGRAVITY_LS_ADDRESS`), `persistSidecarRuntime` caches `{ pid, webPort, lsAddress, csrfToken }` to `~/.gemini/antigravity/sidecar_data/<id>/data/runtime.json` so CLI tools (`setup.mjs`) invoked from external terminals can talk to the Language Server even when env vars aren't exported in the user's shell.
-- **Fallback Process Restarter (`killSidecarProcessByPortOrPid`)**: If the Language Server RPC is unreachable from an external terminal, inspects `runtime.json` PID first and falls back to parsing `listening on 127.0.0.1:<port>` from `logs/sidecar.log`, sending `SIGTERM` so Antigravity's `"restart_policy": "always"` respawns the updated sidecar immediately.
+- **Automatic Credential Persistence**: When imported inside a running sidecar daemon (`ANTIGRAVITY_SIDECAR_WEB_PORT` + `ANTIGRAVITY_LS_ADDRESS`), `persistSidecarRuntime` caches `{ pid, webPort, lsAddress, csrfToken }` to `~/.gemini/antigravity/sidecar_data/<id>/data/runtime.json` (owner-only, mode `0600` on macOS/Linux) so CLI tools (`setup.mjs`) invoked from external terminals can talk to the Language Server even when env vars aren't exported in the user's shell.
+- **Fallback Process Restarter (`killSidecarProcessByPortOrPid`)**: If the Language Server RPC is unreachable from an external terminal, sends `SIGTERM` to the sidecar so Antigravity's `"restart_policy": "always"` respawns the updated version. It only kills a process it can verify: the `runtime.json` PID must still own the recorded `webPort`, and when the port only comes from `logs/sidecar.log`, only `node` processes listening on it are stopped. A stale `runtime.json` is ignored.
 
 ---
 
@@ -154,13 +155,18 @@ await runSidecarSetup({
 });
 ```
 
+Command-line flags read from `args` (default `process.argv`): `--skip-tests`, `--uninstall`, and `--force`.
+
 What `runSidecarSetup` handles automatically:
 1. Verifies Node.js `>= 20.0.0` and all `requiredFiles`.
-2. Runs `testFiles` via `node --test` unless `--skip-tests` is passed.
-3. **Ephemeral `_npx` Copy & SDK Bundling (`resolvePermanentLinkSource`)**: When executed via `npx`, copies the package out of the temporary `_npx` cache into `~/.gemini/hangar/packages/<id>@<version>` and guarantees `node_modules/antigravity-sidecar-kit` is present inside the permanent copy whether npm nested or hoisted the dependency.
-4. Links `~/.gemini/config/sidecars/<id>` using an NTFS directory junction on Windows or symlink on macOS/Linux.
-5. Enables `sidecars[id].enabled = true` in `~/.gemini/config/config.json` (preserving `projectId`).
-6. Hot-reloads the sidecar via `ManageSidecar` RPC (`SIDECAR_ACTION_RESTART` $\rightarrow$ `SIDECAR_ACTION_ENABLE`) or `killSidecarProcessByPortOrPid` fallback.
+2. Refuses to continue if `~/.gemini/config/sidecars/<id>` is a real directory (an in-place checkout) rather than a link, unless setup is running from inside that directory or `--force` is passed. Nothing is run, copied, or deleted before this check.
+3. Runs `testFiles` via `node --test` unless `--skip-tests` is passed.
+4. **Ephemeral `_npx` Copy & SDK Bundling (`resolvePermanentLinkSource`)**: When executed via `npx`, copies the package out of the temporary `_npx` cache into `~/.gemini/hangar/packages/<id>@<version>` and guarantees `node_modules/antigravity-sidecar-kit` is present inside the permanent copy whether npm nested or hoisted the dependency. **Only `antigravity-sidecar-kit` is carried over**: sidecars installed this way must have no other runtime dependencies, and setup warns if `package.json` lists any.
+5. Links `~/.gemini/config/sidecars/<id>` using an NTFS directory junction on Windows or symlink on macOS/Linux.
+6. Enables `sidecars[id].enabled = true` in `~/.gemini/config/config.json` (preserving `projectId`, written atomically via temp file + rename).
+7. Hot-reloads the sidecar via `ManageSidecar` RPC (`SIDECAR_ACTION_RESTART` $\rightarrow$ `SIDECAR_ACTION_ENABLE`) or `killSidecarProcessByPortOrPid` fallback.
+
+`--uninstall` removes the link (never a real directory unless `--force` is passed), disables the sidecar in `config.json`, and prunes `~/.gemini/hangar/packages/<id>@*` copies left by earlier `npx` installs.
 
 ---
 
@@ -177,6 +183,7 @@ import {
 } from 'antigravity-sidecar-kit/workspace';
 
 normalizeWorkspacePath('file:///c%3A/Projects/App/'); // -> 'c:/Projects/App'
+normalizeWorkspacePath('file:///home/dev/app');       // -> '/home/dev/app'
 matchesWorkspaceRule('c:/Projects/App/packages/api', ['c:/Projects/App']); // -> true
 ```
 
@@ -187,6 +194,7 @@ matchesWorkspaceRule('c:/Projects/App/packages/api', ['c:/Projects/App']); // ->
 ```text
 antigravity-sidecar-kit/
 ├── package.json
+├── .github/workflows/test.yml  # CI: Linux, macOS, Windows × Node 20/22/24
 ├── bin/
 │   └── cli.mjs                 # CLI scaffolder (agy-sidecar-kit / create-antigravity-sidecar)
 ├── lib/
@@ -198,7 +206,10 @@ antigravity-sidecar-kit/
 │   ├── server.mjs              # SidecarApp asset & stylesheet route factories
 │   ├── workspace.mjs           # Workspace URI normalizer, glob matcher & trajectory resolver
 │   └── scaffolder.mjs          # Project template generator
+├── packages/
+│   └── create-antigravity-sidecar/   # `npm create antigravity-sidecar` launcher (published separately)
 └── test/
+    ├── cli.test.mjs
     ├── config.test.mjs
     ├── rpc.test.mjs
     ├── theme.test.mjs
@@ -208,6 +219,23 @@ antigravity-sidecar-kit/
 
 ---
 
+## Changes in 1.0.3
+
+- The CLI is exported as `antigravity-sidecar-kit/cli`, so launcher packages such as `create-antigravity-sidecar` can run it.
+
+## Changes in 1.0.2
+
+- `npx antigravity-sidecar-kit init <name>` now works: the package exposes a bin with its own name. The previous README commands pointed at unpublished package names.
+- Setup no longer deletes an in-place checkout at `~/.gemini/config/sidecars/<id>`; it refuses unless `--force` is passed.
+- The restart fallback no longer kills a process based on a stale `runtime.json` PID.
+- The UI token is no longer appended to protocol-relative (`//host`) URLs, and is inserted before `#fragment`s.
+- `file:///home/...` URIs normalize to absolute POSIX paths.
+- `runtime.json` is written owner-only; `config.json` writes are atomic.
+- Uninstall prunes old `npx` copies; setup warns about dependencies that the `npx` copy can't carry.
+- Scaffolded projects pass `ResponseClass: Response` and depend on the current kit version.
+
+---
+
 ## License
 
 [MIT](./LICENSE)

package/bin/cli.mjs

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 /**
- * @fileoverview CLI entrypoint for create-antigravity-sidecar / agy-sidecar-kit.
+ * @fileoverview CLI entrypoint for antigravity-sidecar-kit / create-antigravity-sidecar / agy-sidecar-kit.
  */
 
+import { isAbsolute, relative } from 'node:path';
 import { scaffoldSidecarProject } from '../lib/scaffolder.mjs';
 
+const USAGE = 'Usage: npx antigravity-sidecar-kit init <sidecar-name> [--dir <target-dir>] [--force]';
+
 const rawArgs = process.argv.slice(2);
 let name = '';
 let targetDir = '';
@@ -26,14 +29,24 @@ for (let i = 0; i < rawArgs.length; i++) {
   }
 }
 
-if (!name || rawArgs.includes('--help') || rawArgs.includes('-h')) {
-  console.log('Usage: agy-sidecar-kit init <sidecar-name> [--dir <target-dir>] [--force]');
-  process.exit(name ? 0 : 1);
+if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (!name) {
+  console.error(USAGE);
+  process.exit(1);
 }
 
 try {
   const res = scaffoldSidecarProject({ name, targetDir, force });
+  const rel = relative(process.cwd(), res.outDir);
+  const cdPath = !rel ? '.' : rel.startsWith('..') || isAbsolute(rel) ? res.outDir : rel;
   console.log(`[antigravity-sidecar-kit] Scaffolded ${res.pkgName} at ${res.outDir}`);
+  console.log('\nNext steps:');
+  console.log(`  cd ${cdPath.includes(' ') ? `"${cdPath}"` : cdPath}`);
+  console.log('  npm install');
+  console.log('  npm run setup');
 } catch (err) {
   console.error(`[antigravity-sidecar-kit] Error: ${err.message}`);
   process.exit(1);

package/lib/config.mjs

@@ -2,7 +2,15 @@
  * @fileoverview OS-aware Antigravity paths and UTF-8 BOM-safe JSON config helpers.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
@@ -47,9 +55,39 @@ export function readJsonFile(filePath, { strict = false, fallback = {} } = {}) {
   return res && typeof res === 'object' ? res : structuredClone(fallback);
 }
 
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+/**
+ * Writes JSON without a BOM via temp file + rename, so readers (including Antigravity
+ * itself for config.json) never observe a truncated or half-written file.
+ */
 export function writeJsonNoBom(filePath, data) {
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  let target = filePath;
+  try {
+    // Write through symlinked files instead of replacing the link
+    target = realpathSync(filePath);
+  } catch {
+    // does not exist yet
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  const content = JSON.stringify(data, null, 2) + '\n';
+  const tmpPath = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, content, 'utf8');
+  for (let attempt = 0; ; attempt++) {
+    try {
+      renameSync(tmpPath, target);
+      return;
+    } catch (err) {
+      if (!RENAME_RETRY_CODES.has(err?.code) || attempt >= 3) break;
+      // Windows: another process may briefly hold the file open
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+  }
+  try {
+    writeFileSync(target, content, 'utf8');
+  } finally {
+    rmSync(tmpPath, { force: true });
+  }
 }
 
 export const writeJsonFile = writeJsonNoBom;

package/lib/rpc.mjs

@@ -4,11 +4,12 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { SIDECAR_DATA_ROOT, readJsonSafe } from './config.mjs';
 
 const DEFAULT_TIMEOUT_MS = 4000;
+const EXEC_OPTS = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
 
 function inferCurrentSidecarId() {
   if (process.env.ANTIGRAVITY_SIDECAR_ID) return String(process.env.ANTIGRAVITY_SIDECAR_ID).trim();
@@ -42,17 +43,25 @@ export function persistSidecarRuntime(
   }
   try {
     const dir = join(sidecarDataRoot, sidecarId, 'data');
-    mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const runtimePath = join(dir, 'runtime.json');
+    // runtime.json holds the Language Server CSRF token, so keep it owner-only
     writeFileSync(
-      join(dir, 'runtime.json'),
+      runtimePath,
       JSON.stringify({
         pid: process.pid,
         webPort: Number(env.ANTIGRAVITY_SIDECAR_WEB_PORT) || 0,
         lsAddress: env.ANTIGRAVITY_LS_ADDRESS,
         csrfToken: env.ANTIGRAVITY_CSRF_TOKEN || '',
       }) + '\n',
-      'utf8'
+      { encoding: 'utf8', mode: 0o600 }
     );
+    try {
+      // mode only applies on creation; tighten files written by older versions
+      chmodSync(runtimePath, 0o600);
+    } catch {
+      // ignore (e.g. Windows)
+    }
     return true;
   } catch {
     return false;
@@ -61,7 +70,11 @@ export function persistSidecarRuntime(
 
 persistSidecarRuntime();
 
-export function readCachedLsCredentials(sidecarDataRoot = SIDECAR_DATA_ROOT, preferredId = '') {
+export function readCachedLsCredentials(
+  sidecarDataRoot = SIDECAR_DATA_ROOT,
+  preferredId = '',
+  { lsAddress: matchAddress = '' } = {}
+) {
   const candidates = [preferredId, 'hangar', 'context-monitor'].filter(Boolean);
   try {
     if (existsSync(sidecarDataRoot)) {
@@ -78,6 +91,7 @@ export function readCachedLsCredentials(sidecarDataRoot = SIDECAR_DATA_ROOT, pre
       if (!existsSync(p)) continue;
       const data = JSON.parse(readFileSync(p, 'utf8'));
       if (data?.lsAddress && data?.csrfToken) {
+        if (matchAddress && String(data.lsAddress) !== matchAddress) continue;
         return { lsAddress: String(data.lsAddress), csrfToken: String(data.csrfToken) };
       }
     } catch {
@@ -92,35 +106,71 @@ export function getLsConfig(overrides = {}) {
   let lsAddress = overrides.lsAddress ?? env.ANTIGRAVITY_LS_ADDRESS ?? '';
   let csrfToken = overrides.csrfToken ?? env.ANTIGRAVITY_CSRF_TOKEN ?? '';
   if ((!lsAddress || !csrfToken) && overrides.lsAddress === undefined) {
-    const cached = readCachedLsCredentials(overrides.sidecarDataRoot, overrides.sidecarId);
+    // With a known address, only accept a token cached for that same Language Server
+    const cached = readCachedLsCredentials(overrides.sidecarDataRoot, overrides.sidecarId, {
+      lsAddress,
+    });
     if (!lsAddress) lsAddress = cached.lsAddress;
     if (!csrfToken) csrfToken = cached.csrfToken;
   }
   return { lsAddress, csrfToken };
 }
 
+export function findListeningPids(port, { execFn = execFileSync } = {}) {
+  const p = Number(port);
+  if (!Number.isInteger(p) || p <= 0) return [];
+  try {
+    const rawOut =
+      process.platform === 'win32'
+        ? execFn(
+            'powershell.exe',
+            [
+              '-NoProfile',
+              '-Command',
+              `(Get-NetTCPConnection -LocalPort ${p} -State Listen -ErrorAction SilentlyContinue).OwningProcess`,
+            ],
+            EXEC_OPTS
+          )
+        : execFn('lsof', ['-ti', `tcp:${p}`, '-sTCP:LISTEN'], EXEC_OPTS);
+    const pids = String(rawOut || '')
+      .split(/\r?\n/)
+      .map((s) => Number.parseInt(s.trim(), 10))
+      .filter((n) => Number.isFinite(n) && n > 0 && n !== process.pid);
+    return [...new Set(pids)];
+  } catch {
+    return [];
+  }
+}
+
+export function isNodeProcess(pid, { execFn = execFileSync } = {}) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    const rawOut =
+      process.platform === 'win32'
+        ? execFn(
+            'powershell.exe',
+            ['-NoProfile', '-Command', `(Get-Process -Id ${n} -ErrorAction SilentlyContinue).ProcessName`],
+            EXEC_OPTS
+          )
+        : execFn('ps', ['-p', String(n), '-o', 'comm='], EXEC_OPTS);
+    return /(^|[\\/])node(\.exe)?$/i.test(String(rawOut || '').trim());
+  } catch {
+    return false;
+  }
+}
+
 export function killSidecarProcessByPortOrPid(
   sidecarId,
   { sidecarDataRoot = SIDECAR_DATA_ROOT, execFn = execFileSync, killFn = process.kill } = {}
 ) {
   if (!sidecarId) return { restarted: false };
+  let runtimePid = 0;
   let port = 0;
-  try {
-    const rtPath = join(sidecarDataRoot, sidecarId, 'data', 'runtime.json');
-    if (existsSync(rtPath)) {
-      const rt = JSON.parse(readFileSync(rtPath, 'utf8'));
-      if (rt?.pid && Number(rt.pid) > 0 && Number(rt.pid) !== process.pid) {
-        try {
-          killFn(Number(rt.pid), 'SIGTERM');
-          return { restarted: true, method: `pid:${rt.pid}` };
-        } catch {
-          // Process already exited; fall through to log port check
-        }
-      }
-      if (rt?.webPort) port = Number(rt.webPort);
-    }
-  } catch {
-    // ignore
+  const rt = readJsonSafe(join(sidecarDataRoot, sidecarId, 'data', 'runtime.json'), null);
+  if (rt && typeof rt === 'object') {
+    if (Number(rt.pid) > 0) runtimePid = Number(rt.pid);
+    if (Number(rt.webPort) > 0) port = Number(rt.webPort);
   }
 
   if (!port) {
@@ -138,40 +188,34 @@ export function killSidecarProcessByPortOrPid(
     }
   }
 
+  // Never kill on a PID alone: runtime.json outlives the sidecar, and the OS may have
+  // reused that PID for an unrelated process (Windows recycles PIDs aggressively).
   if (!port) return { restarted: false };
+  const owners = findListeningPids(port, { execFn });
 
-  try {
-    const rawOut =
-      process.platform === 'win32'
-        ? execFn(
-            'powershell.exe',
-            [
-              '-NoProfile',
-              '-Command',
-              `(Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue).OwningProcess`,
-            ],
-            { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
-          )
-        : execFn('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN'], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-          });
-    const pids = String(rawOut || '')
-      .split(/\r?\n/)
-      .map((s) => Number.parseInt(s.trim(), 10))
-      .filter((n) => Number.isFinite(n) && n > 0 && n !== process.pid);
-    if (pids.length > 0) {
-      for (const pid of pids) {
-        try {
-          killFn(pid, 'SIGTERM');
-        } catch {
-          // ignore
-        }
-      }
-      return { restarted: true, method: `port:${port}->pid:${pids.join(',')}` };
+  if (runtimePid) {
+    if (!owners.includes(runtimePid)) return { restarted: false, reason: 'stale runtime.json' };
+    try {
+      killFn(runtimePid, 'SIGTERM');
+      return { restarted: true, method: `pid:${runtimePid}` };
+    } catch {
+      return { restarted: false };
     }
-  } catch {
-    // ignore
+  }
+
+  // Port recovered from the log only: kill just the node processes listening on it
+  const killed = [];
+  for (const pid of owners) {
+    if (!isNodeProcess(pid, { execFn })) continue;
+    try {
+      killFn(pid, 'SIGTERM');
+      killed.push(pid);
+    } catch {
+      // ignore
+    }
+  }
+  if (killed.length > 0) {
+    return { restarted: true, method: `port:${port}->pid:${killed.join(',')}` };
   }
   return { restarted: false };
 }

package/lib/scaffolder.mjs

@@ -2,10 +2,12 @@
  * @fileoverview Scaffolds a minimal, Hangar-compatible Antigravity sidecar project.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { writeJsonNoBom } from './config.mjs';
 
+const KIT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
 export function sanitizeSidecarName(raw = '') {
   return String(raw || '')
     .trim()
@@ -51,7 +53,7 @@ export function scaffoldSidecarProject({ name, targetDir, force = false } = {})
     },
     engines: { node: '>=20.0.0' },
     dependencies: {
-      'antigravity-sidecar-kit': '^1.0.1',
+      'antigravity-sidecar-kit': `^${KIT_VERSION}`,
     },
     scripts: {
       start: 'node server.mjs',
@@ -122,7 +124,7 @@ runSidecarSetup({
 
   writeFileSync(
     join(outDir, 'server.mjs'),
-    `import { SidecarApp } from 'sidecar_sdk';
+    `import { SidecarApp, Response } from 'sidecar_sdk';
 import { realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -132,12 +134,16 @@ import { resolveHostTheme } from 'antigravity-sidecar-kit/theme';
 const __dirname = realpathSync(dirname(fileURLToPath(import.meta.url)));
 const UI_DIR = join(__dirname, 'ui');
 
+// Pass the SDK's Response class so SidecarApp's instanceof checks recognise handler results
+const serveAsset = (relPath, contentType) =>
+  createAssetHandler(UI_DIR, relPath, contentType, { ResponseClass: Response });
+
 const app = new SidecarApp();
-app.page('/', createAssetHandler(UI_DIR, 'index.html', 'text/html; charset=utf-8'));
-app.page('/index.html', createAssetHandler(UI_DIR, 'index.html', 'text/html; charset=utf-8'));
-app.page('/compiled_tailwind.css', createAgyCssHandler());
-app.page('/styles.css', createAssetHandler(UI_DIR, 'styles.css', 'text/css; charset=utf-8'));
-app.page('/app.js', createAssetHandler(UI_DIR, 'app.js', 'text/javascript; charset=utf-8'));
+app.page('/', serveAsset('index.html', 'text/html; charset=utf-8'));
+app.page('/index.html', serveAsset('index.html', 'text/html; charset=utf-8'));
+app.page('/compiled_tailwind.css', createAgyCssHandler({ ResponseClass: Response }));
+app.page('/styles.css', serveAsset('styles.css', 'text/css; charset=utf-8'));
+app.page('/app.js', serveAsset('app.js', 'text/javascript; charset=utf-8'));
 
 app.api('/api/status', async () => ({
   ok: true,

package/lib/server.mjs

@@ -19,23 +19,35 @@ let SdkResponse = FallbackResponse;
 try {
   const sdk = await import('sidecar_sdk');
   if (sdk?.Response) SdkResponse = sdk.Response;
-} catch {
-  // Running outside Antigravity SidecarManager (e.g. standalone unit tests)
+} catch (err) {
+  // Expected outside Antigravity SidecarManager (e.g. standalone unit tests); inside a
+  // sidecar it means handlers will return FallbackResponse, which SidecarApp won't recognise.
+  if (process.env.ANTIGRAVITY_SIDECAR_WEB_PORT) {
+    console.warn(
+      `[antigravity-sidecar-kit] Could not import sidecar_sdk (${err?.message || err}); ` +
+        'pass { ResponseClass: Response } to createAssetHandler/createAgyCssHandler.'
+    );
+  }
 }
 
 const DEFAULT_BOOT_TS = Date.now();
 
+// Same-origin absolute paths only: skips protocol-relative //host URLs and paths that
+// already carry a query string, and keeps any #fragment after the injected query.
+const LOCAL_ASSET_ATTR = /(\s(?:src|href))="(\/(?!\/)[^"?#]*)(#[^"]*)?"/g;
+
 export function createAssetHandler(uiDir, relPath, contentType, options = {}) {
   const ResponseClass = options.ResponseClass || SdkResponse;
   const bootTs = options.bootTs ?? DEFAULT_BOOT_TS;
   return () => {
     const uiToken = options.uiToken ?? process.env.ANTIGRAVITY_SIDECAR_UI_TOKEN ?? '';
     const raw = readFileSync(join(uiDir, relPath), 'utf-8');
+    const query = `?token=${encodeURIComponent(uiToken)}&v=${bootTs}`;
     const body =
       relPath.endsWith('.html') && uiToken
         ? raw.replace(
-            /(src|href)="(\/[^"?]+)"/g,
-            `$1="$2?token=${encodeURIComponent(uiToken)}&v=${bootTs}"`
+            LOCAL_ASSET_ATTR,
+            (_, attr, path, fragment = '') => `${attr}="${path}${query}${fragment}"`
           )
         : raw;
     return new ResponseClass(body, { contentType });

package/lib/setup.mjs

@@ -9,12 +9,13 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readdirSync,
   realpathSync,
   rmSync,
   symlinkSync,
   unlinkSync,
 } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   CONFIG_JSON_PATH,
@@ -47,7 +48,31 @@ export function removeLinkOrDir(targetPath) {
   return true;
 }
 
-export function createSidecarLink(sourceDir, linkPath) {
+/**
+ * True when targetPath is a real directory rather than a symlink or junction
+ * (Windows junctions report isSymbolicLink() === true).
+ */
+export function isRealDirectory(targetPath) {
+  try {
+    const stat = lstatSync(targetPath);
+    return stat.isDirectory() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function assertNotInPlaceCheckout(linkPath, sourceRealPath, force) {
+  if (force || !isRealDirectory(linkPath)) return;
+  if (realpathSync(linkPath) === sourceRealPath) return;
+  const err = new Error(
+    `Refusing to replace ${linkPath}: it is a real directory (an in-place checkout?), not a link. ` +
+      'Run setup from inside that directory, move it away, or re-run with --force to replace it.'
+  );
+  err.code = 'EINPLACECHECKOUT';
+  throw err;
+}
+
+export function createSidecarLink(sourceDir, linkPath, { force = false } = {}) {
   mkdirSync(resolve(linkPath, '..'), { recursive: true });
   const resolvedSource = realpathSync(resolve(sourceDir));
   let alreadyLinked = false;
@@ -59,19 +84,38 @@ export function createSidecarLink(sourceDir, linkPath) {
     }
   }
   if (!alreadyLinked) {
+    assertNotInPlaceCheckout(linkPath, resolvedSource, force);
     removeLinkOrDir(linkPath);
     symlinkSync(resolvedSource, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
   }
   return resolvedSource;
 }
 
+/**
+ * Path of `src` relative to `root` as '' (the root itself) or '/a/b', for cpSync filters.
+ * Slicing by string length breaks when Windows hands the filter a differently-cased or
+ * short-name form of the root, so compare as paths and fall back to canonical real paths.
+ */
+function pathFromRoot(root, src) {
+  let rel = relative(root, src);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    try {
+      rel = relative(realpathSync.native(root), realpathSync.native(src));
+    } catch {
+      // keep the first answer
+    }
+  }
+  rel = rel.replace(/\\/g, '/');
+  return rel ? `/${rel}` : '';
+}
+
 export function bundleSidecarKit(targetDir, kitRoot = KIT_ROOT) {
   if (!targetDir || !kitRoot || !existsSync(join(kitRoot, 'package.json'))) return false;
   const targetKitDir = join(targetDir, 'node_modules', 'antigravity-sidecar-kit');
   mkdirSync(join(targetDir, 'node_modules'), { recursive: true });
   cpSync(kitRoot, targetKitDir, {
     recursive: true,
-    filter: (src) => !/^\/(\.git|node_modules)(\/|$)/.test(src.slice(kitRoot.length).replace(/\\/g, '/')),
+    filter: (src) => !/^\/(\.git|node_modules|test)(\/|$)/.test(pathFromRoot(kitRoot, src)),
   });
   return true;
 }
@@ -89,6 +133,15 @@ export function resolvePermanentLinkSource(
     return resolvedRoot;
   }
   const pkgJson = readJsonSafe(join(resolvedRoot, 'package.json'), {});
+  const droppedDeps = Object.keys(pkgJson.dependencies || {}).filter(
+    (dep) => dep !== 'antigravity-sidecar-kit'
+  );
+  if (droppedDeps.length > 0) {
+    console.warn(
+      `[antigravity-sidecar-kit] Warning: the permanent copy only bundles antigravity-sidecar-kit; ` +
+        `these dependencies will be missing at runtime: ${droppedDeps.join(', ')}`
+    );
+  }
   const cleanVer = String(version || pkgJson.version || '1.0.0').replace(/[^a-z0-9._-]+/gi, '') || '1.0.0';
   const id =
     sidecarId ||
@@ -102,7 +155,7 @@ export function resolvePermanentLinkSource(
   cpSync(resolvedRoot, destDir, {
     recursive: true,
     filter: (src) => {
-      const rel = src.slice(resolvedRoot.length).replace(/\\/g, '/');
+      const rel = pathFromRoot(resolvedRoot, src);
       if (!rel) return true;
       if (/^\/\.git(\/|$)/.test(rel)) return false;
       if (/^\/node_modules(\/|$)/.test(rel)) {
@@ -170,20 +223,34 @@ export async function runSidecarSetup({
   const cliArgs = new Set(args);
   const isUninstall = cliArgs.has('--uninstall');
   const skipTests = cliArgs.has('--skip-tests');
+  const force = cliArgs.has('--force');
 
   console.log(`[${sidecarId}] Repository root: ${resolvedRepoRoot}`);
 
   if (isUninstall) {
-    const isInPlaceCheckout =
-      existsSync(junctionPath) &&
-      realpathSync(junctionPath) === resolvedRepoRoot &&
-      !lstatSync(junctionPath).isSymbolicLink();
-    if (isInPlaceCheckout) {
+    if (isRealDirectory(junctionPath) && realpathSync(junctionPath) === resolvedRepoRoot) {
       console.log(`[${sidecarId}] Preserving in-place repository directory at ${junctionPath}.`);
+    } else if (isRealDirectory(junctionPath) && !force) {
+      console.log(
+        `[${sidecarId}] Not removing ${junctionPath}: it is a real directory, not a link (re-run with --force to delete it).`
+      );
     } else {
       removeLinkOrDir(junctionPath);
     }
 
+    // Prune permanent copies made by earlier npx installs, but never the directory we are running from
+    const entries = existsSync(packagesDir) ? readdirSync(packagesDir) : [];
+    for (const entry of entries) {
+      if (!entry.startsWith(`${sidecarId}@`)) continue;
+      const entryPath = join(packagesDir, entry);
+      try {
+        if (realpathSync(entryPath) === resolvedRepoRoot) continue;
+      } catch {
+        // dangling entry; safe to remove
+      }
+      removeLinkOrDir(entryPath);
+    }
+
     if (typeof onUninstall === 'function') {
       await onUninstall({
         sidecarId,
@@ -207,6 +274,9 @@ export async function runSidecarSetup({
     }
   }
 
+  // Fail before running hooks, tests, or the npx copy if we would have to delete a real checkout
+  assertNotInPlaceCheckout(junctionPath, resolvedRepoRoot, force);
+
   if (typeof onBeforeSetup === 'function') {
     await onBeforeSetup({
       sidecarId,
@@ -231,7 +301,7 @@ export async function runSidecarSetup({
     version,
     packagesDir,
   });
-  createSidecarLink(targetSourceDir, junctionPath);
+  createSidecarLink(targetSourceDir, junctionPath, { force });
   console.log(`[${sidecarId}] Linked ${junctionPath} -> ${realpathSync(junctionPath)}`);
 
   updateAgySidecarConfig(sidecarId, true, configJsonPath, { createIfMissing: true });
@@ -246,7 +316,7 @@ export async function runSidecarSetup({
     );
   }
   if (!rpcRes.notified) {
-    const killed = killSidecarProcessByPortOrPid(sidecarId, rpcOptions);
+    const killed = killSidecarProcessByPortOrPid(sidecarId, { execFn, ...rpcOptions });
     if (killed.restarted) {
       rpcRes = { notified: true, viaProcessRestart: killed.method };
     }

package/lib/workspace.mjs

@@ -10,10 +10,19 @@ export function normalizeWorkspacePath(uriOrPath = '', { lowercase = false } = {
   } catch {
     // Keep original string if percent-decoding fails
   }
-  clean = clean
-    .replace(/^file:\/\/\/?/i, '')
-    .replace(/\\/g, '/')
-    .replace(/\/+$/, '');
+  clean = clean.replace(/\\/g, '/');
+  if (/^file:\/\//i.test(clean)) {
+    clean = clean.slice('file://'.length);
+    if (/^\/[A-Za-z]:/.test(clean)) {
+      // file:///c:/x -> c:/x
+      clean = clean.slice(1);
+    } else if (clean && !clean.startsWith('/')) {
+      // file://server/share -> //server/share (UNC)
+      clean = `//${clean}`;
+    }
+    // otherwise file:///home/x -> /home/x
+  }
+  clean = clean.replace(/(.)\/+$/, '$1');
 
   // Normalize Windows drive letter casing (e.g. C:/Projects -> c:/Projects)
   if (/^[A-Za-z]:/.test(clean)) {
@@ -33,7 +42,10 @@ function globToRegExp(pattern = '') {
   if (!normalizedPattern || normalizedPattern === '*') {
     return /^.*$/;
   }
-  const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  const escaped = normalizedPattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
   return new RegExp(`^${escaped}$`, 'i');
 }
 
@@ -55,7 +67,7 @@ export function matchesWorkspaceRule(activeWorkspacePath = '', patterns = []) {
     if (activeNorm === normPat || activeNorm.startsWith(`${normPat}/`)) {
       return true;
     }
-    if (trimmed.includes('*') && globToRegExp(trimmed).test(activeNorm)) {
+    if (/[*?]/.test(trimmed) && globToRegExp(trimmed).test(activeNorm)) {
       return true;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-sidecar-kit",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "Zero-dependency SDK and CLI scaffolder for Google Antigravity Auxiliary Pane sidecars (Connect RPC client, host theme & Tailwind proxy, BOM-safe config store, workspace URI matcher, and npx-safe installer).",
   "license": "MIT",
@@ -19,7 +19,6 @@
   "files": [
     "bin",
     "lib",
-    "test",
     "README.md",
     "LICENSE"
   ],
@@ -30,11 +29,14 @@
     "./theme": "./lib/theme.mjs",
     "./setup": "./lib/setup.mjs",
     "./server": "./lib/server.mjs",
-    "./workspace": "./lib/workspace.mjs"
+    "./workspace": "./lib/workspace.mjs",
+    "./scaffolder": "./lib/scaffolder.mjs",
+    "./cli": "./bin/cli.mjs"
   },
   "bin": {
-    "create-antigravity-sidecar": "./bin/cli.mjs",
-    "agy-sidecar-kit": "./bin/cli.mjs"
+    "antigravity-sidecar-kit": "bin/cli.mjs",
+    "create-antigravity-sidecar": "bin/cli.mjs",
+    "agy-sidecar-kit": "bin/cli.mjs"
   },
   "keywords": [
     "antigravity",
@@ -50,6 +52,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test",
+    "test:pack": "node scripts/pack-smoke.mjs && node scripts/pack-smoke-create.mjs"
   }
 }

package/test/config.test.mjs

@@ -1,66 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  readJsonSafe,
-  readJsonFile,
-  writeJsonNoBom,
-  updateAgySidecarConfig,
-} from '../lib/config.mjs';
-
-describe('antigravity-sidecar-kit/config BOM-safe JSON helpers and config.json updater', () => {
-  it('strips UTF-8 BOM on read, writes without BOM, and supports strict mode', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-config-test-'));
-    try {
-      const p = join(dir, 'bom.json');
-      writeFileSync(p, '\uFEFF{"hello":"world"}\n', 'utf8');
-      assert.deepEqual(readJsonSafe(p, {}), { hello: 'world' });
-
-      const outPath = join(dir, 'nested', 'out.json');
-      writeJsonNoBom(outPath, { a: 1 });
-      const rawBytes = readFileSync(outPath);
-      assert.notEqual(rawBytes[0], 0xef);
-      assert.deepEqual(readJsonFile(outPath), { a: 1 });
-
-      const badPath = join(dir, 'bad.json');
-      writeFileSync(badPath, '{ truncated', 'utf8');
-      assert.deepEqual(readJsonSafe(badPath, { fallback: true }), { fallback: true });
-      assert.throws(() => readJsonFile(badPath, { strict: true }));
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('updateAgySidecarConfig preserves projectId and never clobbers malformed config.json', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-agy-cfg-test-'));
-    try {
-      const cfgPath = join(dir, 'config.json');
-      writeJsonNoBom(cfgPath, {
-        userSettings: { themeMode: 'THEME_MODE_DARK' },
-        sidecars: {
-          hangar: {
-            enabled: false,
-            projectId: 'preserve-uuid-999',
-          },
-        },
-      });
-
-      const ok = updateAgySidecarConfig('hangar', true, cfgPath);
-      assert.equal(ok, true);
-      const updated = readJsonSafe(cfgPath, {});
-      assert.equal(updated.sidecars.hangar.enabled, true);
-      assert.equal(updated.sidecars.hangar.projectId, 'preserve-uuid-999');
-
-      // Malformed config.json must never be overwritten
-      const corruptContent = '{ "sidecars": { "hangar": ';
-      writeFileSync(cfgPath, corruptContent, 'utf8');
-      const okCorrupt = updateAgySidecarConfig('hangar', false, cfgPath);
-      assert.equal(okCorrupt, false);
-      assert.equal(readFileSync(cfgPath, 'utf8'), corruptContent);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});

package/test/rpc.test.mjs

@@ -1,124 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  callLsRpc,
-  getLsConfig,
-  persistSidecarRuntime,
-  killSidecarProcessByPortOrPid,
-  getSidecars,
-  manageSidecar,
-  getAllTrajectories,
-  getUserStatus,
-} from '../lib/rpc.mjs';
-
-describe('antigravity-sidecar-kit/rpc client, credential cache, and process restarter', () => {
-  it('persists and reads runtime.json credentials when env vars are absent', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-rpc-cache-'));
-    try {
-      const saved = persistSidecarRuntime('hangar', {
-        sidecarDataRoot: dir,
-        env: {
-          ANTIGRAVITY_SIDECAR_WEB_PORT: '51234',
-          ANTIGRAVITY_LS_ADDRESS: '127.0.0.1:59999',
-          ANTIGRAVITY_CSRF_TOKEN: 'cached-token-abc',
-        },
-      });
-      assert.equal(saved, true);
-
-      const cfg = getLsConfig({ sidecarDataRoot: dir, env: {} });
-      assert.equal(cfg.lsAddress, '127.0.0.1:59999');
-      assert.equal(cfg.csrfToken, 'cached-token-abc');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('killSidecarProcessByPortOrPid terminates by runtime.json PID first, then falls back to log port', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-rpc-kill-'));
-    try {
-      const dataDir = join(dir, 'demo-sc', 'data');
-      const logsDir = join(dir, 'demo-sc', 'logs');
-      mkdirSync(dataDir, { recursive: true });
-      mkdirSync(logsDir, { recursive: true });
-      writeFileSync(join(dataDir, 'runtime.json'), JSON.stringify({ pid: 999999, webPort: 0 }), 'utf8');
-
-      const killedPids = [];
-      const res1 = killSidecarProcessByPortOrPid('demo-sc', {
-        sidecarDataRoot: dir,
-        killFn: (pid, sig) => killedPids.push({ pid, sig }),
-      });
-      assert.equal(res1.restarted, true);
-      assert.equal(res1.method, 'pid:999999');
-      assert.deepEqual(killedPids, [{ pid: 999999, sig: 'SIGTERM' }]);
-
-      // Fallback when runtime.json PID is dead and port is parsed from sidecar.log
-      writeFileSync(
-        join(logsDir, 'sidecar.log'),
-        '[sidecar] listening on 127.0.0.1:61111\n[sidecar] listening on 127.0.0.1:62222\n',
-        'utf8'
-      );
-      const portKilled = [];
-      const res2 = killSidecarProcessByPortOrPid('demo-sc', {
-        sidecarDataRoot: dir,
-        killFn: (pid) => {
-          if (pid === 999999) throw new Error('ESRCH');
-          portKilled.push(pid);
-        },
-        execFn: () => '888888\n',
-      });
-      assert.equal(res2.restarted, true);
-      assert.equal(res2.method, 'port:62222->pid:888888');
-      assert.deepEqual(portKilled, [888888]);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('callLsRpc and convenience wrappers send CSRF header and handle HTTP errors', async () => {
-    const calls = [];
-    const mockFetch = async (url, init) => {
-      calls.push({ url, init });
-      return {
-        ok: true,
-        status: 200,
-        text: async () => JSON.stringify({ ok: true }),
-      };
-    };
-    const opts = { lsAddress: '127.0.0.1:50000', csrfToken: 'tok-1', fetchFn: mockFetch };
-
-    await getSidecars(opts);
-    await manageSidecar('context-monitor', 'SIDECAR_ACTION_RESTART', opts);
-    await getAllTrajectories(opts);
-    await getUserStatus(opts);
-
-    assert.equal(calls.length, 4);
-    assert.ok(calls[0].url.endsWith('/GetSidecars'));
-    assert.ok(calls[1].url.endsWith('/ManageSidecar'));
-    assert.equal(calls[1].init.headers['x-codeium-csrf-token'], 'tok-1');
-    assert.deepEqual(JSON.parse(calls[1].init.body), {
-      action: 'SIDECAR_ACTION_RESTART',
-      sidecarId: 'context-monitor',
-    });
-
-    await assert.rejects(
-      () =>
-        callLsRpc(
-          'GetSidecars',
-          {},
-          {
-            lsAddress: '127.0.0.1:50000',
-            csrfToken: 'tok-1',
-            fetchFn: async () => ({
-              ok: false,
-              status: 500,
-              text: async () => JSON.stringify({ message: 'internal failure' }),
-            }),
-          }
-        ),
-      /LanguageServerService\/GetSidecars failed: internal failure/
-    );
-  });
-});

package/test/setup-server.test.mjs

@@ -1,143 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { readJsonSafe, writeJsonNoBom } from '../lib/config.mjs';
-import { resolvePermanentLinkSource, runSidecarSetup } from '../lib/setup.mjs';
-import { createAssetHandler, createAgyCssHandler } from '../lib/server.mjs';
-import { scaffoldSidecarProject } from '../lib/scaffolder.mjs';
-
-describe('antigravity-sidecar-kit/setup, /server, and CLI scaffolder', () => {
-  it('resolvePermanentLinkSource copies out of _npx and guarantees node_modules/antigravity-sidecar-kit in both nested and hoisted layouts', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-npx-test-'));
-    try {
-      const packagesDir = join(dir, 'packages');
-
-      // Case 1: Hoisted _npx layout (no nested node_modules inside repoRoot)
-      const hoistedRepo = join(dir, '_npx', 'hash123', 'node_modules', 'antigravity-demo');
-      mkdirSync(join(hoistedRepo, '.git'), { recursive: true });
-      writeJsonNoBom(join(hoistedRepo, 'package.json'), {
-        name: 'antigravity-demo',
-        version: '1.2.3',
-      });
-      writeFileSync(join(hoistedRepo, 'server.mjs'), '// server', 'utf8');
-      writeFileSync(join(hoistedRepo, '.git', 'HEAD'), 'ref: refs/heads/main', 'utf8');
-
-      const copiedHoisted = resolvePermanentLinkSource(hoistedRepo, {
-        sidecarId: 'demo',
-        packagesDir,
-      });
-      assert.ok(copiedHoisted.endsWith('demo@1.2.3'));
-      assert.equal(existsSync(join(copiedHoisted, '.git')), false);
-      assert.equal(existsSync(join(copiedHoisted, 'server.mjs')), true);
-      assert.equal(
-        existsSync(join(copiedHoisted, 'node_modules', 'antigravity-sidecar-kit', 'package.json')),
-        true,
-        'Should inject KIT_ROOT into destDir/node_modules/antigravity-sidecar-kit when hoisted'
-      );
-
-      // Case 2: Nested node_modules with both antigravity-sidecar-kit and an extraneous package
-      const nestedRepo = join(dir, '_npx', 'hash456', 'node_modules', 'antigravity-nested');
-      mkdirSync(join(nestedRepo, 'node_modules', 'antigravity-sidecar-kit', 'lib'), { recursive: true });
-      mkdirSync(join(nestedRepo, 'node_modules', 'other-bloat-pkg'), { recursive: true });
-      writeJsonNoBom(join(nestedRepo, 'package.json'), { name: 'antigravity-nested', version: '2.0.0' });
-      writeJsonNoBom(join(nestedRepo, 'node_modules', 'antigravity-sidecar-kit', 'package.json'), {
-        name: 'antigravity-sidecar-kit',
-        version: '1.0.0',
-      });
-      writeFileSync(join(nestedRepo, 'node_modules', 'other-bloat-pkg', 'index.js'), '', 'utf8');
-
-      const copiedNested = resolvePermanentLinkSource(nestedRepo, {
-        sidecarId: 'nested',
-        packagesDir,
-      });
-      assert.equal(
-        existsSync(join(copiedNested, 'node_modules', 'antigravity-sidecar-kit', 'package.json')),
-        true
-      );
-      assert.equal(existsSync(join(copiedNested, 'node_modules', 'other-bloat-pkg')), false);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('runSidecarSetup links sidecar, preserves projectId on enable/uninstall, and scaffolds projects cleanly', async () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-setup-flow-'));
-    try {
-      const scaffoldDir = join(dir, 'my-custom-tool');
-      const sc = scaffoldSidecarProject({ name: 'my-custom-tool', targetDir: scaffoldDir });
-      assert.equal(sc.id, 'my-custom-tool');
-      assert.equal(existsSync(join(scaffoldDir, 'sidecar.json')), true);
-      assert.equal(existsSync(join(scaffoldDir, 'hub-manifest.json')), true);
-
-      const globalSidecarsDir = join(dir, 'sidecars');
-      const configJsonPath = join(dir, 'config.json');
-      writeJsonNoBom(configJsonPath, {
-        sidecars: {
-          'my-custom-tool': {
-            enabled: false,
-            projectId: 'keep-this-project-id',
-          },
-        },
-      });
-
-      const setupRes = await runSidecarSetup({
-        sidecarId: 'my-custom-tool',
-        repoRoot: scaffoldDir,
-        args: ['--skip-tests'],
-        globalSidecarsDir,
-        configJsonPath,
-        rpcOptions: { lsAddress: '', csrfToken: '' },
-        restartDelayMs: 0,
-      });
-      assert.equal(setupRes.uninstalled, false);
-      assert.equal(existsSync(join(globalSidecarsDir, 'my-custom-tool', 'sidecar.json')), true);
-
-      const cfgAfterSetup = readJsonSafe(configJsonPath, {});
-      assert.equal(cfgAfterSetup.sidecars['my-custom-tool'].enabled, true);
-      assert.equal(cfgAfterSetup.sidecars['my-custom-tool'].projectId, 'keep-this-project-id');
-
-      const uninstRes = await runSidecarSetup({
-        sidecarId: 'my-custom-tool',
-        repoRoot: scaffoldDir,
-        args: ['--uninstall'],
-        globalSidecarsDir,
-        configJsonPath,
-        rpcOptions: { lsAddress: '', csrfToken: '' },
-      });
-      assert.equal(uninstRes.uninstalled, true);
-      assert.equal(existsSync(join(globalSidecarsDir, 'my-custom-tool')), false);
-      const cfgAfterUninst = readJsonSafe(configJsonPath, {});
-      assert.equal(cfgAfterUninst.sidecars['my-custom-tool'].enabled, false);
-      assert.equal(cfgAfterUninst.sidecars['my-custom-tool'].projectId, 'keep-this-project-id');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('createAssetHandler injects UI token into local HTML asset links and createAgyCssHandler serves CSS', async () => {
-    const dir = mkdtempSync(join(tmpdir(), 'kit-server-test-'));
-    try {
-      writeFileSync(
-        join(dir, 'index.html'),
-        '<link rel="stylesheet" href="/styles.css"><script src="/app.js"></script>',
-        'utf8'
-      );
-      const handler = createAssetHandler(dir, 'index.html', 'text/html; charset=utf-8', {
-        uiToken: 'sec-123',
-        bootTs: 999,
-      });
-      const res = handler();
-      assert.equal(res.contentType, 'text/html; charset=utf-8');
-      assert.match(res.body, /href="\/styles\.css\?token=sec-123&v=999"/);
-      assert.match(res.body, /src="\/app\.js\?token=sec-123&v=999"/);
-
-      const cssHandler = createAgyCssHandler({ lsAddress: '' });
-      const cssRes = await cssHandler();
-      assert.equal(cssRes.contentType, 'text/css; charset=utf-8');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});

package/test/theme.test.mjs

@@ -1,66 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { writeJsonNoBom } from '../lib/config.mjs';
-import { fetchHostStylesheet, resolveHostTheme } from '../lib/theme.mjs';
-
-describe('antigravity-sidecar-kit/theme unified resolver and stylesheet proxy', () => {
-  it('resolves both Hangar cssVariables and Context Monitor vars across dark, light, and high-contrast modes', () => {
-    const darkDefault = resolveHostTheme({ themeMode: 2 });
-    assert.equal(darkDefault.mode, 'dark');
-    assert.equal(darkDefault.themeType, 'dark');
-    assert.equal(darkDefault.contrast, 'normal');
-    assert.equal(darkDefault.vars['--cm-bg'], '#181818');
-    assert.equal(darkDefault.vars['--cm-text'], '#ffffff');
-    assert.equal(darkDefault.vars['--cm-card'], 'color-mix(in srgb, #ffffff 5%, #181818)');
-    assert.equal(darkDefault.vars['--cm-border'], 'color-mix(in srgb, #ffffff 5%, transparent)');
-    assert.equal(darkDefault.vars['--cm-hover'], 'rgba(255, 255, 255, 0.05)');
-    assert.equal(darkDefault.cssVariables['--background'], '#181818');
-
-    const dir = mkdtempSync(join(tmpdir(), 'kit-theme-test-'));
-    try {
-      const agyCfgPath = join(dir, 'config.json');
-      const appStoragePath = join(dir, 'app_storage.json');
-      writeJsonNoBom(agyCfgPath, {
-        userSettings: {
-          themeMode: 'THEME_MODE_LIGHT',
-          customThemeSeedsLight: { background: '#FAFAFA', primary: '#10b981' },
-        },
-      });
-      writeJsonNoBom(appStoragePath, { 'jetski.contrast': '2' });
-      const resolved = resolveHostTheme(agyCfgPath, appStoragePath);
-      assert.equal(resolved.themeType, 'light');
-      assert.equal(resolved.mode, 'light');
-      assert.equal(resolved.contrast, 'high');
-      assert.equal(resolved.cssVariables['--background'], '#FAFAFA');
-      assert.equal(resolved.cssVariables['--primary'], '#10b981');
-      assert.equal(resolved.cssVariables['--border'], 'rgba(0, 0, 0, 0.12)');
-      assert.equal(resolved.vars['--cm-bg'], '#FAFAFA');
-      assert.equal(resolved.vars['--cm-accent'], '#10b981');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('fetchHostStylesheet discovers renamed CSS links, rejects SPA HTML catch-all, and wraps in @layer agy-host', async () => {
-    const css = await fetchHostStylesheet({
-      lsAddress: '127.0.0.1:59125',
-      fetchFn: async (u) =>
-        u.endsWith('/')
-          ? {
-              ok: true,
-              headers: new Map([['content-type', 'text/html']]),
-              text: async () => '<link rel="stylesheet" href="/app-hash.css">',
-            }
-          : {
-              ok: true,
-              headers: new Map([['content-type', 'text/css']]),
-              text: async () => ':root{--radius-sm:4px}@property --tw-x { syntax: "*"; }',
-            },
-      forceRefresh: true,
-    });
-    assert.match(css, /^@layer agy-host \{[\s\S]*--radius-sm:4px[\s\S]*\}\n@property --tw-x/);
-  });
-});

package/test/workspace.test.mjs

@@ -1,44 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import {
-  normalizeWorkspacePath,
-  extractWorkspaceName,
-  matchesWorkspaceRule,
-  resolveActiveWorkspace,
-} from '../lib/workspace.mjs';
-
-describe('antigravity-sidecar-kit/workspace normalization and glob matching', () => {
-  it('normalizes percent-encoded Windows file:// URIs, supports lowercase flag, and matches rules', () => {
-    assert.equal(normalizeWorkspacePath('file:///c%3A/Projects/App/'), 'c:/Projects/App');
-    assert.equal(
-      normalizeWorkspacePath('file:///C:/Users/dev/Repo', { lowercase: true }),
-      'c:/users/dev/repo'
-    );
-    assert.equal(extractWorkspaceName('c:/Projects/services'), 'services');
-
-    assert.equal(matchesWorkspaceRule('c:/Projects/App', ['*']), true);
-    assert.equal(matchesWorkspaceRule('c:/Projects/App/packages/api', ['c:/Projects/App']), true);
-    assert.equal(matchesWorkspaceRule('c:/Users/dev/backend-api', ['*backend*']), true);
-    assert.equal(matchesWorkspaceRule('c:/Users/dev/frontend', ['c:/Projects/App']), false);
-  });
-
-  it('resolves active workspace from trajectories sorted by lastUserViewTime', () => {
-    const resolved = resolveActiveWorkspace({
-      trajectoriesResponse: {
-        trajectorySummaries: {
-          'conv-1': {
-            annotations: { lastUserViewTime: '2026-10-17T05:00:00Z' },
-            workspaces: [{ workspaceFolderAbsoluteUri: 'file:///c:/Old' }],
-          },
-          'conv-2': {
-            annotations: { lastUserViewTime: '2026-10-17T08:00:00Z' },
-            workspaces: [{ workspaceFolderAbsoluteUri: 'file:///c%3A/Projects/Current' }],
-          },
-        },
-      },
-    });
-    assert.equal(resolved.workspacePath, 'c:/Projects/Current');
-    assert.equal(resolved.workspaceName, 'Current');
-    assert.equal(resolved.conversationId, 'conv-2');
-  });
-});