@domain-first/project-structure 8.6.0 → 8.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bin/df-skills.mjs +55 -9
- package/dist/287.js +54 -2
- package/dist/38.js +36 -0
- package/dist/561.js +9 -1
- package/dist/780.js +2 -1
- package/dist/947.js +11 -1
- package/dist/agent-cli.d.ts +9 -2
- package/dist/agent-principles.cjs +116 -0
- package/dist/agent-principles.d.ts +9 -0
- package/dist/agent-principles.js +64 -0
- package/dist/agent-principles.spec.d.ts +1 -0
- package/dist/agent-requests.d.ts +16 -2
- package/dist/file-system.d.ts +2 -1
- package/dist/graph.cjs +12 -1
- package/dist/index.cjs +76 -2
- package/dist/index.js +4 -1
- package/dist/init.cjs +14 -3
- package/dist/integration.cjs +73 -2
- package/dist/lint.cjs +48 -1
- package/dist/react.cjs +73 -2
- package/dist/upgrade.cjs +21 -13
- package/dist/upgrade.js +19 -12
- package/dist/use-cases/add-integration.d.ts +1 -1
- package/dist/use-cases/index.d.ts +1 -0
- package/dist/use-cases/scaffold-new-infrastructure-helper.d.ts +7 -0
- package/dist/wiring.d.ts +2 -2
- package/package.json +3 -2
- package/principles/df-principles.md +33 -0
- package/skills/df-ps-implement/SKILL.md +26 -1
- package/skills/df-ps-plan-feature/SKILL.md +22 -18
- package/skills/df-ps-react/SKILL.md +2 -9
- package/skills/df-ps-react/references/generators.md +9 -9
- package/skills/df-ps-scaffold/SKILL.md +19 -125
- package/skills/df-ps-scaffold/references/agent-mode.md +2 -2
- package/skills/df-ps-scaffold/references/agent-operations.md +1 -0
- package/skills/df-ps-scaffold/references/choosing-components.md +65 -49
- package/skills/df-ps-scaffold/references/generators.md +28 -5
- package/skills/df-ps-scaffold/references/units/aggregate.md +1 -3
- package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
- package/skills/df-ps-scaffold/references/units/command-query.md +4 -6
- package/skills/df-ps-scaffold/references/units/delete.md +0 -2
- package/skills/df-ps-scaffold/references/units/endpoint.md +1 -4
- package/skills/df-ps-scaffold/references/units/entity-value-object.md +0 -4
- package/skills/df-ps-scaffold/references/units/errors.md +0 -4
- package/skills/df-ps-scaffold/references/units/helper.md +30 -0
- package/skills/df-ps-scaffold/references/units/implementation.md +0 -4
- package/skills/df-ps-scaffold/references/units/move-or-rename.md +0 -4
- package/skills/df-ps-scaffold/references/units/port.md +2 -5
- package/skills/df-ps-scaffold/references/units/services.md +2 -4
- package/skills/df-ps-scaffold/references/units/use-case.md +1 -2
- package/skills/df-ps-scaffold/references/units/wire-dependency.md +0 -2
- package/skills/df-ps-scaffold/references/work-plan.md +73 -0
- package/skills/df-ps-scaffold/scripts/drive.mjs +0 -252
|
@@ -6,27 +6,27 @@ Split the request into pieces of logic (one responsibility each). For each piece
|
|
|
6
6
|
|
|
7
7
|
## Procedure
|
|
8
8
|
|
|
9
|
-
| #
|
|
10
|
-
| --- |
|
|
11
|
-
| 1
|
|
12
|
-
| 2
|
|
13
|
-
| 3
|
|
14
|
-
| 4
|
|
15
|
-
| 5
|
|
16
|
-
| 6
|
|
17
|
-
| 7
|
|
18
|
-
| 8
|
|
19
|
-
| 9
|
|
20
|
-
| 10
|
|
21
|
-
| 11
|
|
22
|
-
| 12
|
|
23
|
-
| 13
|
|
24
|
-
| 14
|
|
25
|
-
| 15
|
|
26
|
-
| —
|
|
9
|
+
| # | Question | Component |
|
|
10
|
+
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| 1 | A business failure callers must recognize? | **Errors** (Domain → Errors) |
|
|
12
|
+
| 2 | An HTTP entry point? | **REST endpoint** (Presentation; needs handlers-rest) |
|
|
13
|
+
| 3 | A screen, UI block, or app-wide React hook? | **React page / widget / UI-kit component / shared hook**. Which one: `df-ps-react` |
|
|
14
|
+
| 4 | A thing with identity, lifecycle, and rules about its own state, **owned by this context** and stored on its own? | **Aggregate** (+ repository) |
|
|
15
|
+
| 5 | An entity or value object used **only inside one** aggregate (an entity inside it, or a value like `order-id` used only by `order`)? | **Entity / value object** (Domain → New Entity / New Value Object, pick that aggregate) |
|
|
16
|
+
| 6 | An entity or value object used by **several** aggregates or by a domain service? | **Entity / value object** (Domain → New Entity / New Value Object, `No aggregate`). Universal ones (see "Where it goes") in Shared Kernel |
|
|
17
|
+
| 7 | A rule about one aggregate's own state, including the junction of entities / value objects that all belong to it? | **Method on the aggregate**. No new file |
|
|
18
|
+
| 8 | One business action a user/system triggers that doesn't fit into a single query or command? (Its I/O is separate pieces.) | **Use case**. An action that is exactly one query or command gets none (see below) |
|
|
19
|
+
| 9 | Data or behavior of **another context**? | **Application port** in this context, with an adapter for the interaction (see below) |
|
|
20
|
+
| 10 | Leaves this context's code and storage: external system or time? | **Port** (+ adapters) |
|
|
21
|
+
| 11 | One atomic read/write on this context's own storage that doesn't load aggregates to change them or check their rules (read model, data for a reader, report, bulk update)? | **Command** (write) / **query** (read) |
|
|
22
|
+
| 12 | A rule at the junction of several entities / value objects not all belonging to one aggregate (a discount from purchase history and the current discount), no I/O? | **Domain service**, always. It takes the aggregates and values it needs as arguments; loading them is the caller's job (use case, application service) |
|
|
23
|
+
| 13 | Application logic reused by 2+ use cases, with any external interaction or storage access delegated to injected ports, commands or queries? | **Application service** |
|
|
24
|
+
| 14 | A technical helper used only by infrastructure code? | Stateless, no dependencies and for one implementation type (mapper, query builder, error translator): **Infrastructure helper**. Otherwise, including code shared by several types: **Infrastructure service** |
|
|
25
|
+
| 15 | A helper used only by presentation code? | **Presentation service** |
|
|
26
|
+
| — | None of the above | A method or function in an existing file |
|
|
27
27
|
|
|
28
28
|
- Entities and value objects are **rich**: rules about their own data, including how they are created, are their methods. They never know about their storage or loading: that's repositories and queries/commands.
|
|
29
|
-
-
|
|
29
|
+
- Decide by what the result is for. A **repository method** loads aggregates in order to change them or check their rules, and saves them. A **query** returns data to a reader as a DTO of its own, never a domain model, even when it is the data of one aggregate: showing a post by id is a query, editing it is a use case that loads the post through the repository, calls its method and saves it.
|
|
30
30
|
- A query or command is **one atomic operation of one kind of implementation**: one operation on this context's own storage (several statements in one transaction count as one). Its implementations differ in how they perform that operation (`prisma`, `in-memory`). Neighboring contexts and external systems are reached through ports. Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in the use case that needs them; only when 2+ use cases need the same composition does it move to an application service (step 13).
|
|
31
31
|
- **No proxy use cases.** Every query and command is a handler, so an endpoint uses it directly. A use case that only forwards the call to one query or command adds nothing: don't create it. A use case appears only when the action needs several queries, commands or ports, or logic around them. An endpoint that needs a port uses a use case as its handler: ports have capability methods, not `handle`. A use case whose logic lives in an application service is not a proxy: an application service has no `handle`, so the use case is how an endpoint reaches that logic.
|
|
32
32
|
- A rule about a **set** of aggregates (uniqueness, "at most N per day") = a repository method that queries it, plus a check and a domain error in the use case. No separate component.
|
|
@@ -45,41 +45,57 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
45
45
|
|
|
46
46
|
## Commonly confused
|
|
47
47
|
|
|
48
|
-
| Pair
|
|
49
|
-
|
|
|
50
|
-
| Port / repository
|
|
51
|
-
| Port / command, query
|
|
52
|
-
| Port with one method / query
|
|
53
|
-
| Query / command
|
|
54
|
-
| Domain service / entity, value object method
|
|
55
|
-
| Domain / application service
|
|
56
|
-
| Use case / application service
|
|
57
|
-
| Application / infrastructure service
|
|
58
|
-
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service.
|
|
59
|
-
| Clock
|
|
60
|
-
| Configuration
|
|
48
|
+
| Pair | Rule |
|
|
49
|
+
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| Port / repository | Own aggregate's persistence → repository. Another context or external system → port. |
|
|
51
|
+
| Port / command, query | Own storage → command/query. Another context or external system → port. |
|
|
52
|
+
| Port with one method / query | Decided by what's on the other side, not by the number of methods: a single read from an external system is still a port. Another context = a folder in `bounded-contexts/` of this project; any other service (another team's API, a SaaS) is an external system → port. |
|
|
53
|
+
| Query / command | A query only reads: it never changes any state, not even idempotently (no cache filling, no default settings created if missing), and never calls a command. Any state change → command. A command returns nothing or only the minimum needed to use its result later (the created order's ID), never the changed data: read that with a query. A command or query implementation depends only on infrastructure services (the database client, the HTTP client it runs on) and uses domain models; no repositories, ports, domain services or other commands and queries. Composing them is the job of a use case or an application service. |
|
|
54
|
+
| Domain service / entity, value object method | One entity / value object → its method. The junction of several → always a domain service, unless they all belong to one aggregate → a method on that aggregate. |
|
|
55
|
+
| Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
|
|
56
|
+
| Use case / application service | Use case = one action with `handle`, the entry point an endpoint calls. Application service = helper with no `handle`, used by 2+ use cases. A composition of queries/commands needed by one action stays in its use case; the same composition needed by several → application service, called by each of those use cases. |
|
|
57
|
+
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
58
|
+
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service. |
|
|
59
|
+
| Clock | Always a port (`clock`, usually in Shared Kernel). A command or query never uses it: the use case reads the time and passes it in the input. |
|
|
60
|
+
| Configuration | Values application logic needs (limits, feature flags) → a port (`application-config`, usually in Shared Kernel), with methods in the application's terms. Settings only an adapter needs (connection strings, API keys) → that adapter or its infrastructure service reads them; no port. |
|
|
61
|
+
|
|
62
|
+
## Naming
|
|
63
|
+
|
|
64
|
+
### Names describe the module, not its caller
|
|
65
|
+
|
|
66
|
+
A use case is named by its action, a verb: `get-user-info`, `edit-post`, `delete-post`. A query is named by what it reads, a noun: `user-info`, `own-post-list`. A command is named by the change it makes, a verb: `mark-order-paid`. None of these names carries the caller's context: `GetUserInfoUseCase` takes a `userId` and doesn't know it's the signed-in user, so it isn't `GetCurrentUserUseCase`. The caller's context belongs to the caller, e.g. the endpoint that takes the id from the token.
|
|
67
|
+
|
|
68
|
+
A word that describes what the module really does is not the caller's context: `own-post-list` filters posts by their author, so `own` stays.
|
|
69
|
+
|
|
70
|
+
### Ports are named by their role
|
|
71
|
+
|
|
72
|
+
An application port is named by the role it plays for the application, not by what it returns: `WeatherProvider`, not `Weather`. Usually the name ends with a role word: `PaymentGateway`, `SourcePostProvider`, `ReferenceNetworkResolver`, `PostAdaptationRegistrar`, `ReferenceOwnershipChecker`.
|
|
73
|
+
|
|
74
|
+
A name that returns "what" reads like a domain model (`IdeaReferences`, `TargetNetworks`) and hides that this is a dependency on the outside world.
|
|
75
|
+
|
|
76
|
+
A short name is enough when it already names a role: `Mailer`, `Logger`, `Clock`, `ApplicationConfig`. Don't add a role word just to fit the pattern.
|
|
61
77
|
|
|
62
78
|
## Where it goes
|
|
63
79
|
|
|
64
80
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
65
|
-
- Shared Kernel: technical, ownerless pieces (`clock`, `config`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
|
|
81
|
+
- Shared Kernel: technical, ownerless pieces (`clock`, `application-config`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
|
|
66
82
|
- Another context's data or behavior → an application port in the consuming context (step 9).
|
|
67
83
|
|
|
68
84
|
## Example
|
|
69
85
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| Piece
|
|
73
|
-
|
|
|
74
|
-
| Order, customer
|
|
75
|
-
| Order line
|
|
76
|
-
| Money
|
|
77
|
-
| "Can't pay twice"
|
|
78
|
-
| Discount ≤ 30%
|
|
79
|
-
| Place order, reorder
|
|
80
|
-
| Promo code check
|
|
81
|
-
| Email, order date
|
|
82
|
-
| Free shipping for gold customers | 13
|
|
83
|
-
| Confirmation for both use cases
|
|
84
|
-
| Invalid promo code
|
|
85
|
-
| `POST /sales/orders`
|
|
86
|
+
_"On order placement, check the promo code (owned by `marketing`) and email a confirmation, also sent on reorder. Discount ≤ 30% of the order. Gold customers get free shipping on orders over 100."_
|
|
87
|
+
|
|
88
|
+
| Piece | Step | Result (context `sales` unless noted) |
|
|
89
|
+
| -------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| Order, customer | 4 | aggregates `order`, `customer` + repositories |
|
|
91
|
+
| Order line | 5 | `order-line.entity.ts` in `order` (used only by `order`) |
|
|
92
|
+
| Money | 6 | `domain/value-objects/money.value-object.ts` (used by `order` and `shipping-policy`) |
|
|
93
|
+
| "Can't pay twice" | 7 | `Order.pay()` |
|
|
94
|
+
| Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the port |
|
|
95
|
+
| Place order, reorder | 8 | use cases `place-order`, `reorder` |
|
|
96
|
+
| Promo code check | 9 | port `promotions`: `cross-context` to `marketing`'s handler in the same app, or a transport adapter when deployed separately |
|
|
97
|
+
| Email, order date | 10 | ports `mailer`, `clock` (Shared Kernel) |
|
|
98
|
+
| Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
|
|
99
|
+
| Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
|
|
100
|
+
| Invalid promo code | 1 | error `invalid-promo-code` in namespace `order` |
|
|
101
|
+
| `POST /sales/orders` | 2 | endpoint, controller `orders` |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# df-scaffold generators: common parts
|
|
2
2
|
|
|
3
|
-
Use the JSON interface described in [agent-mode.md](agent-mode.md), with the complete operation map in [agent-operations.md](agent-operations.md).
|
|
3
|
+
Use the JSON interface described in [agent-mode.md](agent-mode.md), with the complete operation map in [agent-operations.md](agent-operations.md). Prompts below are what a generator asks interactively; JSON requests carry the same answers as fields. Generated files and implementation rules are the same.
|
|
4
4
|
|
|
5
5
|
What every generator shares: notation, the `Dependencies:` step, env-branched wiring and spec templates. Prompts and output of each generator are in `units/<unit>.md`.
|
|
6
6
|
|
|
@@ -8,11 +8,34 @@ Config paths: `project.rootFolder`, `backend.domainFirstPackages`, `backend.test
|
|
|
8
8
|
|
|
9
9
|
Notation: `<C>` = `<rootFolder>/bounded-contexts/<context>` or `<rootFolder>/shared-kernel`. `n` = the entered kebab-case name, `N` = PascalCase, `v` = camelCase. `I` = implementation label (`prisma` → `Prisma`). Specs are generated without a prompt **only if `backend.testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
|
|
10
10
|
|
|
11
|
-
Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Kernel"`, then the layer, then the operation (abbreviated below as `…`).
|
|
12
|
-
|
|
13
11
|
In interactive mode, if the run would replace existing files, the last prompt is the confirm `Overwrite them?` (the files are listed above it). Without it, nothing extra is asked. Added lines (barrels, errors, wiring indexes) never trigger it.
|
|
14
12
|
|
|
15
|
-
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask
|
|
13
|
+
{wire} Generators that create a wire (all except endpoints, which ask their own two selects) then ask for dependencies, before `Overwrite them?`: the checkbox `Dependencies:` interactively, the `dependencies` field in JSON ([agent operations](agent-operations.md#dependency-keys-and-system-implementations)).
|
|
14
|
+
|
|
15
|
+
The list holds wired modules of `<C>` and of the Shared Kernel (`(shared-kernel)` suffix), grouped in this order: Repositories, Domain services, Ports, Application services, Queries, Commands, Use cases, Infrastructure services, Presentation services. Inside a group: by type name, `<C>` first. Endpoints are never listed. The step is skipped when nothing fits: check `<C>/wiring/`, `<rootFolder>/shared-kernel/wiring/` and neighboring contexts' `wiring/`.
|
|
16
|
+
|
|
17
|
+
What fits depends on the layer of the class the wire builds:
|
|
18
|
+
|
|
19
|
+
- domain → domain
|
|
20
|
+
- application → domain, application
|
|
21
|
+
- infrastructure (repository, command/query, and port implementations, infrastructure services) → domain, application ports (of `<C>` and the Shared Kernel; no other application modules), infrastructure
|
|
22
|
+
- presentation → application, presentation
|
|
23
|
+
|
|
24
|
+
On top of that:
|
|
25
|
+
|
|
26
|
+
- Domain services see only domain services (no repositories).
|
|
27
|
+
- Application services see only ports, commands and queries from application.
|
|
28
|
+
- Use cases never see use cases.
|
|
29
|
+
- Repository implementations never see repositories.
|
|
30
|
+
- Command/query implementations see only infrastructure services, locally and in the Shared Kernel.
|
|
31
|
+
- Only port adapters under `infrastructure/application-adapters/cross-context/` also see neighboring queries, commands and use cases labelled `(<context>)`. Imports and constructor names get context-qualified aliases. Query/command implementations have no cross-context exception. This exception is fixed and doesn't expose foreign models, infrastructure or other kinds; other labels keep context isolation. The wire checks each implementation separately, even when several types share its imports. Leave test implementations independent.
|
|
32
|
+
- These are the defaults: `backend.rules.dependencies` in the config changes them per kind (`use-cases`, `queries`, …), so go by what the project's rules allow.
|
|
33
|
+
|
|
34
|
+
Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order.
|
|
35
|
+
|
|
36
|
+
An env-branched wire (repository, command/query, port) wires each implementation in isolation: it asks `Dependencies for <Implementation>:` once per implementation, in the order of the wire (main, then test). Each list leaves out only what that implementation already has, and a list with nothing to choose is skipped.
|
|
37
|
+
|
|
38
|
+
It may start with a `Suggested` group, which holds only the system service of the implementation: `prisma-infrastructure-service` for `prisma`, `in-memory-db-infrastructure-service` for `in-memory`. It is listed there only and is **checked**: omitting the implementation's group in JSON keeps it, `[]` selects none. Any other service is an ordinary unchecked item in `Infrastructure services`, whatever its name, so select it explicitly.
|
|
16
39
|
|
|
17
40
|
## Remembered and system implementation types
|
|
18
41
|
|
|
@@ -23,7 +46,7 @@ Active system choices are explicitly labelled:
|
|
|
23
46
|
- `System: cross-context (calls handlers in another bounded context)` — only port adapters with at least one neighboring context, never Shared Kernel ports.
|
|
24
47
|
- `System: in-memory (uses the shared in-memory database)` — only repositories, commands and queries when `backend.withInMemoryDb` is enabled and its service and required wire exist. The DB is still a suggested dependency with wiring. Inactive `in-memory` and port adapters named `in-memory` are ordinary types, not automatic choices.
|
|
25
48
|
|
|
26
|
-
|
|
49
|
+
Saved system labels retain the marker and are not duplicated. **New Implementation** merges primary/test history and available system choices, without introducing ordinary presets.
|
|
27
50
|
|
|
28
51
|
The two manual actions are `Enter implementation type and save for future use` and `Enter implementation type for this run only`, each followed by a separate text input. Saving stages a new ordinary label in the config’s `backend.implementations` section; run-only entry leaves it unchanged. Both generate source files. This distinction also applies to **New Implementation** after environments are selected. Include the JSON file in generated-file lists when saving a new type; cancellation discards its update too.
|
|
29
52
|
|
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
# Aggregate and repository
|
|
2
2
|
|
|
3
|
-
When: a thing with identity, lifecycle, and rules about its own state, owned by this context and stored on its own (`../choosing-components.md`, step 4). A rule about its own state is a method on it (step 7), not a new unit. Loading
|
|
3
|
+
When: a thing with identity, lifecycle, and rules about its own state, owned by this context and stored on its own (`../choosing-components.md`, step 4). A rule about its own state is a method on it (step 7), not a new unit. Loading aggregates to change them or check their rules, and saving them, is a repository method. Returning data to a reader is a query, even for one aggregate.
|
|
4
4
|
|
|
5
5
|
## Generate (context only)
|
|
6
6
|
|
|
7
7
|
Prompts: name → `With Repository` → primary implementation select → `Add a test implementation` → test implementation select if yes → {wire} dependencies per implementation. Each select contains saved repository types for that role, available system types and both manual-entry actions (`../generators.md`). `System: in-memory (uses the shared in-memory database)` appears only with the shared DB enabled and scaffolded. There are no ordinary presets; default to the first available saved/system choice, otherwise manual entry.
|
|
8
8
|
|
|
9
|
-
`… pick:Domain "pick:New Aggregate" text:order yes "pick:Enter implementation type and save for future use" text:prisma yes "pick:System: in-memory"` (with the shared DB ready; otherwise enter the test type manually).
|
|
10
|
-
|
|
11
9
|
- Custom types entered with the save action are staged in the shared config under `backend.implementations.repositories.primary` or `backend.implementations.repositories.test` and offered on later runs, including in other contexts. Both manual-entry actions from `../generators.md` are available; the run-only action generates the repository without remembering its type.
|
|
12
10
|
- `<C>/domain/aggregates/n/`: `n.aggregate-root.ts` (`class N extends domainType()` {types}), `index.ts`, spec; with repository: `n-repository.ts` (`abstract class NRepository`), spec
|
|
13
11
|
- `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
|
|
@@ -4,7 +4,7 @@ When: a concept with its own lifecycle and vocabulary, or a different business o
|
|
|
4
4
|
|
|
5
5
|
## Generate
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Creates an empty folder `<rootFolder>/bounded-contexts/sales/`. No error namespace until the first error ([errors](errors.md)).
|
|
8
8
|
|
|
9
9
|
Name: a business area in kebab-case (`sales`, `reviews`), not a feature.
|
|
10
10
|
|
|
@@ -1,17 +1,14 @@
|
|
|
1
1
|
# Command and query
|
|
2
2
|
|
|
3
|
-
When (`../choosing-components.md`, step 11): one atomic read/write on this context's own storage that
|
|
3
|
+
When (`../choosing-components.md`, step 11): one atomic read/write on this context's own storage that doesn't load aggregates to change them or check their rules (read model, data for a reader, report, bulk update). Another context or external system is reached through a port (`port.md`).
|
|
4
4
|
|
|
5
5
|
- One atomic operation of one kind of storage implementation: several statements in one transaction count as one. Several operations, a mix of storages, or logic between steps → several queries/commands, composed in a use case.
|
|
6
|
-
- A query only reads: it never changes any state, not even idempotently, and never calls a command. A command returns nothing or
|
|
6
|
+
- A query only reads: it never changes any state, not even idempotently, and never calls a command. A command returns nothing or only what is needed to get the result of its work (e.g. a created ID), never the changed data itself: read that with a query.
|
|
7
7
|
|
|
8
8
|
## Generate (context only)
|
|
9
9
|
|
|
10
10
|
Prompts: name → primary implementation select → `Add a test implementation` → test implementation select if yes → {wire} dependencies per implementation. Menus contain saved types from `commands` or `queries` for the selected role, active system types and both manual-entry actions (`../generators.md`). Only `System: in-memory (uses the shared in-memory database)` can be automatic here, when its integration is ready. `api` and `mock` must be saved or entered manually. The first saved/system choice is the default, otherwise manual entry without a suggested name. Saving stages the new ordinary label for that category/role; run-only input leaves the catalog unchanged.
|
|
11
11
|
|
|
12
|
-
`… pick:Application "pick:New Command" text:place-order "pick:Enter implementation type and save for future use" text:prisma yes "pick:System: in-memory"` (with the shared DB ready).
|
|
13
|
-
`… pick:Application "pick:New Query" text:order-summary "pick:Enter implementation type for this run only" text:sql no`
|
|
14
|
-
|
|
15
12
|
- `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
|
|
16
13
|
- `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
|
|
17
14
|
- {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
|
|
@@ -24,7 +21,8 @@ Queries: the same with `query` / `queries`.
|
|
|
24
21
|
- Queries and commands never import neighboring contexts. `cross-context` is reserved for port adapters and is unavailable here, including as a custom label.
|
|
25
22
|
- {handlers} The abstract contract holds static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes its `handler` callback.
|
|
26
23
|
- An implementation performs its one operation with no business logic or surrounding steps. Its wired dependencies are infrastructure services (the database client it runs on); repositories, ports, domain services and other queries/commands stay with the consuming use case.
|
|
27
|
-
-
|
|
24
|
+
- Query input and command input use this context's domain models; time comes through input, never through the clock port.
|
|
25
|
+
- A query never returns a domain model as its output. Its output is an independent DTO, needed only in the context of this query: it is defined by the query's `outputSchema` and isn't shared with other queries, even when the fields match. Fields of the DTO may use value objects and even entities, but the DTO itself is always a separate type.
|
|
28
26
|
- An `in-memory` implementation works on the in-memory DB when configured; `mock`/`stub` implementations may return fixed data.
|
|
29
27
|
|
|
30
28
|
## Test
|
|
@@ -6,8 +6,6 @@ When: a module is no longer needed. Never delete module files by hand: the CLI r
|
|
|
6
6
|
|
|
7
7
|
Prompts: `Module to delete:` (select, grouped by kind as in Move or rename) → `Delete?` (default No).
|
|
8
8
|
|
|
9
|
-
`… "pick:Delete" pick:orders yes`
|
|
10
|
-
|
|
11
9
|
JSON: `{ "operation": "delete", "context": "sales", "module": "query:orders" }`.
|
|
12
10
|
|
|
13
11
|
Deleted: the files of the unit, as Move or rename moves them (an aggregate with its whole folder, entities and value objects inside included). Cleaned up: an entity's or value object's `export *` in its aggregate's `index.ts`, and an aggregate's in-memory DB section with its import.
|
|
@@ -6,9 +6,6 @@ When: an HTTP entry point (`../choosing-components.md`, step 2). It exposes a qu
|
|
|
6
6
|
|
|
7
7
|
Prompts: controller (select: `(root) — /<C>` | existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
|
|
8
8
|
|
|
9
|
-
`… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
|
|
10
|
-
`… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
|
|
11
|
-
|
|
12
9
|
For `sales`, `orders`, `get`, `recent`:
|
|
13
10
|
|
|
14
11
|
- `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. `endpointGenerator: RestEndpointGeneratorPresentationService` (the Shared Kernel generator) and `handler: RecentOrdersQuery` (`never` without a pick), both `import type`. `get handle()` calls `this.endpointGenerator(...)`, which doesn't compile until a generating getter is picked (`this.endpointGenerator.withoutGuards(...)`); that's expected, not a generator bug. Projects without the generator file get `EndpointGenerator` from handlers-rest.
|
|
@@ -24,7 +21,7 @@ The same controller, path, and method replace the existing endpoint (after `Over
|
|
|
24
21
|
1. Generator: `df-init` (or the `REST endpoint generator` integration) creates `RestEndpointGeneratorPresentationService` in `<rootFolder>/shared-kernel/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 the Next adapter was connected, the file already imports `nextAdapter` from `@domain-first/handlers-next` and passes it instead; just make sure that package is installed.
|
|
25
22
|
2. Errors: 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 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-kernel/` may import from a context, besides domain models in the in-memory DB).
|
|
26
23
|
3. 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`.
|
|
27
|
-
4. Complete `get handle()`: pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`.
|
|
24
|
+
4. Complete `get handle()`: pick the generating getter that fits the endpoint (`this.endpointGenerator.withoutGuards(...)`, or one with the needed guards), then `.input(...)`, `.mapInput(...)`, optional `.output(...)`, `.mapOutput(...)`. They check only the shape of the request: a condition on the input as a whole belongs to the use case (`use-case.md`, "The use case checks that its input makes sense"), so no `refine` or checks in `mapInput` for it. `get handle()` doesn't compile until a guard is chosen, on purpose: there is no default, so a protected endpoint can't be left open by accident. Choose by who may call the endpoint. `withoutGuards` is only for endpoints that are public by design, never a way to make the code compile. If the access rules aren't specified, ask. A guard the generator doesn't have yet is a new getter (step 3).
|
|
28
25
|
5. Register `restHandlers` from `<rootFolder>/presentation/rest/index.ts` in the server bootstrap (`df-ps-scaffold` `SKILL.md`, rule 2, exception 5). With the Next adapter and wire, `app/api/[...path]/route.ts` (or `src/app/…`) already serves them through `nextEndpoints(restHandlers)`; it compiles once the first endpoint exists.
|
|
29
26
|
|
|
30
27
|
After new endpoints, regenerate the OpenAPI document and the API client with the project's scripts (Running in the plan).
|
|
@@ -6,10 +6,6 @@ When (`../choosing-components.md`, steps 5–6): used only inside one aggregate
|
|
|
6
6
|
|
|
7
7
|
Prompts: name → aggregate (select: existing aggregate folders | `No aggregate`; asked only if `<C>/domain/aggregates/` has aggregates, so never in Shared Kernel).
|
|
8
8
|
|
|
9
|
-
`… pick:Domain "pick:New Entity" text:order-line pick:order`
|
|
10
|
-
`… pick:Domain "pick:New Value Object" text:money "pick:No aggregate"`
|
|
11
|
-
`"pick:Shared Kernel" pick:Domain "pick:New Value Object" text:money`
|
|
12
|
-
|
|
13
9
|
- In an aggregate: `<C>/domain/aggregates/a/entities/n.entity.ts` or `<C>/domain/aggregates/a/value-objects/n.value-object.ts` (`class N extends domainType()` {types}), spec; `export * from './entities/n.entity'` (or `./value-objects/n.value-object`) appended to the aggregate's `index.ts`
|
|
14
10
|
- `No aggregate`: `<C>/domain/entities/n.entity.ts` or `<C>/domain/value-objects/n.value-object.ts`, spec; no barrel
|
|
15
11
|
|
|
@@ -6,10 +6,6 @@ When: a business failure callers must recognize (`../choosing-components.md`, st
|
|
|
6
6
|
|
|
7
7
|
First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
|
|
8
8
|
|
|
9
|
-
`… pick:Domain pick:Errors "pick:New namespace" text:order`
|
|
10
|
-
`… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
|
|
11
|
-
`… pick:Domain pick:Errors "pick:New error without" text:order-closed`
|
|
12
|
-
|
|
13
9
|
- Without namespace: appends `export class N extends CtxErrors.define('n') {}` to `<C>/domain/errors/index.ts`; the first one also puts `CtxErrors = errorNamespace('ctx')` (with its import) at the top of `index.ts`
|
|
14
10
|
- New namespace: `<C>/domain/errors/ns.ts` (`NsErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
|
|
15
11
|
- In namespace: appends `export class NsN extends NsErrors.define('n') {}` to `ns.ts` (namespace first), extending the namespace the file exports
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Infrastructure helper
|
|
2
|
+
|
|
3
|
+
When (`../choosing-components.md`, step 14): stateless technical code of one implementation type: a mapper between storage and domain, a query builder, an error translator. No class, no wire, no state. If it needs a dependency or several implementation types share it (cursor encoding for `prisma` and `in-memory`, retry for several adapters), it is an infrastructure service (`services.md`). Other layers have no helpers: domain logic belongs in the model, application logic in a use case or application service, presentation logic in a presentation service.
|
|
4
|
+
|
|
5
|
+
## Generate (context and Shared Kernel)
|
|
6
|
+
|
|
7
|
+
Prompts: `Name (folders split by "/"):` → `Implementation:` (a type the project already has).
|
|
8
|
+
|
|
9
|
+
JSON: `{ "operation": "helper", "context": "sales", "name": "mappers/social-network-type", "implementationType": "prisma" }`.
|
|
10
|
+
|
|
11
|
+
- `<C>/infrastructure/helpers/I/<folders>/I-n.ts` (`export const iN = () => {}`), spec
|
|
12
|
+
|
|
13
|
+
A name that already starts with the type (`prisma-errors`) doesn't get the prefix twice. A helper of a type that isn't saved yet can't be generated: add an implementation of that type first, saving the type.
|
|
14
|
+
|
|
15
|
+
## Implement
|
|
16
|
+
|
|
17
|
+
Replace the stub. Rename the function and add more next to it freely. Use the helper by importing it directly: it isn't injected or listed under `Dependencies:`.
|
|
18
|
+
|
|
19
|
+
- Location: always inside the folder of its type, nothing right under `helpers/`.
|
|
20
|
+
- Imports: domain models, helpers of its type, and `import type` of query, command and port contracts. No repositories, domain services, services or implementations.
|
|
21
|
+
- Used by: implementations of its type and infrastructure services. Never by wiring, application, presentation, or another context; a helper of the Shared Kernel is available to implementations of its type in every context.
|
|
22
|
+
- `npx df-lint` checks all of this except that a helper is stateless.
|
|
23
|
+
|
|
24
|
+
## Move and delete
|
|
25
|
+
|
|
26
|
+
Helpers are not modules: `Move or rename` and `Delete` don't list them, so edit them by hand.
|
|
27
|
+
|
|
28
|
+
- A module that uses a helper can't move to another context while the helper stays behind: the CLI refuses and names the imports. Move the helper by hand first, then the module.
|
|
29
|
+
- `Delete` of a module refuses while a helper imports it. Delete or change the helper by hand first.
|
|
30
|
+
- Renaming a module inside its context leaves the helper's file name as it was: rename it by hand if it no longer fits.
|
|
@@ -6,10 +6,6 @@ When: a repository, command, query or port already exists and needs one more imp
|
|
|
6
6
|
|
|
7
7
|
Prompts: `Contract:` → `Implementation type:` → {wire} `Environments:` (at least one) → {wire} dependencies for the new implementation. The type menu merges the category's primary/test history with active system choices and both manual-entry actions (`../generators.md`); it has no ordinary `api`, `mock` or `in-memory` presets. System choices are explicitly marked and conditional: cross-context for ports with a neighbor, shared in-memory DB for repositories/commands/queries with that integration ready. Existing types are disabled. Saving a new ordinary label registers it under `test` and/or `primary` according to selected environments (primary without usable wiring). The run-only action registers nothing.
|
|
8
8
|
|
|
9
|
-
`… pick:Infrastructure "pick:New Implementation" pick:file-storage "pick:Enter implementation type and save for future use" text:local toggle:2`
|
|
10
|
-
|
|
11
|
-
`toggle:` numbers the environments top to bottom: 1 `test`, 2 `development`, 3 `production`.
|
|
12
|
-
|
|
13
9
|
- `<C>/infrastructure/<kind>/I/I-n….ts` as the contract's generator creates it (in-memory DB included)
|
|
14
10
|
- {wire} `~ <C>/wiring/<kind>/wire-n….ts`: import, `const wireIImplementation = wireClass(IN…, [])` before the module's wire, the chosen environments of `envBranchedWire` point at it
|
|
15
11
|
|
|
@@ -6,10 +6,6 @@ When: a module's name no longer fits, or it belongs elsewhere: another bounded c
|
|
|
6
6
|
|
|
7
7
|
Prompts: `Module:` (select, grouped by kind; entities and value objects of an aggregate show it: `order-line (order)`) → `Move to:` (`Bounded Context: <current> (stays)`, other contexts, `Shared Kernel` for the kinds it has) → `Aggregate:` (entities and value objects only, when the target context has aggregates: `No aggregate` or one of them) → `New name:` (default: the current one) → `Apply?`.
|
|
8
8
|
|
|
9
|
-
`… "pick:Move or rename" pick:order "pick:Bounded Context: sales" text:purchase yes`
|
|
10
|
-
`… "pick:Move or rename" pick:money "pick:Shared Kernel" default yes`
|
|
11
|
-
`… "pick:Move or rename" pick:order-line "pick:Bounded Context: sales" "pick:No aggregate" default yes`
|
|
12
|
-
|
|
13
9
|
Every file of the module moves (contract, implementations, wire, specs; an aggregate with its whole folder), every import of it follows, and derived names change in the module and its importers: `OrderRepository`, `PrismaOrderRepository`, `wireOrderRepository`, dependents' `orderRepository` parameters, an aggregate's in-memory DB section. An entity leaving its aggregate is no longer re-exported there; its importers import its file.
|
|
14
10
|
|
|
15
11
|
Before `Apply?` the CLI lists the files to move and to update: check that they are the module's files and its importers. A move that would introduce a forbidden context import prints `Nothing was moved: these imports would cross a bounded context boundary.` with the imports: nothing changed. Fix the design instead (`../choosing-components.md`, step 9: the consuming context gets a port with a cross-context adapter), or move the dependency first.
|
|
@@ -1,14 +1,11 @@
|
|
|
1
1
|
# Port
|
|
2
2
|
|
|
3
|
-
When: a capability across this context's boundary: another bounded context, an external system, time or configuration (`../choosing-components.md`, steps 9–10). Own aggregate persistence → repository; atomic operations on this context's own storage → command/query. One method is enough. Wanting to mock a class or imagining multiple implementations does not by itself establish a boundary. The `clock` and `config` ports usually belong in the Shared Kernel.
|
|
3
|
+
When: a capability across this context's boundary: another bounded context, an external system, time or configuration (`../choosing-components.md`, steps 9–10). Own aggregate persistence → repository; atomic operations on this context's own storage → command/query. One method is enough. Wanting to mock a class or imagining multiple implementations does not by itself establish a boundary. The `clock` and `application-config` ports usually belong in the Shared Kernel.
|
|
4
4
|
|
|
5
5
|
## Generate (context and Shared Kernel)
|
|
6
6
|
|
|
7
7
|
Prompts: name → primary adapter select → `With test implementation` → test adapter select if yes → {wire} dependencies per adapter. Both selects show saved port types for their role, active system types and both manual-entry actions (`../generators.md`). The only automatic system choice is `System: cross-context (calls handlers in another bounded context)`, conditional on a neighboring context and unavailable in the Shared Kernel. No `api`, `mock` or `in-memory` presets are inserted for ports. The first saved/system choice is the default; manual input is empty without saved choices. Existing labels are disabled. Saved ordinary port types are isolated from other categories. Save-entry updates `ports` history; run-only entry generates the adapter without updating the catalog.
|
|
8
8
|
|
|
9
|
-
`… pick:Application "pick:New Port" text:payment-gateway "pick:Enter implementation type and save for future use" text:api yes "pick:Enter implementation type and save for future use" text:mock`
|
|
10
|
-
`… pick:Application "pick:New Port" text:billing-gateway "pick:System: cross-context" yes "pick:Enter implementation type for this run only" text:mock`
|
|
11
|
-
|
|
12
9
|
- `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
|
|
13
10
|
- `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
|
|
14
11
|
- {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
|
|
@@ -19,7 +16,7 @@ Prompts: name → primary adapter select → `With test implementation` → test
|
|
|
19
16
|
- For another context, define the port in the consuming context with its own models and errors. A `cross-context` adapter can inject queries, commands and use cases from any neighboring context; choices are labelled `(<context>)` and names get context-qualified aliases. Only this adapter imports neighboring handler types, and only its matching wiring imports their factories. Never import foreign models, errors, repositories, ports, services, infrastructure or barrels.
|
|
20
17
|
- Implement the capability's methods by mapping input, invoking injected handlers, and mapping results/errors. The CLI creates the contract, adapters and dependencies; it does not generate methods or delegation. Keep business coordination in the consuming use case.
|
|
21
18
|
- One implementation per adapter: `api` performs the real interaction (an SDK or HTTP client, through an [infrastructure service](services.md) for the client); `mock`/`fake` is deterministic.
|
|
22
|
-
- Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code, and
|
|
19
|
+
- Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code, and an `application-config` port instead of `process.env` / `import.meta.env`. Its adapter reads the environment; infrastructure and wiring may read it directly.
|
|
23
20
|
|
|
24
21
|
## Test
|
|
25
22
|
|
|
@@ -4,15 +4,13 @@ When (`../choosing-components.md`, steps 12–15, "Port or service?"):
|
|
|
4
4
|
|
|
5
5
|
- **Domain service**: a rule at the junction of several entities / value objects not all belonging to one aggregate, no I/O. It takes the aggregates and values it needs as arguments; loading them is the caller's job. In the Shared Kernel only for junctions of universal types.
|
|
6
6
|
- **Application service**: application logic reused by 2+ use cases, with external interaction or storage access delegated to injected ports, commands or queries. A composition needed by one use case stays in it.
|
|
7
|
-
- **Infrastructure service**: a technical helper used only by infrastructure code; also the home of a value that isn't a wired module (a database or SDK client, a config value), named after the implementation label (`prisma`, `stripe`).
|
|
7
|
+
- **Infrastructure service**: a technical helper used only by infrastructure code that has state or dependencies or is shared by several implementation types (stateless code of one type is an [infrastructure helper](helper.md)); also the home of a value that isn't a wired module (a database or SDK client, a config value), named after the implementation label (`prisma`, `stripe`).
|
|
8
8
|
- **Presentation service**: a helper used only by presentation code.
|
|
9
9
|
|
|
10
10
|
## Generate (context and Shared Kernel)
|
|
11
11
|
|
|
12
12
|
Prompts: name → {wire} `Dependencies:` (`../generators.md`). `L` = `domain` | `application` | `infrastructure` | `presentation`.
|
|
13
13
|
|
|
14
|
-
`… pick:Application "pick:New Service" text:checkout`
|
|
15
|
-
|
|
16
14
|
- `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
|
|
17
15
|
- {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
|
|
18
16
|
|
|
@@ -20,7 +18,7 @@ Prompts: name → {wire} `Dependencies:` (`../generators.md`). `L` = `domain` |
|
|
|
20
18
|
|
|
21
19
|
- Domain services take and return domain types. Pure: no I/O, ports, or repositories, not even injected ones; they work with the data they are handed. They depend only on other domain services.
|
|
22
20
|
- Application services have no `handle`: a use case is how an endpoint reaches their logic. They call injected ports, commands and queries, never external SDKs, HTTP clients, or another context directly.
|
|
23
|
-
- Infrastructure services: an external client or config value is created or read by the service itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-scaffold
|
|
21
|
+
- Infrastructure services: an external client or config value is created or read by the service itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-scaffold`. Only `prisma-infrastructure-service` for `prisma` and `in-memory-db-infrastructure-service` for `in-memory` come checked under `Suggested`; select any other service explicitly. Wrap its wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`.
|
|
24
22
|
- Infrastructure never sees application services. Logic infrastructure needs from one: pure logic without ports → a domain service; logic over ports → call the ports directly; technical (mapping, retries, external API formats) → an infrastructure service.
|
|
25
23
|
|
|
26
24
|
## Test
|
|
@@ -6,8 +6,6 @@ When: one business action a user or system triggers that doesn't fit into a sing
|
|
|
6
6
|
|
|
7
7
|
Prompts: name → {wire} `Dependencies:` (`../generators.md`; use cases never see use cases by default).
|
|
8
8
|
|
|
9
|
-
`… pick:Application "pick:New Use Case" text:place-order`
|
|
10
|
-
|
|
11
9
|
- `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
|
|
12
10
|
- {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
|
|
13
11
|
|
|
@@ -18,6 +16,7 @@ Generate its dependencies (repositories, ports, commands, queries, application s
|
|
|
18
16
|
- {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.
|
|
19
17
|
- It composes repositories, ports, commands, queries and domain services: loads aggregates, calls their methods, saves them. Reading the time: the `clock` port, then pass the time into commands and queries in their input.
|
|
20
18
|
- A rule about a set of aggregates: a repository method that queries it, plus a check and a domain error here.
|
|
19
|
+
- **The use case checks that its input makes sense.** The HTTP layer checks the shape of each request part: types, formats, required fields (through the value objects' schemas). Whether the input as a whole makes sense for the scenario ("at least one field to change") is the use case's job. It throws a domain error (`NothingToEdit`), and the endpoint maps it in `errors` (`httpError(NothingToEdit, 400)`). Don't express such conditions with `refine` in the request schema or the use case's `inputSchema`, or with checks in `mapInput`: the client would get a generic `invalid-request`, and other callers of the use case would skip the check. If the endpoint calls a single command or query, such a check is a reason to add a use case: it isn't a proxy.
|
|
21
20
|
- Call others' handlers with `x.handle(input)` (returns a result) or `x.handle.unsafe(input)` (throws).
|
|
22
21
|
|
|
23
22
|
## Test
|
|
@@ -6,8 +6,6 @@ When: an existing wired module needs a new dependency (`df-ps-scaffold` `SKILL.m
|
|
|
6
6
|
|
|
7
7
|
Prompts: module (select: wired modules of `<C>`, grouped as in `Dependencies:`, endpoints excluded; an env-branched module is listed once per implementation, e.g. `UserRepository (prisma)`, `UserRepository (in-memory)`) → `Dependencies:`, or `Dependencies for <Implementation>:` for the chosen implementation only (`../generators.md`). Modules already in the wire are not listed. If nothing fits, it prints `No dependencies available for this module.` and changes nothing.
|
|
8
8
|
|
|
9
|
-
`"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
|
|
10
|
-
|
|
11
9
|
Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`. List it in the plan as a run for the existing module.
|
|
12
10
|
|
|
13
11
|
## Implement
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Work plan format
|
|
2
|
+
|
|
3
|
+
How to write the plan that `SKILL.md`, rule 1, requires. Show it in this format and stop:
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
**Plan: order cancellation**
|
|
7
|
+
|
|
8
|
+
**Scaffolding**
|
|
9
|
+
|
|
10
|
+
**sales**
|
|
11
|
+
|
|
12
|
+
Why here: cancelling changes the order's status; orders belong to sales.
|
|
13
|
+
|
|
14
|
+
What will be scaffolded:
|
|
15
|
+
|
|
16
|
+
| Layer | Type | Name | Details | Why |
|
|
17
|
+
| --- | --- | --- | --- | --- |
|
|
18
|
+
| **domain** | error | order-already-shipped | | shipped orders can't be cancelled |
|
|
19
|
+
| **application** | command | cancel-order | prisma, fake in tests | one atomic status change |
|
|
20
|
+
| | query | cancellable-orders | prisma | read-only list for the UI |
|
|
21
|
+
| **presentation** | endpoint | POST orders/:id/cancel | → cancel-order | UI calls it over HTTP |
|
|
22
|
+
|
|
23
|
+
**billing**
|
|
24
|
+
|
|
25
|
+
Why here: refunds are payments; payments belong to billing.
|
|
26
|
+
|
|
27
|
+
What will be scaffolded:
|
|
28
|
+
|
|
29
|
+
| Layer | Type | Name | Details | Why |
|
|
30
|
+
| --- | --- | --- | --- | --- |
|
|
31
|
+
| **application** | port | order-refunds | cross-context, stub in tests | paid amount lives in sales |
|
|
32
|
+
| | use case | refund-cancelled-order | deps: OrderRefunds, PaymentGateway | read order, then call provider |
|
|
33
|
+
|
|
34
|
+
**React**
|
|
35
|
+
|
|
36
|
+
Why here: the user cancels from the order screen.
|
|
37
|
+
|
|
38
|
+
What will be scaffolded:
|
|
39
|
+
|
|
40
|
+
| Layer | Type | Name | Details | Why |
|
|
41
|
+
| --- | --- | --- | --- | --- |
|
|
42
|
+
| **presentation** | widget | orders/cancel-order | with separated ui | dialog has its own state |
|
|
43
|
+
| | page | orders/details | add the widget | button goes on this screen |
|
|
44
|
+
|
|
45
|
+
**Writing by hand**
|
|
46
|
+
- cancel-order: input { orderId }, output { status }
|
|
47
|
+
- prisma implementation: update status, throw OrderAlreadyShipped
|
|
48
|
+
- endpoint: :id → orderId, OrderAlreadyShipped → 409
|
|
49
|
+
- order-refunds adapter: sales:OrderSummaryQuery result → RefundableAmount
|
|
50
|
+
|
|
51
|
+
**Running**
|
|
52
|
+
- after the endpoint: npm run openapi && npm run client:orval
|
|
53
|
+
|
|
54
|
+
**Question**
|
|
55
|
+
1. Refund right on cancel, or after a manager confirms?
|
|
56
|
+
|
|
57
|
+
Reply "ok" to start.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- Write the plan in the user's language (headings and sentences); module names, types, commands and paths stay as in the code. Omit empty sections.
|
|
61
|
+
- **Scaffolding** has one block per owner, in run order: new contexts first, marked `(new)` (and `(provisional)` with the reason when ownership is a reversible default), then existing contexts, `shared-kernel`, React last.
|
|
62
|
+
- **Why here**: one short sentence on why this owner, not another: the data or rule the context owns; for `shared-kernel`, why several contexts share it; for React, why the UI changes.
|
|
63
|
+
- **What will be scaffolded**: one table per owner, one row per `df-scaffold`/`df-react` run. Layers in order domain → application → infrastructure → presentation, the layer in bold only on its first row. Repositories go with their aggregate in domain; commands, queries and ports in application (their implementations are Details); endpoints and React modules in presentation.
|
|
64
|
+
- **Type**: the unit: aggregate, entity, value object, error, error namespace, service, port, command, query, use case, implementation, endpoint, wire dependency, move, delete; for React: page, widget, ui-kit component, hook, page move, widget move, ui-kit component move, hook move, page delete, widget delete, ui-kit component delete, hook delete.
|
|
65
|
+
- **Name**: the entered name; for a move `old → new`; for an implementation the contract; for wire dependency the module.
|
|
66
|
+
- **Details**: only what changes behavior: implementation types (`(saved)` when saved for future runs), the test implementation, dependencies (`deps: OrderRepository`), environments, widget type, the endpoint's handler, whether a Next.js route moves (`route moves: /a → /b`). No file paths, no CLI menu paths.
|
|
67
|
+
- **Why**: at most six words: why this kind of module (`choosing-components.md`).
|
|
68
|
+
- **Writing by hand**: members, schemas, mappings. Not full code.
|
|
69
|
+
- **Running**: every command that generates files (migrations, OpenAPI, API client, other codegen), with what it produces and when. Use the project's own scripts; find them in `package.json` and configs. Their output needs no approval of its own and is never edited; scripts that change a database are run only by the user. Details: the project's scripts skill (`project-scripts`), if there is one.
|
|
70
|
+
- **Overwrites**, only when a run would replace existing files (`overwriteRequired` of a `dryRun`): list those files.
|
|
71
|
+
- **Exception requests**, only for hand-created files: `<path>` (`SKILL.md`, rule 2, #n) with the reason. Any other file needs its own request with a reason.
|
|
72
|
+
- **Question**, only for open decisions that change structure or domain behavior. Open questions block approval: answers first, then the updated plan.
|
|
73
|
+
- The last line says what reply starts the work.
|