@jini-ai/cms 0.1.0

package/dist/core/commands/command.js

@@ -0,0 +1,173 @@
+/**
+ * Thrown when a command's idempotency key was already used in the workspace.
+ * Callers should re-read current state instead of retrying the mutation.
+ */
+export class DuplicateCommandError extends Error {
+    changeSetId;
+    constructor(message, changeSetId) {
+        super(message);
+        this.changeSetId = changeSetId;
+    }
+}
+/**
+ * Thrown when `authorize()` denies the caller. Routes map
+ * this to 403 `FORBIDDEN`. Raised before the idempotency check (INV-04) — a
+ * replayed command id from a denied caller therefore never produces
+ * `DuplicateCommandError` either (EC-08).
+ */
+export class ForbiddenError extends Error {
+    permission;
+    reason;
+    constructor(message, permission, reason) {
+        super(message);
+        this.permission = permission;
+        this.reason = reason;
+    }
+}
+/**
+ * Detects a UNIQUE-constraint violation on `changeSets.insert()`'s idempotency-key index —
+ * the losing side of the TOCTOU race between the pre-execute `findByIdempotencyKey` check and
+ * this same key's insert (two concurrent requests can both pass the check before either inserts;
+ * the DB's real unique index then rejects the second write). Duck-typed on `.code` rather than an
+ * `instanceof` class check: `core/commands` stays storage-agnostic (see this file's header — it
+ * never imports a SQLite adapter), and `better-sqlite3`'s `SqliteError` is not a dependency here.
+ * `SQLITE_CONSTRAINT_UNIQUE` is deliberately not treated as conclusive on its own — a caller must
+ * still re-query for the winning row (see `executeCommand`'s catch block) before trusting this,
+ * since an adapter could throw the same code for an unrelated UNIQUE index.
+ */
+function isIdempotencyKeyConflict(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "SQLITE_CONSTRAINT_UNIQUE");
+}
+/**
+ * Execute a mutation through the command gateway.
+ *
+ * Order matters: idempotency check → inverse capture → execute → record.
+ * If execute throws, nothing is recorded; if inverse capture throws, the
+ * mutation never runs.
+ *
+ * The feature mutation and its change-set record commit as one unit of work
+ * (REQ-01): if `changeSets.insert` fails after `execute` has applied the
+ * mutation, the gateway rolls the mutation back via `mutation.rollback` and
+ * re-throws, so no change set and no outbox event survive (EC-08 / AC-17,
+ * INV-01).
+ *
+ * The `change-set.applied` event is passed as `changeSets.insert()`'s third argument, not a
+ * separate `deps.outbox.enqueue()` call afterward — a durable adapter co-persists it inside the
+ * same transaction as the change-set record, so it can never land without a durable delivery
+ * record (or vice versa). This still does NOT cover the domain mutation itself
+ * (`mutation.execute()` stays outside any shared transaction, covered only by the compensating
+ * rollback above), and it covers only this producer. See
+ * `docs/decisions/change-set-outbox-transaction-boundary.md` for the full rationale, including the
+ * other direct `OutboxPort.enqueue()` producers this decision deliberately leaves untouched.
+ */
+export async function executeCommand(required, _optional = {}) {
+    const { deps, command, mutation } = required;
+    // authorize() runs BEFORE the idempotency check, so
+    // a denied caller never learns whether a replayed command id previously
+    // succeeded (no DUPLICATE_COMMAND / changeSetId leak, EC-08). `permission`
+    // and `authorize` are wired together or not at all (see ExecuteCommandDeps
+    // doc) — partial wiring is a programming error, not a silent allow/skip.
+    if (Boolean(deps.authorize) !== Boolean(command.permission)) {
+        throw new Error("executeCommand: command.permission and deps.authorize must be supplied together " +
+            "— partial wiring would silently skip or misapply authorization");
+    }
+    if (deps.authorize && command.permission) {
+        const authResult = await deps.authorize({
+            principalId: command.actor.id,
+            permission: command.permission,
+            workspaceId: command.workspaceId,
+            entityType: mutation.entityType,
+            entityId: mutation.entityId,
+        });
+        if (!authResult.allowed) {
+            throw new ForbiddenError(`principal '${command.actor.id}' is not authorized for '${command.permission}' (${authResult.reason})`, command.permission, authResult.reason);
+        }
+    }
+    if (command.idempotencyKey) {
+        const existing = await deps.changeSets.findByIdempotencyKey({
+            workspaceId: command.workspaceId,
+            idempotencyKey: command.idempotencyKey,
+        });
+        if (existing) {
+            throw new DuplicateCommandError(`command with idempotency key '${command.idempotencyKey}' was already executed`, existing.id);
+        }
+    }
+    const inversePayload = await mutation.captureInverse();
+    const result = await mutation.execute();
+    const entityVersionAtApply = mutation.captureEntityVersion?.(result) ?? undefined;
+    const now = deps.clock.nowIso();
+    const changeSetId = deps.idGen.newId();
+    // BR-04: the event rides into insert()'s third argument (see this function's doc comment) so a
+    // durable adapter co-persists it atomically with the record it belongs to. Built unconditionally
+    // (cheap, pure data) but only passed through when an outbox is actually wired.
+    const event = {
+        id: deps.idGen.newId(),
+        name: "change-set.applied",
+        occurredAt: now,
+        aggregateId: changeSetId,
+        workspaceId: command.workspaceId,
+        actorId: command.actor.id,
+        changeSetId,
+        payload: {
+            changeSetId,
+            entityType: mutation.entityType,
+            entityId: mutation.entityId,
+        },
+    };
+    // Unit of work: the change-set record (and, when an outbox is wired, its delivery event) must
+    // land together, or the feature mutation is rolled back (REQ-01 / EC-08). On the in-memory
+    // adapter this is a compensating restore via `mutation.rollback`; the SQLite adapter does this
+    // as one real transaction and the rollback becomes a no-op for this step.
+    try {
+        await deps.changeSets.insert({
+            id: changeSetId,
+            workspaceId: command.workspaceId,
+            actorId: command.actor.id,
+            status: "applied",
+            summary: command.summary,
+            idempotencyKey: command.idempotencyKey,
+            intentRef: command.intentRef,
+            createdAt: now,
+            appliedAt: now,
+        }, [
+            {
+                id: deps.idGen.newId(),
+                changeSetId,
+                entityType: mutation.entityType,
+                entityId: mutation.entityId,
+                operation: mutation.operation,
+                inversePayload: inversePayload ?? undefined,
+                entityVersionAtApply,
+                position: 0,
+            },
+        ], deps.outbox ? event : undefined);
+    }
+    catch (recordError) {
+        // AC-17 / EC-08: the mutation applied but its record did not. Undo the
+        // mutation so INV-01 holds (no mutation without a record). We surface the
+        // original persist error; a rollback that itself throws is a harder failure
+        // that the SQLite transaction path is designed to remove.
+        await mutation.rollback?.();
+        // TOCTOU: the idempotency check above and this insert are separated by
+        // `captureInverse`/`execute`, so two concurrent requests on the same key can both pass the
+        // check before either inserts — the DB's unique index then rejects the loser here instead of
+        // at the check. Re-throw as the intended `DuplicateCommandError` (referencing the WINNING
+        // change set) rather than letting the raw driver error escape, so callers' existing
+        // `instanceof DuplicateCommandError` handling (409) catches this race the same as the
+        // already-covered non-racing replay.
+        if (command.idempotencyKey && isIdempotencyKeyConflict(recordError)) {
+            const winner = await deps.changeSets.findByIdempotencyKey({
+                workspaceId: command.workspaceId,
+                idempotencyKey: command.idempotencyKey,
+            });
+            if (winner) {
+                throw new DuplicateCommandError(`command with idempotency key '${command.idempotencyKey}' was already executed`, winner.id);
+            }
+        }
+        throw recordError;
+    }
+    return { result, changeSetId };
+}
+//# sourceMappingURL=command.js.map

