fractalia-faro · Wizard inicial de repos Fractalia

CLI PRE-harness e independiente de él: el harness vive DENTRO de cada repo; este wizard es quien crea / abre / adopta el repo. Pensado para usuarios no técnicos: un solo comando, sin paths ni git a mano. Multiplataforma (Windows / macOS / Linux).

npx fractalia-faro

Requiere ser miembro de la organización CAS-IA en GitHub.

Cuatro puertas de entrada

Al arrancar, el wizard pregunta ¿Qué quieres hacer?:

1. Crear un repositorio nuevo — el asistente completo (abajo). Nace del template oficial.
2. Abrir uno que ya existe — te lista tus repos FARO (los de tus equipos), etiquetados por equipo; eliges y lo clona. Si no tienes ninguno todavía, te ofrece crear uno. La búsqueda también encuentra por nombres antiguos (si el repo se renombró). También por flag: --abrir=<repo>.
3. Adoptar una carpeta existente — reenfoca un proyecto que YA tienes hacia el harness sin tocar tu código/stack: detecta el stack, añade la capa FARO (colisiones → *.fractalia), crea el repo y lo sube. Flag: --adoptar.
4. Renombrar un proyecto — el nombre comercial cambió ("análisis red" → "solución 360"): renombra sin miedo. Flag: --renombrar (+ --repo=<nombre>). Detalle abajo.

Qué hace, paso a paso (crear)

1. Sesión GitHub: si no estás logueado, te guía con login por navegador (device flow: abre github.com/login/device con el código copiado al portapapeles). Se hace UNA vez por máquina; queda en ~/.fractalia-cli.json.

2. Valida la organización: comprueba por API que eres miembro activo de CAS-IA (y si eres owner). Sin membresía no hay acceso a los templates (privados).

3. Clasifica el trabajo en dos ejes (modelo v2), en lenguaje llano. La clasificación va a GitHub topics + al metadato .fractalia-template.json, NO al nombre:

   • Entity (ent-*) — qué ES: servicio · proyecto · iniciativa · proceso · plataforma · sistema · funcionalidad · libreria · generico · procedimiento · acuerdo.
   • Domain (dom-*) — de qué ÁREA del CDM: producto · comercial · operaciones · financiero · legal · marketing · rrhh · sistemas · master-data · servicios-generales.

   Evolucionar (iniciativa→proyecto→servicio) = cambiar el topic ent-*, SIN renombrar el repo.

4. Naturaleza → template (data-driven): documental/gestión → template-faro-doc · Cloudflare Worker → template-faro-worker · app de cualquier stack → template-faro-app. El catálogo se puede sobreescribir desde la org (fractalia-templates/catalog.json) sin republicar el CLI.

5. Nomenclatura AGNÓSTICA: el nombre es faro-<slug> (p. ej. faro-notificaciones), estable e independiente de la clasificación. Valida en vivo que el nombre no exista, y si existe te dice de qué equipo es. El slug es el concepto (la identidad estable que ancla el harness/Directus, aunque renombres).

6. Crea el repo privado en la org desde el template (API nativa generate), estampa los topics, crea la rama develop (por defecto) y protege main (best-effort: si el plan no lo permite, avisa y sigue; el harness la protege en local).

7. Equipo(s) — comparte el repo con tu(s) equipo(s) GitHub, con permiso Write por defecto (los devs trabajan). Si tienes 1 equipo, se autoasigna; si varios, eliges. El owner elige entre todos.

8. Clona en local en la carpeta que elijas, con el remoto sin fricción: prefiere SSH (tu clave/1Password) → gh → HTTPS limpio (el token nunca queda en .git/config).

9. ClickUp API key personal (opcional): pegar ahora / más tarde / no usar.

10. Deja git listo (identidad user.name/user.email) y abre el editor (VS Code o Cursor, lo detecta). Dentro, Claude Code arranca el onboarding del harness, consciente de la clasificación que lee del metadato.

Clasificación v2 (el modelo)

• ENTIDAD = la clase del trabajo (11, alineadas con el CDM). DOMINIO = una de las 10 áreas (único eje obligatorio compartido con el CDM). CONCEPTO = el slug del repo = la identidad estable.
• El repo está desvinculado del catálogo: solo aporta git_url. Renombrarlo/moverlo no rompe nada. La clasificación vive en .fractalia-template.json (lo que el harness LEE) + topics (espejo para el listado).
• Lo que no encaja en entity/domain va a Directus, no al repo.

Renombrar un proyecto (sin romper nada)

Los nombres cambian con la vida del proyecto; el modelo lo asume:

• Es seguro: GitHub redirige automáticamente el nombre viejo (HTTPS y SSH) — los clones y URLs de todos siguen funcionando. El wizard además actualiza el origin de tu clon local (preservando SSH/HTTPS).
• Permisos (regla de GitHub): renombrar exige admin sobre el repo. Lo tienen quien creó el repo y los owners de la org; el selector te marca en cada repo si puedes (admin ✓) o no (write). Sin admin, el wizard no se estrella: crea una solicitud como Issue (con motivo) para que un admin la ejecute — queda rastro auditable de por qué cambió el nombre.
• Trazabilidad: el nombre viejo queda como topic antes-<slug> y en alias[] de .fractalia-template.json. La búsqueda de «Abrir» encuentra el repo por cualquiera de sus nombres. El concept NO cambia (identidad estable para harness/Directus).
• Cloudflare: el nombre del repo y el del Worker están desacoplados — renombrar el repo no toca wrangler, URLs workers.dev, bindings ni dominios. Si usas Workers Builds (deploy por Git), la conexión sigue al repo por su ID interno; el wizard te recuerda verificarlo en el dashboard (10 segundos).

