@the-bearded-bear/claude-craft 7.35.0 → 8.1.0

package/cli/kanban/server/app.js

@@ -0,0 +1,201 @@
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { serveStatic } from '@hono/node-server/serve-static';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import { csrfGuard, readonlyGuard, resolveSafe } from './middleware/security.js';
+import { validateTransition, validateUnblock, computeTransitionPatch } from './services/state-machine.js';
+import { updateFrontmatter, LockedError, MtimeMismatchError } from './services/file-writer.js';
+import { loadSprintStatus, computeBurndown } from './services/sprint-cache.js';
+import { TransitionRequestSchema } from '../shared/schemas.js';
+
+/**
+ * Build the Hono app. Kept separate from the HTTP server boot so tests can
+ * invoke routes via app.request() without opening a socket.
+ *
+ * @param {object} opts
+ * @param {import('./services/repository.js').Repository} opts.repository
+ * @param {number} opts.port
+ * @param {boolean} [opts.readonly=false]
+ * @param {string} [opts.projectRoot] - Parent of project-management/, defaults to parent of repository.rootDir
+ * @returns {Hono}
+ */
+export function createApp({ repository, port, readonly = false, eventBus = null, projectRoot = null }) {
+  const resolvedProjectRoot = projectRoot ?? path.dirname(repository.rootDir);
+  const app = new Hono();
+
+  app.use('*', csrfGuard(port));
+  app.use('*', readonlyGuard(readonly));
+
+  app.get('/api/health', (c) => c.json({ ok: true, readonly }));
+
+  app.get('/api/stories', (c) => {
+    const sprintId = c.req.query('sprint_id') || undefined;
+    const status = c.req.query('status') || undefined;
+    const epicId = c.req.query('epic_id') || undefined;
+    return c.json({
+      stories: repository.listStories({ sprintId, status, epicId }),
+      epics: repository.listEpics(),
+    });
+  });
+
+  app.get('/api/stories/:id', (c) => {
+    const id = c.req.param('id');
+    const story = repository.getStory(id);
+    if (!story) return c.json({ error: 'not_found' }, 404);
+    const tasks = repository.listTasksForStory(id);
+    return c.json({ story, tasks });
+  });
+
+  app.get('/api/dependencies', (c) => {
+    return c.json(repository.buildDependenciesGraph());
+  });
+
+  app.get('/api/docs', (c) => {
+    return c.json({ docs: repository.listDocs().map((d) => ({ rel: d.rel })) });
+  });
+
+  app.get('/api/docs/:rel{.+}', async (c) => {
+    const rel = c.req.param('rel');
+    try {
+      resolveSafe(repository.rootDir, rel);
+    } catch {
+      return c.json({ error: 'invalid_path' }, 400);
+    }
+    const content = await repository.readDoc(rel);
+    if (content === null) return c.json({ error: 'not_found' }, 404);
+    return c.text(content);
+  });
+
+  app.patch('/api/stories/:id/status', async (c) => {
+    const id = c.req.param('id');
+    const filepath = repository.getStoryFile(id);
+    const story = repository.getStory(id);
+    if (!story || !filepath) return c.json({ error: 'not_found' }, 404);
+
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'invalid_json' }, 400);
+    }
+
+    const parsed = TransitionRequestSchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'invalid_payload', issues: parsed.error.issues }, 400);
+    }
+    const { status: target, blocked_reason } = parsed.data;
+
+    // Unblock : dispatch when story is blocked and target matches previous_status
+    if (story.status === 'blocked' && target !== 'blocked') {
+      const unblock = validateUnblock(story);
+      if (!unblock.allowed) {
+        return c.json({ error: 'invalid_transition', reason: unblock.reason }, 409);
+      }
+      if (unblock.status !== target) {
+        return c.json(
+          {
+            error: 'invalid_transition',
+            reason: `blocked stories may only be restored to previous_status (${unblock.status})`,
+          },
+          409
+        );
+      }
+    } else {
+      const check = validateTransition(story, target, { blocked_reason });
+      if (!check.allowed) {
+        return c.json(
+          {
+            error: 'invalid_transition',
+            reason: check.reason,
+            gate: check.gate,
+            missing: check.missing,
+          },
+          409
+        );
+      }
+    }
+
+    const patch = computeTransitionPatch(story, target, { blocked_reason });
+    try {
+      await updateFrontmatter(filepath, patch, { expectedMtime: story._mtime });
+      await repository.refresh();
+      const fresh = repository.getStory(id);
+      if (eventBus) eventBus.publish('story:updated', { id, story: fresh });
+      return c.json({ story: fresh });
+    } catch (err) {
+      if (err instanceof LockedError) return c.json({ error: 'locked' }, 423);
+      if (err instanceof MtimeMismatchError) return c.json({ error: 'conflict', reason: 'file changed on disk' }, 409);
+      return c.json({ error: 'write_failed', message: err.message }, 500);
+    }
+  });
+
+  app.get('/api/events', (c) => {
+    if (!eventBus) return c.json({ error: 'events_disabled' }, 501);
+    return streamSSE(c, async (stream) => {
+      const unsubscribe = eventBus.subscribe((msg) => {
+        stream
+          .writeSSE({
+            event: msg.event,
+            data: JSON.stringify(msg),
+          })
+          .catch(() => {
+            /* client disconnected */
+          });
+      });
+      stream.onAbort(() => unsubscribe());
+      // heartbeat toutes les 30s
+      try {
+        while (!stream.aborted) {
+          await stream.sleep(30_000);
+          await stream.writeSSE({ event: 'heartbeat', data: String(Date.now()) });
+        }
+      } catch {
+        /* aborted */
+      }
+      unsubscribe();
+    });
+  });
+
+  app.get('/api/sprints/current', async (c) => {
+    const sprintStatus = await loadSprintStatus(resolvedProjectRoot);
+    if (!sprintStatus || sprintStatus._invalid) {
+      return c.json({ error: 'not_found' }, 404);
+    }
+
+    const sprintId = sprintStatus.metadata.sprint_id;
+    const stories = repository.listStories({ sprintId });
+    if (stories.length === 0) {
+      return c.json({ error: 'not_found' }, 404);
+    }
+
+    const burndown = computeBurndown(sprintStatus, stories);
+
+    return c.json({
+      sprint: sprintStatus.metadata,
+      stories: stories.map((s) => ({
+        id: s.id,
+        title: s.title,
+        status: s.status,
+        story_points: s.story_points,
+        assigned_to: s.assigned_to,
+        tasks: s.tasks,
+      })),
+      burndown,
+    });
+  });
+
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const clientDist = path.resolve(__dirname, '../client/dist');
+  if (fs.existsSync(clientDist)) {
+    app.use('/assets/*', serveStatic({ root: path.relative(process.cwd(), clientDist) }));
+    app.get('/', (c) => c.html(fs.readFileSync(path.join(clientDist, 'index.html'), 'utf8')));
+  } else {
+    app.get('/', (c) =>
+      c.text('claude-craft kanban : client not built.\n' + 'Run "npm run kanban:build" to build the UI.\n')
+    );
+  }
+
+  return app;
+}

