orbital-ds 0.13.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/scripts/cli.mjs CHANGED
@@ -1,370 +1,370 @@
1
- #!/usr/bin/env node
2
- /**
3
- * orbital-ds — una sola orden para todo:
4
- *
5
- * orbital-ds menú (¿qué quieres hacer?)
6
- * orbital-ds init [opciones] configuración inicial: tema, colores y extras (= orbital-ds-init)
7
- * orbital-ds theme [tema] cambiar de tema conservando tu marca y tus extras
8
- * orbital-ds doctor [opc.] comprobar contrato, contraste y marca (= orbital-ds-doctor)
9
- * orbital-ds i18n [opc.] textos de orbital-ds en los idiomas de la app (= orbital-ds-i18n)
10
- * orbital-ds help esta ayuda
11
- *
12
- * Las órdenes sueltas (orbital-ds-init, -doctor, -i18n) siguen funcionando: son atajos.
13
- */
14
- import { existsSync, readdirSync, readFileSync } from 'node:fs';
15
- import { dirname, join, resolve } from 'node:path';
16
- import { fileURLToPath } from 'node:url';
17
- import { spawnSync } from 'node:child_process';
18
-
19
- import { detectarCssApp, yaInstalado } from './setup.mjs';
20
- import { estadoSkill, instalarSkill, raizApp, SKILL_NAME } from './skill.mjs';
21
-
22
- const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
23
- const [orden, ...resto] = process.argv.slice(2);
24
- const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
25
- const temasDir = existsSync(join(ROOT, 'src/themes')) ? join(ROOT, 'src/themes') : join(ROOT, 'dist/themes');
26
- /** Fichas de los temas que trae el paquete. */
27
- const temas = () =>
28
- readdirSync(temasDir)
29
- .filter((f) => f.endsWith('.meta.json'))
30
- .map((f) => JSON.parse(readFileSync(join(temasDir, f), 'utf8')));
31
-
32
- /** Ejecuta otro script del paquete con los mismos stdin/stdout (interactivo incluido). */
33
- function ejecutar(script, args) {
34
- const r = spawnSync(process.execPath, [join(ROOT, 'scripts', script), ...args], { stdio: 'inherit' });
35
- process.exit(r.status ?? 1);
36
- }
37
-
38
- const AYUDA = {
39
- general: `orbital-ds ${version} — sistema de diseño: temas, componentes y herramientas
40
-
41
- Uso: orbital-ds <orden> [opciones] (sin orden, un menú)
42
-
43
- Órdenes
44
- init configuración inicial: tema, colores y extras (asistente)
45
- theme cambiar de tema conservando tu marca y tus extras
46
- doctor comprobar contrato, contraste, pesos y marca
47
- i18n textos de orbital-ds en los idiomas de la app
48
- context resumen de esta app para un agente: tema, marca, componentes y patrones
49
- skill instala o refresca el diseñador de orbital-ds para Claude Code
50
- help esta ayuda · orbital-ds help <orden> para el detalle
51
-
52
- Ejemplos
53
- orbital-ds menú
54
- orbital-ds init asistente paso a paso
55
- orbital-ds theme fractalia pasar a fractalia
56
- orbital-ds doctor --css src/brand.css comprobar tu marca
57
-
58
- Desde un script de package.json: pnpm exec orbital-ds <orden> (o npx orbital-ds <orden>).
59
- Las órdenes antiguas (orbital-ds-init, orbital-ds-doctor, orbital-ds-i18n) siguen valiendo.`,
60
-
61
- init: `orbital-ds init — configuración inicial de la app
62
-
63
- Sin opciones abre el asistente: 1) tema, 2) colores (fiel, solo primario o marca completa;
64
- primario y, si quieres, secundario; ves la paleta y el contraste), 3) extras (animaciones,
65
- Motion, gráficos, tablas, idiomas) y 4) resumen antes de escribir nada. Es la configuración
66
- INICIAL: todo se cambia después en src/brand.css o volviendo a ejecutarlo.
67
-
68
- Sin preguntas (scripts / CI)
69
- --theme <tema> qratia, fractalia, tactile, zyro, friendly, twitter
70
- --mode <modo> faithful (tema tal cual) · primary (solo tu color) · full (paleta entera)
71
- --primary <color> #1D63D8, rgb(), hsl() u oklch()
72
- --secondary <color> serie 2 de los gráficos y gesto del tema
73
- --connect [--css <f>] conecta el CSS de la app (imports en orden)
74
- --animations activa las animaciones del tema (orbital-ds/motion.css)
75
- --motion --charts --tables instala Motion, ECharts o TanStack Table
76
- --i18n rellena el espacio «orbital» de los JSON de idioma
77
- --update reescribe el bloque generado de brand.css
78
- --dry-run enseña el resultado sin escribir nada
79
- --out <fichero> fichero de marca (por defecto src/brand.css)
80
-
81
- Ejemplos
82
- orbital-ds init --theme fractalia --connect --animations
83
- orbital-ds init --theme qratia --mode primary --primary "#0A7D4F" --connect --charts`,
84
-
85
- theme: `orbital-ds theme [tema] — cambiar de tema
86
-
87
- Cambia el import del tema en el CSS de la app y conserva lo tuyo:
88
- - si tu marca se generó desde un color, la recalcula para el tema nuevo (mismo color y modo);
89
- - si el tema nuevo es de un sistema corporativo (fractalia), se usa fiel;
90
- - si tenías las animaciones activas, siguen activas.
91
- Sin tema, pregunta a cuál cambiar.
92
-
93
- Ejemplos
94
- orbital-ds theme elegir de la lista
95
- orbital-ds theme tactile`,
96
-
97
- doctor: `orbital-ds doctor — comprobar
98
-
99
- orbital-ds doctor --css src/brand.css tu marca: variables que existen, contraste AA,
100
- pesos de letra cargados
101
- orbital-ds doctor --ui src tus vistas no se salen del sistema: colores, medidas y
102
- valores arbitrarios, paleta de Tailwind, !important,
103
- controles nativos sueltos
104
- --aaa mide también el objetivo AAA del texto
105
-
106
- Va bien en el verify de la app: "check:ds": "orbital-ds doctor --css src/brand.css --ui src"`,
107
-
108
- context: `orbital-ds context — lo que un agente necesita saber de ESTA app
109
-
110
- Imprime: versión de orbital-ds, tema activo (esencia, gesto, movimiento, excepciones), cómo está la marca,
111
- extras activos, componentes con sus notas de uso, patrones del diseñador y dónde está la documentación.
112
- Lo lee el skill «orbital-ds-designer» antes de diseñar, y vale para cualquier agente.
113
-
114
- orbital-ds context en texto (markdown)
115
- orbital-ds context --json en JSON`,
116
-
117
- skill: `orbital-ds skill — diseñador de orbital-ds para Claude Code
118
-
119
- Instala (o refresca) el skill «orbital-ds-designer» en la raíz de la app: .claude/skills/orbital-ds-designer/.
120
- Es fino: las reglas largas se leen de node_modules/orbital-ds/docs/designer/, así que al actualizar orbital-ds
121
- ya trabaja con lo nuevo. Lleva la versión estampada; lo que añadas DESPUÉS de su bloque se conserva.
122
-
123
- orbital-ds skill instala o refresca
124
- orbital-ds skill --check comprueba (para el verify): falla si falta o es de otra versión
125
- orbital-ds skill --print enseña el contenido sin escribir nada`,
126
-
127
- i18n: `orbital-ds i18n — textos de orbital-ds en tus idiomas
128
-
129
- orbital-ds i18n rellena el espacio «orbital» de cada JSON (sin pisar lo tuyo)
130
- orbital-ds i18n --check solo comprueba (para el verify): falla si falta algo
131
- --dir <carpeta> carpeta de los JSON (por defecto src/i18n/locales, src/locales…)
132
- --ns <nombre> espacio de nombres (por defecto orbital)
133
-
134
- Añadir un idioma (p. ej. ru): crea ru.json, ejecuta orbital-ds i18n y traduce lo que liste.`,
135
- };
136
-
137
- function ayuda(tema = 'general') {
138
- console.log(AYUDA[tema] ?? AYUDA.general);
139
- }
140
-
141
- /** Lo que hay hoy en la app: tema importado, marca generada (primario, modo) y animaciones. */
142
- /** Lo que falta en la raíz de la app para que las piezas de orbital-ds funcionen del todo. */
143
- function avisosIntegracion(estado) {
144
- const src = resolve('src');
145
- let codigo = '';
146
- const leer = (d) => {
147
- if (!existsSync(d)) return;
148
- for (const n of readdirSync(d, { withFileTypes: true })) {
149
- if (n.name === 'node_modules' || n.name.startsWith('.')) continue;
150
- const p = join(d, n.name);
151
- if (n.isDirectory()) leer(p);
152
- // Sin comentarios: nombrar <Toaster /> en un comentario no cuenta como tenerlo.
153
- else if (/\.(tsx|jsx|ts|js)$/.test(n.name)) codigo += readFileSync(p, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
154
- }
155
- };
156
- leer(src);
157
- const avisos = [];
158
- if (!estado.tema) avisos.push('El CSS de la app no importa ningún tema: ejecuta orbital-ds init (o orbital-ds theme).');
159
- if (codigo && !/DsI18nProvider/.test(codigo)) avisos.push('No hay <DsI18nProvider> en la raíz: los textos de orbital-ds salen en inglés (orbital-ds/ui/i18n-provider).');
160
- if (codigo && /\btoast\b/.test(codigo) && !/<Toaster\b/.test(codigo)) avisos.push('Se usa toast pero no hay <Toaster /> en la raíz: los avisos no se verán (orbital-ds/ui/toast).');
161
- if (codigo && /useDsMotion|DsMotionProvider/.test(codigo) && !yaInstalado('motion')) avisos.push('Se usa Motion (useDsMotion/DsMotionProvider) pero el paquete motion no está instalado.');
162
- if (codigo && /useDsMotion/.test(codigo) && !/DsMotionProvider/.test(codigo)) avisos.push('Se usa useDsMotion() sin <DsMotionProvider> en la raíz: envuelve la app para que todo motion.* use el ritmo del tema.');
163
- return avisos;
164
- }
165
-
166
- /** orbital-ds context: el estado real de la app, para un agente (texto o JSON). */
167
- function contexto(json) {
168
- const estado = estadoApp();
169
- const ficha = temas().find((t) => t.name === estado.tema) ?? null;
170
- const manifest = JSON.parse(readFileSync(join(ROOT, 'components.manifest.json'), 'utf8'));
171
- const patronesMd = join(ROOT, 'docs', 'designer', 'patrones.md');
172
- const patrones = existsSync(patronesMd) ? [...readFileSync(patronesMd, 'utf8').matchAll(/^## (P\d+ · .+)$/gm)].map((m) => m[1].trim()) : [];
173
- const brand = resolve('src/brand.css');
174
- const brandVars = existsSync(brand)
175
- ? [...new Set([...readFileSync(brand, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/(--[\w-]+)\s*:/g)].map((m) => m[1]))]
176
- : [];
177
- const docs = 'node_modules/orbital-ds';
178
- const datos = {
179
- version,
180
- tema: ficha
181
- ? {
182
- nombre: ficha.name,
183
- etiqueta: ficha.label,
184
- esencia: ficha.essence,
185
- gesto: ficha.signature ?? [],
186
- movimiento: ficha.motion?.about ?? null,
187
- animaciones: ficha.motion?.auto ?? null,
188
- marca: ficha.branding ?? 'full',
189
- excepciones: ficha.a11y?.exceptions ?? [],
190
- guia: `${docs}/dist/themes/${ficha.name}.guide.md`,
191
- }
192
- : null,
193
- marca: estado.marca ?? null,
194
- brandCss: { fichero: existsSync(brand) ? 'src/brand.css' : null, variables: brandVars },
195
- extras: { animaciones: estado.animaciones, motion: yaInstalado('motion'), echarts: yaInstalado('echarts'), tablas: yaInstalado('@tanstack/react-table') },
196
- componentes: Object.fromEntries(Object.entries(manifest.components).map(([n, c]) => [n, { import: c.import, exports: c.exports, ...(c.notes ? { notes: c.notes } : {}) }])),
197
- patrones,
198
- documentacion: {
199
- reglas: `${docs}/AGENTS.md`,
200
- flujo: `${docs}/docs/designer/flujo.md`,
201
- patrones: `${docs}/docs/designer/patrones.md`,
202
- ux: `${docs}/docs/designer/ux.md`,
203
- revision: `${docs}/docs/designer/revision.md`,
204
- manifiesto: `${docs}/components.manifest.json`,
205
- },
206
- skill: estadoSkill(raizApp()).estado,
207
- integracion: avisosIntegracion(estado),
208
- };
209
- if (json) return console.log(JSON.stringify(datos, null, 2));
210
-
211
- const L = [`# orbital-ds ${version} · contexto de esta app`, ''];
212
- if (datos.tema) {
213
- const t = datos.tema;
214
- L.push(`## Tema activo: ${t.etiqueta ?? t.nombre} (${t.nombre})`, t.esencia ?? '');
215
- if (t.gesto.length) L.push(`- Gesto firma: ${t.gesto.join(' · ')}`);
216
- if (t.movimiento) L.push(`- Movimiento: ${t.movimiento}`);
217
- if (t.animaciones) L.push(`- Animaciones (${datos.extras.animaciones ? 'ACTIVAS' : 'inactivas'}): ${t.animaciones.about}`);
218
- L.push(`- Marca: ${t.marca === 'faithful' ? 'sistema corporativo, se usa FIEL' : 'admite marca propia'}`);
219
- if (t.excepciones.length) L.push(`- Excepciones de contraste declaradas: ${t.excepciones.join(', ')}`);
220
- L.push(`- Guía: ${t.guia}`);
221
- } else {
222
- L.push('## Tema activo: no detectado (¿falta conectar el CSS? orbital-ds init)');
223
- }
224
- L.push('', '## Marca de la app');
225
- L.push(datos.marca ? `- Generada desde ${datos.marca.primario} (modo ${datos.marca.modo}, tema ${datos.marca.tema})` : '- Sin bloque generado (tema fiel o marca a mano)');
226
- if (brandVars.length) L.push(`- src/brand.css cambia: ${brandVars.join(', ')}`);
227
- const sino = (v) => (v ? 'sí' : 'no');
228
- L.push('', '## Extras', `- Animaciones del tema: ${sino(datos.extras.animaciones)} · Motion: ${sino(datos.extras.motion)} · ECharts: ${sino(datos.extras.echarts)} · TanStack Table: ${sino(datos.extras.tablas)}`);
229
- L.push('', `## Componentes (${Object.keys(datos.componentes).length}) · import orbital-ds/ui/<nombre>`, Object.keys(datos.componentes).join(', '));
230
- const conNotas = Object.entries(datos.componentes).filter(([, c]) => c.notes);
231
- if (conNotas.length) {
232
- L.push('', '### Notas de uso');
233
- for (const [n, c] of conNotas) for (const x of c.notes) L.push(`- ${n}: ${x}`);
234
- }
235
- if (datos.integracion.length) L.push('', '## Avisos de integración', ...datos.integracion.map((a) => `- ${a}`));
236
- if (patrones.length) L.push('', '## Patrones (docs/designer/patrones.md)', ...patrones.map((p) => `- ${p}`));
237
- L.push('', '## Documentación', ...Object.entries(datos.documentacion).map(([k, v]) => `- ${k}: ${v}`));
238
- L.push(
239
- '',
240
- '## Reglas que no se rompen',
241
- '- Solo componentes de orbital-ds y variables: nada de colores, medidas, sombras, radios, pesos, duraciones ni z-index a mano.',
242
- '- El aspecto lo ponen el tema y src/brand.css, no la vista. Si falta algo, se anota como hueco de la librería.',
243
- '- Primero el mapa del flujo de la persona; después los patrones; al final, componer y revisar (doctor incluido).',
244
- );
245
- console.log(L.join('\n'));
246
- }
247
-
248
- /** orbital-ds skill [--check | --print] */
249
- function ordenSkill(args) {
250
- if (args.includes('--print')) return console.log(readFileSync(join(ROOT, 'skill', 'SKILL.md'), 'utf8').replaceAll('{{VERSION}}', version));
251
- const raiz = raizApp();
252
- if (args.includes('--check')) {
253
- const e = estadoSkill(raiz);
254
- if (e.estado === 'al-dia') return console.log(`skill ${SKILL_NAME}: al día (${version})`);
255
- console.error(
256
- e.estado === 'falta'
257
- ? `skill ${SKILL_NAME}: no está instalado. Instálalo con: orbital-ds skill`
258
- : `skill ${SKILL_NAME}: es de la versión ${e.version} y orbital-ds es la ${version}. Refréscalo con: orbital-ds skill`,
259
- );
260
- process.exit(1);
261
- }
262
- const r = instalarSkill(raiz);
263
- console.log(`skill ${SKILL_NAME} ${r.accion} (${r.version}): ${r.ruta}`);
264
- }
265
-
266
- function estadoApp() {
267
- const css = detectarCssApp();
268
- const cssTxt = css && existsSync(css) ? readFileSync(css, 'utf8') : '';
269
- const tema = cssTxt.match(/orbital-ds\/themes\/([\w-]+)\.css/)?.[1] ?? null;
270
- const animaciones = /orbital-ds\/motion\.css/.test(cssTxt);
271
- const brand = resolve('src/brand.css');
272
- const brandTxt = existsSync(brand) ? readFileSync(brand, 'utf8') : '';
273
- const cab = brandTxt.match(/Generado por `orbital-ds-init` \(tema ([\w-]+), primario (#[0-9a-f]{3,8})(?:, modo (\w+))?\)/i);
274
- return { css, tema, animaciones, marca: cab ? { tema: cab[1], primario: cab[2], modo: cab[3] ?? 'full' } : null };
275
- }
276
-
277
- /** Cambiar de tema: reescribe el import del tema y, si la marca se generó, la recalcula para el nuevo. */
278
- async function cambiarTema(nuevo) {
279
- const lista = temas();
280
- const estado = estadoApp();
281
- if (!nuevo) {
282
- const p = await import('@clack/prompts');
283
- p.intro(` orbital-ds ${version} · cambiar de tema `);
284
- if (estado.tema) p.log.info(`Tema actual: ${estado.tema}${estado.marca ? ` · marca generada desde ${estado.marca.primario} (modo ${estado.marca.modo})` : ' · sin marca generada'}`);
285
- const v = await p.select({
286
- message: '¿A qué tema cambias?',
287
- initialValue: estado.tema ?? undefined,
288
- options: lista.map((t) => ({ value: t.name, label: t.label ? `${t.label} (${t.name})` : t.name, hint: t.essence })),
289
- });
290
- if (p.isCancel(v)) { p.cancel('Sin cambios.'); return; }
291
- nuevo = v;
292
- }
293
- if (!lista.some((t) => t.name === nuevo)) {
294
- console.error(`El tema «${nuevo}» no existe. Disponibles: ${lista.map((t) => t.name).join(', ')}`);
295
- process.exit(1);
296
- }
297
- const ficha = lista.find((t) => t.name === nuevo);
298
- const args = ['--theme', nuevo, '--connect', '--update'];
299
- if (estado.css) args.push('--css', estado.css);
300
- if (estado.animaciones) args.push('--animations');
301
- if (estado.marca && ficha.branding !== 'faithful') args.push('--primary', estado.marca.primario, '--mode', estado.marca.modo);
302
- else if (estado.marca) console.log(`«${nuevo}» es un tema de sistema corporativo: se usa FIEL y se quita la marca generada (${estado.marca.primario}). Vuelve a ponerla con: orbital-ds init`);
303
- ejecutar('init.mjs', args);
304
- }
305
-
306
- async function menu() {
307
- const p = await import('@clack/prompts');
308
- const estado = estadoApp();
309
- p.intro(` orbital-ds ${version} `);
310
- if (estado.tema) p.log.info(`En esta app: tema ${estado.tema}${estado.marca ? `, marca desde ${estado.marca.primario}` : ''}${estado.animaciones ? ', animaciones activas' : ''}.`);
311
- const v = await p.select({
312
- message: '¿Qué quieres hacer?',
313
- initialValue: estado.tema ? 'theme' : 'init',
314
- options: [
315
- { value: 'init', label: 'Configurar la app', hint: 'tema, colores y extras (también para rehacer la marca)' },
316
- { value: 'theme', label: 'Cambiar de tema', hint: 'conserva tu marca y tus extras' },
317
- { value: 'doctor', label: 'Comprobar mi marca', hint: 'contrato, contraste y pesos' },
318
- { value: 'i18n', label: 'Textos en mis idiomas', hint: 'espacio «orbital» de los JSON de idioma' },
319
- { value: 'skill', label: 'Diseñador para Claude (skill)', hint: 'instala o refresca .claude/skills/orbital-ds-designer' },
320
- ],
321
- });
322
- if (p.isCancel(v)) { p.cancel('Nada que hacer.'); return; }
323
- if (v === 'init') ejecutar('init.mjs', ['--wizard']);
324
- if (v === 'theme') return cambiarTema(null);
325
- if (v === 'doctor') ejecutar('doctor.mjs', ['--css', resolve('src/brand.css')]);
326
- if (v === 'i18n') ejecutar('i18n.mjs', []);
327
- if (v === 'skill') return ordenSkill([]);
328
- }
329
-
330
- // Ayuda de una orden: orbital-ds <orden> --help · orbital-ds help <orden>
331
- if (orden && AYUDA[orden] && (resto.includes('--help') || resto.includes('-h'))) {
332
- ayuda(orden);
333
- process.exit(0);
334
- }
335
-
336
- switch (orden) {
337
- case undefined:
338
- if (process.stdin.isTTY && process.stdout.isTTY) await menu();
339
- else ayuda();
340
- break;
341
- case 'init':
342
- ejecutar('init.mjs', resto.length ? resto : ['--wizard']);
343
- break;
344
- case 'theme':
345
- await cambiarTema(resto.find((a) => !a.startsWith('--')) ?? null);
346
- break;
347
- case 'doctor':
348
- ejecutar('doctor.mjs', resto);
349
- break;
350
- case 'context':
351
- contexto(resto.includes('--json'));
352
- break;
353
- case 'skill':
354
- ordenSkill(resto);
355
- break;
356
- case 'i18n':
357
- ejecutar('i18n.mjs', resto);
358
- break;
359
- case 'help':
360
- case '--help':
361
- case '-h':
362
- case '--version':
363
- if (orden === '--version') console.log(version);
364
- else ayuda(resto[0]);
365
- break;
366
- default:
367
- console.error(`Orden desconocida: ${orden}\n`);
368
- ayuda();
369
- process.exit(1);
370
- }
1
+ #!/usr/bin/env node
2
+ /**
3
+ * orbital-ds — una sola orden para todo:
4
+ *
5
+ * orbital-ds menú (¿qué quieres hacer?)
6
+ * orbital-ds init [opciones] configuración inicial: tema, colores y extras (= orbital-ds-init)
7
+ * orbital-ds theme [tema] cambiar de tema conservando tu marca y tus extras
8
+ * orbital-ds doctor [opc.] comprobar contrato, contraste y marca (= orbital-ds-doctor)
9
+ * orbital-ds i18n [opc.] textos de orbital-ds en los idiomas de la app (= orbital-ds-i18n)
10
+ * orbital-ds help esta ayuda
11
+ *
12
+ * Las órdenes sueltas (orbital-ds-init, -doctor, -i18n) siguen funcionando: son atajos.
13
+ */
14
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
15
+ import { dirname, join, resolve } from 'node:path';
16
+ import { fileURLToPath } from 'node:url';
17
+ import { spawnSync } from 'node:child_process';
18
+
19
+ import { detectarCssApp, yaInstalado } from './setup.mjs';
20
+ import { estadoSkill, instalarSkill, raizApp, SKILL_NAME } from './skill.mjs';
21
+
22
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
23
+ const [orden, ...resto] = process.argv.slice(2);
24
+ const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
25
+ const temasDir = existsSync(join(ROOT, 'src/themes')) ? join(ROOT, 'src/themes') : join(ROOT, 'dist/themes');
26
+ /** Fichas de los temas que trae el paquete. */
27
+ const temas = () =>
28
+ readdirSync(temasDir)
29
+ .filter((f) => f.endsWith('.meta.json'))
30
+ .map((f) => JSON.parse(readFileSync(join(temasDir, f), 'utf8')));
31
+
32
+ /** Ejecuta otro script del paquete con los mismos stdin/stdout (interactivo incluido). */
33
+ function ejecutar(script, args) {
34
+ const r = spawnSync(process.execPath, [join(ROOT, 'scripts', script), ...args], { stdio: 'inherit' });
35
+ process.exit(r.status ?? 1);
36
+ }
37
+
38
+ const AYUDA = {
39
+ general: `orbital-ds ${version} — sistema de diseño: temas, componentes y herramientas
40
+
41
+ Uso: orbital-ds <orden> [opciones] (sin orden, un menú)
42
+
43
+ Órdenes
44
+ init configuración inicial: tema, colores y extras (asistente)
45
+ theme cambiar de tema conservando tu marca y tus extras
46
+ doctor comprobar contrato, contraste, pesos y marca
47
+ i18n textos de orbital-ds en los idiomas de la app
48
+ context resumen de esta app para un agente: tema, marca, componentes y patrones
49
+ skill instala o refresca el diseñador de orbital-ds para Claude Code
50
+ help esta ayuda · orbital-ds help <orden> para el detalle
51
+
52
+ Ejemplos
53
+ orbital-ds menú
54
+ orbital-ds init asistente paso a paso
55
+ orbital-ds theme fractalia pasar a fractalia
56
+ orbital-ds doctor --css src/brand.css comprobar tu marca
57
+
58
+ Desde un script de package.json: pnpm exec orbital-ds <orden> (o npx orbital-ds <orden>).
59
+ Las órdenes antiguas (orbital-ds-init, orbital-ds-doctor, orbital-ds-i18n) siguen valiendo.`,
60
+
61
+ init: `orbital-ds init — configuración inicial de la app
62
+
63
+ Sin opciones abre el asistente: 1) tema, 2) colores (fiel, solo primario o marca completa;
64
+ primario y, si quieres, secundario; ves la paleta y el contraste), 3) extras (animaciones,
65
+ Motion, gráficos, tablas, idiomas) y 4) resumen antes de escribir nada. Es la configuración
66
+ INICIAL: todo se cambia después en src/brand.css o volviendo a ejecutarlo.
67
+
68
+ Sin preguntas (scripts / CI)
69
+ --theme <tema> qratia, fractalia, tactile, zyro, friendly, twitter, liquid
70
+ --mode <modo> faithful (tema tal cual) · primary (solo tu color) · full (paleta entera)
71
+ --primary <color> #1D63D8, rgb(), hsl() u oklch()
72
+ --secondary <color> serie 2 de los gráficos y gesto del tema
73
+ --connect [--css <f>] conecta el CSS de la app (imports en orden)
74
+ --animations activa las animaciones del tema (orbital-ds/motion.css)
75
+ --motion --charts --tables instala Motion, ECharts o TanStack Table
76
+ --i18n rellena el espacio «orbital» de los JSON de idioma
77
+ --update reescribe el bloque generado de brand.css
78
+ --dry-run enseña el resultado sin escribir nada
79
+ --out <fichero> fichero de marca (por defecto src/brand.css)
80
+
81
+ Ejemplos
82
+ orbital-ds init --theme fractalia --connect --animations
83
+ orbital-ds init --theme qratia --mode primary --primary "#0A7D4F" --connect --charts`,
84
+
85
+ theme: `orbital-ds theme [tema] — cambiar de tema
86
+
87
+ Cambia el import del tema en el CSS de la app y conserva lo tuyo:
88
+ - si tu marca se generó desde un color, la recalcula para el tema nuevo (mismo color y modo);
89
+ - si el tema nuevo es de un sistema corporativo (fractalia), se usa fiel;
90
+ - si tenías las animaciones activas, siguen activas.
91
+ Sin tema, pregunta a cuál cambiar.
92
+
93
+ Ejemplos
94
+ orbital-ds theme elegir de la lista
95
+ orbital-ds theme tactile`,
96
+
97
+ doctor: `orbital-ds doctor — comprobar
98
+
99
+ orbital-ds doctor --css src/brand.css tu marca: variables que existen, contraste AA,
100
+ pesos de letra cargados
101
+ orbital-ds doctor --ui src tus vistas no se salen del sistema: colores, medidas y
102
+ valores arbitrarios, paleta de Tailwind, !important,
103
+ controles nativos sueltos
104
+ --aaa mide también el objetivo AAA del texto
105
+
106
+ Va bien en el verify de la app: "check:ds": "orbital-ds doctor --css src/brand.css --ui src"`,
107
+
108
+ context: `orbital-ds context — lo que un agente necesita saber de ESTA app
109
+
110
+ Imprime: versión de orbital-ds, tema activo (esencia, gesto, movimiento, excepciones), cómo está la marca,
111
+ extras activos, componentes con sus notas de uso, patrones del diseñador y dónde está la documentación.
112
+ Lo lee el skill «orbital-ds-designer» antes de diseñar, y vale para cualquier agente.
113
+
114
+ orbital-ds context en texto (markdown)
115
+ orbital-ds context --json en JSON`,
116
+
117
+ skill: `orbital-ds skill — diseñador de orbital-ds para Claude Code
118
+
119
+ Instala (o refresca) el skill «orbital-ds-designer» en la raíz de la app: .claude/skills/orbital-ds-designer/.
120
+ Es fino: las reglas largas se leen de node_modules/orbital-ds/docs/designer/, así que al actualizar orbital-ds
121
+ ya trabaja con lo nuevo. Lleva la versión estampada; lo que añadas DESPUÉS de su bloque se conserva.
122
+
123
+ orbital-ds skill instala o refresca
124
+ orbital-ds skill --check comprueba (para el verify): falla si falta o es de otra versión
125
+ orbital-ds skill --print enseña el contenido sin escribir nada`,
126
+
127
+ i18n: `orbital-ds i18n — textos de orbital-ds en tus idiomas
128
+
129
+ orbital-ds i18n rellena el espacio «orbital» de cada JSON (sin pisar lo tuyo)
130
+ orbital-ds i18n --check solo comprueba (para el verify): falla si falta algo
131
+ --dir <carpeta> carpeta de los JSON (por defecto src/i18n/locales, src/locales…)
132
+ --ns <nombre> espacio de nombres (por defecto orbital)
133
+
134
+ Añadir un idioma (p. ej. ru): crea ru.json, ejecuta orbital-ds i18n y traduce lo que liste.`,
135
+ };
136
+
137
+ function ayuda(tema = 'general') {
138
+ console.log(AYUDA[tema] ?? AYUDA.general);
139
+ }
140
+
141
+ /** Lo que hay hoy en la app: tema importado, marca generada (primario, modo) y animaciones. */
142
+ /** Lo que falta en la raíz de la app para que las piezas de orbital-ds funcionen del todo. */
143
+ function avisosIntegracion(estado) {
144
+ const src = resolve('src');
145
+ let codigo = '';
146
+ const leer = (d) => {
147
+ if (!existsSync(d)) return;
148
+ for (const n of readdirSync(d, { withFileTypes: true })) {
149
+ if (n.name === 'node_modules' || n.name.startsWith('.')) continue;
150
+ const p = join(d, n.name);
151
+ if (n.isDirectory()) leer(p);
152
+ // Sin comentarios: nombrar <Toaster /> en un comentario no cuenta como tenerlo.
153
+ else if (/\.(tsx|jsx|ts|js)$/.test(n.name)) codigo += readFileSync(p, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
154
+ }
155
+ };
156
+ leer(src);
157
+ const avisos = [];
158
+ if (!estado.tema) avisos.push('El CSS de la app no importa ningún tema: ejecuta orbital-ds init (o orbital-ds theme).');
159
+ if (codigo && !/DsI18nProvider/.test(codigo)) avisos.push('No hay <DsI18nProvider> en la raíz: los textos de orbital-ds salen en inglés (orbital-ds/ui/i18n-provider).');
160
+ if (codigo && /\btoast\b/.test(codigo) && !/<Toaster\b/.test(codigo)) avisos.push('Se usa toast pero no hay <Toaster /> en la raíz: los avisos no se verán (orbital-ds/ui/toast).');
161
+ if (codigo && /useDsMotion|DsMotionProvider/.test(codigo) && !yaInstalado('motion')) avisos.push('Se usa Motion (useDsMotion/DsMotionProvider) pero el paquete motion no está instalado.');
162
+ if (codigo && /useDsMotion/.test(codigo) && !/DsMotionProvider/.test(codigo)) avisos.push('Se usa useDsMotion() sin <DsMotionProvider> en la raíz: envuelve la app para que todo motion.* use el ritmo del tema.');
163
+ return avisos;
164
+ }
165
+
166
+ /** orbital-ds context: el estado real de la app, para un agente (texto o JSON). */
167
+ function contexto(json) {
168
+ const estado = estadoApp();
169
+ const ficha = temas().find((t) => t.name === estado.tema) ?? null;
170
+ const manifest = JSON.parse(readFileSync(join(ROOT, 'components.manifest.json'), 'utf8'));
171
+ const patronesMd = join(ROOT, 'docs', 'designer', 'patrones.md');
172
+ const patrones = existsSync(patronesMd) ? [...readFileSync(patronesMd, 'utf8').matchAll(/^## (P\d+ · .+)$/gm)].map((m) => m[1].trim()) : [];
173
+ const brand = resolve('src/brand.css');
174
+ const brandVars = existsSync(brand)
175
+ ? [...new Set([...readFileSync(brand, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/(--[\w-]+)\s*:/g)].map((m) => m[1]))]
176
+ : [];
177
+ const docs = 'node_modules/orbital-ds';
178
+ const datos = {
179
+ version,
180
+ tema: ficha
181
+ ? {
182
+ nombre: ficha.name,
183
+ etiqueta: ficha.label,
184
+ esencia: ficha.essence,
185
+ gesto: ficha.signature ?? [],
186
+ movimiento: ficha.motion?.about ?? null,
187
+ animaciones: ficha.motion?.auto ?? null,
188
+ marca: ficha.branding ?? 'full',
189
+ excepciones: ficha.a11y?.exceptions ?? [],
190
+ guia: `${docs}/dist/themes/${ficha.name}.guide.md`,
191
+ }
192
+ : null,
193
+ marca: estado.marca ?? null,
194
+ brandCss: { fichero: existsSync(brand) ? 'src/brand.css' : null, variables: brandVars },
195
+ extras: { animaciones: estado.animaciones, motion: yaInstalado('motion'), echarts: yaInstalado('echarts'), tablas: yaInstalado('@tanstack/react-table') },
196
+ componentes: Object.fromEntries(Object.entries(manifest.components).map(([n, c]) => [n, { import: c.import, exports: c.exports, ...(c.notes ? { notes: c.notes } : {}) }])),
197
+ patrones,
198
+ documentacion: {
199
+ reglas: `${docs}/AGENTS.md`,
200
+ flujo: `${docs}/docs/designer/flujo.md`,
201
+ patrones: `${docs}/docs/designer/patrones.md`,
202
+ ux: `${docs}/docs/designer/ux.md`,
203
+ revision: `${docs}/docs/designer/revision.md`,
204
+ manifiesto: `${docs}/components.manifest.json`,
205
+ },
206
+ skill: estadoSkill(raizApp()).estado,
207
+ integracion: avisosIntegracion(estado),
208
+ };
209
+ if (json) return console.log(JSON.stringify(datos, null, 2));
210
+
211
+ const L = [`# orbital-ds ${version} · contexto de esta app`, ''];
212
+ if (datos.tema) {
213
+ const t = datos.tema;
214
+ L.push(`## Tema activo: ${t.etiqueta ?? t.nombre} (${t.nombre})`, t.esencia ?? '');
215
+ if (t.gesto.length) L.push(`- Gesto firma: ${t.gesto.join(' · ')}`);
216
+ if (t.movimiento) L.push(`- Movimiento: ${t.movimiento}`);
217
+ if (t.animaciones) L.push(`- Animaciones (${datos.extras.animaciones ? 'ACTIVAS' : 'inactivas'}): ${t.animaciones.about}`);
218
+ L.push(`- Marca: ${t.marca === 'faithful' ? 'sistema corporativo, se usa FIEL' : 'admite marca propia'}`);
219
+ if (t.excepciones.length) L.push(`- Excepciones de contraste declaradas: ${t.excepciones.join(', ')}`);
220
+ L.push(`- Guía: ${t.guia}`);
221
+ } else {
222
+ L.push('## Tema activo: no detectado (¿falta conectar el CSS? orbital-ds init)');
223
+ }
224
+ L.push('', '## Marca de la app');
225
+ L.push(datos.marca ? `- Generada desde ${datos.marca.primario} (modo ${datos.marca.modo}, tema ${datos.marca.tema})` : '- Sin bloque generado (tema fiel o marca a mano)');
226
+ if (brandVars.length) L.push(`- src/brand.css cambia: ${brandVars.join(', ')}`);
227
+ const sino = (v) => (v ? 'sí' : 'no');
228
+ L.push('', '## Extras', `- Animaciones del tema: ${sino(datos.extras.animaciones)} · Motion: ${sino(datos.extras.motion)} · ECharts: ${sino(datos.extras.echarts)} · TanStack Table: ${sino(datos.extras.tablas)}`);
229
+ L.push('', `## Componentes (${Object.keys(datos.componentes).length}) · import orbital-ds/ui/<nombre>`, Object.keys(datos.componentes).join(', '));
230
+ const conNotas = Object.entries(datos.componentes).filter(([, c]) => c.notes);
231
+ if (conNotas.length) {
232
+ L.push('', '### Notas de uso');
233
+ for (const [n, c] of conNotas) for (const x of c.notes) L.push(`- ${n}: ${x}`);
234
+ }
235
+ if (datos.integracion.length) L.push('', '## Avisos de integración', ...datos.integracion.map((a) => `- ${a}`));
236
+ if (patrones.length) L.push('', '## Patrones (docs/designer/patrones.md)', ...patrones.map((p) => `- ${p}`));
237
+ L.push('', '## Documentación', ...Object.entries(datos.documentacion).map(([k, v]) => `- ${k}: ${v}`));
238
+ L.push(
239
+ '',
240
+ '## Reglas que no se rompen',
241
+ '- Solo componentes de orbital-ds y variables: nada de colores, medidas, sombras, radios, pesos, duraciones ni z-index a mano.',
242
+ '- El aspecto lo ponen el tema y src/brand.css, no la vista. Si falta algo, se anota como hueco de la librería.',
243
+ '- Primero el mapa del flujo de la persona; después los patrones; al final, componer y revisar (doctor incluido).',
244
+ );
245
+ console.log(L.join('\n'));
246
+ }
247
+
248
+ /** orbital-ds skill [--check | --print] */
249
+ function ordenSkill(args) {
250
+ if (args.includes('--print')) return console.log(readFileSync(join(ROOT, 'skill', 'SKILL.md'), 'utf8').replaceAll('{{VERSION}}', version));
251
+ const raiz = raizApp();
252
+ if (args.includes('--check')) {
253
+ const e = estadoSkill(raiz);
254
+ if (e.estado === 'al-dia') return console.log(`skill ${SKILL_NAME}: al día (${version})`);
255
+ console.error(
256
+ e.estado === 'falta'
257
+ ? `skill ${SKILL_NAME}: no está instalado. Instálalo con: orbital-ds skill`
258
+ : `skill ${SKILL_NAME}: es de la versión ${e.version} y orbital-ds es la ${version}. Refréscalo con: orbital-ds skill`,
259
+ );
260
+ process.exit(1);
261
+ }
262
+ const r = instalarSkill(raiz);
263
+ console.log(`skill ${SKILL_NAME} ${r.accion} (${r.version}): ${r.ruta}`);
264
+ }
265
+
266
+ function estadoApp() {
267
+ const css = detectarCssApp();
268
+ const cssTxt = css && existsSync(css) ? readFileSync(css, 'utf8') : '';
269
+ const tema = cssTxt.match(/orbital-ds\/themes\/([\w-]+)\.css/)?.[1] ?? null;
270
+ const animaciones = /orbital-ds\/motion\.css/.test(cssTxt);
271
+ const brand = resolve('src/brand.css');
272
+ const brandTxt = existsSync(brand) ? readFileSync(brand, 'utf8') : '';
273
+ const cab = brandTxt.match(/Generado por `orbital-ds-init` \(tema ([\w-]+), primario (#[0-9a-f]{3,8})(?:, modo (\w+))?\)/i);
274
+ return { css, tema, animaciones, marca: cab ? { tema: cab[1], primario: cab[2], modo: cab[3] ?? 'full' } : null };
275
+ }
276
+
277
+ /** Cambiar de tema: reescribe el import del tema y, si la marca se generó, la recalcula para el nuevo. */
278
+ async function cambiarTema(nuevo) {
279
+ const lista = temas();
280
+ const estado = estadoApp();
281
+ if (!nuevo) {
282
+ const p = await import('@clack/prompts');
283
+ p.intro(` orbital-ds ${version} · cambiar de tema `);
284
+ if (estado.tema) p.log.info(`Tema actual: ${estado.tema}${estado.marca ? ` · marca generada desde ${estado.marca.primario} (modo ${estado.marca.modo})` : ' · sin marca generada'}`);
285
+ const v = await p.select({
286
+ message: '¿A qué tema cambias?',
287
+ initialValue: estado.tema ?? undefined,
288
+ options: lista.map((t) => ({ value: t.name, label: t.label ? `${t.label} (${t.name})` : t.name, hint: t.essence })),
289
+ });
290
+ if (p.isCancel(v)) { p.cancel('Sin cambios.'); return; }
291
+ nuevo = v;
292
+ }
293
+ if (!lista.some((t) => t.name === nuevo)) {
294
+ console.error(`El tema «${nuevo}» no existe. Disponibles: ${lista.map((t) => t.name).join(', ')}`);
295
+ process.exit(1);
296
+ }
297
+ const ficha = lista.find((t) => t.name === nuevo);
298
+ const args = ['--theme', nuevo, '--connect', '--update'];
299
+ if (estado.css) args.push('--css', estado.css);
300
+ if (estado.animaciones) args.push('--animations');
301
+ if (estado.marca && ficha.branding !== 'faithful') args.push('--primary', estado.marca.primario, '--mode', estado.marca.modo);
302
+ else if (estado.marca) console.log(`«${nuevo}» es un tema de sistema corporativo: se usa FIEL y se quita la marca generada (${estado.marca.primario}). Vuelve a ponerla con: orbital-ds init`);
303
+ ejecutar('init.mjs', args);
304
+ }
305
+
306
+ async function menu() {
307
+ const p = await import('@clack/prompts');
308
+ const estado = estadoApp();
309
+ p.intro(` orbital-ds ${version} `);
310
+ if (estado.tema) p.log.info(`En esta app: tema ${estado.tema}${estado.marca ? `, marca desde ${estado.marca.primario}` : ''}${estado.animaciones ? ', animaciones activas' : ''}.`);
311
+ const v = await p.select({
312
+ message: '¿Qué quieres hacer?',
313
+ initialValue: estado.tema ? 'theme' : 'init',
314
+ options: [
315
+ { value: 'init', label: 'Configurar la app', hint: 'tema, colores y extras (también para rehacer la marca)' },
316
+ { value: 'theme', label: 'Cambiar de tema', hint: 'conserva tu marca y tus extras' },
317
+ { value: 'doctor', label: 'Comprobar mi marca', hint: 'contrato, contraste y pesos' },
318
+ { value: 'i18n', label: 'Textos en mis idiomas', hint: 'espacio «orbital» de los JSON de idioma' },
319
+ { value: 'skill', label: 'Diseñador para Claude (skill)', hint: 'instala o refresca .claude/skills/orbital-ds-designer' },
320
+ ],
321
+ });
322
+ if (p.isCancel(v)) { p.cancel('Nada que hacer.'); return; }
323
+ if (v === 'init') ejecutar('init.mjs', ['--wizard']);
324
+ if (v === 'theme') return cambiarTema(null);
325
+ if (v === 'doctor') ejecutar('doctor.mjs', ['--css', resolve('src/brand.css')]);
326
+ if (v === 'i18n') ejecutar('i18n.mjs', []);
327
+ if (v === 'skill') return ordenSkill([]);
328
+ }
329
+
330
+ // Ayuda de una orden: orbital-ds <orden> --help · orbital-ds help <orden>
331
+ if (orden && AYUDA[orden] && (resto.includes('--help') || resto.includes('-h'))) {
332
+ ayuda(orden);
333
+ process.exit(0);
334
+ }
335
+
336
+ switch (orden) {
337
+ case undefined:
338
+ if (process.stdin.isTTY && process.stdout.isTTY) await menu();
339
+ else ayuda();
340
+ break;
341
+ case 'init':
342
+ ejecutar('init.mjs', resto.length ? resto : ['--wizard']);
343
+ break;
344
+ case 'theme':
345
+ await cambiarTema(resto.find((a) => !a.startsWith('--')) ?? null);
346
+ break;
347
+ case 'doctor':
348
+ ejecutar('doctor.mjs', resto);
349
+ break;
350
+ case 'context':
351
+ contexto(resto.includes('--json'));
352
+ break;
353
+ case 'skill':
354
+ ordenSkill(resto);
355
+ break;
356
+ case 'i18n':
357
+ ejecutar('i18n.mjs', resto);
358
+ break;
359
+ case 'help':
360
+ case '--help':
361
+ case '-h':
362
+ case '--version':
363
+ if (orden === '--version') console.log(version);
364
+ else ayuda(resto[0]);
365
+ break;
366
+ default:
367
+ console.error(`Orden desconocida: ${orden}\n`);
368
+ ayuda();
369
+ process.exit(1);
370
+ }