# 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.

## Cinco 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. **Revisar esta carpeta (check)** — el *doctor* de un repo FARO: diagnostica estructura, dependencias y ramas, y **aplica los arreglos sanos** (crear `develop`, normalizar `master`→`main`, fijar la rama por defecto, subir ramas que falten en el servidor, declarar el plugin en `settings.json`, retirar la copia legada del harness). Flag: `--check`; con `--dry-run` solo informa.
5. **Renombrar un proyecto** — el nombre comercial cambió ("análisis red" → "solución 360"): renombra sin miedo. Flag: `--renombrar` (+ `--repo=<nombre>`). Detalle abajo.

## El motor vive en el PLUGIN, no en el repo

FARO se gobierna con el **plugin `faro` de Claude Code** (marketplace `CAS-IA/faro-plugin`): skills `/faro:*`, agentes y el harness de hooks. El repo ya **no** lleva copia local del motor en `.claude/hooks/` — con esa copia presente el plugin se inhibe, así que `crear`/`adoptar`/`check` la retiran y declaran en su lugar la distribución en `.claude/settings.json` (marketplace + `autoUpdate`), que **viaja con el clon**: quien clone el repo recibe la oferta de instalar el plugin y se mantiene solo al día.

Para que esa instalación no falle, el wizard deja **git preparado en la máquina**: el repo del plugin es privado, y Claude Code clona los marketplaces **siempre por HTTPS** desde su propio directorio, donde ni tu clave SSH ni el token en memoria del CLI existen. Por eso el credential helper HTTPS (acotado a la org) se cablea **aunque uses SSH** — son canales paralelos, no alternativas.

## 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 `~/.faro.json` (usuarios legados con `~/.fractalia-cli.json` se migran automáticamente, sin perder la sesión).

   - **Valida los permisos del token, no solo que exista.** Un token sin `repo` responde 200 en la API y aun así no puede clonar un repo privado: el fallo aparecería mucho después, dentro de Claude Code, sin pista de la causa. El CLI lee los permisos reales (`X-OAuth-Scopes`) y, si le faltan los críticos (`repo`, `read:org`), descarta esa sesión y vuelve a pedir login. `workflow` y `user:email` avisan pero no bloquean.
   - **Deja git listo** para clonar/hacer push sin pedir credenciales: SSH si ya autentica de verdad, y **además** un credential helper HTTPS con el token de sesión **acotado a la org** (nunca global a `github.com`, así no se filtra a otras cuentas tuyas en la misma máquina). Los dos canales conviven: SSH mueve tu código, HTTPS baja el plugin.
   - **Recupera tu identidad real**: si tu correo de GitHub es privado, la API devuelve `null` y el commit se firma con el alias `noreply` (atribuye bien, pero no recibe correo). El CLI consulta además `/user/emails` y guarda los dos por separado en `~/.faro.json`: `email` (firma de commits) y `email_contacto` (el verificado, para notificar y emparejar cuentas).
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 por **DEPARTAMENTO (dominio)**, en lenguaje llano. La clasificación va a **GitHub topics** + al metadato `.faro.json`, **NO al nombre**:
   - **Domain** (`dom-*`) — de qué ÁREA del CDM: `producto · comercial · operaciones · financiero · legal · marketing · rrhh · sistemas · master-data · servicios-generales`. **`innovacion`** solo la ve el owner/admin.
   - **Naturaleza** (`nat-*`) — el tipo técnico: `nat-worker · nat-app · nat-documental`.

   La ENTIDAD (clase del trabajo) ya **no** la clasifica el CLI: un documento puede corresponder a varias entidades, así que la resuelve el harness dentro del template.
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. **Nombre NATURAL, sin prefijo** (p. ej. `analisis-de-red`). El marcador FARO es el topic `faro`, no el nombre. **Validación inteligente en vivo**: avisa si el nombre es poco específico (<5 letras/genérico), si ya existe (te dice de qué equipo es y ofrece **abrir** o **elegir otro** con **sugerencias libres**), o si hay **parecidos** ya creados.
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 (el modelo)

- **DOMINIO** = el departamento/área que lo crea (uno de los 10 del CDM + `innovacion` solo-owner). Es el **único eje** que gestiona el CLI y va en `.faro.json` + topic `dom-*`.
- La ENTIDAD (clase del trabajo) la clasifica el **harness** dentro del template, no el CLI (un documento puede corresponder a varias entidades).
- El repo está **desvinculado** del catálogo: solo aporta `git_url`. Renombrarlo/moverlo no rompe nada. La clasificación vive en `.faro.json` (lo que el harness LEE) + topics (espejo para el listado): `faro · dom-<departamento> · nat-<tipo>`.
- El nombre es **natural** (sin prefijo); el marcador FARO es el topic `faro`.

## 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 `.faro.json`. La búsqueda de «Abrir» encuentra el repo por cualquiera de sus nombres.
- **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 `.faro.json`.

## Catálogo/biblioteca (MCP)

Se opera **100% por MCP** (servidor MCP de Fractalia, OAuth propio de Orbital) — **sin token local**. Consultar es libre; escribir (`faro_upsert_*`) depende de tu permiso en el MCP. El CLI no escribe ahí: solo registra el repo en el MCP de usuario para que Claude Code lo tenga disponible.

## 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):
```powershell
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](https://brew.sh)):
```bash
brew install node git
brew install --cask visual-studio-code       # si no lo tiene ya
```

**Linux** (Debian/Ubuntu):
```bash
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.** De qué área/departamento (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" \
    --domain=producto --naturaleza=worker --team=ia --dir=. --yes
```
Flags: `--org --domain --naturaleza --nombre --dir --abrir --adoptar --check --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` / `~/.faro.json`). Scope solicitado: `repo read:org user:email workflow` (el scope `workflow` es obligatorio para poder tocar `.github/workflows/*.yml` en repos que lo necesiten — sin él, GitHub rechaza el push completo).
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 `.faro.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

- **Montar espacio**: clonar de golpe los repos de un sistema + manifiesto para dar contexto multi-repo a Claude.
- Reclasificación asistida (editar `.faro.json` → re-estampar topics + catálogo por MCP).
- Búsqueda del listado por **Search API** (miles de repos).
- Adaptador GitLab (misma capa de proveedor).

## Licencia

[MIT](./LICENSE) © Fractalia.