@sanqianx/project-knowledge 5.0.19 → 5.0.20-rc.1

package/_site/_test/knowledge-engine-client-test.js

@@ -1,109 +1,109 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const http = require('node:http');
-const { spawn } = require('node: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 { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
-const endpoint = require('../lib/runtime-endpoint');
-const control = require('../lib/runtime-control');
-const { EngineKnowledgeClient } = require('../lib/engine-knowledge-client');
-
-(async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-engine-client-'));
-  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
-  const settings = new SettingsStore({ layout }), registry = new ProjectRegistryStore({ layout }), projects = new ProjectStore({ layout });
-  const projectId = 'project-test', repoPath = path.join(root, 'repo'), knowledgePath = path.join(root, 'knowledge');
-  fs.mkdirSync(repoPath); fs.mkdirSync(knowledgePath);
-  fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# Legacy\n\nlegacy-local-only\n');
-  await settings.initialize(); await registry.initialize();
-  await projects.create(projectId, { repoPath, knowledgePath }, { modules: { engine: { status: 'registered', projectId } } });
-  await projects.updateState(projectId, state => { state.modules = { engine: { status: 'registered', projectId } }; });
-  await registry.add(projectId, { displayNameSnapshot: 'Test' });
-  let invalidIdentity = false, malformed = false, businessError = false, oversized = false, wrongBinding = false, scopeChanged = false;
-  const calls = [];
-  const reference = { scope_project_id: projectId, entry_id: 'changes/aaaaaaaaaaaa.md', commitSha: 'a'.repeat(40), chunk_text: 'Engine authoritative knowledge' };
-  const payload = { ok: true, projectId, backend: 'hybrid+markdown-truth', results: [reference], answer: reference.chunk_text, citations: [{ ...reference, entryId: reference.entry_id }], chunks: [{ chunk_text: reference.chunk_text }] };
-  const server = http.createServer(async (req, res) => {
-    res.setHeader('Content-Type', 'application/json');
-    if (req.url === '/api/runtime/identity') return res.end(JSON.stringify(control.identity(invalidIdentity ? root : layout.getDataDir(), { port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' })));
-    if (req.url === '/api/health') return res.end(JSON.stringify({ name: 'knowledge-engine', dataSchemaVersion: 3 }));
-    if (req.url === '/api/projects') return res.end(JSON.stringify({ projects: [{ projectId, repoPath, knowledgePath: wrongBinding ? root : knowledgePath }] }));
-    let text = ''; for await (const bytes of req) text += bytes;
-    calls.push({ route: req.url, input: JSON.parse(text || '{}') });
-    if (oversized) return res.end(JSON.stringify({ ok: true, text: 'x'.repeat(2 * 1024 * 1024) }));
-    if (scopeChanged) { res.statusCode = 409; return res.end(JSON.stringify({ ok: false, error: { code: 'PROJECT_SCOPE_CHANGED' } })); }
-    if (businessError) { res.statusCode = 403; return res.end(JSON.stringify({ ok: false, error: { code: 'PATH_OUTSIDE_ROOT', message: 'private-test-secret' } })); }
-    res.end(malformed ? '[]' : JSON.stringify(payload));
-  });
-  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
-  endpoint.writeEndpoint(layout.getDataDir(), { pid: process.pid, port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' });
-  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
-  try {
-    for (const action of ['search', 'ask', 'get', 'history']) {
-      assert.deepEqual(await runtime[action]({ project: projectId, query: 'knowledge', entry: reference.entry_id, scope: 'brain', apiKey: 'must-not-forward', password: 'must-not-forward' }), payload);
-      const call = calls.at(-1);
-      assert.equal(call.route, `/api/engine/${action}`);
-      assert.equal(call.input.projectId, projectId); assert.equal(call.input.scope, 'brain');
-      assert.ok(!JSON.stringify(call.input).includes('must-not-forward'));
-    }
-    const subprocess = (file, args) => new Promise((resolve, reject) => {
-      const child = spawn(process.execPath, [file, ...args], { env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, windowsHide: true });
-      let out = '', err = ''; child.stdout.on('data', b => { out += b; }); child.stderr.on('data', b => { err += b; });
-      child.once('error', reject); child.once('close', code => resolve({ code, out, err }));
-    });
-    const cli = await subprocess(path.resolve(__dirname, '../../bin/project-knowledge-kb.js'), ['search', '--project', projectId, '--query', 'knowledge', '--scope', 'brain', '--json']);
-    assert.equal(cli.code, 0, cli.err); assert.deepEqual(JSON.parse(cli.out), payload);
-    assert.equal(calls.at(-1).input.scope, 'brain');
-    await runtime.get({ projectId, entry: reference.entry_id, space: 'brain:test' });
-    assert.equal(calls.at(-1).input.spaceId, 'brain:test', 'legacy space alias is forwarded');
-    const { createRequire } = require('node:module');
-    const sdk = createRequire(path.resolve(__dirname, '../../package.json'));
-    const { Client } = sdk('@modelcontextprotocol/sdk/client/index.js');
-    const { StdioClientTransport } = sdk('@modelcontextprotocol/sdk/client/stdio.js');
-    const transport = new StdioClientTransport({ command: process.execPath, args: [path.resolve(__dirname, '../../bin/project-knowledge-mcp.js')], env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, stderr: 'pipe' });
-    const client = new Client({ name: 'engine-regression', version: '1.0.0' });
-    try {
-      await client.connect(transport);
-      const tools = await client.listTools();
-      assert.deepEqual(tools.tools.find(t => t.name === 'project_knowledge_search').inputSchema.properties.scope.enum, ['project', 'domain', 'brain']);
-      for (const action of ['search', 'ask', 'get', 'history']) {
-        const result = await client.callTool({ name: `project_knowledge_${action}`, arguments: { projectId, scope: 'brain', ...(action === 'get' ? { entry: reference.entry_id, space: 'brain:test' } : action === 'history' ? {} : { query: 'knowledge' }) } });
-        assert.ok(!result.isError); assert.deepEqual(JSON.parse(result.content[0].text), payload);
-        assert.equal(calls.at(-1).input.scope, 'brain');
-      }
-    } finally { await client.close(); }
-    invalidIdentity = true;
-    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
-    invalidIdentity = false; malformed = true;
-    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
-    malformed = false; businessError = true;
-    await assert.rejects(runtime.get({ projectId, entry: '../outside.md' }), e => e.code === 'PATH_OUTSIDE_ROOT' && !e.message.includes('private-test-secret'));
-    businessError = false; oversized = true;
-    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
-    oversized = false;
-    scopeChanged = true;
-    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'PROJECT_SCOPE_CHANGED' && e.status === 409);
-    scopeChanged = false;
-    const direct = new EngineKnowledgeClient({ layout, engineUrl: `http://127.0.0.1:${server.address().port}` });
-    assert.deepEqual(await direct.request('search', {}, runtime.resolveProject({ projectId })), payload);
-    assert.equal(calls.at(-1).route, '/api/search');
-    wrongBinding = true;
-    await assert.rejects(direct.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
-    wrongBinding = false;
-    for (const engineUrl of ['http://example.com', 'http://secret@127.0.0.1', 'http://127.0.0.1/?apiKey=secret', 'file:///private']) {
-      const unsafe = new EngineKnowledgeClient({ layout, engineUrl });
-      await assert.rejects(unsafe.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_URL_INVALID' && !e.message.includes('secret'));
-    }
-    await assert.rejects(direct.request('../runtime-config', {}, {}), e => e.code === 'INVALID_ARGUMENT');
-    await assert.rejects(runtime.search({ projectId, scope: 'another-brain' }), e => e.code === 'INVALID_ARGUMENT');
-    const unavailable = new EngineKnowledgeClient({ layout, fetchImpl: async () => { throw new Error('private-test-secret'); } });
-    await assert.rejects(unavailable.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_UNAVAILABLE' && !e.message.includes('private-test-secret'));
-    console.log('knowledge-engine-client-test PASS (native runtime, CLI and MCP share engine facts)');
-  } finally { await runtime.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
-})().catch(error => { console.error(error); process.exitCode = 1; });
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawn } = require('node: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 { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+const endpoint = require('../lib/runtime-endpoint');
+const control = require('../lib/runtime-control');
+const { EngineKnowledgeClient } = require('../lib/engine-knowledge-client');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-engine-client-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const settings = new SettingsStore({ layout }), registry = new ProjectRegistryStore({ layout }), projects = new ProjectStore({ layout });
+  const projectId = 'project-test', repoPath = path.join(root, 'repo'), knowledgePath = path.join(root, 'knowledge');
+  fs.mkdirSync(repoPath); fs.mkdirSync(knowledgePath);
+  fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# Legacy\n\nlegacy-local-only\n');
+  await settings.initialize(); await registry.initialize();
+  await projects.create(projectId, { repoPath, knowledgePath }, { modules: { engine: { status: 'registered', projectId } } });
+  await projects.updateState(projectId, state => { state.modules = { engine: { status: 'registered', projectId } }; });
+  await registry.add(projectId, { displayNameSnapshot: 'Test' });
+  let invalidIdentity = false, malformed = false, businessError = false, oversized = false, wrongBinding = false, scopeChanged = false;
+  const calls = [];
+  const reference = { scope_project_id: projectId, entry_id: 'changes/aaaaaaaaaaaa.md', commitSha: 'a'.repeat(40), chunk_text: 'Engine authoritative knowledge' };
+  const payload = { ok: true, projectId, backend: 'hybrid+markdown-truth', results: [reference], answer: reference.chunk_text, citations: [{ ...reference, entryId: reference.entry_id }], chunks: [{ chunk_text: reference.chunk_text }] };
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    if (req.url === '/api/runtime/identity') return res.end(JSON.stringify(control.identity(invalidIdentity ? root : layout.getDataDir(), { port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' })));
+    if (req.url === '/api/health') return res.end(JSON.stringify({ name: 'knowledge-engine', dataSchemaVersion: 3 }));
+    if (req.url === '/api/projects') return res.end(JSON.stringify({ projects: [{ projectId, repoPath, knowledgePath: wrongBinding ? root : knowledgePath }] }));
+    let text = ''; for await (const bytes of req) text += bytes;
+    calls.push({ route: req.url, input: JSON.parse(text || '{}') });
+    if (oversized) return res.end(JSON.stringify({ ok: true, text: 'x'.repeat(2 * 1024 * 1024) }));
+    if (scopeChanged) { res.statusCode = 409; return res.end(JSON.stringify({ ok: false, error: { code: 'PROJECT_SCOPE_CHANGED' } })); }
+    if (businessError) { res.statusCode = 403; return res.end(JSON.stringify({ ok: false, error: { code: 'PATH_OUTSIDE_ROOT', message: 'private-test-secret' } })); }
+    res.end(malformed ? '[]' : JSON.stringify(payload));
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  endpoint.writeEndpoint(layout.getDataDir(), { pid: process.pid, port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' });
+  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
+  try {
+    for (const action of ['search', 'ask', 'get', 'history']) {
+      assert.deepEqual(await runtime[action]({ project: projectId, query: 'knowledge', entry: reference.entry_id, scope: 'brain', apiKey: 'must-not-forward', password: 'must-not-forward' }), payload);
+      const call = calls.at(-1);
+      assert.equal(call.route, `/api/engine/${action}`);
+      assert.equal(call.input.projectId, projectId); assert.equal(call.input.scope, 'brain');
+      assert.ok(!JSON.stringify(call.input).includes('must-not-forward'));
+    }
+    const subprocess = (file, args) => new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [file, ...args], { env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, windowsHide: true });
+      let out = '', err = ''; child.stdout.on('data', b => { out += b; }); child.stderr.on('data', b => { err += b; });
+      child.once('error', reject); child.once('close', code => resolve({ code, out, err }));
+    });
+    const cli = await subprocess(path.resolve(__dirname, '../../bin/project-knowledge-kb.js'), ['search', '--project', projectId, '--query', 'knowledge', '--scope', 'brain', '--json']);
+    assert.equal(cli.code, 0, cli.err); assert.deepEqual(JSON.parse(cli.out), payload);
+    assert.equal(calls.at(-1).input.scope, 'brain');
+    await runtime.get({ projectId, entry: reference.entry_id, space: 'brain:test' });
+    assert.equal(calls.at(-1).input.spaceId, 'brain:test', 'legacy space alias is forwarded');
+    const { createRequire } = require('node:module');
+    const sdk = createRequire(path.resolve(__dirname, '../../package.json'));
+    const { Client } = sdk('@modelcontextprotocol/sdk/client/index.js');
+    const { StdioClientTransport } = sdk('@modelcontextprotocol/sdk/client/stdio.js');
+    const transport = new StdioClientTransport({ command: process.execPath, args: [path.resolve(__dirname, '../../bin/project-knowledge-mcp.js')], env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, stderr: 'pipe' });
+    const client = new Client({ name: 'engine-regression', version: '1.0.0' });
+    try {
+      await client.connect(transport);
+      const tools = await client.listTools();
+      assert.deepEqual(tools.tools.find(t => t.name === 'project_knowledge_search').inputSchema.properties.scope.enum, ['project', 'domain', 'brain']);
+      for (const action of ['search', 'ask', 'get', 'history']) {
+        const result = await client.callTool({ name: `project_knowledge_${action}`, arguments: { projectId, scope: 'brain', ...(action === 'get' ? { entry: reference.entry_id, space: 'brain:test' } : action === 'history' ? {} : { query: 'knowledge' }) } });
+        assert.ok(!result.isError); assert.deepEqual(JSON.parse(result.content[0].text), payload);
+        assert.equal(calls.at(-1).input.scope, 'brain');
+      }
+    } finally { await client.close(); }
+    invalidIdentity = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
+    invalidIdentity = false; malformed = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
+    malformed = false; businessError = true;
+    await assert.rejects(runtime.get({ projectId, entry: '../outside.md' }), e => e.code === 'PATH_OUTSIDE_ROOT' && !e.message.includes('private-test-secret'));
+    businessError = false; oversized = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
+    oversized = false;
+    scopeChanged = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'PROJECT_SCOPE_CHANGED' && e.status === 409);
+    scopeChanged = false;
+    const direct = new EngineKnowledgeClient({ layout, engineUrl: `http://127.0.0.1:${server.address().port}` });
+    assert.deepEqual(await direct.request('search', {}, runtime.resolveProject({ projectId })), payload);
+    assert.equal(calls.at(-1).route, '/api/search');
+    wrongBinding = true;
+    await assert.rejects(direct.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
+    wrongBinding = false;
+    for (const engineUrl of ['http://example.com', 'http://secret@127.0.0.1', 'http://127.0.0.1/?apiKey=secret', 'file:///private']) {
+      const unsafe = new EngineKnowledgeClient({ layout, engineUrl });
+      await assert.rejects(unsafe.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_URL_INVALID' && !e.message.includes('secret'));
+    }
+    await assert.rejects(direct.request('../runtime-config', {}, {}), e => e.code === 'INVALID_ARGUMENT');
+    await assert.rejects(runtime.search({ projectId, scope: 'another-brain' }), e => e.code === 'INVALID_ARGUMENT');
+    const unavailable = new EngineKnowledgeClient({ layout, fetchImpl: async () => { throw new Error('private-test-secret'); } });
+    await assert.rejects(unavailable.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_UNAVAILABLE' && !e.message.includes('private-test-secret'));
+    console.log('knowledge-engine-client-test PASS (native runtime, CLI and MCP share engine facts)');
+  } finally { await runtime.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-maintenance-test.js

@@ -1,40 +1,40 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { IndexService } = require('../lib/index-service');
-
-(async () => {
-  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-maintenance-v2-'));
-  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
-  const registry = new ProjectRegistryStore({ layout });
-  const projects = new ProjectStore({ layout });
-  await registry.initialize();
-  const target = layout.getIndexPath();
-  fs.mkdirSync(target, { recursive: true });
-  fs.writeFileSync(path.join(target, 'version.txt'), 'old-index', 'utf8');
-  const adapter = {
-    validationOk: false,
-    async buildFull({ targetPath }) {
-      fs.mkdirSync(targetPath, { recursive: true });
-      fs.writeFileSync(path.join(targetPath, 'version.txt'), 'new-index', 'utf8');
-    },
-    async validateIndex(candidate) {
-      return { ok: this.validationOk, marker: fs.readFileSync(path.join(candidate, 'version.txt'), 'utf8') };
-    },
-  };
-  const service = new IndexService({ layout, registryStore: registry, projectStore: projects, adapter });
-  await assert.rejects(service.fullRebuild({ operationId: 'op-validation-failure' }), error => error.code === 'DATA_CORRUPT');
-  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'old-index', 'failed validation must leave the live index untouched');
-  assert(!fs.existsSync(path.join(path.dirname(target), '.knowledge.rebuild.op-validation-failure')));
-
-  adapter.validationOk = true;
-  const rebuilt = await service.fullRebuild({ operationId: 'op-valid-rebuild' });
-  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'new-index');
-  assert(rebuilt.backup && fs.existsSync(rebuilt.backup));
-  assert.strictEqual(fs.readFileSync(path.join(rebuilt.backup, 'version.txt'), 'utf8'), 'old-index', 'atomic swap must retain the previous live index');
-  console.log('knowledge-maintenance-test: PASS');
-})().catch(error => { console.error(error); 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 { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { IndexService } = require('../lib/index-service');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-maintenance-v2-'));
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+  const target = layout.getIndexPath();
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, 'version.txt'), 'old-index', 'utf8');
+  const adapter = {
+    validationOk: false,
+    async buildFull({ targetPath }) {
+      fs.mkdirSync(targetPath, { recursive: true });
+      fs.writeFileSync(path.join(targetPath, 'version.txt'), 'new-index', 'utf8');
+    },
+    async validateIndex(candidate) {
+      return { ok: this.validationOk, marker: fs.readFileSync(path.join(candidate, 'version.txt'), 'utf8') };
+    },
+  };
+  const service = new IndexService({ layout, registryStore: registry, projectStore: projects, adapter });
+  await assert.rejects(service.fullRebuild({ operationId: 'op-validation-failure' }), error => error.code === 'DATA_CORRUPT');
+  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'old-index', 'failed validation must leave the live index untouched');
+  assert(!fs.existsSync(path.join(path.dirname(target), '.knowledge.rebuild.op-validation-failure')));
+
+  adapter.validationOk = true;
+  const rebuilt = await service.fullRebuild({ operationId: 'op-valid-rebuild' });
+  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'new-index');
+  assert(rebuilt.backup && fs.existsSync(rebuilt.backup));
+  assert.strictEqual(fs.readFileSync(path.join(rebuilt.backup, 'version.txt'), 'utf8'), 'old-index', 'atomic swap must retain the previous live index');
+  console.log('knowledge-maintenance-test: PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-panel-ui-contract-test.js

@@ -0,0 +1,112 @@
+'use strict';
+// K1 knowledge panel contract: the shell registers a same-origin provider with
+// the workbench, streams structured references, folds the fixed column only
+// after a version-matched panel ack, restores it on any failure, and the panel
+// page itself renders external strings through textContent only.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const root = path.resolve(__dirname, '../..');
+const html = fs.readFileSync(path.join(root, 'ui/index.html'), 'utf8');
+const script = fs.readFileSync(path.join(root, 'ui/product.js'), 'utf8');
+const css = fs.readFileSync(path.join(root, 'ui/product.css'), 'utf8');
+const panelPath = path.join(root, 'ui/knowledge-panel.html');
+const panelHtml = fs.readFileSync(panelPath, 'utf8');
+
+/* ===================== panel page source contract ===================== */
+assert.ok(panelHtml.includes('KB-K1-KNOWLEDGE-PANEL-v1'), 'the panel page shows the stable marker');
+assert.ok(panelHtml.includes('event.source !== window.parent'), 'the panel only accepts its Workbench parent as the message source');
+assert.ok(panelHtml.includes("data.type !== 'kb:panel/content'"), 'kb:panel/content is the only inbound verb');
+assert.ok(panelHtml.includes("'kb:panel/content-ack'"), 'the panel answers with a content ack');
+assert.ok(!panelHtml.includes('innerHTML') && !panelHtml.includes('insertAdjacentHTML') && !panelHtml.includes('document.write'), 'no string becomes markup');
+assert.ok(!/<(?:script|link|img)[^>]+(?:src|href)=/.test(panelHtml.replace(/<script>[\s\S]*?<\/script>/, '')), 'the panel page loads no external resources');
+assert.ok(!panelHtml.includes('fetch(') && !panelHtml.includes('XMLHttpRequest'), 'the sandboxed panel never talks to APIs directly');
+const panelScriptMatch = panelHtml.match(/<script>([\s\S]*?)<\/script>/);
+assert.ok(panelScriptMatch, 'the panel page carries an inline script');
+assert.doesNotThrow(() => new Function(panelScriptMatch[1]));
+
+/* ===================== panel page behavior (minimal DOM) ===================== */
+function runPanelPage() {
+  const acks = [];
+  const node = () => ({ children: [], textContent: '', append(...items) { this.children.push(...items); }, replaceChildren() { this.children.length = 0; } });
+  const elements = { panelTitle: node(), panelProject: node(), panelStatus: node(), panelReferences: node(), panelMarker: node() };
+  let listener = null;
+  const parent = { postMessage(message) { acks.push(message); } };
+  const fakeWindow = { parent, addEventListener(type, fn) { if (type === 'message') listener = fn; } };
+  const fakeDocument = {
+    getElementById: id => elements[id] || null,
+    createElement: () => node(),
+  };
+  new Function('window', 'document', panelScriptMatch[1])(fakeWindow, fakeDocument);
+  assert.equal(typeof listener, 'function', 'the panel registers a message listener');
+  const deliver = (data, source = parent) => listener({ source, data });
+  return { acks, elements, deliver };
+}
+
+{
+  const page = runPanelPage();
+  page.deliver({ type: 'kb:panel/content', panelId: 'tab-1', version: 3, content: {
+    title: '本次知识引用', projectId: 'proj-a', status: 'ready',
+    references: [{ entryId: 'docs/a.md', title: 'T', text: '<img src=x onerror=alert(1)>', source: 'proj / docs/a.md' }],
+  } });
+  const ack = page.acks[page.acks.length - 1];
+  assert.equal(ack.type, 'kb:panel/content-ack');
+  assert.equal(ack.panelId, 'tab-1');
+  assert.equal(ack.version, 3);
+  assert.equal(ack.ok, true);
+  assert.equal(page.elements.panelTitle.textContent, '本次知识引用');
+  assert.equal(page.elements.panelProject.textContent, 'proj-a');
+  const reference = page.elements.panelReferences.children[0];
+  assert.ok(reference, 'one reference card rendered');
+  const text = reference.children.find(child => child.textContent.includes('<img'));
+  assert.ok(text, 'the reference body exists');
+  assert.equal(text.textContent, '<img src=x onerror=alert(1)>', 'markup-looking strings stay inert text');
+}
+{
+  const page = runPanelPage();
+  const stranger = { postMessage() {} };
+  page.deliver({ type: 'kb:panel/content', panelId: 'tab-1', version: 1, content: { title: 'x' } }, stranger);
+  assert.equal(page.acks.length, 0, 'a non-parent source is ignored without any ack');
+  page.deliver({ type: 'kb:panel/command', panelId: 'tab-1' });
+  assert.equal(page.acks.length, 0, 'non-content verbs are ignored');
+  page.deliver({ type: 'kb:panel/content', panelId: 'tab-1', version: 2, content: ['not', 'an', 'object'] });
+  const failure = page.acks[page.acks.length - 1];
+  assert.equal(failure.ok, false, 'illegal content is refused with an explicit receipt');
+  assert.ok(failure.error, 'the refusal carries an error message');
+}
+
+/* ===================== shell (product.js) contract ===================== */
+assert.ok(script.includes('kb.knowledge.references'), 'the provider id is stable');
+assert.match(script, /url: '\/knowledge-panel\.html'/, 'the provider URL is the KB-owned panel page');
+assert.match(script, /panelType: 'knowledge', title: '本次知识引用'/, 'panel type and title match the product');
+assert.match(script, /capabilities: \['read-only'\]/, 'the panel declares itself read-only');
+assert.match(script, /multiInstance: 'single'/, 'the provider is single-instance');
+assert.match(script, /if \(message\.type === 'kb:ready'\)[\s\S]*?if \(key === 'terminal'\) void resetKnowledgePanel\(\)/, 'registration starts from the terminal kb:ready');
+assert.ok(script.includes("'kb:panel/register'") && script.includes("'kb:panel/open'") && script.includes("'kb:panel/content'"), 'the shell uses the W3 verbs');
+assert.match(script, /if \(message\.type === 'kb:knowledge' && key === 'terminal'\)[\s\S]*?renderContext\(\); void pushKnowledgeToPanel/, 'kb:knowledge still refreshes the fixed column first, then streams the panel');
+assert.match(script, /const ack = panel\.content\?\.ack;[\s\S]*?if \(ack && String\(ack\.version\) === String\(pending\.version\)\)/, 'collapse waits for the version-matched ack');
+assert.match(script, /if \(ack\.ok && !panel\.error\) \{ setKnowledgeCollapsed\(true\)/, 'folding requires an error-free ack');
+assert.match(script, /if \(!panel\) \{[\s\S]*?if \(knowledgePanel\.collapsed\) setKnowledgeCollapsed\(false\);[\s\S]*?return;/, 'closing the dock panel unfolds the fixed column again');
+assert.match(script, /function knowledgePanelFailed\(reason\)[\s\S]*?setKnowledgeCollapsed\(false\);[\s\S]*?panelNotice\(/, 'every failure path restores the full column with a non-blocking notice');
+assert.match(script, /function selectProject\(id\)[\s\S]*?setKnowledgeCollapsed\(false\);[\s\S]*?pushKnowledgeToPanel\(id\)/, 'a project switch re-scopes the panel to the new project before folding again');
+assert.match(script, /renderProjectOptions\(\); setKnowledgeCollapsed\(false\); render\(\)/, 'unbinding a project also restores the fixed column');
+assert.match(script, /\.slice\(0, 50\)\.map\(r => \(\{/, 'the payload bounds the reference count');
+assert.match(script, /text: String\(r\.text \|\| ''\)\.slice\(0, 800\)/, 'the payload bounds reference text');
+assert.match(script, /knowledgePayload\(projectId\)[\s\S]*?entryId: String\(/, 'payload fields are coerced to plain strings');
+assert.equal((script.match(/classList\.toggle\('kb-panel-collapsed'/g) || []).length, 1, 'collapse is driven only through the work-layout class');
+assert.ok(!/data-action="collapse|toggle-context|折叠知识栏/.test(script + html), 'no duplicate column control button is introduced');
+assert.match(script, /panelRequest\('kb:panel\/content', \{ panelId: knowledgePanel\.panelId, providerId: knowledgePanel\.providerId, version, content: knowledgePayload\(projectId\) \}\)/, 'content carries panelId, providerId and version');
+assert.match(script, /message\.type\.startsWith\('kb:panel\/'\)/, 'panel replies are routed before the frame-context staleness drop');
+assert.match(script, /if \(message\.requestId && message\.requestId !== frames\[key\]\.requestId\) return;/, 'the legacy staleness drop stays intact for module traffic');
+assert.doesNotThrow(() => new Function(script));
+
+/* ===================== markup and css contract ===================== */
+assert.equal((html.match(/id="panelNotice"/g) || []).length, 1, 'exactly one non-blocking panel notice exists');
+assert.ok(html.includes('knowledge-context') && html.includes('id="contextContent"'), 'the fixed knowledge column markup is untouched');
+assert.ok(css.includes('.work-layout.kb-panel-collapsed{grid-template-columns:minmax(0,1fr) 0px}'), 'the fold animates the grid track instead of removing the column');
+assert.match(css, /\.work-layout\{[^}]*transition:grid-template-columns/, 'the fold is a smooth transition');
+assert.match(css, /@media \(prefers-reduced-motion: reduce\)\{\.work-layout,\.knowledge-context\{transition:none\}\}/, 'reduced-motion users get no animation');
+assert.ok(css.includes('.panel-notice'), 'the notice has styling');
+assert.match(css, /\.work-layout\{display:grid;grid-template-columns:minmax\(0,1fr\) 288px/, 'the default full-width column is unchanged');
+
+console.log('knowledge panel UI contract test PASS (source contract + sandboxed render behavior; not browser acceptance)');

package/_site/_test/knowledge-scopes-test.js

@@ -1,37 +1,37 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-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 { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
-
-(async () => {
-  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-scopes-v2-'));
-  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
-  const settings = new SettingsStore({ layout });
-  const registry = new ProjectRegistryStore({ layout });
-  const projects = new ProjectStore({ layout });
-  await settings.initialize({ knowledge: { rootPath: path.join(temp, 'knowledge') } });
-  await registry.initialize();
-  for (const projectId of ['project-api', 'project-web', 'project-transitive']) {
-    const knowledgePath = path.join(temp, 'knowledge', projectId);
-    fs.mkdirSync(knowledgePath, { recursive: true });
-    await projects.create(projectId, {
-      displayName: projectId, storageName: projectId, repoPath: path.join(temp, projectId), knowledgePath,
-      relatedProjectIds: projectId === 'project-api' ? ['project-web'] : projectId === 'project-web' ? ['project-transitive'] : [],
-    });
-    await registry.add(projectId, { displayNameSnapshot: projectId });
-  }
-  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
-  const project = runtime.resolveProject({ projectId: 'project-api' });
-  const scopes = runtime.scopes(project);
-  assert.deepStrictEqual(scopes.map(scope => scope.spaceId), ['project:project-api', 'project:project-web']);
-  assert(!scopes.some(scope => scope.projectId === 'project-transitive'), 'related scopes must remain non-transitive');
-  assert.strictEqual(scopes[0].weight, 1);
-  assert.strictEqual(scopes[1].weight, 0.88);
-  assert(!fs.existsSync(path.join(layout.getDataDir(), 'knowledge-scopes.json')), 'scope resolution must derive from immutable project config without side effects');
-  console.log('knowledge-scopes-test PASS');
-})().catch(error => { console.error(error); 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 { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-scopes-v2-'));
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const settings = new SettingsStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: path.join(temp, 'knowledge') } });
+  await registry.initialize();
+  for (const projectId of ['project-api', 'project-web', 'project-transitive']) {
+    const knowledgePath = path.join(temp, 'knowledge', projectId);
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    await projects.create(projectId, {
+      displayName: projectId, storageName: projectId, repoPath: path.join(temp, projectId), knowledgePath,
+      relatedProjectIds: projectId === 'project-api' ? ['project-web'] : projectId === 'project-web' ? ['project-transitive'] : [],
+    });
+    await registry.add(projectId, { displayNameSnapshot: projectId });
+  }
+  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
+  const project = runtime.resolveProject({ projectId: 'project-api' });
+  const scopes = runtime.scopes(project);
+  assert.deepStrictEqual(scopes.map(scope => scope.spaceId), ['project:project-api', 'project:project-web']);
+  assert(!scopes.some(scope => scope.projectId === 'project-transitive'), 'related scopes must remain non-transitive');
+  assert.strictEqual(scopes[0].weight, 1);
+  assert.strictEqual(scopes[1].weight, 0.88);
+  assert(!fs.existsSync(path.join(layout.getDataDir(), 'knowledge-scopes.json')), 'scope resolution must derive from immutable project config without side effects');
+  console.log('knowledge-scopes-test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-storage-location-test.js

@@ -1,28 +1,28 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { SettingsStore } = require('../lib/settings-store');
-
-(async () => {
-  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-storage-location-v2-'));
-  const dataDir = path.join(temp, 'data');
-  const rootA = path.join(temp, 'knowledge-a');
-  const rootB = path.join(temp, 'knowledge-b');
-  const layout = new StorageLayout({ dataDir });
-  const settings = new SettingsStore({ layout });
-  await settings.initialize({ knowledge: { rootPath: rootA } });
-  const indexPath = layout.getIndexPath();
-  fs.mkdirSync(indexPath, { recursive: true });
-  fs.writeFileSync(path.join(indexPath, 'sentinel'), 'derived-index', 'utf8');
-  await settings.updatePatch({ knowledge: { rootPath: rootB } });
-  assert.strictEqual(layout.getIndexPath(), indexPath, 'the internal index path must not follow the user knowledge root');
-  assert.strictEqual(fs.readFileSync(path.join(indexPath, 'sentinel'), 'utf8'), 'derived-index');
-  assert.strictEqual(layout.isPathInside(rootA, indexPath), false);
-  assert.strictEqual(layout.isPathInside(rootB, indexPath), false);
-  assert.strictEqual(layout.getKnowledgeRootPath(settings.read()), path.resolve(rootB));
-  assert(!fs.existsSync(path.join(rootA, '.project-knowledge')));
-  assert(!fs.existsSync(path.join(rootB, '.project-knowledge')));
-  console.log('knowledge-storage-location-test: PASS');
-})().catch(error => { console.error(error); 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 { SettingsStore } = require('../lib/settings-store');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-storage-location-v2-'));
+  const dataDir = path.join(temp, 'data');
+  const rootA = path.join(temp, 'knowledge-a');
+  const rootB = path.join(temp, 'knowledge-b');
+  const layout = new StorageLayout({ dataDir });
+  const settings = new SettingsStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: rootA } });
+  const indexPath = layout.getIndexPath();
+  fs.mkdirSync(indexPath, { recursive: true });
+  fs.writeFileSync(path.join(indexPath, 'sentinel'), 'derived-index', 'utf8');
+  await settings.updatePatch({ knowledge: { rootPath: rootB } });
+  assert.strictEqual(layout.getIndexPath(), indexPath, 'the internal index path must not follow the user knowledge root');
+  assert.strictEqual(fs.readFileSync(path.join(indexPath, 'sentinel'), 'utf8'), 'derived-index');
+  assert.strictEqual(layout.isPathInside(rootA, indexPath), false);
+  assert.strictEqual(layout.isPathInside(rootB, indexPath), false);
+  assert.strictEqual(layout.getKnowledgeRootPath(settings.read()), path.resolve(rootB));
+  assert(!fs.existsSync(path.join(rootA, '.project-knowledge')));
+  assert(!fs.existsSync(path.join(rootB, '.project-knowledge')));
+  console.log('knowledge-storage-location-test: PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });