@sanqianx/project-knowledge 4.6.1

package/_site/_test/scanner-test.js

@@ -0,0 +1,83 @@
+// Run: node _site/_test/scanner-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { CommitScanner, scanProject } = require('../lib/scanner');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-scanner-${process.pid}-`));
+
+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 initRepo(name) {
+  const repo = path.join(temp, name);
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, ['init', '--initial-branch=main']);
+  git(repo, ['config', 'user.email', 'scanner@example.test']);
+  git(repo, ['config', 'user.name', 'Scanner Test']);
+  return repo;
+}
+
+function commit(repo, index) {
+  fs.writeFileSync(path.join(repo, `${index}.txt`), `${index}\n`, 'utf8');
+  git(repo, ['add', `${index}.txt`]);
+  git(repo, ['commit', '-m', `commit ${index}`]);
+  return git(repo, ['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  const scanner = new CommitScanner({ batchSize: 2 });
+  const emptyRepo = initRepo('empty');
+  const empty = await scanner.scan({ repoPath: emptyRepo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.strictEqual(empty.status, 'empty-repo');
+  assert.deepStrictEqual(empty.commits, []);
+
+  const repo = initRepo('multi');
+  const importedHead = commit(repo, 1);
+  const initial = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.strictEqual(initial.status, 'establish-tracking');
+  assert.strictEqual(initial.head, importedHead);
+  assert.strictEqual(initial.commits.length, 0, 'pre-import history must not be analyzed');
+
+  const second = commit(repo, 2);
+  const third = commit(repo, 3);
+  const fourth = commit(repo, 4);
+  const pending = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
+  assert.deepStrictEqual(pending.commits, [second, third]);
+  assert.strictEqual(pending.pendingCount, 3);
+  assert.deepStrictEqual(pending.continuation, { remaining: 1, after: third });
+
+  const next = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: third });
+  assert.deepStrictEqual(next.commits, [fourth], 'lastAnalyzedCommit must take priority over trackingStartCommit');
+  assert.strictEqual(next.continuation, null);
+
+  const firstAfterEmpty = await scanner.scan({ repoPath: repo }, { trackingMode: 'empty-repo', trackingStartCommit: null, lastAnalyzedCommit: null });
+  assert.deepStrictEqual(firstAfterEmpty.commits, [importedHead, second], 'empty-repo mode should start with the root commit and expose continuation');
+
+  const legacyView = await scanProject({ slug: 'legacy-view', gitPath: repo, trackingStartCommit: importedHead }, { batchSize: 10 });
+  assert.strictEqual(legacyView.repoStatus, 'ok');
+  assert.deepStrictEqual(legacyView.commits.map(item => item.hash), [second, third, fourth]);
+
+  const tree = git(repo, ['write-tree']);
+  const rewritten = git(repo, ['commit-tree', tree, '-m', 'rewritten']);
+  git(repo, ['update-ref', 'refs/heads/main', rewritten]);
+  const diverged = await scanner.scan({ repoPath: repo }, { trackingMode: 'normal', trackingStartCommit: importedHead, lastAnalyzedCommit: null });
+  assert.strictEqual(diverged.status, 'history-diverged');
+  assert.strictEqual(diverged.head, rewritten);
+  assert.deepStrictEqual(diverged.commits, []);
+
+  const missing = await scanner.scan({ repoPath: path.join(temp, 'missing') }, { trackingMode: 'normal' });
+  assert.strictEqual(missing.status, 'not-git');
+  console.log('scanner-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/server-runtime-migration-safety-test.js

@@ -0,0 +1,27 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { initializeRuntime } = require('../lib/server-app');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-runtime-migration-safety-'));
+let settingsInitialized = false;
+let registryInitialized = false;
+const runtime = {
+  rootDir: path.join(root, 'missing-legacy-root'),
+  dataPath: path.join(root, 'data'),
+  logger: { info: async () => {} },
+  migrationService: { migrateIfNeeded: async () => ({ ok: false, requiresManualRecovery: true, reason: 'fault-injected' }) },
+  settingsStore: { initialize: async () => { settingsInitialized = true; } },
+  registryStore: { initialize: async () => { registryInitialized = true; } },
+};
+
+initializeRuntime(runtime).then(() => {
+  throw new Error('initializeRuntime must reject an unsuccessful migration');
+}).catch(error => {
+  assert.equal(error.code, 'MIGRATION_FAILED');
+  assert.equal(settingsInitialized, false, 'settings defaults must not be initialized after migration failure');
+  assert.equal(registryInitialized, false, 'empty project registry must not be initialized after migration failure');
+  fs.rmSync(root, { recursive: true, force: true });
+  console.log('server-runtime-migration-safety-test PASS');
+});

package/_site/_test/server-security-test.js

@@ -0,0 +1,96 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { createRequestHandler } = require('../lib/server-app');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7832;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-security-v2-'));
+const REMOTE_PORT = 7833;
+const REMOTE_BASE = `http://127.0.0.1:${REMOTE_PORT}`;
+const remoteDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-security-remote-v2-'));
+
+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 () => {
+  assert.throws(
+    () => createRequestHandler({}, { host: '0.0.0.0', port: 9999 }),
+    error => error && error.code === 'AUTH_REQUIRED',
+    'non-loopback bind must require authentication',
+  );
+
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'security-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    let response = await fetch(`${BASE}/api/ai-profiles`, { headers: { Origin: 'https://evil.example' } });
+    assert.strictEqual(response.status, 403);
+    assert.strictEqual(response.headers.get('access-control-allow-origin'), null);
+
+    response = await fetch(`${BASE}/api/ai-profiles`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({
+        schema: 'ai-profiles/v1', profiles: [{ id: 'secret', enabled: true, apiKeyUpdate: { mode: 'replace', value: 'top-secret-api-key' } }],
+      }),
+    });
+    assert.strictEqual(response.status, 200);
+    response = await fetch(`${BASE}/api/ai-profiles`);
+    const profileText = await response.text();
+    assert(!profileText.includes('top-secret-api-key'));
+    assert(!/"apiKey"\s*:/.test(profileText));
+
+    response = await fetch(`${BASE}/api/raw?path=../../settings.json`);
+    assert.strictEqual(response.status, 404);
+    const rawText = await response.text();
+    assert(!rawText.includes('top-secret-api-key'));
+
+    response = await fetch(`${BASE}/api/projects/not-valid%2Fid`);
+    const errorText = await response.text();
+    assert(!/\bstack\b/i.test(errorText));
+    assert(!errorText.includes('top-secret-api-key'));
+    const error = JSON.parse(errorText);
+    assert(error.error.operationId);
+
+    const remote = spawnServer({
+      root: ROOT,
+      port: REMOTE_PORT,
+      host: '0.0.0.0',
+      dataDir: remoteDataDir,
+      tag: 'security-remote-v2',
+      extraEnv: {
+        KB_SKIP_MIGRATION: '1',
+        KB_SITE_AUTH_TOKEN: 'remote-auth-secret',
+        KB_ALLOWED_ORIGINS: 'https://allowed.example',
+      },
+    });
+    try {
+      for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+          const ready = await fetch(`${REMOTE_BASE}/api/health`, { headers: { Authorization: 'Bearer remote-auth-secret', Origin: 'https://allowed.example' } });
+          if (ready.ok) break;
+        } catch {}
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+      let remoteResponse = await fetch(`${REMOTE_BASE}/api/health`, { headers: { Origin: 'https://allowed.example' } });
+      assert.strictEqual(remoteResponse.status, 401, 'non-loopback request without token must fail');
+      remoteResponse = await fetch(`${REMOTE_BASE}/api/health`, { headers: { Authorization: 'Bearer remote-auth-secret', Origin: 'https://evil.example' } });
+      assert.strictEqual(remoteResponse.status, 403, 'non-loopback request from an unlisted Origin must fail');
+      remoteResponse = await fetch(`${REMOTE_BASE}/api/health`, { headers: { Authorization: 'Bearer remote-auth-secret', Origin: 'https://allowed.example' } });
+      assert.strictEqual(remoteResponse.status, 200);
+      assert.strictEqual(remoteResponse.headers.get('access-control-allow-origin'), 'https://allowed.example');
+    } finally {
+      remote.cleanup();
+    }
+    console.log('server-security-test PASS');
+  } finally {
+    await spawned.cleanup();
+    fs.rmSync(remoteDataDir, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/sessions-stream-test.js

@@ -0,0 +1,92 @@
+const assert = require('assert');
+const fs = require('fs');
+const http = require('http');
+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 = 7804;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-sse-v2-'));
+const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-sse-repo-'));
+
+function git(args) {
+  const result = spawnSync('git', args, { cwd: repoPath, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+}
+
+async function json(method, pathname, body) {
+  const response = await fetch(`${BASE}${pathname}`, { method, headers: body === undefined ? undefined : { 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body) });
+  return { status: response.status, data: await response.json() };
+}
+
+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');
+}
+
+function openSse() {
+  const frames = [];
+  let buffer = '';
+  const request = http.get(`${BASE}/api/claude/sessions-stream`, response => {
+    assert.strictEqual(response.statusCode, 200);
+    response.on('data', chunk => {
+      buffer += chunk.toString('utf8');
+      let boundary;
+      while ((boundary = buffer.indexOf('\n\n')) >= 0) {
+        const block = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const event = /^event:\s*(.+)$/m.exec(block);
+        const data = /^data:\s*(.+)$/m.exec(block);
+        if (event && data) frames.push({ event: event[1], data: JSON.parse(data[1]) });
+      }
+    });
+  });
+  request.on('error', error => { frames.push({ event: 'transport-error', data: { message: error.message } }); });
+  return { frames, close: () => request.destroy() };
+}
+
+async function waitFor(predicate) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (predicate()) return;
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  throw new Error('timed out waiting for SSE frame');
+}
+
+(async () => {
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.email', 'sse@example.test']);
+  git(['config', 'user.name', 'SSE Test']);
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'sse-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(dataDir, 'knowledge') } });
+    await json('PUT', '/api/ai-profiles', { schema: 'ai-profiles/v1', defaultProfileId: 'test', profiles: [{ id: 'test', name: 'Test', enabled: true, implementation: 'claude-code-agent', apiKeyUpdate: { mode: 'replace', value: 'sk-test' } }] });
+    const imported = await json('POST', '/api/projects/import', { localPath: repoPath, aiProfileId: 'test' });
+    assert.strictEqual(imported.status, 201, JSON.stringify(imported.data));
+
+    const stream = openSse();
+    await waitFor(() => stream.frames.some(frame => frame.event === 'claude/snapshot'));
+    const snapshot = stream.frames.find(frame => frame.event === 'claude/snapshot');
+    assert(Array.isArray(snapshot.data.sessions));
+
+    const started = await json('POST', '/api/claude/sessions', { projectId: imported.data.projectId });
+    assert.strictEqual(started.status, 201, JSON.stringify(started.data));
+    await waitFor(() => stream.frames.some(frame => frame.event === 'claude/sessions-changed' && frame.data.kind === 'create'));
+    const created = stream.frames.find(frame => frame.event === 'claude/sessions-changed' && frame.data.kind === 'create');
+    assert.strictEqual(created.data.projectSlug, imported.data.projectId);
+    const sessions = await json('GET', `/api/claude/sessions?projectId=${encodeURIComponent(imported.data.projectId)}`);
+    assert(sessions.data.sessions.some(session => session.sessionId === started.data.sessionId));
+    stream.close();
+    console.log('sessions-stream-test PASS');
+  } finally {
+    await spawned.cleanup();
+    fs.rmSync(repoPath, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/shared-contracts-test.js

@@ -0,0 +1,58 @@
+const assert = require('assert');
+const contracts = require('../lib/contracts');
+
+assert.deepStrictEqual(contracts.TRIGGERS, ['git-hook']);
+assert.deepStrictEqual(contracts.LOG_LEVELS, ['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+assert.strictEqual(contracts.SCHEMAS.projectState, 'project-state/v2');
+assert.strictEqual(contracts.SCHEMA_VERSIONS.layoutMigration, 'layout-v2');
+
+for (const trigger of contracts.TRIGGERS) assert.strictEqual(contracts.validateTrigger(trigger), trigger);
+assert.throws(() => contracts.validateTrigger('simulate'), error => error.code === 'INVALID_TRIGGER');
+assert.throws(() => contracts.validateTrigger('project-init'), error => error.code === 'INVALID_TRIGGER');
+assert.throws(() => contracts.validateTrigger('startup'), error => error.code === 'INVALID_TRIGGER');
+
+const publicProfile = contracts.publicAiProfileView({
+  id: 'primary',
+  name: 'Primary',
+  apiKey: 'sk-super-secret-1234',
+  authToken: 'second-secret',
+  baseUrl: 'https://example.invalid',
+});
+assert.strictEqual(publicProfile.id, 'primary');
+assert.strictEqual(publicProfile.baseUrl, 'https://example.invalid');
+assert.strictEqual(publicProfile.hasApiKey, true);
+assert.strictEqual(publicProfile.apiKeyMasked, '****1234');
+assert.strictEqual(Object.prototype.hasOwnProperty.call(publicProfile, 'apiKey'), false);
+assert.strictEqual(Object.prototype.hasOwnProperty.call(publicProfile, 'authToken'), false);
+
+const domainError = new contracts.DomainError('HOOK_CONFLICT', 'A non-managed hook exists.', {
+  status: 409,
+  operationId: 'op-test',
+  details: {
+    apiKey: 'must-not-leak',
+    stack: 'must-not-leak',
+    nested: { authorization: 'Bearer must-not-leak', safe: 'kept' },
+  },
+});
+const envelope = contracts.serializeErrorEnvelope(domainError);
+const serialized = JSON.stringify(envelope);
+assert.strictEqual(envelope.ok, false);
+assert.strictEqual(envelope.error.code, 'HOOK_CONFLICT');
+assert.strictEqual(envelope.error.operationId, 'op-test');
+assert(!serialized.includes('must-not-leak'));
+assert(!serialized.includes('stack'));
+assert(serialized.includes('kept'));
+
+assert.strictEqual(contracts.validateStateTransition('idle', 'scanning'), true);
+assert.strictEqual(contracts.validateStateTransition('markdown.promoted', 'state.advanced'), true);
+assert.throws(() => contracts.validateStateTransition('idle', 'markdown.promoted'));
+
+assert.strictEqual(contracts.assertMutableProjectPatch({ displayName: 'New', enabled: false }), true);
+assert.throws(() => contracts.assertMutableProjectPatch({ projectId: 'new' }), error => error.code === 'IMMUTABLE_FIELD');
+assert.throws(() => contracts.assertMutableProjectPatch({ knowledgePath: 'D:/new' }), error => error.code === 'IMMUTABLE_FIELD');
+assert.strictEqual(contracts.assertMutableProjectPatch({ knowledgePath: 'D:/new' }, { allowKnowledgePath: true }), true);
+assert.throws(() => contracts.assertMutableProjectPatch({ repoPath: 'D:/moved' }), error => error.code === 'INVALID_ARGUMENT');
+assert.strictEqual(contracts.assertMutableProjectPatch({ repoPath: 'D:/moved' }, { allowRepoPath: true }), true);
+assert.throws(() => contracts.assertMutableProjectPatch({ teamBinding: {} }), error => error.code === 'INVALID_ARGUMENT');
+
+console.log('shared-contracts-test PASS');

package/_site/_test/simple-import-test.js

@@ -0,0 +1,97 @@
+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 = 7824;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-v2-'));
+const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-repo-'));
+const knowledgeRoot = path.join(dataDir, 'knowledge');
+
+function git(args) {
+  const result = spawnSync('git', args, { cwd: repoPath, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return String(result.stdout || '').trim();
+}
+
+async function request(method, pathname, body) {
+  const response = await fetch(`${BASE}${pathname}`, {
+    method,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: response.status, data: await response.json() };
+}
+
+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 () => {
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.email', 'import@example.test']);
+  git(['config', 'user.name', 'Import Test']);
+  fs.writeFileSync(path.join(repoPath, 'README.md'), '# source\n', 'utf8');
+  git(['add', 'README.md']);
+  git(['commit', '-m', 'baseline']);
+  const baseline = git(['rev-parse', 'HEAD']);
+
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'simple-import-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  let output = '';
+  spawned.child.stdout.on('data', chunk => { output += chunk; });
+  spawned.child.stderr.on('data', chunk => { output += chunk; });
+  try {
+    await waitForServer();
+    let result = await request('PATCH', '/api/settings', { knowledge: { rootPath: knowledgeRoot } });
+    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
+
+    result = await request('POST', '/api/projects/import', { localPath: repoPath, displayName: 'Imported v2' });
+    assert.strictEqual(result.status, 201, JSON.stringify(result.data));
+    assert.match(result.data.projectId, /^project-/);
+    assert.strictEqual(result.data.project.config.projectId, result.data.projectId);
+    assert.strictEqual(result.data.project.state.trackingStartCommit, baseline);
+    assert.strictEqual(result.data.project.state.lastAnalyzedCommit, null);
+    assert.strictEqual(result.data.project.state.analysis.status, 'idle');
+    assert.strictEqual(result.data.hook.ok, true);
+    assert.strictEqual(result.data.project.state.hook.managedVersion, 2);
+    assert.deepStrictEqual(fs.readdirSync(result.data.project.config.knowledgePath), [], 'import must not create speculative knowledge');
+    assert(!fs.existsSync(path.join(dataDir, 'projects', result.data.projectId, 'requirements.jsonl')));
+
+    const projectId = result.data.projectId;
+    result = await request('PATCH', `/api/projects/${projectId}`, { displayName: 'Renamed safely', knowledgeLanguage: 'en-US' });
+    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
+    assert.strictEqual(result.data.config.displayName, 'Renamed safely');
+    result = await request('PATCH', `/api/projects/${projectId}`, { repoPath: path.join(repoPath, 'unverified') });
+    assert.strictEqual(result.status, 400, 'generic PATCH must not bypass Hook-verified repo relocation');
+    assert.strictEqual(result.data.error.code, 'INVALID_ARGUMENT');
+    result = await request('PATCH', `/api/projects/${projectId}`, { teamBinding: { provider: 'github' } });
+    assert.strictEqual(result.status, 400, 'generic PATCH must not change a fixed team binding');
+
+    const hookPath = path.join(repoPath, '.git', 'hooks', 'post-commit');
+    assert(fs.existsSync(hookPath), 'managed Hook was not installed');
+    const hook = fs.readFileSync(hookPath, 'utf8');
+    assert(hook.includes('PROJECT-KNOWLEDGE-HOOK'));
+    assert(hook.includes(projectId));
+
+    result = await request('GET', '/api/projects');
+    assert.strictEqual(result.status, 200);
+    assert.strictEqual(result.data.projects.length, 1);
+    assert.strictEqual(result.data.projects[0].projectId, result.data.projects[0].config.projectId);
+    assert(!fs.existsSync(path.join(dataDir, 'runtime', 'staging')), 'import must not dispatch analysis');
+    console.log('simple-import-test PASS');
+  } catch (error) {
+    console.error(output);
+    throw error;
+  } finally {
+    await spawned.cleanup();
+    fs.rmSync(repoPath, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/startup-analysis-disabled-test.js

@@ -0,0 +1,16 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..', '..');
+const server = fs.readFileSync(path.join(root, '_site', 'lib', 'server-app.js'), 'utf8');
+const contracts = require('../lib/contracts');
+const automation = require('../lib/post-commit-automation');
+
+assert.deepEqual(contracts.TRIGGERS, ['git-hook']);
+assert.equal(/reconcileProjectCommits\(projectId, 'startup'/.test(server), false);
+assert.equal(server.includes('reconcile.startup_failed'), false);
+assert.equal(Object.hasOwn(automation, 'dispatchPendingAutomations'), false);
+assert.equal(typeof automation.recoverOrphanedClaims, 'function');
+assert.equal(/recoverOrphanedClaims\(runtime\)/.test(server), true);
+console.log('startup-analysis-disabled-test PASS');

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

@@ -0,0 +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;
+});

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

@@ -0,0 +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;
+});