@openora/core 0.4.0

package/tsconfig/base.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "tsBuildInfoFile": "${configDir}/dist/.tsbuildinfo",
+    "strict": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "moduleDetection": "force",
+    "target": "ES2022",
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "exclude": ["node_modules", "dist", "coverage", ".turbo"]
+}

package/tsconfig/nextjs.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "incremental": true,
+    "allowJs": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "plugins": [{ "name": "next" }]
+  }
+}

package/tsconfig/node-service.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "exactOptionalPropertyTypes": false,
+    "noUncheckedIndexedAccess": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "strictPropertyInitialization": false,
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM"],
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "types": ["node"],
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  }
+}

package/tsconfig/node.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "types": ["node"],
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  }
+}

package/tsconfig/react-lib.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  }
+}

package/turbo-generators/src/config.ts

@@ -0,0 +1,466 @@
+import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import type { PlopTypes } from '@turbo/gen';
+
+// The single generation surface for the platform. ONE Plop engine, ONE template
+// dir - used by both the OSS monorepo and downstream consumer repos (a consumer's
+// `turbo/generators/config.ts` re-exports this default). Humans run `pnpm gen
+// <type> ...`; AI agents call the same via the MCP `scaffold-*` tools. See the
+// "How to add ..." sections in AGENTS.md.
+//
+//   pnpm gen module <group> <name>   - business module (schema/service/router/plugin)
+//   pnpm gen route <module> <M> <p>  - oRPC procedure + contract entry
+//   pnpm gen plugin <name>           - overlay plugin
+//   pnpm gen adapter <name> <token>  - overlay that rebinds a vendor adapter token
+//   pnpm gen config <name>           - operator config schema block
+//   pnpm gen event <topic>           - domain event payload in the catalog
+//   pnpm gen job-worker <name>       - JOB_QUEUE worker overlay
+//   pnpm gen adr <title>             - architecture decision record
+//   pnpm gen service <name> <mods>   - thin single-service host (SERVICE_MANIFEST)
+//   pnpm gen app <dir>               - downstream consumer repo
+
+// turbo gen bundles this config into a CJS file inside the *consumer* repo, so
+// import.meta.url / __dirname point at the consumer, not here, and the .hbs files
+// are never copied. Resolve our own install dir through node_modules (the bundle
+// is CJS, so `require.resolve` is the real Node resolver) and read templates by
+// absolute path.
+declare const require: NodeJS.Require;
+const pkgDir = dirname(require.resolve('@openora/core/package.json'));
+const tpl = (name: string): string => join(pkgDir, 'turbo-generators', 'src', 'templates', name);
+
+const kebabRe = /^[a-z][a-z0-9-]*$/;
+const MODULE_GROUPS = ['player', 'backoffice', 'platform'] as const;
+
+// Plop hands actions an open `Answers` bag; read fields through these coercers.
+type Answers = Record<string, unknown>;
+const s = (a: Answers, k: string): string => String(a[k] ?? '');
+
+const toKebab = (v: string): string =>
+  v
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/\s+/g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '');
+const toCamel = (v: string): string =>
+  toKebab(v).replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+const root = (): string => process.cwd();
+// OSS monorepo has packages/addons; a consumer repo only has overlays.
+const isOssRepo = (): boolean => existsSync(join(root(), 'packages', 'addons'));
+// extensions.config.ts lives at the repo root (both OSS and consumer repos).
+const extensionsConfigPath = (): string => join(root(), 'extensions.config.ts');
+const ossOnly = (gen: string): void => {
+  if (!isOssRepo()) {
+    throw new Error(
+      `'gen ${gen}' is an OSS-core generator and only runs inside the oss monorepo. ` +
+        `In a consumer repo, extend via 'gen plugin' / 'gen adapter' overlays instead.`,
+    );
+  }
+};
+
+function registerExtension(id: string, importPath: string): string {
+  const file = extensionsConfigPath();
+  const line = `  { id: '${id}', path: '${importPath}' },`;
+  if (!existsSync(file)) {
+    writeFileSync(
+      file,
+      [
+        `// Registered plugins. Order matters - loaded top to bottom.`,
+        `export const extensions = [`,
+        line,
+        `];`,
+        ``,
+      ].join('\n'),
+    );
+    return `created ${file}`;
+  }
+  const src = readFileSync(file, 'utf8');
+  if (src.includes(`id: '${id}'`)) return `extensions.config.ts already has '${id}'`;
+  writeFileSync(file, src.replace(/(export const extensions = \[)/, `$1\n${line}`));
+  return `registered '${id}' in extensions.config.ts`;
+}
+
+function wireContractIndex(name: string): string {
+  const indexFile = join(root(), 'packages', 'contracts', 'orpc-contract', 'src', 'index.ts');
+  if (!existsSync(indexFile)) return 'no orpc-contract index (skipped)';
+  let src = readFileSync(indexFile, 'utf8');
+  if (src.includes(`from './${name}.js'`)) return `contract index already wires '${name}'`;
+  const camel = toCamel(name);
+  const contractName = `${camel}Contract`;
+  src = src.replace(/(^export\s)/m, `import { ${contractName} } from './${name}.js';\n\n$1`);
+  src = src.replace(
+    /(^export const contract)/m,
+    `export { ${contractName} } from './${name}.js';\n\n$1`,
+  );
+  src = src.replace(/^(\}\);)/m, `  ${camel}: ${contractName},\n$1`);
+  writeFileSync(indexFile, src);
+  return `wired '${camel}' into orpc-contract index`;
+}
+
+function appendEventSchema(topic: string): string {
+  const file = join(root(), 'packages', 'contracts', 'shared-schemas', 'src', 'events.ts');
+  if (!existsSync(file)) return 'no events.ts (skipped)';
+  let src = readFileSync(file, 'utf8');
+  if (src.includes(`'${topic}':`)) return `event '${topic}' already in the catalog`;
+  const entry = `  '${topic}': z.object({\n    // AGENT: define the payload (ids + primitives)\n  }),`;
+  src = src.replace(/(export const domainEventSchemas = \{)/, `$1\n${entry}`);
+  writeFileSync(file, src);
+  return `added '${topic}' to domainEventSchemas`;
+}
+
+function appendRoute(moduleName: string, method: string, routePath: string): string {
+  const name = toKebab(moduleName);
+  const moduleDir = join(root(), 'packages', 'addons', name);
+  if (!existsSync(moduleDir)) {
+    throw new Error(`add-on '${name}' not found under packages/addons/`);
+  }
+  const proc = routePath
+    .replace(/^\//, '')
+    .replace(/\/:(\w+)/g, 'By$1')
+    .replace(/[{}]/g, '')
+    .replace(/\//g, '.')
+    .replace(/[^a-zA-Z0-9.]/g, '');
+
+  const contractFile = join(root(), 'packages', 'contracts', 'orpc-contract', 'src', `${name}.ts`);
+  if (existsSync(contractFile)) {
+    let c = readFileSync(contractFile, 'utf8');
+    const camel = toCamel(name);
+    if (!c.includes(`${proc}:`)) {
+      const entry = `  ${proc}: oc.route({ method: '${method.toUpperCase()}', path: '${routePath}' }).output(z.object({})),`;
+      c = c.replace(new RegExp(`(export const ${camel}Contract = \\{)`), `$1\n${entry}`);
+      writeFileSync(contractFile, c);
+    }
+  }
+
+  const routerFile = join(moduleDir, 'src', 'router', 'index.ts');
+  let r = readFileSync(routerFile, 'utf8');
+  if (!r.includes(`${proc}: os.${proc}`)) {
+    const stub = `\n    ${proc}: os.${proc}.handler(() => ({})),`;
+    r = r.replace(/(\n\s*\}\);\s*\n\}\s*)$/, `${stub}$1`);
+    writeFileSync(routerFile, r);
+  }
+  return `added '${proc}' (${method.toUpperCase()} ${routePath}) to ${name} - implement the handler/service method, then pnpm regen`;
+}
+
+export default function generator(plop: PlopTypes.NodePlopAPI): void {
+  plop.setGenerator('module', {
+    description: 'New business module - a standalone @openora-addons/<name> core add-on package',
+    prompts: [
+      {
+        type: 'list',
+        name: 'group',
+        // The group no longer maps to a directory (every add-on lives flat under
+        // packages/addons/<name>). It is kept purely as descriptive metadata in the
+        // generated AGENTS.md / scaffold message.
+        message: 'Surface this add-on serves (metadata only):',
+        choices: [...MODULE_GROUPS],
+      },
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Add-on name (kebab-case):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      ossOnly('module');
+      const a = data ?? {};
+      const base = 'packages/addons/{{kebabCase name}}';
+      return [
+        {
+          type: 'add',
+          path: `${base}/package.json`,
+          templateFile: tpl('module/package.json.hbs'),
+        },
+        {
+          type: 'add',
+          path: `${base}/tsconfig.json`,
+          templateFile: tpl('module/tsconfig.json.hbs'),
+        },
+        {
+          type: 'add',
+          path: `${base}/src/schema/index.ts`,
+          templateFile: tpl('module/schema.hbs'),
+        },
+        {
+          type: 'add',
+          path: `${base}/src/service/{{kebabCase name}}.service.ts`,
+          templateFile: tpl('module/service.hbs'),
+        },
+        {
+          type: 'add',
+          path: `${base}/src/router/index.ts`,
+          templateFile: tpl('module/router.hbs'),
+        },
+        { type: 'add', path: `${base}/src/plugin.ts`, templateFile: tpl('module/plugin.hbs') },
+        { type: 'add', path: `${base}/src/index.ts`, templateFile: tpl('module/index.hbs') },
+        {
+          type: 'add',
+          path: `${base}/src/migrate.ts`,
+          templateFile: tpl('module/migrate.hbs'),
+        },
+        {
+          type: 'add',
+          path: `${base}/drizzle.config.ts`,
+          templateFile: tpl('module/drizzle.config.hbs'),
+        },
+        { type: 'add', path: `${base}/AGENTS.md`, templateFile: tpl('module/agents.hbs') },
+        {
+          type: 'add',
+          path: 'packages/contracts/orpc-contract/src/{{kebabCase name}}.ts',
+          templateFile: tpl('contract.hbs'),
+        },
+        // Core add-on: no `kind`, always loaded. Path points at the compiled plugin.
+        () =>
+          registerExtension(
+            toKebab(s(a, 'name')),
+            `./packages/addons/${toKebab(s(a, 'name'))}/dist/plugin.js`,
+          ),
+        () => wireContractIndex(toKebab(s(a, 'name'))),
+        () =>
+          `next: pnpm install (link the new package) && pnpm -F @openora-addons/${toKebab(s(a, 'name'))} generate (its own migration history) && pnpm regen && pnpm verify`,
+      ];
+    },
+  });
+
+  plop.setGenerator('route', {
+    description: 'Add an oRPC procedure (contract entry + router handler) to a module',
+    prompts: [
+      {
+        type: 'input',
+        name: 'module',
+        message: 'Module name:',
+        validate: (v: string) => (v ? true : 'required'),
+      },
+      {
+        type: 'list',
+        name: 'method',
+        message: 'HTTP method:',
+        choices: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+      },
+      {
+        type: 'input',
+        name: 'path',
+        message: 'Route path (eg /balance):',
+        validate: (v: string) => (v ? true : 'required'),
+      },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      ossOnly('route');
+      const a = data ?? {};
+      return [() => appendRoute(s(a, 'module'), s(a, 'method'), s(a, 'path'))];
+    },
+  });
+
+  plop.setGenerator('plugin', {
+    description: 'New overlay plugin (routes / providers / event handlers / jobs)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Plugin name (kebab-case):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+    ],
+    actions: [
+      {
+        type: 'add',
+        path: 'extensions/{{kebabCase name}}/plugin.ts',
+        templateFile: tpl('plugin.hbs'),
+      },
+      (a: Answers) =>
+        registerExtension(toKebab(s(a, 'name')), `./extensions/${toKebab(s(a, 'name'))}/plugin.ts`),
+    ],
+  });
+
+  plop.setGenerator('adapter', {
+    description: 'Overlay that swaps a vendor adapter (rebinds a DI token)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Adapter name (kebab-case, eg stripe-payment):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+      {
+        type: 'list',
+        name: 'token',
+        message: 'Which adapter token does this override?',
+        choices: [
+          'PAYMENT_ADAPTER',
+          'KYC_ADAPTER',
+          'NOTIFICATION_DELIVERY_ADAPTER',
+          'GEO_IP_ADAPTER',
+          'GAME_ADAPTER',
+          'AGGREGATOR_ADAPTER',
+          'RNG_ADAPTER',
+          'SEND_EMAIL',
+        ],
+      },
+      {
+        type: 'input',
+        name: 'dependsOn',
+        message: 'Load after which plugin (owns the default binding)?',
+        default: 'wallet',
+      },
+    ],
+    actions: [
+      {
+        type: 'add',
+        path: 'extensions/{{kebabCase name}}/plugin.ts',
+        templateFile: tpl('adapter.hbs'),
+      },
+      (a: Answers) =>
+        registerExtension(toKebab(s(a, 'name')), `./extensions/${toKebab(s(a, 'name'))}/plugin.ts`),
+    ],
+  });
+
+  plop.setGenerator('config', {
+    description: 'Operator config schema block (merge into PlatformConfigSchema)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Config name (kebab-case):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+    ],
+    actions: (): PlopTypes.ActionType[] => {
+      ossOnly('config');
+      return [
+        {
+          type: 'add',
+          path: 'packages/contracts/shared-schemas/src/config/{{kebabCase name}}.ts',
+          templateFile: tpl('config.hbs'),
+        },
+      ];
+    },
+  });
+
+  plop.setGenerator('event', {
+    description: 'Add a domain event payload to the shared-schemas catalog',
+    prompts: [
+      {
+        type: 'input',
+        name: 'topic',
+        message: "Event topic (eg 'wallet.payout.completed'):",
+        validate: (v: string) => (/^[a-z][\w.-]+$/.test(v) ? true : 'use <module>.<thing>.<verb>'),
+      },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      ossOnly('event');
+      const a = data ?? {};
+      return [() => appendEventSchema(s(a, 'topic'))];
+    },
+  });
+
+  plop.setGenerator('job-worker', {
+    description: 'Background-job worker overlay (consumes the JOB_QUEUE seam)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Queue / worker name (kebab-case):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+    ],
+    actions: [
+      {
+        type: 'add',
+        path: 'extensions/{{kebabCase name}}-worker/plugin.ts',
+        templateFile: tpl('job-worker.hbs'),
+      },
+      (a: Answers) =>
+        registerExtension(
+          `${toKebab(s(a, 'name'))}-worker`,
+          `./extensions/${toKebab(s(a, 'name'))}-worker/plugin.ts`,
+        ),
+    ],
+  });
+
+  plop.setGenerator('adr', {
+    description: 'New architecture decision record',
+    prompts: [
+      {
+        type: 'input',
+        name: 'title',
+        message: 'ADR title:',
+        validate: (v: string) => (v ? true : 'required'),
+      },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      const a = data ?? {};
+      const adrDir = join(root(), 'docs', 'adr');
+      const existing = existsSync(adrDir)
+        ? readdirSync(adrDir).filter((f) => /^\d{4}-/.test(f))
+        : [];
+      a['number'] = String(existing.length + 1).padStart(4, '0');
+      a['date'] = new Date().toISOString().slice(0, 10);
+      return [
+        {
+          type: 'add',
+          path: 'docs/adr/{{number}}-{{kebabCase title}}.md',
+          templateFile: tpl('adr.hbs'),
+        },
+      ];
+    },
+  });
+
+  plop.setGenerator('service', {
+    description: 'Thin single-purpose service host (bakes SERVICE_MANIFEST)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Service name (kebab-case):',
+        validate: (v: string) => (kebabRe.test(v) ? true : 'use kebab-case'),
+      },
+      {
+        type: 'input',
+        name: 'modules',
+        message: 'Module ids (comma-separated):',
+        validate: (v: string) => (v ? true : 'required'),
+      },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      ossOnly('service');
+      const a = data ?? {};
+      return [
+        () => {
+          execFileSync(
+            'pnpm',
+            ['exec', 'tsx', 'tools/create/create-service.ts', s(a, 'name'), s(a, 'modules')],
+            { cwd: root(), stdio: 'inherit' },
+          );
+          return `created apps/${toKebab(s(a, 'name'))}/ (SERVICE_MANIFEST=${s(a, 'modules')})`;
+        },
+      ];
+    },
+  });
+
+  plop.setGenerator('app', {
+    description: 'Scaffold a downstream consumer repo (api wired to this checkout)',
+    prompts: [
+      {
+        type: 'input',
+        name: 'dir',
+        message: 'Target directory (eg ../my-casino):',
+        validate: (v: string) => (v ? true : 'required'),
+      },
+      { type: 'input', name: 'appName', message: 'Project name:', default: '' },
+    ],
+    actions: (data?: Answers): PlopTypes.ActionType[] => {
+      ossOnly('app');
+      const a = data ?? {};
+      return [
+        () => {
+          const args = ['exec', 'tsx', 'tools/create/create-igaming-app.ts', s(a, 'dir')];
+          if (s(a, 'appName')) args.push('--name', s(a, 'appName'));
+          execFileSync('pnpm', args, { cwd: root(), stdio: 'inherit' });
+          return `scaffolded consumer repo at ${s(a, 'dir')}`;
+        },
+      ];
+    },
+  });
+}