package/cli/kanban/server/middleware/security.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+
+/**
+ * Middleware factory : enforces same-origin for mutating requests.
+ * Only http://127.0.0.1:<port> and http://localhost:<port> are accepted.
+ */
+export function csrfGuard(port) {
+  const allowed = new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`]);
+  return async (c, next) => {
+    if (!['POST', 'PATCH', 'PUT', 'DELETE'].includes(c.req.method)) {
+      return next();
+    }
+    const origin = c.req.header('origin');
+    const referer = c.req.header('referer');
+    const source = origin ?? (referer ? new URL(referer).origin : null);
+    if (!source || !allowed.has(source)) {
+      return c.json({ error: 'forbidden', reason: 'invalid origin' }, 403);
+    }
+    return next();
+  };
+}
+
+/**
+ * Resolves a user-provided relative path safely under a base directory.
+ * Throws on path traversal attempts.
+ * @param {string} baseDir - absolute, trusted
+ * @param {string} userPath - user-provided, untrusted
+ * @returns {string} absolute resolved path, guaranteed under baseDir
+ */
+export function resolveSafe(baseDir, userPath) {
+  const base = path.resolve(baseDir);
+  const resolved = path.resolve(base, userPath);
+  const rel = path.relative(base, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    const err = new Error('path traversal detected');
+    err.code = 'PATH_TRAVERSAL';
+    throw err;
+  }
+  return resolved;
+}
+
+/**
+ * Rejects requests when --readonly mode is active.
+ */
+export function readonlyGuard(enabled) {
+  return async (c, next) => {
+    if (!enabled) return next();
+    if (['POST', 'PATCH', 'PUT', 'DELETE'].includes(c.req.method)) {
+      return c.json({ error: 'readonly', reason: 'server started in --readonly mode' }, 403);
+    }
+    return next();
+  };
+}

package/cli/kanban/server/services/event-bus.js

@@ -0,0 +1,33 @@
+/**
+ * Minimal in-memory event bus with SSE-friendly fan-out.
+ * Subscribers receive objects ; the route layer serializes them for SSE.
+ */
+export class EventBus {
+  constructor() {
+    this.subscribers = new Set();
+  }
+
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => this.subscribers.delete(fn);
+  }
+
+  publish(event, payload) {
+    const msg = { event, payload, ts: Date.now() };
+    for (const fn of [...this.subscribers]) {
+      try {
+        fn(msg);
+      } catch {
+        /* isolate subscriber failures */
+      }
+    }
+  }
+
+  get size() {
+    return this.subscribers.size;
+  }
+
+  clear() {
+    this.subscribers.clear();
+  }
+}

package/cli/kanban/server/services/file-scanner.js

@@ -0,0 +1,113 @@
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Recursive scanner for a project-management/ directory (BMAD v6 layout).
+ * Returns categorized file paths with mtime for cache invalidation.
+ *
+ * Layout :
+ *   project-management/
+ *     prd.md, tech-spec.md, personas.md, definition-of-done.md, dependencies-matrix.md
+ *     architecture/*.md
+ *     backlog/epics/EPIC-*.md
+ *     backlog/user-stories/US-*.md
+ *     sprints/sprint-*\/{sprint-goal,board,status-*}.md
+ *     sprints/sprint-*\/tasks/TASK-*.md
+ */
+
+const IGNORE_PATTERNS = [/\.bak$/, /\.lock$/, /^\./];
+
+function isIgnored(name) {
+  return IGNORE_PATTERNS.some((re) => re.test(name));
+}
+
+async function walk(dir, onFile) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const entry of entries) {
+    if (isIgnored(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(full, onFile);
+    } else if (entry.isFile()) {
+      await onFile(full);
+    }
+  }
+}
+
+function classify(rootDir, absPath) {
+  const rel = path.relative(rootDir, absPath).split(path.sep).join('/');
+  if (!rel.endsWith('.md') && !rel.endsWith('.yaml') && !rel.endsWith('.yml')) return null;
+
+  if (rel.startsWith('backlog/user-stories/') && /US-\d+/.test(rel)) return 'story';
+  if (rel.startsWith('backlog/epics/') && /EPIC-\d+/.test(rel)) return 'epic';
+
+  const sprintMatch = rel.match(/^sprints\/([^/]+)\/(.+)$/);
+  if (sprintMatch) {
+    const [, , rest] = sprintMatch;
+    if (rest.startsWith('tasks/') && /TASK-\d+/.test(rest)) return 'task';
+    if (rest === 'sprint-goal.md') return 'sprint-goal';
+    if (rest === 'board.md') return 'board';
+    if (rest.startsWith('status-')) return 'sprint-status-snapshot';
+    if (rest === 'sprint-review.md') return 'sprint-review';
+    if (rest === 'sprint-dependencies.md') return 'sprint-deps';
+    return 'sprint-other';
+  }
+
+  if (rel.startsWith('architecture/')) return 'architecture';
+
+  const docs = new Set([
+    'prd.md',
+    'tech-spec.md',
+    'personas.md',
+    'definition-of-done.md',
+    'dependencies-matrix.md',
+    'README.md',
+  ]);
+  if (docs.has(rel)) return 'doc';
+  if (rel === 'workflow-status.yaml') return 'workflow-status';
+
+  return 'other';
+}
+
+function sprintIdOf(rootDir, absPath) {
+  const rel = path.relative(rootDir, absPath).split(path.sep).join('/');
+  const m = rel.match(/^sprints\/([^/]+)\//);
+  return m ? m[1] : null;
+}
+
+/**
+ * @param {string} rootDir - absolute path to project-management/
+ * @returns {Promise<{ files: Array<{path:string, category:string, mtime:number, sprintId:string|null}> }>}
+ */
+export async function scan(rootDir) {
+  const absRoot = path.resolve(rootDir);
+  const files = [];
+  await walk(absRoot, async (full) => {
+    const category = classify(absRoot, full);
+    if (!category) return;
+    const st = await stat(full);
+    files.push({
+      path: full,
+      category,
+      mtime: st.mtimeMs,
+      sprintId: sprintIdOf(absRoot, full),
+    });
+  });
+  return { files };
+}
+
+export function groupByCategory(files) {
+  const groups = {};
+  for (const f of files) {
+    (groups[f.category] ??= []).push(f);
+  }
+  return groups;
+}
+
+export const _internal = { classify, sprintIdOf };

package/cli/kanban/server/services/file-watcher.js

@@ -0,0 +1,68 @@
+import chokidar from 'chokidar';
+import { _internal } from './file-scanner.js';
+
+/**
+ * Start watching project-management/ directory for changes.
+ * Publishes 'file:changed' events to eventBus after debounce.
+ *
+ * @param {object} opts
+ * @param {string} opts.rootDir - absolute path to watch
+ * @param {EventBus} opts.eventBus - bus to publish events
+ * @param {Repository} opts.repository - cache to refresh on changes
+ * @param {number} [opts.debounceMs=200] - debounce delay per path
+ * @returns {object} - { stop: async () => void }
+ */
+export function startWatcher({ rootDir, eventBus, repository, debounceMs = 200 }) {
+  const debounceTimers = new Map();
+  let watcher = null;
+
+  const onEvent = async (event, filePath) => {
+    const category = _internal.classify(rootDir, filePath);
+    if (!category || category === 'other') return;
+
+    if (debounceTimers.has(filePath)) {
+      clearTimeout(debounceTimers.get(filePath));
+    }
+
+    debounceTimers.set(
+      filePath,
+      setTimeout(async () => {
+        debounceTimers.delete(filePath);
+        try {
+          await repository.refresh();
+          eventBus.publish('file:changed', { path: filePath, event, category });
+        } catch (err) {
+          console.error('[file-watcher] Error processing change:', err.message);
+        }
+      }, debounceMs)
+    );
+  };
+
+  try {
+    watcher = chokidar.watch(rootDir, {
+      ignored: [/\.bak$/, /\.lock$/, /\.tmp-/, /(^|[/\\])\../, /node_modules/],
+      ignoreInitial: true,
+      persistent: true,
+    });
+
+    watcher
+      .on('add', (path) => onEvent('add', path))
+      .on('change', (path) => onEvent('change', path))
+      .on('unlink', (path) => onEvent('unlink', path));
+  } catch (err) {
+    console.error('[file-watcher] Failed to start watcher:', err.message);
+  }
+
+  return {
+    async stop() {
+      for (const timer of debounceTimers.values()) {
+        clearTimeout(timer);
+      }
+      debounceTimers.clear();
+      if (watcher) {
+        await watcher.close();
+        watcher = null;
+      }
+    },
+  };
+}

package/cli/kanban/server/services/file-writer.js

@@ -0,0 +1,107 @@
+import { open, rename, copyFile, unlink, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseFile, stringify } from './frontmatter.js';
+
+/**
+ * Atomic update of a Markdown file's frontmatter.
+ *
+ * Safety :
+ *   1. Exclusive lock file (<path>.lock, O_CREAT|O_EXCL) — refuses concurrent writes.
+ *   2. Optional mtime check (ETag-like) — rejects writes if file changed on disk.
+ *   3. Backup (<path>.bak) — restored if the write fails.
+ *   4. Write to a temp file then rename — atomic on POSIX.
+ *   5. Body of the markdown file is preserved byte-for-byte.
+ */
+
+class LockedError extends Error {
+  constructor(filepath) {
+    super(`File is locked: ${filepath}`);
+    this.code = 'LOCKED';
+  }
+}
+
+class MtimeMismatchError extends Error {
+  constructor(filepath, expected, actual) {
+    super(`mtime mismatch for ${filepath}: expected ${expected}, got ${actual}`);
+    this.code = 'MTIME_MISMATCH';
+  }
+}
+
+async function acquireLock(filepath) {
+  const lockPath = `${filepath}.lock`;
+  try {
+    const fd = await open(lockPath, 'wx');
+    await fd.close();
+    return lockPath;
+  } catch (err) {
+    if (err.code === 'EEXIST') throw new LockedError(filepath);
+    throw err;
+  }
+}
+
+async function releaseLock(lockPath) {
+  try {
+    await unlink(lockPath);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * @param {string} filepath
+ * @param {object} patch - partial frontmatter to merge
+ * @param {object} [opts]
+ * @param {number} [opts.expectedMtime] - if provided, write only if current mtime matches
+ * @returns {Promise<{ data: object, body: string, mtime: number }>}
+ */
+export async function updateFrontmatter(filepath, patch, opts = {}) {
+  const abs = path.resolve(filepath);
+  const lockPath = await acquireLock(abs);
+  const backup = `${abs}.bak`;
+  try {
+    if (typeof opts.expectedMtime === 'number') {
+      const st = await stat(abs);
+      if (st.mtimeMs !== opts.expectedMtime) {
+        throw new MtimeMismatchError(abs, opts.expectedMtime, st.mtimeMs);
+      }
+    }
+
+    const { data, body } = await parseFile(abs);
+    await copyFile(abs, backup);
+
+    const merged = { ...data, ...patch };
+    const next = stringify(merged, body);
+    const tmp = `${abs}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      await writeFile(tmp, next, 'utf8');
+      await rename(tmp, abs);
+    } catch (err) {
+      // Rollback from backup
+      try {
+        await copyFile(backup, abs);
+      } catch {
+        /* best effort */
+      }
+      try {
+        await unlink(tmp);
+      } catch {
+        /* ignore */
+      }
+      throw err;
+    }
+    await unlink(backup);
+    const st = await stat(abs);
+    return { data: merged, body, mtime: st.mtimeMs };
+  } catch (err) {
+    try {
+      await unlink(backup);
+    } catch {
+      /* backup may not exist yet */
+    }
+    throw err;
+  } finally {
+    await releaseLock(lockPath);
+  }
+}
+
+export { LockedError, MtimeMismatchError };

