@openora/create 0.4.1-canary.35 → 0.4.1-canary.351

package/template/docs/standards/git-delivery.md

@@ -0,0 +1,20 @@
+# Git and delivery
+
+Read this before a commit, PR, or branch operation.
+
+- Conventional commits, enforced by commitlint (husky locally, CI on the PR/MR title): `feat`, `fix`, `refactor`, `chore`,
+  `docs`, `test`, `ci`, `perf`. E.g. `feat(wallet): atomic debit command port`.
+- Subject starts lowercase, acronyms included (`feat(pam): kyc status filter`). This applies to
+  the PR title too - squash merges derive the commit message from it.
+- One PR = one concern. Stage files explicitly; never `git add -A` when foreign changes are in
+  the tree.
+- Green before review: `pnpm verify` on the committed tree. It is the full gate and records the
+  verified commit; the `guard-mr` hook blocks opening the PR/MR without it.
+- Branch off `dev`; never commit directly to a shared branch; never push without an explicit
+  per-action "yes push", except the ticket branch `/ship` opens its MR from.
+- PR description carries intent: what / why / acceptance criteria / ticket link. No secrets,
+  internal hostnames, or PII - it is the public record.
+- A PR that adds or changes a flow across components (request path, state machine, async job or
+  webhook, a new module, overlay or vendor binding) carries a Mermaid `flowchart` or
+  `sequenceDiagram` of it: nodes named as in the code, under ~15 nodes, refusal and failure
+  branches included. No flow, no diagram.

package/template/docs/standards/module-structure.md

@@ -0,0 +1,37 @@
+# Package and module structure
+
+Read this before creating a package, an overlay add-on, or wiring a new module's internal layout.
+
+- One package = one concern, named `@<scope>/<kebab>`, with an explicit `exports` map. The
+  entrypoint IS the public API; everything else is internal and off-limits to consumers
+  (`oss-boundaries`).
+- Overlay/add-on packages mirror the platform module shape: `contract/`, `schema/`, `service/`,
+  `router/`, `adapters/`, `__tests__/`, plus `plugin.ts` at the root as the single wiring point.
+
+| Layer    | File                        | Holds                                                           | Must NOT hold                    |
+| -------- | --------------------------- | --------------------------------------------------------------- | -------------------------------- |
+| schema   | `schema/index.ts`           | Drizzle `pgTable`s; row types via `$inferSelect`/`$inferInsert` | logic                            |
+| contract | `contract/index.ts`         | oRPC route contract + req/res Zod schemas                       | logic, transport wiring          |
+| service  | `service/<name>.service.ts` | ALL business logic; emits events after DB commit                | HTTP/transport knowledge         |
+| router   | `router/index.ts`           | thin oRPC wiring: resolve caller, call service, map errors      | business rules                   |
+| plugin   | `plugin.ts`                 | DI wiring only: `ctx.provide(...)`, route registration          | logic                            |
+| adapters | `adapters/<vendor>/`        | concrete impls of adapter ports                                 | being imported by another module |
+
+- Each overlay owns its `drizzle.config.ts` and its own migration history - never share one
+  migration folder across packages.
+- Pin exact dependency versions in every package; a package never depends on an app.
+- Add a dependency deliberately - std lib or a few lines often beat a tree.
+
+```ts
+// bad - a service reaches into the container and hides what it depends on
+export class WalletService {
+  constructor(private readonly container: Container) {}
+}
+// good - deps are constructor params of their port type; plugin.ts does the resolving
+export class WalletService {
+  constructor(
+    private readonly db: DrizzleService,
+    private readonly payments: PaymentAdapter,
+  ) {}
+}
+```

package/template/docs/standards/testing.md

