@ntlinkmx/nt 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,450 @@
-# Temporary Holding Version
+# nt · CLI del backend Go
+
+## Responsabilidad
+
+Cliente Node/TypeScript dentro de este monorepo para comunicarse por HTTP con el
+backend Go de NTLink IA Invoice. Ejecutable **`nt`**, compatible con Windows y
+Linux, Node **22.12 o posterior** y npm. No necesita React abierto ni acceso directo
+a SQL, certificados, Azure o claves de IA: esas dependencias las gestiona Go.
+
+
+## Contrato
+
+### Instalar y comenzar
+
+Instala el paquete publicado y úsalo en PowerShell o Bash:
+
+```sh
+npm install --global @ntlinkmx/nt
+nt --version
+nt --help
+nt mode
+nt mode production
+nt client info
+nt client balance
+```
+
+`npm ci` compila automáticamente; después de cambiar fuentes usa `npm run build`.
+El paquete se publicará como `@ntlinkmx/nt`; instala o actualiza con `npm install --global @ntlinkmx/nt`.
+Para preparar el primer lanzamiento, desde la cuenta npm que será dueña del
+paquete ejecuta `npm login` y `npm publish` dentro de `cli/`. Es un paso inicial:
+npm requiere que el paquete exista antes de activar su trusted publisher.
+Después, en npmjs.com abre `Packages` → `@ntlinkmx/nt` → `Settings` →
+`Trusted Publisher`; elige GitHub Actions y configura
+organización/usuario `NTlink`, repositorio `ntlink-ia-invoice`, workflow
+`publish-invoice-cli.yml` y permite `npm publish`. Para las versiones siguientes,
+cambia la versión del paquete y ejecuta manualmente el workflow desde la rama
+`main` en la pestaña Actions del repositorio. OIDC evita guardar un `NPM_TOKEN`.
+El paquete pertenece al scope `@ntlinkmx`.
+El workflow tiene que estar primero en `main` para poder seleccionarlo en npm.
+Para instalar desde un archivo: ejecuta `npm pack` y luego
+`npm install --global ./ntlinkmx-nt-0.1.0.tgz` desde `cli/`.
+Para retirar el comando global: `npm uninstall --global @ntlinkmx/nt`.
+El perfil predeterminado es `pruebas`. Las instalaciones existentes conservan su configuración guardada.
+El arranque de Go se describe en [desarrollo local](../doc/guides/LOCAL-DEVELOPMENT.md).
+
+### Usar en pruebas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Al instalar, el CLI anuncia que queda en modo `pruebas`. La primera operación protegida inicia sesión automáticamente con la cuenta pública de demostración.
+
+### Cuenta pública de demostración
+
+Estas credenciales son para el modo `pruebas`:
+
+- Correo: `URE180429TM6@ntlink.com.mx`
+- Contraseña: `NTPruebas.2021*?`
+
+### Modos y perfiles
+
+`nt mode` muestra el modo activo sin imprimir el host. `nt mode pruebas` vuelve al entorno de pruebas. `nt mode production` informa que producción estará disponible próximamente y conserva el modo actual.
+
+Cada perfil conserva URL, timeout y token independientes. Los nombres de perfiles
+son etiquetas locales; no cambian las banderas fiscales del servidor.
+
+```sh
+nt --profile local config set --base-url http://localhost:8092 --timeout 120
+nt --profile pruebas config set --base-url http://pruebas.ntlink.com.mx:8092
+nt --profile pruebas auth login --email URE180429TM6@ntlink.com.mx
+nt config use pruebas
+nt config show
+nt config list
+nt --profile local health ready
+```
+
+La URL debe contener protocolo y host/puerto, sin `/api`, usuario, contraseña, query ni fragmento.
+También existe `config set --url URL`. Cambiar la URL guardada de un perfil borra
+su token anterior. Un `--base-url` temporal a otro origen tampoco reutiliza su token.
+
+| Ajuste | Variable | Opción global |
+|---|---|---|
+| Perfil | `NTLINK_PROFILE` | `--profile` |
+| Origen Go | `NTLINK_BASE_URL` | `--base-url` |
+| Bearer | `NTLINK_TOKEN` | `--token` |
+| Timeout en segundos | `NTLINK_TIMEOUT` | `--timeout` |
+
+Prioridad: opción > variable > perfil guardado > valor inicial. No se leen los
+tokens ni el archivo del CLI Proxy. La configuración está en
+`~/.ntlink-invoice/config.json` (Windows: `%USERPROFILE%\.ntlink-invoice\config.json`);
+`NTLINK_INVOICE_CONFIG_DIR` permite cambiar su carpeta.
+Los tokens se almacenan localmente sin cifrar; los archivos nuevos usan modo 0600
+en POSIX y en Windows heredan las ACL de la carpeta del usuario.
+`config show/list` solo muestran el modo y los perfiles; no imprimen el host ni los tokens.
+
+### Autenticación
+
+```sh
+nt auth login
+nt auth login --email usuario@example.invalid
+nt auth status
+nt auth accept-terms
+nt auth logout
+```
+
+El login solicita la contraseña sin mostrarla en terminal. Usa
+`POST /api/v2/auth/login` con `email/password` y guarda el campo `token` devuelto
+por Membership Go. **Go no expone refresh token**: un 401 requiere iniciar sesión
+otra vez. `auth status` consulta el perfil real, no solo la existencia del token.
+`logout` borra el token local del perfil; no revoca JWT ya emitidos ni variables
+de entorno que sigan definidas.
+
+Para automatizar, usa `NTLINK_PASSWORD` o `--password-stdin` con `--email`:
+
+```sh
+nt auth login --email usuario@example.invalid --password-stdin
+```
+
+Conecta stdin desde tu gestor de secretos o tubería. No hay opción `--password`
+para evitar dejarla en los argumentos. `auth register registro.json` envía
+`email`, `name`, `phone`, `rfc`, `postalCode`; puede crear una cuenta y enviar correo.
+`auth verify-code codigo.json` envía `email` y `verificationCode`.
+
+### Cuenta, directorios, estadísticas y reportes
+
+```sh
+nt client info
+nt client balance
+nt client companies
+nt client usage --year 2026
+nt client blacklist AAA010101AAA
+nt customers list
+nt customers get 123
+nt customers create cliente.json
+nt customers update 123 cliente.json
+nt customers delete 123
+nt companies list
+nt companies get 10
+nt companies create emisor.json
+nt companies update 10 emisor.json
+nt users list
+nt users create usuario.json
+nt users update usuario@example.invalid usuario.json
+nt dashboard daily --range LAST_MONTH
+nt dashboard types
+nt dashboard status
+nt dashboard top-receivers
+nt dashboard top-transmitters
+nt reports pending-ppd --company 10 --page 0 --size 50
+nt reports retentions --from 2026-01-01 --to 2026-01-31
+```
+
+`users update` recibe el **correo/username** como identificador, conforme a Go.
+La autorización de usuarios exige administrador. Crear emisor no instala su CSD.
+El CLI envía los JSON sin renombrar campos: los directorios usan los DTO del
+[contrato Portal](../backend/doc/modules/Portal.md) y
+[frontend/src/api/portal.ts](../frontend/src/api/portal.ts).
+Ejemplo sintético de cliente (adapta empresa y datos fiscales antes de guardar):
+
+```json
+{
+  "companyId": 10,
+  "rfc": "AAA010101AAA",
+  "legalName": "CLIENTE DE EJEMPLO",
+  "taxRegime": "601",
+  "postalCode": "06000",
+  "email": "cliente@example.invalid"
+}
+```
+
+El saldo viene de `/customer/balances`, con canales de portal y web service.
+PPD conserva `outstandingBalance` y `balanceSource`; consultar no registra pagos.
+Los listados CFDI/reportes/borradores aceptan `--page`, `--size`, `--company`,
+`--customer`, `--search`, `--from`, `--to`, `--filter KEY=VALUE` y
+`-q KEY=VALUE`. Cada endpoint aplica solo sus filtros admitidos: para borradores,
+por ejemplo, usa `--filter estado=sin-timbrar` o `--filter folio=eq:BOR-000000001`.
+La paginación del portal comienza en cero y admite hasta 200 filas por solicitud;
+no descarga automáticamente las páginas restantes. La salida conserva el sobre
+con `content`, `totalElements`, `totalPages`, `page` y `size`.
+
+### Catálogos, CFDI y borradores
+
+```sh
+nt catalogs list
+nt catalogs get moneda --id MXN
+nt catalogs get ClaveProdServ --description consultoria
+nt cfdi list --from 2026-01-01 --to 2026-01-31 --size 100
+nt cfdi list --filter uuid=eq:00000000-0000-0000-0000-000000000000
+nt cfdi get UUID
+nt cfdi status UUID
+nt cfdi validate factura.xml
+nt cfdi download UUID --format xml --output factura.xml
+nt cfdi download UUID --format pdf --output factura.pdf --force
+nt cfdi prepare cfdi.json
+nt drafts create cfdi.json
+nt drafts list --filter estado=sin-timbrar
+nt drafts get ID
+nt drafts update ID cfdi.json
+nt drafts reserve-folio
+```
+
+Los nombres de catálogo se normalizan al nombre Go, por ejemplo `moneda` →
+`Moneda`. La búsqueda envía `q`; `--id` busca identificador exacto. El listado
+incluye los 15 catálogos del portal; los catálogos nativos adicionales están en
+`native catalogo`. Que un nombre exista no garantiza que la base tenga sus datos.
+
+`cfdi prepare` normaliza/recalcula en Go sin guardar ni emitir. `drafts create`
+y `update` guardan en SQL. `drafts get` devuelve un sobre con `cfdi`, metadatos y
+revisión: para actualizar, envía el **objeto `cfdi` interior**, no todo ese sobre.
+`reserve-folio` reserva un folio provisional BOR, no el consecutivo fiscal.
+Nómina y complementos viajan en el JSON del portal; el CLI no calcula ISR ni
+subsidio. Consulta [emisión](../doc/flows/ISSUANCE.md) y
+[nómina](../backend/doc/parity/payroll.md) para el alcance de cada variante.
+
+Las operaciones explícitas siguientes también tienen comando:
+
+```sh
+nt cfdi stamp cfdi.json
+nt drafts stamp ID cfdi.json
+nt cfdi cancel UUID --reason 02
+nt cfdi cancel UUID --reason 01 --replacement UUID_SUSTITUTO
+nt cfdi email UUID --to facturacion@example.invalid --to archivo@example.invalid
+```
+
+Estos comandos pueden emitir, cancelar o enviar realmente si el servidor lo
+permite. No tienen un modo simulado; nombrar un perfil `pruebas` no garantiza
+que su PAC sea sandbox. Las banderas y permisos de Go siguen siendo obligatorios.
+Las descargas del portal usan `/api/v2/cfdis/{uuid}/xml|pdf`, distintas de las
+rutas de descarga del CLI Proxy, y no sobrescriben archivos sin `--force`.
+
+### Chat y análisis de PDF/XML/JSON
+
+```sh
+nt chat models
+nt chat sessions create
+nt chat sessions list
+nt chat sessions get SESSION_ID
+nt chat attach documento.pdf
+nt chat send SESSION_ID "Analiza las discrepancias de este documento" --attach documento.pdf
+nt chat send SESSION_ID "Consulta mis comprobantes" --provider google --model MODELO_HABILITADO
+nt --timeout 360 chat events RUN_ID
+nt --timeout 360 chat events RUN_ID --last-event-id 3
+nt chat cancel RUN_ID
+nt chat sessions delete SESSION_ID
+```
+
+`send` devuelve `sessionId`, `requestId` y `runId`; consulta sus eventos con
+`chat events`. Se pueden adjuntar hasta tres archivos repitiendo `--attach`.
+`chat attach` extrae el contenido por sí solo. Go conserva los límites de PDF
+(5 MB, 30 páginas) y XML/JSON (1 MB), OCR selectivo y advertencias.
+Los proveedores/modelos deben figurar en `chat models`.
+
+`send --request-id UUID` permite reutilizar un identificador conocido sin crear
+una nueva petición de chat; si falta, se genera uno. Los eventos salen como SSE
+original (`id`, `event`, `data`), no como un único JSON. Un evento `error` o
+`cancelled` es parte del protocolo SSE y debe interpretarlo el consumidor.
+Cerrar el CLI o vencer su timeout no cancela la ejecución del servidor;
+usa `chat cancel`, recupera la sesión y revisa borradores antes de repetir.
+No hay reconexión SSE automática: utiliza `--last-event-id`.
+`chat complete solicitud.json` conserva acceso al contrato síncrono de Go.
+
+Analizar no autoriza guardar: solicita explícitamente la creación de un borrador
+cuando quieras persistirlo. El chat puede consultar y preparar borradores; sus
+herramientas no timbran, cancelan, cobran ni envían correos. Esas capacidades
+pertenecen a los comandos explícitos y rutas nativas correspondientes.
+
+### API manual y rutas nativas
+
+```sh
+nt health live
+nt health ready
+nt parity
+nt api GET /api/v2/customer/profile
+nt api GET /api/v2/cfdis -q page=0 -q size=20
+nt api POST /api/v2/cfdis/prepare --data cfdi.json
+nt api POST /api/v2/cfdis/validate --raw factura.xml --content-type application/xml
+nt native routes
+nt native routes --controller Empresa
+nt native empresa --help
+nt native empresa get-empresa -q id=10
+nt native cfdi descargar-acuse --param id=123 --output acuse.xml
+nt native validarxml validar --file archivoXml=factura.xml
+```
+
+`native` mapea las 87 rutas del registro nativo: catálogos, clientes, empresas,
+usuarios, sesión, CSF, reportes, CFDI/REP, retenciones, plantillas, CSD/FIEL/convenios,
+entrega y compras según el controlador. Todas conservan el método y path de Go.
+`--param KEY=VALUE` sustituye parámetros de ruta, `-q KEY=VALUE` agrega query,
+`--data archivo.json` envía JSON, `--raw archivo` envía bytes y
+`--file CAMPO=RUTA`/`--field CLAVE=VALOR` construyen multipart.
+`--header NOMBRE=VALOR` permite enviar cabeceras adicionales, por ejemplo las
+requeridas por contratos con firma; sus valores no se imprimen en verbose.
+Las tres formas de cuerpo son excluyentes. `--output` guarda cualquier respuesta
+exitosa como bytes; `--stream` muestra SSE original y excluye `--output`.
+
+Para conocer los campos particulares, abre el módulo del controlador desde
+[backend/doc/INDEX.md](../backend/doc/INDEX.md), y consulta los nombres exactos con
+`native GRUPO COMANDO --help`. Los comandos nativos siguen nombres derivados de
+las acciones originales y sus DTO nativos; no reciben automáticamente los DTO del
+portal. Por ejemplo, el `id` nativo de CFDI es el ID SQL, no su UUID.
+La tabla siguiente se sincroniza con `npm run routes:sync`; es un inventario de
+acceso, no una certificación de operación externa.
+
+<!-- native-routes:start -->
+| Comando (`nt native …`) | HTTP | Ruta Go |
+|---|---|---|
+| `catalogo get-clave-unidad` | GET | `/api/Catalogo/ClaveUnidad` |
+| `catalogo get-clave-unidad-filtro` | GET | `/api/Catalogo/ClaveUnidadFiltro` |
+| `catalogo get-clave-unidad-peso` | GET | `/api/Catalogo/ClaveUnidadPeso` |
+| `catalogo buscar-estaciones` | GET | `/api/Catalogo/Estaciones` |
+| `catalogo buscar-clave-prod-serv-cp` | GET | `/api/Catalogo/ClaveProdServCP` |
+| `catalogo buscar-fraccion-arancelaria` | GET | `/api/Catalogo/FraccionArancelaria` |
+| `catalogo buscar-prod-serv` | GET | `/api/Catalogo/ClaveProdServ` |
+| `catalogo get-estados` | GET | `/api/Catalogo/GetEstados` |
+| `catalogo get-paises` | GET | `/api/Catalogo/GetPaises` |
+| `catalogo get-localidad` | GET | `/api/Catalogo/GetLocalidad` |
+| `catalogo get-municipios` | GET | `/api/Catalogo/GetMunicipios` |
+| `catalogo get-cps` | GET | `/api/Catalogo/GetCPs` |
+| `catalogo existe-cp` | GET | `/api/Catalogo/ExisteCP` |
+| `catalogo get-tasa-cuota` | GET | `/api/Catalogo/TasaCuota` |
+| `catalogo get-monedas` | GET | `/api/Catalogo/Monedas` |
+| `cfdi timbrar` | POST | `/api/CFDI/Timbrar` |
+| `cfdi timbrado-previo` | POST | `/api/CFDI/TimbradoPrevio` |
+| `cfdi guardar-plantilla` | POST | `/api/CFDI/Plantilla` |
+| `cfdi listar-plantillas` | GET | `/api/CFDI/Plantillas` |
+| `cfdi obtener-plantilla` | GET | `/api/CFDI/Plantilla/{id:long}` |
+| `cfdi eliminar-plantilla` | POST | `/api/CFDI/Plantilla/{id:long}` |
+| `cfdi descargar-xml` | GET | `/api/CFDI/xml/{id:int}` |
+| `cfdi verificar-pdf` | HEAD | `/api/CFDI/pdf/{id:int}` |
+| `cfdi descargar-pdf` | GET | `/api/CFDI/pdf/{id:int}` |
+| `cfdi descargar-acuse` | GET | `/api/CFDI/acuse/{id:int}` |
+| `cfdi enviar-correo` | POST | `/api/CFDI/correo/{id:int}` |
+| `cfdi enviar-whats-app` | POST | `/api/CFDI/whatsapp/{id:int}` |
+| `cfdi descargar-pdf-whats-app` | GET | `/api/CFDI/wa/{token}/{archivo}` |
+| `cfdi cancelar` | POST | `/api/CFDI/cancelar/{id:int}` |
+| `cliente get-clientes` | GET | `/api/Cliente/GetClientes` |
+| `cliente get-by-id` | GET | `/api/Cliente/GetById` |
+| `cliente guardar` | POST | `/api/Cliente/Guardar` |
+| `config get-session-config` | GET | `/api/Config/session` |
+| `empresa get-empresas` | GET | `/api/Empresa/GetEmpresas` |
+| `empresa get-sucursales` | GET | `/api/Empresa/GetSucursales` |
+| `empresa get-empresa` | GET | `/api/Empresa/GetEmpresa` |
+| `empresa get-sucursales-lista` | GET | `/api/Empresa/GetSucursalesLista` |
+| `empresa get-sucursal` | GET | `/api/Empresa/GetSucursal` |
+| `empresa guardar` | POST | `/api/Empresa/Guardar` |
+| `empresa validar-csd` | POST | `/api/Empresa/ValidarCSD` |
+| `empresa tiene-csd` | GET | `/api/Empresa/TieneCsd` |
+| `empresa subir-fiel` | POST | `/api/Empresa/SubirFiel` |
+| `empresa guardar-sucursal` | POST | `/api/Empresa/GuardarSucursal` |
+| `empresa parse-constancia` | POST | `/api/Empresa/ParseConstancia` |
+| `homedashboard get-stats` | GET | `/api/HomeDashboard/stats` |
+| `listanegra consultar-xml` | POST | `/api/ListaNegra/consultar-xml` |
+| `pagos config` | GET | `/api/Pagos/Config` |
+| `pagos crear-cargo2` | POST | `/api/Pagos/CrearCargo2` |
+| `pagos validar-sesion` | GET | `/api/Pagos/ValidarSesion` |
+| `pagos webhook` | POST | `/api/Pagos/Webhook` |
+| `pagos generar-pre-factura-externa` | POST | `/api/Pagos/GenerarPreFacturaExterna` |
+| `renovarfolios obtener-datos-empresa` | GET | `/api/RenovarFolios/ObtenerDatosEmpresa` |
+| `renovarfolios renovar` | POST | `/api/RenovarFolios/Renovar` |
+| `reporte get-cfdi` | GET | `/api/Reporte/GetCFDI` |
+| `reporte lista-timbrado` | GET | `/api/Reporte/lista-timbrado` |
+| `reporte reporte-anual` | GET | `/api/Reporte/reporte-anual` |
+| `reporte reporte-empresa` | GET | `/api/Reporte/reporte-empresa` |
+| `reporte anios` | GET | `/api/Reporte/anios` |
+| `retenciones reporte` | GET | `/api/Retenciones/Reporte` |
+| `retenciones enviar-correo` | POST | `/api/Retenciones/correo/{id:int}` |
+| `retenciones cancelar` | POST | `/api/Retenciones/cancelar/{id:int}` |
+| `retenciones descargar-acuse` | GET | `/api/Retenciones/acuse/{id:int}` |
+| `retenciones timbrar` | POST | `/api/Retenciones/Timbrar` |
+| `retenciones timbrado-previo` | POST | `/api/Retenciones/TimbradoPrevio` |
+| `retenciones descargar-xml` | GET | `/api/Retenciones/xml/{id:int}` |
+| `retenciones verificar-pdf` | HEAD | `/api/Retenciones/pdf/{id:int}` |
+| `retenciones descargar-pdf` | GET | `/api/Retenciones/pdf/{id:int}` |
+| `retenciones enviar-whats-app` | POST | `/api/Retenciones/whatsapp/{id:int}` |
+| `retenciones descargar-pdf-whats-app` | GET | `/api/Retenciones/wa/{token}/{archivo}` |
+| `session login` | POST | `/api/Session/Login` |
+| `session generar-codigo` | POST | `/api/Session/GenerarCodigo` |
+| `session generar-codigo-correo` | POST | `/api/Session/GenerarCodigoCorreo` |
+| `session validar-codigo` | POST | `/api/Session/ValidarCodigo` |
+| `session heartbeat` | POST | `/api/Session/Heartbeat` |
+| `session logout` | POST | `/api/Session/Logout` |
+| `session recuperar-contrasena` | POST | `/api/Session/RecuperarContrasena` |
+| `session upload-csf` | POST | `/api/Session/UploadCSF` |
+| `session registro` | POST | `/api/Session/Registro` |
+| `session cambiar-contrasena` | POST | `/api/Session/CambiarContrasena` |
+| `usuarioadmin get-usuarios` | GET | `/api/UsuarioAdmin/GetUsuarios` |
+| `usuarioadmin debug-profile` | GET | `/api/UsuarioAdmin/DebugProfile` |
+| `usuarioadmin guardar` | POST | `/api/UsuarioAdmin/Guardar` |
+| `usuarioadmin editar` | POST | `/api/UsuarioAdmin/Editar` |
+| `usuarioadmin cambiar-password` | POST | `/api/UsuarioAdmin/CambiarPassword` |
+| `usuarioadmin bloquear` | POST | `/api/UsuarioAdmin/Bloquear/{userId}` |
+| `usuarioadmin eliminar` | POST | `/api/UsuarioAdmin/Eliminar/{userId}` |
+| `validarxml validar` | POST | `/api/ValidarXML/validar` |
+<!-- native-routes:end -->
+
+## Flujo y fallos
+
+CLI → perfil/variables/opciones → HTTP Bearer a Go → permisos y reglas Go →
+SQL/servicios según la ruta → JSON o archivo. No copia reglas fiscales al cliente.
+Las peticiones anónimas solo se usan en login/registro/verificación, salud/paridad
+y rutas nativas marcadas así por el registro; los catálogos del portal sí llevan JWT.
+`api --anonymous` permite omitirlo deliberadamente.
+
+La salida normal es JSON en stdout (`--json` es compatible y opcional). Los
+errores van a stderr y terminan con código 1; el éxito usa 0. Ayuda/versión son
+texto. `--verbose` imprime método, origen, ruta y estado en stderr; omite tokens,
+query y cuerpos. Con `--output`, stdout devuelve `{ "path": "...", "bytes": 123 }`.
+En PowerShell, evita convertir XML/PDF a texto por tubería: usa `--output`.
+
+No se reintenta ninguna petición automáticamente, tampoco después de 401. Un
+timeout, 502 o fallo de red durante una escritura puede tener resultado incierto:
+consulta su estado antes de repetir. Un timbrado externo y su persistencia SQL
+pueden tener éxito parcial; sigue la recuperación documentada en Go.
+Los errores HTTP conservan estado y mensaje; `exito:false` nativo también falla.
+Go puede devolver 403 por alcance, 409 por conflicto, 501 por módulo pendiente o
+503 por configuración/servicio/catálogo ausente. El CLI no habilita esas funciones.
+
+## Reglas y trazabilidad
+
+| Regla | Implementación y evidencia |
+|---|---|
+| Token separado por perfil y origen | `src/config.ts`; pruebas de perfiles, override y logout |
+| Sin refresh ni repetición automática | `src/http.ts`, `auth login`; pruebas 401/503 y escrituras |
+| Descarga exacta y sin sobrescritura implícita | `src/http.ts`; prueba de bytes y `--force` |
+| Rutas reales sin inventar equivalentes Proxy | `src/native-routes.json`, `scripts/sync-routes.mjs`; prueba contra registro Go |
+| Chat conserva requestId y SSE | `src/cli.ts`; prueba de adjuntos, modelo, eventos y cancelación |
+
+Fuentes: [Portal](../backend/doc/modules/Portal.md),
+[router Go](../backend/internal/api/server.go),
+[registro nativo](../backend/internal/legacy/routes.json),
+[chat Go](../backend/internal/api/ai.go) y
+[capacidades y límites](../doc/FEATURES.md).
+
+## Estado y verificación
+
+Implementación 27/oct/2026. Comprobaciones locales:
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run routes:sync
+npm run build
+```
+
+Las pruebas lanzan el ejecutable real contra un servidor HTTP sintético local;
+comprueban comandos, login, perfiles, contratos de transporte, descargas, multipart,
+chat y errores. No equivalen a integración Go/SQL/PAC ni prueban timbrados,
+cancelaciones, correos, compras o disponibilidad productiva. No se modificó Go.
+Las 11 pruebas pasaron en Windows (Node 24) y Ubuntu mediante WSL (Node 22.22.0).
+También se consultaron `/health/live` y `/health/ready` del Go real en
+`localhost:8092`: estado `ok`, `ready: true`, conexiones main/sat/catalogs `ok`.
+Esas consultas no comprueban login real ni escrituras de negocio.