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

package/dist/runtime/commands/rewind.js

@@ -0,0 +1,333 @@
+/**
+ * `/rewind` runtime — .
+ *
+ * Three invocation modes, sharing one runner:
+ *
+ *  - `/rewind N`             drop the last N operator turns + every
+ *                             tool call that landed between.
+ *  - `/rewind --to <id>`     rewind to a specific event index from the
+ *                             visible (post-mask) transcript.
+ *  - `/rewind`               interactive picker — surfaces the last 10
+ *                             user-turn boundaries (newest-first) and
+ *                             returns a payload the caller can use to
+ *                             mount a select prompt.
+ *
+ * The rewind is APPEND-ONLY: we never delete events. `applyRewindMask`
+ * elides the masked range on read; `pugi sessions undo-rewind` appends
+ * an inverse marker that nullifies the latest rewind so operators have
+ * a reliable escape hatch.
+ *
+ * Surface contract (same shape as `runCompactCommand`):
+ *
+ *  - Returns a structured result for the JSON path.
+ *  - Calls `ctx.writeOutput(payload, text)` once per invocation.
+ *  - Throws ONLY on programmer-error. Store failures, missing
+ *    sessions, etc. are surfaced as `failed_*` statuses.
+ *
+ * Exit codes (mapped by the dispatcher in cli.ts):
+ *
+ *  0 — marker appended OR picker surfaced
+ *  1 — store unavailable / session not found
+ *  2 — noop (asked to drop 0 turns, nothing to rewind, etc.)
+ */
+import { homedir } from 'node:os';
+import { slugForCwd } from '../../core/repl/history.js';
+import { appendRewindMarker, buildRewindPickerRows, pickRewindTargetForTurns, resolveEventIdToIndex, } from '../../core/checkpoint/rewinder.js';
+import { loadFromStore } from '../../core/checkpoint/resumer.js';
+import { SqliteSessionStore, resolveProjectStoreDir, } from '../../core/repl/store/session-store.js';
+/**
+ * Entry point reused by the slash command + the top-level dispatcher.
+ *
+ * `args` accepts:
+ *  - `[]`             picker mode
+ *  - `["N"]`          drop last N turns
+ *  - `["--to", "<id>"]` rewind to event id
+ *
+ * Both `-N` and `--turns N` are accepted for parity with the upstream tool's
+ * `--turns` flag.
+ */
+export async function runRewindCommand(args, ctx) {
+    const parsed = parseRewindArgs(args);
+    if (parsed.kind === 'error') {
+        return emit(ctx, {
+            command: 'rewind',
+            status: 'failed_parse',
+            reason: parsed.message,
+        }, parsed.message);
+    }
+    // Resolve session + store.
+    const slug = slugForCwd(ctx.workspaceRoot);
+    let store = ctx.store ?? null;
+    let sessionId = ctx.sessionId ?? null;
+    let storeOpenedHere = false;
+    if (store === null) {
+        sessionId = sessionId ?? (await pickMostRecentSessionIdReadOnly(slug));
+        if (!sessionId) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_no_session',
+                reason: 'No active session to rewind. Start a REPL with `pugi`.',
+            });
+        }
+        const opened = await openLiveStore(slug, sessionId);
+        if (!opened) {
+            return emit(ctx, {
+                command: '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: 'rewind',
+                status: 'failed_no_session',
+                reason: 'No active session to rewind.',
+            });
+        }
+        sessionId = rows[0].id;
+    }
+    try {
+        const loaded = await loadFromStore(store, sessionId);
+        if (!loaded) {
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'failed_no_session',
+                sessionId,
+                reason: `Session '${sessionId}' not found.`,
+            });
+        }
+        // Picker mode: surface the last 10 user-turn boundaries.
+        if (parsed.kind === 'picker') {
+            const rows = buildRewindPickerRows(loaded.rawEvents, 10);
+            if (rows.length === 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_empty',
+                    sessionId,
+                    reason: 'No operator turns to rewind to.',
+                }, 'Nothing to rewind — no operator turns yet.');
+            }
+            const pickerRows = rows.map((r) => ({
+                visibleIndex: r.visibleIndex,
+                turnsAgo: r.turnsAgo,
+                preview: r.preview,
+                timestampEpochMs: r.timestampEpochMs,
+            }));
+            const text = renderPicker(pickerRows);
+            return emit(ctx, {
+                command: 'rewind',
+                status: 'picker',
+                sessionId,
+                pickerRows,
+            }, text);
+        }
+        // Resolve target index.
+        let toEventIndex;
+        let turnsRewound;
+        if (parsed.kind === 'turns') {
+            if (parsed.n <= 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_zero',
+                    sessionId,
+                    reason: 'Asked to drop 0 turns — nothing to do.',
+                }, 'Asked to drop 0 turns — nothing to do.');
+            }
+            const target = pickRewindTargetForTurns(loaded.rawEvents, parsed.n);
+            if (target.turnsRewound === 0) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'noop_empty',
+                    sessionId,
+                    reason: 'No operator turns to rewind.',
+                }, 'No operator turns to rewind.');
+            }
+            toEventIndex = target.toEventIndex;
+            turnsRewound = target.turnsRewound;
+        }
+        else {
+            // mode === 'to-event'
+            const resolvedIdx = resolveEventIdToIndex(loaded.rawEvents, parsed.eventId);
+            if (resolvedIdx === null) {
+                return emit(ctx, {
+                    command: 'rewind',
+                    status: 'failed_parse',
+                    sessionId,
+                    reason: `Could not resolve event id '${parsed.eventId}'. Try \`/rewind\` for the picker.`,
+                });
+            }
+            toEventIndex = resolvedIdx;
+            // Count user turns in the masked range to report turnsRewound.
+            turnsRewound = countUserTurnsAfter(loaded.rawEvents, toEventIndex);
+        }
+        const fromEventIndex = loaded.rawEvents.length;
+        await appendRewindMarker({
+            store,
+            toEventIndex,
+            fromEventIndex,
+            turnsRewound,
+            reason: parsed.kind === 'turns' ? 'manual' : 'to-event',
+            ...(ctx.now !== undefined ? { now: ctx.now } : {}),
+        });
+        // Reload + recompute visible count for the operator banner.
+        const after = await loadFromStore(store, sessionId);
+        const visibleAfter = after?.visibleEvents.length ?? 0;
+        const banner = `Rewound ${turnsRewound} turn${turnsRewound === 1 ? '' : 's'} ` +
+            `(to event ${toEventIndex < 0 ? 'start' : `#${toEventIndex + 1}`}). ` +
+            `${visibleAfter} event${visibleAfter === 1 ? '' : 's'} now visible. ` +
+            `Undo with \`pugi sessions undo-rewind\`.`;
+        return emit(ctx, {
+            command: 'rewind',
+            status: 'rewound',
+            sessionId,
+            turnsRewound,
+            toEventIndex,
+            fromEventIndex,
+            visibleAfter,
+        }, banner);
+    }
+    finally {
+        if (storeOpenedHere && store) {
+            try {
+                await store.close();
+            }
+            catch {
+                /* idempotent */
+            }
+        }
+    }
+}
+/**
+ * Accepts:
+ *  pugi rewind           -> picker
+ *  pugi rewind 3         -> drop 3 turns
+ *  pugi rewind --turns 3 -> same
+ *  pugi rewind --to 12   -> rewind to event index 12 (1-based visible)
+ *  pugi rewind --to #12  -> rewind to event index 12 (0-based hidden)
+ */
+function parseRewindArgs(args) {
+    if (args.length === 0)
+        return { kind: 'picker' };
+    const head = args[0];
+    // --to <id>
+    if (head === '--to' || head === '-t') {
+        const eventId = args[1];
+        if (!eventId) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --to <event-id>',
+            };
+        }
+        return { kind: 'to-event', eventId };
+    }
+    if (head.startsWith('--to=')) {
+        const eventId = head.slice('--to='.length);
+        if (eventId.length === 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --to <event-id>',
+            };
+        }
+        return { kind: 'to-event', eventId };
+    }
+    // --turns N OR -N OR positional N
+    if (head === '--turns' || head === '-n') {
+        const n = Number.parseInt(args[1] ?? '', 10);
+        if (!Number.isFinite(n) || n < 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --turns <N>',
+            };
+        }
+        return { kind: 'turns', n };
+    }
+    if (head.startsWith('--turns=')) {
+        const n = Number.parseInt(head.slice('--turns='.length), 10);
+        if (!Number.isFinite(n) || n < 0) {
+            return {
+                kind: 'error',
+                message: 'Usage: pugi rewind --turns <N>',
+            };
+        }
+        return { kind: 'turns', n };
+    }
+    // Bare integer: positional turns count.
+    const positional = Number.parseInt(head, 10);
+    if (Number.isFinite(positional) && positional >= 0) {
+        return { kind: 'turns', n: positional };
+    }
+    return {
+        kind: 'error',
+        message: `Unknown argument '${head}'. Try \`pugi rewind\`, \`pugi rewind <N>\`, or \`pugi rewind --to <id>\`.`,
+    };
+}
+function emit(ctx, payload, text) {
+    const human = text ?? payload.reason ?? `rewind: ${payload.status}`;
+    ctx.writeOutput(payload, human);
+    return payload;
+}
+function renderPicker(rows) {
+    const lines = ['Rewind picker — pick a turn boundary:', ''];
+    for (const r of rows) {
+        const tag = `[#${r.visibleIndex.toString().padStart(3)}]`;
+        const ago = `${r.turnsAgo}t ago`.padStart(8);
+        lines.push(` ${tag} ${ago} ${r.preview}`);
+    }
+    lines.push('', 'Rewind with: pugi rewind --to <#N> (or `pugi rewind <turnsToDrop>`).');
+    return lines.join('\n');
+}
+function countUserTurnsAfter(events, toEventIndex) {
+    let count = 0;
+    for (let i = toEventIndex + 1; i < events.length; i += 1) {
+        if (events[i].kind === 'user')
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Open the SqliteSessionStore for the workspace's project slug, bound
+ * to `sessionId`. Returns null when the lock is held by another REPL.
+ */
+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;
+    }
+}
+/**
+ * Discover the most recent active session id for a project slug,
+ * without taking the writer lockfile. Used by the standalone CLI path
+ * (no `--session` flag) so a live REPL holding the lock does not block
+ * the lookup.
+ */
+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=rewind.js.map

