mstro-app 0.4.3 → 0.4.4

package/server/services/websocket/plan-helpers.ts

@@ -0,0 +1,215 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { PlanExecutor } from '../plan/executor.js';
+import { defaultPmDir, resolvePmDir } from '../plan/parser.js';
+import type { Workspace } from '../plan/types.js';
+import { PlanWatcher } from '../plan/watcher.js';
+import type { HandlerContext } from './handler-context.js';
+import type { WSContext } from './types.js';
+
+export const watcherCache = new Map<string, PlanWatcher>();
+export const executorCache = new Map<string, PlanExecutor>();
+
+/** Validate that a user-supplied path resolves within the .pm/ (or legacy .plan/) directory. */
+export function resolvePlanPath(workingDir: string, relativePath: string): string | null {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return null;
+  const resolved = resolve(pmDir, relativePath);
+  if (!resolved.startsWith(`${pmDir}/`) && resolved !== pmDir) return null;
+  return resolved;
+}
+
+/** Guard for write operations — returns true if denied. */
+export function denyIfViewOnly(ctx: HandlerContext, ws: WSContext, permission?: 'control' | 'view'): boolean {
+  if (permission === 'view') {
+    ctx.send(ws, { type: 'planError', data: { error: 'Permission denied' } });
+    return true;
+  }
+  return false;
+}
+
+export function formatYamlValue(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    return `[${value.map(v => typeof v === 'string' ? v : String(v)).join(', ')}]`;
+  }
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+export function buildIssueMarkdown(
+  id: string, title: string, type: string, priority: string,
+  labels: string[], sprint: string | null, description: string,
+): string {
+  const labelsYaml = labels.length > 0 ? `[${labels.join(', ')}]` : '[]';
+  const today = new Date().toISOString().split('T')[0];
+  return `---
+id: ${id}
+title: "${title.replace(/"/g, '\\"')}"
+type: ${type}
+status: backlog
+priority: ${priority}
+estimate: null
+labels: ${labelsYaml}
+epic: null
+sprint: ${sprint || 'null'}
+milestone: null
+assigned: null
+created: "${today}"
+due: null
+blocked_by: []
+blocks: []
+relates_to: []
+---
+
+# ${id}: ${title}
+
+## Description
+${description}
+
+## Acceptance Criteria
+
+## Technical Notes
+
+## Files to Modify
+
+## Activity
+`;
+}
+
+function buildProjectMarkdown(name: string): string {
+  const today = new Date().toISOString().split('T')[0];
+  const projectId = name.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+  return `---
+name: "${name}"
+id: ${projectId}
+created: "${today}"
+status: active
+estimation: fibonacci
+id_prefixes:
+  epic: EP
+  issue: IS
+  bug: BG
+labels: []
+---
+
+# ${name}
+
+## Goals
+
+## Teams
+
+## Labels
+
+## Workflows
+| Status | Category | Description |
+|---|---|---|
+| backlog | unstarted | Accepted, not yet scheduled |
+| todo | unstarted | Scheduled for current sprint |
+| in_progress | started | Actively being worked on |
+| in_review | started | PR open, awaiting review |
+| done | completed | Merged and verified |
+| cancelled | cancelled | Will not be done |
+`;
+}
+
+function buildStateMarkdown(name: string): string {
+  return `---
+project: "${name}"
+current_sprint: null
+active_milestone: null
+paused: false
+last_session: null
+---
+
+# Project State
+
+## Current Focus
+
+## Ready to Work
+
+## In Progress
+
+## Blocked
+
+## Recently Completed
+
+## Warnings
+`;
+}
+
+export function getWatcher(workingDir: string, ctx: HandlerContext): PlanWatcher {
+  let watcher = watcherCache.get(workingDir);
+  if (!watcher) {
+    watcher = new PlanWatcher(workingDir, ctx);
+    watcherCache.set(workingDir, watcher);
+  }
+  return watcher;
+}
+
+export function getExecutor(workingDir: string): PlanExecutor {
+  let executor = executorCache.get(workingDir);
+  if (!executor) {
+    executor = new PlanExecutor(workingDir);
+    executorCache.set(workingDir, executor);
+  }
+  return executor;
+}
+
+/** Cleanup watchers and executors for a working directory. */
+export function cleanupPlanResources(workingDir: string): void {
+  const watcher = watcherCache.get(workingDir);
+  if (watcher) {
+    watcher.stop();
+    watcherCache.delete(workingDir);
+  }
+  const executor = executorCache.get(workingDir);
+  if (executor) {
+    executor.stop();
+    executorCache.delete(workingDir);
+  }
+}
+
+/** Create the .mstro/pm/ directory structure with a default board. */
+export function scaffoldPmDirectory(workingDir: string, name: string): void {
+  const planDir = defaultPmDir(workingDir);
+  const boardId = 'BOARD-001';
+  const boardDir = join(planDir, 'boards', boardId);
+
+  for (const dir of ['milestones', 'templates']) {
+    mkdirSync(join(planDir, dir), { recursive: true });
+  }
+  for (const dir of ['backlog', 'out', 'reviews', 'logs']) {
+    mkdirSync(join(boardDir, dir), { recursive: true });
+  }
+
+  writeFileSync(join(planDir, 'project.md'), buildProjectMarkdown(name), 'utf-8');
+
+  const workspace: Workspace = { activeBoardId: boardId, boardOrder: [boardId] };
+  writeFileSync(join(planDir, 'workspace.json'), JSON.stringify(workspace, null, 2), 'utf-8');
+
+  const today = new Date().toISOString().split('T')[0];
+  writeFileSync(join(boardDir, 'board.md'), `---
+id: ${boardId}
+title: "Board 1"
+status: draft
+created: "${today}"
+completed_at: null
+goal: ""
+---
+
+# Board 1
+
+## Goal
+
+## Notes
+`, 'utf-8');
+
+  writeFileSync(join(boardDir, 'STATE.md'), buildStateMarkdown(name), 'utf-8');
+  writeFileSync(join(boardDir, 'progress.md'), '# Board Progress\n', 'utf-8');
+}

