project-knowledge 0.1.0

package/_site/lib/job-orchestrator.js

@@ -0,0 +1,231 @@
+// Job Orchestrator (TASK-010)
+//
+// Run modes for the server-side scheduler. Each mode produces a job record
+// that is persisted to <KB_ROOT>/.jobs-log.json so the user can audit what ran
+// and when.
+//
+// Modes:
+//   * `legacy`         — runs the existing PowerShell gen-commit-doc.ps1.
+//                        Kept for backward compatibility. The script writes
+//                        docs directly to the KB; this is the historical path.
+//   * `scan`           — read-only: for each enabled project, call scanProject
+//                        to update headCommit/lastSeenCommit/lastScanAt. Never
+//                        invokes AI and never writes any drafts.
+//   * `analyze-initial`— for each enabled project that has a v2 KB but no
+//                        trusted project-goal.md, run the initial-analysis
+//                        orchestrator. Drafts land under _ai/drafts/.
+//   * `analyze-commits`— for each enabled project with pending commits
+//                        (scan.pendingCount > 0), run incremental commit
+//                        analysis. Drafts land under _ai/drafts/.
+//   * `safe`           — composite mode: scan + analyze-commits. This is the
+//                        new default for the scheduled task. Crucially, it
+//                        never calls apply, so AI drafts cannot become
+//                        trusted knowledge without a human at the Drafts tab.
+//
+// All modes honor `slug` to scope a run to one project, or `ALL` (default)
+// to iterate every enabled project.
+//
+// Job records are JSON-serializable and streamed to the caller via the job
+// object passed in by the route handler (so the existing `runningJobs` map
+// can be repurposed as a live status view).
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { scanProject, applyScanResult } = require('./scanner');
+const { runInitialAnalysis, runCommitAnalysis } = require('./analysis-orchestrator');
+
+const LEGACY_SCRIPT = 'D:\\SanQian.Xu\\project-knowledge-base\\scripts\\gen-commit-doc.ps1';
+
+const KNOWN_MODES = new Set(['legacy', 'scan', 'analyze-initial', 'analyze-commits', 'safe']);
+
+function appendLine(job, line) {
+  job.output = (job.output || '') + line + '\n';
+  if (job.output.length > 200_000) {
+    job.output = job.output.slice(-200_000);
+  }
+}
+
+function appendJobLog(jobsLogPath, entry) {
+  let arr = [];
+  try { arr = JSON.parse(fs.readFileSync(jobsLogPath, 'utf-8')); } catch {}
+  if (!Array.isArray(arr)) arr = [];
+  arr.push(entry);
+  // Keep at most the most recent 100 entries
+  if (arr.length > 100) arr = arr.slice(-100);
+  try { fs.writeFileSync(jobsLogPath, JSON.stringify(arr, null, 2) + '\n', 'utf-8'); } catch {}
+}
+
+function readJobLog(jobsLogPath) {
+  if (!fs.existsSync(jobsLogPath)) return [];
+  try { return JSON.parse(fs.readFileSync(jobsLogPath, 'utf-8')) || []; }
+  catch { return []; }
+}
+
+function makeJob({ mode, slug }) {
+  return {
+    jobId: 'job-' + Date.now() + '-' + Math.floor(Math.random() * 10000),
+    mode,
+    slug: slug || 'ALL',
+    startTime: new Date().toISOString(),
+    endTime: null,
+    status: 'running',
+    exitCode: null,
+    output: '',
+    summary: null,
+  };
+}
+
+function projectList(projects, slug) {
+  // Return the live project objects (with a `slug` field guaranteed). The caller
+  // may mutate them — `runScan` does, via `applyScanResult` — and those changes
+  // should be visible in the projects map the caller passed in.
+  if (slug && slug !== 'ALL') {
+    if (!projects[slug]) throw new Error(`unknown slug: ${slug}`);
+    return [{ slug, ...projects[slug] }];
+  }
+  return Object.keys(projects)
+    .filter(s => projects[s].enabled !== false)
+    .map(s => projects[s]);
+}
+
+function defaultProjectKbPath(slug) {
+  return path.join('D:\\SanQian.Xu\\project-knowledge-base', 'projects', slug);
+}
+
+async function runScan(projects, slug, job) {
+  const list = projectList(projects, slug);
+  let scanned = 0, errors = 0;
+  for (const p of list) {
+    const scan = await scanProject(p, { maxCommits: 200 });
+    if (scan.error && scan.repoStatus !== 'ok' && scan.repoStatus !== 'empty') {
+      appendLine(job, `[scan] ${p.slug} → ${scan.repoStatus}: ${scan.error}`);
+      errors++;
+    } else {
+      // Mutate the original in the projects map so the caller sees the update.
+      const target = projects[p.slug] || p;
+      applyScanResult(target, scan);
+      appendLine(job, `[scan] ${p.slug} → head ${(scan.headCommit || '?').slice(0, 7)} · ${scan.pendingCount} pending · mode ${scan.mode || '?'}`);
+      scanned++;
+    }
+  }
+  return { scanned, errors, total: list.length };
+}
+
+async function runInitial(projects, slug, job) {
+  const list = projectList(projects, slug);
+  let ran = 0, skipped = 0, failed = 0;
+  for (const p of list) {
+    const kbPath = p.kbPath || defaultProjectKbPath(p.slug);
+    if (!fs.existsSync(kbPath)) { skipped++; appendLine(job, `[analyze-initial] ${p.slug} → skipped (no KB)`); continue; }
+    const goalPath = path.join(kbPath, 'project-goal.md');
+    if (fs.existsSync(goalPath)) { skipped++; appendLine(job, `[analyze-initial] ${p.slug} → skipped (goal already exists)`); continue; }
+    const result = await runInitialAnalysis({ slug: p.slug, ...p, kbPath });
+    if (result.ok) { ran++; appendLine(job, `[analyze-initial] ${p.slug} → run ${result.runId} (${(result.runRecord.drafts || []).length} drafts)`); }
+    else { failed++; appendLine(job, `[analyze-initial] ${p.slug} → failed: ${result.error}`); }
+  }
+  return { ran, skipped, failed, total: list.length };
+}
+
+async function runCommits(projects, slug, job) {
+  const list = projectList(projects, slug);
+  let ran = 0, noop = 0, failed = 0;
+  for (const p of list) {
+    const kbPath = p.kbPath || defaultProjectKbPath(p.slug);
+    if (!fs.existsSync(kbPath)) { appendLine(job, `[analyze-commits] ${p.slug} → skipped (no KB)`); continue; }
+    const result = await runCommitAnalysis({ slug: p.slug, ...p, kbPath });
+    if (result.ok) {
+      if (result.noop) { noop++; appendLine(job, `[analyze-commits] ${p.slug} → no pending commits`); }
+      else { ran++; appendLine(job, `[analyze-commits] ${p.slug} → run ${result.runId} (${result.runRecord.commitCount} commits)`); }
+    } else { failed++; appendLine(job, `[analyze-commits] ${p.slug} → failed: ${result.error}`); }
+  }
+  return { ran, noop, failed, total: list.length };
+}
+
+function runLegacyScript(slug, job) {
+  return new Promise((resolve) => {
+    const p = spawn('powershell', ['-ExecutionPolicy', 'Bypass', '-File', LEGACY_SCRIPT, '-ProjectSlug', slug], {
+      windowsHide: true,
+    });
+    p.stdout.on('data', d => appendLine(job, d.toString('utf-8')));
+    p.stderr.on('data', d => appendLine(job, d.toString('utf-8')));
+    p.on('close', code => resolve({ exitCode: code, status: code === 0 ? 'success' : 'failed' }));
+    p.on('error', e => resolve({ exitCode: 1, status: 'failed', error: e.message }));
+  });
+}
+
+async function runJob({ job, projects, projectsPath, jobsLogPath, writeProjects }) {
+  if (!job) throw new Error('job required');
+  if (!KNOWN_MODES.has(job.mode)) {
+    job.status = 'failed';
+    job.endTime = new Date().toISOString();
+    job.exitCode = 2;
+    job.summary = { error: `unknown mode: ${job.mode}` };
+    appendLine(job, `Unknown mode: ${job.mode}. Known: ${[...KNOWN_MODES].join(', ')}`);
+    appendJobLog(jobsLogPath, job);
+    return job;
+  }
+  const slug = job.slug || 'ALL';
+  appendLine(job, `[start] mode=${job.mode} slug=${slug} at ${job.startTime}`);
+
+  let summary = null;
+  let exitCode = 0;
+  try {
+    if (job.mode === 'legacy') {
+      const r = await runLegacyScript(slug, job);
+      exitCode = r.exitCode;
+      job.status = r.status;
+      summary = { kind: 'legacy' };
+    } else if (job.mode === 'scan') {
+      summary = await runScan(projects, slug, job);
+      job.status = summary.errors > 0 ? 'partial' : 'success';
+      exitCode = summary.errors > 0 ? 1 : 0;
+    } else if (job.mode === 'analyze-initial') {
+      summary = await runInitial(projects, slug, job);
+      job.status = summary.failed > 0 ? 'partial' : 'success';
+      exitCode = summary.failed > 0 ? 1 : 0;
+    } else if (job.mode === 'analyze-commits') {
+      summary = await runCommits(projects, slug, job);
+      job.status = summary.failed > 0 ? 'partial' : 'success';
+      exitCode = summary.failed > 0 ? 1 : 0;
+    } else if (job.mode === 'safe') {
+      // scan → analyze-commits. Crucially, no apply step.
+      const scanSummary = await runScan(projects, slug, job);
+      const commitSummary = await runCommits(projects, slug, job);
+      summary = { scan: scanSummary, commits: commitSummary, applied: 0 };
+      const totalFailed = scanSummary.errors + commitSummary.failed;
+      job.status = totalFailed > 0 ? 'partial' : 'success';
+      exitCode = totalFailed > 0 ? 1 : 0;
+      appendLine(job, `[safe] complete. applied drafts: 0 (review required).`);
+    }
+  } catch (e) {
+    job.status = 'failed';
+    exitCode = 1;
+    summary = { error: e.message };
+    appendLine(job, `[error] ${e.message}`);
+  }
+
+  job.endTime = new Date().toISOString();
+  job.exitCode = exitCode;
+  job.summary = summary;
+  appendLine(job, `[end] status=${job.status} exitCode=${exitCode}`);
+
+  // Persist any project-state changes (e.g. scan updated headCommit).
+  if (writeProjects) {
+    try { writeProjects(); } catch (e) { appendLine(job, `[warn] could not persist projects.json: ${e.message}`); }
+  }
+  appendJobLog(jobsLogPath, job);
+  return job;
+}
+
+module.exports = {
+  KNOWN_MODES,
+  makeJob,
+  runJob,
+  readJobLog,
+  appendJobLog,
+  runScan,
+  runInitial,
+  runCommits,
+  runLegacyScript,
+};

