@openora/core 0.4.0

package/turbo-generators/src/templates/module/agents.hbs

@@ -0,0 +1,67 @@
+# {{pascalCase name}} Add-on - AGENTS.md
+
+Generated by `pnpm gen module {{group}} {{kebabCase name}}`. A standalone `@openora-addons/{{kebabCase name}}`
+package. The scaffold ships a working `list` route end to end; extend it, then fill in the
+sections below before opening a PR.
+
+## What this add-on does
+
+<!-- One paragraph: what business domain does this own? What problem does it solve? -->
+
+## Layout (a standalone package under `packages/addons/{{kebabCase name}}/`)
+
+| Layer | File | Holds |
+|---|---|---|
+| schema | `src/schema/index.ts` | Drizzle `pgTable`s + row types (`$inferSelect`). Every table carries `tenantId`. |
+| service | `src/service/{{kebabCase name}}.service.ts` | ALL business logic; emits events after DB commit; money in `db.transaction` |
+| router | `src/router/index.ts` | thin oRPC wiring: resolve caller, call service, `mapErrors` |
+| plugin | `src/plugin.ts` | DI wiring only: `ctx.routers.add(...)`, `ctx.provide(...)` |
+
+This is a CORE add-on: its contract slice lives in `packages/contracts/orpc-contract/src/{{kebabCase name}}.ts`
+(the source of truth for shapes) and its migrations are generated centrally from
+`packages/platform/db` (the scaffolder adds the schema glob there). The router does
+`implement(contract.{{camelCase name}})`. Registered with NO `kind` in `extensions.config.ts`,
+so it always loads.
+
+## Extension points
+
+### Ports (adapter interfaces)
+Define the vendor interface + DI token in `@openora/adapters`
+(`packages/contracts/adapters/src/<category>.ts`) via `createToken<T>('NAME')`, implement it
+under `src/adapters/<vendor>/`, and bind it in `plugin.ts` with
+`ctx.provide(TOKEN, () => new Impl())`. Services depend on the port, never on the container.
+
+| Interface | Token | Purpose |
+|---|---|---|
+| <!-- `{{pascalCase name}}Provider` --> | <!-- `{{constantCase name}}_PROVIDER` --> | <!-- external calls --> |
+
+### Events emitted (declare payloads in `@openora/shared-schemas` events.ts via `pnpm gen event <topic>`)
+| Topic | Payload | When |
+|---|---|---|
+| <!-- `{{kebabCase name}}.created` --> | <!-- `{ id, tenantId }` --> | <!-- after insert commit --> |
+
+### oRPC routes
+| Procedure | Method | Path | Admin? |
+|---|---|---|---|
+| `{{camelCase name}}.list` | GET | `/{{kebabCase name}}` | no |
+
+## Do
+
+- Put business logic in `src/service/{{kebabCase name}}.service.ts`; keep the router thin.
+- Define new shapes in the contract slice; derive variants with `.pick()/.omit()/.extend()`.
+- New Drizzle tables in `src/schema/index.ts` (always with `tenantId`), then `pnpm regen`.
+- Add routes with `pnpm gen route {{kebabCase name}} <METHOD> <path>`; admin handlers call
+  `await adminGuard.assert(context)` first (the plugin passes `c.get(ADMIN_GUARD)` to the factory).
+- Cross-module reads: import another add-on's tables via `@openora-addons/<name>/schema`
+  (read-only). For synchronous money/answers use a command port (eg `WALLET_COMMANDS`).
+- Emit events AFTER the DB commit via the injected `EventBus`; use `emitInTransaction` for
+  durable money-critical events.
+
+## Don't
+
+- Import another add-on's root or internals (lint errors). Talk via events / command ports /
+  contracts / the `/schema` subpath.
+- Call a vendor SDK / `fetch` directly - define a port + adapter.
+- Throw HTTP errors from the service - throw domain errors, map them in the router.
+- Import another `@openora-addons/*` package (cross-add-on imports are lint errors).
+- Define ad-hoc Zod in `router/` or use `any` (both lint-enforced).

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

@@ -0,0 +1,22 @@
+import 'dotenv/config';
+import { defineConfig } from 'drizzle-kit';
+
+// This add-on owns its migration history + tracking table. One database shared with
+// sibling modules, but one journal per module so it can be installed or extracted
+// independently without history surgery. See ADR-0020/0027.
+export default defineConfig({
+  dialect: 'postgresql',
+  casing: 'snake_case',
+  schema: ['./src/schema/index.ts'],
+  out: './drizzle/migrations',
+  migrations: {
+    table: '__drizzle_migrations_addon_{{snakeCase name}}',
+    schema: 'drizzle',
+  },
+  dbCredentials: {
+    url:
+      process.env['DATABASE_ADMIN_URL'] ??
+      process.env['DATABASE_URL'] ??
+      'postgresql://postgres:postgres@localhost:5432/oss_igaming',
+  },
+});

