@agentworkforce/cli 0.15.0 → 0.16.0

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { constants, homedir } from 'node:os';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { constants, homedir, tmpdir } 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, resolveSidecar, routingProfiles, useSelection } from '@agentworkforce/workload-router';
+import { HARNESS_VALUES, materializeSkills, PERSONA_TAGS, PERSONA_TIERS, listBuiltInPersonas, personaCatalog, resolveSidecar, routingProfiles, useSelection } from '@agentworkforce/workload-router';
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
 import { launchOnMount, readAgentDotfiles } from '@relayfile/local-mount';
 import ora from 'ora';
@@ -57,6 +57,26 @@ Commands:
                                             Disable launch metadata recording.
                                             Also disabled by
                                             AGENTWORKFORCE_LAUNCH_METADATA=0.
+                        --dry-run           Validate the persona without
+                                            spawning the harness or burning
+                                            tier-model tokens. Three checks:
+                                            (1) sidecar — claudeMd / agentsMd
+                                            filename refs are readable;
+                                            (2) harness spec — permissions /
+                                            mcpServers / harness-settings
+                                            shape is accepted by the harness
+                                            translator; (3) skills — each
+                                            \`skills[].source\` is run through
+                                            its real installer (npx skills
+                                            add / npx prpm install) inside a
+                                            fresh temp dir, with per-skill
+                                            pass/fail reporting. Use this in
+                                            the persona-author loop to catch
+                                            hallucinated skill names and
+                                            malformed config before a persona
+                                            ships. Temp dir is removed on
+                                            success, kept on failure for
+                                            inspection.
   list [flags]        List available personas from the cascade (cwd →
                       configured persona dirs → library). By default shows
                       one row per persona at the recommended tier for its
@@ -117,11 +137,11 @@ configured persona dir is ~/.agentworkforce/workforce/personas.
 Examples:
   agentworkforce create
   agentworkforce create --save-in-directory=user
-  agentworkforce agent npm-provenance-publisher@best
-  agentworkforce agent my-posthog@best
-  agentworkforce agent review@best-value
+  agentworkforce install @agentworkforce/personas-core --persona code-reviewer
+  agentworkforce agent code-reviewer@best-value
+  agentworkforce agent my-reviewer@best
   agentworkforce list
-  agentworkforce show posthog
+  agentworkforce show code-reviewer
   agentworkforce install @agentrelay/personas --persona relay-orchestrator
   agentworkforce install ./local-personas --overwrite
   agentworkforce sources list
@@ -159,7 +179,7 @@ function collectKnownPersonas() {
             description: spec.description
         });
     }
-    for (const spec of Object.values(personaCatalog)) {
+    for (const spec of listBuiltInPersonas()) {
         if (byName.has(spec.id))
             continue;
         byName.set(spec.id, {
@@ -196,11 +216,14 @@ function resolveSpec(key) {
     const catalogAsIntent = personaCatalog[key];
     if (catalogAsIntent)
         return catalogAsIntent;
-    const byId = Object.values(personaCatalog).find((p) => p.id === key);
+    const byId = listBuiltInPersonas().find((p) => p.id === key);
     if (byId)
         return byId;
+    const packHint = 'Optional first-party personas are installed from packs, for example:\n' +
+        '  agentworkforce install @agentworkforce/personas-core\n' +
+        '  agentworkforce install @agentrelay/personas';
     return {
-        error: `Unknown persona "${key}". Known personas:\n${formatNameDescriptionTable(collectKnownPersonas())}`
+        error: `Unknown persona "${key}". Known personas:\n${formatNameDescriptionTable(collectKnownPersonas())}\n\n${packHint}`
     };
 }
 function parseSelector(sel) {
@@ -674,6 +697,128 @@ export function decideCleanMode(harness, installInRepo = false) {
     }
     return { useClean: false };
 }
+/**
+ * Persona authoring dry-run. Used by persona authors to verify a persona
+ * actually launches before it ships, without spawning the harness or
+ * running the agent's tier model. Three checks, in order:
+ *
+ *   1. Sidecar resolution — `claudeMd` / `agentsMd` filename references
+ *      that point at unreadable files would brick the launch silently
+ *      today (lenient warning); dry-run promotes them to failures.
+ *   2. Interactive spec build — runs `buildInteractiveSpec` on the
+ *      resolved selection. Catches malformed `permissions` patterns,
+ *      `mcpServers` shape errors, and missing required harness fields.
+ *      Pure / no side effects.
+ *   3. Skill install — runs each `skills[].source` through its real
+ *      installer (`npx skills add` / `npx prpm install`) inside a fresh
+ *      temp dir and reports per-skill pass/fail.
+ *
+ * Temp dir is deleted on success so dry-run leaves no trace; on a skill
+ * failure it is left in place and its path printed so the author can
+ * inspect the installer's output. Checks 1 and 2 run before any temp
+ * dir is created so an early failure doesn't litter `/tmp`.
+ */
+function runDryRun(selection) {
+    const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
+    const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
+    const renderedClaudeContent = selection.claudeMdContent !== undefined
+        ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
+        : undefined;
+    const renderedAgentsContent = selection.agentsMdContent !== undefined
+        ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
+        : undefined;
+    const effectiveSelection = {
+        ...selection,
+        runtime: { ...selection.runtime, systemPrompt: renderedSystemPrompt },
+        ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
+        ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
+    };
+    const { runtime, personaId, tier } = effectiveSelection;
+    process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model}) [DRY-RUN]\n`);
+    // Check 1: sidecar resolution. A loadSidecarForSelection warning means
+    // the persona points `claudeMd` / `agentsMd` at a file we couldn't
+    // read; the launch path degrades to a warning today, which silently
+    // drops the persona's operating spec. In dry-run that's a failure.
+    const sidecarLookup = loadSidecarForSelection(effectiveSelection);
+    if (sidecarLookup.warning) {
+        process.stderr.write(`✗ sidecar: ${sidecarLookup.warning}\n`);
+        return 1;
+    }
+    process.stderr.write(`✓ sidecar: ${sidecarLookup.sidecar ? sidecarLookup.sidecar.mountFile : '(none)'}\n`);
+    // Check 2: harness-kit translation. buildInteractiveSpec validates
+    // permissions shape, mcpServers shape, and required runtime fields.
+    // We resolve env + mcp leniently (same as the live launch path) so
+    // the spec call sees the same inputs it would at runtime.
+    const callerEnv = { ...process.env, ...inputResolution.values };
+    const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
+    const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
+    emitDropWarnings(formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers));
+    let spec;
+    try {
+        spec = buildInteractiveSpec({
+            harness: runtime.harness,
+            personaId,
+            model: runtime.model,
+            systemPrompt: runtime.systemPrompt,
+            harnessSettings: runtime.harnessSettings,
+            mcpServers: mcpResolution.servers,
+            permissions: effectiveSelection.permissions
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`✗ harness spec: ${msg}\n`);
+        return 1;
+    }
+    for (const w of spec.warnings)
+        process.stderr.write(`warning: ${w}\n`);
+    process.stderr.write(`✓ harness spec: ${spec.bin} (${spec.args.length} args)\n`);
+    // Check 3: skill installs.
+    const plan = materializeSkills(effectiveSelection.skills, runtime.harness);
+    if (plan.installs.length === 0) {
+        process.stderr.write('✓ skills: (none declared)\n');
+        process.stderr.write('✓ dry-run ok\n');
+        return 0;
+    }
+    const tempDir = mkdtempSync(join(tmpdir(), `agentworkforce-dryrun-${personaId}-`));
+    process.stderr.write(`• temp dir: ${tempDir}\n`);
+    process.stderr.write(`• installing ${plan.installs.length} skill(s)\n`);
+    const failures = [];
+    for (const inst of plan.installs) {
+        const [bin, ...args] = inst.installCommand;
+        if (!bin) {
+            process.stderr.write(`  skipped ${inst.skillId}: empty install command\n`);
+            continue;
+        }
+        process.stderr.write(`• ${inst.skillId} (${inst.sourceKind}) → ${inst.packageRef}\n`);
+        const res = spawnSync(bin, args, { stdio: 'inherit', shell: false, cwd: tempDir });
+        const code = subprocessExitCode(res);
+        if (code === 0) {
+            process.stderr.write(`  ✓ ${inst.skillId}\n`);
+        }
+        else {
+            process.stderr.write(`  ✗ ${inst.skillId} (exit ${code})\n`);
+            failures.push({ skillId: inst.skillId, exitCode: code });
+        }
+    }
+    if (failures.length === 0) {
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warning: failed to clean up ${tempDir}: ${msg}\n`);
+        }
+        process.stderr.write(`✓ dry-run ok: ${plan.installs.length} skill(s) installed cleanly\n`);
+        return 0;
+    }
+    process.stderr.write(`✗ dry-run failed: ${failures.length} of ${plan.installs.length} skill(s) failed\n`);
+    process.stderr.write(`  inspect ${tempDir} for installer output\n`);
+    for (const f of failures) {
+        process.stderr.write(`  - ${f.skillId} (exit ${f.exitCode})\n`);
+    }
+    return failures[0]?.exitCode || 1;
+}
 async function runInteractive(selection, options) {
     const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
     const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
@@ -748,7 +893,7 @@ async function runInteractive(selection, options) {
     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
-    // valid target even for skill-less personas like posthog. Gate on the
+    // valid target even for skill-less local personas. Gate on the
     // command string rather than `installs.length` so we don't skip that.
     const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
     const installLabel = install.plan.installs.length === 0
@@ -1374,7 +1519,7 @@ function collectPersonaRows() {
         pushSpec(spec, local.sources.get(id) ?? 'library');
         seen.add(id);
     }
-    for (const spec of Object.values(personaCatalog)) {
+    for (const spec of listBuiltInPersonas()) {
         if (seen.has(spec.id))
             continue;
         pushSpec(spec, 'library');
@@ -1588,7 +1733,7 @@ function resolveShowTarget(selector, all) {
             spec = byIntent;
         }
         else {
-            const byId = Object.values(personaCatalog).find((p) => p.id === key);
+            const byId = listBuiltInPersonas().find((p) => p.id === key);
             if (byId)
                 spec = byId;
         }
@@ -1843,6 +1988,10 @@ async function runAgentSelector(selector, flags, inputValues) {
         ...buildSelection(target.spec, target.tier, target.kind),
         ...(inputValues ? { inputValues } : {})
     };
+    if (flags.dryRun) {
+        const code = runDryRun(selection);
+        process.exit(code);
+    }
     const code = await runInteractive(selection, {
         installInRepo: flags.installInRepo,
         noLaunchMetadata: flags.noLaunchMetadata,
@@ -1858,7 +2007,7 @@ async function runAgentSelector(selector, flags, inputValues) {
  */
 export function buildPickCandidates() {
     const byId = new Map();
-    for (const spec of Object.values(personaCatalog)) {
+    for (const spec of listBuiltInPersonas()) {
         byId.set(spec.id, {
             id: spec.id,
             intent: spec.intent,
@@ -1969,7 +2118,7 @@ async function runPick(args) {
         ...buildCreateInputValues(target),
         TASK_DESCRIPTION: task
     };
-    await runAgentSelector(CREATE_SELECTOR, { installInRepo: false, noLaunchMetadata: false }, inputValues);
+    await runAgentSelector(CREATE_SELECTOR, { installInRepo: false, noLaunchMetadata: false, dryRun: false }, inputValues);
     // runAgentSelector terminates via process.exit; this satisfies TS's
     // reachable-end-point check for the `Promise<never>` return type.
     process.exit(0);
@@ -2030,7 +2179,11 @@ export async function main() {
     await runAgentSelector(selector, flags);
 }
 export function parseAgentArgs(args) {
-    const flags = { installInRepo: false, noLaunchMetadata: false };
+    const flags = {
+        installInRepo: false,
+        noLaunchMetadata: false,
+        dryRun: false
+    };
     const positional = [];
     let seenDoubleDash = false;
     for (const arg of args) {
@@ -2050,6 +2203,10 @@ export function parseAgentArgs(args) {
             flags.noLaunchMetadata = true;
             continue;
         }
+        if (arg === '--dry-run') {
+            flags.dryRun = true;
+            continue;
+        }
         if (arg === '-h' || arg === '--help') {
             process.stdout.write(USAGE);
             process.exit(0);
@@ -2059,7 +2216,12 @@ export function parseAgentArgs(args) {
     return { flags, positional };
 }
 export function parseCreateArgs(args) {
-    const flags = { installInRepo: false, noLaunchMetadata: false, saveDefault: false };
+    const flags = {
+        installInRepo: false,
+        noLaunchMetadata: false,
+        dryRun: false,
+        saveDefault: false
+    };
     let seenDoubleDash = false;
     const positional = [];
     const valueOf = (i, flag) => {