@chenguangyao/devflow-kit 0.1.43

package/src/core/worktree.js

@@ -0,0 +1,241 @@
+'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 stateMod = require('./state.js');
+const autodetect = require('./autodetect.js');
+
+/**
+ * worktree-swarm: per-task git worktree isolation for the apply phase.
+ *
+ * Layout (under repo root):
+ *   .devflow-worktrees/<slug>/                       — single worktree (no --task)
+ *   .devflow-worktrees/<slug>/task-<id>/             — per-task worktrees
+ *
+ * Branch naming:
+ *   devflow/<slug>                — single
+ *   devflow/<slug>/task-<id>      — per-task
+ *
+ * State (changes/<slug>/state.json):
+ *   phases.apply.tasks: [{ id, title, worktree, branch, status, started_at, ended_at, notes[] }]
+ *
+ * Status lifecycle: pending → in_progress → done (or skipped/failed)
+ */
+
+function git(args, cwd) {
+  return cp.spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function isGitRepo(root) {
+  if (!fsSync.existsSync(path.join(root, '.git'))) return false;
+  return true;
+}
+
+function ensureTaskBucket(state) {
+  state.phases = state.phases || {};
+  state.phases.apply = state.phases.apply || { status: 'pending' };
+  state.phases.apply.tasks = state.phases.apply.tasks || [];
+  state.phases.apply.iterations = state.phases.apply.iterations || 0;
+  return state.phases.apply;
+}
+
+function findTask(state, taskId) {
+  const apply = ensureTaskBucket(state);
+  return apply.tasks.find((t) => t.id === taskId);
+}
+
+function branchNameFor(slug, taskId) {
+  return taskId ? `devflow/${slug}/${taskId}` : `devflow/${slug}`;
+}
+
+function worktreeFor(root, slug, taskId) {
+  return paths.worktreePath(root, slug, taskId);
+}
+
+/**
+ * Create a worktree for a task.
+ * Idempotent: if the worktree already exists, returns existing record.
+ */
+async function create(root, slug, opts = {}) {
+  if (!isGitRepo(root)) throw new Error('not a git repo — cannot create worktree');
+  const taskId = normaliseTaskId(opts.task);
+  const wtPath = worktreeFor(root, slug, taskId);
+  const branch = opts.branch || branchNameFor(slug, taskId);
+  // Base resolution: explicit opt > current checked-out branch (normal case
+  // when user runs `devflow apply` from their feature branch) > autodetected
+  // default branch (covers repos that use `master` instead of `main`).
+  const base = opts.base || currentBranch(root) || autodetect.detectDefaultBranch(root);
+  const title = opts.title || (taskId ? `task ${taskId}` : 'main');
+
+  const state = await stateMod.read(root, slug);
+  const apply = ensureTaskBucket(state);
+  let task = findTask(state, taskId || 'main');
+
+  // Already exists?
+  if (fsSync.existsSync(wtPath)) {
+    if (!task) {
+      task = recordTask(apply, taskId || 'main', { title, worktree: wtPath, branch });
+      await stateMod.write(root, slug, state);
+    }
+    return { created: false, path: wtPath, branch, task };
+  }
+
+  // Ensure parent dir
+  await fs.mkdir(path.dirname(wtPath), { recursive: true });
+
+  // Create branch if missing
+  const branchExists = git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], root).status === 0;
+  const args = ['worktree', 'add'];
+  if (!branchExists) args.push('-b', branch);
+  args.push(wtPath);
+  if (!branchExists) args.push(base);
+  else args.push(branch);
+
+  const r = git(args, root);
+  if (r.status !== 0) {
+    throw new Error(`git worktree add failed: ${(r.stderr || r.stdout || '').trim()}`);
+  }
+
+  task = recordTask(apply, taskId || 'main', { title, worktree: wtPath, branch });
+  apply.status = apply.status === 'done' ? 'in_progress' : (apply.status || 'in_progress');
+  if (state.currentPhase === 'plan' || state.currentPhase === 'review') {
+    state.currentPhase = 'apply';
+  }
+  stateMod.logEvent(state, 'worktree.create', { task: task.id, path: wtPath, branch });
+  await stateMod.write(root, slug, state);
+
+  return { created: true, path: wtPath, branch, task };
+}
+
+function recordTask(apply, id, fields) {
+  const now = new Date().toISOString();
+  const existing = apply.tasks.find((t) => t.id === id);
+  if (existing) {
+    Object.assign(existing, fields, { updated_at: now });
+    return existing;
+  }
+  const t = {
+    id,
+    title: fields.title || id,
+    worktree: fields.worktree,
+    branch: fields.branch,
+    status: 'pending',
+    started_at: now,
+    notes: [],
+  };
+  apply.tasks.push(t);
+  return t;
+}
+
+/**
+ * List all worktrees for a slug, or for all slugs if slug omitted.
+ * Cross-references git's own worktree list with our state.json records.
+ */
+async function list(root, slug) {
+  const gitList = parseGitWorktrees(root);
+  const out = [];
+  if (slug) {
+    const state = await stateMod.read(root, slug).catch(() => null);
+    const apply = state ? ensureTaskBucket(state) : { tasks: [] };
+    for (const t of apply.tasks) {
+      out.push({
+        slug,
+        task: t.id,
+        path: t.worktree,
+        branch: t.branch,
+        status: t.status,
+        gitTracked: gitList.some((g) => g.path === t.worktree),
+      });
+    }
+    return out;
+  }
+  // All slugs
+  const changesDir = paths.changesDir(root);
+  if (!fsSync.existsSync(changesDir)) return [];
+  const slugs = (await fs.readdir(changesDir)).filter((d) =>
+    fsSync.statSync(path.join(changesDir, d)).isDirectory()
+  );
+  for (const s of slugs) {
+    const inner = await list(root, s);
+    out.push(...inner);
+  }
+  return out;
+}
+
+function parseGitWorktrees(root) {
+  const r = git(['worktree', 'list', '--porcelain'], root);
+  if (r.status !== 0) return [];
+  const out = [];
+  let cur = null;
+  for (const line of (r.stdout || '').split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) out.push(cur);
+      cur = { path: line.slice('worktree '.length).trim() };
+    } else if (line.startsWith('branch ')) {
+      cur && (cur.branch = line.slice('branch '.length).trim());
+    } else if (line.startsWith('HEAD ')) {
+      cur && (cur.head = line.slice('HEAD '.length).trim());
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/**
+ * Cleanup a worktree (and optionally its branch).
+ */
+async function cleanup(root, slug, opts = {}) {
+  const taskId = normaliseTaskId(opts.task) || 'main';
+  const state = await stateMod.read(root, slug).catch(() => null);
+  if (!state) throw new Error(`no state for slug: ${slug}`);
+  const apply = ensureTaskBucket(state);
+  const idx = apply.tasks.findIndex((t) => t.id === taskId);
+  if (idx === -1) throw new Error(`no task recorded: ${taskId}`);
+  const task = apply.tasks[idx];
+
+  // git worktree remove (force if dirty unless --no-force)
+  const removeArgs = ['worktree', 'remove'];
+  if (opts.force !== false) removeArgs.push('--force');
+  removeArgs.push(task.worktree);
+  const r = git(removeArgs, root);
+  // Tolerant: if path doesn't exist anymore, prune and continue.
+  if (r.status !== 0 && !/is not a working tree/.test(r.stderr || '')) {
+    git(['worktree', 'prune'], root);
+  }
+
+  // Delete branch unless asked to keep
+  if (!opts.keepBranch) {
+    git(['branch', '-D', task.branch], root);
+  }
+
+  apply.tasks.splice(idx, 1);
+  stateMod.logEvent(state, 'worktree.cleanup', { task: taskId, branch: task.branch, kept: !!opts.keepBranch });
+  await stateMod.write(root, slug, state);
+
+  return { removed: true, branch: task.branch, kept: !!opts.keepBranch };
+}
+
+function currentBranch(root) {
+  const r = git(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+  if (r.status !== 0) return null;
+  const b = (r.stdout || '').trim();
+  return b === 'HEAD' ? null : b;
+}
+
+function normaliseTaskId(t) {
+  if (t === undefined || t === null || t === '' || t === false) return null;
+  const s = String(t);
+  if (/^\d+$/.test(s)) return `task-${s}`;
+  if (/^T-0*\d+$/i.test(s)) return `task-${parseInt(s.slice(2), 10)}`;
+  if (/^task-/.test(s)) return s;
+  return s.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+module.exports = {
+  create, list, cleanup,
+  branchNameFor, worktreeFor, normaliseTaskId,
+  parseGitWorktrees, currentBranch,
+  findTask, ensureTaskBucket,
+};

package/src/knowledge/categories.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Canonical mapping: English slug → WeKnora tag info.
+ *
+ * `name` is BOTH the WeKnora tag label AND the local directory name:
+ *   devflow/knowledge/
+ *     架构决策/    接口契约/    服务信息/
+ *     领域概念/    业务规则/    业务场景/
+ *     环境配置/    故障复盘/    运维手册/
+ *     解决方案/
+ *
+ * Colors follow WeKnora palette; grouped by domain tier:
+ *   domain  → blue   (#1890ff)
+ *   system  → green  (#52c41a)
+ *   ops     → orange (#fa8c16)
+ *   archive → gray   (#8c8c8c)
+ */
+const CATEGORY_TAG_NAMES = {
+  // ── domain ──────────────────────────────────────────
+  concepts:     { name: '领域概念', color: '#1890ff', order: 10 },
+  rules:        { name: '业务规则', color: '#096dd9', order: 11 },
+  scenarios:    { name: '业务场景', color: '#40a9ff', order: 12 },
+
+  // ── system ──────────────────────────────────────────
+  contracts:    { name: '接口契约', color: '#52c41a', order: 20 },
+  decisions:    { name: '架构决策', color: '#389e0d', order: 21 },
+  services:     { name: '服务信息', color: '#73d13d', order: 22 },
+
+  // ── ops ─────────────────────────────────────────────
+  environments: { name: '环境配置', color: '#fa8c16', order: 30 },
+  incidents:    { name: '故障复盘', color: '#d4380d', order: 31 },
+  runbooks:     { name: '运维手册', color: '#ffa940', order: 32 },
+
+  // ── archive ─────────────────────────────────────────
+  solutions:    { name: '解决方案', color: '#8c8c8c', order: 40 },
+};
+
+/** Reverse map: Chinese name → CATEGORY_TAG_NAMES entry (for directory-based lookups). */
+const BY_CHINESE_NAME = Object.fromEntries(
+  Object.values(CATEGORY_TAG_NAMES).map((v) => [v.name, v]),
+);
+const SLUG_BY_CHINESE_NAME = Object.fromEntries(
+  Object.entries(CATEGORY_TAG_NAMES).map(([slug, v]) => [v.name, slug]),
+);
+
+const DEFAULT_COLOR = '#bfbfbf';
+const DEFAULT_ORDER = 99;
+
+/**
+ * Resolve tag info for a given category identifier.
+ *
+ * Accepts:
+ *   - English slug:            "decisions", "contracts"
+ *   - Legacy domain/category:  "2-system/decisions"
+ *   - Chinese directory name:  "架构决策", "接口契约"
+ *
+ * @param {string} categoryId
+ * @param {string} [tagNameHint]  optional override from .meta.json tag_name
+ */
+function buildTagMap(overrides = {}) {
+  const out = {};
+  for (const [slug, info] of Object.entries(CATEGORY_TAG_NAMES)) {
+    out[slug] = { ...info, ...(overrides[slug] || {}) };
+  }
+  for (const [slug, info] of Object.entries(overrides || {})) {
+    if (!out[slug]) out[slug] = {
+      name: info.name || slug,
+      color: info.color || DEFAULT_COLOR,
+      order: info.order || DEFAULT_ORDER,
+    };
+  }
+  return out;
+}
+
+function resolveTagInfo(categoryId, tagNameHint, tagMap = CATEGORY_TAG_NAMES) {
+  // Strip legacy domain prefix
+  const slug = (typeof categoryId === 'string' && categoryId.includes('/'))
+    ? categoryId.split('/').pop()
+    : categoryId;
+
+  // English slug lookup
+  const bySlug = tagMap[slug];
+  if (bySlug) {
+    return { ...bySlug };
+  }
+
+  // Chinese name lookup (used when walking directories named after Chinese tags).
+  // Resolve through the canonical slug first so provider-specific tag overrides apply.
+  const canonicalSlug = SLUG_BY_CHINESE_NAME[slug];
+  if (canonicalSlug && tagMap[canonicalSlug]) return { ...tagMap[canonicalSlug] };
+  if (canonicalSlug && BY_CHINESE_NAME[slug]) return { ...BY_CHINESE_NAME[slug] };
+
+  if (tagNameHint) return { name: tagNameHint, color: DEFAULT_COLOR, order: DEFAULT_ORDER };
+  return { name: slug, color: DEFAULT_COLOR, order: DEFAULT_ORDER };
+}
+
+/**
+ * Return the directory name for a given English category slug.
+ * e.g. categoryDir('decisions') → '架构决策'
+ */
+function categoryDir(slug) {
+  const entry = CATEGORY_TAG_NAMES[slug];
+  return entry ? entry.name : slug;
+}
+
+module.exports = { CATEGORY_TAG_NAMES, BY_CHINESE_NAME, buildTagMap, resolveTagInfo, categoryDir };

package/src/knowledge/classify.js

@@ -0,0 +1,125 @@
+'use strict';
+/**
+ * Rules-based classifier: given an extracted knowledge entry from a change folder,
+ * decide which (domain, category) under devflow/knowledge/ it belongs to.
+ *
+ * Inputs:
+ *   {
+ *     artifact:  string  // 'knowledge/<category>/*.md' | 'design.md' | 'reports/incident-*.md' | ...
+ *     section:   string  // section heading
+ *     content:   string  // raw markdown
+ *     hints:     object  // optional override: { domain, category }
+ *   }
+ *
+ * Output:
+ *   { domain, category, suggestedFilename, confidence, reasons[] }
+ *
+ * Order of precedence:
+ *   1. explicit hint
+ *   2. artifact-based mapping
+ *   3. section/keyword heuristics
+ *   4. default to '4-archive/solutions'
+ */
+
+const ARTIFACT_RULES = [
+  // Incidents and runbooks live under ops.
+  { match: /(^|\/)incident[-_]?.*\.md$/i,        domain: '3-ops', category: 'incidents' },
+  { match: /(^|\/)runbook|sop[-_]?/i,            domain: '3-ops', category: 'runbooks' },
+  // Design / ADR and contracts live under system.
+  { match: /(^|\/)adr[-_]?\d*/i,                 domain: '2-system', category: 'decisions' },
+  { match: /(^|\/)contract[-_]|api[-_]?spec/i,   domain: '2-system', category: 'contracts' },
+  { match: /(^|\/)design\.md$/i,                 domain: '2-system', category: 'decisions' },
+  // Brainstorm / requirements / proposal -> domain
+  { match: /(^|\/)proposal\.md$/i,               domain: '1-domain', category: 'scenarios' },
+  { match: /(^|\/)requirement\.md$/i,            domain: '1-domain', category: 'scenarios' },
+];
+
+const SECTION_HINTS = [
+  { re: /(术语|名词|glossary|terminology)/i,                              domain: '1-domain', category: 'concepts' },
+  { re: /(规则|决策表|policy|rule)/i,                                     domain: '1-domain', category: 'rules' },
+  { re: /(业务流程|场景|scenario|story)/i,                                domain: '1-domain', category: 'scenarios' },
+  { re: /(api|接口|契约|contract|protobuf|grpc|rest|kafka|event)/i,       domain: '2-system', category: 'contracts' },
+  { re: /(adr|架构决策|技术决策|architecture decision)/i,                  domain: '2-system', category: 'decisions' },
+  { re: /(服务概述|module overview|service overview|system overview)/i,    domain: '2-system', category: 'services' },
+  { re: /(runbook|排查|sop|on-call|playbook)/i,                            domain: '3-ops', category: 'runbooks' },
+  { re: /(incident|事故|复盘|postmortem)/i,                                domain: '3-ops', category: 'incidents' },
+  { re: /(环境|environment|infra|deploy)/i,                                domain: '3-ops', category: 'environments' },
+];
+
+function classify(entry) {
+  const reasons = [];
+  if (entry.hints && entry.hints.domain && entry.hints.category) {
+    return {
+      domain: entry.hints.domain, category: entry.hints.category,
+      suggestedFilename: filename(entry, entry.hints),
+      confidence: 1.0,
+      reasons: ['explicit hint'],
+    };
+  }
+
+  let pick = null;
+  // 1. Heading hints win first (most specific signal).
+  for (const r of SECTION_HINTS) {
+    if (entry.section && r.re.test(entry.section)) {
+      pick = { domain: r.domain, category: r.category };
+      reasons.push(`heading: ${r.re}`);
+      break;
+    }
+  }
+  // 2. Artifact-based fallback.
+  if (!pick) {
+    for (const r of ARTIFACT_RULES) {
+      if (r.match.test(entry.artifact || '')) {
+        pick = { domain: r.domain, category: r.category };
+        reasons.push(`artifact: ${r.match}`);
+        break;
+      }
+    }
+  }
+  // 3. Body keyword fallback (broadest).
+  if (!pick) {
+    for (const r of SECTION_HINTS) {
+      if (r.re.test(entry.content || '')) {
+        pick = { domain: r.domain, category: r.category };
+        reasons.push(`content: ${r.re}`);
+        break;
+      }
+    }
+  }
+  if (!pick) {
+    pick = { domain: '4-archive', category: 'solutions' };
+    reasons.push('default fallback');
+  }
+  return {
+    domain: pick.domain, category: pick.category,
+    suggestedFilename: filename(entry, pick),
+    confidence: reasons.length === 1 ? 0.5 : 0.8,
+    reasons,
+  };
+}
+
+function filename(entry, pick) {
+  const sect = (entry.section || '').trim();
+  const slug = (entry.slug || 'note').replace(/[^a-zA-Z0-9-]+/g, '-');
+  let base;
+  if (sect) {
+    base = safe(sect);
+  } else {
+    base = safe(slug);
+  }
+  // Add slug suffix to avoid collisions across changes.
+  if (!base.includes(slug)) base = `${base}__${slug}`;
+  return `${base}.md`.slice(0, 200);
+}
+
+function safe(s) {
+  return s
+    .normalize('NFKC')
+    .replace(/[\\\/:*?"<>|\n\r\t]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+}
+
+module.exports = { classify };