review-workspace 1.3.0 → 1.5.0

package/dist/bundle/publish-with-handoff.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exportHandoff } from "../handoff/export-handoff.js";
+import { readQuestions } from "../questions/questions-log.js";
+import { DEFAULT_LIMITS } from "../security/limits.js";
+import { publishBundle } from "./publish.js";
+import { readChain } from "./round.js";
+/**
+ * Publishes a bundle and, only once the publish itself succeeds, exports its
+ * open change-request Comments as a hand-off file into the target repo's
+ * working tree. The round number comes from `chain.json` when present
+ * (round N>1), otherwise round 1 — independent of chaining, same as the
+ * hand-off export itself.
+ */
+export async function publishBundleAndExportHandoff(bundlePath, options) {
+    const result = publishBundle(bundlePath, options.limits ?? DEFAULT_LIMITS);
+    if (!result.ok)
+        return result;
+    const document = JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8'));
+    const round = readChain(bundlePath)?.round ?? 1;
+    const handoff = await exportHandoff({
+        bundlePath,
+        comparison: document.comparison,
+        round,
+        comments: readQuestions(bundlePath),
+        annotations: document.annotations ?? [],
+        ask: options.ask,
+        repoPathCachePath: options.repoPathCachePath,
+    });
+    return { ...result, handoff };
+}

package/dist/bundle/round.js

