@chenguangyao/devflow-kit 0.1.43

package/src/knowledge/deposit.js

@@ -0,0 +1,414 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const paths = require('../core/paths.js');
+const { ensureMeta, writeMeta, sha256 } = require('./registry.js');
+const { categoryDir } = require('./categories.js');
+
+/**
+ * Knowledge deposit strategy: **artifact-first, not section-first**.
+ *
+ * Each source file (knowledge/*.md, design.md, incident-*.md) produces AT MOST
+ * ONE knowledge document — the whole file is deposited as a single document.
+ *
+ * This mirrors the arb-workflow-kit pattern where one change yields 2-4 files
+ * rather than 10+ fragmented section files.
+ *
+ * Exceptions (both produce ADDITIONAL files, not replacements):
+ *   <!-- knowledge:skip -->         — exclude entire source file from deposit
+ *   <!-- knowledge:domain=X category=Y filename=foo.md -->
+ *                                  — specific section gets its own targeted file
+ *
+ * Source → Category mapping:
+ *   design.md      → decisions            "[slug] <title> - 技术方案.md"
+ *   knowledge/*.md → category by dir       keep filename
+ *   incident-*.md  → incidents            "[slug] <name> - 故障复盘.md"
+ *   regression*.md → runbooks             "[slug] regression - 回归测试.md"
+ *
+ * Returns a plan: [{ source, title, target, targetAbs, action, sha256, domain, category, filename, body }]
+ */
+
+const ARTIFACT_MAP = [
+  { match: /(^|\/)design\.md$/i,               category: 'decisions'  },
+  { match: /(^|\/)requirement\.md$/i,           category: 'scenarios'  },
+  { match: /(^|\/)proposal\.md$/i,              category: 'scenarios'  },
+  { match: /(^|\/)incident[-_]?.*\.md$/i,       category: 'incidents'  },
+  { match: /(^|\/)regression.*\.md$/i,          category: 'runbooks'   },
+  { match: /(^|\/)adr[-_]?\d*\.md$/i,           category: 'decisions'  },
+];
+
+const KIND_MAP = {
+  concepts:     'concept',
+  rules:        'rule',
+  scenarios:    'scenario',
+  contracts:    'contract',
+  decisions:    'adr',
+  services:     'service',
+  runbooks:     'runbook',
+  incidents:    'incident',
+  environments: 'environment',
+  solutions:    'solution-pattern',
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Find the change directory for a slug (active or archived).
+ */
+function resolveChangeDir(root, slug) {
+  const workspace = paths.workspaceChangesDir(slug);
+  if (fsSync.existsSync(workspace)) return workspace;
+  const live = path.join(paths.devflowDir(root), 'changes', slug);
+  if (fsSync.existsSync(live)) return live;
+  const archDir = paths.archiveDir(root);
+  if (!fsSync.existsSync(archDir)) return null;
+  const entries = require('fs').readdirSync(archDir, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name === slug || e.name.endsWith('-' + slug)) {
+      return path.join(archDir, e.name);
+    }
+  }
+  return null;
+}
+
+/**
+ * Build the deposit plan (dry-run safe).
+ * Returns [{ source, title, target, targetAbs, action, sha256, domain, category, filename, body }]
+ */
+async function deposit(root, opts = {}) {
+  const { slug, dryRun = false, force = false } = opts;
+  if (!slug) throw new Error('deposit requires slug');
+
+  const cdir = resolveChangeDir(root, slug);
+  if (!cdir) throw new Error(`change not found: ${slug}`);
+
+  const sources = await collectSources(cdir);
+  const plan = [];
+
+  for (const src of sources) {
+    const rawFile = await fs.readFile(src.abs, 'utf8');
+    const raw = /^knowledge[\\/]/.test(src.rel)
+      ? stripDepositFrontmatter(rawFile)
+      : rawFile;
+
+    // 1. Whole-file skip directive
+    if (/<!--\s*knowledge:\s*skip\b/i.test(raw)) continue;
+
+    // 2. Handle explicit per-section overrides FIRST (<!-- knowledge:domain=X category=Y -->)
+    const explicit = extractExplicitSections(raw);
+    for (const sec of explicit) {
+      const entry = await buildEntry(root, sec.body, sec.category, sec.filename || null, src.rel, slug, { force });
+      if (entry) plan.push(entry);
+    }
+
+    // 3. Deposit the remaining content as ONE document
+    const cleaned = removeExplicitSections(raw);
+    if (!cleaned.trim()) continue;
+
+    const target = artifactCategory(src.rel);
+    if (!target) continue; // unknown artifact type; skip
+
+    const title = extractTitle(raw, src.rel, slug);
+    const fname = buildFilename(slug, title, src.rel);
+    const entry = await buildEntry(root, cleaned, target.category, fname, src.rel, slug, { force });
+    if (entry) plan.push(entry);
+  }
+
+  if (!dryRun) {
+    await executeItems(root, plan.filter((p) => p.action !== 'noop'), slug);
+  }
+  return plan;
+}
+
+function stripDepositFrontmatter(text) {
+  const m = /^---\s*\n([\s\S]*?)\n---\s*\n?/m.exec(text);
+  if (!m) return text;
+  if (!/^deposited_at:/m.test(m[1]) && !/^sha256:/m.test(m[1])) return text;
+  return text.slice(m[0].length);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function collectSources(cdir) {
+  const out = [];
+  for (const f of ['design.md']) {
+    const abs = path.join(cdir, f);
+    if (fsSync.existsSync(abs)) out.push({ rel: f, abs });
+  }
+  const knowledgeDir = path.join(cdir, 'knowledge');
+  if (fsSync.existsSync(knowledgeDir)) {
+    await collectKnowledgeSources(knowledgeDir, knowledgeDir, out);
+  }
+  const reportsDir = path.join(cdir, 'reports');
+  if (fsSync.existsSync(reportsDir)) {
+    for (const f of await fs.readdir(reportsDir)) {
+      if (!f.endsWith('.md')) continue;
+      if (/^(incident|regression)/i.test(f)) {
+        out.push({ rel: 'reports/' + f, abs: path.join(reportsDir, f) });
+      }
+    }
+  }
+  return out;
+}
+
+async function collectKnowledgeSources(baseDir, dir, out) {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectKnowledgeSources(baseDir, abs, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push({ rel: path.join('knowledge', path.relative(baseDir, abs)), abs });
+    }
+  }
+}
+
+/**
+ * Extract sections with explicit knowledge: hints into standalone items.
+ * Each returns { body, domain, category, filename? }.
+ */
+function extractExplicitSections(text) {
+  const sections = [];
+  const lines = text.split('\n');
+  let pending = null; // { domain, category, filename, lines[] }
+
+  for (const line of lines) {
+    const hint = parseKnowledgeHint(line.trim());
+    if (hint && hint.domain && hint.category) {
+      // Flush previous pending
+      if (pending) sections.push({ ...pending, body: pending.lines.join('\n') });
+      pending = { domain: hint.domain, category: hint.category, filename: hint.filename || null, lines: [] };
+      continue;
+    }
+    if (pending) {
+      // Close on next H2 that doesn't have another hint right above it
+      if (/^## /.test(line) && !hint) {
+        sections.push({ ...pending, body: pending.lines.join('\n') });
+        pending = null;
+      } else {
+        pending.lines.push(line);
+      }
+    }
+  }
+  if (pending) sections.push({ ...pending, body: pending.lines.join('\n') });
+  return sections.filter((s) => s.body.trim());
+}
+
+/**
+ * Strip explicit sections (<!-- knowledge:domain=... --> blocks) from text
+ * so they aren't double-deposited in the whole-file entry.
+ */
+function removeExplicitSections(text) {
+  const lines = text.split('\n');
+  const out = [];
+  let inExplicit = false;
+
+  for (const line of lines) {
+    const hint = parseKnowledgeHint(line.trim());
+    if (hint && hint.domain && hint.category) {
+      inExplicit = true;
+      continue;
+    }
+    if (inExplicit && /^## /.test(line)) {
+      inExplicit = false;
+    }
+    if (!inExplicit) out.push(line);
+  }
+  return out.join('\n');
+}
+
+function parseKnowledgeHint(str) {
+  const m = /^<!--\s*knowledge:([^>]*?)-->/i.exec(str);
+  if (!m) return null;
+  const hint = {};
+  for (const part of m[1].trim().split(/\s+/)) {
+    const kv = /^(\w+)=(.+)$/.exec(part);
+    if (kv) hint[kv[1]] = kv[2];
+  }
+  if (m[1].trim() === 'skip') hint.skip = true;
+  return hint;
+}
+
+function artifactCategory(rel) {
+  const parts = rel.split(/[\\/]/);
+  if (parts[0] === 'knowledge' && parts.length >= 3) {
+    const { CATEGORY_TAG_NAMES } = require('./categories.js');
+    const category = Object.entries(CATEGORY_TAG_NAMES)
+      .find(([, info]) => info.name === parts[1])?.[0] || parts[1];
+    return { category };
+  }
+  for (const r of ARTIFACT_MAP) {
+    if (r.match.test(rel)) return { category: r.category };
+  }
+  return null;
+}
+
+/**
+ * Extract a meaningful title from the document.
+ * Priority: frontmatter title: → first # heading → fallback to artifact name
+ *
+ * Strips common auto-generated prefixes that appear in headings:
+ *   "design.md — ", "技术方案 — ", etc.
+ */
+function extractTitle(text, rel, slug) {
+  const fm = /^---\s*\n([\s\S]*?)\n---/m.exec(text);
+  if (fm) {
+    const t = /^title:\s*"?([^"\n]+)"?/m.exec(fm[1]);
+    if (t) return cleanTitle(t[1].trim());
+  }
+  const h1 = /^#\s+(.+)$/m.exec(text);
+  if (h1) return cleanTitle(h1[1].replace(/<!--.*?-->/g, '').trim());
+  // Fallback: artifact basename (no suffix needed, buildFilename adds one)
+  return cleanTitle(path.basename(rel, '.md').replace(/[-_]/g, ' '));
+}
+
+/**
+ * Clean a raw title:
+ *  1. Strip leading "filename.ext — " or "keyword — " patterns
+ *     (agents sometimes write "design.md — 实际标题" or "技术方案 — 实际标题")
+ *  2. Strip trailing " — " dangling dashes
+ */
+function cleanTitle(raw) {
+  let t = raw;
+  // Remove any "*.md —" or "*.md -" fragment anywhere in the string
+  // Handles: "design.md — foo", "[slug] design.md — foo", etc.
+  t = t.replace(/\b\w[\w.-]*\.md\s*[—\-–]+\s*/gi, '');
+  // Strip leading bracket slug like "[18-xxx] "
+  t = t.replace(/^\s*\[[^\]]+\]\s*/, '');
+  // Strip trailing em-dash artifacts
+  t = t.replace(/\s*[—\-–]+\s*$/, '').trim();
+  return t || raw.trim();
+}
+
+/**
+ * Artifact type suffix — appended after the title, ARB style.
+ *   design.md       → " - 技术方案"
+ *   incident-*.md   → " - 故障复盘"
+ *   regression*.md  → " - 回归测试"
+ */
+const ARTIFACT_SUFFIX = [
+  { match: /(^|\/)design\.md$/i,         suffix: ' - 技术方案'   },
+  { match: /(^|\/)requirement\.md$/i,    suffix: ' - 需求分析'   },
+  { match: /(^|\/)proposal\.md$/i,       suffix: ' - 需求背景'   },
+  { match: /(^|\/)incident[-_]?.*\.md$/i, suffix: ' - 故障复盘'  },
+  { match: /(^|\/)regression.*\.md$/i,   suffix: ' - 回归测试'   },
+];
+
+/**
+ * Build filename in ARB style:
+ *   "[{slug}] {title} - {artifact-type}.md"
+ *
+ * Examples:
+ *   design.md  + title "健康保障会员升级版"  → "[feature-18] 健康保障会员升级版 - 技术方案.md"
+ *   knowledge/解决方案/foo.md               → "[feature-18] foo.md"  (keeps explicit knowledge filename)
+ */
+function buildFilename(slug, title, rel) {
+  if (/^knowledge[\\/]/.test(rel)) return path.basename(rel);
+  const safetitle = title
+    .normalize('NFKC')
+    .replace(/[\\\/:*?"<>|\n\r\t]/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim()
+    .slice(0, 60);
+
+  let suffix = '';
+  for (const r of ARTIFACT_SUFFIX) {
+    if (r.match.test(rel)) { suffix = r.suffix; break; }
+  }
+
+  // Avoid duplicate suffix if title already ends with the suffix text
+  const suffixLabel = suffix.replace(/^[\s-]+/, '');
+  const body = (suffixLabel && safetitle.endsWith(suffixLabel))
+    ? safetitle
+    : safetitle + suffix;
+
+  return `[${slug}] ${body}.md`;
+}
+
+async function buildEntry(root, body, category, filename, sourceRel, slug, { force = false } = {}) {
+  if (!body.trim()) return null;
+  // Default target: ~/.devflow/workspace/changes/<slug>/knowledge/<中文目录名>/<filename>
+  // Historical fallback remains <repo>/devflow/knowledge/ when callers provide old roots.
+  const dirName = categoryDir(category);
+  const targetAbs = path.join(resolveKnowledgeDir(root, slug), dirName, filename);
+  const newSha = sha256(body);
+  const action = await decideAction(targetAbs, newSha, force);
+  const kind = KIND_MAP[category] || 'note';
+  // Extract clean title from body for WeKnora display (readMarkdownFile uses title: frontmatter field)
+  const cleanedTitle = cleanTitle(extractTitle(body, sourceRel, slug));
+  return {
+    source: sourceRel,
+    title: cleanedTitle,
+    target: path.relative(root, targetAbs),
+    knowledgeRoot: resolveKnowledgeDir(root, slug),
+    targetAbs,
+    action,
+    sha256: newSha,
+    body,
+    category,
+    dirName,
+    filename,
+    kind,
+  };
+}
+
+function resolveKnowledgeDir(root, slug) {
+  return paths.workspaceKnowledgeDir(slug) || paths.knowledgeDir(root);
+}
+
+async function decideAction(targetAbs, newSha, force = false) {
+  if (!fsSync.existsSync(targetAbs)) return 'create';
+  if (force) return 'update';
+  try {
+    const existing = await fs.readFile(targetAbs, 'utf8');
+    const fmMatch  = existing.match(/^sha256:\s*([a-f0-9]{64})/m);
+    const cmt      = existing.match(/sha256=([a-f0-9]{12})/);
+    const stored   = (fmMatch && fmMatch[1]) || (cmt && cmt[1]);
+    if (stored && newSha.startsWith(stored.slice(0, 12))) return 'noop';
+  } catch { /* ignore */ }
+  return 'update';
+}
+
+/**
+ * Write confirmed plan items to devflow/knowledge/ and update .meta.json.
+ * Exported so the CLI can call it after interactive confirmation.
+ */
+async function executeItems(root, items, slug) {
+  for (const p of items) {
+    if (p.action === 'noop') continue;
+    await fs.mkdir(path.dirname(p.targetAbs), { recursive: true });
+    const fm = buildFrontmatter(p, slug);
+    await fs.writeFile(p.targetAbs, fm + p.body, 'utf8');
+    const catDir = path.dirname(p.targetAbs);
+    const meta = await ensureMeta(catDir, p.category);
+    meta.files = meta.files || {};
+    const prev = meta.files[p.filename] || {};
+    meta.files[p.filename] = {
+      ...prev,
+      sha256: p.sha256,
+      source: { slug, artifact: p.source },
+      updated_at: new Date().toISOString(),
+    };
+    await writeMeta(catDir, meta);
+  }
+}
+
+function buildFrontmatter(p, slug) {
+  return [
+    '---',
+    `kind: ${p.kind}`,
+    `slug: ${slug}`,
+    `title: ${p.title}`,
+    `source: ${p.source}`,
+    `category: ${p.category}`,
+    `sha256: ${p.sha256}`,
+    `deposited_at: ${new Date().toISOString()}`,
+    '---',
+    '',
+  ].join('\n');
+}
+
+module.exports = { deposit, executeItems, resolveChangeDir, extractTitle, buildFilename };

package/src/knowledge/migrate.js

@@ -0,0 +1,149 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const paths = require('../core/paths.js');
+
+/**
+ * Migrate a knowledge tree from one layout to another.
+ *
+ * Currently supported:
+ *   from='arb-7'  to='improved-9'
+ *
+ * The arb-7 layout (per arb-knowledge):
+ *   1-业务概念/   2-业务规则/   3-业务流程/   4-接口/   5-技术决策/   6-排查记录/   7-其他/
+ *
+ * Mapping table:
+ *   1-业务概念   → 1-domain/concepts
+ *   2-业务规则   → 1-domain/rules
+ *   3-业务流程   → 1-domain/scenarios
+ *   4-接口       → 2-system/contracts
+ *   5-技术决策   → 2-system/decisions
+ *   6-排查记录   → 3-ops/incidents
+ *   7-其他       → 4-archive/solutions
+ *
+ * Files are MOVED (not copied). A migration report is written to
+ *   devflow/knowledge/.migration.log
+ *
+ * Options: { dryRun: bool, from: string, to: string }
+ */
+
+const MAPPINGS = {
+  'arb-7→improved-9': {
+    '1-业务概念':  ['1-domain', 'concepts'],
+    '2-业务规则':  ['1-domain', 'rules'],
+    '3-业务流程':  ['1-domain', 'scenarios'],
+    '4-接口':      ['2-system', 'contracts'],
+    '5-技术决策':  ['2-system', 'decisions'],
+    '6-排查记录':  ['3-ops',    'incidents'],
+    '7-其他':      ['4-archive','solutions'],
+    // English fallbacks for ASCII forks of arb-knowledge
+    '1-concept':   ['1-domain', 'concepts'],
+    '2-rule':      ['1-domain', 'rules'],
+    '3-flow':      ['1-domain', 'scenarios'],
+    '4-api':       ['2-system', 'contracts'],
+    '5-decision':  ['2-system', 'decisions'],
+    '6-incident':  ['3-ops',    'incidents'],
+    '7-other':     ['4-archive','solutions'],
+  },
+};
+
+async function migrate(root, opts = {}) {
+  const { dryRun = false, from = 'arb-7', to = 'improved-9' } = opts;
+  const key = `${from}→${to}`;
+  const map = MAPPINGS[key];
+  if (!map) throw new Error(`unsupported migration: ${key}`);
+
+  const kbDir = paths.knowledgeDir(root);
+  if (!fsSync.existsSync(kbDir)) throw new Error('no devflow/knowledge/ found');
+
+  const moved = [];
+  const skipped = [];
+  const conflicts = [];
+
+  const entries = await fs.readdir(kbDir, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!map[e.name]) {
+      // already migrated layout buckets (1-domain/2-system/...) or unknown
+      if (/^[1-4]-(domain|system|ops|archive)$/.test(e.name)) continue;
+      skipped.push({ name: e.name, reason: 'no mapping' });
+      continue;
+    }
+    const [domain, category] = map[e.name];
+    const srcDir = path.join(kbDir, e.name);
+    const dstDir = path.join(kbDir, domain, category);
+
+    if (!dryRun) await fs.mkdir(dstDir, { recursive: true });
+
+    const files = await walkAll(srcDir);
+    for (const f of files) {
+      const rel = path.relative(srcDir, f);
+      const dst = path.join(dstDir, rel.replace(/[\\\/]/g, '__'));
+      if (fsSync.existsSync(dst)) {
+        conflicts.push({ src: path.relative(root, f), dst: path.relative(root, dst) });
+        continue;
+      }
+      moved.push({ src: path.relative(root, f), dst: path.relative(root, dst) });
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.rename(f, dst);
+      }
+    }
+    if (!dryRun) {
+      // Try to rmdir source if now empty
+      await rmEmptyTree(srcDir);
+    }
+  }
+
+  const report = {
+    when: new Date().toISOString(),
+    from, to,
+    moved: moved.length,
+    skipped: skipped.length,
+    conflicts: conflicts.length,
+    details: { moved, skipped, conflicts },
+  };
+  if (!dryRun) {
+    await fs.writeFile(path.join(kbDir, '.migration.log'), JSON.stringify(report, null, 2) + '\n', 'utf8');
+  }
+  return report;
+}
+
+async function walkAll(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    const ents = await fs.readdir(cur, { withFileTypes: true });
+    for (const e of ents) {
+      const p = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else if (e.isFile() && !e.name.startsWith('.')) out.push(p);
+    }
+  }
+  return out;
+}
+
+async function rmEmptyTree(dir) {
+  if (!fsSync.existsSync(dir)) return;
+  const stack = [dir];
+  const stackForRemoval = [];
+  while (stack.length) {
+    const cur = stack.pop();
+    stackForRemoval.push(cur);
+    const ents = await fs.readdir(cur, { withFileTypes: true });
+    for (const e of ents) if (e.isDirectory()) stack.push(path.join(cur, e.name));
+  }
+  for (const d of stackForRemoval.reverse()) {
+    try {
+      const ents = await fs.readdir(d);
+      if (ents.length === 0 || (ents.length === 1 && ents[0] === '.meta.json')) {
+        if (ents.length === 1) await fs.unlink(path.join(d, '.meta.json'));
+        await fs.rmdir(d);
+      }
+    } catch { /* ignore */ }
+  }
+}
+
+module.exports = { migrate, MAPPINGS };