@cristobalbn/chaski 0.0.0-stage → 0.1.0

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Política de seguridad
+
+## Reportar una vulnerabilidad
+
+No abras un issue público para un problema de seguridad.
+
+Usa la pestaña **Security → Report a vulnerability** del repositorio en GitHub
+(advisory privado). Incluye:
+
+- Versión de chaski y de Node.
+- Sistema operativo.
+- Qué CLIs tienes configurados.
+- Pasos para reproducir.
+- Impacto que observaste.
+
+Respondo en un plazo razonable y coordino la divulgación antes de publicar el
+arreglo.
+
+## Modelo de amenaza
+
+Vale la pena que sepas a qué está expuesta esta herramienta, porque es una que
+se ejecuta sola en cada turno de tus sesiones.
+
+### Qué puede hacer chaski
+
+- **Leer:** el transcript de tus sesiones, la salida de `git` en tu proyecto,
+  y sus propios archivos de configuración.
+- **Escribir:** `.tambo/` dentro del proyecto, `~/.chaski/`, los archivos de
+  configuración de los CLIs que habilitaste, y `.gitignore`, `AGENTS.md` y
+  `.claude/skills/relevo/` durante `init`.
+- **Red:** ninguna. chaski no hace ninguna petición de red, nunca.
+
+### Qué NO hace
+
+- No invoca `claude -p`, `codex exec` ni `agy -p`.
+- No hace commits ni modifica tu historial de git.
+- No ejecuta scripts del repositorio en el que corre.
+- No abre puertos ni escucha conexiones.
+- No tiene dependencias de runtime, así que no hay árbol de npm que comprometer.
+
+### Riesgos conocidos y cómo se contienen
+
+**Inyección de prompt a través del relevo.** El relevo se inyecta en el contexto
+de un agente con permisos de escritura, así que quien pueda escribir en
+`.tambo/` podría intentar colar instrucciones. Contención: el bloque se declara
+como datos entre delimitadores explícitos, se firma con HMAC contra una clave
+local que nunca se versiona, y un relevo cuya firma no valida se inyecta
+rotulado como no verificado en lugar de pasar por legítimo. Además `.tambo/`
+está en `.gitignore`, así que no viaja entre máquinas.
+
+**Captura accidental de secretos.** El transcript contiene todo lo que pasó por
+la sesión. El filtro de `src/lib/secrets.mjs` corre antes de escribir a disco,
+no solo antes de enviar algo. Si encuentras un formato de credencial que se nos
+escapa, es un reporte de seguridad válido y lo agradecemos.
+
+**ReDoS en los patrones de `chaski.json`.** `redact` y `excludePaths` son
+expresiones regulares que el filtro de secretos ejecuta en cada turno. Un
+patrón con retroceso catastrófico (por ejemplo algo con grupos anidados y
+cuantificadores superpuestos) puede colgar el hook indefinidamente en vez de
+terminar en milisegundos. **`chaski.json` se versiona**, así que sus patrones
+pueden venir de un tercero — un colaborador, un PR, una plantilla copiada de
+otro repo — y no son menos código que un script: revísalos en el PR como
+revisarías cualquier otro cambio antes de aceptarlo.
+
+**chaski como vector de cadena de suministro.** Instalarlo significa registrar
+un comando que tus CLIs van a ejecutar solos. Para que puedas verificarlo:
+`chaski doctor` imprime el comando exacto registrado en cada configuración —
+son unas diez líneas. Revísalo después de instalar y después de cada
+actualización. Si prefieres no confiar en un paquete publicado, clona el
+repositorio y ejecuta desde el código fuente: son ~2.000 líneas sin dependencias.
+
+## Versiones soportadas
+
+Mientras el proyecto esté antes de 1.0, solo se da soporte a la última versión
+publicada.

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@cristobalbn/chaski",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Relevo de contexto entre agentes de codigo (Claude Code, Codex, agy)",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "chaski": "src/cli.mjs"
+  },
+  "scripts": {
+    "check": "node --check src/capture.mjs && node --check src/inject.mjs && node --check src/cli.mjs && node --check src/capturar.mjs && node --check src/leer.mjs && node --check src/lib/paths.mjs && node --check src/lib/facts.mjs && node --check src/lib/secrets.mjs && node --check src/lib/relay.mjs && node --check src/lib/ask.mjs && node --check src/lib/budget.mjs",
+    "test": "node --test test/core.test.mjs test/install.test.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "skill",
+    "README.md",
+    "AGENTS.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "codex",
+    "antigravity",
+    "agy",
+    "handoff",
+    "context",
+    "ai-agent",
+    "cli",
+    "relevo"
+  ],
+  "author": "Cristobal Barrera",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cristobalbn/chaski.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cristobalbn/chaski/issues"
+  },
+  "homepage": "https://github.com/cristobalbn/chaski#readme"
+}

