@makerkit/prd 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/.turbo/turbo-build.log +46 -0
  2. package/.turbo/turbo-test.log +21 -0
  3. package/.turbo/turbo-typecheck.log +1 -0
  4. package/README.md +64 -2
  5. package/dist/LICENSE +21 -0
  6. package/dist/README.md +65 -0
  7. package/dist/index.d.ts +227 -0
  8. package/dist/index.js +1897 -0
  9. package/dist/index.mjs +1791 -0
  10. package/dist/mcp.d.ts +9 -0
  11. package/dist/mcp.js +532 -0
  12. package/dist/mcp.mjs +531 -0
  13. package/dist/node.d.ts +19 -0
  14. package/dist/node.js +94 -0
  15. package/dist/node.mjs +92 -0
  16. package/dist/package.json +49 -0
  17. package/dist/prd.service-DSBp8sMl.d.ts +2327 -0
  18. package/dist/prompts-Bber0S1Z.mjs +778 -0
  19. package/dist/prompts-CIX8IeAx.js +1233 -0
  20. package/package.json +66 -4
  21. package/src/__tests__/agent-workflow.test.ts +377 -0
  22. package/src/__tests__/attachments.test.ts +475 -0
  23. package/src/__tests__/node.test.ts +141 -0
  24. package/src/__tests__/plan-check.test.ts +229 -0
  25. package/src/__tests__/planning.test.ts +1059 -0
  26. package/src/__tests__/prd-operations.test.ts +423 -0
  27. package/src/__tests__/prd.service.test.ts +477 -0
  28. package/src/__tests__/prd.tool.test.ts +282 -0
  29. package/src/__tests__/templates.test.ts +141 -0
  30. package/src/applicability.ts +73 -0
  31. package/src/attachment-paths.ts +78 -0
  32. package/src/attachments.ts +160 -0
  33. package/src/edge-cases.ts +52 -0
  34. package/src/index.ts +35 -0
  35. package/src/markdown.ts +268 -0
  36. package/src/mcp/index.ts +839 -0
  37. package/src/mcp/tool-response.ts +85 -0
  38. package/src/node.ts +146 -0
  39. package/src/open-questions.ts +93 -0
  40. package/src/plan-check.ts +282 -0
  41. package/src/planning-operations.ts +429 -0
  42. package/src/prd-operations.ts +690 -0
  43. package/src/prd.service.ts +1051 -0
  44. package/src/prompts.ts +110 -0
  45. package/src/safe-file-name.ts +42 -0
  46. package/src/schema.ts +976 -0
  47. package/src/templates.ts +173 -0
  48. package/src/testing/fake-mcp-server.ts +81 -0
  49. package/src/types.ts +333 -0
  50. package/tsconfig.json +23 -0
  51. package/tsconfig.lib.json +8 -0
  52. package/tsconfig.spec.json +7 -0
  53. package/tsdown.config.mts +11 -0
  54. package/vitest.config.mts +8 -0
