project-knowledge 0.1.0

package/_site/_test/job-orchestrator-test.js

@@ -0,0 +1,297 @@
+// TASK-010: Job orchestrator test
+// Run: node _site/_test/job-orchestrator-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { makeRepo } = require('./fixtures/make-git-repos');
+const {
+  runJob, makeJob, readJobLog, appendJobLog, KNOWN_MODES,
+} = require('../lib/job-orchestrator');
+const { runInitialAnalysis, runCommitAnalysis, readRun, listDrafts } = require('../lib/analysis-orchestrator');
+
+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_JOB_TEST_PORT || '7800';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-010-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');
+  }
+  const log = path.join(ROOT, '.jobs-log.json');
+  if (fs.existsSync(log)) fs.unlinkSync(log);
+}
+
+function makeProjectsDir(slug) {
+  const base = path.join(ROOT, 'projects', slug);
+  fs.rmSync(base, { recursive: true, force: true });
+  fs.mkdirSync(base, { recursive: true });
+  fs.writeFileSync(path.join(base, 'project-goal.md'), '# Goal\n');
+  fs.mkdirSync(path.join(base, 'features'), { recursive: true });
+  fs.mkdirSync(path.join(base, 'changes'), { recursive: true });
+  return base;
+}
+
+(async () => {
+  assert(fs.existsSync(SERVER), 'server.js missing');
+
+  // 1. KNOWN_MODES lists the expected set
+  for (const m of ['legacy', 'scan', 'analyze-initial', 'analyze-commits', 'safe']) {
+    assert(KNOWN_MODES.has(m), `KNOWN_MODES should include ${m}`);
+  }
+
+  // 2. makeJob returns a job with the expected shape
+  const j = makeJob({ mode: 'scan', slug: 'ALL' });
+  assert(j.jobId && j.jobId.startsWith('job-'), 'jobId should start with job-');
+  assert(j.mode === 'scan' && j.slug === 'ALL', 'mode and slug set');
+  assert(j.status === 'running', 'initial status is running');
+  assert(typeof j.startTime === 'string', 'startTime is an ISO string');
+
+  // 3. appendJobLog / readJobLog round-trip
+  const log = path.join(ROOT, '.jobs-log-test.json');
+  if (fs.existsSync(log)) fs.unlinkSync(log);
+  appendJobLog(log, { jobId: 'job-a', status: 'success' });
+  appendJobLog(log, { jobId: 'job-b', status: 'failed' });
+  const readBack = readJobLog(log);
+  assert(readBack.length === 2, `expected 2 entries, got ${readBack.length}`);
+  assert(readBack[0].jobId === 'job-a' && readBack[1].jobId === 'job-b', 'entries in order');
+  fs.unlinkSync(log);
+
+  // 4. runJob with unknown mode returns failure but still records
+  const badJob = makeJob({ mode: 'no-such-mode', slug: 'ALL' });
+  const badResult = await runJob({
+    job: badJob,
+    projects: {},
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(!badResult.summary || badResult.summary.error, 'unknown mode should set summary.error');
+  assert(badResult.status === 'failed', 'unknown mode should fail');
+  fs.unlinkSync(log);
+
+  // ----- Integration: scan mode -----
+  const repo = makeRepo({ kind: 'multi-commit' });
+  const kbBase = makeProjectsDir(TEMP_SLUG);
+  const project = {
+    slug: TEMP_SLUG,
+    kbPath: kbBase,
+    gitPath: repo.path,
+    localPath: repo.path,
+    aiProfileId: 'mock-agent',
+    enabled: true,
+    headCommit: null,
+    lastSeenCommit: null,
+    lastAnalyzedCommit: null,
+  };
+  const projectsMap = { [TEMP_SLUG]: project };
+
+  const scanJob = makeJob({ mode: 'scan', slug: TEMP_SLUG });
+  const scanResult = await runJob({
+    job: scanJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(scanResult.status === 'success', `scan should succeed, got ${scanResult.status}`);
+  assert(scanResult.summary && scanResult.summary.scanned === 1, `expected 1 scanned, got ${JSON.stringify(scanResult.summary)}`);
+  assert(projectsMap[TEMP_SLUG].headCommit, 'scan should populate headCommit');
+  assert(projectsMap[TEMP_SLUG].lastSeenCommit, 'scan should populate lastSeenCommit');
+  assert(projectsMap[TEMP_SLUG].lastScanPendingCount === 3, `expected 3 pending, got ${projectsMap[TEMP_SLUG].lastScanPendingCount}`);
+
+  // 5. safe mode runs scan + analyze-commits, and crucially does NOT apply drafts
+  // Reset the project so analyze-commits sees 3 pending
+  projectsMap[TEMP_SLUG].lastAnalyzedCommit = null;
+  const safeJob = makeJob({ mode: 'safe', slug: TEMP_SLUG });
+  const safeResult = await runJob({
+    job: safeJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(safeResult.status === 'success', `safe should succeed, got ${safeResult.status}: ${safeResult.summary ? JSON.stringify(safeResult.summary) : ''}`);
+  assert(safeResult.summary && safeResult.summary.scan && safeResult.summary.commits, 'safe should include both scan and commits summaries');
+  assert(safeResult.summary.applied === 0, `safe must apply 0 drafts, got ${safeResult.summary.applied}`);
+  // Drafts were created under _ai/drafts/ but NOT applied to the formal KB
+  // Verify there is at least one draft on disk
+  const runs = fs.readdirSync(path.join(kbBase, '_ai', 'runs'));
+  const appliedRuns = runs.filter(r => {
+    try { return JSON.parse(fs.readFileSync(path.join(kbBase, '_ai', 'runs', r), 'utf-8')).applyStatus === 'applied'; }
+    catch { return false; }
+  });
+  assert(appliedRuns.length === 0, `safe mode must NOT apply drafts; found ${appliedRuns.length} applied run(s)`);
+  // Verify the formal KB does NOT have any features/<slug>.md or changes/<short>.md (except those from the init template)
+  const featuresDir = path.join(kbBase, 'features');
+  const changesDir = path.join(kbBase, 'changes');
+  const realFeatureFiles = fs.existsSync(featuresDir)
+    ? fs.readdirSync(featuresDir).filter(f => f !== '00-index.md')
+    : [];
+  const realChangeFiles = fs.existsSync(changesDir)
+    ? fs.readdirSync(changesDir).filter(f => f !== '00-index.md')
+    : [];
+  assert(realFeatureFiles.length === 0, `safe mode must not write features files; found: ${realFeatureFiles.join(',')}`);
+  assert(realChangeFiles.length === 0, `safe mode must not write changes files; found: ${realChangeFiles.join(',')}`);
+
+  // 6. analyze-commits mode runs analysis and creates drafts
+  projectsMap[TEMP_SLUG].lastAnalyzedCommit = null;
+  const acJob = makeJob({ mode: 'analyze-commits', slug: TEMP_SLUG });
+  const acResult = await runJob({
+    job: acJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(acResult.status === 'success', `analyze-commits should succeed, got ${acResult.status}`);
+  assert(acResult.summary && acResult.summary.ran === 1, `expected 1 ran, got ${JSON.stringify(acResult.summary)}`);
+
+  // 7. analyze-initial mode skips a project that already has a goal
+  const aiJob = makeJob({ mode: 'analyze-initial', slug: TEMP_SLUG });
+  const aiResult = await runJob({
+    job: aiJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(aiResult.summary && aiResult.summary.skipped === 1, `analyze-initial should skip project with existing goal; got ${JSON.stringify(aiResult.summary)}`);
+
+  // 8. analyze-initial on a project with no goal creates an initial run
+  const noGoalSlug = TEMP_SLUG + '-no-goal';
+  const noGoalBase = makeProjectsDir(noGoalSlug);
+  fs.unlinkSync(path.join(noGoalBase, 'project-goal.md'));
+  const noGoalRepo = makeRepo({ kind: 'one-commit' });
+  projectsMap[noGoalSlug] = {
+    slug: noGoalSlug,
+    kbPath: noGoalBase,
+    gitPath: noGoalRepo.path,
+    localPath: noGoalRepo.path,
+    aiProfileId: 'mock-agent',
+    enabled: true,
+  };
+  const aiJob2 = makeJob({ mode: 'analyze-initial', slug: noGoalSlug });
+  const aiResult2 = await runJob({
+    job: aiJob2,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(aiResult2.summary && aiResult2.summary.ran === 1, `analyze-initial should run on a no-goal project; got ${JSON.stringify(aiResult2.summary)}`);
+  // Note: the orchestrator does not write project-goal.md; it writes a draft only.
+  assert(!fs.existsSync(path.join(noGoalBase, 'project-goal.md')), 'analyze-initial must NOT create project-goal.md directly (it creates a draft)');
+
+  // 9. scan with slug=ALL iterates enabled projects
+  projectsMap[TEMP_SLUG].headCommit = null;
+  projectsMap[TEMP_SLUG].lastSeenCommit = null;
+  const scanAllJob = makeJob({ mode: 'scan', slug: 'ALL' });
+  const scanAllResult = await runJob({
+    job: scanAllJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(scanAllResult.summary.scanned >= 1, 'scan ALL should hit at least the test project');
+
+  // 10. unknown slug returns a clear error
+  const badSlugJob = makeJob({ mode: 'scan', slug: 'no-such-slug' });
+  const badSlugResult = await runJob({
+    job: badSlugJob,
+    projects: projectsMap,
+    projectsPath: PROJECTS_JSON,
+    jobsLogPath: log,
+  });
+  assert(badSlugResult.status === 'failed', 'scan on unknown slug should fail');
+
+  // 11. Job log persisted
+  const persistedLog = readJobLog(log);
+  assert(persistedLog.length >= 5, `expected ≥5 persisted jobs, got ${persistedLog.length}`);
+
+  repo.cleanup();
+  noGoalRepo.cleanup();
+  fs.rmSync(kbBase, { recursive: true, force: true });
+  fs.rmSync(noGoalBase, { recursive: true, force: true });
+  fs.unlinkSync(log);
+
+  // ----- 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();
+
+    // 12. /api/jobs/run dispatches a job and returns jobId
+    r = await json('POST', '/api/jobs/run', { mode: 'scan', slug: 'ALL' });
+    assert(r.res.ok, `jobs/run should succeed: ${JSON.stringify(r.data)}`);
+    assert(r.data.jobId && r.data.jobId.startsWith('job-'), 'should return jobId');
+    assert(r.data.mode === 'scan' && r.data.slug === 'ALL', 'should echo mode and slug');
+    const dispatchedJobId = r.data.jobId;
+
+    // 13. /api/jobs returns history
+    r = await json('GET', '/api/jobs');
+    assert(r.res.ok, 'GET /api/jobs should succeed');
+    assert(Array.isArray(r.data.history), 'history should be an array');
+    assert(Array.isArray(r.data.knownModes), 'knownModes should be an array');
+    assert(r.data.knownModes.includes('safe'), 'knownModes should include safe');
+
+    // 14. /api/jobs/:jobId returns the job (live or persisted)
+    r = await json('GET', `/api/jobs/${dispatchedJobId}`);
+    assert(r.res.ok, `GET job should succeed: ${JSON.stringify(r.data)}`);
+    assert(r.data.job.jobId === dispatchedJobId, 'should return the right job');
+
+    // 15. unknown mode returns 400
+    r = await json('POST', '/api/jobs/run', { mode: 'no-such-mode' });
+    assert(!r.res.ok && r.res.status === 400, 'unknown mode should 400');
+
+    // 16. unknown jobId returns 404
+    r = await json('GET', '/api/jobs/job-999999-9999');
+    assert(!r.res.ok && r.res.status === 404, 'unknown job should 404');
+
+    console.log('TASK-010 job orchestrator test passed');
+  } catch (e) {
+    console.error('TASK-010 job orchestrator test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    await cleanup().catch(() => {});
+    child.kill();
+  }
+})();

package/_site/_test/kb-v2-templates-test.js

@@ -0,0 +1,189 @@
+// TASK-003: KB v2 templates test
+// Run: node _site/_test/kb-v2-templates-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+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_V2_TEST_PORT || '7793';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-003-temp';
+
+const REQUIRED_V2_DIRS = [
+  'architecture', 'modules', 'commits', 'operations', 'references',
+  'requirements', 'features', 'changes', 'quality',
+  '_ai/drafts', '_ai/runs', '_ai/context-packs',
+];
+
+const REQUIRED_V2_FILES = [
+  'README.md',
+  'framework.md',
+  'project-goal.md',
+  'project-analysis.md',
+  'kb-manifest.json',
+  'architecture/overview.md',
+  'modules/00-index.md',
+  'commits/00-index.md',
+  'features/00-index.md',
+  'changes/00-index.md',
+  'quality/quality-review-rules.md',
+  'requirements/roadmap.md',
+  'requirements/constraints.md',
+  'requirements/success-criteria.md',
+  'references/source-map.md',
+];
+
+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 cleanupTemp() {
+  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');
+  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(); });
+
+  try {
+    await cleanupTemp();
+    await waitForServer();
+
+    // 1. Upsert project + init
+    let r = await json('PUT', '/api/projects', {
+      slug: TEMP_SLUG,
+      config: {
+        displayName: 'TASK-003 Temp',
+        localPath: 'D:\\__no_such__',
+        gitPath: 'D:\\__no_such__',
+      },
+    });
+    assert(r.res.ok, 'upsert should succeed');
+
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/init`);
+    assert(r.res.ok, 'init should succeed');
+    assert(r.data.kbSchemaVersion === 'v2', `init should set schema v2, got ${r.data.kbSchemaVersion}`);
+
+    const base = path.join(ROOT, 'projects', TEMP_SLUG);
+    for (const sub of REQUIRED_V2_DIRS) {
+      const p = path.join(base, sub);
+      assert(fs.existsSync(p) && fs.statSync(p).isDirectory(), `missing dir: ${sub}`);
+    }
+    for (const rel of REQUIRED_V2_FILES) {
+      const p = path.join(base, rel);
+      assert(fs.existsSync(p), `missing file: ${rel}`);
+    }
+
+    // 2. Manifest parses and points to existing files
+    const manifestPath = path.join(base, 'kb-manifest.json');
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    assert(manifest.schema === 'kb-manifest/v1', 'manifest schema should be v1');
+    assert(manifest.project === TEMP_SLUG, 'manifest project should match');
+    assert(manifest.goal.path === 'project-goal.md', 'manifest should point at project-goal.md');
+    assert(Array.isArray(manifest.trustedKnowledge) && manifest.trustedKnowledge.length > 0, 'trustedKnowledge should be non-empty');
+    for (const tpath of [manifest.goal.path, manifest.analysis.path, ...manifest.indexes ? Object.values(manifest.indexes) : []]) {
+      const full = path.join(base, tpath);
+      assert(fs.existsSync(full), `manifest should not point to missing file: ${tpath}`);
+    }
+    for (const trusted of manifest.trustedKnowledge) {
+      const full = path.join(base, trusted);
+      assert(fs.existsSync(full), `trusted entry should exist: ${trusted}`);
+    }
+
+    // 3. Templates rendered with project name
+    const goal = fs.readFileSync(path.join(base, 'project-goal.md'), 'utf-8');
+    assert(goal.includes(TEMP_SLUG), 'project-goal should contain project name');
+    assert(goal.includes('TODO'), 'project-goal should still have TODO placeholders');
+    const analysis = fs.readFileSync(path.join(base, 'project-analysis.md'), 'utf-8');
+    assert(analysis.includes(TEMP_SLUG), 'project-analysis should contain project name');
+    const feature = fs.readFileSync(path.join(base, 'features/00-index.md'), 'utf-8');
+    assert(feature.includes('Features'), 'features index should be created');
+
+    // 4. Idempotent re-init
+    const before = fs.readFileSync(manifestPath, 'utf-8');
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/init`);
+    assert(r.res.ok, 're-init should succeed');
+    const after = fs.readFileSync(manifestPath, 'utf-8');
+    assert(before === after, 're-init should not rewrite manifest');
+
+    // 5. Legacy commits/ is preserved when migrating an existing v1 project
+    const legacySlug = 'task-003-legacy';
+    const legacyBase = path.join(ROOT, 'projects', legacySlug);
+    fs.mkdirSync(path.join(legacyBase, 'commits'), { recursive: true });
+    const legacyCommitFile = path.join(legacyBase, 'commits', '2026-01-01_aaaaaaa_test.md');
+    fs.writeFileSync(legacyCommitFile, 'legacy commit file — should not be deleted\n');
+    fs.writeFileSync(path.join(legacyBase, 'README.md'), 'legacy readme\n');
+    fs.mkdirSync(path.join(legacyBase, 'modules'), { recursive: true });
+    fs.writeFileSync(path.join(legacyBase, 'modules', 'foo.md'), 'legacy module\n');
+
+    r = await json('PUT', '/api/projects', { slug: legacySlug, config: { displayName: 'legacy' } });
+    assert(r.res.ok, 'legacy upsert should succeed');
+    r = await json('POST', `/api/projects/${legacySlug}/migrate-v2`);
+    assert(r.res.ok, 'migrate-v2 should succeed');
+    assert(fs.existsSync(legacyCommitFile), 'migrate-v2 must preserve legacy commits/ files');
+    assert(fs.existsSync(path.join(legacyBase, 'kb-manifest.json')), 'migrate-v2 should create manifest');
+    assert(fs.existsSync(path.join(legacyBase, 'project-goal.md')), 'migrate-v2 should create project-goal.md');
+
+    // 6. Bad slug still 400
+    r = await json('POST', '/api/projects/INVALID../migrate-v2');
+    assert(!r.res.ok && r.res.status === 400, 'migrate-v2 bad slug should 400');
+
+    console.log('TASK-003 KB v2 templates test passed');
+  } catch (e) {
+    console.error('TASK-003 KB v2 templates test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    await cleanupTemp().catch(() => {});
+    const legacyBase = path.join(ROOT, 'projects', 'task-003-legacy');
+    fs.rmSync(legacyBase, { recursive: true, force: true });
+    const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+    if (cur['task-003-legacy']) {
+      delete cur['task-003-legacy'];
+      fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+    }
+    child.kill();
+  }
+})();