@@ -0,0 +1,88 @@
+# Testing
+
+Read this before adding or restructuring a test.
+
+## When a test is written
+
+A feature or fix PR carries **its own tests**, written in the same branch from the manual
+verification pass that proves the change works. There is no separate test PR.
+
+Before the PR opens:
+
+1. Drive the change against the running stack. Reach for the **Playwright CLI** first
+   (`playwright-cli`, or a throwaway spec that clicks through the flow) - it costs a fraction of
+   the tokens a browser MCP does. Use a browser MCP only for a live console or network read the CLI
+   cannot give you. No videos in this pass, except a fix's "before" clip, taken when you reproduce
+   the bug: the code can still change before review is clean. Every changed screen gets the
+   `ui-verify` skill's screenshot review: four shots (mobile and desktop, light and dark), each
+   read for layout defects and given a PASS or FAIL line. Screenshots are for the agent, videos
+   for the reviewer.
+2. Capture the evidence once, on the final commit, after the tests are green and review is clean:
+   one short video per acceptance criterion, ending on the outcome it names, and the "after" twin
+   of a fix's "before" clip. Run every browser spec that drives an AC in one command with video on
+   (`test.use({ video: 'on' })` or the repo's record switch); `playwright-cli` with `video-start` /
+   `video-stop` only for an AC no spec drives. An API-only change attaches the request/response
+   trace instead.
+3. Attach that evidence **to the PR description**, not only to your report - a reviewer confirms a
+   change by looking at it.
+4. Write the tests that pass exercised, in this branch, at the tier the table below names. Include
+   the hostile paths and the authz negatives. A fix carries the test that fails without it.
+5. End the description with a **"Tests"** list: one line per test added, naming its tier
+   (unit / API E2E / browser E2E) and path.
+
+A changed behaviour with no test is a review `[WARN]`, never a `[BLOCK]`, except on the paths below.
+
+## Tests that catch the bug
+
+A test that still passes when the code it covers is broken checks nothing. On a money, KYC,
+responsible-gambling or authz path, break each changed check on purpose (flip a condition, move a
+boundary by one, drop an owner check, change the sign of an amount) and run the tests: at least one
+must fail. The tester does this in its pass and lists each break as a mutation row in its verdict
+table; a break no test catches on those paths holds the PR until a test catches it. Where the repo
+has a `test:mutation` script, it does the breaking for you; the repo-wide mutation score is shown,
+not a gate.
+
+## Pick the tier
+
+Pick the OUTERMOST tier that can reach the behaviour - a test earns its keep by running real code,
+not by being cheap.
+
+| What you changed                                              | Tier                                          |
+| ------------------------------------------------------------- | --------------------------------------------- |
+| A screen, a form, a player/admin journey                      | Browser E2E (`apps/e2e/tests/<app>/**`)       |
+| An API route, an overlay, a vendor adapter, anything with SQL | API E2E (`apps/e2e/tests/api/**`)             |
+| A pure function - parser, resolver, mapper, money calculation | Unit (`src/__tests__/<name>.test.ts`, Vitest) |
+
+The API tier drives the real API over HTTP against real Postgres, with each external vendor
+replaced by a stub HTTP server the API is pointed at by env. It is the default tier for
+`apps/api/src/extensions/**`: an overlay is wiring, and wiring is exactly what a unit test skips.
+
+## What is real, what is doubled
+
+- **Anything that touches the database is tested against real Postgres.** Never fake a query
+  builder: a stubbed chain proves a call order, not a result, so it misses the regressions that
+  matter - a unique-index conflict, a wrong `where`, a lost race, a rollback that never happened.
+- **External vendors are stubbed at their HTTP boundary** (a `node:http` stand-in the API's
+  base-URL env var points at), never by mocking our own adapter - a mocked adapter skips exactly
+  the wiring the test exists to check. Every vendor adapter therefore accepts a base-URL override.
+- **A spy assertion is never the point of a test.** `expect(client.x).toHaveBeenCalledWith(...)`
+  only restates the line above it. A spy may stand in for an outbound vendor call, never for the
+  thing under test.
+
+```ts
+// bad - a mocked builder chain proves a call order, not a result
+const db = { select: vi.fn().mockReturnValue({ from: vi.fn().mockResolvedValue([row]) }) };
+expect(db.select).toHaveBeenCalled();
+// good - assert the outcome
+expect(await service.get(id)).toEqual(row);
+```
+
+## How to write them
+
+- Test behavior, not implementation - tests must survive a safe refactor (assert outputs, not
+  private caches).
+- Cover the change in the same PR as the change; always include the authz negatives.
+- Drive a vendor's inbound side the way the vendor does: post the real webhook shape to the real
+  route with a signature the stub's key material produces. Never call the adapter directly.
+- Deterministic and isolated: no shared mutable state, no real outbound network, seedable data.
+  Own the rows a test creates and clean them up - the API suite shares one database.

package/template/docs/standards/types.md

@@ -0,0 +1,31 @@
+# Types
+
+Read this before adding or changing a schema, type, or enum-like value set.
+
+- One source of truth per shape - infer, never hand-write a type that already exists:
+  `z.infer<typeof UserSchema>`, `typeof users.$inferSelect`, `Omit<User, 'id'>`.
+- Schema-first at every boundary (HTTP, config, env, messages, events): validate once at the edge,
+  trust the type after. oRPC + Zod does this for routes; do the same elsewhere.
+- Never re-infer a schema you imported - the owning contract exports the type once; import it.
+- No `any` outside tests - `unknown` + narrowing.
+- No `as` casts to silence the compiler - fix the root cause (`as const` is fine).
+- Never `!` non-null assertions - narrow explicitly, or restructure so the value is provably
+  present (carry it on the object instead of re-looking it up).
+- Under `noUncheckedIndexedAccess`: `.at()`, destructure-with-default
+  (`const [first = ''] = parts`), or an explicit guard - never `arr[i]!`.
+- `type` over `interface` (lint-enforced).
+- Type entity ids through their owning type (`playerId: Player['id']`), never a bare `string`.
+- Derive related schemas with `.pick()/.omit()/.partial()/.extend()/.merge()` - never re-type
+  fields.
+- Enum-like value sets are a values + schema + type triple declared once on the contract surface:
+  `X_STATUSES = [...] as const` -> `XStatusSchema = z.enum(X_STATUSES)` -> inferred `XStatus`.
+  Never a TS `enum`, never a second hand-typed copy - import the one from `@openora/*`.
+- Make illegal states unrepresentable - discriminated unions
+  (`{ status: 'ok'; data } | { status: 'error'; error }`) over optional-flag soup.
+
+```ts
+// bad - hand-written duplicate of an inferrable type
+type User = { id: string; email: string; roles: string[] };
+// good - infer from the schema that already validates the shape
+type User = z.infer<typeof UserSchema>;
+```

package/template/package.json.tpl

@@ -8,25 +8,31 @@
     "build": "turbo run build",
     "check:types": "turbo run check:types",
     "check:lint": "oxlint .",
+    "test:unit": "turbo run test:unit",
+    "verify": "turbo run check:types check:lint test:unit && node .rulesync/hooks/guard-mr.mjs --stamp",
     "gen:agents": "rulesync generate",
-    "prepare": "rulesync generate",
+    "sync:agents": "node tools/sync-agents.mjs",
+    "oss:worktree": "node tools/oss-worktree.mjs",
+    "review:precheck": "node tools/review-precheck.mjs",
+    "prepare": "node tools/sync-agents.mjs && rulesync generate",
     "db:migrate": "pnpm -F @{{name}}/api exec openora-migrate",
     "db:seed": "pnpm -F @{{name}}/api db:seed",
     "gen": "turbo gen"
   },
   "devDependencies": {
+    "@openora/create": "{{coreVersion}}",
     "@openora/mcp": "latest",
-    "@turbo/gen": "2.9.14",
-    "@types/node": "25.9.0",
-    "oxlint": "1.64.0",
-    "rulesync": "8.25.0",
-    "tsx": "4.22.2",
-    "turbo": "2.9.14",
-    "typescript": "6.0.3"
+    "@turbo/gen": "{{turboVersion}}",
+    "@types/node": "{{typesNodeVersion}}",
+    "oxlint": "{{oxlintVersion}}",
+    "rulesync": "{{rulesyncVersion}}",
+    "tsx": "{{tsxVersion}}",
+    "turbo": "{{turboVersion}}",
+    "typescript": "{{typescriptVersion}}"
   },
   "engines": {
     "node": ">=22.0.0",
     "pnpm": ">=10.0.0"
   },
