@agentworkforce/cli 0.6.1 → 0.8.0

package/dist/cli.js

@@ -1,18 +1,31 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, routingProfiles, useSelection } from '@agentworkforce/workload-router';
-import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
+import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
 import { launchOnMount } from '@relayfile/local-mount';
 import ora from 'ora';
-import { buildPersonaSourceDirectories, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
+import { buildPersonaSourceDirectories, defaultCwdPersonaDir, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
+import { installPersonas } from './persona-install.js';
 const USAGE = `Usage: agentworkforce <command> [args...]
 
 Commands:
+  create [flags]     Opens persona-maker@best for creating a new
+                      persona, with target path passed as persona inputs.
+                      Flags:
+                        --to <target>       Storage target: cwd, user, dir:n,
+                                            library, or an explicit path.
+                                            Default: cwd when
+                                            .agentworkforce/workforce exists,
+                                            otherwise config defaultCreateTarget,
+                                            otherwise user.
+                        --save-default      Persist --to as defaultCreateTarget in
+                                            ~/.agentworkforce/workforce/config.json.
+                        --install-in-repo   Same behavior as agent.
   agent [flags] <persona>[@<tier>]
                       Run a persona. Tier one of: ${PERSONA_TIERS.join(' | ')}
                       (default: best-value). Drops into an interactive harness
@@ -55,6 +68,13 @@ Commands:
                       or --all to see every tier. Flags:
                         --all         include every tier (overrides default)
                         --json        emit the resolved PersonaSpec as JSON
+  install [flags] <pkg|path>
+                      Copy persona JSON files from an npm package or local
+                      package directory into
+                      <cwd>/.agentworkforce/workforce/personas/. Flags:
+                        --persona <id>  install only the matching persona id;
+                                        repeat to install multiple
+                        --overwrite     replace existing target files
   sources list [--json]
                       List persona source directories in cascade order.
   sources add <dir> [--position <n>]
@@ -66,6 +86,10 @@ Commands:
   harness check       Probe which harnesses (claude, codex, opencode) are
                       installed and runnable on this machine.
 
+Options:
+  -h, --help          Show this help text.
+  -v, --version       Print the agentworkforce version.
+
 Local personas cascade: <cwd>/.agentworkforce/workforce/personas/*.json → configured persona dirs → repo library.
 Each layer only needs to specify fields it overrides; everything else inherits
 from the next lower layer. "extends" explicitly names a base; omit it and the
@@ -73,11 +97,15 @@ loader implicitly inherits from the same-id persona below. By default the only
 configured persona dir is ~/.agentworkforce/workforce/personas.
 
 Examples:
+  agentworkforce create
+  agentworkforce create --to user
   agentworkforce agent npm-provenance-publisher@best
   agentworkforce agent my-posthog@best
   agentworkforce agent review@best-value
   agentworkforce list
   agentworkforce show posthog
+  agentworkforce install @agentrelay/personas --persona relay-orchestrator
+  agentworkforce install ./local-personas --overwrite
   agentworkforce sources list
   agentworkforce sources add ../my-personas --position 1
   agentworkforce harness check
@@ -88,6 +116,17 @@ function die(msg, withUsage = true) {
         process.stderr.write(`\n${USAGE}`);
     process.exit(1);
 }
+function readPackageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    if (typeof pkg.version !== 'string' || !pkg.version) {
+        throw new Error('Could not read @agentworkforce/cli package version.');
+    }
+    return pkg.version;
+}
+export const CLI_VERSION = readPackageVersion();
+export const CREATE_SELECTOR = 'persona-maker@best';
+const CREATE_INPUT_TARGET_DIR = 'TARGET_DIR';
+const CREATE_INPUT_CREATE_MODE = 'CREATE_MODE';
 const local = loadLocalPersonas();
 for (const warning of local.warnings) {
     process.stderr.write(`warning: ${warning}\n`);
@@ -154,6 +193,7 @@ function buildSelection(spec, tier, kind) {
         runtime,
         skills: spec.skills,
         rationale: kind === 'local' ? `local-override: ${spec.id}` : `cli-tier-override: ${tier}`,
+        ...(spec.inputs ? { inputs: spec.inputs } : {}),
         ...(spec.env ? { env: spec.env } : {}),
         ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
         ...(spec.permissions ? { permissions: spec.permissions } : {})
@@ -443,7 +483,16 @@ export function decideCleanMode(harness, installInRepo = false) {
     return { useClean: false };
 }
 async function runInteractive(selection, options = {}) {
-    const { runtime, personaId, tier } = selection;
+    const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
+    const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
+    const effectiveSelection = {
+        ...selection,
+        runtime: {
+            ...selection.runtime,
+            systemPrompt: renderedSystemPrompt
+        }
+    };
+    const { runtime, personaId, tier } = effectiveSelection;
     // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
     // claude-only; the workload-router SDK throws if it's set for other
     // harnesses. For opencode, we instead keep installs out of the repo by
@@ -459,13 +508,17 @@ async function runInteractive(selection, options = {}) {
     const installRoot = sessionRoot && runtime.harness === 'claude'
         ? sessionInstallRoot(sessionRoot)
         : undefined;
-    const ctx = useSelection(selection, installRoot !== undefined ? { installRoot } : {});
+    const ctx = useSelection(effectiveSelection, installRoot !== undefined ? { installRoot } : {});
     const { install } = ctx;
     process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model})\n`);
-    const envResolution = resolveStringMapLenient(selection.env, process.env, 'env');
-    const mcpResolution = resolveMcpServersLenient(selection.mcpServers, process.env);
+    const inputEnv = inputResolution.values;
+    const callerEnv = { ...process.env, ...inputEnv };
+    const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
+    const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
     emitDropWarnings(formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers));
