@chenguangyao/devflow-kit 0.1.43

package/src/core/config.js

@@ -0,0 +1,60 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const paths = require('./paths.js');
+
+const DEFAULT_CONFIG = {
+  $schema: 'https://devflow.dev/schemas/config.schema.json',
+  version: 1,
+  ide: {
+    targets: ['claude', 'cursor', 'agents'],
+  },
+  projectOverview: {
+    mode: 'reference',
+    candidates: [
+      '.claude/CLAUDE.md',
+      'CLAUDE.md',
+      'PROJECT.md',
+      'AGENTS.md',
+      '.cursor/rules/project.mdc',
+      'docs/project-overview.md',
+      'docs/architecture.md',
+      'README.md',
+    ],
+    referencedFile: null,
+  },
+  knowledge: {
+    layout: 'improved-9',
+    domains: ['1-domain', '2-system', '3-ops', '4-archive'],
+  },
+  defaults: {
+    level: 'L2',
+    workflow: 'standard',
+    branchPrefix: 'feature',
+  },
+};
+
+async function read(root) {
+  const file = paths.configFile(root);
+  if (!fsSync.existsSync(file)) return null;
+  const buf = await fs.readFile(file, 'utf8');
+  return JSON.parse(buf);
+}
+
+async function write(root, cfg) {
+  const file = paths.configFile(root);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+
+async function ensure(root) {
+  let cfg = await read(root);
+  if (!cfg) {
+    cfg = JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+    await write(root, cfg);
+  }
+  return cfg;
+}
+
+module.exports = { DEFAULT_CONFIG, read, write, ensure };

package/src/core/delta.js

@@ -0,0 +1,290 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const paths = require('./paths.js');
+
+/**
+ * Supported section labels (case-insensitive).
+ * Both "Requirements" (legacy) and "Capabilities" (OpenSpec) are accepted.
+ */
+const SECTION_RE = /^##\s+(ADDED|MODIFIED|REMOVED)\s+(Capabilities?|Requirements?)\s*$/i;
+
+/**
+ * Parse YAML-ish frontmatter from a markdown file.
+ * Only reads simple "key: value" pairs (no nesting).
+ * Returns { capability?, slug?, [key]: value }
+ */
+function parseFrontmatter(md) {
+  const m = /^---\s*\n([\s\S]*?)\n---/.exec(md);
+  if (!m) return {};
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const kv = /^(\w[\w-]*):\s*(.+)$/.exec(line.trim());
+    if (kv) meta[kv[1]] = kv[2].trim();
+  }
+  return meta;
+}
+
+/**
+ * Parse a single OpenSpec delta markdown file.
+ * Handles both:
+ *   ## ADDED Requirements   (OpenSpec Requirements format)
+ *   ## ADDED Capabilities   (legacy compatibility)
+ *
+ * Returns:
+ *   {
+ *     meta: { capability?, slug? },
+ *     added:    [{ heading, body }],
+ *     modified: [{ heading, body }],
+ *     removed:  [{ heading, body }],
+ *     rejected: [{ heading, body }],   // REJECTED Alternatives — appended verbatim
+ *   }
+ */
+function parseDelta(md) {
+  const result = { meta: parseFrontmatter(md), added: [], modified: [], removed: [], rejected: [] };
+  const lines = md.split(/\r?\n/);
+  let section = null;
+  let item = null;
+
+  for (const line of lines) {
+    // Section header: ## ADDED Requirements / ## MODIFIED Capabilities / etc.
+    const m2 = SECTION_RE.exec(line);
+    if (m2) {
+      section = m2[1].toLowerCase();  // 'added' | 'modified' | 'removed'
+      item = null;
+      continue;
+    }
+    // REJECTED Alternatives section
+    if (/^##\s+REJECTED\s+Alternatives?\s*$/i.test(line)) {
+      section = 'rejected';
+      item = null;
+      continue;
+    }
+
+    if (!section) continue;
+
+    // Sub-heading starts a new item block
+    const m3 = /^###\s+(.*?)\s*$/.exec(line);
+    if (m3) {
+      item = { heading: m3[1].trim(), body: '' };
+      result[section].push(item);
+      continue;
+    }
+
+    if (item) item.body += (item.body ? '\n' : '') + line;
+  }
+  return result;
+}
+
+/**
+ * Apply parsed delta to a target spec markdown (OpenSpec format).
+ *
+ * - ADDED Requirements   → append under "## Requirements" section
+ * - MODIFIED Requirements → find `### heading`; replace body until next heading
+ * - REMOVED Requirements  → drop `### heading` + body
+ * - REJECTED Alternatives → append under "## REJECTED Alternatives" section
+ *
+ * Returns { content, conflicts: [{ heading, kind, reason }] }
+ */
+function applyToSpec(specMd, parsed) {
+  let content = specMd || '';
+  const conflicts = [];
+  let lines = content.split(/\r?\n/);
+
+  const findHeading = (heading) => {
+    for (let i = 0; i < lines.length; i++) {
+      if (/^###\s+/.test(lines[i]) && lines[i].slice(4).trim() === heading) return i;
+    }
+    return -1;
+  };
+  const blockEnd = (start) => {
+    for (let j = start + 1; j < lines.length; j++) {
+      if (/^##?#\s+/.test(lines[j])) return j;
+    }
+    return lines.length;
+  };
+
+  // REMOVED first (so MODIFIED doesn't operate on deleted blocks)
+  for (const it of parsed.removed) {
+    const idx = findHeading(it.heading);
+    if (idx === -1) {
+      conflicts.push({ heading: it.heading, kind: 'removed', reason: 'heading not found' });
+      continue;
+    }
+    lines.splice(idx, blockEnd(idx) - idx);
+  }
+
+  // MODIFIED
+  for (const it of parsed.modified) {
+    const idx = findHeading(it.heading);
+    if (idx === -1) {
+      conflicts.push({ heading: it.heading, kind: 'modified', reason: 'heading not found' });
+      continue;
+    }
+    const newBlock = (`### ${it.heading}\n` + it.body.replace(/^\n+|\n+$/g, '')).split('\n');
+    lines.splice(idx, blockEnd(idx) - idx, ...newBlock, '');
+  }
+
+  // ADDED Requirements → append into the OpenSpec Requirements section.
+  if (parsed.added.length) {
+    let reqIdx = lines.findIndex((l) => /^##\s+Requirements?\s*$/.test(l));
+    if (reqIdx === -1) {
+      if (lines.length === 0 || lines[lines.length - 1] !== '') lines.push('');
+      lines.push('## Requirements', '');
+      reqIdx = lines.length - 2;
+    }
+
+    let insertAt = lines.length;
+    for (let i = reqIdx + 1; i < lines.length; i++) {
+      if (/^##\s+/.test(lines[i])) {
+        insertAt = i;
+        break;
+      }
+    }
+
+    const blocks = [];
+    if (insertAt > 0 && lines[insertAt - 1] !== '') blocks.push('');
+    for (const it of parsed.added) {
+      blocks.push(`### ${it.heading}`);
+      if (it.body) blocks.push(it.body.replace(/^\n+|\n+$/g, ''));
+      blocks.push('');
+    }
+    lines.splice(insertAt, 0, ...blocks);
+  }
+
+  // REJECTED Alternatives → append / merge into dedicated section
+  if (parsed.rejected.length) {
+    if (lines.length === 0 || lines[lines.length - 1] !== '') lines.push('');
+    const rejIdx = lines.findIndex((l) => /^##\s+REJECTED\s+Alternatives?/.test(l));
+    if (rejIdx === -1) lines.push('## REJECTED Alternatives', '');
+    for (const it of parsed.rejected) {
+      lines.push(`### ${it.heading}`);
+      if (it.body) lines.push(it.body.replace(/^\n+|\n+$/g, ''));
+      lines.push('');
+    }
+  }
+
+  return { content: lines.join('\n'), conflicts };
+}
+
+/**
+ * Resolve the target spec path for a delta file.
+ *
+ * Priority:
+ *   1. frontmatter `capability:` field  e.g. "coupon/grant" → specs/coupon/spec.md
+ *   2. filename (basename without .md)  e.g. "coupon-grant.md" → specs/coupon-grant.md
+ *
+ * The `capability` value supports:
+ *   - Simple:   "coupon"             → specs/coupon/spec.md
+ *   - Nested:   "coupon/grant"       → specs/coupon/spec.md
+ *   - Deep:     "payment/alipay/v2"  → specs/payment/spec.md
+ */
+function resolveSpecTarget(specsRoot, deltaFile, meta) {
+  const cap = (meta.capability || '').trim().replace(/\.md$/, '');
+  if (cap) {
+    const domain = cap.split('/').filter(Boolean)[0];
+    if (domain) return path.join(specsRoot, domain, 'spec.md');
+  }
+  // fallback: use basename (legacy behaviour)
+  return path.join(specsRoot, path.basename(deltaFile));
+}
+
+/**
+ * Scaffold content for a brand-new spec file (no existing content).
+ * Uses the spec domain from path for the title.
+ */
+function newSpecContent(specPath, slug) {
+  const isDomainSpec = path.basename(specPath) === 'spec.md';
+  const name = (isDomainSpec ? path.basename(path.dirname(specPath)) : path.basename(specPath, '.md')).replace(/-/g, ' ');
+  return [
+    `<!-- auto-created by devflow archive -->`,
+    `<!-- edit via devflow/changes/<slug>/delta/ — do not edit directly -->`,
+    '',
+    `# ${name} Specification`,
+    '',
+    `## Purpose`,
+    '',
+    `TBD - created by archiving change ${slug}. Update Purpose after archive.`,
+    '',
+    `## Requirements`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Recursively collect all *.md files under a directory.
+ */
+async function collectDeltaFiles(dir) {
+  const out = [];
+  if (!fsSync.existsSync(dir)) return out;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...await collectDeltaFiles(full));
+    } else if (e.name.endsWith('.md') && e.name !== 'sample-capability.md') {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Merge all delta/*.md (recursive) from a change folder into devflow/specs/.
+ *
+ * Target path is determined per-file by `capability` frontmatter:
+ *   capability: coupon/grant  →  specs/coupon/spec.md
+ *   capability: order         →  specs/order/spec.md
+ *   (no capability)           →  specs/<filename>.md  (legacy)
+ *
+ * Returns { merged: [{ file, target }], conflicts: [{ file, conflicts }] }
+ */
+async function mergeChangeDeltas(root, slug, opts = {}) {
+  const deltaDir = path.join(paths.changeDir(root, slug), 'delta');
+  const deltaFiles = await collectDeltaFiles(deltaDir);
+
+  if (!deltaFiles.length) return { merged: [], conflicts: [] };
+
+  const specsDir = paths.specsDir(root);
+  const merged = [];
+  const allConflicts = [];
+
+  for (const absFile of deltaFiles) {
+    const md = await fs.readFile(absFile, 'utf8');
+    const parsed = parseDelta(md);
+
+    // Skip files that have no capability changes at all
+    const isEmpty = !parsed.added.length && !parsed.modified.length
+                 && !parsed.removed.length && !parsed.rejected.length;
+    if (isEmpty) continue;
+
+    const target = resolveSpecTarget(specsDir, path.basename(absFile), parsed.meta);
+
+    let existing = '';
+    if (fsSync.existsSync(target)) {
+      existing = await fs.readFile(target, 'utf8');
+    } else {
+      existing = newSpecContent(target, slug);
+    }
+
+    const { content, conflicts } = applyToSpec(existing, parsed);
+
+    if (conflicts.length && !opts.force) {
+      allConflicts.push({ file: path.relative(root, absFile), conflicts });
+      continue;
+    }
+
+    if (!opts.dryRun) {
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      const header = `<!-- merged-from: change=${slug}  ts=${new Date().toISOString()} -->\n`;
+      const needsHeader = !content.includes('merged-from:');
+      await fs.writeFile(target, needsHeader ? header + content : content, 'utf8');
+    }
+    merged.push({ file: path.relative(root, absFile), target });
+  }
+
+  return { merged, conflicts: allConflicts };
+}
+
+module.exports = { parseDelta, applyToSpec, mergeChangeDeltas, parseFrontmatter, resolveSpecTarget };

package/src/core/markers.js

@@ -0,0 +1,59 @@
+'use strict';
+const fs = require('fs/promises');
+const path = require('path');
+
+function begin(name) { return `<!-- BEGIN devflow:${name} -->`; }
+function end(name) { return `<!-- END devflow:${name} -->`; }
+
+/**
+ * Idempotently upsert a marker section in a markdown file.
+ * If file does not exist, creates it with just the section.
+ */
+async function upsertSection(file, name, body, opts = {}) {
+  const header = opts.header || '';
+  const beginTag = begin(name);
+  const endTag = end(name);
+  const block = `${beginTag}\n${body}\n${endTag}`;
+
+  let content = '';
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  if (content.includes(beginTag) && content.includes(endTag)) {
+    const re = new RegExp(escapeRe(beginTag) + '[\\s\\S]*?' + escapeRe(endTag), 'm');
+    content = content.replace(re, block);
+  } else {
+    if (content && !content.endsWith('\n')) content += '\n';
+    content += (content ? '\n' : header ? header + '\n\n' : '') + block + '\n';
+  }
+
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, content, 'utf8');
+  return file;
+}
+
+async function removeSection(file, name) {
+  const beginTag = begin(name);
+  const endTag = end(name);
+  let content;
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return false;
+    throw e;
+  }
+  const re = new RegExp('\\n*' + escapeRe(beginTag) + '[\\s\\S]*?' + escapeRe(endTag) + '\\n*', 'm');
+  if (!re.test(content)) return false;
+  content = content.replace(re, '\n');
+  await fs.writeFile(file, content, 'utf8');
+  return true;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { begin, end, upsertSection, removeSection };

package/src/core/paths.js

@@ -0,0 +1,173 @@
+'use strict';
+const path = require('path');
+const fs = require('fs');
+
+const DEVFLOW_DIR = 'devflow';
+
+function repoRoot(start) {
+  let cur = start || process.cwd();
+  // Search for .git or devflow/ marker upward
+  for (let i = 0; i < 32; i++) {
+    if (
+      fs.existsSync(path.join(cur, '.git')) ||
+      fs.existsSync(path.join(cur, DEVFLOW_DIR, 'config.json'))
+    ) {
+      return cur;
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  // Fallback: cwd
+  return start || process.cwd();
+}
+
+function devflowDir(root) {
+  return path.join(root, DEVFLOW_DIR);
+}
+
+function specsDir(root) {
+  return path.join(devflowDir(root), 'specs');
+}
+
+function knowledgeDir(root) {
+  return path.join(devflowDir(root), 'knowledge');
+}
+
+function changesDir(root) {
+  return path.join(workspaceBaseDir(), 'changes');
+}
+
+function archiveDir(root) {
+  return path.join(workspaceBaseDir(), 'archive');
+}
+
+function changeDir(root, slug) {
+  return path.join(changesDir(root), slug);
+}
+
+function stateFile(root, slug) {
+  return path.join(changeDir(root, slug), 'state.json');
+}
+
+function configFile(root) {
+  return path.join(devflowDir(root), 'config.json');
+}
+
+function projectProvidersFile(root) {
+  return path.join(devflowDir(root), 'providers.json');
+}
+
+function userConfigDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.devflow');
+}
+
+function legacyUserConfigDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.config', 'devflow');
+}
+
+function userProvidersFile() {
+  return path.join(userConfigDir(), 'providers.json');
+}
+
+function userProvidersExampleFile() {
+  return path.join(userConfigDir(), 'providers.example.json');
+}
+
+function userProjectsFile() {
+  return path.join(userConfigDir(), 'projects.json');
+}
+
+function legacyUserProvidersFile() {
+  return path.join(legacyUserConfigDir(), 'providers.json');
+}
+
+function legacyUserProjectsFile() {
+  return path.join(legacyUserConfigDir(), 'projects.json');
+}
+
+function workspaceBaseDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.devflow', 'workspace');
+}
+
+function workspaceKnowledgeRoot() {
+  return path.join(workspaceBaseDir(), 'knowledge');
+}
+
+function safeWorkspaceSlug(slug) {
+  return String(slug || 'change')
+    .normalize('NFKC')
+    .replace(/[^a-zA-Z0-9\u4e00-\u9fa5-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 80) || 'change';
+}
+
+function workspaceDir(slug) {
+  const base = workspaceBaseDir();
+  const safe = safeWorkspaceSlug(slug);
+  const changesBase = path.join(base, 'changes');
+  if (fs.existsSync(changesBase)) {
+    const entries = fs.readdirSync(changesBase, { withFileTypes: true });
+    const existing = entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .find((name) => name === safe);
+    if (existing) return path.join(changesBase, existing);
+  }
+  return path.join(changesBase, safe);
+}
+
+function workspaceChangesDir(slug) {
+  return workspaceDir(slug);
+}
+
+function workspaceKnowledgeDir(slug) {
+  return path.join(workspaceDir(slug), 'knowledge');
+}
+
+function workspaceArchiveDir(slug) {
+  const date = new Date().toISOString().slice(0, 10);
+  return path.join(workspaceBaseDir(), 'archive', `${date}-${safeWorkspaceSlug(slug)}`);
+}
+
+function worktreesDir(root) {
+  return path.join(root, '.devflow-worktrees');
+}
+
+function worktreePath(root, slug, taskId) {
+  if (!taskId) return path.join(worktreesDir(root), slug);
+  return path.join(worktreesDir(root), slug, taskId);
+}
+
+module.exports = {
+  DEVFLOW_DIR,
+  repoRoot,
+  devflowDir,
+  specsDir,
+  knowledgeDir,
+  changesDir,
+  archiveDir,
+  changeDir,
+  stateFile,
+  configFile,
+  projectProvidersFile,
+  userConfigDir,
+  legacyUserConfigDir,
+  userProvidersFile,
+  userProvidersExampleFile,
+  userProjectsFile,
+  legacyUserProvidersFile,
+  legacyUserProjectsFile,
+  workspaceBaseDir,
+  workspaceKnowledgeRoot,
+  workspaceDir,
+  workspaceChangesDir,
+  workspaceKnowledgeDir,
+  workspaceArchiveDir,
+  worktreesDir,
+  worktreePath,
+};

package/src/core/plan-tasks.js

@@ -0,0 +1,36 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const change = require('./change.js');
+
+function readPlanTaskIds(root, slug) {
+  const file = path.join(change.resolveChangeDir(root, slug), 'plan.md');
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf8');
+  return parsePlanTaskIds(content);
+}
+
+function parsePlanTaskIds(content) {
+  const headingIds = collectTaskIds(content, /^#{2,6}\s+(?:Task\s*)?(?:T|task)-0*(\d+)\b/gim);
+  if (headingIds.length) return headingIds;
+
+  const tableIds = collectTaskIds(content, /^\|\s*(?:T|task)-0*(\d+)\s*\|/gim);
+  if (tableIds.length) return tableIds;
+
+  return collectTaskIds(content, /\b(?:T|task)-0*(\d+)\b/gi);
+}
+
+function collectTaskIds(content, re) {
+  const ids = [];
+  const seen = new Set();
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const id = `task-${parseInt(m[1], 10)}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+
+module.exports = { readPlanTaskIds, parsePlanTaskIds };