package/dist/core/commands/command.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file `@jini-ai/cms/core` — the framework-free kernel of the CMS capability.
+ *
+ * ## What belongs here
+ *
+ * Everything that must run in any JavaScript runtime: the shared runtime ports (clock, id
+ * generation, outbox, domain events), the auditable mutation write path, and the tool-registration
+ * kit every domain's agent-tool layer builds on. No Express, no `node:*`, no DOM, no concrete
+ * adapters.
+ *
+ * ## What belongs in `../server`
+ *
+ * Only the Node-bound half: concrete repository implementations (SQLite/Postgres), filesystem blob
+ * stores, and anything importing `node:*`.
+ *
+ * ## Why the split is drawn here, and why it is enforced by `exports` rather than convention
+ *
+ * This mirrors a defect measured in the CMS runtime this is ported from. There, the content model
+ * and its HTTP composition root lived in one `src/` tree with no enforced boundary, and 53 import
+ * edges ended up pointing *into* the composition root — including 22 domain modules importing a
+ * 454-line route-deps type whose first line was `import type { Express } from "express"`. The
+ * consequence, visible in git history, was that no content module could be changed without also
+ * changing the server: its theme module and its server co-changed in 71% of commits touching the
+ * former.
+ *
+ * A package's `exports` map is exactly the enforcement a single `src/` tree cannot provide: a
+ * consumer of `@jini-ai/cms/core` physically cannot reach a Node adapter, and `/core` physically
+ * cannot import a transport type, because the module resolver refuses it. Keep it that way — if a
+ * core module wants something from `/server`, the dependency is pointing the wrong way and the fix
+ * is a port (interface) in core, not a widened export.
+ *
+ * ## Why the barrel does not re-export `./commands/appliers`
+ *
+ * There is no `appliers` module here, and that is deliberate rather than an oversight. In the
+ * source repo the equivalent barrel re-exported an inverse-applier registry that named two specific
+ * content features by import. Because every domain's tool layer reaches the kernel, that single
+ * re-export put a dependency on those two features into every domain module in the tree — the
+ * measured reason no domain could be extracted on its own. A per-entity applier registry belongs
+ * behind a registration call the host makes, not behind a kernel barrel.
+ */
+export type { UUID, ISODateTime, JsonPrimitive, JsonValue, JsonObject, JsonArray, DomainEvent, EventBusPort, OutboxRecord, OutboxPort, ClockPort, IdGeneratorPort, } from './ports.js';
+export type { ChangeSetStatus, ChangeSetOperation, ChangeSetRecord, ChangeSetItemRecord, ChangeSetWithItems, ChangeSetRepoPort, } from './commands/change-set.js';
+export * from './commands/command.js';
+export * from './tools/registration-kit.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,YAAY,EACV,IAAI,EACJ,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,43 @@
+/**
+ * @file `@jini-ai/cms/core` — the framework-free kernel of the CMS capability.
+ *
+ * ## What belongs here
+ *
+ * Everything that must run in any JavaScript runtime: the shared runtime ports (clock, id
+ * generation, outbox, domain events), the auditable mutation write path, and the tool-registration
+ * kit every domain's agent-tool layer builds on. No Express, no `node:*`, no DOM, no concrete
+ * adapters.
+ *
+ * ## What belongs in `../server`
+ *
+ * Only the Node-bound half: concrete repository implementations (SQLite/Postgres), filesystem blob
+ * stores, and anything importing `node:*`.
+ *
+ * ## Why the split is drawn here, and why it is enforced by `exports` rather than convention
+ *
+ * This mirrors a defect measured in the CMS runtime this is ported from. There, the content model
+ * and its HTTP composition root lived in one `src/` tree with no enforced boundary, and 53 import
+ * edges ended up pointing *into* the composition root — including 22 domain modules importing a
+ * 454-line route-deps type whose first line was `import type { Express } from "express"`. The
+ * consequence, visible in git history, was that no content module could be changed without also
+ * changing the server: its theme module and its server co-changed in 71% of commits touching the
+ * former.
+ *
+ * A package's `exports` map is exactly the enforcement a single `src/` tree cannot provide: a
+ * consumer of `@jini-ai/cms/core` physically cannot reach a Node adapter, and `/core` physically
+ * cannot import a transport type, because the module resolver refuses it. Keep it that way — if a
+ * core module wants something from `/server`, the dependency is pointing the wrong way and the fix
+ * is a port (interface) in core, not a widened export.
+ *
+ * ## Why the barrel does not re-export `./commands/appliers`
+ *
+ * There is no `appliers` module here, and that is deliberate rather than an oversight. In the
+ * source repo the equivalent barrel re-exported an inverse-applier registry that named two specific
+ * content features by import. Because every domain's tool layer reaches the kernel, that single
+ * re-export put a dependency on those two features into every domain module in the tree — the
+ * measured reason no domain could be extracted on its own. A per-entity applier registry belongs
+ * behind a registration call the host makes, not behind a kernel barrel.
+ */
+export * from './commands/command.js';
+export * from './tools/registration-kit.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AA0BH,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC"}

