@ikunin/sprintpilot 1.0.5 → 2.0.5

package/_Sprintpilot/scripts/cached-read.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+// cached-read.js — TTL + mtime-aware file cache for the autopilot loop.
+//
+// Usage:
+//   cached-read.js read     --file <path> [--ttl <ms>] [--cache-root <path>]
+//   cached-read.js invalidate --file <path> [--cache-root <path>]
+//   cached-read.js clear      [--cache-root <path>]
+//   cached-read.js stats      [--cache-root <path>]
+//
+// Rationale (PR 8 / M5):
+//   workflow.md re-reads sprint-status.yaml, git-status.yaml, and
+//   decision-log.yaml at many step boundaries. A single loop iteration
+//   can read each one 5+ times. This helper memoizes the reads to a
+//   per-project cache directory, respecting TTL AND source-file mtime
+//   so a write always invalidates the cache even if the caller forgets
+//   to call `invalidate` explicitly.
+//
+// Cache layout:
+//   <cache-root>/.cache/cached-reads/<sha256(file)>.json
+//     { source, mtime_ms, cached_at, body }
+//
+// Consumer gate:
+//   Callers should gate use of this script on `autopilot.cache_shared_reads`
+//   via resolve-profile.js. When the flag is false, read the file directly.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const DEFAULT_TTL_MS = 60_000;
+const VALID_ACTIONS = ['read', 'invalidate', 'clear', 'stats'];
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  cached-read.js read --file <path> [--ttl <ms>] [--cache-root <path>]',
+      '  cached-read.js invalidate --file <path> [--cache-root <path>]',
+      '  cached-read.js clear  [--cache-root <path>]',
+      '  cached-read.js stats  [--cache-root <path>]',
+      '',
+      `Default TTL: ${DEFAULT_TTL_MS}ms. Source-file mtime always invalidates.`,
+    ].join('\n'),
+  );
+}
+
+function cacheDir(cacheRoot) {
+  return path.join(cacheRoot, '.cache', 'cached-reads');
+}
+
+function keyFor(filePath) {
+  return crypto.createHash('sha256').update(path.resolve(filePath)).digest('hex').slice(0, 32);
+}
+
+function cacheEntryPath(cacheRoot, filePath) {
+  return path.join(cacheDir(cacheRoot), `${keyFor(filePath)}.json`);
+}
+
+function readFileStat(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return { exists: true, mtime_ms: stat.mtimeMs };
+  } catch {
+    return { exists: false, mtime_ms: 0 };
+  }
+}
+
+function readFromCache(cacheRoot, filePath, ttlMs) {
+  const entryFile = cacheEntryPath(cacheRoot, filePath);
+  if (!fs.existsSync(entryFile)) return { hit: false, reason: 'miss' };
+  let entry;
+  try {
+    entry = JSON.parse(fs.readFileSync(entryFile, 'utf8'));
+  } catch {
+    return { hit: false, reason: 'corrupt' };
+  }
+  const now = Date.now();
+  // ttlMs=0 means "always miss" (bypass); >= (not >) ensures that.
+  if (now - entry.cached_at >= ttlMs) return { hit: false, reason: 'ttl-expired' };
+  const srcStat = readFileStat(filePath);
+  if (!srcStat.exists) return { hit: false, reason: 'source-gone' };
+  if (srcStat.mtime_ms > entry.mtime_ms) return { hit: false, reason: 'source-newer' };
+  return { hit: true, body: entry.body, entry };
+}
+
+function writeToCache(cacheRoot, filePath, body) {
+  const dir = cacheDir(cacheRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  const srcStat = readFileStat(filePath);
+  const entry = {
+    source: path.resolve(filePath),
+    mtime_ms: srcStat.mtime_ms,
+    cached_at: Date.now(),
+    body,
+  };
+  const file = cacheEntryPath(cacheRoot, filePath);
+  const tmp = `${file}.tmp.${process.pid}.${process.hrtime.bigint().toString(36)}`;
+  fs.writeFileSync(tmp, JSON.stringify(entry));
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function readThrough(cacheRoot, filePath, ttlMs) {
+  const hit = readFromCache(cacheRoot, filePath, ttlMs);
+  if (hit.hit) return { body: hit.body, hit: true, source: filePath };
+  // Cache miss — read through.
+  if (!fs.existsSync(filePath)) {
+    return { body: null, hit: false, source: filePath, reason: hit.reason || 'missing' };
+  }
+  const body = fs.readFileSync(filePath, 'utf8');
+  writeToCache(cacheRoot, filePath, body);
+  return { body, hit: false, source: filePath, reason: hit.reason };
+}
+
+function invalidate(cacheRoot, filePath) {
+  const file = cacheEntryPath(cacheRoot, filePath);
+  try {
+    fs.unlinkSync(file);
+    return { cleared: true };
+  } catch {
+    return { cleared: false };
+  }
+}
+
+function clearAll(cacheRoot) {
+  const dir = cacheDir(cacheRoot);
+  if (!fs.existsSync(dir)) return { cleared: 0 };
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  let cleared = 0;
+  for (const f of files) {
+    try {
+      fs.unlinkSync(path.join(dir, f));
+      cleared++;
+    } catch {
+      /* best effort */
+    }
+  }
+  return { cleared };
+}
+
+function stats(cacheRoot) {
+  const dir = cacheDir(cacheRoot);
+  if (!fs.existsSync(dir)) return { entries: 0, oldest_age_ms: null, newest_age_ms: null };
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const now = Date.now();
+  let oldest = Infinity;
+  let newest = 0;
+  for (const f of files) {
+    try {
+      const entry = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      const age = now - entry.cached_at;
+      if (age < oldest) oldest = age;
+      if (age > newest) newest = age;
+    } catch {
+      /* skip corrupt */
+    }
+  }
+  return {
+    entries: files.length,
+    oldest_age_ms: files.length ? oldest : null,
+    newest_age_ms: files.length ? newest : null,
+  };
+}
+
+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 = positional[0];
+  if (!VALID_ACTIONS.includes(action)) {
+    log.error(`unknown action '${action}'. Valid: ${VALID_ACTIONS.join(', ')}`);
+    process.exit(1);
+  }
+  const cacheRoot = opts['cache-root'] || process.cwd();
+  const filePath = opts.file;
+  const ttlMs = opts.ttl !== undefined ? Number.parseInt(String(opts.ttl), 10) : DEFAULT_TTL_MS;
+  if (Number.isNaN(ttlMs) || ttlMs < 0) {
+    log.error(`invalid --ttl '${opts.ttl}': must be a non-negative integer (ms)`);
+    process.exit(1);
+  }
+
+  if (action === 'read') {
+    if (!filePath) {
+      log.error('--file is required for read');
+      process.exit(1);
+    }
+    const out = readThrough(cacheRoot, filePath, ttlMs);
+    if (out.body === null) {
+      log.error(`source missing: ${filePath}`);
+      process.exit(2);
+    }
+    process.stdout.write(out.body);
+    return;
+  }
+  if (action === 'invalidate') {
+    if (!filePath) {
+      log.error('--file is required for invalidate');
+      process.exit(1);
+    }
+    const r = invalidate(cacheRoot, filePath);
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+    return;
+  }
+  if (action === 'clear') {
+    const r = clearAll(cacheRoot);
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+    return;
+  }
+  if (action === 'stats') {
+    const r = stats(cacheRoot);
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+  }
+}
+
+module.exports = {
+  DEFAULT_TTL_MS,
+  VALID_ACTIONS,
+  cacheDir,
+  keyFor,
+  cacheEntryPath,
+  readFileStat,
+  readFromCache,
+  writeToCache,
+  readThrough,
+  invalidate,
+  clearAll,
+  stats,
+};
+
+if (require.main === module) {
+  main();
+}

package/_Sprintpilot/scripts/check-prereqs.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+// check-prereqs.js — verify Sprintpilot v2's environment prerequisites.
+//
+// Exit codes:
+//   0 — all prereqs met (may include a warning for degraded mode)
+//   1 — hard failure (user must resolve before continuing)
+//
+// Checks:
+//   - Node >= 18 (package.json engines)
+//   - Git >= 2.18 required for submodule --jobs / --reference (PR 10).
+//     Git 2.5.0–2.17 works in degraded mode (no submodule speedup) —
+//     emits a warning on stderr but exits 0.
+
+const { execFileSync } = require('node:child_process');
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const MIN_NODE = [18, 0, 0];
+const MIN_GIT_STRICT = [2, 18, 0]; // submodule --jobs / --reference
+const MIN_GIT_SOFT = [2, 5, 0]; // worktree basics
+
+function help() {
+  log.out('Usage: check-prereqs.js [--min-git <semver>]');
+}
+
+function parseSemver(str) {
+  // Accept "2.18.0", "2.18", "git version 2.39.3 (Apple Git-145)", etc.
+  const m = String(str).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!m) return null;
+  return [
+    Number.parseInt(m[1], 10),
+    Number.parseInt(m[2], 10),
+    m[3] ? Number.parseInt(m[3], 10) : 0,
+  ];
+}
+
+function cmp(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+function fmt(v) {
+  return `${v[0]}.${v[1]}.${v[2]}`;
+}
+
+function checkNode() {
+  const v = parseSemver(process.version);
+  if (!v) {
+    log.error(`unable to parse node version '${process.version}'`);
+    return { ok: false };
+  }
+  if (cmp(v, MIN_NODE) < 0) {
+    log.error(`node ${fmt(v)} is too old; need >= ${fmt(MIN_NODE)}. Upgrade node.`);
+    return { ok: false };
+  }
+  return { ok: true, version: fmt(v) };
+}
+
+function readGitVersion() {
+  // execFileSync (not exec) — no shell, no injection surface.
+  try {
+    const out = execFileSync('git', ['--version'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    }).trim();
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+function checkGit(minStrictArg) {
+  const raw = readGitVersion();
+  if (!raw) {
+    log.error('git not found on PATH. Install git >= 2.18 (or 2.5 for degraded mode).');
+    return { ok: false };
+  }
+  const v = parseSemver(raw);
+  if (!v) {
+    log.warn(`unable to parse git version string: ${raw}`);
+    return { ok: true, version: raw, degraded: true };
+  }
+  const minStrict = minStrictArg ? parseSemver(minStrictArg) : MIN_GIT_STRICT;
+  if (cmp(v, minStrict) >= 0) {
+    return { ok: true, version: fmt(v), degraded: false };
+  }
+  if (cmp(v, MIN_GIT_SOFT) >= 0) {
+    log.warn(
+      `git ${fmt(v)} is below recommended ${fmt(minStrict)}. Degraded mode: submodule speedups disabled (PR 10 features).`,
+    );
+    return { ok: true, version: fmt(v), degraded: true };
+  }
+  log.error(
+    `git ${fmt(v)} is too old; need >= ${fmt(MIN_GIT_SOFT)} minimum (${fmt(minStrict)} recommended).`,
+  );
+  return { ok: false, version: fmt(v) };
+}
+
+function main() {
+  const { opts } = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    help();
+    process.exit(0);
+  }
+
+  const node = checkNode();
+  if (!node.ok) process.exit(1);
+
+  const git = checkGit(opts['min-git']);
+  if (!git.ok) process.exit(1);
+
+  // Summary on stdout for scripting consumers.
+  const summary = {
+    node: node.version,
+    git: git.version,
+    git_degraded: git.degraded || false,
+  };
+  process.stdout.write(JSON.stringify(summary) + '\n');
+  process.exit(0);
+}
+
+module.exports = {
+  checkNode,
+  checkGit,
+  parseSemver,
+  cmp,
+  fmt,
+  MIN_NODE,
+  MIN_GIT_STRICT,
+  MIN_GIT_SOFT,
+};
+
+if (require.main === module) {
+  main();
+}

package/_Sprintpilot/scripts/dispatch-layer.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+
+// dispatch-layer.js — orchestrator for parallel intra-epic story execution.
+//
+// Usage:
+//   dispatch-layer.js --layer <key,key,...> [--max-parallel <n>]
+//                     [--project-root <path>] [--branch-prefix <str>]
+//                     [--base-branch <br>] [--dry-run]
+//
+// Responsibilities:
+//   1. For each story in --layer (respecting --max-parallel concurrency),
+//      create the story's worktree and branch. Worktree creation itself
+//      happens synchronously (cheap after PR 10); actual sub-agent spawn
+//      is delegated to the host agent via a plan file the host reads.
+//   2. Emit a plan.json to the project at
+//        _bmad-output/implementation-artifacts/.layer-plan.json
+//      that the host workflow then consumes — invoking N sub-agents, one
+//      per story, pointing each at its worktree + branch.
+//   3. When the host reports back (all sub-agents complete), the top-level
+//      workflow invokes `merge-shards.js --archive --layer <id>` to merge
+//      each story's state shard into the authoritative project YAML.
+//
+// This script itself does NOT call an LLM. Host-specific multi-agent
+// dispatch is up to workflow.md (gated on agent-adapter.js's confidence).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const STORY_RE = /^[a-z0-9][a-z0-9-]*$/;
+const PLAN_FILENAME = '.layer-plan.json';
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  dispatch-layer.js --layer <key,key,...> [options]',
+      '',
+      'Options:',
+      '  --max-parallel N    Upper bound on concurrent sub-agents (default 2).',
+      '  --project-root P    Defaults to cwd.',
+      '  --branch-prefix S   Branch name prefix (default story/).',
+      '  --base-branch B     Branch point (default main).',
+      '  --dry-run           Compute the plan but do not create worktrees.',
+    ].join('\n'),
+  );
+}
+
+function parseLayer(raw) {
+  if (!raw) return { ok: false, error: '--layer is required' };
+  const keys = String(raw).split(',').map((s) => s.trim()).filter(Boolean);
+  for (const k of keys) {
+    if (!STORY_RE.test(k)) {
+      return { ok: false, error: `invalid story key '${k}': must match ${STORY_RE}` };
+    }
+  }
+  if (keys.length === 0) {
+    return { ok: false, error: '--layer must contain at least one story key' };
+  }
+  return { ok: true, value: keys };
+}
+
+function planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch }) {
+  const effectiveParallel = Math.max(1, Math.min(maxParallel | 0, keys.length));
+  const worktrees = keys.map((key) => ({
+    story: key,
+    worktree: path.join(projectRoot, '.worktrees', key),
+    branch: `${branchPrefix}${key}`,
+    base_branch: baseBranch,
+  }));
+  return {
+    version: 1,
+    created_at: new Date().toISOString(),
+    effective_parallel: effectiveParallel,
+    max_parallel: maxParallel,
+    stories: worktrees,
+  };
+}
+
+function writePlan(projectRoot, plan) {
+  const dir = path.join(projectRoot, '_bmad-output', 'implementation-artifacts');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, PLAN_FILENAME);
+  const tmp = `${file}.tmp.${process.pid}.${process.hrtime.bigint().toString(36)}`;
+  fs.writeFileSync(tmp, JSON.stringify(plan, null, 2));
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
+  // Try -b first, fall back to checkout-existing-branch if already present.
+  const args = ['worktree', 'add', worktree, '-b', branch];
+  if (baseBranch) args.push(baseBranch);
+  const first = spawnSync('git', ['-C', projectRoot, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (first.status === 0) return { created: true, retried: false, stderr: first.stderr || '' };
+  // Retry without -b (branch exists).
+  const second = spawnSync(
+    'git',
+    ['-C', projectRoot, 'worktree', 'add', worktree, branch],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  return {
+    created: second.status === 0,
+    retried: true,
+    stderr: (first.stderr || '') + (second.stderr || ''),
+  };
+}
+
+function dispatch({ keys, maxParallel, projectRoot, branchPrefix, baseBranch, dryRun }) {
+  const plan = planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch });
+  const results = {
+    plan_file: null,
+    effective_parallel: plan.effective_parallel,
+    stories: [],
+    dry_run: !!dryRun,
+  };
+  if (!dryRun) {
+    for (const entry of plan.stories) {
+      const out = createWorktree({
+        projectRoot,
+        worktree: entry.worktree,
+        branch: entry.branch,
+        baseBranch: entry.base_branch,
+      });
+      results.stories.push({ story: entry.story, worktree: entry.worktree, branch: entry.branch, ...out });
+    }
+    results.plan_file = writePlan(projectRoot, plan);
+  } else {
+    results.stories = plan.stories.map((e) => ({
+      story: e.story,
+      worktree: e.worktree,
+      branch: e.branch,
+      created: false,
+      retried: false,
+      stderr: '(dry-run)',
+    }));
+  }
+  return results;
+}
+
+function main() {
+  const { opts } = parseArgs(process.argv.slice(2), { booleanFlags: ['dry-run'] });
+  if (opts.help) {
+    help();
+    process.exit(0);
+  }
+  const layer = parseLayer(opts.layer);
+  if (!layer.ok) {
+    log.error(layer.error);
+    process.exit(1);
+  }
+  const maxParallel = opts['max-parallel'] !== undefined ? Number.parseInt(String(opts['max-parallel']), 10) : 2;
+  if (Number.isNaN(maxParallel) || maxParallel < 1) {
+    log.error(`invalid --max-parallel '${opts['max-parallel']}': must be a positive integer`);
+    process.exit(1);
+  }
+  const projectRoot = opts['project-root'] || process.cwd();
+  const branchPrefix = opts['branch-prefix'] !== undefined ? String(opts['branch-prefix']) : 'story/';
+  const baseBranch = opts['base-branch'] !== undefined ? String(opts['base-branch']) : 'main';
+  const dryRun = opts['dry-run'] === true;
+
+  const result = dispatch({
+    keys: layer.value,
+    maxParallel,
+    projectRoot,
+    branchPrefix,
+    baseBranch,
+    dryRun,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  const allCreated = dryRun || result.stories.every((s) => s.created);
+  process.exit(allCreated ? 0 : 1);
+}
+
+module.exports = {
+  STORY_RE,
+  PLAN_FILENAME,
+  parseLayer,
+  planLayer,
+  writePlan,
+  dispatch,
+};
+
+if (require.main === module) {
+  main();
+}