@growconnect/growtickets-nest 0.1.0 → 0.3.0

package/dist/cli/env.d.ts

@@ -0,0 +1,34 @@
+import { type KeygenOptions } from '../env/transport/keygen';
+export interface EnvCliOutcome {
+    exitCode: number;
+    output: string;
+}
+export interface EnvCliDeps {
+    env: Record<string, string | undefined>;
+    cwd: string;
+    fetchImpl?: typeof fetch;
+    /** Segundos, época Unix. */
+    now?: () => number;
+}
+/**
+ * `growtickets-nest env pull`: baja lo que la central tiene para este servidor y escribe la COPIA LOCAL cifrada (la que sirve para arrancar
+ * si la central no contesta), SIN poner nada en el entorno de ningún proceso. Dice la versión y CUÁNTAS variables: nunca sus nombres ni sus
+ * valores, que se quedarían en el historial de la terminal y en el registro del despliegue. Útil en el despliegue para dejar sembrada la
+ * copia, y para comprobar que la clave funciona. Respeta el «no se retrocede»: no pisa una copia de una versión posterior del mismo entorno.
+ */
+export declare function runEnvPull(deps: EnvCliDeps): Promise<EnvCliOutcome>;
+/**
+ * `growtickets-nest env status`: el DOCTOR de las variables desde la central. No habla con la red ni escribe nada: lee el entorno y los
+ * archivos de la pieza y dice qué versión tiene aplicada este servidor, la edad de la copia local y si todo lo necesario para que «Vincular» le
+ * llegue está en su sitio. Nunca enseña un valor ni un nombre de variable aplicada; de la clave, sólo su prefijo.
+ *
+ * `✓` está bien, `!` funciona pero conviene mirarlo, `✗` impide aplicar: sale con 1 si hay alguno.
+ */
+export declare function runEnvStatus(deps: EnvCliDeps): EnvCliOutcome;
+export type EnvKeygenOptions = KeygenOptions;
+/**
+ * `growtickets-nest env keygen`: genera el par de ESTE servidor aquí mismo, para que su llave privada no pase nunca por un navegador ni por un
+ * portapapeles (ver `runKeygen`, que es del transporte: sabe qué es una credencial). Sin `--central` genera la semilla y enseña sólo la
+ * pública; con `--central=<llave de la central>` arma la credencial y, con `--write`, la escribe en el `.env`.
+ */
+export declare function runEnvKeygen(deps: EnvCliDeps, options: EnvKeygenOptions): EnvCliOutcome;

