mstro-app 0.3.7 → 0.3.9

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 (131) hide show
  1. package/README.md +4 -8
  2. package/bin/mstro.js +54 -15
  3. package/dist/server/cli/headless/claude-invoker.d.ts.map +1 -1
  4. package/dist/server/cli/headless/claude-invoker.js +18 -9
  5. package/dist/server/cli/headless/claude-invoker.js.map +1 -1
  6. package/dist/server/cli/headless/headless-logger.d.ts +10 -0
  7. package/dist/server/cli/headless/headless-logger.d.ts.map +1 -0
  8. package/dist/server/cli/headless/headless-logger.js +66 -0
  9. package/dist/server/cli/headless/headless-logger.js.map +1 -0
  10. package/dist/server/cli/headless/mcp-config.d.ts.map +1 -1
  11. package/dist/server/cli/headless/mcp-config.js +6 -5
  12. package/dist/server/cli/headless/mcp-config.js.map +1 -1
  13. package/dist/server/cli/headless/runner.d.ts.map +1 -1
  14. package/dist/server/cli/headless/runner.js +4 -0
  15. package/dist/server/cli/headless/runner.js.map +1 -1
  16. package/dist/server/cli/headless/stall-assessor.d.ts +21 -0
  17. package/dist/server/cli/headless/stall-assessor.d.ts.map +1 -1
  18. package/dist/server/cli/headless/stall-assessor.js +74 -20
  19. package/dist/server/cli/headless/stall-assessor.js.map +1 -1
  20. package/dist/server/cli/headless/tool-watchdog.d.ts +0 -12
  21. package/dist/server/cli/headless/tool-watchdog.d.ts.map +1 -1
  22. package/dist/server/cli/headless/tool-watchdog.js +30 -9
  23. package/dist/server/cli/headless/tool-watchdog.js.map +1 -1
  24. package/dist/server/cli/headless/types.d.ts +8 -1
  25. package/dist/server/cli/headless/types.d.ts.map +1 -1
  26. package/dist/server/cli/improvisation-session-manager.d.ts +16 -0
  27. package/dist/server/cli/improvisation-session-manager.d.ts.map +1 -1
  28. package/dist/server/cli/improvisation-session-manager.js +94 -11
  29. package/dist/server/cli/improvisation-session-manager.js.map +1 -1
  30. package/dist/server/index.js +0 -4
  31. package/dist/server/index.js.map +1 -1
  32. package/dist/server/mcp/bouncer-cli.d.ts +3 -0
  33. package/dist/server/mcp/bouncer-cli.d.ts.map +1 -0
  34. package/dist/server/mcp/bouncer-cli.js +54 -0
  35. package/dist/server/mcp/bouncer-cli.js.map +1 -0
  36. package/dist/server/mcp/bouncer-integration.d.ts +2 -0
  37. package/dist/server/mcp/bouncer-integration.d.ts.map +1 -1
  38. package/dist/server/mcp/bouncer-integration.js +55 -39
  39. package/dist/server/mcp/bouncer-integration.js.map +1 -1
  40. package/dist/server/mcp/bouncer-sandbox.d.ts +60 -0
  41. package/dist/server/mcp/bouncer-sandbox.d.ts.map +1 -0
  42. package/dist/server/mcp/bouncer-sandbox.js +182 -0
  43. package/dist/server/mcp/bouncer-sandbox.js.map +1 -0
  44. package/dist/server/mcp/security-patterns.d.ts +6 -12
  45. package/dist/server/mcp/security-patterns.d.ts.map +1 -1
  46. package/dist/server/mcp/security-patterns.js +197 -10
  47. package/dist/server/mcp/security-patterns.js.map +1 -1
  48. package/dist/server/services/plan/composer.d.ts +4 -0
  49. package/dist/server/services/plan/composer.d.ts.map +1 -0
  50. package/dist/server/services/plan/composer.js +181 -0
  51. package/dist/server/services/plan/composer.js.map +1 -0
  52. package/dist/server/services/plan/dependency-resolver.d.ts +28 -0
  53. package/dist/server/services/plan/dependency-resolver.d.ts.map +1 -0
  54. package/dist/server/services/plan/dependency-resolver.js +152 -0
  55. package/dist/server/services/plan/dependency-resolver.js.map +1 -0
  56. package/dist/server/services/plan/executor.d.ts +91 -0
  57. package/dist/server/services/plan/executor.d.ts.map +1 -0
  58. package/dist/server/services/plan/executor.js +545 -0
  59. package/dist/server/services/plan/executor.js.map +1 -0
  60. package/dist/server/services/plan/parser.d.ts +11 -0
  61. package/dist/server/services/plan/parser.d.ts.map +1 -0
  62. package/dist/server/services/plan/parser.js +415 -0
  63. package/dist/server/services/plan/parser.js.map +1 -0
  64. package/dist/server/services/plan/state-reconciler.d.ts +2 -0
  65. package/dist/server/services/plan/state-reconciler.d.ts.map +1 -0
  66. package/dist/server/services/plan/state-reconciler.js +105 -0
  67. package/dist/server/services/plan/state-reconciler.js.map +1 -0
  68. package/dist/server/services/plan/types.d.ts +120 -0
  69. package/dist/server/services/plan/types.d.ts.map +1 -0
  70. package/dist/server/services/plan/types.js +4 -0
  71. package/dist/server/services/plan/types.js.map +1 -0
  72. package/dist/server/services/plan/watcher.d.ts +14 -0
  73. package/dist/server/services/plan/watcher.d.ts.map +1 -0
  74. package/dist/server/services/plan/watcher.js +69 -0
  75. package/dist/server/services/plan/watcher.js.map +1 -0
  76. package/dist/server/services/websocket/file-explorer-handlers.js +20 -0
  77. package/dist/server/services/websocket/file-explorer-handlers.js.map +1 -1
  78. package/dist/server/services/websocket/handler.d.ts +0 -1
  79. package/dist/server/services/websocket/handler.d.ts.map +1 -1
  80. package/dist/server/services/websocket/handler.js +28 -2
  81. package/dist/server/services/websocket/handler.js.map +1 -1
  82. package/dist/server/services/websocket/plan-handlers.d.ts +6 -0
  83. package/dist/server/services/websocket/plan-handlers.d.ts.map +1 -0
  84. package/dist/server/services/websocket/plan-handlers.js +494 -0
  85. package/dist/server/services/websocket/plan-handlers.js.map +1 -0
  86. package/dist/server/services/websocket/quality-handlers.d.ts +4 -0
  87. package/dist/server/services/websocket/quality-handlers.d.ts.map +1 -0
  88. package/dist/server/services/websocket/quality-handlers.js +470 -0
  89. package/dist/server/services/websocket/quality-handlers.js.map +1 -0
  90. package/dist/server/services/websocket/quality-persistence.d.ts +45 -0
  91. package/dist/server/services/websocket/quality-persistence.d.ts.map +1 -0
  92. package/dist/server/services/websocket/quality-persistence.js +187 -0
  93. package/dist/server/services/websocket/quality-persistence.js.map +1 -0
  94. package/dist/server/services/websocket/quality-service.d.ts +54 -0
  95. package/dist/server/services/websocket/quality-service.d.ts.map +1 -0
  96. package/dist/server/services/websocket/quality-service.js +816 -0
  97. package/dist/server/services/websocket/quality-service.js.map +1 -0
  98. package/dist/server/services/websocket/session-handlers.d.ts.map +1 -1
  99. package/dist/server/services/websocket/session-handlers.js +23 -0
  100. package/dist/server/services/websocket/session-handlers.js.map +1 -1
  101. package/dist/server/services/websocket/types.d.ts +2 -2
  102. package/dist/server/services/websocket/types.d.ts.map +1 -1
  103. package/package.json +3 -2
  104. package/server/cli/headless/claude-invoker.ts +21 -9
  105. package/server/cli/headless/headless-logger.ts +78 -0
  106. package/server/cli/headless/mcp-config.ts +6 -5
  107. package/server/cli/headless/runner.ts +4 -0
  108. package/server/cli/headless/stall-assessor.ts +101 -20
  109. package/server/cli/headless/tool-watchdog.ts +18 -9
  110. package/server/cli/headless/types.ts +10 -1
  111. package/server/cli/improvisation-session-manager.ts +118 -11
  112. package/server/index.ts +0 -4
  113. package/server/mcp/bouncer-cli.ts +73 -0
  114. package/server/mcp/bouncer-integration.ts +66 -44
  115. package/server/mcp/bouncer-sandbox.ts +214 -0
  116. package/server/mcp/security-patterns.ts +206 -10
  117. package/server/services/plan/composer.ts +199 -0
  118. package/server/services/plan/dependency-resolver.ts +179 -0
  119. package/server/services/plan/executor.ts +604 -0
  120. package/server/services/plan/parser.ts +459 -0
  121. package/server/services/plan/state-reconciler.ts +132 -0
  122. package/server/services/plan/types.ts +164 -0
  123. package/server/services/plan/watcher.ts +73 -0
  124. package/server/services/websocket/file-explorer-handlers.ts +20 -0
  125. package/server/services/websocket/handler.ts +28 -2
  126. package/server/services/websocket/plan-handlers.ts +592 -0
  127. package/server/services/websocket/quality-handlers.ts +570 -0
  128. package/server/services/websocket/quality-persistence.ts +250 -0
  129. package/server/services/websocket/quality-service.ts +975 -0
  130. package/server/services/websocket/session-handlers.ts +26 -0
  131. package/server/services/websocket/types.ts +62 -2
