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

package/dist/core/feedback/submitter.js

@@ -0,0 +1,145 @@
+/**
+ * Feedback POST submitter — .
+ *
+ * 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.
+ *
+ * ( upstream `FileEditTool.ts`, 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