@domain-first/project-structure 6.0.0 → 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 (46) hide show
  1. package/README.md +16 -19
  2. package/dist/201.js +46 -35
  3. package/dist/287.js +1685 -1612
  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 +100 -916
  9. package/dist/index.js +6 -46
  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 +412 -33
  14. package/dist/integration.js +4 -4
  15. package/dist/integrations/in-memory-db.d.ts +6 -0
  16. package/dist/integrations/index.d.ts +2 -0
  17. package/dist/integrations/missing-domain-first-packages.d.ts +8 -0
  18. package/dist/integrations/rest-endpoint-generator.d.ts +18 -0
  19. package/dist/integrations/rest-endpoint-generator.spec.d.ts +1 -0
  20. package/dist/lint.cjs +8 -8
  21. package/dist/lint.js +7 -7
  22. package/dist/print-next-steps.d.ts +2 -2
  23. package/dist/react.cjs +915 -0
  24. package/dist/react.d.ts +2 -0
  25. package/dist/react.js +73 -0
  26. package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
  27. package/package.json +3 -1
  28. package/skills/df-ps-implement/SKILL.md +10 -55
  29. package/skills/df-ps-plan-feature/SKILL.md +6 -6
  30. package/skills/df-ps-project-scripts/SKILL.md +1 -1
  31. package/skills/df-ps-react/SKILL.md +82 -0
  32. package/skills/df-ps-react/references/generators.md +80 -0
  33. package/skills/df-ps-scaffold/SKILL.md +38 -20
  34. package/skills/df-ps-scaffold/references/choosing-components.md +7 -28
  35. package/skills/df-ps-scaffold/references/generators.md +6 -179
  36. package/skills/df-ps-scaffold/references/units/aggregate.md +47 -0
  37. package/skills/df-ps-scaffold/references/units/bounded-context.md +13 -0
  38. package/skills/df-ps-scaffold/references/units/command-query.md +32 -0
  39. package/skills/df-ps-scaffold/references/units/endpoint.md +28 -0
  40. package/skills/df-ps-scaffold/references/units/entity-value-object.md +27 -0
  41. package/skills/df-ps-scaffold/references/units/errors.md +26 -0
  42. package/skills/df-ps-scaffold/references/units/port.md +23 -0
  43. package/skills/df-ps-scaffold/references/units/services.md +28 -0
  44. package/skills/df-ps-scaffold/references/units/use-case.md +25 -0
  45. package/skills/df-ps-scaffold/references/units/wire-dependency.md +15 -0
  46. package/skills/df-ps-scaffold/scripts/drive.mjs +12 -4
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/react.js ADDED
@@ -0,0 +1,73 @@
1
+ #!/usr/bin/env node
2
+ import { parseArgs } from "node:util";
3
+ import { select as prompts_select } from "@inquirer/prompts";
4
+ import { ProjectRoot, ConfigFile, Folder } from "./201.js";
5
+ import { scaffoldReactWidget, moveReactModuleUseCase, scaffoldReactPage, scaffoldReactUIKitComponent, scaffoldReactSharedHook, savePendingChanges } from "./287.js";
6
+ const help = `Usage: df-react
7
+
8
+ Scaffolds React modules of a Domain-First project: pages, widgets, UI-kit
9
+ components and shared hooks, and moves or renames pages and widgets.
10
+ Needs "useReact": true in domain-first.project-structure.config.json.
11
+
12
+ Options:
13
+ -h, --help show this help`;
14
+ const { values: values } = parseArgs({
15
+ options: {
16
+ help: {
17
+ type: 'boolean',
18
+ short: 'h',
19
+ default: false
20
+ }
21
+ }
22
+ });
23
+ if (values.help) {
24
+ console.log(help);
25
+ process.exit(0);
26
+ }
27
+ if (!ConfigFile.exists) {
28
+ console.log('No domain-first.project-structure.config.json found: run df-init first to initialize the project.');
29
+ process.exit(1);
30
+ }
31
+ if (!ConfigFile.Instance.data.useReact) {
32
+ console.log('React is off: set "useReact": true in domain-first.project-structure.config.json or add Storybook with df-integration.');
33
+ process.exit(1);
34
+ }
35
+ const main = async ()=>{
36
+ const reactFolder = new Folder(new ProjectRoot().path).subitem([
37
+ ConfigFile.Instance.data.rootFolder,
38
+ 'presentation',
39
+ 'react'
40
+ ]);
41
+ const action = await prompts_select({
42
+ message: 'Module: ',
43
+ choices: [
44
+ 'New widget',
45
+ 'New page',
46
+ 'New UI-kit component',
47
+ 'New shared hook',
48
+ 'Move or rename widget',
49
+ 'Move or rename page'
50
+ ]
51
+ });
52
+ switch(action){
53
+ case 'New widget':
54
+ return void await scaffoldReactWidget(reactFolder);
55
+ case 'New page':
56
+ return void await scaffoldReactPage(reactFolder);
57
+ case 'New UI-kit component':
58
+ return void await scaffoldReactUIKitComponent(reactFolder);
59
+ case 'New shared hook':
60
+ return void await scaffoldReactSharedHook(reactFolder);
61
+ case 'Move or rename widget':
62
+ return void await moveReactModuleUseCase(reactFolder, 'widget');
63
+ case 'Move or rename page':
64
+ return void await moveReactModuleUseCase(reactFolder, 'page');
65
+ default:
66
+ return;
67
+ }
68
+ };
69
+ const run = async ()=>{
70
+ await main();
71
+ await savePendingChanges();
72
+ };
73
+ run();
@@ -1,6 +1,6 @@
1
1
  import { File, type Folder } from '../file-system';
