@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.
Files changed (63) hide show
  1. package/.turbo/turbo-build.log +78 -0
  2. package/.turbo/turbo-test.log +19 -0
  3. package/.turbo/turbo-typecheck.log +6 -0
  4. package/README.md +7 -1
  5. package/dist/README.md +71 -0
  6. package/dist/attachment-paths-BAhRGiib.js +112 -0
  7. package/dist/attachment-paths-C-SWgoSx.mjs +77 -0
  8. package/dist/index.d.ts +81 -0
  9. package/{index.js → dist/index.js} +257 -524
  10. package/{index.mjs → dist/index.mjs} +189 -462
  11. package/{mcp.d.ts → dist/mcp.d.ts} +2 -4
  12. package/{mcp.js → dist/mcp.js} +24 -24
  13. package/{mcp.mjs → dist/mcp.mjs} +24 -24
  14. package/{node.d.ts → dist/node.d.ts} +4 -4
  15. package/{node.js → dist/node.js} +28 -4
  16. package/{node.mjs → dist/node.mjs} +30 -6
  17. package/dist/operations.d.ts +141 -0
  18. package/dist/operations.js +22 -0
  19. package/dist/operations.mjs +1 -0
  20. package/dist/package.json +54 -0
  21. package/dist/prd-operations-BvFxo9bg.mjs +459 -0
  22. package/dist/prd-operations-CcahfbOy.js +584 -0
  23. package/dist/prd.service-CTwKZV-3.d.ts +114 -0
  24. package/{prompts-DJQ4FQ11.js → dist/prompts-1qhax_dj.js} +150 -167
  25. package/{prompts-B0VejF7q.mjs → dist/prompts-BlsYD0gf.mjs} +121 -132
  26. package/{prd.service-x5EpOoMv.d.ts → dist/schema-BwTnt0B9.d.ts} +545 -323
  27. package/package.json +26 -2
  28. package/src/__tests__/agent-workflow.test.ts +417 -0
  29. package/src/__tests__/attachments.test.ts +505 -0
  30. package/src/__tests__/node.test.ts +199 -0
  31. package/src/__tests__/plan-check.test.ts +390 -0
  32. package/src/__tests__/planning.test.ts +1137 -0
  33. package/src/__tests__/prd-operations.test.ts +571 -0
  34. package/src/__tests__/prd.service.test.ts +652 -0
  35. package/src/__tests__/prd.tool.test.ts +282 -0
  36. package/src/__tests__/templates.test.ts +145 -0
  37. package/src/applicability.ts +73 -0
  38. package/src/attachment-paths.ts +83 -0
  39. package/src/attachments.ts +166 -0
  40. package/src/edge-cases.ts +61 -0
  41. package/src/index.ts +33 -0
  42. package/src/markdown.ts +297 -0
  43. package/src/mcp/index.ts +875 -0
  44. package/src/mcp/tool-response.ts +85 -0
  45. package/src/node.ts +184 -0
  46. package/src/open-questions.ts +98 -0
  47. package/src/plan-check.ts +385 -0
  48. package/src/planning-operations.ts +524 -0
  49. package/src/prd-operations.ts +769 -0
  50. package/src/prd.service.ts +1165 -0
  51. package/src/prompts.ts +161 -0
  52. package/src/safe-file-name.ts +42 -0
  53. package/src/schema.ts +1090 -0
  54. package/src/templates.ts +173 -0
  55. package/src/testing/fake-mcp-server.ts +81 -0
  56. package/src/types.ts +381 -0
  57. package/tsconfig.json +23 -0
  58. package/tsconfig.lib.json +8 -0
  59. package/tsconfig.spec.json +7 -0
  60. package/tsdown.config.mts +12 -0
  61. package/vitest.config.mts +8 -0
  62. package/index.d.ts +0 -228
  63. /package/{LICENSE → dist/LICENSE} +0 -0
