@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/runtime/cli.js

@@ -17,8 +17,10 @@ import { toolRegistry, toolSchemaBundleHashInput } from '../tools/registry.js';
 import { webFetchTool } from '../tools/web-fetch.js';
 import { emptyIndex, rebuildIndex, readIndex, upsertArtifact, writeIndex, } from '../core/index-store.js';
 import { signatureForPlanReview } from '../core/repl/ask.js';
-import { buildRuntimeConfig, loadRuntimeConfig, pollDeviceFlow, pugiHandoffBundleSchema, pugiSyncDryRunPlanSchema, pugiSyncPrivacyModeSchema, pugiSyncRequestSchema, pugiSyncUploadPlanSchema, pugiTripleReviewRequestSchema, startDeviceFlow, submitSync, submitTripleReview, } from '@pugi/sdk';
+import { buildRuntimeConfig, fetchPersonaRoster, loadRuntimeConfig, openPugiSession, pollDeviceFlow, pugiHandoffBundleSchema, pugiSyncDryRunPlanSchema, pugiSyncPrivacyModeSchema, pugiSyncRequestSchema, pugiSyncUploadPlanSchema, pugiTripleReviewRequestSchema, startDeviceFlow, submitDelegate, submitSync, submitTripleReview, } from '@pugi/sdk';
 import { PUGI_TAGLINE } from '@pugi/personas';
+import { resolveRoster, renderRosterTable } from './commands/roster.js';
+import { runDelegateCommand } from './commands/delegate.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
@@ -27,9 +29,14 @@ import { runPrivacyCommand } from './commands/privacy.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runBudgetCommand } from './commands/budget.js';
 import { runSkillsCommand } from './commands/skills.js';
+import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
+import { runLspCommand } from './commands/lsp.js';
+import { runPatchCommand } from './commands/patch.js';
+import { runWorktreeCommand } from './commands/worktree.js';
 import { resolveWorkspaceLabel } from '../core/repl/workspace-context.js';
 import { runReviewConsensus } from './commands/review-consensus.js';
+import { DECOMPOSE_PROMPT_SUFFIX, parseDecompositionFromText, writeDecomposition, } from './plan-decompose.js';
 import { FtsSyntaxError, SqliteSessionStore, resolveProjectStoreDir } from '../core/repl/store/index.js';
 import { slugForCwd } from '../core/repl/history.js';
 import { dispatchEdit, } from '../core/edits/index.js';
@@ -44,7 +51,7 @@ import { dispatchEdit, } from '../core/edits/index.js';
  * packages/pugi-sdk/package.json); the publish workflow validates the
  * three are in lockstep.
  */
