shakers-cli-beta 0.8.0-beta.0

package/src/repo-context.js

@@ -0,0 +1,215 @@
+'use strict';
+
+// repo-context.js — collect a COMPACT, content-free structural context of a codebase for the LLM analysis that builds the LOCAL report's graph (`map`).
+
+const fs = require('fs');
+const path = require('path');
+const { scrubString } = require('./graph-generator');
+const { modelNode } = require('./graph-scan'); // exact-model resolver (aliases → exact ids)
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo', 'vendor', '__snapshots__', '__tests__', '__mocks__', 'test', 'tests', 'e2e']);
+const CODE_EXT = new Set(['.ts', '.js', '.tsx', '.jsx', '.mjs', '.cts', '.mts']);
+const SKIP_FILE_RE = /\.(spec|test|e2e-spec|d)\.[tj]sx?$/;
+const MAX_FILES = 6000;
+const MAX_READ = 700;
+const MAX_BYTES_PER = 200 * 1024;
+const LINE_MAX = 160;
+const CAP = { entrypoints: 12, crons: 18, agents: 30, integrations: 20, stores: 12, services: 40, tech: 60 };
+
+const AI_RE = /generateText|streamText|generateObject|streamObject|embedMany|tool\s*\(|@ai-sdk\/|from\s+['"]ai['"]|new\s+OpenAI|new\s+Anthropic|@anthropic-ai\/sdk|GoogleGenerativeAI|@google\/(?:genai|generative-ai)|Gemini\w*Service|Anthropic\w*Service|ShakersAi\w*|\.sendMessage\(|\.messages\.create\(|\.chat\.completions\.create\(|\.generateContent\(|\.responses\.create\(|ChatOpenAI|langchain|llamaindex|createAgent|AgentExecutor/;
+const CRON_RE = /@Cron\b|CronExpression|new\s+CronJob|EVERY_(MINUTE|HOUR|DAY)/;
+const CRON_PATH_RE = /(\.cron\.[tj]s$|(^|\/)cron-jobs?\/|(^|\/)crons?\/)/i;
+const ENTRY_PATH_RE = /(controller|\.route|router|webhook|gateway|resolver|main\.[tj]s|(^|\/)cli\/|(^|\/)commands?\/)/i;
+const IMPORT_RE = /^\s*(import\b|const\b.*=\s*require\()/;
+
+// npm import substring -> integration/provider label
+const INTEG = [
+  [/stripe/i, 'Stripe'], [/hubspot/i, 'HubSpot'], [/(datadog|dd-trace)/i, 'Datadog'],
+  [/twilio/i, 'Twilio'], [/(sendgrid|@sendgrid)/i, 'SendGrid'], [/(@slack|slack-)/i, 'Slack'],
+  [/(bigquery|@google-cloud\/bigquery)/i, 'BigQuery'], [/holded/i, 'Holded'], [/adobe/i, 'Adobe PDF'],
+  [/n8n/i, 'n8n'], [/cloudfront/i, 'CloudFront'], [/(mongoose|mongodb)/i, 'MongoDB'],
+  [/(ioredis|['"]redis['"])/i, 'Redis'], [/@aws-sdk|aws-sdk/i, 'AWS'],
+];
+// integrations/<dir> -> label (a dir under any `integrations/` path = a wired service)
+const INTEG_DIR = {
+  hubspot: 'HubSpot', holded: 'Holded', slack: 'Slack', datadog: 'Datadog', bigquery: 'BigQuery',
+  adobe: 'Adobe PDF', 'adobe-pdf': 'Adobe PDF', n8n: 'n8n', cloudfront: 'CloudFront', s3: 'AWS S3',
+  stripe: 'Stripe', match: 'calc-match', 'shakers-ai': 'shakers-ai-api', 'sh-ai': 'shakers-ai-api',
+  twilio: 'Twilio', sendgrid: 'SendGrid',
+};
+const MODEL_DIRS = new Set(['gemini', 'anthropic', 'openai']); // integration dirs that are MODELS, not externals
+
+function slug(s) { return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'x'; }
+function clip(s) { s = String(s || '').trim(); return s.length > LINE_MAX ? s.slice(0, LINE_MAX) + '…' : s; }
+function titleize(s) { return String(s || '').replace(/[-_]+/g, ' ').replace(/\.(service|controller|cron|module)$/i, '').trim().replace(/\b\w/g, (c) => c.toUpperCase()).slice(0, 40); }
+function readSafe(p) { try { const st = fs.statSync(p); if (st.size > MAX_BYTES_PER) return null; return fs.readFileSync(p, 'utf8'); } catch { return null; } }
+
+function providerFromLine(line) {
+  const l = String(line || '').toLowerCase();
+  if (/gemini|generatecontent|google.*genai|generativeai/.test(l)) return { label: 'Gemini', domain: 'gemini.google.com' };
+  if (/anthropic|claude|messages\.create/.test(l)) return { label: 'Claude', domain: 'claude.ai' };
+  if (/openai|chat\.completions|responses\.create|\bgpt\b/.test(l)) return { label: 'OpenAI', domain: 'openai.com' };
+  if (/shakersai|sh_ai|shakers-ai|chatgpt/.test(l)) return { label: 'shakers-ai-api', domain: null };
+  return null;
+}
+
+function walk(root) {
+  const files = [];
+  const stack = [root];
+  while (stack.length && files.length < MAX_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (files.length >= MAX_FILES) break;
+      if (e.name.startsWith('.') && e.name !== '.claude') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (CODE_EXT.has(path.extname(e.name)) && !SKIP_FILE_RE.test(e.name)) files.push(full);
+    }
+  }
+  return files;
+}
+
+function entryGroup(rel) {
+  const p = rel.toLowerCase();
+  const app = (p.match(/(?:^|\/)apps\/([^/]+)\//) || [])[1];
+  if (app) return { key: 'app:' + app, label: titleize(app) + ' API', sub: `apps/${app}` };
+  const integ = (p.match(/(?:^|\/)integrations\/([^/]+)\/.*(webhook|controller)/) || [])[1];
+  if (integ) return { key: 'wh:' + integ, label: titleize(integ) + ' webhook', sub: 'inbound webhook' };
+  if (/gateway|websocket|\bws\b/.test(p)) return { key: 'ws', label: 'WebSocket gateway', sub: 'realtime' };
+  if (/(^|\/)cli\/|(^|\/)commands?\//.test(p)) return { key: 'cli', label: 'CLI', sub: 'commands' };
+  if (/main\.[tj]s$/.test(p)) return { key: 'http', label: 'HTTP server', sub: 'main' };
+  if (/webhook/.test(p)) return { key: 'wh', label: 'Webhook', sub: 'inbound' };
+  return { key: 'ctrl', label: 'HTTP API', sub: 'controllers' };
+}
+
+function collectRepoContext(root, { readFileImpl = readSafe } = {}) {
+  const abs = path.resolve(root || process.cwd());
+  const rel = (p) => path.relative(abs, p) || path.basename(p);
+
+  const ctx = {
+    project: { name: scrubString(path.basename(abs) || 'project'), slug: slug(path.basename(abs)), date: new Date().toISOString().slice(0, 10) },
+    entrypoints: [], crons: [], agents: [], services: [], models: [], integrations: [], stores: [], technologies: [],
+  };
+  const integrationSet = new Set();
+  const modelSet = new Map();
+  const storeSet = new Set();
+  const serviceSet = new Set();
+  const entryGroups = new Map();
+  const cronFiles = new Set();
+  const aiFiles = new Map(); // path -> { provider, line }
+
+  const pkgRaw = readFileImpl(path.join(abs, 'package.json'));
+  if (pkgRaw) {
+    try {
+      const pkg = JSON.parse(pkgRaw);
+      if (pkg.name) { const nm = pkg.name.replace(/^@[^/]+\//, ''); ctx.project.name = scrubString(nm); ctx.project.slug = slug(nm); }
+      if (pkg.description) ctx.project.tagline = scrubString(clip(pkg.description));
+      ctx.technologies = Object.keys({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }).slice(0, CAP.tech).map(scrubString);
+    } catch { /* ignore */ }
+  }
+
+  // Prisma stores (datasource provider). schema.prisma OR prisma/schema/ dir.
+  const eatPrisma = (raw) => {
+    if (!raw) return;
+    const provider = (raw.match(/datasource\s+\w+\s*\{[^}]*provider\s*=\s*"([^"]+)"/m) || [])[1];
+    if (provider) storeSet.add(provider === 'postgresql' ? 'PostgreSQL' : titleize(provider));
+  };
+  for (const cand of ['prisma/schema.prisma', 'schema.prisma']) { const r = readFileImpl(path.join(abs, cand)); if (r) { eatPrisma(r); break; } }
+  for (const dir of ['prisma/schema', 'prisma']) {
+    const d = path.join(abs, dir);
+    try { if (fs.statSync(d).isDirectory()) for (const f of fs.readdirSync(d)) if (f.endsWith('.prisma')) eatPrisma(readFileImpl(path.join(d, f))); } catch { /* none */ }
+  }
+
+  try {
+    for (const f of fs.readdirSync(path.join(abs, '.claude', 'agents'))) {
+      if (!f.endsWith('.md')) continue;
+      const raw = readFileImpl(path.join(abs, '.claude', 'agents', f)) || '';
+      const mm = raw.match(/^\s*model\s*:\s*["']?([^"'\n]+?)["']?\s*$/im);
+      const mn = mm ? modelNode(mm[1].trim()) : null;
+      const provider = mn ? mn.label : null;
+      if (mn) modelSet.set(mn.label, { label: mn.label, ...(mn.domain ? { domain: mn.domain } : {}) });
+      ctx.agents.push({ label: titleize(path.basename(f, '.md')), provider, path: scrubString(`.claude/agents/${f}`) });
+    }
+  } catch { /* none */ }
+
+  // scan code files — AI/flow-likely first
+  const score = (p) => {
+    if (/(gemini|openai|anthropic|claude|ai-footprint|\bai\b|\/ai[-/]|llm|agent|orchestrat|generate-|chat|embed|personaliz|translat|synthes|certif|recomm|summar|extract|classif|briefing|showcase)/i.test(p)) return 0;
+    if (/(\.service\.|controller|\.cron|worker|queue|webhook|gateway|resolver|handler|integrations\/)/i.test(p)) return 1;
+    return 2;
+  };
+  const files = walk(abs).sort((a, b) => score(rel(a)) - score(rel(b)));
+  let readCount = 0;
+  for (const f of files) {
+    const r = rel(f);
+    // integration dirs → externals or models (KNOWN dirs only, to avoid noise
+    // from generic subdirs like ai/chat/http/config)
+    const idir = (r.match(/(?:^|\/)integrations\/([^/]+)\//) || [])[1];
+    if (idir) {
+      const key = idir.toLowerCase();
+      if (MODEL_DIRS.has(key)) { const pv = providerFromLine(key); if (pv) modelSet.set(pv.label, pv); }
+      else if (INTEG_DIR[key]) integrationSet.add(INTEG_DIR[key]);
+    }
+    // module/service dirs
+    const mod = (r.match(/(?:^|\/)modules\/([^/]+)\//) || [])[1];
+    if (mod && !/^(prisma|mongo|base-http|response|counter|shared|common|health)$/i.test(mod)) serviceSet.add(mod);
+    // datastore hints from path/libs
+    if (/aws-sdk\/client-s3|(^|\/)s3\b/i.test(r)) storeSet.add('AWS S3');
+    if (/cloudfront/i.test(r)) storeSet.add('CloudFront KVS');
+    // entrypoints (grouped)
+    if (ENTRY_PATH_RE.test(r) && !CRON_PATH_RE.test(r)) { const g = entryGroup(r); if (!entryGroups.has(g.key)) entryGroups.set(g.key, g); }
+    // crons (per file, by path)
+    if (CRON_PATH_RE.test(r)) cronFiles.add(r);
+
+    if (readCount >= MAX_READ) continue;
+    const src = readFileImpl(f);
+    if (src == null) continue;
+    readCount++;
+    const lines = src.split('\n');
+    let firstAi = null;
+    for (const ln of lines) {
+      if (!firstAi && AI_RE.test(ln)) firstAi = ln;
+      if (CRON_RE.test(ln)) cronFiles.add(r);
+      if (IMPORT_RE.test(ln)) {
+        for (const [re, label] of INTEG) if (re.test(ln)) {
+          if (/mongo/i.test(label)) storeSet.add('MongoDB');
+          else if (/redis/i.test(label)) storeSet.add('Redis');
+          else if (label === 'AWS') storeSet.add('AWS S3');
+          else integrationSet.add(label);
+        }
+        const pv = providerFromLine(ln);
+        if (pv && pv.domain) modelSet.set(pv.label, pv);
+      }
+    }
+    if (firstAi) aiFiles.set(r, { provider: providerFromLine(firstAi), line: clip(firstAi) });
+  }
+
+  const AGENT_SKIP_DIR = /^(gemini|anthropic|openai|http|base-http|event|config|util|shared|common|prisma|mongo|health|logger|integrations)$/i;
+  for (const [p, info] of aiFiles) {
+    if (ctx.agents.length >= CAP.agents) break;
+    if (/(?:^|\/)integrations\//.test(p)) { // the provider client, not an agent
+      if (info.provider && info.provider.domain) modelSet.set(info.provider.label, info.provider);
+      continue;
+    }
+    const dir = p.split('/').slice(-2, -1)[0] || path.basename(p);
+    if (AGENT_SKIP_DIR.test(dir)) continue;
+    ctx.agents.push({ label: titleize(dir), provider: info.provider ? info.provider.label : null, path: scrubString(p) });
+    if (info.provider && info.provider.domain) modelSet.set(info.provider.label, info.provider);
+    else if (info.provider) integrationSet.add(info.provider.label); // shakers-ai-api = external tool
+  }
+  const hasApp = [...entryGroups.keys()].some((k) => k.startsWith('app:'));
+  const hasNamedWebhook = [...entryGroups.keys()].some((k) => k.startsWith('wh:'));
+  if (hasApp) { entryGroups.delete('ctrl'); entryGroups.delete('http'); }
+  if (hasNamedWebhook) entryGroups.delete('wh');
+  ctx.entrypoints = Array.from(entryGroups.values()).slice(0, CAP.entrypoints).map((g) => ({ label: g.label, sub: g.sub }));
+  ctx.crons = Array.from(cronFiles).slice(0, CAP.crons).map((p) => ({ label: titleize(path.basename(p).replace(/\.(cron\.)?[tj]s$/, '')), path: scrubString(p) }));
+  ctx.services = Array.from(serviceSet).slice(0, CAP.services).map((m) => titleize(m));
+  ctx.models = Array.from(modelSet.values());
+  ctx.integrations = Array.from(integrationSet).slice(0, CAP.integrations);
+  ctx.stores = Array.from(storeSet).slice(0, CAP.stores);
+  return ctx;
+}
+
+module.exports = { collectRepoContext, slug };

package/src/report-gating.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { loadAuthSession, sessionStatus, isPlatformTalent } = require('./auth-session-store');
+const { getProfile } = require('./config');
+
+// THE ONE LAYER THAT DECIDES WHAT THE REPORT SHOWS ACCORDING TO IDENTITY (talents-ai-score, issue 123 / ADR-044).
+
+// Pure: identity in, policy out.
+function resolveReportGate({ loggedIn = false, status = null, email = null, userType = null, profile = 'talent' } = {}) {
+  const showEverything = !loggedIn;
+  const resolvedProfile = profile === 'external' ? 'external' : 'talent';
+  return Object.freeze({
+    loggedIn: !!loggedIn,
+    profile: resolvedProfile,
+    sessionStatus: status,
+    email: loggedIn && typeof email === 'string' && email ? email : null,
+    // --roadmap AND its server-side computation/egress (see bin/report.js): a
+    // logged-in Talent's roadmap is not merely hidden, it is not requested.
+    showRoadmap: showEverything,
+    // Per-agent "how to improve this agent" tips in the footprint report.
+    showAgentSuggestions: showEverything,
+    // The copyable remediation prompt in a `certify` verdict.
+    showCertifyRemediation: showEverything,
+    showFrameworkIntro: resolvedProfile === 'talent' && loggedIn && isPlatformTalent({ userType }),
+  });
+}
+
+// The general-user policy, used when a renderer is called without a gate. Frozen
+// and shared so callers cannot accidentally mutate the default for everyone.
+const DEFAULT_REPORT_GATE = resolveReportGate({ loggedIn: false });
+
+// Reads the auth session and resolves the policy.
+function reportGateForIdentity(env = process.env, now = Date.now()) {
+  const session = loadAuthSession(env);
+  const status = sessionStatus(session, now);
+  return resolveReportGate({
+    loggedIn: status === 'active',
+    status,
+    email: session ? session.email : null,
+    userType: session ? session.userType : null,
+    profile: getProfile(env),
+  });
+}
+
+module.exports = {
+  resolveReportGate,
+  reportGateForIdentity,
+  DEFAULT_REPORT_GATE,
+};

package/src/report-store.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const { getConfigDir } = require('./config-dir');
+const { renderSheet } = require('./render-sheet');
+const { reportGateForIdentity } = require('./report-gating');
+
+const SCHEMA_VERSION = 2;
+
+function configDir() {
+  return getConfigDir(process.env);
+}
+function statePath() {
+  return path.join(configDir(), 'report-state.json');
+}
+
+// Stable, filesystem-safe per-project file name derived from the absolute path.
+function projectSlug(absRoot) {
+  return crypto.createHash('sha1').update(String(absRoot)).digest('hex').slice(0, 12);
+}
+function htmlPathFor(absRoot) {
+  return path.join(configDir(), `report-${projectSlug(path.resolve(absRoot))}.html`);
+}
+
+// A real file:// URL (handles spaces, Windows drive letters, etc.) so the CLI
+// can print a link the talent can click/paste to open the report.
+function fileUrl(p) {
+  return pathToFileURL(p).href;
+}
+
+function freshState() {
+  return { schemaVersion: SCHEMA_VERSION, updatedAt: null, projects: {} };
+}
+
+function migrateFromV1(parsed) {
+  const projects = {};
+  const legacyFootprints = parsed && parsed.footprints && typeof parsed.footprints === 'object'
+    ? parsed.footprints
+    : {};
+  for (const [absRoot, fp] of Object.entries(legacyFootprints)) {
+    projects[absRoot] = {
+      root: (fp && fp.root) || absRoot,
+      updatedAt: (fp && fp.generatedAt) || null,
+      footprint: fp
+        ? { generatedAt: fp.generatedAt || null, report: fp.report, maturity: fp.maturity }
+        : null,
+      certifications: {},
+    };
+  }
+  return { schemaVersion: SCHEMA_VERSION, updatedAt: (parsed && parsed.updatedAt) || null, projects };
+}
+
+function loadState() {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(statePath(), 'utf8'));
+  } catch {
+    return freshState();
+  }
+  if (parsed && parsed.schemaVersion === SCHEMA_VERSION && parsed.projects && typeof parsed.projects === 'object') {
+    return { schemaVersion: SCHEMA_VERSION, updatedAt: parsed.updatedAt || null, projects: parsed.projects };
+  }
+  // Any older / unknown shape (v1 global model, or garbage) -> migrate what we can.
+  return migrateFromV1(parsed);
+}
+
+function saveState(state) {
+  fs.mkdirSync(configDir(), { recursive: true });
+  fs.writeFileSync(statePath(), JSON.stringify(state, null, 2));
+}
+
+function getOrCreateProject(state, absRoot) {
+  if (!state.projects[absRoot]) {
+    state.projects[absRoot] = {
+      root: absRoot,
+      updatedAt: null,
+      footprint: null,
+      certifications: {},
+      backendAcceptance: {},
+    };
+  }
+  // Backward-compat: a project persisted before the two-backend chain
+  // existed (talents-ai-score, ADR-020/021).
+  if (!state.projects[absRoot].backendAcceptance) {
+    state.projects[absRoot].backendAcceptance = {};
+  }
+  return state.projects[absRoot];
+}
+
+/* ---------- rendering a SINGLE project's document ---------- */
+
+function renderProjectHtml(project, lang, gate) {
+  return renderSheet(project, lang, gate);
+}
+
+/* ---------- persist (state only) + materialize (render HTML) ---------- */
+// ADR-016 split: `footprint` and `certify` now PERSIST state only (no HTML file, no printed link).
+
+function stampAndSaveState(state, absRoot) {
+  state.schemaVersion = SCHEMA_VERSION;
+  const now = new Date().toISOString();
+  state.updatedAt = now;
+  state.projects[absRoot].updatedAt = now;
+  saveState(state);
+  return { statePath: statePath(), stateDir: configDir() };
+}
+
+function writeProjectHtml(project, absRoot, lang, gate) {
+  const html = renderProjectHtml(project, lang, gate);
+  fs.mkdirSync(configDir(), { recursive: true });
+  const p = htmlPathFor(absRoot);
+  fs.writeFileSync(p, html);
+  return { htmlPath: p, fileUrl: fileUrl(p) };
+}
+
+// Persist THIS project's footprint into report-state.json (keyed by absolute project path).
+function persistFootprint({ root, report, maturity }) {
+  const absRoot = path.resolve(root || process.cwd());
+  const state = loadState();
+  const project = getOrCreateProject(state, absRoot);
+  project.footprint = {
+    generatedAt: (report && report.generatedAt) || new Date().toISOString(),
+    report,
+    maturity,
+  };
+  return stampAndSaveState(state, absRoot);
+}
+
+function loadAgentClassifications(root) {
+  const absRoot = path.resolve(root || process.cwd());
+  const state = loadState();
+  const project = state.projects && state.projects[absRoot];
+  const evaluation = project && project.footprint && project.footprint.report && project.footprint.report.agentEvaluation;
+  const evaluations = evaluation && Array.isArray(evaluation.evaluations) ? evaluation.evaluations : [];
+  const byName = {};
+  for (const e of evaluations) {
+    if (e && typeof e.name === 'string' && e.name && e.classification) {
+      byName[e.name] = e.classification;
+    }
+  }
+  return byName;
+}
+
+function recordBackendAcceptance({ root, kind, backend }) {
+  if (!kind || !backend) return null;
+  const absRoot = path.resolve(root || process.cwd());
+  const state = loadState();
+  const project = getOrCreateProject(state, absRoot);
+  project.backendAcceptance[kind] = { backend, at: new Date().toISOString() };
+  return stampAndSaveState(state, absRoot);
+}
+
+function loadFootprint({ root } = {}) {
+  const absRoot = path.resolve(root || process.cwd());
+  const state = loadState();
+  const project = state.projects && state.projects[absRoot];
+  const fp = project && project.footprint;
+  return fp && fp.report ? { report: fp.report, maturity: fp.maturity } : null;
+}
+
+// The gate of `materializeProjectReport`, as a NAMED TABLE rather than an inlined chain of `&&`s — and the table IS the inventory.
+const RENDERED_DATA = {
+  footprint: (p) => !!(p.footprint && p.footprint.report),
+  certifications: (p) => !!(p.certifications && Object.keys(p.certifications).length),
+};
+
+function hasRenderableData(project) {
+  if (!project) return false;
+  return Object.values(RENDERED_DATA).some((has) => has(project));
+}
+
+// Materialize (render + write) THIS project's cumulative HTML from persisted state, and return its path + file:// URL.
+function materializeProjectReport({ root, lang }) {
+  const absRoot = path.resolve(root || process.cwd());
+  const state = loadState();
+  const project = state.projects[absRoot];
+  if (!hasRenderableData(project)) return { hasData: false };
+  // issue 123 / ADR-044: the shareable HTML is gated by identity AT GENERATION TIME — this is the moment the `report` command produces the file, so this is where the gate is resolved.
+  const gate = reportGateForIdentity();
+  return { hasData: true, ...writeProjectHtml(project, absRoot, lang, gate) };
+}
+
+// `upsertFootprint` AND `upsertCertification` WERE HERE, and ADR-035 retired them.
+
+function certKey(item) {
+  if (item && item.skillId != null) return `id:${item.skillId}`;
+  const name = (item && item.skillName) || '';
+  const tech = (item && item.technology) || '';
+  return `nt:${name}::${tech}`;
+}
+
+// Upsert each certified Skill from this run into THIS PROJECT's report (keyed by Skill id within the project).
+function persistCertification({ root, items }) {
+  const absRoot = path.resolve(root || process.cwd());
+  const list = Array.isArray(items) ? items.filter((i) => i && (i.skillId != null || i.skillName)) : [];
+  const state = loadState();
+  const project = getOrCreateProject(state, absRoot);
+  const now = new Date().toISOString();
+  for (const item of list) {
+    project.certifications[certKey(item)] = { generatedAt: now, item };
+  }
+  return stampAndSaveState(state, absRoot);
+}
+
+module.exports = {
+  configDir,
+  statePath,
+  htmlPathFor,
+  projectSlug,
+  fileUrl,
+  loadState,
+  saveState,
+  renderProjectHtml,
+  persistFootprint,
+  persistCertification,
+  loadAgentClassifications,
+  loadFootprint,
+  recordBackendAcceptance,
+  materializeProjectReport,
+  certKey,
+  SCHEMA_VERSION,
+};

package/src/report-theme.js

@@ -0,0 +1,177 @@
+'use strict';
+
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (ch) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[ch]));
+}
+
+/* ---------- design tokens (Shakers "Nexia", light-only, WHITE bg) ---------- */
+
+const TOKENS_CSS = `
+  :root{
+    /* Layer 1 — brand primitives (subset used), verbatim from the DS */
+    --ds-teal-50:#e2f2f0; --ds-teal-100:#c5e5e1; --ds-teal-300:#51b1a5;
+    --ds-teal-400:#269787; --ds-teal-500:#0e7d69; --ds-teal-600:#0b5a4c;
+    --ds-teal-700:#08473c; --ds-teal-800:#05342c; --ds-teal-900:#03211c;
+    --ds-lime-200:#f5ff96; --ds-lime-500:#d8e637; --ds-lime-600:#b0bd2d;
+    --ds-zinc-50:#fafafa; --ds-zinc-100:#f4f4f5; --ds-zinc-200:#e4e4e7;
+    --ds-zinc-300:#d4d4d8; --ds-zinc-400:#a1a1aa; --ds-zinc-500:#71717a;
+    --ds-zinc-600:#52525b; --ds-zinc-700:#3f3f46; --ds-zinc-800:#27272a; --ds-zinc-900:#18181b;
+    --ds-zinc-950:#09090b; --ds-white:#ffffff;
+    /* DS status palette (design-spec/tokens.css) — used for score bands and
+       the "partial sample" warning; functional status colors, not invented. */
+    --ds-success:#059669; --ds-success-fg:#ecfdf5;
+    --ds-warning:#f59e0b; --ds-warning-fg:#fffdf5;
+    --ds-destructive:#e11d48; --ds-destructive-fg:#fef2f2;
+
+    /* Radii ("Border Radius" frame) */
+    --r-sm:6px; --r-md:8px; --r-lg:10px; --r-xl:14px; --r-full:9999px;
+    /* Shadows (shadcn upstream) */
+    --shadow-sm:0 1px 3px 0 rgb(0 0 0 / .1), 0 1px 2px -1px rgb(0 0 0 / .1);
+    --shadow-md:0 1px 3px 0 rgb(0 0 0 / .1), 0 2px 4px -1px rgb(0 0 0 / .1);
+    --shadow-lg:0 1px 3px 0 rgb(0 0 0 / .1), 0 4px 6px -1px rgb(0 0 0 / .1);
+
+    /* Inter with a system fallback (no @font-face, no network): if Inter isn't
+       installed it degrades to the DS's own fallback stack. */
+    --font-sans:"Inter",ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,
+      "Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,
+      "Apple Color Emoji","Segoe UI Emoji";
+    --font-mono:ui-monospace,"SF Mono","Cascadia Code","JetBrains Mono",Menlo,Consolas,monospace;
+
+    /* Layer 2 — semantic (light theme, the ONLY theme). Background is WHITE
+       (the DS's --color-background), priority #1. */
+    --bg:var(--ds-white);
+    --surface:var(--ds-white);
+    --fg:var(--ds-zinc-900);
+    --muted:var(--ds-zinc-700);
+    /* zinc-600 (not zinc-500) for caption/label text: clears WCAG AA on white. */
+    --faint:var(--ds-zinc-600);
+    --border:var(--ds-zinc-200);
+    --primary:var(--ds-teal-800);
+    --primary-fg:var(--ds-zinc-50);
+    --secondary:var(--ds-teal-50);
+    --secondary-fg:var(--ds-teal-600);
+    --emphasis:var(--ds-teal-500);
+    --emphasis-strong:var(--ds-teal-600);
+    --accent-lime:var(--ds-lime-500);
+    --accent-lime-fg:var(--ds-teal-800);
+    /* Model chip: an opaque lime tint over the surface, dark teal text. */
+    --model-bg:color-mix(in srgb,var(--ds-lime-500) 26%, var(--surface));
+    --model-fg:var(--ds-teal-800);
+    --off:var(--ds-zinc-300);
+    --track:var(--ds-zinc-100);
+    --ring:var(--ds-teal-500);
+    /* Score bands (certification): DS status colors. */
+    --band-high-bg:var(--ds-success); --band-high-fg:var(--ds-success-fg);
+    --band-mid-bg:var(--ds-warning); --band-mid-fg:var(--ds-warning-fg);
+    --band-low-bg:var(--ds-destructive); --band-low-fg:var(--ds-destructive-fg);
+  }
+`;
+
+/* ---------- shared base + primitives (used by every report) ---------- */
+
+const BASE_CSS = `
+  *{box-sizing:border-box}
+  html{color-scheme:light}
+  body{margin:0;background:var(--bg);color:var(--fg);
+    font-family:var(--font-sans);line-height:1.45;
+    -webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;
+    padding:40px 20px 64px;}
+  .wrap{max-width:840px;margin:0 auto;overflow-x:clip}
+  .card{background:var(--surface);border:1px solid var(--border);
+    border-radius:var(--r-lg);box-shadow:var(--shadow-sm)}
+
+  /* Header */
+  header{margin-bottom:24px}
+  .badge{display:inline-flex;align-items:center;gap:8px;
+    background:var(--secondary);color:var(--secondary-fg);
+    font-size:12px;font-weight:600;letter-spacing:.02em;
+    padding:5px 12px;border-radius:var(--r-full)}
+  .badge .spark{width:7px;height:7px;border-radius:50%;background:var(--emphasis)}
+  h1{font-size:clamp(28px,5vw,36px);font-weight:700;letter-spacing:-.02em;
+    line-height:1.15;margin:16px 0 6px}
+  .sub{color:var(--muted);font-size:16px;margin:0}
+
+  /* Section scaffolding */
+  section{margin-bottom:24px}
+  .h2{font-size:13px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;
+    color:var(--faint);margin:0 0 12px 2px}
+
+  /* Chips */
+  .chips{display:flex;flex-wrap:wrap;gap:6px}
+  .chip{font-size:11px;font-weight:500;letter-spacing:.02em;color:var(--secondary-fg);
+    background:var(--secondary);padding:3px 10px;border-radius:var(--r-full);
+    flex:none;white-space:nowrap}
+  .chip.empty{background:transparent;color:var(--faint);padding-left:0}
+
+  /* Footer */
+  footer{margin-top:28px;color:var(--faint);font-size:12.5px;line-height:1.55}
+  .priv{display:flex;gap:12px;padding:16px 18px;border-radius:var(--r-lg);
+    background:var(--secondary);color:var(--secondary-fg);margin-bottom:16px}
+  .priv .lock{flex:none;font-size:16px;line-height:1.4}
+  .meta-line{font-family:var(--font-mono);font-size:11.5px}
+  .meta-line code{color:var(--emphasis-strong);font-weight:600}
+  details{margin-top:14px}
+  details summary{cursor:pointer;color:var(--muted);font-weight:500;
+    padding:8px 0;user-select:none}
+  details summary:hover{color:var(--fg)}
+  pre{background:var(--bg);border:1px solid var(--border);border-radius:var(--r-md);
+    padding:14px;overflow:auto;font-family:var(--font-mono);font-size:11.5px;
+    color:var(--muted);max-height:300px}
+
+  a:focus-visible,summary:focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+
+  @media (prefers-reduced-motion:reduce){
+    *{animation:none!important;transition:none!important}
+  }
+`;
+
+// Generic, zero-network clipboard helper shared by every report.
+const COPY_SCRIPT = `
+  (function(){
+    function fallbackCopy(text){
+      var ta=document.createElement('textarea');ta.value=text;ta.setAttribute('readonly','');
+      ta.style.position='fixed';ta.style.opacity='0';document.body.appendChild(ta);ta.focus();ta.select();
+      try{document.execCommand('copy');}catch(e){}document.body.removeChild(ta);
+    }
+    document.querySelectorAll('[data-copy-target]').forEach(function(btn){
+      btn.addEventListener('click',function(){
+        var target=document.getElementById(btn.getAttribute('data-copy-target'));
+        if(!target)return;var text=target.textContent;
+        var showCopied=function(){
+          var original=btn.getAttribute('data-original-label')||btn.textContent;
+          btn.setAttribute('data-original-label',original);
+          btn.textContent=btn.getAttribute('data-copied-label')||original;
+          btn.classList.add('copied');
+          setTimeout(function(){btn.textContent=original;btn.classList.remove('copied');},1800);
+        };
+        if(navigator.clipboard&&navigator.clipboard.writeText){
+          navigator.clipboard.writeText(text).then(showCopied,function(){fallbackCopy(text);showCopied();});
+        }else{fallbackCopy(text);showCopied();}
+      });
+    });
+  })();
+`;
+
+// Assembles a full, self-contained HTML document from the shared theme plus a report's own component CSS, body markup, and (optional) extra script.
+function renderDocument({ lang, title, componentCss = '', body, script = '' }) {
+  const scriptTag = (COPY_SCRIPT + '\n' + script).trim();
+  return `<!DOCTYPE html>
+<html lang="${esc(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${TOKENS_CSS}${BASE_CSS}${componentCss}</style>
+</head>
+<body>
+<div class="wrap">
+${body}
+</div>
+<script>${scriptTag}</script>
+</body>
+</html>`;
+}
+
+module.exports = { esc, renderDocument, TOKENS_CSS, BASE_CSS, COPY_SCRIPT };