shardev
Officialby shardevcom
README.md
# @shardev/cli
Servidor MCP (stdio) y CLI (`shardev`) para crear y operar proyectos Laravel + React + AWS ECS, pensado para reemplazar scripts de shell. Solo ESM, Node >= 22.
**Estado: núcleo del generador y lecturas AWS.** Siete herramientas de lectura (T0/T1: `ops_status`, `ops_services`, `ops_tasks`, `ops_logs`, `ops_env_check`, `ops_ci_check`, `log_read`) y seis de escritura local (T2, sin AWS: `project_*`, `app_*`, `ops_ci_generate`). Pendientes (no existen todavía): `mobile_add`, las herramientas `ui_*` y el resto de operaciones que cambian AWS. Hoy son `ops_redeploy` y `ops_scale` (T3): el MCP solo devuelve el comando y lo ejecuta una persona con `shardev ops redeploy` o `shardev ops scale`.
| Herramienta | Tier | Qué hace |
|---|---|---|
| `ops_status` | T1 | Lista proyectos registrados; con `project` (y opcionalmente `env`) muestra perfil AWS, identidad (`aws sts get-caller-identity`) y política efectiva por entorno. |
| `ops_services` | T1 | Estado de los servicios ECS declarados del entorno (`ecs describe-services`): estado, conteos, task definition (`familia:revisión`), despliegues y últimos 5 eventos (texto no confiable). `project` y `env` obligatorios; `service` opcional (omitido = todos los de `services`). Requiere la capacidad `ecs`. |
| `ops_tasks` | T1 | Hasta 20 tareas `RUNNING` (por defecto) o `STOPPED` de un servicio declarado (`list-tasks` + `describe-tasks`): id corto, estados, horas, `stopCode`/`stoppedReason` y contenedores (nombre, estado, `exitCode`, `reason`). Lista blanca de campos: nunca `overrides` ni variables de entorno. Requiere `ecs`. |
| `ops_redeploy` | T3 | Redespliegue forzado de servicios ECS declarados. **No ejecuta nada**: valida proyecto, entorno y servicios, aplica la política y devuelve el comando exacto `shardev ops redeploy --project P --env E (--service S \| --all)` para que lo ejecute una persona (lo ejecuta `shardev ops redeploy`). Exactamente uno de `service` o `all: true`; sin objetivo por defecto. `project` y `env` obligatorios. Requiere `ecs`. disabled, sin sesión, cuenta distinta o entrada inválida no devuelven comando. Lleva `destructiveHint` y `requiresUserInteraction`. |
| `ops_scale` | T3 | Cambia el `desired-count` de servicios ECS declarados. **No ejecuta nada**: valida, aplica la política y devuelve el comando exacto `shardev ops scale --project P --env E (--service S \| --all) --desired-count N` para que lo ejecute una persona. Exactamente uno de `service` o `all: true`; `desired_count` entero 0-20 obligatorio. Con 0 avisa de que los servicios quedan fuera de línea. Requiere `ecs`. disabled, sin sesión, cuenta distinta o entrada inválida no devuelven comando. Lleva `destructiveHint` y `requiresUserInteraction`. |
| `ops_logs` | T1 | Busca en el grupo `/ecs/<servicio>` (`logs filter-log-events`; `since_minutes` 1-1440, por defecto 60; `limit` 1-1000, por defecto 200; `filter` literal de hasta 200 caracteres). **No devuelve el contenido**: lo guarda redactado y devuelve conteo, `truncated`, primer/último timestamp y `log_ref` para `log_read`. Devuelve los eventos **más recientes** de la ventana (los `limit` últimos, ascendentes en el archivo guardado). Antes de guardar, además de los secretos, enmascara correos (`[EMAIL]`) y números de 7+ dígitos o con formato de teléfono (`[NUMERO]`) en el contenido de los eventos (sin flag para desactivarlo; conserva fechas ISO, estados HTTP, puertos y números cortos) y devuelve solo `personal_data_masked` (conteo). **Reduce la exposición, no anonimiza**: nombres, direcciones y texto libre no se detectan, y el texto de `filter` va sin enmascarar a CloudWatch y a la auditoría. Detalle y compromisos (epoch, ID largos) en `docs/decisions/0007-ops-lectura-aws.md`. Borra las copias de esta herramienta con más de 7 días: al iniciar `shardev mcp serve`, en cada comando `shardev ops ...`, en `log_read` y en cada llamada a `ops_logs` (best-effort; `log_read` además rechaza una copia vencida aunque la purga haya fallado). No hay demonio ni temporizador: si no se ejecuta ninguno de esos comandos, los archivos vencidos siguen en disco hasta la próxima ejecución, así que no es un plazo de borrado garantizado. Requiere `logs`. |
| `ops_env_check` | T0 | Valida **sin conexión** (sin AWS, sin cambios) la configuración local de un entorno. `project` y `env` obligatorios. Comprueba: entorno en `ops.yaml` (clasificación, `services`, `capabilities`) y regla `aws_profiles` si es producción; `<root>/.aws/env/<env>/{aws,environment,secrets}.env` (existen, archivos regulares dentro de la raíz, sin enlaces simbólicos; aviso si `secrets.env` es accesible por grupo/otros; fallo si git lo versiona); sintaxis de nombres (duplicados, `^[A-Z_][A-Z0-9_]*$`, líneas sin `=`); `<root>/env.schema` (cada variable en el archivo que su clasificación exige, obligatorias no vacías; sin esquema es un aviso); aislamiento respecto a producción (`DB_DATABASE`, `DB_USERNAME`, `REDIS_HOST`, `AWS_PROJECT_NAME`, `AWS_DOMAIN_NAME`); y consistencia de `AWS_PROFILE`, `AWS_ACCOUNT_ID`, `AWS_ECS_CLUSTER_NAME` y región con el manifest. Devuelve `{project, env, ok, checks: [{name, status: ok|warn|fail|skip, message}], counts}`; `isError` si algún check falla (los avisos no fallan). **Nunca devuelve ni audita valores**, solo nombres de variables, rutas relativas y conteos. Solo valida archivos locales, no lo desplegado. Convenciones y límites en `docs/decisions/0008-env-check.md`. |
| `ops_ci_check` | T0 | Renderiza en memoria el workflow de despliegue de un entorno desde la plantilla **del proyecto** (`<root>/.github/templates/deploy.template.yml`) y lo compara con `<root>/.github/workflows/deploy-<env>.yml`: `up_to_date`, `missing` o `different` (con conteo de líneas distintas, diff acotado y las opciones en uso). `project` y `env` obligatorios; `branch` y `mobile` opcionales (sin ellos se reutiliza la línea `# Opciones:` del workflow actual). Se ignora la cabecera de comentarios generada. No escribe nada, no usa git ni GitHub; `isError` si no está al día. Ver `docs/decisions/0009-ci-workflows.md`. |
| `ops_ci_generate` | T2 | Escribe ese workflow de forma atómica (solo esa ruta; rechaza enlaces simbólicos y rutas fuera de la raíz). En un entorno de **producción** el MCP nunca escribe: devuelve `decision: "command-only"` con el comando `shardev ops ci-generate ...` para que lo ejecute una persona. No hace commit ni push: el archivo debe revisarse y versionarse a mano. |
| `log_read` | T0 | Lee/filtra (grep literal) un log guardado, solo por referencia. El contenido se devuelve marcado como dato no confiable. |
| `project_plan` | T2 | Planifica un proyecto **nuevo** a partir de un spec: archivos (por defecto un resumen por capa: archivos y bytes; `detail: "full"` / `--detail full` da la lista completa), diffs de edits, comandos de verificación, conflictos y `plan_id` (30 min). No escribe el proyecto; `detail` solo cambia la respuesta, no el plan guardado. |
| `project_create` | T2 | Aplica un `plan_id` (nunca un spec): genera en un temporal junto al destino, verifica y renombra atómicamente. |
| `project_verify` | T2 | Re-verifica un proyecto generado y registrado (pasos de las plantillas + escaneo de secretos). |
| `app_plan` | T2 | Planifica añadir una app frontend a un proyecto ya generado (`project_path` bajo `allowed_roots` con `.ops/lock.yaml`): `key`, `user_type` (`new`\|`existing`), `provider`, `table`, `model`, `api_guard`, `session_guard`, `port`, `build_dir` (todos derivados de la `key` si faltan) `features` (`otp`, `social`, `mfa`, `invitations`; `mfa` no se combina con `otp` ni `social`, `invitations` no se combina con `auto_register`), `social_providers` (`google`, `microsoft`, `apple`) y `auto_register` (por defecto `false`). Devuelve archivos, diffs de edits, conflictos, notas y un `plan_id` (30 min) atado al estado de los archivos que toca. No escribe el proyecto. |
| `app_create` | T2 | Aplica un `plan_id` de `app_plan` (nunca datos de la app): solo capas de app y edits por ancla; si algo falla restaura y borra todo. Ver `docs/decisions/0004-app-create.md`. |
`templates/` contiene las capas base (laravel, workspace, packages, app-model, app-auth, tests-auth, app-react, app-workspace, env, docker, claude-kit, verify, y las opcionales app-otp, app-social, app-mfa, mfa-deps, app-invitations, tests-otp, tests-social, tests-mfa, tests-invitations, app-react-otp, app-react-social, app-react-mfa, app-react-invitations); ver `docs/decisions/0003-plantillas.md`. `project_create` solo corre pasos ligeros; `project_verify` corre además composer, migraciones, tests, pnpm, build y `docker compose config`. `app_plan`/`app_create` añaden una app a un proyecto ya generado sin re-renderizar nada de proyecto (los feature layers `otp`, `social`, `mfa` e `invitations` existen, ver `docs/decisions/0005-otp-social.md` y `docs/decisions/0006-mfa-invitations.md`).
## Instalación
Requiere Node >= 22.
```bash
npm install -g @shardev/cli # instala el binario `shardev`
# o, sin instalar: npx @shardev/cli --version
```
Registrar el servidor en Claude Code (lo ejecutas tú; el paquete no toca tu configuración):
```bash
claude mcp add --scope user shardev -- shardev mcp serve
# sin instalación global: claude mcp add --scope user shardev -- npx -y @shardev/cli mcp serve
```
Para evitar prompts en las herramientas de solo lectura, permite `mcp__shardev__ops_status`, `mcp__shardev__ops_services`, `mcp__shardev__ops_tasks`, `mcp__shardev__ops_logs`, `mcp__shardev__ops_env_check`, `mcp__shardev__ops_ci_check` y `mcp__shardev__log_read` en tus permisos. Las herramientas futuras de producción (T3) llevarán `_meta["anthropic/requiresUserInteraction"] = true` y pedirán confirmación en cada llamada (ver `docs/decisions/0001-spikes.md`).
Prueba rápida: `shardev --version`. La CLI es un solo binario: `shardev mcp serve` inicia el servidor y `shardev project plan|create|verify [--json]` `shardev app plan|create [--json]` ejecutan las mismas funciones que las herramientas `project_*` y `app_*`, y `shardev ops status|services|tasks|logs|env-check|log-read` las de `ops_*` y `log_read` (solo lectura; `--project`, `--env`, `--service`, `--status`, `--since-minutes`, `--filter`, `--limit`, `--ref`, `--grep`, `--context`, `--offset`, `--json`; `--env` es obligatorio en services/tasks/logs; sale con código 1 si falla). Ejemplo: `shardev ops logs --project demo --env staging --service demo-staging-app --since-minutes 30 --filter ERROR`. Para validar la configuración local de un entorno sin AWS: `shardev ops env-check --project demo --env staging [--json]` (sale con 1 si algún check falla). Para leer lo que guardó `ops logs`: `shardev ops log-read --ref <log_ref> [--grep ERROR] [--context 2] [--offset 1] [--limit 100]` (límites de `log_read`: `limit` 1-500, `context` 0-5; solo acepta referencias generadas, y marca el contenido como no confiable). Ejemplo: `shardev app plan --project-path ~/projects/acme --key supp --user-type new --json` y luego `shardev app create --plan-id plan_...`.
### Para contribuir
```bash
git clone https://github.com/shardevcom/shardev-mcp.git
cd shardev-mcp
npm install && npm run build
npm link # opcional: expone el binario `shardev` desde tu copia local
```
## Configuración inicial del dueño
Solo se documentan los pasos; nada de esto lo ejecuta el paquete por ti.
1. **Crear la configuración** en `~/.config/shardev-mcp/` (ninguna herramienta la escribe):
- `config.yaml`: `allowed_roots: [/home/yo/projects]`. Sin esto `project_create` no crea nada. Opcionalmente `leftover_terms` (ver más abajo).
- `policy.yaml`: modo por perfil AWS (`default_mode`, `aws_profiles` con `account_id`, `production_mode`, `environments`). Sin archivo todo es `command-only`; producción con un perfil no listado queda `disabled`. Ver `examples/policy.yaml`.
- `projects.yaml`: proyectos registrados (`path` absoluto y `production_envs` opcional). Ver `examples/projects.yaml`.
2. **`ops.yaml` en la raíz de cada proyecto** (nombre, `service_prefix`, `capabilities`, y por entorno `is_production`, `aws_profile`, `account_id`, `region`, `cluster`). Ver `examples/ops.yaml`.
3. Inicia sesión AWS tú mismo (`aws sso login --profile X`); el servidor nunca lo hace.
## Archivos de configuración
Todo vive en `~/.config/shardev-mcp/` (config del dueño) y `~/.local/state/shardev-mcp/` (estado). Las rutas no se pueden cambiar por variables de entorno, a propósito: un `.mcp.json` de proyecto no debe poder apuntar a otra política.
### `~/.config/shardev-mcp/policy.yaml`
Política del dueño, fuera de cualquier proyecto; **ninguna herramienta puede escribirla**. Ejemplo comentado en `examples/policy.yaml`:
```yaml
default_mode: command-only # entornos no productivos
aws_profiles:
mi-perfil-prod:
account_id: "222222222222"
production_mode: command-only
environments: [prod] # opcional
```
- Modos (de menos a más permisivo): `disabled < command-only < gated-apply`. Sin archivo: `command-only`.
- Modo efectivo = el más restrictivo entre la regla del usuario y `policy.max_mode` del `ops.yaml` (el proyecto solo restringe).
- Producción con un perfil que no está en `aws_profiles` => `disabled` (fail closed). `policy.yaml` inválido => todo `disabled`.
- Sin sesión AWS => "operaciones AWS no disponibles" con el comando exacto (`aws sso login --profile X`); el servidor nunca intenta iniciar sesión.
- Cuenta autenticada distinta de la de `ops.yaml` (o de la del perfil en la policy) => rechazo.
- `command-only`: los **cambios** no se ejecutan (se devuelve el comando exacto para que lo ejecutes tú). No bloquea las lecturas fijas de solo lectura `ops_services`, `ops_tasks` y `ops_logs`, que corren también en producción. `disabled`, sin sesión y cuenta distinta siguen bloqueando todo antes de llamar a ECS/CloudWatch.
- `gated-apply`: se lee, pero **no está implementado**; actúa como `command-only` y lo indica en el resultado.
### `shardev ops redeploy` y `shardev ops scale` (las órdenes de la CLI que cambian AWS)
`shardev ops redeploy --project P --env E (--service S | --all) [--json]` fuerza un despliegue nuevo (`ecs update-service --force-new-deployment`) de los servicios declarados, de uno en uno y en orden. Pasa por la misma validación, política e identidad que la herramienta MCP (`disabled`, sin sesión, cuenta distinta o servicio ajeno no preguntan nada ni llaman a ECS). Exige una terminal interactiva (stdin y stderr TTY) y escribir la frase `<proyecto>/<entorno>`; no existe `--yes`, `--force` ni variable que lo eluda, y cualquier flag desconocido es un error. Escribe en `audit.jsonl` una entrada de intención (`phase: "intent"`) **antes** de cambiar (si falla, no cambia nada) y otra de resultado (`phase: "result"`). Se detiene en el primer fallo, no revierte, informa `done`/`failed`/`unknown`/`not_attempted` por servicio y sale con 1 si no todos terminaron bien. Un timeout se informa como `unknown` (puede haberse aplicado). **"Iniciado" no es "completado"**: comprueba el avance con `shardev ops services`. Decisiones en `docs/decisions/0010-operaciones-t3.md`.
`shardev ops scale --project P --env E (--service S | --all) --desired-count N [--json]` (N entero 0-20) cambia el `desired-count` con `ecs update-service --desired-count N` (sin `--force-new-deployment`) y sigue las mismas reglas: confirmación por TTY, sin `--yes`, auditoría de intención antes de cambiar, un servicio tras otro y parada en el primer fallo. Además: antes de preguntar lee el estado actual (`ecs describe-services`) y lo muestra (`deseadas/en ejecución -> N`); si la lectura falla o falta un servicio, no pregunta ni cambia nada; los servicios que ya están en N se informan `unchanged` y no se tocan, y si todos lo están sale con 0 sin preguntar ni escribir intención. La frase es `<proyecto>/<entorno>`, salvo para N=0 (servicios **fuera de línea**), que exige `<proyecto>/<entorno>/apagar`. No detecta autoscaling programado, que podría volver a cambiar el número de tareas. Que AWS acepte el valor no significa que las tareas ya estén en marcha o detenidas.
### `<proyecto>/ops.yaml`
Ejemplo en `examples/ops.yaml`:
```yaml
project: { name: demo }
stack: laravel
service_prefix: demo-
capabilities: [ecs, logs]
policy: { max_mode: command-only } # opcional
environments:
- name: staging
is_production: false
aws_profile: demo-stg
account_id: "111111111111"
region: us-east-1
cluster: shared
services: [demo-staging-app, demo-staging-worker] # opcional, requerido por las lecturas ECS/logs
```
`env` nunca tiene valor por defecto. `is_production` es obligatorio. Los servicios ECS deben empezar por `service_prefix` (el cluster es compartido entre proyectos). Con cluster y cuenta compartidos un prefijo no separa entornos (el `demo-` de producción también cubre `demo-staging-app`), así que `ops_services`, `ops_tasks` y `ops_logs` solo operan sobre servicios que empiecen por el prefijo **y** estén listados exactamente en `services` de ese entorno; sin `services` fallan cerrado (no hay descubrimiento con `list-services`). `capabilities` se aplica: `ecs` para `ops_services`/`ops_tasks`, `logs` para `ops_logs`. Los logs de un servicio se leen del grupo `<log_group_prefix><servicio>`; `log_group_prefix` es opcional por entorno y vale `/ecs/` por defecto (solo letras, dígitos y `_ . / # -`, hasta 200 caracteres, sin `..`; un valor inválido hace fallar la lectura del `ops.yaml`). El servicio sigue teniendo que estar declarado en `services`, así que el prefijo no permite salir de los servicios declarados. Ver `docs/decisions/0007-ops-lectura-aws.md`.
**Compatibilidad al actualizar:** el esquema de entornos es estricto, así que una versión anterior de `shardev` rechaza un `ops.yaml` con `services` (`Unrecognized key`). Actualiza el CLI **antes** de añadir `services`. Lo mismo vale para `log_group_prefix`: mismo orden de actualización (CLI primero, después el `ops.yaml`).
### `~/.config/shardev-mcp/projects.yaml`
```yaml
projects:
demo:
path: /ruta/absoluta/al/proyecto/demo
production_envs: [prod] # opcional
root: /ruta/absoluta/al/codigo/demo # opcional; por defecto, path
```
`path` es donde vive `ops.yaml`. Si el árbol de código (con `.aws/env/` y `env.schema`) está en otro sitio, `root` (ruta absoluta) lo indica; `ops_env_check` es la única herramienta que lo usa y, sin `root`, usa `path`. **Compatibilidad al actualizar:** el esquema de `projects.yaml` es estricto, así que una versión anterior de `shardev` rechaza una entrada con `root` (`Unrecognized key`). Mismo orden de actualización que `services`: primero el CLI, después `projects.yaml`.
**Producción** (la política no confía en el `ops.yaml` del proyecto, que un agente puede editar): un entorno es producción si el manifest dice `is_production: true`, **o** su nombre es `prod`/`production` (sin distinguir mayúsculas), **o** está en `production_envs` de este archivo. Gana producción ante cualquier conflicto y el resultado lo indica (`production_conflict`). El `account_id` no sirve para distinguir: staging y producción comparten cuenta.
Las herramientas reciben el nombre registrado, nunca una ruta libre.
### `~/.config/shardev-mcp/config.yaml`
```yaml
allowed_roots: # sin esto, project_create no crea nada
- /home/yo/projects
leftover_terms: # opcional: restos que no deben llegar a un proyecto generado
- acme-legacy
```
`leftover_terms` es una lista de términos (mínimo 2 caracteres) que el escaneo de restos busca en lo que se genera: coincidencia literal (los caracteres especiales de regex no se interpretan) y sin distinguir mayúsculas. Sirve para nombres de proyectos o dominios de origen que no deben quedar en un proyecto nuevo. Un término contenido en el nombre o dominio del propio proyecto no cuenta. Aplica a `project_create`, `project_verify` y `app_plan`/`app_create`; no forma parte del plan, que sigue siendo determinista. Independientemente de esta lista, el escaneo siempre rechaza ARN y registros ECR con un id de cuenta AWS de 12 dígitos. Ver `examples/config.yaml`.
El destino de `project_plan`/`project_create` y el `project_path` de `app_plan` deben quedar **estrictamente dentro** de una raíz (se resuelven symlinks y `..`).
## Generador
- **Spec** (`src/gen/spec.ts`, zod): `ProjectSpec { name, domain, apps[], features[], mobile? }`; `mobile` se acepta en el esquema (y los locks antiguos que lo traen siguen resolviendo), pero `project_plan` lo rechaza con `invalid_spec` ("mobile todavía no está disponible") mientras no exista ninguna capa de `scope: mobile`: antes se anotaba en el lock sin generar nada. La comprobación se desactiva sola cuando exista esa capa, y no afecta a `app_plan` ni `project_verify`; cada app deriva guards, tabla, provider, modelo y `build_dir` de `key` (todo sobrescribible). Nombres estrictos (sin separadores de ruta); se rechazan duplicados de key, guard, tabla, puerto y `build_dir`.
- **Capas** (`templates/<capa>/layer.yaml`): `scope` (project|app|mobile), `order`, `when`, `requires` (variables que deben usarse), `files` (`src` o `tree`; `render` lista lo que se renderiza en un `tree`), `edits` (`json-merge`, `yaml-append`, `insert` anclado) y `verify` (`full: true` = solo `project_verify`). `{{ secret.app_key }}` etc. se rellenan con valores aleatorios al crear (archivo 0600, fuera del lock). Renderer propio: `{{ var }}` y `{{#if x}}`; estricto (variable desconocida, requerida sin usar o bloque sin cerrar = error); `$VAR`, `${VAR}`, `${{ }}` y variables de nginx pasan intactos; `\{{` emite un `{{` literal.
- **Cableado**: ancla ausente o ambigua = error; reaplicar un edit ya presente es no-op.
- **Plan** puro; se guarda en `~/.local/state/shardev-mcp/plans` (0600) con spec, hash de plantillas y hash del destino, firmado con HMAC (clave en `plan.key`, 0600). Un plan expirado, alterado, con plantillas distintas o con destino cambiado se rechaza. Un plan con conflictos no recibe `plan_id`.
- **Aplicar a repo existente**: árbol limpio, rama base distinta de `master`/`main`, rama nueva derivada del plan (`shardev/<label>-<proyecto>-<id8>`); sin commit, sin push, sin migraciones; si la verificación falla se revierte y se borra la rama.
- **Lock** `.ops/lock.yaml`: hash de plantillas, capas, spec y hash de cada archivo generado. **Verify**: pasos por `exec` (array, stdin cerrado, env explícito, timeout) y escaneo de secretos con los patrones del Redactor (una línea con `shardev-allow-secret` se omite). Decisiones en `docs/decisions/0002-generador.md`.
## Seguridad del motor
- `exec`: solo arrays de argumentos (sin shell), timeout, entorno explícito (PATH, HOME, AWS_PROFILE, AWS_REGION, AWS_DEFAULT_REGION, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE + adiciones por llamada) y stdin cerrado.
- `redact`: enmascara formas conocidas de secretos (sk-ant-, AIza, GOCSPX-, AKIA, tokens de GitHub, JWT, Bearer, claves privadas), `NOMBRE=valor` con nombre de apariencia secreta (incluidas comillas: `export X_TOKEN="a b"`) `nombre: valor` (YAML y logs, con o sin comillas) con nombre de apariencia secreta, credenciales en URLs (`mysql://user:[REDACTED]@host`, se conservan usuario y host) y literales registrados. Limitaciones: es heurístico y prefiere enmascarar de más; no detecta secretos sin forma conocida ni nombre sospechoso (p. ej. un valor suelto en una línea sola), valores multilínea de YAML (`|`, `>`) ni secretos codificados/partidos.
- Logs completos (ya redactados) en `~/.local/state/shardev-mcp/logs` (dir 0700, archivos 0600); los resultados solo llevan resumen, exit code y `log_ref`. `log_read` rechaza cualquier referencia que no sea un nombre de archivo generado (sin `/`, `..`, ni symlinks).
- Lecturas AWS: solo `ecs describe-services`, `ecs list-tasks`, `ecs describe-tasks` y `logs filter-log-events` (más `sts get-caller-identity`), siempre como array de argumentos con `--profile`, `--region`, `--output json` y `--no-cli-pager`; el contenido de logs nunca vuelve en el resultado.
- Auditoría append-only en `~/.local/state/shardev-mcp/audit.jsonl`, tanto del servidor MCP como de la CLI (`shardev project|app|ops`): `source` (`mcp` o `cli`; las líneas antiguas no lo traen y eran del MCP), tool (el mismo nombre del catálogo, p. ej. `ops_services`), proyecto, env, tier, decisión, exit code, duración y argumentos redactados. Una entrada inválida en la CLI queda como `rejected`; un fallo al escribir la auditoría solo avisa por stderr y no cambia la salida ni el código de salida, salvo la entrada `intent` de `ops redeploy` y `ops scale`: si no se puede escribir, no se cambia nada en AWS. Una `intent` sin su `result` significa que el cambio pudo aplicarse. `mcp serve`, `--help` y `--version` no escriben nada.
- stdout es el canal del protocolo; los logs del servidor van a stderr.
## Desarrollo
```bash
npm run typecheck
npm test # rápido: sin red
npm run test:slow # genera un proyecto real y corre composer/pnpm/build (red, ~70 s)
npm run build
```
Los tests usan directorios temporales y un runner falso de `aws`; nunca tocan el HOME real ni AWS. Las decisiones de diseño están en el repositorio (`docs/decisions/`; no se publican en el paquete npm).
This server cannot be deployed