@makerkit/prd 0.0.0 → 0.0.1

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.
Files changed (53) hide show
  1. package/package.json +2 -21
  2. package/.turbo/turbo-build.log +0 -46
  3. package/.turbo/turbo-test.log +0 -21
  4. package/.turbo/turbo-typecheck.log +0 -1
  5. package/dist/README.md +0 -65
  6. package/dist/package.json +0 -49
  7. package/src/__tests__/agent-workflow.test.ts +0 -377
  8. package/src/__tests__/attachments.test.ts +0 -475
  9. package/src/__tests__/node.test.ts +0 -141
  10. package/src/__tests__/plan-check.test.ts +0 -229
  11. package/src/__tests__/planning.test.ts +0 -1059
  12. package/src/__tests__/prd-operations.test.ts +0 -423
  13. package/src/__tests__/prd.service.test.ts +0 -477
  14. package/src/__tests__/prd.tool.test.ts +0 -282
  15. package/src/__tests__/templates.test.ts +0 -141
  16. package/src/applicability.ts +0 -73
  17. package/src/attachment-paths.ts +0 -78
  18. package/src/attachments.ts +0 -160
  19. package/src/edge-cases.ts +0 -52
  20. package/src/index.ts +0 -35
  21. package/src/markdown.ts +0 -268
  22. package/src/mcp/index.ts +0 -839
  23. package/src/mcp/tool-response.ts +0 -85
  24. package/src/node.ts +0 -146
  25. package/src/open-questions.ts +0 -93
  26. package/src/plan-check.ts +0 -282
  27. package/src/planning-operations.ts +0 -429
  28. package/src/prd-operations.ts +0 -690
  29. package/src/prd.service.ts +0 -1051
  30. package/src/prompts.ts +0 -110
  31. package/src/safe-file-name.ts +0 -42
  32. package/src/schema.ts +0 -976
  33. package/src/templates.ts +0 -173
  34. package/src/testing/fake-mcp-server.ts +0 -81
  35. package/src/types.ts +0 -333
  36. package/tsconfig.json +0 -23
  37. package/tsconfig.lib.json +0 -8
  38. package/tsconfig.spec.json +0 -7
  39. package/tsdown.config.mts +0 -11
  40. package/vitest.config.mts +0 -8
  41. /package/{dist/LICENSE → LICENSE} +0 -0
  42. /package/{dist/index.d.ts → index.d.ts} +0 -0
  43. /package/{dist/index.js → index.js} +0 -0
  44. /package/{dist/index.mjs → index.mjs} +0 -0
  45. /package/{dist/mcp.d.ts → mcp.d.ts} +0 -0
  46. /package/{dist/mcp.js → mcp.js} +0 -0
  47. /package/{dist/mcp.mjs → mcp.mjs} +0 -0
  48. /package/{dist/node.d.ts → node.d.ts} +0 -0
  49. /package/{dist/node.js → node.js} +0 -0
  50. /package/{dist/node.mjs → node.mjs} +0 -0
  51. /package/{dist/prd.service-DSBp8sMl.d.ts → prd.service-DSBp8sMl.d.ts} +0 -0
  52. /package/{dist/prompts-Bber0S1Z.mjs → prompts-Bber0S1Z.mjs} +0 -0
  53. /package/{dist/prompts-CIX8IeAx.js → prompts-CIX8IeAx.js} +0 -0
