@domain-first/project-structure 8.6.1 → 8.7.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 (50) hide show
  1. package/README.md +1 -1
  2. package/bin/df-skills.mjs +55 -9
  3. package/dist/287.js +54 -2
  4. package/dist/38.js +36 -0
  5. package/dist/561.js +9 -1
  6. package/dist/947.js +11 -1
  7. package/dist/agent-cli.d.ts +9 -2
  8. package/dist/agent-principles.cjs +116 -0
  9. package/dist/agent-principles.d.ts +9 -0
  10. package/dist/agent-principles.js +64 -0
  11. package/dist/agent-principles.spec.d.ts +1 -0
  12. package/dist/agent-requests.d.ts +16 -2
  13. package/dist/graph.cjs +10 -0
  14. package/dist/index.cjs +74 -1
  15. package/dist/index.js +4 -1
  16. package/dist/init.cjs +12 -2
  17. package/dist/integration.cjs +71 -1
  18. package/dist/lint.cjs +46 -0
  19. package/dist/react.cjs +71 -1
  20. package/dist/use-cases/add-integration.d.ts +1 -1
  21. package/dist/use-cases/index.d.ts +1 -0
  22. package/dist/use-cases/scaffold-new-infrastructure-helper.d.ts +7 -0
  23. package/dist/wiring.d.ts +2 -2
  24. package/package.json +3 -2
  25. package/principles/df-principles.md +33 -0
  26. package/skills/df-ps-implement/SKILL.md +26 -1
  27. package/skills/df-ps-plan-feature/SKILL.md +22 -18
  28. package/skills/df-ps-react/SKILL.md +2 -9
  29. package/skills/df-ps-react/references/generators.md +9 -9
  30. package/skills/df-ps-scaffold/SKILL.md +19 -125
  31. package/skills/df-ps-scaffold/references/agent-mode.md +2 -2
  32. package/skills/df-ps-scaffold/references/agent-operations.md +1 -0
  33. package/skills/df-ps-scaffold/references/choosing-components.md +65 -49
  34. package/skills/df-ps-scaffold/references/generators.md +28 -5
  35. package/skills/df-ps-scaffold/references/units/aggregate.md +1 -3
  36. package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
  37. package/skills/df-ps-scaffold/references/units/command-query.md +4 -6
  38. package/skills/df-ps-scaffold/references/units/delete.md +0 -2
  39. package/skills/df-ps-scaffold/references/units/endpoint.md +1 -4
  40. package/skills/df-ps-scaffold/references/units/entity-value-object.md +0 -4
  41. package/skills/df-ps-scaffold/references/units/errors.md +0 -4
  42. package/skills/df-ps-scaffold/references/units/helper.md +30 -0
  43. package/skills/df-ps-scaffold/references/units/implementation.md +0 -4
  44. package/skills/df-ps-scaffold/references/units/move-or-rename.md +0 -4
  45. package/skills/df-ps-scaffold/references/units/port.md +2 -5
  46. package/skills/df-ps-scaffold/references/units/services.md +2 -4
  47. package/skills/df-ps-scaffold/references/units/use-case.md +1 -2
  48. package/skills/df-ps-scaffold/references/units/wire-dependency.md +0 -2
  49. package/skills/df-ps-scaffold/references/work-plan.md +73 -0
  50. package/skills/df-ps-scaffold/scripts/drive.mjs +0 -252
@@ -5,7 +5,7 @@ description: Turn an abstract feature request into a Domain-First plan for a pro
5
5
 
6
6
  # Plan a feature
7
7
 
8
- Understand → decompose → assign → get approval → hand off. A feature creates files, so nothing is generated or written before approval (`df-ps-scaffold`, rule 1).
8
+ Understand → decompose → assign → get approval → hand off. A feature creates files, so nothing is generated or written before approval (`df-ps-scaffold`, rule 1). Only the user's literal request to skip the plan ("skip the plan", "with plan skipped", etc.) removes this step. However direct or urgent any other wording sounds, it is a request to write the plan.
9
9
 
10
10
  ## 1. Understand what exists
11
11
 
@@ -33,12 +33,13 @@ Split the request into pieces of logic and choose each piece's component with `d
33
33
  2. Extend an existing context when the concept fits its language and lifecycle (the normal case).
34
34
  3. Create a new context only for a concept with its own lifecycle and vocabulary, or a different business owner. Never one context per feature.
35
35
  4. Domain and application stay isolated. Every need for another context's data or behavior is an **application port** in the consuming context, with its own duplicated models. The implementation can be replaced when a context becomes a separate service. Choose the simplest available way, respecting the user's requested transport:
