@erdemtuna/doc-review 0.11.1 → 0.13.0

package/lib/setup.js

@@ -41,55 +41,19 @@ export function shellQuote(arg) {
 /** The skill lives in its own markdown file so nothing needs escaping. */
 export const readSkill = () => fs.readFileSync(path.join(here, "SKILL.md"), "utf8");
 export const skillFor = (cmd) => readSkill().replaceAll(NPX_COMMAND, cmd);
-const CODEX_BLOCK = `
-## Reviewing files and localhost pages with doc-review
+const codexBlock = () => `## Interactive reviews 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.
+Start only when the user explicitly invokes /doc-review or requests an interactive
+browser review. Another skill's automatic review step is not user permission.
+Otherwise do not open a review or poll.
 
-After that explicit request, open the requested HTML or Markdown file with
-\`${NPX_COMMAND} <file.html>\`. For a locally running web page, open the real
-route with \`${NPX_COMMAND} http://localhost:3000/path\` instead of recreating
-it as a static file. Then block on
-\`${NPX_COMMAND} 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, handle every item, then run the exact acknowledgement command in its
-\`next_step\`, which uses \`--ack <batch_id>\`. Keep that exact batch ID on retries;
-never acknowledge an unhandled batch.
+On activation, read [.agents/skills/doc-review/SKILL.md](.agents/skills/doc-review/SKILL.md)
+and load its relative references only when needed. Preserve review/submission
+identity, per-message permissions and exact edit evidence. Use the generated
+commands and complete response template; retry the same response file/requestId,
+never source edits after uncertain acceptance.
 
-Without \`--timeout\`, the CLI defaults to a 12-hour cutoff. An explicit
-\`--timeout\` is one end-to-end deadline, including server discovery and reconnect
-attempts. Keep using the bounded foreground \`--timeout 600\` loop above;
-those polls do not wait 12 hours.
-
-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_COMMAND} 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. For non-truncated edits,
-\`after\` is their exact wording: carry it across verbatim and never revert it.
-If the HTML was generated from MDX or Markdown, apply complete edits to the
-source too.
-
-Edit fields are limited to 200,000 Unicode code points each. An edit with
-\`truncated: true\` identifies clipped fields in the \`truncated_fields\` array.
-Never apply incomplete text or HTML as a complete replacement or invent missing
-text. Recover the full edit only from an authoritative source; otherwise ask the
-user for the complete edit. Do not acknowledge the batch until every item,
-including truncated edits, has been handled.
-
-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.
-`;
+The skill and references are installed together by doc-review setup.`;
 export function installSkills(cwd, { global: isGlobal = false, home = os.homedir(), command } = {}) {
     const done = [];
     const cmd = command || invocation();
@@ -102,7 +66,7 @@ export function installSkills(cwd, { global: isGlobal = false, home = os.homedir
         if (!Buffer.from(existing, "utf8").equals(bytes)) {
             throw new Error("AGENTS.md is not valid UTF-8; convert it before re-running setup. No setup files were changed.");
         }
-        guidance = updateGuidance(existing, CODEX_BLOCK.replaceAll(NPX_COMMAND, cmd));
+        guidance = updateGuidance(existing, codexBlock().replaceAll(NPX_COMMAND, cmd));
     }
     const skillRoots = isGlobal
         ? [
@@ -110,11 +74,16 @@ export function installSkills(cwd, { global: isGlobal = false, home = os.homedir
             ["Codex", path.join(home, ".codex")],
             ["Shared agents", path.join(home, ".agents")],
         ]
-        : [["Claude Code", path.join(cwd, ".claude")]];
+        : [["Claude Code", path.join(cwd, ".claude")], ["Shared agents", path.join(cwd, ".agents")]];
     for (const [agent, base] of skillRoots) {
         const skillFile = path.join(base, "skills", "doc-review", "SKILL.md");
         fs.mkdirSync(path.dirname(skillFile), { recursive: true });
         fs.writeFileSync(skillFile, skillFor(cmd));
+        const refs = path.join(path.dirname(skillFile), "references");
+        fs.mkdirSync(refs, { recursive: true });
+        for (const name of fs.readdirSync(path.join(here, "references"))) {
+            fs.writeFileSync(path.join(refs, name), fs.readFileSync(path.join(here, "references", name), "utf8").replaceAll(NPX_COMMAND, cmd));
+        }
         done.push(`${agent} skill  ${skillFile}${isGlobal ? "   (all projects)" : ""}`);
     }
     if (!isGlobal) {

package/lib/state.js

@@ -8,12 +8,14 @@ import { atomicWrite } from "./atomic-write.js";
 import { RevisionStore } from "./revision-store.js";
 import { CAPTURE_LEASE_MS, HISTORY_SCHEMA_VERSION, normalizeHistoryTargets, revisionError } from "./revision-schema.js";
 import { historyRevisionReferences, retainHistory } from "./history-policy.js";
+import { Conversations, emptyConversations, validateConversations } from "./conversation-store.js";
+import { ContractError } from "./contracts/validation.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: {}, histories: {} });
+const emptyState = () => ({ schemaVersion: 1, conversations: emptyConversations(), pages: {}, batches: {}, receipts: {}, histories: {} });
 const historyId = (prefix) => `${prefix}_${crypto.randomBytes(12).toString("hex")}`;
 function historyRound(data, entryKey, roundId) {
     return data.histories[entryKey]?.rounds.find((round) => round.roundId === roundId) || null;
@@ -49,7 +51,8 @@ function finishCapture(round) {
 function pruneData(data, now = Date.now()) {
     let changed = retainHistory(data);
     for (const [key, page] of Object.entries(data.pages)) {
-        const protectedPage = page.comments?.length || page.edits?.length || page.revisionRefs?.length ||
+        const protectedPage = Object.values(data.conversations?.reviews || {}).some((record) => Object.hasOwn(record.pages, key)) ||
+            page.comments?.length || page.edits?.length || page.revisionRefs?.length ||
             data.batches[key] || Object.values(data.batches).some((record) => record.cleanup.some((item) => item.key === key)) ||
             Object.values(data.histories).some((history) => history.rounds.some((round) => round.targets.some((target) => target.key === key)));
         if (protectedPage)
@@ -72,10 +75,13 @@ function pruneData(data, now = Date.now()) {
     return changed;
 }
 function normalizeState(parsed, makeBatchId) {
+    validateConversations(parsed);
     if (!parsed || typeof parsed !== "object" || !parsed.pages || typeof parsed.pages !== "object") {
         throw new Error("Invalid doc-review state: expected a pages object.");
     }
     const data = {
+        schemaVersion: parsed.schemaVersion,
+        conversations: parsed.conversations,
         pages: parsed.pages,
         batches: parsed.batches && typeof parsed.batches === "object" ? parsed.batches : {},
         receipts: parsed.receipts && typeof parsed.receipts === "object" ? parsed.receipts : {},
@@ -163,12 +169,13 @@ function normalizeState(parsed, makeBatchId) {
  * means "your feedback is safe" stays true across server restarts.
  */
 export class Store {
-    constructor({ write = atomicWrite, makeBatchId = batchId, revisions = new RevisionStore() } = {}) {
+    constructor({ write = atomicWrite, makeBatchId = batchId, revisions = new RevisionStore(), writeSource = atomicWrite } = {}) {
         this.data = emptyState();
         this.write = write;
         this.makeBatchId = makeBatchId;
         this.revisions = revisions;
         this.load();
+        this.conversations = new Conversations(this, { writeSource });
     }
     load() {
         let parsed;
@@ -177,8 +184,10 @@ export class Store {
             parsed = JSON.parse(raw);
         }
         catch (err) {
-            if (err.code === "ENOENT")
+            if (err.code === "ENOENT") {
+                this.persist(this.data);
                 return this.data;
+            }
             throw err;
         }
         const normalized = normalizeState(parsed, this.makeBatchId);
@@ -189,8 +198,13 @@ export class Store {
         return this.data;
     }
     persist(data) {
-        ensureStateDir();
-        this.write(statePath(), JSON.stringify(data, null, 2));
+        try {
+            ensureStateDir();
+            this.write(statePath(), JSON.stringify(data, null, 2));
+        }
+        catch (error) {
+            throw new ContractError("STATE_PERSIST_FAILED", `State was not accepted: ${error.message}. Source writes, if any, must be reconciled separately.`);
+        }
     }
     /** Replace durable state once, then publish the committed draft in memory. */
     transaction(mutator) {
@@ -202,7 +216,7 @@ export class Store {
         pruneData(draft);
         this.persist(draft);
         this.data = draft;
-        return result;
+        return structuredClone(result);
     }
     /** Persist deliberate direct changes used by maintenance and tests. */
     save() {

package/lib/thread-anchor-controller.js

@@ -0,0 +1,56 @@
+import { frameAnchorsSchema, sameFrameAnchorProjection, validateFrameAnchorStates, validateFrameThreadAction, } from "./contracts/frame.js";
+import { reject } from "./contracts/validation.js";
+/** Frame-local metadata only. The shell separately validates every report/action. */
+export function createThreadAnchorController(options) {
+    let projection = null;
+    let signature = "";
+    function measure(current) {
+        return validateFrameAnchorStates({
+            ...current, type: "eh:threadAnchorStates",
+            anchors: current.anchors.map(options.resolve),
+        }, current);
+    }
+    function publish(states) {
+        options.reconcile?.(projection, states);
+        const next = JSON.stringify(states);
+        if (signature !== next) {
+            options.changed(projection, states);
+            signature = next;
+        }
+        return states;
+    }
+    function refresh() {
+        return projection ? publish(measure(projection)) : null;
+    }
+    return {
+        get projection() { return projection; },
+        refresh,
+        project(input) {
+            const next = frameAnchorsSchema.parse(input);
+            if (next.capability !== options.channel.capability || next.generation !== options.channel.generation ||
+                next.pageKey !== options.channel.pageKey || (projection &&
+                (next.reviewId !== projection.reviewId || next.renderId !== projection.renderId))) {
+                reject("SCOPE_MISMATCH", "Projection does not belong to this bound frame.");
+            }
+            if (projection && (next.projectionRevision < projection.projectionRevision ||
+                (next.projectionRevision === projection.projectionRevision && !sameFrameAnchorProjection(next, projection)))) {
+                reject("SCOPE_MISMATCH", "Stale or reused anchor projection revision.");
+            }
+            const states = measure(next);
+            projection = next;
+            signature = "";
+            return publish(states);
+        },
+        action(input) {
+            if (!projection)
+                return reject("SCOPE_MISMATCH", "No current thread projection.");
+            const action = validateFrameThreadAction(input, projection);
+            if (action.action !== "dismiss") {
+                const state = refresh().anchors.find((anchor) => anchor.threadId === action.threadId);
+                if (state?.state !== "found")
+                    reject("INVALID_INPUT", "Target is not currently available; use Feedback.");
+            }
+            return action;
+        },
+    };
+}

package/lib/toolbar-controller.js

@@ -23,9 +23,9 @@ export function createToolbarController(read, commands) {
                 if (!state.ended && !state.comparing)
                     commands.openComments();
             },
-            toggleTheme() {
-                if (!read().ended)
-                    commands.toggleTheme();
+            setTheme(theme) {
+                if (!read().ended && read().theme !== theme)
+                    commands.setTheme(theme);
             },
         },
     };

package/lib/ui/THIRD_PARTY_NOTICES.md

@@ -142,6 +142,30 @@ 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.
 
+## @radix-ui/react-checkbox - 1.3.11 (MIT)
+
+MIT License
+
+Copyright (c) 2022 WorkOS
+
+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.
+
 ## @radix-ui/react-collection - 1.1.15 (MIT)
 
 MIT License
@@ -382,7 +406,7 @@ 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.
 
-## @radix-ui/react-label - 2.1.15 (MIT)
+## @radix-ui/react-menu - 2.1.24 (MIT)
 
 MIT License
 
@@ -406,7 +430,7 @@ 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.
 
-## @radix-ui/react-menu - 2.1.24 (MIT)
+## @radix-ui/react-popper - 1.3.7 (MIT)
 
 MIT License
 
@@ -430,7 +454,7 @@ 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.
 
-## @radix-ui/react-popper - 1.3.7 (MIT)
+## @radix-ui/react-portal - 1.1.17 (MIT)
 
 MIT License
 
@@ -454,7 +478,7 @@ 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.
 
-## @radix-ui/react-portal - 1.1.17 (MIT)
+## @radix-ui/react-presence - 1.1.10 (MIT)
 
 MIT License
 
@@ -478,7 +502,7 @@ 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.
 
-## @radix-ui/react-presence - 1.1.10 (MIT)
+## @radix-ui/react-primitive - 2.1.10 (MIT)
 
 MIT License
 
@@ -502,7 +526,7 @@ 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.
 
-## @radix-ui/react-primitive - 2.1.10 (MIT)
+## @radix-ui/react-roving-focus - 1.1.19 (MIT)
 
 MIT License
 
@@ -526,7 +550,7 @@ 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.
 
-## @radix-ui/react-roving-focus - 1.1.19 (MIT)
+## @radix-ui/react-slot - 1.3.3 (MIT)
 
 MIT License
 
@@ -550,7 +574,31 @@ 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.
 
-## @radix-ui/react-slot - 1.3.3 (MIT)
+## @radix-ui/react-toast - 1.2.23 (MIT)
+
+MIT License
+
+Copyright (c) 2022 WorkOS
+
+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.
+
+## @radix-ui/react-tooltip - 1.2.16 (MIT)
 
 MIT License
 
@@ -718,6 +766,30 @@ 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.
 
+## @radix-ui/react-visually-hidden - 1.2.11 (MIT)
+
+MIT License
+
+Copyright (c) 2022 WorkOS
+
+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.
+
 ## aria-hidden - 1.2.6 (MIT)
 
 MIT License
@@ -971,6 +1043,53 @@ 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.
 
+## marked - 18.0.12 (MIT)
+
+# License information
+
+## Contribution License Agreement
+
+If you contribute code to this project, you are implicitly allowing your code
+to be distributed under the MIT license. You are also implicitly verifying that
+all code is your original work. `</legalese>`
+
+## Marked
+
+Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
+Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
+
+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.
+
+## Markdown
+
+Copyright © 2004, John Gruber
+http://daringfireball.net/
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
+
 ## react-dom - 19.3.0 (MIT)
 
 MIT License