@ikunin/sprintpilot 1.0.0

package/_Sprintpilot/Sprintpilot.md

@@ -0,0 +1,216 @@
+# BMad Method Workflow — Mandatory for All AI Agents
+
+This project uses the **BMad Method** with **Sprintpilot** (autopilot + multi-agent addon). Always use the BMad Method workflow for every story. Never skip steps. When unsure, invoke `bmad-help` first.
+
+---
+
+## Navigation & orientation
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-help` | First resort when unsure what to do next — analyzes current state and recommends the right skill or workflow |
+
+---
+
+## Sprintpilot — autopilot & git workflow
+
+| Skill | When to use |
+|-------|-------------|
+| `sprint-autopilot-on` | Start autonomous story execution with git branching, commits, and PRs |
+| `sprint-autopilot-off` | Disengage autopilot, show sprint + git status report |
+
+When Sprintpilot or the git addon is active:
+- **NEVER** use `git add -A` or `git add .` — always stage files explicitly by name
+- **NEVER** commit secrets, API keys, tokens, or credentials
+- Each story gets its own isolated worktree and branch (`story/<key>`)
+- Commits use conventional format: `feat(<epic>): <title> (<key>)`
+
+---
+
+## Full skill reference by lifecycle phase
+
+### Phase 0 — Project inception (new projects)
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-product-brief` | Start here for a new project — collaborative discovery of goals, constraints, users |
+| `bmad-create-prd` | Create a full Product Requirements Document from scratch |
+| `bmad-edit-prd` | Update or revise an existing PRD |
+| `bmad-validate-prd` | Validate a PRD against BMad Method standards before moving to design |
+| `bmad-create-architecture` | Create technical architecture and solution design decisions |
+| `bmad-create-ux-design` | Plan UX patterns and design specifications |
+| `bmad-create-epics-and-stories` | Break PRD + architecture into epics and story list |
+| `bmad-generate-project-context` | Generate `project-context.md` with AI rules (run once after inception) |
+| `bmad-document-project` | Document an existing (brownfield) project to give AI agents context |
+
+### Phase 1 — Sprint planning (before development starts)
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-sprint-planning` | Generate `sprint-status.yaml` tracking file from epics list |
+| `bmad-sprint-status` | Check current sprint status and surface risks at any time |
+| `bmad-correct-course` | Manage significant scope or direction changes mid-sprint |
+
+### Phase 2 — Story development (the mandatory per-story loop)
+
+See **Mandatory sequence per story** section below.
+
+### Phase 3 — Epic close-out
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-retrospective` | Run after all stories in an epic are `done`; saves lessons, marks epic `done` |
+
+---
+
+## Quick path — for small changes without full story ceremony
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-quick-dev` | Implement any user intent (bug fix, tweak, refactor) directly — follows project conventions |
+
+> Use the quick path only for genuinely small, isolated changes. For anything touching multiple components or requiring E2E coverage, use the full story loop.
+
+---
+
+## Sprintpilot multi-agent skills
+
+These launch parallel subagents for deeper, faster analysis:
+
+| Skill | Agents | When to use |
+|-------|--------|-------------|
+| `sprintpilot-code-review` | 3 | Parallel adversarial code review (Blind Hunter + Edge Case + Acceptance) |
+| `sprintpilot-codebase-map` | 5 | Brownfield codebase mapping (stack, architecture, quality, concerns, integrations) |
+| `sprintpilot-assess` | 3 | Tech debt assessment (dependency audit, debt classification, migration analysis) |
+| `sprintpilot-reverse-architect` | 3 | Extract architecture from existing code (components, data flow, patterns) |
+| `sprintpilot-migrate` | 4 | Full migration planning — 12 steps from current stack to target stack |
+| `sprintpilot-research` | N | Parallel research fan-out with web search |
+| `sprintpilot-party-mode` | 2-3 | Multi-persona discussion (architect, PM, QA, etc. debating in parallel) |
+
+### Brownfield analysis pipeline
+
+```
+sprintpilot-codebase-map → sprintpilot-assess → sprintpilot-reverse-architect → sprintpilot-migrate
+```
+
+Run `sprintpilot-codebase-map` first on any existing codebase. The other multi-agent skills consume its outputs.
+
+---
+
+## Research & discovery skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-technical-research` | Research technologies, frameworks, or architectural trade-offs |
+| `bmad-domain-research` | Research a business domain or industry |
+| `bmad-market-research` | Research market competition and customers |
+| `bmad-brainstorming` | Facilitate structured ideation sessions |
+| `bmad-advanced-elicitation` | Push the model to reconsider and refine recent output |
+
+---
+
+## QA & test architecture skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-qa-generate-e2e-tests` | Generate E2E tests for existing features (retroactive coverage) |
+| `bmad-testarch-framework` | Initialize test framework (Playwright / Cypress) |
+| `bmad-testarch-atdd` | Generate failing acceptance tests (TDD cycle) |
+| `bmad-testarch-test-design` | Create system-level or epic-level test plans |
+| `bmad-testarch-nfr` | Assess non-functional requirements (performance, security, reliability) |
+| `bmad-testarch-ci` | Scaffold CI/CD quality pipeline with test execution |
+| `bmad-testarch-trace` | Generate traceability matrix and quality gate decisions |
+| `bmad-testarch-test-review` | Review test quality against best practices |
+| `bmad-testarch-automate` | Expand test automation coverage across the codebase |
+| `bmad-teach-me-testing` | Interactive testing education sessions |
+
+---
+
+## Review skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-code-review` | Full adversarial code review (3 layers) — mandatory step 5 of per-story loop |
+| `bmad-review-adversarial-general` | Cynical critical review of any artifact (specs, designs, docs) |
+| `bmad-review-edge-case-hunter` | Exhaustive edge-case and boundary analysis of code or specs |
+| `bmad-editorial-review-structure` | Structural editing of documents |
+| `bmad-editorial-review-prose` | Copy-editing for communication issues in documents |
+
+---
+
+## Agent role personas
+
+These skills activate an interactive agent persona. They stay in character until given an exit command.
+
+| Skill | Persona |
+|-------|---------|
+| `bmad-agent-pm` | Product Manager |
+| `bmad-agent-analyst` | Business Analyst |
+| `bmad-agent-architect` | Solution Architect |
+| `bmad-agent-ux-designer` | UX Designer |
+| `bmad-agent-dev` | Developer |
+| `bmad-agent-qa` | QA Engineer |
+| `bmad-agent-sm` | Scrum Master |
+| `bmad-agent-tech-writer` | Technical Writer |
+| `bmad-agent-quick-flow-solo-dev` | Rapid full-stack solo developer |
+| `bmad-party-mode` | All agents in one group discussion |
+
+---
+
+## Document utilities
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-shard-doc` | Split a large markdown document into organized smaller files |
+| `bmad-index-docs` | Generate or update an `index.md` for a docs folder |
+| `bmad-distillator` | Lossless LLM-optimized compression of source documents |
+
+---
+
+## Mandatory sequence per story
+
+| Step | Skill | sprint-status.yaml transition | Definition of Done |
+|------|-------|-------------------------------|--------------------|
+| 1 | `bmad-create-story` | → `ready-for-dev` | Story file exists, all sections complete |
+| 2 | `bmad-check-implementation-readiness` | (no change) | Readiness check passes with no blockers |
+| 3 | `bmad-dev-story` (RED) | → `in-progress` | Tests written and **confirmed failing** before any implementation |
+| 4 | `bmad-dev-story` (GREEN) | → `review` | All tests pass; pass count stated explicitly (e.g. "9/9 passed") |
+| 5 | `bmad-code-review` | (no change) | All review layers complete; findings triaged |
+| 6 | Apply `patch` findings + re-run tests | → `done` | All patch tasks completed, tests still green, pass count confirmed |
+| 7 | `bmad-retrospective` (per epic, after all stories done) | epic → `done` | Retrospective output saved; epic marked done |
+
+## Task list hygiene
+
+BMad Method skills only update `{implementation_artifacts}/sprint-status.yaml` — they do NOT update the coding agent's task list.
+
+The task list must always reflect the full BMad Method work breakdown. Before starting a story, create a task for **each step** above. Keep the list granular enough that anyone can see exactly where work stands at a glance.
+
+Rules:
+- Create all step-tasks for a story **before** starting work on it
+- Mark each step-task `in_progress` when you begin it
+- Mark each step-task `completed` immediately when done — never batch
+- Do not start step N+1 until step N is `completed`
+- `sprint-status.yaml` is updated automatically by BMad Method skills — do NOT edit it manually
+
+## Issue and patch tracking
+
+When tests fail **or** code review produces `patch` findings, each issue gets its own task:
+
+- Create one task per distinct issue / patch item (not one task for all issues)
+- Name it clearly: e.g. "Fix: `deleteTask` transaction not awaited" or "Patch P1: rollback missing on Ctrl+Down"
+- Mark it `in_progress` when fixing, `completed` only after the fix is applied **and the relevant test passes**
+- State the test result explicitly: "fixed — 10/10 passed"
+- Do not mark the parent step-task `completed` until all its issue/patch tasks are `completed`
+
+## Story file updates
+
+After `bmad-dev-story` completes, fill in the story file's `Dev Agent Record` section:
+- List all files changed
+- Note any non-obvious decisions or deviations from the spec
+- Record final test pass count
+
+## Test result transparency
+
+Every time tests are run, state the result explicitly in your response:
+- `N/N passed` — or — `N passed, M failed` with failure details
+- Never say "tests pass" without the count

package/_Sprintpilot/lib/runtime/args.js

@@ -0,0 +1,77 @@
+'use strict';
+
+function parseArgs(argv, { booleanFlags = [], positionalActions = null } = {}) {
+  const opts = {};
+  const positional = [];
+  const flatBool = new Set(booleanFlags);
+  const actionSet = positionalActions ? new Set(positionalActions) : null;
+  const actions = [];
+
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+
+    if (token === '-h' || token === '--help') {
+      opts.help = true;
+      i++;
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      let name;
+      let value;
+      if (eq !== -1) {
+        name = token.slice(2, eq);
+        value = token.slice(eq + 1);
+        opts[name] = value;
+        i++;
+        continue;
+      }
+      name = token.slice(2);
+      if (flatBool.has(name)) {
+        opts[name] = true;
+        i++;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('-')) {
+        opts[name] = true;
+        i++;
+      } else {
+        opts[name] = next;
+        i += 2;
+      }
+      continue;
+    }
+
+    if (token.startsWith('-') && token.length === 2) {
+      const name = token.slice(1);
+      const next = argv[i + 1];
+      if (flatBool.has(name)) {
+        opts[name] = true;
+        i++;
+        continue;
+      }
+      if (next === undefined || next.startsWith('-')) {
+        opts[name] = true;
+        i++;
+      } else {
+        opts[name] = next;
+        i += 2;
+      }
+      continue;
+    }
+
+    if (actionSet && actionSet.has(token)) {
+      actions.push(token);
+    } else {
+      positional.push(token);
+    }
+    i++;
+  }
+
+  return { opts, positional, actions };
+}
+
+module.exports = { parseArgs };

package/_Sprintpilot/lib/runtime/git.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { run, tryRun } = require('./spawn');
+
+async function git(args, opts = {}) {
+  return run('git', args, opts);
+}
+
+async function tryGit(args, opts = {}) {
+  return tryRun('git', args, opts);
+}
+
+async function gitStdout(args, opts = {}) {
+  const { stdout } = await git(args, opts);
+  return stdout.trim();
+}
+
+async function tryGitStdout(args, opts = {}) {
+  const r = await tryGit(args, opts);
+  if (r.exitCode !== 0) return null;
+  return r.stdout.trim();
+}
+
+module.exports = { git, tryGit, gitStdout, tryGitStdout };

package/_Sprintpilot/lib/runtime/http.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const https = require('node:https');
+const http = require('node:http');
+const { URL } = require('node:url');
+
+// Bound response bodies so a malicious / misconfigured server cannot OOM the
+// process with an unbounded chunked response. 5 MB is generous for any PR
+// API response we'd expect.
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+
+function postJson(urlStr, body, { headers = {}, timeoutMs = 15_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(urlStr);
+    } catch (e) {
+      return reject(e);
+    }
+
+    // Single resolve/reject guard — both `req.on('error')` and `res.on('error')`
+    // can fire on the size-cap abort path (we call req.destroy(err)). Without
+    // this, the observed error message becomes non-deterministic.
+    let settled = false;
+    const done = (fn, val) => { if (!settled) { settled = true; fn(val); } };
+    const ok = (val) => done(resolve, val);
+    const fail = (err) => done(reject, err);
+
+    const payload = typeof body === 'string' ? body : JSON.stringify(body);
+    // Pick the transport based on URL scheme so http:// can be used by local
+    // integration tests without standing up a TLS cert. Production callers
+    // always use https://.
+    const transport = url.protocol === 'http:' ? http : https;
+    const defaultPort = url.protocol === 'http:' ? 80 : 443;
+    const req = transport.request(
+      {
+        method: 'POST',
+        hostname: url.hostname,
+        port: url.port || defaultPort,
+        path: `${url.pathname}${url.search || ''}`,
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+          'User-Agent': 'sprintpilot',
+          ...headers,
+        },
+        timeout: timeoutMs,
+      },
+      (res) => {
+        // We do NOT follow redirects: the caller's Authorization header
+        // could leak to an unintended host, and upstream PR APIs don't
+        // return 3xx for normal success paths. Surface redirects explicitly
+        // so the caller can fix the base URL.
+        if (res.statusCode >= 300 && res.statusCode < 400) {
+          const location = res.headers.location || '<no Location header>';
+          res.resume(); // drain
+          return ok({
+            statusCode: res.statusCode,
+            body: `redirect not supported; Location: ${location}`,
+            json: null,
+          });
+        }
+
+        const chunks = [];
+        let total = 0;
+        let aborted = false;
+        res.on('data', (c) => {
+          if (aborted) return;
+          total += c.length;
+          if (total > MAX_RESPONSE_BYTES) {
+            aborted = true;
+            req.destroy(new Error(`response exceeded ${MAX_RESPONSE_BYTES} bytes`));
+            return;
+          }
+          chunks.push(c);
+        });
+        res.on('end', () => {
+          if (aborted) return; // error path handles it
+          const text = Buffer.concat(chunks).toString('utf8');
+          let json = null;
+          try { json = JSON.parse(text); } catch { /* non-json */ }
+          ok({ statusCode: res.statusCode, body: text, json });
+        });
+        res.on('error', fail);
+      }
+    );
+    req.on('timeout', () => {
+      req.destroy(new Error(`HTTP timeout after ${timeoutMs}ms`));
+    });
+    req.on('error', fail);
+    req.write(payload);
+    req.end();
+  });
+}
+
+module.exports = { postJson, MAX_RESPONSE_BYTES };

package/_Sprintpilot/lib/runtime/log.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function out(msg) {
+  process.stdout.write(String(msg));
+  if (!String(msg).endsWith('\n')) process.stdout.write('\n');
+}
+
+function err(msg) {
+  process.stderr.write(String(msg));
+  if (!String(msg).endsWith('\n')) process.stderr.write('\n');
+}
+
+function warn(msg) {
+  err(`WARN: ${msg}`);
+}
+
+function info(msg) {
+  err(`INFO: ${msg}`);
+}
+
+function error(msg) {
+  err(`ERROR: ${msg}`);
+}
+
+function fail(msg, code = 1) {
+  error(msg);
+  process.exit(code);
+}
+
+module.exports = { out, err, warn, info, error, fail };

package/_Sprintpilot/lib/runtime/secrets.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const fs = require('node:fs');
+
+// Keyword-based fuzzy matches (high false-positive rate, but useful as a
+// last-resort catch for things like `API_KEY = "..."`).
+const SECRET_KEYWORD = /API_KEY|SECRET|TOKEN|PASSWORD|aws_access|private_key/i;
+
+// Concrete, high-confidence key prefixes / formats — these are what real
+// secrets actually look like. Matching here is much less noisy than the
+// keyword list above.
+const SECRET_FORMATS = [
+  /\bAKIA[0-9A-Z]{16}\b/,                  // AWS Access Key ID
+  /\bASIA[0-9A-Z]{16}\b/,                  // AWS temporary Access Key ID
+  /\bghp_[A-Za-z0-9]{30,}\b/,              // GitHub personal access token
+  /\bgho_[A-Za-z0-9]{30,}\b/,              // GitHub OAuth token
+  /\bghu_[A-Za-z0-9]{30,}\b/,              // GitHub user-to-server token
+  /\bghs_[A-Za-z0-9]{30,}\b/,              // GitHub server-to-server token
+  /\bghr_[A-Za-z0-9]{30,}\b/,              // GitHub refresh token
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/,      // GitHub fine-grained PAT
+  /\bsk-[A-Za-z0-9_-]{20,}\b/,             // OpenAI / Anthropic-like
+  /\bsk_live_[A-Za-z0-9]{20,}\b/,          // Stripe live secret
+  /\bsk_test_[A-Za-z0-9]{20,}\b/,          // Stripe test secret
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,      // Slack tokens
+  /\bAIza[0-9A-Za-z_-]{35,99}\b/,          // Google API key (standard is 39 chars = AIza + 35)
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,    // PEM private key header
+];
+
+// Deprecated: callers should use `matchesSecret(line)` which applies both
+// the keyword list and the concrete-format list. Retained only for
+// compatibility with anyone importing the old symbol.
+const SECRET_PATTERN = SECRET_KEYWORD;
+
+function matchesSecret(line) {
+  if (SECRET_KEYWORD.test(line)) return true;
+  for (const re of SECRET_FORMATS) {
+    if (re.test(line)) return true;
+  }
+  return false;
+}
+
+function scanLinesForSecrets(text, maxHits = 3) {
+  if (!text) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (matchesSecret(lines[i])) {
+      out.push({ line: i + 1, text: lines[i] });
+      if (out.length >= maxHits) break;
+    }
+  }
+  return out;
+}
+
+function globToRegex(glob) {
+  let src = '^';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        src += '.*';
+        i += 2;
+        if (glob[i] === '/') i++;
+      } else {
+        src += '[^/]*';
+        i++;
+      }
+      continue;
+    }
+    if (c === '?') {
+      src += '[^/]';
+      i++;
+      continue;
+    }
+    if ('.+^$(){}|\\'.indexOf(c) !== -1) {
+      src += '\\' + c;
+      i++;
+      continue;
+    }
+    if (c === '[') {
+      const close = glob.indexOf(']', i);
+      if (close === -1) {
+        src += '\\[';
+        i++;
+        continue;
+      }
+      src += glob.slice(i, close + 1);
+      i = close + 1;
+      continue;
+    }
+    src += c;
+    i++;
+  }
+  src += '$';
+  return new RegExp(src);
+}
+
+function parseAllowlist(filePath) {
+  if (!filePath) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'))
+    .map((glob) => ({ glob, regex: globToRegex(glob) }));
+}
+
+function isAllowlisted(filePath, patterns) {
+  return patterns.some(({ regex }) => regex.test(filePath));
+}
+
+function isTextSafeSample(buf) {
+  // Binary detection: any NUL byte -> binary.
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0) return false;
+  }
+  return true;
+}
+
+function isBinaryFile(filePath) {
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(8192);
+      const bytes = fs.readSync(fd, buf, 0, buf.length, 0);
+      if (bytes === 0) return false;
+      return !isTextSafeSample(buf.subarray(0, bytes));
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  SECRET_PATTERN, // deprecated — prefer matchesSecret
+  SECRET_FORMATS,
+  matchesSecret,
+  scanLinesForSecrets,
+  globToRegex,
+  parseAllowlist,
+  isAllowlisted,
+  isBinaryFile,
+};

package/_Sprintpilot/lib/runtime/spawn.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const child = require('node:child_process');
+
+function run(file, args, { cwd, timeoutMs = 30_000, input, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = child.execFile(
+      file,
+      args,
+      {
+        cwd,
+        timeout: timeoutMs,
+        windowsHide: true,
+        maxBuffer: 10 * 1024 * 1024,
+        env: env || process.env,
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          const e = new Error(
+            `${file} ${args.join(' ')} failed with code ${err.code ?? err.signal ?? 'unknown'}`
+          );
+          e.exitCode = typeof err.code === 'number' ? err.code : 1;
+          e.signal = err.signal || null;
+          e.stdout = String(stdout || '');
+          e.stderr = String(stderr || '');
+          e.originalError = err;
+          return reject(e);
+        }
+        resolve({ stdout: String(stdout || ''), stderr: String(stderr || ''), exitCode: 0 });
+      }
+    );
+    // Rejecting on spawn-time errors (ENOENT etc) ensures the caller sees a
+    // rejected Promise rather than hanging, even if `proc.stdin` was never
+    // attached. Without this, a missing binary can crash via `proc.stdin.write`.
+    proc.on('error', reject);
+    if (input !== undefined && proc.stdin) {
+      proc.stdin.on('error', () => { /* ignore EPIPE etc */ });
+      try { proc.stdin.write(input); } catch { /* ignore */ }
+      try { proc.stdin.end(); } catch { /* ignore */ }
+    }
+  });
+}
+
+async function tryRun(file, args, opts) {
+  try {
+    return await run(file, args, opts);
+  } catch (e) {
+    return { stdout: e.stdout || '', stderr: e.stderr || '', exitCode: e.exitCode ?? 1, error: e };
+  }
+}
+
+function runInherit(file, args, { cwd, env, input } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = child.spawn(file, args, {
+      cwd,
+      env: env || process.env,
+      stdio: input !== undefined ? ['pipe', 'inherit', 'inherit'] : 'inherit',
+      windowsHide: true,
+    });
+    proc.on('error', reject);
+    proc.on('close', (code) => resolve({ exitCode: code ?? 0 }));
+    if (input !== undefined && proc.stdin) {
+      try { proc.stdin.write(input); proc.stdin.end(); } catch { /* ignore */ }
+    }
+  });
+}
+
+module.exports = { run, tryRun, runInherit };

package/_Sprintpilot/lib/runtime/text.js

@@ -0,0 +1,26 @@
+'use strict';
+
+function splitLines(text) {
+  if (!text) return [];
+  const trimmedTrailing = text.replace(/\r?\n$/, '');
+  if (trimmedTrailing === '') return [];
+  return trimmedTrailing.split(/\r?\n/);
+}
+
+function headLines(text, n) {
+  if (n <= 0) return '';
+  const lines = splitLines(text);
+  return lines.slice(0, n).join('\n');
+}
+
+function countLines(text) {
+  return splitLines(text).length;
+}
+
+function extractUrl(text) {
+  if (!text) return null;
+  const m = text.match(/https?:\/\/[^\s"'<>)]+/);
+  return m ? m[0] : null;
+}
+
+module.exports = { splitLines, headLines, countLines, extractUrl };