@timekast/factory 1.26.0 → 1.27.0

package/dist/commands/doctor.js

@@ -13,8 +13,9 @@
  *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
  *     update, not yet available).
  *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
- *     generated `.sql`, so its `vercel-build` (`pnpm db:migrate && pnpm build`)
- *     would migrate an empty database. INFORMATIONAL — see below.
+ *     generated `.sql`, so its `vercel-build` (`pnpm build && pnpm db:migrate`)
+ *     has nothing to apply and its first deploy never creates the tables.
+ *     INFORMATIONAL — see below.
  *
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
@@ -65,8 +66,8 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
  */
 export const MISSING_INITIAL_MIGRATION_NOTICE = `⚠ Falta la migración inicial: hay schema en \`${SCHEMA_DIR}/\` y ningún \`.sql\` en ` +
     `\`${MIGRATIONS_DIR}/\`.\n` +
-    '  El deploy corre `pnpm db:migrate && pnpm build`, así que el primer build migraría una ' +
-    'base vacía. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
+    '  El deploy corre `pnpm build && pnpm db:migrate`, así que el primer deploy no crearía ' +
+    'ninguna tabla. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
     'deploy.\n' +
     '  (Aviso informativo: `factory doctor` no bloquea — sale con éxito de todos modos.)';
 /** Parse `doctor`'s argv slice into flags. Unknown flags are ignored. */

package/dist/commands/env.js

@@ -13,7 +13,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
-import { PROVISION_OWNED, setEnvLine } from '../lib/env-file.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';
@@ -30,23 +30,40 @@ export const REDEPLOY_NOTICE = 'ℹ️  Las variables aplican en el próximo dep
 export function parseEnvPushFlags(argv) {
     return { dryRun: argv.includes('--dry-run') };
 }
+/** No extra exclusions — the common case (the derivative declared nothing). */
+const NO_PER_ENV_KEYS = new Set();
 /**
- * Parse `.env.local` into the product vars to push: skip comments/blanks, the
- * provision-owned keys, and empty values. First-`=` split; surrounding quotes
- * stripped (mirrors the rail reader in provision.ts).
+ * Read `.env.local` as text, or `''` when it is absent or unreadable.
+ *
+ * Fail-SAFE on purpose, and the polarity is the opposite of `readPerEnvRegistry`:
+ * this file is the source of VALUES, so an empty body means "there is nothing to
+ * push" — the harmless direction. The registry is the source of EXCLUSIONS, where
+ * an empty result would mean "push everything", so it throws instead. Do NOT
+ * copy this `catch` over there.
  */
