@adonis-agora/collaboration 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @adonis-agora/collaboration
 
+## 0.2.0
+
+### Minor Changes
+
+- badb9f7: New `partykit` engine: edge sync via Cloudflare Workers + Durable Objects. Includes `PartyKitDriver` (HTTP client of the worker's onRequest API), HS256 JWT helpers (`signPartyKitToken`/`verifyPartyKitToken`), worker template published by the new `collaboration:init` command, and `config.partykit.{roomHost,jwtSecret,party,fetchTimeoutMs}`.
+
+  New ace commands: `collaboration:init` (base directories, migrations, PartyKit worker scaffold) and `make:collab-document <name>` (shared per-document types with spaces + anchor kinds). Commands are registered automatically by `configure` via the new `./commands` export.
+
+  Built-in REST endpoints (token, comments CRUD, versions, binary state) are now registered automatically by the provider under `/collaboration`. Set `routes.enabled = false` to take manual control with the new `collaborationRoutes(router, options)` export — supports custom prefix, middleware/guards and a pluggable `resolveUser`. The binary state POST is protected by a shared worker secret.
+
+  AdonisJS v7 codegen integration: an Assembler `init` hook generates `.adonisjs/collaboration/documents.ts`, a typed registry (`CollabDocumentName`, `CollabDocumentDefinition`) refreshed by `node ace codegen` / dev server / build.
+
+  Refactor — seams made real:
+
+  - Comments now flow through a single seam: `manager.comments`. Drivers no longer accept, store or delegate comment operations (12 pass-through methods removed). This also fixes a latent bug where manager and drivers held separate in-memory storage instances when none was configured.
+  - New `auth/token` module (`issueToken`, `parseLegacyToken`, `buildWsUrl`, `signPartyKitToken`, `verifyPartyKitToken`) replaces six scattered token implementations; the REST `/token` endpoint now enforces `config.authorize` (403 on denial) — previously it was bypassed off the WS path.
+  - Drivers take narrow dependency objects (`SelfHostedDriverOptions`, `PartyKitDriverOptions`) instead of the whole `CollaborationConfig`.
+  - Removed dead `PresenceService` (+ ioredis dependency) and the duplicated REST controller/routes stubs — manual mode uses `collaborationRoutes()` directly.
+
+  New engines and client surfaces:
+
+  - `partyserver` engine: client transport (`PartyServerCollabTransport`) for the self-hosted Cloudflare Workers stack via `y-partyserver/provider`; token issuance treats it like the partykit edge engine.
+  - Automerge on the client: new `useAutomergeDoc(docName)` hook speaking the server driver's binary protocol directly (initial full save, debounced local saves, CRDT merge) — intentionally outside the Y.Doc-centric hooks, since Automerge docs cannot back Tiptap/awareness.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,172 @@
+# @adonis-agora/collaboration
+
+Collaborative editing (CRDT) for AdonisJS — Yjs (Hocuspocus), Automerge and PartyKit (edge) drivers, Redis-backed presence, unified version control, anchored comments, ace codegen and React client hooks. Part of the Agora ecosystem.
+
+## Install
+
+```sh
+node ace add @adonis-agora/collaboration
+```
+
+## Quick start
+
+```sh
+node ace configure @adonis-agora/collaboration   # provider + config/collaboration.ts
+node ace collaboration:init                       # REST routes, controller, migrations
+node ace make:collab-document researches/writing  # shared types per document
+```
+
+Wire `config/collaboration.ts` with your `authorize()` (the lib never authorizes by default) and a storage backend (`LucidStorage`, `FileSystemStorage` or your own).
+
+### Engines
+
+| Engine | Sync runs on | Best for |
+|---|---|---|
+| `yjs` (default) | Embedded Hocuspocus on the Adonis HTTP server | Self-hosted, single origin |
+| `automerge` | Custom room broadcast on Adonis server | Native history |
+| `partykit` | Cloudflare Workers + Durable Objects (edge) | Global latency, separate origin |
+
+PartyKit setup:
+
+```ts
+// config/collaboration.ts
+{
+  engine: 'partykit',
+  partykit: { roomHost: 'meu-app.partykit.dev', jwtSecret: process.env.COLLAB_JWT_SECRET },
+}
+```
+
+Then run `collaboration:init --engine=partykit` to scaffold the worker into `partykit-worker/` and deploy with `npx partykit deploy`.
+
+## Server API
+
+```ts
+import collaboration from '@adonis-agora/collaboration/services/main'
+
+await collaboration.current.getDocumentText('researches/42/writing')
+const version = await collaboration.current.createVersion('researches/42/writing', userId, 'v1')
+collaboration.current.comments.list('researches/42/writing', 'text')
+```
+
+Version control works across engines: full-update snapshots (Yjs/PartyKit) or native heads (Automerge). Comments are anchored per space (`text-range`, `canvas-object`, `timestamp`) and persisted via the storage backend.
+
+## Client hooks (React)
+
+```sh
+pnpm add @adonis-agora/collaboration-client
+```
+
+```tsx
+import {
+  CollaborationProvider,
+  useCollabDoc,
+  useAwareness,
+  useComments,
+  useVersions,
+} from '@adonis-agora/collaboration-client'
+
+<CollaborationProvider baseUrl="https://api.app" getHeaders={() => ({ cookie })}>
+  <Editor docName="researches/42/writing" />
+</CollaborationProvider>
+
+function Editor({ docName }: { docName: string }) {
+  const { doc, status } = useCollabDoc(docName)   // Y.Doc + connection status
+  const { peers } = useAwareness(docName)
+  const { comments, create, resolve } = useComments(docName, 'text')
+  const { versions, create: createVersion } = useVersions(docName)
+  // feed doc into Tiptap/y-prosemirror…
+}
+```
+
+The transport is chosen automatically from the engine reported by `GET /collaboration/token` (HocuspocusProvider or YPartyKitProvider).
+
+## Codegen
+
+### Commands
+
+- `collaboration:init` — scaffolds the documents directory, base migrations (when a database is configured) and the PartyKit worker (`--engine=partykit`)
+- `make:collab-document <name>` — generates shared document types in `app/collaboration/documents/` (spaces + allowed anchor kinds), importable by the frontend
+
+Commands are registered automatically by `configure`; manual setups need `commands: ['@adonis-agora/collaboration/commands']` in `adonisrc.ts`.
+
+### Typed document registry
+
+The package ships an Assembler `init` hook (registered by `configure`) that scans `app/collaboration/documents/` and generates `.adonisjs/collaboration/documents.ts`:
+
+```ts
+import type { CollabDocumentName, CollabDocumentDefinition } from '.adonisjs/collaboration/documents.js'
+
+function open(name: CollabDocumentName) { … }   // autocomplete + exhaustiveness
+```
+
+Refresh it with `node ace codegen`, the dev server, tests or build — same lifecycle as controllers/routes barrels.
+
+## REST endpoints
+
+Ten endpoints ship built-in (token, comments CRUD, versions, binary state) and are **registered automatically** on boot under `/collaboration`.
+
+Protect them via config — any Adonis middleware or auth guard works:
+
+```ts
+// config/collaboration.ts
+routes: {
+  enabled: true,
+  prefix: '/collaboration',
+  middleware: [() => import('#middleware/auth_middleware')], // guards apply here
+}
+```
+
+Prefer full control? Disable and register manually where you want:
+
+```ts
+// routes.enabled = false
+import { collaborationRoutes } from '@adonis-agora/collaboration'
+
+collaborationRoutes(router, {
+  prefix: '/api/collab',
+  middleware: [authMiddleware],
+})
+```
+
+Without a resolver the token endpoint fails closed (401): pass `routes.resolveUser` or run your auth middleware first. The binary `state` POST is machine-to-machine (PartyKit worker → Adonis) and requires the shared worker secret instead of a user.
+
+> **Route type-safety caveat**: auto-registered routes live in the provider's `ready()` phase, which runs after the codegen warmup — so they may not appear in `.adonisjs/server/routes.d.ts`. If your app relies on generated route types (e.g. Tuyau), use manual mode: set `routes.enabled = false` and call `collaborationRoutes(router)` in `start/routes.ts`, where routes are always picked up.
+
+## Editor binding (Tiptap)
+
+The client hooks hand you a plain `Y.Doc` — feed it straight into Tiptap:
+
+```tsx
+import Collaboration from '@tiptap/extension-collaboration'
+import CollaborationCursor from '@tiptap/extension-collaboration-cursor'
+import { useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { useCollabDoc, useAwareness } from '@adonis-agora/collaboration-client'
+
+function Editor({ docName, user }: { docName: string; user: { name: string; color: string } }) {
+  const { doc, status } = useCollabDoc(docName)
+  const { peers } = useAwareness(docName)
+
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      Collaboration.configure({ document: doc }),
+      CollaborationCursor.configure({ user }),
+    ],
+    editable: status === 'connected',
+  })
+
+  return (
+    <>
+      <EditorContent editor={editor} />
+      {peers.map((peer) => (
+        <span key={peer.clientId} style={{ color: 'gray' }}>{peer.name ?? 'anon'}</span>
+      ))}
+    </>
+  )
+}
+```
+
+## License
+
+MIT

package/dist/commands/collaboration_init.d.ts

@@ -0,0 +1,26 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+/**
+ * `node ace collaboration:init`
+ *
+ * Scaffolds the HTTP + edge layer of the collaboration package:
+ *  - base directory for document definitions (scanned by the codegen hook);
+ *  - migrations when a database is configured (storage-backed installs);
+ *  - PartyKit worker (when engine = partykit).
+ *
+ * REST endpoints are registered automatically by the service provider —
+ * set `routes.enabled: false` in config and call `collaborationRoutes()`
+ * in `start/routes.ts` to control middleware yourself.
+ *
+ * `config/collaboration.ts` and the provider are published by
+ * `node ace configure @adonis-agora/collaboration`.
+ */
+export default class CollaborationInit extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    engine?: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=collaboration_init.d.ts.map

package/dist/commands/collaboration_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaboration_init.d.ts","sourceRoot":"","sources":["../../commands/collaboration_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAS,MAAM,oBAAoB,CAAC;AAGxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,WAAW;IACxD,OAAgB,WAAW,SAAwB;IACnD,OAAgB,WAAW,SACoD;IAC/E,OAAgB,OAAO;;MAAsB;IAKrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAET,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA+DpC"}

package/dist/commands/collaboration_init.js

@@ -0,0 +1,83 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { stubsRoot } from '../stubs/main.js';
+/**
+ * `node ace collaboration:init`
+ *
+ * Scaffolds the HTTP + edge layer of the collaboration package:
+ *  - base directory for document definitions (scanned by the codegen hook);
+ *  - migrations when a database is configured (storage-backed installs);
+ *  - PartyKit worker (when engine = partykit).
+ *
+ * REST endpoints are registered automatically by the service provider —
+ * set `routes.enabled: false` in config and call `collaborationRoutes()`
+ * in `start/routes.ts` to control middleware yourself.
+ *
+ * `config/collaboration.ts` and the provider are published by
+ * `node ace configure @adonis-agora/collaboration`.
+ */
+export default class CollaborationInit extends BaseCommand {
+    static commandName = 'collaboration:init';
+    static description = 'Scaffold base directories, migrations and (optionally) the PartyKit worker';
+    static options = { startApp: true };
+    async run() {
+        const appConfig = this.app.config.get('collaboration', {});
+        const resolvedEngine = this.engine ?? appConfig.engine ?? 'yjs';
+        const hasDatabase = this.app.config.has('database');
+        const codemods = await this.createCodemods();
+        // 1. Base documents directory (scanned by the codegen init hook).
+        await codemods.makeUsingStub(stubsRoot, 'collaboration/documents_dir.stub', {});
+        this.logger.action('create app/collaboration/documents/').succeeded();
+        // 2. Base migrations (when a database is configured).
+        if (hasDatabase) {
+            const prefix = Date.now();
+            const tables = ['collab_documents', 'collab_versions', 'collab_comments'];
+            for (const [index, tableName] of tables.entries()) {
+                await codemods.makeUsingStub(stubsRoot, `collaboration/migrations/${tableName}.stub`, {
+                    migration: {
+                        tableName,
+                        fileName: `${prefix}_${index}_create_${tableName}_table.ts`,
+                    },
+                });
+                this.logger.action(`create migration ${tableName}`).succeeded();
+            }
+        }
+        // 3. PartyKit worker.
+        if (resolvedEngine === 'partykit') {
+            if (!appConfig.partykit?.roomHost) {
+                this.logger.warning('engine=partykit without config.partykit.roomHost — the driver will fail at runtime until configured');
+            }
+            await codemods.makeUsingStub(stubsRoot, 'partykit/worker/party.ts.stub', {});
+            await codemods.makeUsingStub(stubsRoot, 'partykit/worker/package.json.stub', {});
+            await codemods.makeUsingStub(stubsRoot, 'partykit/worker/partykit.toml.stub', {
+                partykitWorkerName: this.app.appName ?? 'collab-worker',
+                adonisBaseUrl: process.env.APP_URL ?? 'http://localhost:3333',
+            });
+            this.logger.info([
+                '',
+                'PartyKit worker generated at partykit-worker/',
+                '  1. cd partykit-worker && npm install',
+                '  2. npx partykit secret put COLLAB_JWT_SECRET',
+                '  3. npx partykit dev   # local',
+                '  4. npx partykit deploy # production',
+                '',
+            ].join('\n'));
+        }
+        this.logger.success([
+            'Collaboration initialized.',
+            'REST endpoints are registered automatically by the provider (disable with routes.enabled=false).',
+            'Next step: node ace make:collab-document <name>',
+        ].join(' '));
+    }
+}
+__decorate([
+    flags.string({
+        description: 'Sync engine (yjs | automerge | partykit) — defaults to the one in config',
+    })
+], CollaborationInit.prototype, "engine", void 0);
+//# sourceMappingURL=collaboration_init.js.map

package/dist/commands/collaboration_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaboration_init.js","sourceRoot":"","sources":["../../commands/collaboration_init.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,WAAW;IACxD,MAAM,CAAU,WAAW,GAAG,oBAAoB,CAAC;IACnD,MAAM,CAAU,WAAW,GACzB,4EAA4E,CAAC;IAC/E,MAAM,CAAU,OAAO,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAOpC,KAAK,CAAC,GAAG;QAChB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAGlC,eAAe,EAAE,EAAE,CAAC,CAAC;QAExB,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,IAAI,KAAK,CAAC;QAChE,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAE7C,kEAAkE;QAClE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kCAAkC,EAAE,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,qCAAqC,CAAC,CAAC,SAAS,EAAE,CAAC;QAEtE,sDAAsD;QACtD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,CAAC,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,CAAU,CAAC;YACnF,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;gBAClD,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,4BAA4B,SAAS,OAAO,EAAE;oBACpF,SAAS,EAAE;wBACT,SAAS;wBACT,QAAQ,EAAE,GAAG,MAAM,IAAI,KAAK,WAAW,SAAS,WAAW;qBAC5D;iBACF,CAAC,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,oBAAoB,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;YAClE,CAAC;QACH,CAAC;QAED,sBAAsB;QACtB,IAAI,cAAc,KAAK,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC;gBAClC,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB,qGAAqG,CACtG,CAAC;YACJ,CAAC;YACD,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,+BAA+B,EAAE,EAAE,CAAC,CAAC;YAC7E,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,mCAAmC,EAAE,EAAE,CAAC,CAAC;YACjF,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,oCAAoC,EAAE;gBAC5E,kBAAkB,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,eAAe;gBACvD,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,uBAAuB;aAC9D,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CACd;gBACE,EAAE;gBACF,+CAA+C;gBAC/C,wCAAwC;gBACxC,gDAAgD;gBAChD,iCAAiC;gBACjC,uCAAuC;gBACvC,EAAE;aACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,OAAO,CACjB;YACE,4BAA4B;YAC5B,kGAAkG;YAClG,iDAAiD;SAClD,CAAC,IAAI,CAAC,GAAG,CAAC,CACZ,CAAC;IACJ,CAAC;;AAhEO;IAHP,KAAK,CAAC,MAAM,CAAC;QACZ,WAAW,EAAE,0EAA0E;KACxF,CAAC;iDACsB"}

package/dist/commands/commands.json

@@ -0,0 +1 @@
+{"commands":[{"commandName":"collaboration:init","description":"Scaffold base directories, migrations and (optionally) the PartyKit worker","help":"","namespace":"collaboration","aliases":[],"flags":[{"name":"engine","flagName":"engine","required":false,"type":"string","description":"Sync engine (yjs | automerge | partykit) — defaults to the one in config"}],"args":[],"options":{"startApp":true},"filePath":"collaboration_init.js"},{"commandName":"make:collab-document","description":"Make shared types for a collaborative document (spaces + anchors)","help":"","namespace":"make","aliases":[],"flags":[{"name":"anchors","flagName":"anchors","required":false,"type":"string","description":"Allowed anchor kinds as a comma-separated list (text-range,canvas-object,timestamp)"},{"name":"spaces","flagName":"spaces","required":false,"type":"string","description":"Document spaces as a comma-separated list (default 'text')"}],"args":[{"name":"name","argumentName":"name","required":true,"description":"Collaborative document name (e.g. researches/writing)","type":"string"}],"options":{"startApp":true,"allowUnknownFlags":true},"filePath":"make_collab_document.js"}],"version":1}

package/dist/commands/main.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ace commands barrel — same pattern as @adonisjs/lucid. The Adonis kernel
+ * calls getMetaData()/getCommand() through the "./commands" export listed in
+ * the adonisrc.ts `commands` array.
+ */
+interface CommandMeta {
+    commandName: string;
+    filePath: string;
+    [key: string]: unknown;
+}
+export declare function getMetaData(): Promise<CommandMeta[]>;
+export declare function getCommand(metaData: {
+    commandName: string;
+}): Promise<any>;
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/commands/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,UAAU,WAAW;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAS1D;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,gBAWjE"}

package/dist/commands/main.js

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+let commandsMetaData;
+export async function getMetaData() {
+    if (commandsMetaData) {
+        return commandsMetaData;
+    }
+    const commandsIndex = await readFile(new URL('./commands.json', import.meta.url), 'utf-8');
+    commandsMetaData = JSON.parse(commandsIndex).commands;
+    return commandsMetaData;
+}
+export async function getCommand(metaData) {
+    const commands = await getMetaData();
+    const command = commands.find(({ commandName }) => metaData.commandName === commandName);
+    if (!command) {
+        return null;
+    }
+    const { default: commandConstructor } = await import(new URL(command.filePath, import.meta.url).href);
+    return commandConstructor;
+}
+//# sourceMappingURL=main.js.map

package/dist/commands/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAc5C,IAAI,gBAA2C,CAAC;AAEhD,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;IAC3F,gBAAgB,GAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAiC,CAAC,QAAQ,CAAC;IAEvF,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAiC;IAChE,MAAM,QAAQ,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC;IACzF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAClD,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAChD,CAAC;IACF,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/commands/make_collab_document.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+/**
+ * `node ace make:collab-document researches/writing`
+ *
+ * Generates the shared types for a collaborative document (doc name
+ * pattern, spaces, allowed anchor kinds) at
+ * `app/collaboration/documents/<name>_types.ts`. The typed registry in
+ * `.adonisjs/collaboration/documents.ts` is refreshed automatically by the
+ * codegen hook (`node ace codegen` / dev server).
+ */
+export default class MakeCollabDocument extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+        allowUnknownFlags: boolean;
+    };
+    name: string;
+    anchors?: string;
+    spaces?: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=make_collab_document.d.ts.map

