codeam-cli 2.16.1 → 2.17.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `codeam-cli` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.16.2] — 2026-05-22
+
+### Chore
+
+- **meta:** Expand issue templates with question + documentation forms
+
+### Documentation
+
+- **shared:** Correct prod URL in api-url history comment
+
+### Fixed
+
+- **cli:** Codeam link — auto-install, multi-probe creds, file-watcher login
+- **cli:** Windows EPERM crash from chokidar watching user-profile junctions (#43)
+
+## [2.16.1] — 2026-05-21
+
+### Fixed
+
+- **cli:** Codeam link — auto-install, multi-probe creds, file-watcher login (#42)
+
 ## [2.16.0] — 2026-05-21
 
 ### Added

package/dist/index.js

@@ -424,7 +424,7 @@ var import_qrcode_terminal = __toESM(require("qrcode-terminal"));
 // package.json
 var package_default = {
   name: "codeam-cli",
-  version: "2.16.1",
+  version: "2.17.0",
   description: "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device \u2014 async. The terminal companion for CodeAgent Mobile.",
   type: "commonjs",
   main: "dist/index.js",
@@ -6262,6 +6262,7 @@ var HistoryService = class _HistoryService {
 
 // src/services/file-watcher.service.ts
 var import_child_process7 = require("child_process");
+var os13 = __toESM(require("os"));
 var path15 = __toESM(require("path"));
 
 // src/services/file-watcher/diff-parser.ts
@@ -6397,6 +6398,44 @@ var API_BASE5 = process.env.CODEAM_API_URL ?? DEFAULT_API_BASE_URL;
 var DEBOUNCE_MS = 250;
 var MAX_RETRIES = 2;
 var RETRY_BACKOFF_MS = 300;
+var WINDOWS_LEGACY_JUNCTIONS = [
+  /[\\/]Application Data([\\/]|$)/i,
+  /[\\/]Cookies([\\/]|$)/i,
+  /[\\/]Local Settings([\\/]|$)/i,
+  /[\\/]My Documents([\\/]|$)/i,
+  /[\\/]NetHood([\\/]|$)/i,
+  /[\\/]PrintHood([\\/]|$)/i,
+  /[\\/]Recent([\\/]|$)/i,
+  /[\\/]SendTo([\\/]|$)/i,
+  /[\\/]Start Menu([\\/]|$)/i,
+  /[\\/]Templates([\\/]|$)/i
+];
+function isUnsafeWindowsWatchRoot(dir, homedir12) {
+  const norm = (p2) => p2.replace(/\//g, "\\").replace(/\\+$/, "").toLowerCase();
+  const cwd = norm(dir);
+  const home = norm(homedir12);
+  if (cwd === home) return true;
+  if (/^[a-z]:$/.test(cwd)) return true;
+  const sysRoots = [
+    "c:\\windows",
+    "c:\\program files",
+    "c:\\program files (x86)",
+    "c:\\programdata"
+  ];
+  for (const root of sysRoots) {
+    if (cwd === root || cwd.startsWith(root + "\\")) return true;
+  }
+  return false;
+}
+var _chokidarSeam = {
+  load: () => {
+    try {
+      return require("chokidar");
+    } catch {
+      return null;
+    }
+  }
+};
 var FileWatcherService = class {
   constructor(opts) {
     this.opts = opts;
@@ -6419,14 +6458,19 @@ var FileWatcherService = class {
     if (this.stopped) {
       throw new Error("FileWatcherService has already been stopped \u2014 re-instantiate to restart.");
     }
-    let chokidar2;
-    try {
-      chokidar2 = require("chokidar");
-    } catch (err) {
+    const isWin = process.platform === "win32";
+    if (isWin && isUnsafeWindowsWatchRoot(this.opts.workingDir, os13.homedir())) {
+      log.warn(
+        "fileWatcher",
+        `refusing to watch ${this.opts.workingDir} \u2014 looks like a Windows user-profile or system path. Run codeam from your project folder to enable file change emission.`
+      );
+      return;
+    }
+    const chokidar2 = _chokidarSeam.load();
+    if (!chokidar2) {
       log.warn(
         "fileWatcher",
-        `chokidar unavailable \u2014 file change emission disabled`,
-        err
+        `chokidar unavailable \u2014 file change emission disabled`
       );
       return;
     }
@@ -6444,11 +6488,22 @@ var FileWatcherService = class {
         /\.parcel-cache/,
         // Build outputs that aren't a typical "dist" target
         /target\//,
-        /__pycache__/
+        /__pycache__/,
+        // Windows-only: skip legacy user-profile junctions whose ACLs
+        // throw EPERM during chokidar's recursive traversal.
+        ...isWin ? WINDOWS_LEGACY_JUNCTIONS : []
       ],
       ignoreInitial: true,
       // we only care about post-start changes
       persistent: true,
+      // Windows-only safety net: don't follow reparse points, and let
+      // chokidar swallow EPERM/EACCES on unreadable paths instead of
+      // bubbling them up as fatal errors. Both are no-ops on macOS
+      // (fsevents traversal doesn't fail on permission errors).
+      ...isWin ? {
+        followSymlinks: false,
+        ignorePermissionErrors: true
+      } : {},
       awaitWriteFinish: {
         // Coalesces rapid sequential writes (npm install spam, build
         // tools emitting bursts). Lower than chokidar's default so
@@ -6461,6 +6516,13 @@ var FileWatcherService = class {
     watcher.on("add", (filePath) => this.schedule(filePath, "add"));
     watcher.on("change", (filePath) => this.schedule(filePath, "change"));
     watcher.on("unlink", (filePath) => this.schedule(filePath, "unlink"));
+    watcher.on("error", (err) => {
+      const code = err?.code ?? "unknown";
+      log.warn(
+        "fileWatcher",
+        `chokidar error (code=${code}) \u2014 watcher continues: ${err}`
+      );
+    });
     this.watcher = watcher;
     log.info(
       "fileWatcher",
@@ -7199,7 +7261,7 @@ function buildKeepAlive(ctx) {
 
 // src/commands/start/handlers.ts
 var fs14 = __toESM(require("fs"));
-var os13 = __toESM(require("os"));
+var os14 = __toESM(require("os"));
 var path19 = __toESM(require("path"));
 var import_crypto3 = require("crypto");
 var import_child_process11 = require("child_process");
@@ -8007,7 +8069,7 @@ function closeTerminal(sessionId) {
 function saveFilesTemp(files) {
   return files.filter(({ base64 }) => base64 && base64.length > 0).map(({ filename, base64 }) => {
     const safeName = filename.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
-    const tmpPath = path19.join(os13.tmpdir(), `codeam-${(0, import_crypto3.randomUUID)()}-${safeName}`);
+    const tmpPath = path19.join(os14.tmpdir(), `codeam-${(0, import_crypto3.randomUUID)()}-${safeName}`);
     fs14.writeFileSync(tmpPath, Buffer.from(base64, "base64"));
     return tmpPath;
   });
@@ -8530,8 +8592,9 @@ async function promptForAgent(initialValue) {
 // src/commands/pair.ts
 async function pair(args2 = []) {
   const config = loadCliConfig();
+  const dryRun = args2.includes("--dry-run");
   const flagAgent = parseAgentFlag(args2);
-  const agentId = flagAgent ?? await promptForAgent(config.preferredAgent ?? "claude");
+  const agentId = dryRun ? flagAgent ?? config.preferredAgent ?? "claude" : flagAgent ?? await promptForAgent(config.preferredAgent ?? "claude");
   showIntro();
   const pluginId = (0, import_crypto4.randomUUID)();
   const spin = dist_exports.spinner();
@@ -8543,6 +8606,20 @@ async function pair(args2 = []) {
     process.exit(1);
   }
   spin.stop("Got pairing code");
+  if (dryRun) {
+    const codeOk = typeof result.code === "string" && result.code.trim().length > 0;
+    const expiresOk = typeof result.expiresAt === "number" && result.expiresAt > 0;
+    if (!codeOk || !expiresOk) {
+      showError(
+        `Pair dry-run: backend response shape unexpected (codeType=${typeof result.code}, codeEmpty=${!codeOk}, expiresType=${typeof result.expiresAt}, expiresPositive=${expiresOk}).`
+      );
+      process.exit(1);
+    }
+    showSuccess(
+      `Pair dry-run OK \u2014 backend reachable, response shape valid (codeLength=${result.code.length}, expiresAt=${result.expiresAt}, agent=${agentId}).`
+    );
+    process.exit(0);
+  }
   showPairingCode(result.code);
   console.log(import_picocolors3.default.dim("  Scan the QR code or enter the code in CodeAgent Mobile."));
   console.log("");
@@ -8596,7 +8673,7 @@ async function pair(args2 = []) {
 
 // src/commands/pair-auto.ts
 var fs15 = __toESM(require("fs"));
-var os14 = __toESM(require("os"));
+var os15 = __toESM(require("os"));
 var import_crypto5 = require("crypto");
 var API_BASE7 = process.env.CODEAM_API_URL ?? DEFAULT_API_BASE_URL;
 function fail(msg) {
@@ -8636,7 +8713,7 @@ async function claim(token, pluginId) {
     pluginId,
     ideName: "codeam-cli (codespace)",
     ideVersion: process.env.npm_package_version ?? "unknown",
-    hostname: os14.hostname(),
+    hostname: os15.hostname(),
     codespaceName: process.env.CODESPACE_NAME ?? "",
     // Current git branch of the codespace's working directory, so the
     // backend can populate `PairedSession.branch` for the codespace pair.
@@ -10741,7 +10818,7 @@ var import_picocolors11 = __toESM(require("picocolors"));
 // src/agents/claude/local-token.ts
 var import_node_child_process2 = require("child_process");
 var fs16 = __toESM(require("fs"));
-var os15 = __toESM(require("os"));
+var os16 = __toESM(require("os"));
 var path24 = __toESM(require("path"));
 var import_node_util3 = require("util");
 var execFileP7 = (0, import_node_util3.promisify)(import_node_child_process2.execFile);
@@ -10752,7 +10829,7 @@ var KEYCHAIN_SERVICE_NAMES = [
   "Anthropic Claude"
 ];
 function claudeCredentialsPaths() {
-  const home = os15.homedir();
+  const home = os16.homedir();
   return [
     path24.join(home, ".claude", ".credentials.json"),
     path24.join(home, ".config", "claude", ".credentials.json")
@@ -10787,10 +10864,10 @@ async function extractLocalClaudeToken() {
 
 // src/agents/codex/local-token.ts
 var fs17 = __toESM(require("fs"));
-var os16 = __toESM(require("os"));
+var os17 = __toESM(require("os"));
 var path25 = __toESM(require("path"));
 function codexCredentialsPath() {
-  return path25.join(os16.homedir(), ".codex", "auth.json");
+  return path25.join(os17.homedir(), ".codex", "auth.json");
 }
 async function extractLocalCodexToken() {
   const file = codexCredentialsPath();
@@ -10858,11 +10935,12 @@ function parseLinkArgs(args2) {
     );
   }
   const reuseExisting = args2.includes("--reuse-existing");
+  const dryRun = args2.includes("--dry-run");
   const apiKeyArg = args2.find((a) => a.startsWith("--api-key="));
   const apiKey = apiKeyArg ? apiKeyArg.slice("--api-key=".length) : null;
   const tokenFileArg = args2.find((a) => a.startsWith("--token-file="));
   const tokenFile = tokenFileArg ? tokenFileArg.slice("--token-file=".length) : null;
-  return { agent: normalised, reuseExisting, apiKey, tokenFile };
+  return { agent: normalised, reuseExisting, apiKey, tokenFile, dryRun };
 }
 async function link(args2 = []) {
   const parsed = parseLinkArgs(args2);
@@ -10872,6 +10950,10 @@ async function link(args2 = []) {
     import_picocolors11.default.bold(`  Link ${meta.displayName}`) + import_picocolors11.default.dim(`  \xB7  ${meta.vendor}`)
   );
   console.log("");
+  if (parsed.dryRun) {
+    await linkDryRunPreflight(meta);
+    return;
+  }
   const pluginId = (0, import_node_crypto.randomUUID)();
   const spin = dist_exports.spinner();
   spin.start("Requesting pairing code...");
@@ -10981,10 +11063,20 @@ async function link(args2 = []) {
   await uploadAndSucceed(meta, paired, pluginId, captured);
 }
 async function captureFreshCredentials(meta) {
+  const isWin = process.platform === "win32";
   const watcher = import_chokidar.default.watch(meta.watchPaths(), {
     persistent: true,
     ignoreInitial: false,
-    awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 }
+    awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+    // Windows-only: when a credential file's ancestor is missing,
+    // chokidar walks up to the closest existing parent and starts
+    // traversing it. On a default Windows shell that ancestor is
+    // `C:\Users\<u>`, which contains legacy junctions whose ACL makes
+    // `fs.watch` throw EPERM (#43). These flags are no-ops on macOS,
+    // where the user has read access to their entire home.
+    ...isWin ? { followSymlinks: false, ignorePermissionErrors: true } : {}
+  });
+  watcher.on("error", () => {
   });
   let child = null;
   let keychainPoll = null;
@@ -11081,11 +11173,42 @@ async function uploadAndSucceed(meta, paired, pluginId, token) {
   );
   console.log("");
 }
+async function linkDryRunPreflight(meta) {
+  const spin = dist_exports.spinner();
+  spin.start(`Probing ${meta.publicId} link endpoint...`);
+  const result = await postLinkCredential({
+    agentId: meta.publicId,
+    sessionId: "dryrun-session",
+    pluginId: "dryrun-plugin",
+    pluginAuthToken: "dryrun-token",
+    method: "oauth",
+    credential: "dryrun-credential"
+  });
+  if (result.ok) {
+    spin.stop("Unexpected 2xx");
+    showError(
+      "Link dry-run: backend accepted a stub credential (2xx). PluginAuthGuard appears to be disabled \u2014 investigate api-v2."
+    );
+    process.exit(1);
+  }
+  if (result.status === 401) {
+    spin.stop("Endpoint OK");
+    showSuccess(
+      `Link dry-run OK \u2014 /api/plugin/agents/${meta.publicId}/link reachable and auth-gated (401 as expected).`
+    );
+    process.exit(0);
+  }
+  spin.stop("Failed");
+  showError(
+    `Link dry-run: unexpected response from /api/plugin/agents/${meta.publicId}/link (status=${result.status}, message=${result.message}). Expected 401.`
+  );
+  process.exit(1);
+}
 
 // src/commands/version.ts
 var import_picocolors12 = __toESM(require("picocolors"));
 function version() {
-  const v = true ? "2.16.1" : "unknown";
+  const v = true ? "2.17.0" : "unknown";
   console.log(`${import_picocolors12.default.bold("codeam-cli")} ${import_picocolors12.default.cyan(v)}`);
 }
 
@@ -11126,18 +11249,80 @@ function help() {
   process.stdout.write(lines.join("\n") + "\n");
 }
 
+// src/commands/subcommand-help.ts
+var import_picocolors14 = __toESM(require("picocolors"));
+var HELPS = {
+  pair: () => print([
+    `  ${import_picocolors14.default.bold("codeam pair")}  ${import_picocolors14.default.dim("\u2014 pair a mobile device with this CLI")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam pair")}                  ${import_picocolors14.default.dim("interactive pairing (prompts for the agent)")}`,
+    `     ${import_picocolors14.default.cyan("codeam pair --agent <id>")}     ${import_picocolors14.default.dim("pair non-interactively (agent: claude | codex)")}`,
+    `     ${import_picocolors14.default.cyan("codeam pair --dry-run")}        ${import_picocolors14.default.dim("request a pairing code, validate the response, exit")}`
+  ]),
+  "pair-auto": () => print([
+    `  ${import_picocolors14.default.bold("codeam pair-auto")}  ${import_picocolors14.default.dim("\u2014 non-interactive variant of pair for scripted setups")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam pair-auto --agent <id>")}  ${import_picocolors14.default.dim("pair using the supplied agent id; exit on success or timeout")}`
+  ]),
+  link: () => print([
+    `  ${import_picocolors14.default.bold("codeam link <agent>")}  ${import_picocolors14.default.dim("\u2014 upload a local agent token (Claude or Codex) to your vault")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam link claude")}`,
+    `     ${import_picocolors14.default.cyan("codeam link codex")}`,
+    "",
+    `     ${import_picocolors14.default.white("--api-key=<key>")}      ${import_picocolors14.default.dim("paste an API key directly (skip the local auth flow)")}`,
+    `     ${import_picocolors14.default.white("--reuse-existing")}     ${import_picocolors14.default.dim("upload existing creds without re-launching the agent login")}`,
+    `     ${import_picocolors14.default.white("--token-file=<path>")}  ${import_picocolors14.default.dim("manual credential blob path for unusual vendor locations")}`,
+    `     ${import_picocolors14.default.white("--dry-run")}            ${import_picocolors14.default.dim("probe the /api/plugin/agents/<agent>/link endpoint and exit")}`
+  ]),
+  sessions: () => print([
+    `  ${import_picocolors14.default.bold("codeam sessions")}  ${import_picocolors14.default.dim("\u2014 list, switch, or delete paired mobile sessions")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam sessions")}              ${import_picocolors14.default.dim("list all paired sessions on this machine")}`,
+    `     ${import_picocolors14.default.cyan("codeam sessions switch")}       ${import_picocolors14.default.dim("interactively switch the active session")}`,
+    `     ${import_picocolors14.default.cyan("codeam sessions delete <id>")}  ${import_picocolors14.default.dim("remove a specific paired session")}`
+  ]),
+  deploy: () => print([
+    `  ${import_picocolors14.default.bold("codeam deploy")}  ${import_picocolors14.default.dim("\u2014 provision a cloud workspace (GitHub Codespaces) and pair it")}`,
+    "",
+    `     ${import_picocolors14.default.cyan("codeam deploy")}                ${import_picocolors14.default.dim("start a new deploy (prompts for repo + agent)")}`,
+    `     ${import_picocolors14.default.cyan("codeam deploy ls | list")}      ${import_picocolors14.default.dim("list deployed cloud workspaces")}`,
+    `     ${import_picocolors14.default.cyan("codeam deploy stop | remove")}  ${import_picocolors14.default.dim("pick a workspace and stop its codeam-pair session")}`
+  ]),
+  status: () => print([
+    `  ${import_picocolors14.default.bold("codeam status")}  ${import_picocolors14.default.dim("\u2014 show the active session, agent, and connection info")}`
+  ]),
+  logout: () => print([
+    `  ${import_picocolors14.default.bold("codeam logout")}  ${import_picocolors14.default.dim("\u2014 remove every paired session from this machine")}`
+  ])
+};
+function print(lines) {
+  process.stdout.write(["", ...lines, ""].join("\n") + "\n");
+}
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
+function tryShowSubcommandHelp(cmd, args2) {
+  if (!isHelpFlag(args2[0])) return false;
+  const renderer = HELPS[cmd];
+  if (!renderer) return false;
+  renderer();
+  return true;
+}
+var _subcommandHelpKeys = Object.keys(HELPS);
+
 // src/lib/updateNotifier.ts
 var fs19 = __toESM(require("fs"));
-var os17 = __toESM(require("os"));
+var os18 = __toESM(require("os"));
 var path27 = __toESM(require("path"));
 var https7 = __toESM(require("https"));
-var import_picocolors14 = __toESM(require("picocolors"));
+var import_picocolors15 = __toESM(require("picocolors"));
 var PKG_NAME = "codeam-cli";
 var REGISTRY_URL = `https://registry.npmjs.org/${PKG_NAME}/latest`;
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var REQUEST_TIMEOUT_MS = 1500;
 function cachePath() {
-  const dir = path27.join(os17.homedir(), ".codeam");
+  const dir = path27.join(os18.homedir(), ".codeam");
   return path27.join(dir, "update-check.json");
 }
 function readCache() {
@@ -11210,11 +11395,11 @@ function fetchLatest() {
 }
 function notifyIfStale(currentVersion, latest) {
   if (compareSemver(latest, currentVersion) <= 0) return;
-  const arrow = import_picocolors14.default.dim("\u2192");
-  const cmd = import_picocolors14.default.cyan("npm install -g codeam-cli");
+  const arrow = import_picocolors15.default.dim("\u2192");
+  const cmd = import_picocolors15.default.cyan("npm install -g codeam-cli");
   const lines = [
     "",
-    `  ${import_picocolors14.default.yellow("\u25CF")} ${import_picocolors14.default.bold("Update available")} ${import_picocolors14.default.dim(currentVersion)} ${arrow} ${import_picocolors14.default.green(latest)}`,
+    `  ${import_picocolors15.default.yellow("\u25CF")} ${import_picocolors15.default.bold("Update available")} ${import_picocolors15.default.dim(currentVersion)} ${arrow} ${import_picocolors15.default.green(latest)}`,
     `    Run ${cmd} to upgrade.`,
     ""
   ];
@@ -11225,7 +11410,7 @@ function checkForUpdates() {
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
   if (!process.stdout.isTTY) return;
-  const current = true ? "2.16.1" : null;
+  const current = true ? "2.17.0" : null;
   if (!current) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -11244,6 +11429,9 @@ var [, , command, ...args] = process.argv;
 async function main() {
   const isMetaCommand = command === "--version" || command === "-v" || command === "version" || command === "--help" || command === "-h" || command === "help";
   if (!isMetaCommand) checkForUpdates();
+  if (typeof command === "string" && tryShowSubcommandHelp(command, args)) {
+    return;
+  }
   switch (command) {
     case "--version":
     case "-v":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeam-cli",
-  "version": "2.16.1",
+  "version": "2.17.0",
   "description": "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device — async. The terminal companion for CodeAgent Mobile.",
   "type": "commonjs",
   "main": "dist/index.js",