-const PUGI_CLI_VERSION = "0.1.0-beta.1";
+const PUGI_CLI_VERSION = "0.1.0-beta.10";
 const handlers = {
     accounts,
     agents: dispatchAgents,
@@ -53,6 +60,7 @@ const handlers = {
     budget: dispatchBudget,
     code: runEngineTask('code'),
     config: dispatchConfig,
+    delegate: dispatchDelegate,
     deploy: dispatchDeploy,
     doctor,
     explain: runEngineTask('explain'),
@@ -64,11 +72,14 @@ const handlers = {
     jobs,
     login,
     logout,
+    lsp: dispatchLsp,
+    patch: dispatchPatch,
     plan: runEngineTask('plan'),
     'plan-review': dispatchPlanReview,
     privacy: dispatchPrivacy,
     review,
     resume,
+    roster: dispatchRoster,
     sessions,
     skills: dispatchSkills,
     sync,
@@ -76,6 +87,7 @@ const handlers = {
     version,
     web: dispatchWeb,
     whoami,
+    worktree: dispatchWorktree,
 };
 /**
  * α6.3 `pugi ask "<question>"` — surface the office-hours forcing-question
@@ -246,6 +258,59 @@ async function dispatchPrivacy(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi roster` - α7.5 Phase 1.
+ *
+ * List the live Tier 1 personas with display name, role, and routing
+ * tag. Walks the remote /api/pugi/sessions/roster endpoint when a
+ * credential is available; falls back to the local @pugi/personas
+ * roster when offline so the operator can still see who is on the team.
+ */
+async function dispatchRoster(_args, flags, _session) {
+    const credential = resolveActiveCredential();
+    const config = credential
+        ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
+        : null;
+    const { rows, warning } = await resolveRoster(config);
+    const payload = {
+        ok: true,
+        personas: rows,
+        warning,
+    };
+    const text = (warning ? `# warning: ${warning}\n\n` : '') +
+        renderRosterTable(rows);
+    writeOutput(flags, payload, text);
+}
+/**
+ * `pugi delegate <slug> "<brief>"` - α7.5 Phase 1.
+ *
+ * Open a fresh REPL session and POST the brief to one Tier 1 persona,
+ * bypassing Mira's coordinator pass. Non-interactive: the CLI prints
+ * the dispatch id on success and exits; the operator (or a script) can
+ * subscribe to the session stream separately if they want the live
+ * lifecycle. Interactive operators use `/delegate` from inside the REPL
+ * instead so the dispatch lifecycle surfaces inline.
+ */
+async function dispatchDelegate(args, flags, _session) {
+    await runDelegateCommand(args, {
+        workspaceCwd: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        resolveConfig: () => {
+            const credential = resolveActiveCredential();
+            if (!credential)
+                return null;
+            return buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey });
+        },
+        fetchRoster: fetchPersonaRoster,
+        submitDelegate,
+        openSession: async (config, workspaceCwd) => {
+            const result = await openPugiSession(config, { workspaceCwd });
+            if (result.status === 'ok')
+                return { sessionId: result.response.sessionId };
+            return { error: `${result.status}: ${result.message}` };
+        },
+    });
+}
 async function dispatchUndo(args, flags, session) {
     await runUndoCommand(args, {
         workspaceRoot: process.cwd(),
@@ -314,6 +379,59 @@ async function dispatchWeb(args, flags, _session) {
     }
     writeOutput(flags, result, `# ${result.title}\n# ${result.url}\n# fetched ${result.fetched_at}\n\n${result.content_md}`);
 }
+/**
+ * α7.7: `pugi lsp <op> <file> [args]` — direct LSP queries. Delegated
+ * to the standalone runner in `./commands/lsp.ts` so the giant cli.ts
+ * dispatch table stays narrow. The runner spawns + tears down the LSP
+ * server per invocation (no daemon yet — that ships in α7.7b).
+ */
+async function dispatchLsp(args, flags, _session) {
+    const result = await runLspCommand(args, { cwd: process.cwd(), json: flags.json });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
+/**
+ * α7.7: `pugi patch` — apply a unified-diff patch from stdin or a file.
+ * Routes through the same security gate as the Layer A/B/C applicators
+ * (see `src/core/edits/security-gate.ts`). Exit codes mirror the
+ * security taxonomy so CI loops can alert on hostile patches without
+ * confusing them with operator typos.
+ *
+ * R1 fix (2026-05-26, PR #413 r1): pass `flags.dryRun` through so the
+ * top-level parser's consumption of `--dry-run` does not silently
+ * disable dry-run mode on `pugi patch --dry-run < diff.patch`.
+ */
+async function dispatchPatch(args, flags, _session) {
+    const result = await runPatchCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        dryRun: flags.dryRun,
+    });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
+/**
+ * α7.7: `pugi worktree <op>` — manual scratch worktree management.
+ * The `pugi build` and `pugi review --consensus` paths use the same
+ * primitives internally (`createWorktree` / `promoteWorktree`); this
+ * surface is the operator escape hatch for debug + experiment flows.
+ *
+ * R1 fix (2026-05-26, PR #413 r1): forward `flags.dryRun` so the
+ * top-level parser's consumption of `--dry-run` does not silently
+ * disable dry-run mode on `pugi worktree promote --dry-run <path>`.
+ */
+async function dispatchWorktree(args, flags, _session) {
+    const result = await runWorktreeCommand(args, {
+        cwd: process.cwd(),
+        json: flags.json,
+        dryRun: flags.dryRun,
+    });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
 export async function runCli(argv) {
     const { command, args, flags, isBareInvocation } = parseArgs(argv);
     // Bare `pugi` on a TTY enters the REPL-by-default agentic session
@@ -399,11 +517,13 @@ function parseArgs(argv) {
         // "Mira: ..." prose, never "Read(path)" prefix) OR fires falsely on
         // accidental `Verb(noun)` shapes producing stuck `running` rows.
         // Hide by default; opt-in via `--tool-stream` OR PUGI_TOOL_STREAM=1
-        // for development/testing. Will flip к default ON when backend
+        // for development/testing. Will flip to default ON when backend
         // emits real tool events (filed as α6.13.X follow-up).
         noToolStream: process.env.PUGI_TOOL_STREAM === '1' || process.env.PUGI_HIDE_TOOL_STREAM === '1'
             ? process.env.PUGI_HIDE_TOOL_STREAM === '1'
             : true,
+        noDefaults: process.env.PUGI_INIT_NO_DEFAULTS === '1',
+        decompose: false,
     };
     const args = [];
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
@@ -436,7 +556,7 @@ function parseArgs(argv) {
         else if (arg === '--consensus') {
             // α6.7: customer-facing 3-model consensus review. Routes through
             // the SSE-based runtime gate rather than the legacy artifact
-            // writer. The triple flag stays unset так the existing
+            // writer. The triple flag stays unset so the existing
             // performRemoteTripleReview path is never accidentally entered.
             flags.consensus = true;
         }
@@ -459,10 +579,21 @@ function parseArgs(argv) {
             flags.noToolStream = true;
         }
         else if (arg === '--tool-stream') {
-            // Opt-in для α6.12 dev/testing — backend tool events not live yet,
-            // pane shows синтесайз heuristic OR empty placeholder
+            // Opt-in for α6.12 dev/testing — backend tool events not live yet,
+            // pane shows synthesized heuristic OR empty placeholder
             flags.noToolStream = false;
         }
+        else if (arg === '--no-defaults') {
+            // Init-only flag: skip the bundled default-skills install. Parsed
+            // at the global level for consistency with --no-splash / --no-tool-stream.
+            flags.noDefaults = true;
+        }
+        else if (arg === '--decompose') {
+            // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
+            // it. Parsed globally for symmetry with the rest of the flag
+            // grammar; `runEngineTask('plan')` is the single consumer.
+            flags.decompose = true;
+        }
         else if (arg.startsWith('--privacy=')) {
             flags.privacy = parsePrivacyMode(arg.slice('--privacy='.length));
         }
@@ -478,8 +609,20 @@ function parseArgs(argv) {
         }
     }
     const isBareInvocation = args.length === 0;
+    const command = args.shift() ?? 'help';
+    // Sprint α6.X CEO dogfood 2026-05-26 (P0 hot-fix): trailing `--help`
+    // / `-h` on ANY sub-command must route to the help printer rather
+    // than dispatching the real engine. Before this guard `pugi build
+    // --help` burned 86k tokens running the actual build loop because
+    // the dispatcher saw `--help` as an opaque arg and forwarded it
+    // through to the engine. Re-routing here means `pugi <cmd> --help`
+    // becomes `pugi help <cmd>` deterministically across the entire
+    // command tree.
+    if (args.includes('--help') || args.includes('-h')) {
+        return { command: 'help', args: [command], flags, isBareInvocation: false };
+    }
     return {
-        command: args.shift() ?? 'help',
+        command,
         args,
         flags,
         isBareInvocation,
@@ -527,6 +670,15 @@ async function help(_args, flags, _session) {
         '  pugi ask "<question>"          Surface a yes/no question modal locally.',
         '  pugi plan-review <task>        Generate + present a plan-review modal.',
         '',
+        'Persona dispatch (α7.5):',
+        '  pugi roster                              List the live Tier 1 personas + roles.',
+        '  pugi delegate <slug> "<brief>"           Dispatch a brief to one specialist.',
+        '',
+        'Plan decomposition (α6.8):',
+        '  pugi plan --decompose <idea>   Split a high-level idea into 3-7 components.',
+        '                                 Writes .pugi/plan/<session-id>/splits/NN-<name>/spec.md',
+        '                                 plus manifest.md with the dependency DAG.',
+        '',
         'Deploy:',
         '  pugi deploy --target vercel <vercelProject> --project <id>',
         '                          Trigger a Vercel deployment from the bound Git source.',
@@ -549,6 +701,8 @@ async function help(_args, flags, _session) {
         '                          PUGI_SKIP_SPLASH=1.',
         '  --no-tool-stream        Hide the live tool stream pane (α6.12).',
         '                          Pairs with PUGI_HIDE_TOOL_STREAM=1.',
+        '  --no-defaults           Skip bundled default-skills install on',
+        '                          `pugi init`. Pairs with PUGI_INIT_NO_DEFAULTS=1.',
         '',
         PUGI_TAGLINE,
         'Execution defaults to local. Use --remote or --web to create a handoff bundle.',
@@ -618,6 +772,7 @@ async function init(_args, flags, _session) {
     ensureDir(pugiDir, created, skipped);
     ensureDir(resolve(pugiDir, 'artifacts'), created, skipped);
     ensureDir(resolve(pugiDir, 'sessions'), created, skipped);
+    ensureDir(resolve(pugiDir, 'skills'), created, skipped);
     writeJsonIfMissing(resolve(pugiDir, 'settings.json'), {
         schema: 1,
         workflow: {
@@ -687,17 +842,50 @@ async function init(_args, flags, _session) {
     // Ensure `.pugi/` is git-ignored so users do not accidentally commit
     // local audit logs, artifacts, or triple-review request payloads.
     ensurePugiGitIgnore(cwd, created, skipped);
+    // Bundled default skills (brand-voice, endpoint-probe, readme-sync).
+    // Skipped when --no-defaults is passed OR when PUGI_INIT_NO_DEFAULTS=1.
+    // Idempotent: a skill whose target directory already exists is left
+    // alone so re-running `pugi init` after the operator customised one of
+    // the defaults does not clobber their edits.
+    let defaultSkills = [];
+    if (!flags.noDefaults) {
+        try {
+            defaultSkills = await installDefaultSkills({
+                workspaceRoot: cwd,
+                log: (line) => process.stderr.write(line),
+            });
+        }
+        catch (error) {
+            // Default-skills install is a convenience layer. A failure here
+            // (bad sha256 hashing, permission error on .pugi/skills/) must not
+            // leave `pugi init` in a half-state where settings.json exists but
+            // the operator sees an unexplained crash. Log the error to stderr
+            // and continue — the operator can still install skills manually.
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[pugi init] default-skills install failed: ${message}\n`);
+        }
+    }
     const payload = {
         status: 'initialized',
         root: cwd,
         created,
         skipped,
+        defaultSkills,
     };
+    const defaultSkillLines = flags.noDefaults
+        ? ['Default skills: skipped (--no-defaults)']
+        : defaultSkills.length === 0
+            ? ['Default skills: none installed']
+            : [
+                'Default skills:',
+                ...defaultSkills.map((entry) => `  ${entry.name.padEnd(18)} ${entry.status}`),
+            ];
     writeOutput(flags, payload, [
         'Pugi initialized',
         `Root: ${cwd}`,
         created.length ? `Created:\n${created.map((path) => `  ${path}`).join('\n')}` : 'Created: none',
         skipped.length ? `Already present:\n${skipped.map((path) => `  ${path}`).join('\n')}` : 'Already present: none',
+        ...defaultSkillLines,
     ].join('\n'));
 }
 async function idea(args, flags, session) {
@@ -2042,6 +2230,26 @@ function runEngineTask(kind) {
         const config = credential
             ? buildRuntimeConfig({ apiUrl: credential.apiUrl, apiKey: credential.apiKey })
             : envConfig;
+        // α6.8 EXTEND PR1 v2: `--decompose` gating runs BEFORE the offline
+        // fallback. Two reasons:
+        //   1. The flag is plan-only — surfacing the rejection for
+        //      `pugi build --decompose` before we drop into `offlineBuild`
+        //      means the operator gets a deterministic error instead of a
+        //      silent no-op stub.
+        //   2. The decompose post-processor depends on the engine's final
+        //      text. The offline plan stub does not invoke the engine, so
+        //      `pugi plan --decompose --offline` would silently skip the
+        //      decomposition step. Refusing the combination up front is the
+        //      cheapest way to keep the contract honest.
+        if (flags.decompose && kind !== 'plan') {
+            throw new Error(`--decompose is only valid for \`pugi plan\` (got \`pugi ${label}\`)`);
+        }
+        if (flags.decompose && flags.offline) {
+            throw new Error('--decompose requires the engine — drop --offline (decomposition needs the model to emit a fenced JSON block)');
+        }
+        if (flags.decompose && !config) {
+            throw new Error('--decompose requires the engine — run `pugi login` or set PUGI_API_KEY (decomposition needs the model to emit a fenced JSON block)');
+        }
         // Offline fallback: preserves the local-first invariant. `plan` /
         // `build` / `explain` drop back to their pre-Sprint-2 stub
         // behaviour so an operator without an API key (or with --offline)
@@ -2094,6 +2302,17 @@ function runEngineTask(kind) {
                 throw new Error(`pugi ${label} requires a prompt`);
             }
         }
+        // α6.8 EXTEND PR1: when `--decompose` is set, augment the user
+        // prompt with the decomposition-request suffix BEFORE the adapter
+        // run. The system prompt for `plan` already constrains the model
+        // to read-only tools + a plan deliverable; the suffix layers the
+        // JSON-emission contract on top so the post-run parser can lift
+        // the structured payload out of the final answer. The plan-only /
+        // engine-required gates fired before the offline fallback above,
+        // so by here we know we are on the engine path with a plan task.
+        if (flags.decompose && kind === 'plan') {
+            prompt = `${prompt}\n${DECOMPOSE_PROMPT_SUFFIX}`;
+        }
         // Narrow `config` for the type checker — the offline branches above
         // return whenever `config` is null, so by this point it must be set.
         if (!config) {
@@ -2203,6 +2422,41 @@ function runEngineTask(kind) {
                 statusEvents,
             });
         }
+        // α6.8 EXTEND PR1: `--decompose` post-processing. We only attempt
+        // the parse on a `done` plan (a blocked/failed plan is already
+        // captured in plan.md with its reason; no JSON to extract). The
+        // model's final answer arrives via `result.summary` — on success
+        // the adapter prefix is empty so it is the raw final text. We
+        // strip any leading/trailing whitespace then run the parser
+        // against the contents. On parse failure we surface a non-fatal
+        // structured error in the payload — the operator still gets the
+        // plan.md artifact and can re-run.
+        //
+        // TODO(α7.x): `result.summary` is currently a string contract that
+        // doubles as both "human-readable headline" and "raw final model
+        // text". Split into `{ summary, finalText }` on the adapter so the
+        // parser does not have to assume the prefix is empty. Tracked in
+        // PR #423 v2 retro (P2.6, Claude review).
+        let decomposeArtifact = null;
+        let decomposeError = null;
+        if (flags.decompose && kind === 'plan' && result.status === 'done') {
+            const parsed = parseDecompositionFromText(result.summary);
+            if (parsed.ok) {
+                decomposeArtifact = writeDecomposition({
+                    root,
+                    sessionId: session.id,
+                    // Persist the OPERATOR's original prompt, not the prompt+suffix
+                    // we sent to the engine. The suffix is plumbing; the manifest
+                    // header reads naturally only with the operator text.
+                    prompt: args.join(' ').trim() || prompt,
+                    decomposition: parsed.decomposition,
+                    rationale: parsed.rationale,
+                });
+            }
+            else {
+                decomposeError = { reason: parsed.reason, detail: parsed.detail };
+            }
+        }
         // Pull the headline metrics out of `eventRefs` so the summary and
         // JSON envelope match without re-parsing strings in two places.
         const metrics = parseEventRefs(result.eventRefs);
@@ -2262,6 +2516,20 @@ function runEngineTask(kind) {
                 reason: dr.reason,
                 detail: dr.detail,
             })),
+            // α6.8 EXTEND PR1: decompose artifacts (only present when
+            // `--decompose` was passed AND the model emitted a parseable
+            // JSON block). The `error` shape lands when the model returned
+            // unparseable output; the operator can re-run with a tighter
+            // prompt without losing the plain plan.md artifact.
+            decompose: decomposeArtifact !== null
+                ? {
+                    manifest: relative(root, decomposeArtifact.manifestPath),
+                    planDir: relative(root, decomposeArtifact.planDir),
+                    splits: decomposeArtifact.splitPaths,
+                }
+                : decomposeError !== null
+                    ? { error: decomposeError }
+                    : undefined,
             // The full event stream is useful for cabinet UI replay. We surface
             // it in JSON mode only — text mode operators want the summary, not
             // 30 turn-level lines.
@@ -2271,6 +2539,13 @@ function runEngineTask(kind) {
         if (kind === 'plan' && planArtifact) {
             textLines.push(`Pugi plan written to ${planArtifact.relPath}`);
         }
+        if (decomposeArtifact !== null) {
+            textLines.push(`Decomposition: ${decomposeArtifact.splitPaths.length} component spec${decomposeArtifact.splitPaths.length === 1 ? '' : 's'} under ${relative(root, decomposeArtifact.planDir)}`);
+            textLines.push(`Manifest: ${relative(root, decomposeArtifact.manifestPath)}`);
+        }
+        else if (decomposeError !== null) {
+            textLines.push(`Decomposition: skipped (${decomposeError.reason}) — plan.md still written`);
+        }
         textLines.push(`Pugi ${label}: ${result.status}`);
         textLines.push(`Summary: ${result.summary}`);
         if (result.filesChanged.length > 0) {