@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,690 @@
|
|
|
1
|
+
import { resolveAttachments } from './attachment-paths';
|
|
2
|
+
import { designDecisions, edgeCasesForStory } from './edge-cases';
|
|
3
|
+
import type {
|
|
4
|
+
AssignStoryToPhaseInput,
|
|
5
|
+
AssignStoryToPhaseOutput,
|
|
6
|
+
CreateCustomPhaseInput,
|
|
7
|
+
CreateCustomPhaseOutput,
|
|
8
|
+
DeleteUserStoryOutput,
|
|
9
|
+
UpdateUserStoryInput,
|
|
10
|
+
UpdateUserStoryOutput,
|
|
11
|
+
} from './schema';
|
|
12
|
+
import type {
|
|
13
|
+
StoryLogEntry,
|
|
14
|
+
StoryStatus,
|
|
15
|
+
StructuredPRD,
|
|
16
|
+
UserStory,
|
|
17
|
+
} from './types';
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Pure PRD transforms.
|
|
21
|
+
*
|
|
22
|
+
* Everything here takes an already-loaded `StructuredPRD`, mutates it, and
|
|
23
|
+
* returns the tool payload. No filesystem, no clock, no deps — the service is
|
|
24
|
+
* left with load → transform → save, and every rule below is unit-testable
|
|
25
|
+
* without a harness.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Issues the next story id and advances the high-water mark.
|
|
30
|
+
*
|
|
31
|
+
* Deliberately not `max(existing) + 1`: delete the highest-numbered story and
|
|
32
|
+
* that hands its id straight to the next one, so a story id quoted in a commit
|
|
33
|
+
* or a decision-log topic would silently come to mean something else.
|
|
34
|
+
*/
|
|
35
|
+
export function nextId(items: { id: string }[], prefix: string) {
|
|
36
|
+
const highest = items.reduce((max, item) => {
|
|
37
|
+
const match = new RegExp(`^${prefix}(\\d+)$`).exec(item.id);
|
|
38
|
+
|
|
39
|
+
return match ? Math.max(max, Number(match[1])) : max;
|
|
40
|
+
}, 0);
|
|
41
|
+
|
|
42
|
+
return `${prefix}${String(highest + 1).padStart(3, '0')}`;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export function nextStoryId(prd: StructuredPRD) {
|
|
46
|
+
const highestPresent = prd.userStories.reduce((max, story) => {
|
|
47
|
+
const match = /^US(\d+)$/.exec(story.id);
|
|
48
|
+
|
|
49
|
+
return match ? Math.max(max, Number(match[1])) : max;
|
|
50
|
+
}, 0);
|
|
51
|
+
|
|
52
|
+
const next = Math.max(prd.metadata.lastStoryNumber ?? 0, highestPresent) + 1;
|
|
53
|
+
|
|
54
|
+
prd.metadata.lastStoryNumber = next;
|
|
55
|
+
|
|
56
|
+
return `US${String(next).padStart(3, '0')}`;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function recomputeProgress(prd: StructuredPRD) {
|
|
60
|
+
const total = prd.userStories.length;
|
|
61
|
+
const completed = prd.userStories.filter(
|
|
62
|
+
(story) => story.status === 'completed',
|
|
63
|
+
).length;
|
|
64
|
+
const blocked = prd.userStories.filter(
|
|
65
|
+
(story) => story.status === 'blocked',
|
|
66
|
+
).length;
|
|
67
|
+
|
|
68
|
+
prd.progress = {
|
|
69
|
+
completed,
|
|
70
|
+
blocked,
|
|
71
|
+
total,
|
|
72
|
+
overall: total > 0 ? Math.round((completed / total) * 100) : 0,
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export function appendChangeLog(
|
|
77
|
+
prd: StructuredPRD,
|
|
78
|
+
entry: string,
|
|
79
|
+
today: string,
|
|
80
|
+
) {
|
|
81
|
+
prd.changeLog.push(`${today}: ${entry}`);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function findStory(prd: StructuredPRD, storyId: string): UserStory {
|
|
85
|
+
const story = prd.userStories.find((candidate) => candidate.id === storyId);
|
|
86
|
+
|
|
87
|
+
if (!story) {
|
|
88
|
+
const known = prd.userStories.map((candidate) => candidate.id).join(', ');
|
|
89
|
+
|
|
90
|
+
throw new Error(
|
|
91
|
+
`Story ${storyId} not found.` +
|
|
92
|
+
(known ? ` Known stories: ${known}.` : ' This PRD has no stories yet.'),
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return story;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const USER_STORY_SENTENCE =
|
|
100
|
+
/^As an?\s+(.+?),\s*I want to\s+(.+?)\s+so that\s+(.+)$/i;
|
|
101
|
+
|
|
102
|
+
/** Splits the rendered sentence back into its parts so one can be patched. */
|
|
103
|
+
/** The parts of an "As a X, I want to Y so that Z" story, or undefined. */
|
|
104
|
+
export function splitUserStory(sentence: string) {
|
|
105
|
+
const match = USER_STORY_SENTENCE.exec(sentence.trim());
|
|
106
|
+
|
|
107
|
+
if (!match) {
|
|
108
|
+
return undefined;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
return { userType: match[1]!, action: match[2]!, benefit: match[3]! };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
export function renderUserStory(parts: {
|
|
115
|
+
userType: string;
|
|
116
|
+
action: string;
|
|
117
|
+
benefit: string;
|
|
118
|
+
}) {
|
|
119
|
+
return `As a ${parts.userType}, I want to ${parts.action} so that ${parts.benefit}`;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export function updateStory(
|
|
123
|
+
prd: StructuredPRD,
|
|
124
|
+
input: UpdateUserStoryInput,
|
|
125
|
+
today: string,
|
|
126
|
+
): UpdateUserStoryOutput {
|
|
127
|
+
const story = findStory(prd, input.storyId);
|
|
128
|
+
const updated: string[] = [];
|
|
129
|
+
|
|
130
|
+
const wantsSentenceEdit =
|
|
131
|
+
input.userType !== undefined ||
|
|
132
|
+
input.action !== undefined ||
|
|
133
|
+
input.benefit !== undefined;
|
|
134
|
+
|
|
135
|
+
if (wantsSentenceEdit) {
|
|
136
|
+
const current = splitUserStory(story.userStory);
|
|
137
|
+
|
|
138
|
+
if (
|
|
139
|
+
!current &&
|
|
140
|
+
(input.userType === undefined ||
|
|
141
|
+
input.action === undefined ||
|
|
142
|
+
input.benefit === undefined)
|
|
143
|
+
) {
|
|
144
|
+
throw new Error(
|
|
145
|
+
`Story ${story.id} does not use the "As a X, I want to Y so that Z" form, ` +
|
|
146
|
+
'so its parts cannot be patched individually. Supply userType, action and benefit together.',
|
|
147
|
+
);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
const parts = {
|
|
151
|
+
userType: input.userType ?? current!.userType,
|
|
152
|
+
action: input.action ?? current!.action,
|
|
153
|
+
benefit: input.benefit ?? current!.benefit,
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
story.userStory = renderUserStory(parts);
|
|
157
|
+
updated.push('userStory');
|
|
158
|
+
|
|
159
|
+
// The benefit *is* the business value unless one was set explicitly.
|
|
160
|
+
if (input.benefit !== undefined && input.businessValue === undefined) {
|
|
161
|
+
story.businessValue = input.benefit;
|
|
162
|
+
updated.push('businessValue');
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
if (input.title !== undefined) {
|
|
167
|
+
story.title = input.title;
|
|
168
|
+
updated.push('title');
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
if (input.testSeams !== undefined) {
|
|
172
|
+
story.testSeams = input.testSeams;
|
|
173
|
+
updated.push('testSeams');
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
if (input.designNotes !== undefined) {
|
|
177
|
+
story.designNotes = withoutBlanks(input.designNotes);
|
|
178
|
+
updated.push('designNotes');
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
if (input.securityNotes !== undefined) {
|
|
182
|
+
story.securityNotes = withoutBlanks(input.securityNotes);
|
|
183
|
+
updated.push('securityNotes');
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (input.businessValue !== undefined) {
|
|
187
|
+
story.businessValue = input.businessValue;
|
|
188
|
+
updated.push('businessValue');
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
if (input.acceptanceCriteria !== undefined) {
|
|
192
|
+
story.acceptanceCriteria = input.acceptanceCriteria.filter(
|
|
193
|
+
(entry) => entry.trim().length > 0,
|
|
194
|
+
);
|
|
195
|
+
updated.push('acceptanceCriteria');
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
if (input.priority !== undefined) {
|
|
199
|
+
story.priority = input.priority;
|
|
200
|
+
updated.push('priority');
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
if (input.estimatedComplexity !== undefined) {
|
|
204
|
+
story.estimatedComplexity = input.estimatedComplexity;
|
|
205
|
+
updated.push('estimatedComplexity');
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
if (input.dependencies !== undefined) {
|
|
209
|
+
story.dependencies = validateDependencies(
|
|
210
|
+
prd,
|
|
211
|
+
story.id,
|
|
212
|
+
input.dependencies,
|
|
213
|
+
);
|
|
214
|
+
updated.push('dependencies');
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
if (input.notes !== undefined) {
|
|
218
|
+
story.notes = input.notes;
|
|
219
|
+
updated.push('notes');
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
if (input.attachmentIds !== undefined) {
|
|
223
|
+
story.attachmentIds = validateAttachmentIds(prd, input.attachmentIds);
|
|
224
|
+
updated.push('attachmentIds');
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// In the same write, so a story and its phase never change half-way
|
|
228
|
+
if (input.phaseId !== undefined) {
|
|
229
|
+
assignStoryToPhase(
|
|
230
|
+
prd,
|
|
231
|
+
{ filename: input.filename, storyId: story.id, phaseId: input.phaseId },
|
|
232
|
+
today,
|
|
233
|
+
);
|
|
234
|
+
updated.push('phase');
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
if (updated.length === 0) {
|
|
238
|
+
throw new Error(
|
|
239
|
+
`No fields supplied to update on ${story.id}. Provide at least one of: ` +
|
|
240
|
+
'title, userType, action, benefit, businessValue, acceptanceCriteria, ' +
|
|
241
|
+
'priority, estimatedComplexity, dependencies, notes, testSeams, designNotes, securityNotes, attachmentIds, phaseId.',
|
|
242
|
+
);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
appendChangeLog(prd, `Updated ${story.id} (${updated.join(', ')})`, today);
|
|
246
|
+
|
|
247
|
+
return {
|
|
248
|
+
story_id: story.id,
|
|
249
|
+
title: story.title,
|
|
250
|
+
updated_fields: [...new Set(updated)],
|
|
251
|
+
story: story as unknown as Record<string, unknown>,
|
|
252
|
+
};
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
export function findAttachment(prd: StructuredPRD, attachmentId: string) {
|
|
256
|
+
const attachment = prd.attachments.find(
|
|
257
|
+
(candidate) => candidate.id === attachmentId,
|
|
258
|
+
);
|
|
259
|
+
|
|
260
|
+
if (!attachment) {
|
|
261
|
+
throw new Error(`Attachment "${attachmentId}" not found.`);
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
return attachment;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** Attachment ids must name attachments in the PRD. */
|
|
268
|
+
export function validateAttachmentIds(prd: StructuredPRD, ids: string[]) {
|
|
269
|
+
for (const id of ids) {
|
|
270
|
+
findAttachment(prd, id);
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
return [...new Set(ids)];
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Dependencies must name real stories, never the story itself, and never form
|
|
278
|
+
* a cycle — an unsatisfiable order is worse than no order at all.
|
|
279
|
+
*/
|
|
280
|
+
export function validateDependencies(
|
|
281
|
+
prd: StructuredPRD,
|
|
282
|
+
storyId: string,
|
|
283
|
+
dependencies: string[],
|
|
284
|
+
) {
|
|
285
|
+
const unique = [
|
|
286
|
+
...new Set(dependencies.filter((id) => id.trim().length > 0)),
|
|
287
|
+
];
|
|
288
|
+
|
|
289
|
+
for (const id of unique) {
|
|
290
|
+
if (id === storyId) {
|
|
291
|
+
throw new Error(`Story ${storyId} cannot depend on itself.`);
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
findStory(prd, id);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
const edges = new Map(
|
|
298
|
+
prd.userStories.map((story) => [
|
|
299
|
+
story.id,
|
|
300
|
+
story.id === storyId ? unique : story.dependencies,
|
|
301
|
+
]),
|
|
302
|
+
);
|
|
303
|
+
|
|
304
|
+
const cycle = findCycle(edges, storyId);
|
|
305
|
+
|
|
306
|
+
if (cycle) {
|
|
307
|
+
throw new Error(
|
|
308
|
+
`Dependency cycle: ${cycle.join(' -> ')}. Remove one of these links.`,
|
|
309
|
+
);
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
return unique;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function findCycle(edges: Map<string, string[]>, from: string) {
|
|
316
|
+
const visiting = new Set<string>();
|
|
317
|
+
const done = new Set<string>();
|
|
318
|
+
|
|
319
|
+
const walk = (id: string, trail: string[]): string[] | undefined => {
|
|
320
|
+
if (done.has(id)) return undefined;
|
|
321
|
+
if (visiting.has(id)) return [...trail, id];
|
|
322
|
+
|
|
323
|
+
visiting.add(id);
|
|
324
|
+
|
|
325
|
+
for (const next of edges.get(id) ?? []) {
|
|
326
|
+
const found = walk(next, [...trail, id]);
|
|
327
|
+
|
|
328
|
+
if (found) return found;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
visiting.delete(id);
|
|
332
|
+
done.add(id);
|
|
333
|
+
|
|
334
|
+
return undefined;
|
|
335
|
+
};
|
|
336
|
+
|
|
337
|
+
return walk(from, []);
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
export function deleteStory(
|
|
341
|
+
prd: StructuredPRD,
|
|
342
|
+
storyId: string,
|
|
343
|
+
today: string,
|
|
344
|
+
): DeleteUserStoryOutput {
|
|
345
|
+
const story = findStory(prd, storyId);
|
|
346
|
+
|
|
347
|
+
prd.userStories = prd.userStories.filter(
|
|
348
|
+
(candidate) => candidate.id !== storyId,
|
|
349
|
+
);
|
|
350
|
+
|
|
351
|
+
// Ids are never reissued, but references to the deleted story have to go or
|
|
352
|
+
// the plan describes an ordering against something that no longer exists.
|
|
353
|
+
const dependencyReferencesRemoved: string[] = [];
|
|
354
|
+
|
|
355
|
+
for (const candidate of prd.userStories) {
|
|
356
|
+
if (candidate.dependencies.includes(storyId)) {
|
|
357
|
+
candidate.dependencies = candidate.dependencies.filter(
|
|
358
|
+
(id) => id !== storyId,
|
|
359
|
+
);
|
|
360
|
+
dependencyReferencesRemoved.push(candidate.id);
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
const phasesUpdated: string[] = [];
|
|
365
|
+
|
|
366
|
+
for (const phase of prd.customPhases) {
|
|
367
|
+
if (phase.userStoryIds.includes(storyId)) {
|
|
368
|
+
phase.userStoryIds = phase.userStoryIds.filter((id) => id !== storyId);
|
|
369
|
+
phasesUpdated.push(phase.id);
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
// An edge case linked only to the deleted story would otherwise become
|
|
374
|
+
// PRD-wide, so it is dropped; shared ones lose the link.
|
|
375
|
+
prd.edgeCases = prd.edgeCases.flatMap((edgeCase) => {
|
|
376
|
+
if (!edgeCase.storyIds?.includes(storyId)) {
|
|
377
|
+
return [edgeCase];
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
const storyIds = edgeCase.storyIds.filter((id) => id !== storyId);
|
|
381
|
+
|
|
382
|
+
return storyIds.length > 0 ? [{ ...edgeCase, storyIds }] : [];
|
|
383
|
+
});
|
|
384
|
+
|
|
385
|
+
for (const question of prd.openQuestions) {
|
|
386
|
+
if (question.storyIds?.includes(storyId)) {
|
|
387
|
+
const storyIds = question.storyIds.filter((id) => id !== storyId);
|
|
388
|
+
|
|
389
|
+
if (storyIds.length > 0) {
|
|
390
|
+
question.storyIds = storyIds;
|
|
391
|
+
} else {
|
|
392
|
+
delete question.storyIds;
|
|
393
|
+
}
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
// Decisions about a deleted story are history, not live commitments.
|
|
398
|
+
for (const entry of prd.decisionLog) {
|
|
399
|
+
if (
|
|
400
|
+
entry.topic?.startsWith(`story:${storyId}:`) &&
|
|
401
|
+
entry.status === 'accepted'
|
|
402
|
+
) {
|
|
403
|
+
entry.status = 'superseded';
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
recomputeProgress(prd);
|
|
408
|
+
appendChangeLog(prd, `Deleted ${storyId} (${story.title})`, today);
|
|
409
|
+
|
|
410
|
+
return {
|
|
411
|
+
story_id: storyId,
|
|
412
|
+
title: story.title,
|
|
413
|
+
total_stories: prd.userStories.length,
|
|
414
|
+
progress: prd.progress.overall,
|
|
415
|
+
dependency_references_removed: dependencyReferencesRemoved,
|
|
416
|
+
phases_updated: phasesUpdated,
|
|
417
|
+
};
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
export function createPhase(
|
|
421
|
+
prd: StructuredPRD,
|
|
422
|
+
input: CreateCustomPhaseInput,
|
|
423
|
+
today: string,
|
|
424
|
+
): CreateCustomPhaseOutput {
|
|
425
|
+
const name = input.name.trim();
|
|
426
|
+
|
|
427
|
+
if (
|
|
428
|
+
prd.customPhases.some(
|
|
429
|
+
(phase) => phase.name.toLowerCase() === name.toLowerCase(),
|
|
430
|
+
)
|
|
431
|
+
) {
|
|
432
|
+
throw new Error(`A phase named "${name}" already exists.`);
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
const phase = {
|
|
436
|
+
id: nextId(prd.customPhases, 'PHASE'),
|
|
437
|
+
name,
|
|
438
|
+
description: input.description,
|
|
439
|
+
color: input.color,
|
|
440
|
+
order: prd.customPhases.length,
|
|
441
|
+
userStoryIds: [] as string[],
|
|
442
|
+
};
|
|
443
|
+
|
|
444
|
+
prd.customPhases.push(phase);
|
|
445
|
+
appendChangeLog(prd, `Created phase ${phase.id} (${name})`, today);
|
|
446
|
+
|
|
447
|
+
return {
|
|
448
|
+
phase: {
|
|
449
|
+
id: phase.id,
|
|
450
|
+
name: phase.name,
|
|
451
|
+
description: phase.description,
|
|
452
|
+
color: phase.color,
|
|
453
|
+
order: phase.order,
|
|
454
|
+
user_story_ids: phase.userStoryIds,
|
|
455
|
+
},
|
|
456
|
+
total_phases: prd.customPhases.length,
|
|
457
|
+
};
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
export function assignStoryToPhase(
|
|
461
|
+
prd: StructuredPRD,
|
|
462
|
+
input: AssignStoryToPhaseInput,
|
|
463
|
+
today: string,
|
|
464
|
+
): AssignStoryToPhaseOutput {
|
|
465
|
+
findStory(prd, input.storyId);
|
|
466
|
+
|
|
467
|
+
const target =
|
|
468
|
+
input.phaseId === null
|
|
469
|
+
? undefined
|
|
470
|
+
: prd.customPhases.find((phase) => phase.id === input.phaseId);
|
|
471
|
+
|
|
472
|
+
if (input.phaseId !== null && !target) {
|
|
473
|
+
const known = prd.customPhases.map((phase) => phase.id).join(', ');
|
|
474
|
+
|
|
475
|
+
throw new Error(
|
|
476
|
+
`Phase "${input.phaseId}" not found.` +
|
|
477
|
+
(known ? ` Known phases: ${known}.` : ' This PRD has no phases yet.'),
|
|
478
|
+
);
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
// A story belongs to at most one phase, so clear it out of the others first.
|
|
482
|
+
const previous = prd.customPhases.find((phase) =>
|
|
483
|
+
phase.userStoryIds.includes(input.storyId),
|
|
484
|
+
);
|
|
485
|
+
|
|
486
|
+
for (const phase of prd.customPhases) {
|
|
487
|
+
phase.userStoryIds = phase.userStoryIds.filter(
|
|
488
|
+
(id) => id !== input.storyId,
|
|
489
|
+
);
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
target?.userStoryIds.push(input.storyId);
|
|
493
|
+
|
|
494
|
+
appendChangeLog(
|
|
495
|
+
prd,
|
|
496
|
+
target
|
|
497
|
+
? `Assigned ${input.storyId} to ${target.id} (${target.name})`
|
|
498
|
+
: `Removed ${input.storyId} from all phases`,
|
|
499
|
+
today,
|
|
500
|
+
);
|
|
501
|
+
|
|
502
|
+
return {
|
|
503
|
+
story_id: input.storyId,
|
|
504
|
+
phase_id: target?.id ?? null,
|
|
505
|
+
phase_name: target?.name ?? null,
|
|
506
|
+
moved_from: previous && previous.id !== target?.id ? previous.id : null,
|
|
507
|
+
};
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
// Workflow ------------------------------------------------------------------
|
|
511
|
+
|
|
512
|
+
/** Statuses that mean work on the story has started or finished. */
|
|
513
|
+
const WORK_STATUSES: StoryStatus[] = ['in_progress', 'review', 'completed'];
|
|
514
|
+
|
|
515
|
+
const PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2, P3: 3 } as const;
|
|
516
|
+
|
|
517
|
+
/** Dependencies of `story` that are not completed yet. */
|
|
518
|
+
export function incompleteDependencies(prd: StructuredPRD, story: UserStory) {
|
|
519
|
+
return story.dependencies.filter((id) => {
|
|
520
|
+
const dependency = prd.userStories.find((candidate) => candidate.id === id);
|
|
521
|
+
|
|
522
|
+
return dependency?.status !== 'completed';
|
|
523
|
+
});
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* A story cannot be worked on, reviewed or completed before the stories it
|
|
528
|
+
* depends on are completed. `not_started`, `research` and `blocked` stay
|
|
529
|
+
* available so a story can still be planned or parked.
|
|
530
|
+
*/
|
|
531
|
+
export function assertCanEnterStatus(
|
|
532
|
+
prd: StructuredPRD,
|
|
533
|
+
story: UserStory,
|
|
534
|
+
status: StoryStatus,
|
|
535
|
+
) {
|
|
536
|
+
if (!WORK_STATUSES.includes(status)) {
|
|
537
|
+
return;
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
const waitingOn = incompleteDependencies(prd, story);
|
|
541
|
+
|
|
542
|
+
if (waitingOn.length > 0) {
|
|
543
|
+
throw new Error(
|
|
544
|
+
`Cannot move ${story.id} to ${status}: it depends on ${waitingOn.join(', ')}, which ${waitingOn.length === 1 ? 'is' : 'are'} not completed yet.`,
|
|
545
|
+
);
|
|
546
|
+
}
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
/** Position of the story's phase; stories without a phase come last. */
|
|
550
|
+
function phaseRank(prd: StructuredPRD, storyId: string) {
|
|
551
|
+
const phase = prd.customPhases.find((candidate) =>
|
|
552
|
+
candidate.userStoryIds.includes(storyId),
|
|
553
|
+
);
|
|
554
|
+
|
|
555
|
+
return phase ? phase.order : Number.MAX_SAFE_INTEGER;
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/**
|
|
559
|
+
* The next story to start: not started, every dependency completed, ordered
|
|
560
|
+
* by phase, then priority, then position in the PRD.
|
|
561
|
+
*/
|
|
562
|
+
export function pickNextStory(prd: StructuredPRD) {
|
|
563
|
+
const notStarted = prd.userStories.filter(
|
|
564
|
+
(story) => story.status === 'not_started',
|
|
565
|
+
);
|
|
566
|
+
|
|
567
|
+
const ready = notStarted
|
|
568
|
+
.filter((story) => incompleteDependencies(prd, story).length === 0)
|
|
569
|
+
.sort(
|
|
570
|
+
(a, b) =>
|
|
571
|
+
phaseRank(prd, a.id) - phaseRank(prd, b.id) ||
|
|
572
|
+
PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority] ||
|
|
573
|
+
prd.userStories.indexOf(a) - prd.userStories.indexOf(b),
|
|
574
|
+
);
|
|
575
|
+
|
|
576
|
+
const waiting = notStarted
|
|
577
|
+
.map((story) => ({
|
|
578
|
+
id: story.id,
|
|
579
|
+
title: story.title,
|
|
580
|
+
waiting_on: incompleteDependencies(prd, story),
|
|
581
|
+
}))
|
|
582
|
+
.filter((entry) => entry.waiting_on.length > 0);
|
|
583
|
+
|
|
584
|
+
return {
|
|
585
|
+
story: ready[0] ?? null,
|
|
586
|
+
ready_count: ready.length,
|
|
587
|
+
in_progress: prd.userStories
|
|
588
|
+
.filter((story) => story.status === 'in_progress')
|
|
589
|
+
.map((story) => story.id),
|
|
590
|
+
waiting,
|
|
591
|
+
};
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
/**
|
|
595
|
+
* Everything an agent needs to work on one story without loading the whole
|
|
596
|
+
* PRD: the story, the scope boundaries, its dependencies with their hand-off
|
|
597
|
+
* logs, and the log of the most recently completed story.
|
|
598
|
+
*/
|
|
599
|
+
/** `filename` is the PRD's file name, used to give attachment paths. */
|
|
600
|
+
export function buildStoryContext(
|
|
601
|
+
prd: StructuredPRD,
|
|
602
|
+
storyId: string,
|
|
603
|
+
filename: string,
|
|
604
|
+
) {
|
|
605
|
+
const story = findStory(prd, storyId);
|
|
606
|
+
const linked = new Set(story.attachmentIds ?? []);
|
|
607
|
+
const phase =
|
|
608
|
+
prd.customPhases.find((candidate) =>
|
|
609
|
+
candidate.userStoryIds.includes(story.id),
|
|
610
|
+
) ?? null;
|
|
611
|
+
|
|
612
|
+
const lastCompleted =
|
|
613
|
+
prd.userStories
|
|
614
|
+
.filter((candidate) => candidate.status === 'completed')
|
|
615
|
+
.filter((candidate) => candidate.id !== story.id)
|
|
616
|
+
.sort((a, b) => (a.completedAt ?? '').localeCompare(b.completedAt ?? ''))
|
|
617
|
+
.at(-1) ?? null;
|
|
618
|
+
|
|
619
|
+
return {
|
|
620
|
+
prd: {
|
|
621
|
+
title: prd.introduction.title,
|
|
622
|
+
overview: prd.introduction.overview,
|
|
623
|
+
non_goals: prd.nonGoals,
|
|
624
|
+
out_of_scope: prd.outOfScope,
|
|
625
|
+
global_acceptance_criteria: prd.acceptanceCriteria.global,
|
|
626
|
+
attachments: resolveAttachments(filename, prd.attachments),
|
|
627
|
+
},
|
|
628
|
+
story,
|
|
629
|
+
attachments: resolveAttachments(
|
|
630
|
+
filename,
|
|
631
|
+
prd.attachments.filter((attachment) => linked.has(attachment.id)),
|
|
632
|
+
),
|
|
633
|
+
phase: phase ? { id: phase.id, name: phase.name } : null,
|
|
634
|
+
edge_cases: edgeCasesForStory(prd, story.id),
|
|
635
|
+
open_questions: prd.openQuestions.filter((question) =>
|
|
636
|
+
question.storyIds?.includes(story.id),
|
|
637
|
+
),
|
|
638
|
+
security: {
|
|
639
|
+
permissions: prd.technicalContracts.permissions,
|
|
640
|
+
compliance: prd.technicalRequirements.complianceRequirements,
|
|
641
|
+
considerations: prd.securityConsiderations,
|
|
642
|
+
story_notes: story.securityNotes ?? [],
|
|
643
|
+
},
|
|
644
|
+
not_applicable: prd.notApplicable as Record<string, string>,
|
|
645
|
+
design: {
|
|
646
|
+
guidance: prd.designGuidance,
|
|
647
|
+
story_notes: story.designNotes ?? [],
|
|
648
|
+
decisions: designDecisions(prd).map(({ id, decision, rationale }) => ({
|
|
649
|
+
id,
|
|
650
|
+
decision,
|
|
651
|
+
rationale,
|
|
652
|
+
})),
|
|
653
|
+
},
|
|
654
|
+
dependencies: story.dependencies.map((id) => {
|
|
655
|
+
const dependency = prd.userStories.find(
|
|
656
|
+
(candidate) => candidate.id === id,
|
|
657
|
+
);
|
|
658
|
+
|
|
659
|
+
return {
|
|
660
|
+
id,
|
|
661
|
+
title: dependency?.title ?? null,
|
|
662
|
+
status: dependency?.status ?? null,
|
|
663
|
+
log: dependency?.log ?? [],
|
|
664
|
+
};
|
|
665
|
+
}),
|
|
666
|
+
previous_story: lastCompleted
|
|
667
|
+
? {
|
|
668
|
+
id: lastCompleted.id,
|
|
669
|
+
title: lastCompleted.title,
|
|
670
|
+
log: lastCompleted.log ?? [],
|
|
671
|
+
}
|
|
672
|
+
: null,
|
|
673
|
+
};
|
|
674
|
+
}
|
|
675
|
+
|
|
676
|
+
export function appendStoryLog(
|
|
677
|
+
prd: StructuredPRD,
|
|
678
|
+
storyId: string,
|
|
679
|
+
entry: StoryLogEntry,
|
|
680
|
+
) {
|
|
681
|
+
const story = findStory(prd, storyId);
|
|
682
|
+
|
|
683
|
+
story.log = [...(story.log ?? []), entry];
|
|
684
|
+
|
|
685
|
+
return { story_id: story.id, entries: story.log.length };
|
|
686
|
+
}
|
|
687
|
+
|
|
688
|
+
function withoutBlanks(entries: string[]) {
|
|
689
|
+
return entries.map((entry) => entry.trim()).filter(Boolean);
|
|
690
|
+
}
|