project-knowledge 0.1.0

package/_site/_test/draft-apply-test.js

@@ -0,0 +1,363 @@
+// TASK-009: Draft Review and Apply test
+// Run: node _site/_test/draft-apply-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { makeRepo } = require('./fixtures/make-git-repos');
+const { runCommitAnalysis, readRun, listDrafts } = require('../lib/analysis-orchestrator');
+const {
+  applyDrafts, rejectDrafts, validateDraftSchema, isSafeApplyPath,
+} = require('../lib/draft-apply');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SERVER = path.join(ROOT, '_site', 'server.js');
+const PROJECTS_JSON = path.join(ROOT, 'projects.json');
+const PORT = process.env.KB_APPLY_TEST_PORT || '7799';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-009-temp';
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(r => setTimeout(r, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function json(method, url, body) {
+  const res = await fetch(`${BASE_URL}${url}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+  return { res, data };
+}
+
+async function cleanup() {
+  const base = path.join(ROOT, 'projects', TEMP_SLUG);
+  fs.rmSync(base, { recursive: true, force: true });
+  const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+  if (cur[TEMP_SLUG]) {
+    delete cur[TEMP_SLUG];
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+  }
+}
+
+(async () => {
+  assert(fs.existsSync(SERVER), 'server.js missing');
+
+  // ----- Unit tests on draft-apply primitives -----
+  // 1. validateDraftSchema
+  assert(validateDraftSchema({ path: 'features/x.md', content: 'hi' }).valid, 'simple md should be valid');
+  assert(validateDraftSchema({ path: 'a.json', content: '{}' }).valid, 'json should be valid');
+  assert(!validateDraftSchema({ path: 'a.txt', content: 'x' }).valid, '.txt must be rejected');
+  assert(!validateDraftSchema({ path: '/abs.md', content: 'x' }).valid, 'absolute path must be rejected');
+  assert(!validateDraftSchema({ path: 'a.md', content: '' }).valid, 'empty content must be rejected');
+  assert(!validateDraftSchema(null).valid, 'null must be rejected');
+
+  // 2. isSafeApplyPath
+  const kbRoot = path.join(ROOT, 'projects', 'unit');
+  assert(isSafeApplyPath(kbRoot, 'features/x.md'), 'plain relative path is safe');
+  assert(isSafeApplyPath(kbRoot, 'project-goal.md'), 'project-goal.md is safe (apply layer enforces trust separately)');
+  assert(!isSafeApplyPath(kbRoot, '_ai/drafts/x.md'), '_ai paths must be refused');
+  assert(!isSafeApplyPath(kbRoot, '../outside.md'), 'traversal must be refused');
+  assert(!isSafeApplyPath(kbRoot, '/abs.md'), 'absolute must be refused');
+  assert(!isSafeApplyPath(kbRoot, ''), 'empty must be refused');
+  assert(!isSafeApplyPath(kbRoot, 'features/../../outside.md'), 'embedded traversal must be refused');
+
+  // ----- Integration: run an analysis then apply its drafts -----
+  const repo = makeRepo({ kind: 'feature-commit' });
+  const kbBase = path.join(ROOT, 'projects', TEMP_SLUG);
+  fs.rmSync(kbBase, { recursive: true, force: true });
+  fs.mkdirSync(kbBase, { recursive: true });
+  // Pre-existing project-goal.md that the orchestrator must NOT overwrite
+  const existingGoal = '# Project Goal — PRESERVE\n';
+  fs.writeFileSync(path.join(kbBase, 'project-goal.md'), existingGoal);
+  fs.mkdirSync(path.join(kbBase, 'features'), { recursive: true });
+  fs.mkdirSync(path.join(kbBase, 'changes'), { recursive: true });
+
+  const project = {
+    slug: TEMP_SLUG,
+    kbPath: kbBase,
+    gitPath: repo.path,
+    localPath: repo.path,
+    aiProfileId: 'mock-agent',
+  };
+
+  let r = await runCommitAnalysis(project);
+  assert(r.ok, `commit analysis should succeed: ${r.error || ''}`);
+  const runId = r.runId;
+  const headCommitAtRun = r.runRecord.headCommitAtRun;
+  assert(headCommitAtRun, 'run should record headCommitAtRun');
+
+  // 3. List drafts
+  const drafts = listDrafts(kbBase, runId);
+  assert(drafts.length >= 3, `expected 3+ drafts (1 goal + 1 analysis + 2 changes + 1 feature), got ${drafts.length}`);
+  // The orchestrator does NOT produce a goal draft for commit runs. It produces changes/* and a feature/*.
+
+  // 4. Build draft payloads from the on-disk drafts
+  const payloads = drafts.map(d => ({
+    path: d.path,
+    content: fs.readFileSync(path.join(kbBase, '_ai', 'drafts', runId, d.path), 'utf-8'),
+  }));
+
+  // 5. Apply drafts: should succeed, write to KB, create backups, update manifest, mark run as applied
+  const applyResult = applyDrafts({
+    kbPath: kbBase,
+    slug: TEMP_SLUG,
+    runId,
+    drafts: payloads,
+    allowGoalEdit: false,
+    headCommitAtRun,
+  });
+  assert(applyResult.ok, `apply should succeed: ${JSON.stringify(applyResult)}`);
+  assert(applyResult.applied.length === payloads.length, `applied length should match, got ${applyResult.applied.length}`);
+  assert(applyResult.backups.length === 0, 'no backups expected (no pre-existing targets)');
+
+  // 6. Files are now on disk in the formal KB
+  for (const d of payloads) {
+    const target = path.join(kbBase, d.path);
+    assert(fs.existsSync(target), `applied file should exist: ${d.path}`);
+    const got = fs.readFileSync(target, 'utf-8');
+    assert(got === d.content, `applied content should match for ${d.path}`);
+  }
+
+  // 7. Manifest updated
+  const manifest = JSON.parse(fs.readFileSync(path.join(kbBase, 'kb-manifest.json'), 'utf-8'));
+  assert(manifest.trustedKnowledge.includes('features/'), 'manifest should add features/');
+  assert(manifest.trustedKnowledge.includes('changes/'), 'manifest should add changes/');
+
+  // 8. Run record marked as applied
+  const run = readRun(kbBase, runId);
+  assert(run.applyStatus === 'applied', `run should be applied, got ${run.applyStatus}`);
+  assert(run.appliedAt, 'run should have appliedAt');
+  assert(Array.isArray(run.appliedPaths) && run.appliedPaths.length === payloads.length, 'run should list appliedPaths');
+  assert(run.advancedLastAnalyzedCommit === headCommitAtRun, 'run should record advancedLastAnalyzedCommit');
+
+  // 9. Second pass: drafts now need to apply OVER existing files; backups should be created
+  const modifiedDrafts = payloads.map(d => ({ path: d.path, content: d.content + '\n<!-- second-pass -->\n' }));
+  const applyResult2 = applyDrafts({
+    kbPath: kbBase,
+    slug: TEMP_SLUG,
+    runId,
+    drafts: modifiedDrafts,
+    allowGoalEdit: false,
+  });
+  assert(applyResult2.ok, `second apply should succeed: ${JSON.stringify(applyResult2)}`);
+  assert(applyResult2.backups.length === modifiedDrafts.length, `should have backups for every overwrite, got ${applyResult2.backups.length}`);
+  for (const b of applyResult2.backups) {
+    assert(fs.existsSync(path.join(kbBase, b.backup)), `backup should exist on disk: ${b.backup}`);
+  }
+
+  repo.cleanup();
+  fs.rmSync(kbBase, { recursive: true, force: true });
+
+  // ----- Refusal: project-goal.md without allowGoalEdit -----
+  const repo2 = makeRepo({ kind: 'one-commit' });
+  const kbBase2 = path.join(ROOT, 'projects', TEMP_SLUG + '-goal');
+  fs.rmSync(kbBase2, { recursive: true, force: true });
+  fs.mkdirSync(kbBase2, { recursive: true });
+  fs.writeFileSync(path.join(kbBase2, 'project-goal.md'), '# Goal — original\n');
+  const project2 = { ...project, slug: TEMP_SLUG + '-goal', kbPath: kbBase2, gitPath: repo2.path, localPath: repo2.path };
+
+  // Use a synthetic draft: pretend an analysis run wrote a goal draft
+  const fakeRunId = 'commits-fake';
+  fs.mkdirSync(path.join(kbBase2, '_ai', 'drafts', fakeRunId), { recursive: true });
+  fs.mkdirSync(path.join(kbBase2, '_ai', 'runs'), { recursive: true });
+  fs.writeFileSync(path.join(kbBase2, '_ai', 'drafts', fakeRunId, 'project-goal.md'), '# Goal — AI proposal\n');
+  fs.writeFileSync(path.join(kbBase2, '_ai', 'runs', fakeRunId + '.json'), JSON.stringify({
+    schema: 'ai-run/v1', runId: fakeRunId, type: 'commits', status: 'succeeded',
+  }));
+
+  // 10. Refuse without allowGoalEdit
+  const refuse = applyDrafts({
+    kbPath: kbBase2,
+    slug: TEMP_SLUG + '-goal',
+    runId: fakeRunId,
+    drafts: [{ path: 'project-goal.md', content: '# Goal — should not write' }],
+    allowGoalEdit: false,
+  });
+  assert(!refuse.ok, 'apply without allowGoalEdit must refuse to overwrite project-goal.md');
+  assert(refuse.status === 422, `expected 422, got ${refuse.status}: ${JSON.stringify(refuse)}`);
+  // Original file untouched
+  const stillThere = fs.readFileSync(path.join(kbBase2, 'project-goal.md'), 'utf-8');
+  assert(stillThere === '# Goal — original\n', 'original project-goal.md must be preserved');
+
+  // 11. Allow with allowGoalEdit: true
+  const allow = applyDrafts({
+    kbPath: kbBase2,
+    slug: TEMP_SLUG + '-goal',
+    runId: fakeRunId,
+    drafts: [{ path: 'project-goal.md', content: '# Goal — accepted' }],
+    allowGoalEdit: true,
+  });
+  assert(allow.ok, `apply with allowGoalEdit should succeed: ${JSON.stringify(allow)}`);
+  const after = fs.readFileSync(path.join(kbBase2, 'project-goal.md'), 'utf-8');
+  assert(after === '# Goal — accepted\n' || after === '# Goal — accepted', 'project-goal.md should be overwritten when allowed');
+  // Manifest should now record the goal
+  const m2 = JSON.parse(fs.readFileSync(path.join(kbBase2, 'kb-manifest.json'), 'utf-8'));
+  assert(m2.goal && m2.goal.path === 'project-goal.md', 'manifest should record goal');
+  assert(m2.goal.status === 'accepted', 'manifest.goal.status should be accepted');
+
+  repo2.cleanup();
+  fs.rmSync(kbBase2, { recursive: true, force: true });
+
+  // ----- Reject flow -----
+  const repo3 = makeRepo({ kind: 'one-commit' });
+  const kbBase3 = path.join(ROOT, 'projects', TEMP_SLUG + '-reject');
+  fs.rmSync(kbBase3, { recursive: true, force: true });
+  fs.mkdirSync(kbBase3, { recursive: true });
+  fs.writeFileSync(path.join(kbBase3, 'project-goal.md'), '# Goal\n');
+  const project3 = { ...project, slug: TEMP_SLUG + '-reject', kbPath: kbBase3, gitPath: repo3.path, localPath: repo3.path };
+  r = await runCommitAnalysis(project3);
+  assert(r.ok, `commit analysis should succeed: ${r.error || ''}`);
+
+  const rej = rejectDrafts({ kbPath: kbBase3, runId: r.runId, reason: 'not ready' });
+  assert(rej.ok, 'reject should succeed');
+  const rejRun = readRun(kbBase3, r.runId);
+  assert(rejRun.applyStatus === 'rejected', 'run should be marked rejected');
+  assert(rejRun.rejectionReason === 'not ready', 'run should record reason');
+  repo3.cleanup();
+  fs.rmSync(kbBase3, { recursive: true, force: true });
+
+  // ----- Bad inputs -----
+  const noKb = applyDrafts({ kbPath: null, slug: 'x', runId: 'y', drafts: [], allowGoalEdit: false });
+  assert(!noKb.ok, 'null kbPath should fail');
+  const empty = applyDrafts({ kbPath: kbBase, slug: TEMP_SLUG, runId: 'r', drafts: [], allowGoalEdit: false });
+  assert(!empty.ok, 'empty drafts should fail');
+  const badSchema = applyDrafts({
+    kbPath: kbBase, slug: TEMP_SLUG, runId: 'r',
+    drafts: [{ path: 'x.txt', content: 'no' }], allowGoalEdit: false,
+  });
+  assert(!badSchema.ok && badSchema.status === 422, 'invalid schema should 422');
+
+  // 12. Unsafe path during apply
+  const kbBase4 = path.join(ROOT, 'projects', TEMP_SLUG + '-unsafe');
+  fs.rmSync(kbBase4, { recursive: true, force: true });
+  fs.mkdirSync(kbBase4, { recursive: true });
+  const unsafe = applyDrafts({
+    kbPath: kbBase4, slug: TEMP_SLUG + '-unsafe', runId: 'r',
+    drafts: [{ path: '_ai/drafts/foo.md', content: 'x' }], allowGoalEdit: false,
+  });
+  assert(!unsafe.ok && unsafe.status === 422, '_ai/ path must be refused at apply');
+  fs.rmSync(kbBase4, { recursive: true, force: true });
+
+  // ----- Server tests -----
+  const child = spawn(process.execPath, [SERVER], {
+    cwd: ROOT,
+    env: { ...process.env, KB_SITE_PORT: PORT, KB_SITE_HOST: '127.0.0.1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let serverOutput = '';
+  child.stdout.on('data', d => { serverOutput += d.toString(); });
+  child.stderr.on('data', d => { serverOutput += d.toString(); });
+
+  try {
+    await cleanup();
+    await waitForServer();
+
+    // 13. End-to-end
+    const repo4 = makeRepo({ kind: 'feature-commit' });
+    const slug = TEMP_SLUG;
+    const kbPath = path.join(ROOT, 'projects', slug);
+    fs.rmSync(kbPath, { recursive: true, force: true });
+    fs.mkdirSync(kbPath, { recursive: true });
+    fs.writeFileSync(path.join(kbPath, 'project-goal.md'), '# Goal — server\n');
+
+    r = await json('PUT', '/api/projects', {
+      slug,
+      config: { displayName: 'TASK-009', localPath: repo4.path, gitPath: repo4.path, kbPath },
+    });
+    assert(r.res.ok, 'upsert should succeed');
+
+    r = await json('POST', `/api/projects/${slug}/analyze/commits`, {});
+    assert(r.res.ok, `analyze commits should succeed: ${JSON.stringify(r.data)}`);
+    const srvRunId = r.data.runId;
+    const srvHeadCommit = r.data.run.headCommitAtRun;
+    assert(srvHeadCommit, 'run should record headCommitAtRun');
+
+    // 14. List drafts
+    r = await json('GET', `/api/projects/${slug}/drafts/${srvRunId}`);
+    assert(r.res.ok, 'list drafts should succeed');
+    assert(r.data.drafts.length >= 3, `expected 3+ drafts, got ${r.data.drafts.length}`);
+    const serverDrafts = r.data.drafts;
+
+    // 15. Read raw draft text
+    const someDraft = serverDrafts[0];
+    r = await json('GET', `/api/projects/${slug}/drafts/${srvRunId}/raw?path=${encodeURIComponent(someDraft.path)}`);
+    assert(r.res.ok, 'read raw draft should succeed');
+    assert(typeof r.data.content === 'string' && r.data.content.length > 0, 'raw content should be non-empty');
+
+    // 16. Apply without allowGoalEdit (no goal in these drafts, so this should succeed)
+    const payloads2 = serverDrafts.map(d => ({
+      path: d.path,
+      content: fs.readFileSync(path.join(kbPath, '_ai', 'drafts', srvRunId, d.path), 'utf-8'),
+    }));
+    r = await json('POST', `/api/projects/${slug}/drafts/${srvRunId}/apply`, {
+      drafts: payloads2,
+      allowGoalEdit: false,
+    });
+    assert(r.res.ok, `apply should succeed: ${JSON.stringify(r.data)}`);
+    assert(r.data.applied.length === payloads2.length, 'applied length should match');
+
+    // 17. lastAnalyzedCommit advanced in projects.json
+    const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+    assert(cur[slug].lastAnalyzedCommit === srvHeadCommit,
+      `lastAnalyzedCommit should advance to ${srvHeadCommit}, got ${cur[slug].lastAnalyzedCommit}`);
+
+    // 18. Run marked as applied
+    r = await json('GET', `/api/projects/${slug}/runs/${srvRunId}`);
+    assert(r.data.run.applyStatus === 'applied', `run should be applied, got ${r.data.run.applyStatus}`);
+
+    // 19. Refuse: try to apply a goal draft without allowGoalEdit
+    fs.mkdirSync(path.join(kbPath, '_ai', 'drafts', 'goal-test'), { recursive: true });
+    fs.writeFileSync(path.join(kbPath, '_ai', 'drafts', 'goal-test', 'project-goal.md'), '# Goal — bad');
+    fs.writeFileSync(path.join(kbPath, '_ai', 'runs', 'goal-test.json'), JSON.stringify({ schema: 'ai-run/v1', runId: 'goal-test' }));
+    r = await json('POST', `/api/projects/${slug}/drafts/goal-test/apply`, {
+      drafts: [{ path: 'project-goal.md', content: '# Goal — should not write' }],
+      allowGoalEdit: false,
+    });
+    assert(!r.res.ok && r.res.status === 422, 'goal apply without allowGoalEdit should 422');
+    // Original project-goal.md preserved
+    const goal = fs.readFileSync(path.join(kbPath, 'project-goal.md'), 'utf-8');
+    assert(goal.includes('Goal — server'), 'original goal must be preserved');
+
+    // 20. Reject endpoint
+    fs.mkdirSync(path.join(kbPath, '_ai', 'drafts', 'reject-test', 'features'), { recursive: true });
+    fs.writeFileSync(path.join(kbPath, '_ai', 'drafts', 'reject-test', 'features', 'x.md'), '# X');
+    fs.writeFileSync(path.join(kbPath, '_ai', 'runs', 'reject-test.json'), JSON.stringify({ schema: 'ai-run/v1', runId: 'reject-test' }));
+    r = await json('POST', `/api/projects/${slug}/drafts/reject-test/reject`, { reason: 'unit test' });
+    assert(r.res.ok, 'reject should succeed');
+    r = await json('GET', `/api/projects/${slug}/runs/reject-test`);
+    assert(r.data.run.applyStatus === 'rejected', 'run should be rejected');
+
+    // 21. Bad slug (starts with dash — invalid for isSafeSlug)
+    r = await json('POST', '/api/projects/-bad-/drafts/x/apply', { drafts: [] });
+    assert(!r.res.ok && r.res.status === 400, 'bad slug should 400');
+
+    repo4.cleanup();
+    console.log('TASK-009 draft-apply test passed');
+  } catch (e) {
+    console.error('TASK-009 draft-apply test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    await cleanup().catch(() => {});
+    for (const suffix of ['-goal', '-reject', '-unsafe']) {
+      try { fs.rmSync(path.join(ROOT, 'projects', TEMP_SLUG + suffix), { recursive: true, force: true }); } catch {}
+    }
+    child.kill();
+  }
+})();

package/_site/_test/git-validation-test.js

@@ -0,0 +1,171 @@
+// TASK-002: Git import validation test
+// Run: node _site/_test/git-validation-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { makeRepo } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SERVER = path.join(ROOT, '_site', 'server.js');
+const PROJECTS_JSON = path.join(ROOT, 'projects.json');
+const PORT = process.env.KB_GIT_TEST_PORT || '7792';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-002-temp';
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(r => setTimeout(r, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function json(method, url, body) {
+  const res = await fetch(`${BASE_URL}${url}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+  return { res, data };
+}
+
+async function upsertProject(slug, config) {
+  const r = await json('PUT', '/api/projects', { slug, config });
+  assert(r.res.ok, `upsert failed: ${JSON.stringify(r.data)}`);
+  return r.data;
+}
+
+async function removeTemp() {
+  const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+  if (cur[TEMP_SLUG]) {
+    delete cur[TEMP_SLUG];
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+  }
+}
+
+(async () => {
+  // 1. Static checks
+  assert(fs.existsSync(SERVER), 'server.js missing');
+  JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+
+  const child = spawn(process.execPath, [SERVER], {
+    cwd: ROOT,
+    env: { ...process.env, KB_SITE_PORT: PORT, KB_SITE_HOST: '127.0.0.1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let serverOutput = '';
+  child.stdout.on('data', d => { serverOutput += d.toString(); });
+  child.stderr.on('data', d => { serverOutput += d.toString(); });
+
+  const fixtures = [];
+  try {
+    await waitForServer();
+
+    // 2. Bad slug returns 400
+    const bad = await json('POST', '/api/projects/INVALID..SLUG!/validate-git');
+    assert(!bad.res.ok, 'bad slug should not succeed');
+    assert(bad.res.status === 400, `bad slug should return 400, got ${bad.res.status}`);
+
+    // 3. One-commit repo → repoStatus=ok
+    const okRepo = makeRepo({ kind: 'one-commit' });
+    fixtures.push(okRepo);
+    await upsertProject(TEMP_SLUG, {
+      displayName: 'TASK-002 OK',
+      localPath: okRepo.path,
+      gitPath: okRepo.path,
+    });
+    let r = await json('GET', '/api/projects');
+    let cfg = r.data[TEMP_SLUG];
+    assert(cfg.repoStatus === 'ok', `one-commit should be ok, got ${cfg.repoStatus}`);
+    assert(cfg.headCommit && cfg.headCommit.length >= 7, 'headCommit should be set');
+    assert(cfg.currentBranch === 'main', `currentBranch should be main, got ${cfg.currentBranch}`);
+
+    // validate-git endpoint
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/validate-git`);
+    assert(r.res.ok, 'validate-git should succeed');
+    assert(r.data.repoStatus === 'ok', `validate-git should report ok, got ${r.data.repoStatus}`);
+
+    // git-status read-only endpoint
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/git-status`);
+    assert(r.res.ok, 'git-status should return 200');
+    assert(r.data.repoStatus === 'ok', 'git-status should report ok');
+
+    // 4. Not-git folder → repoStatus=not-git
+    const notGit = makeRepo({ kind: 'not-git' });
+    fixtures.push(notGit);
+    await upsertProject(TEMP_SLUG, {
+      displayName: 'TASK-002 NotGit',
+      localPath: notGit.path,
+      gitPath: notGit.path,
+    });
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/git-status`);
+    assert(r.res.ok, 'git-status should return 200 for not-git');
+    assert(r.data.repoStatus === 'not-git', `not-git folder should report not-git, got ${r.data.repoStatus}`);
+
+    // 5. Missing path → repoStatus=missing-path
+    const missing = 'D:\\__no_such_path__\\__no_such_repo__';
+    await upsertProject(TEMP_SLUG, {
+      displayName: 'TASK-002 Missing',
+      localPath: missing,
+      gitPath: missing,
+    });
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/git-status`);
+    assert(r.res.ok, 'git-status should return 200 for missing');
+    assert(r.data.repoStatus === 'missing-path', `missing should report missing-path, got ${r.data.repoStatus}`);
+
+    // 6. Empty Git repo → repoStatus=empty
+    const empty = makeRepo({ kind: 'empty' });
+    fixtures.push(empty);
+    await upsertProject(TEMP_SLUG, {
+      displayName: 'TASK-002 Empty',
+      localPath: empty.path,
+      gitPath: empty.path,
+    });
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/git-status`);
+    assert(r.res.ok, 'git-status should return 200 for empty');
+    assert(r.data.repoStatus === 'empty', `empty should report empty, got ${r.data.repoStatus}`);
+    assert(r.data.headCommit === null, 'empty repo should have no headCommit');
+
+    // 7. Nonexistent slug for validate-git
+    r = await json('POST', '/api/projects/nonexistent-12345/validate-git');
+    assert(!r.res.ok, 'nonexistent slug should fail');
+    assert(r.res.status === 404, 'nonexistent slug should return 404');
+
+    // 8. Persisted state visible in /api/state
+    await upsertProject(TEMP_SLUG, {
+      displayName: 'TASK-002 OK',
+      localPath: okRepo.path,
+      gitPath: okRepo.path,
+    });
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/validate-git`);
+    r = await json('GET', '/api/state');
+    cfg = r.data.projects[TEMP_SLUG];
+    assert(cfg.repoStatus === 'ok', 'persisted repoStatus should be ok');
+    assert(cfg.headCommit && cfg.headCommit.length >= 7, 'persisted headCommit should be set');
+    assert(cfg.currentBranch === 'main', 'persisted currentBranch should be main');
+
+    console.log('TASK-002 git validation test passed');
+  } catch (e) {
+    console.error('TASK-002 git validation test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    for (const f of fixtures) {
+      try { f.cleanup(); } catch {}
+    }
+    await removeTemp().catch(() => {});
+    child.kill();
+  }
+})();