package/_site/lib/kb-validator.js

@@ -0,0 +1,224 @@
+// KB Validator (TASK-011)
+//
+// Validates that a project's knowledge base is in a state where a downstream
+// consumer (e.g. the future PR-review project) can rely on it.
+//
+// What is "valid"?
+//   * `<kbPath>/kb-manifest.json` exists and parses with `schema: "kb-manifest/v1"`.
+//   * `manifest.trustedKnowledge` lists directories the consumer is allowed to
+//     read from as authoritative. They are not required to exist, but at least
+//     the seed entry `README.md` must be listed (and exist).
+//   * `manifest.goal.path` points to a file that exists, OR is `null`/`""` (i.e.
+//     the project has not been goal-edited yet). The validator reports a clear
+//     "no goal" state instead of failing the project.
+//   * `manifest.analysis.path` points to a file that exists, OR is `null`/`""`.
+//   * If `manifest.trustedKnowledge` lists a directory, the directory either
+//     exists or is intentionally absent (a v2 KB starts with only the indexes).
+//     Missing `features/` etc. is NOT a hard error — the contract only
+//     promises that anything listed is reachable.
+//   * `manifest.draftAreas` is always a list and always includes `_ai/drafts/`,
+//     `_ai/runs/`, and `_ai/context-packs/`. These are the explicit "do not
+//     trust without human review" zones.
+//   * `_ai/` is present and contains `drafts/`, `runs/`, and `context-packs/`
+//     subdirectories (the consumer must never accidentally treat drafts as
+//     authoritative).
+//
+// What is "invalid"?
+//   * The manifest JSON does not parse.
+//   * The manifest schema is not `kb-manifest/v1`.
+//   * `manifest.goal.path` is set but the file does not exist.
+//   * `manifest.analysis.path` is set but the file does not exist.
+//   * Any entry in `manifest.trustedKnowledge` is non-empty and does not
+//     resolve to an existing file or directory.
+//   * A path listed in `manifest.trustedKnowledge` is actually inside the AI
+//     draft area (e.g. `_ai/`). That would mean someone tried to elevate a
+//     draft to trusted knowledge without going through apply — the validator
+//     refuses to certify the project in that case.
+
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_SCHEMA = 'kb-manifest/v1';
+const REQUIRED_DRAFT_AREAS = ['_ai/drafts/', '_ai/runs/', '_ai/context-packs/'];
+
+function readJsonSafe(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); }
+  catch (e) { return { __error: e.message, __path: p }; }
+}
+
+function existsAny(root, rel) {
+  if (!rel) return false;
+  const abs = path.resolve(root, rel);
+  return fs.existsSync(abs);
+}
+
+function isInsideDraftArea(rel) {
+  const norm = String(rel || '').replace(/\\/g, '/');
+  return norm === '_ai' || norm.startsWith('_ai/');
+}
+
+function validateKb(kbPath) {
+  const errors = [];
+  const warnings = [];
+  const info = {
+    kbPath,
+    manifestExists: false,
+    goalStatus: 'unknown',
+    analysisStatus: 'unknown',
+    trustedKnowledgeEntries: 0,
+    draftAreasEntries: 0,
+    aiSubdirsPresent: [],
+  };
+
+  if (!kbPath || !fs.existsSync(kbPath)) {
+    return { ok: false, status: 400, error: `kbPath does not exist: ${kbPath}` };
+  }
+  if (!fs.statSync(kbPath).isDirectory()) {
+    return { ok: false, status: 400, error: `kbPath is not a directory: ${kbPath}` };
+  }
+
+  const manifestPath = path.join(kbPath, 'kb-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    return { ok: false, status: 422, error: 'kb-manifest.json missing', info, errors: ['manifest missing'] };
+  }
+  info.manifestExists = true;
+
+  const manifest = readJsonSafe(manifestPath);
+  if (manifest.__error) {
+    return { ok: false, status: 422, error: `kb-manifest.json could not be parsed: ${manifest.__error}`, info, errors: ['manifest unparseable'] };
+  }
+
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    errors.push(`manifest.schema must be ${MANIFEST_SCHEMA}, got ${JSON.stringify(manifest.schema)}`);
+  }
+
+  // --- goal ---
+  if (manifest.goal && manifest.goal.path) {
+    if (isInsideDraftArea(manifest.goal.path)) {
+      errors.push(`manifest.goal.path is inside _ai/ (${manifest.goal.path}) — drafts must not be trusted knowledge`);
+    } else if (!existsAny(kbPath, manifest.goal.path)) {
+      errors.push(`manifest.goal.path (${manifest.goal.path}) does not exist on disk`);
+    } else {
+      info.goalStatus = manifest.goal.status || 'accepted';
+    }
+  } else {
+    info.goalStatus = 'not-created';
+  }
+
+  // --- analysis ---
+  if (manifest.analysis && manifest.analysis.path) {
+    if (isInsideDraftArea(manifest.analysis.path)) {
+      errors.push(`manifest.analysis.path is inside _ai/ (${manifest.analysis.path})`);
+    } else if (!existsAny(kbPath, manifest.analysis.path)) {
+      errors.push(`manifest.analysis.path (${manifest.analysis.path}) does not exist on disk`);
+    } else {
+      info.analysisStatus = 'present';
+    }
+  } else {
+    info.analysisStatus = 'not-created';
+  }
+
+  // --- trustedKnowledge ---
+  if (!Array.isArray(manifest.trustedKnowledge)) {
+    errors.push('manifest.trustedKnowledge must be an array');
+  } else {
+    info.trustedKnowledgeEntries = manifest.trustedKnowledge.length;
+    if (!manifest.trustedKnowledge.includes('README.md')) {
+      warnings.push('manifest.trustedKnowledge should include README.md');
+    }
+    for (const rel of manifest.trustedKnowledge) {
+      if (!rel || typeof rel !== 'string') { errors.push(`trustedKnowledge entry is not a non-empty string: ${JSON.stringify(rel)}`); continue; }
+      if (isInsideDraftArea(rel)) {
+        errors.push(`trustedKnowledge entry is inside _ai/: ${rel}`);
+        continue;
+      }
+      // Trust-entries that end with `/` are directories. Others are files.
+      const expectsDir = rel.endsWith('/');
+      if (!existsAny(kbPath, rel)) {
+        warnings.push(`trustedKnowledge entry does not exist on disk: ${rel}`);
+        continue;
+      }
+      const abs = path.resolve(kbPath, rel);
+      const stat = fs.statSync(abs);
+      if (expectsDir && !stat.isDirectory()) warnings.push(`trustedKnowledge entry is a file but listed as a dir: ${rel}`);
+      if (!expectsDir && stat.isDirectory()) warnings.push(`trustedKnowledge entry is a dir but listed as a file: ${rel}`);
+    }
+  }
+
+  // --- draftAreas ---
+  if (!Array.isArray(manifest.draftAreas)) {
+    errors.push('manifest.draftAreas must be an array');
+  } else {
+    info.draftAreasEntries = manifest.draftAreas.length;
+    for (const required of REQUIRED_DRAFT_AREAS) {
+      if (!manifest.draftAreas.includes(required)) {
+        warnings.push(`manifest.draftAreas should include ${required}`);
+      }
+    }
+    for (const rel of manifest.draftAreas) {
+      if (isInsideDraftArea(rel)) continue;
+      warnings.push(`draftArea entry is not inside _ai/: ${rel}`);
+    }
+  }
+
+  // --- _ai/ subdirs on disk ---
+  for (const sub of REQUIRED_DRAFT_AREAS) {
+    const abs = path.join(kbPath, sub);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      info.aiSubdirsPresent.push(sub);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    status: errors.length ? 422 : 200,
+    info,
+    errors,
+    warnings,
+    manifest: errors.length ? null : manifest,
+  };
+}
+
+function buildPrContextPack(kbPath) {
+  // Build a small, JSON-serializable context pack a PR-review tool can
+  // consume directly: the project goal, the analysis, and the indexes. The
+  // pack never reads from _ai/; only from manifest.trustedKnowledge.
+  const v = validateKb(kbPath);
+  if (!v.ok) return { ok: false, status: v.status || 422, error: 'kb invalid', validation: v };
+  const manifest = v.manifest;
+  const read = rel => {
+    if (!rel || !existsAny(kbPath, rel)) return null;
+    const abs = path.resolve(kbPath, rel);
+    return { path: rel, content: fs.readFileSync(abs, 'utf-8'), size: fs.statSync(abs).size };
+  };
+  const pack = {
+    schema: 'pr-context-pack/v1',
+    generatedAt: new Date().toISOString(),
+    project: manifest.project,
+    goal: read(manifest.goal && manifest.goal.path),
+    analysis: read(manifest.analysis && manifest.analysis.path),
+    indexes: {},
+    trustedKnowledge: [],
+  };
+  if (manifest.indexes) {
+    for (const [k, rel] of Object.entries(manifest.indexes)) {
+      const got = read(rel);
+      if (got) pack.indexes[k] = got;
+    }
+  }
+  if (Array.isArray(manifest.trustedKnowledge)) {
+    for (const rel of manifest.trustedKnowledge) {
+      if (!rel || rel.endsWith('/')) continue; // directories
+      const got = read(rel);
+      if (got) pack.trustedKnowledge.push(got);
+    }
+  }
+  return { ok: true, pack };
+}
+
+module.exports = {
+  MANIFEST_SCHEMA,
+  REQUIRED_DRAFT_AREAS,
+  validateKb,
+  buildPrContextPack,
+};

