@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/workflows.js

@@ -0,0 +1,233 @@
+/**
+ * Workflow management library.
+ *
+ * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
+ * They optionally contain subagents/, skills/, and plugins/ subdirectories that
+ * are composed at runtime by `agents run <workflow>`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
+import { listInstalledVersions, getVersionHomePath } from './versions.js';
+/** Agents that support running workflows via `agents run`. */
+export const WORKFLOW_CAPABLE_AGENTS = ['claude'];
+/** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
+export function parseWorkflowFrontmatter(workflowDir) {
+    const workflowMdPath = path.join(workflowDir, 'WORKFLOW.md');
+    if (!fs.existsSync(workflowMdPath))
+        return null;
+    try {
+        const content = fs.readFileSync(workflowMdPath, 'utf-8');
+        const lines = content.split('\n');
+        if (lines[0] !== '---')
+            return null;
+        const endIndex = lines.slice(1).findIndex(l => l === '---');
+        if (endIndex < 0)
+            return null;
+        const frontmatter = lines.slice(1, endIndex + 1).join('\n');
+        const parsed = yaml.parse(frontmatter);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return {
+            name: parsed.name || '',
+            description: parsed.description || '',
+            model: parsed.model,
+            tools: parsed.tools,
+            skills: parsed.skills,
+            mcpServers: parsed.mcpServers,
+            allowedAgents: parsed.allowedAgents,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Count subagent .md files in a workflow's subagents/ directory. */
+export function countWorkflowSubagents(workflowDir) {
+    const subagentsDir = path.join(workflowDir, 'subagents');
+    if (!fs.existsSync(subagentsDir))
+        return 0;
+    try {
+        return fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Discover all workflow directories (those containing WORKFLOW.md) in a local path.
+ * Checks if the path itself is a workflow, then scans a top-level workflows/ subdirectory,
+ * then falls back to scanning all immediate subdirectories.
+ */
+export function discoverWorkflowsFromRepo(repoPath) {
+    const results = [];
+    // The path itself may be a single workflow directory.
+    if (fs.existsSync(path.join(repoPath, 'WORKFLOW.md'))) {
+        const frontmatter = parseWorkflowFrontmatter(repoPath);
+        if (frontmatter) {
+            return [{
+                    name: path.basename(repoPath),
+                    path: repoPath,
+                    frontmatter,
+                    subagentCount: countWorkflowSubagents(repoPath),
+                }];
+        }
+    }
+    // Try a workflows/ subdirectory first, then fall back to scanning root subdirectories.
+    const workflowsSubdir = path.join(repoPath, 'workflows');
+    const scanDir = fs.existsSync(workflowsSubdir) ? workflowsSubdir : repoPath;
+    let entries;
+    try {
+        entries = fs.readdirSync(scanDir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const workflowPath = path.join(scanDir, entry.name);
+        const frontmatter = parseWorkflowFrontmatter(workflowPath);
+        if (frontmatter) {
+            results.push({
+                name: entry.name,
+                path: workflowPath,
+                frontmatter,
+                subagentCount: countWorkflowSubagents(workflowPath),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * List all workflows in central storage.
+ * User layer (~/.agents/workflows/) wins over system (~/.agents-system/workflows/).
+ */
+export function listInstalledWorkflows() {
+    const result = new Map();
+    const extraRepos = getEnabledExtraRepos();
+    const searchDirs = [
+        getUserWorkflowsDir(),
+        getSystemWorkflowsDir(),
+        ...extraRepos.map(r => path.join(r.dir, 'workflows')),
+    ];
+    for (const dir of searchDirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (result.has(entry.name))
+                continue; // Higher-priority layer already present
+            const workflowPath = path.join(dir, entry.name);
+            const frontmatter = parseWorkflowFrontmatter(workflowPath);
+            if (!frontmatter)
+                continue;
+            result.set(entry.name, {
+                name: entry.name,
+                path: workflowPath,
+                frontmatter,
+                subagentCount: countWorkflowSubagents(workflowPath),
+            });
+        }
+    }
+    return result;
+}
+/** Copy a workflow directory into user central storage (~/.agents/workflows/<name>/). */
+export function installWorkflowCentrally(sourcePath, name) {
+    const targetPath = path.join(getUserWorkflowsDir(), name);
+    try {
+        fs.mkdirSync(getUserWorkflowsDir(), { recursive: true });
+        if (fs.existsSync(targetPath)) {
+            fs.rmSync(targetPath, { recursive: true, force: true });
+        }
+        fs.cpSync(sourcePath, targetPath, { recursive: true });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/** Move a workflow from user central storage to trash. */
+export function removeWorkflow(name) {
+    const sourcePath = path.join(getUserWorkflowsDir(), name);
+    if (!fs.existsSync(sourcePath)) {
+        return { success: false, error: `Workflow '${name}' not found in ~/.agents/workflows/` };
+    }
+    try {
+        const trashDir = getTrashWorkflowsDir();
+        fs.mkdirSync(trashDir, { recursive: true });
+        fs.renameSync(sourcePath, path.join(trashDir, `${name}-${Date.now()}`));
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/** List workflow names synced into a specific agent version home (at {versionHome}/workflows/). */
+export function listWorkflowsForAgent(_agent, versionHome) {
+    const workflowsDir = path.join(versionHome, 'workflows');
+    if (!fs.existsSync(workflowsDir))
+        return [];
+    try {
+        return fs.readdirSync(workflowsDir, { withFileTypes: true })
+            .filter(d => d.isDirectory() && fs.existsSync(path.join(workflowsDir, d.name, 'WORKFLOW.md')))
+            .map(d => d.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Copy a workflow directory into a version home at {versionHome}/workflows/<name>/. */
+export function syncWorkflowToVersion(workflowPath, name, _agent, versionHome) {
+    const targetDir = path.join(versionHome, 'workflows', name);
+    try {
+        fs.mkdirSync(path.join(versionHome, 'workflows'), { recursive: true });
+        if (fs.existsSync(targetDir)) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+        }
+        fs.cpSync(workflowPath, targetDir, { recursive: true });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/** Remove a workflow from a specific agent version home. */
+export function removeWorkflowFromVersion(agent, version, name) {
+    const versionHome = getVersionHomePath(agent, version);
+    const targetDir = path.join(versionHome, 'workflows', name);
+    if (!fs.existsSync(targetDir)) {
+        return { success: false, error: `Workflow '${name}' not synced to ${agent}@${version}` };
+    }
+    try {
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/** Iterate all installed (agent, version) pairs that support workflows. */
+export function iterWorkflowsCapableVersions(filter) {
+    const result = [];
+    for (const agentId of WORKFLOW_CAPABLE_AGENTS) {
+        if (filter?.agent && filter.agent !== agentId)
+            continue;
+        const versions = listInstalledVersions(agentId);
+        for (const version of versions) {
+            if (filter?.version && filter.version !== version)
+                continue;
+            result.push({ agent: agentId, version });
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",
@@ -66,9 +66,7 @@
     "node": ">=22.5.0"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "3.1033.0",
     "@inquirer/prompts": "^7.0.0",
-    "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/proper-lockfile": "^4.1.4",
     "@xterm/headless": "^6.0.0",
     "@zed-industries/agent-client-protocol": "^0.4.5",
@@ -81,7 +79,6 @@
     "node-pty": "1.1.0",
     "ora": "^8.1.0",
     "proper-lockfile": "^4.1.2",
-    "semver": "^7.6.0",
     "simple-git": "3.36.0",
     "smol-toml": "^1.6.1",
     "yaml": "^2.8.3"
@@ -90,7 +87,6 @@
     "@types/diff": "^6.0.0",
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^22.0.0",
-    "@types/semver": "^7.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"

package/scripts/postinstall.js

@@ -9,7 +9,7 @@ import * as os from 'os';
 import * as readline from 'readline';
 
 const HOME = os.homedir();
-const SHIMS_DIR = path.join(HOME, '.agents-system', 'shims');
+const SHIMS_DIR = path.join(HOME, '.agents', '.cache', 'shims');
 const SYSTEM_DIR = path.join(HOME, '.agents-system');
 const USER_DIR = path.join(HOME, '.agents');
 
@@ -20,7 +20,7 @@ if (!isGlobalInstall) {
   fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
   console.log(`
 agents-cli installed locally.
-To complete setup, run: npx agents init
+To complete setup, run: npx agents setup
 `);
   process.exit(0);
 }
@@ -111,7 +111,8 @@ const exportLine = shellName === 'fish'
   ? `fish_add_path ${SHIMS_DIR}`
   : `export PATH="${SHIMS_DIR}:$PATH"`;
 
-const ALIASES = ['sessions', 'teams'];
+// Shorthands that delegate to `agents <name>` — written unconditionally on install.
+const ALIASES = ['sessions', 'secrets', 'browser', 'pty', 'teams'];
 
 function writeAliasShims() {
   const written = [];
@@ -124,6 +125,27 @@ function writeAliasShims() {
   return written;
 }
 
+function getVersion() {
+  const pkgPath = new URL('../package.json', import.meta.url).pathname;
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+  } catch { return null; }
+}
+
+function getChangelogSection(version) {
+  const changelogPath = new URL('../CHANGELOG.md', import.meta.url).pathname;
+  if (!fs.existsSync(changelogPath)) return null;
+  const lines = fs.readFileSync(changelogPath, 'utf-8').split('\n');
+  let inSection = false;
+  const section = [];
+  for (const line of lines) {
+    if (line.startsWith(`## ${version}`)) { inSection = true; continue; }
+    if (inSection && line.startsWith('## ')) break;
+    if (inSection) section.push(line);
+  }
+  return section.length ? section.join('\n').trim() : null;
+}
+
 function ask(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -134,33 +156,18 @@ function ask(question) {
   });
 }
 
-async function promptForAliases() {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return 'skip';
-  console.log(`
-Install bare-command aliases for common subcommands?
-This creates ${ALIASES.map((n) => `\`${n}\``).join(', ')} as wrappers in ${SHIMS_DIR}
-so you can type \`sessions\` instead of \`agents sessions\`.
-
-  1) Let's do it
-  2) Skip this time
-  3) I'll do it manually if needed
-`);
-  const answer = await ask('Choose [1/2/3] (default 1): ');
-  if (answer === '' || answer === '1') return 'install';
-  if (answer === '3') return 'manual';
-  return 'skip';
+function isAlreadyConfigured(rcFile) {
+  if (!fs.existsSync(rcFile)) return false;
+  const content = fs.readFileSync(rcFile, 'utf-8');
+  // Accept either the new path or the legacy ~/.agents-system/shims path
+  return content.includes('.agents/.cache/shims') || content.includes('.agents-system/shims');
 }
 
 async function main() {
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
   if (process.env.AGENTS_INIT_SHELL === '1') {
     const rcFile = getShellRc();
-    let alreadyConfigured = false;
-    if (fs.existsSync(rcFile)) {
-      const content = fs.readFileSync(rcFile, 'utf-8');
-      alreadyConfigured = content.includes('.agents-system/shims');
-    }
-    if (!alreadyConfigured) {
+    if (!isAlreadyConfigured(rcFile)) {
       const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;
       fs.mkdirSync(path.dirname(rcFile), { recursive: true });
       fs.appendFileSync(rcFile, addition);
@@ -169,53 +176,47 @@ async function main() {
     }
     writeAliasShims();
     console.log(`  Installed bare-command aliases: ${ALIASES.join(', ')}\n`);
-    return;
-  }
-
-  // Default: offer to auto-add shims to PATH (like homebrew does)
-  const rcFile = getShellRc();
-  let alreadyConfigured = false;
-  if (fs.existsSync(rcFile)) {
-    const content = fs.readFileSync(rcFile, 'utf-8');
-    alreadyConfigured = content.includes('.agents-system/shims');
-  }
-
-  console.log(`\nagents-cli installed.`);
+  } else {
+    // Default: offer to auto-add shims to PATH (like homebrew does)
+    const rcFile = getShellRc();
 
-  if (!alreadyConfigured && process.stdin.isTTY && process.stdout.isTTY) {
-    const answer = await ask(`\nAdd shims to PATH in ~/${path.basename(rcFile)}? [Y/n] `);
-    if (answer === '' || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
-      const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;
-      fs.mkdirSync(path.dirname(rcFile), { recursive: true });
-      fs.appendFileSync(rcFile, addition);
-      console.log(`\n  Added ${SHIMS_DIR} to PATH in ${path.basename(rcFile)}`);
-      console.log(`  Restart your shell or run: source ~/${path.basename(rcFile)}\n`);
-    } else {
-      console.log(`
+    console.log(`\nagents-cli installed.`);
+
+    if (!isAlreadyConfigured(rcFile) && process.stdin.isTTY && process.stdout.isTTY) {
+      const answer = await ask(`\nAdd shims to PATH in ~/${path.basename(rcFile)}? [Y/n] `);
+      if (answer === '' || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+        const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;
+        fs.mkdirSync(path.dirname(rcFile), { recursive: true });
+        fs.appendFileSync(rcFile, addition);
+        console.log(`\n  Added ${SHIMS_DIR} to PATH in ${path.basename(rcFile)}`);
+        console.log(`  Restart your shell or run: source ~/${path.basename(rcFile)}\n`);
+      } else {
+        console.log(`
 To enable version-aware shims, add this to your shell config:
 
   ${exportLine}
 `);
-    }
-  } else if (!alreadyConfigured) {
-    console.log(`
+      }
+    } else if (!isAlreadyConfigured(rcFile)) {
+      console.log(`
 To enable version-aware shims, add this to your shell config:
 
   ${exportLine}
 `);
-  }
+    }
 
-  const choice = await promptForAliases();
-  if (choice === 'install') {
     const written = writeAliasShims();
-    console.log(`\n  Installed aliases: ${written.join(', ')} (in ${SHIMS_DIR})`);
-    console.log(`  Make sure ${SHIMS_DIR} is on your PATH (see above).\n`);
-  } else if (choice === 'manual') {
-    console.log(`\n  To add aliases later, drop these in a directory on your PATH:`);
-    for (const name of ALIASES) {
-      console.log(`    ${name} -> exec agents ${name} "$@"`);
+    console.log(`  Installed shorthands: ${written.join(', ')}`);
+  }
+
+  const version = getVersion();
+  if (version) {
+    const section = getChangelogSection(version);
+    if (section) {
+      console.log(`\nWhat's new in ${version}:\n`);
+      console.log(section);
+      console.log('');
     }
-    console.log('');
   }
 }
 

package/dist/commands/fork.d.ts

@@ -1,10 +0,0 @@
-/**
- * Repository fork command.
- *
- * Registers the `agents fork` command which forks the default system
- * config repo to the user's GitHub account, reconfigures remotes
- * (origin -> user fork, upstream -> system repo), and pushes.
- */
-import type { Command } from 'commander';
-/** Register the `agents fork` command. */
-export declare function registerForkCommand(program: Command): void;

package/dist/commands/fork.js

@@ -1,146 +0,0 @@
-/**
- * Repository fork command.
- *
- * Registers the `agents fork` command which forks the default system
- * config repo to the user's GitHub account, reconfigures remotes
- * (origin -> user fork, upstream -> system repo), and pushes.
- */
-import chalk from 'chalk';
-import ora from 'ora';
-import { getAgentsDir, ensureAgentsDir } from '../lib/state.js';
-import { isGitRepo, isSystemRepoOrigin, getGitHubUsername, hasLocalChanges, setUpstreamRemote, setRemoteUrl, getRemoteUrl, } from '../lib/git.js';
-import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
-import { isPromptCancelled } from './utils.js';
-/** Register the `agents fork` command. */
-export function registerForkCommand(program) {
-    program
-        .command('fork')
-        .description('Copy the default config repo to your own GitHub so you can push changes. Runs once after init.')
-        .addHelpText('after', `
-Examples:
-  # Fork the default repo to your GitHub account
-  agents fork
-
-When to use:
-  - You initialized with 'agents init' using the default config
-  - You've customized commands, skills, or settings
-  - You want to save your changes to your own GitHub repo
-
-What it does:
-  1. Creates a fork of the default repo under your GitHub account (gh:yourname/.agents)
-  2. Reconfigures remotes: origin -> your fork, upstream -> default repo
-  3. Commits any local changes you've made
-  4. Pushes everything to your new fork
-
-After forking:
-  - 'agents push' sends your changes to your fork
-  - 'agents pull --upstream' pulls updates from the default repo
-
-Requirements:
-  - GitHub CLI authenticated (run 'gh auth login' if needed)
-  - ~/.agents/ must be tracking the default repo (not already forked)
-`)
-        .action(async () => {
-        try {
-            const agentsDir = getAgentsDir();
-            ensureAgentsDir();
-            // Check if ~/.agents/ is a git repo
-            if (!isGitRepo(agentsDir)) {
-                console.log(chalk.yellow('~/.agents/ is not a git repository.'));
-                console.log(chalk.gray('\nInitialize first:'));
-                console.log(chalk.cyan('  agents pull'));
-                return;
-            }
-            // Check if already forked (origin is not system repo)
-            if (!await isSystemRepoOrigin(agentsDir)) {
-                const currentOrigin = await getRemoteUrl(agentsDir);
-                console.log(chalk.green('Already forked!'));
-                console.log(chalk.gray(`\nOrigin: ${currentOrigin}`));
-                console.log(chalk.gray('\nTo push your changes:'));
-                console.log(chalk.cyan('  agents push'));
-                console.log(chalk.gray('\nTo pull updates from system repo:'));
-                console.log(chalk.cyan('  agents pull --upstream'));
-                return;
-            }
-            // Get GitHub username
-            const spinner = ora('Checking GitHub...').start();
-            const username = await getGitHubUsername();
-            if (!username) {
-                spinner.fail('GitHub CLI not authenticated');
-                console.log(chalk.gray('\nTo authenticate:'));
-                console.log(chalk.cyan('  gh auth login'));
-                return;
-            }
-            spinner.succeed(`Logged in as ${username}`);
-            // Fork the system repo
-            const forkSpinner = ora('Forking system repo...').start();
-            const { execFile } = await import('child_process');
-            const { promisify } = await import('util');
-            const execFileAsync = promisify(execFile);
-            const repoSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO);
-            try {
-                // gh repo fork creates a fork and optionally clones it
-                // We just want to create the fork on GitHub, not clone
-                await execFileAsync('gh', ['repo', 'fork', repoSlug, '--clone=false']);
-                forkSpinner.succeed(`Forked to ${username}/.agents`);
-            }
-            catch (err) {
-                const errorMsg = err.message;
-                // Check if fork already exists
-                if (errorMsg.includes('already exists') || errorMsg.includes('409')) {
-                    forkSpinner.info(`Fork ${username}/.agents already exists`);
-                }
-                else {
-                    forkSpinner.fail(`Failed to fork: ${errorMsg}`);
-                    return;
-                }
-            }
-            // Reconfigure remotes
-            const remoteSpinner = ora('Reconfiguring remotes...').start();
-            // Set current origin as upstream
-            await setUpstreamRemote(agentsDir, `https://github.com/${repoSlug}.git`);
-            // Set user's fork as new origin
-            await setRemoteUrl(agentsDir, `https://github.com/${username}/.agents.git`);
-            remoteSpinner.succeed('Reconfigured remotes');
-            console.log(chalk.gray(`  origin   -> ${username}/.agents`));
-            console.log(chalk.gray(`  upstream -> ${repoSlug}`));
-            // Commit any local changes
-            if (await hasLocalChanges(agentsDir)) {
-                const commitSpinner = ora('Committing local changes...').start();
-                const simpleGit = (await import('simple-git')).default;
-                const git = simpleGit(agentsDir);
-                await git.add('-A');
-                await git.commit('Local changes before fork');
-                commitSpinner.succeed('Committed local changes');
-            }
-            // Push to new origin
-            const pushSpinner = ora('Pushing to your fork...').start();
-            try {
-                const simpleGit = (await import('simple-git')).default;
-                const git = simpleGit(agentsDir);
-                await git.push('origin', 'main', ['--set-upstream']);
-                pushSpinner.succeed('Pushed to your fork');
-            }
-            catch (err) {
-                pushSpinner.fail(`Push failed: ${err.message}`);
-                console.log(chalk.yellow('\nYou can push manually later:'));
-                console.log(chalk.cyan('  agents push'));
-                return;
-            }
-            console.log(chalk.green('\nFork complete!'));
-            console.log(chalk.gray(`\nView: https://github.com/${username}/.agents`));
-            console.log(chalk.gray('\nTo push future changes:'));
-            console.log(chalk.cyan('  agents push'));
-            console.log(chalk.gray('\nTo pull updates from system repo:'));
-            console.log(chalk.cyan('  agents pull --upstream'));
-        }
-        catch (err) {
-            if (isPromptCancelled(err)) {
-                console.log(chalk.yellow('\nCancelled'));
-                process.exit(0);
-            }
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-}