@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/copilot/entry-proposal.applier.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkSaveEntriesProposalApplier = exports.UpdateEntryProposalApplier = exports.CreateEntryProposalApplier = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const content_tokens_1 = require("../content.tokens");
+const entry_writer_service_1 = require("../entries/infrastructure/persistence/entry-writer.service");
+const workspace_grants_query_1 = require("../content-types/queries/workspace-grants.query");
+const proposal_kinds_1 = require("./proposal-kinds");
+/**
+ * Refuses a create that names a translation group — the shape these tools no
+ * longer offer.
+ *
+ * A create is a whole row: `coerceValues` stamps every declared field, so each
+ * shared field the change did not name arrives as `null`, and the i18n
+ * extension propagates a create's shared columns **outward** onto every sibling
+ * — blanking the record in every other language, and silently so where the
+ * siblings are all drafts. Doing it correctly means inheriting the source row's
+ * shared values at apply time, which is knowledge the i18n plugin owns; hence
+ * `i18n_propose_translation` / `i18n_propose_bulk_translation`.
+ *
+ * The schemas dropped `localeGroupId`, so nothing produces one any more. This
+ * guards the one case that outlives a schema: a proposal drafted before the
+ * change whose apply failed, left `pending`, and is carried out later.
+ */
+function assertStartsItsOwnGroup(localeGroupId) {
+    if (typeof localeGroupId === 'string' && localeGroupId.length > 0) {
+        throw new Error('This change would add a language to an existing record, which a content save ' +
+            'cannot do without blanking the record’s shared fields in every other ' +
+            'language. Translate with i18n_propose_translation or ' +
+            'i18n_propose_bulk_translation instead.');
+    }
+}
+/** Resolves a granted, registered type or throws — shared by both appliers. */
+async function grantedType(registry, grants, typeName, workspaceId) {
+    const name = typeof typeName === 'string' ? typeName : '';
+    const type = registry.get(name);
+    const granted = await grants.grantedSlugs(workspaceId);
+    if (!type || !granted.has(type.name)) {
+        throw new Error(`Unknown content type "${name}" in this workspace.`);
+    }
+    return type;
+}
+/**
+ * Applies `content.entry.create` — a new draft entry.
+ *
+ * **It calls `EntryWriterService.create`, the same method the POST route
+ * calls.** Not "similar to": the same. That is what makes an accepted proposal
+ * validated by `EntryValidationService`, wrapped in the workspace's shared
+ * advisory lock, snapshotted as revision 1, and passed through the bound i18n
+ * extension exactly as a hand-typed entry would be
+ * ([ADR-0005](../../../../../../docs/adr/0005-copilot-authority-model.md) §5).
+ * An applier that reimplemented the insert to "keep it simple" is the failure
+ * the port exists to prevent.
+ *
+ * The grants are re-checked here, not trusted from the proposal. The row was
+ * written when the proposal was made, and a workspace's content grants can be
+ * revoked in between — a stored `typeName` is an argument like any other.
+ */
+let CreateEntryProposalApplier = class CreateEntryProposalApplier {
+    registry;
+    writer;
+    grants;
+    kind = proposal_kinds_1.CONTENT_PROPOSAL_KINDS.createEntry;
+    constructor(registry, writer, grants) {
+        this.registry = registry;
+        this.writer = writer;
+        this.grants = grants;
+    }
+    async apply(input, actor) {
+        const type = await grantedType(this.registry, this.grants, input.target['typeName'], actor.workspaceId);
+        const values = (input.patch['values'] ?? {});
+        const locale = input.target['locale'];
+        assertStartsItsOwnGroup(input.target['localeGroupId']);
+        const entry = await this.writer.create(type, values, actor.workspaceId, 
+        // No relation *deltas*. An owning many-relation still lands: it
+        // travels as an array in `values`, which the writer turns into a
+        // whole-set link write. Deltas are the editor's incremental path
+        // and have no caller here.
+        undefined, typeof locale === 'string' ? locale : undefined, 
+        // No group to join — a create here always starts its own.
+        undefined, 
+        // The human who accepted is the actor on the write, on its revision
+        // and on the domain event it raises — never a copilot identity,
+        // which does not exist.
+        { id: actor.userId, email: actor.actorEmail });
+        return {
+            entityId: entry.id,
+            detail: { typeName: type.name, status: entry.status ?? 'draft' }
+        };
+    }
+};
+exports.CreateEntryProposalApplier = CreateEntryProposalApplier;
+exports.CreateEntryProposalApplier = CreateEntryProposalApplier = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_tokens_1.InjectContentRegistry)()),
+    tslib_1.__metadata("design:paramtypes", [Function, entry_writer_service_1.EntryWriterService,
+        workspace_grants_query_1.WorkspaceGrantsQuery])
+], CreateEntryProposalApplier);
+/**
+ * Applies `content.entry.update` — a change to an existing entry's values.
+ *
+ * **Merges rather than replaces.** The admin's `PATCH` replaces the whole
+ * values bag because the editor always submits the full document; a proposal
+ * carries only the fields a reviewer approved, so replacing would silently null
+ * everything they did not see. This is the same reasoning — and the same merge
+ * semantics — as the public API's partial update.
+ *
+ * The merge reads the entry **now**, not when the proposal was made, so a
+ * proposal accepted an hour later writes the approved fields onto whatever the
+ * entry has become instead of resurrecting a stale document. A reviewer
+ * approving "fix this typo" gets that typo fixed, not the rest of the entry
+ * rewound.
+ */
+let UpdateEntryProposalApplier = class UpdateEntryProposalApplier {
+    registry;
+    writer;
+    grants;
+    kind = proposal_kinds_1.CONTENT_PROPOSAL_KINDS.updateEntry;
+    constructor(registry, writer, grants) {
+        this.registry = registry;
+        this.writer = writer;
+        this.grants = grants;
+    }
+    async apply(input, actor) {
+        const type = await grantedType(this.registry, this.grants, input.target['typeName'], actor.workspaceId);
+        const entryId = input.target['entryId'];
+        if (typeof entryId !== 'string') {
+            throw new Error('This proposal names no entry.');
+        }
+        // 404s a missing or soft-deleted entry, workspace-scoped — so a
+        // proposal whose target was deleted before it was accepted fails with
+        // that reason rather than creating something.
+        const current = await this.writer.getOne(type, entryId, actor.workspaceId);
+        const patch = (input.patch['values'] ?? {});
+        const merged = { ...(current.values ?? {}), ...patch };
+        const entry = await this.writer.update(type, entryId, merged, actor.workspaceId, undefined, { id: actor.userId, email: actor.actorEmail });
+        return {
+            entityId: entry.id,
+            detail: {
+                typeName: type.name,
+                fields: Object.keys(patch),
+                status: entry.status ?? 'draft'
+            }
+        };
+    }
+};
+exports.UpdateEntryProposalApplier = UpdateEntryProposalApplier;
+exports.UpdateEntryProposalApplier = UpdateEntryProposalApplier = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_tokens_1.InjectContentRegistry)()),
+    tslib_1.__metadata("design:paramtypes", [Function, entry_writer_service_1.EntryWriterService,
+        workspace_grants_query_1.WorkspaceGrantsQuery])
+], UpdateEntryProposalApplier);
+/**
+ * Applies `content.entry.bulk-save` — a batch of creates and edits, carried out
+ * as one change.
+ *
+ * **Item by item through the same `EntryWriterService` methods the other two
+ * appliers call**, for the same reason they do: validation, the advisory lock,
+ * the revision snapshot and the i18n sibling sync all have to happen per entry,
+ * and a batch-shaped shortcut around any of them would be a second write path.
+ * Sequentially, not concurrently — each write takes the workspace's shared
+ * content lock, so a fan-out would mostly contend with itself.
+ *
+ * **It stops at the first failure and throws.** There is no per-item verdict to
+ * show: a proposal is one row with one status, and its card says "Saved" or
+ * "Not saved". Carrying on after a failure would grow the number of entries
+ * written under a receipt that then reports failure — so the batch halts, and
+ * the error names exactly how many landed, which is what the model reads back
+ * to the user. (The public API's `bulkSave` does the opposite and keeps going,
+ * because there the caller gets every item's verdict and can retry the ones it
+ * can fix.)
+ */
+let BulkSaveEntriesProposalApplier = class BulkSaveEntriesProposalApplier {
+    registry;
+    writer;
+    grants;
+    kind = proposal_kinds_1.CONTENT_PROPOSAL_KINDS.bulkSaveEntries;
+    constructor(registry, writer, grants) {
+        this.registry = registry;
+        this.writer = writer;
+        this.grants = grants;
+    }
+    async apply(input, actor) {
+        const type = await grantedType(this.registry, this.grants, input.target['typeName'], actor.workspaceId);
+        const items = input.patch['items'];
+        if (!Array.isArray(items) || items.length === 0) {
+            throw new Error('This change names no entries.');
+        }
+        const created = [];
+        const updated = [];
+        for (const [index, raw] of items.entries()) {
+            const item = (raw ?? {});
+            const values = (item.values ?? {});
+            const id = typeof item.id === 'string' ? item.id : undefined;
+            try {
+                if (id) {
+                    // Read now, not when the batch was proposed, so an item
+                    // written minutes later lands on whatever the entry has
+                    // become — the same merge rule the single-entry applier
+                    // states at length.
+                    const current = await this.writer.getOne(type, id, actor.workspaceId);
+                    const entry = await this.writer.update(type, id, { ...(current.values ?? {}), ...values }, actor.workspaceId, undefined, { id: actor.userId, email: actor.actorEmail });
+                    updated.push(entry.id);
+                }
+                else {
+                    assertStartsItsOwnGroup(item.localeGroupId);
+                    const entry = await this.writer.create(type, values, actor.workspaceId, undefined, typeof item.locale === 'string'
+                        ? item.locale
+                        : undefined, 
+                    // No group to join — see `assertStartsItsOwnGroup`.
+                    undefined, { id: actor.userId, email: actor.actorEmail });
+                    created.push(entry.id);
+                }
+            }
+            catch (error) {
+                const done = created.length + updated.length;
+                throw new Error(`Entry ${index + 1} of ${items.length} failed: ` +
+                    `${error instanceof Error ? error.message : String(error)}. ` +
+                    (done === 0
+                        ? 'Nothing was saved.'
+                        : `The first ${done} were saved and the rest were not.`));
+            }
+        }
+        return {
+            // No `entityId`: a batch has no single entity to link to, and
+            // naming one of them would send the user to an arbitrary member of
+            // the set. The ids are in `detail` instead.
+            detail: {
+                typeName: type.name,
+                created,
+                updated,
+                count: created.length + updated.length
+            }
+        };
+    }
+};
+exports.BulkSaveEntriesProposalApplier = BulkSaveEntriesProposalApplier;
+exports.BulkSaveEntriesProposalApplier = BulkSaveEntriesProposalApplier = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_tokens_1.InjectContentRegistry)()),
+    tslib_1.__metadata("design:paramtypes", [Function, entry_writer_service_1.EntryWriterService,
+        workspace_grants_query_1.WorkspaceGrantsQuery])
+], BulkSaveEntriesProposalApplier);

