@timekast/factory 1.28.0 → 2.0.0

package/dist/commands/env.js

@@ -3,7 +3,8 @@
  *
  * Reads `.env.local` and pushes ONLY the product vars (everything EXCEPT the
  * provision-owned, per-environment vars) to `production` + `preview` via the
- * Vercel REST API. Reuses `pushEnvPlan` + `readVercelToken` + the existing
+ * Vercel REST API. Reuses `pushEnvPlan` + `readVercelToken` (the vault rail, with the
+ * person's session — `lib/rail.ts`) + the existing
  * `.vercel/project.json` link — no `vercel link`, no re-implemented REST push,
  * no risk of clobbering the per-env DATABASE_URL/AUTH_SECRET that provision set.
  *
@@ -14,9 +15,10 @@ import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
 import { PER_ENV_MARKER, PER_ENV_REGISTRY_FILE, PROVISION_OWNED, addToPerEnvRegistry, findInlinePerEnvMarkers, findPerEnvMarkedKeys, listEnvKeys, readPerEnvRegistry, setEnvLine, } from '../lib/env-file.js';
-import { applyDefaultOverrides, applyWizardAnswers, buildEnvReview, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, } from '../lib/env-wizard.js';
-import { defaultEnvPath, readVercelToken } from '../lib/provision-preflight.js';
-import { readProvisionState } from '../lib/provision-state.js';
+import { applyDefaultOverrides, applyWizardAnswers, applyWizardAnswersToVault, buildEnvReview, buildEnvReviewFromEnv, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, readVaultLocalEnv, readVaultMain, writeSharedToVault, } from '../lib/env-wizard.js';
+import { defaultRail, railTokenRejectedHint, readVercelToken } from '../lib/provision-preflight.js';
+import { readProvisionState, readVaultLink } from '../lib/provision-state.js';
+import { createVaultClient } from '../lib/vault-api.js';
 import { pushEnvPlan, vercelProjectPath, VercelApiError, } from '../lib/vercel-env.js';
 // Re-exported so existing importers (and `cli/tests/unit/env-push.test.ts`) keep
 // resolving PROVISION_OWNED from this module after it moved to `lib/env-file.js`.
@@ -110,7 +112,59 @@ function readProjectLink(rootDir) {
     }
     return { projectId, teamId };
 }