package/dist/cli/env.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEnvPull = runEnvPull;
+exports.runEnvStatus = runEnvStatus;
+exports.runEnvKeygen = runEnvKeygen;
+const errors_1 = require("../env/errors");
+const runtime_1 = require("../env/runtime");
+const keygen_1 = require("../env/transport/keygen");
+const sdk_1 = require("../security/sdk");
+/** Un runtime privado para el proceso de la CLI: lee el entorno que se le da y NO se instala en `globalThis`, ni arranca temporizadores. */
+function cliRuntime(deps) {
+    return new runtime_1.EnvRuntime({
+        env: () => deps.env,
+        fetchImpl: deps.fetchImpl,
+        now: deps.now ?? (() => Math.floor(Date.now() / 1000)),
+        cwd: () => deps.cwd,
+        warn: () => undefined,
+        timer: false,
+    });
+}
+/**
+ * `growtickets-nest env pull`: baja lo que la central tiene para este servidor y escribe la COPIA LOCAL cifrada (la que sirve para arrancar
+ * si la central no contesta), SIN poner nada en el entorno de ningún proceso. Dice la versión y CUÁNTAS variables: nunca sus nombres ni sus
+ * valores, que se quedarían en el historial de la terminal y en el registro del despliegue. Útil en el despliegue para dejar sembrada la
+ * copia, y para comprobar que la clave funciona. Respeta el «no se retrocede»: no pisa una copia de una versión posterior del mismo entorno.
+ */
+async function runEnvPull(deps) {
+    const runtime = cliRuntime(deps);
+    if (!runtime.enabled())
+        return { exitCode: 1, output: `✗ ${runtime.transport.diagnose()[0]?.text ?? 'Está apagada.'}` };
+    let payload;
+    try {
+        payload = await runtime.transport.fetch();
+    }
+    catch (error) {
+        const fallo = error instanceof errors_1.EnvError ? error : new errors_1.EnvError('unreachable', 'No se pudo hablar con la central.');
+        return { exitCode: 1, output: `✗ ${fallo.message} (${fallo.reason})` };
+    }
+    if (payload === null)
+        return { exitCode: 1, output: '✗ La central no mandó nada.' };
+    const copia = runtime.snapshot.read();
+    const estado = runtime.state.read();
+    const minimo = Math.max(copia && copia.payload.environmentId === payload.environmentId ? copia.payload.version : 0, estado.environment === payload.environmentId ? estado.version : 0);
+    if (payload.version < minimo) {
+        return { exitCode: 1, output: `✗ La central dio la versión ${payload.version}, anterior a la ${minimo} que ya tiene este servidor: no se retrocede (rollback).` };
+    }
+    if (!runtime.snapshot.write(payload)) {
+        return { exitCode: 1, output: '✗ No se pudo escribir la copia local (¿carpeta sin permisos? GROWTICKETS_ENV_DIR fija otra).' };
+    }
+    const cuantas = Object.keys(payload.variables).length;
+    const lineas = [`✓ «${payload.environmentName}» v${payload.version}: ${cuantas} variables. Copia local cifrada escrita en ${runtime.storage.directory() ?? '(sin carpeta)'}.`];
+    if (payload.discarded.length > 0)
+        lineas.push(`  ${payload.discarded.length} variables se ignoran por política (prefijo GROWTICKETS_, las del sistema…): no se pondrán en el entorno.`);
+    return { exitCode: 0, output: lineas.join('\n') };
+}
+/**
+ * `growtickets-nest env status`: el DOCTOR de las variables desde la central. No habla con la red ni escribe nada: lee el entorno y los
+ * archivos de la pieza y dice qué versión tiene aplicada este servidor, la edad de la copia local y si todo lo necesario para que «Vincular» le
+ * llegue está en su sitio. Nunca enseña un valor ni un nombre de variable aplicada; de la clave, sólo su prefijo.
+ *
+ * `✓` está bien, `!` funciona pero conviene mirarlo, `✗` impide aplicar: sale con 1 si hay alguno.
+ */
+function runEnvStatus(deps) {
+    const runtime = cliRuntime(deps);
+    const ajustes = runtime.settings();
+    const ahora = (deps.now ?? (() => Math.floor(Date.now() / 1000)))();
+    const lineas = ['', '  GrowTickets · variables de entorno', ''];
+    let fallos = 0;
+    const ok = (texto) => lineas.push(`  ✓ ${texto}`);
+    const aviso = (texto) => lineas.push(`  ! ${texto}`);
+    const fallo = (texto) => {
+        fallos++;
+        lineas.push(`  ✗ ${texto}`);
+    };
+    if (!runtime.enabled()) {
+        for (const c of runtime.transport.diagnose())
+            aviso(c.text);
+        return { exitCode: 0, output: [...lineas, ''].join('\n') };
+    }
+    for (const c of runtime.transport.diagnose())
+        (c.level === 'ok' ? ok : c.level === 'warn' ? aviso : fallo)(c.text);
+    const aplicada = runtime.state.read();
+    if (aplicada.applied === null)
+        aviso('Este servidor todavía no ha aplicado ninguna versión (¿falta loadGrowTicketsEnv() en main.ts?).');
+    else
+        ok(`Aplicada la versión ${aplicada.version} del entorno ${aplicada.environment} (${aplicada.count} variables), ${hace(ahora, aplicada.appliedAt)}.`);
+    if (aplicada.discarded.length > 0)
+        aviso(`Se ignoran por política: ${aplicada.discarded.join(', ')} (el prefijo GROWTICKETS_ y las del sistema no las puede poner la central).`);
+    const copia = runtime.snapshot.read();
+    const edad = runtime.snapshot.ageHours(copia);
+    if (copia === null) {
+        aviso('No hay copia local legible: si la central no contesta al arrancar, no hay con qué seguir. Corre growtickets-nest env pull.');
+    }
+    else {
+        ok(`Copia local cifrada: v${copia.payload.version}, confirmada ${hace(ahora, copia.fetchedAt)}.`);
+        if (edad !== null && edad > ajustes.maxStaleHours)
+            aviso(`La copia tiene más de ${ajustes.maxStaleHours} h (GROWTICKETS_ENV_MAX_STALE_HOURS): ya no sirve para arrancar sin la central.`);
+    }
+    lineas.push(`  · Esta réplica: ${(0, sdk_1.instanceId)(deps.env)}`);
+    lineas.push(`  · La central avisa en: POST /${ajustes.path}/apply y confirma el dominio en GET /${ajustes.path}/identity (fuera del prefijo global; los contesta el middleware de main.ts)`);
+    lineas.push(`  · Si la central no contesta: ${ajustes.onFailure === 'fail' ? 'no se arranca' : `se arranca con la copia local (hasta ${ajustes.maxStaleHours} h)`}`);
+    lineas.push(`  · Al cambiar una versión: ${ajustes.onChange === 'reload' ? 'se actualiza process.env en caliente y se llama a onEnvChange' : `cierre ordenado del proceso con código ${ajustes.exitCode} (GROWTICKETS_ENV_EXIT_CODE; el gestor tiene que levantarlo otra vez: Railway «On Failure», Docker restart, PM2)`}`);
+    lineas.push('');
+    return { exitCode: fallos > 0 ? 1 : 0, output: lineas.join('\n') };
+}
+function hace(ahora, momento) {
+    if (momento <= 0)
+        return 'en un momento desconocido';
+    const minutos = Math.floor(Math.max(0, ahora - momento) / 60);
+    if (minutos < 1)
+        return 'hace un momento';
+    if (minutos < 60)
+        return `hace ${minutos} min`;
+    if (minutos < 1440)
+        return `hace ${Math.floor(minutos / 60)} h`;
+    return `hace ${Math.floor(minutos / 1440)} d`;
+}
+/**
+ * `growtickets-nest env keygen`: genera el par de ESTE servidor aquí mismo, para que su llave privada no pase nunca por un navegador ni por un
+ * portapapeles (ver `runKeygen`, que es del transporte: sabe qué es una credencial). Sin `--central` genera la semilla y enseña sólo la
+ * pública; con `--central=<llave de la central>` arma la credencial y, con `--write`, la escribe en el `.env`.
+ */
+function runEnvKeygen(deps, options) {
+    return (0, keygen_1.runKeygen)(cliRuntime(deps).storage, deps.cwd, options);
+}

