@makerkit/prd 0.0.0-stage → 0.0.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/.turbo/turbo-build.log +46 -0
- package/.turbo/turbo-test.log +21 -0
- package/.turbo/turbo-typecheck.log +1 -0
- package/README.md +64 -2
- package/dist/LICENSE +21 -0
- package/dist/README.md +65 -0
- package/dist/index.d.ts +227 -0
- package/dist/index.js +1897 -0
- package/dist/index.mjs +1791 -0
- package/dist/mcp.d.ts +9 -0
- package/dist/mcp.js +532 -0
- package/dist/mcp.mjs +531 -0
- package/dist/node.d.ts +19 -0
- package/dist/node.js +94 -0
- package/dist/node.mjs +92 -0
- package/dist/package.json +49 -0
- package/dist/prd.service-DSBp8sMl.d.ts +2327 -0
- package/dist/prompts-Bber0S1Z.mjs +778 -0
- package/dist/prompts-CIX8IeAx.js +1233 -0
- package/package.json +66 -4
- package/src/__tests__/agent-workflow.test.ts +377 -0
- package/src/__tests__/attachments.test.ts +475 -0
- package/src/__tests__/node.test.ts +141 -0
- package/src/__tests__/plan-check.test.ts +229 -0
- package/src/__tests__/planning.test.ts +1059 -0
- package/src/__tests__/prd-operations.test.ts +423 -0
- package/src/__tests__/prd.service.test.ts +477 -0
- package/src/__tests__/prd.tool.test.ts +282 -0
- package/src/__tests__/templates.test.ts +141 -0
- package/src/applicability.ts +73 -0
- package/src/attachment-paths.ts +78 -0
- package/src/attachments.ts +160 -0
- package/src/edge-cases.ts +52 -0
- package/src/index.ts +35 -0
- package/src/markdown.ts +268 -0
- package/src/mcp/index.ts +839 -0
- package/src/mcp/tool-response.ts +85 -0
- package/src/node.ts +146 -0
- package/src/open-questions.ts +93 -0
- package/src/plan-check.ts +282 -0
- package/src/planning-operations.ts +429 -0
- package/src/prd-operations.ts +690 -0
- package/src/prd.service.ts +1051 -0
- package/src/prompts.ts +110 -0
- package/src/safe-file-name.ts +42 -0
- package/src/schema.ts +976 -0
- package/src/templates.ts +173 -0
- package/src/testing/fake-mcp-server.ts +81 -0
- package/src/types.ts +333 -0
- package/tsconfig.json +23 -0
- package/tsconfig.lib.json +8 -0
- package/tsconfig.spec.json +7 -0
- package/tsdown.config.mts +11 -0
- package/vitest.config.mts +8 -0
|
@@ -0,0 +1,1051 @@
|
|
|
1
|
+
import { attachmentsFolder, normalizeAttachments } from './attachment-paths';
|
|
2
|
+
import { normalizeNotApplicable, setNotApplicable } from './applicability';
|
|
3
|
+
import { normalizeEdgeCases } from './edge-cases';
|
|
4
|
+
import { normalizeOpenQuestions } from './open-questions';
|
|
5
|
+
import { addAttachment, removeAttachment, updateAttachment } from './attachments';
|
|
6
|
+
import { formatPrdMarkdown } from './markdown';
|
|
7
|
+
import { checkPlan } from './plan-check';
|
|
8
|
+
import {
|
|
9
|
+
addDecision,
|
|
10
|
+
addGlossaryTerm,
|
|
11
|
+
deletePhase,
|
|
12
|
+
reorderPhases,
|
|
13
|
+
decideEdgeCase,
|
|
14
|
+
resolveOpenQuestion,
|
|
15
|
+
updatePhase,
|
|
16
|
+
updatePrdSection,
|
|
17
|
+
} from './planning-operations';
|
|
18
|
+
import {
|
|
19
|
+
appendChangeLog,
|
|
20
|
+
appendStoryLog,
|
|
21
|
+
assertCanEnterStatus,
|
|
22
|
+
buildStoryContext,
|
|
23
|
+
pickNextStory,
|
|
24
|
+
assignStoryToPhase,
|
|
25
|
+
createPhase,
|
|
26
|
+
deleteStory,
|
|
27
|
+
findStory,
|
|
28
|
+
incompleteDependencies,
|
|
29
|
+
recomputeProgress,
|
|
30
|
+
nextStoryId,
|
|
31
|
+
renderUserStory,
|
|
32
|
+
updateStory,
|
|
33
|
+
validateAttachmentIds,
|
|
34
|
+
validateDependencies,
|
|
35
|
+
} from './prd-operations';
|
|
36
|
+
import { implementStoryPrompt } from './prompts';
|
|
37
|
+
import { assertSafeFileName, assertSafeRelativePath } from './safe-file-name';
|
|
38
|
+
import type {
|
|
39
|
+
AddUserStoryInput,
|
|
40
|
+
AddUserStoryOutput,
|
|
41
|
+
CreatePrdInput,
|
|
42
|
+
CreatePrdOutput,
|
|
43
|
+
DeletePrdInput,
|
|
44
|
+
DeletePrdOutput,
|
|
45
|
+
ExportPrdMarkdownInput,
|
|
46
|
+
ExportPrdMarkdownOutput,
|
|
47
|
+
GetImplementationPromptsOutput,
|
|
48
|
+
GetImprovementSuggestionsOutput,
|
|
49
|
+
GetPrdInput,
|
|
50
|
+
GetPrdOutput,
|
|
51
|
+
GetProjectStatusOutput,
|
|
52
|
+
ListPrdsOutput,
|
|
53
|
+
PrdSummary,
|
|
54
|
+
UpdateStoryStatusInput,
|
|
55
|
+
UpdateStoryStatusOutput,
|
|
56
|
+
UpdateUserStoryInput,
|
|
57
|
+
UpdateUserStoryOutput,
|
|
58
|
+
DeleteUserStoryInput,
|
|
59
|
+
DeleteUserStoryOutput,
|
|
60
|
+
CreateCustomPhaseInput,
|
|
61
|
+
CreateCustomPhaseOutput,
|
|
62
|
+
AssignStoryToPhaseInput,
|
|
63
|
+
AssignStoryToPhaseOutput,
|
|
64
|
+
AddStoryLogInput,
|
|
65
|
+
AddStoryLogOutput,
|
|
66
|
+
GetNextStoryOutput,
|
|
67
|
+
GetStoryInput,
|
|
68
|
+
GetStoryOutput,
|
|
69
|
+
AddAttachmentInput,
|
|
70
|
+
AddAttachmentOutput,
|
|
71
|
+
RemoveAttachmentInput,
|
|
72
|
+
RemoveAttachmentOutput,
|
|
73
|
+
UpdateAttachmentInput,
|
|
74
|
+
UpdateAttachmentOutput,
|
|
75
|
+
CheckPlanOutput,
|
|
76
|
+
ListTemplatesOutput,
|
|
77
|
+
UpdatePrdSectionInput,
|
|
78
|
+
UpdatePrdSectionOutput,
|
|
79
|
+
AddDecisionInput,
|
|
80
|
+
MarkNotApplicableInput,
|
|
81
|
+
MarkNotApplicableOutput,
|
|
82
|
+
AddDecisionOutput,
|
|
83
|
+
DecideEdgeCaseInput,
|
|
84
|
+
DecideEdgeCaseOutput,
|
|
85
|
+
ResolveOpenQuestionInput,
|
|
86
|
+
ResolveOpenQuestionOutput,
|
|
87
|
+
AddGlossaryTermInput,
|
|
88
|
+
AddGlossaryTermOutput,
|
|
89
|
+
UpdatePhaseInput,
|
|
90
|
+
DeletePhaseInput,
|
|
91
|
+
ReorderPhasesInput,
|
|
92
|
+
PhasesOutput,
|
|
93
|
+
} from './schema';
|
|
94
|
+
import { PRD_TEMPLATES, getTemplate } from './templates';
|
|
95
|
+
import type { StoryComplexity, StructuredPRD, UserStory } from './types';
|
|
96
|
+
|
|
97
|
+
import { join } from 'node:path';
|
|
98
|
+
|
|
99
|
+
export interface PrdVerificationDiagnostic {
|
|
100
|
+
file: string;
|
|
101
|
+
line: number | null;
|
|
102
|
+
message: string;
|
|
103
|
+
severity: string;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
export interface PrdVerificationResult {
|
|
107
|
+
passed: boolean;
|
|
108
|
+
/** Scripts that ran, e.g. ['typecheck', 'lint']. */
|
|
109
|
+
checks: string[];
|
|
110
|
+
errors: number;
|
|
111
|
+
warnings: number;
|
|
112
|
+
diagnostics: PrdVerificationDiagnostic[];
|
|
113
|
+
/** Human-readable reasons for checks that failed without diagnostics. */
|
|
114
|
+
messages: string[];
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export interface PrdDeps {
|
|
118
|
+
rootPath: string;
|
|
119
|
+
readdir(path: string): Promise<string[]>;
|
|
120
|
+
readFile(path: string): Promise<string>;
|
|
121
|
+
writeFile(path: string, content: string): Promise<void>;
|
|
122
|
+
/** Must not throw when the directory already exists. */
|
|
123
|
+
mkdir(path: string): Promise<void>;
|
|
124
|
+
unlink(path: string): Promise<void>;
|
|
125
|
+
fileExists(path: string): Promise<boolean>;
|
|
126
|
+
now(): Date;
|
|
127
|
+
/**
|
|
128
|
+
* Runs the project's checks before a story may be marked completed. When
|
|
129
|
+
* the result is not passing the status change is rejected, so "completed"
|
|
130
|
+
* always means "the code verifies", not "the agent believes it is done".
|
|
131
|
+
*/
|
|
132
|
+
verifyCompletion(): Promise<PrdVerificationResult>;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* A write was based on an older revision of the PRD than the one on disk:
|
|
137
|
+
* someone else (an agent, Loop, another editor) changed it in between. Read
|
|
138
|
+
* the PRD again and retry; never overwrite.
|
|
139
|
+
*/
|
|
140
|
+
export class PrdRevisionConflictError extends Error {
|
|
141
|
+
readonly code = 'PRD_REVISION_CONFLICT';
|
|
142
|
+
|
|
143
|
+
constructor(
|
|
144
|
+
readonly filename: string,
|
|
145
|
+
readonly expectedRevision: number,
|
|
146
|
+
readonly currentRevision: number,
|
|
147
|
+
) {
|
|
148
|
+
super(
|
|
149
|
+
`PRD "${filename}" was changed by someone else since it was read ` +
|
|
150
|
+
`(revision ${expectedRevision}, now ${currentRevision}). ` +
|
|
151
|
+
'Read it again and retry.',
|
|
152
|
+
);
|
|
153
|
+
this.name = 'PrdRevisionConflictError';
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export function createPrdService(deps: PrdDeps) {
|
|
158
|
+
return new PrdService(deps);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export class PrdService {
|
|
162
|
+
constructor(private readonly deps: PrdDeps) {}
|
|
163
|
+
|
|
164
|
+
get prdsDir() {
|
|
165
|
+
return join(this.deps.rootPath, '.prds');
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
async list(): Promise<ListPrdsOutput> {
|
|
169
|
+
const filenames = await this.listFilenames();
|
|
170
|
+
const prds: PrdSummary[] = [];
|
|
171
|
+
const warnings: string[] = [];
|
|
172
|
+
|
|
173
|
+
for (const filename of filenames) {
|
|
174
|
+
try {
|
|
175
|
+
const prd = await this.load(filename);
|
|
176
|
+
|
|
177
|
+
prds.push({
|
|
178
|
+
filename,
|
|
179
|
+
title: prd.introduction.title,
|
|
180
|
+
last_updated: prd.metadata.lastUpdated,
|
|
181
|
+
progress: prd.progress.overall,
|
|
182
|
+
total_stories: prd.progress.total,
|
|
183
|
+
completed_stories: prd.progress.completed,
|
|
184
|
+
blocked_stories: prd.progress.blocked,
|
|
185
|
+
});
|
|
186
|
+
} catch (error) {
|
|
187
|
+
warnings.push(
|
|
188
|
+
`Skipped ${filename}: ${error instanceof Error ? error.message : 'unreadable'}`,
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
return { prds, total: prds.length, prds_dir: this.prdsDir, warnings };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
async get(input: GetPrdInput): Promise<GetPrdOutput> {
|
|
197
|
+
const filename = this.safeName(input.filename);
|
|
198
|
+
const prd = await this.load(filename);
|
|
199
|
+
|
|
200
|
+
return {
|
|
201
|
+
filename,
|
|
202
|
+
path: join(this.prdsDir, filename),
|
|
203
|
+
prd,
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
async create(input: CreatePrdInput): Promise<CreatePrdOutput> {
|
|
208
|
+
await this.deps.mkdir(this.prdsDir);
|
|
209
|
+
|
|
210
|
+
const filename = `${slugify(input.title)}.json`;
|
|
211
|
+
const path = join(this.prdsDir, filename);
|
|
212
|
+
|
|
213
|
+
if (await this.deps.fileExists(path)) {
|
|
214
|
+
throw new Error(
|
|
215
|
+
`A PRD named "${filename}" already exists. Use a different title or delete it first with delete_prd.`,
|
|
216
|
+
);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
const today = this.today();
|
|
220
|
+
const defaults = input.template ? getTemplate(input.template).defaults : {};
|
|
221
|
+
|
|
222
|
+
const prd: StructuredPRD = {
|
|
223
|
+
introduction: {
|
|
224
|
+
title: input.title,
|
|
225
|
+
overview: input.overview,
|
|
226
|
+
lastUpdated: today,
|
|
227
|
+
},
|
|
228
|
+
problemStatement: {
|
|
229
|
+
problem: input.problemStatement,
|
|
230
|
+
marketOpportunity: input.marketOpportunity,
|
|
231
|
+
targetUsers: input.targetUsers,
|
|
232
|
+
},
|
|
233
|
+
solutionOverview: {
|
|
234
|
+
description: input.solutionDescription,
|
|
235
|
+
keyFeatures: input.keyFeatures,
|
|
236
|
+
successMetrics: input.successMetrics,
|
|
237
|
+
},
|
|
238
|
+
nonGoals: input.nonGoals ?? defaults.nonGoals ?? [],
|
|
239
|
+
outOfScope: input.outOfScope ?? defaults.outOfScope ?? [],
|
|
240
|
+
assumptions: input.assumptions ?? [],
|
|
241
|
+
openQuestions: normalizeOpenQuestions([
|
|
242
|
+
...(input.openQuestions ?? []),
|
|
243
|
+
...(defaults.openQuestions ?? []),
|
|
244
|
+
]),
|
|
245
|
+
risks: [],
|
|
246
|
+
dependencies: [],
|
|
247
|
+
userStories: [],
|
|
248
|
+
customPhases: [],
|
|
249
|
+
storyTraceability: [],
|
|
250
|
+
technicalRequirements: {
|
|
251
|
+
constraints: defaults.technicalConstraints ?? [],
|
|
252
|
+
integrationNeeds: [],
|
|
253
|
+
complianceRequirements: [],
|
|
254
|
+
},
|
|
255
|
+
technicalContracts: {
|
|
256
|
+
apis: [],
|
|
257
|
+
dataModels: [],
|
|
258
|
+
permissions: [],
|
|
259
|
+
integrationBoundaries: [],
|
|
260
|
+
},
|
|
261
|
+
acceptanceCriteria: {
|
|
262
|
+
global: defaults.globalAcceptanceCriteria ?? [],
|
|
263
|
+
qualityStandards: defaults.qualityStandards ?? [],
|
|
264
|
+
},
|
|
265
|
+
constraints: { timeline: '', resources: [], nonNegotiables: [] },
|
|
266
|
+
rolloutPlan: {
|
|
267
|
+
featureFlags: [],
|
|
268
|
+
migrationPlan: [],
|
|
269
|
+
rolloutPhases: defaults.rolloutPhases ?? [],
|
|
270
|
+
rollbackConditions: defaults.rollbackConditions ?? [],
|
|
271
|
+
},
|
|
272
|
+
measurementPlan: {
|
|
273
|
+
events: [],
|
|
274
|
+
dashboards: [],
|
|
275
|
+
baselineMetrics: [],
|
|
276
|
+
targetMetrics: [],
|
|
277
|
+
guardrailMetrics: [],
|
|
278
|
+
},
|
|
279
|
+
edgeCases: [],
|
|
280
|
+
designGuidance: [],
|
|
281
|
+
securityConsiderations: [],
|
|
282
|
+
notApplicable: {},
|
|
283
|
+
decisionLog: [],
|
|
284
|
+
glossary: [],
|
|
285
|
+
attachments: [],
|
|
286
|
+
agentTaskPackets: [],
|
|
287
|
+
changeLog: [
|
|
288
|
+
input.template
|
|
289
|
+
? `Initial PRD created from the ${input.template} template`
|
|
290
|
+
: 'Initial PRD created',
|
|
291
|
+
],
|
|
292
|
+
metadata: {
|
|
293
|
+
version: '2.0',
|
|
294
|
+
created: today,
|
|
295
|
+
lastUpdated: today,
|
|
296
|
+
lastValidatedAt: today,
|
|
297
|
+
approver: '',
|
|
298
|
+
},
|
|
299
|
+
progress: { overall: 0, completed: 0, total: 0, blocked: 0 },
|
|
300
|
+
};
|
|
301
|
+
|
|
302
|
+
await this.deps.writeFile(path, JSON.stringify(prd, null, 2));
|
|
303
|
+
|
|
304
|
+
return { status: 'success', filename, path };
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
async delete(input: DeletePrdInput): Promise<DeletePrdOutput> {
|
|
308
|
+
const filename = this.safeName(input.filename);
|
|
309
|
+
|
|
310
|
+
try {
|
|
311
|
+
await this.deps.unlink(join(this.prdsDir, filename));
|
|
312
|
+
} catch (error) {
|
|
313
|
+
if (isErrnoCode(error, 'ENOENT')) {
|
|
314
|
+
throw new Error(`PRD file "${filename}" not found`);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
throw error;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
return { status: 'success', filename };
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
async addUserStory(input: AddUserStoryInput): Promise<AddUserStoryOutput> {
|
|
324
|
+
const filename = this.safeName(input.filename);
|
|
325
|
+
const prd = await this.load(filename);
|
|
326
|
+
|
|
327
|
+
const storyId = nextStoryId(prd);
|
|
328
|
+
const title = input.title?.trim() || titleFromAction(input.action);
|
|
329
|
+
const complexity =
|
|
330
|
+
input.estimatedComplexity ?? assessComplexity(input.acceptanceCriteria);
|
|
331
|
+
|
|
332
|
+
prd.userStories.push({
|
|
333
|
+
id: storyId,
|
|
334
|
+
title,
|
|
335
|
+
userStory: renderUserStory(input),
|
|
336
|
+
businessValue: input.benefit,
|
|
337
|
+
acceptanceCriteria: input.acceptanceCriteria.filter(
|
|
338
|
+
(entry) => entry.trim().length > 0,
|
|
339
|
+
),
|
|
340
|
+
status: 'not_started',
|
|
341
|
+
priority: input.priority,
|
|
342
|
+
estimatedComplexity: complexity,
|
|
343
|
+
dependencies: [],
|
|
344
|
+
...(input.testSeams?.length ? { testSeams: input.testSeams } : {}),
|
|
345
|
+
...(input.designNotes?.length
|
|
346
|
+
? { designNotes: input.designNotes }
|
|
347
|
+
: {}),
|
|
348
|
+
...(input.securityNotes?.length
|
|
349
|
+
? { securityNotes: input.securityNotes }
|
|
350
|
+
: {}),
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
// Validated against the in-memory PRD; a bad id throws before anything is saved.
|
|
354
|
+
if (input.dependencies?.length) {
|
|
355
|
+
findStory(prd, storyId).dependencies = validateDependencies(
|
|
356
|
+
prd,
|
|
357
|
+
storyId,
|
|
358
|
+
input.dependencies,
|
|
359
|
+
);
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
if (input.attachmentIds?.length) {
|
|
363
|
+
findStory(prd, storyId).attachmentIds = validateAttachmentIds(
|
|
364
|
+
prd,
|
|
365
|
+
input.attachmentIds,
|
|
366
|
+
);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
if (input.phaseId) {
|
|
370
|
+
assignStoryToPhase(
|
|
371
|
+
prd,
|
|
372
|
+
{ filename, storyId, phaseId: input.phaseId },
|
|
373
|
+
this.today(),
|
|
374
|
+
);
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
recomputeProgress(prd);
|
|
378
|
+
appendChangeLog(prd, `Added ${storyId} (${title})`, this.today());
|
|
379
|
+
await this.save(filename, prd);
|
|
380
|
+
|
|
381
|
+
return {
|
|
382
|
+
story_id: storyId,
|
|
383
|
+
title,
|
|
384
|
+
complexity,
|
|
385
|
+
total_stories: prd.userStories.length,
|
|
386
|
+
};
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
async updateUserStory(
|
|
390
|
+
input: UpdateUserStoryInput,
|
|
391
|
+
): Promise<UpdateUserStoryOutput> {
|
|
392
|
+
return this.mutate(
|
|
393
|
+
input.filename,
|
|
394
|
+
(prd) => updateStory(prd, input, this.today()),
|
|
395
|
+
input.expectedRevision,
|
|
396
|
+
);
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
async deleteUserStory(
|
|
400
|
+
input: DeleteUserStoryInput,
|
|
401
|
+
): Promise<DeleteUserStoryOutput> {
|
|
402
|
+
const filename = this.safeName(input.filename);
|
|
403
|
+
const prd = await this.load(filename);
|
|
404
|
+
const result = deleteStory(prd, input.storyId, this.today());
|
|
405
|
+
|
|
406
|
+
await this.save(filename, prd);
|
|
407
|
+
|
|
408
|
+
return result;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
async createCustomPhase(
|
|
412
|
+
input: CreateCustomPhaseInput,
|
|
413
|
+
): Promise<CreateCustomPhaseOutput> {
|
|
414
|
+
const filename = this.safeName(input.filename);
|
|
415
|
+
const prd = await this.load(filename);
|
|
416
|
+
const result = createPhase(prd, input, this.today());
|
|
417
|
+
|
|
418
|
+
await this.save(filename, prd);
|
|
419
|
+
|
|
420
|
+
return result;
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
async assignStoryToPhase(
|
|
424
|
+
input: AssignStoryToPhaseInput,
|
|
425
|
+
): Promise<AssignStoryToPhaseOutput> {
|
|
426
|
+
const filename = this.safeName(input.filename);
|
|
427
|
+
const prd = await this.load(filename);
|
|
428
|
+
const result = assignStoryToPhase(prd, input, this.today());
|
|
429
|
+
|
|
430
|
+
await this.save(filename, prd);
|
|
431
|
+
|
|
432
|
+
return result;
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
async updateStoryStatus(
|
|
436
|
+
input: UpdateStoryStatusInput,
|
|
437
|
+
): Promise<UpdateStoryStatusOutput> {
|
|
438
|
+
const filename = this.safeName(input.filename);
|
|
439
|
+
|
|
440
|
+
// Validate the target and the workflow before paying for verification.
|
|
441
|
+
const current = await this.load(filename);
|
|
442
|
+
const currentRevision = current.metadata.revision ?? 0;
|
|
443
|
+
|
|
444
|
+
// Checked against what the caller saw, before the (slow) checks: edits
|
|
445
|
+
// made while the checks run, e.g. an agent's log entry, are expected.
|
|
446
|
+
if (
|
|
447
|
+
input.expectedRevision !== undefined &&
|
|
448
|
+
input.expectedRevision !== currentRevision
|
|
449
|
+
) {
|
|
450
|
+
throw new PrdRevisionConflictError(
|
|
451
|
+
filename,
|
|
452
|
+
input.expectedRevision,
|
|
453
|
+
currentRevision,
|
|
454
|
+
);
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
assertCanEnterStatus(
|
|
458
|
+
current,
|
|
459
|
+
findStory(current, input.storyId),
|
|
460
|
+
input.status,
|
|
461
|
+
);
|
|
462
|
+
|
|
463
|
+
let verification: UpdateStoryStatusOutput['verification'] = null;
|
|
464
|
+
|
|
465
|
+
if (input.status === 'completed') {
|
|
466
|
+
const result = await this.deps.verifyCompletion();
|
|
467
|
+
|
|
468
|
+
if (!result.passed) {
|
|
469
|
+
throw new Error(buildVerificationFailure(input.storyId, result));
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
verification = {
|
|
473
|
+
verified_at: this.deps.now().toISOString(),
|
|
474
|
+
checks: result.checks,
|
|
475
|
+
passed: true,
|
|
476
|
+
};
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
// Verification can take minutes: reload so concurrent edits made in the
|
|
480
|
+
// meantime are not overwritten by a stale snapshot.
|
|
481
|
+
const prd = await this.load(filename);
|
|
482
|
+
const story = findStory(prd, input.storyId);
|
|
483
|
+
assertCanEnterStatus(prd, story, input.status);
|
|
484
|
+
|
|
485
|
+
const previousStatus = story.status;
|
|
486
|
+
|
|
487
|
+
if (verification) {
|
|
488
|
+
story.verification = {
|
|
489
|
+
verifiedAt: verification.verified_at,
|
|
490
|
+
checks: verification.checks,
|
|
491
|
+
passed: true,
|
|
492
|
+
};
|
|
493
|
+
story.completedAt = this.today();
|
|
494
|
+
|
|
495
|
+
// The one moment the project is known to build and lint clean.
|
|
496
|
+
prd.metadata.lastValidatedAt = this.today();
|
|
497
|
+
} else {
|
|
498
|
+
delete story.verification;
|
|
499
|
+
delete story.completedAt;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
story.status = input.status;
|
|
503
|
+
|
|
504
|
+
if (input.notes) {
|
|
505
|
+
story.notes = input.notes;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
recomputeProgress(prd);
|
|
509
|
+
appendChangeLog(
|
|
510
|
+
prd,
|
|
511
|
+
`${story.id} ${previousStatus} -> ${story.status}`,
|
|
512
|
+
this.today(),
|
|
513
|
+
);
|
|
514
|
+
await this.save(filename, prd);
|
|
515
|
+
|
|
516
|
+
return {
|
|
517
|
+
story_id: story.id,
|
|
518
|
+
title: story.title,
|
|
519
|
+
status: story.status,
|
|
520
|
+
progress: prd.progress.overall,
|
|
521
|
+
verification,
|
|
522
|
+
};
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
async exportMarkdown(
|
|
526
|
+
input: ExportPrdMarkdownInput,
|
|
527
|
+
): Promise<ExportPrdMarkdownOutput> {
|
|
528
|
+
const filename = this.safeName(input.filename);
|
|
529
|
+
const prd = await this.load(filename);
|
|
530
|
+
|
|
531
|
+
const markdownFile = filename.replace(/\.json$/, '.md');
|
|
532
|
+
const path = join(this.prdsDir, markdownFile);
|
|
533
|
+
|
|
534
|
+
await this.deps.writeFile(path, formatPrdMarkdown(prd, filename));
|
|
535
|
+
|
|
536
|
+
return { markdown_file: markdownFile, path };
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
async getImplementationPrompts(
|
|
540
|
+
filename: string,
|
|
541
|
+
): Promise<GetImplementationPromptsOutput> {
|
|
542
|
+
const name = this.safeName(filename);
|
|
543
|
+
const prd = await this.load(name);
|
|
544
|
+
const prompts: string[] = [];
|
|
545
|
+
|
|
546
|
+
// Only stories that can start now: the prompt sets them in progress.
|
|
547
|
+
for (const story of prd.userStories
|
|
548
|
+
.filter(
|
|
549
|
+
(s) =>
|
|
550
|
+
s.status === 'not_started' &&
|
|
551
|
+
incompleteDependencies(prd, s).length === 0,
|
|
552
|
+
)
|
|
553
|
+
.slice(0, 3)) {
|
|
554
|
+
prompts.push(implementStoryPrompt(name, story.id));
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
return { prompts, total: prompts.length };
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
async getImprovementSuggestions(
|
|
561
|
+
filename: string,
|
|
562
|
+
): Promise<GetImprovementSuggestionsOutput> {
|
|
563
|
+
const suggestions = (await this.checkPlan(filename)).items.map(
|
|
564
|
+
(item) => item.message,
|
|
565
|
+
);
|
|
566
|
+
|
|
567
|
+
return { suggestions, total: suggestions.length };
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
listTemplates(): ListTemplatesOutput {
|
|
571
|
+
return {
|
|
572
|
+
templates: PRD_TEMPLATES.map((template) => ({
|
|
573
|
+
id: template.id,
|
|
574
|
+
name: template.name,
|
|
575
|
+
description: template.description,
|
|
576
|
+
when_to_use: template.whenToUse,
|
|
577
|
+
})),
|
|
578
|
+
};
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
async checkPlan(filename: string): Promise<CheckPlanOutput> {
|
|
582
|
+
return checkPlan(await this.load(this.safeName(filename)));
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
async getProjectStatus(filename: string): Promise<GetProjectStatusOutput> {
|
|
586
|
+
const prd = await this.load(this.safeName(filename));
|
|
587
|
+
|
|
588
|
+
const blockers = prd.userStories.filter((s) => s.status === 'blocked');
|
|
589
|
+
const inProgress = prd.userStories.filter(
|
|
590
|
+
(s) => s.status === 'in_progress',
|
|
591
|
+
);
|
|
592
|
+
const nextPending = prd.userStories
|
|
593
|
+
.filter((s) => s.status === 'not_started')
|
|
594
|
+
.slice(0, 3);
|
|
595
|
+
const highRisks = prd.risks.filter((risk) => risk.severity === 'high');
|
|
596
|
+
|
|
597
|
+
return {
|
|
598
|
+
progress: prd.progress.overall,
|
|
599
|
+
summary: `${prd.progress.completed}/${prd.progress.total} stories completed (${prd.progress.overall}%). Open questions: ${prd.openQuestions.length}. High risks: ${highRisks.length}.`,
|
|
600
|
+
next_steps: [
|
|
601
|
+
...inProgress.map((s) => `Continue: ${s.title}`),
|
|
602
|
+
...nextPending.map((s) => `Start: ${s.title}`),
|
|
603
|
+
],
|
|
604
|
+
blockers: blockers.map((s) => ({
|
|
605
|
+
id: s.id,
|
|
606
|
+
title: s.title,
|
|
607
|
+
notes: s.notes ?? null,
|
|
608
|
+
})),
|
|
609
|
+
open_questions: prd.openQuestions.map((question) => question.question),
|
|
610
|
+
high_risks: highRisks.map(({ id, description, mitigation, owner }) => ({
|
|
611
|
+
id,
|
|
612
|
+
description,
|
|
613
|
+
mitigation,
|
|
614
|
+
owner,
|
|
615
|
+
})),
|
|
616
|
+
};
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
// Planning ----------------------------------------------------------------
|
|
620
|
+
|
|
621
|
+
updatePrdSection(
|
|
622
|
+
input: UpdatePrdSectionInput,
|
|
623
|
+
): Promise<UpdatePrdSectionOutput> {
|
|
624
|
+
return this.mutate(
|
|
625
|
+
input.filename,
|
|
626
|
+
(prd) => updatePrdSection(prd, input, this.today()),
|
|
627
|
+
input.expectedRevision,
|
|
628
|
+
);
|
|
629
|
+
}
|
|
630
|
+
|
|
631
|
+
/** Mark a part of the PRD (not) applicable, e.g. no rollout for an internal tool. */
|
|
632
|
+
markNotApplicable(
|
|
633
|
+
input: MarkNotApplicableInput,
|
|
634
|
+
): Promise<MarkNotApplicableOutput> {
|
|
635
|
+
return this.mutate(
|
|
636
|
+
input.filename,
|
|
637
|
+
(prd) => setNotApplicable(prd, input, this.today()),
|
|
638
|
+
input.expectedRevision,
|
|
639
|
+
);
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
addDecision(input: AddDecisionInput): Promise<AddDecisionOutput> {
|
|
643
|
+
return this.mutate(input.filename, (prd) =>
|
|
644
|
+
addDecision(prd, input, this.today()),
|
|
645
|
+
);
|
|
646
|
+
}
|
|
647
|
+
|
|
648
|
+
resolveOpenQuestion(
|
|
649
|
+
input: ResolveOpenQuestionInput,
|
|
650
|
+
): Promise<ResolveOpenQuestionOutput> {
|
|
651
|
+
return this.mutate(
|
|
652
|
+
input.filename,
|
|
653
|
+
(prd) => resolveOpenQuestion(prd, input, this.today()),
|
|
654
|
+
input.expectedRevision,
|
|
655
|
+
);
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
decideEdgeCase(input: DecideEdgeCaseInput): Promise<DecideEdgeCaseOutput> {
|
|
659
|
+
return this.mutate(
|
|
660
|
+
input.filename,
|
|
661
|
+
(prd) => decideEdgeCase(prd, input, this.today()),
|
|
662
|
+
input.expectedRevision,
|
|
663
|
+
);
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
addGlossaryTerm(input: AddGlossaryTermInput): Promise<AddGlossaryTermOutput> {
|
|
667
|
+
return this.mutate(input.filename, (prd) =>
|
|
668
|
+
addGlossaryTerm(prd, input, this.today()),
|
|
669
|
+
);
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
updatePhase(input: UpdatePhaseInput): Promise<PhasesOutput> {
|
|
673
|
+
return this.mutate(input.filename, (prd) =>
|
|
674
|
+
updatePhase(prd, input, this.today()),
|
|
675
|
+
);
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
deletePhase(input: DeletePhaseInput): Promise<PhasesOutput> {
|
|
679
|
+
return this.mutate(input.filename, (prd) =>
|
|
680
|
+
deletePhase(prd, input, this.today()),
|
|
681
|
+
);
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
reorderPhases(input: ReorderPhasesInput): Promise<PhasesOutput> {
|
|
685
|
+
return this.mutate(input.filename, (prd) =>
|
|
686
|
+
reorderPhases(prd, input, this.today()),
|
|
687
|
+
);
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
// Agent workflow ----------------------------------------------------------
|
|
691
|
+
|
|
692
|
+
async getNextStory(filename: string): Promise<GetNextStoryOutput> {
|
|
693
|
+
return pickNextStory(await this.load(this.safeName(filename)));
|
|
694
|
+
}
|
|
695
|
+
|
|
696
|
+
async getStory(input: GetStoryInput): Promise<GetStoryOutput> {
|
|
697
|
+
const filename = this.safeName(input.filename);
|
|
698
|
+
const prd = await this.load(filename);
|
|
699
|
+
|
|
700
|
+
return buildStoryContext(prd, input.storyId, filename);
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
async addStoryLog(input: AddStoryLogInput): Promise<AddStoryLogOutput> {
|
|
704
|
+
const filename = this.safeName(input.filename);
|
|
705
|
+
const prd = await this.load(filename);
|
|
706
|
+
|
|
707
|
+
const result = appendStoryLog(prd, input.storyId, {
|
|
708
|
+
at: this.deps.now().toISOString(),
|
|
709
|
+
whatsNew: input.whatsNew,
|
|
710
|
+
technicalNotes: input.technicalNotes,
|
|
711
|
+
...(input.deviations?.length && { deviations: input.deviations }),
|
|
712
|
+
});
|
|
713
|
+
|
|
714
|
+
appendChangeLog(prd, `Logged work on ${result.story_id}`, this.today());
|
|
715
|
+
await this.save(filename, prd);
|
|
716
|
+
|
|
717
|
+
return result;
|
|
718
|
+
}
|
|
719
|
+
|
|
720
|
+
// Attachments -------------------------------------------------------------
|
|
721
|
+
|
|
722
|
+
/** Files must already be in the PRD's folder, `.prds/<prd name>/`. */
|
|
723
|
+
async addAttachment(input: AddAttachmentInput): Promise<AddAttachmentOutput> {
|
|
724
|
+
const filename = this.safeName(input.filename);
|
|
725
|
+
|
|
726
|
+
if (input.path) {
|
|
727
|
+
const folder = attachmentsFolder(filename);
|
|
728
|
+
const path = assertSafeRelativePath(input.path, 'attachment path');
|
|
729
|
+
|
|
730
|
+
if (!(await this.deps.fileExists(join(this.prdsDir, folder, path)))) {
|
|
731
|
+
throw new Error(
|
|
732
|
+
`File ".prds/${folder}/${path}" not found. Save it in .prds/${folder}/ first.`,
|
|
733
|
+
);
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
return this.mutate(
|
|
738
|
+
filename,
|
|
739
|
+
(prd) => addAttachment(prd, { ...input, filename }, this.today()),
|
|
740
|
+
input.expectedRevision,
|
|
741
|
+
);
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/** Changes an attachment's title, note or the stories that use it. */
|
|
745
|
+
updateAttachment(input: UpdateAttachmentInput): Promise<UpdateAttachmentOutput> {
|
|
746
|
+
return this.mutate(
|
|
747
|
+
input.filename,
|
|
748
|
+
(prd) => updateAttachment(prd, input, this.today()),
|
|
749
|
+
input.expectedRevision,
|
|
750
|
+
);
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
/** Removes the attachment from the PRD and its stories; the file stays. */
|
|
754
|
+
async removeAttachment(
|
|
755
|
+
input: RemoveAttachmentInput,
|
|
756
|
+
): Promise<RemoveAttachmentOutput> {
|
|
757
|
+
return this.mutate(
|
|
758
|
+
input.filename,
|
|
759
|
+
(prd) => removeAttachment(prd, input.attachmentId, this.today()),
|
|
760
|
+
input.expectedRevision,
|
|
761
|
+
);
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
// Persistence -------------------------------------------------------------
|
|
765
|
+
|
|
766
|
+
/** Load → transform → save for operations that only touch the PRD. */
|
|
767
|
+
/**
|
|
768
|
+
* Load, change and save a PRD. With `expectedRevision` (the revision the
|
|
769
|
+
* caller's change is based on, e.g. what a person saw before editing), the
|
|
770
|
+
* change is rejected when the PRD has moved on since.
|
|
771
|
+
*/
|
|
772
|
+
private async mutate<T>(
|
|
773
|
+
filename: string,
|
|
774
|
+
transform: (prd: StructuredPRD) => T,
|
|
775
|
+
expectedRevision?: number,
|
|
776
|
+
): Promise<T> {
|
|
777
|
+
const name = this.safeName(filename);
|
|
778
|
+
const prd = await this.load(name);
|
|
779
|
+
const currentRevision = prd.metadata.revision ?? 0;
|
|
780
|
+
|
|
781
|
+
if (
|
|
782
|
+
expectedRevision !== undefined &&
|
|
783
|
+
expectedRevision !== currentRevision
|
|
784
|
+
) {
|
|
785
|
+
throw new PrdRevisionConflictError(
|
|
786
|
+
name,
|
|
787
|
+
expectedRevision,
|
|
788
|
+
currentRevision,
|
|
789
|
+
);
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
const result = transform(prd);
|
|
793
|
+
|
|
794
|
+
await this.save(name, prd);
|
|
795
|
+
|
|
796
|
+
return result;
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
/**
|
|
800
|
+
* Load and normalise a PRD. The file name is validated here, at the
|
|
801
|
+
* filesystem boundary, so every caller (including the dev tool) is covered.
|
|
802
|
+
*/
|
|
803
|
+
async load(filename: string): Promise<StructuredPRD> {
|
|
804
|
+
const name = this.safeName(filename);
|
|
805
|
+
let raw: string;
|
|
806
|
+
|
|
807
|
+
try {
|
|
808
|
+
raw = await this.deps.readFile(join(this.prdsDir, name));
|
|
809
|
+
} catch {
|
|
810
|
+
throw new Error(`PRD file "${name}" not found`);
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
let parsed: unknown;
|
|
814
|
+
|
|
815
|
+
try {
|
|
816
|
+
parsed = JSON.parse(raw);
|
|
817
|
+
} catch {
|
|
818
|
+
throw new Error(`PRD file "${name}" is not valid JSON`);
|
|
819
|
+
}
|
|
820
|
+
|
|
821
|
+
return normalizePrd(parsed, this.today());
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
private async save(filename: string, prd: StructuredPRD) {
|
|
825
|
+
const today = this.today();
|
|
826
|
+
const path = join(this.prdsDir, filename);
|
|
827
|
+
const loadedRevision = prd.metadata.revision ?? 0;
|
|
828
|
+
|
|
829
|
+
if (await this.deps.fileExists(path)) {
|
|
830
|
+
const onDisk = await this.load(filename);
|
|
831
|
+
|
|
832
|
+
if ((onDisk.metadata.revision ?? 0) !== loadedRevision) {
|
|
833
|
+
throw new PrdRevisionConflictError(
|
|
834
|
+
filename,
|
|
835
|
+
loadedRevision,
|
|
836
|
+
onDisk.metadata.revision ?? 0,
|
|
837
|
+
);
|
|
838
|
+
}
|
|
839
|
+
}
|
|
840
|
+
|
|
841
|
+
prd.metadata.revision = loadedRevision + 1;
|
|
842
|
+
|
|
843
|
+
prd.metadata.lastUpdated = today;
|
|
844
|
+
prd.introduction.lastUpdated = today;
|
|
845
|
+
|
|
846
|
+
// Callers append their own change-log entry describing what they did. The
|
|
847
|
+
// previous `if (changeLog.length === 0)` guard meant the log never grew
|
|
848
|
+
// past the line `create` seeded, so a PRD's history was always one entry.
|
|
849
|
+
|
|
850
|
+
await this.deps.writeFile(path, JSON.stringify(prd, null, 2));
|
|
851
|
+
}
|
|
852
|
+
|
|
853
|
+
private async listFilenames() {
|
|
854
|
+
await this.deps.mkdir(this.prdsDir);
|
|
855
|
+
|
|
856
|
+
try {
|
|
857
|
+
return (await this.deps.readdir(this.prdsDir))
|
|
858
|
+
.filter((file) => file.endsWith('.json'))
|
|
859
|
+
.sort();
|
|
860
|
+
} catch {
|
|
861
|
+
return [];
|
|
862
|
+
}
|
|
863
|
+
}
|
|
864
|
+
|
|
865
|
+
private safeName(filename: string) {
|
|
866
|
+
return assertSafeFileName(filename, 'PRD file name');
|
|
867
|
+
}
|
|
868
|
+
|
|
869
|
+
private today() {
|
|
870
|
+
return this.deps.now().toISOString().slice(0, 10);
|
|
871
|
+
}
|
|
872
|
+
}
|
|
873
|
+
|
|
874
|
+
function buildVerificationFailure(
|
|
875
|
+
storyId: string,
|
|
876
|
+
result: PrdVerificationResult,
|
|
877
|
+
) {
|
|
878
|
+
const sample = result.diagnostics
|
|
879
|
+
.slice(0, 5)
|
|
880
|
+
.map((d) => `${d.file}${d.line ? `:${d.line}` : ''} ${d.message}`)
|
|
881
|
+
.join('; ');
|
|
882
|
+
|
|
883
|
+
const reasons = [
|
|
884
|
+
sample ? `First diagnostics: ${sample}.` : '',
|
|
885
|
+
...result.messages,
|
|
886
|
+
]
|
|
887
|
+
.filter(Boolean)
|
|
888
|
+
.join(' ');
|
|
889
|
+
|
|
890
|
+
return (
|
|
891
|
+
`Cannot mark ${storyId} as completed: verification failed ` +
|
|
892
|
+
`(${result.errors} errors, ${result.warnings} warnings across ${result.checks.join(', ') || 'no checks'}). ` +
|
|
893
|
+
(reasons ? `${reasons} ` : '') +
|
|
894
|
+
'Fix the issues, run the project checks, then retry.'
|
|
895
|
+
);
|
|
896
|
+
}
|
|
897
|
+
|
|
898
|
+
function isErrnoCode(error: unknown, code: string) {
|
|
899
|
+
return (
|
|
900
|
+
typeof error === 'object' &&
|
|
901
|
+
error !== null &&
|
|
902
|
+
'code' in error &&
|
|
903
|
+
(error as { code?: unknown }).code === code
|
|
904
|
+
);
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
export function normalizePrd(input: unknown, today: string): StructuredPRD {
|
|
908
|
+
const prd = (isPlainObject(input) ? input : {}) as Partial<StructuredPRD>;
|
|
909
|
+
const openQuestions = normalizeOpenQuestions(prd.openQuestions);
|
|
910
|
+
// Ids given to questions from older files must never be handed out again
|
|
911
|
+
const highestQuestion = openQuestions.reduce(
|
|
912
|
+
(max, question) => Math.max(max, Number(/^Q(\d+)$/.exec(question.id)?.[1] ?? 0)),
|
|
913
|
+
0,
|
|
914
|
+
);
|
|
915
|
+
|
|
916
|
+
return {
|
|
917
|
+
// Keep top-level fields this version does not know, so a file written by
|
|
918
|
+
// a newer version keeps them when this one saves it. Known sections below
|
|
919
|
+
// are rebuilt, so unknown keys inside them are not kept.
|
|
920
|
+
...prd,
|
|
921
|
+
introduction: {
|
|
922
|
+
title: prd.introduction?.title ?? 'Untitled PRD',
|
|
923
|
+
overview: prd.introduction?.overview ?? '',
|
|
924
|
+
lastUpdated: prd.introduction?.lastUpdated ?? today,
|
|
925
|
+
},
|
|
926
|
+
problemStatement: {
|
|
927
|
+
problem: prd.problemStatement?.problem ?? '',
|
|
928
|
+
marketOpportunity: prd.problemStatement?.marketOpportunity ?? '',
|
|
929
|
+
targetUsers: prd.problemStatement?.targetUsers ?? [],
|
|
930
|
+
},
|
|
931
|
+
solutionOverview: {
|
|
932
|
+
description: prd.solutionOverview?.description ?? '',
|
|
933
|
+
keyFeatures: prd.solutionOverview?.keyFeatures ?? [],
|
|
934
|
+
successMetrics: prd.solutionOverview?.successMetrics ?? [],
|
|
935
|
+
},
|
|
936
|
+
nonGoals: prd.nonGoals ?? [],
|
|
937
|
+
outOfScope: prd.outOfScope ?? [],
|
|
938
|
+
assumptions: prd.assumptions ?? [],
|
|
939
|
+
openQuestions,
|
|
940
|
+
risks: prd.risks ?? [],
|
|
941
|
+
dependencies: prd.dependencies ?? [],
|
|
942
|
+
userStories: prd.userStories ?? [],
|
|
943
|
+
customPhases: prd.customPhases ?? [],
|
|
944
|
+
storyTraceability: prd.storyTraceability ?? [],
|
|
945
|
+
technicalRequirements: {
|
|
946
|
+
constraints: prd.technicalRequirements?.constraints ?? [],
|
|
947
|
+
integrationNeeds: prd.technicalRequirements?.integrationNeeds ?? [],
|
|
948
|
+
complianceRequirements:
|
|
949
|
+
prd.technicalRequirements?.complianceRequirements ?? [],
|
|
950
|
+
},
|
|
951
|
+
technicalContracts: {
|
|
952
|
+
apis: prd.technicalContracts?.apis ?? [],
|
|
953
|
+
dataModels: prd.technicalContracts?.dataModels ?? [],
|
|
954
|
+
permissions: prd.technicalContracts?.permissions ?? [],
|
|
955
|
+
integrationBoundaries:
|
|
956
|
+
prd.technicalContracts?.integrationBoundaries ?? [],
|
|
957
|
+
},
|
|
958
|
+
acceptanceCriteria: {
|
|
959
|
+
global: prd.acceptanceCriteria?.global ?? [],
|
|
960
|
+
qualityStandards: prd.acceptanceCriteria?.qualityStandards ?? [],
|
|
961
|
+
},
|
|
962
|
+
constraints: {
|
|
963
|
+
timeline: prd.constraints?.timeline ?? '',
|
|
964
|
+
budget: prd.constraints?.budget,
|
|
965
|
+
resources: prd.constraints?.resources ?? [],
|
|
966
|
+
nonNegotiables: prd.constraints?.nonNegotiables ?? [],
|
|
967
|
+
},
|
|
968
|
+
rolloutPlan: {
|
|
969
|
+
featureFlags: prd.rolloutPlan?.featureFlags ?? [],
|
|
970
|
+
migrationPlan: prd.rolloutPlan?.migrationPlan ?? [],
|
|
971
|
+
rolloutPhases: prd.rolloutPlan?.rolloutPhases ?? [],
|
|
972
|
+
rollbackConditions: prd.rolloutPlan?.rollbackConditions ?? [],
|
|
973
|
+
},
|
|
974
|
+
measurementPlan: {
|
|
975
|
+
events: prd.measurementPlan?.events ?? [],
|
|
976
|
+
dashboards: prd.measurementPlan?.dashboards ?? [],
|
|
977
|
+
baselineMetrics: prd.measurementPlan?.baselineMetrics ?? [],
|
|
978
|
+
targetMetrics: prd.measurementPlan?.targetMetrics ?? [],
|
|
979
|
+
guardrailMetrics: prd.measurementPlan?.guardrailMetrics ?? [],
|
|
980
|
+
},
|
|
981
|
+
edgeCases: normalizeEdgeCases(prd.edgeCases),
|
|
982
|
+
securityConsiderations: Array.isArray(prd.securityConsiderations)
|
|
983
|
+
? prd.securityConsiderations.filter(
|
|
984
|
+
(item): item is string => typeof item === 'string',
|
|
985
|
+
)
|
|
986
|
+
: [],
|
|
987
|
+
notApplicable: normalizeNotApplicable(prd.notApplicable),
|
|
988
|
+
designGuidance: Array.isArray(prd.designGuidance)
|
|
989
|
+
? prd.designGuidance.filter((item): item is string => typeof item === 'string')
|
|
990
|
+
: [],
|
|
991
|
+
decisionLog: prd.decisionLog ?? [],
|
|
992
|
+
glossary: prd.glossary ?? [],
|
|
993
|
+
attachments: normalizeAttachments(prd.attachments),
|
|
994
|
+
agentTaskPackets: prd.agentTaskPackets ?? [],
|
|
995
|
+
changeLog: prd.changeLog ?? [],
|
|
996
|
+
metadata: {
|
|
997
|
+
version: prd.metadata?.version ?? '2.0',
|
|
998
|
+
created: prd.metadata?.created ?? today,
|
|
999
|
+
lastUpdated: prd.metadata?.lastUpdated ?? today,
|
|
1000
|
+
lastValidatedAt: prd.metadata?.lastValidatedAt ?? today,
|
|
1001
|
+
approver: prd.metadata?.approver ?? '',
|
|
1002
|
+
lastStoryNumber: prd.metadata?.lastStoryNumber,
|
|
1003
|
+
lastAttachmentNumber: prd.metadata?.lastAttachmentNumber,
|
|
1004
|
+
lastQuestionNumber:
|
|
1005
|
+
Math.max(prd.metadata?.lastQuestionNumber ?? 0, highestQuestion) || undefined,
|
|
1006
|
+
revision: prd.metadata?.revision,
|
|
1007
|
+
},
|
|
1008
|
+
progress: {
|
|
1009
|
+
overall: prd.progress?.overall ?? 0,
|
|
1010
|
+
completed: prd.progress?.completed ?? 0,
|
|
1011
|
+
total: prd.progress?.total ?? 0,
|
|
1012
|
+
blocked: prd.progress?.blocked ?? 0,
|
|
1013
|
+
},
|
|
1014
|
+
};
|
|
1015
|
+
}
|
|
1016
|
+
|
|
1017
|
+
function isPlainObject(value: unknown): value is Record<string, unknown> {
|
|
1018
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
1019
|
+
}
|
|
1020
|
+
|
|
1021
|
+
function slugify(value: string) {
|
|
1022
|
+
const slug = value
|
|
1023
|
+
.toLowerCase()
|
|
1024
|
+
.replace(/[^a-z0-9]+/g, '-')
|
|
1025
|
+
.replace(/^-+|-+$/g, '');
|
|
1026
|
+
|
|
1027
|
+
return slug || 'untitled-prd';
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
function titleFromAction(action: string) {
|
|
1031
|
+
return action
|
|
1032
|
+
.trim()
|
|
1033
|
+
.toLowerCase()
|
|
1034
|
+
.split(/\s+/)
|
|
1035
|
+
.slice(0, 4)
|
|
1036
|
+
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
|
1037
|
+
.join(' ');
|
|
1038
|
+
}
|
|
1039
|
+
|
|
1040
|
+
function assessComplexity(criteria: string[]): StoryComplexity {
|
|
1041
|
+
const count = criteria.length;
|
|
1042
|
+
|
|
1043
|
+
if (count <= 2) return 'XS';
|
|
1044
|
+
if (count <= 3) return 'S';
|
|
1045
|
+
if (count <= 5) return 'M';
|
|
1046
|
+
if (count <= 8) return 'L';
|
|
1047
|
+
|
|
1048
|
+
return 'XL';
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
export type { StructuredPRD, UserStory };
|