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

package/dist/core/engine/verification-patterns.js

@@ -0,0 +1,195 @@
+/**
+ * PUGI-VERIFY-GATE — verification command detection.
+ *
+ * Background: Codex dogfood 2026-06-04 surfaced a P0 trust failure
+ * where the Pugi engine returned `status: done` + `exitCode: 0`
+ * even after `npm test` exited non-zero on a regression the agent
+ * itself had introduced. Root cause: no layer of the dispatch
+ * pipeline knew which bash invocations were verification commands,
+ * so the engine outcome had no way to gate the final status on
+ * test/lint/build pass.
+ *
+ * This module is the deterministic, configurable allowlist of regex
+ * patterns the engine uses to recognise verification commands at
+ * dispatch time. The detection is intentionally simple (anchored on
+ * the head of the command after sudo / env-prefix stripping) so the
+ * allowlist stays auditable. False negatives are recoverable (the
+ * agent can re-run with a recognised wrapper); false positives would
+ * silently down-grade unrelated commands and are forbidden.
+ *
+ * The pattern table is exported as `VERIFICATION_PATTERNS`; callers
+ * use `detectVerificationCommand(cmd)` for the boolean + tool-tag
+ * decision. Both surfaces are pure — no I/O, no session state, no
+ * environment reads.
+ */
+/**
+ * Canonical verification allowlist. Patterns target the head of each
+ * shell-separated component AFTER:
+ *   - leading whitespace is trimmed
+ *   - leading `sudo` / `time` / `env KEY=value` prefixes are stripped
+ *
+ * Pre-trim the cmd through `extractCommandHead` before matching.
+ *
+ * When extending: keep the regex anchored (`^`) so a path containing
+ * the tool name (`./scripts/npm.sh`) does not false-positive.
+ */
+export const VERIFICATION_PATTERNS = [
+    // ----- JavaScript / TypeScript ecosystem -----
+    // npm test / npm run test / npm run lint / npm run typecheck / npm run build
+    { tool: 'npm-test', pattern: /^npm\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'npm-lint', pattern: /^npm\s+run\s+lint\b/, category: 'lint' },
+    { tool: 'npm-typecheck', pattern: /^npm\s+run\s+typecheck\b/, category: 'typecheck' },
+    { tool: 'npm-build', pattern: /^npm\s+run\s+build\b/, category: 'build' },
+    // pnpm (with and without -C / --filter prefixes — match the full head)
+    { tool: 'pnpm-test', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'pnpm-lint', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?lint\b/, category: 'lint' },
+    { tool: 'pnpm-typecheck', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?typecheck\b/, category: 'typecheck' },
+    { tool: 'pnpm-build', pattern: /^pnpm(?:\s+(?:-C\s+\S+|--filter(?:\s+|=)\S+|-r))*\s+(?:run\s+)?build\b/, category: 'build' },
+    // yarn
+    { tool: 'yarn-test', pattern: /^yarn\s+(?:run\s+)?test\b/, category: 'test' },
+    { tool: 'yarn-lint', pattern: /^yarn\s+(?:run\s+)?lint\b/, category: 'lint' },
+    { tool: 'yarn-typecheck', pattern: /^yarn\s+(?:run\s+)?typecheck\b/, category: 'typecheck' },
+    { tool: 'yarn-build', pattern: /^yarn\s+(?:run\s+)?build\b/, category: 'build' },
+    // Direct test-runner invocations (npx and bare).
+    { tool: 'jest', pattern: /^(?:npx\s+)?jest\b/, category: 'test' },
+    { tool: 'vitest', pattern: /^(?:npx\s+)?vitest\b/, category: 'test' },
+    { tool: 'mocha', pattern: /^(?:npx\s+)?mocha\b/, category: 'test' },
+    { tool: 'tsc-typecheck', pattern: /^(?:npx\s+)?tsc\b(?=.*--noEmit|\s*$)/, category: 'typecheck' },
+    { tool: 'eslint', pattern: /^(?:npx\s+)?eslint\b/, category: 'lint' },
+    { tool: 'node-test', pattern: /^node\s+--test\b/, category: 'test' },
+    // ----- Python -----
+    { tool: 'pytest', pattern: /^(?:python\s+-m\s+)?pytest\b/, category: 'test' },
+    { tool: 'python-unittest', pattern: /^python\s+-m\s+unittest\b/, category: 'test' },
+    { tool: 'ruff', pattern: /^ruff\s+check\b/, category: 'lint' },
+    { tool: 'mypy', pattern: /^mypy\b/, category: 'typecheck' },
+    // ----- Rust -----
+    { tool: 'cargo-test', pattern: /^cargo\s+test\b/, category: 'test' },
+    { tool: 'cargo-check', pattern: /^cargo\s+check\b/, category: 'typecheck' },
+    { tool: 'cargo-clippy', pattern: /^cargo\s+clippy\b/, category: 'lint' },
+    { tool: 'cargo-build', pattern: /^cargo\s+build\b/, category: 'build' },
+    // ----- Go -----
+    { tool: 'go-test', pattern: /^go\s+test\b/, category: 'test' },
+    { tool: 'go-vet', pattern: /^go\s+vet\b/, category: 'lint' },
+    { tool: 'go-build', pattern: /^go\s+build\b/, category: 'build' },
+    // ----- Elixir -----
+    { tool: 'mix-test', pattern: /^mix\s+test\b/, category: 'test' },
+    // ----- Ruby -----
+    { tool: 'rspec', pattern: /^(?:bundle\s+exec\s+)?rspec\b/, category: 'test' },
+    { tool: 'rubocop', pattern: /^(?:bundle\s+exec\s+)?rubocop\b/, category: 'lint' },
+    // ----- Java / Kotlin / Gradle / Maven -----
+    { tool: 'gradle-test', pattern: /^(?:\.\/)?gradlew?\s+test\b/, category: 'test' },
+    { tool: 'gradle-build', pattern: /^(?:\.\/)?gradlew?\s+build\b/, category: 'build' },
+    { tool: 'maven-test', pattern: /^mvn\s+test\b/, category: 'test' },
+    { tool: 'maven-verify', pattern: /^mvn\s+verify\b/, category: 'test' },
+    // ----- C/C++ / Make -----
+    { tool: 'make-test', pattern: /^make\s+(?:test|check)\b/, category: 'test' },
+    { tool: 'ctest', pattern: /^ctest\b/, category: 'test' },
+];
+const SHELL_SEPARATORS = /\s*(?:&&|\|\||;|\|)\s*/;
+const ENV_ASSIGN = /^[A-Z_][A-Z0-9_]*=\S+$/;
+/**
+ * Strip leading `sudo` / `time` / `env A=1 B=2` noise so the verb is
+ * the first non-prefix token. Returns the stripped head as a single
+ * normalised string. Pure — no side effects.
+ *
+ * We do NOT strip generic env-variable assignments like `CI=1` that
+ * the operator typed inline (e.g. `CI=1 pnpm test`) because the
+ * regex allowlist anchors `pnpm` — matching the head after stripping
+ * `CI=1` is precisely the intent.
+ */
+export function extractCommandHead(component) {
+    let head = component.trim();
+    // sudo / time wrappers
+    while (true) {
+        if (head.startsWith('sudo ')) {
+            head = head.slice(5).trimStart();
+            continue;
+        }
+        if (head.startsWith('time ')) {
+            head = head.slice(5).trimStart();
+            continue;
+        }
+        // env A=1 B=2 prefix (inline env assignments before the verb).
+        // Peel one token at a time so `FOO=bar BAZ=qux pnpm test` resolves to `pnpm test`.
+        const firstToken = head.split(/\s+/, 1)[0] ?? '';
+        if (firstToken !== '' && ENV_ASSIGN.test(firstToken)) {
+            head = head.slice(firstToken.length).trimStart();
+            continue;
+        }
+        break;
+    }
+    return head;
+}
+/**
+ * Detect whether a shell command runs a verification step. The
+ * predicate scans every `&&` / `;` / `||` / `|`-separated component
+ * and returns the first match — a compound command like
+ * `cd packages/foo && pnpm test` is correctly flagged on the
+ * trailing component.
+ *
+ * The check is intentionally optimistic: it does not parse `if`,
+ * `for`, or function bodies. Operators wrapping verification inside
+ * a script (e.g. `./scripts/test.sh`) opt out of the gate; that is
+ * recorded in the unverifiedReason as `no_verification_command_run`
+ * downstream.
+ */
+export function detectVerificationCommand(cmd) {
+    if (typeof cmd !== 'string' || cmd.trim() === '') {
+        return { isVerification: false, tool: null, matchedComponent: '' };
+    }
+    const components = cmd.split(SHELL_SEPARATORS);
+    for (const raw of components) {
+        const head = extractCommandHead(raw);
+        if (head === '')
+            continue;
+        for (const entry of VERIFICATION_PATTERNS) {
+            if (entry.pattern.test(head)) {
+                return {
+                    isVerification: true,
+                    tool: entry.tool,
+                    matchedComponent: raw.trim(),
+                };
+            }
+        }
+    }
+    return { isVerification: false, tool: null, matchedComponent: '' };
+}
+/**
+ * Phrases the agent uses to dispute ownership of a verification
+ * failure. When ANY of these phrases appears in the final assistant
+ * text AND the agent mutated files in the same module as a failing
+ * test, the outcome's `regressionOwnershipDispute` flag is set so a
+ * downstream reviewer can decide whether to escalate.
+ *
+ * The list is case-insensitive at match time. Punctuation around the
+ * phrase is allowed because `.includes()` looks for the substring,
+ * not word boundaries (an agent that writes "this is a pre-existing
+ * test bug" still trips the flag).
+ */
+export const REGRESSION_DISPUTE_PHRASES = [
+    'pre-existing',
+    'preexisting',
+    'pre existing',
+    'not from my changes',
+    'not related to my changes',
+    'unrelated test failure',
+    'unrelated to my changes',
+    'unrelated failure',
+    'not my change',
+];
+/**
+ * Tail trimmer for stderr captured in verification ledger entries.
+ * Returns the last `maxBytes` of UTF-8 text, clamped at a hard 2 KB
+ * default to match the PUGI-VERIFY-GATE contract.
+ */
+export function tailStderr(stderr, maxBytes = 2048) {
+    if (typeof stderr !== 'string' || stderr.length === 0)
+        return '';
+    if (Buffer.byteLength(stderr, 'utf8') <= maxBytes)
+        return stderr;
+    // Approximate cap by character index — accurate enough for stderr
+    // tails that are overwhelmingly ASCII test output.
+    const slice = stderr.slice(-maxBytes);
+    return slice;
+}
+//# sourceMappingURL=verification-patterns.js.map