@@ -1,160 +0,0 @@
1
- import { attachmentProjectPath } from './attachment-paths';
2
- import { appendChangeLog, findAttachment, findStory } from './prd-operations';
3
- import { assertSafeRelativePath } from './safe-file-name';
4
- import type {
5
- AddAttachmentInput,
6
- RemoveAttachmentOutput,
7
- UpdateAttachmentInput,
8
- UpdateAttachmentOutput,
9
- } from './schema';
10
- import type { StructuredPRD } from './types';
11
-
12
- /**
13
- * Adds an attachment and links it to the given stories. The caller checks
14
- * that a `path` exists on disk; this only validates the PRD.
15
- */
16
- export function addAttachment(
17
- prd: StructuredPRD,
18
- input: AddAttachmentInput,
19
- today: string,
20
- ) {
21
- if (Boolean(input.path) === Boolean(input.url)) {
22
- throw new Error('Give either path or url for an attachment, not both.');
23
- }
24
-
25
- if (input.url && !/^https?:\/\//i.test(input.url)) {
26
- throw new Error('An attachment url must start with http:// or https://.');
27
- }
28
-
29
- const path = input.path
30
- ? assertSafeRelativePath(input.path, 'attachment path')
31
- : undefined;
32
-
33
- const stories = (input.storyIds ?? []).map((id) => findStory(prd, id));
34
- const id = nextAttachmentId(prd);
35
-
36
- prd.attachments.push({
37
- id,
38
- title: input.title,
39
- ...(path ? { path } : { url: input.url }),
40
- ...(input.note ? { note: input.note } : {}),
41
- });
42
-
43
- for (const story of stories) {
44
- story.attachmentIds = [...new Set([...(story.attachmentIds ?? []), id])];
45
- }
46
-
47
- appendChangeLog(prd, `Added attachment ${id} (${input.title})`, today);
48
-
49
- return {
50
- attachment_id: id,
51
- path: path ? attachmentProjectPath(input.filename, path) : null,
52
- stories_updated: stories.map((story) => story.id),
53
- total_attachments: prd.attachments.length,
54
- };
55
- }
56
-
57
- /**
58
- * Issues the next attachment id and advances the high-water mark, like story
59
- * ids. Ids still linked from stories count too: a writer that predates
60
- * attachments drops the list and the counter but keeps the stories' links,
61
- * and those must never come to mean a different file.
62
- */
63
- function nextAttachmentId(prd: StructuredPRD) {
64
- const numbers = [
65
- ...prd.attachments.map((attachment) => attachment.id),
66
- ...prd.userStories.flatMap((story) => story.attachmentIds ?? []),
67
- ].map((id) => Number(/^ATT(\d+)$/.exec(id)?.[1] ?? 0));
68
-
69
- const next =
70
- Math.max(prd.metadata.lastAttachmentNumber ?? 0, 0, ...numbers) + 1;
71
-
72
- prd.metadata.lastAttachmentNumber = next;
73
-
74
- return `ATT${String(next).padStart(3, '0')}`;
75
- }
76
-
77
- /**
78
- * Removes an attachment and every story's link to it. The file itself stays
79
- * on disk.
80
- */
81
- export function removeAttachment(
82
- prd: StructuredPRD,
83
- attachmentId: string,
84
- today: string,
85
- ): RemoveAttachmentOutput {
86
- const attachment = findAttachment(prd, attachmentId);
87
-
88
- prd.attachments = prd.attachments.filter(
89
- (candidate) => candidate.id !== attachment.id,
90
- );
91
-
92
- const storiesUpdated: string[] = [];
93
-
94
- for (const story of prd.userStories) {
95
- if (story.attachmentIds?.includes(attachment.id)) {
96
- story.attachmentIds = story.attachmentIds.filter(
97
- (id) => id !== attachment.id,
98
- );
99
- storiesUpdated.push(story.id);
100
- }
101
- }
102
-
103
- appendChangeLog(
104
- prd,
105
- `Removed attachment ${attachment.id} (${attachment.title})`,
106
- today,
107
- );
108
-
109
- return {
110
- attachment_id: attachment.id,
111
- stories_updated: storiesUpdated,
112
- total_attachments: prd.attachments.length,
113
- };
114
- }
115
-
116
- /**
117
- * Changes an attachment's title or note, and which stories use it: with
118
- * storyIds, links are added and removed so exactly those stories use it.
119
- */
120
- export function updateAttachment(
121
- prd: StructuredPRD,
122
- input: UpdateAttachmentInput,
123
- today: string,
124
- ): UpdateAttachmentOutput {
125
- const attachment = findAttachment(prd, input.attachmentId);
126
-
127
- if (input.title !== undefined) {
128
- attachment.title = input.title;
129
- }
130
-
131
- if (input.note !== undefined) {
132
- if (input.note.trim()) {
133
- attachment.note = input.note;
134
- } else {
135
- delete attachment.note;
136
- }
137
- }
138
-
139
- const storiesUpdated: string[] = [];
140
-
141
- if (input.storyIds !== undefined) {
142
- const wanted = new Set(input.storyIds.map((id) => findStory(prd, id).id));
143
-
144
- for (const story of prd.userStories) {
145
- const linked = story.attachmentIds?.includes(attachment.id) ?? false;
146
-
147
- if (wanted.has(story.id) && !linked) {
148
- story.attachmentIds = [...(story.attachmentIds ?? []), attachment.id];
149
- storiesUpdated.push(story.id);
150
- } else if (!wanted.has(story.id) && linked) {
151
- story.attachmentIds = story.attachmentIds!.filter((id) => id !== attachment.id);
152
- storiesUpdated.push(story.id);
153
- }
154
- }
155
- }
156
-
157
- appendChangeLog(prd, `Updated attachment ${attachment.id} (${attachment.title})`, today);
158
-
159
- return { attachment_id: attachment.id, stories_updated: storiesUpdated };
160
- }
package/src/edge-cases.ts DELETED
@@ -1,52 +0,0 @@
1
- import type { EdgeCase, StructuredPRD } from './types';
2
-
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
- export function normalizeEdgeCases(value: unknown): EdgeCase[] {
8
- if (!Array.isArray(value)) {
9
- return [];
10
- }
11
-
12
- return value.flatMap((entry): EdgeCase[] => {
13
- if (typeof entry !== 'object' || entry === null) {
14
- return [];
15
- }
16
-
17
- const { id, case: caseText, expectedBehavior, status, storyIds } =
18
- entry as Record<string, unknown>;
19
-
20
- if (typeof id !== 'string' || typeof caseText !== 'string' || !caseText) {
21
- return [];
22
- }
23
-
24
- const ids = Array.isArray(storyIds)
25
- ? storyIds.filter((storyId): storyId is string => typeof storyId === 'string')
26
- : [];
27
-
28
- return [
29
- {
30
- id,
31
- case: caseText,
32
- expectedBehavior: typeof expectedBehavior === 'string' ? expectedBehavior : '',
33
- status: status === 'decided' ? 'decided' : 'open',
34
- ...(ids.length > 0 ? { storyIds: ids } : {}),
35
- },
36
- ];
37
- });
38
- }
39
-
40
- /** The edge cases that apply to a story: those linked to it, and those linked to no story. */
41
- export function edgeCasesForStory(prd: StructuredPRD, storyId: string) {
42
- return prd.edgeCases.filter(
43
- (edgeCase) => !edgeCase.storyIds?.length || edgeCase.storyIds.includes(storyId),
44
- );
45
- }
46
-
47
- /** Accepted decisions whose topic starts with `design`, e.g. `design:navigation`. */
48
- export function designDecisions(prd: StructuredPRD) {
49
- return prd.decisionLog.filter(
50
- (entry) => entry.status === 'accepted' && entry.topic?.startsWith('design'),
51
- );
52
- }
package/src/index.ts DELETED
@@ -1,35 +0,0 @@
1
- export {
2
- createPrdService,
3
- normalizePrd,
4
- PrdRevisionConflictError,
5
- PrdService,
6
- type PrdDeps,
7
- type PrdVerificationDiagnostic,
8
- type PrdVerificationResult,
9
- } from './prd.service';
10
- export * from './prd-operations';
11
- export {
12
- attachmentProjectPath,
13
- attachmentsFolder,
14
- resolveAttachments,
15
- } from './attachment-paths';
16
- export {
17
- NOT_APPLICABLE_TOPICS,
18
- isNotApplicable,
19
- } from './applicability';
20
- export { formatPrdMarkdown } from './markdown';
21
- export {
22
- implementStoryPrompt,
23
- reviewStoryPrompt,
24
- shapePrdPrompt,
25
- } from './prompts';
26
- export { checkPlan, type PlanCheckItem } from './plan-check';
27
- export {
28
- PRD_TEMPLATES,
29
- TEMPLATE_IDS,
30
- getTemplate,
31
- type PrdTemplate,
32
- type TemplateId,
33
- } from './templates';
34
- export * from './schema';
35
- export type * from './types';
package/src/markdown.ts DELETED
@@ -1,268 +0,0 @@
1
- import { attachmentsFolder } from './attachment-paths';
2
- import type {
3
- Attachment,
4
- StoryStatus,
5
- StructuredPRD,
6
- UserStory,
7
- } from './types';
8
-
9
- const STATUS_LABELS: Record<StoryStatus, string> = {
10
- not_started: '[not started]',
11
- research: '[research]',
12
- in_progress: '[in progress]',
13
- review: '[review]',
14
- completed: '[completed]',
15
- blocked: '[blocked]',
16
- };
17
-
18
- /**
19
- * Pass the PRD file name to link attachment files relative to `.prds/`, where
20
- * the markdown export is written.
21
- */
22
- export function formatPrdMarkdown(
23
- prd: StructuredPRD,
24
- filename?: string,
25
- ): string {
26
- const lines: string[] = [];
27
-
28
- lines.push(`# ${prd.introduction.title}`, '');
29
- lines.push('## Introduction', '', prd.introduction.overview, '');
30
- lines.push(`**Last Updated:** ${prd.introduction.lastUpdated}`);
31
- lines.push(`**Version:** ${prd.metadata.version}`, '');
32
-
33
- lines.push('## Problem Statement', '', prd.problemStatement.problem, '');
34
- lines.push(
35
- '### Market Opportunity',
36
- prd.problemStatement.marketOpportunity,
37
- '',
38
- );
39
- lines.push('### Target Users');
40
- lines.push(...bullets(prd.problemStatement.targetUsers));
41
-
42
- lines.push(
43
- '',
44
- '## Solution Overview',
45
- '',
46
- prd.solutionOverview.description,
47
- '',
48
- );
49
- lines.push('### Key Features', ...bullets(prd.solutionOverview.keyFeatures));
50
- lines.push('', '### Success Metrics');
51
- lines.push(...bullets(prd.solutionOverview.successMetrics));
52
-
53
- lines.push('', '## Scope Guardrails', '');
54
- lines.push('### Non-Goals', ...bullets(prd.nonGoals, 'None specified'));
55
- lines.push(
56
- '',
57
- '### Out of Scope',
58
- ...bullets(prd.outOfScope, 'None specified'),
59
- );
60
- lines.push(
61
- '',
62
- '### Assumptions',
63
- ...bullets(prd.assumptions, 'None specified'),
64
- );
65
- lines.push(
66
- '',
67
- '### Open Questions',
68
- ...bullets(
69
- prd.openQuestions.map(
70
- (question) =>
71
- `${question.id}: ${question.question}` +
72
- (question.storyIds?.length ? ` (blocks ${question.storyIds.join(', ')})` : '') +
73
- (question.recommended ? ` Recommended: ${question.recommended}` : ''),
74
- ),
75
- 'None',
76
- ),
77
- );
78
-
79
- if (prd.edgeCases.length > 0) {
80
- lines.push('', '## Edge Cases');
81
-
82
- for (const edgeCase of prd.edgeCases) {
83
- const stories = edgeCase.storyIds?.length ? ` (${edgeCase.storyIds.join(', ')})` : '';
84
- const behaviour =
85
- edgeCase.status === 'decided' ? edgeCase.expectedBehavior : 'OPEN: ask, do not assume';
86
-
87
- lines.push(`- ${edgeCase.case}${stories} -> ${behaviour}`);
88
- }
89
- }
90
-
91
- const security = [
92
- ...prd.technicalContracts.permissions.map((item) => `Permission: ${item}`),
93
- ...prd.technicalRequirements.complianceRequirements.map((item) => `Data: ${item}`),
94
- ...prd.securityConsiderations,
95
- ];
96
-
97
- if (security.length > 0) {
98
- lines.push('', '## Security', ...bullets(security));
99
- }
100
-
101
- const notApplicable = Object.entries(prd.notApplicable);
102
-
103
- if (notApplicable.length > 0) {
104
- lines.push(
105
- '',
106
- '## Not Applicable',
107
- ...notApplicable.map(([topic, reason]) => `- ${topic}${reason ? `: ${reason}` : ''}`),
108
- );
109
- }
110
-
111
- if (prd.designGuidance.length > 0) {
112
- lines.push('', '## Design Guidance', ...bullets(prd.designGuidance));
113
- }
114
-
115
- if (prd.risks.length > 0) {
116
- lines.push('', '## Risks');
117
-
118
- for (const risk of prd.risks) {
119
- lines.push(
120
- `- [${risk.severity}] ${risk.description} | Mitigation: ${risk.mitigation} | Owner: ${risk.owner}`,
121
- );
122
- }
123
- }
124
-
125
- if (prd.dependencies.length > 0) {
126
- lines.push('', '## Dependencies');
127
-
128
- for (const dependency of prd.dependencies) {
129
- const mode = dependency.blocking ? 'blocking' : 'non-blocking';
130
- lines.push(`- ${dependency.name} (${mode}) - ${dependency.description}`);
131
- }
132
- }
133
-
134
- if (prd.attachments.length > 0) {
135
- lines.push('', '## Attachments');
136
-
137
- for (const attachment of prd.attachments) {
138
- lines.push(formatAttachment(attachment, filename));
139
- }
140
- }
141
-
142
- lines.push('', '## User Stories', '');
143
-
144
- for (const priority of ['P0', 'P1', 'P2', 'P3'] as const) {
145
- const stories = prd.userStories.filter((s) => s.priority === priority);
146
-
147
- if (stories.length === 0) continue;
148
-
149
- lines.push(`### Priority ${priority}`, '');
150
-
151
- for (const story of stories) {
152
- lines.push(...formatStory(story));
153
- }
154
- }
155
-
156
- lines.push('', '## Progress', '');
157
- lines.push(
158
- `**Overall:** ${prd.progress.overall}% (${prd.progress.completed}/${prd.progress.total} stories)`,
159
- );
160
-
161
- if (prd.progress.blocked > 0) {
162
- lines.push(`**Blocked:** ${prd.progress.blocked} stories need attention`);
163
- }
164
-
165
- if (prd.rolloutPlan.rolloutPhases.length > 0) {
166
- lines.push(
167
- '',
168
- '## Rollout Plan',
169
- ...bullets(prd.rolloutPlan.rolloutPhases),
170
- );
171
- }
172
-
173
- if (prd.measurementPlan.targetMetrics.length > 0) {
174
- lines.push(
175
- '',
176
- '## Measurement Plan',
177
- ...bullets(prd.measurementPlan.targetMetrics),
178
- );
179
- }
180
-
181
- lines.push(
182
- '',
183
- '---',
184
- '',
185
- `*Approver: ${prd.metadata.approver || 'TBD'}*`,
186
- '',
187
- );
188
-
189
- return lines.join('\n');
190
- }
191
-
192
- function formatStory(story: UserStory): string[] {
193
- const lines = [
194
- `#### ${story.id}: ${story.title} ${STATUS_LABELS[story.status]} [${story.estimatedComplexity}]`,
195
- '',
196
- `**User Story:** ${story.userStory}`,
197
- '',
198
- `**Business Value:** ${story.businessValue}`,
199
- '',
200
- '**Acceptance Criteria:**',
201
- ...bullets(story.acceptanceCriteria),
202
- ];
203
-
204
- if (story.dependencies.length > 0) {
205
- lines.push('', `**Dependencies:** ${story.dependencies.join(', ')}`);
206
- }
207
-
208
- if (story.attachmentIds?.length) {
209
- lines.push('', `**Attachments:** ${story.attachmentIds.join(', ')}`);
210
- }
211
-
212
- if (story.designNotes?.length) {
213
- lines.push('', '**Design Notes:**', ...bullets(story.designNotes));
214
- }
215
-
216
- if (story.securityNotes?.length) {
217
- lines.push('', '**Security Notes:**', ...bullets(story.securityNotes));
218
- }
219
-
220
- if (story.verification) {
221
- lines.push(
222
- '',
223
- `**Verified:** ${story.verification.verifiedAt} (${story.verification.checks.join(', ')})`,
224
- );
225
- }
226
-
227
- lines.push('');
228
-
229
- return lines;
230
- }
231
-
232
- function formatAttachment(attachment: Attachment, filename?: string) {
233
- const title = oneLine(attachment.title).replace(/[[\]]/g, '\\$&');
234
- const target = attachment.url
235
- ? linkTarget(attachment.url)
236
- : filename
237
- ? linkTarget(
238
- encodeURI(`${attachmentsFolder(filename)}/${attachment.path}`),
239
- )
240
- : undefined;
241
- const label = target
242
- ? `[${title}](${target})`
243
- : `${title} (${attachment.path})`;
244
- const note = attachment.note ? ` - ${oneLine(attachment.note)}` : '';
245
-
246
- return `- ${attachment.id}: ${label}${note}`;
247
- }
248
-
249
- /** Keeps a list item on one line, so text cannot start a new block. */
250
- function oneLine(value: string) {
251
- return value.replace(/\s+/g, ' ').trim();
252
- }
253
-
254
- /** Parentheses and spaces would end a markdown link target early. */
255
- function linkTarget(value: string) {
256
- return value
257
- .replace(/\s/g, '%20')
258
- .replace(/\(/g, '%28')
259
- .replace(/\)/g, '%29');
260
- }
261
-
262
- function bullets(items: string[], emptyLabel?: string) {
263
- if (items.length === 0) {
264
- return emptyLabel ? [`- ${emptyLabel}`] : [];
265
- }
266
-
267
- return items.map((item) => `- ${item}`);
268
- }