orbital-ds 0.4.0 → 0.6.0

package/scripts/doctor.mjs

@@ -1,224 +1,237 @@
-#!/usr/bin/env node
-/**
- * orbital-ds doctor — comprueba que el sistema se cumple.
- *
- *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
- *      contract.json y la fuente `--ds-font-sans`. En .dark solo avisa.
- *   2. REPETIDOS: ninguna variable se define dos veces en el mismo bloque.
- *   3. SOMBRAS: «sin sombra» es `0 0 #0000`, nunca `none` (una variable con
- *      `none` invalida todo el box-shadow, anillo de foco incluido).
- *   4. FUGAS: el tema base (contract.baseTheme) está aplicado siempre; todo tema
- *      con ámbito debe definir cada `--ds-*` que defina el base, o su valor se
- *      colaría al cambiar de tema.
- *   5. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
- *      duraciones ni sombras a mano; todo sale de tokens.
- *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
- *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
- *
- * Uso:
- *   node scripts/doctor.mjs                 # temas y componentes del paquete
- *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (repetidos)
- *
- * Sale con código 1 si hay errores (los avisos no fallan).
- */
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
-
-const errors = [];
-const warnings = [];
-const read = (p) => readFileSync(p, 'utf8');
-const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
-
-/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
-function blocks(css, selectorRe) {
-  const out = [];
-  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
-  let m;
-  while ((m = re.exec(css))) {
-    let depth = 1;
-    let i = re.lastIndex;
-    const start = i;
-    while (i < css.length && depth > 0) {
-      if (css[i] === '{') depth++;
-      else if (css[i] === '}') depth--;
-      i++;
-    }
-    out.push(css.slice(start, i - 1));
-    re.lastIndex = i;
-  }
-  return out;
-}
-
-/** Declaraciones `--x: valor;` del nivel superior de un bloque (no las anidadas). */
-function declarations(body) {
-  let depth = 0;
-  let top = '';
-  for (const ch of body) {
-    if (ch === '{') depth++;
-    else if (ch === '}') depth--;
-    else if (depth === 0) top += ch;
-  }
-  return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
-}
-
-/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
-function knownDsVars() {
-  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
-  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
-}
-
-// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
-for (const t of contract.brand?.tokens ?? []) {
-  const inContract =
-    contract.root.includes(t.name) ||
-    contract.fonts.includes(t.name) ||
-    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
-  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
-}
-
-const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
-
-function checkTheme(file, name) {
-  const label = `tema ${name}`;
-  const css = stripComments(read(file));
-  const roots = blocks(css, /(?:^|[\s}])\:root/);
-  const darks = blocks(css, /(?:^|[\s}])\.dark/);
-
-  const rootDecl = roots.flatMap(declarations);
-  const darkDecl = darks.flatMap(declarations);
-  const rootVars = new Set(rootDecl.map((d) => d.name));
-  const darkVars = new Set(darkDecl.map((d) => d.name));
-  themeInfo[name] = { rootVars, darkVars };
-
-  for (const t of contract.root) {
-    if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
-  }
-  for (const f of contract.fonts) {
-    if (!rootVars.has(`--${f}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
-  }
-  if (darks.length) {
-    for (const t of contract.dark.avisar_si_falta) {
-      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
-    }
-  } else {
-    warnings.push(`${label}: no define piel .dark`);
-  }
-
-  // Repetidos (solo declaraciones del nivel superior de cada bloque)
-  for (const [kind, list] of [[':root', roots], ['.dark', darks]]) {
-    list.forEach((body, idx) => {
-      const seen = new Map();
-      for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
-      for (const [v, n] of seen) {
-        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${kind} (#${idx + 1})`);
-      }
-    });
-  }
-
-  // Sombras: `none` invalida el box-shadow
-  for (const d of [...rootDecl, ...darkDecl]) {
-    if (/^--ds-(?:shadow|sidebar-shadow)/.test(d.name) && /^none$/i.test(d.value)) {
-      errors.push(`${label}: ${d.name}: none — usa «0 0 #0000» (none invalida todo el box-shadow)`);
-    }
-  }
-}
-
-// 1+2+3) temas
-const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
-const themeFiles = readdirSync(themesDir).filter(
-  (n) => n.endsWith('.css') && !n.endsWith('.fonts.css') && !n.endsWith('.scoped.css'),
-);
-for (const f of themeFiles) checkTheme(join(themesDir, f), f.replace(/\.css$/, ''));
-
-// 4) fugas desde el tema base
-const base = contract.baseTheme;
-if (base && themeInfo[base]) {
-  const baseDs = [...themeInfo[base].rootVars].filter((v) => v.startsWith('--ds-'));
-  for (const [name, info] of Object.entries(themeInfo)) {
-    if (name === base) continue;
-    for (const v of baseDs) {
-      if (!info.rootVars.has(v)) {
-        errors.push(`tema ${name}: no define ${v}, que sí define el tema base «${base}» — su valor se colaría al cambiar de tema`);
-      }
-    }
-  }
-}
-
-// CSS de una app (opcional)
-const cssArgIdx = process.argv.indexOf('--css');
-if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
-  const css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
-  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
-    const seen = new Map();
-    for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
-    for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
-    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
-    const known = knownDsVars();
-    for (const d of declarations(body)) {
-      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
-        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
-      }
-    }
-  });
-}
-
-// 5) valores fijos en componentes
-const NO_HARDCODE = [
-  { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
-  { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
-  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
-  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
-  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
-  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
-  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
-  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
-  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
-];
-
-const uiDir = join(ROOT, 'src/ui');
-if (existsSync(uiDir)) {
-  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
-    const lines = read(join(uiDir, f)).split(/\r?\n/);
-    lines.forEach((line, i) => {
-      const code = line.replace(/\/\/.*$/, '');
-      for (const rule of NO_HARDCODE) {
-        if (rule.skip?.includes(f)) continue;
-        const hits = code.match(rule.re);
-        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
-      }
-    });
-  }
-}
-
-// 6) API pública frente a la huella commiteada
-const manifestPath = join(ROOT, 'components.manifest.json');
-if (existsSync(manifestPath) && existsSync(uiDir)) {
-  const { buildManifest } = await import('./manifest.mjs');
-  const before = JSON.parse(read(manifestPath)).components;
-  const now = buildManifest().components;
-  for (const [name, comp] of Object.entries(before)) {
-    if (!now[name]) {
-      errors.push(`API pública: desaparece el componente «${name}» (¿versión mayor? regenera con pnpm manifest)`);
-      continue;
-    }
-    for (const e of comp.exports) {
-      if (!now[name].exports.includes(e)) {
-        errors.push(`API pública: «${name}» ya no exporta ${e} (¿versión mayor? regenera con pnpm manifest)`);
-      }
-    }
-  }
-  const added = Object.keys(now).filter((n) => !before[n]);
-  if (added.length) warnings.push(`API pública: componentes nuevos sin registrar en el manifiesto (${added.join(', ')}); ejecuta pnpm manifest`);
-}
-
-for (const w of warnings) console.log(`AVISO  ${w}`);
-for (const e of errors) console.log(`ERROR  ${e}`);
-if (errors.length) {
-  console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
-  process.exit(1);
-}
-console.log(`doctor: contrato, repetidos, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);
+#!/usr/bin/env node
+/**
+ * orbital-ds doctor — comprueba que el sistema se cumple.
+ *
+ *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
+ *      contract.json y la fuente `--ds-font-sans`. En .dark solo avisa.
+ *   2. REPETIDOS: ninguna variable se define dos veces en el mismo bloque.
+ *   3. SOMBRAS: «sin sombra» es `0 0 #0000`, nunca `none` (una variable con
+ *      `none` invalida todo el box-shadow, anillo de foco incluido).
+ *   4. FUGAS: el tema base (contract.baseTheme) está aplicado siempre; todo tema
+ *      con ámbito debe definir cada `--ds-*` que defina el base, o su valor se
+ *      colaría al cambiar de tema.
+ *   5. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
+ *      duraciones ni sombras a mano; todo sale de tokens.
+ *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
+ *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
+ *
+ * Uso:
+ *   node scripts/doctor.mjs                 # temas y componentes del paquete
+ *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (repetidos)
+ *
+ * Sale con código 1 si hay errores (los avisos no fallan).
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
+
+const errors = [];
+const warnings = [];
+const read = (p) => readFileSync(p, 'utf8');
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
+function blocks(css, selectorRe) {
+  const out = [];
+  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    const start = i;
+    while (i < css.length && depth > 0) {
+      if (css[i] === '{') depth++;
+      else if (css[i] === '}') depth--;
+      i++;
+    }
+    out.push(css.slice(start, i - 1));
+    re.lastIndex = i;
+  }
+  return out;
+}
+
+/** Declaraciones `--x: valor;` del nivel superior de un bloque (no las anidadas). */
+function declarations(body) {
+  let depth = 0;
+  let top = '';
+  for (const ch of body) {
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    else if (depth === 0) top += ch;
+  }
+  return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
+}
+
+/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
+function knownDsVars() {
+  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
+  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+}
+
+// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
+for (const t of contract.brand?.tokens ?? []) {
+  const inContract =
+    contract.root.includes(t.name) ||
+    contract.fonts.includes(t.name) ||
+    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
+  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
+}
+
+const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
+
+function checkTheme(file, name) {
+  const label = `tema ${name}`;
+  const css = stripComments(read(file));
+  const roots = blocks(css, /(?:^|[\s}])\:root/);
+  const darks = blocks(css, /(?:^|[\s}])\.dark/);
+
+  const rootDecl = roots.flatMap(declarations);
+  const darkDecl = darks.flatMap(declarations);
+  const rootVars = new Set(rootDecl.map((d) => d.name));
+  const darkVars = new Set(darkDecl.map((d) => d.name));
+  themeInfo[name] = { rootVars, darkVars };
+
+  for (const t of contract.root) {
+    if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
+  }
+  for (const f of contract.fonts) {
+    if (!rootVars.has(`--${f}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
+  }
+  if (darks.length) {
+    for (const t of contract.dark.avisar_si_falta) {
+      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
+    }
+  } else {
+    warnings.push(`${label}: no define piel .dark`);
+  }
+
+  // Repetidos (solo declaraciones del nivel superior de cada bloque)
+  for (const [kind, list] of [[':root', roots], ['.dark', darks]]) {
+    list.forEach((body, idx) => {
+      const seen = new Map();
+      for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
+      for (const [v, n] of seen) {
+        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${kind} (#${idx + 1})`);
+      }
+    });
+  }
+
+  // Sombras: `none` invalida el box-shadow
+  for (const d of [...rootDecl, ...darkDecl]) {
+    if (/^--ds-(?:shadow|sidebar-shadow)/.test(d.name) && /^none$/i.test(d.value)) {
+      errors.push(`${label}: ${d.name}: none — usa «0 0 #0000» (none invalida todo el box-shadow)`);
+    }
+  }
+}
+
+// 1+2+3) temas
+const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
+const themeFiles = readdirSync(themesDir).filter(
+  (n) => n.endsWith('.css') && !n.endsWith('.fonts.css') && !n.endsWith('.scoped.css'),
+);
+for (const f of themeFiles) checkTheme(join(themesDir, f), f.replace(/\.css$/, ''));
+
+// 1b) documentación de cada tema: guía de diseño (.guide.md) + ficha legible por máquina (.meta.json)
+const META_CLAVES = ['name', 'label', 'essence', 'signature', 'fonts', 'palette', 'references', 'status', 'guide'];
+for (const f of themeFiles) {
+  const t = f.replace(/\.css$/, '');
+  if (!existsSync(join(themesDir, `${t}.guide.md`))) errors.push(`tema ${t}: falta ${t}.guide.md (guía de diseño)`);
+  const metaPath = join(themesDir, `${t}.meta.json`);
+  if (!existsSync(metaPath)) { errors.push(`tema ${t}: falta ${t}.meta.json (ficha del tema)`); continue; }
+  let meta;
+  try { meta = JSON.parse(read(metaPath)); } catch { errors.push(`tema ${t}: ${t}.meta.json no es JSON válido`); continue; }
+  for (const k of META_CLAVES) if (!(k in meta)) errors.push(`tema ${t}: ${t}.meta.json no define «${k}»`);
+  if (meta.name !== t) errors.push(`tema ${t}: ${t}.meta.json tiene name «${meta.name}»`);
+}
+
+// 4) fugas desde el tema base
+const base = contract.baseTheme;
+if (base && themeInfo[base]) {
+  const baseDs = [...themeInfo[base].rootVars].filter((v) => v.startsWith('--ds-'));
+  for (const [name, info] of Object.entries(themeInfo)) {
+    if (name === base) continue;
+    for (const v of baseDs) {
+      if (!info.rootVars.has(v)) {
+        errors.push(`tema ${name}: no define ${v}, que sí define el tema base «${base}» — su valor se colaría al cambiar de tema`);
+      }
+    }
+  }
+}
+
+// CSS de una app (opcional)
+const cssArgIdx = process.argv.indexOf('--css');
+if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
+  const css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
+  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
+    const seen = new Map();
+    for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
+    for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
+    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
+    const known = knownDsVars();
+    for (const d of declarations(body)) {
+      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
+        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
+      }
+    }
+  });
+}
+
+// 5) valores fijos en componentes
+const NO_HARDCODE = [
+  { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
+  { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
+  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
+  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
+  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
+  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
+  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
+  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
+  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
+];
+
+const uiDir = join(ROOT, 'src/ui');
+if (existsSync(uiDir)) {
+  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
+    const lines = read(join(uiDir, f)).split(/\r?\n/);
+    lines.forEach((line, i) => {
+      const code = line.replace(/\/\/.*$/, '');
+      for (const rule of NO_HARDCODE) {
+        if (rule.skip?.includes(f)) continue;
+        const hits = code.match(rule.re);
+        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
+      }
+    });
+  }
+}
+
+// 6) API pública frente a la huella commiteada
+const manifestPath = join(ROOT, 'components.manifest.json');
+if (existsSync(manifestPath) && existsSync(uiDir)) {
+  const { buildManifest } = await import('./manifest.mjs');
+  const before = JSON.parse(read(manifestPath)).components;
+  const now = buildManifest().components;
+  for (const [name, comp] of Object.entries(before)) {
+    if (!now[name]) {
+      errors.push(`API pública: desaparece el componente «${name}» (¿versión mayor? regenera con pnpm manifest)`);
+      continue;
+    }
+    for (const e of comp.exports) {
+      if (!now[name].exports.includes(e)) {
+        errors.push(`API pública: «${name}» ya no exporta ${e} (¿versión mayor? regenera con pnpm manifest)`);
+      }
+    }
+  }
+  const added = Object.keys(now).filter((n) => !before[n]);
+  if (added.length) warnings.push(`API pública: componentes nuevos sin registrar en el manifiesto (${added.join(', ')}); ejecuta pnpm manifest`);
+}
+
+for (const w of warnings) console.log(`AVISO  ${w}`);
+for (const e of errors) console.log(`ERROR  ${e}`);
+if (errors.length) {
+  console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
+  process.exit(1);
+}
+console.log(`doctor: contrato, repetidos, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);

package/scripts/init.mjs

@@ -1,55 +1,89 @@
-#!/usr/bin/env node
-/**
- * orbital-ds-init — crea el fichero de MARCA de una app.
- *
- *   pnpm exec orbital-ds-init            # crea src/brand.css si no existe
- *   pnpm exec orbital-ds-init --out app/brand.css
- *
- * NUNCA sobrescribe un fichero existente. Ese fichero es de la app: ninguna
- * actualización de orbital-ds lo toca, y se importa DESPUÉS del tema para que gane.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const contract = JSON.parse(readFileSync(resolve(ROOT, 'contract.json'), 'utf8'));
-
-const outIdx = process.argv.indexOf('--out');
-const out = resolve(outIdx > -1 && process.argv[outIdx + 1] ? process.argv[outIdx + 1] : 'src/brand.css');
-
-if (existsSync(out)) {
-  console.log(`Ya existe ${out}: no se toca (es de tu app).`);
-  process.exit(0);
-}
-
-const lines = contract.brand.tokens.map(
-  (t) => `  /* --${t.name}: ${t.example}; */  /* ${t.about} */`,
-);
-
-const css = `/*
- * MARCA de la app — fichero TUYO.
- *
- * Ninguna actualización de orbital-ds lo toca. Se importa DESPUÉS del tema, así que
- * lo que pongas aquí gana. Si no defines nada, se aplica el valor estándar del tema.
- *
- * Estas variables son el grupo estable de «lo que una marca suele cambiar»: renombrar
- * o quitar una de ellas es una versión MAYOR de orbital-ds, con aviso previo.
- * Descomenta solo lo que necesites y cambia el valor.
- *
- * Cambia el color principal TODO junto: primary, ring, link, brand, sidebar-primary y
- * chart-1 deben ir a la par (y comprueba el contraste del texto sobre ellos).
- */
-:root {
-${lines.join('\n')}
-}
-
-/* Piel oscura: solo si tu marca necesita valores distintos en oscuro. */
-.dark {
-  /* --primary: ...; */
-}
-`;
-
-mkdirSync(dirname(out), { recursive: true });
-writeFileSync(out, css);
-console.log(`Creado ${out}.\n\nImpórtalo DESPUÉS del tema, en el CSS de tu app:\n\n  @import 'orbital-ds/themes/<tema>.css';\n  @import './brand.css';\n`);
+#!/usr/bin/env node
+/**
+ * orbital-ds-init — crea el fichero de MARCA de una app.
+ *
+ *   pnpm exec orbital-ds-init            # crea src/brand.css si no existe
+ *   pnpm exec orbital-ds-init --out app/brand.css
+ *
+ * NUNCA sobrescribe un fichero existente. Ese fichero es de la app: ninguna
+ * actualización de orbital-ds lo toca, y se importa DESPUÉS del tema para que gane.
+ *
+ * DESIGN.md: orbital-ds NO lo crea. Si la app ya tiene uno (`./DESIGN.md` o
+ * `--design ruta`), añade —o actualiza— solo un bloque delimitado por marcas
+ * `<!-- orbital-ds:start -->` … `<!-- orbital-ds:end -->`; el resto no se toca.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(resolve(ROOT, 'contract.json'), 'utf8'));
+
+const outIdx = process.argv.indexOf('--out');
+const out = resolve(outIdx > -1 && process.argv[outIdx + 1] ? process.argv[outIdx + 1] : 'src/brand.css');
+
+const brandExiste = existsSync(out);
+if (brandExiste) console.log(`Ya existe ${out}: no se toca (es de tu app).`);
+
+if (!brandExiste) {
+const lines = contract.brand.tokens.map(
+  (t) => `  /* --${t.name}: ${t.example}; */  /* ${t.about} */`,
+);
+
+const css = `/*
+ * MARCA de la app — fichero TUYO.
+ *
+ * Ninguna actualización de orbital-ds lo toca. Se importa DESPUÉS del tema, así que
+ * lo que pongas aquí gana. Si no defines nada, se aplica el valor estándar del tema.
+ *
+ * Estas variables son el grupo estable de «lo que una marca suele cambiar»: renombrar
+ * o quitar una de ellas es una versión MAYOR de orbital-ds, con aviso previo.
+ * Descomenta solo lo que necesites y cambia el valor.
+ *
+ * Cambia el color principal TODO junto: primary, ring, link, brand, sidebar-primary y
+ * chart-1 deben ir a la par (y comprueba el contraste del texto sobre ellos).
+ */
+:root {
+${lines.join('\n')}
+}
+
+/* Piel oscura: solo si tu marca necesita valores distintos en oscuro. */
+.dark {
+  /* --primary: ...; */
+}
+`;
+
+mkdirSync(dirname(out), { recursive: true });
+writeFileSync(out, css);
+console.log(`Creado ${out}.\n\nImpórtalo DESPUÉS del tema, en el CSS de tu app:\n\n  @import 'orbital-ds/themes/<tema>.css';\n  @import './brand.css';\n`);
+}
+
+// ── DESIGN.md de la app: bloque adicional, nunca el fichero entero ───────────────
+const designIdx = process.argv.indexOf('--design');
+const design = resolve(designIdx > -1 && process.argv[designIdx + 1] ? process.argv[designIdx + 1] : 'DESIGN.md');
+if (existsSync(design)) {
+  const INI = '<!-- orbital-ds:start -->';
+  const FIN = '<!-- orbital-ds:end -->';
+  const bloque = `${INI}
+## Sistema de diseño (orbital-ds)
+
+Bloque gestionado por \`orbital-ds-init\`; lo de fuera de las marcas es de la app y no se toca.
+
+- Reglas de uso: \`node_modules/orbital-ds/AGENTS.md\`
+- Contrato de tokens: \`orbital-ds/contract.json\` · componentes: \`orbital-ds/components.manifest.json\`
+- Cada tema trae su guía (\`orbital-ds/themes/<tema>.guide.md\`) y su ficha (\`<tema>.meta.json\`).
+- La marca de la app va en \`brand.css\` (importado después del tema), nunca editando el paquete.
+- Comprobación: \`pnpm exec orbital-ds-doctor\`
+${FIN}`;
+  const actual = readFileSync(design, 'utf8');
+  let nuevo;
+  if (actual.includes(INI) && actual.includes(FIN)) {
+    nuevo = actual.slice(0, actual.indexOf(INI)) + bloque + actual.slice(actual.indexOf(FIN) + FIN.length);
+  } else {
+    nuevo = `${actual.replace(/\s*$/, '')}\n\n${bloque}\n`;
+  }
+  if (nuevo !== actual) {
+    writeFileSync(design, nuevo);
+    console.log(`Actualizado el bloque de orbital-ds en ${design} (el resto no se toca).`);
+  } else console.log(`${design}: el bloque de orbital-ds ya está al día.`);
+}