create-kontrolia-auth 1.1.2 → 2.0.0

package/README.md

@@ -1,15 +1,51 @@
 # create-kontrolia-auth
 
-Wizard de instalación. Dos preguntas independientes (ver la sección "Desacoplamiento clave" del plan de arquitectura):
+Instalador "todo en uno" de KontrolIA Auth. Pensado para que alguien **sin
+conocimiento técnico** deje el sistema funcionando con un solo comando.
 
-1. **¿De dónde sale tu Supabase?** Proyecto existente (pegas URL/keys, sin Docker) o uno nuevo self-hosted (genera `docker/.env` con secretos reales).
-2. **¿Dónde despliegas `auth-server`/`admin-panel`?** Docker, Vercel, Coolify, Railway u otro — genera los `.env.local` correspondientes.
+## Instalar (desde cero, sin clonar nada a mano)
 
-## Uso
+```bash
+npx create-kontrolia-auth mi-app
+```
+
+Eso hace, en orden:
+
+1. **Revisa requisitos** (Node 20+, pnpm, y git/Docker según lo que elijas) y te
+   dice exactamente qué instalar si falta algo.
+2. **Descarga** el repositorio en `./mi-app` e instala dependencias.
+3. **Base de datos** — dos caminos independientes:
+   - _Ya tengo Supabase_ (Cloud o self-hosted): pegas URL + keys, sin Docker.
+   - _Crear uno nuevo self-hosted_: genera `docker/.env`, **levanta los
+     contenedores por ti** (`docker compose up -d`) y aplica las migraciones
+     en cuanto Postgres está listo.
+4. **Primera aplicación** (opcional): registra tu app y su catálogo de permisos.
+5. **Despliegue**: genera los `.env.local` de `auth-server` y `admin-panel` y te
+   da los pasos exactos para Docker, Vercel, Railway, Render, Coolify o manual.
+
+Si ya estás **dentro del repo** (desarrollo), el instalador lo detecta y se
+salta la descarga:
 
 ```bash
-git clone <tu-fork-de-kontrolia-auth>
-cd kontrolia-auth
-pnpm install
 pnpm --filter create-kontrolia-auth dev
 ```
+
+## Subcomandos
+
+| Comando                               | Qué hace                                                                     |
+| ------------------------------------- | ----------------------------------------------------------------------------- |
+| `npx create-kontrolia-auth [carpeta]` | Instalación completa (el flujo de arriba).                                   |
+| `npx create-kontrolia-auth update`    | Descarga el código nuevo (`git pull`) sobre una copia ya instalada, instala dependencias, y aplica las migraciones nuevas. |
+| `npx create-kontrolia-auth migrate`   | Aplica/re-aplica las migraciones contra una base existente.                  |
+| `npx create-kontrolia-auth doctor`    | Solo revisa que tengas Node, pnpm, git y Docker.                             |
+
+Las migraciones son **idempotentes** (solo tocan el schema `kontrolia_auth`), así
+que `migrate` es seguro de correr las veces que necesites.
+
+`update` es para quien instaló con `npx create-kontrolia-auth mi-app` y ya
+tiene esa carpeta corriendo — no descarta cambios locales (se detiene si hay
+algo sin guardar) y solo avanza si puede hacer fast-forward sobre `origin/main`.
+Si usas los paquetes `@kontrolia/*` como dependencias npm en tu propia
+aplicación (en vez de tener este repo clonado), actualízalos como a cualquier
+otra dependencia (`pnpm update @kontrolia/db` etc.) y vuelve a correr tu
+propio paso de migración — `update` no aplica a ese caso.

package/dist/index.js

@@ -4,34 +4,150 @@ import { migrate } from "@kontrolia/db";
 import { askApplicationStep } from "./steps/application.js";
 import { askDatabaseStep } from "./steps/database.js";
 import { askDeploymentStep } from "./steps/deployment.js";
