@chenguangyao/devflow-kit 0.1.43

package/src/knowledge/mr.js

@@ -0,0 +1,219 @@
+'use strict';
+/**
+ * Knowledge MR/PR mode.
+ *
+ * Two sub-modes:
+ *
+ * A) External KB repo (kb-git provider configured) — mirrors arb-workflow-kit:
+ *      Clones/pulls the standalone knowledge GitLab/GitHub repo → copies files →
+ *      creates branch + commit + push → creates MR/PR in THAT repo.
+ *
+ * B) Current project repo (no kb-git provider, or explicit --local-mr):
+ *      Creates a branch in the current repo → commits devflow/knowledge/ →
+ *      pushes → creates PR/MR via gh / glab / vcs provider.
+ *
+ * `createKnowledgePr` auto-detects which mode to use.
+ */
+
+const cp = require('child_process');
+const path = require('path');
+const autodetect = require('../core/autodetect.js');
+const loader = require('../providers/loader.js');
+
+function git(args, cwd) {
+  return cp.spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+}
+
+function gitOrThrow(args, cwd, label) {
+  const r = git(args, cwd);
+  if (r.status !== 0) {
+    throw new Error(`[git ${label}] ${(r.stderr || r.stdout || '').trim()}`);
+  }
+  return (r.stdout || '').trim();
+}
+
+/**
+ * Main entry point — call after executeItems() has written knowledge files.
+ *
+ * Auto-selects mode:
+ *   • External repo  — when a kb provider with driver='git' is configured
+ *   • Current repo   — fallback (or when --local-mr is set)
+ *
+ * @param {string}   root   — git repo root
+ * @param {object}   opts
+ *   @param {string}   slug      — change slug
+ *   @param {Array}    items     — plan items (used for PR body generation)
+ *   @param {boolean}  dryRun    — preview only, no git/network ops
+ *   @param {boolean}  localMr   — force current-repo mode even if kb-git is configured
+ * @returns {{ branch, url, baseBranch, status, mode, error? }}
+ */
+async function createKnowledgePr(root, { slug, items, dryRun = false, localMr = false }) {
+  // ── Auto-detect: use external kb-git repo if configured ───────────────────
+  if (!localMr) {
+    let kbGitProvider = null;
+    try {
+      const all = await loader.listConfigured(root);
+      const gitEntry = all.find((e) => e.type === 'kb' && e.driver === 'git');
+      if (gitEntry) kbGitProvider = await loader.load(root, { name: gitEntry.name });
+    } catch { /* no kb-git configured → fall through */ }
+
+    if (kbGitProvider) {
+      const actionable = (items || []).filter((p) => p.action !== 'noop');
+      const result = await kbGitProvider.depositAndCreateMr(root, { items: actionable, slug, dryRun });
+      return { ...result, mode: 'external' };
+    }
+  }
+
+  // ── Mode B: current project repo ──────────────────────────────────────────
+  // Workspace knowledge lives under ~/.devflow/workspace and cannot be committed
+  // by the current project repository. In that case an external kb.git provider
+  // is required.
+  if ((items || []).some((p) => p.knowledgeRoot && !path.resolve(p.knowledgeRoot).startsWith(path.resolve(root) + path.sep))) {
+    return {
+      branch: null,
+      url: null,
+      baseBranch: null,
+      status: 'workspace_requires_kb_git',
+      mode: 'local',
+      error: 'workspace knowledge MR requires a kb.git provider; current project repo cannot commit files under ~/.devflow/workspace',
+    };
+  }
+
+  // ── 1. Determine branch names ──────────────────────────────────────────────
+  const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  const safeslug = slug.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-{2,}/g, '-').slice(0, 40).replace(/-$/, '');
+  const branch = `knowledge/deposit-${safeslug}-${date}`;
+
+  let baseBranch;
+  try { baseBranch = autodetect.detectDefaultBranch(root); }
+  catch { baseBranch = 'main'; }
+
+  // ── 2. Check there are knowledge changes to commit ─────────────────────────
+  const statusOut = git(['status', '--porcelain', 'devflow/knowledge/'], root).stdout.trim();
+  if (!statusOut) {
+    return { branch: null, url: null, baseBranch, status: 'no_changes', mode: 'local' };
+  }
+
+  if (dryRun) {
+    return {
+      branch, baseBranch, url: null, status: 'dry_run', mode: 'local',
+      message: `would create branch '${branch}' from origin/${baseBranch} and open PR`,
+    };
+  }
+
+  // ── 3. Remember current branch ─────────────────────────────────────────────
+  const currentBranch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root).stdout.trim() || 'HEAD';
+
+  let pushOk = false;
+  try {
+    // ── 4. Fetch origin (best-effort, don't fail if offline) ─────────────────
+    git(['fetch', 'origin', baseBranch, '--no-tags'], root);
+
+    // ── 5. Create branch from origin/<baseBranch> ─────────────────────────────
+    //   git checkout -b <branch> origin/<base> preserves working-tree changes.
+    //   If origin/<base> doesn't exist (local-only repo), fall back to HEAD.
+    const remoteRef = `origin/${baseBranch}`;
+    const remoteExists = git(['rev-parse', '--verify', '--quiet', remoteRef], root).status === 0;
+    const baseRef = remoteExists ? remoteRef : baseBranch;
+
+    gitOrThrow(['checkout', '-b', branch, baseRef], root, 'checkout -b');
+
+    // ── 6. Stage & commit ─────────────────────────────────────────────────────
+    gitOrThrow(['add', 'devflow/knowledge/'], root, 'add');
+
+    const actionable = (items || []).filter((p) => p.action !== 'noop');
+    const commitMsg = `chore(knowledge): deposit ${actionable.length} item(s) from ${slug}\n\n${buildCommitBody(actionable, slug)}`;
+
+    const commitR = git(['commit', '-m', commitMsg], root);
+    if (commitR.status !== 0) {
+      const out = (commitR.stdout + commitR.stderr).toLowerCase();
+      if (out.includes('nothing to commit')) {
+        await _returnBranch(root, currentBranch, branch);
+        return { branch, url: null, baseBranch, status: 'no_changes' };
+      }
+      throw new Error(`[git commit] ${(commitR.stderr || commitR.stdout || '').trim()}`);
+    }
+
+    // ── 7. Push ───────────────────────────────────────────────────────────────
+    gitOrThrow(['push', '-u', 'origin', branch], root, 'push');
+    pushOk = true;
+
+    // ── 8. Create PR/MR ───────────────────────────────────────────────────────
+    const prTitle = `[Knowledge] Deposit: ${slug}`;
+    const prBody  = buildPrBody(actionable, slug, branch, baseBranch);
+
+    const vcs = await loader.load(root, { type: 'vcs' });
+    let url = null;
+    try {
+      const result = await vcs.pr({ title: prTitle, body_md: prBody, head: branch, base: baseBranch });
+      url = result.url;
+    } catch (prErr) {
+      // Branch is pushed — return partial success with the error.
+      await _returnBranch(root, currentBranch, branch);
+      return { branch, url: null, baseBranch, status: 'pushed_no_pr', error: prErr.message, mode: 'local' };
+    }
+
+    await _returnBranch(root, currentBranch, branch);
+    return { branch, url, baseBranch, status: 'created', mode: 'local' };
+
+  } catch (err) {
+    // Best-effort cleanup: return to original branch.
+    try { await _returnBranch(root, currentBranch, branch, !pushOk); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+async function _returnBranch(root, currentBranch, newBranch, deleteBranch = false) {
+  if (currentBranch && currentBranch !== newBranch && currentBranch !== 'HEAD') {
+    git(['checkout', currentBranch], root);
+  }
+  if (deleteBranch) {
+    git(['branch', '-D', newBranch], root);
+  }
+}
+
+function buildCommitBody(items, slug) {
+  const lines = [`Change: ${slug}`, ''];
+  for (const p of items) {
+    lines.push(`${p.action === 'create' ? 'A' : 'M'} ${p.target}`);
+  }
+  return lines.join('\n');
+}
+
+function buildPrBody(items, slug, branch, baseBranch) {
+  const lines = [
+    '## Knowledge Deposit',
+    '',
+    `**Change**: \`${slug}\``,
+    `**Branch**: \`${branch}\` → \`${baseBranch}\``,
+    '',
+    '## Changes',
+    '',
+    '| Op | File | Source | Confidence |',
+    '|----|------|--------|------------|',
+  ];
+
+  for (const p of items) {
+    const op   = p.action === 'create' ? '+ New' : '~ Update';
+    const conf = (p.confidence || 0.5) >= 0.8 ? `${(p.confidence).toFixed(2)} ✓` : `${(p.confidence || 0.5).toFixed(2)} ⚠`;
+    const src  = `${p.source}#${p.section}`;
+    lines.push(`| ${op} | \`${p.target}\` | ${src} | ${conf} |`);
+  }
+
+  lines.push(
+    '',
+    '## Review Checklist',
+    '',
+    '- [ ] 分类归属正确（domain/category 合理）',
+    '- [ ] 文件命名符合约定',
+    '- [ ] 内容与需求/设计一致，无敏感信息',
+    '- [ ] ⚠ confidence < 0.8 条目已人工确认分类',
+    '- [ ] 如有 `related:` 字段建议，已补充关联路径',
+  );
+
+  return lines.join('\n');
+}
+
+module.exports = { createKnowledgePr, buildPrBody };

package/src/knowledge/query.js

@@ -0,0 +1,131 @@
+'use strict';
+const fs = require('fs/promises');
+const path = require('path');
+const paths = require('../core/paths.js');
+const { walkKnowledge } = require('./registry.js');
+const loader = require('../providers/loader.js');
+
+/**
+ * Local + remote knowledge search.
+ *
+ * Scoring:
+ *   per-keyword:
+ *     +5  match in filename
+ *     +3  match in H1/H2 heading
+ *     +1  per match in body (capped at 10)
+ *   normalized by sqrt(numKeywords).
+ *
+ * Returns top-K hits with snippet + path + score.
+ *
+ * Options:
+ *   { keywords: [], k: 8, withRemote: bool }
+ */
+async function query(root, opts = {}) {
+  const { keywords = [], k = 8, withRemote = true, slug = null } = opts;
+  if (!keywords.length) return { hits: [], remoteHits: [] };
+
+  const kws = keywords.map((s) => s.toLowerCase()).filter(Boolean);
+
+  // Local: specs first (project truth), then workspace/repo knowledge.
+  const all = [
+    ...(await walkSpecs(root)),
+    ...(slug ? await walkWorkspaceKnowledge(slug) : []),
+    ...(await walkKnowledge(root)),
+  ];
+  const localHits = [];
+  for (const f of all) {
+    const buf = await fs.readFile(f.abs, 'utf8');
+    const lower = buf.toLowerCase();
+    let score = 0;
+    let firstHitLine = -1;
+    let lineHit = '';
+    const fnameLower = f.file.toLowerCase();
+    const headings = (buf.match(/^#{1,2}\s+.+$/gm) || []).join('\n').toLowerCase();
+    for (const kw of kws) {
+      if (fnameLower.includes(kw)) score += 5;
+      if (headings.includes(kw)) score += 3;
+      const matches = countOccurrences(lower, kw);
+      score += Math.min(matches, 10);
+      if (firstHitLine === -1 && matches > 0) {
+        const lines = buf.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].toLowerCase().includes(kw)) { firstHitLine = i + 1; lineHit = lines[i].trim(); break; }
+        }
+      }
+    }
+    score = +(score / Math.sqrt(kws.length)).toFixed(2);
+    if (score > 0) {
+      localHits.push({
+        path: path.relative(root, f.abs),
+        domain: f.domain, category: f.category, file: f.file, source: f.source || 'knowledge',
+        score, line: firstHitLine, snippet: lineHit.slice(0, 200),
+      });
+    }
+  }
+  localHits.sort((a, b) => sourcePriority(a.source) - sourcePriority(b.source) || b.score - a.score);
+
+  // Remote (if a kb provider configured & supports search)
+  let remoteHits = [];
+  if (withRemote) {
+    try {
+      const provider = await loader.load(root, { type: 'kb' });
+      if (typeof provider.search === 'function') {
+        remoteHits = await provider.search(kws.join(' '), { k }) || [];
+      }
+    } catch { /* ignore */ }
+  }
+
+  return { hits: localHits.slice(0, k), remoteHits: remoteHits.slice(0, k) };
+}
+
+async function walkSpecs(root) {
+  const dir = paths.specsDir(root);
+  const files = await walkMd(dir);
+  return files.map((abs) => ({
+    source: 'specs',
+    category: 'specs',
+    file: path.basename(abs),
+    abs,
+  }));
+}
+
+async function walkWorkspaceKnowledge(slug) {
+  const dir = paths.workspaceKnowledgeDir(slug);
+  const files = await walkMd(dir);
+  return files.map((abs) => ({
+    source: 'workspace-knowledge',
+    category: path.basename(path.dirname(abs)),
+    file: path.basename(abs),
+    abs,
+  }));
+}
+
+async function walkMd(dir) {
+  if (!dir || !require('fs').existsSync(dir)) return [];
+  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.endsWith('.md')) out.push(p);
+    }
+  }
+  return out;
+}
+
+function countOccurrences(haystack, needle) {
+  let count = 0; let pos = 0;
+  while ((pos = haystack.indexOf(needle, pos)) !== -1) { count++; pos += needle.length; }
+  return count;
+}
+
+function sourcePriority(source) {
+  if (source === 'specs') return 0;
+  if (source === 'workspace-knowledge') return 1;
+  return 2;
+}
+
+module.exports = { query };

