@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/dist/mcp.mjs ADDED
@@ -0,0 +1,531 @@
1
+ import { A as ExportPrdMarkdownInputSchema, B as GetProjectStatusInputSchema, C as DecideEdgeCaseInputSchema, D as DeletePrdOutputSchema, E as DeletePrdInputSchema, F as GetImprovementSuggestionsOutputSchema, G as ListPrdsOutputSchema, H as GetStoryInputSchema, I as GetNextStoryInputSchema, J as MarkNotApplicableInputSchema, K as ListTemplatesInputSchema, L as GetNextStoryOutputSchema, M as GetImplementationPromptsInputSchema, N as GetImplementationPromptsOutputSchema, O as DeleteUserStoryInputSchema, P as GetImprovementSuggestionsInputSchema, R as GetPrdInputSchema, T as DeletePhaseInputSchema, U as GetStoryOutputSchema, V as GetProjectStatusOutputSchema, W as ListPrdsInputSchema, Y as MarkNotApplicableOutputSchema, Z as PhasesOutputSchema, _ as CheckPlanOutputSchema, _t as UpdateStoryStatusOutputSchema, a as AddAttachmentOutputSchema, b as CreatePrdInputSchema, c as AddGlossaryTermInputSchema, d as AddStoryLogOutputSchema, dt as UpdateAttachmentInputSchema, et as RemoveAttachmentInputSchema, f as AddUserStoryInputSchema, ft as UpdateAttachmentOutputSchema, g as CheckPlanInputSchema, gt as UpdateStoryStatusInputSchema, h as AssignStoryToPhaseOutputSchema, ht as UpdatePrdSectionOutputSchema, i as AddAttachmentInputSchema, it as ResolveOpenQuestionOutputSchema, j as ExportPrdMarkdownOutputSchema, k as DeleteUserStoryOutputSchema, l as AddGlossaryTermOutputSchema, m as AssignStoryToPhaseInputSchema, mt as UpdatePrdSectionInputSchema, n as reviewStoryPrompt, nt as ReorderPhasesInputSchema, o as AddDecisionInputSchema, p as AddUserStoryOutputSchema, pt as UpdatePhaseInputSchema, q as ListTemplatesOutputSchema, r as shapePrdPrompt, rt as ResolveOpenQuestionInputSchema, s as AddDecisionOutputSchema, t as implementStoryPrompt, tt as RemoveAttachmentOutputSchema, u as AddStoryLogInputSchema, v as CreateCustomPhaseInputSchema, vt as UpdateUserStoryInputSchema, w as DecideEdgeCaseOutputSchema, x as CreatePrdOutputSchema, xt as TEMPLATE_IDS, y as CreateCustomPhaseOutputSchema, yt as UpdateUserStoryOutputSchema, z as GetPrdOutputSchema } from "./prompts-Bber0S1Z.mjs";
2
+ import { z } from "zod/v3";
3
+ //#region src/mcp/tool-response.ts
4
+ /**
5
+ * Standard annotation presets. Every registered tool must declare one so MCP
6
+ * clients can gate permissions correctly (e.g. auto-approve read-only tools,
7
+ * always confirm destructive ones).
8
+ */
9
+ const READ_ONLY_TOOL = {
10
+ readOnlyHint: true,
11
+ destructiveHint: false,
12
+ idempotentHint: true,
13
+ openWorldHint: false
14
+ };
15
+ /** Writes files or state but can be re-applied safely and is reversible. */
16
+ const MUTATING_TOOL = {
17
+ readOnlyHint: false,
18
+ destructiveHint: false,
19
+ idempotentHint: false,
20
+ openWorldHint: false
21
+ };
22
+ /** Same as MUTATING_TOOL but repeating the call has no further effect. */
23
+ const IDEMPOTENT_MUTATING_TOOL = {
24
+ readOnlyHint: false,
25
+ destructiveHint: false,
26
+ idempotentHint: true,
27
+ openWorldHint: false
28
+ };
29
+ /** Deletes or irreversibly replaces data. Clients should always confirm. */
30
+ const DESTRUCTIVE_TOOL = {
31
+ readOnlyHint: false,
32
+ destructiveHint: true,
33
+ idempotentHint: false,
34
+ openWorldHint: false
35
+ };
36
+ function buildStructuredResponse(result) {
37
+ return {
38
+ structuredContent: result,
39
+ content: buildTextContent(JSON.stringify(result))
40
+ };
41
+ }
42
+ function buildErrorResponse(tool, error) {
43
+ const message = `${tool} failed: ${toErrorMessage(error)}`;
44
+ return {
45
+ isError: true,
46
+ structuredContent: { error: { message } },
47
+ content: buildTextContent(message)
48
+ };
49
+ }
50
+ function toErrorMessage(error) {
51
+ if (error instanceof Error) return error.message;
52
+ return "Unknown error";
53
+ }
54
+ function buildTextContent(text) {
55
+ return [{
56
+ type: "text",
57
+ text
58
+ }];
59
+ }
60
+ //#endregion
61
+ //#region src/mcp/index.ts
62
+ /**
63
+ * Registers the PRD tools on an MCP server. The caller builds the service, so
64
+ * it decides where PRDs live and which checks gate a story's completion.
65
+ */
66
+ function registerPRDTools(server, service) {
67
+ server.registerTool("list_prds", {
68
+ title: "List PRDs",
69
+ description: "List Product Requirements Documents in .prds with title and story progress.",
70
+ inputSchema: ListPrdsInputSchema,
71
+ outputSchema: ListPrdsOutputSchema,
72
+ annotations: READ_ONLY_TOOL
73
+ }, async () => {
74
+ try {
75
+ return buildStructuredResponse(await service.list());
76
+ } catch (error) {
77
+ return buildErrorResponse("list_prds", error);
78
+ }
79
+ });
80
+ server.registerTool("get_prd", {
81
+ title: "Read a PRD",
82
+ description: "Get the full contents of one PRD file.",
83
+ inputSchema: GetPrdInputSchema,
84
+ outputSchema: GetPrdOutputSchema,
85
+ annotations: READ_ONLY_TOOL
86
+ }, async (input) => {
87
+ try {
88
+ const parsed = GetPrdInputSchema.parse(input);
89
+ return buildStructuredResponse(await service.get(parsed));
90
+ } catch (error) {
91
+ return buildErrorResponse("get_prd", error);
92
+ }
93
+ });
94
+ server.registerTool("create_prd", {
95
+ title: "Create a PRD",
96
+ description: "Create a new structured PRD in .prds. The file name is derived from the title.",
97
+ inputSchema: CreatePrdInputSchema,
98
+ outputSchema: CreatePrdOutputSchema,
99
+ annotations: MUTATING_TOOL
100
+ }, async (input) => {
101
+ try {
102
+ const parsed = CreatePrdInputSchema.parse(input);
103
+ return buildStructuredResponse(await service.create(parsed));
104
+ } catch (error) {
105
+ return buildErrorResponse("create_prd", error);
106
+ }
107
+ });
108
+ server.registerTool("delete_prd", {
109
+ title: "Delete a PRD",
110
+ description: "Permanently delete a PRD file. Its folder of attachments, if any, is kept.",
111
+ inputSchema: DeletePrdInputSchema,
112
+ outputSchema: DeletePrdOutputSchema,
113
+ annotations: DESTRUCTIVE_TOOL
114
+ }, async (input) => {
115
+ try {
116
+ const parsed = DeletePrdInputSchema.parse(input);
117
+ return buildStructuredResponse(await service.delete(parsed));
118
+ } catch (error) {
119
+ return buildErrorResponse("delete_prd", error);
120
+ }
121
+ });
122
+ server.registerTool("add_user_story", {
123
+ title: "Add a user story",
124
+ description: "Append a user story with acceptance criteria to a PRD.",
125
+ inputSchema: AddUserStoryInputSchema,
126
+ outputSchema: AddUserStoryOutputSchema,
127
+ annotations: MUTATING_TOOL
128
+ }, async (input) => {
129
+ try {
130
+ const parsed = AddUserStoryInputSchema.parse(input);
131
+ return buildStructuredResponse(await service.addUserStory(parsed));
132
+ } catch (error) {
133
+ return buildErrorResponse("add_user_story", error);
134
+ }
135
+ });
136
+ server.registerTool("update_story_status", {
137
+ title: "Update story status",
138
+ description: "Update a user story status. Marking a story \"completed\" runs the project checks (typecheck, lint) first and is rejected if they fail.",
139
+ inputSchema: UpdateStoryStatusInputSchema,
140
+ outputSchema: UpdateStoryStatusOutputSchema,
141
+ annotations: MUTATING_TOOL
142
+ }, async (input) => {
143
+ try {
144
+ const parsed = UpdateStoryStatusInputSchema.parse(input);
145
+ return buildStructuredResponse(await service.updateStoryStatus(parsed));
146
+ } catch (error) {
147
+ return buildErrorResponse("update_story_status", error);
148
+ }
149
+ });
150
+ server.registerTool("update_user_story", {
151
+ title: "Update a user story",
152
+ description: "Edit an existing story's content. Every field is optional; only the ones supplied change. Use update_story_status for status.",
153
+ inputSchema: UpdateUserStoryInputSchema,
154
+ outputSchema: UpdateUserStoryOutputSchema,
155
+ annotations: IDEMPOTENT_MUTATING_TOOL
156
+ }, async (input) => {
157
+ try {
158
+ const parsed = UpdateUserStoryInputSchema.parse(input);
159
+ return buildStructuredResponse(await service.updateUserStory(parsed));
160
+ } catch (error) {
161
+ return buildErrorResponse("update_user_story", error);
162
+ }
163
+ });
164
+ server.registerTool("delete_user_story", {
165
+ title: "Delete a user story",
166
+ description: "Remove a story and clean up references to it in other stories' dependencies and in phases. Story ids are never reissued.",
167
+ inputSchema: DeleteUserStoryInputSchema,
168
+ outputSchema: DeleteUserStoryOutputSchema,
169
+ annotations: DESTRUCTIVE_TOOL
170
+ }, async (input) => {
171
+ try {
172
+ const parsed = DeleteUserStoryInputSchema.parse(input);
173
+ return buildStructuredResponse(await service.deleteUserStory(parsed));
174
+ } catch (error) {
175
+ return buildErrorResponse("delete_user_story", error);
176
+ }
177
+ });
178
+ server.registerTool("create_custom_phase", {
179
+ title: "Create a delivery phase",
180
+ description: "Create a named phase (e.g. \"MVP\", \"Fast follow\") that stories can be grouped into.",
181
+ inputSchema: CreateCustomPhaseInputSchema,
182
+ outputSchema: CreateCustomPhaseOutputSchema,
183
+ annotations: MUTATING_TOOL
184
+ }, async (input) => {
185
+ try {
186
+ const parsed = CreateCustomPhaseInputSchema.parse(input);
187
+ return buildStructuredResponse(await service.createCustomPhase(parsed));
188
+ } catch (error) {
189
+ return buildErrorResponse("create_custom_phase", error);
190
+ }
191
+ });
192
+ server.registerTool("assign_story_to_phase", {
193
+ title: "Assign a story to a phase",
194
+ description: "Move a story into a phase, or pass phaseId null to remove it from every phase. A story belongs to at most one phase.",
195
+ inputSchema: AssignStoryToPhaseInputSchema,
196
+ outputSchema: AssignStoryToPhaseOutputSchema,
197
+ annotations: IDEMPOTENT_MUTATING_TOOL
198
+ }, async (input) => {
199
+ try {
200
+ const parsed = AssignStoryToPhaseInputSchema.parse(input);
201
+ return buildStructuredResponse(await service.assignStoryToPhase(parsed));
202
+ } catch (error) {
203
+ return buildErrorResponse("assign_story_to_phase", error);
204
+ }
205
+ });
206
+ server.registerTool("export_prd_markdown", {
207
+ title: "Export PRD as Markdown",
208
+ description: "Write a Markdown rendering of the PRD next to the JSON file.",
209
+ inputSchema: ExportPrdMarkdownInputSchema,
210
+ outputSchema: ExportPrdMarkdownOutputSchema,
211
+ annotations: IDEMPOTENT_MUTATING_TOOL
212
+ }, async (input) => {
213
+ try {
214
+ const parsed = ExportPrdMarkdownInputSchema.parse(input);
215
+ return buildStructuredResponse(await service.exportMarkdown(parsed));
216
+ } catch (error) {
217
+ return buildErrorResponse("export_prd_markdown", error);
218
+ }
219
+ });
220
+ server.registerTool("get_implementation_prompts", {
221
+ title: "Implementation prompts",
222
+ description: "The implement_story instructions for the next unstarted stories, as text to paste into an agent that does not support MCP prompts.",
223
+ inputSchema: GetImplementationPromptsInputSchema,
224
+ outputSchema: GetImplementationPromptsOutputSchema,
225
+ annotations: READ_ONLY_TOOL
226
+ }, async (input) => {
227
+ try {
228
+ const { filename } = GetImplementationPromptsInputSchema.parse(input);
229
+ return buildStructuredResponse(await service.getImplementationPrompts(filename));
230
+ } catch (error) {
231
+ return buildErrorResponse("get_implementation_prompts", error);
232
+ }
233
+ });
234
+ server.registerTool("get_improvement_suggestions", {
235
+ title: "PRD completeness checks",
236
+ description: "Rule-based suggestions for missing PRD sections (stories, metrics, scope guardrails, rollout plan).",
237
+ inputSchema: GetImprovementSuggestionsInputSchema,
238
+ outputSchema: GetImprovementSuggestionsOutputSchema,
239
+ annotations: READ_ONLY_TOOL
240
+ }, async (input) => {
241
+ try {
242
+ const { filename } = GetImprovementSuggestionsInputSchema.parse(input);
243
+ return buildStructuredResponse(await service.getImprovementSuggestions(filename));
244
+ } catch (error) {
245
+ return buildErrorResponse("get_improvement_suggestions", error);
246
+ }
247
+ });
248
+ server.registerTool("get_project_status", {
249
+ title: "PRD project status",
250
+ description: "Progress, next steps, blockers, open questions and high risks for a PRD.",
251
+ inputSchema: GetProjectStatusInputSchema,
252
+ outputSchema: GetProjectStatusOutputSchema,
253
+ annotations: READ_ONLY_TOOL
254
+ }, async (input) => {
255
+ try {
256
+ const { filename } = GetProjectStatusInputSchema.parse(input);
257
+ return buildStructuredResponse(await service.getProjectStatus(filename));
258
+ } catch (error) {
259
+ return buildErrorResponse("get_project_status", error);
260
+ }
261
+ });
262
+ server.registerTool("list_templates", {
263
+ title: "List PRD templates",
264
+ description: "Starting points for create_prd (e.g. a SaaS feature, an internal tool, an integration, a first version). Each says when to use it.",
265
+ inputSchema: ListTemplatesInputSchema,
266
+ outputSchema: ListTemplatesOutputSchema,
267
+ annotations: READ_ONLY_TOOL
268
+ }, async () => {
269
+ try {
270
+ return buildStructuredResponse(service.listTemplates());
271
+ } catch (error) {
272
+ return buildErrorResponse("list_templates", error);
273
+ }
274
+ });
275
+ server.registerTool("check_plan", {
276
+ title: "Check what the plan is missing",
277
+ description: "A checklist of what the PRD still needs before and during the build. \"required\" items (no stories, stories without acceptance criteria, no scope limits) mean it is not ready to build; \"recommended\" items improve it. Each item names the section to change and, when relevant, the stories.",
278
+ inputSchema: CheckPlanInputSchema,
279
+ outputSchema: CheckPlanOutputSchema,
280
+ annotations: READ_ONLY_TOOL
281
+ }, async (input) => {
282
+ try {
283
+ const { filename } = CheckPlanInputSchema.parse(input);
284
+ return buildStructuredResponse(await service.checkPlan(filename));
285
+ } catch (error) {
286
+ return buildErrorResponse("check_plan", error);
287
+ }
288
+ });
289
+ server.registerTool("get_next_story", {
290
+ title: "Next story to work on",
291
+ description: "The next not-started story whose dependencies are all completed, ordered by phase, priority and position. Also lists stories in progress and stories waiting on dependencies.",
292
+ inputSchema: GetNextStoryInputSchema,
293
+ outputSchema: GetNextStoryOutputSchema,
294
+ annotations: READ_ONLY_TOOL
295
+ }, async (input) => {
296
+ try {
297
+ const { filename } = GetNextStoryInputSchema.parse(input);
298
+ return buildStructuredResponse(await service.getNextStory(filename));
299
+ } catch (error) {
300
+ return buildErrorResponse("get_next_story", error);
301
+ }
302
+ });
303
+ server.registerTool("get_story", {
304
+ title: "Story with context",
305
+ description: "One story with what is needed to implement it: PRD summary and scope limits, its phase, its dependencies and their hand-off logs, and the log of the most recently completed story. Prefer this over get_prd when working on a single story.",
306
+ inputSchema: GetStoryInputSchema,
307
+ outputSchema: GetStoryOutputSchema,
308
+ annotations: READ_ONLY_TOOL
309
+ }, async (input) => {
310
+ try {
311
+ return buildStructuredResponse(await service.getStory(GetStoryInputSchema.parse(input)));
312
+ } catch (error) {
313
+ return buildErrorResponse("get_story", error);
314
+ }
315
+ });
316
+ server.registerTool("add_story_log", {
317
+ title: "Log work on a story",
318
+ description: "Append a hand-off entry to a story: what a person can now try (whatsNew), notes for the next agent (technicalNotes) and where the work departed from the PRD (deviations). Write one when you finish a work session on a story.",
319
+ inputSchema: AddStoryLogInputSchema,
320
+ outputSchema: AddStoryLogOutputSchema,
321
+ annotations: MUTATING_TOOL
322
+ }, async (input) => {
323
+ try {
324
+ return buildStructuredResponse(await service.addStoryLog(AddStoryLogInputSchema.parse(input)));
325
+ } catch (error) {
326
+ return buildErrorResponse("add_story_log", error);
327
+ }
328
+ });
329
+ server.registerTool("add_attachment", {
330
+ title: "Add an attachment",
331
+ description: "Record a file or link the plan refers to (a mockup, a screenshot, reference docs) and link it to the stories that use it. Save files in the PRD folder, .prds/<prd file name without .json>/, first. get_story returns a story's attachments with their paths.",
332
+ inputSchema: AddAttachmentInputSchema,
333
+ outputSchema: AddAttachmentOutputSchema,
334
+ annotations: MUTATING_TOOL
335
+ }, async (input) => {
336
+ try {
337
+ return buildStructuredResponse(await service.addAttachment(AddAttachmentInputSchema.parse(input)));
338
+ } catch (error) {
339
+ return buildErrorResponse("add_attachment", error);
340
+ }
341
+ });
342
+ server.registerTool("remove_attachment", {
343
+ title: "Remove an attachment",
344
+ description: "Remove an attachment from the PRD and from every story that uses it. The file itself is kept.",
345
+ inputSchema: RemoveAttachmentInputSchema,
346
+ outputSchema: RemoveAttachmentOutputSchema,
347
+ annotations: DESTRUCTIVE_TOOL
348
+ }, async (input) => {
349
+ try {
350
+ return buildStructuredResponse(await service.removeAttachment(RemoveAttachmentInputSchema.parse(input)));
351
+ } catch (error) {
352
+ return buildErrorResponse("remove_attachment", error);
353
+ }
354
+ });
355
+ server.registerTool("update_prd_section", {
356
+ title: "Update a PRD section",
357
+ description: "Change one section of a PRD after it was created: scope (nonGoals, outOfScope), assumptions, open questions, risks, edge cases (what can go wrong and what should happen), security considerations, design guidance, external dependencies, technical requirements and contracts (including permissions and compliance), global acceptance criteria, constraints, rollout and measurement plans, or the introduction, problem and solution. For risks, edge cases and security, think adversarially: assume things fail and that someone is actively trying to abuse the feature, and write down the specific failure or attack with what should happen.",
358
+ inputSchema: UpdatePrdSectionInputSchema,
359
+ outputSchema: UpdatePrdSectionOutputSchema,
360
+ annotations: IDEMPOTENT_MUTATING_TOOL
361
+ }, async (input) => {
362
+ try {
363
+ return buildStructuredResponse(await service.updatePrdSection(UpdatePrdSectionInputSchema.parse(input)));
364
+ } catch (error) {
365
+ return buildErrorResponse("update_prd_section", error);
366
+ }
367
+ });
368
+ server.registerTool("add_decision", {
369
+ title: "Record a decision",
370
+ description: "Add an entry to the PRD decision log. Use it for choices that are hard to reverse or would surprise someone reading the code later. Pass supersedes to replace an earlier decision.",
371
+ inputSchema: AddDecisionInputSchema,
372
+ outputSchema: AddDecisionOutputSchema,
373
+ annotations: MUTATING_TOOL
374
+ }, async (input) => {
375
+ try {
376
+ return buildStructuredResponse(await service.addDecision(AddDecisionInputSchema.parse(input)));
377
+ } catch (error) {
378
+ return buildErrorResponse("add_decision", error);
379
+ }
380
+ });
381
+ server.registerTool("mark_not_applicable", {
382
+ title: "Mark a part of the PRD not applicable",
383
+ description: "Mark an optional part of a PRD (dataModel, outsideServices, security, design, qualityBar, edgeCases, rollout, measurement, glossary, risks) as not applicable, with a reason, so the plan check stops asking for it and agents do not invent it. Pass notApplicable false to undo. Do not mark security or edgeCases not applicable for features that take input from people or store their data.",
384
+ inputSchema: MarkNotApplicableInputSchema,
385
+ outputSchema: MarkNotApplicableOutputSchema,
386
+ annotations: IDEMPOTENT_MUTATING_TOOL
387
+ }, async (input) => {
388
+ try {
389
+ return buildStructuredResponse(await service.markNotApplicable(MarkNotApplicableInputSchema.parse(input)));
390
+ } catch (error) {
391
+ return buildErrorResponse("mark_not_applicable", error);
392
+ }
393
+ });
394
+ server.registerTool("resolve_open_question", {
395
+ title: "Answer an open question",
396
+ description: "Answer an open question (by questionId, or by its exact text): it is removed from the PRD and, by default, the answer is recorded in the decision log.",
397
+ inputSchema: ResolveOpenQuestionInputSchema,
398
+ outputSchema: ResolveOpenQuestionOutputSchema,
399
+ annotations: MUTATING_TOOL
400
+ }, async (input) => {
401
+ try {
402
+ return buildStructuredResponse(await service.resolveOpenQuestion(ResolveOpenQuestionInputSchema.parse(input)));
403
+ } catch (error) {
404
+ return buildErrorResponse("resolve_open_question", error);
405
+ }
406
+ });
407
+ server.registerTool("update_attachment", {
408
+ title: "Update an attachment",
409
+ description: "Change an attachment's title or note, or which stories use it (storyIds: links are added and removed to match).",
410
+ inputSchema: UpdateAttachmentInputSchema,
411
+ outputSchema: UpdateAttachmentOutputSchema,
412
+ annotations: IDEMPOTENT_MUTATING_TOOL
413
+ }, async (input) => {
414
+ try {
415
+ return buildStructuredResponse(await service.updateAttachment(UpdateAttachmentInputSchema.parse(input)));
416
+ } catch (error) {
417
+ return buildErrorResponse("update_attachment", error);
418
+ }
419
+ });
420
+ server.registerTool("decide_edge_case", {
421
+ title: "Decide an open edge case",
422
+ description: "Record what should happen for an open edge case; it becomes decided and binding for the stories it applies to.",
423
+ inputSchema: DecideEdgeCaseInputSchema,
424
+ outputSchema: DecideEdgeCaseOutputSchema,
425
+ annotations: IDEMPOTENT_MUTATING_TOOL
426
+ }, async (input) => {
427
+ try {
428
+ return buildStructuredResponse(await service.decideEdgeCase(DecideEdgeCaseInputSchema.parse(input)));
429
+ } catch (error) {
430
+ return buildErrorResponse("decide_edge_case", error);
431
+ }
432
+ });
433
+ server.registerTool("add_glossary_term", {
434
+ title: "Define a glossary term",
435
+ description: "Add or redefine a term in the PRD glossary, with words to avoid, so people and agents use the same names for the same things.",
436
+ inputSchema: AddGlossaryTermInputSchema,
437
+ outputSchema: AddGlossaryTermOutputSchema,
438
+ annotations: IDEMPOTENT_MUTATING_TOOL
439
+ }, async (input) => {
440
+ try {
441
+ return buildStructuredResponse(await service.addGlossaryTerm(AddGlossaryTermInputSchema.parse(input)));
442
+ } catch (error) {
443
+ return buildErrorResponse("add_glossary_term", error);
444
+ }
445
+ });
446
+ server.registerTool("update_phase", {
447
+ title: "Update a phase",
448
+ description: "Rename a phase or change its description or colour.",
449
+ inputSchema: UpdatePhaseInputSchema,
450
+ outputSchema: PhasesOutputSchema,
451
+ annotations: IDEMPOTENT_MUTATING_TOOL
452
+ }, async (input) => {
453
+ try {
454
+ return buildStructuredResponse(await service.updatePhase(UpdatePhaseInputSchema.parse(input)));
455
+ } catch (error) {
456
+ return buildErrorResponse("update_phase", error);
457
+ }
458
+ });
459
+ server.registerTool("delete_phase", {
460
+ title: "Delete a phase",
461
+ description: "Delete a phase. Its stories stay in the PRD without a phase.",
462
+ inputSchema: DeletePhaseInputSchema,
463
+ outputSchema: PhasesOutputSchema,
464
+ annotations: DESTRUCTIVE_TOOL
465
+ }, async (input) => {
466
+ try {
467
+ return buildStructuredResponse(await service.deletePhase(DeletePhaseInputSchema.parse(input)));
468
+ } catch (error) {
469
+ return buildErrorResponse("delete_phase", error);
470
+ }
471
+ });
472
+ server.registerTool("reorder_phases", {
473
+ title: "Reorder phases",
474
+ description: "Set the order of all phases. get_next_story works through phases in this order.",
475
+ inputSchema: ReorderPhasesInputSchema,
476
+ outputSchema: PhasesOutputSchema,
477
+ annotations: IDEMPOTENT_MUTATING_TOOL
478
+ }, async (input) => {
479
+ try {
480
+ return buildStructuredResponse(await service.reorderPhases(ReorderPhasesInputSchema.parse(input)));
481
+ } catch (error) {
482
+ return buildErrorResponse("reorder_phases", error);
483
+ }
484
+ });
485
+ server.registerPrompt("shape_prd", {
486
+ title: "Shape a PRD",
487
+ description: "Interview the user round by round until the plan is clear, writing each decision into the PRD as it is made, then slice the work into stories and phases.",
488
+ argsSchema: {
489
+ idea: z.string().optional().describe("What to build, in a sentence or two"),
490
+ filename: z.string().optional().describe("Existing PRD to keep shaping, inside .prds"),
491
+ template: z.enum(TEMPLATE_IDS).optional().describe("Kind of work, see list_templates")
492
+ }
493
+ }, ({ idea, filename, template }) => ({ messages: [{
494
+ role: "user",
495
+ content: {
496
+ type: "text",
497
+ text: shapePrdPrompt(idea, filename, template)
498
+ }
499
+ }] }));
500
+ server.registerPrompt("review_story", {
501
+ title: "Review a story against its spec",
502
+ description: "Check the changes made for a story against its acceptance criteria, scope limits and test seams, and report a verdict.",
503
+ argsSchema: {
504
+ filename: z.string().describe("PRD file name inside .prds"),
505
+ storyId: z.string().describe("Story id such as US003"),
506
+ base: z.string().optional().describe("Git ref the story started from. Defaults to HEAD.")
507
+ }
508
+ }, ({ filename, storyId, base }) => ({ messages: [{
509
+ role: "user",
510
+ content: {
511
+ type: "text",
512
+ text: reviewStoryPrompt(filename, storyId, base)
513
+ }
514
+ }] }));
515
+ server.registerPrompt("implement_story", {
516
+ title: "Implement a PRD story",
517
+ description: "Instructions for implementing one story end to end with the PRD tools.",
518
+ argsSchema: {
519
+ filename: z.string().describe("PRD file name inside .prds"),
520
+ storyId: z.string().optional().describe("Story id such as US003. Omit to take the next ready one.")
521
+ }
522
+ }, ({ filename, storyId }) => ({ messages: [{
523
+ role: "user",
524
+ content: {
525
+ type: "text",
526
+ text: implementStoryPrompt(filename, storyId)
527
+ }
528
+ }] }));
529
+ }
530
+ //#endregion
531
+ export { registerPRDTools };
package/dist/node.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ import { t as PrdDeps } from "./prd.service-DSBp8sMl.js";
2
+ //#region src/node.d.ts
3
+ export interface NodePrdDepsOptions {
4
+ /**
5
+ * Decides whether a story may be marked completed. Defaults to running the
6
+ * project's `typecheck` and `lint` scripts (see `createScriptVerifier`).
7
+ */
8
+ verifyCompletion?: PrdDeps['verifyCompletion'];
9
+ }
10
+ /** PRD dependencies backed by the local filesystem, rooted at `rootPath`. */
11
+ export declare function createNodePrdDeps(rootPath?: string, options?: NodePrdDepsOptions): PrdDeps;
12
+ /**
13
+ * Verifies completion by running the project's package.json scripts with its
14
+ * package manager (via @makerkit/repo-checks), so a failure comes back as
15
+ * file-and-line diagnostics. Scripts the project does not define are skipped,
16
+ * so a repo without e.g. `lint` can still complete stories.
17
+ */
18
+ export declare function createScriptVerifier(rootPath: string, scripts?: string[]): PrdDeps['verifyCompletion'];
19
+ //#endregion
package/dist/node.js ADDED
@@ -0,0 +1,94 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ let node_path = require("node:path");
3
+ let _makerkit_repo_checks_node = require("@makerkit/repo-checks/node");
4
+ let node_fs_promises = require("node:fs/promises");
5
+ //#region src/node.ts
6
+ /** Check-only scripts that gate marking a story as completed. */
7
+ const DEFAULT_COMPLETION_CHECKS = ["typecheck", "lint"];
8
+ /** PRD dependencies backed by the local filesystem, rooted at `rootPath`. */
9
+ function createNodePrdDeps(rootPath = process.cwd(), options = {}) {
10
+ return {
11
+ rootPath,
12
+ readdir(path) {
13
+ return (0, node_fs_promises.readdir)(path);
14
+ },
15
+ readFile(path) {
16
+ return (0, node_fs_promises.readFile)(path, "utf8");
17
+ },
18
+ writeFile(path, content) {
19
+ return (0, node_fs_promises.writeFile)(path, content, "utf8");
20
+ },
21
+ async mkdir(path) {
22
+ await (0, node_fs_promises.mkdir)(path, { recursive: true });
23
+ },
24
+ unlink(path) {
25
+ return (0, node_fs_promises.unlink)(path);
26
+ },
27
+ fileExists,
28
+ now() {
29
+ return /* @__PURE__ */ new Date();
30
+ },
31
+ verifyCompletion: options.verifyCompletion ?? createScriptVerifier(rootPath)
32
+ };
33
+ }
34
+ /**
35
+ * Verifies completion by running the project's package.json scripts with its
36
+ * package manager (via @makerkit/repo-checks), so a failure comes back as
37
+ * file-and-line diagnostics. Scripts the project does not define are skipped,
38
+ * so a repo without e.g. `lint` can still complete stories.
39
+ */
40
+ function createScriptVerifier(rootPath, scripts = DEFAULT_COMPLETION_CHECKS) {
41
+ return async () => {
42
+ if (!await fileExists((0, node_path.join)(rootPath, "package.json"))) return {
43
+ passed: true,
44
+ checks: [],
45
+ errors: 0,
46
+ warnings: 0,
47
+ diagnostics: [],
48
+ messages: ["No package.json: there are no project checks to run."]
49
+ };
50
+ const checks = (0, _makerkit_repo_checks_node.createRepoChecksServices)(rootPath);
51
+ const { scripts: available } = await checks.scripts.list();
52
+ const defined = new Set(available.map((script) => script.name));
53
+ const toRun = scripts.filter((script) => defined.has(script));
54
+ const messages = scripts.filter((script) => !defined.has(script)).map((script) => `${script}: skipped (no "${script}" script in package.json)`);
55
+ if (toRun.length === 0) return {
56
+ passed: true,
57
+ checks: [],
58
+ errors: 0,
59
+ warnings: 0,
60
+ diagnostics: [],
61
+ messages
62
+ };
63
+ const result = await checks.runChecks.run({ scripts: toRun });
64
+ const unexplained = result.checks.filter((check) => check.status !== "pass" && check.diagnostics.length === 0);
65
+ for (const check of unexplained) {
66
+ const detail = (check.stderr.trim() || check.stdout.trim()).slice(-300);
67
+ messages.push(`${check.script}: ${check.status}${detail ? ` (${detail})` : ""}`);
68
+ }
69
+ return {
70
+ passed: result.overall === "pass",
71
+ checks: result.scripts_requested,
72
+ errors: result.summary.errors + unexplained.length,
73
+ warnings: result.summary.warnings,
74
+ diagnostics: result.diagnostics.map((diagnostic) => ({
75
+ file: diagnostic.file,
76
+ line: diagnostic.line,
77
+ message: diagnostic.message,
78
+ severity: diagnostic.severity
79
+ })),
80
+ messages
81
+ };
82
+ };
83
+ }
84
+ async function fileExists(path) {
85
+ try {
86
+ await (0, node_fs_promises.access)(path);
87
+ return true;
88
+ } catch {
89
+ return false;
90
+ }
91
+ }
92
+ //#endregion
93
+ exports.createNodePrdDeps = createNodePrdDeps;
94
+ exports.createScriptVerifier = createScriptVerifier;