-async function main() {
-    const repoRoot = process.cwd();
-    console.clear();
-    p.intro("KontrolIA Auth — instalador");
-    const db = await askDatabaseStep(repoRoot);
-    if (db.mode === "new-self-hosted") {
-        p.note("Corre `docker compose -f docker/docker-compose.yml up -d` y espera a que Postgres esté healthy antes de continuar con las migraciones.", "Antes de migrar");
-        const proceed = await p.confirm({ message: "¿Ya levantaste el docker-compose y Postgres está arriba?" });
-        if (p.isCancel(proceed) || !proceed) {
-            p.outro("Cuando esté listo, corre de nuevo: pnpm --filter create-kontrolia-auth dev");
-            return;
-        }
-    }
+import { bringUpAndMigrate } from "./utils/docker.js";
+import { runPreflight } from "./utils/preflight.js";
+import { ensureRepo, isInsideRepo } from "./utils/scaffold.js";
+import { pullLatest } from "./utils/update.js";
+/** Applies the schema against an already-reachable database, with a spinner. */
+async function migrateWithSpinner(connectionString) {
     const s = p.spinner();
-    s.start("Aplicando migraciones del schema kontrolia");
+    s.start("Aplicando migraciones del schema kontrolia_auth");
     try {
-        await migrate({ connectionString: db.databaseUrl });
+        await migrate({ connectionString });
         s.stop("Migraciones aplicadas");
+        return true;
     }
     catch (error) {
         s.stop("Fallaron las migraciones");
         p.log.error(error.message);
+        return false;
+    }
+}
+/** `create-kontrolia-auth migrate` — re-run migrations against any DB later. */
+async function runMigrateCommand() {
+    console.clear();
+    p.intro("KontrolIA Auth — migrar base de datos");
+    const url = await p.text({
+        message: "Connection string de Postgres",
+        placeholder: "postgres://postgres:...@host:5432/postgres",
+    });
+    if (p.isCancel(url) || !url) {
+        p.cancel("Cancelado.");
+        process.exit(0);
+    }
+    const ok = await migrateWithSpinner(url);
+    if (!ok)
+        process.exitCode = 1;
+    p.outro(ok ? "Base de datos al día." : "Revisa la connection string y vuelve a intentar.");
+}
+/** `create-kontrolia-auth doctor` — just the requirements check. */
+async function runDoctor() {
+    console.clear();
+    p.intro("KontrolIA Auth — diagnóstico del entorno");
+    const ok = runPreflight({ git: true, docker: true });
+    p.outro(ok ? "Todo listo para instalar." : "Instala lo marcado con ✗ y vuelve a correr.");
+}
+/**
+ * `create-kontrolia-auth update` — pulls the latest code into an existing
+ * self-hosted clone and re-applies migrations. Only makes sense from inside
+ * a clone (this is not how someone consuming @kontrolia/* as npm
+ * dependencies in their own app updates — for that, bumping the package
+ * versions and re-running the app's own migrate step is the right path).
+ */
+async function runUpdateCommand() {
+    console.clear();
+    p.intro("KontrolIA Auth — actualizar instalación");
+    if (!isInsideRepo(process.cwd())) {
+        p.log.error("Este comando actualiza una copia clonada de KontrolIA Auth — corre esto dentro de la carpeta donde instalaste todo (la que tiene docker/docker-compose.yml).");
+        p.outro("Nada que hacer aquí.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!runPreflight({ git: true })) {
+        p.outro("Instala lo que falta (arriba) y vuelve a correr.");
+        process.exitCode = 1;
+        return;
+    }
+    const updated = await pullLatest(process.cwd());
+    if (!updated) {
         process.exitCode = 1;
         return;
     }
-    await askApplicationStep(db);
+    const url = await p.text({
+        message: "Connection string de Postgres (para aplicar las migraciones nuevas, si hay)",
+        placeholder: "postgres://postgres:...@host:5432/postgres",
+    });
+    if (p.isCancel(url) || !url) {
+        p.outro("Código actualizado. Corre `npx create-kontrolia-auth migrate` cuando quieras aplicar la base de datos.");
+        return;
+    }
+    const migrated = await migrateWithSpinner(url);
+    p.outro(migrated
+        ? "Listo. Si despliegas con Docker: `docker compose -f docker/docker-compose.yml up -d --build`. Si usas Vercel/Railway/Render/Coolify, vuelve a desplegar (push a tu rama, o su CLI) para que tomen el código nuevo."
+        : "El código ya está actualizado, pero revisa el error de las migraciones antes de redesplegar.");
+}
+/** Default flow: preflight → (scaffold if outside repo) → DB → migrate → app → deploy. */
+async function runInstall(targetDirArg) {
+    console.clear();
+    p.intro("KontrolIA Auth — instalador");
+    const inRepo = isInsideRepo(process.cwd());
+    if (!runPreflight({ git: !inRepo })) {
+        p.outro("Instala lo que falta (arriba) y vuelve a correr el instalador.");
+        process.exitCode = 1;
+        return;
+    }
+    const scaffold = await ensureRepo(process.cwd(), targetDirArg);
+    if (!scaffold) {
+        process.exitCode = 1;
+        return;
+    }
+    const { repoRoot, scaffolded, dirName } = scaffold;
+    const db = await askDatabaseStep(repoRoot);
+    let migrated = false;
+    if (db.mode === "new-self-hosted") {
+        const auto = await p.confirm({
+            message: "¿Levanto los contenedores (docker compose up -d) y aplico las migraciones por ti ahora?",
+            initialValue: true,
+        });
+        if (p.isCancel(auto)) {
+            p.cancel("Instalación cancelada.");
+            process.exit(0);
+        }
+        if (auto) {
+            migrated = await bringUpAndMigrate(repoRoot, db.databaseUrl);
+        }
+        else {
+            p.note("Cuando quieras:\n\n  docker compose -f docker/docker-compose.yml up -d\n  npx create-kontrolia-auth migrate", "Lo harás a mano");
+        }
+    }
+    else {
+        migrated = await migrateWithSpinner(db.databaseUrl);
+    }
+    // Registering the first application writes to kontrolia_auth tables, so it
+    // only makes sense once the schema exists. Env generation below is always
+    // useful (it never touches the DB), so it runs either way.
+    if (migrated) {
+        await askApplicationStep(db);
+    }
+    else {
+        p.note("Cuando la base de datos esté lista corre `npx create-kontrolia-auth migrate`, y registra tu primera aplicación desde admin-panel.", "Migraciones pendientes");
+    }
     await askDeploymentStep(repoRoot, db);
-    p.outro("Listo. Crea tu primer usuario/organización desde /register en auth-server, y usa @kontrolia/react en tus apps.");
+    const cdHint = scaffolded && dirName ? `cd ${dirName} && ` : "";
+    p.outro(`Listo. Arranca en local con \`${cdHint}pnpm dev\`, crea tu primer usuario/organización en /register, y usa @kontrolia/react en tus apps.`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const first = args[0];
+    if (first === "migrate")
+        return runMigrateCommand();
+    if (first === "doctor")
+        return runDoctor();
+    if (first === "update")
+        return runUpdateCommand();
+    // `create <dir>` / `install <dir>` / `<dir>` / (nothing) all reach install.
+    const dir = first === "create" || first === "install" ? args[1] : first;
+    return runInstall(dir);
 }
 main().catch((error) => {
     console.error(error);

package/dist/steps/application.d.ts

@@ -1,7 +1,7 @@
 import type { DatabaseAnswer } from "./database.js";
 /**
  * Optional final step: registers a first application and its permission
- * catalog. kontrolia.applications/permissions have no write policy for
+ * catalog. kontrolia_auth.applications/permissions have no write policy for
  * regular users (see migrations/0010_rls_policies.sql) and no admin API
  * exists yet for it, so this writes directly against Postgres — the same
  * platform-admin path migrate() already uses to apply schema changes.

package/dist/steps/application.js

@@ -11,7 +11,7 @@ function slugify(name) {
 }
 /**
  * Optional final step: registers a first application and its permission
- * catalog. kontrolia.applications/permissions have no write policy for
+ * catalog. kontrolia_auth.applications/permissions have no write policy for
  * regular users (see migrations/0010_rls_policies.sql) and no admin API
  * exists yet for it, so this writes directly against Postgres — the same
  * platform-admin path migrate() already uses to apply schema changes.
@@ -26,7 +26,7 @@ export async function askApplicationStep(db) {
         process.exit(0);
     }
     if (!wantsApp) {
-        p.note("Puedes registrar aplicaciones más tarde corriendo este wizard de nuevo, o insertando directamente en kontrolia.applications / kontrolia.permissions.", "Omitido");
+        p.note("Puedes registrar aplicaciones más tarde corriendo este wizard de nuevo, o insertando directamente en kontrolia_auth.applications / kontrolia_auth.permissions.", "Omitido");
         return;
     }
     const name = await textOrExit("Nombre de la aplicación", "Facturación");
@@ -93,7 +93,7 @@ export async function askApplicationStep(db) {
         p.note(`${slug} ya existía — su clave de sincronización (si tiene una) no cambió. Si la perdiste, tendrás que borrar ` +
             "y volver a registrar la aplicación para generar una nueva.", "Aplicación existente");
     }
-    p.note("Para habilitarla en una organización (kontrolia.application_organizations) y asignarla a un rol, hazlo por ahora directo en la base de datos — el admin panel todavía solo permite verla, no darla de alta.", "Siguiente paso");
+    p.note("Para habilitarla en una organización, entra a admin-panel → \"Aplicaciones\" — cualquier owner/admin puede activarla ahí con un clic.", "Siguiente paso");
 }
 async function textOrExit(message, placeholder) {
     const value = await p.text({ message, placeholder });

package/dist/steps/database.js

@@ -31,7 +31,7 @@ export async function askDatabaseStep(repoRoot) {
         const anonKey = await textOrExit("Anon/public key");
         const serviceRoleKey = await textOrExit("Service role key (server-only, nunca la expongas al navegador)");
         const databaseUrl = await textOrExit("Connection string de Postgres", "postgres://postgres:...@db.tu-proyecto.supabase.co:5432/postgres");
-        p.note("Si tu proyecto es Supabase Cloud, activa el Custom Access Token Hook manualmente en Dashboard → Authentication → Hooks → selecciona kontrolia.custom_access_token_hook. No se puede automatizar por API.", "Paso manual pendiente");
+        p.note("Si tu proyecto es Supabase Cloud, activa el Custom Access Token Hook manualmente en Dashboard → Authentication → Hooks → selecciona kontrolia_auth.custom_access_token_hook. No se puede automatizar por API.", "Paso manual pendiente");
         return { mode, databaseUrl, supabaseUrl, anonKey, serviceRoleKey };
     }
     const jwtSecret = generateJwtSecret();

package/dist/steps/deployment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/steps/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAYpD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAiI3F"}
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/steps/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA6BpD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkI3F"}

package/dist/steps/deployment.js

@@ -2,10 +2,21 @@ import * as p from "@clack/prompts";
 import { updateEnvValue, writeEnvFile } from "../utils/files.js";
 import { registerOAuthClient } from "../utils/oauth-client.js";
 const NEXT_STEPS = {
-    docker: "Se despliegan como parte del mismo docker/docker-compose.yml (servicios auth-server y admin-panel).",
-    vercel: "vercel deploy en apps/auth-server y apps/admin-panel por separado, configurando las mismas variables en el dashboard de Vercel.",
-    coolify: "Crea dos recursos 'Next.js App' en Coolify apuntando a apps/auth-server y apps/admin-panel, con las variables de .env.local generadas.",
-    railway: "railway up en apps/auth-server y apps/admin-panel, o conéctalos como servicios desde el repo en el dashboard de Railway.",
+    docker: "Ya está: los servicios auth-server y admin-panel viven en el mismo docker/docker-compose.yml. Corre `docker compose -f docker/docker-compose.yml up -d` para tenerlos arriba.",
+    vercel: "1) Instala la CLI: npm i -g vercel\n" +
+        "2) En apps/auth-server corre `vercel` y sigue el asistente (crea 1 proyecto).\n" +
+        "3) En apps/admin-panel corre `vercel` (crea otro proyecto).\n" +
+        "4) En cada proyecto → Settings → Environment Variables, pega las variables de su .env.local (las acabo de generar).\n" +
+        "5) `vercel --prod` en cada carpeta para publicar.",
+    railway: "1) Instala la CLI: npm i -g @railway/cli && railway login\n" +
+        "2) En apps/auth-server: `railway init` y luego `railway up`.\n" +
+        "3) Repite en apps/admin-panel.\n" +
+        "4) En cada servicio (dashboard de Railway → Variables) pega su .env.local.",
+    render: "1) Sube el repo a GitHub.\n" +
+        "2) En Render → New → Web Service, apúntalo a apps/auth-server (Build: `pnpm install && pnpm build`, Start: `pnpm start`).\n" +
+        "3) Repite para apps/admin-panel.\n" +
+        "4) En cada servicio → Environment, pega su .env.local.",
+    coolify: "Crea dos recursos 'Next.js App' en Coolify apuntando a apps/auth-server y apps/admin-panel, y pega en cada uno las variables de su .env.local.",
     manual: "Corre `pnpm build && pnpm start` en apps/auth-server y apps/admin-panel en el servidor/K8s de tu elección, usando los .env.local generados.",
 };
 /**
@@ -19,8 +30,9 @@ export async function askDeploymentStep(repoRoot, db) {
         options: [
             { value: "docker", label: "Docker (incluido en el mismo docker-compose)" },
             { value: "vercel", label: "Vercel" },
-            { value: "coolify", label: "Coolify" },
             { value: "railway", label: "Railway" },
+            { value: "render", label: "Render" },
+            { value: "coolify", label: "Coolify" },
             { value: "manual", label: "Otro / Kubernetes / manual" },
         ],
     });

package/dist/utils/docker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Self-hosted happy path: brings the docker-compose stack up in the
+ * background, then keeps retrying the migrations while Postgres finishes
+ * booting (a fresh container isn't ready to accept connections the instant
+ * `up -d` returns). Returns true once the schema is applied.
+ */
+export declare function bringUpAndMigrate(repoRoot: string, databaseUrl: string): Promise<boolean>;
+//# sourceMappingURL=docker.d.ts.map

package/dist/utils/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/utils/docker.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsC/F"}

package/dist/utils/docker.js

@@ -0,0 +1,47 @@
+import * as p from "@clack/prompts";
+import { migrate } from "@kontrolia/db";
+import { commandExists, run } from "./exec.js";
+const COMPOSE_FILE = "docker/docker-compose.yml";
+/**
+ * Self-hosted happy path: brings the docker-compose stack up in the
+ * background, then keeps retrying the migrations while Postgres finishes
+ * booting (a fresh container isn't ready to accept connections the instant
+ * `up -d` returns). Returns true once the schema is applied.
+ */
+export async function bringUpAndMigrate(repoRoot, databaseUrl) {
+    if (!commandExists("docker")) {
+        p.log.error("Docker no está instalado o no está corriendo. Abre Docker Desktop y vuelve a intentar.");
+        return false;
+    }
+    const up = p.spinner();
+    up.start("Levantando Postgres + GoTrue con docker compose");
+    try {
+        await run("docker", ["compose", "-f", COMPOSE_FILE, "up", "-d"], { cwd: repoRoot });
+        up.stop("Contenedores arriba");
+    }
+    catch (error) {
+        up.stop("No se pudo levantar docker compose");
+        p.log.error(error.message);
+        p.log.info("¿Docker Desktop está abierto? Ábrelo y vuelve a correr el instalador.");
+        return false;
+    }
+    const mig = p.spinner();
+    mig.start("Esperando a que Postgres acepte conexiones y aplicando migraciones");
+    let lastError = null;
+    for (let attempt = 1; attempt <= 30; attempt++) {
+        try {
+            await migrate({ connectionString: databaseUrl });
+            mig.stop("Migraciones aplicadas");
+            return true;
+        }
+        catch (error) {
+            lastError = error;
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+    }
+    mig.stop("Postgres no respondió a tiempo (60s)");
+    if (lastError)
+        p.log.error(lastError.message);
+    p.note("Los contenedores quedaron arriba. Cuando Postgres termine de iniciar corre:\n\n  npx create-kontrolia-auth migrate", "Reintenta las migraciones");
+    return false;
+}

package/dist/utils/exec.d.ts

@@ -0,0 +1,16 @@
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Runs a command to completion, buffering its output. Rejects with the
+ * captured stderr/stdout on a non-zero exit. Uses a shell so Windows can
+ * resolve the `.cmd` shims for pnpm/docker/git; args with spaces are quoted
+ * so a target directory like `mi carpeta` survives that round-trip.
+ */
+export declare function run(command: string, args: string[], options?: RunOptions): Promise<string>;
+/** True if a command resolves on PATH. */
+export declare function commandExists(command: string): boolean;
+/** Best-effort first line of `command --version`, or null if it isn't installed. */
+export declare function tryVersion(command: string, arg?: string): string | null;
+//# sourceMappingURL=exec.d.ts.map

package/dist/utils/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB9F;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQtD;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAc,GAAG,MAAM,GAAG,IAAI,CAO5E"}

package/dist/utils/exec.js

@@ -0,0 +1,49 @@
+import { execSync, spawn } from "node:child_process";
+/**
+ * Runs a command to completion, buffering its output. Rejects with the
+ * captured stderr/stdout on a non-zero exit. Uses a shell so Windows can
+ * resolve the `.cmd` shims for pnpm/docker/git; args with spaces are quoted
+ * so a target directory like `mi carpeta` survives that round-trip.
+ */
+export function run(command, args, options = {}) {
+    const quoted = args.map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" ");
+    return new Promise((resolve, reject) => {
+        const child = spawn(`${command} ${quoted}`.trim(), {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            shell: true,
+        });
+        let out = "";
+        let err = "";
+        child.stdout?.on("data", (d) => (out += d.toString()));
+        child.stderr?.on("data", (d) => (err += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(err.trim() || out.trim() || `${command} terminó con código ${code}`));
+        });
+    });
+}
+/** True if a command resolves on PATH. */
+export function commandExists(command) {
+    try {
+        const probe = process.platform === "win32" ? "where" : "command -v";
+        execSync(`${probe} ${command}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Best-effort first line of `command --version`, or null if it isn't installed. */
+export function tryVersion(command, arg = "--version") {
+    try {
+        const output = execSync(`${command} ${arg}`, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+        return (output.trim().split("\n")[0] ?? "").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/preflight.d.ts

@@ -0,0 +1,14 @@
+export interface PreflightNeeds {
+    /** Needs git to clone the repo (turnkey install from outside the repo). */
+    git?: boolean;
+    /** Needs Docker for the self-hosted path. */
+    docker?: boolean;
+}
+/**
+ * Friendly, non-technical requirements check. Prints a ✓/✗ table and, for
+ * anything missing, exactly how to install it. Returns false if a required
+ * tool is missing so the caller can stop before confusing the user with a
+ * deep stack trace.
+ */
+export declare function runPreflight(needs?: PreflightNeeds): boolean;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/utils/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/utils/preflight.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AASD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,cAAmB,GAAG,OAAO,CA8ChE"}

package/dist/utils/preflight.js

@@ -0,0 +1,49 @@
+import * as p from "@clack/prompts";
+import { tryVersion } from "./exec.js";
+/**
+ * Friendly, non-technical requirements check. Prints a ✓/✗ table and, for
+ * anything missing, exactly how to install it. Returns false if a required
+ * tool is missing so the caller can stop before confusing the user with a
+ * deep stack trace.
+ */
+export function runPreflight(needs = {}) {
+    const checks = [];
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    checks.push({
+        label: "Node.js",
+        ok: nodeMajor >= 20,
+        detail: `v${process.versions.node}`,
+        hint: "Instala Node 20 o superior desde https://nodejs.org (elige la versión LTS).",
+    });
+    const pnpm = tryVersion("pnpm");
+    checks.push({
+        label: "pnpm",
+        ok: Boolean(pnpm),
+        detail: pnpm ?? "no encontrado",
+        hint: "Instálalo con:  npm install -g pnpm",
+    });
+    if (needs.git) {
+        const git = tryVersion("git");
+        checks.push({
+            label: "git",
+            ok: Boolean(git),
+            detail: git ?? "no encontrado",
+            hint: "Instala Git desde https://git-scm.com/downloads",
+        });
+    }
+    if (needs.docker) {
+        const docker = tryVersion("docker");
+        checks.push({
+            label: "Docker",
+            ok: Boolean(docker),
+            detail: docker ?? "no encontrado",
+            hint: "Instala Docker Desktop desde https://www.docker.com/products/docker-desktop y ábrelo antes de continuar.",
+        });
+    }
+    const table = checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.label.padEnd(9)} ${c.detail}`).join("\n");
+    p.note(table, "Requisitos");
+    const missing = checks.filter((c) => !c.ok);
+    for (const m of missing)
+        p.log.error(`Falta ${m.label}. ${m.hint}`);
+    return missing.length === 0;
+}

package/dist/utils/scaffold.d.ts

@@ -0,0 +1,21 @@
+/** Heuristic: are we already standing inside a checkout of the monorepo? */
+export declare function isInsideRepo(dir: string): boolean;
+export interface ScaffoldResult {
+    repoRoot: string;
+    /** true when we cloned a fresh copy (vs. running inside an existing one). */
+    scaffolded: boolean;
+    /** the folder name we cloned into, for the closing "cd" hint. */
+    dirName?: string;
+}
+/**
+ * Turnkey entrypoint: guarantees there's a working copy of KontrolIA Auth to
+ * configure. Run from inside the repo (dev, or an already-cloned copy) it's a
+ * no-op. Run from anywhere else (`npx create-kontrolia-auth mi-app`) it does a
+ * shallow clone into the target folder and installs dependencies, so a
+ * non-technical user never has to know what git or pnpm are.
+ *
+ * Returns null on any failure the user needs to fix (folder exists, clone or
+ * install failed) — the caller stops with a friendly message.
+ */
+export declare function ensureRepo(cwd: string, targetDirArg?: string): Promise<ScaffoldResult | null>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/utils/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/utils/scaffold.ts"],"names":[],"mappings":"AAOA,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA+CnG"}

package/dist/utils/scaffold.js

@@ -0,0 +1,65 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import { run } from "./exec.js";
+const REPO_URL = "https://github.com/rauldolores/auth.git";
+/** Heuristic: are we already standing inside a checkout of the monorepo? */
+export function isInsideRepo(dir) {
+    return existsSync(join(dir, "docker", "docker-compose.yml")) && existsSync(join(dir, "packages", "cli"));
+}
+/**
+ * Turnkey entrypoint: guarantees there's a working copy of KontrolIA Auth to
+ * configure. Run from inside the repo (dev, or an already-cloned copy) it's a
+ * no-op. Run from anywhere else (`npx create-kontrolia-auth mi-app`) it does a
+ * shallow clone into the target folder and installs dependencies, so a
+ * non-technical user never has to know what git or pnpm are.
+ *
+ * Returns null on any failure the user needs to fix (folder exists, clone or
+ * install failed) — the caller stops with a friendly message.
+ */
+export async function ensureRepo(cwd, targetDirArg) {
+    if (isInsideRepo(cwd))
+        return { repoRoot: cwd, scaffolded: false };
+    let dir = targetDirArg;
+    if (!dir) {
+        const answer = await p.text({
+            message: "¿En qué carpeta quieres instalar KontrolIA Auth?",
+            placeholder: "kontrolia-auth",
+            defaultValue: "kontrolia-auth",
+        });
+        if (p.isCancel(answer)) {
+            p.cancel("Instalación cancelada.");
+            process.exit(0);
+        }
+        dir = answer || "kontrolia-auth";
+    }
+    const target = join(cwd, dir);
+    if (existsSync(target)) {
+        p.log.error(`La carpeta "${dir}" ya existe. Elige otro nombre, o bórrala y vuelve a intentar.`);
+        return null;
+    }
+    const clone = p.spinner();
+    clone.start(`Descargando KontrolIA Auth en ./${dir}`);
+    try {
+        await run("git", ["clone", "--depth", "1", REPO_URL, target]);
+        clone.stop(`Código descargado en ./${dir}`);
+    }
+    catch (error) {
+        clone.stop("No se pudo descargar el repositorio");
+        p.log.error(error.message);
+        return null;
+    }
+    const install = p.spinner();
+    install.start("Instalando dependencias (pnpm install) — puede tardar un par de minutos");
+    try {
+        await run("pnpm", ["install"], { cwd: target });
+        install.stop("Dependencias instaladas");
+    }
+    catch (error) {
+        install.stop("Falló pnpm install");
+        p.log.error(error.message);
+        p.note(`Entra a la carpeta y corre pnpm install a mano:\n\n  cd ${dir}\n  pnpm install`, "Puedes reintentar");
+        return null;
+    }
+    return { repoRoot: target, scaffolded: true, dirName: dir };
+}

package/dist/utils/update.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pulls the latest KontrolIA Auth code into an existing self-hosted clone.
+ * Deliberately conservative: refuses to touch a working tree with local
+ * changes (never discards anything), and only fast-forwards — if history
+ * has diverged (a local commit, a force-push upstream), it stops and tells
+ * the operator to sort it out with git directly instead of guessing.
+ *
+ * Returns true if the working tree ends up on the latest commit (whether or
+ * not it actually moved), false if it stopped short of that for any reason.
+ */
+export declare function pullLatest(repoRoot: string): Promise<boolean>;
+//# sourceMappingURL=update.d.ts.map

package/dist/utils/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/utils/update.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgEnE"}

package/dist/utils/update.js

@@ -0,0 +1,67 @@
+import * as p from "@clack/prompts";
+import { run } from "./exec.js";
+/**
+ * Pulls the latest KontrolIA Auth code into an existing self-hosted clone.
+ * Deliberately conservative: refuses to touch a working tree with local
+ * changes (never discards anything), and only fast-forwards — if history
+ * has diverged (a local commit, a force-push upstream), it stops and tells
+ * the operator to sort it out with git directly instead of guessing.
+ *
+ * Returns true if the working tree ends up on the latest commit (whether or
+ * not it actually moved), false if it stopped short of that for any reason.
+ */
+export async function pullLatest(repoRoot) {
+    const dirty = (await run("git", ["status", "--porcelain"], { cwd: repoRoot })).trim();
+    if (dirty) {
+        p.log.error("Hay cambios sin guardar en esta copia — no los voy a tocar. Guárdalos (git commit / git stash) y vuelve a correr `npx create-kontrolia-auth update`.");
+        return false;
+    }
+    const fetch = p.spinner();
+    fetch.start("Buscando actualizaciones");
+    try {
+        await run("git", ["fetch", "origin"], { cwd: repoRoot });
+    }
+    catch (error) {
+        fetch.stop("No se pudo conectar a GitHub");
+        p.log.error(error.message);
+        return false;
+    }
+    const behindRaw = await run("git", ["rev-list", "--count", "HEAD..origin/main"], { cwd: repoRoot });
+    const behind = Number(behindRaw.trim());
+    if (behind === 0) {
+        fetch.stop("Ya tienes la última versión");
+        return true;
+    }
+    fetch.stop(`${behind} cambio${behind === 1 ? "" : "s"} nuevo${behind === 1 ? "" : "s"} disponible${behind === 1 ? "" : "s"}`);
+    const log = await run("git", ["log", "--oneline", "HEAD..origin/main"], { cwd: repoRoot });
+    p.note(log.trim(), "Qué se va a aplicar");
+    const proceed = await p.confirm({ message: "¿Descargar y aplicar estos cambios ahora?", initialValue: true });
+    if (p.isCancel(proceed) || !proceed) {
+        p.cancel("Actualización cancelada.");
+        return false;
+    }
+    const pull = p.spinner();
+    pull.start("Descargando el código nuevo");
+    try {
+        await run("git", ["pull", "--ff-only", "origin", "main"], { cwd: repoRoot });
+        pull.stop("Código actualizado");
+    }
+    catch (error) {
+        pull.stop("No se pudo actualizar automáticamente");
+        p.log.error(error.message);
+        p.note("El historial local y el de GitHub ya no coinciden (por ejemplo, si hiciste un commit propio). Resuélvelo a mano con git, o clona de nuevo en una carpeta aparte.", "Requiere intervención manual");
+        return false;
+    }
+    const install = p.spinner();
+    install.start("Instalando dependencias nuevas (pnpm install)");
+    try {
+        await run("pnpm", ["install"], { cwd: repoRoot });
+        install.stop("Dependencias al día");
+    }
+    catch (error) {
+        install.stop("Falló pnpm install");
+        p.log.error(error.message);
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "create-kontrolia-auth",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "license": "MIT",
-  "description": "Installer wizard for KontrolIA Auth. Two independent questions: (1) connect to an existing Supabase project or create a new self-hosted one via Docker; (2) where to deploy auth-server/admin-panel (Docker, Vercel, Coolify, Railway).",
+  "description": "Turnkey installer for KontrolIA Auth. `npx create-kontrolia-auth mi-app` checks requirements, downloads the repo, installs deps, and runs a wizard: (1) connect to an existing Supabase project or create a new self-hosted one via Docker; (2) where to deploy auth-server/admin-panel (Docker, Vercel, Railway, Render, Coolify). Also exposes `update`, `migrate` and `doctor` subcommands.",
   "keywords": [
     "kontrolia",
     "auth",
@@ -23,6 +23,9 @@
     "access": "public"
   },
   "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "bin": {
     "create-kontrolia-auth": "./dist/index.js"
   },
@@ -32,7 +35,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "jose": "^5.9.6",
-    "@kontrolia/db": "1.2.0"
+    "@kontrolia/db": "2.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",