@@ -14,6 +14,8 @@
14
14
  * - The question is: "Does this operation make sense given user intent?"
15
15
  */
16
16
 
17
+ import { resolve } from 'node:path';
18
+
17
19
  export interface SecurityPattern {
18
20
  pattern: RegExp;
19
21
  reason?: string;
@@ -83,7 +85,16 @@ export const CRITICAL_THREATS: SecurityPattern[] = [
83
85
  {
84
86
  pattern: /chmod\s+000\s+\//i,
85
87
  reason: 'Attempting to make system directories inaccessible'
86
- }
88
+ },
89
+ // Reverse shells - never legitimate in a dev workflow
90
+ {
91
+ pattern: /\/dev\/tcp\//i,
92
+ reason: 'Reverse shell via /dev/tcp - classic backdoor technique'
93
+ },
94
+ {
95
+ pattern: /\bnc\b.*-[elp].*\b\d+\b/i,
96
+ reason: 'Netcat listener/reverse shell - common backdoor technique'
97
+ },
87
98
  // NOTE: curl|bash is NOT here - it goes to Haiku for context review
88
99
  // The question is "did a bad actor inject this?" not "is curl|bash dangerous?"
89
100
  ];
@@ -158,12 +169,104 @@ export const NEEDS_AI_REVIEW: SecurityPattern[] = [
158
169
  reason: 'Recursive deletion - verify target matches user intent'
159
170
  },
