@domain-first/project-structure 8.1.0 → 8.1.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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@domain-first/project-structure",
3
3
  "description": "Build and manage your Domain-First project structure with CLI",
4
- "version": "8.1.0",
4
+ "version": "8.1.1",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -54,20 +54,52 @@ Never: pick silently, put one context's domain logic in `shared-kernel/`, create
54
54
 
55
55
  ## 4. Present the plan
56
56
 
57
- One message: the architectural part plus the work plan in the `df-ps-scaffold` rule 1 format. Then stop.
57
+ One message in the `df-ps-scaffold` rule 1 format, then stop. The architecture lives in it: each context block's "Why here" is the ownership decision of step 3, each row's Why the component choice of step 2, and open decisions go to Question.
58
58
 
59
59
  ```markdown
60
- **Feature:** product reviews
61
- **Contexts:** `reviews` (new): reviews and their moderation. `sales`: unchanged; `reviews` reads purchases from the shared database.
60
+ **Plan: product reviews**
62
61
 
63
- **Work plan**
64
- (df-ps-scaffold format: new contexts first; mark (new) and (provisional))
62
+ **Scaffolding**
65
63
 
66
- **Why:** own lifecycle and vocabulary → own context (step 3, rule 3); review → aggregate (choosing-components, step 4). "Only buyers" needs `sales` data → port `customer-purchase` in `reviews` with its own models, implementation `prisma`: same database, so no `sales` endpoint is needed (choosing-components, step 9; step 3, rule 4).
64
+ **reviews (new)**
67
65
 
68
- **Decisions for you:**
69
- 1. Separate `reviews` context (recommended) or part of `catalog`?
66
+ Why here: reviews have their own lifecycle and moderation; no context owns them.
67
+
68
+ What will be scaffolded:
69
+
70
+ | Layer | Type | Name | Details | Why |
71
+ | --- | --- | --- | --- | --- |
72
+ | **domain** | aggregate | review | repository prisma, in-memory in tests | consistency boundary with moderation |
73
+ | | error | not-a-buyer | | only buyers may review |
74
+ | **application** | port | customer-purchases | prisma (same database) | purchases live in sales |
75
+ | | use case | submit-review | deps: ReviewRepository, CustomerPurchases | checks purchase, then saves |
76
+ | **presentation** | endpoint | POST products/:id/reviews | → submit-review | UI calls it over HTTP |
77
+
78
+ **React**
79
+
80
+ Why here: buyers write a review on the product page.
81
+
82
+ What will be scaffolded:
83
+
84
+ | Layer | Type | Name | Details | Why |
85
+ | --- | --- | --- | --- | --- |
86
+ | **presentation** | widget | products/review-form | with separated ui | form has its own state |
87
+ | | page | products/details | add the widget | form goes on this screen |
88
+
89
+ **Writing by hand**
90
+ - review: schema (id, productId, authorId, rating, text, status), method publish()
91
+ - customer-purchases adapter: purchases query → HasPurchased
92
+ - submit-review: input { productId, rating, text }, NotABuyer when no purchase
93
+
94
+ **Running**
95
+ - after domain: npm run prisma:migration:plan -- --name add-reviews (applied by the user)
96
+ - after the endpoint: npm run openapi && npm run client:orval
97
+
98
+ **Question**
99
+ 1. Separate reviews context (recommended) or part of catalog?
70
100
  2. Must reviews be moderated before publishing?
101
+
102
+ Reply "ok" to start.
71
103
  ```
72
104
 
73
105
  - Ask only what changes structure or domain behavior. Decide names and details yourself.
@@ -12,7 +12,7 @@ React modules live in `<rootFolder>/presentation/react/` (`…/react/` below) an
12
12
  1. Read `domain-first.project-structure.config.json`: source root is `project.rootFolder`; React is enabled by `frontend.react`; `frontend.react.framework` is `react` or `next`, and both use `df-react`. Stories use `frontend.react.storybookFramework` (initialization uses `@storybook/react-vite` for both React and Next.js via the shared Storybook integration). A config of an earlier major version (`CONFIG_OUTDATED`): ask the user to run `npx df-upgrade`; never run it yourself. Without the config, tell the user to run `npx df-init`; without React configured, tell them to run `npx df-init --section frontend`. Initialization and configuration belong to the human: do not run `df-init` or edit these settings yourself.
13
13
  2. A feature that also needs backend work → plan it with `df-ps-plan-feature`; React runs come last in the plan.
14
14
  3. Choose a module for each piece of UI ("Choosing the module").
15
- 4. Show the work plan in the `df-ps-scaffold` rule 1 format and **stop until it's approved**. CLI paths are `df-react → New widget` etc.; list every answer and the files from `references/generators.md`.
15
+ 4. Show the work plan in the `df-ps-scaffold` rule 1 format (the React block) and **stop until it's approved**. Type is page, widget, ui-kit component, hook, page move or widget move; Details holds the widget type and, for a page move with Next.js, whether the route moves.
16
16
  5. Run the generators with `df-react --request` JSON in plan order (shared hooks → UI-kit → widgets → pages); check each output.
17
17
  6. Implement ("Implementing"), after the backend and the regenerated API client.
18
18
  7. Run `npx df-lint` and the project's tsc/lint/tests. Report against the plan.
@@ -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
- **Work plan**
33
+ **Plan: order cancellation**
34
34
 
35
- | # | Where | CLI path | Name | Options | Files (+ new, ~ changed) |
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
- Hand-written changes:
37
+ **sales**
43
38
 
44
- - `order.aggregate-root.ts`: schema (id, lines, status), method `pay()`
45
- - `place-order-use-case.ts`: schemas, handler
39
+ Why here: cancelling changes the order's status; orders belong to sales.
46
40
 
47
- Hand-created files (exception #): none; list each as `<path>` (#n)
41
+ What will be scaffolded:
48
42
 
49
- Tool runs:
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
- - 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 && npm run client:orval`: OpenAPI document and API client with the new endpoints
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
- - Every run lists the CLI path, target, name, the JSON parameters (or every answer for a legacy interactive run), and the files from its unit file. Flag overwrites of existing files.
56
- - Hand-written changes: members, schemas, dependencies. Not full code.
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
- - Any file outside the rule 2 exceptions appears as a separate **exception request** with a reason.
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 **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.
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 the plan as run options (`deps: OrderRepository`), with a `Wire dependency` run for existing modules.
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`; include that generated config update in the work plan. The run-only action generates code without adding saved choices. These generator-managed choice updates are allowed; project/backend/frontend setup remains a human task. Changes are staged with the generated code and cancelled with it. Repository, command, query and port choices are independent; read that category's saved `primary`/`test` lists before preparing answers.
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 files. "Still waiting for input" means too few steps; nothing was written. If the raw output ends at `Overwrite them?`, the run would replace files the plan didn't flag: show the user the listed files and ask, never just add `yes`. If prompts get out of sync, retry with `--delay 1200`.
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 (tool runs in the plan).
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 them against the plan. 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.
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, list a move as a run: old → new place and name, the files to move (`→`) and the files whose imports or names change (`~`).
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