@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/runtime/commands/plan.js

@@ -0,0 +1,143 @@
+/**
+ * `pugi plan` / `/plan` — quick mode-switch shortcut.
+ *
+ * `/plan` is the slick UX shortcut for `/permissions plan`: one keystroke
+ * (well, five) puts the gate into plan mode + surfaces a banner so the
+ * operator knows write/dispatch tools are refused. The model goes off and
+ * thinks / researches without side effects until the operator types
+ * `/plan --back` (restore previous mode) or explicitly flips with
+ * `/permissions <mode>`.
+ *
+ * The slash and CLI surfaces both go through `runPlanCommand` — same
+ * separation as `runPermissionsCommand`. The runtime is I/O free w.r.t.
+ * the engine; the optional one-shot dispatch (`/plan <prompt>`) is
+ * handled by the CLI dispatcher AFTER this helper sets the workspace
+ * mode so the existing `runEngineTask('plan')` path sees plan mode as
+ * the workspace state without needing a parallel code path.
+ *
+ * Verdicts (the helper returns one so the caller can decide what to do
+ * after the mode write — print the banner, dispatch the engine, no-op):
+ *  - `entered`       — first `/plan` from a non-plan mode. Print the
+ *                       banner. Caller may then run a one-shot prompt.
+ *  - `already-in-plan` — `/plan` while already in plan. No-op + show
+ *                       current. No banner reprint.
+ *  - `reverted`       — `/plan --back` popped the snapshot. Print a
+ *                       one-line confirmation; no banner.
+ *  - `no-previous`    — `/plan --back` without a snapshot. Print a
+ *                       clear "nothing to revert" line.
+ *  - `persisted`      — `/plan --persist` wrote the global default
+ *                       AND set workspace state to plan. Banner +
+ *                       persistence-confirmation line.
+ *
+ * `previousMode` semantics: stashed BEFORE the workspace write on
+ * `entered` / `persisted`. Cleared after a successful `reverted` so a
+ * second `--back` reports `no-previous` instead of looping back to plan.
+ */
+import { PERMISSION_MODES, PERMISSION_MODE_GLOSS, getCurrentMode, getGlobalDefaultMode, getPreviousMode, setCurrentMode, setGlobalDefaultMode, setPreviousMode, } from '../../core/permissions/index.js';
+/**
+ * Run the `/plan` flow. Side effects:
+ *
+ *  command.back = true:
+ *    - If a previousMode snapshot exists → restore it, clear snapshot,
+ *      return `reverted`.
+ *    - Otherwise → no writes, return `no-previous`.
+ *
+ *  command.back = false, current mode is plan:
+ *    - If `--persist`, write global config (no workspace re-write — it
+ *      is already plan).
+ *    - Print "already in plan" + the banner-summary line. Return
+ *      `already-in-plan`.
+ *
+ *  command.back = false, current mode is NOT plan:
+ *    - Snapshot current mode → previousPermissionMode.
+ *    - Write workspace mode = plan.
+ *    - If `--persist`, also write global config.
+ *    - Print the banner + (if persisted) the persistence line.
+ *    - Return `entered` or `persisted`.
+ *
+ * --back + --persist is a no-op for persistence (revert never writes
+ * global config) but the revert itself fires.
+ */
+export async function runPlanCommand(command, ctx) {
+    const current = effectiveMode(ctx);
+    if (command.back) {
+        const prev = getPreviousMode(ctx.workspaceRoot);
+        if (!prev) {
+            ctx.writeOutput(`No previous mode to restore. Current: ${current}. Use \`/permissions <mode>\` to switch explicitly.`);
+            return { verdict: 'no-previous', mode: current };
+        }
+        setCurrentMode(ctx.workspaceRoot, prev);
+        setPreviousMode(ctx.workspaceRoot, null);
+        ctx.writeOutput(`Switched back to '${prev}' mode. ${PERMISSION_MODE_GLOSS[prev]}`);
+        return { verdict: 'reverted', mode: prev };
+    }
+    if (current === 'plan') {
+        // Repeat /plan in plan mode is a no-op for the mode write, but
+        // --persist still honours the operator's intent to lock plan as
+        // the global default for future sessions.
+        if (command.persist) {
+            setGlobalDefaultMode('plan', ctx.homeDir);
+            ctx.writeOutput('Already in plan mode. Persisted plan as the default for future sessions (~/.pugi/config.json).');
+            return { verdict: 'persisted', mode: 'plan' };
+        }
+        ctx.writeOutput(`Already in plan mode. ${PERMISSION_MODE_GLOSS.plan} Switch back with \`/plan --back\` or \`/permissions <mode>\`.`);
+        return { verdict: 'already-in-plan', mode: 'plan' };
+    }
+    // Entering plan mode from a non-plan baseline. Stash the current mode
+    // BEFORE the write so /plan --back can pop it. We intentionally use the
+    // observed effective mode (workspace || global || default) rather than
+    // strictly the workspace value — if the operator's previous mode was
+    // sourced from the global config, `--back` should restore that observed
+    // state, not silently degrade to default.
+    setPreviousMode(ctx.workspaceRoot, current);
+    setCurrentMode(ctx.workspaceRoot, 'plan');
+    if (command.persist) {
+        setGlobalDefaultMode('plan', ctx.homeDir);
+    }
+    for (const line of renderPlanBanner()) {
+        ctx.writeOutput(line);
+    }
+    if (command.persist) {
+        ctx.writeOutput('Persisted plan as the default for future sessions (~/.pugi/config.json).');
+        return { verdict: 'persisted', mode: 'plan' };
+    }
+    return { verdict: 'entered', mode: 'plan' };
+}
+/**
+ * Render the plan-mode banner as a sequence of lines. The slash + CLI
+ * surfaces both print these line-by-line through their respective
+ * `writeOutput` sinks so the Ink REPL conversation pane and the plain
+ * stdout pipeline render identically.
+ *
+ * The box-drawing uses light-line glyphs (U+2500 family) which render in
+ * every modern terminal we target (Linux/macOS/Windows Terminal/iTerm/
+ * Ghostty/Alacritty). No emoji per brand-voice gate.
+ */
+export function renderPlanBanner() {
+    return [
+        '┌─ Plan mode active ────────────────────────────────────────┐',
+        '│ Read-only tools allowed. Write/dispatch tools blocked.   │',
+        '│ Pugi will think + research without making changes.       │',
+        '│ Switch back: /plan --back or /permissions <mode>       │',
+        '└───────────────────────────────────────────────────────────┘',
+    ];
+}
+/**
+ * Resolve the effective mode at the moment the helper was invoked,
+ * mirroring `resolveMode` but without taking a CLI flag (the `/plan`
+ * helper is called AFTER the top-level `--mode` flag has been applied
+ * to the workspace, so the file state is the source of truth here).
+ */
+function effectiveMode(ctx) {
+    const workspace = getCurrentMode(ctx.workspaceRoot);
+    if (workspace)
+        return workspace;
+    const global = getGlobalDefaultMode(ctx.homeDir);
+    if (global)
+        return global;
+    // canonical default — `PERMISSION_MODES[0]` is `default` (the
+    // CC-parity ask-every-call ground state). Fall back literally if the
+    // array is empty (defensive — should never happen).
+    return PERMISSION_MODES[0] ?? 'default';
+}
+//# sourceMappingURL=plan.js.map

