@sanqianx/project-knowledge 4.6.1

package/_site/_test/ai-profile-test.js

@@ -0,0 +1,75 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7795;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-ai-v2-'));
+
+async function request(method, pathname, body) {
+  const response = await fetch(`${BASE}${pathname}`, {
+    method,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: response.status, text: await response.text() };
+}
+
+async function json(method, pathname, body) {
+  const result = await request(method, pathname, body);
+  return { ...result, data: JSON.parse(result.text || '{}') };
+}
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+(async () => {
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'ai-profile-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    let result = await json('PUT', '/api/ai-profiles', {
+      schema: 'ai-profiles/v1', defaultProfileId: 'secure', profiles: [{
+        id: 'secure', name: 'Secure', enabled: true, implementation: 'claude-code-agent', apiKeyUpdate: { mode: 'replace', value: 'sk-secret-1234' },
+      }],
+    });
+    assert.strictEqual(result.status, 200, result.text);
+    assert.strictEqual(result.data.config.profiles[0].hasApiKey, true);
+    assert.strictEqual(result.data.config.profiles[0].apiKeyMasked, '****1234');
+    assert(!result.text.includes('sk-secret-1234'));
+
+    result = await json('GET', '/api/ai-profiles');
+    assert.strictEqual(result.status, 200);
+    assert(!result.text.includes('sk-secret-1234'));
+    assert(!/"apiKey"\s*:/.test(result.text));
+
+    result = await json('PUT', '/api/ai-profiles', {
+      schema: 'ai-profiles/v1', defaultProfileId: 'secure', profiles: [{ id: 'secure', name: 'Renamed', enabled: true, implementation: 'claude-code-agent', apiKeyUpdate: { mode: 'preserve' } }],
+    });
+    assert.strictEqual(result.status, 200);
+    let settings = JSON.parse(fs.readFileSync(path.join(dataDir, 'settings.json'), 'utf8'));
+    assert.strictEqual(settings.ai.profiles[0].apiKey, 'sk-secret-1234');
+
+    result = await json('PUT', '/api/ai-profiles', {
+      schema: 'ai-profiles/v1', defaultProfileId: 'secure', profiles: [{ id: 'secure', name: 'Renamed', enabled: true, implementation: 'claude-code-agent', apiKeyUpdate: { mode: 'clear' } }],
+    });
+    assert.strictEqual(result.status, 200);
+    settings = JSON.parse(fs.readFileSync(path.join(dataDir, 'settings.json'), 'utf8'));
+    assert(!Object.prototype.hasOwnProperty.call(settings.ai.profiles[0], 'apiKey'));
+
+    result = await json('PUT', '/api/ai-profiles', { profiles: [{ id: '../bad', apiKeyUpdate: { mode: 'clear' } }] });
+    assert.strictEqual(result.status, 400);
+    assert.strictEqual(result.data.error.code, 'INVALID_ARGUMENT');
+    assert(!Object.prototype.hasOwnProperty.call(result.data.error, 'stack'));
+    console.log('ai-profile-test PASS');
+  } finally {
+    await spawned.cleanup();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/ai-vendor-presets-test.js

@@ -0,0 +1,91 @@
+// Tests for ai-vendor-presets: 4 vendors with full fields, name/id lookup.
+
+const { AI_VENDOR_PRESETS, listVendorPresetNames, findVendorPresetByName } = require('../lib/ai-vendor-presets');
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+(() => {
+  try {
+    // 1. Exactly 4 vendors
+    assert(Array.isArray(AI_VENDOR_PRESETS), 'AI_VENDOR_PRESETS should be an array');
+    assert(AI_VENDOR_PRESETS.length === 4, `expected 4 vendors, got ${AI_VENDOR_PRESETS.length}`);
+
+    // 2. IDs unique and match the expected set
+    const ids = AI_VENDOR_PRESETS.map(v => v.id).sort();
+    assert(JSON.stringify(ids) === JSON.stringify(['anthropic', 'deepseek', 'minimax', 'zhipu']),
+      `vendor ids should be anthropic/deepseek/minimax/zhipu, got ${JSON.stringify(ids)}`);
+
+    // 3. Every preset has the required fields
+    const required = ['id', 'name', 'baseUrl', 'mainModel', 'thinkingModel',
+                      'haikuModel', 'sonnetModel', 'opusModel', 'contextWindow', 'website'];
+    for (const v of AI_VENDOR_PRESETS) {
+      for (const f of required) {
+        assert(v[f] !== undefined && v[f] !== null && v[f] !== '',
+          `vendor ${v.id} missing or empty field: ${f}`);
+      }
+    }
+
+    // 4. baseUrl: https://, no trailing slash
+    for (const v of AI_VENDOR_PRESETS) {
+      assert(/^https?:\/\//.test(v.baseUrl), `${v.id} baseUrl must start with http(s)://`);
+      assert(!/\/$/.test(v.baseUrl), `${v.id} baseUrl must NOT have trailing slash`);
+    }
+
+    // 5. contextWindow is a positive integer
+    for (const v of AI_VENDOR_PRESETS) {
+      assert(Number.isInteger(v.contextWindow) && v.contextWindow > 0,
+        `${v.id} contextWindow must be a positive integer, got ${v.contextWindow}`);
+    }
+
+    // 6. Specific known values
+    const minimax = findVendorPresetByName('MiniMax');
+    assert(minimax && minimax.baseUrl === 'https://api.minimaxi.com/anthropic',
+      `minimax baseUrl wrong: ${minimax && minimax.baseUrl}`);
+    assert(minimax && minimax.mainModel === 'MiniMax-M3',
+      `minimax mainModel wrong: ${minimax && minimax.mainModel}`);
+    assert(minimax && minimax.contextWindow === 1048576,
+      `minimax contextWindow should be 1M`);
+
+    const anthropic = findVendorPresetByName('Anthropic Claude');
+    assert(anthropic && anthropic.baseUrl === 'https://api.anthropic.com',
+      `anthropic baseUrl wrong`);
+    assert(anthropic && anthropic.contextWindow === 200000,
+      `anthropic contextWindow should be 200K`);
+
+    const zhipu = findVendorPresetByName('智谱 GLM');
+    assert(zhipu && zhipu.baseUrl === 'https://open.bigmodel.cn/api/anthropic',
+      `zhipu baseUrl wrong: ${zhipu && zhipu.baseUrl}`);
+
+    const deepseek = findVendorPresetByName('DeepSeek');
+    assert(deepseek && deepseek.baseUrl === 'https://api.deepseek.com/anthropic',
+      `deepseek baseUrl wrong: ${deepseek && deepseek.baseUrl}`);
+    assert(deepseek && deepseek.mainModel === 'deepseek-chat',
+      `deepseek mainModel wrong`);
+    assert(deepseek && deepseek.thinkingModel === 'deepseek-reasoner',
+      `deepseek thinkingModel wrong`);
+
+    // 7. Case-insensitive lookup by name
+    assert(findVendorPresetByName('minimax').id === 'minimax', 'lowercase name lookup');
+    assert(findVendorPresetByName('MINIMAX').id === 'minimax', 'uppercase name lookup');
+
+    // 8. Lookup by id also works
+    assert(findVendorPresetByName('minimax').id === 'minimax', 'id lookup');
+
+    // 9. Unknown / empty / null returns null (no false positive)
+    assert(findVendorPresetByName('Totally Unknown Vendor') === null, 'unknown vendor → null');
+    assert(findVendorPresetByName('') === null, 'empty name → null');
+    assert(findVendorPresetByName(null) === null, 'null name → null');
+    assert(findVendorPresetByName(undefined) === null, 'undefined name → null');
+
+    // 10. listVendorPresetNames returns all 4 names in stable order
+    const names = listVendorPresetNames();
+    assert(names.length === 4, `expected 4 names, got ${names.length}`);
+    assert(names.every(n => typeof n === 'string' && n.length > 0),
+      'all names should be non-empty strings');
+
+    console.log('ai-vendor-presets test passed');
+  } catch (e) {
+    console.error('ai-vendor-presets test failed:', e.message);
+    process.exitCode = 1;
+  }
+})();

package/_site/_test/automation-queue-test.js

@@ -0,0 +1,14 @@
+// Run: node _site/_test/automation-queue-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const automation = require('../lib/post-commit-automation');
+
+(() => {
+  assert.strictEqual(fs.existsSync(path.join(__dirname, '..', 'lib', 'automation-queue.js')), false, 'legacy in-memory automation queue must be deleted');
+  assert.strictEqual(fs.existsSync(path.join(__dirname, '..', 'lib', 'commit-automation-store.js')), false, 'legacy commit automation state must not remain a second pending authority');
+  assert.strictEqual(typeof automation.reconcileProjectCommits, 'function', 'Git-backed reconciler should be the single automation authority');
+  assert.strictEqual(Object.hasOwn(automation, 'dispatchPendingAutomations'), false, 'startup must not dispatch pending commit analysis');
+  console.log('automation-queue-test PASS');
+})();

package/_site/_test/automation-ui-test.js

@@ -0,0 +1,40 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const html = fs.readFileSync(path.join(ROOT, 'ui', 'index.html'), 'utf8');
+const app = fs.readFileSync(path.join(ROOT, 'ui', 'app.js'), 'utf8');
+const server = fs.readFileSync(path.join(ROOT, '_site', 'lib', 'server-app.js'), 'utf8');
+
+assert.strictEqual((html.match(/class="shell"/g) || []).length, 1, 'production UI must have one full product shell');
+assert.strictEqual((html.match(/id="settings-logs"/g) || []).length, 1, 'production UI must have one Settings logs section');
+assert(html.includes('id="view-terminal"') && html.includes('id="view-search"') && html.includes('id="view-import"'), 'Terminal, Search and Import must remain reachable');
+
+const forbiddenUi = [
+  /\/api\/projects\/[^"' ]+\/hook/,
+  /\/api\/projects\/[^"' ]+\/analy/,
+  /\/api\/projects\/[^"' ]+\/scan/,
+  /\/api\/projects\/[^"' ]+\/init/,
+  /simulate/i,
+  /installHook\s*\(/,
+  /uninstallHook\s*\(/,
+  /reinstallHook\s*\(/,
+  /manual analysis/i,
+];
+for (const pattern of forbiddenUi) assert(!pattern.test(html + app), 'removed manual automation control/call remains: ' + pattern);
+
+for (const route of [
+  '/api/projects/:projectId/hook/install',
+  '/api/projects/:projectId/hook/uninstall',
+  '/api/projects/:projectId/analyze/initial',
+  '/api/projects/:projectId/analyze/incremental',
+  '/api/projects/:projectId/simulate',
+]) {
+  assert(!server.includes(route), 'removed backend route remains: ' + route);
+}
+
+assert(!html.includes('vue.global.prod.js'), 'product shell must not require the old Vue runtime');
+assert(!html.includes('tailwind-browser.js'), 'product shell must not require the old browser Tailwind runtime');
+
+console.log('automation UI test PASS');

package/_site/_test/background-task-registry-test.js

@@ -0,0 +1,43 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { activeTaskPromises, isProjectBusy, taskForProject } = require('../lib/server-app');
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+
+(async () => {
+  const records = [];
+  const runtime = {
+    activeTasks: new Map(),
+    logger: {
+      async debug(event, message, context) { records.push({ level: 'debug', event, message, ...context }); },
+      async error(event, message, context) { records.push({ level: 'error', event, message, ...context }); },
+    },
+  };
+  const longGate = deferred();
+  const long = taskForProject(runtime, 'project-a', 'op-long', () => longGate.promise, 'startup');
+  const fast = taskForProject(runtime, 'project-a', 'op-fast', async () => { throw new Error('fast failure'); }, 'git-hook');
+  assert.strictEqual(runtime.activeTasks.get('project-a').size, 2, 'overlapping operations must both remain registered');
+  assert.strictEqual(activeTaskPromises(runtime.activeTasks).length, 2, 'shutdown snapshot must include every operation promise');
+  assert.strictEqual(isProjectBusy('project-a', { readState: () => ({ analysis: { activeClaim: null } }) }, runtime.activeTasks), true);
+  await assert.rejects(fast, /fast failure/);
+  assert.strictEqual(runtime.activeTasks.get('project-a').size, 1, 'fast terminal must remove only its own operation');
+  assert(runtime.activeTasks.get('project-a').has('op-long'));
+  assert.strictEqual(activeTaskPromises(runtime.activeTasks).length, 1);
+  longGate.resolve('done');
+  assert.strictEqual(await long, 'done');
+  assert.strictEqual(runtime.activeTasks.has('project-a'), false, 'empty project task map must be removed');
+  assert(records.some(record => record.event === 'background.operation_failed' && record.operationId === 'op-fast'));
+  assert(records.some(record => record.event === 'background.operation_completed' && record.operationId === 'op-long'));
+
+  console.log('background-task-registry-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/baseline-schema-test.js

@@ -0,0 +1,91 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { makeRepo } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7791;
+const BASE = 'http://127.0.0.1:' + PORT;
+
+async function json(method, pathname, body) {
+  const response = await fetch(BASE + pathname, {
+    method,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { response, body: await response.json() };
+}
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 150; attempt += 1) {
+    try { if ((await fetch(BASE + '/api/health')).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('v2 baseline server did not start');
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-baseline-v2-'));
+  const knowledgeRoot = path.join(dataDir, 'knowledge-root');
+  const repo = makeRepo({ kind: 'one-commit' });
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'baseline-v2', stdio: 'ignore' });
+  try {
+    await waitForServer();
+    let result = await json('GET', '/api/state');
+    assert.strictEqual(result.response.status, 200);
+    assert.strictEqual(result.body.schema, 'server-state/v2');
+    assert.strictEqual(result.body.settings.schema, 'settings/v2');
+    assert.deepStrictEqual(result.body.projects, []);
+
+    result = await json('PATCH', '/api/settings', { knowledge: { rootPath: knowledgeRoot } });
+    assert.strictEqual(result.response.status, 200);
+
+    result = await json('POST', '/api/projects/import', { localPath: repo.path, displayName: 'Baseline v2' });
+    assert.strictEqual(result.response.status, 201, JSON.stringify(result.body));
+    const projectId = result.body.projectId;
+    const project = result.body.project;
+    assert.strictEqual(project.config.schema, 'project-config/v2');
+    assert.strictEqual(project.state.schema, 'project-state/v2');
+    assert.strictEqual(project.config.projectId, projectId);
+    assert.strictEqual(project.state.trackingStartCommit, repo.headCommit);
+    assert.strictEqual(project.state.lastAnalyzedCommit, null);
+    assert.strictEqual(project.state.analysis.status, 'idle');
+    assert.strictEqual(project.state.hook.managedVersion, 2);
+    assert(path.isAbsolute(project.config.repoPath) && path.isAbsolute(project.config.knowledgePath));
+    assert(project.config.knowledgePath.startsWith(path.resolve(knowledgeRoot)));
+    assert.deepStrictEqual(fs.readdirSync(project.config.knowledgePath), []);
+
+    const registry = JSON.parse(fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8'));
+    assert.strictEqual(registry.schema, 'project-registry/v2');
+    assert.deepStrictEqual(registry.projectOrder, [projectId]);
+    assert.deepStrictEqual(Object.keys(registry.projects), [projectId]);
+    assert(!Object.prototype.hasOwnProperty.call(registry.projects[projectId], 'lastAnalyzedCommit'));
+
+    result = await json('GET', '/api/projects');
+    assert.strictEqual(result.response.status, 200);
+    assert.strictEqual(result.body.projects.length, 1);
+    assert.strictEqual(result.body.projects[0].projectId, projectId);
+
+    const htmlResponse = await fetch(BASE + '/');
+    const html = await htmlResponse.text();
+    assert.strictEqual(htmlResponse.status, 200);
+    assert.strictEqual((html.match(/class="shell"/g) || []).length, 1);
+    assert.strictEqual((html.match(/id="settings-logs"/g) || []).length, 1);
+    assert(!html.includes('vue.global.prod.js'));
+
+    result = await json('DELETE', '/api/projects/' + encodeURIComponent(projectId), { deleteKnowledge: false });
+    assert.strictEqual(result.response.status, 200);
+    assert.strictEqual(fs.existsSync(project.config.knowledgePath), true, 'default delete must preserve external knowledge');
+    assert.strictEqual(fs.existsSync(path.join(repo.path, '.git', 'hooks', 'post-commit')), false);
+
+    console.log('baseline schema test PASS');
+  } finally {
+    await spawned.cleanup();
+    repo.cleanup();
+  }
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,218 @@
+// 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 PID_FILE = path.join(os.tmpdir(), '.project-knowledge.pid');
+const ISOLATED_STATUS_PORT = 19000 + (process.pid % 1000);
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-${process.pid}-`));
+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;
+    const lines = fs.readFileSync(PID_FILE, 'utf-8').trim().split('\n');
+    return { pid: parseInt(lines[0], 10), port: lines[1] ? parseInt(lines[1], 10) : null };
+  } 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 isPortListening(port)) return true;
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  return 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 isPortListening(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);
+});