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

package/dist/runtime/commands/feedback.js

@@ -0,0 +1,184 @@
+/**
+ * `pugi feedback` + `/feedback` slash — .
+ *
+ * In-CLI feedback collector. Parity with the upstream tool's `/feedback`
+ * built-in. The operator never has to leave the terminal to file a
+ * bug / feature / general comment / praise. The wizard collects:
+ *
+ *  1. category  (bug / feature / general / praise)
+ *  2. rating    (1-5)
+ *  3. comment   (multi-line free text)
+ *  4. optional  redacted session context (last 5 turns)
+ *  5. confirm   (final y/n)
+ *
+ * # Module contract
+ *
+ *  - This file owns the WIRING from the CLI surface (TTY mount,
+ *    non-TTY JSON, slash dispatcher) to the queue + submitter
+ *    modules. The corpus + redactor + queue persistence live in
+ *    `core/feedback/{queue.ts,submitter.ts}`. The Ink prompt lives
+ *    in `tui/feedback-prompt.tsx`. Both have zero coupling to the
+ *    CLI dispatch surface.
+ *
+ *  - `runFeedbackCommand` is the single entry point. Both the top-
+ *    level `pugi feedback` handler в `runtime/cli.ts` AND the in-REPL
+ *    `/feedback` slash dispatcher call it. The function returns the
+ *    resolved `FeedbackRunResult` so the slash dispatcher can route
+ *    the outcome message to the REPL's system pane without re-prompting.
+ *
+ *  - Exit code is ALWAYS 0. Feedback is a brand surface — never a
+ *    gate. Failures land as result variants; the wrapper never
+ *    turns a network blip into a non-zero shell exit.
+ *
+ *  - The random-source-style test seam: the run helper accepts an
+ *    `interactive` flag that the spec sets to false, plus an injected
+ *    `draft` so unit tests can drive the submit + queue branches
+ *    without mounting Ink.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { enqueueFeedback, feedbackQueuePath, flushFeedbackQueue, } from '../../core/feedback/queue.js';
+import { feedbackSubmitUrl, redactSessionContext, submitFeedback, } from '../../core/feedback/submitter.js';
+/**
+ * Drive one feedback round. The function is async because of the
+ * submit round-trip, but everything else (queue write, redaction) is
+ * sync — no surprise concurrency.
+ */
+export async function runFeedbackCommand(ctx) {
+    if (ctx.draft == null) {
+        return { kind: 'cancelled' };
+    }
+    const envelope = {
+        category: ctx.draft.category,
+        rating: ctx.draft.rating,
+        comment: ctx.draft.comment,
+        ts: new Date().toISOString(),
+        cliVersion: ctx.cliVersion,
+        ...(ctx.tier ? { tier: ctx.tier } : {}),
+    };
+    if (ctx.draft.includeSessionContext && ctx.sessionContext) {
+        const sc = ctx.sessionContext();
+        if (sc)
+            envelope.sessionContext = sc;
+    }
+    let result;
+    try {
+        result = await ctx.submit(envelope);
+    }
+    catch (err) {
+        // Defensive: a thrown submitter (should not happen — the live
+        // submitter catches everything) is treated as transient so the
+        // envelope lands in the queue.
+        const reason = err instanceof Error ? err.message : String(err);
+        result = { kind: 'transient', reason };
+    }
+    if (result.kind === 'ok') {
+        return { kind: 'submitted', envelope, httpStatus: result.httpStatus };
+    }
+    if (result.kind === 'transient') {
+        const path = enqueueFeedback(envelope, ctx.cwd);
+        return { kind: 'queued', envelope, path, reason: result.reason };
+    }
+    // permanent — log + drop
+    return {
+        kind: 'dropped',
+        envelope,
+        reason: result.reason,
+        httpStatus: result.httpStatus,
+    };
+}
+/**
+ * Render one human-readable toast for the operator. Centralised so the
+ * top-level `pugi feedback` shell handler + the in-REPL `/feedback`
+ * slash dispatcher agree on the copy.
+ */
+export function renderFeedbackToast(result) {
+    switch (result.kind) {
+        case 'submitted':
+            return 'Feedback submitted. Thank you.';
+        case 'queued':
+            return `Feedback queued locally. Will sync on next online run. (${result.path})`;
+        case 'cancelled':
+            return 'Feedback cancelled. Nothing was sent.';
+        case 'dropped':
+            return `Feedback rejected by server (${result.httpStatus}): ${result.reason}. Not queued.`;
+        case 'noop':
+            return `No feedback collected: ${result.reason}`;
+    }
+}
+/**
+ * Background queue flush. Invoked silently on session start so any
+ * envelopes that landed during an offline run get drained when the
+ * operator next has connectivity. The function never throws — it
+ * returns the flush stats so the caller can log them at debug level.
+ */
+export async function flushFeedbackQueueSilently(cwd, config) {
+    // Short-circuit when the queue file does not exist. Avoids a
+    // pointless `fs.stat` round-trip on every cold session start.
+    if (!existsSync(feedbackQueuePath(cwd))) {
+        return { attempted: 0, succeeded: 0, failed: 0 };
+    }
+    const result = await flushFeedbackQueue(cwd, async (env) => {
+        const r = await submitFeedback(env, config);
+        if (r.kind === 'ok')
+            return true;
+        if (r.kind === 'permanent') {
+            // Permanent failures are "done" from the queue's POV — they
+            // would never resolve on retry. Drop them so the queue does
+            // not grow without bound.
+            return true;
+        }
+        return false;
+    });
+    return {
+        attempted: result.attempted,
+        succeeded: result.succeeded,
+        failed: result.failed,
+    };
+}
+/**
+ * Re-exports — the spec imports these via the command module so the
+ * dependency graph in the test stays single-rooted.
+ */
+export { feedbackQueuePath, feedbackSubmitUrl, redactSessionContext, submitFeedback, };
+/**
+ * Read the persona conversation log if present. Best-effort: returns
+ * an empty list when the file is missing or malformed. The CLI's REPL
+ * persists transcripts via the session module at a canonical relative
+ * path under `.pugi/sessions/`. The shell-level `pugi feedback` does
+ * not have access to a live session, so it tries to pick up the most
+ * recent persisted one for the `--with-context` path.
+ *
+ * Intentionally tolerant — feedback works even with no transcript.
+ */
+export function readMostRecentTranscript(cwd, options = {}) {
+    // The CLI may persist sessions in several places depending on the
+    // surface. We probe the conventional default; the spec drives the
+    // function via a fixture file instead of a live REPL.
+    const candidate = resolve(cwd, '.pugi', 'sessions', 'latest.jsonl');
+    if (!existsSync(candidate))
+        return [];
+    try {
+        const text = readFileSync(candidate, 'utf8');
+        const lines = text.split('\n').filter((l) => l.trim().length > 0);
+        const turns = [];
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                if ((obj.role === 'user' || obj.role === 'assistant' || obj.role === 'system')
+                    && typeof obj.text === 'string') {
+                    turns.push({ role: obj.role, text: obj.text });
+                }
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        const cap = options.maxTurns ?? 5;
+        return turns.slice(-cap);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/runtime/commands/hooks.js

@@ -0,0 +1,187 @@
+/**
+ * `pugi hooks` — operator surface for user-config hooks (MVP).
+ *
+ * Two subcommands ship in the MVP:
+ *
+ *  pugi hooks list        List configured hooks per event.
+ *  pugi hooks doctor      Validate the config and surface any
+ *                          parse / schema errors.
+ *
+ * Both accept `--json` for scripted callers. Argument grammar is
+ * intentionally narrow — no `add` / `remove` / `test` subcommands in
+ * the MVP. Operators hand-edit `~/.pugi/hooks-mvp.json` for now.
+ *
+ * Exit codes:
+ *  0 -> happy path (no hooks OR config valid).
+ *  1 -> config present but invalid (only `doctor` returns this).
+ *  2 -> unknown subcommand / argument error.
+ *
+ * Brand voice: ASCII only.
+ */
+import { ALL_HOOK_EVENTS_V2, defaultHooksMvpPath, loadHooksConfig, } from '../../core/hooks/index.js';
+function parseFlags(args) {
+    const rest = [];
+    const flags = { json: false };
+    for (const arg of args) {
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { rest, flags };
+}
+/**
+ * Top-level dispatcher for `pugi hooks <subcommand>`. Returns the
+ * intended process exit code. `cli.ts` is expected to set
+ * `process.exitCode = <return value>` so error states propagate to
+ * scripted callers without throwing.
+ */
+export async function runHooksCommand(args, ctx) {
+    const { rest, flags } = parseFlags(args);
+    const sub = rest[0];
+    if (!sub || sub === 'help' || sub === '--help') {
+        emitUsage(ctx, flags);
+        return sub ? 0 : 2;
+    }
+    if (sub === 'list') {
+        return runList(ctx, flags);
+    }
+    if (sub === 'doctor') {
+        return runDoctor(ctx, flags);
+    }
+    ctx.writeOutput({ ok: false, error: `unknown subcommand: ${sub}` }, `pugi hooks: unknown subcommand '${sub}'. Try 'pugi hooks --help'.`);
+    return 2;
+}
+function emitUsage(ctx, flags) {
+    const text = [
+        'pugi hooks — user-config lifecycle hooks (MVP).',
+        '',
+        'Subcommands:',
+        ' pugi hooks list       Show hooks configured per event.',
+        ' pugi hooks doctor     Validate ~/.pugi/hooks-mvp.json.',
+        '',
+        'Flags:',
+        ' --json                Emit a JSON envelope instead of human text.',
+        '',
+        'Config file:',
+        ' ~/.pugi/hooks-mvp.json',
+        '',
+        'Status:',
+        ' MVP — 2 events out of 8. Remaining events (PostToolUse,',
+        " UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification)",
+        ' deferred to fast-follow PR.',
+    ].join('\n');
+    ctx.writeOutput({
+        ok: true,
+        command: 'hooks',
+        usage: text,
+    }, text);
+    if (flags.json) {
+        // The structured payload is already emitted by writeOutput when
+        // --json is on; nothing extra to do.
+    }
+}
+function runList(ctx, flags) {
+    let config;
+    try {
+        config = loadHooksConfig(ctx.configPath);
+    }
+    catch (error) {
+        const msg = error.message;
+        ctx.writeOutput({ ok: false, error: msg }, `pugi hooks list: ${msg}\nFix the config or remove the file. Run 'pugi hooks doctor' for details.`);
+        return 1;
+    }
+    const perEvent = {
+        SessionStart: [],
+        PreToolUse: [],
+        PostToolUse: [],
+        UserPromptSubmit: [],
+        Stop: [],
+        SubagentStop: [],
+        PreCompact: [],
+        Notification: [],
+        // PUGI-487 - worktree lifecycle events.
+        WorktreeCreate: [],
+        WorktreeRemove: [],
+    };
+    for (const event of ALL_HOOK_EVENTS_V2) {
+        perEvent[event] = config.list(event).map((entry) => ({
+            matcher: entry.matcher,
+            command: entry.command,
+            timeoutMs: entry.timeoutMs,
+            blocking: entry.blocking,
+        }));
+    }
+    const total = Object.values(perEvent).reduce((acc, list) => acc + list.length, 0);
+    const payload = {
+        ok: true,
+        configPath: config.configPath(),
+        total,
+        perEvent,
+    };
+    if (flags.json) {
+        ctx.writeOutput(payload, JSON.stringify(payload, null, 2));
+        return 0;
+    }
+    const lines = [];
+    lines.push(`pugi hooks (${total} configured)`);
+    lines.push(` config: ${config.configPath()}`);
+    if (total === 0) {
+        lines.push(' no hooks configured — create the file above to add one.');
+    }
+    else {
+        for (const event of ALL_HOOK_EVENTS_V2) {
+            const list = perEvent[event];
+            if (list.length === 0)
+                continue;
+            lines.push(` ${event}:`);
+            for (const entry of list) {
+                const tags = [];
+                if (entry.matcher)
+                    tags.push(`matcher=${entry.matcher}`);
+                if (entry.timeoutMs)
+                    tags.push(`timeoutMs=${entry.timeoutMs}`);
+                if (entry.blocking)
+                    tags.push('blocking');
+                const suffix = tags.length ? ` [${tags.join(', ')}]` : '';
+                lines.push(`   - ${entry.command}${suffix}`);
+            }
+        }
+    }
+    const text = lines.join('\n');
+    ctx.writeOutput(payload, text);
+    return 0;
+}
+function runDoctor(ctx, flags) {
+    const path = ctx.configPath ?? defaultHooksMvpPath();
+    try {
+        const config = loadHooksConfig(ctx.configPath);
+        const total = config.flatten().length;
+        const payload = {
+            ok: true,
+            configPath: config.configPath(),
+            total,
+            issues: [],
+        };
+        const text = total
+            ? `pugi hooks doctor: ${path} OK (${total} hooks).`
+            : `pugi hooks doctor: ${path} not present (no hooks configured).`;
+        ctx.writeOutput(payload, text);
+        return 0;
+    }
+    catch (error) {
+        const msg = error.message;
+        const payload = {
+            ok: false,
+            configPath: path,
+            error: msg,
+        };
+        const text = `pugi hooks doctor: ${msg}`;
+        ctx.writeOutput(payload, text);
+        return 1;
+    }
+    // flags.json is consumed by writeOutput in the host shell.
+    void flags;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/runtime/commands/init.js

@@ -0,0 +1,254 @@
+/**
+ * `pugi init` codebase scan → PUGI.md auto-gen (backlog #82).
+ *
+ * Extends the existing `init()` scaffold with a project-aware PUGI.md
+ * generator. Runs AFTER `scaffoldPugiWorkspace` so the `.pugi/` workspace
+ * exists for the `init-report.json` write.
+ *
+ * Flow:
+ *
+ *  1. Detect existing PUGI.md. If present without `--force`, refuse
+ *     with `refused_existing`.
+ *  2. Run `detectWorkspace` against cwd.
+ *  3. Render PUGI.md content for the requested style.
+ *  4. Confirm with the operator unless `--yes` / `--json` / `--force`.
+ *  5. Write `<cwd>/PUGI.md` atomically (tmp + rename, fallback к
+ *     direct write on EXDEV — happens когда tmp lives на a different
+ *     volume).
+ *  6. Write `.pugi/init-report.json` (mode 0o600) with the raw
+ *     detection payload for re-runs / auditing.
+ *  7. Emit a JSON envelope describing the outcome.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { detectWorkspace } from '../../core/init/detector.js';
+import { renderPugiMd, STYLE_WORD_CAPS, } from '../../core/init/template-renderer.js';
+export const DEFAULT_PUGI_MD_STYLE = 'standard';
+/** Entry point invoked by `cli.ts::init`. */
+export async function runInitScanCommand(args, ctx) {
+    const cwd = resolve(ctx.cwd);
+    const pugiMdPath = join(cwd, 'PUGI.md');
+    const reportPath = join(cwd, '.pugi', 'init-report.json');
+    // `args` is currently consumed only via flags. Keep the parameter to
+    // mirror every other command surface so we can grow positional args
+    // (e.g. an explicit target path) without breaking the call site.
+    void args;
+    try {
+        if (existsSync(pugiMdPath) && !ctx.force) {
+            const envelope = {
+                command: 'init-scan',
+                status: 'refused_existing',
+                pugiMdPath,
+                reportPath,
+                style: ctx.style,
+                message: 'PUGI.md already exists. Re-run with --force to overwrite, or edit by hand.',
+            };
+            ctx.writeOutput(envelope, formatHuman(envelope));
+            return envelope;
+        }
+        const detection = detectWorkspace(cwd);
+        const rendered = renderPugiMd(detection, { style: ctx.style, now: ctx.now });
+        const shouldConfirm = !ctx.yes && !ctx.json && !ctx.force;
+        if (shouldConfirm) {
+            const confirm = ctx.confirm ?? defaultConfirm;
+            const ok = await confirm(`Write PUGI.md at ${pugiMdPath} (${rendered.wordCount} words, style: ${ctx.style})? [y/N] `);
+            if (!ok) {
+                const envelope = {
+                    command: 'init-scan',
+                    status: 'aborted',
+                    pugiMdPath,
+                    reportPath,
+                    style: ctx.style,
+                    message: 'Aborted by operator before write.',
+                };
+                ctx.writeOutput(envelope, formatHuman(envelope));
+                return envelope;
+            }
+        }
+        atomicWrite(pugiMdPath, rendered.content);
+        writeReport(reportPath, detection, rendered.wordCount, ctx.style);
+        const envelope = {
+            command: 'init-scan',
+            status: 'written',
+            pugiMdPath,
+            reportPath,
+            detection,
+            wordCount: rendered.wordCount,
+            style: ctx.style,
+        };
+        ctx.writeOutput(envelope, formatHuman(envelope));
+        return envelope;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const envelope = {
+            command: 'init-scan',
+            status: 'error',
+            pugiMdPath,
+            reportPath,
+            style: ctx.style,
+            message,
+        };
+        ctx.writeOutput(envelope, formatHuman(envelope));
+        return envelope;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Atomic write                                                      */
+/* ------------------------------------------------------------------ */
+function atomicWrite(targetPath, content) {
+    const dir = dirname(targetPath);
+    mkdirSync(dir, { recursive: true });
+    const tmpName = `.pugi-md-${process.pid}-${Date.now()}.tmp`;
+    const tmpPath = join(tmpdir(), tmpName);
+    try {
+        writeFileSync(tmpPath, content, { encoding: 'utf8', mode: 0o644 });
+        renameSync(tmpPath, targetPath);
+        return;
+    }
+    catch (error) {
+        // EXDEV — cross-device link: tmpdir lives on a different volume
+        // than the workspace. Retry with the tmpfile inside the workspace.
+        cleanupTmp(tmpPath);
+        const code = error.code;
+        if (code !== 'EXDEV') {
+            // Fall through to the in-dir fallback for any rename failure so
+            // we keep the contract: PUGI.md is either fully written or not
+            // written. The direct writeFileSync at the end is the final
+            // safety net.
+        }
+        const localTmpPath = join(dir, `.pugi-md-${process.pid}-${Date.now()}.tmp`);
+        try {
+            writeFileSync(localTmpPath, content, { encoding: 'utf8', mode: 0o644 });
+            renameSync(localTmpPath, targetPath);
+            return;
+        }
+        catch {
+            cleanupTmp(localTmpPath);
+        }
+        // Final fallback — direct write. We sacrifice the atomicity guarantee
+        // here but keep behavioural correctness when both the tmp + in-dir
+        // strategies fail (rare; usually FS quirks).
+        writeFileSync(targetPath, content, { encoding: 'utf8', mode: 0o644 });
+    }
+}
+function cleanupTmp(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // best effort
+    }
+}
+function writeReport(reportPath, detection, wordCount, style) {
+    mkdirSync(dirname(reportPath), { recursive: true });
+    const payload = {
+        generatedAt: new Date().toISOString(),
+        style,
+        wordCap: STYLE_WORD_CAPS[style],
+        wordCount,
+        detection,
+    };
+    writeFileSync(reportPath, JSON.stringify(payload, null, 2), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        chmodSync(reportPath, 0o600);
+    }
+    catch {
+        // Some filesystems (FAT, NTFS over CIFS) reject chmod; the mode
+        // option on writeFileSync is the primary guard. Best-effort here.
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Confirm prompt                                                    */
+/* ------------------------------------------------------------------ */
+async function defaultConfirm(question) {
+    if (process.stdin.isTTY !== true) {
+        return true;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolveAnswer) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            rl.close();
+            resolveAnswer(value);
+        };
+        rl.once('close', () => settle(false));
+        rl.question(question, (answer) => {
+            settle(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Human-readable formatting                                         */
+/* ------------------------------------------------------------------ */
+function formatHuman(env) {
+    switch (env.status) {
+        case 'written':
+            return [
+                `PUGI.md written to ${env.pugiMdPath}`,
+                ` Style:     ${env.style}`,
+                ` Word count: ${env.wordCount ?? 0}`,
+                ` Report:    ${env.reportPath}`,
+            ].join('\n');
+        case 'refused_existing':
+            return env.message ?? 'PUGI.md already exists. Use --force to overwrite.';
+        case 'aborted':
+            return env.message ?? 'Aborted.';
+        case 'error':
+            return `pugi init scan failed: ${env.message ?? 'unknown error'}`;
+        default:
+            return 'pugi init scan complete.';
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Helpers consumed by cli.ts                                        */
+/* ------------------------------------------------------------------ */
+/** Parse `--style=<minimal|standard|detailed>` (or `--style minimal`). */
+export function parseInitStyle(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (typeof arg !== 'string')
+            continue;
+        if (arg.startsWith('--style=')) {
+            const value = arg.slice('--style='.length);
+            const parsed = coerceStyle(value);
+            if (parsed)
+                return parsed;
+        }
+        else if (arg === '--style') {
+            const next = args[i + 1];
+            if (typeof next === 'string') {
+                const parsed = coerceStyle(next);
+                if (parsed)
+                    return parsed;
+            }
+        }
+    }
+    return DEFAULT_PUGI_MD_STYLE;
+}
+function coerceStyle(value) {
+    if (value === 'minimal' || value === 'standard' || value === 'detailed')
+        return value;
+    return null;
+}
+/** Test surface: read back the on-disk report. */
+export function readInitReport(reportPath) {
+    try {
+        return JSON.parse(readFileSync(reportPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=init.js.map