codeam-cli 2.16.2 → 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.2",
+  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",
@@ -8592,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();
@@ -8605,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("");
@@ -10920,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);
@@ -10934,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...");
@@ -11153,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.2" : "unknown";
+  const v = true ? "2.17.0" : "unknown";
   console.log(`${import_picocolors12.default.bold("codeam-cli")} ${import_picocolors12.default.cyan(v)}`);
 }
 
@@ -11198,12 +11249,74 @@ 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 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;
@@ -11282,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.`,
     ""
   ];
@@ -11297,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.2" : null;
+  const current = true ? "2.17.0" : null;
   if (!current) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -11316,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.2",
+  "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",