|
|
# before_0_1
|
|
|
|
|
|
> Lo que hay que **cerrar, incluir o verificar** antes de etiquetar
|
|
|
> `0.1.0`. Construido sobre las evidencias del repo a fecha de hoy y los
|
|
|
> hallazgos del audit. Un par de bloqueantes son políticas / hygiene que
|
|
|
> pesan más que cualquier hallazgo técnico individual.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. Qué significa `0.1` aquí (definición operativa)
|
|
|
|
|
|
`0.1` no es _production-ready_. Es la versión que **un equipo externo
|
|
|
puede probar sin sorpresas grandes**, sabiendo que la API pública no
|
|
|
romperá silenciosamente durante la línea `0.1.x`. Esto fija el listón:
|
|
|
|
|
|
- API pública de los 9 roots always-present **congelada** durante `0.1.x`.
|
|
|
- Las 5 factorías scoped (`Sium`, `Session`, `Connections`, `Auth`,
|
|
|
`Permissions`) pueden iterar pero deben respetar deprecation policy.
|
|
|
- Sin bugs de seguridad conocidos en flujos hot.
|
|
|
- Repo aceptable para un PR externo: licencia, README, contributing, CI.
|
|
|
- Docs suficientes para enviar una feature sin leer el código fuente.
|
|
|
- Build estático funciona end-to-end (no solo el typecheck).
|
|
|
|
|
|
Lo que **no** entra en `0.1`: MFA en producción, OAuth con todos los
|
|
|
proveedores, todos los módulos con docs profundas, métricas / telemetría,
|
|
|
ejemplos reales más allá de las páginas `/test`.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. Estado real verificado hoy
|
|
|
|
|
|
Antes de listar gaps, lo que ya está cerrado (corroborado leyendo el
|
|
|
repo, los tests y los gates locales):
|
|
|
|
|
|
- **Tests reales**: 108 archivos / 1208 tests verdes.
|
|
|
- **Typecheck**: `npm run check` 0/0/0.
|
|
|
- **Build estático**: `npm run build` verde.
|
|
|
- **Gate completo**: `npm run test:all` verde (`check` + `test` +
|
|
|
`build` + `test:static` + `test:bundle`).
|
|
|
- **Bundle smoke**: `createActiveApp({})` está medido con Vite/OXC en
|
|
|
`scripts/bundle-smoke.mjs`; baseline actual ~65 KB gzip, presupuesto
|
|
|
`0.1` en 70 KB gzip configurable con `ACTIVE_BUNDLE_GZIP_LIMIT_KB`.
|
|
|
- **Refactor wave** documentada en `NEXT_STEPS.md` ha resuelto
|
|
|
parcialmente varios de mis hallazgos del audit:
|
|
|
- **C2/C3** (Auth → Permissions/Cache invalidation) — cableado a través
|
|
|
de `arts/aapp/integrations/auth-cache.ts`. _A verificar_ con tests
|
|
|
de race cross-actor que el flujo real cierra el gap.
|
|
|
- **C1** (perm race cross-actor) — el cliente perm se ha partido en
|
|
|
`client-cache.ts` / `client-keys.ts` / `client-snapshot.ts`. _A
|
|
|
verificar_ que `pending` se invalida en `hydrate` / cambio de scope.
|
|
|
- Cobertura: `auth + sess + perm + cach` ya tienen test de
|
|
|
integración cruzada.
|
|
|
- **Brand brief** (`BRAND.md`) escrito y assets estáticos añadidos.
|
|
|
- **Documentación interna** (`/active`): shell + landing + Get Started,
|
|
|
páginas para todos los módulos bajo `docs/<module>`, sección de capa
|
|
|
servidor (`$svrs`), seguridad, versionado y guía para AI agents. La
|
|
|
profundidad por módulo sigue siendo desigual y es trabajo pendiente.
|
|
|
|
|
|
Lo que **sigue abierto** sale en §3.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. Bloqueantes duros para `0.1`
|
|
|
|
|
|
Cada bloqueante lleva una _Acceptance criteria_ verificable.
|
|
|
|
|
|
### 3.1 Repo hygiene
|
|
|
|
|
|
Estado actual:
|
|
|
|
|
|
| Pieza | Estado | Evidencia |
|
|
|
| ------------------ | ------- | --------------------------------------------------------------------------------------------- |
|
|
|
| `LICENSE` | Cerrado | Existe y coincide con `package.json` (`UNLICENSED`). |
|
|
|
| `README.md` | Cerrado | Incluye tagline, quick start, módulos, desarrollo, seguridad y link a `BRAND.md`. |
|
|
|
| `SECURITY.md` | Cerrado | Política de reporte y threat model resumido. |
|
|
|
| `CONTRIBUTING.md` | Cerrado | Setup, verificación, layout, constants-first, logging/diagnostics y deprecation policy. |
|
|
|
| `CHANGELOG.md` | Cerrado | Sigue Keep a Changelog y abre `0.1.0` como target. |
|
|
|
| `.github/` | Cerrado | CI, bug report, feature request y PR template. |
|
|
|
| `.gitignore` | Cerrado | Ignora `tmp-active-docs-*.log` y estado local de IDE/herramientas sin ignorar auditorías/docs. |
|
|
|
| `package.json` | Cerrado | `license`, `engines.node`, `repository`, `bugs` y `homepage` presentes. |
|
|
|
|
|
|
Queda como higiene manual: no commitear directorios personales (`.claude/`,
|
|
|
`.opencode/`, `.idea/`) ni logs temporales ya ignorados.
|
|
|
|
|
|
### 3.2 Seguridad
|
|
|
|
|
|
Varios puntos del audit ya están cerrados en código y tests. Mantenerlos aquí
|
|
|
como evidencias evita que el checklist vuelva a arrastrar deuda antigua:
|
|
|
|
|
|
| ID | Estado | Evidencia |
|
|
|
| --- | -------- | ------------------------------------------------------------------------------------------------------ |
|
|
|
| S1 | Cerrado | `rate-limit.test.ts`; password, recovery y OAuth llaman `enforceAuthRateLimit(...)`. |
|
|
|
| S2 | Cerrado | `oauth-pkce.test.ts`; `completeOAuth` entrega `codeVerifier` al provider y valida el challenge. |
|
|
|
| S3 | Cerrado | `engine-password.test.ts`; `verifyMfaChallenge` no está en la superficie estable de `EngineAuth`. |
|
|
|
| S4 | Cerrado | Auth y Cache memory adapters emiten warning productivo con tests; `svrs/perm` no tiene memory adapter. |
|
|
|
| S5 | Cerrado | `AUTH_COOKIE_POLICY.SAME_SITE` es `strict`; `csrf.test.ts` lo cubre. |
|
|
|
| S6 | Cerrado | `client-http.test.ts` cubre in-flight decisions y batch/what tras cambio de actor/scope. |
|
|
|
|
|
|
| ID | Bloqueante | Acceptance |
|
|
|
| --- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
|
| S7 | Cerrado | `SECURITY.md` documenta cookie scopes, CSRF flow, refresh rotation, OAuth state binding, MFA actual y actor/tenant model. |
|
|
|
|
|
|
### 3.3 Correctitud / API
|
|
|
|
|
|
| ID | Estado | Evidencia |
|
|
|
| --- | ------- | -------------------------------------------------------------------------------------------------------------- |
|
|
|
| A1 | Cerrado | `AUTH_METHOD_*` / `PERMISSION_METHOD_*` se usan en `ensureLive`; tests verifican mensajes post-dispose. |
|
|
|
| A2 | Cerrado | `active-app.test.ts` incluye snapshot de superficie de roots y factories scoped actuales. |
|
|
|
| A4 | Cerrado | `AuthRateLimitPort` se exporta porque S1 está cableado y cubierto por tests. |
|
|
|
| A5 | Cerrado | Mono Lang está documentado como passthrough tipado amplio; warnings DEV pasan por `Logger` bajo `lang.mono`. |
|
|
|
|
|
|
| ID | Bloqueante | Acceptance |
|
|
|
| --- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
|
|
|
| A3 | Cerrado | `CONTRIBUTING.md` describe `@deprecated`, warning runtime, `__EXPERIMENTAL_*` y ventana mínima de una minor. |
|
|
|
|
|
|
### 3.4 Documentación mínima
|
|
|
|
|
|
`/active` ya tiene rutas para todos los módulos, pero la profundidad sigue
|
|
|
siendo desigual. Para `0.1`:
|
|
|
|
|
|
| Bloqueante | Acceptance |
|
|
|
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| Los **9 roots always-present** con docs reales (no stub). | `App, Lang, Logger, Formats, Frontend, Dom, Storage, Http, Timers, Cache` tienen sección Overview / Quick start / API / Limits / Testing. |
|
|
|
| Las 5 factorías scoped pueden ser stub si llevan una nota "shape final en `0.2`". | El stub indica explícitamente qué partes de su API no están comprometidas. |
|
|
|
| `SECURITY.md` (cubre S7) **enlazado** desde sidebar de `/active`. | Item en la sección `Get Started` con ruta `/active/security`. |
|
|
|
| Migration / versioning policy publicada. | Página `/active/get-started/versioning` o sección dentro de Composition. |
|
|
|
|
|
|
### 3.5 Build y tooling
|
|
|
|
|
|
| Pieza | Estado | Evidencia |
|
|
|
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------- |
|
|
|
| Build estático | Cerrado | `npm run build` está incluido en `test:all` y fue verificado localmente. |
|
|
|
| CI en GitHub Actions | Cerrado | `.github/workflows/ci.yml` ejecuta typecheck, tests, build, static smoke y bundle smoke. |
|
|
|
| Scripts npm completos | Cerrado | `test:typecheck`, `test:static`, `test:bundle` y `test:all` existen. |
|
|
|
| Reproducibilidad | Cerrado | `package-lock.json`, `.nvmrc` y `engines.node >=22` presentes. |
|
|
|
| Bundle size sanity | Cerrado | `scripts/bundle-smoke.mjs` verifica `createActiveApp({})` contra `ACTIVE_BUNDLE_GZIP_LIMIT_KB`. |
|
|
|
|
|
|
> `npm run lint` existe, pero sigue siendo deuda global pre-`0.1`; CI no
|
|
|
> lo ejecuta hasta que el árbol completo quede limpio. La regla mientras
|
|
|
> tanto es no añadir deuda nueva en archivos tocados.
|
|
|
|
|
|
### 3.6 Marca y assets
|
|
|
|
|
|
Estado actual:
|
|
|
|
|
|
| Pieza | Estado | Evidencia |
|
|
|
| --------------------------- | ------- | ----------------------------------------------------------------------------------------- |
|
|
|
| `static/favicon.svg` | Cerrado | SVG presente. |
|
|
|
| `favicon-16/32/48.png` | Cerrado | PNGs presentes. |
|
|
|
| `apple-touch-icon.png` | Cerrado | Icono 180 presente. |
|
|
|
| `icon-192/512.png` | Cerrado | Iconos PWA presentes. |
|
|
|
| `icon-maskable-512.png` | Cerrado | Icono maskable presente. |
|
|
|
| `og-image.png` | Cerrado | Imagen OG presente. |
|
|
|
| `app.html` | Cerrado | Theme color, description, OG tags, favicons, apple-touch-icon y manifest enlazados. |
|
|
|
| `manifest.webmanifest` | Cerrado | Manifest presente con iconos. |
|
|
|
|
|
|
Queda como revisión manual: abrir `/active` en navegador real y comprobar
|
|
|
contraste/legibilidad de sidebar, code blocks y callouts en tema claro/oscuro.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. Bloqueantes blandos (pueden caer en `0.1.1`–`0.1.x`)
|
|
|
|
|
|
Son hallazgos del audit con impacto real pero acotables a un parche:
|
|
|
|
|
|
- M4 (refactor `validateOptionalField` en sess) — limpieza; no rompe nada.
|
|
|
- M5 (acoplamiento `aapp` ↔ `stor` en mensajes de log) — se puede pulir
|
|
|
más tarde sin tocar la superficie pública.
|
|
|
- M9 (body-scroll-lock con scheduling propio en vez de delegar a `timr`) —
|
|
|
optimización; no afecta la API.
|
|
|
- M10 (HTTP recompone headers en cada retry) — perf, no semántica.
|
|
|
- M14 (sess `BroadcastChannel` ignora el `event` recibido y vuelve a
|
|
|
leer storage) — documentar como diseño y seguir.
|
|
|
- m1–m15 (menores: docs faltantes, magic strings residuales, refactors
|
|
|
cosméticos).
|
|
|
|
|
|
Estos pueden entrar como issues etiquetados `0.1.x` y resolverse de
|
|
|
manera incremental.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. Fuera de alcance para `0.1` (explícito)
|
|
|
|
|
|
Para evitar que el sprint se infle, dejar fuera y comunicarlo:
|
|
|
|
|
|
- MFA real (TOTP, WebAuthn, recovery codes).
|
|
|
- OAuth provider catalog (GitHub, Google, etc.) — solo el motor + un
|
|
|
proveedor de ejemplo.
|
|
|
- Métricas / telemetría / OpenTelemetry export.
|
|
|
- Server-side rendering completo del docs site (es estático).
|
|
|
- Componentes UI prefabricados (eso vive _encima_ de los artefactos).
|
|
|
- Internacionalización del propio docs site (English-only en `0.1`).
|
|
|
- Distribución por `npm publish` — `0.1` puede vivir solo como repo
|
|
|
template / submódulo / vendoring. Decidir si publicar es objetivo.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. Verificación pre-tag (un solo comando)
|
|
|
|
|
|
Antes de etiquetar `0.1.0`, todo esto debe pasar en CI y local:
|
|
|
|
|
|
```sh
|
|
|
# 1. Gate completo automatizado
|
|
|
npm run test:all # → check + tests + build + static smoke + bundle smoke
|
|
|
|
|
|
# 2. Tipos, si se quiere aislar el paso
|
|
|
npm run check # → 0 errors / 0 warnings
|
|
|
|
|
|
# 3. Suite, si se quiere aislar el paso
|
|
|
npm test # → 0 failed; assert >= 1208 tests
|
|
|
|
|
|
# 4. Build estático, si se quiere aislar el paso
|
|
|
npm run build # → produce build/ sin errores
|
|
|
|
|
|
# 5. Bundle smoke, si se quiere aislar el paso
|
|
|
npm run test:bundle # → createActiveApp({}) <= 70 KB gzip por defecto
|
|
|
|
|
|
# 6. Static smoke, si se quiere aislar el paso tras build
|
|
|
npm run test:static # → rutas/docs/assets críticos existen en build/
|
|
|
```
|
|
|
|
|
|
Y, cuando se quiera verificar el sitio servido:
|
|
|
|
|
|
```sh
|
|
|
npm run preview
|
|
|
curl -fsS http://localhost:4173/active | grep -q "active"
|
|
|
curl -fsS http://localhost:4173/test/ecosystem | grep -q "ecosystem"
|
|
|
```
|
|
|
|
|
|
`npm run lint` debe ejecutarse antes del tag, pero hoy todavía representa
|
|
|
una limpieza global separada. No debe bloquear el gate automático hasta
|
|
|
que esa deuda esté cerrada.
|
|
|
|
|
|
Y manual:
|
|
|
|
|
|
- [ ] Abrir `/active` y `/test/ecosystem` en Chromium, Firefox, Safari
|
|
|
desktop. **No console errors. No layout shifts grandes.**
|
|
|
- [ ] `App.dispose()` se llama dos veces seguidas → no throw, no warn.
|
|
|
- [ ] Cambio de locale a `ar` aplica `dir="rtl"` y propaga a Formats.
|
|
|
- [ ] Sign-in → sign-out limpia perm cache y session bridge.
|
|
|
- [ ] Refresh durante revoke → no resucita la sesión.
|
|
|
- [ ] 404 en una ruta `/active/docs/<inexistente>` → muestra fallback.
|
|
|
- [ ] Tema oscuro: contraste suficiente en sidebar activo, code blocks,
|
|
|
callouts.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. Orden sugerido
|
|
|
|
|
|
Dos sprints serios bastan si nadie se desvía.
|
|
|
|
|
|
**Sprint A — Seguridad y correctitud**
|
|
|
|
|
|
Cerrado para el estado actual: S1, S2, S3, S4, S5, S6, S7, A1, A2, A3, A4 y A5.
|
|
|
|
|
|
**Sprint B — Hygiene, docs y release (1 semana)**
|
|
|
|
|
|
1. Repo hygiene: LICENSE, README, CONTRIBUTING, SECURITY, CHANGELOG,
|
|
|
`.github/` con CI básica.
|
|
|
2. A2/A3 — snapshot tests de superficie + política de deprecación
|
|
|
escrita. **Cerrado para la superficie actual**; mantenerlo actualizado
|
|
|
con cada miembro público nuevo.
|
|
|
3. Completar los 9 roots always-present en `/active/docs`.
|
|
|
4. Marca: ejecutar al menos `favicon.svg` + `favicon-32/16` +
|
|
|
`og-image.png` + meta tags en `app.html`.
|
|
|
5. Build estático, static smoke y bundle smoke verificados en CI.
|
|
|
6. Tag `0.1.0` con changelog real.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. Decisiones abiertas (necesitan criterio humano antes de avanzar)
|
|
|
|
|
|
1. **¿Se publica en npm o se distribuye como repo / template?** Cambia
|
|
|
la forma de empaquetar (`exports`, `files`, `sideEffects` granular).
|
|
|
2. **¿`AuthRateLimitPort` se cablea ahora o se posterga?** Si se
|
|
|
posterga, sacarlo del barrel hasta `0.2`.
|
|
|
3. **¿MFA en `0.1` o explicitamente en `0.2`?** Hoy está stubbed; un
|
|
|
stub que lanza no debe estar en la superficie pública.
|
|
|
4. **¿`mono-lang` es público o interno?** Si público, se documenta y
|
|
|
se asume el cast laxo; si interno, se quita del barrel.
|
|
|
5. **¿La doc de los 5 factorías scoped (`Sess`, `Auth`, `Perm`, `Conn`,
|
|
|
`Sium`) llega a `0.1` profunda o stub?** Mi recomendación: `Auth`,
|
|
|
`Sess` y `Perm` profundas (son las que un consumidor pisa en
|
|
|
onboarding); `Conn` y `Sium` pueden quedar como stubs marcados.
|
|
|
6. **¿Adapter Static es el target final?** Si hay plan de SSR (auth
|
|
|
server-side real), conviene cambiar a `adapter-node` antes de
|
|
|
`0.1` para no romper consumidores en `0.1.x`.
|
|
|
7. **¿La API de `App.Cache.invalidate({tags})` queda como contrato
|
|
|
estable?** Se merece ser parte del primer snapshot test de
|
|
|
superficie porque cae en el camino crítico de `Auth`.
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. Métricas de "listo"
|
|
|
|
|
|
Cuando todo lo anterior pase, el repo debería poder responder _sí_ a:
|
|
|
|
|
|
- "¿Un dev externo clona, sigue el README y arranca `/active` en
|
|
|
< 5 min?"
|
|
|
- "¿Existe un punto de contacto claro para reportar un fallo de
|
|
|
seguridad?"
|
|
|
- "¿Hay manera de saber qué cambia entre `0.1.0` y `0.1.1` sin leer
|
|
|
commits?"
|
|
|
- "¿La superficie de los 9 roots always-present está documentada con
|
|
|
una garantía explícita de no-break en la línea `0.1.x`?"
|
|
|
- "¿Si elimino los assets de marca, queda algo identificable en el
|
|
|
navegador?" (Hoy: no, `static/` solo tiene `robots.txt`).
|
|
|
|
|
|
Si las cinco respuestas son sí, etiqueta `0.1.0`.
|
