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

package/dist/state.js

@@ -0,0 +1,147 @@
+/**
+ * @file Machine fingerprint and the per-repo state file that records what setup last did.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { TOOLS } from "./detect.js";
+/** Directory, inside the tools dir, that holds one state file per repo. */
+const STATE_DIR = "state";
+/** Prefix of every fingerprint. */
+const FINGERPRINT_PREFIX = "sha256-";
+/** Hash algorithm used for fingerprints. */
+const HASH_ALGORITHM = "sha256";
+/** Indentation of the state file. */
+const JSON_INDENT = 2;
+/**
+ * Serializes a value as JSON with object keys sorted recursively; arrays keep their order.
+ *
+ * @param value - Any JSON-compatible value.
+ * @returns A canonical JSON string.
+ */
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * Hashes everything that decides how the machine is built, so a change asks for a rebuild.
+ * `session`, `requiredEnv` and `notes` are left out: changing them does not need a rebuild.
+ *
+ * @param config - Repo config.
+ * @param versions - Pinned tool versions.
+ * @param images - Docker images to pull.
+ * @param packageVersion - Version of this package.
+ * @returns `sha256-<hex>`.
+ * @example
+ * fingerprint(config, { node: "20.1.0" }, ["postgres:16"], "1.0.0"); // "sha256-ab12..."
+ */
+export function fingerprint(config, versions, images, packageVersion) {
+    const { version, aptRepos, apt, docker, setup } = config;
+    const json = stableJson({ version, aptRepos, apt, docker, setup, versions, images, packageVersion });
+    return FINGERPRINT_PREFIX + createHash(HASH_ALGORITHM).update(json).digest("hex");
+}
+/**
+ * Locates the state file of a repo.
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @returns `<toolsDir>/state/<basename(repo)>.json`.
+ * @example
+ * statePath("/opt/agent-cloud-kit", "/home/user/app"); // "/opt/agent-cloud-kit/state/app.json"
+ */
+export function statePath(toolsDir, repo) {
+    return join(toolsDir, STATE_DIR, `${basename(repo)}.json`);
+}
+/**
+ * Writes the state file atomically (temp file in the same dir, then rename).
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @param state - State to record.
+ * @example
+ * writeState("/opt/agent-cloud-kit", "/home/user/app", state);
+ */
+export function writeState(toolsDir, repo, state) {
+    const file = statePath(toolsDir, repo);
+    mkdirSync(join(toolsDir, STATE_DIR), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(state, null, JSON_INDENT)}\n`);
+    renameSync(temp, file);
+}
+/**
+ * Tells whether a value is a plain JSON object.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True for non-null, non-array objects.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Tells whether a parsed value has the shape of a `StepResult`.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True for a string `name`, a boolean `ok`, a finite numeric `ms` and an optional string `error`.
+ */
+function isStepResult(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.name === "string" &&
+        typeof value.ok === "boolean" &&
+        typeof value.ms === "number" &&
+        Number.isFinite(value.ms) &&
+        (value.error === undefined || typeof value.error === "string"));
+}
+/**
+ * Tells whether a parsed value is a map of known tools to version strings.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True when every key is a tool and every value a string.
+ */
+function isVersionMap(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.entries(value).every(([k, v]) => TOOLS.includes(k) && typeof v === "string");
+}
+/**
+ * Tells whether a parsed value has the shape of a `MachineState`; a missing `resolved` is accepted.
+ *
+ * @param value - Any parsed JSON value.
+ * @returns True when all required fields are present with the right types.
+ */
+function isMachineState(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.fingerprint === "string" &&
+        typeof value.packageVersion === "string" &&
+        typeof value.finishedAt === "string" &&
+        Array.isArray(value.steps) &&
+        value.steps.every(isStepResult) &&
+        (value.resolved === undefined || isVersionMap(value.resolved)));
+}
+/**
+ * Reads a repo's state file; never throws because it runs at session start.
+ *
+ * @param toolsDir - Tools directory.
+ * @param repo - Repo root path.
+ * @returns The state, or undefined when the file is missing, unreadable, invalid or incomplete.
+ * @example
+ * readState("/opt/agent-cloud-kit", "/home/user/app"); // undefined before the first setup
+ */
+export function readState(toolsDir, repo) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(toolsDir, repo), "utf8"));
+        return isMachineState(parsed) ? { ...parsed, resolved: parsed.resolved ?? {} } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/steps.js

@@ -0,0 +1,46 @@
+/**
+ * @file Step results: runs one unit of work and reports its outcome without ever throwing.
+ */
+/**
+ * Runs a step, timing it and converting any failure into a result.
+ *
+ * @param name - Name reported in the result.
+ * @param fn - Work to run.
+ * @returns The outcome; this promise never rejects.
+ * @example
+ * await step("pull images", async () => pull()); // { name: "pull images", ok: true, ms: 1200 }
+ */
+export async function step(name, fn) {
+    const start = Date.now();
+    try {
+        await fn();
+        return { name, ok: true, ms: Date.now() - start };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { name, ok: false, ms: Date.now() - start, error };
+    }
+}
+/** Prefix of the name given to a lane whose function rejected. */
+const LANE_NAME_PREFIX = "lane ";
+/**
+ * Runs lanes of steps concurrently and joins their results in lane order.
+ *
+ * @param laneFns - Lane functions, each resolving to the results of its own steps.
+ * @returns Results ordered by lane, then by position within the lane; never rejects.
+ * @example
+ * await lanes(async () => [await step("a", fa)], async () => [await step("b", fb)]);
+ */
+export async function lanes(...laneFns) {
+    const groups = await Promise.all(laneFns.map(async (laneFn, index) => {
+        const start = Date.now();
+        try {
+            return await laneFn();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return [{ name: `${LANE_NAME_PREFIX}${index}`, ok: false, ms: Date.now() - start, error }];
+        }
+    }));
+    return groups.flat();
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "agent-cloud-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.1",
+  "description": "Zero-dependency CLI that prepares Claude Code cloud sessions.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramon-sg/agent-cloud-kit.git"
+  },
+  "homepage": "https://github.com/ramon-sg/agent-cloud-kit#readme",
+  "bugs": {
+    "url": "https://github.com/ramon-sg/agent-cloud-kit/issues"
+  },
+  "keywords": [
+    "cloud",
+    "sandbox",
+    "setup",
+    "session-start",
+    "cli"
+  ],
+  "bin": {
+    "agent-cloud-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --test 'test/**/*.test.ts'"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "typescript": "7.0.2"
+  }
+}

package/schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "agent-cloud-kit config",
+  "description": "Contents of .claude/cloud.json for agent-cloud-kit.",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string", "description": "Path or URL of this schema." },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$",
+      "description": "Exact agent-cloud-kit version to run (no ranges)."
+    },
+    "aptRepos": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "HTTPS URLs of setup scripts that add APT repositories (piped to bash)."
+    },
+    "apt": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "APT packages to install."
+    },
+    "docker": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": { "pull": "auto" },
+      "properties": {
+        "pull": {
+          "description": "\"auto\" detects images, false disables pulling, or list images explicitly.",
+          "oneOf": [
+            { "const": "auto" },
+            { "const": false },
+            { "type": "array", "items": { "type": "string" } }
+          ],
+          "default": "auto"
+        }
+      }
+    },
+    "setup": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Shell commands run once when the environment is set up."
+    },
+    "session": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Shell commands run at the start of every session."
+    },
+    "requiredEnv": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Environment variables that must be set; a warning is shown when missing."
+    },
+    "domains": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)+$" },
+      "default": [],
+      "description": "Extra hosts the cloud environment must allow; doctor probes them and the manual lists them."
+    },
+    "notes": {
+      "type": "string",
+      "description": "What does and does not run in the cloud: free text, or a path, relative to the repo, of a text file inside it whose contents are used instead. The session prints it at start and the manual shows it."
+    }
+  }
+}

package/skills/cloud-ready/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: cloud-ready
+description: Prepara o verifica un repo Node/TypeScript para las sesiones en la nube de Claude Code (claude.ai/code). Usa `configure` en local, con el usuario, para escribir `.claude/cloud.json` y decidir qué corre en la nube; usa `verify` dentro de una sesión en la nube para comprobar la preparación, arreglarla y reportar en el PR.
+argument-hint: "configure | verify"
+metadata:
+  version: "1.0.0"
+---
+
+# cloud-ready
+
+Deja el repo listo para la nube de Claude Code y lo comprueba en la nube real. No impone una
+forma de testear: se respeta lo que el repo ya hace. Un repo sin tests solo necesita la máquina
+preparada.
+
+- **Modo:** el primer argumento. `configure` corre en local con el usuario; `verify`, en la nube.
+  Sin argumento: `verify` si `CLAUDE_CODE_REMOTE=true`, si no `configure`.
+- **Antes de empezar:** lee `reference/knowledge.md` (lo que se sabe de la nube) y, si el repo
+  tiene tests, `reference/compat.md` (cómo hacerlos compatibles).
+- **El archivo de `notes`:** el que diga `notes` en `.claude/cloud.json`; si no hay, usa
+  `.claude/cloud-notes.md` y pon `"notes": ".claude/cloud-notes.md"` en la config. Se muestra al
+  empezar cada sesión en la nube y se copia en `docs/agent-cloud.md`: que sea corto.
+- **La CLI:** `agent-cloud-kit <comando>`. Si no está en el `PATH`, usa `npx -y agent-cloud-kit <comando>`.
+
+## Archivos de la preparación
+
+Son los únicos que `verify` puede cambiar:
+
+- `.claude/cloud.json`
+- el archivo de `notes`
+- `docs/agent-cloud.md` (lo regenera `agent-cloud-kit manual`; a mano solo la sección "Hallazgos")
+- `.agents/skills/test-audit/project.md` (solo su sección "Nube", y solo si el archivo existe)
+
+## `configure` (local, con el usuario)
+
+Si `CLAUDE_CODE_REMOTE=true`, detente: este modo necesita al usuario en una terminal local.
+No le pidas al usuario una lista de variables secretas ni de dominios: anota en `requiredEnv` y
+`domains` solo lo que veas que el repo necesita en la nube; lo que falte lo detecta `verify` (ver
+"Dominios y variables nuevos").
+
+1. **Lee qué usa el repo:** `package.json` (scripts, `packageManager`, `engines`), el lockfile,
+   `.tool-versions`, `mise.toml`, `.nvmrc`, archivos de Docker compose, `Dockerfile`,
+   `.env.example`, la CI (`.github/workflows/`) y el README. Lee `.claude/cloud.json` si existe.
+2. **Escribe la preparación en `.claude/cloud.json`** (no toques `version` ni `$schema`):
+   - `setup`: la instalación de dependencias con el gestor del repo y el lockfile congelado
+     (`npm ci`, `pnpm install --frozen-lockfile`, `bun install --frozen-lockfile`…), más lo que
+     haga falta una sola vez (p. ej. navegadores de Playwright). Node y los gestores fijados en
+     `.tool-versions`, `mise.toml`, `.nvmrc` o `packageManager` los instala el paquete solo: no
+     los agregues. Cada paso tiene 180 s y el setup entero debe quedar bajo ~5 min.
+   - `apt` y `aptRepos`: solo lo que el repo necesite y la imagen no traiga.
+   - `session`: comandos rápidos de cada sesión (2 min como máximo cada uno, sin depender de la red).
+   - `domains`: los hosts que el setup o los tests necesitan y que no están en la lista por
+     defecto de gestores de paquetes.
+   - `requiredEnv`: solo los nombres de las variables secretas que de verdad hacen falta en la nube.
+   - `notes`: la ruta del archivo de `notes`.
+3. **Busca los tests del repo:** scripts `test*` y `e2e*` de `package.json`, configuración de
+   runners (`vitest.config.*`, `jest.config.*`, `playwright.config.*`, `.mocharc*`),
+   Testcontainers en las dependencias, compose de tests y los jobs de la CI que corren tests.
+4. **Sin tests:** díselo al usuario y no hagas nada más con tests. Anota en `notes` que el repo
+   no tiene tests y que en la nube solo se prepara la máquina. Sigue en el paso 7.
+5. **Con tests:** agrúpalos (p. ej. unitarios, con base de datos, de navegador) y, para cada
+   grupo, di si correría en la nube tal cual. Si no, propón, en este orden
+   (`reference/compat.md`):
+   1. Adaptar la preparación: `setup`, `session`, `domains`, `requiredEnv`.
+   2. Solo si eso no basta, una variante para la nube: un script aparte (p. ej. `cloud:services`)
+      o una rama por `CLAUDE_CODE_REMOTE` en un script existente.
+   3. Si nada de eso alcanza, déjalo fuera de la nube y explica por qué.
+
+   Muestra cada propuesta con el cambio exacto (archivo y contenido).
+6. **Pregunta y aplica solo lo aprobado.** Un cambio fuera de la config (scripts, compose,
+   configuración de tests) necesita un sí explícito del usuario. Nunca cambies lo que un test
+   comprueba ni crees scripts de tests nuevos sin aprobación.
+7. **Escribe el archivo de `notes`:** qué correr en la nube (el comando tal como lo corre el
+   repo, lo que hay que levantar antes, cuánto tarda y si va en segundo plano), qué no y por qué.
+   Por ejemplo:
+
+   ```markdown
+   En la nube: `npm test` (~1 min). Antes de `npm run test:db`, `docker compose up -d db`
+   (~3 min, en segundo plano). No corre `npm run test:e2e:prod`: pega a una API externa que el
+   entorno no permite.
+   ```
+
+8. **Si existe `.agents/skills/test-audit/project.md`:** escribe o actualiza su sección "Nube"
+   con el mismo resumen; no toques el resto del archivo.
+9. **Corre `agent-cloud-kit manual`** y muéstrale al usuario la sección "Configurar el entorno en
+   claude.ai" de `docs/agent-cloud.md` (setup script, dominios, variables). Dile que ese
+   documento se irá actualizando: si la skill, en local o en la nube, detecta que hace falta un
+   dominio o una variable nueva, lo agrega ahí y se lo dice.
+10. **No hagas commit:** `agent-cloud-kit prepare` lo hace al salir. Si te invocaron fuera de
+    `prepare`, pregunta al usuario.
+11. **Termina diciéndole al usuario que salga:** dile al usuario, con estas palabras o parecidas,
+    "configure terminó: sal de claude con `/exit` y `prepare` sigue (commit, push y PR)". Si te
+    invocaron fuera de `prepare`, omite este paso.
+
+## `verify` (en la nube)
+
+Solo con `CLAUDE_CODE_REMOTE=true`; si no, detente y dilo. El prompt trae la rama de `prepare`
+(`chore/cloud-ready-…`) y puede traer el número del PR. La sesión trabaja en su propia rama
+`claude/…`: no la cambies; al final empujas a la rama de `prepare`.
+
+1. **Contexto:** lee `.claude/cloud.json`, el archivo de `notes` y `docs/agent-cloud.md`. Anota
+   las líneas `agent-cloud-kit:` de falla que mostró el inicio de la sesión ("did not run",
+   pasos fallidos, "another configuration", variables faltantes).
+2. **Corre `agent-cloud-kit doctor`** y guarda la salida. Si `agent-cloud-kit` no está en el
+   `PATH`, el setup no corrió: usa `npx -y agent-cloud-kit doctor` y repórtalo.
+3. **Comprueba la preparación:** dependencias instaladas (p. ej. `node_modules` existe), las
+   versiones fijadas (`node -v` y los demás gestores contra `.tool-versions`, `mise.toml`,
+   `.nvmrc` o `packageManager`), las variables de `requiredEnv` presentes (solo nombres; nunca
+   imprimas valores) y Docker, si el repo lo usa.
+4. **Tests, solo si las `notes` dicen qué correr en la nube.** Córrelos tal como el repo los
+   corre, con lo que haya que levantar antes. Las corridas largas van en segundo plano, con la
+   salida a un log que sigues hasta que terminen. Si las `notes` no dicen qué correr, no corras
+   tests y dilo en el reporte.
+5. **Si algo falla,** diagnostica con `reference/knowledge.md` y `reference/compat.md`, y
+   clasifica:
+   - **Se arregla en la preparación:** cambia solo los archivos de la preparación y vuelve a
+     comprobar. Un cambio de `setup` no se re-ejecuta en esta sesión (el setup ya corrió): corre
+     el comando a mano para probarlo y anota que la máquina guardada se rehará en una sesión nueva.
+   - **Falta un dominio o una variable:** sigue "Dominios y variables nuevos" y deja de intentar
+     arreglos que dependan de eso.
+   - **Solo se cambia en claude.ai** (entorno por defecto con `/remote-env`, rehacer la máquina
+     editando el setup script, el Claude GitHub App): no lo intentes; deja la instrucción exacta
+     para el reporte y deja de intentar arreglos.
+   - **Requiere cambiar código, tests o scripts:** no lo cambies; deja el cambio propuesto
+     (archivo y diff) para el comentario del PR.
+
+   Hasta **3 intentos** de arreglo en total. Tras el tercero, detente y reporta lo que queda.
+6. **Hallazgos:** ver "Hallazgos", abajo.
+7. **Corre `agent-cloud-kit manual`.**
+8. **Antes del commit,** revisa `git diff --name-only HEAD` y `git status --porcelain`. Todo lo
+   que no sea un archivo de la preparación se revierte con `git checkout -- <archivo>` (si está
+   versionado) o se borra (si es nuevo y lo creaste tú). Un cambio necesario al código, tests o
+   scripts queda como propuesta en el comentario del PR.
+9. **Commit y push:** agrega solo los archivos de la preparación que cambiaron, por nombre
+   (`git add -- .claude/cloud.json <archivo de notes> docs/agent-cloud.md`, más
+   `.agents/skills/test-audit/project.md` si lo tocaste); si hay algo en stage,
+   `git commit -m "chore(cloud): verify cloud-ready"`. Luego
+   `git push origin HEAD:<rama de prepare>`. Si el push se rechaza, `git fetch origin <rama de
+   prepare>`, `git rebase FETCH_HEAD` (el clon es parcial: `origin/<rama>` puede no existir) y
+   reintenta una vez.
+10. **Comentario en el PR,** por REST con `gh api` (`gh pr …` usa GraphQL y está bloqueado;
+    `gh auth status` dice que el token es inválido, pero `gh api` funciona):
+    - `owner` y `repo`: de `git remote get-url origin` (las dos últimas partes de la ruta, sin `.git`).
+    - Número del PR: el del prompt; si no viene,
+      `gh api "repos/{owner}/{repo}/pulls?head={owner}:{rama de prepare}&state=open" --jq '.[0].number'`.
+    - Comentario: escribe el cuerpo en un archivo temporal y
+      `gh api repos/{owner}/{repo}/issues/{n}/comments -f body="$(cat <archivo>)"`.
+    - Si no hay PR, el resultado queda solo en `docs/agent-cloud.md` y en tu resumen final.
+    - No saques el PR de draft: lo decide el usuario.
+11. **Resumen final** en la sesión, con lo mismo que el comentario.
+
+### El comentario del PR
+
+```markdown
+## cloud-ready verify
+
+**Comprobado:** `agent-cloud-kit doctor` (salida 0 / qué falló), dependencias, versiones, variables.
+**Corrió:** cada comando, su resultado y cuánto tardó.
+**No corrió:** qué y por qué.
+**Cambiar en claude.ai:** la instrucción exacta (dónde y qué), o "nada".
+**Cambios propuestos al código o los tests:** archivo y diff, o "ninguno".
+**Arreglado en la preparación:** archivos y por qué. Intentos: n de 3.
+**Hallazgos:** los nuevos, o "ninguno".
+```
+
+## Dominios y variables nuevos
+
+En ambos modos, cuando algo falla porque falta un dominio en la red del entorno (el proxy
+rechaza la conexión, `403` o `CONNECT` fallido hacia un host) o una variable de entorno (el
+inicio de la sesión la marca como faltante, o el error nombra una variable vacía):
+
+1. Agrega el host a `domains` o el nombre a `requiredEnv` en `.claude/cloud.json` (solo el
+   nombre; nunca un valor).
+2. Corre `agent-cloud-kit manual`: `docs/agent-cloud.md` queda con lo nuevo.
+3. **Díselo al usuario en la sesión, en ese momento**, sin esperar al final: qué falta, por qué
+   (el comando y el error) y qué hacer, con estas palabras o parecidas: "Falta `<X>` en el entorno
+   de claude.ai. Agrégalo en <Network access / Variables de entorno> (está en
+   `docs/agent-cloud.md`), abre una sesión nueva y corre `/cloud-ready verify`".
+4. En `verify`, ponlo también en "Cambiar en claude.ai" del comentario del PR.
+
+Un dominio que ya está en `domains`, o una variable que ya está en `requiredEnv`, no se agrega
+de nuevo: si sigue faltando, el usuario aún no actualizó el entorno; recuérdaselo.
+
+## Hallazgos
+
+En ambos modos: todo hecho nuevo sobre la nube (algo que no está en `reference/knowledge.md`,
+o que lo contradice) va a la sección `## Hallazgos` de `docs/agent-cloud.md`, fuera de las
+marcas de `agent-cloud-kit` (`manual` la conserva). Una línea por hallazgo, marcada
+"proponer al paquete":
+
+```markdown
+- (proponer al paquete) `docker compose` necesita `--wait` para que la base acepte conexiones.
+  Visto en `verify`, 2026-11-02, con `docker compose up -d db`.
+```
+
+No edites `reference/knowledge.md` del repo: se reemplaza al actualizar el paquete.
+
+## Límites
+
+- `verify` nunca cambia código, tests ni scripts; `configure`, solo con aprobación del usuario.
+- Nunca imprimas ni escribas el valor de una variable secreta; solo su nombre.
+- Nada de `gh pr` ni `gh issue` en la nube: usa `gh api` (REST).
+- No configures claude.ai: da la instrucción exacta y que la haga el usuario.

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.
+```