@domain-first/project-structure 5.1.2 → 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 +18 -21
- package/dist/201.js +46 -35
- package/dist/287.js +3290 -0
- 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 +195 -2156
- package/dist/index.js +9 -3169
- package/dist/init.cjs +868 -0
- package/dist/init.d.ts +2 -0
- package/dist/init.js +36 -0
- package/dist/integration.cjs +2063 -0
- package/dist/integration.d.ts +2 -0
- package/dist/integration.js +31 -0
- 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/orval.d.ts +7 -4
- 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 +9 -2
- package/dist/react.cjs +915 -0
- package/dist/react.d.ts +2 -0
- package/dist/react.js +73 -0
- package/dist/use-cases/add-integration-order.spec.d.ts +1 -0
- package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
- package/package.json +5 -2
- package/skills/df-ps-implement/SKILL.md +12 -57
- package/skills/df-ps-plan-feature/SKILL.md +7 -7
- 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 +46 -28
- 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();
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -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,10 @@
|
|
|
16
16
|
}
|
|
17
17
|
},
|
|
18
18
|
"bin": {
|
|
19
|
-
"df-
|
|
19
|
+
"df-init": "./dist/init.js",
|
|
20
|
+
"df-scaffold": "./dist/index.js",
|
|
21
|
+
"df-react": "./dist/react.js",
|
|
22
|
+
"df-integration": "./dist/integration.js",
|
|
20
23
|
"df-skills": "./bin/df-skills.mjs",
|
|
21
24
|
"df-lint": "./dist/lint.js"
|
|
22
25
|
},
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: df-ps-implement
|
|
3
|
-
description: Fill in code generated by the `df-
|
|
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
|
|
@@ -9,9 +9,9 @@ Generated files contain placeholders: empty classes, `{}` schemas, `[]` dependen
|
|
|
9
9
|
|
|
10
10
|
## Ground rules
|
|
11
11
|
|
|
12
|
-
- New files need an approved work plan (`df-ps-scaffold`, rule 1) and come only via df-
|
|
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,43 +45,13 @@ 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
|
|
|
84
|
-
Dependencies (constructor parameters and their wires) are added only by `df-
|
|
54
|
+
Dependencies (constructor parameters and their wires) are added only by `df-scaffold` (`df-ps-scaffold`, rule 3): the generator's `Dependencies:` step or `Wire dependency`. It keeps each `wireClass(X, [...])` in the order of the constructor, which TypeScript checks:
|
|
85
55
|
|
|
86
56
|
```ts
|
|
87
57
|
export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [
|
|
@@ -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-ps, `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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: df-ps-plan-feature
|
|
3
|
-
description: Turn an abstract feature request into a Domain-First plan for a project using `df-
|
|
3
|
+
description: Turn an abstract feature request into a Domain-First plan for a project using `df-scaffold` (@domain-first/project-structure) — decide which bounded contexts own what and which components are needed, then get the user's approval before generating anything. Use when the project has domain-first.project-structure.config.json and the user describes a feature ("add product reviews", "let users cancel orders") without naming bounded contexts or exact components.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Plan a feature
|
|
@@ -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
|
+
```
|