@chenguangyao/devflow-kit 0.1.43

package/src/core/autodetect.js

@@ -0,0 +1,271 @@
+'use strict';
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const cp = require('child_process');
+
+/**
+ * Auto-detection helpers for `devflow init` — all functions return safe defaults
+ * when detection fails (never throw).
+ *
+ * Mirrors arb-workflow-kit/skills/dev-workflow/scripts/init-project.py but
+ * ships as a library rather than a generator script.
+ */
+
+/** Detect git remote URL; returns null when not a git repo or no remote. */
+function gitRemote(root, name = 'origin') {
+  try {
+    const r = cp.spawnSync('git', ['config', '--get', `remote.${name}.url`], {
+      cwd: root, encoding: 'utf8',
+    });
+    if (r.status !== 0) return null;
+    const url = (r.stdout || '').trim();
+    return url || null;
+  } catch { return null; }
+}
+
+/**
+ * Parse a git remote URL into { host, group, project }.
+ *
+ * Handles:
+ *   - git@gitlab.corp.com:group/subgroup/project.git
+ *   - ssh://git@gitlab.corp.com:2222/group/project.git
+ *   - https://gitlab.corp.com/group/project
+ *   - https://gitlab.corp.com/group/subgroup/project.git
+ */
+function parseRemote(url) {
+  if (!url) return null;
+  let host, pathPart;
+
+  // git@host:group/project.git
+  const sshShort = /^([\w.-]+@)?([\w.-]+):(.+?)(?:\.git)?\/?$/.exec(url);
+  // ssh://git@host[:port]/group/project(.git)?
+  const sshLong = /^ssh:\/\/(?:[\w.-]+@)?([\w.-]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/.exec(url);
+  // https?://host/group/project(.git)?
+  const https   = /^https?:\/\/(?:[^@/]+@)?([\w.-]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/.exec(url);
+
+  if (sshLong) { host = sshLong[1]; pathPart = sshLong[2]; }
+  else if (https) { host = https[1]; pathPart = https[2]; }
+  else if (sshShort) { host = sshShort[2]; pathPart = sshShort[3]; }
+  else return null;
+
+  pathPart = pathPart.replace(/\.git$/, '').replace(/^\/+|\/+$/g, '');
+  const segs = pathPart.split('/').filter(Boolean);
+  if (segs.length < 2) return { host, group: '', project: segs[0] || '', fullPath: pathPart };
+  const project = segs.pop();
+  const group = segs.join('/');
+  return { host, group, project, fullPath: `${group}/${project}` };
+}
+
+/**
+ * Detect the repo's default branch. Returns a best guess branch name
+ * (never throws). Priority:
+ *
+ *   1. `git symbolic-ref refs/remotes/origin/HEAD` — what the remote marks
+ *      as HEAD (authoritative for cloned repos)
+ *   2. Existence of remote tracking `origin/master` → master
+ *   3. Existence of remote tracking `origin/main`   → main
+ *   4. Existence of local branch `master` → master
+ *   5. Existence of local branch `main`   → main
+ *   6. `git config init.defaultBranch` (when explicitly set)
+ *   7. Literal `'main'` (git 2.28+ default)
+ *
+ * We prefer `master` ahead of `main` when both remote/local flags must be
+ * inspected, because legacy repos (common in internal GitLab) still default
+ * to master; newer repos declare their HEAD via step 1.
+ */
+function detectDefaultBranch(root) {
+  const run = (args) => {
+    try { return cp.spawnSync('git', args, { cwd: root, encoding: 'utf8' }); }
+    catch { return { status: 1, stdout: '', stderr: '' }; }
+  };
+
+  // 1. origin/HEAD symbolic ref — most reliable when present
+  let r = run(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  if (r.status === 0) {
+    const full = (r.stdout || '').trim();         // e.g. "origin/master"
+    if (full) {
+      const branch = full.replace(/^origin\//, '');
+      if (branch) return branch;
+    }
+  }
+
+  // 2-3. Remote tracking branches
+  for (const name of ['master', 'main']) {
+    r = run(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`]);
+    if (r.status === 0) return name;
+  }
+
+  // 4-5. Local branches (e.g. fresh repo, no remote yet)
+  for (const name of ['master', 'main']) {
+    r = run(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]);
+    if (r.status === 0) return name;
+  }
+
+  // 6. Respect explicit git config
+  r = run(['config', '--get', 'init.defaultBranch']);
+  if (r.status === 0) {
+    const v = (r.stdout || '').trim();
+    if (v) return v;
+  }
+
+  // 7. Sensible fallback (matches modern git default)
+  return 'main';
+}
+
+/**
+ * Detect primary language / stack from lock + manifest files.
+ * Returns first match (priority ordered) or 'unknown'.
+ */
+function detectLanguage(root) {
+  const checks = [
+    { f: 'go.mod',            lang: 'go' },
+    { f: 'package.json',      lang: 'node' },
+    { f: 'pyproject.toml',    lang: 'python' },
+    { f: 'requirements.txt',  lang: 'python' },
+    { f: 'setup.cfg',         lang: 'python' },
+    { f: 'Cargo.toml',        lang: 'rust' },
+    { f: 'pom.xml',           lang: 'java' },
+    { f: 'build.gradle',      lang: 'java' },
+    { f: 'build.gradle.kts',  lang: 'kotlin' },
+    { f: 'composer.json',     lang: 'php' },
+    { f: 'Gemfile',           lang: 'ruby' },
+    { f: 'mix.exs',           lang: 'elixir' },
+    { f: '*.csproj',          lang: 'dotnet', glob: true },
+  ];
+
+  for (const c of checks) {
+    if (c.glob) {
+      try {
+        const files = fs.readdirSync(root);
+        if (files.some((n) => n.endsWith('.csproj'))) return c.lang;
+      } catch { /* ignore */ }
+    } else if (fs.existsSync(path.join(root, c.f))) {
+      return c.lang;
+    }
+  }
+  return 'unknown';
+}
+
+/**
+ * Detect package manager / build tool for the current project.
+ */
+function detectBuildTool(root, lang) {
+  const exists = (f) => fs.existsSync(path.join(root, f));
+  if (lang === 'node') {
+    if (exists('pnpm-lock.yaml'))   return 'pnpm';
+    if (exists('yarn.lock'))        return 'yarn';
+    if (exists('bun.lockb'))        return 'bun';
+    return 'npm';
+  }
+  if (lang === 'python') {
+    if (exists('poetry.lock'))      return 'poetry';
+    if (exists('uv.lock'))          return 'uv';
+    if (exists('Pipfile.lock'))     return 'pipenv';
+    return 'pip';
+  }
+  if (lang === 'java') return exists('pom.xml') ? 'maven' : 'gradle';
+  if (lang === 'go')   return 'go';
+  return '';
+}
+
+/**
+ * Suggest a Jenkins job name based on project name + common conventions.
+ * Returns a list of candidates so UI can offer choices.
+ *
+ *   - <project>-test
+ *   - <project>-test2
+ *   - <group>-<project>-test
+ *   - deploy/<project>
+ */
+function suggestJenkinsJobs({ group, project, env = 'test' }) {
+  if (!project) return [];
+  const proj = project.replace(/[^\w-]/g, '-');
+  const grp  = (group || '').replace(/[^\w-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  const envName = String(env || 'test').replace(/[^\w-]/g, '-');
+  const out = [
+    `${proj}-${envName}`,
+    `${proj}-test`,
+    `${proj}-test2`,
+    `${proj}-deploy-${envName}`,
+    `deploy/${proj}`,
+    `deploy/${proj}-${envName}`,
+    `${envName}/${proj}`,
+  ];
+  if (grp) out.unshift(`${grp}-${proj}`, `${grp}-${proj}-${envName}`, `${grp}-${envName}-${proj}`);
+  return [...new Set(out)];
+}
+
+function rankJenkinsJobs(candidates, { group, project, env = 'test' } = {}) {
+  const expected = suggestJenkinsJobs({ group, project, env });
+  const scored = (candidates || []).map((job) => {
+    const name = String(job && (job.name || job.fullName || job.url || job) || '');
+    const normalized = name.toLowerCase();
+    let score = 0;
+    const exactIdx = expected.findIndex((x) => x.toLowerCase() === normalized);
+    if (exactIdx >= 0) score += 100 - exactIdx;
+    if (project && normalized.includes(String(project).toLowerCase())) score += 30;
+    if (group && normalized.includes(String(group).split('/').pop().toLowerCase())) score += 10;
+    if (env && normalized.includes(String(env).toLowerCase())) score += 20;
+    if (/deploy|发布|部署/.test(normalized)) score += 5;
+    if (/rollback|回滚/.test(normalized)) score -= 20;
+    return { job, name, score };
+  }).filter((x) => x.score > 0);
+  return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).map((x) => x.job);
+}
+
+/**
+ * Full one-shot detect used by `devflow init`.
+ * Returns object with detection flags + never-throws.
+ */
+async function detect(root) {
+  const remoteUrl = gitRemote(root);
+  const remote = parseRemote(remoteUrl);
+  const language = detectLanguage(root);
+  const buildTool = detectBuildTool(root, language);
+  const jenkinsJobs = remote ? suggestJenkinsJobs(remote) : [];
+  const defaultBranch = detectDefaultBranch(root);
+
+  return {
+    remoteUrl,
+    remote,         // { host, group, project, fullPath } or null
+    language,       // 'go' | 'node' | 'python' | ...
+    buildTool,
+    jenkinsJobs,
+    defaultBranch,  // 'main' | 'master' | <custom>
+  };
+}
+
+/**
+ * Render detection result to human-readable summary for CLI output.
+ */
+function formatSummary(d) {
+  const lines = [];
+  if (d.remote) {
+    lines.push(`  remote:     ${d.remote.host}:${d.remote.fullPath}`);
+  } else if (d.remoteUrl) {
+    lines.push(`  remote:     ${d.remoteUrl} (parse failed)`);
+  } else {
+    lines.push(`  remote:     (not a git repo or no origin)`);
+  }
+  lines.push(`  language:   ${d.language}${d.buildTool ? ` (${d.buildTool})` : ''}`);
+  if (d.defaultBranch) {
+    lines.push(`  branch:     ${d.defaultBranch} (default)`);
+  }
+  if (d.jenkinsJobs.length) {
+    lines.push(`  jenkins:    ${d.jenkinsJobs.slice(0, 3).join(' / ')}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  gitRemote,
+  parseRemote,
+  detectLanguage,
+  detectBuildTool,
+  detectDefaultBranch,
+  suggestJenkinsJobs,
+  rankJenkinsJobs,
+  detect,
+  formatSummary,
+};

package/src/core/change.js

@@ -0,0 +1,208 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const cp = require('child_process');
+const paths = require('./paths.js');
+const state = require('./state.js');
+
+function slugify(input) {
+  if (!input) return 'untitled-' + Date.now().toString(36);
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+}
+
+function currentBranch(root) {
+  for (const args of [
+    ['branch', '--show-current'],
+    ['rev-parse', '--abbrev-ref', 'HEAD'],
+  ]) {
+    const r = cp.spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    if (r.status !== 0) continue;
+    const branch = (r.stdout || '').trim();
+    if (branch && branch !== 'HEAD') return branch;
+  }
+  return null;
+}
+
+function withCurrentBranchSlug(root, slug) {
+  const safeSlug = slugify(slug);
+  const branch = currentBranch(root);
+  if (!branch) return safeSlug;
+  const branchSlug = slugify(branch);
+  if (!branchSlug) return safeSlug;
+  if (safeSlug === branchSlug || safeSlug.startsWith(`${branchSlug}-`)) return safeSlug;
+  return slugify(`${branchSlug}-${safeSlug}`);
+}
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function listChanges(root) {
+  const dirs = [paths.changesDir(root), legacyChangesDir(root)];
+  const names = new Set();
+  for (const dir of dirs) {
+    if (!fsSync.existsSync(dir)) continue;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) names.add(e.name);
+    }
+  }
+  return Array.from(names);
+}
+
+async function getCurrent(root) {
+  const all = await listChanges(root);
+  if (all.length === 0) {
+    // Fallback: look for the most recently archived change
+    return getLastArchived(root);
+  }
+  if (all.length === 1) return all[0];
+  // multi-change: pick most recently updated state.json
+  let best = null;
+  let bestTime = 0;
+  for (const slug of all) {
+    const file = resolveStateFile(root, slug);
+    if (!fsSync.existsSync(file)) continue;
+    const stat = await fs.stat(file);
+    if (stat.mtimeMs > bestTime) {
+      bestTime = stat.mtimeMs;
+      best = slug;
+    }
+  }
+  return best;
+}
+
+/**
+ * Return the slug of the most recently archived change (by dir mtime).
+ * Archive dirs are named `<YYYY-MM-DD>-<slug>`.
+ */
+async function getLastArchived(root) {
+  const all = [];
+  for (const dir of [paths.archiveDir(root), legacyArchiveDir(root)]) {
+    if (!fsSync.existsSync(dir)) continue;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) all.push({ base: dir, name: e.name });
+    }
+  }
+  const dirs = all;
+  if (!dirs.length) return null;
+  let best = null;
+  let bestTime = 0;
+  for (const e of dirs) {
+    const abs = path.join(e.base, e.name);
+    try {
+      const stat = await fs.stat(abs);
+      if (stat.mtimeMs > bestTime) {
+        bestTime = stat.mtimeMs;
+        best = e.name;
+      }
+    } catch { /* ignore */ }
+  }
+  if (!best) return null;
+  // Strip leading date prefix: "2026-05-07-<slug>" → "<slug>"
+  const m = best.match(/^\d{4}-\d{2}-\d{2}-(.+)$/);
+  return m ? m[1] : best;
+}
+
+async function create(root, opts) {
+  const slug = opts.slug;
+  if (!slug) throw new Error('change.create requires slug');
+  const dir = paths.changeDir(root, slug);
+  if (await exists(dir)) {
+    throw new Error(`change already exists: ${slug}`);
+  }
+  await fs.mkdir(dir, { recursive: true });
+  const st = state.newState(opts);
+  await state.write(root, slug, st);
+  return { slug, dir, state: st };
+}
+
+async function ensureSubdir(root, slug, sub) {
+  const dir = await ensureWorkspaceChangeDir(root, slug);
+  const p = path.join(dir, sub);
+  await fs.mkdir(p, { recursive: true });
+  return p;
+}
+
+async function writeArtifact(root, slug, name, content) {
+  const dir = await ensureWorkspaceChangeDir(root, slug);
+  const file = path.join(dir, name);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, content, 'utf8');
+  return file;
+}
+
+async function readArtifact(root, slug, name) {
+  const workspaceFile = path.join(paths.changeDir(root, slug), name);
+  if (fsSync.existsSync(workspaceFile)) return fs.readFile(workspaceFile, 'utf8');
+  const legacyFile = path.join(legacyChangeDir(root, slug), name);
+  return fs.readFile(legacyFile, 'utf8');
+}
+
+async function hasArtifact(root, slug, name) {
+  if (await exists(path.join(paths.changeDir(root, slug), name))) return true;
+  return exists(path.join(legacyChangeDir(root, slug), name));
+}
+
+function legacyChangesDir(root) {
+  return path.join(paths.devflowDir(root), 'changes');
+}
+
+function legacyArchiveDir(root) {
+  return path.join(paths.devflowDir(root), 'archive');
+}
+
+function legacyChangeDir(root, slug) {
+  return path.join(legacyChangesDir(root), slug);
+}
+
+async function ensureWorkspaceChangeDir(root, slug) {
+  const workspace = paths.changeDir(root, slug);
+  const legacy = legacyChangeDir(root, slug);
+  if (fsSync.existsSync(workspace)) return workspace;
+  if (fsSync.existsSync(legacy)) {
+    try {
+      await fs.mkdir(path.dirname(workspace), { recursive: true });
+      await fs.cp(legacy, workspace, { recursive: true });
+      return workspace;
+    } catch (e) {
+      if (e && (e.code === 'EACCES' || e.code === 'EPERM')) return legacy;
+      throw e;
+    }
+  }
+  await fs.mkdir(workspace, { recursive: true });
+  return workspace;
+}
+
+function resolveChangeDir(root, slug) {
+  const workspace = paths.changeDir(root, slug);
+  const legacy = legacyChangeDir(root, slug);
+  if (fsSync.existsSync(workspace)) return workspace;
+  if (fsSync.existsSync(legacy)) return legacy;
+  return workspace;
+}
+
+function resolveStateFile(root, slug) {
+  return path.join(resolveChangeDir(root, slug), 'state.json');
+}
+
+module.exports = {
+  slugify,
+  currentBranch,
+  withCurrentBranchSlug,
+  listChanges,
+  getCurrent,
+  create,
+  ensureSubdir,
+  writeArtifact,
+  readArtifact,
+  hasArtifact,
+  ensureWorkspaceChangeDir,
+  resolveChangeDir,
+};

package/src/core/checkpoint.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const VALID_STATUS = new Set(['pending', 'resolved', 'cancelled']);
+
+function createCheckpoint(input = {}) {
+  const now = input.createdAt || new Date().toISOString();
+  const type = required(input.type, 'type');
+  const phase = input.phase || null;
+  const options = normalizeOptions(input.options || []);
+  return {
+    id: input.id || makeId(type, now),
+    type,
+    phase,
+    status: input.status || 'pending',
+    summary: input.summary || '',
+    question: input.question || '',
+    options,
+    defaultOption: input.defaultOption || (options[0] && options[0].id) || null,
+    nextAction: input.nextAction || (options[0] && options[0].command) || null,
+    risks: Array.isArray(input.risks) ? input.risks : [],
+    evidence: Array.isArray(input.evidence) ? input.evidence : [],
+    createdAt: now,
+  };
+}
+
+function addCheckpoint(state, checkpointInput) {
+  const checkpoint = createCheckpoint(checkpointInput);
+  state.checkpoints = Array.isArray(state.checkpoints) ? state.checkpoints : [];
+  state.checkpoints.push(checkpoint);
+  return checkpoint;
+}
+
+function resolveCheckpoint(state, id, decision, note) {
+  const checkpoint = findCheckpoint(state, id);
+  if (!checkpoint) throw new Error(`checkpoint not found: ${id}`);
+  checkpoint.status = 'resolved';
+  checkpoint.decision = decision || null;
+  checkpoint.note = note || null;
+  checkpoint.resolvedAt = new Date().toISOString();
+  return checkpoint;
+}
+
+function cancelCheckpoint(state, id, reason) {
+  const checkpoint = findCheckpoint(state, id);
+  if (!checkpoint) throw new Error(`checkpoint not found: ${id}`);
+  checkpoint.status = 'cancelled';
+  checkpoint.reason = reason || null;
+  checkpoint.resolvedAt = new Date().toISOString();
+  return checkpoint;
+}
+
+function latestPending(state) {
+  const checkpoints = Array.isArray(state && state.checkpoints) ? state.checkpoints : [];
+  for (let i = checkpoints.length - 1; i >= 0; i--) {
+    if (normalizeStatus(checkpoints[i].status) === 'pending') return checkpoints[i];
+  }
+  return null;
+}
+
+function latestPendingByType(state, type) {
+  const checkpoints = Array.isArray(state && state.checkpoints) ? state.checkpoints : [];
+  for (let i = checkpoints.length - 1; i >= 0; i--) {
+    const cp = checkpoints[i];
+    if (cp.type === type && normalizeStatus(cp.status) === 'pending') return cp;
+  }
+  return null;
+}
+
+function latestPendingByTypes(state, types) {
+  const wanted = new Set(types || []);
+  const checkpoints = Array.isArray(state && state.checkpoints) ? state.checkpoints : [];
+  for (let i = checkpoints.length - 1; i >= 0; i--) {
+    const cp = checkpoints[i];
+    if (wanted.has(cp.type) && normalizeStatus(cp.status) === 'pending') return cp;
+  }
+  return null;
+}
+
+function hasResolvedDecision(state, type, decision) {
+  const checkpoints = Array.isArray(state && state.checkpoints) ? state.checkpoints : [];
+  return checkpoints.some((cp) => {
+    if (cp.type !== type) return false;
+    if (normalizeStatus(cp.status) !== 'resolved') return false;
+    return decision ? cp.decision === decision : true;
+  });
+}
+
+function renderNextStepCard(checkpoint, result = 'NEEDS_INPUT') {
+  if (!checkpoint) return '';
+  const options = normalizeOptions(checkpoint.options || []);
+  const lines = [
+    '## 下一步',
+    `状态：${result}`,
+    `检查点：${checkpoint.type}`,
+  ];
+  if (checkpoint.phase) lines.push(`阶段：${checkpoint.phase}`);
+  if (checkpoint.summary) lines.push(`摘要：${checkpoint.summary}`);
+  if (checkpoint.question) lines.push(`需要你确认：${checkpoint.question}`);
+  if (options.length) {
+    lines.push('选项：');
+    for (const opt of options) {
+      const pieces = [`- ${opt.id}`];
+      if (opt.label && opt.label !== opt.id) pieces.push(opt.label);
+      if (opt.command) pieces.push(`命令：\`${opt.command}\``);
+      if (opt.description) pieces.push(opt.description);
+      lines.push(pieces.join(' — '));
+    }
+  }
+  const command = checkpoint.nextAction || (options[0] && options[0].command) || '<等待用户选择>';
+  lines.push(`命令：\`${command}\``);
+  if (checkpoint.risks && checkpoint.risks.length) lines.push(`风险：${checkpoint.risks.join('；')}`);
+  return lines.join('\n');
+}
+
+function buildConfirmationCard(checkpoint, options = {}) {
+  if (!checkpoint) return null;
+  const normalized = normalizeOptions(checkpoint.options || []);
+  const primaryId = options.primaryActionId || checkpoint.defaultOption || (normalized[0] && normalized[0].id);
+  const primary = normalized.find((opt) => opt.id === primaryId) || normalized[0] || null;
+  return {
+    type: options.type || `${checkpoint.type}_confirm`,
+    title: options.title || '确认下一步',
+    question: checkpoint.question || '',
+    checkpoint: summarizeCheckpoint(checkpoint),
+    risks: Array.isArray(checkpoint.risks) ? checkpoint.risks.slice() : [],
+    evidence: Array.isArray(checkpoint.evidence) ? checkpoint.evidence.slice() : [],
+    primaryAction: primary ? actionFromOption(primary) : null,
+    secondaryActions: normalized
+      .filter((opt) => !primary || opt.id !== primary.id)
+      .map(actionFromOption),
+  };
+}
+
+function summarizeCheckpoint(checkpoint) {
+  return {
+    id: checkpoint.id,
+    type: checkpoint.type,
+    phase: checkpoint.phase || null,
+    status: checkpoint.status || 'pending',
+    summary: checkpoint.summary || '',
+  };
+}
+
+function actionFromOption(option) {
+  return {
+    id: option.id,
+    label: option.label || option.id,
+    command: option.command || null,
+    description: option.description || '',
+  };
+}
+
+function parseOptions(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return normalizeOptions(value);
+  return String(value)
+    .split(';')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [left, ...rest] = entry.split('=');
+      const id = left.trim();
+      const command = rest.join('=').trim();
+      return { id, label: id, command };
+    });
+}
+
+function normalizeOptions(options) {
+  return options.map((opt) => {
+    if (typeof opt === 'string') return { id: opt, label: opt, command: null, description: '' };
+    const id = required(opt.id || opt.label, 'option.id');
+    return {
+      id,
+      label: opt.label || id,
+      command: opt.command || null,
+      description: opt.description || '',
+    };
+  });
+}
+
+function findCheckpoint(state, id) {
+  const checkpoints = Array.isArray(state && state.checkpoints) ? state.checkpoints : [];
+  return checkpoints.find((c) => c.id === id || c.name === id) || null;
+}
+
+function normalizeStatus(status) {
+  const s = status || 'pending';
+  return VALID_STATUS.has(s) ? s : s === 'passed' ? 'resolved' : s;
+}
+
+function makeId(type, ts) {
+  const nonce = crypto.randomBytes(4).toString('hex');
+  const hash = crypto.createHash('sha1').update(`${type}:${ts}:${nonce}`).digest('hex').slice(0, 8);
+  return `${type}-${hash}`;
+}
+
+function required(value, name) {
+  if (!value) throw new Error(`checkpoint ${name} is required`);
+  return String(value);
+}
+
+module.exports = {
+  createCheckpoint,
+  addCheckpoint,
+  resolveCheckpoint,
+  cancelCheckpoint,
+  latestPending,
+  latestPendingByType,
+  latestPendingByTypes,
+  hasResolvedDecision,
+  renderNextStepCard,
+  buildConfirmationCard,
+  summarizeCheckpoint,
+  parseOptions,
+};