audit-devground-init

name	audit-devground-init
description	Skill de auditoría destilada para el flujo "devground-init". Acumula el conocimiento de auditorías previas: invariantes confirmadas, falsos positivos ya descartados, y edge cases descubiertos. La cargas ANTES de re-auditar devground-init para partir de un piso más alto y reducir ruido. Generada y mantenida por @devground/deepcheck.

Auditoría destilada — devground-init

Generada por deepcheck. Última corrida: 2026-06-03T15:00:00-04:00. Corridas acumuladas: 2.

Cambios entre corridas (delta crítico — leer primero)

Entre la corrida 1 y la 2, TRES hallazgos previos se ARREGLARON en index.ts. Verifica que sigan arreglados; si una de estas guardas desaparece, vuelve a ser hallazgo:

• --preset inválido ya valida y hace error()+exit(1) (index.ts:57-60). Lo que queda es la falta de TEST del cableado, no el bug.
• no-TTY/CI sin --yes ya se rechaza con exit(1) ANTES del prompt (index.ts:100-103). El falso éxito desapareció. Lo que queda es la falta de TEST de esa guarda.
• catch de detectStack ya tiene binding y discrimina ENOENT vs error real (index.ts:67-77). El diagnóstico falso desapareció.

Estos tres viven en ruta crítica de integridad en CI y NO tienen red de tests: una regresión que los mueva/invierta no la detecta ninguna suite.

Mapa del flujo

