@orthacms/i18n-server 0.0.0-reserve.0

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

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkTranslationProposalApplier = exports.TranslationProposalApplier = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const drizzle_orm_1 = require("drizzle-orm");
+const database_1 = require("@orthacms/database");
+const content_server_1 = require("@orthacms/content-server");
+const translation_proposal_provider_1 = require("./translation-proposal.provider");
+/**
+ * Applies `i18n.entry.translate` by creating the sibling row through
+ * {@link EntryWriterService.create} — the same call `POST /api/content/:type`
+ * makes, with a `localeGroupId`.
+ *
+ * **There is no "create translation" write path to reuse, and that is the
+ * point**: joining an existing group is what `localeGroupId` on a create
+ * already means, and the bound entry extension stamps and validates it inside
+ * the write transaction. So this applier passes two extra arguments to the
+ * ordinary create rather than reaching for a second mechanism — which is also
+ * what makes a duplicate `(group, locale)` a clean 409 instead of a corrupt
+ * group.
+ *
+ * ## Why it reads the source entry first
+ *
+ * The propose tool accepts **only localized values** — a shared field is one
+ * value across the group, so asking a model to translate it is meaningless. But
+ * a create is a whole row: `coerceValues` stamps every declared field onto the
+ * bag, so a shared field nobody supplied arrives as `null` rather than as
+ * "absent". Two things then go wrong at once, and neither is obvious:
+ *
+ * 1. The new row fails its own required-field validation — `tag.slug` is
+ *    required and shared, and no translation of a tag ever carries it.
+ * 2. Worse, the bound extension treats that `null` as a shared value the save
+ *    *carries* and pushes it onto every sibling in the group. A published
+ *    sibling is re-validated and fails, which rolls the create back — but a
+ *    group whose siblings are all drafts has no such guard, and the shared
+ *    field is silently blanked in every locale.
+ *
+ * So the values the create is given are the **source entry's**, with the
+ * translated ones layered on top: the same thing the admin's own "create
+ * translation" does (it sends the source's values), and the reason that path
+ * has never hit this. The shared values then match the group exactly, the
+ * extension's `IS DISTINCT FROM` predicate finds nothing to sync, and no
+ * sibling is touched at all.
+ *
+ * Read at **apply** time rather than frozen into the proposal: a shared field
+ * can be edited between drafting and applying, and the group's current value is
+ * the one that must not be clobbered.
+ */
+let TranslationProposalApplier = class TranslationProposalApplier {
+    registry;
+    writer;
+    grants;
+    db;
+    kind = translation_proposal_provider_1.I18N_PROPOSAL_KINDS.createTranslation;
+    constructor(registry, writer, grants, db) {
+        this.registry = registry;
+        this.writer = writer;
+        this.grants = grants;
+        this.db = db;
+    }
+    async apply(input, actor) {
+        const typeName = input.target['typeName'];
+        const locale = input.target['locale'];
+        const localeGroupId = input.target['localeGroupId'];
+        const sourceId = input.target['sourceId'];
+        if (typeof typeName !== 'string' ||
+            typeof locale !== 'string' ||
+            typeof localeGroupId !== 'string' ||
+            typeof sourceId !== 'string') {
+            throw new Error('This proposal is missing its translation target.');
+        }
+        // Re-checked rather than trusted from the row: grants can be revoked
+        // between proposing and applying, and a stored type name is an
+        // argument like any other.
+        const type = this.registry.get(typeName);
+        const granted = await this.grants.grantedSlugs(actor.workspaceId);
+        if (!type || !granted.has(type.name)) {
+            throw new Error(`Unknown content type "${typeName}" in this workspace.`);
+        }
+        const translated = (input.patch['values'] ?? {});
+        const inherited = await sharedValues(this.db, type, sourceId, actor.workspaceId);
+        const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, { id: actor.userId, email: actor.actorEmail });
+        return {
+            entityId: entry.id,
+            detail: { typeName: type.name, locale, localeGroupId }
+        };
+    }
+};
+exports.TranslationProposalApplier = TranslationProposalApplier;
+exports.TranslationProposalApplier = TranslationProposalApplier = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_server_1.InjectContentRegistry)()),
+    tslib_1.__param(3, (0, database_1.InjectDatabase)()),
+    tslib_1.__metadata("design:paramtypes", [Function, content_server_1.EntryWriterService,
+        content_server_1.WorkspaceGrantsQuery, Object])
+], TranslationProposalApplier);
+/**
+ * The source entry's **shared** field values — everything the new sibling must
+ * carry over rather than invent.
+ *
+ * The exclusions mirror what the extension itself treats as shared, because a
+ * value copied here that the extension does *not* consider shared would be a
+ * per-locale field silently seeded from another language:
+ *
+ * - **Localized fields** are what the translation supplies.
+ * - **Many and inverse relations** are join-backed rather than column-backed,
+ *   so `toRecord` already drops them; the extension's own sync is what carries
+ *   them onto the new sibling.
+ * - **Any relation whose stored id differs per locale** — mirrored or unsynced
+ *   (`isPerLocaleField`). Copying the source's would point the German row at an
+ *   English one, which the writer rejects as a cross-locale link; for a
+ *   mirrored relation the extension resolves the right per-locale id itself,
+ *   after the insert.
+ *
+ * A free function rather than a method because **both** appliers need it, and
+ * needing it is not optional: it is the whole difference between joining a
+ * translation group and blanking it.
+ */
+async function sharedValues(db, type, sourceId, workspaceId) {
+    const table = type.table;
+    const [row] = await db
+        .select()
+        .from(type.table)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(table['id'], sourceId), (0, drizzle_orm_1.eq)(table['workspaceId'], workspaceId), ...(type.paranoid ? [(0, drizzle_orm_1.isNull)(table['deletedAt'])] : [])))
+        .limit(1);
+    if (!row) {
+        // The propose tool proved this row existed; by apply time it may not.
+        // Failing here beats creating a translation of nothing.
+        throw new Error('The entry this translates no longer exists.');
+    }
+    const source = (0, content_server_1.toRecord)(type, row).values;
+    const shared = {};
+    for (const [name, spec] of Object.entries(type.fields)) {
+        if ((0, content_server_1.isPerLocaleField)(type, spec))
+            continue;
+        if (!(name in source))
+            continue;
+        shared[name] = source[name];
+    }
+    return shared;
+}
+/**
+ * Applies `i18n.entry.bulk-translate` — several translations carried out as one
+ * change.
+ *
+ * **Item by item through the same `EntryWriterService.create` the single-entry
+ * applier calls**, each with its own source entry's shared values inherited: a
+ * batch is a way of asking for N translations, not a second way of writing one.
+ * Sequentially rather than concurrently, because every write takes the
+ * workspace's shared content lock and (on a localized type) an advisory lock
+ * over the translation group — a batch translating one record into five
+ * languages contends with itself by construction, so a fan-out would buy
+ * nothing but lock waits.
+ *
+ * **It stops at the first failure and throws**, exactly as the content plugin's
+ * bulk applier does. A proposal is one row with one status, so there is no
+ * per-item verdict to render; carrying on would grow the number of rows written
+ * under a receipt that then reports failure. The error names how many landed,
+ * which is what the model reads back to the user.
+ */
+let BulkTranslationProposalApplier = class BulkTranslationProposalApplier {
+    registry;
+    writer;
+    grants;
+    db;
+    kind = translation_proposal_provider_1.I18N_PROPOSAL_KINDS.bulkTranslation;
+    constructor(registry, writer, grants, db) {
+        this.registry = registry;
+        this.writer = writer;
+        this.grants = grants;
+        this.db = db;
+    }
+    async apply(input, actor) {
+        const typeName = input.target['typeName'];
+        if (typeof typeName !== 'string') {
+            throw new Error('This proposal is missing its content type.');
+        }
+        // Re-checked rather than trusted from the row: grants can be revoked
+        // between proposing and applying, and a stored type name is an
+        // argument like any other.
+        const type = this.registry.get(typeName);
+        const granted = await this.grants.grantedSlugs(actor.workspaceId);
+        if (!type || !granted.has(type.name)) {
+            throw new Error(`Unknown content type "${typeName}" in this workspace.`);
+        }
+        const items = input.patch['items'];
+        if (!Array.isArray(items) || items.length === 0) {
+            throw new Error('This change names no translations.');
+        }
+        const created = [];
+        const locales = [];
+        for (const [index, raw] of items.entries()) {
+            const item = (raw ?? {});
+            const sourceId = item.sourceId;
+            const localeGroupId = item.localeGroupId;
+            const locale = item.locale;
+            if (typeof sourceId !== 'string' ||
+                typeof localeGroupId !== 'string' ||
+                typeof locale !== 'string') {
+                throw new Error(`Translation ${index + 1} of ${items.length} is missing its target.`);
+            }
+            try {
+                // Read per item and at apply time, not once for the batch: two
+                // items may translate two different records, and a shared field
+                // edited between drafting and applying must not be clobbered by
+                // a stale copy of itself.
+                const inherited = await sharedValues(this.db, type, sourceId, actor.workspaceId);
+                const translated = (item.values ?? {});
+                const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, { id: actor.userId, email: actor.actorEmail });
+                created.push(entry.id);
+                locales.push(locale);
+            }
+            catch (error) {
+                throw new Error(`Translation ${index + 1} of ${items.length} (${locale}) failed: ` +
+                    `${error instanceof Error ? error.message : String(error)}. ` +
+                    (created.length === 0
+                        ? 'Nothing was saved.'
+                        : `The first ${created.length} 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,
+                locales,
+                count: created.length
+            }
+        };
+    }
+};
+exports.BulkTranslationProposalApplier = BulkTranslationProposalApplier;
+exports.BulkTranslationProposalApplier = BulkTranslationProposalApplier = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_server_1.InjectContentRegistry)()),
+    tslib_1.__param(3, (0, database_1.InjectDatabase)()),
+    tslib_1.__metadata("design:paramtypes", [Function, content_server_1.EntryWriterService,
+        content_server_1.WorkspaceGrantsQuery, Object])
+], BulkTranslationProposalApplier);

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

@@ -0,0 +1,114 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { WorkspaceGrantsQuery, type ContentTypeRegistry } from '@orthacms/content-server';
+import { ToolRegistry } from '@orthacms/tools-server';
+import type { ToolDefinition, ToolProvider } from '@orthacms/tools-server';
+import { LocaleRegistryService } from '../locales/services/locale-registry.service';
+import { LocaleGroupService } from '../content/services/locale-group.service';
+/** The proposal kinds this plugin declares and applies. */
+export declare const I18N_PROPOSAL_KINDS: {
+    /** Create a sibling row of an entry in another locale. */
+    readonly createTranslation: "i18n.entry.translate";
+    /**
+     * Create several sibling rows — more locales of one record, more records
+     * in one locale, or both — as **one** change.
+     *
+     * Its own kind rather than a repeated `createTranslation`, for the reason
+     * `content.entry.bulk-save` is: a proposal row is the receipt for one tool
+     * call, and "translate this into five languages" written as five rows is
+     * five cards in the transcript for a single instruction, none of which says
+     * what the other four were.
+     */
+    readonly bulkTranslation: "i18n.entry.bulk-translate";
+};
+/**
+ * The plugin's **write** tools: `i18n_propose_translation` for one locale of one
+ * entry, and `i18n_propose_bulk_translation` for a batch of them.
+ *
+ * Like every propose tool their handlers **write nothing** — they compute the
+ * change and hand it back, and the run engine records and applies it. What they
+ * do is the part a model cannot be trusted to get right on its own: resolve the
+ * locale slug against the configured set, confirm the target locale does not
+ * already exist in the group (a duplicate is a 409 at apply time, after the
+ * card has said the change is happening), and name the source entry so the
+ * applier can inherit its shared values.
+ *
+ * Only **localized** fields are translated. A field the type declares as shared
+ * is one value across the whole group by definition — writing a per-locale
+ * version of it would either be ignored or silently overwrite every sibling,
+ * and neither is something to show a reader as a translation.
+ */
+export declare class TranslationProposalToolProvider implements ToolProvider, OnModuleInit {
+    private readonly registry;
+    private readonly locales;
+    private readonly groups;
+    private readonly grants;
+    private readonly toolRegistry?;
+    constructor(registry: ContentTypeRegistry, locales: LocaleRegistryService, groups: LocaleGroupService, grants: WorkspaceGrantsQuery, toolRegistry?: ToolRegistry | 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 two i18n write tools — one translation, and the batch. */
+    tools(): readonly ToolDefinition[];
+    /**
+     * A granted, registered, **localized** type — the gate both write tools
+     * open with.
+     *
+     * The two failures are worth separating: "unknown type" is the uniform
+     * answer every content tool gives a name it cannot reach (it must not
+     * distinguish "no such type" from "not granted here"), while "not
+     * localized" describes a type the caller has already proved it can reach
+     * and is safe — and useful — to say out loud.
+     */
+    private resolveLocalizedType;
+    /**
+     * The type's **localized** fields, keyed by name — the only ones a
+     * translation may carry.
+     *
+     * A field the type declares as shared is one value across the whole group
+     * by definition: writing a per-locale version of it would be fanned back
+     * out over every sibling by this plugin's own sync, so a "translated"
+     * shared field silently rewrites every other language.
+     */
+    private localizedFields;
+    /**
+     * Rejects anything in `values` that is not a localized field, and an empty
+     * bag — the check that makes a translation tool a translation tool.
+     *
+     * `prefix` names which item is at fault in a batch, and is empty for the
+     * single-entry tool so its message is unchanged.
+     */
+    private assertTranslatable;
+    /** The field's admin label, when it has one — for the card's diff rows. */
+    private labelOf;
+    /** `i18n_propose_translation` — one entry into one locale. */
+    private proposeTranslation;
+    /**
+     * `i18n_propose_bulk_translation` — several translations as **one** change.
+     *
+     * The single-entry tool scales badly in both directions users actually push
+     * it: "translate this into German, French and Spanish" is three calls, and
+     * "translate these eight posts into German" is eight. Each one spent a step
+     * of a bounded run and left its own card, so one instruction read back as a
+     * pile of receipts, none of which said what the others were.
+     *
+     * **Why this rather than `content_propose_bulk_save` with a
+     * `localeGroupId`.** That is what a model reached for before, and it is the
+     * shape that quietly breaks a group: a create is a whole row, so every
+     * shared field the batch did not name arrives as `null`, and this plugin's
+     * sync then pushes those nulls onto every sibling — see
+     * {@link TranslationProposalApplier}. Joining a translation group needs the
+     * source's shared values inherited at apply time, which is knowledge that
+     * lives here, so the content tools no longer offer `localeGroupId` at all
+     * and this is the one route in.
+     *
+     * An item is one **(source entry, target locale)** pair, so both shapes are
+     * the same list: five items naming one `id` and five locales, eight naming
+     * eight ids and one locale, or any mixture.
+     */
+    private proposeBulkTranslation;
+}
+//# sourceMappingURL=translation-proposal.provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"translation-proposal.provider.d.ts","sourceRoot":"","sources":["../../../src/lib/copilot/translation-proposal.provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAGH,oBAAoB,EACpB,KAAK,mBAAmB,EAE3B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6CAA6C,CAAC;AACpF,OAAO,EACH,kBAAkB,EAErB,MAAM,0CAA0C,CAAC;AAElD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB;IAC5B,0DAA0D;;IAE1D;;;;;;;;;OASG;;CAEG,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,+BACT,YAAW,YAAY,EAAE,YAAY;IAIjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACX,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAJzB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EAChB,YAAY,CAAC,EAAE,YAAY,YAAA;IAG5D;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAIpB,iEAAiE;IACjE,KAAK,IAAI,SAAS,cAAc,EAAE;IAIlC;;;;;;;;;OASG;YACW,oBAAoB;IAgBlC;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IASvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAoB1B,2EAA2E;IAC3E,OAAO,CAAC,OAAO;IAKf,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB;IA8H1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,sBAAsB;CA2MjC"}