review-workspace 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salih Sayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# Review Workspace
+
+A local, offline decision surface for reviewing a code Comparison. See
+`docs/framework.md` for product rules, `CONTEXT.md` for the domain glossary,
+and `docs/spec.md` for the v1 spec.
+
+## Reviewing an MR/PR
+
+This repo (the engine: schema, validator, CLI, server, UI) never fetches a Comparison or writes a Review Document itself — that's the Generator's job, a separate Claude Code skill (see `skills/review-workspace/`). Paste an MR/PR URL to Claude Code with that skill available and ask it to review it — the skill scaffolds a bundle under `.bundles/`, generates + publishes the Review Document, then `serve`s it (see below).
+
+To view an already-scaffolded bundle:
+
+```sh
+npx review-workspace serve .bundles/<name> --port 4317
+```
+
+Opens the UI at `http://127.0.0.1:4317` (prints a write token too — needed only to raise/answer Questions, not to view). One process, no separate dev server.
+
+## Development
+
+```sh
+pnpm install
+pnpm test         # vitest
+pnpm typecheck    # tsc --noEmit, doubling as lint (ponytail: no separate linter yet)
+pnpm build:ui     # builds ui/ and copies it to ui-dist/ so `serve` hosts the UI itself
+```
+
+While developing the UI itself, run the two pieces separately instead — `node src/cli.ts serve .bundles/<name> --port 4317` for the API, and `cd ui && pnpm dev` for the UI with hot reload (its Vite dev server proxies `/api/*` to the port above).
+
+Add fixtures under `fixtures/` — see `fixtures/README.md`. Never commit a real
+Review Bundle (per ADR 0004); fixtures are synthetic only.
+
+## Releasing
+
+Versioning and npm publishing are fully automated by
+[semantic-release](https://semantic-release.org/) (`.releaserc.json`,
+`.github/workflows/release.yml`) — every push to `main` computes the next
+version from commit messages, publishes to npm, tags the release, and
+updates `CHANGELOG.md`. There is no manual version bump.
+
+This only works if commits follow [Conventional
+Commits](https://www.conventionalcommits.org/): a `type` prefix tells
+semantic-release what kind of release (if any) the commit deserves. A commit
+that doesn't match a recognized type is ignored for versioning — safe, but it
+means that change won't ship until a later commit does trigger a release.
+
+```
+fix: correct hunk line-target off-by-one          # patch release
+feat: add file-level diff collapse                # minor release
+feat!: rename Target `kind` to `type`              # major release (breaking)
+
+BREAKING CHANGE: `target.kind` renamed to `target.type` in the Review Document schema.
+```
+
+Other common types (`docs:`, `chore:`, `refactor:`, `test:`) don't trigger a
+release on their own.

package/dist/bundle/diagnostics.js

@@ -0,0 +1 @@
+export {};

package/dist/bundle/publish.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateBundle } from "./validate-bundle.js";
+import { DEFAULT_LIMITS } from "../security/limits.js";
+/**
+ * Validates a staged `review.next.json` and, only on success, atomically
+ * replaces `review.json` with it. On any failure `review.json` is left
+ * byte-for-byte untouched.
+ */
+export function publishBundle(bundlePath, limits = DEFAULT_LIMITS) {
+    const nextPath = join(bundlePath, 'review.next.json');
+    if (!existsSync(nextPath)) {
+        return { ok: false, blockingReason: 'missing-next', message: 'review.next.json not found' };
+    }
+    const result = validateBundle(bundlePath, limits, 'review.next.json');
+    if (!result.valid) {
+        return { ok: false, blockingReason: result.blockingReason, message: result.message };
+    }
+    const reviewPath = join(bundlePath, 'review.json');
+    const tmpPath = join(bundlePath, `.review.json.tmp-${process.pid}-${Date.now()}`);
+    writeFileSync(tmpPath, readFileSync(nextPath, 'utf-8'));
+    renameSync(tmpPath, reviewPath);
+    return { ok: true };
+}

package/dist/bundle/resolve-diagnostics.js