Equipos y aislamiento

• Los repos se comparten con equipos (teams de GitHub), no persona a persona. Al crear, se asigna el/los equipo(s) con permiso Write.
• Para que un miembro solo vea sus repos, la organización debe tener Base permission = No permission (Settings → Member privileges). Con eso, GitHub aísla por equipo y el listado "abrir" solo muestra lo tuyo.
• El owner ve todo por su rol (no por estar en cada equipo): puede quedarse solo en su equipo real.

Métricas

Cada sesión de Claude Code, el harness del repo envía una métrica (a un webhook n8n) con: identidad git, clasificación, tokens/coste, fase, docs, y el equipo que actúa = el equipo tuyo que está en el repo (si el repo tiene varios, el primario). Estampado por el wizard en .fractalia-template.json.

Directus (catálogo/biblioteca)

Se opera 100% por MCP (servidor MCP de Fractalia, OAuth propio de Orbital) a través del agente gestor-directus — sin token local. Consultar es libre; escribir (faro_upsert_*) depende de tu permiso en el MCP (si no lo tienes, el agente te dice que lo pidas al administrador de Orbital). El harness NO escribe en Directus.

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

Dónde "vive" el wizard: el código está en este repo; el paquete se publica en npm (registro público, sin secretos). npx lo descarga a una caché temporal y lo ejecuta — no instala nada y siempre corre la última versión.

Paso 0 · Prerrequisitos de la máquina (una sola vez). Tres herramientas: Node (trae npx), git y VS Code (o Cursor). Según tu sistema:

Windows (PowerShell; o ejecuta kit/instalar-fractalia.ps1, que lo hace solo):

winget install OpenJS.NodeJS.LTS            # Node (trae npx)
winget install Git.Git                      # git
winget install Microsoft.VisualStudioCode   # si no lo tiene ya

macOS (con Homebrew):

brew install node git
brew install --cask visual-studio-code       # si no lo tiene ya

Linux (Debian/Ubuntu):

sudo apt install -y nodejs npm git
# VS Code: https://code.visualstudio.com/docs/setup/linux

El wizard es multiplataforma: detecta el SO y usa lo correcto (abrir navegador, portapapeles, editor, SSH). En macOS/Linux funciona igual que en Windows. Para que abra el editor solo, ten code/cursor en el PATH (VS Code: Cmd/Ctrl+Shift+P → "Install 'code' command in PATH").

Paso 1 · Invitación a la organización. El administrador te invita a CAS-IA (y te añade a tu equipo). Aceptas el email con tu cuenta GitHub.

Paso 2 · Ejecutar. Abre una terminal (en 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 1ª vez por máquina): el wizard abre github.com/login/device, con el código ya copiado; inicias sesión, lo pegas y autorizas.

Paso 4 · Contesta al asistente. Qué es (entity), de qué área (domain), naturaleza (documental/worker/app), nombre en lenguaje normal, equipo, carpeta, y ClickUp si quieres.

Paso 5 · A trabajar. El repo queda creado (main + develop), clonado en tu carpeta ya en develop, y el editor abierto. Dentro, Claude Code arranca el onboarding del harness.

Las siguientes veces: solo el Paso 2.

Modo no interactivo (CI / power users)

npx fractalia-faro --nombre="Analisis de red" --entity=servicio \
    --domain=producto --naturaleza=worker --team=ia --dir=. --yes

Flags: --org --entity --domain --naturaleza --nombre --dir --abrir --adoptar --renombrar --repo --team --team-perm --yes --no-open --dry-run. --help para todo.

Configuración de administrador (una vez)

1. Subir template-faro-doc, template-faro-worker y template-faro-app a CAS-IA y marcarlos como Template repository (Settings → General).
2. OAuth App de la org para el device flow; su client_id va embebido en el CLI (o FRACTALIA_CLIENT_ID / ~/.fractalia-cli.json).
3. Org → Member privileges → Base permission = No permission (aísla por equipo) y crear los equipos (IA, data, producto, desarrollo…), añadiendo a cada usuario al suyo al invitarlo.
4. Publicar en npm (npm publish — sin build; ESM de un fichero).
5. Directus: se opera por MCP (OAuth de Orbital); no hay token local ni org secret que gestionar para esto.

Requisito de plan GitHub

En Free, los repos privados no tienen branch protection/rulesets en servidor (el harness protege main en local igualmente). Para protección en servidor hace falta GitHub Team. El wizard lo intenta best-effort: si no puede, avisa y sigue. FARO no usa releases, así que la release immutability no aplica.

Anti-deriva (sync del estándar)

La API generate crea una copia congelada. El wizard estampa .fractalia-template.json (de qué template salió) para poder añadir a los templates un workflow de sync que abra PRs en los repos derivados cuando el estándar evoluciona.

Roadmap

• Puerta 4 · Montar espacio: clonar de golpe los repos de un sistema + manifiesto para dar contexto multi-repo a Claude.
• Reclasificación asistida (editar .fractalia-template.json → re-estampar topics + Directus por MCP).
• Búsqueda del listado por Search API (miles de repos).
• Adaptador GitLab (misma capa de proveedor).

Licencia

MIT © Fractalia.