package/src/knowledge/registry.js

@@ -0,0 +1,151 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const paths = require('../core/paths.js');
+const { resolveTagInfo, BY_CHINESE_NAME } = require('./categories.js');
+
+/**
+ * Per-category .meta.json acts as the file registry.
+ *
+ * Flat directory layout:
+ *   ~/.devflow/workspace/knowledge/<category>/.meta.json
+ *   ~/.devflow/workspace/changes/<slug>/knowledge/<category>/.meta.json
+ *
+ * Shape:
+ *   {
+ *     "category": "decisions",
+ *     "tag_name": "架构决策",
+ *     "tag_id":   "",          // filled in by sync
+ *     "external": {},
+ *     "files":    { ... }
+ *   }
+ */
+
+async function readMeta(catDir) {
+  const file = path.join(catDir, '.meta.json');
+  if (!fsSync.existsSync(file)) return null;
+  try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return null; }
+}
+
+async function writeMeta(catDir, meta) {
+  const file = path.join(catDir, '.meta.json');
+  await fs.writeFile(file, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Ensure a .meta.json exists in catDir.
+ *
+ * @param {string} catDir       absolute path to the category directory
+ * @param {string} categoryId   English slug OR Chinese dir name (e.g. "decisions" / "架构决策")
+ * @param {string} [_domainId]  ignored — kept for call-site compatibility
+ */
+async function ensureMeta(catDir, categoryId, _domainId) {
+  const existing = await readMeta(catDir);
+  if (existing) {
+    if (!existing.files) existing.files = {};
+    if (!existing.tag_name) {
+      const tagInfo = resolveTagInfo(categoryId);
+      existing.tag_name = tagInfo.name;
+      await writeMeta(catDir, existing);
+    }
+    return existing;
+  }
+  const tagInfo = resolveTagInfo(categoryId);
+  // Store the Chinese name as category so it's human-readable in .meta.json
+  const m = {
+    $schema:  'https://devflow.dev/schemas/meta.schema.json',
+    category: tagInfo.name,   // e.g. "架构决策"
+    tag_name: tagInfo.name,
+    tag_id:   '',
+    external: {},
+    files:    {},
+  };
+  await writeMeta(catDir, m);
+  return m;
+}
+
+function sha256(buf) {
+  const h = crypto.createHash('sha256');
+  h.update(buf);
+  return h.digest('hex');
+}
+
+/**
+ * Walk all knowledge trees and yield { root, dir, category, file, abs }.
+ *
+ * Supports BOTH the new flat layout (knowledge/<category>/)
+ * AND the legacy nested layout (knowledge/<domain>/<category>/)
+ * so old projects can migrate gradually.
+ */
+async function walkKnowledge(root, opts = {}) {
+  const out = [];
+  for (const dir of knowledgeRoots(root, opts)) {
+    await walkKnowledgeRoot(dir, out);
+  }
+  return out;
+}
+
+function knowledgeRoots(root, opts = {}) {
+  const dirs = [];
+  const add = (dir) => {
+    if (dir && fsSync.existsSync(dir) && !dirs.includes(dir)) dirs.push(dir);
+  };
+
+  if (opts.slug) {
+    add(paths.workspaceKnowledgeDir(opts.slug));
+    add(path.join(paths.devflowDir(root), 'changes', opts.slug, 'knowledge'));
+    return dirs;
+  }
+
+  add(paths.workspaceKnowledgeRoot());
+
+  const changesDir = paths.changesDir(root);
+  if (fsSync.existsSync(changesDir)) {
+    const entries = fsSync.readdirSync(changesDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) add(path.join(changesDir, e.name, 'knowledge'));
+    }
+  }
+
+  // Legacy project-local knowledge remains readable for older projects.
+  add(paths.knowledgeDir(root));
+  return dirs;
+}
+
+async function walkKnowledgeRoot(dir, out) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const ePath = path.join(dir, e.name);
+    // Check if this is a flat category dir (has .meta.json or .md files directly)
+    const sub = await fs.readdir(ePath, { withFileTypes: true });
+    const hasMd    = sub.some((s) => s.isFile() && s.name.endsWith('.md'));
+    const hasMeta  = sub.some((s) => s.isFile() && s.name === '.meta.json');
+    const hasSubDirs = sub.some((s) => s.isDirectory());
+
+    if (hasMd || hasMeta) {
+      // Flat category dir
+      for (const s of sub) {
+        if (s.isFile() && s.name.endsWith('.md')) {
+          out.push({ root: dir, dir: ePath, category: e.name, file: s.name, abs: path.join(ePath, s.name) });
+        }
+      }
+    } else if (hasSubDirs) {
+      // Legacy nested domain/category layout
+      for (const c of sub) {
+        if (!c.isDirectory()) continue;
+        const cs = path.join(ePath, c.name);
+        const files = await fs.readdir(cs);
+        for (const f of files) {
+          if (!f.endsWith('.md')) continue;
+          out.push({ root: dir, dir: cs, category: c.name, file: f, abs: path.join(cs, f) });
+        }
+      }
+    }
+  }
+}
+
+module.exports = { readMeta, writeMeta, ensureMeta, sha256, walkKnowledge, knowledgeRoots };

