@domain-first/project-structure 5.1.2 → 7.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.
Files changed (49) hide show
  1. package/README.md +18 -21
  2. package/dist/201.js +46 -35
  3. package/dist/287.js +3290 -0
  4. package/dist/config-file.d.ts +2 -2
  5. package/dist/dependency-rules.d.ts +1 -1
  6. package/dist/file-system.d.ts +5 -0
  7. package/dist/in-memory-db.d.ts +5 -0
  8. package/dist/index.cjs +195 -2156
  9. package/dist/index.js +9 -3169
  10. package/dist/init.cjs +868 -0
  11. package/dist/init.d.ts +2 -0
  12. package/dist/init.js +36 -0
  13. package/dist/integration.cjs +2063 -0
  14. package/dist/integration.d.ts +2 -0
  15. package/dist/integration.js +31 -0
  16. package/dist/integrations/in-memory-db.d.ts +6 -0
  17. package/dist/integrations/index.d.ts +2 -0
  18. package/dist/integrations/missing-domain-first-packages.d.ts +8 -0
  19. package/dist/integrations/orval.d.ts +7 -4
  20. package/dist/integrations/rest-endpoint-generator.d.ts +18 -0
  21. package/dist/integrations/rest-endpoint-generator.spec.d.ts +1 -0
  22. package/dist/lint.cjs +8 -8
  23. package/dist/lint.js +7 -7
  24. package/dist/print-next-steps.d.ts +9 -2
  25. package/dist/react.cjs +915 -0
  26. package/dist/react.d.ts +2 -0
  27. package/dist/react.js +73 -0
  28. package/dist/use-cases/add-integration-order.spec.d.ts +1 -0
  29. package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
  30. package/package.json +5 -2
  31. package/skills/df-ps-implement/SKILL.md +12 -57
  32. package/skills/df-ps-plan-feature/SKILL.md +7 -7
  33. package/skills/df-ps-project-scripts/SKILL.md +1 -1
  34. package/skills/df-ps-react/SKILL.md +82 -0
  35. package/skills/df-ps-react/references/generators.md +80 -0
  36. package/skills/df-ps-scaffold/SKILL.md +46 -28
  37. package/skills/df-ps-scaffold/references/choosing-components.md +7 -28
  38. package/skills/df-ps-scaffold/references/generators.md +6 -179
  39. package/skills/df-ps-scaffold/references/units/aggregate.md +47 -0
  40. package/skills/df-ps-scaffold/references/units/bounded-context.md +13 -0
  41. package/skills/df-ps-scaffold/references/units/command-query.md +32 -0
  42. package/skills/df-ps-scaffold/references/units/endpoint.md +28 -0
  43. package/skills/df-ps-scaffold/references/units/entity-value-object.md +27 -0
  44. package/skills/df-ps-scaffold/references/units/errors.md +26 -0
  45. package/skills/df-ps-scaffold/references/units/port.md +23 -0
  46. package/skills/df-ps-scaffold/references/units/services.md +28 -0
  47. package/skills/df-ps-scaffold/references/units/use-case.md +25 -0
  48. package/skills/df-ps-scaffold/references/units/wire-dependency.md +15 -0
  49. package/skills/df-ps-scaffold/scripts/drive.mjs +12 -4
@@ -1,21 +1,21 @@
1
1
  ---
2
2
  name: df-ps-scaffold
3
- description: Generate Domain-First components with the `df-ps` CLI (@domain-first/project-structure) — bounded contexts, aggregates, repositories, errors, services, use cases, commands, queries, ports, handlers-rest endpoints, React pages, widgets, UI-kit components (with Storybook stories) and shared hooks, and moving or renaming pages and widgets. Use when the project has domain-first.project-structure.config.json and the user asks to add or create any of these, or to move, rename or regroup a page or widget. Holds the mandatory rules (work plan approval, new files and new dependencies only via df-ps) that the other df-ps skills rely on.
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 driver that the other df-ps skills, df-ps-react included, rely on.
4
4
  ---
5
5
 
6
- # Scaffold components with df-ps
6
+ # Scaffold components with df-scaffold
7
7
 
8
8
  ## Workflow
9
9
 
10
10
  Follow this order for every request:
11
11
 
