@purposeinplay/payload-ai-translate 0.1.0

package/dist/settings-global.js

@@ -0,0 +1,216 @@
+import { invalidateSettingsCache } from './lib/effective-locales.js';
+export const DEFAULT_SETTINGS_GLOBAL_SLUG = 'translation-settings';
+export function createSettingsGlobal(providerKeys, targetLocales, options, trackedSurfaces = []) {
+    const slug = options?.globalSlug ?? DEFAULT_SETTINGS_GLOBAL_SLUG;
+    const defaultAdminAccess = ({ req })=>req?.user?.roles?.includes('admin') ?? false;
+    const providerOptions = providerKeys.map((key)=>({
+            label: key,
+            value: key
+        }));
+    const localeOptions = targetLocales.map((locale)=>({
+            label: locale,
+            value: locale
+        }));
+    const surfaceOptions = trackedSurfaces.map((slugName)=>({
+            label: slugName,
+            value: slugName
+        }));
+    const fields = [];
+    // Provider selector — only meaningful when there's something to switch
+    // between. Single-provider consumers see only the locale toggle.
+    if (providerKeys.length > 0) {
+        fields.push({
+            name: 'activeProvider',
+            type: 'select',
+            required: false,
+            options: providerOptions,
+            admin: {
+                description: 'The provider used for new translations. When unset, the plugin falls back to the default `provider` configured in code.'
+            }
+        });
+    }
+    // Per-locale auto-translate toggle. Empty = "all enabled" so that
+    // existing consumers see no behavior change after upgrading.
+    fields.push({
+        name: 'enabledTargetLocales',
+        type: 'select',
+        hasMany: true,
+        required: false,
+        options: localeOptions,
+        admin: {
+            description: '⚠️ EMPTY = ALL LOCALES ENABLED (back-compat default). Select locales here to NARROW auto-translate to that subset; unselected locales are skipped by automation. Clearing the list does NOT disable auto-translate — to fully stop automation, uncheck "Enabled" or "Auto on publish" on every per-collection row below. Manual Translate from the dialog is never gated by this field.'
+        }
+    });
+    // Three independent plugin-wide kill switches. Each one supersedes
+    // every per-collection setting below — when off, no surface receives
+    // work via that subsystem regardless of the per-surface `enabled` /
+    // `autoOnPublish` flags. Defaults are `true` so upgrades don't break
+    // existing consumers; admins flip them off when they need an
+    // emergency stop without redeploying.
+    //
+    // Storage shape: three top-level checkboxes (not nested in a group)
+    // so Payload's drizzle generator emits flat boolean columns —
+    // `global_auto_translate_enabled` etc. on the `translation_settings`
+    // table — instead of a join table or a JSON blob. Flat columns make
+    // the migration a no-op `ADD COLUMN IF NOT EXISTS ... DEFAULT true`
+    // on both consumer repos.
+    //
+    // Read path: every gate uses `getGlobalKillSwitches` in
+    // `lib/effective-locales.ts`, which shares the 30s-TTL settings
+    // cache with the per-collection helpers. The settings global's own
+    // `afterChange` already invalidates the cache, so admin edits
+    // propagate on the next read.
+    fields.push({
+        name: 'globalAutoTranslateEnabled',
+        type: 'checkbox',
+        defaultValue: true,
+        admin: {
+            description: '🛑 GLOBAL KILL SWITCH — auto-translate. When unchecked, the after-change hook does nothing on every save. Per-collection `Enabled` / `Auto on publish` still apply WITHIN this switch — flipping it back on resumes whatever per-surface config was already in place. Manual Translate and Bulk Translate are unaffected by this flag.'
+        }
+    }, {
+        name: 'globalManualTranslateEnabled',
+        type: 'checkbox',
+        defaultValue: true,
+        admin: {
+            description: '🛑 GLOBAL KILL SWITCH — manual Translate dialog + per-field button. When unchecked, the dialog and the per-field button hide in the admin UI, and the underlying endpoint returns 403. Per-collection `Enabled` still applies WITHIN this switch. Auto-translate and Bulk Translate are unaffected by this flag.'
+        }
+    }, {
+        name: 'globalBulkTranslateEnabled',
+        type: 'checkbox',
+        defaultValue: true,
+        admin: {
+            description: '🛑 GLOBAL KILL SWITCH — Bulk Translate (new runs). When unchecked, enqueueing a new bulk run is rejected and the BulkTranslate trigger in the Hub renders disabled. In-flight bulk runs that were already enqueued continue to completion — flipping this switch does NOT cancel running work. Manual Translate and auto-translate are unaffected by this flag.'
+        }
+    });
+    // Per-collection / per-global configuration. Each tracked surface
+    // gets a row; admins can disable a surface entirely, turn off
+    // auto-on-publish, or narrow the target locales for just that
+    // surface. Empty rows / missing entries fall back to the site-wide
+    // defaults — so consumers upgrading without admin action see no
+    // behavior change.
+    if (trackedSurfaces.length > 0) {
+        fields.push({
+            name: 'perCollection',
+            type: 'array',
+            required: false,
+            labels: {
+                singular: 'Collection / Global setting',
+                plural: 'Per-collection settings'
+            },
+            // Postgres identifier limit is 63 chars; the default-generated
+            // table / enum names from `translation_settings_per_collection_*`
+            // overflow. Pin compact db identifiers so generated migrations
+            // are portable across adapters.
+            dbName: 'tr_st_pc',
+            admin: {
+                description: 'Override site-wide settings for a specific collection or global. Rows that are missing or have all defaults inherit the site-wide config above.',
+                initCollapsed: true
+            },
+            fields: [
+                {
+                    name: 'slug',
+                    type: 'select',
+                    required: true,
+                    options: surfaceOptions,
+                    enumName: 'enum_tr_st_pc_slug',
+                    admin: {
+                        description: 'The collection or global this row configures.'
+                    }
+                },
+                {
+                    name: 'enabled',
+                    type: 'checkbox',
+                    defaultValue: true,
+                    admin: {
+                        description: 'KILL SWITCH. Unchecked = translation is fully disabled for this surface — auto-on-publish AND manual Translate dialog AND per-field button. Use the "Auto on publish" toggle below if you want to disable ONLY automation while keeping manual translate available.'
+                    }
+                },
+                {
+                    name: 'autoOnPublish',
+                    type: 'checkbox',
+                    defaultValue: true,
+                    admin: {
+                        description: 'AUTOMATION ONLY. When checked, publishing a doc in this surface fires auto-translate. Uncheck to keep this collection manual-only — editors can still trigger Translate… on demand. Has no effect when "Enabled" above is unchecked (the kill switch takes precedence).'
+                    }
+                },
+                {
+                    name: 'targetLocalesOverride',
+                    type: 'select',
+                    hasMany: true,
+                    required: false,
+                    options: localeOptions,
+                    enumName: 'enum_tr_st_pc_tlo',
+                    admin: {
+                        description: '⚠️ EMPTY = INHERIT site-wide locales (back-compat default). Select locales here to NARROW auto-translate for THIS surface specifically. A locale must be enabled at BOTH the site-wide level AND here to fan out. Clearing the list does NOT opt this surface out — uncheck "Enabled" above to do that.'
+                    }
+                },
+                {
+                    // Opt this surface's `slug` field into translation. Defaults
+                    // to false because the plugin's `excludeFields` config
+                    // typically lists `slug` to prevent accidental URL churn
+                    // across locales. Editors who want per-locale SEO-friendly
+                    // URLs check this on a per-collection basis.
+                    //
+                    // Pre-requisite: the slug field on the collection schema
+                    // must be `localized: true` — otherwise the resolver can't
+                    // see it and this toggle has no effect. The widget below
+                    // surfaces the path only when localized; the description
+                    // makes this explicit.
+                    name: 'translateSlug',
+                    type: 'checkbox',
+                    defaultValue: false,
+                    admin: {
+                        description: 'Include the slug field in translation runs for this surface. The slug field must also be `localized: true` on the collection schema for this to take effect — otherwise the toggle is a no-op. Applies to BOTH automation and the manual Translate… dialog.'
+                    }
+                },
+                {
+                    // Storage shape: `text hasMany` => Postgres join table.
+                    // Parent array's `dbName: 'tr_st_pc'` keeps the generated
+                    // join-table name under the 63-char identifier limit.
+                    // Stored as opaque strings — the plugin doesn't enforce
+                    // that listed paths currently exist, so renaming a field
+                    // doesn't auto-clean stale entries. Stale entries are
+                    // harmless downstream: the filter is a Set membership
+                    // check; paths absent from the resolver don't match
+                    // anything and pass through unchanged.
+                    name: 'excludedFieldPaths',
+                    type: 'text',
+                    hasMany: true,
+                    required: false,
+                    admin: {
+                        description: 'Fields excluded from translation for this surface. Applies to BOTH automation and the Translate… dialog — different from the AUTOMATION-ONLY flags above. Renders a checkbox list driven by the current "Slug" value: uncheck a field to opt it out of every translation path (auto + manual). Leave all checked to translate every detected field (back-compat default).',
+                        components: {
+                            Field: '@purposeinplay/payload-ai-translate/client#ExcludedFieldsField'
+                        }
+                    }
+                }
+            ]
+        });
+    }
+    return {
+        slug,
+        label: 'Translation Settings',
+        admin: {
+            group: 'System',
+            description: 'Configure runtime translation behaviour: which provider runs new translations and which locales auto-translate on publish.',
+            // Hide from non-admins — same posture as `translation-usage`.
+            hidden: ({ user })=>!user?.roles?.includes('admin')
+        },
+        access: {
+            read: options?.access?.read ?? defaultAdminAccess,
+            update: options?.access?.update ?? defaultAdminAccess
+        },
+        hooks: {
+            // Invalidate the `effective-locales` cache whenever the settings
+            // global is saved so admin edits propagate to the next publish
+            // cycle without waiting for the 30s TTL.
+            afterChange: [
+                ()=>{
+                    invalidateSettingsCache(slug);
+                }
+            ]
+        },
+        graphQL: false,
+        fields
+    };
+}

