@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/help.js

@@ -0,0 +1,93 @@
+'use strict';
+const log = require('../../utils/log.js');
+
+const TEXT = `
+@chenguangyao/devflow-kit — independent dev workflow
+  command: devflow (short alias: dfk)
+
+USAGE
+  devflow <command> [subcommand] [options] [args]
+
+ENTRY POINTS
+  devflow ingest <url|issue-id|incident:id>   primary: pull source material, draft proposal
+    [--project-root=<dir>[,<dir>]]            use primary project git branch for the change slug
+    [--follow-links] [--max-links=10]         also fetch one-level same-domain/local markdown links
+  devflow new <slug>                          fallback: brainstorm-driven start
+  devflow new <slug> --micro                  L0 path: create plan directly, skip requirement/design/archive
+  devflow new <slug> --level=L0               same as --micro
+    [--project-root=<dir>[,<dir>]]            use primary project git branch for the change slug
+
+LIFECYCLE
+  devflow propose | devflow requirement | devflow design | devflow plan | devflow apply
+  devflow review  | devflow test <kind>  | devflow verify | devflow deploy | devflow deliver | devflow archive
+  devflow requirement --project-root=<dir>[,<dir>]  use/override explicitly selected project roots
+  devflow requirement --search-root=<dir>  auto-route a requirement to projects under a multi-project root
+
+SUBSYSTEMS
+  devflow provider <list|status|add|import|relogin|...>
+  devflow knowledge <init|query|deposit|sync|validate|migrate>
+  devflow skills install [--scope=user|project] [--target=...]
+                              # --scope=user → copy once to ~/.devflow/skills/devflow-kit,
+                              #                 then symlink ~/.cursor + ~/.claude + ~/.agents (all projects share)
+                              # --scope=project → per-repo .cursor/skills + .claude/skills + .agents/skills (default)
+                              # --copy can force user-scope back to physical copies
+                              # all shipped skills are grouped under a single  devflow-kit/  subfolder,
+                              # so other skill collections (e.g. ~/.cursor/skills/superpowers/) stay untouched
+  devflow skills status        # show where skills are installed (and their layout)
+  devflow skills migrate [--scope=user|project]   # move legacy flat layout into  devflow-kit/  subfolder
+  devflow skills uninstall [--scope=user|project] # also scrubs any stray flat-layout leftovers
+  devflow sync project [--check]
+  devflow sync yapi --file=<openapi.json|api.md> [--provider=api.yapi] [--dry-run]
+                              sync API contract to YAPI through api provider
+  devflow logs query [--provider=observability.sls] [--query=...] [--trace-id=...] [--request-id=...]
+                              query SLS/OSS logs for verify/self-test evidence
+  devflow switch project-overview --mode=<reference|supplement|generate>
+  devflow enable / devflow disable <feature>
+
+OPS
+  devflow init [--ide=auto|full|minimal|none]
+                                initialize devflow in current repo
+                                (default --ide=auto: skip per-project IDE files
+                                 when ~/.cursor/skills/devflow-kit/ is installed)
+  devflow update                refresh marker sections
+  devflow uninstall [--purge]   remove devflow integration
+  devflow status                current change overview
+  devflow status set-level <L0|L1|L2|L3> --reason="..."  adjust level; L0 uses micro route
+  devflow status risk <add|resolve|accept|list> <type> --reason="..."
+                                record/close risk signals such as frontend_change, dependency_change, security_sensitive, ci_failure
+  devflow doctor [--scope=...] [--fix] [--json]   7-dimension health check
+  devflow test remote --preflight --api-base-url=<url> --cmd="..."
+                              remote API validation against a deployed test env
+  devflow test joint --preflight --backend-url=<url> --frontend-url=<url> --cmd="..."
+                              frontend/backend joint test with browser-tool preflight
+  devflow test contract --cmd="..."
+                              call-chain/API contract consistency validation
+    [--split-report]          also write legacy reports/<kind>-test.md
+  devflow report compact [--remove-split]
+                              merge existing split reports into reports/test-report.md
+  devflow flow <recommend|draft|suggest|add-step|disable-step|move-step|set-verify|diff|picker|apply-selection|card|check|confirm|explain>
+                              draft and adjust the change workflow from builtin/project recipes
+  devflow deploy test --project=<name>             trigger configured Jenkins test job
+    auto-prompts feature->test merge/push before Jenkins when run from a dev branch
+    [--merge-to=test] [--preflight] [--update-self-test]
+                              non-interactive merge + local compile precheck; opt-in self-test refresh
+  devflow deliver --notify                         email submit body + one reports/test-report.md attachment
+    [--attach-design-plan] [--attach-docs] [--attach-reports]
+                              opt in to design+plan, all docs, or raw report attachments
+  devflow checkpoint <show|add|resolve|cancel> [--json]
+                              structured user decision cards / phase gates
+  devflow version | devflow help [topic]
+
+LEARN MORE
+  See devflow/RFC-001-devflow-kit.md inside the repo, or run "devflow help <command>".
+`;
+
+async function run({ topic } = {}) {
+  if (topic) {
+    log.raw(`(detailed help for "${topic}" not yet written; see RFC for now)`);
+    return;
+  }
+  log.raw(TEXT);
+}
+
+module.exports = { run };