-    const resolvedEnv = envResolution.value;
+    const resolvedEnv = Object.keys(inputEnv).length > 0 || envResolution.value
+        ? { ...(envResolution.value ?? {}), ...inputEnv }
+        : undefined;
     const resolvedMcp = mcpResolution.servers;
     // In session mode the install command is never `:` — it at minimum runs
     // the plugin scaffold (mkdir + manifest + symlink) so `--plugin-dir` has a
@@ -489,7 +542,7 @@ async function runInteractive(selection, options = {}) {
         model: runtime.model,
         systemPrompt: runtime.systemPrompt,
         mcpServers: resolvedMcp,
-        permissions: selection.permissions,
+        permissions: effectiveSelection.permissions,
         ...(installRoot !== undefined ? { pluginDirs: [installRoot] } : {})
     });
     for (const w of spec.warnings)
@@ -524,14 +577,14 @@ async function runInteractive(selection, options = {}) {
     if (runtime.harness === 'claude') {
         const servers = Object.keys(resolvedMcp ?? {});
         summary.push(`mcp-strict=${servers.length ? servers.join(',') : '(none)'}`);
-        if (selection.permissions?.allow?.length) {
-            summary.push(`allow=${selection.permissions.allow.length} rule(s)`);
+        if (effectiveSelection.permissions?.allow?.length) {
+            summary.push(`allow=${effectiveSelection.permissions.allow.length} rule(s)`);
         }
-        if (selection.permissions?.deny?.length) {
-            summary.push(`deny=${selection.permissions.deny.length} rule(s)`);
+        if (effectiveSelection.permissions?.deny?.length) {
+            summary.push(`deny=${effectiveSelection.permissions.deny.length} rule(s)`);
         }
-        if (selection.permissions?.mode) {
-            summary.push(`mode=${selection.permissions.mode}`);
+        if (effectiveSelection.permissions?.mode) {
+            summary.push(`mode=${effectiveSelection.permissions.mode}`);
         }
     }
     if (spec.initialPrompt)
@@ -802,9 +855,14 @@ function collectSourceDirRows() {
         exists: 'yes',
         dir: '(built-in)'
     });
-    return { configPath: config.configPath, personaDirs: config.personaDirs, rows };
+    return {
+        configPath: config.configPath,
+        personaDirs: config.personaDirs,
+        ...(config.defaultCreateTarget ? { defaultCreateTarget: config.defaultCreateTarget } : {}),
+        rows
+    };
 }
-function formatSourcesTable(rows, configPath) {
+function formatSourcesTable(rows, configPath, defaultCreateTarget) {
     const headers = {
         cascade: 'CASCADE',
         config: 'CONFIG',
@@ -817,6 +875,7 @@ function formatSourcesTable(rows, configPath) {
     const line = (row) => cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
     return [
         `Config: ${configPath}`,
+        `Default create target: ${defaultCreateTarget ?? '(auto)'}`,
         [line(headers), ...rows.map(line)].join('\n'),
         ''
     ].join('\n');
@@ -839,12 +898,12 @@ function parseSourcesListArgs(args) {
 }
 function runSourcesList(args) {
     const { json } = parseSourcesListArgs(args);
-    const { configPath, personaDirs, rows } = collectSourceDirRows();
+    const { configPath, personaDirs, defaultCreateTarget, rows } = collectSourceDirRows();
     if (json) {
-        process.stdout.write(JSON.stringify({ configPath, personaDirs, sources: rows }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ configPath, personaDirs, defaultCreateTarget, sources: rows }, null, 2) + '\n');
     }
     else {
-        process.stdout.write(formatSourcesTable(rows, configPath));
+        process.stdout.write(formatSourcesTable(rows, configPath, defaultCreateTarget));
     }
     process.exit(0);
 }
@@ -977,6 +1036,86 @@ function runSources(args) {
         runSourcesRemove(rest);
     die(`sources: unknown action "${action}". Expected: list, add, remove.`);
 }
+export function parseInstallArgs(args) {
+    let source;
+    const personaIds = [];
+    let overwrite = false;
+    const valueOf = (i, flag) => {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith('--')) {
+            throw new Error(`install: ${flag} requires a value.`);
+        }
+        return v;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--overwrite') {
+            overwrite = true;
+        }
+        else if (arg === '--persona') {
+            const value = valueOf(i++, arg);
+            if (!value.trim())
+                throw new Error('install: --persona requires a non-empty value.');
+            personaIds.push(value);
+        }
+        else if (arg.startsWith('--')) {
+            throw new Error(`install: unexpected flag "${arg}".`);
+        }
+        else if (source === undefined) {
+            source = arg;
+        }
+        else {
+            throw new Error(`install: unexpected argument "${arg}".`);
+        }
+    }
+    if (!source)
+        throw new Error('install: missing package or local path.');
+    return { source, personaIds, overwrite };
+}
+function formatPersonaInstallSummary(result) {
+    const lines = [];
+    for (const persona of result.installed) {
+        lines.push(`installed ${persona.id} -> ${persona.targetPath}`);
+    }
+    if (result.installed.length > 0) {
+        lines.push(`Installed ${result.installed.length} persona(s) into ${result.targetDir}.`);
+    }
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+function formatPersonaInstallConflicts(result) {
+    if (result.conflicts.length === 0)
+        return '';
+    const lines = result.conflicts.map((conflict) => `conflict ${conflict.id}: ${conflict.targetPath} already exists (use --overwrite to replace it)`);
+    lines.push(`Skipped ${result.conflicts.length} existing persona file(s); re-run with --overwrite to replace.`);
+    return lines.join('\n') + '\n';
+}
+function runPersonaInstall(args) {
+    if (args.includes('-h') || args.includes('--help')) {
+        process.stdout.write('Usage: agentworkforce install <pkg|path> [--persona <id> ...] [--overwrite]\n');
+        process.exit(0);
+    }
+    let parsed;
+    try {
+        parsed = parseInstallArgs(args);
+    }
+    catch (err) {
+        die(err.message);
+    }
+    let result;
+    try {
+        result = installPersonas({
+            source: parsed.source,
+            personaIds: parsed.personaIds,
+            overwrite: parsed.overwrite
+        });
+    }
+    catch (err) {
+        die(err.message, false);
+    }
+    process.stdout.write(formatPersonaInstallSummary(result));
+    process.stderr.write(formatPersonaInstallConflicts(result));
+    process.exit(result.conflicts.length > 0 ? 1 : 0);
+}
 function collectPersonaRows() {
     const rows = [];
     const pushSpec = (spec, source) => {
@@ -1263,6 +1402,21 @@ function formatPersonaShow(spec, source, tiers, tierNote) {
         }
     }
     lines.push('');
+    lines.push('INPUTS');
+    const inputs = Object.entries(spec.inputs ?? {});
+    if (inputs.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const [name, input] of inputs) {
+            lines.push(`  - ${name}`);
+            if (input.description)
+                lines.push(`      description: ${input.description}`);
+            lines.push(`      env:         ${input.env ?? name}`);
+            lines.push(`      default:     ${input.default ?? '(required)'}`);
+        }
+    }
+    lines.push('');
     lines.push('MCP SERVERS');
     const servers = Object.entries(spec.mcpServers ?? {});
     if (servers.length === 0) {
@@ -1347,6 +1501,93 @@ function runHarnessCheck() {
     process.stdout.write(`\n${available}/${results.length} harness(es) available.\n`);
     process.exit(0);
 }
+function defaultCreateTargetSelector() {
+    if (existsSync(join(process.cwd(), '.agentworkforce', 'workforce'))) {
+        return 'cwd';
+    }
+    return loadPersonaSourceConfig().defaultCreateTarget ?? 'user';
+}
+function resolveCreateTarget(rawTarget) {
+    const raw = rawTarget?.trim() || defaultCreateTargetSelector();
+    const config = loadPersonaSourceConfig();
+    if (raw === 'cwd') {
+        return {
+            raw,
+            kind: 'cwd',
+            dir: defaultCwdPersonaDir(process.cwd()),
+            createMode: 'local'
+        };
+    }
+    if (raw === 'user') {
+        return {
+            raw,
+            kind: 'user',
+            dir: config.userPersonaDir,
+            createMode: 'local'
+        };
+    }
+    if (raw === 'library') {
+        const dir = resolvePath(process.cwd(), 'personas');
+        if (!existsSync(dir)) {
+            die('create: --to library requires running from the AgentWorkforce repo root, where ./personas exists.');
+        }
+        return {
+            raw,
+            kind: 'library',
+            dir,
+            createMode: 'built-in'
+        };
+    }
+    const dirMatch = /^dir:([1-9]\d*)$/.exec(raw);
+    if (dirMatch) {
+        const idx = Number(dirMatch[1]) - 1;
+        const dir = config.personaDirs[idx];
+        if (!dir) {
+            die(`create: ${raw} does not exist. Run "agentworkforce sources list" to see configured dirs.`);
+        }
+        return {
+            raw,
+            kind: raw,
+            dir,
+            createMode: 'local'
+        };
+    }
+    return {
+        raw: normalizePersonaDir(raw),
+        kind: 'path',
+        dir: normalizePersonaDir(raw),
+        createMode: 'local'
+    };
+}
+function buildCreateInputValues(target) {
+    return {
+        [CREATE_INPUT_TARGET_DIR]: target.dir,
+        [CREATE_INPUT_CREATE_MODE]: target.createMode
+    };
+}
+function ensureCreateTargetDir(target) {
+    if (target.createMode === 'built-in')
+        return;
+    mkdirSync(target.dir, { recursive: true });
+}
+function saveDefaultCreateTarget(target) {
+    const config = loadPersonaSourceConfig();
+    const raw = target.kind === 'path' ? target.dir : target.raw;
+    const saved = savePersonaSourceConfig(config.personaDirs, { defaultCreateTarget: raw });
+    process.stderr.write(`• default create target saved: ${raw}\n`);
+    process.stderr.write(`• config: ${saved.configPath}\n`);
+}
+async function runAgentSelector(selector, flags, inputValues) {
+    const target = parseSelector(selector);
+    const selection = {
+        ...buildSelection(target.spec, target.tier, target.kind),
+        ...(inputValues ? { inputValues } : {})
+    };
+    const code = await runInteractive(selection, {
+        installInRepo: flags.installInRepo
+    });
+    process.exit(code);
+}
 export async function main() {
     const argv = process.argv.slice(2);
     const [subcommand, ...rest] = argv;
@@ -1354,12 +1595,19 @@ export async function main() {
         process.stdout.write(USAGE);
         process.exit(subcommand ? 0 : 1);
     }
+    if (subcommand === '-v' || subcommand === '--version') {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        process.exit(0);
+    }
     if (subcommand === 'list') {
         runList(rest);
     }
     if (subcommand === 'show') {
         runShow(rest);
     }
+    if (subcommand === 'install') {
+        runPersonaInstall(rest);
+    }
     if (subcommand === 'sources') {
         runSources(rest);
     }
@@ -1376,6 +1624,10 @@ export async function main() {
         }
         runHarnessCheck();
     }
+    if (subcommand === 'create') {
+        const { flags, selector, inputValues } = parseCreateArgs(rest);
+        await runAgentSelector(selector, flags, inputValues);
+    }
     if (subcommand !== 'agent') {
         die(`Unknown subcommand "${subcommand}".`);
     }
@@ -1386,12 +1638,7 @@ export async function main() {
     if (extra.length > 0) {
         die(`agent: unexpected argument "${extra[0]}". The agent subcommand only takes a persona selector.`);
     }
-    const target = parseSelector(selector);
-    const selection = buildSelection(target.spec, target.tier, target.kind);
-    const code = await runInteractive(selection, {
-        installInRepo: flags.installInRepo
-    });
-    process.exit(code);
+    await runAgentSelector(selector, flags);
 }
 export function parseAgentArgs(args) {
     const flags = { installInRepo: false };
@@ -1418,6 +1665,60 @@ export function parseAgentArgs(args) {
     }
     return { flags, positional };
 }
+export function parseCreateArgs(args) {
+    const flags = { installInRepo: false, saveDefault: false };
+    let seenDoubleDash = false;
+    const positional = [];
+    const valueOf = (i, flag) => {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith('--')) {
+            die(`create: ${flag} requires a value.`);
+        }
+        return v;
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (seenDoubleDash) {
+            positional.push(arg);
+            continue;
+        }
+        if (arg === '--') {
+            seenDoubleDash = true;
+            continue;
+        }
+        if (arg === '--install-in-repo') {
+            flags.installInRepo = true;
+            continue;
+        }
+        if (arg === '--to') {
+            flags.to = valueOf(i, arg);
+            i += 1;
+            continue;
+        }
+        if (arg === '--save-default') {
+            flags.saveDefault = true;
+            continue;
+        }
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce create [--to <cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo]\n');
+            process.exit(0);
+        }
+        positional.push(arg);
+    }
+    const [unexpected] = positional;
+    if (unexpected) {
+        die(`create: unexpected argument "${unexpected}". The create command always runs ${CREATE_SELECTOR}; use "agentworkforce agent <persona>[@<tier>]" to run another persona.`);
+    }
+    const target = resolveCreateTarget(flags.to);
+    ensureCreateTargetDir(target);
+    if (flags.saveDefault)
+        saveDefaultCreateTarget(target);
+    return {
+        flags,
+        selector: CREATE_SELECTOR,
+        inputValues: buildCreateInputValues(target)
+    };
+}
 // Only run main when invoked as the CLI entry, not when imported by tests.
 // Node ESM: import.meta.url is the module URL; argv[1] is the entry script
 // path, which may be relative (e.g. `node ./dist/cli.js`) and pathToFileURL
@@ -1435,6 +1736,10 @@ const isCliEntry = (() => {
 })();
 if (isCliEntry) {
     main().catch((err) => {
+        if (err instanceof MissingPersonaInputError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(1);
+        }
         process.stderr.write(`${err?.stack ?? String(err)}\n`);
         process.exit(1);
     });