@@ -0,0 +1,113 @@
+import { existsSync, statSync } from 'node:fs';
+import { validateReviewDocumentSchema } from "../schema/validate.js";
+import { resolveAssetPath } from "../security/asset-path.js";
+import { DEFAULT_LIMITS } from "../security/limits.js";
+import { readQuestions } from "../questions/questions-log.js";
+function findFile(patch, path) {
+    return patch.files.find((f) => f.path === path);
+}
+function checkAssetPath(bundlePath, assetPath, limits) {
+    const resolution = resolveAssetPath(bundlePath, assetPath);
+    if (!resolution.ok) {
+        return resolution.reason === 'unsafe-path'
+            ? { kind: 'unsafe-asset-path', assetPath }
+            : { kind: 'disallowed-asset-type', assetPath };
+    }
+    if (!existsSync(resolution.absolutePath)) {
+        return { kind: 'missing-asset', assetPath };
+    }
+    const { size } = statSync(resolution.absolutePath);
+    if (size > limits.maxAssetBytes) {
+        return { kind: 'asset-too-large', assetPath, bytes: size };
+    }
+    return undefined;
+}
+function resolveTarget(target, patch) {
+    const file = findFile(patch, target.path);
+    if (target.type === 'file') {
+        if (!file)
+            return { kind: 'unresolved-target', targetType: 'file', path: target.path, detail: 'file not found in patch' };
+        return undefined;
+    }
+    if (target.type === 'binary') {
+        if (!file || !file.binary) {
+            return { kind: 'unresolved-target', targetType: 'binary', path: target.path, detail: 'no binary change found for file' };
+        }
+        return undefined;
+    }
+    if (target.type === 'hunk') {
+        if (!file || !file.hunks[target.hunkIndex]) {
+            return { kind: 'unresolved-target', targetType: 'hunk', path: target.path, detail: `hunk index ${target.hunkIndex} not found` };
+        }
+        return undefined;
+    }
+    // target.type === 'line'
+    const line = file?.hunks
+        .flatMap((h) => h.lines)
+        .find((l) => (target.side === 'base' ? l.oldLine === target.line : l.newLine === target.line));
+    if (!line) {
+        return {
+            kind: 'stale-line-target',
+            path: target.path,
+            side: target.side,
+            line: target.line,
+            expectedText: target.expectedText,
+            detail: 'no line found at that position',
+        };
+    }
+    if (line.text !== target.expectedText) {
+        return {
+            kind: 'stale-line-target',
+            path: target.path,
+            side: target.side,
+            line: target.line,
+            expectedText: target.expectedText,
+            detail: `expected ${JSON.stringify(target.expectedText)}, found ${JSON.stringify(line.text)}`,
+        };
+    }
+    return undefined;
+}
+export function collectDiagnostics(document, patch, bundlePath, limits = DEFAULT_LIMITS) {
+    const diagnostics = [];
+    const schemaResult = validateReviewDocumentSchema(document);
+    if (!schemaResult.valid) {
+        for (const err of schemaResult.errors ?? []) {
+            diagnostics.push({ kind: 'invalid-field', instancePath: err.instancePath, message: err.message ?? 'invalid field' });
+        }
+    }
+    for (const group of document.behavioralGroups ?? []) {
+        for (const target of group.targets ?? []) {
+            const diagnostic = resolveTarget(target, patch);
+            if (diagnostic)
+                diagnostics.push(diagnostic);
+        }
+    }
+    for (const annotation of document.annotations ?? []) {
+        const diagnostic = resolveTarget(annotation.target, patch);
+        if (diagnostic)
+            diagnostics.push(diagnostic);
+        for (const related of annotation.relatedTargets ?? []) {
+            const relatedDiagnostic = resolveTarget(related.target, patch);
+            if (relatedDiagnostic)
+                diagnostics.push(relatedDiagnostic);
+        }
+    }
+    for (const evidence of document.evidence ?? []) {
+        for (const assetPath of [evidence.assetPath, evidence.baseAssetPath]) {
+            if (!assetPath)
+                continue;
+            const diagnostic = checkAssetPath(bundlePath, assetPath, limits);
+            if (diagnostic)
+                diagnostics.push(diagnostic);
+        }
+    }
+    if (document.answers?.length) {
+        const questionIds = new Set(readQuestions(bundlePath).map((q) => q.id));
+        for (const answer of document.answers) {
+            if (!questionIds.has(answer.questionId)) {
+                diagnostics.push({ kind: 'dangling-answer', answerId: answer.id, questionId: answer.questionId });
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/bundle/validate-bundle.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parsePatch } from "../patch/parse.js";
+import { PatchParseError } from "../patch/types.js";
+import { collectDiagnostics } from "./resolve-diagnostics.js";
+import { DEFAULT_LIMITS } from "../security/limits.js";
+export const SUPPORTED_SCHEMA_VERSIONS = [1];
+function hasComparisonIdentity(document) {
+    if (typeof document !== 'object' || document === null)
+        return false;
+    const comparison = document.comparison;
+    if (typeof comparison !== 'object' || comparison === null)
+        return false;
+    const { base, head } = comparison;
+    return typeof base === 'string' && base.length > 0 && typeof head === 'string' && head.length > 0;
+}
+export function validateBundle(bundlePath, limits = DEFAULT_LIMITS, documentFileName = 'review.json') {
+    let raw;
+    try {
+        raw = readFileSync(join(bundlePath, documentFileName), 'utf-8');
+    }
+    catch (err) {
+        return { valid: false, blockingReason: 'unparseable-json', message: err.message };
+    }
+    if (Buffer.byteLength(raw, 'utf-8') > limits.maxDocumentBytes) {
+        return {
+            valid: false,
+            blockingReason: 'document-too-large',
+            message: `${documentFileName} exceeds ${limits.maxDocumentBytes} bytes`,
+        };
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch (err) {
+        return { valid: false, blockingReason: 'unparseable-json', message: err.message };
+    }
+    const schemaVersion = document?.schemaVersion;
+    if (typeof schemaVersion !== 'number' || !SUPPORTED_SCHEMA_VERSIONS.includes(schemaVersion)) {
+        return {
+            valid: false,
+            blockingReason: 'unsupported-schema-version',
+            message: `schemaVersion ${String(schemaVersion)} is not supported (supported: ${SUPPORTED_SCHEMA_VERSIONS.join(', ')})`,
+        };
+    }
+    if (!hasComparisonIdentity(document)) {
+        return { valid: false, blockingReason: 'missing-comparison-identity', message: 'comparison.base/head are required' };
+    }
+    let rawPatch;
+    try {
+        rawPatch = readFileSync(join(bundlePath, 'changes.diff'), 'utf-8');
+    }
+    catch (err) {
+        return { valid: false, blockingReason: 'unusable-patch', message: err.message };
+    }
+    if (Buffer.byteLength(rawPatch, 'utf-8') > limits.maxPatchBytes) {
+        return { valid: false, blockingReason: 'patch-too-large', message: `changes.diff exceeds ${limits.maxPatchBytes} bytes` };
+    }
+    let patch;
+    try {
+        patch = parsePatch(rawPatch);
+    }
+    catch (err) {
+        const message = err instanceof PatchParseError || err instanceof Error ? err.message : String(err);
+        return { valid: false, blockingReason: 'unusable-patch', message };
+    }
+    const totalLines = patch.files.reduce((sum, f) => sum + f.hunks.reduce((s, h) => s + h.lines.length, 0), 0);
+    if (totalLines > limits.maxPatchLines) {
+        return {
+            valid: false,
+            blockingReason: 'too-many-patch-lines',
+            message: `patch has ${totalLines} lines, exceeding the limit of ${limits.maxPatchLines}`,
+        };
+    }
+    const diagnostics = collectDiagnostics(document, patch, bundlePath, limits);
+    return { valid: true, document, patch, diagnostics };
+}

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { validateBundle } from "./bundle/validate-bundle.js";
+import { publishBundle } from "./bundle/publish.js";
+import { startReviewServer } from "./server/create-server.js";
+const [, , command, bundlePath, ...rest] = process.argv;
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+function flagValue(name) {
+    const index = rest.indexOf(name);
+    return index === -1 ? undefined : rest[index + 1];
+}
+if (!command || !bundlePath) {
+    fail('Usage: review-workspace <open|publish|serve> <bundlePath> [--port N]');
+}
+if (command === 'open') {
+    const result = validateBundle(bundlePath);
+    if (!result.valid) {
+        fail(`Cannot open bundle: ${result.blockingReason} — ${result.message}`);
+    }
+    console.log('Bundle is valid.');
+    if (result.diagnostics?.length) {
+        console.log(`${result.diagnostics.length} diagnostic(s) found.`);
+    }
+}
+else if (command === 'publish') {
+    const result = publishBundle(bundlePath);
+    if (!result.ok) {
+        fail(`Publish rejected: ${result.blockingReason} — ${result.message}`);
+    }
+    console.log('Published.');
+}
+else if (command === 'serve') {
+    const port = Number(flagValue('--port') ?? 4317);
+    const handle = await startReviewServer(bundlePath, { port });
+    console.log(JSON.stringify({ port: handle.port, writeToken: handle.writeToken, url: `http://127.0.0.1:${handle.port}` }));
+}
+else {
+    fail(`Unknown command: ${command}`);
+}

package/dist/export/report.js

@@ -0,0 +1,63 @@
+function formatTarget(target) {
+    switch (target.type) {
+        case 'file':
+            return target.path;
+        case 'hunk':
+            return `${target.path}#hunk${target.hunkIndex}`;
+        case 'binary':
+            return `${target.path} (binary)`;
+        case 'line':
+            return `${target.path}:${target.line} (${target.side})`;
+    }
+}
+export function buildConcernComment(concern) {
+    const prefix = concern.target ? `[${formatTarget(concern.target)}] ` : '';
+    return `${prefix}${concern.note}`;
+}
+/** One comment per Concern, plain text — pasteable individually into an external tool. */
+export function buildConcernComments(state) {
+    return state.concerns.map(buildConcernComment);
+}
+/**
+ * A self-contained Markdown report — no server needed to view it afterward.
+ * Read-only with respect to the bundle: never mutates state.json or questions.jsonl.
+ */
+export function buildReport(document, state) {
+    const lines = [];
+    lines.push('# Review Report');
+    lines.push('');
+    lines.push(`**Comparison:** ${document.comparison.base} → ${document.comparison.head}`);
+    lines.push(`**Decision:** ${state.decision}`);
+    lines.push('');
+    lines.push('## Behavioral Groups');
+    const groups = document.behavioralGroups ?? [];
+    if (groups.length === 0) {
+        lines.push('_None declared._');
+    }
+    else {
+        for (const group of [...groups].sort((a, b) => a.order - b.order)) {
+            const progress = state.groups[group.id];
+            lines.push(`- **${group.title}** — understood: ${progress?.understood ? 'yes' : 'no'}, verified: ${progress?.verified ? 'yes' : 'no'}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Concerns');
+    if (state.concerns.length === 0) {
+        lines.push('_None raised._');
+    }
+    else {
+        for (const comment of buildConcernComments(state)) {
+            lines.push(`- ${comment}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Notes');
+    if (state.notes.length === 0) {
+        lines.push('_None._');
+    }
+    else {
+        for (const note of state.notes)
+            lines.push(`- ${note}`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/patch/parse.js

@@ -0,0 +1,168 @@
+import { PatchParseError } from "./types.js";
+const GIT_FILE_HEADER = /^diff --git a\/(.+) b\/(.+)$/;
+const OLD_FILE_MARKER = /^--- (.+)$/;
+const NEW_FILE_MARKER = /^\+\+\+ (.+)$/;
+const BINARY_MARKER = /^Binary files (?:a\/)?(.+) and (?:b\/)?(.+) differ$/;
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+function stripPrefix(path) {
+    if (path === '/dev/null')
+        return path;
+    if (path.startsWith('a/') || path.startsWith('b/'))
+        return path.slice(2);
+    return path;
+}
+/**
+ * Parses both git's extended unified diff format ("diff --git a/X b/Y" plus
+ * "--- "/"+++ " headers) and a bare POSIX unified diff (just "--- "/"+++ ",
+ * no "diff --git" line, no a/ b/ path prefixes) — real Generators and forge
+ * tooling (e.g. `glab mr diff`) emit either shape.
+ */
+export function parsePatch(text) {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+    const files = [];
+    let currentFile = null;
+    let currentHunk = null;
+    let pendingGitPaths = null;
+    let pendingOldPath = null;
+    const closeHunk = () => {
+        if (!currentHunk)
+            return;
+        const expected = currentHunk.oldLines + currentHunk.newLines;
+        const seenOld = currentHunk.lines.filter((l) => l.kind !== 'add').length;
+        const seenNew = currentHunk.lines.filter((l) => l.kind !== 'remove').length;
+        if (seenOld !== currentHunk.oldLines || seenNew !== currentHunk.newLines) {
+            throw new PatchParseError(`Truncated hunk in ${currentFile?.path ?? 'unknown file'}: expected ${expected} old/new lines, saw ${seenOld}/${seenNew}`);
+        }
+        currentHunk = null;
+    };
+    for (const line of lines) {
+        const gitFileMatch = GIT_FILE_HEADER.exec(line);
+        if (gitFileMatch) {
+            closeHunk();
+            pendingGitPaths = { old: gitFileMatch[1], new: gitFileMatch[2] };
+            continue;
+        }
+        const binaryMatch = BINARY_MARKER.exec(line);
+        if (binaryMatch) {
+            closeHunk();
+            // A bare unified diff (no "diff --git") can still emit "--- "/"+++ " for a binary
+            // file before the "Binary files ... differ" line — that already created a
+            // (non-binary, hunk-less) file entry above, which this just converts in place
+            // rather than pushing a duplicate. Trust that already-open entry's path over the
+            // Binary marker's own paths: for a bare-format deletion the marker line reads
+            // "Binary files a/X and /dev/null differ", so deriving identity from its second
+            // capture group would wrongly produce "/dev/null" instead of the real path X.
+            if (!pendingGitPaths && currentFile !== null && currentFile.hunks.length === 0 && !currentFile.binary) {
+                currentFile.binary = true;
+            }
+            else {
+                const path = pendingGitPaths?.new ?? stripPrefix(binaryMatch[2]);
+                currentFile = {
+                    path,
+                    oldPath: pendingGitPaths?.old ?? stripPrefix(binaryMatch[1]),
+                    binary: true,
+                    hunks: [],
+                };
+                files.push(currentFile);
+            }
+            pendingGitPaths = null;
+            continue;
+        }
+        if (line.startsWith('index '))
+            continue;
+        // A real file header only ever appears between hunks, never inside one — so once a
+        // hunk is open and still expects more lines, a "--- "/"+++ "-prefixed line is content
+        // (e.g. a removed line whose text itself starts with "-- "), not a new file boundary.
+        if (!currentHunk) {
+            const oldMatch = OLD_FILE_MARKER.exec(line);
+            if (oldMatch) {
+                pendingOldPath = stripPrefix(oldMatch[1]);
+                continue;
+            }
+            const newMatch = NEW_FILE_MARKER.exec(line);
+            if (newMatch) {
+                closeHunk();
+                const newPath = stripPrefix(newMatch[1]);
+                currentFile = {
+                    path: pendingGitPaths?.new ?? newPath,
+                    oldPath: pendingGitPaths?.old ?? pendingOldPath ?? newPath,
+                    binary: false,
+                    hunks: [],
+                };
+                files.push(currentFile);
+                pendingGitPaths = null;
+                pendingOldPath = null;
+                continue;
+            }
+        }
+        if (!currentFile) {
+            if (line.trim() === '')
+                continue;
+            throw new PatchParseError(`Content encountered before any file header: ${JSON.stringify(line)}`);
+        }
+        const hunkMatch = HUNK_HEADER.exec(line);
+        if (hunkMatch) {
+            closeHunk();
+            currentHunk = {
+                oldStart: Number(hunkMatch[1]),
+                oldLines: hunkMatch[2] !== undefined ? Number(hunkMatch[2]) : 1,
+                newStart: Number(hunkMatch[3]),
+                newLines: hunkMatch[4] !== undefined ? Number(hunkMatch[4]) : 1,
+                lines: [],
+            };
+            currentFile.hunks.push(currentHunk);
+            continue;
+        }
+        if (currentHunk) {
+            const marker = line[0];
+            const text = line.slice(1);
+            let oldLine;
+            let newLine;
+            const priorOld = currentHunk.lines.filter((l) => l.kind !== 'add').length;
+            const priorNew = currentHunk.lines.filter((l) => l.kind !== 'remove').length;
+            if (marker === '+') {
+                newLine = currentHunk.newStart + priorNew;
+                currentHunk.lines.push({ kind: 'add', text, newLine });
+            }
+            else if (marker === '-') {
+                oldLine = currentHunk.oldStart + priorOld;
+                currentHunk.lines.push({ kind: 'remove', text, oldLine });
+            }
+            else if (marker === ' ' || line === '') {
+                oldLine = currentHunk.oldStart + priorOld;
+                newLine = currentHunk.newStart + priorNew;
+                currentHunk.lines.push({ kind: 'context', text: line === '' ? '' : text, oldLine, newLine });
+            }
+            else if (line === '\') {
+                continue;
+            }
+            else {
+                throw new PatchParseError(`Unrecognized hunk line prefix in ${currentFile.path}: ${JSON.stringify(line)}`);
+            }
+            // Self-close the moment declared counts are satisfied, rather than waiting for the
+            // next header line to trigger it — otherwise an immediately-following bare "--- "/
+            // "+++ " file header (no git "diff --git" line ahead of it) is mistaken for hunk
+            // content, since the ambiguity guard above only reopens header-detection once no
+            // hunk is open.
+            const seenOld = currentHunk.lines.filter((l) => l.kind !== 'add').length;
+            const seenNew = currentHunk.lines.filter((l) => l.kind !== 'remove').length;
+            if (seenOld === currentHunk.oldLines && seenNew === currentHunk.newLines) {
+                currentHunk = null;
+            }
+            continue;
+        }
+        // A hunk self-closes as soon as its declared line count is satisfied (see above), but a
+        // trailing "no newline" marker for the hunk's last line arrives as the very next line —
+        // after the self-close, so it must still be recognized here, not just while a hunk is open.
+        if (line === '\')
+            continue;
+        if (line.trim() !== '') {
+            throw new PatchParseError(`Unexpected content outside a hunk in ${currentFile.path}: ${JSON.stringify(line)}`);
+        }
+    }
+    closeHunk();
+    return { files };
+}

package/dist/patch/types.js

@@ -0,0 +1,2 @@
+export class PatchParseError extends Error {
+}

package/dist/questions/questions-log.js

@@ -0,0 +1,80 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+function logPath(bundlePath) {
+    return join(bundlePath, 'questions.jsonl');
+}
+function readLog(bundlePath) {
+    const path = logPath(bundlePath);
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf-8');
+    return raw
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => JSON.parse(line));
+}
+function appendEntry(bundlePath, entry) {
+    appendFileSync(logPath(bundlePath), JSON.stringify(entry) + '\n');
+}
+/** Raises a new, immutable Question. Never mutates or removes any existing log entry. */
+export function raiseQuestion(bundlePath, body, target) {
+    const entry = { type: 'raised', id: randomUUID(), createdAt: new Date().toISOString(), body, target };
+    appendEntry(bundlePath, entry);
+    return { id: entry.id, createdAt: entry.createdAt, body: entry.body, target: entry.target, status: 'open' };
+}
+/**
+ * Withdraws an existing Question and raises its replacement in one call — a
+ * correction is recorded as new log entries, never as an edit to the original.
+ */
+export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBody, replacementTarget) {
+    const replacement = {
+        type: 'raised',
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        body: replacementBody,
+        target: replacementTarget,
+    };
+    const withdrawal = {
+        type: 'withdrawn',
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        questionId,
+        replacementId: replacement.id,
+    };
+    appendEntry(bundlePath, withdrawal);
+    appendEntry(bundlePath, replacement);
+    return {
+        withdrawn: questionId,
+        replacement: {
+            id: replacement.id,
+            createdAt: replacement.createdAt,
+            body: replacement.body,
+            target: replacement.target,
+            status: 'open',
+        },
+    };
+}
+/** Reduces the append-only log into the current set of Questions. */
+export function readQuestions(bundlePath) {
+    const questions = new Map();
+    for (const entry of readLog(bundlePath)) {
+        if (entry.type === 'raised') {
+            questions.set(entry.id, {
+                id: entry.id,
+                createdAt: entry.createdAt,
+                body: entry.body,
+                target: entry.target,
+                status: 'open',
+            });
+        }
+        else {
+            const question = questions.get(entry.questionId);
+            if (question) {
+                question.status = 'withdrawn';
+                question.supersededBy = entry.replacementId;
+            }
+        }
+    }
+    return [...questions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}

package/dist/questions/types.js

@@ -0,0 +1 @@
+export {};