shakers-cli 0.0.0-stage → 0.14.1

package/src/share-card.js

@@ -0,0 +1,362 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { getCatalog } = require('./i18n');
+const { setupLevelForTier } = require('./tier-engine');
+const { renderDocument } = require('./report-theme');
+const { loadState, configDir, projectSlug, fileUrl } = require('./report-store');
+const { WORDMARK_VIEWBOX, WORDMARK_PATHS } = require('./shakers-wordmark');
+
+// LinkedIn shares render best at 1.91:1 (1200×627). Fixed so the browser-side
+// canvas export writes exactly these pixels.
+const CARD_W = 1200;
+const CARD_H = 627;
+
+// Brand palette (from shakers-design-system/design-spec/tokens.css).
+const BRAND = {
+  lime: '#d8e637',      // hero accent (tier, score arc, stat numbers)
+  dark: '#181B1A',      // card background
+  white: '#ffffff',
+  zinc300: '#d4d4d8',   // stat labels / technology names (light, secondary)
+  zinc400: '#a1a1aa',   // "/ 100", muted labels
+  zinc500: '#71717a',   // shakersworks.com, separators
+  teal500: '#0e7d69',   // teal-500 — accent stripe + eyebrow
+  teal700: '#08473c',   // teal-700 — band pill + score-ring track
+};
+
+// Font stack shared with the reports (Inter -> system fallback).
+const FONT_STACK =
+  "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
+
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (ch) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[ch]));
+}
+
+function loadProjectFootprint(root, { load = loadState } = {}) {
+  const absRoot = path.resolve(root || process.cwd());
+  let state;
+  try {
+    state = load();
+  } catch {
+    return null;
+  }
+  const project = state && state.projects && state.projects[absRoot];
+  const fp = project && project.footprint;
+  const m = fp && fp.maturity;
+  if (!m || m.tierKey == null || typeof m.score !== 'number') return null;
+
+  // Derived signals from the persisted report (defensive: any missing piece
+  // reads as 0 / empty — an older stored report never crashes the card).
+  const report = (fp && fp.report) || {};
+  const counts = report.agentCounts || {};
+  const toolsDetected = Array.isArray(report.tools)
+    ? report.tools.filter((tl) => tl && tl.detected).length
+    : 0;
+  const mcpTotal = report.mcp && typeof report.mcp.total === 'number'
+    ? report.mcp.total
+    : (typeof counts.mcpServers === 'number' ? counts.mcpServers : 0);
+  const technologies = Array.isArray(report.technologies)
+    ? report.technologies.filter((s) => typeof s === 'string' && s.trim())
+    : [];
+
+  return {
+    root: absRoot,
+    tier: m.tier,
+    tierKey: m.tierKey,
+    score: m.score,
+    level: m.level,
+    levelKey: m.key,
+    // ADR-016: Setup Level for the card pill (replaces the 0-4 band). Prefer the
+    // persisted `setupLevel`; derive from the tier for older stored reports.
+    setupLevelKey: (m.setupLevel && m.setupLevel.key)
+      || (typeof m.tier === 'number' ? setupLevelForTier(m.tier).key : 'none'),
+    generatedAt: fp.generatedAt || null,
+    signals: {
+      toolsDetected,
+      mcpServers: mcpTotal,
+      agents: typeof counts.agents === 'number' ? counts.agents : 0,
+      skills: typeof counts.skills === 'number' ? counts.skills : 0,
+      commands: typeof counts.commands === 'number' ? counts.commands : 0,
+      hooks: typeof counts.hooks === 'number' ? counts.hooks : 0,
+      technologies,
+    },
+  };
+}
+
+// How many top technologies to name on the card (kept small — social card).
+const MAX_TECHNOLOGIES = 4;
+
+// Maps the raw footprint into the card's display model.
+function buildCardModel(fp) {
+  const en = getCatalog('en');
+  const tierKey = fp.tierKey;
+  const tierName = (en.tierNames && en.tierNames[tierKey]) || tierKey;
+  // ADR-016: Setup Level label for the pill (English-fixed like the tier name).
+  const setupKey = fp.setupLevelKey || 'none';
+  const bandName = (en.setupLevels && en.setupLevels[setupKey] && en.setupLevels[setupKey].label) || '';
+
+  const s = fp.signals || {};
+  const n = (v) => (typeof v === 'number' && isFinite(v) ? v : 0);
+  // Only stats with a value > 0 make the card — never a "0 skills" filler.
+  // Order is the reading order the label list implies (tools -> hooks).
+  const stats = [
+    { value: n(s.toolsDetected), label: 'AI tools' },
+    { value: n(s.mcpServers), label: 'MCP' },
+    { value: n(s.agents), label: 'agents' },
+    { value: n(s.skills), label: 'skills' },
+    { value: n(s.commands), label: 'commands' },
+    { value: n(s.hooks), label: 'hooks' },
+  ].filter((st) => st.value > 0);
+  const technologies = Array.isArray(s.technologies) ? s.technologies.slice(0, MAX_TECHNOLOGIES) : [];
+
+  return {
+    tierKey,
+    tierName,
+    bandName,
+    score: Math.max(0, Math.min(100, Math.round(fp.score))),
+    stats,
+    technologies,
+  };
+}
+
+// Suggested LinkedIn caption, built deterministically from the model. English.
+function buildSuggestedText(model) {
+  return (
+    `I just measured my AI tooling maturity with the Shakers AI Usage Evaluator: `
+    + `tier ${model.tierKey} (${model.tierName}), scoring ${model.score}/100. `
+    + `How do you work with AI? Measure yours at shakersworks.com `
+    + `#AI #DeveloperExperience #AITooling #Shakers`
+  );
+}
+
+// Builds the branded card as a SELF-CONTAINED SVG (1200×627).
+function renderCardSvg(model, { id = 'share-card-svg' } = {}) {
+  const { tierKey, tierName, bandName, score, stats, technologies } = model;
+
+  // Logo: the REAL hand-drawn "shakers" wordmark (87×18 asset), ~44px tall, top-left, in white.
+  const wordmarkScale = 44 / WORDMARK_VIEWBOX.h; // ≈ 2.44
+  const wordmark = WORDMARK_PATHS
+    .map((d) => `<path d="${d}" fill="${BRAND.white}"/>`)
+    .join('');
+
+  // Score donut ring (right). Deterministic geometry from the score.
+  const cx = 980;
+  const cy = 262;
+  const r = 118;
+  const circ = 2 * Math.PI * r;
+  const dashOffset = (circ * (1 - score / 100)).toFixed(2);
+
+  // Stats: a single LIGHT line — only signals with a value > 0 (buildCardModel
+  // already filtered zeros out). Number in lime, label muted, " · " separators.
+  const SEP = `<tspan fill="${BRAND.zinc500}">   ·   </tspan>`;
+  const statsInline = (Array.isArray(stats) ? stats : [])
+    .map((st) => `<tspan font-weight="800" fill="${BRAND.lime}">${esc(st.value)}</tspan><tspan fill="${BRAND.zinc300}"> ${esc(st.label)}</tspan>`)
+    .join(SEP);
+  const statsLine = stats && stats.length
+    ? `<text x="82" y="500" font-size="27" fill="${BRAND.zinc300}">${statsInline}</text>`
+    : '';
+
+  // Technologies: one muted line ("Top: A · B · C"), only when present.
+  const techLine = Array.isArray(technologies) && technologies.length
+    ? `<text x="82" y="546" font-size="22" fill="${BRAND.zinc400}">Top: <tspan fill="${BRAND.white}">${esc(technologies.join(' · '))}</tspan></text>`
+    : '';
+
+  // Band pill (teal, secondary) with a lime status dot before the band name.
+  const pillWidth = Math.max(150, 58 + bandName.length * 12);
+
+  return `<svg id="${id}" width="${CARD_W}" height="${CARD_H}" viewBox="0 0 ${CARD_W} ${CARD_H}"`
+    + ` xmlns="http://www.w3.org/2000/svg" font-family="${esc(FONT_STACK)}">
+  <rect width="${CARD_W}" height="${CARD_H}" fill="${BRAND.dark}"/>
+  <rect x="0" y="0" width="12" height="${CARD_H}" fill="${BRAND.teal500}"/>
+
+  <!-- logo: real hand-drawn shakers wordmark (inline vector paths, self-contained) -->
+  <g transform="translate(80,56) scale(${wordmarkScale.toFixed(4)})">${wordmark}</g>
+  <text x="1160" y="92" text-anchor="end" font-size="19" fill="${BRAND.zinc500}">shakersworks.com</text>
+
+  <!-- eyebrow (teal, letterspaced) -->
+  <text x="82" y="176" font-size="25" letter-spacing="4" font-weight="700" fill="${BRAND.teal500}">AI TOOLING MATURITY</text>
+
+  <!-- tier (hero, lime) + tier name -->
+  <text x="76" y="330" font-size="150" font-weight="800" fill="${BRAND.lime}">${esc(tierKey)}</text>
+  <text x="82" y="392" font-size="40" font-weight="700" fill="${BRAND.white}">${esc(tierName)}</text>
+
+  <!-- maturity band pill (teal, secondary) with a lime status dot -->
+  <g transform="translate(82,414)">
+    <rect x="0" y="0" rx="15" ry="15" width="${pillWidth}" height="40" fill="${BRAND.teal700}"/>
+    <circle cx="24" cy="20" r="6" fill="${BRAND.lime}"/>
+    <text x="42" y="27" font-size="19" font-weight="700" fill="${BRAND.white}">${esc(bandName)}</text>
+  </g>
+
+  <!-- score donut (hero, lime arc on a teal track) -->
+  <g transform="translate(${cx},${cy})">
+    <circle r="${r}" fill="none" stroke="${BRAND.teal700}" stroke-width="22"/>
+    <circle r="${r}" fill="none" stroke="${BRAND.lime}" stroke-width="22" stroke-linecap="round"
+      stroke-dasharray="${circ.toFixed(2)}" stroke-dashoffset="${dashOffset}" transform="rotate(-90)"/>
+    <text text-anchor="middle" y="14" font-size="86" font-weight="800" fill="${BRAND.white}">${score}</text>
+    <text text-anchor="middle" y="56" font-size="24" letter-spacing="2" fill="${BRAND.zinc400}">/ 100</text>
+  </g>
+
+  <!-- light stats line + technologies (no panel, no footer; bottom edge breathes) -->
+  ${statsLine}
+  ${techLine}
+</svg>`;
+}
+
+// Component CSS for the HTML wrapper (the page around the card). Reuses the
+// report theme tokens (var(--...)) from report-theme.js's renderDocument.
+const SHARE_CSS = `
+  .card-frame{margin:8px 0 22px}
+  .card-svg-wrap{max-width:760px;border-radius:var(--r-xl);overflow:hidden;
+    box-shadow:var(--shadow-lg);border:1px solid var(--border);background:#181B1A}
+  .card-svg-wrap svg{display:block;width:100%;height:auto}
+  .actions{display:flex;flex-wrap:wrap;gap:12px;margin:0 0 18px}
+  .btn{display:inline-flex;align-items:center;gap:8px;font:inherit;font-size:15px;
+    font-weight:600;padding:11px 20px;border-radius:var(--r-md);border:1px solid transparent;
+    cursor:pointer;text-decoration:none;line-height:1}
+  .btn-primary{background:var(--primary);color:var(--primary-fg)}
+  .btn-primary:hover{background:var(--emphasis-strong)}
+  .btn-secondary{background:var(--accent-lime);color:var(--accent-lime-fg)}
+  .btn-secondary:hover{filter:brightness(.96)}
+  .flow-note{display:flex;gap:12px;padding:16px 18px;border-radius:var(--r-lg);
+    background:var(--secondary);color:var(--secondary-fg);margin:0 0 22px;font-size:14px;line-height:1.55}
+  .flow-note ol{margin:6px 0 0;padding-left:20px}
+  .flow-note li{margin:2px 0}
+  .suggested{margin:0 0 8px}
+  .sug-head{display:flex;align-items:center;justify-content:space-between;margin:0 0 8px}
+  .sug-head span{font-size:13px;font-weight:600;letter-spacing:.04em;text-transform:uppercase;color:var(--faint)}
+  .copy{font:inherit;font-size:12.5px;font-weight:600;padding:6px 12px;border-radius:var(--r-sm);
+    border:1px solid var(--border);background:var(--surface);color:var(--muted);cursor:pointer}
+  .copy.copied{background:var(--secondary);color:var(--secondary-fg);border-color:var(--secondary)}
+  #li-text{margin:0;padding:16px 18px;border:1px solid var(--border);border-radius:var(--r-md);
+    background:var(--track);color:var(--fg);font-size:14.5px;line-height:1.6}
+`;
+
+// Browser-side PNG export + LinkedIn share wiring.
+const SHARE_SCRIPT = `
+  (function(){
+    var CARD_W=${CARD_W}, CARD_H=${CARD_H};
+    var svg=document.getElementById('share-card-svg');
+    var dl=document.getElementById('dl-png');
+    var li=document.getElementById('li-share');
+    var liText=document.getElementById('li-text');
+    if(li){
+      var text=liText?liText.textContent:'';
+      li.setAttribute('href','https://www.linkedin.com/feed/?shareActive=true&text='+encodeURIComponent(text));
+    }
+    if(dl&&svg){
+      dl.addEventListener('click',function(){
+        // Serialize the inline SVG and load it as an image. encodeURIComponent
+        // (not btoa) so any non-ASCII survives; charset is declared for safety.
+        var xml=new XMLSerializer().serializeToString(svg);
+        var src='data:image/svg+xml;charset=utf-8,'+encodeURIComponent(xml);
+        var img=new Image();
+        img.onload=function(){
+          var canvas=document.createElement('canvas');
+          canvas.width=CARD_W; canvas.height=CARD_H;
+          var ctx=canvas.getContext('2d');
+          ctx.fillStyle='#181B1A'; ctx.fillRect(0,0,CARD_W,CARD_H);
+          ctx.drawImage(img,0,0,CARD_W,CARD_H);
+          var png;
+          try{ png=canvas.toDataURL('image/png'); }
+          catch(e){ /* self-contained SVG shouldn't taint; bail quietly if it did */ return; }
+          var a=document.createElement('a');
+          a.href=png; a.download='shakers-ai-maturity.png';
+          document.body.appendChild(a); a.click(); a.remove();
+        };
+        img.onerror=function(){};
+        img.src=src;
+      });
+    }
+  })();
+`;
+
+// Assembles the full, self-contained HTML page around the card, using the shared Shakers report theme (report-theme.js#renderDocument).
+function renderShareCardHtml(model) {
+  const svg = renderCardSvg(model);
+  const suggested = buildSuggestedText(model);
+
+  const body = `<header>
+    <span class="badge"><span class="spark"></span>SHAKERS</span>
+    <h1>Share your AI maturity</h1>
+    <p class="sub">A branded card to post on LinkedIn.</p>
+  </header>
+
+  <div class="card-frame">
+    <div class="card-svg-wrap">${svg}</div>
+  </div>
+
+  <div class="actions">
+    <button type="button" id="dl-png" class="btn btn-primary">Download PNG</button>
+    <a id="li-share" class="btn btn-secondary" href="https://www.linkedin.com/feed/?shareActive=true" target="_blank" rel="noopener">Share on LinkedIn</a>
+  </div>
+
+  <div class="flow-note">
+    <span aria-hidden="true">💡</span>
+    <div>
+      <strong>LinkedIn can't attach an image from a URL.</strong> To post the card:
+      <ol>
+        <li>Click <strong>Download PNG</strong> to save the image.</li>
+        <li>Click <strong>Share on LinkedIn</strong> to open the composer (with the suggested text).</li>
+        <li>Attach the downloaded PNG to your post.</li>
+      </ol>
+    </div>
+  </div>
+
+  <section class="suggested">
+    <div class="sug-head">
+      <span>Suggested text</span>
+      <button type="button" class="copy" data-copy-target="li-text" data-copied-label="Copied ✓">Copy</button>
+    </div>
+    <p id="li-text">${esc(suggested)}</p>
+  </section>
+
+  <footer>
+    <div class="priv">
+      <span class="lock" aria-hidden="true">🔒</span>
+      <span>Generated locally on your machine. The card and the PNG are built entirely in your browser — nothing is uploaded.</span>
+    </div>
+  </footer>`;
+
+  return renderDocument({
+    lang: 'en',
+    title: 'Shakers — Share your AI maturity',
+    componentCss: SHARE_CSS,
+    body,
+    script: SHARE_SCRIPT,
+  });
+}
+
+// Per-project card file, alongside the reports in ~/.config/ai-footprint/ (override via SHAKERS_CLI_CONFIG_DIR).
+function cardPathFor(absRoot) {
+  return path.join(configDir(), `share-${projectSlug(path.resolve(absRoot))}.html`);
+}
+
+// Orchestrates the command: load the project's footprint, and either return a "no footprint" signal or render + write the card and return its file:// link.
+function generateShareCard({ root, load } = {}) {
+  const absRoot = path.resolve(root || process.cwd());
+  const fp = loadProjectFootprint(absRoot, load ? { load } : {});
+  if (!fp) return { ok: false, reason: 'no-footprint', root: absRoot };
+
+  const model = buildCardModel(fp);
+  const html = renderShareCardHtml(model);
+  fs.mkdirSync(configDir(), { recursive: true });
+  const htmlPath = cardPathFor(absRoot);
+  fs.writeFileSync(htmlPath, html);
+  return { ok: true, root: absRoot, model, html, htmlPath, fileUrl: fileUrl(htmlPath) };
+}
+
+module.exports = {
+  CARD_W,
+  CARD_H,
+  loadProjectFootprint,
+  buildCardModel,
+  buildSuggestedText,
+  renderCardSvg,
+  renderShareCardHtml,
+  cardPathFor,
+  generateShareCard,
+};

