@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/commands/commands.js

@@ -3,15 +3,16 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { checkbox, confirm } from '@inquirer/prompts';
-import { ALL_AGENT_IDS, COMMANDS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { checkbox } from '@inquirer/prompts';
+import { ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverCommands, resolveCommandSource, installCommandCentrally, uninstallCommand, listCentralCommands, getCommandInfo, diffVersionCommands, installCommandToVersion, removeCommandFromVersion, iterCommandsCapableVersions, } from '../lib/commands.js';
+import { discoverCommands, resolveCommandSource, installCommandCentrally, uninstallCommand, listCentralCommands, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+/** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
         .command('commands')
@@ -58,7 +59,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] || undefined;
+            filterVersion = resolveVersionAlias(resolved, parts[1]);
         }
         const rows = buildCommandRows({ filterAgent, filterVersion });
         spinner.stop();
@@ -127,7 +128,7 @@ Examples:
                     }
                     // Build choices with descriptions
                     const choices = centralCommands.map((name) => {
-                        const cmdPath = path.join(os.homedir(), '.agents', 'commands', `${name}.md`);
+                        const cmdPath = path.join(getCommandsDir(), `${name}.md`);
                         let description = '';
                         if (fs.existsSync(cmdPath)) {
                             const content = fs.readFileSync(cmdPath, 'utf-8');
@@ -324,174 +325,26 @@ Examples:
             }
         }
     });
+    // `commands sync` is gone — sync runs automatically when the agent launches.
     commandsCmd
-        .command('sync')
-        .description('Reconcile version-home commands against central ~/.agents/commands/ (add + update, never delete)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('-m, --method <method>', 'Install method: copy (default) or symlink (markdown-format agents only)', 'copy')
-        .addHelpText('after', `
-Examples:
-  # Sync every installed version
-  agents commands sync
-
-  # Scope to one agent or version
-  agents commands sync --agent claude
-  agents commands sync --agent claude@2.1.113
-
-  # Symlink into version homes (propagates central edits automatically, markdown agents only)
-  agents commands sync --method symlink
-
-Note: Gemini uses TOML — symlink is ignored and a fresh conversion is written
-on every sync. Sync is additive: to remove orphans, use 'agents commands prune'.
-`)
-        .action(async (options) => {
-        const method = (options.method === 'symlink' ? 'symlink' : 'copy');
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, COMMANDS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterCommandsCapableVersions(filter);
-        if (pairs.length === 0) {
-            console.log(chalk.gray('No matching installed versions.'));
-            return;
-        }
-        const diffs = pairs.map(({ agent, version }) => diffVersionCommands(agent, version));
-        const plan = diffs.filter((d) => d.toAdd.length > 0 || d.toUpdate.length > 0);
-        if (plan.length === 0) {
-            console.log(chalk.green('All version homes are up to date with central.'));
-            if (diffs.some((d) => d.orphans.length > 0)) {
-                console.log(chalk.gray('Orphan commands present. Run \'agents commands prune --dry-run\' to review.'));
-            }
-            return;
-        }
-        console.log(chalk.bold(`Syncing commands (method: ${method})\n`));
-        let adds = 0, updates = 0, failures = 0;
-        for (const diff of plan) {
-            const label = `${diff.agent}@${diff.version}`;
-            if (diff.toAdd.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('add:')} ${diff.toAdd.join(', ')}`);
-                for (const name of diff.toAdd) {
-                    const r = installCommandToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        adds++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-            if (diff.toUpdate.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('update:')} ${diff.toUpdate.join(', ')}`);
-                for (const name of diff.toUpdate) {
-                    const r = installCommandToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        updates++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-        }
-        console.log();
-        console.log(chalk.green(`Synced: ${adds} added, ${updates} updated${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
-        const totalOrphans = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        if (totalOrphans > 0) {
-            console.log(chalk.gray(`${totalOrphans} orphan(s) remain. Run 'agents commands prune --dry-run' to review.`));
-        }
+        .command('sync', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents commands sync" is gone.'));
+        console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune commands'));
+        process.exit(1);
     });
+    // `commands prune` moved to the top-level `agents prune` command.
     commandsCmd
-        .command('prune')
-        .description('Remove orphan commands from version homes (commands present locally but not in central)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('--dry-run', 'Show orphans without deleting')
-        .option('-y, --yes', 'Skip confirmation prompt')
-        .addHelpText('after', `
-Examples:
-  # See what would be pruned
-  agents commands prune --dry-run
-
-  # Prune across every installed version (prompts for confirmation)
-  agents commands prune
-
-  # Scope to one agent or version
-  agents commands prune --agent claude@2.0.65
-
-  # Skip confirmation (for scripts)
-  agents commands prune -y
-`)
-        .action(async (options) => {
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, COMMANDS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterCommandsCapableVersions(filter);
-        const diffs = pairs
-            .map(({ agent, version }) => diffVersionCommands(agent, version))
-            .filter((d) => d.orphans.length > 0);
-        if (diffs.length === 0) {
-            console.log(chalk.green('No orphan commands.'));
-            return;
-        }
-        const total = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        console.log(chalk.bold(`Orphans (in version home, not in central)\n`));
-        for (const d of diffs) {
-            console.log(`  ${chalk.cyan(`${d.agent}@${d.version}`)}  ${d.orphans.join(', ')}`);
-        }
-        console.log();
-        if (options.dryRun) {
-            console.log(chalk.gray(`${total} orphan(s). Run without --dry-run to delete.`));
-            return;
-        }
-        if (!options.yes) {
-            if (!isInteractiveTerminal()) {
-                console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-                process.exit(1);
-            }
-            let ok = false;
-            try {
-                ok = await confirm({
-                    message: `Delete ${total} orphan command${total === 1 ? '' : 's'}?`,
-                    default: false,
-                });
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-                throw err;
-            }
-            if (!ok) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-        }
-        let removed = 0, failures = 0;
-        for (const d of diffs) {
-            for (const name of d.orphans) {
-                const r = removeCommandFromVersion(d.agent, d.version, name);
-                if (r.success)
-                    removed++;
-                else {
-                    failures++;
-                    console.log(chalk.red(`  ! ${d.agent}@${d.version} ${name}: ${r.error}`));
-                }
-            }
-        }
-        console.log(chalk.green(`Pruned ${removed} orphan(s)${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
+        .command('prune', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents commands prune" moved.'));
+        console.error(chalk.gray('Use:  agents prune commands   (or `agents prune` for everything)'));
+        process.exit(1);
     });
     commandsCmd
         .command('view [name]')
@@ -625,4 +478,3 @@ function formatCommandDetail(name, info, targets) {
     lines.push(buildTargetsSection(targets));
     return lines.join('\n');
 }
-//# sourceMappingURL=commands.js.map

package/dist/commands/daemon.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Deprecated daemon commands.
+ *
+ * Registers the hidden `agents daemon` command tree as backward-compatible
+ * aliases for `agents routines` scheduler lifecycle commands. Scheduled
+ * for removal in v2.0.
+ */
 import type { Command } from 'commander';
+/** Register the deprecated `agents daemon` command tree. */
 export declare function registerDaemonCommands(program: Command): void;
-//# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.js

@@ -1,11 +1,21 @@
+/**
+ * Deprecated daemon commands.
+ *
+ * Registers the hidden `agents daemon` command tree as backward-compatible
+ * aliases for `agents routines` scheduler lifecycle commands. Scheduled
+ * for removal in v2.0.
+ */
+import { spawn } from 'child_process';
 import chalk from 'chalk';
 import * as path from 'path';
 import { startDaemon, stopDaemon, isDaemonRunning, readDaemonPid, readDaemonLog, runDaemon, } from '../lib/daemon.js';
 import { listJobs as listAllJobs } from '../lib/routines.js';
 import { JobScheduler } from '../lib/scheduler.js';
+/** Print a deprecation warning pointing to the replacement command. */
 function warnDeprecated(subcommand, replacement) {
     console.log(chalk.yellow(`\u26a0  'agents daemon ${subcommand}' is deprecated and will be removed in v2.0. Use '${replacement}' instead.\n`));
 }
+/** Register the deprecated `agents daemon` command tree. */
 export function registerDaemonCommands(program) {
     const daemonCmd = program
         .command('daemon', { hidden: true })
@@ -81,12 +91,11 @@ you never need to start it manually.
         .action(async (options) => {
         warnDeprecated('logs', 'agents routines scheduler-logs');
         if (options.follow) {
-            const { exec: execCb } = await import('child_process');
             const { getAgentsDir } = await import('../lib/state.js');
             const logPath = path.join(getAgentsDir(), 'daemon.log');
-            const child = execCb(`tail -f "${logPath}"`);
-            child.stdout?.pipe(process.stdout);
-            child.stderr?.pipe(process.stderr);
+            const child = spawn('tail', ['-f', logPath], { stdio: ['ignore', 'pipe', 'pipe'] });
+            child.stdout.pipe(process.stdout);
+            child.stderr.pipe(process.stderr);
             child.on('exit', () => process.exit(0));
             process.on('SIGINT', () => { child.kill(); process.exit(0); });
             return;
@@ -107,4 +116,3 @@ you never need to start it manually.
         await runDaemon();
     });
 }
-//# sourceMappingURL=daemon.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents doctor` — diagnostic readout across the install.
+ *
+ * Three sections:
+ *   1. CLI availability — which agent binaries can be invoked.
+ *   2. Sync status — per (agent, default-version), is the version-home sync
+ *      manifest fresh? (sync runs at launch; this surfaces what would happen.)
+ *   3. Orphans — per resource type per default version, count of files that
+ *      would be removed by `agents prune`.
+ *
+ * Read-only: doctor never mutates state. Run `agents prune` to act on the
+ * orphan readout, or just launch the agent to apply pending sync.
+ */
+import type { Command } from 'commander';
+export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,132 @@
+import chalk from 'chalk';
+import { checkAllClis } from '../lib/teams/agents.js';
+import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+import { getAvailableResources, getGlobalDefault, } from '../lib/versions.js';
+import { loadSyncManifest, isSyncStale } from '../lib/sync-manifest.js';
+import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
+import { diffVersionHooks, iterHooksCapableVersions } from '../lib/hooks.js';
+const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
+function checkSyncStatus(cwd) {
+    const rows = [];
+    for (const agent of ALL_AGENT_IDS) {
+        const version = getGlobalDefault(agent);
+        if (!version)
+            continue;
+        const manifest = loadSyncManifest(agent, version);
+        if (!manifest) {
+            rows.push({ agent, version, status: 'never-synced' });
+            continue;
+        }
+        const available = getAvailableResources(cwd);
+        const stale = isSyncStale(manifest, available, agent, version, cwd);
+        rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
+    }
+    return rows;
+}
+function countOrphans() {
+    const byKey = new Map();
+    const ensure = (agent, version) => {
+        const key = `${agent}@${version}`;
+        let row = byKey.get(key);
+        if (!row) {
+            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
+            byKey.set(key, row);
+        }
+        return row;
+    };
+    for (const { agent, version } of iterCommandsCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionCommands(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).commands = diff.orphans.length;
+    }
+    for (const { agent, version } of iterSkillsCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionSkills(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).skills = diff.orphans.length;
+    }
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionHooks(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).hooks = diff.orphans.length;
+    }
+    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+}
+function renderText(clis, syncRows, orphanRows) {
+    console.log(chalk.bold('Agent CLIs'));
+    if (Object.keys(clis).length === 0) {
+        console.log(chalk.gray('  (no agents reported)'));
+    }
+    else {
+        for (const [name, entry] of Object.entries(clis)) {
+            const pretty = AGENT_NAMES[name] || name;
+            if (entry.installed) {
+                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}`);
+            }
+            else {
+                console.log(`  ${chalk.red('no   ')}  ${pretty.padEnd(10)} ${chalk.gray(entry.error || 'not installed')}`);
+            }
+        }
+    }
+    console.log();
+    console.log(chalk.bold('Sync status (default versions)'));
+    if (syncRows.length === 0) {
+        console.log(chalk.gray('  (no default versions set; pin one with `agents use <agent>@<version>`)'));
+    }
+    else {
+        for (const row of syncRows) {
+            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+            if (row.status === 'fresh') {
+                console.log(`  ${chalk.green('fresh')}  ${label}`);
+            }
+            else if (row.status === 'stale') {
+                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— will sync on next launch')}`);
+            }
+            else {
+                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced; first launch will populate')}`);
+            }
+        }
+    }
+    console.log();
+    console.log(chalk.bold('Orphans (default versions)'));
+    if (orphanRows.length === 0) {
+        console.log(chalk.gray('  (none — version homes match central sources)'));
+    }
+    else {
+        for (const row of orphanRows) {
+            const parts = [];
+            if (row.commands > 0)
+                parts.push(`${row.commands} command${row.commands === 1 ? '' : 's'}`);
+            if (row.skills > 0)
+                parts.push(`${row.skills} skill${row.skills === 1 ? '' : 's'}`);
+            if (row.hooks > 0)
+                parts.push(`${row.hooks} hook${row.hooks === 1 ? '' : 's'}`);
+            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+            console.log(`  ${chalk.yellow('warn ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
+        }
+        console.log(chalk.gray('  Run `agents prune` to remove.'));
+    }
+}
+export function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Diagnose CLI availability, sync status, and orphan resources')
+        .option('--json', 'Output machine-readable JSON')
+        .action((opts) => {
+        const cwd = process.cwd();
+        const clis = checkAllClis();
+        const syncRows = checkSyncStatus(cwd);
+        const orphanRows = countOrphans();
+        if (opts.json) {
+            console.log(JSON.stringify({ clis, sync: syncRows, orphans: orphanRows }, null, 2));
+            return;
+        }
+        renderText(clis, syncRows, orphanRows);
+    });
+}

package/dist/commands/drive.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Drive sync commands.
+ *
+ * Registers the `agents drive` command tree for syncing agent session
+ * history across machines via rsync. Supports pull, push, attach
+ * (redirect agent homes to drive), and detach operations.
+ */
 import type { Command } from 'commander';
+/** Register the `agents drive` command tree. */
 export declare function registerDriveCommands(program: Command): void;
-//# sourceMappingURL=drive.d.ts.map

package/dist/commands/drive.js

@@ -1,9 +1,19 @@
+/**
+ * Drive sync commands.
+ *
+ * Registers the `agents drive` command tree for syncing agent session
+ * history across machines via rsync. Supports pull, push, attach
+ * (redirect agent homes to drive), and detach operations.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { setRemote, pull, push, attach, detach, getDriveStatus, } from '../lib/drive-sync.js';
+/** Register the `agents drive` command tree. */
 export function registerDriveCommands(program) {
+    const enabled = isBetaEnabled('drive');
     const driveCmd = program
-        .command('drive')
+        .command('drive', { hidden: !enabled })
         .description('Sync agent session history across machines via rsync. Set up once, then pull/push to keep sessions in sync.')
         .addHelpText('after', `
 Typical workflow:
@@ -24,13 +34,20 @@ Typical workflow:
 Use case: Keep session history consistent across your laptop and desktop,
 or back up sessions to a server you control.
 `);
+    driveCmd.hook('preAction', () => {
+        if (enabled)
+            return;
+        console.error(chalk.red('agents drive is in beta.'));
+        console.error(chalk.gray(betaEnableHint('drive')));
+        process.exit(1);
+    });
     driveCmd
         .command('remote <target>')
         .description('Set the rsync remote target (e.g., user@hostname). Sessions sync to <target>:~/.agents/drive/')
         .addHelpText('after', `
 Examples:
   # Set remote to a server
-  agents drive remote muqsit@spark
+  agents drive remote user@server
 
   # Set remote to a local machine on your network
   agents drive remote macbook.local
@@ -146,6 +163,7 @@ Example:
         }
     });
 }
+/** Format an ISO timestamp as a human-readable relative time (e.g. "5 min ago"). */
 function formatTime(iso) {
     const d = new Date(iso);
     const now = Date.now();
@@ -163,4 +181,3 @@ function formatTime(iso) {
     const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
     return `${months[d.getMonth()]} ${d.getDate()}`;
 }
-//# sourceMappingURL=drive.js.map

package/dist/commands/exec.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Agent execution command.
+ *
+ * Registers the `agents run` command which spawns agent CLIs interactively
+ * or headlessly. Supports profile resolution, version rotation, secrets
+ * injection, and multi-agent fallback chains for rate-limit resilience.
+ */
 import type { Command } from 'commander';
+/** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;
-//# sourceMappingURL=exec.d.ts.map