@domain-first/project-structure 2.17.1 → 2.18.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.
@@ -0,0 +1,132 @@
1
+ ---
2
+ name: df-ps-scaffold
3
+ description: Generate Domain-First components with the `df-ps` CLI (@domain-first/project-structure) — bounded contexts, aggregates, repositories, errors, services, use cases, commands, queries, ports, handlers-rest endpoints, React pages, widgets, UI-kit components (with Storybook stories) and shared hooks, and moving or renaming pages and widgets. Use when the project has domain-first.project-structure.config.json and the user asks to add or create any of these, or to move, rename or regroup a page or widget. Holds the mandatory rules (work plan approval, new files and new dependencies only via df-ps) that the other df-ps skills rely on.
4
+ ---
5
+
6
+ # Scaffold components with df-ps
7
+
8
+ ## Workflow
9
+
10
+ Follow this order for every request:
11
+
12
+ 1. Read `domain-first.project-structure.config.json` (beside the nearest `package.json`). If missing, stop and tell the user to initialize the project with `npx df-ps` first.
13
+ 2. Feature request without named contexts/components → `df-ps-plan-feature` (it covers steps 3–5).
14
+ 3. Choose a component for each piece of logic with `references/choosing-components.md`.
15
+ 4. Prepare the run details ("Preparing runs" below).
16
+ 5. If the task creates files, show the work plan and **stop until it's approved** (rule 1).
17
+ 6. Run the generators in plan order with the driver; check each output.
18
+ 7. Implement with `df-ps-implement`, in its order: domain → application → schema tool runs (migrations) → infrastructure → endpoints → other tool runs (OpenAPI, API client) → React.
19
+ 8. Run `df-ps-implement/scripts/check-context-isolation.mjs` and the project's tsc/lint/tests.
20
+ 9. Report against the plan.
21
+
22
+ ## Mandatory rules
23
+
24
+ ### 1. Work plan approval
25
+
26
+ **A task that creates any new file** (a df-ps run, or a hand-created file under rule 2) needs an approved work plan first, even for one component, unless the user explicitly says to skip approval for this task. Until approval, only read. Files written by the project's own scripts (rule 2, exception 2) don't count: run those scripts when the work needs them.
27
+
28
+ Tasks that only edit existing files (a bug fix, a new field, a changed rule) don't need a plan: do them directly and say what you changed.
29
+
30
+ Show the plan in this format and stop:
31
+
32
+ ```markdown
33
+ **Work plan**
34
+
35
+ | # | Where | CLI path | Name | Options | Files (+ new, ~ changed) |
36
+ | --- | ----- | -------------------------- | ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | 1 | sales | Domain → New Aggregate | order | repo prisma + in-memory | + …/domain/aggregates/order/{order.aggregate-root.ts, index.ts, order-repository.ts, specs}<br>+ …/infrastructure/repositories/{prisma,in-memory}/…<br>+ …/wiring/repositories/wire-order-repository.ts |
38
+ | 2 | sales | Domain → New Entity | order-line | aggregate order | + …/domain/aggregates/order/entities/{order-line.entity.ts, spec}<br>~ …/domain/aggregates/order/index.ts |
39
+ | 3 | sales | Application → New Use Case | place-order | deps: OrderRepository | + …/application/use-cases/place-order-use-case.ts, spec<br>+ …/wiring/use-cases/wire-place-order-use-case.ts |
40
+ | 4 | react | Move or rename widget | users → admin/users | | → …/widgets/admin/users/{admin-users-widget.tsx, ui/admin-users-widget-ui.tsx, hooks/use-admin-users-ui-model.ts, …}<br>~ …/pages/users-page.tsx (import) |
41
+
42
+ Hand-written changes:
43
+
44
+ - `order.aggregate-root.ts`: schema (id, lines, status), method `pay()`
45
+ - `place-order-use-case.ts`: schemas, handler
46
+
47
+ Hand-created files (exception #): none; list each as `<path>` (#n)
48
+
49
+ Tool runs:
50
+
51
+ - after application, before infrastructure: `npm run prisma:migration:plan -- --name add-order`: migration for the `order` table (applied by the user)
52
+ - `npm run openapi && npx orval`: OpenAPI document and API client with the new endpoints
53
+ ```
54
+
55
+ - Every run lists the CLI path, target, name, every answer you'll give, and the files from `references/generators.md`. Flag overwrites of existing files.
56
+ - Hand-written changes: members, schemas, dependencies. Not full code.
57
+ - Tool runs: every command that generates files (migrations, OpenAPI, API client, other codegen), with what it produces and when. Use the project's own scripts; find them in `package.json` and configs. Their output needs no approval of its own and is never edited; scripts that change a database are run only by the user. Details: the project's scripts skill (`project-scripts`), if there is one.
58
+ - Any file outside the rule 2 exceptions appears as a separate **exception request** with a reason.
59
+ - Approval must be explicit ("ok", "да", "делай"…). A question or silence isn't approval. Changes to the plan → show the updated plan and ask again.
60
+ - After approval, do exactly the plan. An extra **new file**, component, or a different name/option → stop and get the delta approved. Edits to existing files needed along the way don't need approval; list them in the final report.
61
+
62
+ ### 2. New files only through df-ps
63
+
64
+ Every new file is created by `df-ps`. Don't create files with the Write tool, `touch`, redirects, or by copying templates. The only exceptions (`<C>` = `<rootFolder>/bounded-contexts/<context>`):
65
+
66
+ | # | Files | Location | Condition |
67
+ | --- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
+ | 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
69
+ | 2 | Output of project tools | where the tool puts it | Migrations, codegen: run the project's script, use its output as-is; never hand-write or edit it. No approval needed for these files. |
70
+ | 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` | Widget generated by df-ps. |
71
+ | 4 | Widget/page/UI-kit support files | inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.tsx`, `*.stories.tsx`; next to a page: `pages/<name>-page.module.css`, for a nested page in its folder (`pages/admin/admin-users-page.module.css`) (layout of its widgets only) | Widget/page/UI-kit component generated by df-ps. A page stays one file that composes widgets, plus an optional CSS module for their layout (grid, spacing, areas); no page tests. Its own hooks, UI parts, types, or styles for how a block looks mean a widget is missing, so generate it. A missing UI-kit or widget UI story: exactly from "Story templates" in `references/generators.md`. |
72
+ | 5 | App bootstrap and config | outside `<rootFolder>/{bounded-contexts,shared,presentation}/`: entry point, HTTP server setup registering `restHandlers`, tool configs | Bootstrapping only. Domain/application/infrastructure logic never goes there. |
73
+
74
+ Anything else (helpers, types, constants, mappers, wiring, barrels): put it in an existing generated file, or generate a component that can host it. Editing existing files is fine. If neither works, request an exception for that exact file.
75
+
76
+ If the CLI can't run, give the user the menu path and answers to run `npx df-ps` themselves (`! npx df-ps`). Never hand-write its output. Missing generated files are only recreated by re-running the generator, as an approved overwrite.
77
+
78
+ Moving or renaming a page or widget is a df-ps run too (`Move or rename page` / `Move or rename widget`, see `references/generators.md`): it creates the files at the new paths, so it needs an approved plan (rule 1). Don't move, rename, or copy their files by hand, and don't rename their `<Name>Page…`, `<Name>Widget…`, or `use<Name>UIModel` by hand: df-ps 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 (`~`).
79
+
80
+ ### 3. New dependencies only through df-ps
81
+
82
+ With `@domain-first/wire`, every new dependency of a wired class (a constructor parameter plus its wire) is added by `df-ps`: the generator's `Dependencies:` step for a new module, `Wire dependency` for an existing one, and the `Endpoint generator:` / `Handler:` picks for an endpoint. Don't add constructor parameters or wire entries by hand, and don't reorder or remove the ones `df-ps` added.
83
+
84
+ - List each module's dependencies in the plan as run options (`deps: OrderRepository`), with a `Wire dependency` run for existing modules.
85
+ - A dependency the CLI doesn't offer is forbidden by the wiring rules (layer, kind, or another context): change the design (a port, an execution query or command, an infrastructure service) instead of adding it by hand.
86
+ - A value that isn't a wired module (a database or SDK client, a config value) lives in an infrastructure service named after the implementation label (`prisma`, `in-memory-db`, `stripe`): the service creates or reads it itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-ps`, where it shows up under `Suggested`. Wrap the service's wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`. A domain or application module never gets such a value directly: it depends on a port whose adapter uses the service.
87
+ - An endpoint generated with `handler: never` gets its handler by re-running the endpoint generator once the handler exists, as an approved overwrite.
88
+
89
+ ### 4. Bounded contexts never import each other
90
+
91
+ Details and the check script: `df-ps-implement`, "Bounded context isolation".
92
+
93
+ ## Preparing runs
94
+
95
+ - **Contexts**: subfolders of `<rootFolder>/bounded-contexts/` (menu: `Bounded Context: <name>`).
96
+ - **Names**: lowercase kebab-case, no generator suffix (`place-order`, not `place-order-use-case`). No empty segments (`a--b`). Pages and widgets only: folders before the name, each segment kebab-case (`admin/users`); when to nest: `references/choosing-components.md`.
97
+ - **Collisions**: before writing, the CLI asks `Overwrite them?` if the run would replace existing files. Check the target paths; rename, or flag the overwrite in the plan and end that run's steps with `yes`.
98
+ - **Tests**: with `testingLibrary` set, df-ps always generates specs; add a test implementation (`in-memory`/`mock`) to repositories, execution commands/queries, and ports. Otherwise the spec wires the real one. Without `testingLibrary`, tell the user once and suggest adding it; don't edit the config yourself.
99
+ - **Prompts**: take the exact sequence for the generator and config from `references/generators.md`.
100
+
101
+ ## Running the driver
102
+
103
+ `df-ps` is interactive. `scripts/drive.mjs` answers its prompts, then lists created (`+`) and changed (`~`) files.
104
+
105
+ ```bash
106
+ node <this-skill-dir>/scripts/drive.mjs [--cwd <dir>] [--delay <ms>] <step>...
107
+ node scripts/drive.mjs "pick:Bounded Context: sales" pick:Domain "pick:New Aggregate" text:order yes default yes default
108
+ ```
109
+
110
+ | Step | Prompt | Effect |
111
+ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
112
+ | `pick:<label>` | select | Types a **prefix of the choice text** + Enter. Aborts before submitting if the highlighted choice doesn't match. |
113
+ | `text:<v>` / `default` | input | Types a value / accepts the default. |
114
+ | `yes` / `no` | confirm | |
115
+ | `toggle:1,3` / `none` | checkbox | Init, `Dependencies:`, `Dependencies for <Implementation>:`. |
116
+
117
+ Check every run: exit code 0, no `WARNING`/`ABORTED`, and exactly the planned files. "Still waiting for input" means too few steps; nothing was written. If the raw output ends at `Overwrite them?`, the run would replace files the plan didn't flag: show the user the listed files and ask, never just add `yes`. If prompts get out of sync, retry with `--delay 1200`.
118
+
119
+ ## Menu map
120
+
121
+ | Layer | Bounded context | Shared Layer |
122
+ | -------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
123
+ | Domain | New Aggregate, New Entity, New Value Object, Errors, New Service | New Entity, New Value Object, Errors, New Service |
124
+ | Application | New Query, New Command, New Use Case, New Port, New Service | New Port, New Service |
125
+ | Infrastructure | New Service | New Service |
126
+ | Presentation | New Handlers-REST Endpoint (needs handlers-rest), New Service | New Service |
127
+
128
+ With `@domain-first/wire`, the layer menu of a context and of the Shared Layer also has `Wire dependency`: it adds dependencies to an existing wired module.
129
+
130
+ The main menu also has `Scaffold React module` (needs `useReact`: New widget, New page, New UI-kit component, New shared hook) and `Scaffold new bounded context`.
131
+
132
+ Run order in a plan: new contexts → domain (aggregates before their entities and value objects) → application (ports, commands/queries, use cases) → endpoints → React (shared hooks → UI-kit → widgets → pages).
@@ -0,0 +1,103 @@
1
+ # Choosing the component for a piece of logic
2
+
3
+ The only place where these rules live.
4
+
5
+ Split the request into pieces of logic (one responsibility each). For each piece, go through the steps **in order**: the first "yes" decides. A name the user used ("service", "gateway") is not a decision.
6
+
7
+ ## Procedure
8
+
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 and widget type: below |
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 Layer |
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? (Its I/O is separate pieces.) | **Use case** |
19
+ | 9 | Data or behavior of **another context**? | **Execution query** (read) / **execution command** (write) in this context (see below) |
20
+ | 10 | Leaves this context's code and storage: external system or time? | **Port** (+ adapters) |
21
+ | 11 | One read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update)? | **Execution command** (write) / **query** (read) |
22
+ | 12 | A reusable read/write composed of other commands/queries/ports? | **Orchestrator command / query** |
23
+ | 13 | 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 |
24
+ | 14 | Application logic reused by 2+ use cases, with any external interaction delegated to injected ports? | **Application service** |
25
+ | 15 | A technical helper used only by infrastructure code? | **Infrastructure service** |
26
+ | 16 | A helper used only by presentation code? | **Presentation service** |
27
+ | — | None of the above | A method or function in an existing file |
28
+
29
+ - 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 execution queries/commands.
30
+ - Loading/saving one aggregate = a **repository method**, not a query or command.
31
+ - 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.
32
+ - Steps 9–10 beat 11–16. The other-context or external part becomes an execution query/command or a port. What remains may be a service that **receives it in its constructor**.
33
+ - Another context (step 9): input/output are this context's own models, duplicated in its terms, never the other context's. The implementation reaches the other context the simplest available way: a shared database → directly (the persistence label, e.g. `prisma`); otherwise the way chosen by `df-ps-plan-feature` (step 3, rule 4): if the project has several ways to reach a context (REST, message queue, RPC…), ask the user; with REST only, its REST endpoint (`http`). The test implementation returns fixed data. No imports from the other context.
34
+ - Don't create components "just in case": a command only when storage access deserves its own contract, an application service only when reused.
35
+
36
+ ## Port or service?
37
+
38
+ - A **port** describes a capability at the boundary: an external system or time. Its adapter performs the actual interaction. Own storage still follows the repository / execution command / query rules above. Another context is not a port: it's an execution query/command (step 9).
39
+ - An **application service** contains reusable application logic and may call injected ports. It does not call external SDKs, HTTP clients, or another context directly. A domain service remains pure: no I/O, ports, or repositories.
40
+ - Wanting to mock a class or imagining multiple implementations is not enough to make it a port. Identify the boundary capability first. Ports get swappable adapters and a test implementation under `NODE_ENV=test`; test a service's logic with fake dependencies.
41
+
42
+ Example: `order-confirmation` prepares a message and calls the injected `mailer` port. It stays an application service; the mailer adapter calls the email provider. Tests use a fake mailer and exercise the real service.
43
+
44
+ ## Commonly confused
45
+
46
+ | Pair | Rule |
47
+ | --- | --- |
48
+ | Port / repository | Own aggregate's persistence → repository. External system → port. |
49
+ | Port / execution command, query | Own storage or another context → command/query. External system → port. |
50
+ | Query / command | A query reads; it may have side effects, but only idempotent ones: repeating it changes nothing further (filling a cache, creating default settings if missing). Any other state change → command. A command may return data (the created order, the new balance). |
51
+ | 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. |
52
+ | Domain / application service | Stated without requests, permissions, responses, scenarios → domain. Otherwise application. |
53
+ | Use case / application service | Use case = one action with `handle`. Application service = helper used by use cases. |
54
+ | Use case / orchestrator | Use case = action exposed outside. Orchestrator = reusable operation called by use cases. |
55
+ | Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
56
+ | Clock | Always a port (`clock`, usually in Shared Layer). |
57
+
58
+ ## React page, widget, UI-kit component or shared hook
59
+
60
+ | Piece | Component |
61
+ | --- | --- |
62
+ | A route / whole screen | **Page** |
63
+ | A block with business meaning or backend data (`cart`, `order-summary`) | **Widget** |
64
+ | A generic element with no business meaning, driven only by props (`button`, `date-picker`, `modal`) | **UI-kit component** |
65
+ | A business element that several widgets repeat whole, with the same meaning (`product-card`) | **UI-kit component** (domain) |
66
+ | Generic app-wide logic without markup and business meaning (`debounce`, `media-query`, `local-storage`) | **Shared hook** |
67
+
68
+ 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.
69
+
70
+ 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.
71
+
72
+ **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.
73
+
74
+ 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 component'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`).
75
+
76
+ ## React widget type
77
+
78
+ 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.
79
+
80
+ ## Where it goes
81
+
82
+ - Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
83
+ - Shared Layer: technical, ownerless pieces (`clock`, `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 Layer 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 their own execution queries/commands.
84
+ - Another context's data or behavior → an execution query/command in the consuming context (step 9).
85
+
86
+ ## Example
87
+
88
+ *"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."*
89
+
90
+ | Piece | Step | Result (context `sales` unless noted) |
91
+ | --- | --- | --- |
92
+ | Order, customer | 4 | aggregates `order`, `customer` + repositories |
93
+ | Order line | 5 | `order-line.entity.ts` in `order` (used only by `order`) |
94
+ | Money | 6 | `domain/value-objects/money.value-object.ts` (used by `order` and `shipping-policy`) |
95
+ | "Can't pay twice" | 7 | `Order.pay()` |
96
+ | Discount ≤ 30% | 7 | `Order.applyDiscount()`: a rule about one aggregate's state; the use case passes the discount it got from the query |
97
+ | Place order, reorder | 8 | use cases `place-order`, `reorder` |
98
+ | Promo code check | 9 | execution query `promo-code-discount`: `prisma` if `marketing` shares the database, otherwise `http` to its endpoint |
99
+ | Email, order date | 10 | ports `mailer`, `clock` (Shared Layer) |
100
+ | Free shipping for gold customers | 13 | domain service `shipping-policy`: takes `customer` and `order`, no I/O |
101
+ | Confirmation for both use cases | 14 | application service `order-confirmation` (gets `mailer`) |
102
+ | Invalid promo code | 1 | error `invalid-promo-code` in namespace `order` |
103
+ | `POST /sales/orders` | 2 | endpoint, controller `orders` |
@@ -0,0 +1,234 @@
1
+ # df-ps generators: prompts and output
2
+
3
+ Notation: `<C>` = `<rootFolder>/bounded-contexts/<context>` or `<rootFolder>/shared`. `n` = the entered kebab-case name, `N` = PascalCase, `v` = camelCase. `I` = implementation label (`prisma` → `Prisma`). Specs are generated without a prompt **only if `testingLibrary` is set**. `{pkg}` = output depends on that `@domain-first/*` package.
4
+
5
+ Every step list starts with `"pick:Bounded Context: <ctx>"` or `"pick:Shared Layer"`, then the layer, then the operation (abbreviated below as `…`).
6
+
7
+ Any generator: 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.
8
+
9
+ {wire} Generators that create a wire (all below except endpoints, which ask their own two selects) then ask the checkbox `Dependencies:`, before `Overwrite them?`. It lists wired modules of `<C>` and of the Shared Layer (`(shared)` suffix), grouped under headers 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. Headers are not counted: `toggle:<n,..>` numbers only modules, top to bottom. Answer `toggle:<n,..>` or `none`. It is skipped when nothing fits, so check `<C>/wiring/` and `<rootFolder>/shared/wiring/` before counting steps. What fits depends on the layer of the class the wire builds: domain → domain; application → domain, application; infrastructure (repository, execution command/query, and port implementations) → domain, infrastructure (it implements application modules, never depends on them); presentation → application, presentation. On top of that, application services see only ports from application, use cases never see use cases, repository implementations never see repositories, execution command/query implementations never see commands or queries, and orchestration commands/queries see only execution commands and queries from application. Endpoints are never listed. Each chosen module goes into the wire (`wireClass(X, [wireUserRepository])`) and the constructor (`private readonly userRepository: UserRepository`, with `import type`), in the same order. An env-branched wire (repository, execution command/query, port) wires each implementation in isolation: instead of `Dependencies:` 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. It may start with a `Suggested` group: infrastructure modules whose file name has the implementation label (its folder, e.g. `prisma`, `in-memory`) as whole words, such as `in-memory-db-infrastructure-service` for `in-memory`. They are listed there only, so numbering starts with them.
10
+
11
+ ## Bounded context
12
+
13
+ `"pick:Scaffold new bounded context" text:sales` → folder `<rootFolder>/bounded-contexts/sales/`; {errors} `domain/errors/index.ts` with `SalesErrors = errorNamespace('sales')`.
14
+
15
+ ## Domain → New Aggregate (context only)
16
+
17
+ Prompts: name → `With Repository` → if yes: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
18
+
19
+ `… pick:Domain "pick:New Aggregate" text:order yes default yes default`
20
+
21
+ - `<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
22
+ - `<C>/infrastructure/repositories/I/I-n-repository.ts` per implementation (`class INRepository implements NRepository`)
23
+ - {wire} `<C>/wiring/repositories/wire-n-repository.ts` (env-branched)
24
+
25
+ ## Domain → New Entity / New Value Object (context and Shared Layer)
26
+
27
+ Prompts: name → aggregate (select: existing aggregate folders | `No aggregate`; asked only if `<C>/domain/aggregates/` has aggregates, so never in Shared Layer).
28
+
29
+ `… pick:Domain "pick:New Entity" text:order-line pick:order`
30
+ `… pick:Domain "pick:New Value Object" text:money "pick:No aggregate"`
31
+ `"pick:Shared Layer" pick:Domain "pick:New Value Object" text:money`
32
+
33
+ - 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`
34
+ - `No aggregate`: `<C>/domain/entities/n.entity.ts` or `<C>/domain/value-objects/n.value-object.ts`, spec; no barrel
35
+
36
+ ## Domain → Errors (context and Shared Layer)
37
+
38
+ First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
39
+
40
+ `… pick:Domain pick:Errors "pick:New namespace" text:order`
41
+ `… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
42
+ `… pick:Domain pick:Errors "pick:New error without" text:order-closed`
43
+
44
+ - Without namespace: appends `export const NCtxError = CtxErrors.define('n')` to `<C>/domain/errors/index.ts`
45
+ - New namespace: `<C>/domain/errors/ns.ts` (`NsCtxErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
46
+ - In namespace: appends `NNsCtxError = NsCtxErrors.define('n')` to `ns.ts`
47
+
48
+ Re-running is safe: an existing namespace file is kept, and a line already in the file isn't added again.
49
+
50
+ `Ctx` = PascalCase of the context folder (`Shared` in Shared Layer). Requires `index.ts` with `CtxErrors` {errors}.
51
+
52
+ ## Services: Domain / Application / Infrastructure / Presentation (context and Shared Layer)
53
+
54
+ Prompts: name. `L` = `domain` | `application` | `infrastructure` | `presentation`.
55
+
56
+ `… pick:Application "pick:New Service" text:checkout`
57
+
58
+ - `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
59
+ - {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
60
+
61
+ ## Application → New Use Case (context only)
62
+
63
+ Prompts: name. `… pick:Application "pick:New Use Case" text:place-order`
64
+
65
+ - `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
66
+ - {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
67
+
68
+ ## Application → New Command / New Query (context only)
69
+
70
+ Prompts: name → type (`Execution…` | `Orchestrator…`) → Execution only: implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`).
71
+
72
+ `… pick:Application "pick:New Command" text:place-order pick:Execution default yes default`
73
+ `… pick:Application "pick:New Query" text:order-summary pick:Orchestrator`
74
+
75
+ Execution:
76
+
77
+ - `<C>/application/commands/execution/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
78
+ - `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
79
+ - {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
80
+
81
+ Orchestrator: `<C>/application/commands/orchestration/n-command.ts` (concrete class), spec, {wire} `wire-n-command.ts`.
82
+
83
+ Queries: the same with `query` / `queries`.
84
+
85
+ ## Application → New Port (context and Shared Layer)
86
+
87
+ Prompts: name → adapter implementation (default `api`) → `With test implementation` → if yes: test implementation (default `mock`).
88
+
89
+ `… pick:Application "pick:New Port" text:payment-gateway default yes default`
90
+
91
+ - `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
92
+ - `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
93
+ - {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
94
+
95
+ ## Wire dependency (context and Shared Layer, needs wire)
96
+
97
+ Prompts: module (select: wired modules of `<C>`, grouped as below, 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 (as above). Modules already in the wire are not listed. If nothing fits, it prints `No dependencies available for this module.` and changes nothing.
98
+
99
+ `"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
100
+
101
+ Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`.
102
+
103
+ ## Presentation → New Handlers-REST Endpoint (context only, needs handlers-rest)
104
+
105
+ Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Endpoint generator:` (select: presentation services of `<C>` and the Shared Layer, `(shared)` suffix; those with `endpoint` in the name come first under `Suggested`; skipped if there are none) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
106
+
107
+ `… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RestEndpointGenerator pick:GetRecentOrders`
108
+ `… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:RestEndpointGenerator pick:PlaceOrder`
109
+
110
+ For `sales`, `orders`, `get`, `recent`:
111
+
112
+ - `<C>/presentation/rest/orders/recent/GET.ts`: `class OrdersRecentGetEndpoint(endpointGenerator, handler)`, route `['sales','orders','recent']`. With the picks: `endpointGenerator: RestEndpointGeneratorPresentationService` and `handler: GetRecentOrdersUseCase`, both `import type`. Without a pick: `EndpointGenerator` from handlers-rest and `handler: never`. `get handle()` calls `this.endpointGenerator(...)` either way: with a picked service, choose its generating method there (`this.endpointGenerator.generate(...)`).
113
+ - {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireGetRecentOrdersUseCase]`; `[]` without a generator) + a line in that folder's `index.ts`
114
+ - {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
115
+
116
+ The same controller, path, and method replace the existing endpoint (after `Overwrite them?`).
117
+
118
+ ## React (needs useReact)
119
+
120
+ `"pick:Scaffold React module" "pick:New page" text:checkout` → `<rootFolder>/presentation/react/pages/n-page.tsx`
121
+
122
+ `"pick:Scaffold React module" "pick:New widget" text:cart "pick:with separated ui"` → `…/widgets/n/`:
123
+
124
+ - `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`)
125
+ - `headless`: `n-widget.tsx`, `types.ts` (props include `UI`), `hooks/use-n-ui-model.ts`
126
+ - `monolithic`: `n-widget.tsx`
127
+ - every type: `index.ts` (`export * from './n-widget'`)
128
+
129
+ 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.
130
+
131
+ Move or rename a page or a widget only with df-ps, never by hand: `"pick:Scaffold React module" "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.
132
+
133
+ `"pick:Scaffold React module" "pick:New UI-kit" text:date-picker` → `…/ui-kit/n/`:
134
+
135
+ - `n.tsx` (`type NProps`, `const N: FC<NProps>`)
136
+ - `index.ts` (`export * from './n'`)
137
+ - with `storybookFramework`: `n.stories.tsx` (CSF3: `meta` with `title: 'UI-kit/N'`, story `Default`)
138
+
139
+ No Storybook prompt: UI-kit and widget UI stories follow the config.
140
+
141
+ `"pick:Scaffold React module" "pick:New shared hook" text:debounce` → `…/presentation/react/hooks/use-n.ts` (`const useN = () => …`). A leading `use-` in the name is dropped, so `use-debounce` gives the same file.
142
+
143
+ ### Story templates
144
+
145
+ Only for recreating a **missing** story (rule 2, exception 4).
146
+
147
+ UI-kit, at `…/ui-kit/n/n.stories.tsx`:
148
+
149
+ ```tsx
150
+ import type { Meta, StoryObj } from "<storybookFramework>";
151
+ import { N } from "./n";
152
+
153
+ const meta = {
154
+ title: "UI-kit/N",
155
+ component: N,
156
+ } satisfies Meta<typeof N>;
157
+
158
+ export default meta;
159
+
160
+ type Story = StoryObj<typeof meta>;
161
+
162
+ export const Default: Story = {
163
+ args: {},
164
+ };
165
+ ```
166
+
167
+ Widget UI (`with separated ui` only), at `…/widgets/n/ui/n-widget-ui.stories.tsx`:
168
+
169
+ ```tsx
170
+ import type { Meta, StoryObj } from "<storybookFramework>";
171
+ import { NWidgetUI } from "./n-widget-ui";
172
+
173
+ const meta = {
174
+ title: "Widgets/N",
175
+ component: NWidgetUI,
176
+ } satisfies Meta<typeof NWidgetUI>;
177
+
178
+ export default meta;
179
+
180
+ type Story = StoryObj<typeof meta>;
181
+
182
+ export const Default: Story = {
183
+ args: {},
184
+ };
185
+ ```
186
+
187
+ ## Env-branched wiring {wire}
188
+
189
+ ```ts
190
+ const wirePrismaImplementation = wireClass(PrismaOrderRepository, []);
191
+ const wireInMemoryImplementation = wireClass(InMemoryOrderRepository, []);
192
+
193
+ export const wireOrderRepository = envBranchedWire({
194
+ test: wireInMemoryImplementation, // primary if there's no test implementation
195
+ development: wirePrismaImplementation,
196
+ production: wirePrismaImplementation,
197
+ });
198
+ ```
199
+
200
+ ## Spec templates
201
+
202
+ Only for recreating a **missing** spec (rule 2, exception 1). With {wire}:
203
+
204
+ ```ts
205
+ import { describe, test, expect, beforeEach } from '<testingLibrary>'
206
+ import { type <Type> } from './<file>'
207
+ import { wire<Type> } from '<wirePath>'
208
+
209
+ let <var>: <Type>
210
+
211
+ beforeEach(() => {
212
+ <var> = wire<Type>()
213
+ })
214
+
215
+ describe('<label>', () => {
216
+ test('can be wired', () => {
217
+ expect(<var>).toBeDefined()
218
+ })
219
+ })
220
+ ```
221
+
222
+ Without wire: import `<Class>` from `<noWire>`, use `new <Class>()` and the test name `<noWireTest>`. If `<noWire>` is an implementation, add `type <Type> = <Class>`.
223
+
224
+ | Component | Spec next to | `<Type>` / `<var>` | `<wirePath>` | `<label>` | `<Class>` from `<noWire>`, `<noWireTest>` |
225
+ | -------------------- | ---------------------------- | ----------------------------- | ------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------- |
226
+ | Aggregate root | `n.aggregate-root.ts` | `N` / `v` | none: always `new N()` | `n words` | `N` `./n.aggregate-root`, `can be instantiated via constructor` |
227
+ | Repository* | `n-repository.ts` | `NRepository` / `vRepository` | `../../../wiring/repositories/wire-n-repository` | `n words repository` | `INRepository` `../../../infrastructure/repositories/I/I-n-repository`, `can be created via constructor` |
228
+ | Service | `n-L-service.ts` | `NLService` / `vLService` | `../../wiring/L-services/wire-n-L-service` | `n words` | `NLService` `./n-L-service`, `can be created` |
229
+ | Use case | `n-use-case.ts` | `NUseCase` / `vUseCase` | `../../wiring/use-cases/wire-n-use-case` | `n words use case` | `NUseCase` `./n-use-case`, `can be created` |
230
+ | Execution command | `execution/n-command.ts` | `NCommand` / `vCommand` | `../../../wiring/commands/wire-n-command` | `n words command` | `INCommand` `../../../infrastructure/commands/I/I-n-command`, `can be created via constructor` |
231
+ | Orchestrator command | `orchestration/n-command.ts` | `NCommand` / `vCommand` | `../../../wiring/commands/wire-n-command` | `n words command` | `NCommand` `./n-command`, `can be created via constructor` |
232
+ | Port | `n.ts` | `N` / `v` | `../../wiring/application-ports/wire-n` | `n words` | `IN` `../../infrastructure/application-adapters/I/I-n`, `can be created via constructor` |
233
+
234
+ `n words` = the name with spaces instead of hyphens. Queries are the same as commands. \*The repository spec imports the wire first, then `import type { NRepository } from './n-repository'`.