package/turbo-generators/src/templates/adapter.hbs

@@ -0,0 +1,19 @@
+import { definePlugin } from '@openora/plugin-host';
+import { {{token}}, type {{pascalCase token}} } from '@openora/adapters';
+
+// Overlay that swaps the {{token}} binding. Registered AFTER `{{dependsOn}}` (which
+// owns the default binding) so this one wins - last registration of a DI token wins.
+// Implement every method of {{pascalCase token}} against your vendor. The factory's
+// declared return type keeps you honest at compile time; it throws until implemented.
+function create{{pascalCase name}}Adapter(): {{pascalCase token}} {
+  // AGENT: implement the {{pascalCase token}} interface here, then remove the throw.
+  throw new Error('{{kebabCase name}} adapter is not implemented yet');
+}
+
+export default definePlugin({
+  id: '{{kebabCase name}}',
+  dependsOn: ['{{dependsOn}}'],
+  register(ctx) {
+    ctx.provide({{token}}, () => create{{pascalCase name}}Adapter());
+  },
+});

package/turbo-generators/src/templates/adr.hbs

@@ -0,0 +1,23 @@
+# ADR-{{number}}: {{titleCase title}}
+
+**Date**: {{date}}
+**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
+
+## Context
+
+<!-- What problem are we solving? What constraints exist? -->
+
+## Decision
+
+<!-- What are we doing? Be specific. -->
+
+## Consequences
+
+**Positive:**
+- <!-- benefit -->
+
+**Negative / trade-offs:**
+- <!-- cost or limitation -->
+
+**Neutral:**
+- <!-- anything worth noting -->

