@phnx-labs/agents-cli 1.20.7 → 1.20.9

package/dist/lib/self-update.js

@@ -0,0 +1,178 @@
+/**
+ * Self-update install plumbing.
+ *
+ * The hard requirement: an upgrade must replace the copy that is currently
+ * running. A bare `npm install -g` writes into the global prefix of whatever
+ * `npm` PATH happens to resolve — on machines with more than one node
+ * installation (nvm + Homebrew + vendored runtimes) that prefix can belong to
+ * a different node than the one this copy lives under. The install then
+ * "succeeds" while the running copy stays stale and re-prompts forever.
+ *
+ * So every step here is anchored to the running package root on disk, never
+ * to PATH resolution.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { compareVersions } from './versions.js';
+export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+/** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
+export function readUpdateCache(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        /* cache file missing or corrupt */
+        return null;
+    }
+}
+/**
+ * Persist the latest known version and current timestamp. Preserves an
+ * existing `dismissed` marker — the background refresh must not erase a
+ * user's "Skip this version" choice, or they get re-prompted for the exact
+ * version they dismissed.
+ */
+export function saveUpdateCheck(file, latestVersion) {
+    try {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const dismissed = readUpdateCache(file)?.dismissed;
+        fs.writeFileSync(file, JSON.stringify({ lastCheck: Date.now(), latestVersion, ...(dismissed ? { dismissed } : {}) }));
+    }
+    catch {
+        /* best-effort cache update */
+    }
+}
+/** Record that the user chose to skip `version`; suppresses prompts until a newer version appears. */
+export function dismissUpdateVersion(file, version) {
+    try {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const existing = readUpdateCache(file);
+        fs.writeFileSync(file, JSON.stringify({
+            lastCheck: existing?.lastCheck ?? Date.now(),
+            latestVersion: version,
+            dismissed: version,
+        }));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Whether the cached state warrants an upgrade prompt for a copy running `currentVersion`. */
+export function shouldPromptUpgrade(cache, currentVersion) {
+    if (!cache?.latestVersion)
+        return false;
+    return (cache.latestVersion !== currentVersion &&
+        compareVersions(cache.latestVersion, currentVersion) > 0 &&
+        cache.latestVersion !== cache.dismissed);
+}
+/**
+ * Derive the npm global prefix that owns the install at `packageRoot`.
+ *
+ * npm's global layout for a scoped package:
+ *   POSIX:   <prefix>/lib/node_modules/@phnx-labs/agents-cli
+ *   Windows: <prefix>/node_modules/@phnx-labs/agents-cli
+ *
+ * Throws when `packageRoot` is not inside a node_modules tree (e.g. running
+ * from a source checkout) — there is no prefix to install into, and guessing
+ * one is exactly the bug this module exists to prevent.
+ */
+export function deriveGlobalPrefix(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    // Two levels up from the package root: the scope dir, then node_modules.
+    const nodeModulesDir = path.dirname(path.dirname(resolved));
+    if (path.basename(nodeModulesDir) !== 'node_modules') {
+        throw new Error(`${resolved} is not an npm-managed install; reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+    }
+    const parent = path.dirname(nodeModulesDir);
+    return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
+}
+/**
+ * Install `spec` into an explicit global prefix. `--prefix` pins the
+ * destination no matter which npm binary PATH resolves. `--ignore-scripts`
+ * skips lifecycle scripts; the caller refreshes alias shims afterwards via
+ * refreshAliasShims().
+ */
+export async function installPackageIntoPrefix(spec, prefix) {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
+}
+/** Read the version field of the package.json at `packageRoot`, fresh from disk. */
+export function readInstalledVersion(packageRoot) {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version;
+}
+/**
+ * Assert that the install at `packageRoot` now carries `expectedVersion`.
+ * npm exiting 0 only proves it wrote *somewhere*; this proves it wrote *here*.
+ */
+export function verifyInstalledVersion(packageRoot, expectedVersion) {
+    const actual = readInstalledVersion(packageRoot);
+    if (actual !== expectedVersion) {
+        throw new Error(`npm reported success but ${packageRoot} is still ${actual} (expected ${expectedVersion}). ` +
+            `Run manually: npm install -g --prefix ${deriveGlobalPrefix(packageRoot)} ${NPM_PACKAGE_NAME}@${expectedVersion}`);
+    }
+}
+/**
+ * Re-run the freshly installed copy's postinstall in shims-only mode so the
+ * bare-command aliases (secrets, sessions, ...) pick up the new entrypoint
+ * and any aliases added in the new version. Best-effort: a failure here
+ * leaves the previous shims in place, which still point at the (now
+ * upgraded) package root.
+ */
+export function refreshAliasShims(packageRoot) {
+    spawnSync(process.execPath, [path.join(packageRoot, 'scripts', 'postinstall.js')], {
+        env: { ...process.env, AGENTS_POSTINSTALL_SHIMS_ONLY: '1' },
+        stdio: 'ignore',
+    });
+}
+/**
+ * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
+ * package root it executes. More than one distinct root means upgrades,
+ * shims, and the command the user types can act on different copies — the
+ * divergence behind silently-failing self-updates.
+ *
+ * npm bin entries are symlinks that resolve to `<packageRoot>/dist/index.js`
+ * (the dev install's `~/.local/bin/agents` chains through the dev prefix to
+ * the same shape). Anything that doesn't resolve to a dist/index.js inside a
+ * package named @phnx-labs/agents-cli is some other tool and is skipped.
+ * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
+ */
+export function findAgentsCliInstalls(pathEnv) {
+    if (process.platform === 'win32')
+        return [];
+    const installs = [];
+    const seenRoots = new Set();
+    for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, 'agents');
+        let real;
+        try {
+            real = fs.realpathSync(candidate);
+        }
+        catch {
+            continue; // missing or dangling symlink
+        }
+        if (path.basename(real) !== 'index.js' || path.basename(path.dirname(real)) !== 'dist') {
+            continue;
+        }
+        const packageRoot = path.dirname(path.dirname(real));
+        if (seenRoots.has(packageRoot))
+            continue;
+        let pkg;
+        try {
+            pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (pkg.name !== NPM_PACKAGE_NAME || typeof pkg.version !== 'string')
+            continue;
+        seenRoots.add(packageRoot);
+        installs.push({ binPath: candidate, packageRoot, version: pkg.version });
+    }
+    return installs;
+}

package/dist/lib/shims.d.ts

@@ -248,20 +248,25 @@ export declare function isShimsInPath(): boolean;
  * Get shell configuration instructions for adding shims to PATH.
  */
 export declare function getPathSetupInstructions(): string;
+interface ShimPathResult {
+    success: boolean;
+    alreadyPresent?: boolean;
+    rcFile?: string;
+    /** Human label of where the entry landed, e.g. `~/.zshrc` or `your user PATH`. */
+    location?: string;
+    /** Per-platform "how to pick it up" hint, e.g. `source ~/.zshrc` / open a new terminal. */
+    reloadHint?: string;
+    error?: string;
+}
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export declare function addShimsToPath(overrides?: {
     homeDir?: string;
     shell?: string;
     shimsDir?: string;
-}): {
-    success: boolean;
-    alreadyPresent?: boolean;
-    rcFile?: string;
-    error?: string;
-};
+}): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in

package/dist/lib/shims.js

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
 import { IS_WINDOWS } from './platform/index.js';
@@ -1520,18 +1521,15 @@ Then restart your shell or run:
   source ~/${rcFile}`;
 }
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export function addShimsToPath(overrides) {
-    // Windows has no shell rc file to edit: the primary `agents` command is already
-    // on PATH via npm's global bin, and bare shorthands / versioned aliases are
-    // handled by the `.cmd` shims plus the PATH guidance printed at install time.
-    // Report "already present" so callers don't emit a misleading "added to
-    // ~/.bashrc / source ~/.bashrc" message. (The `shell` override is the test hook
-    // for exercising the POSIX path, so it bypasses this short-circuit.)
+    // Windows has no shell rc file to edit. Register the shims dir on the User PATH
+    // via the platform-native mechanism instead. (The `shell` override is the test
+    // hook for exercising the POSIX path, so it bypasses this branch.)
     if (IS_WINDOWS && !overrides?.shell) {
-        return { success: true, alreadyPresent: true };
+        return addShimsToWindowsUserPath(overrides?.shimsDir || getShimsDir());
     }
     const shimsDir = overrides?.shimsDir || getShimsDir();
     const { rcFile, rcPath, shell } = getShellRcFile(overrides);
@@ -1565,16 +1563,53 @@ export function addShimsToPath(overrides) {
         const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
         let newContent = contentWithoutShimLines + separator + exportBlock;
         newContent = newContent.replace(/\n{2,}$/g, '\n');
+        const location = `~/${rcFile}`;
+        const reloadHint = `Restart your shell or run: source ~/${rcFile}`;
         if (newContent === content) {
-            return { success: true, alreadyPresent: true, rcFile };
+            return { success: true, alreadyPresent: true, rcFile, location, reloadHint };
         }
         fs.writeFileSync(rcPath, newContent, 'utf-8');
-        return { success: true, rcFile };
+        return { success: true, rcFile, location, reloadHint };
     }
     catch (err) {
         return { success: false, error: `Could not write ${rcFile}: ${err.message}` };
     }
 }
+/**
+ * Register the shims dir on the Windows User PATH via the .NET environment API,
+ * which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct analog
+ * of editing a shell rc file (no `setx` truncation, no manual step). Idempotent:
+ * a no-op when the dir is already present. The shims dir is passed via an env var
+ * so it is never interpolated into the PowerShell script text.
+ */
+function addShimsToWindowsUserPath(shimsDir) {
+    const script = [
+        '$d = $env:AGENTS_SHIMS_DIR',
+        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
+        "if ($null -eq $u) { $u = '' }",
+        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
+        "if ($parts -contains $d) { 'present' } else {",
+        "  [Environment]::SetEnvironmentVariable('Path', (($parts + $d) -join ';'), 'User')",
+        "  'added'",
+        '}',
+    ].join('\n');
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf-8',
+            env: { ...process.env, AGENTS_SHIMS_DIR: shimsDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return {
+            success: true,
+            alreadyPresent: out.includes('present'),
+            location: 'your user PATH',
+            reloadHint: 'Open a new terminal for the change to take effect.',
+        };
+    }
+    catch (err) {
+        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    }
+}
 export function listAgentsWithInstalledVersions() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {

package/dist/lib/versions.js

@@ -777,9 +777,9 @@ export function parseAgentSpec(spec) {
     if (parts.length > 2) {
         return null;
     }
-    const agentName = parts[0].toLowerCase();
     const version = parts[1] || 'latest';
-    if (!AGENTS[agentName]) {
+    const agent = resolveAgentName(parts[0]);
+    if (!agent) {
         return null;
     }
     // Reject any version string that could escape an exec context or a
@@ -788,7 +788,7 @@ export function parseAgentSpec(spec) {
         return null;
     }
     return {
-        agent: agentName,
+        agent,
         version,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.7",
+  "version": "1.20.9",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",

package/scripts/postinstall.js

@@ -32,6 +32,35 @@ function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+// Shorthands that delegate to the installed agents-cli entrypoint.
+const ALIASES = ['sessions', 'secrets', 'browser', 'pty', 'teams'];
+
+function writeAliasShims() {
+  const written = [];
+  for (const name of ALIASES) {
+    const target = path.join(SHIMS_DIR, name);
+    const script = `#!/bin/sh\nAGENTS_BIN=${shellQuote(AGENTS_BIN)}\nif [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then\n  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2\n  exit 127\nfi\nexec "$AGENTS_BIN" ${name} "$@"\n`;
+    fs.writeFileSync(target, script, { mode: 0o755 });
+    // Windows can't run the POSIX shim; drop a `.cmd` companion that invokes the
+    // entrypoint via node so the bare shorthand works in a Windows shell.
+    if (process.platform === 'win32') {
+      fs.writeFileSync(target + '.cmd', `@echo off\r\nnode "${AGENTS_BIN}" ${name} %*\r\n`);
+    }
+    written.push(name);
+  }
+  return written;
+}
+
+// Self-updater entry: the upgrade installs with --ignore-scripts (skipping
+// this script as an npm lifecycle hook), then re-invokes it with this env var
+// so the alias shims are refreshed from the newly installed copy. Shims only —
+// no prompts, no rc-file edits, no output.
+if (process.env.AGENTS_POSTINSTALL_SHIMS_ONLY === '1') {
+  fs.mkdirSync(SHIMS_DIR, { recursive: true });
+  writeAliasShims();
+  process.exit(0);
+}
+
 // For local installs, create directories and show a message
 const isGlobalInstall = process.env.npm_config_global || process.argv.includes('-g');
 if (!isGlobalInstall) {
@@ -86,25 +115,6 @@ const exportLine = shellName === 'fish'
   ? `fish_add_path ${SHIMS_DIR}`
   : `export PATH="${SHIMS_DIR}:$PATH"`;
 
-// Shorthands that delegate to the installed agents-cli entrypoint.
-const ALIASES = ['sessions', 'secrets', 'browser', 'pty', 'teams'];
-
-function writeAliasShims() {
-  const written = [];
-  for (const name of ALIASES) {
-    const target = path.join(SHIMS_DIR, name);
-    const script = `#!/bin/sh\nAGENTS_BIN=${shellQuote(AGENTS_BIN)}\nif [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then\n  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2\n  exit 127\nfi\nexec "$AGENTS_BIN" ${name} "$@"\n`;
-    fs.writeFileSync(target, script, { mode: 0o755 });
-    // Windows can't run the POSIX shim; drop a `.cmd` companion that invokes the
-    // entrypoint via node so the bare shorthand works in a Windows shell.
-    if (process.platform === 'win32') {
-      fs.writeFileSync(target + '.cmd', `@echo off\r\nnode "${AGENTS_BIN}" ${name} %*\r\n`);
-    }
-    written.push(name);
-  }
-  return written;
-}
-
 function getVersion() {
   const pkgPath = new URL('../package.json', import.meta.url).pathname;
   try {
@@ -144,17 +154,17 @@ function isAlreadyConfigured(rcFile) {
 }
 
 async function main() {
-  // Windows has no shell rc files to edit. Write the `.cmd` shorthands and point
-  // the user at the PATH entry they can add (the primary `agents` command is
-  // already on PATH via npm's global bin, so this only affects bare shorthands
-  // and versioned aliases).
+  // Windows has no shell rc files to edit. Write the `.cmd` shorthands here; the
+  // shims dir gets registered on the User PATH by `agents setup` (via the native
+  // registry API), so we point the user there instead of mutating PATH from an
+  // npm lifecycle script. The primary `agents` command is already on PATH via
+  // npm's global bin and works immediately.
   if (process.platform === 'win32') {
     console.log(`\nagents-cli installed.`);
     const written = writeAliasShims();
     console.log(`  Installed shorthands: ${written.join(', ')}`);
-    console.log(`\nTo use bare shorthands (${ALIASES.join(', ')}) and versioned aliases, add this to your PATH:`);
-    console.log(`  ${SHIMS_DIR}`);
-    console.log(`  PowerShell: setx PATH "$env:PATH;${SHIMS_DIR}"  (then open a new terminal)`);
+    console.log(`\nNext: run  agents setup  — it finishes setup and adds the shims dir to your PATH`);
+    console.log(`(so the bare shorthands ${ALIASES.join(', ')} and versioned aliases work in a new terminal).`);
   }
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
   else if (process.env.AGENTS_INIT_SHELL === '1') {