@aphexcms/cms-core 9.6.0 → 9.8.0

package/dist/server/api/routes/workers-run.js

@@ -0,0 +1,40 @@
+import { Hono } from 'hono';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { runJobsBatch } from '../../../jobs/index.js';
+/**
+ * Constant-time compare of the presented bearer token against the configured secret.
+ * Length is compared first (and short-circuits), which leaks only the secret's length —
+ * acceptable, and unavoidable without hashing both sides.
+ */
+function secretMatches(presented, expected) {
+    const a = Buffer.from(presented);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+export const workersRunRouter = new Hono();
+/**
+ * POST /api/internal/workers/run — drive one bounded batch of due jobs and return counts.
+ *
+ * Machine-to-machine: authorized by a shared secret (`Authorization: Bearer <secret>`),
+ * NOT the user capability system — platform cron (hosted) or a self-hosted worker loop
+ * calls it on a cadence. Disabled (404) unless `jobs.workerSecret` is configured, so it
+ * never exists as an unauthenticated surface by default. Bounded per call (batchSize), so
+ * a single invocation can't run unboundedly; the caller's cadence sets throughput.
+ */
+workersRunRouter.post('/run', async (c) => {
+    const secret = c.var.aphexCMS.config.jobs?.workerSecret;
+    // Not configured → the endpoint doesn't exist. Don't advertise it or hint at auth.
+    if (!secret)
+        return c.json({ success: false, error: 'Not found' }, 404);
+    const header = c.req.header('authorization') ?? '';
+    const presented = header.startsWith('Bearer ') ? header.slice('Bearer '.length) : '';
+    if (!presented || !secretMatches(presented, secret)) {
+        return c.json({ success: false, error: 'Unauthorized' }, 401);
+    }
+    // Shared seam: builds the handler map (built-in + app-registered) and runs one batch.
+    // The embedded poll loop calls the same helper, so the two modes can't drift.
+    const result = await runJobsBatch(c.var.aphexCMS, { workerId: `endpoint-${randomUUID()}` });
+    return c.json({ success: true, result });
+});

package/dist/server/index.d.ts

@@ -2,6 +2,7 @@ export * from '../types/index.js';
 export * from '../auth/provider.js';
 export * from '../cache/index.js';
 export * from '../email/index.js';
+export * from '../ai/index.js';
 export { AuthError, type AuthErrorCode } from '../auth/auth-errors.js';
 export { createCMSConfig } from '../config.js';
 export { cmsLogger, setLogger, type Logger } from '../utils/logger.js';
@@ -16,6 +17,7 @@ export { AssetService } from '../services/asset-service.js';
 export { RolesService } from '../services/roles-service.js';
 export { GET as serveAssetCDN } from '../routes/assets-cdn.js';
 export { createAphexApi, mountAphexBuiltins, toHonoHandler, type AphexEnv } from './api/index.js';
+export * from '../jobs/index.js';
 export * from '../schema-utils/index.js';
 export { createHashForPublishing } from '../utils/content-hash.js';
 export { getPreviewPerspective, type PreviewPerspective } from '../preview/perspective.js';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/server/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAE/B,cAAc,kBAAkB,CAAC;AAEjC,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxF,cAAc,wBAAwB,CAAC;AAGvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAKzD,OAAO,EAAE,GAAG,IAAI,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG/F,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGxF,OAAO,EACN,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACN,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACN,iBAAiB,EACjB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/server/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAE/B,cAAc,kBAAkB,CAAC;AAEjC,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gBAAgB,CAAC;AAE/B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxF,cAAc,wBAAwB,CAAC;AAGvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAKzD,OAAO,EAAE,GAAG,IAAI,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG/F,cAAc,eAAe,CAAC;AAG9B,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGxF,OAAO,EACN,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACN,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACN,iBAAiB,EACjB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,MAAM,cAAc,CAAC"}

package/dist/server/index.js

@@ -5,6 +5,7 @@ export * from '../types/index.js';
 export * from '../auth/provider.js';
 export * from '../cache/index.js';
 export * from '../email/index.js';
+export * from '../ai/index.js';
 // Authentication errors
 export { AuthError } from '../auth/auth-errors.js';
 // Configuration system
@@ -32,6 +33,8 @@ export { GET as serveAssetCDN } from '../routes/assets-cdn.js';
 // Hono API app — exposed so user apps (and tests) can construct or extend
 // the same router the SK catch-all forwards to.
 export { createAphexApi, mountAphexBuiltins, toHonoHandler } from './api/index.js';
+// Job execution — the DB-backed job runner (claim → run handler → complete/retry/fail).
+export * from '../jobs/index.js';
 // Schema utilities
 export * from '../schema-utils/index.js';
 // Content hash utilities (server-side)

package/dist/services/version-service.d.ts

@@ -17,18 +17,34 @@ export declare class VersionService {
      * Create a version snapshot and enforce rolling retention.
      */
     createVersion(db: DatabaseAdapter, organizationId: string, documentId: string, eventType: 'draft' | 'publish', data: any, userId?: string | null): Promise<DocumentVersion | null>;
+    /**
+     * Write a version snapshot on an already-transactional adapter. The caller owns
+     * the transaction boundary and retention (call `enforceRetentionFor` post-commit).
+     * No-op when the adapter has no versioning support.
+     */
+    snapshotTx(tx: DatabaseAdapter, organizationId: string, documentId: string, eventType: 'draft' | 'publish', data: any, userId?: string | null): Promise<void>;
+    /**
+     * Publish + snapshot on an already-transactional adapter. Caller owns the tx
+     * and retention. Returns the published document (or null if publish was a no-op).
+     */
+    publishTx(tx: DatabaseAdapter, organizationId: string, documentId: string, expectedRevision?: number): Promise<Document | null>;
+    /**
+     * Public retention trigger for callers that manage their own transaction and
+     * therefore can't rely on `saveWithVersion`/`publishWithVersion` to run it.
+     */
+    enforceRetentionFor(db: DatabaseAdapter, organizationId: string, documentId: string): Promise<void>;
     /**
      * Save draft and create version atomically using adapter transaction.
      */
-    saveWithVersion(db: DatabaseAdapter, organizationId: string, documentId: string, data: any, userId?: string): Promise<Document | null>;
+    saveWithVersion(db: DatabaseAdapter, organizationId: string, documentId: string, data: any, userId?: string, expectedRevision?: number): Promise<Document | null>;
     /**
      * Publish and create version.
      */
-    publishWithVersion(db: DatabaseAdapter, organizationId: string, documentId: string): Promise<Document | null>;
+    publishWithVersion(db: DatabaseAdapter, organizationId: string, documentId: string, expectedRevision?: number): Promise<Document | null>;
     /**
      * Restore a version to draft. Creates a 'draft' version entry.
      */
-    restoreVersion(db: DatabaseAdapter, organizationId: string, documentId: string, versionNumber: number, userId?: string): Promise<Document | null>;
+    restoreVersion(db: DatabaseAdapter, organizationId: string, documentId: string, versionNumber: number, userId?: string, expectedRevision?: number): Promise<Document | null>;
     listVersions(db: DatabaseAdapter, organizationId: string, documentId: string, options?: {
         limit?: number;
         offset?: number;

package/dist/services/version-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version-service.d.ts","sourceRoot":"","sources":["../../src/lib/services/version-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE7E;;;;;;GAMG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAI9C;;OAEG;IACG,aAAa,CAClB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAelC;;OAEG;IACG,eAAe,CACpB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA2B3B;;OAEG;IACG,kBAAkB,CACvB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAsC3B;;OAEG;IACG,cAAc,CACnB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAqCrB,YAAY,CACjB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,mBAAmB,CAAC;IAKzB,UAAU,CACf,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;YAKpB,gBAAgB;CAuB9B"}
+{"version":3,"file":"version-service.d.ts","sourceRoot":"","sources":["../../src/lib/services/version-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG7E;;;;;;GAMG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAI9C;;OAEG;IACG,aAAa,CAClB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAelC;;;;OAIG;IACG,UAAU,CACf,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,IAAI,CAAC;IAWhB;;;OAGG;IACG,SAAS,CACd,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,gBAAgB,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoB3B;;;OAGG;IACG,mBAAmB,CACxB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAIhB;;OAEG;IACG,eAAe,CACpB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,GAAG,EACT,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAwB3B;;OAEG;IACG,kBAAkB,CACvB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,gBAAgB,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAiB3B;;OAEG;IACG,cAAc,CACnB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA6BrB,YAAY,CACjB,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,mBAAmB,CAAC;IAKzB,UAAU,CACf,EAAE,EAAE,eAAe,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;YAKpB,gBAAgB;CAuB9B"}

package/dist/services/version-service.js

@@ -1,3 +1,4 @@
+import { emitDocumentPublished } from '../events/emit.js';
 /**
  * VersionService — orchestrates document versioning with rolling retention.
  *
@@ -27,98 +28,103 @@ export class VersionService {
         return version;
     }
     /**
-     * Save draft and create version atomically using adapter transaction.
+     * Write a version snapshot on an already-transactional adapter. The caller owns
+     * the transaction boundary and retention (call `enforceRetentionFor` post-commit).
+     * No-op when the adapter has no versioning support.
+     */
+    async snapshotTx(tx, organizationId, documentId, eventType, data, userId) {
+        if (!tx.createDocumentVersion)
+            return;
+        await tx.createDocumentVersion({
+            documentId,
+            organizationId,
+            eventType,
+            data,
+            createdBy: userId
+        });
+    }
+    /**
+     * Publish + snapshot on an already-transactional adapter. Caller owns the tx
+     * and retention. Returns the published document (or null if publish was a no-op).
      */
-    async saveWithVersion(db, organizationId, documentId, data, userId) {
-        if (db.withTransaction && db.createDocumentVersion) {
-            const updated = await db.withTransaction(async (txAdapter) => {
-                const result = await txAdapter.updateDocDraft(organizationId, documentId, data, userId);
-                if (result) {
-                    await txAdapter.createDocumentVersion({
-                        documentId,
-                        organizationId,
-                        eventType: 'draft',
-                        data,
-                        createdBy: userId
-                    });
-                }
-                return result;
-            });
-            if (updated)
-                await this.enforceRetention(db, documentId, organizationId);
-            return updated;
+    async publishTx(tx, organizationId, documentId, expectedRevision) {
+        const result = await tx.publishDoc(organizationId, documentId, expectedRevision);
+        if (result) {
+            await this.snapshotTx(tx, organizationId, documentId, 'publish', result.publishedData, result.updatedBy);
+            // Transactional outbox: record the durable fact in the same tx as the publish, so
+            // the event and the state change commit (or roll back) together — a consumer can
+            // never see a publish that didn't happen, nor miss one that did. The non-versioned
+            // publish path (collection-api) emits the same event via the same helper.
+            await emitDocumentPublished(tx, organizationId, result);
         }
-        // Fallback: non-atomic
-        const updated = await db.updateDocDraft(organizationId, documentId, data, userId);
-        if (updated) {
-            await this.createVersion(db, organizationId, documentId, 'draft', data, userId);
+        return result;
+    }
+    /**
+     * Public retention trigger for callers that manage their own transaction and
+     * therefore can't rely on `saveWithVersion`/`publishWithVersion` to run it.
+     */
+    async enforceRetentionFor(db, organizationId, documentId) {
+        await this.enforceRetention(db, documentId, organizationId);
+    }
+    /**
+     * Save draft and create version atomically using adapter transaction.
+     */
+    async saveWithVersion(db, organizationId, documentId, data, userId, expectedRevision) {
+        // No versioning support: a single write, atomic on its own.
+        if (!db.createDocumentVersion) {
+            return db.updateDocDraft(organizationId, documentId, data, userId, expectedRevision);
         }
+        // RevisionConflictError propagates out of the transaction un-swallowed —
+        // callers must surface it distinctly from a validation error.
+        const updated = await db.withTransaction(async (txAdapter) => {
+            const result = await txAdapter.updateDocDraft(organizationId, documentId, data, userId, expectedRevision);
+            if (result)
+                await this.snapshotTx(txAdapter, organizationId, documentId, 'draft', data, userId);
+            return result;
+        });
+        if (updated)
+            await this.enforceRetention(db, documentId, organizationId);
         return updated;
     }
     /**
      * Publish and create version.
      */
-    async publishWithVersion(db, organizationId, documentId) {
+    async publishWithVersion(db, organizationId, documentId, expectedRevision) {
         // Publish + version snapshot must commit together: a crash between them
         // would leave a published document with no 'publish' version row. Mirror
         // saveWithVersion / restoreVersion and run both writes in one transaction.
-        if (db.withTransaction && db.createDocumentVersion) {
-            const published = await db.withTransaction(async (txAdapter) => {
-                const result = await txAdapter.publishDoc(organizationId, documentId);
-                if (result) {
-                    await txAdapter.createDocumentVersion({
-                        documentId,
-                        organizationId,
-                        eventType: 'publish',
-                        data: result.publishedData,
-                        createdBy: result.updatedBy
-                    });
-                }
-                return result;
-            });
-            if (published)
-                await this.enforceRetention(db, documentId, organizationId);
-            return published;
+        // No versioning support: a single write, atomic on its own.
+        if (!db.createDocumentVersion) {
+            return db.publishDoc(organizationId, documentId, expectedRevision);
         }
-        // Fallback: non-atomic (adapter without transaction/versioning support)
-        const published = await db.publishDoc(organizationId, documentId);
-        if (!published)
-            return null;
-        await this.createVersion(db, organizationId, documentId, 'publish', published.publishedData, published.updatedBy);
+        const published = await db.withTransaction((txAdapter) => this.publishTx(txAdapter, organizationId, documentId, expectedRevision));
+        if (published)
+            await this.enforceRetention(db, documentId, organizationId);
         return published;
     }
     /**
      * Restore a version to draft. Creates a 'draft' version entry.
      */
-    async restoreVersion(db, organizationId, documentId, versionNumber, userId) {
+    async restoreVersion(db, organizationId, documentId, versionNumber, userId, expectedRevision) {
         if (!db.getDocumentVersion)
             return null;
         const version = await db.getDocumentVersion(organizationId, documentId, versionNumber);
         if (!version)
             return null;
-        if (db.withTransaction && db.createDocumentVersion) {
-            const restored = await db.withTransaction(async (txAdapter) => {
-                const result = await txAdapter.updateDocDraft(organizationId, documentId, version.data, userId);
-                if (result) {
-                    await txAdapter.createDocumentVersion({
-                        documentId,
-                        organizationId,
-                        eventType: 'draft',
-                        data: version.data,
-                        createdBy: userId
-                    });
-                }
-                return result;
-            });
-            if (restored)
-                await this.enforceRetention(db, documentId, organizationId);
-            return restored;
-        }
-        // Fallback: non-atomic
-        const restored = await db.updateDocDraft(organizationId, documentId, version.data, userId);
-        if (restored) {
-            await this.createVersion(db, organizationId, documentId, 'draft', version.data, userId);
+        // A restore is itself a draft write — just as capable of clobbering a
+        // concurrent edit as a normal save, so it goes through the same CAS guard.
+        // No versioning support: a single write, atomic on its own.
+        if (!db.createDocumentVersion) {
+            return db.updateDocDraft(organizationId, documentId, version.data, userId, expectedRevision);
         }
+        const restored = await db.withTransaction(async (txAdapter) => {
+            const result = await txAdapter.updateDocDraft(organizationId, documentId, version.data, userId, expectedRevision);
+            if (result)
+                await this.snapshotTx(txAdapter, organizationId, documentId, 'draft', version.data, userId);
+            return result;
+        });
+        if (restored)
+            await this.enforceRetention(db, documentId, organizationId);
         return restored;
     }
     async listVersions(db, organizationId, documentId, options) {

package/dist/type-gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-gen.d.ts","sourceRoot":"","sources":["../src/lib/type-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAoJzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAG3E;AA6VD;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8I3D;AAgGD,wBAAsB,uBAAuB,CAC5C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAoDf"}
+{"version":3,"file":"type-gen.d.ts","sourceRoot":"","sources":["../src/lib/type-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAoJzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAG3E;AA6VD;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8I3D;AA2GD,wBAAsB,uBAAuB,CAC5C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/type-gen.js

@@ -573,6 +573,17 @@ async function compileAndImportModule(absolutePath, tempName, opts = {}) {
                 {
                     name: 'remove-icons',
                     setup(build) {
+                        // SvelteKit's `$env/*` virtual modules (dynamic/static, public/private)
+                        // only exist inside Vite — plain esbuild can't resolve them. A
+                        // plugin/schema module may import one just to read a default config
+                        // value, which never affects the generated types, so stub it out to
+                        // an empty object rather than fail the whole build.
+                        build.onResolve({ filter: /^\$env\// }, (args) => {
+                            return { path: args.path, namespace: 'env-stub' };
+                        });
+                        build.onLoad({ filter: /.*/, namespace: 'env-stub' }, () => {
+                            return { contents: 'export const env = {};', loader: 'js' };
+                        });
                         build.onResolve({ filter: /^@lucide\/svelte/ }, (args) => {
                             return { path: args.path, namespace: 'lucide-stub' };
                         });

package/dist/types/agent-change-sets.d.ts

@@ -0,0 +1,70 @@
+export type AgentChangeSetStatus = 'in_progress' | 'completed' | 'failed';
+/** One agent turn. Created eagerly, before the model is even called, so token usage is
+ * captured regardless of whether the turn ends up mutating anything. */
+export interface AgentChangeSet {
+    id: string;
+    organizationId: string;
+    createdBy: string | null;
+    status: AgentChangeSetStatus;
+    /** The turn's first user message, truncated — a human-readable label for the activity list. */
+    summary: string | null;
+    /** `AIProviderAdapter.name`, e.g. `'anthropic'` / `'openai'` / `'openrouter'`. */
+    provider: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    createdAt: Date;
+    completedAt: Date | null;
+}
+export interface CreateAgentChangeSetInput {
+    organizationId: string;
+    createdBy?: string | null;
+    summary?: string | null;
+    provider: string;
+    model: string;
+}
+export interface CompleteAgentChangeSetInput {
+    status: AgentChangeSetStatus;
+    promptTokens?: number;
+    completionTokens?: number;
+}
+/** One mutating tool call within a turn. `versionBefore` is what an undo restores to — null
+ * means there's nothing to restore to (e.g. this was a `create_document`, which isn't
+ * undoable in this pass). */
+export interface AgentOperation {
+    id: string;
+    changeSetId: string;
+    organizationId: string;
+    collection: string;
+    documentId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    success: boolean;
+    error: string | null;
+    versionBefore: number | null;
+    versionAfter: number | null;
+    createdAt: Date;
+}
+export interface RecordAgentOperationInput {
+    changeSetId: string;
+    organizationId: string;
+    collection: string;
+    documentId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    success: boolean;
+    error?: string | null;
+    versionBefore?: number | null;
+    versionAfter?: number | null;
+}
+/** A change-set with its operations attached — what the undo endpoint and the activity
+ * detail view both need. */
+export interface AgentChangeSetWithOperations extends AgentChangeSet {
+    operations: AgentOperation[];
+}
+export interface ListAgentChangeSetsOptions {
+    organizationId: string;
+    limit?: number;
+    offset?: number;
+}
+//# sourceMappingURL=agent-change-sets.d.ts.map

package/dist/types/agent-change-sets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-change-sets.d.ts","sourceRoot":"","sources":["../../src/lib/types/agent-change-sets.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1E;wEACwE;AACxE,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,+FAA+F;IAC/F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,2BAA2B;IAC3C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;6BAE6B;AAC7B,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;4BAC4B;AAC5B,MAAM,WAAW,4BAA6B,SAAQ,cAAc;IACnE,UAAU,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types/agent-change-sets.js

@@ -0,0 +1,6 @@
+// Dialect-agnostic shapes for the agent audit/undo trail — mirrors `types/events.ts`'s
+// relationship to `cms_domain_events`/`cms_jobs`, but for `cms_agent_change_sets`/
+// `cms_agent_operations`. One `AgentChangeSet` row per agent turn (not per mutation — a
+// pure Q&A turn still costs tokens and is still worth an audit/cost row), with zero or more
+// `AgentOperation` children recording the mutating tool calls that turn made.
+export {};

package/dist/types/agent-stream.d.ts

@@ -0,0 +1,60 @@
+import type { AIMessage } from '../ai/interfaces/ai-provider.js';
+/** One event in an agent turn's response stream. */
+export type AgentStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'toolCall';
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'toolResult';
+    toolCallId: string;
+    name: string;
+    success: boolean;
+    data?: unknown;
+    /** Present when `success` is false — a message safe to show the model/user. */
+    error?: string;
+} | {
+    type: 'usage';
+    promptTokens: number;
+    completionTokens: number;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+    /**
+     * `'awaiting_workspace_tool'` means the model requested one or more
+     * `execution: 'workspace'` tool calls this round — those can only be executed by
+     * the browser (they touch a live, possibly-unsaved editor draft), so the server
+     * stopped short of resolving them. `pendingWorkspaceCalls` lists exactly which
+     * ones need a result before the turn can continue; the caller resolves them
+     * locally, appends `tool` messages, and re-POSTs to resume — see
+     * `server/api/routes/agent-chat.ts` and `AgentChat.svelte`.
+     */
+    finishReason: 'stop' | 'tool_calls' | 'length' | 'error' | 'awaiting_workspace_tool';
+    /**
+     * The complete running conversation, including every intermediate
+     * `assistant`(toolCalls)/`tool` message this turn produced — not just the final
+     * user-visible text. `/api/agent/chat` is stateless per call, so the caller is
+     * expected to resend this wholesale as `messages` on the next turn rather than
+     * reconstructing it client-side (easy to get subtly wrong — see the history bug
+     * this replaced).
+     */
+    messages: AIMessage[];
+    /** Only present when `finishReason === 'awaiting_workspace_tool'`. */
+    pendingWorkspaceCalls?: {
+        toolCallId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[];
+    /**
+     * Stamped by `agent-chat.ts` (not `runAgentTurn`, which has no DB access) on every
+     * `done` event so a resume request can echo it back and the audit trail's
+     * `cms_agent_change_sets` row stays the same across a paused turn's multiple legs.
+     */
+    changeSetId?: string | null;
+};
+//# sourceMappingURL=agent-stream.d.ts.map

package/dist/types/agent-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stream.d.ts","sourceRoot":"","sources":["../../src/lib/types/agent-stream.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1F;IACA,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CACd,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IACA,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,yBAAyB,CAAC;IACrF;;;;;;;OAOG;IACH,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,sEAAsE;IACtE,qBAAqB,CAAC,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,EAAE,CAAC;IACJ;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC"}

package/dist/types/agent-stream.js

@@ -0,0 +1,11 @@
+// types/agent-stream.ts
+//
+// Browser-facing stream contract for an agent turn — what an SSE/NDJSON chat
+// endpoint actually sends over the wire. Deliberately close to `AIProviderAdapter`'s `AIStreamEvent`
+// (ai/interfaces/ai-provider.ts) since most events pass through unchanged — this type
+// adds the one thing the provider boundary doesn't have: the *result* of a tool call
+// the runtime executed, which the browser needs to render (and which the model needs
+// fed back as a `tool` message for the next round trip).
+//
+// Client-safe: no DB handles, no provider SDKs, just the wire shape.
+export {};

package/dist/types/agent-tools.d.ts

@@ -0,0 +1,65 @@
+import type { z } from 'zod';
+import type { Capability } from './capabilities.js';
+import type { CMSInstances } from '../hooks.js';
+import type { LocalAPIContext } from '../local-api/index.js';
+/**
+ * Where a tool's `execute` actually runs.
+ *
+ * - `server`: runs entirely in this process against the database — the vast
+ *   majority of tools (read, patch, publish, ...).
+ * - `workspace`: must round-trip to a live editor tab holding the in-progress
+ *   draft (e.g. "apply this change to what's currently open, unsaved, in the
+ *   browser"). `run-agent-turn.ts` never calls `execute` for a tool declared
+ *   this way — it pauses the turn instead (`AgentStreamEvent`'s
+ *   `awaiting_workspace_tool` finish reason) and the caller resolves it
+ *   client-side against a `DocumentWorkspace` (types/document-workspace.ts),
+ *   then resumes. Only advertised at all when `resolveAgentTools` is given a
+ *   `documentContext` (mcp/tools.ts) — see `ai/content-workspace-tools.ts` for
+ *   the two tools that currently use this mode.
+ */
+export type AgentToolExecutionMode = 'server' | 'workspace';
+/**
+ * Serializable description of a tool — the part an LLM/UI needs to know a
+ * tool exists and how to call it, without knowing how to run it.
+ */
+export interface AgentToolDefinition<TInput = unknown> {
+    /** Unique, namespaced by package to avoid collisions (e.g. `content_patch_fields`). */
+    name: string;
+    description: string;
+    /**
+     * Whether invoking this tool can change stored data. A coarse, cheap-to-display
+     * hint for approval flows and audit — not itself an authorization mechanism
+     * (`requiredCapabilities` is what's actually enforced).
+     */
+    mutates: boolean;
+    /**
+     * Capabilities required to see AND to invoke this tool — checked at both
+     * advertisement (don't list a tool the caller can't use) and execution
+     * (don't trust the advertisement check alone). A tool hidden from an
+     * unauthorized caller must also reject direct invocation.
+     */
+    requiredCapabilities: Capability[];
+    execution: AgentToolExecutionMode;
+    /** zod schema for the tool's arguments — single source of truth for validation. */
+    inputSchema: z.ZodType<TInput>;
+}
+/** Outcome of a single tool call. */
+export interface AgentToolResult {
+    success: boolean;
+    data?: unknown;
+    /** Present when `success` is false — a message safe to show the model/user. */
+    error?: string;
+}
+/** Everything an `execute` function needs to act on behalf of the calling request. */
+export interface AgentToolExecutionContext {
+    aphexCMS: CMSInstances;
+    context: LocalAPIContext;
+}
+/**
+ * Runs a tool call. Receives services via `ctx` at call time rather than
+ * static import, so a module defining an executor never has a heavy/server
+ * import at its top level — safe to sit alongside a definition in a plugin
+ * part that's also referenced from client-shared code.
+ */
+export type AgentToolExecutor<TInput = unknown> = (input: TInput, ctx: AgentToolExecutionContext) => Promise<AgentToolResult>;
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/types/agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/lib/types/agent-tools.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,MAAM,GAAG,OAAO;IACpD,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,oBAAoB,EAAE,UAAU,EAAE,CAAC;IACnC,SAAS,EAAE,sBAAsB,CAAC;IAClC,mFAAmF;IACnF,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,GAAG,OAAO,IAAI,CACjD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,yBAAyB,KAC1B,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/dist/types/agent-tools.js

@@ -0,0 +1 @@
+export {};