copillm 0.2.5 → 0.2.7

package/dist/cli/launchAgent.js

@@ -1,10 +1,14 @@
-import { spawn } from "node:child_process";
 import { resolveAgent } from "./resolveAgent.js";
+import { spawnAgent } from "./windowsSpawn.js";
 export async function launchAgent(opts) {
     const log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
     let resolved;
     try {
-        resolved = await resolveAgent(opts.agent, { pinnedSpec: opts.pinnedSpec, log });
+        resolved = await resolveAgent(opts.agent, {
+            pinnedSpec: opts.pinnedSpec,
+            preferPath: useSystemAgentOptIn(),
+            log
+        });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -14,11 +18,9 @@ export async function launchAgent(opts) {
     }
     log(resolved.displayLine);
     const childEnv = { ...process.env, ...opts.env };
-    const useShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(resolved.binPath);
-    const child = spawn(resolved.binPath, opts.args, {
+    const child = spawnAgent(resolved.binPath, opts.args, {
         stdio: "inherit",
-        env: childEnv,
-        shell: useShell
+        env: childEnv
     });
     return new Promise((resolve, reject) => {
         child.once("error", reject);
@@ -65,3 +67,17 @@ function installHint(agent) {
         "    npm i -g @anthropic-ai/claude-code"
     ].join("\n");
 }
+/**
+ * Whether the user has opted in to letting copillm fall back to a system-installed
+ * coding-agent binary on PATH. Off by default — copillm uses its own cache and
+ * downloads on demand so the executed version is deterministic.
+ *
+ * Opt in by setting `COPILLM_USE_SYSTEM_AGENT` to `1`, `true`, or `yes`
+ * (case-insensitive).
+ */
+function useSystemAgentOptIn() {
+    const raw = process.env.COPILLM_USE_SYSTEM_AGENT;
+    if (!raw)
+        return false;
+    return /^(1|true|yes)$/i.test(raw.trim());
+}

package/dist/cli/packageInfo.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 const FALLBACK_PACKAGE_INFO = {
     name: "copillm",
-    version: "0.2.5"
+    version: "0.2.7"
 };
 export function getPackageInfo() {
     const envName = cleanPackageValue(process.env.COPILLM_PACKAGE_NAME);

package/dist/cli/resolveAgent.js

@@ -39,8 +39,12 @@ export async function resolveAgent(agent, opts = {}) {
     const pkg = pin.packageName;
     const binName = AGENT_REGISTRY[agent].binName;
     const agentRoot = path.join(cacheRoot, agent);
-    // 1. PATH lookup (skipped when user pinned a specific version)
-    if (!pin.version && opts.preferPath !== false) {
+    // 1. PATH lookup (opt-in only).
+    // PATH lookup is OFF by default so the running agent version is always the one copillm
+    // manages in its cache. Users who want to fall back to a system-installed binary can opt
+    // in via the COPILLM_USE_SYSTEM_AGENT env var (wired in launchAgent.ts) or by passing
+    // `preferPath: true` directly. Pinned versions always skip this branch.
+    if (!pin.version && opts.preferPath === true) {
         const found = findOnPath(binName);
         if (found) {
             const v = probeVersion(found) ?? "unknown";
@@ -55,16 +59,25 @@ export async function resolveAgent(agent, opts = {}) {
             };
         }
     }
-    // 2. Determine target version
+    // 2. Determine target version. If we can reach npm we ask for `latest`;
+    // otherwise we fall through to whatever's already cached so the user can
+    // keep working when the registry is unreachable (corp proxy, npm outage,
+    // airplane mode, etc.).
     let target = pin.version;
+    let viewError = null;
     if (!target && !opts.offline) {
-        target = npmViewLatest(npmExe, pkg);
+        try {
+            target = npmViewLatest(npmExe, pkg);
+        }
+        catch (err) {
+            viewError = err instanceof Error ? err : new Error(String(err));
+        }
     }
     // 3. Cache lookup
     if (target) {
         const cachedDir = path.join(agentRoot, target);
-        const cachedBin = binPathInPrefix(cachedDir, binName);
-        if (cachedBin && fs.existsSync(cachedBin)) {
+        const cachedBin = findReadyCachedBin(cachedDir, binName);
+        if (cachedBin) {
             return {
                 source: "cache",
                 binPath: cachedBin,
@@ -77,8 +90,13 @@ export async function resolveAgent(agent, opts = {}) {
         }
     }
     else {
+        // Either --offline or we couldn't reach npm to ask "what's latest?".
+        // Use the newest known-good install on disk.
         const last = pickLastCached(agentRoot, binName);
         if (last) {
+            if (viewError) {
+                log(`\u26a0 could not reach npm registry to check for updates (${viewError.message}); using cached ${binName} v${last.version}`);
+            }
             return {
                 source: "cache",
                 binPath: last.binPath,
@@ -89,12 +107,22 @@ export async function resolveAgent(agent, opts = {}) {
                 displayLine: `\u2192 ${binName} (cached fallback, ${displayPath(last.dir)}, v${last.version})`
             };
         }
+        if (viewError) {
+            throw new Error(`${binName} not installed and could not reach npm registry to download it: ${viewError.message}`);
+        }
         throw new Error(`${binName} not installed and no cache available (offline).`);
     }
     if (opts.offline) {
         throw new Error(`${binName}@${target} not in cache and --offline is set.`);
     }
-    // 4. Install
+    // 4. Install. We install *directly* into the canonical version directory
+    // and write `version.txt` LAST as the "install complete" marker.
+    // findReadyCachedBin requires both the bin and the marker, so any crash
+    // before the marker is written leaves the tree visible as incomplete and
+    // the next run cleans it up + re-installs. Avoids the older staging+rename
+    // pattern, which had to retry rename-of-directory on Windows when AV or
+    // npm post-install workers transiently held handles on freshly-written
+    // files.
     log(`\u2192 ${binName} (installing ${pkg}@${target} into ${displayPath(agentRoot)} \u2026)`);
     fs.mkdirSync(agentRoot, { recursive: true });
     const lockFile = path.join(agentRoot, ".lock");
@@ -102,8 +130,8 @@ export async function resolveAgent(agent, opts = {}) {
     try {
         // Re-check after acquiring lock — another invocation may have just installed it.
         const finalDir = path.join(agentRoot, target);
-        const recheckBin = binPathInPrefix(finalDir, binName);
-        if (recheckBin && fs.existsSync(recheckBin)) {
+        const recheckBin = findReadyCachedBin(finalDir, binName);
+        if (recheckBin) {
             return {
                 source: "cache",
                 binPath: recheckBin,
@@ -114,40 +142,37 @@ export async function resolveAgent(agent, opts = {}) {
                 displayLine: `\u2192 ${binName} (cached, ${displayPath(finalDir)}, v${target})`
             };
         }
-        const stagingDir = path.join(agentRoot, `.staging-${sanitize(target)}-${process.pid}`);
-        if (fs.existsSync(stagingDir)) {
-            fs.rmSync(stagingDir, { recursive: true, force: true });
+        // Wipe any partial state (missing marker means a previous attempt was
+        // interrupted) before we re-run npm into the same prefix.
+        if (fs.existsSync(finalDir)) {
+            fs.rmSync(finalDir, { recursive: true, force: true });
         }
-        fs.mkdirSync(stagingDir, { recursive: true });
+        fs.mkdirSync(finalDir, { recursive: true });
         const spec = `${pkg}@${target}`;
-        const installResult = spawnSync(npmExe, ["install", "--prefix", stagingDir, "--no-audit", "--no-fund", "--omit=dev", spec], {
+        const installResult = spawnSync(npmExe, ["install", "--prefix", finalDir, "--no-audit", "--no-fund", "--omit=dev", spec], {
             stdio: ["ignore", "inherit", "inherit"],
             shell: process.platform === "win32"
         });
         if (installResult.status !== 0) {
+            cleanupFailedInstall(finalDir);
             const msg = installResult.error ? `: ${installResult.error.message}` : "";
             throw new Error(`npm install ${spec} failed (exit ${installResult.status})${msg}`);
         }
-        const stagedBin = binPathInPrefix(stagingDir, binName);
-        if (!stagedBin || !fs.existsSync(stagedBin)) {
-            throw new Error(`Installed package did not produce a ${binName} bin at ${stagingDir}`);
-        }
-        if (probeVersion(stagedBin) === null) {
-            throw new Error(`Smoke test failed: ${stagedBin} --version did not exit 0`);
+        const installedBin = binPathInPrefix(finalDir, binName);
+        if (!installedBin || !fs.existsSync(installedBin)) {
+            cleanupFailedInstall(finalDir);
+            throw new Error(`Installed package did not produce a ${binName} bin at ${finalDir}`);
         }
-        if (fs.existsSync(finalDir)) {
-            fs.rmSync(finalDir, { recursive: true, force: true });
+        if (probeVersion(installedBin) === null) {
+            cleanupFailedInstall(finalDir);
+            throw new Error(`Smoke test failed: ${installedBin} --version did not exit 0`);
         }
-        fs.renameSync(stagingDir, finalDir);
+        // Marker file: MUST be the last write. Cache-hit checks key off this.
         fs.writeFileSync(path.join(finalDir, "version.txt"), `${target}\n`);
         const pruned = pruneSiblings(agentRoot, target);
-        const finalBin = binPathInPrefix(finalDir, binName);
-        if (!finalBin) {
-            throw new Error(`Final install missing bin at ${finalDir}`);
-        }
         return {
             source: "installed",
-            binPath: finalBin,
+            binPath: installedBin,
             version: target,
             packageName: pkg,
             cacheDir: finalDir,
@@ -159,6 +184,26 @@ export async function resolveAgent(agent, opts = {}) {
         releaseFileLock(lockFile);
     }
 }
+function cleanupFailedInstall(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort: a stuck handle here means the next run will retry the
+        // cleanup before reinstalling. Worst case the user gets a clearer
+        // "rmSync failed" error on the next attempt.
+    }
+}
+function findReadyCachedBin(dir, binName) {
+    const bin = binPathInPrefix(dir, binName);
+    if (!bin || !fs.existsSync(bin))
+        return null;
+    // version.txt is written LAST, after the smoke test passes. Missing
+    // marker = partial/aborted install; do not treat as a cache hit.
+    if (!fs.existsSync(path.join(dir, "version.txt")))
+        return null;
+    return bin;
+}
 function defaultNpmExecutable() {
     return process.env.COPILLM_NPM_EXECUTABLE && process.env.COPILLM_NPM_EXECUTABLE.trim().length > 0
         ? process.env.COPILLM_NPM_EXECUTABLE
@@ -241,7 +286,7 @@ function pickLastCached(agentRoot, binName) {
         .sort((a, b) => compareVersionsDescending(a, b));
     for (const v of versions) {
         const dir = path.join(agentRoot, v);
-        const bin = binPathInPrefix(dir, binName);
+        const bin = findReadyCachedBin(dir, binName);
         if (bin)
             return { dir, binPath: bin, version: v };
     }
@@ -347,6 +392,3 @@ function displayPath(p) {
     }
     return p;
 }
-function sanitize(s) {
-    return s.replace(/[^A-Za-z0-9._-]/g, "_");
-}

package/dist/cli/windowsSpawn.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+const META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+function escapeArgument(arg, doubleEscapeMetaChars) {
+    let escaped = `${arg}`;
+    escaped = escaped.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    escaped = escaped.replace(/(?=(\\+?)?)\1$/, "$1$1");
+    escaped = `"${escaped}"`;
+    escaped = escaped.replace(META_CHARS, "^$1");
+    if (doubleEscapeMetaChars) {
+        escaped = escaped.replace(META_CHARS, "^$1");
+    }
+    return escaped;
+}
+function escapeCommand(command) {
+    return command.replace(META_CHARS, "^$1");
+}
+/**
+ * Build the `cmd.exe /d /s /c "..."` invocation we need to run a `.cmd` /
+ * `.bat` file safely on Windows.
+ *
+ * Background: Node's `child_process.spawn` cannot directly exec a batch file
+ * (CreateProcess only understands real PE binaries), and `shell: true` is now
+ * deprecated when combined with an args array because Node performs no
+ * escaping (see Node DEP0190). The accepted alternative — long used by
+ * cross-spawn and npm's own bin shims — is to spawn `cmd.exe` ourselves,
+ * pre-quote the command line, and set `windowsVerbatimArguments: true` so
+ * Node hands the buffer to Windows untouched.
+ *
+ * The quoting follows the well-known two-layer algorithm:
+ *   1. Apply Microsoft's CommandLineToArgvW rules (backslash/quote dance) so
+ *      that the underlying program parses each argument back into the values
+ *      we passed in.
+ *   2. Escape cmd.exe metacharacters (`^ & | < > ( ) % ! ;` etc.) with `^` so
+ *      they don't get interpreted by the shell before the program sees them.
+ *
+ * `doubleEscape` is needed when the target is an npm-generated `.cmd` shim
+ * (which itself spawns a nested cmd.exe via `CALL` on older npm versions, or
+ * via subshell composition); each cmd.exe parse strips one layer of `^`, so
+ * we apply it twice to survive the round trip. We default to true for
+ * `.cmd`/`.bat` because every agent we launch is installed via npm.
+ */
+export function buildWindowsCmdInvocation(file, args, doubleEscape = true) {
+    const escapedCommand = escapeCommand(file);
+    const escapedArgs = args.map((a) => escapeArgument(a, doubleEscape));
+    const commandLine = [escapedCommand, ...escapedArgs].join(" ");
+    const comspec = process.env.ComSpec || process.env.comspec || "cmd.exe";
+    return {
+        command: comspec,
+        args: ["/d", "/s", "/c", `"${commandLine}"`]
+    };
+}
+/**
+ * Spawn a child process, transparently routing `.cmd` / `.bat` files through
+ * `cmd.exe` with safe quoting on Windows. Non-Windows platforms and real
+ * `.exe` / `.com` binaries go through a direct `spawn` with no shell flag.
+ *
+ * Mirrors the surface of `child_process.spawn(file, args, options)` but
+ * never sets `shell: true` and therefore never triggers Node's DEP0190
+ * deprecation warning.
+ */
+export function spawnAgent(file, args, options) {
+    if (process.platform !== "win32" || !/\.(cmd|bat)$/i.test(file)) {
+        return spawn(file, args, { ...options, shell: false });
+    }
+    const { command, args: cmdArgs } = buildWindowsCmdInvocation(file, args);
+    return spawn(command, cmdArgs, {
+        ...options,
+        shell: false,
+        windowsVerbatimArguments: true
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copillm",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Local Copilot proxy CLI (OpenAI/Anthropic-compatible)",
   "license": "MIT",
   "type": "module",