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

package/dist/runtime/commands/redo.js

@@ -0,0 +1,361 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { hashContent } from '../../core/file-cache.js';
+import { recordFileMutation, recordToolCall, recordToolResult, } from '../../core/session.js';
+import { deleteBlob, readBlob } from './redo-blob-store.js';
+/**
+ * `pugi redo` — counterpart to `pugi undo` .
+ *
+ * Reapplies the file mutations that the most recent `/undo` invocation
+ * reverted. Stack-based: each successful redo consumes one undo entry
+ * from the event log, so calling /redo twice after two /undo calls
+ * walks back through the original mutation history in reverse order.
+ *
+ * Walk strategy:
+ *  1. Read `.pugi/events.jsonl` line by line into an array.
+ *  2. Walk backwards. Find the most recent `tool_result` whose
+ *     `status === 'success'` and whose linked `tool_call` tool is
+ *     `undo` AND for which no later `tool_result` with tool `redo`
+ *     has already consumed it. (We track the consumed-by-redo set
+ *     by walking events forward once and tagging undo results that
+ *     a subsequent redo references.)
+ *  3. Gather every `file_mutation` event that shares the same undo
+ *     `toolCallId`. These are the INVERSE mutations:
+ *       - operation: 'delete' + beforeHash=<original-after-sha>
+ *         → original op was `create`; redo = recreate file from blob
+ *       - operation: 'update' + beforeHash=<original-after-sha>,
+ *         afterHash=<original-before-sha>
+ *         → original op was `update`; redo = restore content from blob
+ *       - operation: 'update' + beforeHash=undefined,
+ *         afterHash=<original-before-sha>
+ *         → original op was `delete`; redo = delete the file again
+ *
+ * Reapply strategy:
+ *  For each step we re-apply with a strict safety gate. If the file
+ *  was modified externally since the undo (current sha ≠ undo's
+ *  `afterHash`) we refuse to overwrite operator work and abort the
+ *  whole redo atomically — no partial reapply per spec parity with
+ *  the undo runner.
+ *
+ *  - inverse `delete` (recreate from create-undo): read blob keyed
+ *    by `beforeHash`, write at path. Path must not exist OR must
+ *    match the post-undo (afterHash = undefined, file deleted).
+ *  - inverse `update` with afterHash present (update-undo or
+ *    delete-undo restoring HEAD): file must currently match
+ *    `afterHash`. Reapply by writing blob content (update case) or
+ *    by unlinking the file (delete case — no blob exists, the
+ *    `beforeHash === undefined` discriminator routes here).
+ *  - any other shape → unsafe → abort.
+ *
+ * After a successful redo:
+ *  - Emit a `tool_call` event with tool `redo` and inputSummary
+ *    `replay <undo-toolCallId>` so the next /undo invocation walks
+ *    PAST it (the redo creates fresh mutations that show up as the
+ *    most recent successful mutating result).
+ *  - Emit one `file_mutation` per reapplied step describing the
+ *    re-applied operation (create / update / delete) so a subsequent
+ *    /undo can reverse the redo if the operator changes their mind.
+ *  - Best-effort delete the consumed blobs from `.pugi/undo-blobs/`
+ *    so a second /redo without a fresh /undo is a noop instead of
+ *    re-applying stale content.
+ */
+const UNDO_TOOL = 'undo';
+export async function runRedoCommand(_args, ctx) {
+    const eventsPath = resolve(ctx.workspaceRoot, '.pugi/events.jsonl');
+    if (!existsSync(eventsPath)) {
+        ctx.writeOutput({ command: 'redo', status: 'noop', reason: 'no_session' }, 'No session events found. Nothing to redo.');
+        return;
+    }
+    const events = parseEvents(eventsPath);
+    const target = findReplayTarget(events);
+    if (!target) {
+        ctx.writeOutput({ command: 'redo', status: 'noop', reason: 'no_undo' }, 'No /undo to redo. Run an undo first, then /redo will replay it.');
+        return;
+    }
+    if (target.mutations.length === 0) {
+        ctx.writeOutput({
+            command: 'redo',
+            status: 'noop',
+            reason: 'no_inverse_mutations',
+            undoToolCallId: target.undoToolCallId,
+        }, `Undo ${target.undoToolCallId} recorded no inverse mutations. Nothing to redo.`);
+        return;
+    }
+    // Pre-flight: every step must be reversible before touching disk.
+    const plan = planReplays(ctx.workspaceRoot, target.mutations);
+    if (plan.aborted) {
+        ctx.writeOutput({
+            command: 'redo',
+            status: 'aborted',
+            reason: plan.reason,
+            undoToolCallId: target.undoToolCallId,
+            unsafe: plan.unsafe,
+        }, `Refusing to redo ${target.undoToolCallId}: ${plan.reason}`);
+        process.exitCode = 1;
+        return;
+    }
+    const replayed = [];
+    for (const step of plan.steps) {
+        try {
+            executeReplay(ctx.workspaceRoot, step);
+            replayed.push({ path: step.path, operation: step.replayOperation });
+        }
+        catch (error) {
+            // Mid-flight failure after pre-flight said it was safe. Surface
+            // the error and bail — parity with the undo runner's "no partial
+            // state on failure" contract.
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.writeOutput({
+                command: 'redo',
+                status: 'failed',
+                reason: message,
+                undoToolCallId: target.undoToolCallId,
+                replayed,
+                failedAt: step.path,
+            }, `Redo failed mid-flight on ${step.path}: ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Audit the redo so a future /undo walks back through it. Each
+    // replayed step gets a fresh `file_mutation` event so the next
+    // /undo's walk picks this up as the most-recent successful
+    // mutating tool result.
+    const toolCallId = recordToolCall(ctx.session, 'redo', `replay ${target.undoToolCallId}`);
+    for (const step of plan.steps) {
+        recordFileMutation(ctx.session, {
+            toolCallId,
+            path: step.path,
+            operation: step.replayOperation,
+            beforeHash: step.preReplayHash,
+            afterHash: step.postReplayHash,
+        });
+    }
+    recordToolResult(ctx.session, toolCallId, 'success', `Redid ${replayed.length} mutation(s) from undo ${target.undoToolCallId}`);
+    // Best-effort blob cleanup. After redo the blob is no longer needed
+    // — a future /undo will capture fresh after-state from disk if the
+    // operator un-does this redo.
+    for (const step of plan.steps) {
+        if (step.blobSha)
+            deleteBlob(ctx.workspaceRoot, step.blobSha);
+    }
+    ctx.writeOutput({
+        command: 'redo',
+        status: 'ok',
+        undoToolCallId: target.undoToolCallId,
+        replayed,
+    }, [
+        `Redid ${replayed.length} mutation(s) from undo ${target.undoToolCallId}:`,
+        ...replayed.map((entry) => ` ${entry.operation.padEnd(7)} ${entry.path}`),
+        'Use /undo to revert.',
+    ].join('\n'));
+}
+function parseEvents(eventsPath) {
+    const raw = readFileSync(eventsPath, 'utf8');
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Partial-write tolerance — same approach as undo.ts.
+        }
+    }
+    return out;
+}
+/**
+ * Find the most recent successful `undo` tool result that has NOT
+ * been consumed by a later `redo` invocation.
+ *
+ * Consumption tracking: we collect every `redo` tool_call's
+ * `inputSummary` of the shape `replay <toolCallId>`. Any matching
+ * undo toolCallId is treated as already-redone — calling /redo a
+ * second time without a fresh /undo must be a noop, not a re-apply
+ * (re-apply would double-write the same content and corrupt the
+ * audit trail).
+ */
+function findReplayTarget(events) {
+    const toolCalls = new Map();
+    const results = [];
+    const consumed = new Set();
+    for (let i = 0; i < events.length; i += 1) {
+        const event = events[i];
+        if (!event)
+            continue;
+        if (event.type === 'tool_call' && typeof event.id === 'string' && typeof event.tool === 'string') {
+            toolCalls.set(event.id, { id: event.id, tool: event.tool, index: i });
+            if (event.tool === 'redo' && typeof event.inputSummary === 'string') {
+                const match = /^replay\s+(\S+)/.exec(event.inputSummary);
+                if (match && match[1])
+                    consumed.add(match[1]);
+            }
+        }
+        else if (event.type === 'tool_result' &&
+            typeof event.id === 'string' &&
+            typeof event.toolCallId === 'string' &&
+            (event.status === 'success' || event.status === 'error' || event.status === 'cancelled')) {
+            results.push({
+                id: event.id,
+                toolCallId: event.toolCallId,
+                status: event.status,
+                index: i,
+            });
+        }
+    }
+    // Newest → oldest walk so the stack pops in LIFO order.
+    for (let i = results.length - 1; i >= 0; i -= 1) {
+        const result = results[i];
+        if (result.status !== 'success')
+            continue;
+        const call = toolCalls.get(result.toolCallId);
+        if (!call)
+            continue;
+        if (call.tool !== UNDO_TOOL)
+            continue;
+        if (consumed.has(result.toolCallId))
+            continue;
+        const mutations = [];
+        for (const event of events) {
+            if (event.type !== 'file_mutation')
+                continue;
+            if (event.toolCallId !== result.toolCallId)
+                continue;
+            if (typeof event.path !== 'string')
+                continue;
+            if (event.operation !== 'create' &&
+                event.operation !== 'update' &&
+                event.operation !== 'delete' &&
+                event.operation !== 'move') {
+                continue;
+            }
+            mutations.push({
+                toolCallId: result.toolCallId,
+                path: event.path,
+                operation: event.operation,
+                beforeHash: typeof event.beforeHash === 'string' ? event.beforeHash : undefined,
+                afterHash: typeof event.afterHash === 'string' ? event.afterHash : undefined,
+            });
+        }
+        return { undoToolCallId: result.toolCallId, mutations };
+    }
+    return null;
+}
+function planReplays(root, mutations) {
+    const steps = [];
+    const unsafe = [];
+    for (const mutation of mutations) {
+        const abs = resolve(root, mutation.path);
+        // The undo emitted three inverse shapes — decode the original op
+        // from the (operation, beforeHash, afterHash) triple.
+        if (mutation.operation === 'delete' && mutation.beforeHash) {
+            // Original op was `create`. Redo = recreate from blob.
+            if (existsSync(abs)) {
+                unsafe.push(`${mutation.path}: post-undo expected file to be absent, found existing content`);
+                continue;
+            }
+            const content = readBlob(root, mutation.beforeHash);
+            if (content === undefined) {
+                unsafe.push(`${mutation.path}: no captured AFTER content blob (sha=${mutation.beforeHash.slice(0, 12)}…) — redo not available`);
+                continue;
+            }
+            if (hashContent(content) !== mutation.beforeHash) {
+                unsafe.push(`${mutation.path}: blob sha mismatch (store may have been tampered with) — refusing to write`);
+                continue;
+            }
+            steps.push({
+                path: mutation.path,
+                replayOperation: 'create',
+                preReplayHash: undefined,
+                postReplayHash: mutation.beforeHash,
+                content,
+                blobSha: mutation.beforeHash,
+            });
+            continue;
+        }
+        if (mutation.operation === 'update' && mutation.beforeHash && mutation.afterHash) {
+            // Original op was `update`. Post-undo file matches afterHash
+            // (= original beforeHash). Redo = restore beforeHash content
+            // from blob (= original afterHash content).
+            if (!existsSync(abs)) {
+                unsafe.push(`${mutation.path}: file expected to exist for update redo, not found`);
+                continue;
+            }
+            const current = readFileSync(abs, 'utf8');
+            if (hashContent(current) !== mutation.afterHash) {
+                unsafe.push(`${mutation.path}: modified externally since /undo — refusing to overwrite operator work`);
+                continue;
+            }
+            const content = readBlob(root, mutation.beforeHash);
+            if (content === undefined) {
+                unsafe.push(`${mutation.path}: no captured AFTER content blob (sha=${mutation.beforeHash.slice(0, 12)}…) — redo not available`);
+                continue;
+            }
+            if (hashContent(content) !== mutation.beforeHash) {
+                unsafe.push(`${mutation.path}: blob sha mismatch (store may have been tampered with) — refusing to write`);
+                continue;
+            }
+            steps.push({
+                path: mutation.path,
+                replayOperation: 'update',
+                preReplayHash: mutation.afterHash,
+                postReplayHash: mutation.beforeHash,
+                content,
+                blobSha: mutation.beforeHash,
+            });
+            continue;
+        }
+        if (mutation.operation === 'update' && !mutation.beforeHash && mutation.afterHash) {
+            // Original op was `delete`. Post-undo file matches afterHash
+            // (= original beforeHash, restored from git HEAD). Redo = delete
+            // the file again. No blob lookup needed.
+            if (!existsSync(abs)) {
+                // Already gone — nothing to redo for this entry.
+                continue;
+            }
+            const current = readFileSync(abs, 'utf8');
+            if (hashContent(current) !== mutation.afterHash) {
+                unsafe.push(`${mutation.path}: modified externally since /undo — refusing to delete operator work`);
+                continue;
+            }
+            steps.push({
+                path: mutation.path,
+                replayOperation: 'delete',
+                preReplayHash: mutation.afterHash,
+                postReplayHash: undefined,
+            });
+            continue;
+        }
+        // Anything else (move undo, malformed entry) — refuse rather than
+        // partial-replay. Matches the undo runner's posture.
+        unsafe.push(`${mutation.path}: redo of inverse op '${mutation.operation}' is not supported in this build`);
+    }
+    if (unsafe.length > 0) {
+        return {
+            aborted: true,
+            reason: 'one or more files are unsafe to redo',
+            unsafe,
+            steps: [],
+        };
+    }
+    return { aborted: false, steps };
+}
+function executeReplay(root, step) {
+    const abs = resolve(root, step.path);
+    if (step.replayOperation === 'delete') {
+        if (existsSync(abs))
+            unlinkSync(abs);
+        return;
+    }
+    if (step.content === undefined) {
+        throw new Error(`internal: replay content missing for ${step.path}`);
+    }
+    // Atomic tmp+rename — same pattern as undo's executeRevert.
+    const tmp = `${abs}.pugi-redo-${Date.now()}`;
+    writeFileSync(tmp, step.content, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, abs);
+}
+//# sourceMappingURL=redo.js.map

package/dist/runtime/commands/release-notes.js

@@ -0,0 +1,229 @@
+/**
+ * `pugi release-notes` — changelog diff between last-seen + current
+ * ().
+ *
+ * Parity command with the upstream tool's `/release-notes`, which shows
+ * what changed between the previously-installed CLI version and the
+ * currently-installed one. The Pugi variant reads the bundled
+ * `CHANGELOG.md`, slices it к the range `(last-seen, current]`, and
+ * renders the Markdown sections to the operator. After а successful
+ * render the marker is bumped к `current` so the next invocation is а
+ * no-op until the operator upgrades again.
+ *
+ * # Module contract
+ *
+ *  - This file owns the WIRING from CLI flags + ambient state к the
+ *    parser + state I/O helpers. The parser + state modules в
+ *    `core/release-notes/` have zero coupling к the CLI dispatch
+ *    surface.
+ *
+ *  - `runReleaseNotesCommand` is the single entry point. Both the
+ *    top-level `pugi release-notes` handler в `runtime/cli.ts` AND
+ *    the in-REPL `/release-notes` slash command call it. The
+ *    function returns а structured `ReleaseNotesResult` so the
+ *    slash dispatcher can route the lines к the system pane
+ *    without re-reading the changelog.
+ *
+ *  - Exit code is ALWAYS 0. The command is informational, never а
+ *    gate. Read failures, missing CHANGELOG, and write failures all
+ *    degrade к а structured envelope with а human-readable footer.
+ *
+ *  - The changelog source is captured behind а function so the spec
+ *    can stub it without touching disk. The default reads the file
+ *    bundled with the CLI install (resolved relative к the package
+ *    root); fixtures pass an in-memory string.
+ *
+ *  - `--reset` flag clears the last-seen marker AND re-renders the
+ *    full bundled changelog as if the operator had never run the
+ *    command. Distinct from а plain `--all` toggle because the
+ *    reset PERSISTS (the next invocation again shows everything
+ *    newer than the cleared marker — `none`).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseChangelog, sliceVersionsBetween, } from '../../core/release-notes/parser.js';
+import { clearLastSeenVersion, readLastSeenVersion, writeLastSeenVersion, } from '../../core/release-notes/state.js';
+import { PUGI_CLI_VERSION } from '../version.js';
+/**
+ * Default loader для the bundled `apps/pugi-cli/CHANGELOG.md`. The
+ * compiled bundle ships under `dist/runtime/commands/release-notes.js`;
+ * the CHANGELOG sits next к `package.json` at the package root, two
+ * directories up from `dist/runtime/commands/`. We also probe а
+ * couple of fallback locations so the dev path (running the source
+ * directly из `src/`) works без а compile step.
+ */
+export function defaultReadChangelog() {
+    const candidates = resolveChangelogCandidates();
+    for (const candidate of candidates) {
+        try {
+            if (existsSync(candidate)) {
+                return readFileSync(candidate, 'utf8');
+            }
+        }
+        catch {
+            // Permission errors, transient FS hiccups — keep probing the
+            // remaining candidates. Returning null at the end is fine; the
+            // renderer surfaces а "changelog-missing" envelope.
+        }
+    }
+    return null;
+}
+function resolveChangelogCandidates() {
+    // import.meta.url points к the compiled JS in production
+    // (`dist/runtime/commands/release-notes.js`) and к the source TS в
+    // tests / dev runs. We probe both relative ancestries so either
+    // path lands on `<package>/CHANGELOG.md`.
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return [
+            resolve(here, '../../..', 'CHANGELOG.md'),
+            resolve(here, '../../../..', 'CHANGELOG.md'),
+            resolve(process.cwd(), 'apps/pugi-cli/CHANGELOG.md'),
+            resolve(process.cwd(), 'CHANGELOG.md'),
+        ];
+    }
+    catch {
+        // Some non-ESM contexts (very old node, eval'd code) reject
+        // `import.meta.url`. Fall back к cwd-relative probes — works for
+        // tests that run from the package root.
+        return [
+            resolve(process.cwd(), 'apps/pugi-cli/CHANGELOG.md'),
+            resolve(process.cwd(), 'CHANGELOG.md'),
+        ];
+    }
+}
+/**
+ * Default home dir resolver. Centralised so the CLI handler can call
+ * `runReleaseNotesCommand` without re-importing `os.homedir`.
+ */
+export function defaultReleaseNotesHome() {
+    return homedir();
+}
+/**
+ * Pick + render the release notes, hand the result к the output
+ * sink, persist the marker. Always exits 0.
+ */
+export function runReleaseNotesCommand(ctx) {
+    const readChangelog = ctx.readChangelog ?? defaultReadChangelog;
+    const currentVersion = ctx.currentVersion ?? PUGI_CLI_VERSION;
+    // `--reset` clears the marker before slicing. We capture the
+    // pre-clear value so the JSON envelope still shows the operator
+    // what their previous marker was, which makes scripting + bug
+    // reports easier.
+    const lastSeenBefore = readLastSeenVersion(ctx.home);
+    if (ctx.reset) {
+        clearLastSeenVersion(ctx.home);
+    }
+    const lastSeen = ctx.reset ? null : lastSeenBefore;
+    const raw = readChangelog();
+    if (raw === null) {
+        const result = {
+            command: 'release-notes',
+            currentVersion,
+            lastSeenVersion: lastSeenBefore ?? 'none',
+            sections: [],
+            status: 'changelog-missing',
+            markerPersisted: false,
+            persistFailure: null,
+            text: renderMissingChangelog(currentVersion),
+        };
+        ctx.writeOutput(result, result.text);
+        process.exitCode = 0;
+        return result;
+    }
+    const sections = parseChangelog(raw);
+    if (sections.length === 0) {
+        const result = {
+            command: 'release-notes',
+            currentVersion,
+            lastSeenVersion: lastSeenBefore ?? 'none',
+            sections: [],
+            status: 'changelog-empty',
+            markerPersisted: false,
+            persistFailure: null,
+            text: renderEmptyChangelog(currentVersion),
+        };
+        ctx.writeOutput(result, result.text);
+        process.exitCode = 0;
+        return result;
+    }
+    const slice = sliceVersionsBetween(sections, lastSeen, currentVersion);
+    if (slice.length === 0) {
+        // Nothing new — render the no-op message and DO NOT touch the
+        // marker (marker already equals current OR is newer; either way
+        // re-writing it is а no-op write we can avoid).
+        const result = {
+            command: 'release-notes',
+            currentVersion,
+            lastSeenVersion: lastSeenBefore ?? 'none',
+            sections: [],
+            status: 'up-to-date',
+            markerPersisted: false,
+            persistFailure: null,
+            text: renderUpToDate(currentVersion, lastSeenBefore),
+        };
+        ctx.writeOutput(result, result.text);
+        process.exitCode = 0;
+        return result;
+    }
+    const persist = writeLastSeenVersion(ctx.home, currentVersion);
+    const text = renderSections(slice, currentVersion, lastSeen, persist);
+    const result = {
+        command: 'release-notes',
+        currentVersion,
+        lastSeenVersion: lastSeenBefore ?? 'none',
+        sections: slice,
+        status: ctx.reset ? 'reset' : 'rendered',
+        markerPersisted: persist.status === 'ok',
+        persistFailure: persist.status === 'failed' ? persist.reason : null,
+        text,
+    };
+    ctx.writeOutput(result, text);
+    process.exitCode = 0;
+    return result;
+}
+function renderSections(sections, current, lastSeen, persist) {
+    const header = lastSeen
+        ? `Pugi release notes — ${lastSeen} → ${current}`
+        : `Pugi release notes — up to ${current}`;
+    const blocks = [header, '═'.repeat(Math.max(header.length, 30))];
+    for (const section of sections) {
+        const subhead = section.date
+            ? `## [${section.version}] - ${section.date}`
+            : `## [${section.version}]`;
+        blocks.push('');
+        blocks.push(subhead);
+        if (section.body.length > 0) {
+            blocks.push('');
+            blocks.push(section.body);
+        }
+    }
+    if (persist.status === 'failed') {
+        blocks.push('');
+        blocks.push(`Warning: could not persist last-seen marker (${persist.reason}). Next run will surface the same notes.`);
+    }
+    return blocks.join('\n');
+}
+function renderUpToDate(current, lastSeen) {
+    const lines = ['No new release notes.'];
+    lines.push(`Installed: ${current}`);
+    lines.push(`Last seen: ${lastSeen ?? 'none'}`);
+    return lines.join('\n');
+}
+function renderMissingChangelog(current) {
+    return [
+        'Release notes are not bundled with this install.',
+        `Installed: ${current}`,
+        `https://www.npmjs.com/package/@pugi/cli/v/${current}`,
+    ].join('\n');
+}
+function renderEmptyChangelog(current) {
+    return [
+        'Bundled changelog is empty — no parsed sections.',
+        `Installed: ${current}`,
+        `https://www.npmjs.com/package/@pugi/cli/v/${current}`,
+    ].join('\n');
+}
+//# sourceMappingURL=release-notes.js.map

package/dist/runtime/commands/repo-map.js

@@ -0,0 +1,95 @@
+/**
+ * `pugi repo-map` — .
+ *
+ * Builds a compact AST-light summary of the workspace's source surface
+ * (top-level function / class / interface / type / enum declarations
+ * plus the leading JSDoc / markdown summary line) and renders it as
+ * a markdown listing. The same builder backs the engine boot-time
+ * system-prompt injection — running `pugi repo-map` shows the operator
+ * EXACTLY what the engine would inject.
+ *
+ * The command surface mirrors the L28 spec:
+ *
+ *  `pugi repo-map`            build + show (cache hit when fresh)
+ *  `pugi repo-map --refresh`  bust cache + rebuild from scratch
+ *  `pugi repo-map --format=json` machine-readable envelope
+ *
+ * Exit code is always 0 — the command is informational, not a gate.
+ * The `--json` envelope carries an `ok: false` branch when the repo is
+ * too large to map (the L28 5000-file ceiling), so scripted callers
+ * can detect the skip without parsing prose.
+ *
+ * The handler is awaited even though the underlying pipeline is sync,
+ * matching the pattern of every other `run*Command` (stickers, status,
+ * doctor) so future async paths (remote cache pull) drop в without
+ * changing the call sites.
+ */
+import { buildAndFormatRepoMap } from '../../core/repo-map/build.js';
+/**
+ * Run the command. Always resolves к the structured envelope so the
+ * caller can chain into a status table. Exit code is set к 0 in every
+ * branch — the command is informational.
+ */
+export async function runRepoMapCommand(ctx) {
+    const result = buildAndFormatRepoMap({
+        root: ctx.cwd,
+        refresh: ctx.refresh === true,
+        writeCache: ctx.writeCache !== false,
+        formatBytesCap: ctx.formatBytesCap,
+        omitHeader: false,
+    });
+    if (!result.build.ok) {
+        const payload = {
+            ok: false,
+            command: 'repo-map',
+            root: result.build.root,
+            reason: result.build.reason,
+            walked: result.build.walked,
+        };
+        const text = result.build.reason === 'too-large'
+            ? `repo-map skipped: workspace exceeds the ${result.build.walked}-file ceiling. Tighten .pugiignore and re-run.`
+            : `repo-map skipped: no workspace at ${result.build.root}.`;
+        ctx.writeOutput(payload, text);
+        // Informational — never a gate.
+        process.exitCode = 0;
+        return payload;
+    }
+    const build = result.build;
+    if (!build.ok) {
+        // TS narrowing — handled above.
+        throw new Error('unreachable');
+    }
+    const format = result.format;
+    const payload = {
+        ok: true,
+        command: 'repo-map',
+        root: build.root,
+        stats: {
+            filesScanned: build.scanStats.walked,
+            filesIncluded: format.filesIncluded,
+            filesRebuilt: build.diffStats.rebuilt,
+            filesReused: build.diffStats.reused,
+            filesDropped: build.diffStats.dropped,
+            skippedLarge: build.scanStats.skippedLarge,
+            skippedIgnored: build.scanStats.skippedIgnored,
+            bytes: format.bytes,
+            truncated: format.truncated,
+        },
+        cachePath: build.cachePath,
+        cacheWritten: build.cacheWritten,
+        text: format.text,
+    };
+    // The text surface IS the formatted markdown. We append a one-line
+    // stats footer so the operator sees the cache-hit ratio at a glance
+    // (engine context cache is opaque otherwise) — kept off the JSON
+    // payload so machine consumers do not have to skip a trailer.
+    const footer = formatFooter(payload.stats);
+    ctx.writeOutput(payload, `${format.text}\n${footer}`);
+    process.exitCode = 0;
+    return payload;
+}
+function formatFooter(stats) {
+    const truncatedHint = stats.truncated ? ' (truncated к budget)' : '';
+    return `${stats.filesIncluded} files · ${stats.filesRebuilt} rebuilt · ${stats.filesReused} cache hit · ${stats.bytes} bytes${truncatedHint}`;
+}
+//# sourceMappingURL=repo-map.js.map