12
- 1. Read `domain-first.project-structure.config.json` (beside the nearest `package.json`). If missing, stop and tell the user to initialize the project with `npx df-ps` first. Its optional `rules.dependencies` changes what each kind of module may depend on; where it differs from the defaults in these skills, the config wins.
12
+ 1. Read `domain-first.project-structure.config.json` (beside the nearest `package.json`). If missing, stop and tell the user to initialize the project with `npx df-init` first. Its optional `rules.dependencies` changes what each kind of module may depend on; where it differs from the defaults in these skills, the config wins.
13
13
  2. Feature request without named contexts/components → `df-ps-plan-feature` (it covers steps 3–5).
14
- 3. Choose a component for each piece of logic with `references/choosing-components.md`.
15
- 4. Prepare the run details ("Preparing runs" below).
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").
16
16
  5. If the task creates files, show the work plan and **stop until it's approved** (rule 1).
17
17
  6. Run the generators in plan order with the driver; check each output.
18
- 7. Implement with `df-ps-implement`, in its order: domain → application → schema tool runs (migrations) → infrastructure → endpoints → other tool runs (OpenAPI, API client) → React.
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.
21
21
 
@@ -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-ps 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. 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
 
@@ -49,61 +49,79 @@ Hand-created files (exception #): none; list each as `<path>` (#n)
49
49
  Tool runs:
50
50
 
51
51
  - after application, before infrastructure: `npm run prisma:migration:plan -- --name add-order`: migration for the `order` table (applied by the user)
52
- - `npm run openapi && npx orval`: OpenAPI document and API client with the new endpoints
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 you'll give, and the files from `references/generators.md`. Flag overwrites of existing files.
55
+ - Every run lists the CLI path, target, name, every answer you'll give, 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.
59
59
  - Approval must be explicit ("ok", "да", "делай"…). A question or silence isn't approval. Changes to the plan → show the updated plan and ask again.
60
60
  - After approval, do exactly the plan. An extra **new file**, component, 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.
61
61
 
62
- ### 2. New files only through df-ps
62
+ ### 2. New files only through df-scaffold
63
63
 
64
- Every new file is created by `df-ps`. Don't create files with the Write tool, `touch`, redirects, or by copying templates. The only exceptions (`<C>` = `<rootFolder>/bounded-contexts/<context>`):
64
+ 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>`):
65
65
 
66
66
  | # | Files | Location | Condition |
67
67
  | --- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
68
  | 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
69
69
  | 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. |
70
- | 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-ps. |
71
- | 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-ps. A page stays one file that composes widgets, plus an optional CSS module for their layout (grid, spacing, areas); no page tests. Its own hooks, UI parts, types, or styles for how a block looks mean a widget is missing, so generate it. A missing UI-kit or widget UI story: exactly from "Story templates" in `references/generators.md`. |
72
- | 5 | App bootstrap and config | outside `<rootFolder>/{bounded-contexts,shared,presentation}/`: entry point, HTTP server setup registering `restHandlers`, tool configs | Bootstrapping only. Domain/application/infrastructure logic never goes there. |
70
+ | 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-react. |
71
+ | 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`. |
72
+ | 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. |
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 can't run, give the user the menu path and answers to run `npx df-ps` themselves (`! npx df-ps`). Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
76
+ If the CLI can't run, give the user the menu path and answers to run `npx df-scaffold` (or `npx df-react` for React modules) themselves (`! npx df-scaffold`). Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
77
77
 
78
- Moving or renaming a page or widget is a df-ps run too (`Move or rename page` / `Move or rename widget`, see `references/generators.md`): it creates the files at the new paths, so it needs an approved plan (rule 1). Don't move, rename, or copy their files by hand, and don't rename their `<Name>Page…`, `<Name>Widget…`, or `use<Name>UIModel` by hand: df-ps keeps file names, code names, story titles, and imports in sync. List each move as a run: old → new name, the files to move (`→`), and the files whose imports change (`~`).
78
+ Moving or renaming a page or widget is a df-react run, never done by hand: see `df-ps-react`.
79
79
 
80
- ### 3. New dependencies only through df-ps
80
+ ### 3. New dependencies only through df-scaffold
81
81
 
82
- With `@domain-first/wire`, every new dependency of a wired class (a constructor parameter plus its wire) is added by `df-ps`: 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-ps` added.
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
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.
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-ps`, 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.
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
89
  ### 4. Bounded contexts never import each other
90
90
 
91
91
  Details and the check script: `df-ps-implement`, "Bounded context isolation".
92
92
 
93
+ ## Units
94
+
95
+ One file per unit in `references/units/`: when to choose it, how to generate it (prompts, example steps, 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.
96
+
97
+ | Unit | File | Menu |
98
+ | --- | --- | --- |
99
+ | Bounded context | `bounded-context.md` | Scaffold new bounded context |
100
+ | Aggregate + repository | `aggregate.md` | Domain → New Aggregate |
101
+ | Entity, value object | `entity-value-object.md` | Domain → New Entity / New Value Object |
102
+ | Errors | `errors.md` | Domain → Errors |
103
+ | Domain, application, infrastructure, presentation service | `services.md` | <Layer> → New Service |
104
+ | Use case | `use-case.md` | Application → New Use Case |
105
+ | Command, query | `command-query.md` | Application → New Command / New Query |
106
+ | Port + adapters | `port.md` | Application → New Port |
107
+ | REST endpoint | `endpoint.md` | Presentation → New Handlers-REST Endpoint |
108
+ | Dependency of an existing module | `wire-dependency.md` | Wire dependency |
109
+ | React modules | `df-ps-react` skill | `df-react` |
110
+
93
111
  ## Preparing runs
94
112
 
95
113
  - **Contexts**: subfolders of `<rootFolder>/bounded-contexts/` (menu: `Bounded Context: <name>`).
96
- - **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`). Pages and widgets only: folders before the name, each segment kebab-case (`admin/users`); when to nest: `references/choosing-components.md`.
114
+ - **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`).
97
115
  - **Collisions**: before writing, the CLI asks `Overwrite them?` if the run would replace existing files. Check the target paths; rename, or flag the overwrite in the plan and end that run's steps with `yes`.
98
- - **Tests**: with `testingLibrary` set, df-ps 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; don't edit the config yourself.
99
- - **Prompts**: take the exact sequence for the generator and config from `references/generators.md`.
116
+ - **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.
117
+ - **Prompts**: take the exact sequence for the generator and config from its unit file, and the `Dependencies:` step from `references/generators.md`.
100
118
 
101
119
  ## Running the driver
102
120
 
103
- `df-ps` is interactive. `scripts/drive.mjs` answers its prompts, then lists created (`+`) and changed (`~`) files.
121
+ `df-scaffold` is interactive. `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`).
104
122
 
