@erdemtuna/doc-review 0.8.1 → 0.10.0

package/src/setup-guidance.js

@@ -1,128 +0,0 @@
-export const GUIDANCE_BEGIN = "<!-- BEGIN doc-review -->";
-export const GUIDANCE_END = "<!-- END doc-review -->";
-
-// Historical generated text is deliberately independent of the current guidance.
-const LEGACY_TAIL = `
-\`npx -y @erdemtuna/doc-review <file.html>\`. For a locally running web page, open the real
-route with \`npx -y @erdemtuna/doc-review http://localhost:3000/path\` instead of recreating
-it as a static file. Then block on
-\`npx -y @erdemtuna/doc-review poll <target> --timeout 600\` until they send feedback.
-If it prints \`{"status":"timeout"}\`, no feedback arrived yet — run the same
-poll command again to keep waiting. When a \`{"status":"feedback"}\` batch
-arrives, apply it, then run the exact acknowledgement command in its
-\`next_step\`, which uses \`--ack <batch_id>\`.
-
-Keep the poll command in the foreground and do not end the turn while it waits.
-If the shell returns a process or session handle, keep waiting on that handle until
-the command exits. \`npx -y @erdemtuna/doc-review status <target>\` reports instantly
-whether feedback is already waiting, without blocking.
-
-The batch groups feedback by page under \`pages\`, so fix every page listed. Items
-under \`edits\` are changes the user already made: \`after\` is their exact wording,
-so carry it across verbatim and never revert it — and if the HTML was generated
-from MDX or Markdown, apply it to the source too. Markdown files open rendered
-and are never written by doc-review: apply their comments and edits to the
-Markdown source, keeping its syntax. There is no reply channel; the user sees
-your work when the page reloads. For a localhost page, direct edits and deletions
-arrive with \`kind: "url"\`; find and update the matching MDX, TSX, template, or
-component source. Never write the rendered HTTP response over project source.`;
-
-export const LEGACY_GUIDANCE = Object.freeze([
-  `## Reviewing files and localhost pages with doc-review
-
-After writing an HTML or Markdown file the user will read, open it for them with${LEGACY_TAIL}`,
-  `## Reviewing files and localhost pages with doc-review
-
-Start only when the user explicitly invokes /doc-review or requests an
-interactive browser review. Writing, updating, discussing, or generically reviewing
-content does not authorize opening a review or polling. Another skill's automatic
-review step is not user permission. Otherwise respond normally.
-
-After that explicit request, open the requested HTML or Markdown file with${LEGACY_TAIL}`,
-]);
-
-const migrationMessage = "AGENTS.md contains custom or unrecognized doc-review guidance — left it unchanged. " +
-  "Manually reconcile that guidance, then wrap only the setup-owned section in " +
-  `${GUIDANCE_BEGIN} and ${GUIDANCE_END}, or remove it and re-run setup.`;
-
-function invalidMarkers() {
-  throw new Error("AGENTS.md has malformed, duplicate, or ambiguous doc-review ownership markers. " +
-    "Keep exactly one standalone BEGIN/END pair in order, then re-run setup. No setup files were changed.");
-}
-
-function render(body, newline) {
-  return `${GUIDANCE_BEGIN}\n${body.trim()}\n${GUIDANCE_END}`.replaceAll("\n", newline);
-}
-
-/** Plan the complete edit before setup writes any files. Never normalize user text. */
-export function updateGuidance(existing, body) {
-  const lines = [...existing.matchAll(/[^\n]*(?:\n|$)/g)]
-    .filter((match) => match[0])
-    .map((match) => ({
-      text: match[0].replace(/\r?\n$/, ""),
-      start: match.index,
-      end: match.index + match[0].replace(/\r?\n$/, "").length,
-    }));
-  const markers = lines.filter(({ text }) => /doc-review/i.test(text) &&
-    (/\b(?:BEGIN|END)\b/i.test(text) && /<!--|-->|^\s*(?:BEGIN|END)\b/i.test(text)));
-
-  if (markers.length) {
-    if (markers.length !== 2 || markers[0].text !== GUIDANCE_BEGIN || markers[1].text !== GUIDANCE_END) {
-      invalidMarkers();
-    }
-    const [begin, end] = markers;
-    const newline = existing.slice(begin.end).startsWith("\r\n") ? "\r\n" : "\n";
-    return {
-      contents: existing.slice(0, begin.start) + render(body, newline) + existing.slice(end.end),
-      message: "Updated setup-owned AGENTS.md guidance   (Codex)",
-    };
-  }
-
-  const candidates = [];
-  for (const legacy of LEGACY_GUIDANCE) {
-    for (const command of ["npx -y @erdemtuna/doc-review", "doc-review"]) {
-      for (const newline of ["\n", "\r\n"]) {
-        const text = legacy.replaceAll("npx -y @erdemtuna/doc-review", command).replaceAll("\n", newline);
-        let start = existing.indexOf(text);
-        while (start !== -1) {
-          const end = start + text.length;
-          const before = existing.slice(0, start);
-          const after = existing.slice(end);
-          // A complete generated section, not a substring of customized prose.
-          if ((start === 0 || before.endsWith("\n") || before === "\uFEFF") &&
-              /^(?:\r?\n|$)/.test(after) &&
-              /^(?:\s*$|(?:\r?\n)+(?=#{1,2} ))/.test(after)) {
-            candidates.push({ start, end, newline });
-          }
-          start = existing.indexOf(text, start + text.length);
-        }
-      }
-    }
-  }
-  if (candidates.length > 1) {
-    throw new Error("AGENTS.md contains multiple legacy doc-review sections; ownership is ambiguous. " +
-      "Reconcile them before re-running setup. No setup files were changed.");
-  }
-  if (candidates.length === 1) {
-    const { start, end, newline } = candidates[0];
-    const surrounding = existing.slice(0, start) + existing.slice(end);
-    if (!/doc-review/i.test(surrounding)) {
-      return {
-        contents: existing.slice(0, start) + render(body, newline) + existing.slice(end),
-        message: "Migrated legacy AGENTS.md guidance to setup-owned markers   (Codex)",
-      };
-    }
-  }
-  if (/doc-review/i.test(existing)) {
-    return { contents: existing, message: migrationMessage };
-  }
-
-  const newline = existing.includes("\r\n") ? "\r\n" : "\n";
-  const separator = !existing || existing.endsWith(newline + newline)
-    ? ""
-    : existing.endsWith("\n") ? newline : newline + newline;
-  return {
-    contents: existing + separator + render(body, newline) + newline,
-    message: `${existing ? "Updated" : "Created"} AGENTS.md   (Codex)`,
-  };
-}

package/src/state.js

@@ -1,507 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { normalizeCommentAnchor } from "./comment-anchor.js";
-import { canonicalTarget, ensureStateDir, pageKey, realFile, statePath, targetKey } from "./paths.js";
-export { atomicWrite } from "./atomic-write.js";
-import { atomicWrite } from "./atomic-write.js";
-
-/** Anything untouched this long is review debris, not work in progress. */
-const PRUNE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
-const DELIVERY_STATES = new Set(["queued", "possibly_delivered", "delivered"]);
-
-const fresh = (entry, now) => !!entry && now - (entry.updatedAt || 0) < PRUNE_AGE_MS;
-const batchId = () => `b_${crypto.randomBytes(12).toString("hex")}`;
-const emptyState = () => ({ pages: {}, batches: {}, receipts: {} });
-
-function pruneData(data, now = Date.now()) {
-  let changed = false;
-  for (const [key, page] of Object.entries(data.pages)) {
-    const missingFile = page.kind !== "url" && !fs.existsSync(page.file);
-    if (!fresh(page, now) || missingFile) {
-      delete data.pages[key];
-      delete data.batches[key];
-      changed = true;
-    }
-  }
-  for (const [key, batch] of Object.entries(data.batches)) {
-    if (!fresh(batch, now)) {
-      delete data.batches[key];
-      changed = true;
-    }
-  }
-  for (const [id, receipt] of Object.entries(data.receipts)) {
-    if (!fresh(receipt, now)) {
-      delete data.receipts[id];
-      changed = true;
-    }
-  }
-  return changed;
-}
-
-function normalizeState(parsed, makeBatchId) {
-  if (!parsed || typeof parsed !== "object" || !parsed.pages || typeof parsed.pages !== "object") {
-    throw new Error("Invalid doc-review state: expected a pages object.");
-  }
-  const data = {
-    pages: parsed.pages,
-    batches: parsed.batches && typeof parsed.batches === "object" ? parsed.batches : {},
-    receipts: parsed.receipts && typeof parsed.receipts === "object" ? parsed.receipts : {},
-  };
-  let changed = !parsed.batches || !parsed.receipts;
-  const normalizeAnchor = (comment) => {
-    if (!comment || comment.anchor == null) return;
-    const normalized = normalizeCommentAnchor(comment.kind === "element" ? "element" : "selection", comment.anchor);
-    if (JSON.stringify(normalized) !== JSON.stringify(comment.anchor)) {
-      comment.anchor = normalized;
-      changed = true;
-    }
-  };
-  for (const page of Object.values(data.pages)) {
-    for (const comment of page?.comments || []) normalizeAnchor(comment);
-  }
-  for (const record of Object.values(data.batches)) {
-    if (!record || typeof record !== "object" || !record.batch || !Array.isArray(record.cleanup)) {
-      throw new Error("Invalid doc-review state: malformed feedback batch.");
-    }
-    const existingId = record.batch_id || record.batch.batch_id;
-    if (record.batch_id && record.batch.batch_id && record.batch_id !== record.batch.batch_id) {
-      throw new Error("Invalid doc-review state: feedback batch IDs disagree.");
-    }
-    if (!existingId) {
-      record.batch_id = makeBatchId();
-      record.batch.batch_id = record.batch_id;
-      record.delivery_state = "possibly_delivered";
-      changed = true;
-    } else {
-      record.batch_id = existingId;
-      if (record.batch.batch_id !== existingId) {
-        record.batch.batch_id = existingId;
-        changed = true;
-      }
-      if (!record.delivery_state) {
-        record.delivery_state = "possibly_delivered";
-        changed = true;
-      }
-    }
-    if (!DELIVERY_STATES.has(record.delivery_state)) {
-      throw new Error(`Invalid doc-review state: unknown delivery state ${record.delivery_state}.`);
-    }
-    for (const page of record.batch.pages || []) {
-      for (const comment of page.comments || []) normalizeAnchor(comment);
-    }
-  }
-  return { data, changed };
-}
-
-/**
- * All durable state lives in one JSON file. No database, no network.
- *
- * Shape:
- *   {
- *     pages:   { <key>: { key, file, pristine, comments[], edits[], updatedAt } },
- *     batches: { <entryKey>: { batch_id, batch, cleanup, delivery_state, updatedAt } },
- *     receipts:{ <batchId>: { cleanup, delivery_state, updatedAt } },
- *   }
- *
- * Pages are fully independent: no page ever references another. Batches are
- * feedback the user sent that no agent has acknowledged yet; persisting them
- * means "your feedback is safe" stays true across server restarts.
- */
-export class Store {
-  constructor({ write = atomicWrite, makeBatchId = batchId } = {}) {
-    this.data = emptyState();
-    this.write = write;
-    this.makeBatchId = makeBatchId;
-    this.load();
-  }
-
-  load() {
-    let parsed;
-    try {
-      const raw = fs.readFileSync(statePath(), "utf8");
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      if (err.code === "ENOENT") return this.data;
-      throw err;
-    }
-    const normalized = normalizeState(parsed, this.makeBatchId);
-    this.data = normalized.data;
-    const changed = pruneData(this.data);
-    if (normalized.changed || changed) this.persist(this.data);
-    return this.data;
-  }
-
-  persist(data) {
-    ensureStateDir();
-    this.write(statePath(), JSON.stringify(data, null, 2));
-  }
-
-  /** Replace durable state once, then publish the committed draft in memory. */
-  transaction(mutator) {
-    const draft = structuredClone(this.data);
-    const result = mutator(draft);
-    if (result && typeof result.then === "function") {
-      throw new Error("Store.transaction mutators must be synchronous.");
-    }
-    pruneData(draft);
-    this.persist(draft);
-    this.data = draft;
-    return result;
-  }
-
-  /** Persist deliberate direct changes used by maintenance and tests. */
-  save() {
-    const draft = structuredClone(this.data);
-    pruneData(draft);
-    this.persist(draft);
-    this.data = draft;
-    return this.data;
-  }
-
-  /** Register a file as a reviewable page, capturing the agent's version. */
-  openPage(file, pristine) {
-    const key = pageKey(file);
-    return this.transaction((draft) => {
-      const existing = draft.pages[key];
-      const page = existing || {
-        key,
-        kind: "file",
-        file: realFile(file),
-        pristine: "",
-        comments: [],
-        edits: [],
-        updatedAt: 0,
-      };
-      page.kind = "file";
-      page.file = realFile(file);
-      delete page.url;
-      if (!existing || typeof pristine === "string") {
-        page.pristine = typeof pristine === "string" ? pristine : page.pristine;
-      }
-      page.updatedAt = Date.now();
-      draft.pages[key] = page;
-      return page;
-    });
-  }
-
-  /** Register a rendered localhost route. Browser edits are never written to it. */
-  openUrl(url) {
-    const target = canonicalTarget(url);
-    if (target.kind !== "url") throw new Error("Expected a localhost URL.");
-    const key = targetKey(target.value);
-    return this.transaction((draft) => {
-      const existing = draft.pages[key];
-      const page = existing || {
-        key,
-        kind: "url",
-        url: target.value,
-        pristine: "",
-        comments: [],
-        edits: [],
-        updatedAt: 0,
-      };
-      page.kind = "url";
-      page.url = target.value;
-      delete page.file;
-      page.updatedAt = Date.now();
-      draft.pages[key] = page;
-      return page;
-    });
-  }
-
-  page(key) {
-    return this.data.pages[key] || null;
-  }
-
-  pageForFile(file) {
-    return this.page(pageKey(file));
-  }
-
-  pageForTarget(target) {
-    return this.page(targetKey(target));
-  }
-
-  update(key, mutate) {
-    if (!this.page(key)) return null;
-    return this.transaction((draft) => {
-      const page = draft.pages[key];
-      mutate(page);
-      page.updatedAt = Date.now();
-      return page;
-    });
-  }
-
-  addComment(key, comment) {
-    const anchor = comment.anchor == null
-      ? comment.anchor
-      : normalizeCommentAnchor(comment.kind === "element" ? "element" : "selection", comment.anchor);
-    if (comment.anchor != null && !anchor) throw new Error("Invalid comment anchor.");
-    return this.update(key, (page) => {
-      page.comments.push({ ...comment, ...(comment.anchor !== undefined ? { anchor } : {}) });
-    });
-  }
-
-  removeComment(key, id) {
-    return this.update(key, (page) => {
-      page.comments = page.comments.filter((c) => c.id !== id);
-    });
-  }
-
-  /** Reword feedback, optionally turning a delivered instruction into a correction. */
-  updateComment(key, id, feedback, { replacementId = "", correctionOf = "" } = {}) {
-    let found = false;
-    const page = this.update(key, (p) => {
-      const index = p.comments.findIndex((c) => c.id === id);
-      const comment = p.comments[index];
-      if (comment) {
-        const updated = {
-          ...comment,
-          ...(replacementId ? { id: replacementId } : {}),
-          feedback,
-          updatedAt: Date.now(),
-          ...(correctionOf ? { correction: true, correctionOf } : {}),
-        };
-        p.comments[index] = updated;
-        found = true;
-      }
-    });
-    return found ? page : null;
-  }
-
-  /**
-   * Reword a comment and every queued copy in one commit. Any evidence that
-   * the old ID may have shipped turns the edit into a replacement correction.
-   */
-  reviseComment(key, id, feedback, { replacementId } = {}) {
-    if (!this.page(key)?.comments.some((comment) => comment.id === id)) return null;
-    return this.transaction((draft) => {
-      const page = draft.pages[key];
-      const index = page.comments.findIndex((comment) => comment.id === id);
-      const existing = page.comments[index];
-      const matching = (record) => record.cleanup.some((item) => item.key === key && item.ids.includes(id));
-      const mayHaveShipped =
-        Object.values(draft.batches).some((record) => record.delivery_state !== "queued" && matching(record)) ||
-        Object.values(draft.receipts).some((record) => matching(record));
-
-      if (mayHaveShipped) {
-        page.comments[index] = {
-          ...existing,
-          id: replacementId || this.makeBatchId().replace(/^b_/, "c_"),
-          feedback,
-          updatedAt: Date.now(),
-          correction: true,
-          correctionOf: existing.feedback,
-        };
-        page.updatedAt = Date.now();
-        return { delivery: "correction", page };
-      }
-
-      page.comments[index] = { ...existing, feedback, updatedAt: Date.now() };
-      page.updatedAt = Date.now();
-      let updatedPending = false;
-      for (const record of Object.values(draft.batches)) {
-        if (record.delivery_state !== "queued" || !matching(record)) continue;
-        for (const batchPage of record.batch.pages || []) {
-          const comment = (batchPage.comments || []).find((item) => item.id === id);
-          if (comment) {
-            comment.feedback = feedback;
-            updatedPending = true;
-          }
-        }
-        record.updatedAt = Date.now();
-      }
-      return { delivery: updatedPending ? "updated-pending" : "unsent", page };
-    });
-  }
-
-  /**
-   * Edits are deduped by label+kind so retyping one block stays one row, but
-   * the text is refreshed every time so `after` is always the latest wording.
-   */
-  addEdit(key, label, kind, before, after, beforeHtml, afterHtml, extra) {
-    return this.update(key, (page) => {
-      const row = page.edits.find((e) => e.label === label && e.kind === kind);
-      if (row) {
-        if (after !== undefined) row.after = after;
-        if (afterHtml !== undefined) row.after_html = afterHtml;
-        // A re-move of the same block replaces its landing spot.
-        if (extra) {
-          if (Array.isArray(extra.truncated_fields)) {
-            const replaced = new Set([
-              ...(after !== undefined ? ["after"] : []),
-              ...(afterHtml !== undefined ? ["after_html"] : []),
-              ...["moved_after", "moved_before"].filter((field) => extra[field] !== undefined),
-            ]);
-            // Original before text is retained across edits, including its truncation.
-            const truncatedFields = [...new Set([
-              ...(row.truncated_fields || []).filter((field) => !replaced.has(field)),
-              ...extra.truncated_fields.filter((field) => replaced.has(field)),
-            ])];
-            extra = { ...extra, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
-          }
-          if (extra.staged_assets) {
-            const assets = [...(row.staged_assets || []), ...extra.staged_assets];
-            extra = { ...extra, staged_assets: [...new Map(assets.map((asset) => [asset.path, asset])).values()] };
-          }
-          Object.assign(row, extra);
-        }
-        row.updatedAt = Date.now();
-        return;
-      }
-      page.edits.push({ label, kind, before, after, before_html: beforeHtml, after_html: afterHtml, ...(extra || {}), at: Date.now(), updatedAt: Date.now() });
-    });
-  }
-
-  clearEdits(key) {
-    return this.update(key, (page) => {
-      page.edits = [];
-    });
-  }
-
-  /** After the agent writes, its version becomes the new revert target. */
-  setPristine(key, html, { keepEdits = false } = {}) {
-    return this.update(key, (page) => {
-      page.pristine = html;
-      if (!keepEdits) page.edits = [];
-    });
-  }
-
-  /**
-   * Drop exactly what the acknowledged batch carried. Comments made after
-   * Send have unknown ids; edits made (or retyped) after Send have a newer
-   * timestamp than the batch. Both must survive for the next batch.
-   */
-  clearSent(key, ids, sentAt) {
-    return this.update(key, (page) => {
-      const drop = new Set(ids);
-      page.comments = page.comments.filter((c) => !drop.has(c.id));
-      // >= not >: an edit stamped the same millisecond as the send may not
-      // have shipped — resending it is harmless, dropping it loses work.
-      page.edits = typeof sentAt === "number" ? page.edits.filter((e) => (e.updatedAt || e.at || 0) >= sentAt) : [];
-    });
-  }
-
-  // Sent-but-unacked feedback, keyed by the entry page the agent polls.
-
-  batch(entryKey) {
-    return this.data.batches[entryKey] || null;
-  }
-
-  allBatches() {
-    return this.data.batches;
-  }
-
-  setBatch(entryKey, { batch, cleanup, deliveryState = "queued" }) {
-    if (!DELIVERY_STATES.has(deliveryState)) throw new Error(`Unknown delivery state: ${deliveryState}`);
-    return this.transaction((draft) => {
-      const existing = draft.batches[entryKey];
-      if (existing && existing.delivery_state !== "queued") {
-        draft.receipts[existing.batch_id] = {
-          cleanup: existing.cleanup,
-          delivery_state: existing.delivery_state,
-          updatedAt: Date.now(),
-        };
-      }
-      const id = batch.batch_id || this.makeBatchId();
-      const storedBatch = { ...batch, batch_id: id };
-      const record = {
-        batch_id: id,
-        batch: storedBatch,
-        cleanup,
-        delivery_state: deliveryState,
-        updatedAt: Date.now(),
-      };
-      draft.batches[entryKey] = record;
-      return record;
-    });
-  }
-
-  markBatchDelivered(entryKey) {
-    if (!this.batch(entryKey)) return null;
-    return this.transaction((draft) => {
-      const record = draft.batches[entryKey];
-      record.delivery_state = "delivered";
-      record.updatedAt = Date.now();
-      return record;
-    });
-  }
-
-  /**
-   * Clear exactly one delivered receipt and its shipped page contents.
-   * Stale, duplicate, queued, and legacy possibly-delivered IDs are no-ops.
-   */
-  acknowledgeBatch(entryKey, id) {
-    const current = this.batch(entryKey);
-    if (!current || current.batch_id !== id || current.delivery_state !== "delivered") {
-      return { acknowledged: false, staged: [], keys: [] };
-    }
-    return this.transaction((draft) => {
-      const record = draft.batches[entryKey];
-      delete draft.batches[entryKey];
-      draft.receipts[id] = {
-        cleanup: record.cleanup,
-        delivery_state: "acknowledged",
-        updatedAt: Date.now(),
-      };
-      const staged = [];
-      const keys = [];
-      for (const { key, ids, staged: assets = [], sentAt } of record.cleanup) {
-        staged.push(...assets);
-        keys.push(key);
-        const page = draft.pages[key];
-        if (!page) continue;
-        const drop = new Set(ids);
-        page.comments = page.comments.filter((comment) => !drop.has(comment.id));
-        page.edits =
-          typeof sentAt === "number"
-            ? page.edits.filter((edit) => (edit.updatedAt || edit.at || 0) >= sentAt)
-            : [];
-        page.updatedAt = Date.now();
-      }
-      return { acknowledged: true, staged, keys };
-    });
-  }
-
-  clearBatch(entryKey) {
-    if (!this.batch(entryKey)) return null;
-    return this.transaction((draft) => {
-      const record = draft.batches[entryKey];
-      delete draft.batches[entryKey];
-      return record;
-    });
-  }
-}
-
-/** Resolve a sibling asset request without escaping the artifact's directory. */
-export function resolveAsset(pageFile, relative) {
-  let decoded;
-  try {
-    decoded = decodeURIComponent(relative);
-  } catch {
-    return null;
-  }
-  const base = path.dirname(pageFile);
-  const target = path.resolve(base, decoded);
-  const contained = (candidate, root) => {
-    const rel = path.relative(root, candidate);
-    return !rel.startsWith("..") && !path.isAbsolute(rel);
-  };
-  if (!contained(target, base)) return null;
-  // The lexical check alone would follow a symlink out of the directory, so
-  // the resolved filesystem path must land inside it too.
-  let real;
-  try {
-    real = fs.realpathSync(target);
-  } catch {
-    // Nothing readable at that path — anything a symlink could point to would
-    // have resolved. The caller's read fails with a plain 404.
-    return target;
-  }
-  let realBase = base;
-  try {
-    realBase = fs.realpathSync(base);
-  } catch {}
-  if (!contained(real, realBase)) return null;
-  return real;
-}