inovabiz-harness 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# INOVABIZ Dev Kit Harness
+
+TUI y CLI corporativa para explorar el AI Assets Registry y materializar su conocimiento en la carpeta `.agents/` de cada proyecto.
+
+El Dev Kit sólo lee el Registry y nunca modifica el repositorio central. Si un perfil requiere una fuente externa, la CLI la identifica y ejecuta su comando de instalación antes de aplicar el perfil, sin exponer la salida interna del proceso.
+
+## Requisitos
+
+- Node.js 20 o superior.
+- Git.
+- Git Credential Manager (GCM).
+
+## Instalación y desarrollo
+
+```bash
+npm install
+npm run check
+npm link
+```
+
+La prueba funcional aislada se ejecuta con `npm run test:functional`; compila el binario, prepara `output`, ejecuta `--setup=angular21` y vuelve a dejar el directorio vacío.
+
+## Configuración corporativa
+
+Configura una vez la URL HTTPS del Registry corporativo, sin credenciales embebidas. El Dev Kit la guarda globalmente para el usuario:
+
+```bash
+inovabiz-dev-kit-harness --remote "https://example.invalid/organization/project/_git/registry"
+```
+
+La misma configuración se puede administrar con `inovabiz-dev-kit-harness config remote set|get|unset`. Para CI u overrides temporales, `INOVABIZ_DEV_KIT_REGISTRY_URL` tiene precedencia sobre la URL persistida. La rama `main` permanece fijada en el paquete. El Dev Kit no requiere App Registration ni PAT: GCM abre el inicio de sesión corporativo cuando una operación Git lo necesita y conserva la sesión en el almacén seguro del sistema operativo.
+
+## TUI
+
+```bash
+inovabiz-dev-kit-harness
+```
+
+En una terminal interactiva abre una aplicación de consola con tema teal oscuro, estado resumido del Registry y un menú principal. Las rutas extensas se reservan para **Estado y ayuda** y cada acción de escritura pasa antes por una revisión clara.
+
+| Sección | Propósito | Atajos principales |
+| --- | --- | --- |
+| Inicio | Resumen del proyecto y accesos principales. | `1`–`5`, `↑`/`↓`, `Enter`, `q` |
+| Perfiles | Buscar, consultar compatibilidad y revisar un setup antes de aplicarlo. | `/`, `↑`/`↓`, `Enter`, `Esc` |
+| Configuración avanzada | Elegir tecnología y luego seleccionar overlays por categoría. | `Tab`, `↑`/`↓`, `c`, `Espacio`, `s`, `Esc` |
+| Sincronizar proyecto | Revisar perfil, revisión y extras instalados antes de sincronizar. | `Enter`, `Esc` |
+| Estado y ayuda | Ver autenticación, caché, destino completo y atajos. | `Esc` |
+
+`Esc` siempre vuelve al menú principal. En la pantalla de revisión, `y` aplica, `f` aplica ignorando conflictos de archivos administrados y `n` cancela.
+
+## CLI no interactiva
+
+```bash
+inovabiz-dev-kit-harness login          # opcional: valida acceso e inicia GCM si hace falta
+inovabiz-dev-kit-harness auth status
+inovabiz-dev-kit-harness profiles
+inovabiz-dev-kit-harness list skills --profile angular21
+inovabiz-dev-kit-harness setup angular21
+inovabiz-dev-kit-harness --setup=angular21
+inovabiz-dev-kit-harness sync
+inovabiz-dev-kit-harness add skills nestjs-feature-architecture --technology nestjs --version 10
+inovabiz-dev-kit-harness remove skills nestjs-feature-architecture --technology nestjs --version 10
+inovabiz-dev-kit-harness skill nestjs-feature-architecture --profile angular21 --technology nestjs --version 10
+```
+
+Todos los comandos que consultan el Registry intentan autenticar automáticamente mediante GCM. `auth status` no inicia una sesión: informa si existe acceso reutilizable, si se requiere autenticación o si Azure DevOps no está disponible. El cierre o cambio de cuenta se administra directamente en GCM.
+
+Un `setup` o `sync` que requiere skills externas las instala sin solicitar entradas adicionales. El Dev Kit acepta únicamente comandos `npx skills add <fuente>` y fuerza siempre `--path .agents/skills -y`, aunque esos flags no estén declarados en el Registry o indiquen otro destino.
+
+Durante `setup`, la salida interna de `npx` se mantiene oculta. Al finalizar, el comando muestra únicamente `INOVABIZ Dev Kit configurado correctamente.`; `--json` conserva el resultado técnico completo para automatizaciones.
+
+Integración recomendada en `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "inovabiz-dev-kit-harness sync && ng serve"
+  }
+}
+```
+
+El setup inicial también puede integrarse como `inovabiz-dev-kit-harness --setup=angular21 && ng serve`.
+
+### Fuente local
+
+Para desarrollar o validar contra un checkout local:
+
+```bash
+inovabiz-dev-kit-harness profiles --registry-path "../AI Assets Registry"
+inovabiz-dev-kit-harness setup angular21 --registry-path "../AI Assets Registry"
+```
+
+### Caché y modo offline
+
+Cada operación remota consulta `main` mediante Git/GCM, la resuelve a un commit y trabaja contra una snapshot inmutable. Si Azure DevOps sufre un error transitorio, se usa la última snapshot válida y se informa su antigüedad. Los errores de identidad o permisos nunca se ocultan con caché.
+
+`--offline` prohíbe la consulta remota y exige una snapshot local válida.
+
+## Estado administrado
+
+`.agents/.inovabiz-dev-kit-harness.json` registra el perfil, commit del Registry, assets base, overlays y hashes. Los archivos ajenos no se eliminan. Si un archivo administrado fue modificado localmente, la operación termina con conflicto; `--force` reemplaza exclusivamente archivos administrados.
+
+Las fuentes externas declaradas mediante `SOURCE.json` se registran en `.agents/external-skills.json`. Cuando definen un comando, la CLI lo ejecuta una sola vez por fuente durante `setup` y `sync`, sin entrada interactiva y con salida oculta. Si el proceso falla, se informa el código de salida y un detalle limitado y sanitizado.
+
+## Publicación en npm
+
+El scope público `@inovabiz` debe existir en npm y la cuenta o identidad de CI que publique debe tener permisos sobre él. Antes de publicar, revisa el contenido con `npm pack --dry-run --json`; el paquete está configurado para publicar únicamente `dist`, `README.md` y `package.json`.
+
+## Códigos de salida
+
+- `0`: éxito.
+- `1`: uso inválido.
+- `2`: Registry o instalación inválida.
+- `3`: conflicto local.
+- `4`: autenticación o autorización.
+- `5`: Registry no disponible y sin caché válida.