@makerkit/prd 0.0.4 → 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} +155 -562
  10. package/{index.mjs → dist/index.mjs} +87 -497
  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-oI_6dxvx.js → dist/prompts-1qhax_dj.js} +113 -164
  25. package/{prompts-CPlFVutB.mjs → dist/prompts-BlsYD0gf.mjs} +96 -129
  26. package/{prd.service-CV0-aQHk.d.ts → dist/schema-BwTnt0B9.d.ts} +424 -336
  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 -233
  63. /package/{LICENSE → dist/LICENSE} +0 -0
@@ -0,0 +1,78 @@
1
+ $ tsdown && node ../../scripts/prepare-dist.mjs
2
+ ℹ tsdown v0.23.7 powered by rolldown v1.3.2
3
+ ℹ config file: /Users/giancarlo/Code/makerkit/packages/prd/tsdown.config.mts
4
+ ℹ entry: src/index.ts, src/prd-operations.ts, src/node.ts, src/mcp/index.ts
5
+ ℹ entry: src/index.ts, src/prd-operations.ts, src/node.ts, src/mcp/index.ts
6
+ ℹ tsconfig: tsconfig.lib.json
7
+ ℹ tsconfig: tsconfig.lib.json
8
+ ℹ Build start
9
+ ℹ Cleaning 15 files
10
+
11
+  WARN  The `tsgo` generator on TypeScript 7.0 is deprecated and will be removed in the next minor. Upgrade to TypeScript 7.1 or later.
12
+
13
+ ℹ Emit types with typescript@7.0.2
14
+ ℹ [ESM] dist/index.mjs 64.25 kB │ gzip: 16.66 kB
15
+ ℹ [ESM] dist/mcp.mjs 25.05 kB │ gzip: 5.63 kB
16
+ ℹ [ESM] dist/node.mjs  3.85 kB │ gzip: 1.54 kB
17
+ ℹ [ESM] dist/operations.mjs  0.48 kB │ gzip: 0.28 kB
18
+ ℹ [ESM] dist/prompts-BlsYD0gf.mjs 60.23 kB │ gzip: 17.91 kB
19
+ ℹ [ESM] dist/prd-operations-BvFxo9bg.mjs 18.86 kB │ gzip: 5.81 kB
20
+ ℹ [ESM] dist/attachment-paths-C-SWgoSx.mjs  3.00 kB │ gzip: 1.24 kB
21
+ ℹ [ESM] 7 files, total: 175.72 kB
22
+ ℹ [CJS] dist/index.js 68.23 kB │ gzip: 16.45 kB
23
+ ℹ [CJS] dist/mcp.js 24.70 kB │ gzip: 5.27 kB
24
+ ℹ [CJS] dist/node.js  4.21 kB │ gzip: 1.63 kB
25
+ ℹ [CJS] dist/operations.js  1.45 kB │ gzip: 0.39 kB
26
+ ℹ [CJS] dist/prompts-1qhax_dj.js 72.56 kB │ gzip: 18.35 kB
27
+ ℹ [CJS] dist/prd-operations-CcahfbOy.js 21.02 kB │ gzip: 5.93 kB
28
+ ℹ [CJS] dist/attachment-paths-BAhRGiib.js  3.62 kB │ gzip: 1.30 kB
29
+ ℹ [CJS] 7 files, total: 195.79 kB
30
+ src/node.ts (5:27) [UNRESOLVED_IMPORT] Could not resolve 'node:crypto' in src/node.ts
31
+ ╭─[ src/node.ts:5:28 ]
32
+ │
33
+ 5 │ import { randomUUID } from 'node:crypto';
34
+  │ ──────┬──────
35
+  │ ╰──────── Module not found, treating it as an external dependency
36
+  │
37
+  │ Help: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
38
+ ───╯
39
+
40
+ src/node.ts (16:7) [UNRESOLVED_IMPORT] Could not resolve 'node:fs/promises' in src/node.ts
41
+ ╭─[ src/node.ts:16:8 ]
42
+ │
43
+ 16 │ } from 'node:fs/promises';
44
+  │ ─────────┬────────
45
+  │ ╰────────── Module not found, treating it as an external dependency
46
+  │
47
+  │ Help: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
48
+ ────╯
49
+
50
+ src/node.ts (17:30) [UNRESOLVED_IMPORT] Could not resolve 'node:path' in src/node.ts
51
+ ╭─[ src/node.ts:17:31 ]
52
+ │
53
+ 17 │ import { join, resolve } from 'node:path';
54
+  │ ─────┬─────
55
+  │ ╰─────── Module not found, treating it as an external dependency
56
+  │
57
+  │ Help: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
58
+ ────╯
59
+
60
+ src/prd.service.ts (104:48) [UNRESOLVED_IMPORT] Could not resolve 'node:path' in src/prd.service.ts
61
+ ╭─[ src/prd.service.ts:104:49 ]
62
+ │
63
+ 104 │ import { isAbsolute, join, relative, sep } from 'node:path';
64
+  │ ─────┬─────
65
+  │ ╰─────── Module not found, treating it as an external dependency
66
+  │
67
+  │ Help: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
68
+ ─────╯
69
+
70
+ ✔ Build complete in 48ms
71
+ ℹ [CJS] dist/index.d.ts 12.70 kB │ gzip: 3.33 kB
72
+ ℹ [CJS] dist/operations.d.ts  5.62 kB │ gzip: 1.88 kB
73
+ ℹ [CJS] dist/node.d.ts  0.99 kB │ gzip: 0.53 kB
74
+ ℹ [CJS] dist/mcp.d.ts  0.38 kB │ gzip: 0.27 kB
75
+ ℹ [CJS] dist/schema-BwTnt0B9.d.ts 85.41 kB │ gzip: 11.81 kB
76
+ ℹ [CJS] dist/prd.service-CTwKZV-3.d.ts  7.05 kB │ gzip: 2.27 kB
77
+ ℹ [CJS] 6 files, total: 112.15 kB
78
+ ✔ Build complete in 189ms
@@ -0,0 +1,19 @@
1
+ $ vitest run
2
+
3
+  RUN  v5.0.4 /Users/giancarlo/Code/makerkit/packages/prd
4
+
5
+ ✓ src/__tests__/templates.test.ts (4 tests) 6ms
6
+ ✓ src/__tests__/prd.tool.test.ts (9 tests) 12ms
7
+ ✓ src/__tests__/agent-workflow.test.ts (13 tests) 12ms
8
+ ✓ src/__tests__/prd-operations.test.ts (30 tests) 5ms
9
+ ✓ src/__tests__/attachments.test.ts (16 tests) 13ms
10
+ ✓ src/__tests__/plan-check.test.ts (16 tests) 8ms
11
+ ✓ src/__tests__/prd.service.test.ts (21 tests) 13ms
12
+ ✓ src/__tests__/planning.test.ts (41 tests) 25ms
13
+ ✓ src/__tests__/node.test.ts (7 tests) 929ms
14
+
15
+  Test Files  9 passed (9)
16
+  Tests  157 passed (157)
17
+  Start at  16:21:58
18
+  Duration  1.06s (tests 57%, transform 31%, import 11%, worker 2%)
19
+
@@ -0,0 +1,6 @@
1
+ $ tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.spec.json
2
+ src/__tests__/planning.test.ts(443,27): error TS2339: Property 'story_notes' does not exist on type '{ guidance: string[]; decisions: { id: string; decision: string; rationale: string; }[]; }'.
3
+ src/__tests__/planning.test.ts(446,29): error TS2339: Property 'story_notes' does not exist on type '{ permissions: string[]; compliance: string[]; considerations: string[]; }'.
4
+ src/__tests__/planning.test.ts(480,27): error TS2339: Property 'story_notes' does not exist on type '{ guidance: string[]; decisions: { id: string; decision: string; rationale: string; }[]; }'.
5
+ src/__tests__/planning.test.ts(481,29): error TS2339: Property 'story_notes' does not exist on type '{ permissions: string[]; compliance: string[]; considerations: string[]; }'.
6
+ [ELIFECYCLE] Command failed with exit code 2.
package/README.md CHANGED
@@ -7,7 +7,11 @@ Structured product requirements documents (PRDs) stored as JSON files in `.prds/
7
7
  - **Completion gate**: a story can only be marked `completed` when the project's checks pass, so "done" means the code verifies.
8
8
  - **MCP tools**: the same operations exposed to Claude Code, Codex, OpenCode or any MCP client.
9
9
  - **Attachments**: files (mockups, screenshots, reference docs) live in a folder next to the PRD, `.prds/<prd name>/`, and links can be recorded too. Stories reference them by id, and `get_story` returns them with their paths.
10
- - **Prompts**: `shape_prd` interviews you round by round (numbered questions, each with a recommended answer and its reason) and writes every decision into the PRD; `architect_prd` designs the shape all stories share (using the project's `architect` skill when it has one) and records it as an attachment the story agents build against; `implement_story` walks an agent through one story and its hand-off log; `review_story` checks the result against the spec. The same text is exported (`shapePrdPrompt`, `architectPrdPrompt`, `implementStoryPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
10
+ - **Prompts**: `shape_prd` interviews you round by round (numbered questions, each with a recommended answer and its reason) and writes every decision into the PRD; `architect_prd` designs the shape all stories share (using the project's `architect` skill when it has one) and records it as an attachment the story agents build against; `implement_story` implements ready stories in sequence, with a single-story mode for parallel workers; `review_story` checks the result against the spec. The same text is exported (`shapePrdPrompt`, `architectPrdPrompt`, `implementStoryPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
11
+
12
+ Pass `mode: "light"` to `shape_prd` for a shorter interview focused on scope, user-visible behaviour, and decisions that block stories. The default is `"detailed"`. In TypeScript, pass the mode as the third argument to `shapePrdPrompt`.
13
+
14
+ A PRD can have optional roadmap metadata in its top-level `roadmap` object. Set `order` (a non-negative integer), `criticality` (`critical`, `high`, `medium`, or `low`), and any of `plan`, `group`, and `section`. Supply it to `create_prd`, or patch it with `update_prd_section` using `section: "roadmap"`. Set a field to `null` in a patch to clear it. `list_prds` sorts explicit orders first, then higher criticality within each order. It returns the roadmap metadata with each PRD so clients can group the list.
11
15
 
12
16
  ## Install
13
17
 
@@ -23,6 +27,8 @@ import { createNodePrdDeps } from '@makerkit/prd/node';
23
27
 
24
28
  const prds = createPrdService(createNodePrdDeps(process.cwd()));
25
29
 
30
+ // To use a different directory, pass { prdsDir: "docs/prds" } as the second argument.
31
+
26
32
  const { prds: list } = await prds.list();
27
33
  ```
28
34
 
package/dist/README.md ADDED
@@ -0,0 +1,71 @@
1
+ # @makerkit/prd
2
+
3
+ Structured product requirements documents (PRDs) stored as JSON files in `.prds/`, plus the tools to manage them from code or from a coding agent over MCP.
4
+
5
+ - **Format**: a typed `StructuredPRD` (stories, statuses, priorities, dependencies, phases, risks, decisions) with Zod schemas. Hand-written files are normalized on load. Text fields may use Markdown; list items (acceptance criteria, non-goals, ...) keep to inline Markdown, and raw HTML is not rendered.
6
+ - **Service**: create PRDs, add and update user stories, move stories through `not_started → research → in_progress → review → completed`, export markdown.
7
+ - **Completion gate**: a story can only be marked `completed` when the project's checks pass, so "done" means the code verifies.
8
+ - **MCP tools**: the same operations exposed to Claude Code, Codex, OpenCode or any MCP client.
9
+ - **Attachments**: files (mockups, screenshots, reference docs) live in a folder next to the PRD, `.prds/<prd name>/`, and links can be recorded too. Stories reference them by id, and `get_story` returns them with their paths.
10
+ - **Prompts**: `shape_prd` interviews you round by round (numbered questions, each with a recommended answer and its reason) and writes every decision into the PRD; `architect_prd` designs the shape all stories share (using the project's `architect` skill when it has one) and records it as an attachment the story agents build against; `implement_story` implements ready stories in sequence, with a single-story mode for parallel workers; `review_story` checks the result against the spec. The same text is exported (`shapePrdPrompt`, `architectPrdPrompt`, `implementStoryPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
11
+
12
+ Pass `mode: "light"` to `shape_prd` for a shorter interview focused on scope, user-visible behaviour, and decisions that block stories. The default is `"detailed"`. In TypeScript, pass the mode as the third argument to `shapePrdPrompt`.
13
+
14
+ A PRD can have optional roadmap metadata in its top-level `roadmap` object. Set `order` (a non-negative integer), `criticality` (`critical`, `high`, `medium`, or `low`), and any of `plan`, `group`, and `section`. Supply it to `create_prd`, or patch it with `update_prd_section` using `section: "roadmap"`. Set a field to `null` in a patch to clear it. `list_prds` sorts explicit orders first, then higher criticality within each order. It returns the roadmap metadata with each PRD so clients can group the list.
15
+
16
+ ## Install
17
+
18
+ ```bash
19
+ pnpm add @makerkit/prd
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ```ts
25
+ import { createPrdService } from '@makerkit/prd';
26
+ import { createNodePrdDeps } from '@makerkit/prd/node';
27
+
28
+ const prds = createPrdService(createNodePrdDeps(process.cwd()));
29
+
30
+ // To use a different directory, pass { prdsDir: "docs/prds" } as the second argument.
31
+
32
+ const { prds: list } = await prds.list();
33
+ ```
34
+
35
+ By default, completing a story runs the project's `typecheck` and `lint` scripts with its package manager (scripts that do not exist are skipped). Pass your own check instead:
36
+
37
+ ```ts
38
+ createNodePrdDeps(root, {
39
+ verifyCompletion: async () => ({
40
+ passed: true,
41
+ checks: ['custom'],
42
+ errors: 0,
43
+ warnings: 0,
44
+ diagnostics: [],
45
+ messages: [],
46
+ }),
47
+ });
48
+ ```
49
+
50
+ ### MCP
51
+
52
+ Requires `@modelcontextprotocol/sdk`.
53
+
54
+ ```ts
55
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
56
+ import { createPrdService } from '@makerkit/prd';
57
+ import { registerPRDTools } from '@makerkit/prd/mcp';
58
+ import { createNodePrdDeps } from '@makerkit/prd/node';
59
+
60
+ const server = new McpServer({ name: 'prd', version: '1.0.0' });
61
+
62
+ registerPRDTools(server, createPrdService(createNodePrdDeps()));
63
+ ```
64
+
65
+ ## Credits
66
+
67
+ The `shape_prd` interview and the story-slicing rules are adapted from ideas in Matt Pocock's [skills](https://github.com/mattpocock/skills) (MIT), in particular grilling and to-tickets.
68
+
69
+ ## License
70
+
71
+ MIT
@@ -0,0 +1,112 @@
1
+ // src/safe-file-name.ts
2
+ /**
3
+ * Accept only a bare file name. Anything that could escape the intended
4
+ * directory (path separators, parent references, hidden files) is rejected
5
+ * before the filesystem is touched.
6
+ */
7
+ function assertSafeFileName(value, label = "file name") {
8
+ const name = value.trim();
9
+ if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
10
+ return name;
11
+ }
12
+ /**
13
+ * Accept only a relative path that stays inside the directory it is joined
14
+ * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
15
+ * This is a check on the text only; code that serves the file must still
16
+ * resolve symlinks before reading it.
17
+ */
18
+ function assertSafeRelativePath(value, label = "path") {
19
+ const path = value.trim();
20
+ const segments = path.split("/");
21
+ if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
22
+ return path;
23
+ }
24
+ // src/attachment-paths.ts
25
+ /**
26
+ * The folder for a PRD's files, relative to `.prds`: the PRD file name
27
+ * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
28
+ */
29
+ function attachmentsFolder(filename) {
30
+ return filename.replace(/\.json$/, "");
31
+ }
32
+ /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
33
+ function attachmentProjectPath(filename, path, prdsPath = ".prds") {
34
+ return `${prdsPath.replace(/\/$/, "")}/${attachmentsFolder(filename)}/${path}`;
35
+ }
36
+ /** Attachments as an agent needs them: file paths from the project root. */
37
+ function resolveAttachments(filename, attachments, prdsPath) {
38
+ return attachments.map(({ path, ...attachment }) => ({
39
+ ...attachment,
40
+ ...path ? { path: attachmentProjectPath(filename, path, prdsPath) } : {}
41
+ }));
42
+ }
43
+ /**
44
+ * Attachments as stored, with hand-edited entries that would break readers
45
+ * or point outside the PRD folder dropped: each needs a string id and title
46
+ * and either a safe relative path or an http(s) url.
47
+ */
48
+ function normalizeAttachments(value) {
49
+ if (!Array.isArray(value)) return [];
50
+ return value.flatMap((entry) => {
51
+ if (typeof entry !== "object" || entry === null) return [];
52
+ const { id, title, path, url, note } = entry;
53
+ if (typeof id !== "string" || typeof title !== "string") return [];
54
+ const base = {
55
+ id,
56
+ title,
57
+ ...typeof note === "string" && note ? { note } : {}
58
+ };
59
+ if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
60
+ ...base,
61
+ path
62
+ }];
63
+ if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
64
+ ...base,
65
+ url
66
+ }];
67
+ return [];
68
+ });
69
+ }
70
+ function isSafePath(path) {
71
+ try {
72
+ return assertSafeRelativePath(path) === path;
73
+ } catch {
74
+ return false;
75
+ }
76
+ }
77
+ Object.defineProperty(exports, "assertSafeFileName", {
78
+ enumerable: true,
79
+ get: function() {
80
+ return assertSafeFileName;
81
+ }
82
+ });
83
+ Object.defineProperty(exports, "assertSafeRelativePath", {
84
+ enumerable: true,
85
+ get: function() {
86
+ return assertSafeRelativePath;
87
+ }
88
+ });
89
+ Object.defineProperty(exports, "attachmentProjectPath", {
90
+ enumerable: true,
91
+ get: function() {
92
+ return attachmentProjectPath;
93
+ }
94
+ });
95
+ Object.defineProperty(exports, "attachmentsFolder", {
96
+ enumerable: true,
97
+ get: function() {
98
+ return attachmentsFolder;
99
+ }
100
+ });
101
+ Object.defineProperty(exports, "normalizeAttachments", {
102
+ enumerable: true,
103
+ get: function() {
104
+ return normalizeAttachments;
105
+ }
106
+ });
107
+ Object.defineProperty(exports, "resolveAttachments", {
108
+ enumerable: true,
109
+ get: function() {
110
+ return resolveAttachments;
111
+ }
112
+ });
@@ -0,0 +1,77 @@
1
+ // src/safe-file-name.ts
2
+ /**
3
+ * Accept only a bare file name. Anything that could escape the intended
4
+ * directory (path separators, parent references, hidden files) is rejected
5
+ * before the filesystem is touched.
6
+ */
7
+ function assertSafeFileName(value, label = "file name") {
8
+ const name = value.trim();
9
+ if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
10
+ return name;
11
+ }
12
+ /**
13
+ * Accept only a relative path that stays inside the directory it is joined
14
+ * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
15
+ * This is a check on the text only; code that serves the file must still
16
+ * resolve symlinks before reading it.
17
+ */
18
+ function assertSafeRelativePath(value, label = "path") {
19
+ const path = value.trim();
20
+ const segments = path.split("/");
21
+ if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
22
+ return path;
23
+ }
24
+ // src/attachment-paths.ts
25
+ /**
26
+ * The folder for a PRD's files, relative to `.prds`: the PRD file name
27
+ * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
28
+ */
29
+ function attachmentsFolder(filename) {
30
+ return filename.replace(/\.json$/, "");
31
+ }
32
+ /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
33
+ function attachmentProjectPath(filename, path, prdsPath = ".prds") {
34
+ return `${prdsPath.replace(/\/$/, "")}/${attachmentsFolder(filename)}/${path}`;
35
+ }
36
+ /** Attachments as an agent needs them: file paths from the project root. */
37
+ function resolveAttachments(filename, attachments, prdsPath) {
38
+ return attachments.map(({ path, ...attachment }) => ({
39
+ ...attachment,
40
+ ...path ? { path: attachmentProjectPath(filename, path, prdsPath) } : {}
41
+ }));
42
+ }
43
+ /**
44
+ * Attachments as stored, with hand-edited entries that would break readers
45
+ * or point outside the PRD folder dropped: each needs a string id and title
46
+ * and either a safe relative path or an http(s) url.
47
+ */
48
+ function normalizeAttachments(value) {
49
+ if (!Array.isArray(value)) return [];
50
+ return value.flatMap((entry) => {
51
+ if (typeof entry !== "object" || entry === null) return [];
52
+ const { id, title, path, url, note } = entry;
53
+ if (typeof id !== "string" || typeof title !== "string") return [];
54
+ const base = {
55
+ id,
56
+ title,
57
+ ...typeof note === "string" && note ? { note } : {}
58
+ };
59
+ if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
60
+ ...base,
61
+ path
62
+ }];
63
+ if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
64
+ ...base,
65
+ url
66
+ }];
67
+ return [];
68
+ });
69
+ }
70
+ function isSafePath(path) {
71
+ try {
72
+ return assertSafeRelativePath(path) === path;
73
+ } catch {
74
+ return false;
75
+ }
76
+ }
77
+ export { assertSafeFileName as a, resolveAttachments as i, attachmentsFolder as n, assertSafeRelativePath as o, normalizeAttachments as r, attachmentProjectPath as t };
@@ -0,0 +1,81 @@
1
+ import { a as PrdVerificationResult, i as PrdVerificationDiagnostic, n as PrdRevisionConflictError, o as createPrdService, r as PrdService, s as normalizePrd, t as PrdDeps } from "./prd.service-CTwKZV-3.js";
2
+ import { appendChangeLog, appendStoryLog, assertCanEnterStatus, assignStoryToPhase, buildStoryContext, createPhase, deleteStory, findAttachment, findStory, incompleteDependencies, nextId, nextStoryId, pickNextStory, recomputeProgress, renderUserStory, splitUserStory, updateStory, validateAttachmentIds, validateDependencies, validateProofs } from "./operations.js";
3
+ import { $ as ExportPrdMarkdownInputSchema, $t as StoryAttachment, A as CreateCustomPhaseOutput, An as EdgeCase, At as MarkNotApplicableOutput, B as DecideEdgeCaseOutput, Bn as StoryStatus, Bt as PrdSummary, C as AssignStoryToPhaseOutput, Cn as UpdateUserStoryOutputSchema, Ct as ListPrdsOutput, D as CheckPlanOutputSchema, Dn as CrossDependency, Dt as ListTemplatesOutputSchema, E as CheckPlanOutput, En as CriterionProof, Et as ListTemplatesOutput, F as CreatePrdOutputSchema, Fn as ProofKind, Ft as PrdCriticalitySchema, G as DeletePrdInputSchema, Gt as RemoveAttachmentOutput, H as DeletePhaseInput, Hn as StoryVerification, Ht as ProofKindSchema, I as CriterionProofSchema, In as RiskItem, It as PrdRoadmapSchema, J as DeleteUserStoryInput, Jt as ReorderPhasesInputSchema, K as DeletePrdOutput, Kt as RemoveAttachmentOutputSchema, L as CustomPhaseSchema, Ln as StoryComplexity, Lt as PrdRoadmapUpdateSchema, M as CreatePrdInput, Mn as NotApplicableTopic, Mt as NotApplicableTopicSchema, N as CreatePrdInputSchema, Nn as OpenQuestion, Nt as PhasesOutput, O as CreateCustomPhaseInput, On as CustomPhase, Ot as MarkNotApplicableInput, P as CreatePrdOutput, Pn as PrdRoadmap, Pt as PhasesOutputSchema, Q as ExportPrdMarkdownInput, Qt as ResolveOpenQuestionOutputSchema, R as DecideEdgeCaseInput, Rn as StoryLogEntry, Rt as PrdSection, S as AssignStoryToPhaseInputSchema, Sn as UpdateUserStoryOutput, St as ListPrdsInputSchema, T as CheckPlanInputSchema, Tn as Attachment, Tt as ListTemplatesInputSchema, U as DeletePhaseInputSchema, Un as StructuredPRD, Ut as RemoveAttachmentInput, V as DecideEdgeCaseOutputSchema, Vn as StoryTraceabilityMap, Vt as PrdSummarySchema, W as DeletePrdInput, Wn as UserStory, Wt as RemoveAttachmentInputSchema, X as DeleteUserStoryOutput, Xt as ResolveOpenQuestionInputSchema, Y as DeleteUserStoryInputSchema, Yt as ResolveOpenQuestionInput, Z as DeleteUserStoryOutputSchema, Zt as ResolveOpenQuestionOutput, _ as AddUserStoryInput, _n as UpdateStoryStatusInputSchema, _t as GetProjectStatusOutputSchema, a as AddDecisionInput, an as StoryVerificationSchema, at as GetImprovementSuggestionsInputSchema, b as AddUserStoryOutputSchema, bn as UpdateUserStoryInput, bt as GetStoryOutput, c as AddDecisionOutputSchema, cn as UpdateAttachmentOutput, ct as GetNextStoryInputSchema, d as AddGlossaryTermOutput, dn as UpdatePhaseInputSchema, dt as GetPrdInput, en as StoryAttachmentSchema, et as ExportPrdMarkdownOutput, f as AddGlossaryTermOutputSchema, fn as UpdatePrdSectionInput, ft as GetPrdInputSchema, g as AddStoryLogOutputSchema, gn as UpdateStoryStatusInput, gt as GetProjectStatusOutput, h as AddStoryLogOutput, hn as UpdatePrdSectionOutputSchema, ht as GetProjectStatusInputSchema, i as AddAttachmentOutputSchema, in as StoryStatusSchema, it as GetImplementationPromptsOutputSchema, j as CreateCustomPhaseOutputSchema, jn as GlossaryTerm, jt as MarkNotApplicableOutputSchema, k as CreateCustomPhaseInputSchema, kn as DecisionLogEntry, kt as MarkNotApplicableInputSchema, l as AddGlossaryTermInput, ln as UpdateAttachmentOutputSchema, lt as GetNextStoryOutput, m as AddStoryLogInputSchema, mn as UpdatePrdSectionOutput, mt as GetPrdOutputSchema, n as AddAttachmentInputSchema, nn as StoryLogEntrySchema, nt as GetImplementationPromptsInputSchema, o as AddDecisionInputSchema, on as UpdateAttachmentInput, ot as GetImprovementSuggestionsOutput, p as AddStoryLogInput, pn as UpdatePrdSectionInputSchema, pt as GetPrdOutput, q as DeletePrdOutputSchema, qt as ReorderPhasesInput, r as AddAttachmentOutput, rn as StoryPrioritySchema, rt as GetImplementationPromptsOutput, s as AddDecisionOutput, sn as UpdateAttachmentInputSchema, st as GetImprovementSuggestionsOutputSchema, t as AddAttachmentInput, tn as StoryComplexitySchema, tt as ExportPrdMarkdownOutputSchema, u as AddGlossaryTermInputSchema, un as UpdatePhaseInput, ut as GetNextStoryOutputSchema, v as AddUserStoryInputSchema, vn as UpdateStoryStatusOutput, vt as GetStoryInput, w as AssignStoryToPhaseOutputSchema, wn as AgentTaskPacket, wt as ListPrdsOutputSchema, x as AssignStoryToPhaseInput, xn as UpdateUserStoryInputSchema, xt as GetStoryOutputSchema, y as AddUserStoryOutput, yn as UpdateStoryStatusOutputSchema, yt as GetStoryInputSchema, z as DecideEdgeCaseInputSchema, zn as StoryPriority, zt as PrdSectionValueSchemas } from "./schema-BwTnt0B9.js";
4
+ /**
5
+ * The folder for a PRD's files, relative to `.prds`: the PRD file name
6
+ * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
7
+ */
8
+ export declare function attachmentsFolder(filename: string): string;
9
+ /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
10
+ export declare function attachmentProjectPath(filename: string, path: string, prdsPath?: string): string;
11
+ /** Attachments as an agent needs them: file paths from the project root. */
12
+ export declare function resolveAttachments(filename: string, attachments: Attachment[], prdsPath?: string): StoryAttachment[];
13
+ /**
14
+ * Parts of a PRD that can be marked "not applicable" (e.g. no rollout plan
15
+ * for an internal tool), so the plan check stops asking for them and agents
16
+ * do not invent them. The core (overview, problem, solution, scope, stories)
17
+ * always applies.
18
+ */
19
+ export declare const NOT_APPLICABLE_TOPICS: readonly ["dataModel", "outsideServices", "security", "design", "qualityBar", "edgeCases", "rollout", "measurement", "glossary", "risks"];
20
+ export declare function isNotApplicable(prd: StructuredPRD, topic: NotApplicableTopic): boolean;
21
+ /**
22
+ * Pass the PRD file name to link attachment files relative to `.prds/`, where
23
+ * the markdown export is written.
24
+ */
25
+ export declare function formatPrdMarkdown(prd: StructuredPRD, filename?: string): string;
26
+ /**
27
+ * The instructions behind the MCP prompts, exported so other tools (e.g. a
28
+ * UI that shows what to ask the agent) give exactly the same text.
29
+ */
30
+ export declare function shapePrdPrompt(overview?: string, filename?: string, mode?: 'light' | 'detailed', prdsPath?: string): string;
31
+ export declare function architectPrdPrompt(filename: string, prdsPath?: string): string;
32
+ export declare function reviewStoryPrompt(filename: string, storyId: string, base?: string): string;
33
+ export declare function implementStoryPrompt(filename: string, storyId?: string, singleStory?: boolean): string;
34
+ /**
35
+ * What a plan is still missing, as items a UI can render as a checklist and an
36
+ * agent can act on. `required` items mean the plan is not ready to build;
37
+ * `recommended` items make it better but do not block.
38
+ */
39
+ interface PlanCheckItem {
40
+ /** Stable key, e.g. `stories` or `vague-stories`. */
41
+ id: string;
42
+ /** The PRD section to change, matching `update_prd_section` where possible. */
43
+ section: string;
44
+ message: string;
45
+ severity: 'required' | 'recommended';
46
+ /** Stories the item is about, when it is about specific stories. */
47
+ storyIds?: string[];
48
+ }
49
+ export declare function checkPlan(prd: StructuredPRD): {
50
+ ready_to_build: boolean;
51
+ items: PlanCheckItem[];
52
+ };
53
+ /**
54
+ * Starting points for new PRDs. A template fills sections the author would
55
+ * otherwise start empty, and gives `shape_prd` extra questions that matter for
56
+ * that kind of work. Everything it adds can be edited or removed afterwards.
57
+ */
58
+ interface PrdTemplate {
59
+ id: TemplateId;
60
+ name: string;
61
+ description: string;
62
+ /** Sentence an agent can use to pick the right template. */
63
+ whenToUse: string;
64
+ defaults: {
65
+ nonGoals?: string[];
66
+ outOfScope?: string[];
67
+ openQuestions?: string[];
68
+ globalAcceptanceCriteria?: string[];
69
+ qualityStandards?: string[];
70
+ technicalConstraints?: string[];
71
+ rolloutPhases?: string[];
72
+ rollbackConditions?: string[];
73
+ };
74
+ /** Extra questions for the shaping interview. */
75
+ interviewFocus: string[];
76
+ }
77
+ export declare const TEMPLATE_IDS: readonly ['saas-feature', 'internal-tool', 'integration', 'mvp'];
78
+ type TemplateId = (typeof TEMPLATE_IDS)[number];
79
+ export declare const PRD_TEMPLATES: readonly PrdTemplate[];
80
+ export declare function getTemplate(id: TemplateId): PrdTemplate;
81
+ 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 CriterionProof, CriterionProofSchema, 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, PrdCriticalitySchema, type PrdDeps, PrdRevisionConflictError, type PrdRoadmap, PrdRoadmapSchema, PrdRoadmapUpdateSchema, PrdSection, PrdSectionValueSchemas, PrdService, PrdSummary, PrdSummarySchema, type PrdTemplate, type PrdVerificationDiagnostic, type PrdVerificationResult, type ProofKind, ProofKindSchema, 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, appendChangeLog, appendStoryLog, assertCanEnterStatus, assignStoryToPhase, buildStoryContext, createPhase, createPrdService, deleteStory, findAttachment, findStory, incompleteDependencies, nextId, nextStoryId, normalizePrd, pickNextStory, recomputeProgress, renderUserStory, splitUserStory, updateStory, validateAttachmentIds, validateDependencies, validateProofs };