@openora/create 0.4.1-canary.31 → 0.4.1-canary.310

package/template/docs/standards/database.md

@@ -0,0 +1,77 @@
+# Database conventions (SQL / Drizzle)
+
+Read this in full before editing a schema, Drizzle query, migration config, or seed under
+`apps/api/**`. Tables live in `@openora/*` core for platform domains - never edit those; these
+rules govern the tables your overlay adds
+(`apps/api/src/extensions/<name>/src/schema/`). Import/boundary rules live in `oss-boundaries`;
+this file is SQL only.
+
+## Identifiers - snake_case everywhere
+
+Every drizzle instance sets `casing: 'snake_case'`, so the SQL name derives from the camelCase
+key. Pass an explicit name only where casing can't derive it: table names, `pgEnum` types, index
+names.
+
+```ts
+// good - key derives the column; const camelCase; explicit snake_case only for table + index
+export const playerNote = pgTable(
+  'player_note',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    playerId: uuid().notNull(), // -> player_id
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('player_note_player_id_idx').on(t.playerId)],
+);
+
+// bad - explicit/camelCase column names, PascalCase table
+pgTable('PlayerNote', { player_id: uuid('playerId') });
+```
+
+## Timestamps - always timestamptz
+
+```ts
+createdAt: timestamp({ withTimezone: true }); // good - Postgres timestamptz, store UTC
+createdAt: timestamp(); // bad - naive, drops the zone
+```
+
+Every datetime column (`createdAt`, `updatedAt`, `expiresAt`, any `*At`) carries the zone.
+
+## Keys, references, indexes
+
+- UUID primary keys (`uuid().primaryKey().defaultRandom()`).
+- **No foreign keys across a module/overlay boundary** - store a plain ID string and resolve via
+  the oRPC client or a schema subpath. FKs only within the same add-on.
+- `NOT NULL` by default; push defaults to the DB (`.notNull().default(...)`), not app code.
+- Index every column you filter or join on; name it `<table>_<cols>_idx`.
+
+## Efficient operations
+
+```ts
+// bad - N+1
+for (const id of ids) await db.select().from(wallet).where(eq(wallet.playerId, id));
+// good - one batched query
+await db.select().from(wallet).where(inArray(wallet.playerId, ids));
+```
+
+- Select only the columns you use; don't `select(*)` wide rows to read one field.
+- **Build rows by spread + override, never hand-copy field-by-field.** When a row mostly mirrors a
+  validated input, spread it and set only the server-computed fields - `db.insert(x).values({
+...input, id, createdAt })` - never re-list `field: input.field` per key (it silently drifts the
+  moment a column is added). Keep fields explicit only for: an order-sensitive hash/signature
+  payload; a source carrying columns the row must not receive (spread then omit them); or a
+  null-vs-undefined boundary that won't coerce (`actorId: input.actorId ?? null`).
+- **Money / critical paths are transactional and idempotent** - a DB guard inside the transaction,
+  not just an `idempotencyKey` (delivery is at-least-once).
+
+```ts
+await db.transaction(async (t) => {
+  if (await ledgerExists(t, idempotencyKey)) return; // guard, not just a key
+  await insertLedger(t, { idempotencyKey, amount, currency });
+});
+```
+
+## Migrations
+
+- Never hand-edit generated migrations. Change the `pgTable`, then `pnpm db:migrate`.
+- One migration per schema change; review the generated SQL before committing.

package/template/docs/standards/enforcement.md

@@ -0,0 +1,12 @@
+# Enforcement
+
+Read this before working around a failing gate or adding a lint rule.
+
+- `pnpm check:types` + `pnpm check:lint` (oxlint) + `pnpm test:unit` is the fast gate;
+  In repos that ship `pnpm check:boundaries` (dependency-cruiser), that is the whole-graph
+  boundary/cycle check, also run by the pre-commit hook and CI.
+- oxlint extends the platform's shared config (`./node_modules/@openora/core/oxlint/oxlintrc.json`)
+  - add local rules on top, never fork it.
+- Don't work around a lint/boundary violation - fix the import.
+- Agent rules are generated from `.rulesync/` via `pnpm gen:agents` - never hand-edit a generated
+  file.

