@bacano/sdk 1.1.9 → 1.1.12

package/skills/bacano-figma-web/references/visual-validation.md

@@ -0,0 +1,39 @@
+# Validación visual y funcional
+
+Validar por cortes para evitar corregir 70 secciones al final.
+
+## Evidencia mínima por página
+
+- URL/ruta implementada.
+- Frame y node ID de referencia.
+- Viewport desktop y mobile utilizados.
+- Captura de referencia y captura de implementación.
+- Diferencias intencionales e inferencias.
+- Resultado de accesibilidad/interacción aplicable.
+
+## Orden de revisión
+
+1. Estructura, jerarquía y contenido.
+2. Breakpoints, anchuras y flujo responsive.
+3. Tipografía, color, espacios y radios.
+4. Imágenes, recortes, densidad y estado de carga.
+5. Hover, focus, teclado, formularios y navegación.
+6. Estados loading, vacío, error y contenido largo.
+7. Integración Bacano y ausencia de datos inventados.
+8. Contenido editorial real o fixture temporal claramente identificado.
+
+Usar Playwright o la herramienta de navegador disponible para capturas y
+traces. Una comparación pixel a pixel puede ayudar, pero no debe ocultar fallos
+semánticos o funcionales.
+
+## Cierre técnico
+
+- Typecheck, lint, tests y build del proyecto.
+- Rutas generadas y sitemap esperado.
+- Sin errores de consola/recurso.
+- Sin GraphQL directo ni solicitudes duplicadas evitables.
+- HTML estático presente cuando el contrato es Static First.
+- Media responsive sin upscale visible.
+- Ningún fixture, placeholder o fallback editorial temporal en el build de
+  producción.
+- `$bacano-web` ejecutado al final cuando corresponda.

