@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/helpers/parallel-nav-proxy.js

@@ -0,0 +1,148 @@
+// _site/_test/helpers/parallel-nav-proxy.js
+//
+// A pass-through proxy in front of the product server that injects transport
+// faults (a held response = a late read, a failed response) and carries the
+// product's live WebSocket channel.
+//
+// The shared product proxy cannot be used for these cases: the shell's live
+// channel is a WebSocket upgrade (/api/live), and a plain HTTP proxy answers
+// an upgrade request with 404. Without the upgrade relay the shell loses the
+// live registry/progress streams, and a product that only fills its pages
+// through those streams cannot be observed faithfully. This file is the lane's
+// own fixture for that reason; the shared helper is left untouched.
+//
+// The relay forwards the upgrade request verbatim, so the product sees the
+// browser's own Host and Origin headers and applies its own upgrade checks.
+
+'use strict';
+
+const http = require('node:http');
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', chunk => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function createNavProductProxy({ target, tag = 'product' }) {
+  const state = { requests: [], held: [], faults: [], upgrades: 0 };
+  const upstream = new URL(target);
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const raw = await readBody(req);
+    let body = null;
+    if (raw.length) { try { body = JSON.parse(raw.toString('utf8')); } catch { body = null; } }
+    const entry = { method: req.method, path: url.pathname + url.search, body, at: Date.now(), status: null };
+    state.requests.push(entry);
+
+    const fault = state.faults.find(item => !item.used && item.match(entry));
+    if (fault && fault.once) fault.used = true;
+    if (fault && fault.kind === 'fail') {
+      entry.status = fault.status;
+      sendJson(res, fault.status, { ok: false, error: { code: 'TRANSPORT_FAULT', message: fault.message || '注入的传输故障' } });
+      return;
+    }
+
+    const headers = { 'Content-Type': req.headers['content-type'] || 'application/json', 'Content-Length': String(raw.length) };
+    if (req.headers.authorization) headers.Authorization = req.headers.authorization;
+    const upstreamRequest = http.request({
+      hostname: upstream.hostname,
+      port: upstream.port,
+      path: url.pathname + url.search,
+      method: req.method,
+      headers,
+    }, upstreamResponse => {
+      entry.status = upstreamResponse.statusCode;
+      entry.respondedAt = Date.now();
+      if (fault && fault.kind === 'hold') {
+        const chunks = [];
+        upstreamResponse.on('data', chunk => chunks.push(chunk));
+        upstreamResponse.on('end', () => {
+          state.held.push({ response: res, entry, status: upstreamResponse.statusCode, headers: upstreamResponse.headers, payload: Buffer.concat(chunks) });
+        });
+        return;
+      }
+      res.writeHead(upstreamResponse.statusCode, upstreamResponse.headers);
+      upstreamResponse.pipe(res);
+    });
+    upstreamRequest.on('error', error => {
+      entry.status = 502;
+      if (!res.headersSent) sendJson(res, 502, { ok: false, error: { code: 'UPSTREAM_UNREACHABLE', message: String(error.message || error) } });
+      else res.destroy();
+    });
+    if (raw.length) upstreamRequest.write(raw);
+    upstreamRequest.end();
+  });
+
+  // The live channel: relay the upgrade to the product unchanged.
+  server.on('upgrade', (req, socket, head) => {
+    state.upgrades += 1;
+    const upstreamRequest = http.request({
+      hostname: upstream.hostname,
+      port: upstream.port,
+      path: req.url,
+      method: req.method,
+      headers: req.headers,
+    });
+    upstreamRequest.on('upgrade', (upstreamResponse, upstreamSocket, upstreamHead) => {
+      const lines = Object.entries(upstreamResponse.headers)
+        .map(([name, value]) => `${name}: ${Array.isArray(value) ? value.join(', ') : value}`);
+      socket.write(`HTTP/1.1 101 Switching Protocols\r\n${lines.join('\r\n')}\r\n\r\n`);
+      if (upstreamHead && upstreamHead.length) socket.write(upstreamHead);
+      upstreamSocket.on('error', () => socket.destroy());
+      socket.on('error', () => upstreamSocket.destroy());
+      upstreamSocket.pipe(socket);
+      socket.pipe(upstreamSocket);
+    });
+    upstreamRequest.on('error', () => socket.destroy());
+    upstreamRequest.end(head);
+  });
+
+  return {
+    tag,
+    state,
+    requests: state.requests,
+    url: null,
+    /** Hold the response of every request that matches the predicate. */
+    hold(match, { once = false } = {}) { state.faults.push({ kind: 'hold', match, once }); },
+    /** Fail every matching request with an HTTP status. */
+    fail(match, status = 503, message = '注入的传输故障', { once = false } = {}) { state.faults.push({ kind: 'fail', match, status, message, once }); },
+    clearFaults() { state.faults = []; },
+    heldCount() { return state.held.length; },
+    /** How many live-channel upgrades the proxy really relayed. */
+    upgradeCount() { return state.upgrades; },
+    /** Deliver every held response to the browser that is still waiting. */
+    releaseHeld() {
+      const held = state.held.splice(0);
+      for (const item of held) {
+        try {
+          item.response.writeHead(item.status, item.headers);
+          item.response.end(item.payload);
+        } catch {}
+      }
+      return held.length;
+    },
+    async start() {
+      await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+      this.url = `http://127.0.0.1:${server.address().port}`;
+      return this.url;
+    },
+    async close() {
+      state.held.length = 0;
+      server.closeAllConnections();
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+module.exports = { createNavProductProxy };

package/_site/_test/helpers/parallel-nav-shell.js

@@ -0,0 +1,361 @@
+// _site/_test/helpers/parallel-nav-shell.js
+//
+// Shared harness for the P-TEST-NAV regressions (NAV-002/004/005/006/007/008).
+//
+// Every case runs against a real, isolated product instance:
+//   * its own port, data dir, knowledge root and Bridge journal home
+//     (the shared spawn-server helper already isolates those);
+//   * the REAL vendored knowledge engine on its own port, reached through a
+//     pass-through proxy, so snapshots and runs are real engine state;
+//   * a test double for the embedded module UI, so the shell really talks
+//     the kb:* protocol to a real frame;
+//   * a real Chrome (CDP) in its own profile, reaching the product through a
+//     pass-through proxy that can hold or fail a single answer.
+//
+// The harness owns the native-input helpers: pointer clicks and key presses
+// go through CDP Input events, never through element.click(), and every
+// pointer click proves the hit test first (document.elementFromPoint must
+// return the target, so a transparent overlay cannot fake a click).
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { spawnServer } = require('../helpers/spawn-server');
+const { findChrome } = require('../helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('../helpers/cdp-browser');
+const { attachNetworkCapture } = require('../helpers/cdp-network-capture');
+const { createUpstreamProxy } = require('../helpers/module-fixture');
+const { createNavProductProxy } = require('./parallel-nav-proxy');
+const { createModuleUiFixture } = require('./parallel-nav-module-ui');
+const { enterNavIsolation } = require('./parallel-nav-isolation-env');
+const freePort = require('../helpers/free-port');
+
+const ROOT = path.resolve(__dirname, '../../..');
+const ENGINE_ENTRY = path.join(ROOT, '_modules', 'knowledge-engine', 'src', 'server.js');
+
+const THEMES = ['light', 'dark'];
+
+function git(cwd, args) {
+  const result = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', windowsHide: true, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+  assert.equal(result.status, 0, `git ${args.join(' ')} failed: ${result.stderr}`);
+  return String(result.stdout || '').trim();
+}
+
+/** A real Git repository with one real commit: the product imports it for real. */
+function makeRepo(root, name) {
+  const repo = path.join(root, name);
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, ['init', '-q', '-b', 'main']);
+  git(repo, ['config', 'user.email', 'parallel-nav@local.invalid']);
+  git(repo, ['config', 'user.name', 'Parallel NAV Regression']);
+  fs.writeFileSync(path.join(repo, 'README.md'), `# ${name}\n`);
+  git(repo, ['add', '.']);
+  git(repo, ['commit', '-qm', 'baseline']);
+  return { path: repo, headCommit: git(repo, ['rev-parse', 'HEAD']) };
+}
+
+/**
+ * Boot the isolated product instance, the real engine, the module-UI double
+ * and a real browser. The caller owns the cleanup through `harness.cleanup()`.
+ */
+async function startHarness({ tag, viewport = { width: 1920, height: 1080 }, evidenceDir, withEngine = true, browserDirect = false } = {}) {
+  // R7 incident premise: Chrome resolves under the REAL environment (read-only
+  // discovery) BEFORE isolation; the engine entry and every child load AFTER
+  // the driver enters the explicit environment whitelist.
+  const chromeExec = findChrome();
+  const isolation = enterNavIsolation({ tag: `pk-parallel-nav-${tag}` });
+  const fixture = isolation.root;
+  const evidence = evidenceDir || path.join(fixture, 'evidence');
+  fs.mkdirSync(evidence, { recursive: true });
+  const dataDir = path.join(fixture, 'data');
+  const knowledgeRoot = path.join(fixture, 'knowledge');
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+
+  const handles = { fixture, evidence, dataDir, knowledgeRoot };
+  let engine = null;
+  let engineProxy = null;
+  let engineToken = null;
+  let engineUrl = null;
+
+  // The vector stand-in starts BEFORE the engine: the engine constructor gets
+  // its URL explicitly, so its built-in default (127.0.0.1:8787 — a LIVE
+  // desktop hub here) is never reachable (R7 root-cause fix).
+  const moduleUi = createModuleUiFixture({ tag: `${tag}-module-ui` });
+  await moduleUi.start();
+
+  if (withEngine) {
+    engineToken = crypto.randomBytes(24).toString('hex');
+    const { createEngineServer } = require(ENGINE_ENTRY);
+    engine = createEngineServer({ dataDir: path.join(fixture, 'engine'), runtimeToken: engineToken, debug: true, consume: false, vectorUrl: moduleUi.url, bridgeUrl: moduleUi.url });
+    assert.equal(engine.coordinator.vectorUrl, moduleUi.url, 'the engine must run against the lane vector stand-in, never its 8787 default');
+    assert.equal(engine.coordinator.bridge.url, moduleUi.url, 'the engine bridge must use the lane stand-in even if a case enables consumption');
+    await engine.ready;
+    await new Promise(resolve => engine.server.listen(0, '127.0.0.1', resolve));
+    engineUrl = `http://127.0.0.1:${engine.server.address().port}`;
+    engineProxy = createUpstreamProxy({ target: engineUrl, token: engineToken, tag: 'engine' });
+    await engineProxy.start();
+  }
+
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const server = spawnServer({
+    root: ROOT,
+    port,
+    dataDir,
+    tag: `parallel-nav-${tag}`,
+    analysisOwner: 'engine',
+    extraEnv: {
+      KB_MODULES_REGISTER: '1',
+      KB_MODULES_AUTOSTART: '0',
+      KB_TERMINAL_URL: moduleUi.url,
+      KB_VECTORHUB_URL: moduleUi.url,
+      KB_EVENTBRIDGE_URL: moduleUi.url,
+      ...(engineProxy ? { KB_KNOWLEDGE_ENGINE_URL: engineProxy.url } : {}),
+    },
+  });
+
+  const productProxy = createNavProductProxy({ target: base, tag: `parallel-nav-${tag}` });
+  await productProxy.start();
+
+  const api = async (method, route, body) => {
+    const response = await fetch(base + route, {
+      method,
+      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(20000),
+    });
+    return { status: response.status, body: await response.json().catch(() => null) };
+  };
+  const engineApi = async (method, route, body) => {
+    if (!engineUrl) throw new Error('the harness runs without the engine');
+    const response = await fetch(engineUrl + route, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(engineToken ? { Authorization: `Bearer ${engineToken}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(20000),
+    });
+    return { status: response.status, body: await response.json().catch(() => null) };
+  };
+
+  await waitFor(async () => {
+    try { return (await api('GET', '/api/health')).status === 200; } catch { return false; }
+  }, 'the isolated product instance', 30000);
+  const settings = await api('PATCH', '/api/settings', { knowledge: { rootPath: knowledgeRoot } });
+  assert.equal(settings.status, 200, `the isolated instance accepts its own knowledge root: ${JSON.stringify(settings.body)}`);
+
+  let browser = null;
+  try {
+    browser = await launchCdpBrowser({
+      chrome: chromeExec,
+      profileDir: path.join(fixture, 'browser'),
+      // The live channel is a WebSocket upgrade: a plain HTTP proxy cannot
+      // carry it, so a case that needs the real live stream talks to the
+      // product directly and emulates the network failure in the browser.
+      url: (browserDirect ? base : productProxy.url) + '/',
+      width: viewport.width,
+      height: viewport.height,
+    });
+    await browser.setViewport(viewport.width, viewport.height);
+    await browser.send('Network.enable');
+  } catch (error) {
+    await server.cleanup();
+    await productProxy.close();
+    await moduleUi.close();
+    if (engineProxy) await engineProxy.close();
+    if (engine) await engine.close().catch(() => {});
+    fs.rmSync(fixture, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    isolation.restore();
+    throw error;
+  }
+
+  const capture = attachNetworkCapture(browser);
+  await capture.enable();
+
+  const run = expression => browser.evaluate(expression);
+  const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+  /** Import a real project through the real product API. */
+  const importProject = async (repo, displayName) => {
+    const knowledgePath = path.join(knowledgeRoot, displayName);
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    const result = await api('POST', '/api/projects/import', { localPath: repo.path, knowledgePath, displayName });
+    assert.equal(result.status, 201, `the project import must succeed: ${JSON.stringify(result.body)}`);
+    return { projectId: result.body.projectId, project: result.body.project, knowledgePath };
+  };
+
+  /**
+   * A native pointer click: the hit test runs first and must resolve to the
+   * target, so no transparent layer can stand in for a real click.
+   */
+  const nativeClick = async (selector, { expectHit = true } = {}) => {
+    const probe = await run(`(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return { missing: true };
+      const rect = el.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return { invisible: true, rect: { width: rect.width, height: rect.height } };
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      return {
+        x, y,
+        width: rect.width, height: rect.height,
+        hitTag: hit ? hit.tagName : '',
+        hitId: hit && hit.id ? hit.id : '',
+        hitClass: hit && hit.className && typeof hit.className === 'string' ? hit.className : '',
+        hitIsTarget: Boolean(hit && (hit === el || el.contains(hit))),
+        label: (el.textContent || '').trim().slice(0, 40),
+      };
+    })()`);
+    assert.ok(probe && !probe.missing, `the control ${selector} must exist in the page`);
+    assert.ok(!probe.invisible, `the control ${selector} must be visible: ${JSON.stringify(probe)}`);
+    if (expectHit) {
+      assert.ok(probe.hitIsTarget, `the control ${selector} must be the hit target at (${probe.x}, ${probe.y}); something else is on top: ${probe.hitTag}#${probe.hitId}.${probe.hitClass}`);
+    }
+    const common = { x: probe.x, y: probe.y, button: 'left', clickCount: 1 };
+    await browser.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: probe.x, y: probe.y, button: 'none', clickCount: 0 });
+    await browser.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...common });
+    await browser.send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...common });
+    return probe;
+  };
+
+  /** A native key press (raw key events, no synthesized DOM events). */
+  const pressKey = async (key, { code, keyCode, text } = {}) => {
+    const base = { key, code: code || key, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode };
+    await browser.send('Input.dispatchKeyEvent', { type: text ? 'keyDown' : 'rawKeyDown', ...base, text });
+    await browser.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+  };
+
+  const pressTab = () => pressKey('Tab', { code: 'Tab', keyCode: 9 });
+  const pressEnter = () => pressKey('Enter', { code: 'Enter', keyCode: 13, text: '\r' });
+
+  /** The real browser network goes offline / online (CDP, not a mock). */
+  const setOffline = async offline => {
+    await browser.send('Network.emulateNetworkConditions', {
+      offline,
+      latency: 0,
+      downloadThroughput: offline ? 0 : -1,
+      uploadThroughput: offline ? 0 : -1,
+    });
+  };
+
+  const setViewport = (width, height) => browser.setViewport(width, height);
+
+  /**
+   * The kb:* messages one embedded frame really received, in order. The
+   * module double records them inside the frame, so this is the protocol
+   * traffic itself and not a shell-side guess.
+   */
+  const frameMessages = id => run(`(() => {
+    const frame = document.getElementById(${JSON.stringify(id)});
+    const messages = frame && frame.contentWindow && frame.contentWindow.__navMessages;
+    if (!Array.isArray(messages)) return null;
+    return messages.map(entry => ({
+      type: String(entry.type || ''),
+      theme: entry.payload ? entry.payload.theme : undefined,
+      visible: entry.payload ? entry.payload.visible : undefined,
+      project: entry.payload ? entry.payload.project : undefined,
+      projectId: entry.payload ? entry.payload.projectId : undefined,
+      requestId: entry.payload ? entry.payload.requestId : undefined,
+    }));
+  })()`);
+
+  /** The number of embedded-UI documents the module double really served. */
+  const modulePageLoads = () => moduleUi.pageLoads();
+
+  /**
+   * Ask the shell to read the registry again, through the real event the
+   * shell itself listens for when the page becomes visible.
+   */
+  const requestRegistryRefresh = () => run("document.dispatchEvent(new Event('visibilitychange'))");
+
+  /**
+   * Make the shell read the registry again and wait until a new registry
+   * read really left the browser. The shell joins a registry read that is
+   * already running, so the visibility event is repeated until a new read
+   * shows up in the proxy.
+   */
+  const refreshRegistryAndWait = async (match = entry => entry.path.startsWith('/api/projects/projection'), timeoutMs = 20000) => {
+    const before = productProxy.requests.filter(match).length;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await requestRegistryRefresh();
+      await wait(300);
+      const now = productProxy.requests.filter(match).length;
+      if (now > before) return now;
+    }
+    throw new Error('the shell did not read the registry again');
+  };
+
+  /**
+   * The engine's vector traffic stayed inside this run: every /api/sync and
+   * /api/import body the stand-in received must name a sourceDir inside the
+   * fixture root. The stand-in is the ONLY vector endpoint the engine can
+   * reach (constructor vectorUrl + whitelisted env), so this proves the run
+   * never touched the real 8787 hub's write surface.
+   */
+  const assertVectorIsolation = () => {
+    const calls = [...moduleUi.vectorSyncs(), ...moduleUi.vectorImports()];
+    const violations = [];
+    for (const entry of calls) {
+      const sourceDir = entry.body && entry.body.sourceDir;
+      if (!sourceDir) continue;
+      const inside = sourceDir === fixture || sourceDir.startsWith(fixture + path.sep);
+      if (!inside) violations.push({ path: entry.path, sourceDir });
+    }
+    assert.deepEqual(violations, [], `vector calls must stay inside the fixture root (${fixture})`);
+    return { calls: calls.length, bodies: calls.map(entry => entry.body), violations };
+  };
+
+  const cleanup = async () => {
+    await browser?.close();
+    await server.cleanup();
+    await productProxy.close();
+    await moduleUi.close();
+    if (engineProxy) await engineProxy.close();
+    if (engine) await engine.close().catch(() => {});
+    fs.rmSync(fixture, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    isolation.restore();
+  };
+
+  return {
+    ...handles,
+    base,
+    server,
+    productProxy,
+    moduleUi,
+    engine,
+    engineUrl,
+    engineApi,
+    engineProxy,
+    api,
+    browser,
+    capture,
+    run,
+    wait,
+    waitFor,
+    importProject,
+    nativeClick,
+    pressKey,
+    pressTab,
+    pressEnter,
+    setOffline,
+    setViewport,
+    frameMessages,
+    modulePageLoads,
+    requestRegistryRefresh,
+    refreshRegistryAndWait,
+    assertVectorIsolation,
+    isolation,
+    cleanup,
+  };
+}
+
+module.exports = { startHarness, makeRepo, THEMES, ROOT };