105
123
  ```bash
106
- node <this-skill-dir>/scripts/drive.mjs [--cwd <dir>] [--delay <ms>] <step>...
124
+ node <this-skill-dir>/scripts/drive.mjs [--bin df-react] [--cwd <dir>] [--delay <ms>] <step>...
107
125
  node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggregate" text:order yes default yes default
108
126
  ```
109
127
 
@@ -118,15 +136,15 @@ Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the planned fi
118
136
 
119
137
  ## Menu map
120
138
 
121
- | Layer | Bounded context | Shared Layer |
139
+ | Layer | Bounded context | Shared Kernel |
122
140
  | -------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
123
141
  | Domain | New Aggregate, New Entity, New Value Object, Errors, New Service | New Entity, New Value Object, Errors, New Service |
124
142
  | Application | New Query, New Command, New Use Case, New Port, New Service | New Port, New Service |
125
143
  | Infrastructure | New Service | New Service |
126
144
  | Presentation | New Handlers-REST Endpoint (needs handlers-rest), New Service | New Service |
127
145
 
128
- With `@domain-first/wire`, the layer menu of a context and of the Shared Layer also has `Wire dependency`: it adds dependencies to an existing wired module.
146
+ 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.
129
147
 
130
- The main menu also has `Scaffold React module` (needs `useReact`: New widget, New page, New UI-kit component, New shared hook) and `Scaffold new bounded context`.
148
+ The main menu also has `Scaffold new bounded context`. React modules come from a separate CLI, `df-react`: see `df-ps-react`.
131
149
 
132
- Run order in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → endpoints → React (shared hooks → UI-kit → widgets → pages).
150
+ Run order in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → endpoints → React (`df-ps-react`).
@@ -10,10 +10,10 @@ Split the request into pieces of logic (one responsibility each). For each piece
10
10
  | --- | --- | --- |
11
11
  | 1 | A business failure callers must recognize? | **Errors** (Domain → Errors) |
12
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 and widget type: below |
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
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
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 Layer |
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
19
  | 9 | Data or behavior of **another context**? | **Query** (read) / **command** (write) in this context, one per atomic operation (see below) |