packages/cli/src/index.ts es el orquestador: valida --preset (exit 1 si inválido), rechaza entornos no-TTY sin --yes/--preset, lee el manifest de versión, llama detectStack (src/detect-stack.ts → utils/package-json.ts:readPackageJson con readFileSync+JSON.parse), resuelve el set de herramientas (preset estático vía selectPresetValues o prompt prompts), itera los installers en serie acumulando failures, y al final imprime un tally succeeded/total que decide el process.exit. Cada herramienta vive en packages/cli/src/installers/*.ts (prettier, eslint, tsconfig, commitlint, lint-staged, husky, agents-md, architecture-guide). Patrón típico: addDevDependency(...) (que shellea npm/pnpm/yarn add -D vía utils/exec.ts:run() con execSync) y luego escritura del config protegida por el write-guard (installers/write-guard.ts). El write-guard es la garantía central de "no sobreescribir"; husky/agents-md/architecture-guide la EVADEN delegando la escritura a un binario externo. El contrato público se documenta en tres lugares que tienden a desincronizarse: README.md raíz, packages/cli/README.md y la tabla "What it does".

Invariantes confirmadas

Cosas que SON verdad de este flujo y no hay que re-verificar desde cero (pero sí re-chequear que sigan siendo verdad si el código cambió):

• readPackageJson vive en src/utils/package-json.ts:9-13 (NO en src/ops/package-json.ts — ese path no existe; los installers la consumen vía ops.readPackageJson y detect-stack.ts directamente). Hace JSON.parse(raw) as Record<string, unknown> SIN validar que el resultado sea un objeto plano. Es la fuente raíz del hallazgo HIGH de forma (ver hotspots qa-edge).
• run() (utils/exec.ts) usa execSync(cmd, ...) con stdio:'pipe' y string interpolado (shell habilitado). Inyectable POR DISEÑO pero NO explotable en este flujo: todos los inputs son listas estáticas internas o el nombre del PM detectado, no datos de usuario no confiables. No re-reportar como vuln de seguridad.
• Los casts as en fronteras (readPackageJson → as Record<string, unknown>, manifest → as { version: string }, response.tools as string[]) NO violan ADR-0011 (su alcance es DB/API, no CLI args/FS local). No re-reportar como hallazgo de tipos por sí solos. OJO: esto NO absuelve la falta de validación de FORMA en readPackageJson — ese sí es un defecto de correctitud real (ver hotspots), distinto del cast.
• El callback .action() de index.ts queda JUSTO bajo el umbral de función de ADR-0010. No dispara ni la señal warn. No re-reportar como violación de límites.
• getInstallCmd (package-json.ts:27-35) mapea correctamente pnpm/yarn/npm a pnpm add -D / yarn add -D / npm install -D. La lógica es correcta; lo que falta es TEST, no fix.
• La promesa del README raíz sobre el script prepare SÍ se cumple (lo escribe husky vía su binario, fuera de packages/cli/src/). No confundir con el hallazgo HIGH histórico de lint-staged.
• El installer prettier (y el patrón general) ejecuta addDevDependency ANTES del guard. Estructural y confirmado; el guard solo protege el archivo de config, nunca los side effects de instalación.
• La action ES async (index.ts:52) y se invoca con program.parse() síncrono (index.ts:156), NO parseAsync. Mecanismo factualmente correcto pero suprimido (ver supresiones); no re-reportar sin nueva evidencia de daño observable.
• Tests existentes (la red ACTUAL): src/detect-stack.test.ts, src/select.test.ts, src/utils/package-json.test.ts, src/installers/installers.test.ts. NINGUNO importa index.ts → toda la orquestación (tally, exit codes, guardas de preset/TTY) está sin cubrir.

Hotspots por dimensión

Dónde mirar primero en cada dimensión, aprendido de corridas anteriores:

• qa-edge (fuente raíz #1): validación de forma en readPackageJson (utils/package-json.ts:9-13). package.json JSON-válido-pero-no-objeto produce tres daños del MISMO origen: (a) ARRAY [] → data loss silencioso (instala deps reales, reescribe package.json perdiendo el original, reporta success); (b) escalar 42/"x" → TypeError engañoso atribuido a Prettier; (c) null → "Could not read package.json" factualmente falso. Fix correcto: validar forma en readPackageJson/detectStack, NO parchear cada installer. Severidad consolidada HIGH (por el caso array). Revisar también el orden addDevDependency antes de la escritura en cada installer, y los que evaden el guard (agents-md, architecture-guide).
• aud-tests: la orquestación de index.ts no tiene test (ninguna suite importa index.ts). Prioriza las guardas de ruta crítica recién añadidas: rechazo no-TTY (index.ts:100-103, HIGH sin red) y cableado de --preset inválido → exit 1 (index.ts:57-60, LOW: la función pura isValidPreset/selectPresetValues SÍ está testeada en select.test.ts, solo falta el efecto secundario). La rama de dos archivos de tsconfig Next tampoco tiene test.
• val-contracts: (1) el tally final (index.ts:142-152) cuenta succeeded = total - failures, así que un installer OMITIDO (skip por guard) se reporta como "configured successfully" → sobre-reporta el efecto real; debería distinguir installed/skipped/failed. NO es el success() interno de tsconfig (ese ya intenta ser honesto), es el AGREGADO de index.ts. (2) README raíz lista preset next-loose que NO se publica en el tarball y omite next-typecheck que SÍ se publica y que el CLI consume (README.md:107); la descripción del package.json del tsconfig sí es correcta.
• val-requirements (doc↔código): comparar SIEMPRE las 3 docs contra el comportamiento real. Confirmado run 2: el diff "Qué pasa en esos 30 segundos" del README raíz (README.md:55) promete tsconfig.typecheck.json como salida fija, pero el CLI solo lo crea en proyectos Next.js; la línea de eslint del mismo bloque SÍ anota la condicionalidad y packages/cli/README.md:31 lo documenta bien. Hallazgos históricos a re-chequear: lint-staged config key, garantía "No sobreescribe" para husky/agents-md/architecture-guide, architecture-guide ausente de la tabla del CLI.
• aud-perf: el loop de installers (index.ts:132-140) dispara hasta 6 add -D (+3 npx) en serie; cada uno re-resuelve el grafo, re-lee/escribe lockfile y reconstruye node_modules. Los paquetes se conocen ANTES (listas estáticas; única variación = rama Next de eslint, determinística desde el stack ya detectado): recolectarlos y pasarlos en UNA sola invocación recorta latencia de ~6x a 1x. Costo dominante; el resto del I/O síncrono es aceptable para un CLI de un disparo.

Falsos positivos conocidos (supresiones)

Hallazgos reportados antes y descartados. Cada uno lleva fecha + razón. El destilador los RE-VALIDA periódicamente: una supresión no es para siempre.

Hallazgo	Razón del descarte	Fecha	Re-validar después de
README raíz promete un script prepare que ningún installer escribe	Falso positivo por grep mal acotado a packages/cli/src/. La promesa SÍ se cumple (lo escribe husky vía su binario, fuera de ese path)	2026-06-03T15:00:00-04:00	re-validar si cambia README.md o packages/cli/src/installers/husky.ts
detectFramework/readPackageJson castean con as en frontera no confiable (invocando ADR-0011)	El cast en sí NO viola ADR-0011 (alcance DB/API, no CLI/FS). OJO: la falta de validación de FORMA en readPackageJson SÍ es defecto real y está PROMOVIDA a hallazgo HIGH (qa-edge) — esta supresión cubre solo la atribución a ADR-0011, no el bug de forma	2026-06-03T15:00:00-04:00	re-validar si cambia knowledge/adr/0011-*.md o utils/package-json.ts
Errores de npx/instalación pierden detalle cuando la tool escribe diagnósticos en stdout	Mecanismo real pero impacto no aplica: run() usa stdio:'pipe' y descarta e.stdout; index.ts solo imprime err.message — el detalle ya estaba fuera del alcance del flujo	2026-06-03T15:00:00-04:00	re-validar si cambia utils/exec.ts o el manejo de error en index.ts
Falla parcial en installers que shellean deja entorno inconsistente sin rollback	Descripción mecánica exacta pero tratado bajo qa-edge de tsconfig/instalación, no como hallazgo de errores independiente	2026-06-03T15:00:00-04:00	re-validar si cambia husky.ts, agents-md.ts o architecture-guide.ts
run() ejecuta execSync con string interpolado (inyectable) y addDevDependency es sink latente	Código factualmente correcto pero NO explotable: inputs son listas estáticas internas / nombre de PM, no datos no confiables	2026-06-03T15:00:00-04:00	re-validar si exec.ts o package-json.ts empiezan a interpolar input de usuario
El callback .action() concentra demasiadas responsabilidades (borde de ADR-0010)	Auto-clasificado info; NO viola el umbral ni dispara la señal warn; premisa numérica débil	2026-06-03T15:00:00-04:00	re-validar si crece index.ts o cambia knowledge/adr/0010-*.md
La selección del prompt se castea a string[] sin validar (index.ts:122)	Cast real y response.tools es any por @types/prompts, pero no genera daño en este flujo (mismo razonamiento que ADR-0011 sobre fronteras)	2026-06-03T15:00:00-04:00	re-validar si cambia index.ts:122 o el manejo del response del prompt
El manifest se castea a { version: string } sin validar (index.ts:41)	Cierto a nivel sintáctico pero la atribución de riesgo no aplica: el manifest es artefacto interno controlado, no frontera no confiable	2026-06-03T15:00:00-04:00	re-validar si el manifest pasa a leerse de fuente externa
El orquestador index.ts no tiene NINGÚN test (loop de orquestación / exit code)	Hecho crudo cierto (ninguna suite importa index.ts) pero descartado como hallazgo de correctitud; es deuda de cobertura. NOTA: las guardas específicas de no-TTY y preset SÍ se promovieron a hallazgos aud-tests por ser ruta crítica recién introducida	2026-06-03T15:00:00-04:00	re-validar si se agrega/quita cobertura sobre index.ts
package-json.ts: addDevDependency y getInstallCmd sin test	Descripción correcta pero es falta de test, no fix; getInstallCmd ya está confirmado como lógicamente correcto (ver invariantes)	2026-06-03T15:00:00-04:00	re-validar si cambia utils/package-json.ts
La action es async pero se invoca con program.parse() síncrono → unhandled rejection del prompt	Mecanismo factualmente verificado (action async en :52, parse() síncrono en :156) pero descartado: en este flujo no produce el camino de error sucio descrito de forma accionable; sin evidencia de daño observable	2026-06-03T15:00:00-04:00	re-validar si cambia index.ts:52/156 o se añade lógica async tras el prompt
La rama catch de detectStack (ENOENT vs error real) no tiene test que verifique diagnóstico y exit(1)	Factualmente cierto pero NO es defecto de correctitud (el catch YA discrimina bien en :67-77 desde run 2) y es repetición de la deuda de cobertura ya suprimida de index.ts	2026-06-03T15:00:00-04:00	re-validar si cambia index.ts:67-77 o se añade detect-stack/index integration test

Edge cases descubiertos

• package.json JSON-válido-pero-no-objeto — fuente raíz HIGH, tres manifestaciones del mismo bug en readPackageJson (utils/package-json.ts:9-13):
  • ARRAY []: data loss silencioso (instala deps, reescribe package.json perdiendo el original, reporta success). Daño directo según ADR-0012.
  • escalar 42 / "x": TypeError engañoso atribuido a Prettier (el installer real que primero lee propiedades).
  • null: "Could not read package.json" factualmente falso (el archivo existe y se leyó bien; el problema es el contenido).
• package.json existente pero malformado (SyntaxError) o sin permisos (EACCES): RESUELTO en run 2. El catch de index.ts:67-77 ahora discrimina ENOENT (mensaje de "falta package.json") vs cualquier otro error (surfacea err.message). Re-verificar que la discriminación siga si se toca el catch.
• Entorno no-TTY / CI sin --yes: RESUELTO en run 2. index.ts:100-103 rechaza con exit(1) antes del prompt. El falso éxito (exit 0 con cero instalado) desapareció. SIN TEST — regresión silenciosa posible.
• --preset con valor inválido: RESUELTO en run 2. index.ts:57-60 valida y hace error()+exit(1). Ya no cae al prompt. SIN TEST del cableado (la función pura sí está cubierta en select.test.ts).
• Config preexistente con guard: el config se respeta (skip) pero las dependencias YA se instalaron antes del guard → árbol modificado + commit sucio. Además, el tally agregado (index.ts:142-152) cuenta ese skip como "configured successfully" — sobre-reporte del efecto real.
• tsconfig Next con UN solo archivo preexistente (tsconfig.json XOR tsconfig.typecheck.json): estado parcial, uno se omite y otro se escribe, pero siempre imprime success de la variante completa. Pérdida silenciosa de config (daño directo según ADR-0012). La rama de dos archivos no tiene test.
• Stack no-Next (React/Node/lib TS): NO se genera tsconfig.typecheck.json, pese a que README.md:55 lo presenta como salida fija. Promesa documentada incumplida para la mayoría de stacks.