agentic-comments 0.6.1 → 0.8.0

package/README.md

@@ -86,6 +86,36 @@ erased message or a thread that holds one.
 Replicas that edit one message at once leave a copy each. When the copies agree on the author kind and time,
 the read keeps the erased copy, or else the latest edit. An edit and a delete made at once keep the edit.
 
+## Account export and erase
+
+`import { commentsAccount } from "agentic-comments/account"` lets a host export and erase one person's data
+without reading the storage layout. Pass the subject (`{ kind, name }`) and `{ documents, actor }`. Each
+document is `{ id, comments, suggestions }`. The actor is made with `stamp()` and must name the subject.
+`exportAccount` returns JSON records in `messages`, `statusChanges`, `edits`, `suggestions`, `decisions`,
+`documents`, and `unread`. `eraseAccount` tombstones the same data as `erasePerson` and returns counts. A second
+erase counts 0, except `unread`: see below.
+
+The package keeps no grants or audit rows. A host that runs the HTTP worker passes `worker: docs` (the
+`CommentsDocs` of the worker). Then the run also covers every stored document: the subject's messages and
+suggestions in it, and the creator that the worker keeps on each row. The creators are listed under `documents`
+and get the tombstone name on erase. Without `worker`, that data stays. A stored document is erased in one
+transaction. A stored document that `documents` also lists is refused, before any write. The check compares ids
+only. A row whose creator cannot be read shows in `unread` of the export, and in the `unread` count of the erase,
+which leaves the row in place. `unread` counts every row it cannot read, whoever made it, so it can stay above 0 on a repeat. A store that loses a race gives `CONFLICT`: run the erase again.
+
+A run covers only the subject's own kind: `human:ada` does not reach `agent_of_human:ada`. Names and mentions of
+the subject inside other people's messages are neither exported nor erased. Records can name other people, such
+as the moderator in `editedBy` or the person in `decidedBy`. A record in `unread` means the export is not
+complete: the store holds entries of the subject that a read cannot show. A missing `documents` list is an
+error, not an empty run. Erase goes document by document. If one fails, the error code tells why, the message names the document when the store allows, and the earlier
+documents stay erased. A failed document in `documents` may be partly erased (its threads and its suggestions
+are two steps). A repeat counts only what is left. The counts of a failed run are lost.
+
+The ids in `documents` and the ids of the worker share one namespace. Erase can make a state a little larger, so a stored
+document near the size limit may stop the run with `STORE_FULL`: the host must shrink or delete that document, and
+run the erase again. The run reads the list of stored documents once. Block the subject before the erase, so no
+document is made during it. A repeat erase finishes what a race left.
+
 ## Anchors for plain text
 
 `agentic-comments/anchor` pins a range of a plain string. It needs no Yjs and no framework.
