@birdapi/velinstyle 0.7.0 → 0.9.0

package/cli/meta.js

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { buildAgentBundle, buildLlmsTxt, buildPageMeta, serializePageMetaScript } from '../core/meta/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.outFile]
+ * @param {string} [options.llmsFile]
+ * @param {string} [options.baseUrl]
+ * @param {boolean} [options.llms]
+ */
+export async function buildMeta(options = {}) {
+  const outFile = options.outFile || join(PKG_ROOT, 'dist', 'velin-agent.json');
+  const llmsFile = options.llmsFile || join(PKG_ROOT, 'dist', 'llms.txt');
+  const bundle = await buildAgentBundle({ pkgRoot: PKG_ROOT });
+
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, JSON.stringify(bundle, null, 2), 'utf-8');
+
+  const written = [outFile];
+
+  if (options.llms !== false) {
+    const llms = buildLlmsTxt(bundle, options.baseUrl || 'https://velinstyle.info');
+    writeFileSync(llmsFile, llms, 'utf-8');
+    written.push(llmsFile);
+  }
+
+  return { ok: true, bundle, written, count: written.length };
+}
+
+/**
+ * @param {string} htmlPath
+ * @param {object} [options]
+ */
+export function metaPage(htmlPath, options = {}) {
+  const abs = resolve(htmlPath);
+  if (!existsSync(abs)) {
+    return { ok: false, error: `File not found: ${abs}` };
+  }
+  const html = readFileSync(abs, 'utf-8');
+  const rel = htmlPath.replace(/\\/g, '/');
+  const meta = buildPageMeta(html, rel, PKG_ROOT);
+  const script = serializePageMetaScript(meta);
+
+  if (options.write) {
+    if (html.includes('id="velin-meta"')) {
+      const updated = html.replace(
+        /<script[^>]*id=["']velin-meta["'][^>]*>[\s\S]*?<\/script>/i,
+        script,
+      );
+      writeFileSync(abs, updated, 'utf-8');
+    } else if (/<\/head>/i.test(html)) {
+      writeFileSync(abs, html.replace(/<\/head>/i, `  ${script}\n</head>`), 'utf-8');
+    } else {
+      return { ok: false, error: 'No </head> or existing velin-meta block found' };
+    }
+  }
+
+  return { ok: true, meta, script };
+}
+
+export async function metaMain(argv = process.argv.slice(2)) {
+  const pageIdx = argv.indexOf('page');
+  if (pageIdx !== -1 && argv[pageIdx + 1]) {
+    const write = argv.includes('--write');
+    const result = metaPage(argv[pageIdx + 1], { write });
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    if (write) {
+      console.log(`Updated velin-meta in ${argv[pageIdx + 1]}`);
+    } else {
+      console.log(result.script);
+    }
+    return;
+  }
+
+  const outIdx = argv.indexOf('--out');
+  const llmsIdx = argv.indexOf('--llms-out');
+  const baseIdx = argv.indexOf('--base-url');
+  const noLlms = argv.includes('--no-llms');
+
+  const result = await buildMeta({
+    outFile: outIdx !== -1 && argv[outIdx + 1] ? resolve(argv[outIdx + 1]) : undefined,
+    llmsFile: llmsIdx !== -1 && argv[llmsIdx + 1] ? resolve(argv[llmsIdx + 1]) : undefined,
+    baseUrl: baseIdx !== -1 && argv[baseIdx + 1] ? argv[baseIdx + 1] : undefined,
+    llms: !noLlms,
+  });
+
+  console.log(`Velin-Meta: wrote ${result.count} file(s)`);
+  for (const p of result.written) console.log(`  ${p}`);
+}

package/cli/perf-audit.js

@@ -0,0 +1,174 @@
+/**
+ * Performance audit for static HTML — images, scripts, inline styles.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, extname, relative } from 'path';
+
+const DEFAULT_IGNORE = ['node_modules', 'dist', '.git', '.next', 'build'];
+
+export function walkHtmlFiles(dir, ignore = DEFAULT_IGNORE) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (ignore.includes(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...walkHtmlFiles(full, ignore));
+    else if (extname(entry.name).toLowerCase() === '.html') results.push(full);
+  }
+  return results;
+}
+
+function lineOf(content, index) {
+  return content.slice(0, index).split('\n').length;
+}
+
+/**
+ * @param {string} html
+ * @param {{ file?: string }} meta
+ */
+export function auditHtml(html, meta = {}) {
+  const issues = [];
+  const file = meta.file || '';
+  const lines = html.split('\n');
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+
+    const imgTags = [...line.matchAll(/<img\b[^>]*>/gi)];
+    for (const m of imgTags) {
+      const tag = m[0];
+      const hasW = /\bwidth\s*=/i.test(tag);
+      const hasH = /\bheight\s*=/i.test(tag);
+      const hasStyleDim = /style\s*=\s*["'][^"']*(?:width|height)\s*:/i.test(tag);
+      if (!hasW && !hasH && !hasStyleDim) {
+        issues.push({
+          id: 'img-missing-dimensions',
+          severity: 'warning',
+          message: '<img> without width/height causes layout shift (CLS).',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<img\b/i, '<img width="800" height="450"'),
+        });
+      }
+      if (!/\bloading\s*=/i.test(tag) && !/\bfetchpriority\s*=\s*["']high["']/i.test(tag)) {
+        issues.push({
+          id: 'img-no-lazy',
+          severity: 'info',
+          message: 'Consider loading="lazy" for below-fold images.',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<img\b/i, '<img loading="lazy"'),
+        });
+      }
+    }
+
+    const scriptTags = [...line.matchAll(/<script\b[^>]*>/gi)];
+    for (const m of scriptTags) {
+      const tag = m[0];
+      if (/\bsrc\s*=/i.test(tag) && !/\bdefer\b/i.test(tag) && !/\basync\b/i.test(tag) && !/\btype\s*=\s*["']module["']/i.test(tag)) {
+        issues.push({
+          id: 'script-no-defer',
+          severity: 'warning',
+          message: 'External <script> without defer/async blocks parsing.',
+          line: ln,
+          file,
+          fixable: true,
+          fix: (l) => l.replace(/<script\b/i, '<script defer'),
+        });
+      }
+    }
+
+    if (/\sstyle\s*=\s*["'][^"']{120,}["']/i.test(line)) {
+      issues.push({
+        id: 'large-inline-style',
+        severity: 'info',
+        message: 'Large inline style block. Prefer external CSS.',
+        line: ln,
+        file,
+        fixable: false,
+      });
+    }
+  });
+
+  if (/@font-face/i.test(html) && !/font-display\s*:\s*swap/i.test(html)) {
+    issues.push({
+      id: 'font-display-swap',
+      severity: 'info',
+      message: 'Add font-display: swap to @font-face rules.',
+      file,
+      line: 1,
+      fixable: false,
+    });
+  }
+
+  if (/velinstyle-components\.min\.js/i.test(html) && /velin-(?:modal|toast|tabs)/i.test(html) === false) {
+    issues.push({
+      id: 'unused-velin-import',
+      severity: 'info',
+      message: 'Full component bundle loaded. Consider @birdapi/velinstyle/runtime for tree-shaking.',
+      file,
+      line: 1,
+      fixable: false,
+    });
+  }
+
+  return issues;
+}
+
+export function auditPath(targetPath) {
+  const files = walkHtmlFiles(targetPath);
+  const issues = [];
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    issues.push(...auditHtml(html, { file }));
+  }
+  return { issues, files };
+}
+
+export function formatTextReport(issues, files) {
+  const lines = [`Performance audit — ${files.length} HTML file(s)\n`];
+  if (issues.length === 0) {
+    lines.push('No performance issues found.');
+    return lines.join('\n');
+  }
+  for (const i of issues) {
+    const loc = i.line ? `${relative(process.cwd(), i.file)}:${i.line}` : i.file;
+    lines.push(`[${i.severity}] ${i.id} — ${loc}`);
+    lines.push(`  ${i.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function fixPath(targetPath, { write = false, dryRun = true } = {}) {
+  const { issues } = auditPath(targetPath);
+  const fixable = issues.filter((i) => i.fixable && typeof i.fix === 'function');
+  const byFile = {};
+  for (const issue of fixable) {
+    if (!byFile[issue.file]) byFile[issue.file] = [];
+    byFile[issue.file].push(issue);
+  }
+  const changes = [];
+  for (const [file, fileIssues] of Object.entries(byFile)) {
+    const original = readFileSync(file, 'utf-8');
+    const lines = original.split('\n');
+    fileIssues.sort((a, b) => b.line - a.line);
+    const applied = [];
+    for (const issue of fileIssues) {
+      const idx = issue.line - 1;
+      if (idx < 0 || idx >= lines.length) continue;
+      const next = issue.fix(lines[idx]);
+      if (next !== lines[idx]) {
+        lines[idx] = next;
+        applied.push(issue.id);
+      }
+    }
+    const content = lines.join('\n');
+    if (content !== original) {
+      if (write && !dryRun) writeFileSync(file, content, 'utf-8');
+      changes.push({ file, changes: applied });
+    }
+  }
+  return { ok: true, changes, dryRun: dryRun && !write };
+}

package/cli/pii-scanner.js

@@ -0,0 +1,134 @@
+/**
+ * PII / secrets detection for velinstyle scan (--only pii).
+ */
+
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+const PLACEHOLDER_EMAILS = new Set([
+  'user@example.com',
+  'test@example.com',
+  'admin@example.com',
+  'email@example.com',
+  'you@example.com',
+  'name@example.com',
+  '{{email}}',
+  '{{EMAIL}}',
+]);
+
+const SECRET_PATTERNS = [
+  { re: /\b(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{8,}['"]/i, rule: 'pii/hardcoded-secret', msg: 'Possible API key in source.' },
+  { re: /\b(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{4,}['"]/i, rule: 'pii/hardcoded-secret', msg: 'Possible password/secret in source.' },
+  { re: /\bAKIA[0-9A-Z]{16}\b/, rule: 'pii/hardcoded-secret', msg: 'AWS access key pattern detected.' },
+  { re: /\bsk_(?:live|test)_[0-9a-zA-Z]{16,}\b/, rule: 'pii/hardcoded-secret', msg: 'Stripe secret key pattern detected.' },
+  { re: /\bghp_[0-9a-zA-Z]{36,}\b/, rule: 'pii/hardcoded-secret', msg: 'GitHub token pattern detected.' },
+];
+
+export function isPlaceholderEmail(email) {
+  const lower = email.toLowerCase();
+  if (PLACEHOLDER_EMAILS.has(lower)) return true;
+  if (/@example\.(com|org|net)$/i.test(email)) return true;
+  if (/@test\.(com|local)$/i.test(email)) return true;
+  if (/@localhost$/i.test(email)) return true;
+  return false;
+}
+
+export function maskEmail(email, placeholder = 'user@example.com') {
+  return placeholder;
+}
+
+export function fixHardcodedEmailLine(line, placeholder = 'user@example.com') {
+  return line.replace(EMAIL_RE, (match) => {
+    if (isPlaceholderEmail(match)) return match;
+    return placeholder;
+  });
+}
+
+export function scanPIIHTML(content, file, options = {}) {
+  const issues = [];
+  const lines = content.split('\n');
+  const placeholder = options.fixEmailPlaceholder || 'user@example.com';
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+    if (/\/\/|\/\*|\*\/|<!--/.test(line) && !/@/.test(line.replace(/<!--.*-->/, ''))) {
+      /* still scan — emails in comments are PII too */
+    }
+
+    const emails = [...line.matchAll(EMAIL_RE)].map((m) => m[0]);
+    for (const email of emails) {
+      if (isPlaceholderEmail(email)) continue;
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/hardcoded-email',
+        message: `Hardcoded email "${email}" found. Use env/config or <velin-email>.`,
+        fixable: true,
+        fix: (currentLine) => fixHardcodedEmailLine(currentLine, placeholder),
+      });
+    }
+
+    const hasMailto = /mailto:/i.test(line);
+    const emailRe = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/;
+    if (hasMailto && emailRe.test(line)) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 2,
+        rule: 'pii/mailto-in-source',
+        message: 'mailto: link exposes email in HTML. Consider <velin-email> for obfuscation.',
+        fixable: false,
+      });
+    }
+  });
+
+  return issues;
+}
+
+export function scanPIIJS(content, file) {
+  const issues = [];
+  const lines = content.split('\n');
+
+  lines.forEach((line, idx) => {
+    const ln = idx + 1;
+
+    for (const { re, rule, msg } of SECRET_PATTERNS) {
+      if (re.test(line)) {
+        issues.push({
+          file,
+          line: ln,
+          severity: 0,
+          rule,
+          message: msg,
+          fixable: false,
+        });
+      }
+    }
+
+    const emails = [...line.matchAll(EMAIL_RE)].map((m) => m[0]);
+    for (const email of emails) {
+      if (isPlaceholderEmail(email)) continue;
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/hardcoded-email',
+        message: `Hardcoded email "${email}" in JavaScript.`,
+        fixable: true,
+        fix: (currentLine) => fixHardcodedEmailLine(currentLine),
+      });
+    }
+
+    if (/localStorage\.setItem\s*\([^)]*@/.test(line) || /sessionStorage\.setItem\s*\([^)]*@/.test(line)) {
+      issues.push({
+        file,
+        line: ln,
+        severity: 1,
+        rule: 'pii/localstorage-pii',
+        message: 'Storing email-like data in Web Storage may violate privacy policies.',
+        fixable: false,
+      });
+    }
+  });
+
+  return issues;
+}

package/cli/scaffold-recipes.json

@@ -0,0 +1,70 @@
+{
+  "intents": {
+    "navbar": {
+      "keywords": ["navbar", "navigation", "nav bar", "nav-bar", "header", "menü", "menu bar", "top bar"],
+      "blueprints": ["navbar-header"],
+      "optional": ["search-field"],
+      "optionalIf": { "search": ["search-field"], "suche": ["search-field"] },
+      "confidence": "high"
+    },
+    "modal": {
+      "keywords": ["modal", "dialog", "popup", "bestätigung", "confirm", "lightbox"],
+      "blueprints": ["modal"],
+      "confidence": "high"
+    },
+    "card": {
+      "keywords": ["card", "cards", "karte", "karten", "grid", "kacheln"],
+      "blueprints": ["card-grid"],
+      "confidence": "high"
+    },
+    "dashboard": {
+      "keywords": ["dashboard", "admin", "shell", "sidebar layout", "app shell"],
+      "blueprints": ["navbar-header", "layout-dashboard"],
+      "confidence": "high"
+    },
+    "login": {
+      "keywords": ["login", "sign in", "signin", "anmelden", "auth"],
+      "blueprints": ["form-login"],
+      "confidence": "high"
+    },
+    "footer": {
+      "keywords": ["footer", "fußzeile", "fusszeile", "site footer"],
+      "blueprints": ["footer-simple"],
+      "confidence": "high"
+    },
+    "pricing": {
+      "keywords": ["pricing", "preise", "plans", "tarife", "subscription"],
+      "blueprints": ["pricing-table"],
+      "confidence": "high"
+    },
+    "empty": {
+      "keywords": ["empty state", "empty-state", "keine daten", "no results", "leer"],
+      "blueprints": ["empty-state"],
+      "confidence": "high"
+    },
+    "hero": {
+      "keywords": ["hero", "landing", "above the fold", "cta section"],
+      "blueprints": ["hero-section"],
+      "confidence": "medium"
+    },
+    "table": {
+      "keywords": ["table", "datatable", "data table", "tabelle"],
+      "blueprints": ["table-responsive"],
+      "confidence": "high"
+    },
+    "onboarding": {
+      "keywords": ["onboarding", "wizard", "steps", "tutorial flow"],
+      "blueprints": ["onboarding"],
+      "confidence": "high"
+    }
+  },
+  "fallback": {
+    "intent": "hero",
+    "confidence": "low"
+  },
+  "slots": {
+    "brand": ["brand", "logo", "marke"],
+    "title": ["title", "titel", "heading", "überschrift"],
+    "cta": ["cta", "button", "get started", "loslegen", "start"]
+  }
+}

package/cli/scaffold.js

@@ -0,0 +1,155 @@
+/**
+ * Prompt-based scaffolding: map natural language to VelinStyle blueprint composition.
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { emitBlueprint } from './blueprint.js';
+import { auditHtml, suggestFromIssues } from './layout-audit.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RECIPES_PATH = join(__dirname, 'scaffold-recipes.json');
+
+function loadRecipes() {
+  return JSON.parse(readFileSync(RECIPES_PATH, 'utf-8'));
+}
+
+/**
+ * @param {string} prompt
+ */
+export function parseIntent(prompt) {
+  const recipes = loadRecipes();
+  const lower = prompt.toLowerCase();
+  let best = { id: recipes.fallback.intent, confidence: recipes.fallback.confidence, score: 0 };
+
+  for (const [id, def] of Object.entries(recipes.intents)) {
+    let score = 0;
+    for (const kw of def.keywords) {
+      if (lower.includes(kw.toLowerCase())) score += kw.length;
+    }
+    if (score > best.score) {
+      best = { id, confidence: def.confidence || 'medium', score };
+    }
+  }
+
+  return { id: best.id, confidence: best.score > 0 ? best.confidence : 'low' };
+}
+
+/**
+ * @param {string} prompt
+ */
+export function extractSlots(prompt) {
+  const recipes = loadRecipes();
+  const lower = prompt.toLowerCase();
+  const slots = {
+    brand: 'Brand',
+    title: 'Welcome',
+    cta: 'Get started',
+    columns: 3,
+  };
+
+  const brandMatch = prompt.match(/(?:brand|logo|marke)\s*[:\-]?\s*["']?([^"'\n,]+)/i);
+  if (brandMatch) slots.brand = brandMatch[1].trim();
+
+  const titleMatch = prompt.match(/(?:title|titel|heading)\s*[:\-]?\s*["']?([^"'\n]+)/i);
+  if (titleMatch) slots.title = titleMatch[1].trim();
+
+  const colMatch = lower.match(/(\d+)\s*(?:spalten|columns|cols|karten|cards)/);
+  if (colMatch) slots.columns = Math.min(12, Math.max(1, parseInt(colMatch[1], 10)));
+
+  for (const [slot, keys] of Object.entries(recipes.slots || {})) {
+    if (keys.some((k) => lower.includes(k)) && slot === 'cta') {
+      slots.cta = 'Get started';
+    }
+  }
+
+  if (/suche|search/i.test(prompt)) slots.includeSearch = true;
+
+  return slots;
+}
+
+/**
+ * @param {string} intentId
+ * @param {{ prompt?: string, slots?: object }} options
+ */
+export function resolveBlueprints(intentId, options = {}) {
+  const recipes = loadRecipes();
+  const def = recipes.intents[intentId] || recipes.intents[recipes.fallback.intent];
+  const ids = [...def.blueprints];
+
+  const lower = (options.prompt || '').toLowerCase();
+  if (def.optionalIf) {
+    for (const [key, bps] of Object.entries(def.optionalIf)) {
+      if (lower.includes(key)) ids.push(...bps);
+    }
+  }
+  if (options.slots?.includeSearch && intentId === 'navbar' && !ids.includes('search-field')) {
+    ids.push('search-field');
+  }
+
+  return [...new Set(ids)];
+}
+
+function applySlots(html, slots) {
+  let out = html;
+  out = out.replace(/\bBrand\b/g, slots.brand);
+  out = out.replace(/Card one/gi, `${slots.title} — 1`);
+  out = out.replace(/Welcome/gi, slots.title);
+  out = out.replace(/Get started/gi, slots.cta);
+  return out;
+}
+
+/**
+ * @param {string} prompt
+ * @param {{ pkgRoot?: string }} options
+ */
+export function scaffoldFromPrompt(prompt, options = {}) {
+  if (!prompt || !prompt.trim()) {
+    return { ok: false, error: 'Prompt is required.' };
+  }
+
+  const intent = parseIntent(prompt);
+  const slots = extractSlots(prompt);
+  const blueprintIds = resolveBlueprints(intent.id, { prompt, slots });
+
+  const parts = [];
+  for (const id of blueprintIds) {
+    const r = emitBlueprint(id, {});
+    if (!r.ok) {
+      return { ok: false, error: r.error };
+    }
+    parts.push(r.text);
+  }
+
+  let html = parts.join('\n\n');
+  html = applySlots(html, slots);
+
+  const banner =
+    `<!-- Generated by velinstyle scaffold (0.8.0) — intent: ${intent.id}, confidence: ${intent.confidence} -->\n` +
+    `<!-- Blueprints: ${blueprintIds.join(', ')} — run: velinstyle layout suggest & velinstyle scan -->\n`;
+
+  const fullHtml = banner + html;
+  const issues = auditHtml(fullHtml);
+  const responsiveHints = suggestFromIssues(issues);
+
+  return {
+    ok: true,
+    intent: intent.id,
+    confidence: intent.confidence,
+    blueprints: blueprintIds,
+    html: fullHtml,
+    slots,
+    responsiveHints,
+    nextSteps: ['velinstyle layout suggest <file>', 'velinstyle scan <file>'],
+  };
+}
+
+export function listIntents() {
+  const recipes = loadRecipes();
+  return Object.entries(recipes.intents).map(([id, def]) => ({
+    id,
+    keywords: def.keywords,
+    blueprints: def.blueprints,
+    confidence: def.confidence,
+  }));
+}