talo-hub 0.1.3 → 0.1.5

package/README.md

@@ -32,7 +32,7 @@ claude mcp add --transport http talo https://talopartnerhub.vercel.app/api/mcp
 
 ```bash
 npx talo-hub mcp --client cursor     # o --client desktop; --with-key para usar tu key
-npx talo-hub skills install          # skills de Talo en .claude/skills
+npx talo-hub skills install          # skills de Talo + el kit de tu stack, en .claude/skills
 ```
 
 El agente puede crear cobros, simular transferencias, registrar y probar su webhook, correr el checklist de producción (`check_go_live`) y leer la documentación (`read_docs`).
@@ -41,11 +41,11 @@ El agente puede crear cobros, simular transferencias, registrar y probar su webh
 
 - Purpose: accept ARS bank-transfer payments in Argentina on the user's Talo Pay account. Each payment returns a `cvu` and `alias`; status goes `PENDING` → `SUCCESS` (or `UNDERPAID` / `OVERPAID` / `EXPIRED`).
 - Connect: MCP at `https://talopartnerhub.vercel.app/api/mcp` (OAuth), or this CLI after the user runs `npx talo-hub login`. A person must authorize Talo once per environment; everything else you can do.
-- Keys: `tph_test_…` sandbox (test money: test freely), `tph_live_…` production (real money: confirm refunds and amount changes with the user). Scopes `read` < `charge` < `full`; give servers `charge`. Store project keys in the server's env (`TALO_HUB_API_KEY`), never in code or chat; exporting it in your own shell replaces the login key. `login --production` does not make production the default: pass `--production` or run `use production`.
+- Keys: `tph_test_…` sandbox (test money: test freely), `tph_live_…` production (real money: confirm refunds and amount changes with the user). Scopes `read` < `charge` < `full`; give servers `charge`. Store project keys in the server's env (`TALO_HUB_API_KEY`), never in code or chat: `keys create --env-file .env.local` or `--vercel production|preview[:<branch>]` writes it there without printing it (same flags on `webhooks add` for `TALO_HUB_WEBHOOK_SECRET`); exporting it in your own shell replaces the login key. `login --production` does not make production the default: pass `--production` or run `use production`.
 - Machine-readable: every command takes `--json` (JSON on stdout, human messages on stderr) and exits non-zero on failure, `doctor` and `webhooks test` included. Errors with `--json`: `{"error":{"code","message","status"}}`, with stable codes such as `not_logged_in`, `invalid_amount`, `invalid_hub`, `env_key_mismatch`, `insufficient_scope` (plus `key_scope` and `required_scope`), `talo_reconnect_required`, `network_error`, `invalid_response`. `status` is the hub's HTTP status, or null when the CLI found the error itself or couldn't reach the hub. `events listen --json` prints one event per line; the last few existing events come first with `"replayed": true`. Docs as Markdown: https://talopartnerhub.vercel.app/llms.txt, `/docs/<page>.md`, OpenAPI at `/openapi.json`.
 - Amounts: pass `--amount 15000` or `15000.50`. Don't use thousands separators unquoted: PowerShell turns `15.000,50` into `15,50`.
 - Payments always include `paid` and `refunded` as numbers (0 when none) and `refunds: [{ id, status, type, amount, currency, created_at }]`. Filter events with `events list --payment <id>`.
