@sanqianx/project-knowledge 4.7.0 → 4.8.0

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

@@ -1,149 +1,149 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawn, spawnSync } = require('child_process');
-const { StorageLayout } = require('../lib/storage-layout');
-const { SettingsStore } = require('../lib/settings-store');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { ConversationStore } = require('../lib/conversation-store');
-const { KnowledgeDatabase } = require('../lib/knowledge-db');
-const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const MCP_BIN = path.join(ROOT, 'bin', 'project-knowledge-mcp.js');
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-mcp-v2-'));
-const dataDir = path.join(temp, 'data');
-const repo = path.join(temp, 'repo');
-const vectorRepo = path.join(temp, 'vector-repo');
-const markdownKb = path.join(temp, 'knowledge-markdown');
-const vectorKb = path.join(temp, 'knowledge-vector');
-
-function write(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-}
-
-function git(cwd, args) {
-  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
-  assert.strictEqual(result.status, 0, result.stderr);
-  return String(result.stdout || '').trim();
-}
-
-function fakeVector(text) {
-  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
-  for (let index = 0; index < String(text).length; index += 1) vector[String(text).charCodeAt(index) % vector.length] += 1;
-  const norm = Math.sqrt(vector.reduce((sum, item) => sum + item * item, 0)) || 1;
-  return vector.map(item => item / norm);
-}
-
-async function createMcpClient() {
-  const child = spawn(process.execPath, [MCP_BIN], {
-    cwd: repo,
-    env: { ...process.env, KB_DATA_DIR: dataDir, KB_SKIP_MIGRATION: '1', KB_EMBEDDING_FAKE: '1' },
-    stdio: ['pipe', 'pipe', 'pipe'],
-    windowsHide: true,
-  });
-  let stderr = '';
-  let buffer = '';
-  let nextId = 1;
-  const pending = new Map();
-  child.stderr.on('data', chunk => { stderr += chunk; });
-  child.stdout.on('data', chunk => {
-    buffer += chunk;
-    let newline;
-    while ((newline = buffer.indexOf('\n')) >= 0) {
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      if (!line) continue;
-      const message = JSON.parse(line);
-      const entry = pending.get(message.id);
-      if (entry) { entry(message); pending.delete(message.id); }
-    }
-  });
-  const request = (method, params = {}) => new Promise((resolve, reject) => {
-    const id = nextId++;
-    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`MCP timeout: ${method}\n${stderr}`)); }, 15_000);
-    pending.set(id, message => { clearTimeout(timer); resolve(message); });
-    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
-  });
-  await request('initialize', { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'test', version: '1' } });
-  child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
-  return { child, request, stderr: () => stderr };
-}
-
-(async () => {
-  for (const cwd of [repo, vectorRepo]) {
-    fs.mkdirSync(cwd, { recursive: true });
-    git(cwd, ['init', '--initial-branch=main']);
-    git(cwd, ['config', 'user.email', 'mcp@example.test']);
-    git(cwd, ['config', 'user.name', 'MCP Test']);
-    write(path.join(cwd, 'README.md'), '# source\n');
-    git(cwd, ['add', 'README.md']);
-    git(cwd, ['commit', '-m', 'baseline']);
-  }
-  write(path.join(markdownKb, 'README.md'), '# Demo knowledge\n\nThis project uses rotating refresh tokens.\n');
-  write(path.join(markdownKb, 'modules', 'auth.md'), '# Authentication\n\nRefresh tokens rotate after every successful renewal.\n');
-  write(path.join(markdownKb, 'changes', 'auth.md'), '# Authentication update\n\nIntroduced rotating refresh tokens.\n');
-  write(path.join(vectorKb, 'modules', 'payments.md'), '# Payment tokens\n\nPayment tokens expire after fifteen minutes.\n');
-
-  const layout = new StorageLayout({ dataDir });
-  const settingsStore = new SettingsStore({ layout });
-  const registryStore = new ProjectRegistryStore({ layout });
-  const projectStore = new ProjectStore({ layout });
-  await settingsStore.initialize({ knowledge: { rootPath: path.join(temp, 'future-root') } });
-  await registryStore.initialize();
-  await projectStore.create('project-demo', { displayName: 'Demo', storageName: 'demo', repoPath: repo, knowledgePath: markdownKb, legacyExtensions: { slug: 'demo' } }, { trackingStartCommit: git(repo, ['rev-parse', 'HEAD']), index: { dirty: true, generation: 1 } });
-  await registryStore.add('project-demo', { displayNameSnapshot: 'Demo' });
-  await projectStore.create('project-vector', { displayName: 'Vector', storageName: 'vector', repoPath: vectorRepo, knowledgePath: vectorKb, legacyExtensions: { slug: 'vector' } }, { trackingStartCommit: git(vectorRepo, ['rev-parse', 'HEAD']) });
-  await registryStore.add('project-vector', { displayNameSnapshot: 'Vector' });
-
-  const database = new KnowledgeDatabase({ dbPath: layout.getIndexPath(), maintenancePath: layout.getRuntimePath('index-maintenance.json') });
-  await database.replaceEntry('project:project-vector', 'modules/payments.md', [{ chunkOrder: 0, title: 'Payment tokens', chunkText: 'Payment tokens expire after fifteen minutes.', vector: fakeVector('payment tokens'), sourceCommit: 'abc123' }]);
-  await database.ensureSearchIndexes();
-  await database.close();
-
-  const client = await createMcpClient();
-  try {
-    const listed = await client.request('tools/list');
-    assert.strictEqual(listed.result.tools.length, 6);
-    assert(listed.result.tools.some(tool => tool.name === 'project_knowledge_record_requirement'));
-
-    let response = await client.request('tools/call', { name: 'project_knowledge_resolve', arguments: { repoPath: repo } });
-    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
-    assert.strictEqual(response.result.structuredContent.knowledgePath, markdownKb);
-    assert.strictEqual(response.result.structuredContent.indexPath, layout.getIndexPath());
-
-    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { projectId: 'project-demo', query: 'refresh tokens' } });
-    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
-    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
-    assert.strictEqual(response.result.structuredContent.health.scopes[0].dirty, true);
-    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/auth.md'));
-
-    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { project: 'vector', query: 'payment tokens' } });
-    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
-    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
-    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/payments.md'));
-
-    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: 'modules/auth.md' } });
-    assert.match(response.result.structuredContent.chunks[0].chunk_text, /rotate/i);
-    response = await client.request('tools/call', { name: 'project_knowledge_history', arguments: { projectId: 'project-demo' } });
-    assert.strictEqual(response.result.structuredContent.results[0].entry_id, 'changes/auth.md');
-
-    const stateBefore = fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8');
-    response = await client.request('tools/call', { name: 'project_knowledge_record_requirement', arguments: { projectId: 'project-demo', repoPath: repo, client: 'codex', sessionId: 'session-mcp', text: 'Keep refresh token rotation documented.' } });
-    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
-    assert.strictEqual(new ConversationStore({ layout, projectStore }).readEvents('project-demo').length, 1);
-    assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-demo')), false, 'explicit MCP adapter must not create legacy requirements.jsonl');
-    assert.strictEqual(fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8'), stateBefore, 'requirement tool must not trigger analysis or mutate state');
-    assert(!fs.existsSync(layout.getRuntimePath('staging')));
-
-    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: '../settings.json' } });
-    assert.strictEqual(response.result.isError, true);
-    console.log('mcp-server-test PASS');
-  } finally {
-    client.child.stdin.end();
-    await new Promise(resolve => client.child.once('exit', resolve));
-  }
-})().catch(error => { console.error(error); process.exitCode = 1; }).finally(() => fs.rmSync(temp, { recursive: true, force: true }));
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ConversationStore } = require('../lib/conversation-store');
+const { KnowledgeDatabase } = require('../lib/knowledge-db');
+const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const MCP_BIN = path.join(ROOT, 'bin', 'project-knowledge-mcp.js');
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-mcp-v2-'));
+const dataDir = path.join(temp, 'data');
+const repo = path.join(temp, 'repo');
+const vectorRepo = path.join(temp, 'vector-repo');
+const markdownKb = path.join(temp, 'knowledge-markdown');
+const vectorKb = path.join(temp, 'knowledge-vector');
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return String(result.stdout || '').trim();
+}
+
+function fakeVector(text) {
+  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+  for (let index = 0; index < String(text).length; index += 1) vector[String(text).charCodeAt(index) % vector.length] += 1;
+  const norm = Math.sqrt(vector.reduce((sum, item) => sum + item * item, 0)) || 1;
+  return vector.map(item => item / norm);
+}
+
+async function createMcpClient() {
+  const child = spawn(process.execPath, [MCP_BIN], {
+    cwd: repo,
+    env: { ...process.env, KB_DATA_DIR: dataDir, KB_SKIP_MIGRATION: '1', KB_EMBEDDING_FAKE: '1' },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let stderr = '';
+  let buffer = '';
+  let nextId = 1;
+  const pending = new Map();
+  child.stderr.on('data', chunk => { stderr += chunk; });
+  child.stdout.on('data', chunk => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const entry = pending.get(message.id);
+      if (entry) { entry(message); pending.delete(message.id); }
+    }
+  });
+  const request = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`MCP timeout: ${method}\n${stderr}`)); }, 15_000);
+    pending.set(id, message => { clearTimeout(timer); resolve(message); });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+  });
+  await request('initialize', { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'test', version: '1' } });
+  child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+  return { child, request, stderr: () => stderr };
+}
+
+(async () => {
+  for (const cwd of [repo, vectorRepo]) {
+    fs.mkdirSync(cwd, { recursive: true });
+    git(cwd, ['init', '--initial-branch=main']);
+    git(cwd, ['config', 'user.email', 'mcp@example.test']);
+    git(cwd, ['config', 'user.name', 'MCP Test']);
+    write(path.join(cwd, 'README.md'), '# source\n');
+    git(cwd, ['add', 'README.md']);
+    git(cwd, ['commit', '-m', 'baseline']);
+  }
+  write(path.join(markdownKb, 'README.md'), '# Demo knowledge\n\nThis project uses rotating refresh tokens.\n');
+  write(path.join(markdownKb, 'modules', 'auth.md'), '# Authentication\n\nRefresh tokens rotate after every successful renewal.\n');
+  write(path.join(markdownKb, 'changes', 'auth.md'), '# Authentication update\n\nIntroduced rotating refresh tokens.\n');
+  write(path.join(vectorKb, 'modules', 'payments.md'), '# Payment tokens\n\nPayment tokens expire after fifteen minutes.\n');
+
+  const layout = new StorageLayout({ dataDir });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+  await settingsStore.initialize({ knowledge: { rootPath: path.join(temp, 'future-root') } });
+  await registryStore.initialize();
+  await projectStore.create('project-demo', { displayName: 'Demo', storageName: 'demo', repoPath: repo, knowledgePath: markdownKb, legacyExtensions: { slug: 'demo' } }, { trackingStartCommit: git(repo, ['rev-parse', 'HEAD']), index: { dirty: true, generation: 1 } });
+  await registryStore.add('project-demo', { displayNameSnapshot: 'Demo' });
+  await projectStore.create('project-vector', { displayName: 'Vector', storageName: 'vector', repoPath: vectorRepo, knowledgePath: vectorKb, legacyExtensions: { slug: 'vector' } }, { trackingStartCommit: git(vectorRepo, ['rev-parse', 'HEAD']) });
+  await registryStore.add('project-vector', { displayNameSnapshot: 'Vector' });
+
+  const database = new KnowledgeDatabase({ dbPath: layout.getIndexPath(), maintenancePath: layout.getRuntimePath('index-maintenance.json') });
+  await database.replaceEntry('project:project-vector', 'modules/payments.md', [{ chunkOrder: 0, title: 'Payment tokens', chunkText: 'Payment tokens expire after fifteen minutes.', vector: fakeVector('payment tokens'), sourceCommit: 'abc123' }]);
+  await database.ensureSearchIndexes();
+  await database.close();
+
+  const client = await createMcpClient();
+  try {
+    const listed = await client.request('tools/list');
+    assert.strictEqual(listed.result.tools.length, 6);
+    assert(listed.result.tools.some(tool => tool.name === 'project_knowledge_record_requirement'));
+
+    let response = await client.request('tools/call', { name: 'project_knowledge_resolve', arguments: { repoPath: repo } });
+    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
+    assert.strictEqual(response.result.structuredContent.knowledgePath, markdownKb);
+    assert.strictEqual(response.result.structuredContent.indexPath, layout.getIndexPath());
+
+    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { projectId: 'project-demo', query: 'refresh tokens' } });
+    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
+    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
+    assert.strictEqual(response.result.structuredContent.health.scopes[0].dirty, true);
+    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/auth.md'));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { project: 'vector', query: 'payment tokens' } });
+    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
+    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
+    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/payments.md'));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: 'modules/auth.md' } });
+    assert.match(response.result.structuredContent.chunks[0].chunk_text, /rotate/i);
+    response = await client.request('tools/call', { name: 'project_knowledge_history', arguments: { projectId: 'project-demo' } });
+    assert.strictEqual(response.result.structuredContent.results[0].entry_id, 'changes/auth.md');
+
+    const stateBefore = fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8');
+    response = await client.request('tools/call', { name: 'project_knowledge_record_requirement', arguments: { projectId: 'project-demo', repoPath: repo, client: 'codex', sessionId: 'session-mcp', text: 'Keep refresh token rotation documented.' } });
+    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
+    assert.strictEqual(new ConversationStore({ layout, projectStore }).readEvents('project-demo').length, 1);
+    assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-demo')), false, 'explicit MCP adapter must not create legacy requirements.jsonl');
+    assert.strictEqual(fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8'), stateBefore, 'requirement tool must not trigger analysis or mutate state');
+    assert(!fs.existsSync(layout.getRuntimePath('staging')));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: '../settings.json' } });
+    assert.strictEqual(response.result.isError, true);
+    console.log('mcp-server-test PASS');
+  } finally {
+    client.child.stdin.end();
+    await new Promise(resolve => client.child.once('exit', resolve));
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(() => fs.rmSync(temp, { recursive: true, force: true }));

package/_site/_test/module-artifact-integrity-test.js

@@ -0,0 +1,27 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { verifyInstalled, safeRelative } = require('../scripts/pack-module-candidates');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-module-integrity-'));
+const directory = path.join(root, 'node_modules/test-module'); fs.mkdirSync(directory, { recursive: true });
+const pkg = JSON.stringify({ name: 'test-module', version: '1.0.0' });
+fs.writeFileSync(path.join(directory, 'package.json'), pkg); fs.writeFileSync(path.join(directory, 'ui.js'), 'real-ui');
+const hash = text => crypto.createHash('sha256').update(text).digest('hex');
+const manifest = { modules: { test: { installName: 'test-module', name: 'test-module', version: '1.0.0', files: { 'package.json': hash(pkg), 'ui.js': hash('real-ui') } } } };
+verifyInstalled(manifest, root);
+fs.writeFileSync(path.join(directory, 'ui.js'), 'old-ui');
+assert.throws(() => verifyInstalled(manifest, root), /stale or altered/);
+for (const unsafe of ['../secret', '/absolute', 'ui/../../secret', 'ui\\secret', 'ui/./secret']) assert.equal(safeRelative(unsafe), false);
+assert.equal(safeRelative('ui/app.js'), true);
+const { contentAddressedArtifact } = require('../scripts/install-module-candidates');
+const tarball = path.join(root, 'same-version.tgz');
+fs.writeFileSync(tarball, 'old candidate'); const old = contentAddressedArtifact(tarball);
+fs.writeFileSync(tarball, 'new candidate'); const updated = contentAddressedArtifact(tarball);
+assert.notEqual(old.file, updated.file, 'same-version changes must invalidate the npm artifact address');
+assert.equal(fs.readFileSync(old.file, 'utf8'), 'old candidate');
+assert.equal(fs.readFileSync(updated.file, 'utf8'), 'new candidate');
+assert.equal(contentAddressedArtifact(tarball).file, updated.file, 'identical bytes keep a stable content address');
+console.log('module artifact integrity test PASS');

package/_site/_test/module-boundary-test.js

@@ -0,0 +1,30 @@
+'use strict';
+const assert = require('node:assert/strict');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+(async () => {
+  const bridge = new ModuleBridge({ engineUrl: 'http://127.0.0.1:1', settingsStore: { read: () => ({ knowledge: { rootPath: 'D:/test-knowledge' }, brain: { id: 'brain-default', name: 'test', domains: [] } }) } });
+  let calls = [];
+  bridge.proxy = async (_req, _res, target) => calls.push(target);
+  for (const route of ['api/health', '%61pi/health', 'a/../api/runtime-config', '%2e%2e/api/control', '%252e%252e/api/control', 'x\\api/health', 'internal/maintenance-config']) {
+    const res = { end() {}, statusCode: 0 };
+    await bridge.proxyModuleUi({ method: 'GET' }, res, 'engine', route, '');
+    assert.equal(res.statusCode, 404); assert.equal(calls.length, 0);
+  }
+  await bridge.proxyModuleUi({ method: 'GET' }, { end() {} }, 'terminal', 'agent-terminal/app.js', '?embed=1');
+  assert.equal(calls.length, 1);
+  calls = [];
+  bridge._fetch = async (url, init) => {
+    if (url.endsWith('/scopes')) throw new Error('scope connection failure');
+    if (url.endsWith('/internal/maintenance-config') || url.endsWith('/internal/embedding-config')) throw new Error('profile source offline');
+    calls.push({ url, body: JSON.parse(init.body) });
+    return { ok: true };
+  };
+  const status = await bridge.syncEngineConfiguration();
+  assert.equal(status.scopes, false); assert.equal(status.model, false);
+  assert.equal(calls.length, 2);
+  assert.equal(calls.find(call => call.url.endsWith('/api/runtime-config')).body.profile, null, 'scope failures must not leave a stale model credential active');
+  assert.equal(calls.find(call => call.url.endsWith('/api/internal/runtime-config')).body.settings, null, 'profile source failure must clear a stale embedding credential');
+  assert.equal(status.embedding, false);
+  console.log('module-boundary-test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/module-bridge-eventbridge-test.js

@@ -50,6 +50,7 @@ async function main() {
   const stub = http.createServer((req, res) => {
     const url = new URL(req.url, 'http://localhost');
     hits.push(`${req.method} ${url.pathname}${url.search}`);
+    if (url.pathname === '/api/health') { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ ok: true })); return; }
     if (url.pathname === '/api/echo') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ echo: `${req.method} ${url.pathname}`, query: Object.fromEntries(url.searchParams) }));
@@ -106,6 +107,7 @@ async function main() {
       terminalUrl: DEAD_URL,
       vectorHubUrl: DEAD_URL,
       eventBridgeUrl: stubUrl,
+      engineUrl: DEAD_URL,
       registryStore: { listIds: () => ['demo-proj'] },
       projectStore: makeStoreStub(),
     });
