@ikunin/sprintpilot 1.0.0

package/_Sprintpilot/scripts/lock.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+'use strict';
+
+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 ACTIONS = ['check', 'acquire', 'release', 'status'];
+const CLOCK_SKEW_TOLERANCE_SECONDS = 60;
+
+function help() {
+  log.out('Usage: lock.js <check|acquire|release|status> [--file path] [--stale-minutes n]');
+}
+
+function makeSessionId() {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `session-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+  }
+}
+
+function readLockInfo(lockFile, staleSeconds) {
+  let stat;
+  try {
+    stat = fs.lstatSync(lockFile);
+  } catch {
+    return { state: 'FREE' };
+  }
+  // A non-regular-file lock (directory, symlink, device, etc.) is unsafe to
+  // read/overwrite. Treat as LOCKED so the operator can investigate rather
+  // than silently stomp it.
+  // Identifiers returned from this function are included in the CLI's
+  // stdout as part of a `STATE:ID:AGE` contract — callers split on `:`, so
+  // IDs must not contain colons, spaces, or parentheses. Use stable,
+  // parser-safe slugs for the diagnostic cases.
+  if (!stat.isFile()) {
+    return { state: 'LOCKED', id: 'non-file-lock-path', ageMin: 0, corrupt: true };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(lockFile, 'utf8');
+  } catch {
+    return { state: 'LOCKED', id: 'unreadable-lock', ageMin: 0, corrupt: true };
+  }
+
+  const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+  const firstLine = lines[0];
+  // A corrupted or unparseable first line is not automatically stale.
+  // Treating garbage as epoch-0 lets anyone wipe a live lock by writing junk.
+  if (!firstLine || !/^\d+$/.test(firstLine)) {
+    return { state: 'LOCKED', id: 'corrupt-lock', ageMin: 0, corrupt: true };
+  }
+
+  const lockTime = parseInt(firstLine, 10);
+  const lockId = lines[lines.length - 1] || 'unknown';
+  const now = Math.floor(Date.now() / 1000);
+  const age = now - lockTime;
+
+  // Future-dated lockTime (clock skew, DST, manual mtime): treat as STALE so
+  // the lock doesn't become permanent. Tolerate a small positive skew window.
+  if (age < -CLOCK_SKEW_TOLERANCE_SECONDS) {
+    return { state: 'STALE', id: lockId, ageMin: 0, skew: true };
+  }
+
+  const ageMin = Math.floor(Math.max(age, 0) / 60);
+  if (age < staleSeconds) return { state: 'LOCKED', id: lockId, ageMin };
+  return { state: 'STALE', id: lockId, ageMin };
+}
+
+// Atomic exclusive-create write — the lockfile's existence IS the lock.
+// Two racing acquirers cannot both win: the second sees EEXIST.
+function writeLockExclusive(lockFile, id) {
+  const dir = path.dirname(lockFile);
+  if (dir && dir !== '.' && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const ts = Math.floor(Date.now() / 1000);
+  const content = `${ts}\n${id}\n`;
+  // 'wx' => O_CREAT | O_EXCL: fails with EEXIST if file already exists.
+  const fd = fs.openSync(lockFile, 'wx', 0o644);
+  let wrote = false;
+  try {
+    fs.writeSync(fd, content, 0, 'utf8');
+    wrote = true;
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    if (!wrote) {
+      // writeSync failed (ENOSPC, EIO): leaving an empty lockfile behind
+      // would look "corrupt" to the next acquirer and permanently wedge
+      // the autopilot. Unlink so the next try can re-create cleanly.
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+    }
+  }
+}
+
+function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    help();
+    process.exit(0);
+  }
+
+  const action = positional.find((p) => ACTIONS.includes(p));
+  const lockFile = opts.file || '.autopilot.lock';
+  const staleMinutes = parseInt(opts['stale-minutes'] || '30', 10);
+  const staleSeconds = staleMinutes * 60;
+
+  if (!action) {
+    log.error('action required (check|acquire|release|status)');
+    process.exit(1);
+  }
+
+  if (action === 'check') {
+    const info = readLockInfo(lockFile, staleSeconds);
+    if (info.state === 'FREE') log.out('FREE');
+    else log.out(`${info.state}:${info.id}:${info.ageMin}m`);
+    return;
+  }
+
+  if (action === 'acquire') {
+    const id = makeSessionId();
+    // First try the fast exclusive-create path.
+    try {
+      writeLockExclusive(lockFile, id);
+      log.out(`ACQUIRED:${id}`);
+      return;
+    } catch (e) {
+      if (e.code !== 'EEXIST') {
+        log.error(`failed to acquire lock: ${e.message}`);
+        process.exit(1);
+      }
+    }
+
+    // EEXIST: inspect the current lock. Only STALE may be taken over, and
+    // the takeover is still racy (two processes could unlink+recreate) —
+    // mitigate by re-doing an exclusive create after unlink. On race, one
+    // of them gets EEXIST.
+    const info = readLockInfo(lockFile, staleSeconds);
+    if (info.state === 'STALE') {
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+      try {
+        writeLockExclusive(lockFile, id);
+        log.out(`ACQUIRED_STALE:${id}`);
+        return;
+      } catch (e) {
+        // Another acquirer either won the stale takeover race, OR released
+        // their lock in the meantime. Re-read and handle both cases.
+        const fresh = readLockInfo(lockFile, staleSeconds);
+        if (fresh.state === 'FREE') {
+          // Released between our unlink and our re-create. Try once more.
+          try {
+            writeLockExclusive(lockFile, id);
+            log.out(`ACQUIRED:${id}`);
+            return;
+          } catch {
+            const afterRetry = readLockInfo(lockFile, staleSeconds);
+            log.out(`LOCKED:${afterRetry.id || 'unknown'}:${afterRetry.ageMin || 0}m`);
+            process.exit(1);
+          }
+        }
+        log.out(`LOCKED:${fresh.id || 'unknown'}:${fresh.ageMin || 0}m`);
+        process.exit(1);
+      }
+    }
+
+    // LOCKED (or corrupt lock — surface the state rather than silently evicting it).
+    log.out(`LOCKED:${info.id}:${info.ageMin}m`);
+    process.exit(1);
+  }
+
+  if (action === 'release') {
+    if (fs.existsSync(lockFile)) {
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+      log.out('RELEASED');
+    } else {
+      log.out('NO_LOCK');
+    }
+    return;
+  }
+
+  if (action === 'status') {
+    const info = readLockInfo(lockFile, staleSeconds);
+    if (info.state === 'FREE') log.out('Lock: free (no active session)');
+    else if (info.state === 'LOCKED') log.out(`Lock: ACTIVE — session ${info.id}, age ${info.ageMin}m`);
+    else log.out(`Lock: STALE — session ${info.id}, age ${info.ageMin}m (will auto-remove)`);
+  }
+}
+
+main();

package/_Sprintpilot/scripts/sanitize-branch.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+
+const { parseArgs } = require('../lib/runtime/args');
+const { tryGit } = require('../lib/runtime/git');
+const log = require('../lib/runtime/log');
+
+function help() {
+  log.out('Usage: sanitize-branch.js <story-key> [--prefix story/] [--max-length 60]');
+}
+
+// Minimum length for truncation to produce a valid result: we need at least
+// 1 char of name + '-' + 6-char hash = 8 chars.
+const MIN_MAX_LENGTH = 8;
+
+function sanitize(storyKey, maxLength) {
+  let name = storyKey.toLowerCase();
+  // Strip invalid git ref chars + control chars.
+  name = name
+    .replace(/[~^:?*[\\@{}"'!#$%+;=,<>|`\]]/g, '')
+    .replace(/[\x00-\x1f]/g, '')
+    // Path separators and path-traversal sequences — git treats `..` as
+    // invalid and `/` creates ref namespaces, so a story key like
+    // `../../etc/passwd` otherwise lands as a directory-traversing ref.
+    .replace(/\.\.+/g, '-')
+    .replace(/\//g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/[&()]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+/, '')
+    .replace(/[-.]+$/, '');
+
+  if (!name) return null;
+
+  if (name.length > maxLength) {
+    const hash = crypto.createHash('sha256').update(name).digest('hex').slice(0, 6);
+    const truncLen = maxLength - 7; // -6 for hash, -1 for separator
+    name = `${name.slice(0, truncLen)}-${hash}`;
+  }
+  return name;
+}
+
+async function branchExists(fullName) {
+  const r = await tryGit(['rev-parse', '--verify', fullName]);
+  return r.exitCode === 0;
+}
+
+async function validateRefFormat(fullName) {
+  const r = await tryGit(['check-ref-format', '--branch', fullName]);
+  return r.exitCode === 0;
+}
+
+async function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+  if (opts.help) { help(); process.exit(0); }
+  const storyKey = positional[0];
+  const prefix = opts.prefix ?? 'story/';
+  const maxLength = parseInt(opts['max-length'] || '60', 10);
+
+  if (!storyKey) {
+    log.error('story key required');
+    process.exit(1);
+  }
+
+  if (!Number.isFinite(maxLength) || maxLength < MIN_MAX_LENGTH) {
+    log.error(`--max-length must be at least ${MIN_MAX_LENGTH} (got ${maxLength})`);
+    process.exit(1);
+  }
+
+  let name = sanitize(storyKey, maxLength);
+  if (!name) {
+    log.error(`story key '${storyKey}' produced empty branch name after sanitization`);
+    process.exit(1);
+  }
+
+  let fullName = `${prefix}${name}`;
+  if (await branchExists(fullName)) {
+    const maxAttempts = 100;
+    let counter = 2;
+    while (counter <= maxAttempts) {
+      if (!(await branchExists(`${prefix}${name}-${counter}`))) {
+        name = `${name}-${counter}`;
+        fullName = `${prefix}${name}`;
+        break;
+      }
+      counter++;
+    }
+    if (counter > maxAttempts) {
+      log.error(`branch collision limit (${maxAttempts}) exceeded for '${name}'`);
+      process.exit(1);
+    }
+  }
+
+  if (!(await validateRefFormat(fullName))) {
+    log.error(`could not produce valid branch name from '${storyKey}'`);
+    process.exit(1);
+  }
+
+  log.out(name);
+}
+
+main().catch((e) => {
+  log.error(e.message || String(e));
+  process.exit(1);
+});