package/cli/kanban/server/services/frontmatter.js

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+import matter from 'gray-matter';
+
+/**
+ * Parse a Markdown file with YAML frontmatter.
+ * Returns { data, body, raw } where `data` is the parsed frontmatter,
+ * `body` is everything after the second '---', and `raw` is the full file.
+ *
+ * gray-matter handles missing frontmatter gracefully (returns data = {}).
+ *
+ * @param {string} filepath
+ * @returns {Promise<{ data: object, body: string, raw: string }>}
+ */
+export async function parseFile(filepath) {
+  const raw = await readFile(filepath, 'utf8');
+  return parseString(raw);
+}
+
+/**
+ * Parse a Markdown string with YAML frontmatter.
+ */
+export function parseString(raw) {
+  const { data, content } = matter(raw);
+  return { data: data ?? {}, body: content ?? '', raw };
+}
+
+/**
+ * Serialize frontmatter + body back to a Markdown string.
+ * Uses gray-matter's stringify which preserves YAML canonical format.
+ *
+ * @param {object} data
+ * @param {string} body
+ * @returns {string}
+ */
+export function stringify(data, body) {
+  return matter.stringify(body ?? '', data ?? {});
+}
+
+/**
+ * Parse and validate frontmatter against a Zod schema.
+ * @param {string} filepath
+ * @param {import('zod').ZodTypeAny} schema
+ * @returns {Promise<{ ok: true, data: object, body: string } | { ok: false, errors: Array, body: string, raw: any }>}
+ */
+export async function parseAndValidate(filepath, schema) {
+  const { data, body } = await parseFile(filepath);
+  const result = schema.safeParse(data);
+  if (result.success) return { ok: true, data: result.data, body };
+  return {
+    ok: false,
+    errors: result.error.issues,
+    body,
+    raw: data,
+  };
+}