package/dist/runtime/commands/roster.js

@@ -1,26 +1,26 @@
 /**
- * `pugi roster` command - α7.5 Tier 1 instantiation Phase 1.
+ * `pugi roster` command - Tier 1 instantiation Phase 1.
  *
  * Lists the live Tier 1 personas with display name, role, and routing
  * tag. The CLI walks two sources in order:
  *
- *   1. The local @pugi/personas roster (THE_TEN). Always succeeds; the
- *      ten brand-canonical personas are baked into the SDK.
- *   2. The remote `GET /api/pugi/sessions/roster` endpoint when the
- *      operator has a valid credential. The remote response carries the
- *      server-side dispatch role + dispatchTag for each slug so the
- *      operator sees the actual routing decision the dispatcher will
- *      apply on a `pugi delegate <slug>` call.
+ *  1. The local @pugi/personas roster (THE_TEN). Always succeeds; the
+ *     ten brand-canonical personas are baked into the SDK.
+ *  2. The remote `GET /api/pugi/sessions/roster` endpoint when the
+ *     operator has a valid credential. The remote response carries the
+ *     server-side dispatch role + dispatchTag for each slug so the
+ *     operator sees the actual routing decision the dispatcher will
+ *     apply on a `pugi delegate <slug>` call.
  *
  * The command never fails if the network is unreachable - it falls back
  * to local-only output with a one-line warning. This matches the
- * local-first contract (ADR-0037): the operator can still see who is on
+ * local-first contract : the operator can still see who is on
  * the team without an API key.
  *
  * Output:
- *   - text default: a 3-column table (slug | name | role).
- *   - --json:        a structured array of { slug, name, role, totem,
- *                    dispatchTag } records, used by scripted callers.
+ *  - text default: a 3-column table (slug | name | role).
+ *  - --json:       a structured array of { slug, name, role, totem,
+ *                   dispatchTag } records, used by scripted callers.
  */
 import { THE_TEN } from '@pugi/personas';
 import { fetchPersonaRoster, } from '@pugi/sdk';
