@sanqianx/project-knowledge 4.6.1

package/_site/_test/fixtures/make-git-repos.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function parseArgs(input) {
+  if (Array.isArray(input)) return input.map(String);
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let match;
+  while ((match = re.exec(String(input || '')))) {
+    out.push(match[1] != null ? match[1] : match[2] != null ? match[2] : match[3]);
+  }
+  return out;
+}
+
+function git(cwd, args) {
+  const argv = ['-C', cwd, ...parseArgs(args)];
+  return execFileSync('git', argv, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+function commit(repoPath, message) {
+  git(repoPath, ['add', '.']);
+  git(repoPath, ['commit', '-q', '-m', message]);
+  const hash = git(repoPath, ['rev-parse', 'HEAD']);
+  return {
+    hash,
+    short: hash.slice(0, 7),
+    date: git(repoPath, ['show', '-s', '--format=%ad', '--date=short', 'HEAD']),
+    author: git(repoPath, ['show', '-s', '--format=%an', 'HEAD']),
+    subject: message,
+  };
+}
+
+function initRepo(repoPath) {
+  git(repoPath, ['init', '-q', '-b', 'main']);
+  git(repoPath, ['config', 'user.name', 'Project Knowledge Test']);
+  git(repoPath, ['config', 'user.email', 'project-knowledge-test@example.local']);
+  git(repoPath, ['config', 'commit.gpgsign', 'false']);
+}
+
+function makeRepo({ kind = 'one-commit' } = {}) {
+  const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), `kb-fixture-${kind}-${process.pid}-`));
+  const commits = [];
+  const cleanup = () => fs.rmSync(repoPath, { recursive: true, force: true });
+
+  if (kind === 'not-git') {
+    write(path.join(repoPath, 'README.md'), '# not git\n');
+    return { path: repoPath, commits, headCommit: null, cleanup };
+  }
+
+  initRepo(repoPath);
+
+  if (kind === 'empty') {
+    return { path: repoPath, commits, headCommit: null, cleanup };
+  }
+
+  write(path.join(repoPath, 'README.md'), `# ${kind}\n`);
+  commits.push(commit(repoPath, 'chore: initial commit'));
+
+  if (kind === 'one-commit') {
+    return { path: repoPath, commits, headCommit: commits[commits.length - 1].hash, cleanup };
+  }
+
+  if (kind === 'feature-commit') {
+    write(path.join(repoPath, 'src', 'feature.ts'), 'export const feature = true;\n');
+    commits.push(commit(repoPath, 'feat: add feature module'));
+  } else if (kind === 'multi-commit') {
+    write(path.join(repoPath, 'src', 'a.ts'), 'export const a = 1;\n');
+    commits.push(commit(repoPath, 'feat: add a module'));
+    write(path.join(repoPath, 'src', 'b.ts'), 'export const b = 2;\n');
+    commits.push(commit(repoPath, 'fix: add b module'));
+  } else if (kind === 'binary-commit') {
+    fs.writeFileSync(path.join(repoPath, 'big.bin'), Buffer.alloc(256 * 1024, 7));
+    commits.push(commit(repoPath, 'feat: add binary fixture'));
+  } else {
+    cleanup();
+    throw new Error(`unknown fixture kind: ${kind}`);
+  }
+
+  return { path: repoPath, commits, headCommit: commits[commits.length - 1].hash, cleanup };
+}
+
+module.exports = { makeRepo, git };

package/_site/_test/folder-picker-output-test.js

