@makerkit/prd 0.0.4 → 0.0.5
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 +78 -0
- package/.turbo/turbo-test.log +19 -0
- package/.turbo/turbo-typecheck.log +6 -0
- package/README.md +7 -1
- package/dist/README.md +71 -0
- package/dist/attachment-paths-BAhRGiib.js +112 -0
- package/dist/attachment-paths-C-SWgoSx.mjs +77 -0
- package/dist/index.d.ts +81 -0
- package/{index.js → dist/index.js} +155 -562
- package/{index.mjs → dist/index.mjs} +87 -497
- package/{mcp.d.ts → dist/mcp.d.ts} +2 -4
- package/{mcp.js → dist/mcp.js} +24 -24
- package/{mcp.mjs → dist/mcp.mjs} +24 -24
- package/{node.d.ts → dist/node.d.ts} +4 -4
- package/{node.js → dist/node.js} +28 -4
- package/{node.mjs → dist/node.mjs} +30 -6
- package/dist/operations.d.ts +141 -0
- package/dist/operations.js +22 -0
- package/dist/operations.mjs +1 -0
- package/dist/package.json +54 -0
- package/dist/prd-operations-BvFxo9bg.mjs +459 -0
- package/dist/prd-operations-CcahfbOy.js +584 -0
- package/dist/prd.service-CTwKZV-3.d.ts +114 -0
- package/{prompts-oI_6dxvx.js → dist/prompts-1qhax_dj.js} +113 -164
- package/{prompts-CPlFVutB.mjs → dist/prompts-BlsYD0gf.mjs} +96 -129
- package/{prd.service-CV0-aQHk.d.ts → dist/schema-BwTnt0B9.d.ts} +424 -336
- package/package.json +26 -2
- package/src/__tests__/agent-workflow.test.ts +417 -0
- package/src/__tests__/attachments.test.ts +505 -0
- package/src/__tests__/node.test.ts +199 -0
- package/src/__tests__/plan-check.test.ts +390 -0
- package/src/__tests__/planning.test.ts +1137 -0
- package/src/__tests__/prd-operations.test.ts +571 -0
- package/src/__tests__/prd.service.test.ts +652 -0
- package/src/__tests__/prd.tool.test.ts +282 -0
- package/src/__tests__/templates.test.ts +145 -0
- package/src/applicability.ts +73 -0
- package/src/attachment-paths.ts +83 -0
- package/src/attachments.ts +166 -0
- package/src/edge-cases.ts +61 -0
- package/src/index.ts +33 -0
- package/src/markdown.ts +297 -0
- package/src/mcp/index.ts +875 -0
- package/src/mcp/tool-response.ts +85 -0
- package/src/node.ts +184 -0
- package/src/open-questions.ts +98 -0
- package/src/plan-check.ts +385 -0
- package/src/planning-operations.ts +524 -0
- package/src/prd-operations.ts +769 -0
- package/src/prd.service.ts +1165 -0
- package/src/prompts.ts +161 -0
- package/src/safe-file-name.ts +42 -0
- package/src/schema.ts +1090 -0
- package/src/templates.ts +173 -0
- package/src/testing/fake-mcp-server.ts +81 -0
- package/src/types.ts +381 -0
- package/tsconfig.json +23 -0
- package/tsconfig.lib.json +8 -0
- package/tsconfig.spec.json +7 -0
- package/tsdown.config.mts +12 -0
- package/vitest.config.mts +8 -0
- package/index.d.ts +0 -233
- /package/{LICENSE → dist/LICENSE} +0 -0
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@makerkit/prd",
|
|
3
|
+
"version": "0.0.5",
|
|
4
|
+
"description": "Structured PRDs as JSON files: the format, a service to manage them, and MCP tools so coding agents can read and update them.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"ai-agents",
|
|
7
|
+
"claude-code",
|
|
8
|
+
"codex",
|
|
9
|
+
"mcp",
|
|
10
|
+
"prd",
|
|
11
|
+
"product-requirements"
|
|
12
|
+
],
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "https://github.com/makerkit/makerkit",
|
|
17
|
+
"directory": "packages/prd"
|
|
18
|
+
},
|
|
19
|
+
"main": "./index.js",
|
|
20
|
+
"exports": {
|
|
21
|
+
".": {
|
|
22
|
+
"types": "./index.d.ts",
|
|
23
|
+
"import": "./index.mjs",
|
|
24
|
+
"require": "./index.js"
|
|
25
|
+
},
|
|
26
|
+
"./node": {
|
|
27
|
+
"types": "./node.d.ts",
|
|
28
|
+
"import": "./node.mjs",
|
|
29
|
+
"require": "./node.js"
|
|
30
|
+
},
|
|
31
|
+
"./operations": {
|
|
32
|
+
"types": "./operations.d.ts",
|
|
33
|
+
"import": "./operations.mjs",
|
|
34
|
+
"require": "./operations.js"
|
|
35
|
+
},
|
|
36
|
+
"./mcp": {
|
|
37
|
+
"types": "./mcp.d.ts",
|
|
38
|
+
"import": "./mcp.mjs",
|
|
39
|
+
"require": "./mcp.js"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@makerkit/repo-checks": "^0.0.2",
|
|
44
|
+
"zod": "^3.25.0 || ^4.0.0"
|
|
45
|
+
},
|
|
46
|
+
"peerDependencies": {
|
|
47
|
+
"@modelcontextprotocol/sdk": "^1.32.0"
|
|
48
|
+
},
|
|
49
|
+
"peerDependenciesMeta": {
|
|
50
|
+
"@modelcontextprotocol/sdk": {
|
|
51
|
+
"optional": true
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
import { i as resolveAttachments } from "./attachment-paths-C-SWgoSx.mjs";
|
|
2
|
+
// src/edge-cases.ts
|
|
3
|
+
/**
|
|
4
|
+
* Edge cases as stored, with hand-edited entries that would break readers
|
|
5
|
+
* dropped: each needs a string id and case; status defaults to "open".
|
|
6
|
+
*/
|
|
7
|
+
function normalizeEdgeCases(value) {
|
|
8
|
+
if (!Array.isArray(value)) return [];
|
|
9
|
+
return value.flatMap((entry) => {
|
|
10
|
+
if (typeof entry !== "object" || entry === null) return [];
|
|
11
|
+
const { id, case: caseText, expectedBehavior, status, storyIds } = entry;
|
|
12
|
+
if (typeof id !== "string" || typeof caseText !== "string" || !caseText) return [];
|
|
13
|
+
const ids = Array.isArray(storyIds) ? storyIds.filter((storyId) => typeof storyId === "string") : [];
|
|
14
|
+
return [{
|
|
15
|
+
id,
|
|
16
|
+
case: caseText,
|
|
17
|
+
expectedBehavior: typeof expectedBehavior === "string" ? expectedBehavior : "",
|
|
18
|
+
status: status === "decided" ? "decided" : "open",
|
|
19
|
+
...ids.length > 0 ? { storyIds: ids } : {}
|
|
20
|
+
}];
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
/** The edge cases that apply to a story: those linked to it, and those linked to no story. */
|
|
24
|
+
function edgeCasesForStory(prd, storyId) {
|
|
25
|
+
return prd.edgeCases.filter((edgeCase) => !edgeCase.storyIds?.length || edgeCase.storyIds.includes(storyId));
|
|
26
|
+
}
|
|
27
|
+
/** Accepted decisions whose topic starts with `design`, e.g. `design:navigation`. */
|
|
28
|
+
function designDecisions(prd) {
|
|
29
|
+
return prd.decisionLog.filter((entry) => entry.status === "accepted" && entry.topic?.startsWith("design"));
|
|
30
|
+
}
|
|
31
|
+
// src/prd-operations.ts
|
|
32
|
+
/**
|
|
33
|
+
* Pure PRD transforms.
|
|
34
|
+
*
|
|
35
|
+
* Everything here takes an already-loaded `StructuredPRD`, mutates it, and
|
|
36
|
+
* returns the tool payload. No filesystem, no clock, no deps — the service is
|
|
37
|
+
* left with load → transform → save, and every rule below is unit-testable
|
|
38
|
+
* without a harness.
|
|
39
|
+
*/
|
|
40
|
+
/**
|
|
41
|
+
* Issues the next story id and advances the high-water mark.
|
|
42
|
+
*
|
|
43
|
+
* Deliberately not `max(existing) + 1`: delete the highest-numbered story and
|
|
44
|
+
* that hands its id straight to the next one, so a story id quoted in a commit
|
|
45
|
+
* or a decision-log topic would silently come to mean something else.
|
|
46
|
+
*/
|
|
47
|
+
function nextId(items, prefix) {
|
|
48
|
+
const highest = items.reduce((max, item) => {
|
|
49
|
+
const match = new RegExp(`^${prefix}(\\d+)$`).exec(item.id);
|
|
50
|
+
return match ? Math.max(max, Number(match[1])) : max;
|
|
51
|
+
}, 0);
|
|
52
|
+
return `${prefix}${String(highest + 1).padStart(3, "0")}`;
|
|
53
|
+
}
|
|
54
|
+
function nextStoryId(prd) {
|
|
55
|
+
const highestPresent = prd.userStories.reduce((max, story) => {
|
|
56
|
+
const match = /^US(\d+)$/.exec(story.id);
|
|
57
|
+
return match ? Math.max(max, Number(match[1])) : max;
|
|
58
|
+
}, 0);
|
|
59
|
+
const next = Math.max(prd.metadata.lastStoryNumber ?? 0, highestPresent) + 1;
|
|
60
|
+
prd.metadata.lastStoryNumber = next;
|
|
61
|
+
return `US${String(next).padStart(3, "0")}`;
|
|
62
|
+
}
|
|
63
|
+
function recomputeProgress(prd) {
|
|
64
|
+
const total = prd.userStories.length;
|
|
65
|
+
const completed = prd.userStories.filter((story) => story.status === "completed").length;
|
|
66
|
+
prd.progress = {
|
|
67
|
+
completed,
|
|
68
|
+
blocked: prd.userStories.filter((story) => story.status === "blocked").length,
|
|
69
|
+
total,
|
|
70
|
+
overall: total > 0 ? Math.round(completed / total * 100) : 0
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
function appendChangeLog(prd, entry, today) {
|
|
74
|
+
prd.changeLog.push(`${today}: ${entry}`);
|
|
75
|
+
}
|
|
76
|
+
function findStory(prd, storyId) {
|
|
77
|
+
const story = prd.userStories.find((candidate) => candidate.id === storyId);
|
|
78
|
+
if (!story) {
|
|
79
|
+
const known = prd.userStories.map((candidate) => candidate.id).join(", ");
|
|
80
|
+
throw new Error(`Story ${storyId} not found.` + (known ? ` Known stories: ${known}.` : " This PRD has no stories yet."));
|
|
81
|
+
}
|
|
82
|
+
return story;
|
|
83
|
+
}
|
|
84
|
+
const USER_STORY_SENTENCE = /^As an?\s+(.+?),\s*I want to\s+(.+?)\s+so that\s+(.+)$/i;
|
|
85
|
+
/** Splits the rendered sentence back into its parts so one can be patched. */
|
|
86
|
+
/** The parts of an "As a X, I want to Y so that Z" story, or undefined. */
|
|
87
|
+
function splitUserStory(sentence) {
|
|
88
|
+
const match = USER_STORY_SENTENCE.exec(sentence.trim());
|
|
89
|
+
if (!match) return;
|
|
90
|
+
return {
|
|
91
|
+
userType: match[1],
|
|
92
|
+
action: match[2],
|
|
93
|
+
benefit: match[3]
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
function renderUserStory(parts) {
|
|
97
|
+
return `As a ${parts.userType}, I want to ${parts.action} so that ${parts.benefit}`;
|
|
98
|
+
}
|
|
99
|
+
function updateStory(prd, input, today) {
|
|
100
|
+
const story = findStory(prd, input.storyId);
|
|
101
|
+
const updated = [];
|
|
102
|
+
if (input.userType !== void 0 || input.action !== void 0 || input.benefit !== void 0) {
|
|
103
|
+
const current = splitUserStory(story.userStory);
|
|
104
|
+
if (!current && (input.userType === void 0 || input.action === void 0 || input.benefit === void 0)) throw new Error(`Story ${story.id} does not use the "As a X, I want to Y so that Z" form, so its parts cannot be patched individually. Supply userType, action and benefit together.`);
|
|
105
|
+
story.userStory = renderUserStory({
|
|
106
|
+
userType: input.userType ?? current.userType,
|
|
107
|
+
action: input.action ?? current.action,
|
|
108
|
+
benefit: input.benefit ?? current.benefit
|
|
109
|
+
});
|
|
110
|
+
updated.push("userStory");
|
|
111
|
+
if (input.benefit !== void 0 && input.businessValue === void 0) {
|
|
112
|
+
story.businessValue = input.benefit;
|
|
113
|
+
updated.push("businessValue");
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
if (input.title !== void 0) {
|
|
117
|
+
story.title = input.title;
|
|
118
|
+
updated.push("title");
|
|
119
|
+
}
|
|
120
|
+
if (input.testSeams !== void 0) {
|
|
121
|
+
story.testSeams = input.testSeams;
|
|
122
|
+
updated.push("testSeams");
|
|
123
|
+
}
|
|
124
|
+
if (input.designNotes !== void 0) {
|
|
125
|
+
story.designNotes = withoutBlanks(input.designNotes);
|
|
126
|
+
updated.push("designNotes");
|
|
127
|
+
}
|
|
128
|
+
if (input.securityNotes !== void 0) {
|
|
129
|
+
story.securityNotes = withoutBlanks(input.securityNotes);
|
|
130
|
+
updated.push("securityNotes");
|
|
131
|
+
}
|
|
132
|
+
if (input.businessValue !== void 0) {
|
|
133
|
+
story.businessValue = input.businessValue;
|
|
134
|
+
updated.push("businessValue");
|
|
135
|
+
}
|
|
136
|
+
if (input.acceptanceCriteria !== void 0) {
|
|
137
|
+
story.acceptanceCriteria = input.acceptanceCriteria.filter((entry) => entry.trim().length > 0);
|
|
138
|
+
updated.push("acceptanceCriteria");
|
|
139
|
+
if (input.proofs === void 0 && story.proofs?.length) {
|
|
140
|
+
const kept = story.proofs.filter((proof) => story.acceptanceCriteria.includes(proof.criterion));
|
|
141
|
+
if (kept.length !== story.proofs.length) {
|
|
142
|
+
story.proofs = kept;
|
|
143
|
+
updated.push("proofs");
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
if (input.proofs !== void 0) {
|
|
148
|
+
story.proofs = validateProofs(story.acceptanceCriteria, input.proofs);
|
|
149
|
+
updated.push("proofs");
|
|
150
|
+
}
|
|
151
|
+
if (input.priority !== void 0) {
|
|
152
|
+
story.priority = input.priority;
|
|
153
|
+
updated.push("priority");
|
|
154
|
+
}
|
|
155
|
+
if (input.estimatedComplexity !== void 0) {
|
|
156
|
+
story.estimatedComplexity = input.estimatedComplexity;
|
|
157
|
+
updated.push("estimatedComplexity");
|
|
158
|
+
}
|
|
159
|
+
if (input.dependencies !== void 0) {
|
|
160
|
+
story.dependencies = validateDependencies(prd, story.id, input.dependencies);
|
|
161
|
+
updated.push("dependencies");
|
|
162
|
+
}
|
|
163
|
+
if (input.notes !== void 0) {
|
|
164
|
+
story.notes = input.notes;
|
|
165
|
+
updated.push("notes");
|
|
166
|
+
}
|
|
167
|
+
if (input.attachmentIds !== void 0) {
|
|
168
|
+
story.attachmentIds = validateAttachmentIds(prd, input.attachmentIds);
|
|
169
|
+
updated.push("attachmentIds");
|
|
170
|
+
}
|
|
171
|
+
if (input.phaseId !== void 0) {
|
|
172
|
+
assignStoryToPhase(prd, {
|
|
173
|
+
filename: input.filename,
|
|
174
|
+
storyId: story.id,
|
|
175
|
+
phaseId: input.phaseId
|
|
176
|
+
}, today);
|
|
177
|
+
updated.push("phase");
|
|
178
|
+
}
|
|
179
|
+
if (updated.length === 0) throw new Error(`No fields supplied to update on ${story.id}. Provide at least one of: title, userType, action, benefit, businessValue, acceptanceCriteria, priority, estimatedComplexity, dependencies, notes, testSeams, proofs, designNotes, securityNotes, attachmentIds, phaseId.`);
|
|
180
|
+
appendChangeLog(prd, `Updated ${story.id} (${updated.join(", ")})`, today);
|
|
181
|
+
return {
|
|
182
|
+
story_id: story.id,
|
|
183
|
+
title: story.title,
|
|
184
|
+
updated_fields: [...new Set(updated)],
|
|
185
|
+
story
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
function findAttachment(prd, attachmentId) {
|
|
189
|
+
const attachment = prd.attachments.find((candidate) => candidate.id === attachmentId);
|
|
190
|
+
if (!attachment) throw new Error(`Attachment "${attachmentId}" not found.`);
|
|
191
|
+
return attachment;
|
|
192
|
+
}
|
|
193
|
+
/** Attachment ids must name attachments in the PRD. */
|
|
194
|
+
function validateAttachmentIds(prd, ids) {
|
|
195
|
+
for (const id of ids) findAttachment(prd, id);
|
|
196
|
+
return [...new Set(ids)];
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Each proof must name one of the story's criteria, at most once, and a proof
|
|
200
|
+
* no test makes must say why — the reason is what a reviewer judges.
|
|
201
|
+
*/
|
|
202
|
+
function validateProofs(criteria, proofs) {
|
|
203
|
+
const seen = /* @__PURE__ */ new Set();
|
|
204
|
+
return proofs.map((proof) => {
|
|
205
|
+
const criterion = criteria.find((candidate) => candidate.trim() === proof.criterion.trim());
|
|
206
|
+
if (criterion === void 0) throw new Error(`Proof names a criterion the story does not have: "${proof.criterion}". Copy the criterion exactly.`);
|
|
207
|
+
if (seen.has(criterion)) throw new Error(`Criterion "${criterion}" has more than one proof.`);
|
|
208
|
+
seen.add(criterion);
|
|
209
|
+
const reason = proof.reason?.trim();
|
|
210
|
+
if ((proof.kind === "manual" || proof.kind === "post-deploy") && !reason) throw new Error(`A ${proof.kind} proof needs a reason: why no test can prove "${criterion}".`);
|
|
211
|
+
const rubric = (proof.rubric ?? []).map((point) => point.trim()).filter(Boolean);
|
|
212
|
+
if (proof.kind === "judge" && rubric.length === 0) throw new Error(`A judge proof needs a rubric: what the reviewer scores "${criterion}" against.`);
|
|
213
|
+
const seam = proof.seam?.trim();
|
|
214
|
+
const fallback = proof.fallback?.trim();
|
|
215
|
+
return {
|
|
216
|
+
criterion,
|
|
217
|
+
kind: proof.kind,
|
|
218
|
+
...seam ? { seam } : {},
|
|
219
|
+
...reason ? { reason } : {},
|
|
220
|
+
...fallback ? { fallback } : {},
|
|
221
|
+
...rubric.length > 0 ? { rubric } : {}
|
|
222
|
+
};
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Dependencies must name real stories, never the story itself, and never form
|
|
227
|
+
* a cycle — an unsatisfiable order is worse than no order at all.
|
|
228
|
+
*/
|
|
229
|
+
function validateDependencies(prd, storyId, dependencies) {
|
|
230
|
+
const unique = [...new Set(dependencies.filter((id) => id.trim().length > 0))];
|
|
231
|
+
for (const id of unique) {
|
|
232
|
+
if (id === storyId) throw new Error(`Story ${storyId} cannot depend on itself.`);
|
|
233
|
+
findStory(prd, id);
|
|
234
|
+
}
|
|
235
|
+
const cycle = findCycle(new Map(prd.userStories.map((story) => [story.id, story.id === storyId ? unique : story.dependencies])), storyId);
|
|
236
|
+
if (cycle) throw new Error(`Dependency cycle: ${cycle.join(" -> ")}. Remove one of these links.`);
|
|
237
|
+
return unique;
|
|
238
|
+
}
|
|
239
|
+
function findCycle(edges, from) {
|
|
240
|
+
const visiting = /* @__PURE__ */ new Set();
|
|
241
|
+
const done = /* @__PURE__ */ new Set();
|
|
242
|
+
const walk = (id, trail) => {
|
|
243
|
+
if (done.has(id)) return void 0;
|
|
244
|
+
if (visiting.has(id)) return [...trail, id];
|
|
245
|
+
visiting.add(id);
|
|
246
|
+
for (const next of edges.get(id) ?? []) {
|
|
247
|
+
const found = walk(next, [...trail, id]);
|
|
248
|
+
if (found) return found;
|
|
249
|
+
}
|
|
250
|
+
visiting.delete(id);
|
|
251
|
+
done.add(id);
|
|
252
|
+
};
|
|
253
|
+
return walk(from, []);
|
|
254
|
+
}
|
|
255
|
+
function deleteStory(prd, storyId, today) {
|
|
256
|
+
const story = findStory(prd, storyId);
|
|
257
|
+
prd.userStories = prd.userStories.filter((candidate) => candidate.id !== storyId);
|
|
258
|
+
const dependencyReferencesRemoved = [];
|
|
259
|
+
for (const candidate of prd.userStories) if (candidate.dependencies.includes(storyId)) {
|
|
260
|
+
candidate.dependencies = candidate.dependencies.filter((id) => id !== storyId);
|
|
261
|
+
dependencyReferencesRemoved.push(candidate.id);
|
|
262
|
+
}
|
|
263
|
+
const phasesUpdated = [];
|
|
264
|
+
for (const phase of prd.customPhases) if (phase.userStoryIds.includes(storyId)) {
|
|
265
|
+
phase.userStoryIds = phase.userStoryIds.filter((id) => id !== storyId);
|
|
266
|
+
phasesUpdated.push(phase.id);
|
|
267
|
+
}
|
|
268
|
+
prd.edgeCases = prd.edgeCases.flatMap((edgeCase) => {
|
|
269
|
+
if (!edgeCase.storyIds?.includes(storyId)) return [edgeCase];
|
|
270
|
+
const storyIds = edgeCase.storyIds.filter((id) => id !== storyId);
|
|
271
|
+
return storyIds.length > 0 ? [{
|
|
272
|
+
...edgeCase,
|
|
273
|
+
storyIds
|
|
274
|
+
}] : [];
|
|
275
|
+
});
|
|
276
|
+
for (const question of prd.openQuestions) if (question.storyIds?.includes(storyId)) {
|
|
277
|
+
const storyIds = question.storyIds.filter((id) => id !== storyId);
|
|
278
|
+
if (storyIds.length > 0) question.storyIds = storyIds;
|
|
279
|
+
else delete question.storyIds;
|
|
280
|
+
}
|
|
281
|
+
for (const entry of prd.decisionLog) if (entry.topic?.startsWith(`story:${storyId}:`) && entry.status === "accepted") entry.status = "superseded";
|
|
282
|
+
recomputeProgress(prd);
|
|
283
|
+
appendChangeLog(prd, `Deleted ${storyId} (${story.title})`, today);
|
|
284
|
+
return {
|
|
285
|
+
story_id: storyId,
|
|
286
|
+
title: story.title,
|
|
287
|
+
total_stories: prd.userStories.length,
|
|
288
|
+
progress: prd.progress.overall,
|
|
289
|
+
dependency_references_removed: dependencyReferencesRemoved,
|
|
290
|
+
phases_updated: phasesUpdated
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
function createPhase(prd, input, today) {
|
|
294
|
+
const name = input.name.trim();
|
|
295
|
+
if (prd.customPhases.some((phase) => phase.name.toLowerCase() === name.toLowerCase())) throw new Error(`A phase named "${name}" already exists.`);
|
|
296
|
+
const phase = {
|
|
297
|
+
id: nextId(prd.customPhases, "PHASE"),
|
|
298
|
+
name,
|
|
299
|
+
description: input.description,
|
|
300
|
+
color: input.color,
|
|
301
|
+
order: prd.customPhases.length,
|
|
302
|
+
userStoryIds: []
|
|
303
|
+
};
|
|
304
|
+
prd.customPhases.push(phase);
|
|
305
|
+
appendChangeLog(prd, `Created phase ${phase.id} (${name})`, today);
|
|
306
|
+
return {
|
|
307
|
+
phase: {
|
|
308
|
+
id: phase.id,
|
|
309
|
+
name: phase.name,
|
|
310
|
+
description: phase.description,
|
|
311
|
+
color: phase.color,
|
|
312
|
+
order: phase.order,
|
|
313
|
+
user_story_ids: phase.userStoryIds
|
|
314
|
+
},
|
|
315
|
+
total_phases: prd.customPhases.length
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
function assignStoryToPhase(prd, input, today) {
|
|
319
|
+
findStory(prd, input.storyId);
|
|
320
|
+
const target = input.phaseId === null ? void 0 : prd.customPhases.find((phase) => phase.id === input.phaseId);
|
|
321
|
+
if (input.phaseId !== null && !target) {
|
|
322
|
+
const known = prd.customPhases.map((phase) => phase.id).join(", ");
|
|
323
|
+
throw new Error(`Phase "${input.phaseId}" not found.` + (known ? ` Known phases: ${known}.` : " This PRD has no phases yet."));
|
|
324
|
+
}
|
|
325
|
+
const previous = prd.customPhases.find((phase) => phase.userStoryIds.includes(input.storyId));
|
|
326
|
+
for (const phase of prd.customPhases) phase.userStoryIds = phase.userStoryIds.filter((id) => id !== input.storyId);
|
|
327
|
+
target?.userStoryIds.push(input.storyId);
|
|
328
|
+
appendChangeLog(prd, target ? `Assigned ${input.storyId} to ${target.id} (${target.name})` : `Removed ${input.storyId} from all phases`, today);
|
|
329
|
+
return {
|
|
330
|
+
story_id: input.storyId,
|
|
331
|
+
phase_id: target?.id ?? null,
|
|
332
|
+
phase_name: target?.name ?? null,
|
|
333
|
+
moved_from: previous && previous.id !== target?.id ? previous.id : null
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
/** Statuses that mean work on the story has started or finished. */
|
|
337
|
+
const WORK_STATUSES = [
|
|
338
|
+
"in_progress",
|
|
339
|
+
"review",
|
|
340
|
+
"completed"
|
|
341
|
+
];
|
|
342
|
+
const PRIORITY_ORDER = {
|
|
343
|
+
P0: 0,
|
|
344
|
+
P1: 1,
|
|
345
|
+
P2: 2,
|
|
346
|
+
P3: 3
|
|
347
|
+
};
|
|
348
|
+
/** Dependencies of `story` that are not completed yet. */
|
|
349
|
+
function incompleteDependencies(prd, story) {
|
|
350
|
+
return story.dependencies.filter((id) => {
|
|
351
|
+
return prd.userStories.find((candidate) => candidate.id === id)?.status !== "completed";
|
|
352
|
+
});
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* A story cannot be worked on, reviewed or completed before the stories it
|
|
356
|
+
* depends on are completed. `not_started`, `research` and `blocked` stay
|
|
357
|
+
* available so a story can still be planned or parked.
|
|
358
|
+
*/
|
|
359
|
+
function assertCanEnterStatus(prd, story, status) {
|
|
360
|
+
if (!WORK_STATUSES.includes(status)) return;
|
|
361
|
+
const waitingOn = incompleteDependencies(prd, story);
|
|
362
|
+
if (waitingOn.length > 0) throw new Error(`Cannot move ${story.id} to ${status}: it depends on ${waitingOn.join(", ")}, which ${waitingOn.length === 1 ? "is" : "are"} not completed yet.`);
|
|
363
|
+
}
|
|
364
|
+
/** Position of the story's phase; stories without a phase come last. */
|
|
365
|
+
function phaseRank(prd, storyId) {
|
|
366
|
+
const phase = prd.customPhases.find((candidate) => candidate.userStoryIds.includes(storyId));
|
|
367
|
+
return phase ? phase.order : Number.MAX_SAFE_INTEGER;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* The next story to start: not started, every dependency completed, ordered
|
|
371
|
+
* by phase, then priority, then position in the PRD.
|
|
372
|
+
*/
|
|
373
|
+
function pickNextStory(prd) {
|
|
374
|
+
const notStarted = prd.userStories.filter((story) => story.status === "not_started");
|
|
375
|
+
const ready = notStarted.filter((story) => incompleteDependencies(prd, story).length === 0).sort((a, b) => phaseRank(prd, a.id) - phaseRank(prd, b.id) || PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority] || prd.userStories.indexOf(a) - prd.userStories.indexOf(b));
|
|
376
|
+
const waiting = notStarted.map((story) => ({
|
|
377
|
+
id: story.id,
|
|
378
|
+
title: story.title,
|
|
379
|
+
waiting_on: incompleteDependencies(prd, story)
|
|
380
|
+
})).filter((entry) => entry.waiting_on.length > 0);
|
|
381
|
+
return {
|
|
382
|
+
story: ready[0] ?? null,
|
|
383
|
+
ready_count: ready.length,
|
|
384
|
+
in_progress: prd.userStories.filter((story) => story.status === "in_progress").map((story) => story.id),
|
|
385
|
+
waiting
|
|
386
|
+
};
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Everything an agent needs to work on one story without loading the whole
|
|
390
|
+
* PRD: the story, the scope boundaries, its dependencies with their hand-off
|
|
391
|
+
* logs, and the log of the most recently completed story.
|
|
392
|
+
*/
|
|
393
|
+
/** `filename` is the PRD's file name, used to give attachment paths. */
|
|
394
|
+
function buildStoryContext(prd, storyId, filename, prdsPath) {
|
|
395
|
+
const story = findStory(prd, storyId);
|
|
396
|
+
const linked = new Set(story.attachmentIds ?? []);
|
|
397
|
+
const phase = prd.customPhases.find((candidate) => candidate.userStoryIds.includes(story.id)) ?? null;
|
|
398
|
+
const lastCompleted = prd.userStories.filter((candidate) => candidate.status === "completed").filter((candidate) => candidate.id !== story.id).sort((a, b) => (a.completedAt ?? "").localeCompare(b.completedAt ?? "")).at(-1) ?? null;
|
|
399
|
+
return {
|
|
400
|
+
prd: {
|
|
401
|
+
title: prd.introduction.title,
|
|
402
|
+
overview: prd.introduction.overview,
|
|
403
|
+
non_goals: prd.nonGoals,
|
|
404
|
+
out_of_scope: prd.outOfScope,
|
|
405
|
+
global_acceptance_criteria: prd.acceptanceCriteria.global,
|
|
406
|
+
attachments: resolveAttachments(filename, prd.attachments, prdsPath)
|
|
407
|
+
},
|
|
408
|
+
story,
|
|
409
|
+
attachments: resolveAttachments(filename, prd.attachments.filter((attachment) => linked.has(attachment.id)), prdsPath),
|
|
410
|
+
phase: phase ? {
|
|
411
|
+
id: phase.id,
|
|
412
|
+
name: phase.name
|
|
413
|
+
} : null,
|
|
414
|
+
edge_cases: edgeCasesForStory(prd, story.id),
|
|
415
|
+
open_questions: prd.openQuestions.filter((question) => question.storyIds?.includes(story.id)),
|
|
416
|
+
security: {
|
|
417
|
+
permissions: prd.technicalContracts.permissions,
|
|
418
|
+
compliance: prd.technicalRequirements.complianceRequirements,
|
|
419
|
+
considerations: prd.securityConsiderations,
|
|
420
|
+
story_notes: story.securityNotes ?? []
|
|
421
|
+
},
|
|
422
|
+
not_applicable: prd.notApplicable,
|
|
423
|
+
design: {
|
|
424
|
+
guidance: prd.designGuidance,
|
|
425
|
+
story_notes: story.designNotes ?? [],
|
|
426
|
+
decisions: designDecisions(prd).map(({ id, decision, rationale }) => ({
|
|
427
|
+
id,
|
|
428
|
+
decision,
|
|
429
|
+
rationale
|
|
430
|
+
}))
|
|
431
|
+
},
|
|
432
|
+
dependencies: story.dependencies.map((id) => {
|
|
433
|
+
const dependency = prd.userStories.find((candidate) => candidate.id === id);
|
|
434
|
+
return {
|
|
435
|
+
id,
|
|
436
|
+
title: dependency?.title ?? null,
|
|
437
|
+
status: dependency?.status ?? null,
|
|
438
|
+
log: dependency?.log ?? []
|
|
439
|
+
};
|
|
440
|
+
}),
|
|
441
|
+
previous_story: lastCompleted ? {
|
|
442
|
+
id: lastCompleted.id,
|
|
443
|
+
title: lastCompleted.title,
|
|
444
|
+
log: lastCompleted.log ?? []
|
|
445
|
+
} : null
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
function appendStoryLog(prd, storyId, entry) {
|
|
449
|
+
const story = findStory(prd, storyId);
|
|
450
|
+
story.log = [...story.log ?? [], entry];
|
|
451
|
+
return {
|
|
452
|
+
story_id: story.id,
|
|
453
|
+
entries: story.log.length
|
|
454
|
+
};
|
|
455
|
+
}
|
|
456
|
+
function withoutBlanks(entries) {
|
|
457
|
+
return entries.map((entry) => entry.trim()).filter(Boolean);
|
|
458
|
+
}
|
|
459
|
+
export { updateStory as _, buildStoryContext as a, validateProofs as b, findAttachment as c, nextId as d, nextStoryId as f, splitUserStory as g, renderUserStory as h, assignStoryToPhase as i, findStory as l, recomputeProgress as m, appendStoryLog as n, createPhase as o, pickNextStory as p, assertCanEnterStatus as r, deleteStory as s, appendChangeLog as t, incompleteDependencies as u, validateAttachmentIds as v, normalizeEdgeCases as x, validateDependencies as y };
|