@domain-first/project-structure 8.4.0 → 8.5.1
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 +6 -3
- package/dist/287.js +70 -46
- package/dist/38.js +23 -11
- package/dist/561.js +10 -7
- package/dist/870.js +2 -1
- package/dist/agent-cli.d.ts +2 -2
- package/dist/agent-requests.d.ts +2 -2
- package/dist/config-file.d.ts +4 -1
- package/dist/graph.cjs +2 -1
- package/dist/index.cjs +82 -54
- package/dist/init.cjs +2 -1
- package/dist/integration.cjs +82 -54
- package/dist/lint.cjs +27 -13
- package/dist/lint.js +2 -1
- package/dist/react.cjs +82 -54
- package/dist/upgrade-steps.d.ts +1 -1
- package/dist/upgrade.cjs +2 -1
- package/package.json +1 -1
- package/skills/df-ps-implement/SKILL.md +2 -1
- package/skills/df-ps-scaffold/references/agent-mode.md +1 -1
- package/skills/df-ps-scaffold/references/agent-operations.md +1 -1
- package/skills/df-ps-scaffold/references/choosing-components.md +2 -1
- package/skills/df-ps-scaffold/references/units/endpoint.md +3 -1
- package/skills/df-ps-scaffold/references/units/port.md +2 -2
package/dist/integration.cjs
CHANGED
|
@@ -369,7 +369,8 @@ const lintChecks = [
|
|
|
369
369
|
'layers',
|
|
370
370
|
'dependencies',
|
|
371
371
|
'react',
|
|
372
|
-
'clock'
|
|
372
|
+
'clock',
|
|
373
|
+
'config'
|
|
373
374
|
];
|
|
374
375
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
375
376
|
const projectConfigSchema = external_zod_default().object({
|
|
@@ -1530,10 +1531,11 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
|
|
|
1530
1531
|
path: readonly string[];
|
|
1531
1532
|
}): OpenApiData | undefined => {
|
|
1532
1533
|
try {
|
|
1533
|
-
|
|
1534
|
-
|
|
1534
|
+
// The controller, if any, is the first folder of the path:
|
|
1535
|
+
// context-root endpoints live right in presentation/rest.
|
|
1536
|
+
const [currentBoundedContext, ...relativePath] = routeMetadata.path;
|
|
1535
1537
|
|
|
1536
|
-
if (!currentBoundedContext
|
|
1538
|
+
if (!currentBoundedContext) {
|
|
1537
1539
|
return undefined;
|
|
1538
1540
|
}
|
|
1539
1541
|
|
|
@@ -1543,7 +1545,6 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
|
|
|
1543
1545
|
currentBoundedContext,
|
|
1544
1546
|
'presentation',
|
|
1545
1547
|
'rest',
|
|
1546
|
-
controller,
|
|
1547
1548
|
...relativePath.map(pathParameterAsName),
|
|
1548
1549
|
\`\${routeMetadata.method.toUpperCase()}.ts\`
|
|
1549
1550
|
)
|
|
@@ -3199,7 +3200,7 @@ const scaffoldRequestSchema = external_zod_default().discriminatedUnion('operati
|
|
|
3199
3200
|
agent_requests_operation('endpoint', {
|
|
3200
3201
|
...common,
|
|
3201
3202
|
...agent_requests_owner,
|
|
3202
|
-
controller: agent_requests_name,
|
|
3203
|
+
controller: agent_requests_name.optional().describe('Omit for an endpoint at the context root (`/<context>`); then path is empty or starts with a :param.'),
|
|
3203
3204
|
method: external_zod_default()["enum"]([
|
|
3204
3205
|
'get',
|
|
3205
3206
|
'post',
|
|
@@ -5129,46 +5130,45 @@ export const ${names.namespace(ClassName)} = errorNamespace('${boundedContextFol
|
|
|
5129
5130
|
const namespaceFile = currentErrorFolder.file(`${namespace}.ts`);
|
|
5130
5131
|
namespaceFile.addLineIfMissing(errorClass(names.error(`${namespaceNaming.ClassName}${ClassName}`), exportedNamespace(namespaceFile, names.namespace(namespaceNaming.ClassName)), fileName), '\n\n');
|
|
5131
5132
|
};
|
|
5133
|
+
const newController = 'New controller';
|
|
5134
|
+
const withoutController = 'No controller (context root)';
|
|
5135
|
+
const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
|
|
5136
|
+
const isPathParameterName = (name)=>name.startsWith(':') || /^_.+_$/.test(name);
|
|
5137
|
+
const sharedRestFolder = (boundedContextFolder)=>boundedContextFolder.subitem([
|
|
5138
|
+
'..',
|
|
5139
|
+
'..',
|
|
5140
|
+
'presentation',
|
|
5141
|
+
'rest'
|
|
5142
|
+
]);
|
|
5132
5143
|
const scaffoldNewHandlersRestEndpoint = async (boundedContextFolder)=>{
|
|
5133
5144
|
const restPresentationFolder = boundedContextFolder.subitem([
|
|
5134
5145
|
'presentation',
|
|
5135
5146
|
'rest'
|
|
5136
5147
|
]);
|
|
5137
|
-
const controllers = restPresentationFolder.content.subfolderNames;
|
|
5138
|
-
let
|
|
5148
|
+
const controllers = restPresentationFolder.content.subfolderNames.filter((x)=>!isPathParameterName(x));
|
|
5149
|
+
let controllerChoice = await interaction_select({
|
|
5139
5150
|
key: 'controllerSelection',
|
|
5140
5151
|
message: 'Controller: ',
|
|
5141
5152
|
choices: [
|
|
5142
5153
|
...controllers,
|
|
5143
|
-
|
|
5154
|
+
newController,
|
|
5155
|
+
withoutController
|
|
5144
5156
|
]
|
|
5145
5157
|
});
|
|
5146
|
-
if (
|
|
5147
|
-
|
|
5148
|
-
|
|
5149
|
-
|
|
5150
|
-
|
|
5151
|
-
|
|
5152
|
-
|
|
5153
|
-
|
|
5154
|
-
|
|
5155
|
-
|
|
5156
|
-
|
|
5157
|
-
|
|
5158
|
-
|
|
5159
|
-
|
|
5160
|
-
'presentation',
|
|
5161
|
-
'rest'
|
|
5162
|
-
]);
|
|
5163
|
-
sharedRestFolder.file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
|
|
5164
|
-
if (!sharedRestFolder.file('index.ts').exists) sharedRestFolder.createFile('index.ts', `
|
|
5165
|
-
import * as wires from './wires'
|
|
5166
|
-
|
|
5167
|
-
const restWires = Object.values(wires)
|
|
5168
|
-
|
|
5169
|
-
export const restHandlers = restWires.map(x => x().handle)
|
|
5170
|
-
`.trim());
|
|
5171
|
-
}
|
|
5158
|
+
if (controllerChoice === newController) controllerChoice = await interaction_input({
|
|
5159
|
+
key: 'controllerName',
|
|
5160
|
+
message: 'Name: ',
|
|
5161
|
+
validate: (value)=>value.trim() ? isPathParameterName(value) || value.includes('/') ? 'A controller is one static path segment' : true : `Name is required; pick "${withoutController}" for an endpoint at the context root`
|
|
5162
|
+
});
|
|
5163
|
+
const controller = controllerChoice === withoutController ? void 0 : controllerChoice;
|
|
5164
|
+
const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
|
|
5165
|
+
if (controller && !controllers.includes(controller) && withWiring) {
|
|
5166
|
+
boundedContextFolder.subitem([
|
|
5167
|
+
'wiring',
|
|
5168
|
+
'presentation',
|
|
5169
|
+
'rest'
|
|
5170
|
+
]).file('index.ts').addLine(`export * from './${controller}'`);
|
|
5171
|
+
sharedRestFolder(boundedContextFolder).file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
|
|
5172
5172
|
}
|
|
5173
5173
|
const method = await interaction_select({
|
|
5174
5174
|
key: 'method',
|
|
@@ -5183,21 +5183,32 @@ export const restHandlers = restWires.map(x => x().handle)
|
|
|
5183
5183
|
});
|
|
5184
5184
|
const routeSegments = (await interaction_input({
|
|
5185
5185
|
key: 'path',
|
|
5186
|
-
message: 'Relative path (split by "/"):'
|
|
5186
|
+
message: 'Relative path (split by "/"):',
|
|
5187
|
+
validate: (value)=>{
|
|
5188
|
+
const [first] = value.split('/').filter((x)=>!!x);
|
|
5189
|
+
return controller || !first || first.startsWith(':') ? true : `Without a controller, the path is empty or starts with a path parameter; "${first}" is a controller`;
|
|
5190
|
+
}
|
|
5187
5191
|
})).split('/').filter((x)=>!!x);
|
|
5188
|
-
const
|
|
5189
|
-
|
|
5190
|
-
|
|
5191
|
-
|
|
5192
|
-
|
|
5193
|
-
|
|
5192
|
+
const folderSegments = [
|
|
5193
|
+
...controller ? [
|
|
5194
|
+
controller
|
|
5195
|
+
] : [],
|
|
5196
|
+
...routeSegments
|
|
5197
|
+
];
|
|
5198
|
+
const endpointFolder = restPresentationFolder.subitem(folderSegments.map(pathParameterAsName));
|
|
5199
|
+
const nameSegments = [
|
|
5200
|
+
controller ?? boundedContextFolder.name,
|
|
5201
|
+
...routeSegments
|
|
5202
|
+
];
|
|
5203
|
+
const nameBase = `${[
|
|
5204
|
+
...nameSegments.map(pathParameterAsName),
|
|
5205
|
+
method
|
|
5206
|
+
].join('-')}-endpoint`;
|
|
5194
5207
|
const endpointClassName = [
|
|
5195
|
-
|
|
5196
|
-
...routeSegments,
|
|
5208
|
+
...nameSegments,
|
|
5197
5209
|
method,
|
|
5198
5210
|
'endpoint'
|
|
5199
5211
|
].map((segment)=>segment.startsWith(':') ? pathParameterAsName(segment) : new UnknownFormatNaming(segment).ClassName).join('');
|
|
5200
|
-
const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
|
|
5201
5212
|
const endpointGenerator = findRestEndpointGenerator(boundedContextFolder.subitem([
|
|
5202
5213
|
'..',
|
|
5203
5214
|
'..',
|
|
@@ -5217,8 +5228,11 @@ export class ${endpointClassName} {
|
|
|
5217
5228
|
|
|
5218
5229
|
get handle() {
|
|
5219
5230
|
return this.endpointGenerator(this.handler.handle, {
|
|
5220
|
-
route: { method: '${method}', path: [
|
|
5221
|
-
|
|
5231
|
+
route: { method: '${method}', path: [${[
|
|
5232
|
+
boundedContextFolder.name,
|
|
5233
|
+
...folderSegments
|
|
5234
|
+
].map((x)=>`'${x}'`).join(', ')}] },
|
|
5235
|
+
tags: ['${boundedContextFolder.name}${controller ? `: ${controller}` : ''}'],
|
|
5222
5236
|
})
|
|
5223
5237
|
}
|
|
5224
5238
|
}
|
|
@@ -5228,7 +5242,9 @@ export class ${endpointClassName} {
|
|
|
5228
5242
|
'wiring',
|
|
5229
5243
|
'presentation',
|
|
5230
5244
|
'rest',
|
|
5231
|
-
controller
|
|
5245
|
+
...controller ? [
|
|
5246
|
+
controller
|
|
5247
|
+
] : []
|
|
5232
5248
|
]);
|
|
5233
5249
|
const wireNameBase = `wire-${nameBase}`;
|
|
5234
5250
|
const wireNaming = new UnknownFormatNaming(wireNameBase);
|
|
@@ -5248,6 +5264,15 @@ export const wire${endpointClassName} = wireClass(
|
|
|
5248
5264
|
)
|
|
5249
5265
|
`.trim());
|
|
5250
5266
|
wiringFolder.file('index.ts').addLineIfMissing(`export * from './${wireNaming.fileName}'`);
|
|
5267
|
+
if (!controller) sharedRestFolder(boundedContextFolder).file('wires.ts').addLineIfMissing(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${wireNaming.fileName}'`);
|
|
5268
|
+
const restHandlersFile = sharedRestFolder(boundedContextFolder).file('index.ts');
|
|
5269
|
+
if (!restHandlersFile.exists) sharedRestFolder(boundedContextFolder).createFile('index.ts', `
|
|
5270
|
+
import * as wires from './wires'
|
|
5271
|
+
|
|
5272
|
+
const restWires = Object.values(wires)
|
|
5273
|
+
|
|
5274
|
+
export const restHandlers = restWires.map(x => x().handle)
|
|
5275
|
+
`.trim());
|
|
5251
5276
|
}
|
|
5252
5277
|
};
|
|
5253
5278
|
const scaffold_new_implementation_kindTitles = {
|
|
@@ -5887,12 +5912,15 @@ const answersFor = (command, request, owner)=>{
|
|
|
5887
5912
|
if ('error' === request.operation || 'error-namespace' === request.operation) defaults.errorAction = 'error-namespace' === request.operation ? 'New namespace' : request.namespace ? `New error in namespace ${request.namespace}` : 'New error without namespace';
|
|
5888
5913
|
if ('endpoint' === request.operation) {
|
|
5889
5914
|
delete answers.controller;
|
|
5890
|
-
|
|
5891
|
-
|
|
5892
|
-
|
|
5893
|
-
|
|
5894
|
-
|
|
5895
|
-
|
|
5915
|
+
if (void 0 === request.controller) answers.controllerSelection = 'No controller (context root)';
|
|
5916
|
+
else {
|
|
5917
|
+
const existing = owner.subitem([
|
|
5918
|
+
'presentation',
|
|
5919
|
+
'rest'
|
|
5920
|
+
]).content.subfolderNames.includes(request.controller);
|
|
5921
|
+
answers.controllerSelection = existing ? request.controller : 'New controller';
|
|
5922
|
+
if (!existing) answers.controllerName = request.controller;
|
|
5923
|
+
}
|
|
5896
5924
|
}
|
|
5897
5925
|
if ('move' === request.operation) defaults.targetContext = request.context;
|
|
5898
5926
|
}
|
package/dist/lint.cjs
CHANGED
|
@@ -238,7 +238,8 @@ const lintChecks = [
|
|
|
238
238
|
'layers',
|
|
239
239
|
'dependencies',
|
|
240
240
|
'react',
|
|
241
|
-
'clock'
|
|
241
|
+
'clock',
|
|
242
|
+
'config'
|
|
242
243
|
];
|
|
243
244
|
const configFileName = 'domain-first.project-structure.config.json';
|
|
244
245
|
const projectConfigSchema = external_zod_default().object({
|
|
@@ -891,7 +892,19 @@ const wiringViolations = (projectRoot, rootFolder, rules)=>{
|
|
|
891
892
|
}
|
|
892
893
|
return violations;
|
|
893
894
|
};
|
|
894
|
-
const
|
|
895
|
+
const directReadChecks = [
|
|
896
|
+
{
|
|
897
|
+
check: 'clock',
|
|
898
|
+
pattern: /\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g,
|
|
899
|
+
rule: 'domain or application reads the current time directly (use the clock port):'
|
|
900
|
+
},
|
|
901
|
+
{
|
|
902
|
+
check: 'config',
|
|
903
|
+
pattern: /\bprocess\s*\??\.\s*env\b|\bprocess\s*\[\s*(['"`])env\1\s*\]|\bimport\.meta\.env\b/g,
|
|
904
|
+
rule: 'domain or application reads environment variables directly (use the config port):'
|
|
905
|
+
}
|
|
906
|
+
];
|
|
907
|
+
const directReadViolations = (projectRoot, rootFolder)=>{
|
|
895
908
|
const root = external_node_path_default().resolve(projectRoot, rootFolder);
|
|
896
909
|
const folders = [
|
|
897
910
|
external_node_path_default().join(root, 'shared-kernel'),
|
|
@@ -902,21 +915,21 @@ const clockViolations = (projectRoot, rootFolder)=>{
|
|
|
902
915
|
]);
|
|
903
916
|
return folders.flatMap(sourceFiles).filter((file)=>!isSpec(file)).flatMap((file)=>{
|
|
904
917
|
const source = external_node_fs_default().readFileSync(file, 'utf8');
|
|
905
|
-
return [
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
918
|
+
return directReadChecks.flatMap(({ check, pattern, rule })=>[
|
|
919
|
+
...source.matchAll(pattern)
|
|
920
|
+
].map((match)=>({
|
|
921
|
+
check,
|
|
922
|
+
rule,
|
|
923
|
+
file,
|
|
924
|
+
line: lineAt(source, match.index),
|
|
925
|
+
text: match[0]
|
|
926
|
+
})));
|
|
914
927
|
});
|
|
915
928
|
};
|
|
916
929
|
const lintProject = (projectRoot, rootFolder, { rules = defaultDependencyRules, checks = {} } = {})=>[
|
|
917
930
|
...importViolations(projectRoot, rootFolder, rules),
|
|
918
931
|
...wiringViolations(projectRoot, rootFolder, rules),
|
|
919
|
-
...
|
|
932
|
+
...directReadViolations(projectRoot, rootFolder)
|
|
920
933
|
].filter((x)=>false !== checks[x.check]);
|
|
921
934
|
const formatViolations = (violations, projectRoot)=>{
|
|
922
935
|
const groups = new Map();
|
|
@@ -935,7 +948,8 @@ const help = `Usage: df-lint [rootFolder]
|
|
|
935
948
|
|
|
936
949
|
Reports what breaks the Domain-First rules in the project:
|
|
937
950
|
bounded context isolation, layers, dependency rules (imports and wiring),
|
|
938
|
-
React modules, and reading the time
|
|
951
|
+
React modules, and reading the time or environment variables without
|
|
952
|
+
the clock and config ports.
|
|
939
953
|
rootFolder defaults to the one in domain-first.project-structure.config.json,
|
|
940
954
|
whose optional \`backend.rules\` change the dependency rules and turn checks off.
|
|
941
955
|
Exits with 1 when something is found.
|
package/dist/lint.js
CHANGED
|
@@ -6,7 +6,8 @@ const help = `Usage: df-lint [rootFolder]
|
|
|
6
6
|
|
|
7
7
|
Reports what breaks the Domain-First rules in the project:
|
|
8
8
|
bounded context isolation, layers, dependency rules (imports and wiring),
|
|
9
|
-
React modules, and reading the time
|
|
9
|
+
React modules, and reading the time or environment variables without
|
|
10
|
+
the clock and config ports.
|
|
10
11
|
rootFolder defaults to the one in domain-first.project-structure.config.json,
|
|
11
12
|
whose optional \`backend.rules\` change the dependency rules and turn checks off.
|
|
12
13
|
Exits with 1 when something is found.
|
package/dist/react.cjs
CHANGED
|
@@ -370,7 +370,8 @@ const lintChecks = [
|
|
|
370
370
|
'layers',
|
|
371
371
|
'dependencies',
|
|
372
372
|
'react',
|
|
373
|
-
'clock'
|
|
373
|
+
'clock',
|
|
374
|
+
'config'
|
|
374
375
|
];
|
|
375
376
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
376
377
|
const projectConfigSchema = external_zod_default().object({
|
|
@@ -1530,10 +1531,11 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
|
|
|
1530
1531
|
path: readonly string[];
|
|
1531
1532
|
}): OpenApiData | undefined => {
|
|
1532
1533
|
try {
|
|
1533
|
-
|
|
1534
|
-
|
|
1534
|
+
// The controller, if any, is the first folder of the path:
|
|
1535
|
+
// context-root endpoints live right in presentation/rest.
|
|
1536
|
+
const [currentBoundedContext, ...relativePath] = routeMetadata.path;
|
|
1535
1537
|
|
|
1536
|
-
if (!currentBoundedContext
|
|
1538
|
+
if (!currentBoundedContext) {
|
|
1537
1539
|
return undefined;
|
|
1538
1540
|
}
|
|
1539
1541
|
|
|
@@ -1543,7 +1545,6 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
|
|
|
1543
1545
|
currentBoundedContext,
|
|
1544
1546
|
'presentation',
|
|
1545
1547
|
'rest',
|
|
1546
|
-
controller,
|
|
1547
1548
|
...relativePath.map(pathParameterAsName),
|
|
1548
1549
|
\`\${routeMetadata.method.toUpperCase()}.ts\`
|
|
1549
1550
|
)
|
|
@@ -3199,7 +3200,7 @@ const scaffoldRequestSchema = external_zod_default().discriminatedUnion('operati
|
|
|
3199
3200
|
agent_requests_operation('endpoint', {
|
|
3200
3201
|
...common,
|
|
3201
3202
|
...agent_requests_owner,
|
|
3202
|
-
controller: agent_requests_name,
|
|
3203
|
+
controller: agent_requests_name.optional().describe('Omit for an endpoint at the context root (`/<context>`); then path is empty or starts with a :param.'),
|
|
3203
3204
|
method: external_zod_default()["enum"]([
|
|
3204
3205
|
'get',
|
|
3205
3206
|
'post',
|
|
@@ -5129,46 +5130,45 @@ export const ${names.namespace(ClassName)} = errorNamespace('${boundedContextFol
|
|
|
5129
5130
|
const namespaceFile = currentErrorFolder.file(`${namespace}.ts`);
|
|
5130
5131
|
namespaceFile.addLineIfMissing(errorClass(names.error(`${namespaceNaming.ClassName}${ClassName}`), exportedNamespace(namespaceFile, names.namespace(namespaceNaming.ClassName)), fileName), '\n\n');
|
|
5131
5132
|
};
|
|
5133
|
+
const newController = 'New controller';
|
|
5134
|
+
const withoutController = 'No controller (context root)';
|
|
5135
|
+
const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
|
|
5136
|
+
const isPathParameterName = (name)=>name.startsWith(':') || /^_.+_$/.test(name);
|
|
5137
|
+
const sharedRestFolder = (boundedContextFolder)=>boundedContextFolder.subitem([
|
|
5138
|
+
'..',
|
|
5139
|
+
'..',
|
|
5140
|
+
'presentation',
|
|
5141
|
+
'rest'
|
|
5142
|
+
]);
|
|
5132
5143
|
const scaffoldNewHandlersRestEndpoint = async (boundedContextFolder)=>{
|
|
5133
5144
|
const restPresentationFolder = boundedContextFolder.subitem([
|
|
5134
5145
|
'presentation',
|
|
5135
5146
|
'rest'
|
|
5136
5147
|
]);
|
|
5137
|
-
const controllers = restPresentationFolder.content.subfolderNames;
|
|
5138
|
-
let
|
|
5148
|
+
const controllers = restPresentationFolder.content.subfolderNames.filter((x)=>!isPathParameterName(x));
|
|
5149
|
+
let controllerChoice = await interaction_select({
|
|
5139
5150
|
key: 'controllerSelection',
|
|
5140
5151
|
message: 'Controller: ',
|
|
5141
5152
|
choices: [
|
|
5142
5153
|
...controllers,
|
|
5143
|
-
|
|
5154
|
+
newController,
|
|
5155
|
+
withoutController
|
|
5144
5156
|
]
|
|
5145
5157
|
});
|
|
5146
|
-
if (
|
|
5147
|
-
|
|
5148
|
-
|
|
5149
|
-
|
|
5150
|
-
|
|
5151
|
-
|
|
5152
|
-
|
|
5153
|
-
|
|
5154
|
-
|
|
5155
|
-
|
|
5156
|
-
|
|
5157
|
-
|
|
5158
|
-
|
|
5159
|
-
|
|
5160
|
-
'presentation',
|
|
5161
|
-
'rest'
|
|
5162
|
-
]);
|
|
5163
|
-
sharedRestFolder.file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
|
|
5164
|
-
if (!sharedRestFolder.file('index.ts').exists) sharedRestFolder.createFile('index.ts', `
|
|
5165
|
-
import * as wires from './wires'
|
|
5166
|
-
|
|
5167
|
-
const restWires = Object.values(wires)
|
|
5168
|
-
|
|
5169
|
-
export const restHandlers = restWires.map(x => x().handle)
|
|
5170
|
-
`.trim());
|
|
5171
|
-
}
|
|
5158
|
+
if (controllerChoice === newController) controllerChoice = await interaction_input({
|
|
5159
|
+
key: 'controllerName',
|
|
5160
|
+
message: 'Name: ',
|
|
5161
|
+
validate: (value)=>value.trim() ? isPathParameterName(value) || value.includes('/') ? 'A controller is one static path segment' : true : `Name is required; pick "${withoutController}" for an endpoint at the context root`
|
|
5162
|
+
});
|
|
5163
|
+
const controller = controllerChoice === withoutController ? void 0 : controllerChoice;
|
|
5164
|
+
const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
|
|
5165
|
+
if (controller && !controllers.includes(controller) && withWiring) {
|
|
5166
|
+
boundedContextFolder.subitem([
|
|
5167
|
+
'wiring',
|
|
5168
|
+
'presentation',
|
|
5169
|
+
'rest'
|
|
5170
|
+
]).file('index.ts').addLine(`export * from './${controller}'`);
|
|
5171
|
+
sharedRestFolder(boundedContextFolder).file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
|
|
5172
5172
|
}
|
|
5173
5173
|
const method = await interaction_select({
|
|
5174
5174
|
key: 'method',
|
|
@@ -5183,21 +5183,32 @@ export const restHandlers = restWires.map(x => x().handle)
|
|
|
5183
5183
|
});
|
|
5184
5184
|
const routeSegments = (await interaction_input({
|
|
5185
5185
|
key: 'path',
|
|
5186
|
-
message: 'Relative path (split by "/"):'
|
|
5186
|
+
message: 'Relative path (split by "/"):',
|
|
5187
|
+
validate: (value)=>{
|
|
5188
|
+
const [first] = value.split('/').filter((x)=>!!x);
|
|
5189
|
+
return controller || !first || first.startsWith(':') ? true : `Without a controller, the path is empty or starts with a path parameter; "${first}" is a controller`;
|
|
5190
|
+
}
|
|
5187
5191
|
})).split('/').filter((x)=>!!x);
|
|
5188
|
-
const
|
|
5189
|
-
|
|
5190
|
-
|
|
5191
|
-
|
|
5192
|
-
|
|
5193
|
-
|
|
5192
|
+
const folderSegments = [
|
|
5193
|
+
...controller ? [
|
|
5194
|
+
controller
|
|
5195
|
+
] : [],
|
|
5196
|
+
...routeSegments
|
|
5197
|
+
];
|
|
5198
|
+
const endpointFolder = restPresentationFolder.subitem(folderSegments.map(pathParameterAsName));
|
|
5199
|
+
const nameSegments = [
|
|
5200
|
+
controller ?? boundedContextFolder.name,
|
|
5201
|
+
...routeSegments
|
|
5202
|
+
];
|
|
5203
|
+
const nameBase = `${[
|
|
5204
|
+
...nameSegments.map(pathParameterAsName),
|
|
5205
|
+
method
|
|
5206
|
+
].join('-')}-endpoint`;
|
|
5194
5207
|
const endpointClassName = [
|
|
5195
|
-
|
|
5196
|
-
...routeSegments,
|
|
5208
|
+
...nameSegments,
|
|
5197
5209
|
method,
|
|
5198
5210
|
'endpoint'
|
|
5199
5211
|
].map((segment)=>segment.startsWith(':') ? pathParameterAsName(segment) : new UnknownFormatNaming(segment).ClassName).join('');
|
|
5200
|
-
const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
|
|
5201
5212
|
const endpointGenerator = findRestEndpointGenerator(boundedContextFolder.subitem([
|
|
5202
5213
|
'..',
|
|
5203
5214
|
'..',
|
|
@@ -5217,8 +5228,11 @@ export class ${endpointClassName} {
|
|
|
5217
5228
|
|
|
5218
5229
|
get handle() {
|
|
5219
5230
|
return this.endpointGenerator(this.handler.handle, {
|
|
5220
|
-
route: { method: '${method}', path: [
|
|
5221
|
-
|
|
5231
|
+
route: { method: '${method}', path: [${[
|
|
5232
|
+
boundedContextFolder.name,
|
|
5233
|
+
...folderSegments
|
|
5234
|
+
].map((x)=>`'${x}'`).join(', ')}] },
|
|
5235
|
+
tags: ['${boundedContextFolder.name}${controller ? `: ${controller}` : ''}'],
|
|
5222
5236
|
})
|
|
5223
5237
|
}
|
|
5224
5238
|
}
|
|
@@ -5228,7 +5242,9 @@ export class ${endpointClassName} {
|
|
|
5228
5242
|
'wiring',
|
|
5229
5243
|
'presentation',
|
|
5230
5244
|
'rest',
|
|
5231
|
-
controller
|
|
5245
|
+
...controller ? [
|
|
5246
|
+
controller
|
|
5247
|
+
] : []
|
|
5232
5248
|
]);
|
|
5233
5249
|
const wireNameBase = `wire-${nameBase}`;
|
|
5234
5250
|
const wireNaming = new UnknownFormatNaming(wireNameBase);
|
|
@@ -5248,6 +5264,15 @@ export const wire${endpointClassName} = wireClass(
|
|
|
5248
5264
|
)
|
|
5249
5265
|
`.trim());
|
|
5250
5266
|
wiringFolder.file('index.ts').addLineIfMissing(`export * from './${wireNaming.fileName}'`);
|
|
5267
|
+
if (!controller) sharedRestFolder(boundedContextFolder).file('wires.ts').addLineIfMissing(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${wireNaming.fileName}'`);
|
|
5268
|
+
const restHandlersFile = sharedRestFolder(boundedContextFolder).file('index.ts');
|
|
5269
|
+
if (!restHandlersFile.exists) sharedRestFolder(boundedContextFolder).createFile('index.ts', `
|
|
5270
|
+
import * as wires from './wires'
|
|
5271
|
+
|
|
5272
|
+
const restWires = Object.values(wires)
|
|
5273
|
+
|
|
5274
|
+
export const restHandlers = restWires.map(x => x().handle)
|
|
5275
|
+
`.trim());
|
|
5251
5276
|
}
|
|
5252
5277
|
};
|
|
5253
5278
|
const scaffold_new_implementation_kindTitles = {
|
|
@@ -5887,12 +5912,15 @@ const answersFor = (command, request, owner)=>{
|
|
|
5887
5912
|
if ('error' === request.operation || 'error-namespace' === request.operation) defaults.errorAction = 'error-namespace' === request.operation ? 'New namespace' : request.namespace ? `New error in namespace ${request.namespace}` : 'New error without namespace';
|
|
5888
5913
|
if ('endpoint' === request.operation) {
|
|
5889
5914
|
delete answers.controller;
|
|
5890
|
-
|
|
5891
|
-
|
|
5892
|
-
|
|
5893
|
-
|
|
5894
|
-
|
|
5895
|
-
|
|
5915
|
+
if (void 0 === request.controller) answers.controllerSelection = 'No controller (context root)';
|
|
5916
|
+
else {
|
|
5917
|
+
const existing = owner.subitem([
|
|
5918
|
+
'presentation',
|
|
5919
|
+
'rest'
|
|
5920
|
+
]).content.subfolderNames.includes(request.controller);
|
|
5921
|
+
answers.controllerSelection = existing ? request.controller : 'New controller';
|
|
5922
|
+
if (!existing) answers.controllerName = request.controller;
|
|
5923
|
+
}
|
|
5896
5924
|
}
|
|
5897
5925
|
if ('move' === request.operation) defaults.targetContext = request.context;
|
|
5898
5926
|
}
|
package/dist/upgrade-steps.d.ts
CHANGED
|
@@ -65,7 +65,7 @@ export declare const planUpgrade: (config: unknown, acceptOptional?: (step: Plan
|
|
|
65
65
|
add?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
66
66
|
remove?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
67
67
|
}>> | undefined;
|
|
68
|
-
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock", boolean>> | undefined;
|
|
68
|
+
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock" | "config", boolean>> | undefined;
|
|
69
69
|
} | undefined;
|
|
70
70
|
} | undefined;
|
|
71
71
|
frontend?: {
|
package/dist/upgrade.cjs
CHANGED
package/package.json
CHANGED
|
@@ -42,7 +42,8 @@ Run it from the project root; `rootFolder` defaults to the config's. It resolves
|
|
|
42
42
|
- imports against the layers ("Ground rules"; specs excluded);
|
|
43
43
|
- module files importing kinds the project's dependency rules don't allow (a use case importing a use case, a query importing a command, …), and wired dependencies they don't allow ("Wiring" below, `df-ps-scaffold` rule 3); an implementation importing its own contract is fine;
|
|
44
44
|
- a widget importing another widget (a widget = the nearest folder under `presentation/react/widgets/` with a `*-widget.tsx`, nested widgets included), UI-kit importing widgets, pages or contexts, shared hooks importing UI-kit, widgets, pages or contexts;
|
|
45
|
-
- `new Date()` / `Date.now()` in domain or application (use the `clock` port)
|
|
45
|
+
- `new Date()` / `Date.now()` in domain or application (use the `clock` port);
|
|
46
|
+
- `process.env` / `import.meta.env` in domain or application (use the `config` port).
|
|
46
47
|
|
|
47
48
|
It exits with 1 when anything is found. Checks turned off in the config (`backend.rules.lint`) aren't reported; don't turn checks off yourself.
|
|
48
49
|
|
|
@@ -40,7 +40,7 @@ npx df-integration --request '{"operation":"add","integrations":["storybook"]}'
|
|
|
40
40
|
- `dependencies`: implementation/class name → array of qualified module IDs. Omitted entries keep the generator's checked suggestions; `[]` explicitly selects none when that selection applies. When wiring is off or no candidates exist, omit the group; see the [dependency conditions](agent-operations.md#dependency-keys-and-system-implementations). Every supplied dependency group must apply to the operation. Different primary/test implementations have independent lists.
|
|
41
41
|
- Aggregate repositories require `withRepository: true` and an `implementation`. Without it, aggregate creation makes no repository.
|
|
42
42
|
- New implementations use a `contract` ID and, with a branched wire, an explicit `environments` array. Moves use a `module` unit ID and optional `targetContext`, `aggregate` and `name`. `wire-dependency` uses a wiring target ID in `module` plus its `dependencies` entry.
|
|
43
|
-
- Endpoints use `controller`, lowercase `method`, relative `path` and a qualified `handler` ID when a wired handler is available. A new controller is created when its name does not exist.
|
|
43
|
+
- Endpoints use `controller`, lowercase `method`, relative `path` and a qualified `handler` ID when a wired handler is available. A new controller is created when its name does not exist; omit `controller` for an endpoint at the context root (`/<context>`, `/<context>/:id`).
|
|
44
44
|
- Integration-specific fields and script conflict decisions are in the integration request schema. Conflicts require explicit decisions, e.g. `"scriptConflicts": { "storybook": "keep" }`. Configuration changes that require confirmation interactively also require their explicit request field.
|
|
45
45
|
|
|
46
46
|
## Check the result
|
|
@@ -25,7 +25,7 @@ All operations support `dryRun` and `overwrite`. Except `bounded-context`, they
|
|
|
25
25
|
| `query` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |
|
|
26
26
|
| `port` | `name`, `implementation` | `testImplementation`, `dependencies`. `cross-context` is available only with a neighboring context, never in Shared Kernel. |
|
|
27
27
|
| `implementation` | `contract`, `implementation` | For a usable branched wire, `environments` is required and nonempty; otherwise omit it. `dependencies` is available for the newly added implementation when wiring applies. |
|
|
28
|
-
| `endpoint` | `
|
|
28
|
+
| `endpoint` | `method`, `path`, optional `controller` (omit for the context root; `path` then empty or starting with `:param`) | REST package and generator must exist. With wiring and selectable handlers, provide `handler`. Without selectable handlers, omit it; the generated handler remains `never` and needs a later approved generator rerun. |
|
|
29
29
|
| `wire-dependency` | `module`, `dependencies` | `module` is a wiring target ID, not a contract/unit ID. Adds only eligible dependencies not already wired to that implementation. |
|
|
30
30
|
| `move` | `module` | `module` is a unit ID. Optional `name`, `targetContext`, `aggregate`; omitted name/context keep the existing ones. A same-owner entity/value-object keeps its aggregate by default. The target aggregate must exist; the target context must be a discovered, allowed destination for that unit kind. Illegal cross-context imports reject the move. |
|
|
31
31
|
| `delete` | `module` | `module` is a unit ID. Deletes every file of the unit and its generated references (aggregate barrel re-export, in-memory DB section). Refused with `DELETE_NOT_ALLOWED` and `details.usedBy` while other files import it; nothing changes. |
|
|
@@ -57,11 +57,12 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
57
57
|
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
58
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
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 (`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. |
|
|
60
61
|
|
|
61
62
|
## Where it goes
|
|
62
63
|
|
|
63
64
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
64
|
-
- Shared Kernel: 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 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.
|
|
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.
|
|
65
66
|
- Another context's data or behavior → an application port in the consuming context (step 9).
|
|
66
67
|
|
|
67
68
|
## Example
|
|
@@ -4,7 +4,7 @@ When: an HTTP entry point (`../choosing-components.md`, step 2). It exposes a qu
|
|
|
4
4
|
|
|
5
5
|
## Generate (context only)
|
|
6
6
|
|
|
7
|
-
Prompts: controller (select: 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).
|
|
7
|
+
Prompts: controller (select: existing | `New controller` → name | `No controller (context root)`) → 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
9
|
`… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
|
|
10
10
|
`… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
|
|
@@ -15,6 +15,8 @@ For `sales`, `orders`, `get`, `recent`:
|
|
|
15
15
|
- {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
|
|
16
16
|
- {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)
|
|
17
17
|
|
|
18
|
+
- No controller, context `social-networks`, `get`, empty path: `<C>/presentation/rest/GET.ts`, `class SocialNetworksGetEndpoint`, route `['social-networks']`, tag `'social-networks'`; {wire} `<C>/wiring/presentation/rest/wire-social-networks-get-endpoint.ts`, a line in `<C>/wiring/presentation/rest/index.ts` and one in `<rootFolder>/presentation/rest/wires.ts`. Use it for collection endpoints of the context (`GET /social-networks`, `POST /social-networks`, `GET /social-networks/:id`) instead of a `list` controller or `/social-networks/social-networks`. Its path is empty or starts with `:param`: a static first segment is a controller.
|
|
19
|
+
|
|
18
20
|
The same controller, path, and method replace the existing endpoint (after `Overwrite them?`). Generate the exposed handler first, so `Handler:` lists it. If `handler: never` is left, re-run the endpoint generator once the handler exists, as an approved overwrite; don't replace it by hand.
|
|
19
21
|
|
|
20
22
|
## Implement
|