@mantis-core/ui 0.5.0 → 0.7.0

package/bin/mantis-llm.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// mantis-llm — escribe/actualiza un bloque de punteros de discovery para LLMs
+// (CLAUDE.md / AGENTS.md) en el proyecto que consume @mantis-core/*.
+//
+// El objetivo: que cualquier LLM trabajando en un proyecto consumidor sepa qué
+// componentes existen y cómo usarlos, sin que el humano tenga que recordárselo.
+// Los docs ya viajan dentro de node_modules/@mantis-core/*/ — esto solo agrega el
+// puntero en la raíz del repo (lo único que un LLM lee por defecto).
+//
+// Uso (post-install, el bin vive dentro de @mantis-core/ui):
+//   pnpm exec mantis-llm            # escribe/actualiza CLAUDE.md y AGENTS.md
+//   pnpm exec mantis-llm --files=CLAUDE.md
+//   pnpm exec mantis-llm --check    # no escribe; exit≠0 si falta o está viejo (para CI)
+//   pnpm exec mantis-llm --self-check
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BLOCK_VERSION = "v1";
+const START = `<!-- mantis-core:llm-pointers ${BLOCK_VERSION} START (auto-generado por \`pnpm exec mantis-llm\` — no editar a mano) -->`;
+const END = `<!-- mantis-core:llm-pointers END -->`;
+// Regex tolerante a cualquier versión previa del marcador START.
+const BLOCK_RE =
+  /<!-- mantis-core:llm-pointers[^>]*START[^>]*-->[\s\S]*?<!-- mantis-core:llm-pointers END -->/;
+
+const SELF_DIR = dirname(fileURLToPath(import.meta.url)); // .../@mantis-core/ui/bin
+const SCOPE_DIR = resolve(SELF_DIR, "..", ".."); // .../@mantis-core
+
+// Solo paquetes que shipean docs de consumo. commons/utils no shipean llms.txt.
+const PACKAGES = ["ui", "next-core", "nuqs", "styles"];
+
+const isInstalled = (pkg) => existsSync(resolve(SCOPE_DIR, pkg, "llms.txt"));
+
+/** Líneas de puntero por paquete — SOLO archivos de consumo (nunca docs internos). */
+function pointerLines(pkg) {
+  const base = `node_modules/@mantis-core/${pkg}`;
+  switch (pkg) {
+    case "ui":
+      return [
+        `- **@mantis-core/ui** — \`${base}/llms.txt\` (índice de componentes: whenToUse + import por componente, léelo primero) · \`${base}/catalog.json\` (props/tipos — ~132KB, solo para grep puntual) · \`${base}/docs/components/*.md\` (1 doc con ejemplo compilable por componente) · \`${base}/docs/contracts/field-controller.md\` (contrato de form fields) · \`${base}/docs/contracts/style-imports.md\` (qué SCSS importar)`,
+      ];
+    case "next-core":
+      return [
+        `- **@mantis-core/next-core** — \`${base}/llms.txt\` · \`${base}/docs/setup.md\` (install → providers → estilos → primer form + tabla) · \`${base}/docs/theme.md\` (MantisThemeProvider: preset, color ramps, dark mode) · \`${base}/docs/providers.md\` · \`${base}/docs/hooks.md\` · \`${base}/docs/toasts.md\``,
+      ];
+    case "nuqs":
+      return [
+        `- **@mantis-core/nuqs** — \`${base}/llms.txt\` (parsers de URL-state + \`useDataTableQuery\`)`,
+      ];
+    case "styles":
+      return [
+        `- **@mantis-core/styles** — \`${base}/llms.txt\` (partials SCSS + design tokens)`,
+      ];
+    default:
+      return [];
+  }
+}
+
+/** Construye el CONTENIDO del bloque (sin los marcadores), condicionado a lo instalado. */
+function buildBlock(installed) {
+  const hasNextCore = installed.includes("next-core");
+
+  const rules = [
+    "- Importá desde `@mantis-core/ui` (o subpaths `@mantis-core/ui/components/*`). Nunca desde `packages/*`.",
+    "- Los form fields son `FieldControllerProps` planos: `<TextField name control label />` — sin `controller={{...}}`.",
+  ];
+  if (hasNextCore) {
+    rules.push(
+      "- Montá `MantisCoreBaseProvider` + `MantisThemeProvider` una sola vez en el root. Ver `node_modules/@mantis-core/next-core/docs/setup.md`.",
+    );
+  }
+  rules.push(
+    "- Leé el `llms.txt` del paquete primero (índice chico). No leas `catalog.json` entero (~132KB): usalo solo para buscar props puntuales.",
+  );
+
+  const pointers = installed.flatMap(pointerLines);
+
+  return [
+    "## Mantis Core — componentes `@mantis-core/*` (LEER antes de escribir UI)",
+    "",
+    "Este proyecto usa `@mantis-core/*`. **Antes de crear o editar cualquier UI** con estos paquetes,",
+    "leé sus docs — ya están instaladas en `node_modules`, no hace falta clonar ni buscar en internet.",
+    "",
+    "### Reglas (no romper)",
+    ...rules,
+    "",
+    "### Dónde mirar (por paquete instalado)",
+    ...pointers,
+  ].join("\n");
+}
+
+/** Envuelve el contenido con los marcadores. */
+const wrap = (block) => `${START}\n${block}\n${END}`;
+
+/** Extrae el contenido interno (sin marcadores) de un bloque ya presente. */
+function extractInner(fileContent) {
+  const m = fileContent.match(BLOCK_RE);
+  if (!m) return null;
+  return m[0].replace(/^<!--[^>]*-->\n?/, "").replace(/\n?<!-- mantis-core:llm-pointers END -->$/, "");
+}
+
+/**
+ * Inserta/reemplaza el bloque en el contenido del archivo.
+ * @returns {string} nuevo contenido
+ */
+function applyBlock(existing, wrapped) {
+  if (existing == null || existing.trim() === "") {
+    return wrapped + "\n";
+  }
+  if (BLOCK_RE.test(existing)) {
+    return existing.replace(BLOCK_RE, wrapped);
+  }
+  // Sin bloque previo → append preservando el contenido del usuario.
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  return existing + sep + wrapped + "\n";
+}
+
+function parseArgs(argv) {
+  const args = { files: ["CLAUDE.md", "AGENTS.md"], check: false, selfCheck: false, help: false };
+  for (const a of argv) {
+    if (a === "--check") args.check = true;
+    else if (a === "--self-check") args.selfCheck = true;
+    else if (a === "-h" || a === "--help") args.help = true;
+    else if (a.startsWith("--files=")) {
+      args.files = a
+        .slice("--files=".length)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    }
+  }
+  return args;
+}
+
+const HELP = `mantis-llm — puntero de discovery de @mantis-core/* para LLMs
+
+  pnpm exec mantis-llm [--files=CLAUDE.md,AGENTS.md] [--check]
+
+Escribe/actualiza un bloque gestionado en los archivos de agente del proyecto
+consumidor apuntando a las docs de @mantis-core/* dentro de node_modules.
+
+  (sin flags)   Escribe/actualiza el bloque en CLAUDE.md y AGENTS.md (los crea si faltan).
+  --files=...   Lista de archivos destino separada por comas.
+  --check       No escribe. Exit≠0 si el bloque falta o está desactualizado (para CI).
+  --self-check  Corre el auto-test interno (idempotencia + check) en un dir temporal.
+`;
+
+function run(cwd, argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const installed = PACKAGES.filter(isInstalled);
+  if (installed.length === 0) {
+    process.stderr.write(
+      "mantis-llm: no encontré ningún @mantis-core/* con llms.txt junto a este bin. " +
+        "¿Se corrió desde un proyecto con @mantis-core instalado?\n",
+    );
+    return 1;
+  }
+
+  const wrapped = wrap(buildBlock(installed));
+  const expectedInner = buildBlock(installed).trim();
+
+  if (args.check) {
+    let drift = false;
+    for (const file of args.files) {
+      const path = resolve(cwd, file);
+      const inner = existsSync(path) ? extractInner(readFileSync(path, "utf8")) : null;
+      if (inner == null) {
+        process.stderr.write(`mantis-llm --check: falta el bloque en ${file}\n`);
+        drift = true;
+      } else if (inner.trim() !== expectedInner) {
+        process.stderr.write(`mantis-llm --check: bloque desactualizado en ${file} (re-corré \`pnpm exec mantis-llm\`)\n`);
+        drift = true;
+      }
+    }
+    if (!drift) process.stdout.write(`mantis-llm --check: OK (${installed.join(", ")})\n`);
+    return drift ? 1 : 0;
+  }
+
+  for (const file of args.files) {
+    const path = resolve(cwd, file);
+    const existed = existsSync(path);
+    const existing = existed ? readFileSync(path, "utf8") : null;
+    const next = applyBlock(existing, wrapped);
+    if (existed && next === existing) {
+      process.stdout.write(`mantis-llm: ${file} ya estaba al día\n`);
+    } else {
+      writeFileSync(path, next);
+      process.stdout.write(`mantis-llm: ${existed ? "actualizado" : "creado"} ${file}\n`);
+    }
+  }
+  process.stdout.write(`mantis-llm: paquetes detectados → ${installed.join(", ")}\n`);
+  return 0;
+}
+
+// --- self-check (ponytail: un check runnable, sin frameworks) --------------
+async function selfCheck() {
+  const { mkdtempSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const assert = (await import("node:assert/strict")).default;
+
+  const tmp = mkdtempSync(resolve(tmpdir(), "mantis-llm-"));
+  const claude = resolve(tmp, "CLAUDE.md");
+
+  // Reusa la lógica pura contra un set "instalado" fijo (no toca disco real de paquetes).
+  const installed = ["ui", "next-core"];
+  const wrapped = wrap(buildBlock(installed));
+
+  // 1) crea el archivo con el bloque
+  writeFileSync(claude, applyBlock(null, wrapped));
+  let content = readFileSync(claude, "utf8");
+  assert.ok(content.includes(START), "debe escribir el marcador START");
+  assert.ok(content.includes("MantisThemeProvider"), "con next-core debe incluir la regla de providers");
+
+  // 2) idempotente: 2ª aplicación no duplica
+  const again = applyBlock(content, wrapped);
+  assert.equal((again.match(/mantis-core:llm-pointers .*START/g) || []).length, 1, "no debe duplicar el bloque");
+  assert.equal(again, content, "2ª corrida no debe cambiar nada");
+
+  // 3) regla condicional: sin next-core NO aparece la regla de providers
+  const uiOnly = applyBlock(null, wrap(buildBlock(["ui"])));
+  assert.ok(!uiOnly.includes("MantisThemeProvider"), "sin next-core no debe mencionar providers");
+
+  // 4) extractInner round-trips y detecta drift
+  assert.equal(extractInner(content).trim(), buildBlock(installed).trim(), "extractInner debe recuperar el bloque");
+
+  rmSync(tmp, { recursive: true, force: true });
+  process.stdout.write("mantis-llm --self-check: OK\n");
+  return 0;
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes("--self-check")) {
+  process.exit(await selfCheck());
+} else {
+  process.exit(run(process.cwd(), argv));
+}