package/dist/lib/copilot/entry-proposal.provider.d.ts

@@ -0,0 +1,157 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { ToolRegistry } from '@orthacms/tools-server';
+import type { ToolDefinition, ToolProvider } from '@orthacms/tools-server';
+import type { ContentTypeRegistry } from '../registry/content-type-registry';
+import { EntryWriterService } from '../entries/infrastructure/persistence/entry-writer.service';
+import { WorkspaceGrantsQuery } from '../content-types/queries/workspace-grants.query';
+import { type ContentEntryExtension } from '../extension/entry-extension';
+/**
+ * The content plugin's **write** tools — `content_propose_create`,
+ * `content_propose_update`, and `content_propose_bulk_save` for the batch.
+ *
+ * All three are `effect: 'propose'`: they compute a change and hand it back, and the
+ * run engine persists it as a `copilot_proposals` row for a human to accept
+ * ([ADR-0005](../../../../../../docs/adr/0005-copilot-authority-model.md) §5).
+ * **Nothing here writes to the database.** That is the whole point of the split
+ * — the tool is a pure function of the model's arguments plus the current
+ * entry, so a prompt-injected instruction to "just save it" has nowhere to
+ * land, and the actual write happens later through the ordinary use-case with a
+ * person as actor.
+ *
+ * Two things they *do* touch the database for, both reads: resolving the
+ * workspace's content grants, and loading the entry an edit would change — the
+ * latter so the proposal carries a real before/after diff rather than a patch a
+ * reviewer has to mentally apply.
+ *
+ * **`content:publish` is not exposed at any role** (ADR-0005 §7). The copilot
+ * may prepare a publishable draft; a person presses publish. There is
+ * deliberately no `status` in any of their schemas — and no bulk publish or
+ * bulk delete either, however convenient: batching is a way of *asking*, not a
+ * route to authority a single-entry tool was not given.
+ */
+export declare class EntryProposalToolProvider implements ToolProvider, OnModuleInit {
+    private readonly registry;
+    private readonly writer;
+    private readonly grants;
+    private readonly toolRegistry?;
+    private readonly extension?;
+    constructor(registry: ContentTypeRegistry, writer: EntryWriterService, grants: WorkspaceGrantsQuery, toolRegistry?: ToolRegistry | undefined, extension?: ContentEntryExtension | undefined);
+    /**
+     * Register with the shared tool registry once the DI graph is built —
+     * the same catalogue the MCP endpoint serves, narrowed to the `copilot`
+     * surface by each tool's `surfaces`. `@Optional()` because a deployment
+     * may run neither consumer, in which case these simply go unregistered.
+     */
+    onModuleInit(): void;
+    /** The three write tools, in the order the model sees them. */
+    tools(): readonly ToolDefinition[];
+    /** Resolves a granted, registered type — the same uniform message as the reads. */
+    private resolveGranted;
+    /**
+     * The type's writable fields, keyed by name.
+     *
+     * **Back-references are excluded and owning many-relations are not.** The
+     * exclusion used to cover both, on the stated grounds that join-backed
+     * links "never travel in the `values` bag" — which is not true of the
+     * owning side: `RelationLinkService.writeLinks` performs a whole-set write
+     * for any owning many-relation submitted as an **array**, on create and on
+     * update alike, and the appliers already merge the patch straight into the
+     * values they hand the writer. So refusing `article.tags` refused something
+     * that works, which is how "Unknown or non-writable field(s): tags" came to
+     * be the answer to a perfectly ordinary request.
+     *
+     * An **inverse** relation genuinely cannot be written from this side —
+     * `writeLinks` skips it (`ownCol !== 'sourceId'`) — so a value for one
+     * really would be silently dropped, and a proposal that does nothing is
+     * worse than one refused up front.
+     */
+    private writableFields;
+    /**
+     * Whether a field is written as a **whole set** of target ids.
+     *
+     * These have no `before` in the diff: the current links are not part of the
+     * entry's `values` (`toRecord` drops join-backed fields), so the honest card
+     * shows what the set is being made into rather than a fabricated `null`
+     * before that reads as "it had no tags".
+     */
+    private isWholeSetRelation;
+    /**
+     * Narrows model-supplied values to the type's writable fields, rejecting a
+     * name that isn't one.
+     *
+     * Unlike the read tools' `fields`, an unknown name here is an **error**.
+     * There the cost of a mis-remembered name is a missing column in a result
+     * the model can see; here it is a change a human approves believing it
+     * writes a field that does not exist.
+     */
+    private narrowValues;
+    /**
+     * Asks the bound entries extension what a write of `values` onto this entry
+     * would rewrite **besides** that row.
+     *
+     * A localized type stores one row per language, and a field the type does
+     * not mark `localized` is *shared* — so saving it propagates to every
+     * sibling in the translation group. That is the contract working, not a
+     * bug: "shared" means shared, and refusing the write would leave no way to
+     * edit a shared field at all. What was missing is that nobody was told.
+     * Under [ADR-0009](../../../../../../docs/adr/0009-copilot-applies-directly.md)
+     * the change applies the moment it is drafted, so the proposal's own
+     * summary is the only place a person learns that one accepted edit moved
+     * their content in four languages — and it read as a single-entry edit.
+     *
+     * An error is deliberately **not** swallowed. This is a read against the
+     * same rows the write is about to take, so a failure here is a failure
+     * there; drafting the change anyway would drop the disclosure at exactly
+     * the moment something is wrong.
+     */
+    private fanoutOf;
+    /**
+     * Appends the blast radius to the model's own summary.
+     *
+     * The summary rather than a field of its own because of where a summary
+     * *goes*: it is the card's title, the audit row's `output_summary`, and —
+     * via the run engine's `Applied: …` receipt — the sentence the model reads
+     * back and reports to the user. One string reaches the person, the log and
+     * the model, and the model correcting itself ("that touched every
+     * language — for a translation I should use `i18n_propose_translation`") is
+     * worth as much here as the card is.
+     */
+    private discloseFanout;
+    /** `content_propose_create` — a new draft entry, for a human to accept. */
+    private proposeEntry;
+    /** `content_propose_update` — a change to an existing entry, with a real diff. */
+    private proposeEdit;
+    /**
+     * `content_propose_bulk_save` — many creates and edits as **one** change.
+     *
+     * It exists because the single-entry pair scales badly in the one direction
+     * users actually push it: "translate these eight posts", "retag everything
+     * from last month". Each entry was a tool call, so a run spent its step
+     * budget on round trips and the transcript grew a card per record — eight
+     * receipts for one instruction, none of which said what the other seven
+     * were.
+     *
+     * **Still `effect: 'propose'`, and still writes nothing here.** The batch is
+     * computed from the model's arguments plus the entries as they are now, and
+     * handed back for the engine to record and apply. One proposal row, one
+     * card, one diff listing every field of every entry — which is also what
+     * makes the batch reviewable after the fact instead of merely fast.
+     *
+     * The per-item addressing is the smaller half of the public API's: an `id`
+     * updates, no `id` creates. There is deliberately no group-addressed update
+     * (the ambiguity the REST `op` field resolves), because the admin tools hand
+     * the model entry ids and nothing here would produce a bare group id.
+     *
+     * **And deliberately no `localeGroupId`, which it used to take.** Joining a
+     * translation group is not a content save with two extra arguments: a
+     * create is a whole row, so every shared field the item did not name
+     * arrives as `null`, and the i18n extension then pushes those nulls onto
+     * every sibling in the group — blanking the record in every other language,
+     * silently where the siblings are drafts. Getting that right means
+     * inheriting the source row's shared values at apply time, which is
+     * knowledge the i18n plugin owns, so `i18n_propose_bulk_translation` is the
+     * route and this tool creates new records only.
+     */
+    private proposeBulk;
+}
+//# sourceMappingURL=entry-proposal.provider.d.ts.map

package/dist/lib/copilot/entry-proposal.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-proposal.provider.d.ts","sourceRoot":"","sources":["../../../src/lib/copilot/entry-proposal.provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,KAAK,YAAY,EACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,KAAK,EACR,mBAAmB,EAEtB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AAEvF,OAAO,EAEH,KAAK,qBAAqB,EAE7B,MAAM,8BAA8B,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,yBAA0B,YAAW,YAAY,EAAE,YAAY;IAGpE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACX,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAQ1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAXV,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EAChB,YAAY,CAAC,EAAE,YAAY,YAAA,EAQvC,SAAS,CAAC,EAAE,qBAAqB,YAAA;IAGtD;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAIpB,+DAA+D;IAC/D,KAAK,IAAI,SAAS,cAAc,EAAE;IAIlC,mFAAmF;YACrE,cAAc;IAW5B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAmBpB;;;;;;;;;;;;;;;;;;OAkBG;YACW,QAAQ;IActB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IA2BtB,2EAA2E;IAC3E,OAAO,CAAC,YAAY;IAkGpB,kFAAkF;IAClF,OAAO,CAAC,WAAW;IAsJnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,WAAW;CAwNtB"}