agentic-documents 0.0.0-stage → 0.1.0

package/dist/service-eYISo6-b.d.ts

@@ -0,0 +1,159 @@
+import * as Y from 'yjs';
+import { Blobs, Store } from 'agentic-identity';
+
+/** A ProseMirror node in JSON form, the shape y-prosemirror reads and writes. */
+interface PmNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: PmNode[];
+    text?: string;
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+}
+/** Parse GitHub-flavored Markdown into top-level ProseMirror blocks. */
+declare function markdownToBlocks(markdown: string): PmNode[];
+/** Serialize top-level ProseMirror blocks to GitHub-flavored Markdown. */
+declare function blocksToMarkdown(nodes: PmNode[]): string;
+
+declare const PRINCIPAL_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
+/** Who made a change. Every mutation needs one, so machine-made work stays labeled. */
+interface Principal {
+    kind: PrincipalKind;
+    name: string;
+    /** Rights this principal was granted, such as `docs:accept`. Used to decide, never stored in the doc. */
+    scopes?: string[];
+}
+/** A text range that follows its text through concurrent edits. */
+interface Anchor {
+    text: string;
+    start: Record<string, unknown>;
+    end: Record<string, unknown>;
+}
+type TextTarget = {
+    text: string;
+    occurrence?: number;
+    at?: "before" | "after";
+};
+type AnchorTarget = {
+    anchor: Anchor;
+    at?: "before" | "after";
+};
+type SectionTarget = {
+    section: string;
+    at?: "start" | "end";
+};
+type Target = TextTarget | AnchorTarget | SectionTarget;
+interface Section {
+    id: string;
+    level: number;
+    title: string;
+}
+interface EditEntry {
+    op: "create" | "append" | "insert" | "replace" | "delete";
+    at: string;
+    author: Principal;
+    /** Counts of characters (text targets) or blocks (section targets). Never content. */
+    inserted: number;
+    deleted: number;
+    section?: string;
+    /** Set when an accepted suggestion caused the edit. `author` is who suggested it. */
+    suggestion?: {
+        id: string;
+        author: Principal;
+    };
+}
+/** When the edit was logged, and where it put new text (relative positions that follow the text). */
+interface EditResult {
+    at: string;
+    inserted?: {
+        start: Record<string, unknown>;
+        end: Record<string, unknown>;
+    };
+}
+interface DocOptions {
+    now?: () => Date;
+}
+type Range = {
+    unit: Y.XmlText;
+    start: number;
+    end: number;
+};
+/** `kind:name`, for example `agent_of_human:scribe`. Validation happens when a change needs it. */
+declare function parseAuthor(value: string | undefined): Principal | undefined;
+declare class AgenticDoc {
+    readonly ydoc: Y.Doc;
+    readonly now: () => Date;
+    constructor(ydoc?: Y.Doc, options?: DocOptions);
+    static fromMarkdown(markdown: string, author: Principal, options?: DocOptions): AgenticDoc;
+    static fromUpdate(update: Uint8Array, options?: DocOptions): AgenticDoc;
+    encode(): Uint8Array;
+    applyUpdate(update: Uint8Array): void;
+    /** A new replica with its own client id, holding the same state. */
+    fork(): AgenticDoc;
+    private get fragment();
+    private get log();
+    edits(): EditEntry[];
+    private change;
+    toJSON(): PmNode;
+    toMarkdown(): string;
+    /** Sections in order. Blocks before the first heading come first, as the `preamble` section at level 0. */
+    outline(): Section[];
+    readSection(id: string): string;
+    private headings;
+    /**
+     * A section runs from its heading to the next heading of the same or a higher level. The preamble
+     * has no heading and runs to the first heading. It is always a valid target, even when empty.
+     */
+    private range;
+    private find;
+    private pick;
+    /** Pin a text range so later edits by other replicas do not move it. */
+    anchor(text: string, occurrence?: number): Anchor;
+    resolve(target: TextTarget | AnchorTarget): Range;
+    edit(op: "insert" | "replace" | "delete", target: TextTarget | AnchorTarget, content: string, author: Principal, extra?: Pick<EditEntry, "suggestion">): EditResult;
+    private editSection;
+    /** Insert Markdown into a section, or plain text next to matched text. */
+    insert(target: Target, content: string, author: Principal): void;
+    /** Replace a section body (the heading stays), or the matched text. */
+    replace(target: Target, content: string, author: Principal): void;
+    /** Delete a whole section with its subsections, or the matched text. */
+    delete(target: Target, author: Principal): void;
+    append(markdown: string, author: Principal): void;
+}
+
+/** What the catalog keeps for each document. The author kind stays, so machine-made work stays labeled. */
+interface DocInfo {
+    createdBy: {
+        kind: PrincipalKind;
+        name: string;
+    };
+    createdAt: number;
+}
+interface DocsPorts {
+    /** Holds each document as a Yjs update. Saves are conditional on the version that was read. */
+    blobs: Blobs;
+    /** Holds the catalog: who created each document, and when. */
+    store: Store;
+}
+/** Loads and saves documents as Yjs updates in a Blobs port. The CLI, MCP server, and API share it. */
+declare class DocsService {
+    private readonly options;
+    private readonly blobs;
+    private readonly store;
+    constructor(ports: DocsPorts, options?: DocOptions);
+    private key;
+    create(id: string, markdown: string, author: Principal): Promise<void>;
+    /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
+    info(id: string): Promise<DocInfo | null>;
+    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    /**
+     * Load, run the change, and save only if nobody saved in between. When someone did, load again and
+     * run the change again, so a check such as "is it still pending" sees the new state.
+     */
+    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+}
+
+export { type Anchor as A, DocsService as D, type EditEntry as E, type Principal as P, type Section as S, type TextTarget as T, AgenticDoc as a, type AnchorTarget as b, type PmNode as c, type DocInfo as d, type DocOptions as e, type DocsPorts as f, PRINCIPAL_KINDS as g, type PrincipalKind as h, type SectionTarget as i, type Target as j, blocksToMarkdown as k, markdownToBlocks as m, parseAuthor as p };

