Merge pull request #74 from focusreactive/refactor/translate-collection-plugin

refactor(translator): reshape TranslateCollectionPlugin orchestration (#73)

Author: SearheiParkhamchuk

packages/payload-plugin-translator/CLAUDE.md

@@ -32,3 +32,34 @@ Scope:
 Non-trivial work is designed in a committed doc under [docs/plans/](docs/plans)
 before implementation. Deprecations are tracked in
 [docs/DEPRECATIONS.md](docs/DEPRECATIONS.md) (keyed by date + PR, removal = next major).
+
+## File naming — role tags
+
+Files carry a **role tag** as a dotted suffix: `<Domain>.<role>.ts` with a PascalCase
+domain base (e.g. `Provenance.service.ts`). The tag names *what kind of thing* the file is,
+so a directory listing reads as an architecture map. Extend this vocabulary rather than
+inventing a parallel scheme.
+
+| Role | Tag | Example |
+| ---- | --- | ------- |
+| Framework-agnostic port / abstract contract (in `core/`) | `.interface.ts` | `ProvenanceStore.interface.ts` |
+| Domain / policy service | `.service.ts` | `Provenance.service.ts` |
+| Payload adapter implementing a port | `.store.ts` (or a role word for the port kind) | `Provenance.store.ts` |
+| Payload collection factory | `.collection.ts` | `Provenance.collection.ts` |
+| Payload hook | `.hook.ts` | `ProvenanceCleanup.hook.ts` |
+| Config-time wiring (`configure(ctx) → ConfigModifier`) | `.wiring.ts` | `Provenance.wiring.ts` |
+| Narrow structural shapes (Payload-type slices — see below) | `.shapes.ts` | `Provenance.shapes.ts` |
+| Translation-pipeline stage | `.stage.ts` | `DataReconciler.stage.ts` |
+| Pluggable strategy / provider / factory | `.strategy.ts` · `.provider.ts` · `.factory.ts` | `Overwrite.strategy.ts` |
+| Client RSC / admin boundary | `.export.tsx` · `.server.tsx` · `.client.ts` | `TranslateDocument.server.tsx` |
+
+Not everything is tagged: `index.ts` barrels, and small **pure helpers** named by topic
+(`slugGuard.ts`, `staleness.ts`) stay untagged. The tag is for role-bearing units, not every file.
+
+**Structural Payload-type slices (`.shapes.ts`).** Functions/classes must not depend on
+Payload's god types (`Config`, `CollectionConfig`, …). Define a narrow structural interface with
+only the fields you touch — the real Payload type is assignable to it (structural typing), so it
+"plugs in" with no adapter and tests pass a tiny literal. Full Payload types stay near the surface:
+`plugin.ts`, `PluginConfigBuilder.applyTo`, the `ConfigModifier` contract (`types/ConfigModifier.ts`),
+and HTTP route boundaries (`PayloadRequest`) — not in leaf helpers. See
+`server/modules/provenance/Provenance.shapes.ts`.

packages/payload-plugin-translator/docs/plans/2026-07-14-translate-collection-plugin-reshape.md

@@ -6,8 +6,8 @@ import type { LevelContext } from "../../server/modules/translation-levels";
  * Contribute the runner-agnostic document-translation API — the shared route
  * bundle, bound to the level context's runner. Both `documentLevel` and
  * `collectionLevel` call this; the plugin deduplicates the endpoints by method +
- * path, so the bundle registers exactly once. The schema map and provenance
- * store factory ride along for the staleness endpoints.
+ * path, so the bundle registers exactly once. The provenance service factory
+ * rides along for the staleness endpoints (its schema lives inside the service).
  */
 export function useDocTranslationApi(ctx: LevelContext): void {
   ctx.addEndpoints(
@@ -18,8 +18,7 @@ export function useDocTranslationApi(ctx: LevelContext): void {
       },
       access: ctx.access,
       basePath: ctx.basePath,
-      schemaMap: ctx.schemaMap,
-      provenanceStoreFactory: ctx.provenanceStoreFactory,
+      provenanceServiceFactory: ctx.provenanceServiceFactory,
     })
   );
 }

packages/payload-plugin-translator/src/composition/levels/useDocTranslationApi.ts