package/_Sprintpilot/scripts/stage-and-commit.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const { tryGit, tryGitStdout, gitStdout } = require('../lib/runtime/git');
+const {
+  parseAllowlist,
+  isAllowlisted,
+  scanLinesForSecrets,
+  isBinaryFile,
+} = require('../lib/runtime/secrets');
+const log = require('../lib/runtime/log');
+
+function help() {
+  log.out("Usage: stage-and-commit.js --message 'msg' [--allowlist path] [--max-size-mb 1] [--file-list path] [--dry-run]");
+}
+
+function splitOut(out) {
+  return (out || '').split(/\r?\n/).filter(Boolean);
+}
+
+function dedupeSorted(arr) {
+  return Array.from(new Set(arr)).sort();
+}
+
+async function collectChanges() {
+  const modified = await tryGitStdout(['diff', '--name-only', 'HEAD']);
+  const untracked = await tryGitStdout(['ls-files', '--others', '--exclude-standard']);
+  const deleted = splitOut(await tryGitStdout(['diff', '--name-only', '--diff-filter=D', 'HEAD']));
+  // `git diff --name-only HEAD` includes deletions — remove them from the
+  // add-side list so we don't `git add` a path that no longer exists and
+  // emit a spurious warning; the dedicated `git rm` loop handles them.
+  const deletedSet = new Set(deleted);
+  const all = dedupeSorted([...splitOut(modified), ...splitOut(untracked)])
+    .filter((f) => !deletedSet.has(f));
+  return { all, deleted };
+}
+
+function parseFileListMarkdown(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return [];
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const results = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+(.+?)\s*$/);
+    if (m) results.push(m[1]);
+  }
+  return results;
+}
+
+async function main() {
+  const { opts } = parseArgs(process.argv.slice(2), { booleanFlags: ['dry-run'] });
+  if (opts.help) { help(); process.exit(0); }
+
+  const message = opts.message ?? opts.m;
+  const allowlist = opts.allowlist;
+  const maxSizeMb = parseFloat(opts['max-size-mb'] || '1');
+  const fileList = opts['file-list'];
+  const dryRun = !!opts['dry-run'];
+
+  if (!message) {
+    log.error('--message required');
+    process.exit(2);
+  }
+
+  const { all, deleted } = await collectChanges();
+
+  if (all.length === 0 && deleted.length === 0) {
+    log.err('Nothing to commit');
+    process.exit(1);
+  }
+
+  const warnings = [];
+  const maxSizeBytes = Math.round(maxSizeMb * 1024 * 1024);
+  const allowPatterns = parseAllowlist(allowlist);
+  // Cap secret-scan reads to keep memory bounded on accidentally-staged
+  // multi-megabyte logs / generated artifacts. The scan is a warning-only
+  // heuristic anyway — refusing to scan a huge file is preferable to OOM.
+  const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+
+  for (const file of all) {
+    try {
+      // lstat (not stat) so symlinks are visible and skippable. A symlink
+      // pointing outside the repo (e.g. /etc/shadow) would otherwise be
+      // opened and its contents included in warning output.
+      const lstat = fs.lstatSync(file);
+      if (lstat.isSymbolicLink()) continue;
+      if (!lstat.isFile()) continue;
+
+      // Detect once — binary classification is the same whether we're
+      // scanning for secrets or emitting the binary-file warning.
+      const isBinary = isBinaryFile(file);
+
+      if (!isAllowlisted(file, allowPatterns)) {
+        if (lstat.size > MAX_SCAN_BYTES) {
+          warnings.push(`secret scan skipped for ${file} (size ${Math.floor(lstat.size / 1024)} KB > ${MAX_SCAN_BYTES / 1024} KB limit)`);
+        } else if (!isBinary) {
+          try {
+            const raw = fs.readFileSync(file, 'utf8');
+            const hits = scanLinesForSecrets(raw, 3);
+            if (hits.length > 0) {
+              const shown = hits.map((h) => `${file}:${h.line}:${h.text}`).join('\n');
+              warnings.push(`possible secret in ${file}:\n${shown}\n`);
+            }
+          } catch {
+            // read error — skip
+          }
+        }
+      }
+
+      if (lstat.size > maxSizeBytes) {
+        const sizeMb = Math.floor(lstat.size / (1024 * 1024));
+        warnings.push(`large file ${file} (${sizeMb}MB > ${maxSizeMb}MB limit)`);
+      }
+
+      if (isBinary) {
+        warnings.push(`binary file detected: ${file} (will be staged but verify it's intended)`);
+      }
+    } catch {
+      // missing / permission — ignore
+    }
+  }
+
+  if (fs.existsSync('.gitignore')) {
+    // Exact line match — substring tests were fooled by the entry appearing
+    // inside a comment (e.g. "# .autopilot.lock is auto-created").
+    const entries = fs.readFileSync('.gitignore', 'utf8')
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith('#'));
+    if (!entries.includes('.autopilot.lock')) {
+      warnings.push(".gitignore missing entry '.autopilot.lock' — run installer to fix");
+    }
+  } else {
+    warnings.push('no .gitignore found — addon artifacts may be committed');
+  }
+
+  if (fileList) {
+    const expected = parseFileListMarkdown(fileList);
+    if (expected.length > 0) {
+      for (const file of all) {
+        if (!expected.includes(file)) {
+          warnings.push(`unexpected file not in story File List: ${file}`);
+        }
+      }
+    }
+  }
+
+  for (const w of warnings) log.err(`WARN: ${w}`);
+
+  if (dryRun) {
+    log.out('DRY RUN — would stage and commit:');
+    for (const f of all) log.out(f);
+    if (deleted.length > 0) log.out(`Deleted: ${deleted.join(' ')}`);
+    return;
+  }
+
+  // Stage adds
+  for (const file of all) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    const r = await tryGit(['add', '--', file]);
+    if (r.exitCode !== 0) {
+      log.err(`WARN: could not add '${file}': ${(r.stderr || '').trim()}`);
+    }
+  }
+
+  // Stage deletions
+  for (const file of deleted) {
+    const r = await tryGit(['rm', '--quiet', '--', file]);
+    if (r.exitCode !== 0) {
+      log.err(`WARN: could not remove '${file}' from index (may not be tracked)`);
+    }
+  }
+
+  const commit = await tryGit(['commit', '-m', message]);
+  if (commit.exitCode !== 0) {
+    log.error(`commit failed: ${(commit.stderr || commit.stdout || '').trim()}`);
+    process.exit(2);
+  }
+
+  const sha = await gitStdout(['rev-parse', 'HEAD']);
+  log.out(sha);
+}
+
+main().catch((e) => {
+  log.error(e.message || String(e));
+  process.exit(2);
+});