package/turbo-generators/src/templates/config.hbs

@@ -0,0 +1,15 @@
+import * as z from 'zod';
+
+// Operator-only config block for {{pascalCase name}} (feature flags, brand/RG defaults,
+// etc). To activate it:
+//   1. Merge {{pascalCase name}}ConfigSchema into PlatformConfigSchema
+//      (packages/contracts/shared-schemas/src/platform-config.ts) via `.extend(...)`.
+//   2. Read it through `loadPlatformConfig()` (@openora/core), bound on the
+//      PLATFORM_CONFIG container token.
+// No admin UI in v1 - operators edit platform-config.yaml/.json. See ADR-0013 T0.
+export const {{pascalCase name}}ConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  // AGENT: define operator-tunable fields here
+});
+
+export type {{pascalCase name}}Config = z.infer<typeof {{pascalCase name}}ConfigSchema>;

package/turbo-generators/src/templates/contract.hbs

@@ -0,0 +1,18 @@
+import { oc } from '@orpc/contract';
+import * as z from 'zod';
+
+// Canonical request/response shapes for the {{pascalCase name}} module. This is the
+// single source of truth - the router validates against it, OpenAPI + the typed
+// client are emitted from it. Derive related shapes with .pick()/.omit()/.extend()
+// rather than re-typing fields. Promote anything shared across modules to
+// @openora/shared-schemas.
+export const {{pascalCase name}}Schema = z.object({
+  id: z.string(),
+  tenantId: z.string(),
+});
+
+export type {{pascalCase name}} = z.infer<typeof {{pascalCase name}}Schema>;
+
+export const {{camelCase name}}Contract = {
+  list: oc.route({ method: 'GET', path: '/{{kebabCase name}}' }).output(z.array({{pascalCase name}}Schema)),
+};

