@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_site/lib/hook-manager.js

@@ -1,202 +1,203 @@
-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,
-};
+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, dataDir, bridgeHomeDir, bridgeModulePath }) {
+  validateProjectId(projectId);
+  if (!triggerScriptPath) throw new DomainError('HOOK_INVALID', 'triggerScriptPath is required.', { status: 400 });
+  const trigger = path.resolve(triggerScriptPath);
+  const binding = [[dataDir && '--data-dir', dataDir], [bridgeHomeDir && '--bridge-home', bridgeHomeDir], [bridgeModulePath && '--bridge-module', bridgeModulePath]].filter(([flag]) => flag).map(([flag, value]) => ` ${flag} ${shellQuote(value)}`).join('');
+  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"${binding} >/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({ ...options, 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 && options.replaceManagedHookProjectId !== marker.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,
+};