package/dist/runtime/commands/prd-check.js

@@ -0,0 +1,285 @@
+/**
+ * `pugi prd-check` — Pugi  verified-deliverable gate .
+ *
+ * Runs a PRD ↔ delivered-artifact verification sweep BEFORE the
+ * operator (or an autonomous agent) claims a feature is done.
+ * Reads `docs/prd/<feature>.md` (or any explicit path), parses the
+ * acceptance-criteria section, and runs file / test / doc / command
+ * / route verifiers per criterion. Output mirrors `pugi doctor`:
+ * either a plain-text table or a JSON envelope (`--json`).
+ *
+ * Module contract (mirrors L17 doctor split):
+ *
+ *  - parser + verifiers + reporter are pure with respect to deps;
+ *    this file is the THIN wiring that resolves cwd, glob-expands
+ *    `--all`, loads each PRD, and forwards the structured result
+ *    к the supplied writeOutput sink.
+ *
+ *  - `runPrdCheckCommand` is the single entry point. Both the
+ *    top-level `pugi prd-check` shell command AND the in-REPL
+ *    `/prd-check` slash command call it. The function returns the
+ *    `PrdCheckEnvelope[]` so the REPL can render via Ink without
+ *    re-running the verification.
+ *
+ *  - Exit codes follow `exitCodeFor` from the reporter:
+ *      0 — healthy (every criterion PASS or SKIPPED)
+ *      1 — failing (≥1 FAIL across the scanned PRDs)
+ *      2 — unparsed (≥1 PRD missing the acceptance section)
+ *    When `--all` scans multiple PRDs the worst verdict wins (1 > 2 > 0).
+ *
+ *  - The `knownCommands` set is sourced from the CLI registry — we
+ *    accept it as an injected parameter so the spec can drive
+ *    command-verification without importing the entire cli.ts
+ *    module (which would pull the engine graph into the test).
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { parsePrd } from '../../core/prd-check/parser.js';
+import { buildEnvelope, exitCodeFor, renderTable, } from '../../core/prd-check/reporter.js';
+import { defaultSessionReviewDeps, renderSessionReview, runSessionReview, } from '../../core/prd-check/session-review.js';
+import { createDefaultDeps, verifyAll, } from '../../core/prd-check/verifiers.js';
+const DEFAULT_PRD_DIR = 'docs/prd';
+/**
+ * Run the gate. Resolves which PRDs to inspect, runs the parser +
+ * verifiers + reporter chain per PRD, emits the combined output,
+ * and sets `process.exitCode` to the worst verdict across the set.
+ */
+export async function runPrdCheckCommand(ctx) {
+    // final : session-review mode. Orthogonal to
+    // the verifier-graph mode — no PRD path resolution, no command
+    // registry. The runner walks up for PRD.md, reads the NDJSON
+    // events log, and dispatches a cross-review subagent.
+    if (ctx.flags.session) {
+        const status = (line) => {
+            // Emit status lines through the output sink so the slash
+            // surface can render them inline. The status payload is
+            // intentionally lightweight — only the human-facing text.
+            ctx.writeOutput({
+                command: 'prd-check',
+                overall: 'healthy',
+                envelopes: [],
+            }, line);
+        };
+        const sessionDeps = ctx.sessionDeps ??
+            defaultSessionReviewDeps({ onStatus: status });
+        const review = await runSessionReview(ctx.cwd, sessionDeps);
+        const overall = review.status === 'ok'
+            ? review.outstanding.length === 0
+                ? 'healthy'
+                : 'failing'
+            : 'unparsed';
+        const result = {
+            command: 'prd-check',
+            overall,
+            envelopes: [],
+            sessionReview: review,
+        };
+        ctx.writeOutput(result, renderSessionReview(review));
+        process.exitCode = exitCodeFor(overall);
+        return result;
+    }
+    const paths = resolveTargets(ctx);
+    if (paths.length === 0) {
+        const result = {
+            command: 'prd-check',
+            overall: 'unparsed',
+            envelopes: [],
+        };
+        ctx.writeOutput(result, 'No PRD files found.');
+        process.exitCode = exitCodeFor('unparsed');
+        return result;
+    }
+    const deps = ctx.deps ??
+        createDefaultDeps({
+            workspaceRoot: ctx.cwd,
+            knownCommands: ctx.knownCommands,
+        });
+    const envelopes = [];
+    for (const path of paths) {
+        envelopes.push(checkSinglePrd(path, ctx.cwd, deps));
+    }
+    const overall = combineOverall(envelopes.map((e) => e.overall));
+    const result = {
+        command: 'prd-check',
+        overall,
+        envelopes,
+    };
+    const text = renderRun(result, ctx.cwd);
+    ctx.writeOutput(result, text);
+    process.exitCode = exitCodeFor(overall);
+    return result;
+}
+/**
+ * Render the combined plain-text view. Multi-PRD runs print one
+ * table per envelope separated by a divider; single-PRD runs print
+ * just the table to keep the output narrow.
+ */
+function renderRun(result, cwd) {
+    if (result.envelopes.length === 0) {
+        return 'No PRD files found.';
+    }
+    if (result.envelopes.length === 1) {
+        return renderTable(result.envelopes[0]);
+    }
+    const parts = [];
+    for (const envelope of result.envelopes) {
+        const relPath = relative(cwd, envelope.prdPath) || envelope.prdPath;
+        parts.push(renderTable({ ...envelope, prdPath: relPath }));
+        parts.push('');
+    }
+    parts.push('-'.repeat(50));
+    const summary = `${result.envelopes.length} PRD(s) scanned. Overall: ${result.overall.toUpperCase()}`;
+    parts.push(summary);
+    return parts.join('\n');
+}
+function checkSinglePrd(prdPath, workspaceRoot, deps) {
+    let source;
+    try {
+        source = readFileSync(prdPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            command: 'prd-check',
+            prdPath: relative(workspaceRoot, prdPath) || prdPath,
+            title: null,
+            overall: 'unparsed',
+            counts: { pass: 0, fail: 0, skipped: 0 },
+            criteria: [
+                {
+                    index: 0,
+                    text: `PRD file unreadable: ${message}`,
+                    status: 'fail',
+                    results: [],
+                },
+            ],
+        };
+    }
+    const parsed = parsePrd(source);
+    const verified = verifyAll(parsed.criteria, deps);
+    return buildEnvelope({
+        prdPath: relative(workspaceRoot, prdPath) || prdPath,
+        title: parsed.title,
+        hasAcceptanceSection: parsed.hasAcceptanceSection,
+        verified,
+    });
+}
+function resolveTargets(ctx) {
+    if (ctx.flags.all) {
+        const prdDir = resolve(ctx.cwd, DEFAULT_PRD_DIR);
+        return listMarkdownFiles(prdDir);
+    }
+    if (ctx.prdPath) {
+        const absolute = isAbsolute(ctx.prdPath)
+            ? ctx.prdPath
+            : resolve(ctx.cwd, ctx.prdPath);
+        return [absolute];
+    }
+    return [];
+}
+function listMarkdownFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        let isDirectory = false;
+        try {
+            isDirectory = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDirectory) {
+            out.push(...listMarkdownFiles(full));
+            continue;
+        }
+        if (entry.endsWith('.md')) {
+            out.push(full);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Combine per-PRD verdicts into the run-wide one. failing > unparsed > healthy.
+ * Exported for the spec.
+ */
+export function combineOverall(verdicts) {
+    if (verdicts.length === 0)
+        return 'unparsed';
+    if (verdicts.some((v) => v === 'failing'))
+        return 'failing';
+    if (verdicts.some((v) => v === 'unparsed'))
+        return 'unparsed';
+    return 'healthy';
+}
+/**
+ * Parse the CLI argv tail. Accepts:
+ *
+ *  pugi prd-check                      -> error (no target)
+ *  pugi prd-check <path>               -> single PRD
+ *  pugi prd-check --all                -> scan docs/prd/**.md
+ *  pugi prd-check <path> --json        -> single PRD, JSON envelope
+ *
+ * `--json` is also forwarded from the global flag set in cli.ts;
+ * the local parse re-honours it so the slash command can use the
+ * same parser without the global flag plumbing.
+ */
+export function parsePrdCheckArgs(args, options) {
+    let json = options.jsonDefault;
+    let all = false;
+    let session = false;
+    let prdPath;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--all') {
+            all = true;
+            continue;
+        }
+        if (arg === '--session') {
+            session = true;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            return { ok: false, error: `unknown flag: ${arg}` };
+        }
+        if (prdPath !== undefined) {
+            return { ok: false, error: `unexpected extra argument: ${arg}` };
+        }
+        prdPath = arg;
+    }
+    // final : `--session` is mutually exclusive with
+    // the verifier modes — it walks up for a PRD, reads NDJSON turns,
+    // and dispatches a subagent. No <path>, no --all, no command-
+    // registry inputs. Validating up-front gives operators a clear
+    // error instead of a silent fall-through.
+    if (session && (all || prdPath !== undefined)) {
+        return {
+            ok: false,
+            error: 'cannot combine --session with --all or <path>',
+        };
+    }
+    if (!session && !all && prdPath === undefined) {
+        return {
+            ok: false,
+            error: 'pugi prd-check <prd-path> | --all | --session  (pass a PRD path, --all to scan docs/prd/**.md, or --session to review the live session against PRD.md)',
+        };
+    }
+    if (all && prdPath !== undefined) {
+        return { ok: false, error: 'cannot combine <path> with --all' };
+    }
+    return {
+        ok: true,
+        flags: { json, all, session },
+        ...(prdPath !== undefined ? { prdPath } : {}),
+    };
+}
+//# sourceMappingURL=prd-check.js.map

