@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.
- package/.turbo/turbo-build.log +46 -0
- package/.turbo/turbo-test.log +21 -0
- package/.turbo/turbo-typecheck.log +1 -0
- package/README.md +64 -2
- package/dist/LICENSE +21 -0
- package/dist/README.md +65 -0
- package/dist/index.d.ts +227 -0
- package/dist/index.js +1897 -0
- package/dist/index.mjs +1791 -0
- package/dist/mcp.d.ts +9 -0
- package/dist/mcp.js +532 -0
- package/dist/mcp.mjs +531 -0
- package/dist/node.d.ts +19 -0
- package/dist/node.js +94 -0
- package/dist/node.mjs +92 -0
- package/dist/package.json +49 -0
- package/dist/prd.service-DSBp8sMl.d.ts +2327 -0
- package/dist/prompts-Bber0S1Z.mjs +778 -0
- package/dist/prompts-CIX8IeAx.js +1233 -0
- package/package.json +66 -4
- package/src/__tests__/agent-workflow.test.ts +377 -0
- package/src/__tests__/attachments.test.ts +475 -0
- package/src/__tests__/node.test.ts +141 -0
- package/src/__tests__/plan-check.test.ts +229 -0
- package/src/__tests__/planning.test.ts +1059 -0
- package/src/__tests__/prd-operations.test.ts +423 -0
- package/src/__tests__/prd.service.test.ts +477 -0
- package/src/__tests__/prd.tool.test.ts +282 -0
- package/src/__tests__/templates.test.ts +141 -0
- package/src/applicability.ts +73 -0
- package/src/attachment-paths.ts +78 -0
- package/src/attachments.ts +160 -0
- package/src/edge-cases.ts +52 -0
- package/src/index.ts +35 -0
- package/src/markdown.ts +268 -0
- package/src/mcp/index.ts +839 -0
- package/src/mcp/tool-response.ts +85 -0
- package/src/node.ts +146 -0
- package/src/open-questions.ts +93 -0
- package/src/plan-check.ts +282 -0
- package/src/planning-operations.ts +429 -0
- package/src/prd-operations.ts +690 -0
- package/src/prd.service.ts +1051 -0
- package/src/prompts.ts +110 -0
- package/src/safe-file-name.ts +42 -0
- package/src/schema.ts +976 -0
- package/src/templates.ts +173 -0
- package/src/testing/fake-mcp-server.ts +81 -0
- package/src/types.ts +333 -0
- package/tsconfig.json +23 -0
- package/tsconfig.lib.json +8 -0
- package/tsconfig.spec.json +7 -0
- package/tsdown.config.mts +11 -0
- package/vitest.config.mts +8 -0
package/src/prompts.ts
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { type TemplateId, getTemplate } from './templates';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The instructions behind the MCP prompts, exported so other tools (e.g. a
|
|
5
|
+
* UI that shows what to ask the agent) give exactly the same text.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export function shapePrdPrompt(
|
|
9
|
+
idea?: string,
|
|
10
|
+
filename?: string,
|
|
11
|
+
templateId?: TemplateId,
|
|
12
|
+
) {
|
|
13
|
+
const template = templateId ? getTemplate(templateId) : null;
|
|
14
|
+
|
|
15
|
+
const start = filename
|
|
16
|
+
? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.`
|
|
17
|
+
: idea
|
|
18
|
+
? `The idea: ${idea}`
|
|
19
|
+
: 'Start by asking what we are building, in a sentence or two.';
|
|
20
|
+
|
|
21
|
+
return [
|
|
22
|
+
`We are shaping a product requirements document before any code is written. ${start}`,
|
|
23
|
+
'',
|
|
24
|
+
'How to run the interview:',
|
|
25
|
+
'- Think of the plan as a tree of decisions. In each round, ask only the questions that can be answered now, i.e. whose prerequisites are already decided. Number them.',
|
|
26
|
+
'- Give a recommended answer for every question, with a one-line reason, worded so that replying "yes" accepts it. The user can accept, change or discuss each one.',
|
|
27
|
+
'- Look up facts yourself (the codebase, existing PRDs, docs) instead of asking. Only decisions go to the user.',
|
|
28
|
+
'- PRD text may use Markdown. Keep list items (criteria, non-goals, open questions) to one line of inline Markdown: bold, code, links. No raw HTML.',
|
|
29
|
+
'- Before the first round, read CLAUDE.md, AGENTS.md and package.json to learn the stack and whether the project starts from a kit or starter. Do not plan stories for what it already provides (e.g. sign-in, billing, teams); add those to assumptions instead (update_prd_section replaces the list, so pass the existing items too).',
|
|
30
|
+
'- After each round, record what was decided before asking the next round.',
|
|
31
|
+
'- Stop when no undecided questions remain, and confirm with the user before slicing the work.',
|
|
32
|
+
'',
|
|
33
|
+
template
|
|
34
|
+
? `This is a "${template.name}" (${template.description}) Create the PRD with template "${template.id}", and make sure the interview covers: ${template.interviewFocus.join(' ')}`
|
|
35
|
+
: 'If you are unsure what kind of work this is, call list_templates and suggest one.',
|
|
36
|
+
'',
|
|
37
|
+
'Order of the rounds, broad to detailed:',
|
|
38
|
+
'1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).',
|
|
39
|
+
'2. Main features, then what we are explicitly NOT building (update_prd_section with nonGoals and outOfScope). Be explicit: anything unlisted is likely to be invented later.',
|
|
40
|
+
'3. Whether this is an internal tool or a product for many customers or tenants. It changes what should be configurable versus hard-coded.',
|
|
41
|
+
'4. The main entities and the words for them (add_glossary_term, including words to avoid). Describe each entity, what it holds and how it relates to the others in plain language, e.g. "Bookmark: a saved link. Belongs to one account; has many tags." Record them with update_prd_section, section "technicalContracts", value { dataModels: [...] }. The list replaces the previous one, so always pass every entity.',
|
|
42
|
+
'5. Outside services (email, payments, storage, AI, SMS, maps...): for each feature that needs one, recommend a provider and list the credentials or environment variables the user must get. Record them with update_prd_section, section "technicalRequirements", value { integrationNeeds: [...] }, one entry per service, e.g. "Payments: Stripe. Needs STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET." The list replaces the previous one, so always pass every service.',
|
|
43
|
+
'6. For each feature: what is in and out of scope, and what a person must be able to do (acceptance criteria).',
|
|
44
|
+
'7. What can go wrong. Take an adversarial view: assume users make mistakes, data is messy, networks and outside services fail, and two people act at once. Go through each feature and find the failure modes before the user has to think of them: missing or invalid input, empty and very large data, partial success and retries, duplicates and double submits, concurrent edits, time zones and dates, limits and quotas, outside services failing or slow, deleting and undoing. For each one, recommend what should happen. Record them with update_prd_section, section "edgeCases", value [{ case, expectedBehavior, status, storyIds }]: "decided" once the user agreed, "open" while it needs an answer. The list replaces the previous one, so always pass every case. Do not slice the work while any edge case is open.',
|
|
45
|
+
'8. Security. Switch to an attacker\'s mindset: for each feature, ask how a malicious user, a curious user of another account or tenant, or a compromised integration would abuse it, and assume they will try. Probe at least: changing ids in URLs and requests to reach other people\'s data; acting above one\'s role; hostile input (SQL, HTML and script, prompt injection into AI features, path traversal, oversized payloads); hostile file uploads; forged or replayed webhooks; brute force and account or email enumeration; abuse of costly actions (spam, quotas, paid APIs); secrets reaching the browser, logs or error messages; server requests to user-supplied URLs. Recommend a defence for each one that applies, then record: who can see and change what in update_prd_section "technicalContracts" { permissions: [...] }; sensitive data and legal duties (personal data, payments, retention, deletion) in "technicalRequirements" { complianceRequirements: [...] }; the standing rules that prevent abuse in "securityConsiderations"; and each concrete attack as an edge case with the safe behaviour (e.g. "User opens another account\'s invoice by changing the id" -> "404, nothing about it is revealed"). These lists replace the previous ones, so pass every item.',
|
|
46
|
+
'9. Risks. Run a pre-mortem: assume the feature shipped and failed badly six months later, and work out why (data loss, a security incident, cost running away, an outside dependency changing, nobody using it, legal trouble, the team unable to maintain it). Record specific risks, not generic ones, with severity, mitigation and owner via update_prd_section "risks".',
|
|
47
|
+
'10. Design: how it should look and feel. Ask for or suggest standing rules (which components and layout to use, tone of copy, mobile, how empty, loading and error states look) and record them with update_prd_section, section "designGuidance". Save mockups as attachments. Record individual design choices with add_decision and a topic starting with "design:", e.g. "design:navigation".',
|
|
48
|
+
'11. Hard-to-reverse choices (add_decision). A question the user cannot answer now goes to update_prd_section "openQuestions" as { question, why, options, recommended, storyIds }: why says what goes wrong if an agent guesses, options are the real choices, recommended is your suggestion, and storyIds are the stories it blocks. Write it so a person can answer it later without this conversation. Keep the ids of existing questions (the list replaces the previous one). Answers are recorded with resolve_open_question.',
|
|
49
|
+
'12. If a part genuinely does not apply (no outside services; no rollout plan for an internal tool), mark it with mark_not_applicable and a reason instead of leaving it empty. Never mark security or edge cases as not applicable for a feature that takes input from people or stores their data.',
|
|
50
|
+
'',
|
|
51
|
+
'Then slice the work:',
|
|
52
|
+
'- Each story is a thin slice through every layer that a person can try once it is done, and that fits in one agent session. Put refactoring needed by later stories in its own earlier story.',
|
|
53
|
+
'- Create the phases first (create_custom_phase), in the order they should be built. Each phase should end with something a person can try (a page in the app, an API call, a command); say what in its description.',
|
|
54
|
+
'- Add each story with add_user_story in one call: testSeams (the public entry points the tests will exercise), dependencies (stories that must be completed first) and phaseId. Add designNotes when the story has a screen or states the PRD design guidance does not settle, and securityNotes for each way this story in particular could be abused (whose ids it accepts, what input it trusts, what it costs to repeat) with the defence. Do not repeat the PRD-wide guidance or considerations there.',
|
|
55
|
+
'- When the user shares mockups, screenshots or reference docs, save each file in the PRD folder (.prds/<prd file name without .json>/) and record it with add_attachment, linking the stories that use it. Record links to outside docs with a url instead.',
|
|
56
|
+
'- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase.',
|
|
57
|
+
].join('\n');
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function reviewStoryPrompt(
|
|
61
|
+
filename: string,
|
|
62
|
+
storyId: string,
|
|
63
|
+
base?: string,
|
|
64
|
+
) {
|
|
65
|
+
const diff = base
|
|
66
|
+
? `git diff ${base}`
|
|
67
|
+
: 'git diff HEAD (plus untracked files from git status)';
|
|
68
|
+
|
|
69
|
+
return [
|
|
70
|
+
`Review the work done for story ${storyId} in the PRD "${filename}". You are checking it against its spec, not reviewing code style: a separate review covers code quality.`,
|
|
71
|
+
'',
|
|
72
|
+
`1. Call get_story for the acceptance criteria, non-goals, out-of-scope items, test seams and the story log. Read the changes with ${diff}.`,
|
|
73
|
+
'2. For each acceptance criterion, decide met, partly met or not met, and cite the file or test that shows it.',
|
|
74
|
+
'3. Scope: list changes the story did not ask for, especially anything in non-goals or out of scope.',
|
|
75
|
+
'4. Tests: check that tests exercise the listed test seams and cover the criteria and the decided edge cases through public behaviour.',
|
|
76
|
+
'5. Security, as an attacker: for every new route, action or query, try to reach another user\'s or tenant\'s data by changing ids, act above your role, send hostile or oversized input, and repeat or replay requests. Check that the permissions and security rules in get_story are enforced on the server and tested. List each hole you find with the file and how to exploit it.',
|
|
77
|
+
'6. Check that the story log matches what changed. Flag claims in whatsNew that the changes do not support, and departures from the spec that are not listed in deviations.',
|
|
78
|
+
'',
|
|
79
|
+
'Report:',
|
|
80
|
+
'- Verdict: "approve" or "send back".',
|
|
81
|
+
'- Criteria: one line per criterion with its result and evidence.',
|
|
82
|
+
'- Scope: extra or missing work, or "none".',
|
|
83
|
+
'- Deviations: whether each one listed in the log is acceptable, or "none".',
|
|
84
|
+
'- Security: holes found, or "none".',
|
|
85
|
+
'- Tests: gaps, or "none".',
|
|
86
|
+
'- If sending back: a short list of specific fixes, written for the agent that will make them.',
|
|
87
|
+
'',
|
|
88
|
+
'Do not change the story status and do not edit code. A person decides.',
|
|
89
|
+
].join('\n');
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export function implementStoryPrompt(filename: string, storyId?: string) {
|
|
93
|
+
const pick = storyId
|
|
94
|
+
? `Work on story ${storyId}.`
|
|
95
|
+
: 'Call get_next_story. If a story is already in progress (for example one sent back from review), finish that one first; otherwise take the story it returns. If none is ready, report why and stop.';
|
|
96
|
+
|
|
97
|
+
return [
|
|
98
|
+
`You are implementing a story from the PRD "${filename}". ${pick}`,
|
|
99
|
+
'',
|
|
100
|
+
'1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer\'s feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. Build only what this story asks for.',
|
|
101
|
+
' Its edge_cases are part of the spec: implement and test each decided case as stated. If a case is still open, ask the user what should happen before building that part; never pick a behaviour yourself. Follow the design guidance, design decisions and the story\'s own design.story_notes for anything a person sees.',
|
|
102
|
+
' If open_questions lists questions that block this story, ask the user, record the answer with resolve_open_question, and only then build the part it affects.',
|
|
103
|
+
' The security rules are binding, including the story\'s own security.story_notes: enforce the permissions on the server for every read and write, never trust input from the browser, and keep secrets out of the client and logs. Before finishing, attack your own change: try another user\'s ids, a lower role, hostile input and repeated requests, and add tests for what you find. Parts listed in not_applicable do not apply: do not build them.',
|
|
104
|
+
'2. Call update_story_status with status "in_progress".',
|
|
105
|
+
'3. Plan the change, then implement it with tests that cover the acceptance criteria.',
|
|
106
|
+
'4. Run the project checks and fix what fails.',
|
|
107
|
+
'5. Call add_story_log: whatsNew lists what a person can now try, in plain language; technicalNotes lists decisions, gotchas and files the next agent should know about; deviations lists where the work departed from the PRD (a criterion changed or skipped, extra scope, a different approach) and why. Leave deviations empty if there were none.',
|
|
108
|
+
'6. Call update_story_status with status "review". Do not mark the story completed; a person approves it.',
|
|
109
|
+
].join('\n');
|
|
110
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Accept only a bare file name. Anything that could escape the intended
|
|
3
|
+
* directory (path separators, parent references, hidden files) is rejected
|
|
4
|
+
* before the filesystem is touched.
|
|
5
|
+
*/
|
|
6
|
+
export function assertSafeFileName(value: string, label = 'file name') {
|
|
7
|
+
const name = value.trim();
|
|
8
|
+
|
|
9
|
+
if (
|
|
10
|
+
name.length === 0 ||
|
|
11
|
+
name.includes('..') ||
|
|
12
|
+
name.includes('/') ||
|
|
13
|
+
name.includes('\\') ||
|
|
14
|
+
name.startsWith('.')
|
|
15
|
+
) {
|
|
16
|
+
throw new Error(`Invalid ${label} "${value}"`);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
return name;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Accept only a relative path that stays inside the directory it is joined
|
|
24
|
+
* to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
|
|
25
|
+
* This is a check on the text only; code that serves the file must still
|
|
26
|
+
* resolve symlinks before reading it.
|
|
27
|
+
*/
|
|
28
|
+
export function assertSafeRelativePath(value: string, label = 'path') {
|
|
29
|
+
const path = value.trim();
|
|
30
|
+
const segments = path.split('/');
|
|
31
|
+
|
|
32
|
+
if (
|
|
33
|
+
path.length === 0 ||
|
|
34
|
+
path.includes('\\') ||
|
|
35
|
+
/^[a-zA-Z]:/.test(path) ||
|
|
36
|
+
segments.some((segment) => segment.length === 0 || segment.startsWith('.'))
|
|
37
|
+
) {
|
|
38
|
+
throw new Error(`Invalid ${label} "${value}"`);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
return path;
|
|
42
|
+
}
|