package/src/share-certification.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// Certification-persistence payload (skill-code-certification, issue 005), extracted from src/share.js (structure refactor, issue 020).
+
+const { scrubSecrets } = require('./agent-synthesis');
+
+const CERTIFY_SEND_THROTTLE_MS = 60 * 60 * 1000;
+const CERT_SCHEMA_VERSION = 1;
+
+// Strict whitelist: the analyzed RESULT + observability provenance (ADR-017), rebuilt field-by-field (never spread).
+const CERT_DIMENSION_KEYS = ['idiomatic', 'correctness', 'depth', 'structure', 'testing'];
+function deriveDimensionScores(dimensions) {
+  if (!dimensions || typeof dimensions !== 'object') return null;
+  const out = {};
+  let any = false;
+  for (const key of CERT_DIMENSION_KEYS) {
+    const v = dimensions[key];
+    if (typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 4) {
+      out[key] = v;
+      any = true;
+    } else {
+      out[key] = null;
+    }
+  }
+  return any ? out : null;
+}
+
+const MAX_INTERVIEW_EVIDENCE_TOKEN_CHARS = 4096;
+function interviewEvidenceTokenOf(item) {
+  const t = item && item.interviewEvidenceToken;
+  return typeof t === 'string' && t ? t.slice(0, MAX_INTERVIEW_EVIDENCE_TOKEN_CHARS) : null;
+}
+
+const MAX_CERTIFY_EVIDENCE_TOKEN_CHARS = 4096;
+function certifyEvidenceTokenOf(item) {
+  const t = item && item.result && item.result.evidenceToken;
+  return typeof t === 'string' && t ? t.slice(0, MAX_CERTIFY_EVIDENCE_TOKEN_CHARS) : null;
+}
+
+function deriveCertificationPayload(items, { repository = null, commitRange = null, toolVersion = null } = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const skillCodeAssessments = list
+    .filter((i) => i && i.result && typeof i.result === 'object')
+    .map((i) => {
+      const assessment = {
+      skillId: i.skillId != null ? i.skillId : null,
+      skillName: typeof i.skillName === 'string' ? i.skillName : null,
+      technology: typeof i.technology === 'string' ? i.technology : null,
+      score: typeof i.result.score === 'number' ? i.result.score : null,
+      rationale: scrubSecrets(typeof i.result.rationale === 'string' ? i.result.rationale : ''),
+      improvements: Array.isArray(i.result.improvements)
+        ? i.result.improvements.filter((x) => typeof x === 'string' && x).map((x) => scrubSecrets(x))
+        : [],
+      sampled: !!(i.sampling && i.sampling.sampleable),
+      model: typeof i.result.model === 'string' && i.result.model ? i.result.model : null,
+      // Paths only (never content). The attribution gate already filtered
+      // these to the Talent's own files (bin/certify.js).
+      sampledFiles: Array.isArray(i.sampledFiles)
+        ? i.sampledFiles.filter((p) => typeof p === 'string' && p)
+        : [],
+      // Verified-authorship evidence: every considered author-email + match flag.
+      authorEmails: Array.isArray(i.authorEmails)
+        ? i.authorEmails
+            .filter((a) => a && typeof a.email === 'string' && a.email)
+            .map((a) => ({ email: a.email, matched: !!a.matched }))
+        : [],
+      // Model's per-file scores; `[]` when the model degraded to aggregate-only.
+      perFileBreakdown: Array.isArray(i.result.perFileBreakdown)
+        ? i.result.perFileBreakdown
+            .filter((f) => f && typeof f.path === 'string' && typeof f.score === 'number')
+            .map((f) => ({
+              path: f.path,
+              score: f.score,
+              note: typeof f.note === 'string' && f.note ? scrubSecrets(f.note) : null,
+            }))
+        : [],
+      // ADR-024 rubric dimensions (0-4 or null) — the inputs the server used to
+      // compute the deterministic score. Rebuilt key-by-key, never spread.
+      dimensionScores: deriveDimensionScores(i.result.dimensions),
+      };
+      const certifyToken = certifyEvidenceTokenOf(i);
+      if (certifyToken) assessment.evidenceToken = certifyToken;
+      // ADR-049 / issue 128: the attested combined level, bound ONLY when an
+      // interview ran. Added conditionally so an item without one is byte-identical.
+      const token = interviewEvidenceTokenOf(i);
+      if (token) assessment.interviewEvidenceToken = token;
+      return assessment;
+    });
+  return {
+    schemaVersion: CERT_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    kind: 'skill-code-assessment',
+    skillCodeAssessments,
+    toolVersion: typeof toolVersion === 'string' && toolVersion ? toolVersion : null,
+    repository: typeof repository === 'string' && repository ? repository : null,
+    commitRange: typeof commitRange === 'string' && commitRange ? commitRange : null,
+  };
+}
+
+function isCertifyThrottled(state, now = Date.now()) {
+  if (!state || !state.lastCertifySentAt) return false;
+  const last = new Date(state.lastCertifySentAt).getTime();
+  if (Number.isNaN(last)) return false;
+  return now - last < CERTIFY_SEND_THROTTLE_MS;
+}
+
+module.exports = {
+  deriveCertificationPayload,
+  isCertifyThrottled,
+  CERTIFY_SEND_THROTTLE_MS,
+};

