agentic-documents 0.0.0-stage → 0.2.0

package/dist/service-BKkxEnaJ.d.ts

@@ -0,0 +1,181 @@
+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;
+}
+/** What every command needs: make a document, read it, and change it. A live room can stand behind it as well as the ports. */
+interface DocAccess {
+    create(id: string, markdown: string, author: Principal): Promise<void>;
+    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+}
+/** Loads and saves documents as Yjs updates in a Blobs port. The CLI, MCP server, and API share it. */
+declare class DocsService implements DocAccess {
+    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>;
+    /** The stored document as a Yjs update. A live client seeds its room from it. */
+    state(id: string): Promise<Uint8Array>;
+    /**
+     * Merge a Yjs update from a live room into the stored document, and create the document when it
+     * has none. A merge is safe to repeat and to run in any order. The save is conditional, so two
+     * checkpoints at once both land.
+     */
+    checkpoint(id: string, update: Uint8Array, author: Principal): Promise<void>;
+    /**
+     * The encoded document, once it reads back and every stored entry has the shape the commands rely on. Yjs does not
+     * check types, so an update can put text where the editor expects blocks, or a thread with no messages, and then a
+     * command fails on every later call.
+     */
+    private checked;
+    private fits;
+    private catalog;
+    /** 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, type DocAccess 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, DocsService as g, PRINCIPAL_KINDS as h, type PrincipalKind as i, type SectionTarget as j, type Target as k, blocksToMarkdown as l, markdownToBlocks as m, parseAuthor as p };

package/dist/worker.d.ts

@@ -0,0 +1,50 @@
+import { Hono } from 'hono';
+import { Region } from 'agentic-identity';
+import { D1Like, R2Like } from 'agentic-identity/cloudflare';
+import { Realtime, Role } from 'agentic-realtime';
+import { g as DocsService, P as Principal } from './service-BKkxEnaJ.js';
+import 'yjs';
+
+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"], "role": "viewer" }`.
+     * A role is `editor` (the default) or `viewer`. A viewer reads and cannot write, over HTTP or in a live room.
+     * Set it as a secret. A short token or a bad entry refuses the whole config.
+     */
+    AGENTIC_DOCS_TOKENS?: string;
+}
+type DocRole = Extract<Role, "editor" | "viewer">;
+/** A service, or a function that makes one from the Worker bindings. */
+type ServiceSource = DocsService | ((env: WorkerEnv) => Promise<DocsService>);
+type AppEnv = {
+    Bindings: WorkerEnv;
+    Variables: {
+        author: Principal;
+        role: DocRole;
+    };
+};
+interface AppOptions {
+    /** Makes the live-room server from the Worker bindings. Without it, the ws route answers 404. */
+    live?: (env: WorkerEnv) => Realtime;
+}
+declare function createApp(source: ServiceSource, options?: AppOptions): Hono<AppEnv>;
+/** The region claim, or a MISCONFIGURED error. The HTTP API and the live rooms both use it, so neither runs without it. */
+declare function regionOf(env: WorkerEnv): Region;
+/** The service over D1 and R2. One region claim covers D1 and R2. The bucket is declared with the "eu" jurisdiction in wrangler.jsonc: keep the two in step. */
+declare function serviceFor(env: WorkerEnv): Promise<DocsService>;
+declare const _default: {
+    fetch: (request: Request, env: WorkerEnv, ctx: unknown) => Response | Promise<Response>;
+};
+
+export { type AppOptions, type DocRole, type ServiceSource, type WorkerEnv, createApp, _default as default, regionOf, serviceFor };

package/dist/worker.js

@@ -0,0 +1,15 @@
+import {
+  createApp,
+  regionOf,
+  serviceFor,
+  worker_default
+} from "./chunk-IU3YIQ4Y.js";
+import "./chunk-FZA5LQV3.js";
+import "./chunk-GYQFTF2E.js";
+import "./chunk-YBBQNCMC.js";
+export {
+  createApp,
+  worker_default as default,
+  regionOf,
+  serviceFor
+};

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,106 @@
 {
   "name": "agentic-documents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+    "CHANGELOG.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"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "import": "./dist/live.js"
+    },
+    "./live-worker": {
+      "types": "./dist/live-worker.d.ts",
+      "import": "./dist/live-worker.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "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.3.0",
+    "agentic-realtime": "^0.1.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"
+  }
+}