2
2
  /**
3
- * The one endpoint generator of the project: a Shared Layer presentation
3
+ * The one endpoint generator of the project: a Shared Kernel presentation
4
4
  * service, scaffolded like any other. Every generating method is a getter
5
5
  * typed as `EndpointGenerator`. With `withNextAdapter`, the adapter is
6
6
  * `nextAdapter` of `@domain-first/handlers-next` instead of a placeholder.
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": "6.0.0",
4
+ "version": "7.0.0",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -16,7 +16,9 @@
16
16
  }
17
17
  },
18
18
  "bin": {
19
+ "df-init": "./dist/init.js",
19
20
  "df-scaffold": "./dist/index.js",
21
+ "df-react": "./dist/react.js",
20
22
  "df-integration": "./dist/integration.js",
21
23
  "df-skills": "./bin/df-skills.mjs",
22
24
  "df-lint": "./dist/lint.js"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: df-ps-implement
3
- description: Fill in code generated by the `df-scaffold` CLI (@domain-first/project-structure) — aggregates, entities and value objects (@domain-first/types), repositories, handler schemas (@domain-first/handlers), errors (@domain-first/errors), wiring (@domain-first/wire), handlers-rest endpoints, React modules, tests — while keeping bounded contexts isolated. Use after scaffolding, or when the user asks to implement, connect, or wire Domain-First components in a project with domain-first.project-structure.config.json.
3
+ description: Fill in code generated by the `df-scaffold` CLI (@domain-first/project-structure) — aggregates, entities and value objects (@domain-first/types), repositories, handler schemas (@domain-first/handlers), errors (@domain-first/errors), wiring (@domain-first/wire), handlers-rest endpoints, tests — while keeping bounded contexts isolated. React modules: df-ps-react. Use after scaffolding, or when the user asks to implement, connect, or wire Domain-First components in a project with domain-first.project-structure.config.json.
4
4
  ---
5
5
 
6
6
  # Implement Domain-First scaffolds
@@ -11,7 +11,7 @@ Generated files contain placeholders: empty classes, `{}` schemas, `[]` dependen
11
11
 
12
12
  - New files need an approved work plan (`df-ps-scaffold`, rule 1) and come only via df-scaffold or its listed exceptions (rule 2). Edits to existing files don't need approval; report them.
13
13
  - Keep generated names and paths: barrels, wiring, specs, and `presentation/rest/wires.ts` import them.
14
- - Layers: domain imports nothing from other layers. Application uses domain and its own abstractions. Infrastructure implements repositories, contracts, and ports, and may use application ports (of its context and the Shared Layer), never other application modules. Infrastructure needing logic from an application service means the logic is misplaced: pure logic without ports → a domain service; logic over ports → call those ports directly; technical logic (mapping, retries, formatting for an external API) → an infrastructure service. Presentation calls application handlers. Only `wiring/` knows concrete classes.
14
+ - Layers: domain imports nothing from other layers. Application uses domain and its own abstractions. Infrastructure implements repositories, contracts, and ports, and may use application ports (of its context and the Shared Kernel), never other application modules. Infrastructure needing logic from an application service means the logic is misplaced: pure logic without ports → a domain service; logic over ports → call those ports directly; technical logic (mapping, retries, formatting for an external API) → an infrastructure service. Presentation calls application handlers. Only `wiring/` knows concrete classes.
15
15
  - Constructors take abstractions (`OrderRepository`, abstract `PlaceOrderCommand`, port `PaymentGateway`), never `PrismaOrderRepository`.
16
16
  - Implementation order: domain → application → schema tool runs (migrations, only if infrastructure needs data the database lacks) → infrastructure (repositories, commands/queries, adapters) → endpoints → other tool runs (OpenAPI, API client) → React. Widgets need the regenerated client. How to run tools and handle their output: the project's scripts skill (`project-scripts`), if there is one.
17
17
  - Run the project's tsc/lint/tests after each component.
@@ -24,9 +24,9 @@ A file in context A imports **nothing** from context B: no types (`import type`
24
24
  - A needs B's data or behavior → a **query** (read) or **command** (write) in A. Its input/output are A's own models, duplicated in A's terms; B's models never appear in A.
25
25
  - Its infrastructure implementation reaches B's data **the simplest available way**: a shared database → query it directly (e.g. `prisma`); otherwise the way chosen in the plan (`df-ps-plan-feature`, step 3, rule 4), by default B's REST endpoint (`http`), like an external service. Either way it maps the result to A's models and errors and imports nothing from B. Its test implementation returns fixed data, so A's tests never run B.
26
26
  - Refer to B's entities by id only.
27
- - `shared/` may import any context's **`domain/errors`** (e.g. to map them to HTTP statuses), and nothing else from a context. The one exception: the shared in-memory DB, `shared/infrastructure/services/in-memory-db-infrastructure-service.ts`, may also import any context's **domain models** (aggregate roots, entities, value objects: the `domainType` classes under `domain/aggregates/`, `domain/entities/`, `domain/value-objects/`) to type its sections, never repository contracts or anything outside `domain/`. Don't move a context's domain concepts into `shared/` to share them between contexts; only universal entities / value objects (`money`, `email`) live there.
27
+ - `shared-kernel/` may import any context's **`domain/errors`** (e.g. to map them to HTTP statuses), and nothing else from a context. The one exception: the shared in-memory DB, `shared-kernel/infrastructure/services/in-memory-db-infrastructure-service.ts`, may also import any context's **domain models** (aggregate roots, entities, value objects: the `domainType` classes under `domain/aggregates/`, `domain/entities/`, `domain/value-objects/`) to type its sections, never repository contracts or anything outside `domain/`. Don't move a context's domain concepts into `shared-kernel/` to share them between contexts; only universal entities / value objects (`money`, `email`) live there.
28
28
  - `<rootFolder>/presentation/rest/` (the generated `wires.ts`, `index.ts`) may import every context's REST wiring.
29
- - `<rootFolder>/presentation/react/` imports **nothing** from contexts whenever it can avoid it (`ui-kit/` never does). If the project has a generated API client (orval, openapi-typescript, … from the OpenAPI document built by `generateOpenAPI`), use its hooks and types only. As a fallback, without such a client, it may import **only endpoint contract types**: `import type` from `<C>/presentation/rest/**`, e.g. `type Contract = EndpointContract<OrdersRecentGetEndpoint['handle']>`. No value imports, no `import { type X }`, nothing from other layers.
29
+ - `<rootFolder>/presentation/react/` imports **nothing** from contexts whenever it can avoid it: a generated API client first, `import type` of endpoint contracts only without one (`df-ps-react`, "Talking to the backend").
30
30
  - Need a forbidden import? A's own query or command is missing. Plan it and generate it.
31
31
 
32
32
  Check before reporting done; fix every finding:
@@ -37,7 +37,7 @@ npx df-lint [rootFolder]
37
37
 
38
38
  Run it from the project root; `rootFolder` defaults to the config's. It resolves relative paths and tsconfig `paths` aliases, checks `import`/`export … from`, side-effect imports, `import()` and `require()`, and reports:
39
39
 
40
- - imports across contexts, and from `shared/` or React outside the exceptions above;
40
+ - imports across contexts, and from `shared-kernel/` or React outside the exceptions above;
41
41
  - imports against the layers ("Ground rules"; specs excluded);
42
42
  - module files importing kinds the project's dependency rules don't allow (a use case importing a use case, a query importing a command, …), and wired dependencies they don't allow ("Wiring" below, `df-ps-scaffold` rule 3); an implementation importing its own contract is fine;
43
43
  - a widget importing another widget (a widget = the nearest folder under `presentation/react/widgets/` with a `*-widget.tsx`, nested widgets included), UI-kit importing widgets, pages or contexts, shared hooks importing UI-kit, widgets, pages or contexts;
@@ -45,39 +45,9 @@ Run it from the project root; `rootFolder` defaults to the config's. It resolves
45
45
 
46
46
  It exits with 1 when anything is found. Checks turned off in the config (`rules.lint`) aren't reported; don't turn checks off yourself.
47
47
 
48
- ## Domain
48
+ ## Units
49
49
 
50
- ```ts
51
- export class Order extends domainType(
52
- z.object({
53
- id: z.instanceof(OrderId),
54
- lines: z.array(z.instanceof(OrderLine)),
55
- status: z.enum(["open", "paid"]),
56
- }),
57
- ) {
58
- withPayment = () => {
59
- if (this.status === "paid") {
60
- throw new AlreadyPaidOrderSalesError({
61
- id: this.id.snapshot,
62
- });
63
- }
64
- return this.with({ status: "paid" });
65
- };
66
- }
67
- ```
68
-
69
- - Use the schema library the project already uses. Methods return new instances. Invalid input throws `TypeParsingError`.
70
- - Entities and value objects are `domainType(...)` classes generated by Domain → New Entity / New Value Object; inside an aggregate, the generator exports them from its `index.ts`.
71
- - Entities and value objects are rich and know nothing about storage (`df-ps-scaffold/references/choosing-components.md`): write their rules and factories as methods, using the standard library where it suffices. No repository calls, persistence fields, or storage mapping in them.
72
- - Repository contract: abstract members (`abstract findById(id: OrderId): Promise<Order | null>`, `abstract save(order: Order): Promise<void>`). Implementations map storage ⇄ aggregates. The in-memory one behaves like the real one for what tests use.
73
- - Errors: `.define<{ orderId: string }>('not-found')` for details; throw `new XError({...})`; recognize with `XError.is(e)`, or `XError.matchesCode(data)` after serialization.
74
-
75
- ## Application
76
-
77
- - Use cases, commands, queries ({handlers}): the member is `handle = defineHandler({ inputSchema, outputSchema, handler })`. Replace the static `{}` schemas with real ones and write the logic in the `handler` callback; dependencies come through the constructor. Commands and queries: the abstract contract holds the static schemas and `abstract handle`; each infrastructure implementation defines `handle` with the contract's schemas and writes only its `handler` callback. A command or query implementation performs one atomic operation: one database operation (one transaction at most), one API request; no business logic and no steps around it. Its only wired dependencies are infrastructure services (the client it runs on); repositories, ports and domain services stay with the use case. Needing more → it's several commands/queries, composed in the use case (in an application service only when 2+ use cases share that composition). Call with `x.handle(input)` (returns a result) or `x.handle.unsafe(input)` (throws).
78
- - A query only reads: it never changes data (not even idempotently) and never uses a command; see "Commonly confused" in `df-ps-scaffold/references/choosing-components.md`. A command returns nothing or only the minimum needed to use its result later (e.g. the created ID), in its output schema; data to show after it comes from a query.
79
- - Ports: abstract members in the port, one implementation per adapter (`api` real, `mock`/`fake` deterministic). Use the shared `clock` port instead of `new Date()`.
80
- - Services: what each kind may contain and call is in `choosing-components.md` (steps 12–15, "Port or service?"). Domain services take and return domain types. Application services have no `handle`.
50
+ How to fill in each unit (aggregate, entity, value object, errors, services, use case, command, query, port, endpoint) is in the "Implement" and "Test" sections of `df-ps-scaffold/references/units/<unit>.md`. Read the files of the units you implement; the rules below apply to all of them.
81
51
 
82
52
  ## Wiring ({wire})
83
53
 
@@ -92,29 +62,14 @@ export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [
92
62
 
93
63
  - Use the injected dependencies in the class body; don't edit the parameter list or the wire list.
94
64
  - Env-branched files (repositories, commands/queries, ports): each `wire<Impl>Implementation` has its own dependencies, added per implementation. `NODE_ENV=test` selects the test one; vitest sets it.
95
- - External clients and config values: an infrastructure service named after the implementation label creates or reads them (`readonly client = new PrismaClient()`); wrap its wire in `memoWire(...)` when the instance must be shared. Implementations depend on that service, never on a `wireValue(...)`.
65
+ - External clients and config values: an infrastructure service ([services](../df-ps-scaffold/references/units/services.md)), never a `wireValue(...)`.
96
66
  - A needed dependency the CLI doesn't offer: see rule 3 (change the design).
97
67
 
98
- ## REST endpoints ({handlers-rest})
99
-
100
- 1. Generator: initialization creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared/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 initialization connected the Next adapter, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed. 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 to statuses in the generator's `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/` may import from a context, besides domain models in the in-memory DB). 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`. Generate the exposed handler before the endpoint: with wire, the `Handler:` pick fills its type and the wire (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`).
101
- 2. If `handler: never` is left (no handler existed at generation), re-run the endpoint generator as an approved overwrite to pick it (rule 3); don't replace it by hand.
102
- 3. Complete `get handle()`: the generated `this.endpointGenerator(...)` doesn't compile on purpose. Pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`.
103
- 4. Register `restHandlers` from `<rootFolder>/presentation/rest/index.ts` in the server bootstrap (rule 2, exception 5).
104
-
105
68
  ## React
106
69
 
107
- - Separated UI widget: state, effects, and derived data in `hooks/use-<name>-ui-model.ts` (props → UI props); `ui/` stays presentational. Headless: the same hook, and the consumer passes `UI`.
108
- - Widgets never import other widgets (their component, `ui/`, `hooks/` or `types.ts`). Shared markup → UI-kit, shared logic → a shared hook, combining widgets → the page.
109
- - UI-kit components: presentational, driven only by props; no API client, no data loading, no imports from widgets, pages, or contexts. Other UI-kit components and shared hooks (`hooks/`) are fine. Business terms only in a domain UI-kit component — an element several widgets repeat whole (`references/choosing-components.md` in `df-ps-scaffold`); its props describe what it shows, not domain types.
110
- - Shared hooks (`…/presentation/react/hooks/use-<name>.ts`): generic app-wide logic, driven only by arguments; no business terms, no API client, no imports from UI-kit, widgets, pages, or contexts.
111
- - Stories (`storybookFramework`): fill `args` of `Default` with valid props and add one story per meaningful state (`Disabled`, `Loading`, `WithError`). Keep `meta`, the file name, and the title (`UI-kit/N` or `Widgets/N`). For widget UI, the stories cover the UI states that its UI model produces.
112
- - Extra hooks, UI parts, styles, and stories: rule 2, exceptions 3–4.
113
- - Moving or renaming a page or widget (files, code names, imports): only with df-scaffold, `Move or rename page` / `Move or rename widget` (`df-ps-scaffold`, rule 2).
114
- - Talk to the backend over HTTP. First look for a generated API client (orval config, `openapi-typescript` output, generated `*.gen.ts` / `api/` folders) and use it, importing nothing from contexts. Only without one, take types from endpoint contracts (`import type`, see "Bounded context isolation"). Regenerating the client is tool output (rule 2, exception 2).
70
+ Pages, widgets, UI-kit components, shared hooks and stories, and how they reach the backend: `df-ps-react`.
115
71
 
116
72
  ## Tests
117
73
 
118
- - Entities and value objects: extend their generated `<name>.entity.spec.ts` / `<name>.value-object.spec.ts` with their rules (e.g. rating is 1–5).
119
- - Generated specs only check construction. Extend them in the same file with behavior tests: aggregate rules, repository contracts against the test implementation, handlers via `handle(...)`.
74
+ - Generated specs only check construction. Extend them in the same file with behavior tests; what to test per unit: its unit file.
120
75
  - Missing spec: create it from "Spec templates" in `df-ps-scaffold/references/generators.md` (exception 1). Don't re-run the generator: it would overwrite the implementation. Never delete generated specs.
@@ -9,21 +9,21 @@ Understand → decompose → assign → get approval → hand off. A feature cre
9
9
 
10
10
  ## 1. Understand what exists
11
11
 
12
- Read the config, then build an overview of the contexts and `shared/` from existing architecture docs and a file inventory:
12
+ Read the config, then build an overview of the contexts and `shared-kernel/` from existing architecture docs and a file inventory:
13
13
 
14
14
  ```bash
15
- rg --files <rootFolder>/bounded-contexts <rootFolder>/shared
15
+ rg --files <rootFolder>/bounded-contexts <rootFolder>/shared-kernel
16
16
  ```
17
17
 
18
18
  Use the overview to identify likely owners and related contexts. Search for the feature's domain terms and synonyms; don't infer ownership from folder names alone.
19
19
 
20
- Read the relevant code in the affected contexts: aggregates and their rules, use cases, commands/queries, ports, and behavior tests. Follow their dependencies into adapters, wiring, relevant `shared/` components, and the REST endpoints of any providing context. Note how contexts can reach each other: which database each one uses, and any message queue, RPC, or event setup. Expand the search when ownership or a dependency remains unclear; unrelated implementations do not need a full read.
20
+ Read the relevant code in the affected contexts: aggregates and their rules, use cases, commands/queries, ports, and behavior tests. Follow their dependencies into adapters, wiring, relevant `shared-kernel/` components, and the REST endpoints of any providing context. Note how contexts can reach each other: which database each one uses, and any message queue, RPC, or event setup. Expand the search when ownership or a dependency remains unclear; unrelated implementations do not need a full read.
21
21
 
22
22
  For each affected context, note what it owns, what it does, its language, and the ports and other-context queries/commands involved in the feature. Stop expanding when you can justify ownership, identify reusable components, and verify both sides of each required cross-context interaction. Mark unresolved assumptions in the plan. If there are no contexts yet, propose an initial split in step 3.
23
23
 
24
24
  ## 2. Decompose
25
25
 
26
- Split the request into pieces of logic and choose each piece's component with `df-ps-scaffold/references/choosing-components.md`. Record the deciding step for the "Why" in the plan: `choosing-components, step N` for a component, `step 3, rule N` (below) for a placement.
26
+ Split the request into pieces of logic and choose each piece's component with `df-ps-scaffold/references/choosing-components.md` (pieces of UI: `df-ps-react`, "Choosing the module"). Record the deciding step for the "Why" in the plan: `choosing-components, step N` for a component, `step 3, rule N` (below) for a placement.
27
27
 
28
28
  ## 3. Assign to contexts
29
29
 
@@ -36,7 +36,7 @@ Split the request into pieces of logic and choose each piece's component with `d
36
36
  - Nothing besides REST → the providing context's REST endpoint (`http`).
37
37
 
38
38
  Unless it's the database, 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.
39
- 5. `shared/` 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.
39
+ 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.
40
40
  6. Names: kebab-case, in the context's language. Contexts are business areas (`sales`, `reviews`), not features.
41
41
 
42
42
  If two placements are plausible, ask the user and give your recommendation.
@@ -49,7 +49,7 @@ Find out why, then act:
49
49
  - **The logic spans several contexts** (e.g. "cancel only if not shipped and refunded"). It's a process: each context owns its part, and the initiating context gets the coordinating use case and reaches the others through its own queries and commands.
50
50
  - **Nobody knows, including the user.** Pick a reversible default: the initiating or closest context, other contexts behind its own queries and commands, and mark it **(provisional)** with the reason.
51
51
 
52
- Never: pick silently, put one context's domain logic in `shared/`, create a catch-all context (`common`, `core`, `misc`), or split arbitrarily.
52
+ Never: pick silently, put one context's domain logic in `shared-kernel/`, create a catch-all context (`common`, `core`, `misc`), or split arbitrarily.
53
53
 
54
54
  ## 4. Present the plan
55
55
 
@@ -15,7 +15,7 @@ The project's scripts live in `package.json`. Run them through `npm run <script>
15
15
 
16
16
  ## Prisma
17
17
 
18
- Config: `shared/infrastructure/prisma/prisma.config.ts`. Source: `shared/infrastructure/prisma/contract.prisma` (edit by hand). Output: `contract.json`, `contract.d.ts` (from `prisma:emit`) and `migrations/` (from `prisma:migration:plan`), all next to it. The client is created in `shared/infrastructure/services/prisma-infrastructure-service.ts`.
18
+ Config: `shared-kernel/infrastructure/prisma/prisma.config.ts`. Source: `shared-kernel/infrastructure/prisma/contract.prisma` (edit by hand). Output: `contract.json`, `contract.d.ts` (from `prisma:emit`) and `migrations/` (from `prisma:migration:plan`), all next to it. The client is created in `shared-kernel/infrastructure/services/prisma-infrastructure-service.ts`.
19
19
 
20
20
  | Script | Does | Who runs it |
21
21
  | ------------------------ | ------------------------------------------------------------------------- | ----------------- |
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: df-ps-react
3
+ description: Build the React part of a Domain-First project with the `df-react` CLI (@domain-first/project-structure) — choose between pages, widgets (separated UI, headless, monolithic), UI-kit components and shared hooks, generate them with Storybook stories, move or rename pages and widgets, and implement them against the backend without importing bounded contexts. Use when the project has domain-first.project-structure.config.json with "useReact": true and the user asks for screens, UI blocks, components, hooks or stories, or to move, rename or regroup a page or widget.
4
+ ---
5
+
6
+ # React modules with df-react
7
+
8
+ React modules live in `<rootFolder>/presentation/react/` (`…/react/` below) and come only from `df-react`. The mandatory rules of `df-ps-scaffold` apply here too: an approved work plan before any new file (rule 1), new files only through the CLI or its listed exceptions (rule 2).
9
+
10
+ ## Workflow
11
+
12
+ 1. Read `domain-first.project-structure.config.json`. Without it, tell the user to run `npx df-init`. With `"useReact": false`, `df-react` refuses to run: tell the user to turn React on (or add Storybook with `! npx df-integration`); don't edit the config yourself.
13
+ 2. A feature that also needs backend work → plan it with `df-ps-plan-feature`; React runs come last in the plan.
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`.
16
+ 5. Run the generators with the driver in plan order (shared hooks → UI-kit → widgets → pages); check each output.
17
+ 6. Implement ("Implementing"), after the backend and the regenerated API client.
18
+ 7. Run `npx df-lint` and the project's tsc/lint/tests. Report against the plan.
19
+
20
+ ## Choosing the module
21
+
22
+ | Piece | Module |
23
+ | --- | --- |
24
+ | A route / whole screen | **Page** |
25
+ | A block with business meaning or backend data (`cart`, `order-summary`) | **Widget** |
26
+ | A generic element with no business meaning, driven only by props (`button`, `date-picker`, `modal`) | **UI-kit component** |
27
+ | A business element that several widgets repeat whole, with the same meaning (`product-card`) | **UI-kit component** (domain) |
28
+ | Generic app-wide logic without markup and business meaning (`debounce`, `media-query`, `local-storage`) | **Shared hook** |
29
+
30
+ 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.
31
+
32
+ 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.
33
+
34
+ **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.
35
+
36
+ **Widget type.** 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.
37
+
38
+ **Folders.** 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 module'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`).
39
+
40
+ **Names**: lowercase kebab-case, no suffix (`cart`, not `cart-widget`); page and widget names may have folders before them, each segment kebab-case.
41
+
42
+ ## Running df-react
43
+
44
+ `df-react` is interactive. Drive it with the driver of `df-ps-scaffold` and `--bin df-react`; it answers the prompts, then lists created (`+`) and changed (`~`) files:
45
+
46
+ ```bash
47
+ node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react [--cwd <dir>] [--delay <ms>] <step>...
48
+ node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react "pick:New widget" text:cart "pick:with separated ui"
49
+ ```
50
+
51
+ Steps and checks are the same as for `df-scaffold` ("Running the 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`. Prompts and output of each: `references/generators.md`.
52
+
53
+ If the CLI can't run, give the user the menu path and answers to run `! npx df-react` themselves. Never hand-write its output.
54
+
55
+ ### Moving and renaming
56
+
57
+ Moving or renaming a page or widget is a df-react run (`Move or rename page` / `Move or rename widget`): it creates the files at the new paths, so it needs an approved plan. 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-react 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 (`~`).
58
+
59
+ ### Files you may create by hand
60
+
61
+ Only these (`df-ps-scaffold`, rule 2, exceptions 3–4), for modules generated by df-react:
62
+
63
+ - Widget hooks and UI parts: `…/react/widgets/<name>/hooks/**`, `ui/**`.
64
+ - Support files inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.tsx`, `*.stories.tsx`. A missing UI-kit or widget UI story: exactly from "Story templates" in `references/generators.md`.
65
+ - Next to a page: `pages/<name>-page.module.css` (for a nested page in its folder: `pages/admin/admin-users-page.module.css`), for the layout of its widgets only. A page stays one file that composes widgets; no page tests. Its own hooks, UI parts, types, or styles for how a block looks mean a widget is missing, so generate it.
66
+
67
+ ## Implementing
68
+
69
+ - Separated UI widget: state, effects, and derived data in `hooks/use-<name>-ui-model.ts` (props → UI props); `ui/` stays presentational. Headless: the same hook, and the consumer passes `UI`.
70
+ - Widgets never import other widgets (their component, `ui/`, `hooks/` or `types.ts`). Shared markup → UI-kit, shared logic → a shared hook, combining widgets → the page.
71
+ - UI-kit components: presentational, driven only by props; no API client, no data loading, no imports from widgets, pages, or contexts. Other UI-kit components and shared hooks (`hooks/`) are fine. Business terms only in a domain UI-kit component; its props describe what it shows, not domain types.
72
+ - Shared hooks (`…/react/hooks/use-<name>.ts`): generic app-wide logic, driven only by arguments; no business terms, no API client, no imports from UI-kit, widgets, pages, or contexts.
73
+ - Stories (`storybookFramework`): fill `args` of `Default` with valid props and add one story per meaningful state (`Disabled`, `Loading`, `WithError`). Keep `meta`, the file name, and the title (`UI-kit/N` or `Widgets/N`). For widget UI, the stories cover the UI states that its UI model produces.
74
+
75
+ ### Talking to the backend
76
+
77
+ `…/react/` imports **nothing** from bounded contexts whenever it can avoid it (`ui-kit/` never does). Talk to the backend over HTTP:
78
+
79
+ 1. First look for a generated API client (orval config, `openapi-typescript` output, generated `*.gen.ts` / `api/` folders) and use its hooks and types. Regenerating it is tool output (`df-ps-scaffold`, rule 2, exception 2); widgets need it regenerated after new endpoints. No client yet and the project has `handlers-rest` → suggest the Orval integration (`! npx df-integration`).
80
+ 2. Only without such a client, take types from endpoint contracts: `import type` from `<C>/presentation/rest/**`, e.g. `type Contract = EndpointContract<OrdersRecentGetEndpoint['handle']>`. No value imports, no `import { type X }`, nothing from other layers.
81
+
82
+ `npx df-lint` reports a widget importing another widget, UI-kit importing widgets, pages or contexts, shared hooks importing UI-kit, widgets, pages or contexts, and React importing contexts beyond the contract types. Fix every finding.
@@ -0,0 +1,80 @@
1
+ # df-react generators: prompts and output
2
+
3
+ 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).
4
+
5
+ ## New page
6
+
7
+ `"pick:New page" text:checkout` → `…/react/pages/n-page.tsx`
8
+
9
+ ## New widget
10
+
11
+ `"pick:New widget" text:cart "pick:with separated ui"` → `…/react/widgets/n/`:
12
+
13
+ - `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`)
14
+ - `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
15
+ - `monolithic`: `n-widget.tsx`
16
+ - every type: `index.ts` (`export * from './n-widget'`)
17
+
18
+ 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.
19
+
20
+ ## Move or rename page / widget
21
+
22
+ 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.
23
+
24
+ ## New UI-kit component
25
+
26
+ `"pick:New UI-kit" text:date-picker` → `…/react/ui-kit/n/`:
27
+
28
+ - `n.tsx` (`type NProps`, `const N: FC<NProps>`)
29
+ - `index.ts` (`export * from './n'`)
30
+ - with `storybookFramework`: `n.stories.tsx` (CSF3: `meta` with `title: 'UI-kit/N'`, story `Default`)
31
+
32
+ No Storybook prompt: UI-kit and widget UI stories follow the config.
33
+
34
+ ## New shared hook
35
+
36
+ `"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.
37
+
38
+ ## Story templates
39
+
40
+ Only for recreating a **missing** story (`df-ps-scaffold`, rule 2, exception 4).
41
+
42
+ UI-kit, at `…/react/ui-kit/n/n.stories.tsx`:
43
+
44
+ ```tsx
45
+ import type { Meta, StoryObj } from "<storybookFramework>";
46
+ import { N } from "./n";
47
+
48
+ const meta = {
49
+ title: "UI-kit/N",
50
+ component: N,
51
+ } satisfies Meta<typeof N>;
52
+
53
+ export default meta;
54
+
55
+ type Story = StoryObj<typeof meta>;
56
+
57
+ export const Default: Story = {
58
+ args: {},
59
+ };
60
+ ```
61
+
62
+ Widget UI (`with separated ui` only), at `…/react/widgets/n/ui/n-widget-ui.stories.tsx`:
63
+
64
+ ```tsx
65
+ import type { Meta, StoryObj } from "<storybookFramework>";
66
+ import { NWidgetUI } from "./n-widget-ui";
67
+
68
+ const meta = {
69
+ title: "Widgets/N",
70
+ component: NWidgetUI,
71
+ } satisfies Meta<typeof NWidgetUI>;
72
+
73
+ export default meta;
74
+
75
+ type Story = StoryObj<typeof meta>;
76
+
77
+ export const Default: Story = {
78
+ args: {},
79
+ };
80
+ ```
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: df-ps-scaffold
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, 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-scaffold) that the other df-scaffold 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
6
  # Scaffold components with df-scaffold
@@ -9,13 +9,13 @@ description: Generate Domain-First components with the `df-scaffold` CLI (@domai
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-scaffold` 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
 
@@ -52,7 +52,7 @@ Tool runs:
52
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.
@@ -61,21 +61,21 @@ Tool runs:
61
61
 
62
62
  ### 2. New files only through df-scaffold
63
63
 
64
- Every new file is created by `df-scaffold`. 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-scaffold. |
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-scaffold. 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-scaffold` themselves (`! npx df-scaffold`). 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-scaffold 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-scaffold 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
80
  ### 3. New dependencies only through df-scaffold
81
81
 
@@ -90,20 +90,38 @@ With `@domain-first/wire`, every new dependency of a wired class (a constructor
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
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.
99
- - **Prompts**: take the exact sequence for the generator and config from `references/generators.md`.
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-scaffold` 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`).