@@ -1,44 +1,17 @@
-import type { CollectionConfig, Config, Payload } from "payload";
+import type { CollectionConfig, Config } from "payload";
 
 import { CacheProviderExport } from "./client/app/cache/CacheProvider.export";
-import {
-  DEFAULT_PROVENANCE_SLUG,
-  PayloadProvenanceStore,
-  assertProvenanceSlugFree,
-  injectProvenanceCleanup,
-  isProvenanceCollection,
-  makeProvenanceCollection,
-} from "./server/modules/provenance";
+import { configureProvenance } from "./server/modules/provenance";
 import type { AccessGuard } from "./types/AccessGuard";
 import type { TranslationProvider } from "./core/translation-providers";
-import type {
-  TaskRunnerProvider,
-  TaskRunnerContext,
-  TaskRunnerFactory,
-} from "./server/modules/task-runner";
-import { TranslateDocumentHandler } from "./server/features/translate-document";
-import {
-  LifecycleNotifier,
-  taskFromHandlerInput,
-  withQueuedNotification,
-} from "./server/modules/lifecycle";
+import type { TaskRunnerProvider } from "./server/modules/task-runner";
+import { wireTranslateRunner } from "./server/features/translate-document";
 import type { TranslationLifecycleCallbacks } from "./server/modules/lifecycle";
 import { documentLevel, collectionLevel } from "./composition/levels";
 import type { TranslationLevel } from "./server/modules/translation-levels";
 import { PluginConfigBuilder } from "./server/modules/translation-levels/PluginConfigBuilder";
 import { normalizePath } from "./server/shared";
 
