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

package/_site/_test/automatic-context-test.js

@@ -1,70 +1,70 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { IntegrationManager } = require('../lib/integration-installer');
-const { run, writeOutput } = require('../../plugins/project-knowledge/scripts/context-hook.cjs');
-
-async function main() {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'automatic-context-'));
-  try {
-    const endpoint = { schema: 'project-knowledge/runtime-endpoint/v1', host: '127.0.0.1', pid: process.pid, port: 23456, startedAt: 'now' };
-    fs.writeFileSync(path.join(root, 'runtime-endpoint.json'), JSON.stringify(endpoint));
-    const payload = { cwd: root, session_id: 'session-a', hook_event_name: 'UserPromptSubmit', prompt: 'Develop export normally' };
-    const env = { KB_DATA_DIR: root }, calls = [];
-    const identity = { ...endpoint, schema: 'project-knowledge/runtime-control/v1', name: 'project-knowledge', dataDir: root };
-    const fetchImpl = async (url, options) => {
-      calls.push({ url: String(url), options });
-      if (String(url).endsWith('/identity')) return Response.json(identity);
-      const input = JSON.parse(options.body);
-      return Response.json({ ok: true, requestId: input.requestId, projectId: 'project-a', status: 'ready', memoryStatus: 'ready', prompt: '<knowledge_context>export revision 37</knowledge_context>', facts: [{}], memories: [{}], references: [{}] });
-    };
-    const output = await run(payload, { env, fetchImpl });
-    assert.match(output.hookSpecificOutput.additionalContext, /revision 37/); assert.equal(calls.length, 2);
-    assert.equal(JSON.parse(calls[1].options.body).query, payload.prompt);
-    assert.ok(!JSON.stringify(output).includes('receipt')); assert.ok(!fs.existsSync(path.join(root, 'logs')));
-    await writeOutput(output, { write: (text, callback) => { assert.ok(!text.includes('receipt')); callback(); } });
-    const logDir = path.join(root, 'logs/projects/project-a'); const logText = fs.readFileSync(path.join(logDir, fs.readdirSync(logDir)[0]), 'utf8');
-    assert.ok(!logText.includes(payload.prompt)); assert.ok(!logText.includes('revision 37')); assert.ok(logText.includes('agent.context.output'));
-    calls.length = 0;
-    assert.deepEqual(await run(payload, { env: { ...env, KB_KNOWLEDGE_CONTEXT: '0' }, fetchImpl }), {}); assert.equal(calls.length, 0);
-    assert.deepEqual(await run({ ...payload, hook_event_name: 'Stop' }, { env, fetchImpl }), {});
-    const mismatch = await run(payload, { env, fetchImpl: async () => Response.json({ ...identity, dataDir: path.join(root, 'other') }) });
-    assert.match(mismatch.systemMessage, /CONTEXT_IDENTITY_MISMATCH/);
-    const unknown = await run(payload, { env, fetchImpl: async url => String(url).endsWith('/identity') ? Response.json(identity) : Response.json({ ok: false, error: 'PROJECT_NOT_FOUND' }, { status: 404 }) });
-    assert.match(unknown.systemMessage, /未识别到当前代码目录/);
-    assert.match(unknown.hookSpecificOutput.additionalContext, /不代表知识库为空/);
-    const offline = await run(payload, { env, fetchImpl: async () => { throw new Error('sensitive untrusted upstream text'); } });
-    assert.match(offline.systemMessage, /可继续开发/); assert.ok(!JSON.stringify(offline).includes('sensitive'));
-    const slow = await run(payload, { env, timeoutMs: 30, fetchImpl: (url, options) => new Promise((resolve, reject) => options.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true })) });
-    assert.match(slow.systemMessage, /CONTEXT_TIMEOUT/);
-    let version = '4.2.16'; const commandCalls = [];
-    const manager = new IntegrationManager({ homeDir: root, commandResolver: name => name, runner: (command, args) => {
-      commandCalls.push(args.join(' '));
-      if (args.join(' ') === 'plugin list --json') return { status: 0, stdout: JSON.stringify([{ id: 'project-knowledge@project-knowledge', version, enabled: true }]) };
-      if (args.join(' ') === 'plugin marketplace list --json') return { status: 0, stdout: JSON.stringify([{ name: 'project-knowledge' }]) };
-      if (args.slice(0, 2).join(' ') === 'plugin update') {
-        version = manager.version;
-        const source = path.resolve(__dirname, '../../plugins/project-knowledge'), cache = path.join(root, '.claude/plugins/cache/project-knowledge/project-knowledge', version);
-        fs.mkdirSync(cache, { recursive: true }); fs.cpSync(source, cache, { recursive: true });
-      }
-      return { status: 0, stdout: '' };
-    } });
-    const knownMarketplaces = path.join(root, '.claude/plugins/known_marketplaces.json');
-    fs.mkdirSync(path.dirname(knownMarketplaces), { recursive: true });
-    fs.writeFileSync(knownMarketplaces, JSON.stringify({ 'project-knowledge': { source: { source: 'directory', path: manager.rootDir } } }));
-    assert.equal(manager.statusClaude().state, 'needs-update');
-    manager.installClaude();
-    assert.ok(commandCalls.includes('plugin marketplace update project-knowledge'));
-    assert.ok(commandCalls.includes('plugin update project-knowledge@project-knowledge --scope user'));
-    assert.equal(manager.statusClaude().state, 'installed');
-    const cacheRoot = path.join(root, '.claude/plugins/cache/project-knowledge/project-knowledge', manager.version);
-    for (const file of ['hooks/claude.json', 'scripts/context-hook.cjs']) fs.writeFileSync(path.join(cacheRoot, file), fs.readFileSync(path.join(cacheRoot, file), 'utf8').replace(/\r?\n/g, '\r\n'));
-    assert.equal(manager.automaticContextStatus('claude', manager.statusClaude()).configured, true, 'Git CRLF checkout and npm LF are the same client integration');
-    const before = commandCalls.filter(c => c.startsWith('plugin update')).length; manager.installClaude();
-    assert.equal(commandCalls.filter(c => c.startsWith('plugin update')).length, before);
-    console.log('Automatic context protocol, fail-open safety and stale-plugin upgrade passed.');
-  } finally { fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
-}
-main().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 { IntegrationManager } = require('../lib/integration-installer');
+const { run, writeOutput } = require('../../plugins/project-knowledge/scripts/context-hook.cjs');
+
+async function main() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'automatic-context-'));
+  try {
+    const endpoint = { schema: 'project-knowledge/runtime-endpoint/v1', host: '127.0.0.1', pid: process.pid, port: 23456, startedAt: 'now' };
+    fs.writeFileSync(path.join(root, 'runtime-endpoint.json'), JSON.stringify(endpoint));
+    const payload = { cwd: root, session_id: 'session-a', hook_event_name: 'UserPromptSubmit', prompt: 'Develop export normally' };
+    const env = { KB_DATA_DIR: root }, calls = [];
+    const identity = { ...endpoint, schema: 'project-knowledge/runtime-control/v1', name: 'project-knowledge', dataDir: root };
+    const fetchImpl = async (url, options) => {
+      calls.push({ url: String(url), options });
+      if (String(url).endsWith('/identity')) return Response.json(identity);
+      const input = JSON.parse(options.body);
+      return Response.json({ ok: true, requestId: input.requestId, projectId: 'project-a', status: 'ready', memoryStatus: 'ready', prompt: '<knowledge_context>export revision 37</knowledge_context>', facts: [{}], memories: [{}], references: [{}] });
+    };
+    const output = await run(payload, { env, fetchImpl });
+    assert.match(output.hookSpecificOutput.additionalContext, /revision 37/); assert.equal(calls.length, 2);
+    assert.equal(JSON.parse(calls[1].options.body).query, payload.prompt);
+    assert.ok(!JSON.stringify(output).includes('receipt')); assert.ok(!fs.existsSync(path.join(root, 'logs')));
+    await writeOutput(output, { write: (text, callback) => { assert.ok(!text.includes('receipt')); callback(); } });
+    const logDir = path.join(root, 'logs/projects/project-a'); const logText = fs.readFileSync(path.join(logDir, fs.readdirSync(logDir)[0]), 'utf8');
+    assert.ok(!logText.includes(payload.prompt)); assert.ok(!logText.includes('revision 37')); assert.ok(logText.includes('agent.context.output'));
+    calls.length = 0;
+    assert.deepEqual(await run(payload, { env: { ...env, KB_KNOWLEDGE_CONTEXT: '0' }, fetchImpl }), {}); assert.equal(calls.length, 0);
+    assert.deepEqual(await run({ ...payload, hook_event_name: 'Stop' }, { env, fetchImpl }), {});
+    const mismatch = await run(payload, { env, fetchImpl: async () => Response.json({ ...identity, dataDir: path.join(root, 'other') }) });
+    assert.match(mismatch.systemMessage, /CONTEXT_IDENTITY_MISMATCH/);
+    const unknown = await run(payload, { env, fetchImpl: async url => String(url).endsWith('/identity') ? Response.json(identity) : Response.json({ ok: false, error: 'PROJECT_NOT_FOUND' }, { status: 404 }) });
+    assert.match(unknown.systemMessage, /未识别到当前代码目录/);
+    assert.match(unknown.hookSpecificOutput.additionalContext, /不代表知识库为空/);
+    const offline = await run(payload, { env, fetchImpl: async () => { throw new Error('sensitive untrusted upstream text'); } });
+    assert.match(offline.systemMessage, /可继续开发/); assert.ok(!JSON.stringify(offline).includes('sensitive'));
+    const slow = await run(payload, { env, timeoutMs: 30, fetchImpl: (url, options) => new Promise((resolve, reject) => options.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true })) });
+    assert.match(slow.systemMessage, /CONTEXT_TIMEOUT/);
+    let version = '4.2.16'; const commandCalls = [];
+    const manager = new IntegrationManager({ homeDir: root, commandResolver: name => name, runner: (command, args) => {
+      commandCalls.push(args.join(' '));
+      if (args.join(' ') === 'plugin list --json') return { status: 0, stdout: JSON.stringify([{ id: 'project-knowledge@project-knowledge', version, enabled: true }]) };
+      if (args.join(' ') === 'plugin marketplace list --json') return { status: 0, stdout: JSON.stringify([{ name: 'project-knowledge' }]) };
+      if (args.slice(0, 2).join(' ') === 'plugin update') {
+        version = manager.version;
+        const source = path.resolve(__dirname, '../../plugins/project-knowledge'), cache = path.join(root, '.claude/plugins/cache/project-knowledge/project-knowledge', version);
+        fs.mkdirSync(cache, { recursive: true }); fs.cpSync(source, cache, { recursive: true });
+      }
+      return { status: 0, stdout: '' };
+    } });
+    const knownMarketplaces = path.join(root, '.claude/plugins/known_marketplaces.json');
+    fs.mkdirSync(path.dirname(knownMarketplaces), { recursive: true });
+    fs.writeFileSync(knownMarketplaces, JSON.stringify({ 'project-knowledge': { source: { source: 'directory', path: manager.rootDir } } }));
+    assert.equal(manager.statusClaude().state, 'needs-update');
+    manager.installClaude();
+    assert.ok(commandCalls.includes('plugin marketplace update project-knowledge'));
+    assert.ok(commandCalls.includes('plugin update project-knowledge@project-knowledge --scope user'));
+    assert.equal(manager.statusClaude().state, 'installed');
+    const cacheRoot = path.join(root, '.claude/plugins/cache/project-knowledge/project-knowledge', manager.version);
+    for (const file of ['hooks/claude.json', 'scripts/context-hook.cjs']) fs.writeFileSync(path.join(cacheRoot, file), fs.readFileSync(path.join(cacheRoot, file), 'utf8').replace(/\r?\n/g, '\r\n'));
+    assert.equal(manager.automaticContextStatus('claude', manager.statusClaude()).configured, true, 'Git CRLF checkout and npm LF are the same client integration');
+    const before = commandCalls.filter(c => c.startsWith('plugin update')).length; manager.installClaude();
+    assert.equal(commandCalls.filter(c => c.startsWith('plugin update')).length, before);
+    console.log('Automatic context protocol, fail-open safety and stale-plugin upgrade passed.');
+  } finally { fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/bin-cli-test.js

@@ -1,230 +1,230 @@
-// Run: node _site/_test/bin-cli-test.js
-//
-// Covers the project-knowledge CLI:
-//   --version, --help, status (no pid), stop (no pid),
-//   --fg foreground lifecycle (PID file written + cleaned),
-//   port fallback when default port is busy.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const net = require('net');
-const { spawn, spawnSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const BIN = path.join(ROOT, 'bin', 'project-knowledge.js');
-const KB_BIN = path.join(ROOT, 'bin', 'project-knowledge-kb.js');
-const ISOLATED_STATUS_PORT = 19000 + (process.pid % 1000);
-const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-${process.pid}-`));
-const PID_FILE = path.join(TEST_DATA_DIR, 'runtime-endpoint.json');
-const TEST_BRIDGE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-bridge-${process.pid}-`));
-const TEST_ENV = { ...process.env, KB_DATA_DIR: TEST_DATA_DIR, KB_SKIP_MIGRATION: '1', AI_CODING_EVENT_BRIDGE_HOME: TEST_BRIDGE_HOME, KB_MODULES_AUTOSTART: '0' };
-
-function assert(cond, msg) { if (!cond) throw new Error(msg); }
-
-function run(args, opts = {}) {
-  return spawnSync(process.execPath, [BIN, ...args], {
-    cwd: ROOT,
-    encoding: 'utf-8',
-    timeout: 15_000,
-    env: TEST_ENV,
-    ...opts,
-  });
-}
-
-function readPidFile() {
-  try {
-    if (!fs.existsSync(PID_FILE)) return null;
-    return JSON.parse(fs.readFileSync(PID_FILE, 'utf8'));
-  } catch { return null; }
-}
-
-function removePidFile() {
-  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
-}
-
-function pickFreePort() {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on('error', reject);
-    server.listen(0, () => {
-      const { port } = server.address();
-      server.close(() => resolve(port));
-    });
-  });
-}
-
-function isPortListening(port) {
-  // A port is "in use by someone else" iff we cannot bind it (EADDRINUSE).
-  // If our probe bind succeeds, the port is actually free.
-  return new Promise((resolve) => {
-    const tester = net.createServer();
-    tester.unref();
-    const finish = (inUse) => {
-      tester.removeAllListeners();
-      tester.close(() => resolve(inUse));
-    };
-    tester.once('error', (err) => {
-      if (err && err.code === 'EADDRINUSE') finish(true);
-      else finish(false);
-    });
-    tester.once('listening', () => finish(false));
-    tester.listen(port, '127.0.0.1');
-    setTimeout(() => finish(false), 500);
-  });
-}
-
-async function waitForListening(port, deadlineMs = 8000) {
-  const deadline = Date.now() + deadlineMs;
-  while (Date.now() < deadline) {
-    if (await canConnect(port)) return true;
-    await new Promise(resolve => setTimeout(resolve, 150));
-  }
-  return false;
-}
-
-function canConnect(port) {
-  // A bind probe can steal the selected port exactly as the child starts.
-  // Readiness checks must connect, never compete with the server's listener.
-  return new Promise(resolve => {
-    const socket = net.createConnection({ host: '127.0.0.1', port });
-    let settled = false;
-    const finish = result => { if (settled) return; settled = true; socket.destroy(); resolve(result); };
-    socket.setTimeout(500, () => finish(false));
-    socket.once('connect', () => finish(true));
-    socket.once('error', () => finish(false));
-  });
-}
-
-(async () => {
-  // Make sure no leftover PID file or server from a previous run.
-  removePidFile();
-
-  // --version
-  const versionResult = run(['--version']);
-  assert(versionResult.status === 0, `--version should exit 0, got ${versionResult.status}: ${versionResult.stderr}`);
-  assert(versionResult.stdout.trim() === require(path.join(ROOT, 'package.json')).version,
-    `--version output (${versionResult.stdout.trim()}) should match package.json`);
-
-  // --help mentions the new subcommands
-  const helpResult = run(['--help']);
-  assert(helpResult.status === 0, '--help should exit 0');
-  const helpText = helpResult.stdout;
-  assert(/stop/.test(helpText), '--help should mention `stop`');
-  assert(/status/.test(helpText), '--help should mention `status`');
-  assert(/--fg/.test(helpText), '--help should mention `--fg`');
-  assert(/--no-open/.test(helpText), '--help should mention `--no-open`');
-  assert(/5757/.test(helpText), '--help should mention default port 5757');
-
-  const kbHelp = spawnSync(process.execPath, [KB_BIN, '--help'], { cwd: ROOT, encoding: 'utf8', timeout: 15_000 });
-  assert(kbHelp.status === 0, `project-knowledge-kb --help should exit 0: ${kbHelp.stderr}`);
-  assert(/search/.test(kbHelp.stdout) && /history/.test(kbHelp.stdout), 'knowledge CLI help should list read-only commands');
-
-  // status when no PID file
-  removePidFile();
-  const statusResult = run(['status'], { env: { ...TEST_ENV, KB_SITE_PORT: String(ISOLATED_STATUS_PORT) } });
-  assert(statusResult.status === 0, 'status should exit 0 when not running');
-  assert(/not running/i.test(statusResult.stdout + statusResult.stderr),
-    `status output should mention "not running", got: ${statusResult.stdout} ${statusResult.stderr}`);
-
-  // stop when no PID file
-  const stopResult = run(['stop'], { env: { ...TEST_ENV, KB_SITE_PORT: String(ISOLATED_STATUS_PORT) } });
-  assert(stopResult.status === 0, 'stop should exit 0 when no PID file');
-  assert(/No background process/i.test(stopResult.stdout + stopResult.stderr),
-    `stop output should mention "No background process", got: ${stopResult.stdout} ${stopResult.stderr}`);
-
-  // Foreground lifecycle: --fg writes PID file and listens; SIGTERM cleans up.
-  const fgPort = await pickFreePort();
-  const fgChild = spawn(process.execPath, [BIN, '--fg', '--port', String(fgPort), '--no-open'], {
-    cwd: ROOT,
-    env: TEST_ENV,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    windowsHide: true,
-  });
-  let fgOutput = '';
-  fgChild.stdout.on('data', d => { fgOutput += d.toString(); });
-  fgChild.stderr.on('data', d => { fgOutput += d.toString(); });
-
-  const listening = await waitForListening(fgPort);
-  assert(listening, `server in --fg mode should listen on port ${fgPort}; output: ${fgOutput}`);
-
-  const pidRecord = readPidFile();
-  assert(pidRecord, `PID file at ${PID_FILE} should exist after fg child bound port; output: ${fgOutput}`);
-  assert(pidRecord.pid === fgChild.pid,
-    `PID file should record the foreground child PID (file: ${JSON.stringify(pidRecord)}, child: ${fgChild.pid})`);
-  assert(pidRecord.port === fgPort,
-    `PID file should record the actual port ${fgPort}, got ${pidRecord && pidRecord.port}`);
-
-  fgChild.kill('SIGTERM');
-  await new Promise(resolve => setTimeout(resolve, 400));
-
-  // On Windows, child.kill('SIGTERM') goes through TerminateProcess and skips
-  // Node's exit/SIGTERM handlers, so we can't reliably assert PID file cleanup
-  // here. Instead, verify the bin was responsive while alive and that the
-  // child is gone; the test harness cleans up the PID file at the end.
-  assert(fgChild.killed || fgChild.exitCode !== null, 'foreground child should have exited on kill');
-  removePidFile();
-
-  // Port fallback: bind a port in 5757-5776 range, then start --fg without --port
-  // → CLI should pick the next free port in that range.
-  let busyPort = null;
-  for (let candidate = 5757; candidate < 5757 + 19; candidate++) {
-    if (!(await isPortListening(candidate)) && !(await isPortListening(candidate + 1))) {
-      busyPort = candidate;
-      break;
-    }
-  }
-  assert(busyPort, 'should find a free port in fallback range');
-  const busyServer = net.createServer();
-  await new Promise((resolve, reject) => {
-    busyServer.once('error', reject);
-    busyServer.listen(busyPort, '127.0.0.1', resolve);
-  });
-
-  const fallbackChild = spawn(process.execPath, [BIN, '--fg', '--no-open'], {
-    cwd: ROOT,
-    env: { ...TEST_ENV, KB_SITE_PORT: String(busyPort) },
-    stdio: ['ignore', 'pipe', 'pipe'],
-    windowsHide: true,
-  });
-  let fallbackOutput = '';
-  fallbackChild.stdout.on('data', d => { fallbackOutput += d.toString(); });
-  fallbackChild.stderr.on('data', d => { fallbackOutput += d.toString(); });
-
-  // Wait for server to come up on some port.
-  const deadline = Date.now() + 8000;
-  let detectedPort = null;
-  while (Date.now() < deadline && !detectedPort) {
-    const rec = readPidFile();
-    if (rec && rec.port && rec.port !== busyPort) {
-      if (await canConnect(rec.port)) {
-        detectedPort = rec.port;
-        break;
-      }
-    }
-    await new Promise(resolve => setTimeout(resolve, 150));
-  }
-  assert(detectedPort, `port fallback should pick a free port (output: ${fallbackOutput})`);
-  assert(detectedPort >= 5757 && detectedPort < 5757 + 20,
-    `fallback port ${detectedPort} should be in 5757–${5757 + 19} range`);
-
-  fallbackChild.kill('SIGTERM');
-  await new Promise(resolve => setTimeout(resolve, 400));
-  await new Promise(resolve => busyServer.close(resolve));
-
-  // Unknown flag should exit non-zero
-  const unknown = run(['--bogus']);
-  assert(unknown.status !== 0, 'unknown flag should exit non-zero');
-  assert(/Unknown option/i.test(unknown.stdout + unknown.stderr),
-    `unknown flag output should mention "Unknown option", got: ${unknown.stdout} ${unknown.stderr}`);
-
-  removePidFile();
-  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
-  console.log('bin-cli-test PASS');
-})().catch(err => {
-  console.error(err && err.stack || err);
-  removePidFile();
-  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
-  process.exit(1);
-});
+// Run: node _site/_test/bin-cli-test.js
+//
+// Covers the project-knowledge CLI:
+//   --version, --help, status (no pid), stop (no pid),
+//   --fg foreground lifecycle (PID file written + cleaned),
+//   port fallback when default port is busy.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const net = require('net');
+const { spawn, spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BIN = path.join(ROOT, 'bin', 'project-knowledge.js');
+const KB_BIN = path.join(ROOT, 'bin', 'project-knowledge-kb.js');
+const ISOLATED_STATUS_PORT = 19000 + (process.pid % 1000);
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-${process.pid}-`));
+const PID_FILE = path.join(TEST_DATA_DIR, 'runtime-endpoint.json');
+const TEST_BRIDGE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-bridge-${process.pid}-`));
+const TEST_ENV = { ...process.env, KB_DATA_DIR: TEST_DATA_DIR, KB_SKIP_MIGRATION: '1', AI_CODING_EVENT_BRIDGE_HOME: TEST_BRIDGE_HOME, KB_MODULES_AUTOSTART: '0' };
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+function run(args, opts = {}) {
+  return spawnSync(process.execPath, [BIN, ...args], {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    timeout: 15_000,
+    env: TEST_ENV,
+    ...opts,
+  });
+}
+
+function readPidFile() {
+  try {
+    if (!fs.existsSync(PID_FILE)) return null;
+    return JSON.parse(fs.readFileSync(PID_FILE, 'utf8'));
+  } catch { return null; }
+}
+
+function removePidFile() {
+  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+}
+
+function pickFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+function isPortListening(port) {
+  // A port is "in use by someone else" iff we cannot bind it (EADDRINUSE).
+  // If our probe bind succeeds, the port is actually free.
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    tester.unref();
+    const finish = (inUse) => {
+      tester.removeAllListeners();
+      tester.close(() => resolve(inUse));
+    };
+    tester.once('error', (err) => {
+      if (err && err.code === 'EADDRINUSE') finish(true);
+      else finish(false);
+    });
+    tester.once('listening', () => finish(false));
+    tester.listen(port, '127.0.0.1');
+    setTimeout(() => finish(false), 500);
+  });
+}
+
+async function waitForListening(port, deadlineMs = 8000) {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    if (await canConnect(port)) return true;
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  return false;
+}
+
+function canConnect(port) {
+  // A bind probe can steal the selected port exactly as the child starts.
+  // Readiness checks must connect, never compete with the server's listener.
+  return new Promise(resolve => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    let settled = false;
+    const finish = result => { if (settled) return; settled = true; socket.destroy(); resolve(result); };
+    socket.setTimeout(500, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+(async () => {
+  // Make sure no leftover PID file or server from a previous run.
+  removePidFile();
+
+  // --version
+  const versionResult = run(['--version']);
+  assert(versionResult.status === 0, `--version should exit 0, got ${versionResult.status}: ${versionResult.stderr}`);
+  assert(versionResult.stdout.trim() === require(path.join(ROOT, 'package.json')).version,
+    `--version output (${versionResult.stdout.trim()}) should match package.json`);
+
+  // --help mentions the new subcommands
+  const helpResult = run(['--help']);
+  assert(helpResult.status === 0, '--help should exit 0');
+  const helpText = helpResult.stdout;
+  assert(/stop/.test(helpText), '--help should mention `stop`');
+  assert(/status/.test(helpText), '--help should mention `status`');
+  assert(/--fg/.test(helpText), '--help should mention `--fg`');
+  assert(/--no-open/.test(helpText), '--help should mention `--no-open`');
+  assert(/5757/.test(helpText), '--help should mention default port 5757');
+
+  const kbHelp = spawnSync(process.execPath, [KB_BIN, '--help'], { cwd: ROOT, encoding: 'utf8', timeout: 15_000 });
+  assert(kbHelp.status === 0, `project-knowledge-kb --help should exit 0: ${kbHelp.stderr}`);
+  assert(/search/.test(kbHelp.stdout) && /history/.test(kbHelp.stdout), 'knowledge CLI help should list read-only commands');
+
+  // status when no PID file
+  removePidFile();
+  const statusResult = run(['status'], { env: { ...TEST_ENV, KB_SITE_PORT: String(ISOLATED_STATUS_PORT) } });
+  assert(statusResult.status === 0, 'status should exit 0 when not running');
+  assert(/not running/i.test(statusResult.stdout + statusResult.stderr),
+    `status output should mention "not running", got: ${statusResult.stdout} ${statusResult.stderr}`);
+
+  // stop when no PID file
+  const stopResult = run(['stop'], { env: { ...TEST_ENV, KB_SITE_PORT: String(ISOLATED_STATUS_PORT) } });
+  assert(stopResult.status === 0, 'stop should exit 0 when no PID file');
+  assert(/No background process/i.test(stopResult.stdout + stopResult.stderr),
+    `stop output should mention "No background process", got: ${stopResult.stdout} ${stopResult.stderr}`);
+
+  // Foreground lifecycle: --fg writes PID file and listens; SIGTERM cleans up.
+  const fgPort = await pickFreePort();
+  const fgChild = spawn(process.execPath, [BIN, '--fg', '--port', String(fgPort), '--no-open'], {
+    cwd: ROOT,
+    env: TEST_ENV,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let fgOutput = '';
+  fgChild.stdout.on('data', d => { fgOutput += d.toString(); });
+  fgChild.stderr.on('data', d => { fgOutput += d.toString(); });
+
+  const listening = await waitForListening(fgPort);
+  assert(listening, `server in --fg mode should listen on port ${fgPort}; output: ${fgOutput}`);
+
+  const pidRecord = readPidFile();
+  assert(pidRecord, `PID file at ${PID_FILE} should exist after fg child bound port; output: ${fgOutput}`);
+  assert(pidRecord.pid === fgChild.pid,
+    `PID file should record the foreground child PID (file: ${JSON.stringify(pidRecord)}, child: ${fgChild.pid})`);
+  assert(pidRecord.port === fgPort,
+    `PID file should record the actual port ${fgPort}, got ${pidRecord && pidRecord.port}`);
+
+  fgChild.kill('SIGTERM');
+  await new Promise(resolve => setTimeout(resolve, 400));
+
+  // On Windows, child.kill('SIGTERM') goes through TerminateProcess and skips
+  // Node's exit/SIGTERM handlers, so we can't reliably assert PID file cleanup
+  // here. Instead, verify the bin was responsive while alive and that the
+  // child is gone; the test harness cleans up the PID file at the end.
+  assert(fgChild.killed || fgChild.exitCode !== null, 'foreground child should have exited on kill');
+  removePidFile();
+
+  // Port fallback: bind a port in 5757-5776 range, then start --fg without --port
+  // → CLI should pick the next free port in that range.
+  let busyPort = null;
+  for (let candidate = 5757; candidate < 5757 + 19; candidate++) {
+    if (!(await isPortListening(candidate)) && !(await isPortListening(candidate + 1))) {
+      busyPort = candidate;
+      break;
+    }
+  }
+  assert(busyPort, 'should find a free port in fallback range');
+  const busyServer = net.createServer();
+  await new Promise((resolve, reject) => {
+    busyServer.once('error', reject);
+    busyServer.listen(busyPort, '127.0.0.1', resolve);
+  });
+
+  const fallbackChild = spawn(process.execPath, [BIN, '--fg', '--no-open'], {
+    cwd: ROOT,
+    env: { ...TEST_ENV, KB_SITE_PORT: String(busyPort) },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let fallbackOutput = '';
+  fallbackChild.stdout.on('data', d => { fallbackOutput += d.toString(); });
+  fallbackChild.stderr.on('data', d => { fallbackOutput += d.toString(); });
+
+  // Wait for server to come up on some port.
+  const deadline = Date.now() + 8000;
+  let detectedPort = null;
+  while (Date.now() < deadline && !detectedPort) {
+    const rec = readPidFile();
+    if (rec && rec.port && rec.port !== busyPort) {
+      if (await canConnect(rec.port)) {
+        detectedPort = rec.port;
+        break;
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  assert(detectedPort, `port fallback should pick a free port (output: ${fallbackOutput})`);
+  assert(detectedPort >= 5757 && detectedPort < 5757 + 20,
+    `fallback port ${detectedPort} should be in 5757–${5757 + 19} range`);
+
+  fallbackChild.kill('SIGTERM');
+  await new Promise(resolve => setTimeout(resolve, 400));
+  await new Promise(resolve => busyServer.close(resolve));
+
+  // Unknown flag should exit non-zero
+  const unknown = run(['--bogus']);
+  assert(unknown.status !== 0, 'unknown flag should exit non-zero');
+  assert(/Unknown option/i.test(unknown.stdout + unknown.stderr),
+    `unknown flag output should mention "Unknown option", got: ${unknown.stdout} ${unknown.stderr}`);
+
+  removePidFile();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  console.log('bin-cli-test PASS');
+})().catch(err => {
+  console.error(err && err.stack || err);
+  removePidFile();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  process.exit(1);
+});