fractalia-faro 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# fractalia-faro · Wizard inicial de repos Fractalia
+
+> CLI **PRE-harness** e independiente de él: el harness vive DENTRO de cada repo ya creado; este wizard es quien **crea** el repo. Pensado para usuarios no técnicos: un solo comando, sin paths ni git a mano.
+
+```
+npx fractalia-faro
+```
+
+## Qué hace, paso a paso
+
+1. **Sesión GitHub**: si no estás logueado, te guía (device flow con código en el navegador, o token personal). Se hace UNA vez por máquina; queda guardado en `~/.fractalia-cli.json`.
+2. **Valida la organización**: comprueba vía API que eres **miembro activo** de la organización destino (p. ej. `CAS-IA`). Si no lo eres, te dice a quién pedir acceso y para. Como los templates son privados de la org, sin membresía no hay acceso posible.
+3. **Clasifica** lo que arrancas, explicándote las diferencias:
+
+| Tipo | Prefijo de repo | Qué es |
+|---|---|---|
+| Servicio de la plataforma Core | `core-serv-` | Operación continua de Core; no se cierra, se opera y evoluciona |
+| Funcionalidad de la plataforma Core | `core-func-` | Funcionalidad acotada que se añade a Core; se entrega y se integra |
+| Proyecto | `prj-` | Fin definido, entregables y fechas (grande o pequeño = más o menos fases) |
+| Iniciativa | `ini-` | Exploración/mejora con alcance aún abierto |
+
+4. **Naturaleza → template**: documental/gestión → `template-faro-doc` · código (worker Cloudflare) → `template-faro-worker`. El catálogo puede sobreescribirse desde la org (`fractalia-templates/catalog.json`) sin republicar el CLI.
+5. **Nomenclatura**: aplica el prefijo al nombre (`core-serv-notificaciones`), valida que el repo no exista.
+6. **Crea el repo** privado en la org desde el template (API nativa `generate`), crea la rama `develop` y la deja **por defecto** (main queda como rama de aprobación).
+7. **Clona en local** en la carpeta que elijas (default recordado), con el remote limpio (el token no queda en la URL).
+8. **ClickUp API key personal** (opcional): la guarda en `git config --global clickup.token` — vale para todos tus repos y da atribución correcta.
+9. **Abre VS Code** en la carpeta. Al abrir Claude Code dentro, el harness del template arranca su onboarding (fasear, funcional, riesgos), ya con conciencia del **tipo** por el prefijo del repo.
+
+## Probar sin crear nada
+
+```
+node bin/crear.mjs --dry-run
+```
+
+Simula todo el asistente (sin login ni API) y muestra el plan.
+
+## Primer uso — guía para el usuario nuevo, paso a paso
+
+**Dónde "vive" el wizard**: el código fuente está en este repo (privado de la org); el paquete ejecutable se **publica en npm** (registro público, sin secretos dentro). `npx` no va a GitHub: busca `fractalia-faro` en npm, lo descarga a una caché temporal y lo ejecuta. No se instala nada del wizard y siempre corre la última versión publicada. *(Alternativa sin npm: hacer público solo este repo y usar `npx github:CAS-IA/faro-cli`.)*
+
+**Paso 0 · Prerrequisitos de la máquina (una sola vez).** Tres herramientas; en Windows se instalan pegando esto en PowerShell (o ejecutando `kit/instalar-fractalia.ps1`, que lo hace solo):
+
+```powershell
+winget install OpenJS.NodeJS.LTS   # Node (trae npx)
+winget install Git.Git             # git (para clonar)
+winget install Microsoft.VisualStudioCode   # si no lo tiene ya
+```
+
+**Paso 1 · Invitación a la organización.** El administrador te invita (GitHub → org → People → Invite member); aceptas el email con tu cuenta GitHub (si no tienes, créala gratis en github.com).
+
+**Paso 2 · Ejecutar el wizard.** Abre VS Code → Terminal → New Terminal y pega:
+
+```
+npx fractalia-faro
+```
+
+La primera vez npx pregunta `Ok to proceed? (y)` → responde `y`.
+
+**Paso 3 · Login GitHub (solo la primera vez en cada máquina).** El wizard te da un código y abre `github.com/login/device`: inicias sesión con tu cuenta corporativa, tecleas el código y autorizas. Queda guardado en `~/.fractalia-cli.json`.
+
+**Paso 4 · Contesta al asistente.** Qué es (te explica servicio Core / funcionalidad Core / proyecto / iniciativa), nombre en lenguaje normal (él lo sanitiza y aplica el prefijo), carpeta local, y ClickUp key si quieres.
+
+**Paso 5 · A trabajar.** El wizard deja el repo creado en la org (main + develop, develop por defecto), clonado en tu carpeta **ya en develop**, y VS Code abierto. Dentro, abre Claude Code: el harness del repo arranca su onboarding y desde ahí te gobierna el trabajo.
+
+Las siguientes veces: solo el paso 2 (mismo comando, sin login ni preguntas de npx).
+
+## Requisitos del usuario (resumen)
+
+- Node 18+ y git instalados; VS Code con comando `code` (lo instala VS Code por defecto).
+- Cuenta GitHub **dentro de la organización** (el wizard te dice si no lo estás).
+
+## Configuración de administrador (una vez)
+
+1. Subir `template-faro-doc` y `template-faro-worker` a la organización y marcarlos como **Template repository** (Settings → General).
+2. (Opcional, mejor UX) Crear una **OAuth App** en la org para el device flow y distribuir su `client_id` (`FRACTALIA_CLIENT_ID` o `client_id` en `~/.fractalia-cli.json`). Sin ella, el wizard pide un PAT.
+3. (Opcional) Repo `fractalia-templates` con `catalog.json` (`{ "tipos": {...}, "naturalezas": {...} }`) para gobernar tipos/prefijos/templates sin tocar el CLI.
+4. Publicar este paquete en npm (`npm publish --access public`): no contiene secretos, solo lógica.
+5. **Secrets globales** (p. ej. `DIRECTUS_TOKEN`): como *organization secrets* de GitHub Actions (write-only, nadie puede leerlos) — los usan los workflows de los repos creados, nunca la máquina del usuario.
+
+## ⚠ Requisito de plan GitHub (verificado contra la documentación)
+
+En el plan **Free**, los repos **privados** NO tienen: (a) acceso a *organization secrets* desde Actions, ni (b) *branch protection* / rulesets. Es decir: con org Free, la publicación a Directus con secret de org y la protección en servidor de `main` **no funcionan** (el harness sigue protegiendo main en local, eso no depende del plan). Para el diseño completo hace falta **GitHub Team**. Verifícalo antes del despliegue.
+
+## Sincronización del estándar (anti-deriva)
+
+La API `generate` de GitHub crea una **copia congelada**: los repos derivados no se enteran de las mejoras del template. Por eso el wizard estampa en cada repo creado un `.fractalia-template.json` (de qué template y de qué commit salió — patrón `copier`/`.copier-answers`). Con ese metadato, el plan de sync es añadir a los templates el workflow **actions-template-sync**, que abre PRs automáticos en los repos derivados cuando el template evoluciona.
+
+## Roadmap
+
+- Workflow `actions-template-sync` en los templates (cierra el ciclo anti-deriva de arriba).
+- Registro central de repos generados (índice ligero en la org, estilo catálogo Backstage).
+- Modo **no interactivo** por flags (`--tipo= --nombre= --naturaleza= --si`) para CI y agentes, y cancelación limpia con Ctrl-C (patrón create-vite).
+- Adaptador GitLab (misma capa de proveedor).
+- Broker Cloudflare Worker para secretos compartidos usables desde local (Directus push bajo demanda).
+- Extensión VS Code fina que envuelva este CLI con formulario gráfico.

