project-knowledge 0.1.0

package/_site/lib/context-pack-builder.js

@@ -0,0 +1,290 @@
+// Context Pack Builder (TASK-006)
+// Collects Git diff / stats, project goal, related feature/module docs,
+// package/config files, neighbouring source, and tests into a machine-readable
+// context pack written to projects/<slug>/_ai/context-packs/<run-id>/.
+//
+// Path safety: every path is normalized and verified to live inside the project root
+// before it is added to the pack. Outside-the-project paths are rejected.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execGit } = require('./git-runner');
+
+const MAX_FILE_BYTES = 200 * 1024;     // Skip files larger than 200 KB
+const MAX_EXCERPT_BYTES = 8 * 1024;    // Excerpt limited to 8 KB
+const BINARY_DETECT_BYTES = 4096;      // Read up to 4 KB to detect binary
+
+const PACKAGE_CONFIG_FILES = [
+  'package.json', 'package-lock.json', 'pnpm-workspace.yaml', 'pnpm-lock.yaml',
+  'tsconfig.json', 'tsconfig.base.json', 'pyproject.toml', 'setup.py', 'requirements.txt',
+  'Cargo.toml', 'Cargo.lock', 'go.mod', 'go.sum', 'pom.xml', 'build.gradle',
+  '.eslintrc.json', '.eslintrc.js', '.prettierrc.json',
+];
+
+function shortHash(input) {
+  return crypto.createHash('sha1').update(input).digest('hex').slice(0, 12);
+}
+
+function isSafePath(projectRoot, target) {
+  const resolved = path.resolve(projectRoot, target);
+  const root = path.resolve(projectRoot);
+  // Use a separator-aware check so 'proj-other' does not pass 'proj' as parent.
+  return resolved === root || resolved.startsWith(root + path.sep) || resolved.startsWith(root + '/');
+}
+
+function isBinaryBuffer(buf) {
+  const limit = Math.min(BINARY_DETECT_BYTES, buf.length);
+  for (let i = 0; i < limit; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+function readSafeExcerpt(absPath) {
+  let stat;
+  try { stat = fs.statSync(absPath); } catch { return null; }
+  if (!stat.isFile()) return null;
+  if (stat.size > MAX_FILE_BYTES) {
+    return { excerpt: null, size: stat.size, binary: false, skipped: 'too-large' };
+  }
+  let buf;
+  try { buf = fs.readFileSync(absPath); } catch { return null; }
+  if (isBinaryBuffer(buf)) {
+    return { excerpt: null, size: stat.size, binary: true, skipped: 'binary' };
+  }
+  const text = buf.toString('utf-8');
+  if (text.length > MAX_EXCERPT_BYTES) {
+    return { excerpt: text.slice(0, MAX_EXCERPT_BYTES) + '\n...[truncated]', size: stat.size, binary: false, truncated: true };
+  }
+  return { excerpt: text, size: stat.size, binary: false, truncated: false };
+}
+
+function getNeighborPaths(projectRoot, changedFiles) {
+  const neighbors = new Set();
+  for (const file of changedFiles) {
+    if (!file) continue;
+    const dir = path.dirname(file);
+    if (!dir || dir === '.') continue;
+    try {
+      const entries = fs.readdirSync(path.join(projectRoot, dir), { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile()) continue;
+        if (e.name.startsWith('.')) continue;
+        const rel = path.posix.join(dir, e.name).replace(/\\/g, '/');
+        if (changedFiles.includes(rel)) continue;
+        neighbors.add(rel);
+      }
+    } catch {}
+  }
+  return [...neighbors];
+}
+
+function getTestPaths(projectRoot, changedFiles) {
+  const tests = new Set();
+  const isTestName = (name) => /\.(test|spec)\.[a-z]+$/i.test(name) || /^test[s]?[\/\\]/i.test(name) || /__tests__[\/\\]/i.test(name);
+  // Tests in the same directory tree, and direct "test" / "tests" siblings
+  for (const file of changedFiles) {
+    if (!file) continue;
+    const dir = path.dirname(file);
+    // Same-dir tests
+    try {
+      const entries = fs.readdirSync(path.join(projectRoot, dir), { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile()) continue;
+        if (isTestName(e.name)) {
+          tests.add(path.posix.join(dir, e.name).replace(/\\/g, '/'));
+        }
+      }
+    } catch {}
+    // Direct test/ folder sibling
+    for (const candidate of ['tests', 'test', '__tests__']) {
+      const testDir = path.join(projectRoot, dir, candidate);
+      if (!fs.existsSync(testDir)) continue;
+      try {
+        const entries = fs.readdirSync(testDir, { withFileTypes: true });
+        for (const e of entries) {
+          if (!e.isFile()) continue;
+          if (isTestName(e.name)) {
+            tests.add(path.posix.join(dir, candidate, e.name).replace(/\\/g, '/'));
+          }
+        }
+      } catch {}
+    }
+  }
+  return [...tests];
+}
+
+function findRelatedDocs(projectRoot, changedFiles) {
+  // Map files to existing feature/module docs by directory match.
+  // Lightweight heuristic: any feature or module doc whose frontmatter lists paths
+  // that intersect the changed files is "related". If frontmatter does not exist
+  // (legacy docs), fall back to filename match.
+  const out = new Set();
+  const featuresDir = path.join(projectRoot, 'features');
+  const modulesDir = path.join(projectRoot, 'modules');
+  for (const dir of [featuresDir, modulesDir]) {
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      const full = path.join(dir, e.name);
+      let text;
+      try { text = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+      const rel = path.posix.join(path.basename(dir), e.name).replace(/\\/g, '/');
+      // Heuristic: if any changed file path is mentioned in the doc body, treat as related.
+      for (const f of changedFiles) {
+        if (f && text.includes(f)) { out.add(rel); break; }
+      }
+    }
+  }
+  return [...out];
+}
+
+async function buildContextPack({ project, runId, trigger, commits = [], options = {} }) {
+  if (!project || !project.slug) throw new Error('project required');
+  const slug = project.slug;
+  if (!project.kbPath) throw new Error('project.kbPath is required');
+  const projectRoot = path.resolve(project.kbPath);
+  if (!isSafePath(projectRoot, '')) throw new Error('unsafe project root');
+
+  const gitPath = project.gitPath || project.localPath;
+  if (!gitPath) throw new Error('project has no git/local path');
+  const sourceRoot = path.resolve(gitPath); // source files live in the git repo, not the KB
+
+  const maxFiles = options.maxFiles || 80;
+  const entries = [];
+  const seenAbs = new Set();
+  const safeSeen = (rel) => entries.find(e => e.path === rel);
+
+  function addEntry(rel, kind, reason) {
+    if (entries.length >= maxFiles) return;
+    // Decide which root to read from: KB files are anchored at projectRoot,
+    // source files are anchored at sourceRoot.
+    const isKbKind = ['goal', 'analysis', 'feature-doc', 'module-doc'].includes(kind);
+    const root = isKbKind ? projectRoot : sourceRoot;
+    if (!isSafePath(root, rel)) return; // path traversal guard
+    if (safeSeen(rel)) return;
+    const abs = path.join(root, rel);
+    if (seenAbs.has(abs)) return;
+    if (!fs.existsSync(abs)) return;
+    let stat;
+    try { stat = fs.statSync(abs); } catch { return; }
+    if (!stat.isFile()) return;
+    const data = readSafeExcerpt(abs);
+    if (!data) return;
+    entries.push({
+      path: rel.replace(/\\/g, '/'),
+      kind,
+      reason,
+      size: data.size,
+      binary: data.binary,
+      truncated: !!data.truncated,
+      skipped: data.skipped || null,
+      excerpt: data.excerpt,
+    });
+    seenAbs.add(abs);
+  }
+
+  // 1. project-goal.md (highest-priority context)
+  if (fs.existsSync(path.join(projectRoot, 'project-goal.md'))) {
+    addEntry('project-goal.md', 'goal', 'highest-priority human-controlled truth');
+  }
+
+  // 2. project-analysis.md
+  if (fs.existsSync(path.join(projectRoot, 'project-analysis.md'))) {
+    addEntry('project-analysis.md', 'analysis', 'current AI-generated description');
+  }
+
+  let changedFiles = [];
+  let range = null;
+  let diffStat = null;
+
+  if (trigger === 'commits' && commits.length > 0) {
+    // 3a. Collect every file touched by any of the commits (use git show --name-only).
+    // This is safer than `diff first^..last` because the first commit has no parent.
+    const seen = new Set();
+    for (const c of commits) {
+      const r = await execGit(gitPath, ['show', '--name-only', '--format=', c.hash]);
+      if (r.ok) {
+        for (const line of (r.stdout || '').split('\n')) {
+          const f = line.trim();
+          if (f) seen.add(f);
+        }
+      }
+    }
+    changedFiles = [...seen];
+    range = `${commits[0].hash.slice(0, 7)}..${commits[commits.length - 1].hash.slice(0, 7)} (${commits.length} commit${commits.length === 1 ? '' : 's'})`;
+    // shortstat across the union of commits
+    const stat = await execGit(gitPath, ['diff', '--shortstat', `${commits[0].hash}^`, commits[commits.length - 1].hash]);
+    if (stat.ok) diffStat = (stat.stdout || '').trim();
+  } else {
+    // initial: enumerate tracked files (top N by size is overkill — just take first maxFiles)
+    const ls = await execGit(gitPath, ['ls-files']);
+    if (ls.ok) {
+      changedFiles = (ls.stdout || '').split('\n').map(s => s.trim()).filter(Boolean);
+    }
+    range = 'all-tracked-files';
+  }
+
+  // 3b. Changed files (as evidence)
+  for (const f of changedFiles) addEntry(f, 'git-changed', trigger === 'commits' ? `changed in ${range}` : 'tracked file');
+
+  // 4. Package / config files (look in source root)
+  for (const f of PACKAGE_CONFIG_FILES) {
+    if (fs.existsSync(path.join(sourceRoot, f))) addEntry(f, 'package-config', 'package or build configuration');
+  }
+
+  // 5. Neighbouring source files (in source root)
+  for (const f of getNeighborPaths(sourceRoot, changedFiles)) {
+    addEntry(f, 'neighbor', 'sibling of a changed file');
+  }
+
+  // 6. Tests near changed files (in source root)
+  for (const f of getTestPaths(sourceRoot, changedFiles)) {
+    addEntry(f, 'test-nearby', 'test for a changed file');
+  }
+
+  // 7. Related feature / module docs (look in KB root)
+  for (const f of findRelatedDocs(projectRoot, changedFiles)) {
+    addEntry(f, 'feature-doc', 'mentions a changed file');
+  }
+
+  const pack = {
+    schema: 'context-pack/v1',
+    runId: runId || shortHash(`${slug}:${Date.now()}:${Math.random()}`),
+    project: slug,
+    createdAt: new Date().toISOString(),
+    trigger: trigger || 'initial',
+    gitPath,
+    range,
+    diffStat,
+    commitCount: commits.length,
+    commits: commits.map(c => ({ hash: c.hash, short: c.short, subject: c.subject, date: c.date, author: c.author })),
+    entries,
+    limits: {
+      maxFiles,
+      maxFileBytes: MAX_FILE_BYTES,
+      maxExcerptBytes: MAX_EXCERPT_BYTES,
+    },
+  };
+
+  // 8. Write to disk
+  const outDir = path.join(projectRoot, '_ai', 'context-packs', pack.runId);
+  if (!isSafePath(projectRoot, path.relative(projectRoot, outDir))) {
+    throw new Error('unsafe output path');
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(path.join(outDir, 'context-pack.json'), JSON.stringify(pack, null, 2), 'utf-8');
+
+  return pack;
+}
+
+module.exports = {
+  buildContextPack,
+  isSafePath,
+  PACKAGE_CONFIG_FILES,
+  MAX_FILE_BYTES,
+  MAX_EXCERPT_BYTES,
+};

package/_site/lib/draft-apply.js

@@ -0,0 +1,219 @@
+// Draft Apply (TASK-009)
+//
+// Validates a draft, optionally creates backups of any file it would overwrite,
+// writes the new content into the formal KB, updates kb-manifest.json, and (for
+// commit-analysis runs) advances lastAnalyzedCommit to the head commit captured
+// at run time.
+//
+// Hard rules:
+//   * `project-goal.md` is only written when the caller passes `allowGoalEdit: true`.
+//     Any other call that would touch the goal returns 409.
+//   * All file writes are best-effort transactional: we write to a backup
+//     directory first, then swap into place. If a partial failure occurs, the
+//     run is marked `applyStatus: failed` and no KB file is left in a half-written state.
+
+const fs = require('fs');
+const path = require('path');
+
+const TRUSTED_GOAL_REL = 'project-goal.md';
+
+function readManifest(kbPath) {
+  const p = path.join(kbPath, 'kb-manifest.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+function writeManifest(kbPath, manifest) {
+  fs.writeFileSync(path.join(kbPath, 'kb-manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+function isSafeApplyPath(kbPath, rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return false;
+  if (path.isAbsolute(rel)) return false;
+  const resolved = path.resolve(kbPath, rel);
+  const root = path.resolve(kbPath);
+  // Reject anything that resolves outside the KB root, even with sibling-prefix bypass
+  // (e.g. "/kb-other" passes a naive "startsWith(/kb)" check).
+  const relPath = path.relative(root, resolved);
+  if (relPath.startsWith('..') || path.isAbsolute(relPath)) return false;
+  // Forbid writes to internal AI areas (we never want an apply to write to _ai/ from a draft)
+  const norm = rel.replace(/\\/g, '/');
+  if (norm.startsWith('_ai/') || norm.split('/').includes('_ai')) return false;
+  return true;
+}
+
+function listDraftFiles(kbPath, runId) {
+  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else out.push({ path: path.relative(dir, full).replace(/\\/g, '/'), full });
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function validateDraftSchema(draft) {
+  // A draft is a single file produced by the orchestrator. It must:
+  //   * have a non-empty path (relative to KB root, no leading slash)
+  //   * have non-empty text content
+  //   * be a known safe extension (.md, .json)
+  if (!draft || typeof draft !== 'object') return { valid: false, errors: ['draft must be an object'] };
+  if (!draft.path || typeof draft.path !== 'string') return { valid: false, errors: ['draft.path required'] };
+  if (draft.path.startsWith('/') || draft.path.startsWith('\\')) return { valid: false, errors: ['draft.path must be relative'] };
+  const ext = path.extname(draft.path).toLowerCase();
+  if (ext !== '.md' && ext !== '.json') return { valid: false, errors: ['draft.path must be .md or .json'] };
+  if (typeof draft.content !== 'string' || draft.content.length === 0) return { valid: false, errors: ['draft.content required'] };
+  return { valid: true };
+}
+
+function backupExisting(kbPath, backupsDir, rel) {
+  const src = path.join(kbPath, rel);
+  if (!fs.existsSync(src)) return null;
+  const dest = path.join(backupsDir, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return dest;
+}
+
+function applyDrafts({ kbPath, slug, runId, drafts, allowGoalEdit, headCommitAtRun }) {
+  if (!kbPath || !slug || !runId) return { ok: false, status: 400, error: 'kbPath, slug, runId required' };
+  if (!Array.isArray(drafts) || drafts.length === 0) return { ok: false, status: 400, error: 'drafts must be a non-empty array' };
+
+  // 1. Validate every draft before touching anything
+  const errors = [];
+  const prepared = [];
+  for (const d of drafts) {
+    const v = validateDraftSchema(d);
+    if (!v.valid) { errors.push({ draft: d && d.path, errors: v.errors }); continue; }
+    if (!isSafeApplyPath(kbPath, d.path)) { errors.push({ draft: d.path, errors: ['unsafe path'] }); continue; }
+    if (d.path === TRUSTED_GOAL_REL && !allowGoalEdit) {
+      errors.push({ draft: d.path, errors: ['refusing to overwrite project-goal.md without allowGoalEdit=true'] });
+      continue;
+    }
+    prepared.push(d);
+  }
+  if (errors.length) return { ok: false, status: 422, error: 'invalid drafts', errors };
+  if (prepared.length === 0) return { ok: false, status: 400, error: 'no valid drafts after validation' };
+
+  // 2. Backup everything we will overwrite, into _ai/backups/<runId>/
+  const backupsDir = path.join(kbPath, '_ai', 'backups', runId);
+  fs.mkdirSync(backupsDir, { recursive: true });
+  const backups = [];
+  for (const d of prepared) {
+    const b = backupExisting(kbPath, backupsDir, d.path);
+    if (b) backups.push({ path: d.path, backup: path.relative(kbPath, b).replace(/\\/g, '/') });
+  }
+
+  // 3. Write each draft. Track failures for rollback.
+  const writes = [];
+  const failed = [];
+  for (const d of prepared) {
+    const dest = path.join(kbPath, d.path);
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, d.content, 'utf-8');
+      writes.push(d.path);
+    } catch (e) {
+      failed.push({ path: d.path, error: e.message });
+    }
+  }
+  if (failed.length) {
+    // Roll back the writes that did succeed
+    for (const rel of writes) {
+      const dest = path.join(kbPath, rel);
+      const backup = path.join(backupsDir, rel);
+      if (fs.existsSync(backup)) {
+        try { fs.copyFileSync(backup, dest); } catch {}
+      } else {
+        try { fs.rmSync(dest, { force: true }); } catch {}
+      }
+    }
+    return { ok: false, status: 500, error: 'partial write failure, rolled back', failed, backups };
+  }
+
+  // 4. Update manifest
+  const manifest = readManifest(kbPath) || { schema: 'kb-manifest/v1', project: slug, trustedKnowledge: [], draftAreas: [] };
+  const today = new Date().toISOString().slice(0, 10);
+  if (!manifest.trustedKnowledge.includes('README.md')) manifest.trustedKnowledge.push('README.md');
+  for (const d of prepared) {
+    if (d.path === TRUSTED_GOAL_REL) {
+      manifest.goal = { path: d.path, status: 'accepted', updatedAt: today };
+    } else if (d.path === 'project-analysis.md') {
+      manifest.analysis = manifest.analysis || {};
+      manifest.analysis.path = d.path;
+      manifest.analysis.updatedAt = today;
+      if (headCommitAtRun) manifest.analysis.lastAnalyzedCommit = headCommitAtRun;
+    } else if (d.path.startsWith('features/')) {
+      if (!manifest.trustedKnowledge.includes('features/')) manifest.trustedKnowledge.push('features/');
+    } else if (d.path.startsWith('modules/')) {
+      if (!manifest.trustedKnowledge.includes('modules/')) manifest.trustedKnowledge.push('modules/');
+    } else if (d.path.startsWith('changes/')) {
+      if (!manifest.trustedKnowledge.includes('changes/')) manifest.trustedKnowledge.push('changes/');
+    } else if (d.path.startsWith('architecture/')) {
+      if (!manifest.trustedKnowledge.includes('architecture/')) manifest.trustedKnowledge.push('architecture/');
+    }
+  }
+  writeManifest(kbPath, manifest);
+
+  // 5. Mark the run as applied (caller is responsible for advancing
+  //    lastAnalyzedCommit since they know the commit-batch size).
+  const runsDir = path.join(kbPath, '_ai', 'runs');
+  const runPath = path.join(runsDir, `${runId}.json`);
+  if (fs.existsSync(runPath)) {
+    try {
+      const run = JSON.parse(fs.readFileSync(runPath, 'utf-8'));
+      run.applyStatus = 'applied';
+      run.appliedAt = new Date().toISOString();
+      run.appliedPaths = writes;
+      run.backups = backups.map(b => b.backup);
+      if (headCommitAtRun) run.advancedLastAnalyzedCommit = headCommitAtRun;
+      fs.writeFileSync(runPath, JSON.stringify(run, null, 2), 'utf-8');
+    } catch {}
+  }
+
+  return { ok: true, applied: writes, backups, manifest };
+}
+
+function rejectDrafts({ kbPath, runId, reason }) {
+  if (!kbPath || !runId) return { ok: false, status: 400, error: 'kbPath and runId required' };
+  const runsDir = path.join(kbPath, '_ai', 'runs');
+  const runPath = path.join(runsDir, `${runId}.json`);
+  if (!fs.existsSync(runPath)) return { ok: false, status: 404, error: 'run not found' };
+  const run = JSON.parse(fs.readFileSync(runPath, 'utf-8'));
+  run.applyStatus = 'rejected';
+  run.rejectedAt = new Date().toISOString();
+  run.rejectionReason = reason || null;
+  fs.writeFileSync(runPath, JSON.stringify(run, null, 2), 'utf-8');
+  return { ok: true, run };
+}
+
+function readDraftContent(kbPath, runId, rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return null;
+  if (path.isAbsolute(rel)) return null;
+  const norm = rel.replace(/\\/g, '/');
+  if (norm.startsWith('../') || norm.includes('/../') || norm.endsWith('/..')) return null;
+  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  const target = path.join(dir, rel);
+  // Reject if the resolved target escapes the drafts dir
+  const relPath = path.relative(dir, target);
+  if (relPath.startsWith('..') || path.isAbsolute(relPath)) return null;
+  if (!fs.existsSync(target)) return null;
+  return fs.readFileSync(target, 'utf-8');
+}
+
+module.exports = {
+  applyDrafts,
+  rejectDrafts,
+  validateDraftSchema,
+  listDraftFiles,
+  readDraftContent,
+  readManifest,
+  writeManifest,
+  isSafeApplyPath,
+  TRUSTED_GOAL_REL,
+};

package/_site/lib/git-runner.js

@@ -0,0 +1,26 @@
+// Shared git runner used by server.js, context-pack-builder.js, and tests.
+// Wraps spawn() with a hard timeout and returns { ok, code, stdout, stderr, error }.
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+
+function execGit(cwd, args, timeoutMs = 8000) {
+  return new Promise((resolve) => {
+    if (!cwd || !fs.existsSync(cwd)) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: 'missing path', error: 'missing path' });
+    }
+    const child = spawn('git', args, { cwd, windowsHide: true, timeout: timeoutMs });
+    let out = '', err = '';
+    child.stdout.on('data', d => out += d.toString('utf-8'));
+    child.stderr.on('data', d => err += d.toString('utf-8'));
+    let timedOut = false;
+    const killer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    child.on('error', e => { clearTimeout(killer); resolve({ ok: false, code: -1, stdout: out, stderr: err, error: e.message }); });
+    child.on('close', code => {
+      clearTimeout(killer);
+      resolve({ ok: code === 0 && !timedOut, code, stdout: out, stderr: err, error: timedOut ? 'timeout' : null });
+    });
+  });
+}
+
+module.exports = { execGit };

package/_site/lib/hook-manager.js

@@ -0,0 +1,148 @@
+// _site/lib/hook-manager.js
+//
+// Install/uninstall a post-commit hook in a project's git repo so that
+// commits automatically trigger a `safe` KB run. The hook is a tiny shim
+// that calls `node <siteRoot>/scripts/hook-trigger.js` with the project
+// repo path.
+//
+// Safety contract:
+//   * The hook is installed as `<repo>/.git/hooks/post-commit`.
+//   * It is a real, standalone script — it does NOT depend on the KB
+//     server being up to commit; it always exits 0.
+//   * The script points at the absolute path of the KB site scripts dir,
+//     so moving either the repo or the KB root is safe only when both
+//     are reinstalled.
+//   * If `<repo>/.git/hooks/post-commit` already exists, we refuse
+//     unless the caller passes `overwrite: true`. This protects any
+//     pre-existing hook the user might rely on.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOOK_NAME = 'post-commit';
+const HOOK_MARKER = '# KB-HOOK-MANAGED';
+
+function isWindows() { return process.platform === 'win32'; }
+
+function repoGitDir(repoPath) {
+  // We expect repoPath to be the work-tree root, but accept either.
+  const direct = path.join(repoPath, '.git');
+  if (fs.existsSync(direct)) {
+    const stat = fs.statSync(direct);
+    if (stat.isDirectory()) {
+      // Normal repo: hooks live in <repo>/.git/hooks
+      return direct;
+    }
+    // Submodule / linked work-tree: .git is a file containing "gitdir: ..."
+    if (stat.isFile()) {
+      const text = fs.readFileSync(direct, 'utf-8').trim();
+      const m = /^gitdir:\s*(.+)$/m.exec(text);
+      if (m) return path.resolve(repoPath, m[1].trim());
+    }
+  }
+  return null;
+}
+
+function gitHooksDir(gitDir) {
+  // Git's hooks directory is `<gitDir>/hooks`, unless core.hooksPath is set.
+  // We respect the env var `GIT_HOOKS_PATH` and `core.hooksPath` by reading
+  // the repo's config; otherwise default to the conventional location.
+  if (!gitDir) return null;
+  const env = process.env.GIT_HOOKS_PATH;
+  if (env) return env;
+  // Try to read the worktree's config: search upward for the git toplevel.
+  // We don't need to do a full `git rev-parse` — we trust that the standard
+  // hooks dir exists.
+  return path.join(gitDir, 'hooks');
+}
+
+function buildHookBody({ siteRoot, host, port }) {
+  // The script is a plain POSIX shell that defers to Node. This works in
+  // Git for Windows (git-bash) and on macOS / Linux.
+  const trigger = path.join(siteRoot, 'scripts', 'hook-trigger.js');
+  // Use forward slashes inside the shim for portability; Windows git-bash
+  // accepts them. Quote with single-quotes for paths that contain spaces.
+  const triggerPosix = trigger.replace(/\\/g, '/');
+  const repoPath = '$REPO_PATH_PLACEHOLDER';
+  const hostLine = host ? `--host ${host}` : '';
+  const portLine = Number.isFinite(port) ? `--port ${port}` : '';
+  return `#!/bin/sh
+${HOOK_MARKER} v1 — auto-installed by KB manager
+# This hook is generated. Editing the marker line will break updates.
+# To remove: 'git hooks uninstall' from the KB manager, or delete this file.
+set -e
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+node '${triggerPosix}' \\
+  --kb-root '${siteRoot.replace(/\\/g, '/')}' \\
+  --repo "${repoPath}" \\
+  ${hostLine} ${portLine} &
+HOOK_PID=$!
+# Wait up to 4 seconds for the trigger to dispatch; otherwise let it run free.
+( sleep 4 && kill -0 "$HOOK_PID" 2>/dev/null && kill "$HOOK_PID" 2>/dev/null ) &
+WATCHER=$!
+wait "$HOOK_PID" 2>/dev/null || true
+kill "$WATCHER" 2>/dev/null || true
+exit 0
+`;
+}
+
+function installHook({ repoPath, siteRoot, host, port, overwrite = false }) {
+  if (!repoPath) return { ok: false, status: 400, error: 'repoPath required' };
+  if (!siteRoot) return { ok: false, status: 400, error: 'siteRoot required' };
+  const abs = path.resolve(repoPath);
+  const gitDir = repoGitDir(abs);
+  if (!gitDir) return { ok: false, status: 400, error: `no .git directory under ${abs}` };
+  const hooksDir = gitHooksDir(gitDir);
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, HOOK_NAME);
+  if (fs.existsSync(hookPath) && !overwrite) {
+    const existing = fs.readFileSync(hookPath, 'utf-8');
+    if (!existing.includes(HOOK_MARKER)) {
+      return { ok: false, status: 409, error: `${HOOK_NAME} already exists and is not KB-managed. Pass overwrite:true to replace.` };
+    }
+  }
+  let body = buildHookBody({ siteRoot, host, port });
+  body = body.replace('$REPO_PATH_PLACEHOLDER', abs.replace(/\\/g, '/'));
+  fs.writeFileSync(hookPath, body, { mode: 0o755 });
+  return { ok: true, hookPath, repoPath: abs };
+}
+
+function uninstallHook({ repoPath }) {
+  if (!repoPath) return { ok: false, status: 400, error: 'repoPath required' };
+  const abs = path.resolve(repoPath);
+  const gitDir = repoGitDir(abs);
+  if (!gitDir) return { ok: false, status: 400, error: `no .git directory under ${abs}` };
+  const hooksDir = gitHooksDir(gitDir);
+  const hookPath = path.join(hooksDir, HOOK_NAME);
+  if (!fs.existsSync(hookPath)) return { ok: true, removed: false, hookPath };
+  const text = fs.readFileSync(hookPath, 'utf-8');
+  if (!text.includes(HOOK_MARKER)) {
+    return { ok: false, status: 409, error: `${HOOK_NAME} is not KB-managed; refusing to delete. Remove it manually.` };
+  }
+  fs.unlinkSync(hookPath);
+  return { ok: true, removed: true, hookPath };
+}
+
+function readHookStatus({ repoPath }) {
+  if (!repoPath) return { ok: false, status: 400, error: 'repoPath required' };
+  const abs = path.resolve(repoPath);
+  const gitDir = repoGitDir(abs);
+  if (!gitDir) return { ok: true, installed: false, repoPath: abs, reason: 'no .git directory' };
+  const hooksDir = gitHooksDir(gitDir);
+  const hookPath = path.join(hooksDir, HOOK_NAME);
+  if (!fs.existsSync(hookPath)) return { ok: true, installed: false, hookPath, repoPath: abs };
+  const text = fs.readFileSync(hookPath, 'utf-8');
+  if (!text.includes(HOOK_MARKER)) {
+    return { ok: true, installed: false, kbManaged: false, hookPath, repoPath: abs, reason: 'pre-existing hook (not KB-managed)' };
+  }
+  return { ok: true, installed: true, kbManaged: true, hookPath, repoPath: abs, bytes: text.length };
+}
+
+module.exports = {
+  HOOK_NAME,
+  HOOK_MARKER,
+  installHook,
+  uninstallHook,
+  readHookStatus,
+};