160
171
 
172
+ // Data exfiltration patterns — piping data to network tools
173
+ {
174
+ pattern: /\|\s*(nc|netcat|ncat)\b/i,
175
+ reason: 'Pipe to netcat - potential data exfiltration'
176
+ },
177
+ {
178
+ pattern: /\bscp\b.*@/i,
179
+ reason: 'SCP to remote host - potential data exfiltration'
180
+ },
181
+ {
182
+ pattern: /\|\s*curl\b/i,
183
+ reason: 'Pipe to curl - potential data exfiltration'
184
+ },
185
+ {
186
+ pattern: /curl\b.*-d\s*@/i,
187
+ reason: 'Curl with file upload - potential data exfiltration'
188
+ },
189
+
161
190
  // ALL Write/Edit operations that aren't to /tmp go through context review
162
191
  // This is the key change: we review based on context, not blanket allow/deny
163
192
  {
164
193
  pattern: /^(Write|Edit):\s*(?!\/tmp\/|\/var\/tmp\/)/i,
165
194
  reason: 'File modification - verify aligns with user request'
166
195
  },
196
+
197
+ // Reverse shells and bind shells — network-connected interactive shells
198
+ {
199
+ pattern: /\/dev\/tcp\//i,
200
+ reason: 'Potential reverse shell via /dev/tcp'
201
+ },
202
+ {
203
+ pattern: /\b(nc|netcat|ncat)\b.*-e\s/i,
204
+ reason: 'Netcat with -e flag - potential reverse shell'
205
+ },
206
+ {
207
+ pattern: /\bsocket\b.*\bconnect\b.*\b(dup2|subprocess|exec)\b/i,
208
+ reason: 'Programmatic reverse shell pattern (socket+connect+exec)'
209
+ },
210
+ {
211
+ pattern: /\bperl\b.*\bsocket\b.*\bexec\b/i,
212
+ reason: 'Perl reverse shell pattern'
213
+ },
214
+
215
+ // Encoded/obfuscated payloads piped to shell or eval
216
+ {
217
+ pattern: /\b(base64|base32)\b.*-d.*\|\s*(bash|sh)\b/i,
218
+ reason: 'Decoded payload piped to shell - obfuscated command execution'
219
+ },
220
+ {
221
+ pattern: /\\x[0-9a-f]{2}.*\|\s*(bash|sh)\b/i,
222
+ reason: 'Hex-encoded payload piped to shell'
223
+ },
224
+ {
225
+ pattern: /\bexec\b.*\b(base64|b64decode)\b/i,
226
+ reason: 'Exec with base64 decoding - obfuscated code execution'
227
+ },
228
+ {
229
+ pattern: /\bprintf\b.*\\x[0-9a-f].*\|\s*(bash|sh)\b/i,
230
+ reason: 'Printf hex payload piped to shell'
231
+ },
232
+
233
+ // Cloud metadata / SSRF — accessing cloud instance credentials
234
+ {
235
+ pattern: /169\.254\.169\.254/i,
236
+ reason: 'AWS/Azure IMDS access - potential credential theft'
237
+ },
238
+ {
239
+ pattern: /metadata\.google\.internal/i,
240
+ reason: 'GCP metadata access - potential credential theft'
241
+ },
242
+
243
+ // Persistence — writing to shell profiles, cron, authorized_keys via echo/append
244
+ {
245
+ pattern: />>\s*~?\/?.*\/(authorized_keys|\.bashrc|\.bash_profile|\.zshrc|\.profile)/i,
246
+ reason: 'Appending to sensitive file - potential persistence mechanism'
247
+ },
248
+ {
249
+ pattern: /\bld\.so\.preload\b/i,
250
+ reason: 'LD_PRELOAD injection - shared library hijacking'
251
+ },
252
+
253
+ // wget with file upload
254
+ {
255
+ pattern: /wget\b.*--post-file/i,
256
+ reason: 'wget file upload - potential data exfiltration'
257
+ },
258
+
259
+ // pip install from custom index (supply chain attack)
260
+ {
261
+ pattern: /pip\b.*--index-url\s+https?:\/\/(?!pypi\.org)/i,
262
+ reason: 'pip install from non-PyPI index - potential supply chain attack'
263
+ },
264
+
265
+ // MCP server manipulation
266
+ {
267
+ pattern: /\bclaude\b.*\bmcp\b.*\badd\b/i,
268
+ reason: 'Adding MCP server - verify source is trusted'
269
+ },
167
270
  ];
