@timekast/factory 1.18.0 → 1.19.0

package/dist/commands/add.js

@@ -85,6 +85,7 @@ export async function runAdd(flags = { core: false, full: false }) {
             mineAll: false,
             resume: false,
             verify: false,
+            dryRun: false,
             commit: false,
             noCommit: false,
             // A legacy `add` redirect is never a beta channel operation.

package/dist/commands/env.js

@@ -21,6 +21,12 @@ import { pushEnvPlan, vercelProjectPath, VercelApiError, } from '../lib/vercel-e
 // 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`.
 export { PROVISION_OWNED };
+/**
+ * Post-push notice: freshly uploaded env vars stay INERT until the next Vercel
+ * deployment (stale-config window — see BOOT-010). Printed only after a
+ * successful push with at least one real change (created or updated).
+ */
+export const REDEPLOY_NOTICE = 'ℹ️  Las variables aplican en el próximo deployment — redeploya el proyecto en Vercel para que tomen efecto.';
 export function parseEnvPushFlags(argv) {
     return { dryRun: argv.includes('--dry-run') };
 }
@@ -114,6 +120,9 @@ export async function runEnvPush(flags, rootDir = process.cwd()) {
         const result = await pushEnvPlan(projectId, token, teamId, plan);
         console.log(`✔ env push: ${result.created.length} creadas, ${result.updated.length} actualizadas ` +
             '(production, preview).');
+        if (result.created.length > 0 || result.updated.length > 0) {
+            console.log(REDEPLOY_NOTICE);
+        }
     }
     catch (error) {
         if (error instanceof VercelApiError) {

package/dist/commands/provision.js

@@ -25,7 +25,7 @@ import { execa } from 'execa';
 import prompts from 'prompts';
 import { FACTORY_ORG } from '../lib/constants.js';
 import { CLIError } from '../lib/cli-error.js';
-import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, ensureCnameRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, } from '../lib/cloudflare-api.js';
+import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, ensureCnameRecord, ensureDnsRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, } from '../lib/cloudflare-api.js';
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { defaultEnvPath, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
 import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, GitHubAppNotInstalledError, linkGitRepo, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, writeVercelProjectJson, } from '../lib/vercel-env.js';
@@ -180,6 +180,21 @@ export function parseVerifyTimeout(raw) {
     }
     return minutes;
 }
