@sanqianx/project-knowledge 4.8.0 → 5.0.0

package/_site/_test/p0-e2e-gate-test.js

@@ -1,347 +0,0 @@
-// _site/_test/p0-e2e-gate-test.js
-//
-// T09: P0 E2E gate. Four scenarios in one sequential run:
-//
-//   A. Fresh project: import -> hook -> commit -> reconciler -> Markdown
-//                     -> analyzed pointer advances.
-//   B. v4.1.22 legacy project: migrate (no re-import) -> hook -> commit
-//                              -> reconciler -> Markdown -> advances.
-//   C. Backend offline: stop -> commit -> restart -> startup recon
-//                       catches up.
-//   D. No conversation captured: commit with no Bridge cursor advance
-//                                still analyzes from Git evidence.
-
-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 { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-const { LEGACY_HOOK_MARKER } = require('../lib/hook-manager');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const BASE_PORT = 7970 + (process.pid % 200);
-
-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();
-}
-
-function makeRepo() {
-  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-repo-' + process.pid + '-'));
-  git(repo, ['init', '-q', '-b', 'main']);
-  git(repo, ['config', 'user.email', 'p0e2e@example.local']);
-  git(repo, ['config', 'user.name', 'P0 E2E']);
-  fs.writeFileSync(path.join(repo, 'README.md'), '# p0\n');
-  git(repo, ['add', 'README.md']);
-  git(repo, ['commit', '-q', '-m', 'baseline']);
-  return repo;
-}
-
-async function serverFetch(server, url, init, timeoutMs = 15000) {
-  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 function waitForState(server, projectId, predicate, label, timeoutMs = 60000) {
-  const deadline = Date.now() + timeoutMs;
-  let last;
-  while (Date.now() < deadline) {
-    try {
-      const r = await serverFetch(server, `${server.base}/api/projects/${projectId}`, undefined);
-      if (r.status === 200) {
-        last = r.body.project.state;
-        if (predicate(last)) return last;
-      }
-    } catch {}
-    await new Promise(resolve => setTimeout(resolve, 200));
-  }
-  throw new Error(`${label} timed out; last=${JSON.stringify(last)}`);
-}
-
-async function waitForHealth(server) {
-  for (let attempt = 0; attempt < 100; attempt += 1) {
-    try { const r = await serverFetch(server, `${server.base}/api/health`, undefined); if (r.body.ok) return; } catch {}
-    await new Promise(resolve => setTimeout(resolve, 100));
-  }
-  throw new Error('server did not start');
-}
-
-async function configureServer(server, dataDir) {
-  await serverFetch(server, `${server.base}/api/settings`, {
-    method: 'PATCH', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ knowledge: { rootPath: path.join(dataDir, 'knowledge') } }),
-  });
-  await serverFetch(server, `${server.base}/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' } }],
-    }),
-  });
-}
-
-async function killServer(server) {
-  if (!server || !server.child) return;
-  server.child.kill();
-  await new Promise(resolve => server.child.once('exit', resolve));
-}
-
-(async () => {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-data-' + process.pid + '-'));
-  const freshRepo = makeRepo();
-  const legacyRepo = makeRepo();
-  // Add a legacy v1 hook to legacyRepo so the migration path includes T03 case 2.
-  {
-    const gitDir = git(legacyRepo, ['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\n${LEGACY_HOOK_MARKER} — legacy\n` +
-      `node 'C:/legacy/_site/scripts/hook-trigger.js' >/dev/null 2>&1 || true\n` +
-      `exit 0\n`
-    ), { mode: 0o755 });
-  }
-  const legacyKbPath = path.join(dataDir, 'knowledge', 'legacy');
-  fs.mkdirSync(legacyKbPath, { recursive: true });
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    'legacy': {
-      schema: 'kb-project/v1',
-      displayName: 'Legacy',
-      localPath: legacyRepo,
-      gitPath: legacyRepo,
-      kbPath: legacyKbPath,
-      trackingStartCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
-      lastAnalyzedCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
-      enabled: true,
-      aiProfileId: 'primary',
-      knowledgeLanguage: 'zh-CN',
-    },
-  }, null, 2));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({
-    schema: 'knowledge-store/v1',
-    rootPath: path.join(dataDir, 'knowledge'), configured: true,
-  }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({
-    schema: 'ai-profiles/v1',
-    profiles: [{ id: 'primary', name: 'Primary', enabled: true, vendor: 'anthropic', model: 'claude-sonnet' }],
-    defaultProfileId: 'primary',
-  }));
-
-  // Scenario A — fresh project
-  const serverA = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-a',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverA.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverA);
-    await configureServer(serverA, dataDir);
-    const importR = await serverFetch(serverA, `${serverA.base}/api/projects/import`, {
-      method: 'POST', headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ localPath: freshRepo, aiProfileId: 'fake', knowledgeLanguage: 'zh-CN' }),
-    });
-    assert.strictEqual(importR.status, 201, JSON.stringify(importR.body));
-    const projectA = importR.body.projectId;
-    const configA = importR.body.config;
-    // Verify hook installed
-    const hookPath = path.join(freshRepo, '.git', 'hooks', 'post-commit');
-    assert(fs.existsSync(hookPath), 'post-commit hook must be installed after import');
-    const hookBody = fs.readFileSync(hookPath, 'utf8');
-    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'hook body must carry the v2 marker');
-    assert(hookBody.includes(projectA), 'hook body must reference the projectId');
-    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract: hook body must prefix ELECTRON_RUN_AS_NODE=1');
-    // Commit a change
-    fs.writeFileSync(path.join(freshRepo, 'feature-a.txt'), 'feature a\n');
-    git(freshRepo, ['add', 'feature-a.txt']);
-    git(freshRepo, ['commit', '-q', '-m', 'scenario-a: feature a']);
-    const headA = git(freshRepo, ['rev-parse', 'HEAD']);
-    // Wait for reconciliation. If the live hook didn't fire (common in
-    // headless test environments), retry by POSTing the hook event
-    // ourselves — this is the same code path the hook runs.
-    let stateA = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headA) {
-          stateA = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateA) {
-      // Retry path: explicitly invoke /api/hooks/post-commit. The reconciler
-      // will run and advance lastAnalyzedCommit.
-      await serverFetch(serverA, `${serverA.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId: projectA, repoRoot: freshRepo,
-          head: headA, branch: 'main', operationId: `op-scenario-a-${Date.now()}`,
-        }),
-      });
-      stateA = await waitForState(serverA, projectA, s => s.lastAnalyzedCommit === headA, 'scenario A reconciliation');
-    }
-    // Give the trailing reconcile work a chance to settle so the post-
-    // fix runSweep does not overwrite analysis.status with 'idle' between
-    // waitForState returning and the assertion reading the state.
-    await new Promise(resolve => setTimeout(resolve, 500));
-    const finalStateA = await (await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined)).body;
-    stateA = finalStateA.project.state;
-    assert.strictEqual(stateA.analysis.activeClaim, null, 'analysis.activeClaim must be null after promotion');
-    assert.strictEqual(stateA.analysis.status, 'state.advanced', 'analysis.status must be state.advanced');
-    assert.strictEqual(stateA.trackingStartCommit, stateA.lastAnalyzedCommit === headA ? stateA.trackingStartCommit : null);
-    // Verify Markdown knowledge
-    const mdPath = path.join(configA.knowledgePath, 'changes', `${headA.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
-  } finally {
-    await killServer(serverA);
-  }
-
-  // Scenario B — v4.1.22 legacy project (migrate, no re-import)
-  // We restart with the SAME dataDir so the migration service picks up the
-  // legacy projects.json. The server's startup will run MigrationService +
-  // migrateManagedHooks.
-  const serverB = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-b',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverB.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverB);
-    await configureServer(serverB, dataDir);
-    const stateList = await serverFetch(serverB, `${serverB.base}/api/state`, undefined);
-    assert.strictEqual(stateList.status, 200);
-    const legacyProject = stateList.body.projects.find(p => p.config.displayName === 'Legacy');
-    assert(legacyProject, 'migrated Legacy project must appear in /api/state without a re-import call');
-    const projectB = legacyProject.projectId;
-    // Verify hook was migrated from v1 to v2
-    const hookPath = path.join(legacyRepo, '.git', 'hooks', 'post-commit');
-    const hookBody = fs.readFileSync(hookPath, 'utf8');
-    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'migrated hook must carry v2 marker');
-    assert(!hookBody.includes(LEGACY_HOOK_MARKER), 'migrated hook must NOT carry the legacy v1 marker');
-    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract applies to migrated hooks too');
-    // Commit a change
-    fs.writeFileSync(path.join(legacyRepo, 'feature-b.txt'), 'feature b\n');
-    git(legacyRepo, ['add', 'feature-b.txt']);
-    git(legacyRepo, ['commit', '-q', '-m', 'scenario-b: feature b']);
-    const headB = git(legacyRepo, ['rev-parse', 'HEAD']);
-    let stateB = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverB, `${serverB.base}/api/projects/${projectB}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headB) {
-          stateB = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateB) {
-      await serverFetch(serverB, `${serverB.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId: projectB, repoRoot: legacyRepo,
-          head: headB, branch: 'main', operationId: `op-scenario-b-${Date.now()}`,
-        }),
-      });
-      stateB = await waitForState(serverB, projectB, s => s.lastAnalyzedCommit === headB, 'scenario B reconciliation');
-    }
-    assert.strictEqual(stateB.analysis.activeClaim, null);
-    const mdPath = path.join(legacyProject.config.knowledgePath, 'changes', `${headB.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
-  } finally {
-    await killServer(serverB);
-  }
-
-  // Scenario C — backend offline, then restart. Restart must preserve facts
-  // but must not infer this missed commit for knowledge analysis.
-  fs.writeFileSync(path.join(legacyRepo, 'feature-c.txt'), 'feature c (offline)\n');
-  git(legacyRepo, ['add', 'feature-c.txt']);
-  git(legacyRepo, ['commit', '-q', '-m', 'scenario-c: offline commit']);
-  const headC = git(legacyRepo, ['rev-parse', 'HEAD']);
-  const serverC = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-c',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverC.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverC);
-    const projectIdC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
-    await new Promise(resolve => setTimeout(resolve, 500));
-    const stateC = (await serverFetch(serverC, `${serverC.base}/api/projects/${projectIdC}`, undefined)).body.project.state;
-    assert.notStrictEqual(stateC.lastAnalyzedCommit, headC, 'startup must not analyze an offline commit');
-    const legacyKbC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
-    assert.strictEqual(fs.existsSync(path.join(legacyKbC, 'changes', `${headC.slice(0, 12)}.md`)), false);
-  } finally {
-    await killServer(serverC);
-  }
-
-  // Scenario D — no conversation captured. With KB_AUTOMATION_FAKE_CLAUDE
-  // the analyzer uses the fake result path that does not depend on the
-  // Bridge cursor advancing; we verify the same flow still produces a
-  // Markdown file from Git evidence alone.
-  fs.writeFileSync(path.join(legacyRepo, 'feature-d.txt'), 'feature d (no conversation)\n');
-  git(legacyRepo, ['add', 'feature-d.txt']);
-  git(legacyRepo, ['commit', '-q', '-m', 'scenario-d: no conversation']);
-  const headD = git(legacyRepo, ['rev-parse', 'HEAD']);
-  const serverD = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-d',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverD.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverD);
-    const projectId = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
-    let stateD = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverD, `${serverD.base}/api/projects/${projectId}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headD) {
-          stateD = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateD) {
-      await serverFetch(serverD, `${serverD.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId, repoRoot: legacyRepo,
-          head: headD, branch: 'main', operationId: `op-scenario-d-${Date.now()}`,
-        }),
-      });
-      stateD = await waitForState(serverD, projectId, s => s.lastAnalyzedCommit === headD, 'scenario D reconciliation without conversation');
-    }
-    const legacyKb = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
-    const mdPath = path.join(legacyKb, 'changes', `${headD.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `scenario D must still produce Markdown at ${mdPath}`);
-  } finally {
-    await killServer(serverD);
-    fs.rmSync(dataDir, { recursive: true, force: true });
-    fs.rmSync(freshRepo, { recursive: true, force: true });
-    fs.rmSync(legacyRepo, { recursive: true, force: true });
-  }
-  console.log('p0-e2e-gate-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exit(1);
-});