@@ -321,12 +351,42 @@ try {
 - The client never follows a redirect and never retries. A write that you abort after the client sends it can still apply:
   read the thread before you try again.
 
+## React panel
+
+`agentic-comments/ui` is a threaded comments panel for a React page. It shows the thread list, the quote each thread
+points at, a reply box, resolve and reopen, and an author mark on every message. A person shows a name. An agent
+shows the `AgentBadge` of `agentic-design`, with the words "Comment by an agent". Each suggestion has Accept and
+Reject buttons. React 19 and `react-dom` are peer dependencies. The package depends on `agentic-design`.
+
+```tsx
+import { CommentsPanel, createClient } from "agentic-comments/ui";
+import "agentic-design/styles.css";
+import "agentic-comments/ui.css";
+
+const client = createClient({ baseUrl: "https://comments.example.com", token });
+<CommentsPanel client={client} docId="report-q3" />;
+```
+
+`client` is any object with the methods of `PanelClient`, so a host can pass its own. The panel reads who is signed
+in from `client.me()`. It follows the product rule for suggestions: an agent never gets Accept or Reject for its own
+suggestion. Through the Worker, an agent needs the `comments:admin` scope to decide any suggestion. With a client of your own, the `comments:accept` right is enough too. A person who holds
+`comments:write` decides any suggestion. `mayDecide(me, suggestion)` is exported, so a host can use the same rule.
+A hidden button is a help and not a lock: the Worker checks every call. The panel shows an error with its code, and
+it never retries a call with other input. It needs a document whose text holds the quote, because a new thread
+points at a quote. It meets WCAG 2.2 AA (axe runs on light, dark, and 390px) and its classes all start with `agd-`.
+
+The demo page in `ui/` runs the panel with no token on in-memory data, with a switch for the signed-in principal. Open
+`/#token=<bearer>&doc=<id>` on a Worker that serves it, and it talks to that Worker. `npm run test:ui` drives it in
+Chromium against `wrangler dev`.
+
+![The panel in the light theme](docs/screenshots/panel-light.png)
+
 ## Live demo
 
 A demo Worker runs at <https://agentic-comments-demo.hello-fd1.workers.dev>. It is a staging site. Check it with
 `GET /health`. Every `/api/v1` route needs a bearer token, and the demo does not publish one, so a call
 with no token gets `401`. The data lives in a D1 database in the EU (`weur`), and the Worker sets the
-region to `eu`.
+region to `eu`. The panel demo page is at the root of the demo Worker.
 
 To deploy your own copy, log in with `wrangler login` or set `CLOUDFLARE_API_TOKEN`, then:
 
@@ -436,13 +496,29 @@ const stop = notifications.subscribe(async (event) => {
 - Mentions are stored in lowercase, with no leading `@`. A handle holds up to 64 letters, digits, marks,
   and `. _ -`. A longer handle in a body is refused.
 
+## Run locally
+
+```sh
+git clone https://github.com/pooriaarab/agentic-comments
+cd agentic-comments
+npm install && npm run dev
+```
+
+You can also use `bun install && bun run dev`. The `dev` script calls npm, so npm must be installed. The scripts need macOS, Linux, or WSL. The `dev` script builds the package, then starts `wrangler dev` on <http://localhost:8794>. Wrangler keeps a local D1 database. The `dev` script turns off Wrangler telemetry. Set `WRANGLER_SEND_METRICS=false` when you run other wrangler commands.
+
+```sh
+curl -i http://localhost:8794/health   # 200
+```
+
+`npm run dev:smoke` runs the same check by itself. It starts the dev server. It waits for `/health` to answer 200. It stops the server. CI runs it as the "dev smoke" step. To use another port, change `8794` in the `dev` and `dev:smoke` scripts.
+
 ## Develop
 
 ```sh
 git clone https://github.com/pooriaarab/agentic-comments
 cd agentic-comments
 npm ci
-npm run ci:local
+npm run ci:local   # build, typecheck, unit tests, then the browser tests (npx playwright install chromium once)
 ```
 
 ## License

package/SKILL.md

@@ -32,6 +32,11 @@ anyone's with that scope). Check `unread` in an export.
 Over MCP, call `list_threads`, `add_comment`, `reply_to_thread`, `resolve_thread`, `suggest_change`,
 `accept_suggestion`, `reject_suggestion`, and the tools above. You never pass an author or a scope.
 
+## Show threads in a React page
+
+`import { CommentsPanel, createClient } from "agentic-comments/ui"` and load `agentic-design/styles.css` and `agentic-comments/ui.css`.
+`<CommentsPanel client={createClient({ baseUrl, token })} docId="..." />`. The panel never offers an agent Accept or Reject for its own suggestion.
+
 ## Rules
 
 - The host stamps the author. Never call `stamp()` yourself, and never pass an author in an input.

package/dist/account.d.ts

@@ -0,0 +1,62 @@
+import { C as Comments, c as Suggestions, b as Author, A as Actor } from './suggestions-G1seGf5d.js';
+import 'yjs';
+import 'agentic-identity';
+
+/** One document the host holds comments on. The host loads it; the package never lists documents. */
+interface CommentsAccountDocument {
+    /** A stable id for the document. It goes in each exported record. */
+    id: string;
+    comments: Comments;
+    suggestions: Suggestions;
+}
+/** What `CommentsDocs` offers the plug-in. */
+interface AccountWorker {
+    /** The id of each stored document. */
+    accountDocumentIds(): Promise<string[]>;
+    /** Runs `fn` on each stored document. With `save`, the state is written back in the same transaction. A document deleted meanwhile is skipped. `committed` is called with the id after its transaction commits. */
+    eachAccountDocument(fn: (doc: CommentsAccountDocument) => void, save: boolean, committed?: (id: string) => void): Promise<void>;
+    /** The documents the subject created. `unread` names the rows whose creator cannot be read, so the export is not complete for them. */
+    exportCreated(author: Author): Promise<{
+        documents: {
+            documentId: string;
+            createdAt: unknown;
+        }[];
+        unread: string[];
+    }>;
+    /** `count` is the creators it tombstoned. `unread` names the rows whose creator cannot be read, which it leaves in place. */
+    eraseCreated(author: Author): Promise<{
+        count: number;
+        unread: string[];
+    }>;
+}
+interface CommentsAccountDeps {
+    /** Every document that may hold data of the subject. */
+    documents: Iterable<CommentsAccountDocument>;
+    /** Made with `stamp()`. It must name the subject: the same kind and name. A moderate scope does not widen the run. */
+    actor: Actor;
+    /**
+     * The document store of the HTTP worker (`CommentsDocs`), when the host runs it. Its rows hold the threads of each
+     * document and the creator of each document, outside what `documents` can reach. Pass it, and the run covers every
+     * stored document. Without it, a worker host leaves that data in place.
+     */
+    worker?: AccountWorker;
+}
+type JsonRecord = Record<string, unknown>;
+interface CommentsAccount {
+    id: "comments";
+    /**
+     * Collections, each record tagged with `documentId`: `messages` (with the thread anchor), `statusChanges`,
+     * `edits` (the subject's edits of other people's messages), `suggestions` (the ones the subject wrote),
+     * `decisions` (accepts and rejects by the subject), `documents` (the worker documents the subject created, only
+     * when `deps.worker` is set), and `unread` (stored entries of the subject that a read
+     * cannot show; the export is not complete when this has a record). The package keeps no grants or audit rows. Its
+     * one owner-like record is the creator of a worker document, which `deps.worker` covers. A host that runs the
+     * worker and omits `worker` leaves that creator in place.
+     */
+    exportAccount(subject: Author, deps: CommentsAccountDeps): Promise<Record<"messages" | "statusChanges" | "edits" | "suggestions" | "decisions" | "documents" | "unread", JsonRecord[]>>;
+    /** Replaces what the subject wrote with a tombstone (see `Comments.erasePerson`). Counts by kind, summed over documents. The thread shape stays. A repeat finds nothing and counts 0. A decision that the subject made on their own suggestion is deleted and not counted, while `unread` in the export counts it. */
+    eraseAccount(subject: Author, deps: CommentsAccountDeps): Promise<Record<"messages" | "statuses" | "edits" | "suggestions" | "decisions" | "documents" | "unread", number>>;
+}
+declare const commentsAccount: CommentsAccount;
+
+export { type AccountWorker, type CommentsAccount, type CommentsAccountDeps, type CommentsAccountDocument, commentsAccount };

package/dist/account.js

@@ -0,0 +1,114 @@
+import {
+  Actor,
+  Comments,
+  CommentsError,
+  Suggestions,
+  assertActor,
+  readAuthor,
+  shown
+} from "./chunk-4G5BDTBA.js";
+
+// src/account.ts
+import { StoreConflictError } from "agentic-identity";
+var plain = (value) => JSON.parse(JSON.stringify(value));
+function check(subject, deps) {
+  const who = readAuthor(subject);
+  if (!who) throw new CommentsError("INVALID_INPUT", "subject needs a known kind and a name");
+  const actor = assertActor(deps?.actor);
+  if (actor.kind !== who.kind || actor.name !== who.name) throw new CommentsError("FORBIDDEN", "actor does not match the subject");
+  if (typeof deps?.documents?.[Symbol.iterator] !== "function") throw new CommentsError("INVALID_INPUT", "deps.documents must be a list of documents");
+  const documents = [...deps.documents];
+  const ids = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const bad = (why) => {
+    throw new CommentsError("INVALID_INPUT", `deps: ${why}`);
+  };
+  if (deps.worker !== void 0 && ["accountDocumentIds", "eachAccountDocument", "exportCreated", "eraseCreated"].some((m) => typeof deps.worker?.[m] !== "function")) bad("worker needs accountDocumentIds, eachAccountDocument, exportCreated, and eraseCreated");
+  for (const d of documents) {
+    if (typeof d?.id !== "string" || d.id === "" || ids.has(d.id)) bad("each document needs a unique id");
+    if (!(d.comments instanceof Comments) || !(d.suggestions instanceof Suggestions)) bad("each document needs Comments and Suggestions made by this package");
+    if (d.suggestions.comments.ydoc !== d.comments.ydoc) bad("suggestions must be made on the same comments");
+    if (seen.has(d.comments.ydoc)) bad("two documents share one Yjs document");
+    ids.add(d.id);
+    seen.add(d.comments.ydoc);
+  }
+  return { documents, own: Actor.of(who) };
+}
+function collect({ id: documentId, comments, suggestions }, own, out) {
+  const c = comments.exportPerson(own.name, own);
+  const s = suggestions.exportPerson(own.name, own);
+  for (const t of c.threads) {
+    for (const message of t.messages) out.messages.push({ ...message, documentId, threadId: t.threadId, anchor: t.anchor });
+    if (t.statusChange) out.statusChanges.push({ ...t.statusChange, documentId, threadId: t.threadId });
+  }
+  for (const e of c.edits) out.edits.push({ ...e, documentId });
+  for (const x of s.authored) out.suggestions.push({ ...x, documentId });
+  for (const d of s.decided) out.decisions.push({ documentId, suggestionId: d.id, status: d.status, at: d.at });
+  const unread = c.unread + s.unread;
+  if (unread > 0) out.unread.push({ documentId, count: unread });
+}
+async function stopAt(where, run) {
+  try {
+    return await run();
+  } catch (cause) {
+    const known = cause instanceof CommentsError;
+    const reason = cause instanceof Error ? cause.message : "unknown error";
+    if (!known && !(cause instanceof StoreConflictError)) throw cause;
+    throw new CommentsError(known ? cause.code : "CONFLICT", `erase stopped at ${where}: ${reason}`, { cause });
+  }
+}
+async function refuseOverlap(documents, worker) {
+  const listed = new Set(documents.map((d) => d.id));
+  if ((await worker.accountDocumentIds()).some((id) => listed.has(id))) throw new CommentsError("INVALID_INPUT", "deps.worker holds a document that deps.documents also lists");
+}
+function wipe({ comments, suggestions }, own, counts) {
+  const c = comments.erasePerson(own.name, own);
+  const s = suggestions.erasePerson(own.name, own);
+  counts.messages += c.messages;
+  counts.statuses += c.statuses;
+  counts.edits += c.edits;
+  counts.suggestions += s.suggestions;
+  counts.decisions += s.decisions;
+}
+var commentsAccount = {
+  id: "comments",
+  async exportAccount(subject, deps) {
+    const { documents, own } = check(subject, deps);
+    const out = { messages: [], statusChanges: [], edits: [], suggestions: [], decisions: [], documents: [], unread: [] };
+    if (deps.worker) await refuseOverlap(documents, deps.worker);
+    for (const doc of documents) collect(doc, own, out);
+    if (deps.worker) {
+      await deps.worker.eachAccountDocument((doc) => collect(doc, own, out), false);
+      const created = await deps.worker.exportCreated(own);
+      out.documents.push(...created.documents);
+      for (const documentId of created.unread) out.unread.push({ documentId, count: 1 });
+    }
+    return plain(out);
+  },
+  async eraseAccount(subject, deps) {
+    const { documents, own } = check(subject, deps);
+    if (deps.worker) await refuseOverlap(documents, deps.worker);
+    const counts = { messages: 0, statuses: 0, edits: 0, suggestions: 0, decisions: 0, documents: 0, unread: 0 };
+    for (const doc of documents) await stopAt(`document ${shown(doc.id)}`, () => wipe(doc, own, counts));
+    if (deps.worker) {
+      const each = /* @__PURE__ */ new Map();
+      const done = /* @__PURE__ */ new Set();
+      await stopAt(
+        "a worker document",
+        () => deps.worker.eachAccountDocument((doc) => {
+          const one = { messages: 0, statuses: 0, edits: 0, suggestions: 0, decisions: 0, documents: 0, unread: 0 };
+          wipe(doc, own, one);
+          each.set(doc.id, one);
+        }, true, (id) => void done.add(id))
+      );
+      for (const [id, c] of each) if (done.has(id)) for (const k of Object.keys(counts)) counts[k] += c[k];
+      const creators = await stopAt("the worker creators", () => deps.worker.eraseCreated(own));
+      counts.documents = creators.count;
+      counts.unread = creators.unread.length;
+    }
+    return counts;
+  }
+};
+export {
+  commentsAccount
+};