package/skills/bacano-figma-web/scripts/cli.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { connect } from "node:net";
+import { dirname, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { validateSnapshot } from "./snapshot.mjs";
+
+const skillName = "bacano-figma-web";
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const sourceSkill = resolve(scriptDirectory, "..");
+const projectRoot = process.cwd();
+const canonicalSkill = resolve(projectRoot, ".agents", "skills", skillName);
+
+const adapterPaths = {
+  antigravity: canonicalSkill,
+  claude: resolve(projectRoot, ".claude", "skills", skillName),
+  codex: resolve(projectRoot, ".codex", "skills", skillName),
+};
+
+function usage() {
+  console.log(`Bacano Figma Web
+
+Uso:
+  bacano-figma-web install [--agent antigravity|claude|codex|all] [--force]
+  bacano-figma-web check
+  bacano-figma-web doctor [--json]
+  bacano-figma-web validate-snapshot <ruta/manifest.json>
+
+La copia canónica vive en .agents/skills/${skillName}.
+Claude y Codex reciben enlaces a esa misma copia.`);
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+function relativeDisplay(path) {
+  const value = relative(projectRoot, path);
+  return value || ".";
+}
+
+function listFiles(directory, base = directory) {
+  return readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) return listFiles(path, base);
+      if (!entry.isFile()) return [];
+      return [{ path, name: relative(base, path) }];
+    })
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function skillDigest(directory) {
+  const hash = createHash("sha256");
+  for (const file of listFiles(directory)) {
+    hash.update(file.name);
+    hash.update("\0");
+    hash.update(readFileSync(file.path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function isSkillDirectory(directory) {
+  return existsSync(resolve(directory, "SKILL.md"));
+}
+
+function removeExisting(path, force) {
+  if (!existsSync(path)) return;
+  if (!force) {
+    throw new Error(
+      `${relativeDisplay(path)} ya existe. Usa --force para reemplazarlo.`,
+    );
+  }
+  rmSync(path, { recursive: true, force: true });
+}
+
+function installCanonical(force) {
+  if (resolve(sourceSkill) === canonicalSkill) return;
+
+  if (isSkillDirectory(canonicalSkill)) {
+    if (skillDigest(canonicalSkill) === skillDigest(sourceSkill)) return;
+    removeExisting(canonicalSkill, force);
+  } else if (existsSync(canonicalSkill)) {
+    removeExisting(canonicalSkill, force);
+  }
+
+  mkdirSync(dirname(canonicalSkill), { recursive: true });
+  cpSync(sourceSkill, canonicalSkill, { recursive: true });
+}
+
+function installAdapter(agent, force) {
+  const target = adapterPaths[agent];
+  if (!target || target === canonicalSkill) return;
+
+  if (existsSync(target)) {
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      const resolvedLink = resolve(dirname(target), readlinkSync(target));
+      if (resolvedLink === canonicalSkill) return;
+    }
+    removeExisting(target, force);
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  const targetReference =
+    process.platform === "win32"
+      ? canonicalSkill
+      : relative(dirname(target), canonicalSkill);
+  symlinkSync(
+    targetReference,
+    target,
+    process.platform === "win32" ? "junction" : "dir",
+  );
+}
+
+async function chooseAgent() {
+  const explicit = option("--agent");
+  if (explicit) return explicit;
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      "Indica --agent antigravity, --agent claude, --agent codex o --agent all.",
+    );
+  }
+
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await prompt.question(
+    "¿Qué agente usará la skill? [1] Antigravity [2] Claude Code [3] Codex [4] Todos: ",
+  );
+  prompt.close();
+
+  return (
+    { 1: "antigravity", 2: "claude", 3: "codex", 4: "all" }[answer.trim()] ??
+    answer.trim().toLowerCase()
+  );
+}
+
+function validateAgent(agent) {
+  if (!["antigravity", "claude", "codex", "all"].includes(agent)) {
+    throw new Error(`Agente no reconocido: ${agent || "(vacío)"}.`);
+  }
+}
+
+async function installSkill() {
+  const agent = await chooseAgent();
+  validateAgent(agent);
+  const force = process.argv.includes("--force");
+
+  installCanonical(force);
+  if (agent === "all") {
+    installAdapter("claude", force);
+    installAdapter("codex", force);
+  } else {
+    installAdapter(agent, force);
+  }
+
+  console.log("Skill Bacano Figma Web instalada.");
+  console.log(`Fuente canónica: ${relativeDisplay(canonicalSkill)}`);
+  if (agent === "claude" || agent === "all") {
+    console.log(`Claude Code: ${relativeDisplay(adapterPaths.claude)}`);
+  }
+  if (agent === "codex" || agent === "all") {
+    console.log(`Codex: ${relativeDisplay(adapterPaths.codex)}`);
+  }
+  console.log("Ejecuta bacano-figma-web doctor para revisar la conexión.");
+}
+
+function checkPath(name, path) {
+  if (!existsSync(path)) {
+    return { name, path: relativeDisplay(path), status: "missing" };
+  }
+  if (!isSkillDirectory(path)) {
+    return { name, path: relativeDisplay(path), status: "invalid" };
+  }
+  return {
+    name,
+    path: relativeDisplay(path),
+    status:
+      skillDigest(path) === skillDigest(sourceSkill) ? "current" : "outdated",
+    link: lstatSync(path).isSymbolicLink(),
+  };
+}
+
+function skillStatus() {
+  const results = [
+    checkPath("canonical", canonicalSkill),
+    checkPath("antigravity", adapterPaths.antigravity),
+    checkPath("claude", adapterPaths.claude),
+    checkPath("codex", adapterPaths.codex),
+  ];
+  return results.filter(
+    (result, index) =>
+      results.findIndex((candidate) => candidate.path === result.path) ===
+      index,
+  );
+}
+
+function check() {
+  const results = skillStatus();
+  console.table(results);
+  if (results[0]?.status !== "current") {
+    console.error(
+      "Bacano Figma Web no está instalada o está desactualizada. Ejecuta bacano-figma-web install.",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (results.slice(1).some((result) => result.link === false)) {
+    console.warn(
+      "Hay copias físicas en adaptadores. Reinstala con --force para evitar divergencias.",
+    );
+  }
+  if (results.some((result) => result.status === "outdated")) {
+    process.exitCode = 1;
+  }
+}
+
+function canConnect(port, timeout = 250) {
+  return new Promise((finish) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const close = (available) => {
+      socket.destroy();
+      finish(available);
+    };
+    socket.setTimeout(timeout);
+    socket.once("connect", () => close(true));
+    socket.once("timeout", () => close(false));
+    socket.once("error", () => close(false));
+  });
+}
+
+async function doctor() {
+  const bridgeChecks = await Promise.all(
+    Array.from({ length: 10 }, (_, index) => 9223 + index).map(
+      async (port) => ({
+        port,
+        available: await canConnect(port),
+      }),
+    ),
+  );
+  const report = {
+    skill: skillStatus()[0]?.status ?? "missing",
+    officialRemoteMcp: "verify-in-agent",
+    officialDesktopMcp: (await canConnect(3845))
+      ? "detected-on-127.0.0.1:3845"
+      : "not-detected",
+    communityBridgePorts: bridgeChecks
+      .filter((result) => result.available)
+      .map((result) => result.port),
+    restToken: process.env.FIGMA_ACCESS_TOKEN ? "configured" : "not-configured",
+  };
+
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("Diagnóstico Bacano Figma Web");
+  console.table([
+    { control: "Skill instalada", result: report.skill },
+    {
+      control: "MCP remoto oficial",
+      result: "Verificar OAuth y whoami dentro del agente",
+    },
+    { control: "MCP local oficial", result: report.officialDesktopMcp },
+    {
+      control: "Desktop Bridge comunitario",
+      result: report.communityBridgePorts.length
+        ? `Puerto(s) detectado(s): ${report.communityBridgePorts.join(", ")}`
+        : "No detectado",
+    },
+    { control: "Token REST (solo presencia)", result: report.restToken },
+  ]);
+  console.log(
+    "Este diagnóstico no lee secretos ni puede certificar el OAuth del cliente MCP.",
+  );
+}
+
+const command = process.argv[2] ?? "help";
+
+try {
+  if (command === "install") await installSkill();
+  else if (command === "check") check();
+  else if (command === "doctor") await doctor();
+  else if (command === "validate-snapshot")
+    validateSnapshot(process.argv[3], projectRoot);
+  else usage();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/skills/bacano-figma-web/scripts/snapshot.mjs

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+function object(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateFrame(frame, path, errors) {
+  if (!object(frame)) {
+    errors.push(`${path} debe ser un objeto.`);
+    return;
+  }
+  if (typeof frame.nodeId !== "string" && typeof frame.url !== "string") {
+    errors.push(`${path} requiere nodeId o url.`);
+  }
+}
+
+function inspectSecrets(value, errors, path = "manifest") {
+  const secretNames = new Set([
+    "accesstoken",
+    "authorization",
+    "cookie",
+    "password",
+    "personalaccesstoken",
+    "secret",
+  ]);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      inspectSecrets(item, errors, `${path}[${index}]`),
+    );
+    return;
+  }
+  if (!object(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (secretNames.has(key.toLowerCase())) {
+      errors.push(`${path}.${key} no puede contener secretos.`);
+    }
+    inspectSecrets(child, errors, `${path}.${key}`);
+  }
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+  const adapters = new Set([
+    "figma-official",
+    "figma-desktop",
+    "desktop-bridge",
+    "rest-snapshot",
+  ]);
+  const capabilities = new Set(["available", "partial", "missing"]);
+  const pageStatuses = new Set([
+    "pending",
+    "extracted",
+    "implemented",
+    "validated",
+  ]);
+
+  if (!object(manifest)) return ["El manifiesto debe ser un objeto JSON."];
+  if (manifest.schemaVersion !== 1) errors.push("schemaVersion debe ser 1.");
+  if (typeof manifest.project !== "string" || !manifest.project.trim()) {
+    errors.push("project es obligatorio.");
+  }
+  if (!object(manifest.source)) {
+    errors.push("source es obligatorio.");
+  } else {
+    if (!adapters.has(manifest.source.adapter)) {
+      errors.push("source.adapter no es compatible.");
+    }
+    if (
+      typeof manifest.source.extractedAt !== "string" ||
+      Number.isNaN(Date.parse(manifest.source.extractedAt))
+    ) {
+      errors.push("source.extractedAt debe ser una fecha ISO válida.");
+    }
+  }
+  if (manifest.capabilities !== undefined) {
+    if (!object(manifest.capabilities)) {
+      errors.push("capabilities debe ser un objeto.");
+    } else {
+      for (const [name, status] of Object.entries(manifest.capabilities)) {
+        if (!capabilities.has(status)) {
+          errors.push(`capabilities.${name} no tiene un estado válido.`);
+        }
+      }
+    }
+  }
+  if (!Array.isArray(manifest.pages) || manifest.pages.length === 0) {
+    errors.push("pages requiere al menos una página.");
+  } else {
+    const routes = new Set();
+    manifest.pages.forEach((page, index) => {
+      const path = `pages[${index}]`;
+      if (!object(page)) {
+        errors.push(`${path} debe ser un objeto.`);
+        return;
+      }
+      if (typeof page.route !== "string" || !page.route.startsWith("/")) {
+        errors.push(`${path}.route debe comenzar por /.`);
+      } else if (routes.has(page.route)) {
+        errors.push(`${path}.route está duplicada.`);
+      } else {
+        routes.add(page.route);
+      }
+      if (typeof page.name !== "string" || !page.name.trim()) {
+        errors.push(`${path}.name es obligatorio.`);
+      }
+      if (!pageStatuses.has(page.status)) {
+        errors.push(`${path}.status no es válido.`);
+      }
+      if (!page.desktop && !page.mobile) {
+        errors.push(`${path} requiere un frame desktop o mobile.`);
+      }
+      if (page.desktop) validateFrame(page.desktop, `${path}.desktop`, errors);
+      if (page.mobile) validateFrame(page.mobile, `${path}.mobile`, errors);
+    });
+  }
+  inspectSecrets(manifest, errors);
+  return errors;
+}
+
+export function validateSnapshot(path, projectRoot) {
+  if (!path) throw new Error("Indica la ruta de manifest.json.");
+  const manifestPath = resolve(projectRoot, path);
+  if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) {
+    throw new Error(`No existe el manifiesto: ${path}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const errors = validateManifest(manifest);
+  if (errors.length) {
+    console.error("Snapshot inválido:");
+    for (const error of errors) console.error(`- ${error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Snapshot válido: ${relative(projectRoot, manifestPath)}`);
+  console.log(
+    `${manifest.pages.length} página(s), fuente ${manifest.source.adapter}.`,
+  );
+}

package/skills/bacano-web/scripts/postinstall.mjs

@@ -4,5 +4,9 @@ if (!process.env.CI && process.env.BACANO_SDK_HIDE_SKILL_NOTICE !== "1") {
 Instálala una vez:       pnpm exec bacano-web install --agent all
 Verifica su estado:      pnpm exec bacano-web check
 Luego invócala desde tu agente para iniciar la auditoría.
+
+Para implementar un diseño Figma con el cascarón Bacano:
+Instala la skill:        pnpm exec bacano-figma-web install --agent all
+Revisa la conexión:      pnpm exec bacano-figma-web doctor
 `);
 }