package/dist/cli/index.js

@@ -5,18 +5,29 @@ exports.runCli = runCli;
 const args_1 = require("./args");
 const check_1 = require("./check");
 const deps_1 = require("./deps");
+const env_1 = require("./env");
 const init_1 = require("./init");
+const transport_1 = require("../env/transport");
+const host_1 = require("../logs-nest/host");
+const doctor_1 = require("../logs/doctor");
 const HELP = [
-    'growtickets-nest <init|check|deps> [opciones]',
+    'growtickets-nest <init|check|deps|doctor|env> [opciones]',
     '',
     '  init     Crea o completa .env.example y .gitignore, e imprime cómo montar el módulo y el middleware de main.ts.',
     '             --dry-run            No escribe nada; sólo imprime lo que haría.',
     '  check    De sólo lectura. Sale con 1 si la clave puede acabar versionada, y avisa de un montaje que no hará lo que se espera.',
+    '  doctor   Comprueba los logs de punta a punta: el entorno, la clave con el alcance «Logs» y el módulo encendido en el proyecto. Los fallos de esta parte no dan error, sólo un explorador vacío. Con GROWTICKETS_ENV_KEY suma el informe de env status.',
+    '             --send               Además manda una línea de prueba y comprueba que llega.',
     '  deps     Manda a GrowTickets los nombres y versiones de tus paquetes (de package-lock.json, pnpm-lock.yaml o yarn.lock) para vigilar sus vulnerabilidades. Pensado para CI.',
     '             --lockfile <ruta>    El archivo de bloqueo, en vez de buscarlo en el directorio actual.',
     '             --app <nombre>       Cómo aparece el proyecto en el informe (por defecto, el name del package.json).',
     '             --origin <url>       La dirección pública del producto (o GROWTICKETS_ORIGIN): distingue este servidor de otro con el mismo nombre.',
     '             --dry-run            Cuenta lo que se enviaría, sin enviar nada. Necesita GROWTICKETS_API_KEY para enviar de verdad.',
+    '  env      Las variables de entorno que GROWTICKETS_ENV_KEY trae desde la central (nunca imprime nombres de secretos ni valores).',
+    '             env pull             Baja la versión vigente y escribe la copia local cifrada; dice la versión y cuántas variables.',
+    '             env status           Versión aplicada, edad de la copia y qué falta para que «Vincular» llegue. No usa la red.',
+    '             env keygen           Genera aquí el par de este servidor (la privada no sale de él) y enseña sólo la pública para «Ya tengo una llave pública».',
+    '                                  Después: env keygen --central=<llave de la central> --write arma GROWTICKETS_ENV_KEY en el .env (--force: otra llave).',
 ].join('\n');
 /**
  * La entrada que usa el binario: igual que `runCli` pero además atiende `deps`, el único comando que habla con la red
@@ -24,12 +35,35 @@ const HELP = [
  */
 async function runCliAsync(argv, cwd = process.cwd(), env = process.env, fetchImpl) {
     const parsed = (0, args_1.parseArgs)(argv);
+    if (parsed.command === 'env')
+        return runEnvCommand(argv, cwd, env, fetchImpl);
+    if (parsed.command === 'doctor') {
+        if (parsed.unknown.length > 0)
+            return { exitCode: 1, output: `Opción desconocida: ${parsed.unknown.join(', ')}\n\n${HELP}` };
+        const { exitCode, lines } = await (0, doctor_1.runLogsDoctor)({ ...(0, host_1.createLogsHost)(), env: () => env, fetchImpl }, { send: parsed.send });
+        const informeEnv = (0, transport_1.envConfigured)(env) ? (0, env_1.runEnvStatus)({ env, cwd }) : null;
+        return { exitCode: Math.max(exitCode, informeEnv?.exitCode ?? 0), output: [...lines, ...(informeEnv ? [informeEnv.output] : [])].join('\n') };
+    }
     if (parsed.command !== 'deps')
         return runCli(argv, cwd);
     if (parsed.unknown.length > 0)
         return { exitCode: 1, output: `Opción desconocida: ${parsed.unknown.join(', ')}\n\n${HELP}` };
     return (0, deps_1.runDeps)(cwd, { lockfile: parsed.lockfile, app: parsed.app, origin: parsed.origin, dryRun: parsed.dryRun }, env, fetchImpl);
 }