package/dist/core/evaluation/golden-dataset.js

@@ -0,0 +1,293 @@
+/**
+ * Golden dataset primitive — pugi-eval-v1 foundation (task).
+ *
+ * Formalizes a frozen set of representative CLI tasks that we replay
+ * against the agent loop to detect quality regressions. This module is
+ * the pure data layer:
+ *
+ *  1. `GoldenTask` — typed contract for one evaluation case (id, query,
+ *     expected file touches, expected output substrings, exit-code
+ *     gate, soft budgets, tags).
+ *  2. `loadGoldenDataset(path)` — reads a JSON file from disk, asserts
+ *     it is a non-empty array, and runs `validateGoldenTask` on every
+ *     element. Throws on the first malformed entry so the eval harness
+ *     cannot silently drop a task.
+ *  3. `validateGoldenTask(raw)` — schema validator. Enforces kebab-case
+ *     ids, non-empty query, optional arrays whose elements are
+ *     well-formed, and rejects parent-traversal `..` segments inside
+ *     `expectedFiles`. Throws `TypeError` with a specific field message.
+ *  4. `diffAgainstBaseline(current, baseline)` — turns two `TaskResult`
+ *     maps into a `DriftReport` that lists regressed / improved / new /
+ *     removed tasks. A regression is a task that PASSED in baseline and
+ *     FAILED in current; an improvement is the inverse. The report is
+ *     what the future CI gate consumes — a positive `regressed.length`
+ *     blocks the merge.
+ *
+ * Out of scope here: actually running tasks against the engine. The
+ * follow-up `runOfflineEval()` consumer reads a dataset via
+ * `loadGoldenDataset`, executes each task through `pugi code/explain/
+ * plan/fix/build`, collects pass/fail/latency/tokens into a
+ * `TaskResult[]`, and feeds the previous run's results into
+ * `diffAgainstBaseline` for the drift gate.
+ *
+ * Pure functions only. No file I/O beyond `fs/promises.readFile` inside
+ * `loadGoldenDataset` so the module composes cleanly with in-memory test
+ * fixtures and engine-side consumers that already hold dataset bytes.
+ */
+import { readFile } from 'node:fs/promises';
+const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Validate one raw value as a `GoldenTask`. Throws `TypeError` with a
+ * field-specific message on any violation. Returns the typed task on
+ * success.
+ *
+ * The validator is intentionally hand-rolled — the shape is small, and
+ * adding zod here would obscure the per-field error contract that the
+ * eval harness logs at load time.
+ */
+export function validateGoldenTask(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new TypeError('golden task must be a JSON object');
+    }
+    const r = raw;
+    // id — required, kebab-case.
+    if (typeof r.id !== 'string' || r.id.length === 0) {
+        throw new TypeError('golden task: `id` required (non-empty string)');
+    }
+    if (!ID_PATTERN.test(r.id)) {
+        throw new TypeError(`golden task ${JSON.stringify(r.id)}: \`id\` must match ${ID_PATTERN.source} (kebab-case, leading letter)`);
+    }
+    const id = r.id;
+    // query — required.
+    if (typeof r.query !== 'string' || r.query.length === 0) {
+        throw new TypeError(`golden task ${id}: \`query\` required (non-empty string)`);
+    }
+    const query = r.query;
+    // expectedFiles — optional, when present must be non-empty array of
+    // relative paths without traversal.
+    let expectedFiles;
+    if (r.expectedFiles !== undefined) {
+        if (!Array.isArray(r.expectedFiles)) {
+            throw new TypeError(`golden task ${id}: \`expectedFiles\` must be an array`);
+        }
+        if (r.expectedFiles.length === 0) {
+            throw new TypeError(`golden task ${id}: \`expectedFiles\` must be non-empty (omit field instead of passing [])`);
+        }
+        expectedFiles = r.expectedFiles.map((entry, idx) => {
+            if (typeof entry !== 'string' || entry.length === 0) {
+                throw new TypeError(`golden task ${id}: \`expectedFiles[${idx}]\` must be a non-empty string`);
+            }
+            if (entry.startsWith('/')) {
+                throw new TypeError(`golden task ${id}: \`expectedFiles[${idx}]\` must be relative (no leading /)`);
+            }
+            const segments = entry.split('/');
+            if (segments.some((s) => s === '..')) {
+                throw new TypeError(`golden task ${id}: \`expectedFiles[${idx}]\` contains \`..\` traversal`);
+            }
+            return entry;
+        });
+    }
+    // expectedSubstrings — optional array of non-empty strings.
+    let expectedSubstrings;
+    if (r.expectedSubstrings !== undefined) {
+        if (!Array.isArray(r.expectedSubstrings)) {
+            throw new TypeError(`golden task ${id}: \`expectedSubstrings\` must be an array`);
+        }
+        if (r.expectedSubstrings.length === 0) {
+            throw new TypeError(`golden task ${id}: \`expectedSubstrings\` must be non-empty (omit field instead of passing [])`);
+        }
+        expectedSubstrings = r.expectedSubstrings.map((entry, idx) => {
+            if (typeof entry !== 'string' || entry.length === 0) {
+                throw new TypeError(`golden task ${id}: \`expectedSubstrings[${idx}]\` must be a non-empty string`);
+            }
+            return entry;
+        });
+    }
+    // expectedExitCode — optional integer.
+    let expectedExitCode;
+    if (r.expectedExitCode !== undefined) {
+        if (typeof r.expectedExitCode !== 'number' ||
+            !Number.isInteger(r.expectedExitCode)) {
+            throw new TypeError(`golden task ${id}: \`expectedExitCode\` must be an integer`);
+        }
+        expectedExitCode = r.expectedExitCode;
+    }
+    // maxTokens — optional positive integer.
+    let maxTokens;
+    if (r.maxTokens !== undefined) {
+        if (typeof r.maxTokens !== 'number' ||
+            !Number.isInteger(r.maxTokens) ||
+            r.maxTokens <= 0) {
+            throw new TypeError(`golden task ${id}: \`maxTokens\` must be a positive integer`);
+        }
+        maxTokens = r.maxTokens;
+    }
+    // maxLatencyMs — optional positive integer.
+    let maxLatencyMs;
+    if (r.maxLatencyMs !== undefined) {
+        if (typeof r.maxLatencyMs !== 'number' ||
+            !Number.isInteger(r.maxLatencyMs) ||
+            r.maxLatencyMs <= 0) {
+            throw new TypeError(`golden task ${id}: \`maxLatencyMs\` must be a positive integer`);
+        }
+        maxLatencyMs = r.maxLatencyMs;
+    }
+    // tags — optional array of non-empty strings.
+    let tags;
+    if (r.tags !== undefined) {
+        if (!Array.isArray(r.tags)) {
+            throw new TypeError(`golden task ${id}: \`tags\` must be an array`);
+        }
+        tags = r.tags.map((entry, idx) => {
+            if (typeof entry !== 'string' || entry.length === 0) {
+                throw new TypeError(`golden task ${id}: \`tags[${idx}]\` must be a non-empty string`);
+            }
+            return entry;
+        });
+    }
+    const task = { id, query };
+    if (expectedFiles !== undefined)
+        task.expectedFiles = expectedFiles;
+    if (expectedSubstrings !== undefined)
+        task.expectedSubstrings = expectedSubstrings;
+    if (expectedExitCode !== undefined)
+        task.expectedExitCode = expectedExitCode;
+    if (maxTokens !== undefined)
+        task.maxTokens = maxTokens;
+    if (maxLatencyMs !== undefined)
+        task.maxLatencyMs = maxLatencyMs;
+    if (tags !== undefined)
+        task.tags = tags;
+    return task;
+}
+/**
+ * Load and validate a golden dataset JSON file. The file must parse as
+ * a JSON array of objects, each one a valid `GoldenTask`. Duplicate
+ * ids are rejected — drift comparisons key by id and a duplicate would
+ * silently mask one row.
+ */
+export async function loadGoldenDataset(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new TypeError(`golden dataset: cannot read ${filePath}: ${message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new TypeError(`golden dataset ${filePath}: invalid JSON (${message})`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new TypeError(`golden dataset ${filePath}: top-level value must be a JSON array`);
+    }
+    const tasks = [];
+    const seen = new Set();
+    for (let i = 0; i < parsed.length; i += 1) {
+        let task;
+        try {
+            task = validateGoldenTask(parsed[i]);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new TypeError(`golden dataset ${filePath}: entry [${i}]: ${message}`);
+        }
+        if (seen.has(task.id)) {
+            throw new TypeError(`golden dataset ${filePath}: duplicate task id ${JSON.stringify(task.id)} at entry [${i}]`);
+        }
+        seen.add(task.id);
+        tasks.push(task);
+    }
+    return tasks;
+}
+/**
+ * Compare a current run against a baseline run and return a drift
+ * report. Pure function — no I/O, no clock, deterministic ordering
+ * (regressed/improved sorted by id).
+ *
+ * Either input may be empty. An empty baseline produces an
+ * all-newTasks report without crashing — useful for the very first
+ * eval run when no previous artifact exists yet.
+ */
+export function diffAgainstBaseline(currentResults, baselineResults, options) {
+    const includeReason = options?.includeReason ?? true;
+    const currentById = new Map();
+    for (const r of currentResults) {
+        if (typeof r.id !== 'string' || r.id.length === 0)
+            continue;
+        currentById.set(r.id, r);
+    }
+    const baselineById = new Map();
+    for (const r of baselineResults) {
+        if (typeof r.id !== 'string' || r.id.length === 0)
+            continue;
+        baselineById.set(r.id, r);
+    }
+    const regressed = [];
+    const improved = [];
+    const newTasks = [];
+    const removedTasks = [];
+    for (const [id, currentRow] of currentById) {
+        const baselineRow = baselineById.get(id);
+        if (!baselineRow) {
+            newTasks.push(id);
+            continue;
+        }
+        if (baselineRow.passed && !currentRow.passed) {
+            const diff = {
+                id,
+                baselinePassed: true,
+                currentPassed: false,
+            };
+            if (includeReason && currentRow.reason !== undefined) {
+                diff.reason = currentRow.reason;
+            }
+            regressed.push(diff);
+        }
+        else if (!baselineRow.passed && currentRow.passed) {
+            const diff = {
+                id,
+                baselinePassed: false,
+                currentPassed: true,
+            };
+            if (includeReason && currentRow.reason !== undefined) {
+                diff.reason = currentRow.reason;
+            }
+            improved.push(diff);
+        }
+    }
+    for (const id of baselineById.keys()) {
+        if (!currentById.has(id)) {
+            removedTasks.push(id);
+        }
+    }
+    regressed.sort((a, b) => a.id.localeCompare(b.id));
+    improved.sort((a, b) => a.id.localeCompare(b.id));
+    newTasks.sort();
+    removedTasks.sort();
+    let passedNow = 0;
+    for (const r of currentById.values()) {
+        if (r.passed)
+            passedNow += 1;
+    }
+    let passedBaseline = 0;
+    for (const r of baselineById.values()) {
+        if (r.passed)
+            passedBaseline += 1;
+    }
+    return {
+        totalTasks: currentById.size,
+        passedNow,
+        passedBaseline,
+        regressed,
+        improved,
+        newTasks,
+        removedTasks,
+    };
+}
+//# sourceMappingURL=golden-dataset.js.map

package/dist/core/feedback/queue.js

@@ -0,0 +1,177 @@
+/**
+ * Local feedback queue — .
+ *
+ * `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