agent-cloud-kit 0.0.0-stage → 1.0.0-rc.0

package/skills/cloud-ready/reference/compat.md

@@ -0,0 +1,110 @@
+# Hacer compatible con la nube lo que el repo ya tiene
+
+De menos a más invasivo. Prueba cada nivel antes de pasar al siguiente, y propón al usuario el
+cambio exacto: en `configure` se aplica solo lo aprobado; en `verify` solo se tocan los archivos
+de la preparación y el resto queda propuesto en el PR.
+
+## 1. Adaptar la preparación
+
+Todo va en `.claude/cloud.json`; no toca código ni tests.
+
+| Lo que usa el repo | Qué hacer |
+| --- | --- |
+| Dependencias de npm, pnpm, Yarn o Bun | En `setup`, con el lockfile congelado: `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, `bun install --frozen-lockfile`. Node y el gestor fijados los instala el paquete. |
+| Servicios de Docker compose (base de datos, cola) | `docker.pull: "auto"` baja las imágenes en el setup. Levántalos en el comando que corre los tests (`agent-cloud-kit docker && docker compose up -d --wait db`) o, si son rápidos, en `session` (2 min como máximo) con ese mismo comando. `agent-cloud-kit session` arranca `dockerd` en segundo plano sin esperar a que responda; `agent-cloud-kit docker` lo arranca si hace falta y espera hasta 60 s a que `docker info` responda (sale con error si no). Para comprobarlo a mano: `docker info`. |
+| Testcontainers | Necesita Docker respondiendo: corre `agent-cloud-kit docker` antes de los tests (`agent-cloud-kit session` lo arranca pero no espera) y que la imagen esté en el setup: lístala en `docker.pull` si no está en un compose. Si construye imágenes, el CA del proxy entra con `CLOUD_PROXY_CA` como secreto. |
+| Playwright | Los navegadores de la versión del repo en `setup` (`npx playwright install --with-deps chromium`); suma tiempo al setup (límite ~5 min) y puede pedir `domains` (`cdn.playwright.dev`, `playwright.download.prss.microsoft.com`). La imagen ya trae navegadores en `/opt/pw-browsers`: si la versión coincide, alcanza con eso. Corre contra el servidor local de la sesión. |
+| `localhost` en URLs de tests o servicios | No hay IPv6: si algo resuelve `localhost` a `::1` y falla, usa `127.0.0.1` (en la config del test, por variable de entorno si el repo lo permite). |
+| Variables secretas (API keys de prueba) | Nombres en `requiredEnv`; el usuario pone los valores en el entorno de claude.ai. Recuerda que las lee cualquiera que use el entorno. |
+| Hosts externos que el setup o los tests necesitan | En `domains`; el manual los lista para la red del entorno. |
+| Corridas largas (más de 2 min) | En segundo plano con la salida a un log, o `BASH_DEFAULT_TIMEOUT_MS` y `BASH_MAX_TIMEOUT_MS` en las variables del entorno. Anota en `notes` cuánto tardan. |
+
+## 2. Bifurcar una variante para la nube
+
+Solo si adaptar la preparación no basta, y con aprobación del usuario.
+
+- **Script aparte:** p. ej. `cloud:services` en `package.json`, que prende Docker
+  (`agent-cloud-kit docker`) y levanta lo que los tests necesitan. El script de tests del repo
+  no cambia.
+- **Rama por `CLAUDE_CODE_REMOTE`:** dentro de un script existente,
+  `if [ "$CLAUDE_CODE_REMOTE" = true ]; then …; fi`, para lo que en la nube se hace distinto
+  (p. ej. no abrir un navegador, usar `127.0.0.1`). Que en local se comporte igual que antes.
+
+## 3. Lo que no corre en la nube
+
+Déjalo fuera y anótalo en `notes` con el porqué:
+
+- APIs externas que el entorno no permite o que no deben recibir tráfico de pruebas.
+- Secretos que el entorno no tiene (o que no deben estar en un entorno compartido).
+- Lo que necesita abrir puertos hacia fuera o una vista previa (no existen).
+- Recursos de dominios externos cargados por Playwright (bug abierto, ver `knowledge.md`).
+
+## Ejemplo: vitest, Postgres en compose y Playwright
+
+El repo usa npm, `vitest` para unitarios (`npm test`), `vitest` con Postgres de
+`compose.yml` para integración (`npm run test:db`, espera `DATABASE_URL`) y Playwright para e2e
+(`npm run test:e2e`, levanta el servidor con `webServer`). Una prueba e2e de pagos llama a la
+sandbox de un proveedor externo.
+
+Propuesta: unitarios tal cual; integración adaptando la preparación (la imagen se baja en el
+setup y la base se levanta antes de los tests); e2e con los navegadores en el setup; la prueba
+de pagos fuera (necesita una API externa y su secreto).
+
+`.claude/cloud.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/agent-cloud-kit@1.0.0/schema.json",
+  "version": "1.0.0",
+  "aptRepos": [],
+  "apt": [],
+  "docker": { "pull": "auto" },
+  "setup": ["npm ci", "npx playwright install --with-deps chromium"],
+  "session": [],
+  "requiredEnv": [],
+  "domains": ["cdn.playwright.dev", "playwright.download.prss.microsoft.com"],
+  "notes": ".claude/cloud-notes.md"
+}
+```
+
+`.claude/cloud-notes.md`:
+
+```markdown
+En la nube corren:
+- `npm test` (unitarios, ~1 min).
+- `npm run test:db`, antes `docker compose up -d --wait db` y
+  `DATABASE_URL=postgres://app:app@127.0.0.1:5432/app` (~3 min, en segundo plano).
+- `npm run test:e2e -- --grep-invert @payments` (Playwright contra el servidor local, ~6 min,
+  en segundo plano).
+
+No corre `@payments`: llama a la sandbox del proveedor de pagos, que el entorno no permite y
+cuyo secreto no está en el entorno.
+```
+
+## Ejemplo: repo sin tests
+
+Solo se prepara la máquina; nada de tests.
+
+`.claude/cloud.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/agent-cloud-kit@1.0.0/schema.json",
+  "version": "1.0.0",
+  "aptRepos": [],
+  "apt": [],
+  "docker": { "pull": false },
+  "setup": ["pnpm install --frozen-lockfile"],
+  "session": [],
+  "requiredEnv": [],
+  "domains": [],
+  "notes": ".claude/cloud-notes.md"
+}
+```
+
+`.claude/cloud-notes.md`:
+
+```markdown
+El repo no tiene tests: en la nube solo se prepara la máquina (pnpm y dependencias). `verify`
+comprueba `agent-cloud-kit doctor`, `node_modules` y las versiones fijadas.
+```

package/skills/cloud-ready/reference/knowledge.md

@@ -0,0 +1,56 @@
+# Lo que se sabe de la nube de Claude Code
+
+Cada hecho lleva su estado: `verificado` (alguien lo vio, con la fuente) o `por verificar`. Si
+en una sesión ves algo que no está aquí o que lo contradice, va a "Hallazgos" de
+`docs/agent-cloud.md`, marcado "proponer al paquete" (ver `SKILL.md`). "README" es el README del
+paquete `agent-cloud-kit`; "prueba en la nube, 2026-11-02" son sesiones de prueba del paquete en
+claude.ai/code.
+
+## Máquina y setup
+
+| Hecho | Estado | Fuente |
+| --- | --- | --- |
+| El setup script del entorno corre como root desde `/home/user` (no desde el repo), antes de que empiece Claude; si falla, no avisa. El repo queda en `/home/user/<repo>`. | verificado | README ("What it solves"); Prueba en la nube, 2026-11-02 |
+| Un setup de más de ~5 min no deja máquina guardada: cada sesión arranca de cero. Cada paso de `setup` del paquete tiene 180 s. | verificado | README ("What it solves") |
+| La máquina guardada se rehace cada ~7 días o al editar el setup script o la red. Cambiar `.claude/cloud.json` no la rehace; para forzarla, edita el setup script (p. ej. un comentario con la fecha). | verificado | README ("Machine fingerprint") |
+| Una sesión reanudada no vuelve a correr el setup; los cambios del entorno se prueban con una sesión nueva. | verificado | README ("What it does not do") |
+| Las variables del panel del entorno llegan a la sesión, pero no al setup script. | por verificar | Sin comprobar en la prueba en la nube, 2026-11-02 (hace falta editar un entorno en claude.ai) |
+| El `node_modules` que instala el setup sigue ahí en la sesión. | por verificar | Sin comprobar en la prueba en la nube, 2026-11-02 (hace falta editar un entorno en claude.ai); un repo en uso lo midió en 2026-10 |
+| Las variables del entorno las puede leer cualquiera que use ese entorno. | verificado | README ("What it does not do") |
+| La imagen trae Node 22 por defecto (`/opt/node22`), también `/opt/node24`, y navegadores de Playwright en `/opt/pw-browsers`. | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| `dockerd` viene apagado y el clon es parcial (sin historial completo ni `origin/<rama por defecto>`); `agent-cloud-kit session` prende Docker y completa el clon. Docker funciona dentro de la sesión. | verificado | README ("What it solves") |
+| Dos `apt` a la vez chocan en el lock de dpkg. | verificado | README ("What it solves") |
+| `CLAUDE_CODE_SYNC_SKILLS=1` y `CLAUDE_CODE_SYNC_PLUGINS=1` están definidas; qué sincronizan no se sabe. | por verificar | Variables vistas en la prueba en la nube, 2026-11-02 |
+
+## Red
+
+| Hecho | Estado | Fuente |
+| --- | --- | --- |
+| La red *Custom* sin la casilla "Also include default list of common package managers" bloquea npm (DNS o `CONNECT 403`). | verificado | README ("Set up claude.ai"); un repo en uso, 2026-10 |
+| El proxy bloquea los releases de GitHub y la API GraphQL; la API REST (`api.github.com`) pasa. | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| El proxy reemplaza el TLS: `HTTPS_PROXY`, `NO_PROXY`, `SSL_CERT_FILE` y `NODE_EXTRA_CA_CERTS` vienen definidas. `docker build` no confía en su CA: pásala como secreto con `CLOUD_PROXY_CA` (lo exporta `agent-cloud-kit session`). | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02; README ("The proxy CA") |
+| No hay IPv6. | verificado | README ("What it solves") |
+| En tests, `127.0.0.1` es más seguro que `localhost` (que puede resolver a `::1`). | por verificar | Consecuencia de no tener IPv6 |
+| No hay puertos abiertos ni vista previa: la app no se ve en un navegador externo. Playwright sí corre dentro de la sesión, contra `localhost`. | verificado | README ("What it does not do"); un repo en uso, 2026-10 |
+| Playwright no carga recursos de dominios externos en la página. | verificado | Bug abierto `anthropics/claude-code#11791` |
+
+## GitHub
+
+| Hecho | Estado | Fuente |
+| --- | --- | --- |
+| `gh` 2.89 está instalado. `gh auth status` dice que `GH_TOKEN` es inválido (`GH_TOKEN=proxy-…`), pero `gh api` REST funciona: el proxy pone la credencial. | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| `gh pr …` y `gh issue …` fallan con 403 porque usan GraphQL: usa `gh api` (REST). | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| `gh pr ready` no funciona (GraphQL). Para draft/ready y auto-merge habría rutas REST: `POST /repos/{o}/{r}/pulls/{n}/ccr/ready_for_review`, `…/ccr/convert_to_draft`, `PUT\|DELETE …/ccr/auto_merge`, `GET …/ccr/review_threads`. | por verificar | Mensaje del 403 de GraphQL en la nube (2026-11), ruta no probada |
+| La sesión trabaja en su propia rama `claude/<slug>`, parte del commit de la rama local desde la que se lanzó (`CLAUDE_CODE_BASE_REF`) y puede empujar a otra rama: `git push origin HEAD:<rama>`. | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| Sin el Claude GitHub App instalado en el repo, `claude --cloud` sube una copia local y la sesión no puede empujar. | verificado | Guía de un repo que ya usa la nube (2026-10) |
+
+## Claude Code
+
+| Hecho | Estado | Fuente |
+| --- | --- | --- |
+| Claude Code no descubre `.agents/skills/`, ni en local ni en la nube. Hace falta el symlink `.claude/skills/<nombre> -> ../../.agents/skills/<nombre>` (lo crea `agent-cloud-kit init`). | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| Los plugins de la máquina local no llegan a la nube, ni sus hooks: las skills deben estar copiadas en el repo. | verificado | README ("What it does not do") |
+| `claude --cloud` usa el entorno elegido con `/remote-env` (queda en la configuración del usuario). | verificado | Guía de un repo que ya usa la nube (2026-10) |
+| `--environment` de `claude --cloud` solo acepta entornos self-hosted (`ccpool_…`). | verificado (prueba en la nube, 2026-11-02) | `claude --help` |
+| `claude --cloud <prompt>` exige una terminal interactiva; toma el texto como primer mensaje, imprime la URL de la sesión y el comando `claude --teleport`, y vuelve. | verificado (prueba en la nube, 2026-11-02) | Prueba en la nube, 2026-11-02 |
+| Un comando de la herramienta Bash se corta a los 2 min por defecto (10 como máximo). Para corridas largas: en segundo plano, o subir `BASH_DEFAULT_TIMEOUT_MS` y `BASH_MAX_TIMEOUT_MS` en las variables del entorno (p. ej. `3600000`). | verificado | Documentación de Claude Code (configuración); un repo en uso, 2026-10 (suite de ~35 min) |