@birdapi/velinstyle 1.2.2 → 1.3.0

package/cli/production/extract.js

@@ -9,9 +9,45 @@ export const DEFAULT_IGNORE = [
 ];
 
 export const CONTENT_EXTS = new Set([
-  '.html', '.htm', '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.vue', '.md', '.css',
+  '.html', '.htm',
+  '.blade.php',
+  '.twig',
+  '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+  '.vue',
+  '.astro',
+  '.md', '.mdx',
+  '.css',
 ]);
 
+/** Resolve multi-dot extensions (.blade.php, .mdx) before extname. */
+export function contentExtOf(filePath) {
+  const name = String(filePath || '').toLowerCase().replace(/\\/g, '/');
+  const base = name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name;
+  if (base.endsWith('.blade.php')) return '.blade.php';
+  if (base.endsWith('.mdx')) return '.mdx';
+  return extname(base).toLowerCase();
+}
+
+export function isContentFile(filePath) {
+  return CONTENT_EXTS.has(contentExtOf(filePath));
+}
+
+/** Strip template expressions so {{ class }} / {% %} are not mistaken for tokens. */
+export function stripTemplateNoise(content, ext) {
+  let text = String(content || '');
+  if (ext === '.astro') {
+    text = text.replace(/^---[\s\S]*?---\s*/, ' ');
+  }
+  if (ext === '.blade.php' || ext === '.twig' || ext === '.vue' || ext === '.astro' || ext === '.mdx') {
+    text = text
+      .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+      .replace(/\{!![\s\S]*?!!\}/g, ' ')
+      .replace(/\{%[\s\S]*?%\}/g, ' ')
+      .replace(/@\{\{[\s\S]*?\}\}/g, ' ');
+  }
+  return text;
+}
+
 const CLASS_ATTR_RE = /class(?:Name)?\s*=\s*["'`]([^"'`]+)["'`]/gi;
 const CLASS_TOKEN_RE = /\b((?:velin|expo)-[\w:-]+)\b/g;
 const TAG_RE = /<(velin-[a-z0-9-]+)\b/gi;
@@ -21,6 +57,7 @@ const THEMES_LIST_RE = /themes\s*[:=]\s*\[([^\]]+)\]/gi;
 const ICON_NAME_RE = /(?:name|icon)\s*=\s*["']([a-z0-9][a-z0-9_-]*)["']/gi;
 const ICON_HASH_RE = /velin-icons\.svg#([a-z0-9][a-z0-9_-]*)/gi;
 const MOTION_ATTR_RE = /data-velin-(?:animate|motion|scroll)\s*=\s*["']([^"']+)["']/gi;
+const MOTION_BARE_RE = /\svelin-(?:motion|reveal|fade|slide|scale|parallax|hover|stagger|scroll|trigger|timeline|motion-sequence)(?:\s|=|>)/gi;
 const FONT_FACE_RE = /@font-face\s*\{([\s\S]*?)\}/gi;
 const FONT_WEIGHT_RE = /font-weight\s*:\s*([0-9]+|normal|bold)/gi;
 
@@ -44,7 +81,7 @@ export function walkContentFiles(dir, { ignore = DEFAULT_IGNORE, out = [], root
       continue;
     }
     if (!entry.isFile()) continue;
-    const ext = extname(entry.name).toLowerCase();
+    const ext = contentExtOf(entry.name);
     if (!CONTENT_EXTS.has(ext)) continue;
     out.push(full);
   }
@@ -57,8 +94,7 @@ export function collectContentFiles(targetPath, { ignore = DEFAULT_IGNORE, extra
   if (!existsSync(abs)) return [];
   const st = statSync(abs);
   if (st.isFile()) {
-    const ext = extname(abs).toLowerCase();
-    return CONTENT_EXTS.has(ext) ? [abs] : [];
+    return isContentFile(abs) ? [abs] : [];
   }
   return walkContentFiles(abs, { ignore: ignoreList });
 }
@@ -119,6 +155,9 @@ export function extractFromText(content, { isCss = false } = {}) {
       if (part) motion.add(part.trim());
     }
   }
+  for (const m of text.matchAll(MOTION_BARE_RE)) {
+    motion.add(m[0].trim().replace(/=.*/, '').trim() || 'velin-motion');
+  }
   for (const cls of classes) {
     if (cls.includes('animate') || cls.includes('motion') || cls.startsWith('velin-scroll-')) {
       motion.add(cls);
@@ -191,8 +230,9 @@ export function extractProject(targetPath, options = {}) {
     } catch {
       continue;
     }
-    const isCss = extname(file).toLowerCase() === '.css';
-    const part = extractFromText(body, { isCss });
+    const ext = contentExtOf(file);
+    const isCss = ext === '.css';
+    const part = extractFromText(isCss ? body : stripTemplateNoise(body, ext), { isCss });
     for (const c of part.classes) merged.classes.add(c);
     for (const t of part.tags) merged.tags.add(t);
     for (const t of part.themes) merged.themes.add(t);

package/cli/production/report.js

@@ -1,15 +1,22 @@
 /**
- * Production report — text + JSON.
+ * Production report — text + JSON with before/after breakdown.
  */
 export function buildReport(data) {
   const {
     originalBytes = 0,
     productionBytes = 0,
     breakdown = {},
+    categories = null,
     themes = [],
     icons = [],
     components = [],
     tags = [],
+    themeCountBefore = null,
+    themeCountAfter = null,
+    motionBefore = null,
+    motionAfter = null,
+    componentsBefore = null,
+    componentsAfter = null,
     imagesSkipped = true,
     filesScanned = 0,
   } = data;
@@ -17,23 +24,40 @@ export function buildReport(data) {
   const saved = Math.max(0, originalBytes - productionBytes);
   const pct = originalBytes > 0 ? Math.round((saved / originalBytes) * 100) : 0;
 
+  const rows = categories || buildCategoryRows({
+    breakdown,
+    themes,
+    icons,
+    components,
+    tags,
+    themeCountBefore,
+    themeCountAfter,
+    motionBefore,
+    motionAfter,
+    componentsBefore,
+    componentsAfter,
+    fullCss: data.fullCss,
+    fullJs: data.fullJs,
+    fullIcons: data.fullIcons,
+    cssBytes: data.cssBytes,
+    jsBytes: data.jsBytes,
+    iconBytes: data.iconBytes,
+  });
+
   const lines = [
-    'Velin Production Report',
-    `Original     ${formatKb(originalBytes)}`,
-    '↓',
-    `Production    ${formatKb(productionBytes)}`,
-    '↓',
-    `${pct} % gespart`,
+    'Production Report',
     '',
   ];
 
-  for (const [key, delta] of Object.entries(breakdown)) {
-    if (delta == null) continue;
-    const label = key.padEnd(8);
-    const sign = delta > 0 ? '-' : delta < 0 ? '+' : ' ';
-    lines.push(`${label} ${sign}${formatKb(Math.abs(delta))}`);
+  for (const row of rows) {
+    const before = row.beforeCount != null ? String(row.beforeCount) : formatKb(row.before);
+    const after = row.afterCount != null ? String(row.afterCount) : formatKb(row.after);
+    lines.push(`${String(row.label).padEnd(14)}${before.padStart(8)}  →  ${after}`);
   }
 
+  lines.push('');
+  lines.push(`${'Savings'.padEnd(14)}${pct} %`);
+
   if (imagesSkipped) {
     lines.push('');
     lines.push('Images: skipped (coming soon)');
@@ -41,18 +65,19 @@ export function buildReport(data) {
 
   lines.push('');
   lines.push(`Scanned files: ${filesScanned}`);
-  if (themes.length) lines.push(`Themes: ${themes.join(', ')}`);
+  if (themes.length) lines.push(`Themes kept: ${themes.join(', ')}`);
   if (icons.length) lines.push(`Icons (${icons.length}): ${icons.slice(0, 12).join(', ')}${icons.length > 12 ? '…' : ''}`);
   if (tags.length) lines.push(`Web Components: ${tags.join(', ')}`);
   if (components.length) lines.push(`CSS modules: ${components.length}`);
 
   return {
-    version: 1,
+    version: 2,
     originalBytes,
     productionBytes,
     savedBytes: saved,
     savedPercent: pct,
     breakdown,
+    categories: rows,
     themes,
     icons,
     tags,
@@ -63,7 +88,50 @@ export function buildReport(data) {
   };
 }
 
+function buildCategoryRows(opts) {
+  const {
+    fullCss = 0,
+    fullJs = 0,
+    fullIcons = 0,
+    cssBytes = 0,
+    jsBytes = 0,
+    iconBytes = 0,
+    themeCountBefore,
+    themeCountAfter,
+    motionBefore,
+    motionAfter,
+    componentsBefore,
+    componentsAfter,
+    breakdown = {},
+    themes = [],
+    components = [],
+    tags = [],
+  } = opts;
+
+  return [
+    { label: 'CSS', before: fullCss || (cssBytes + (breakdown.CSS || 0)), after: cssBytes },
+    { label: 'Runtime', before: fullJs || (jsBytes + (breakdown.JS || 0)), after: jsBytes },
+    { label: 'Icons', before: fullIcons || (iconBytes + (breakdown.Icons || 0)), after: iconBytes },
+    {
+      label: 'Themes',
+      beforeCount: themeCountBefore != null ? themeCountBefore : (themes.length + (breakdown.Themes ? 1 : 0)),
+      afterCount: themeCountAfter != null ? themeCountAfter : themes.length,
+    },
+    {
+      label: 'Motion',
+      beforeCount: motionBefore != null ? motionBefore : 18,
+      afterCount: motionAfter != null ? motionAfter : (breakdown.Motion ? 4 : 18),
+    },
+    {
+      label: 'Components',
+      beforeCount: componentsBefore != null ? componentsBefore : Math.max(components.length, tags.length, 43),
+      afterCount: componentsAfter != null ? componentsAfter : Math.max(tags.length, components.length ? Math.min(components.length, tags.length || components.length) : tags.length),
+    },
+  ];
+}
+
 export function formatKb(bytes) {
+  if (bytes == null || Number.isNaN(bytes)) return '—';
   return `${(bytes / 1024).toFixed(bytes >= 10240 ? 0 : 1)} KB`;
 }
 
@@ -76,3 +144,25 @@ export function measureBytes(parts) {
   }
   return total;
 }
+
+/** Map report → Experience contract widgets */
+export function reportToExperienceWidgets(report) {
+  return [
+    {
+      id: 'hero',
+      props: {
+        title: 'Production Builder',
+        subtitle: 'Build only what your project actually uses',
+        eyebrow: 'Velin Experience',
+      },
+    },
+    {
+      id: 'bundle',
+      props: {
+        title: 'Production Report',
+        rows: report.categories || [],
+        savingsPct: report.savedPercent,
+      },
+    },
+  ];
+}

package/cli/production/run.js

@@ -229,6 +229,12 @@ export async function runProduction(opts = {}) {
     const report = buildReport({
       originalBytes: original || (fullCss + fullJs + fullIcons),
       productionBytes,
+      fullCss,
+      fullJs,
+      fullIcons,
+      cssBytes,
+      jsBytes,
+      iconBytes: iconMeta.bytes || 0,
       breakdown: {
         CSS: Math.max(0, fullCss - cssBytes),
         JS: Math.max(0, fullJs - jsBytes),
@@ -238,6 +244,12 @@ export async function runProduction(opts = {}) {
         Fonts: 2 * 1024,
       },
       themes: themeMeta.selected || [],
+      themeCountBefore: listKnownThemeNames(PKG_ROOT).length,
+      themeCountAfter: (themeMeta.selected || []).length,
+      motionBefore: 18,
+      motionAfter: includeMotion ? 18 : 4,
+      componentsBefore: 43,
+      componentsAfter: Math.max(closure.tags.length, 1),
       icons: iconMeta.included || [],
       components: cssResult.included,
       tags: closure.tags,
@@ -280,7 +292,38 @@ export async function runProduction(opts = {}) {
     }
 
     console.log(C.green(`\nProduction build → ${outDir}`));
-    console.log(report.text);
+    try {
+      const { createExperienceSession, parseExperienceFlags, writeRecording, loadExperienceConfig } = await import('../experience.js');
+      const { reportToExperienceWidgets } = await import('./report.js');
+      const overrides = parseExperienceFlags(args || process.argv.slice(2), helpers || {
+        getArg: () => null,
+        hasFlag: () => false,
+      });
+      const config = loadExperienceConfig(cwd, overrides);
+      const session = createExperienceSession(config);
+      const contract = {
+        project: { outDir, filesScanned: extracted.files.length },
+        lifecycle: { stage: 'summary', stages: [] },
+        result: { status: 'PASS', message: `Saved ${report.savedPercent}%` },
+        stats: { savedPercent: report.savedPercent, productionBytes, originalBytes: report.originalBytes },
+        widgets: reportToExperienceWidgets(report),
+        suggestions: explain
+          ? [{ text: 'See explain.txt for removed CSS/themes/icons' }]
+          : [{ text: 'Add --explain for removed-asset details' }],
+        diagnostics: [],
+        notifications: [
+          { tone: 'ok', message: `Production savings ${report.savedPercent}%` },
+        ],
+        meta: { commandId: 'production', layout: 'build', durationMs: 0 },
+      };
+      console.log(session.render(contract));
+      if (config.record || overrides.record) {
+        const paths = writeRecording({ contract, events: [], config });
+        console.log(`\nRecorded → ${paths.json}`);
+      }
+    } catch {
+      console.log(report.text);
+    }
     console.log(C.dim(`\nCSS: ${cssOut}${bundled ? ' (lightningcss)' : ' (raw)'}`));
     if (jsOut) console.log(C.dim(`JS:  ${jsOut} (${closure.tags.length} components)`));
     if (!noIcons) console.log(C.dim(`Icons: ${iconMeta.included.length} / ${iconMeta.availableCount || '?'}`));

package/cli/security.js

@@ -0,0 +1,190 @@
+/**
+ * Velin Security Suite — CLI surface over Security Engine.
+ * velinstyle security doctor|scan|audit|publish|ci|deps|secrets|report
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { resolve, join } from 'path';
+import {
+  runSecurityEngine,
+  toExperiencePayload,
+  toMarkdownReport,
+  gateLabel,
+  timelineRows,
+} from '../core/security/index.js';
+
+/**
+ * @param {string[]} args
+ * @param {{ C: object, getArg: Function, hasFlag: Function, emitExperience: Function }} util
+ */
+export async function securityCmd(args, util) {
+  const { getArg, hasFlag, emitExperience } = util;
+  const sub = args[0] || 'doctor';
+  const rest = args.slice(1);
+  const target = rest.find((a) => !a.startsWith('-')) || '.';
+  const root = resolve(target);
+  const asJson = hasFlag('--json');
+  const strict = hasFlag('--strict');
+  const present = (payload) => emitExperience('security', payload);
+
+  if (sub === '--help' || sub === '-h') {
+    await present({
+      message: 'Usage: velinstyle security <doctor|scan|audit|publish|ci|deps|secrets|report> [path]',
+      suggestions: [
+        { text: 'velinstyle security doctor .' },
+        { text: 'velinstyle security deps .' },
+        { text: 'velinstyle security publish' },
+        { text: 'velinstyle security report --out ./security-report' },
+      ],
+    });
+    return;
+  }
+
+  try {
+    if (!existsSync(root)) {
+      await present({ status: 'ERROR', message: `Path not found: ${root}`, exitCode: 1 });
+      return;
+    }
+
+    const mode = resolveMode(sub, hasFlag);
+    const result = await runSecurityEngine({
+      root,
+      mode,
+      includeReleaseHealth: mode === 'publish' || mode === 'audit' || hasFlag('--publish'),
+      includeDependencyHealth: true,
+      updateTimeline: sub !== 'report' || true,
+    });
+
+    if (sub === 'report') {
+      const out = getArg('--out') || getArg('--output') || getArg('-o') || join(root, '.velin', 'security', 'report');
+      mkdirSync(out, { recursive: true });
+      writeFileSync(join(out, 'security-report.json'), `${JSON.stringify(result, null, 2)}\n`);
+      writeFileSync(join(out, 'security-report.md'), toMarkdownReport(result));
+      if (asJson) {
+        console.log(JSON.stringify({ ok: result.ok, out, score: result.securityScore }, null, 2));
+        return;
+      }
+      await present({
+        subtitle: 'report',
+        message: `Wrote security report → ${out}`,
+        items: [
+          { label: 'Score', value: String(result.securityScore) },
+          { label: 'Overall', value: result.overall },
+        ],
+        ...toExperiencePayload(result),
+      });
+      setExit(result, strict);
+      return;
+    }
+
+    if (asJson) {
+      console.log(JSON.stringify(result, null, 2));
+      setExit(result, strict);
+      return;
+    }
+
+    const exp = toExperiencePayload(result);
+    const extra = [];
+    if (result.dependencyHealth) {
+      extra.push({
+        label: 'Dep Health',
+        value: `${result.dependencyHealth.score}% (${result.dependencyHealth.deprecated} deprecated, ${result.dependencyHealth.noLockfile ?? 0} no-lockfile, ${result.dependencyHealth.outdated} outdated-heuristic, ${result.dependencyHealth.critical} critical)`,
+      });
+    }
+    if (result.releaseHealth) {
+      extra.push({ label: 'Release', value: result.releaseHealth.status });
+    }
+    const tl = timelineRows(result.timeline || { entries: {} });
+    await present({
+      subtitle: sub,
+      status: result.ok ? (result.overallGate === 'warn' ? 'WARNING' : 'PASS') : 'ERROR',
+      message: exp.message,
+      items: [...(exp.items || []), ...extra],
+      table: exp.table,
+      score: exp.score,
+      notifications: exp.notifications,
+      findings: (result.findings || []).slice(0, 25).map((f) => ({
+        severity: f.severity,
+        message: `[${f.ruleId}] ${f.message}`,
+        path: f.path,
+      })),
+      suggestions: tl.length
+        ? tl.map((r) => ({ text: `${r.title}: ${r.date}` }))
+        : [{ text: 'velinstyle security report --out ./.velin/security/report' }],
+      exitCode: exitCode(result, strict),
+    });
+  } catch (err) {
+    await present({
+      status: 'ERROR',
+      message: err?.message || String(err),
+      exitCode: 1,
+    });
+  }
+}
+
+function resolveMode(sub, hasFlag) {
+  if (hasFlag('--repo')) return 'repo';
+  if (hasFlag('--consumer')) return 'consumer';
+  if (hasFlag('--ci')) return 'ci';
+  if (hasFlag('--publish')) return 'publish';
+  if (hasFlag('--deps')) return 'deps';
+  if (hasFlag('--secrets')) return 'secrets';
+  if (sub === 'doctor') return 'doctor';
+  if (sub === 'scan') return 'scan';
+  if (sub === 'audit') return 'audit';
+  if (sub === 'publish') return 'publish';
+  if (sub === 'ci') return 'ci';
+  if (sub === 'deps') return 'deps';
+  if (sub === 'secrets') return 'secrets';
+  if (sub === 'report') return 'audit';
+  return 'doctor';
+}
+
+function exitCode(result, strict) {
+  if (result.overallGate === 'fail') return 1;
+  if (strict && result.overallGate === 'warn') return 1;
+  return 0;
+}
+
+function setExit(result, strict) {
+  const code = exitCode(result, strict);
+  if (code) process.exitCode = code;
+}
+
+/**
+ * Check-pipeline step (used by `velinstyle check`).
+ * @param {string} path
+ * @param {{ quiet?: boolean, C?: object, strict?: boolean }} [opts]
+ */
+export async function securityCheckStep(path, { quiet, C, strict } = {}) {
+  try {
+    const root = resolve(path);
+    if (!existsSync(root)) return { ok: true, skipped: true };
+
+    const result = await runSecurityEngine({
+      root,
+      mode: 'doctor',
+      includeReleaseHealth: false,
+      includeDependencyHealth: true,
+      updateTimeline: true,
+    });
+
+    const fail = result.overallGate === 'fail' || (strict && result.overallGate === 'warn');
+    if (!quiet && C) {
+      const score = result.securityScore != null ? `${result.securityScore}%` : '—';
+      const gate = result.overallGate || '—';
+      const line = `  security: ${score} · ${gate} · ${result.overall || ''}`;
+      console.log(fail ? C.red(line) : result.overallGate === 'warn' ? C.yellow(line) : C.green(line));
+    }
+
+    return {
+      ok: !fail,
+      skipped: false,
+      securityScore: result.securityScore,
+      overall: result.overall,
+      overallGate: result.overallGate,
+      findings: result.findings?.length || 0,
+    };
+  } catch {
+    return { ok: true, skipped: true };
+  }
+}

package/cli/skills.js

@@ -28,7 +28,11 @@ export function loadSkillRegistry() {
   return loadRegistry(REGISTRY_PATH);
 }
 
-export function skillsList(argv = []) {
+/**
+ * @param {string[]} argv
+ * @param {{ silent?: boolean }} [opts]
+ */
+export function skillsList(argv = [], opts = {}) {
   const registry = loadSkillRegistry();
   const items = listSkills(registry, {
     capability: argValue(argv, '--capability') || undefined,
@@ -37,14 +41,16 @@ export function skillsList(argv = []) {
     origin: argValue(argv, '--origin') || undefined,
     category: argValue(argv, '--category') || undefined,
   });
+  if (opts.silent) return items;
   if (hasFlag(argv, '--json')) {
     console.log(JSON.stringify(items, null, 2));
-    return;
+    return items;
   }
   for (const item of items) {
     console.log(`${item.id}  [${item.category}]  ${item.priority}/${item.status}  capabilities=${(item.capabilities || []).join(',')}`);
   }
   console.log(`\n${items.length} skill(s)`);
+  return items;
 }
 
 export function skillsShow(skillId, argv = []) {
@@ -56,9 +62,10 @@ export function skillsShow(skillId, argv = []) {
   }
   if (hasFlag(argv, '--human')) {
     console.log(formatSkillHuman(skill));
-    return;
+    return skill;
   }
   console.log(JSON.stringify(skill, null, 2));
+  return skill;
 }
 
 function formatSkillHuman(skill) {
@@ -103,9 +110,14 @@ function formatSkillHuman(skill) {
   return lines.filter(Boolean).join('\n');
 }
 
-export function skillsInstall(argv = []) {
+/**
+ * @param {string[]} argv
+ * @param {{ silent?: boolean }} [opts]
+ */
+export function skillsInstall(argv = [], opts = {}) {
   const selection = argv[0];
   if (!selection) {
+    if (opts.silent) return null;
     console.error('Usage: velinstyle skills install <skill-id|pack|bundle:id|project:id>');
     process.exit(1);
   }
@@ -118,18 +130,30 @@ export function skillsInstall(argv = []) {
     targetRoot: target,
     includeDependencies: !hasFlag(argv, '--no-deps'),
   });
+  if (opts.silent) {
+    const markerPath = join(target, 'registry-source.json');
+    writeFileSync(markerPath, JSON.stringify({ source: REGISTRY_PATH, installed: result.installed }, null, 2), 'utf-8');
+    return result;
+  }
   for (const installed of result.installed) console.log(`Installed ${installed}`);
   if (result.issues.length) {
     for (const issue of result.issues) console.warn(`Warning: ${issue}`);
   }
   const markerPath = join(target, 'registry-source.json');
   writeFileSync(markerPath, JSON.stringify({ source: REGISTRY_PATH, installed: result.installed }, null, 2), 'utf-8');
+  return result;
 }
 
-export function skillsRun(skillId, argv = []) {
+/**
+ * @param {string} skillId
+ * @param {string[]} argv
+ * @param {{ silent?: boolean }} [opts]
+ */
+export function skillsRun(skillId, argv = [], opts = {}) {
   const registry = loadSkillRegistry();
   const resolved = resolveSkillGraph(registry, skillId);
   if (resolved.issues.length) {
+    if (opts.silent) return { ok: false, issues: resolved.issues, steps: [] };
     for (const issue of resolved.issues) console.error(issue);
     process.exit(1);
   }
@@ -139,20 +163,27 @@ export function skillsRun(skillId, argv = []) {
     if (!skill) continue;
     steps.push({ id: skill.id, requiresCli: skill.requiresCli || [], onlyIf: skill.onlyIf || [] });
   }
+  const payload = { steps };
+  if (opts.silent) return payload;
   if (hasFlag(argv, '--json')) {
-    console.log(JSON.stringify({ steps }, null, 2));
-    return;
+    console.log(JSON.stringify(payload, null, 2));
+    return payload;
   }
   for (const step of steps) {
     console.log(`- ${step.id}`);
     if (step.requiresCli.length) console.log(`  cli: ${step.requiresCli.join(', ')}`);
     if (step.onlyIf.length) console.log(`  onlyIf: ${step.onlyIf.join(', ')}`);
   }
+  return payload;
 }
 
-export function skillsValidate() {
+/**
+ * @param {{ silent?: boolean }} [opts]
+ */
+export function skillsValidate(opts = {}) {
   const registry = loadSkillRegistry();
   const result = validateRegistry(registry);
+  if (opts.silent) return result;
   if (result.errors.length) {
     for (const error of result.errors) console.error(`Error: ${error}`);
   }
@@ -163,9 +194,14 @@ export function skillsValidate() {
   process.exit(result.ok ? 0 : 1);
 }
 
-export async function skillsDoctor(argv = []) {
+/**
+ * @param {string[]} argv
+ * @param {{ silent?: boolean }} [opts]
+ */
+export async function skillsDoctor(argv = [], opts = {}) {
   const { doctorSkillPaths } = await import('../scripts/check-skills-paths.mjs');
   const result = doctorSkillPaths(PKG_ROOT);
+  if (opts.silent) return result;
   if (hasFlag(argv, '--json')) {
     console.log(JSON.stringify(result, null, 2));
     process.exit(result.ok ? 0 : 1);
@@ -176,9 +212,14 @@ export async function skillsDoctor(argv = []) {
     process.exit(1);
   }
   console.log(`skills doctor OK (${result.checked} paths).`);
+  return result;
 }
 
-export function skillsIndex(kind) {
+/**
+ * @param {string} kind
+ * @param {{ silent?: boolean }} [opts]
+ */
+export function skillsIndex(kind, opts = {}) {
   const registry = loadSkillRegistry();
   const map = {
     packs: registry.packs || [],
@@ -188,7 +229,9 @@ export function skillsIndex(kind) {
     graphs: registry.workflowGraphs || [],
   };
   const out = map[kind] || [];
+  if (opts.silent) return out;
   console.log(JSON.stringify(out, null, 2));
+  return out;
 }
 
 export function skillsCommand(argv = []) {