package/dist/worker.d.ts

@@ -0,0 +1,37 @@
+import { Hono } from 'hono';
+import { D1Like, R2Like } from 'agentic-identity/cloudflare';
+import { D as DocsService, P as Principal } from './service-eYISo6-b.js';
+import 'yjs';
+import 'agentic-identity';
+
+interface WorkerEnv {
+    /**
+     * Where the data lives: "eu" or "us". It is a claim you make at deploy time, with no default.
+     * "unknown" skips the region check. Local D1 reports no region, so "unknown" needs `AGENTIC_DOCS_UNSAFE_REGION=1` too.
+     */
+    AGENTIC_DOCS_REGION?: string;
+    /** Set to "1" to accept the region "unknown" under `wrangler dev`. Never set it in production. */
+    AGENTIC_DOCS_UNSAFE_REGION?: string;
+    /** D1 database: the catalog of documents. Create it with `wrangler d1 create agentic-documents --location weur`. */
+    DB?: D1Like;
+    /** R2 bucket: each document as a Yjs update. Create it with `--jurisdiction eu`. */
+    DOCS?: R2Like;
+    /**
+     * JSON object: bearer token (32 bytes or more) to `kind:name`, or to `{ "as": "kind:name", "scopes": ["docs:accept"] }`.
+     * Set it as a secret. A short token or a bad entry refuses the whole config.
+     */
+    AGENTIC_DOCS_TOKENS?: string;
+}
+/** A service, or a function that makes one from the Worker bindings. */
+type ServiceSource = DocsService | ((env: WorkerEnv) => Promise<DocsService>);
+declare function createApp(source: ServiceSource): Hono<{
+    Bindings: WorkerEnv;
+    Variables: {
+        author: Principal;
+    };
+}>;
+declare const _default: {
+    fetch: (request: Request, env: WorkerEnv, ctx: unknown) => Response | Promise<Response>;
+};
+
+export { type ServiceSource, type WorkerEnv, createApp, _default as default };

package/dist/worker.js