package/package.json CHANGED
@@ -1,6 +1,68 @@
1
1
  {
2
2
  "name": "@makerkit/prd",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
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
+ "./mcp": {
32
+ "types": "./mcp.d.ts",
33
+ "import": "./mcp.mjs",
34
+ "require": "./mcp.js"
35
+ }
36
+ },
37
+ "publishConfig": {
38
+ "access": "public",
39
+ "directory": "dist",
40
+ "linkDirectory": true
41
+ },
42
+ "scripts": {
43
+ "build": "tsdown && node ../../scripts/prepare-dist.mjs",
44
+ "typecheck": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.spec.json",
45
+ "test": "vitest run"
46
+ },
47
+ "dependencies": {
48
+ "@makerkit/repo-checks": "workspace:^",
49
+ "zod": "^3.25.0 || ^4.0.0"
50
+ },
51
+ "devDependencies": {
52
+ "@modelcontextprotocol/sdk": "catalog:",
53
+ "@types/node": "catalog:",
54
+ "tsdown": "catalog:",
55
+ "typescript": "catalog:",
56
+ "vite": "catalog:",
57
+ "vitest": "catalog:",
58
+ "zod": "catalog:"
59
+ },
60
+ "peerDependencies": {
61
+ "@modelcontextprotocol/sdk": "^1.32.0"
62
+ },
63
+ "peerDependenciesMeta": {
64
+ "@modelcontextprotocol/sdk": {
65
+ "optional": true
66
+ }
67
+ }
68
+ }
@@ -0,0 +1,377 @@
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
+ import type { StructuredPRD } from '../types';
7
+
8
+ const basename = (path: string) => path.replace(/\\/g, '/').split('/').pop()!;
9
+
10
+ function createDeps(files: Record<string, string>, hooks: Hooks = {}) {
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
+ hooks.beforeExists?.(basename(path));
34
+ return basename(path) in files;
35
+ },
36
+ now: () => new Date('2026-10-14T10:00:00Z'),
37
+ verifyCompletion: async () => ({
38
+ passed: true,
39
+ checks: ['typecheck'],
40
+ errors: 0,
41
+ warnings: 0,
42
+ diagnostics: [],
43
+ messages: [],
44
+ }),
45
+ } satisfies PrdDeps;
46
+ }
47
+
48
+ interface Hooks {
49
+ beforeExists?: (file: string) => void;
50
+ }
51
+
52
+ const STORY = {
53
+ userType: 'member',
54
+ benefit: 'it helps',
55
+ acceptanceCriteria: ['works'],
56
+ };
57
+
58
+ /** A PRD with US001 <- US002 (depends on US001) and an independent US003. */
59
+ async function seed(hooks: Hooks = {}) {
60
+ const files: Record<string, string> = {};
61
+ const service = createPrdService(createDeps(files, hooks));
62
+
63
+ const { filename } = await service.create({
64
+ title: 'Notes',
65
+ overview: 'Let members keep notes',
66
+ problemStatement: 'No place for context',
67
+ marketOpportunity: 'Retention',
68
+ targetUsers: ['Members'],
69
+ solutionDescription: 'Notes per account',
70
+ keyFeatures: ['Create note'],
71
+ successMetrics: ['Notes created'],
72
+ nonGoals: ['Rich text'],
73
+ });
74
+
75
+ await service.addUserStory({
76
+ ...STORY,
77
+ filename,
78
+ action: 'create a note',
79
+ priority: 'P2',
80
+ });
81
+ await service.addUserStory({
82
+ ...STORY,
83
+ filename,
84
+ action: 'share a note',
85
+ priority: 'P2',
86
+ });
87
+ await service.addUserStory({
88
+ ...STORY,
89
+ filename,
90
+ action: 'pin a note',
91
+ priority: 'P1',
92
+ });
93
+ await service.updateUserStory({
94
+ filename,
95
+ storyId: 'US002',
96
+ dependencies: ['US001'],
97
+ });
98
+
99
+ const read = () => JSON.parse(files[filename]!) as StructuredPRD;
100
+
101
+ return { files, filename, service, read };
102
+ }
103
+
104
+ describe('story workflow', () => {
105
+ it('rejects starting a story before its dependencies are completed', async () => {
106
+ const { filename, service } = await seed();
107
+
108
+ await expect(
109
+ service.updateStoryStatus({
110
+ filename,
111
+ storyId: 'US002',
112
+ status: 'in_progress',
113
+ }),
114
+ ).rejects.toThrow(/depends on US001/);
115
+
116
+ await expect(
117
+ service.updateStoryStatus({
118
+ filename,
119
+ storyId: 'US002',
120
+ status: 'completed',
121
+ }),
122
+ ).rejects.toThrow(/depends on US001/);
123
+ });
124
+
125
+ it('still allows planning or parking a waiting story', async () => {
126
+ const { filename, service } = await seed();
127
+
128
+ await expect(
129
+ service.updateStoryStatus({
130
+ filename,
131
+ storyId: 'US002',
132
+ status: 'research',
133
+ }),
134
+ ).resolves.toMatchObject({ status: 'research' });
135
+
136
+ await expect(
137
+ service.updateStoryStatus({
138
+ filename,
139
+ storyId: 'US002',
140
+ status: 'blocked',
141
+ }),
142
+ ).resolves.toMatchObject({ status: 'blocked' });
143
+ });
144
+
145
+ it('allows the story once its dependencies are completed', async () => {
146
+ const { filename, service } = await seed();
147
+
148
+ await service.updateStoryStatus({
149
+ filename,
150
+ storyId: 'US001',
151
+ status: 'completed',
152
+ });
153
+
154
+ await expect(
155
+ service.updateStoryStatus({
156
+ filename,
157
+ storyId: 'US002',
158
+ status: 'in_progress',
159
+ }),
160
+ ).resolves.toMatchObject({ status: 'in_progress' });
161
+ });
162
+ });
163
+
164
+ describe('getNextStory', () => {
165
+ it('prefers higher priority among ready stories and lists waiting ones', async () => {
166
+ const { filename, service } = await seed();
167
+
168
+ const next = await service.getNextStory(filename);
169
+
170
+ expect(next.story?.id).toBe('US003');
171
+ expect(next.ready_count).toBe(2);
172
+ expect(next.waiting).toEqual([
173
+ { id: 'US002', title: expect.any(String), waiting_on: ['US001'] },
174
+ ]);
175
+ });
176
+
177
+ it('orders by phase before priority', async () => {
178
+ const { filename, service } = await seed();
179
+
180
+ const { phase } = await service.createCustomPhase({
181
+ filename,
182
+ name: 'Milestone 1',
183
+ description: '',
184
+ color: '#4f46e5',
185
+ });
186
+ await service.assignStoryToPhase({
187
+ filename,
188
+ storyId: 'US001',
189
+ phaseId: phase.id,
190
+ });
191
+
192
+ const next = await service.getNextStory(filename);
193
+
194
+ expect(next.story?.id).toBe('US001');
195
+ });
196
+
197
+ it('returns null when nothing is ready', async () => {
198
+ const { filename, service } = await seed();
199
+
200
+ for (const storyId of ['US001', 'US003']) {
201
+ await service.updateStoryStatus({
202
+ filename,
203
+ storyId,
204
+ status: 'in_progress',
205
+ });
206
+ }
207
+
208
+ const next = await service.getNextStory(filename);
209
+
210
+ expect(next.story).toBeNull();
211
+ expect(next.in_progress).toEqual(['US001', 'US003']);
212
+ expect(next.waiting.map((entry) => entry.id)).toEqual(['US002']);
213
+ });
214
+ });
215
+
216
+ describe('story logs and context', () => {
217
+ it('appends hand-off logs and returns them in the dependent story context', async () => {
218
+ const { filename, service } = await seed();
219
+
220
+ await service.addStoryLog({
221
+ filename,
222
+ storyId: 'US001',
223
+ whatsNew: ['You can create a note from the sidebar'],
224
+ technicalNotes: ['Notes table has RLS by account_id'],
225
+ });
226
+ await service.updateStoryStatus({
227
+ filename,
228
+ storyId: 'US001',
229
+ status: 'completed',
230
+ });
231
+
232
+ const context = await service.getStory({ filename, storyId: 'US002' });
233
+
234
+ expect(context.prd.non_goals).toEqual(['Rich text']);
235
+ expect(context.dependencies).toEqual([
236
+ {
237
+ id: 'US001',
238
+ title: expect.any(String),
239
+ status: 'completed',
240
+ log: [
241
+ {
242
+ at: '2026-10-14T10:00:00.000Z',
243
+ whatsNew: ['You can create a note from the sidebar'],
244
+ technicalNotes: ['Notes table has RLS by account_id'],
245
+ },
246
+ ],
247
+ },
248
+ ]);
249
+ expect(context.previous_story?.id).toBe('US001');
250
+ });
251
+
252
+ it('stores deviations only when there are some', async () => {
253
+ const { filename, service, read } = await seed();
254
+
255
+ await service.addStoryLog({
256
+ filename,
257
+ storyId: 'US001',
258
+ whatsNew: ['a'],
259
+ technicalNotes: [],
260
+ deviations: ['Used a modal instead of a page: the sidebar has no room'],
261
+ });
262
+ await service.addStoryLog({
263
+ filename,
264
+ storyId: 'US001',
265
+ whatsNew: ['b'],
266
+ technicalNotes: [],
267
+ deviations: [],
268
+ });
269
+
270
+ const log = read().userStories.find((story) => story.id === 'US001')!.log!;
271
+
272
+ expect(log[0]!.deviations).toEqual([
273
+ 'Used a modal instead of a page: the sidebar has no room',
274
+ ]);
275
+ expect(log[1]).not.toHaveProperty('deviations');
276
+ });
277
+
278
+ it('keeps earlier log entries', async () => {
279
+ const { filename, service } = await seed();
280
+
281
+ await service.addStoryLog({
282
+ filename,
283
+ storyId: 'US001',
284
+ whatsNew: ['a'],
285
+ technicalNotes: [],
286
+ });
287
+ const result = await service.addStoryLog({
288
+ filename,
289
+ storyId: 'US001',
290
+ whatsNew: ['b'],
291
+ technicalNotes: [],
292
+ });
293
+
294
+ expect(result.entries).toBe(2);
295
+ });
296
+ });
297
+
298
+ describe('revision check', () => {
299
+ it('increments the revision on every write', async () => {
300
+ const { read } = await seed();
301
+
302
+ // create + 3 stories + 1 update
303
+ expect(read().metadata.revision).toBe(4);
304
+ });
305
+
306
+ it('rejects a write when the file changed after it was read', async () => {
307
+ let interfere = false;
308
+ const hooks: Hooks = {};
309
+ const { filename, service, files, read } = await seed(hooks);
310
+
311
+ hooks.beforeExists = (file) => {
312
+ if (!interfere) return;
313
+ interfere = false;
314
+
315
+ // Another writer saves between our read and our write.
316
+ const other = JSON.parse(files[file]!) as StructuredPRD;
317
+ other.metadata.revision = (other.metadata.revision ?? 0) + 1;
318
+ other.introduction.overview = 'Changed elsewhere';
319
+ files[file] = JSON.stringify(other);
320
+ };
321
+
322
+ interfere = true;
323
+
324
+ await expect(
325
+ service.addStoryLog({
326
+ filename,
327
+ storyId: 'US001',
328
+ whatsNew: ['x'],
329
+ technicalNotes: [],
330
+ }),
331
+ ).rejects.toThrow(/changed by someone else/);
332
+
333
+ expect(read().introduction.overview).toBe('Changed elsewhere');
334
+ expect(read().userStories[0]?.log).toBeUndefined();
335
+ });
336
+ });
337
+
338
+ describe('MCP registration', () => {
339
+ it('registers the workflow tools and the implement_story prompt', async () => {
340
+ const fake = createFakeMcpServer();
341
+ const { files, filename } = await seed();
342
+
343
+ registerPRDTools(fake.server, createPrdService(createDeps(files)));
344
+
345
+ const next = await fake.call('get_next_story', { filename });
346
+ expect(next.structuredContent).toMatchObject({ story: { id: 'US003' } });
347
+
348
+ await fake.call('get_story', { filename, storyId: 'US002' });
349
+ await fake.call('add_story_log', {
350
+ filename,
351
+ storyId: 'US001',
352
+ whatsNew: ['x'],
353
+ });
354
+
355
+ const prompt = fake.prompts.find(
356
+ (entry) => entry.name === 'implement_story',
357
+ );
358
+ const text = prompt!.handler({ filename }).messages[0]!.content.text;
359
+
360
+ expect(text).toContain('get_next_story');
361
+ expect(text).toContain('add_story_log');
362
+ expect(text).toContain('deviations');
363
+ expect(text).not.toContain('run_checks');
364
+
365
+ const review = fake.prompts.find((entry) => entry.name === 'review_story');
366
+ const reviewText = review!.handler({
367
+ filename,
368
+ storyId: 'US001',
369
+ base: 'main',
370
+ }).messages[0]!.content.text;
371
+
372
+ expect(reviewText).toContain('git diff main');
373
+ expect(reviewText).toContain('get_story');
374
+ expect(reviewText).toMatch(/Do not change the story status/);
375
+ expect(reviewText).toContain('deviations');
376
+ });
377
+ });