@domain-first/project-structure 8.11.0 → 8.12.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/dist/287.js +36 -967
- package/dist/364.js +3 -3
- package/dist/38.js +4 -3
- package/dist/561.js +76 -67
- package/dist/783.js +1147 -0
- package/dist/{201.js → 878.js} +455 -1
- package/dist/agent-cli.d.ts +5 -5
- package/dist/agent-requests.d.ts +9 -9
- package/dist/frontend-modules.d.ts +6 -1
- package/dist/graph.cjs +115 -4
- package/dist/graph.js +1 -1
- package/dist/index.cjs +129 -71
- package/dist/index.js +1 -1
- package/dist/init.cjs +49 -6
- package/dist/init.js +1 -1
- package/dist/integration.cjs +129 -71
- package/dist/integration.js +1 -1
- package/dist/integrations/openapi.d.ts +13 -3
- package/dist/lint.cjs +121 -9
- package/dist/lint.js +1 -1
- package/dist/react-module-move.d.ts +20 -2
- package/dist/react.cjs +185 -123
- package/dist/svelte.cjs +185 -123
- package/dist/upgrade-svelte.d.ts +15 -0
- package/dist/upgrade-svelte.spec.d.ts +1 -0
- package/dist/upgrade.cjs +296 -41
- package/dist/upgrade.js +132 -13
- package/dist/use-cases/scaffold-svelte-modules.d.ts +7 -2
- package/package.json +1 -1
- package/skills/df-ps-scaffold/SKILL.md +2 -2
- package/skills/df-ps-scaffold/references/agent-operations.md +2 -2
- package/skills/df-ps-svelte/SKILL.md +14 -9
- package/skills/df-ps-svelte/references/generators.md +5 -5
- package/dist/115.js +0 -616
package/dist/upgrade.js
CHANGED
|
@@ -4,8 +4,8 @@ import { parseArgs } from "node:util";
|
|
|
4
4
|
import { confirm as prompts_confirm } from "@inquirer/prompts";
|
|
5
5
|
import zod from "zod";
|
|
6
6
|
import node_fs from "node:fs";
|
|
7
|
-
import {
|
|
8
|
-
import { restFolders, withIdLookup,
|
|
7
|
+
import { domainFirstPackages as config_file_domainFirstPackages, discardPendingChanges, configSchema, module_move_walk, escapeRegExp, writePendingChanges, stageModuleMove, configFileName, toPosix, boundedContextNames, implementationLabelSchema, rulesSchema, ConfigFile, boundedContextPath, isOutdatedConfig, File, ProjectRoot, codeExtension, boundedContextName } from "./878.js";
|
|
8
|
+
import { svelteSwaggerPage, restFolders, withIdLookup, openapiExtractorPath, rootEndpointFileLookup, legacyEndpointFileLookup, hasLegacyRootEndpoints, legacyHasId, legacyWithIdLookup, endpointFileLookup, hasDependency, svelteKitStaticUrl, legacyRootEndpoints, swaggerPagePath } from "./783.js";
|
|
9
9
|
const serviceFile = ({ config })=>{
|
|
10
10
|
const project = config.project;
|
|
11
11
|
const rootFolder = 'object' == typeof project && null !== project ? project.rootFolder : void 0;
|
|
@@ -48,7 +48,7 @@ const rootMoves = (contextFolder)=>{
|
|
|
48
48
|
files: [
|
|
49
49
|
...[
|
|
50
50
|
...endpointFiles,
|
|
51
|
-
...parameterFolders.flatMap(
|
|
51
|
+
...parameterFolders.flatMap(module_move_walk)
|
|
52
52
|
].map((file)=>[
|
|
53
53
|
file,
|
|
54
54
|
intoRoot(presentation, file)
|
|
@@ -201,6 +201,122 @@ const openapiExtractorManualStep = {
|
|
|
201
201
|
]
|
|
202
202
|
};
|
|
203
203
|
const record = (value)=>'object' != typeof value || null === value || Array.isArray(value) ? {} : value;
|
|
204
|
+
const svelteOf = ({ config })=>'svelte' in record(config.frontend) ? record(record(config.frontend).svelte) : void 0;
|
|
205
|
+
const upgrade_svelte_rootFolderOf = ({ config })=>{
|
|
206
|
+
const rootFolder = record(config.project).rootFolder;
|
|
207
|
+
return 'string' == typeof rootFolder ? rootFolder : void 0;
|
|
208
|
+
};
|
|
209
|
+
const upgrade_svelte_relative = (file)=>toPosix(node_path.relative(new ProjectRoot().path, file));
|
|
210
|
+
const svelteFolder = (context)=>{
|
|
211
|
+
const rootFolder = upgrade_svelte_rootFolderOf(context);
|
|
212
|
+
return svelteOf(context) && rootFolder ? node_path.join(new ProjectRoot().path, rootFolder, 'presentation', 'svelte') : void 0;
|
|
213
|
+
};
|
|
214
|
+
const legacySwaggerPage = (context)=>{
|
|
215
|
+
const rootFolder = upgrade_svelte_rootFolderOf(context);
|
|
216
|
+
if (!svelteOf(context) || !rootFolder) return;
|
|
217
|
+
const file = new File(node_path.join(new ProjectRoot().path, swaggerPagePath(rootFolder, 'svelte')));
|
|
218
|
+
return file.exists && /swagger-ui\/dist\/swagger-ui\.css|import\(\s*['"]swagger-ui['"]\s*\)/.test(file.data) ? file : void 0;
|
|
219
|
+
};
|
|
220
|
+
const importedSpecPath = (page)=>{
|
|
221
|
+
const specifier = page.data.match(/import\s+spec\s+from\s+['"]([^'"]+)['"]/)?.[1];
|
|
222
|
+
return specifier?.startsWith('.') ? upgrade_svelte_relative(node_path.resolve(node_path.dirname(page.path), specifier)) : void 0;
|
|
223
|
+
};
|
|
224
|
+
const svelteSwaggerPageStep = {
|
|
225
|
+
id: 'svelte-swagger-ui-dist',
|
|
226
|
+
kind: 'optional',
|
|
227
|
+
title: 'Render the Svelte Swagger UI page with swagger-ui-dist',
|
|
228
|
+
detect: (context)=>{
|
|
229
|
+
const page = legacySwaggerPage(context);
|
|
230
|
+
return !!page && !!importedSpecPath(page);
|
|
231
|
+
},
|
|
232
|
+
plan: (context)=>{
|
|
233
|
+
const page = legacySwaggerPage(context);
|
|
234
|
+
return [
|
|
235
|
+
`${upgrade_svelte_relative(page.path)}: regenerated on swagger-ui-dist/swagger-ui-bundle.js, which bundles its own React`
|
|
236
|
+
];
|
|
237
|
+
},
|
|
238
|
+
apply: (context)=>{
|
|
239
|
+
const page = legacySwaggerPage(context);
|
|
240
|
+
const outputPath = importedSpecPath(page);
|
|
241
|
+
const sveltekit = svelteOf(context)?.framework === 'sveltekit';
|
|
242
|
+
page.update(svelteSwaggerPage(upgrade_svelte_rootFolderOf(context), outputPath, sveltekit ? svelteKitStaticUrl(outputPath) : void 0));
|
|
243
|
+
}
|
|
244
|
+
};
|
|
245
|
+
const svelteSwaggerPackagesStep = {
|
|
246
|
+
id: 'svelte-swagger-ui-dist-packages',
|
|
247
|
+
kind: 'manual',
|
|
248
|
+
title: 'Replace swagger-ui with swagger-ui-dist',
|
|
249
|
+
detect: (context)=>!!svelteOf(context) && hasDependency('swagger-ui'),
|
|
250
|
+
plan: ()=>[
|
|
251
|
+
`npm uninstall swagger-ui${hasDependency('@types/swagger-ui') ? ' @types/swagger-ui' : ''}`,
|
|
252
|
+
...hasDependency('swagger-ui-dist') ? [] : [
|
|
253
|
+
'npm install swagger-ui-dist'
|
|
254
|
+
],
|
|
255
|
+
...hasDependency('@types/swagger-ui-dist') ? [] : [
|
|
256
|
+
'npm install --save-dev @types/swagger-ui-dist'
|
|
257
|
+
]
|
|
258
|
+
]
|
|
259
|
+
};
|
|
260
|
+
const legacyFunctionNames = (file)=>[
|
|
261
|
+
...node_fs.readFileSync(file, 'utf8').matchAll(/export\s+(?:const|function)\s+use(\w+)\b/g)
|
|
262
|
+
].map(([, name])=>[
|
|
263
|
+
`use${name}`,
|
|
264
|
+
`create${name}`
|
|
265
|
+
]);
|
|
266
|
+
const legacyModels = (context)=>{
|
|
267
|
+
const folder = svelteFolder(context);
|
|
268
|
+
if (!folder) return [];
|
|
269
|
+
const isModule = (file)=>/^use-.+\.svelte\.[jt]s$/.test(node_path.basename(file)) && !/\.(spec|test)\./.test(file);
|
|
270
|
+
const renamed = (file)=>node_path.basename(file).replace(/^use-/, 'create-');
|
|
271
|
+
const widgetModels = module_move_walk(node_path.join(folder, 'widgets')).filter((file)=>'hooks' === node_path.basename(node_path.dirname(file)) && /-ui-model\./.test(file) && isModule(file)).map((file)=>({
|
|
272
|
+
from: file,
|
|
273
|
+
to: node_path.join(node_path.dirname(node_path.dirname(file)), 'model', renamed(file))
|
|
274
|
+
}));
|
|
275
|
+
const sharedFolder = node_path.join(folder, 'hooks');
|
|
276
|
+
const sharedHooks = node_fs.existsSync(sharedFolder) ? node_fs.readdirSync(sharedFolder).map((name)=>node_path.join(sharedFolder, name)).filter(isModule).map((file)=>({
|
|
277
|
+
from: file,
|
|
278
|
+
to: node_path.join(folder, 'shared', 'model', renamed(file))
|
|
279
|
+
})) : [];
|
|
280
|
+
return [
|
|
281
|
+
...widgetModels,
|
|
282
|
+
...sharedHooks
|
|
283
|
+
].filter(({ to })=>!node_fs.existsSync(to)).map((move)=>({
|
|
284
|
+
...move,
|
|
285
|
+
names: legacyFunctionNames(move.from)
|
|
286
|
+
}));
|
|
287
|
+
};
|
|
288
|
+
const svelteModelsStep = {
|
|
289
|
+
id: 'svelte-models',
|
|
290
|
+
kind: 'optional',
|
|
291
|
+
title: 'Rename Svelte hooks to models: model/create-*.svelte.ts',
|
|
292
|
+
detect: (context)=>legacyModels(context).length > 0,
|
|
293
|
+
plan: (context)=>legacyModels(context).flatMap(({ from, to, names })=>[
|
|
294
|
+
`${upgrade_svelte_relative(from)} → ${upgrade_svelte_relative(to)}`,
|
|
295
|
+
...names.map(([from, to])=>` ${from} → ${to}`)
|
|
296
|
+
]),
|
|
297
|
+
apply: (context)=>{
|
|
298
|
+
const models = legacyModels(context);
|
|
299
|
+
const moves = new Map(models.map(({ from, to })=>[
|
|
300
|
+
from,
|
|
301
|
+
to
|
|
302
|
+
]));
|
|
303
|
+
const withoutExtension = new Map(models.map(({ from, to })=>[
|
|
304
|
+
from.replace(codeExtension, ''),
|
|
305
|
+
to.replace(codeExtension, '')
|
|
306
|
+
]));
|
|
307
|
+
const names = models.flatMap((model)=>model.names);
|
|
308
|
+
const namePattern = names.length && new RegExp(`(?<![\\w$])(${names.map(([from])=>escapeRegExp(from)).join('|')})(?![\\w$])`, 'g');
|
|
309
|
+
const renames = new Map(names);
|
|
310
|
+
stageModuleMove({
|
|
311
|
+
projectRoot: new ProjectRoot().path,
|
|
312
|
+
stopAt: svelteFolder(context),
|
|
313
|
+
moves,
|
|
314
|
+
movedPath: (candidate)=>moves.get(candidate) ?? withoutExtension.get(candidate),
|
|
315
|
+
rename: (content)=>namePattern ? content.replace(namePattern, (name)=>renames.get(name) ?? name) : content
|
|
316
|
+
});
|
|
317
|
+
}
|
|
318
|
+
};
|
|
319
|
+
const upgrade_steps_record = (value)=>'object' != typeof value || null === value || Array.isArray(value) ? {} : value;
|
|
204
320
|
const flatConfigSchema = zod.object({
|
|
205
321
|
rootFolder: zod.string().min(1),
|
|
206
322
|
domainFirstPackages: zod.array(zod["enum"](config_file_domainFirstPackages)),
|
|
@@ -254,17 +370,17 @@ const sectionsStep = {
|
|
|
254
370
|
};
|
|
255
371
|
}
|
|
256
372
|
};
|
|
257
|
-
const reactOf = (config)=>
|
|
373
|
+
const reactOf = (config)=>upgrade_steps_record(upgrade_steps_record(config.frontend).react);
|
|
258
374
|
const frameworkStep = {
|
|
259
375
|
id: 'react-framework',
|
|
260
376
|
kind: 'required',
|
|
261
377
|
title: 'Record the frontend framework explicitly',
|
|
262
|
-
detect: ({ config })=>'react' in
|
|
378
|
+
detect: ({ config })=>'react' in upgrade_steps_record(config.frontend) && !reactOf(config).framework,
|
|
263
379
|
plan: ()=>[
|
|
264
380
|
hasDependency('next') ? 'frontend.react.framework: "next" (next is in package.json)' : 'frontend.react.framework: "react" (next is not in package.json)'
|
|
265
381
|
],
|
|
266
382
|
apply: ({ config })=>{
|
|
267
|
-
const frontend =
|
|
383
|
+
const frontend = upgrade_steps_record(config.frontend);
|
|
268
384
|
config.frontend = {
|
|
269
385
|
...frontend,
|
|
270
386
|
react: {
|
|
@@ -283,9 +399,9 @@ const persistenceStep = {
|
|
|
283
399
|
id: 'persistence-default',
|
|
284
400
|
kind: 'required',
|
|
285
401
|
title: 'Move the default persistence implementation to saved implementation types',
|
|
286
|
-
detect: ({ config })=>'defaultPersistenceLayerImplementation' in
|
|
402
|
+
detect: ({ config })=>'defaultPersistenceLayerImplementation' in upgrade_steps_record(config.backend),
|
|
287
403
|
plan: ({ config })=>{
|
|
288
|
-
const label =
|
|
404
|
+
const label = upgrade_steps_record(config.backend).defaultPersistenceLayerImplementation;
|
|
289
405
|
if (void 0 === label) return [];
|
|
290
406
|
return implementationLabelSchema.safeParse(label).success ? [
|
|
291
407
|
`defaultPersistenceLayerImplementation "${label}" → first primary type of backend.implementations.${persistenceKinds.join(', ')}`
|
|
@@ -294,11 +410,11 @@ const persistenceStep = {
|
|
|
294
410
|
];
|
|
295
411
|
},
|
|
296
412
|
apply: ({ config })=>{
|
|
297
|
-
const { defaultPersistenceLayerImplementation: label, ...backend } =
|
|
298
|
-
const implementations =
|
|
413
|
+
const { defaultPersistenceLayerImplementation: label, ...backend } = upgrade_steps_record(config.backend);
|
|
414
|
+
const implementations = upgrade_steps_record(backend.implementations);
|
|
299
415
|
if (implementationLabelSchema.safeParse(label).success) {
|
|
300
416
|
for (const kind of persistenceKinds){
|
|
301
|
-
const group =
|
|
417
|
+
const group = upgrade_steps_record(implementations[kind]);
|
|
302
418
|
const primary = Array.isArray(group.primary) ? group.primary : [];
|
|
303
419
|
implementations[kind] = {
|
|
304
420
|
primary: [
|
|
@@ -321,12 +437,15 @@ const upgradeSteps = [
|
|
|
321
437
|
openapiExtractorRootStep,
|
|
322
438
|
openapiExtractorNestedStep,
|
|
323
439
|
openapiExtractorManualStep,
|
|
324
|
-
inMemoryDbWithIdStep
|
|
440
|
+
inMemoryDbWithIdStep,
|
|
441
|
+
svelteSwaggerPageStep,
|
|
442
|
+
svelteSwaggerPackagesStep,
|
|
443
|
+
svelteModelsStep
|
|
325
444
|
];
|
|
326
445
|
const skillsNote = 'Update the agent skills to this version: npx df-skills';
|
|
327
446
|
const planUpgrade = async (config, acceptOptional = ()=>true, steps = upgradeSteps)=>{
|
|
328
447
|
const context = {
|
|
329
|
-
config: structuredClone(
|
|
448
|
+
config: structuredClone(upgrade_steps_record(config))
|
|
330
449
|
};
|
|
331
450
|
const original = JSON.stringify(context.config);
|
|
332
451
|
const planned = [];
|
|
@@ -5,6 +5,10 @@ import { NestedName } from '../nested-name';
|
|
|
5
5
|
* script, so importers can use it as with `export type` in React.
|
|
6
6
|
*/
|
|
7
7
|
export declare const svelteComponentContent: (propsType: string) => string;
|
|
8
|
+
/**
|
|
9
|
+
* The UI model of a widget: props → UI props, reactive through getters.
|
|
10
|
+
*/
|
|
11
|
+
export declare const svelteUIModelContent: (ClassName: string, propsType: string) => string;
|
|
8
12
|
/** A thin SvelteKit route that renders the page component. */
|
|
9
13
|
export declare const svelteKitRouteContent: (ClassName: string, pageImport: string) => string;
|
|
10
14
|
/**
|
|
@@ -17,6 +21,7 @@ export declare const scaffoldSveltePage: (presentationSvelteFolder: Folder) => P
|
|
|
17
21
|
export declare const scaffoldSvelteWidget: (presentationSvelteFolder: Folder) => Promise<void>;
|
|
18
22
|
export declare const scaffoldSvelteUIKitComponent: (presentationSvelteFolder: Folder) => Promise<void>;
|
|
19
23
|
/**
|
|
20
|
-
* A shared
|
|
24
|
+
* A shared model is a `.svelte.ts` factory, so it may use runes. Svelte
|
|
25
|
+
* has no hooks: in SvelteKit they are `hooks.server.ts`/`hooks.client.ts`.
|
|
21
26
|
*/
|
|
22
|
-
export declare const
|
|
27
|
+
export declare const scaffoldSvelteSharedModel: (presentationSvelteFolder: Folder) => Promise<void>;
|
package/package.json
CHANGED
|
@@ -11,7 +11,7 @@ Follow this order for every request:
|
|
|
11
11
|
|
|
12
12
|
1. Read `domain-first.project-structure.config.json` beside the nearest `package.json`: `project.rootFolder`, `backend` (including `backend.implementations` and `backend.rules`), and `frontend`. `frontend.react.framework` records React (`react`) or Next.js (`next`); both use `df-react`. `frontend.svelte.framework` records Svelte (`svelte`) or SvelteKit (`sveltekit`); both use `df-svelte`. Initialization and configuration belong to the human: never run `df-init` or manually add/change these settings. If the config is missing, tell the user to run `npx df-init`; if backend work needs an absent `backend`, tell them to run `npx df-init --section backend`. Continue only with work whose required sections are configured. A config of an earlier major version (flat, without `project`) makes every command stop with `run npx df-upgrade` (`CONFIG_OUTDATED` in JSON mode): ask the user to run `npx df-upgrade`; never run it or convert the config yourself. `df-init` scaffolds explicit standard lists and enabled lint checks under `backend.rules`; read the saved values as authoritative. Older or partial configs may omit entries, which retain the defaults. Backend reconfiguration by the user fills missing entries without resetting existing rules.
|
|
13
13
|
2. Feature request without named contexts/components → `df-ps-plan-feature` (it covers steps 3–5).
|
|
14
|
-
3. Choose a component for each piece of logic with `references/choosing-components.md`. Pieces of UI (pages, widgets, UI-kit components, shared hooks): `df-ps-react` (Svelte: `df-ps-svelte
|
|
14
|
+
3. Choose a component for each piece of logic with `references/choosing-components.md`. Pieces of UI (pages, widgets, UI-kit components, shared hooks): `df-ps-react` (Svelte: `df-ps-svelte`, with shared models in place of shared hooks).
|
|
15
15
|
4. Read `references/units/<unit>.md` for every unit in the plan ("Units" below) and prepare the run details ("Preparing runs"). Read [agent-mode.md](references/agent-mode.md) for the JSON protocol and use `--describe` to obtain the installed request schema and selectable IDs.
|
|
16
16
|
5. If the task creates files, show the work plan and **stop until it's approved** (rule 1).
|
|
17
17
|
6. Run the generators in plan order with `--request` JSON; check exit code, `ok` and all returned file lists.
|
|
@@ -40,7 +40,7 @@ Every new file is created by `df-scaffold` (React modules: `df-react`; Svelte mo
|
|
|
40
40
|
| --- | --- | --- | --- |
|
|
41
41
|
| 1 | Missing spec | `<component>.spec.ts` next to the component | Exactly from "Spec templates" in `references/generators.md`. |
|
|
42
42
|
| 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. |
|
|
43
|
-
| 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` (Svelte: `…/presentation/svelte/widgets/<name
|
|
43
|
+
| 3 | Widget hooks / UI | `…/presentation/react/widgets/<name>/hooks/**`, `ui/**` (Svelte: `…/presentation/svelte/widgets/<name>/model/**`, `ui/**`) | Widget generated by df-react or df-svelte. |
|
|
44
44
|
| 4 | Widget/page/UI-kit support files | inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.tsx`, `*.stories.tsx`; next to a page: `pages/<name>-page.module.css`, for a nested page in its folder (`pages/admin/admin-users-page.module.css`) (layout of its widgets only) | Widget/page/UI-kit component generated by df-react. Details and story templates: `df-ps-react`. |
|
|
45
45
|
| 5 | App bootstrap and config | outside `<rootFolder>/{bounded-contexts,shared-kernel,presentation}/`: entry point, HTTP server setup registering `restHandlers`, tool configs | Bootstrapping only. Domain/application/infrastructure logic never goes there. |
|
|
46
46
|
|
|
@@ -131,7 +131,7 @@ All support `dryRun` and `overwrite`. Use CLI moves even for a rename or folder
|
|
|
131
131
|
|
|
132
132
|
## Svelte operations: df-svelte
|
|
133
133
|
|
|
134
|
-
With `frontend.svelte` configured, `df-svelte` takes the same operations and fields as `df-react` for `<rootFolder>/presentation/svelte
|
|
134
|
+
With `frontend.svelte` configured, `df-svelte` takes the same operations and fields as `df-react` for `<rootFolder>/presentation/svelte/`, except that Svelte has shared models, not hooks: `shared-model`, `move-shared-model` and `delete-shared-model` (`shared/model/create-<name>.svelte.ts`, `create<Name>`; a leading `create-` is dropped) replace the `shared-hook` operations, which `df-svelte` rejects with `INVALID_REQUEST`. `--describe` lists modules as `svelteModules`, shared models with kind `model`. Svelte and SvelteKit use the same operations. With SvelteKit, `page` also creates `src/routes/<name>/+page.svelte`, and `moveRoute` / `deleteRoute` apply to that route folder. Stories follow `frontend.svelte.storybookFramework`. Generated files: `df-ps-svelte/references/generators.md`.
|
|
135
135
|
|
|
136
136
|
## Integrations: df-integration
|
|
137
137
|
|
|
@@ -148,7 +148,7 @@ Use `operation: "add"` and a nonempty `integrations` array. Select only IDs mark
|
|
|
148
148
|
| `playwright` | No extra integration-specific fields. Adds its config, example and scripts. |
|
|
149
149
|
| `testcontainers` | Backend required. With wire: optional `integrationTestTypes`, the saved primary types whose implementations get integration specs (omitted: the configured list stays); missing specs of existing primary implementations are added. Reads staged Prisma/Drizzle/Vitest setup when selected together. Database scripts are generated, not executed. |
|
|
150
150
|
| `openapi` | Backend with `handlers-rest`. `routePrefix` defaults to `/api`; `openapiPath` is computed from the project unless supplied. `withExtractor` defaults to true. `swaggerPage` applies only with React or Svelte configured and defaults to true there; otherwise omit it. With Svelte it is `swagger-page.svelte` (route `src/routes/swagger/+page.svelte` with SvelteKit), and `openapiPath` defaults to `static/openapi.json` with SvelteKit. |
|
|
151
|
-
| `orval` | Requires configured `handlers-rest`. `openapiPath` is read from the staged/existing OpenAPI generator when omitted. With React or Svelte configured, `targets` can be a nonempty list of `hooks`/`client` and defaults to `hooks` (React Query or Svelte Query
|
|
151
|
+
| `orval` | Requires configured `handlers-rest`. `openapiPath` is read from the staged/existing OpenAPI generator when omitted. With React or Svelte configured, `targets` can be a nonempty list of `hooks`/`client` and defaults to `hooks` (React Query hooks, or Svelte Query `createQuery`/`createMutation`; with SvelteKit, a missing `src/routes/+layout.svelte` is created with `QueryProvider`). Without a frontend, omit `targets`: the typed client is generated automatically. |
|
|
152
152
|
|
|
153
153
|
Fields for integrations not selected, or for conditions that do not apply, must be omitted. For example, `targets` on a non-React project and `nextAdapter` on an explicitly React project are unused parameters. If OpenAPI and Orval are selected together, a supplied `openapiPath` applies to both.
|
|
154
154
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: df-ps-svelte
|
|
3
|
-
description: Build the Svelte part of a Domain-First project with the `df-svelte` CLI (@domain-first/project-structure) — choose between pages, widgets (separated UI, headless, monolithic), UI-kit components and shared
|
|
3
|
+
description: Build the Svelte part of a Domain-First project with the `df-svelte` CLI (@domain-first/project-structure) — choose between pages, widgets (separated UI, headless, monolithic), UI-kit components and shared models (Svelte 5 runes, `create…` factories), generate them with Storybook stories and SvelteKit routes, move, rename or delete them, and implement them against the backend without importing bounded contexts. Use when the project has domain-first.project-structure.config.json with frontend.svelte configured and the user asks for screens, UI blocks, components, runes, reusable reactive logic or stories, or to move, rename or regroup a page or widget.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Svelte modules with df-svelte
|
|
@@ -11,15 +11,15 @@ Svelte modules live in `<rootFolder>/presentation/svelte/` (`…/svelte/` below)
|
|
|
11
11
|
|
|
12
12
|
1. Read `domain-first.project-structure.config.json`: source root is `project.rootFolder`; Svelte is enabled by `frontend.svelte`; `frontend.svelte.framework` is `svelte` or `sveltekit`, and both use `df-svelte`. Stories use `frontend.svelte.storybookFramework` (`@storybook/svelte-vite` or `@storybook/sveltekit`). A config of an earlier major version (`CONFIG_OUTDATED`): ask the user to run `npx df-upgrade`; never run it yourself. Without the config, tell the user to run `npx df-init`; without Svelte configured, tell them to run `npx df-init --section frontend`. Initialization and configuration belong to the human: do not run `df-init` or edit these settings yourself.
|
|
13
13
|
2. A feature that also needs backend work → plan it with `df-ps-plan-feature`; Svelte runs come last in the plan.
|
|
14
|
-
3. Choose a module for each piece of UI by "Choosing the module" of `df-ps-react`: page, widget, UI-kit component, shared hook. Widgets never import each other; the widget type defaults to `with separated ui`.
|
|
14
|
+
3. Choose a module for each piece of UI by "Choosing the module" of `df-ps-react`: page, widget, UI-kit component, shared model (React's shared hook: Svelte has no hooks). Widgets never import each other; the widget type defaults to `with separated ui`.
|
|
15
15
|
4. Show the work plan in the format of `df-ps-scaffold/references/work-plan.md` (the frontend block, `df-svelte` runs) and **stop until it's approved**. Details holds the widget type and, for a page move or delete with SvelteKit, whether the route follows.
|
|
16
|
-
5. Run the generators with `df-svelte --request` JSON in plan order (shared
|
|
16
|
+
5. Run the generators with `df-svelte --request` JSON in plan order (shared models → UI-kit → widgets → pages); check each output.
|
|
17
17
|
6. Implement ("Implementing"), after the backend and the regenerated API client.
|
|
18
18
|
7. Run `npx df-lint` and the project's svelte-check/lint/tests. Report against the plan.
|
|
19
19
|
|
|
20
20
|
## Running df-svelte
|
|
21
21
|
|
|
22
|
-
Prefer `npx df-svelte --describe` and `npx df-svelte --request` JSON. The operations and fields are those of `df-react` (`page`, `widget`, `ui-kit-component`, `shared-
|
|
22
|
+
Prefer `npx df-svelte --describe` and `npx df-svelte --request` JSON. The operations and fields are those of `df-react` (`page`, `widget`, `ui-kit-component`, `move-*`, `delete-*`), with `shared-model`, `move-shared-model` and `delete-shared-model` in place of the `shared-hook` ones; `--describe` lists current Svelte modules as `svelteModules` (shared models with kind `model`). For example:
|
|
23
23
|
|
|
24
24
|
```bash
|
|
25
25
|
npx df-svelte --request '{"operation":"widget","name":"cart","widgetType":"separated"}'
|
|
@@ -33,7 +33,7 @@ Moving, renaming and deleting go through df-svelte, never by hand, with an appro
|
|
|
33
33
|
|
|
34
34
|
Only these (`df-ps-scaffold`, rule 2, exceptions 3–4), for modules generated by df-svelte:
|
|
35
35
|
|
|
36
|
-
- Widget
|
|
36
|
+
- Widget models and UI parts: `…/svelte/widgets/<name>/model/**` (`*.svelte.ts` for runes), `ui/**`.
|
|
37
37
|
- Support files inside the widget folder or `ui-kit/<name>/`: styles, assets, `*.test.ts`, `*.stories.ts`. A missing UI-kit or widget UI story: exactly from "Story templates" in `references/generators.md`.
|
|
38
38
|
- A page stays one `.svelte` file that composes widgets; its `<style>` block lays out its widgets only. Its own state, UI parts or types mean a widget is missing, so generate it.
|
|
39
39
|
- SvelteKit route files next to a generated route (`+page.ts`, `+layout.svelte`, `+error.svelte`) for loading and layout; the route's `+page.svelte` only renders the page component.
|
|
@@ -41,9 +41,14 @@ Only these (`df-ps-scaffold`, rule 2, exceptions 3–4), for modules generated b
|
|
|
41
41
|
## Implementing
|
|
42
42
|
|
|
43
43
|
- Svelte 5 with runes: props through `$props()`, state through `$state`, derived values through `$derived`. Each component exports its props type from `<script lang="ts" module>`.
|
|
44
|
-
- Separated UI widget: state, effects and derived data in `
|
|
45
|
-
-
|
|
44
|
+
- Separated UI widget: state, effects and derived data in `model/create-<name>-ui-model.svelte.ts` (`create<Name>UIModel`: props → UI props); `ui/` stays presentational. Keep it reactive:
|
|
45
|
+
- take `widgetProps` whole, the `$props()` proxy; destructuring it in the signature (`({ a }) =>`) or copying props in `<script>` (`{ ...props }`, `{ a: props.a }`) reads them once and the UI stops following them;
|
|
46
|
+
- values that depend on props are `$derived` and leave the model through getters only (`get total() { return total }`); getters satisfy the UI props type;
|
|
47
|
+
- local state is `$state`; methods are plain functions of the returned object;
|
|
48
|
+
- keep the generated `// svelte-ignore state_referenced_locally` before `create<Name>UIModel(props)`: the proxy never changes, the warning is a false positive.
|
|
49
|
+
- Headless: the same model, given `widgetProps` from `let { UI, ...widgetProps } = $props()` (the rest stays reactive); the consumer passes `UI` (a `Component<UIProps>`).
|
|
50
|
+
- UI-kit components and shared models (`…/svelte/shared/model/create-<name>.svelte.ts`, `create<Name>`): the same limits as in `df-ps-react` — driven only by props or arguments; no API client, no data loading, no imports from widgets, pages or contexts.
|
|
46
51
|
- Stories (`frontend.svelte.storybookFramework`): fill `args` of `Default` with valid props and add one story per meaningful state. Keep `meta`, the file name and the title (`UI-kit/N` or `Widgets/N`).
|
|
47
|
-
- Talking to the backend: as in `df-ps-react` ("Talking to the backend") — a generated API client first (Orval's Svelte Query
|
|
52
|
+
- Talking to the backend: as in `df-ps-react` ("Talking to the backend") — a generated API client first (Orval's Svelte Query `createQuery`/`createMutation` in `<rootFolder>/presentation/svelte/data-layer/orval`, or its typed client in `<rootFolder>/presentation/data-layer`; queries need `QueryProvider` from `…/svelte/data-layer/query-provider.svelte` above them, which SvelteKit's root `+layout.svelte` provides), `import type` of endpoint contracts only without one. SvelteKit `+page.ts`/`+page.server.ts` loads call the client, not bounded contexts.
|
|
48
53
|
|
|
49
|
-
`npx df-lint` (check `svelte`) reports a widget importing another widget, UI-kit importing widgets, pages or contexts, shared
|
|
54
|
+
`npx df-lint` (check `svelte`) reports a widget importing another widget, UI-kit importing widgets, pages or contexts, shared models importing UI-kit, widgets, pages or contexts, and Svelte importing contexts beyond the contract types. Fix every finding.
|
|
@@ -12,8 +12,8 @@ Notation: `…/svelte/` = `<rootFolder>/presentation/svelte/`. `n` = the entered
|
|
|
12
12
|
|
|
13
13
|
`…/svelte/widgets/n/`:
|
|
14
14
|
|
|
15
|
-
- `with separated ui` (default): `n-widget.svelte`, `types.ts`, `ui/n-widget-ui.svelte`, `
|
|
16
|
-
- `headless`: `n-widget.svelte` (renders `<UI {...uiModel} />`), `types.ts` (props include `UI: Component<NWidgetUIProps>`), `
|
|
15
|
+
- `with separated ui` (default): `n-widget.svelte`, `types.ts`, `ui/n-widget-ui.svelte`, `model/create-n-ui-model.svelte.ts` (`createNUIModel`, returning getters); with `storybookFramework`: `ui/n-widget-ui.stories.ts` (CSF3: `title: 'Widgets/N'`, `component: NWidgetUI`, story `Default`)
|
|
16
|
+
- `headless`: `n-widget.svelte` (renders `<UI {...uiModel} />`), `types.ts` (props include `UI: Component<NWidgetUIProps>`), `model/create-n-ui-model.svelte.ts`, given the rest of `let { UI, ...widgetProps } = $props()`
|
|
17
17
|
- `monolithic`: `n-widget.svelte` (`NWidgetProps`)
|
|
18
18
|
- every type: `index.ts` (`export { default as NWidget } from './n-widget.svelte'` and the props type)
|
|
19
19
|
|
|
@@ -23,13 +23,13 @@ Nested names work as in df-react: `admin/panel/users` → `…/widgets/admin/pan
|
|
|
23
23
|
|
|
24
24
|
`…/svelte/ui-kit/n/`: `n.svelte` (`NProps`), `index.ts` (`export { default as N } from './n.svelte'` and `NProps`), with `storybookFramework`: `n.stories.ts` (`title: 'UI-kit/N'`).
|
|
25
25
|
|
|
26
|
-
## New shared
|
|
26
|
+
## New shared model
|
|
27
27
|
|
|
28
|
-
`…/svelte/
|
|
28
|
+
Operation `shared-model`: `…/svelte/shared/model/create-n.svelte.ts` (`const createN = () => …`), so it may use runes. A leading `create-` in the name is dropped. Svelte has no hooks: in SvelteKit they are `hooks.server.ts`/`hooks.client.ts`.
|
|
29
29
|
|
|
30
30
|
## Move, rename, delete
|
|
31
31
|
|
|
32
|
-
As in df-react: files, `<Name>Page` / `<Name>Widget…` / `
|
|
32
|
+
As in df-react: files, `<Name>Page` / `<Name>Widget…` / `create<Name>UIModel` / `<Name>` / `create<Name>`, story titles and every import (with or without the `.svelte` extension, relative or through `tsconfig` aliases) follow a move; a delete is refused while other files import the module. With SvelteKit, the page's own route folder files move or are deleted too when confirmed.
|
|
33
33
|
|
|
34
34
|
## Story templates
|
|
35
35
|
|