@@ -0,0 +1,162 @@
+import {
+  DocsService
+} from "./chunk-LRPLNXOF.js";
+import {
+  DocError,
+  PRINCIPAL_KINDS,
+  commands,
+  parseAuthor
+} from "./chunk-4YVWD5PH.js";
+
+// src/worker.ts
+import { Hono } from "hono";
+import { assertRegion, parseRegion } from "agentic-identity";
+import { D1_SCHEMA, createD1Store, createR2Blobs } from "agentic-identity/cloudflare";
+var STATUS = {
+  NO_MATCH: 404,
+  NO_SECTION: 404,
+  NO_THREAD: 404,
+  NO_SUGGESTION: 404,
+  NO_DOCUMENT: 404,
+  AMBIGUOUS_MATCH: 409,
+  STALE_ANCHOR: 409,
+  ALREADY_DECIDED: 409,
+  DOCUMENT_EXISTS: 409,
+  CONFLICT: 409,
+  FORBIDDEN: 403,
+  LOCKED: 503,
+  MISCONFIGURED: 500
+};
+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;
+}
+var MIN_TOKEN_BYTES = 32;
+var warned = /* @__PURE__ */ new Set();
+function refuse(reason) {
+  if (!warned.has(reason)) {
+    warned.add(reason);
+    console.error(`AGENTIC_DOCS_TOKENS is refused: ${reason}`);
+  }
+  return void 0;
+}
+function principalOf(entry) {
+  const object = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : void 0;
+  const who = typeof entry === "string" ? entry : object?.as;
+  const author = typeof who === "string" ? parseAuthor(who) : void 0;
+  if (!author || !PRINCIPAL_KINDS.includes(author.kind) || !author.name) return void 0;
+  if (object?.scopes === void 0) return author;
+  const scopes = object.scopes;
+  return Array.isArray(scopes) && scopes.every((s) => typeof s === "string" && s !== "") ? { ...author, scopes } : void 0;
+}
+function readTokens(raw) {
+  let table;
+  try {
+    table = JSON.parse(raw ?? "{}");
+  } catch {
+    return refuse("not valid JSON");
+  }
+  if (typeof table !== "object" || table === null || Array.isArray(table)) return refuse("not a JSON object");
+  const found = /* @__PURE__ */ new Map();
+  for (const [token, entry] of Object.entries(table)) {
+    if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) return refuse(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+    const principal = principalOf(entry);
+    if (!principal) return refuse("an entry is not a valid kind:name or { as, scopes }");
+    found.set(token, principal);
+  }
+  return found;
+}
+function principalFor(tokens, bearer) {
+  let found;
+  for (const [token, principal] of readTokens(tokens) ?? []) if (same(token, bearer)) found = principal;
+  return found;
+}
+var fail = (code, message, status, matches = []) => Response.json({ error: { code, message, matches } }, { status });
+function createApp(source) {
+  const app2 = new Hono();
+  app2.use("*", async (c, next) => {
+    await next();
+    c.header("x-content-type-options", "nosniff");
+  });
+  app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-documents" }));
+  app2.use("/api/v1/*", async (c, next) => {
+    const bearer = /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1];
+    const author = bearer === void 0 ? void 0 : principalFor(c.env?.AGENTIC_DOCS_TOKENS, bearer);
+    if (!author) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
+    c.set("author", author);
+    await next();
+  });
+  async function run(c, command, input) {
+    try {
+      const result = await command.run(await (typeof source === "function" ? source(c.env ?? {}) : source), input, c.get("author"));
+      if (command.name === "export") {
+        const { data, contentType, encoding, format } = result;
+        const images = input.remoteImages === true || input.remoteImages === "true" ? "data: https:" : "data:";
+        const disposition = format === "odt" ? { "content-disposition": `attachment; filename="${input.id}.odt"` } : {};
+        const headers = { ...disposition, "content-type": contentType, "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; img-src ${images}; sandbox` };
+        return encoding === "base64" ? c.body(Uint8Array.from(atob(data), (ch) => ch.charCodeAt(0)), 200, headers) : c.body(data, 200, headers);
+      }
+      if (typeof result === "string") return c.body(result, 200, { "content-type": "text/markdown; charset=utf-8" });
+      return c.json(result);
+    } catch (error) {
+      if (!(error instanceof DocError)) throw error;
+      return fail(error.code, error.message, STATUS[error.code] ?? 400, error.matches);
+    }
+  }
+  async function body(c) {
+    const parsed = await c.req.json().catch(() => void 0);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new DocError("INVALID_INPUT", "the body must be a JSON object");
+    }
+    return parsed;
+  }
+  const create = commands.find((c) => c.name === "new");
+  app2.post("/api/v1/docs", async (c) => run(c, create, await body(c)));
+  for (const command of commands.filter((c) => c !== create)) {
+    const path = `/api/v1/docs/:id/${command.name}`;
+    if (command.readOnly) app2.get(path, (c) => run(c, command, { ...c.req.query(), id: c.req.param("id") }));
+    else app2.post(path, async (c) => run(c, command, { ...await body(c), id: c.req.param("id") }));
+  }
+  app2.notFound(() => fail("NOT_FOUND", "no such route", 404));
+  app2.onError((error) => {
+    if (error instanceof DocError) return fail(error.code, error.message, STATUS[error.code] ?? 400, error.matches);
+    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();
+var urlSecret;
+async function serviceFor(env) {
+  if (!env.DB || !env.DOCS) throw new DocError("MISCONFIGURED", "bind a D1 database as DB and an R2 bucket as DOCS");
+  let region;
+  try {
+    region = parseRegion(env.AGENTIC_DOCS_REGION);
+  } catch {
+    throw new DocError("MISCONFIGURED", 'set AGENTIC_DOCS_REGION to "eu" or "us" ("unknown" only for local development)');
+  }
+  if (region === "unknown" && env.AGENTIC_DOCS_UNSAFE_REGION !== "1") {
+    throw new DocError("MISCONFIGURED", 'the region "unknown" turns the residency check off; set AGENTIC_DOCS_UNSAFE_REGION=1 to accept that for local development');
+  }
+  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 });
+  const blobs = createR2Blobs(env.DOCS, { region, urlBase: "https://invalid.example/unused", urlSecret: urlSecret ??= `${crypto.randomUUID()}${crypto.randomUUID()}` });
+  assertRegion(region, store, blobs);
+  return new DocsService({ store, blobs });
+}
+var app = createApp(serviceFor);
+var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+export {
+  createApp,
+  worker_default as default
+};