-/**
- * Resolve the opt-in `provenance` config to a sidecar slug, or `null` when disabled.
- * `false`/omitted → off; `true` or `{}` → on with the default slug; `{ slug }` → on with that slug.
- */
-function resolveProvenanceSlug(provenance: TranslatorPluginConfig["provenance"]): string | null {
-  if (!provenance) return null;
-  if (provenance === true) return DEFAULT_PROVENANCE_SLUG;
-  // `||` (not `??`) so an empty/blank slug falls back to the default instead of silently disabling.
-  return provenance.slug || DEFAULT_PROVENANCE_SLUG;
-}
-
 export type TranslatorPluginConfig = {
   /**
    * Original collection configs (same objects passed to buildConfig).
@@ -132,75 +105,30 @@ export class TranslateCollectionPlugin {
         basePath: rawBasePath = "/translate",
       } = this.pluginConfig;
 
-      const lifecycleCallbacks: TranslationLifecycleCallbacks = lifecycle ?? {};
-
-      // Build schema map from deep-cloned collections
-      // Deep clone is required because Payload mutates the original collection objects,
-      // removing `localized: true` from nested fields during sanitization.
-      // We use JSON round-trip instead of structuredClone because Lexical editor
-      // configs contain async functions that structuredClone cannot handle.
-      // TODO: Consider introducing a FieldLike interface with only the properties
-      // used by the pipeline (name, type, localized, fields, blocks, tabs, custom)
-      // to make the contract explicit and avoid reliance on JSON round-trip.
+      // Build schema map from deep-cloned collections.
+      // Deep clone is required because Payload mutates the original collection objects, removing
+      // `localized: true` from nested fields during sanitization. JSON round-trip (not
+      // structuredClone) because Lexical editor configs contain async functions structuredClone
+      // cannot handle.
+      // TODO: Consider introducing a FieldLike interface with only the properties used by the
+      // pipeline (name, type, localized, fields, blocks, tabs, custom) to make the contract explicit
+      // and avoid reliance on JSON round-trip.
       const schemaMap = new Map(
         collections.map((col) => [col.slug, JSON.parse(JSON.stringify(col.fields))])
       );
       const collectionSlugs = new Set(schemaMap.keys());
       const basePath = normalizePath(rawBasePath);
-      const provenanceSlug = resolveProvenanceSlug(provenance);
-      if (provenanceSlug) {
-        const existing = (config.collections ?? []).filter(
-          (collection) => !isProvenanceCollection(collection)
-        );
-        assertProvenanceSlugFree(provenanceSlug, existing);
-      }
-      const provenanceStoreFactory = provenanceSlug
-        ? (p: Payload) => new PayloadProvenanceStore(p, provenanceSlug)
-        : undefined;
 
-      const translateHandler = new TranslateDocumentHandler(
+      // Each concern owns its own config-time wiring and exposes it uniformly; init() just composes.
+      const provenanceModule = configureProvenance(provenance, schemaMap);
+      const { taskRunnerFactory, configModifier: runnerConfigModifier } = wireTranslateRunner({
         translationProvider,
         schemaMap,
-        provenanceStoreFactory
-      );
-
-      const runnerContext: TaskRunnerContext = {
-        handler: async (payload, input) => {
-          const notifier = new LifecycleNotifier(lifecycleCallbacks, payload.logger);
-          const task = taskFromHandlerInput(input);
-          try {
-            await translateHandler.handle(payload, {
-              collection: input.collection,
-              collectionId: input.collectionId,
-              sourceLng: input.sourceLng,
-              targetLng: input.targetLng,
-              strategy: input.strategy,
-              publishOnTranslation: input.publishOnTranslation,
-            });
-          } catch (error) {
-            await notifier.failed(task, error);
-            throw error; // rethrow so the runner marks the job failed
-          }
-          await notifier.completed(task);
-        },
+        provenanceServiceFactory: provenanceModule.serviceFactory,
+        runner,
+        lifecycle: lifecycle ?? {},
         collections: Array.from(collectionSlugs),
-      };
-      const runnerConfigModifier = runner.configure(runnerContext);
-
-      // Bind the context once so routes receive a self-sufficient factory: the
-      // runner needs no mutable per-instance handler state and create() has no
-      // "configure() must run first" ordering coupling (translator plan, 0c).
-      // When an `onQueued` callback is set, decorate the runner so `enqueue` fires it.
-      const taskRunnerFactory: TaskRunnerFactory = {
-        create: (payload) => {
-          const taskRunner = runner.create(payload, runnerContext.handler);
-          if (!lifecycleCallbacks.onQueued) return taskRunner;
-          return withQueuedNotification(
-            taskRunner,
-            new LifecycleNotifier(lifecycleCallbacks, payload.logger)
-          );
-        },
-      };
+      });
 
       const activeLevels = levels ?? [documentLevel(), collectionLevel()];
       const builder = new PluginConfigBuilder({
@@ -210,26 +138,12 @@ export class TranslateCollectionPlugin {
         taskRunnerFactory,
         schemaMap,
         translationProvider,
-        provenanceStoreFactory,
+        provenanceServiceFactory: provenanceModule.serviceFactory,
       });
       for (const level of activeLevels) level.extend(builder);
 
       builder.addConfigModifier(runnerConfigModifier);
-      if (provenanceSlug && provenanceStoreFactory) {
-        builder.addConfigModifier((cfg) => {
-          const alreadyAdded = cfg.collections?.some(
-            (collection) => collection.slug === provenanceSlug && isProvenanceCollection(collection)
-          );
-          if (!alreadyAdded) {
-            cfg.collections = [
-              ...(cfg.collections ?? []),
-              makeProvenanceCollection(provenanceSlug),
-            ];
-          }
-          injectProvenanceCleanup(cfg, collectionSlugs, provenanceStoreFactory, provenanceSlug);
-          return cfg;
-        });
-      }
+      builder.addConfigModifier(provenanceModule.configure(collectionSlugs));
       builder.addAdminProvider(new CacheProviderExport(basePath));
 
       // The single place the Payload config is mutated.

packages/payload-plugin-translator/src/plugin.ts

@@ -11,7 +11,6 @@ const deps = (basePath?: string): TranslationRoutesDeps => ({
   taskRunnerFactory: { create: vi.fn() },
   collectionConfig: { availableCollections: new Set() },
   basePath,
-  schemaMap: new Map(),
 });
 
 describe("createTranslationRoutes (bundle contract)", () => {

packages/payload-plugin-translator/src/server/features/_lib/sourceDocument.ts

@@ -1,9 +1,6 @@
 import type { CollectionSlug, Endpoint } from "payload";
 
-import type { AccessGuard } from "../shared";
-import type { TaskRunnerFactory } from "../modules/task-runner";
-import type { CollectionSchemaMap } from "../../types/CollectionSchemaMap";
-import type { ProvenanceStoreFactory } from "../modules/provenance";
+import type { TranslationContext } from "../modules/translation-levels";
 
 import { createEnqueueRoute } from "./enqueue-translation";
 import { createRunRoute } from "./run-translation";
@@ -13,16 +10,13 @@ import { createGetDocumentStatusRoute } from "./get-document-status";
 import { createGetCollectionStatusRoute } from "./get-collection-status";
 import { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./staleness";
 
-export type TranslationRoutesDeps = {
-  taskRunnerFactory: TaskRunnerFactory;
+export type TranslationRoutesDeps = Pick<
+  TranslationContext,
+  "taskRunnerFactory" | "access" | "provenanceServiceFactory"
+> & {
   /** Collections the plugin manages — gates which slugs the routes accept. */
   collectionConfig: { availableCollections: Set<CollectionSlug> };
-  access?: AccessGuard;
   basePath?: string;
-  /** Original per-collection field schema — needed to recompute source fingerprints for staleness. */
-  schemaMap: CollectionSchemaMap;
-  /** Builds a provenance store; absent when provenance is disabled (staleness then reports empty). */
-  provenanceStoreFactory?: ProvenanceStoreFactory;
 };
 
 /**
@@ -35,20 +29,18 @@ export type TranslationRoutesDeps = {
  * document and collection levels each contribute this bundle via the level
  * context; the plugin deduplicates by method + path, so it registers exactly
  * once. The staleness endpoints always register; when provenance is disabled
- * (`provenanceStoreFactory` absent) they simply report no staleness.
+ * (`provenanceServiceFactory` absent) they simply report no staleness.
  */
 export function createTranslationRoutes({
   taskRunnerFactory,
   collectionConfig,
   access,
   basePath,
-  schemaMap,
-  provenanceStoreFactory,
+  provenanceServiceFactory,
 }: TranslationRoutesDeps): Endpoint[] {
   const stalenessConfig = {
     availableCollections: collectionConfig.availableCollections,
-    schemaMap,
-    provenanceStoreFactory,
+    provenanceServiceFactory,
   };
   return [
     createEnqueueRoute(taskRunnerFactory, collectionConfig, access, basePath),

packages/payload-plugin-translator/src/server/features/createTranslationRoutes.test.ts

@@ -5,7 +5,6 @@ import { isCollectionAvailable } from "../_lib/collection-utils";
 
 import { DismissStalenessInputSchema } from "./model";
 import type { StalenessConfig } from "./model";
-import { dismissLocaleStaleness } from "./service";
 
 /** Dismisses (acknowledges) staleness of one target locale for a document. */
 export class DismissStalenessHandler {
@@ -23,13 +22,12 @@ export class DismissStalenessHandler {
       return ServerResponse.badRequest("Collection not available for translation");
     }
 
-    await dismissLocaleStaleness(
-      req.payload,
-      this.config,
-      collectionSlug,
-      collection_id,
-      target_lng
-    );
+    const service = this.config.provenanceServiceFactory?.(req.payload);
+    await service?.dismiss({
+      collectionSlug: collectionSlug,
+      documentId: collection_id,
+      targetLocale: target_lng,
+    });
     return ServerResponse.success({ success: true });
   }
 }

packages/payload-plugin-translator/src/server/features/createTranslationRoutes.ts

@@ -5,7 +5,6 @@ import { isCollectionAvailable } from "../_lib/collection-utils";
 
 import { GetDocumentStalenessInputSchema } from "./model";
 import type { StalenessConfig } from "./model";
-import { computeDocumentStaleness } from "./service";
 
 /**
  * Reads per-locale staleness for a single document. Best-effort: a recompute failure (e.g. the
@@ -28,12 +27,8 @@ export class GetDocumentStalenessHandler {
     }
 
     try {
-      const locales = await computeDocumentStaleness(
-        req.payload,
-        this.config,
-        collectionSlug,
-        collection_id
-      );
+      const service = this.config.provenanceServiceFactory?.(req.payload);
+      const locales = service ? await service.getStaleness(collectionSlug, collection_id) : [];
       return ServerResponse.success({ locales });
     } catch (error) {
       req.payload.logger.error({

packages/payload-plugin-translator/src/server/features/staleness/dismissStaleness.handler.ts

@@ -1,2 +1,2 @@
 export { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./route";
-export type { StalenessConfig, StalenessLocaleOutput } from "./model";
+export type { StalenessConfig } from "./model";