@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/pull.js

@@ -1,10 +1,16 @@
+/**
+ * Config pull command.
+ *
+ * Registers the `agents pull` command which clones or updates the
+ * system ~/.agents-system/ git repo and syncs CLI versions, MCP servers,
+ * resources, and hooks to installed agent versions.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
 import { AGENTS, ALL_AGENT_IDS, HOOKS_CAPABLE_AGENTS, MCP_CAPABLE_AGENTS, getAllCliStates, registerMcpToTargets, isAgentName, resolveAgentName, agentLabel, } from '../lib/agents.js';
 import { readManifest, MANIFEST_FILENAME, } from '../lib/manifest.js';
-import { getAgentsDir, ensureAgentsDir, readMeta, updateMeta, } from '../lib/state.js';
-import { DEFAULT_SYSTEM_REPO, LEGACY_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
-import { isGitRepo, cloneIntoExisting, pullRepo, pullFromUpstream, parseSource, getGitHubUsername, checkGitHubRepoExists, hasUpstreamRemote, getUpstreamUrl, } from '../lib/git.js';
+import { getUserAgentsDir, ensureAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
+import { isGitRepo, pullRepo, isSystemRepoOrigin, } from '../lib/git.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
@@ -14,7 +20,7 @@ import { select } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
  * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
- * The new layout is ~/.agents/promptcuts.yaml at the repo root — the hook
+ * The new layout is ~/.agents-system/promptcuts.yaml at the repo root — the hook
  * reads from a fixed path so it survives version upgrades. If the root file
  * doesn't exist yet but an agent-scoped one does, hoist the first one found.
  */
@@ -37,24 +43,18 @@ function migratePromptcutsToRoot(agentsDir) {
         }
     }
 }
