@mettlecast/domain-cli

Local developer toolchain for TIB Domain Module projects. Provides build, validate, test, and dev subcommands.

Install

Install as a dev dependency:

npm install --save-dev @mettlecast/domain-cli

Then add to package.json:

{
  "scripts": {
    "domain:build": "mc-domain-module build ./src/domain",
    "domain:validate": "mc-domain-module validate ./src/domain",
    "domain:test": "mc-domain-module test ./src/domain charge-handler --fixture ./fixtures/charge.json",
    "domain:dev": "mc-domain-module dev ./src/domain"
  }
}

Commands

Query & Development

| Command | Description | Output | |---|---|---| | mc-domain-module build <domain> | Load domain handlers via tsx, walk registry, emit .mc/domain-registry.json | Registry JSON at --out <path> or default location | | mc-domain-module validate <domain> | Build registry and lint (semver ranges, 90-day lifecycle rule, enforcement config) | Exits 1 if validation fails (CI gate) | | mc-domain-module test <domain> <handler-id> --fixture <path> | Invoke handler with fixture data, hydrate local DomainContext stub | Handler result printed to stdout | | mc-domain-module dev <domain> | Start Fastify HTTP server on port 3000 (or --port <n>) simulating API Gateway | All defineApi() handlers mounted and callable via HTTP |

Scaffolding

New domains and handlers:

Add a new domain:

npx mc-domain-module add-domain payments [--tenancy required]

Creates domains/payments/ with domain.config.ts, skeleton API, and event definitions.

Add an API endpoint to a domain:

npx mc-domain-module add-api payments charge-api [--method POST] [--tenancy required]

Creates domains/payments/api/charge-api.ts with a defineApi v1 stub.

Add an event subscriber to a domain:

npx mc-domain-module add-subscriber payments charge-completed-subscriber --event payment.completed

Creates domains/payments/subscribers/charge-completed-subscriber.ts listening to payment.completed event.

Add a flow:

npx mc-domain-module add-flow onboard-user

Scaffolds flows/onboard-user.ts with a constrained-step skeleton. Flows can ONLY orchestrate domain primitives (domain-action / domain-api / domain-event / flow-control built-ins) — no raw Lambda ARNs or arbitrary Step Functions states allowed.

Validation & Diagnostics

Run structural checks:

npx mc-domain-module doctor              # human-readable table of all checks
npx mc-domain-module doctor --strict     # exit 1 on any FAIL (CI mode)
npx mc-domain-module doctor --json       # machine-readable JSON output

Verify infra/modules/ integrity:

npx mc-domain-module check-hashes

Verifies that infra/modules/ files have not been hand-edited since the last scaffold. Compares current SHA256 against .mc/modules-hashes.json manifest. Reports drifted, missing, and unexpected files. Re-scaffold to legitimately update infra/modules/.

Registry Building

Build domain registries:

npx mc-domain-module build domains/<id>

Loads domain handlers, walks registry, and emits .mc/<id>-registry.json and .mc/actions-types.d.ts. CI runs this before cdk deploy domain-<id>.

Build flow registries:

npx mc-domain-module build-flows --out .mc/flows-registry.json

Walks flows/*.{ts,json}, validates each flow definition, and emits .mc/flows-registry.json. CI runs this before cdk deploy of the flows stack.

Typical Workflow

1. Develop locally

   npm run domain:dev
   # Open http://localhost:3000/charge with curl

2. Test a handler

   npm run domain:test charge-handler --fixture ./fixtures/charge.json

3. Validate before commit

   npm run domain:validate

4. Build for deployment

   npm run domain:build
   # .mc/domain-registry.json is ready for CDK or contracts generation

Options

build:

• --out <path> — Override output file path (default: .mc/domain-registry.json)

dev:

• --port <n> — Listen port (default: 3000)

test:

• --fixture <path> — Required. JSON file with shape { event?: unknown, ctx?: Partial<DomainContext> }

See Also

• @mettlecast/domain-runtime — handler definitions
• @mettlecast/domain-cdk-packer — CDK infrastructure
• @mettlecast/eslint-plugin-domain-module — linting rules