@@ -146,6 +148,11 @@ async function main() {
     assert.strictEqual(health.modules.eventBridge.up, true, 'health reports event-bridge up');
     assert.strictEqual(health.modules.terminal.up, false, 'health keeps terminal leg honest');
 
+    // An unreachable writer must block every subsequent removal.
+    const beforeRemoval = hits.length;
+    await assert.rejects(bridge.removeProjectLinks({ projectId: 'demo-proj' }), { code: 'PROJECT_BUSY' });
+    assert.strictEqual(hits.length, beforeRemoval, 'offline engine cannot remove other module bindings');
+    bridge.engineUrl = stubUrl; // This stub returns 404: the writer is already absent.
     // ---- removal: DELETE ?id=..., wiring cleared ----
     const removal = await bridge.removeProjectLinks({ projectId: 'demo-proj' });
     assert.strictEqual(removal.eventBridge.ok, true, 'removal succeeds');

package/_site/_test/module-model-configuration-test.js

@@ -0,0 +1,43 @@
+'use strict';
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { ModuleBridge } = require('../lib/module-bridge');
+(async () => {
+  let profile = { apiKey: 'controlled-model-key', mainModel: 'durable-default' };
+  let settings = { provider: 'openai', apiKey: 'controlled-vector-key', model: 'embedding-model' };
+  let appliedModel, appliedVector; const hits = [];
+  const migrationId = `embedding-${'a'.repeat(64)}`;
+  let legacy = { provider: 'minimax', apiKey: 'controlled-legacy-key', model: 'embo-01' };
+  const service = http.createServer((req, res) => {
+    assert.equal(req.headers.authorization, 'Bearer runtime-test');
+    assert.equal(req.headers.origin, undefined);
+    let input = ''; req.on('data', c => { input += c; });
+    req.on('end', () => {
+      hits.push(req.url); const body = JSON.parse(input || '{}');
+      let result = { ok: true }; let status = 200;
+      if (req.url.endsWith('/internal/maintenance-config')) { result = profile; if (!profile) status = 409; }
+      else if (req.url === '/api/internal/embedding-config') result = { settings: legacy, migrationId };
+      else if (req.url.endsWith('/internal/import-embedding')) { assert.equal(body.settings.apiKey, 'controlled-legacy-key'); }
+      else if (req.url === '/api/internal/retire-embedding') { assert.equal(body.migrationId, migrationId); legacy = null; }
+      else if (req.url.endsWith('/v1/internal/embedding-config')) { result = settings; if (!settings) status = 409; }
+      else if (req.url === '/api/internal/runtime-config') appliedVector = body.settings;
+      else if (req.url === '/api/runtime-config') appliedModel = body.profile;
+      res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(result || {}));
+    });
+  });
+  await new Promise(resolve => service.listen(0, '127.0.0.1', resolve));
+  const url = `http://127.0.0.1:${service.address().port}`;
+  const bridge = new ModuleBridge({ terminalUrl: url, engineUrl: url, vectorHubUrl: url, runtimeToken: 'runtime-test' });
+  try {
+    const status = await bridge.syncEngineConfiguration();
+    assert.equal(status.model, true); assert.equal(status.embedding, true);
+    assert.equal(appliedModel.mainModel, 'durable-default'); assert.equal(appliedVector.model, 'embedding-model');
+    assert.ok(!JSON.stringify(status).includes('key'));
+    assert.ok(hits.indexOf('/api/claude-workbench/v1/internal/import-embedding') < hits.indexOf('/api/internal/retire-embedding'));
+    profile = null; settings = null;
+    const revoked = await bridge.syncEngineConfiguration();
+    assert.equal(revoked.model, false); assert.equal(revoked.embedding, false);
+    assert.equal(appliedModel, null); assert.equal(appliedVector, null);
+    console.log('module-model-configuration-test PASS');
+  } finally { service.closeAllConnections(); await new Promise(resolve => service.close(resolve)); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/module-process-lifecycle-test.js

@@ -0,0 +1,24 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const assert = require('node:assert/strict');
+const { ModuleBridge } = require('../lib/module-bridge');
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-supervisor-lifecycle-'));
+  const fixture = path.join(root, '中文 module.js'), result = path.join(root, 'stopped.json');
+  fs.writeFileSync(fixture, "const fs=require('fs');process.on('message',m=>{if(m.type==='kb:shutdown'){fs.writeFileSync(process.argv[2],JSON.stringify({arg:process.argv[3],stopped:true}));process.exit(0);}});process.send({ready:true});");
+  const bridge = new ModuleBridge();
+  bridge._spawnSupervised({ name: 'fixture', command: `node ${JSON.stringify(fixture)} ${JSON.stringify(result)} ${JSON.stringify('中文 argument with spaces')} ` });
+  const child = bridge.supervised[0];
+  await new Promise((resolve, reject) => { child.once('message', resolve); child.once('error', reject); });
+  await bridge.stopSupervised();
+  assert.equal(child.exitCode, 0, 'IPC shutdown must finish before the shell releases its process');
+  assert.deepEqual(JSON.parse(fs.readFileSync(result)), { arg: '中文 argument with spaces', stopped: true });
+  const missing = new ModuleBridge();
+  missing._spawnSupervised({ name: 'missing', command: 'kb-definitely-missing-executable' });
+  await new Promise(resolve => setTimeout(resolve, 100));
+  assert.equal(missing.supervised.length, 0, 'failed process start must not crash or leave a false running module');
+  await missing.stopSupervised();
+  console.log('module process lifecycle test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/module-stream-proxy-test.js

@@ -0,0 +1,34 @@
+'use strict';
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+(async () => {
+  let disconnected = false; let cursor;
+  const upstream = http.createServer((req, res) => {
+    cursor = req.headers['last-event-id'];
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    res.write('id: 8\nevent: delta\ndata: {"text":"first"}\n\n');
+    const timer = setInterval(() => res.write(': live\n\n'), 100);
+    res.on('close', () => { clearInterval(timer); disconnected = true; });
+  });
+  await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
+  const bridge = new ModuleBridge();
+  const shell = http.createServer((req, res) => bridge.proxy(req, res, `http://127.0.0.1:${upstream.address().port}/events`));
+  await new Promise(resolve => shell.listen(0, '127.0.0.1', resolve));
+  const abort = new AbortController();
+  try {
+    const response = await fetch(`http://127.0.0.1:${shell.address().port}/events`, { headers: { 'Last-Event-ID': '7' }, signal: abort.signal });
+    const reader = response.body.getReader();
+    const first = await Promise.race([reader.read(), new Promise((_, reject) => setTimeout(() => reject(new Error('SSE was buffered')), 1500))]);
+    assert.match(Buffer.from(first.value).toString(), /first/);
+    assert.equal(cursor, '7');
+    abort.abort();
+    for (let i = 0; i < 40 && !disconnected; i++) await new Promise(resolve => setTimeout(resolve, 25));
+    assert.equal(disconnected, true, 'browser disconnect releases upstream');
+    console.log('module-stream-proxy-test PASS');
+  } finally {
+    abort.abort();
+    for (const server of [shell, upstream]) { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/non-release-ci-test.js

@@ -1,34 +1,34 @@
-const assert = require('assert');
-const fs = require('fs');
-const path = require('path');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const workflowPath = path.join(ROOT, '.github', 'workflows', 'ci.yml');
-const workflow = fs.readFileSync(workflowPath, 'utf8');
-
-assert.match(workflow, /^\s*push:/m, 'non-release CI must run for branch pushes');
-assert.match(workflow, /^\s*pull_request:/m, 'non-release CI must run for pull requests');
-assert.match(workflow, /node:\s*\['18\.x', '24\.x'\]/, 'Linux CI must cover Node 18 and 24');
-assert.match(workflow, /runs-on:\s*windows-latest/, 'CI must include a Windows job');
-assert.match(workflow, /npm test -- --no-report/, 'CI must run the core regression suite');
-assert.match(workflow, /npm pack --dry-run --json/, 'CI must audit the npm package contents');
-
-// Desktop development is paused by product decision (2026-08-18): the
-// non-release CI validates the web runtime only. Desktop packaging validation
-// must be restored together with desktop development; until then it must not
-// run silently under this workflow.
-assert.doesNotMatch(workflow, /npm test --prefix desktop/, 'desktop validation is paused and must not run here');
-assert.doesNotMatch(workflow, /test:packaged/, 'packaged desktop smoke is paused and must not run here');
-assert.doesNotMatch(workflow, /electron-forge|npm run make/, 'desktop packaging is paused and must not run here');
-
-for (const forbidden of [
-  /workflow_dispatch:/,
-  /^\s*tags:/m,
-  /npm\s+publish/,
-  /gh\s+release/,
-  /git\s+tag/,
-]) {
-  assert(!forbidden.test(workflow), `non-release CI contains forbidden release behavior: ${forbidden}`);
-}
-
-console.log('non-release-ci-test PASS');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const workflowPath = path.join(ROOT, '.github', 'workflows', 'ci.yml');
+const workflow = fs.readFileSync(workflowPath, 'utf8');
+
+assert.match(workflow, /^\s*push:/m, 'non-release CI must run for branch pushes');
+assert.match(workflow, /^\s*pull_request:/m, 'non-release CI must run for pull requests');
+assert.match(workflow, /node:\s*\['18\.x', '24\.x'\]/, 'Linux CI must cover Node 18 and 24');
+assert.match(workflow, /runs-on:\s*windows-latest/, 'CI must include a Windows job');
+assert.match(workflow, /npm test -- --no-report/, 'CI must run the core regression suite');
+assert.match(workflow, /npm pack --dry-run --json/, 'CI must audit the npm package contents');
+
+// Desktop development is paused by product decision (2026-08-18): the
+// non-release CI validates the web runtime only. Desktop packaging validation
+// must be restored together with desktop development; until then it must not
+// run silently under this workflow.
+assert.doesNotMatch(workflow, /npm test --prefix desktop/, 'desktop validation is paused and must not run here');
+assert.doesNotMatch(workflow, /test:packaged/, 'packaged desktop smoke is paused and must not run here');
+assert.doesNotMatch(workflow, /electron-forge|npm run make/, 'desktop packaging is paused and must not run here');
+
+for (const forbidden of [
+  /workflow_dispatch:/,
+  /^\s*tags:/m,
+  /npm\s+publish/,
+  /gh\s+release/,
+  /git\s+tag/,
+]) {
+  assert(!forbidden.test(workflow), `non-release CI contains forbidden release behavior: ${forbidden}`);
+}
+
+console.log('non-release-ci-test PASS');