+/**
+ * Parse + validate `--repo=<org/name>` (BOOT-001). Absent → `undefined` (the repo
+ * resolution then falls back to the `origin` remote / `FACTORY_ORG/projectName`).
+ * A malformed value (no `/`, more than one `/`, or an empty side) throws a clear
+ * `CLIError` — a corrupt slug must never silently reach the GitHub/Vercel calls.
+ */
+export function parseRepoFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw.split('/');
+    if (parts.length !== 2 || parts.some((part) => part.trim() === '')) {
+        throw new CLIError(`\`--repo\` debe tener el formato \`org/nombre\` (un solo \`/\`; recibí \`${raw}\`).`);
+    }
+    return raw;
+}
 /** Parse `provision`'s argv slice into typed flags. */
 export function parseProvisionFlags(argv) {
     return {
@@ -187,6 +202,7 @@ export function parseProvisionFlags(argv) {
         team: readValueFlag(argv, 'team'),
         orgId: readValueFlag(argv, 'org-id'),
         slug: readValueFlag(argv, 'slug'),
+        repo: parseRepoFlag(readValueFlag(argv, 'repo')),
         domain: readValueFlag(argv, 'domain'),
         dns: parseDnsRoute(readValueFlag(argv, 'dns')),
         verifyTimeout: parseVerifyTimeout(readValueFlag(argv, 'verify-timeout')),
@@ -217,6 +233,11 @@ function buildPlan(services, state) {
 /** Print the plain-text plan (the `--dry-run` and pre-run narration). */
 function printPlan(result) {
     console.log(`Plan de provision para \`${result.projectName}\` (lifecycle: ${result.lifecycle}):`);
+    // BOOT-001: print the RESOLVED repo (--repo → origin → FACTORY_ORG/name), so a
+    // `--dry-run` shows the exact repo the github step / E2E secrets will target.
+    if (result.repo) {
+        console.log(`  Repo de GitHub: ${result.repo}`);
+    }
     for (const step of result.steps) {
         const mark = step.action === 'skip' ? '⏭  (ya completado)' : '＋ crear';
         console.log(`  ${mark}  ${SERVICE_LABEL[step.service]}`);
@@ -405,9 +426,11 @@ function neonErrorToCliError(error, projectName, context) {
 }
 /** The GitHub repo (`owner/name`) the project-scoped secret is pushed to. */
 function neonSecretRepo(state) {
-    // PROV-004 records the created repo in `state.github.repo`; before it runs we
-    // fall back to the canonical `org/projectName` so the secret push is attempted
-    // (a non-existent repo → §8 pending path, never an abort).
+    // `state.github.repo` carries the RESOLVED repo: `runProvision` seeds it before
+    // any step runs (BOOT-001: --repo → origin → FACTORY_ORG/name) and PROV-004
+    // re-records it. The fallback only covers a direct `provisionNeon` call with no
+    // seeded state, so the secret push is still attempted (a non-existent repo →
+    // §8 pending path, never an abort).
     return state.github?.repo ?? `${FACTORY_ORG}/${state.projectName}`;
 }
 /**
@@ -696,10 +719,10 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     // Mint an INDEPENDENT AUTH_SECRET per environment (issue §4 — never shared).
     // POOLED strings → the Vercel runtime DATABASE_URL (serverless/concurrent).
     // WebAuthn rpID = the EXACT host per env (provision's interim domains). A passkey
-    // dies if the rpID changes, so a later custom-domain swap (--domain / PROV-006)
-    // must also re-point WEBAUTHN_RP_ID — tracked as a follow-up. MFA_ENCRYPTION_KEY
-    // is minted independently per env (base64url) so a derivative with MFA enabled
-    // never boots broken (P-1).
+    // dies if the rpID changes, so the custom-domain swap (--domain / PROV-006)
+    // re-points the PRODUCTION WEBAUTHN_RP_ID too (`updateDomainEnv`, BOOT-004).
+    // MFA_ENCRYPTION_KEY is minted independently per env (base64url) so a derivative
+    // with MFA enabled never boots broken (P-1).
     const rpDomains = provisionDomains(state.projectName);
     const plan = buildEnvPlan({
         mainDatabaseUrl: neonSecrets.mainPooled,
@@ -811,6 +834,19 @@ export { writeEnvLocal };
 function repoHttpsUrl(repoSlug) {
     return `https://github.com/${repoSlug}.git`;
 }
+/**
+ * Parse the `owner/name` slug out of a GitHub `origin` URL, HTTPS or SSH
+ * (`https://github.com/Owner/repo[.git]`, `git@github.com:Owner/repo[.git]`,
+ * `ssh://git@github.com/Owner/repo[.git]`). Returns `null` for anything else —
+ * including non-GitHub hosts, deliberately: deriving a slug from a GitLab/other
+ * origin and re-pointing it at `github.com` (see {@link repoHttpsUrl}) would
+ * silently retarget the project, so an unparsable origin falls back to the
+ * historical `FACTORY_ORG/projectName` default instead (BOOT-001).
+ */
+export function parseOriginRepoSlug(originUrl) {
+    const match = /^(?:https:\/\/|ssh:\/\/git@|git@)github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(originUrl.trim());
+    return match ? `${match[1]}/${match[2]}` : null;
+}
 /** Default git runner — `execa` in the derived dir, no shell. */
 async function gitInDir(args, cwd) {
     const { stdout } = await execa('git', args, { cwd });
@@ -831,6 +867,47 @@ async function readOriginUrl(runGit, cwd) {
         return null;
     }
 }
+/**
+ * Resolve the GitHub repo slug (`owner/name`) the `github` step targets (BOOT-001
+ * — decouples the repo from the project slug). Priority:
+ *   1. The repo PERSISTED in the state (a prior run's authority — a `--resume`
+ *      must never silently re-point a repo already in progress; a CONFLICTING
+ *      `--repo` throws instead, mirroring the `--force` discipline of the other
+ *      steps — discard the state with `--force` to start over).
+ *   2. An explicit `--repo=<org/name>` (the dev's stated intent — wins over an
+ *      `origin` pointing elsewhere; the remote is updated via `buildGitSubstrate`'s
+ *      existing same-repo/`--force` flow).
+ *   3. The existing `origin` remote, when it parses as a GitHub repo (a derived
+ *      project whose repo name ≠ slug, or living outside the Factory org).
+ *   4. The historical default `${FACTORY_ORG}/${projectName}` (unchanged behavior
+ *      when there is no flag and no `origin`).
+ */
+export async function resolveRepoSlug(rootDir, projectName, persistedRepo, explicitRepo, runGit) {
+    if (persistedRepo) {
+        // GitHub slugs are case-insensitive — only a REAL divergence is a conflict.
+        if (explicitRepo && explicitRepo.toLowerCase() !== persistedRepo.toLowerCase()) {
+            throw new CLIError(`El estado de provision ya registra el repo \`${persistedRepo}\` (de un run anterior), ` +
+                `distinto de \`--repo=${explicitRepo}\`.\n` +
+                'En `--resume` el estado es la autoridad; usa `--force` para descartarlo y empezar de cero con el repo nuevo.');
+        }
+        return persistedRepo;
+    }
+    if (explicitRepo)
+        return explicitRepo;
+    const fallback = `${FACTORY_ORG}/${projectName}`;
+    const origin = await readOriginUrl(runGit, rootDir);
+    if (origin) {
+        const derived = parseOriginRepoSlug(origin);
+        if (derived) {
+            // An origin at the SAME repo as the canonical default (case drift only, e.g.
+            // `TimeKast/Acme` vs `TimeKast/acme`) keeps the CANONICAL slug, so
+            // `buildGitSubstrate` re-cases the remote exactly as it always did (GitHub
+            // slugs are case-insensitive — reuse that normalization, don't fork it).
+            return derived.toLowerCase() === fallback.toLowerCase() ? fallback : derived;
+        }
+    }
+    return fallback;
+}
 /**
  * Build the git substrate in the documented, asserted ORDER (issue §6):
  *   1. rename `master` → `main` (only when the current branch is `master`)
@@ -870,11 +947,14 @@ async function buildGitSubstrate(rootDir, repoSlug, runGit, force) {
     if (existingOrigin && existingOrigin !== url) {
         // GitHub repo URLs are case-insensitive: an `origin` differing ONLY by case
         // (e.g. `TimeKast/Edmond.git` vs the canonical lowercase `TimeKast/edmond.git`)
-        // points at the SAME repo. Re-case it to the canonical URL silently — no `--force`
-        // needed. A difference BEYOND case is a genuinely different repo → throw unless
-        // `--force` resets it.
-        const sameRepoDifferentCase = existingOrigin.toLowerCase() === url.toLowerCase();
-        if (!sameRepoDifferentCase && !force) {
+        // points at the SAME repo. So does an SSH origin (`git@github.com:Org/name.git`)
+        // whose parsed `owner/name` matches the resolved slug (BOOT-001 — the slug may
+        // have been DERIVED from that very origin). Either way, re-point it to the
+        // canonical HTTPS URL silently — no `--force` needed. A genuinely different
+        // repo → throw unless `--force` resets it.
+        const sameRepo = existingOrigin.toLowerCase() === url.toLowerCase() ||
+            parseOriginRepoSlug(existingOrigin)?.toLowerCase() === repoSlug.toLowerCase();
+        if (!sameRepo && !force) {
             throw new CLIError(`El repo ya tiene un remote \`origin\` apuntando a otro URL (\`${existingOrigin}\` ≠ \`${url}\`).\n` +
                 'Usa `--force` para sobrescribirlo, o limpia el remote si reutilizas este directorio.');
         }
@@ -988,7 +1068,10 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
     }
     const runGit = deps.runGit ?? gitInDir;
     const apiDeps = { fetchImpl: deps.fetchImpl };
-    const repoSlug = `${FACTORY_ORG}/${state.projectName}`;
+    // BOOT-001: the repo is RESOLVED (--repo → existing origin → FACTORY_ORG/name),
+    // no longer hardcoded to `${FACTORY_ORG}/${projectName}`. On resume the persisted
+    // `state.github.repo` is the authority (a conflicting `--repo` throws).
+    const repoSlug = await resolveRepoSlug(rootDir, state.projectName, state.github?.repo, deps.repo, runGit);
     // Record the repo on the state up-front so the Neon secret push (PROV-002) and a
     // `--resume` target it; this is durable even if a later REST step fails.
     state.github = { repo: repoSlug };
@@ -1287,44 +1370,262 @@ async function promptConfirm(message) {
     const { ok } = await prompts({ type: 'confirm', name: 'ok', message, initial: false });
     return ok === true;
 }
+/** The `status` Resend reports once its DNS records validated (the poll's goal). */
+const RESEND_DOMAIN_VERIFIED_STATUS = 'verified';
+/** Shared headers for every Resend REST call (Bearer auth + JSON) — no-echo. */
+function resendHeaders(resendKey) {
+    return {
+        Authorization: `Bearer ${resendKey}`,
+        'Content-Type': 'application/json',
+    };
+}
+/**
+ * Build the FQDN for a record name Resend returns (BOOT-003 §4). Resend hands
+ * record names RELATIVE to the registered domain (`send` → `send.updates.miapp.com`,
+ * `resend._domainkey` → `resend._domainkey.updates.miapp.com`); Cloudflare's
+ * `dns_records` API wants the fully-qualified name. Defensive on shape drift: a
+ * name that already carries the domain (or the apex marker `@`) passes through.
+ */
+export function resendRecordFqdn(name, domain) {
+    if (name === '' || name === '@' || name === domain)
+        return domain;
+    if (name.endsWith(`.${domain}`))
+        return name;
+    return `${name}.${domain}`;
+}
+/**
+ * Look up an existing Resend domain by NAME — `GET /domains` (list) then
+ * `GET /domains/{id}` for its records. This is the `--resume` path (issue §8):
+ * a re-run's `POST /domains` 403s when the domain already exists in THIS account,
+ * so recovering the domain object lets the step re-ensure the DNS records and
+ * re-poll verification instead of dead-ending on a warning. Returns `null` when
+ * the domain is NOT in this account (then it really is "another account" and the
+ * caller keeps the preserved warning behavior — issue §4). Best-effort: any
+ * network/API failure degrades to `null`, never a throw.
+ */
+async function findResendDomain(domain, resendKey, fetchImpl) {
+    try {
+        const listResponse = await fetchImpl(`${RESEND_API_BASE}/domains`, {
+            method: 'GET',
+            headers: resendHeaders(resendKey),
+            signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
+        });
+        if (!listResponse.ok)
+            return null;
+        const list = (await listResponse.json());
+        const match = (list.data ?? []).find((d) => d.name === domain);
+        if (!match?.id)
+            return null;
+        const getResponse = await fetchImpl(`${RESEND_API_BASE}/domains/${match.id}`, {
+            method: 'GET',
+            headers: resendHeaders(resendKey),
+            signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
+        });
+        // Detail fetch failed → still return the id (poll works; records unknown → none created).
+        if (!getResponse.ok)
+            return { id: match.id, name: domain };
+        return (await getResponse.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Trigger Resend's DNS verification for a domain — `POST /domains/{id}/verify`
+ * (BOOT-003 §4). Without this call Resend never starts checking the records and
+ * the domain sits `not_started` forever (the exact bug this issue fixes). Best
+ * effort: a failure here is non-fatal (the poll surfaces the real outcome, and
+ * the step is re-runnable with `--resume`).
+ */
+async function triggerResendVerification(domainId, resendKey, fetchImpl) {
+    try {
+        await fetchImpl(`${RESEND_API_BASE}/domains/${domainId}/verify`, {
+            method: 'POST',
+            headers: resendHeaders(resendKey),
+            signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Non-fatal — the verification poll below reports the actual state.
+    }
+}
+/**
+ * Poll `GET /domains/{id}` until Resend reports `status: verified` or the timeout
+ * budget runs out (BOOT-003 §4) — the Resend sibling of {@link pollDomainVerification},
+ * same injectable `sleep`/`now`/timeout seams so the unit test never waits for real.
+ * Returns `true` once verified; `false` on timeout OR on any network/API failure
+ * (non-fatal either way — the DNS records are already created, Resend keeps
+ * checking them in background, and the step is re-runnable with `--resume`).
+ */
+async function pollResendDomainVerification(domainId, resendKey, deps, fetchImpl) {
+    const sleep = deps.sleep ?? realSleep;
+    const now = deps.now ?? Date.now;
+    const timeoutMs = (deps.verifyTimeoutMin ?? DEFAULT_VERIFY_TIMEOUT_MIN) * 60_000;
+    const intervalMs = VERIFY_POLL_INTERVAL_SEC * 1_000;
+    const deadline = now() + timeoutMs;
+    // First check immediately (the domain may already be verified — idempotent re-run).
+    for (;;) {
+        let status;
+        try {
+            const response = await fetchImpl(`${RESEND_API_BASE}/domains/${domainId}`, {
+                method: 'GET',
+                headers: resendHeaders(resendKey),
+                signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return false;
+            status = (await response.json()).status;
+        }
+        catch {
+            // A failure while POLLING is non-fatal: pending + resumable, never a throw.
+            return false;
+        }
+        if (status === RESEND_DOMAIN_VERIFIED_STATUS)
+            return true;
+        if (now() >= deadline)
+            return false;
+        console.log(`  … esperando verificación del dominio en Resend (reintento en ${VERIFY_POLL_INTERVAL_SEC}s)`);
+        await sleep(intervalMs);
+    }
+}
 /**
- * Register the client domain in Resend — `POST /domains { name }` (PROV-006 §4),
- * reusing the rail's `RESEND_API_KEY`. Idempotency (issue §8): Resend returns an
- * error when the domain is already verified on ANOTHER account; that is a WARNING,
- * not an abort — `EMAIL_FROM` is updated regardless. An absent `RESEND_API_KEY` is
- * also a warning (mail stays unconfigured). No-echo: the key never reaches stdout.
+ * Register the client mail domain in Resend AND make it verifiable end-to-end
+ * (BOOT-003): `POST /domains { name }` with the rail's `RESEND_API_KEY`, then
+ * CREATE the DNS records Resend returns (DKIM/SPF/MX — exactly the ones it
+ * returns, never an assumed fixed set, §8) in the client's Cloudflare zone via
+ * {@link ensureDnsRecord} (create-or-PATCH, idempotent on re-run, never delete),
+ * trigger verification, and poll until `verified` or timeout.
+ *
+ * `dns` carries the zone + token already resolved for the client-domain CNAME
+ * (same org/cliente-cf route); `null` = the `registrar` route (no DNS API — the
+ * records must be created by hand in the Resend dashboard; extending
+ * `printManualRecords` to them is an explicit follow-up, issue §9).
+ *
+ * Non-fatal by design — the domain switch already happened on Vercel:
+ *   - absent `RESEND_API_KEY` → warning (mail stays unconfigured).
+ *   - `POST /domains` rejected → recover the domain from THIS account when it
+ *     exists (`--resume`, §8) or keep the preserved warning ("another account", §4).
+ *   - a record create/PATCH failure → warning; the poll is skipped (it cannot
+ *     succeed with missing records) and the step stays re-runnable.
+ *   - poll timeout → warning + `pending-verification` note, NEVER a hard failure
+ *     (§8 — the records are in place; Resend keeps verifying in background).
+ *
+ * No-echo: the Resend key and Cloudflare token never reach stdout.
  */
-async function registerResendDomain(domain, envPath, fetchImpl) {
+async function registerResendDomain(domain, envPath, deps, fetchImpl, dns) {
     const resendKey = readGateValue('RESEND_API_KEY', envPath);
     if (!resendKey) {
         console.warn('⚠ No hay `RESEND_API_KEY` en `~/.claude/.env` — omito el alta del dominio en Resend ' +
             '(bájala con `factory secrets <archivo>` y reintenta con `--resume`).');
         return;
     }
+    // 1. Register (or recover, on re-run) the domain in Resend.
+    let resendDomain = null;
     try {
         const response = await fetchImpl(`${RESEND_API_BASE}/domains`, {
             method: 'POST',
-            headers: {
-                Authorization: `Bearer ${resendKey}`,
-                'Content-Type': 'application/json',
-            },
+            headers: resendHeaders(resendKey),
             body: JSON.stringify({ name: domain }),
             signal: AbortSignal.timeout(RESEND_API_TIMEOUT_MS),
         });
-        if (!response.ok) {
-            // Already verified elsewhere / validation error → warn + continue (issue §8).
-            console.warn(`⚠ Resend rechazó el alta de \`${domain}\` (status ${response.status}). ` +
-                'Quizá ya está verificado en otra cuenta — `EMAIL_FROM` se actualiza igual; ' +
-                'verifica el dominio a mano en Resend si hace falta.');
-            return;
+        if (response.ok) {
+            resendDomain = (await response.json());
+            console.log(`  ＋ Resend: dominio ${domain} registrado`);
+        }
+        else {
+            // Rejected (e.g. 403 already-exists). If the domain lives in THIS account
+            // (a `--resume` re-run), recover it and continue; otherwise keep the
+            // preserved warning behavior (issue §4) — warn + continue, never abort.
+            const status = response.status;
+            resendDomain = await findResendDomain(domain, resendKey, fetchImpl);
+            if (resendDomain) {
+                console.log(`  ↻ Resend: dominio ${domain} ya registrado en esta cuenta (reuso sus records)`);
+            }
+            else {
+                console.warn(`⚠ Resend rechazó el alta de \`${domain}\` (status ${status}). ` +
+                    'Quizá ya está verificado en otra cuenta — `EMAIL_FROM` se actualiza igual; ' +
+                    'verifica el dominio a mano en Resend si hace falta.');
+                return;
+            }
         }
-        console.log(`  ＋ Resend: dominio ${domain} registrado (verifica los records DNS en Resend)`);
     }
     catch (error) {
         // A network/timeout failure on Resend is non-fatal — the domain switch already
         // happened on Vercel; Resend verification is re-runnable with `--resume`.
         console.warn(`⚠ No se pudo dar de alta \`${domain}\` en Resend (${error?.message ?? 'error'}). ` +
             'Reintenta con `--resume`; `EMAIL_FROM` ya se actualizó.');
+        return;
+    }
+    if (resendDomain.status === RESEND_DOMAIN_VERIFIED_STATUS) {
+        console.log(`  ✔ Resend: dominio ${domain} ya verificado`);
+        return;
+    }
+    // 2. Create the DNS records Resend returned — the ones it RETURNS, no fixed set (§8).
+    if (!dns) {
+        // `registrar` route: no DNS API — the records live in the Resend dashboard and
+        // must be created by hand (printing them here is a follow-up — issue §9).
+        console.warn(`⚠ (registrar) Los records DNS de Resend para \`${domain}\` no se crean automáticamente. ` +
+            'Créalos a mano desde el dashboard de Resend y verifica el dominio ahí.');
+        return;
+    }
+    const records = resendDomain.records ?? [];
+    const cloudflareDeps = { fetchImpl };
+    let allEnsured = true;
+    for (const record of records) {
+        const type = record.type?.toUpperCase();
+        if ((type !== 'TXT' && type !== 'MX') || !record.name || !record.value) {
+            // Only the types Resend requires are supported (issue §9) — anything else
+            // (or a malformed record) is surfaced for manual creation, never guessed.
+            console.warn(`  ⚠ Record de Resend no soportado o incompleto (${record.record ?? record.type ?? '?'}) — créalo a mano en Cloudflare.`);
+            allEnsured = false;
+            continue;
+        }
+        const spec = {
+            type,
+            name: resendRecordFqdn(record.name, domain),
+            content: record.value,
+            ...(record.priority !== undefined ? { priority: record.priority } : {}),
+        };
+        try {
+            const outcome = await ensureDnsRecord(dns.zoneId, spec, dns.token, cloudflareDeps);
+            const mark = outcome === 'created'
+                ? '＋'
+                : outcome === 'updated'
+                    ? '↻ (contenido actualizado)'
+                    : '⏭ (ya estaba)';
+            console.log(`  ${mark} ${spec.type} ${spec.name} (record ${record.record ?? 'DNS'} de Resend)`);
+        }
+        catch (error) {
+            // Non-fatal (the mail path is additive): warn with the actionable mapping
+            // and keep going — the step is re-runnable with `--resume`.
+            allEnsured = false;
+            const detail = error instanceof CloudflareApiError
+                ? cloudflareErrorToCliError(error, `crear el record ${spec.type} \`${spec.name}\``)
+                    .message
+                : (error?.message ?? 'error');
+            console.warn(`  ⚠ No se pudo asegurar el record ${spec.type} \`${spec.name}\`: ${detail}`);
+        }
+    }
+    if (!allEnsured) {
+        console.warn(`⚠ El dominio \`${domain}\` queda pending en Resend (faltaron records DNS). ` +
+            'Corrige lo anterior y reintenta con `--resume`.');
+        return;
+    }
+    // 3. Trigger verification + poll until `verified` or timeout (never a hard fail).
+    if (!resendDomain.id) {
+        console.warn(`⚠ Resend no devolvió un id para \`${domain}\` — no puedo sondear la verificación. ` +
+            'Revisa el dominio en el dashboard de Resend.');
+        return;
+    }
+    await triggerResendVerification(resendDomain.id, resendKey, fetchImpl);
+    const verified = await pollResendDomainVerification(resendDomain.id, resendKey, deps, fetchImpl);
+    if (verified) {
+        console.log(`  ✔ Resend: dominio ${domain} verificado`);
+    }
+    else {
+        // §8: the records ARE created — pending-verification, resumable, never fatal.
+        console.warn(`⚠ El dominio \`${domain}\` quedó pending-verification en Resend (los records DNS ya están; ` +
+            'Resend sigue verificando en background). Reintenta con `--resume` o revisa el dashboard.');
     }
 }
 /** Print the exact DNS records the owner must create for the `--dns=registrar` path. */
@@ -1421,6 +1722,9 @@ async function resolveDnsToken(route, envPath, headless) {
  *   - domain already attached to Vercel (409) → only polls, never re-adds.
  *   - interim retire fails → WARNING, the step is NOT marked failed (interim stays).
  *   - Resend already verified elsewhere → warning + continue.
+ *   - 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.
  *
  * On timeout the state is left `clientDomainStatus: pending-verification` (resumable);
@@ -1456,6 +1760,9 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
         throw error;
     }
     // 2. DNS record: org/cliente-cf CREATE the CNAME; registrar only PRINTS it (§4).
+    //    The resolved zone + token are kept for step 6: the Resend DKIM/SPF/MX records
+    //    live in the SAME client zone (`updates.<domain>` shares the apex — BOOT-003).
+    let resendDns = null;
     if (route === 'registrar') {
         // Print the canonical record now; the poll loop re-prints Vercel's verification.
         printManualRecords(domain, []);
@@ -1474,6 +1781,7 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
             }
             throw error; // resolveZoneIdForName's own CLIError (zone not found) propagates.
         }
+        resendDns = { zoneId, token: cfToken };
         try {
             const cnameOutcome = await ensureCnameRecord(zoneId, domain, cfToken, cloudflareDeps);
             const mark = cnameOutcome === 'created'
@@ -1514,7 +1822,9 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
     // 6. Register the client's MAIL SUBDOMAIN (`updates.<domain>`) in Resend — NOT the
     //    apex, which holds the client's corporate MX/SPF (Google Workspace, M365, …).
     //    Verifying Resend on a dedicated subdomain keeps the client's own mail intact.
-    await registerResendDomain(mailDomainFor(domain), envPath, fetchImpl);
+    //    BOOT-003: also CREATES the DKIM/SPF/MX records Resend returns (in the same
+    //    client zone as the CNAME) and polls until Resend reports `verified`.
+    await registerResendDomain(mailDomainFor(domain), envPath, deps, fetchImpl, resendDns);
     // 7. Record the client domain as LIVE and persist.
     state.dns = {
         ...(state.dns ?? {
@@ -1532,6 +1842,12 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
  * pre-approves; otherwise a TTY prompt asks (headless without `--confirm` → NOT
  * retired). The DEV domain (`{slug}-dev.timekast.mx`) is ALWAYS conserved. A
  * removal failure is a WARNING, never a step failure (issue §8 — interim stays up).
+ *
+ * BOOT-007: once Vercel detaches the interim, its CNAME in the org `timekast.mx`
+ * zone is deleted too — otherwise it stays orphaned, resolving to Vercel's generic
+ * target and serving a 404 forever. The delete lives INSIDE the confirmed block
+ * (a declined prompt never touches Cloudflare) and is SKIPPED when the Vercel
+ * detach failed (the interim is still live — its CNAME must keep resolving).
  */
 async function retireInterimDomain(projectId, token, teamId, state, deps, fetchImpl) {
     const interim = provisionDomains(state.projectName).prod;
@@ -1558,15 +1874,78 @@ async function retireInterimDomain(projectId, token, teamId, state, deps, fetchI
         // the step is NOT marked failed, the dev retires it manually later.
         console.warn(`⚠ No se pudo retirar el dominio interino \`${interim}\` (${error?.message ?? 'error'}).\n` +
             '  Queda activo; retíralo a mano en Vercel o reintenta con `--resume`. El paso NO falla por esto.');
+        // BOOT-007: the interim is still attached to Vercel — its CNAME stays too.
+        return;
     }
     // The DEV domain is intentionally never touched (issue §4 — conserved).
+    // BOOT-007: the interim is off Vercel — delete its now-orphaned CNAME as well.
+    await deleteInterimCname(interim, deps.envPath ?? defaultEnvPath(), fetchImpl);
+}
+/**
+ * Delete the interim CNAME (`{slug}.timekast.mx`) from the org Cloudflare zone
+ * after Vercel detached the domain (BOOT-007). Without this, the record stays
+ * orphaned: it keeps resolving to `cname.vercel-dns.com` while no Vercel project
+ * answers for the host → a 404 forever, dead weight in the `timekast.mx` zone.
+ *
+ * Runs ONLY inside the already-confirmed retire block (a declined prompt never
+ * reaches here). Best-effort by design (issue §4 + §8): EVERY failure — missing
+ * rail token, zone not visible to the token (the `resolveZoneId` CLIError that is
+ * hard in the CREATION path), an out-of-scope token, a 5xx on the DELETE — is a
+ * WARNING, never a step failure; the record stays and the cleanup is retryable.
+ * Idempotent: an already-absent record (`findCnameRecord` → null, or a 404 on the
+ * DELETE) is a narrated no-op. The record content is NOT validated before deleting
+ * (this is a retirement, not a repair — issue §8). The DEV domain's CNAME is never
+ * touched: only the prod interim name is looked up.
+ */
+async function deleteInterimCname(interim, envPath, fetchImpl) {
+    const warnRetryable = (reason) => {
+        console.warn(`⚠ No se pudo borrar el CNAME interino \`${interim}\` en Cloudflare (${reason}).\n` +
+            `  El registro queda en la zona \`${TIMEKAST_ZONE_NAME}\`; bórralo a mano o reintenta. El paso NO falla por esto.`);
+    };
+    const cloudflareToken = readCloudflareApiKey(envPath);
+    if (!cloudflareToken) {
+        warnRetryable('sin `CLOUDFLARE_API_TOKEN` en el rail');
+        return;
+    }
+    const cloudflareDeps = { fetchImpl };
+    try {
+        const zoneId = await resolveZoneId(cloudflareToken, cloudflareDeps);
+        const record = await findCnameRecord(zoneId, interim, cloudflareToken, cloudflareDeps);
+        // Same outcome narration as the Vercel retire above (no-echo — only the
+        // domain NAME prints; the token never crosses this boundary).
+        const outcome = record
+            ? await deleteDnsRecord(zoneId, record.id, cloudflareToken, cloudflareDeps)
+            : 'absent';
+        console.log(outcome === 'absent'
+            ? `  ⏭ (ya no estaba) CNAME interino ${interim} en Cloudflare`
+            : `  － CNAME interino ${interim} borrado de Cloudflare`);
+    }
+    catch (error) {
+        // §8: zone not visible (CLIError) / out-of-scope token / 5xx → warning,
+        // retryable — never the hard CLIError the creation path uses.
+        warnRetryable(error?.message ?? 'error');
+    }
 }
 /**
- * Update `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL` + `NEXT_PUBLIC_APP_URL` to the client domain in the
- * Vercel env, per-target and idempotently (PROV-006 §4). Lists the existing vars
- * once; an `AUTH_URL`/`NEXTAUTH_URL`/`EMAIL_FROM` already set to the target value
- * has its PATCH omitted (issue §8 — second run is a no-op). No-echo: only KEY
- * NAMES + targets print (the values here are public, but the discipline holds).
+ * Update `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL` + `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
+ * SPLIT per target (e.g. `NEXT_PUBLIC_APP_URL` as `['production']` + `['preview']`
+ * from `buildEnvPlan`) into ONE combined-target record (BOOT-002 — a single-record
+ * PATCH would 400 against the sibling). A second run over the reconciled state
+ * re-PATCHes in place: no duplicate records, no 400 (issue §8).
+ *
+ * `WEBAUTHN_RP_ID` is re-pointed for PRODUCTION ONLY: the interim dev domain stays
+ * the preview rpID (the dev domain is never retired — see `retireInterimDomain`),
+ * so `buildEnvPlan`'s intentional split pair is preserved — the single-target plan
+ * only PATCHes the overlapping production record and never touches the preview
+ * sibling (no BOOT-002 400 reintroduced). Changing the rpID invalidates every
+ * passkey registered under the interim rpID and the CLI cannot count them (that
+ * table lives in the derivative's DB), so a warning prints UNCONDITIONALLY.
+ *
+ * No-echo: only KEY NAMES + targets print (the values here are public, but the
+ * discipline holds).
  */
 async function updateDomainEnv(projectId, token, teamId, domain, deps) {
     const authUrl = `https://${domain}`;
@@ -1583,12 +1962,22 @@ async function updateDomainEnv(projectId, token, teamId, domain, deps) {
         // Keep the public app origin in lockstep with AUTH_URL once a client domain 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'] },
+        // 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.
+        { key: 'WEBAUTHN_RP_ID', value: domain, target: ['production'] },
     ];
     const existing = await listEnvVars(projectId, token, teamId, deps);
     for (const entry of plan) {
         const outcome = await upsertEnvVar(projectId, token, teamId, entry, existing, deps);
         console.log(`  ${outcome === 'created' ? '＋' : '↻'} ${entry.key} [${entry.target.join(', ')}]`);
     }
+    // BOOT-004: changing the rpID orphans every passkey registered under the interim
+    // rpID. The CLI cannot query how many exist (that table lives in the derivative's
+    // DB, unreachable from provisioning), so the warning is UNCONDITIONAL.
+    console.warn(`⚠ WEBAUTHN_RP_ID (production) ahora es \`${domain}\`: cualquier passkey registrada ` +
+        'bajo el rpID interino queda invalidada — esos usuarios deben registrar una nueva ' +
+        'passkey en el dominio definitivo.');
 }
 /**
  * Print the resolved client-domain operation tree for `--domain --dry-run`
@@ -1609,7 +1998,14 @@ function printClientDomainPlan(domain, interim, route, confirm) {
     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(`  ↻ 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') {
+        console.log('  · (registrar) los records DNS de Resend (DKIM/SPF/MX) se crean a mano en el dashboard de Resend');
+    }
+    else {
+        console.log(`  ＋ records DNS de Resend (DKIM/SPF/MX, los que devuelva) en la zona ${apexZoneOf(domain)} + sondeo hasta verified`);
+    }
     console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
 }
 /**
@@ -1631,7 +2027,10 @@ async function runServiceStep(service, rootDir, state, flags) {
             // PROV-004: git substrate (rename → remote add → push main) + create the
             // Vercel project + connect git (GitHub App) + PATCH production-branch +
             // .vercel/project.json + activate E2E. Migrations run in vercel-build, not a workflow.
-            await provisionGithubVercel(rootDir, state, flags.team, { force: flags.force });
+            await provisionGithubVercel(rootDir, state, flags.team, {
+                force: flags.force,
+                repo: flags.repo,
+            });
             break;
         case 'dns':
             // PROV-005: attach the interim domains to Vercel (dev → develop, prod →
@@ -2431,6 +2830,16 @@ export async function runProvision(flags) {
     // In patch mode the projectName comes from the loaded state (the interim slug);
     // a fresh run derives it from flags (the scaffold default).
     const projectName = state?.projectName ?? deriveProjectName(flags, rootDir);
+    // BOOT-001: resolve the target GitHub repo ONCE (--repo → existing origin →
+    // FACTORY_ORG/projectName) for every consumer of the slug: the plan/report
+    // (`--dry-run` included), the Neon E2E-secret push (which runs BEFORE the github
+    // step) and the github step itself. Reading the local `origin` is a read-only
+    // git call — safe under `--dry-run` (no REST, no state write). On resume the
+    // persisted repo is the authority (a conflicting `--repo` throws, never a
+    // silent re-point).
+    const repoSlug = flags.services.includes('github') || flags.services.includes('neon')
+        ? await resolveRepoSlug(rootDir, projectName, state?.github?.repo, flags.repo, gitInDir)
+        : undefined;
     const steps = buildPlan(flags.services, state);
     const result = {
         projectName,
@@ -2439,6 +2848,9 @@ export async function runProvision(flags) {
         resumed: (flags.resume || standaloneDomain) && !flags.force,
         steps,
     };
+    if (repoSlug) {
+        result.repo = repoSlug;
+    }
     if (hasDomain) {
         result.clientDomain = { domain: flags.domain, route: flags.dns };
     }
@@ -2472,6 +2884,13 @@ export async function runProvision(flags) {
         scope: flags.team ?? flags.orgId ?? '',
         createdAt: new Date().toISOString(),
     };
+    // BOOT-001: record the resolved repo BEFORE the steps run, so the Neon E2E-secret
+    // push (`neonSecretRepo`, which runs before the github step) targets the resolved
+    // repo — not the historical `${FACTORY_ORG}/${projectName}` fallback. Never
+    // clobbers a resumed state's repo (that one is the authority).
+    if (repoSlug && !runState.github?.repo) {
+        runState.github = { repo: repoSlug };
+    }
     // Ensure the state dir exists + a baseline file before the first step, so a
     // step failure on the very first service still leaves a resumable state.
     writeProvisionState(rootDir, runState);

package/dist/commands/update.js

@@ -58,6 +58,7 @@ export function parseUpdateFlags(argv) {
         mineAll: argv.includes('--mine-all'),
         resume: argv.includes('--resume'),
         verify: argv.includes('--verify'),
+        dryRun: argv.includes('--dry-run'),
         core: argv.includes('--core'),
         full: argv.includes('--full'),
         commit: argv.includes('--commit'),
@@ -395,6 +396,26 @@ function syncDerivedPrettierignore(rootDir, stagedDir) {
         console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
     }
 }
+/** Exit code of `--dry-run` when the preview found conflicts (0 = none). Lets a
+ * non-interactive caller (the GUI) branch on the result instead of clobbering. */
+const DRY_RUN_CONFLICTS_EXIT = 2;
+/**
+ * `--dry-run`: preview the plan (buckets + the explicit conflict list) and apply
+ * NOTHING. Prints the conflicting paths so a human or agent sees exactly what
+ * collides before deciding. The GUI runs this first: no conflicts → it is safe to
+ * apply `--theirs-all` (only adds/overwrites of clean files); conflicts → hand off
+ * to the CLI for per-file resolution instead of silently taking theirs.
+ */
+function reportDryRun(diff, manifest) {
+    console.log(`\n🔍 Vista previa de update a v${manifest.version} — no se modificó nada:`);
+    reportSummary(diff, manifest);
+    if (diff.conflicts.length > 0) {
+        console.log('\nArchivos en conflicto (los modificaste tú y el Factory también los cambió):');
+        for (const c of diff.conflicts)
+            console.log(`  • ${c.path}`);
+        console.log('\nPara resolverlos, corre `factory update` (sin `--dry-run`): pregunta archivo por archivo.');
+    }
+}
 /** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
 function reportSummary(diff, manifest) {
     if (diff.deleteSilent.length > 0) {
@@ -469,6 +490,9 @@ export async function runUpdate(flags, deps = {}) {
     if (flags.beta && flags.stable) {
         throw new CLIError('No puedes combinar `--beta` con `--stable`.');
     }
+    if (flags.dryRun && (flags.verify || flags.resume)) {
+        throw new CLIError('No puedes combinar `--dry-run` con `--verify` ni `--resume`.');
+    }
     // --verify and --resume short-circuit (no download).
     if (flags.verify) {
         runVerify(rootDir);
@@ -529,6 +553,14 @@ export async function runUpdate(flags, deps = {}) {
                 'El release está mal publicado; no se modificó nada.');
         }
         if (legacy) {
+            // --dry-run on a no-lockfile repo: nothing to conflict with (first sync has no
+            // prior version), so report clean and STOP — never auto-register under dry-run.
+            if (flags.dryRun) {
+                console.log('\n🔍 Vista previa: este repo aún no tiene lockfile. El primer `factory update` ' +
+                    'registra el cerebro; en el primer sync no hay conflictos posibles.');
+                process.exitCode = 0;
+                return;
+            }
             await applyLegacy(rootDir, stagedDir, manifest);
             // Legacy auto-register succeeded → end-pointer (PVSKILL-002).
             printProvisionPointer({ assumeYes: flags.yes });
@@ -542,6 +574,14 @@ export async function runUpdate(flags, deps = {}) {
         ]);
         const disk = hashDiskPaths(rootDir, trackedPaths);
         const diff = diffLockfiles(oldLock, manifest, disk);
+        // --dry-run: preview + STOP. No prompts, no apply, no lockfile, no commit.
+        // Exit 2 when conflicts exist so the GUI branches on it (0 otherwise). `return`
+        // runs the finally → tmpRoot is cleaned (no update-state was written).
+        if (flags.dryRun) {
+            reportDryRun(diff, manifest);
+            process.exitCode = diff.conflicts.length > 0 ? DRY_RUN_CONFLICTS_EXIT : 0;
+            return;
+        }
         // Resolve conflicts.
         const theirsConflicts = [];
         for (const conflict of diff.conflicts) {

package/dist/index.js

@@ -69,6 +69,7 @@ Sobre \`update\`:
     --mine-all     Conserva tu versión en todos los conflictos
     --resume       Retoma un update interrumpido sin re-descargar
     --verify       Reporta diferencias disco-vs-lockfile sin modificar nada
+    --dry-run      Previsualiza el plan (conflictos incluidos) SIN aplicar; sale 2 si hay conflictos
     --beta         Entra al canal beta (instala el último pre-release \`-beta.N\`)
     --stable       Sale del canal beta y baja al estable (limpia \`beta\` del lockfile)
     --yes / -y     Auto-confirma el auto-registro de un repo legacy (sin lockfile) —

package/dist/lib/cloudflare-api.js

@@ -16,8 +16,12 @@
  * actionable `CLIError` (issue §8 Gherkin) — it NEVER deletes a record to recover.
  *
  * What this module does NOT do:
- *   - Delete a DNS record. The idempotent path is create-or-PATCH; an existing
- *     record is never removed without explicit human confirmation (issue §8).
+ *   - Delete a DNS record to RECOVER from an error. The idempotent provisioning
+ *     path is create-or-PATCH; a record is never removed to "fix" a failed call
+ *     (issue §8). The ONE deletion shipped here ({@link deleteDnsRecord},
+ *     BOOT-007) is DELIBERATE cleanup inside a flow a human already confirmed
+ *     (retiring the interim domain after the client domain went live) — it is
+ *     never an automatic recovery move.
  *   - Read or log a token value. The token arrives as an argument and is handed
  *     straight to the `Authorization` header; it never reaches stdout.
  *
@@ -241,3 +245,109 @@ export async function ensureCnameRecord(zoneId, name, token, deps = {}) {
     }
     return 'unchanged';
 }
+/**
+ * Delete a DNS record by id — `DELETE /zones/{id}/dns_records/{recordId}`
+ * (BOOT-007). The ONE deletion in this module, and it is DELIBERATE: it runs only
+ * inside a flow the human already confirmed (retiring the interim domain after the
+ * client domain verified — the orphaned interim CNAME would otherwise resolve to
+ * {@link CNAME_VERCEL_TARGET} and serve a 404 forever). It is NEVER used to
+ * recover from a failed call — the module-header contract stands.
+ *
+ * Mirrors `removeVercelDomain`'s 404 tolerance: a record already gone (deleted by
+ * hand or by a previous run) is `absent`, not an error — the cleanup is idempotent.
+ *
+ * @throws {CloudflareApiError} on any non-2xx other than 404 / `success: false`.
+ */
+export async function deleteDnsRecord(zoneId, recordId, token, deps = {}) {
+    try {
+        await cloudflareApi('DELETE', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps);
+        return 'removed';
+    }
+    catch (error) {
+        if (error instanceof CloudflareApiError && error.status === 404)
+            return 'absent';
+        throw error;
+    }
+}
+/**
+ * Normalize a record content for comparison (issue §8 idempotency). Cloudflare
+ * returns TXT content wrapped in double quotes (`"v=spf1 …"`) while Resend hands
+ * it bare — a byte-compare would false-positive a "different content" and PATCH
+ * on every re-run. Stripping ONE layer of surrounding quotes + trimming makes the
+ * re-run comparison stable without touching the value actually stored.
+ */
+function normalizeRecordContent(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * Find an existing record of `spec.type` for `name` in the zone (issue §8
+ * idempotency) — same lookup shape as {@link findCnameRecord}, parameterized on
+ * the type. Returns the record (so the caller can compare content and PATCH a
+ * rotated value) or `null` when absent.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function findDnsRecord(zoneId, type, name, token, deps = {}) {
+    const data = (await cloudflareApi('GET', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, undefined, { type, name }));
+    return (data.result ?? []).find((r) => r.name === name && r.type === type) ?? null;
+}
+/**
+ * Create a TXT/MX record — `POST /zones/{id}/dns_records` (BOOT-003 §4), same
+ * call shape as {@link createCnameRecord} (`ttl: 1` = auto). TXT/MX cannot be
+ * proxied, so no `proxied` flag is sent. `priority` rides along for MX only.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function createDnsRecord(zoneId, spec, token, deps = {}) {
+    await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, {
+        type: spec.type,
+        name: spec.name,
+        content: spec.content,
+        ttl: 1,
+        ...(spec.priority !== undefined ? { priority: spec.priority } : {}),
+    });
+}
+/**
+ * PATCH an existing record to the content/priority the spec demands — `PATCH
+ * /zones/{id}/dns_records/{recordId}` (issue §8: a DKIM rotation leaves a record
+ * with STALE content; we repoint it in place). Same principle as
+ * {@link unproxyCnameRecord}: we NEVER delete a record to "fix" it.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function patchDnsRecord(zoneId, recordId, spec, token, deps = {}) {
+    await cloudflareApi('PATCH', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps, {
+        type: spec.type,
+        name: spec.name,
+        content: spec.content,
+        ...(spec.priority !== undefined ? { priority: spec.priority } : {}),
+    });
+}
+/**
+ * Idempotently ensure a TXT/MX record matching `spec` exists in the zone
+ * (BOOT-003 §4 + §8) — the TXT/MX sibling of {@link ensureCnameRecord}. Returns
+ * the outcome so the caller can narrate it:
+ *   - `created`   — no record existed → POSTed a fresh one
+ *   - `updated`   — a record existed with DIFFERENT content/priority (e.g. a DKIM
+ *                   rotation) → PATCHed it in place (never deleted — §8)
+ *   - `unchanged` — a record with the same content already existed → nothing to do
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ */
+export async function ensureDnsRecord(zoneId, spec, token, deps = {}) {
+    const existing = await findDnsRecord(zoneId, spec.type, spec.name, token, deps);
+    if (!existing) {
+        await createDnsRecord(zoneId, spec, token, deps);
+        return 'created';
+    }
+    const sameContent = normalizeRecordContent(existing.content) === normalizeRecordContent(spec.content);
+    const samePriority = spec.priority === undefined || existing.priority === spec.priority;
+    if (sameContent && samePriority)
+        return 'unchanged';
+    await patchDnsRecord(zoneId, existing.id, spec, token, deps);
+    return 'updated';
+}

package/dist/lib/env-file.js

@@ -78,10 +78,13 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
     body = setEnvLine(body, 'DATABASE_URL', neon.developDirect);
     body = setEnvLine(body, 'DATABASE_URL_MAIN', neon.mainDirect);
     body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
-    writeFileSync(localPath, body, 'utf8');
-    // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600). Same
-    // discipline the secrets rail uses; matters on the headless multi-tenant
-    // Agent Server where the default umask would leave it world-readable.
+    // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600) from birth.
+    // The `mode: 0o600` makes the file created 0600 with no world-readable window
+    // between create and chmod — critical on the headless multi-tenant Agent Server
+    // where the default umask would otherwise leave one tenant's secrets briefly
+    // readable by others. `mode` only applies when the file is CREATED, so the
+    // chmod below still covers the `--force` overwrite path (file already exists).
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     chmodSync(localPath, 0o600);
     return 'written';
 }
@@ -104,7 +107,7 @@ export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
     let body = readFileSync(localPath, 'utf8');
     body = setEnvLine(body, 'NEON_PROJECT_ID', projectId);
     body = setEnvLine(body, 'NEON_API_KEY', apiKey);
-    writeFileSync(localPath, body, 'utf8');
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     chmodSync(localPath, 0o600); // holds NEON_API_KEY → owner-only.
     return true;
 }
@@ -133,7 +136,7 @@ export function writeEmailLocalCreds(rootDir, resendKey, emailFrom) {
     body = setEnvLine(body, 'EMAIL_PROVIDER', 'resend');
     body = setEnvLine(body, 'RESEND_API_KEY', resendKey);
     body = setEnvLine(body, 'EMAIL_FROM', emailFrom);
-    writeFileSync(localPath, body, 'utf8');
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     chmodSync(localPath, 0o600); // holds RESEND_API_KEY → owner-only.
     return true;
 }

package/dist/lib/env-wizard.js

@@ -41,6 +41,12 @@ const DIVIDER = /^#\s*-{3,}\s*$/;
 const ACTIVE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
 const COMMENTED = /^#\s*([A-Z][A-Z0-9_]*)=(.*)$/;
 const SECRET_KEY = /(_SECRET|_KEY|_TOKEN|_PASSWORD)$/;
+/**
+ * `NEXT_PUBLIC_*` vars are public by Next.js convention — they're inlined into
+ * the client bundle, so they can never be secrets regardless of their suffix
+ * (e.g. NEXT_PUBLIC_AUTH_PASSWORD is a boolean feature flag, not a credential).
+ */
+const PUBLIC_PREFIX = /^NEXT_PUBLIC_/;
 function unquote(raw) {
     const v = raw.trim();
     if (v.length >= 2 &&
@@ -104,10 +110,16 @@ export function parseEnvExample(text) {
     }
     return entries;
 }
-function questionKind(key, defaultValue) {
+/**
+ * Classify a var into the widget the wizard renders. Secret detection delegates
+ * to `isSecretKey` so classification, masking and review all share one rule
+ * (secret suffix AND not `NEXT_PUBLIC_*` — public-by-convention vars are never
+ * secrets, e.g. NEXT_PUBLIC_AUTH_PASSWORD="true" is a boolean flag).
+ */
+export function questionKind(key, defaultValue) {
     if (SELECTS[key])
         return 'select';
-    if (SECRET_KEY.test(key))
+    if (isSecretKey(key))
         return 'secret';
     if (defaultValue === 'true' || defaultValue === 'false')
         return 'boolean';
@@ -189,9 +201,13 @@ export function applyWizardAnswers(rootDir, answers) {
 // secret values, (c) auto-generate what a dev can't type, and (d) catch broken
 // setups (a provider flag on with empty creds). All pure over their inputs.
 // ─────────────────────────────────────────────────────────────────────────────
-/** True when `key`'s value is a secret (never printed in review/summary output). */
+/**
+ * True when `key`'s value is a secret (never printed in review/summary output).
+ * `NEXT_PUBLIC_*` keys are excluded: Next.js inlines them into the client bundle,
+ * so they're public by convention even when their suffix looks secret-ish.
+ */
 export function isSecretKey(key) {
-    return SECRET_KEY.test(key);
+    return !PUBLIC_PREFIX.test(key) && SECRET_KEY.test(key);
 }
 /** Parse an env-file body into `{ KEY: value }` (unquoted), skipping comments/blanks. */
 export function parseEnvBody(body) {
@@ -247,8 +263,12 @@ const OAUTH_PROVIDERS = [
 ];
 /**
  * Warn (do NOT block) about half-configured setups that would ship a broken app:
- * an OAuth provider enabled with empty creds → broken login button; notifications
- * enabled with no VAPID keys → dead push. Pure over the resolved env map.
+ * an OAuth flag on with missing creds → `next build` FAILS (BOOT-005: auth.ts
+ * resolves the provider credentials at module load, i.e. during the build — a
+ * deploy that never ships on derivatives whose frozen src/ predates the auth.ts
+ * guard); notifications enabled with no VAPID keys → dead push. Pure over the
+ * resolved env map. Warn-never-block by contract (headless-safe): the wizard
+ * stays pure + non-interactive, so escalation is message-only.
  */
 export function checkEnvCompleteness(env) {
     const warnings = [];
@@ -257,8 +277,10 @@ export function checkEnvCompleteness(env) {
             continue;
         const missing = [p.id, p.secret].filter((k) => !env[k]);
         if (missing.length) {
-            warnings.push(`Login con ${p.label} activado pero falta ${missing.join(' + ')} → el botón de login ` +
-                `quedará roto. Complétalas o pon ${p.flag}="false".`);
+            warnings.push(`Login con ${p.label} activado pero falta ${missing.join(' + ')} → EL BUILD FALLARÁ ` +
+                `mientras ${p.flag} quede en "true" sin credenciales (next build resuelve las ` +
+                `credenciales del provider al compilar — el deploy nunca sale). ` +
+                `Complétalas o pon ${p.flag}="false".`);
         }
     }
     if (env['NEXT_PUBLIC_NOTIFICATIONS_ENABLED'] === 'true' &&

package/dist/lib/vercel-env.js

@@ -334,19 +334,53 @@ export async function listEnvVars(projectId, token, teamId, deps = {}) {
     return data.envs ?? [];
 }
 /**
- * Idempotently set ONE env var for its targets (issue §4 + §8). If an existing
- * var already covers any of the requested targets, it is PATCHed
- * (`/v10/projects/{id}/env/{envId}`); otherwise it is POSTed
- * (`/v10/projects/{id}/env`). Either way the call threads `?teamId=`.
+ * Idempotently set ONE env var for its targets (issue §4 + §8). If existing vars
+ * already cover any of the requested targets, they are RECONCILED into a single
+ * record (PATCH `/v10/projects/{id}/env/{envId}`, DELETEing any surplus record —
+ * see below); otherwise the var is POSTed (`/v10/projects/{id}/env`). Either way
+ * every call threads `?teamId=`.
  *
  * Matching is by `key` + target overlap — a var pushed for `production` does not
  * clobber the same key's `preview` entry (they are distinct Vercel env records,
- * which is exactly how `AUTH_SECRET` can differ per environment).
+ * which is exactly how `AUTH_SECRET` can differ per environment). Same-key
+ * records whose target does NOT overlap the plan are never touched, so the
+ * intentional split pairs `buildEnvPlan` creates (distinct values per env) are
+ * never collapsed by a per-target push.
+ *
+ * Split-target reconciliation (BOOT-002): `buildEnvPlan` intentionally creates
+ * SPLIT records per target for some keys (e.g. `NEXT_PUBLIC_APP_URL` as
+ * `['production']` + `['preview']`). When a later plan re-points that key with a
+ * COMBINED target (`['production','preview']` — e.g. the `--domain` go-live),
+ * ALL overlapping records are gathered, the surplus ones are DELETEd FIRST
+ * (Vercel rejects a PATCH whose expanded target collides with a sibling record),
+ * and the first record is then PATCHed with the plan's value + target — leaving
+ * ONE consistent record for the key. A re-run over the already-reconciled state
+ * finds a single record and simply re-PATCHes it in place: no duplicate, no 400.
+ *
+ * @throws {CLIError} when a surplus-record DELETE fails mid-reconciliation — the
+ * message names the key and the step stays re-runnable with `--resume` (the next
+ * run re-lists the records and retries the cleanup).
+ * @throws {VercelApiError} on any other non-2xx (the caller maps it).
  */
 export async function upsertEnvVar(projectId, token, teamId, plan, existing, deps = {}) {
-    const match = existing.find((e) => e.key === plan.key && (e.target ?? []).some((t) => plan.target.includes(t)));
-    if (match) {
-        await vercelApi('PATCH', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(match.id)}`, token, teamId, deps, {
+    // EVERY record of the key whose target overlaps the plan — not just the first
+    // (a combined-target plan over split records must reconcile the whole set).
+    const matches = existing.filter((e) => e.key === plan.key && (e.target ?? []).some((t) => plan.target.includes(t)));
+    if (matches.length > 0) {
+        const [survivor, ...surplus] = matches;
+        // DELETE the surplus records BEFORE the PATCH: expanding the survivor's
+        // target while a sibling still owns one of those targets 400s on Vercel.
+        for (const record of surplus) {
+            try {
+                await vercelApi('DELETE', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(record.id)}`, token, teamId, deps);
+            }
+            catch (error) {
+                throw new CLIError(`No se pudo eliminar el record duplicado de \`${plan.key}\` en Vercel al reconciliar ` +
+                    `sus targets (${error?.message ?? 'error desconocido'}).\n` +
+                    'La variable quedó a medio reconciliar; reintenta con `--resume` para completar la limpieza.');
+            }
+        }
+        await vercelApi('PATCH', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(survivor.id)}`, token, teamId, deps, {
             value: plan.value,
             target: plan.target,
             type: 'encrypted',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",