forgecraft-mcp 1.1.0 → 1.2.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/dist/tools/scaffold-spec-stubs.d.ts +43 -0
- package/dist/tools/scaffold-spec-stubs.d.ts.map +1 -1
- package/dist/tools/scaffold-spec-stubs.js +142 -0
- package/dist/tools/scaffold-spec-stubs.js.map +1 -1
- package/dist/tools/scaffold-writer.d.ts.map +1 -1
- package/dist/tools/scaffold-writer.js +11 -3
- package/dist/tools/scaffold-writer.js.map +1 -1
- package/package.json +1 -1
- package/templates/universal/instructions.yaml +19 -8
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
* scaffold-spec-stubs: Spec stub writers for scaffold_project.
|
|
3
3
|
*
|
|
4
4
|
* Manages UNFILLED stub documents that are detectable by check_cascade.
|
|
5
|
+
* Diagram stubs are structured (real Mermaid syntax with placeholder labels)
|
|
6
|
+
* so they function as grammar production rules from day one, not empty files.
|
|
5
7
|
*/
|
|
6
8
|
export declare const USE_CASES_STUB = "<!-- UNFILLED: Use Cases -->\n# Use Cases\n\n## UC-01: [Name]\n**Actor**: <!-- FILL: who? -->\n**Precondition**: <!-- FILL: what must be true before? -->\n**Steps**: <!-- FILL: numbered steps -->\n**Success**: <!-- FILL: what changed? -->\n\n## UC-02: [Name]\n<!-- FILL -->\n\n## UC-03: [Name]\n<!-- FILL -->\n";
|
|
7
9
|
/**
|
|
@@ -11,6 +13,47 @@ export declare const USE_CASES_STUB = "<!-- UNFILLED: Use Cases -->\n# Use Cases
|
|
|
11
13
|
* @returns Stub content with UNFILLED markers
|
|
12
14
|
*/
|
|
13
15
|
export declare function buildC4ContextStub(projectName: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* Build the UNFILLED stub content for a sequence diagram.
|
|
18
|
+
*
|
|
19
|
+
* Emits a structured Mermaid sequenceDiagram with participant declarations and
|
|
20
|
+
* labelled message arrows — a real grammar production rule, not an empty file.
|
|
21
|
+
*
|
|
22
|
+
* @param feature - Human-readable feature name (e.g. "User Authentication")
|
|
23
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
24
|
+
*/
|
|
25
|
+
export declare function buildSequenceDiagramStub(feature: string): string;
|
|
26
|
+
/**
|
|
27
|
+
* Build the UNFILLED stub content for a state machine diagram.
|
|
28
|
+
*
|
|
29
|
+
* Emits a stateDiagram-v2 with an initial transition, named states, transitions
|
|
30
|
+
* between them, and terminal states — a grammar that directly generates state
|
|
31
|
+
* transition test cases.
|
|
32
|
+
*
|
|
33
|
+
* @param entityName - Domain entity whose lifecycle is modelled (e.g. "Order")
|
|
34
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
35
|
+
*/
|
|
36
|
+
export declare function buildStateMachineDiagramStub(entityName: string): string;
|
|
37
|
+
/**
|
|
38
|
+
* Build the UNFILLED stub content for a user flow / flowchart diagram.
|
|
39
|
+
*
|
|
40
|
+
* Emits a flowchart TD with Start/End rounded nodes, a decision diamond, and
|
|
41
|
+
* labelled edges — the script for E2E tests and user documentation in one artifact.
|
|
42
|
+
*
|
|
43
|
+
* @param ucName - Use case name (e.g. "UC-01: Register User")
|
|
44
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
45
|
+
*/
|
|
46
|
+
export declare function buildFlowDiagramStub(ucName: string): string;
|
|
47
|
+
/**
|
|
48
|
+
* Build the UNFILLED stub content for a C4 Container diagram.
|
|
49
|
+
*
|
|
50
|
+
* Emits Container declarations and Rel statements for a multi-container system —
|
|
51
|
+
* the topology layer that C4 Context does not capture.
|
|
52
|
+
*
|
|
53
|
+
* @param projectName - Human-readable project name for the diagram title
|
|
54
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
55
|
+
*/
|
|
56
|
+
export declare function buildC4ContainerStub(projectName: string): string;
|
|
14
57
|
/**
|
|
15
58
|
* Write a spec stub file. Only creates when the file does not exist, or when
|
|
16
59
|
* force=true AND the existing file still contains the UNFILLED marker.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-spec-stubs.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"scaffold-spec-stubs.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,eAAO,MAAM,cAAc,2TAc1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA0BvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAyB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAoBhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,EAAE,EACtB,YAAY,EAAE,MAAM,EAAE,GACrB,IAAI,CAgBN"}
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
* scaffold-spec-stubs: Spec stub writers for scaffold_project.
|
|
3
3
|
*
|
|
4
4
|
* Manages UNFILLED stub documents that are detectable by check_cascade.
|
|
5
|
+
* Diagram stubs are structured (real Mermaid syntax with placeholder labels)
|
|
6
|
+
* so they function as grammar production rules from day one, not empty files.
|
|
5
7
|
*/
|
|
6
8
|
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
|
|
7
9
|
import { dirname } from "node:path";
|
|
@@ -39,6 +41,146 @@ C4Context
|
|
|
39
41
|
\`\`\`
|
|
40
42
|
`;
|
|
41
43
|
}
|
|
44
|
+
/**
|
|
45
|
+
* Build the UNFILLED stub content for a sequence diagram.
|
|
46
|
+
*
|
|
47
|
+
* Emits a structured Mermaid sequenceDiagram with participant declarations and
|
|
48
|
+
* labelled message arrows — a real grammar production rule, not an empty file.
|
|
49
|
+
*
|
|
50
|
+
* @param feature - Human-readable feature name (e.g. "User Authentication")
|
|
51
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
52
|
+
*/
|
|
53
|
+
export function buildSequenceDiagramStub(feature) {
|
|
54
|
+
return `<!-- UNFILLED: Sequence Diagram — ${feature} -->
|
|
55
|
+
<!-- Replace participant labels and messages with real actors and contracts -->
|
|
56
|
+
# Sequence Diagram: ${feature}
|
|
57
|
+
|
|
58
|
+
\`\`\`mermaid
|
|
59
|
+
sequenceDiagram
|
|
60
|
+
participant Client as <!-- FILL: initiating actor, e.g. Browser / CLI / Service -->
|
|
61
|
+
participant API as <!-- FILL: entry-point service, e.g. API Gateway -->
|
|
62
|
+
participant Service as <!-- FILL: domain service, e.g. AuthService -->
|
|
63
|
+
participant Store as <!-- FILL: persistence layer, e.g. Database -->
|
|
64
|
+
|
|
65
|
+
Note over Client,Store: <!-- FILL: describe the primary flow in one sentence -->
|
|
66
|
+
|
|
67
|
+
Client->>API: <!-- FILL: request, e.g. POST /login {credentials} -->
|
|
68
|
+
API->>Service: <!-- FILL: delegate, e.g. authenticate(credentials) -->
|
|
69
|
+
Service->>Store: <!-- FILL: query, e.g. findUserByEmail(email) -->
|
|
70
|
+
Store-->>Service: <!-- FILL: result, e.g. User | null -->
|
|
71
|
+
|
|
72
|
+
alt <!-- FILL: failure case, e.g. User not found or wrong password -->
|
|
73
|
+
Service-->>API: <!-- FILL: error response, e.g. AuthError -->
|
|
74
|
+
API-->>Client: <!-- FILL: HTTP error, e.g. 401 Unauthorized -->
|
|
75
|
+
else <!-- FILL: success case -->
|
|
76
|
+
Service-->>API: <!-- FILL: success result, e.g. JWT token -->
|
|
77
|
+
API-->>Client: <!-- FILL: HTTP success, e.g. 200 OK {token} -->
|
|
78
|
+
end
|
|
79
|
+
\`\`\`
|
|
80
|
+
`;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Build the UNFILLED stub content for a state machine diagram.
|
|
84
|
+
*
|
|
85
|
+
* Emits a stateDiagram-v2 with an initial transition, named states, transitions
|
|
86
|
+
* between them, and terminal states — a grammar that directly generates state
|
|
87
|
+
* transition test cases.
|
|
88
|
+
*
|
|
89
|
+
* @param entityName - Domain entity whose lifecycle is modelled (e.g. "Order")
|
|
90
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
91
|
+
*/
|
|
92
|
+
export function buildStateMachineDiagramStub(entityName) {
|
|
93
|
+
return `<!-- UNFILLED: State Machine — ${entityName} -->
|
|
94
|
+
<!-- Replace state names (Draft, Pending, Active, etc.) and transition labels -->
|
|
95
|
+
<!-- with the actual lifecycle states of your domain entity. -->
|
|
96
|
+
# State Machine: ${entityName}
|
|
97
|
+
|
|
98
|
+
\`\`\`mermaid
|
|
99
|
+
stateDiagram-v2
|
|
100
|
+
[*] --> Draft
|
|
101
|
+
|
|
102
|
+
Draft --> Pending: submit()
|
|
103
|
+
Pending --> Active: approve()
|
|
104
|
+
Pending --> Rejected: reject()
|
|
105
|
+
Active --> Completed: complete()
|
|
106
|
+
Active --> Cancelled: cancel()
|
|
107
|
+
|
|
108
|
+
Completed --> [*]
|
|
109
|
+
Rejected --> [*]
|
|
110
|
+
Cancelled --> [*]
|
|
111
|
+
|
|
112
|
+
note right of Active
|
|
113
|
+
FILL: add invariant or constraint
|
|
114
|
+
e.g. "requires valid payment method"
|
|
115
|
+
end note
|
|
116
|
+
\`\`\`
|
|
117
|
+
`;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Build the UNFILLED stub content for a user flow / flowchart diagram.
|
|
121
|
+
*
|
|
122
|
+
* Emits a flowchart TD with Start/End rounded nodes, a decision diamond, and
|
|
123
|
+
* labelled edges — the script for E2E tests and user documentation in one artifact.
|
|
124
|
+
*
|
|
125
|
+
* @param ucName - Use case name (e.g. "UC-01: Register User")
|
|
126
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
127
|
+
*/
|
|
128
|
+
export function buildFlowDiagramStub(ucName) {
|
|
129
|
+
return `<!-- UNFILLED: Flow Diagram — ${ucName} -->
|
|
130
|
+
<!-- Replace node labels and edge conditions with real user journey steps -->
|
|
131
|
+
# Flow: ${ucName}
|
|
132
|
+
|
|
133
|
+
\`\`\`mermaid
|
|
134
|
+
flowchart TD
|
|
135
|
+
Start([<!-- FILL: trigger, e.g. User opens registration page -->])
|
|
136
|
+
|
|
137
|
+
Start --> Input[<!-- FILL: first action, e.g. Fill in name, email, password -->]
|
|
138
|
+
Input --> Validate{<!-- FILL: validation check, e.g. All fields valid? -->}
|
|
139
|
+
|
|
140
|
+
Validate -->|<!-- FILL: failure label, e.g. Invalid -->| Error[<!-- FILL: error action, e.g. Show validation errors -->]
|
|
141
|
+
Error --> Input
|
|
142
|
+
|
|
143
|
+
Validate -->|<!-- FILL: success label, e.g. Valid -->| Process[<!-- FILL: main action, e.g. Create account -->]
|
|
144
|
+
Process --> Check{<!-- FILL: guard check, e.g. Email already exists? -->}
|
|
145
|
+
|
|
146
|
+
Check -->|<!-- FILL: conflict label, e.g. Yes -->| Conflict[<!-- FILL: conflict action, e.g. Show duplicate email error -->]
|
|
147
|
+
Conflict --> End([<!-- FILL: exit label, e.g. User corrects email -->])
|
|
148
|
+
|
|
149
|
+
Check -->|<!-- FILL: proceed label, e.g. No -->| Success[<!-- FILL: success action, e.g. Send confirmation email -->]
|
|
150
|
+
Success --> End
|
|
151
|
+
\`\`\`
|
|
152
|
+
`;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Build the UNFILLED stub content for a C4 Container diagram.
|
|
156
|
+
*
|
|
157
|
+
* Emits Container declarations and Rel statements for a multi-container system —
|
|
158
|
+
* the topology layer that C4 Context does not capture.
|
|
159
|
+
*
|
|
160
|
+
* @param projectName - Human-readable project name for the diagram title
|
|
161
|
+
* @returns Stub content with UNFILLED markers and structural Mermaid syntax
|
|
162
|
+
*/
|
|
163
|
+
export function buildC4ContainerStub(projectName) {
|
|
164
|
+
return `<!-- UNFILLED: C4 Container Diagram -->
|
|
165
|
+
<!-- Replace container labels, technology fields, and relations with your stack -->
|
|
166
|
+
# Container Diagram — ${projectName}
|
|
167
|
+
|
|
168
|
+
\`\`\`mermaid
|
|
169
|
+
C4Container
|
|
170
|
+
title Container Diagram: ${projectName}
|
|
171
|
+
|
|
172
|
+
Person(user, "<!-- FILL: actor name -->", "<!-- FILL: actor description -->")
|
|
173
|
+
|
|
174
|
+
Container(web, "<!-- FILL: frontend name, e.g. Web Application -->", "<!-- FILL: technology, e.g. React -->", "<!-- FILL: responsibility -->")
|
|
175
|
+
Container(api, "<!-- FILL: backend name, e.g. API Server -->", "<!-- FILL: technology, e.g. Node.js / Express -->", "<!-- FILL: responsibility -->")
|
|
176
|
+
Container(db, "<!-- FILL: database name, e.g. Primary Database -->", "<!-- FILL: technology, e.g. PostgreSQL -->", "<!-- FILL: responsibility -->")
|
|
177
|
+
|
|
178
|
+
Rel(user, web, "<!-- FILL: interaction, e.g. Uses -->", "<!-- FILL: protocol, e.g. HTTPS -->")
|
|
179
|
+
Rel(web, api, "<!-- FILL: call, e.g. API calls -->", "<!-- FILL: protocol, e.g. REST / JSON -->")
|
|
180
|
+
Rel(api, db, "<!-- FILL: query, e.g. Reads and writes -->", "<!-- FILL: protocol, e.g. SQL -->")
|
|
181
|
+
\`\`\`
|
|
182
|
+
`;
|
|
183
|
+
}
|
|
42
184
|
/**
|
|
43
185
|
* Write a spec stub file. Only creates when the file does not exist, or when
|
|
44
186
|
* force=true AND the existing file still contains the UNFILLED marker.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-spec-stubs.js","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"scaffold-spec-stubs.js","sourceRoot":"","sources":["../../src/tools/scaffold-spec-stubs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;CAc7B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO;;;;;0BAKiB,WAAW;;oBAEjB,WAAW;;;CAG9B,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,qCAAqC,OAAO;;sBAE/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CAwB5B,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAAkB;IAC7D,OAAO,kCAAkC,UAAU;;;mBAGlC,UAAU;;;;;;;;;;;;;;;;;;;;;CAqB5B,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,iCAAiC,MAAM;;UAEtC,MAAM;;;;;;;;;;;;;;;;;;;;;CAqBf,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO;;wBAEe,WAAW;;;;+BAIJ,WAAW;;;;;;;;;;;;CAYzC,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAoB,EACpB,QAAgB,EAChB,OAAe,EACf,KAAc,EACd,YAAsB,EACtB,YAAsB;IAEtB,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAElD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAChD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-writer.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;
|
|
1
|
+
{"version":3,"file":"scaffold-writer.d.ts","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAoBzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EAC7C,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,kBAAkB,EAAE,kBAAkB,EACtC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAClC,mBAAmB,CAoOrB"}
|
|
@@ -12,7 +12,7 @@ import { writeFileIfMissing } from "../shared/filesystem.js";
|
|
|
12
12
|
import { ensureGateDirs } from "../shared/project-gates.js";
|
|
13
13
|
import { resolveTemplatePlaceholders } from "../shared/template-resolver.js";
|
|
14
14
|
import { PROJECT_SPECIFIC_TEMPLATE, EXCEPTIONS_TEMPLATE, PROJECT_GATES_TEMPLATE, renderAdrsReadme, renderGitignore, renderSmokeTestsReadme, renderLoadTestsReadme, } from "./scaffold-templates.js";
|
|
15
|
-
import { buildC4ContextStub, USE_CASES_STUB, writeSpecStub } from "./scaffold-spec-stubs.js";
|
|
15
|
+
import { buildC4ContextStub, buildC4ContainerStub, buildSequenceDiagramStub, buildStateMachineDiagramStub, buildFlowDiagramStub, USE_CASES_STUB, writeSpecStub, } from "./scaffold-spec-stubs.js";
|
|
16
16
|
/**
|
|
17
17
|
* Write all scaffold files for a project.
|
|
18
18
|
*
|
|
@@ -64,7 +64,9 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
64
64
|
? join(input.project_dir, targetConfig.directory, targetConfig.filename)
|
|
65
65
|
: join(input.project_dir, targetConfig.filename);
|
|
66
66
|
mkdirSync(dirname(outputPath), { recursive: true });
|
|
67
|
-
const relativePath = targetConfig.directory
|
|
67
|
+
const relativePath = targetConfig.directory
|
|
68
|
+
? `${targetConfig.directory}/${targetConfig.filename}`
|
|
69
|
+
: targetConfig.filename;
|
|
68
70
|
trackWrite(relativePath, outputPath, resolveTemplatePlaceholders(content, placeholderContext));
|
|
69
71
|
}
|
|
70
72
|
}
|
|
@@ -73,6 +75,10 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
73
75
|
trackWrite("docs/PRD.md", join(input.project_dir, "docs", "PRD.md"), prdContent);
|
|
74
76
|
trackWrite("docs/TechSpec.md", join(input.project_dir, "docs", "TechSpec.md"), techSpecContent);
|
|
75
77
|
writeSpecStub("docs/diagrams/c4-context.md", join(input.project_dir, "docs", "diagrams", "c4-context.md"), buildC4ContextStub(input.project_name), input.force, filesCreated, filesSkipped);
|
|
78
|
+
writeSpecStub("docs/diagrams/c4-container.md", join(input.project_dir, "docs", "diagrams", "c4-container.md"), buildC4ContainerStub(input.project_name), input.force, filesCreated, filesSkipped);
|
|
79
|
+
writeSpecStub("docs/diagrams/sequence-primary.md", join(input.project_dir, "docs", "diagrams", "sequence-primary.md"), buildSequenceDiagramStub("Primary Flow"), input.force, filesCreated, filesSkipped);
|
|
80
|
+
writeSpecStub("docs/diagrams/state-primary.md", join(input.project_dir, "docs", "diagrams", "state-primary.md"), buildStateMachineDiagramStub("Primary Entity"), input.force, filesCreated, filesSkipped);
|
|
81
|
+
writeSpecStub("docs/diagrams/flow-primary.md", join(input.project_dir, "docs", "diagrams", "flow-primary.md"), buildFlowDiagramStub("UC-01: Primary Use Case"), input.force, filesCreated, filesSkipped);
|
|
76
82
|
writeSpecStub("docs/use-cases.md", join(input.project_dir, "docs", "use-cases.md"), USE_CASES_STUB, input.force, filesCreated, filesSkipped);
|
|
77
83
|
const adrsDir = join(input.project_dir, "docs", "adrs");
|
|
78
84
|
mkdirSync(adrsDir, { recursive: true });
|
|
@@ -86,7 +92,9 @@ export function writeScaffoldFiles(input, composed, context, statusMdContent, pr
|
|
|
86
92
|
try {
|
|
87
93
|
chmodSync(hookPath, 0o755);
|
|
88
94
|
}
|
|
89
|
-
catch {
|
|
95
|
+
catch {
|
|
96
|
+
/* chmod may fail on Windows */
|
|
97
|
+
}
|
|
90
98
|
}
|
|
91
99
|
if (composed.skills.length > 0) {
|
|
92
100
|
const commandsDir = join(input.project_dir, ".claude", "commands");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scaffold-writer.js","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAE7E,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,
|
|
1
|
+
{"version":3,"file":"scaffold-writer.js","sourceRoot":"","sources":["../../src/tools/scaffold-writer.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forgecraft-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"mcpName": "io.github.jghiringhelli/forgecraft",
|
|
5
5
|
"description": "CLI + MCP sentinel for engineering standards — SOLID, testing, architecture, CI/CD — auto-tailored to your stack. Minimal MCP footprint (~200 tokens) via CLI-first design.",
|
|
6
6
|
"type": "module",
|
|
@@ -891,10 +891,14 @@ blocks:
|
|
|
891
891
|
Update the following in order — skip any that do not exist in this project:
|
|
892
892
|
1. **spec.md** — update the relevant feature section (APIs, behavior, contract changes)
|
|
893
893
|
2. **docs/adrs/** — add an ADR if a new architectural decision was made
|
|
894
|
-
3. **docs/diagrams/c4-*.md** — update
|
|
895
|
-
or external dependency was added
|
|
896
|
-
|
|
897
|
-
|
|
894
|
+
3. **docs/diagrams/c4-*.md** — update `c4-context.md` or `c4-container.md` if a new
|
|
895
|
+
module, container, or external dependency was added. Diagrams must be written to disk
|
|
896
|
+
as fenced Mermaid blocks — updating prose that references a diagram is not an update.
|
|
897
|
+
4. **docs/diagrams/sequence-*.md / state-*.md / flow-*.md** — update or create the
|
|
898
|
+
relevant diagram file for the changed surface. Sequence diagrams must name real
|
|
899
|
+
participants; state diagrams must name real states and transitions; flow diagrams must
|
|
900
|
+
have entry/exit nodes and decision diamonds. A file containing only `<!-- UNFILLED -->`
|
|
901
|
+
markers is a specification gap, not a completed diagram.
|
|
898
902
|
5. **docs/TechSpec.md** — update module list, API reference, or technology choice sections
|
|
899
903
|
6. **docs/use-cases.md** — update or add use cases if new actor interactions were introduced
|
|
900
904
|
7. **Status.md** — always update: what changed, current state, next steps
|
|
@@ -1274,10 +1278,10 @@ blocks:
|
|
|
1274
1278
|
|---|---|---|
|
|
1275
1279
|
| **Architectural constitution** (`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.github/copilot-instructions.md`) | Defines what is and is not a valid sentence in this system. Governs every AI interaction. Agent-agnostic concept; filename is agent-specific. | Core |
|
|
1276
1280
|
| **Architecture Decision Records (ADRs)** | Documents why the grammar evolved. Prevents the AI from "correcting" intentional decisions that appear suboptimal without context. | Core |
|
|
1277
|
-
| **C4 diagrams / structural diagrams** (PlantUML, Mermaid) | The parsed structural representation: system context, container topology, component composition. Static structure at a glance for any agent entering the codebase. | Recommended |
|
|
1278
|
-
| **Sequence diagrams** | Fix the inter-component protocol: which call, in which order, with which contracts. A sequence diagram specifying that auth precedes data fetch is an unambiguous ordering constraint. The AI has two valid sentences: the one matching the diagram, and deviations from it. | Recommended |
|
|
1279
|
-
| **State machine diagrams** | Enumerate every valid state and every valid transition. Directly generate state transition test cases and user-facing modal behavior documentation. | When system has states |
|
|
1280
|
-
| **User flow diagrams** | Define the expected journey from entry to outcome. Simultaneously the script for every E2E test in that flow and the user journey narrative for the manual. | Recommended |
|
|
1281
|
+
| **C4 diagrams / structural diagrams** (PlantUML, Mermaid) | The parsed structural representation: system context, container topology, component composition. Static structure at a glance for any agent entering the codebase. **Emit as files in P1** — `docs/diagrams/c4-context.md` and `docs/diagrams/c4-container.md`. A diagram referenced in prose but not written to disk provides zero structural constraint. | Recommended |
|
|
1282
|
+
| **Sequence diagrams** | Fix the inter-component protocol: which call, in which order, with which contracts. A sequence diagram specifying that auth precedes data fetch is an unambiguous ordering constraint. The AI has two valid sentences: the one matching the diagram, and deviations from it. **Emit as `docs/diagrams/sequence-[feature].md` in P1** with real `participant` declarations and message arrows — not an empty file. | Recommended |
|
|
1283
|
+
| **State machine diagrams** | Enumerate every valid state and every valid transition. Directly generate state transition test cases and user-facing modal behavior documentation. **Emit as `docs/diagrams/state-[entity].md` in P1** with real `stateDiagram-v2` states and transitions — these become the source of truth for state transition tests. | When system has states |
|
|
1284
|
+
| **User flow diagrams** | Define the expected journey from entry to outcome. Simultaneously the script for every E2E test in that flow and the user journey narrative for the manual. **Emit as `docs/diagrams/flow-[usecase].md` in P1** with real `flowchart` Start/End nodes and decision diamonds. | Recommended |
|
|
1281
1285
|
| **Use cases** | Single, precise descriptions of an interaction. One use case seeds three artifacts: implementation contract, acceptance test, user documentation. See `use-case-triple-derivation`. | Recommended |
|
|
1282
1286
|
| **Schema definitions** (DB, API, events) | The vocabulary of the system with constraints formally stated. Types, relations, validation rules, value ranges. | Core |
|
|
1283
1287
|
| **Living documentation** (derived) | OpenAPI from decorators/schemas; TypeDoc/JSDoc auto-published; Storybook from component specs; README sections from centralized specs. Documentation maintained separately from code drifts — documentation derived from the same artifacts cannot be wrong in a way the code is right. | Recommended |
|
|
@@ -1289,6 +1293,13 @@ blocks:
|
|
|
1289
1293
|
| **Status.md** | Session bridge: current implementation state, what was completed, where the session stopped, what was tried. The Auditable property requires both that the record exists and that the next session begins by reading it. | Core |
|
|
1290
1294
|
| **MCP tools and environment tooling** | The tools available to the agent define what operations are possible. Bounded tool access is bounded agency. Specification governs not just code but the system that can act. | Optional |
|
|
1291
1295
|
|
|
1296
|
+
> **Emit, Don't Reference.** Every diagram type above that is marked "Recommended" or
|
|
1297
|
+
> higher must be written as a file on disk with real, parseable content. A spec that
|
|
1298
|
+
> says "a sequence diagram should be created later" is not a grammar production rule — it
|
|
1299
|
+
> is a forward reference. Forward references do not constrain the AI. Only emitted files
|
|
1300
|
+
> do. If a diagram file exists but still contains `<!-- UNFILLED -->`, it is a known gap.
|
|
1301
|
+
> Known gaps must be on the cascade backlog; they are not acceptable as a final state.
|
|
1302
|
+
|
|
1292
1303
|
### The Six Properties (self-test)
|
|
1293
1304
|
A generative specification satisfies all six. Use as an inspection checklist:
|
|
1294
1305
|
- **Self-describing**: Does the system explain its own architecture, decisions, and conventions from its own artifacts?
|