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

package/dist/runtime/commands/sessions.js

@@ -0,0 +1,163 @@
+/**
+ * `pugi sessions` extensions — .
+ *
+ * The legacy `pugi sessions` handler lives inline in `runtime/cli.ts`
+ * (it predates the per-command runner pattern). This module exposes the
+ * new sub-commands the L9 sprint adds:
+ *
+ *  - `pugi sessions undo-rewind [<session-id>]`
+ *      Append an inverse marker that nullifies the latest 'rewind'
+ *      marker on the target session. Operator escape hatch: nothing
+ *      is destroyed, the masked range simply becomes visible again.
+ *
+ * Wire pattern matches `runCompactCommand` / `runRewindCommand`: one
+ * structured payload + one human line per invocation, returned to the
+ * caller for the JSON path.
+ */
+import { homedir } from 'node:os';
+import { slugForCwd } from '../../core/repl/history.js';
+import { appendRewindMarker, findLatestActiveRewind, } from '../../core/checkpoint/rewinder.js';
+import { loadFromStore } from '../../core/checkpoint/resumer.js';
+import { SqliteSessionStore, resolveProjectStoreDir, } from '../../core/repl/store/session-store.js';
+/**
+ * Sub-command router. The caller passes the full positional args; we
+ * peel `args[0]` as the sub-command name and forward the tail. Unknown
+ * sub-commands surface a usage hint at exit code 2.
+ */
+export async function runSessionsCommand(args, ctx) {
+    const sub = args[0];
+    if (sub === 'undo-rewind') {
+        return runUndoRewind(args.slice(1), ctx);
+    }
+    // Other sub-commands (the legacy `pugi sessions` list path) are
+    // owned by runtime/cli.ts — return null so the caller knows to fall
+    // through to that handler.
+    return null;
+}
+async function runUndoRewind(args, ctx) {
+    const explicitId = args[0] && !args[0].startsWith('--') ? args[0] : undefined;
+    const slug = slugForCwd(ctx.workspaceRoot);
+    let store = ctx.store ?? null;
+    let sessionId = ctx.sessionId ?? explicitId ?? null;
+    let storeOpenedHere = false;
+    if (store === null) {
+        sessionId = sessionId ?? (await pickMostRecentSessionIdReadOnly(slug));
+        if (!sessionId) {
+            return emit(ctx, {
+                command: 'sessions',
+                sub: 'undo-rewind',
+                status: 'failed_no_session',
+                reason: 'No session to undo-rewind. Start a REPL with `pugi`.',
+            });
+        }
+        const opened = await openLiveStore(slug, sessionId);
+        if (!opened) {
+            return emit(ctx, {
+                command: 'sessions',
+                sub: 'undo-rewind',
+                status: 'failed_store',
+                sessionId,
+                reason: 'Could not open local session store (lock held by another REPL?).',
+            });
+        }
+        store = opened;
+        storeOpenedHere = true;
+    }
+    else if (sessionId === null) {
+        const rows = await store.listSessions({ project: slug, limit: 1, status: 'active' });
+        if (rows.length === 0) {
+            return emit(ctx, {
+                command: 'sessions',
+                sub: 'undo-rewind',
+                status: 'failed_no_session',
+                reason: 'No active session to undo-rewind.',
+            });
+        }
+        sessionId = rows[0].id;
+    }
+    try {
+        const loaded = await loadFromStore(store, sessionId);
+        if (!loaded) {
+            return emit(ctx, {
+                command: 'sessions',
+                sub: 'undo-rewind',
+                status: 'failed_no_session',
+                sessionId,
+                reason: `Session '${sessionId}' not found.`,
+            });
+        }
+        const latest = findLatestActiveRewind(loaded.rawEvents);
+        if (latest === null) {
+            return emit(ctx, {
+                command: 'sessions',
+                sub: 'undo-rewind',
+                status: 'noop_no_rewind',
+                sessionId,
+                reason: 'No active rewind to undo on this session.',
+            }, 'No active rewind to undo.');
+        }
+        const fromEventIndex = loaded.rawEvents.length;
+        await appendRewindMarker({
+            store,
+            mode: 'undo-rewind',
+            toEventIndex: latest.payload.toEventIndex,
+            fromEventIndex,
+            turnsRewound: latest.payload.turnsRewound,
+            reason: 'undo',
+            ...(ctx.now !== undefined ? { now: ctx.now } : {}),
+        });
+        return emit(ctx, {
+            command: 'sessions',
+            sub: 'undo-rewind',
+            status: 'undone',
+            sessionId,
+            undoneTurns: latest.payload.turnsRewound,
+        }, `Undid the latest rewind (${latest.payload.turnsRewound} turn${latest.payload.turnsRewound === 1 ? '' : 's'} restored).`);
+    }
+    finally {
+        if (storeOpenedHere && store) {
+            try {
+                await store.close();
+            }
+            catch {
+                /* idempotent */
+            }
+        }
+    }
+}
+function emit(ctx, payload, text) {
+    const human = text ?? payload.reason ?? `sessions ${payload.sub}: ${payload.status}`;
+    ctx.writeOutput(payload, human);
+    return payload;
+}
+async function openLiveStore(projectSlug, sessionId) {
+    try {
+        const store = new SqliteSessionStore({ projectSlug, home: homedir() });
+        await store.open({
+            id: sessionId,
+            workspaceRoot: process.cwd(),
+            projectSlug,
+        });
+        return store;
+    }
+    catch {
+        return null;
+    }
+}
+async function pickMostRecentSessionIdReadOnly(projectSlug) {
+    try {
+        const dir = resolveProjectStoreDir(projectSlug, homedir());
+        const view = await SqliteSessionStore.openReadOnly(dir);
+        try {
+            const rows = await view.list({ project: projectSlug, limit: 1, status: 'active' });
+            return rows.length > 0 ? rows[0].id : null;
+        }
+        finally {
+            await view.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/runtime/commands/share.js

@@ -0,0 +1,316 @@
+/**
+ * `pugi share` / `/share` command handler — .
+ *
+ * Exports the current session transcript as Markdown to either a GitHub
+ * Gist (default when `gh` is available + auth'd) or a pugi.io public URL
+ * (`--pugi`). Mirrors the standard tool's `/share` ergonomics — operator can
+ * pin a session for portfolio / debugging / team sharing without copy-
+ * pasting the REPL pane by hand.
+ *
+ * Subcommands / flags (see L20 spec):
+ *
+ *  pugi share               Default upload — picks gist when available,
+ *                             falls back to pugi.io.
+ *  pugi share --gist         Force gist target; refuses if `gh` is not
+ *                             installed / authenticated.
+ *  pugi share --pugi         Force pugi.io target.
+ *  pugi share --redact       Run PII scrubber first; shows finding
+ *                             counts in the privacy gate banner.
+ *  pugi share --preview      Print transcript to stdout WITHOUT
+ *                             upload. Always implies a redact step IF
+ *                             `--redact` is also set so the operator
+ *                             inspects the scrubbed shape, not the raw.
+ *  pugi share --yes          Skip the y/n confirmation prompt
+ *                             (CI / scripted callers). Default is
+ *                             ALWAYS to ask before uploading. Refuses
+ *                             if the heuristic detects an active
+ *                             `Bearer ` credential regardless of `--yes`.
+ *  pugi share --json         Emit the result envelope as JSON.
+ *
+ * Privacy gates (mandatory):
+ *
+ *  1. Active credential heuristic — refuses upload entirely when the
+ *     transcript contains a live `Bearer <token>` span. Operators who
+ *     want to share a debug session that captured an auth header MUST
+ *     run `--redact` first; the redactor masks the credential before
+ *     the upload path sees it.
+ *  2. Confirmation prompt — y/n question shown to the operator before
+ *     every upload. Bypassed with `--yes`. Refuses upload on `n` /
+ *     empty / Ctrl-C.
+ *  3. Redact preview — when `--redact` is set, the gate banner shows
+ *     the per-category finding counts BEFORE the upload prompt so the
+ *     operator sees what would leave the machine.
+ *
+ * Same handler powers both `pugi share` (top-level) and `/share`
+ * (in-REPL slash). The slash side wires `writeOutput` to the REPL's
+ * `appendSystemLine` and never hits stdout directly.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { formatTranscript } from '../../core/share/formatter.js';
+import { containsActiveCredential, redactPii, summariseFindings, } from '../../core/share/redactor.js';
+import { uploadShare, } from '../../core/share/uploader.js';
+export function parseShareFlags(args) {
+    const flags = {
+        target: 'auto',
+        redact: false,
+        preview: false,
+        yes: false,
+        json: false,
+    };
+    for (const arg of args) {
+        if (arg === '--gist')
+            flags.target = 'gist';
+        else if (arg === '--pugi')
+            flags.target = 'pugi';
+        else if (arg === '--redact')
+            flags.redact = true;
+        else if (arg === '--preview')
+            flags.preview = true;
+        else if (arg === '--yes' || arg === '-y')
+            flags.yes = true;
+        else if (arg === '--json')
+            flags.json = true;
+    }
+    return flags;
+}
+export async function runShareCommand(args, ctx) {
+    const flags = parseShareFlags(args);
+    const eventsPath = resolve(ctx.workspaceRoot, '.pugi/events.jsonl');
+    if (!existsSync(eventsPath)) {
+        ctx.writeOutput({
+            command: 'share',
+            status: 'no_session',
+            message: '.pugi/events.jsonl not found',
+        }, 'pugi share: no session log found. Run any pugi command first to create .pugi/events.jsonl.');
+        process.exitCode = 2;
+        return;
+    }
+    // Read + format. The formatter walks the events stream once; size cap
+    // is implicit (we do not chunk multi-GB files because session logs are
+    // capped at a few MB by the cost-tracker / compaction subsystems).
+    const eventsJsonl = readFileSync(eventsPath, 'utf8');
+    const sessionId = ctx.sessionId ?? deriveSessionIdFromEvents(eventsJsonl) ?? 'no-session';
+    const formatted = formatTranscript({
+        sessionId,
+        workspaceRoot: ctx.workspaceRoot,
+        cliVersion: ctx.cliVersion,
+        eventsJsonl,
+        now: ctx.now,
+    });
+    // Active-credential gate. Refuses even with `--yes`; redact-first IS
+    // the only path to share a transcript with a Bearer token. We check
+    // BEFORE redact so the operator's intent is clear in the gate banner.
+    const hasLiveCredential = containsActiveCredential(formatted.markdown);
+    if (hasLiveCredential && !flags.redact) {
+        ctx.writeOutput({
+            command: 'share',
+            status: 'refused_active_credential',
+            message: 'Transcript contains an active Bearer credential. Re-run with --redact to scrub it before sharing.',
+        }, 'pugi share: refused — transcript contains an active `Bearer ` credential. ' +
+            'Re-run with --redact to scrub it before sharing, or open .pugi/events.jsonl to inspect manually.');
+        process.exitCode = 4;
+        return;
+    }
+    // Optional redact pass. We run BEFORE the preview/upload decisions so
+    // the operator sees what would actually leave their machine.
+    let body = formatted.markdown;
+    let redactionSummary = null;
+    let redactionFindings = [];
+    if (flags.redact) {
+        const result = redactPii(body);
+        body = result.output;
+        redactionSummary = summariseFindings(result);
+        redactionFindings = result.findings;
+    }
+    // Preview path. Always non-destructive: prints the (possibly redacted)
+    // transcript + the redact summary, no upload, no prompt. Operators
+    // chain `--preview --redact` to see what would be shared before they
+    // commit, which is the L20 spec's "inspect first" affordance.
+    if (flags.preview) {
+        const payload = {
+            command: 'share',
+            status: 'preview',
+            sessionId,
+            turnCount: formatted.turnCount,
+            eventCount: formatted.eventCount,
+            redact: flags.redact,
+            redactionSummary,
+            redactionFindings,
+            markdown: body,
+        };
+        const text = [
+            redactionSummary ? `${redactionSummary}` : null,
+            '--- transcript preview (not uploaded) ---',
+            body,
+        ]
+            .filter((line) => line !== null)
+            .join('\n');
+        ctx.writeOutput(payload, text);
+        return;
+    }
+    // Resolve the target. `auto` picks gist if `gh` is available, else
+    // falls back to pugi.io. The probe is best-effort — a missing `gh`
+    // surfaces as `ghAvailable -> false` and we route to pugi without an
+    // error.
+    const resolvedTarget = await pickTarget(flags.target, ctx);
+    // Confirmation gate. Refused by default unless `--yes`.
+    if (!flags.yes) {
+        const promptText = redactionSummary
+            ? `${redactionSummary} Share session transcript to ${resolvedTarget}? [y/N] `
+            : `Share session transcript to ${resolvedTarget}? [y/N] `;
+        const answer = (await ((ctx.promptYesNo ?? defaultPromptYesNo)(promptText))).trim().toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            ctx.writeOutput({
+                command: 'share',
+                status: 'cancelled',
+                target: resolvedTarget,
+                message: 'Operator declined the upload.',
+            }, 'pugi share: cancelled.');
+            return;
+        }
+    }
+    // Resolve pugi.io credentials lazily — gist target does not need them.
+    let credential = null;
+    if (resolvedTarget === 'pugi') {
+        credential = ctx.resolveCredential ? await safeResolveCredential(ctx.resolveCredential) : null;
+    }
+    const uploadReq = {
+        target: resolvedTarget,
+        sessionId,
+        markdown: body,
+        description: `Pugi session ${sessionId}`,
+        ...(credential?.apiUrl !== undefined ? { apiUrl: credential.apiUrl } : {}),
+        ...(credential?.apiToken !== undefined ? { apiToken: credential.apiToken } : {}),
+        ...(ctx.execaLike !== undefined ? { execaLike: ctx.execaLike } : {}),
+        ...(ctx.fetchLike !== undefined ? { fetchLike: ctx.fetchLike } : {}),
+    };
+    const result = await uploadShare(uploadReq);
+    emitUploadResult(ctx, sessionId, resolvedTarget, redactionSummary, redactionFindings, result);
+}
+/**
+ * Default-target selection. `--gist` / `--pugi` are honoured verbatim;
+ * `auto` consults the `gh` probe and picks gist when available. We
+ * deliberately do not cache the probe — it costs one syscall and the
+ * operator might `gh auth login` between two `pugi share` runs.
+ */
+async function pickTarget(requested, ctx) {
+    if (requested === 'gist')
+        return 'gist';
+    if (requested === 'pugi')
+        return 'pugi';
+    // auto
+    const probe = ctx.ghAvailable ?? defaultGhAvailable(ctx.execaLike);
+    return (await probe()) ? 'gist' : 'pugi';
+}
+function defaultGhAvailable(execaLike) {
+    return async () => {
+        if (!execaLike) {
+            // Production: try to spawn `gh --version`. The default execa shim
+            // in uploader.ts is the right one but importing it here would
+            // create a small cycle; instead we replicate the minimal probe.
+            try {
+                const { defaultExecaLike } = await import('../../core/share/uploader.js');
+                const result = await defaultExecaLike('gh', ['--version']);
+                return result.exitCode === 0;
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            const result = await execaLike('gh', ['--version']);
+            return result.exitCode === 0;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+async function defaultPromptYesNo(question) {
+    if (!process.stdin.isTTY) {
+        // Non-interactive caller without --yes: refuse rather than block on
+        // an empty stdin. Mirrors the install-trust pattern in skills.ts.
+        process.stdout.write(`${question}\n(non-interactive stdin; declining)\n`);
+        return 'n';
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function safeResolveCredential(resolver) {
+    try {
+        return await resolver();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk the JSONL log from the tail and pick the newest `session.created`
+ * id. Mirrors the helper in cost.ts so the two surfaces agree on what
+ * "current session" means.
+ */
+function deriveSessionIdFromEvents(raw) {
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        try {
+            const parsed = JSON.parse(lines[i]);
+            if (parsed.type === 'session' && parsed.name === 'created' && typeof parsed.sessionId === 'string') {
+                return parsed.sessionId;
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    return null;
+}
+function emitUploadResult(ctx, sessionId, target, redactionSummary, redactionFindings, result) {
+    if (result.ok) {
+        const payload = {
+            command: 'share',
+            status: 'ok',
+            sessionId,
+            target,
+            url: result.url,
+            remoteId: result.remoteId ?? null,
+            redact: redactionSummary !== null,
+            redactionSummary,
+            redactionFindings,
+        };
+        const text = [
+            redactionSummary,
+            `pugi share: uploaded to ${target}.`,
+            `URL: ${result.url}`,
+        ]
+            .filter((line) => line !== null)
+            .join('\n');
+        ctx.writeOutput(payload, text);
+        return;
+    }
+    const payload = {
+        command: 'share',
+        status: 'upload_failed',
+        sessionId,
+        target,
+        reason: result.reason,
+        message: result.message,
+        redact: redactionSummary !== null,
+        redactionSummary,
+    };
+    const text = [
+        redactionSummary,
+        `pugi share: ${result.reason} — ${result.message}`,
+    ]
+        .filter((line) => line !== null)
+        .join('\n');
+    ctx.writeOutput(payload, text);
+    process.exitCode = 3;
+}
+//# sourceMappingURL=share.js.map

package/dist/runtime/commands/skills.js

@@ -7,20 +7,20 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 const USAGE = [
     'Usage:',
-    '  pugi skills list [--global|--workspace]            Show installed skills.',
-    '  pugi skills install <source> [--global|--workspace] [--yes] [--as <name>]',
-    '                                                     Fetch + trust-prompt + activate a skill.',
-    '  pugi skills info <name>                            Show metadata + body preview.',
-    '  pugi skills remove <name> [--global|--workspace]   Delete an installed skill.',
-    '  pugi skills trust <name> [--global|--workspace]    Re-trust the on-disk payload.',
+    ' pugi skills list [--global|--workspace]           Show installed skills.',
+    ' pugi skills install <source> [--global|--workspace] [--yes] [--as <name>]',
+    '                                                    Fetch + trust-prompt + activate a skill.',
+    ' pugi skills info <name>                           Show metadata + body preview.',
+    ' pugi skills remove <name> [--global|--workspace]  Delete an installed skill.',
+    ' pugi skills trust <name> [--global|--workspace]   Re-trust the on-disk payload.',
     '',
     'Source forms accepted by `install`:',
-    '  gh:owner/repo[/subdir][@ref]   GitHub tree fetch (default ref: main).',
-    '  https://github.com/...         GitHub tree/blob URL.',
-    '  anthropic:<slug>               Shortcut for gh:anthropics/skills/<slug>@main.',
-    '  npm:<package>[@version]        npm registry tarball.',
-    '  ./path | /abs/path             Local filesystem.',
-    '  <slug>                         Catalog lookup (catalog.pugi.dev).',
+    ' gh:owner/repo[/subdir][@ref]  GitHub tree fetch (default ref: main).',
+    ' https://github.com/...        GitHub tree/blob URL.',
+    ' anthropic:<slug>              Shortcut for gh:anthropics/skills/<slug>@main.',
+    ' npm:<package>[@version]       npm registry tarball.',
+    ' ./path | /abs/path            Local filesystem.',
+    ' <slug>                        Catalog lookup (catalog.pugi.dev).',
 ].join('\n');
 export async function runSkillsCommand(args, ctx) {
     const sub = args[0];
@@ -103,8 +103,8 @@ async function runSkillsList(args, ctx) {
     for (const { skill, trust } of trustStatuses) {
         const version = skill.frontmatter.metadata.version ? ` v${String(skill.frontmatter.metadata.version)}` : '';
         const trustMark = trust.status === 'trusted' ? '[trusted]' : trust.status === 'unsigned' ? '[unsigned]' : '[mismatch]';
-        lines.push(`  ${skill.name.padEnd(28)} ${skill.scope.padEnd(10)} ${trustMark.padEnd(11)}${version}`);
-        lines.push(`    ${truncate(skill.frontmatter.description, 80)}`);
+        lines.push(` ${skill.name.padEnd(28)} ${skill.scope.padEnd(10)} ${trustMark.padEnd(11)}${version}`);
+        lines.push(`   ${truncate(skill.frontmatter.description, 80)}`);
     }
     ctx.writeOutput({ command: 'skills.list', skills: trustStatuses }, lines.join('\n'));
 }
@@ -206,9 +206,9 @@ async function runSkillsInstall(args, ctx) {
         source: fetched.sourceUrl,
     }, [
         `Installed skill "${skillName}" (${scope}).`,
-        `  Path:    ${installedDir}`,
-        `  Source:  ${fetched.sourceUrl}`,
-        `  sha256:  ${sha256}`,
+        ` Path:   ${installedDir}`,
+        ` Source: ${fetched.sourceUrl}`,
+        ` sha256: ${sha256}`,
     ].join('\n'));
 }
 async function runSkillsInfo(args, ctx) {
@@ -234,13 +234,13 @@ async function runSkillsInfo(args, ctx) {
     const preview = skill.body.slice(0, 800);
     const lines = [
         `Skill: ${skill.name}`,
-        `  Scope:        ${skill.scope}`,
-        `  Path:         ${skill.dir}`,
-        `  Description:  ${skill.frontmatter.description}`,
-        `  Version:      ${String(skill.frontmatter.metadata.version ?? '(unset)')}`,
-        `  Tools:        ${(skill.frontmatter.metadata.tools ?? []).join(', ') || '(none)'}`,
-        `  Trust:        ${trust.status}`,
-        `  sha256:       ${actualSha}`,
+        ` Scope:       ${skill.scope}`,
+        ` Path:        ${skill.dir}`,
+        ` Description: ${skill.frontmatter.description}`,
+        ` Version:     ${String(skill.frontmatter.metadata.version ?? '(unset)')}`,
+        ` Tools:       ${(skill.frontmatter.metadata.tools ?? []).join(', ') || '(none)'}`,
+        ` Trust:       ${trust.status}`,
+        ` sha256:      ${actualSha}`,
         '',
         'Body preview:',
         preview,
@@ -362,13 +362,13 @@ async function promptTrust(kind, summary, body) {
     const banner = [
         '',
         `About to install ${kind} "${summary.name}"`,
-        `  Description:  ${summary.description}`,
-        `  Version:      ${summary.version ?? '(unset)'}`,
-        `  Tools:        ${summary.tools.join(', ') || '(none)'}`,
-        `  Files:        ${summary.files}`,
-        `  Source:       ${summary.source}`,
-        `  Target:       ${summary.targetDir}`,
-        `  sha256:       ${summary.sha256}`,
+        ` Description: ${summary.description}`,
+        ` Version:     ${summary.version ?? '(unset)'}`,
+        ` Tools:       ${summary.tools.join(', ') || '(none)'}`,
+        ` Files:       ${summary.files}`,
+        ` Source:      ${summary.source}`,
+        ` Target:      ${summary.targetDir}`,
+        ` sha256:      ${summary.sha256}`,
         '',
         'This payload becomes part of the system prompt and may influence agent decisions.',
         'Trust this install? [y/N/info] ',