package/_Sprintpilot/scripts/sync-status.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { parseArgs } = require('../lib/runtime/args');
+const {
+  yamlSafe,
+  hasStoryBlock,
+  replaceStoryBlock,
+  appendStoryBlock,
+} = require('../lib/runtime/yaml-lite');
+const log = require('../lib/runtime/log');
+
+function help() {
+  log.out('Usage: sync-status.js --story <key> --git-status-file <path> [git fields...]');
+}
+
+function atomicWrite(targetPath, content) {
+  const dir = path.dirname(targetPath);
+  if (dir && dir !== '.' && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  // Random suffix avoids collision between concurrent writers in the same ms.
+  const suffix = crypto.randomBytes(4).toString('hex');
+  const tmp = `${targetPath}.${process.pid}.${Date.now()}.${suffix}.tmp`;
+  fs.writeFileSync(tmp, content, 'utf8');
+  try {
+    fs.renameSync(tmp, targetPath);
+  } catch (e) {
+    if (e.code === 'EXDEV') {
+      // Cross-device rename (rare — bind mounts or the target path crossing
+      // a mount boundary between its parent dir and the file itself). Since
+      // we already have the full content in memory, skip the risky
+      // copyFile-then-unlink dance (which isn't atomic — O_TRUNC can leave
+      // the target truncated on failure) and just write the content
+      // directly at the target.
+      try {
+        fs.writeFileSync(targetPath, content, 'utf8');
+      } finally {
+        try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+      }
+      return;
+    }
+    // Any other error: clean up tmp so we don't leak cruft.
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+    throw e;
+  }
+}
+
+function buildBlock(story, fields) {
+  const lines = [`  ${story}:`];
+  for (const { key, value, raw } of fields) {
+    if (value === undefined || value === null || value === '') continue;
+    if (raw) {
+      lines.push(`    ${key}: ${value}`);
+    } else {
+      lines.push(`    ${key}: ${yamlSafe(value)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function buildHeader(baseBranch, platform) {
+  return [
+    '# Sprintpilot — Git Status',
+    '# Tracks git metadata per story. Do not edit manually.',
+    'git_integration:',
+    '  enabled: true',
+    `  base_branch: ${baseBranch || 'main'}`,
+    `  platform: ${platform || ''}`,
+    '',
+    'stories:',
+  ].join('\n');
+}
+
+function main() {
+  const { opts } = parseArgs(process.argv.slice(2));
+  if (opts.help) { help(); process.exit(0); }
+
+  const story = opts.story;
+  const statusFile = opts['git-status-file'];
+
+  if (!story || !statusFile) {
+    log.error('--story and --git-status-file required');
+    process.exit(1);
+  }
+
+  const branch = opts.branch;
+  const worktree = opts.worktree;
+  const storyCommit = opts.commit;
+  const patchCommits = opts['patch-commits'];
+  const pushStatus = opts['push-status'] || 'pending';
+  const mergeStatus = opts['merge-status'];
+  const prUrl = opts['pr-url'];
+  const lintResult = opts['lint-result'];
+  const platform = opts.platform;
+  const baseBranch = opts['base-branch'] || 'main';
+  // worktree-cleaned is a *tri-state*: unprovided means "don't touch prior
+  // value", so we must NOT emit the field when the flag is absent. The
+  // previous logic defaulted to 'false' and overwrote a prior 'true' every
+  // call.
+  const hasWorktreeCleaned = Object.prototype.hasOwnProperty.call(opts, 'worktree-cleaned');
+  let worktreeCleaned;
+  if (hasWorktreeCleaned) {
+    const v = opts['worktree-cleaned'];
+    // Accept 'true'/'false' strings (any case) and boolean true.
+    worktreeCleaned = (v === true || String(v).toLowerCase() === 'true') ? 'true' : 'false';
+  }
+
+  const fields = [
+    { key: 'branch', value: branch },
+    { key: 'worktree', value: worktree },
+    { key: 'story_commit', value: storyCommit },
+    { key: 'patch_commits', value: patchCommits ? `[${patchCommits}]` : undefined, raw: true },
+    { key: 'lint_result', value: lintResult },
+    { key: 'push_status', value: pushStatus },
+    { key: 'merge_status', value: mergeStatus },
+    { key: 'pr_url', value: prUrl },
+    { key: 'worktree_cleaned', value: worktreeCleaned, raw: true },
+  ];
+
+  const block = buildBlock(story, fields);
+  const existing = fs.existsSync(statusFile) ? fs.readFileSync(statusFile, 'utf8') : '';
+
+  let updated;
+  if (!existing) {
+    updated = `${buildHeader(baseBranch, platform)}\n${block}\n`;
+  } else if (hasStoryBlock(existing, story)) {
+    updated = replaceStoryBlock(existing, story, block);
+  } else {
+    updated = appendStoryBlock(existing, block);
+  }
+
+  atomicWrite(statusFile, updated);
+  log.out(`OK:${story}:push=${pushStatus}`);
+}
+
+main();

package/_Sprintpilot/skills/sprint-autopilot-off/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: sprint-autopilot-off
+description: 'Disengage autonomous story execution mode with git status report. Reports sprint position, completed work, git branch/PR status, and next steps. Releases the autopilot lock file. Use when user says "/sprint-autopilot-off" or "stop autopilot" or "pause autopilot".'
+---
+
+Follow the instructions in ./workflow.md.