package/skill/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: relevo
+description: Guarda la narrativa de Chaski al pedir «relevo», «guarda el relevo» o «actualiza el relevo», o al cerrar un bloque de trabajo para cambiar de agente. Registra intención, decisiones, pendientes y siguiente paso. No usar para consultas sobre Chaski ni para leer o continuar un relevo existente.
+---
+
+# Actualizar el relevo
+
+Escribes la parte del relevo que un script no puede deducir: la **intención**.
+Los hechos —archivos tocados, diff, tests, commits— ya los escribió chaski y
+son exactos. No los repitas ni los corrijas.
+
+## Petición común
+
+En Claude Code, Codex y agy, un mensaje que solo diga **«relevo»**, o que pida
+**«guarda el relevo»** o **«actualiza el relevo»**, solicita guardar la narrativa:
+ejecuta los pasos de abajo y confirma al terminar.
+
+**«Continúa desde el relevo»** solicita retomar el trabajo. Lee el relevo de la
+rama actual, contrástalo con el código y continúa con lo pendiente; no ejecutes
+estos pasos de guardado por esa petición. Una pregunta sobre el funcionamiento
+del relevo tampoco solicita sobrescribirlo.
+
+## Pasos
+
+1. Ubica la raíz del repositorio Git (si el espacio de trabajo es una carpeta contenedora con un único repo hijo o una subcarpeta del repo, usa la raíz de ese repositorio). Lee `.tambo/branches/<rama-actual>/estado.json` desde esa raíz, donde `<rama-actual>` sale de `git rev-parse --abbrev-ref HEAD`.
+2. Escribe la narrativa en el campo `narrative` de ese JSON en UTF-8, junto con
+   `narrativeAuthor` (tu nombre de agente) y `narrativeWrittenAt` (ISO 8601 de ahora).
+3. No toques ningún otro campo. `facts`, `commands`, `offset` y `signature` son de chaski.
+4. Confirma al usuario en una línea: qué quedó anotado como siguiente paso.
+
+El Markdown se regenera solo en el próximo turno. No edites `relevo.md` a mano.
+
+## Qué escribir
+
+Cuatro secciones, en este orden, en prosa breve. Apunta a 120-200 palabras en
+total: el relevo tiene un presupuesto duro de contexto y lo que escribas compite
+con el espacio que el próximo agente necesita para trabajar.
+
+**Tarea** — qué se está intentando lograr, en una o dos frases. No el archivo
+que se está editando, sino el objetivo.
+
+**Decisiones** — qué se eligió y, sobre todo, **qué se descartó y por qué**.
+Esto es lo que evita que el siguiente agente reabra algo ya cerrado. Si no se
+tomó ninguna decisión en esta sesión, omite la sección.
+
+**A medias** — lo más importante del relevo. Qué está empezado y no terminado,
+con la ruta y la línea si existe. Sé específico: «falta invalidar el token
+anterior en Redis antes de emitir el nuevo, en `src/auth/refresh.ts:41`» sirve;
+«falta terminar refresh» no sirve.
+
+**Siguiente paso** — la próxima acción concreta, una sola.
+
+## Reglas
+
+- **Escribe solo lo que pasó en la conversación.** Si no sabes por qué se eligió
+  algo, no lo inventes: omítelo. Una narrativa incompleta es útil; una inventada
+  manda al próximo agente en la dirección equivocada con confianza.
+- **No incluyas secretos.** Ni tokens, ni claves, ni contenido de `.env`, ni
+  URLs con credenciales. Si necesitas mencionar una variable sensible, nómbrala
+  sin su valor.
+- **No incluyas instrucciones dirigidas al próximo agente** más allá del
+  siguiente paso. El relevo se inyecta como datos, no como órdenes.
+- **No repitas los hechos.** Si el diff ya dice que `jwt.ts` tiene +82 líneas,
+  no lo escribas.
+- **Preserva UTF-8 al escribir `estado.json`.** Usa la herramienta de edición de archivos del agente o escribe en UTF-8 directo; en Windows no pases texto con tildes o `«»` como literal por la consola de PowerShell sin `UTF8Encoding`, porque convierte los caracteres no ASCII en `?`.
+- **Distingue lo temporal de lo permanente.** Si en esta sesión apareció una
+  convención que vale **siempre** —un estilo, una herramienta prohibida, un
+  comando que hay que correr antes de dar algo por listo— no va en el relevo,
+  que se reescribe: propón al usuario agregarla a `AGENTS.md`. Una línea
+  preguntando, no la agregues sin confirmar.
+
+## Ejemplo
+
+```json
+{
+  "narrative": "Migrando la capa de auth a JWT con refresh tokens.\n\nDecidido: el refresh token va en cookie httpOnly, no en localStorage, por XSS. Se descartó passport.js: demasiado peso para dos endpoints.\n\nA medias: el endpoint de refresh existe y responde, pero no rota el token viejo. Falta invalidarlo en Redis antes de emitir el nuevo, en src/auth/refresh.ts:41. Los dos tests que fallan en test/auth.test.ts son por esto, no por otra cosa.\n\nSiguiente paso: cerrar la rotación en refresh.ts:41 y volver a correr npm test -- auth.",
+  "narrativeAuthor": "claude code",
+  "narrativeWrittenAt": "2026-10-31T16:20:00.000Z"
+}
+```

