@domain-first/project-structure 8.1.0 → 8.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -1
- package/dist/201.js +1 -1
- package/dist/287.js +57 -3
- package/dist/38.js +268 -0
- package/dist/graph.cjs +933 -0
- package/dist/graph.d.ts +2 -0
- package/dist/graph.js +337 -0
- package/dist/index.cjs +56 -2
- package/dist/init.cjs +56 -2
- package/dist/integration.cjs +56 -2
- package/dist/interaction.d.ts +9 -0
- package/dist/interaction.spec.d.ts +1 -0
- package/dist/lint.js +8 -273
- package/dist/project-graph.d.ts +53 -0
- package/dist/project-graph.spec.d.ts +1 -0
- package/dist/project-lint.d.ts +10 -0
- package/dist/react.cjs +56 -2
- package/package.json +3 -2
- package/skills/df-ps-plan-feature/SKILL.md +42 -8
- package/skills/df-ps-react/SKILL.md +1 -1
- package/skills/df-ps-scaffold/SKILL.md +64 -22
- package/skills/df-ps-scaffold/references/units/endpoint.md +1 -1
- package/skills/df-ps-scaffold/references/units/move-or-rename.md +2 -2
|
@@ -30,34 +30,76 @@ Tasks that only edit existing files (a bug fix, a new field, a changed rule) don
|
|
|
30
30
|
Show the plan in this format and stop:
|
|
31
31
|
|
|
32
32
|
```markdown
|
|
33
|
-
**
|
|
33
|
+
**Plan: order cancellation**
|
|
34
34
|
|
|
35
|
-
|
|
36
|
-
| --- | ----- | -------------------------- | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
-
| 1 | sales | Domain → New Aggregate | order | repo prisma + in-memory | + …/domain/aggregates/order/{order.aggregate-root.ts, index.ts, order-repository.ts, specs}<br>+ …/infrastructure/repositories/{prisma,in-memory}/…<br>+ …/wiring/repositories/wire-order-repository.ts |
|
|
38
|
-
| 2 | sales | Domain → New Entity | order-line | aggregate order | + …/domain/aggregates/order/entities/{order-line.entity.ts, spec}<br>~ …/domain/aggregates/order/index.ts |
|
|
39
|
-
| 3 | sales | Application → New Use Case | place-order | deps: OrderRepository | + …/application/use-cases/place-order-use-case.ts, spec<br>+ …/wiring/use-cases/wire-place-order-use-case.ts |
|
|
40
|
-
| 4 | react | Move or rename widget | users → admin/users | | → …/widgets/admin/users/{admin-users-widget.tsx, ui/admin-users-widget-ui.tsx, hooks/use-admin-users-ui-model.ts, …}<br>~ …/pages/users-page.tsx (import) |
|
|
35
|
+
**Scaffolding**
|
|
41
36
|
|
|
42
|
-
|
|
37
|
+
**sales**
|
|
43
38
|
|
|
44
|
-
|
|
45
|
-
- `place-order-use-case.ts`: schemas, handler
|
|
39
|
+
Why here: cancelling changes the order's status; orders belong to sales.
|
|
46
40
|
|
|
47
|
-
|
|
41
|
+
What will be scaffolded:
|
|
48
42
|
|
|
49
|
-
|
|
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 |
|
|
50
49
|
|
|
51
|
-
|
|
52
|
-
|
|
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.
|
|
53
85
|
```
|
|
54
86
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
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; for React: page, widget, ui-kit component, hook, page move, widget move.
|
|
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.
|
|
59
101
|
- Approval must be explicit ("ok", "да", "делай"…). A question or silence isn't approval. Changes to the plan → show the updated plan and ask again.
|
|
60
|
-
- After approval, do exactly the plan. An extra
|
|
102
|
+
- 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.
|
|
61
103
|
|
|
62
104
|
### 2. New files only through df-scaffold
|
|
63
105
|
|
|
@@ -81,7 +123,7 @@ Moving or renaming a module (aggregate, entity, value object, service, port, que
|
|
|
81
123
|
|
|
82
124
|
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
125
|
|
|
84
|
-
- List each module's dependencies in
|
|
126
|
+
- List each module's dependencies in its plan row's Details (`deps: OrderRepository`); for an existing module, add a `wire dependency` row.
|
|
85
127
|
- A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `backend.rules.dependencies` in the config) or by context isolation: change the design (a port, a query or command, an infrastructure service) instead of adding it by hand.
|
|
86
128
|
- 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
129
|
- An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
|
|
@@ -143,9 +185,9 @@ node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggre
|
|
|
143
185
|
|
|
144
186
|
Implementation-type menus contain saved names and active system choices, without automatic `api` or `mock` presets. Use `pick:prisma` only when saved for that category, `"pick:System: cross-context"` for a port with a neighboring context, or `"pick:System: in-memory"` for a repository/command/query with the shared DB integration ready. New ordinary names take two steps: `"pick:Enter implementation type and save for future use" text:redis` or `"pick:Enter implementation type for this run only" text:redis`. Use the complete manual-entry label to distinguish saving from run-only input. `default` accepts the selected choice.
|
|
145
187
|
|
|
146
|
-
Custom types entered with the save action update `backend.implementations` in `domain-first.project-structure.config.json`;
|
|
188
|
+
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.
|
|
147
189
|
|
|
148
|
-
Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the planned
|
|
190
|
+
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`.
|
|
149
191
|
|
|
150
192
|
## Menu map
|
|
151
193
|
|
|
@@ -25,4 +25,4 @@ The same controller, path, and method replace the existing endpoint (after `Over
|
|
|
25
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
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
27
|
|
|
28
|
-
After new endpoints, regenerate the OpenAPI document and the API client with the project's scripts (
|
|
28
|
+
After new endpoints, regenerate the OpenAPI document and the API client with the project's scripts (Running in the plan).
|
|
@@ -12,9 +12,9 @@ Prompts: `Module:` (select, grouped by kind; entities and value objects of an ag
|
|
|
12
12
|
|
|
13
13
|
Every file of the module moves (contract, implementations, wire, specs; an aggregate with its whole folder), every import of it follows, and derived names change in the module and its importers: `OrderRepository`, `PrismaOrderRepository`, `wireOrderRepository`, dependents' `orderRepository` parameters, an aggregate's in-memory DB section. An entity leaving its aggregate is no longer re-exported there; its importers import its file.
|
|
14
14
|
|
|
15
|
-
Before `Apply?` the CLI lists the files to move and to update: check
|
|
15
|
+
Before `Apply?` the CLI lists the files to move and to update: check that they are the module's files and its importers. A move that would introduce a forbidden context import prints `Nothing was moved: these imports would cross a bounded context boundary.` with the imports: nothing changed. Fix the design instead (`../choosing-components.md`, step 9: the consuming context gets a port with a cross-context adapter), or move the dependency first.
|
|
16
16
|
|
|
17
|
-
In the plan,
|
|
17
|
+
In the plan, a move is a row of the owner it leaves: Type `move`, Name `old → new`, Details what else changes (`to billing`, `into aggregate order`, `out of aggregate order`).
|
|
18
18
|
|
|
19
19
|
## Implement
|
|
20
20
|
|