@birdapi/velinstyle 1.1.0 → 1.2.1

package/cli/serve.js

@@ -0,0 +1,81 @@
+/**
+ * Static file server for local previews.
+ */
+import { createServer } from 'http';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, resolve, extname, normalize } from 'path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+  '.ico': 'image/x-icon',
+  '.map': 'application/json',
+};
+
+function safeJoin(root, reqPath) {
+  const decoded = decodeURIComponent((reqPath || '/').split('?')[0]);
+  const cleaned = normalize(decoded).replace(/^(\.\.[/\\])+/, '');
+  const full = resolve(root, '.' + (cleaned.startsWith('/') || cleaned.startsWith('\\') ? cleaned : `/${cleaned}`));
+  if (!full.startsWith(resolve(root))) return null;
+  return full;
+}
+
+/**
+ * @param {{ dir?: string, port?: number, host?: string }} opts
+ */
+export function serveStatic(opts = {}) {
+  const dir = resolve(opts.dir || '.');
+  const port = Number(opts.port) || 4173;
+  const host = opts.host || '127.0.0.1';
+
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${dir}` };
+  }
+
+  const server = createServer((req, res) => {
+    let filePath = safeJoin(dir, req.url || '/');
+    if (!filePath) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return;
+    }
+    if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+      filePath = join(filePath, 'index.html');
+    }
+    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Not found');
+      return;
+    }
+    const type = MIME[extname(filePath).toLowerCase()] || 'application/octet-stream';
+    try {
+      const body = readFileSync(filePath);
+      res.writeHead(200, { 'Content-Type': type });
+      res.end(body);
+    } catch {
+      res.writeHead(500);
+      res.end('Read error');
+    }
+  });
+
+  return new Promise((resolvePromise) => {
+    server.listen(port, host, () => {
+      resolvePromise({
+        ok: true,
+        server,
+        url: `http://${host}:${port}/`,
+        dir,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}

package/cli/skills.js

