@domain-first/project-structure 8.6.1 → 8.7.1
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 +1 -1
- package/bin/df-skills.mjs +55 -9
- package/dist/287.js +44 -138
- package/dist/38.js +36 -0
- package/dist/561.js +9 -1
- package/dist/947.js +11 -1
- package/dist/agent-cli.d.ts +9 -2
- package/dist/agent-principles.cjs +116 -0
- package/dist/agent-principles.d.ts +9 -0
- package/dist/agent-principles.js +64 -0
- package/dist/agent-principles.spec.d.ts +1 -0
- package/dist/agent-requests.d.ts +16 -2
- package/dist/graph.cjs +10 -0
- package/dist/in-memory-db.d.ts +1 -6
- package/dist/index.cjs +64 -137
- package/dist/index.js +4 -1
- package/dist/init.cjs +12 -21
- package/dist/integration.cjs +61 -137
- package/dist/lint.cjs +46 -0
- package/dist/react.cjs +61 -137
- package/dist/use-cases/add-integration.d.ts +1 -1
- package/dist/use-cases/index.d.ts +1 -0
- package/dist/use-cases/scaffold-new-infrastructure-helper.d.ts +7 -0
- package/dist/wiring.d.ts +2 -2
- package/package.json +3 -2
- package/principles/df-principles.md +33 -0
- package/skills/df-ps-implement/SKILL.md +26 -1
- package/skills/df-ps-plan-feature/SKILL.md +22 -18
- package/skills/df-ps-react/SKILL.md +2 -9
- package/skills/df-ps-react/references/generators.md +9 -9
- package/skills/df-ps-scaffold/SKILL.md +20 -126
- package/skills/df-ps-scaffold/references/agent-mode.md +2 -2
- package/skills/df-ps-scaffold/references/agent-operations.md +1 -0
- package/skills/df-ps-scaffold/references/choosing-components.md +65 -49
- package/skills/df-ps-scaffold/references/generators.md +33 -11
- package/skills/df-ps-scaffold/references/units/aggregate.md +3 -5
- package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
- package/skills/df-ps-scaffold/references/units/command-query.md +6 -8
- package/skills/df-ps-scaffold/references/units/delete.md +0 -2
- package/skills/df-ps-scaffold/references/units/endpoint.md +1 -4
- package/skills/df-ps-scaffold/references/units/entity-value-object.md +0 -4
- package/skills/df-ps-scaffold/references/units/errors.md +0 -4
- package/skills/df-ps-scaffold/references/units/helper.md +30 -0
- package/skills/df-ps-scaffold/references/units/implementation.md +1 -5
- package/skills/df-ps-scaffold/references/units/move-or-rename.md +0 -4
- package/skills/df-ps-scaffold/references/units/port.md +3 -6
- package/skills/df-ps-scaffold/references/units/services.md +4 -6
- package/skills/df-ps-scaffold/references/units/use-case.md +1 -2
- package/skills/df-ps-scaffold/references/units/wire-dependency.md +0 -2
- package/skills/df-ps-scaffold/references/work-plan.md +73 -0
- package/skills/df-ps-scaffold/scripts/drive.mjs +0 -252
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
# df-react generators: operations and output
|
|
2
2
|
|
|
3
|
-
Prefer JSON requests; [agent operations](../../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) maps all six React operations and fields.
|
|
3
|
+
Prefer JSON requests; [agent operations](../../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) maps all six React operations and fields. Generated files and story templates apply to both modes.
|
|
4
4
|
|
|
5
5
|
Settings: `project.rootFolder` and `frontend.react.storybookFramework`. The frontend section must be configured by the user before these runs.
|
|
6
6
|
|
|
7
|
-
Notation: `…/react/` = `<rootFolder>/presentation/react/`. `n` = the entered kebab-case name, `N` = PascalCase.
|
|
7
|
+
Notation: `…/react/` = `<rootFolder>/presentation/react/`. `n` = the entered kebab-case name, `N` = PascalCase. If the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it).
|
|
8
8
|
|
|
9
9
|
## New page
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
`…/react/pages/n-page.tsx`; with Next.js (`frontend.react.framework: next`) also `app/n/page.tsx` (`src/app/…` when that folder exists) rendering `NPage`, unless that route already exists. A nested name nests the route too: `admin/users` → `app/admin/users/page.tsx`.
|
|
12
12
|
|
|
13
13
|
## New widget
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
`…/react/widgets/n/`:
|
|
16
16
|
|
|
17
17
|
- `with separated ui` (default): `n-widget.tsx`, `types.ts`, `ui/n-widget-ui.tsx`, `hooks/use-n-ui-model.ts`; with `storybookFramework`: `ui/n-widget-ui.stories.tsx` (CSF3: `meta` with `title: 'Widgets/N'`, `component: NWidgetUI`, story `Default`)
|
|
18
18
|
- `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
|
|
@@ -23,19 +23,19 @@ Page and widget names may have folders before them: `text:admin/panel/users` →
|
|
|
23
23
|
|
|
24
24
|
## Move or rename page / widget
|
|
25
25
|
|
|
26
|
-
Move or rename a page or a widget only with df-react, never by hand
|
|
26
|
+
Move or rename a page or a widget only with df-react, never by hand (JSON `move-widget`, `move-page`). It moves the widget folder (or the page with its `<name>-page.*` files), renames files and `<Name>Widget…` / `use<Name>UIModel` / `<Name>Page…` to the new name, updates a generated story title and every import of the module (relative and `tsconfig` aliases; importers of barrels re-exporting it get the renamed classes), and fixes relative imports inside it. Before `Apply?` it prints the files to move and to update; check them. An existing target or a move into itself is rejected.
|
|
27
27
|
|
|
28
28
|
## Move, rename or delete a UI-kit component / shared hook
|
|
29
29
|
|
|
30
|
-
The same runs exist for them
|
|
30
|
+
The same runs exist for them (`move-ui-kit-component`, `move-shared-hook`, `delete-ui-kit-component`, `delete-shared-hook`). Names have no folders; a hook's name is entered without `use-`. A move renames the folder or `use-<name>.*` files, `<Name>` / `<Name>Props` / `use<Name>`, the `UI-kit/<Name>` story title and every import; a delete is refused while other files import the module.
|
|
31
31
|
|
|
32
32
|
## Delete page / widget
|
|
33
33
|
|
|
34
|
-
Delete a page or a widget only with df-react
|
|
34
|
+
Delete a page or a widget only with df-react (JSON `delete-widget`, `delete-page`; with Next.js and the page's own route, whether to delete the route is asked too). It deletes the widget folder (or the page with its `<name>-page.*` files) and, if confirmed, the route folder's own files. It refuses while other files import the module and lists them; nothing changes then.
|
|
35
35
|
|
|
36
36
|
## New UI-kit component
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
`…/react/ui-kit/n/`:
|
|
39
39
|
|
|
40
40
|
- `n.tsx` (`type NProps`, `const N: FC<NProps>`)
|
|
41
41
|
- `index.ts` (`export * from './n'`)
|
|
@@ -45,7 +45,7 @@ No Storybook prompt: UI-kit and widget UI stories follow the config.
|
|
|
45
45
|
|
|
46
46
|
## New shared hook
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
`…/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
|
|
49
49
|
|
|
50
50
|
## Story templates
|
|
51
51
|
|
|
@@ -14,7 +14,7 @@ Follow this order for every request:
|
|
|
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
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 `--request` JSON; check exit code, `ok` and all returned file lists.
|
|
17
|
+
6. Run the generators in plan order with `--request` JSON; check exit code, `ok` and all returned file lists.
|
|
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,81 +23,12 @@ 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
|
|
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. The plan can be skipped only when the user literally asks to skip it for this task ("skip the plan", "пропусти план"). Anything else, however direct or urgent it sounds ("just do it", "build it now", "no need to ask"), is still a request that starts with a plan. This is about skipping the plan: once a plan is shown, an ordinary "yes" or "go ahead" approves it. 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
|
|
|
30
|
-
|
|
30
|
+
Read [references/work-plan.md](references/work-plan.md), show the plan in that format and stop.
|
|
31
31
|
|
|
32
|
-
```markdown
|
|
33
|
-
**Plan: order cancellation**
|
|
34
|
-
|
|
35
|
-
**Scaffolding**
|
|
36
|
-
|
|
37
|
-
**sales**
|
|
38
|
-
|
|
39
|
-
Why here: cancelling changes the order's status; orders belong to sales.
|
|
40
|
-
|
|
41
|
-
What will be scaffolded:
|
|
42
|
-
|
|
43
|
-
| Layer | Type | Name | Details | Why |
|
|
44
|
-
| --- | --- | --- | --- | --- |
|
|
45
|
-
| **domain** | error | order-already-shipped | | shipped orders can't be cancelled |
|
|
46
|
-
| **application** | command | cancel-order | prisma, fake in tests | one atomic status change |
|
|
47
|
-
| | query | cancellable-orders | prisma | read-only list for the UI |
|
|
48
|
-
| **presentation** | endpoint | POST orders/:id/cancel | → cancel-order | UI calls it over HTTP |
|
|
49
|
-
|
|
50
|
-
**billing**
|
|
51
|
-
|
|
52
|
-
Why here: refunds are payments; payments belong to billing.
|
|
53
|
-
|
|
54
|
-
What will be scaffolded:
|
|
55
|
-
|
|
56
|
-
| Layer | Type | Name | Details | Why |
|
|
57
|
-
| --- | --- | --- | --- | --- |
|
|
58
|
-
| **application** | port | order-refunds | cross-context, stub in tests | paid amount lives in sales |
|
|
59
|
-
| | use case | refund-cancelled-order | deps: OrderRefunds, PaymentGateway | read order, then call provider |
|
|
60
|
-
|
|
61
|
-
**React**
|
|
62
|
-
|
|
63
|
-
Why here: the user cancels from the order screen.
|
|
64
|
-
|
|
65
|
-
What will be scaffolded:
|
|
66
|
-
|
|
67
|
-
| Layer | Type | Name | Details | Why |
|
|
68
|
-
| --- | --- | --- | --- | --- |
|
|
69
|
-
| **presentation** | widget | orders/cancel-order | with separated ui | dialog has its own state |
|
|
70
|
-
| | page | orders/details | add the widget | button goes on this screen |
|
|
71
|
-
|
|
72
|
-
**Writing by hand**
|
|
73
|
-
- cancel-order: input { orderId }, output { status }
|
|
74
|
-
- prisma implementation: update status, throw OrderAlreadyShipped
|
|
75
|
-
- endpoint: :id → orderId, OrderAlreadyShipped → 409
|
|
76
|
-
- order-refunds adapter: sales:OrderSummaryQuery result → RefundableAmount
|
|
77
|
-
|
|
78
|
-
**Running**
|
|
79
|
-
- after the endpoint: npm run openapi && npm run client:orval
|
|
80
|
-
|
|
81
|
-
**Question**
|
|
82
|
-
1. Refund right on cancel, or after a manager confirms?
|
|
83
|
-
|
|
84
|
-
Reply "ok" to start.
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
- Write the plan in the user's language (headings and sentences); module names, types, commands and paths stay as in the code. Omit empty sections.
|
|
88
|
-
- **Scaffolding** has one block per owner, in run order: new contexts first, marked `(new)` (and `(provisional)` with the reason when ownership is a reversible default), then existing contexts, `shared-kernel`, React last.
|
|
89
|
-
- **Why here**: one short sentence on why this owner, not another: the data or rule the context owns; for `shared-kernel`, why several contexts share it; for React, why the UI changes.
|
|
90
|
-
- **What will be scaffolded**: one table per owner, one row per `df-scaffold`/`df-react` run. Layers in order domain → application → infrastructure → presentation, the layer in bold only on its first row. Repositories go with their aggregate in domain; commands, queries and ports in application (their implementations are Details); endpoints and React modules in presentation.
|
|
91
|
-
- **Type**: the unit: aggregate, entity, value object, error, error namespace, service, port, command, query, use case, implementation, endpoint, wire dependency, move, delete; for React: page, widget, ui-kit component, hook, page move, widget move, ui-kit component move, hook move, page delete, widget delete, ui-kit component delete, hook delete.
|
|
92
|
-
- **Name**: the entered name; for a move `old → new`; for an implementation the contract; for wire dependency the module.
|
|
93
|
-
- **Details**: only what changes behavior: implementation types (`(saved)` when saved for future runs), the test implementation, dependencies (`deps: OrderRepository`), environments, widget type, the endpoint's handler, whether a Next.js route moves (`route moves: /a → /b`). No file paths, no CLI menu paths.
|
|
94
|
-
- **Why**: at most six words: why this kind of module (`choosing-components.md`).
|
|
95
|
-
- **Writing by hand**: members, schemas, mappings. Not full code.
|
|
96
|
-
- **Running**: 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.
|
|
97
|
-
- **Overwrites**, only when a run would replace existing files (`overwriteRequired` of a `dryRun`): list those files.
|
|
98
|
-
- **Exception requests**, only for hand-created files: `<path>` (rule 2, #n) with the reason. Any other file needs its own request with a reason.
|
|
99
|
-
- **Question**, only for open decisions that change structure or domain behavior. Open questions block approval: answers first, then the updated plan.
|
|
100
|
-
- The last line says what reply starts the work.
|
|
101
32
|
- Approval must be explicit ("ok", "да", "делай"…). A question or silence isn't approval. Changes to the plan → show the updated plan and ask again.
|
|
102
33
|
- After approval, do exactly the plan. An extra module or file, or a different name/option → stop and get the delta approved. Edits to existing files needed along the way don't need approval; list them in the final report.
|
|
103
34
|
|
|
@@ -105,19 +36,19 @@ Reply "ok" to start.
|
|
|
105
36
|
|
|
106
37
|
Every new file is created by `df-scaffold` (React modules: `df-react`). Don't create files with the Write tool, `touch`, redirects, or by copying templates. The only exceptions (`<C>` = `<rootFolder>/bounded-contexts/<context>`):
|
|
107
38
|
|
|
108
|
-
| #
|
|
109
|
-
| --- |
|
|
110
|
-
| 1
|
|
111
|
-
| 2
|
|
112
|
-
| 3
|
|
113
|
-
| 4
|
|
114
|
-
| 5
|
|
39
|
+
| # | Files | Location | Condition |
|
|
40
|
+
| --- | --- | --- | --- |
|
|
41
|
+
| 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
|
|
42
|
+
| 2 | Output of project tools | where the tool puts it | Migrations, codegen: run the project's script, use its output as-is; never hand-write or edit it. No approval needed for these files. |
|
|
43
|
+
| 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-react. |
|
|
44
|
+
| 4 | Widget/page/UI-kit support files | inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.tsx`, `*.stories.tsx`; next to a page: `pages/<name>-page.module.css`, for a nested page in its folder (`pages/admin/admin-users-page.module.css`) (layout of its widgets only) | Widget/page/UI-kit component generated by df-react. Details and story templates: `df-ps-react`. |
|
|
45
|
+
| 5 | App bootstrap and config | outside `<rootFolder>/{bounded-contexts,shared-kernel,presentation}/`: entry point, HTTP server setup registering `restHandlers`, tool configs | Bootstrapping only. Domain/application/infrastructure logic never goes there. |
|
|
115
46
|
|
|
116
|
-
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.
|
|
47
|
+
Anything else (helpers, types, constants, mappers, wiring, barrels): put it in an existing generated file, or generate a component that can host it. Stateless technical code of the infrastructure layer (mappers included) is an infrastructure helper, generated with `New Helper` (`references/units/helper.md`). Editing existing files is fine. If neither works, request an exception for that exact file.
|
|
117
48
|
|
|
118
|
-
If the CLI cannot run, report the failure and give the user the prepared JSON command to run themselves
|
|
49
|
+
If the CLI cannot run, report the failure and give the user the prepared JSON command to run themselves. Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
|
|
119
50
|
|
|
120
|
-
Moving
|
|
51
|
+
Moving, renaming and deleting a module go through the CLI too, never by hand, and need an approved plan: `references/units/move-or-rename.md`, `references/units/delete.md`; pages and widgets: `df-ps-react`.
|
|
121
52
|
|
|
122
53
|
### 3. New dependencies only through df-scaffold
|
|
123
54
|
|
|
@@ -125,8 +56,7 @@ With `@domain-first/wire`, every new dependency of a wired class (a constructor
|
|
|
125
56
|
|
|
126
57
|
- List each module's dependencies in its plan row's Details (`deps: OrderRepository`); for an existing module, add a `wire dependency` row.
|
|
127
58
|
- 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.
|
|
128
|
-
- A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service
|
|
129
|
-
- An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
|
|
59
|
+
- A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service (`references/units/services.md`). A domain or application module never gets such a value directly: it depends on a port whose adapter uses the service.
|
|
130
60
|
|
|
131
61
|
### 4. Cross-context calls stay in application port adapters
|
|
132
62
|
|
|
@@ -134,7 +64,7 @@ Details and the check script: `df-ps-implement`, "Bounded context isolation".
|
|
|
134
64
|
|
|
135
65
|
## Units
|
|
136
66
|
|
|
137
|
-
One file per unit in `references/units/`: when to choose it, how to generate it (prompts,
|
|
67
|
+
One file per unit in `references/units/`: when to choose it, how to generate it (prompts, output), how to implement and test it. Read `references/generators.md` first: it holds what all generators share (the notation the unit files use, `Dependencies:`, env-branched wiring, spec templates). Then read only the files of the units in the plan. `references/choosing-components.md` decides between units.
|
|
138
68
|
|
|
139
69
|
| Unit | File | Menu |
|
|
140
70
|
| --- | --- | --- |
|
|
@@ -143,6 +73,7 @@ One file per unit in `references/units/`: when to choose it, how to generate it
|
|
|
143
73
|
| Entity, value object | `entity-value-object.md` | Domain → New Entity / New Value Object |
|
|
144
74
|
| Errors | `errors.md` | Domain → Errors |
|
|
145
75
|
| Domain, application, infrastructure, presentation service | `services.md` | <Layer> → New Service |
|
|
76
|
+
| Infrastructure helper (mapper, query builder, error translator) | `helper.md` | Infrastructure → New Helper |
|
|
146
77
|
| Use case | `use-case.md` | Application → New Use Case |
|
|
147
78
|
| Command, query | `command-query.md` | Application → New Command / New Query |
|
|
148
79
|
| Port + adapters | `port.md` | Application → New Port |
|
|
@@ -155,52 +86,15 @@ One file per unit in `references/units/`: when to choose it, how to generate it
|
|
|
155
86
|
|
|
156
87
|
## Preparing runs
|
|
157
88
|
|
|
158
|
-
- **Contexts**: subfolders of `<rootFolder>/bounded-contexts
|
|
89
|
+
- **Contexts**: subfolders of `<rootFolder>/bounded-contexts/`.
|
|
159
90
|
- **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`).
|
|
160
91
|
- **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?`.
|
|
161
|
-
- **Tests**: with `backend.testingLibrary` set, df-scaffold
|
|
162
|
-
- **
|
|
92
|
+
- **Tests**: with `backend.testingLibrary` set, df-scaffold generates specs for modules without infrastructure (domain model, non-infrastructure services, use cases); repositories, commands/queries, ports, infrastructure services and helpers get none. Add a test implementation (`in-memory`/`mock`) to repositories, commands/queries and ports, so `NODE_ENV=test` specs of the use cases that inject them don't touch real infrastructure. Without `backend.testingLibrary`, tell the user once and suggest adding it with `! npx df-integration` (Vitest); don't edit the config yourself.
|
|
93
|
+
- **Run order** in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → new implementations of existing contracts → endpoints → React (`df-ps-react`).
|
|
94
|
+
- **Requests**: take the unit semantics and output files from its reference, then use `--describe` and `references/agent-mode.md` to build a JSON request.
|
|
163
95
|
|
|
164
96
|
## Running non-interactively
|
|
165
97
|
|
|
166
98
|
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).
|
|
167
99
|
|
|
168
100
|
Initialization remains a human task. No JSON initialization workflow is provided.
|
|
169
|
-
|
|
170
|
-
## Legacy interactive driver
|
|
171
|
-
|
|
172
|
-
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`).
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
node <this-skill-dir>/scripts/drive.mjs [--bin df-react] [--cwd <dir>] [--delay <ms>] <step>...
|
|
176
|
-
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
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
| Step | Prompt | Effect |
|
|
180
|
-
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
181
|
-
| `pick:<label>` | select | Types a **prefix of the choice text** + Enter. Aborts before submitting if the highlighted choice doesn't match. |
|
|
182
|
-
| `text:<v>` | input | Types a value. |
|
|
183
|
-
| `default` | input/select | Accepts the suggested input value or the highlighted default choice. |
|
|
184
|
-
| `yes` / `no` | confirm | |
|
|
185
|
-
| `toggle:1,3` / `none` | checkbox | `Dependencies:`, `Dependencies for <Implementation>:`. `Suggested` items come checked: toggling unchecks. |
|
|
186
|
-
|
|
187
|
-
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.
|
|
188
|
-
|
|
189
|
-
Custom types entered with the save action update `backend.implementations` in `domain-first.project-structure.config.json`; mark the type `(saved)` in the plan row's Details. 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.
|
|
190
|
-
|
|
191
|
-
Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the files its unit file lists for the planned options. "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's Overwrites didn't list: show the user the listed files and ask, never just add `yes`. If prompts get out of sync, retry with `--delay 1200`.
|
|
192
|
-
|
|
193
|
-
## Menu map
|
|
194
|
-
|
|
195
|
-
| Layer | Bounded context | Shared Kernel |
|
|
196
|
-
| -------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
|
|
197
|
-
| Domain | New Aggregate, New Entity, New Value Object, Errors, New Service | New Entity, New Value Object, Errors, New Service |
|
|
198
|
-
| Application | New Query, New Command, New Use Case, New Port, New Service | New Port, New Service |
|
|
199
|
-
| Infrastructure | New Service, New Implementation | New Service, New Implementation |
|
|
200
|
-
| Presentation | New Handlers-REST Endpoint (needs handlers-rest), New Service | New Service |
|
|
201
|
-
|
|
202
|
-
With `@domain-first/wire`, the layer menu of a context and of the Shared Kernel also has `Wire dependency`: it adds dependencies to an existing wired module. Every layer menu has `Move or rename` and `Delete`.
|
|
203
|
-
|
|
204
|
-
The main menu also has `Scaffold new bounded context`. React modules come from a separate CLI, `df-react`: see `df-ps-react`.
|
|
205
|
-
|
|
206
|
-
Run order in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → new implementations of existing contracts → endpoints → React (`df-ps-react`).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Non-interactive operations for agents
|
|
2
2
|
|
|
3
|
-
Prefer the JSON interface for `df-scaffold`, `df-react` and `df-integration`.
|
|
3
|
+
Prefer the JSON interface for `df-scaffold`, `df-react` and `df-integration`. Initialization (`df-init`) remains a human task. The same plan, file creation and dependency rules apply to both interfaces.
|
|
4
4
|
|
|
5
5
|
For the complete operation map, conditional integration fields and recipes, read [agent-operations.md](agent-operations.md) for the work at hand.
|
|
6
6
|
|
|
@@ -12,7 +12,7 @@ npx df-react --describe
|
|
|
12
12
|
npx df-integration --describe
|
|
13
13
|
```
|
|
14
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
|
|
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. If the installed CLI doesn't support these flags, ask the owner to upgrade the package; don't upgrade it yourself. Without a config it still describes the protocol; ask the owner to initialize missing sections.
|
|
16
16
|
|
|
17
17
|
- `project.contexts[].name`: a bounded context or the reserved `shared-kernel` context.
|
|
18
18
|
- `modules[].id`: qualified dependency ID, e.g. `shared-kernel:PrismaInfrastructureService` or `billing:InvoiceQuery`.
|
|
@@ -19,6 +19,7 @@ All operations support `dryRun` and `overwrite`. Except `bounded-context`, they
|
|
|
19
19
|
| `domain-service` | `name` | `dependencies`, when wiring is configured and eligible modules exist. |
|
|
20
20
|
| `application-service` | `name` | `dependencies`, with the same conditions. |
|
|
21
21
|
| `infrastructure-service` | `name` | `dependencies`, with the same conditions. |
|
|
22
|
+
| `helper` | `name`, `implementationType` | `name` may hold folders: `mappers/social-network-type`. `implementationType` is a saved or system type. See [the helper unit](units/helper.md). |
|
|
22
23
|
| `presentation-service` | `name` | `dependencies`, with the same conditions. |
|
|
23
24
|
| `use-case` | `name` | `dependencies`. Bounded contexts only. |
|
|
24
25
|
| `command` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |
|
|
@@ -6,27 +6,27 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
6
6
|
|
|
7
7
|
## Procedure
|
|
8
8
|
|
|
9
|
-
| #
|
|
10
|
-
| --- |
|
|
11
|
-
| 1
|
|
12
|
-
| 2
|
|
13
|
-
| 3
|
|
14
|
-
| 4
|
|
15
|
-
| 5
|
|
16
|
-
| 6
|
|
17
|
-
| 7
|
|
18
|
-
| 8
|
|
19
|
-
| 9
|
|
20
|
-
| 10
|
|
21
|
-
| 11
|
|
22
|
-
| 12
|
|
23
|
-
| 13
|
|
24
|
-
| 14
|
|
25
|
-
| 15
|
|
26
|
-
| —
|
|
9
|
+
| # | Question | Component |
|
|
10
|
+
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| 1 | A business failure callers must recognize? | **Errors** (Domain → Errors) |
|
|
12
|
+
| 2 | An HTTP entry point? | **REST endpoint** (Presentation; needs handlers-rest) |
|
|
13
|
+
| 3 | A screen, UI block, or app-wide React hook? | **React page / widget / UI-kit component / shared hook**. Which one: `df-ps-react` |
|
|
14
|
+
| 4 | A thing with identity, lifecycle, and rules about its own state, **owned by this context** and stored on its own? | **Aggregate** (+ repository) |
|
|
15
|
+
| 5 | An entity or value object used **only inside one** aggregate (an entity inside it, or a value like `order-id` used only by `order`)? | **Entity / value object** (Domain → New Entity / New Value Object, pick that aggregate) |
|
|
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
|
+
| 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
|
+
| 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**? | **Application port** in this context, with an adapter for the interaction (see below) |
|
|
20
|
+
| 10 | Leaves this context's code and storage: external system or time? | **Port** (+ adapters) |
|
|
21
|
+
| 11 | One atomic read/write on this context's own storage that doesn't load aggregates to change them or check their rules (read model, data for a reader, report, bulk update)? | **Command** (write) / **query** (read) |
|
|
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) |
|
|
23
|
+
| 13 | Application logic reused by 2+ use cases, with any external interaction or storage access delegated to injected ports, commands or queries? | **Application service** |
|
|
24
|
+
| 14 | A technical helper used only by infrastructure code? | Stateless, no dependencies and for one implementation type (mapper, query builder, error translator): **Infrastructure helper**. Otherwise, including code shared by several types: **Infrastructure service** |
|
|
25
|
+
| 15 | A helper used only by presentation code? | **Presentation service** |
|
|
26
|
+
| — | None of the above | A method or function in an existing file |
|
|
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
|
+
- Decide by what the result is for. A **repository method** loads aggregates in order to change them or check their rules, and saves them. A **query** returns data to a reader as a DTO of its own, never a domain model, even when it is the data of one aggregate: showing a post by id is a query, editing it is a use case that loads the post through the repository, calls its method and saves it.
|
|
30
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
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.
|
|
@@ -45,41 +45,57 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
45
45
|
|
|
46
46
|
## Commonly confused
|
|
47
47
|
|
|
48
|
-
| Pair
|
|
49
|
-
|
|
|
50
|
-
| Port / repository
|
|
51
|
-
| Port / command, query
|
|
52
|
-
| Port with one method / query
|
|
53
|
-
| Query / command
|
|
54
|
-
| Domain service / entity, value object method
|
|
55
|
-
| Domain / application service
|
|
56
|
-
| Use case / application service
|
|
57
|
-
| Application / infrastructure service
|
|
58
|
-
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service.
|
|
59
|
-
| Clock
|
|
60
|
-
| Configuration
|
|
48
|
+
| Pair | Rule |
|
|
49
|
+
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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
|
+
| 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
|
+
| 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
|
+
| 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. |
|
|
55
|
+
| Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
|
|
56
|
+
| Use case / application service | Use case = one action with `handle`, the entry point an endpoint calls. Application service = helper with no `handle`, used by 2+ use cases. A composition of queries/commands needed by one action stays in its use case; the same composition needed by several → application service, called by each of those use cases. |
|
|
57
|
+
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
58
|
+
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service. |
|
|
59
|
+
| Clock | Always a port (`clock`, usually in Shared Kernel). A command or query never uses it: the use case reads the time and passes it in the input. |
|
|
60
|
+
| Configuration | Values application logic needs (limits, feature flags) → a port (`application-config`, usually in Shared Kernel), with methods in the application's terms. Settings only an adapter needs (connection strings, API keys) → that adapter or its infrastructure service reads them; no port. |
|
|
61
|
+
|
|
62
|
+
## Naming
|
|
63
|
+
|
|
64
|
+
### Names describe the module, not its caller
|
|
65
|
+
|
|
66
|
+
A use case is named by its action, a verb: `get-user-info`, `edit-post`, `delete-post`. A query is named by what it reads, a noun: `user-info`, `own-post-list`. A command is named by the change it makes, a verb: `mark-order-paid`. None of these names carries the caller's context: `GetUserInfoUseCase` takes a `userId` and doesn't know it's the signed-in user, so it isn't `GetCurrentUserUseCase`. The caller's context belongs to the caller, e.g. the endpoint that takes the id from the token.
|
|
67
|
+
|
|
68
|
+
A word that describes what the module really does is not the caller's context: `own-post-list` filters posts by their author, so `own` stays.
|
|
69
|
+
|
|
70
|
+
### Ports are named by their role
|
|
71
|
+
|
|
72
|
+
An application port is named by the role it plays for the application, not by what it returns: `WeatherProvider`, not `Weather`. Usually the name ends with a role word: `PaymentGateway`, `SourcePostProvider`, `ReferenceNetworkResolver`, `PostAdaptationRegistrar`, `ReferenceOwnershipChecker`.
|
|
73
|
+
|
|
74
|
+
A name that returns "what" reads like a domain model (`IdeaReferences`, `TargetNetworks`) and hides that this is a dependency on the outside world.
|
|
75
|
+
|
|
76
|
+
A short name is enough when it already names a role: `Mailer`, `Logger`, `Clock`, `ApplicationConfig`. Don't add a role word just to fit the pattern.
|
|
61
77
|
|
|
62
78
|
## Where it goes
|
|
63
79
|
|
|
64
80
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
65
|
-
- Shared Kernel: technical, ownerless pieces (`clock`, `config`, `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.
|
|
81
|
+
- Shared Kernel: technical, ownerless pieces (`clock`, `application-config`, `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.
|
|
66
82
|
- Another context's data or behavior → an application port in the consuming context (step 9).
|
|
67
83
|
|
|
68
84
|
## Example
|
|
69
85
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| Piece
|
|
73
|
-
|
|
|
74
|
-
| Order, customer
|
|
75
|
-
| Order line
|
|
76
|
-
| Money
|
|
77
|
-
| "Can't pay twice"
|
|
78
|
-
| Discount ≤ 30%
|
|
79
|
-
| Place order, reorder
|
|
80
|
-
| Promo code check
|
|
81
|
-
| Email, order date
|
|
82
|
-
| Free shipping for gold customers | 13
|
|
83
|
-
| Confirmation for both use cases
|
|
84
|
-
| Invalid promo code
|
|
85
|
-
| `POST /sales/orders`
|
|
86
|
+
_"On order placement, check the promo code (owned by `marketing`) and email a confirmation, also sent on reorder. Discount ≤ 30% of the order. Gold customers get free shipping on orders over 100."_
|
|
87
|
+
|
|
88
|
+
| Piece | Step | Result (context `sales` unless noted) |
|
|
89
|
+
| -------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| Order, customer | 4 | aggregates `order`, `customer` + repositories |
|
|
91
|
+
| Order line | 5 | `order-line.entity.ts` in `order` (used only by `order`) |
|
|
92
|
+
| Money | 6 | `domain/value-objects/money.value-object.ts` (used by `order` and `shipping-policy`) |
|
|
93
|
+
| "Can't pay twice" | 7 | `Order.pay()` |
|
|
94
|
+
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the port |
|
|
95
|
+
| Place order, reorder | 8 | use cases `place-order`, `reorder` |
|
|
96
|
+
| Promo code check | 9 | port `promotions`: `cross-context` to `marketing`'s handler in the same app, or a transport adapter when deployed separately |
|
|
97
|
+
| Email, order date | 10 | ports `mailer`, `clock` (Shared Kernel) |
|
|
98
|
+
| Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
|
|
99
|
+
| Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
|
|
100
|
+
| Invalid promo code | 1 | error `invalid-promo-code` in namespace `order` |
|
|
101
|
+
| `POST /sales/orders` | 2 | endpoint, controller `orders` |
|
|
@@ -1,6 +1,6 @@
|
|
|
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).
|
|
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). Prompts below are what a generator asks interactively; JSON requests carry the same answers as fields. Generated files and implementation rules are the same.
|
|
4
4
|
|
|
5
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`.
|
|
6
6
|
|
|
@@ -8,11 +8,34 @@ Config paths: `project.rootFolder`, `backend.domainFirstPackages`, `backend.test
|
|
|
8
8
|
|
|
9
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.
|
|
10
10
|
|
|
11
|
-
Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Kernel"`, then the layer, then the operation (abbreviated below as `…`).
|
|
12
|
-
|
|
13
11
|
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
12
|
|
|
15
|
-
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask
|
|
13
|
+
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask for dependencies, before `Overwrite them?`: the checkbox `Dependencies:` interactively, the `dependencies` field in JSON ([agent operations](agent-operations.md#dependency-keys-and-system-implementations)).
|
|
14
|
+
|
|
15
|
+
The list holds wired modules of `<C>` and of the Shared Kernel (`(shared-kernel)` suffix), grouped 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. Endpoints are never listed. The step is skipped when nothing fits: check `<C>/wiring/`, `<rootFolder>/shared-kernel/wiring/` and neighboring contexts' `wiring/`.
|
|
16
|
+
|
|
17
|
+
What fits depends on the layer of the class the wire builds:
|
|
18
|
+
|
|
19
|
+
- domain → domain
|
|
20
|
+
- application → domain, application
|
|
21
|
+
- infrastructure (repository, command/query, and port implementations, infrastructure services) → domain, application ports (of `<C>` and the Shared Kernel; no other application modules), infrastructure
|
|
22
|
+
- presentation → application, presentation
|
|
23
|
+
|
|
24
|
+
On top of that:
|
|
25
|
+
|
|
26
|
+
- Domain services see only domain services (no repositories).
|
|
27
|
+
- Application services see only ports, commands and queries from application.
|
|
28
|
+
- Use cases never see use cases.
|
|
29
|
+
- Repository implementations never see repositories.
|
|
30
|
+
- Command/query implementations see only infrastructure services, locally and in the Shared Kernel.
|
|
31
|
+
- Only port adapters under `infrastructure/application-adapters/cross-context/` also see neighboring queries, commands and use cases labelled `(<context>)`. Imports and constructor names get context-qualified aliases. Query/command implementations have no cross-context exception. This exception is fixed and doesn't 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.
|
|
32
|
+
- These are the defaults: `backend.rules.dependencies` in the config changes them per kind (`use-cases`, `queries`, …), so go by what the project's rules allow.
|
|
33
|
+
|
|
34
|
+
Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order.
|
|
35
|
+
|
|
36
|
+
An env-branched wire (repository, command/query, port) wires each implementation in isolation: 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.
|
|
37
|
+
|
|
38
|
+
It may start with a `Suggested` group, which holds only the system service of the implementation: `prisma-infrastructure-service` for `prisma`, `in-memory-db-infrastructure-service` for `in-memory`. It is listed there only and is **checked**: omitting the implementation's group in JSON keeps it, `[]` selects none. Any other service is an ordinary unchecked item in `Infrastructure services`, whatever its name, so select it explicitly.
|
|
16
39
|
|
|
17
40
|
## Remembered and system implementation types
|
|
18
41
|
|
|
@@ -23,7 +46,7 @@ Active system choices are explicitly labelled:
|
|
|
23
46
|
- `System: cross-context (calls handlers in another bounded context)` — only port adapters with at least one neighboring context, never Shared Kernel ports.
|
|
24
47
|
- `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
48
|
|
|
26
|
-
|
|
49
|
+
Saved system labels retain the marker and are not duplicated. **New Implementation** merges primary/test history and available system choices, without introducing ordinary presets.
|
|
27
50
|
|
|
28
51
|
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.
|
|
29
52
|
|
|
@@ -62,15 +85,14 @@ describe('<label>', () => {
|
|
|
62
85
|
})
|
|
63
86
|
```
|
|
64
87
|
|
|
65
|
-
Without wire: import `<Class>` from `<noWire>`, use `new <Class>()` and the test name `<noWireTest>`.
|
|
88
|
+
Without wire: import `<Class>` from `<noWire>`, use `new <Class>()` and the test name `<noWireTest>`.
|
|
89
|
+
|
|
90
|
+
Only modules without infrastructure have specs. Repositories, commands, queries, ports, infrastructure services and helpers get none: don't create one for them.
|
|
66
91
|
|
|
67
92
|
| Component | Spec next to | `<Type>` / `<var>` | `<wirePath>` | `<label>` | `<Class>` from `<noWire>`, `<noWireTest>` |
|
|
68
93
|
| -------------------- | ---------------------------- | ----------------------------- | ------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
69
94
|
| Aggregate root | `n.aggregate-root.ts` | `N` / `v` | none: `N.of({})` {types} (`can be instantiated via of`), `new N()` otherwise | `n words` | `N` `./n.aggregate-root`, `can be instantiated via constructor` |
|
|
70
|
-
|
|
|
71
|
-
| Service | `n-L-service.ts` | `NLService` / `vLService` | `../../wiring/L-services/wire-n-L-service` | `n words` | `NLService` `./n-L-service`, `can be created` |
|
|
95
|
+
| Service (not infrastructure) | `n-L-service.ts` | `NLService` / `vLService` | `../../wiring/L-services/wire-n-L-service` | `n words` | `NLService` `./n-L-service`, `can be created` |
|
|
72
96
|
| Use case | `n-use-case.ts` | `NUseCase` / `vUseCase` | `../../wiring/use-cases/wire-n-use-case` | `n words use case` | `NUseCase` `./n-use-case`, `can be created` |
|
|
73
|
-
| Command | `n-command.ts` | `NCommand` / `vCommand` | `../../wiring/commands/wire-n-command` | `n words command` | `INCommand` `../../infrastructure/commands/I/I-n-command`, `can be created via constructor` |
|
|
74
|
-
| Port | `n.ts` | `N` / `v` | `../../wiring/application-ports/wire-n` | `n words` | `IN` `../../infrastructure/application-adapters/I/I-n`, `can be created via constructor` |
|
|
75
97
|
|
|
76
|
-
Entities and value objects (`n.entity.ts`, `n.value-object.ts`) follow the aggregate root row. `n words` = the name with spaces instead of hyphens.
|
|
98
|
+
Entities and value objects (`n.entity.ts`, `n.value-object.ts`) follow the aggregate root row. `n words` = the name with spaces instead of hyphens.
|