@openora/core 0.4.0 → 0.4.1-canary.100

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

@@ -1,67 +0,0 @@
-# {{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

@@ -1,22 +0,0 @@
-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

@@ -1,5 +0,0 @@
-// 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

@@ -1,15 +0,0 @@
-// 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

@@ -1,62 +0,0 @@
-{
-  "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

@@ -1,20 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

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

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

@@ -1,20 +0,0 @@
-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
-  },
-});