@birdapi/velinstyle 1.2.1 → 1.2.2

package/cli/atelier-formats.js

@@ -0,0 +1,159 @@
+/**
+ * Framework integration shells for Atelier pulls.
+ * Blade/Vue/React are wrappers around vanilla showcase assets — not native rewrites.
+ */
+
+export const LIMITATION_EN = `## Limitation
+
+\`--format blade|vue|react\` writes an **integration shell** that mounts the original Atelier vanilla showcase (HTML/JS/CSS + Web Components). It does **not** rewrite the template into idiomatic Blade/Vue/React.
+
+Native framework blocks are **planned** for a later release / Velin Studio (not shipped).
+
+Atelier Library ≠ Velin Studio Builder.
+`;
+
+export const LIMITATION_DE = `## Einschränkung
+
+\`--format blade|vue|react\` erzeugt eine **Integrations-Shell** um das originale Vanilla-Showcase (HTML/JS/CSS + Web Components). Kein idiomatischer Rewrite.
+
+Native Framework-Bausteine sind **geplant** (spätere Version / Velin Studio — nicht shipped).
+
+Atelier Library ≠ Velin Studio Builder.
+`;
+
+const FORMATS = new Set(['html', 'blade', 'vue', 'react']);
+
+export function normalizeFormat(raw) {
+  const f = String(raw || 'html').toLowerCase().trim();
+  if (!FORMATS.has(f)) {
+    return { ok: false, error: `Unknown format "${raw}". Use: html | blade | vue | react (blade/vue/react = integration wrappers, not native rewrites).` };
+  }
+  return { ok: true, format: f };
+}
+
+/**
+ * @param {{ id: string, title?: string, assetDir: string, format: string }} opts
+ */
+export function emitFormatShell(opts) {
+  const { id, title = id, assetDir = '.', format } = opts;
+  const n = normalizeFormat(format);
+  if (!n.ok) return n;
+
+  const rel = !assetDir || assetDir === '.' ? '.' : assetDir.replace(/\\/g, '/').replace(/\/$/, '');
+  const appJs = rel === '.' ? './app.js' : `${rel}/app.js`;
+  const appCss = rel === '.' ? './app.css' : `${rel}/app.css`;
+
+  if (n.format === 'html') {
+    return {
+      ok: true,
+      format: 'html',
+      files: {},
+      note: 'html',
+    };
+  }
+
+  if (n.format === 'blade') {
+    const assetPath = rel === '.' ? `velin-atelier/${id}` : rel;
+    const blade = `{{-- VelinStyle Atelier wrapper for ${id} — vanilla showcase mount, not a native Blade rewrite --}}
+{{-- Limitation: integration shell only. Native framework blocks / Studio = planned. --}}
+@vite(['resources/css/app.css', 'resources/js/app.js'])
+<link rel="stylesheet" href="{{ asset('${assetPath}/app.css') }}">
+<div id="root" data-atelier-id="${id}" data-velin-atelier-mount></div>
+<script type="module" src="{{ asset('${assetPath}/app.js') }}"></script>
+`;
+    return {
+      ok: true,
+      format: 'blade',
+      files: {
+        [`${id}.blade.php`]: blade,
+      },
+    };
+  }
+
+  if (n.format === 'vue') {
+    const vue = `<!-- VelinStyle Atelier wrapper for ${id} — mounts vanilla showcase; not idiomatic Vue SFC rewrite -->
+<script setup>
+import { onMounted, ref } from 'vue';
+import '${appCss}';
+
+const root = ref(null);
+const title = ${JSON.stringify(title)};
+
+onMounted(async () => {
+  // Load original Atelier app.js (vanilla). Native Vue rewrite is planned later.
+  await import('${appJs}');
+});
+</script>
+
+<template>
+  <div>
+    <p class="velin-text-muted">Atelier {{ title }} (integration wrapper)</p>
+    <div id="root" ref="root" data-atelier-id="${id}" data-velin-atelier-mount></div>
+  </div>
+</template>
+`;
+    return {
+      ok: true,
+      format: 'vue',
+      files: {
+        [`${id}.vue`]: vue,
+      },
+    };
+  }
+
+  // react
+  const jsx = `/** VelinStyle Atelier wrapper for ${id} — mounts vanilla showcase; not a native JSX rewrite */
+import { useEffect, useRef } from 'react';
+import '${appCss}';
+
+/**
+ * Limitation: integration shell only. Native React blocks are planned / Studio later.
+ */
+export default function Atelier${id.replace(/[^a-zA-Z0-9]/g, '_')}() {
+  const rootRef = useRef(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      if (cancelled) return;
+      await import('${appJs}');
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  return (
+    <div>
+      <p>{${JSON.stringify(title)}} (Atelier integration wrapper)</p>
+      <div id="root" ref={rootRef} data-atelier-id="${id}" data-velin-atelier-mount />
+    </div>
+  );
+}
+`;
+  return {
+    ok: true,
+    format: 'react',
+    files: {
+      [`${id}.jsx`]: jsx,
+    },
+  };
+}
+
+/**
+ * @param {{ id: string, title?: string, format: string, sourceHint?: string }} opts
+ */
+export function buildPullReadme(opts) {
+  const { id, title = id, format, sourceHint = '' } = opts;
+  return `# Atelier pull: ${id}
+
+**Title:** ${title}
+**Format:** ${format}
+${sourceHint ? `**Source:** ${sourceHint}\n` : ''}
+Install CSS/WC: \`npm i @birdapi/velinstyle\` and point vendor/link stylesheets to \`node_modules/@birdapi/velinstyle/dist\`.
+
+${LIMITATION_EN}
+
+---
+
+${LIMITATION_DE}
+`;
+}