-- Test plan: `payments create --amount 15000` → `sandbox pay <id> --amount 14999` (UNDERPAID, don't fulfil) → `sandbox pay <id> --amount 1` (SUCCESS) → `webhooks add <https url>` → `webhooks test <id>` → `doctor` until it exits 0.
+- Test plan: `payments create --amount 15000` → `sandbox pay <id> --amount 14999` (UNDERPAID, don't fulfil) → `sandbox pay <id> --amount 1` (SUCCESS) → `webhooks add <https url>` (it first probes the URL and refuses redirects, Vercel Deployment Protection or a handler that accepts unsigned events; `--skip-check` to skip) → `webhooks test <id>` (on failure `reason` says why: `redirect`, `vercel_protection`, `timeout`, `network`, `http_error`) → `doctor` until it exits 0. Best practices per stack: `skills install` (it detects the stack).
 
 ## Comandos
 
@@ -62,10 +62,13 @@ El agente puede crear cobros, simular transferencias, registrar y probar su webh
 | `balance`, `transactions [--from] [--to] [--limit <n>] [--cursor]` | Saldo y movimientos |
 | `events list [--payment <id>] [--type <tipo>] [--after <id>] [--limit <n>]` | Eventos recientes, filtrables por cobro o tipo |
 | `events listen [--forward-to <url\|puerto>]` | Recibe eventos en vivo y los reenvía a localhost sin túneles (sin firma, con `talo-hub-forwarded: 1`: solo para desarrollo) |
-| `webhooks list \| add <url> \| remove <id> \| test <id>` | Webhooks firmados con HMAC-SHA256 |
+| `webhooks list \| add <url> \| remove <id> \| test <id>` | Webhooks firmados con HMAC-SHA256. `add` prueba antes la URL (redirecciones, Deployment Protection de Vercel) |
+| `webhooks add <url> --vercel <production\|preview[:rama]>` / `--env-file <archivo>` | Guarda el secreto como `TALO_HUB_WEBHOOK_SECRET` en Vercel o en tu .env, sin mostrarlo |
 | `keys list \| create [--name] [--scope read\|charge\|full] \| revoke <id>` | Keys para tus proyectos (`charge` por defecto) |
+| `keys create … --vercel <production\|preview[:rama]>` / `--env-file <archivo>` | Guarda la key como `TALO_HUB_API_KEY` en Vercel (tipo Secret) o en tu .env, sin mostrarla |
 | `mcp [--client claude\|cursor\|desktop] [--with-key]` | Configuración del MCP para tu agente |
-| `skills install [--global]` | Instala las skills de Talo |
+| `skills install [--stack <kit>] [--global]` | Instala las skills de Talo y el kit de mejores prácticas de tu stack (Next.js + Vercel, Node, Python, Laravel, edge) |
+| `skills list` | Kits por stack y cuál corresponde a tu proyecto |
 | `use <sandbox\|production>` | Entorno activo de los próximos comandos |
 | `logout [--production \| --all]` | Revoca la key en el hub y la borra de esta máquina |
 
@@ -78,8 +81,8 @@ Montos: `15000` o `15000.50`. También entiende `15000,50` y `15.000,50`, pero e
 ```bash
 npx talo-hub doctor                                         # sandbox listo
 npx talo-hub login --production
-npx talo-hub keys create --production --name mi-tienda --scope charge
-npx talo-hub webhooks add https://tu-sitio.com/api/webhooks/talo --production
+npx talo-hub keys create --production --name mi-tienda --scope charge --vercel production   # o --env-file .env
+npx talo-hub webhooks add https://tu-sitio.com/api/webhooks/talo --production --vercel production
 npx talo-hub webhooks test <id> --production
 npx talo-hub doctor --production
 ```

package/dist/cli.js

@@ -12,6 +12,9 @@ import { parseArgs } from "node:util";
 import { configPath, environmentOfKey, loadConfig, requestedHub, resolveKey, saveConfig, DEFAULT_HUB, } from "./config.js";
 import { Hub, HubRequestError, networkReason } from "./hub.js";
 import { parseAmount, parseCount, parseDate, parseForwardUrl } from "./parse.js";
+import { probeWebhookUrl } from "./probe.js";
+import { addToVercel, describeTarget, gitIgnores, parseVercelTarget, writeEnvFile } from "./secrets.js";
+import { detectStacks, pickStacks, readSkillsIndex } from "./stacks.js";
 const VERSION = createRequire(import.meta.url)("../package.json").version;
 /** How to tell people to run us again: through npx when that's how they ran us. */
 const CMD = process.env.npm_command === "exec" ? "npx talo-hub" : "talo-hub";
@@ -40,11 +43,17 @@ Eventos y webhooks
   events listen [--forward-to <url|puerto>]      Muestra los últimos y escucha los nuevos
                                                  (los reenviados no van firmados: solo para desarrollo)
   webhooks list | add <url> | remove <id> | test <id>
+  webhooks add <url> [--vercel <entorno>] [--env-file <archivo>] [--skip-check]
+                                                 Antes de registrar prueba la URL (redirecciones, Vercel)
 
 Keys y agentes
   keys list | create [--name <nombre>] [--scope read|charge|full] | revoke <id>   (charge por defecto)
+  keys create … --vercel <production|preview[:rama]> | --env-file <archivo>
+                                                 Guarda la key en Vercel o en tu .env sin mostrarla
   mcp [--client claude|cursor|desktop] [--with-key]   Configuración del MCP para tu agente
-  skills install [--global]                           Instala las skills de Talo en .claude/skills
+  skills install [--stack <kit>] [--global]          Instala las skills de Talo en .claude/skills, con el kit
+                                                      de tu stack (lo detecta; --stack all, --stack none)
+  skills list                                         Kits por stack y cuál corresponde a este proyecto
 
 Montos: 15000 o 15000.50 (en PowerShell, con separador de miles, entre comillas: "15.000,50").
 Fechas: AAAA-MM-DD o ISO 8601; sin zona horaria, hora de Argentina.
@@ -99,6 +108,10 @@ function parseCommandLine() {
                 client: { type: "string" },
                 "with-key": { type: "boolean" },
                 global: { type: "boolean" },
+                stack: { type: "string" },
+                vercel: { type: "string" },
+                "env-file": { type: "string" },
+                "skip-check": { type: "boolean" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
             },
@@ -135,9 +148,12 @@ const COMMAND_OPTIONS = {
     "events list": ["after", "limit", "payment", "type"],
     "events listen": ["forward-to"],
     webhooks: [],
+    "webhooks add": ["vercel", "env-file", "skip-check"],
     keys: ["name", "scope"],
+    "keys create": ["name", "scope", "vercel", "env-file"],
     mcp: ["client", "with-key"],
-    skills: ["global"],
+    "skills install": ["global", "stack"],
+    "skills list": [],
 };
 function checkOptions(command, sub) {
     const key = COMMAND_OPTIONS[`${command} ${sub ?? "list"}`] ? `${command} ${sub ?? "list"}` : command;
@@ -229,6 +245,7 @@ const HUB_MESSAGES = {
     invalid_url: "La URL del webhook no es válida: tiene que ser https.",
     environment_disabled: "El hub todavía no está conectado a ese entorno de Talo.",
     talo_partner_unsupported: "Talo todavía no habilita el saldo y los movimientos para integraciones de partner: consultalos en el panel de Talo.",
+    talo_unavailable: "Talo no respondió bien o a tiempo. Puede que lo haya hecho igual: revisá el cobro (payments get) antes de reintentar.",
 };
 /** A hub error in words for this CLI: transient failures read the same whatever the hub said. */
 function hubMessage(error) {
@@ -423,16 +440,47 @@ async function listen(hub) {
         await sleep(2000);
     }
 }
-const SKILLS = ["talo-payments", "talo-go-live", "talo-operations"];
-/** Downloads the skills into ./.claude/skills (or ~/.claude/skills with --global). */
+/** The hub's list of skills: the core ones, and the stack kits with how to recognize each stack. */
+async function fetchSkillsIndex(hubUrl) {
+    let status = 0;
+    let body;
+    try {
+        const response = await fetch(`${hubUrl}/skills/index.json`, { signal: AbortSignal.timeout(30_000) });
+        status = response.status;
+        if (response.ok)
+            body = await response.json().catch(() => undefined);
+    }
+    catch (error) {
+        fail(`No pudimos conectar con ${hubUrl} (${networkReason(error)}).`, "network_error");
+    }
+    const skills = readSkillsIndex(body);
+    if (!skills?.length)
+        fail(`No pudimos leer la lista de skills del hub (HTTP ${status}).`, "download_failed");
+    return skills;
+}
+const kitIds = (kits) => kits.map((kit) => kit.stack).join(", ");
+/**
+ * Downloads the core skills and the stack kits into ./.claude/skills (or ~/.claude/skills with
+ * --global): the kits that match this project, the ones --stack names, or all of them for --global.
+ */
 async function installSkills(hubUrl) {
+    const index = await fetchSkillsIndex(hubUrl);
+    const kits = index.filter((skill) => skill.kind === "stack");
+    const detected = flags.global ? [] : await detectStacks(process.cwd(), kits);
+    let chosen = flags.global ? kits : detected;
+    if (flags.stack !== undefined) {
+        const picked = pickStacks(kits, flags.stack);
+        if (picked.unknown.length)
+            fail(`No hay kit para ${picked.unknown.join(", ")}. Kits: ${kitIds(kits)} (o all, none).`, "unknown_stack");
+        chosen = picked.kits;
+    }
     const root = join(flags.global ? homedir() : process.cwd(), ".claude", "skills");
     const installed = [];
-    for (const skill of SKILLS) {
+    for (const skill of [...index.filter((entry) => entry.kind === "core"), ...chosen]) {
         let text = "";
         let status = 0;
         try {
-            const response = await fetch(`${hubUrl}/skills/${skill}/SKILL.md`, { signal: AbortSignal.timeout(30_000) });
+            const response = await fetch(`${hubUrl}/skills/${skill.slug}/SKILL.md`, { signal: AbortSignal.timeout(30_000) });
             status = response.status;
             if (response.ok)
                 text = await response.text();
@@ -440,15 +488,75 @@ async function installSkills(hubUrl) {
         catch (error) {
             fail(`No pudimos conectar con ${hubUrl} (${networkReason(error)}).`, "network_error");
         }
-        if (!text.startsWith("---") || !text.includes(`name: ${skill}`))
-            fail(`No pudimos descargar la skill ${skill} (HTTP ${status}).`, "download_failed");
-        const path = join(root, skill, "SKILL.md");
-        await mkdir(join(root, skill), { recursive: true });
+        if (!text.startsWith("---") || !text.includes(`name: ${skill.slug}`))
+            fail(`No pudimos descargar la skill ${skill.slug} (HTTP ${status}).`, "download_failed");
+        const path = join(root, skill.slug, "SKILL.md");
+        await mkdir(join(root, skill.slug), { recursive: true });
         await writeFile(path, text);
         installed.push(path);
         say(`✓ ${path}`);
     }
-    emit({ installed }, () => console.log(`Tu agente ya puede integrar y operar Talo. Sumale el MCP: ${CMD} mcp`));
+    emit({ installed, stacks: chosen.map((kit) => kit.stack), detected: detected.map((kit) => kit.stack) }, () => {
+        if (chosen.length)
+            console.log(`Kits por stack: ${chosen.map((kit) => kit.label).join(", ")}.`);
+        else if (flags.stack === undefined)
+            console.log(`No reconocí el stack de este proyecto. Elegí un kit con ${CMD} skills install --stack <${kitIds(kits)}>.`);
+        console.log(`Tu agente ya puede integrar y operar Talo. Sumale el MCP: ${CMD} mcp`);
+    });
+}
+/** The stack kits, marking the ones that match this project. */
+async function listSkills(hubUrl) {
+    const index = await fetchSkillsIndex(hubUrl);
+    const kits = index.filter((skill) => skill.kind === "stack");
+    const detected = new Set((await detectStacks(process.cwd(), kits)).map((kit) => kit.slug));
+    emit({ skills: index.map((skill) => ({ ...skill, ...(skill.kind === "stack" ? { detected: detected.has(skill.slug) } : {}) })) }, () => {
+        console.log(`Skills base: ${index.filter((skill) => skill.kind === "core").map((skill) => skill.slug).join(", ")}`);
+        console.log("\nKits por stack (--stack <kit>):");
+        for (const kit of kits)
+            console.log(`  ${kit.stack.padEnd(16)}${kit.label}${detected.has(kit.slug) ? "  ← este proyecto" : ""}`);
+        console.log(`\nInstalar: ${CMD} skills install. Otro stack: ${DEFAULT_HUB}/docs/stacks.md`);
+    });
+}
+/** Where --vercel and --env-file ask a new secret to go, checked before anything is created. */
+function secretDestinations() {
+    let vercel;
+    if (flags.vercel !== undefined) {
+        try {
+            vercel = parseVercelTarget(flags.vercel);
+        }
+        catch (error) {
+            fail(error.message, "invalid_option");
+        }
+    }
+    if (flags["env-file"] !== undefined && !flags["env-file"].trim())
+        fail("--env-file necesita la ruta del archivo, por ejemplo .env.local.", "invalid_option");
+    return { vercel, envFile: flags["env-file"] };
+}
+/**
+ * Writes the secret to each destination. Returns where it went, or Vercel's or the file system's
+ * error (the caller then undoes what it created, so no secret is left that nobody has).
+ */
+async function storeSecret(name, value, to) {
+    const saved = [];
+    if (to.envFile) {
+        try {
+            await writeEnvFile(to.envFile, name, value);
+        }
+        catch (error) {
+            return { saved, error: `No pudimos escribir ${to.envFile}: ${error.message}` };
+        }
+        saved.push(to.envFile);
+        if (gitIgnores(to.envFile) === false)
+            say(`! git no ignora ${to.envFile}: agregá .env* a .gitignore antes de commitear.`);
+    }
+    if (to.vercel) {
+        say(`… Guardando ${name} en Vercel (${to.vercel.environment}${to.vercel.branch ? `, rama ${to.vercel.branch}` : ""})`);
+        const error = addToVercel(name, value, to.vercel);
+        if (error)
+            return { saved, error: `Vercel no la guardó:\n${error}\n¿Corriste vercel link en este proyecto?` };
+        saved.push(describeTarget(to.vercel));
+    }
+    return { saved };
 }
 /** Which shell will run a printed command: PowerShell spells environment variables differently. */
 function shellSyntax() {
@@ -524,8 +632,8 @@ async function main() {
     if (command === "login")
         return login(config);
     if (command === "skills") {
-        if (sub !== "install")
-            fail(`Usá: ${CMD} skills install [--global]`);
+        if (sub !== undefined && sub !== "install" && sub !== "list")
+            fail(`Usá: ${CMD} skills install [--stack <kit>] [--global] | skills list`);
         let hubUrl;
         try {
             hubUrl = requestedHub(flags.hub) ?? DEFAULT_HUB;
@@ -533,7 +641,7 @@ async function main() {
         catch (error) {
             fail(error.message, "invalid_hub");
         }
-        return installSkills(hubUrl);
+        return sub === "install" ? installSkills(hubUrl) : listSkills(hubUrl);
     }
     if (command === "logout") {
         const environments = flags.all ? ["sandbox", "production"] : [chosenEnvironment(config)];
@@ -745,7 +853,25 @@ async function run(hub, ctx) {
             if (!arg)
                 fail(`Usá: ${CMD} webhooks ${sub === "add" ? "add <url>" : `${sub} <id>`}`);
             if (sub === "add") {
+                const destinations = secretDestinations();
+                if (!flags["skip-check"]) {
+                    const probe = await probeWebhookUrl(arg);
+                    const shown = arg.replace(/(x-vercel-protection-bypass=)[^&#]+/, "$1redacted");
+                    if (probe.verdict !== "ok")
+                        fail(`${shown}: ${probe.message}\nSi ya lo resolviste, repetí con --skip-check.`, `webhook_url_${probe.verdict}`, { status: probe.status ?? null });
+                    say(`✓ ${probe.message}`);
+                }
                 const endpoint = await hub.post("/api/v1/webhook-endpoints", { url: arg });
+                if (destinations.vercel || destinations.envFile) {
+                    const stored = await storeSecret("TALO_HUB_WEBHOOK_SECRET", endpoint.secret, destinations);
+                    if (stored.error) {
+                        await hub.request("DELETE", `/api/v1/webhook-endpoints/${encodeURIComponent(endpoint.id)}`).catch(() => undefined);
+                        fail(`${stored.error}\nBorramos el webhook que acabábamos de registrar.`, "secret_not_saved");
+                    }
+                    const { secret: _secret, ...shown } = endpoint;
+                    return emit({ ...shown, secret_saved_to: stored.saved }, () => console.log(`✓ Webhook ${endpoint.id}: secreto guardado como TALO_HUB_WEBHOOK_SECRET en ${stored.saved.join(" y ")} (no se muestra).` +
+                        (destinations.vercel ? `\n  Redesplegá para que lo tome, y probalo con ${CMD} webhooks test ${endpoint.id}.` : "")));
+                }
                 return emit(endpoint, () => console.log(`✓ Webhook ${endpoint.id}\n  Secreto para verificar la firma (guardalo en el .env de tu servidor como TALO_HUB_WEBHOOK_SECRET; no se vuelve a mostrar):\n  ${endpoint.secret}`));
             }
             if (sub === "remove")
@@ -755,7 +881,7 @@ async function run(hub, ctx) {
                 process.exitCode = 1;
             return emit(result, () => console.log(result.delivered
                 ? `✓ ${result.url} recibió el evento de prueba (HTTP ${result.status_code}).`
-                : `✗ ${result.url} no lo aceptó: ${result.error ?? `HTTP ${result.status_code}`}. Revisá que verifique la firma y responda 2xx.`));
+                : `✗ ${result.url} no lo aceptó: ${result.error ?? `HTTP ${result.status_code}`}.${result.reason && result.reason !== "http_error" ? "" : " Revisá que verifique la firma y responda 2xx."}`));
         }
         case "keys": {
             if (sub === undefined || sub === "list")
@@ -763,10 +889,27 @@ async function run(hub, ctx) {
             if (sub === "create") {
                 if (flags.scope && !["read", "charge", "full"].includes(flags.scope))
                     fail("--scope tiene que ser read, charge o full.", "invalid_option");
+                const destinations = secretDestinations();
                 const created = await hub.post("/api/v1/api-keys", {
                     name: flags.name ?? "CLI",
                     scope: flags.scope ?? "charge",
                 });
+                if (destinations.vercel || destinations.envFile) {
+                    const revoke = () => hub.request("DELETE", `/api/v1/api-keys/${encodeURIComponent(created.id)}`).catch(() => undefined);
+                    if (created.environment === "production" && destinations.vercel && destinations.vercel.environment !== "production") {
+                        await revoke();
+                        fail("Una key de producción (plata real) va solo en el entorno production de Vercel. La revocamos; para preview creá una de sandbox.", "live_key_outside_production");
+                    }
+                    const stored = await storeSecret("TALO_HUB_API_KEY", created.api_key, destinations);
+                    if (stored.error) {
+                        await revoke();
+                        fail(`${stored.error}\nRevocamos la key que acabábamos de crear.`, "secret_not_saved");
+                    }
+                    const { api_key, ...shown } = created;
+                    const prefix = `${api_key.slice(0, 13)}…`;
+                    return emit({ ...shown, prefix, saved_to: stored.saved }, () => console.log(`✓ Key ${prefix} (${created.environment} · scope ${created.scope}) guardada como TALO_HUB_API_KEY en ${stored.saved.join(" y ")}. No se muestra.` +
+                        (destinations.vercel ? "\n  Redesplegá para que la tome." : "")));
+                }
                 return emit(created, () => console.log(`✓ ${created.api_key}\n  ${created.environment} · scope ${created.scope}. Guardala ahora en el .env o los secretos de tu servidor (TALO_HUB_API_KEY): no se vuelve a mostrar.\n  En esta terminal, exportarla reemplaza a la key de tu login.`));
             }
             if (sub === "revoke") {

package/dist/probe.js

@@ -0,0 +1,59 @@
+// Before registering a webhook URL, one unsigned POST tells whether the hub's signed deliveries
+// would reach the handler: the hub doesn't follow redirects and sends no login, and a correct
+// handler rejects an unsigned body with 400.
+const VERCEL_LOGIN = /^https:\/\/vercel\.com\/sso-api/;
+export async function probeWebhookUrl(url, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": "TaloPartnerHub-Webhooks/1" },
+            body: "{}",
+            redirect: "manual",
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (error) {
+        const reason = error.cause?.code ?? error.name;
+        return { verdict: "unreachable", message: `No pudimos llegar a la URL (${reason}). ¿Está desplegada y es pública?` };
+    }
+    const status = response.status;
+    const location = response.headers.get("location") ?? "";
+    const body = status === 401 || status === 403 ? (await response.text().catch(() => "")).slice(0, 2000) : "";
+    const vercelLogin = VERCEL_LOGIN.test(location) || /_vercel_sso_nonce=/.test(response.headers.get("set-cookie") ?? "") || /Protected deployment|Protected by Vercel/.test(body);
+    if (vercelLogin) {
+        return {
+            verdict: "vercel_protection",
+            status,
+            message: "La Deployment Protection de Vercel la bloquea antes de tu código (las URLs *.vercel.app de cada deploy y de cada rama están protegidas). Usá el dominio de producción, o abrí esa URL a propósito (Deployment Protection Exception o ?x-vercel-protection-bypass=<secreto>).",
+        };
+    }
+    if (status >= 300 && status < 400) {
+        return { verdict: "redirect", status, message: `Redirige${location ? ` a ${location}` : ""}. El hub no sigue redirecciones: registrá la URL final (sin barra al final, el dominio principal).` };
+    }
+    if (response.headers.get("x-vercel-mitigated")) {
+        return { verdict: "vercel_firewall", status, message: "El Firewall de Vercel desafió el pedido. Agregá una regla Bypass para POST a esta ruta antes de los managed rulesets." };
+    }
+    if (status === 419) {
+        return { verdict: "csrf", status, message: "Responde 419: la ruta está bajo el CSRF de Laravel. Ponela en routes/api.php o excluila en bootstrap/app.php." };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            verdict: "auth",
+            status,
+            message: `Responde ${status} antes de verificar la firma: algo delante de la ruta pide login o un token CSRF (middleware, proxy de auth, CsrfViewMiddleware de Django). Excluí la ruta del webhook.`,
+        };
+    }
+    if (status === 404 || status === 405) {
+        return { verdict: "not_found", status, message: `Responde ${status}: no hay una ruta POST ahí. Revisá la URL o desplegá el handler primero.` };
+    }
+    if (status === 429) {
+        return { verdict: "vercel_firewall", status, message: "Responde 429: un rate limit o el firewall frena el pedido. Excluí la ruta del webhook." };
+    }
+    if (status >= 200 && status < 300) {
+        return { verdict: "unsigned_accepted", status, message: `Aceptó un evento sin firma (HTTP ${status}). El handler tiene que verificar talo-hub-signature y responder 400 si no es válida.` };
+    }
+    // 400 is the expected answer; a 5xx usually means TALO_HUB_WEBHOOK_SECRET isn't set yet, which is
+    // normal before registering (the secret comes from this command).
+    return { verdict: "ok", status, message: status === 400 ? "Rechaza eventos sin firma (HTTP 400), como corresponde." : `Respondió HTTP ${status}.` };
+}

package/dist/secrets.js

@@ -0,0 +1,67 @@
+// Puts a new secret (a project key or a webhook secret) where the project reads it, without
+// printing it: into a dotenv file, or into a Vercel environment with `vercel env add`, the value
+// going through stdin. Piping into `vercel env add` from a shell can store an empty value (it reads
+// stdin for only 500 ms) or a BOM (Windows PowerShell), so we write the pipe ourselves.
+import { spawnSync } from "node:child_process";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+const BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,249}$/;
+/** `production`, `preview` or `preview:<git branch>`. */
+export function parseVercelTarget(value) {
+    const [environment, branch, ...rest] = value.trim().split(":");
+    if (environment === "development") {
+        throw new Error("Para desarrollo usá --env-file .env.local: Vercel no deja bajar los valores secretos a tu máquina.");
+    }
+    if ((environment !== "production" && environment !== "preview") || rest.length) {
+        throw new Error(`--vercel tiene que ser production, preview o preview:<rama> (recibimos "${value}").`);
+    }
+    if (branch !== undefined && (environment !== "preview" || !BRANCH.test(branch))) {
+        throw new Error(`La rama va solo con preview y sin espacios ni comillas: --vercel preview:<rama> (recibimos "${value}").`);
+    }
+    return branch ? { environment, branch } : { environment };
+}
+export const describeTarget = (target) => `vercel:${target.environment}${target.branch ? `:${target.branch}` : ""}`;
+function run(command, args, input) {
+    // Through the shell so `vercel` (vercel.cmd on Windows) resolves; every argument is validated
+    // above and the secret only travels on stdin.
+    return spawnSync([command, ...args].join(" "), { input, encoding: "utf8", shell: true, timeout: 180_000 });
+}
+/** The Vercel CLI on the PATH, or npx's (TALO_HUB_VERCEL_CLI overrides both, for tests). */
+function vercelCommand() {
+    if (process.env.TALO_HUB_VERCEL_CLI)
+        return process.env.TALO_HUB_VERCEL_CLI;
+    return run("vercel", ["--version"]).status === 0 ? "vercel" : "npx --yes vercel";
+}
+/** Stores `value` as a Secret env var of the linked Vercel project. Returns Vercel's error when it fails. */
+export function addToVercel(name, value, target) {
+    const args = ["env", "add", name, target.environment, ...(target.branch ? [target.branch] : []), "--sensitive", "--force", "--yes"];
+    const result = run(vercelCommand(), args, value);
+    if (result.status === 0)
+        return undefined;
+    const output = `${result.stderr ?? ""}\n${result.stdout ?? ""}`.replaceAll(value, "…").trim();
+    return output.split("\n").filter(Boolean).slice(-4).join("\n") || (result.error?.message ?? `vercel terminó con código ${result.status}`);
+}
+/** Sets NAME=value in a dotenv file (replacing the line if there is one), readable only by the user. */
+export async function writeEnvFile(path, name, value) {
+    let text = "";
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const line = `${name}=${value}`;
+    const existing = new RegExp(`^(export\\s+)?${name}=.*$`, "m");
+    const next = existing.test(text) ? text.replace(existing, () => line) : `${text}${text && !text.endsWith("\n") ? "\n" : ""}${line}\n`;
+    await writeFile(path, next, { mode: 0o600 });
+    await chmod(path, 0o600).catch(() => undefined);
+}
+/** Whether git ignores the file: false means it could end up committed; undefined, not a git repo. */
+export function gitIgnores(path) {
+    const result = spawnSync("git", ["check-ignore", "-q", path], { encoding: "utf8" });
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    return undefined;
+}

package/dist/stacks.js

@@ -0,0 +1,97 @@
+// Which stack kits fit a project. The hub's /skills/index.json says how to recognize each stack
+// (dependency names, or files at the project root); we look for them in the current folder.
+import { access, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
+/** Keeps the index entries we can trust: the slug becomes a folder name, so it must be plain. */
+export function readSkillsIndex(body) {
+    const skills = body?.skills;
+    if (!Array.isArray(skills))
+        return undefined;
+    return skills.flatMap((raw) => {
+        const entry = raw;
+        if (typeof entry.slug !== "string" || !SLUG.test(entry.slug) || (entry.kind !== "core" && entry.kind !== "stack"))
+            return [];
+        if (entry.kind === "core")
+            return [{ slug: entry.slug, kind: "core" }];
+        if (typeof entry.stack !== "string" || !SLUG.test(entry.stack))
+            return [];
+        const detect = (entry.detect ?? {});
+        return [
+            {
+                slug: entry.slug,
+                kind: "stack",
+                stack: entry.stack,
+                label: typeof entry.label === "string" ? entry.label : entry.stack,
+                detect: { npm: strings(detect.npm), composer: strings(detect.composer), python: strings(detect.python), files: strings(detect.files) },
+            },
+        ];
+    });
+}
+async function text(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function dependencyNames(source, sections) {
+    if (!source)
+        return new Set();
+    try {
+        const manifest = JSON.parse(source);
+        return new Set(sections.flatMap((section) => Object.keys(manifest[section] ?? {})));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** A Python requirement as written in requirements.txt (`fastapi==…`), pyproject.toml (`"fastapi>=…"`, `fastapi = "^…"`) or a Pipfile. */
+function mentionsPythonPackage(sources, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[\\s"'\\[,])${escaped}(?=[\\s"'<>=!~\\[;,]|$)`, "im").test(sources);
+}
+/** The stack kits whose dependencies or files appear at the root of `dir`. */
+export async function detectStacks(dir, kits) {
+    const npm = dependencyNames(await text(join(dir, "package.json")), ["dependencies", "devDependencies"]);
+    const composer = dependencyNames(await text(join(dir, "composer.json")), ["require", "require-dev"]);
+    const entries = await readdir(dir).catch(() => []);
+    const pythonFiles = entries.filter((name) => /^requirements.*\.txt$/i.test(name) || name === "pyproject.toml" || name === "Pipfile");
+    const python = (await Promise.all(pythonFiles.map((name) => text(join(dir, name))))).join("\n");
+    const matched = [];
+    for (const kit of kits) {
+        const detect = kit.detect ?? {};
+        const found = (detect.npm ?? []).some((name) => npm.has(name)) ||
+            (detect.composer ?? []).some((name) => composer.has(name)) ||
+            (detect.python ?? []).some((name) => mentionsPythonPackage(python, name)) ||
+            (await Promise.all((detect.files ?? []).map((file) => exists(join(dir, file))))).some(Boolean);
+        if (found)
+            matched.push(kit);
+    }
+    return matched;
+}
+/** Resolves `--stack nextjs-vercel,python` (ids or full slugs), `all` or `none`. */
+export function pickStacks(kits, asked) {
+    const wanted = asked
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+    if (wanted.includes("none"))
+        return { kits: [], unknown: [] };
+    if (wanted.includes("all"))
+        return { kits, unknown: [] };
+    const chosen = kits.filter((kit) => wanted.includes(kit.stack) || wanted.includes(kit.slug));
+    const unknown = wanted.filter((item) => !kits.some((kit) => kit.stack === item || kit.slug === item));
+    return { kits: chosen, unknown };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talo-hub",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Transferencias bancarias automáticas en Argentina con Talo Pay: un CVU por cobro, acreditación y conciliación automáticas, webhooks firmados, sandbox y MCP para agentes de IA (Claude, Cursor).",
   "keywords": [
     "talo",