@makerkit/prd 0.0.0 → 0.0.2
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/README.md +1 -1
- package/{dist/index.d.ts → index.d.ts} +1 -0
- package/{dist/index.js → index.js} +74 -151
- package/{dist/index.mjs → index.mjs} +62 -140
- package/{dist/mcp.js → mcp.js} +12 -1
- package/{dist/mcp.mjs → mcp.mjs} +12 -1
- package/package.json +2 -21
- package/{dist/prompts-Bber0S1Z.mjs → prompts-B0ciGmv-.mjs} +101 -3
- package/{dist/prompts-CIX8IeAx.js → prompts-CTRnq1J5.js} +142 -2
- package/.turbo/turbo-build.log +0 -46
- package/.turbo/turbo-test.log +0 -21
- package/.turbo/turbo-typecheck.log +0 -1
- package/dist/README.md +0 -65
- package/dist/package.json +0 -49
- package/src/__tests__/agent-workflow.test.ts +0 -377
- package/src/__tests__/attachments.test.ts +0 -475
- package/src/__tests__/node.test.ts +0 -141
- package/src/__tests__/plan-check.test.ts +0 -229
- package/src/__tests__/planning.test.ts +0 -1059
- package/src/__tests__/prd-operations.test.ts +0 -423
- package/src/__tests__/prd.service.test.ts +0 -477
- package/src/__tests__/prd.tool.test.ts +0 -282
- package/src/__tests__/templates.test.ts +0 -141
- package/src/applicability.ts +0 -73
- package/src/attachment-paths.ts +0 -78
- package/src/attachments.ts +0 -160
- package/src/edge-cases.ts +0 -52
- package/src/index.ts +0 -35
- package/src/markdown.ts +0 -268
- package/src/mcp/index.ts +0 -839
- package/src/mcp/tool-response.ts +0 -85
- package/src/node.ts +0 -146
- package/src/open-questions.ts +0 -93
- package/src/plan-check.ts +0 -282
- package/src/planning-operations.ts +0 -429
- package/src/prd-operations.ts +0 -690
- package/src/prd.service.ts +0 -1051
- package/src/prompts.ts +0 -110
- package/src/safe-file-name.ts +0 -42
- package/src/schema.ts +0 -976
- package/src/templates.ts +0 -173
- package/src/testing/fake-mcp-server.ts +0 -81
- package/src/types.ts +0 -333
- package/tsconfig.json +0 -23
- package/tsconfig.lib.json +0 -8
- package/tsconfig.spec.json +0 -7
- package/tsdown.config.mts +0 -11
- package/vitest.config.mts +0 -8
- /package/{dist/LICENSE → LICENSE} +0 -0
- /package/{dist/mcp.d.ts → mcp.d.ts} +0 -0
- /package/{dist/node.d.ts → node.d.ts} +0 -0
- /package/{dist/node.js → node.js} +0 -0
- /package/{dist/node.mjs → node.mjs} +0 -0
- /package/{dist/prd.service-DSBp8sMl.d.ts → prd.service-DSBp8sMl.d.ts} +0 -0
|
@@ -1,282 +0,0 @@
|
|
|
1
|
-
import { describe, expect, it } from 'vitest';
|
|
2
|
-
|
|
3
|
-
import { registerPRDTools } from '../mcp';
|
|
4
|
-
import { type PrdDeps, createPrdService } from '../prd.service';
|
|
5
|
-
import { createFakeMcpServer } from '../testing/fake-mcp-server';
|
|
6
|
-
|
|
7
|
-
const normalize = (path: string) => path.replace(/\\/g, '/');
|
|
8
|
-
const basename = (path: string) => normalize(path).split('/').pop() ?? '';
|
|
9
|
-
|
|
10
|
-
function createDeps(files: Record<string, string> = {}): PrdDeps {
|
|
11
|
-
return {
|
|
12
|
-
rootPath: '/repo',
|
|
13
|
-
async readdir() {
|
|
14
|
-
return Object.keys(files);
|
|
15
|
-
},
|
|
16
|
-
async readFile(path) {
|
|
17
|
-
const content = files[basename(path)];
|
|
18
|
-
|
|
19
|
-
if (content === undefined) {
|
|
20
|
-
throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
return content;
|
|
24
|
-
},
|
|
25
|
-
async writeFile(path, content) {
|
|
26
|
-
files[basename(path)] = content;
|
|
27
|
-
},
|
|
28
|
-
async mkdir() {},
|
|
29
|
-
async unlink(path) {
|
|
30
|
-
delete files[basename(path)];
|
|
31
|
-
},
|
|
32
|
-
async fileExists(path) {
|
|
33
|
-
return basename(path) in files;
|
|
34
|
-
},
|
|
35
|
-
now: () => new Date('2026-09-06T10:00:00Z'),
|
|
36
|
-
verifyCompletion: async () => ({
|
|
37
|
-
passed: true,
|
|
38
|
-
checks: ['typecheck', 'lint'],
|
|
39
|
-
errors: 0,
|
|
40
|
-
warnings: 0,
|
|
41
|
-
diagnostics: [],
|
|
42
|
-
messages: [],
|
|
43
|
-
}),
|
|
44
|
-
};
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
const NEW_PRD = {
|
|
48
|
-
title: 'Notes Feature',
|
|
49
|
-
overview: 'Let members keep notes',
|
|
50
|
-
problemStatement: 'Members have nowhere to record context',
|
|
51
|
-
marketOpportunity: 'Table stakes for retention',
|
|
52
|
-
targetUsers: ['Workspace members'],
|
|
53
|
-
solutionDescription: 'A notes surface per account',
|
|
54
|
-
keyFeatures: ['Create note', 'Share note'],
|
|
55
|
-
successMetrics: ['50% of accounts create a note in week one'],
|
|
56
|
-
};
|
|
57
|
-
|
|
58
|
-
async function seed() {
|
|
59
|
-
const fake = createFakeMcpServer();
|
|
60
|
-
const files: Record<string, string> = {};
|
|
61
|
-
|
|
62
|
-
registerPRDTools(fake.server, createPrdService(createDeps(files)));
|
|
63
|
-
|
|
64
|
-
await fake.call('create_prd', NEW_PRD);
|
|
65
|
-
await fake.call('add_user_story', {
|
|
66
|
-
filename: 'notes-feature.json',
|
|
67
|
-
userType: 'member',
|
|
68
|
-
action: 'create a note',
|
|
69
|
-
benefit: 'I can record context',
|
|
70
|
-
acceptanceCriteria: ['Note saves', 'Note appears in the list'],
|
|
71
|
-
});
|
|
72
|
-
|
|
73
|
-
return { fake, files };
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
const read = (files: Record<string, string>) =>
|
|
77
|
-
JSON.parse(files['notes-feature.json']!);
|
|
78
|
-
|
|
79
|
-
describe('registerPRDTools', () => {
|
|
80
|
-
it('registers every tool with a description, annotations and an output schema', () => {
|
|
81
|
-
const fake = createFakeMcpServer();
|
|
82
|
-
|
|
83
|
-
registerPRDTools(fake.server, createPrdService(createDeps()));
|
|
84
|
-
|
|
85
|
-
expect(fake.tools.map((tool) => tool.name).sort()).toEqual([
|
|
86
|
-
'add_attachment',
|
|
87
|
-
'add_decision',
|
|
88
|
-
'add_glossary_term',
|
|
89
|
-
'add_story_log',
|
|
90
|
-
'add_user_story',
|
|
91
|
-
'assign_story_to_phase',
|
|
92
|
-
'check_plan',
|
|
93
|
-
'create_custom_phase',
|
|
94
|
-
'create_prd',
|
|
95
|
-
'decide_edge_case',
|
|
96
|
-
'delete_phase',
|
|
97
|
-
'delete_prd',
|
|
98
|
-
'delete_user_story',
|
|
99
|
-
'export_prd_markdown',
|
|
100
|
-
'get_implementation_prompts',
|
|
101
|
-
'get_improvement_suggestions',
|
|
102
|
-
'get_next_story',
|
|
103
|
-
'get_prd',
|
|
104
|
-
'get_project_status',
|
|
105
|
-
'get_story',
|
|
106
|
-
'list_prds',
|
|
107
|
-
'list_templates',
|
|
108
|
-
'mark_not_applicable',
|
|
109
|
-
'remove_attachment',
|
|
110
|
-
'reorder_phases',
|
|
111
|
-
'resolve_open_question',
|
|
112
|
-
'update_attachment',
|
|
113
|
-
'update_phase',
|
|
114
|
-
'update_prd_section',
|
|
115
|
-
'update_story_status',
|
|
116
|
-
'update_user_story',
|
|
117
|
-
]);
|
|
118
|
-
|
|
119
|
-
for (const tool of fake.tools) {
|
|
120
|
-
expect(tool.config.description, tool.name).toBeTruthy();
|
|
121
|
-
expect(tool.config.outputSchema, tool.name).toBeDefined();
|
|
122
|
-
expect(tool.config.annotations, tool.name).toBeDefined();
|
|
123
|
-
}
|
|
124
|
-
});
|
|
125
|
-
|
|
126
|
-
it('marks the two irreversible tools destructive', () => {
|
|
127
|
-
const fake = createFakeMcpServer();
|
|
128
|
-
|
|
129
|
-
registerPRDTools(fake.server, createPrdService(createDeps()));
|
|
130
|
-
|
|
131
|
-
expect(fake.tool('delete_prd').config.annotations?.destructiveHint).toBe(
|
|
132
|
-
true,
|
|
133
|
-
);
|
|
134
|
-
expect(
|
|
135
|
-
fake.tool('delete_user_story').config.annotations?.destructiveHint,
|
|
136
|
-
).toBe(true);
|
|
137
|
-
});
|
|
138
|
-
|
|
139
|
-
it('round-trips a story edit through the tool boundary', async () => {
|
|
140
|
-
const { fake, files } = await seed();
|
|
141
|
-
|
|
142
|
-
const result = await fake.call('update_user_story', {
|
|
143
|
-
filename: 'notes-feature.json',
|
|
144
|
-
storyId: 'US001',
|
|
145
|
-
title: 'Create a note',
|
|
146
|
-
estimatedComplexity: 'L',
|
|
147
|
-
});
|
|
148
|
-
|
|
149
|
-
expect(result.structuredContent).toMatchObject({
|
|
150
|
-
story_id: 'US001',
|
|
151
|
-
title: 'Create a note',
|
|
152
|
-
updated_fields: ['title', 'estimatedComplexity'],
|
|
153
|
-
});
|
|
154
|
-
expect(read(files).userStories[0].estimatedComplexity).toBe('L');
|
|
155
|
-
});
|
|
156
|
-
|
|
157
|
-
it('reissues no story id after a delete', async () => {
|
|
158
|
-
const { fake, files } = await seed();
|
|
159
|
-
|
|
160
|
-
await fake.call('add_user_story', {
|
|
161
|
-
filename: 'notes-feature.json',
|
|
162
|
-
userType: 'member',
|
|
163
|
-
action: 'share a note',
|
|
164
|
-
benefit: 'my team can read it',
|
|
165
|
-
acceptanceCriteria: ['Share link works'],
|
|
166
|
-
});
|
|
167
|
-
|
|
168
|
-
await fake.call('delete_user_story', {
|
|
169
|
-
filename: 'notes-feature.json',
|
|
170
|
-
storyId: 'US002',
|
|
171
|
-
});
|
|
172
|
-
|
|
173
|
-
await fake.call('add_user_story', {
|
|
174
|
-
filename: 'notes-feature.json',
|
|
175
|
-
userType: 'member',
|
|
176
|
-
action: 'archive a note',
|
|
177
|
-
benefit: 'my list stays short',
|
|
178
|
-
acceptanceCriteria: ['Archived notes hide'],
|
|
179
|
-
});
|
|
180
|
-
|
|
181
|
-
expect(
|
|
182
|
-
read(files).userStories.map((story: { id: string }) => story.id),
|
|
183
|
-
).toEqual(['US001', 'US003']);
|
|
184
|
-
});
|
|
185
|
-
|
|
186
|
-
it('creates a phase and assigns a story to it', async () => {
|
|
187
|
-
const { fake, files } = await seed();
|
|
188
|
-
|
|
189
|
-
const phase = await fake.call('create_custom_phase', {
|
|
190
|
-
filename: 'notes-feature.json',
|
|
191
|
-
name: 'MVP',
|
|
192
|
-
});
|
|
193
|
-
|
|
194
|
-
expect(phase.structuredContent).toMatchObject({
|
|
195
|
-
phase: { id: 'PHASE001', name: 'MVP', order: 0 },
|
|
196
|
-
total_phases: 1,
|
|
197
|
-
});
|
|
198
|
-
|
|
199
|
-
await fake.call('assign_story_to_phase', {
|
|
200
|
-
filename: 'notes-feature.json',
|
|
201
|
-
storyId: 'US001',
|
|
202
|
-
phaseId: 'PHASE001',
|
|
203
|
-
});
|
|
204
|
-
|
|
205
|
-
expect(read(files).customPhases[0].userStoryIds).toEqual(['US001']);
|
|
206
|
-
});
|
|
207
|
-
|
|
208
|
-
it('rejects a bad hex colour before touching the file', async () => {
|
|
209
|
-
const { fake, files } = await seed();
|
|
210
|
-
|
|
211
|
-
const result = await fake.call('create_custom_phase', {
|
|
212
|
-
filename: 'notes-feature.json',
|
|
213
|
-
name: 'MVP',
|
|
214
|
-
color: 'blurple',
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
expect(result.isError).toBe(true);
|
|
218
|
-
expect(read(files).customPhases).toEqual([]);
|
|
219
|
-
});
|
|
220
|
-
|
|
221
|
-
it('grows the change log instead of overwriting it', async () => {
|
|
222
|
-
const { fake, files } = await seed();
|
|
223
|
-
|
|
224
|
-
await fake.call('update_user_story', {
|
|
225
|
-
filename: 'notes-feature.json',
|
|
226
|
-
storyId: 'US001',
|
|
227
|
-
priority: 'P0',
|
|
228
|
-
});
|
|
229
|
-
await fake.call('update_story_status', {
|
|
230
|
-
filename: 'notes-feature.json',
|
|
231
|
-
storyId: 'US001',
|
|
232
|
-
status: 'in_progress',
|
|
233
|
-
});
|
|
234
|
-
|
|
235
|
-
expect(read(files).changeLog).toEqual([
|
|
236
|
-
'Initial PRD created',
|
|
237
|
-
'2026-09-06: Added US001 (Create A Note)',
|
|
238
|
-
'2026-09-06: Updated US001 (priority)',
|
|
239
|
-
'2026-09-06: US001 not_started -> in_progress',
|
|
240
|
-
]);
|
|
241
|
-
});
|
|
242
|
-
|
|
243
|
-
it('stamps lastValidatedAt only when verification actually ran', async () => {
|
|
244
|
-
const { fake, files } = await seed();
|
|
245
|
-
|
|
246
|
-
await fake.call('update_story_status', {
|
|
247
|
-
filename: 'notes-feature.json',
|
|
248
|
-
storyId: 'US001',
|
|
249
|
-
status: 'in_progress',
|
|
250
|
-
});
|
|
251
|
-
|
|
252
|
-
expect(read(files).metadata.lastValidatedAt).toBe('2026-09-06');
|
|
253
|
-
|
|
254
|
-
await fake.call('update_story_status', {
|
|
255
|
-
filename: 'notes-feature.json',
|
|
256
|
-
storyId: 'US001',
|
|
257
|
-
status: 'completed',
|
|
258
|
-
});
|
|
259
|
-
|
|
260
|
-
expect(read(files).userStories[0].verification.passed).toBe(true);
|
|
261
|
-
});
|
|
262
|
-
|
|
263
|
-
it('honours an explicit title and complexity instead of guessing', async () => {
|
|
264
|
-
const { fake, files } = await seed();
|
|
265
|
-
|
|
266
|
-
await fake.call('add_user_story', {
|
|
267
|
-
filename: 'notes-feature.json',
|
|
268
|
-
userType: 'member',
|
|
269
|
-
action: 'export every note as a zip archive for offline backup',
|
|
270
|
-
benefit: 'I keep my own copy',
|
|
271
|
-
acceptanceCriteria: ['Zip downloads'],
|
|
272
|
-
title: 'Bulk note export',
|
|
273
|
-
estimatedComplexity: 'XL',
|
|
274
|
-
});
|
|
275
|
-
|
|
276
|
-
const story = read(files).userStories[1];
|
|
277
|
-
|
|
278
|
-
// Without the override this would be "Export Every Note As".
|
|
279
|
-
expect(story.title).toBe('Bulk note export');
|
|
280
|
-
expect(story.estimatedComplexity).toBe('XL');
|
|
281
|
-
});
|
|
282
|
-
});
|
|
@@ -1,141 +0,0 @@
|
|
|
1
|
-
import { describe, expect, it } from 'vitest';
|
|
2
|
-
|
|
3
|
-
import { registerPRDTools } from '../mcp';
|
|
4
|
-
import { type PrdDeps, createPrdService } from '../prd.service';
|
|
5
|
-
import { PRD_TEMPLATES, TEMPLATE_IDS } from '../templates';
|
|
6
|
-
import { createFakeMcpServer } from '../testing/fake-mcp-server';
|
|
7
|
-
import type { StructuredPRD } from '../types';
|
|
8
|
-
|
|
9
|
-
const basename = (path: string) => path.replace(/\\/g, '/').split('/').pop()!;
|
|
10
|
-
|
|
11
|
-
function createDeps(files: Record<string, string>): PrdDeps {
|
|
12
|
-
return {
|
|
13
|
-
rootPath: '/repo',
|
|
14
|
-
async readdir() {
|
|
15
|
-
return Object.keys(files);
|
|
16
|
-
},
|
|
17
|
-
async readFile(path) {
|
|
18
|
-
const content = files[basename(path)];
|
|
19
|
-
if (content === undefined) throw new Error('ENOENT');
|
|
20
|
-
return content;
|
|
21
|
-
},
|
|
22
|
-
async writeFile(path, content) {
|
|
23
|
-
files[basename(path)] = content;
|
|
24
|
-
},
|
|
25
|
-
async mkdir() {},
|
|
26
|
-
async unlink(path) {
|
|
27
|
-
delete files[basename(path)];
|
|
28
|
-
},
|
|
29
|
-
async fileExists(path) {
|
|
30
|
-
return basename(path) in files;
|
|
31
|
-
},
|
|
32
|
-
now: () => new Date('2026-10-14T10:00:00Z'),
|
|
33
|
-
verifyCompletion: async () => ({
|
|
34
|
-
passed: true,
|
|
35
|
-
checks: [],
|
|
36
|
-
errors: 0,
|
|
37
|
-
warnings: 0,
|
|
38
|
-
diagnostics: [],
|
|
39
|
-
messages: [],
|
|
40
|
-
}),
|
|
41
|
-
};
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
const BASE = {
|
|
45
|
-
title: 'Team notes',
|
|
46
|
-
overview: 'Notes shared within a team',
|
|
47
|
-
problemStatement: 'Context gets lost',
|
|
48
|
-
marketOpportunity: 'Retention',
|
|
49
|
-
targetUsers: ['Team members'],
|
|
50
|
-
solutionDescription: 'Notes per team account',
|
|
51
|
-
keyFeatures: ['Create note'],
|
|
52
|
-
successMetrics: ['Notes created per team'],
|
|
53
|
-
};
|
|
54
|
-
|
|
55
|
-
describe('templates', () => {
|
|
56
|
-
it('has one entry per id, each with interview focus questions', () => {
|
|
57
|
-
expect(PRD_TEMPLATES.map((template) => template.id)).toEqual([
|
|
58
|
-
...TEMPLATE_IDS,
|
|
59
|
-
]);
|
|
60
|
-
|
|
61
|
-
for (const template of PRD_TEMPLATES) {
|
|
62
|
-
expect(template.interviewFocus.length).toBeGreaterThan(0);
|
|
63
|
-
}
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
it('fills empty sections from the template', async () => {
|
|
67
|
-
const files: Record<string, string> = {};
|
|
68
|
-
const service = createPrdService(createDeps(files));
|
|
69
|
-
|
|
70
|
-
const { filename } = await service.create({
|
|
71
|
-
...BASE,
|
|
72
|
-
template: 'saas-feature',
|
|
73
|
-
});
|
|
74
|
-
const prd = JSON.parse(files[filename]!) as StructuredPRD;
|
|
75
|
-
|
|
76
|
-
expect(prd.acceptanceCriteria.global.length).toBeGreaterThan(0);
|
|
77
|
-
expect(prd.rolloutPlan.rolloutPhases.length).toBeGreaterThan(0);
|
|
78
|
-
expect(prd.openQuestions.map((q) => q.question)).toContain(
|
|
79
|
-
'Which roles can view, create, edit and delete it?',
|
|
80
|
-
);
|
|
81
|
-
expect(prd.changeLog[0]).toContain('saas-feature');
|
|
82
|
-
});
|
|
83
|
-
|
|
84
|
-
it('keeps values given by the caller and appends template questions', async () => {
|
|
85
|
-
const files: Record<string, string> = {};
|
|
86
|
-
const service = createPrdService(createDeps(files));
|
|
87
|
-
|
|
88
|
-
const { filename } = await service.create({
|
|
89
|
-
...BASE,
|
|
90
|
-
template: 'internal-tool',
|
|
91
|
-
nonGoals: ['Mobile app'],
|
|
92
|
-
openQuestions: ['Who approves notes?'],
|
|
93
|
-
});
|
|
94
|
-
const prd = JSON.parse(files[filename]!) as StructuredPRD;
|
|
95
|
-
|
|
96
|
-
expect(prd.nonGoals).toEqual(['Mobile app']);
|
|
97
|
-
expect(prd.openQuestions[0]).toEqual({ id: 'Q001', question: 'Who approves notes?' });
|
|
98
|
-
expect(prd.openQuestions.length).toBeGreaterThan(1);
|
|
99
|
-
});
|
|
100
|
-
|
|
101
|
-
it('is exposed through list_templates, create_prd and shape_prd', async () => {
|
|
102
|
-
const fake = createFakeMcpServer();
|
|
103
|
-
const files: Record<string, string> = {};
|
|
104
|
-
|
|
105
|
-
registerPRDTools(fake.server, createPrdService(createDeps(files)));
|
|
106
|
-
|
|
107
|
-
const listed = await fake.call('list_templates');
|
|
108
|
-
expect(
|
|
109
|
-
(
|
|
110
|
-
listed.structuredContent as { templates: { id: string }[] }
|
|
111
|
-
).templates.map((t) => t.id),
|
|
112
|
-
).toEqual([...TEMPLATE_IDS]);
|
|
113
|
-
|
|
114
|
-
const created = await fake.call('create_prd', {
|
|
115
|
-
...BASE,
|
|
116
|
-
template: 'integration',
|
|
117
|
-
});
|
|
118
|
-
expect(created.isError).toBeFalsy();
|
|
119
|
-
|
|
120
|
-
const invalid = await fake.call('create_prd', {
|
|
121
|
-
...BASE,
|
|
122
|
-
title: 'Other',
|
|
123
|
-
template: 'nope',
|
|
124
|
-
});
|
|
125
|
-
expect(invalid.isError).toBe(true);
|
|
126
|
-
|
|
127
|
-
const prompt = fake.prompts.find((entry) => entry.name === 'shape_prd')!;
|
|
128
|
-
const withTemplate = prompt.handler({
|
|
129
|
-
idea: 'Stripe sync',
|
|
130
|
-
template: 'integration',
|
|
131
|
-
}).messages[0]!.content.text;
|
|
132
|
-
const without = prompt.handler({ idea: 'Stripe sync' }).messages[0]!.content
|
|
133
|
-
.text;
|
|
134
|
-
|
|
135
|
-
expect(withTemplate).toContain('template "integration"');
|
|
136
|
-
expect(withTemplate).toContain(
|
|
137
|
-
'What does the user see while the service is unavailable?',
|
|
138
|
-
);
|
|
139
|
-
expect(without).toContain('list_templates');
|
|
140
|
-
});
|
|
141
|
-
});
|
package/src/applicability.ts
DELETED
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
import { appendChangeLog } from './prd-operations';
|
|
2
|
-
import type { NotApplicableTopic, StructuredPRD } from './types';
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* Parts of a PRD that can be marked "not applicable" (e.g. no rollout plan
|
|
6
|
-
* for an internal tool), so the plan check stops asking for them and agents
|
|
7
|
-
* do not invent them. The core (overview, problem, solution, scope, stories)
|
|
8
|
-
* always applies.
|
|
9
|
-
*/
|
|
10
|
-
export const NOT_APPLICABLE_TOPICS = [
|
|
11
|
-
'dataModel',
|
|
12
|
-
'outsideServices',
|
|
13
|
-
'security',
|
|
14
|
-
'design',
|
|
15
|
-
'qualityBar',
|
|
16
|
-
'edgeCases',
|
|
17
|
-
'rollout',
|
|
18
|
-
'measurement',
|
|
19
|
-
'glossary',
|
|
20
|
-
'risks',
|
|
21
|
-
] as const satisfies readonly NotApplicableTopic[];
|
|
22
|
-
|
|
23
|
-
export function isNotApplicable(prd: StructuredPRD, topic: NotApplicableTopic) {
|
|
24
|
-
return prd.notApplicable[topic] !== undefined;
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
/** Stored values, with unknown topics and non-string reasons dropped. */
|
|
28
|
-
export function normalizeNotApplicable(
|
|
29
|
-
value: unknown,
|
|
30
|
-
): StructuredPRD['notApplicable'] {
|
|
31
|
-
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
32
|
-
return {};
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
const topics = new Set<string>(NOT_APPLICABLE_TOPICS);
|
|
36
|
-
|
|
37
|
-
return Object.fromEntries(
|
|
38
|
-
Object.entries(value as Record<string, unknown>).filter(
|
|
39
|
-
([topic, reason]) => topics.has(topic) && typeof reason === 'string',
|
|
40
|
-
),
|
|
41
|
-
);
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
export function setNotApplicable(
|
|
45
|
-
prd: StructuredPRD,
|
|
46
|
-
input: { topic: NotApplicableTopic; notApplicable: boolean; reason?: string },
|
|
47
|
-
today: string,
|
|
48
|
-
) {
|
|
49
|
-
if (input.notApplicable) {
|
|
50
|
-
prd.notApplicable = {
|
|
51
|
-
...prd.notApplicable,
|
|
52
|
-
[input.topic]: input.reason?.trim() ?? '',
|
|
53
|
-
};
|
|
54
|
-
} else {
|
|
55
|
-
const { [input.topic]: _removed, ...rest } = prd.notApplicable;
|
|
56
|
-
|
|
57
|
-
prd.notApplicable = rest;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
appendChangeLog(
|
|
61
|
-
prd,
|
|
62
|
-
input.notApplicable
|
|
63
|
-
? `Marked ${input.topic} not applicable`
|
|
64
|
-
: `Marked ${input.topic} applicable`,
|
|
65
|
-
today,
|
|
66
|
-
);
|
|
67
|
-
|
|
68
|
-
return {
|
|
69
|
-
topic: input.topic,
|
|
70
|
-
not_applicable: input.notApplicable,
|
|
71
|
-
reason: prd.notApplicable[input.topic] ?? null,
|
|
72
|
-
};
|
|
73
|
-
}
|
package/src/attachment-paths.ts
DELETED
|
@@ -1,78 +0,0 @@
|
|
|
1
|
-
import { assertSafeRelativePath } from './safe-file-name';
|
|
2
|
-
import type { StoryAttachment } from './schema';
|
|
3
|
-
import type { Attachment } from './types';
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* The folder for a PRD's files, relative to `.prds`: the PRD file name
|
|
7
|
-
* without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
|
|
8
|
-
*/
|
|
9
|
-
export function attachmentsFolder(filename: string) {
|
|
10
|
-
return filename.replace(/\.json$/, '');
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
/** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
|
|
14
|
-
export function attachmentProjectPath(filename: string, path: string) {
|
|
15
|
-
return `.prds/${attachmentsFolder(filename)}/${path}`;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
/** Attachments as an agent needs them: file paths from the project root. */
|
|
19
|
-
export function resolveAttachments(
|
|
20
|
-
filename: string,
|
|
21
|
-
attachments: Attachment[],
|
|
22
|
-
): StoryAttachment[] {
|
|
23
|
-
return attachments.map(({ path, ...attachment }) => ({
|
|
24
|
-
...attachment,
|
|
25
|
-
...(path ? { path: attachmentProjectPath(filename, path) } : {}),
|
|
26
|
-
}));
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
/**
|
|
30
|
-
* Attachments as stored, with hand-edited entries that would break readers
|
|
31
|
-
* or point outside the PRD folder dropped: each needs a string id and title
|
|
32
|
-
* and either a safe relative path or an http(s) url.
|
|
33
|
-
*/
|
|
34
|
-
export function normalizeAttachments(value: unknown): Attachment[] {
|
|
35
|
-
if (!Array.isArray(value)) {
|
|
36
|
-
return [];
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
return value.flatMap((entry): Attachment[] => {
|
|
40
|
-
if (typeof entry !== 'object' || entry === null) {
|
|
41
|
-
return [];
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
const { id, title, path, url, note } = entry as Record<string, unknown>;
|
|
45
|
-
|
|
46
|
-
if (typeof id !== 'string' || typeof title !== 'string') {
|
|
47
|
-
return [];
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
const base = {
|
|
51
|
-
id,
|
|
52
|
-
title,
|
|
53
|
-
...(typeof note === 'string' && note ? { note } : {}),
|
|
54
|
-
};
|
|
55
|
-
|
|
56
|
-
if (typeof path === 'string' && url === undefined && isSafePath(path)) {
|
|
57
|
-
return [{ ...base, path }];
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
if (
|
|
61
|
-
typeof url === 'string' &&
|
|
62
|
-
path === undefined &&
|
|
63
|
-
/^https?:\/\//i.test(url)
|
|
64
|
-
) {
|
|
65
|
-
return [{ ...base, url }];
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
return [];
|
|
69
|
-
});
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
function isSafePath(path: string) {
|
|
73
|
-
try {
|
|
74
|
-
return assertSafeRelativePath(path) === path;
|
|
75
|
-
} catch {
|
|
76
|
-
return false;
|
|
77
|
-
}
|
|
78
|
-
}
|