@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.
- package/README.md +16 -19
- package/dist/201.js +46 -35
- package/dist/287.js +1685 -1612
- package/dist/config-file.d.ts +2 -2
- package/dist/dependency-rules.d.ts +1 -1
- package/dist/file-system.d.ts +5 -0
- package/dist/in-memory-db.d.ts +5 -0
- package/dist/index.cjs +100 -916
- package/dist/index.js +6 -46
- package/dist/init.cjs +868 -0
- package/dist/init.d.ts +2 -0
- package/dist/init.js +36 -0
- package/dist/integration.cjs +412 -33
- package/dist/integration.js +4 -4
- package/dist/integrations/in-memory-db.d.ts +6 -0
- package/dist/integrations/index.d.ts +2 -0
- package/dist/integrations/missing-domain-first-packages.d.ts +8 -0
- package/dist/integrations/rest-endpoint-generator.d.ts +18 -0
- package/dist/integrations/rest-endpoint-generator.spec.d.ts +1 -0
- package/dist/lint.cjs +8 -8
- package/dist/lint.js +7 -7
- package/dist/print-next-steps.d.ts +2 -2
- package/dist/react.cjs +915 -0
- package/dist/react.d.ts +2 -0
- package/dist/react.js +73 -0
- package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
- package/package.json +3 -1
- package/skills/df-ps-implement/SKILL.md +10 -55
- package/skills/df-ps-plan-feature/SKILL.md +6 -6
- package/skills/df-ps-project-scripts/SKILL.md +1 -1
- package/skills/df-ps-react/SKILL.md +82 -0
- package/skills/df-ps-react/references/generators.md +80 -0
- package/skills/df-ps-scaffold/SKILL.md +38 -20
- package/skills/df-ps-scaffold/references/choosing-components.md +7 -28
- package/skills/df-ps-scaffold/references/generators.md +6 -179
- package/skills/df-ps-scaffold/references/units/aggregate.md +47 -0
- package/skills/df-ps-scaffold/references/units/bounded-context.md +13 -0
- package/skills/df-ps-scaffold/references/units/command-query.md +32 -0
- package/skills/df-ps-scaffold/references/units/endpoint.md +28 -0
- package/skills/df-ps-scaffold/references/units/entity-value-object.md +27 -0
- package/skills/df-ps-scaffold/references/units/errors.md +26 -0
- package/skills/df-ps-scaffold/references/units/port.md +23 -0
- package/skills/df-ps-scaffold/references/units/services.md +28 -0
- package/skills/df-ps-scaffold/references/units/use-case.md +25 -0
- package/skills/df-ps-scaffold/references/units/wire-dependency.md +15 -0
- package/skills/df-ps-scaffold/scripts/drive.mjs +12 -4
package/dist/react.d.ts
ADDED
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
|
|
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": "
|
|
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,
|
|
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
|
|
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
|
|
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
|
-
##
|
|
48
|
+
## Units
|
|
49
49
|
|
|
50
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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-
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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-
|
|
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-
|
|
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`).
|
|
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
|
|
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
|
|
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
|
|
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 (
|
|
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`).
|