@fiado/type-kit 3.57.0 → 3.58.0

package/docs/superpowers/plans/2026-05-22-http-client-inversify-v8.md

@@ -1,243 +0,0 @@
-# http-client → inversify v8 (2.0.0) Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Migrar `@fiado/http-client` a inversify 8 (última) y dejarlo listo como major **2.0.0**, con la línea v6 (1.x) como rama de mantenimiento. **No se publica** hasta terminar los cambios y tener visto bueno.
-
-**Architecture:** http-client solo usa `@injectable()` sobre `AxiosHttpRequest` (sin inyección por constructor). El cambio es: (1) introducir un smoke test que prueba que la clase se resuelve desde un `Container`, como guardia de regresión; (2) subir inversify a 8 moviéndola a `peerDependency` + `devDependency`; (3) dejar 2.0.0 listo (publicación diferida). Es la lib hoja (sin deps `@fiado`), por eso va primero.
-
-**Tech Stack:** TypeScript 5.4, inversify 8.x (^8.1.0), reflect-metadata 0.2.2, axios 1.8, jest + ts-jest (nuevo).
-
-**Nota de versión:** se va de v6 directo a **v8** (la última); se salta v7. Confirmado contra las guías oficiales ([v6](https://inversify.io/docs/guides/migrating-from-v6/), [v7](https://inversify.io/docs/guides/migrating-from-v7/)): http-client solo usa `@injectable()`, que **no cambió**.
-
-**Constraint ESM:** inversify 8 es **ESM-only**; CommonJS lo consume vía `require(esm)` solo en **Node ≥20**. El build de la lib (tsconfig commonjs) no cambia, pero el harness de jest debe correr en Node 20+ y puede requerir ajuste si jest no resuelve el paquete ESM (ver Task 3 Step 3).
-
-**Repo:** `/Users/yhon/fsrc/fiado-http-client` (rama base: `develop`, hoy en 1.0.10, limpia tras pull).
-
----
-
-## Estructura de archivos
-
-- `fiado-http-client/jest.config.js` — **crear**: config jest con preset ts-jest.
-- `fiado-http-client/test/AxiosHttpRequest.di.test.ts` — **crear**: smoke test de resolución por container.
-- `fiado-http-client/package.json` — **modificar**: scripts.test, devDependencies (jest, ts-jest, @types/jest, inversify, reflect-metadata), peerDependencies (inversify, reflect-metadata), quitar inversify de dependencies, bump version.
-- `fiado-http-client/src/AxiosHttpRequest.ts` — **modificar solo si v8 lo exige** (no se espera cambio: `@injectable()` sigue igual).
-- `fiado-http-client/tsconfig.json` — **modificar**: excluir `test/` del build de producción.
-
----
-
-## Task 1: Montar harness de tests + smoke test (baseline en inversify 6)
-
-**Files:**
-- Modify: `fiado-http-client/package.json`
-- Create: `fiado-http-client/jest.config.js`
-- Create: `fiado-http-client/test/AxiosHttpRequest.di.test.ts`
-- Modify: `fiado-http-client/tsconfig.json`
-
-- [ ] **Step 1: Instalar dependencias de test**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-npm install -D jest@^29 ts-jest@^29 @types/jest@^29
-```
-Expected: se agregan a `devDependencies`, sin errores de peer deps.
-
-- [ ] **Step 2: Crear `jest.config.js`**
-
-```js
-/** @type {import('ts-jest').JestConfigWithTsJest} */
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['**/test/**/*.test.ts'],
-  setupFiles: ['reflect-metadata'],
-};
-```
-
-- [ ] **Step 3: Actualizar el script de test en `package.json`**
-
-Reemplazar la línea `"test": "test",` por:
-```json
-"test": "jest",
-```
-
-- [ ] **Step 4: Excluir `test/` del build en `tsconfig.json`**
-
-Agregar a `exclude` (junto a `node_modules`):
-```json
-"exclude": [
-  "node_modules",
-  "test"
-]
-```
-
-- [ ] **Step 5: Escribir el smoke test (debe pasar con inversify 6 actual)**
-
-Create `test/AxiosHttpRequest.di.test.ts`:
-```ts
-import 'reflect-metadata';
-import { Container } from 'inversify';
-import { AxiosHttpRequest } from '../src/AxiosHttpRequest';
-import { IHttpRequest } from '../src/IHttpRequest';
-
-describe('AxiosHttpRequest DI', () => {
-  it('se resuelve como IHttpRequest desde un Container de inversify', () => {
-    const container = new Container();
-    container.bind<IHttpRequest>('IHttpRequest').to(AxiosHttpRequest);
-
-    const instance = container.get<IHttpRequest>('IHttpRequest');
-
-    expect(instance).toBeInstanceOf(AxiosHttpRequest);
-    expect(typeof instance.get).toBe('function');
-    expect(typeof instance.post).toBe('function');
-  });
-});
-```
-
-- [ ] **Step 6: Correr el test (baseline verde en inversify 6)**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client && npm test
-```
-Expected: PASS (1 test). Esto fija el baseline antes del bump.
-
-- [ ] **Step 7: Commit**
-
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-git add jest.config.js test/AxiosHttpRequest.di.test.ts package.json package-lock.json tsconfig.json
-git commit -m "test: add DI smoke test and jest harness for http-client"
-```
-
----
-
-## Task 2: Crear rama de mantenimiento v6 antes de subir develop a v8
-
-**Files:** ninguno (operación de git/branch)
-
-- [ ] **Step 1: Cortar la rama de mantenimiento desde el develop actual (1.x)**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-git checkout -b release/1.x
-git push -u origin release/1.x
-git checkout develop
-```
-Expected: `release/1.x` creada en remoto desde 1.0.10. `develop` será la línea v8.
-
----
-
-## Task 3: Subir inversify a v8 como peerDependency
-
-**Files:**
-- Modify: `fiado-http-client/package.json`
-- (posible) Modify: `fiado-http-client/src/AxiosHttpRequest.ts`
-
-- [ ] **Step 1: Quitar inversify de `dependencies` e instalar v8 como peer + dev**
-
-Editar `package.json`:
-- Quitar `"inversify": "^6.0.2"` de `dependencies` (dejar ahí solo `axios` y `typescript`).
-- Agregar bloque:
-```json
-"peerDependencies": {
-  "inversify": "^8.0.0",
-  "reflect-metadata": "^0.2.2"
-},
-```
-- Agregar a `devDependencies`: `"inversify": "^8.1.0"`, `"reflect-metadata": "^0.2.2"`.
-
-Luego instalar:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-npm install
-```
-Expected: inversify 8.x en `node_modules`, sin errores.
-
-- [ ] **Step 2: Compilar contra v8**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client && npm run build
-```
-Expected: PASS. Si falla por la API de decoradores, ajustar el import de `@injectable` según la guía v8 (no se espera; `import { injectable } from 'inversify'` sigue válido).
-
-- [ ] **Step 3: Correr el smoke test contra v8 (debe seguir verde)**
-
-Run:
-```bash
-node --version   # debe ser >= 20 (inversify 8 es ESM-only)
-cd /Users/yhon/fsrc/fiado-http-client && npm test
-```
-Expected: PASS. Notas según la guía oficial:
-- `container.get()` **sigue síncrono** en v8 (convención sync-first), así que el test no debería requerir `getAsync`.
-- Si jest falla al cargar inversify 8 por ser **ESM-only** (error tipo `Cannot use import statement outside a module` o `ERR_REQUIRE_ESM`), habilitar ESM en jest: correr con `NODE_OPTIONS=--experimental-vm-modules`, `preset: 'ts-jest/presets/default-esm'` y `extensionsToTreatAsEsm: ['.ts']` en `jest.config.js`. Documentar el ajuste final para reutilizarlo en las demás libs.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-git add package.json package-lock.json src/
-git commit -m "feat!: bump inversify to v8 as peerDependency
-
-BREAKING CHANGE: requires inversify ^8 in the consumer. inversify ya no
-es dependency directa; ahora es peerDependency para compartir una sola
-instancia con el container del consumidor."
-```
-
----
-
-## Task 4: Bump a 2.0.0 (sin publicar)
-
-**Files:**
-- Modify: `fiado-http-client/package.json`
-
-- [ ] **Step 1: Subir la versión a 2.0.0**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-npm version 2.0.0 --no-git-tag-version
-```
-Expected: `package.json` queda en `"version": "2.0.0"`.
-
-- [ ] **Step 2: Build limpio y verificación final**
-
-Run:
-```bash
-cd /Users/yhon/fsrc/fiado-http-client && npm run build && npm test
-```
-Expected: build OK + test PASS.
-
-- [ ] **Step 3: Commit y tag (sin publicar a npm)**
-
-```bash
-cd /Users/yhon/fsrc/fiado-http-client
-git add package.json
-git commit -m "2.0.0"
-git tag v2.0.0
-git push origin develop --tags
-```
-
-- [ ] **Step 4: Publicación — EN ESPERA**
-
-> **NO publicar todavía.** Por instrucción del usuario, ninguna lib se publica a
-> npm hasta terminar todos los cambios del set (http-client, gateway-adapter,
-> api-invoker) y tener visto bueno explícito. Cuando se autorice, el publish
-> será (resolviendo antes el token de npm del `.npmrc`, ver spec §Seguridad):
->
-> ```bash
-> npm publish               # 2.0.0 como dist-tag "latest"
-> npm dist-tag add @fiado/http-client@1.0.10 legacy-v6
-> ```
-
----
-
-## Self-Review
-
-- **Cobertura del spec:** http-client es la primera lib del §5 del spec; este plan cubre su migración (v8), la creación de la línea de mantenimiento (§6) y deja el publish documentado pero **en espera** (instrucción del usuario). gateway-adapter + api-invoker y las lambdas son planes aparte.
-- **peerDependency:** decisión añadida sobre el spec para garantizar una sola instancia de inversify a través de la frontera lib↔lambda. Coherente con la causa raíz del §2.
-- **Sin placeholders:** todos los pasos tienen comando o código concreto.
-- **Riesgo abierto:** si `container.get` resultara async en 8.x, el Step 3 de Task 3 lo detecta y obliga a actualizar el test; ese hallazgo se documenta para el codemod de las lambdas.

package/docs/superpowers/specs/2026-05-22-inversify-v8-migration-design.md

@@ -1,191 +0,0 @@
-# Migración a inversify v8 (última) con soporte gradual de lambdas en v6
-
-Fecha: 2026-05-22
-Estado: diseño aprobado (estrategia), pendiente de revisión del spec
-Versión objetivo: inversify **8.x** (la última, hoy 8.1.0). Se salta v7; se va de v6 directo a v8.
-
-## 1. Contexto y objetivo
-
-Las libs compartidas (`@fiado/api-invoker`, `@fiado/gateway-adapter`,
-`@fiado/http-client`) dependen hoy de `inversify ^6.x` como dependencia normal.
-122 repos de lambdas las consumen y todos declaran `inversify` directamente,
-repartidos entre el major 1 (~80 repos, `^1.x`) y el major 3 (~30, `^3.x`).
-Las libs se publican a npm público (`registry.npmjs.org`).
-
-**Objetivo:** subir las libs a inversify 8 y migrar las 122 lambdas **de forma
-gradual**, manteniendo las lambdas no migradas funcionando en inversify 6,
-incluyendo la capacidad de sacar hotfixes a las libs para esas lambdas v6.
-
-## 2. Restricciones técnicas (la causa raíz)
-
-- **La DI cruza la frontera lib↔lambda.** Cada lambda hace
-  `const c = new Container(); c.load(gatewayAdapterBindings); c.load(apiInvokerBindings)`
-  y además `c.bind("IHttpRequest").to(AxiosHttpRequest)`. Los `ContainerModule`
-  y las clases `@injectable` viajan desde la lib al container de la lambda.
-- **Consecuencia:** el `ContainerModule`/decoradores producidos por la lib y el
-  `Container` de la lambda **deben ser de la misma versión de inversify**.
-  inversify 6 y 8 no se pueden mezclar en un mismo container (cambian la firma
-  del callback de `ContainerModule`, se elimina el namespace `interfaces`, y
-  cambian APIs de binding). Por eso **no existe una sola versión de lib que
-  sirva para ambos** sin un shim frágil.
-- **Atomicidad de la migración por lambda:** una lambda no puede mezclar
-  `gateway-adapter` v6 con `api-invoker` v8. Debe subir **en un solo PR**:
-  `inversify` 6→8 + el set completo de libs que tocan su container
-  (`api-invoker`, `gateway-adapter`, `http-client`).
-- **Ciclo entre libs:** `gateway-adapter` depende de `api-invoker` y
-  `api-invoker` depende de `gateway-adapter`. No se pueden publicar "uno a la
-  vez"; sus majors nuevos se publican coordinados (ver §5).
-- **Libs sin inversify:** `logger` y `type-kit` no usan el container ni
-  decoradores → **no se tocan** en esta migración.
-
-## 3. Estrategia elegida: majors paralelos (dual-track)
-
-Sacar un **major nuevo** de cada lib del set, construido sobre inversify 8.
-Los majors v6 actuales quedan como **línea de mantenimiento** para backports.
-Cada lambda migra cuando le toca, en un PR atómico. Cada container en runtime
-ve **una sola** versión de inversify.
-
-Líneas resultantes por lib (los majors de NUESTRAS libs son independientes del
-número de versión de inversify):
-
-| Lib            | Línea v6 (mantenimiento) | Línea v8 (nueva)     |
-|----------------|--------------------------|----------------------|
-| http-client    | 1.x                      | 2.0.0                |
-| gateway-adapter| 1.x                      | 2.0.0                |
-| api-invoker    | 3.x                      | 4.0.0                |
-| logger         | —  (sin cambio)          | —                    |
-| type-kit       | —  (sin cambio)          | —                    |
-
-(Estrategias descartadas: desacoplar las libs de inversify por completo —
-refactor enorme incompatible con "gradual"; peerDependency + shim dual-API —
-frágil por las diferencias de API entre v6 y v8.)
-
-## 4. Breaking changes confirmados (v6 → v8)
-
-Verificado contra las guías oficiales ([migrating-from-v6](https://inversify.io/docs/guides/migrating-from-v6/)
-y [migrating-from-v7](https://inversify.io/docs/guides/migrating-from-v7/)).
-Lo que toca este código:
-
-1. **`ContainerModule`**: el callback recibe ahora un objeto
-   `ContainerModuleLoadOptions`; se usa `options.bind(...)`. Afecta
-   `apiInvokerBindings` y `gatewayAdapterBindings`.
-   ```ts
-   // v6
-   export const apiInvokerBindings = new ContainerModule((bind: interfaces.Bind) => {
-     bind<IDirectoryApi>("IDirectoryApi").to(DirectoryApi);
-   });
-   // v8
-   export const apiInvokerBindings = new ContainerModule((options) => {
-     options.bind<IDirectoryApi>("IDirectoryApi").to(DirectoryApi);
-   });
-   ```
-2. **Namespace `interfaces` eliminado**: importar los tipos directamente.
-   `interfaces.Context → ResolutionContext`, `interfaces.Factory → Factory`,
-   `interfaces.Newable → Newable`, `interfaces.Request → BindingConstraints`.
-   Afecta `import { ContainerModule, interfaces } from "inversify"`.
-3. **`toAutoFactory` eliminado** → reescribir con `toFactory`:
-   ```ts
-   // v6 (auth-business)
-   .toAutoFactory("EventBridgeMessageSubscriber")
-   // v8
-   .toFactory((ctx) => () => ctx.get("EventBridgeMessageSubscriber"))
-   ```
-   También: `toProvider → toFactory` (con función async),
-   `toConstructor → toConstantValue`, `toFunction → toConstantValue`.
-4. **`container.load()` SIGUE SIENDO SÍNCRONO en v8** (convención "sync-first":
-   el nombre por defecto es sync, el async es `loadAsync()`). Como nuestros
-   módulos de binding son síncronos, **el patrón `const container = new
-   Container(); container.load(...); export { container }` se conserva** — NO
-   hay que volverlo async. (En v7 sí era async; v8 lo revirtió, a nuestro favor.)
-   `container.get()` también sigue síncrono.
-5. **Opciones del `Container`**: `autoBindInjectable → autobind`;
-   `container.createChild()` → `new Container({ parent })`. Revisar usos.
-6. **`@injectable`/`@inject` sin cambios**; nuevo `@injectFromBase` solo si una
-   clase hereda de una base injectable (revisar herencia).
-7. **inversify 8 es ESM-only**, pero proyectos CommonJS lo consumen vía
-   `require(esm)` en **Node 20+**. ⇒ todas las lambdas deben correr en runtime
-   **Node 20.x o superior**. Verificar el runtime de cada lambda antes de migrar.
-
-Entregable de esta fase: un **codemod / guía** reproducible para
-`container.config.ts` (reescritura de `toAutoFactory`, import de `interfaces`,
-firma de `ContainerModule`), ya que el patrón se repite en las 122 lambdas.
-
-## 5. Orden de trabajo en las libs (un proyecto a la vez)
-
-Para cada lib, antes de tocar: `git checkout develop && git pull`.
-
-1. **http-client** (hoja, solo `@injectable` en `AxiosHttpRequest`):
-   migrar a v8, publicar **2.0.0**. dist-tag `latest` → 2.x, `legacy-v6` → 1.x.
-2. **gateway-adapter + api-invoker** (ciclo): migrar el código de ambos a v8 en
-   ramas, desarrollando con enlaces locales (`npm link` / `file:`) para que
-   compilen uno contra otro. Publicar coordinado con prerelease:
-   - `gateway-adapter@2.0.0-rc.0` con dep `@fiado/api-invoker@^4.0.0-rc`
-   - `api-invoker@4.0.0-rc.0` con dep `@fiado/gateway-adapter@^2.0.0-rc`
-   - validar en 1 lambda piloto, luego promover a `2.0.0` / `4.0.0` finales.
-3. **logger / type-kit**: sin cambios.
-
-> **Publicación en espera:** no se publica ninguna lib a npm hasta terminar los
-> cambios y tener el visto bueno explícito del usuario.
-
-## 6. Política de branching y backport (soporte v6)
-
-- Cortar una rama de mantenimiento por línea v6 en el último release v6:
-  `release/3.x` en api-invoker (desde 3.18.0), `release/1.x` en
-  gateway-adapter y http-client. `develop` pasa a ser la línea v8.
-- **Hotfix que toca una lib mientras una lambda sigue en v6:**
-  1. El fix se hace en la línea natural y se hace `git cherry-pick` a la otra.
-     La mayoría de hotfixes (lógica de negocio, no inversify) tienen archivos
-     idénticos entre líneas → cherry-pick limpio.
-  2. Publicar patch en la línea v6 (ej. `3.18.1`) y, si aplica, en la nueva.
-  3. La lambda v6 (pineada `^3.x`) hace `npm update` y recibe el fix: cero
-     cambio de inversify, cero cambio en su `container.config.ts`.
-- **Disciplina clave:** mantener el major nuevo como un **diff quirúrgico** sobre
-  v6 (tocar solo archivos que tocan inversify) para que los cherry-picks no
-  choquen.
-- **Ventana de soporte:** se backportea **solo al último major v6** (api-invoker
-  3.x). Las ~80 lambdas aún en `^1.x` deben consolidarse a `^3` como parte de
-  (o antes de) la migración, porque hoy ya no pueden recibir fixes limpios.
-
-## 7. Playbook de migración por lambda (gradual)
-
-Por cada lambda, en un PR atómico:
-
-1. `inversify` 6→8 y `reflect-metadata` a la versión alineada.
-2. Subir el set de libs nuevas: `api-invoker` `^4`, `gateway-adapter` `^2`,
-   `http-client` `^2`.
-3. Aplicar el codemod/guía a `container.config.ts`: reescribir `toAutoFactory`
-   → `toFactory`, ajustar imports del namespace `interfaces`. El patrón
-   síncrono `export { container }` **no cambia** (load/get siguen sync en v8).
-4. Verificar que el runtime de la lambda sea **Node ≥20** (inversify 8 ESM-only).
-5. Correr tests + smoke test del handler. Merge y deploy.
-
-Las lambdas no migradas siguen en v6 sin cambios.
-
-## 8. Riesgos
-
-- **Divergencia de líneas v6/v8** si el major nuevo refactoriza de más →
-  mitigado con el "diff quirúrgico".
-- **Ciclo api-invoker↔gateway-adapter** en el publish → mitigado con prerelease
-  rc + dist-tags.
-- **Cola de migración larga** (122 lambdas) → mantener línea v6 viva y priorizar
-  consolidar los `^1.x` a `^3.x`.
-- **Runtime Node <20**: inversify 8 es ESM-only; lambdas en Node 18 o menor no
-  podrán hacer `require(esm)`. Mitigación: auditar y subir a Node 20+ el runtime
-  de cada lambda como prerrequisito de su PR de migración.
-- **Saltar v7→v8 directo** acumula breaking changes; mitigado validando lib por
-  lib con su smoke test antes de avanzar. (El cambio más riesgoso de v7 —`load`
-  async— quedó revertido en v8, así que el bootstrap síncrono se conserva.)
-
-## 9. Criterios de éxito
-
-- http-client@2, gateway-adapter@2, api-invoker@4 construidos sobre inversify 8
-  y validados en 1 lambda piloto (publicación pendiente de visto bueno).
-- Línea v6 (`release/*`) capaz de recibir y publicar un hotfix backporteado.
-- Guía/codemod de `container.config.ts` documentada y reutilizable.
-- Lambdas no migradas siguen desplegando sin cambios.
-
-## Seguridad (fuera de alcance, pero a atender)
-
-`fiado-api-invoker/.npmrc` contiene un token de publicación de npm en texto
-plano. Si está versionado, debe **revocarse/rotarse** en npmjs.com y moverse a
-una variable de entorno / secret de CI.