@domain-first/project-structure 7.2.0 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -25
- package/dist/201.js +87 -338
- package/dist/287.js +1183 -568
- package/dist/561.js +518 -0
- package/dist/711.js +22 -0
- package/dist/870.js +438 -0
- package/dist/agent-cli.d.ts +378 -0
- package/dist/agent-cli.spec.d.ts +1 -0
- package/dist/agent-identifiers.d.ts +4 -0
- package/dist/agent-requests.d.ts +488 -0
- package/dist/config-file.d.ts +231 -26
- package/dist/config-file.spec.d.ts +1 -0
- package/dist/context-dependencies.d.ts +16 -0
- package/dist/dependency-rules.d.ts +17 -17
- package/dist/file-system.d.ts +10 -1
- package/dist/implementation-choices.d.ts +8 -0
- package/dist/implementation-choices.spec.d.ts +1 -0
- package/dist/implementation-options-schema.d.ts +14 -0
- package/dist/index.cjs +3598 -583
- package/dist/index.js +20 -7
- package/dist/init.cjs +717 -122
- package/dist/init.js +24 -12
- package/dist/integration.cjs +3737 -186
- package/dist/integration.js +29 -17
- package/dist/integrations/rest-endpoint-generator.d.ts +4 -2
- package/dist/integrations/storybook.d.ts +1 -0
- package/dist/interaction.d.ts +41 -0
- package/dist/lint.cjs +165 -41
- package/dist/lint.js +22 -7
- package/dist/next-app.d.ts +7 -0
- package/dist/react.cjs +5128 -414
- package/dist/react.js +72 -60
- package/dist/system-implementations.d.ts +6 -0
- package/dist/upgrade-steps.d.ts +81 -0
- package/dist/upgrade-steps.spec.d.ts +1 -0
- package/dist/upgrade.cjs +593 -0
- package/dist/upgrade.d.ts +2 -0
- package/dist/upgrade.js +235 -0
- package/dist/use-cases/add-integration.d.ts +16 -1
- package/dist/use-cases/cross-context-dependencies.spec.d.ts +1 -0
- package/dist/use-cases/initialize.d.ts +4 -4
- package/dist/use-cases/initialize.spec.d.ts +1 -0
- package/dist/use-cases/prompt-implementation-type.d.ts +20 -0
- package/dist/use-cases/scaffold-react-page.d.ts +3 -1
- package/dist/wire-branches.d.ts +26 -0
- package/dist/wiring.d.ts +3 -2
- package/package.json +3 -2
- package/skills/df-ps-implement/SKILL.md +9 -8
- package/skills/df-ps-plan-feature/SKILL.md +8 -7
- package/skills/df-ps-react/SKILL.md +13 -7
- package/skills/df-ps-react/references/generators.md +6 -2
- package/skills/df-ps-scaffold/SKILL.md +28 -17
- package/skills/df-ps-scaffold/references/agent-mode.md +72 -0
- package/skills/df-ps-scaffold/references/agent-operations.md +155 -0
- package/skills/df-ps-scaffold/references/choosing-components.md +13 -13
- package/skills/df-ps-scaffold/references/generators.md +20 -3
- package/skills/df-ps-scaffold/references/units/aggregate.md +4 -3
- package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
- package/skills/df-ps-scaffold/references/units/command-query.md +12 -12
- package/skills/df-ps-scaffold/references/units/implementation.md +2 -2
- package/skills/df-ps-scaffold/references/units/move-or-rename.md +1 -1
- package/skills/df-ps-scaffold/references/units/port.md +7 -4
- package/skills/df-ps-scaffold/references/units/use-case.md +1 -1
- package/skills/df-ps-scaffold/scripts/drive.mjs +9 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: df-ps-scaffold
|
|
3
|
-
description: Generate Domain-First components with the `df-scaffold` CLI (@domain-first/project-structure) — bounded contexts, aggregates, repositories, errors, services, use cases, commands, queries, ports and handlers-rest endpoints. Use when the project has domain-first.project-structure.config.json and the user asks to add or create any of these. Holds the mandatory rules (work plan approval, new files and new dependencies only via the CLIs) and the CLI
|
|
3
|
+
description: Generate Domain-First components with the `df-scaffold` CLI (@domain-first/project-structure) — bounded contexts, aggregates, repositories, errors, services, use cases, commands, queries, ports and handlers-rest endpoints. Use when the project has domain-first.project-structure.config.json and the user asks to add or create any of these. Holds the mandatory rules (work plan approval, new files and new dependencies only via the CLIs) and the JSON CLI workflow that the other df-ps skills, df-ps-react included, rely on.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Scaffold components with df-scaffold
|
|
@@ -9,12 +9,12 @@ description: Generate Domain-First components with the `df-scaffold` CLI (@domai
|
|
|
9
9
|
|
|
10
10
|
Follow this order for every request:
|
|
11
11
|
|
|
12
|
-
1. Read `domain-first.project-structure.config.json`
|
|
12
|
+
1. Read `domain-first.project-structure.config.json` beside the nearest `package.json`: `project.rootFolder`, `backend` (including `backend.implementations` and `backend.rules`), and `frontend`. `frontend.react.framework` records React (`react`) or Next.js (`next`); both use `df-react`. Initialization and configuration belong to the human: never run `df-init` or manually add/change these settings. If the config is missing, tell the user to run `npx df-init`; if backend work needs an absent `backend`, tell them to run `npx df-init --section backend`. Continue only with work whose required sections are configured. A config of an earlier major version (flat, without `project`) makes every command stop with `run npx df-upgrade` (`CONFIG_OUTDATED` in JSON mode): ask the user to run `npx df-upgrade`; never run it or convert the config yourself. `df-init` scaffolds explicit standard lists and enabled lint checks under `backend.rules`; read the saved values as authoritative. Older or partial configs may omit entries, which retain the defaults. Backend reconfiguration by the user fills missing entries without resetting existing rules.
|
|
13
13
|
2. Feature request without named contexts/components → `df-ps-plan-feature` (it covers steps 3–5).
|
|
14
14
|
3. Choose a component for each piece of logic with `references/choosing-components.md`. Pieces of UI (pages, widgets, UI-kit components, shared hooks): `df-ps-react`.
|
|
15
|
-
4. Read `references/units/<unit>.md` for every unit in the plan ("Units" below) and prepare the run details ("Preparing runs").
|
|
15
|
+
4. Read `references/units/<unit>.md` for every unit in the plan ("Units" below) and prepare the run details ("Preparing runs"). Read [agent-mode.md](references/agent-mode.md) for the JSON protocol and use `--describe` to obtain the installed request schema and selectable IDs.
|
|
16
16
|
5. If the task creates files, show the work plan and **stop until it's approved** (rule 1).
|
|
17
|
-
6. Run the generators in plan order with
|
|
17
|
+
6. Run the generators in plan order with `--request` JSON; check exit code, `ok` and all returned file lists. Use the driver only for older CLI versions without JSON support.
|
|
18
18
|
7. Implement each unit by the "Implement" and "Test" sections of its unit file and the general rules of `df-ps-implement`, in this order: domain → application → schema tool runs (migrations) → infrastructure → endpoints → other tool runs (OpenAPI, API client) → React (`df-ps-react`).
|
|
19
19
|
8. Run `npx df-lint` and the project's tsc/lint/tests.
|
|
20
20
|
9. Report against the plan.
|
|
@@ -23,7 +23,7 @@ Follow this order for every request:
|
|
|
23
23
|
|
|
24
24
|
### 1. Work plan approval
|
|
25
25
|
|
|
26
|
-
**A task that creates any new file** (a df-scaffold run, or a hand-created file under rule 2) needs an approved work plan first, even for one component, unless the user explicitly says to skip approval for this task. Until approval, only read. Files written by the project's own scripts (rule 2, exception 2) don't count: run those scripts when the work needs them.
|
|
26
|
+
**A task that creates any new file** (a df-scaffold run, or a hand-created file under rule 2) needs an approved work plan first, even for one component, unless the user explicitly says to skip approval for this task. Until approval, only read (`--describe` and `dryRun: true` do not write files). Files written by the project's own scripts (rule 2, exception 2) don't count: run those scripts when the work needs them.
|
|
27
27
|
|
|
28
28
|
Tasks that only edit existing files (a bug fix, a new field, a changed rule) don't need a plan: do them directly and say what you changed.
|
|
29
29
|
|
|
@@ -52,7 +52,7 @@ Tool runs:
|
|
|
52
52
|
- `npm run openapi && npm run client:orval`: OpenAPI document and API client with the new endpoints
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
- Every run lists the CLI path, target, name, every answer
|
|
55
|
+
- Every run lists the CLI path, target, name, the JSON parameters (or every answer for a legacy interactive run), and the files from its unit file. Flag overwrites of existing files.
|
|
56
56
|
- Hand-written changes: members, schemas, dependencies. Not full code.
|
|
57
57
|
- Tool runs: every command that generates files (migrations, OpenAPI, API client, other codegen), with what it produces and when. Use the project's own scripts; find them in `package.json` and configs. Their output needs no approval of its own and is never edited; scripts that change a database are run only by the user. Details: the project's scripts skill (`project-scripts`), if there is one.
|
|
58
58
|
- Any file outside the rule 2 exceptions appears as a separate **exception request** with a reason.
|
|
@@ -73,7 +73,7 @@ Every new file is created by `df-scaffold` (React modules: `df-react`). Don't cr
|
|
|
73
73
|
|
|
74
74
|
Anything else (helpers, types, constants, mappers, wiring, barrels): put it in an existing generated file, or generate a component that can host it. Editing existing files is fine. If neither works, request an exception for that exact file.
|
|
75
75
|
|
|
76
|
-
If the CLI
|
|
76
|
+
If the CLI cannot run, report the failure and give the user the prepared JSON command to run themselves (the menu path and answers only for a legacy CLI). Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
|
|
77
77
|
|
|
78
78
|
Moving or renaming a module (aggregate, entity, value object, service, port, query, command, use case) is a df-scaffold run, `Move or rename` (`references/units/move-or-rename.md`); a page or widget, a df-react run (`df-ps-react`). Never by hand: it creates files at the new paths, so it needs an approved plan.
|
|
79
79
|
|
|
@@ -82,11 +82,11 @@ Moving or renaming a module (aggregate, entity, value object, service, port, que
|
|
|
82
82
|
With `@domain-first/wire`, every new dependency of a wired class (a constructor parameter plus its wire) is added by `df-scaffold`: the generator's `Dependencies:` step for a new module, `Wire dependency` for an existing one, and the `Handler:` pick for an endpoint (its generator is added automatically). Don't add constructor parameters or wire entries by hand, and don't reorder or remove the ones `df-scaffold` added.
|
|
83
83
|
|
|
84
84
|
- List each module's dependencies in the plan as run options (`deps: OrderRepository`), with a `Wire dependency` run for existing modules.
|
|
85
|
-
- A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `rules.dependencies` in the config) or by context isolation: change the design (a port, a query or command, an infrastructure service) instead of adding it by hand.
|
|
85
|
+
- A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `backend.rules.dependencies` in the config) or by context isolation: change the design (a port, a query or command, an infrastructure service) instead of adding it by hand.
|
|
86
86
|
- A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service named after the implementation label (`prisma`, `in-memory-db`, `stripe`): the service creates or reads it itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-scaffold`, where it shows up under `Suggested`. Wrap the service's wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`. A domain or application module never gets such a value directly: it depends on a port whose adapter uses the service.
|
|
87
87
|
- An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
|
|
88
88
|
|
|
89
|
-
### 4.
|
|
89
|
+
### 4. Cross-context calls stay in application port adapters
|
|
90
90
|
|
|
91
91
|
Details and the check script: `df-ps-implement`, "Bounded context isolation".
|
|
92
92
|
|
|
@@ -114,25 +114,36 @@ One file per unit in `references/units/`: when to choose it, how to generate it
|
|
|
114
114
|
|
|
115
115
|
- **Contexts**: subfolders of `<rootFolder>/bounded-contexts/` (menu: `Bounded Context: <name>`).
|
|
116
116
|
- **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`).
|
|
117
|
-
- **Collisions**:
|
|
118
|
-
- **Tests**: with `testingLibrary` set, df-scaffold always generates specs; add a test implementation (`in-memory`/`mock`) to repositories, commands/queries, and ports. Otherwise the spec wires the real one. Without `testingLibrary`, tell the user once and suggest adding it with `! npx df-integration` (Vitest); don't edit the config yourself.
|
|
119
|
-
- **
|
|
117
|
+
- **Collisions**: JSON requests require `overwrite: true` to replace changed existing files. Inspect `overwriteRequired` with `dryRun: true` and include those overwrites in the plan. The interactive equivalent asks `Overwrite them?`.
|
|
118
|
+
- **Tests**: with `backend.testingLibrary` set, df-scaffold always generates specs; add a test implementation (`in-memory`/`mock`) to repositories, commands/queries, and ports. Otherwise the spec wires the real one. Without `backend.testingLibrary`, tell the user once and suggest adding it with `! npx df-integration` (Vitest); don't edit the config yourself.
|
|
119
|
+
- **Requests**: take the unit semantics and output files from its reference, then use `--describe` and `references/agent-mode.md` to build a JSON request. The scripted prompt sequences are the legacy interactive fallback.
|
|
120
120
|
|
|
121
|
-
## Running
|
|
121
|
+
## Running non-interactively
|
|
122
122
|
|
|
123
|
-
`df-scaffold`
|
|
123
|
+
Use `npx df-scaffold --describe` and execute approved operations with `--request` JSON. React uses `df-react`; integrations use `df-integration`. Protocol, discovery IDs, previews and error handling: [references/agent-mode.md](references/agent-mode.md). Complete backend/React operation map, dependency recipes and conditional integration options: [references/agent-operations.md](references/agent-operations.md).
|
|
124
|
+
|
|
125
|
+
Initialization remains a human task. No JSON initialization workflow is provided.
|
|
126
|
+
|
|
127
|
+
## Legacy interactive driver
|
|
128
|
+
|
|
129
|
+
For CLI versions without JSON support, `scripts/drive.mjs` answers its prompts, then lists created (`+`) and changed (`~`) files. With `--bin df-react` it drives the React CLI instead (`df-ps-react`).
|
|
124
130
|
|
|
125
131
|
```bash
|
|
126
132
|
node <this-skill-dir>/scripts/drive.mjs [--bin df-react] [--cwd <dir>] [--delay <ms>] <step>...
|
|
127
|
-
node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggregate" text:order yes
|
|
133
|
+
node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggregate" text:order yes "pick:Enter implementation type and save for future use" text:prisma no
|
|
128
134
|
```
|
|
129
135
|
|
|
130
136
|
| Step | Prompt | Effect |
|
|
131
137
|
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
132
138
|
| `pick:<label>` | select | Types a **prefix of the choice text** + Enter. Aborts before submitting if the highlighted choice doesn't match. |
|
|
133
|
-
| `text:<v>`
|
|
139
|
+
| `text:<v>` | input | Types a value. |
|
|
140
|
+
| `default` | input/select | Accepts the suggested input value or the highlighted default choice. |
|
|
134
141
|
| `yes` / `no` | confirm | |
|
|
135
|
-
| `toggle:1,3` / `none` | checkbox |
|
|
142
|
+
| `toggle:1,3` / `none` | checkbox | `Dependencies:`, `Dependencies for <Implementation>:`. `Suggested` items come checked: toggling unchecks. |
|
|
143
|
+
|
|
144
|
+
Implementation-type menus contain saved names and active system choices, without automatic `api` or `mock` presets. Use `pick:prisma` only when saved for that category, `"pick:System: cross-context"` for a port with a neighboring context, or `"pick:System: in-memory"` for a repository/command/query with the shared DB integration ready. New ordinary names take two steps: `"pick:Enter implementation type and save for future use" text:redis` or `"pick:Enter implementation type for this run only" text:redis`. Use the complete manual-entry label to distinguish saving from run-only input. `default` accepts the selected choice.
|
|
145
|
+
|
|
146
|
+
Custom types entered with the save action update `backend.implementations` in `domain-first.project-structure.config.json`; include that generated config update in the work plan. The run-only action generates code without adding saved choices. These generator-managed choice updates are allowed; project/backend/frontend setup remains a human task. Changes are staged with the generated code and cancelled with it. Repository, command, query and port choices are independent; read that category's saved `primary`/`test` lists before preparing answers.
|
|
136
147
|
|
|
137
148
|
Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the planned files. "Still waiting for input" means too few steps; nothing was written. If the raw output ends at `Overwrite them?`, the run would replace files the plan didn't flag: show the user the listed files and ask, never just add `yes`. If prompts get out of sync, retry with `--delay 1200`.
|
|
138
149
|
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Non-interactive operations for agents
|
|
2
|
+
|
|
3
|
+
Prefer the JSON interface for `df-scaffold`, `df-react` and `df-integration`. Use the interactive driver only with older CLI versions that lack this interface. Initialization (`df-init`) remains a human task. The same plan, file creation and dependency rules apply to both interfaces.
|
|
4
|
+
|
|
5
|
+
For the complete operation map, conditional integration fields and recipes, read [agent-operations.md](agent-operations.md) for the work at hand.
|
|
6
|
+
|
|
7
|
+
## Discover before constructing requests
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx df-scaffold --describe
|
|
11
|
+
npx df-react --describe
|
|
12
|
+
npx df-integration --describe
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Each command returns one JSON document with `schemaVersion: 1`, `requestSchema` and the project inventory. Use the schema from the installed version instead of guessing fields. Read `--describe` first; a valid JSON error is not a reason to fall back to the driver. Use the legacy driver only if that installed CLI does not support the flags or opens an interactive menu instead of returning JSON. Stop that discovery process before retrying with the driver; do not automatically upgrade the project package to change interfaces. Without a config it still describes the protocol; ask the owner to initialize missing sections.
|
|
16
|
+
|
|
17
|
+
- `project.contexts[].name`: a bounded context or the reserved `shared-kernel` context.
|
|
18
|
+
- `modules[].id`: qualified dependency ID, e.g. `shared-kernel:PrismaInfrastructureService` or `billing:InvoiceQuery`.
|
|
19
|
+
- `modules[].implementations[].target`: wiring target including its implementation class, e.g. `sales:OrdersQuery:PrismaOrdersQuery`.
|
|
20
|
+
- `modules[].implementations[].dependencies`: currently available dependencies to add to that implementation, filtered by the same rules as the interactive menu. Already-wired dependencies are excluded.
|
|
21
|
+
- `units[].id` and `contracts[].id`: IDs for moves and new implementations, e.g. `query:orders`, `aggregate:order`, `entity:order/line`.
|
|
22
|
+
- `implementationTypes`: saved primary/test labels and available system types per contract category. Do not put the UI's `System:` prefix into a request.
|
|
23
|
+
- `project.integrations`: stable integration IDs and availability; `project.reactModules`: current page/widget names.
|
|
24
|
+
|
|
25
|
+
Refresh discovery after operations that change selectable modules or dependencies. Do not substitute list indexes, display labels or guessed file paths for IDs.
|
|
26
|
+
|
|
27
|
+
## Execute or preview
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx df-scaffold --request '{"operation":"query","context":"sales","name":"orders","implementation":{"type":"prisma","save":false},"dependencies":{"PrismaOrdersQuery":["shared-kernel:PrismaInfrastructureService"]}}'
|
|
31
|
+
npx df-react --request '{"operation":"widget","name":"admin/orders","widgetType":"separated"}'
|
|
32
|
+
npx df-integration --request '{"operation":"add","integrations":["storybook"]}'
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`--request` takes literal JSON, or `-` to read one JSON document from stdin. No request file needs to be created. When constructing invocations programmatically, pass JSON as an argument or stdin through a subprocess API; avoid interpolating values into shell code.
|
|
36
|
+
|
|
37
|
+
- `dryRun: true` returns the proposed changes without writing anything. Discovery and dry runs are read-only and can be used while preparing a plan.
|
|
38
|
+
- `overwrite: true` explicitly permits replacing changed existing generated files. Use it only for overwrites covered by the approved plan. Never add it merely to bypass an `OVERWRITE_REQUIRED` error; inspect the listed paths first. Identical generated file contents need no overwrite flag.
|
|
39
|
+
- `implementation` / `testImplementation`: `{ "type": "prisma", "save": false }`. `save` defaults to false; true remembers an ordinary type in the appropriate backend implementation choices. A missing `testImplementation` means no separate test implementation.
|
|
40
|
+
- `dependencies`: implementation/class name → array of qualified module IDs. Omitted entries keep the generator's checked suggestions; `[]` explicitly selects none when that selection applies. When wiring is off or no candidates exist, omit the group; see the [dependency conditions](agent-operations.md#dependency-keys-and-system-implementations). Every supplied dependency group must apply to the operation. Different primary/test implementations have independent lists.
|
|
41
|
+
- Aggregate repositories require `withRepository: true` and an `implementation`. Without it, aggregate creation makes no repository.
|
|
42
|
+
- New implementations use a `contract` ID and, with a branched wire, an explicit `environments` array. Moves use a `module` unit ID and optional `targetContext`, `aggregate` and `name`. `wire-dependency` uses a wiring target ID in `module` plus its `dependencies` entry.
|
|
43
|
+
- Endpoints use `controller`, lowercase `method`, relative `path` and a qualified `handler` ID when a wired handler is available. A new controller is created when its name does not exist.
|
|
44
|
+
- Integration-specific fields and script conflict decisions are in the integration request schema. Conflicts require explicit decisions, e.g. `"scriptConflicts": { "storybook": "keep" }`. Configuration changes that require confirmation interactively also require their explicit request field.
|
|
45
|
+
|
|
46
|
+
## Check the result
|
|
47
|
+
|
|
48
|
+
Success is one JSON document with `ok: true`, exit code 0, and:
|
|
49
|
+
|
|
50
|
+
- `files.created`, `files.updated`, `files.deleted`: project-relative file paths.
|
|
51
|
+
- `directories`: new directories; `overwriteRequired`: changed files requiring permission to replace (useful for dry runs).
|
|
52
|
+
- `nextSteps`: install commands and follow-up notes; commands are not executed.
|
|
53
|
+
- `messages`: generator diagnostics.
|
|
54
|
+
- `dryRun`: whether the plan was only previewed.
|
|
55
|
+
|
|
56
|
+
Compare the reported changes with the approved plan, then implement the generated code. A nonzero exit code or `ok: false` is failure. Errors include a stable `error.code`, a message and, when applicable, `error.details` identifying fields or available choices. Invalid requests, unavailable dependencies and refused overwrites discard all staged source/config/history changes. The command never falls back to a prompt. Correct the request within its approved scope and retry; do not hand-write the generator's output.
|
|
57
|
+
|
|
58
|
+
## Recover from an error
|
|
59
|
+
|
|
60
|
+
| Error codes | Next action |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `PROJECT_NOT_FOUND`, `CONFIG_NOT_FOUND`, `BACKEND_NOT_CONFIGURED`, `FRONTEND_NOT_CONFIGURED`, `INVALID_CONFIG` | Check project location and required config section. Ask the owner to initialize or repair settings; continue independent work only where its required sections are ready. |
|
|
63
|
+
| `CONFIG_OUTDATED` | The config has the format of an earlier major version. Stop and ask the user to run `npx df-upgrade`; never run it or edit the config yourself. `--describe` reports it as `project.configStatus: "outdated"`. |
|
|
64
|
+
| `INVALID_JSON`, `INVALID_REQUEST`, `MISSING_PARAMETER`, `INVALID_PARAMETER`, `INVALID_ARGUMENTS` | Fix the request against the installed schema and error details. Check JSON syntax, required fields, naming and mutually exclusive CLI flags. |
|
|
65
|
+
| `INVALID_CHOICE`, `INVALID_IMPLEMENTATION` | Refresh discovery and check eligibility, disabled/duplicate types and cross-context restrictions. Do not bypass rules with manual wiring/imports. |
|
|
66
|
+
| `UNUSED_PARAMETERS` | Check the class key, wiring availability and integration conditions. Omit genuinely inapplicable fields; do not drop an intended dependency merely to make a request pass. |
|
|
67
|
+
| `CONTEXT_NOT_FOUND`, `TARGET_NOT_FOUND`, `REST_NOT_CONFIGURED` | Create the required context, aggregate, namespace, contract, handler or integration first if that work is authorized; otherwise report the missing prerequisite. A dry run of a prerequisite does not create it. |
|
|
68
|
+
| `OVERWRITE_REQUIRED` | Preview and inspect the listed paths. Use `overwrite: true` only for replacements already within the approved plan; obtain any required plan change first. |
|
|
69
|
+
| `MOVE_NOT_ALLOWED` | Review the boundary violations and change the design or move prerequisites first. Do not perform the move by hand. |
|
|
70
|
+
| `CANCELLED`, `OPERATION_FAILED`, `UNSUPPORTED_PROMPT` | Inspect the message and report the failed operation or unsupported CLI path. Do not treat this as permission to switch to interactive execution or write output by hand. |
|
|
71
|
+
|
|
72
|
+
Failures discard the operation's staged changes. Success can still have follow-up notes: inspect `messages`/`nextSteps` for manual adapter connection, integration installation, custom wiring or an implementation no longer selected by any environment. Check the actual generated files before implementing business logic.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# JSON operation catalogue
|
|
2
|
+
|
|
3
|
+
Read the common protocol in [agent-mode.md](agent-mode.md) first. This catalogue maps every current operation to its fields and gives recipes for cases with extra conditions. The installed `--describe` schema remains authoritative; fields not accepted by that version must not be sent.
|
|
4
|
+
|
|
5
|
+
One invocation accepts one operation, not an array or a batch. Each invocation saves its own transaction. A successful dry run creates no prerequisites for later requests: dependent operations need their preceding contexts, aggregates, contracts or modules to exist on disk. Run approved prerequisites in plan order and refresh discovery.
|
|
6
|
+
|
|
7
|
+
## Backend operations: df-scaffold
|
|
8
|
+
|
|
9
|
+
All operations support `dryRun` and `overwrite`. Except `bounded-context`, they require `context`, using a discovered context name or reserved `shared-kernel`. Names are lowercase kebab-case. The backend must be configured by the owner.
|
|
10
|
+
|
|
11
|
+
| Operation | Required fields beyond operation/context | Optional fields and conditions |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| `bounded-context` | `name`; no `context` | Creates an empty context. `shared-kernel` is a reserved name. |
|
|
14
|
+
| `aggregate` | `name` | `withRepository` defaults to false. True requires `implementation`; may also use `testImplementation` and `dependencies`. These repository fields do not apply when `withRepository` is false. Bounded contexts only. |
|
|
15
|
+
| `entity` | `name` | `aggregate` selects an existing aggregate in the same context; omitted means a standalone domain entity. |
|
|
16
|
+
| `value-object` | `name` | Same aggregate rules as entity. |
|
|
17
|
+
| `error` | `name` | `namespace` selects an existing namespace; omitted appends to the context's root error namespace. |
|
|
18
|
+
| `error-namespace` | `name` | Creates a namespace, not an error class. Create it before requesting an error in that namespace. |
|
|
19
|
+
| `domain-service` | `name` | `dependencies`, when wiring is configured and eligible modules exist. |
|
|
20
|
+
| `application-service` | `name` | `dependencies`, with the same conditions. |
|
|
21
|
+
| `infrastructure-service` | `name` | `dependencies`, with the same conditions. |
|
|
22
|
+
| `presentation-service` | `name` | `dependencies`, with the same conditions. |
|
|
23
|
+
| `use-case` | `name` | `dependencies`. Bounded contexts only. |
|
|
24
|
+
| `command` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |
|
|
25
|
+
| `query` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |
|
|
26
|
+
| `port` | `name`, `implementation` | `testImplementation`, `dependencies`. `cross-context` is available only with a neighboring context, never in Shared Kernel. |
|
|
27
|
+
| `implementation` | `contract`, `implementation` | For a usable branched wire, `environments` is required and nonempty; otherwise omit it. `dependencies` is available for the newly added implementation when wiring applies. |
|
|
28
|
+
| `endpoint` | `controller`, `method`, `path` | REST package and generator must exist. With wiring and selectable handlers, provide `handler`. Without selectable handlers, omit it; the generated handler remains `never` and needs a later approved generator rerun. |
|
|
29
|
+
| `wire-dependency` | `module`, `dependencies` | `module` is a wiring target ID, not a contract/unit ID. Adds only eligible dependencies not already wired to that implementation. |
|
|
30
|
+
| `move` | `module` | `module` is a unit ID. Optional `name`, `targetContext`, `aggregate`; omitted name/context keep the existing ones. A same-owner entity/value-object keeps its aggregate by default. The target aggregate must exist; the target context must be a discovered, allowed destination for that unit kind. Illegal cross-context imports reject the move. |
|
|
31
|
+
|
|
32
|
+
`implementation` and `testImplementation` contain `type` and optional `save` (default false). Explicit types can be new ordinary names; they need not already be saved. Saving is independent for primary and test roles. The test type must differ from the primary type. Adding a new implementation remembers a saved type according to the selected environments: `test` or primary for other environments. Branches are `backend.envBranches.names` from the config (`test`, `development`, `production` when absent), with `backend.envBranches.test` as the test one; additional names must be offered by the existing branched wire. Custom branches without `test` take no test implementations: omit `testImplementation`. Without usable branching, omit `environments` and follow the returned wiring note.
|
|
33
|
+
|
|
34
|
+
## Dependency keys and system implementations
|
|
35
|
+
|
|
36
|
+
The keys in `dependencies` identify concrete classes, while the values identify dependencies by qualified IDs:
|
|
37
|
+
|
|
38
|
+
| Consumer | Key example |
|
|
39
|
+
| --- | --- |
|
|
40
|
+
| Repository implementation of aggregate `order` | `PrismaOrderRepository` |
|
|
41
|
+
| Query / command implementation | `PrismaOrdersQuery`, `SqlPayCommand` |
|
|
42
|
+
| Port adapter | `CrossContextBillingGateway`, `MockBillingGateway` |
|
|
43
|
+
| Service | `PricingDomainService`, `PaymentApplicationService`, `PrismaInfrastructureService`, `HttpPresentationService` |
|
|
44
|
+
| Use case | `PlaceOrderUseCase` |
|
|
45
|
+
|
|
46
|
+
For existing modules, copy the class from `modules[].implementations[].className`; for newly generated modules use the unit's naming rules. Never use the abstract contract name as an implementation key.
|
|
47
|
+
|
|
48
|
+
Omitted groups retain checked suggestions; `[]` explicitly chooses none when that dependency selection applies. With no eligible candidates the generator skips that selection: omit its group, including an empty one. Without `@domain-first/wire`, omit `dependencies` entirely. A group for another class, an already-wired dependency in an add operation, or an inapplicable option produces a failure rather than being silently ignored. An `UNUSED_PARAMETERS` error means the selection did not apply; verify the class and conditions before removing a field.
|
|
49
|
+
|
|
50
|
+
With the shared in-memory DB enabled and its files ready, the system `in-memory` type receives its DB through the usual suggested wiring. Without wiring the generator passes the DB through its existing constructor logic. Without the ready integration it is an ordinary name and generates no DB behavior. For ports, `in-memory` is always an ordinary label.
|
|
51
|
+
|
|
52
|
+
Example query with independent primary and test dependencies (assumes the displayed services exist and in-memory DB is active):
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"operation": "query",
|
|
57
|
+
"context": "sales",
|
|
58
|
+
"name": "orders",
|
|
59
|
+
"implementation": { "type": "prisma", "save": true },
|
|
60
|
+
"testImplementation": { "type": "in-memory", "save": false },
|
|
61
|
+
"dependencies": {
|
|
62
|
+
"PrismaOrdersQuery": ["shared-kernel:PrismaInfrastructureService"],
|
|
63
|
+
"InMemoryOrdersQuery": ["shared-kernel:InMemoryDbInfrastructureService"]
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Example direct call through a consuming context's port (assumes `billing:InvoiceQuery` exists):
|
|
69
|
+
|
|
70
|
+
```json
|
|
71
|
+
{
|
|
72
|
+
"operation": "port",
|
|
73
|
+
"context": "sales",
|
|
74
|
+
"name": "billing-gateway",
|
|
75
|
+
"implementation": { "type": "cross-context", "save": false },
|
|
76
|
+
"dependencies": {
|
|
77
|
+
"CrossContextBillingGateway": ["billing:InvoiceQuery"]
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
This generates the adapter and injection only; define the port's methods and map inputs, outputs and errors as described in [port.md](units/port.md). It does not make foreign models or other module kinds accessible.
|
|
83
|
+
|
|
84
|
+
Adding a test implementation to an existing contract, then adding a dependency to the primary one are separate operations:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"operation": "implementation",
|
|
89
|
+
"context": "sales",
|
|
90
|
+
"contract": "query:orders",
|
|
91
|
+
"implementation": { "type": "fake", "save": true },
|
|
92
|
+
"environments": ["test"]
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"operation": "wire-dependency",
|
|
99
|
+
"context": "sales",
|
|
100
|
+
"module": "sales:OrdersQuery:PrismaOrdersQuery",
|
|
101
|
+
"dependencies": {
|
|
102
|
+
"PrismaOrdersQuery": ["shared-kernel:ClockInfrastructureService"]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The latter assumes Clock is eligible and not already wired. Refresh `--describe` first; a dependency forbidden by its rules is not a reason to add it manually.
|
|
108
|
+
|
|
109
|
+
## React operations: df-react
|
|
110
|
+
|
|
111
|
+
The owner configures frontend first. React and Next.js use the same operations. Story generation follows `frontend.react.storybookFramework`; there is no Storybook option on individual requests.
|
|
112
|
+
|
|
113
|
+
| Operation | Required fields | Optional fields and conditions |
|
|
114
|
+
| --- | --- | --- |
|
|
115
|
+
| `page` | `name` | Names may contain folders, e.g. `admin/orders`. With Next.js, also creates the App Router route `app/admin/orders/page.tsx` unless it exists. |
|
|
116
|
+
| `widget` | `name` | Nested names allowed. `widgetType`: `separated` (default), `headless`, `monolithic`; use the JSON value `separated`, not the menu label `with separated ui`. |
|
|
117
|
+
| `ui-kit-component` | `name` | Single kebab-case name; stories follow config. |
|
|
118
|
+
| `shared-hook` | `name` | Single kebab-case name, preferably without `use-`; a leading `use-` is stripped. |
|
|
119
|
+
| `move-page` | `module`, `name` | `module` is the existing nested page name from discovery; `name` is the target nested name. With Next.js, the route's import follows, but the route folder stays: plan its move separately if the URL changes. |
|
|
120
|
+
| `move-widget` | `module`, `name` | Same for widgets. Files, imports, code names and generated story titles follow the move. |
|
|
121
|
+
|
|
122
|
+
All support `dryRun` and `overwrite`. Use CLI moves even for a rename or folder regrouping; an existing target or a move into itself is rejected.
|
|
123
|
+
|
|
124
|
+
## Integrations: df-integration
|
|
125
|
+
|
|
126
|
+
Use `operation: "add"` and a nonempty `integrations` array. Select only IDs marked available by discovery. They run in the fixed order below, regardless of request order, so later integrations see earlier staged changes.
|
|
127
|
+
|
|
128
|
+
| Integration ID | Relevant fields and conditions |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `storybook` | Shared React + Vite setup. `configureReact` is required when React is absent or another Storybook framework is configured; true aligns it with the shared preset, false skips this setup. |
|
|
131
|
+
| `rest-endpoint-generator` | Backend must have `@domain-first/handlers-rest`. `nextAdapter` applies only when `frontend.react.framework` is `next`; omitted means no Next adapter in JSON mode. Existing support files are preserved with a manual connection note as needed. |
|
|
132
|
+
| `in-memory-db` | Backend required. Enables the DB flag and restores missing support files while keeping edited files. No extra fields. |
|
|
133
|
+
| `prisma` | Backend required. `withService` defaults to true; false skips the infrastructure service and its wire. Registers `prisma` implementation choices. Existing incompatible Prisma setups are rejected rather than upgraded. |
|
|
134
|
+
| `vitest` | Backend required. `replaceTestingLibrary` is required if a different testing library is configured; true changes it to Vitest, false skips this setup. |
|
|
135
|
+
| `playwright` | No extra integration-specific fields. Adds its config, example and scripts. |
|
|
136
|
+
| `testcontainers` | Backend required. No extra fields. Reads staged Prisma/Vitest setup when selected together. Database scripts are generated, not executed. |
|
|
137
|
+
| `openapi` | Backend with `handlers-rest`. `routePrefix` defaults to `/api`; `openapiPath` is computed from the project unless supplied. `withExtractor` defaults to true. `swaggerPage` applies only with React configured and defaults to true there; otherwise omit it. |
|
|
138
|
+
| `orval` | Requires configured `handlers-rest`. `openapiPath` is read from the staged/existing OpenAPI generator when omitted. With React configured, `targets` can be a nonempty list of `hooks`/`client` and defaults to `hooks`. Without React, omit `targets`: the typed client is generated automatically. |
|
|
139
|
+
|
|
140
|
+
Fields for integrations not selected, or for conditions that do not apply, must be omitted. For example, `targets` on a non-React project and `nextAdapter` on an explicitly React project are unused parameters. If OpenAPI and Orval are selected together, a supplied `openapiPath` applies to both.
|
|
141
|
+
|
|
142
|
+
Integration flags may change their own configuration metadata as part of the authorized integration operation. They do not authorize running `df-init` or manually rewriting unrelated project settings. Install commands and notes stay in `nextSteps`; do not assume anything was installed or any project script ran.
|
|
143
|
+
|
|
144
|
+
Script conflicts require `scriptConflicts` keyed by the **original** script name. Values are `keep`, `replace`, `rename`. With `rename`, also supply `scriptNames` for that original name; the new name must be unused and valid. Supply decisions only for actual conflicts, or they are unused parameters.
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"operation": "add",
|
|
149
|
+
"integrations": ["storybook"],
|
|
150
|
+
"scriptConflicts": { "storybook": "rename" },
|
|
151
|
+
"scriptNames": { "storybook": "storybook:domain-first" }
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
For replacing generated integration files, review `dryRun: true` and apply the existing overwrite rules. Reapplying an integration may preserve edited support files instead of replacing them; inspect `messages` and `nextSteps` for manual follow-up. Do not hand-write missing integration output as a workaround.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Choosing the component for a piece of logic
|
|
2
2
|
|
|
3
|
-
The only place where these rules live. What each kind of module may depend on is the default; `rules.dependencies` in the project's config can change it (e.g. let use cases call each other), and then the config wins.
|
|
3
|
+
The only place where these rules live. What each kind of module may depend on is the default; `backend.rules.dependencies` in the project's config can change it (e.g. let use cases call each other), and then the config wins.
|
|
4
4
|
|
|
5
5
|
Split the request into pieces of logic (one responsibility each). For each piece, go through the steps **in order**: the first "yes" decides. A name the user used ("service", "gateway") is not a decision.
|
|
6
6
|
|
|
@@ -16,7 +16,7 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
16
16
|
| 6 | An entity or value object used by **several** aggregates or by a domain service? | **Entity / value object** (Domain → New Entity / New Value Object, `No aggregate`). Universal ones (see "Where it goes") in Shared Kernel |
|
|
17
17
|
| 7 | A rule about one aggregate's own state, including the junction of entities / value objects that all belong to it? | **Method on the aggregate**. No new file |
|
|
18
18
|
| 8 | One business action a user/system triggers that doesn't fit into a single query or command? (Its I/O is separate pieces.) | **Use case**. An action that is exactly one query or command gets none (see below) |
|
|
19
|
-
| 9 | Data or behavior of **another context**? | **
|
|
19
|
+
| 9 | Data or behavior of **another context**? | **Application port** in this context, with an adapter for the interaction (see below) |
|
|
20
20
|
| 10 | Leaves this context's code and storage: external system or time? | **Port** (+ adapters) |
|
|
21
21
|
| 11 | One atomic read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update)? | **Command** (write) / **query** (read) |
|
|
22
22
|
| 12 | A rule at the junction of several entities / value objects not all belonging to one aggregate (a discount from purchase history and the current discount), no I/O? | **Domain service**, always. It takes the aggregates and values it needs as arguments; loading them is the caller's job (use case, application service) |
|
|
@@ -27,17 +27,17 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
27
27
|
|
|
28
28
|
- Entities and value objects are **rich**: rules about their own data, including how they are created, are their methods. They never know about their storage or loading: that's repositories and queries/commands.
|
|
29
29
|
- Loading/saving one aggregate = a **repository method**, not a query or command.
|
|
30
|
-
- A query or command is **one atomic operation of one kind of implementation**: one
|
|
31
|
-
- **No proxy use cases.** Every query and command is a handler, so an endpoint uses it directly. A use case that only forwards the call to one query or command adds nothing: don't create it. A use case appears only when the action needs several queries, commands or ports, or logic around them. A use case whose logic lives in an application service is not a proxy: an application service has no `handle`, so the use case is how an endpoint reaches that logic.
|
|
30
|
+
- A query or command is **one atomic operation of one kind of implementation**: one operation on this context's own storage (several statements in one transaction count as one). Its implementations differ in how they perform that operation (`prisma`, `in-memory`). Neighboring contexts and external systems are reached through ports. Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in the use case that needs them; only when 2+ use cases need the same composition does it move to an application service (step 13).
|
|
31
|
+
- **No proxy use cases.** Every query and command is a handler, so an endpoint uses it directly. A use case that only forwards the call to one query or command adds nothing: don't create it. A use case appears only when the action needs several queries, commands or ports, or logic around them. An endpoint that needs a port uses a use case as its handler: ports have capability methods, not `handle`. A use case whose logic lives in an application service is not a proxy: an application service has no `handle`, so the use case is how an endpoint reaches that logic.
|
|
32
32
|
- A rule about a **set** of aggregates (uniqueness, "at most N per day") = a repository method that queries it, plus a check and a domain error in the use case. No separate component.
|
|
33
|
-
- Steps 9–10 beat 11–15. The other-context or external part becomes a
|
|
34
|
-
- Another context (step 9): input/output are this context's own models, duplicated in its terms, never the other context's.
|
|
33
|
+
- Steps 9–10 beat 11–15. The other-context or external part becomes a port. What remains may be a service that **receives it in its constructor**.
|
|
34
|
+
- Another context (step 9): input/output are this context's own models, duplicated in its terms, never the other context's. For a direct call inside the same application, a port adapter (reserved type `cross-context`) injects neighboring application queries, commands or use cases. Otherwise use the database or transport chosen by `df-ps-plan-feature` (step 3, rule 4). The test implementation returns fixed data. Imports from the neighbor are limited to the handler in the port adapter and its factory in matching wiring; its domain models and concrete implementations remain private.
|
|
35
35
|
- Another way to perform an **existing** repository, command, query or port (another storage, provider or environment) is a new implementation of it (Infrastructure → New Implementation, `units/implementation.md`), not a new contract.
|
|
36
36
|
- Don't create components "just in case": a command only when storage access deserves its own contract, an application service only when reused.
|
|
37
37
|
|
|
38
38
|
## Port or service?
|
|
39
39
|
|
|
40
|
-
- A **port** describes a capability at the boundary: an external system or time. Its adapter performs the actual interaction. Own storage still follows the repository / command / query rules above. Another context is
|
|
40
|
+
- A **port** describes a capability at the boundary: another bounded context, an external system, or time. Its adapter performs the actual interaction. Own storage still follows the repository / command / query rules above. Another context is reached through its own port in the consuming context (step 9).
|
|
41
41
|
- An **application service** contains reusable application logic and may call injected ports, commands and queries. It does not call external SDKs, HTTP clients, or another context directly. A domain service remains pure: no I/O, ports, or repositories, not even injected ones; it works with the data it is handed.
|
|
42
42
|
- Wanting to mock a class or imagining multiple implementations is not enough to make it a port. Identify the boundary capability first. Ports get swappable adapters and a test implementation under `NODE_ENV=test`; test a service's logic with fake dependencies.
|
|
43
43
|
|
|
@@ -47,8 +47,8 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
47
47
|
|
|
48
48
|
| Pair | Rule |
|
|
49
49
|
| --- | --- |
|
|
50
|
-
| Port / repository | Own aggregate's persistence → repository.
|
|
51
|
-
| Port / command, query | Own storage
|
|
50
|
+
| Port / repository | Own aggregate's persistence → repository. Another context or external system → port. |
|
|
51
|
+
| Port / command, query | Own storage → command/query. Another context or external system → port. |
|
|
52
52
|
| Port with one method / query | Decided by what's on the other side, not by the number of methods: a single read from an external system is still a port. Another context = a folder in `bounded-contexts/` of this project; any other service (another team's API, a SaaS) is an external system → port. |
|
|
53
53
|
| Query / command | A query only reads: it never changes any state, not even idempotently (no cache filling, no default settings created if missing), and never calls a command. Any state change → command. A command returns nothing or only the minimum needed to use its result later (the created order's ID), never the changed data: read that with a query. A command or query implementation depends only on infrastructure services (the database client, the HTTP client it runs on) and uses domain models; no repositories, ports, domain services or other commands and queries. Composing them is the job of a use case or an application service. |
|
|
54
54
|
| Domain service / entity, value object method | One entity / value object → its method. The junction of several → always a domain service, unless they all belong to one aggregate → a method on that aggregate. |
|
|
@@ -61,8 +61,8 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
61
61
|
## Where it goes
|
|
62
62
|
|
|
63
63
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
64
|
-
- Shared Kernel: technical, ownerless pieces (`clock`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in their own
|
|
65
|
-
- Another context's data or behavior →
|
|
64
|
+
- Shared Kernel: technical, ownerless pieces (`clock`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
|
|
65
|
+
- Another context's data or behavior → an application port in the consuming context (step 9).
|
|
66
66
|
|
|
67
67
|
## Example
|
|
68
68
|
|
|
@@ -74,9 +74,9 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
74
74
|
| Order line | 5 | `order-line.entity.ts` in `order` (used only by `order`) |
|
|
75
75
|
| Money | 6 | `domain/value-objects/money.value-object.ts` (used by `order` and `shipping-policy`) |
|
|
76
76
|
| "Can't pay twice" | 7 | `Order.pay()` |
|
|
77
|
-
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the
|
|
77
|
+
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the port |
|
|
78
78
|
| Place order, reorder | 8 | use cases `place-order`, `reorder` |
|
|
79
|
-
| Promo code check | 9 |
|
|
79
|
+
| Promo code check | 9 | port `promotions`: `cross-context` to `marketing`'s handler in the same app, or a transport adapter when deployed separately |
|
|
80
80
|
| Email, order date | 10 | ports `mailer`, `clock` (Shared Kernel) |
|
|
81
81
|
| Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
|
|
82
82
|
| Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
|
|
@@ -1,14 +1,31 @@
|
|
|
1
1
|
# df-scaffold generators: common parts
|
|
2
2
|
|
|
3
|
+
Use the JSON interface described in [agent-mode.md](agent-mode.md), with the complete operation map in [agent-operations.md](agent-operations.md). The prompt sequences below describe the legacy interactive fallback; the generated files and implementation rules apply to both modes.
|
|
4
|
+
|
|
3
5
|
What every generator shares: notation, the `Dependencies:` step, env-branched wiring and spec templates. Prompts and output of each generator are in `units/<unit>.md`.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Config paths: `project.rootFolder`, `backend.domainFirstPackages`, `backend.testingLibrary`, `backend.withInMemoryDb`, and `frontend.react.storybookFramework`. Initialization/reconfiguration is performed by the user, not the agent.
|
|
8
|
+
|
|
9
|
+
Notation: `<C>` = `<rootFolder>/bounded-contexts/<context>` or `<rootFolder>/shared-kernel`. `n` = the entered kebab-case name, `N` = PascalCase, `v` = camelCase. `I` = implementation label (`prisma` → `Prisma`). Specs are generated without a prompt **only if `backend.testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
|
|
6
10
|
|
|
7
11
|
Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Kernel"`, then the layer, then the operation (abbreviated below as `…`).
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
In interactive mode, if the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it). Without it, nothing extra is asked. Added lines (barrels, errors, wiring indexes) never trigger it.
|
|
14
|
+
|
|
15
|
+
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask the checkbox `Dependencies:`, before `Overwrite them?`. It lists wired modules of `<C>` and of the Shared Kernel (`(shared-kernel)` suffix), grouped under headers in this order: Repositories, Domain services, Ports, Application services, Queries, Commands, Use cases, Infrastructure services, Presentation services. Inside a group: by type name, `<C>` first. Headers are not counted: `toggle:<n,..>` numbers only modules, top to bottom. Answer `toggle:<n,..>` or `none`. It is skipped when nothing fits, so check `<C>/wiring/`, `<rootFolder>/shared-kernel/wiring/` and neighboring contexts' `wiring/` before counting steps. What fits depends on the layer of the class the wire builds: domain → domain; application → domain, application; infrastructure (repository, command/query, and port implementations, infrastructure services) → domain, application ports (of `<C>` and the Shared Kernel; no other application modules), infrastructure; presentation → application, presentation. On top of that, domain services see only domain services (no repositories), application services see only ports, commands and queries from application, use cases never see use cases, repository implementations never see repositories, command/query implementations see only infrastructure services locally and in the Shared Kernel. Only port adapters under `infrastructure/application-adapters/cross-context/` also see neighboring queries, commands and use cases labelled `(<context>)`. Query/command implementations have no cross-context exception. Imports and constructor names get context-qualified aliases. This cross-context exception is fixed and does not expose foreign models, infrastructure or other kinds; other labels keep context isolation. The wire checks each implementation separately, even when several types share its imports. Leave test implementations independent. These are the defaults: `backend.rules.dependencies` in the config changes them per kind (`use-cases`, `queries`, …), so count items from what the project's rules allow. Endpoints are never listed. Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order. An env-branched wire (repository, command/query, port) wires each implementation in isolation: instead of `Dependencies:` it asks `Dependencies for <Implementation>:` once per implementation, in the order of the wire (main, then test). Each list leaves out only what that implementation already has, and a list with nothing to choose is skipped. It may start with a `Suggested` group: infrastructure modules whose file name has the implementation label (its folder, e.g. `prisma`, `in-memory`) as whole words, such as `in-memory-db-infrastructure-service` for `in-memory`. They are listed there only, so numbering starts with them, and they are **checked**: `none` keeps them, `toggle:<n>` on one of them unchecks it.
|
|
16
|
+
|
|
17
|
+
## Remembered and system implementation types
|
|
18
|
+
|
|
19
|
+
In interactive mode, implementation prompts are selects. JSON requests use explicit `implementation` / `testImplementation` objects, each with `type` and optional `save`. Read the shared config’s `backend.implementations` section. Categories (`repositories`, `commands`, `queries`, `ports`) and `primary`/`test` lists are independent. Menus contain the relevant saved list, active system implementations and both manual-entry actions. There are no ordinary `api` or `mock` presets. Saved types display their exact name; the first available one is the default, then an available system type, otherwise the save-entry action with an empty input.
|
|
20
|
+
|
|
21
|
+
Active system choices are explicitly labelled:
|
|
22
|
+
|
|
23
|
+
- `System: cross-context (calls handlers in another bounded context)` — only port adapters with at least one neighboring context, never Shared Kernel ports.
|
|
24
|
+
- `System: in-memory (uses the shared in-memory database)` — only repositories, commands and queries when `backend.withInMemoryDb` is enabled and its service and required wire exist. The DB is still a suggested dependency with wiring. Inactive `in-memory` and port adapters named `in-memory` are ordinary types, not automatic choices.
|
|
25
|
+
|
|
26
|
+
Use `"pick:System: cross-context"` or `"pick:System: in-memory"` for those menu prefixes. Saved system labels retain the marker and are not duplicated. **New Implementation** merges primary/test history and available system choices, without introducing ordinary presets.
|
|
10
27
|
|
|
11
|
-
|
|
28
|
+
The two manual actions are `Enter implementation type and save for future use` and `Enter implementation type for this run only`, each followed by a separate text input. Saving stages a new ordinary label in the config’s `backend.implementations` section; run-only entry leaves it unchanged. Both generate source files. This distinction also applies to **New Implementation** after environments are selected. Include the JSON file in generated-file lists when saving a new type; cancellation discards its update too.
|
|
12
29
|
|
|
13
30
|
## Env-branched wiring {wire}
|
|
14
31
|
|
|
@@ -4,14 +4,15 @@ When: a thing with identity, lifecycle, and rules about its own state, owned by
|
|
|
4
4
|
|
|
5
5
|
## Generate (context only)
|
|
6
6
|
|
|
7
|
-
Prompts: name → `With Repository` →
|
|
7
|
+
Prompts: name → `With Repository` → primary implementation select → `Add a test implementation` → test implementation select if yes → {wire} dependencies per implementation. Each select contains saved repository types for that role, available system types and both manual-entry actions (`../generators.md`). `System: in-memory (uses the shared in-memory database)` appears only with the shared DB enabled and scaffolded. There are no ordinary presets; default to the first available saved/system choice, otherwise manual entry.
|
|
8
8
|
|
|
9
|
-
`… pick:Domain "pick:New Aggregate" text:order yes
|
|
9
|
+
`… pick:Domain "pick:New Aggregate" text:order yes "pick:Enter implementation type and save for future use" text:prisma yes "pick:System: in-memory"` (with the shared DB ready; otherwise enter the test type manually).
|
|
10
10
|
|
|
11
|
+
- Custom types entered with the save action are staged in the shared config under `backend.implementations.repositories.primary` or `backend.implementations.repositories.test` and offered on later runs, including in other contexts. Both manual-entry actions from `../generators.md` are available; the run-only action generates the repository without remembering its type.
|
|
11
12
|
- `<C>/domain/aggregates/n/`: `n.aggregate-root.ts` (`class N extends domainType()` {types}), `index.ts`, spec; with repository: `n-repository.ts` (`abstract class NRepository`), spec
|
|
12
13
|
- `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
|
|
13
14
|
- {wire} `<C>/wiring/repositories/wire-n-repository.ts` (env-branched)
|
|
14
|
-
- With `withInMemoryDb` in the config, the `in-memory` implementation can keep its section of the DB: `private readonly data: InMemoryDbInfrastructureService['ns']`, set in the constructor from its `inMemoryDbInfrastructureService` parameter; `ns = this.section<N>('NS');` is added to `<rootFolder>/shared-kernel/infrastructure/services/in-memory-db-infrastructure-service.ts` if missing (`N` needs an `id`). Without {wire} this always happens. {wire} `Dependencies for InMemoryNRepository:` lists the DB under `Suggested`, checked: kept, it gets the section and `wireInMemoryDbInfrastructureService` in its `wireClass`; unchecked, the implementation stays empty (`constructor() {}`) and no section is added.
|
|
15
|
+
- With `backend.withInMemoryDb` in the config, the `in-memory` implementation can keep its section of the DB: `private readonly data: InMemoryDbInfrastructureService['ns']`, set in the constructor from its `inMemoryDbInfrastructureService` parameter; `ns = this.section<N>('NS');` is added to `<rootFolder>/shared-kernel/infrastructure/services/in-memory-db-infrastructure-service.ts` if missing (`N` needs an `id`). Without {wire} this always happens. {wire} `Dependencies for InMemoryNRepository:` lists the DB under `Suggested`, checked: kept, it gets the section and `wireInMemoryDbInfrastructureService` in its `wireClass`; unchecked, the implementation stays empty (`constructor() {}`) and no section is added.
|
|
15
16
|
|
|
16
17
|
Its entities and value objects come after it: [entity-value-object](entity-value-object.md), picking this aggregate.
|
|
17
18
|
|
|
@@ -10,4 +10,4 @@ Name: a business area in kebab-case (`sales`, `reviews`), not a feature.
|
|
|
10
10
|
|
|
11
11
|
## Implement
|
|
12
12
|
|
|
13
|
-
Nothing to fill in. Everything inside comes from the other units.
|
|
13
|
+
Nothing to fill in. Everything inside comes from the other units. Domain and application stay isolated; cross-context port adapters may reach neighboring application handlers through their matching wiring (`df-ps-implement`, "Bounded context isolation").
|
|
@@ -1,31 +1,31 @@
|
|
|
1
1
|
# Command and query
|
|
2
2
|
|
|
3
|
-
When (`../choosing-components.md`,
|
|
3
|
+
When (`../choosing-components.md`, step 11): one atomic read/write on this context's own storage that is not "load/save one aggregate" (read model, report, bulk update). Another context or external system is reached through a port (`port.md`).
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
- A query only reads: it never changes any state, not even idempotently
|
|
7
|
-
- Another context: input/output are this context's own models, duplicated in its terms. The implementation reaches it the simplest available way: a shared database → directly (the persistence label, e.g. `prisma`); otherwise the way chosen in the plan (`df-ps-plan-feature`, step 3, rule 4), by default its REST endpoint (`http`). No imports from the other context.
|
|
5
|
+
- One atomic operation of one kind of storage implementation: several statements in one transaction count as one. Several operations, a mix of storages, or logic between steps → several queries/commands, composed in a use case.
|
|
6
|
+
- A query only reads: it never changes any state, not even idempotently, and never calls a command. A command returns nothing or the minimum needed to use its result later (e.g. a created ID); read changed data with a query.
|
|
8
7
|
|
|
9
8
|
## Generate (context only)
|
|
10
9
|
|
|
11
|
-
Prompts: name → implementation
|
|
10
|
+
Prompts: name → primary implementation select → `Add a test implementation` → test implementation select if yes → {wire} dependencies per implementation. Menus contain saved types from `commands` or `queries` for the selected role, active system types and both manual-entry actions (`../generators.md`). Only `System: in-memory (uses the shared in-memory database)` can be automatic here, when its integration is ready. `api` and `mock` must be saved or entered manually. The first saved/system choice is the default, otherwise manual entry without a suggested name. Saving stages the new ordinary label for that category/role; run-only input leaves the catalog unchanged.
|
|
12
11
|
|
|
13
|
-
`… pick:Application "pick:New Command" text:place-order
|
|
14
|
-
`… pick:Application "pick:New Query" text:order-summary
|
|
12
|
+
`… pick:Application "pick:New Command" text:place-order "pick:Enter implementation type and save for future use" text:prisma yes "pick:System: in-memory"` (with the shared DB ready).
|
|
13
|
+
`… pick:Application "pick:New Query" text:order-summary "pick:Enter implementation type for this run only" text:sql no`
|
|
15
14
|
|
|
16
15
|
- `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
17
16
|
- `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
|
|
18
17
|
- {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
|
|
19
|
-
- With `withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
|
|
18
|
+
- With `backend.withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
|
|
20
19
|
|
|
21
20
|
Queries: the same with `query` / `queries`.
|
|
22
21
|
|
|
23
22
|
## Implement
|
|
24
23
|
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
24
|
+
- Queries and commands never import neighboring contexts. `cross-context` is reserved for port adapters and is unavailable here, including as a custom label.
|
|
25
|
+
- {handlers} The abstract contract holds static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes its `handler` callback.
|
|
26
|
+
- An implementation performs its one operation with no business logic or surrounding steps. Its wired dependencies are infrastructure services (the database client it runs on); repositories, ports, domain services and other queries/commands stay with the consuming use case.
|
|
27
|
+
- Input/output use this context's domain models; time comes through input, never through the clock port.
|
|
28
|
+
- An `in-memory` implementation works on the in-memory DB when configured; `mock`/`stub` implementations may return fixed data.
|
|
29
29
|
|
|
30
30
|
## Test
|
|
31
31
|
|