@@ -0,0 +1,223 @@
+import { resolve, join, dirname } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import {
+  loadRegistry,
+  listSkills,
+  findSkillById,
+  validateRegistry,
+  resolveSkillGraph,
+  installSelection,
+} from '../packages/skill-engine/src/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+const REGISTRY_PATH = join(PKG_ROOT, 'packages', 'velinstyle-skills', 'registry.json');
+const SKILLS_ROOT = join(PKG_ROOT, 'packages', 'velinstyle-skills');
+
+function argValue(argv, flag) {
+  const idx = argv.indexOf(flag);
+  return idx !== -1 ? argv[idx + 1] : null;
+}
+
+function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+
+export function loadSkillRegistry() {
+  return loadRegistry(REGISTRY_PATH);
+}
+
+export function skillsList(argv = []) {
+  const registry = loadSkillRegistry();
+  const items = listSkills(registry, {
+    capability: argValue(argv, '--capability') || undefined,
+    status: argValue(argv, '--status') || undefined,
+    priority: argValue(argv, '--priority') || undefined,
+    origin: argValue(argv, '--origin') || undefined,
+    category: argValue(argv, '--category') || undefined,
+  });
+  if (hasFlag(argv, '--json')) {
+    console.log(JSON.stringify(items, null, 2));
+    return;
+  }
+  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)`);
+}
+
+export function skillsShow(skillId, argv = []) {
+  const registry = loadSkillRegistry();
+  const skill = findSkillById(registry, skillId);
+  if (!skill) {
+    console.error(`Unknown skill: ${skillId}`);
+    process.exit(1);
+  }
+  if (hasFlag(argv, '--human')) {
+    console.log(formatSkillHuman(skill));
+    return;
+  }
+  console.log(JSON.stringify(skill, null, 2));
+}
+
+function formatSkillHuman(skill) {
+  const lines = [
+    `# ${skill.id}`,
+    '',
+    skill.title ? `**${skill.title}**` : '',
+    skill.summary || skill.description || '',
+    '',
+    `- Category: ${skill.category || '—'}`,
+    `- Status: ${skill.status || '—'}`,
+    `- Priority: ${skill.priority || '—'}`,
+    `- Capabilities: ${(skill.capabilities || []).join(', ') || '—'}`,
+  ];
+  if (skill.requiresCli?.length) lines.push(`- CLI: ${skill.requiresCli.join(', ')}`);
+  if (skill.inputs?.length) {
+    lines.push('', '## Inputs');
+    for (const input of skill.inputs) {
+      if (typeof input === 'string') {
+        lines.push(`- \`${input}\``);
+        continue;
+      }
+      const label = input.name || input.id || input.key || input.type || JSON.stringify(input);
+      lines.push(`- \`${label}\`${input.required ? ' (required)' : ''}: ${input.description || input.type || ''}`.trim());
+    }
+  }
+  if (skill.outputs?.length) {
+    lines.push('', '## Outputs');
+    for (const output of skill.outputs) {
+      if (typeof output === 'string') {
+        lines.push(`- \`${output}\``);
+        continue;
+      }
+      const label = output.name || output.id || output.key || output.type || JSON.stringify(output);
+      lines.push(`- \`${label}\`: ${output.description || output.type || ''}`.trim());
+    }
+  }
+  if (skill.dependsOn?.length) {
+    lines.push('', `## Depends on`, skill.dependsOn.map((d) => `- ${d}`).join('\n'));
+  }
+  lines.push('', '_Tip: blueprints must only emit classes present in CSS (`velinstyle blueprint --strict`)._');
+  return lines.filter(Boolean).join('\n');
+}
+
+export function skillsInstall(argv = []) {
+  const selection = argv[0];
+  if (!selection) {
+    console.error('Usage: velinstyle skills install <skill-id|pack|bundle:id|project:id>');
+    process.exit(1);
+  }
+  const target = resolve(argValue(argv, '--target') || '.cursor/skills');
+  mkdirSync(target, { recursive: true });
+  const registry = loadSkillRegistry();
+  const result = installSelection(registry, {
+    selection,
+    skillsRoot: SKILLS_ROOT,
+    targetRoot: target,
+    includeDependencies: !hasFlag(argv, '--no-deps'),
+  });
+  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');
+}
+
+export function skillsRun(skillId, argv = []) {
+  const registry = loadSkillRegistry();
+  const resolved = resolveSkillGraph(registry, skillId);
+  if (resolved.issues.length) {
+    for (const issue of resolved.issues) console.error(issue);
+    process.exit(1);
+  }
+  const steps = [];
+  for (const id of resolved.orderedSkillIds) {
+    const skill = findSkillById(registry, id);
+    if (!skill) continue;
+    steps.push({ id: skill.id, requiresCli: skill.requiresCli || [], onlyIf: skill.onlyIf || [] });
+  }
+  if (hasFlag(argv, '--json')) {
+    console.log(JSON.stringify({ steps }, null, 2));
+    return;
+  }
+  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(', ')}`);
+  }
+}
+
+export function skillsValidate() {
+  const registry = loadSkillRegistry();
+  const result = validateRegistry(registry);
+  if (result.errors.length) {
+    for (const error of result.errors) console.error(`Error: ${error}`);
+  }
+  if (result.warnings.length) {
+    for (const warning of result.warnings) console.warn(`Warning: ${warning}`);
+  }
+  console.log(result.ok ? 'skills registry valid' : 'skills registry invalid');
+  process.exit(result.ok ? 0 : 1);
+}
+
+export async function skillsDoctor(argv = []) {
+  const { doctorSkillPaths } = await import('../scripts/check-skills-paths.mjs');
+  const result = doctorSkillPaths(PKG_ROOT);
+  if (hasFlag(argv, '--json')) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.ok ? 0 : 1);
+  }
+  if (!result.ok) {
+    console.error(`skills doctor FAILED (${result.errors.length} missing path(s)):`);
+    for (const e of result.errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  console.log(`skills doctor OK (${result.checked} paths).`);
+}
+
+export function skillsIndex(kind) {
+  const registry = loadSkillRegistry();
+  const map = {
+    packs: registry.packs || [],
+    bundles: registry.bundles || [],
+    templates: registry.templates || [],
+    projects: registry.projects || [],
+    graphs: registry.workflowGraphs || [],
+  };
+  const out = map[kind] || [];
+  console.log(JSON.stringify(out, null, 2));
+}
+
+export function skillsCommand(argv = []) {
+  const sub = argv[0];
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(`Usage: velinstyle skills <subcommand>
+
+Subcommands:
+  list [--category <id>] [--status <id>] [--json]
+  show <skill-id> [--human]
+  install <skill-id|pack:id|bundle:id|template:id>
+  run <skill-id> [--json]   (dry-run / inspect — not apply)
+  validate
+  doctor [--json]           Fail if demo/docs/starter paths missing
+  packs | bundles | templates | projects | graphs
+`);
+    process.exit(0);
+  }
+  if (sub === 'list') return skillsList(argv.slice(1));
+  if (sub === 'show') return skillsShow(argv[1], argv.slice(2));
+  if (sub === 'install') return skillsInstall(argv.slice(1));
+  if (sub === 'run') return skillsRun(argv[1], argv.slice(2));
+  if (sub === 'validate') return skillsValidate();
+  if (sub === 'doctor') return skillsDoctor(argv.slice(1));
+  if (sub === 'packs' || sub === 'bundles' || sub === 'templates' || sub === 'projects' || sub === 'graphs') return skillsIndex(sub);
+  console.error(`Unknown skills subcommand: ${sub}`);
+  process.exit(1);
+}
+
+export function getRegistryPathForMeta() {
+  return REGISTRY_PATH;
+}

package/cli/transparency.js

@@ -0,0 +1,221 @@
+/**
+ * CLI: velinstyle transparency doctor|validate|report|export|migrate|scan
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { join, resolve, extname, basename } from 'path';
+import {
+  createTransparencyEngine,
+  normalizePolicy,
+} from '../core/transparency/index.js';
+
+function loadPolicy(policyPath) {
+  if (!policyPath) return normalizePolicy({});
+  const abs = resolve(policyPath);
+  if (!existsSync(abs)) throw new Error(`Policy not found: ${abs}`);
+  return normalizePolicy(JSON.parse(readFileSync(abs, 'utf-8')));
+}
+
+function collectHtmlFiles(target) {
+  const abs = resolve(target || '.');
+  if (!existsSync(abs)) throw new Error(`Path not found: ${abs}`);
+  const st = statSync(abs);
+  if (st.isFile()) return [abs];
+  const out = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      if (name === 'node_modules' || name === '.git' || name === 'dist') continue;
+      const p = join(dir, name);
+      const s = statSync(p);
+      if (s.isDirectory()) walk(p);
+      else if (/\.html?$/i.test(name)) out.push(p);
+    }
+  };
+  walk(abs);
+  return out;
+}
+
+function printScores(scores, C) {
+  if (!scores) return;
+  console.log(C.bold('\nScores'));
+  for (const [k, v] of Object.entries(scores)) {
+    console.log(`  ${k.padEnd(14)} ${v}%`);
+  }
+}
+
+/**
+ * @param {string[]} args process.argv slice after "transparency"
+ * @param {{ C: object, getArg: Function, hasFlag: Function }} util
+ */
+export async function transparencyCmd(args, util) {
+  const { C, getArg, hasFlag } = util;
+  const sub = args[0] || 'doctor';
+  const rest = args.slice(1);
+  const target = rest.find((a) => !a.startsWith('-')) || '.';
+  const policyPath = getArg('--policy');
+  const policy = loadPolicy(policyPath);
+  const asJson = hasFlag('--json');
+  const engine = createTransparencyEngine({ policy });
+
+  if (sub === 'scan') {
+    return runDoctor(target, engine, { asJson, C });
+  }
+  if (sub === 'doctor') {
+    return runDoctor(target, engine, { asJson, C });
+  }
+  if (sub === 'validate') {
+    return runValidate(target, engine, { asJson, C });
+  }
+  if (sub === 'report') {
+    return runReport(target, engine, { C, getArg });
+  }
+  if (sub === 'export') {
+    return runExport(target, engine, { C, getArg });
+  }
+  if (sub === 'migrate') {
+    return runMigrate(target, engine, { C, hasFlag, getArg });
+  }
+  if (sub === 'suggest') {
+    return runMigrate(target, engine, { C, hasFlag, getArg, forceDry: true });
+  }
+  if (sub === 'apply') {
+    return runMigrate(target, engine, { C, hasFlag, getArg, forceApply: true });
+  }
+
+  console.log(`Unknown transparency subcommand: ${sub}
+Usage:
+  velinstyle transparency doctor|validate|report|export|migrate|scan [path]
+`);
+  process.exitCode = 1;
+}
+
+async function runDoctor(target, engine, { asJson, C }) {
+  const files = collectHtmlFiles(target);
+  if (!files.length) {
+    console.log(C.yellow('No HTML files found.'));
+    process.exitCode = 1;
+    return;
+  }
+  const reports = [];
+  let failed = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const report = await engine.doctor(html, { file });
+    reports.push(report);
+    if (!report.ok) failed += 1;
+    if (!asJson) {
+      console.log(C.bold(`\n── ${basename(file)} ──`));
+      console.log(report.ok ? C.green('PASS') : C.red('FAIL'));
+      console.log(`disclosures=${report.summary.disclosures} errors=${report.summary.errors} warnings=${report.summary.warnings}`);
+      printScores(report.scores, C);
+      for (const f of report.findings.slice(0, 40)) {
+        const color = f.severity === 'error' ? C.red : f.severity === 'warning' ? C.yellow : C.dim;
+        console.log(color(`  [${f.severity}] ${f.code}: ${f.message}`));
+      }
+      if (report.findings.length > 40) console.log(C.dim(`  … ${report.findings.length - 40} more`));
+    }
+  }
+  if (asJson) {
+    console.log(JSON.stringify(files.length === 1 ? reports[0] : { reports }, null, 2));
+  } else {
+    console.log(failed ? C.red(`\ntransparency doctor: ${failed} file(s) failed`) : C.green('\ntransparency doctor: ok'));
+  }
+  if (failed) process.exitCode = 1;
+  return reports;
+}
+
+async function runValidate(target, engine, { asJson, C }) {
+  const files = collectHtmlFiles(target);
+  const all = [];
+  let failed = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const result = await engine.validate(html, { file });
+    all.push({ file, ...result });
+    if (!result.ok) failed += 1;
+    if (!asJson) {
+      console.log(`${basename(file)}: ${result.ok ? C.green('valid') : C.red('invalid')} (${result.findings.length} findings)`);
+    }
+  }
+  if (asJson) console.log(JSON.stringify(all, null, 2));
+  if (failed) process.exitCode = 1;
+}
+
+async function runReport(target, engine, { C, getArg }) {
+  const outDir = resolve(getArg('--out') || 'transparency-report');
+  mkdirSync(outDir, { recursive: true });
+  const files = collectHtmlFiles(target);
+  const combined = { schema: 'velinstyle.transparency.report.bundle', version: 1, files: [] };
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const artifacts = await engine.report(html, { file, title: `Transparency — ${basename(file)}` });
+    const base = basename(file, extname(file));
+    writeFileSync(join(outDir, `${base}.report.json`), JSON.stringify(artifacts.json, null, 2));
+    writeFileSync(join(outDir, `${base}.report.sarif`), JSON.stringify(artifacts.sarif, null, 2));
+    writeFileSync(join(outDir, `${base}.report.html`), artifacts.html);
+    combined.files.push({ file, scores: artifacts.json.scores, ok: artifacts.json.ok });
+  }
+  writeFileSync(join(outDir, 'index.json'), JSON.stringify(combined, null, 2));
+  console.log(C.green(`Wrote transparency reports to ${outDir}`));
+}
+
+async function runExport(target, engine, { C, getArg }) {
+  const format = getArg('--format') || 'json';
+  const out = getArg('--output') || getArg('-o');
+  const files = collectHtmlFiles(target);
+  const fresh = createTransparencyEngine({ policy: engine.policy });
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const { records } = await createTransparencyEngine({ policy: engine.policy }).ingest(html, { file });
+    for (const r of records) fresh.registry.register(r);
+  }
+  const body = fresh.export(format);
+  if (out) {
+    writeFileSync(resolve(out), body);
+    console.log(C.green(`Exported ${format} → ${out}`));
+  } else {
+    console.log(body);
+  }
+}
+
+async function runMigrate(target, engine, { C, hasFlag, getArg, forceDry, forceApply }) {
+  const apply = forceApply || hasFlag('--apply') || hasFlag('--write');
+  const dryRun = forceDry || (!apply);
+  const files = collectHtmlFiles(target);
+  let total = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const result = await engine.migrate(html, { file, apply: apply && !dryRun, dryRun });
+    total += result.suggestions.length;
+    console.log(C.bold(`\n── ${basename(file)} ──`));
+    console.log(`${result.suggestions.length} suggestion(s)${apply && !dryRun ? `, applied ${result.applied}` : ' (dry-run)'}`);
+    for (const s of result.suggestions.slice(0, 30)) {
+      console.log(C.dim(`  • ${s.id || s.field || s.kind}: ${s.reason}`));
+    }
+    if (apply && !dryRun && result.applied) {
+      writeFileSync(file, result.html);
+      console.log(C.green(`  wrote ${file}`));
+    }
+  }
+  if (!total) console.log(C.green('\nNo migration suggestions.'));
+}
+
+/**
+ * Lightweight doctor for velinstyle check integration.
+ */
+export async function transparencyCheckStep(path, { policyPath, quiet, C } = {}) {
+  const policy = loadPolicy(policyPath);
+  const engine = createTransparencyEngine({ policy });
+  const files = collectHtmlFiles(path);
+  if (!files.length) return { ok: true, skipped: true, scores: null };
+  let failed = 0;
+  let lastScores = null;
+  for (const file of files.slice(0, 20)) {
+    const report = await engine.doctor(readFileSync(file, 'utf-8'), { file });
+    lastScores = report.scores;
+    if (!report.ok) failed += 1;
+    if (!quiet) {
+      console.log(`  ${basename(file)}: transparency ${report.scores?.transparency ?? '—'}% (${report.summary.errors} errors)`);
+    }
+  }
+  return { ok: failed === 0, failed, scores: lastScores };
+}

package/cli/wc-api.js

@@ -0,0 +1,89 @@
+/**
+ * Human-readable WC API from source + generated docs tip.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * @param {string} pkgRoot
+ * @param {string} tag
+ */
+export function describeWcApi(pkgRoot, tag) {
+  const name = String(tag || '').replace(/^</, '').replace(/>$/, '').trim();
+  if (!name.startsWith('velin-')) {
+    return { ok: false, error: `Expected a velin-* tag (got "${tag || ''}"). Example: velinstyle wc api velin-toast` };
+  }
+  const file = join(pkgRoot, 'components', `${name}.js`);
+  if (!existsSync(file)) {
+    return { ok: false, error: `No source at components/${name}.js` };
+  }
+  const src = readFileSync(file, 'utf-8');
+  const attrs = [...src.matchAll(/static\s+get\s+observedAttributes\(\)\s*\{\s*return\s*\[([^\]]*)\]/gs)]
+    .map((m) => m[1].split(',').map((s) => s.replace(/['"`\s]/g, '')).filter(Boolean))
+    .flat();
+  const methods = [...src.matchAll(/^\s{2}([a-zA-Z_][\w]*)\s*\([^)]*\)\s*\{/gm)]
+    .map((m) => m[1])
+    .filter((n) => !['constructor', 'connectedCallback', 'disconnectedCallback', 'attributeChangedCallback', 'adoptedCallback'].includes(n));
+  const showSig = src.match(/show\s*\(\s*\{([^}]*)\}\s*=\s*\{\s*\}\s*\)/);
+  const events = [...src.matchAll(/new\s+CustomEvent\(\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  const unique = (arr) => [...new Set(arr)];
+
+  const docPath = join(pkgRoot, 'docs/generated/components', `${name}.md`);
+  const hasDoc = existsSync(docPath);
+
+  let example = '';
+  if (name === 'velin-toast' && showSig) {
+    example = `<velin-toast></velin-toast>
+<script type="module">
+  const t = document.querySelector('velin-toast');
+  t.show({ message: 'Saved', type: 'success', duration: 4000 });
+</script>`;
+  } else if (name === 'velin-calendar') {
+    example = `<velin-calendar label="Pick a day" value="2026-07-30"></velin-calendar>`;
+  } else if (name === 'velin-file-dropzone') {
+    example = `<velin-file-dropzone label="Files" accept=".pdf,.png" multiple></velin-file-dropzone>`;
+  } else if (name === 'velin-data-table') {
+    example = `<velin-data-table label="Rows" page-size="5" filter-input="#q" editable>
+  <table>…</table>
+</velin-data-table>`;
+  }
+
+  return {
+    ok: true,
+    tag: name,
+    source: `components/${name}.js`,
+    observedAttributes: unique(attrs),
+    methods: unique(methods),
+    events: unique(events),
+    showSignature: showSig ? `show({ ${showSig[1].trim()} } = {})` : null,
+    generatedDoc: hasDoc ? `docs/generated/components/${name}.md` : null,
+    example: example || null,
+  };
+}
+
+export function formatWcApi(report) {
+  if (!report.ok) return report.error;
+  const lines = [
+    `# <${report.tag}>`,
+    '',
+    `Source: \`${report.source}\``,
+    report.generatedDoc ? `Generated docs: \`${report.generatedDoc}\`` : 'Generated docs: (missing — run `velinstyle docs generate`)',
+    '',
+    '## observedAttributes',
+    report.observedAttributes.length ? report.observedAttributes.map((a) => `- \`${a}\``).join('\n') : '_none_',
+    '',
+    '## Methods (from source)',
+    report.methods.length ? report.methods.map((m) => `- \`${m}()\``).join('\n') : '_none detected_',
+  ];
+  if (report.showSignature) {
+    lines.push('', '## Toast show()', `\`${report.showSignature}\``);
+  }
+  if (report.events.length) {
+    lines.push('', '## Custom events', report.events.map((e) => `- \`${e}\``).join('\n'));
+  }
+  if (report.example) {
+    lines.push('', '## Example', '```html', report.example, '```');
+  }
+  lines.push('', '_Tip: offline create projects include `vendor/velinstyle/docs/` mini copies of core WC markdown._');
+  return lines.join('\n');
+}

package/cli/workflow.js

@@ -0,0 +1,42 @@
+import { loadRegistry, resolveWorkflowGraph } from '../packages/skill-engine/src/index.js';
+import { getRegistryPathForMeta } from './skills.js';
+
+function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+
+export function workflowCommand(argv = []) {
+  const workflowId = argv[0];
+  if (!workflowId || workflowId === '--help' || workflowId === '-h') {
+    console.log(`Usage: velinstyle workflow <graph-id|project:id> [--json]
+
+Examples:
+  velinstyle workflow landingpage
+  velinstyle workflow project:marketing-site --json
+`);
+    process.exit(0);
+  }
+  const registry = loadRegistry(getRegistryPathForMeta());
+  let resolved;
+  if (workflowId.startsWith('project:')) {
+    const projectId = workflowId.replace('project:', '');
+    const project = (registry.projects || []).find((item) => item.id === projectId);
+    if (!project) {
+      console.error(`Unknown project: ${projectId}`);
+      process.exit(1);
+    }
+    resolved = resolveWorkflowGraph(registry, project.workflowGraph);
+  } else {
+    resolved = resolveWorkflowGraph(registry, workflowId);
+  }
+  if (resolved.issues.length) {
+    for (const issue of resolved.issues) console.error(issue);
+    process.exit(1);
+  }
+  if (hasFlag(argv, '--json')) {
+    console.log(JSON.stringify(resolved, null, 2));
+    return;
+  }
+  console.log(`Workflow steps (${resolved.orderedSteps.length}):`);
+  for (const step of resolved.orderedSteps) console.log(`- ${step}`);
+}

package/components/index.js

@@ -35,6 +35,8 @@ export { default as VelinLiveDot } from './velin-live-dot.js';
 export { default as VelinCodeBlock } from './velin-code-block.js';
 export { default as VelinDataTable } from './velin-data-table.js';
 export { default as VelinFormSummary } from './velin-form-summary.js';
+export { default as VelinCalendar } from './velin-calendar.js';
+export { default as VelinFileDropzone } from './velin-file-dropzone.js';
 export { default as VelinSearch } from './velin-search.js';
 export { bindDeclarativeSearch } from './velin-search.js';
 export { initReveal, initMotion, velinMotion } from './velin-reveal.js';

package/components/runtime/component-loaders.js

@@ -5,6 +5,7 @@ export const COMPONENT_LOADERS = {
   'velin-accordion': () => import('../velin-accordion.js'),
   'velin-announcer': () => import('../velin-announcer.js'),
   'velin-bottom-nav': () => import('../velin-bottom-nav.js'),
+  'velin-calendar': () => import('../velin-calendar.js'),
   'velin-carousel': () => import('../velin-carousel.js'),
   'velin-code-block': () => import('../velin-code-block.js'),
   'velin-collapse': () => import('../velin-collapse.js'),
@@ -18,6 +19,7 @@ export const COMPONENT_LOADERS = {
   'velin-drawer': () => import('../velin-drawer.js'),
   'velin-dropdown': () => import('../velin-dropdown.js'),
   'velin-email': () => import('../velin-email.js'),
+  'velin-file-dropzone': () => import('../velin-file-dropzone.js'),
   'velin-form-summary': () => import('../velin-form-summary.js'),
   'velin-icon': () => import('../velin-icon.js'),
   'velin-lightbox': () => import('../velin-lightbox.js'),