@makerkit/prd 0.0.3 → 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} +257 -524
- package/{index.mjs → dist/index.mjs} +189 -462
- 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-DJQ4FQ11.js → dist/prompts-1qhax_dj.js} +150 -167
- package/{prompts-B0VejF7q.mjs → dist/prompts-BlsYD0gf.mjs} +121 -132
- package/{prd.service-x5EpOoMv.d.ts → dist/schema-BwTnt0B9.d.ts} +545 -323
- 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 -228
- /package/{LICENSE → dist/LICENSE} +0 -0
|
@@ -0,0 +1,584 @@
|
|
|
1
|
+
const require_attachment_paths = require("./attachment-paths-BAhRGiib.js");
|
|
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: require_attachment_paths.resolveAttachments(filename, prd.attachments, prdsPath)
|
|
407
|
+
},
|
|
408
|
+
story,
|
|
409
|
+
attachments: require_attachment_paths.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
|
+
Object.defineProperty(exports, "appendChangeLog", {
|
|
460
|
+
enumerable: true,
|
|
461
|
+
get: function() {
|
|
462
|
+
return appendChangeLog;
|
|
463
|
+
}
|
|
464
|
+
});
|
|
465
|
+
Object.defineProperty(exports, "appendStoryLog", {
|
|
466
|
+
enumerable: true,
|
|
467
|
+
get: function() {
|
|
468
|
+
return appendStoryLog;
|
|
469
|
+
}
|
|
470
|
+
});
|
|
471
|
+
Object.defineProperty(exports, "assertCanEnterStatus", {
|
|
472
|
+
enumerable: true,
|
|
473
|
+
get: function() {
|
|
474
|
+
return assertCanEnterStatus;
|
|
475
|
+
}
|
|
476
|
+
});
|
|
477
|
+
Object.defineProperty(exports, "assignStoryToPhase", {
|
|
478
|
+
enumerable: true,
|
|
479
|
+
get: function() {
|
|
480
|
+
return assignStoryToPhase;
|
|
481
|
+
}
|
|
482
|
+
});
|
|
483
|
+
Object.defineProperty(exports, "buildStoryContext", {
|
|
484
|
+
enumerable: true,
|
|
485
|
+
get: function() {
|
|
486
|
+
return buildStoryContext;
|
|
487
|
+
}
|
|
488
|
+
});
|
|
489
|
+
Object.defineProperty(exports, "createPhase", {
|
|
490
|
+
enumerable: true,
|
|
491
|
+
get: function() {
|
|
492
|
+
return createPhase;
|
|
493
|
+
}
|
|
494
|
+
});
|
|
495
|
+
Object.defineProperty(exports, "deleteStory", {
|
|
496
|
+
enumerable: true,
|
|
497
|
+
get: function() {
|
|
498
|
+
return deleteStory;
|
|
499
|
+
}
|
|
500
|
+
});
|
|
501
|
+
Object.defineProperty(exports, "findAttachment", {
|
|
502
|
+
enumerable: true,
|
|
503
|
+
get: function() {
|
|
504
|
+
return findAttachment;
|
|
505
|
+
}
|
|
506
|
+
});
|
|
507
|
+
Object.defineProperty(exports, "findStory", {
|
|
508
|
+
enumerable: true,
|
|
509
|
+
get: function() {
|
|
510
|
+
return findStory;
|
|
511
|
+
}
|
|
512
|
+
});
|
|
513
|
+
Object.defineProperty(exports, "incompleteDependencies", {
|
|
514
|
+
enumerable: true,
|
|
515
|
+
get: function() {
|
|
516
|
+
return incompleteDependencies;
|
|
517
|
+
}
|
|
518
|
+
});
|
|
519
|
+
Object.defineProperty(exports, "nextId", {
|
|
520
|
+
enumerable: true,
|
|
521
|
+
get: function() {
|
|
522
|
+
return nextId;
|
|
523
|
+
}
|
|
524
|
+
});
|
|
525
|
+
Object.defineProperty(exports, "nextStoryId", {
|
|
526
|
+
enumerable: true,
|
|
527
|
+
get: function() {
|
|
528
|
+
return nextStoryId;
|
|
529
|
+
}
|
|
530
|
+
});
|
|
531
|
+
Object.defineProperty(exports, "normalizeEdgeCases", {
|
|
532
|
+
enumerable: true,
|
|
533
|
+
get: function() {
|
|
534
|
+
return normalizeEdgeCases;
|
|
535
|
+
}
|
|
536
|
+
});
|
|
537
|
+
Object.defineProperty(exports, "pickNextStory", {
|
|
538
|
+
enumerable: true,
|
|
539
|
+
get: function() {
|
|
540
|
+
return pickNextStory;
|
|
541
|
+
}
|
|
542
|
+
});
|
|
543
|
+
Object.defineProperty(exports, "recomputeProgress", {
|
|
544
|
+
enumerable: true,
|
|
545
|
+
get: function() {
|
|
546
|
+
return recomputeProgress;
|
|
547
|
+
}
|
|
548
|
+
});
|
|
549
|
+
Object.defineProperty(exports, "renderUserStory", {
|
|
550
|
+
enumerable: true,
|
|
551
|
+
get: function() {
|
|
552
|
+
return renderUserStory;
|
|
553
|
+
}
|
|
554
|
+
});
|
|
555
|
+
Object.defineProperty(exports, "splitUserStory", {
|
|
556
|
+
enumerable: true,
|
|
557
|
+
get: function() {
|
|
558
|
+
return splitUserStory;
|
|
559
|
+
}
|
|
560
|
+
});
|
|
561
|
+
Object.defineProperty(exports, "updateStory", {
|
|
562
|
+
enumerable: true,
|
|
563
|
+
get: function() {
|
|
564
|
+
return updateStory;
|
|
565
|
+
}
|
|
566
|
+
});
|
|
567
|
+
Object.defineProperty(exports, "validateAttachmentIds", {
|
|
568
|
+
enumerable: true,
|
|
569
|
+
get: function() {
|
|
570
|
+
return validateAttachmentIds;
|
|
571
|
+
}
|
|
572
|
+
});
|
|
573
|
+
Object.defineProperty(exports, "validateDependencies", {
|
|
574
|
+
enumerable: true,
|
|
575
|
+
get: function() {
|
|
576
|
+
return validateDependencies;
|
|
577
|
+
}
|
|
578
|
+
});
|
|
579
|
+
Object.defineProperty(exports, "validateProofs", {
|
|
580
|
+
enumerable: true,
|
|
581
|
+
get: function() {
|
|
582
|
+
return validateProofs;
|
|
583
|
+
}
|
|
584
|
+
});
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import { A as CreateCustomPhaseOutput, At as MarkNotApplicableOutput, B as DecideEdgeCaseOutput, C as AssignStoryToPhaseOutput, Ct as ListPrdsOutput, E as CheckPlanOutput, Et as ListTemplatesOutput, Gt as RemoveAttachmentOutput, H as DeletePhaseInput, J as DeleteUserStoryInput, K as DeletePrdOutput, M as CreatePrdInput, Nt as PhasesOutput, O as CreateCustomPhaseInput, Ot as MarkNotApplicableInput, P as CreatePrdOutput, Q as ExportPrdMarkdownInput, R as DecideEdgeCaseInput, Sn as UpdateUserStoryOutput, Un as StructuredPRD, Ut as RemoveAttachmentInput, W as DeletePrdInput, X as DeleteUserStoryOutput, Yt as ResolveOpenQuestionInput, Zt as ResolveOpenQuestionOutput, _ as AddUserStoryInput, a as AddDecisionInput, bn as UpdateUserStoryInput, bt as GetStoryOutput, cn as UpdateAttachmentOutput, d as AddGlossaryTermOutput, dt as GetPrdInput, et as ExportPrdMarkdownOutput, fn as UpdatePrdSectionInput, gn as UpdateStoryStatusInput, gt as GetProjectStatusOutput, h as AddStoryLogOutput, l as AddGlossaryTermInput, lt as GetNextStoryOutput, mn as UpdatePrdSectionOutput, on as UpdateAttachmentInput, ot as GetImprovementSuggestionsOutput, p as AddStoryLogInput, pt as GetPrdOutput, qt as ReorderPhasesInput, r as AddAttachmentOutput, rt as GetImplementationPromptsOutput, s as AddDecisionOutput, t as AddAttachmentInput, un as UpdatePhaseInput, vn as UpdateStoryStatusOutput, vt as GetStoryInput, x as AssignStoryToPhaseInput, y as AddUserStoryOutput } from "./schema-BwTnt0B9.js";
|
|
2
|
+
interface PrdVerificationDiagnostic {
|
|
3
|
+
file: string;
|
|
4
|
+
line: number | null;
|
|
5
|
+
message: string;
|
|
6
|
+
severity: string;
|
|
7
|
+
}
|
|
8
|
+
interface PrdVerificationResult {
|
|
9
|
+
passed: boolean;
|
|
10
|
+
/** Scripts that ran, e.g. ['typecheck', 'lint']. */
|
|
11
|
+
checks: string[];
|
|
12
|
+
errors: number;
|
|
13
|
+
warnings: number;
|
|
14
|
+
diagnostics: PrdVerificationDiagnostic[];
|
|
15
|
+
/** Human-readable reasons for checks that failed without diagnostics. */
|
|
16
|
+
messages: string[];
|
|
17
|
+
}
|
|
18
|
+
interface PrdDeps {
|
|
19
|
+
rootPath: string;
|
|
20
|
+
prdsDir?: string;
|
|
21
|
+
readdir(path: string): Promise<string[]>;
|
|
22
|
+
readFile(path: string): Promise<string>;
|
|
23
|
+
writeFile(path: string, content: string): Promise<void>;
|
|
24
|
+
/** Must not throw when the directory already exists. */
|
|
25
|
+
mkdir(path: string): Promise<void>;
|
|
26
|
+
unlink(path: string): Promise<void>;
|
|
27
|
+
fileExists(path: string): Promise<boolean>;
|
|
28
|
+
/** Serializes revision checks and writes across processes sharing a PRD. */
|
|
29
|
+
withWriteLock?<T>(path: string, write: () => Promise<T>): Promise<T>;
|
|
30
|
+
now(): Date;
|
|
31
|
+
/**
|
|
32
|
+
* Runs the project's checks before a story may be marked completed. When
|
|
33
|
+
* the result is not passing the status change is rejected, so "completed"
|
|
34
|
+
* always means "the code verifies", not "the agent believes it is done".
|
|
35
|
+
*/
|
|
36
|
+
verifyCompletion(): Promise<PrdVerificationResult>;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* A write was based on an older revision of the PRD than the one on disk:
|
|
40
|
+
* someone else (an agent, Loop, another editor) changed it in between. Read
|
|
41
|
+
* the PRD again and retry; never overwrite.
|
|
42
|
+
*/
|
|
43
|
+
declare class PrdRevisionConflictError extends Error {
|
|
44
|
+
readonly filename: string;
|
|
45
|
+
readonly expectedRevision: number;
|
|
46
|
+
readonly currentRevision: number;
|
|
47
|
+
readonly code = "PRD_REVISION_CONFLICT";
|
|
48
|
+
constructor(filename: string, expectedRevision: number, currentRevision: number);
|
|
49
|
+
}
|
|
50
|
+
declare function createPrdService(deps: PrdDeps): PrdService;
|
|
51
|
+
declare class PrdService {
|
|
52
|
+
private readonly deps;
|
|
53
|
+
private pendingWrite;
|
|
54
|
+
constructor(deps: PrdDeps);
|
|
55
|
+
get prdsDir(): string;
|
|
56
|
+
/** Path for agent-facing instructions, relative to the project when possible. */
|
|
57
|
+
get prdsPath(): string;
|
|
58
|
+
list(): Promise<ListPrdsOutput>;
|
|
59
|
+
get(input: GetPrdInput): Promise<GetPrdOutput>;
|
|
60
|
+
create(input: CreatePrdInput): Promise<CreatePrdOutput>;
|
|
61
|
+
delete(input: DeletePrdInput): Promise<DeletePrdOutput>;
|
|
62
|
+
addUserStory(input: AddUserStoryInput): Promise<AddUserStoryOutput>;
|
|
63
|
+
updateUserStory(input: UpdateUserStoryInput): Promise<UpdateUserStoryOutput>;
|
|
64
|
+
deleteUserStory(input: DeleteUserStoryInput): Promise<DeleteUserStoryOutput>;
|
|
65
|
+
createCustomPhase(input: CreateCustomPhaseInput): Promise<CreateCustomPhaseOutput>;
|
|
66
|
+
assignStoryToPhase(input: AssignStoryToPhaseInput): Promise<AssignStoryToPhaseOutput>;
|
|
67
|
+
updateStoryStatus(input: UpdateStoryStatusInput): Promise<UpdateStoryStatusOutput>;
|
|
68
|
+
exportMarkdown(input: ExportPrdMarkdownInput): Promise<ExportPrdMarkdownOutput>;
|
|
69
|
+
getImplementationPrompts(filename: string): Promise<GetImplementationPromptsOutput>;
|
|
70
|
+
getImprovementSuggestions(filename: string): Promise<GetImprovementSuggestionsOutput>;
|
|
71
|
+
listTemplates(): ListTemplatesOutput;
|
|
72
|
+
checkPlan(filename: string): Promise<CheckPlanOutput>;
|
|
73
|
+
getProjectStatus(filename: string): Promise<GetProjectStatusOutput>;
|
|
74
|
+
updatePrdSection(input: UpdatePrdSectionInput): Promise<UpdatePrdSectionOutput>;
|
|
75
|
+
/** Mark a part of the PRD (not) applicable, e.g. no rollout for an internal tool. */
|
|
76
|
+
markNotApplicable(input: MarkNotApplicableInput): Promise<MarkNotApplicableOutput>;
|
|
77
|
+
addDecision(input: AddDecisionInput): Promise<AddDecisionOutput>;
|
|
78
|
+
resolveOpenQuestion(input: ResolveOpenQuestionInput): Promise<ResolveOpenQuestionOutput>;
|
|
79
|
+
decideEdgeCase(input: DecideEdgeCaseInput): Promise<DecideEdgeCaseOutput>;
|
|
80
|
+
addGlossaryTerm(input: AddGlossaryTermInput): Promise<AddGlossaryTermOutput>;
|
|
81
|
+
updatePhase(input: UpdatePhaseInput): Promise<PhasesOutput>;
|
|
82
|
+
deletePhase(input: DeletePhaseInput): Promise<PhasesOutput>;
|
|
83
|
+
reorderPhases(input: ReorderPhasesInput): Promise<PhasesOutput>;
|
|
84
|
+
getNextStory(filename: string): Promise<GetNextStoryOutput>;
|
|
85
|
+
getStory(input: GetStoryInput): Promise<GetStoryOutput>;
|
|
86
|
+
addStoryLog(input: AddStoryLogInput): Promise<AddStoryLogOutput>;
|
|
87
|
+
private assertStoryOwner;
|
|
88
|
+
private assertStoryStatusUpdate;
|
|
89
|
+
/** Files must already be in the PRD's folder, `.prds/<prd name>/`. */
|
|
90
|
+
addAttachment(input: AddAttachmentInput): Promise<AddAttachmentOutput>;
|
|
91
|
+
/** Changes an attachment's title, note or the stories that use it. */
|
|
92
|
+
updateAttachment(input: UpdateAttachmentInput): Promise<UpdateAttachmentOutput>;
|
|
93
|
+
/** Removes the attachment from the PRD and its stories; the file stays. */
|
|
94
|
+
removeAttachment(input: RemoveAttachmentInput): Promise<RemoveAttachmentOutput>;
|
|
95
|
+
/** Load → transform → save for operations that only touch the PRD. */
|
|
96
|
+
/**
|
|
97
|
+
* Load, change and save a PRD. With `expectedRevision` (the revision the
|
|
98
|
+
* caller's change is based on, e.g. what a person saw before editing), the
|
|
99
|
+
* change is rejected when the PRD has moved on since.
|
|
100
|
+
*/
|
|
101
|
+
private mutate;
|
|
102
|
+
/**
|
|
103
|
+
* Load and normalise a PRD. The file name is validated here, at the
|
|
104
|
+
* filesystem boundary, so every caller (including the dev tool) is covered.
|
|
105
|
+
*/
|
|
106
|
+
load(filename: string): Promise<StructuredPRD>;
|
|
107
|
+
private save;
|
|
108
|
+
private saveRevision;
|
|
109
|
+
private listFilenames;
|
|
110
|
+
private safeName;
|
|
111
|
+
private today;
|
|
112
|
+
}
|
|
113
|
+
declare function normalizePrd(input: unknown, today: string): StructuredPRD;
|
|
114
|
+
export { PrdVerificationResult as a, PrdVerificationDiagnostic as i, PrdRevisionConflictError as n, createPrdService as o, PrdService as r, normalizePrd as s, PrdDeps as t };
|