agentic-comments 0.1.0 → 0.3.0

package/dist/worker.js

@@ -0,0 +1,287 @@
+import {
+  CommentsService,
+  TEXT_ROOT
+} from "./chunk-IB6ANO32.js";
+import {
+  ACCEPT_SCOPE,
+  CommentsError,
+  PRINCIPAL_KINDS,
+  exact,
+  invalid,
+  stamp
+} from "./chunk-GSAJOCDV.js";
+
+// src/worker.ts
+import { Hono } from "hono";
+import { StoreConflictError, assertRegion, isScope, parseRegion, hasScope } from "agentic-identity";
+import { D1_SCHEMA, createD1Store } from "agentic-identity/cloudflare";
+import * as Y from "yjs";
+var READ = "comments:read";
+var COMMENT = "comments:comment";
+var WRITE = "comments:write";
+var ADMIN = "comments:admin";
+var DEFAULT_SCOPES = [COMMENT];
+var MIN_TOKEN_BYTES = 32;
+var warned = /* @__PURE__ */ new Set();
+function refuse(reason) {
+  if (!warned.has(reason)) {
+    warned.add(reason);
+    console.error(`AGENTIC_COMMENTS_TOKENS is refused: ${reason}`);
+  }
+  return void 0;
+}
+function same(a, b) {
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+function contextOf(entry) {
+  const object = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : void 0;
+  const who = typeof entry === "string" ? entry : object?.as;
+  const cut = typeof who === "string" ? who.indexOf(":") : -1;
+  if (typeof who !== "string" || cut < 1 || cut === who.length - 1) return void 0;
+  const kind = who.slice(0, cut);
+  const name = who.slice(cut + 1);
+  if (!PRINCIPAL_KINDS.includes(kind)) return void 0;
+  const given = object?.scopes;
+  if (given !== void 0 && !(Array.isArray(given) && given.every(isScope))) return void 0;
+  try {
+    stamp({ kind, name });
+  } catch {
+    return void 0;
+  }
+  return { principalId: name, kind, chain: [{ id: name, kind }], scopes: given ?? [...DEFAULT_SCOPES] };
+}
+function createTokenAuth(raw) {
+  let table;
+  try {
+    const parsed = JSON.parse(raw ?? "{}");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { authenticate: async () => (refuse("not a JSON object"), null) };
+    table = /* @__PURE__ */ new Map();
+    for (const [token, entry] of Object.entries(parsed)) {
+      const context = contextOf(entry);
+      if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) throw new Error(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+      if (!context) throw new Error("an entry is not a valid kind:name or { as, scopes }");
+      table.set(token, context);
+    }
+  } catch (error) {
+    table = void 0;
+    refuse(error instanceof SyntaxError ? "not valid JSON" : error.message);
+  }
+  const known = table;
+  return {
+    async authenticate(request) {
+      const bearer = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+      if (bearer === void 0 || !known) return null;
+      let found = null;
+      for (const [token, context] of known) if (same(token, bearer)) found = context;
+      return found;
+    }
+  };
+}
+function actorOf(context) {
+  const scopes = hasScope(context.scopes, ADMIN) ? [ACCEPT_SCOPE] : [];
+  return stamp({ kind: context.kind, name: context.principalId, scopes });
+}
+var DOCS = "comments_docs";
+var DOC_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var MAX_STATE = 6e5;
+var MAX_BODY = 256 * 1024;
+var toBase64 = (bytes) => {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 32768) out += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(out);
+};
+var fromBase64 = (text) => Uint8Array.from(atob(text), (ch) => ch.charCodeAt(0));
+var CommentsDocs = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  id(id) {
+    if (!DOC_ID.test(id)) invalid(`invalid document id "${id}": use 1 to 64 of a-z, 0-9, "-" and "_"`);
+    return id;
+  }
+  load(row, id) {
+    if (row === null) throw new CommentsError("NO_DOCUMENT", `no document with id "${id}"`);
+    const ydoc = new Y.Doc();
+    try {
+      if (typeof row.state !== "string") throw new Error("no state");
+      Y.applyUpdate(ydoc, fromBase64(row.state));
+    } catch {
+      throw new CommentsError("CORRUPT", `document "${id}" is damaged`);
+    }
+    return ydoc;
+  }
+  open(ydoc, actor) {
+    const fixed = { read: (fn) => fn(ydoc), write: (fn) => fn(ydoc) };
+    return new CommentsService(fixed, actor);
+  }
+  async create(id, text, actor) {
+    this.id(id);
+    const ydoc = new Y.Doc();
+    ydoc.getText(TEXT_ROOT).insert(0, text);
+    const state = Y.encodeStateAsUpdate(ydoc);
+    if (state.length > MAX_STATE) throw new CommentsError("STORE_FULL", `the text is too large for one document (${MAX_STATE} bytes of state)`);
+    await this.store.transaction(async (tx) => {
+      if (await tx.get(DOCS, id) !== null) throw new CommentsError("DOCUMENT_EXISTS", `document "${id}" already exists`);
+      await tx.put(DOCS, id, { state: toBase64(state), createdBy: { kind: actor.kind, name: actor.name }, createdAt: Date.now() });
+    });
+  }
+  async read(id, actor, run) {
+    return run(this.open(this.load(await this.store.get(DOCS, this.id(id)), id), actor));
+  }
+  async write(id, actor, run) {
+    this.id(id);
+    return this.store.transaction(async (tx) => {
+      const row = await tx.get(DOCS, id);
+      const ydoc = this.load(row, id);
+      const result = run(this.open(ydoc, actor));
+      const state = Y.encodeStateAsUpdate(ydoc);
+      if (state.length > MAX_STATE) throw new CommentsError("STORE_FULL", `document "${id}" would pass ${MAX_STATE} bytes of state`);
+      await tx.put(DOCS, id, { state: toBase64(state), createdBy: row?.createdBy ?? null, createdAt: row?.createdAt ?? null });
+      return result;
+    });
+  }
+};
+var STATUS = {
+  INVALID_AUTHOR: 400,
+  INVALID_INPUT: 400,
+  INVALID_ANCHOR: 400,
+  NO_THREAD: 404,
+  NO_SUGGESTION: 404,
+  NO_DOCUMENT: 404,
+  THREAD_RESOLVED: 409,
+  ALREADY_DECIDED: 409,
+  DOCUMENT_EXISTS: 409,
+  CONFLICT: 409,
+  APPLY_FAILED: 409,
+  RELOCATE_FAILED: 409,
+  FORBIDDEN: 403,
+  STORE_FULL: 413,
+  CORRUPT: 500,
+  MISCONFIGURED: 500
+};
+var fail = (code, message, status) => Response.json({ error: { code, message } }, { status });
+async function body(c) {
+  if (Number(c.req.header("content-length") ?? 0) > MAX_BODY) invalid(`the body is over ${MAX_BODY} bytes`);
+  const text = await c.req.text();
+  if (text.length > MAX_BODY) invalid(`the body is over ${MAX_BODY} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) invalid("the body must be a JSON object");
+  return parsed;
+}
+function createApp(source, options = {}) {
+  const app2 = new Hono();
+  const docsOf = (c) => typeof source === "function" ? source(c.env ?? {}) : Promise.resolve(source);
+  app2.use("*", async (c, next) => {
+    await next();
+    c.header("x-content-type-options", "nosniff");
+  });
+  app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-comments" }));
+  app2.use("/api/v1/*", async (c, next) => {
+    const auth = typeof options.auth === "function" ? options.auth(c.env ?? {}) : options.auth ?? createTokenAuth(c.env?.AGENTIC_COMMENTS_TOKENS);
+    const context = await auth.authenticate(c.req.raw);
+    if (!context) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
+    c.set("context", context);
+    await next();
+  });
+  app2.get("/api/v1/me", (c) => {
+    const { principalId, kind, scopes } = c.get("context");
+    return c.json({ kind, name: principalId, scopes });
+  });
+  const act = (c, need, write, run) => (async () => {
+    const context = c.get("context");
+    if (!hasScope(context.scopes, need)) throw new CommentsError("FORBIDDEN", `this token needs the ${need} scope`);
+    const docs = await docsOf(c);
+    const actor = actorOf(context);
+    const id = c.req.param("doc") ?? "";
+    return c.json(await (write ? docs.write(id, actor, run) : docs.read(id, actor, run)));
+  })();
+  const doc = "/api/v1/docs/:doc";
+  app2.post("/api/v1/docs", async (c) => {
+    const given = exact(await body(c), ["id", "text"], "a document");
+    if (typeof given.id !== "string") invalid("a document needs an id");
+    if (given.text !== void 0 && typeof given.text !== "string") invalid("text must be a string");
+    const context = c.get("context");
+    if (!hasScope(context.scopes, WRITE)) throw new CommentsError("FORBIDDEN", `this token needs the ${WRITE} scope`);
+    await (await docsOf(c)).create(given.id, given.text ?? "", actorOf(context));
+    return c.json({ id: given.id }, 201);
+  });
+  app2.get(doc, (c) => act(c, READ, false, (s) => ({ id: c.req.param("doc"), text: s.text() })));
+  app2.get(`${doc}/threads`, (c) => act(c, READ, false, (s) => s.threads(c.req.query())));
+  app2.get(`${doc}/threads/:id`, (c) => act(c, READ, false, (s) => s.thread(c.req.param("id"))));
+  app2.post(`${doc}/threads`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.comment(input));
+  });
+  app2.post(`${doc}/threads/:id/replies`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.reply(c.req.param("id"), input));
+  });
+  for (const action of ["resolve", "reopen"]) {
+    app2.post(`${doc}/threads/:id/${action}`, (c) => act(c, COMMENT, true, (s) => s[action](c.req.param("id"))));
+  }
+  app2.post(`${doc}/threads/:id/relocate`, (c) => act(c, WRITE, true, (s) => s.relocate(c.req.param("id"))));
+  app2.get(`${doc}/suggestions`, (c) => act(c, READ, false, (s) => s.suggestions(c.req.query())));
+  app2.post(`${doc}/suggestions`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.suggest(input));
+  });
+  for (const action of ["accept", "reject"]) {
+    app2.post(`${doc}/suggestions/:id/${action}`, (c) => act(c, WRITE, true, (s) => s[action](c.req.param("id"))));
+  }
+  app2.notFound(() => fail("NOT_FOUND", "no such route", 404));
+  app2.onError((error) => {
+    if (error instanceof CommentsError) return fail(error.code, error.message, STATUS[error.code] ?? 400);
+    if (error instanceof StoreConflictError) return fail("CONFLICT", "the document kept changing; try again", 409);
+    console.error(error instanceof Error ? error.name : "error");
+    return fail("INTERNAL", "the server could not finish the request", 500);
+  });
+  return app2;
+}
+var schemas = /* @__PURE__ */ new WeakMap();
+function regionOf(env) {
+  let region;
+  try {
+    region = parseRegion(env.AGENTIC_COMMENTS_REGION);
+  } catch {
+    throw new CommentsError("MISCONFIGURED", 'set AGENTIC_COMMENTS_REGION to "eu" or "us" ("unknown" only for local development)');
+  }
+  if (region === "unknown" && env.AGENTIC_COMMENTS_UNSAFE_REGION !== "1") {
+    throw new CommentsError("MISCONFIGURED", 'the region "unknown" turns the residency check off; set AGENTIC_COMMENTS_UNSAFE_REGION=1 to accept that for local development');
+  }
+  return region;
+}
+async function docsFor(env) {
+  if (!env.DB) throw new CommentsError("MISCONFIGURED", "bind a D1 database as DB");
+  const region = regionOf(env);
+  const db = env.DB;
+  let ready = schemas.get(db);
+  if (!ready) {
+    ready = db.prepare(D1_SCHEMA).run().catch((error) => {
+      schemas.delete(db);
+      throw error;
+    });
+    schemas.set(db, ready);
+  }
+  await ready;
+  const store = createD1Store(db, { region });
+  assertRegion(region, store);
+  return new CommentsDocs(store);
+}
+var app = createApp(docsFor);
+var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+export {
+  CommentsDocs,
+  createApp,
+  createTokenAuth,
+  worker_default as default,
+  docsFor,
+  regionOf
+};

package/llms.txt

@@ -6,7 +6,8 @@ Keywords: comments,threads,mentions,suggestions,annotations,collaboration,agents
 
 - SDK: import { Comments, Suggestions, textAnchor } from "agentic-comments". The host calls stamp(); an agent never does.
 - Threads live on a Yjs document and merge across replicas.
-- The CLI and MCP server are not built yet.
+- Events: new Notifications(comments, suggestions).subscribe(listener). Ids only, never text.
+- CLI: agentic-comments <command>. MCP: agentic-comments mcp. Both use a local store file.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -10,7 +10,8 @@
     "annotations",
     "collaboration",
     "agents",
-    "yjs"
+    "yjs",
+    "mcp"
   ],
   "license": "MIT",
   "author": "Pooria Arab",
@@ -25,7 +26,7 @@
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "files": [
     "dist",
@@ -35,28 +36,51 @@
   "publishConfig": {
     "access": "public"
   },
+  "mcpName": "io.github.pooriaarab/agentic-comments",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "import": "./dist/local.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
     }
   },
+  "bin": {
+    "agentic-comments": "./dist/cli.js",
+    "agentic-comments-mcp": "./dist/mcp-bin.js"
+  },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "deploy:demo": "npm run build && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.demo.jsonc",
     "clean": "rm -rf dist",
+    "prepack": "npm run build",
     "ci:local": "npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "agentic-identity": "^0.4.0",
+    "hono": "^4.13.14",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
     "yjs": "^13.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "wrangler": "^4.155.0",
+    "yjs": "^13.6.0"
   }
 }