ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/init/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# No dependency runs a build script at install, as under npm: one whose script the
+# project needs (a native client, for instance) is allowed by name, once its script was read:
+#
+#   allowBuilds:
+#     '<package>': true
+#
+# Without this line pnpm refuses to install as long as one script is neither allowed nor refused.
+strictDepBuilds: false

package/templates/init/rules/application.md.tpl

@@ -0,0 +1,25 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/application/**"
+---
+
+# Application layer
+
+- Imports `domain/`, `application/`, published languages, `@ddd-ts-kit/kernel` and `@ddd-ts-kit/auth` only (`layer/application-inward`): never `infrastructure/`, `presentation/`, a framework or a driver.
+- One use case per folder, `commands/<use-case>/` or `queries/<use-case>/`: the message, its handler, a `*.result.ts` when the answer has a shape of its own. The handler has one public method, `execute` (`application/handler-shape`): it loads or builds, calls ONE intention method, `await repository.save(aggregate)`, and returns at most an identifier.
+- Events leave with the save: never `pullEvents()`, never a `DomainEventDispatcher` here (`domain-events/dispatched-on-save`). A reaction is a class of `event-handlers/` or a publisher of `integration/publishers/`. It runs at the end of the unit of work, before the commit, and depends only on what the transaction covers (`domain-events/transactional-before-commit`): repositories, the integration event publisher, the command bus. An effect outside the database is a handler of the `after-commit` phase (`generate event-handler ... --phase after-commit`: at most once, never saves, sends a command) or, when it must not be lost, the handler of an integration event.
+{{#if style.declared}}
+- Every command and query carries `@Requires(permission)` or `@Public()` (`authz/declared`), and the actor is in the message (`authz/actor-explicit`). Permissions live in `authorization/<context>.permissions.ts`, rules that need loaded state in `authorization/*.policy.ts`.
+- The decorator is the registration (`declarations/role-declared`): `@CommandHandler(Message, [Ports])`, `@QueryHandler`, `@DomainEventHandler(Event, { name }, [Ports])`, `@IntegrationEventHandler(definition, { consumer }, [Ports])`, `@Scheduled('<context>.<job>', schedule, [CommandBus])`, `@Policy(permission, { name })`. Names are string literals.
+{{/if}}
+{{#if style.explicit}}
+- Every command and query is registered in `<context>.module.ts` with the permission it requires, or as public (`authz/declared`), and the actor is in the message (`authz/actor-explicit`). Permissions live in `authorization/<context>.permissions.ts`, rules that need loaded state in `authorization/*.policy.ts`.
+- A class here carries no registration of its own: `<context>.module.ts` binds it. A job is registered as `@Scheduled('<context>.<job>', schedule, [CommandBus])` would say: one name, one schedule, the command bus.
+{{/if}}
+- A port is an abstract class in `ports/<name>.port.ts` and its own injection token (`ports/abstract-class`, `ports/no-token-constant`), named for the need (`PaymentGateway`), with a fake in `test/fakes/`.
+- A dependency list names port classes, imported as values, in the order of the constructor: never an adapter or a fake (`ports/value-import`, `ports/no-concrete-dependency`).
+- A job (`scheduling/*.job.ts`) and an integration event handler (`integration/handlers/`) only build one command and send it as a system actor; both are safe to repeat (`scheduling/job-triggers-use-case`, `events/consumer-idempotent`).
+- A query never saves, deletes or publishes (`application/command-query-separation`); it hands the access scope of the actor to its read port and never filters after loading.
+- A read that takes criteria, a scope or a page is a search, never a list (`naming/search-not-list`): `Search<Things>Query` in `queries/search-<things>/` (`generate query ... --search`), `search...` on the port, its adapters and its fakes; one element or none stays `findById` or `findBy...`.
+- Time through `Clock`, identifiers through `IdGenerator`, no `process.env` (`purity/*`). No logging, tracing, retry or audit call: they are applied from outside (`aspects/outside-in`, `tracing/platform-only`).
+- A whole feature with `/ddd-ts-kit:use-case`. Create with `npx ddd-ts-kit generate command|query|port|policy|job|event-handler|integration-handler ... --json`, then fill the `TODO(domain)` places.

package/templates/init/rules/domain.md.tpl

@@ -0,0 +1,18 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/domain/**"
+  - "{{config.sharedKernelDir}}/**"
+---
+
+# Domain layer
+
+- Imports only its own `domain/`, the shared kernel and `@ddd-ts-kit/kernel` (`layer/domain-purity`): no framework, no decorator, no validation library, no `node:` module.
+- Names come from the glossary of `CONTEXT.md`, written first (`language/glossary-term`); no `Manager`, `Helper`, `Data`, `Info`, `Model` (`language/no-technical-name`).
+- Aggregate: private constructor, `create` for birth, `rehydrate` for loading, state changed by methods named after the business intention, no setter, no public mutable property (`domain/aggregate-encapsulation`). One aggregate per transaction; another one is referenced by its id.
+- Value objects are immutable, validated in `create`, compared with `equals` (`domain/value-object-immutability`). An email, an amount, a period are types, not strings.
+- A violated invariant throws a `DomainError` of `domain/errors/` with a stable `code`, never a bare `Error` (`domain/no-generic-error`).
+- Domain events are named in the past tense, `<context>.<aggregate>.<fact>` (`events/name-format`), and recorded by the aggregate (`this.record(...)`). They leave with the save: nothing here dispatches them.
+- A repository here is a port: an abstract class extending the kernel `Repository<Aggregate>`, abstract members only (`ports/abstract-class`). A domain service is stateless.
+- Time and identifiers come in as parameters (`purity/*`); nothing here knows the acting user or its rights (`authz/in-application`).
+- One concept per file, with the suffix of its role: `.aggregate.ts`, `.entity.ts`, `.vo.ts`, `.event.ts`, `.error.ts`, `.repository.ts`, `.service.ts` (`naming/suffix`, `naming/one-concept-per-file`).
+- The language first, with `/ddd-ts-kit:glossary`. Then create with `npx ddd-ts-kit generate aggregate|entity|value-object|domain-event|domain-error|domain-service|repository ... --json` and fill the `TODO(domain)` places it lists.

package/templates/init/rules/infrastructure.md.tpl

@@ -0,0 +1,24 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/infrastructure/**"
+---
+
+# Infrastructure layer
+
+- An adapter `implements` a port of `application/ports/` or a repository port of `domain/repositories/`, and never `extends` it (`ports/implements-never-extends`). It never imports `presentation/` (`layer/infrastructure-no-presentation`).
+- `persistence/` holds repository adapters, mappers and rows, `external/` the adapters of outside systems, `anti-corruption/` the translators of another model.
+- Rows never leave `persistence/`: a mapper translates to and from the aggregate, and is the only place for a type assertion (`clean/no-escape-hatch`).
+- Own tables, in the schema of the context: no join, foreign key or transaction across contexts (`context/extractable`).
+- Audit columns and the tenant column are stamped from the execution scope with the kernel helpers (`stampCreation`, `stampUpdate`, `tenantScopeOf`), never handed over by a use case.
+{{#if style.declared}}
+- An adapter declares itself on its class, one per file (`declarations/role-declared`): `@Repository(InvoiceRepository, [{{persistence.tokenOrNone}}, ExecutionScope, Clock])`, `@Gateway(Port, [Ports])` or `@Adapter(Port, { kind }, [Ports])`.
+- Retry, timeout and cache go on the declaration (`aspects: [ownPolicy(retry(...), timeout(...))]`) or, when the policy is part of what the adapter is, as decorators of `@ddd-ts-kit/aspects/decorators` (`aspects/outside-in`). Kinds `external` and `gateway` get the default policy of the platform otherwise. `ownPolicy` is the helper of `{{alias.platform}}/resilience/own-policy.js`, which `generate adapter` writes when the platform does not have it yet.
+{{/if}}
+{{#if style.explicit}}
+- An adapter is bound to its port in `<context>.module.ts` only (`composition/only-in-module`), with its kind (`repository`, `gateway`, `external`).
+- Retry, timeout and cache go on the binding (`ownPolicy(retry(...), timeout(...))`) or, when the policy is part of what the adapter is, as decorators of `@ddd-ts-kit/aspects/decorators` (`aspects/outside-in`). Kinds `external` and `gateway` get the default policy of the platform otherwise. `ownPolicy` is the helper of `{{alias.platform}}/resilience/own-policy.js`, which `generate adapter` writes when the platform does not have it yet.
+{{/if}}
+- A repository only persists: no `pullEvents()`, no dispatcher (`domain-events/dispatched-on-save`). A removal that announces an event takes the aggregate, not its id.
+- Infrastructure faults are plain errors (a 5xx, reported from outside); business refusals are `DomainError`s raised by the domain.
+- Every adapter passes the contract suite of the fake of its port (`test/integration/*.contract.spec.ts`).
+- Method: `/ddd-ts-kit:persistence`. Create with `npx ddd-ts-kit generate repository|adapter|gateway|acl ... --json`.

package/templates/init/rules/platform.md.tpl

@@ -0,0 +1,31 @@
+---
+paths:
+  - "{{config.platformDir}}/**"
+  - "{{config.sourceRoot}}/main.ts"
+  - "{{config.sourceRoot}}/apps/**"
+{{#if style.explicit}}
+  - "{{config.contextsDir}}/*/*.module.ts"
+{{/if}}
+---
+
+# Platform and composition root
+
+- `main.ts`, and each `apps/*/main.ts`, imports `platform/tracing.ts` first{{#if errors.sentry}}, `platform/errors.ts` second{{/if}}, then composes the application: nothing else belongs in an entry point.
+- Contexts, routes and registries are added by the generator between `// ddd-ts-kit:` markers: never edit between them, never remove one.
+{{#if di.tsyringe}}
+- Ports and values are bound by class: `bind(Port).toClass(...)`, `toValue(...)`, or `rebind(Port)` over a default of the kernel module. No token helper, no injection constant; one exported class, interface or function per file.
+- Cross-cutting behaviour lives here: spans through `kernelModule({ instrumentation })` (`lay-foundations.ts`), `around: tracedRoutes()` at the HTTP boundary and `tracedPublisher` for the outbox relay; logs, measures, permissions and audit as bus middlewares (`buses/`); the policy of outbound adapters in `resilience/`.
+{{/if}}
+{{#unless di.tsyringe}}
+- One `Platform` is built in `create-platform.ts` and handed to each context; a port or a value is typed by an abstract class. No token helper, no injection constant; one exported class, interface or function per file.
+- Cross-cutting behaviour lives here: spans through the members of `traceApplication()` (`create-platform.ts`), `around: tracedRoutes()` at the HTTP boundary and `tracedPublisher` for the outbox relay; logs, measures, permissions and audit as bus middlewares; the policy of outbound adapters in `resilience/`.
+{{/unless}}
+- `@ddd-ts-kit/tracing` and `@opentelemetry/*` are imported here and nowhere else (`tracing/platform-only`).
+- Logs, spans and error reports carry identifiers and codes only: never arguments, payloads, error messages, nor anything personal beyond the id of the actor.
+- Configuration is read here only, by `config/load-config.ts`: validated, fail fast, every problem named by its variable. A new variable joins `AppConfig` and `.env.example`. `RUN_JOBS` says whether a process runs the jobs, `job-settings.ts` what configuration changes of each.
+- Stopping: the HTTP server, the relay, then `application.stop()`, which ends with the error reporter and, last, the logger; connections and tracing after it. Whatever logs closes before the logger.
+{{#if style.explicit}}
+- `<context>.module.ts` is the only place a context binds its adapters and registers its handlers (`composition/only-in-module`); the generator writes between its markers.
+{{/if}}
+- A change here is shared by every context: it goes in its own commit (`chore(platform): ...`), on the trunk, never inside a slice.
+- Method: `/ddd-ts-kit:wiring` and `/ddd-ts-kit:cross-cutting`. A process for the jobs: `npx ddd-ts-kit generate worker`; a context alone: `npx ddd-ts-kit generate service <context>`.

package/templates/init/rules/presentation.md.tpl

@@ -0,0 +1,19 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/presentation/**"
+  - "openapi/**"
+  - "scripts/openapi.ts"
+---
+
+# Presentation layer
+
+- A route validates the shape of the input, builds a command or a query with the actor, executes it through `CommandBus` or `QueryBus` (never a handler class) and maps the answer. Nothing else.
+- Imports `application/` (and domain types for mapping), never `infrastructure/` (`layer/presentation-no-infrastructure`).
+- Input shape is validated here with the schema library of the project, behind the `Schema` port. Business rules are not validated here.
+- Every route declares its `security`, or `security: false`, and the `DomainError` codes it can answer in `errors`; the mapping from code to status lives in one place, the error mapper.
+- No role or ownership test here (`authz/in-application`): the bus asks for the permission, a policy decides on loaded state.
+- Request and response types are presentation types (`*.dto.ts`): never an aggregate, never a row.
+- Never put the message of an unexpected failure in a response or a log.
+- Files: `*.route.ts` (or `*.controller.ts`) and `*.dto.ts` in `presentation/http/` (`naming/suffix`).
+- After a change, `npm run docs:generate` regenerates `openapi/openapi.json`, committed with the route; CI fails on a difference. Never edit it by hand.
+- Contract with `/ddd-ts-kit:document`. Create with `npx ddd-ts-kit generate route <context> <UseCase> --method <M> --path <p> --json`, then `generate e2e <context> <UseCase>`.

package/templates/init/rules/published-language.md.tpl

@@ -0,0 +1,15 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/published-language/**"
+---
+
+# Published language
+
+- The only folder another context may import (`context/published-language-only`), and only once the relationship is declared in `ddd-ts-kit.config.json` (`context/declared-relationship`): declare first, import after.
+- Imports only `@ddd-ts-kit/kernel`, `@ddd-ts-kit/events`, the schema library and other published languages (`context/published-language-is-a-contract`).
+- One `defineIntegrationEvent({ type, version, payload })` per event and version, in `<aggregate>-<fact>.v<n>.integration-event.ts`, its payload next to it (`events/defined-in-published-language`). `index.ts` only re-exports.
+- A payload holds identifiers and facts as primitives: never an aggregate, never what other contexts must not depend on.
+- Additive inside a version: a field is added, never renamed or removed. Anything else is a new version (`--version <n+1>`), published next to the previous one until every consumer moved.
+- The read contract of a gateway (`*.contract.ts`) lives here too: what a downstream may ask synchronously, as plain data.
+- A change here is a contract change: committed on its own, before the consumers build on it, with the regenerated event catalog and AsyncAPI document (`npm run docs:generate`).
+- Method: `/ddd-ts-kit:integration-event`. Create with `npx ddd-ts-kit generate integration-event <context> <Aggregate> <Fact> [--version <n>] --json`, or `generate gateway <context> <upstream> <Name>`.

package/templates/init/rules/tests.md.tpl

@@ -0,0 +1,27 @@
+---
+paths:
+  - "{{config.contextsDir}}/*/test/**"
+  - "**/*.spec.ts"
+  - "test/**"
+---
+
+# Tests
+
+- `test/unit/`: aggregates, value objects and domain services without any double, given / when / then on the recorded facts; handlers with the fakes of `test/fakes/`.
+{{#if di.tsyringe}}
+- A handler spec goes through the test application, `createTestApplication({ modules, fakes: [fake(Port, aFake)] })`: it asserts the stored state, the facts announced with the save and heard at the end of the command (`application.domainEvents`), `application.eventBus.published`, and the refusal (`FORBIDDEN`) of an actor without the permission.
+- A job spec runs the job by its name, `await application.jobs.runNow('<context>.<job>')`, and asserts the command it sent as its system actor.
+{{/if}}
+{{#unless di.tsyringe}}
+- A handler spec goes through the buses of `createTestBuses()`, the fake repository wrapped by `dispatching(...)`: it asserts the stored state, the facts announced with the save and heard at the end of the command (`domainEvents`), `publishedEvents()`, and the refusal (`FORBIDDEN`) of an actor without the permission.
+- A job spec runs the job with an occurrence, `await job.run(occurrence)`, and asserts the command it sent as its system actor.
+{{/unless}}
+- `test/integration/`: adapters against the real dependency, and the contract suites every adapter and fake of a port must pass.
+- A fake is a working in-memory implementation, not a mock with expectations: no `vi.mock`, `vi.fn`, `vi.spyOn` (`test/no-mocks`). Test data comes from the builders of `test/builders/`.
+- Name tests after the behaviour, in the words of the business: "refuses to issue an invoice without lines", not "should throw". Arrange, act, assert, separated by a blank line; one behaviour per test.
+- Every aggregate, value object, domain service, handler, event handler and integration event handler has a spec named after its file (`test/spec-required`).
+- Coverage is a floor per context and layer, read from `coverage` in `ddd-ts-kit.config.json` and held by `npm run verify` (`npm run test:coverage`): a layer under its threshold gets the test that is missing. No `exclude` in the runner config, no `v8 ignore` or `istanbul ignore` comment without `-- ADR-NNNN: <reason>` (`test/coverage-governed`); a rate proves that code ran, never that a test asserts anything.
+- An `it.todo` left by the generator names a behaviour still to prove: replace it by a real test, do not delete it. `npx ddd-ts-kit todo <context>` lists what remains.
+- A test never asserts on a private field; it observes results, recorded events and what the fakes received.
+- `test/e2e/` (project root) drives the whole application through HTTP with generated, seeded data, never reads the database, and asserts the trace of a request with `expectSpanTree(storyOf(trace), [...])`.
+- Write tests with `/ddd-ts-kit:testing`; scaffold with `npx ddd-ts-kit generate builder|e2e`.

package/templates/init/scripts/events.ts.tpl

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createEventRegistry, generateEventCatalog, type AnyIntegrationEventDefinition } from '@ddd-ts-kit/events';
+import { generateAsyncApi, stringifyAsyncApi } from '@ddd-ts-kit/events/asyncapi';
+
+// Generates docs/integration/asyncapi.json and docs/integration/event-catalog.md from the
+// declarations of every published language; with --check, fails when a committed file
+// differs. Both files are build products: never edit them by hand.
+const contextsDirectory = '{{config.contextsDir}}';
+const target = path.resolve('docs/integration');
+
+const registry = createEventRegistry(await declaredEvents());
+
+const generated: Readonly<Record<string, string>> = {
+  'asyncapi.json': stringifyAsyncApi(
+    generateAsyncApi({
+      info: {
+        title: manifestField('name', '{{project.name}}'),
+        version: manifestField('version', '0.0.0'),
+      },
+      registry,
+    }),
+  ),
+  'event-catalog.md': generateEventCatalog(registry, { consumers: consumersByEventType() }),
+};
+
+if (process.argv.includes('--check')) {
+  reportStale();
+} else {
+  fs.mkdirSync(target, { recursive: true });
+
+  for (const [file, content] of Object.entries(generated)) {
+    fs.writeFileSync(path.join(target, file), content);
+  }
+}
+
+function reportStale(): void {
+  for (const [file, content] of Object.entries(generated)) {
+    const committed = fs.existsSync(path.join(target, file)) ? fs.readFileSync(path.join(target, file), 'utf8') : '';
+
+    if (committed.replaceAll('\r\n', '\n') !== content) {
+      console.error('docs/integration/' + file + ' is out of date: run the script `docs:generate` and commit it.');
+      process.exitCode = 1;
+    }
+  }
+}
+
+/** Every declaration exported by a published language. Read from the compiled modules next to this script, so that a new context needs no registration: a path completed at run time cannot be an import alias, which the build rewrites. */
+async function declaredEvents(): Promise<AnyIntegrationEventDefinition[]> {
+  const declarations: AnyIntegrationEventDefinition[] = [];
+
+  for (const context of contextNames()) {
+    const index = new URL('../{{config.contextsDir}}/' + context + '/published-language/index.js', import.meta.url);
+    const exported: unknown = await import(index.href);
+    const values: unknown[] = typeof exported === 'object' && exported !== null ? Object.values(exported) : [];
+
+    declarations.push(...values.filter(isDeclaration));
+  }
+
+  return declarations;
+}
+
+function contextNames(): string[] {
+  if (!fs.existsSync(path.resolve(contextsDirectory))) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(path.resolve(contextsDirectory), { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && fs.existsSync(path.resolve(contextsDirectory, entry.name, 'published-language')),
+    )
+    .map((entry) => entry.name);
+}
+
+function isDeclaration(value: unknown): value is AnyIntegrationEventDefinition {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    'version' in value &&
+    'payload' in value &&
+    'create' in value
+  );
+}
+
+/** Who consumes what, read from the sources: an integration event handler names the type it handles in `eventType`. */
+function consumersByEventType(): Record<string, string[]> {
+  const consumers: Record<string, string[]> = {};
+
+  for (const context of contextNames()) {
+    for (const type of consumedBy(context)) {
+      consumers[type] = [...new Set([...(consumers[type] ?? []), context])];
+    }
+  }
+
+  return consumers;
+}
+
+function consumedBy(context: string): string[] {
+  const directory = path.resolve(contextsDirectory, context, 'application/integration/handlers');
+  const files = fs.existsSync(directory) ? fs.readdirSync(directory) : [];
+
+  return files.flatMap((file) => {
+    const type = /static readonly eventType = '([^']+)'/.exec(fs.readFileSync(path.join(directory, file), 'utf8'))?.[1];
+
+    return type === undefined ? [] : [type];
+  });
+}
+
+function manifestField(name: string, fallback: string): string {
+  const manifest: unknown = JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8'));
+
+  if (typeof manifest !== 'object' || manifest === null) {
+    return fallback;
+  }
+
+  const value: unknown = Reflect.get(manifest, name);
+
+  return typeof value === 'string' ? value : fallback;
+}

package/templates/init/scripts/openapi.ts.tpl

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkOpenApiDrift, generateOpenApi, stringifyOpenApi } from '@ddd-ts-kit/http/openapi';
+import { offlineAuthenticator } from '{{alias.platform}}/auth/offline-authenticator.js';
+import { securitySchemes } from '{{alias.platform}}/auth/security-schemes.js';
+import { composeApplication } from '{{alias.platform}}/compose-application.js';
+import { inertPersistence } from '{{alias.platform}}/database/inert-persistence.js';
+import { inProcessEvents } from '{{alias.platform}}/events/in-process-events.js';
+
+// Generates openapi/openapi.json from the route definitions; with --check, fails when the
+// committed file differs. The file is a build product: never edit it by hand.
+const target = path.resolve('openapi/openapi.json');
+
+const application = composeApplication(inertPersistence(), {
+  events: inProcessEvents(),
+  authenticator: offlineAuthenticator,
+});
+
+const document = generateOpenApi({
+  info: {
+    title: manifestField('name', '{{project.name}}'),
+    version: manifestField('version', '0.0.0'),
+  },
+  routes: application.routes,
+  securitySchemes,
+  errorMapper: application.boundary.errorMapper,
+});
+
+if (process.argv.includes('--check')) {
+  reportDrift();
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, stringifyOpenApi(document));
+}
+
+function reportDrift(): void {
+  const committed = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+
+  if (!checkOpenApiDrift(document, committed).drift) {
+    return;
+  }
+
+  console.error('openapi/openapi.json is out of date: run the script `docs:generate` and commit it.');
+  process.exitCode = 1;
+}
+
+function manifestField(name: string, fallback: string): string {
+  const manifest: unknown = JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8'));
+
+  if (typeof manifest !== 'object' || manifest === null) {
+    return fallback;
+  }
+
+  const value: unknown = Reflect.get(manifest, name);
+
+  return typeof value === 'string' ? value : fallback;
+}

package/templates/integration-event/audited.tpl

@@ -0,0 +1,4 @@
+@@imports
+import { {{event.camel}}V{{event.version}} } from '{{alias.context}}/published-language/index.js';
+@@events
+{{event.camel}}V{{event.version}},

package/templates/integration-event/integration-event.class-validator.ts.tpl

@@ -0,0 +1,14 @@
+import { defineIntegrationEvent } from '@ddd-ts-kit/events';
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+import { classSchema } from '@ddd-ts-kit/validation/class-validator';
+import { {{event.pascal}}V{{event.version}}Payload } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.payload.js';
+
+export const {{event.camel}}V{{event.version}} = defineIntegrationEvent({
+  type: '{{event.name}}',
+  version: {{event.version}},
+  // TODO(domain): describe in one sentence, for the teams of other contexts, what "{{event.words}}" means.
+  description: '{{event.title}}.',
+  payload: classSchema({{event.pascal}}V{{event.version}}Payload),
+});
+
+export type {{event.pascal}}V{{event.version}} = IntegrationEvent<{{event.pascal}}V{{event.version}}Payload>;

package/templates/integration-event/integration-event.custom.ts.tpl

@@ -0,0 +1,21 @@
+import { defineIntegrationEvent } from '@ddd-ts-kit/events';
+import { err, ok, type IntegrationEvent } from '@ddd-ts-kit/kernel';
+import { customSchema } from '@ddd-ts-kit/validation';
+import type { {{event.pascal}}V{{event.version}}Payload } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.payload.js';
+
+export const {{event.camel}}V{{event.version}} = defineIntegrationEvent({
+  type: '{{event.name}}',
+  version: {{event.version}},
+  // TODO(domain): describe in one sentence, for the teams of other contexts, what "{{event.words}}" means.
+  description: '{{event.title}}.',
+  // TODO(domain): check every field of the payload in the function below and describe each one in the JSON Schema next to it; the catalog of events is generated from it.
+  payload: customSchema<{{event.pascal}}V{{event.version}}Payload>(
+    (input) =>
+      typeof input === 'object' && input !== null && '{{aggregate.camel}}Id' in input && typeof input.{{aggregate.camel}}Id === 'string'
+        ? ok({ {{aggregate.camel}}Id: input.{{aggregate.camel}}Id })
+        : err([{ path: '{{aggregate.camel}}Id', code: 'invalid_type', message: 'A string is expected.' }]),
+    { type: 'object', required: ['{{aggregate.camel}}Id'], properties: { {{aggregate.camel}}Id: { type: 'string' } } },
+  ),
+});
+
+export type {{event.pascal}}V{{event.version}} = IntegrationEvent<{{event.pascal}}V{{event.version}}Payload>;

package/templates/integration-event/integration-event.zod.ts.tpl

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { defineIntegrationEvent, type PayloadOf } from '@ddd-ts-kit/events';
+import type { IntegrationEvent } from '@ddd-ts-kit/kernel';
+import { zodSchema } from '@ddd-ts-kit/validation/zod';
+
+export const {{event.camel}}V{{event.version}} = defineIntegrationEvent({
+  type: '{{event.name}}',
+  version: {{event.version}},
+  // TODO(domain): describe in one sentence, for the teams of other contexts, what "{{event.words}}" means.
+  description: '{{event.title}}.',
+  payload: zodSchema(
+    z.object({
+      {{aggregate.camel}}Id: z.string(),
+      // TODO(domain): add what downstream contexts need to know about "{{event.words}}", as primitives; this is a public contract: inside version {{event.version}} a field can be added, never renamed or removed.
+    }),
+  ),
+});
+
+export type {{event.pascal}}V{{event.version}}Payload = PayloadOf<typeof {{event.camel}}V{{event.version}}>;
+export type {{event.pascal}}V{{event.version}} = IntegrationEvent<{{event.pascal}}V{{event.version}}Payload>;

package/templates/integration-event/payload.class-validator.ts.tpl

@@ -0,0 +1,8 @@
+import { IsString } from 'class-validator';
+
+export class {{event.pascal}}V{{event.version}}Payload {
+  @IsString()
+  {{aggregate.camel}}Id = '';
+
+  // TODO(domain): add what downstream contexts need to know about "{{event.words}}", as decorated primitive fields; this is a public contract: inside version {{event.version}} a field can be added, never renamed or removed.
+}

package/templates/integration-event/payload.custom.ts.tpl

@@ -0,0 +1,4 @@
+export interface {{event.pascal}}V{{event.version}}Payload {
+  readonly {{aggregate.camel}}Id: string;
+  // TODO(domain): add what downstream contexts need to know about "{{event.words}}", as readonly primitives; this is a public contract: inside version {{event.version}} a field can be added, never renamed or removed.
+}

package/templates/integration-event/publisher.declared.ts.tpl

@@ -0,0 +1,24 @@
+import { IdGenerator, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
+import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+import { {{event.camel}}V{{event.version}} } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.integration-event.js';
+
+@DomainEventHandler({{event.pascal}}, { name: '{{event.name}}' }, [IntegrationEventPublisher, IdGenerator])
+export class {{publisher.pascal}}Publisher implements DomainEventHandler<{{event.pascal}}> {
+  constructor(
+    private readonly publisher: IntegrationEventPublisher,
+    private readonly ids: IdGenerator,
+  ) {}
+
+  async handle(event: {{event.pascal}}): Promise<void> {
+    const published = {{event.camel}}V{{event.version}}.create(
+      {
+        {{aggregate.camel}}Id: event.aggregateId,
+        // TODO(domain): map each fact of the domain event to its field of the public payload, as primitives; leave out what other contexts must not depend on.
+      },
+      { id: this.ids.next(), occurredAt: event.occurredAt },
+    );
+
+    await this.publisher.publish([published]);
+  }
+}

package/templates/integration-event/publisher.spec.ts.tpl

@@ -0,0 +1,26 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { InMemoryEventBus, SequentialIdGenerator } from '@ddd-ts-kit/kernel';
+import { {{publisher.pascal}}Publisher } from '{{alias.context}}/application/integration/publishers/{{publisher.kebab}}.publisher.js';
+import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+
+describe('Publishing "{{event.words}}" to other contexts', () => {
+  it('publishes version {{event.version}} of {{event.name}}', async () => {
+    const bus = new InMemoryEventBus();
+    const publisher = new {{publisher.pascal}}Publisher(bus, new SequentialIdGenerator('event'));
+
+    await publisher.handle(new {{event.pascal}}('{{aggregate.kebab}}-1', new Date('2026-01-01T00:00:00.000Z')));
+
+    expect(bus.published).toEqual([
+      {
+        id: 'event-1',
+        type: '{{event.name}}',
+        version: {{event.version}},
+        occurredAt: '2026-01-01T00:00:00.000Z',
+        payload: { {{aggregate.camel}}Id: '{{aggregate.kebab}}-1' },
+      },
+    ]);
+  });
+
+  // TODO(domain): once the payload has its fields, assert each of them here: this test is the contract other contexts rely on.
+  it.todo('carries every field of the public payload');
+});

package/templates/integration-event/publisher.ts.tpl

@@ -0,0 +1,22 @@
+import type { IdGenerator, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+import type { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+import { {{event.camel}}V{{event.version}} } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.integration-event.js';
+
+export class {{publisher.pascal}}Publisher {
+  constructor(
+    private readonly publisher: IntegrationEventPublisher,
+    private readonly ids: IdGenerator,
+  ) {}
+
+  async handle(event: {{event.pascal}}): Promise<void> {
+    const published = {{event.camel}}V{{event.version}}.create(
+      {
+        {{aggregate.camel}}Id: event.aggregateId,
+        // TODO(domain): map each fact of the domain event to its field of the public payload, as primitives; leave out what other contexts must not depend on.
+      },
+      { id: this.ids.next(), occurredAt: event.occurredAt },
+    );
+
+    await this.publisher.publish([published]);
+  }
+}

package/templates/integration-event/wiring.manual.tpl

@@ -0,0 +1,11 @@
+@@imports
+import { {{publisher.pascal}}Publisher } from '{{alias.context}}/application/integration/publishers/{{publisher.kebab}}.publisher.js';
+import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+@@registrations
+const {{publisher.camel}}Publisher = platform.adapter(new {{publisher.pascal}}Publisher(platform.publisher, platform.ids), { kind: 'domain-event-handler', context: '{{context.kebab}}' });
+
+platform.domainEvents.on('{{event.name}}', async (event) => {
+  if (event instanceof {{event.pascal}}) {
+    await {{publisher.camel}}Publisher.handle(event);
+  }
+});

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

@@ -0,0 +1,12 @@
+@@imports
+import { DomainEventDispatcher, IdGenerator, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+import { {{publisher.pascal}}Publisher } from '{{alias.context}}/application/integration/publishers/{{publisher.kebab}}.publisher.js';
+import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event.js';
+@@registrations
+builder.bind({{publisher.pascal}}Publisher).toClass({{publisher.pascal}}Publisher, [IntegrationEventPublisher, IdGenerator]).as('domain-event-handler');
+@@start
+resolve(DomainEventDispatcher).on('{{event.name}}', async (event) => {
+  if (event instanceof {{event.pascal}}) {
+    await resolve({{publisher.pascal}}Publisher).handle(event);
+  }
+});

package/templates/integration-handler/integration-handler.declared.ts.tpl

@@ -0,0 +1,16 @@
+import { CommandBus, systemActor } from '@ddd-ts-kit/kernel';
+import { IntegrationEventHandler } from '@ddd-ts-kit/kernel/declarations';
+import { {{upstream.definition}}, type {{upstream.eventType}} } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+
+@IntegrationEventHandler({{upstream.definition}}, { consumer: '{{context.kebab}}.{{name.kebab}}' }, [CommandBus])
+export class {{name.pascal}}IntegrationHandler {
+  static readonly eventType = '{{upstream.eventName}}';
+
+  readonly actor = systemActor('{{context.kebab}}.{{name.kebab}}');
+
+  constructor(private readonly commands: CommandBus) {}
+
+  async handle(event: {{upstream.eventType}}): Promise<void> {
+    // TODO(domain): translate `event.payload` (the language of {{upstream.kebab}}) into a command of {{context.kebab}}, built with `this.actor` (nobody is calling: the handler acts as a system actor the authorization model has to grant), and execute it with `this.commands.execute(...)`; delivery is at least once, so the command has to be safe to repeat.
+  }
+}

package/templates/integration-handler/integration-handler.spec.ts.tpl

@@ -0,0 +1,40 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { InMemoryCommandBus } from '@ddd-ts-kit/kernel';
+{{#if upstream.known}}
+import { {{upstream.definition}} } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+{{/if}}
+import { {{name.pascal}}IntegrationHandler } from '{{alias.context}}/application/integration/handlers/{{name.kebab}}.integration-handler.js';
+
+describe('When {{upstream.kebab}} publishes {{upstream.eventName}}', () => {
+  it('listens to the type {{upstream.kebab}} publishes', () => {
+    const handler = new {{name.pascal}}IntegrationHandler(new InMemoryCommandBus());
+
+    expect(handler).toBeInstanceOf({{name.pascal}}IntegrationHandler);
+    expect({{name.pascal}}IntegrationHandler.eventType).toBe('{{upstream.eventName}}');
+  });
+
+  it('acts as a system actor named after its consumer name', () => {
+    const handler = new {{name.pascal}}IntegrationHandler(new InMemoryCommandBus());
+
+    expect(handler.actor).toMatchObject({ id: 'system:{{context.kebab}}.{{name.kebab}}', type: 'system' });
+  });
+
+  it('receives the event as {{upstream.kebab}} publishes it', async () => {
+    const handler = new {{name.pascal}}IntegrationHandler(new InMemoryCommandBus());
+    const meta = { id: 'event-1', occurredAt: '2026-01-01T00:00:00.000Z' };
+    {{#if upstream.known}}
+    // TODO(domain): give the payload every field {{upstream.kebab}} declares, register the command the handler executes and assert what {{context.kebab}} did.
+    const event = {{upstream.definition}}.create({ {{upstream.payloadKey}}: '{{upstream.payloadSample}}' }, meta);
+    {{/if}}
+    {{#unless upstream.known}}
+    // TODO(domain): give the payload what {{upstream.kebab}} really sends, register the command the handler executes and assert what {{context.kebab}} did.
+    const event = { ...meta, type: '{{upstream.eventName}}', version: {{upstream.version}}, payload: {} };
+    {{/unless}}
+
+    await expect(handler.handle(event)).resolves.toBeUndefined();
+  });
+
+  // TODO(domain): replace each entry below by a test that hands the handler an event built from the upstream declaration and asserts what {{context.kebab}} did, through a real command bus with the handler and its fakes.
+  it.todo('executes the command that follows the upstream fact');
+  it.todo('has the same outcome when the same event is delivered twice');
+});