@ikunin/sprintpilot 1.0.5 → 2.0.4

package/_Sprintpilot/scripts/log-timing.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+
+// log-timing.js — append a timing event to a per-story JSONL shard.
+//
+// Usage:
+//   log-timing.js <action> --story <key> --phase <name> [--meta <json>]
+//
+// Actions:
+//   start   Emit {event:"start", story, phase, ts:<iso8601>}
+//   end     Emit {event:"end",   story, phase, ts:<iso8601>}
+//   once    Emit a single-event marker (for things like health-check-run)
+//   mark    Single-call replacement for start/end pairs. Reads a tiny
+//           marker file (.timings/.mark.json), computes the duration
+//           since the previous mark, emits one duration record for the
+//           PREVIOUS phase, and writes a new marker for the current
+//           phase. Designed for LLM-driven workflows where the agent
+//           may forget to call `end` after a long skill — `mark` only
+//           needs to be called ONCE per phase transition.
+//
+// Output path:
+//   <project-root>/_bmad-output/implementation-artifacts/.timings/<story>.jsonl
+//   Append-only, one writer per story-key = one sub-agent in the autopilot
+//   model. Each line is JSON, < LINE_MAX_BYTES so a single write() is
+//   atomic on POSIX (PIPE_BUF >= 4096 on every supported platform).
+//
+// No-op contract:
+//   If the resolved profile has autopilot.phase_timings !== true, the
+//   script silently returns without creating files. This is the
+//   rollback path for PR 2 and the permanent behavior for the `legacy`
+//   profile.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+// Path-traversal guard: a story key is part of the filename, so it must
+// not contain slashes, dots, or other shell-significant characters.
+const STORY_RE = /^[a-z0-9][a-z0-9-]*$/;
+// Phase names follow a dotted-namespace convention (skill.bmad-dev-story).
+const PHASE_RE = /^[a-z][a-z0-9-.]*$/;
+const META_MAX_BYTES = 2048;
+const LINE_MAX_BYTES = 4096; // POSIX PIPE_BUF floor — single write() is atomic
+const VALID_ACTIONS = ['start', 'end', 'once', 'mark'];
+const MARKER_FILE = '.mark.json';
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  log-timing.js <action> --story <key> --phase <name> [--meta <json>]',
+      '',
+      'Actions: start | end | once',
+      '',
+      'Options:',
+      '  --project-root <path>   Defaults to cwd',
+      '  --story <key>           Matches /^[a-z0-9][a-z0-9-]*$/',
+      '  --phase <name>          Matches /^[a-z][a-z0-9-.]*$/',
+      '  --meta <json>           Inline JSON, serialized < 2KB',
+    ].join('\n'),
+  );
+}
+
+function validateStory(s) {
+  if (s === undefined || s === null || s === '') {
+    return { ok: false, error: '--story is required' };
+  }
+  if (!STORY_RE.test(s)) {
+    return { ok: false, error: `invalid --story '${s}': must match ${STORY_RE}` };
+  }
+  return { ok: true, value: s };
+}
+
+function validatePhase(s) {
+  if (s === undefined || s === null || s === '') {
+    return { ok: false, error: '--phase is required' };
+  }
+  if (!PHASE_RE.test(s)) {
+    return { ok: false, error: `invalid --phase '${s}': must match ${PHASE_RE}` };
+  }
+  return { ok: true, value: s };
+}
+
+function validateAction(a) {
+  if (!VALID_ACTIONS.includes(a)) {
+    return { ok: false, error: `invalid action '${a}': must be one of ${VALID_ACTIONS.join(', ')}` };
+  }
+  return { ok: true, value: a };
+}
+
+function validateMeta(metaJson) {
+  if (metaJson === undefined) return { ok: true, value: undefined };
+  let parsed;
+  try {
+    parsed = JSON.parse(metaJson);
+  } catch (e) {
+    return { ok: false, error: `--meta is not valid JSON: ${e.message}` };
+  }
+  const serialized = JSON.stringify(parsed);
+  const bytes = Buffer.byteLength(serialized, 'utf8');
+  if (bytes > META_MAX_BYTES) {
+    return {
+      ok: false,
+      error: `--meta exceeds ${META_MAX_BYTES} bytes after serialization (got ${bytes})`,
+    };
+  }
+  return { ok: true, value: parsed };
+}
+
+function timingsDir(projectRoot) {
+  return path.join(projectRoot, '_bmad-output', 'implementation-artifacts', '.timings');
+}
+
+function readPhaseTimingSetting(projectRoot) {
+  const profilesDir = path.join(projectRoot, '_Sprintpilot', 'modules', 'autopilot', 'profiles');
+  if (!fs.existsSync(profilesDir)) return false;
+  const pick = (raw) => {
+    const m = raw.match(/^[ \t]*phase_timings:[ \t]*(true|false)[ \t]*(?:#.*)?$/m);
+    return m ? m[1] === 'true' : null;
+  };
+
+  const cfgPath = path.join(projectRoot, '_Sprintpilot', 'modules', 'autopilot', 'config.yaml');
+  if (fs.existsSync(cfgPath)) {
+    const override = pick(fs.readFileSync(cfgPath, 'utf8'));
+    if (override !== null) return override;
+  }
+
+  let profileName = 'medium';
+  if (fs.existsSync(cfgPath)) {
+    const raw = fs.readFileSync(cfgPath, 'utf8');
+    const m = raw.match(/^[ \t]*complexity_profile:[ \t]*["']?([a-zA-Z_-]+)["']?[ \t]*(?:#.*)?$/m);
+    if (m) profileName = m[1];
+  }
+
+  const profileFile = path.join(profilesDir, `${profileName}.yaml`);
+  if (fs.existsSync(profileFile)) {
+    const val = pick(fs.readFileSync(profileFile, 'utf8'));
+    if (val !== null) return val;
+  }
+
+  // Non-legacy profiles inherit from _base. Legacy stands alone — if its
+  // own file didn't declare the key (shouldn't happen), we fall through
+  // to `false` (fail-safe — never write silently).
+  if (profileName !== 'legacy') {
+    const baseFile = path.join(profilesDir, '_base.yaml');
+    if (fs.existsSync(baseFile)) {
+      const val = pick(fs.readFileSync(baseFile, 'utf8'));
+      if (val !== null) return val;
+    }
+  }
+
+  return false;
+}
+
+function isEnabled(projectRoot) {
+  try {
+    return readPhaseTimingSetting(projectRoot) === true;
+  } catch {
+    return false;
+  }
+}
+
+function appendLine(projectRoot, story, entry) {
+  const dir = timingsDir(projectRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify(entry);
+  const bytes = Buffer.byteLength(`${line}\n`, 'utf8');
+  if (bytes > LINE_MAX_BYTES) {
+    throw new Error(
+      `timing line exceeds ${LINE_MAX_BYTES} bytes (${bytes}); refusing to write a non-atomic record`,
+    );
+  }
+  const file = path.join(dir, `${story}.jsonl`);
+  fs.appendFileSync(file, `${line}\n`);
+  return file;
+}
+
+function buildEntry(action, story, phase, meta) {
+  const entry = {
+    event: action,
+    story,
+    phase,
+    ts: new Date().toISOString(),
+  };
+  if (meta !== undefined) entry.meta = meta;
+  return entry;
+}
+
+// ---------------------------------------------------------------
+// `mark` — single-call timing
+// ---------------------------------------------------------------
+
+function markerPath(projectRoot) {
+  return path.join(timingsDir(projectRoot), MARKER_FILE);
+}
+
+function readMarker(projectRoot) {
+  const file = markerPath(projectRoot);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      typeof parsed.story === 'string' &&
+      typeof parsed.phase === 'string' &&
+      typeof parsed.ts === 'string'
+    ) {
+      return parsed;
+    }
+  } catch {
+    /* corrupt marker — treat as absent */
+  }
+  return null;
+}
+
+function writeMarker(projectRoot, marker) {
+  const dir = timingsDir(projectRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = markerPath(projectRoot);
+  // Atomic-ish: write tmp + rename. Marker is small, single-line JSON.
+  const tmp = `${file}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(marker));
+  fs.renameSync(tmp, file);
+}
+
+function clearMarker(projectRoot) {
+  const file = markerPath(projectRoot);
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * mark: single-call timing API.
+ *
+ * Emits a duration record for the PREVIOUS phase (if any) covering the
+ * interval since the previous mark, then writes a new marker for the
+ * current phase. The very first mark in a session emits no duration
+ * record — there's no "previous phase" yet.
+ *
+ * Use phase = "_end" to close the last open phase without starting a new
+ * one (e.g. at sprint-complete time).
+ *
+ * Returns { duration_ms, prev_phase } so callers can log/inspect.
+ */
+function markPhase(projectRoot, story, phase, meta) {
+  const now = new Date();
+  const prev = readMarker(projectRoot);
+  let durationMs = null;
+  let prevPhase = null;
+  if (prev) {
+    const prevTs = Date.parse(prev.ts);
+    if (!Number.isNaN(prevTs)) {
+      durationMs = now.getTime() - prevTs;
+      prevPhase = prev.phase;
+      const durationEntry = {
+        event: 'duration',
+        story: prev.story,
+        phase: prev.phase,
+        started: prev.ts,
+        ended: now.toISOString(),
+        duration_ms: durationMs,
+      };
+      if (prev.meta !== undefined) durationEntry.meta = prev.meta;
+      appendLine(projectRoot, prev.story, durationEntry);
+    }
+  }
+  if (phase === '_end') {
+    clearMarker(projectRoot);
+  } else {
+    const marker = { story, phase, ts: now.toISOString() };
+    if (meta !== undefined) marker.meta = meta;
+    writeMarker(projectRoot, marker);
+  }
+  return { duration_ms: durationMs, prev_phase: prevPhase };
+}
+
+function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+  if (opts.help || positional.length === 0) {
+    help();
+    process.exit(opts.help ? 0 : 1);
+  }
+
+  const action = validateAction(positional[0]);
+  if (!action.ok) {
+    log.error(action.error);
+    process.exit(1);
+  }
+  const story = validateStory(opts.story);
+  if (!story.ok) {
+    log.error(story.error);
+    process.exit(1);
+  }
+  // `mark _end` is a sentinel that closes the last open phase without
+  // starting a new one. Skip the regex check for it; everything else
+  // must match PHASE_RE.
+  const phase =
+    action.value === 'mark' && opts.phase === '_end'
+      ? { ok: true, value: '_end' }
+      : validatePhase(opts.phase);
+  if (!phase.ok) {
+    log.error(phase.error);
+    process.exit(1);
+  }
+  const meta = validateMeta(opts.meta);
+  if (!meta.ok) {
+    log.error(meta.error);
+    process.exit(1);
+  }
+
+  const projectRoot = opts['project-root'] || process.cwd();
+  if (!isEnabled(projectRoot)) return;
+
+  try {
+    if (action.value === 'mark') {
+      const r = markPhase(projectRoot, story.value, phase.value, meta.value);
+      // Emit a brief JSON line so callers can log the duration if useful.
+      // Stdout is intentionally separate from the per-story shard.
+      process.stdout.write(`${JSON.stringify({ marked: phase.value, prev_phase: r.prev_phase, duration_ms: r.duration_ms })}\n`);
+      return;
+    }
+    appendLine(projectRoot, story.value, buildEntry(action.value, story.value, phase.value, meta.value));
+  } catch (e) {
+    log.error(`timing write failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  STORY_RE,
+  PHASE_RE,
+  META_MAX_BYTES,
+  LINE_MAX_BYTES,
+  MARKER_FILE,
+  VALID_ACTIONS,
+  validateStory,
+  validatePhase,
+  validateAction,
+  validateMeta,
+  timingsDir,
+  markerPath,
+  readMarker,
+  writeMarker,
+  clearMarker,
+  markPhase,
+  readPhaseTimingSetting,
+  isEnabled,
+  appendLine,
+  buildEntry,
+};
+
+if (require.main === module) {
+  main();
+}

package/_Sprintpilot/scripts/mark-done-stories-tasks.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+// mark-done-stories-tasks.js — final pass that replaces `- [ ]` with `- [x]`
+// in every story file whose status is "done" in sprint-status.yaml.
+//
+// Usage:
+//   mark-done-stories-tasks.js --status-file <path> [--project-root <path>]
+//                              [--output-folder <path>]
+//
+// Rationale: bmad-dev-story is supposed to check off its Tasks/Subtasks as
+// it implements each story, and workflow.md's step 7 has an explicit
+// "Mark all task checkboxes complete" action. Both are LLM-executed
+// instructions that the autopilot sometimes skips in long sessions. This
+// helper is the final deterministic safety net — it runs from step 10's
+// critical path and brings the filesystem state in line with sprint-status.
+//
+// Story file lookup: honors BMad's `output_folder` config
+// (_bmad/bmm/config.yaml). Resolves in this order:
+//   <output-folder>/stories/story-<key>.md
+//   <output-folder>/implementation-artifacts/story-<key>.md
+//   <output-folder>/stories/<key>.md
+//   <output-folder>/implementation-artifacts/<key>.md
+//
+// Checkbox replacement is fenced-code-aware: `- [ ]` inside triple-backtick
+// or triple-tilde blocks is NOT rewritten, because story templates commonly
+// show example task lists that must round-trip verbatim.
+//
+// Writes are durable-atomic: write to tmp, fsync tmp, rename, fsync parent
+// directory. A crash between rename and flush cannot leave a zero-byte
+// story file.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+const { parseStatuses, isDone } = require('./list-remaining-stories.js');
+const timing = require('./log-timing.js');
+
+// Best-effort auto-emit: surfaces a timing event so that callers don't
+// have to wrap every CRITICAL invocation in start/end pairs the LLM
+// might skip. Silent no-op if phase_timings is disabled or anything
+// throws — never affects the script's primary outcome.
+function emitTimingEvent(projectRoot, phase, meta) {
+  try {
+    if (!timing.isEnabled(projectRoot)) return;
+    timing.appendLine(projectRoot, 'sprint', timing.buildEntry('once', 'sprint', phase, meta));
+  } catch {
+    /* ignore */
+  }
+}
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  mark-done-stories-tasks.js --status-file <path> [--project-root <path>]',
+      '                             [--output-folder <path>]',
+      '',
+      'For every story with status="done" (case-insensitive), replaces every',
+      '`- [ ]` with `- [x]` in its story markdown file. Fenced code blocks',
+      'are preserved verbatim. Emits JSON summary to stdout.',
+    ].join('\n'),
+  );
+}
+
+// Read BMad's output_folder from _bmad/bmm/config.yaml if present. Returns
+// the folder name (relative to projectRoot) or null if not configurable.
+function readOutputFolder(projectRoot) {
+  const cfg = path.join(projectRoot, '_bmad', 'bmm', 'config.yaml');
+  if (!fs.existsSync(cfg)) return null;
+  try {
+    const body = fs.readFileSync(cfg, 'utf8');
+    const m = body.match(/^output_folder\s*:\s*(\S+)/m);
+    if (!m) return null;
+    return m[1].replace(/^["']|["']$/g, '').trim();
+  } catch {
+    return null;
+  }
+}
+
+function findStoryFile(projectRoot, storyKey, outputFolder) {
+  const folder = outputFolder || readOutputFolder(projectRoot) || '_bmad-output';
+  const candidates = [
+    path.join(projectRoot, folder, 'stories', `story-${storyKey}.md`),
+    path.join(projectRoot, folder, 'implementation-artifacts', `story-${storyKey}.md`),
+    path.join(projectRoot, folder, 'stories', `${storyKey}.md`),
+    path.join(projectRoot, folder, 'implementation-artifacts', `${storyKey}.md`),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+// Line-by-line replacement that tracks fenced code blocks. Inside ``` or
+// ~~~ blocks the original line is emitted verbatim. Outside, `- [ ]` (or
+// `* [ ]`) at any indent is rewritten to `- [x]`.
+//
+// Fence detection: a line whose first non-whitespace characters are ```
+// or ~~~ toggles the fenced state. Info strings after the opener (e.g.
+// ```ts) are allowed. Only the fence character is significant.
+function markAllTasksChecked(body) {
+  const lines = String(body).split('\n');
+  const out = new Array(lines.length);
+  let inFence = false;
+  let fenceChar = null;
+  const fenceOpenRe = /^\s*(`{3,}|~{3,})/;
+  const taskRe = /^(\s*[-*]\s*)\[ \](\s*)/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = line.match(fenceOpenRe);
+    if (fence) {
+      const ch = fence[1][0];
+      if (!inFence) {
+        inFence = true;
+        fenceChar = ch;
+      } else if (fenceChar === ch) {
+        inFence = false;
+        fenceChar = null;
+      }
+      out[i] = line;
+      continue;
+    }
+    if (inFence) {
+      out[i] = line;
+      continue;
+    }
+    out[i] = line.replace(taskRe, (_m, pre, post) => `${pre}[x]${post}`);
+  }
+  return out.join('\n');
+}
+
+// Durable-atomic write: tmp → fsync(tmp) → rename → fsync(parent dir).
+// Preserves file mode of the existing target if possible.
+function atomicWrite(file, body) {
+  const dir = path.dirname(file);
+  const tmp = path.join(
+    dir,
+    `.${path.basename(file)}.tmp.${process.pid}.${process.hrtime.bigint().toString(36)}`,
+  );
+  let mode;
+  try {
+    mode = fs.statSync(file).mode;
+  } catch {
+    /* new file — leave mode unset */
+  }
+
+  const fd = fs.openSync(tmp, 'w', mode ?? 0o644);
+  try {
+    fs.writeFileSync(fd, body);
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      /* fsync not supported on this fs — best-effort */
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  // Best-effort directory fsync so the rename itself is durable. Skipped on
+  // Windows where fs.openSync(<dir>, 'r') throws EISDIR/EPERM — there's no
+  // documented way to fsync a directory handle. The rename itself is still
+  // atomic on NTFS, just not flushed to disk on power loss the way fsync
+  // would guarantee on POSIX.
+  if (process.platform !== 'win32') {
+    try {
+      const dfd = fs.openSync(dir, 'r');
+      try {
+        fs.fsyncSync(dfd);
+      } finally {
+        fs.closeSync(dfd);
+      }
+    } catch {
+      /* directory fsync unsupported on some filesystems — ignore */
+    }
+  }
+}
+
+function main() {
+  const { opts } = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    help();
+    process.exit(0);
+  }
+  const statusFile = opts['status-file'];
+  if (!statusFile) {
+    log.error('--status-file is required');
+    process.exit(1);
+  }
+  if (!fs.existsSync(statusFile)) {
+    log.error(`status file missing: ${statusFile}`);
+    process.exit(2);
+  }
+  const projectRoot = opts['project-root'] || process.cwd();
+  const outputFolder = opts['output-folder'] || null;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(statusFile, 'utf8');
+  } catch (e) {
+    log.error(`cannot read ${statusFile}: ${e.message}`);
+    process.exit(1);
+  }
+
+  const stories = parseStatuses(raw);
+  const doneKeys = Object.keys(stories).filter((k) => isDone(stories[k].status));
+
+  const summary = {
+    done_stories: doneKeys.length,
+    marked: [],
+    missing_files: [],
+    unchanged: [],
+  };
+
+  for (const key of doneKeys) {
+    const file = findStoryFile(projectRoot, key, outputFolder);
+    if (!file) {
+      summary.missing_files.push(key);
+      continue;
+    }
+    const body = fs.readFileSync(file, 'utf8');
+    const marked = markAllTasksChecked(body);
+    if (marked === body) {
+      summary.unchanged.push(key);
+      continue;
+    }
+    try {
+      atomicWrite(file, marked);
+      summary.marked.push({ key, file });
+    } catch (e) {
+      log.warn(`failed to mark ${file}: ${e.message}`);
+    }
+  }
+
+  emitTimingEvent(projectRoot, 'cleanup.mark-done-tasks', {
+    done_stories: summary.done_stories,
+    marked: summary.marked.length,
+    missing_files: summary.missing_files.length,
+  });
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+module.exports = {
+  findStoryFile,
+  markAllTasksChecked,
+  atomicWrite,
+  readOutputFolder,
+};
+
+if (require.main === module) {
+  main();
+}