-  "packageManager": "pnpm@11.5.2"
+  "packageManager": "{{packageManager}}"
 }

package/template/rulesync.jsonc

@@ -8,13 +8,13 @@
   // AGENTS.md stays a clean human brief (no simulated-command boilerplate).
   // Hooks + permissions are NOT managed here - .claude/settings.json is hand-maintained
   // (it holds the guard hooks), so rulesync never clobbers it.
-  // codexcli: rules (AGENTS.md) + mcp (.codex/config.toml) only - its commands/
-  // subagents are simulation-only (kept off) and it has no hooks system.
+  // codexcli: rules (AGENTS.md), mcp (.codex/config.toml) and hooks (.codex/hooks.json, so
+  // the guards judge its apply_patch edits) - its commands/subagents are simulation-only (kept off).
   "targets": {
     "agentsmd": ["rules"],
     "claudecode": ["rules", "mcp", "subagents", "commands", "skills"],
     "copilot": ["rules", "mcp", "subagents", "commands", "hooks"],
-    "codexcli": ["rules", "mcp"],
+    "codexcli": ["rules", "mcp", "hooks"],
   },
 
   // rulesync emits Copilot agents/prompts natively - no simulation needed.

package/template/tools/oss-worktree.mjs.tpl

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// A git worktree of the sibling OSS checkout - the only place an agent in this repo may change
+// OSS code (the guard-core hook allows {{ossFromRoot}}/.worktrees/ and denies the rest of the
+// checkout). Same command for every agent and every human, so a paired change looks the same
+// on every machine.
+//
+//   pnpm oss:worktree <branch>            create or reuse the worktree, install its deps
+//   pnpm oss:worktree <branch> --link     ...then build it and point `pnpm link:oss` at it
+//   pnpm oss:worktree <branch> --remove   remove it; relinks the main checkout if it was linked
+//
+// Use the same branch name as this repo's branch: that is how skills pair the two requests.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+// oxlint-disable no-console
+
+// This repo is often checked out as a git worktree, whose `.git` is a file pointing at
+// <main>/.git/worktrees/<name>. The sibling OSS checkout sits next to the MAIN checkout, so
+// resolve from there or every path below lands inside the worktree.
+const mainCheckoutOf = (dir) => {
+  try {
+    const pointer = readFileSync(join(dir, '.git'), 'utf8');
+    const gitdir = pointer.match(/^gitdir:\s*(.*[/\\]worktrees[/\\][^/\\]+?)\s*$/m)?.[1];
+    return gitdir ? resolve(dir, gitdir, '..', '..', '..') : dir;
+  } catch {
+    return dir; // `.git` is a directory (the main checkout) or missing
+  }
+};
+
+const OSS = resolve(mainCheckoutOf(process.cwd()), '{{ossFromRoot}}');
+const USAGE = 'usage: pnpm oss:worktree <branch> [--link | --remove]';
+
+const die = (message) => {
+  console.error(`oss:worktree - ${message}`);
+  process.exit(1);
+};
+
+const [branch, flag] = process.argv.slice(2);
+if (!branch || branch.startsWith('--') || (flag && !['--link', '--remove'].includes(flag))) {
+  die(USAGE);
+}
+if (!existsSync(join(OSS, '.git'))) {
+  die(`no OSS checkout at ${OSS} - clone it next to this repo first.`);
+}
+
+const worktree = join(OSS, '.worktrees', branch.replaceAll('/', '+'));
+const worktreeFromHere = relative(process.cwd(), worktree);
+// A fresh worktree has no node_modules yet, so the checkout's own post-checkout hook would run
+// against tools it cannot resolve and fail the command. The install below does that setup.
+const GIT = ['-C', OSS, '-c', 'core.hooksPath=/dev/null'];
+const git = (...args) =>
+  execFileSync('git', [...GIT, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] }).trim();
+const gitOrEmpty = (...args) => {
+  try {
+    return execFileSync('git', [...GIT, ...args], { encoding: 'utf8', stdio: 'pipe' }).trim();
+  } catch {
+    return '';
+  }
+};
+const run = (cmd, args) => execFileSync(cmd, args, { stdio: 'inherit' });
+const hasLinkScript = () =>
+  Boolean(JSON.parse(readFileSync('package.json', 'utf8')).scripts?.['link:oss']);
+const isLinkedTo = (dir) =>
+  existsSync('pnpm-workspace.yaml') &&
+  readFileSync('pnpm-workspace.yaml', 'utf8').includes(`link:${relative(process.cwd(), dir)}/`);
+
+if (flag === '--remove') {
+  const wasLinked = isLinkedTo(worktree);
+  if (existsSync(worktree)) {
+    try {
+      git('worktree', 'remove', worktree);
+    } catch {
+      die(`${worktreeFromHere} has uncommitted changes - commit or discard them, then rerun.`);
+    }
+  }
+  if (wasLinked && hasLinkScript()) {
+    run('pnpm', ['link:oss']);
+  }
+  console.log(`removed ${worktreeFromHere}`);
+  process.exit(0);
+}
+
+if (!existsSync(worktree)) {
+  git('fetch', 'origin', '--quiet');
+  const base = gitOrEmpty('rev-parse', '--abbrev-ref', 'origin/HEAD') || 'origin/dev';
+  if (gitOrEmpty('rev-parse', '--verify', '--quiet', `refs/heads/${branch}`)) {
+    git('worktree', 'add', worktree, branch);
+  } else if (gitOrEmpty('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`)) {
+    git('worktree', 'add', '--track', '-b', branch, worktree, `origin/${branch}`);
+  } else {
+    git('worktree', 'add', '--no-track', '-b', branch, worktree, base);
+  }
+  run('pnpm', ['-C', worktree, 'install', '--frozen-lockfile']);
+}
+
+if (flag === '--link') {
+  if (!hasLinkScript()) {
+    die('this repo has no `link:oss` script - link the worktree through pnpm overrides by hand.');
+  }
+  // @openora/* resolve from dist/, so a linked worktree works only once it is built.
+  run('pnpm', ['-C', worktree, 'build']);
+  run('pnpm', ['link:oss', worktreeFromHere]);
+}
+
+console.log(worktreeFromHere);