package/src/cli/commands/ingest.js

@@ -0,0 +1,602 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const readline = require('readline');
+const log = require('../../utils/log.js');
+const change = require('../../core/change.js');
+const config = require('../../core/config.js');
+const state = require('../../core/state.js');
+const routing = require('../../core/project-routing.js');
+const checkpoint = require('../../core/checkpoint.js');
+const workflowInit = require('../../core/workflow-init.js');
+const templates = require('../../templates/index.js');
+const providers = require('../../providers/loader.js');
+const lifecycle = require('../../providers/lifecycle.js');
+const { printWorkflowSelectionGuidance } = require('./_helpers.js');
+
+/**
+ * Multi-entry router: classifies the input and dispatches to the right provider.
+ *  - URL (http/https/file)            -> intake
+ *  - PROJ-NUM (e.g. SCRUM-15803)      -> issue
+ *  - incident:<id> / alert:<id>       -> ops/incident
+ *  - else                              -> error
+ */
+
+function classify(input) {
+  if (!input || typeof input !== 'string') return { kind: 'unknown' };
+  if (input.startsWith('http://') || input.startsWith('https://') || input.startsWith('file://')) {
+    return { kind: 'url', value: input };
+  }
+  if (/^[A-Z][A-Z0-9]+-\d+$/.test(input)) {
+    return { kind: 'issue', value: input };
+  }
+  if (/^(incident|alert):/i.test(input)) {
+    return { kind: 'incident', value: input.replace(/^[a-z]+:/i, '') };
+  }
+  if (input.endsWith('.md') || input.startsWith('./') || input.startsWith('../') || input.startsWith('/')) {
+    return { kind: 'url', value: input };
+  }
+  return { kind: 'unknown', value: input };
+}
+
+async function run({ positional = [], flags = {}, cwd, _selectProjectIndices } = {}) {
+  const root = cwd || process.cwd();
+  const input = positional[0];
+  if (!input) {
+    log.error('usage: devflow ingest <url|issue-id|incident:id>');
+    process.exitCode = 2;
+    return;
+  }
+  const { kind, value } = classify(input);
+  if (kind === 'unknown') {
+    log.error(`cannot classify input: ${input}`);
+    log.dim('hint: pass a URL, JIRA-style ID (e.g. SCRUM-15803), or "incident:<id>"');
+    process.exitCode = 2;
+    return;
+  }
+
+  log.info(`ingest type=${kind} value=${value}`);
+
+  let provider;
+  try {
+    provider = await lifecycle.loadOrAuth(root, { type: kind === 'issue' ? 'issue' : 'intake' });
+  } catch (e) {
+    log.error(e.message);
+    if (e.code === 'PROVIDER_NOT_INSTALLED') {
+      log.dim(`hint: run "devflow provider setup" to configure an intake provider`);
+      log.dim(`  or: devflow provider add intake.confluence --type=intake --driver=confluence  (built-in, no extra deps)`);
+      log.dim(`  or: devflow provider add intake.confluence  --type=intake --driver=confluence`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+
+  let fetched;
+  try {
+    fetched = await lifecycle.withAutoRetry(provider, (p) => p.fetch(value));
+  } catch (e) {
+    log.error(`provider ${provider.name} failed: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const linkedRefs = await fetchLinkedRefs(provider, value, fetched.body_md || '', flags);
+  const routingQueryParts = [
+    fetched.title,
+    fetched.body_md,
+    ...linkedRefs.items.map((item) => [item.title, item.body_md].join('\n')),
+  ];
+  if (kind !== 'url') routingQueryParts.push(value);
+  const projectRouting = await resolvePreCreateProjectRouting(
+    root,
+    flags,
+    'ingest',
+    routingQueryParts.join('\n'),
+    { selectProjectIndices: _selectProjectIndices }
+  );
+
+  // Derive slug
+  let slug;
+  if (kind === 'issue') {
+    slug = change.slugify(value + '-' + fetched.title);
+  } else {
+    slug = change.slugify(fetched.title || path.basename(value));
+  }
+  if (flags.slug) slug = change.slugify(flags.slug);
+  const branchRoot = projectRouting && projectRouting.slugBranchSource ? projectRouting.slugBranchSource : root;
+  slug = change.withCurrentBranchSlug(branchRoot, slug);
+
+  const level = flags.level || 'L2';
+  let info;
+  try {
+    info = await change.create(root, {
+      slug,
+      title: fetched.title,
+      level,
+      source: { type: kind === 'issue' ? 'issue' : 'url', ref: value },
+    });
+    await persistProjectRouting(root, slug, info.state, projectRouting, 'ingest');
+  } catch (e) {
+    if (/already exists/.test(e.message)) {
+      log.warn(`change already exists: ${slug} (re-using)`);
+      info = { slug, dir: change.resolveChangeDir(root, slug) };
+      if (projectRouting) {
+        try {
+          const st = await state.read(root, slug);
+          await persistProjectRouting(root, slug, st, projectRouting, 'ingest');
+        } catch (readErr) {
+          log.warn(`project routing not saved: ${readErr.message}`);
+        }
+      }
+    } else { throw e; }
+  }
+  printProjectRouting(projectRouting);
+
+  // refs/<source>-<id>.md
+  const refsDir = await change.ensureSubdir(root, slug, 'refs');
+  let bodyMd = fetched.body_md || '';
+  const savedAssets = await saveImageAttachments(refsDir, fetched.attachments || []);
+  if (savedAssets.length) {
+    bodyMd = rewriteImageRefs(bodyMd, savedAssets);
+  }
+  const refName = kind === 'issue' ? `issue-${value}.md` : `intake-${slugFromValue(value)}.md`;
+  const refFile = path.join(refsDir, refName);
+  await fs.writeFile(refFile, bodyMd, 'utf8');
+  log.ok(`refs/${refName}`);
+  if (savedAssets.length) log.ok(`refs/assets (${savedAssets.length} image${savedAssets.length === 1 ? '' : 's'})`);
+  await writeLinkedRefs(refsDir, linkedRefs);
+
+  // Draft proposal.md
+  const tpl = await templates.load('proposal.md');
+  const body = templates.render(tpl, {
+    slug,
+    title: fetched.title,
+    level,
+    source: value,
+    sourceType: kind,
+    sourceRef: value,
+    summary: extractSummary(bodyMd),
+    date: new Date().toISOString().slice(0, 10),
+  });
+  await change.writeArtifact(root, slug, 'proposal.md', body);
+  log.ok(`proposal: ${path.join(info.dir, 'proposal.md')}`);
+  await ensureProblemCardCheckpoint(root, slug, {
+    title: fetched.title,
+    level,
+    source: value,
+    refName,
+    projectRouting,
+    summary: extractSummary(bodyMd),
+  });
+
+  log.raw('');
+  log.ok(`change ready: ${slug}`);
+  log.dim(`workspace: ${info.dir}`);
+  log.dim('next: resolve the problem_card checkpoint, then confirm this change workflow.');
+  const draftResult = await createEntryWorkflowDraft(root, slug);
+  if (draftResult) {
+    printWorkflowSelectionGuidance(slug);
+  }
+}
+
+async function fetchLinkedRefs(provider, sourceUrl, bodyMd, flags = {}) {
+  if (!isTruthy(flags.followLinks || flags['follow-links'])) {
+    return { enabled: false, items: [], skipped: [] };
+  }
+  const requestedDepth = parseInt(flags.linkDepth || flags['link-depth'] || '1', 10);
+  if (Number.isFinite(requestedDepth) && requestedDepth > 1) {
+    log.warn('ingest linked refs currently supports max depth=1; using 1.');
+  }
+  const maxLinks = clampInt(flags.maxLinks || flags['max-links'], 10, 0, 20);
+  const candidates = extractMarkdownLinks(bodyMd)
+    .map((link) => ({ ...link, resolved: resolveIngestLink(sourceUrl, link.href) }))
+    .filter((link) => link.resolved);
+
+  const seen = new Set();
+  const items = [];
+  const skipped = [];
+  for (const link of candidates) {
+    const resolved = link.resolved;
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    if (!isAllowedLinkedRef(sourceUrl, resolved)) {
+      skipped.push({ label: link.label, url: resolved, reason: '非同域或非本地 markdown 链接' });
+      continue;
+    }
+    if (provider && typeof provider.supports === 'function' && !provider.supports(resolved)) {
+      skipped.push({ label: link.label, url: resolved, reason: '当前 intake provider 不支持该链接' });
+      continue;
+    }
+    if (items.length >= maxLinks) {
+      skipped.push({ label: link.label, url: resolved, reason: `超过本次链接抓取上限 ${maxLinks}` });
+      continue;
+    }
+    try {
+      const fetched = await lifecycle.withAutoRetry(provider, (p) => p.fetch(resolved));
+      items.push({
+        label: link.label,
+        url: resolved,
+        title: fetched.title || link.label || resolved,
+        body_md: fetched.body_md || '',
+        source: fetched.source || { type: 'url', ref: resolved },
+      });
+    } catch (e) {
+      skipped.push({ label: link.label, url: resolved, reason: e.message });
+    }
+  }
+
+  if (items.length) log.ok(`linked refs (${items.length})`);
+  if (skipped.length) log.warn(`linked refs skipped: ${skipped.length}`);
+  return { enabled: true, items, skipped };
+}
+
+async function writeLinkedRefs(refsDir, linkedRefs) {
+  if (!linkedRefs || !linkedRefs.enabled) return;
+  const lines = [
+    '# 链接抓取索引',
+    '',
+    '本文件由 `devflow ingest --follow-links` 自动生成。当前只抓取入口页中的一层同域/本地链接。',
+    '',
+    '## 已抓取',
+    '',
+  ];
+
+  for (const [i, item] of linkedRefs.items.entries()) {
+    const n = String(i + 1).padStart(2, '0');
+    const base = change.slugify(item.title || item.label || `linked-${n}`) || `linked-${n}`;
+    const filename = `linked-${n}-${base}.md`;
+    const content = [
+      `# ${item.title || item.label || item.url}`,
+      '',
+      `- 来源链接：${item.url}`,
+      item.label ? `- 原文标签：${item.label}` : null,
+      '',
+      '---',
+      '',
+      item.body_md || '',
+      '',
+    ].filter((x) => x !== null).join('\n');
+    await fs.writeFile(path.join(refsDir, filename), content, 'utf8');
+    lines.push(`- [x] ${item.label || item.title || item.url} -> ${filename}`);
+  }
+
+  if (!linkedRefs.items.length) lines.push('- 无');
+  lines.push('', '## 跳过', '');
+  for (const item of linkedRefs.skipped || []) {
+    lines.push(`- [ ] ${item.label || item.url} (${item.url})：${item.reason}`);
+  }
+  if (!linkedRefs.skipped.length) lines.push('- 无');
+  lines.push('');
+  await fs.writeFile(path.join(refsDir, 'link-index.md'), lines.join('\n'), 'utf8');
+  log.ok('refs/link-index.md');
+}
+
+async function resolvePreCreateProjectRouting(root, flags, source, query, opts = {}) {
+  const roots = parseRoots(flags.projectRoot || flags['project-root']);
+  if (roots.length) return routing.explicitProjectRouting(roots, { source });
+  if (flags['no-project-routing'] || flags.noProjectRouting) return null;
+
+  const searchRoots = parseRoots(flags.searchRoot || flags['search-root'] || flags.projectsRoot || root);
+  const result = await routing.routeProjects({
+    searchRoots,
+    query,
+    maxDepth: parseInt(flags.projectDepth || flags['project-depth'] || '3', 10),
+    topK: parseInt(flags.projectTopK || flags['project-top-k'] || '5', 10),
+  });
+  if (!result.recommended.length) return null;
+  const projectRouting = {
+    status: 'recommended',
+    source,
+    searchRoots: result.searchRoots,
+    queryTerms: routing.extractTerms(query).slice(0, 20),
+    candidates: result.candidates,
+    recommended: result.recommended,
+    slugBranchSource: result.recommended[0].root,
+  };
+  return maybeSelectProjectRouting(projectRouting, opts);
+}
+
+async function persistProjectRouting(root, slug, st, projectRouting, source) {
+  if (!projectRouting || !st) return st;
+  st.projectRouting = projectRouting;
+  st.projects = projectRouting.recommended;
+  await routing.writeProjectRootsArtifact(root, slug, projectRouting, { source });
+  state.logEvent(st, 'project routing selected', {
+    source,
+    status: projectRouting.status,
+    projects: st.projects.length,
+  });
+  await state.write(root, slug, st);
+  return st;
+}
+
+async function maybeSelectProjectRouting(projectRouting, opts = {}) {
+  if (!projectRouting || projectRouting.candidates.length <= 1) return projectRouting;
+
+  let picks = null;
+  if (typeof opts.selectProjectIndices === 'function') {
+    picks = await opts.selectProjectIndices(projectRouting.candidates);
+  } else if (isTty(opts.stdin || process.stdin, opts.stdout || process.stdout)) {
+    picks = await promptProjectSelection(projectRouting.candidates, opts);
+  }
+  if (!Array.isArray(picks)) return projectRouting;
+  if (!picks.length) return null;
+  return selectProjectRouting(projectRouting, picks);
+}
+
+async function promptProjectSelection(candidates, opts = {}) {
+  log.raw('');
+  log.info('project routing candidates:');
+  for (const [i, p] of candidates.slice(0, 8).entries()) {
+    log.raw(`  ${i + 1}. ${p.name}  confidence=${p.confidence}  ${p.root}`);
+    for (const e of (p.evidence || []).slice(0, 2)) log.dim(`     - ${e}`);
+  }
+  const answer = await ask('select project(s), e.g. "1" or "1,2" [1]: ', opts);
+  return parseProjectSelection(answer, candidates.length);
+}
+
+function selectProjectRouting(projectRouting, picks) {
+  const candidates = projectRouting.candidates || [];
+  const recommended = picks
+    .map((idx) => candidates[idx])
+    .filter(Boolean)
+    .map((p, i) => ({
+      name: p.name,
+      root: p.root,
+      role: i === 0 ? 'primary' : 'dependency',
+      branch: p.branch || change.currentBranch(p.root) || null,
+      confidence: p.confidence,
+      evidence: p.evidence || [],
+    }));
+  if (!recommended.length) return projectRouting;
+  return {
+    ...projectRouting,
+    status: 'selected',
+    recommended,
+    slugBranchSource: recommended[0].root,
+  };
+}
+
+function parseProjectSelection(input, count) {
+  const s = String(input || '').trim().toLowerCase();
+  if (!s) return [0];
+  if (s === 'none' || s === 'no' || s === 'n') return [];
+  if (s === 'all' || s === 'a' || s === '*') {
+    return Array.from({ length: count }, (_, i) => i);
+  }
+  const seen = new Set();
+  for (const tok of s.split(/[,\s]+/)) {
+    const n = parseInt(tok, 10);
+    if (Number.isFinite(n) && n >= 1 && n <= count) seen.add(n - 1);
+  }
+  return Array.from(seen).sort((a, b) => a - b);
+}
+
+function ask(question, opts = {}) {
+  const input = opts.stdin || process.stdin;
+  const output = opts.stdout || process.stdout;
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function isTty(stdin, stdout) {
+  return Boolean(stdin && stdout && stdin.isTTY && stdout.isTTY);
+}
+
+function printProjectRouting(projectRouting) {
+  if (!projectRouting || !projectRouting.candidates.length) return;
+  log.raw('');
+  log.info('project routing recommendations:');
+  for (const [i, p] of projectRouting.candidates.slice(0, 5).entries()) {
+    const mark = projectRouting.recommended.some((r) => r.root === p.root) ? '*' : ' ';
+    log.raw(`  ${mark} ${i + 1}. ${p.name}  confidence=${p.confidence}  ${p.root}`);
+    for (const e of (p.evidence || []).slice(0, 3)) log.dim(`       - ${e}`);
+  }
+  log.dim('override if needed: devflow ingest <input> --project-root=<dir>[,<dir>]');
+}
+
+function parseRoots(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function slugFromValue(v) {
+  return change.slugify(v.replace(/^https?:\/\//, '').replace(/[\/?#].*$/, '')).slice(0, 60);
+}
+
+function extractSummary(md) {
+  if (!md) return '';
+  // Skip first H1 and any frontmatter, take first 5 non-heading paragraphs.
+  let body = md.replace(/^---[\s\S]*?\n---\n/, '');
+  body = body.replace(/^#\s.+\n+/, '');
+  const paras = body.split(/\n\s*\n/).slice(0, 3);
+  return paras.join('\n\n').slice(0, 800);
+}
+
+async function ensureProblemCardCheckpoint(root, slug, details) {
+  const st = await state.read(root, slug);
+  if (checkpoint.latestPendingByType(st, 'problem_card')) return null;
+  if (checkpoint.hasResolvedDecision(st, 'problem_card', 'accept')) return null;
+
+  const projectNames = details.projectRouting && details.projectRouting.recommended && details.projectRouting.recommended.length
+    ? details.projectRouting.recommended.map((p) => `${p.name}:${p.role || 'candidate'}`).join(', ')
+    : '未确认';
+  const summary = `${details.title || slug}；level=${details.level || st.level || 'L2'}；projects=${projectNames}`;
+  const evidence = ['proposal.md'];
+  if (details.refName) evidence.push(`refs/${details.refName}`);
+  const cp = checkpoint.addCheckpoint(st, {
+    type: 'problem_card',
+    phase: 'intake',
+    summary,
+    question: '是否接受当前问题卡、复杂度分级和项目范围，并进入 requirement？',
+    options: [
+      { id: 'accept', label: '接受并进入需求分析', command: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=accept' },
+      { id: 'revise', label: '继续修正问题卡', command: '编辑 proposal.md，必要时重跑 devflow ingest --project-root=...' },
+    ],
+    nextAction: 'devflow checkpoint resolve --id=<checkpoint-id> --decision=accept',
+    evidence,
+    risks: ['未确认问题卡时直接 requirement，容易把错误范围带入后续设计和实现。'],
+  });
+  cp.options = cp.options.map((opt) => opt.id === 'accept'
+    ? { ...opt, command: `devflow checkpoint resolve --id=${cp.id} --decision=accept` }
+    : opt);
+  cp.nextAction = `devflow checkpoint resolve --id=${cp.id} --decision=accept`;
+  state.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+  await state.write(root, slug, st);
+  log.raw('');
+  log.raw(checkpoint.renderNextStepCard(cp));
+  return cp;
+}
+
+async function createEntryWorkflowDraft(root, slug) {
+  try {
+    const cfg = (await config.read(root)) || {};
+    const st = await state.read(root, slug);
+    const result = workflowInit.draftRecommendedWorkflow(root, st, cfg, { auto: true });
+    await state.write(root, slug, st);
+    if (result.created && result.recipe) {
+      log.ok(`workflow draft: ${result.recipe.label} (${result.recipe.id})`);
+    }
+    return result;
+  } catch (e) {
+    log.warn(`workflow draft not created: ${e.message}`);
+    log.dim(`workflow: devflow flow recommend --slug=${slug}`);
+    log.dim(`          devflow flow draft --slug=${slug}`);
+    return null;
+  }
+}
+
+function extractMarkdownLinks(markdown) {
+  const out = [];
+  const re = /(!)?\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  let m;
+  while ((m = re.exec(markdown || '')) !== null) {
+    if (m[1]) continue;
+    const label = (m[2] || '').trim();
+    const href = (m[3] || '').trim();
+    if (!href || href.startsWith('#')) continue;
+    if (/^(mailto|javascript|tel):/i.test(href)) continue;
+    out.push({ label, href });
+  }
+  return out;
+}
+
+function resolveIngestLink(sourceUrl, href) {
+  if (!href) return null;
+  if (/^https?:\/\//i.test(href) || href.startsWith('file://')) return href;
+  if (/^https?:\/\//i.test(sourceUrl)) {
+    try { return new URL(href, sourceUrl).toString(); } catch { return null; }
+  }
+  let base = sourceUrl || '';
+  if (base.startsWith('file://')) base = base.slice(7);
+  if (!base) return null;
+  return path.resolve(path.dirname(path.resolve(base)), href);
+}
+
+function isAllowedLinkedRef(sourceUrl, linkedUrl) {
+  if (!linkedUrl) return false;
+  if (/^https?:\/\//i.test(sourceUrl) && /^https?:\/\//i.test(linkedUrl)) {
+    try {
+      const source = new URL(sourceUrl);
+      const linked = new URL(linkedUrl);
+      return source.origin === linked.origin;
+    } catch { return false; }
+  }
+  if (!/^https?:\/\//i.test(sourceUrl) && !/^https?:\/\//i.test(linkedUrl)) {
+    const p = linkedUrl.startsWith('file://') ? linkedUrl.slice(7) : linkedUrl;
+    return /\.(md|markdown|txt)$/i.test(p);
+  }
+  return false;
+}
+
+function isTruthy(v) {
+  return v === true || v === 'true' || v === '1' || v === 'yes' || v === 'y';
+}
+
+function clampInt(v, def, min, max) {
+  const n = v === undefined || v === null || v === '' ? def : parseInt(String(v), 10);
+  if (!Number.isFinite(n)) return def;
+  return Math.max(min, Math.min(max, n));
+}
+
+async function saveImageAttachments(refsDir, attachments) {
+  const images = (attachments || []).filter((a) => a && a.filename && Buffer.isBuffer(a.data));
+  if (!images.length) return [];
+  const assetsDir = path.join(refsDir, 'assets');
+  await fs.mkdir(assetsDir, { recursive: true });
+  const used = new Set();
+  const saved = [];
+  for (const image of images) {
+    const filename = uniqueFilename(safeFilename(image.filename), used);
+    const abs = path.join(assetsDir, filename);
+    await fs.writeFile(abs, image.data);
+    saved.push({
+      original: image.filename,
+      filename,
+      rel: `assets/${filename}`,
+      abs,
+    });
+  }
+  return saved;
+}
+
+function rewriteImageRefs(markdown, assets) {
+  let out = markdown || '';
+  for (const asset of assets) {
+    const candidates = new Set([
+      asset.original,
+      encodeURI(asset.original),
+      asset.filename,
+      encodeURI(asset.filename),
+    ]);
+    out = out.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (full, alt, src) => {
+      const clean = decodeMaybe(src.trim()).split(/[?#]/)[0];
+      const base = path.basename(clean);
+      if (candidates.has(src.trim()) || candidates.has(clean) || candidates.has(base)) {
+        return `![${alt || asset.original}](${asset.rel})`;
+      }
+      return full;
+    });
+  }
+  return out;
+}
+
+function safeFilename(name) {
+  const ext = path.extname(name) || '.png';
+  const base = path.basename(name, ext)
+    .normalize('NFKC')
+    .replace(/[\\/:*?"<>|\n\r\t]+/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 80) || 'image';
+  return base + ext.toLowerCase();
+}
+
+function uniqueFilename(name, used) {
+  let candidate = name;
+  const ext = path.extname(name);
+  const base = path.basename(name, ext);
+  let i = 2;
+  while (used.has(candidate)) {
+    candidate = `${base}-${i}${ext}`;
+    i++;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+function decodeMaybe(s) {
+  try { return decodeURIComponent(s); }
+  catch { return s; }
+}
+
+module.exports = { run, classify };