package/dist/runtime/commands/privacy.js

@@ -7,22 +7,22 @@ import { dirname, resolve } from 'node:path';
  * `pugi privacy` — read or update the operator's privacy mode.
  *
  * Subcommands:
- *   - `pugi privacy show`           — print current mode + source
- *   - `pugi privacy set <mode>`     — write `local-only | metadata | full`
+ *  - `pugi privacy show`          — print current mode + source
+ *  - `pugi privacy set <mode>`    — write `local-only | metadata | full`
  *
  * Persistence:
- *   - Stored in `~/.pugi/privacy.json` (PUGI_HOME-aware).
- *   - The `privacy` key in `~/.pugi/config.json` is also consulted at
- *     read time (config takes precedence when both exist) so a user who
- *     already set `pugi config set privacy ...` sees the same value
- *     here.
+ *  - Stored in `~/.pugi/privacy.json` (PUGI_HOME-aware).
+ *  - The `privacy` key in `~/.pugi/config.json` is also consulted at
+ *    read time (config takes precedence when both exist) so a user who
+ *    already set `pugi config set privacy ...` sees the same value
+ *    here.
  *
  * Modes:
- *   - `local-only` — nothing leaves the workstation. Engine commands
- *     refuse to ship transcripts; sync is a no-op.
- *   - `metadata`   — only artifact metadata + session timeline ships
- *     (no raw file contents).
- *   - `full`       — full sync allowed (operator-acknowledged).
+ *  - `local-only` — nothing leaves the workstation. Engine commands
+ *    refuse to ship transcripts; sync is a no-op.
+ *  - `metadata`  — only artifact metadata + session timeline ships
+ *    (no raw file contents).
+ *  - `full`      — full sync allowed (operator-acknowledged).
  */
 export const privacyModeSchema = z.enum(['local-only', 'metadata', 'full']);
 const privacyFileSchema = z.object({
@@ -53,9 +53,9 @@ function writePrivacyFile(mode) {
 }
 /**
  * Effective privacy mode resolution order:
- *   1. `~/.pugi/config.json` privacy key (when set via `pugi config set`)
- *   2. `~/.pugi/privacy.json` (when set via `pugi privacy set`)
- *   3. `metadata` (default — matches the M1 default-ship posture)
+ *  1. `~/.pugi/config.json` privacy key (when set via `pugi config set`)
+ *  2. `~/.pugi/privacy.json` (when set via `pugi privacy set`)
+ *  3. `metadata` (default — matches the M1 default-ship posture)
  */
 export function resolvePrivacyMode() {
     const config = readConfig();
@@ -75,8 +75,8 @@ export async function runPrivacyCommand(args, ctx) {
             modes: ['local-only', 'metadata', 'full'],
         }, [
             'Usage:',
-            '  pugi privacy show           Show current privacy mode.',
-            '  pugi privacy set <mode>     Set mode to local-only, metadata, or full.',
+            ' pugi privacy show          Show current privacy mode.',
+            ' pugi privacy set <mode>    Set mode to local-only, metadata, or full.',
         ].join('\n'));
         return;
     }