+/** `env pull`, `env status` y `env keygen`: el subcomando va justo después de `env`; sólo `keygen` admite opciones. */
+async function runEnvCommand(argv, cwd, env, fetchImpl) {
+    const sub = argv[1];
+    const resto = (0, args_1.parseArgs)(['env', ...argv.slice(2)]);
+    if (sub !== 'pull' && sub !== 'status' && sub !== 'keygen')
+        return { exitCode: 1, output: `Subcomando de env desconocido: ${sub ?? '(falta)'}. Usa env pull, env status o env keygen.\n\n${HELP}` };
+    if (resto.unknown.length > 0)
+        return { exitCode: 1, output: `Opción desconocida: ${resto.unknown.join(', ')}\n\n${HELP}` };
+    if (sub === 'keygen')
+        return (0, env_1.runEnvKeygen)({ env, cwd }, { central: resto.central, write: resto.write, force: resto.force });
+    if (resto.central !== null || resto.write || resto.force)
+        return { exitCode: 1, output: `Esas opciones son de env keygen.\n\n${HELP}` };
+    return sub === 'pull' ? (0, env_1.runEnvPull)({ env, cwd, fetchImpl }) : (0, env_1.runEnvStatus)({ env, cwd });
+}
 /**
  * El único punto donde se lee `process.cwd()` de verdad: todo lo demás (`runInit`, `runCheck`) recibe
  * el directorio como parámetro explícito, así que las pruebas pueden apuntar a un `mkdtempSync` sin

package/dist/cli/init.js

@@ -69,5 +69,9 @@ const NEXT_STEPS = [
     "       app.useBodyParser('json', { limit: '256kb' });        // sólo con Express: su tope de serie es 100 KB",
     '  4. Seguridad (opcional, apagada por defecto): GROWTICKETS_SECURITY=true y, detrás de un balanceador,',
     '     GROWTICKETS_TRUSTED_PROXY_HOPS (1 = Railway). Marca tus rutas de login con @GrowTicketsLogin({ identifier: \'email\' }).',
-    '  5. Corre: npx growtickets-nest check',
+    '  5. (Opcional) Variables de entorno desde GrowTickets: GROWTICKETS_ENV_KEY (la clave de servidor que da «Conectar un servidor» en la',
+    '     pestaña «Entornos», NUNCA en .env.example) y, en main.ts, ANTES de NestFactory.create:',
+    "       await loadGrowTicketsEnv();                           // import { loadGrowTicketsEnv } from '@growconnect/growtickets-nest'",
+    '     Añade .growtickets/ al .gitignore (la copia local cifrada). Se comprueba con: npx growtickets-nest env status',
+    '  6. Corre: npx growtickets-nest check',
 ].join('\n');

package/dist/client/ingest-client.js

@@ -55,6 +55,10 @@ function raceConnect(promise, ms, controller) {
         });
     });
 }
+/**
+ * `redirect: 'error'`: una redirección se llevaría `X-Api-Key` a otro sitio (undici sólo quita `Authorization` y las cookies al
+ * cambiar de origen). La central nunca redirige `api/ingest`; si alguien lo hace por medio, es un fallo y no un camino.
+ */
 function buildRequestInit(config, init, signal) {
     /*
      * `X-GrowTickets-Proxy` va SIEMPRE: dice qué versión de este paquete habla con la mesa de ayuda
@@ -65,10 +69,11 @@ function buildRequestInit(config, init, signal) {
     const headers = {
         ...init.headers,
         'X-GrowTickets-Proxy': `${sdk_1.SDK_NAME}/${sdk_1.SDK_VERSION}`,
+        'X-GrowTickets-Runtime': (0, sdk_1.runtimeHeader)(),
         'X-Api-Key': config.apiKey.reveal(),
         Accept: 'application/json',
     };
-    const requestInit = { method: init.method, headers, signal };
+    const requestInit = { method: init.method, headers, signal, redirect: 'error' };
     if (init.method === 'POST') {
         headers['Content-Type'] = 'application/json';
         requestInit.body = JSON.stringify(init.data ?? {});

package/dist/env/applier.d.ts

@@ -0,0 +1,83 @@
+import type { EnvOverlay } from './overlay';
+import { type EnvPayload } from './policy';
+import type { EnvSettings } from './settings';
+import type { EnvSnapshot } from './snapshot';
+import type { EnvState } from './state';
+import type { EnvTransport } from './transport';
+/** `applied` (versión nueva puesta), `current` (ya estaba al día), `offline` (la central no contestó y se aplicó la copia), `empty` (el entorno aún no tiene versión vinculada), `failed` o `busy`. */
+export type EnvStatus = 'applied' | 'current' | 'offline' | 'empty' | 'failed' | 'busy';
+/** Lo que cambió al aplicar en caliente. Sólo nombres: ni un valor viaja a quien escucha. */
+export interface EnvChange {
+    version: number;
+    environmentId: number;
+    environmentName: string;
+    changed: string[];
+    removed: string[];
+}
+export interface EnvResult {
+    status: EnvStatus;
+    payload: EnvPayload | null;
+    /** El código corto de por qué falló o por qué se usó la copia (`revoked_key`, `unreachable`…). */
+    reason: string | null;
+    message: string;
+    change: EnvChange | null;
+}
+export interface ApplyOptions {
+    /** `boot`: el arranque del proceso, que siempre pone las variables. `live`: un aviso o la revisión periódica, que obedece a `GROWTICKETS_ENV_ON_CHANGE`. */
+    phase: 'boot' | 'live';
+    /** Preguntar a la central; sin red, sólo la copia local. */
+    network: boolean;
+    /** Esperar a que acabe lo que ya se esté aplicando (arranque y avisos) o rendirse si el candado está tomado (revisión periódica). */
+    wait: boolean;
+    /** Confirmar también cuando ya estaba al día (el arranque y los avisos: alguien está esperando ver el acuse). */
+    ackCurrent: boolean;
+}
+export interface ApplierDeps {
+    settings: () => EnvSettings;
+    transport: Pick<EnvTransport, 'fetch' | 'ack'>;
+    snapshot: EnvSnapshot;
+    state: EnvState;
+    overlay: EnvOverlay;
+    now: () => number;
+    /** `reload`: las variables ya están en `process.env`; quien escucha decide qué recargar. */
+    onReload: (change: EnvChange) => void | Promise<void>;
+    /** `restart`: el cierre ordenado que el gestor de procesos convierte en un arranque con las variables nuevas. */
+    onRestart: () => Promise<void>;
+    warn: (message: string) => void;
+}
+/**
+ * APLICAR una versión: preguntar a la central, validar, guardar la copia, poner las variables y confirmar. Lo usan el arranque
+ * (`loadGrowTicketsEnv`), el aviso de «Vincular» y la revisión de cada minuto. Es el equivalente de `EnvApplier` de growtickets-laravel,
+ * con una diferencia de fondo: allí se reconstruye UNA caché de configuración que comparten todos los procesos; en Node cada proceso tiene
+ * su propio `process.env`, así que cada uno aplica por su cuenta y el candado sólo ordena las aplicaciones DE ESTE proceso.
+ *
+ * ## Orden y garantías
+ *
+ * 1. **Una aplicación a la vez.** Un aviso que llega mientras otra aplica espera su turno (y la revisión periódica se rinde): la segunda
+ *    pregunta con `If-None-Match` y, si nada cambió, no hace nada.
+ * 2. **No se retrocede**: en el MISMO entorno, una versión menor que la aplicada o que la de la copia es `rollback` y se avisa a la central;
+ *    la igual no se vuelve a aplicar. Cambiar de entorno sí puede bajar el número: cada entorno cuenta sus versiones.
+ * 3. **Si la central no contesta**, con `keep` se usa la copia local si no es más vieja que `max_stale_hours`; con `fail`, no se arranca.
+ *    Una clave revocada, vencida o inválida NO cae a la copia: la central dijo que este servidor ya no recibe, y la copia se borra.
+ * 4. **Después de poner las variables se confirma, y sólo entonces se reinicia** (`restart`) o se avisa a quien escucha (`reload`).
+ */
+export declare class EnvApplier {
+    private readonly deps;
+    private applied;
+    private appliedVersion;
+    private appliedEnvironment;
+    private last;
+    private pending;
+    private tail;
+    private closing;
+    constructor(deps: ApplierDeps);
+    /** «entorno:versión» de lo que este proceso tiene puesto, o `null` si nada. */
+    marker(): string | null;
+    apply(options: ApplyOptions): Promise<EnvResult>;
+    private run;
+    private put;
+    private afterLive;
+    private copy;
+    private remember;
+    private floor;
+}

package/dist/env/applier.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvApplier = void 0;
+const errors_1 = require("./errors");
+const policy_1 = require("./policy");
+const KEY_ERRORS = new Set(['invalid_key', 'revoked_key', 'expired_key', 'no_environment']);
+const URL_ERRORS = new Set(['insecure_url', 'invalid_url']);
+/**
+ * APLICAR una versión: preguntar a la central, validar, guardar la copia, poner las variables y confirmar. Lo usan el arranque
+ * (`loadGrowTicketsEnv`), el aviso de «Vincular» y la revisión de cada minuto. Es el equivalente de `EnvApplier` de growtickets-laravel,
+ * con una diferencia de fondo: allí se reconstruye UNA caché de configuración que comparten todos los procesos; en Node cada proceso tiene
+ * su propio `process.env`, así que cada uno aplica por su cuenta y el candado sólo ordena las aplicaciones DE ESTE proceso.
+ *
+ * ## Orden y garantías
+ *
+ * 1. **Una aplicación a la vez.** Un aviso que llega mientras otra aplica espera su turno (y la revisión periódica se rinde): la segunda
+ *    pregunta con `If-None-Match` y, si nada cambió, no hace nada.
+ * 2. **No se retrocede**: en el MISMO entorno, una versión menor que la aplicada o que la de la copia es `rollback` y se avisa a la central;
+ *    la igual no se vuelve a aplicar. Cambiar de entorno sí puede bajar el número: cada entorno cuenta sus versiones.
+ * 3. **Si la central no contesta**, con `keep` se usa la copia local si no es más vieja que `max_stale_hours`; con `fail`, no se arranca.
+ *    Una clave revocada, vencida o inválida NO cae a la copia: la central dijo que este servidor ya no recibe, y la copia se borra.
+ * 4. **Después de poner las variables se confirma, y sólo entonces se reinicia** (`restart`) o se avisa a quien escucha (`reload`).
+ */
+class EnvApplier {
+    constructor(deps) {
+        this.deps = deps;
+        this.applied = null;
+        this.appliedVersion = 0;
+        this.appliedEnvironment = 0;
+        this.last = null;
+        this.pending = 0;
+        this.tail = Promise.resolve();
+        this.closing = false;
+    }
+    /** «entorno:versión» de lo que este proceso tiene puesto, o `null` si nada. */
+    marker() {
+        return this.applied;
+    }
+    async apply(options) {
+        if (this.closing || (this.pending > 0 && !options.wait))
+            return result('busy', null, null, 'Otro proceso de este servidor ya está aplicando.');
+        this.pending++;
+        const turno = this.tail.then(() => this.run(options));
+        this.tail = turno.catch(() => undefined);
+        try {
+            return await turno;
+        }
+        finally {
+            this.pending--;
+        }
+    }
+    async run(options) {
+        if (this.closing)
+            return result('busy', null, null, 'Este proceso se está reiniciando.');
+        const copia = this.copy();
+        const anterior = copia?.payload ?? null;
+        const estado = this.deps.state.read();
+        let offline = null;
+        let payload;
+        try {
+            if (!options.network)
+                throw new errors_1.EnvError('offline', 'Sin preguntar a la central.');
+            const nuevo = await this.deps.transport.fetch(anterior?.etag);
+            if (nuevo === null) {
+                if (anterior === null)
+                    throw new errors_1.EnvError('malformed', 'La central dijo «sin cambios» sin que hubiera copia local.');
+                payload = anterior;
+                this.remember(anterior);
+            }
+            else {
+                const minimo = this.floor(nuevo.environmentId, anterior, estado);
+                if (nuevo.version < minimo) {
+                    await this.deps.transport.ack(nuevo.version, false, 'rollback');
+                    return result('failed', nuevo, 'rollback', `La central dio la versión ${nuevo.version}, anterior a la ${minimo} ya aplicada: no se retrocede.`);
+                }
+                payload = nuevo;
+                this.remember(nuevo);
+            }
+        }
+        catch (error) {
+            const fallo = error instanceof errors_1.EnvError ? error : new errors_1.EnvError('unreachable', 'No se pudo hablar con la central.');
+            if (fallo.reason === 'not_published')
+                return result('empty', null, fallo.reason, fallo.message);
+            if (KEY_ERRORS.has(fallo.reason)) {
+                this.deps.snapshot.forget();
+                this.last = null;
+                return result('failed', null, fallo.reason, fallo.message);
+            }
+            if (URL_ERRORS.has(fallo.reason))
+                return result('failed', null, fallo.reason, fallo.message);
+            const edad = this.deps.snapshot.ageHours(copia);
+            const sirve = anterior !== null && edad !== null && (fallo.reason === 'offline' || (this.deps.settings().onFailure === 'keep' && edad <= this.deps.settings().maxStaleHours));
+            if (!sirve)
+                return result('failed', anterior, fallo.reason, fallo.message);
+            payload = anterior;
+            offline = fallo;
+        }
+        return this.put(payload, offline, options);
+    }
+    async put(payload, offline, options) {
+        const marcador = (0, policy_1.markerOf)(payload);
+        if (this.applied === marcador && options.phase !== 'boot') {
+            if (options.ackCurrent && offline === null)
+                await this.deps.transport.ack(payload.version, true);
+            return result('current', payload, offline?.reason ?? null, offline?.message ?? '');
+        }
+        const reload = options.phase === 'live' && this.deps.settings().onChange === 'reload';
+        const poner = options.phase === 'boot' || reload;
+        let cambio = null;
+        try {
+            cambio = poner ? this.deps.overlay.apply(payload.variables) : null;
+        }
+        catch {
+            await this.deps.transport.ack(payload.version, false, 'apply_failed');
+            return result('failed', payload, 'apply_failed', 'No se pudieron poner las variables en el entorno del proceso.');
+        }
+        this.applied = marcador;
+        this.appliedVersion = payload.version;
+        this.appliedEnvironment = payload.environmentId;
+        this.deps.state.applied(payload);
+        if (payload.discarded.length > 0) {
+            this.deps.warn(`GrowTickets: se descartaron ${payload.discarded.length} variables que no puede poner la central: ${payload.discarded.slice(0, 20).join(', ')}.`);
+        }
+        if (offline === null)
+            await this.deps.transport.ack(payload.version, true);
+        const aplicada = result(offline === null ? 'applied' : 'offline', payload, offline?.reason ?? null, offline?.message ?? '', cambio ? changeOf(payload, cambio) : null);
+        if (options.phase === 'live')
+            await this.afterLive(reload, aplicada);
+        return aplicada;
+    }
+    async afterLive(reload, aplicada) {
+        if (!reload) {
+            this.closing = true;
+            await this.deps.onRestart();
+            return;
+        }
+        try {
+            if (aplicada.change)
+                await this.deps.onReload(aplicada.change);
+        }
+        catch {
+            this.deps.warn('GrowTickets: el oyente de onEnvChange lanzó una excepción; las variables ya están puestas.');
+        }
+    }
+    copy() {
+        return this.deps.snapshot.read() ?? this.last;
+    }
+    remember(payload) {
+        this.last = { payload, fetchedAt: this.deps.now() };
+        this.deps.snapshot.write(payload, this.last.fetchedAt);
+    }
+    floor(environmentId, anterior, estado) {
+        return Math.max(anterior !== null && anterior.environmentId === environmentId ? anterior.version : 0, estado.environment === environmentId ? estado.version : 0, this.appliedEnvironment === environmentId ? this.appliedVersion : 0);
+    }
+}
+exports.EnvApplier = EnvApplier;
+function result(status, payload, reason, message, change = null) {
+    return { status, payload, reason, message, change };
+}
+function changeOf(payload, cambio) {
+    return { version: payload.version, environmentId: payload.environmentId, environmentName: payload.environmentName, changed: cambio.changed, removed: cambio.removed };
+}

package/dist/env/errors.d.ts

@@ -0,0 +1,12 @@
+import { GrowTicketsError } from '../errors/growtickets-error';
+/**
+ * Algo que impidió bajar o aplicar las variables, con un CÓDIGO corto (`reason`: `revoked_key`, `unreachable`, `apply_failed`…) que viaja en
+ * el acuse a la central y un mensaje para quien mira el registro. Ninguno de los dos lleva nunca un valor ni la clave.
+ */
+export declare class EnvError extends GrowTicketsError {
+    readonly reason: string;
+    readonly code = "ENV_ERROR";
+    readonly status = 500;
+    readonly publicMessage = "Las variables de entorno no est\u00E1n disponibles.";
+    constructor(reason: string, message: string);
+}

package/dist/env/errors.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvError = void 0;
+const growtickets_error_1 = require("../errors/growtickets-error");
+/**
+ * Algo que impidió bajar o aplicar las variables, con un CÓDIGO corto (`reason`: `revoked_key`, `unreachable`, `apply_failed`…) que viaja en
+ * el acuse a la central y un mensaje para quien mira el registro. Ninguno de los dos lleva nunca un valor ni la clave.
+ */
+class EnvError extends growtickets_error_1.GrowTicketsError {
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.code = 'ENV_ERROR';
+        this.status = 500;
+        this.publicMessage = 'Las variables de entorno no están disponibles.';
+    }
+}
+exports.EnvError = EnvError;