package/dist/tasks/bulk-translate-coordinator.d.ts

@@ -0,0 +1,115 @@
+import type { Payload, TaskConfig } from 'payload';
+export declare const BULK_TRANSLATE_COORDINATOR_SLUG = "bulk-translate-coordinator";
+export declare const BULK_TRANSLATE_DOC_TASK_SLUG = "bulk-translate-doc";
+/**
+ * Coordinator persists this shape into `bulk-translate-batches
+ * .lastEnumerationCursor` so a crashed-mid-enumeration run can resume
+ * from where it left off rather than re-scan every doc on restart.
+ *
+ * Phase ordering: collections → globals → (canary sampling, when
+ * mode='canary') → done. Each phase is independently resumable.
+ */
+export type EnumerationCursor = {
+    phase: 'collections' | 'globals' | 'canary' | 'done';
+    collectionIndex: number;
+    page: number;
+    globalIndex: number;
+};
+export type BulkBatchScope = {
+    /**
+     * Collection slugs to enumerate. Required when targeting collection
+     * docs. Empty + `globals: []` is a no-op (the coordinator immediately
+     * transitions the batch to `completed` with `totalUnits: 0`).
+     */
+    collections?: string[];
+    /** Global slugs to enumerate. */
+    globals?: string[];
+    /**
+     * Target locales the batch should translate to. Coordinator creates
+     * one unit per (doc, locale). Must be non-empty.
+     */
+    locales: string[];
+    /**
+     * Collections to skip even when listed in `collections`. Honors
+     * `BulkTranslateConfig.excludeCollections` (e.g. `users` per
+     * Decision #32 / F-SEC-USERS-BIO).
+     */
+    excludeCollections?: string[];
+    /** Optional whitelist of specific doc IDs (scopes enumeration). */
+    documentIds?: string[];
+    /** Source locale snapshotted at enqueue. Used to read source docs. */
+    sourceLocale: string;
+    /** Batch mode. `canary` mode caps the unit count via `canaryLimit`. */
+    mode: 'changed' | 'force' | 'canary';
+    /** Canary fan-out cap (only meaningful when `mode === 'canary'`). */
+    canaryLimit?: number;
+};
+export interface BulkCoordinatorOptions {
+    /** Slug override for the batches collection. */
+    batchesCollectionSlug?: string;
+    /** Slug override for the units collection. */
+    unitsCollectionSlug?: string;
+    /**
+     * Per-tick wall-clock budget. When the coordinator hits this limit
+     * mid-enumeration it persists the cursor and re-enqueues itself
+     * instead of running until Payload's job-runner times out.
+     *
+     * Default 25_000ms — well under Vercel Pro's 300s function ceiling
+     * and Payload's default `runJobs` async-function timeout.
+     */
+    tickBudgetMs?: number;
+    /**
+     * Per-collection pagination size. Default 100 — Payload's local API
+     * defaults to 10, which would over-trample the jobs queue with
+     * coordinator re-enqueues.
+     */
+    pageSize?: number;
+    /** Slug for the worker task. Mirrors `BULK_TRANSLATE_DOC_TASK_SLUG`. */
+    workerTaskSlug?: string;
+}
+type CoordinatorTaskInput = {
+    batchId: string;
+};
+/**
+ * Coordinator task that enumerates every (doc, locale) under
+ * `batch.scope`, inserts a `bulk-translate-units` row per unit and
+ * queues a `bulk-translate-doc` task per unit. Both ops are wrapped
+ * in a single transaction per (doc, locale) tuple to close F-DA-TOCTOU
+ * scenario A — the worker can never dequeue before the unit row has
+ * committed.
+ *
+ * Long enumerations trampoline: the task self-re-enqueues with the
+ * same `batchId` and a persisted `lastEnumerationCursor` once it hits
+ * `tickBudgetMs`. Resume from the cursor is exact (collection +
+ * pagination page), not approximate.
+ *
+ * For `mode: 'canary'`, the coordinator performs full enumeration
+ * (so the candidate pool is the same as `mode: 'changed'` would
+ * scope) and selects N units via random-stratified sampling keyed
+ * on `batchId` for reproducibility.
+ */
+export declare function buildBulkTranslateCoordinator(options?: BulkCoordinatorOptions): TaskConfig<{
+    input: CoordinatorTaskInput;
+    output: {
+        ok: true;
+        cursor: EnumerationCursor;
+    };
+}>;
+export type CoordinatorTickParams = {
+    payload: Payload;
+    batchId: string;
+    batchesSlug: string;
+    unitsSlug: string;
+    tickBudgetMs: number;
+    pageSize: number;
+    workerSlug: string;
+    /** Test override — injects current time for deterministic budget checks. */
+    now?: () => number;
+};
+export type CoordinatorTickResult = {
+    cursor: EnumerationCursor;
+    unitsCreated: number;
+    finished: boolean;
+};
+export declare function runCoordinatorTick(params: CoordinatorTickParams): Promise<CoordinatorTickResult>;
+export {};