package/_site/lib/llm-client.js

@@ -0,0 +1,126 @@
+// _site/lib/llm-client.js
+//
+// Tiny Anthropic Messages API client. Zero npm deps; uses node:https.
+// Reads connection settings from env (so the same adapter works against
+// the real Anthropic API, the system-level proxy at api.minimaxi.com,
+// or any other Anthropic-compatible endpoint):
+//
+//   ANTHROPIC_BASE_URL   default "https://api.anthropic.com"
+//   ANTHROPIC_AUTH_TOKEN required
+//   ANTHROPIC_MODEL      default "claude-haiku-4-5"
+//   ANTHROPIC_VERSION    default "2023-06-01"
+//
+// The client returns { text, usage, raw }. Callers are responsible for
+// parsing the model output (usually as JSON) and for any retries.
+
+const https = require('https');
+const { URL } = require('url');
+
+const DEFAULT_BASE = 'https://api.anthropic.com';
+const DEFAULT_VERSION = '2023-06-01';
+const DEFAULT_MODEL = 'claude-haiku-4-5';
+
+function readConfig() {
+  return {
+    baseUrl: process.env.ANTHROPIC_BASE_URL || DEFAULT_BASE,
+    apiKey: process.env.ANTHROPIC_AUTH_TOKEN || '',
+    model: process.env.ANTHROPIC_MODEL || DEFAULT_MODEL,
+    version: process.env.ANTHROPIC_VERSION || DEFAULT_VERSION,
+  };
+}
+
+function postJson({ baseUrl, path: p, body, apiKey, version, timeoutMs = 60_000 }) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      // Allow baseUrl to contain a path prefix (e.g. "https://api.x.com/anthropic").
+      // We resolve `p` relative to that base, but the result must be treated
+      // as the final URL — no further prefix insertion.
+      const base = new URL(baseUrl);
+      // base.pathname is already a valid path; we replace naively if p starts with /
+      let fullPath;
+      if (p.startsWith('/')) {
+        // Strip a trailing slash from base.pathname, then concatenate.
+        const basePath = base.pathname.endsWith('/') ? base.pathname.slice(0, -1) : base.pathname;
+        fullPath = basePath + p;
+      } else {
+        fullPath = p;
+      }
+      const data = JSON.stringify(body);
+      const req = https.request({
+        host: base.host,
+        port: base.port || 443,
+        path: fullPath,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': apiKey,
+          'anthropic-version': version,
+          'Content-Length': Buffer.byteLength(data),
+        },
+        timeout: timeoutMs,
+      }, res => {
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf-8');
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            return reject(new Error(`HTTP ${res.statusCode}: ${text.slice(0, 500)}`));
+          }
+          try { resolve(JSON.parse(text)); }
+          catch (e) { reject(new Error(`bad JSON: ${e.message}; body head: ${text.slice(0, 200)}`)); }
+        });
+      });
+      req.on('error', reject);
+      req.on('timeout', () => req.destroy(new Error(`timeout after ${timeoutMs}ms`)));
+      req.write(data);
+      req.end();
+    } catch (e) { return reject(new Error(`bad baseUrl: ${baseUrl}: ${e.message}`)); }
+  });
+}
+
+async function completeJson({ system, user, schema, maxTokens = 2048, temperature = 0.2, model }) {
+  const cfg = readConfig();
+  if (!cfg.apiKey) throw new Error('ANTHROPIC_AUTH_TOKEN not set');
+  const useModel = model || cfg.model;
+  // Wrap the user content in a directive that asks for strict JSON. The
+  // adapter is also told the schema; it must return JSON that the KB
+  // orchestrator's validateOutput can check.
+  const schemaHint = schema ? `\n\nThe output MUST be a JSON object matching this schema:\n${schema}\n` : '';
+  const finalUser = `${user}${schemaHint}\n\nRespond with ONLY the JSON object, no prose, no markdown fences.`;
+  const messages = [{ role: 'user', content: finalUser }];
+  const body = {
+    model: useModel,
+    max_tokens: maxTokens,
+    temperature,
+    messages,
+  };
+  if (system) body.system = system;
+  const raw = await postJson({
+    baseUrl: cfg.baseUrl,
+    path: '/v1/messages',
+    body,
+    apiKey: cfg.apiKey,
+    version: cfg.version,
+  });
+  // The Messages API returns content as an array of blocks; we expect one text block.
+  const text = (raw.content || [])
+    .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+    .map(b => b.text)
+    .join('\n')
+    .trim();
+  let parsed = null;
+  let parseError = null;
+  // First try direct parse; if that fails, strip a leading ```json fence.
+  const candidates = [
+    text,
+    text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, ''),
+  ];
+  for (const c of candidates) {
+    if (!c) continue;
+    try { parsed = JSON.parse(c); parseError = null; break; } catch (e) { parseError = e; }
+  }
+  return { text, parsed, parseError, raw };
+}
+
+module.exports = { completeJson, readConfig };