package/dist/env/load.d.ts

@@ -0,0 +1,35 @@
+import { type EnvChangeListener, type LoadEnvOptions, type LoadEnvResult } from './runtime';
+/**
+ * Trae las variables de entorno de ESTE servidor desde GrowTickets (pestaña «Entornos» del proyecto) y las pone en `process.env`.
+ * Va en `main.ts` ANTES de `NestFactory.create` —y antes de que `ConfigModule` lea nada—:
+ *
+ * ```ts
+ * import { loadGrowTicketsEnv } from '@growconnect/growtickets-nest';
+ *
+ * async function bootstrap() {
+ *   await loadGrowTicketsEnv();
+ *   const app = await NestFactory.create(AppModule);
+ *   app.use(growTicketsMiddleware(app));
+ * }
+ * ```
+ *
+ * ## Precedencia
+ *
+ * entorno de la plataforma < la central < `GROWTICKETS_URL` y `GROWTICKETS_ENV_KEY` del arranque. La central gana sobre lo que pusieron
+ * Docker o Railway y sobre un `.env` que lea el producto después (`dotenv` no pisa lo que ya está en `process.env`), pero nunca puede tocar
+ * nada con el prefijo `GROWTICKETS_`: son con las que el servidor vuelve a preguntar.
+ *
+ * ## Si la central no contesta
+ *
+ * Con `GROWTICKETS_ENV_ON_FAILURE=keep` (de serie) se arranca con la copia local cifrada si no tiene más de
+ * `GROWTICKETS_ENV_MAX_STALE_HOURS` (168); con `fail`, o sin copia que sirva, LANZA y el producto no arranca. Una clave revocada borra la copia.
+ *
+ * Sin `GROWTICKETS_ENV_KEY` no hace nada y devuelve `{ status: 'off' }`: se puede dejar puesta en todos los productos antes de conectar ninguno.
+ */
+export declare function loadGrowTicketsEnv(options?: LoadEnvOptions): Promise<LoadEnvResult>;
+/**
+ * Suscribe un oyente al cambio en caliente (`GROWTICKETS_ENV_ON_CHANGE=reload`): se llama DESPUÉS de poner en `process.env` una versión
+ * nueva, con los NOMBRES que cambiaron o se quitaron —nunca los valores—, para que el producto recargue lo que lee una sola vez (un
+ * pool de conexiones, un cliente de pagos). Devuelve la función que quita el oyente. Con `restart` no se llama nunca: el proceso se va.
+ */
+export declare function onGrowTicketsEnvChange(listener: EnvChangeListener): () => void;

