@sanqianx/project-knowledge 4.6.1 → 4.8.0

package/_site/_test/storage-foundation-test.js

@@ -1,78 +1,78 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const AtomicFile = require('../lib/atomic-file');
-const { SettingsStore } = require('../lib/settings-store');
-
-(async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-storage-foundation-'));
-  const dataDir = path.join(root, 'data');
-  const knowledgeRoot = path.join(root, 'knowledge');
-  const layout = new StorageLayout({ dataDir, platform: 'win32' });
-
-  assert.strictEqual(layout.pathsEqual('C:\\Work\\Repo', 'c:\\work\\repo\\'), true);
-  const posixLayout = new StorageLayout({ dataDir, platform: 'linux' });
-  assert.strictEqual(posixLayout.pathsEqual('/tmp/Repo', '/tmp/repo'), false);
-  assert.strictEqual(layout.getIndexPath(), path.join(dataDir, 'index', 'knowledge.lancedb'));
-  assert(!layout.getIndexPath().startsWith(knowledgeRoot));
-
-  const rootResult = layout.validateKnowledgeRoot(knowledgeRoot);
-  assert.strictEqual(rootResult.ok, true);
-  assert.strictEqual(fs.readdirSync(knowledgeRoot).length, 0, 'write probe must not leave files');
-  const projectKnowledge = layout.resolveNewProjectKnowledgePath('repo-a1b2c3', { knowledge: { rootPath: knowledgeRoot } });
-  assert.strictEqual(projectKnowledge, path.join(knowledgeRoot, 'repo-a1b2c3'));
-  assert.strictEqual(layout.getProjectKnowledgePath({ knowledgePath: projectKnowledge }), projectKnowledge);
-
-  const atomicPath = path.join(dataDir, 'atomic.json');
-  AtomicFile.writeJsonAtomic(atomicPath, { revision: 1 });
-  assert.throws(() => AtomicFile.writeJsonAtomic(atomicPath, { revision: 2 }, {
-    beforeRename() { throw new Error('injected-before-rename'); },
-  }), /injected-before-rename/);
-  assert.deepStrictEqual(JSON.parse(fs.readFileSync(atomicPath, 'utf8')), { revision: 1 });
-
-  const jsonlPath = path.join(dataDir, 'append', 'requirements.jsonl');
-  await Promise.all(Array.from({ length: 20 }, (_, index) => AtomicFile.appendJsonlLocked(jsonlPath, { index })));
-  const lines = fs.readFileSync(jsonlPath, 'utf8').trim().split(/\r?\n/).map(JSON.parse);
-  assert.strictEqual(lines.length, 20);
-  assert.deepStrictEqual(lines.map(line => line.index).sort((a, b) => a - b), Array.from({ length: 20 }, (_, index) => index));
-
-  fs.mkdirSync(dataDir, { recursive: true });
-  const staleTemp = path.join(dataDir, '.atomic.json.1.1.abcdef.tmp');
-  const unrelated = path.join(dataDir, 'user.tmp');
-  fs.writeFileSync(staleTemp, 'stale');
-  fs.writeFileSync(unrelated, 'keep');
-  const old = new Date(Date.now() - 48 * 60 * 60 * 1000);
-  fs.utimesSync(staleTemp, old, old);
-  const removed = AtomicFile.cleanupStaleTemps(dataDir);
-  assert.deepStrictEqual(removed, [staleTemp]);
-  assert(fs.existsSync(unrelated));
-
-  const store = new SettingsStore({ layout });
-  await store.initialize({
-    knowledge: { rootPath: knowledgeRoot },
-    ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'secret-key-7890' }] },
-  });
-  const privateSettings = store.read();
-  assert.strictEqual(privateSettings.ai.profiles[0].apiKey, 'secret-key-7890');
-  const publicSettings = store.readPublicView();
-  assert.strictEqual(publicSettings.ai.profiles[0].hasApiKey, true);
-  assert.strictEqual(publicSettings.ai.profiles[0].apiKeyMasked, '****7890');
-  assert.strictEqual(Object.prototype.hasOwnProperty.call(publicSettings.ai.profiles[0], 'apiKey'), false);
-
-  await assert.rejects(
-    () => store.updatePatch({ logging: { retentionDays: 0, maxTotalSizeMB: 512 } }),
-    error => error.code === 'INVALID_ARGUMENT',
-    'runtime retention/capacity settings must not be writable',
-  );
-  const updated = store.readPublicView();
-  assert.deepStrictEqual(updated.logging.levels, ['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
-  assert.strictEqual(fs.existsSync(layout.getRecoveryPath()), false, 'optional recovery directory must stay lazy');
-  assert.strictEqual(fs.existsSync(layout.getCachePath()), false, 'optional cache directory must stay lazy');
-
-  console.log('storage-foundation-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const AtomicFile = require('../lib/atomic-file');
+const { SettingsStore } = require('../lib/settings-store');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-storage-foundation-'));
+  const dataDir = path.join(root, 'data');
+  const knowledgeRoot = path.join(root, 'knowledge');
+  const layout = new StorageLayout({ dataDir, platform: 'win32' });
+
+  assert.strictEqual(layout.pathsEqual('C:\\Work\\Repo', 'c:\\work\\repo\\'), true);
+  const posixLayout = new StorageLayout({ dataDir, platform: 'linux' });
+  assert.strictEqual(posixLayout.pathsEqual('/tmp/Repo', '/tmp/repo'), false);
+  assert.strictEqual(layout.getIndexPath(), path.join(dataDir, 'index', 'knowledge.lancedb'));
+  assert(!layout.getIndexPath().startsWith(knowledgeRoot));
+
+  const rootResult = layout.validateKnowledgeRoot(knowledgeRoot);
+  assert.strictEqual(rootResult.ok, true);
+  assert.strictEqual(fs.readdirSync(knowledgeRoot).length, 0, 'write probe must not leave files');
+  const projectKnowledge = layout.resolveNewProjectKnowledgePath('repo-a1b2c3', { knowledge: { rootPath: knowledgeRoot } });
+  assert.strictEqual(projectKnowledge, path.join(knowledgeRoot, 'repo-a1b2c3'));
+  assert.strictEqual(layout.getProjectKnowledgePath({ knowledgePath: projectKnowledge }), projectKnowledge);
+
+  const atomicPath = path.join(dataDir, 'atomic.json');
+  AtomicFile.writeJsonAtomic(atomicPath, { revision: 1 });
+  assert.throws(() => AtomicFile.writeJsonAtomic(atomicPath, { revision: 2 }, {
+    beforeRename() { throw new Error('injected-before-rename'); },
+  }), /injected-before-rename/);
+  assert.deepStrictEqual(JSON.parse(fs.readFileSync(atomicPath, 'utf8')), { revision: 1 });
+
+  const jsonlPath = path.join(dataDir, 'append', 'requirements.jsonl');
+  await Promise.all(Array.from({ length: 20 }, (_, index) => AtomicFile.appendJsonlLocked(jsonlPath, { index })));
+  const lines = fs.readFileSync(jsonlPath, 'utf8').trim().split(/\r?\n/).map(JSON.parse);
+  assert.strictEqual(lines.length, 20);
+  assert.deepStrictEqual(lines.map(line => line.index).sort((a, b) => a - b), Array.from({ length: 20 }, (_, index) => index));
+
+  fs.mkdirSync(dataDir, { recursive: true });
+  const staleTemp = path.join(dataDir, '.atomic.json.1.1.abcdef.tmp');
+  const unrelated = path.join(dataDir, 'user.tmp');
+  fs.writeFileSync(staleTemp, 'stale');
+  fs.writeFileSync(unrelated, 'keep');
+  const old = new Date(Date.now() - 48 * 60 * 60 * 1000);
+  fs.utimesSync(staleTemp, old, old);
+  const removed = AtomicFile.cleanupStaleTemps(dataDir);
+  assert.deepStrictEqual(removed, [staleTemp]);
+  assert(fs.existsSync(unrelated));
+
+  const store = new SettingsStore({ layout });
+  await store.initialize({
+    knowledge: { rootPath: knowledgeRoot },
+    ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'secret-key-7890' }] },
+  });
+  const privateSettings = store.read();
+  assert.strictEqual(privateSettings.ai.profiles[0].apiKey, 'secret-key-7890');
+  const publicSettings = store.readPublicView();
+  assert.strictEqual(publicSettings.ai.profiles[0].hasApiKey, true);
+  assert.strictEqual(publicSettings.ai.profiles[0].apiKeyMasked, '****7890');
+  assert.strictEqual(Object.prototype.hasOwnProperty.call(publicSettings.ai.profiles[0], 'apiKey'), false);
+
+  await assert.rejects(
+    () => store.updatePatch({ logging: { retentionDays: 0, maxTotalSizeMB: 512 } }),
+    error => error.code === 'INVALID_ARGUMENT',
+    'runtime retention/capacity settings must not be writable',
+  );
+  const updated = store.readPublicView();
+  assert.deepStrictEqual(updated.logging.levels, ['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+  assert.strictEqual(fs.existsSync(layout.getRecoveryPath()), false, 'optional recovery directory must stay lazy');
+  assert.strictEqual(fs.existsSync(layout.getCachePath()), false, 'optional cache directory must stay lazy');
+
+  console.log('storage-foundation-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/structured-logger-test.js

@@ -1,101 +1,101 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { Logger, LogRepository, localDay } = require('../lib/structured-logger');
-
-(async () => {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-logger-v3-'));
-  const layout = new StorageLayout({ dataDir });
-  const config = { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] };
-  let stderr = '';
-  const logger = new Logger({
-    layout,
-    settingsProvider: () => config,
-    secrets: ['known-secret-value'],
-    stderr: { write(value) { stderr += String(value); } },
-  });
-  const published = [];
-  logger.subscribe(record => published.push(record));
-  logger.subscribe(() => { throw new Error('subscriber failure must be isolated'); });
-  const child = logger.child({ component: 'commit-reconciler', projectId: 'project-a', operationId: 'op-1', runId: 'run-1', commitSha: 'abc' });
-  const cause = new Error('cause known-secret-value');
-  cause.code = 'ECAUSE';
-  const failure = new Error('Bearer top-secret-token');
-  failure.code = 'ETEST';
-  failure.cause = cause;
-  for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
-    await child[level](`test.${level}`, `${level} message`, {
-      phase: 'test',
-      error: level === 'error' ? failure : null,
-      context: { apiKey: 'known-secret-value', nested: { authorization: 'Bearer nested-token', safe: 'kept' } },
-    });
-  }
-  await logger.close();
-
-  const projectDirectory = layout.getLogPath('project', 'project-a');
-  const files = fs.readdirSync(projectDirectory).filter(file => file.endsWith('.jsonl'));
-  assert.deepStrictEqual(files, [`${localDay()}.jsonl`], 'one project/day must use exactly one file');
-  assert(!files.some(file => /\.\d{3}\.jsonl$/.test(file)), 'v13 writer must never create size segments');
-  const allText = fs.readFileSync(path.join(projectDirectory, files[0]), 'utf8');
-  assert(!allText.includes('known-secret-value'));
-  assert(!allText.includes('top-secret-token'));
-  assert(!allText.includes('nested-token'));
-  assert(allText.includes('[REDACTED]'));
-  assert.strictEqual(published.length, 6, 'each durable append must publish exactly once');
-  assert.deepStrictEqual(published.map(record => record.level), ['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
-  for (const line of allText.trim().split(/\r?\n/)) {
-    const record = JSON.parse(line);
-    assert.strictEqual(record.schema, 'log/v2');
-    assert.strictEqual(record.projectId, 'project-a');
-    assert.strictEqual(record.operationId, 'op-1');
-    assert(record.id && record.ts && record.event);
-  }
-
-  await logger.info('system.completed', 'System record', { component: 'server', operationId: 'op-system' });
-  await logger.close();
-  assert(fs.existsSync(path.join(layout.getLogPath('system'), `${localDay()}.jsonl`)), 'unscoped logs belong to system/day');
-
-  const repository = new LogRepository({ layout, secrets: ['known-secret-value'] });
-  const first = repository.query({ pageSize: 2, projectId: 'project-a' });
-  assert.strictEqual(first.entries.length, 2);
-  assert(first.nextCursor);
-  const second = repository.query({ pageSize: 2, projectId: 'project-a', cursor: first.nextCursor });
-  assert.strictEqual(second.entries.length, 2);
-  assert.notStrictEqual(first.entries[0].id, second.entries[0].id);
-  assert.throws(
-    () => repository.query({ pageSize: 3, projectId: 'project-a', cursor: first.nextCursor }),
-    error => error.code === 'LOG_CURSOR_EXPIRED',
-  );
-
-  const exportPath = path.join(dataDir, 'exports', 'diagnostics.jsonl');
-  const exported = repository.exportToFile(exportPath, { projectId: 'project-a' });
-  assert.strictEqual(exported.count, 6);
-  assert(!fs.readFileSync(exportPath, 'utf8').includes('known-secret-value'));
-  assert.strictEqual(stderr, '');
-  assert.strictEqual(typeof repository.cleanup, 'undefined', 'production log cleanup API must not exist');
-
-  const blocker = path.join(dataDir, 'not-a-directory');
-  fs.writeFileSync(blocker, 'blocker');
-  const failingLayout = {
-    getDataDir() { return dataDir; },
-    getLogPath() { return path.join(blocker, 'logs'); },
-  };
-  const failing = new Logger({
-    layout: failingLayout,
-    settingsProvider: () => config,
-    secrets: ['known-secret-value'],
-    stderr: { write(value) { stderr += String(value); } },
-  });
-  const failingChild = failing.child({ component: 'failure-test' });
-  await failingChild.error('logger.failure.test', 'known-secret-value', { error: new Error('known-secret-value') });
-  assert.strictEqual(failing.getHealth().status, 'degraded', 'parent and child must share logger health');
-  assert.strictEqual(failingChild.getHealth().status, 'degraded');
-  assert(stderr.includes('logger fallback'));
-  assert(!stderr.includes('known-secret-value'));
-  console.log('structured-logger-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { Logger, LogRepository, localDay } = require('../lib/structured-logger');
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-logger-v3-'));
+  const layout = new StorageLayout({ dataDir });
+  const config = { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] };
+  let stderr = '';
+  const logger = new Logger({
+    layout,
+    settingsProvider: () => config,
+    secrets: ['known-secret-value'],
+    stderr: { write(value) { stderr += String(value); } },
+  });
+  const published = [];
+  logger.subscribe(record => published.push(record));
+  logger.subscribe(() => { throw new Error('subscriber failure must be isolated'); });
+  const child = logger.child({ component: 'commit-reconciler', projectId: 'project-a', operationId: 'op-1', runId: 'run-1', commitSha: 'abc' });
+  const cause = new Error('cause known-secret-value');
+  cause.code = 'ECAUSE';
+  const failure = new Error('Bearer top-secret-token');
+  failure.code = 'ETEST';
+  failure.cause = cause;
+  for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
+    await child[level](`test.${level}`, `${level} message`, {
+      phase: 'test',
+      error: level === 'error' ? failure : null,
+      context: { apiKey: 'known-secret-value', nested: { authorization: 'Bearer nested-token', safe: 'kept' } },
+    });
+  }
+  await logger.close();
+
+  const projectDirectory = layout.getLogPath('project', 'project-a');
+  const files = fs.readdirSync(projectDirectory).filter(file => file.endsWith('.jsonl'));
+  assert.deepStrictEqual(files, [`${localDay()}.jsonl`], 'one project/day must use exactly one file');
+  assert(!files.some(file => /\.\d{3}\.jsonl$/.test(file)), 'v13 writer must never create size segments');
+  const allText = fs.readFileSync(path.join(projectDirectory, files[0]), 'utf8');
+  assert(!allText.includes('known-secret-value'));
+  assert(!allText.includes('top-secret-token'));
+  assert(!allText.includes('nested-token'));
+  assert(allText.includes('[REDACTED]'));
+  assert.strictEqual(published.length, 6, 'each durable append must publish exactly once');
+  assert.deepStrictEqual(published.map(record => record.level), ['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+  for (const line of allText.trim().split(/\r?\n/)) {
+    const record = JSON.parse(line);
+    assert.strictEqual(record.schema, 'log/v2');
+    assert.strictEqual(record.projectId, 'project-a');
+    assert.strictEqual(record.operationId, 'op-1');
+    assert(record.id && record.ts && record.event);
+  }
+
+  await logger.info('system.completed', 'System record', { component: 'server', operationId: 'op-system' });
+  await logger.close();
+  assert(fs.existsSync(path.join(layout.getLogPath('system'), `${localDay()}.jsonl`)), 'unscoped logs belong to system/day');
+
+  const repository = new LogRepository({ layout, secrets: ['known-secret-value'] });
+  const first = repository.query({ pageSize: 2, projectId: 'project-a' });
+  assert.strictEqual(first.entries.length, 2);
+  assert(first.nextCursor);
+  const second = repository.query({ pageSize: 2, projectId: 'project-a', cursor: first.nextCursor });
+  assert.strictEqual(second.entries.length, 2);
+  assert.notStrictEqual(first.entries[0].id, second.entries[0].id);
+  assert.throws(
+    () => repository.query({ pageSize: 3, projectId: 'project-a', cursor: first.nextCursor }),
+    error => error.code === 'LOG_CURSOR_EXPIRED',
+  );
+
+  const exportPath = path.join(dataDir, 'exports', 'diagnostics.jsonl');
+  const exported = repository.exportToFile(exportPath, { projectId: 'project-a' });
+  assert.strictEqual(exported.count, 6);
+  assert(!fs.readFileSync(exportPath, 'utf8').includes('known-secret-value'));
+  assert.strictEqual(stderr, '');
+  assert.strictEqual(typeof repository.cleanup, 'undefined', 'production log cleanup API must not exist');
+
+  const blocker = path.join(dataDir, 'not-a-directory');
+  fs.writeFileSync(blocker, 'blocker');
+  const failingLayout = {
+    getDataDir() { return dataDir; },
+    getLogPath() { return path.join(blocker, 'logs'); },
+  };
+  const failing = new Logger({
+    layout: failingLayout,
+    settingsProvider: () => config,
+    secrets: ['known-secret-value'],
+    stderr: { write(value) { stderr += String(value); } },
+  });
+  const failingChild = failing.child({ component: 'failure-test' });
+  await failingChild.error('logger.failure.test', 'known-secret-value', { error: new Error('known-secret-value') });
+  assert.strictEqual(failing.getHealth().status, 'degraded', 'parent and child must share logger health');
+  assert.strictEqual(failingChild.getHealth().status, 'degraded');
+  assert(stderr.includes('logger fallback'));
+  assert(!stderr.includes('known-secret-value'));
+  console.log('structured-logger-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/tracking-start-test.js

@@ -1,97 +1,97 @@
-// Run: node _site/_test/tracking-start-test.js
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
-const { CommitReconciler } = require('../lib/commit-reconciler');
-
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-tracking-start-${process.pid}-`));
-const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
-const registry = new ProjectRegistryStore({ layout });
-const projects = new ProjectStore({ layout });
-const knowledgeRoot = path.join(temp, 'knowledge');
-
-function git(repo, args) {
-  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
-  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
-  return String(result.stdout || '').trim();
-}
-
-function repo(name, withCommit) {
-  const target = path.join(temp, name);
-  fs.mkdirSync(target, { recursive: true });
-  git(target, ['init', '--initial-branch=main']);
-  git(target, ['config', 'user.email', 'tracking@example.test']);
-  git(target, ['config', 'user.name', 'Tracking Test']);
-  if (withCommit) commit(target, 'imported');
-  return target;
-}
-
-function commit(target, name) {
-  fs.writeFileSync(path.join(target, `${name}.txt`), `${name}\n`, 'utf8');
-  git(target, ['add', `${name}.txt`]);
-  git(target, ['commit', '-m', name]);
-  return git(target, ['rev-parse', 'HEAD']);
-}
-
-(async () => {
-  fs.mkdirSync(knowledgeRoot, { recursive: true });
-  await registry.initialize();
-  const installed = [];
-  const lifecycle = new ProjectLifecycleService({
-    layout,
-    registryStore: registry,
-    projectStore: projects,
-    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
-    triggerScriptPath: path.join(temp, 'hook-trigger.js'),
-    hookManager: {
-      installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
-      uninstallHook: () => ({ ok: true }),
-    },
-  });
-
-  const existingRepo = repo('existing-repo', true);
-  const importedHead = git(existingRepo, ['rev-parse', 'HEAD']);
-  const imported = await lifecycle.importProject({ localPath: existingRepo, projectId: 'project-existing', aiProfileId: 'test-profile' });
-  assert.strictEqual(imported.state.trackingStartCommit, importedHead);
-  assert.strictEqual(imported.state.lastAnalyzedCommit, null);
-  assert.strictEqual(imported.state.trackingMode, 'normal');
-  assert.strictEqual(installed.length, 1, 'import should install Hook but not analyze');
-
-  let processorCalls = 0;
-  const processor = {
-    processClaim: async input => {
-      processorCalls += 1;
-      await projects.updateState(input.projectId, state => {
-        state.lastAnalyzedCommit = input.claim.commitSha;
-        state.analysis.activeClaim = null;
-        state.analysis.status = 'state.advanced';
-        state.index.dirty = true;
-        state.index.generation += 1;
-      });
-      return { stateAdvanced: true };
-    },
-  };
-  const reconciler = new CommitReconciler({
-    layout,
-    registryStore: registry,
-    projectStore: projects,
-    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
-    claimProcessor: processor,
-  });
-  await assert.rejects(reconciler.reconcile('project-existing', 'startup'), error => error.code === 'INVALID_TRIGGER');
-  assert.strictEqual(processorCalls, 0, 'startup after import must not analyze pre-import history');
-  const nextCommit = commit(existingRepo, 'after-import');
-  const laterCommit = commit(existingRepo, 'after-import-later');
-  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: nextCommit, branch: 'main' });
-  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, nextCommit);
-  assert.strictEqual(processorCalls, 1);
+// Run: node _site/_test/tracking-start-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+const { CommitReconciler } = require('../lib/commit-reconciler');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-tracking-start-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const knowledgeRoot = path.join(temp, 'knowledge');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function repo(name, withCommit) {
+  const target = path.join(temp, name);
+  fs.mkdirSync(target, { recursive: true });
+  git(target, ['init', '--initial-branch=main']);
+  git(target, ['config', 'user.email', 'tracking@example.test']);
+  git(target, ['config', 'user.name', 'Tracking Test']);
+  if (withCommit) commit(target, 'imported');
+  return target;
+}
+
+function commit(target, name) {
+  fs.writeFileSync(path.join(target, `${name}.txt`), `${name}\n`, 'utf8');
+  git(target, ['add', `${name}.txt`]);
+  git(target, ['commit', '-m', name]);
+  return git(target, ['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  await registry.initialize();
+  const installed = [];
+  const lifecycle = new ProjectLifecycleService({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    triggerScriptPath: path.join(temp, 'hook-trigger.js'),
+    hookManager: {
+      installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
+      uninstallHook: () => ({ ok: true }),
+    },
+  });
+
+  const existingRepo = repo('existing-repo', true);
+  const importedHead = git(existingRepo, ['rev-parse', 'HEAD']);
+  const imported = await lifecycle.importProject({ localPath: existingRepo, projectId: 'project-existing', aiProfileId: 'test-profile' });
+  assert.strictEqual(imported.state.trackingStartCommit, importedHead);
+  assert.strictEqual(imported.state.lastAnalyzedCommit, null);
+  assert.strictEqual(imported.state.trackingMode, 'normal');
+  assert.strictEqual(installed.length, 1, 'import should install Hook but not analyze');
+
+  let processorCalls = 0;
+  const processor = {
+    processClaim: async input => {
+      processorCalls += 1;
+      await projects.updateState(input.projectId, state => {
+        state.lastAnalyzedCommit = input.claim.commitSha;
+        state.analysis.activeClaim = null;
+        state.analysis.status = 'state.advanced';
+        state.index.dirty = true;
+        state.index.generation += 1;
+      });
+      return { stateAdvanced: true };
+    },
+  };
+  const reconciler = new CommitReconciler({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    claimProcessor: processor,
+  });
+  await assert.rejects(reconciler.reconcile('project-existing', 'startup'), error => error.code === 'INVALID_TRIGGER');
+  assert.strictEqual(processorCalls, 0, 'startup after import must not analyze pre-import history');
+  const nextCommit = commit(existingRepo, 'after-import');
+  const laterCommit = commit(existingRepo, 'after-import-later');
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: nextCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, nextCommit);
+  assert.strictEqual(processorCalls, 1);
   await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: laterCommit, branch: 'main' });
   assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, laterCommit, 'an event SHA remains valid even after HEAD advances');
   assert.strictEqual(processorCalls, 2);
@@ -124,20 +124,20 @@ function commit(target, name) {
   assert.strictEqual(blockedResult.status, 'failed');
   assert.strictEqual(processorCalls, 3, 'retryable claims must remain blocked instead of being silently superseded');
   assert.strictEqual(projects.readState('project-existing').analysis.activeClaim.commitSha, retryableFailedCommit);
-
-  const emptyRepo = repo('empty-repo', false);
-  const emptyImported = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', aiProfileId: 'test-profile' });
-  assert.strictEqual(emptyImported.state.trackingMode, 'empty-repo');
-  assert.strictEqual(emptyImported.state.trackingStartCommit, null);
-  const firstCommit = commit(emptyRepo, 'first');
+
+  const emptyRepo = repo('empty-repo', false);
+  const emptyImported = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', aiProfileId: 'test-profile' });
+  assert.strictEqual(emptyImported.state.trackingMode, 'empty-repo');
+  assert.strictEqual(emptyImported.state.trackingStartCommit, null);
+  const firstCommit = commit(emptyRepo, 'first');
   await reconciler.processCommitEvent({ projectId: 'project-empty', commitSha: firstCommit, branch: 'main' });
   assert.strictEqual(projects.readState('project-empty').lastAnalyzedCommit, firstCommit, 'first commit after empty import must be analyzed');
   assert.strictEqual(processorCalls, 4);
-
-  console.log('tracking-start-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-}).finally(() => {
-  fs.rmSync(temp, { recursive: true, force: true });
-});
+
+  console.log('tracking-start-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});