-export function readProductVars(filePath) {
-    const out = {};
+function readEnvBody(filePath) {
     if (!existsSync(filePath))
-        return out;
-    let text;
+        return '';
     try {
-        text = readFileSync(filePath, 'utf8');
+        return readFileSync(filePath, 'utf8');
     }
     catch {
-        return out;
+        return '';
     }
-    for (const line of text.split('\n')) {
+}
+/**
+ * Parse an `.env.local` body into the product vars to push: skip comments/blanks,
+ * the provision-owned keys, the per-environment keys the derivative declared, and
+ * empty values. First-`=` split; surrounding quotes stripped (mirrors the rail
+ * reader in provision.ts).
+ *
+ * `perEnvKeys` only ever SUBTRACTS from the push — it is applied ALONGSIDE
+ * `PROVISION_OWNED` (a union), never instead of it, so a derivative cannot name a
+ * provision-owned key to opt it back in.
+ */
+export function parseProductVars(body, perEnvKeys = NO_PER_ENV_KEYS) {
+    const out = {};
+    for (const line of body.split('\n')) {
         const trimmed = line.trimStart();
         if (trimmed === '' || trimmed.startsWith('#'))
             continue;
@@ -54,7 +71,7 @@ export function readProductVars(filePath) {
         if (eq === -1)
             continue;
         const key = line.slice(0, eq).trim();
-        if (key === '' || PROVISION_OWNED.has(key))
+        if (key === '' || PROVISION_OWNED.has(key) || perEnvKeys.has(key))
             continue;
         let value = line.slice(eq + 1).replace(/\s+$/, '');
         if (value.length >= 2 &&
@@ -68,6 +85,10 @@ export function readProductVars(filePath) {
     }
     return out;
 }
+/** {@link parseProductVars} over the file at `filePath`. */
+export function readProductVars(filePath, perEnvKeys = NO_PER_ENV_KEYS) {
+    return parseProductVars(readEnvBody(filePath), perEnvKeys);
+}
 /** Read `{ projectId, teamId }` from `.vercel/project.json` (written by provision). */
 function readProjectLink(rootDir) {
     const file = vercelProjectPath(rootDir);
@@ -90,13 +111,65 @@ function readProjectLink(rootDir) {
     return { projectId, teamId };
 }
 export async function runEnvPush(flags, rootDir = process.cwd()) {
-    const productVars = readProductVars(path.join(rootDir, '.env.local'));
+    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
+    // (`--dry-run` included), instead of showing a plan as if nothing were protected.
+    const registry = readPerEnvRegistry(rootDir);
+    const marked = findPerEnvMarkedKeys(body);
+    const pendingAdds = marked.filter((key) => !registry.keys.includes(key));
+    // Reconciliation: a marker the registry lacks is APPENDED to it (add-only — see
+    // `addToPerEnvRegistry`). `--dry-run` reports it and writes nothing.
+    if (pendingAdds.length > 0 && !flags.dryRun) {
+        addToPerEnvRegistry(rootDir, registry, pendingAdds);
+    }
+    // Protected = registry ∪ marker ∪ PROVISION_OWNED. A union, never a replacement:
+    // the derivative's declaration can only SUBTRACT variables from the push.
+    const perEnvKeys = new Set([...registry.keys, ...marked]);
+    const productVars = parseProductVars(body, perEnvKeys);
     const keys = Object.keys(productVars).sort();
-    if (keys.length === 0) {
-        console.log('No hay variables de producto que subir en `.env.local` ' +
-            '(todo es provision-owned o está vacío).');
-        return;
+    const envKeys = listEnvKeys(body);
+    const omittedProvisionOwned = envKeys.filter((key) => PROVISION_OWNED.has(key)).sort();
+    // Provision-owned wins the label, so a redundant declaration is listed ONCE.
+    const omittedPerEnv = envKeys
+        .filter((key) => perEnvKeys.has(key) && !PROVISION_OWNED.has(key))
+        .sort();
+    const declaredButAbsent = [...perEnvKeys].filter((key) => !envKeys.includes(key)).sort();
+    if (pendingAdds.length > 0) {
+        const names = pendingAdds.join(', ');
+        console.log(flags.dryRun
+            ? `ℹ️  Agregaría a \`${PER_ENV_REGISTRY_FILE}\` por el marcador ` +
+                `\`${PER_ENV_MARKER}\`: ${names} (--dry-run: no escribí nada).`
+            : `✔ Agregué a \`${PER_ENV_REGISTRY_FILE}\` (marcador \`${PER_ENV_MARKER}\`): ${names}.`);
+    }
+    // 🔴 An INLINE marker ABORTS, it does not warn. Warning and pushing anyway shipped a value the
+    // code had ALREADY PROVEN corrupt: `parseProductVars` splits on the first `=` and strips no
+    // inline comment, so `KEY="x" # @per-env` uploads the literal `"x" # @per-env`. Aborting is
+    // exactly as loud as the warning — the dev sees the wrong form and fixes it — and it is the
+    // only option that also protects. Filtered to keys the registry does NOT already cover: for a
+    // protected one the diagnosis would be false (it does not go up at all), and a message that
+    // sometimes lies trains everyone to skip reading it.
+    const inlineMarked = findInlinePerEnvMarkers(body).filter((key) => !perEnvKeys.has(key));
+    if (inlineMarked.length > 0) {
+        throw new CLIError(`${inlineMarked.map((key) => `\`${key}\``).join(', ')} lleva \`${PER_ENV_MARKER}\` en la MISMA ` +
+            'línea de la asignación. Ahí no protege nada, y además el valor subiría con el comentario ' +
+            'pegado (a Vercel llegaría el texto literal, comillas incluidas).\n' +
+            `  El marcador va en un comentario en la línea de ARRIBA (\`SK.md §7.2\`). Aborté el push.`);
+    }
+    for (const key of declaredButAbsent) {
+        console.log(`⚠ \`${key}\` está declarada por ambiente pero no aparece en \`.env.local\` ` +
+            '— revisa si es un typo: así no está protegiendo nada.');
     }
+    /** Names + reason, NEVER values: the omitted vars are the secret-bearing ones. */
+    const printOmitted = () => {
+        if (omittedProvisionOwned.length === 0 && omittedPerEnv.length === 0)
+            return;
+        console.log('\nOmitidas (no se envían):');
+        for (const key of omittedProvisionOwned)
+            console.log(`  ${key} — provision-owned`);
+        for (const key of omittedPerEnv)
+            console.log(`  ${key} — declarada por ambiente`);
+    };
     const targets = ['production', 'preview'];
     const plan = keys.map((key) => ({
         key,
@@ -104,12 +177,23 @@ export async function runEnvPush(flags, rootDir = process.cwd()) {
         target: targets,
     }));
     if (flags.dryRun) {
-        console.log(`Plan (${plan.length} vars → production, preview):`);
-        for (const key of keys)
-            console.log(`  ${key}`);
+        if (keys.length === 0) {
+            console.log('No hay variables de producto que subir en `.env.local`.');
+        }
+        else {
+            console.log(`Plan (${plan.length} vars → production, preview):`);
+            for (const key of keys)
+                console.log(`  ${key}`);
+        }
+        printOmitted();
         console.log('\n(--dry-run: nada se envió a Vercel.)');
         return;
     }
+    if (keys.length === 0) {
+        console.log('No hay variables de producto que subir en `.env.local` ' +
+            '(todo es provision-owned, está declarado por ambiente, o está vacío).');
+        return;
+    }
     const { projectId, teamId } = readProjectLink(rootDir);
     const token = readVercelToken(defaultEnvPath());
     if (!token) {
@@ -219,9 +303,11 @@ export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {
 }
 /**
  * `factory env wizard --review [--json]` — a secret-safe summary of the resolved
- * `.env.local`. Non-secret values are shown; secret values are masked; empty ones
- * are flagged. This is what the guided flow shows the dev at the end (the agent
- * NEVER echoes raw secrets) — the dev opens `.env.local` to see the full values.
+ * `.env.local`. Non-secret values are shown; secret values are masked down to their
+ * last four characters, enough to tell WHICH value is in place while rotating and
+ * useless on their own; empty ones are flagged. This is what the guided flow shows
+ * 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()) {
     const localPath = path.join(rootDir, '.env.local');
@@ -252,7 +338,7 @@ 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 (los secretos no se imprimen).');
+    console.log('\nAbre `.env.local` para ver los valores completos (de un secreto solo se ven sus últimos 4).');
 }
 /**
  * `factory env wizard --gen-vapid` — generate a VAPID keypair and write it to

package/dist/commands/provision.js

@@ -1245,7 +1245,7 @@ export function writeE2eWorkflow(rootDir) {
  * PROV-004 — the `github` step: build the git substrate, create the Vercel PROJECT,
  * connect the GitHub repo (GitHub App gate), confirm `productionBranch: main`,
  * write `.vercel/project.json`, and activate the E2E workflow. Migrations run in the
- * Vercel build (`vercel-build`: `pnpm db:migrate && pnpm build`), NOT a GitHub Actions
+ * Vercel build (`vercel-build`: `pnpm build && pnpm db:migrate`), NOT a GitHub Actions
  * workflow. HIGH-risk: every failure is recoverable via `--resume`.
  *
  * Order (asserted by the unit test): git substrate (rename → remote add → push
@@ -1334,7 +1334,7 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
     //    the template is absent. It lands in the working tree and is committed below.
     //
     //    Migrations are NOT a GitHub Actions workflow: they run in the Vercel build
-    //    (`vercel-build`: `pnpm db:migrate && pnpm build`, shipped in package.json),
+    //    (`vercel-build`: `pnpm build && pnpm db:migrate`, shipped in package.json),
     //    so every deployment migrates ITS target's DB (production←main, preview←develop)
     //    before building — no migrate.yml, no Deploy Hook, no manual step.
     const e2e = writeE2eWorkflow(rootDir);
@@ -1367,7 +1367,7 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
  * before provision activated this workflow, so it lives only in the working tree
  * until committed here. (Migrations are not part of THIS commit, but they do have one:
  * `ensureInitialMigration` commits the `0000` earlier in the run, with its own pathspec.
- * The Vercel build only APPLIES it — `vercel-build` runs `pnpm db:migrate && pnpm build`,
+ * The Vercel build only APPLIES it — `vercel-build` runs `pnpm build && pnpm db:migrate`,
  * there is no migration workflow.) Idempotent — when a `--resume`
  * finds it already committed, `git add` stages nothing and the commit/push is skipped.
  */
@@ -1418,7 +1418,7 @@ const INITIAL_MIGRATION_COMMIT = 'chore(db): add the initial database migration'
 const INITIAL_MIGRATION_LABEL = 'Migración inicial de la base (0000 de Drizzle)';
 /**
  * The branch the step commits on and pushes: the one `vercel-build` runs
- * `pnpm db:migrate && pnpm build` from for PRODUCTION. Named, never inlined
+ * `pnpm build && pnpm db:migrate` from for PRODUCTION. Named, never inlined
  * (CODING.md §5) — it appears in the checkout guard, in both pushes and in the
  * remote confirmation, and those four have to mean the same branch.
  */
@@ -1567,7 +1567,7 @@ async function confirmMigrationOnRemote(rootDir, runGit) {
 /**
  * Generate the initial Drizzle migration, commit it with its OWN pathspec and get it to
  * the remote BEFORE Vercel builds the tree (PROV-004 pushes `main`; `vercel-build` runs
- * `pnpm db:migrate && pnpm build`). Without this a fresh derivative deploys against an
+ * `pnpm build && pnpm db:migrate`). Without this a fresh derivative deploys against an
  * empty database.
  *
  * Order and its reasons:
@@ -1706,7 +1706,7 @@ export async function ensureInitialMigration(rootDir, evidence, deps = {}) {
         return;
     }
     // Un `try` por push, y no uno compartido: `main` es el que le importa a producción
-    // (`vercel-build` = `pnpm db:migrate && pnpm build`) y `develop` puede fallar solo
+    // (`vercel-build` = `pnpm build && pnpm db:migrate`) y `develop` puede fallar solo
     // (non-fast-forward con un remoto divergido). Con un `try` compartido, esa falla de
     // `develop` imprimía "no pude pushear la migración" y se saltaba la confirmación —
     // un diagnóstico falso justo cuando `main` SÍ había llegado.
@@ -2233,7 +2233,7 @@ async function resolveDnsToken(route, envPath, headless) {
  * PROV-006 — attach the client's DEFINITIVE domain to the Vercel project, create
  * (or print, for `registrar`) its DNS record, poll Vercel until verified, and on
  * success: retire the interim prod domain (with explicit confirmation), update
- * `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL`, and register the domain in Resend.
+ * `EMAIL_FROM` + `NEXT_PUBLIC_APP_URL`, and register the domain in Resend.
  *
  * Standalone-safe: runnable as a PATCH over an existing provision (the `dns` step
  * of PROV-005 already attached the interim domains) or inside the initial run. It
@@ -2246,7 +2246,7 @@ async function resolveDnsToken(route, envPath, headless) {
  *   - Resend DNS records (BOOT-003) → `ensureDnsRecord` create-or-PATCH (a rotated
  *     DKIM is PATCHed in place, never deleted); a Resend poll timeout is a WARNING
  *     (pending-verification, resumable), never a step failure.
- *   - `AUTH_URL`/`NEXTAUTH_URL` already correct → the upsert PATCH is omitted.
+ *   - `EMAIL_FROM`/`NEXT_PUBLIC_APP_URL` already correct → the upsert PATCH is omitted.
  *
  * On timeout the state is left `clientDomainStatus: pending-verification` (resumable);
  * on success it is `live`.
@@ -2462,7 +2462,7 @@ async function deleteInterimCname(interim, envPath, fetchImpl) {
     }
 }
 /**
- * Update `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL` + `NEXT_PUBLIC_APP_URL` +
+ * Update `EMAIL_FROM` + `NEXT_PUBLIC_APP_URL` +
  * `WEBAUTHN_RP_ID` to the client domain in the Vercel env, per-target and
  * idempotently (PROV-006 §4 + BOOT-004). Lists the existing vars once and upserts
  * each entry via `upsertEnvVar`, which reconciles a key that the substrate left
@@ -2483,20 +2483,27 @@ async function deleteInterimCname(interim, envPath, fetchImpl) {
  * discipline holds).
  */
 async function updateDomainEnv(projectId, token, teamId, domain, deps) {
-    const authUrl = `https://${domain}`;
+    const appOrigin = `https://${domain}`;
     const plan = [
         // EMAIL_FROM uses the dedicated mail subdomain (`updates.<domain>`), NOT the apex
-        // — the apex carries the client's corporate mail. AUTH_URL stays the app domain.
+        // — the apex carries the client's corporate mail.
         {
             key: 'EMAIL_FROM',
             value: `noreply@${mailDomainFor(domain)}`,
             target: ['production', 'preview'],
         },
-        { key: 'AUTH_URL', value: authUrl, target: ['production', 'preview'] },
-        { key: 'NEXTAUTH_URL', value: authUrl, target: ['production', 'preview'] },
-        // Keep the public app origin in lockstep with AUTH_URL once a client domain lands
+        // 🔴 AUTH_URL / NEXTAUTH_URL are DELIBERATELY ABSENT — do not re-add them.
+        // `next-auth/lib/env.js` rewrites the origin of every auth request to their value,
+        // so scoping either to `preview` pins all branch deployments' callbacks to this one
+        // host and kills their sign-in. `trustHost` (auth.config.ts) already infers the
+        // origin per request, which is correct on production AND on each preview.
+        // Auth needs nothing here; the domain reaches the app through NEXT_PUBLIC_APP_URL
+        // below, which is what `getAppUrl()` reads for email links (src/lib/env.ts).
+        // A project that enables OAuth and must pin the callback to a fixed host sets it
+        // manually, `production` only, knowing it forfeits preview sign-in.
+        // Keep the public app origin pointing at the client domain once it lands
         // (the substrate set it to the interim domain in buildEnvPlan; this re-points it).
-        { key: 'NEXT_PUBLIC_APP_URL', value: authUrl, target: ['production', 'preview'] },
+        { key: 'NEXT_PUBLIC_APP_URL', value: appOrigin, target: ['production', 'preview'] },
         // WebAuthn rpID is the registrable HOST, never a URL — the bare domain (BOOT-004).
         // PRODUCTION only: the interim dev domain remains the preview rpID (the dev domain
         // is never retired), so the intentional split pair from buildEnvPlan is preserved.
@@ -2532,7 +2539,7 @@ function printClientDomainPlan(domain, interim, route, confirm) {
     console.log(`  … sondea GET /v9/projects/.../domains/${domain} hasta verified:true (o timeout)`);
     console.log(`  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim} ` +
         `(el dev ${domain}-dev se conserva)`);
-    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · AUTH_URL=https://${domain} · NEXTAUTH_URL=https://${domain} · NEXT_PUBLIC_APP_URL=https://${domain}`);
+    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · NEXT_PUBLIC_APP_URL=https://${domain}`);
     console.log(`  ↻ WEBAUTHN_RP_ID=${domain} (solo production — las passkeys del rpID interino quedan invalidadas; el preview conserva el rpID dev)`);
     console.log(`  ＋ Resend: POST /domains { name: ${mailDomainFor(domain)} } (subdominio mail, no el apex)`);
     if (route === 'registrar') {
@@ -3688,7 +3695,7 @@ export async function runProvision(flags) {
     writeProvisionState(rootDir, runState);
     // 5.0. Initial migration (GAP-001) — BEFORE the steps, so the `.sql` is committed
     //      before the `github` step pushes `main` and Vercel builds the remote tree
-    //      (`vercel-build` = `pnpm db:migrate && pnpm build`). A failed generate/install
+    //      (`vercel-build` = `pnpm build && pnpm db:migrate`). A failed generate/install
     //      aborts here, with nothing pushed and nothing deployed.
     await ensureInitialMigration(rootDir, greenfield);
     for (const step of steps) {