package/dist/commands/make_collab_document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_collab_document.d.ts","sourceRoot":"","sources":["../../commands/make_collab_document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,oBAAoB,CAAC;AAI9D;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,WAAW;IACzD,OAAgB,WAAW,SAA0B;IACrD,OAAgB,WAAW,SAAuE;IAClG,OAAgB,OAAO;;;MAA+C;IAG9D,IAAI,EAAE,MAAM,CAAC;IAMb,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAET,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA8CpC"}

package/dist/commands/make_collab_document.js

@@ -0,0 +1,75 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args, flags } from '@adonisjs/core/ace';
+import stringHelpers from '@adonisjs/core/helpers/string';
+import { stubsRoot } from '../stubs/main.js';
+/**
+ * `node ace make:collab-document researches/writing`
+ *
+ * Generates the shared types for a collaborative document (doc name
+ * pattern, spaces, allowed anchor kinds) at
+ * `app/collaboration/documents/<name>_types.ts`. The typed registry in
+ * `.adonisjs/collaboration/documents.ts` is refreshed automatically by the
+ * codegen hook (`node ace codegen` / dev server).
+ */
+export default class MakeCollabDocument extends BaseCommand {
+    static commandName = 'make:collab-document';
+    static description = 'Make shared types for a collaborative document (spaces + anchors)';
+    static options = { startApp: true, allowUnknownFlags: true };
+    async run() {
+        const entity = this.app.generators.createEntity(this.name);
+        const documentName = `${entity.path ? `${entity.path}/` : ''}${stringHelpers.snakeCase(entity.name)}`;
+        const className = stringHelpers.pascalCase(entity.name);
+        const fileName = `${stringHelpers.snakeCase(entity.name)}_types.ts`;
+        const anchorKinds = (this.anchors ?? 'text-range')
+            .split(',')
+            .map((kind) => kind.trim())
+            .filter((kind) => ['text-range', 'canvas-object', 'timestamp'].includes(kind));
+        if (anchorKinds.length === 0) {
+            this.logger.error('invalid --anchors. Use values from: text-range, canvas-object, timestamp');
+            this.exitCode = 1;
+            return;
+        }
+        const spaceList = (this.spaces ?? 'text')
+            .split(',')
+            .map((space) => space.trim())
+            .filter(Boolean);
+        const codemods = await this.createCodemods();
+        await codemods.makeUsingStub(stubsRoot, 'collaboration/document_types.stub', {
+            document: {
+                documentName,
+                className,
+                fileName,
+                anchorKinds,
+                spaceList,
+            },
+        });
+        this.logger.action(`create app/collaboration/documents/${fileName}`).succeeded();
+        // The typed registry is generated by the codegen init hook scanning
+        // app/collaboration/documents — nothing to edit by hand.
+        this.logger.info([
+            '',
+            `Document '${documentName}' registered. Refresh the typed registry with:`,
+            '  node ace codegen   (or restart the dev server)',
+            '→ importable from .adonisjs/collaboration/documents.ts',
+            '  (types CollabDocumentName / CollabDocumentDefinition)',
+            '',
+        ].join('\n'));
+    }
+}
+__decorate([
+    args.string({ description: 'Collaborative document name (e.g. researches/writing)' })
+], MakeCollabDocument.prototype, "name", void 0);
+__decorate([
+    flags.string({
+        description: 'Allowed anchor kinds as a comma-separated list (text-range,canvas-object,timestamp)',
+    })
+], MakeCollabDocument.prototype, "anchors", void 0);
+__decorate([
+    flags.string({ description: "Document spaces as a comma-separated list (default 'text')" })
+], MakeCollabDocument.prototype, "spaces", void 0);
+//# sourceMappingURL=make_collab_document.js.map