package/turbo-generators/src/templates/module/index.hbs

@@ -0,0 +1,5 @@
+// Public surface of the {{pascalCase name}} add-on. Export only what other packages
+// may consume; internal implementation details stay private. Cross-module table
+// reads go through the `@openora-addons/{{kebabCase name}}/schema` subpath.
+export { {{pascalCase name}}Service } from './service/{{kebabCase name}}.service.js';
+export { create{{pascalCase name}}Router } from './router/index.js';

package/turbo-generators/src/templates/module/migrate.hbs

@@ -0,0 +1,15 @@
+// Applies this add-on's own migration set against its own tracking table, so it never
+// collides with sibling modules sharing the database. SQL ships in the tarball (`files`)
+// and loads via an import.meta.url-relative path. See ADR-0020/0027.
+import { fileURLToPath } from 'node:url';
+import { runMigrations } from '@openora/core/server/migrate';
+
+/** Apply the {{kebabCase name}} add-on migrations (idempotent: drizzle skips already-recorded ones). */
+export function migrate(databaseUrl?: string): Promise<void> {
+  return runMigrations({
+    migrationsFolder: fileURLToPath(new URL('../drizzle/migrations', import.meta.url)),
+    migrationsTable: '__drizzle_migrations_addon_{{snakeCase name}}',
+    migrationsSchema: 'drizzle',
+    ...(databaseUrl ? { databaseUrl } : {}),
+  });
+}

package/turbo-generators/src/templates/module/package.json.hbs

@@ -0,0 +1,62 @@
+{
+  "name": "@openora-addons/{{kebabCase name}}",
+  "version": "0.0.1",
+  "license": "AGPL-3.0-only",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js",
+      "default": "./dist/schema/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./migrate": {
+      "types": "./dist/migrate.d.ts",
+      "import": "./dist/migrate.js",
+      "default": "./dist/migrate.js"
+    }
+  },
+  "files": ["dist", "drizzle"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "generate": "drizzle-kit generate",
+    "test": "vitest run",
+    "test:unit": "vitest run --passWithNoTests",
+    "test:integration": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@orpc/contract": "1.14.5",
+    "@orpc/server": "1.14.5",
+    "@openora/adapters": "workspace:*",
+    "@openora/auth": "workspace:*",
+    "@openora/core": "workspace:*",
+    "@openora/db": "workspace:*",
+    "@openora/orpc-contract": "workspace:*",
+    "@openora/plugin-host": "workspace:*",
+    "@openora/shared-schemas": "workspace:*",
+    "@paralleldrive/cuid2": "3.3.0",
+    "drizzle-orm": "0.45.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@openora/vitest-config": "workspace:*",
+    "@types/node": "25.9.2",
+    "drizzle-kit": "0.31.10",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
+  }
+}

package/turbo-generators/src/templates/module/plugin.hbs

@@ -0,0 +1,20 @@
+import { definePlugin } from '@openora/plugin-host';
+import { EVENT_BUS } from '@openora/core';
+import { DRIZZLE } from '@openora/db';
+import { {{pascalCase name}}Service } from './service/{{kebabCase name}}.service.js';
+import { create{{pascalCase name}}Router } from './router/index.js';
+
+// DI wiring only - no business logic here. The router factory resolves deps from
+// the container at boot (after every plugin registered), so an overlay can rebind
+// an adapter token (last registration wins) without a fork.
+export default definePlugin({
+  id: '{{kebabCase name}}',
+  // dependsOn: ['identity'], // declare deps so the loader boots them first
+  register(ctx) {
+    // AGENT: bind any vendor adapters before mounting the router, e.g.
+    //   ctx.provide(SOME_ADAPTER, () => new MockSomeAdapter());
+    ctx.routers.add('{{camelCase name}}', (c) =>
+      create{{pascalCase name}}Router(new {{pascalCase name}}Service(c.get(DRIZZLE), c.get(EVENT_BUS))),
+    );
+  },
+});

package/turbo-generators/src/templates/module/router.hbs