package/llms.txt

@@ -0,0 +1,15 @@
+# agentic-documents
+
+Write documents with people and agents in real time.
+
+Keywords: documents, editor, rich-text, tiptap, yjs, collaboration, agents.
+
+- SDK: import { AgenticDoc } from "agentic-documents".
+- Read as Markdown, read an outline, edit by section id or exact text.
+- CLI: npx agentic-documents <command> <id>. MCP: npx agentic-documents mcp --as <kind>:<name>.
+- Every edit carries an author kind and name.
+
+## Docs
+
+- README: https://github.com/pooriaarab/agentic-documents
+- License: MIT

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "agentic-documents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write documents with people and agents in real time.",
+  "keywords": [
+    "documents",
+    "editor",
+    "rich-text",
+    "tiptap",
+    "collaboration",
+    "agents",
+    "mcp",
+    "cli",
+    "cloudflare"
+  ],
+  "license": "MIT",
+  "author": "Pooria Arab",
+  "homepage": "https://github.com/pooriaarab/agentic-documents#readme",
+  "bugs": {
+    "url": "https://github.com/pooriaarab/agentic-documents/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pooriaarab/agentic-documents.git"
+  },
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "SECURITY.md",
+    "SKILL.md",
+    "llms.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "mcpName": "io.github.pooriaarab/agentic-documents",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "ci:local": "npm run build && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "agentic-identity": "^0.2.0",
+    "fflate": "^0.8.3",
+    "hono": "^4.13.14",
+    "lib0": "^0.2.119",
+    "mdast-util-from-markdown": "^2.1.0",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.2.1",
+    "micromark-extension-gfm": "^3.0.0",
+    "prosemirror-model": "^1.25.12",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-view": "^1.42.8",
+    "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.33",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@tiptap/core": "^3.32.1",
+    "@tiptap/extension-image": "^3.32.1",
+    "@tiptap/extension-list": "^3.32.1",
+    "@tiptap/extension-table": "^3.32.1",
+    "@tiptap/pm": "^3.32.1",
+    "@tiptap/starter-kit": "^3.32.1",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0",
+    "wrangler": "^4.155.0"
+  },
+  "bin": {
+    "agentic-documents": "./dist/cli.js"
+  }
+}