@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_site/_test/run-all-tests.js

@@ -1,156 +1,159 @@
-// _site/_test/run-all-tests.js
-//
-// Single-command regression suite runner. Iterates the canonical test files
-// under _site/_test/ (everything matching *-test.js) and runs each one in a
-// separate child process, capturing exit code, duration, and the last few
-// lines of output. Writes a Markdown report to TEST-REPORT.md.
-//
-// Usage:
-//   node _site/_test/run-all-tests.js                  # run all *-test.js
-//   node _site/_test/run-all-tests.js --no-report      # do not write report
-//
-// Exit code is 0 only if every test passes.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const TEST_DIR = __dirname;
-const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
-
-const args = process.argv.slice(2);
-const WRITE_REPORT = !args.includes('--no-report');
-const PER_TEST_TIMEOUT_MS = Number(process.env.PK_TEST_TIMEOUT_MS || 90_000);
-
-function listTestFiles() {
-  return fs.readdirSync(TEST_DIR)
-    .filter(file => file.endsWith('-test.js'))
-    .filter(file => file !== 'run-all-tests.js')
-    .sort();
-}
-
-function tail(text, lines = 12) {
-  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
-  return arr.slice(-lines).join('\n');
-}
-
-function classifyFailure(result) {
-  if (result.status !== null) {
-    return { kind: 'exit', label: `FAIL (exit ${result.status})` };
-  }
-  if (result.error && result.error.code === 'ETIMEDOUT') {
-    return { kind: 'timeout', label: `TIMEOUT (killed after ${PER_TEST_TIMEOUT_MS}ms, signal ${result.signal || 'none'})` };
-  }
-  const code = result.error && result.error.code ? result.error.code : 'unknown';
-  return { kind: 'error', label: `FAIL (spawn error ${code}, signal ${result.signal || 'none'})` };
-}
-
-function runOne(file) {
-  const start = Date.now();
-  // Every test child gets its own Bridge journal sandbox so hook-trigger /
-  // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
-  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
-  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
-    cwd: ROOT,
-    encoding: 'utf-8',
-    timeout: PER_TEST_TIMEOUT_MS,
-    env: { ...process.env, FORCE_COLOR: '0', AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
-  });
-  try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
-  const failure = result.status === 0 ? null : classifyFailure(result);
-  return {
-    file,
-    passed: result.status === 0,
-    failureKind: failure ? failure.kind : null,
-    failureLabel: failure ? failure.label : null,
-    exitCode: result.status,
-    signal: result.signal,
-    spawnErrorCode: result.error && result.error.code ? result.error.code : null,
-    durationMs: Date.now() - start,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    outputTail: tail(`${result.stdout || ''}\n${result.stderr || ''}`.trim()),
-  };
-}
-
-(async () => {
-  const files = listTestFiles();
-  console.log(`Running ${files.length} test file(s)...\n`);
-
-  const results = [];
-  let totalDuration = 0;
-  for (const file of files) {
-    process.stdout.write(`> ${file} ... `);
-    const result = runOne(file);
-    totalDuration += result.durationMs;
-    results.push(result);
-
-    if (result.passed) {
-      console.log(`PASS (${result.durationMs}ms)`);
-    } else {
-      console.log(`${result.failureLabel}, ${result.durationMs}ms`);
-      if (result.outputTail) {
-        console.log('--- tail ---');
-        console.log(result.outputTail);
-        console.log('--- end tail ---');
-      }
-    }
-  }
-
-  const passed = results.filter(result => result.passed).length;
-  const failed = results.length - passed;
-  console.log('\n=========================================');
-  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
-  console.log('=========================================\n');
-
-  if (WRITE_REPORT) {
-    const lines = [];
-    lines.push('# KB Management Site Regression Test Report');
-    lines.push('');
-    lines.push(`**Generated**: ${new Date().toISOString()}`);
-    lines.push(`**Node**: ${process.version}`);
-    lines.push('**Runner**: node _site/_test/run-all-tests.js');
-    lines.push('');
-    lines.push('## Summary');
-    lines.push('');
-    lines.push(`**Per-test timeout**: ${PER_TEST_TIMEOUT_MS}ms (override with PK_TEST_TIMEOUT_MS)`);
-    lines.push('');
-    lines.push('| # | File | Status | Exit | Duration |');
-    lines.push('|--:|------|:------:|-----:|---------:|');
-    results.forEach((result, index) => {
-      const status = result.passed ? 'PASS' : (result.failureKind === 'timeout' ? 'TIMEOUT' : 'FAIL');
-      const exit = result.passed
-        ? String(result.exitCode)
-        : `${result.exitCode}${result.signal ? `, signal ${result.signal}` : ''}${result.spawnErrorCode ? `, error ${result.spawnErrorCode}` : ''}`;
-      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${exit} | ${result.durationMs}ms |`);
-    });
-    lines.push('');
-    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
-    lines.push('');
-
-    const failures = results.filter(result => !result.passed);
-    if (failures.length) {
-      lines.push('## Failures');
-      lines.push('');
-      for (const result of failures) {
-        lines.push(`### ${result.file}`);
-        lines.push('');
-        lines.push('```');
-        lines.push(result.outputTail);
-        lines.push('```');
-        lines.push('');
-      }
-    }
-
-    try {
-      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
-      console.log(`Report written to: ${REPORT_PATH}`);
-    } catch (e) {
-      console.error(`Failed to write report: ${e.message}`);
-    }
-  }
-
-  process.exit(failed > 0 ? 1 : 0);
-})();
+// _site/_test/run-all-tests.js
+//
+// Single-command regression suite runner. Iterates the canonical test files
+// under _site/_test/ (everything matching *-test.js) and runs each one in a
+// separate child process, capturing exit code, duration, and the last few
+// lines of output. Writes a Markdown report to TEST-REPORT.md.
+//
+// Usage:
+//   node _site/_test/run-all-tests.js                  # run all *-test.js
+//   node _site/_test/run-all-tests.js --no-report      # do not write report
+//
+// Exit code is 0 only if every test passes.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEST_DIR = __dirname;
+const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
+
+const args = process.argv.slice(2);
+const WRITE_REPORT = !args.includes('--no-report');
+const BACKEND_ONLY = args.includes('--backend-only');
+const PER_TEST_TIMEOUT_MS = Number(process.env.PK_TEST_TIMEOUT_MS || 90_000);
+
+function listTestFiles() {
+  return fs.readdirSync(TEST_DIR)
+    .filter(file => file.endsWith('-test.js'))
+    .filter(file => file !== 'run-all-tests.js')
+    .filter(file => !BACKEND_ONLY || !fs.readFileSync(path.join(TEST_DIR, file), 'utf8').includes('helpers/cdp-browser'))
+    .sort();
+}
+
+function tail(text, lines = 12) {
+  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
+  return arr.slice(-lines).join('\n');
+}
+
+function classifyFailure(result) {
+  if (result.status !== null) {
+    return { kind: 'exit', label: `FAIL (exit ${result.status})` };
+  }
+  if (result.error && result.error.code === 'ETIMEDOUT') {
+    return { kind: 'timeout', label: `TIMEOUT (killed after ${PER_TEST_TIMEOUT_MS}ms, signal ${result.signal || 'none'})` };
+  }
+  const code = result.error && result.error.code ? result.error.code : 'unknown';
+  return { kind: 'error', label: `FAIL (spawn error ${code}, signal ${result.signal || 'none'})` };
+}
+
+function runOne(file) {
+  const start = Date.now();
+  // Every test child gets its own Bridge journal sandbox so hook-trigger /
+  // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
+  const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
+  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    timeout: PER_TEST_TIMEOUT_MS,
+    env: { ...process.env, FORCE_COLOR: '0', AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
+  });
+  try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  const failure = result.status === 0 ? null : classifyFailure(result);
+  return {
+    file,
+    passed: result.status === 0,
+    failureKind: failure ? failure.kind : null,
+    failureLabel: failure ? failure.label : null,
+    exitCode: result.status,
+    signal: result.signal,
+    spawnErrorCode: result.error && result.error.code ? result.error.code : null,
+    durationMs: Date.now() - start,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    outputTail: tail(`${result.stdout || ''}\n${result.stderr || ''}`.trim()),
+  };
+}
+
+(async () => {
+  const files = listTestFiles();
+  if (BACKEND_ONLY) console.log('Backend/contract scope only. Browser tests are excluded, not passed.');
+  console.log(`Running ${files.length} test file(s)...\n`);
+
+  const results = [];
+  let totalDuration = 0;
+  for (const file of files) {
+    process.stdout.write(`> ${file} ... `);
+    const result = runOne(file);
+    totalDuration += result.durationMs;
+    results.push(result);
+
+    if (result.passed) {
+      console.log(`PASS (${result.durationMs}ms)`);
+    } else {
+      console.log(`${result.failureLabel}, ${result.durationMs}ms`);
+      if (result.outputTail) {
+        console.log('--- tail ---');
+        console.log(result.outputTail);
+        console.log('--- end tail ---');
+      }
+    }
+  }
+
+  const passed = results.filter(result => result.passed).length;
+  const failed = results.length - passed;
+  console.log('\n=========================================');
+  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
+  console.log('=========================================\n');
+
+  if (WRITE_REPORT) {
+    const lines = [];
+    lines.push('# KB Management Site Regression Test Report');
+    lines.push('');
+    lines.push(`**Generated**: ${new Date().toISOString()}`);
+    lines.push(`**Node**: ${process.version}`);
+    lines.push('**Runner**: node _site/_test/run-all-tests.js');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`**Per-test timeout**: ${PER_TEST_TIMEOUT_MS}ms (override with PK_TEST_TIMEOUT_MS)`);
+    lines.push('');
+    lines.push('| # | File | Status | Exit | Duration |');
+    lines.push('|--:|------|:------:|-----:|---------:|');
+    results.forEach((result, index) => {
+      const status = result.passed ? 'PASS' : (result.failureKind === 'timeout' ? 'TIMEOUT' : 'FAIL');
+      const exit = result.passed
+        ? String(result.exitCode)
+        : `${result.exitCode}${result.signal ? `, signal ${result.signal}` : ''}${result.spawnErrorCode ? `, error ${result.spawnErrorCode}` : ''}`;
+      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${exit} | ${result.durationMs}ms |`);
+    });
+    lines.push('');
+    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
+    lines.push('');
+
+    const failures = results.filter(result => !result.passed);
+    if (failures.length) {
+      lines.push('## Failures');
+      lines.push('');
+      for (const result of failures) {
+        lines.push(`### ${result.file}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(result.outputTail);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+
+    try {
+      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
+      console.log(`Report written to: ${REPORT_PATH}`);
+    } catch (e) {
+      console.error(`Failed to write report: ${e.message}`);
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+})();

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

@@ -1,58 +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');
+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/startup-analysis-disabled-test.js

@@ -1,13 +1,13 @@
-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']);
+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);

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