ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/event-handler/wiring.tsyringe.tpl

@@ -0,0 +1,25 @@
+@@imports
+import { DomainEventDispatcher } from '@ddd-ts-kit/kernel';
+import { {{event.pascal}}EventHandler } from '{{alias.context}}/application/event-handlers/{{event.kebab}}.event-handler.js';
+import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+@@registrations
+builder.bind({{event.pascal}}EventHandler).toClass({{event.pascal}}EventHandler).as('domain-event-handler');
+@@start
+{{#if handler.afterCommit}}
+resolve(DomainEventDispatcher).on(
+  '{{event.name}}',
+  async (event) => {
+    if (event instanceof {{event.pascal}}) {
+      await resolve({{event.pascal}}EventHandler).handle(event);
+    }
+  },
+  { phase: 'after-commit' },
+);
+{{/if}}
+{{#unless handler.afterCommit}}
+resolve(DomainEventDispatcher).on('{{event.name}}', async (event) => {
+  if (event instanceof {{event.pascal}}) {
+    await resolve({{event.pascal}}EventHandler).handle(event);
+  }
+});
+{{/unless}}

package/templates/gateway/adapter.declared.ts.tpl

@@ -0,0 +1,11 @@
+import { Gateway } from '@ddd-ts-kit/kernel/declarations';
+import { {{name.pascal}}Contract } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+import { {{name.pascal}}Gateway } from '{{alias.context}}/application/ports/{{name.kebab}}-gateway.port.js';
+
+// TODO(platform): when {{upstream.kebab}} runs as its own service, turn this class into the remote adapter of {{name.pascal}}Gateway (an HTTP or RPC client with a timeout, retries and a fallback): the declaration stays, nothing else changes.
+@Gateway({{name.pascal}}Gateway, [{{name.pascal}}Contract])
+export class InProcess{{name.pascal}}Gateway implements {{name.pascal}}Gateway {
+  constructor(readonly upstream: {{name.pascal}}Contract) {}
+
+  // TODO(domain): implement each operation of {{name.pascal}}Gateway by asking `this.upstream`, translating its answer into the types of {{context.kebab}}.
+}

package/templates/gateway/adapter.ts.tpl

@@ -0,0 +1,9 @@
+import type { {{name.pascal}}Contract } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+import type { {{name.pascal}}Gateway } from '{{alias.context}}/application/ports/{{name.kebab}}-gateway.port.js';
+
+// TODO(platform): when {{upstream.kebab}} runs as its own service, write the remote adapter of {{name.pascal}}Gateway next to this one (an HTTP or RPC client with a timeout, retries and a fallback) and bind it instead; nothing else changes.
+export class InProcess{{name.pascal}}Gateway implements {{name.pascal}}Gateway {
+  constructor(readonly upstream: {{name.pascal}}Contract) {}
+
+  // TODO(domain): implement each operation of {{name.pascal}}Gateway by asking `this.upstream`, translating its answer into the types of {{context.kebab}}.
+}

package/templates/gateway/contract.spec.ts.tpl

@@ -0,0 +1,19 @@
+import { describe, expect, it } from '{{tests.module}}';
+import type { {{name.pascal}}Gateway } from '{{alias.context}}/application/ports/{{name.kebab}}-gateway.port.js';
+import { InProcess{{name.pascal}}Gateway } from '{{alias.context}}/infrastructure/external/in-process-{{name.kebab}}.gateway.js';
+import { Fake{{name.pascal}}Gateway } from '{{alias.context}}/test/fakes/{{name.kebab}}-gateway.fake.js';
+
+const ADAPTERS: readonly (readonly [string, () => {{name.pascal}}Gateway])[] = [
+  ['the fake', () => new Fake{{name.pascal}}Gateway()],
+  ['the in-process adapter', () => new InProcess{{name.pascal}}Gateway({})],
+];
+
+describe.each(ADAPTERS)('{{name.pascal}}Gateway, %s', (_name, create) => {
+  it('is an adapter of the port', () => {
+    expect(create()).toBeDefined();
+  });
+
+  // TODO(domain): replace each entry below by a behaviour every adapter of {{name.pascal}}Gateway must have, the remote one included: the same suite then holds them all.
+  it.todo('answers what {{upstream.kebab}} publishes, in the types of {{context.kebab}}');
+  it.todo('answers nothing, without failing, for an element {{upstream.kebab}} does not know');
+});

package/templates/gateway/contract.ts.tpl

@@ -0,0 +1,3 @@
+export abstract class {{name.pascal}}Contract {
+  // TODO(domain): declare what {{upstream.kebab}} answers to the contexts that ask as abstract methods, in its published terms and with serializable types only (for example `abstract priceOf(productId: string): Promise<{ amount: number; currency: string } | undefined>`); this is a contract: change it additively.
+}

package/templates/gateway/fake.ts.tpl

@@ -0,0 +1,5 @@
+import type { {{name.pascal}}Gateway } from '{{alias.context}}/application/ports/{{name.kebab}}-gateway.port.js';
+
+export class Fake{{name.pascal}}Gateway implements {{name.pascal}}Gateway {
+  // TODO(domain): implement each operation of {{name.pascal}}Gateway in memory, with what {{upstream.kebab}} would answer given by the test.
+}

package/templates/gateway/platform-test.declared.tpl

@@ -0,0 +1,4 @@
+@@imports
+import { {{name.pascal}}Contract } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+@@test-bindings
+builder.bind({{name.pascal}}Contract).toValue({});

package/templates/gateway/platform.declared.tpl

@@ -0,0 +1,4 @@
+@@imports
+import { {{name.pascal}}Contract } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+@@bindings
+builder.bind({{name.pascal}}Contract).toValue({});

package/templates/gateway/port.ts.tpl

@@ -0,0 +1,3 @@
+export abstract class {{name.pascal}}Gateway {
+  // TODO(domain): declare what {{context.kebab}} needs from {{upstream.kebab}} as abstract methods, in the words and types of {{context.kebab}}; the answer may come from another process tomorrow, so every operation is asynchronous and may fail.
+}

package/templates/gateway/wiring.tsyringe.tpl

@@ -0,0 +1,7 @@
+@@imports
+import { {{name.pascal}}Contract } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+import { {{name.pascal}}Gateway } from '{{alias.context}}/application/ports/{{name.kebab}}-gateway.port.js';
+import { InProcess{{name.pascal}}Gateway } from '{{alias.context}}/infrastructure/external/in-process-{{name.kebab}}.gateway.js';
+@@registrations
+builder.bind({{name.pascal}}Contract).toValue({});
+builder.bind({{name.pascal}}Gateway).toClass(InProcess{{name.pascal}}Gateway, [{{name.pascal}}Contract]).as('gateway');

package/templates/init/CLAUDE.md.tpl

@@ -0,0 +1,39 @@
+# {{project.name}}
+
+A ddd-ts-kit project: one bounded context per directory of `{{config.contextsDir}}/`, each described by its `CONTEXT.md`. The plan and what is next: `docs/architecture/plan.md`, when the project follows the method.
+
+## Commands
+
+- `npm run verify`: types, lint, format, tests with the coverage thresholds of `ddd-ts-kit.config.json` (per context and layer), architecture rules, import graph, dead code, documentation drift. Once, before a commit that closes a slice. A layer under its threshold gets the missing test, never an exclusion.
+- `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
+- `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
+- `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
+- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract and the event catalog.
+
+## Read less
+
+1. `describe <context> --json` and the `CONTEXT.md` of the context before the tree: do not browse `{{config.sourceRoot}}/` to learn what exists.
+2. Open only what the `next` list of a generator (`file:line`) or a violation names.
+3. `check --changed-since <ref>` and the tests of the context while iterating; `npm run verify` once at the end.
+
+## Rules by layer
+
+Loaded with the files they apply to, from `.claude/rules/`: `domain.md` (`domain/`, the shared kernel), `application.md`, `published-language.md`, `infrastructure.md`, `presentation.md` (and the OpenAPI contract), `platform.md` (`{{config.platformDir}}/`, `main.ts`, `apps/`{{#if style.explicit}}, module files{{/if}}), `tests.md` (specs, fakes, builders, `test/`).
+
+## Generated files
+
+Create every file of a role with `npx ddd-ts-kit generate <kind> ... --json`, then fill the `TODO(domain)` places it lists; never write one by hand, never restructure what a generator wrote.
+{{#if assembly.barrel}}
+Never edit `<context>.declarations.ts`: `generate` and `docs` rewrite it.
+{{/if}}
+Never edit `openapi/openapi.json`, `docs/integration/asyncapi.json`, `docs/integration/event-catalog.md`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`.
+Imports: a file of the project is imported by its alias from the project root, never by a relative path, the same directory included: `{{alias.source}}/...` for `{{config.sourceRoot}}/`, `{{alias.test}}/...` for `test/`, `{{alias.scripts}}/...` for `scripts/`, always ending in `.js` (`imports/alias-only`; `npm run lint:fix` rewrites a relative import). The alias is declared once, under `paths` in `tsconfig.json`, from `importAlias` of `ddd-ts-kit.config.json`: never add a second entry or mapping, and never compile without `npm run build`, which rewrites the aliases of `dist/` into relative paths for Node (`imports/alias-declared`).
+Everywhere: one exported class, interface or function per file, named after it in kebab-case; at most 350 lines a file, 30 lines and 3 parameters a function; `private` members, never `#name`; a blank line before a `return` and around `if`, `for`, `try` (`npm run lint:fix`); braces around the body of every `if`, `else`, `for`, `while` and `do`, on its own lines: a branch is visible at a glance, and a statement added to it later cannot silently fall outside it. `npm run format` (Biome, line width 120) lays out every file: do not spend tokens on line breaks.
+
+## TypeScript
+
+The compiler is the native TypeScript 7, installed as `@typescript/native`; `typescript` 6 is there for the tools that need its API (ESLint, dependency-cruiser). Use `npm run typecheck` and `npm run build`, never `npx tsc`, which would run version 6.
+
+## Workflow
+
+With the ddd-ts-kit plugin: `/ddd-ts-kit:start` for a new project or to resume one, `/ddd-ts-kit:glossary` before a new name, `/ddd-ts-kit:use-case` for a feature, `/ddd-ts-kit:document` for the contracts, `/ddd-ts-kit:quality-gate` before a pull or merge request.

package/templates/init/README.md.tpl

@@ -0,0 +1,263 @@
+# {{project.name}}
+
+Domain-Driven Design and Clean Architecture on [ddd-ts-kit](https://www.npmjs.com/package/ddd-ts-kit).
+The rules are in `CLAUDE.md` and `.claude/rules/`; `npx ddd-ts-kit explain <rule-id>` explains each one.
+
+## Run it
+
+```bash
+npm install
+npm run verify          # every gate of the pipeline: green before the first line of business code
+cp .env.example .env
+{{#if database.server}}
+npm run infra:up        # the database, in Docker; add --profile observability for Jaeger
+{{/if}}
+{{#if orm.drizzle}}
+npm run db:generate     # SQL migrations from the Drizzle schema
+npm run db:migrate
+{{/if}}
+{{#if orm.knex}}
+npm run db:migrate      # builds, then applies migrations/ (the first one creates every table)
+{{/if}}
+{{#if orm.prisma}}
+npm run db:client       # the Prisma client and the schema of the tests, from prisma/schema.prisma
+npm run db:generate     # a migration from the schema
+npm run db:migrate
+{{/if}}
+{{#if orm.typeorm}}
+npm run build && npm run db:generate   # a migration from the entity schemas
+npm run db:migrate
+{{/if}}
+npm run dev
+```
+
+`npm run dev` restarts the application when a source file changes. It runs `tsx watch`, which
+executes TypeScript directly and resolves an import alias from the `paths` of `tsconfig.json`;
+`--env-file-if-exists=.env` gives Node the variables of `.env`
+when the file is there, and `--import` loads `{{config.platformDir}}/tracing.ts` before
+everything else so that instrumentation is installed first.
+`{{config.platformDir}}/config/load-config.ts` validates the variables and refuses to start when
+one is wrong.
+{{#if docs.any}}
+
+The API documentation is served at `/docs` and the contract at `/openapi.json`, outside
+production unless `API_DOCS=true`.
+{{/if}}
+
+## How it is put together
+
+{{#if errors.none}}
+`{{config.sourceRoot}}/main.ts` is the composition root: tracing first, then the validated
+configuration, the storage, and `composeApplication` of `{{config.platformDir}}/compose-application.ts`.
+{{/if}}
+{{#if errors.sentry}}
+`{{config.sourceRoot}}/main.ts` is the composition root: tracing first, error reporting second
+(`{{config.platformDir}}/errors.ts`), then the validated configuration, the storage, and
+`composeApplication` of `{{config.platformDir}}/compose-application.ts`.
+{{/if}}
+
+- **A port is an abstract class, and the class is what is injected.** A repository port lives in
+  `domain/repositories/`, any other port in `application/ports/`, one per file; an adapter
+  `implements` its port. There is no token constant and no token file anywhere: a dependency list
+  names port classes (`[InvoiceRepository, Clock]`), the ports of the kernel included (`Clock`,
+  `IdGenerator`, `CommandBus`, `UnitOfWork`... of `@ddd-ts-kit/kernel`).
+{{#if di.tsyringe}}
+- **Three modules, then the contexts.** `kernelModule({...})` binds the ports of the kernel to what
+  this platform chose (one execution scope, one clock, the two buses with their middlewares);
+  `platformModule` (`{{config.platformDir}}/platform.module.ts`) rebinds what needs the storage{{#if broker.external}}, the broker{{/if}}{{#if cache.redis}} or the Redis protocol server{{/if}}
+  (`builder.rebind(UnitOfWork)`, `builder.bind({{persistence.tokenOrNone}})`...); the authorization
+  module binds the guard both buses ask first. Replacing a provider happens in the platform module
+  and nowhere else.
+{{/if}}
+{{#unless di.tsyringe}}
+- **One `Platform`, handed to each context.** `createPlatform` (`{{config.platformDir}}/create-platform.ts`)
+  builds the buses, the clock, the storage and the event ports once; the module file of a context
+  receives it and registers its handlers, adapters and jobs on it. Replacing a provider happens
+  there and nowhere else.
+{{/unless}}
+{{#if style.declared}}
+- **A context declares itself.** Each class says what it is with a decorator of
+  `@ddd-ts-kit/kernel/declarations` and is its own registration{{#if assembly.barrel}}; the composition root reads the
+  generated barrel `<context>.declarations.ts`{{/if}}{{#if assembly.discovery}}; the composition root discovers the role files of
+  each context at startup (`discoverContext`), publishers and jobs included{{/if}}.
+{{/if}}
+{{#if broker.external}}
+- **Behind the broker each context listens under its own name**: the platform module rebinds
+  `EventSubscribers` to `{ forContext: (name) => bus.forConsumer(name) }`, so a context keeps its
+  queues when it is extracted (`npx ddd-ts-kit generate service <context>`).
+{{/if}}
+- **Domain events leave with the save.** A handler writes `await repository.save(aggregate)` and
+  returns: the events the aggregates recorded wait for the end of the unit of work of the command
+  and are dispatched there, before the commit, so their handlers see every save and what they
+  write, the outbox included, commits or rolls back with it. An effect of a domain event exists
+  only if the state change that recorded it is committed: a reaction outside the database is
+  declared in the `after-commit` phase (at most once) or goes through an integration event.
+- **Cross-cutting behaviour stays outside the contexts**: one action is one trace (the request,
+  the use case, each repository or outbound call, the domain events and their handlers, the
+  outbox append, then the publication and each consumer), put around the application by
+  `traceApplication()` of `@ddd-ts-kit/tracing`, `tracedRoutes()` at the HTTP boundary and
+  `tracedPublisher` for the relay; what leaves the process gets retries and a time limit
+  (`{{config.platformDir}}/resilience/`), inside the span of the call.
+
+## Observability
+
+| Variable | Says |
+|---|---|
+| `LOG_LEVEL` | `debug`, `info`, `warn` or `error` |
+{{#if logger.stdout}}
+| `LOG_FORMAT` | `json` only: the logger writes JSON lines on the standard output and has no pretty format (`init --logger pino` or `--logger winston` brings one, and redacts credentials) |
+{{/if}}
+{{#unless logger.stdout}}
+| `LOG_FORMAT` | `json` (the default, everywhere) or `pretty` (a developer's terminal) |
+{{/unless}}
+| `LOG_SCRUB_MESSAGES` | `true` writes `[message removed]` for the message of every logged error that is not a `DomainError` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | where spans go; left out, none leaves the process. `docker compose --profile observability up -d jaeger`, then `http://127.0.0.1:4318`, and the traces are on `http://127.0.0.1:16686` |
+| `TRACE_SAMPLE_RATIO` | the share of traces kept, 0 to 1; left out, every trace |
+| `TRACE_CONSUMERS` | `continue` (the default): a consumed event stays in the trace of the request that published it; `link`: each delivery starts a trace linked to it |
+
+Every log line carries the correlation id, the origin, the actor and the ids of the active trace
+(`{{config.platformDir}}/observability/create-logger.ts`). Stopping the application flushes the
+error reporter, then the logger, last: whatever logs has closed before.
+
+## Scheduled jobs
+
+`npx ddd-ts-kit generate job <context> <Name> --every 15m --command <UseCase>` writes a job in
+`application/scheduling/`: it sends one command, as the system actor `system:<context>.<name>`,
+and `execution.scheduledAt` says which period the work is for.
+
+| Variable | Says |
+|---|---|
+| `RUN_JOBS` | whether this process runs the jobs by time ({{#if worker.off}}`true` by default{{/if}}{{#if worker.on}}`false` by default: the worker runs them{{/if}}) |
+| `JOB_<CONTEXT>_<JOB>_ENABLED` | `false` switches one job off in one environment (`{{config.platformDir}}/job-settings.ts`, where a schedule or a timeout can be read from the environment too) |
+
+- **A dedicated worker**: `npx ddd-ts-kit generate worker` writes `{{config.sourceRoot}}/apps/worker/main.ts`
+  (the same modules as `main.ts`, no HTTP server, the jobs started whatever `RUN_JOBS` says), the
+  script `npm run start:worker` and a compose service, and makes `RUN_JOBS` default to `false`
+  for the API.{{#if events.outbox}} The worker runs no outbox relay: the events its commands store are relayed by the API.{{/if}}
+- **A context extracted as a service** (`generate service <context>`) takes its jobs with it.
+{{#if cache.redis}}
+- **Several instances**: the kernel `Lock` is bound to `RedisLock`, so one occurrence of a job
+  runs on one instance, best effort: it may still run twice or not at all (a paused holder, a
+  failover), which is why a job, or the command it sends, is idempotent.
+{{/if}}
+{{#unless cache.redis}}
+- **Limitation: one instance runs the jobs.** The kernel `Lock` is the in-memory one, which
+  excludes inside one process only: two instances started with their jobs on both run every
+  job. Run the jobs in a single process (one API instance, or one worker with `RUN_JOBS=false`
+  on the API), or initialise the project with `--cache redis`, which binds `RedisLock`, or bind a
+  lock between processes of your own to `Lock` in the platform.
+{{/unless}}
+{{#if errors.sentry}}
+
+## Error reporting
+
+Unexpected failures go to an error tracker through the kernel `ErrorReporter`, bound to
+`@ddd-ts-kit/sentry`: Sentry or GlitchTip, which speak the same protocol, so only the DSN differs.
+`{{config.platformDir}}/errors.ts` starts it, second import of every entry point, and nothing in
+`domain/` or `application/` reports anything: a handler throws, and what stands around it reports.
+
+| Variable | Says |
+|---|---|
+| `SENTRY_DSN` | where the events go. Empty or absent: the application starts and reports nothing. Anything else than a URL refuses the start |
+| `SENTRY_ENVIRONMENT` | the environment issues are filed under; `NODE_ENV` when left out |
+| `SENTRY_RELEASE` | the release issues are attached to; none when left out |
+| `SENTRY_SCRUB_MESSAGES` | `true` removes the message of every reported error that is not a `DomainError`: for a tracker hosted by a third party |
+
+| Reported | Not reported |
+|---|---|
+| a command or a query that fails with anything but a `DomainError` | a `DomainError`: a business refusal is an answer, not an incident |
+{{#if http.any}}
+| a request answered 5xx | a 4xx |
+{{/if}}
+| a scheduled run that failed, a timeout included | a skipped or missed occurrence |
+{{#if errors.broker}}
+| an integration event given up: retries exhausted, poison message{{#if events.outbox}}, publication of the outbox relay declared dead{{/if}} | a delivery that fails and is retried |
+{{/if}}
+{{#unless errors.broker}}
+{{#if events.outbox}}
+| an integration event whose publication the outbox relay declares dead | a publication that fails and is retried |
+{{/if}}
+{{/unless}}
+| `uncaughtException` and `unhandledRejection`, as `fatal`, before the process exits with code 1 | |
+
+One failure is one report: the first boundary that sees an error reports it, the others recognise
+it. Each report carries the trace id of the active span, which opens the trace in the tracing
+backend. What leaves the process is scrubbed first: no request body, header, cookie or query
+string, no local variable, no breadcrumb, no email or name (the actor id only), no tenant. The
+message of the error is sent: `scrubMessages: true` in `{{config.platformDir}}/errors.ts` removes
+it for everything that is not a `DomainError`, which is the setting for a tracker hosted by a
+third party. The README of `@ddd-ts-kit/sentry` has the full table and the other options
+(`sampleRate`, `tagTenant`, `beforeSend`).
+
+Stopping the application flushes the reporter, two seconds at most. The tools and the tests
+compose the application without a reporter: nothing is reported there.
+
+### A local GlitchTip
+
+```bash
+docker compose --profile errors up -d --wait    # GlitchTip 6, its PostgreSQL and its Valkey; the first start migrates, allow a few minutes
+docker compose logs glitchtip | grep 'DSN:'     # the DSN of the project it created
+```
+
+Put that DSN in `SENTRY_DSN` of `.env` (`http://<public-key>@localhost:8000/1`) and restart the
+application; from another container of the compose file, replace `localhost` with `glitchtip`.
+Sign in at http://localhost:8000 with `test@example.com` / `admin_pass`. `GLITCHTIP_PORT` moves
+the port, and the DSN the logs print then names it. This instance is for local development only:
+its secret key, its `DEBUG` mode and its account are public.
+{{/if}}
+
+## Tooling
+
+The compiler is the native TypeScript 7, installed under the alias `@typescript/native` and
+called by its path in `npm run typecheck` and `npm run build`. `typescript` 6 is installed next
+to it because ESLint and dependency-cruiser read sources through the compiler API, which the
+native version does not ship: do not use `npx tsc`, it would run version 6.
+
+Every file of the project is imported by an alias from the project root, never by a relative
+path: `{{alias.platform}}/config/load-config.js` for `{{config.platformDir}}/config/load-config.ts`,
+`{{alias.test}}/...` for `test/`, `{{alias.scripts}}/...` for `scripts/`. The alias is declared
+once, under `paths` in `tsconfig.json`, which the compiler, `npm run dev`, the tests, knip and
+the import graph read. Node reads no alias: `npm run build` compiles, then
+`ddd-ts-kit build-aliases` rewrites each alias of `dist/` into a relative path, so `npm start`
+is plain `node`. `npm run lint:fix` turns a relative import into its alias, and
+`npm run check:arch` reports a declaration that no longer follows `importAlias` of
+`ddd-ts-kit.config.json`, or a build that skips the rewrite (`imports/alias-only`,
+`imports/alias-declared`).
+
+| Gate | Script | Tool |
+|---|---|---|
+| types | `npm run typecheck` | TypeScript 7 |
+| code rules | `npm run lint` | ESLint with `@ddd-ts-kit/eslint-plugin` |
+| structure | `npm run check:arch` | `ddd-ts-kit check` |
+| import graph | `npm run depcruise` | dependency-cruiser, on `.dependency-cruiser.cjs` (generated from `ddd-ts-kit.config.json`) |
+| dead code | `npm run deadcode` | knip |
+| drift | `npm run docs:check` | context map, OpenAPI, AsyncAPI, event catalog |
+
+`npm run verify` chains them with the tests. Git hooks: `npm run hooks:install` once per clone
+(lefthook: lint and architecture on staged files, conventional commit messages).
+{{#if ci.any}}
+The pipeline calls the same `ci:*` scripts; what makes it binding is described in
+{{#if ci.github}}
+`.github/branch-protection.md`{{/if}}{{#if ci.gitlab}} `.gitlab/merge-request-settings.md`{{/if}}.
+{{/if}}
+
+`ddd-ts-kit.config.json` also takes `"guard": "enforce" | "advise" | "off"` (default `enforce`):
+how the editor hook of the ddd-ts-kit plugin reacts when a file just written breaks a rule
+(refuse it, only say so, or stay silent).
+
+## Work on it
+
+1. Define the vocabulary in the `CONTEXT.md` of the context, with the domain experts.
+2. Model: aggregates, value objects, events, in the words of that glossary.
+3. Scaffold with `npx ddd-ts-kit generate ...` (`command`, `query`, `repository`, `port`, `route`, `job`...) and fill the `TODO(domain)` places it lists.
+4. Test: builders and fakes, no mocks. `npm test`, then `npm run test:e2e`.
+5. Verify: `npm run verify`.
+
+| Script | Does |
+|---|---|
+| `npm run dev` | the application with auto reload |
+| `npm test` | domain, application and adapter specs |
+| `npm run test:e2e` | the whole application through HTTP, on an in-process database unless `DATABASE_URL` is set |
+| `npm run check:arch` | `ddd-ts-kit check` |
+| `npm run docs:generate` | context map, OpenAPI, AsyncAPI and event catalog |
+| `npm run verify` | everything CI runs |

package/templates/init/docker/Dockerfile.tpl

@@ -0,0 +1,33 @@
+# syntax=docker/dockerfile:1
+
+FROM node:24-slim AS build
+WORKDIR /app
+{{#if pm.corepack}}
+# corepack provides the release of the package manager that package.json pins.
+RUN corepack enable
+{{/if}}
+COPY package.json package-lock.json{{#if pm.pnpm}} pnpm-workspace.yaml{{/if}} ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:24-slim AS dependencies
+WORKDIR /app
+{{#if pm.corepack}}
+RUN corepack enable
+{{/if}}
+COPY package.json package-lock.json{{#if pm.pnpm}} pnpm-workspace.yaml{{/if}} ./
+RUN npm ci --omit=dev
+
+FROM node:24-slim
+# The entry point: the whole application, or one context run alone (--build-arg ENTRY=dist/{{config.sourceRoot}}/apps/<context>/main.js).
+ARG ENTRY=dist/{{config.sourceRoot}}/main.js
+ENV NODE_ENV=production
+ENV ENTRY=${ENTRY}
+WORKDIR /app
+COPY --from=dependencies /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY package.json ./
+USER node
+EXPOSE 3000
+CMD ["sh", "-c", "exec node $ENTRY"]