package/dist/commands/make_collab_document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_collab_document.js","sourceRoot":"","sources":["../../commands/make_collab_document.ts"],"names":[],"mappings":"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"}

package/dist/configure.d.ts

@@ -3,7 +3,9 @@ import type Configure from '@adonisjs/core/commands/configure';
  * `node ace configure @adonis-agora/collaboration` — auto-wires the package:
  *
  * 1. registers the collaboration service provider in `adonisrc.ts`;
- * 2. publishes `config/collaboration.ts` (engine, path, redis, authorize,
+ * 2. registers the ace commands barrel (`collaboration:init`,
+ *    `make:collab-document`);
+ * 3. publishes `config/collaboration.ts` (engine, path, redis, authorize,
  *    storage).
  */
 export declare function configure(command: Configure): Promise<void>;

package/dist/configure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAQjD"}
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAWjD"}

package/dist/configure.js

@@ -3,13 +3,18 @@ import { stubsRoot } from './stubs/main.js';
  * `node ace configure @adonis-agora/collaboration` — auto-wires the package:
  *
  * 1. registers the collaboration service provider in `adonisrc.ts`;
- * 2. publishes `config/collaboration.ts` (engine, path, redis, authorize,
+ * 2. registers the ace commands barrel (`collaboration:init`,
+ *    `make:collab-document`);
+ * 3. publishes `config/collaboration.ts` (engine, path, redis, authorize,
  *    storage).
  */
 export async function configure(command) {
     const codemods = await command.createCodemods();
     await codemods.updateRcFile((rcFile) => {
         rcFile.addProvider('@adonis-agora/collaboration/collaboration_provider');
+        rcFile.addCommand('@adonis-agora/collaboration/commands');
+        // Codegen v7: registry tipado de documentos em .adonisjs/ (node ace codegen).
+        rcFile.addAssemblerHook('init', '@adonis-agora/collaboration/codegen_init');
     });
     await codemods.makeUsingStub(stubsRoot, 'config/collaboration.stub', {});
 }

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,2BAA2B,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oDAAoD,CAAC,CAAC;QACzE,MAAM,CAAC,UAAU,CAAC,sCAAsC,CAAC,CAAC;QAC1D,8EAA8E;QAC9E,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,0CAA0C,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,2BAA2B,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/providers/collaboration_provider.d.ts

@@ -4,12 +4,16 @@ import type { ApplicationService } from '@adonisjs/core/types';
  *
  * - `register()` hands the booted app to `services/main` and binds the
  *   `CollaborationManager` singleton from `config/collaboration.ts`;
- * - `boot()` attaches the collaboration WebSocket upgrade to the Adonis HTTP
- *   server (path from config, default `/collaboration`);
+ * - `boot()`/`ready()` attaches the collaboration WebSocket upgrade to the
+ *   Adonis HTTP server (path from config, default `/collaboration`);
+ * - `ready()` registers the built-in REST endpoints automatically unless
+ *   `routes.enabled: false` — then call `collaborationRoutes(router)` in
+ *   `start/routes.ts` with your own middleware;
  * - `shutdown()` flushes pending stores and closes all connections.
  */
 export default class CollaborationServiceProvider {
     protected app: ApplicationService;
+    private config?;
     constructor(app: ApplicationService);
     register(): void;
     ready(): Promise<void>;

package/dist/providers/collaboration_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collaboration_provider.d.ts","sourceRoot":"","sources":["../../providers/collaboration_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAU/D;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IACnC,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IAiCF,KAAK;IA4BL,QAAQ;CAIf"}
+{"version":3,"file":"collaboration_provider.d.ts","sourceRoot":"","sources":["../../providers/collaboration_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAM/D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IAGnC,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAF7C,OAAO,CAAC,MAAM,CAAC,CAAyB;gBAElB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IA6BF,KAAK;IA8CL,QAAQ;CAIf"}