package/_site/lib/scanner.js

@@ -0,0 +1,94 @@
+// Shared scanner used by the server and the analysis orchestrator.
+const fs = require('fs');
+const path = require('path');
+const { execGit } = require('./git-runner');
+
+async function scanProject(project, options = {}) {
+  const { maxCommits = 200 } = options;
+  const result = {
+    slug: project && project.slug,
+    repoStatus: 'unknown',
+    headCommit: null,
+    lastSeenCommit: project ? project.lastSeenCommit : null,
+    lastAnalyzedCommit: project ? project.lastAnalyzedCommit : null,
+    pendingCount: 0,
+    mode: null,
+    range: null,
+    commits: [],
+    error: null,
+  };
+  if (!project) { result.error = 'no project'; return result; }
+
+  const targetPath = project.gitPath || project.localPath;
+  if (!targetPath) {
+    result.repoStatus = 'missing-path';
+    result.error = 'no git path configured';
+    return result;
+  }
+  if (!fs.existsSync(targetPath)) {
+    result.repoStatus = 'missing-path';
+    result.error = `path not found: ${targetPath}`;
+    return result;
+  }
+  const inside = await execGit(targetPath, ['rev-parse', '--is-inside-work-tree']);
+  if (!inside.ok || (inside.stdout || '').trim() !== 'true') {
+    result.repoStatus = 'not-git';
+    result.error = 'not a git repository';
+    return result;
+  }
+  const head = await execGit(targetPath, ['rev-parse', 'HEAD']);
+  if (!head.ok) {
+    result.repoStatus = 'empty';
+    result.error = 'repository has no commits';
+    return result;
+  }
+  result.headCommit = (head.stdout || '').trim() || null;
+  result.repoStatus = 'ok';
+
+  if (!project.lastAnalyzedCommit) {
+    result.mode = 'initial';
+    const logArgs = ['log', '--no-merges', `--max-count=${maxCommits}`, '--pretty=format:%H|%h|%ad|%an|%s', '--date=short'];
+    const log = await execGit(targetPath, logArgs);
+    if (log.ok) {
+      const lines = (log.stdout || '').split('\n').filter(l => l.includes('|'));
+      for (const line of lines) {
+        const [hash, short, date, author, ...rest] = line.split('|');
+        result.commits.push({ hash, short, date, author, subject: rest.join('|') });
+      }
+    } else {
+      result.error = (log.stderr || log.error || 'git log failed').toString();
+    }
+    result.range = `HEAD~${result.commits.length}..HEAD`;
+  } else {
+    result.mode = 'incremental';
+    const range = `${project.lastAnalyzedCommit}..${result.headCommit}`;
+    result.range = range;
+    const logArgs = ['log', '--no-merges', range, '--pretty=format:%H|%h|%ad|%an|%s', '--date=short'];
+    const log = await execGit(targetPath, logArgs);
+    if (log.ok) {
+      const lines = (log.stdout || '').split('\n').filter(l => l.includes('|'));
+      for (const line of lines) {
+        const [hash, short, date, author, ...rest] = line.split('|');
+        result.commits.push({ hash, short, date, author, subject: rest.join('|') });
+      }
+    } else {
+      result.error = (log.stderr || log.error || 'git log failed').toString();
+    }
+  }
+
+  result.pendingCount = result.commits.length;
+  return result;
+}
+
+async function applyScanResult(project, scan) {
+  project.headCommit = scan.headCommit;
+  project.repoStatus = scan.repoStatus;
+  project.lastSeenCommit = scan.headCommit || project.lastSeenCommit;
+  project.lastScanAt = new Date().toISOString();
+  project.lastScanPendingCount = scan.pendingCount;
+  project.lastScanMode = scan.mode;
+  project.lastScanError = scan.error || null;
+  return project;
+}
+
+module.exports = { scanProject, applyScanResult };