@sanqianx/project-knowledge 4.6.1

package/_site/lib/hook-manager.js

@@ -0,0 +1,202 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const AtomicFile = require('./atomic-file');
+const { DomainError, validateProjectId } = require('./contracts');
+
+const HOOK_NAME = 'post-commit';
+const HOOK_MARKER = '# PROJECT-KNOWLEDGE-HOOK ';
+const LEGACY_HOOK_MARKER = '# KB-HOOK-MANAGED v1';
+const MANAGED_VERSION = 2;
+const HOOK_SCHEMA = 'project-knowledge/hook/v2';
+
+function runGit(repoPath, args) {
+  const result = spawnSync('git', ['-C', repoPath, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) {
+    throw new DomainError('HOOK_INVALID', 'Git could not resolve the repository hook path.', {
+      status: 400,
+      details: { gitExitCode: result.status, gitError: String(result.stderr || '').trim().slice(0, 1000) },
+    });
+  }
+  return String(result.stdout || '').trim();
+}
+
+function resolveGitHooksDir(_gitDir, repoPath) {
+  if (!repoPath) throw new DomainError('INVALID_ARGUMENT', 'repoPath is required.');
+  const absolute = path.resolve(repoPath);
+  const hooksPath = runGit(absolute, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+  if (!hooksPath) throw new DomainError('HOOK_INVALID', 'Git returned an empty hooks path.', { status: 400 });
+  return path.resolve(absolute, hooksPath);
+}
+
+function repoGitDir(repoPath) {
+  try { return runGit(path.resolve(repoPath), ['rev-parse', '--path-format=absolute', '--git-dir']); }
+  catch { return null; }
+}
+
+function shellQuote(value) { return `'${String(value).replace(/'/g, `'"'"'`)}'`; }
+function toGitBashPath(value) { return path.resolve(value).replace(/\\/g, '/'); }
+
+function markerFor(projectId) {
+  return `${HOOK_MARKER}${JSON.stringify({ schema: HOOK_SCHEMA, managedVersion: MANAGED_VERSION, projectId })}`;
+}
+
+function parseManagedMarker(text) {
+  const line = String(text || '').split(/\r?\n/).find(item => item.startsWith(HOOK_MARKER));
+  if (!line) return null;
+  try {
+    const marker = JSON.parse(line.slice(HOOK_MARKER.length));
+    if (marker.schema !== HOOK_SCHEMA || marker.managedVersion !== MANAGED_VERSION) return null;
+    validateProjectId(marker.projectId);
+    return marker;
+  } catch { return null; }
+}
+
+function isLegacyManagedHook(text) {
+  return String(text || '').split(/\r?\n/).some(line => line.startsWith(LEGACY_HOOK_MARKER));
+}
+
+function buildHookBody({ projectId, triggerScriptPath, nodeExecutable = process.execPath }) {
+  validateProjectId(projectId);
+  if (!triggerScriptPath) throw new DomainError('HOOK_INVALID', 'triggerScriptPath is required.', { status: 400 });
+  const trigger = path.resolve(triggerScriptPath);
+  if (!fs.existsSync(trigger) || !fs.statSync(trigger).isFile()) {
+    throw new DomainError('HOOK_INVALID', 'Hook trigger script does not exist.', { status: 400 });
+  }
+  // T02 runtime contract: Git invokes the hook from a normal shell, which does
+  // NOT inherit ELECTRON_RUN_AS_NODE=1 the way the Desktop backend does.
+  // Without this prefix, the Electron executable (when used as nodeExecutable
+  // in a packaged Desktop install) would launch as a GUI product instead of
+  // executing the trigger as Node. Pure Node ignores the env var, so the
+  // CLI install path is unaffected.
+  return `#!/bin/sh
+${markerFor(projectId)}
+# Generated by project-knowledge. It captures a durable boundary before best-effort notification.
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+ELECTRON_RUN_AS_NODE=1 ${shellQuote(toGitBashPath(nodeExecutable))} ${shellQuote(toGitBashPath(trigger))} \\
+  --project-id ${shellQuote(projectId)} \\
+  --repo-root "$REPO_ROOT" >/dev/null 2>&1 || true
+exit 0
+`;
+}
+
+function hookPathForRepo(repoPath) {
+  const absolute = path.resolve(repoPath);
+  const gitDir = repoGitDir(absolute);
+  if (!gitDir) throw new DomainError('HOOK_INVALID', 'The project is not a Git repository.', { status: 400 });
+  return path.join(resolveGitHooksDir(gitDir, absolute), HOOK_NAME);
+}
+
+function installHook(options = {}) {
+  const repoPath = path.resolve(String(options.repoPath || ''));
+  const projectId = validateProjectId(options.projectId || options.projectSlug || '');
+  const triggerScriptPath = options.triggerScriptPath || (options.siteRoot ? path.join(options.siteRoot, 'scripts', 'hook-trigger.js') : '');
+  const body = buildHookBody({ projectId, triggerScriptPath, nodeExecutable: options.nodeExecutable });
+  const hookPath = hookPathForRepo(repoPath);
+  fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf8');
+    const marker = parseManagedMarker(existing);
+    if (!marker) {
+      if (!isLegacyManagedHook(existing)) {
+        throw new DomainError('HOOK_CONFLICT', 'A non-managed post-commit hook already exists.', { status: 409 });
+      }
+      // Legacy v1 managed hook: preflight already classifies it as an
+      // in-place upgrade target ("legacy-v1"), so overwrite below instead of
+      // refusing — otherwise import promises a migration the installer
+      // rejects for every repo hooked by an older KB generation.
+    }
+    if (marker && marker.projectId !== projectId) {
+      throw new DomainError('HOOK_CONFLICT', 'The managed hook belongs to another project.', { status: 409 });
+    }
+    if (existing === body) return { ok: true, installed: true, updated: false, hookPath, projectId, managedVersion: MANAGED_VERSION };
+  }
+  AtomicFile.writeFileAtomic(hookPath, body, { mode: 0o755 });
+  try { fs.chmodSync(hookPath, 0o755); } catch {
+    // Windows does not expose POSIX executable bits; the atomic write used mode 0755 where supported.
+  }
+  const readback = fs.readFileSync(hookPath, 'utf8');
+  const marker = parseManagedMarker(readback);
+  if (!marker || marker.projectId !== projectId || !readback.includes(toGitBashPath(triggerScriptPath))) {
+    try { fs.unlinkSync(hookPath); } catch {
+      // Verification failure remains authoritative; the lifecycle journal records rollback residue.
+    }
+    throw new DomainError('HOOK_INVALID', 'Managed hook verification failed.', { status: 500 });
+  }
+  return { ok: true, installed: true, updated: true, hookPath, projectId, managedVersion: MANAGED_VERSION };
+}
+
+function uninstallHook({ repoPath, projectId = '' } = {}) {
+  const absolute = path.resolve(String(repoPath || ''));
+  const hookPath = hookPathForRepo(absolute);
+  if (!fs.existsSync(hookPath)) return { ok: true, removed: false, hookPath };
+  const text = fs.readFileSync(hookPath, 'utf8');
+  const marker = parseManagedMarker(text);
+  if (!marker) throw new DomainError('HOOK_CONFLICT', 'The post-commit hook is not managed by project-knowledge.', { status: 409 });
+  if (projectId && marker.projectId !== validateProjectId(projectId)) throw new DomainError('HOOK_CONFLICT', 'The managed hook belongs to another project.', { status: 409 });
+  fs.unlinkSync(hookPath);
+  return { ok: true, removed: true, hookPath, projectId: marker.projectId };
+}
+
+function readHookStatus({ repoPath, projectId = '' } = {}) {
+  const absolute = path.resolve(String(repoPath || ''));
+  let hookPath;
+  try { hookPath = hookPathForRepo(absolute); }
+  catch (error) { return { ok: true, installed: false, repoPath: absolute, reason: error.message }; }
+  if (!fs.existsSync(hookPath)) return { ok: true, installed: false, hookPath, repoPath: absolute };
+  const text = fs.readFileSync(hookPath, 'utf8');
+  const marker = parseManagedMarker(text);
+  if (!marker) return { ok: true, installed: false, kbManaged: false, hookPath, repoPath: absolute, reason: isLegacyManagedHook(text) ? 'legacy managed hook requires migration' : 'third-party hook' };
+  return {
+    ok: true,
+    installed: !projectId || marker.projectId === projectId,
+    kbManaged: true,
+    hookPath,
+    repoPath: absolute,
+    projectId: marker.projectId,
+    managedVersion: marker.managedVersion,
+    bytes: text.length,
+  };
+}
+
+function migrateManagedHook(options = {}) {
+  const hookPath = hookPathForRepo(options.repoPath);
+  if (!fs.existsSync(hookPath)) return { ok: true, migrated: false, reason: 'missing' };
+  const existing = fs.readFileSync(hookPath, 'utf8');
+  const current = parseManagedMarker(existing);
+  if (current) return { ok: true, migrated: false, reason: 'current', hookPath, managedVersion: current.managedVersion };
+  if (!isLegacyManagedHook(existing)) throw new DomainError('HOOK_CONFLICT', 'A third-party post-commit hook cannot be migrated.', { status: 409 });
+  const result = installLegacyReplacement(options, hookPath);
+  return { ...result, migrated: true };
+}
+
+function installLegacyReplacement(options, hookPath) {
+  const body = buildHookBody(options);
+  AtomicFile.writeFileAtomic(hookPath, body, { mode: 0o755 });
+  try { fs.chmodSync(hookPath, 0o755); } catch {
+    // Windows does not expose POSIX executable bits; the atomic write used mode 0755 where supported.
+  }
+  const marker = parseManagedMarker(fs.readFileSync(hookPath, 'utf8'));
+  if (!marker) throw new DomainError('HOOK_INVALID', 'Migrated hook verification failed.', { status: 500 });
+  return { ok: true, installed: true, updated: true, hookPath, projectId: marker.projectId, managedVersion: marker.managedVersion };
+}
+
+module.exports = {
+  HOOK_NAME,
+  HOOK_MARKER,
+  LEGACY_HOOK_MARKER,
+  MANAGED_VERSION,
+  HOOK_SCHEMA,
+  resolveGitHooksDir,
+  repoGitDir,
+  parseManagedMarker,
+  buildHookBody,
+  installHook,
+  uninstallHook,
+  readHookStatus,
+  migrateManagedHook,
+};

package/_site/lib/index-builder.js

@@ -0,0 +1,157 @@
+const fs = require('fs');
+const path = require('path');
+
+const MAX_INDEX_ITEMS = 40;
+const MAX_MODULE_ITEMS = 80;
+const MAX_TAGS = 4;
+const MAX_SOURCE_PATHS = 3;
+const MAX_LOOKUPS = 4;
+const MAX_CELL_CHARS = 120;
+const GENERATED_NOTICE = '<!-- Generated by project-knowledge. Do not edit manually. -->';
+
+function parseFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(String(text || ''));
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (!m) continue;
+    let value = m[2].trim();
+    if (/^\[.*\]$/.test(value)) {
+      value = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+    }
+    meta[m[1]] = value;
+  }
+  return meta;
+}
+
+function listMarkdown(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '00-index.md')
+    .map(entry => {
+      const rel = entry.name;
+      const full = path.join(dir, entry.name);
+      const text = fs.readFileSync(full, 'utf-8');
+      const meta = parseFrontmatter(text);
+      const title = meta.title || text.match(/^#\s+(.+)$/m)?.[1] || entry.name.replace(/\.md$/, '');
+      return { rel, full, meta, title, updatedAt: meta.updatedAt || meta.period || '' };
+    });
+}
+
+function metaList(value) {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  if (!value) return [];
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function compactList(value, limit) {
+  const items = metaList(value);
+  if (items.length <= limit) return items.join(', ');
+  return `${items.slice(0, limit).join(', ')} (+${items.length - limit})`;
+}
+
+function cell(value, maxChars = MAX_CELL_CHARS) {
+  const text = Array.isArray(value) ? value.join(', ') : String(value || '');
+  const clean = text.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').trim();
+  if (!clean) return '-';
+  return clean.length > maxChars ? `${clean.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…` : clean;
+}
+
+function indexSummary(total, shown) {
+  return shown < total
+    ? `Items: ${total} (showing ${shown}; use knowledge search or file search for older entries)`
+    : `Items: ${total}`;
+}
+
+function markdownLink(title, rel) {
+  const label = cell(title, 80).replace(/\[/g, '\\[').replace(/\]/g, '\\]');
+  const target = encodeURI(String(rel || '')).replace(/\(/g, '%28').replace(/\)/g, '%29');
+  return `[${label}](./${target})`;
+}
+
+function renderModuleIndex(kbPath) {
+  const dir = path.join(kbPath, 'modules');
+  const items = listMarkdown(dir).sort((a, b) => a.title.localeCompare(b.title));
+  const visible = items.slice(0, MAX_MODULE_ITEMS);
+  const lines = [
+    GENERATED_NOTICE,
+    '',
+    '# Modules Index',
+    '',
+    indexSummary(items.length, visible.length),
+    '',
+    '| Module | Tags | Source Paths | Routes / Symbols | Updated |',
+    '|---|---|---|---|---|',
+  ];
+  for (const item of visible) {
+    const tagsText = compactList(item.meta.tags, MAX_TAGS);
+    const sourcePaths = compactList(item.meta.sourcePaths, MAX_SOURCE_PATHS);
+    const routes = metaList(item.meta.routes);
+    const symbols = metaList(item.meta.symbols);
+    const lookup = compactList([...routes, ...symbols], MAX_LOOKUPS);
+    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(sourcePaths)} | ${cell(lookup)} | ${cell(item.updatedAt)} |`);
+  }
+  if (!items.length) lines.push('| No modules yet | - | - | - | - |');
+  return { path: 'modules/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
+}
+
+function writeModuleIndex(kbPath) {
+  const rendered = renderModuleIndex(kbPath);
+  const dest = path.join(kbPath, rendered.path);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, rendered.content, 'utf-8');
+  return { path: rendered.path, count: rendered.count };
+}
+
+function renderChangesIndex(kbPath) {
+  const dir = path.join(kbPath, 'changes');
+  const items = listMarkdown(dir).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)) || a.title.localeCompare(b.title));
+  const visible = items.slice(0, MAX_INDEX_ITEMS);
+  const lines = [
+    GENERATED_NOTICE,
+    '',
+    '# Changes Index',
+    '',
+    indexSummary(items.length, visible.length),
+    '',
+    '| Change | Tags | Affected Modules | Period / Updated | Intent |',
+    '|---|---|---|---|---|',
+  ];
+  for (const item of visible) {
+    const tagsText = compactList(item.meta.tags, MAX_TAGS);
+    const affected = compactList(item.meta.affectedModules, MAX_SOURCE_PATHS);
+    const intent = item.meta.developmentIntent || item.meta.intent || '';
+    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(affected)} | ${cell(item.updatedAt)} | ${cell(intent)} |`);
+  }
+  if (!items.length) lines.push('| No changes yet | - | - | - | - |');
+  return { path: 'changes/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
+}
+
+function writeChangesIndex(kbPath) {
+  const rendered = renderChangesIndex(kbPath);
+  const dest = path.join(kbPath, rendered.path);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, rendered.content, 'utf-8');
+  return { path: rendered.path, count: rendered.count };
+}
+
+function regenerateIndexes(kbPath) {
+  return {
+    modules: writeModuleIndex(kbPath),
+    changes: writeChangesIndex(kbPath),
+  };
+}
+
+module.exports = {
+  parseFrontmatter,
+  compactList,
+  cell,
+  markdownLink,
+  GENERATED_NOTICE,
+  renderModuleIndex,
+  renderChangesIndex,
+  regenerateIndexes,
+  writeModuleIndex,
+  writeChangesIndex,
+};