package/_site/_test/project-layout-v2-migration-test.js

@@ -1,127 +0,0 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-
-function fixture() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-migration-'));
-  const oldRoot = path.join(dataDir, 'old-knowledge');
-  const differentRoot = path.join(dataDir, 'different-current-root');
-  fs.mkdirSync(oldRoot, { recursive: true });
-  const exactKbPath = path.join(oldRoot, 'legacy-a-fixed');
-  fs.mkdirSync(exactKbPath, { recursive: true });
-  fs.writeFileSync(path.join(exactKbPath, 'README.md'), '# existing knowledge\n', 'utf8');
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    legacyA: {
-      displayName: 'Legacy A',
-      localPath: path.join(dataDir, 'repo-a'),
-      gitPath: path.join(dataDir, 'repo-a'),
-      kbPath: exactKbPath,
-      trackingStartCommit: 'track-a',
-      lastAnalyzedCommit: 'last-a',
-      enabled: true,
-      aiProfileId: 'primary',
-    },
-    legacyB: {
-      displayName: 'Legacy B',
-      localPath: path.join(dataDir, 'repo-b'),
-      trackingStartCommit: 'track-b',
-      enabled: true,
-    },
-  }, null, 2));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: differentRoot, configured: true }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'exact-secret-value' }] }));
-  fs.writeFileSync(path.join(dataDir, 'embedding-config.json'), JSON.stringify({ modelId: 'model-a' }));
-  fs.writeFileSync(path.join(dataDir, 'logging.json'), JSON.stringify({ levels: ['debug', 'info', 'error'], retentionDays: 0, maxTotalSizeMB: 512 }));
-  fs.writeFileSync(path.join(dataDir, 'claude-prompts.json'), JSON.stringify({ hookPromptTemplate: 'legacy override' }));
-  fs.writeFileSync(path.join(dataDir, '.hook-trigger-errors.log'), '2026-01-01 old hook error\n');
-  return { dataDir, exactKbPath, differentRoot };
-}
-
-(async () => {
-  {
-    const { dataDir, exactKbPath, differentRoot } = fixture();
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'layout-v2-success' });
-    assert.strictEqual(result.ok, true);
-    assert.strictEqual(result.completed, true);
-    assert(fs.existsSync(layout.getMigrationCompletionPath()));
-    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
-    assert.strictEqual(registry.schema, 'project-registry/v2');
-    assert.strictEqual(registry.projectOrder.length, 2);
-    const idA = result.projectMap.legacyA;
-    const idB = result.projectMap.legacyB;
-    const configA = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idA), 'utf8'));
-    const configB = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idB), 'utf8'));
-    const stateA = JSON.parse(fs.readFileSync(layout.getProjectStatePath(idA), 'utf8'));
-    assert.strictEqual(configA.knowledgePath, exactKbPath, 'old kbPath must remain exact');
-    assert.strictEqual(configB.knowledgePath, path.join(differentRoot, 'legacyB'));
-    assert.strictEqual(stateA.trackingStartCommit, 'track-a');
-    assert.strictEqual(stateA.lastAnalyzedCommit, 'last-a');
-    const settings = JSON.parse(fs.readFileSync(layout.getSettingsPath(), 'utf8'));
-    assert.strictEqual(settings.ai.profiles[0].apiKey, 'exact-secret-value');
-    assert.strictEqual(Object.prototype.hasOwnProperty.call(settings.logging, 'retentionDays'), false);
-    assert.strictEqual(settings.legacyExtensions.logging.retentionDays, 0, 'legacy logging settings remain preserved as read-only migration evidence');
-    assert(fs.existsSync(path.join(result.recoveryDir, 'backup', 'projects.json')));
-    assert(fs.existsSync(path.join(dataDir, '.hook-trigger-errors.log')), 'legacy hook log must remain');
-    const second = await migration.migrateIfNeeded();
-    assert.strictEqual(second.completed, true);
-    assert.strictEqual(second.migrated, false);
-  }
-
-  for (const stage of ['backup', 'staging', 'validation', 'activation', 'open-verification']) {
-    const { dataDir } = fixture();
-    const originalProjects = fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8');
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: `fault-${stage}`, faultAt: stage });
-    assert.strictEqual(result.ok, false, `${stage} should fail`);
-    assert.strictEqual(result.useLegacy, true);
-    assert.strictEqual(fs.existsSync(layout.getMigrationCompletionPath()), false, `${stage} must not write completion`);
-    assert.strictEqual(fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8'), originalProjects, `${stage} must preserve/restore legacy registry`);
-    const journal = JSON.parse(fs.readFileSync(path.join(result.recoveryDir, 'journal.json'), 'utf8'));
-    assert.strictEqual(journal.phase, 'failed');
-    assert.strictEqual(journal.rollback.ok, true, `${stage} rollback must complete`);
-    assert.strictEqual(fs.existsSync(layout.getSettingsPath()), false, `${stage} must remove newly activated settings`);
-    assert.strictEqual(fs.existsSync(path.join(dataDir, 'projects')), false, `${stage} must remove newly activated project metadata`);
-    if (['activation', 'open-verification'].includes(stage)) {
-      const retry = await migration.migrateIfNeeded({ migrationRunId: `retry-${stage}` });
-      assert.strictEqual(retry.ok, true, `${stage} must be safely retryable after rollback`);
-      assert.strictEqual(retry.completed, true);
-    }
-  }
-
-  {
-    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-fresh-'));
-    const layout = new StorageLayout({ dataDir });
-    const result = await new MigrationService({ layout }).migrateIfNeeded();
-    assert.strictEqual(result.reason, 'fresh-install');
-    assert.strictEqual(fs.existsSync(layout.getRecoveryPath()), false, 'fresh install must not create optional recovery dir');
-  }
-
-  {
-    // Regression: legacy files carrying a UTF-8 BOM (common from PowerShell
-    // tooling) must migrate cleanly instead of failing as corrupt sources.
-    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-bom-'));
-    const layout = new StorageLayout({ dataDir });
-    const bom = Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(JSON.stringify({
-      legacyA: { displayName: 'BOM A', localPath: path.join(dataDir, 'repo-a'), trackingStartCommit: 'track-a', enabled: true }
-    }), 'utf8')]);
-    fs.writeFileSync(path.join(dataDir, 'projects.json'), bom);
-    fs.writeFileSync(path.join(dataDir, 'team-git-providers.json'), Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from('{}', 'utf8')]));
-    const result = await new MigrationService({ layout, legacyDataDir: dataDir }).migrateIfNeeded();
-    assert.strictEqual(result.ok, true, 'BOM-prefixed legacy sources must migrate');
-    assert.strictEqual(result.migrated, true);
-    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
-    assert.strictEqual(registry.schema, 'project-registry/v2');
-    assert.strictEqual(Object.keys(registry.projects).length, 1);
-  }
-
-  console.log('project-layout-v2-migration-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});

package/_site/_test/server-runtime-migration-safety-test.js

@@ -1,27 +0,0 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { initializeRuntime } = require('../lib/server-app');
-
-const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-runtime-migration-safety-'));
-let settingsInitialized = false;
-let registryInitialized = false;
-const runtime = {
-  rootDir: path.join(root, 'missing-legacy-root'),
-  dataPath: path.join(root, 'data'),
-  logger: { info: async () => {} },
-  migrationService: { migrateIfNeeded: async () => ({ ok: false, requiresManualRecovery: true, reason: 'fault-injected' }) },
-  settingsStore: { initialize: async () => { settingsInitialized = true; } },
-  registryStore: { initialize: async () => { registryInitialized = true; } },
-};
-
-initializeRuntime(runtime).then(() => {
-  throw new Error('initializeRuntime must reject an unsuccessful migration');
-}).catch(error => {
-  assert.equal(error.code, 'MIGRATION_FAILED');
-  assert.equal(settingsInitialized, false, 'settings defaults must not be initialized after migration failure');
-  assert.equal(registryInitialized, false, 'empty project registry must not be initialized after migration failure');
-  fs.rmSync(root, { recursive: true, force: true });
-  console.log('server-runtime-migration-safety-test PASS');
-});

package/_site/_test/v4122-upgrade-data-contract-test.js

@@ -1,56 +0,0 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-const { publicAiProfilesConfig } = require('../lib/contracts');
-
-function fixture() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-v4122-upgrade-'));
-  const knowledgeRoot = path.join(dataDir, 'knowledge-root');
-  const projects = {};
-  for (const slug of ['alpha', 'beta', 'gamma']) {
-    const repoPath = path.join(dataDir, 'repos', slug);
-    const knowledgePath = path.join(knowledgeRoot, `preserved-${slug}`);
-    fs.mkdirSync(knowledgePath, { recursive: true });
-    fs.writeFileSync(path.join(knowledgePath, 'README.md'), `# ${slug}\n`);
-    projects[slug] = { repoPath, kbPath: knowledgePath, aiProfileId: slug === 'alpha' ? 'primary' : 'secondary' };
-  }
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify(projects));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: knowledgeRoot }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ profiles: [
-    { id: 'primary', apiKey: 'fixture-secret-one', model: 'model-a' },
-    { id: 'secondary', apiKey: 'fixture-secret-two', model: 'model-b' },
-  ] }));
-  fs.writeFileSync(path.join(dataDir, 'embedding-config.json'), JSON.stringify({ modelId: 'embedding-v4122', localFilesOnly: true, localModelPath: path.join(dataDir, 'models') }));
-  fs.mkdirSync(path.join(dataDir, 'models', 'A', 'B'), { recursive: true });
-  fs.writeFileSync(path.join(dataDir, 'models', 'A', 'B', 'model.onnx'), 'exact-model-content');
-  return { dataDir, knowledgeRoot, projects };
-}
-
-(async () => {
-  const { dataDir, knowledgeRoot, projects } = fixture();
-  try {
-    const layout = new StorageLayout({ dataDir });
-    const result = await new MigrationService({ layout, legacyDataDir: dataDir }).migrateIfNeeded({ migrationRunId: 'v4122-contract' });
-    assert.equal(result.ok, true);
-    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
-    assert.equal(registry.projectOrder.length, 3);
-    const settings = JSON.parse(fs.readFileSync(layout.getSettingsPath(), 'utf8'));
-    assert.equal(settings.knowledge.rootPath, knowledgeRoot);
-    assert.deepEqual(settings.embedding, { modelId: 'embedding-v4122', localFilesOnly: true, localModelPath: path.join(dataDir, 'models') });
-    assert.equal(settings.ai.profiles.length, 2);
-    assert.equal(publicAiProfilesConfig(settings.ai).profiles.every(profile => profile.hasApiKey && !Object.hasOwn(profile, 'apiKey')), true);
-    for (const projectId of registry.projectOrder) {
-      const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-      const legacy = projects[config.legacyExtensions.slug];
-      assert.equal(config.repoPath, legacy.repoPath);
-      assert.equal(config.knowledgePath, legacy.kbPath);
-    }
-    assert.equal(fs.readFileSync(path.join(dataDir, 'cache', 'models', 'A', 'B', 'model.onnx'), 'utf8'), 'exact-model-content');
-    assert.equal(result.marker.projectCount, 3);
-    assert.equal(result.marker.aiProfileCount, 2);
-  } finally { fs.rmSync(dataDir, { recursive: true, force: true }); }
-  console.log('v4122-upgrade-data-contract-test PASS');
-})().catch(error => { console.error(error.stack || error.message); process.exit(1); });