package/template/docs/standards/errors.md

@@ -0,0 +1,26 @@
+# Errors
+
+Read this before adding an error class, a catch, or a money-handling path.
+
+- Fail fast at boundaries with typed errors (`CreateOrderSchema.parse(raw)` throws early).
+- No silent catches - log with context and rethrow.
+- Typed, named error classes via the shared factories (`makeNotFoundError`/`makeOwnershipError`/
+  `makeConflictError`); the router's `mapErrors` keys off the exported class.
+- `ORPCError.message` is an English fallback for logs, not player-facing copy - UI copy keys off
+  `.code` plus typed `.data` fields.
+- Money/critical paths are transactional AND idempotent: a DB guard inside the transaction, not
+  just an `idempotencyKey` (delivery is at-least-once).
+
+```ts
+// bad - swallows the error, no context, no rethrow
+try {
+  await chargeWallet(tx, amount);
+} catch {
+  return null;
+}
+// good - a DB guard makes the mutation idempotent under at-least-once delivery
+await db.transaction(async (t) => {
+  if (await ledgerExists(t, idempotencyKey)) return;
+  await insertLedger(t, { idempotencyKey, amount });
+});
+```

package/template/docs/standards/frontend.md

@@ -0,0 +1,60 @@
+# Frontend conventions
+
+React/UI rules for this repo's `apps/*` UI apps and shared UI package. Read this before touching
+`apps/web/**`, `apps/backoffice/**`, or `packages/ui/**`. Not applicable if this repo is
+headless/api-only - delete this file and its row in `conventions`'s routing table in that case.
+
+## Component library and styling
+
+- React Compiler is ON. Never hand-write `useMemo`/`useCallback`/`React.memo` - a compiler bail is
+  a Rules-of-React violation to fix. Exception: your shared UI package is consumed pre-built, so
+  hand-write stability there when it's part of a hook's contract (same reason `@openora/core/react`
+  does).
+- Pick ONE component library and use its classes customized via utility classes + theme tokens.
+  Don't hand-roll what the library provides.
+- Never hand-write component CSS selectors (`.btn-*{}`, `.table th{}`). A per-app `styles.css`
+  holds only the theme plus custom properties for raw values with no token; every other style is
+  a utility class on the element.
+- App-specific looks live in that app's `styles.css`; shared UI components stay visually neutral.
+- No hardcoded user-facing copy - every label goes through `t()` with a key in the module's
+  `locales/`. Pattern: `locales/index.ts` exports `export const ns = registerTranslations('<module>',
+locales)`; components use `useTranslation(ns)`. Non-`en` files mirror `en.json` keys exactly.
+- Theme tokens and CSS variables are declared once in the shared UI package - style with semantic
+  tokens (`bg-base-100`, `text-base-content`, `btn-primary`), never inline raw hex. A design color
+  with no token: add it to BOTH dark and light theme blocks. A new token without a design source:
+  ask the user first.
+- Hoist long class strings into a module-scope `const styles = { ... } as const` keyed by role -
+  never inline long strings in JSX; merge with `cn()`.
+- Extract a repeated utility-class recipe into a shared component or constant on the third
+  occurrence.
+- Import helpers like `cn()` from the shared UI package barrel - never deep-import.
+- Server state is not client state - key/cache/invalidate via the query lib, never
+  `useEffect(fetch)`, never shadowed in ad-hoc caches.
+- No label or text is allowed to overflow its container - never leave text unconstrained by
+  default. Pick per element, based on whether the full text is load-bearing: `truncate` + a
+  `title` attribute holding the full string when a single line is the right shape and hiding the
+  tail is acceptable (a table cell, a narrow badge); `line-clamp-N` + a reserved `min-h-[NlH]` when
+  several lines are the right shape or the content differs in length across siblings that must
+  stay visually aligned (a KPI tile label, a card title) - the reserved height keeps every sibling
+  the same height whether or not its text actually wraps. A tooltip/popover with the full text is
+  the fallback only when neither fits the UX.
+
+## Modular architecture (every app)
+
+- Feature modules live in `src/modules/<m>/` with the same internal folders: `pages/`,
+  `components/`, `hooks/`, `utils/`, `locales/`, and a public barrel `index.ts`.
+- App-level (non-module) code splits the same way: `src/lib/` holds stateful/integration code
+  (API clients, SDK wrappers, config); `src/utils/` holds pure stateless helpers (formatters,
+  converters).
+- No cross-module imports, ever. Cross-module communication is query invalidation or a domain
+  event, never a direct import.
+- Outer composition code (`src/app/`, `src/routes/`, `extensions.config.ts`) imports modules only
+  through their barrel; deep-importing internals is forbidden. Files inside a module use relative
+  paths to siblings only, never `../../` out of the module.
+- Components in `components/` and `pages/` are presentation-only: props in, JSX out - no
+  fetching, no side effects. Business logic, queries, and mutations live in `hooks/`, which accept
+  external dependencies (oRPC calls, API clients) as parameters.
+- Next.js client components: `'use client'` on line 1 + `.client.tsx` suffix; server components
+  are the default (no marker). All-client apps (Vite/TanStack) use no suffix.
+- One concept per file, exported name matches the kebab-case filename; split hooks and components
+  into separate files.

