@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/core/feedback/queue.js

@@ -0,0 +1,177 @@
+/**
+ * Local feedback queue — Leak L21 (2026-05-27).
+ *
+ * `pugi feedback` POSTs collected operator feedback to the admin-api
+ * `/api/pugi/feedback` route. When that round-trip fails (endpoint
+ * missing, network down, server 5xx), the submitter falls back to
+ * appending the envelope to `<cwd>/.pugi/feedback-queue.jsonl`. On the
+ * next online session the flusher drains the queue silently in the
+ * background.
+ *
+ * # Module contract
+ *
+ *   - Per-workspace storage. The queue file lives at
+ *     `<cwd>/.pugi/feedback-queue.jsonl` so the operator-visible state
+ *     stays alongside the project's other Pugi metadata. Multi-repo
+ *     operators get one queue per repo — matches the rest of `.pugi/`.
+ *
+ *   - JSONL append-only format. One envelope per line. Newlines inside
+ *     the comment field are escaped as `\n` by `JSON.stringify`. The
+ *     enqueue path uses an atomic `O_APPEND` write so concurrent
+ *     `pugi feedback` invocations from a split-screen REPL + shell do
+ *     not interleave half-records.
+ *
+ *   - The flusher is best-effort. It returns counts but never throws —
+ *     a failed flush leaves the queue untouched and a successful flush
+ *     atomically rewrites the file with the remaining (unsubmitted)
+ *     envelopes. Partial-success is the normal path when the server
+ *     accepts the first N but 5xx's the (N+1)th.
+ *
+ *   - The queue file is intentionally NOT readable by anything beyond
+ *     the flusher. The operator's free-text comments are confidential
+ *     — we do not surface them in `/status` / `/doctor` / telemetry.
+ *
+ *   - All filesystem writes go through `mkdirSync({recursive: true})`
+ *     so the first-ever enqueue on a fresh workspace lazily creates
+ *     `.pugi/` without depending on an earlier `pugi init`.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/**
+ * Resolve the queue file path for a workspace. Centralised so the
+ * submitter + flusher + tests agree on a single canonical location.
+ */
+export function feedbackQueuePath(cwd) {
+    return resolve(cwd, '.pugi', 'feedback-queue.jsonl');
+}
+/**
+ * Append one envelope atomically. Uses `O_APPEND` semantics via
+ * `appendFileSync` so concurrent invocations from a split-screen
+ * REPL + shell cannot interleave bytes mid-line.
+ *
+ * Returns the absolute path written so callers can surface it in the
+ * "Feedback queued locally" toast.
+ */
+export function enqueueFeedback(env, cwd) {
+    const path = feedbackQueuePath(cwd);
+    mkdirSync(dirname(path), { recursive: true });
+    // JSON.stringify of an object never emits raw newlines; the trailing
+    // '\n' is the line separator. JSONL parsers split on '\n' so the
+    // separator survives round-trips.
+    const line = `${JSON.stringify(env)}\n`;
+    appendFileSync(path, line, { encoding: 'utf8' });
+    return path;
+}
+export function readFeedbackQueue(cwd) {
+    const path = feedbackQueuePath(cwd);
+    if (!existsSync(path)) {
+        return { envelopes: [], parseErrors: [] };
+    }
+    const contents = readFileSync(path, 'utf8');
+    const lines = contents.split('\n');
+    const envelopes = [];
+    const parseErrors = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i]?.trim();
+        if (!raw)
+            continue;
+        try {
+            const parsed = JSON.parse(raw);
+            // Minimal shape check — we don't full-validate here because the
+            // server is the trust boundary. Just guard against obvious
+            // corruption that would make the line un-submittable.
+            if (typeof parsed.category === 'string'
+                && typeof parsed.rating === 'number'
+                && typeof parsed.comment === 'string'
+                && typeof parsed.ts === 'string'
+                && typeof parsed.cliVersion === 'string') {
+                envelopes.push(parsed);
+            }
+            else {
+                parseErrors.push(i + 1);
+            }
+        }
+        catch {
+            parseErrors.push(i + 1);
+        }
+    }
+    return { envelopes, parseErrors };
+}
+/**
+ * Rewrite the queue file atomically with the remaining (unsubmitted)
+ * envelopes. Called by the flusher after a partial-success drain.
+ *
+ * Atomicity: write to a sibling `.tmp` then rename. On a crash mid-
+ * rewrite the original file is preserved (rename is atomic on POSIX
+ * + on NTFS via `MoveFileEx`).
+ */
+export function rewriteFeedbackQueue(remaining, cwd) {
+    const path = feedbackQueuePath(cwd);
+    if (remaining.length === 0) {
+        // Clear the file by truncating to empty. Done in-place — we still
+        // want the file to exist (presence signals an active workspace)
+        // but with zero bytes so the next read returns no envelopes.
+        if (existsSync(path)) {
+            writeFileSync(path, '', { encoding: 'utf8' });
+        }
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    const body = remaining.map((env) => JSON.stringify(env)).join('\n') + '\n';
+    writeFileSync(tmp, body, { encoding: 'utf8' });
+    // Use writeFileSync's atomic-replace semantics by going through
+    // tmp + rename. Node's `fs.renameSync` is the atomic primitive
+    // on POSIX. We avoid `fs.writeFileSync` directly on `path`
+    // because writeFileSync truncates first which leaves a brief
+    // window of zero-byte state if the process is killed mid-write.
+    renameSync(tmp, path);
+}
+/**
+ * Drain the queue. Best-effort: each envelope is submitted in order;
+ * a `false` return keeps it in the queue for the next attempt; a
+ * `true` return removes it. After all envelopes are processed the
+ * queue file is rewritten with the unsubmitted ones.
+ *
+ * The function NEVER throws — it returns a structured result and
+ * the caller decides whether to log / surface failures. This keeps
+ * the silent-background-drain path on session-start safe.
+ */
+export async function flushFeedbackQueue(cwd, submit) {
+    const { envelopes, parseErrors } = readFeedbackQueue(cwd);
+    if (envelopes.length === 0) {
+        return {
+            attempted: 0,
+            succeeded: 0,
+            failed: 0,
+            failedEnvelopes: [],
+            parseErrors,
+        };
+    }
+    let succeeded = 0;
+    const failedEnvelopes = [];
+    for (const env of envelopes) {
+        let ok = false;
+        try {
+            ok = await submit(env);
+        }
+        catch {
+            ok = false;
+        }
+        if (ok) {
+            succeeded += 1;
+        }
+        else {
+            failedEnvelopes.push(env);
+        }
+    }
+    rewriteFeedbackQueue(failedEnvelopes, cwd);
+    return {
+        attempted: envelopes.length,
+        succeeded,
+        failed: failedEnvelopes.length,
+        failedEnvelopes,
+        parseErrors,
+    };
+}
+//# sourceMappingURL=queue.js.map

package/dist/core/feedback/submitter.js

@@ -0,0 +1,145 @@
+/**
+ * Feedback POST submitter — Leak L21 (2026-05-27).
+ *
+ * Submits one `FeedbackEnvelope` to the admin-api `/api/pugi/feedback`
+ * route. Designed for graceful degradation:
+ *
+ *   - 200/201/204                → success
+ *   - 404 / route not found      → "endpoint missing, fall back to queue"
+ *   - 4xx (other)                → permanent — discard (do NOT requeue)
+ *   - 5xx / network error / abort → transient — caller should enqueue
+ *
+ * The submitter does NOT touch the local queue. The caller wires the
+ * submitter to `enqueueFeedback` on a `transient` result, and to a
+ * silent log on a `permanent` failure. This split keeps the submitter
+ * a pure HTTP wrapper that the flusher (`flushFeedbackQueue`) can
+ * reuse without filesystem side effects.
+ */
+const DEFAULT_TIMEOUT_MS = 8000;
+/**
+ * Build the absolute submit URL from the base API URL. Centralised so
+ * the spec can reference one canonical place when asserting the
+ * outgoing path. The leading slash is normalised so a base URL with
+ * or without trailing slash both produce a well-formed URL.
+ */
+export function feedbackSubmitUrl(apiUrl) {
+    const base = apiUrl.replace(/\/+$/u, '');
+    return `${base}/api/pugi/feedback`;
+}
+/**
+ * Submit one envelope. See `FeedbackSubmitResult` for the contract.
+ *
+ * Never throws — every failure path is mapped to a result variant so
+ * callers do not need a try/catch boundary.
+ */
+export async function submitFeedback(env, config) {
+    const url = feedbackSubmitUrl(config.apiUrl);
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const headers = {
+            'content-type': 'application/json',
+            'user-agent': `pugi-cli/${env.cliVersion}`,
+        };
+        if (config.apiKey) {
+            headers['authorization'] = `Bearer ${config.apiKey}`;
+        }
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(env),
+            signal: controller.signal,
+        });
+        const status = res.status;
+        if (status >= 200 && status < 300) {
+            return { kind: 'ok', httpStatus: status };
+        }
+        if (status === 404) {
+            // The most common transient cause: admin-api hasn't shipped the
+            // route yet. Treat as retry-worthy so once the controller lands
+            // a future flush picks it up.
+            return {
+                kind: 'transient',
+                reason: 'admin-api /api/pugi/feedback not deployed yet',
+                httpStatus: status,
+            };
+        }
+        if (status >= 500) {
+            return {
+                kind: 'transient',
+                reason: `server error ${status}`,
+                httpStatus: status,
+            };
+        }
+        // Any other 4xx — auth failure, payload rejected, rate-limit
+        // exceeded. None of those will fix themselves on a silent retry,
+        // so we mark them permanent. The operator sees a one-line error
+        // and the envelope is dropped (not queued).
+        return {
+            kind: 'permanent',
+            reason: `client error ${status}`,
+            httpStatus: status,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // AbortController.abort fires when the timeout elapses. We treat
+        // it as transient so the queue picks it up on the next online
+        // session. Same for plain network errors (`fetch failed`, ECONNREFUSED).
+        return { kind: 'transient', reason: `network: ${message}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Bundle the last N turns of the conversation into a redacted
+ * `FeedbackSessionContext`. The redactor:
+ *
+ *   - Caps at 5 turns (most recent). Older context is dropped — the
+ *     submitter never sees it.
+ *   - Truncates each turn to 240 chars + ellipsis. Operator comments
+ *     are the primary signal; raw transcript is just disambiguation.
+ *   - Strips bearer tokens, JWT-like blobs, and `PUGI_API_KEY=`-style
+ *     env-var prefixes. Conservative — we'd rather drop a few
+ *     non-secret characters than leak a key.
+ *
+ * The function is pure + sync so tests can pin its output without a
+ * worktree harness.
+ */
+export function redactSessionContext(turns, options = {}) {
+    const lastFive = turns.slice(-5);
+    const previewed = lastFive.map((turn) => ({
+        role: turn.role,
+        preview: redactPreview(truncate(turn.text, 240)),
+    }));
+    return {
+        turnCount: previewed.length,
+        turns: previewed,
+        ...(options.gitBranch ? { gitBranch: options.gitBranch } : {}),
+    };
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+/**
+ * Conservative secret-blanking. The rules:
+ *   - Bearer tokens: `Bearer <token>` → `Bearer ***REDACTED***`
+ *   - Long base64/JWT-ish blobs (≥ 40 chars of [A-Za-z0-9_-/=+]):
+ *     replace the inner middle with `***`. Keeps a head + tail so the
+ *     operator can still spot which kind of secret it was.
+ *   - `PUGI_API_KEY=...` and similar `*_KEY=`/`*_TOKEN=` lookalikes:
+ *     replace the value with `***REDACTED***`.
+ */
+function redactPreview(s) {
+    let out = s;
+    out = out.replace(/bearer\s+[A-Za-z0-9._-]{20,}/giu, 'Bearer ***REDACTED***');
+    out = out.replace(/([A-Z][A-Z0-9_]*?(?:KEY|TOKEN|SECRET|PASSWORD))\s*=\s*\S+/gu, '$1=***REDACTED***');
+    out = out.replace(/\b([A-Za-z0-9_-]{6})[A-Za-z0-9_/+=-]{30,}([A-Za-z0-9_-]{4})\b/gu, '$1***$2');
+    return out;
+}
+//# sourceMappingURL=submitter.js.map

package/dist/core/file-cache.js

@@ -1,6 +1,45 @@
+/**
+ * Per-session file-read cache + stale-read gate.
+ *
+ * Leak intel L1 (openclaude `FileEditTool.ts`, 2026-05-27 gap analysis
+ * §5.1): every FileEdit must validate the operator's last-known view of
+ * the file before mutating disk. The gate compares BOTH `mtimeMs` and
+ * `sha256(content)` of the file on disk against the record captured at
+ * read time:
+ *
+ *   - mtimeMs is a cheap fast-path. If the inode mtime hasn't moved
+ *     since the read, the content hash cannot have changed (barring a
+ *     filesystem with hash-on-mtime-skew bugs) and we can short-circuit.
+ *   - sha256 is the authoritative gate. A user editor that writes back
+ *     identical content can leave mtime untouched on some filesystems
+ *     (atomic-rename with preserved metadata), and conversely `touch`
+ *     bumps mtime without changing content. Hash is the truth.
+ *
+ * Both signals must agree for the gate to PASS. Any divergence => STALE
+ * => refuse the edit, force the model to re-read.
+ *
+ * Cache lifetime: per-session. `FileReadCache.clear()` is called at
+ * session.end (see `core/session.ts`). The cache is intentionally NOT
+ * durable across sessions — a re-read after restart is cheap and stale
+ * cross-session entries would themselves be a soundness hazard.
+ *
+ * Exception: writeTool for create-new (path doesn't exist on disk) does
+ * not consult the cache. Creating a brand new file has no "last-known
+ * view" to invalidate.
+ */
 import { createHash } from 'node:crypto';
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
+export class StaleReadError extends Error {
+    reason;
+    path;
+    constructor(path, reason, detail) {
+        super(`stale_read: ${path} — ${detail}. Re-read the file before editing.`);
+        this.name = 'StaleReadError';
+        this.reason = reason;
+        this.path = path;
+    }
+}
 export class FileReadCache {
     records = new Map();
     set(record) {
@@ -9,6 +48,70 @@ export class FileReadCache {
     get(root, path) {
         return this.records.get(resolve(root, path));
     }
+    /**
+     * Validate a candidate edit against the cached read record. Returns
+     * a tagged-union: `{ stale: false }` when the edit may proceed, or
+     * `{ stale: true, reason, detail }` when the gate must refuse.
+     *
+     * Pure function over the cache + supplied `currentMtimeMs` /
+     * `currentContent` — does NOT touch disk. Callers (editTool /
+     * writeTool) do their own `statSync` + `readFileSync` because they
+     * also need the content for the diff/edit itself.
+     *
+     * @param root           workspace root (used to resolve relative path)
+     * @param path           workspace-relative file path
+     * @param currentMtimeMs `fs.statSync().mtimeMs` of the on-disk file
+     * @param currentContent UTF-8 contents of the on-disk file
+     */
+    validate(root, path, currentMtimeMs, currentContent) {
+        const record = this.get(root, path);
+        if (!record) {
+            return {
+                stale: true,
+                reason: 'no_prior_read',
+                detail: 'file must be read first',
+            };
+        }
+        // Fast-path: mtime hasn't moved. Hash check is redundant in the
+        // common case but cheap, so we still verify below. Skipping hash
+        // when mtime matches would allow a subtle bug class (in-place
+        // writers that preserve mtime) to slip through.
+        if (currentMtimeMs > record.mtimeMs) {
+            // mtime advanced — confirm with hash before flagging. A bump
+            // without a content change (e.g. `touch`) shouldn't fire stale.
+            const currentHash = hashContent(currentContent);
+            if (currentHash !== record.sha256) {
+                return {
+                    stale: true,
+                    reason: 'mtime_drift',
+                    detail: `mtime advanced (${record.mtimeMs} → ${currentMtimeMs}) and content hash diverged`,
+                };
+            }
+            // mtime bumped but content identical — treat as fresh. The cache
+            // entry's mtime is intentionally NOT refreshed here; the next
+            // edit will hit the same path and the gate will keep agreeing.
+            return { stale: false };
+        }
+        // mtime hasn't moved — hash MUST still match the record. A
+        // mismatch is a filesystem-level inconsistency or an in-place
+        // editor that preserves mtime; either way, refuse.
+        const currentHash = hashContent(currentContent);
+        if (currentHash !== record.sha256) {
+            return {
+                stale: true,
+                reason: 'hash_drift',
+                detail: 'content hash diverged from last read (mtime unchanged)',
+            };
+        }
+        return { stale: false };
+    }
+    /**
+     * Drop every cached record. Called by session.end so a fresh REPL
+     * session never inherits stale cross-session entries.
+     */
+    clear() {
+        this.records.clear();
+    }
 }
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
@@ -26,4 +129,13 @@ export function createReadRecord(root, path, content, source) {
         source,
     };
 }
+/**
+ * Convenience helper: does this absolute path exist on disk? Wraps the
+ * existsSync import so file-tools.ts can decide between create-new
+ * (skip stale gate) and update-existing (apply stale gate) without
+ * pulling in another fs import.
+ */
+export function pathExists(absolutePath) {
+    return existsSync(absolutePath);
+}
 //# sourceMappingURL=file-cache.js.map

package/dist/core/hooks/events.js

@@ -0,0 +1,44 @@
+/**
+ * Pugi hooks MVP — typed event payloads (Leak L12).
+ *
+ * This module ships the MINIMAL FIRST PASS of the user-config hook
+ * matrix. Two lifecycle events out of the eventual 8 land here:
+ *
+ *   - `SessionStart`  — fired once when the REPL boots (`session.ts`).
+ *   - `PreToolUse`    — fired before each tool dispatch
+ *                       (`engine/tool-bridge.ts`). Non-zero exit from a
+ *                       hook with `blocking: true` aborts the dispatch.
+ *
+ * The remaining 6 events (`PostToolUse`, `UserPromptSubmit`, `Stop`,
+ * `SubagentStop`, `PreCompact`, `Notification`) are deferred to a
+ * fast-follow PR. The pattern established here — discriminated union
+ * payloads + registry-driven dispatch — is the reusable template.
+ *
+ * Design note (parallel surface): an older surface lives at
+ * `apps/pugi-cli/src/core/hooks.ts` and uses a flat-array `hooks: [{
+ * event, match, run }]` config shape with per-hook events. THIS module
+ * adopts the Claude Code-style nested `hooks: { EventName: [{ matcher,
+ * command }] }` config shape. The two surfaces co-exist intentionally
+ * for the MVP — they read different files (`~/.pugi/hooks.json` vs.
+ * `~/.pugi/hooks-mvp.json`) so operator configs do not collide. The
+ * fast-follow PR consolidates the two readers.
+ *
+ * Brand voice: ASCII only, no emoji, no em-dashes, no marketing prose.
+ */
+/** Events the MVP actually fires. The 6 deferred events live in the */
+/** type but no integration point emits them yet. */
+export const MVP_HOOK_EVENTS = [
+    'SessionStart',
+    'PreToolUse',
+];
+export const ALL_HOOK_EVENTS_V2 = [
+    'SessionStart',
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'PreCompact',
+    'Notification',
+];
+//# sourceMappingURL=events.js.map

package/dist/core/hooks/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the MVP hooks module (Leak L12).
+ *
+ * Re-exports the registry, runner, and event types so callers can do
+ *
+ *   import { loadHooksConfig, fireHooks } from '../core/hooks/index.js';
+ *
+ * without reaching into individual files. See `events.ts` for the
+ * scope note explaining why this MVP module co-exists with the older
+ * `src/core/hooks.ts` surface.
+ */
+export { DEFAULT_HOOK_TIMEOUT_MS, HooksConfig, MAX_HOOK_TIMEOUT_MS, defaultHooksMvpPath, isToolEvent, loadHooksConfig, matchesTool, } from './registry.js';
+export { fireHooks } from './runner.js';
+export { ALL_HOOK_EVENTS_V2, MVP_HOOK_EVENTS, } from './events.js';
+//# sourceMappingURL=index.js.map