package/server/services/websocket/plan-issue-handlers.ts

@@ -0,0 +1,204 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { replaceFrontMatterField } from '../plan/front-matter.js';
+import { defaultPmDir, getNextId, parseBoardDirectory, parsePlanDirectory, parseSingleIssue, parseSingleMilestone, parseSingleSprint, planDirExists, resolvePmDir } from '../plan/parser.js';
+import type { HandlerContext } from './handler-context.js';
+import { buildIssueMarkdown, denyIfViewOnly, formatYamlValue, getWatcher, resolvePlanPath, scaffoldPmDirectory } from './plan-helpers.js';
+import type { WebSocketMessage, WSContext } from './types.js';
+
+// ============================================================================
+// Read-only handlers
+// ============================================================================
+
+export function handlePlanInit(ctx: HandlerContext, ws: WSContext, workingDir: string): void {
+  if (!planDirExists(workingDir)) {
+    const projectName = basename(workingDir) || 'My Project';
+    scaffoldPmDirectory(workingDir, projectName);
+  }
+
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    ctx.send(ws, { type: 'planNotFound', data: {} });
+    return;
+  }
+
+  ctx.send(ws, { type: 'planState', data: fullState });
+
+  const watcher = getWatcher(workingDir, ctx);
+  watcher.start();
+}
+
+export function handleListIssues(ctx: HandlerContext, ws: WSContext, workingDir: string): void {
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    ctx.send(ws, { type: 'planNotFound', data: {} });
+    return;
+  }
+  ctx.send(ws, { type: 'planIssueList', data: { issues: fullState.issues } });
+}
+
+export function handleGetIssue(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, workingDir: string): void {
+  const path = msg.data?.path;
+  if (!path || !resolvePlanPath(workingDir, path)) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Invalid issue path' } });
+    return;
+  }
+  const issue = parseSingleIssue(workingDir, path);
+  if (!issue) {
+    ctx.send(ws, { type: 'planError', data: { error: `Issue not found: ${path}` } });
+    return;
+  }
+  ctx.send(ws, { type: 'planIssue', data: issue });
+}
+
+export function handleGetSprint(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, workingDir: string): void {
+  const path = msg.data?.path;
+  if (!path || !resolvePlanPath(workingDir, path)) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Invalid sprint path' } });
+    return;
+  }
+  const sprint = parseSingleSprint(workingDir, path);
+  if (!sprint) {
+    ctx.send(ws, { type: 'planError', data: { error: `Sprint not found: ${path}` } });
+    return;
+  }
+  ctx.send(ws, { type: 'planSprint', data: sprint });
+}
+
+export function handleGetMilestone(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, workingDir: string): void {
+  const path = msg.data?.path;
+  if (!path || !resolvePlanPath(workingDir, path)) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Invalid milestone path' } });
+    return;
+  }
+  const milestone = parseSingleMilestone(workingDir, path);
+  if (!milestone) {
+    ctx.send(ws, { type: 'planError', data: { error: `Milestone not found: ${path}` } });
+    return;
+  }
+  ctx.send(ws, { type: 'planMilestone', data: milestone });
+}
+
+// ============================================================================
+// Mutation handlers
+// ============================================================================
+
+/** Resolve backlog directory and existing issues for a board or legacy layout. */
+function resolveBacklogContext(pmDir: string, workingDir: string, boardId?: string) {
+  const fullState = parsePlanDirectory(workingDir);
+  const effectiveBoardId = boardId || fullState?.workspace?.activeBoardId;
+
+  if (effectiveBoardId && existsSync(join(pmDir, 'boards', effectiveBoardId))) {
+    const boardState = parseBoardDirectory(pmDir, effectiveBoardId);
+    return {
+      backlogDir: join(pmDir, 'boards', effectiveBoardId, 'backlog'),
+      issues: boardState?.issues ?? [],
+      pathPrefix: `boards/${effectiveBoardId}/backlog`,
+    };
+  }
+  return {
+    backlogDir: join(pmDir, 'backlog'),
+    issues: fullState?.issues ?? [],
+    pathPrefix: 'backlog',
+  };
+}
+
+export function handleCreateIssue(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const { title, type = 'issue', priority = 'P2', labels = [], sprint, description = '', boardId } = msg.data || {};
+  if (!title) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Title required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir) ?? defaultPmDir(workingDir);
+  const { backlogDir, issues, pathPrefix } = resolveBacklogContext(pmDir, workingDir, boardId);
+
+  if (!existsSync(backlogDir)) mkdirSync(backlogDir, { recursive: true });
+
+  const prefix = type === 'bug' ? 'BG' : type === 'epic' ? 'EP' : 'IS';
+  const id = getNextId(issues, prefix);
+  const fileName = `${id}.md`;
+
+  writeFileSync(join(backlogDir, fileName), buildIssueMarkdown(id, title, type, priority, labels, sprint, description), 'utf-8');
+
+  const issue = parseSingleIssue(workingDir, `${pathPrefix}/${fileName}`);
+  ctx.broadcastToAll({ type: 'planIssueCreated', data: issue });
+}
+
+export function handleUpdateIssue(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const { path, fields } = msg.data || {};
+  if (!path || !fields) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Path and fields required' } });
+    return;
+  }
+
+  const fullPath = resolvePlanPath(workingDir, path);
+  if (!fullPath || !existsSync(fullPath)) {
+    ctx.send(ws, { type: 'planError', data: { error: `File not found: ${path}` } });
+    return;
+  }
+
+  let content = readFileSync(fullPath, 'utf-8');
+  if (!content.match(/^---\n/)) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Invalid file format' } });
+    return;
+  }
+
+  for (const [key, value] of Object.entries(fields as Record<string, unknown>)) {
+    const yamlKey = key.replace(/([A-Z])/g, '_$1').toLowerCase();
+    content = replaceFrontMatterField(content, yamlKey, formatYamlValue(value));
+  }
+
+  writeFileSync(fullPath, content, 'utf-8');
+
+  const issue = parseSingleIssue(workingDir, path);
+  ctx.broadcastToAll({ type: 'planIssueUpdated', data: issue });
+}
+
+export function handleDeleteIssue(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const path = msg.data?.path;
+  if (!path) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Path required' } });
+    return;
+  }
+
+  const fullPath = resolvePlanPath(workingDir, path);
+  if (!fullPath || !existsSync(fullPath)) {
+    ctx.send(ws, { type: 'planError', data: { error: `File not found: ${path}` } });
+    return;
+  }
+
+  unlinkSync(fullPath);
+  ctx.broadcastToAll({ type: 'planIssueDeleted', data: { path } });
+}
+
+export function handleScaffold(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const name = msg.data?.name || 'My Project';
+  scaffoldPmDirectory(workingDir, name);
+
+  const fullState = parsePlanDirectory(workingDir);
+  ctx.broadcastToAll({ type: 'planScaffolded', data: fullState });
+}

