@sanqianx/project-knowledge 4.6.1

package/_site/_test/hook-trigger-test.js

@@ -0,0 +1,85 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  HOOK_MARKER,
+  installHook,
+  uninstallHook,
+  readHookStatus,
+  parseManagedMarker,
+} = require('../lib/hook-manager');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
+
+function git(repo, 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`);
+  return String(result.stdout || '').trim();
+}
+
+function makeRepo() {
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-hook-v2-repo-'));
+  git(repo, ['init', '--initial-branch=main']);
+  git(repo, ['config', 'user.email', 'hook@example.invalid']);
+  git(repo, ['config', 'user.name', 'Hook Test']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# hook\n');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-m', 'initial']);
+  return repo;
+}
+
+const repo = makeRepo();
+const claudePath = path.join(repo, 'CLAUDE.md');
+fs.writeFileSync(claudePath, '# user-owned\n');
+const projectId = 'project-hook-test';
+
+const installed = installHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER });
+assert.strictEqual(installed.ok, true);
+assert(fs.existsSync(installed.hookPath));
+const body = fs.readFileSync(installed.hookPath, 'utf8');
+assert(body.includes(HOOK_MARKER));
+assert(body.includes('--project-id'));
+assert(body.includes('--repo-root "$REPO_ROOT"'));
+assert(body.includes('git rev-parse --show-toplevel'));
+assert(!body.includes(repo.replace(/\\/g, '/')), 'managed hook must not embed the imported repo path');
+assert.strictEqual(parseManagedMarker(body).projectId, projectId);
+assert.strictEqual(fs.readFileSync(claudePath, 'utf8'), '# user-owned\n', 'Hook install must not modify CLAUDE.md');
+
+const repeated = installHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER });
+assert.strictEqual(repeated.updated, false);
+assert.strictEqual(fs.readFileSync(installed.hookPath, 'utf8'), body);
+assert.strictEqual(readHookStatus({ repoPath: repo, projectId }).installed, true);
+
+const removed = uninstallHook({ repoPath: repo, projectId });
+assert.strictEqual(removed.removed, true);
+assert.strictEqual(fs.readFileSync(claudePath, 'utf8'), '# user-owned\n', 'Hook uninstall must not modify CLAUDE.md');
+
+fs.writeFileSync(installed.hookPath, '#!/bin/sh\necho user-hook\n');
+assert.throws(() => installHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER }), error => error.code === 'HOOK_CONFLICT');
+assert.throws(() => uninstallHook({ repoPath: repo, projectId }), error => error.code === 'HOOK_CONFLICT');
+assert(fs.readFileSync(installed.hookPath, 'utf8').includes('user-hook'));
+
+const offlineData = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-hook-offline-'));
+const offlineBridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-hook-offline-bridge-'));
+const offline = spawnSync(process.execPath, [TRIGGER, '--project-id', projectId, '--repo-root', repo, '--port', '65530'], {
+  encoding: 'utf8',
+  timeout: 10_000,
+  env: { ...process.env, KB_DATA_DIR: offlineData, KB_SKIP_MIGRATION: '1', AI_CODING_EVENT_BRIDGE_HOME: offlineBridgeHome },
+});
+assert.strictEqual(offline.status, 0, offline.stderr);
+const hooksLogDir = path.join(offlineData, 'logs', 'projects', projectId);
+assert(fs.existsSync(hooksLogDir));
+const lines = fs.readdirSync(hooksLogDir).flatMap(file => fs.readFileSync(path.join(hooksLogDir, file), 'utf8').trim().split(/\r?\n/).filter(Boolean).map(JSON.parse));
+assert(lines.some(line => line.schema === 'log/v2' && line.event === 'hook.notification.degraded'));
+assert(lines.some(line => line.schema === 'log/v2' && line.event === 'hook.boundary.captured'), 'boundary is durably captured even when the server is offline');
+const boundaryLines = fs.readFileSync(path.join(offlineBridgeHome, 'journal', 'events.jsonl'), 'utf8').trim().split(/\r?\n/).map(JSON.parse);
+assert(boundaryLines.some(record =>
+  record.schema === 'git-commit-boundary/v1' &&
+  record.projectId === projectId &&
+  record.repoIdentity && record.repoIdentity.schema === 'repo-identity/v1' &&
+  typeof record.repoIdentity.workspaceId === 'string'), 'boundary carries a canonical v1 workspace identity in the isolated Bridge journal');
+
+console.log('hook-trigger-test PASS');

package/_site/_test/hook-worktree-test.js

@@ -0,0 +1,42 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { installHook, readHookStatus, migrateManagedHook, LEGACY_HOOK_MARKER } = require('../lib/hook-manager');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
+
+function git(repo, 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`);
+  return String(result.stdout || '').trim();
+}
+
+const base = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-hook-worktree-'));
+const main = path.join(base, 'main repo');
+const linked = path.join(base, 'linked worktree');
+fs.mkdirSync(main, { recursive: true });
+git(main, ['init', '--initial-branch=main']);
+git(main, ['config', 'user.email', 'hook@example.invalid']);
+git(main, ['config', 'user.name', 'Hook Test']);
+fs.writeFileSync(path.join(main, 'README.md'), '# main\n');
+git(main, ['add', 'README.md']);
+git(main, ['commit', '-m', 'initial']);
+git(main, ['worktree', 'add', '-b', 'linked', linked]);
+
+git(linked, ['config', 'core.hooksPath', '.custom-hooks']);
+const installed = installHook({ repoPath: linked, projectId: 'project-worktree', triggerScriptPath: TRIGGER });
+const authoritativeHooks = git(linked, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+assert.strictEqual(path.resolve(path.dirname(installed.hookPath)), path.resolve(authoritativeHooks));
+assert.strictEqual(readHookStatus({ repoPath: linked, projectId: 'project-worktree' }).installed, true);
+
+fs.writeFileSync(installed.hookPath, `#!/bin/sh\n${LEGACY_HOOK_MARKER} — old\nexit 0\n`);
+const migrated = migrateManagedHook({ repoPath: linked, projectId: 'project-worktree', triggerScriptPath: TRIGGER });
+assert.strictEqual(migrated.migrated, true);
+const second = migrateManagedHook({ repoPath: linked, projectId: 'project-worktree', triggerScriptPath: TRIGGER });
+assert.strictEqual(second.migrated, false);
+assert.strictEqual(second.reason, 'current');
+
+console.log('hook-worktree-test PASS');

package/_site/_test/import-preflight-api-test.js

@@ -0,0 +1,233 @@
+// _site/_test/import-preflight-api-test.js
+//
+// T06: preflight endpoint surface contract.
+// Drives POST /api/projects/preflight-import through every documented
+// prerequisite path and asserts the response shape.
+
+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 PORT = 7903;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-${process.pid}-`));
+
+function git(repo, 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 requestJson(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, body: await response.json() };
+}
+function postJson(pathname, body) { return requestJson('POST', pathname, body); }
+function patchJson(pathname, body) { return requestJson('PATCH', pathname, body); }
+function putJson(pathname, body) { return requestJson('PUT', pathname, body); }
+
+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 repoOk = fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-repo-ok-${process.pid}-`));
+  const repoEmpty = fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-repo-empty-${process.pid}-`));
+  const repoNonGit = fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-repo-non-git-${process.pid}-`));
+  const repoSpaces = path.join(fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-spaces-${process.pid}-`)), 'project with spaces');
+  const repoThirdParty = fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-thirdparty-${process.pid}-`));
+  try {
+    fs.mkdirSync(repoSpaces, { recursive: true });
+    // existing Git repo with a baseline commit
+    git(repoOk, ['init', '-q', '-b', 'main']);
+    git(repoOk, ['config', 'user.email', 'preflight@example.local']);
+    git(repoOk, ['config', 'user.name', 'Preflight']);
+    fs.writeFileSync(path.join(repoOk, 'README.md'), '# ok\n');
+    git(repoOk, ['add', 'README.md']);
+    git(repoOk, ['commit', '-q', '-m', 'baseline']);
+    // empty git repo (no commits yet)
+    git(repoEmpty, ['init', '-q', '-b', 'main']);
+    git(repoEmpty, ['config', 'user.email', 'preflight@example.local']);
+    git(repoEmpty, ['config', 'user.name', 'Preflight']);
+    // non-git dir with a stray file
+    fs.writeFileSync(path.join(repoNonGit, 'note.txt'), 'hi\n');
+    // repo with a literal space in its path
+    git(repoSpaces, ['init', '-q', '-b', 'main']);
+    git(repoSpaces, ['config', 'user.email', 'preflight@example.local']);
+    git(repoSpaces, ['config', 'user.name', 'Preflight']);
+    fs.writeFileSync(path.join(repoSpaces, 'README.md'), '# spaces\n');
+    git(repoSpaces, ['add', 'README.md']);
+    git(repoSpaces, ['commit', '-q', '-m', 'baseline']);
+    // repo with a third-party hook
+    git(repoThirdParty, ['init', '-q', '-b', 'main']);
+    git(repoThirdParty, ['config', 'user.email', 'preflight@example.local']);
+    git(repoThirdParty, ['config', 'user.name', 'Preflight']);
+    fs.writeFileSync(path.join(repoThirdParty, 'README.md'), '# tp\n');
+    git(repoThirdParty, ['add', 'README.md']);
+    git(repoThirdParty, ['commit', '-q', '-m', 'baseline']);
+    const gitDir = git(repoThirdParty, ['rev-parse', '--path-format=absolute', '--git-dir']);
+    const hooksDir = path.join(path.resolve(gitDir), 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+    fs.writeFileSync(path.join(hooksDir, 'post-commit'), '#!/bin/sh\necho "user owned"\nexit 0\n', { mode: 0o755 });
+
+    const spawned = spawnServer({
+      root: ROOT, port: PORT, dataDir, tag: 'preflight',
+      extraEnv: { KB_SKIP_MIGRATION: '1' },
+    });
+    try {
+      await waitForServer();
+      const knowledgeRoot = path.join(dataDir, 'knowledge');
+      fs.mkdirSync(knowledgeRoot, { recursive: true });
+      let r = await patchJson('/api/settings', { knowledge: { rootPath: knowledgeRoot } });
+      assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+      // Configure a fake AI profile so most checks succeed.
+      r = await putJson('/api/ai-profiles', {
+        schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+        profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+      });
+      assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+
+      // Case 1: existing Git repo with AI profile -> ready
+      r = await postJson('/api/projects/preflight-import', { localPath: repoOk, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ok, true);
+      assert.strictEqual(r.body.ready, true);
+      assert.strictEqual(r.body.plannedGitInit, false);
+      assert.deepStrictEqual(r.body.problems, []);
+      assert.strictEqual(r.body.checks.git.status, 'ok');
+      assert.strictEqual(r.body.checks.aiProfile.ok, true);
+      assert.strictEqual(r.body.effective.aiProfile.id, 'fake');
+
+      // Case 2: non-Git folder -> plannedGitInit=true, ready=true (auto-init path)
+      // The product intentionally auto-inits on import (T06), so the preflight
+      // surfaces the planned init rather than blocking. The UI shows a banner.
+      r = await postJson('/api/projects/preflight-import', { localPath: repoNonGit, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.plannedGitInit, true);
+      assert.strictEqual(r.body.ready, true, 'non-git folder with planned auto-init is importable');
+      assert.strictEqual(r.body.checks.git.plannedInit, true);
+      assert.strictEqual(r.body.checks.git.status, 'non-git');
+
+      // Case 3: empty git repo (HEAD missing) -> ready=true (commit will be made later)
+      r = await postJson('/api/projects/preflight-import', { localPath: repoEmpty, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ok, true, 'empty repo is importable; the import transaction creates the first commit semantics later');
+      assert.strictEqual(r.body.checks.git.status, 'empty');
+      assert.strictEqual(r.body.checks.git.headCommit, null);
+
+      // Case 4: missing knowledge root -> ready=false
+      const noKnowledgeSpawned = spawnServer({
+        root: ROOT, port: PORT + 1, dataDir: fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-nokb-${process.pid}-`)),
+        tag: 'preflight-nokb', extraEnv: { KB_SKIP_MIGRATION: '1' },
+      });
+      try {
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+          try { if ((await fetch(`http://127.0.0.1:${PORT + 1}/api/health`)).ok) break; } catch {}
+          await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        const r2 = await fetch(`http://127.0.0.1:${PORT + 1}/api/projects/preflight-import`, {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ localPath: repoOk, aiProfileId: 'fake' }),
+        }).then(async response => ({ status: response.status, body: await response.json() }));
+        console.log('DEBUG no-knowledge-root:', r2.status, JSON.stringify(r2.body));
+        assert.strictEqual(r2.status, 200);
+        assert.strictEqual(r2.body.ready, false);
+        assert(r2.body.problems.some(p => p.code === 'KNOWLEDGE_ROOT_MISSING'));
+      } finally {
+        noKnowledgeSpawned.child.kill();
+        await new Promise(resolve => noKnowledgeSpawned.child.once('exit', resolve));
+      }
+
+      // Case 5: path with spaces -> ready=true
+      r = await postJson('/api/projects/preflight-import', { localPath: repoSpaces, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ready, true);
+      assert.strictEqual(r.body.checks.git.ok, true);
+
+      // Case 6: no AI profile configured -> ready=false with AI_PROFILE_REQUIRED
+      const noProfileSpawned = spawnServer({
+        root: ROOT, port: PORT + 2, dataDir: fs.mkdtempSync(path.join(os.tmpdir(), `pk-preflight-noprofile-${process.pid}-`)),
+        tag: 'preflight-noprofile', extraEnv: { KB_SKIP_MIGRATION: '1' },
+      });
+      try {
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+          try { if ((await fetch(`http://127.0.0.1:${PORT + 2}/api/health`)).ok) break; } catch {}
+          await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        // Patch only knowledge root; no AI profile configured
+        const noProfileDir = noProfileSpawned.dataDir || noProfileSpawned.dir;
+        await fetch(`http://127.0.0.1:${PORT + 2}/api/settings`, {
+          method: 'PATCH', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ knowledge: { rootPath: path.join(noProfileDir, 'knowledge') } }),
+        });
+        const r2 = await fetch(`http://127.0.0.1:${PORT + 2}/api/projects/preflight-import`, {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ localPath: repoOk }),
+        }).then(async response => ({ status: response.status, body: await response.json() }));
+        assert.strictEqual(r2.status, 200);
+        assert.strictEqual(r2.body.ready, false);
+        assert(r2.body.problems.some(p => p.code === 'AI_PROFILE_REQUIRED'));
+      } finally {
+        noProfileSpawned.child.kill();
+        await new Promise(resolve => noProfileSpawned.child.once('exit', resolve));
+      }
+
+      // Case 7: third-party hook -> ready=false with HOOK_CONFLICT
+      r = await postJson('/api/projects/preflight-import', { localPath: repoThirdParty, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ready, false);
+      assert(r.body.problems.some(p => p.code === 'HOOK_CONFLICT'));
+      assert.strictEqual(r.body.checks.hook.ok, false);
+      assert.strictEqual(r.body.checks.hook.reason, 'third-party');
+
+      // Case 8: duplicate detection after a successful import
+      r = await postJson('/api/projects/import', { localPath: repoOk, displayName: 'Dup', aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 201, JSON.stringify(r.body));
+      const projectId = r.body.projectId;
+      r = await postJson('/api/projects/preflight-import', { localPath: repoOk, aiProfileId: 'fake' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ready, false);
+      assert(r.body.problems.some(p => p.code === 'DUPLICATE_PROJECT' && p.existingProjectId === projectId));
+
+      // Case 9: invalid knowledgeLanguage -> problem reported
+      r = await postJson('/api/projects/preflight-import', { localPath: repoOk, aiProfileId: 'fake', knowledgeLanguage: 'xx-INVALID' });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ready, false);
+      assert(r.body.problems.some(p => p.code === 'KNOWLEDGE_LANGUAGE_INVALID'));
+
+      // Case 10: path missing entirely
+      r = await postJson('/api/projects/preflight-import', { localPath: path.join(dataDir, 'does-not-exist') });
+      assert.strictEqual(r.status, 200);
+      assert.strictEqual(r.body.ready, false);
+      assert(r.body.problems.some(p => p.code === 'PATH_MISSING'));
+    } finally {
+      spawned.child.kill();
+      await new Promise(resolve => spawned.child.once('exit', resolve));
+    }
+  } finally {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    for (const dir of [repoOk, repoEmpty, repoNonGit, repoSpaces, repoThirdParty]) {
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+  }
+  console.log('import-preflight-api-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/_site/_test/import-ui-flow-test.js

@@ -0,0 +1,171 @@
+// _site/_test/import-ui-flow-test.js
+//
+// T07: end-to-end UI smoke for the Import view.
+// Verifies the preflight-driven UI: every input runs /api/projects/preflight-import,
+// the Import button stays disabled until ready=true, and problems surface
+// as a structured error list with an action hint.
+
+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 { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const sitePort = 7960 + (process.pid % 200);
+const profileDir = path.join(os.tmpdir(), 'pk-import-ui-' + process.pid);
+
+function git(repo, 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 () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-import-ui-data-' + process.pid + '-'));
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-import-ui-repo-' + process.pid + '-'));
+  const repoSpaces = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'pk-import-ui-spaces-' + process.pid + '-')), 'project with spaces');
+  fs.mkdirSync(repoSpaces, { recursive: true });
+  git(repo, ['init', '-q', '-b', 'main']);
+  git(repo, ['config', 'user.email', 'import-ui@example.local']);
+  git(repo, ['config', 'user.name', 'Import UI']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# import ui\n');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-q', '-m', 'baseline']);
+  git(repoSpaces, ['init', '-q', '-b', 'main']);
+  git(repoSpaces, ['config', 'user.email', 'import-ui@example.local']);
+  git(repoSpaces, ['config', 'user.name', 'Import UI']);
+  fs.writeFileSync(path.join(repoSpaces, 'README.md'), '# spaces\n');
+  git(repoSpaces, ['add', 'README.md']);
+  git(repoSpaces, ['commit', '-q', '-m', 'baseline']);
+  const server = spawnServer({
+    root: ROOT, port: sitePort, dataDir, tag: 'import-ui',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1', KB_SKIP_MIGRATION: '1' },
+  });
+  let browser;
+  // Plain Node fetch with explicit timeout. The cdp-browser requestJson helper
+  // uses a 1-second default which is too short for the server's first request
+  // after startup; we use Node's fetch + AbortSignal for direct setup calls.
+  async function serverFetch(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    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);
+    }
+  }
+  try {
+    await waitFor(async () => {
+      try { const r = await serverFetch(`http://127.0.0.1:${sitePort}/api/health`); return r.body.ok ? { ok: true } : null; } catch { return null; }
+    }, 'isolated server', 20000);
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/settings`, {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledge: { rootPath: path.join(dataDir, 'knowledge') } }),
+    });
+    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' } }],
+      }),
+    });
+    browser = await launchCdpBrowser({
+      chrome: findChrome(), profileDir, url: `http://127.0.0.1:${sitePort}/`, width: 1440, height: 900,
+    });
+    // Switch to Import view
+    await browser.evaluate("document.querySelector('[data-go=import]').click()");
+    await waitFor(async () => {
+      const visible = await browser.evaluate("document.getElementById('view-import').classList.contains('active')");
+      return visible ? { ok: true } : null;
+    }, 'import view visible', 20000);
+
+    // Case 1: empty path -> Import button disabled
+    {
+      const disabled = await browser.evaluate("document.getElementById('import-submit').disabled");
+      assert.strictEqual(disabled, true, 'Import button must be disabled when path is empty');
+    }
+
+    // Case 2: enter path with spaces -> preflight returns ready=true; button enabled
+    await browser.evaluate(`(() => {
+      const path = ${JSON.stringify(repoSpaces)};
+      const input = document.getElementById('import-path');
+      input.value = path;
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+    })()`);
+    await waitFor(async () => {
+      const state = await browser.evaluate(`(() => ({
+        disabled: document.getElementById('import-submit').disabled,
+        git: document.getElementById('pv-git-status').textContent,
+        root: document.getElementById('pv-knowledge-root').textContent,
+        preflightHidden: document.getElementById('import-preflight').hidden,
+        errHidden: document.getElementById('import-errors').hidden,
+      }))()`);
+      return state.disabled === false && state.errHidden ? { ok: true, state } : null;
+    }, 'preflight ready for valid path', 20000);
+
+    // Case 3: ② 知识库地址 → 预览回显该地址，导入按钮保持可用（两地址即登记映射）
+    await browser.evaluate(`(() => {
+      const input = document.getElementById('import-knowledge-path');
+      input.value = 'D:\\\\Knowledge\\\\spaces-demo';
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+    })()`);
+    await waitFor(async () => {
+      const state = await browser.evaluate(`(() => ({
+        disabled: document.getElementById('import-submit').disabled,
+        root: document.getElementById('pv-knowledge-root').textContent,
+      }))()`);
+      return state.disabled === false && /spaces-demo/.test(state.root) ? { ok: true } : null;
+    }, 'knowledge address reflected in preview', 20000);
+
+    // Case 5: submit form -> project imported; UI navigates to the terminal view.
+    await browser.evaluate(`(() => {
+      const form = document.getElementById('import-form');
+      if (typeof form.requestSubmit === 'function') form.requestSubmit();
+      else form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+    })()`);
+    await waitFor(async () => {
+      const visible = await browser.evaluate("document.getElementById('view-terminal').classList.contains('active')");
+      return visible ? { ok: true } : null;
+    }, 'import navigates to terminal view', 30000);
+
+    // Case 6: folder picker buttons are visible in Web mode and wired to the
+    // proxied module pickers (never clicked here — that would open a real
+    // native dialog on the host machine).
+    {
+      const pickers = await browser.evaluate(`(() => ({
+        dev: !document.getElementById('import-pick-folder').hidden,
+        knowledge: !document.getElementById('import-pick-knowledge').hidden,
+      }))()`);
+      assert.strictEqual(pickers.dev, true, 'dev-address picker must be visible');
+      assert.strictEqual(pickers.knowledge, true, 'knowledge-address picker must be visible');
+    }
+  } catch (error) {
+    console.error(error.stack || error.message);
+    throw error;
+  } finally {
+    if (browser) await browser.close();
+    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 });
+    fs.rmSync(repoSpaces, { recursive: true, force: true });
+  }
+  console.log('import-ui-flow-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/_site/_test/index-builder-test.js

@@ -0,0 +1,41 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { regenerateIndexes } = require('../lib/index-builder');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'index-builder-test-'));
+
+try {
+  const modules = path.join(temp, 'modules');
+  const changes = path.join(temp, 'changes');
+  fs.mkdirSync(modules, { recursive: true });
+  fs.mkdirSync(changes, { recursive: true });
+
+  const manyTags = Array.from({ length: 40 }, (_, index) => `tag-${index}`);
+  fs.writeFileSync(path.join(modules, 'core.md'), `---\ntitle: Core | API\ntags: [${manyTags.join(', ')}]\nsourcePaths: [${manyTags.map(tag => `src/${tag}.js`).join(', ')}]\nsymbols: [${manyTags.map(tag => `symbol-${tag}`).join(', ')}]\n---\n# Core\n`, 'utf8');
+
+  for (let index = 0; index < 105; index++) {
+    const day = String((index % 28) + 1).padStart(2, '0');
+    fs.writeFileSync(path.join(changes, `change-${String(index).padStart(3, '0')}.md`), `---\ntitle: Change ${index}\ntags: [${manyTags.join(', ')}]\naffectedModules: [core, api, ui, worker, storage, release]\nupdatedAt: 2026-07-${day}\ndevelopmentIntent: ${'Long intent '.repeat(80)}\n---\n# Change ${index}\n`, 'utf8');
+  }
+
+  regenerateIndexes(temp);
+  const moduleIndex = fs.readFileSync(path.join(modules, '00-index.md'), 'utf8');
+  const changeIndex = fs.readFileSync(path.join(changes, '00-index.md'), 'utf8');
+
+  assert(!/^Tags:/m.test(moduleIndex), 'module index must not aggregate all tags');
+  assert(!/^Tags:/m.test(changeIndex), 'change index must not aggregate all tags');
+  assert(moduleIndex.startsWith('<!-- Generated by project-knowledge.'), 'generated indexes should identify themselves as derived files');
+  assert(moduleIndex.includes('[Core \\| API](./core.md)'), 'Markdown table links should escape title separators');
+  assert(moduleIndex.includes('tag-0, tag-1, tag-2, tag-3 (+36)'), 'tags should be capped with a remainder count');
+  assert(changeIndex.includes('Items: 105 (showing 40;'), 'large change indexes should be bounded');
+  assert.equal((changeIndex.match(/^\| \[/gm) || []).length, 40, 'only the most recent 40 entries should be listed');
+  assert(Buffer.byteLength(changeIndex, 'utf8') < 30000, 'large generated indexes should stay below 30 KiB');
+  assert(Math.max(...moduleIndex.split(/\r?\n/).map(line => line.length)) < 900, 'module index lines should stay compact');
+  assert(Math.max(...changeIndex.split(/\r?\n/).map(line => line.length)) < 900, 'change index lines should stay compact');
+
+  console.log('index-builder-test: PASS');
+} finally {
+  fs.rmSync(temp, { recursive: true, force: true });
+}