package/dist/core/ports.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @file Core port contracts for the CMS runtime.
+ *
+ * Purpose:
+ * Defines the stable interfaces that domain/application code depends on.
+ *
+ * How it relates to the project:
+ * - `features/*` import these contracts to stay framework/provider-agnostic.
+ * - `core/memory-bus.ts` provides in-memory implementations for local dev/tests.
+ * - `core/outbox-worker.ts` orchestrates reliable async delivery using these ports.
+ * - `server/app.ts` composes concrete implementations and runs the slice.
+ *
+ * Architectural role:
+ * This file is the dependency inversion seam. Concrete infrastructure can change
+ * without changing feature logic as long as implementations satisfy these types.
+ */
+/**
+ * Shared primitives and runtime ports used by the CMS core.
+ *
+ * Design goal:
+ * Core/domain code depends on interfaces from this file only, never on concrete
+ * infrastructure SDKs or framework-specific implementations.
+ */
+export type UUID = string;
+export type ISODateTime = string;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type JsonArray = JsonValue[];
+/**
+ * Immutable domain event emitted by synchronous command handlers and delivered
+ * asynchronously via the outbox pipeline.
+ */
+export interface DomainEvent<TPayload = Record<string, unknown>> {
+    /** Unique identifier for the event record. */
+    id: UUID;
+    /** Stable event name, e.g. `workspace.created`. */
+    name: string;
+    /** ISO timestamp describing when the event was produced. */
+    occurredAt: ISODateTime;
+    /** Optional aggregate root identifier related to this event. */
+    aggregateId?: UUID;
+    /**
+     * Tenant/workspace boundary. Required: every domain event belongs to a
+     * workspace. Platform-level events must be a deliberate future
+     * decision, not an omission.
+     */
+    workspaceId: UUID;
+    /**
+     * Principal (user or AI agent) that caused this event. Reserved change-set
+     * vocabulary; optional until the identity library lands.
+     */
+    actorId?: UUID;
+    /**
+     * Change set this event belongs to, enabling propose/preview/apply/revert
+     * grouping. Reserved change-set vocabulary.
+     */
+    changeSetId?: UUID;
+    /** Event-specific payload. */
+    payload: TPayload;
+    /** Free-form metadata (trace IDs, source, etc.). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event bus abstraction used by the application layer.
+ *
+ * This is intentionally generic so implementations can be in-memory, queue-based,
+ * broker-based, or provider-managed without changing domain logic.
+ */
+export interface EventBusPort {
+    /** Publish a single event to subscribers. */
+    publish<TPayload>(event: DomainEvent<TPayload>): Promise<void>;
+    /** Publish multiple events in order. */
+    publishBatch<TPayload>(events: Array<DomainEvent<TPayload>>): Promise<void>;
+    /**
+     * Subscribe a handler to an event name.
+     * Returns an async unsubscriber function.
+     */
+    subscribe<TPayload>(eventName: string, handler: (event: DomainEvent<TPayload>) => Promise<void>): Promise<() => Promise<void>>;
+    /**
+     * Subscribe a handler to every event published on this bus, regardless of name. Additive to
+     * `subscribe` — existing per-name callers are unaffected.
+     * The Integrations fan-out (`registerWebhookFanout`) is the first real consumer: it narrows
+     * by topic itself rather than requiring a fixed list of event names up front.
+     */
+    subscribeAll(handler: (event: DomainEvent) => Promise<void>): Promise<() => Promise<void>>;
+}
+/**
+ * Persisted outbox row used for reliable async event delivery.
+ */
+export interface OutboxRecord {
+    /** Primary key for the outbox row (same as `event.id`). */
+    id: UUID;
+    /**
+     * The full event envelope. The outbox must preserve everything the producer
+     * emitted (workspaceId, aggregateId, actorId, occurredAt, metadata) so
+     * delivery replays the original event, not a reconstruction.
+     */
+    event: DomainEvent;
+    /** Delivery lifecycle state. */
+    status: "pending" | "processing" | "delivered" | "failed";
+    /** Number of delivery attempts so far. */
+    attempts: number;
+    /** Retry eligibility timestamp. */
+    nextAttemptAt: ISODateTime;
+    /** Most recent delivery failure reason. */
+    lastError?: string;
+    /** Row creation timestamp. */
+    createdAt: ISODateTime;
+}
+/**
+ * Reliable outbox contract.
+ *
+ * Command handlers enqueue events here in the same unit of work as the write.
+ * A worker later claims and delivers rows to the event bus.
+ */
+export interface OutboxPort {
+    /** Append an event for later delivery. */
+    enqueue(event: DomainEvent): Promise<void>;
+    /** Claim pending rows for processing. */
+    claimPending(batchSize: number, nowIso: ISODateTime): Promise<OutboxRecord[]>;
+    /** Mark a row as delivered. */
+    markDelivered(id: UUID): Promise<void>;
+    /** Mark a row as failed and set next retry time. */
+    markFailed(id: UUID, error: string, nextAttemptAt: ISODateTime): Promise<void>;
+}
+/** Clock abstraction to make time deterministic in tests. */
+export interface ClockPort {
+    /** Current wall-clock time as ISO string. */
+    nowIso(): ISODateTime;
+}
+/** ID generator abstraction to keep ID strategy swappable and testable. */
+export interface IdGeneratorPort {
+    /** Create a new globally unique ID. */
+    newId(): UUID;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/core/ports.d.ts.map

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

package/dist/core/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/core/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/core/ports.ts"],"names":[],"mappings":""}