@pugi/cli 0.1.0-alpha.10

package/dist/runtime/commands/undo.js

@@ -0,0 +1,329 @@
+import { execFileSync } from 'node:child_process';
+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';
+/**
+ * `pugi undo` — revert the file mutations from the most recent successful
+ * `write` / `edit` / `multi_edit` tool result.
+ *
+ * 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` names a
+ *      mutating tool (write / edit / multi_edit).
+ *   3. From that point, gather every `file_mutation` event that shares
+ *      the same `toolCallId`. M1 records one `file_mutation` per
+ *      mutating tool call, but the loop is shaped for the multi_edit
+ *      future case where a single tool call mutates many files.
+ *
+ * Restore strategy (M1 — no blob store yet):
+ *   For each mutation we restore from the workspace's git history when
+ *   possible, with a strict safety gate to avoid silently overwriting
+ *   the user's WORK-IN-PROGRESS:
+ *
+ *   - `operation: create`  → unlink the created file iff its current
+ *     sha256 matches the recorded `afterHash`. Skip otherwise (the user
+ *     has edited it since; refuse to delete their work).
+ *   - `operation: update`  → restore from `HEAD:<path>` iff (a) the file
+ *     was tracked at HEAD AND (b) the HEAD content's sha256 matches the
+ *     recorded `beforeHash`. Otherwise abort the turn (no partial
+ *     reverts — the spec is atomic).
+ *   - `operation: delete`  → restore the deleted file from `HEAD:<path>`
+ *     if tracked there; skip otherwise.
+ *
+ * If any single restore is unsafe the whole turn aborts with exit code
+ * 1 and no files are touched.
+ *
+ * Why git as the backing store: the file cache stores hash + metadata
+ * but NOT raw content (see `core/file-cache.ts`). M1 ships without a
+ * dedicated blob CAS; `git show HEAD:<path>` is the cheapest authoritative
+ * source for pre-mutation content as long as the workspace is a git
+ * repository. The α6.4 SQLite session store will replace this with a
+ * proper before-blob ledger.
+ */
+const MUTATING_TOOLS = new Set(['write', 'edit', 'multi_edit']);
+export async function runUndoCommand(_args, ctx) {
+    const eventsPath = resolve(ctx.workspaceRoot, '.pugi/events.jsonl');
+    if (!existsSync(eventsPath)) {
+        ctx.writeOutput({ command: 'undo', status: 'noop', reason: 'no_session' }, 'No session events found. Nothing to undo.');
+        return;
+    }
+    const events = parseEvents(eventsPath);
+    const target = findLastMutationTurn(events);
+    if (!target) {
+        ctx.writeOutput({ command: 'undo', status: 'noop', reason: 'no_mutation' }, 'No mutating tool result found in the session log.');
+        return;
+    }
+    if (target.mutations.length === 0) {
+        ctx.writeOutput({
+            command: 'undo',
+            status: 'noop',
+            reason: 'no_file_mutations',
+            toolCallId: target.toolCallId,
+        }, `Tool call ${target.toolCallId} recorded no file mutations.`);
+        return;
+    }
+    // Pre-flight: confirm every mutation is reversible before touching
+    // disk. This keeps the operation atomic per spec.
+    const plan = planReverts(ctx.workspaceRoot, target.mutations);
+    if (plan.aborted) {
+        ctx.writeOutput({
+            command: 'undo',
+            status: 'aborted',
+            reason: plan.reason,
+            toolCallId: target.toolCallId,
+            unsafe: plan.unsafe,
+        }, `Refusing to undo ${target.toolCallId}: ${plan.reason}`);
+        process.exitCode = 1;
+        return;
+    }
+    const restored = [];
+    for (const step of plan.steps) {
+        try {
+            executeRevert(ctx.workspaceRoot, step);
+            restored.push({ path: step.path, operation: step.operation });
+        }
+        catch (error) {
+            // A revert failed after pre-flight said it was safe. Surface the
+            // error and bail out — the spec says no partial state on failure.
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.writeOutput({
+                command: 'undo',
+                status: 'failed',
+                reason: message,
+                toolCallId: target.toolCallId,
+                restored,
+                failedAt: step.path,
+            }, `Undo failed mid-flight on ${step.path}: ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Audit the inverse mutations so the event log explains the undo.
+    const toolCallId = recordToolCall(ctx.session, 'undo', `revert ${target.toolCallId}`);
+    for (const step of plan.steps) {
+        recordFileMutation(ctx.session, {
+            toolCallId,
+            path: step.path,
+            operation: step.operation === 'create' ? 'delete' : 'update',
+            beforeHash: step.beforeHash,
+            afterHash: step.afterHash,
+        });
+    }
+    recordToolResult(ctx.session, toolCallId, 'success', `Undid ${restored.length} mutation(s) from ${target.toolCallId}`);
+    ctx.writeOutput({
+        command: 'undo',
+        status: 'ok',
+        toolCallId: target.toolCallId,
+        restored,
+    }, [
+        `Undid ${restored.length} mutation(s) from ${target.toolCallId}:`,
+        ...restored.map((entry) => `  ${entry.operation.padEnd(7)} ${entry.path}`),
+    ].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 {
+            // Drop malformed lines silently — partial writes mid-shutdown can
+            // produce them and undo should still work for the rest.
+        }
+    }
+    return out;
+}
+function findLastMutationTurn(events) {
+    const toolCalls = new Map();
+    const results = [];
+    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 });
+        }
+        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,
+            });
+        }
+    }
+    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 (!MUTATING_TOOLS.has(call.tool))
+            continue;
+        // Collect file_mutation events whose toolCallId matches. We do NOT
+        // window by event index: M1 emits the file_mutation alongside the
+        // tool_result, but a future iteration that emits them earlier
+        // (e.g. mid-stream for multi_edit) still maps correctly.
+        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 {
+            toolCallId: result.toolCallId,
+            resultIndex: result.index,
+            tool: call.tool,
+            mutations,
+        };
+    }
+    return null;
+}
+function planReverts(root, mutations) {
+    const steps = [];
+    const unsafe = [];
+    for (const mutation of mutations) {
+        const abs = resolve(root, mutation.path);
+        switch (mutation.operation) {
+            case 'create': {
+                if (!existsSync(abs)) {
+                    // Already gone — nothing to undo for this entry.
+                    continue;
+                }
+                const current = readFileSync(abs, 'utf8');
+                const currentHash = hashContent(current);
+                if (!mutation.afterHash || currentHash !== mutation.afterHash) {
+                    unsafe.push(`${mutation.path}: created by Pugi, then modified by the user — refusing to delete uncommitted work`);
+                    continue;
+                }
+                steps.push({
+                    path: mutation.path,
+                    operation: 'create',
+                    beforeHash: mutation.afterHash,
+                    afterHash: undefined,
+                });
+                break;
+            }
+            case 'update': {
+                if (!existsSync(abs)) {
+                    unsafe.push(`${mutation.path}: file expected to exist for update revert, not found`);
+                    continue;
+                }
+                const current = readFileSync(abs, 'utf8');
+                const currentHash = hashContent(current);
+                if (!mutation.afterHash || currentHash !== mutation.afterHash) {
+                    unsafe.push(`${mutation.path}: updated by Pugi, then modified by the user — refusing to overwrite uncommitted work`);
+                    continue;
+                }
+                const headContent = readHead(root, mutation.path);
+                if (headContent === null) {
+                    unsafe.push(`${mutation.path}: no git HEAD version available for revert`);
+                    continue;
+                }
+                if (mutation.beforeHash && hashContent(headContent) !== mutation.beforeHash) {
+                    unsafe.push(`${mutation.path}: git HEAD differs from the pre-mutation hash — refusing to restore an unverifiable version`);
+                    continue;
+                }
+                steps.push({
+                    path: mutation.path,
+                    operation: 'update',
+                    beforeHash: mutation.afterHash,
+                    afterHash: mutation.beforeHash,
+                    restoreContent: headContent,
+                });
+                break;
+            }
+            case 'delete': {
+                const headContent = readHead(root, mutation.path);
+                if (headContent === null) {
+                    unsafe.push(`${mutation.path}: deleted file has no git HEAD version, cannot restore`);
+                    continue;
+                }
+                if (mutation.beforeHash && hashContent(headContent) !== mutation.beforeHash) {
+                    unsafe.push(`${mutation.path}: git HEAD differs from the pre-deletion hash, cannot restore safely`);
+                    continue;
+                }
+                steps.push({
+                    path: mutation.path,
+                    operation: 'delete',
+                    beforeHash: undefined,
+                    afterHash: mutation.beforeHash,
+                    restoreContent: headContent,
+                });
+                break;
+            }
+            case 'move':
+                // Move reverts are not in M1 scope — the tool layer does not yet
+                // emit `move` mutations. Flag as unsafe so a future operator who
+                // hits this gets a clear failure instead of partial revert.
+                unsafe.push(`${mutation.path}: move undo is not supported in M1`);
+                break;
+        }
+    }
+    if (unsafe.length > 0) {
+        return {
+            aborted: true,
+            reason: 'one or more files are unsafe to revert',
+            unsafe,
+            steps: [],
+        };
+    }
+    return { aborted: false, steps };
+}
+function executeRevert(root, step) {
+    const abs = resolve(root, step.path);
+    if (step.operation === 'create') {
+        // We previously created the file. Reverting means deleting it.
+        unlinkSync(abs);
+        return;
+    }
+    if (step.restoreContent === undefined) {
+        throw new Error(`internal: restoreContent missing for ${step.path}`);
+    }
+    // Atomic write via tmp+rename — same pattern as file-tools.writeTool.
+    const tmp = `${abs}.pugi-undo-${Date.now()}`;
+    writeFileSync(tmp, step.restoreContent, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, abs);
+}
+function readHead(root, path) {
+    try {
+        const out = execFileSync('git', ['show', `HEAD:${path}`], {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=undo.js.map

package/dist/runtime/update-check.js

@@ -0,0 +1,294 @@
+/**
+ * Update check + install-method detection — Sprint α6.2.
+ *
+ * Shows the REPL operator a one-shot banner at startup when the npm
+ * registry advertises a `@pugi/cli` version newer than what is running.
+ * The banner adapts the upgrade hint per install method so the operator
+ * sees a copy-pasteable command for their toolchain (brew / npm / curl).
+ *
+ * Constraints baked into the spec:
+ *
+ *   - **Default-quiet.** Network errors, cache misses, and the
+ *     `PUGI_SKIP_UPDATE_BANNER=1` env var all return `null` so the
+ *     REPL renders unchanged.
+ *   - **24h cache.** The check runs at most once per day, persisted to
+ *     `~/.pugi/update-check.json`. Repeated REPL launches in the same
+ *     day skip the registry call entirely.
+ *   - **3s timeout.** A slow registry never blocks REPL startup; the
+ *     undici request is aborted after 3 seconds and treated as a
+ *     silent miss.
+ *   - **Pure helpers, IO at the edge.** Detection, comparison, cache
+ *     decode/encode are exported as pure functions with explicit env /
+ *     home / now / fetch seams so the spec's 8 tests can drive every
+ *     branch without touching the network or the real filesystem.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { request } from 'undici';
+const REGISTRY_URL = 'https://registry.npmjs.org/@pugi/cli/latest';
+const FETCH_TIMEOUT_MS = 3_000;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+/**
+ * Pin the install toolchain from the binary path + a small set of env
+ * markers. Order matters: the curl installer sets PUGI_VIA_CURL_INSTALL
+ * unconditionally, so we honor it first; brew is path-based; npm is the
+ * fallback for anything that looks like a node_modules layout; otherwise
+ * unknown.
+ */
+export function detectInstallMethod(input = {}) {
+    const env = input.env ?? process.env;
+    const execPath = input.execPath ?? process.execPath;
+    if (env.PUGI_VIA_CURL_INSTALL === '1')
+        return 'curl';
+    // Homebrew on macOS keeps node + bin shims under /opt/homebrew (Apple
+    // silicon) or /usr/local/Cellar (Intel). Either suffices to pin brew.
+    if (execPath.includes('/opt/homebrew/') ||
+        execPath.includes('/usr/local/Cellar/') ||
+        execPath.includes('/homebrew/')) {
+        return 'brew';
+    }
+    // npm-global layouts: nvm, fnm, asdf, volta, yarn-global, and the
+    // classic `~/.npm-packages` PATH prefix all leave a fingerprint on
+    // execPath or PATH. Treat any of these as `npm` so the banner shows
+    // the matching `npm install -g` hint.
+    const pathEntries = (env.PATH ?? '').split(':');
+    const npmFingerprints = [
+        '/.nvm/',
+        '/.fnm/',
+        '/.volta/',
+        '/.asdf/',
+        '/.npm-packages/',
+        '/.config/yarn/global',
+    ];
+    if (npmFingerprints.some((marker) => execPath.includes(marker)))
+        return 'npm';
+    if (pathEntries.some((entry) => entry.includes('/.npm-packages') || entry.includes('/.config/yarn/global'))) {
+        return 'npm';
+    }
+    if (execPath.includes('/node_modules/'))
+        return 'npm';
+    return 'unknown';
+}
+/**
+ * Cache path resolver. PUGI_HOME wins (test seam matches the rest of
+ * the codebase), else `~/.pugi/update-check.json`.
+ */
+export function resolveCachePath(home, env = process.env) {
+    const root = env.PUGI_HOME ?? resolve(home ?? homedir(), '.pugi');
+    return resolve(root, 'update-check.json');
+}
+export function loadCache(home, env = process.env) {
+    const path = resolveCachePath(home, env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const text = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(text);
+        if (typeof parsed.checkedAt !== 'string' || typeof parsed.latestVersion !== 'string') {
+            return null;
+        }
+        return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion };
+    }
+    catch {
+        // Corrupt or unreadable cache — treat as no cache. The next write
+        // overwrites the file cleanly.
+        return null;
+    }
+}
+export function saveCache(record, home, env = process.env) {
+    const path = resolveCachePath(home, env);
+    const dir = path.slice(0, path.lastIndexOf('/'));
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8' });
+    }
+    catch {
+        // Best-effort. A read-only home or full disk should not crash REPL
+        // startup — we just skip caching this round.
+    }
+}
+export function isCacheFresh(record, nowMs) {
+    const checkedMs = Date.parse(record.checkedAt);
+    if (!Number.isFinite(checkedMs))
+        return false;
+    return nowMs - checkedMs < CACHE_TTL_MS;
+}
+/**
+ * Compare two semver strings (with prerelease support sufficient for
+ * `0.1.0-alpha.6` vs `0.1.0-alpha.7` / `0.1.0-beta.1` / `1.0.0`).
+ *
+ * Returns:
+ *   -1 if `a < b`
+ *    0 if `a === b`
+ *    1 if `a > b`
+ *
+ * Rules follow semver §11:
+ *   - Major.Minor.Patch compared numerically left-to-right.
+ *   - A version with a prerelease tag is LOWER than the same version
+ *     without one (`1.0.0-alpha` < `1.0.0`).
+ *   - Prerelease identifiers compared dot-by-dot; numeric chunks
+ *     numerically, mixed chunks ASCII-lexicographic.
+ */
+export function compareVersions(a, b) {
+    const [coreA, preA] = splitVersion(a);
+    const [coreB, preB] = splitVersion(b);
+    for (let i = 0; i < 3; i += 1) {
+        const da = coreA[i] ?? 0;
+        const db = coreB[i] ?? 0;
+        if (da < db)
+            return -1;
+        if (da > db)
+            return 1;
+    }
+    if (preA === null && preB === null)
+        return 0;
+    if (preA === null)
+        return 1;
+    if (preB === null)
+        return -1;
+    return comparePrerelease(preA, preB);
+}
+function splitVersion(v) {
+    const dashIdx = v.indexOf('-');
+    const coreStr = dashIdx === -1 ? v : v.slice(0, dashIdx);
+    const preStr = dashIdx === -1 ? null : v.slice(dashIdx + 1);
+    const core = coreStr.split('.').map((n) => {
+        const parsed = Number.parseInt(n, 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    });
+    return [core, preStr];
+}
+function comparePrerelease(a, b) {
+    const partsA = a.split('.');
+    const partsB = b.split('.');
+    const max = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < max; i += 1) {
+        const pa = partsA[i];
+        const pb = partsB[i];
+        if (pa === undefined)
+            return -1;
+        if (pb === undefined)
+            return 1;
+        const na = Number.parseInt(pa, 10);
+        const nb = Number.parseInt(pb, 10);
+        const aIsNum = String(na) === pa;
+        const bIsNum = String(nb) === pb;
+        if (aIsNum && bIsNum) {
+            if (na < nb)
+                return -1;
+            if (na > nb)
+                return 1;
+            continue;
+        }
+        if (aIsNum)
+            return -1; // numeric < alphanumeric, per semver §11
+        if (bIsNum)
+            return 1;
+        if (pa < pb)
+            return -1;
+        if (pa > pb)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * One-shot registry GET. Wrapped in a 3s timeout and silently swallows
+ * every failure mode — the spec says cache miss / network error = no
+ * banner. Returns the `version` string from npm's well-known
+ * `/:pkg/latest` document on success, or `null` on any failure.
+ */
+export async function fetchLatestVersion(fetcher = request) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetcher(REGISTRY_URL, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            bodyTimeout: FETCH_TIMEOUT_MS,
+            headersTimeout: FETCH_TIMEOUT_MS,
+            signal: controller.signal,
+        });
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+            await response.body.dump();
+            return null;
+        }
+        const text = await response.body.text();
+        const parsed = JSON.parse(text);
+        if (typeof parsed.version !== 'string' || parsed.version.length === 0)
+            return null;
+        return parsed.version;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * High-level orchestrator wired into the CLI startup path. Returns the
+ * banner payload when an update is available AND every silence rule
+ * declines to fire, otherwise `null`.
+ *
+ * Silence rules (any one of these short-circuits to `null`):
+ *   - `cliSkip === true` (operator passed `--no-update-check`).
+ *   - `env.PUGI_SKIP_UPDATE_BANNER === '1'`.
+ *   - `isTty === false` (CI / piped / scripted invocation).
+ *   - Cache + network both miss — silent skip per spec.
+ *   - `installed >= latest` — no upgrade to advertise.
+ */
+export async function checkForUpdate(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? Date.now;
+    const cliSkip = options.cliSkip === true;
+    const envSkip = env.PUGI_SKIP_UPDATE_BANNER === '1';
+    const isTty = options.isTty ??
+        (Boolean(process.stdout.isTTY) &&
+            Boolean(process.stdin.isTTY));
+    if (cliSkip || envSkip || !isTty)
+        return null;
+    // Cache-first path. A fresh cache (<24h) bypasses the registry round
+    // trip entirely so a daily REPL operator pays one network call per
+    // calendar day.
+    const cached = loadCache(options.home, env);
+    let latest = null;
+    if (cached && isCacheFresh(cached, now())) {
+        latest = cached.latestVersion;
+    }
+    else {
+        latest = await fetchLatestVersion(options.fetcher);
+        if (latest) {
+            saveCache({ checkedAt: new Date(now()).toISOString(), latestVersion: latest }, options.home, env);
+        }
+    }
+    if (!latest)
+        return null;
+    if (compareVersions(options.installed, latest) >= 0)
+        return null;
+    return {
+        installed: options.installed,
+        latest,
+        method: detectInstallMethod({ env }),
+    };
+}
+/**
+ * Render the per-method upgrade command. Pure helper so the Ink
+ * banner component and any future JSON / log surface share one source
+ * of truth on the copy.
+ */
+export function upgradeCommand(method) {
+    switch (method) {
+        case 'brew':
+            return 'brew upgrade pugi-io/tap/pugi';
+        case 'npm':
+            return 'npm install -g @pugi/cli@latest';
+        case 'curl':
+            return 'curl -fsSL https://install.pugi.io | sh';
+        case 'unknown':
+        default:
+            return 'npm install -g @pugi/cli@latest  # or your install method';
+    }
+}
+//# sourceMappingURL=update-check.js.map