+/** Register the `agents pull` command. */
 export function registerPullCommand(program) {
     program
-        .command('pull [source] [agent]')
-        .description('Sync your config from a git repo. Clones on first run, pulls updates thereafter.')
+        .command('pull [agent]')
+        .description('Pull your user repo at ~/.agents/ and refresh installed agent versions.')
         .option('-y, --yes', 'Auto-sync all resources without prompting')
         .option('--skip-clis', 'Pull config changes but do not install or upgrade agent CLIs')
-        .option('--upstream', 'Pull from the upstream remote instead of origin (for forked repos)')
         .addHelpText('after', `
 Examples:
-  # First time: clone from your repo (also works if ~/.agents/ is empty)
-  agents pull gh:yourname/.agents
-
-  # Update your config from origin (GitHub)
+  # First time: clone the system repo into ~/.agents-system/
   agents pull
 
-  # Pull updates from the upstream default repo (after you've forked)
-  agents pull --upstream
-
   # Sync only one agent's config
   agents pull claude
 
@@ -62,9 +62,8 @@ Examples:
   agents pull -y
 
 When to use:
-  - Initial setup: clone your config repo to a new machine
-  - Daily sync: pull changes you or teammates pushed to the repo
-  - Upstream updates: get new skills, commands, or MCP servers from the default repo
+  - Initial setup: clone the system repo to a new machine
+  - Daily sync: pull the latest system skills, commands, or MCP servers
   - Per-agent: sync just one agent's config without touching others
 
 What it syncs:
@@ -76,102 +75,44 @@ What it syncs:
 
 Skip CLI installs with --skip-clis when you only want config updates, not version changes.
 `)
-        .action(async (arg1, arg2, options) => {
+        .action(async (arg1, options) => {
+        // Deprecation banner — `agents pull` is on its way out. agents-cli now
+        // auto-syncs the system repo in the background and surfaces upstream
+        // changes for user/extra repos as one-line notices. Repo lifecycle is
+        // managed under `agents repo`. We keep this command functional today
+        // because `agents init` still invokes it for first-time setup; once
+        // init is refactored to call the bootstrap helpers directly, this
+        // command will hard-error like `agents memory` does.
+        if (!options.yes && process.argv[2] === 'pull') {
+            process.stderr.write('agents-cli: "agents pull" is deprecated.\n' +
+                '            First-time setup:  agents init\n' +
+                '            Force a sync now:  agents repo pull\n' +
+                '            Push your repo:    agents repo push\n\n');
+        }
         const skipPrompts = options.yes || !isInteractiveTerminal();
-        // Parse source and agent filter from positional args
-        let targetSource;
         let agentFilter;
         if (arg1) {
             if (isAgentName(arg1)) {
-                // agents pull claude
                 agentFilter = resolveAgentName(arg1);
             }
             else {
-                // agents pull gh:user/repo [agent]
-                targetSource = arg1;
-                if (arg2 && isAgentName(arg2)) {
-                    agentFilter = resolveAgentName(arg2);
-                }
-            }
-        }
-        const agentsDir = getAgentsDir();
-        ensureAgentsDir();
-        // Handle --upstream: pull from upstream remote
-        if (options.upstream) {
-            if (!isGitRepo(agentsDir)) {
-                console.log(chalk.red('~/.agents/ is not a git repository.'));
-                console.log(chalk.gray('\nInitialize first: agents pull'));
+                console.log(chalk.red(`Invalid agent: ${arg1}`));
+                console.log(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
                 return;
             }
-            if (!await hasUpstreamRemote(agentsDir)) {
-                console.log(chalk.red('No upstream remote configured.'));
-                console.log(chalk.gray('\nIf you forked from the system repo, run: agents fork'));
-                console.log(chalk.gray('This will set up the upstream remote automatically.'));
-                return;
-            }
-            // Migration nudge: one-time notice if upstream still points at the legacy personal repo.
-            const legacySlug = systemRepoSlug(LEGACY_SYSTEM_REPO).toLowerCase();
-            const currentSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO);
-            const nudgeMarker = path.join(agentsDir, '.migration-nudge-shown');
-            const upstreamUrl = await getUpstreamUrl(agentsDir);
-            if (upstreamUrl && upstreamUrl.toLowerCase().includes(legacySlug) && !fs.existsSync(nudgeMarker)) {
-                console.log(chalk.yellow(`\nYour upstream points at a personal repo (${legacySlug}).`));
-                console.log(chalk.yellow(`The curated upstream is now ${currentSlug}.`));
-                console.log(chalk.gray('To switch:'));
-                console.log(chalk.cyan(`  cd ~/.agents && git remote set-url upstream git@github.com:${currentSlug}.git\n`));
-                try {
-                    fs.writeFileSync(nudgeMarker, new Date().toISOString() + '\n');
-                }
-                catch { /* best-effort */ }
-            }
-            const spinner = ora('Pulling from upstream...').start();
-            const result = await pullFromUpstream(agentsDir);
-            if (!result.success) {
-                spinner.fail(`Failed: ${result.error}`);
-                return;
-            }
-            spinner.succeed(`Merged upstream changes (${result.commit})`);
-            // Continue with the rest of the sync (CLI versions, MCP, resources)
-            // Skip the source determination since we already pulled
-            targetSource = 'existing';
-        }
-        // Determine source
-        const meta = readMeta();
-        if (!targetSource) {
-            // Check if ~/.agents/ is already a git repo
-            if (isGitRepo(agentsDir)) {
-                targetSource = 'existing';
-            }
-            else {
-                // Try to infer from GitHub username
-                const spinner = ora('Checking GitHub...').start();
-                const username = await getGitHubUsername();
-                if (username) {
-                    const repoExists = await checkGitHubRepoExists(username, '.agents');
-                    if (repoExists) {
-                        targetSource = `gh:${username}/.agents`;
-                        spinner.succeed(`Found ${username}/.agents`);
-                    }
-                    else {
-                        spinner.info(`No .agents repo found for ${username}`);
-                        console.log(chalk.gray('\nTo create one:'));
-                        console.log(chalk.cyan('  gh repo create .agents --public'));
-                        console.log(chalk.gray('\nThen run: agents pull'));
-                        return;
-                    }
-                }
-                else {
-                    // Fall back to system default repo
-                    targetSource = DEFAULT_SYSTEM_REPO;
-                    spinner.info(`Using default: ${DEFAULT_SYSTEM_REPO}`);
-                }
-            }
         }
+        const agentsDir = getUserAgentsDir();
+        ensureAgentsDir();
         const spinner = ora('Syncing...').start();
         try {
-            let commit;
-            if (targetSource === 'existing') {
-                // Just pull updates
+            let commit = '';
+            if (isGitRepo(agentsDir)) {
+                // Don't pull if the remote is the system repo — that's a misconfiguration
+                if (await isSystemRepoOrigin(agentsDir)) {
+                    spinner.fail('~/.agents/ is pointing at the system repo. Use a personal repo instead.');
+                    console.log(chalk.gray('\nCreate your own repo: agents repo init'));
+                    return;
+                }
                 spinner.text = 'Pulling updates...';
                 const result = await pullRepo(agentsDir);
                 if (!result.success) {
@@ -182,38 +123,28 @@ Skip CLI installs with --skip-clis when you only want config updates, not versio
                 spinner.succeed(`Updated to ${commit}`);
             }
             else {
-                // Clone or update
-                const parsed = parseSource(targetSource);
-                if (isGitRepo(agentsDir)) {
-                    // Already a repo, just pull
-                    spinner.text = 'Pulling updates...';
-                    const result = await pullRepo(agentsDir);
-                    if (!result.success) {
-                        spinner.fail(`Pull failed: ${result.error}`);
-                        return;
+                // ~/.agents/ is not a git repo yet — skip git pull, proceed with local resource sync
+                spinner.succeed('Using local ~/.agents/ (no remote configured)');
+            }
+            // Pull extra DotAgent repos before resource sync so any new skills /
+            // commands they ship land in the version homes on this same run.
+            const extraRepos = getEnabledExtraRepos();
+            if (extraRepos.length > 0) {
+                console.log(chalk.bold(`\nExtra repos (${extraRepos.length}):\n`));
+                for (const { alias, dir } of extraRepos) {
+                    const extraSpinner = ora(`Pulling ${alias}...`).start();
+                    const result = await pullRepo(dir);
+                    if (result.success) {
+                        extraSpinner.succeed(`${alias} -> ${result.commit}`);
                     }
-                    commit = result.commit;
-                    spinner.succeed(`Updated to ${commit}`);
-                }
-                else {
-                    // Clone into existing ~/.agents/
-                    spinner.text = `Cloning ${targetSource}...`;
-                    const result = await cloneIntoExisting(targetSource, agentsDir);
-                    if (!result.success) {
-                        spinner.fail(`Clone failed: ${result.error}`);
-                        return;
+                    else {
+                        extraSpinner.warn(`${alias}: ${result.error}`);
                     }
-                    commit = result.commit;
-                    spinner.succeed(`Initialized from ${targetSource}`);
                 }
-                // Save source to meta
-                updateMeta({
-                    source: parsed.url,
-                });
             }
             // One-time migration: promptcuts.yaml moved from agent-scoped
             // (e.g. claude/promptcuts.yaml) to repo root. We move it so the
-            // hook at ~/.agents/hooks/ can always find it at a fixed path.
+            // hook at ~/.agents-system/hooks/ can always find it at a fixed path.
             migratePromptcutsToRoot(agentsDir);
             // Read manifest for CLI versions and MCP config
             const manifest = readManifest(agentsDir);
@@ -445,4 +376,3 @@ Skip CLI installs with --skip-clis when you only want config updates, not versio
         }
     });
 }
-//# sourceMappingURL=pull.js.map

package/dist/commands/refresh-memory.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Internal memory refresh command.
+ *
+ * Registers the hidden `agents refresh-memory` command invoked by
+ * shims for agents that do not natively resolve @-imports in their
+ * memory file. Recompiles memory only when source files have changed.
+ */
 import { Command } from 'commander';
 /**
  * Hidden command invoked by shims for agents that don't natively resolve
@@ -6,4 +13,3 @@ import { Command } from 'commander';
  * sync. Typical cost: 10-20ms when memory is fresh.
  */
 export declare function registerRefreshMemoryCommand(program: Command): void;
-//# sourceMappingURL=refresh-memory.d.ts.map

package/dist/commands/refresh-memory.js

@@ -1,3 +1,10 @@
+/**
+ * Internal memory refresh command.
+ *
+ * Registers the hidden `agents refresh-memory` command invoked by
+ * shims for agents that do not natively resolve @-imports in their
+ * memory file. Recompiles memory only when source files have changed.
+ */
 import chalk from 'chalk';
 import { AGENTS } from '../lib/agents.js';
 import { isVersionInstalled } from '../lib/versions.js';
@@ -42,4 +49,3 @@ export function registerRefreshMemoryCommand(program) {
         }
     });
 }
-//# sourceMappingURL=refresh-memory.js.map

package/dist/commands/repo.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extra DotAgent repo management.
+ *
+ * Registers `agents repo add|init|list|remove|enable|disable` which manage
+ * additional DotAgent repos alongside the primary ~/.agents-system/ repo so
+ * private, work, or team skills can ship separately from public ones.
+ *
+ * Extras are user-level config: managed clones live at ~/.agents-<alias>/ as
+ * peer dirs to ~/.agents/, and user-owned repos may live anywhere. All extras
+ * are registered in meta.extraRepos. Sync functions merge their resources into
+ * agent version homes after the user repo's (user-wins on name collisions).
+ */
+import type { Command } from 'commander';
+/** Register the `agents repo` command tree. */
+export declare function registerRepoCommands(program: Command): void;