package/index.d.ts DELETED
@@ -1,228 +0,0 @@
1
- import { $ as DeletePrdOutputSchema, $t as ResolveOpenQuestionOutput, A as AssignStoryToPhaseOutput, An as DecisionLogEntry, At as ListPrdsOutputSchema, B as CreatePrdInputSchema, Bn as StoryTraceabilityMap, Bt as PhasesOutputSchema, C as AddStoryLogOutputSchema, Cn as UpdateUserStoryInputSchema, Ct as GetProjectStatusOutputSchema, D as AddUserStoryOutputSchema, Dn as Attachment, Dt as GetStoryOutputSchema, E as AddUserStoryOutput, En as AgentTaskPacket, Et as GetStoryOutput, F as CreateCustomPhaseInput, Fn as RiskItem, Ft as MarkNotApplicableInputSchema, G as DecideEdgeCaseInputSchema, Gt as RemoveAttachmentInput, H as CreatePrdOutputSchema, Hn as StructuredPRD, Ht as PrdSectionValueSchemas, I as CreateCustomPhaseInputSchema, In as StoryComplexity, It as MarkNotApplicableOutput, J as DeletePhaseInput, Jt as RemoveAttachmentOutputSchema, K as DecideEdgeCaseOutput, Kt as RemoveAttachmentInputSchema, L as CreateCustomPhaseOutput, Ln as StoryLogEntry, Lt as MarkNotApplicableOutputSchema, M as CheckPlanInputSchema, Mn as GlossaryTerm, Mt as ListTemplatesOutput, N as CheckPlanOutput, Nn as NotApplicableTopic, Nt as ListTemplatesOutputSchema, O as AssignStoryToPhaseInput, On as CrossDependency, Ot as ListPrdsInputSchema, P as CheckPlanOutputSchema, Pn as OpenQuestion, Pt as MarkNotApplicableInput, Q as DeletePrdOutput, Qt as ResolveOpenQuestionInputSchema, R as CreateCustomPhaseOutputSchema, Rn as StoryPriority, Rt as NotApplicableTopicSchema, S as AddStoryLogOutput, Sn as UpdateUserStoryInput, St as GetProjectStatusOutput, T as AddUserStoryInputSchema, Tn as UpdateUserStoryOutputSchema, Tt as GetStoryInputSchema, U as CustomPhaseSchema, Un as UserStory, Ut as PrdSummary, V as CreatePrdOutput, Vn as StoryVerification, Vt as PrdSection, W as DecideEdgeCaseInput, Wt as PrdSummarySchema, X as DeletePrdInput, Xt as ReorderPhasesInputSchema, Y as DeletePhaseInputSchema, Yt as ReorderPhasesInput, Z as DeletePrdInputSchema, Zt as ResolveOpenQuestionInput, _ as AddGlossaryTermInputSchema, _n as UpdatePrdSectionOutputSchema, _t as GetPrdInput, a as PrdVerificationResult, an as StoryPrioritySchema, at as ExportPrdMarkdownInputSchema, b as AddStoryLogInput, bn as UpdateStoryStatusOutput, bt as GetPrdOutputSchema, c as AddAttachmentInput, cn as UpdateAttachmentInput, ct as GetImplementationPromptsInputSchema, d as AddAttachmentOutputSchema, dn as UpdateAttachmentOutputSchema, dt as GetImprovementSuggestionsInputSchema, en as ResolveOpenQuestionOutputSchema, et as DeleteUserStoryInput, f as AddDecisionInput, fn as UpdatePhaseInput, ft as GetImprovementSuggestionsOutput, g as AddGlossaryTermInput, gn as UpdatePrdSectionOutput, gt as GetNextStoryOutputSchema, h as AddDecisionOutputSchema, hn as UpdatePrdSectionInputSchema, ht as GetNextStoryOutput, i as PrdVerificationDiagnostic, in as StoryLogEntrySchema, it as ExportPrdMarkdownInput, j as AssignStoryToPhaseOutputSchema, jn as EdgeCase, jt as ListTemplatesInputSchema, k as AssignStoryToPhaseInputSchema, kn as CustomPhase, kt as ListPrdsOutput, l as AddAttachmentInputSchema, ln as UpdateAttachmentInputSchema, lt as GetImplementationPromptsOutput, m as AddDecisionOutput, mn as UpdatePrdSectionInput, mt as GetNextStoryInputSchema, n as PrdRevisionConflictError, nn as StoryAttachmentSchema, nt as DeleteUserStoryOutput, o as createPrdService, on as StoryStatusSchema, ot as ExportPrdMarkdownOutput, p as AddDecisionInputSchema, pn as UpdatePhaseInputSchema, pt as GetImprovementSuggestionsOutputSchema, q as DecideEdgeCaseOutputSchema, qt as RemoveAttachmentOutput, r as PrdService, rn as StoryComplexitySchema, rt as DeleteUserStoryOutputSchema, s as normalizePrd, sn as StoryVerificationSchema, st as ExportPrdMarkdownOutputSchema, t as PrdDeps, tn as StoryAttachment, tt as DeleteUserStoryInputSchema, u as AddAttachmentOutput, un as UpdateAttachmentOutput, ut as GetImplementationPromptsOutputSchema, v as AddGlossaryTermOutput, vn as UpdateStoryStatusInput, vt as GetPrdInputSchema, w as AddUserStoryInput, wn as UpdateUserStoryOutput, wt as GetStoryInput, x as AddStoryLogInputSchema, xn as UpdateStoryStatusOutputSchema, xt as GetProjectStatusInputSchema, y as AddGlossaryTermOutputSchema, yn as UpdateStoryStatusInputSchema, yt as GetPrdOutput, z as CreatePrdInput, zn as StoryStatus, zt as PhasesOutput } from "./prd.service-x5EpOoMv.js";
2
- //#region src/prd-operations.d.ts
3
- /**
4
- * Pure PRD transforms.
5
- *
6
- * Everything here takes an already-loaded `StructuredPRD`, mutates it, and
7
- * returns the tool payload. No filesystem, no clock, no deps — the service is
8
- * left with load → transform → save, and every rule below is unit-testable
9
- * without a harness.
10
- */
11
- /**
12
- * Issues the next story id and advances the high-water mark.
13
- *
14
- * Deliberately not `max(existing) + 1`: delete the highest-numbered story and
15
- * that hands its id straight to the next one, so a story id quoted in a commit
16
- * or a decision-log topic would silently come to mean something else.
17
- */
18
- export declare function nextId(items: {
19
- id: string;
20
- }[], prefix: string): string;
21
- export declare function nextStoryId(prd: StructuredPRD): string;
22
- export declare function recomputeProgress(prd: StructuredPRD): void;
23
- export declare function appendChangeLog(prd: StructuredPRD, entry: string, today: string): void;
24
- export declare function findStory(prd: StructuredPRD, storyId: string): UserStory;
25
- /** Splits the rendered sentence back into its parts so one can be patched. */
26
- /** The parts of an "As a X, I want to Y so that Z" story, or undefined. */
27
- export declare function splitUserStory(sentence: string): {
28
- userType: string;
29
- action: string;
30
- benefit: string;
31
- } | undefined;
32
- export declare function renderUserStory(parts: {
33
- userType: string;
34
- action: string;
35
- benefit: string;
36
- }): string;
37
- export declare function updateStory(prd: StructuredPRD, input: UpdateUserStoryInput, today: string): UpdateUserStoryOutput;
38
- export declare function findAttachment(prd: StructuredPRD, attachmentId: string): Attachment;
39
- /** Attachment ids must name attachments in the PRD. */
40
- export declare function validateAttachmentIds(prd: StructuredPRD, ids: string[]): string[];
41
- /**
42
- * Dependencies must name real stories, never the story itself, and never form
43
- * a cycle — an unsatisfiable order is worse than no order at all.
44
- */
45
- export declare function validateDependencies(prd: StructuredPRD, storyId: string, dependencies: string[]): string[];
46
- export declare function deleteStory(prd: StructuredPRD, storyId: string, today: string): DeleteUserStoryOutput;
47
- export declare function createPhase(prd: StructuredPRD, input: CreateCustomPhaseInput, today: string): CreateCustomPhaseOutput;
48
- export declare function assignStoryToPhase(prd: StructuredPRD, input: AssignStoryToPhaseInput, today: string): AssignStoryToPhaseOutput;
49
- /** Dependencies of `story` that are not completed yet. */
50
- export declare function incompleteDependencies(prd: StructuredPRD, story: UserStory): string[];
51
- /**
52
- * A story cannot be worked on, reviewed or completed before the stories it
53
- * depends on are completed. `not_started`, `research` and `blocked` stay
54
- * available so a story can still be planned or parked.
55
- */
56
- export declare function assertCanEnterStatus(prd: StructuredPRD, story: UserStory, status: StoryStatus): void;
57
- /**
58
- * The next story to start: not started, every dependency completed, ordered
59
- * by phase, then priority, then position in the PRD.
60
- */
61
- export declare function pickNextStory(prd: StructuredPRD): {
62
- story: UserStory;
63
- ready_count: number;
64
- in_progress: string[];
65
- waiting: {
66
- id: string;
67
- title: string;
68
- waiting_on: string[];
69
- }[];
70
- };
71
- /**
72
- * Everything an agent needs to work on one story without loading the whole
73
- * PRD: the story, the scope boundaries, its dependencies with their hand-off
74
- * logs, and the log of the most recently completed story.
75
- */
76
- /** `filename` is the PRD's file name, used to give attachment paths. */
77
- export declare function buildStoryContext(prd: StructuredPRD, storyId: string, filename: string): {
78
- prd: {
79
- title: string;
80
- overview: string;
81
- non_goals: string[];
82
- out_of_scope: string[];
83
- global_acceptance_criteria: string[];
84
- attachments: {
85
- title: string;
86
- id: string;
87
- path?: string | undefined;
88
- url?: string | undefined;
89
- note?: string | undefined;
90
- }[];
91
- };
92
- story: UserStory;
93
- attachments: {
94
- title: string;
95
- id: string;
96
- path?: string | undefined;
97
- url?: string | undefined;
98
- note?: string | undefined;
99
- }[];
100
- phase: {
101
- id: string;
102
- name: string;
103
- } | null;
104
- edge_cases: EdgeCase[];
105
- open_questions: OpenQuestion[];
106
- security: {
107
- permissions: string[];
108
- compliance: string[];
109
- considerations: string[];
110
- story_notes: string[];
111
- };
112
- not_applicable: Record<string, string>;
113
- design: {
114
- guidance: string[];
115
- story_notes: string[];
116
- decisions: {
117
- id: string;
118
- decision: string;
119
- rationale: string;
120
- }[];
121
- };
122
- dependencies: {
123
- id: string;
124
- title: string | null;
125
- status: StoryStatus | null;
126
- log: StoryLogEntry[];
127
- }[];
128
- previous_story: {
129
- id: string;
130
- title: string;
131
- log: StoryLogEntry[];
132
- } | null;
133
- };
134
- export declare function appendStoryLog(prd: StructuredPRD, storyId: string, entry: StoryLogEntry): {
135
- story_id: string;
136
- entries: number;
137
- };
138
- //#endregion
139
- //#region src/attachment-paths.d.ts
140
- /**
141
- * The folder for a PRD's files, relative to `.prds`: the PRD file name
142
- * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
143
- */
144
- export declare function attachmentsFolder(filename: string): string;
145
- /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
146
- export declare function attachmentProjectPath(filename: string, path: string): string;
147
- /** Attachments as an agent needs them: file paths from the project root. */
148
- export declare function resolveAttachments(filename: string, attachments: Attachment[]): StoryAttachment[];
149
- //#endregion
150
- //#region src/applicability.d.ts
151
- /**
152
- * Parts of a PRD that can be marked "not applicable" (e.g. no rollout plan
153
- * for an internal tool), so the plan check stops asking for them and agents
154
- * do not invent them. The core (overview, problem, solution, scope, stories)
155
- * always applies.
156
- */
157
- export declare const NOT_APPLICABLE_TOPICS: readonly ["dataModel", "outsideServices", "security", "design", "qualityBar", "edgeCases", "rollout", "measurement", "glossary", "risks"];
158
- export declare function isNotApplicable(prd: StructuredPRD, topic: NotApplicableTopic): boolean;
159
- //#endregion
160
- //#region src/markdown.d.ts
161
- /**
162
- * Pass the PRD file name to link attachment files relative to `.prds/`, where
163
- * the markdown export is written.
164
- */
165
- export declare function formatPrdMarkdown(prd: StructuredPRD, filename?: string): string;
166
- //#endregion
167
- //#region src/prompts.d.ts
168
- /**
169
- * The instructions behind the MCP prompts, exported so other tools (e.g. a
170
- * UI that shows what to ask the agent) give exactly the same text.
171
- */
172
- export declare function shapePrdPrompt(overview?: string, filename?: string): string;
173
- export declare function architectPrdPrompt(filename: string): string;
174
- export declare function reviewStoryPrompt(filename: string, storyId: string, base?: string): string;
175
- export declare function implementStoryPrompt(filename: string, storyId?: string): string;
176
- //#endregion
177
- //#region src/plan-check.d.ts
178
- /**
179
- * What a plan is still missing, as items a UI can render as a checklist and an
180
- * agent can act on. `required` items mean the plan is not ready to build;
181
- * `recommended` items make it better but do not block.
182
- */
183
- interface PlanCheckItem {
184
- /** Stable key, e.g. `stories` or `vague-stories`. */
185
- id: string;
186
- /** The PRD section to change, matching `update_prd_section` where possible. */
187
- section: string;
188
- message: string;
189
- severity: 'required' | 'recommended';
190
- /** Stories the item is about, when it is about specific stories. */
191
- storyIds?: string[];
192
- }
193
- export declare function checkPlan(prd: StructuredPRD): {
194
- ready_to_build: boolean;
195
- items: PlanCheckItem[];
196
- };
197
- //#endregion
198
- //#region src/templates.d.ts
199
- /**
200
- * Starting points for new PRDs. A template fills sections the author would
201
- * otherwise start empty, and gives `shape_prd` extra questions that matter for
202
- * that kind of work. Everything it adds can be edited or removed afterwards.
203
- */
204
- interface PrdTemplate {
205
- id: TemplateId;
206
- name: string;
207
- description: string;
208
- /** Sentence an agent can use to pick the right template. */
209
- whenToUse: string;
210
- defaults: {
211
- nonGoals?: string[];
212
- outOfScope?: string[];
213
- openQuestions?: string[];
214
- globalAcceptanceCriteria?: string[];
215
- qualityStandards?: string[];
216
- technicalConstraints?: string[];
217
- rolloutPhases?: string[];
218
- rollbackConditions?: string[];
219
- };
220
- /** Extra questions for the shaping interview. */
221
- interviewFocus: string[];
222
- }
223
- export declare const TEMPLATE_IDS: readonly ["saas-feature", "internal-tool", "integration", "mvp"];
224
- type TemplateId = (typeof TEMPLATE_IDS)[number];
225
- export declare const PRD_TEMPLATES: readonly PrdTemplate[];
226
- export declare function getTemplate(id: TemplateId): PrdTemplate;
227
- //#endregion
228
- export { AddAttachmentInput, AddAttachmentInputSchema, AddAttachmentOutput, AddAttachmentOutputSchema, AddDecisionInput, AddDecisionInputSchema, AddDecisionOutput, AddDecisionOutputSchema, AddGlossaryTermInput, AddGlossaryTermInputSchema, AddGlossaryTermOutput, AddGlossaryTermOutputSchema, AddStoryLogInput, AddStoryLogInputSchema, AddStoryLogOutput, AddStoryLogOutputSchema, AddUserStoryInput, AddUserStoryInputSchema, AddUserStoryOutput, AddUserStoryOutputSchema, type AgentTaskPacket, AssignStoryToPhaseInput, AssignStoryToPhaseInputSchema, AssignStoryToPhaseOutput, AssignStoryToPhaseOutputSchema, type Attachment, CheckPlanInputSchema, CheckPlanOutput, CheckPlanOutputSchema, CreateCustomPhaseInput, CreateCustomPhaseInputSchema, CreateCustomPhaseOutput, CreateCustomPhaseOutputSchema, CreatePrdInput, CreatePrdInputSchema, CreatePrdOutput, CreatePrdOutputSchema, type CrossDependency, type CustomPhase, CustomPhaseSchema, DecideEdgeCaseInput, DecideEdgeCaseInputSchema, DecideEdgeCaseOutput, DecideEdgeCaseOutputSchema, type DecisionLogEntry, DeletePhaseInput, DeletePhaseInputSchema, DeletePrdInput, DeletePrdInputSchema, DeletePrdOutput, DeletePrdOutputSchema, DeleteUserStoryInput, DeleteUserStoryInputSchema, DeleteUserStoryOutput, DeleteUserStoryOutputSchema, type EdgeCase, ExportPrdMarkdownInput, ExportPrdMarkdownInputSchema, ExportPrdMarkdownOutput, ExportPrdMarkdownOutputSchema, GetImplementationPromptsInputSchema, GetImplementationPromptsOutput, GetImplementationPromptsOutputSchema, GetImprovementSuggestionsInputSchema, GetImprovementSuggestionsOutput, GetImprovementSuggestionsOutputSchema, GetNextStoryInputSchema, GetNextStoryOutput, GetNextStoryOutputSchema, GetPrdInput, GetPrdInputSchema, GetPrdOutput, GetPrdOutputSchema, GetProjectStatusInputSchema, GetProjectStatusOutput, GetProjectStatusOutputSchema, GetStoryInput, GetStoryInputSchema, GetStoryOutput, GetStoryOutputSchema, type GlossaryTerm, ListPrdsInputSchema, ListPrdsOutput, ListPrdsOutputSchema, ListTemplatesInputSchema, ListTemplatesOutput, ListTemplatesOutputSchema, MarkNotApplicableInput, MarkNotApplicableInputSchema, MarkNotApplicableOutput, MarkNotApplicableOutputSchema, type NotApplicableTopic, NotApplicableTopicSchema, type OpenQuestion, PhasesOutput, PhasesOutputSchema, type PlanCheckItem, type PrdDeps, PrdRevisionConflictError, PrdSection, PrdSectionValueSchemas, PrdService, PrdSummary, PrdSummarySchema, type PrdTemplate, type PrdVerificationDiagnostic, type PrdVerificationResult, RemoveAttachmentInput, RemoveAttachmentInputSchema, RemoveAttachmentOutput, RemoveAttachmentOutputSchema, ReorderPhasesInput, ReorderPhasesInputSchema, ResolveOpenQuestionInput, ResolveOpenQuestionInputSchema, ResolveOpenQuestionOutput, ResolveOpenQuestionOutputSchema, type RiskItem, StoryAttachment, StoryAttachmentSchema, type StoryComplexity, StoryComplexitySchema, type StoryLogEntry, StoryLogEntrySchema, type StoryPriority, StoryPrioritySchema, type StoryStatus, StoryStatusSchema, type StoryTraceabilityMap, type StoryVerification, StoryVerificationSchema, type StructuredPRD, type TemplateId, UpdateAttachmentInput, UpdateAttachmentInputSchema, UpdateAttachmentOutput, UpdateAttachmentOutputSchema, UpdatePhaseInput, UpdatePhaseInputSchema, UpdatePrdSectionInput, UpdatePrdSectionInputSchema, UpdatePrdSectionOutput, UpdatePrdSectionOutputSchema, UpdateStoryStatusInput, UpdateStoryStatusInputSchema, UpdateStoryStatusOutput, UpdateStoryStatusOutputSchema, UpdateUserStoryInput, UpdateUserStoryInputSchema, UpdateUserStoryOutput, UpdateUserStoryOutputSchema, type UserStory, createPrdService, normalizePrd };
File without changes