@@ -0,0 +1,19 @@
+import { implement } from '@orpc/server';
+import { type OssContext } from '@openora/core';
+import { contract } from '@openora/orpc-contract';
+import { {{pascalCase name}}Service } from '../service/{{kebabCase name}}.service.js';
+
+// oRPC router factory for {{pascalCase name}}. plugin.ts builds the service from the
+// container and passes it here; each procedure delegates to the service. Keep this
+// thin: resolve the caller, call the service, map domain errors - no business rules.
+// Admin-only procedures MUST `await adminGuard.assert(context)` first (lint: require-admin-guard).
+export function create{{pascalCase name}}Router({{camelCase name}}: {{pascalCase name}}Service) {
+  const os = implement(contract.{{camelCase name}}).$context<OssContext>();
+
+  return os.router({
+    list: os.list.handler(() => {{camelCase name}}.list()),
+
+    // AGENT: add more procedures here. Define their shapes in the contract slice
+    // (packages/contracts/orpc-contract/src/{{kebabCase name}}.ts), never inline Zod here.
+  });
+}

package/turbo-generators/src/templates/module/schema.hbs

@@ -0,0 +1,21 @@
+import { pgTable, text, timestamp, index } from 'drizzle-orm/pg-core';
+import { createId } from '@paralleldrive/cuid2';
+
+// Drizzle tables owned by the {{pascalCase name}} module.
+// Rules:
+//   - Every multi-tenant table MUST include a `tenantId` column (lint: require-tenant-id).
+//   - Do NOT add FK references to tables owned by other modules - reference by id.
+//   - Table names are snake_case; exported consts are camelCase.
+export const {{camelCase name}} = pgTable(
+  '{{snakeCase name}}',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+    tenantId: text('tenantId').notNull(),
+    createdAt: timestamp('createdAt').notNull().defaultNow(),
+  },
+  (t) => [index('{{snakeCase name}}_tenantId_idx').on(t.tenantId)],
+);
+
+export type {{pascalCase name}} = typeof {{camelCase name}}.$inferSelect;

package/turbo-generators/src/templates/module/service.hbs

@@ -0,0 +1,26 @@
+import { DrizzleService } from '@openora/db';
+import { type EventBus } from '@openora/core';
+import { {{camelCase name}} } from '../schema/index.js';
+
+// Pure business logic for {{pascalCase name}}. A plain class wired by plugin.ts via
+// the composition container (no decorators). Methods read as data-in/data-out
+// transforms; isolate side effects (DB writes, event emits) at the edges. Throw
+// domain errors (makeNotFoundError from @openora/core), never HTTP/transport errors.
+// Money mutations MUST run inside `this.drizzle.db.transaction(...)` (lint: money-in-transaction).
+export class {{pascalCase name}}Service {
+  constructor(
+    private readonly drizzle: DrizzleService,
+    private readonly events: EventBus,
+  ) {}
+
+  // Reference list method - the scaffolded `list` route delegates here. Replace the
+  // projection / add filters as your domain needs. Selecting only contract fields
+  // keeps the return type aligned with the output schema.
+  async list(): Promise<Array<{ id: string; tenantId: string }>> {
+    return this.drizzle.db
+      .select({ id: {{camelCase name}}.id, tenantId: {{camelCase name}}.tenantId })
+      .from({{camelCase name}});
+  }
+
+  // AGENT: implement here - add the module's business methods below.
+}

package/turbo-generators/src/templates/module/tsconfig.json.hbs

@@ -0,0 +1,8 @@
+{
+  "extends": "@openora/core/tsconfig/node-service.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

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

@@ -0,0 +1,20 @@
+import { definePlugin } from '@openora/plugin-host';
+
+// Overlay plugin. Registered in extensions.config.ts (auto-wired in the OSS repo;
+// in a consumer repo add it to your apps/api/src/extensions.config.ts).
+//
+// In register(ctx) - the typed ModuleRegistry - you can:
+//   ctx.provide(TOKEN, (c) => new Impl())       - bind/rebind a DI token (last wins)
+//   ctx.routers.add(namespace, (c) => router)   - mount an oRPC router
+//   ctx.events.on(topic, (payload) => ...)       - subscribe to a domain event
+//   ctx.jobs.worker({ queue, schema, handler })  - register a background-job worker
+//   ctx.slots.fill(slotName, component)          - contribute a UI slot
+//   ctx.mcp.tool({ name, description, inputSchema, handler }) - expose an MCP tool
+export default definePlugin({
+  id: '{{kebabCase name}}',
+  // dependsOn: ['wallet'], // load after the plugin that owns a token you rebind
+  register(ctx) {
+    void ctx;
+    // AGENT: implement here
+  },
+});