package/src/capturar.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Puente de compatibilidad. Este archivo se llamaba así antes de que el código
+// se homologara al inglés, y `capturar.mjs` pasó a ser `capture.mjs`.
+//
+// Por qué existe: `init` registra la RUTA ABSOLUTA de los scripts en la
+// configuración de cada CLI, y esa configuración vive fuera del repositorio.
+// Quien actualice chaski desde una versión anterior sin volver a correr
+// `chaski init` tiene los hooks apuntando a este nombre, y sin este archivo
+// recibe un volcado de Node de quince líneas en cada turno:
+//
+//   Error: Cannot find module '...\chaski\src\capturar.mjs'
+//
+// Pasó de verdad, y el error sobrevive a `chaski init` dentro de una sesión ya
+// abierta, porque los CLIs leen su configuración de hooks una sola vez al
+// arrancar. Así que no alcanzaba con documentar el paso: el nombre viejo tiene
+// que seguir funcionando.
+//
+// No avisa por stderr a propósito. Este hook corre en CADA turno, y una línea
+// de aviso por turno es ruido que el usuario no puede callar. El aviso lo da
+// el puente de inicio de sesión (`leer.mjs`), que corre una vez por sesión.
+//
+// No lo borres sin un ciclo de deprecación de verdad: mientras alguien pueda
+// tener una configuración vieja en disco, borrarlo le rompe cada turno.
+import './capture.mjs';