@sanqianx/project-knowledge 5.0.5 → 5.0.6

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "project-knowledge",
-      "version": "5.0.5",
+      "version": "5.0.6",
       "source": "./plugins/project-knowledge",
       "description": "Search durable project decisions and implementation history through MCP."
     }

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [5.0.6] - 2026-10-10
+
+- Do not mistake unregistered, abandoned legacy chat records for a knowledge
+  database on first launch. Preserve their bytes without restoring sessions or
+  importing projects; continue rejecting actual old registries and maintenance.
+- Wait for the background server's real HTTP readiness before reporting success
+  or opening the browser. Surface startup failures in the invoking terminal with
+  a nonzero exit code, and name the exact conflicting data entries.
+- Isolate regression data from the user's default data directory. Add a detached
+  npm CLI startup regression from an unrelated working directory.
+
 ## [5.0.5] - 2026-10-10
 
 - Invalidate in-flight registry snapshots after domain creation, project import,

package/_site/_test/claude-workbench-test.js

@@ -9,6 +9,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+const TEST_DATA = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-workbench-unit-'));
+process.env.KB_DATA_DIR = TEST_DATA;
+process.on('exit', () => fs.rmSync(TEST_DATA, { recursive: true, force: true }));
 const runner = require('../lib/claude-cli-runner');
 
 const ROOT = path.resolve(__dirname, '..', '..');

package/_site/_test/fresh-product-data-test.js

@@ -16,6 +16,20 @@ const { connectEngine } = require('../lib/engine-connection');
   assert.equal(fs.readFileSync(path.join(old, 'projects.json'), 'utf8'), bytes);
   const fresh = path.join(root, 'fresh'); initializeProductData(fresh); initializeProductData(fresh);
   assert.equal(JSON.parse(fs.readFileSync(path.join(fresh, 'product-data.json'))).schema, DATA_SCHEMA);
+  const auxiliary = path.join(root, 'auxiliary');
+  const session = path.join(auxiliary, 'runtime', 'claude-sessions', 'unregistered-test', 'session.json');
+  fs.mkdirSync(path.dirname(session), { recursive: true });
+  fs.writeFileSync(session, 'untouched abandoned chat');
+  fs.writeFileSync(path.join(auxiliary, 'launcher.log'), 'old startup failure');
+  initializeProductData(auxiliary);
+  assert.equal(fs.readFileSync(session, 'utf8'), 'untouched abandoned chat');
+  for (const entry of ['claims', 'runs', 'promotions', 'transactions', 'unknown-business-state']) {
+    const pending = path.join(root, entry);
+    fs.mkdirSync(path.join(pending, 'runtime', entry), { recursive: true });
+    fs.writeFileSync(path.join(pending, 'runtime', entry, 'record.json'), '{}');
+    assert.throws(() => initializeProductData(pending), error => error.code === 'SCHEMA_UNSUPPORTED' && error.message.includes(`runtime/${entry}`));
+    assert.equal(fs.existsSync(path.join(pending, 'product-data.json')), false);
+  }
   const paths = [];
   let activationStatus = 403;
   const logs = [];

package/_site/_test/launcher-readiness-test.js

@@ -0,0 +1,80 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const net = require('node:net');
+const { spawn } = require('node:child_process');
+const endpoint = require('../lib/runtime-endpoint');
+
+const packageRoot = process.env.KB_LAUNCHER_TEST_PACKAGE || path.resolve(__dirname, '../..');
+const bin = path.join(packageRoot, 'bin/project-knowledge.js');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-launcher-readiness-'));
+const data = path.join(root, '.project-knowledge-v5');
+const record = path.join(data, 'runtime/claude-sessions/project-a/session.json');
+const recordBytes = JSON.stringify({ schema: 'claude-workbench-session/v1', sessionId: 'old-test', projectSlug: 'project-a', state: 'running', metadata: { automation: true } });
+fs.mkdirSync(path.dirname(record), { recursive: true });
+fs.writeFileSync(record, recordBytes);
+const env = { ...process.env, KB_DATA_DIR: data, KB_MODULES_AUTOSTART: '0', AI_CODING_EVENT_BRIDGE_HOME: path.join(root, 'bridge') };
+let serverPid;
+
+function run(args, overrides = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], { cwd: root, env: { ...env, ...overrides }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`CLI timed out: ${stdout} ${stderr}`)); }, 25000);
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('exit', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+  });
+}
+async function freePort() {
+  const server = net.createServer();
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+
+(async () => {
+  const port = await freePort();
+  const launched = await run(['--no-open'], { KB_SITE_PORT: String(port) });
+  serverPid = endpoint.readEndpoint(data)?.pid;
+  assert.equal(launched.code, 0, launched.stderr);
+  assert.match(launched.stdout, new RegExp(`is ready at http://127.0.0.1:${port}`));
+  assert(serverPid && endpoint.isProcessAlive(serverPid));
+  const response = await fetch(`http://127.0.0.1:${port}/api/state`);
+  assert.equal(response.status, 200, 'ready must mean HTTP is usable, not only a PID exists');
+  const state = await response.json();
+  assert.deepEqual(state.projects, [], 'abandoned sessions must not import projects or enqueue analysis');
+  assert.equal(fs.readFileSync(record, 'utf8'), recordBytes);
+  const again = await run(['--no-open']);
+  assert.equal(again.code, 0);
+  assert.match(again.stdout, /Already running/);
+  const stopped = await run(['stop']);
+  assert.equal(stopped.code, 0);
+  for (let attempt = 0; attempt < 50 && endpoint.isProcessAlive(serverPid); attempt++) await new Promise(resolve => setTimeout(resolve, 100));
+  assert.equal(endpoint.isProcessAlive(serverPid), false);
+  serverPid = null;
+
+  const oldData = path.join(root, 'actual-old-data');
+  fs.mkdirSync(oldData);
+  const original = JSON.stringify({ projectOrder: ['old-project'] });
+  fs.writeFileSync(path.join(oldData, 'projects.json'), original);
+  const failed = await run(['--no-open', '--port', String(port)], { KB_DATA_DIR: oldData });
+  assert.equal(failed.code, 1, 'background failures must return nonzero to the invoking terminal');
+  assert.match(failed.stderr, /启动失败/);
+  assert.match(failed.stderr, /projects\.json/);
+  assert(!/is ready|Listening at/.test(failed.stdout));
+  assert.equal(fs.readFileSync(path.join(oldData, 'projects.json'), 'utf8'), original);
+  assert.equal(fs.existsSync(path.join(oldData, 'product-data.json')), false);
+  const log = fs.readFileSync(path.join(oldData, 'launcher.log'), 'utf8');
+  assert.match(log, /startup failed/);
+  assert(!/Listening at/.test(log), 'never advertise a listener before initialization succeeds');
+  console.log('launcher readiness PASS: unrelated cwd, abandoned records, HTTP readiness, stop, terminal failure, legacy preservation');
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(() => {
+  if (serverPid && endpoint.readEndpoint(data)?.pid === serverPid) {
+    try { process.kill(serverPid); } catch {}
+  }
+});

package/_site/_test/run-all-tests.js

@@ -54,13 +54,15 @@ function runOne(file) {
   // Every test child gets its own Bridge journal sandbox so hook-trigger /
   // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
   const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
+  const dataHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-data-${process.pid}-`));
   const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
     cwd: ROOT,
     encoding: 'utf-8',
     timeout: PER_TEST_TIMEOUT_MS,
-    env: { ...process.env, FORCE_COLOR: '0', AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
+    env: { ...process.env, FORCE_COLOR: '0', KB_DATA_DIR: dataHome, AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
   });
   try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  try { fs.rmSync(dataHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
   const failure = result.status === 0 ? null : classifyFailure(result);
   return {
     file,

package/_site/lib/product-data.js

@@ -5,6 +5,10 @@ const { DomainError } = require('./contracts');
 
 const DATA_SCHEMA = 'project-knowledge/fresh-product-data/v1';
 
+function hasData(file) {
+  return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
+}
+
 function initializeProductData(dataPath) {
   const marker = path.join(dataPath, 'product-data.json');
   if (fs.existsSync(marker)) {
@@ -13,11 +17,18 @@ function initializeProductData(dataPath) {
     return;
   }
   // Old registries and unfinished claims must never become fresh product work.
-  const oldData = ['settings.json', 'projects.json', 'projects', 'runtime', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json'].some(name => {
-    const file = path.join(dataPath, name);
-    return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
-  });
-  if (oldData) throw new DomainError('SCHEMA_UNSUPPORTED', '不再迁移旧版知识库数据。请取消旧 KB_DATA_DIR 设置，或指定新的空数据目录，然后重新导入项目。', { status: 409 });
+  const oldData = ['settings.json', 'projects.json', 'projects', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json']
+    .filter(name => hasData(path.join(dataPath, name)));
+  const runtimePath = path.join(dataPath, 'runtime');
+  if (fs.existsSync(runtimePath)) {
+    if (!fs.statSync(runtimePath).isDirectory()) oldData.push('runtime');
+    else for (const name of fs.readdirSync(runtimePath)) {
+      // Unregistered legacy chat records cannot be resumed by a fresh registry.
+      // They are neither knowledge nor pending maintenance, and stay untouched.
+      if (name !== 'claude-sessions' && hasData(path.join(runtimePath, name))) oldData.push(`runtime/${name}`);
+    }
+  }
+  if (oldData.length) throw new DomainError('SCHEMA_UNSUPPORTED', `数据目录 ${dataPath} 包含旧版业务数据（${oldData.join('、')}）。新版不会迁移或删除它们；请将 KB_DATA_DIR 指向新的空目录，然后重新导入项目。`, { status: 409, details: { dataPath, entries: oldData } });
   AtomicFile.writeJsonAtomic(marker, { schema: DATA_SCHEMA, createdAt: new Date().toISOString() });
 }
 

package/_site/server.js

@@ -3,10 +3,13 @@ const { startServer, installProcessHandlers } = require('./lib/server-app');
 
 const instancePromise = startServer();
 installProcessHandlers(instancePromise);
+module.exports = instancePromise;
 
 instancePromise.then(instance => {
   process.stdout.write(`Project Knowledge listening on http://${instance.host}:${instance.port}\n`);
 }).catch(error => {
-  process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
-  process.exitCode = 1;
+  if (require.main === module) {
+    process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
+    process.exitCode = 1;
+  }
 });

package/bin/project-knowledge.js

@@ -6,7 +6,7 @@
 
 const path = require('path');
 const { spawn, spawnSync, exec, execSync } = require('child_process');
-const { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync } = require('fs');
+const { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync, closeSync } = require('fs');
 const net = require('net');
 const os = require('os');
 const { getDataDir } = require('../_site/lib/data-dir');
@@ -71,6 +71,33 @@ function openBrowser(url) {
   try { exec(cmd); } catch { /* best-effort */ }
 }
 
+function notifyLauncher(message) {
+  if (process.connected && typeof process.send === 'function') process.send(message);
+}
+
+function waitForStartup(child, logPath) {
+  return new Promise((resolve, reject) => {
+    const finish = (error, value) => {
+      clearTimeout(timer);
+      child.removeListener('message', onMessage);
+      child.removeListener('error', onError);
+      child.removeListener('exit', onExit);
+      if (child.connected) child.disconnect();
+      if (error) reject(error); else resolve(value);
+    };
+    const onMessage = message => {
+      if (message && message.type === 'kb:launcher-ready') finish(null, message);
+      else if (message && message.type === 'kb:launcher-failed') finish(new Error(message.message));
+    };
+    const onError = error => finish(error);
+    const onExit = code => finish(new Error(`后台进程在启动完成前退出（${code}）。请查看 ${logPath}`));
+    const timer = setTimeout(() => finish(new Error(`启动尚未完成，请运行 project-knowledge status 并查看 ${logPath}`)), 45000);
+    child.on('message', onMessage);
+    child.once('error', onError);
+    child.once('exit', onExit);
+  });
+}
+
 function isPortFree(port, host = '127.0.0.1') {
   return new Promise((resolve) => {
     const tester = net.createServer();
@@ -259,7 +286,7 @@ Options:
   -v, --version       Print version and exit
   -h, --help          Show this help message
 
-Runtime data lives next to the npm global root; PID file at ${PID_FILE}.
+Runtime data: ${DATA_DIR}; PID file at ${PID_FILE}.
 `);
   process.exit(0);
 }
@@ -357,28 +384,44 @@ if (!foreground) {
     mkdirSync(path.dirname(LAUNCH_LOG), { recursive: true });
     logFd = openSync(LAUNCH_LOG, 'a');
   } catch { /* best-effort: fall back to discarding output */ }
-  const stdio = logFd == null ? 'ignore' : ['ignore', logFd, logFd];
+  const stdio = ['ignore', logFd == null ? 'ignore' : logFd, logFd == null ? 'ignore' : logFd, 'ipc'];
 
   const child = spawn(
     process.execPath,
     [...process.argv.slice(1), '--fg', ...forwarded],
     { detached: true, stdio, windowsHide: true }
   );
+  if (logFd != null) closeSync(logFd);
   child.unref();
 
   console.log('project-knowledge starting in background');
   console.log(`Diagnostics: ${LAUNCH_LOG}`);
-  console.log(`Use "project-knowledge status" to check, "project-knowledge stop" to stop.`);
-  process.exit(0);
+  waitForStartup(child, LAUNCH_LOG).then(ready => {
+    console.log(`project-knowledge is ready at ${ready.url}`);
+    console.log(`Use "project-knowledge status" to check, "project-knowledge stop" to stop.`);
+    process.exit(0);
+  }).catch(error => {
+    console.error(`启动失败：${error.message}`);
+    console.error(`Diagnostics: ${LAUNCH_LOG}`);
+    process.exit(1);
+  });
+} else {
+  main().catch((err) => {
+    console.error(`[project-knowledge] startup failed: ${err.message}`);
+    notifyLauncher({ type: 'kb:launcher-failed', message: err.message });
+    removePid(process.pid);
+    runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
+    process.exitCode = 1;
+  });
 }
 
-// ── Foreground: start server ──
-process.env.KB_SITE_HOST = host;
-
 async function main() {
+  process.env.KB_SITE_HOST = host;
   const existingEndpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
   if (existingEndpoint && existingEndpoint.pid !== process.pid) {
-    console.log(`Already running (PID ${existingEndpoint.pid}) at http://${existingEndpoint.host}:${existingEndpoint.port}`);
+    const url = `http://${existingEndpoint.host}:${existingEndpoint.port}`;
+    console.log(`Already running (PID ${existingEndpoint.pid}) at ${url}`);
+    notifyLauncher({ type: 'kb:launcher-ready', url, pid: existingEndpoint.pid, port: existingEndpoint.port });
     process.exit(0);
   }
   const actualPort = portExplicit ? port : await findFreePort(port, host);
@@ -393,7 +436,9 @@ async function main() {
   if (!claim.claimed) {
     const active = claim.endpoint;
     if (active) {
-      console.log(`Already running (PID ${active.pid}) at http://${active.host}:${active.port}`);
+      const url = `http://${active.host}:${active.port}`;
+      console.log(`Already running (PID ${active.pid}) at ${url}`);
+      notifyLauncher({ type: 'kb:launcher-ready', url, pid: active.pid, port: active.port });
     } else {
       console.error('Another project-knowledge process is starting. Please try again in a moment.');
     }
@@ -405,35 +450,22 @@ async function main() {
     runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
   };
   process.on('exit', cleanup);
-  process.on('SIGINT', () => { cleanup(); process.exit(0); });
-  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
-  // Windows console-close sends SIGBREAK; Node doesn't run exit handlers after
-  // a forceful TerminateProcess, but SIGBREAK does fire before the process is
-  // torn down, so we can still clean up here.
-  if (process.platform === 'win32') {
-    process.on('SIGBREAK', () => { cleanup(); process.exit(0); });
-  }
 
-  const url = `http://localhost:${actualPort}`;
+  const url = `http://${host === '::1' ? '[::1]' : host}:${actualPort}`;
   if (actualPort !== port) {
     console.log(`(Port ${port} was busy, using ${actualPort} instead)`);
   }
   console.log(`project-knowledge ${pkg.version}`);
-  console.log(`Listening at ${url}`);
   // Resolve data dir the same way server.js will, so we can show the user
   // where their config and KB files live BEFORE the server boots.
   try {
     console.log(`Data dir: ${getDataDir()}`);
   } catch {}
 
-  require(path.join(__dirname, '..', '_site', 'server.js'));
+  const instance = await require(path.join(__dirname, '..', '_site', 'server.js'));
+  if (process.platform === 'win32') process.once('SIGBREAK', () => instance.stop('SIGBREAK').then(() => { process.exitCode = 0; }));
+  console.log(`Listening at ${url}`);
+  notifyLauncher({ type: 'kb:launcher-ready', url, pid: process.pid, port: actualPort });
 
   if (shouldOpen) setTimeout(() => openBrowser(url), 500);
 }
-
-main().catch((err) => {
-  console.error(err.message);
-  removePid(process.pid);
-  runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
-  process.exit(1);
-});

package/docs/fresh-v5-start.md

@@ -13,6 +13,8 @@ project-knowledge
 
 需要 Node ≥22 和 Git。默认使用 `~/.project-knowledge-v5`，四模块的托管数据也在此目录内。若环境变量 `KB_DATA_DIR` 仍指向旧目录，请取消该设置或改为新的空目录。不要把旧 `projects.json`、设置或引擎状态复制进新目录。
 
+5.0.6 修复首次启动被未登记的旧工作台会话误拦截：仅有日志、默认提示词及孤立会话的目录可以创建空的新登记，孤立会话保留原字节但不会恢复或触发任务。实际旧项目、设置、引擎状态或维护任务仍拒绝迁移，错误列出具体目录和冲突项。后台启动命令等待 HTTP 就绪后才报成功；启动失败直接在终端显示原因并返回非零退出码，不提前打开浏览器。
+
 在“系统状态”重新配置模型与后台默认模型、embedding 和知识根目录，然后在“领域与项目”导入代码目录及新的空知识目录。原代码目录无需移动。若残留旧知识库托管 Hook，导入预检会要求明确确认替换；不会覆盖第三方 Hook。导入建立 HEAD 基线，不分析已有历史。
 
 如果模块是自己独立启动的旧进程，请在它原来的终端中停止后重启新版外壳。外壳不会擅自杀死其他服务；版本或运行期鉴权不一致时显示具体连接阶段，不接管旧服务数据。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {

package/plugins/project-knowledge/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "project-knowledge",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "project-knowledge",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.mcp.json

@@ -6,7 +6,7 @@
       "args": [
         "-y",
         "--package",
-        "@sanqianx/project-knowledge@5.0.5",
+        "@sanqianx/project-knowledge@5.0.6",
         "project-knowledge-mcp"
       ]
     }