@timekast/factory 1.28.1 → 2.0.1

package/dist/index.js

@@ -20,12 +20,14 @@ import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/docto
 import { parseNewFlags, runNew } from './commands/new.js';
 import { parseProvisionFlags, runProvision } from './commands/provision.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
-import { secretsCommand } from './commands/secrets.js';
 import { parseStatusFlags, runStatus } from './commands/status.js';
 import { runTicketCommand } from './commands/ticket.js';
 import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
 import { maybeOfferAdopt, parseUpdateFlags, runUpdate } from './commands/update.js';
+import { runVaultCommand } from './commands/vault.js';
+import { loginCommand } from './lib/rail.js';
 import { detectRepo } from './lib/repo-detection.js';
+import { VAULT_CONFIG } from './lib/vault-config.js';
 import { runTuiMenu } from './tui/index.js';
 const HELP = `
 @timekast/factory — bootstrap y mantenimiento de proyectos derivados del Factory.
@@ -43,12 +45,19 @@ Comandos:
                    (--launcher: verifica el entorno — Node ≥ 22, gh, gh auth, membresía org)
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
-  provision        Aprovisiona la infra de un derivado (Neon/Vercel/GitHub/DNS/backlog) — flag-driven, --json
+  provision        Aprovisiona la infra de un derivado (Neon, GitHub, DNS, backlog y su destino de
+                   despliegue: Vercel o Railway) — flag-driven, --json
   backlog <sub>    push: refleja el backlog local en backlog.timekast.mx · sync: status + self-healing
   ticket <sub>     push: entrega un factory-ticket de project/factory/ al repo del Factory
-  secrets <file>   Mergea un archivo KEY=value de secretos de metodología a ~/.claude/.env (chmod 600)
-  env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura .env.local
+  env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura las variables
+                   (en la bóveda si el repo la tiene; sin bóveda, en .env.local)
   invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
+  vault <sub>      adopt: pasa a la bóveda un repo que nació antes de ella (sin --apply sólo
+                   enseña el plan, por nombre y huella — nunca valores; con varios proyectos
+                   de Vercel, --vercel-project <id> elige el principal) · sync railway: crea
+                   el sync de un entorno de la bóveda a un servicio de Railway · deploys: siembra el
+                   proyecto de cada despliegue de un repo multi-cliente desde la plantilla
+                   (--apply, --yes para confirmar sin terminal los valores que cambia)
 
 Sobre \`new\`:
   Pregunta el perfil de forma interactiva. Los flags \`--full\` / \`--core\` lo
@@ -85,28 +94,50 @@ Sobre \`update\`:
 Sobre \`provision\`:
   Aprovisiona la infra de un proyecto derivado. Flag-driven (sin prompts) y
   headless-safe; la interacción la pone la skill \`tk-provision\`. Preflight
-  fail-closed (gh + tokens del gate + \`VERCEL_TOKEN\` con acceso al team);
-  \`neonctl\` es opcional (ausente → warning). Flags:
-    --services=a,b   Servicios a crear (neon,vercel,github,dns,backlog). \`backlog\`
-                     registra el proyecto en backlog.timekast.mx y escribe
-                     BACKLOG_API_KEY + BACKLOG_PROJECT_ID a .env.local (requiere
-                     BACKLOG_ADMIN_TOKEN en el rail; ausente en un bundle → se omite)
+  fail-closed (gh + tokens del gate + — con destino Vercel — \`VERCEL_TOKEN\` con
+  acceso al team);
+  \`neonctl\` es opcional (ausente → warning). Por default crea primero el proyecto
+  del repo en la bóveda (\`vault\`) y cada paso escribe ahí lo que acuña — sin
+  \`.env.local\`. No se ofrece en perfil \`core\`, ni se agrega sola a un repo ya
+  aprovisionado sin bóveda (para eso: \`factory vault adopt\`). Flags:
+    --services=a,b   Servicios a crear (vault,neon,github,vercel,railway,dns,backlog). \`backlog\`
+                     registra el proyecto en backlog.timekast.mx y guarda
+                     BACKLOG_API_KEY + BACKLOG_PROJECT_ID en el entorno \`local\` de la
+                     bóveda (sin bóveda: en .env.local) (requiere BACKLOG_ADMIN_TOKEN en
+                     el rail; ausente en un bundle → se omite)
+    --target=<dest>  Destino de despliegue del repo: vercel | railway. OBLIGATORIO en un
+                     alta nueva con paso de despliegue (github, vercel, railway, dns o
+                     --domain); neon/backlog solos no lo piden. Queda guardado en
+                     .timekast/provision.json. Un repo sin destino guardado lo descubre
+                     preguntando a Railway y a Vercel por el repo conectado (nunca por
+                     vercel.json ni otro archivo). Cambiar un destino guardado: sólo
+                     --adopt --force --target=<otro>. Con Railway, --adopt lo encuentra
+                     por el repo conectado y --destroy borra con RAILWAY_TOKEN del rail
+    --resolve-target Sólo resuelve el destino y lo guarda en .timekast/provision.json; no
+                     crea nada más. Salida: 0 = resuelto (guardado o ya estaba) ·
+                     10 = sin destino (el repo no está conectado en ninguna) ·
+                     11 = ambiguo (conectado en las dos, o project-config.md declara un
+                     rail de cliente) · 12 = no se pudo leer un token del rail
+    --no-vault       Omite la bóveda: ninguna llamada a ella, y todo como antes
+                     (.env.local + escritura directa a los despliegues)
     --slug=<slug>    Identificador del stack (nombre del proyecto + dominios interinos)
-    --team=<id>      Team de Vercel (override; default = \`VERCEL_TEAM_ID\` del rail ~/.claude/.env)
+    --team=<id>      Team de Vercel (override; default = \`VERCEL_TEAM_ID\` de rail-timekast en la bóveda)
     --org-id=<id>    Org de GitHub (override; default = org del Factory)
     --neon-org=<x>   Organización de Neon donde CREAR el proyecto: nombre o id.
                      Default = \`NEON_ORG\` del rail; si la key ve una sola org, esa.
                      Varias orgs y sin selector → aborta (nunca adivina). Un proyecto
                      que YA existe ignora este flag: su org se lee del proyecto
     --remint         Reacuña la API key project-scoped de Neon aunque el paso esté
-                     completo (revoca la vigente, sube los 3 secrets de E2E y
-                     reescribe .env.local). Para una key revocada por fuera
+                     completo (revoca la vigente, sube los 3 secrets de E2E y la
+                     reescribe en develop:/ci de la bóveda — sin bóveda, en .env.local).
+                     Para una key revocada por fuera
     --domain=<dom>   Dominio definitivo del cliente (diferible; standalone o inicial)
     --dns=<ruta>     Ruta DNS para --domain: org (default) | cliente-cf | registrar
     --verify-timeout=<min>  Timeout del sondeo de verificación de Vercel (default 10)
     --confirm        Pre-aprueba retirar el dominio interino tras verificar (headless-safe)
     --ephemeral      Marca el stack \`ephemeral\` (vs \`live\`) para \`--destroy\`
-    --dry-run        Imprime el plan sin tocar ninguna API ni escribir estado
+    --dry-run        Imprime el plan sin tocar ninguna API de plataforma (Railway, Vercel,
+                     Neon, Cloudflare) ni escribir estado; sin destino resuelto lo dice
     --resume         Retoma desde \`.timekast/provision.json\`, salta pasos hechos
     --adopt          Reconstruye \`.timekast/provision.json\` de un derivado existente
                      consultando los providers EN SOLO-LECTURA (nunca crea/borra)
@@ -128,16 +159,23 @@ Sobre \`status\` y \`doctor\`:
 
 Sobre \`env\`:
   \`env push\` sube las product vars de \`.env.local\` a Vercel (production+preview),
-  sin tocar las provision-owned. \`env wizard\` configura \`.env.local\`:
+  sin tocar las provision-owned. En un repo con bóveda (bloque \`vault\`) no escribe:
+  lo dice, nombra el proyecto de la bóveda y termina sin error. \`env wizard\` configura
+  las variables — en un repo con bóveda las escribe ahí (una copia en main:/, referenciada desde develop:/ y local); sin
+  bóveda, en \`.env.local\`:
     (sin flags)      Wizard interactivo en la terminal (deriva las preguntas de \`.env.example\`)
     --plan [--json]  Emite el plan de preguntas (lo consume el agente / la skill tk-provision)
-    --apply [--push] Lee \`{ answers, push? }\` JSON por stdin y escribe \`.env.local\`
+    --apply [--push] Lee \`{ answers, push? }\` JSON por stdin y las escribe (con bóveda,
+                     \`--push\` no aplica: los despliegues las reciben de la bóveda)
+    --review [--json] Resumen enmascarado (con bóveda: del entorno \`local\`)
+    --gen-vapid      Genera las llaves VAPID (con bóveda, se guardan ahí; la privada no se imprime)
 
 Sobre \`backlog\`:
   \`backlog push\` refleja el backlog local (\`project/backlog/*\`) en
   backlog.timekast.mx en cascada (épicas → features de los Refs \`FT-XX\` → issues
   story/task según el campo \`Board:\`). Read-only por defecto: sin \`BACKLOG_API_KEY\`
-  en \`.env.local\` termina con exit 0 y una nota (nunca bloquea \`/backlog\`). Flags:
+  (en un repo sin bóveda, la de \`.env.local\`) termina con exit 0 y una nota (nunca
+  bloquea \`/backlog\`). Flags:
     --reconcile      PATCH del status cuando el elemento ya existe (en vez de saltarlo)
     --stamp          Incluye issues/épicas sin UUID y estampa su \`Backlog UUID\` de vuelta
     --backfill       Campaña legacy: incluye + estampa un backlog pre-BSYNC-007 completo
@@ -166,10 +204,12 @@ Sobre \`ticket\`:
 
 Sobre \`invite-admin\`:
   Materializa el primer super_admin de un derivado por invitación (reemplaza el
-  viejo seed con password en texto plano). Resuelve la connection string del
-  target desde \`.env.local\` y spawnea el script del kit con ella:
+  viejo seed con password en texto plano). En un repo sin bóveda resuelve la
+  connection string del target desde \`.env.local\` y spawnea el script del kit con ella:
+  En un repo con bóveda lee el entorno del target directo de la bóveda, con tu sesión
+  (main → main:/ + main:/ci; develop → local) y no toca \`.env.local\`.
     --email=<addr>   Email que recibe la invitación y será super_admin (requerido)
-    --target=<t>     develop (default, usa DATABASE_URL) | main (usa DATABASE_URL_MAIN)
+    --target=<t>     develop (default, usa DATABASE_URL) | main (sin bóveda: DATABASE_URL_MAIN)
     --app-url=<url>  Override del NEXT_PUBLIC_APP_URL del link de aceptación
                      (úsalo con --target main para que apunte a producción)
   Alias en el derivado: \`pnpm invite:admin --email=...\`.
@@ -191,6 +231,24 @@ function readVersion() {
         return '0.0.0';
     }
 }
+/**
+ * The tombstone of `factory secrets` (RETIRED — the rail lives in the vault; nothing reads a
+ * local rail file anymore). Kept instead of "unknown command" because installed desktop
+ * launchers still run `factory secrets <path>` and paint success on exit 0. Contract:
+ *   · every shape (`secrets`, `secrets <path>`, `secrets pull|sync`, `secrets --help`) gets it;
+ *   · non-zero exit (CLIError), so an old launcher card renders it as an error;
+ *   · the LAST line is the actionable instruction — an old card shows only that line;
+ *   · the arguments are never read: nothing is opened, validated or echoed (a path can name a
+ *     person or a client).
+ */
+function secretsRetiredError() {
+    const { rail } = VAULT_CONFIG;
+    return new CLIError([
+        `\`factory secrets\` se retiró: el rail de secretos ya no se importa a ~/.claude/.env, vive en la bóveda (proyecto ${rail.name}) y los comandos lo leen de ahí.`,
+        'No se leyó ni se importó ningún archivo.',
+        `Para entrar: corre \`${loginCommand()}\` y pide a un admin acceso a ${rail.name}.`,
+    ].join('\n'));
+}
 async function main(argv) {
     const [command, ...rest] = argv;
     // Explicit help flags always print the static HELP — never the TUI.
@@ -198,6 +256,11 @@ async function main(argv) {
         console.log(HELP);
         return;
     }
+    // `factory secrets` is retired: EVERY shape answers with the tombstone — `--help`/`-h`
+    // included, which otherwise the help gate below would turn into an exit 0 that an old
+    // launcher paints as success. Before that gate on purpose.
+    if (command === 'secrets')
+        throw secretsRetiredError();
     // A `--help`/`-h` flag ANYWHERE (e.g. `factory env push --help`) prints help and
     // NEVER runs the command. A help flag must never trigger a mutation: `env push --help`
     // used to fire a REAL Vercel push, because the check above only inspects the first arg.
@@ -259,7 +322,9 @@ async function main(argv) {
                 await runLauncherDoctor({}, flags.json);
             }
             else {
-                runDoctor();
+                // Awaited: in `bóveda` mode the report waits for the bounded drift step (ADOPT-004), and
+                // `main` exits the process as soon as it resolves.
+                await runDoctor();
             }
             return;
         }