-export async function runEnvPush(flags, rootDir = process.cwd()) {
+const VERCEL_SYNC_ROLES = ['vercel-production', 'vercel-preview'];
+/**
+ * The {@link VaultVercelSyncStatus} of the repo, read with the existing state reader and
+ * tolerating its absence or another shape (never throws — it only shapes a message).
+ */
+export function readVaultVercelSyncStatus(rootDir) {
+    let state;
+    try {
+        state = readProvisionState(rootDir);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (!state)
+        return 'unknown';
+    const syncs = state.syncs;
+    const recorded = VERCEL_SYNC_ROLES.every((role) => Boolean(syncs?.ids?.[role]));
+    const pending = VERCEL_SYNC_ROLES.some((role) => syncs?.pending?.includes(role));
+    return recorded && !pending ? 'active' : 'pending';
+}
+/**
+ * What `env push` says in a repo linked to the vault instead of writing (SYNC-002). The vault's
+ * syncs are the ONLY writer of Vercel there (`fx-secrets-vault §7`, "un solo escritor por
+ * destino"): a second writer would leave the destination with whichever value landed last. Names
+ * the vault project and the environments from the block — ids only, never a value. It only claims
+ * the sync carries the value to Vercel when the state records both Vercel syncs; otherwise it
+ * says they are not confirmed and points at `factory provision --resume`, which creates them.
+ */
+export function vaultPushCessionMessage(link, syncs = 'active') {
+    const where = `(proyecto ${link.projectId}, entorno ${link.envs.main} → production, ` +
+        `${link.envs.develop} → preview)`;
+    const delivery = syncs === 'active'
+        ? 'el sync lo lleva a Vercel y aplica en el siguiente deploy. '
+        : syncs === 'pending'
+            ? 'pero los syncs de la bóveda hacia Vercel están pendientes o no están registrados en ' +
+                '`.timekast/provision.json`, así que el valor no llega a Vercel hasta que existan: corre ' +
+                '`factory provision --resume` para crearlos. '
+            : 'pero `.timekast/provision.json` no registra los syncs de la bóveda hacia Vercel, así que ' +
+                'no puedo confirmar que el valor llegue: revisa los syncs del proyecto en la bóveda. ';
+    return ('Este repo usa la bóveda: sus variables llegan a Vercel por sincronización y env push no ' +
+        `escribe ahí. Cambia el valor en la bóveda ${where}; ${delivery}` +
+        'No se envió nada a Vercel.');
+}
+export async function runEnvPush(flags, rootDir = process.cwd(), deps = {}) {
+    // SYNC-002: FIRST, before `.env.local`, the per-env registry or the inline-marker abort. In a
+    // vault repo none of those matter — nothing is written, `--dry-run` included — so a broken
+    // registry must not mask the real answer. Fail-closed: a malformed block throws (never "no
+    // vault", which would make this command the second writer it must not be).
+    const vaultLink = readVaultLink(rootDir);
+    if (vaultLink) {
+        console.log(vaultPushCessionMessage(vaultLink, readVaultVercelSyncStatus(rootDir)));
+        return;
+    }
     const body = readEnvBody(path.join(rootDir, '.env.local'));
     // Resolve the derivative's per-environment declaration BEFORE anything can reach
     // Vercel: a present-but-broken registry throws here and aborts the whole run
@@ -195,11 +249,8 @@ export async function runEnvPush(flags, rootDir = process.cwd()) {
         return;
     }
     const { projectId, teamId } = readProjectLink(rootDir);
-    const token = readVercelToken(defaultEnvPath());
-    if (!token) {
-        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`. ' +
-            'Corre `factory secrets <archivo>` para bajar el token y reintenta.');
-    }
+    // Read only on a real push: `--dry-run` returned above without touching the vault.
+    const token = await readVercelToken(deps.rail ?? defaultRail());
     try {
         const result = await pushEnvPlan(projectId, token, teamId, plan);
         console.log(`✔ env push: ${result.created.length} creadas, ${result.updated.length} actualizadas ` +
@@ -210,6 +261,10 @@ export async function runEnvPush(flags, rootDir = process.cwd()) {
     }
     catch (error) {
         if (error instanceof VercelApiError) {
+            if (error.status === 401) {
+                throw new CLIError('El `VERCEL_TOKEN` del rail es inválido o expiró (Vercel respondió 401 al subir las variables).\n' +
+                    railTokenRejectedHint('VERCEL_TOKEN'));
+            }
             throw new CLIError(`Vercel rechazó el push de env: ${error.message}`);
         }
         throw error;
@@ -272,6 +327,19 @@ async function readStdinJson() {
         chunks.push(chunk);
     return Buffer.concat(chunks).toString('utf8');
 }
+/**
+ * The repo's vault project when `.timekast/provision.json` has a `vault` block, else `null` —
+ * the switch between the vault path and the historical `.env.local` path of every wizard
+ * command. Fail-closed: an unreadable state file throws instead of falling back to the file.
+ */
+export function wizardVaultTarget(rootDir, deps = {}) {
+    const link = readVaultLink(rootDir);
+    if (!link)
+        return null;
+    return { client: deps.vaultClient ?? createVaultClient(), projectId: link.projectId, link };
+}
+/** Said after a wizard write in a vault repo, instead of offering `env:push`. */
+export const VAULT_DEPLOYS_NOTICE = 'ℹ️  En un repo con bóveda, los despliegues reciben estos valores desde la bóveda: no uso `env:push`.';
 /**
  * `factory env wizard --apply [--push]` — read `{ answers, push? }` JSON from
  * stdin, write the answers to `.env.local`, and optionally push product vars.
@@ -286,6 +354,25 @@ export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {
         throw new CLIError('Esperaba JSON `{ "answers": { KEY: "value" }, "push"?: bool }` por stdin.');
     }
     const answers = parsed.answers ?? {};
+    const shouldPush = flags.push || parsed.push === true;
+    // VAULT-002: a repo in the vault gets the answers there (one copy in `main:/`, referenced
+    // from `develop:/` and `local`) — never a `.env.local`, and never `env:push`.
+    const vault = wizardVaultTarget(rootDir, deps);
+    if (vault) {
+        const { written, empty } = await applyWizardAnswersToVault(vault, answers);
+        console.log(`✔ Escribí ${written.length} variable(s) en la bóveda (main:/, referenciadas desde develop:/ y local)` +
+            (written.length > 0 ? `: ${written.join(', ')}.` : '.'));
+        if (empty.length > 0)
+            console.log(`  (sin valor, no se guardan: ${empty.join(', ')})`);
+        for (const w of checkEnvCompleteness(await readVaultLocalEnv(vault)))
+            console.log(`⚠ ${w}`);
+        // SYNC-002: a requested push answers with the cession (the vault's sync is Vercel's only
+        // writer) instead of reaching `runEnvPush` — the wizard ends cleanly, nothing is sent.
+        console.log(shouldPush
+            ? vaultPushCessionMessage(vault.link, readVaultVercelSyncStatus(rootDir))
+            : VAULT_DEPLOYS_NOTICE);
+        return;
+    }
     const written = applyWizardAnswers(rootDir, answers);
     console.log(`✔ Escribí ${written.length} variable(s) en \`.env.local\`.`);
     // Completeness guards (OAuth creds, VAPID) — warn, never block the write. Read
@@ -293,7 +380,6 @@ export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {
     const finalEnv = parseEnvBody(readFileSync(path.join(rootDir, '.env.local'), 'utf8'));
     for (const w of checkEnvCompleteness(finalEnv))
         console.log(`⚠ ${w}`);
-    const shouldPush = flags.push || parsed.push === true;
     if (!shouldPush) {
         console.log('ℹ️  Para subirlas a Vercel cuando quieras: `pnpm env:push`.');
         return;
@@ -309,7 +395,12 @@ export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {
  * the dev at the end (the agent NEVER echoes a raw secret) — the dev opens
  * `.env.local` to see the full values.
  */
-export function runEnvWizardReview(flags, rootDir = process.cwd()) {
+export function runEnvWizardReview(flags, rootDir = process.cwd(), deps = {}) {
+    // VAULT-002: in a vault repo the review resolves the `local` environment (own values + the
+    // `develop:/ci` import + references) — there is no `.env.local` to read or to send the dev to.
+    const vault = wizardVaultTarget(rootDir, deps);
+    if (vault)
+        return runEnvWizardReviewFromVault(flags, rootDir, vault);
     const localPath = path.join(rootDir, '.env.local');
     if (!existsSync(localPath)) {
         throw new CLIError('No encontré `.env.local`. Corre el wizard (`factory env wizard`) primero.');
@@ -317,13 +408,18 @@ export function runEnvWizardReview(flags, rootDir = process.cwd()) {
     const body = readFileSync(localPath, 'utf8');
     const answers = parseEnvBody(body);
     const questions = planWithProvisionDefaults(rootDir).filter((q) => isQuestionActive(q, answers));
-    const rows = buildEnvReview(questions, body);
-    const warnings = checkEnvCompleteness(answers);
+    const printed = printEnvReview(flags, 'Configuración de `.env.local` (los secretos van enmascarados):\n', buildEnvReview(questions, body), checkEnvCompleteness(answers));
+    if (printed) {
+        console.log('\nAbre `.env.local` para ver los valores completos (de un secreto solo se ven sus últimos 4).');
+    }
+}
+/** Print the review rows + warnings (shared by the file path and the vault path). */
+function printEnvReview(flags, title, rows, warnings) {
     if (flags.json) {
         process.stdout.write(`${JSON.stringify({ rows, warnings }, null, 2)}\n`);
-        return;
+        return false;
     }
-    console.log('Configuración de `.env.local` (los secretos van enmascarados):\n');
+    console.log(title);
     let section = '';
     for (const row of rows) {
         if (row.section !== section) {
@@ -338,14 +434,28 @@ export function runEnvWizardReview(flags, rootDir = process.cwd()) {
         for (const w of warnings)
             console.log(`  ⚠ ${w}`);
     }
-    console.log('\nAbre `.env.local` para ver los valores completos (de un secreto solo se ven sus últimos 4).');
+    return true;
+}
+/** `--review` over the vault's `local` environment (VAULT-002). Same masking rule. */
+async function runEnvWizardReviewFromVault(flags, rootDir, vault) {
+    const env = await readVaultLocalEnv(vault);
+    const questions = planWithProvisionDefaults(rootDir).filter((q) => isQuestionActive(q, env));
+    const printed = printEnvReview(flags, 'Configuración del entorno `local` de la bóveda (los secretos van enmascarados):\n', buildEnvReviewFromEnv(questions, env), checkEnvCompleteness(env));
+    if (printed) {
+        console.log('\nLos valores completos viven en la bóveda (entorno `local`); de un secreto aquí solo se ven sus últimos 4.');
+    }
 }
 /**
  * `factory env wizard --gen-vapid` — generate a VAPID keypair and write it to
  * `.env.local`. The private key is a SECRET: it is written to the file (0600) and
  * NEVER printed. The public key is public by design, so it is safe to echo.
  */
-export function runEnvWizardGenVapid(rootDir = process.cwd()) {
+export function runEnvWizardGenVapid(rootDir = process.cwd(), deps = {}) {
+    // VAULT-002: in a vault repo the three keys go to the vault (one copy in `main:/`, referenced
+    // from `develop:/` and `local`) — never to a file. The private key is never printed.
+    const vault = wizardVaultTarget(rootDir, deps);
+    if (vault)
+        return genVapidIntoVault(vault);
     const localPath = path.join(rootDir, '.env.local');
     const examplePath = path.join(rootDir, '.env.example');
     const basePath = existsSync(localPath) ? localPath : examplePath;
@@ -371,3 +481,21 @@ export function runEnvWizardGenVapid(rootDir = process.cwd()) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }
+/**
+ * `--gen-vapid` in a vault repo (VAULT-002): the keypair is upserted (a new pair per run, as on
+ * the file path) and `VAPID_SUBJECT` is seeded only when missing, from `main:/EMAIL_FROM`.
+ */
+async function genVapidIntoVault(vault) {
+    const { publicKey, privateKey } = generateVapidKeys();
+    await writeSharedToVault(vault, { NEXT_PUBLIC_VAPID_PUBLIC_KEY: publicKey, VAPID_PRIVATE_KEY: privateKey }, 'upsert');
+    const main = await readVaultMain(vault);
+    const subjectMissing = !main['VAPID_SUBJECT'];
+    const from = main['EMAIL_FROM'];
+    await writeSharedToVault(vault, { VAPID_SUBJECT: from ? `mailto:${from}` : 'mailto:admin@example.com' }, 'create-if-missing');
+    console.log('✔ Llaves VAPID generadas y escritas en la bóveda (main:/, referenciadas desde develop:/ y local; ' +
+        'la privada queda oculta).');
+    console.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY=${publicKey}`);
+    if (subjectMissing && !from) {
+        console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
+    }
+}

package/dist/commands/invite-admin.js

@@ -4,12 +4,23 @@
  * Replaces the old `SUPER_ADMIN_*` seed. The actual minting lives in the kit
  * script `scripts/tools/invite-admin.ts` (it needs the kit's `@/lib/invites` +
  * `@/lib/email`, which this CLI must not import). This command's only job is to
- * resolve the TARGET branch's connection string from `.env.local` and spawn that
- * script with it:
+ * resolve the TARGET branch's environment and spawn that script with it.
+ *
+ * Repo WITHOUT a vault (no `vault` block in `.timekast/provision.json`) → `.env.local`:
  *
  *   - `--target develop` (default) → `DATABASE_URL`     (the develop branch)
  *   - `--target main`              → `DATABASE_URL_MAIN` (production)
  *
+ * Repo WITH a vault (VAULT-003, Decision 20) → the vault, read directly with the client of
+ * `vault-api.ts` and the person's session (no local wrapper, so it also works through `npx`).
+ * The whole environment goes to the script in memory — not only `DATABASE_URL`, also the mail
+ * provider and the app URL it used to take from `.env.local`:
+ *
+ *   - `--target main`    → `main:/` with `main:/ci` on top (`/ci` wins: the DIRECT string of main)
+ *   - `--target develop` → `local` (its own `DATABASE_URL` is the direct string of develop — ADR-005)
+ *
+ * With a vault, `.env.local` and `DATABASE_URL_MAIN` are never read.
+ *
  * `--target main` is consumed by SETUP-002 after the first deploy+migrate; the
  * accept link must point at production, so pass `--app-url=https://...` there.
  *
@@ -20,6 +31,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { execa } from 'execa';
 import { CLIError } from '../lib/cli-error.js';
+import { readVaultLink } from '../lib/provision-state.js';
+import { VAULT_CI_PATH, VAULT_ROOT_PATH, createVaultClient, } from '../lib/vault-api.js';
 /** Map a target branch to the `.env.local` var holding its connection string. */
 export const TARGET_DB_VAR = {
     develop: 'DATABASE_URL',
@@ -88,6 +101,20 @@ export function readEnvLocalVar(rootDir, key) {
     }
     return null;
 }
+/**
+ * Read the target's environment from the vault (ADR-005 layout). References are expanded and
+ * `local`'s import of `develop:/ci` is flattened (own values win) — the same view `infisical
+ * export` gives the local wrapper.
+ */
+export async function readTargetFromVault(link, target, vault) {
+    const read = { expandReferences: true, includeImports: true };
+    if (target === 'main') {
+        const root = await vault.readSecrets(link.projectId, { env: link.envs.main, path: VAULT_ROOT_PATH }, read);
+        const ci = await vault.readSecrets(link.projectId, { env: link.envs.main, path: VAULT_CI_PATH }, read);
+        return new Map([...root, ...ci]);
+    }
+    return vault.readSecrets(link.projectId, { env: link.envs.local, path: VAULT_ROOT_PATH }, read);
+}
 export async function runInviteAdmin(flags, rootDir = process.cwd(), deps = {}) {
     if (!flags.email) {
         throw new CLIError('Falta el email. Uso: `factory invite-admin --email=you@example.com [--target develop|main]`.');
@@ -96,25 +123,19 @@ export async function runInviteAdmin(flags, rootDir = process.cwd(), deps = {})
         throw new CLIError(`No encontré \`${INVITE_ADMIN_SCRIPT}\`. Corre \`factory update\` para traer el ` +
             'script del kit antes de invitar al admin.');
     }
-    // Resolve the target branch's connection string. develop is the local default
-    // (the script's own dotenv loads DATABASE_URL from .env.local), but we resolve
-    // it anyway to fail early with a clear message; for main we MUST override.
-    const dbVar = TARGET_DB_VAR[flags.target];
-    const dbUrl = readEnvLocalVar(rootDir, dbVar);
-    if (!dbUrl) {
-        throw new CLIError(`No encontré \`${dbVar}\` en \`.env.local\` (target: ${flags.target}). ` +
-            'Corre `/provision` (o `factory provision`) para escribir las connection strings.');
-    }
-    const env = { ...process.env, DATABASE_URL: dbUrl };
+    const link = readVaultLink(rootDir);
+    const env = link
+        ? await vaultEnvironment(link, flags.target, deps.vault ?? createVaultClient())
+        : envLocalEnvironment(rootDir, flags.target);
     // For main the accept link must point at production, not localhost — the
     // caller (SETUP-002) passes the deployed domain via --app-url.
     if (flags.appUrl)
         env.NEXT_PUBLIC_APP_URL = flags.appUrl;
     console.log(`→ Creando invitación de super_admin (${flags.target}) para ${flags.email}…`);
     // `pnpm exec tsx` resolves the kit's local tsx (a devDependency) — same
-    // package-manager assumption provision already makes (`pnpm install`). The
-    // script reads .env.local for the rest of its config (email provider, app URL)
-    // and uses the DATABASE_URL we pass for the chosen branch.
+    // package-manager assumption provision already makes (`pnpm install`). Without a
+    // vault the script reads .env.local for the rest of its config (email provider,
+    // app URL); with one, all of it arrives in `env` and there is no file to read.
     const run = deps.run ?? ((file, args, options) => execa(file, args, { ...options, stdio: 'inherit' }));
     try {
         await run('pnpm', ['exec', 'tsx', INVITE_ADMIN_SCRIPT, `--email=${flags.email}`], {
@@ -126,3 +147,29 @@ export async function runInviteAdmin(flags, rootDir = process.cwd(), deps = {})
         throw new CLIError('El script `invite-admin` falló. Revisa la salida de arriba.');
     }
 }
+/** Without a vault: the target's connection string from `.env.local` (today's behavior). */
+function envLocalEnvironment(rootDir, target) {
+    // develop is the local default (the script's own dotenv loads DATABASE_URL from
+    // .env.local), but we resolve it anyway to fail early with a clear message; for
+    // main we MUST override.
+    const dbVar = TARGET_DB_VAR[target];
+    const dbUrl = readEnvLocalVar(rootDir, dbVar);
+    if (!dbUrl) {
+        throw new CLIError(`No encontré \`${dbVar}\` en \`.env.local\` (target: ${target}). ` +
+            'Corre `/provision` (o `factory provision`) para escribir las connection strings.');
+    }
+    return { ...process.env, DATABASE_URL: dbUrl };
+}
+/**
+ * With a vault: the whole environment of the target, in memory. The vault wins over the
+ * parent environment (a stale `DATABASE_URL` exported in the shell must not reach production).
+ */
+async function vaultEnvironment(link, target, vault) {
+    const values = await readTargetFromVault(link, target, vault);
+    if (!values.get('DATABASE_URL')) {
+        const where = target === 'main' ? `${link.envs.main}:/ci` : `${link.envs.local}:/`;
+        throw new CLIError(`La bóveda no tiene \`DATABASE_URL\` en \`${where}\` (target: ${target}). ` +
+            'Revisa el proyecto de la bóveda del repo (`fx-secrets-vault §7`).');
+    }
+    return { ...process.env, ...Object.fromEntries(values) };
+}