36
- - Both contexts run in the same application → a port adapter with the reserved type `cross-context`. It may inject the neighboring context's queries, commands and use cases. Only the adapter imports the handler type; its wiring imports the handler factory. No transport or endpoint is needed. Check that the providing handler exists; plan it if missing.
37
- - A direct handler call is unavailable or a database integration is requested, and both contexts use the same database → query it directly (the persistence label, e.g. `prisma`).
38
- - Otherwise, look for the ways the project already reaches a context besides its REST endpoints: message queue, RPC, events, generated API clients. Several options (REST counts) → ask the user which one in "Decisions for you", with a recommendation. Never pick silently.
39
- - Nothing besides REST → the providing context's REST endpoint (`http`).
36
+ - Both contexts run in the same application → a port adapter with the reserved type `cross-context`. It may inject the neighboring context's queries, commands and use cases. Only the adapter imports the handler type; its wiring imports the handler factory. No transport or endpoint is needed. Check that the providing handler exists; plan it if missing.
37
+ - A direct handler call is unavailable or a database integration is requested, and both contexts use the same database → query it directly (the persistence label, e.g. `prisma`).
38
+ - Otherwise, look for the ways the project already reaches a context besides its REST endpoints: message queue, RPC, events, generated API clients. Several options (REST counts) → ask the user which one in "Decisions for you", with a recommendation. Never pick silently.
39
+ - Nothing besides REST → the providing context's REST endpoint (`http`).
40
+
41
+ For transport implementations, plan **both sides**: check that the providing context exposes what the call needs (endpoint, queue consumer…). If not, add it (and the handler behind it: a query or command, or a use case only when one query or command isn't enough) to the plan.
40
42
 
41
- For transport implementations, plan **both sides**: check that the providing context exposes what the call needs (endpoint, queue consumer…). If not, add it (and the handler behind it: a query or command, or a use case only when one query or command isn't enough) to the plan.
42
43
  5. `shared-kernel/` holds technical, ownerless pieces and universal entities / value objects (`money`, `email`): the same meaning in every context, owned by none. Never a concept with one context's meaning or rules.
43
44
  6. Names: kebab-case, in the context's language. Contexts are business areas (`sales`, `reviews`), not features.
44
45
 
@@ -56,7 +57,7 @@ Never: pick silently, put one context's domain logic in `shared-kernel/`, create
56
57
 
57
58
  ## 4. Present the plan
58
59
 
59
- 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.
60
+ One message in the format of `df-ps-scaffold/references/work-plan.md`, 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.
60
61
 
61
62
  ```markdown
62
63
  **Plan: product reviews**
@@ -69,13 +70,13 @@ Why here: reviews have their own lifecycle and moderation; no context owns them.
69
70
 
70
71
  What will be scaffolded:
71
72
 
72
- | Layer | Type | Name | Details | Why |
73
- | --- | --- | --- | --- | --- |
74
- | **domain** | aggregate | review | repository prisma, in-memory in tests | consistency boundary with moderation |
75
- | | error | not-a-buyer | | only buyers may review |
76
- | **application** | port | customer-purchases | prisma (same database) | purchases live in sales |
77
- | | use case | submit-review | deps: ReviewRepository, CustomerPurchases | checks purchase, then saves |
78
- | **presentation** | endpoint | POST products/:id/reviews | → submit-review | UI calls it over HTTP |
73
+ | Layer | Type | Name | Details | Why |
74
+ | ---------------- | --------- | ------------------------- | ----------------------------------------- | ------------------------------------ |
75
+ | **domain** | aggregate | review | repository prisma, in-memory in tests | consistency boundary with moderation |
76
+ | | error | not-a-buyer | | only buyers may review |
77
+ | **application** | port | customer-purchases | prisma (same database) | purchases live in sales |
78
+ | | use case | submit-review | deps: ReviewRepository, CustomerPurchases | checks purchase, then saves |
79
+ | **presentation** | endpoint | POST products/:id/reviews | → submit-review | UI calls it over HTTP |
79
80
 
80
81
  **React**
81
82
 
@@ -83,21 +84,24 @@ Why here: buyers write a review on the product page.
83
84
 
84
85
  What will be scaffolded:
85
86
 
86
- | Layer | Type | Name | Details | Why |
87
- | --- | --- | --- | --- | --- |
88
- | **presentation** | widget | products/review-form | with separated ui | form has its own state |
89
- | | page | products/details | add the widget | form goes on this screen |
87
+ | Layer | Type | Name | Details | Why |
88
+ | ---------------- | ------ | -------------------- | ----------------- | ------------------------ |
89
+ | **presentation** | widget | products/review-form | with separated ui | form has its own state |
90
+ | | page | products/details | add the widget | form goes on this screen |
90
91
 
91
92
  **Writing by hand**
93
+
92
94
  - review: schema (id, productId, authorId, rating, text, status), method publish()
93
95
  - customer-purchases adapter: purchases query → HasPurchased
94
96
  - submit-review: input { productId, rating, text }, NotABuyer when no purchase
95
97
 
96
98
  **Running**
99
+
97
100
  - after domain: npm run prisma:migration:plan -- --name add-reviews (applied by the user)
98
101
  - after the endpoint: npm run openapi && npm run client:orval
99
102
 
100
103
  **Question**
104
+
101
105
  1. Separate reviews context (recommended) or part of catalog?
102
106
  2. Must reviews be moderated before publishing?
103
107
 
@@ -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 (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.
15
+ 4. Show the work plan in the format of `df-ps-scaffold/references/work-plan.md` (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.
@@ -49,14 +49,7 @@ npx df-react --request '{"operation":"widget","name":"cart","widgetType":"separa
49
49
 
50
50
  Read `df-ps-scaffold` [agent-mode.md](../df-ps-scaffold/references/agent-mode.md) for previews, overwrite control and JSON result checks; [agent-operations.md](../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) covers all React operations and naming conditions. Initialization remains a human task. For older CLI versions without JSON support, use the interactive driver with `--bin df-react`:
51
51
 
52
- ```bash
53
- node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react [--cwd <dir>] [--delay <ms>] <step>...
54
- node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react "pick:New widget" text:cart "pick:with separated ui"
55
- ```
56
-
57
- Steps and checks are the same as for `df-scaffold` ("Legacy interactive driver" in `df-ps-scaffold`). Its menu: `New widget`, `New page`, `New UI-kit component`, `New shared hook`, `Move or rename widget`, `Move or rename page`, `Move or rename UI-kit component`, `Move or rename shared hook`, `Delete widget`, `Delete page`, `Delete UI-kit component`, `Delete shared hook`. Prompts and output of each: `references/generators.md`.
58
-
59
- If the CLI cannot run, report the failure and give the user the prepared JSON command (a menu path only for a legacy CLI). Never hand-write its output.
52
+ If the CLI cannot run, report the failure and give the user the prepared JSON command. Never hand-write its output.
60
53
 
61
54
  ### Moving and renaming
62
55
 
@@ -1,18 +1,18 @@
1
1
  # df-react generators: operations and output
2
2
 
3
- Prefer JSON requests; [agent operations](../../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) maps all six React operations and fields. The scripted prompt sequences below are the legacy interactive fallback. Generated files and story templates apply to both modes.
3
+ Prefer JSON requests; [agent operations](../../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) maps all six React operations and fields. Generated files and story templates apply to both modes.
4
4
 
5
5
  Settings: `project.rootFolder` and `frontend.react.storybookFramework`. The frontend section must be configured by the user before these runs.
6
6
 
7
- Notation: `…/react/` = `<rootFolder>/presentation/react/`. `n` = the entered kebab-case name, `N` = PascalCase. Every step list goes after `--bin df-react`; the first prompt is the module menu. If the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it).
7
+ Notation: `…/react/` = `<rootFolder>/presentation/react/`. `n` = the entered kebab-case name, `N` = PascalCase. If the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it).
8
8
 
9
9
  ## New page
10
10
 
11
- `"pick:New page" text:checkout` → `…/react/pages/n-page.tsx`; with Next.js (`frontend.react.framework: next`) also `app/n/page.tsx` (`src/app/…` when that folder exists) rendering `NPage`, unless that route already exists. A nested name nests the route too: `admin/users` → `app/admin/users/page.tsx`.
11
+ `…/react/pages/n-page.tsx`; with Next.js (`frontend.react.framework: next`) also `app/n/page.tsx` (`src/app/…` when that folder exists) rendering `NPage`, unless that route already exists. A nested name nests the route too: `admin/users` → `app/admin/users/page.tsx`.
12
12
 
13
13
  ## New widget
14
14
 
15
- `"pick:New widget" text:cart "pick:with separated ui"` → `…/react/widgets/n/`:
15
+ `…/react/widgets/n/`:
16
16
 
17
17
  - `with separated ui` (default): `n-widget.tsx`, `types.ts`, `ui/n-widget-ui.tsx`, `hooks/use-n-ui-model.ts`; with `storybookFramework`: `ui/n-widget-ui.stories.tsx` (CSF3: `meta` with `title: 'Widgets/N'`, `component: NWidgetUI`, story `Default`)
18
18
  - `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
@@ -23,19 +23,19 @@ Page and widget names may have folders before them: `text:admin/panel/users` →
23
23
 
24
24
  ## Move or rename page / widget
25
25
 
26
- Move or rename a page or a widget only with df-react, never by hand: `"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.
26
+ Move or rename a page or a widget only with df-react, never by hand (JSON `move-widget`, `move-page`). It moves the widget folder (or the page with its `<name>-page.*` files), renames files and `<Name>Widget…` / `use<Name>UIModel` / `<Name>Page…` to the new name, updates a generated story title and every import of the module (relative and `tsconfig` aliases; importers of barrels re-exporting it get the renamed classes), and fixes relative imports inside it. Before `Apply?` it prints the files to move and to update; check them. An existing target or a move into itself is rejected.
27
27
 
28
28
  ## Move, rename or delete a UI-kit component / shared hook
29
29
 
30
- The same runs exist for them: `"pick:Move or rename UI-kit component" pick:button text:primary-button yes`, `"pick:Move or rename shared hook" pick:debounce text:throttle yes`, `"pick:Delete UI-kit component" pick:badge yes`, `"pick:Delete shared hook" pick:toggle yes`. Names have no folders; a hook's name is entered without `use-`. A move renames the folder or `use-<name>.*` files, `<Name>` / `<Name>Props` / `use<Name>`, the `UI-kit/<Name>` story title and every import; a delete is refused while other files import the module.
30
+ The same runs exist for them (`move-ui-kit-component`, `move-shared-hook`, `delete-ui-kit-component`, `delete-shared-hook`). Names have no folders; a hook's name is entered without `use-`. A move renames the folder or `use-<name>.*` files, `<Name>` / `<Name>Props` / `use<Name>`, the `UI-kit/<Name>` story title and every import; a delete is refused while other files import the module.
31
31
 
32
32
  ## Delete page / widget
33
33
 
34
- Delete a page or a widget only with df-react: `"pick:Delete widget" "pick:orders/filters" yes` (`Delete page` for pages; with Next.js and the page's own route, a `yes`/`no` for deleting the route comes before `Delete?`). It deletes the widget folder (or the page with its `<name>-page.*` files) and, if confirmed, the route folder's own files. It refuses while other files import the module and lists them; nothing changes then.
34
+ Delete a page or a widget only with df-react (JSON `delete-widget`, `delete-page`; with Next.js and the page's own route, whether to delete the route is asked too). It deletes the widget folder (or the page with its `<name>-page.*` files) and, if confirmed, the route folder's own files. It refuses while other files import the module and lists them; nothing changes then.
35
35
 
36
36
  ## New UI-kit component
37
37
 
38
- `"pick:New UI-kit" text:date-picker` → `…/react/ui-kit/n/`:
38
+ `…/react/ui-kit/n/`:
39
39
 
40
40
  - `n.tsx` (`type NProps`, `const N: FC<NProps>`)
41
41
  - `index.ts` (`export * from './n'`)
@@ -45,7 +45,7 @@ No Storybook prompt: UI-kit and widget UI stories follow the config.
45
45
 
46
46
  ## New shared hook
47
47
 
48
- `"pick:New shared hook" text:debounce` → `…/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
48
+ `…/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
49
49
 
50
50
  ## Story templates
51
51
 
@@ -14,7 +14,7 @@ Follow this order for every request:
14
14
  3. Choose a component for each piece of logic with `references/choosing-components.md`. Pieces of UI (pages, widgets, UI-kit components, shared hooks): `df-ps-react`.
15
15
  4. Read `references/units/<unit>.md` for every unit in the plan ("Units" below) and prepare the run details ("Preparing runs"). Read [agent-mode.md](references/agent-mode.md) for the JSON protocol and use `--describe` to obtain the installed request schema and selectable IDs.
16
16
  5. If the task creates files, show the work plan and **stop until it's approved** (rule 1).
17
- 6. Run the generators in plan order with `--request` JSON; check exit code, `ok` and all returned file lists. Use the driver only for older CLI versions without JSON support.
17
+ 6. Run the generators in plan order with `--request` JSON; check exit code, `ok` and all returned file lists.
18
18
  7. Implement each unit by the "Implement" and "Test" sections of its unit file and the general rules of `df-ps-implement`, in this order: domain → application → schema tool runs (migrations) → infrastructure → endpoints → other tool runs (OpenAPI, API client) → React (`df-ps-react`).
19
19
  8. Run `npx df-lint` and the project's tsc/lint/tests.
20
20
  9. Report against the plan.
@@ -23,81 +23,12 @@ Follow this order for every request:
23
23
 
24
24
  ### 1. Work plan approval
25
25
 
26
- **A task that creates any new file** (a df-scaffold run, or a hand-created file under rule 2) needs an approved work plan first, even for one component, unless the user explicitly says to skip approval for this task. Until approval, only read (`--describe` and `dryRun: true` do not write files). Files written by the project's own scripts (rule 2, exception 2) don't count: run those scripts when the work needs them.
26
+ **A task that creates any new file** (a df-scaffold run, or a hand-created file under rule 2) needs an approved work plan first, even for one component. The plan can be skipped only when the user literally asks to skip it for this task ("skip the plan", "пропусти план"). Anything else, however direct or urgent it sounds ("just do it", "build it now", "no need to ask"), is still a request that starts with a plan. This is about skipping the plan: once a plan is shown, an ordinary "yes" or "go ahead" approves it. Until approval, only read (`--describe` and `dryRun: true` do not write files). Files written by the project's own scripts (rule 2, exception 2) don't count: run those scripts when the work needs them.
27
27
 
28
28
  Tasks that only edit existing files (a bug fix, a new field, a changed rule) don't need a plan: do them directly and say what you changed.
29
29
 
30
- Show the plan in this format and stop:
30
+ Read [references/work-plan.md](references/work-plan.md), show the plan in that format and stop.
31
31
 
32
- ```markdown
33
- **Plan: order cancellation**
34
-
35
- **Scaffolding**
36
-
37
- **sales**
38
-
39
- Why here: cancelling changes the order's status; orders belong to sales.
40
-
41
- What will be scaffolded:
42
-
43
- | Layer | Type | Name | Details | Why |
44
- | --- | --- | --- | --- | --- |
45
- | **domain** | error | order-already-shipped | | shipped orders can't be cancelled |
46
- | **application** | command | cancel-order | prisma, fake in tests | one atomic status change |
47
- | | query | cancellable-orders | prisma | read-only list for the UI |
48
- | **presentation** | endpoint | POST orders/:id/cancel | → cancel-order | UI calls it over HTTP |
49
-
50
- **billing**
51
-
52
- Why here: refunds are payments; payments belong to billing.
53
-
54
- What will be scaffolded:
55
-
56
- | Layer | Type | Name | Details | Why |
57
- | --- | --- | --- | --- | --- |
58
- | **application** | port | order-refunds | cross-context, stub in tests | paid amount lives in sales |
59
- | | use case | refund-cancelled-order | deps: OrderRefunds, PaymentGateway | read order, then call provider |
60
-
61
- **React**
62
-
63
- Why here: the user cancels from the order screen.
64
-
65
- What will be scaffolded:
66
-
67
- | Layer | Type | Name | Details | Why |
68
- | --- | --- | --- | --- | --- |
69
- | **presentation** | widget | orders/cancel-order | with separated ui | dialog has its own state |
70
- | | page | orders/details | add the widget | button goes on this screen |
71
-
72
- **Writing by hand**
73
- - cancel-order: input { orderId }, output { status }
74
- - prisma implementation: update status, throw OrderAlreadyShipped
75
- - endpoint: :id → orderId, OrderAlreadyShipped → 409
76
- - order-refunds adapter: sales:OrderSummaryQuery result → RefundableAmount
77
-
78
- **Running**
79
- - after the endpoint: npm run openapi && npm run client:orval
80
-
81
- **Question**
82
- 1. Refund right on cancel, or after a manager confirms?
83
-
84
- Reply "ok" to start.
85
- ```
86
-
87
- - Write the plan in the user's language (headings and sentences); module names, types, commands and paths stay as in the code. Omit empty sections.
88
- - **Scaffolding** has one block per owner, in run order: new contexts first, marked `(new)` (and `(provisional)` with the reason when ownership is a reversible default), then existing contexts, `shared-kernel`, React last.
89
- - **Why here**: one short sentence on why this owner, not another: the data or rule the context owns; for `shared-kernel`, why several contexts share it; for React, why the UI changes.
90
- - **What will be scaffolded**: one table per owner, one row per `df-scaffold`/`df-react` run. Layers in order domain → application → infrastructure → presentation, the layer in bold only on its first row. Repositories go with their aggregate in domain; commands, queries and ports in application (their implementations are Details); endpoints and React modules in presentation.
91
- - **Type**: the unit: aggregate, entity, value object, error, error namespace, service, port, command, query, use case, implementation, endpoint, wire dependency, move, delete; for React: page, widget, ui-kit component, hook, page move, widget move, ui-kit component move, hook move, page delete, widget delete, ui-kit component delete, hook delete.
92
- - **Name**: the entered name; for a move `old → new`; for an implementation the contract; for wire dependency the module.
93
- - **Details**: only what changes behavior: implementation types (`(saved)` when saved for future runs), the test implementation, dependencies (`deps: OrderRepository`), environments, widget type, the endpoint's handler, whether a Next.js route moves (`route moves: /a → /b`). No file paths, no CLI menu paths.
94
- - **Why**: at most six words: why this kind of module (`choosing-components.md`).
95
- - **Writing by hand**: members, schemas, mappings. Not full code.
96
- - **Running**: every command that generates files (migrations, OpenAPI, API client, other codegen), with what it produces and when. Use the project's own scripts; find them in `package.json` and configs. Their output needs no approval of its own and is never edited; scripts that change a database are run only by the user. Details: the project's scripts skill (`project-scripts`), if there is one.
97
- - **Overwrites**, only when a run would replace existing files (`overwriteRequired` of a `dryRun`): list those files.
98
- - **Exception requests**, only for hand-created files: `<path>` (rule 2, #n) with the reason. Any other file needs its own request with a reason.
99
- - **Question**, only for open decisions that change structure or domain behavior. Open questions block approval: answers first, then the updated plan.
100
- - The last line says what reply starts the work.
101
32
  - Approval must be explicit ("ok", "да", "делай"…). A question or silence isn't approval. Changes to the plan → show the updated plan and ask again.
102
33
  - After approval, do exactly the plan. An extra module or file, or a different name/option → stop and get the delta approved. Edits to existing files needed along the way don't need approval; list them in the final report.
103
34
 
@@ -105,19 +36,19 @@ Reply "ok" to start.
105
36
 
106
37
  Every new file is created by `df-scaffold` (React modules: `df-react`). Don't create files with the Write tool, `touch`, redirects, or by copying templates. The only exceptions (`<C>` = `<rootFolder>/bounded-contexts/<context>`):
107
38
 
108
- | # | Files | Location | Condition |
109
- | --- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
111
- | 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. |
112
- | 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-react. |
113
- | 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`. |
114
- | 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. |
39
+ | # | Files | Location | Condition |
40
+ | --- | --- | --- | --- |
41
+ | 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
42
+ | 2 | Output of project tools | where the tool puts it | Migrations, codegen: run the project's script, use its output as-is; never hand-write or edit it. No approval needed for these files. |
43
+ | 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-react. |
44
+ | 4 | Widget/page/UI-kit support files | inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.tsx`, `*.stories.tsx`; next to a page: `pages/<name>-page.module.css`, for a nested page in its folder (`pages/admin/admin-users-page.module.css`) (layout of its widgets only) | Widget/page/UI-kit component generated by df-react. Details and story templates: `df-ps-react`. |
45
+ | 5 | App bootstrap and config | outside `<rootFolder>/{bounded-contexts,shared-kernel,presentation}/`: entry point, HTTP server setup registering `restHandlers`, tool configs | Bootstrapping only. Domain/application/infrastructure logic never goes there. |
115
46
 
116
- Anything else (helpers, types, constants, mappers, wiring, barrels): put it in an existing generated file, or generate a component that can host it. Editing existing files is fine. If neither works, request an exception for that exact file.
47
+ Anything else (helpers, types, constants, mappers, wiring, barrels): put it in an existing generated file, or generate a component that can host it. Stateless technical code of the infrastructure layer (mappers included) is an infrastructure helper, generated with `New Helper` (`references/units/helper.md`). Editing existing files is fine. If neither works, request an exception for that exact file.
117
48
 
118
- If the CLI cannot run, report the failure and give the user the prepared JSON command to run themselves (the menu path and answers only for a legacy CLI). Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
49
+ If the CLI cannot run, report the failure and give the user the prepared JSON command to run themselves. Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
119
50
 
120
- Moving or renaming a module (aggregate, entity, value object, service, port, query, command, use case) is a df-scaffold run, `Move or rename` (`references/units/move-or-rename.md`); a page or widget, a df-react run (`df-ps-react`). Never by hand: it creates files at the new paths, so it needs an approved plan. Deleting a module is a df-scaffold run too, `Delete` (`references/units/delete.md`): it removes files, so it needs an approved plan as well.
51
+ Moving, renaming and deleting a module go through the CLI too, never by hand, and need an approved plan: `references/units/move-or-rename.md`, `references/units/delete.md`; pages and widgets: `df-ps-react`.
121
52
 
122
53
  ### 3. New dependencies only through df-scaffold
123
54
 
@@ -125,8 +56,7 @@ With `@domain-first/wire`, every new dependency of a wired class (a constructor
125
56
 
126
57
  - List each module's dependencies in its plan row's Details (`deps: OrderRepository`); for an existing module, add a `wire dependency` row.
127
58
  - A dependency the CLI doesn't offer is forbidden by the project's dependency rules (the defaults, changed by `backend.rules.dependencies` in the config) or by context isolation: change the design (a port, a query or command, an infrastructure service) instead of adding it by hand.
128
- - A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service 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.
129
- - An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
59
+ - A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service (`references/units/services.md`). A domain or application module never gets such a value directly: it depends on a port whose adapter uses the service.
130
60
 
131
61
  ### 4. Cross-context calls stay in application port adapters
132
62
 
@@ -134,7 +64,7 @@ Details and the check script: `df-ps-implement`, "Bounded context isolation".
134
64
 
135
65
  ## Units
136
66
 
137
- One file per unit in `references/units/`: when to choose it, how to generate it (prompts, 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.
67
+ One file per unit in `references/units/`: when to choose it, how to generate it (prompts, output), how to implement and test it. Read `references/generators.md` first: it holds what all generators share (the notation the unit files use, `Dependencies:`, env-branched wiring, spec templates). Then read only the files of the units in the plan. `references/choosing-components.md` decides between units.
138
68
 
139
69
  | Unit | File | Menu |
140
70
  | --- | --- | --- |
@@ -143,6 +73,7 @@ One file per unit in `references/units/`: when to choose it, how to generate it
143
73
  | Entity, value object | `entity-value-object.md` | Domain → New Entity / New Value Object |
144
74
  | Errors | `errors.md` | Domain → Errors |
145
75
  | Domain, application, infrastructure, presentation service | `services.md` | <Layer> → New Service |
76
+ | Infrastructure helper (mapper, query builder, error translator) | `helper.md` | Infrastructure → New Helper |
146
77
  | Use case | `use-case.md` | Application → New Use Case |
147
78
  | Command, query | `command-query.md` | Application → New Command / New Query |
148
79
  | Port + adapters | `port.md` | Application → New Port |
@@ -155,52 +86,15 @@ One file per unit in `references/units/`: when to choose it, how to generate it
155
86
 
156
87
  ## Preparing runs
157
88
 
158
- - **Contexts**: subfolders of `<rootFolder>/bounded-contexts/` (menu: `Bounded Context: <name>`).
89
+ - **Contexts**: subfolders of `<rootFolder>/bounded-contexts/`.
159
90
  - **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`).
160
91
  - **Collisions**: JSON requests require `overwrite: true` to replace changed existing files. Inspect `overwriteRequired` with `dryRun: true` and include those overwrites in the plan. The interactive equivalent asks `Overwrite them?`.
161
92
  - **Tests**: with `backend.testingLibrary` set, df-scaffold always generates specs; add a test implementation (`in-memory`/`mock`) to repositories, commands/queries, and ports. Otherwise the spec wires the real one. Without `backend.testingLibrary`, tell the user once and suggest adding it with `! npx df-integration` (Vitest); don't edit the config yourself.
162
- - **Requests**: take the unit semantics and output files from its reference, then use `--describe` and `references/agent-mode.md` to build a JSON request. The scripted prompt sequences are the legacy interactive fallback.
93
+ - **Run order** in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → new implementations of existing contracts → endpoints → React (`df-ps-react`).
94
+ - **Requests**: take the unit semantics and output files from its reference, then use `--describe` and `references/agent-mode.md` to build a JSON request.
163
95
 
164
96
  ## Running non-interactively
165
97
 
166
98
  Use `npx df-scaffold --describe` and execute approved operations with `--request` JSON. React uses `df-react`; integrations use `df-integration`. Protocol, discovery IDs, previews and error handling: [references/agent-mode.md](references/agent-mode.md). Complete backend/React operation map, dependency recipes and conditional integration options: [references/agent-operations.md](references/agent-operations.md).
167
99
 
168
100
  Initialization remains a human task. No JSON initialization workflow is provided.
169
-
170
- ## Legacy interactive driver
171
-
172
- For CLI versions without JSON support, `scripts/drive.mjs` answers its prompts, then lists created (`+`) and changed (`~`) files. With `--bin df-react` it drives the React CLI instead (`df-ps-react`).
173
-
174
- ```bash
175
- node <this-skill-dir>/scripts/drive.mjs [--bin df-react] [--cwd <dir>] [--delay <ms>] <step>...
176
- node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggregate" text:order yes "pick:Enter implementation type and save for future use" text:prisma no
177
- ```
178
-
179
- | Step | Prompt | Effect |
180
- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
181
- | `pick:<label>` | select | Types a **prefix of the choice text** + Enter. Aborts before submitting if the highlighted choice doesn't match. |
182
- | `text:<v>` | input | Types a value. |
183
- | `default` | input/select | Accepts the suggested input value or the highlighted default choice. |
184
- | `yes` / `no` | confirm | |
185
- | `toggle:1,3` / `none` | checkbox | `Dependencies:`, `Dependencies for <Implementation>:`. `Suggested` items come checked: toggling unchecks. |
186
-
187
- Implementation-type menus contain saved names and active system choices, without automatic `api` or `mock` presets. Use `pick:prisma` only when saved for that category, `"pick:System: cross-context"` for a port with a neighboring context, or `"pick:System: in-memory"` for a repository/command/query with the shared DB integration ready. New ordinary names take two steps: `"pick:Enter implementation type and save for future use" text:redis` or `"pick:Enter implementation type for this run only" text:redis`. Use the complete manual-entry label to distinguish saving from run-only input. `default` accepts the selected choice.
188
-
189
- Custom types entered with the save action update `backend.implementations` in `domain-first.project-structure.config.json`; mark the type `(saved)` in the plan row's Details. The run-only action generates code without adding saved choices. These generator-managed choice updates are allowed; project/backend/frontend setup remains a human task. Changes are staged with the generated code and cancelled with it. Repository, command, query and port choices are independent; read that category's saved `primary`/`test` lists before preparing answers.
190
-
191
- Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the files its unit file lists for the planned options. "Still waiting for input" means too few steps; nothing was written. If the raw output ends at `Overwrite them?`, the run would replace files the plan's Overwrites didn't list: show the user the listed files and ask, never just add `yes`. If prompts get out of sync, retry with `--delay 1200`.
192
-
193
- ## Menu map
194
-
195
- | Layer | Bounded context | Shared Kernel |
196
- | -------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
197
- | Domain | New Aggregate, New Entity, New Value Object, Errors, New Service | New Entity, New Value Object, Errors, New Service |
198
- | Application | New Query, New Command, New Use Case, New Port, New Service | New Port, New Service |
199
- | Infrastructure | New Service, New Implementation | New Service, New Implementation |
200
- | Presentation | New Handlers-REST Endpoint (needs handlers-rest), New Service | New Service |
201
-
202
- With `@domain-first/wire`, the layer menu of a context and of the Shared Kernel also has `Wire dependency`: it adds dependencies to an existing wired module. Every layer menu has `Move or rename` and `Delete`.
203
-
204
- The main menu also has `Scaffold new bounded context`. React modules come from a separate CLI, `df-react`: see `df-ps-react`.
205
-
206
- Run order in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → new implementations of existing contracts → endpoints → React (`df-ps-react`).
@@ -1,6 +1,6 @@
1
1
  # Non-interactive operations for agents
2
2
 
3
- Prefer the JSON interface for `df-scaffold`, `df-react` and `df-integration`. Use the interactive driver only with older CLI versions that lack this interface. Initialization (`df-init`) remains a human task. The same plan, file creation and dependency rules apply to both interfaces.
3
+ Prefer the JSON interface for `df-scaffold`, `df-react` and `df-integration`. Initialization (`df-init`) remains a human task. The same plan, file creation and dependency rules apply to both interfaces.
4
4
 
5
5
  For the complete operation map, conditional integration fields and recipes, read [agent-operations.md](agent-operations.md) for the work at hand.
6
6
 
@@ -12,7 +12,7 @@ npx df-react --describe
12
12
  npx df-integration --describe
13
13
  ```
14
14
 
15
- Each command returns one JSON document with `schemaVersion: 1`, `requestSchema` and the project inventory. Use the schema from the installed version instead of guessing fields. Read `--describe` first; a valid JSON error is not a reason to fall back to the driver. Use the legacy driver only if that installed CLI does not support the flags or opens an interactive menu instead of returning JSON. Stop that discovery process before retrying with the driver; do not automatically upgrade the project package to change interfaces. Without a config it still describes the protocol; ask the owner to initialize missing sections.
15
+ Each command returns one JSON document with `schemaVersion: 1`, `requestSchema` and the project inventory. Use the schema from the installed version instead of guessing fields. Read `--describe` first. If the installed CLI doesn't support these flags, ask the owner to upgrade the package; don't upgrade it yourself. Without a config it still describes the protocol; ask the owner to initialize missing sections.
16
16
 
17
17
  - `project.contexts[].name`: a bounded context or the reserved `shared-kernel` context.
18
18
  - `modules[].id`: qualified dependency ID, e.g. `shared-kernel:PrismaInfrastructureService` or `billing:InvoiceQuery`.
@@ -19,6 +19,7 @@ All operations support `dryRun` and `overwrite`. Except `bounded-context`, they
19
19
  | `domain-service` | `name` | `dependencies`, when wiring is configured and eligible modules exist. |
20
20
  | `application-service` | `name` | `dependencies`, with the same conditions. |
21
21
  | `infrastructure-service` | `name` | `dependencies`, with the same conditions. |
22
+ | `helper` | `name`, `implementationType` | `name` may hold folders: `mappers/social-network-type`. `implementationType` is a saved or system type. See [the helper unit](units/helper.md). |
22
23
  | `presentation-service` | `name` | `dependencies`, with the same conditions. |
23
24
  | `use-case` | `name` | `dependencies`. Bounded contexts only. |
24
25
  | `command` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |