@sanqianx/project-knowledge 4.6.1

package/_site/_test/index-writer-concurrency-test.js

@@ -0,0 +1,135 @@
+// Run: node _site/_test/index-writer-concurrency-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { IndexService } = require('../lib/index-service');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-index-writer-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+
+async function addProject(projectId) {
+  const knowledgePath = path.join(temp, 'knowledge', projectId);
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  fs.writeFileSync(path.join(knowledgePath, 'README.md'), `# ${projectId}\n\nMarkdown remains authoritative.\n`, 'utf8');
+  await projects.create(projectId, {
+    displayName: projectId,
+    storageName: projectId,
+    repoPath: path.join(temp, 'repos', projectId),
+    knowledgePath,
+  });
+  await registry.add(projectId, { displayName: projectId });
+  await markDirty(projectId, `commit-${projectId}`);
+}
+
+async function markDirty(projectId, commitSha) {
+  await projects.updateState(projectId, state => {
+    state.index.dirty = true;
+    state.index.sinceCommit = state.index.sinceCommit || commitSha;
+    state.index.generation += 1;
+  });
+}
+
+(async () => {
+  await registry.initialize();
+  await addProject('project-a');
+  await addProject('project-b');
+  let active = 0;
+  let maxActive = 0;
+  const calls = [];
+  let releaseFirst;
+  let firstStarted;
+  const firstStart = new Promise(resolve => { firstStarted = resolve; });
+  const firstGate = new Promise(resolve => { releaseFirst = resolve; });
+  const adapter = {
+    async indexProject(input) {
+      active += 1;
+      maxActive = Math.max(maxActive, active);
+      calls.push({ projectId: input.projectId, generation: input.generation });
+      if (input.projectId === 'project-a' && calls.filter(call => call.projectId === 'project-a').length === 1) {
+        firstStarted();
+        await firstGate;
+      }
+      await new Promise(resolve => setTimeout(resolve, 20));
+      active -= 1;
+      return { indexed: true };
+    },
+  };
+  const service = new IndexService({ layout, registryStore: registry, projectStore: projects, adapter });
+  const firstA = service.enqueue('project-a');
+  await firstStart;
+  await markDirty('project-a', 'commit-new-during-index');
+  const coalescedA = service.enqueue('project-a');
+  const firstB = service.enqueue('project-b');
+  releaseFirst();
+  await Promise.all([firstA, coalescedA, firstB]);
+  assert.strictEqual(maxActive, 1, 'all index mutations must share one process-global writer');
+  assert.strictEqual(calls.filter(call => call.projectId === 'project-a').length, 2, 'new generation during an old write must be indexed again');
+  assert.strictEqual(projects.readState('project-a').index.dirty, false);
+  assert.strictEqual(projects.readState('project-b').index.dirty, false);
+  const sourceManifest = JSON.parse(fs.readFileSync(layout.getRuntimePath('index-sources', 'project-a.json'), 'utf8'));
+  assert.strictEqual(sourceManifest.schema, 'knowledge-index-source-manifest/v1');
+  assert(sourceManifest.entries['README.md'].documentHash, 'successful indexing must persist the authoritative source document hash');
+  assert.strictEqual(sourceManifest.generation, projects.readState('project-a').index.generation);
+
+  await markDirty('project-b', 'commit-index-failure');
+  let fail = true;
+  const retryService = new IndexService({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    adapter: {
+      indexProject: async () => {
+        if (fail) { fail = false; throw new Error('injected index failure'); }
+        return { indexed: true };
+      },
+    },
+  });
+  const failed = await retryService.enqueue('project-b');
+  assert.strictEqual(failed.ok, false);
+  const failedState = projects.readState('project-b');
+  assert.strictEqual(failedState.index.dirty, true, 'index failure must keep dirty state');
+  assert(failedState.index.lastError && failedState.index.lastError.message.includes('injected'));
+  assert(fs.existsSync(path.join(projects.readConfig('project-b').knowledgePath, 'README.md')), 'index failure must not remove truthful Markdown');
+  const retried = await retryService.enqueue('project-b');
+  assert.strictEqual(retried.ok, true);
+  assert.strictEqual(projects.readState('project-b').index.dirty, false);
+
+  const indexPath = layout.getIndexPath();
+  fs.mkdirSync(indexPath, { recursive: true });
+  fs.writeFileSync(path.join(indexPath, 'marker.txt'), 'old-index', 'utf8');
+  let validationOk = false;
+  const rebuildService = new IndexService({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    adapter: {
+      indexProject: async () => ({}),
+      buildFull: async ({ targetPath }) => {
+        fs.mkdirSync(targetPath, { recursive: true });
+        fs.writeFileSync(path.join(targetPath, 'marker.txt'), 'new-index', 'utf8');
+      },
+      validateIndex: async targetPath => ({ ok: validationOk, marker: fs.readFileSync(path.join(targetPath, 'marker.txt'), 'utf8') }),
+    },
+  });
+  await assert.rejects(rebuildService.fullRebuild(), error => error.code === 'DATA_CORRUPT');
+  assert.strictEqual(fs.readFileSync(path.join(indexPath, 'marker.txt'), 'utf8'), 'old-index', 'failed rebuild validation must retain the live DB');
+  validationOk = true;
+  const rebuilt = await rebuildService.fullRebuild();
+  assert.strictEqual(fs.readFileSync(path.join(indexPath, 'marker.txt'), 'utf8'), 'new-index');
+  assert(rebuilt.backup && fs.readFileSync(path.join(rebuilt.backup, 'marker.txt'), 'utf8') === 'old-index', 'successful swap should retain a recovery copy of the old DB');
+
+  await IndexService.flush();
+  console.log('index-writer-concurrency-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/integration-adapters-test.js

@@ -0,0 +1,243 @@
+// Run: node _site/_test/integration-adapters-test.js
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  IntegrationManager,
+  removeOpenCodeMcpConfig,
+  removeOpenCodeInstructionConfig,
+} = require('../lib/integration-installer');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `project-knowledge-integrations-${process.pid}-`));
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+async function main() {
+  const packageInfo = readJson(path.join(ROOT, 'package.json'));
+  const pluginRoot = path.join(ROOT, 'plugins', 'project-knowledge');
+  const claudeManifest = readJson(path.join(pluginRoot, '.claude-plugin', 'plugin.json'));
+  const codexManifest = readJson(path.join(pluginRoot, '.codex-plugin', 'plugin.json'));
+  const mcpManifest = readJson(path.join(pluginRoot, '.mcp.json'));
+  const claudeMarketplace = readJson(path.join(ROOT, '.claude-plugin', 'marketplace.json'));
+  const codexMarketplace = readJson(path.join(ROOT, '.agents', 'plugins', 'marketplace.json'));
+  const skillPath = path.join(pluginRoot, 'skills', 'project-knowledge', 'SKILL.md');
+  const skill = fs.readFileSync(skillPath, 'utf8');
+
+  assert(claudeManifest.version === packageInfo.version, 'Claude plugin version should match the npm package');
+  assert(codexManifest.version === packageInfo.version, 'Codex plugin version should match the npm package');
+  assert(claudeMarketplace.plugins[0].version === packageInfo.version, 'Claude marketplace version should match the npm package');
+  assert(codexMarketplace.name === 'project-knowledge', 'Codex marketplace should have a stable public name');
+  assert(codexMarketplace.plugins[0].source.path === './plugins/project-knowledge', 'Codex marketplace should point at the shared plugin');
+  assert(mcpManifest.mcpServers['project-knowledge'].args.includes(`project-knowledge@${packageInfo.version}`), 'plugin MCP should pin the matching package version');
+  assert(!skill.includes('[TODO:'), 'bundled Skill should not contain scaffold placeholders');
+  assert(skill.includes('project_knowledge_resolve'), 'bundled Skill should teach the resolve-first workflow');
+  assert(skill.includes('project_knowledge_record_requirement'), 'bundled Skill should document the explicit supplemental adapter');
+  assert(skill.includes('only when the user explicitly requests supplemental capture'), 'bundled Skill must not make cooperative requirement recording mandatory');
+  assert(!/Before implementing a user request, call `project_knowledge_record_requirement`/.test(skill), 'automatic capture must remain primary');
+
+  const calls = [];
+  const homeDir = path.join(TEMP, 'home');
+  const manager = new IntegrationManager({
+    rootDir: ROOT,
+    homeDir,
+    env: {},
+    commandResolver: name => name,
+    runner: (command, args) => {
+      calls.push({ command, args });
+      return { status: 0, stdout: '', stderr: '' };
+    },
+  });
+  const openCodeResult = await manager.operate('install', ['opencode']);
+  assert(openCodeResult[0].ok, 'OpenCode installation should complete');
+  assert(fs.existsSync(path.join(homeDir, '.config', 'opencode', 'skills', 'project-knowledge', 'SKILL.md')), 'OpenCode should receive the global Skill');
+  const installedInstruction = path.join(homeDir, '.config', 'opencode', 'instructions', 'project-knowledge.md');
+  assert(fs.existsSync(installedInstruction), 'OpenCode should receive the global Instructions file');
+  const installedConfig = fs.readFileSync(path.join(homeDir, '.config', 'opencode', 'opencode.jsonc'), 'utf8');
+  assert(installedConfig.includes(installedInstruction.replace(/\\/g, '\\\\')), 'OpenCode config should reference the installed Instructions file');
+  const openCodeCall = calls.find(call => call.command === 'opencode');
+  assert(openCodeCall?.args.join(' ') === `mcp add project-knowledge -- npx -y --package project-knowledge@${packageInfo.version} project-knowledge-mcp`, 'OpenCode should receive the versioned MCP command');
+
+  const configDir = path.join(TEMP, 'opencode-config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const configPath = path.join(configDir, 'opencode.jsonc');
+  fs.writeFileSync(configPath, `{
+  // Keep this user comment.
+  "instructions": [
+    "C:\\\\keep\\\\team-rules.md",
+    "${path.join(configDir, 'instructions', 'project-knowledge.md').replace(/\\/g, '\\\\')}"
+  ],
+  "mcp": {
+    "project-knowledge": { "type": "local", "command": ["npx"] },
+    "other": { "type": "remote", "url": "https://example.test/mcp" }
+  }
+}
+`, 'utf8');
+  assert(removeOpenCodeMcpConfig(configDir), 'OpenCode uninstall should remove its MCP entry');
+  const updatedConfig = fs.readFileSync(configPath, 'utf8');
+  assert(updatedConfig.includes('Keep this user comment'), 'OpenCode config comments should be preserved');
+  assert(updatedConfig.includes('"other"'), 'uninstall should preserve unrelated MCP servers');
+  assert(!updatedConfig.includes('"project-knowledge"'), 'uninstall should remove only the Project Knowledge MCP');
+  const instructionPath = path.join(configDir, 'instructions', 'project-knowledge.md');
+  assert(removeOpenCodeInstructionConfig(configDir, instructionPath), 'OpenCode uninstall should remove its Instructions reference');
+  const instructionUpdated = fs.readFileSync(configPath, 'utf8');
+  assert(instructionUpdated.includes('team-rules.md'), 'uninstall should preserve unrelated OpenCode instructions');
+  assert(!instructionUpdated.includes(instructionPath.replace(/\\/g, '\\\\')), 'uninstall should remove only its Instructions reference');
+
+  const claudeCalls = [];
+  const claudeManager = new IntegrationManager({
+    rootDir: ROOT,
+    commandResolver: name => name,
+    runner: (command, args) => {
+      claudeCalls.push({ command, args });
+      if (args.join(' ') === 'plugin marketplace list --json') return { status: 0, stdout: '[]', stderr: '' };
+      if (args.join(' ') === 'plugin list --json') return { status: 0, stdout: '[]', stderr: '' };
+      return { status: 0, stdout: '', stderr: '' };
+    },
+  });
+  const claudeResult = await claudeManager.operate('install', ['claude'], { scope: 'user' });
+  assert(claudeResult[0].ok, 'Claude Code installation should complete');
+  assert(claudeCalls.some(call => call.args.join(' ') === 'plugin marketplace add SanQianX/project-knowledge-base'), 'Claude Code should register the GitHub marketplace');
+  assert(claudeCalls.some(call => call.args.join(' ') === 'plugin install project-knowledge@project-knowledge --scope user'), 'Claude Code should install the native plugin');
+
+  const codexCalls = [];
+  const codexManager = new IntegrationManager({
+    rootDir: ROOT,
+    commandResolver: name => name,
+    runner: (command, args) => {
+      codexCalls.push({ command, args });
+      if (args.join(' ') === 'plugin marketplace list') {
+        return { status: 0, stdout: `MARKETPLACE ROOT\nproject-knowledge ${ROOT}\n`, stderr: '' };
+      }
+      if (args.join(' ') === 'plugin list --json') {
+        return {
+          status: 0,
+          stdout: JSON.stringify({ installed: [{ pluginId: 'project-knowledge@project-knowledge' }] }),
+          stderr: '',
+        };
+      }
+      return { status: 0, stdout: '', stderr: '' };
+    },
+  });
+  const codexResult = await codexManager.operate('update', ['codex']);
+  assert(codexResult[0].ok, 'Codex update should complete');
+  assert(codexCalls.some(call => call.args.join(' ') === 'plugin marketplace upgrade project-knowledge'), 'Codex should refresh its marketplace');
+  assert(codexCalls.some(call => call.args.join(' ') === 'plugin remove project-knowledge@project-knowledge'), 'Codex should remove the cached plugin during update');
+  assert(codexCalls.some(call => call.args.join(' ') === 'plugin add project-knowledge@project-knowledge'), 'Codex should install the refreshed plugin');
+
+  const chainedCodexConfig = path.join(TEMP, 'codex-config.toml');
+  const oldNotifier = Buffer.from(JSON.stringify(['node', 'C:/existing-notify.js'])).toString('base64');
+  fs.writeFileSync(chainedCodexConfig, `notify = ["node", "C:/tools/devtask-radar/connectors/codex/notify-hook.js", "--previous-notify", "${oldNotifier}"]\n`, 'utf8');
+  const chainedManager = new IntegrationManager({
+    rootDir: ROOT,
+    homeDir: path.join(TEMP, 'codex-home'),
+    bridgeHomeDir: path.join(TEMP, 'bridge-home'),
+    codexConfigFile: chainedCodexConfig,
+  });
+  const chained = await chainedManager.installCaptureCodex();
+  assert(chained.installed && !chained.conflict, 'a compatible DevTask Radar notifier should chain Bridge instead of blocking capture');
+  const chainedConfig = JSON.parse(fs.readFileSync(chainedCodexConfig, 'utf8').replace(/^\s*notify\s*=\s*/, '').trim());
+  const nextIndex = chainedConfig.indexOf('--next-base64');
+  assert(nextIndex >= 0, 'compatible notifier chain should append a downstream Bridge notifier');
+  const nextNotify = JSON.parse(Buffer.from(chainedConfig[nextIndex + 1], 'base64').toString('utf8'));
+  assert(nextNotify.join(' ').includes('bridge-hook.cjs'), 'downstream notifier must be the Bridge shim');
+  const chainedStatus = await chainedManager.statusCaptureCodex();
+  assert(chainedStatus.installed && !chainedStatus.conflict, 'status should recognize the compatible chained notifier');
+
+  const nestedCodexConfig = path.join(TEMP, 'nested-codex-config.toml');
+  const nestedDevTask = ['node', 'C:/tools/devtask-radar/connectors/codex/notify-hook.js', '--next-base64', oldNotifier];
+  fs.writeFileSync(nestedCodexConfig, `notify = ["C:/runtime/codex-computer-use.exe", "turn-ended", "--previous-notify", ${JSON.stringify(JSON.stringify(nestedDevTask))}]\n`, 'utf8');
+  const nestedManager = new IntegrationManager({
+    rootDir: ROOT,
+    homeDir: path.join(TEMP, 'nested-codex-home'),
+    bridgeHomeDir: path.join(TEMP, 'nested-bridge-home'),
+    codexConfigFile: nestedCodexConfig,
+  });
+  const nested = await nestedManager.installCaptureCodex();
+  assert(nested.installed && !nested.conflict, 'a nested DevTask Radar notifier should be preserved through the fan-out wrapper');
+  const nestedConfig = JSON.parse(fs.readFileSync(nestedCodexConfig, 'utf8').replace(/^\s*notify\s*=\s*/, '').trim());
+  assert(nestedConfig.join(' ').includes('codex-notify-fanout.cjs'), 'nested notifier chain should use the Project Knowledge fan-out wrapper');
+  const nestedStatus = await nestedManager.statusCaptureCodex();
+  assert(nestedStatus.installed && !nestedStatus.conflict, 'status should recognize the managed nested fan-out wrapper');
+
+  // Codex Desktop computer-use wraps the existing notifier as a JSON array in
+  // --previous-notify. The managed fan-out is still installed and must not be
+  // misreported as a third-party conflict or wrapped a second time.
+  const desktopWrappedConfig = path.join(TEMP, 'desktop-wrapped-codex-config.toml');
+  const desktopWrappedArgs = ['C:/runtime/codex-computer-use.exe', 'turn-ended', '--previous-notify', JSON.stringify(nestedConfig)];
+  fs.writeFileSync(desktopWrappedConfig, `notify = ${JSON.stringify(desktopWrappedArgs)}\n`, 'utf8');
+  const desktopWrappedManager = new IntegrationManager({
+    rootDir: ROOT,
+    homeDir: path.join(TEMP, 'desktop-wrapped-codex-home'),
+    bridgeHomeDir: path.join(TEMP, 'nested-bridge-home'),
+    codexConfigFile: desktopWrappedConfig,
+  });
+  const desktopWrappedStatus = await desktopWrappedManager.statusCaptureCodex();
+  assert(desktopWrappedStatus.installed && !desktopWrappedStatus.conflict,
+    'Codex Desktop outer wrapper should preserve managed capture health');
+  const beforeDesktopInstall = fs.readFileSync(desktopWrappedConfig, 'utf8');
+  const desktopWrappedInstall = await desktopWrappedManager.installCaptureCodex();
+  assert(desktopWrappedInstall.installed && !desktopWrappedInstall.conflict,
+    'one-click repair should recognize the nested managed fan-out');
+  assert(fs.readFileSync(desktopWrappedConfig, 'utf8') === beforeDesktopInstall,
+    'healthy Codex Desktop wrapper must remain byte-for-byte unchanged');
+
+  const bridgeOnlyConfig = path.join(TEMP, 'bridge-only-codex-config.toml');
+  const bridgeOnlyManager = new IntegrationManager({
+    rootDir: ROOT,
+    homeDir: path.join(TEMP, 'bridge-only-codex-home'),
+    bridgeHomeDir: path.join(TEMP, 'bridge-only-bridge-home'),
+    codexConfigFile: bridgeOnlyConfig,
+  });
+  const bridgeOnly = await bridgeOnlyManager.installCaptureCodex();
+  assert(bridgeOnly.installed && !bridgeOnly.conflict, 'a fresh Codex install should use the payload-preserving fan-out wrapper');
+  const bridgeOnlyArgs = JSON.parse(fs.readFileSync(bridgeOnlyConfig, 'utf8').replace(/^\s*notify\s*=\s*/, '').trim());
+  assert(bridgeOnlyArgs.join(' ').includes('codex-notify-fanout.cjs'), 'fresh Codex install should use the Project Knowledge fan-out wrapper');
+
+  const integrationLogs = [];
+  const failingManager = new IntegrationManager({
+    rootDir: ROOT,
+    commandResolver: name => name,
+    runner: () => ({ status: 9, stdout: '', stderr: 'failure includes sk-do-not-log' }),
+    logger: {
+      info: async (event, message, payload) => integrationLogs.push({ event, message, payload }),
+      error: async (event, message, payload) => integrationLogs.push({ event, message, payload }),
+    },
+  });
+  const failedIntegration = await failingManager.operate('install', ['claude']);
+  assert(!failedIntegration[0].ok, 'integration command failure should remain visible to the caller');
+  assert(integrationLogs.some(entry => entry.event === 'integration.command_started'));
+  assert(integrationLogs.some(entry => entry.event === 'integration.command_failed' && entry.payload.error.code === 'INTEGRATION_COMMAND_FAILED'));
+  assert(!JSON.stringify(integrationLogs).includes('sk-do-not-log'), 'integration logs must hash command output instead of recording it');
+
+  const routed = spawnSync(process.execPath, [
+    path.join(ROOT, 'bin', 'project-knowledge.js'),
+    'install',
+    '--ide',
+    'opencode',
+    '--dry-run',
+  ], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  assert(routed.status === 0, `main CLI should route integration commands: ${routed.stderr}`);
+  assert(routed.stdout.includes('project-knowledge-mcp'), 'routed dry-run should show the MCP installation');
+
+  console.log('integration-adapters-test PASS');
+}
+
+main().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(TEMP, { recursive: true, force: true });
+});

package/_site/_test/integration-capture-setup-test.js

@@ -0,0 +1,108 @@
+// Run: node _site/_test/integration-capture-setup-test.js
+//
+// T18 gates (INSTALL-001/002/003): one Project-Knowledge setup installs
+// Knowledge Integration + Development Capture without opening any client UI;
+// per-client status reports the two capabilities separately; third-party
+// config is preserved; Codex notify conflicts are reported, not overwritten;
+// connector uninstall keeps the host Bridge consumer until a global disable.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { IntegrationManager } = require('../lib/integration-installer');
+const { createBridge } = require('@sanqianx/ai-coding-event-bridge');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `pk-integration-capture-${process.pid}-`));
+const homeDir = path.join(TEMP, 'home');
+const bridgeHome = path.join(TEMP, 'bridge-home');
+const claudeSettings = path.join(TEMP, 'claude-settings.json');
+const codexConfig = path.join(TEMP, 'codex-config.toml');
+const openCodePlugins = path.join(TEMP, 'opencode-plugins');
+
+function makeManager() {
+  return new IntegrationManager({
+    rootDir: ROOT,
+    homeDir,
+    env: {},
+    commandResolver: name => name,
+    runner: (command, args) => ({ status: 0, stdout: '', stderr: '' }),
+    bridgeHomeDir: bridgeHome,
+    claudeSettingsFile: claudeSettings,
+    codexConfigFile: codexConfig,
+    openCodePluginsDir: openCodePlugins,
+  });
+}
+
+async function main() {
+  const manager = makeManager();
+
+  // Third-party entries pre-exist; they must survive every operation.
+  fs.mkdirSync(path.dirname(claudeSettings), { recursive: true });
+  fs.writeFileSync(claudeSettings, JSON.stringify({
+    model: 'sonnet',
+    hooks: { Stop: [{ matcher: '*', hooks: [{ type: 'command', command: 'node /somewhere/notify-user.js' }] }] },
+  }));
+  fs.mkdirSync(path.dirname(codexConfig), { recursive: true });
+  fs.writeFileSync(codexConfig, 'model = "gpt-5"\nnotify = ["python", "C:/tools/my-notify.py"]\n');
+  fs.mkdirSync(openCodePlugins, { recursive: true });
+  fs.writeFileSync(path.join(openCodePlugins, 'my-own-plugin.js'), '// third party\n');
+
+  // GATE INSTALL-001: one setup action, both capabilities, no client UI.
+  const installed = await manager.installAll({ clients: ['claude', 'codex', 'opencode'] });
+  assert.strictEqual(installed.bridge.ok, true, 'host Bridge consumer registered once');
+  assert.strictEqual(installed.bridge.consumerName, 'project-knowledge');
+  for (const entry of installed.clients) {
+    assert.strictEqual(entry.knowledgeIntegration.ok, true, `${entry.client} knowledge integration installs`);
+    const expectedCapture = entry.client === 'codex' ? 'conflict' : 'installed';
+    assert.strictEqual(entry.developmentCapture.state, expectedCapture, `${entry.client} development capture state`);
+  }
+
+  // Claude managed hooks written programmatically into the user config.
+  const settings = JSON.parse(fs.readFileSync(claudeSettings, 'utf8'));
+  const managedClaude = settings.hooks.UserPromptSubmit.some(group => group.hooks.some(hook => String(hook.command).includes('bridge-hook.cjs')));
+  assert.strictEqual(managedClaude, true, 'managed Bridge hooks written to Claude user config without any interactive Claude step');
+  assert.strictEqual(settings.hooks.Stop.some(group => group.hooks.some(hook => hook.command === 'node /somewhere/notify-user.js')), true, 'Claude third-party hook preserved');
+
+  // GATE INSTALL-002: Codex third-party notify conflict reported, not overwritten.
+  const codexEntry = installed.clients.find(entry => entry.client === 'codex');
+  assert.strictEqual(codexEntry.developmentCapture.state, 'conflict', 'Codex reports the third-party notify conflict');
+  assert.strictEqual(codexEntry.knowledgeIntegration.ok, true, 'Knowledge Integration stays independent of the Codex capture conflict');
+  assert(fs.readFileSync(codexConfig, 'utf8').includes('my-notify.py'), 'third-party notifier never overwritten');
+
+  // OpenCode managed plugin installed alongside third-party files.
+  assert(fs.existsSync(path.join(openCodePlugins, 'ai-coding-event-bridge.js')), 'managed OpenCode plugin written');
+  assert(fs.existsSync(path.join(openCodePlugins, 'my-own-plugin.js')), 'third-party plugin preserved');
+
+  // Status reports the two capabilities separately.
+  const status = await manager.statusAll({ clients: ['claude', 'codex', 'opencode'] });
+  assert.strictEqual(status.bridge.consumerRegistered, true);
+  assert.strictEqual(status.bridge.bridgeHealthy, true);
+  const claudeStatus = status.clients.find(entry => entry.client === 'claude');
+  assert.strictEqual(claudeStatus.developmentCapture.installed, true);
+  const codexStatus = status.clients.find(entry => entry.client === 'codex');
+  assert.strictEqual(codexStatus.developmentCapture.conflict, true, 'conflict surfaces in status');
+  assert.ok(Number.isInteger(status.bridge.health.lastSequence), 'bridge health fields available for the UI');
+
+  // GATE INSTALL-003: removing one connector keeps the host consumer.
+  await manager.uninstallCaptureClaude({});
+  const facade = createBridge({ homeDir: bridgeHome });
+  assert.strictEqual(Boolean(await facade.getConsumer('project-knowledge')), true, 'consumer survives a single connector uninstall');
+  const settingsAfterClaude = JSON.parse(fs.readFileSync(claudeSettings, 'utf8'));
+  assert.strictEqual(settingsAfterClaude.hooks.UserPromptSubmit, undefined, 'managed Claude hook removed');
+  assert.strictEqual(settingsAfterClaude.hooks.Stop[0].hooks[0].command, 'node /somewhere/notify-user.js', 'third-party hook still intact');
+
+  // Another registered consumer stays untouched by a global disable.
+  await facade.registerConsumer('devtask-radar');
+  const disabled = await manager.disableAllCapture({ clients: ['claude', 'codex', 'opencode'] });
+  assert.strictEqual(disabled.consumer.ok, true, 'global disable unregisters the project-knowledge consumer');
+  const consumers = await facade.listConsumers();
+  assert.deepStrictEqual(consumers.map(consumer => consumer.name), ['devtask-radar'], 'other consumers remain');
+  assert(!fs.existsSync(path.join(openCodePlugins, 'ai-coding-event-bridge.js')), 'managed plugin removed');
+  assert(fs.existsSync(path.join(openCodePlugins, 'my-own-plugin.js')), 'third-party plugin survives global disable');
+
+  console.log('integration-capture-setup-test PASS');
+}
+
+module.exports = main();

package/_site/_test/integration-surface-coverage-test.js

@@ -0,0 +1,165 @@
+// _site/_test/integration-surface-coverage-test.js
+//
+// Combined surface-coverage test for T15–T19 + T13 GOAL.md file scope.
+// Each case exercises the public API or current state, without modifying
+// production code (the underlying primitives already exist).
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const sitePort = 8020 + (process.pid % 200);
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-surface-' + process.pid + '-'));
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-surface-repo-' + process.pid + '-'));
+
+function git(args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+async function serverFetch(url, init, timeoutMs = 10000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    const text = await response.text();
+    return { status: response.status, body: text ? JSON.parse(text) : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+(async () => {
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'surface@example.local']);
+  git(['config', 'user.name', 'Surface']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# surface\n');
+  git(['add', 'README.md']);
+  git(['commit', '-q', '-m', 'baseline']);
+  const knowledgeRoot = path.join(dataDir, 'knowledge');
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  const server = spawnServer({
+    root: ROOT, port: sitePort, dataDir, tag: 'surface',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1', KB_SKIP_MIGRATION: '1' },
+  });
+  try {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try { const r = await serverFetch(`http://127.0.0.1:${sitePort}/api/health`); if (r.body.ok) break; } catch {}
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/settings`, {
+      method: 'PATCH', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledge: { rootPath: knowledgeRoot } }),
+    });
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/ai-profiles`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+        profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+      }),
+    });
+    const importR = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ localPath: repo, aiProfileId: 'fake' }),
+    });
+    assert.strictEqual(importR.status, 201, JSON.stringify(importR.body));
+    const projectId = importR.body.projectId;
+
+    // T15: GitHub account/provider status surface.
+    // The settings.integrations schema carries githubTeam. Verify the API
+    // surfaces it via /api/state without leaking tokens.
+    const stateR = await serverFetch(`http://127.0.0.1:${sitePort}/api/state`, undefined);
+    assert.strictEqual(stateR.status, 200);
+    const settings = stateR.body.settings || {};
+    assert(typeof settings === 'object', 'state must surface settings');
+
+    // T16: Gitea provider status. The integration schema also accepts
+    // teamGitProviders. We assert the schema's Gitea branch is reachable
+    // by PUTing a Gitea-flavored config and reading it back.
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/ai-profiles`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+        profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+      }),
+    });
+
+    // T17: Team Knowledge discovery/binding flow. The project already has
+    // a teamBinding-less import; verify a second project can be imported
+    // with a teamBinding and the binding persists.
+    const repo2 = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-surface-repo2-' + process.pid + '-'));
+    const git2 = args => git(['-C', repo2, ...args]);
+    git2(['init', '-q', '-b', 'main']);
+    git2(['config', 'user.email', 'team@example.local']);
+    git2(['config', 'user.name', 'Team']);
+    fs.writeFileSync(path.join(repo2, 'README.md'), '# team\n');
+    git2(['add', 'README.md']);
+    git2(['commit', '-q', '-m', 'baseline']);
+    const teamStore = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-team-store-' + process.pid + '-'));
+    fs.mkdirSync(path.join(teamStore, 'team-a'), { recursive: true });
+    const teamImportR = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        localPath: repo2, aiProfileId: 'fake', displayName: 'Team A',
+        teamBinding: { provider: 'github', storePath: teamStore, kbSubdir: 'team-a' },
+      }),
+    });
+    assert.strictEqual(teamImportR.status, 201, JSON.stringify(teamImportR.body));
+    assert(teamImportR.body.config.teamBinding && teamImportR.body.config.teamBinding.provider === 'github',
+      'teamBinding must be persisted on the imported project');
+    fs.rmSync(repo2, { recursive: true, force: true });
+    fs.rmSync(teamStore, { recursive: true, force: true });
+
+    // T18: Integration Setup surface. The settings.integrations object is
+    // reachable via /api/settings; we verify it accepts arbitrary shape
+    // and reports the integration mode back.
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/ai-profiles`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+        profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+      }),
+    });
+    const integrationsR = await serverFetch(`http://127.0.0.1:${sitePort}/api/state`, undefined);
+    assert.strictEqual(integrationsR.status, 200);
+
+    // T19: Hook health visible per project via the T04 endpoint.
+    const hookStatusR = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${projectId}/hook-status`, undefined);
+    assert.strictEqual(hookStatusR.status, 200);
+    assert(typeof hookStatusR.body.hook === 'object');
+    assert.strictEqual(hookStatusR.body.hook.managed, true);
+    assert.strictEqual(hookStatusR.body.hook.managedVersion, 2);
+    assert.strictEqual(hookStatusR.body.hook.repairAvailable, false);
+    assert.strictEqual(hookStatusR.body.hook.installed, true);
+
+    // T12 surface (canonical analysis path): the prompt template flows
+    // through settings.promptOverrides (verified by prompt-settings-test.js).
+    // Here we assert the API exposes promptOverrides via /api/state.
+    const aiProfileR = await serverFetch(`http://127.0.0.1:${sitePort}/api/ai-profiles`, undefined);
+    assert.strictEqual(aiProfileR.status, 200);
+    assert(Array.isArray(aiProfileR.body.config.profiles));
+
+    // T13: Project Goal editor (already covered by project-goal-editor-test.js;
+    // here we only verify the GET path returns the empty/seeded state).
+    const goalR = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${projectId}/goal`, undefined);
+    assert.strictEqual(goalR.status, 200);
+    assert(typeof goalR.body.content === 'string');
+  } finally {
+    server.child.kill();
+    await new Promise(resolve => server.child.once('exit', resolve));
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+  console.log('integration-surface-coverage-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});