package/_site/lib/index-service.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const { DomainError, createId, validateProjectId } = require('./contracts');
+const { StorageLayout } = require('./storage-layout');
+const { ProjectRegistryStore } = require('./project-registry-store');
+const { ProjectStore } = require('./project-store');
+const { CHUNKER_VERSION, listMarkdownFiles } = require('./markdown-knowledge-indexer');
+const { sha256 } = require('./knowledge-schema');
+
+let globalWriterTail = Promise.resolve();
+
+function buildSourceManifest(projectId, knowledgePath, generation, sourceCommit = '') {
+  const root = path.resolve(knowledgePath);
+  const entries = {};
+  for (const filePath of listMarkdownFiles(root)) {
+    const entryId = path.relative(root, filePath).replace(/\\/g, '/');
+    const markdown = fs.readFileSync(filePath, 'utf8');
+    entries[entryId] = {
+      entryId,
+      documentHash: sha256(`chunker:${CHUNKER_VERSION}\n${markdown}`),
+      sourceCommit: sourceCommit || '',
+    };
+  }
+  return {
+    schema: 'knowledge-index-source-manifest/v1',
+    projectId,
+    generation: Number(generation || 0),
+    sourceCommit: sourceCommit || null,
+    entries,
+    entryCount: Object.keys(entries).length,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function enqueueGlobal(task) {
+  const run = globalWriterTail.catch(() => {}).then(task);
+  globalWriterTail = run.catch(() => {});
+  return run;
+}
+
+class IndexService {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
+    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.adapter = options.adapter || null;
+    this.atomic = options.atomic || AtomicFile;
+    this.logger = options.logger || null;
+    this.pending = new Map();
+  }
+
+  async log(level, event, message, context) {
+    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+  }
+
+  enqueue(projectId) {
+    validateProjectId(projectId);
+    const existing = this.pending.get(projectId);
+    if (existing) {
+      existing.rerun = true;
+      return existing.promise;
+    }
+    const entry = { rerun: false, promise: null };
+    entry.promise = enqueueGlobal(() => this.processEntry(projectId, entry));
+    this.pending.set(projectId, entry);
+    entry.promise.finally(() => {
+      if (this.pending.get(projectId) === entry) this.pending.delete(projectId);
+    });
+    return entry.promise;
+  }
+
+  async processEntry(projectId, entry) {
+    let lastResult = { ok: true, skipped: true };
+    do {
+      entry.rerun = false;
+      lastResult = await this.processProject(projectId);
+      if (!lastResult.ok) return lastResult;
+      const state = this.projectStore.readState(projectId);
+      if (state.index.dirty) entry.rerun = true;
+    } while (entry.rerun);
+    return lastResult;
+  }
+
+  async processProject(projectId) {
+    const config = this.projectStore.readConfig(projectId);
+    const before = this.projectStore.readState(projectId);
+    if (!before.index.dirty) return { ok: true, skipped: true, projectId };
+    const generation = before.index.generation;
+    const operationId = createId('op');
+    try {
+      if (!this.adapter || typeof this.adapter.indexProject !== 'function') throw new DomainError('INVALID_ARGUMENT', 'Index adapter is unavailable.', { status: 503, retryable: true });
+      const result = await this.adapter.indexProject({
+        projectId,
+        config,
+        knowledgePath: config.knowledgePath,
+        indexPath: this.layout.getIndexPath(),
+        generation,
+        sinceCommit: before.index.sinceCommit,
+      });
+      const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, generation, before.index.sinceCommit);
+      this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
+      await this.projectStore.updateState(projectId, state => {
+        if (state.index.generation === generation) {
+          state.index.dirty = false;
+          state.index.sinceCommit = null;
+          state.index.lastError = null;
+          state.index.lastIndexedAt = new Date().toISOString();
+        }
+      });
+      await this.log('info', 'index.project_applied', 'Derived knowledge index updated.', { projectId, operationId, generation, phase: 'index.applied' });
+      return { ok: true, projectId, generation, result: result || null };
+    } catch (error) {
+      await this.projectStore.updateState(projectId, state => {
+        state.index.dirty = true;
+        state.index.lastError = {
+          code: error.code || 'INVALID_ARGUMENT',
+          message: String(error.message || 'Index update failed.'),
+          generation,
+          ts: new Date().toISOString(),
+        };
+      });
+      await this.log('error', 'index.project_failed', 'Derived index update failed; Markdown remains authoritative.', { projectId, operationId, generation, phase: 'index.queued', error });
+      return { ok: false, projectId, generation, error: { code: error.code || 'INVALID_ARGUMENT', message: error.message } };
+    }
+  }
+
+  retryDirtyProjects() {
+    return Promise.all(this.registryStore.listIds()
+      .filter(projectId => this.projectStore.readState(projectId).index.dirty)
+      .map(projectId => this.enqueue(projectId)));
+  }
+
+  async fullRebuild(options = {}) {
+    if (!this.adapter || typeof this.adapter.buildFull !== 'function' || typeof this.adapter.validateIndex !== 'function') {
+      throw new DomainError('INVALID_ARGUMENT', 'Index adapter does not support atomic full rebuild.', { status: 503 });
+    }
+    return enqueueGlobal(async () => {
+      const operationId = options.operationId || createId('op');
+      const target = this.layout.getIndexPath();
+      const parent = path.dirname(target);
+      const temp = path.join(parent, `.knowledge.rebuild.${operationId}`);
+      const backup = this.layout.getRecoveryPath('index', `${operationId}.previous`);
+      if (fs.existsSync(temp)) throw new DomainError('MIGRATION_TARGET_CONFLICT', 'Index rebuild staging already exists.', { status: 409 });
+      const projects = this.registryStore.listIds().map(projectId => ({ projectId, config: this.projectStore.readConfig(projectId) }));
+      try {
+        await this.adapter.buildFull({ targetPath: temp, projects });
+        const validation = await this.adapter.validateIndex(temp);
+        if (!validation || validation.ok !== true) throw new DomainError('DATA_CORRUPT', 'Rebuilt index validation failed.', { status: 500 });
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        if (fs.existsSync(target)) fs.renameSync(target, backup);
+        try { fs.renameSync(temp, target); }
+        catch (error) {
+          if (fs.existsSync(backup) && !fs.existsSync(target)) fs.renameSync(backup, target);
+          throw error;
+        }
+        for (const { projectId, config } of projects) {
+          const state = this.projectStore.readState(projectId);
+          const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, state.index.generation, state.index.sinceCommit);
+          this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
+        }
+        return { ok: true, operationId, target, backup: fs.existsSync(backup) ? backup : null, validation };
+      } catch (error) {
+        if (fs.existsSync(temp)) fs.rmSync(temp, { recursive: true, force: true });
+        throw error;
+      }
+    });
+  }
+
+  static async flush() { await globalWriterTail.catch(() => {}); }
+}
+
+module.exports = { IndexService, enqueueGlobal, buildSourceManifest };