package/dist/env/load.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGrowTicketsEnv = loadGrowTicketsEnv;
+exports.onGrowTicketsEnvChange = onGrowTicketsEnvChange;
+const runtime_1 = require("./runtime");
+/**
+ * Trae las variables de entorno de ESTE servidor desde GrowTickets (pestaña «Entornos» del proyecto) y las pone en `process.env`.
+ * Va en `main.ts` ANTES de `NestFactory.create` —y antes de que `ConfigModule` lea nada—:
+ *
+ * ```ts
+ * import { loadGrowTicketsEnv } from '@growconnect/growtickets-nest';
+ *
+ * async function bootstrap() {
+ *   await loadGrowTicketsEnv();
+ *   const app = await NestFactory.create(AppModule);
+ *   app.use(growTicketsMiddleware(app));
+ * }
+ * ```
+ *
+ * ## Precedencia
+ *
+ * entorno de la plataforma < la central < `GROWTICKETS_URL` y `GROWTICKETS_ENV_KEY` del arranque. La central gana sobre lo que pusieron
+ * Docker o Railway y sobre un `.env` que lea el producto después (`dotenv` no pisa lo que ya está en `process.env`), pero nunca puede tocar
+ * nada con el prefijo `GROWTICKETS_`: son con las que el servidor vuelve a preguntar.
+ *
+ * ## Si la central no contesta
+ *
+ * Con `GROWTICKETS_ENV_ON_FAILURE=keep` (de serie) se arranca con la copia local cifrada si no tiene más de
+ * `GROWTICKETS_ENV_MAX_STALE_HOURS` (168); con `fail`, o sin copia que sirva, LANZA y el producto no arranca. Una clave revocada borra la copia.
+ *
+ * Sin `GROWTICKETS_ENV_KEY` no hace nada y devuelve `{ status: 'off' }`: se puede dejar puesta en todos los productos antes de conectar ninguno.
+ */
+function loadGrowTicketsEnv(options = {}) {
+    return (0, runtime_1.envRuntime)().load(options);
+}
+/**
+ * Suscribe un oyente al cambio en caliente (`GROWTICKETS_ENV_ON_CHANGE=reload`): se llama DESPUÉS de poner en `process.env` una versión
+ * nueva, con los NOMBRES que cambiaron o se quitaron —nunca los valores—, para que el producto recargue lo que lee una sola vez (un
+ * pool de conexiones, un cliente de pagos). Devuelve la función que quita el oyente. Con `restart` no se llama nunca: el proceso se va.
+ */
+function onGrowTicketsEnvChange(listener) {
+    return (0, runtime_1.envRuntime)().onChange(listener);
+}

package/dist/env/overlay.d.ts

@@ -0,0 +1,23 @@
+type Target = Record<string, string | undefined>;
+export interface OverlayChange {
+    /** Los nombres que se pusieron o cambiaron de valor (nunca los valores). */
+    changed: string[];
+    /** Los nombres que la central ya no manda y volvieron a lo que tenían antes. */
+    removed: string[];
+}
+/**
+ * Pone las variables de la central ENCIMA del entorno del proceso y recuerda qué había debajo. La central gana sobre la plataforma
+ * (Docker, Railway) y sobre un `.env` que lea el producto después, porque `dotenv` no pisa lo que ya está en `process.env`.
+ *
+ * Al recibir una versión nueva en caliente (`reload`) lo que la central dejó de mandar NO se queda: vuelve al valor que tenía la
+ * plataforma, o se borra si no tenía ninguno. Sin esto, quitar una variable de la bóveda no la quitaría hasta el siguiente reinicio.
+ */
+export declare class EnvOverlay {
+    private readonly target;
+    private readonly baseline;
+    private readonly current;
+    constructor(target: Target);
+    apply(variables: Record<string, string>): OverlayChange;
+    private restore;
+}
+export {};