@@ -27,7 +27,7 @@ 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 database operation (several statements in one transaction count as one), one request to an external API or another context's endpoint, one message sent. Its implementations differ only in how they perform that operation (`prisma`, `http`, `in-memory`). 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).
30
+ - A query or command is **one atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to another context's endpoint, one message sent to another context (an external API is never a query or command: it's a port). Its implementations differ only in how they perform that operation (`prisma`, `http`, `in-memory`). 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. 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
33
  - Steps 9–10 beat 11–15. The other-context or external part becomes a query/command or a port. What remains may be a service that **receives it in its constructor**.
@@ -48,40 +48,19 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
48
48
  | --- | --- |
49
49
  | Port / repository | Own aggregate's persistence → repository. External system → port. |
50
50
  | Port / command, query | Own storage or another context → command/query. External system → port. |
51
+ | 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. |
51
52
  | 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. |
52
53
  | 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. |
53
54
  | Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
54
55
  | 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. |
55
56
  | Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
56
57
  | 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. |
57
- | Clock | Always a port (`clock`, usually in Shared Layer). A command or query never uses it: the use case reads the time and passes it in the input. |
58
-
59
- ## React page, widget, UI-kit component or shared hook
60
-
61
- | Piece | Component |
62
- | --- | --- |
63
- | A route / whole screen | **Page** |
64
- | A block with business meaning or backend data (`cart`, `order-summary`) | **Widget** |
65
- | A generic element with no business meaning, driven only by props (`button`, `date-picker`, `modal`) | **UI-kit component** |
66
- | A business element that several widgets repeat whole, with the same meaning (`product-card`) | **UI-kit component** (domain) |
67
- | Generic app-wide logic without markup and business meaning (`debounce`, `media-query`, `local-storage`) | **Shared hook** |
68
-
69
- A UI-kit component or shared hook that starts needing data (API client, loading, backend state) becomes a widget that uses it. A widget's own state goes in its `hooks/`, not in a shared hook.
70
-
71
- A business element goes to UI-kit only when several widgets contain the same element, repeated whole and with the same meaning (a product card shown in a catalog, a cart and recommendations). It stays presentational: business data comes in through props, actions go out through callbacks; no API client, no data loading, no imports from widgets, pages or bounded contexts. Its props describe what it shows (`title`, `price`), not domain types. One widget needing it, or several widgets sharing only a piece of markup, is not a reason: keep it in the widget, or extract the generic piece as a generic UI-kit component.
72
-
73
- **Widgets never import each other.** Not a widget, not its `ui/`, `hooks/` or `types.ts`. What two widgets share goes to UI-kit (an element, by the rules above) or a shared hook (logic without markup); combining widgets is the page's job.
74
-
75
- Nest a page or widget name in folders (`admin/users`) when it belongs to an area of the UI with several pages or widgets: a route group (`/admin/*`) or one section of a screen. Pages follow the route path; a widget goes under the area it serves. Otherwise keep the name flat (`order-summary`); one page or widget is no reason to start a folder. The whole path becomes the code name, so it must read as the component's name: `admin/users/list` (`AdminUsersListWidget`), not `admin/lists/user` (`AdminListsUserWidget`). Not for UI-kit components or shared hooks: they are generic and have no area. When a second page or widget joins an area, move the existing flat one into its folder with `Move or rename page` / `Move or rename widget` (`users` → `admin/users`).
76
-
77
- ## React widget type
78
-
79
- Default **`with separated ui`**. Use `headless` only when consumers must supply different visuals for the same behavior, or the user asks. Use `monolithic` only on explicit request. "It's small" and "other widgets use another type" are not reasons. State any deviation in the plan.
58
+ | 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. |
80
59
 
81
60
  ## Where it goes
82
61
 
83
62
  - Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
84
- - Shared Layer: 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 Layer 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 queries/commands.
63
+ - 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 queries/commands.
85
64
  - Another context's data or behavior → a query/command in the consuming context (step 9).
86
65
 
87
66
  ## Example
@@ -97,7 +76,7 @@ Default **`with separated ui`**. Use `headless` only when consumers must supply
97
76
  | Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the query |
98
77
  | Place order, reorder | 8 | use cases `place-order`, `reorder` |
99
78
  | Promo code check | 9 | query `promo-code-discount`: `prisma` if `marketing` shares the database, otherwise `http` to its endpoint |