package/template/docs/standards/functions.md

@@ -0,0 +1,38 @@
+# Functions and modules
+
+Read this before writing or refactoring a function, service method, or module.
+
+- Pure functions with dependencies passed in as arguments; side effects only at the edges
+  (services, adapters, plugins, handlers) - never in helpers.
+- Immutability: derive new objects (`{ ...user, roles: [...] }`), don't mutate.
+- Construct objects by spread + override, never field-by-field hand-copy. Keep fields explicit
+  only for order-sensitive serialization, when the target must not receive some source fields, or
+  when null-vs-undefined matters at a boundary.
+- A `class` is only a thin dependency-holding shell at a composition root; methods delegate to
+  pure functions. No inheritance for reuse, no decorators - compose.
+- Short, single-purpose functions - if you'd write `// step 2` inside one, extract it.
+- Guard clauses first, main path last.
+- More than 3 parameters -> a single named-object param.
+- Don't annotate a return type TypeScript can infer. Annotate only when: inference can't
+  (recursion), you deliberately widen/narrow, or it's the exported public API of a shared
+  `packages/*` module - there the explicit type IS the contract. Argument types always stay
+  explicit.
+- Named exports only - no default exports (exceptions: `*.config.*` files, `plugin.ts` whose
+  loader reads `mod.default`, and Next.js App Router files; lint-enforced).
+
+```ts
+// bad - the service reaches into a global/container to hide what it depends on
+export class WalletService {
+  constructor(private readonly container: Container) {}
+  async deposit() {
+    const psp = this.container.get(PAYMENT_ADAPTER);
+  }
+}
+// good - deps are constructor params of their port type
+export class WalletService {
+  constructor(
+    private readonly db: DrizzleService,
+    private readonly payments: PaymentAdapter,
+  ) {}
+}
+```

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,72 @@
+# 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` with `video-start` / `video-stop`, or a throwaway spec with
+   `test.use({ video: 'on' })` 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.
+2. Capture the evidence: one short video per acceptance criterion, ending on the outcome it names,
+   and the before/after pair when you fixed something. A screenshot only where a video adds
+   nothing, such as a second theme. 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]`.
+
+## 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

@@ -6,15 +6,21 @@
   "scripts": {
     "dev": "turbo run dev",
     "build": "turbo run build",
-    "typecheck": "turbo run typecheck",
-    "lint": "oxlint .",
-    "sync:agents": "rulesync generate",
-    "prepare": "rulesync generate",
-    "db:migrate": "pnpm -F @{{name}}/api db:migrate",
+    "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",
+    "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",

package/template/rulesync.jsonc

@@ -1,6 +1,6 @@
 // rulesync config - single source of truth for all AI-agent instruction files.
 // Source lives in .rulesync/ (rules, subagents, commands, mcp.json).
-// Regenerate with `pnpm sync:agents`; CI checks with `pnpm sync:agents:check`.
+// Regenerate with `pnpm gen:agents`.
 {
   "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
 

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);