168
271
 
169
272
  /**
@@ -178,11 +281,70 @@ export function matchesPattern(operation: string, patterns: SecurityPattern[]):
178
281
  return null;
179
282
  }
180
283
 
284
+ /**
285
+ * Normalize file paths in Write/Edit/Read operations to resolve .. traversal.
286
+ * Prevents path traversal attacks like "Write: /home/user/../../etc/passwd"
287
+ * from matching safe home-directory patterns.
288
+ */
289
+ export function normalizeOperation(operation: string): string {
290
+ const match = operation.match(/^(Write|Edit|Read):\s*(\S+)/i);
291
+ if (match?.[2].includes('..')) {
292
+ const [, tool, rawPath] = match;
293
+ const normalizedPath = resolve(rawPath);
294
+ return `${tool}: ${normalizedPath}`;
295
+ }
296
+ return operation;
297
+ }
298
+
299
+ /** Check if a Bash command contains chain operators that could hide dangerous ops after a safe prefix. */
300
+ function containsChainOperators(operation: string): boolean {
301
+ const commandPart = operation.replace(/^Bash:\s*/i, '');
302
+ return /;|&&|\|\||\n/.test(commandPart);
303
+ }
304
+
305
+ /** Check if a Bash command pipes output to known exfiltration/network tools or shells. */
306
+ function containsDangerousPipe(operation: string): boolean {
307
+ const commandPart = operation.replace(/^Bash:\s*/i, '');
308
+ return /\|\s*(nc|netcat|ncat|curl|wget|scp|bash|sh)\b/i.test(commandPart);
309
+ }
310
+
311
+ /** Check if a Bash command redirects output to sensitive paths (append or overwrite). */
312
+ function containsSensitiveRedirect(operation: string): boolean {
313
+ const commandPart = operation.replace(/^Bash:\s*/i, '');
314
+ return />>?\s*~?\/?.*\/(authorized_keys|\.bashrc|\.bash_profile|\.zshrc|\.profile|\.ssh\/|\.aws\/|\.gnupg\/|ld\.so\.preload|crontab|sudoers)/i.test(commandPart)
315
+ || />>?\s*\/etc\//i.test(commandPart);
316
+ }
317
+
318
+ /** Check if a Bash command contains subshell or backtick expansion (not simple ${VAR}). */
319
+ function containsBashExpansion(operation: string): boolean {
320
+ const commandPart = operation.replace(/^Bash:\s*/i, '');
321
+ return /`[^`]+`/.test(commandPart) || /\$\([^)]+\)/.test(commandPart);
322
+ }
323
+
324
+ /** Check if a Bash command contains any form of shell expansion: ${VAR}, $(...), or backticks. */
325
+ function containsAnyExpansion(operation: string): boolean {
326
+ const cmd = operation.replace(/^Bash:\s*/i, '');
327
+ return /\$\{[^}]+\}/.test(cmd) || /\$\([^)]+\)/.test(cmd) || /`[^`]+`/.test(cmd);
328
+ }
329
+
330
+ /** Check if expansion is safely used as an argument to a known-safe command prefix.
331
+ * e.g., "echo ${HOME}" or "cat ${FILE}" — the expansion can't change the command itself. */
332
+ function isSafeExpansionUse(operation: string): boolean {
333
+ const cmd = operation.replace(/^Bash:\s*/i, '').trim();
334
+ // If the expansion IS the command (first token), it's never safe
335
+ if (/^(\$\{|\$\(|`)/.test(cmd)) return false;
336
+ // Safe command prefixes where expansion as an argument is harmless
337
+ const safePrefix = /^(echo|printf|cat|ls|pwd|whoami|date|env|printenv|test|true|false)\s/i;
338
+ return safePrefix.test(cmd);
339
+ }
340
+
181
341
  /**
182
342
  * Determine if operation requires AI context review
183
343
  *
184
344
  * The philosophy here is:
185
- * - SAFE_OPERATIONS: No review needed (read-only, temp files, build artifact cleanup)
345
+ * - SENSITIVE_PATHS: Always require review (credentials, system configs)
346
+ * - SAFE_OPERATIONS: No review needed, UNLESS the bash command contains
347
+ * chain operators, dangerous pipes, or subshell/backtick expansion
186
348
  * - CRITICAL_THREATS: Auto-deny, no review (catastrophic operations)
187
349
  * - Everything else: AI reviews context to determine if it matches user intent
188
350
  */
@@ -197,17 +359,48 @@ const SAFE_RM_PATTERNS = [
197
359
  ];
198
360
 
199
361
  export function requiresAIReview(operation: string): boolean {
200
- if (matchesPattern(operation, SAFE_OPERATIONS)) return false;
201
- if (matchesPattern(operation, CRITICAL_THREATS)) return false;
362
+ // Normalize paths to prevent .. traversal bypass
363
+ const op = normalizeOperation(operation);
364
+
365
+ // Check sensitive paths BEFORE safe operations — prevents home-dir
366
+ // safe pattern from masking .ssh, .aws, .bashrc, etc.
367
+ if (matchesPattern(op, SENSITIVE_PATHS)) return true;
368
+
369
+ // Bash commands with any shell expansion (${VAR}, $(...), backticks) are
370
+ // opaque — the bouncer can't predict what they expand to at runtime.
371
+ // Route to AI review BEFORE checking CRITICAL_THREATS or SAFE_OPERATIONS,
372
+ // UNLESS the command is clearly safe (expansion is just an argument to a
373
+ // known-safe prefix like "echo ${HOME}").
374
+ if (/^Bash:/i.test(op) && containsAnyExpansion(op) && !isSafeExpansionUse(op)) {
375
+ return true;
376
+ }
377
+
378
+ if (matchesPattern(op, SAFE_OPERATIONS)) {
379
+ // Safe bash commands must not contain chain operators, dangerous pipes,
380
+ // or subshell/backtick expansion that could hide dangerous operations.
381
+ // A safe prefix (e.g., "git clone") with chain operators (&&, ;, ||)
382
+ // means the full command isn't necessarily safe — route to AI review.
383
+ if (/^Bash:/i.test(op) && (
384
+ containsChainOperators(op) ||
385
+ containsDangerousPipe(op) ||
386
+ containsBashExpansion(op) ||
387
+ containsSensitiveRedirect(op)
388
+ )) {
389
+ return true;
390
+ }
391
+ return false;
392
+ }
393
+
394
+ if (matchesPattern(op, CRITICAL_THREATS)) return false;
202
395
 
203
- if (matchesPattern(operation, NEEDS_AI_REVIEW)) {
204
- return !SAFE_RM_PATTERNS.some(p => p.test(operation));
396
+ if (matchesPattern(op, NEEDS_AI_REVIEW)) {
397
+ return !SAFE_RM_PATTERNS.some(p => p.test(op));
205
398
  }
206
399
 
207
- // Variable expansion and glob patterns are only concerning in Bash commands
208
- if (/^Bash:/.test(operation)) {
209
- if (/\$\{.*\}|\$\(.*\)/.test(operation) || /\*\*?/.test(operation)) return true;
210
- if (/^Bash:\s*\.\//.test(operation)) return true;
400
+ // Glob patterns and script execution are concerning in Bash commands
401
+ if (/^Bash:/.test(op)) {
402
+ if (/\*\*?/.test(op)) return true;
403
+ if (/^Bash:\s*\.\//.test(op)) return true;
211
404
  }
212
405
 
213
406
  return false;
@@ -262,6 +455,9 @@ export function classifyRisk(operation: string): {
262
455
  { pattern: /chmod\s+777/i, reason: 'Dangerous permissions' },
263
456
  { pattern: /(curl|wget).*\|.*(bash|sh)/i, reason: 'Remote code execution' },
264
457
  { pattern: /pkill|killall/i, reason: 'Process termination' },
458
+ { pattern: /\|\s*(nc|netcat|ncat)\b/i, reason: 'Data exfiltration via netcat' },
459
+ { pattern: /\bscp\b.*@/i, reason: 'Data exfiltration via SCP' },
460
+ { pattern: /curl\b.*-d\s*@/i, reason: 'Data exfiltration via curl file upload' },
265
461
  ];
266
462
 
267
463
  for (const pattern of elevatedPatterns) {
@@ -0,0 +1,199 @@
1
+ // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
2
+ // Licensed under the MIT License. See LICENSE file for details.
3
+
4
+ /**
5
+ * Plan Composer — Handles natural language prompts for PPS creation/editing.
6
+ *
7
+ * When a planPrompt message arrives, this builds a context-enriched prompt
8
+ * against the .pm/ (or legacy .plan/) directory and spawns a scoped
9
+ * HeadlessRunner session to execute it.
10
+ */
11
+
12
+ import { existsSync, readFileSync } from 'node:fs';
13
+ import { join } from 'node:path';
14
+ import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
15
+ import { HeadlessRunner, type ToolUseEvent } from '../../cli/headless/index.js';
16
+ import type { HandlerContext } from '../websocket/handler-context.js';
17
+ import type { WSContext } from '../websocket/types.js';
18
+ import { getNextId, parsePlanDirectory, resolvePmDir } from './parser.js';
19
+
20
+ const PROMPT_TOOL_MESSAGES: Record<string, string> = {
21
+ Glob: 'Discovering project files...',
22
+ Read: 'Reading project structure...',
23
+ Grep: 'Searching codebase...',
24
+ Write: 'Creating project files...',
25
+ Edit: 'Updating project files...',
26
+ Bash: 'Running commands...',
27
+ };
28
+
29
+ function getPromptToolCompleteMessage(event: ToolUseEvent): string | null {
30
+ const input = event.completeInput;
31
+ if (!input) return null;
32
+ if (event.toolName === 'Write' && input.file_path) {
33
+ const filename = String(input.file_path).split('/').pop() ?? '';
34
+ return `Created ${filename}`;
35
+ }
36
+ if (event.toolName === 'Edit' && input.file_path) {
37
+ const filename = String(input.file_path).split('/').pop() ?? '';
38
+ return `Updated ${filename}`;
39
+ }
40
+ if (event.toolName === 'Read' && input.file_path) {
41
+ return `Read ${String(input.file_path).split('/').slice(-2).join('/')}`;
42
+ }
43
+ return null;
44
+ }
45
+
46
+ function createPromptProgressTracker() {
47
+ const seenToolStarts = new Set<string>();
48
+
49
+ return (event: ToolUseEvent): string | null => {
50
+ if (event.type === 'tool_start' && event.toolName) {
51
+ if (seenToolStarts.has(event.toolName)) return null;
52
+ seenToolStarts.add(event.toolName);
53
+ return PROMPT_TOOL_MESSAGES[event.toolName] ?? null;
54
+ }
55
+ if (event.type === 'tool_complete') return getPromptToolCompleteMessage(event);
56
+ return null;
57
+ };
58
+ }
59
+
60
+ function readFileOrEmpty(path: string): string {
61
+ try {
62
+ if (existsSync(path)) return readFileSync(path, 'utf-8');
63
+ } catch { /* skip */ }
64
+ return '';
65
+ }
66
+
67
+ export async function handlePlanPrompt(
68
+ ctx: HandlerContext,
69
+ ws: WSContext,
70
+ userPrompt: string,
71
+ workingDir: string,
72
+ ): Promise<void> {
73
+ const pmDir = resolvePmDir(workingDir) ?? join(workingDir, '.pm');
74
+ const stateContent = readFileOrEmpty(join(pmDir, 'STATE.md'));
75
+ const projectContent = readFileOrEmpty(join(pmDir, 'project.md'));
76
+
77
+ // Compute next available IDs
78
+ const fullState = parsePlanDirectory(workingDir);
79
+ let idInfo = '';
80
+ if (fullState) {
81
+ const nextIS = getNextId(fullState.issues, 'IS');
82
+ const nextBG = getNextId(fullState.issues, 'BG');
83
+ const nextEP = getNextId(fullState.issues, 'EP');
84
+ idInfo = `Next available IDs: ${nextIS}, ${nextBG}, ${nextEP}`;
85
+ }
86
+
87
+ // Read existing epic files to provide context
88
+ let epicContext = '';
89
+ if (fullState) {
90
+ const existingEpics = fullState.issues.filter((i: { type: string }) => i.type === 'epic');
91
+ if (existingEpics.length > 0) {
92
+ epicContext = `\nExisting epics:\n${existingEpics.map((e: { id: string; title: string; path: string; children: string[] }) => `- ${e.id}: ${e.title} (${e.path}, children: ${e.children.length})`).join('\n')}\n`;
93
+ }
94
+ }
95
+
96
+ const enrichedPrompt = `You are managing a project in the .pm/ directory format (Project Plan Spec).
97
+ The project's current state is:
98
+
99
+ <state>
100
+ ${stateContent || 'No STATE.md exists yet'}
101
+ </state>
102
+
103
+ <project>
104
+ ${projectContent || 'No project.md yet'}
105
+ </project>
106
+
107
+ ${idInfo}
108
+ ${epicContext}
109
+
110
+ Follow these rules:
111
+ - When creating .pm/ files, use YAML front matter + markdown body
112
+ - When modifying issues, preserve all existing YAML fields you don't change
113
+ - After any state change, update STATE.md to reflect the new status
114
+ - Use the next available ID for new entities
115
+ - Respond briefly describing what you did
116
+
117
+ Issue scoping rules (critical for execution quality):
118
+ - Each issue is executed by a single AI agent with its own context window
119
+ - Issues estimated at 1-3 story points execute well (focused, single concern)
120
+ - Issues at 5 story points are viable if scoped to one subsystem
121
+ - Issues at 8+ story points MUST be decomposed into smaller sub-issues
122
+ - Issues at 13+ story points MUST become an epic with child issues
123
+ - Each issue should touch one logical concern (one component, one service, one data flow)
124
+ - If an issue requires work across multiple subsystems, split it into one issue per subsystem with blocked_by edges between them
125
+ - Research/investigation issues should be separate from implementation issues
126
+
127
+ Epic creation rules (when user asks for a feature with sub-tasks or an epic):
128
+ - Create an EP-*.md file in .pm/backlog/ with type: epic and a children: [] field in front matter
129
+ - Create individual IS-*.md (or BG-*.md) files for each child issue
130
+ - Each child issue must have epic: backlog/EP-XXX.md in its front matter
131
+ - The epic's children field must list all child paths: [backlog/IS-001.md, backlog/IS-002.md, ...]
132
+ - Set blocked_by between child issues where there are natural dependencies
133
+ - Give each child issue clear acceptance criteria and files to modify when possible
134
+ - Set appropriate priorities (P0-P3) based on the issue's importance within the epic
135
+
136
+ User request: ${userPrompt}`;
137
+
138
+ try {
139
+ ctx.broadcastToAll({
140
+ type: 'planPromptProgress',
141
+ data: { message: 'Starting project planning...' },
142
+ });
143
+
144
+ const runner = new HeadlessRunner({
145
+ workingDir,
146
+ directPrompt: enrichedPrompt,
147
+ outputCallback: (text: string) => {
148
+ ctx.send(ws, {
149
+ type: 'planPromptStreaming',
150
+ data: { token: text },
151
+ });
152
+ },
153
+ toolUseCallback: (() => {
154
+ const getProgressMessage = createPromptProgressTracker();
155
+ return (event: ToolUseEvent) => {
156
+ const message = getProgressMessage(event);
157
+ if (message) {
158
+ ctx.broadcastToAll({
159
+ type: 'planPromptProgress',
160
+ data: { message },
161
+ });
162
+ }
163
+ };
164
+ })(),
165
+ });
166
+
167
+ ctx.broadcastToAll({
168
+ type: 'planPromptProgress',
169
+ data: { message: 'Claude is planning your project...' },
170
+ });
171
+
172
+ const result = await runWithFileLogger('pm-compose', () => runner.run());
173
+
174
+ ctx.broadcastToAll({
175
+ type: 'planPromptProgress',
176
+ data: { message: 'Finalizing project plan...' },
177
+ });
178
+
179
+ ctx.send(ws, {
180
+ type: 'planPromptResponse',
181
+ data: {
182
+ response: result.completed ? 'Prompt executed successfully.' : (result.error || 'Unknown error'),
183
+ success: result.completed,
184
+ error: result.error || null,
185
+ },
186
+ });
187
+
188
+ // Re-parse and broadcast updated state
189
+ const updatedState = parsePlanDirectory(workingDir);
190
+ if (updatedState) {
191
+ ctx.broadcastToAll({ type: 'planStateUpdated', data: updatedState });
192
+ }
193
+ } catch (error) {
194
+ ctx.send(ws, {
195
+ type: 'planError',
196
+ data: { error: error instanceof Error ? error.message : String(error) },
197
+ });
198
+ }
199
+ }
@@ -0,0 +1,179 @@
1
+ // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
2
+ // Licensed under the MIT License. See LICENSE file for details.
3
+
4
+ /**
5
+ * Dependency Resolver — Validates and computes the dependency DAG.
6
+ *
7
+ * Builds adjacency list from blocked_by/blocks fields, detects cycles,
8
+ * and computes the "ready to work" set.
9
+ */
10
+
11
+ import type { Issue } from './types.js';
12
+
13
+ /**
14
+ * Detect cycles in the dependency graph.
15
+ * Returns the first cycle found as an array of issue IDs, or null if acyclic.
16
+ */
17
+ export function detectCycles(issues: Issue[]): string[] | null {
18
+ const issueByPath = new Map<string, Issue>();
19
+ for (const issue of issues) {
20
+ issueByPath.set(issue.path, issue);
21
+ }
22
+
23
+ // DFS with coloring: 0=white, 1=gray, 2=black
24
+ const color = new Map<string, number>();
25
+ const parent = new Map<string, string>();
26
+
27
+ for (const issue of issues) {
28
+ color.set(issue.path, 0);
29
+ }
30
+
31
+ for (const issue of issues) {
32
+ if (color.get(issue.path) === 0) {
33
+ const cycle = dfs(issue.path, issueByPath, color, parent);
34
+ if (cycle) return cycle;
35
+ }
36
+ }
37
+
38
+ return null;
39
+ }
40
+
41
+ function dfs(
42
+ path: string,
43
+ issueByPath: Map<string, Issue>,
44
+ color: Map<string, number>,
45
+ parent: Map<string, string>,
46
+ ): string[] | null {
47
+ color.set(path, 1); // Gray
48
+ const issue = issueByPath.get(path);
49
+ if (!issue) {
50
+ color.set(path, 2);
51
+ return null;
52
+ }
53
+
54
+ for (const dep of issue.blocks) {
55
+ if (!issueByPath.has(dep)) continue;
56
+ const depColor = color.get(dep);
57
+ if (depColor === 1) {
58
+ // Found cycle — reconstruct
59
+ const cycle = [dep, path];
60
+ let cur = path;
61
+ while (parent.has(cur) && parent.get(cur) !== dep) {
62
+ cur = parent.get(cur)!;
63
+ cycle.push(cur);
64
+ }
65
+ return cycle.map(p => issueByPath.get(p)?.id || p);
66
+ }
67
+ if (depColor === 0) {
68
+ parent.set(dep, path);
69
+ const cycle = dfs(dep, issueByPath, color, parent);
70
+ if (cycle) return cycle;
71
+ }
72
+ }
73
+
74
+ color.set(path, 2); // Black
75
+ return null;
76
+ }
77
+
78
+ /**
79
+ * Compute the set of issues that are ready to work on.
80
+ * An issue is ready if:
81
+ * - It's not an epic
82
+ * - Its status is backlog or todo (not started, done, or cancelled)
83
+ * - All its blocked_by items are done or cancelled
84
+ *
85
+ * If epicScope is provided, only returns issues belonging to that epic.
86
+ */
87
+ export function resolveReadyToWork(issues: Issue[], epicScope?: string): Issue[] {
88
+ const issueByPath = new Map<string, Issue>();
89
+ for (const issue of issues) {
90
+ issueByPath.set(issue.path, issue);
91
+ }
92
+
93
+ const readyStatuses = new Set(['backlog', 'todo']);
94
+ const doneStatuses = new Set(['done', 'cancelled']);
95
+
96
+ const priorityOrder: Record<string, number> = { P0: 0, P1: 1, P2: 2, P3: 3 };
97
+
98
+ // Build set of child paths for epic scoping
99
+ let epicChildPaths: Set<string> | null = null;
100
+ if (epicScope) {
101
+ const epic = issueByPath.get(epicScope);
102
+ if (epic) {
103
+ epicChildPaths = new Set(epic.children);
104
+ // Also include issues that reference this epic via their epic field
105
+ for (const issue of issues) {
106
+ if (issue.epic === epicScope) epicChildPaths.add(issue.path);
107
+ }
108
+ }
109
+ }
110
+
111
+ return issues
112
+ .filter(issue => {
113
+ if (issue.type === 'epic') return false;
114
+ if (!readyStatuses.has(issue.status)) return false;
115
+
116
+ // If scoped to an epic, only include that epic's children
117
+ if (epicChildPaths && !epicChildPaths.has(issue.path)) return false;
118
+
119
+ // Check all blockers are resolved
120
+ if (issue.blockedBy.length > 0) {
121
+ const allResolved = issue.blockedBy.every(bp => {
122
+ const blocker = issueByPath.get(bp);
123
+ return blocker && doneStatuses.has(blocker.status);
124
+ });
125
+ if (!allResolved) return false;
126
+ }
127
+
128
+ return true;
129
+ })
130
+ .sort((a, b) => {
131
+ // Sort by priority (P0 first)
132
+ return (priorityOrder[a.priority] ?? 9) - (priorityOrder[b.priority] ?? 9);
133
+ });
134
+ }
135
+
136
+ /**
137
+ * Compute the critical path through incomplete issues.
138
+ * Returns the longest chain of dependent issues.
139
+ */
140
+ export function computeCriticalPath(issues: Issue[]): Issue[] {
141
+ const issueByPath = new Map<string, Issue>();
142
+ for (const issue of issues) {
143
+ issueByPath.set(issue.path, issue);
144
+ }
145
+
146
+ const doneStatuses = new Set(['done', 'cancelled']);
147
+ const incompleteIssues = issues.filter(i => !doneStatuses.has(i.status) && i.type !== 'epic');
148
+
149
+ // Compute longest path using DFS with memoization
150
+ const longestFrom = new Map<string, Issue[]>();
151
+
152
+ function getLongest(path: string): Issue[] {
153
+ if (longestFrom.has(path)) return longestFrom.get(path)!;
154
+
155
+ const issue = issueByPath.get(path);
156
+ if (!issue || doneStatuses.has(issue.status)) {
157
+ longestFrom.set(path, []);
158
+ return [];
159
+ }
160
+
161
+ let best: Issue[] = [];
162
+ for (const dep of issue.blocks) {
163
+ const sub = getLongest(dep);
164
+ if (sub.length > best.length) best = sub;
165
+ }
166
+
167
+ const result = [issue, ...best];
168
+ longestFrom.set(path, result);
169
+ return result;
170
+ }
171
+
172
+ let criticalPath: Issue[] = [];
173
+ for (const issue of incompleteIssues) {
174
+ const path = getLongest(issue.path);
175
+ if (path.length > criticalPath.length) criticalPath = path;
176
+ }
177
+
178
+ return criticalPath;
179
+ }