package/src/knowledge/sync.js

@@ -0,0 +1,179 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const loader = require('../providers/loader.js');
+const { walkKnowledge, knowledgeRoots, readMeta, writeMeta, sha256 } = require('./registry.js');
+const { buildTagMap, resolveTagInfo } = require('./categories.js');
+
+/**
+ * Push knowledge files to the configured kb provider, incrementally.
+ *
+ * Strategy:
+ *   1. walk knowledge/ tree → collect (cat, file, sha256)
+ *   2. read each category's .meta.json → previously synced sha256 + uuid
+ *   3. diff:
+ *        new file        → provider.upload  → store uuid+sha
+ *        sha changed     → provider.update
+ *        file deleted    → provider.delete  (if registry had uuid)
+ *        unchanged       → noop
+ *   4. write updated .meta.json
+ *
+ * Options:
+ *   { dryRun, force, providerName, slug }
+ *   force=true  → clear all stored UUIDs/sha before diff,
+ *                 so every file is treated as new (re-uploads all).
+ *                 Use after fixing an API misconfiguration that caused empty uploads.
+ *
+ * Returns { actions: [...], summary: { create, update, delete, noop } }
+ */
+async function sync(root, opts = {}) {
+  const { dryRun = false, force = false, providerName, slug } = opts;
+  const provider = await loader.load(root, providerName ? { name: providerName } : { type: 'kb' });
+
+  const summary = { create: 0, update: 0, delete: 0, noop: 0, tag: 0, scanned: 0 };
+  const actions = [];
+  const tagMap = buildTagMap((provider.config && provider.config.tags) || {});
+  // Collect { uuid → tagId } for docs that exist but were never tagged (or tag changed)
+  const pendingTagUpdates = {};
+
+  // ── Pre-create ALL known tags before uploading any documents ──────────────
+  // This ensures tags exist and tag_ids are cached before the first upload,
+  // so every document gets tagged immediately at creation time.
+  if (typeof provider.ensureTag === 'function') {
+    for (const [_catSlug, tagInfo] of Object.entries(tagMap)) {
+      try {
+        await provider.ensureTag(tagInfo.name, tagInfo.color, tagInfo.order);
+      } catch { /* non-fatal: continue without this tag */ }
+    }
+  }
+
+  // Build current view per category (from disk).
+  // Flat layout: key = category slug  (e.g. "decisions")
+  const all = await walkKnowledge(root, { slug });
+  const byCat = {}; // dir -> { key, dir, files: { name -> { abs, sha } } }
+  for (const f of all) {
+    const dir = f.dir;
+    const key = f.category;
+    if (!byCat[dir]) byCat[dir] = { key, dir, files: {} };
+    const buf = await fs.readFile(f.abs);
+    byCat[dir].files[f.file] = { abs: f.abs, sha: sha256(buf), buf };
+    summary.scanned++;
+  }
+
+  // Also include dirs that have a .meta.json but no files (detect deletions).
+  for (const kbDir of knowledgeRoots(root, { slug })) {
+    const entries = await fs.readdir(kbDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const eDir = path.join(kbDir, e.name);
+      if (fsSync.existsSync(path.join(eDir, '.meta.json'))) {
+        if (!byCat[eDir]) byCat[eDir] = { key: e.name, dir: eDir, files: {} };
+      }
+    }
+  }
+  // key is now the Chinese directory name (e.g. "架构决策") or English slug for legacy dirs
+
+  for (const catDir of Object.keys(byCat)) {
+    const { key, dir, files } = byCat[catDir];
+    let meta = (await readMeta(dir)) || { category: path.basename(dir), files: {}, external: {} };
+    meta.files = meta.files || {};
+
+    // --force: clear all stored UUIDs/sha so every file is re-uploaded as new
+    if (force) {
+      for (const name of Object.keys(meta.files)) {
+        delete meta.files[name].uuid;
+        delete meta.files[name].sha256;
+      }
+    }
+
+    // ── Resolve tag_id for this category ─────────────────────────────────
+    // All tags were pre-created above; here we just look them up from cache.
+    // key is category slug (e.g. "decisions").
+    const tagInfo = resolveTagInfo(key, null, tagMap);
+    let tagId = (meta.tag_name === tagInfo.name) ? (meta.tag_id || '') : '';
+    if (!tagId && typeof provider.ensureTag === 'function') {
+      try {
+        const tag = await provider.ensureTag(tagInfo.name, tagInfo.color, tagInfo.order);
+        if (tag && tag.id) {
+          tagId = tag.id;
+          meta.tag_id   = tag.id;
+          meta.tag_name = tag.name;
+        }
+      } catch (e) {
+        actions.push({ kind: 'warn', dir: key, error: `ensureTag failed: ${e.message}` });
+      }
+    }
+
+    // create / update
+    for (const name of Object.keys(files)) {
+      const cur = files[name];
+      const reg = meta.files[name] || {};
+      const uploadMeta = { category: meta.category, filename: name, tag_id: tagId };
+
+      if (reg.uuid && reg.sha256 === cur.sha) {
+        // Content unchanged — but check if tag needs to be applied retroactively.
+        // A doc needs tag patching when:
+        //   - we now have a tagId
+        //   - the stored tag_id doesn't match (including previously untagged docs)
+        if (tagId && reg.tag_id !== tagId) {
+          pendingTagUpdates[reg.uuid] = tagId;
+          meta.files[name] = { ...reg, tag_id: tagId };
+          actions.push({ kind: 'tag', name, dir: key, uuid: reg.uuid });
+          summary.tag++;
+        } else {
+          summary.noop++;
+          actions.push({ kind: 'noop', name, dir: key });
+        }
+        continue;
+      }
+
+      if (!reg.uuid) {
+        actions.push({ kind: 'create', name, dir: key });
+        if (!dryRun) {
+          const r = await provider.upload(cur.abs, uploadMeta);
+          meta.files[name] = { ...reg, uuid: r.uuid, url: r.url || null, sha256: cur.sha, tag_id: tagId || null, synced_at: now() };
+        }
+        summary.create++;
+      } else {
+        actions.push({ kind: 'update', name, dir: key, uuid: reg.uuid });
+        if (!dryRun) {
+          await provider.update(reg.uuid, cur.abs, uploadMeta);
+          meta.files[name] = { ...reg, sha256: cur.sha, tag_id: tagId || null, synced_at: now() };
+        }
+        summary.update++;
+      }
+    }
+
+    // delete: in registry but not on disk
+    for (const name of Object.keys(meta.files)) {
+      if (files[name]) continue;
+      const reg = meta.files[name];
+      if (!reg || !reg.uuid) { delete meta.files[name]; continue; }
+      actions.push({ kind: 'delete', name, dir: key, uuid: reg.uuid });
+      if (!dryRun) {
+        try { await provider.delete(reg.uuid); } catch (e) { actions[actions.length-1].error = e.message; }
+        delete meta.files[name];
+      }
+      summary.delete++;
+    }
+
+    if (!dryRun) await writeMeta(dir, meta);
+  }
+
+  // ── Batch-apply tags for docs that were previously untagged ─────────────
+  if (!dryRun && Object.keys(pendingTagUpdates).length > 0
+      && typeof provider.batchUpdateTags === 'function') {
+    try {
+      await provider.batchUpdateTags(pendingTagUpdates);
+    } catch (e) {
+      actions.push({ kind: 'warn', error: `batchUpdateTags failed: ${e.message}` });
+    }
+  }
+
+  return { actions, summary };
+}
+
+function now() { return new Date().toISOString(); }
+
+module.exports = { sync };