@sanqianx/project-knowledge 5.0.18 → 5.0.20-rc.1

package/_site/_test/simple-import-test.js

@@ -1,98 +1,98 @@
-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 freePort = require('./helpers/free-port');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-let PORT, BASE;
-const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-v2-'));
-const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-repo-'));
-const knowledgeRoot = path.join(dataDir, 'knowledge');
-
-function git(args) {
-  const result = spawnSync('git', args, { cwd: repoPath, encoding: 'utf8' });
-  assert.strictEqual(result.status, 0, result.stderr);
-  return String(result.stdout || '').trim();
-}
-
-async function request(method, pathname, body) {
-  const response = await fetch(`${BASE}${pathname}`, {
-    method,
-    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  return { status: response.status, data: await response.json() };
-}
-
-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 () => {
-  PORT = await freePort(); BASE = `http://127.0.0.1:${PORT}`;
-  git(['init', '--initial-branch=main']);
-  git(['config', 'user.email', 'import@example.test']);
-  git(['config', 'user.name', 'Import Test']);
-  fs.writeFileSync(path.join(repoPath, 'README.md'), '# source\n', 'utf8');
-  git(['add', 'README.md']);
-  git(['commit', '-m', 'baseline']);
-  const baseline = git(['rev-parse', 'HEAD']);
-
-  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'simple-import-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
-  let output = '';
-  spawned.child.stdout.on('data', chunk => { output += chunk; });
-  spawned.child.stderr.on('data', chunk => { output += chunk; });
-  try {
-    await waitForServer();
-    let result = await request('PATCH', '/api/settings', { knowledge: { rootPath: knowledgeRoot } });
-    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
-
-    result = await request('POST', '/api/projects/import', { localPath: repoPath, displayName: 'Imported v2' });
-    assert.strictEqual(result.status, 201, JSON.stringify(result.data));
-    assert.match(result.data.projectId, /^project-/);
-    assert.strictEqual(result.data.project.config.projectId, result.data.projectId);
-    assert.strictEqual(result.data.project.state.trackingStartCommit, baseline);
-    assert.strictEqual(result.data.project.state.lastAnalyzedCommit, null);
-    assert.strictEqual(result.data.project.state.analysis.status, 'idle');
-    assert.strictEqual(result.data.hook.ok, true);
-    assert.strictEqual(result.data.project.state.hook.managedVersion, 2);
-    assert.deepStrictEqual(fs.readdirSync(result.data.project.config.knowledgePath), [], 'import must not create speculative knowledge');
-    assert(!fs.existsSync(path.join(dataDir, 'projects', result.data.projectId, 'requirements.jsonl')));
-
-    const projectId = result.data.projectId;
-    result = await request('PATCH', `/api/projects/${projectId}`, { displayName: 'Renamed safely', knowledgeLanguage: 'en-US' });
-    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
-    assert.strictEqual(result.data.config.displayName, 'Renamed safely');
-    result = await request('PATCH', `/api/projects/${projectId}`, { repoPath: path.join(repoPath, 'unverified') });
-    assert.strictEqual(result.status, 400, 'generic PATCH must not bypass Hook-verified repo relocation');
-    assert.strictEqual(result.data.error.code, 'INVALID_ARGUMENT');
-    result = await request('PATCH', `/api/projects/${projectId}`, { teamBinding: { provider: 'github' } });
-    assert.strictEqual(result.status, 400, 'generic PATCH must not change a fixed team binding');
-
-    const hookPath = path.join(repoPath, '.git', 'hooks', 'post-commit');
-    assert(fs.existsSync(hookPath), 'managed Hook was not installed');
-    const hook = fs.readFileSync(hookPath, 'utf8');
-    assert(hook.includes('PROJECT-KNOWLEDGE-HOOK'));
-    assert(hook.includes(projectId));
-
-    result = await request('GET', '/api/projects');
-    assert.strictEqual(result.status, 200);
-    assert.strictEqual(result.data.projects.length, 1);
-    assert.strictEqual(result.data.projects[0].projectId, result.data.projects[0].config.projectId);
-    assert(!fs.existsSync(path.join(dataDir, 'runtime', 'staging')), 'import must not dispatch analysis');
-    console.log('simple-import-test PASS');
-  } catch (error) {
-    console.error(output);
-    throw error;
-  } finally {
-    await spawned.cleanup();
-    fs.rmSync(repoPath, { recursive: true, force: true });
-  }
-})().catch(error => { console.error(error); process.exitCode = 1; });
+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 freePort = require('./helpers/free-port');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+let PORT, BASE;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-v2-'));
+const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-repo-'));
+const knowledgeRoot = path.join(dataDir, 'knowledge');
+
+function git(args) {
+  const result = spawnSync('git', args, { cwd: repoPath, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return String(result.stdout || '').trim();
+}
+
+async function request(method, pathname, body) {
+  const response = await fetch(`${BASE}${pathname}`, {
+    method,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: response.status, data: await response.json() };
+}
+
+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 () => {
+  PORT = await freePort(); BASE = `http://127.0.0.1:${PORT}`;
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.email', 'import@example.test']);
+  git(['config', 'user.name', 'Import Test']);
+  fs.writeFileSync(path.join(repoPath, 'README.md'), '# source\n', 'utf8');
+  git(['add', 'README.md']);
+  git(['commit', '-m', 'baseline']);
+  const baseline = git(['rev-parse', 'HEAD']);
+
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'simple-import-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  let output = '';
+  spawned.child.stdout.on('data', chunk => { output += chunk; });
+  spawned.child.stderr.on('data', chunk => { output += chunk; });
+  try {
+    await waitForServer();
+    let result = await request('PATCH', '/api/settings', { knowledge: { rootPath: knowledgeRoot } });
+    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
+
+    result = await request('POST', '/api/projects/import', { localPath: repoPath, displayName: 'Imported v2' });
+    assert.strictEqual(result.status, 201, JSON.stringify(result.data));
+    assert.match(result.data.projectId, /^project-/);
+    assert.strictEqual(result.data.project.config.projectId, result.data.projectId);
+    assert.strictEqual(result.data.project.state.trackingStartCommit, baseline);
+    assert.strictEqual(result.data.project.state.lastAnalyzedCommit, null);
+    assert.strictEqual(result.data.project.state.analysis.status, 'idle');
+    assert.strictEqual(result.data.hook.ok, true);
+    assert.strictEqual(result.data.project.state.hook.managedVersion, 2);
+    assert.deepStrictEqual(fs.readdirSync(result.data.project.config.knowledgePath), [], 'import must not create speculative knowledge');
+    assert(!fs.existsSync(path.join(dataDir, 'projects', result.data.projectId, 'requirements.jsonl')));
+
+    const projectId = result.data.projectId;
+    result = await request('PATCH', `/api/projects/${projectId}`, { displayName: 'Renamed safely', knowledgeLanguage: 'en-US' });
+    assert.strictEqual(result.status, 200, JSON.stringify(result.data));
+    assert.strictEqual(result.data.config.displayName, 'Renamed safely');
+    result = await request('PATCH', `/api/projects/${projectId}`, { repoPath: path.join(repoPath, 'unverified') });
+    assert.strictEqual(result.status, 400, 'generic PATCH must not bypass Hook-verified repo relocation');
+    assert.strictEqual(result.data.error.code, 'INVALID_ARGUMENT');
+    result = await request('PATCH', `/api/projects/${projectId}`, { teamBinding: { provider: 'github' } });
+    assert.strictEqual(result.status, 400, 'generic PATCH must not change a fixed team binding');
+
+    const hookPath = path.join(repoPath, '.git', 'hooks', 'post-commit');
+    assert(fs.existsSync(hookPath), 'managed Hook was not installed');
+    const hook = fs.readFileSync(hookPath, 'utf8');
+    assert(hook.includes('PROJECT-KNOWLEDGE-HOOK'));
+    assert(hook.includes(projectId));
+
+    result = await request('GET', '/api/projects');
+    assert.strictEqual(result.status, 200);
+    assert.strictEqual(result.data.projects.length, 1);
+    assert.strictEqual(result.data.projects[0].projectId, result.data.projects[0].config.projectId);
+    assert(!fs.existsSync(path.join(dataDir, 'runtime', 'staging')), 'import must not dispatch analysis');
+    console.log('simple-import-test PASS');
+  } catch (error) {
+    console.error(output);
+    throw error;
+  } finally {
+    await spawned.cleanup();
+    fs.rmSync(repoPath, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/startup-analysis-disabled-test.js

@@ -8,9 +8,9 @@ const contracts = require('../lib/contracts');
 const automation = require('../lib/post-commit-automation');
 
 assert.deepEqual(contracts.TRIGGERS, ['git-hook']);
-assert.equal(/reconcileProjectCommits\(projectId, 'startup'/.test(server), false);
-assert.equal(server.includes('reconcile.startup_failed'), false);
-assert.equal(Object.hasOwn(automation, 'dispatchPendingAutomations'), false);
-assert.equal(typeof automation.recoverOrphanedClaims, 'function');
-assert.equal(/recoverOrphanedClaims\(runtime\)/.test(server), true);
-console.log('startup-analysis-disabled-test PASS');
+assert.equal(/reconcileProjectCommits\(projectId, 'startup'/.test(server), false);
+assert.equal(server.includes('reconcile.startup_failed'), false);
+assert.equal(Object.hasOwn(automation, 'dispatchPendingAutomations'), false);
+assert.equal(typeof automation.recoverOrphanedClaims, 'function');
+assert.equal(/recoverOrphanedClaims\(runtime\)/.test(server), true);
+console.log('startup-analysis-disabled-test PASS');

package/_site/_test/team-knowledge-store-sparse-checkout-test.js

@@ -1,196 +1,196 @@
-// Tests for sparse-checkout automation in github-team-store.js.
-// Style mirrors team-knowledge-store-test.js (IIFE + assert()).
-//
-// Three scenarios:
-//   1. New sparse clone — checkoutStore({ subdir, partialClone }) clones with
-//      --filter=blob:none --sparse --no-checkout, applies cone, and materializes
-//      only the requested subdirectory.
-//   2. Re-clone / switch — calling checkoutStore twice on the same local path
-//      re-applies sparse-checkout cone (idempotent).
-//   3. Git version fallback — _setGitVersionForTests forces a low version; the
-//      partial-clone branch must fall back to a full clone and return warning.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const githubTeamStore = require('../lib/github-team-store');
-const gitRunner = require('../lib/git-runner');
-
-function assert(cond, msg) {
-  if (!cond) throw new Error(msg);
-}
-
-function git(cwd, args) {
-  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf-8').trim();
-}
-
-function initBareRemote(cwd) {
-  fs.mkdirSync(cwd, { recursive: true });
-  git(cwd, ['init', '--bare']);
-}
-
-function seedRemoteWith(cwd, files) {
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-seed-${process.pid}-`));
-  git(work, ['init']);
-  git(work, ['config', 'user.name', 'Test User']);
-  git(work, ['config', 'user.email', 'test@example.com']);
-  for (const [relPath, content] of Object.entries(files)) {
-    const abs = path.join(work, relPath);
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, content);
-  }
-  git(work, ['add', '-A']);
-  git(work, ['commit', '-m', 'seed']);
-  git(work, ['branch', '-M', 'main']);
-  const head = git(work, ['rev-parse', 'HEAD']);
-  git(cwd, ['symbolic-ref', 'HEAD', 'refs/heads/main']);
-  const pushTarget = `file://${path.resolve(cwd)}`;
-  git(work, ['remote', 'add', 'origin', pushTarget]);
-  git(work, ['push', 'origin', 'main']);
-  return { work, head };
-}
-
-async function run() {
-  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `kb-team-sparse-${process.pid}-`));
-  const TEAM_REMOTE_SPARSE = path.join(tmpRoot, 'remote-sparse.git');
-  const LOCAL_CLONE = path.join(tmpRoot, 'local-clone');
-  const remoteUrl = `file://${TEAM_REMOTE_SPARSE.replace(/\\/g, '/')}`;
-
-  let scenariosPassed = 0;
-  let scenariosTotal = 0;
-
-  // ------------------------------------------------------------------
-  // Scenario 1: New sparse clone
-  // ------------------------------------------------------------------
-  {
-    scenariosTotal++;
-    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
-    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
-    initBareRemote(TEAM_REMOTE_SPARSE);
-    seedRemoteWith(TEAM_REMOTE_SPARSE, {
-      'acc/README.md': '# acc\n',
-      'other/README.md': '# other\n',
-      'docs/notes.md': 'docs\n',
-    });
-
-    const result = await githubTeamStore.checkoutStore({
-      cloneUrl: remoteUrl,
-      branch: 'main',
-      localPath: LOCAL_CLONE,
-      subdir: 'acc',
-      partialClone: true,
-    });
-
-    assert(result.ok, `[scenario 1] checkoutStore should succeed: ${result.error || ''}`);
-    assert(result.action === 'cloned-partial', `[scenario 1] expected action='cloned-partial' but got '${result.action}'`);
-    assert(result.sparseCheckedOut === true, '[scenario 1] sparseCheckedOut should be true');
-    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 1] acc/README.md should exist');
-    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 1] other/README.md should NOT exist (cone excluded)');
-    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'docs', 'notes.md')), '[scenario 1] docs/notes.md should NOT exist (cone excluded)');
-    const sparseFile = path.join(LOCAL_CLONE, '.git', 'info', 'sparse-checkout');
-    assert(fs.existsSync(sparseFile), '[scenario 1] .git/info/sparse-checkout should be present');
-    scenariosPassed++;
-    console.log('[scenario 1: NEW sparse clone] OK');
-  }
-
-  // ------------------------------------------------------------------
-  // Scenario 2: Re-clone / add cone
-  // ------------------------------------------------------------------
-  {
-    scenariosTotal++;
-    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
-    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
-    initBareRemote(TEAM_REMOTE_SPARSE);
-    seedRemoteWith(TEAM_REMOTE_SPARSE, {
-      'acc/README.md': '# acc\n',
-      'other/README.md': '# other\n',
-    });
-    // First clone with subdir='acc'
-    const first = await githubTeamStore.checkoutStore({
-      cloneUrl: remoteUrl,
-      branch: 'main',
-      localPath: LOCAL_CLONE,
-      subdir: 'acc',
-      partialClone: true,
-    });
-    assert(first.ok && first.action === 'cloned-partial', `[scenario 2] first clone should be partial`);
-    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should exist after first clone');
-
-    // Add a new subdir to remote
-    const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-switch-${process.pid}-`));
-    fs.rmSync(work, { recursive: true, force: true });
-    fs.mkdirSync(work, { recursive: true });
-    git(work, ['clone', `file://${TEAM_REMOTE_SPARSE}`, '.']);
-    git(work, ['config', 'user.name', 'Test User']);
-    git(work, ['config', 'user.email', 'test@example.com']);
-    fs.mkdirSync(path.join(work, 'acc2'), { recursive: true });
-    fs.writeFileSync(path.join(work, 'acc2', 'README.md'), '# acc2\n');
-    git(work, ['add', '-A']);
-    git(work, ['commit', '-m', 'add acc2']);
-    git(work, ['push']);
-
-    // Re-sync with subdir='acc2' should expand the cone, not remove acc.
-    const second = await githubTeamStore.checkoutStore({
-      cloneUrl: remoteUrl,
-      branch: 'main',
-      localPath: LOCAL_CLONE,
-      subdir: 'acc2',
-      partialClone: true,
-    });
-    assert(second.ok, `[scenario 2] second checkout should succeed: ${second.error || ''}`);
-    assert(second.action === 'pulled-partial', `[scenario 2] expected action='pulled-partial' but got '${second.action}'`);
-    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc2', 'README.md')), '[scenario 2] acc2/README.md should exist after adding cone');
-    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should still exist after adding acc2');
-    scenariosPassed++;
-    console.log('[scenario 2: cone expand] OK');
-  }
-
-  // ------------------------------------------------------------------
-  // Scenario 3: Git version fallback
-  // ------------------------------------------------------------------
-  {
-    scenariosTotal++;
-    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
-    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
-    initBareRemote(TEAM_REMOTE_SPARSE);
-    seedRemoteWith(TEAM_REMOTE_SPARSE, {
-      'acc/README.md': '# acc\n',
-      'other/README.md': '# other\n',
-    });
-
-    // Force the cached version to be < 2.25
-    gitRunner._setGitVersionForTests({ ok: true, major: 2, minor: 24, raw: 'git version 2.24.0' });
-    try {
-      const result = await githubTeamStore.checkoutStore({
-        cloneUrl: remoteUrl,
-        branch: 'main',
-        localPath: LOCAL_CLONE,
-        subdir: 'acc',
-        partialClone: true,
-      });
-      assert(result.ok, `[scenario 3] checkoutStore should fall back to full clone: ${result.error || ''}`);
-      assert(result.action === 'cloned-fallback', `[scenario 3] expected action='cloned-fallback' but got '${result.action}'`);
-      assert(typeof result.warning === 'string' && /2\.25/.test(result.warning), `[scenario 3] warning should mention 2.25: ${result.warning || ''}`);
-      // Full clone means both subdirs ARE present.
-      assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 3] acc/README.md should exist (full clone)');
-      assert(fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 3] other/README.md should exist (full clone)');
-      scenariosPassed++;
-      console.log('[scenario 3: Git < 2.25 fallback] OK');
-    } finally {
-      gitRunner._setGitVersionForTests(null);
-    }
-  }
-
-  console.log(`\nsummary: ${scenariosPassed}/${scenariosTotal} scenarios passed`);
-  if (scenariosPassed !== scenariosTotal) {
-    process.exitCode = 1;
-  }
-}
-
-run().catch(err => {
-  console.error('test failed:', err.message);
-  console.error(err.stack);
-  process.exitCode = 1;
-});
+// Tests for sparse-checkout automation in github-team-store.js.
+// Style mirrors team-knowledge-store-test.js (IIFE + assert()).
+//
+// Three scenarios:
+//   1. New sparse clone — checkoutStore({ subdir, partialClone }) clones with
+//      --filter=blob:none --sparse --no-checkout, applies cone, and materializes
+//      only the requested subdirectory.
+//   2. Re-clone / switch — calling checkoutStore twice on the same local path
+//      re-applies sparse-checkout cone (idempotent).
+//   3. Git version fallback — _setGitVersionForTests forces a low version; the
+//      partial-clone branch must fall back to a full clone and return warning.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const githubTeamStore = require('../lib/github-team-store');
+const gitRunner = require('../lib/git-runner');
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg);
+}
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf-8').trim();
+}
+
+function initBareRemote(cwd) {
+  fs.mkdirSync(cwd, { recursive: true });
+  git(cwd, ['init', '--bare']);
+}
+
+function seedRemoteWith(cwd, files) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-seed-${process.pid}-`));
+  git(work, ['init']);
+  git(work, ['config', 'user.name', 'Test User']);
+  git(work, ['config', 'user.email', 'test@example.com']);
+  for (const [relPath, content] of Object.entries(files)) {
+    const abs = path.join(work, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  git(work, ['add', '-A']);
+  git(work, ['commit', '-m', 'seed']);
+  git(work, ['branch', '-M', 'main']);
+  const head = git(work, ['rev-parse', 'HEAD']);
+  git(cwd, ['symbolic-ref', 'HEAD', 'refs/heads/main']);
+  const pushTarget = `file://${path.resolve(cwd)}`;
+  git(work, ['remote', 'add', 'origin', pushTarget]);
+  git(work, ['push', 'origin', 'main']);
+  return { work, head };
+}
+
+async function run() {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `kb-team-sparse-${process.pid}-`));
+  const TEAM_REMOTE_SPARSE = path.join(tmpRoot, 'remote-sparse.git');
+  const LOCAL_CLONE = path.join(tmpRoot, 'local-clone');
+  const remoteUrl = `file://${TEAM_REMOTE_SPARSE.replace(/\\/g, '/')}`;
+
+  let scenariosPassed = 0;
+  let scenariosTotal = 0;
+
+  // ------------------------------------------------------------------
+  // Scenario 1: New sparse clone
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+      'docs/notes.md': 'docs\n',
+    });
+
+    const result = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc',
+      partialClone: true,
+    });
+
+    assert(result.ok, `[scenario 1] checkoutStore should succeed: ${result.error || ''}`);
+    assert(result.action === 'cloned-partial', `[scenario 1] expected action='cloned-partial' but got '${result.action}'`);
+    assert(result.sparseCheckedOut === true, '[scenario 1] sparseCheckedOut should be true');
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 1] acc/README.md should exist');
+    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 1] other/README.md should NOT exist (cone excluded)');
+    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'docs', 'notes.md')), '[scenario 1] docs/notes.md should NOT exist (cone excluded)');
+    const sparseFile = path.join(LOCAL_CLONE, '.git', 'info', 'sparse-checkout');
+    assert(fs.existsSync(sparseFile), '[scenario 1] .git/info/sparse-checkout should be present');
+    scenariosPassed++;
+    console.log('[scenario 1: NEW sparse clone] OK');
+  }
+
+  // ------------------------------------------------------------------
+  // Scenario 2: Re-clone / add cone
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+    });
+    // First clone with subdir='acc'
+    const first = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc',
+      partialClone: true,
+    });
+    assert(first.ok && first.action === 'cloned-partial', `[scenario 2] first clone should be partial`);
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should exist after first clone');
+
+    // Add a new subdir to remote
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-switch-${process.pid}-`));
+    fs.rmSync(work, { recursive: true, force: true });
+    fs.mkdirSync(work, { recursive: true });
+    git(work, ['clone', `file://${TEAM_REMOTE_SPARSE}`, '.']);
+    git(work, ['config', 'user.name', 'Test User']);
+    git(work, ['config', 'user.email', 'test@example.com']);
+    fs.mkdirSync(path.join(work, 'acc2'), { recursive: true });
+    fs.writeFileSync(path.join(work, 'acc2', 'README.md'), '# acc2\n');
+    git(work, ['add', '-A']);
+    git(work, ['commit', '-m', 'add acc2']);
+    git(work, ['push']);
+
+    // Re-sync with subdir='acc2' should expand the cone, not remove acc.
+    const second = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc2',
+      partialClone: true,
+    });
+    assert(second.ok, `[scenario 2] second checkout should succeed: ${second.error || ''}`);
+    assert(second.action === 'pulled-partial', `[scenario 2] expected action='pulled-partial' but got '${second.action}'`);
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc2', 'README.md')), '[scenario 2] acc2/README.md should exist after adding cone');
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should still exist after adding acc2');
+    scenariosPassed++;
+    console.log('[scenario 2: cone expand] OK');
+  }
+
+  // ------------------------------------------------------------------
+  // Scenario 3: Git version fallback
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+    });
+
+    // Force the cached version to be < 2.25
+    gitRunner._setGitVersionForTests({ ok: true, major: 2, minor: 24, raw: 'git version 2.24.0' });
+    try {
+      const result = await githubTeamStore.checkoutStore({
+        cloneUrl: remoteUrl,
+        branch: 'main',
+        localPath: LOCAL_CLONE,
+        subdir: 'acc',
+        partialClone: true,
+      });
+      assert(result.ok, `[scenario 3] checkoutStore should fall back to full clone: ${result.error || ''}`);
+      assert(result.action === 'cloned-fallback', `[scenario 3] expected action='cloned-fallback' but got '${result.action}'`);
+      assert(typeof result.warning === 'string' && /2\.25/.test(result.warning), `[scenario 3] warning should mention 2.25: ${result.warning || ''}`);
+      // Full clone means both subdirs ARE present.
+      assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 3] acc/README.md should exist (full clone)');
+      assert(fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 3] other/README.md should exist (full clone)');
+      scenariosPassed++;
+      console.log('[scenario 3: Git < 2.25 fallback] OK');
+    } finally {
+      gitRunner._setGitVersionForTests(null);
+    }
+  }
+
+  console.log(`\nsummary: ${scenariosPassed}/${scenariosTotal} scenarios passed`);
+  if (scenariosPassed !== scenariosTotal) {
+    process.exitCode = 1;
+  }
+}
+
+run().catch(err => {
+  console.error('test failed:', err.message);
+  console.error(err.stack);
+  process.exitCode = 1;
+});