@@ -85,7 +85,7 @@ export function renderRosterTable(rows) {
         dispatchTag: Math.max(head.dispatchTag.length, ...rows.map((r) => r.dispatchTag.length)),
     };
     const pad = (s, width) => s + ' '.repeat(Math.max(0, width - s.length));
-    const line = (r) => [pad(r.slug, widths.slug), pad(r.name, widths.name), pad(r.totem, widths.totem), pad(r.role, widths.role), pad(r.dispatchTag, widths.dispatchTag)].join('  ');
+    const line = (r) => [pad(r.slug, widths.slug), pad(r.name, widths.name), pad(r.totem, widths.totem), pad(r.role, widths.role), pad(r.dispatchTag, widths.dispatchTag)].join(' ');
     const header = line(head);
     const sep = '-'.repeat(header.length);
     return [header, sep, ...rows.map((r) => line(r))].join('\n');
@@ -107,7 +107,7 @@ export async function resolveRoster(config) {
         return { rows: mergeRoster(THE_TEN, result.response.personas), warning: null };
     }
     const reason = result.status === 'endpoint_missing'
-        ? 'runtime does not expose /api/pugi/sessions/roster (upgrade admin-api to α7.5+)'
+        ? 'runtime does not expose /api/pugi/sessions/roster (upgrade admin-api to +)'
         : result.message;
     return {
         rows: mergeRoster(THE_TEN, null),

package/dist/runtime/commands/servers-cli.js

@@ -0,0 +1,182 @@
+/**
+ * PR M (2026-06-05): `pugi servers` top-level CLI surface.
+ *
+ * Operator pain (CEO 2026-06-05): PR H #919 added the `/servers` slash
+ * command so the REPL can list and kill processes tracked by
+ * `server_start`. That covers the in-REPL case, but the most painful
+ * regression is when the operator closes the REPL (Ctrl+D, crash,
+ * accidental window close) and a Vite/Next dev server keeps holding
+ * port 5173. With the slash-only surface, the only way back is
+ * `lsof -i :5173 | xargs kill -9`. `pugi servers` ports the same
+ * primitive to a shell-invocable subcommand so the orphan path is one
+ * command: `pugi servers stop all`.
+ *
+ * Surface mirrors the slash exactly to keep operator muscle memory:
+ *
+ *   pugi servers                          list tracked servers
+ *   pugi servers stop <runId>             kill by srv-<uuid>
+ *   pugi servers stop <pid>               kill by numeric pid
+ *   pugi servers stop all                 kill every alive entry
+ *   pugi servers --workspace <path>       use <path>/.pugi/runs/ instead
+ *                                         of process.cwd() (orphan rescue)
+ *   pugi servers --help                   print usage + exit 0
+ *
+ * This is a thin wrapper around `listServers` / `stopServers` /
+ * `runServersCommand` already exported by `commands/servers.ts` (the
+ * slash-command runner). Library coverage of the underlying primitive
+ * lives in `test/servers-command.spec.ts`; this module owns only the
+ * argv contract + exit codes, mirroring the `flatten-command` /
+ * `flatten-repo` split.
+ *
+ * Exit codes:
+ *   0 - success (list, empty, stopped, --help)
+ *   2 - invalid CLI args (unknown flag, missing target, malformed --workspace)
+ *   3 - not-found (stop <unknown>)
+ *
+ * The `--workspace` flag is parsed locally rather than pulled from the
+ * global `CliFlags` because `flags.workspace` already means something
+ * different (the headless workspace slug surfaced in `session.start`),
+ * and `flags.cwd` is reserved for the `--print` headless path. Local
+ * parsing keeps the wrapper self-contained and avoids a global-state
+ * collision the way `commands/index-cmd.ts` and `commands/flatten.ts`
+ * already do.
+ */
+import { resolve } from 'node:path';
+import { runServersCommand, } from './servers.js';
+/**
+ * Single entry-point. Returns the desired process exit code so the
+ * dispatcher in `runtime/cli.ts` can propagate it via
+ * `process.exitCode`. Mirrors the `runIndexCommand` / `runFlattenCommand`
+ * shape.
+ */
+export async function runServersCliCommand(args, ctx) {
+    const parsed = parseArgs(args);
+    switch (parsed.kind) {
+        case 'help':
+            return printHelp(ctx);
+        case 'error':
+            ctx.writeOutput({ ok: false, command: 'servers', error: parsed.message }, `pugi servers: ${parsed.message}`);
+            return 2;
+        case 'list':
+        case 'stop': {
+            const workspaceRoot = parsed.workspaceOverride !== null
+                ? resolve(parsed.workspaceOverride)
+                : ctx.workspaceRoot;
+            const lines = [];
+            const io = {
+                write: (line) => lines.push(line),
+            };
+            const mode = parsed.kind === 'list'
+                ? { kind: 'list' }
+                : { kind: 'stop', target: parsed.target };
+            const result = await runServersCommand(mode, io, { workspaceRoot });
+            const text = lines.join('\n');
+            ctx.writeOutput({
+                ok: result.kind !== 'not-found' && result.kind !== 'error',
+                command: 'servers',
+                mode: parsed.kind,
+                result,
+            }, text);
+            if (result.kind === 'not-found')
+                return 3;
+            if (result.kind === 'error')
+                return 1;
+            return 0;
+        }
+    }
+}
+/**
+ * Pure argv parser. Exported for the spec to pin canonical shapes.
+ *
+ * Accepted shapes:
+ *   []                                          list
+ *   ['--help'] | ['-h'] | ['help']              help
+ *   ['--workspace', '/path']                    list, workspace override
+ *   ['--workspace=/path']                       same, fused
+ *   ['stop', '<target>']                        stop
+ *   ['stop', '<target>', '--workspace', '<p>']  stop with override
+ *
+ * Unknown flag or `stop` with no target is a structural error (exit 2).
+ */
+export function parseArgs(args) {
+    let workspaceOverride = null;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h' || arg === 'help') {
+            return { kind: 'help' };
+        }
+        if (arg === '--workspace') {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('-')) {
+                return { kind: 'error', message: '--workspace requires a path argument.' };
+            }
+            workspaceOverride = next;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--workspace=')) {
+            const value = arg.slice('--workspace='.length);
+            if (value.length === 0) {
+                return { kind: 'error', message: '--workspace requires a non-empty path.' };
+            }
+            workspaceOverride = value;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { kind: 'error', message: `unknown flag "${arg}"` };
+        }
+        positional.push(arg);
+    }
+    if (positional.length === 0) {
+        return { kind: 'list', workspaceOverride };
+    }
+    const [head, ...rest] = positional;
+    if (head === 'stop') {
+        if (rest.length === 0) {
+            return {
+                kind: 'error',
+                message: 'stop requires a target (runId, pid, or "all").',
+            };
+        }
+        if (rest.length > 1) {
+            return {
+                kind: 'error',
+                message: `stop accepts one target; got ${rest.length}.`,
+            };
+        }
+        return { kind: 'stop', target: rest[0], workspaceOverride };
+    }
+    return {
+        kind: 'error',
+        message: `unknown subcommand "${head}". Allowed: stop, --help.`,
+    };
+}
+function printHelp(ctx) {
+    ctx.writeOutput({ ok: true, command: 'servers', sub: 'help' }, [
+        'pugi servers - list and stop dev servers tracked by server_start.',
+        '',
+        'Usage:',
+        '  pugi servers                          List tracked servers (.pugi/runs/srv-*).',
+        '  pugi servers stop <runId>             Kill one by srv-<uuid> runId.',
+        '  pugi servers stop <pid>               Kill one by numeric pid.',
+        '  pugi servers stop all                 Kill every alive tracked server.',
+        '',
+        'Options:',
+        '  --workspace <path>                    Use <path>/.pugi/runs/ instead of cwd.',
+        '                                        Handy when a server was orphaned in',
+        '                                        another repo and the REPL is gone.',
+        '  --help, -h                            Print this message and exit 0.',
+        '',
+        'Exit codes:',
+        '  0  success (list, empty, stopped)',
+        '  2  usage error (unknown flag, missing target)',
+        '  3  not-found (stop target did not match any tracked server)',
+        '',
+        'Mirrors the in-REPL `/servers` slash command (PR H, beta.100+).',
+    ].join('\n'));
+    return 0;
+}
+//# sourceMappingURL=servers-cli.js.map