package/_site/lib/data-state-classifier.js

@@ -1,40 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const { SCHEMAS } = require('./contracts');
-const { LEGACY_ASSETS, assetPath } = require('./legacy-data-manifest');
-
-const STATES = Object.freeze({ FRESH: 'FRESH', LEGACY: 'LEGACY', V2_VALID: 'V2_VALID', MIGRATION_INCOMPLETE: 'MIGRATION_INCOMPLETE', CONFLICT: 'CONFLICT', CORRUPT: 'CORRUPT' });
-
-function readJson(filePath) {
-  if (!fs.existsSync(filePath)) return { exists: false, value: null };
-  try { const raw = fs.readFileSync(filePath, 'utf8'); return { exists: true, value: JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw) }; }
-  catch (error) { return { exists: true, error }; }
-}
-function isEmptyJson(value) {
-  if (value == null || typeof value !== 'object') return false;
-  if (Array.isArray(value)) return value.length === 0;
-  if (value.schema === SCHEMAS.projectRegistry) return Array.isArray(value.projectOrder) && value.projectOrder.length === 0;
-  return Object.keys(value).length === 0;
-}
-function hasRecovery(root) { const recovery = path.join(root, 'recovery'); return fs.existsSync(recovery) && fs.statSync(recovery).isDirectory() && fs.readdirSync(recovery).length > 0; }
-function classifyDataState(root) {
-  const projects = readJson(path.join(root, 'projects.json'));
-  const settings = readJson(path.join(root, 'settings.json'));
-  if (projects.error || settings.error) return { state: STATES.CORRUPT, projects, settings };
-  // Logs and hook diagnostics can be created before startup classification;
-  // alone they are not user configuration evidence and must not turn a clean
-  // install into an impossible legacy migration.
-  const hasLegacyAssets = LEGACY_ASSETS.some(asset => asset.authority !== 'history' && fs.existsSync(assetPath(root, asset)));
-  const isV2 = projects.value && projects.value.schema === SCHEMAS.projectRegistry && projects.value.schemaVersion === 2;
-  const settingsV2 = settings.value && settings.value.schema === SCHEMAS.settings && settings.value.schemaVersion === 2;
-  if (isV2 && settingsV2) return { state: STATES.V2_VALID, projects, settings, hasLegacyAssets };
-  // A failed migration may have written default v2 settings before activation.
-  // A non-v2 projects registry remains authoritative legacy evidence and is
-  // eligible for a controlled retry; it must never be classified as Fresh.
-  if (projects.exists && !isV2 && hasLegacyAssets) return { state: STATES.LEGACY, projects, settings, hasLegacyAssets };
-  if (isV2 || settingsV2 || hasRecovery(root)) return { state: STATES.MIGRATION_INCOMPLETE, projects, settings, hasLegacyAssets };
-  if (hasLegacyAssets) return { state: STATES.LEGACY, projects, settings, hasLegacyAssets };
-  return { state: STATES.FRESH, projects, settings, hasLegacyAssets };
-}
-
-module.exports = { STATES, readJson, isEmptyJson, classifyDataState };