package/bin/crear.mjs

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+// fractalia-faro — Wizard INICIAL de creación de repos (PRE-harness).
+// Pieza independiente: el harness vive DENTRO de cada repo ya creado; este CLI es quien lo crea.
+// Flujo: clasificar (con explicaciones) -> nomenclatura -> login GitHub -> validar organización
+//        -> crear repo desde el template -> ramas main+develop -> clonar en local -> ClickUp key -> abrir VS Code.
+// Sin dependencias. Node >= 18 (usa fetch nativo).
+'use strict';
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
+
+// ---------- Catálogo de tipos (nomenclatura + explicación para clasificar) ----------
+// El prefijo del repo garantiza la coherencia del catálogo de la organización.
+// Si existe fractalia-templates/catalog.json en la org, SOBREESCRIBE este catálogo embebido.
+// PLATAFORMAS de producto Fractalia. Core = plataforma PRINCIPAL (primera); el resto son
+// soluciones transversales (Orbital, y las que vengan). EXTENSIBLE: añade una entrada aquí (o en
+// el catalog.json de la org) y aparece con su -serv y -func. Los tipos de plataforma llevan
+// `soloOwner: true` -> en el menú solo se ofrecen a owners/admins de la org (crear una capacidad
+// de plataforma es estratégico); siguen accesibles por flag (--tipo) para automatización.
+const PLATAFORMAS = [
+  { id: 'core', nombre: 'Core', nota: 'plataforma principal' },
+  { id: 'orbital', nombre: 'Orbital', nota: 'solución transversal' },
+];
+const CATALOGO = {};
+for (const p of PLATAFORMAS) {
+  CATALOGO[`${p.id}-serv`] = {
+    etiqueta: `Servicio de ${p.nombre}`, prefijo: `${p.id}-serv-`, soloOwner: true,
+    explica: `Servicio de la plataforma ${p.nombre} (${p.nota}): operación CONTINUA, sin fecha de fin. No "se termina": se opera y evoluciona.`,
+    ejemplos: `servicio de notificaciones de ${p.nombre}, motor de ingesta de ${p.nombre}`,
+  };
+  CATALOGO[`${p.id}-func`] = {
+    etiqueta: `Funcionalidad de ${p.nombre}`, prefijo: `${p.id}-func-`, soloOwner: true,
+    explica: `Funcionalidad CONCRETA que se añade a la plataforma ${p.nombre}. Alcance acotado: se entrega y se integra en ${p.nombre}.`,
+    ejemplos: `exportación a Excel en ${p.nombre}, nueva vista en ${p.nombre}`,
+  };
+}
+// Tipos transversales (para todos los miembros).
+CATALOGO.proyecto = {
+  etiqueta: 'Proyecto',
+  prefijo: 'prj-',
+  explica: 'Trabajo con FIN definido: objetivo, entregables y fechas; se cierra al terminar. Grande o pequeño solo cambia el número de fases. Si YA sabes que acabará en producto, empieza aquí.',
+  ejemplos: 'implantar CRM, migración a proveedor X, onboarding de cliente Y',
+};
+CATALOGO.iniciativa = {
+  etiqueta: 'Iniciativa / investigación',
+  prefijo: 'ini-',
+  explica: 'Exploración, estudio o investigación con alcance AÚN abierto (mercado, técnica, viabilidad). Si cristaliza en producto, se CONVIERTE en proyecto o servicio (se registra la decisión como ADR y, si cambia la naturaleza, se crea el repo destino). Úsala cuando el resultado es CONOCIMIENTO, no todavía un producto.',
+  ejemplos: 'estudiar automatización de altas, investigación de mercado, piloto de agentes IA',
+};
+
+// Naturaleza del trabajo -> repo template a clonar (independiente del tipo/nomenclatura).
+const NATURALEZAS = {
+  documental: {
+    etiqueta: 'Documental / gestión (sin código)',
+    template: 'template-faro-doc',
+    explica: 'Documentación funcional, specs, faseo, informes. El estándar FARO documental.',
+  },
+  codigo: {
+    etiqueta: 'Código: aplicación / worker Cloudflare',
+    template: 'template-faro-worker',
+    explica: 'App Cloudflare Workers con gestión faseada encima (harness FARO de código: gates, openspec, deploy).',
+  },
+};
+
+const CONFIG_PATH = path.join(os.homedir(), '.fractalia-cli.json');
+const API = 'https://api.github.com';
+
+// ---------- CLI args ----------
+const args = process.argv.slice(2);
+const DRY = args.includes('--dry-run');
+const argVal = (name) => {
+  const a = args.find((x) => x.startsWith(`--${name}=`));
+  return a ? a.split('=').slice(1).join('=') : null;
+};
+
+const argFlag = (name) => args.includes(`--${name}`);
+const NO_OPEN = argFlag('no-open');
+const YES = argFlag('yes') || argFlag('si');
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+fractalia-faro — asistente de nuevo proyecto/iniciativa/servicio Fractalia
+
+Uso:  npx fractalia-faro [opciones]
+
+Interactivo (por defecto):  npx fractalia-faro
+
+No interactivo (para CI o power users): pasa todo por flags
+  npx fractalia-faro --org=CAS-IA --tipo=core-serv --naturaleza=documental \\
+      --nombre="Notificaciones Core" --dir=H:/PROYECTOS --yes
+
+Opciones:
+  --org=<nombre>        Organización GitHub destino (si no, se pregunta/recuerda).
+  --tipo=<id>           core-serv | core-func | orbital-serv | orbital-func | proyecto | iniciativa
+  --naturaleza=<id>     documental | codigo
+  --nombre=<texto>      Nombre del trabajo (se sanitiza y se le aplica el prefijo).
+  --dir=<ruta>          Carpeta donde clonar (si no, se pregunta/recuerda).
+  --team=<slug>         Asigna el repo a un equipo GitHub (control de visibilidad).
+  --yes / --si          No pide confirmaciones (asume "sí").
+  --no-open             No abre VS Code al terminar.
+  --dry-run             Simula todo SIN crear nada (ni login): valida el flujo.
+  --help                Esta ayuda.
+
+Qué hace: clasifica lo que arrancas, aplica la nomenclatura oficial, inicia sesión
+en GitHub (device flow), valida tu pertenencia a la organización, crea el repo desde
+el template, crea main+develop (develop por defecto), intenta proteger main en
+servidor (si el plan lo permite), lo clona, guarda tu ClickUp key y abre VS Code.
+`);
+  process.exit(0);
+}
+
+// Cancelacion limpia (Ctrl-C) — no deja el terminal a medias (patron create-vite).
+let _rlRef = null;
+const cancelar = () => { if (_rlRef) { try { _rlRef.close(); } catch {} } console.log('\n\n  Cancelado. No se ha creado nada nuevo.\n'); process.exit(130); };
+process.on('SIGINT', cancelar);
+
+// ---------- UI helpers (colores ANSI + caracteres de caja, sin dependencias; se apagan sin TTY) ----------
+const C = process.stdout.isTTY
+  ? { g: '\x1b[32m', y: '\x1b[33m', r: '\x1b[31m', c: '\x1b[36m', b: '\x1b[1m', d: '\x1b[2m', x: '\x1b[0m' }
+  : { g: '', y: '', r: '', c: '', b: '', d: '', x: '' };
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+_rlRef = rl;
+const say = (s = '') => console.log(s);
+const ok = (s) => console.log(`  ${C.g}✔${C.x} ${s}`);
+const warn = (s) => console.log(`  ${C.y}⚠${C.x} ${s}`);
+const fail = (s) => { console.error(`  ${C.r}✖${C.x} ${s}`); process.exitCode = 1; };
+
+// Ancho visible de un texto (ignora los codigos ANSI para alinear cajas).
+const vis = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+const W = 66;
+// Caja con titulo opcional y lineas dentro (centra el marco, respeta el color).
+function caja(lineas, { color = C.c, titulo = '' } = {}) {
+  const top = titulo ? `╭─ ${C.b}${titulo}${C.x}${color} ${'─'.repeat(Math.max(0, W - 4 - vis(titulo).length))}╮` : `╭${'─'.repeat(W)}╮`;
+  say(`${color}${top}${C.x}`);
+  for (const l of lineas) { const pad = Math.max(0, W - 2 - vis(l).length); say(`${color}│${C.x} ${l}${' '.repeat(pad)} ${color}│${C.x}`); }
+  say(`${color}╰${'─'.repeat(W)}╯${C.x}`);
+}
+// Encabezado de paso: "Paso N/T · titulo" con separacion visual.
+let _pasoN = 0; const _pasoT = 6;
+function paso(titulo) { _pasoN++; say(''); say(`${C.c}${C.b}▸ Paso ${_pasoN}/${_pasoT}${C.x}  ${C.b}${titulo}${C.x}`); say(`${C.d}${'─'.repeat(W + 2)}${C.x}`); }
+
+async function pregunta(q, defecto) {
+  const suf = defecto ? ` ${C.d}[${defecto}]${C.x}` : '';
+  const r = (await rl.question(`${C.b}?${C.x} ${q}${suf}: `)).trim();
+  return r || defecto || '';
+}
+// Confirmación s/n (respeta --yes).
+async function confirma(q, def = 's') {
+  if (YES) return true;
+  return (await pregunta(`${q} (s/n)`, def)).toLowerCase().startsWith('s');
+}
+
+// Menú numerado con explicación por opción. Si `preseleccion` (de un flag) casa con una clave, la usa sin preguntar.
+async function elige(titulo, opciones, preseleccion) {
+  const keys = Object.keys(opciones);
+  if (preseleccion) {
+    if (keys.includes(preseleccion)) return preseleccion;
+    fail(`Valor '${preseleccion}' no válido. Opciones: ${keys.join(', ')}.`); rl.close(); process.exit(1);
+  }
+  say(`\n${C.b}${titulo}${C.x}\n`);
+  keys.forEach((k, i) => {
+    const o = opciones[k];
+    say(`   ${C.c}${C.b}${i + 1}${C.x}  ${C.b}${o.etiqueta}${C.x}${o.prefijo ? `  ${C.d}→${C.x}  ${C.g}${o.prefijo}<nombre>${C.x}` : ''}`);
+    say(`      ${C.d}${o.explica}${C.x}`);
+    if (o.ejemplos) say(`      ${C.d}Ej.: ${o.ejemplos}${C.x}`);
+    say('');
+  });
+  for (;;) {
+    const r = (await rl.question(`${C.b}?${C.x} Elige 1-${keys.length}: `)).trim();
+    const n = Number.parseInt(r, 10);
+    if (n >= 1 && n <= keys.length) return keys[n - 1];
+    say('  Respuesta no válida.');
+  }
+}
+
+// Comprobación de prerrequisitos de la máquina (una vez, antes de nada).
+function tieneCmd(bins) { for (const b of bins) { try { execFileSync(b, ['--version'], { stdio: 'ignore', timeout: 8000 }); return true; } catch {} } return false; }
+function checkPrerrequisitos() {
+  const falta = [];
+  if (!tieneCmd(['git'])) falta.push('Git (winget install Git.Git)');
+  if (!tieneCmd(['code', 'code.cmd'])) warn('VS Code (comando "code") no detectado — al final tendrás que abrir la carpeta a mano.');
+  if (falta.length) { fail(`Falta instalar: ${falta.join(' · ')}. Instálalo y vuelve a ejecutar (o usa kit/instalar-fractalia.ps1).`); rl.close(); process.exit(1); }
+}
+
+const slugify = (s) => s
+  .toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+  .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+
+// ---------- config local (~/.fractalia-cli.json) ----------
+function loadConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')); } catch { return {}; }
+}
+function saveConfig(cfg) {
+  try { fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 }); } catch {}
+}
+
+// ---------- GitHub API ----------
+async function gh(token, ruta, init = {}) {
+  const res = await fetch(`${API}${ruta}`, {
+    ...init,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+      ...(init.headers || {}),
+    },
+  });
+  const text = await res.text();
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { body = text; }
+  return { status: res.status, ok: res.ok, body };
+}
+
+// Login SIN contraseñas: GitHub Device Flow (requiere una OAuth App de la org; solo client_id, sin secreto).
+async function deviceFlow(clientId) {
+  const form = (o) => Object.entries(o).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&');
+  const post = async (url, data) => {
+    const res = await fetch(url, { method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' }, body: form(data) });
+    return res.json();
+  };
+  const d = await post('https://github.com/login/device/code', { client_id: clientId, scope: 'repo read:org' });
+  if (!d.device_code) throw new Error(`device flow: ${JSON.stringify(d)}`);
+  say(`\n  1) Abre en el navegador:  ${d.verification_uri}`);
+  say(`  2) Inicia sesión con tu cuenta corporativa y teclea el código:  ${d.user_code}\n`);
+  const intervalo = (d.interval || 5) * 1000;
+  for (;;) {
+    await new Promise((r) => setTimeout(r, intervalo));
+    const t = await post('https://github.com/login/oauth/access_token', {
+      client_id: clientId, device_code: d.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    });
+    if (t.access_token) return t.access_token;
+    if (t.error && t.error !== 'authorization_pending' && t.error !== 'slow_down') throw new Error(`device flow: ${t.error}`);
+  }
+}
+
+// Cascada de autenticación: env -> token guardado -> gh CLI -> device flow (si hay client_id) -> pegar PAT.
+async function obtenerToken(cfg) {
+  const candidatos = [];
+  if (process.env.FRACTALIA_GITHUB_TOKEN) candidatos.push(['variable de entorno FRACTALIA_GITHUB_TOKEN', process.env.FRACTALIA_GITHUB_TOKEN]);
+  if (process.env.GITHUB_TOKEN) candidatos.push(['variable de entorno GITHUB_TOKEN', process.env.GITHUB_TOKEN]);
+  if (cfg.token) candidatos.push(['sesión guardada (~/.fractalia-cli.json)', cfg.token]);
+  try {
+    const t = execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 8000 }).trim();
+    if (t) candidatos.push(['GitHub CLI (gh auth token)', t]);
+  } catch {}
+  for (const [via, tok] of candidatos) {
+    const me = await gh(tok, '/user');
+    if (me.ok) { ok(`Sesión GitHub válida vía ${via}: @${me.body.login}`); return { token: tok, login: me.body.login }; }
+  }
+  const clientId = cfg.client_id || process.env.FRACTALIA_CLIENT_ID;
+  if (clientId) {
+    say('\nNecesitas iniciar sesión en GitHub (una sola vez en esta máquina).');
+    const tok = await deviceFlow(clientId);
+    const me = await gh(tok, '/user');
+    if (!me.ok) throw new Error('el token del device flow no valida');
+    cfg.token = tok; saveConfig(cfg);
+    ok(`Sesión iniciada: @${me.body.login} (guardada para próximas veces)`);
+    return { token: tok, login: me.body.login };
+  }
+  say('\nNo hay sesión de GitHub. Crea un token personal (PAT clásico, scopes: repo + read:org)');
+  say('en https://github.com/settings/tokens y pégalo aquí (queda guardado en tu máquina).');
+  const tok = await pregunta('Token de GitHub (ghp_...)');
+  const me = await gh(tok, '/user');
+  if (!me.ok) throw new Error('el token pegado no es válido');
+  cfg.token = tok; saveConfig(cfg);
+  ok(`Sesión iniciada: @${me.body.login} (guardada para próximas veces)`);
+  return { token: tok, login: me.body.login };
+}
+
+// Catálogo remoto opcional: <org>/fractalia-templates:catalog.json manda sobre el embebido.
+async function cargarCatalogo(token, org) {
+  try {
+    const r = await gh(token, `/repos/${org}/fractalia-templates/contents/catalog.json`);
+    if (r.ok && r.body && r.body.content) {
+      const remoto = JSON.parse(Buffer.from(r.body.content, 'base64').toString('utf8'));
+      if (remoto.tipos) { ok('Catálogo de tipos cargado desde la organización (fractalia-templates/catalog.json).'); return { tipos: remoto.tipos, naturalezas: remoto.naturalezas || NATURALEZAS }; }
+    }
+  } catch {}
+  return { tipos: CATALOGO, naturalezas: NATURALEZAS };
+}
+
+const run = (cmd, argv, opts = {}) => execFileSync(cmd, argv, { stdio: 'inherit', ...opts });
+
+// Clona el repo en local, estampa metadatos de origen, guarda ClickUp key y abre VS Code.
+// Compartida por el flujo normal y por el RESUME (repo ya existente).
+async function finalizarLocal(auth, org, repoName, baseDir, destino, nat, tipo, naturaleza) {
+  fs.mkdirSync(baseDir, { recursive: true });
+  if (fs.existsSync(destino)) { warn(`La carpeta ${destino} ya existe: no la sobrescribo. Abre ahí a mano si es el clon.`); }
+  else {
+    run('git', ['clone', `https://x-access-token:${auth.token}@github.com/${org}/${repoName}.git`, destino]);
+    run('git', ['-C', destino, 'remote', 'set-url', 'origin', `https://github.com/${org}/${repoName}.git`]);
+    ok(`Clonado en ${destino}`);
+    // Metadatos de ORIGEN del template (patron copier): de que template y commit salio -> habilita sync futuro.
+    try {
+      const head = await gh(auth.token, `/repos/${org}/${nat.template}/commits?per_page=1`);
+      const meta = { template: `${org}/${nat.template}`, template_commit: (head.ok && head.body[0] && head.body[0].sha) || null, tipo, naturaleza, organizacion: org, generador: 'fractalia-faro' };
+      const mp = path.join(destino, '.fractalia-template.json');
+      if (!fs.existsSync(mp)) {
+        fs.writeFileSync(mp, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+        run('git', ['-C', destino, 'add', '.fractalia-template.json'], { stdio: 'ignore' });
+        run('git', ['-C', destino, 'commit', '-m', 'chore: metadatos de origen del template (habilita sync del estandar)'], { stdio: 'ignore' });
+        run('git', ['-C', destino, 'push'], { stdio: 'ignore' });
+        ok('Metadatos de template guardados (.fractalia-template.json).');
+      }
+    } catch { warn('No pude estampar los metadatos del template (no bloquea).'); }
+  }
+  // ClickUp API key personal (opcional; el harness del repo la usará).
+  let cuToken = null;
+  try { cuToken = execFileSync('git', ['config', '--global', 'clickup.token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+  if (!cuToken && !YES) {
+    const cu = await pregunta('ClickUp API key personal (pk_..., Enter para omitir)');
+    if (cu) { run('git', ['config', '--global', 'clickup.token', cu]); ok('ClickUp key guardada en tu git config global (vale para todos tus repos).'); }
+  } else if (cuToken) ok('ClickUp key personal ya configurada en esta máquina.');
+  // Abrir VS Code (salvo --no-open).
+  if (NO_OPEN) { ok(`Listo. Abre la carpeta: ${destino}`); return; }
+  let abierto = false;
+  for (const bin of ['code', 'code.cmd']) { try { execFileSync(bin, [destino], { stdio: 'ignore' }); abierto = true; break; } catch {} }
+  if (abierto) ok('Abriendo VS Code…');
+  else warn(`No pude abrir VS Code automáticamente: abre la carpeta ${destino} a mano.`);
+}
+
+// ---------- flujo principal ----------
+async function main() {
+  say('');
+  caja([
+    `${C.b}🧭  Fractalia · asistente de nuevo repositorio${C.x}`,
+    `${C.d}Crea el repo con la nomenclatura oficial, ramas main+develop${C.x}`,
+    `${C.d}y te lo deja clonado y listo para trabajar con Claude Code.${C.x}`,
+  ]);
+  if (DRY) { say(''); warn(`${C.y}MODO SIMULACIÓN (--dry-run): no se crea nada.${C.x}`); }
+  if (!DRY) checkPrerrequisitos();
+
+  const cfg = loadConfig();
+
+  // 1. Sesión GitHub + organización (en dry-run se omite el login).
+  let auth = { token: null, login: '(dry-run)' };
+  let org = argVal('org') || cfg.org || '';
+  if (!DRY) {
+    auth = await obtenerToken(cfg);
+    if (!org) {
+      const orgs = await gh(auth.token, '/user/orgs');
+      const nombres = (orgs.ok && orgs.body.map((o) => o.login)) || [];
+      if (nombres.length === 1) org = nombres[0];
+      else if (nombres.length > 1) {
+        const opciones = Object.fromEntries(nombres.map((n) => [n, { etiqueta: n, explica: 'organización GitHub de la que eres miembro' }]));
+        org = await elige('¿En qué organización se crea el repo?', opciones);
+      } else org = await pregunta('Organización GitHub destino');
+    }
+    // 2. Validar pertenencia a la organización (los templates son privados: sin membresía no hay acceso).
+    const memb = await gh(auth.token, `/user/memberships/orgs/${org}`);
+    if (!memb.ok || memb.body.state !== 'active') {
+      fail(`No eres miembro activo de la organización '${org}'. Pide acceso al administrador y vuelve a ejecutar el asistente.`);
+      rl.close(); return;
+    }
+    auth.esOwner = memb.body.role === 'admin'; // 'admin' = owner de la organización
+    ok(`Miembro de '${org}' verificado (@${auth.login}) · rol: ${auth.esOwner ? 'OWNER/admin' : 'member'}.`);
+    cfg.org = org; saveConfig(cfg);
+  } else if (!org) {
+    org = await pregunta('Organización GitHub destino (simulación)', 'fractalia');
+  }
+  const esOwner = DRY ? true : !!auth.esOwner; // en dry-run se muestran todas las opciones
+
+  // 3. Clasificación con explicaciones (¿qué estás arrancando?). Los flags --tipo/--naturaleza saltan la pregunta.
+  const catalogo = DRY ? { tipos: CATALOGO, naturalezas: NATURALEZAS } : await cargarCatalogo(auth.token, org);
+  const tipoFlag = argVal('tipo');
+  // Menú filtrado por rol: los tipos de plataforma (soloOwner) solo se MUESTRAN a owners.
+  // Con --tipo (flag) se usa el catálogo completo (guía, no candado).
+  const menuTipos = tipoFlag ? catalogo.tipos
+    : Object.fromEntries(Object.entries(catalogo.tipos).filter(([, v]) => esOwner || !v.soloOwner));
+  if (!esOwner && !tipoFlag) say(`\n${C.d}(Los tipos de plataforma —servicios/funcionalidades de Core, Orbital…— los crean owners de la organización; no aparecen abajo.)${C.x}`);
+  const tipo = await elige('¿Qué vas a arrancar? (elige por lo que ES, no por el tamaño)', menuTipos, tipoFlag);
+  const t = catalogo.tipos[tipo];
+  const naturaleza = await elige('¿Qué naturaleza tiene el trabajo?', catalogo.naturalezas, argVal('naturaleza'));
+  const nat = catalogo.naturalezas[naturaleza];
+
+  // 4. Nombre + nomenclatura oficial (--nombre lo pasa directo).
+  let repoName = '';
+  const nombreFlag = argVal('nombre');
+  for (;;) {
+    const bruto = nombreFlag || await pregunta(`Nombre corto (sin prefijo; ej. "${(t.ejemplos || 'mi-tema').split(',')[0].trim().split(' ').slice(-2).join('-')}")`);
+    const slug = slugify(bruto);
+    if (!slug) { if (nombreFlag) { fail('El --nombre no produce un slug válido.'); rl.close(); return; } say('  Nombre vacío o inválido.'); continue; }
+    repoName = `${t.prefijo}${slug}`;
+    say(`  → nombre de repo según nomenclatura: ${C.g}${org}/${repoName}${C.x}`);
+    if (nombreFlag || await confirma('¿Correcto?')) break;
+  }
+
+  // 5. Carpeta local de trabajo (--dir lo pasa directo).
+  const defDir = cfg.workdir || path.join(os.homedir(), 'PROYECTOS');
+  const baseDir = argVal('dir') || await pregunta('Carpeta donde clonarlo', defDir);
+  const destino = path.join(baseDir, repoName);
+  cfg.workdir = baseDir; saveConfig(cfg);
+
+  // Resumen previo en caja.
+  say('');
+  caja([
+    `${C.d}Tipo${C.x}       ${t.etiqueta} ${C.d}(${tipo})${C.x}`,
+    `${C.d}Naturaleza${C.x} ${nat.etiqueta}`,
+    `${C.d}Template${C.x}   ${org}/${nat.template}`,
+    `${C.d}Repo nuevo${C.x} ${C.g}${org}/${repoName}${C.x} ${C.d}· privado · main + develop${C.x}`,
+    `${C.d}Clon en${C.x}    ${destino}`,
+  ], { titulo: 'Resumen', color: C.g });
+  say('');
+  if (DRY) { ok('(dry-run) Flujo validado — no se ha creado nada.'); say(''); rl.close(); return; }
+  if (!(await confirma('¿Adelante?'))) { rl.close(); return; }
+  say('');
+
+  // 6. Crear el repo desde el template (API nativa de GitHub "generate").
+  // RESUME: si ya existe (ejecucion previa interrumpida), ofrecer clonarlo en vez de morir.
+  const libre = await gh(auth.token, `/repos/${org}/${repoName}`);
+  if (libre.status !== 404) {
+    if (libre.ok && await confirma(`Ya existe ${org}/${repoName}. ¿Solo clonarlo en local (reanudar)?`)) {
+      await finalizarLocal(auth, org, repoName, baseDir, destino, nat, tipo, naturaleza);
+      say(`\n${C.g}✅ Reanudado.${C.x} Trabaja en develop/feature; main = aprobación.\n`); rl.close(); return;
+    }
+    fail(`Ya existe ${org}/${repoName} — elige otro nombre.`); rl.close(); return;
+  }
+  const gen = await gh(auth.token, `/repos/${org}/${nat.template}/generate`, {
+    method: 'POST',
+    body: JSON.stringify({ owner: org, name: repoName, private: true, description: `${t.etiqueta} · creado con fractalia-faro` }),
+  });
+  if (!gen.ok) { fail(`No se pudo crear el repo desde el template: ${JSON.stringify(gen.body && gen.body.message)}. ¿Está ${org}/${nat.template} marcado como "Template repository"?`); rl.close(); return; }
+  ok(`Repo creado: ${gen.body.html_url}`);
+
+  // 6b. Asignar a un equipo GitHub (control de VISIBILIDAD): quien no este en el equipo no lo ve.
+  const team = argVal('team') || cfg.team;
+  if (team) {
+    const asg = await gh(auth.token, `/orgs/${org}/teams/${team}/repos/${org}/${repoName}`, { method: 'PUT', body: JSON.stringify({ permission: 'push' }) });
+    if (asg.ok || asg.status === 204) { ok(`Repo asignado al equipo '${team}' (visibilidad restringida a sus miembros).`); cfg.team = team; saveConfig(cfg); }
+    else warn(`No pude asignar el repo al equipo '${team}' (¿existe? ¿tienes permiso?): continúo.`);
+  }
+
+  // 7. Esperar a que el contenido esté listo y crear develop (rama por defecto).
+  let defBranch = gen.body.default_branch || 'main';
+  let sha = null;
+  for (let i = 0; i < 20 && !sha; i++) {
+    await new Promise((r) => setTimeout(r, 1500));
+    const ref = await gh(auth.token, `/repos/${org}/${repoName}/git/ref/heads/${defBranch}`);
+    if (ref.ok) sha = ref.body.object.sha;
+  }
+  if (!sha) { warn('El repo tarda en estar listo; crea develop a mano más tarde (git switch -c develop && git push -u origin develop).'); }
+  else {
+    const dev = await gh(auth.token, `/repos/${org}/${repoName}/git/refs`, { method: 'POST', body: JSON.stringify({ ref: 'refs/heads/develop', sha }) });
+    if (dev.ok) {
+      const pat = await gh(auth.token, `/repos/${org}/${repoName}`, { method: 'PATCH', body: JSON.stringify({ default_branch: 'develop' }) });
+      ok(`Rama develop creada${pat.ok ? ' y fijada como rama por defecto' : ''} (main queda como rama de aprobación).`);
+    } else warn('No se pudo crear develop automáticamente; créala tras el clon.');
+  }
+
+  // 7b. Proteger main en SERVIDOR (2ª capa, sobre el gate local del harness). Requiere plan Team en
+  // repos privados: si el plan no lo permite, GitHub responde 403 y avisamos sin romper (Free = solo gate local).
+  const prot = await gh(auth.token, `/repos/${org}/${repoName}/branches/main/protection`, {
+    method: 'PUT',
+    body: JSON.stringify({ required_pull_request_reviews: { required_approving_review_count: 1 }, enforce_admins: false, required_status_checks: null, restrictions: null }),
+  });
+  if (prot.ok) ok('main protegida en servidor (solo se llega por PR/merge = aprobación).');
+  else warn('No pude proteger main en servidor (normal en plan GitHub Free para repos privados) — el harness la protege igual en local. Para el candado de servidor: GitHub Team.');
+
+  // 8-10. Clonar en local, metadatos, ClickUp y abrir VS Code.
+  await finalizarLocal(auth, org, repoName, baseDir, destino, nat, tipo, naturaleza);
+
+  say('');
+  caja([
+    `${C.g}${C.b}✅  Repositorio listo${C.x}`,
+    `${C.d}Al abrir Claude Code dentro, el harness arranca el onboarding${C.x}`,
+    `${C.d}(fasear el trabajo, funcional, riesgos).${C.x}`,
+    `Trabaja en ${C.b}develop/feature${C.x}${C.d}; el merge a ${C.x}main${C.d} = aprobación.${C.x}`,
+  ], { color: C.g });
+  say('');
+  rl.close();
+}
+
+main().catch((e) => { fail(e.message || String(e)); rl.close(); });

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "fractalia-faro",
+  "version": "0.1.0",
+  "description": "Wizard FARO: crea un repo de trabajo (servicio/funcionalidad de plataforma, proyecto o iniciativa) desde el template oficial, con nomenclatura, ramas main+develop y clon local listo.",
+  "bin": {
+    "faro": "bin/crear.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/"
+  ],
+  "license": "UNLICENSED",
+  "private": false
+}