100
- | Email, order date | 10 | ports `mailer`, `clock` (Shared Layer) |
79
+ | Email, order date | 10 | ports `mailer`, `clock` (Shared Kernel) |
101
80
  | Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
102
81
  | Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
103
82
  | Invalid promo code | 1 | error `invalid-promo-code` in namespace `order` |
@@ -1,187 +1,14 @@
1
- # df-ps generators: prompts and output
1
+ # df-scaffold generators: common parts
2
2
 
3
- Notation: `<C>` = `<rootFolder>/bounded-contexts/<context>` or `<rootFolder>/shared`. `n` = the entered kebab-case name, `N` = PascalCase, `v` = camelCase. `I` = implementation label (`prisma` → `Prisma`). Specs are generated without a prompt **only if `testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
3
+ 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
4
 
5
- Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Layer"`, then the layer, then the operation (abbreviated below as `…`).
5
+ 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 `testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
6
6
 
7
- Any generator: 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.
8
-
9
- {wire} Generators that create a wire (all below 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 Layer (`(shared)` 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/` and `<rootFolder>/shared/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 Layer; 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. These are the defaults: `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.
10
-
11
- ## Bounded context
12
-
13
- `"pick:Scaffold new bounded context" text:sales` → folder `<rootFolder>/bounded-contexts/sales/`; {errors} `domain/errors/index.ts` with `SalesErrors = errorNamespace('sales')`.
14
-
15
- ## Domain → New Aggregate (context only)
16
-
17
- Prompts: name → `With Repository` → if yes: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
18
-
19
- `… pick:Domain "pick:New Aggregate" text:order yes default yes default`
20
-
21
- - `<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
22
- - `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
23
- - {wire} `<C>/wiring/repositories/wire-n-repository.ts` (env-branched)
24
- - 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/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.
25
-
26
- ## Domain → New Entity / New Value Object (context and Shared Layer)
27
-
28
- Prompts: name → aggregate (select: existing aggregate folders | `No aggregate`; asked only if `<C>/domain/aggregates/` has aggregates, so never in Shared Layer).
29
-
30
- `… pick:Domain "pick:New Entity" text:order-line pick:order`
31
- `… pick:Domain "pick:New Value Object" text:money "pick:No aggregate"`
32
- `"pick:Shared Layer" pick:Domain "pick:New Value Object" text:money`
33
-
34
- - In an aggregate: `<C>/domain/aggregates/a/entities/n.entity.ts` or `<C>/domain/aggregates/a/value-objects/n.value-object.ts` (`class N extends domainType()` {types}), spec; `export * from './entities/n.entity'` (or `./value-objects/n.value-object`) appended to the aggregate's `index.ts`
35
- - `No aggregate`: `<C>/domain/entities/n.entity.ts` or `<C>/domain/value-objects/n.value-object.ts`, spec; no barrel
36
-
37
- ## Domain → Errors (context and Shared Layer)
38
-
39
- First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
40
-
41
- `… pick:Domain pick:Errors "pick:New namespace" text:order`
42
- `… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
43
- `… pick:Domain pick:Errors "pick:New error without" text:order-closed`
44
-
45
- - Without namespace: appends `export class N extends CtxErrors.define('n') {}` to `<C>/domain/errors/index.ts`
46
- - New namespace: `<C>/domain/errors/ns.ts` (`NsErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
47
- - In namespace: appends `export class NsN extends NsErrors.define('n') {}` to `ns.ts` (namespace first), extending the namespace the file exports
48
- - Shared Layer: errors end with `SharedError`, namespaces with `SharedErrors`: `NSharedError`, `NsSharedErrors`, `NsNSharedError`
49
-
50
- Re-running is safe: an existing namespace file is kept, and a line already in the file isn't added again.
51
-
52
- `Ctx` = PascalCase of the context folder (`Shared` in Shared Layer). Requires `index.ts` with `CtxErrors` {errors}.
53
-
54
- ## Services: Domain / Application / Infrastructure / Presentation (context and Shared Layer)
55
-
56
- Prompts: name. `L` = `domain` | `application` | `infrastructure` | `presentation`.
57
-
58
- `… pick:Application "pick:New Service" text:checkout`
59
-
60
- - `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
61
- - {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
62
-
63
- ## Application → New Use Case (context only)
64
-
65
- Prompts: name. `… pick:Application "pick:New Use Case" text:place-order`
66
-
67
- - `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
68
- - {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
69
-
70
- ## Application → New Command / New Query (context only)
71
-
72
- Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
73
-
74
- `… pick:Application "pick:New Command" text:place-order default yes default`
75
- `… pick:Application "pick:New Query" text:order-summary default no`
76
-
77
- - `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
78
- - `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
79
- - {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
80
- - 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.
81
-
82
- Queries: the same with `query` / `queries`.
83
-
84
- ## Application → New Port (context and Shared Layer)
85
-
86
- Prompts: name → adapter implementation (default `api`) → `With test implementation` → if yes: test implementation (default `mock`).
87
-
88
- `… pick:Application "pick:New Port" text:payment-gateway default yes default`
89
-
90
- - `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
91
- - `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
92
- - {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
93
-
94
- ## Wire dependency (context and Shared Layer, needs wire)
7
+ Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Kernel"`, then the layer, then the operation (abbreviated below as `…`).
95
8
 
96
- Prompts: module (select: wired modules of `<C>`, grouped as below, endpoints excluded; an env-branched module is listed once per implementation, e.g. `UserRepository (prisma)`, `UserRepository (in-memory)`) → `Dependencies:`, or `Dependencies for <Implementation>:` for the chosen implementation only (as above). Modules already in the wire are not listed. If nothing fits, it prints `No dependencies available for this module.` and changes nothing.
97
-
98
- `"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
99
-
100
- Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`.
101
-
102
- ## Presentation → New Handlers-REST Endpoint (context only, needs handlers-rest)
103
-
104
- Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
105
-
106
- `… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
107
- `… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
108
-
109
- For `sales`, `orders`, `get`, `recent`:
110
-
111
- - `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. `endpointGenerator: RestEndpointGeneratorPresentationService` (the Shared Layer generator from initialization) and `handler: RecentOrdersQuery` (`never` without a pick), both `import type`. `get handle()` calls `this.endpointGenerator(...)`, which doesn't compile until a generating getter is picked (`this.endpointGenerator.withoutGuards(...)`); that's expected, not a generator bug. Projects without the generator file get `EndpointGenerator` from handlers-rest.
112
- - {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
113
- - {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
114
-
115
- The same controller, path, and method replace the existing endpoint (after `Overwrite them?`).
116
-
117
- ## React (needs useReact)
118
-
119
- `"pick:Scaffold React module" "pick:New page" text:checkout` → `<rootFolder>/presentation/react/pages/n-page.tsx`
120
-
121
- `"pick:Scaffold React module" "pick:New widget" text:cart "pick:with separated ui"` → `…/widgets/n/`:
122
-
123
- - `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`)
124
- - `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
125
- - `monolithic`: `n-widget.tsx`
126
- - every type: `index.ts` (`export * from './n-widget'`)
127
-
128
- Page and widget names may have folders before them: `text:admin/panel/users` → `…/pages/admin/panel/admin-panel-users-page.tsx` and `…/widgets/admin/panel/users/`. The widget folder uses only the last segment; file names use the whole path (`admin-panel-users-page.tsx`, `admin-panel-users-widget.tsx`, `ui/admin-panel-users-widget-ui.tsx`, `hooks/use-admin-panel-users-ui-model.ts`), and so do code names (`AdminPanelUsersPage`, `AdminPanelUsersWidget`, `useAdminPanelUsersUIModel`); the story title follows the folders (`Widgets/Admin/Panel/Users`). `.` and `..` are rejected.
129
-
130
- Move or rename a page or a widget only with df-ps, never by hand: `"pick:Scaffold React module" "pick:Move or rename widget" "pick:admin/users" text:team/users "yes"` (`Move or rename page` for pages; the list shows nested names, the default new name is the current one). 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.
131
-
132
- `"pick:Scaffold React module" "pick:New UI-kit" text:date-picker` → `…/ui-kit/n/`:
133
-
134
- - `n.tsx` (`type NProps`, `const N: FC<NProps>`)
135
- - `index.ts` (`export * from './n'`)
136
- - with `storybookFramework`: `n.stories.tsx` (CSF3: `meta` with `title: 'UI-kit/N'`, story `Default`)
137
-
138
- No Storybook prompt: UI-kit and widget UI stories follow the config.
139
-
140
- `"pick:Scaffold React module" "pick:New shared hook" text:debounce` → `…/presentation/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
141
-
142
- ### Story templates
143
-
144
- Only for recreating a **missing** story (rule 2, exception 4).
145
-
146
- UI-kit, at `…/ui-kit/n/n.stories.tsx`:
147
-
148
- ```tsx
149
- import type { Meta, StoryObj } from "<storybookFramework>";
150
- import { N } from "./n";
151
-
152
- const meta = {
153
- title: "UI-kit/N",
154
- component: N,
155
- } satisfies Meta<typeof N>;
156
-
157
- export default meta;
158
-
159
- type Story = StoryObj<typeof meta>;
160
-
161
- export const Default: Story = {
162
- args: {},
163
- };
164
- ```
165
-
166
- Widget UI (`with separated ui` only), at `…/widgets/n/ui/n-widget-ui.stories.tsx`:
167
-
168
- ```tsx
169
- import type { Meta, StoryObj } from "<storybookFramework>";
170
- import { NWidgetUI } from "./n-widget-ui";
171
-
172
- const meta = {
173
- title: "Widgets/N",
174
- component: NWidgetUI,
175
- } satisfies Meta<typeof NWidgetUI>;
176
-
177
- export default meta;
178
-
179
- type Story = StoryObj<typeof meta>;
9
+ Any generator: 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.
180
10
 
181
- export const Default: Story = {
182
- args: {},
183
- };
184
- ```
11
+ {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/` and `<rootFolder>/shared-kernel/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. These are the defaults: `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.
185
12
 
186
13
  ## Env-branched wiring {wire}
187
14
 
@@ -0,0 +1,47 @@
1
+ # Aggregate and repository
2
+
3
+ When: a thing with identity, lifecycle, and rules about its own state, owned by this context and stored on its own (`../choosing-components.md`, step 4). A rule about its own state is a method on it (step 7), not a new unit. Loading/saving one aggregate is a repository method, not a query or command.
4
+
5
+ ## Generate (context only)
6
+
7
+ Prompts: name → `With Repository` → if yes: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
8
+
9
+ `… pick:Domain "pick:New Aggregate" text:order yes default yes default`
10
+
11
+ - `<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
+ - `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
13
+ - {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
+
16
+ Its entities and value objects come after it: [entity-value-object](entity-value-object.md), picking this aggregate.
17
+
18
+ ## Implement
19
+
20
+ ```ts
21
+ export class Order extends domainType(
22
+ z.object({
23
+ id: z.instanceof(OrderId),
24
+ lines: z.array(z.instanceof(OrderLine)),
25
+ status: z.enum(["open", "paid"]),
26
+ }),
27
+ ) {
28
+ withPayment = () => {
29
+ if (this.status === "paid") {
30
+ throw new AlreadyPaidOrderSalesError({
31
+ id: this.id.snapshot,
32
+ });
33
+ }
34
+ return this.with({ status: "paid" });
35
+ };
36
+ }
37
+ ```
38
+
39
+ - Use the schema library the project already uses. Methods return new instances. Invalid input throws `TypeParsingError`.
40
+ - The aggregate is rich and knows nothing about storage: its rules and factories are methods; no repository calls, persistence fields, or storage mapping.
41
+ - Repository contract: abstract members (`abstract findById(id: OrderId): Promise<Order | null>`, `abstract save(order: Order): Promise<void>`). A rule about a set of aggregates (uniqueness, "at most N per day") is a repository method that queries it, checked in the use case.
42
+ - Implementations map storage ⇄ aggregates. The in-memory one behaves like the real one for what tests use; with the in-memory DB, it keeps the aggregates in its section (`this.data.save(order)`, `this.data.withId(id)`).
43
+ - Refer to other contexts' entities by id only.
44
+
45
+ ## Test
46
+
47
+ Extend the generated specs in the same files: aggregate rules on the root, the repository contract against the test implementation.
@@ -0,0 +1,13 @@
1
+ # Bounded context
2
+
3
+ When: a concept with its own lifecycle and vocabulary, or a different business owner (`df-ps-plan-feature`, step 3). Never one context per feature.
4
+
5
+ ## Generate
6
+
7
+ `"pick:Scaffold new bounded context" text:sales` → empty folder `<rootFolder>/bounded-contexts/sales/`. No error namespace until the first error ([errors](errors.md)).
8
+
9
+ Name: a business area in kebab-case (`sales`, `reviews`), not a feature.
10
+
11
+ ## Implement
12
+
13
+ Nothing to fill in. Everything inside comes from the other units. The context imports nothing from other contexts and they import nothing from it (`df-ps-implement`, "Bounded context isolation").
@@ -0,0 +1,32 @@
1
+ # Command and query
2
+
3
+ When (`../choosing-components.md`, steps 9 and 11): data or behavior of **another context**, or one atomic read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update). A query reads, a command writes.
4
+
5
+ - **One atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to another context's endpoint, one message sent to another context (an external API is never a query or command: it's a port). Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in a use case.
6
+ - 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. 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.
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.
8
+
9
+ ## Generate (context only)
10
+
11
+ Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
12
+
13
+ `… pick:Application "pick:New Command" text:place-order default yes default`
14
+ `… pick:Application "pick:New Query" text:order-summary default no`
15
+
16
+ - `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
17
+ - `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
18
+ - {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.
20
+
21
+ Queries: the same with `query` / `queries`.
22
+
23
+ ## Implement
24
+
25
+ - {handlers} The abstract contract holds the static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes only its `handler` callback.
26
+ - An implementation performs its one operation: no business logic, no steps around it. Its only wired dependencies are infrastructure services (the client it runs on); repositories, ports, domain services and other commands and queries stay with the use case. Needing more → it's several commands/queries.
27
+ - It uses domain models in its input/output; the time comes in the input, never from the `clock` port.
28
+ - The test implementation returns fixed data (another context) or works on the in-memory DB (own storage), so tests never run another context.
29
+
30
+ ## Test
31
+
32
+ Extend the generated spec: the handler against the test implementation via `handle(...)`.
@@ -0,0 +1,28 @@
1
+ # REST endpoint {handlers-rest}
2
+
3
+ When: an HTTP entry point (`../choosing-components.md`, step 2). It exposes a query, a command or a use case of its context.
4
+
5
+ ## Generate (context only)
6
+
7
+ Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
8
+
9
+ `… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
10
+ `… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
11
+
12
+ For `sales`, `orders`, `get`, `recent`:
13
+
14
+ - `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. `endpointGenerator: RestEndpointGeneratorPresentationService` (the Shared Kernel generator) and `handler: RecentOrdersQuery` (`never` without a pick), both `import type`. `get handle()` calls `this.endpointGenerator(...)`, which doesn't compile until a generating getter is picked (`this.endpointGenerator.withoutGuards(...)`); that's expected, not a generator bug. Projects without the generator file get `EndpointGenerator` from handlers-rest.
15
+ - {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
16
+ - {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
17
+
18
+ The same controller, path, and method replace the existing endpoint (after `Overwrite them?`). Generate the exposed handler first, so `Handler:` lists it. If `handler: never` is left, re-run the endpoint generator once the handler exists, as an approved overwrite; don't replace it by hand.
19
+
20
+ ## Implement
21
+
22
+ 1. Generator: `df-init` (or the `REST endpoint generator` integration) creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared-kernel/presentation/services/`; every endpoint uses it. Set the module-level `const adapter` above the class (`undefined` until set) to the HTTP framework's adapter; the class reads it through closure. If the Next adapter was connected, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed.
23
+ 2. Errors: invalid requests (`400`) are answered by `invalidRequest()` of `@domain-first/handlers-rest` in `errors`; don't map `RequestParsingError` / `InputMappingError` by hand, add your own mappings next to it: `errors: [httpError(MyError, 404), invalidRequest()]`. Map domain errors with `httpError(ErrorClass, status, { description, message, details: { schema, map } })` (one class) or `httpStatus(status, { code, match })` (many errors, one code); the first match wins, so put specific mappings first, importing them from the contexts' `domain/errors` (the only thing `shared-kernel/` may import from a context, besides domain models in the in-memory DB).
24
+ 3. A new kind of endpoint (auth, other context) is a new getter returning `createEndpoint({ context, errors: [..., invalidRequest()] })(adapter) as EndpointGenerator` (`nextAdapter` with the Next adapter), next to `withoutGuards`.
25
+ 4. Complete `get handle()`: pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`.
26
+ 5. Register `restHandlers` from `<rootFolder>/presentation/rest/index.ts` in the server bootstrap (`df-ps-scaffold` `SKILL.md`, rule 2, exception 5). With the Next adapter and wire, `app/api/[...path]/route.ts` (or `src/app/…`) already serves them through `nextEndpoints(restHandlers)`; it compiles once the first endpoint exists.
27
+
28
+ After new endpoints, regenerate the OpenAPI document and the API client with the project's scripts (tool runs in the plan).