@makerkit/prd 0.0.0 → 0.0.1
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/package.json +2 -21
- package/.turbo/turbo-build.log +0 -46
- package/.turbo/turbo-test.log +0 -21
- package/.turbo/turbo-typecheck.log +0 -1
- package/dist/README.md +0 -65
- package/dist/package.json +0 -49
- package/src/__tests__/agent-workflow.test.ts +0 -377
- package/src/__tests__/attachments.test.ts +0 -475
- package/src/__tests__/node.test.ts +0 -141
- package/src/__tests__/plan-check.test.ts +0 -229
- package/src/__tests__/planning.test.ts +0 -1059
- package/src/__tests__/prd-operations.test.ts +0 -423
- package/src/__tests__/prd.service.test.ts +0 -477
- package/src/__tests__/prd.tool.test.ts +0 -282
- package/src/__tests__/templates.test.ts +0 -141
- package/src/applicability.ts +0 -73
- package/src/attachment-paths.ts +0 -78
- package/src/attachments.ts +0 -160
- package/src/edge-cases.ts +0 -52
- package/src/index.ts +0 -35
- package/src/markdown.ts +0 -268
- package/src/mcp/index.ts +0 -839
- package/src/mcp/tool-response.ts +0 -85
- package/src/node.ts +0 -146
- package/src/open-questions.ts +0 -93
- package/src/plan-check.ts +0 -282
- package/src/planning-operations.ts +0 -429
- package/src/prd-operations.ts +0 -690
- package/src/prd.service.ts +0 -1051
- package/src/prompts.ts +0 -110
- package/src/safe-file-name.ts +0 -42
- package/src/schema.ts +0 -976
- package/src/templates.ts +0 -173
- package/src/testing/fake-mcp-server.ts +0 -81
- package/src/types.ts +0 -333
- package/tsconfig.json +0 -23
- package/tsconfig.lib.json +0 -8
- package/tsconfig.spec.json +0 -7
- package/tsdown.config.mts +0 -11
- package/vitest.config.mts +0 -8
- /package/{dist/LICENSE → LICENSE} +0 -0
- /package/{dist/index.d.ts → index.d.ts} +0 -0
- /package/{dist/index.js → index.js} +0 -0
- /package/{dist/index.mjs → index.mjs} +0 -0
- /package/{dist/mcp.d.ts → mcp.d.ts} +0 -0
- /package/{dist/mcp.js → mcp.js} +0 -0
- /package/{dist/mcp.mjs → mcp.mjs} +0 -0
- /package/{dist/node.d.ts → node.d.ts} +0 -0
- /package/{dist/node.js → node.js} +0 -0
- /package/{dist/node.mjs → node.mjs} +0 -0
- /package/{dist/prd.service-DSBp8sMl.d.ts → prd.service-DSBp8sMl.d.ts} +0 -0
- /package/{dist/prompts-Bber0S1Z.mjs → prompts-Bber0S1Z.mjs} +0 -0
- /package/{dist/prompts-CIX8IeAx.js → prompts-CIX8IeAx.js} +0 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@makerkit/prd",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.1",
|
|
4
4
|
"description": "Structured PRDs as JSON files: the format, a service to manage them, and MCP tools so coding agents can read and update them.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai-agents",
|
|
@@ -34,29 +34,10 @@
|
|
|
34
34
|
"require": "./mcp.js"
|
|
35
35
|
}
|
|
36
36
|
},
|
|
37
|
-
"publishConfig": {
|
|
38
|
-
"access": "public",
|
|
39
|
-
"directory": "dist",
|
|
40
|
-
"linkDirectory": true
|
|
41
|
-
},
|
|
42
|
-
"scripts": {
|
|
43
|
-
"build": "tsdown && node ../../scripts/prepare-dist.mjs",
|
|
44
|
-
"typecheck": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.spec.json",
|
|
45
|
-
"test": "vitest run"
|
|
46
|
-
},
|
|
47
37
|
"dependencies": {
|
|
48
|
-
"@makerkit/repo-checks": "
|
|
38
|
+
"@makerkit/repo-checks": "^0.0.1",
|
|
49
39
|
"zod": "^3.25.0 || ^4.0.0"
|
|
50
40
|
},
|
|
51
|
-
"devDependencies": {
|
|
52
|
-
"@modelcontextprotocol/sdk": "catalog:",
|
|
53
|
-
"@types/node": "catalog:",
|
|
54
|
-
"tsdown": "catalog:",
|
|
55
|
-
"typescript": "catalog:",
|
|
56
|
-
"vite": "catalog:",
|
|
57
|
-
"vitest": "catalog:",
|
|
58
|
-
"zod": "catalog:"
|
|
59
|
-
},
|
|
60
41
|
"peerDependencies": {
|
|
61
42
|
"@modelcontextprotocol/sdk": "^1.32.0"
|
|
62
43
|
},
|
package/.turbo/turbo-build.log
DELETED
|
@@ -1,46 +0,0 @@
|
|
|
1
|
-
$ tsdown && node ../../scripts/prepare-dist.mjs
|
|
2
|
-
ℹ tsdown v0.23.0 powered by rolldown v1.2.13
|
|
3
|
-
ℹ config file: /Users/giancarlo/Code/makerkit/packages/prd/tsdown.config.mts
|
|
4
|
-
ℹ entry: src/index.ts, src/node.ts, src/mcp/index.ts
|
|
5
|
-
ℹ entry: src/index.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
|
-
ℹ [ESM] dist/index.mjs 57.30 kB │ gzip: 14.75 kB
|
|
11
|
-
ℹ [ESM] dist/mcp.mjs 21.44 kB │ gzip: 4.71 kB
|
|
12
|
-
ℹ [ESM] dist/node.mjs 2.79 kB │ gzip: 1.19 kB
|
|
13
|
-
ℹ [ESM] dist/prompts-D-8eu2qV.mjs 31.30 kB │ gzip: 9.07 kB
|
|
14
|
-
ℹ [ESM] 4 files, total: 112.84 kB
|
|
15
|
-
src/prd.service.ts (87:21) [33m[UNRESOLVED_IMPORT] [0mCould not resolve 'node:path' in src/prd.service.ts
|
|
16
|
-
[38;5;246m╭[0m[38;5;246m─[0m[38;5;246m[[0m src/prd.service.ts:87:22 [38;5;246m][0m
|
|
17
|
-
[38;5;246m│[0m
|
|
18
|
-
[38;5;246m87 │[0m [38;5;249mi[0m[38;5;249mm[0m[38;5;249mp[0m[38;5;249mo[0m[38;5;249mr[0m[38;5;249mt[0m[38;5;249m [0m[38;5;249m{[0m[38;5;249m [0m[38;5;249mj[0m[38;5;249mo[0m[38;5;249mi[0m[38;5;249mn[0m[38;5;249m [0m[38;5;249m}[0m[38;5;249m [0m[38;5;249mf[0m[38;5;249mr[0m[38;5;249mo[0m[38;5;249mm[0m[38;5;249m [0m'node:path'[38;5;249m;[0m
|
|
19
|
-
[38;5;240m │[0m ─────┬─────
|
|
20
|
-
[38;5;240m │[0m ╰─────── Module not found, treating it as an external dependency
|
|
21
|
-
[38;5;240m │[0m
|
|
22
|
-
[38;5;240m │[0m [38;5;115mHelp[0m: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
|
|
23
|
-
[38;5;246m────╯[0m
|
|
24
|
-
|
|
25
|
-
src/node.ts (12:7) [33m[UNRESOLVED_IMPORT] [0mCould not resolve 'node:fs/promises' in src/node.ts
|
|
26
|
-
[38;5;246m╭[0m[38;5;246m─[0m[38;5;246m[[0m src/node.ts:12:8 [38;5;246m][0m
|
|
27
|
-
[38;5;246m│[0m
|
|
28
|
-
[38;5;246m12 │[0m [38;5;249m}[0m[38;5;249m [0m[38;5;249mf[0m[38;5;249mr[0m[38;5;249mo[0m[38;5;249mm[0m[38;5;249m [0m'node:fs/promises'[38;5;249m;[0m
|
|
29
|
-
[38;5;240m │[0m ─────────┬────────
|
|
30
|
-
[38;5;240m │[0m ╰────────── Module not found, treating it as an external dependency
|
|
31
|
-
[38;5;240m │[0m
|
|
32
|
-
[38;5;240m │[0m [38;5;115mHelp[0m: The "main" field here was ignored. Main fields must be configured explicitly when using the "neutral" platform.
|
|
33
|
-
[38;5;246m────╯[0m
|
|
34
|
-
|
|
35
|
-
✔ Build complete in 472ms
|
|
36
|
-
ℹ [CJS] dist/index.js 59.60 kB │ gzip: 14.68 kB
|
|
37
|
-
ℹ [CJS] dist/mcp.js 21.14 kB │ gzip: 4.40 kB
|
|
38
|
-
ℹ [CJS] dist/node.js 3.04 kB │ gzip: 1.27 kB
|
|
39
|
-
ℹ [CJS] dist/prompts-DUS02Mwl.js 41.35 kB │ gzip: 9.39 kB
|
|
40
|
-
ℹ [CJS] 4 files, total: 125.15 kB
|
|
41
|
-
ℹ [CJS] dist/index.d.ts 14.49 kB │ gzip: 3.91 kB
|
|
42
|
-
ℹ [CJS] dist/node.d.ts 0.94 kB │ gzip: 0.51 kB
|
|
43
|
-
ℹ [CJS] dist/mcp.d.ts 0.42 kB │ gzip: 0.28 kB
|
|
44
|
-
ℹ [CJS] dist/prd.service-DoTF-akm.d.ts 61.23 kB │ gzip: 9.37 kB
|
|
45
|
-
ℹ [CJS] 4 files, total: 77.08 kB
|
|
46
|
-
✔ Build complete in 777ms
|
package/.turbo/turbo-test.log
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
$ vitest run
|
|
2
|
-
|
|
3
|
-
[1m[30m[46m RUN [49m[39m[22m [36mv5.0.4 [39m[90m/Users/giancarlo/Code/makerkit/packages/prd[39m
|
|
4
|
-
|
|
5
|
-
[32m✓[39m src/__tests__/templates.test.ts [2m([22m[2m4 tests[22m[2m)[22m[32m 10[2mms[22m[39m
|
|
6
|
-
[32m✓[39m src/__tests__/plan-check.test.ts [2m([22m[2m6 tests[22m[2m)[22m[32m 3[2mms[22m[39m
|
|
7
|
-
[32m✓[39m src/__tests__/prd-operations.test.ts [2m([22m[2m24 tests[22m[2m)[22m[32m 5[2mms[22m[39m
|
|
8
|
-
[32m✓[39m src/__tests__/prd.tool.test.ts [2m([22m[2m9 tests[22m[2m)[22m[32m 17[2mms[22m[39m
|
|
9
|
-
[32m✓[39m src/__tests__/attachments.test.ts [2m([22m[2m14 tests[22m[2m)[22m[32m 18[2mms[22m[39m
|
|
10
|
-
[32m✓[39m src/__tests__/agent-workflow.test.ts [2m([22m[2m12 tests[22m[2m)[22m[32m 21[2mms[22m[39m
|
|
11
|
-
[32m✓[39m src/__tests__/planning.test.ts [2m([22m[2m17 tests[22m[2m)[22m[32m 23[2mms[22m[39m
|
|
12
|
-
[32m✓[39m src/__tests__/prd.service.test.ts [2m([22m[2m18 tests[22m[2m)[22m[32m 16[2mms[22m[39m
|
|
13
|
-
[32m✓[39m src/__tests__/node.test.ts [2m([22m[2m6 tests[22m[2m)[22m[33m 941[2mms[22m[39m
|
|
14
|
-
[32m✓[39m createScriptVerifier [2m(4)[22m
|
|
15
|
-
[33m[2m✓[22m[39m passes when every defined check exits 0[33m 307[2mms[22m[39m
|
|
16
|
-
|
|
17
|
-
[2m Test Files [22m [1m[32m9 passed[39m[22m[90m (9)[39m
|
|
18
|
-
[2m Tests [22m [1m[32m110 passed[39m[22m[90m (110)[39m
|
|
19
|
-
[2m Start at [22m 23:31:27
|
|
20
|
-
[2m Duration [22m 1.15s[2m (tests 47%, transform 41%, import 10%, worker 2%)[22m
|
|
21
|
-
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
$ tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.spec.json
|
package/dist/README.md
DELETED
|
@@ -1,65 +0,0 @@
|
|
|
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; `implement_story` walks an agent through one story and its hand-off log. The same text is exported (`implementStoryPrompt`, `shapePrdPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
|
|
11
|
-
|
|
12
|
-
## Install
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
pnpm add @makerkit/prd
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
## Usage
|
|
19
|
-
|
|
20
|
-
```ts
|
|
21
|
-
import { createPrdService } from '@makerkit/prd';
|
|
22
|
-
import { createNodePrdDeps } from '@makerkit/prd/node';
|
|
23
|
-
|
|
24
|
-
const prds = createPrdService(createNodePrdDeps(process.cwd()));
|
|
25
|
-
|
|
26
|
-
const { prds: list } = await prds.list();
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
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:
|
|
30
|
-
|
|
31
|
-
```ts
|
|
32
|
-
createNodePrdDeps(root, {
|
|
33
|
-
verifyCompletion: async () => ({
|
|
34
|
-
passed: true,
|
|
35
|
-
checks: ['custom'],
|
|
36
|
-
errors: 0,
|
|
37
|
-
warnings: 0,
|
|
38
|
-
diagnostics: [],
|
|
39
|
-
messages: [],
|
|
40
|
-
}),
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### MCP
|
|
45
|
-
|
|
46
|
-
Requires `@modelcontextprotocol/sdk`.
|
|
47
|
-
|
|
48
|
-
```ts
|
|
49
|
-
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
50
|
-
import { createPrdService } from '@makerkit/prd';
|
|
51
|
-
import { registerPRDTools } from '@makerkit/prd/mcp';
|
|
52
|
-
import { createNodePrdDeps } from '@makerkit/prd/node';
|
|
53
|
-
|
|
54
|
-
const server = new McpServer({ name: 'prd', version: '1.0.0' });
|
|
55
|
-
|
|
56
|
-
registerPRDTools(server, createPrdService(createNodePrdDeps()));
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
## Credits
|
|
60
|
-
|
|
61
|
-
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.
|
|
62
|
-
|
|
63
|
-
## License
|
|
64
|
-
|
|
65
|
-
MIT
|
package/dist/package.json
DELETED
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@makerkit/prd",
|
|
3
|
-
"version": "0.0.0",
|
|
4
|
-
"description": "Structured PRDs as JSON files: the format, a service to manage them, and MCP tools so coding agents can read and update them.",
|
|
5
|
-
"keywords": [
|
|
6
|
-
"ai-agents",
|
|
7
|
-
"claude-code",
|
|
8
|
-
"codex",
|
|
9
|
-
"mcp",
|
|
10
|
-
"prd",
|
|
11
|
-
"product-requirements"
|
|
12
|
-
],
|
|
13
|
-
"license": "MIT",
|
|
14
|
-
"repository": {
|
|
15
|
-
"type": "git",
|
|
16
|
-
"url": "https://github.com/makerkit/makerkit",
|
|
17
|
-
"directory": "packages/prd"
|
|
18
|
-
},
|
|
19
|
-
"main": "./index.js",
|
|
20
|
-
"exports": {
|
|
21
|
-
".": {
|
|
22
|
-
"types": "./index.d.ts",
|
|
23
|
-
"import": "./index.mjs",
|
|
24
|
-
"require": "./index.js"
|
|
25
|
-
},
|
|
26
|
-
"./node": {
|
|
27
|
-
"types": "./node.d.ts",
|
|
28
|
-
"import": "./node.mjs",
|
|
29
|
-
"require": "./node.js"
|
|
30
|
-
},
|
|
31
|
-
"./mcp": {
|
|
32
|
-
"types": "./mcp.d.ts",
|
|
33
|
-
"import": "./mcp.mjs",
|
|
34
|
-
"require": "./mcp.js"
|
|
35
|
-
}
|
|
36
|
-
},
|
|
37
|
-
"dependencies": {
|
|
38
|
-
"@makerkit/repo-checks": "^0.0.0",
|
|
39
|
-
"zod": "^3.25.0 || ^4.0.0"
|
|
40
|
-
},
|
|
41
|
-
"peerDependencies": {
|
|
42
|
-
"@modelcontextprotocol/sdk": "^1.32.0"
|
|
43
|
-
},
|
|
44
|
-
"peerDependenciesMeta": {
|
|
45
|
-
"@modelcontextprotocol/sdk": {
|
|
46
|
-
"optional": true
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
}
|
|
@@ -1,377 +0,0 @@
|
|
|
1
|
-
import { describe, expect, it } from 'vitest';
|
|
2
|
-
|
|
3
|
-
import { registerPRDTools } from '../mcp';
|
|
4
|
-
import { type PrdDeps, createPrdService } from '../prd.service';
|
|
5
|
-
import { createFakeMcpServer } from '../testing/fake-mcp-server';
|
|
6
|
-
import type { StructuredPRD } from '../types';
|
|
7
|
-
|
|
8
|
-
const basename = (path: string) => path.replace(/\\/g, '/').split('/').pop()!;
|
|
9
|
-
|
|
10
|
-
function createDeps(files: Record<string, string>, hooks: Hooks = {}) {
|
|
11
|
-
return {
|
|
12
|
-
rootPath: '/repo',
|
|
13
|
-
async readdir() {
|
|
14
|
-
return Object.keys(files);
|
|
15
|
-
},
|
|
16
|
-
async readFile(path) {
|
|
17
|
-
const content = files[basename(path)];
|
|
18
|
-
|
|
19
|
-
if (content === undefined) {
|
|
20
|
-
throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
return content;
|
|
24
|
-
},
|
|
25
|
-
async writeFile(path, content) {
|
|
26
|
-
files[basename(path)] = content;
|
|
27
|
-
},
|
|
28
|
-
async mkdir() {},
|
|
29
|
-
async unlink(path) {
|
|
30
|
-
delete files[basename(path)];
|
|
31
|
-
},
|
|
32
|
-
async fileExists(path) {
|
|
33
|
-
hooks.beforeExists?.(basename(path));
|
|
34
|
-
return basename(path) in files;
|
|
35
|
-
},
|
|
36
|
-
now: () => new Date('2026-10-14T10:00:00Z'),
|
|
37
|
-
verifyCompletion: async () => ({
|
|
38
|
-
passed: true,
|
|
39
|
-
checks: ['typecheck'],
|
|
40
|
-
errors: 0,
|
|
41
|
-
warnings: 0,
|
|
42
|
-
diagnostics: [],
|
|
43
|
-
messages: [],
|
|
44
|
-
}),
|
|
45
|
-
} satisfies PrdDeps;
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
interface Hooks {
|
|
49
|
-
beforeExists?: (file: string) => void;
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
const STORY = {
|
|
53
|
-
userType: 'member',
|
|
54
|
-
benefit: 'it helps',
|
|
55
|
-
acceptanceCriteria: ['works'],
|
|
56
|
-
};
|
|
57
|
-
|
|
58
|
-
/** A PRD with US001 <- US002 (depends on US001) and an independent US003. */
|
|
59
|
-
async function seed(hooks: Hooks = {}) {
|
|
60
|
-
const files: Record<string, string> = {};
|
|
61
|
-
const service = createPrdService(createDeps(files, hooks));
|
|
62
|
-
|
|
63
|
-
const { filename } = await service.create({
|
|
64
|
-
title: 'Notes',
|
|
65
|
-
overview: 'Let members keep notes',
|
|
66
|
-
problemStatement: 'No place for context',
|
|
67
|
-
marketOpportunity: 'Retention',
|
|
68
|
-
targetUsers: ['Members'],
|
|
69
|
-
solutionDescription: 'Notes per account',
|
|
70
|
-
keyFeatures: ['Create note'],
|
|
71
|
-
successMetrics: ['Notes created'],
|
|
72
|
-
nonGoals: ['Rich text'],
|
|
73
|
-
});
|
|
74
|
-
|
|
75
|
-
await service.addUserStory({
|
|
76
|
-
...STORY,
|
|
77
|
-
filename,
|
|
78
|
-
action: 'create a note',
|
|
79
|
-
priority: 'P2',
|
|
80
|
-
});
|
|
81
|
-
await service.addUserStory({
|
|
82
|
-
...STORY,
|
|
83
|
-
filename,
|
|
84
|
-
action: 'share a note',
|
|
85
|
-
priority: 'P2',
|
|
86
|
-
});
|
|
87
|
-
await service.addUserStory({
|
|
88
|
-
...STORY,
|
|
89
|
-
filename,
|
|
90
|
-
action: 'pin a note',
|
|
91
|
-
priority: 'P1',
|
|
92
|
-
});
|
|
93
|
-
await service.updateUserStory({
|
|
94
|
-
filename,
|
|
95
|
-
storyId: 'US002',
|
|
96
|
-
dependencies: ['US001'],
|
|
97
|
-
});
|
|
98
|
-
|
|
99
|
-
const read = () => JSON.parse(files[filename]!) as StructuredPRD;
|
|
100
|
-
|
|
101
|
-
return { files, filename, service, read };
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
describe('story workflow', () => {
|
|
105
|
-
it('rejects starting a story before its dependencies are completed', async () => {
|
|
106
|
-
const { filename, service } = await seed();
|
|
107
|
-
|
|
108
|
-
await expect(
|
|
109
|
-
service.updateStoryStatus({
|
|
110
|
-
filename,
|
|
111
|
-
storyId: 'US002',
|
|
112
|
-
status: 'in_progress',
|
|
113
|
-
}),
|
|
114
|
-
).rejects.toThrow(/depends on US001/);
|
|
115
|
-
|
|
116
|
-
await expect(
|
|
117
|
-
service.updateStoryStatus({
|
|
118
|
-
filename,
|
|
119
|
-
storyId: 'US002',
|
|
120
|
-
status: 'completed',
|
|
121
|
-
}),
|
|
122
|
-
).rejects.toThrow(/depends on US001/);
|
|
123
|
-
});
|
|
124
|
-
|
|
125
|
-
it('still allows planning or parking a waiting story', async () => {
|
|
126
|
-
const { filename, service } = await seed();
|
|
127
|
-
|
|
128
|
-
await expect(
|
|
129
|
-
service.updateStoryStatus({
|
|
130
|
-
filename,
|
|
131
|
-
storyId: 'US002',
|
|
132
|
-
status: 'research',
|
|
133
|
-
}),
|
|
134
|
-
).resolves.toMatchObject({ status: 'research' });
|
|
135
|
-
|
|
136
|
-
await expect(
|
|
137
|
-
service.updateStoryStatus({
|
|
138
|
-
filename,
|
|
139
|
-
storyId: 'US002',
|
|
140
|
-
status: 'blocked',
|
|
141
|
-
}),
|
|
142
|
-
).resolves.toMatchObject({ status: 'blocked' });
|
|
143
|
-
});
|
|
144
|
-
|
|
145
|
-
it('allows the story once its dependencies are completed', async () => {
|
|
146
|
-
const { filename, service } = await seed();
|
|
147
|
-
|
|
148
|
-
await service.updateStoryStatus({
|
|
149
|
-
filename,
|
|
150
|
-
storyId: 'US001',
|
|
151
|
-
status: 'completed',
|
|
152
|
-
});
|
|
153
|
-
|
|
154
|
-
await expect(
|
|
155
|
-
service.updateStoryStatus({
|
|
156
|
-
filename,
|
|
157
|
-
storyId: 'US002',
|
|
158
|
-
status: 'in_progress',
|
|
159
|
-
}),
|
|
160
|
-
).resolves.toMatchObject({ status: 'in_progress' });
|
|
161
|
-
});
|
|
162
|
-
});
|
|
163
|
-
|
|
164
|
-
describe('getNextStory', () => {
|
|
165
|
-
it('prefers higher priority among ready stories and lists waiting ones', async () => {
|
|
166
|
-
const { filename, service } = await seed();
|
|
167
|
-
|
|
168
|
-
const next = await service.getNextStory(filename);
|
|
169
|
-
|
|
170
|
-
expect(next.story?.id).toBe('US003');
|
|
171
|
-
expect(next.ready_count).toBe(2);
|
|
172
|
-
expect(next.waiting).toEqual([
|
|
173
|
-
{ id: 'US002', title: expect.any(String), waiting_on: ['US001'] },
|
|
174
|
-
]);
|
|
175
|
-
});
|
|
176
|
-
|
|
177
|
-
it('orders by phase before priority', async () => {
|
|
178
|
-
const { filename, service } = await seed();
|
|
179
|
-
|
|
180
|
-
const { phase } = await service.createCustomPhase({
|
|
181
|
-
filename,
|
|
182
|
-
name: 'Milestone 1',
|
|
183
|
-
description: '',
|
|
184
|
-
color: '#4f46e5',
|
|
185
|
-
});
|
|
186
|
-
await service.assignStoryToPhase({
|
|
187
|
-
filename,
|
|
188
|
-
storyId: 'US001',
|
|
189
|
-
phaseId: phase.id,
|
|
190
|
-
});
|
|
191
|
-
|
|
192
|
-
const next = await service.getNextStory(filename);
|
|
193
|
-
|
|
194
|
-
expect(next.story?.id).toBe('US001');
|
|
195
|
-
});
|
|
196
|
-
|
|
197
|
-
it('returns null when nothing is ready', async () => {
|
|
198
|
-
const { filename, service } = await seed();
|
|
199
|
-
|
|
200
|
-
for (const storyId of ['US001', 'US003']) {
|
|
201
|
-
await service.updateStoryStatus({
|
|
202
|
-
filename,
|
|
203
|
-
storyId,
|
|
204
|
-
status: 'in_progress',
|
|
205
|
-
});
|
|
206
|
-
}
|
|
207
|
-
|
|
208
|
-
const next = await service.getNextStory(filename);
|
|
209
|
-
|
|
210
|
-
expect(next.story).toBeNull();
|
|
211
|
-
expect(next.in_progress).toEqual(['US001', 'US003']);
|
|
212
|
-
expect(next.waiting.map((entry) => entry.id)).toEqual(['US002']);
|
|
213
|
-
});
|
|
214
|
-
});
|
|
215
|
-
|
|
216
|
-
describe('story logs and context', () => {
|
|
217
|
-
it('appends hand-off logs and returns them in the dependent story context', async () => {
|
|
218
|
-
const { filename, service } = await seed();
|
|
219
|
-
|
|
220
|
-
await service.addStoryLog({
|
|
221
|
-
filename,
|
|
222
|
-
storyId: 'US001',
|
|
223
|
-
whatsNew: ['You can create a note from the sidebar'],
|
|
224
|
-
technicalNotes: ['Notes table has RLS by account_id'],
|
|
225
|
-
});
|
|
226
|
-
await service.updateStoryStatus({
|
|
227
|
-
filename,
|
|
228
|
-
storyId: 'US001',
|
|
229
|
-
status: 'completed',
|
|
230
|
-
});
|
|
231
|
-
|
|
232
|
-
const context = await service.getStory({ filename, storyId: 'US002' });
|
|
233
|
-
|
|
234
|
-
expect(context.prd.non_goals).toEqual(['Rich text']);
|
|
235
|
-
expect(context.dependencies).toEqual([
|
|
236
|
-
{
|
|
237
|
-
id: 'US001',
|
|
238
|
-
title: expect.any(String),
|
|
239
|
-
status: 'completed',
|
|
240
|
-
log: [
|
|
241
|
-
{
|
|
242
|
-
at: '2026-10-14T10:00:00.000Z',
|
|
243
|
-
whatsNew: ['You can create a note from the sidebar'],
|
|
244
|
-
technicalNotes: ['Notes table has RLS by account_id'],
|
|
245
|
-
},
|
|
246
|
-
],
|
|
247
|
-
},
|
|
248
|
-
]);
|
|
249
|
-
expect(context.previous_story?.id).toBe('US001');
|
|
250
|
-
});
|
|
251
|
-
|
|
252
|
-
it('stores deviations only when there are some', async () => {
|
|
253
|
-
const { filename, service, read } = await seed();
|
|
254
|
-
|
|
255
|
-
await service.addStoryLog({
|
|
256
|
-
filename,
|
|
257
|
-
storyId: 'US001',
|
|
258
|
-
whatsNew: ['a'],
|
|
259
|
-
technicalNotes: [],
|
|
260
|
-
deviations: ['Used a modal instead of a page: the sidebar has no room'],
|
|
261
|
-
});
|
|
262
|
-
await service.addStoryLog({
|
|
263
|
-
filename,
|
|
264
|
-
storyId: 'US001',
|
|
265
|
-
whatsNew: ['b'],
|
|
266
|
-
technicalNotes: [],
|
|
267
|
-
deviations: [],
|
|
268
|
-
});
|
|
269
|
-
|
|
270
|
-
const log = read().userStories.find((story) => story.id === 'US001')!.log!;
|
|
271
|
-
|
|
272
|
-
expect(log[0]!.deviations).toEqual([
|
|
273
|
-
'Used a modal instead of a page: the sidebar has no room',
|
|
274
|
-
]);
|
|
275
|
-
expect(log[1]).not.toHaveProperty('deviations');
|
|
276
|
-
});
|
|
277
|
-
|
|
278
|
-
it('keeps earlier log entries', async () => {
|
|
279
|
-
const { filename, service } = await seed();
|
|
280
|
-
|
|
281
|
-
await service.addStoryLog({
|
|
282
|
-
filename,
|
|
283
|
-
storyId: 'US001',
|
|
284
|
-
whatsNew: ['a'],
|
|
285
|
-
technicalNotes: [],
|
|
286
|
-
});
|
|
287
|
-
const result = await service.addStoryLog({
|
|
288
|
-
filename,
|
|
289
|
-
storyId: 'US001',
|
|
290
|
-
whatsNew: ['b'],
|
|
291
|
-
technicalNotes: [],
|
|
292
|
-
});
|
|
293
|
-
|
|
294
|
-
expect(result.entries).toBe(2);
|
|
295
|
-
});
|
|
296
|
-
});
|
|
297
|
-
|
|
298
|
-
describe('revision check', () => {
|
|
299
|
-
it('increments the revision on every write', async () => {
|
|
300
|
-
const { read } = await seed();
|
|
301
|
-
|
|
302
|
-
// create + 3 stories + 1 update
|
|
303
|
-
expect(read().metadata.revision).toBe(4);
|
|
304
|
-
});
|
|
305
|
-
|
|
306
|
-
it('rejects a write when the file changed after it was read', async () => {
|
|
307
|
-
let interfere = false;
|
|
308
|
-
const hooks: Hooks = {};
|
|
309
|
-
const { filename, service, files, read } = await seed(hooks);
|
|
310
|
-
|
|
311
|
-
hooks.beforeExists = (file) => {
|
|
312
|
-
if (!interfere) return;
|
|
313
|
-
interfere = false;
|
|
314
|
-
|
|
315
|
-
// Another writer saves between our read and our write.
|
|
316
|
-
const other = JSON.parse(files[file]!) as StructuredPRD;
|
|
317
|
-
other.metadata.revision = (other.metadata.revision ?? 0) + 1;
|
|
318
|
-
other.introduction.overview = 'Changed elsewhere';
|
|
319
|
-
files[file] = JSON.stringify(other);
|
|
320
|
-
};
|
|
321
|
-
|
|
322
|
-
interfere = true;
|
|
323
|
-
|
|
324
|
-
await expect(
|
|
325
|
-
service.addStoryLog({
|
|
326
|
-
filename,
|
|
327
|
-
storyId: 'US001',
|
|
328
|
-
whatsNew: ['x'],
|
|
329
|
-
technicalNotes: [],
|
|
330
|
-
}),
|
|
331
|
-
).rejects.toThrow(/changed by someone else/);
|
|
332
|
-
|
|
333
|
-
expect(read().introduction.overview).toBe('Changed elsewhere');
|
|
334
|
-
expect(read().userStories[0]?.log).toBeUndefined();
|
|
335
|
-
});
|
|
336
|
-
});
|
|
337
|
-
|
|
338
|
-
describe('MCP registration', () => {
|
|
339
|
-
it('registers the workflow tools and the implement_story prompt', async () => {
|
|
340
|
-
const fake = createFakeMcpServer();
|
|
341
|
-
const { files, filename } = await seed();
|
|
342
|
-
|
|
343
|
-
registerPRDTools(fake.server, createPrdService(createDeps(files)));
|
|
344
|
-
|
|
345
|
-
const next = await fake.call('get_next_story', { filename });
|
|
346
|
-
expect(next.structuredContent).toMatchObject({ story: { id: 'US003' } });
|
|
347
|
-
|
|
348
|
-
await fake.call('get_story', { filename, storyId: 'US002' });
|
|
349
|
-
await fake.call('add_story_log', {
|
|
350
|
-
filename,
|
|
351
|
-
storyId: 'US001',
|
|
352
|
-
whatsNew: ['x'],
|
|
353
|
-
});
|
|
354
|
-
|
|
355
|
-
const prompt = fake.prompts.find(
|
|
356
|
-
(entry) => entry.name === 'implement_story',
|
|
357
|
-
);
|
|
358
|
-
const text = prompt!.handler({ filename }).messages[0]!.content.text;
|
|
359
|
-
|
|
360
|
-
expect(text).toContain('get_next_story');
|
|
361
|
-
expect(text).toContain('add_story_log');
|
|
362
|
-
expect(text).toContain('deviations');
|
|
363
|
-
expect(text).not.toContain('run_checks');
|
|
364
|
-
|
|
365
|
-
const review = fake.prompts.find((entry) => entry.name === 'review_story');
|
|
366
|
-
const reviewText = review!.handler({
|
|
367
|
-
filename,
|
|
368
|
-
storyId: 'US001',
|
|
369
|
-
base: 'main',
|
|
370
|
-
}).messages[0]!.content.text;
|
|
371
|
-
|
|
372
|
-
expect(reviewText).toContain('git diff main');
|
|
373
|
-
expect(reviewText).toContain('get_story');
|
|
374
|
-
expect(reviewText).toMatch(/Do not change the story status/);
|
|
375
|
-
expect(reviewText).toContain('deviations');
|
|
376
|
-
});
|
|
377
|
-
});
|