@@ -0,0 +1,19 @@
+const assert = require('assert');
+const { selectedDirectoryFromOutput } = require('../lib/folder-picker-output');
+
+const banner = '������µĿ�ƽ̨ PowerShell https://aka.ms/pscore6';
+assert.equal(selectedDirectoryFromOutput(banner, { exists: () => false }), '',
+  'PowerShell banner text must never be accepted as a selected folder');
+
+const folder = 'D:\\work\\project';
+assert.equal(selectedDirectoryFromOutput(`${banner}\r\n${folder}\r\n`, {
+  exists: candidate => candidate === folder,
+  stat: () => ({ isDirectory: () => true }),
+}), folder, 'the existing absolute directory should be selected from mixed output');
+
+assert.equal(selectedDirectoryFromOutput('relative-folder', {
+  exists: () => true,
+  stat: () => ({ isDirectory: () => true }),
+}), '', 'relative output must not be accepted');
+
+console.log('folder-picker-output-test PASS');

package/_site/_test/full-integration-e2e-test.js

@@ -0,0 +1,165 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { RequirementRecorder } = require('../lib/requirement-recorder');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = Number(process.env.KB_FULL_E2E_PORT || 7942);
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `project-knowledge-e2e-${process.pid}-`));
+const DATA_DIR = path.join(TEMP, 'data');
+const REPO = path.join(TEMP, 'repo with 空格');
+const PROJECT_ID = 'project-full-e2e';
+// Git commits fire the managed hook -> hook-trigger -> Bridge journal.
+// Keep that journal inside the test sandbox, never the developer's home.
+const BRIDGE_HOME = path.join(TEMP, 'bridge-home');
+
+function git(args, allowFailure = false) {
+  const result = spawnSync('git', ['-C', REPO, ...args], {
+    encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, KB_DATA_DIR: DATA_DIR, KB_SITE_PORT: String(PORT), AI_CODING_EVENT_BRIDGE_HOME: BRIDGE_HOME },
+  });
+  if (!allowFailure) assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+  return { status: result.status, stdout: String(result.stdout || '').trim(), stderr: String(result.stderr || '').trim() };
+}
+
+function commit(name, content) {
+  fs.writeFileSync(path.join(REPO, `${name}.txt`), `${content}\n`, 'utf8');
+  git(['add', `${name}.txt`]);
+  git(['commit', '-m', name]);
+  return git(['rev-parse', 'HEAD']).stdout;
+}
+
+async function json(method, route, body) {
+  const response = await fetch(`${BASE_URL}${route}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await response.text();
+  return { response, body: text ? JSON.parse(text) : {} };
+}
+
+async function start() {
+  const spawned = spawnServer({
+    root: ROOT, port: PORT, dataDir: DATA_DIR, tag: 'full-e2e',
+    extraEnv: {
+      KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1', KB_MAINTENANCE_INTERVAL_MS: '600000',
+      AI_CODING_EVENT_BRIDGE_HOME: BRIDGE_HOME,
+    },
+  });
+  let output = '';
+  spawned.child.stdout.on('data', chunk => { output += chunk; });
+  spawned.child.stderr.on('data', chunk => { output += chunk; });
+  for (let attempt = 0; attempt < 150; attempt += 1) {
+    try { if ((await fetch(`${BASE_URL}/api/health`)).ok) return { ...spawned, output: () => output }; } catch {}
+    if (spawned.child.exitCode != null) throw new Error(`server exited during startup (${spawned.child.exitCode})\n${output}`);
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`server did not start\n${output}`);
+}
+
+async function stop(spawned) {
+  if (!spawned || spawned.child.exitCode != null) return;
+  const exited = new Promise(resolve => spawned.child.once('exit', resolve));
+  spawned.child.kill();
+  await Promise.race([exited, new Promise(resolve => setTimeout(resolve, 5000))]);
+}
+
+async function waitForState(predicate, label) {
+  let last;
+  for (let attempt = 0; attempt < 250; attempt += 1) {
+    const result = await json('GET', `/api/projects/${PROJECT_ID}`);
+    if (result.response.ok) {
+      last = result.body.project.state;
+      if (predicate(last)) return last;
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`${label} timed out: ${JSON.stringify(last)}`);
+}
+
+(async () => {
+  let server;
+  fs.mkdirSync(REPO, { recursive: true });
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.name', 'Full E2E']);
+  git(['config', 'user.email', 'e2e@example.test']);
+  commit('baseline', 'baseline before import');
+  try {
+    server = await start();
+    let result = await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(TEMP, '用户知识') } });
+    assert(result.response.ok, JSON.stringify(result.body));
+    result = await json('PUT', '/api/ai-profiles', {
+      schema: 'ai-profiles/v1',
+      defaultProfileId: 'fake-profile',
+      profiles: [{ id: 'fake-profile', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'fake-key-for-test' } }],
+    });
+    assert(result.response.ok, JSON.stringify(result.body));
+    result = await json('POST', '/api/projects/import', {
+      projectId: PROJECT_ID, localPath: REPO, displayName: 'Full E2E', aiProfileId: 'fake-profile', knowledgeLanguage: 'en-US',
+    });
+    assert.strictEqual(result.response.status, 201, `${JSON.stringify(result.body)}\n${server.output()}`);
+    const knowledgePath = result.body.config.knowledgePath;
+    assert.deepStrictEqual(fs.readdirSync(knowledgePath), [], 'import must not run AI or generate knowledge');
+    assert.strictEqual(result.body.state.lastAnalyzedCommit, null);
+    assert.strictEqual(result.body.project.state.hook.managedVersion, 2);
+
+    const layout = new StorageLayout({ dataDir: DATA_DIR });
+    const recorder = new RequirementRecorder({
+      layout,
+      registryStore: new ProjectRegistryStore({ layout }),
+      projectStore: new ProjectStore({ layout }),
+    });
+    const requirement = await recorder.recordRequirement({
+      projectId: PROJECT_ID, repoPath: REPO, client: 'codex', sessionId: 'full-e2e-session',
+      text: 'Record the actual post-commit behavior and keep Markdown as the source of truth.',
+    });
+    assert(requirement.id && fs.existsSync(layout.getProjectConversationEventsPath(PROJECT_ID)));
+    assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath(PROJECT_ID)), false);
+
+    const onlineCommit = commit('online-change', 'online hook evidence');
+    let state = await waitForState(current => current.lastAnalyzedCommit === onlineCommit && current.index.dirty === false, 'online Hook reconciliation');
+    assert.strictEqual(state.analysis.activeClaim, null);
+    assert(fs.existsSync(path.join(knowledgePath, 'changes', `${onlineCommit.slice(0, 12)}.md`)));
+    result = await json('POST', '/api/knowledge/search', { projectId: PROJECT_ID, query: onlineCommit.slice(0, 12), limit: 5 });
+    assert(result.response.ok && result.body.results.length > 0, JSON.stringify(result.body));
+
+    result = await json('GET', `/api/logs?projectId=${PROJECT_ID}&pageSize=500`);
+    const onlineEvents = result.body.entries.map(entry => entry.event);
+    for (const event of ['reconcile.claim_prepared', 'knowledge.promotion_completed', 'reconcile.commit_completed', 'index.project_applied']) {
+      assert(onlineEvents.includes(event), `missing online operation event: ${event}`);
+    }
+    assert.strictEqual(result.body.entries.filter(entry => entry.event === 'reconcile.claim_prepared' && entry.commitSha === onlineCommit).length, 1, 'Hook/startup overlap must not duplicate one Commit');
+
+    await stop(server);
+    server = null;
+    const offlineOne = commit('offline-one', 'first offline change');
+    const offlineTwo = commit('offline-two', 'second offline change');
+    assert.notStrictEqual(offlineOne, offlineTwo);
+    server = await start();
+    await new Promise(resolve => setTimeout(resolve, 500));
+    result = await json('GET', `/api/projects/${PROJECT_ID}`);
+    state = result.body.project.state;
+    assert.strictEqual(state.lastAnalyzedCommit, onlineCommit, 'restart must not analyze offline commits');
+    assert.strictEqual(fs.existsSync(path.join(knowledgePath, 'changes', `${offlineOne.slice(0, 12)}.md`)), false);
+    assert.strictEqual(fs.existsSync(path.join(knowledgePath, 'changes', `${offlineTwo.slice(0, 12)}.md`)), false);
+    const onlineAfterRestart = commit('online-after-restart', 'explicit hook after offline commits');
+    state = await waitForState(current => current.lastAnalyzedCommit === onlineAfterRestart && current.index.dirty === false, 'explicit online Hook after restart');
+    assert.strictEqual(state.analysis.activeClaim, null);
+    assert(fs.existsSync(path.join(knowledgePath, 'changes', `${onlineAfterRestart.slice(0, 12)}.md`)));
+    result = await json('GET', `/api/logs?projectId=${PROJECT_ID}&pageSize=500`);
+    assert.strictEqual(result.body.entries.filter(entry => entry.event === 'reconcile.commit_completed' && entry.commitSha === offlineOne).length, 0);
+    assert.strictEqual(result.body.entries.filter(entry => entry.event === 'reconcile.commit_completed' && entry.commitSha === offlineTwo).length, 0);
+    assert.strictEqual(result.body.entries.filter(entry => entry.event === 'reconcile.commit_completed' && entry.commitSha === onlineAfterRestart).length, 1);
+    console.log('full-integration-e2e-test PASS');
+  } finally {
+    await stop(server);
+  }
+})().catch(error => { console.error(error.stack || error); process.exitCode = 1; });

package/_site/_test/git-validation-test.js

@@ -0,0 +1,81 @@
+// Git status remains a read-only v2 API; manual validation/state mutation is removed.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+const { makeRepo } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-data-git-validation-${process.pid}-`));
+const PORT = Number(process.env.KB_GIT_TEST_PORT || 7792);
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const PROJECT_ID = 'task-002-temp';
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE_URL}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+async function json(method, route, body) {
+  const response = await fetch(`${BASE_URL}${route}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  return { response, body: await response.json() };
+}
+
+(async () => {
+  const repo = makeRepo({ kind: 'one-commit' });
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir: DATA_DIR, tag: 'git-validation' });
+  let output = '';
+  spawned.child.stdout.on('data', chunk => { output += chunk; });
+  spawned.child.stderr.on('data', chunk => { output += chunk; });
+  try {
+    await waitForServer();
+    let result = await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(DATA_DIR, 'knowledge') } });
+    assert(result.response.ok, JSON.stringify(result.body));
+    result = await json('POST', '/api/projects/import', { projectId: PROJECT_ID, localPath: repo.path, displayName: 'Git status fixture' });
+    assert(result.response.status === 201, JSON.stringify(result.body));
+
+    const statePath = path.join(DATA_DIR, 'projects', PROJECT_ID, 'state.json');
+    const stateBefore = fs.readFileSync(statePath, 'utf8');
+    result = await json('GET', `/api/projects/${PROJECT_ID}/git-status`);
+    assert(result.response.ok, JSON.stringify(result.body));
+    assert.strictEqual(result.body.repoStatus, 'ok');
+    assert.strictEqual(result.body.branch, 'main');
+    assert.strictEqual(result.body.dirty, false);
+    assert.match(result.body.headCommit, /^[a-f0-9]{40}$/i);
+    assert.strictEqual(fs.readFileSync(statePath, 'utf8'), stateBefore, 'read-only status must not mutate project state');
+
+    fs.writeFileSync(path.join(repo.path, 'untracked.txt'), 'working tree change\n', 'utf8');
+    result = await json('GET', `/api/projects/${PROJECT_ID}/git-status`);
+    assert.strictEqual(result.body.dirty, true);
+    assert(result.body.changes.some(line => line.includes('untracked.txt')));
+
+    execFileSync('git', ['add', 'untracked.txt'], { cwd: repo.path });
+    execFileSync('git', ['commit', '-m', 'status fixture'], { cwd: repo.path });
+    result = await json('GET', `/api/projects/${PROJECT_ID}/git-status`);
+    assert.strictEqual(result.body.repoStatus, 'ok');
+    assert.strictEqual(result.body.dirty, false);
+
+    result = await json('POST', `/api/projects/${PROJECT_ID}/validate-git`, {});
+    assert.strictEqual(result.response.status, 404, 'manual validation route must remain deleted');
+    result = await json('GET', '/api/projects/%5Ebad/git-status');
+    assert.strictEqual(result.response.status, 400);
+    result = await json('GET', '/api/projects/project-missing/git-status');
+    assert.strictEqual(result.response.status, 404);
+    console.log('TASK-002 git validation test passed');
+  } catch (error) {
+    if (output) process.stderr.write(output);
+    throw error;
+  } finally {
+    spawned.child.kill();
+    repo.cleanup();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/hook-runtime-endpoint-test.js

@@ -0,0 +1,88 @@
+// Run: node _site/_test/hook-runtime-endpoint-test.js
+
+const fs = require('fs');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { writeEndpoint } = require('../lib/runtime-endpoint');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `kb-hook-runtime-${process.pid}-`));
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), `kb-hook-runtime-repo-${process.pid}-`));
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function git(args) {
+  return spawnSync('git', ['-C', repo, ...args], { encoding: 'utf-8', windowsHide: true });
+}
+
+(async () => {
+  git(['init']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# runtime endpoint\n', 'utf-8');
+  git(['config', 'user.email', 'runtime@example.test']);
+  git(['config', 'user.name', 'Runtime Test']);
+  git(['add', 'README.md']);
+  git(['commit', '-m', 'test']);
+
+  let received = null;
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.setEncoding('utf-8');
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      received = { method: req.method, url: req.url, body: JSON.parse(body) };
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end('{}');
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const port = server.address().port;
+  writeEndpoint(dataDir, { pid: process.pid, host: '127.0.0.1', port, mode: 'desktop' });
+  const bridgeJournal = path.join(dataDir, 'bridge-journal.jsonl');
+  const bridgeModule = path.join(dataDir, 'bridge-fixture.cjs');
+  fs.writeFileSync(bridgeModule, `const fs = require('fs');\nmodule.exports = {\n  appendCommitBoundary(input) {\n    fs.appendFileSync(process.env.BRIDGE_TEST_JOURNAL, JSON.stringify(input) + '\\n');\n    return { sequence: 17, bridgeCursorAtCommit: 17, openTurnIdsAtCommit: ['turn-runtime'] };\n  }\n};\n`);
+
+  const child = spawn(process.execPath, [
+    TRIGGER,
+    '--project-id', 'project-runtime',
+    '--repo-root', repo,
+    '--host', '127.0.0.1',
+    '--port', '1',
+  ], {
+    cwd: ROOT,
+    windowsHide: true,
+    stdio: 'pipe',
+    env: { ...process.env, KB_DATA_DIR: dataDir, AI_CODING_EVENT_BRIDGE_MODULE: bridgeModule, BRIDGE_TEST_JOURNAL: bridgeJournal },
+  });
+  const exitCode = await new Promise(resolve => child.once('exit', resolve));
+  assert(exitCode === 0, `hook trigger should exit 0, got ${exitCode}`);
+  assert(received, 'hook trigger should use the live runtime endpoint instead of fallback port 1');
+  assert(received.method === 'POST' && received.url === '/api/hooks/post-commit', 'unexpected hook request');
+  assert(received.body.schema === 'hook-event/v2', 'hook request should use the v2 event schema');
+  assert(received.body.projectId === 'project-runtime', 'hook request should contain the stable project id');
+  assert(path.resolve(received.body.repoRoot) === path.resolve(repo), 'hook request should contain the runtime repo root');
+  assert(received.body.head, 'hook request should contain the current head');
+  assert(received.body.branch, 'hook request should contain the current branch');
+  assert(received.body.operationId && received.body.operationId.startsWith('op-'), 'Hook boundary operation id should propagate to notification');
+  assert(received.body.boundary && received.body.boundary.status === 'captured', 'Hook must append the Bridge boundary before notifying the server');
+  assert(received.body.boundary.boundary.bridgeCursorAtCommit === 17, 'Hook must forward the atomic Bridge cursor receipt');
+  const durableBoundary = JSON.parse(fs.readFileSync(bridgeJournal, 'utf8').trim());
+  assert(durableBoundary.commitSha === received.body.head, 'durable Bridge boundary and Hook payload must reference the same commit');
+
+  await new Promise(resolve => server.close(resolve));
+  fs.rmSync(dataDir, { recursive: true, force: true });
+  fs.rmSync(repo, { recursive: true, force: true });
+  console.log('hook-runtime-endpoint-test PASS');
+})().catch(error => {
+  console.error(error && error.stack || error);
+  fs.rmSync(dataDir, { recursive: true, force: true });
+  fs.rmSync(repo, { recursive: true, force: true });
+  process.exit(1);
+});

package/_site/_test/hook-status-repair-api-test.js

@@ -0,0 +1,152 @@
+// _site/_test/hook-status-repair-api-test.js
+//
+// Integration tests for T04 — Hook status / verify / repair service API.
+// Drives the live server through:
+//   GET  /api/projects/:id/hook-status
+//   POST /api/projects/:id/hook-repair
+//
+// and verifies that:
+//   - the status payload carries all required fields;
+//   - repair works for missing / broken managed hooks;
+//   - repair refuses to overwrite third-party hooks;
+//   - lastConflict is surfaced from state.hook.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7901;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `pk-hook-api-${process.pid}-`));
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), `pk-hook-api-repo-${process.pid}-`));
+
+function git(args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+function makeRepo() {
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'hook-api@example.local']);
+  git(['config', 'user.name', 'Hook API Test']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# hook api\n');
+  git(['add', 'README.md']);
+  git(['commit', '-q', '-m', 'initial']);
+}
+
+function requestJson(method, pathname, body) {
+  return fetch(`${BASE}${pathname}`, {
+    method,
+    headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  }).then(async response => ({ status: response.status, body: await response.json() }));
+}
+function postJson(pathname, body) { return requestJson('POST', pathname, body); }
+function patchJson(pathname, body) { return requestJson('PATCH', pathname, body); }
+function putJson(pathname, body) { return requestJson('PUT', pathname, body); }
+function getJson(pathname) { return requestJson('GET', pathname); }
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+(async () => {
+  makeRepo();
+  const spawned = spawnServer({
+    root: ROOT, port: PORT, dataDir, tag: 'hook-api',
+    extraEnv: { KB_SKIP_MIGRATION: '1' },
+  });
+  try {
+    await waitForServer();
+    // Configure knowledge root + a fake AI profile so import succeeds.
+    let r = await patchJson('/api/settings', { knowledge: { rootPath: path.join(dataDir, 'knowledge') } });
+    assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+    r = await putJson('/api/ai-profiles', {
+      schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+      profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+    });
+    assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+    const PROJECT_ID = 'project-hook-api';
+    r = await postJson('/api/projects/import', {
+      projectId: PROJECT_ID, localPath: repo, displayName: 'Hook API', aiProfileId: 'fake',
+    });
+    assert.strictEqual(r.status, 201, JSON.stringify(r.body));
+
+    // Case 1: status payload after fresh import carries all required fields.
+    r = await getJson(`/api/projects/${PROJECT_ID}/hook-status`);
+    assert.strictEqual(r.status, 200);
+    assert.strictEqual(r.body.ok, true);
+    assert.strictEqual(r.body.projectId, PROJECT_ID);
+    assert.strictEqual(typeof r.body.hook.repoPath, 'string');
+    assert.strictEqual(typeof r.body.hook.hookPath, 'string');
+    assert.strictEqual(r.body.hook.installed, true);
+    assert.strictEqual(r.body.hook.managed, true);
+    assert.strictEqual(r.body.hook.managedVersion, 2);
+    assert.strictEqual(typeof r.body.hook.runtimeTarget, 'string');
+    assert(typeof r.body.hook.lastVerifiedAt === 'string' && r.body.hook.lastVerifiedAt.length > 0);
+    assert.strictEqual(r.body.hook.migrationVersion, 2);
+    assert.strictEqual(r.body.hook.repairAvailable, false, 'freshly-imported managed hook needs no repair');
+
+    // Case 2: missing managed hook is reported + repairable.
+    const hookPath = r.body.hook.hookPath;
+    fs.unlinkSync(hookPath);
+    r = await getJson(`/api/projects/${PROJECT_ID}/hook-status`);
+    assert.strictEqual(r.body.hook.installed, false);
+    assert.strictEqual(r.body.hook.managed, false);
+    assert.strictEqual(r.body.hook.repairAvailable, true, 'missing managed hook must be repairable');
+    r = await postJson(`/api/projects/${PROJECT_ID}/hook-repair`, {});
+    assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+    assert.strictEqual(r.body.installed, true);
+    assert.strictEqual(r.body.managedVersion, 2);
+    r = await getJson(`/api/projects/${PROJECT_ID}/hook-status`);
+    assert.strictEqual(r.body.hook.installed, true, 'repair must re-install the managed hook');
+    assert.strictEqual(r.body.hook.managed, true);
+    assert.strictEqual(r.body.hook.repairAvailable, false);
+
+    // Case 3: third-party hook is reported as conflict + repair refuses.
+    const userHook = '#!/bin/sh\necho "user owned"\nexit 0\n';
+    fs.writeFileSync(hookPath, userHook, { mode: 0o755 });
+    r = await getJson(`/api/projects/${PROJECT_ID}/hook-status`);
+    assert.strictEqual(r.body.hook.installed, false, 'third-party hook must not be reported as installed');
+    assert.strictEqual(r.body.hook.managed, false, 'third-party hook must not be reported as managed');
+    assert.strictEqual(r.body.hook.repairAvailable, false, 'third-party hook must not be repairable');
+    assert(r.body.hook.reason && /third-party/i.test(r.body.hook.reason));
+    r = await postJson(`/api/projects/${PROJECT_ID}/hook-repair`, {});
+    assert.strictEqual(r.status, 409, `third-party repair must be rejected with 409; got ${r.status}`);
+    assert.strictEqual(r.body.error.code, 'HOOK_CONFLICT');
+    assert.strictEqual(fs.readFileSync(hookPath, 'utf8'), userHook, 'third-party hook body must remain untouched');
+
+    // Case 4: managed hook belonging to a different project is reported as conflict.
+    fs.writeFileSync(hookPath, '#!/bin/sh\n# PROJECT-KNOWLEDGE-HOOK ' + JSON.stringify({
+      schema: 'project-knowledge/hook/v2', managedVersion: 2, projectId: 'project-someone-else',
+    }) + '\nexit 0\n', { mode: 0o755 });
+    r = await getJson(`/api/projects/${PROJECT_ID}/hook-status`);
+    assert.strictEqual(r.body.hook.managed, true, 'managed hook body must be recognized as managed');
+    assert.strictEqual(r.body.hook.installed, false, 'wrong-project managed hook must not be installed for this project');
+    assert.strictEqual(r.body.hook.repairAvailable, false, 'wrong-project managed hook must not be auto-repaired');
+    r = await postJson(`/api/projects/${PROJECT_ID}/hook-repair`, {});
+    assert.strictEqual(r.status, 409, 'wrong-project repair must be rejected with 409');
+  } finally {
+    spawned.child.kill();
+    await new Promise(resolve => spawned.child.once('exit', resolve));
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+  console.log('hook-status-repair-api-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});