@@ -13,6 +13,13 @@ export function mrKeyFor(comparison) {
 function readReviewDocument(bundlePath) {
     return JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8'));
 }
+/** Reads a bundle's `chain.json`, if it has one — absent for every round-1 bundle. */
+export function readChain(bundlePath) {
+    const path = join(bundlePath, 'chain.json');
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
 /**
  * Reads a bundle directory name shaped like `<name>-r{N}` and splits it into
  * the chain's base name and that bundle's round number. A name with no

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { validateBundle } from "./bundle/validate-bundle.js";
-import { publishBundle } from "./bundle/publish.js";
+import { publishBundleAndExportHandoff } from "./bundle/publish-with-handoff.js";
 import { checkRound, scaffoldNextRound } from "./bundle/round.js";
+import { askForRepoPathOnStdin } from "./handoff/ask-repo-path.js";
 import { startReviewServer } from "./server/create-server.js";
 const [, , command, bundlePath, ...rest] = process.argv;
 function fail(message) {
@@ -27,11 +28,14 @@ if (command === 'open') {
     }
 }
 else if (command === 'publish') {
-    const result = publishBundle(bundlePath);
+    const result = await publishBundleAndExportHandoff(bundlePath, { ask: askForRepoPathOnStdin });
     if (!result.ok) {
         fail(`Publish rejected: ${result.blockingReason} — ${result.message}`);
     }
     console.log('Published.');
+    if (result.handoff?.written) {
+        console.log(`Hand-off file written: ${result.handoff.filePath}`);
+    }
 }
 else if (command === 'round') {
     const liveHead = flagValue('--live-head');

package/dist/handoff/ask-repo-path.js

@@ -0,0 +1,17 @@
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+/**
+ * Real interactive `AskForRepoPath` implementation for CLI/server use —
+ * prompts on stdin/stdout. Kept separate from `repo-path-cache.ts` so that
+ * module stays free of any actual I/O and easy to unit test with a stub `ask`.
+ */
+export async function askForRepoPathOnStdin(repoSlug) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await rl.question(`Local checkout path for ${repoSlug}: `);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/handoff/build-handoff-markdown.js

@@ -0,0 +1,110 @@
+import { resolve } from 'node:path';
+const GENERAL_GROUP = '(general — no Target)';
+function targetPath(target) {
+    return target.path;
+}
+function targetKey(target) {
+    switch (target.type) {
+        case 'file':
+            return `file:${target.path}`;
+        case 'binary':
+            return `binary:${target.path}`;
+        case 'hunk':
+            return `hunk:${target.path}:${target.hunkIndex}`;
+        case 'line':
+            return `line:${target.path}:${target.side}:${target.line}`;
+    }
+}
+// Same-type-same-Target only: a file-level comment does not pick up
+// hunk-level Annotations on that file (or vice versa). Cross-granularity
+// matching is a coarser question ("does this Annotation touch material this
+// comment also concerns?") that issue #10 doesn't ask for — it wants the
+// Annotation the comment was raised against, i.e. the same Target.
+function targetsEqual(a, b) {
+    return targetKey(a) === targetKey(b);
+}
+function describeTarget(target) {
+    switch (target.type) {
+        case 'file':
+            return `File: ${target.path}`;
+        case 'hunk':
+            return `Hunk #${target.hunkIndex} in ${target.path}`;
+        case 'line':
+            return `Line ${target.line} (${target.side}) in ${target.path}`;
+        case 'binary':
+            return `Binary change: ${target.path}`;
+    }
+}
+function openChangeRequests(comments) {
+    return comments.filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+}
+function groupByFile(comments) {
+    const byFile = new Map();
+    for (const comment of comments) {
+        const key = comment.target ? targetPath(comment.target) : GENERAL_GROUP;
+        const group = byFile.get(key) ?? [];
+        group.push(comment);
+        byFile.set(key, group);
+    }
+    return byFile;
+}
+function orderedFileKeys(byFile) {
+    return [...byFile.keys()].sort((a, b) => {
+        if (a === GENERAL_GROUP)
+            return 1;
+        if (b === GENERAL_GROUP)
+            return -1;
+        return a.localeCompare(b);
+    });
+}
+function metadataBlock(input) {
+    return [
+        '<!--',
+        'review-workspace-handoff',
+        `bundlePath: ${resolve(input.bundlePath)}`,
+        `repository: ${input.comparison.repository ?? ''}`,
+        `mrNumber: ${input.comparison.number ?? ''}`,
+        `round: ${input.round}`,
+        '-->',
+    ];
+}
+/**
+ * Builds the hand-off Markdown a separate implementer-side skill parses.
+ * Content is raw: every open change-request Comment verbatim, grouped by
+ * file, with its exact Target and any Annotation raised against that same
+ * Target for context. This exact shape is a parsed contract — golden-tested,
+ * do not reformat without updating that consumer too.
+ */
+export function buildHandoffMarkdown(input) {
+    const comments = openChangeRequests(input.comments);
+    const lines = [`# Change requests — round ${input.round}`, '', ...metadataBlock(input), ''];
+    if (comments.length === 0) {
+        lines.push('_No open change-request comments._');
+        return lines.join('\n') + '\n';
+    }
+    const byFile = groupByFile(comments);
+    for (const file of orderedFileKeys(byFile)) {
+        lines.push(`## ${file}`);
+        lines.push('');
+        const fileComments = [...(byFile.get(file) ?? [])].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        for (const comment of fileComments) {
+            lines.push(comment.target ? `### ${describeTarget(comment.target)}` : '### (no Target)');
+            if (comment.target?.type === 'line') {
+                lines.push(`> ${comment.target.expectedText}`);
+            }
+            lines.push('');
+            lines.push(comment.body);
+            lines.push('');
+            const relatedAnnotations = comment.target
+                ? input.annotations.filter((a) => targetsEqual(a.target, comment.target))
+                : [];
+            for (const annotation of relatedAnnotations) {
+                lines.push(`**Annotation (${annotation.kind ?? 'note'}):** ${annotation.summary}`);
+                lines.push('');
+            }
+            lines.push('---');
+            lines.push('');
+        }
+    }
+    return lines.join('\n').replace(/\n{2,}$/, '\n');
+}

package/dist/handoff/ensure-gitignore.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const ENTRY = '.review-feedback/';
+const COVERING_PATTERNS = new Set(['.review-feedback/', '.review-feedback', '.review-feedback/**', '.review-feedback/*']);
+function lineCoversHandoffDir(line) {
+    return COVERING_PATTERNS.has(line.trim());
+}
+/**
+ * Ensures the target repo's `.gitignore` excludes `.review-feedback/` —
+ * creating the file if it doesn't exist, appending the entry if the file
+ * exists but neither an exact nor a broader matching entry already covers it.
+ */
+export function ensureGitignoreExcludesHandoff(repoPath) {
+    const gitignorePath = join(repoPath, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, `${ENTRY}\n`);
+        return;
+    }
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (content.split('\n').some(lineCoversHandoffDir))
+        return;
+    const withTrailingNewline = content.endsWith('\n') ? content : `${content}\n`;
+    writeFileSync(gitignorePath, `${withTrailingNewline}${ENTRY}\n`);
+}

package/dist/handoff/export-handoff.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildHandoffMarkdown } from "./build-handoff-markdown.js";
+import { ensureGitignoreExcludesHandoff } from "./ensure-gitignore.js";
+import { DEFAULT_REPO_PATH_CACHE_PATH, resolveRepoPath } from "./repo-path-cache.js";
+/**
+ * Exports open change-request Comments as a self-describing hand-off
+ * Markdown file into the target repo's local working tree, and ensures
+ * `.review-feedback/` is gitignored there. A no-op when there are no open
+ * change-requests — this is what makes it safe to call after every publish.
+ */
+export async function exportHandoff(options) {
+    const { bundlePath, comparison, round, comments, annotations, ask, repoPathCachePath } = options;
+    const hasOpenChangeRequest = comments.some((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+    if (!hasOpenChangeRequest)
+        return { written: false };
+    if (!comparison.repository) {
+        throw new Error('comparison.repository is required to export a hand-off file');
+    }
+    const repoPath = await resolveRepoPath(comparison.repository, ask, repoPathCachePath ?? DEFAULT_REPO_PATH_CACHE_PATH);
+    const markdown = buildHandoffMarkdown({ bundlePath, comparison, round, comments, annotations });
+    const feedbackDir = join(repoPath, '.review-feedback');
+    mkdirSync(feedbackDir, { recursive: true });
+    const filePath = join(feedbackDir, `${comparison.number}-round${round}.md`);
+    writeFileSync(filePath, markdown);
+    ensureGitignoreExcludesHandoff(repoPath);
+    return { written: true, filePath, repoPath };
+}

package/dist/handoff/repo-path-cache.js

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_REPO_PATH_CACHE_PATH = join(homedir(), '.claude', 'review-workspace-repo-paths.json');
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return {};
+    return JSON.parse(readFileSync(cachePath, 'utf-8'));
+}
+function writeCache(cachePath, cache) {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n');
+}
+/**
+ * Resolves a target repo's local checkout path for `repoSlug`. Reuses a
+ * cached answer as long as it still exists on disk; asks (via `ask`) and
+ * caches the answer otherwise — this covers both "never asked before" and
+ * "the cached checkout was moved or deleted" in the same branch.
+ */
+export async function resolveRepoPath(repoSlug, ask, cachePath = DEFAULT_REPO_PATH_CACHE_PATH) {
+    const cache = readCache(cachePath);
+    const cached = cache[repoSlug];
+    if (cached && existsSync(cached))
+        return cached;
+    const answer = await ask(repoSlug);
+    writeCache(cachePath, { ...cache, [repoSlug]: answer });
+    return answer;
+}

package/dist/questions/questions-log.js

@@ -20,18 +20,26 @@ function readLog(bundlePath) {
 function appendEntry(bundlePath, entry) {
     appendFileSync(logPath(bundlePath), JSON.stringify(entry) + '\n');
 }
-/** Raises a new, immutable question Comment. Never mutates or removes any existing log entry. */
-export function raiseQuestion(bundlePath, body, target) {
+/** Raises a new, immutable Comment. Never mutates or removes any existing log entry. */
+export function raiseQuestion(bundlePath, body, target, kind = 'question') {
     const entry = {
         type: 'raised',
         id: randomUUID(),
         createdAt: new Date().toISOString(),
         body,
         target,
-        kind: 'question',
+        kind,
     };
     appendEntry(bundlePath, entry);
-    return { id: entry.id, createdAt: entry.createdAt, body: entry.body, target: entry.target, kind: 'question', status: 'open' };
+    return {
+        id: entry.id,
+        createdAt: entry.createdAt,
+        body: entry.body,
+        target: entry.target,
+        kind,
+        status: 'open',
+        resolved: false,
+    };
 }
 /**
  * Withdraws an existing question Comment and raises its replacement in one call —
@@ -64,9 +72,39 @@ export function withdrawAndReplaceQuestion(bundlePath, questionId, replacementBo
             target: replacement.target,
             kind: 'question',
             status: 'open',
+            resolved: false,
         },
     };
 }
+function isOpenChangeRequest(comment) {
+    return comment.kind === 'change-request' && comment.status === 'open' && !comment.resolved;
+}
+/**
+ * Marks an open change-request Comment resolved. This is a human-only, reviewer-triggered
+ * action recorded in the same append-only log — nothing a Generator writes (the
+ * Review Document, `review.next.json`) can ever produce this entry.
+ *
+ * Validates before writing: a Comment that doesn't exist, or isn't currently an open
+ * change-request, is rejected without appending anything to the log.
+ */
+export function resolveComment(bundlePath, commentId) {
+    const comment = readQuestions(bundlePath).find((c) => c.id === commentId);
+    if (!comment)
+        return { outcome: 'not-found' };
+    if (!isOpenChangeRequest(comment))
+        return { outcome: 'not-resolvable', comment };
+    const entry = {
+        type: 'resolved',
+        id: randomUUID(),
+        createdAt: new Date().toISOString(),
+        commentId,
+    };
+    appendEntry(bundlePath, entry);
+    return {
+        outcome: 'resolved',
+        comment: { ...comment, resolved: true, resolvedAt: entry.createdAt },
+    };
+}
 /** Reduces the append-only log into the current set of Comments. */
 export function readQuestions(bundlePath) {
     const comments = new Map();
@@ -79,15 +117,23 @@ export function readQuestions(bundlePath) {
                 target: entry.target,
                 kind: entry.kind ?? 'question',
                 status: 'open',
+                resolved: false,
             });
         }
-        else {
+        else if (entry.type === 'withdrawn') {
             const comment = comments.get(entry.questionId);
             if (comment) {
                 comment.status = 'withdrawn';
                 comment.supersededBy = entry.replacementId;
             }
         }
+        else {
+            const comment = comments.get(entry.commentId);
+            if (comment && comment.kind === 'change-request') {
+                comment.resolved = true;
+                comment.resolvedAt = entry.createdAt;
+            }
+        }
     }
     return [...comments.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }

package/dist/server/create-server.js

@@ -3,9 +3,10 @@ import { randomBytes } from 'node:crypto';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { validateBundle } from "../bundle/validate-bundle.js";
-import { publishBundle } from "../bundle/publish.js";
+import { publishBundleAndExportHandoff } from "../bundle/publish-with-handoff.js";
 import { watchBundle } from "./watch-bundle.js";
-import { raiseQuestion, readQuestions, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
+import { raiseQuestion, readQuestions, resolveComment, withdrawAndReplaceQuestion } from "../questions/questions-log.js";
+import { askForRepoPathOnStdin } from "../handoff/ask-repo-path.js";
 import { readReviewState, writeReviewState } from "../review-state/review-state.js";
 import { render } from "../renderer/render.js";
 import { buildReport } from "../export/report.js";
@@ -15,6 +16,8 @@ export function generateWriteToken() {
 }
 const WRITE_TOKEN_HEADER = 'x-write-token';
 const WITHDRAW_PATH = /^\/questions\/([^/]+)\/withdraw$/;
+const RESOLVE_PATH = /^\/questions\/([^/]+)\/resolve$/;
+const COMMENT_KINDS = ['question', 'change-request'];
 const ASSET_CONTENT_TYPES = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -69,6 +72,7 @@ function readJsonBody(req) {
 }
 export function startReviewServer(bundlePath, opts = {}) {
     const writeToken = opts.writeToken ?? generateWriteToken();
+    const askForRepoPath = opts.askForRepoPath ?? askForRepoPathOnStdin;
     // The served document is cached and only refreshed by the watcher below, so a
     // publish must actually trigger re-validation for /document to ever change —
     // this is what makes file watching load-bearing rather than a no-op wrapper
@@ -137,19 +141,24 @@ export function startReviewServer(bundlePath, opts = {}) {
             }
         }
         if (req.method === 'POST' && url.pathname === '/publish') {
-            const result = publishBundle(bundlePath);
-            respond(result.ok ? 200 : 422, result);
+            publishBundleAndExportHandoff(bundlePath, { ask: askForRepoPath, repoPathCachePath: opts.repoPathCachePath })
+                .then((result) => respond(result.ok ? 200 : 422, result))
+                .catch((err) => respond(500, { error: err instanceof Error ? err.message : 'publish failed' }));
             return;
         }
         if (req.method === 'POST' && url.pathname === '/questions') {
             readJsonBody(req)
                 .then((body) => {
-                const { body: text, target } = body;
+                const { body: text, target, kind } = body;
                 if (typeof text !== 'string' || text.trim() === '') {
                     respond(400, { error: 'body is required' });
                     return;
                 }
-                respond(201, raiseQuestion(bundlePath, text, target));
+                if (kind !== undefined && !COMMENT_KINDS.includes(kind)) {
+                    respond(400, { error: `kind must be one of ${COMMENT_KINDS.join(', ')}` });
+                    return;
+                }
+                respond(201, raiseQuestion(bundlePath, text, target, kind ?? 'question'));
             })
                 .catch(() => respond(400, { error: 'invalid JSON body' }));
             return;
@@ -168,6 +177,23 @@ export function startReviewServer(bundlePath, opts = {}) {
                 .catch(() => respond(400, { error: 'invalid JSON body' }));
             return;
         }
+        // Human-only action: a Reviewer marking a change-request Comment resolved. This
+        // never reads from or writes to `review.next.json`/the Generator-owned Review
+        // Document — the Generator has no path to setting `resolved` (see ADR 0002).
+        const resolveMatch = RESOLVE_PATH.exec(url.pathname);
+        if (req.method === 'POST' && resolveMatch) {
+            const result = resolveComment(bundlePath, resolveMatch[1]);
+            if (result.outcome === 'not-found') {
+                respond(404, { error: 'no such Comment' });
+                return;
+            }
+            if (result.outcome === 'not-resolvable') {
+                respond(400, { error: 'Comment is not an open change-request' });
+                return;
+            }
+            respond(200, result.comment);
+            return;
+        }
         if (req.method === 'PUT' && url.pathname === '/state') {
             readJsonBody(req)
                 .then((body) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "review-workspace",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "A local, offline decision surface for reviewing a code Comparison — evidence-linked map of intent, behavior, risk, and observable effects.",
   "license": "MIT",
   "author": "Salih Sayer",