package/src/share-consent-state.js

@@ -0,0 +1,157 @@
+'use strict';
+
+// Consent state + email identity + client-side throttle, extracted from src/share.js (structure refactor, issue 020).
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+function configDir() {
+  return getConfigDir(process.env);
+}
+
+function consentPath() {
+  return path.join(configDir(), 'consent.json');
+}
+
+// Client-side throttle: don't retry a submission if the last one was less than 1h ago.
+const SEND_THROTTLE_MS = 60 * 60 * 1000;
+
+// consent state (~/.config/ai-footprint/consent.json) Replaces the old `credentials.json` (token model).
+
+function loadConsentState() {
+  try {
+    return JSON.parse(fs.readFileSync(consentPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveConsentState(state) {
+  fs.mkdirSync(configDir(), { recursive: true });
+  fs.writeFileSync(consentPath(), JSON.stringify(state, null, 2));
+  try { fs.chmodSync(consentPath(), 0o600); } catch { /* e.g. Windows */ }
+}
+
+// Returns 'granted' | 'denied' | null ("no decision persisted yet").
+function getConsentDecision(state) {
+  if (!state || state.consent === undefined || state.consent === null) return null;
+  return state.consent;
+}
+
+function hasTraceContentConsent() {
+  return getConsentDecision(loadConsentState()) === 'granted';
+}
+
+/* ---------- email ---------- */
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Basic format validation only (specs.md: "validación de formato básica").
+function isValidEmail(value) {
+  return typeof value === 'string' && EMAIL_RE.test(value.trim());
+}
+
+// Same normalization the backend applies (specs.md Data model): trim +
+// lowercase, so client and server agree on what "the same email" means.
+function normalizeEmail(value) {
+  return String(value).trim().toLowerCase();
+}
+
+// Persists a consent decision.
+function recordConsent(decision, email = null, { verified } = {}) {
+  if (decision !== 'granted' && decision !== 'denied') {
+    throw new Error(`Decisión de consentimiento no válida: ${decision}`);
+  }
+  if (decision === 'granted' && !isValidEmail(email)) {
+    throw new Error('No se puede conceder consentimiento sin un correo válido.');
+  }
+  const state = loadConsentState() || {};
+  state.consent = decision;
+  if (email !== null) state.email = normalizeEmail(email);
+  if (state.lastSentAt === undefined) state.lastSentAt = null;
+  // Email-ownership verification flag (skill-code-certification / ADR-006).
+  if (decision === 'granted' && verified !== undefined) {
+    state.emailVerified = verified === true;
+  }
+  saveConsentState(state);
+  return state;
+}
+
+// consent management (issue 007: status / revoke / change email) One-shot actions (do not scan), same pattern the retired `--enroll` used.
+
+// Read-only snapshot for `--consent-status`. Never throws.
+function getConsentStatus() {
+  const state = loadConsentState();
+  return {
+    consent: getConsentDecision(state),
+    email: state && state.email ? state.email : null,
+    emailVerified: state ? state.emailVerified !== false : false,
+    lastSentAt: state && state.lastSentAt ? state.lastSentAt : null,
+  };
+}
+
+// Revokes consent unconditionally (works even with no prior decision, or after a prior `denied` — idempotent): from this point on `autoShare` skips with `consent-denied`.
+function revokeConsent() {
+  const state = recordConsent('denied');
+  return { ok: true, state };
+}
+
+function resetConsent() {
+  const state = loadConsentState() || {};
+  delete state.consent;
+  // A re-grant is "concede de cero" (ADR-006): drop the verification flag so the OTP runs again from scratch and nothing is sent under the old email until it's re-verified.
+  delete state.emailVerified;
+  if (state.lastSentAt === undefined) state.lastSentAt = null;
+  saveConsentState(state);
+  return { ok: true, state };
+}
+
+function clearConsentState() {
+  try {
+    fs.rmSync(consentPath(), { force: true });
+  } catch { /* no-op */ }
+  return { ok: true };
+}
+
+// Changes the persisted email WITHOUT touching the consent decision (specs.md: "sin tocar la decisión de consentimiento").
+function setEmail(newEmail) {
+  if (!isValidEmail(newEmail)) {
+    return { ok: false, reason: 'invalid-email' };
+  }
+  const state = loadConsentState() || {};
+  state.email = normalizeEmail(newEmail);
+  // A new email is unverified until proven (ADR-006): reset the flag so
+  // autoShare won't send under an address whose ownership wasn't checked.
+  state.emailVerified = false;
+  saveConsentState(state);
+  return { ok: true, state };
+}
+
+/* ---------- client-side throttle ---------- */
+
+function isThrottled(state, now = Date.now()) {
+  if (!state || !state.lastSentAt) return false;
+  const last = new Date(state.lastSentAt).getTime();
+  if (Number.isNaN(last)) return false;
+  return now - last < SEND_THROTTLE_MS;
+}
+
+module.exports = {
+  configDir,
+  consentPath,
+  SEND_THROTTLE_MS,
+  loadConsentState,
+  saveConsentState,
+  getConsentDecision,
+  hasTraceContentConsent,
+  isValidEmail,
+  normalizeEmail,
+  recordConsent,
+  getConsentStatus,
+  revokeConsent,
+  resetConsent,
+  clearConsentState,
+  setEmail,
+  isThrottled,
+};