package/server/services/websocket/plan-sprint-handlers.ts

@@ -0,0 +1,252 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFrontMatterField } from '../plan/front-matter.js';
+import { defaultPmDir, getNextSprintId, parsePlanDirectory, parseSingleSprint, parseSprintArtifacts, resolvePmDir } from '../plan/parser.js';
+import type { Issue } from '../plan/types.js';
+import type { HandlerContext } from './handler-context.js';
+import { denyIfViewOnly, resolvePlanPath } from './plan-helpers.js';
+import type { WebSocketMessage, WSContext } from './types.js';
+
+// ============================================================================
+// Sprint lifecycle handlers (legacy — kept for backward compatibility)
+// ============================================================================
+
+function buildSprintMarkdown(
+  id: string, title: string, goal: string, start: string, end: string,
+  issueRefs: string[],
+): string {
+  const issuesYaml = issueRefs.length > 0
+    ? `\n${issueRefs.map(p => `  - ${p}`).join('\n')}`
+    : ' []';
+  return `---
+id: ${id}
+title: "${title.replace(/"/g, '\\"')}"
+status: planned
+start: "${start}"
+end: "${end}"
+goal: "${goal.replace(/"/g, '\\"')}"
+capacity: null
+committed: null
+completed: null
+completed_at: null
+issues:${issuesYaml}
+---
+
+# ${id}: ${title}
+
+## Sprint Goal
+${goal}
+
+## Issues
+| Issue | Title | Points | Status |
+|---|---|---|---|
+`;
+}
+
+/** Assign issues to a sprint by updating their front matter sprint field. */
+function assignIssuesToSprint(workingDir: string, issues: Issue[], issueIds: string[], sprintPath: string): void {
+  for (const issueId of issueIds) {
+    const issue = issues.find(i => i.id === issueId);
+    if (!issue) continue;
+    const fullPath = resolvePlanPath(workingDir, issue.path);
+    if (!fullPath || !existsSync(fullPath)) continue;
+    const content = replaceFrontMatterField(readFileSync(fullPath, 'utf-8'), 'sprint', sprintPath);
+    writeFileSync(fullPath, content, 'utf-8');
+  }
+}
+
+export function handleCreateSprint(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const { title, goal = '', start = '', end = '', issueIds = [] } = msg.data || {};
+  if (!title) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Sprint title required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir) ?? defaultPmDir(workingDir);
+  const sprintsDir = join(pmDir, 'sprints');
+  if (!existsSync(sprintsDir)) mkdirSync(sprintsDir, { recursive: true });
+
+  const fullState = parsePlanDirectory(workingDir);
+  const id = fullState ? getNextSprintId(fullState.sprints) : 'SPRINT-001';
+
+  const issueRefs = (issueIds as string[]).map((issueId: string) => {
+    const issue = fullState?.issues.find(i => i.id === issueId);
+    return issue ? issue.path : `backlog/${issueId}.md`;
+  });
+
+  writeFileSync(join(sprintsDir, `${id}.md`), buildSprintMarkdown(id, title, goal, start, end, issueRefs), 'utf-8');
+
+  const sandboxDir = join(sprintsDir, id);
+  mkdirSync(join(sandboxDir, 'out'), { recursive: true });
+  mkdirSync(join(sandboxDir, 'reviews'), { recursive: true });
+  writeFileSync(join(sandboxDir, 'progress.md'), `# ${id}: ${title} — Progress Log\n`, 'utf-8');
+
+  if (issueRefs.length > 0 && fullState) {
+    assignIssuesToSprint(workingDir, fullState.issues, issueIds as string[], `sprints/${id}.md`);
+  }
+
+  const sprint = parseSingleSprint(workingDir, `sprints/${id}.md`);
+  ctx.broadcastToAll({ type: 'planSprintCreated', data: sprint });
+}
+
+/** Promote sprint issues from 'backlog' to 'todo' status. */
+function promoteSprintIssues(pmDir: string, sprint: { issues: Array<{ id: string; path: string }> }, allIssues: Issue[]): void {
+  for (const issueSummary of sprint.issues) {
+    const issue = allIssues.find(i => i.id === issueSummary.id || i.path === issueSummary.path);
+    if (!issue || issue.status !== 'backlog') continue;
+    const issuePath = join(pmDir, issue.path);
+    if (!existsSync(issuePath)) continue;
+    writeFileSync(issuePath, replaceFrontMatterField(readFileSync(issuePath, 'utf-8'), 'status', 'todo'), 'utf-8');
+  }
+}
+
+/** Update a file's front matter field if the file exists. */
+function updateFileField(filePath: string, field: string, value: string): void {
+  if (!existsSync(filePath)) return;
+  writeFileSync(filePath, replaceFrontMatterField(readFileSync(filePath, 'utf-8'), field, value), 'utf-8');
+}
+
+export function handleActivateSprint(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const sprintId = msg.data?.sprintId;
+  if (!sprintId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Sprint ID required' } });
+    return;
+  }
+
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    ctx.send(ws, { type: 'planError', data: { error: 'No project found' } });
+    return;
+  }
+
+  const currentActive = fullState.sprints.find(s => s.status === 'active');
+  if (currentActive && currentActive.id !== sprintId) {
+    ctx.send(ws, { type: 'planError', data: { error: `Sprint ${currentActive.id} is already active. Complete it first.` } });
+    return;
+  }
+
+  const sprint = fullState.sprints.find(s => s.id === sprintId);
+  if (!sprint) {
+    ctx.send(ws, { type: 'planError', data: { error: `Sprint not found: ${sprintId}` } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  updateFileField(join(pmDir, sprint.path), 'status', 'active');
+  updateFileField(join(pmDir, 'STATE.md'), 'current_sprint', `"${sprint.path}"`);
+  promoteSprintIssues(pmDir, sprint, fullState.issues);
+
+  const updatedSprint = parseSingleSprint(workingDir, sprint.path);
+  ctx.broadcastToAll({ type: 'planSprintUpdated', data: updatedSprint });
+
+  const updatedState = parsePlanDirectory(workingDir);
+  if (updatedState) {
+    ctx.broadcastToAll({ type: 'planStateUpdated', data: updatedState });
+  }
+}
+
+export function handleCompleteSprint(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const sprintId = msg.data?.sprintId;
+  if (!sprintId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Sprint ID required' } });
+    return;
+  }
+
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    ctx.send(ws, { type: 'planError', data: { error: 'No project found' } });
+    return;
+  }
+
+  const sprint = fullState.sprints.find(s => s.id === sprintId);
+  if (!sprint) {
+    ctx.send(ws, { type: 'planError', data: { error: `Sprint not found: ${sprintId}` } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const now = new Date().toISOString();
+
+  const sprintIssues = fullState.issues.filter(i => i.sprint === sprint.path);
+  const completedIssues = sprintIssues.filter(i => i.status === 'done').length;
+  const failedIssues = sprintIssues.filter(i => i.status !== 'done' && i.status !== 'cancelled').length;
+
+  const sprintPath = join(pmDir, sprint.path);
+  if (existsSync(sprintPath)) {
+    let content = readFileSync(sprintPath, 'utf-8');
+    content = replaceFrontMatterField(content, 'status', 'completed');
+    content = replaceFrontMatterField(content, 'completed_at', `"${now}"`);
+    content = replaceFrontMatterField(content, 'completed', String(completedIssues));
+
+    if (!content.includes('execution_summary:')) {
+      const summaryYaml = [
+        'execution_summary:',
+        `  total_issues: ${sprintIssues.length}`,
+        `  completed_issues: ${completedIssues}`,
+        `  failed_issues: ${failedIssues}`,
+      ].join('\n');
+      const fmClose = content.indexOf('\n---', content.indexOf('---') + 3);
+      if (fmClose !== -1) {
+        content = `${content.slice(0, fmClose)}\n${summaryYaml}${content.slice(fmClose)}`;
+      }
+    }
+
+    writeFileSync(sprintPath, content, 'utf-8');
+  }
+
+  const statePath = join(pmDir, 'STATE.md');
+  if (existsSync(statePath)) {
+    let stateContent = readFileSync(statePath, 'utf-8');
+    stateContent = replaceFrontMatterField(stateContent, 'current_sprint', 'null');
+    writeFileSync(statePath, stateContent, 'utf-8');
+  }
+
+  const updatedSprint = parseSingleSprint(workingDir, sprint.path);
+  ctx.broadcastToAll({ type: 'planSprintCompleted', data: updatedSprint });
+
+  const updatedState = parsePlanDirectory(workingDir);
+  if (updatedState) {
+    ctx.broadcastToAll({ type: 'planStateUpdated', data: updatedState });
+  }
+}
+
+export function handleGetSprintArtifacts(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string,
+): void {
+  const sprintId = msg.data?.sprintId;
+  if (!sprintId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Sprint ID required' } });
+    return;
+  }
+
+  const artifacts = parseSprintArtifacts(workingDir, sprintId);
+  if (!artifacts) {
+    ctx.send(ws, { type: 'planSprintArtifacts', data: { sprintId, progressLog: '', outputFiles: [], reviewResults: [] } });
+    return;
+  }
+
+  ctx.send(ws, { type: 'planSprintArtifacts', data: artifacts });
+}