package/cli/atelier.js

@@ -0,0 +1,382 @@
+/**
+ * Atelier Library pull: resolve curated num/id → copy or HTTPS fetch showcase assets.
+ */
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+} from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { emitFormatShell, buildPullReadme, normalizeFormat } from './atelier-formats.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CATALOG_PATH = join(__dirname, 'atelier-catalog.json');
+const DEFAULT_BASE_URL = 'https://velinstyle.info/atelier/library/';
+const ASSET_NAMES = ['index.html', 'app.js', 'app.css'];
+
+/**
+ * @param {string} [catalogPath]
+ */
+export function loadCatalog(catalogPath = DEFAULT_CATALOG_PATH) {
+  const full = resolve(catalogPath);
+  if (!existsSync(full)) {
+    return { ok: false, error: `Catalog not found: ${full}`, items: [] };
+  }
+  const data = JSON.parse(readFileSync(full, 'utf-8'));
+  return { ok: true, items: data.items || [], meta: data };
+}
+
+/**
+ * Resolve query like "36", "036", "36-calendar", or "calendar" (unique suffix).
+ * SEO ids (e.g. 3600-…) are not matched by short number lookup.
+ * @param {string} query
+ * @param {{ catalogPath?: string, items?: object[] }} [opts]
+ */
+export function resolveAtelierEntry(query, opts = {}) {
+  const q = String(query || '').trim();
+  if (!q) return { ok: false, error: 'Empty atelier query' };
+
+  const items = opts.items || loadCatalog(opts.catalogPath).items;
+  if (!items?.length) return { ok: false, error: 'Atelier catalog is empty' };
+
+  // Exact id
+  const byId = items.find((it) => it.id === q);
+  if (byId) return { ok: true, entry: byId };
+
+  // Numeric: 36 / 036 → num pad match only (not 3600)
+  if (/^\d{1,3}$/.test(q)) {
+    const n = String(Number(q));
+    const entry = items.find((it) => String(Number(it.num)) === n);
+    if (entry) return { ok: true, entry };
+    return { ok: false, error: `Unknown atelier number "${q}". Try: velinstyle atelier list` };
+  }
+
+  // id prefix or slug contains
+  const lower = q.toLowerCase();
+  const matches = items.filter(
+    (it) => it.id.toLowerCase() === lower
+      || it.id.toLowerCase().startsWith(lower + '-')
+      || it.id.toLowerCase().endsWith('-' + lower)
+      || it.id.toLowerCase().includes('-' + lower),
+  );
+  if (matches.length === 1) return { ok: true, entry: matches[0] };
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      error: `Ambiguous "${q}": ${matches.slice(0, 8).map((m) => m.id).join(', ')}${matches.length > 8 ? '…' : ''}`,
+    };
+  }
+  return { ok: false, error: `Unknown atelier id "${q}". Try: velinstyle atelier list` };
+}
+
+/**
+ * @param {string} listStr comma-separated queries
+ * @param {{ catalogPath?: string, items?: object[] }} [opts]
+ */
+export function resolveAtelierList(listStr, opts = {}) {
+  const parts = String(listStr || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (!parts.length) return { ok: false, error: 'Empty --atelier list', entries: [] };
+  const entries = [];
+  for (const p of parts) {
+    const r = resolveAtelierEntry(p, opts);
+    if (!r.ok) return { ok: false, error: r.error, entries };
+    entries.push(r.entry);
+  }
+  return { ok: true, entries };
+}
+
+export function listAtelierEntries(opts = {}) {
+  const cat = opts.items ? { ok: true, items: opts.items } : loadCatalog(opts.catalogPath);
+  if (!cat.ok) return cat;
+  return { ok: true, items: cat.items };
+}
+
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+function libraryRootFromFrom(fromDir) {
+  const root = resolve(fromDir);
+  // Accept …/library or …/library/showcases or collection root with showcases/
+  if (existsSync(join(root, 'showcases'))) return root;
+  if (existsSync(join(root, '01-login')) || existsSync(join(root, '04-pricing'))) {
+    // already showcases dir
+    return dirname(root);
+  }
+  const parent = join(root, '..');
+  if (existsSync(join(parent, 'showcases'))) return parent;
+  return root;
+}
+
+function localShowcaseDir(libraryRoot, entry) {
+  const candidates = [
+    join(libraryRoot, 'showcases', entry.id),
+    join(libraryRoot, entry.id),
+    join(libraryRoot, 'showcases', entry.id.replace(/^0+/, '') || entry.id),
+  ];
+  for (const c of candidates) {
+    if (existsSync(join(c, 'index.html')) || existsSync(join(c, 'app.js'))) return c;
+  }
+  return null;
+}
+
+/**
+ * @param {object} entry
+ * @param {{ from?: string, baseUrl?: string }} opts
+ * @returns {Promise<{ ok: boolean, files?: Record<string,string>, error?: string, source?: string }>}
+ */
+export async function fetchShowcaseAssets(entry, opts = {}) {
+  const from = opts.from || process.env.VELINSTYLE_ATELIER_ROOT || '';
+  if (from) {
+    const lib = libraryRootFromFrom(from);
+    const dir = localShowcaseDir(lib, entry);
+    if (!dir) {
+      return { ok: false, error: `Local showcase not found for ${entry.id} under ${lib}` };
+    }
+    const files = {};
+    for (const name of ASSET_NAMES) {
+      const p = join(dir, name);
+      if (existsSync(p)) files[name] = readFileSync(p, 'utf-8');
+    }
+    if (!Object.keys(files).length) {
+      return { ok: false, error: `No assets in ${dir}` };
+    }
+    return { ok: true, files, source: `local:${dir}` };
+  }
+
+  const base = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/?$/, '/');
+  const urlBase = `${base}showcases/${entry.id}/`;
+  const files = {};
+  for (const name of ASSET_NAMES) {
+    const url = urlBase + name;
+    try {
+      const res = await fetch(url);
+      if (!res.ok) {
+        if (name === 'index.html') {
+          return { ok: false, error: `HTTP ${res.status} fetching ${url}` };
+        }
+        continue;
+      }
+      files[name] = await res.text();
+    } catch (err) {
+      return { ok: false, error: `Fetch failed ${url}: ${err.message}` };
+    }
+  }
+  if (!files['index.html'] && !files['app.js']) {
+    return { ok: false, error: `No assets at ${urlBase}` };
+  }
+  return { ok: true, files, source: urlBase };
+}
+
+/**
+ * Pull one atelier entry into output directory.
+ * @param {string} query
+ * @param {{
+ *   output?: string,
+ *   from?: string,
+ *   baseUrl?: string,
+ *   format?: string,
+ *   catalogPath?: string,
+ *   rewriteVendor?: string,
+ * }} opts
+ */
+export async function pullAtelier(query, opts = {}) {
+  const resolved = resolveAtelierEntry(query, { catalogPath: opts.catalogPath });
+  if (!resolved.ok) return resolved;
+  const { entry } = resolved;
+
+  const fmt = normalizeFormat(opts.format || 'html');
+  if (!fmt.ok) return fmt;
+
+  const fetched = await fetchShowcaseAssets(entry, {
+    from: opts.from,
+    baseUrl: opts.baseUrl,
+  });
+  if (!fetched.ok) return fetched;
+
+  const outRoot = resolve(opts.output || join(process.cwd(), 'velin-atelier', entry.id));
+  ensureDir(outRoot);
+
+  const files = { ...fetched.files };
+  if (opts.rewriteVendor) {
+    const vendor = opts.rewriteVendor.replace(/\\/g, '/').replace(/\/?$/, '/');
+    for (const key of Object.keys(files)) {
+      if (typeof files[key] !== 'string') continue;
+      files[key] = files[key]
+        .replace(/\.\.\/\.\.\/vendor\//g, vendor)
+        .replace(/\.\.\/vendor\//g, vendor);
+    }
+  }
+
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(join(outRoot, name), content, 'utf-8');
+  }
+
+  const shell = emitFormatShell({
+    id: entry.id,
+    title: entry.title,
+    assetDir: '.',
+    format: fmt.format,
+  });
+  if (!shell.ok) return shell;
+  for (const [name, content] of Object.entries(shell.files || {})) {
+    writeFileSync(join(outRoot, name), content, 'utf-8');
+  }
+
+  const readme = buildPullReadme({
+    id: entry.id,
+    title: entry.title,
+    format: fmt.format,
+    sourceHint: fetched.source,
+  });
+  writeFileSync(join(outRoot, 'README.md'), readme, 'utf-8');
+
+  return {
+    ok: true,
+    entry,
+    path: outRoot,
+    format: fmt.format,
+    source: fetched.source,
+    files: [...Object.keys(files), ...Object.keys(shell.files || {}), 'README.md'],
+  };
+}
+
+/**
+ * Build a composite HTML page that mounts multiple atelier showcases.
+ * @param {string[]} queries
+ * @param {{
+ *   output?: string,
+ *   from?: string,
+ *   baseUrl?: string,
+ *   catalogPath?: string,
+ *   assetsSubdir?: string,
+ * }} opts
+ */
+export async function composeAtelierPage(queries, opts = {}) {
+  const list = resolveAtelierList(Array.isArray(queries) ? queries.join(',') : String(queries), {
+    catalogPath: opts.catalogPath,
+  });
+  if (!list.ok) return list;
+
+  const outFile = opts.output
+    ? resolve(opts.output)
+    : resolve(process.cwd(), 'velin-atelier', 'compose.html');
+  const outDir = dirname(outFile);
+  const assetsSub = opts.assetsSubdir || 'atelier-assets';
+  const assetsRoot = join(outDir, assetsSub);
+  ensureDir(assetsRoot);
+
+  const sections = [];
+  const planSections = [];
+
+  for (const entry of list.entries) {
+    const fetched = await fetchShowcaseAssets(entry, {
+      from: opts.from,
+      baseUrl: opts.baseUrl,
+    });
+    if (!fetched.ok) return { ok: false, error: fetched.error, entry: entry.id };
+
+    const dest = join(assetsRoot, entry.id);
+    ensureDir(dest);
+    for (const [name, content] of Object.entries(fetched.files)) {
+      writeFileSync(join(dest, name), content, 'utf-8');
+    }
+
+    const rel = `${assetsSub}/${entry.id}`.replace(/\\/g, '/');
+    sections.push(`
+  <section class="velin-atelier-compose__block" data-atelier-id="${entry.id}" aria-label="${entry.title || entry.id}">
+    <h2 class="velin-atelier-compose__title">${entry.title || entry.id} <span class="velin-text-muted">#${entry.num}</span></h2>
+    <iframe class="velin-atelier-compose__frame" title="${entry.id}" src="${rel}/index.html" loading="lazy"></iframe>
+  </section>`);
+    planSections.push({
+      atelierId: entry.id,
+      num: entry.num,
+      title: entry.title,
+      href: entry.href,
+    });
+  }
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>VelinStyle Atelier compose (beta)</title>
+  <style>
+    .velin-atelier-compose__frame { width: 100%; min-height: 70vh; border: 1px solid #ccc; border-radius: 8px; }
+    .velin-atelier-compose__block { margin-block: 2rem; }
+  </style>
+</head>
+<body>
+  <!-- Generated by velinstyle scaffold --atelier (beta). Atelier Library compose — not Velin Studio. -->
+  <!-- Limitation: mounts original vanilla showcases; native Blade/Vue/React rewrites are planned. -->
+  <main class="velin-atelier-compose">
+    <header>
+      <h1>Atelier compose (beta)</h1>
+      <p>Composed from Library ids: ${list.entries.map((e) => e.id).join(', ')}. Studio Builder remains planned.</p>
+    </header>
+${sections.join('\n')}
+  </main>
+</body>
+</html>
+`;
+
+  ensureDir(outDir);
+  writeFileSync(outFile, html, 'utf-8');
+  writeFileSync(
+    join(outDir, 'README.md'),
+    buildPullReadme({
+      id: list.entries.map((e) => e.id).join('+'),
+      title: 'Atelier compose (beta)',
+      format: 'html',
+      sourceHint: 'scaffold --atelier',
+    }),
+    'utf-8',
+  );
+
+  return {
+    ok: true,
+    path: outFile,
+    entries: list.entries,
+    planSections,
+    mode: 'atelier-compose',
+    html,
+  };
+}
+
+/**
+ * Plan payload when --atelier is set.
+ * @param {string} listStr
+ * @param {{ catalogPath?: string, prompt?: string }} opts
+ */
+export function planFromAtelierList(listStr, opts = {}) {
+  const list = resolveAtelierList(listStr, { catalogPath: opts.catalogPath });
+  if (!list.ok) return list;
+  return {
+    ok: true,
+    analysis: {
+      intent: 'atelier-compose',
+      confidence: 'high',
+      pageId: 'atelier-compose',
+      prompt: opts.prompt || '',
+    },
+    plan: {
+      page: { id: 'atelier-compose', title: 'Atelier compose (beta)' },
+      sections: list.entries.map((e) => ({
+        id: e.id,
+        atelierId: e.id,
+        num: e.num,
+        title: e.title,
+        blueprint: null,
+        source: 'atelier-library',
+      })),
+      maturity: 'beta',
+      note: 'Composes Atelier Library showcases. Velin Studio Builder is planned — not shipped.',
+    },
+  };
+}

package/cli/blueprints/empty-state.html

@@ -1,5 +1,3 @@
-<section class="velin-p-8 velin-text-center" aria-labelledby="empty-title">
-  <h2 id="empty-title" class="velin-text-xl velin-font-bold velin-mbe-2">No items yet</h2>
-  <p class="velin-text-muted velin-mbe-4">Create your first entry to see it listed here.</p>
-  <button type="button" class="velin-btn velin-btn--primary">Create item</button>
-</section>
+<velin-empty-state heading="No items yet" description="Create your first entry to see it listed here.">
+  <button type="button" class="velin-btn velin-btn--primary" slot="actions">Create item</button>
+</velin-empty-state>

package/cli/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "1.2.2",
   "commands": [
     {
       "name": "init",
@@ -9,9 +9,15 @@
     },
     {
       "name": "build",
-      "summary": "Build custom CSS with selected layers from config",
-      "flags": ["--output", "-o", "--minify", "--preset"],
-      "example": "velinstyle build --preset lite -o ./lite.css"
+      "summary": "Build custom CSS with selected layers from config, or production output with --production",
+      "flags": ["--output", "-o", "--out", "--minify", "--preset", "--production", "--explain", "--watch", "--report", "--safelist"],
+      "example": "velinstyle build --production --explain -o ./dist/velin-production"
+    },
+    {
+      "name": "production",
+      "summary": "Content-aware production builder (CSS/JS/themes/icons/fonts/motion + report)",
+      "flags": ["--out", "-o", "--explain", "--watch", "--report", "--safelist", "--no-js", "--no-icons", "--no-themes", "--no-motion", "--no-minify"],
+      "example": "velinstyle production . --explain --report ./report.json"
     },
     {
       "name": "themes",
@@ -78,16 +84,23 @@
     },
     {
       "name": "scaffold",
-      "summary": "Plan-first page HTML or recipe fragment from natural language",
-      "flags": ["--output", "-o", "--json"],
+      "summary": "Plan-first page HTML, recipe fragment, or Atelier Library compose (--atelier, beta)",
+      "flags": ["--output", "-o", "--json", "--atelier", "--from", "--base-url"],
       "subcommands": ["list-intents"],
-      "example": "velinstyle scaffold \"Steuerberater Landingpage mit Kontakt\""
+      "example": "velinstyle scaffold --atelier 04,07 -o compose.html --from ./atelier/library"
     },
     {
       "name": "plan",
-      "summary": "Emit page plan JSON from a prompt (no HTML)",
-      "flags": ["--output", "-o", "--json"],
-      "example": "velinstyle plan \"SaaS landing with pricing\""
+      "summary": "Emit page plan JSON from a prompt or --atelier Library ids (beta)",
+      "flags": ["--output", "-o", "--json", "--atelier"],
+      "example": "velinstyle plan --atelier 04,07"
+    },
+    {
+      "name": "atelier",
+      "summary": "Pull curated Atelier Library showcase by number/id; blade/vue/react = wrappers only",
+      "flags": ["--output", "-o", "--format", "--from", "--base-url", "--rewrite-vendor"],
+      "subcommands": ["list"],
+      "example": "velinstyle atelier 36 -o ./velin-atelier/36-calendar --format html"
     },
     {
       "name": "review",

package/cli/docgen/extract-cli.js

@@ -9,7 +9,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 export const REGISTERED_COMMANDS = [
   'init', 'build', 'themes', 'add', 'icons', 'blueprint', 'create', 'serve', 'doctor', 'check', 'tokens',
   'scan', 'prefix', 'scaffold', 'plan', 'review', 'layout', 'perf', 'docs', 'meta',
-  'search', 'skills', 'workflow', 'wc',
+  'search', 'skills', 'workflow', 'wc', 'production', 'atelier',
 ];
 
 export function loadCliManifest() {