@@ -300,16 +365,9 @@ async function main(argv) {
             return;
         }
         case 'secrets': {
-            // Single shape: `factory secrets <file>` — merge a KEY=value file into the
-            // rail (~/.claude/.env). The org gate (`secrets pull`/`sync`) was removed;
-            // the future shared-secrets system is Infisical (a fresh branch).
-            const file = rest.filter((a) => !a.startsWith('-'))[0];
-            if (!file) {
-                throw new CLIError('Falta el archivo de secretos. Uso: `factory secrets <file>` ' +
-                    '(un archivo `KEY=value`, p.ej. el master `secrets.env`) que se mergea a `~/.claude/.env`.');
-            }
-            await secretsCommand(file);
-            return;
+            // Unreachable today (the tombstone fires before the help gate). Kept so that reordering
+            // the gates above can never turn `secrets` into "unknown command".
+            throw secretsRetiredError();
         }
         case 'env': {
             const sub = rest[0];
@@ -329,11 +387,11 @@ async function main(argv) {
                     return;
                 }
                 if (wflags.review) {
-                    runEnvWizardReview(wflags);
+                    await runEnvWizardReview(wflags);
                     return;
                 }
                 if (wflags.genVapid) {
-                    runEnvWizardGenVapid();
+                    await runEnvWizardGenVapid();
                     return;
                 }
                 if (wflags.apply) {
@@ -346,6 +404,12 @@ async function main(argv) {
             throw new CLIError(`Subcomando de env desconocido: \`${sub ?? '(ninguno)'}\`. ` +
                 'Uso: `factory env push` o `factory env wizard`.');
         }
+        case 'vault': {
+            // `factory vault adopt [--apply]` (ADOPT-001) — move a repo born before the vault into it.
+            // Without a subcommand it prints the vault help.
+            await runVaultCommand(rest);
+            return;
+        }
         case 'invite-admin': {
             // Mint a single-use super_admin invite against the target branch's DB.
             // Spawns the kit script `scripts/tools/invite-admin.ts` with the resolved

package/dist/lib/backlog-mapping.js

@@ -18,6 +18,9 @@
  * remotely, keeping the 6↔6 bijection intact.
  */
 import { existsSync, readFileSync } from 'node:fs';
+import { readVaultLink, UNREADABLE_STATE_REMEDY, VaultLinkMalformedError, } from './provision-state.js';
+import { INFISICAL_INSTALL_HINT, RailNoSessionError, RailNotInstalledError, loginCommand, } from './rail.js';
+import { VAULT_ROOT_PATH, VaultApiError, VaultNoAccessError, createVaultClient, } from './vault-api.js';
 /**
  * LOCAL bucket → REMOTE `WorkStatus`. Half of the bijection; {@link STATUS_REMOTE_TO_LOCAL}
  * is its exact inverse. The 6 remote states were live-verified (smoke Hallazgo 3).
@@ -106,9 +109,9 @@ export function mapStoryPoints(sp) {
     return Number.isInteger(sp) && sp > 0 ? sp : null;
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// Credential resolution — fail-closed, NEVER throws (issue §4)
+// Credential resolution — fail-closed, NEVER throws (issue §4 · VAULT-006)
 // ─────────────────────────────────────────────────────────────────────────────
-/** The env keys the derivative's `.env.local` carries for the backlog integration. */
+/** The env keys that carry the project-scoped backlog credentials. */
 export const BACKLOG_API_KEY_VAR = 'BACKLOG_API_KEY';
 export const BACKLOG_PROJECT_ID_VAR = 'BACKLOG_PROJECT_ID';
 /** Default FS reader — reads `.env.local` if present, swallowing any error to `null`. */
@@ -133,15 +136,14 @@ function readEnvValue(body, key) {
     }
     return value.length > 0 ? value : undefined;
 }
-/**
- * Resolve the per-project backlog credentials from `{rootDir}/.env.local`. FAIL-CLOSED
- * (issue §4): a missing file, an unreadable file, or a missing/empty `BACKLOG_API_KEY`
- * / `BACKLOG_PROJECT_ID` all return the distinctive `not-configured` result — this
- * function NEVER throws, so a derivative that never provisioned the backlog service
- * does not crash `push`/`sync`; they just skip. The `readFile` seam is injectable so
- * tests drive every branch without disk.
- */
-export function resolveBacklogCredentials(rootDir, deps = {}) {
+/** The names of the two credential keys that are missing, joined for a reason. */
+function missingKeys(apiKey, projectId) {
+    return [!apiKey ? BACKLOG_API_KEY_VAR : null, !projectId ? BACKLOG_PROJECT_ID_VAR : null]
+        .filter(Boolean)
+        .join(' + ');
+}
+/** The pre-vault source: `{rootDir}/.env.local` (behavior unchanged). */
+function resolveFromEnvFile(rootDir, deps) {
     const read = deps.readFile ?? defaultReadFile;
     let body;
     try {
@@ -160,16 +162,107 @@ export function resolveBacklogCredentials(rootDir, deps = {}) {
     const apiKey = readEnvValue(body, BACKLOG_API_KEY_VAR);
     const projectId = readEnvValue(body, BACKLOG_PROJECT_ID_VAR);
     if (!apiKey || !projectId) {
-        const missing = [
-            !apiKey ? BACKLOG_API_KEY_VAR : null,
-            !projectId ? BACKLOG_PROJECT_ID_VAR : null,
-        ]
-            .filter(Boolean)
-            .join(' + ');
         return {
             status: 'not-configured',
-            reason: `Falta ${missing} en \`.env.local\`; el backlog central no está configurado.`,
+            reason: `Falta ${missingKeys(apiKey, projectId)} en \`.env.local\`; el backlog central no está configurado.`,
         };
     }
     return { status: 'configured', apiKey, projectId };
 }
+/**
+ * Translate a vault failure into the `reason` of a `not-configured` result. Branches on the
+ * error CLASS / `kind`, never on its text, and never quotes the error's message (it could carry a
+ * host or an operation, but never a value — still, the reason is built here, names only).
+ * 🔴 No reason mentions `.env.local`: in a repo with a vault that file is not the source, and
+ * naming it sends the developer after a file that no longer exists.
+ */
+function vaultFailureReason(error, link) {
+    if (error instanceof RailNoSessionError) {
+        return ('No hay una sesión activa en la bóveda de secretos, o ya caducó; entra con ' +
+            `\`${loginCommand()}\` y vuelve a correr.`);
+    }
+    if (error instanceof RailNotInstalledError) {
+        return ('El CLI de la bóveda (`infisical`) no está instalado; instálalo con ' +
+            `\`${INFISICAL_INSTALL_HINT}\` y entra con \`${loginCommand()}\`.`);
+    }
+    if (error instanceof VaultNoAccessError) {
+        return (`Tu sesión de la bóveda no tiene acceso al proyecto \`${link.projectId}\` de este repo ` +
+            '(o ese proyecto no existe); pide acceso a un admin de la bóveda.');
+    }
+    if (error instanceof VaultApiError && error.kind === 'timeout') {
+        return 'La bóveda de secretos no respondió a tiempo; reintenta más tarde.';
+    }
+    return ('La bóveda de secretos no respondió (o respondió algo que no reconozco); reintenta más tarde ' +
+        'y, si persiste, repórtalo al equipo del Factory.');
+}
+/**
+ * The vault source (VAULT-006): the `local` environment of the repo's vault project, read with
+ * the vault client (VAULT-001) and the PERSON's session — no wrapper, so it works through `npx`.
+ * Never touches `.env.local`, even when a leftover one exists: the vault is the only source, and
+ * an old file would point at a rotated key.
+ */
+async function resolveFromVault(link, deps) {
+    let secrets;
+    try {
+        const client = createVaultClient(deps.vault);
+        secrets = await client.readSecrets(link.projectId, { env: link.envs.local, path: VAULT_ROOT_PATH }, { expandReferences: true });
+    }
+    catch (error) {
+        return { status: 'not-configured', reason: vaultFailureReason(error, link) };
+    }
+    const apiKey = secrets.get(BACKLOG_API_KEY_VAR)?.trim() || undefined;
+    const projectId = secrets.get(BACKLOG_PROJECT_ID_VAR)?.trim() || undefined;
+    if (!apiKey || !projectId) {
+        return {
+            status: 'not-configured',
+            reason: `Falta ${missingKeys(apiKey, projectId)} en el entorno \`${link.envs.local}\` de la bóveda ` +
+                'de este repo; el backlog central no está conectado (se da de alta con ' +
+                '`factory provision --services=backlog`).',
+        };
+    }
+    return { status: 'configured', apiKey, projectId };
+}
+/**
+ * Resolve the per-project backlog credentials. The presence of the `vault` block in
+ * `.timekast/provision.json` decides the source:
+ *   - WITH a vault block → the `local` environment of the repo's vault project (never
+ *     `.env.local`). Every vault failure (no session, no access, missing keys, vault down,
+ *     `infisical` missing, no seam under tests) becomes `not-configured` with a reason that names
+ *     the real cause.
+ *   - WITHOUT one → `{rootDir}/.env.local`, exactly as before.
+ *
+ * FAIL-CLOSED: this function NEVER throws (nor rejects), so a derivative that never provisioned
+ * the backlog service does not crash `push`/`sync`; they just skip. An unreadable
+ * `provision.json` is `not-configured` too — "I could not tell" never falls back to `.env.local`.
+ */
+export async function resolveBacklogCredentials(rootDir, deps = {}) {
+    let link;
+    try {
+        link = (deps.vaultLink ?? readVaultLink)(rootDir);
+    }
+    catch (error) {
+        // Neither case is fixed by `--adopt`: a malformed `vault` block stops it on the same block,
+        // and over an unreadable file it rebuilds the state WITHOUT the `vault` block. Name the
+        // manual fix (the file is committed: git holds the last good copy).
+        return {
+            status: 'not-configured',
+            reason: error instanceof VaultLinkMalformedError
+                ? 'El bloque `vault` de `.timekast/provision.json` no tiene la forma esperada; ' +
+                    'corrígelo a mano (o bórralo si este repo no vive en la bóveda).'
+                : 'No pude leer `.timekast/provision.json` para saber si este repo vive en la bóveda: ' +
+                    UNREADABLE_STATE_REMEDY,
+        };
+    }
+    if (link === null)
+        return resolveFromEnvFile(rootDir, deps);
+    try {
+        return await resolveFromVault(link, deps);
+    }
+    catch {
+        // Belt-and-suspenders: resolveFromVault already catches; the contract is "never throws".
+        return {
+            status: 'not-configured',
+            reason: 'La bóveda de secretos no respondió (o respondió algo que no reconozco); reintenta más tarde.',
+        };
+    }
+}

package/dist/lib/backlog-parse.js

@@ -95,7 +95,7 @@ export function parseTitle(content) {
     const match = content.match(/^# [\w-]+: (.*)$/m);
     return match ? match[1].trim() : undefined;
 }
-/** Parse `> **Skills:**` into its backtick-quoted tokens (`` `sk-api`, `kb-api` `` → [...]). */
+/** Parse `> **Skills:**` into its backtick-quoted tokens (`` `sk-api`, `sk-db` `` → [...]). */
 export function parseSkills(content) {
     const line = matchBlockquoteField(content, 'Skills');
     if (!line)