package/turbo-generators/src/templates/job-worker.hbs

@@ -0,0 +1,34 @@
+import { definePlugin } from '@openora/plugin-host';
+import { queue } from '@openora/adapters';
+import * as z from 'zod';
+
+// Background-job worker overlay for the '{{kebabCase name}}' queue. A service enqueues
+// work with `jobQueue.enqueue(queue('{{kebabCase name}}'), payload, { idempotencyKey })`
+// (resolve JOB_QUEUE from @openora/adapters in its plugin.ts); this overlay consumes it.
+// Delivery is AT-LEAST-ONCE - the handler MUST be idempotent (a DB unique-row guard,
+// not just idempotencyKey, for money). The default driver is in-process; the bullmq
+// overlay rebinds JOB_QUEUE to Redis when REDIS_URL is set. See ADR-0014.
+const {{camelCase name}}Payload = z.object({
+  // AGENT: define the job payload
+  id: z.string(),
+});
+
+export default definePlugin({
+  id: '{{kebabCase name}}-worker',
+  register(ctx) {
+    ctx.jobs.worker({
+      queue: queue('{{kebabCase name}}'),
+      schema: {{camelCase name}}Payload,
+      handler: async ({ payload, attempt }) => {
+        void attempt;
+        // AGENT: process the job idempotently.
+        void payload;
+      },
+      onDeadLetter: (ctx, error) => {
+        void ctx;
+        void error;
+        // AGENT: alert / persist the poison job after retries are exhausted.
+      },
+    });
+  },
+});