@timekast/factory 1.23.1 → 1.25.0

package/dist/commands/provision.js

@@ -29,7 +29,8 @@ import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, e
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
 import { defaultEnvPath, readEnvKeyNames, 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';
+import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, getVercelProjectByName, GitHubAppNotInstalledError, linkGitRepo, listProjectDomains, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, removeVercelProject, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, VERCEL_AUTO_APEX, writeVercelProjectJson, } from '../lib/vercel-env.js';
+import { decideInitialMigration, hasGeneratedMigrations, MIGRATION_SKIP_MESSAGES, MIGRATIONS_DIR, } from '../lib/initial-migration.js';
 import { writeBacklogLocalCreds, writeE2eLocalCreds, writeEmailLocalCreds, writeEnvLocal, } from '../lib/env-file.js';
 import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
@@ -257,6 +258,12 @@ function printPlan(result) {
             console.log(`        · Resend env: RESEND_API_KEY [production, preview] + EMAIL_FROM=${PROVISION_EMAIL_FROM}`);
         }
     }
+    // GAP-001: the initial migration is not a service, it is a step of the bootstrap —
+    // announced with the plan so a `--dry-run` states it without generating anything.
+    if (result.initialMigration) {
+        console.log(`  ＋ crear  ${INITIAL_MIGRATION_LABEL}`);
+        console.log('        · se commitea con pathspec propio antes del primer deploy');
+    }
     if (result.dryRun) {
         console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
     }
@@ -834,6 +841,28 @@ function readSharedVercelEnv(envPath) {
 async function pnpmInstall(cwd) {
     await execa('pnpm', ['install'], { cwd });
 }
+/**
+ * The roots this PROCESS already installed. A provision run targets ONE root, so this
+ * is the run-scoped flag the initial-migration step and the `vercel` step share: the
+ * first of the two pays for `pnpm install`, the second is a no-op.
+ *
+ * 🔴 It is NOT `existsSync('node_modules')`. Having the directory does not mean having
+ * the dependencies at their current versions, and the `vercel` step installs
+ * unconditionally today — gating on presence would be a silent regression of that
+ * guarantee (GAP-001 §8). A failed install is deliberately NOT recorded, so the next
+ * caller retries it.
+ */
+const installedRoots = new Set();
+/**
+ * `pnpm install` in the derived dir, at most ONCE per process per root. The seam is the
+ * caller's `runInstall` (tests never run a real install); the default is {@link pnpmInstall}.
+ */
+export async function ensureDeps(rootDir, runInstall = pnpmInstall) {
+    if (installedRoots.has(rootDir))
+        return;
+    await runInstall(rootDir);
+    installedRoots.add(rootDir);
+}
 /**
  * PROV-003 — sync env into the Vercel project: thread `teamId` on EVERY REST call,
  * push variables PER TARGET (production vs preview), mint an INDEPENDENT
@@ -949,9 +978,11 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     // `pnpm install` the derived dir (issue §4). A missing package.json (non-Node
     // derivative) is reported, NOT fatal (issue §8).
     if (existsSync(join(rootDir, 'package.json'))) {
-        const runInstall = deps.runInstall ?? pnpmInstall;
         try {
-            await runInstall(rootDir);
+            // Run-scoped (GAP-001): a no-op when the initial-migration step already
+            // installed this root in the same run — never twice, never skipped by a
+            // `node_modules` that happens to exist.
+            await ensureDeps(rootDir, deps.runInstall);
         }
         catch (error) {
             console.warn(`⚠ \`pnpm install\` falló en el directorio del derivado (${error?.message ?? 'error'}).\n` +
@@ -1334,8 +1365,10 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
  * Commit the activated E2E workflow (`e2e.yml`) and push it to BOTH `main` and
  * `develop` in the derived repo. `factory new` pushed the initial scaffold commit
  * before provision activated this workflow, so it lives only in the working tree
- * until committed here. (Migrations run in the Vercel build via `vercel-build`, not a
- * workflow — there is nothing to commit for them.) Idempotent — when a `--resume`
+ * 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`,
+ * there is no migration workflow.) Idempotent — when a `--resume`
  * finds it already committed, `git add` stages nothing and the commit/push is skipped.
  */
 async function commitAndPushWorkflows(rootDir, runGit) {
@@ -1375,6 +1408,329 @@ async function commitProvisionState(rootDir) {
         // Non-fatal: the local state is intact; the dev can commit it later.
     }
 }
+/** Default `pnpm db:generate` runner — `execa` in the derived dir, no shell. */
+async function drizzleGenerate(cwd) {
+    await execa('pnpm', ['db:generate'], { cwd });
+}
+/** The commit subject of the generated migration (English — GIT.md §3.1). */
+const INITIAL_MIGRATION_COMMIT = 'chore(db): add the initial database migration';
+/** The plan label of the step (es-MX), printed by {@link printPlan}. */
+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
+ * (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.
+ */
+const MIGRATION_BRANCH = 'main';
+/** The secondary branch the same commit is fast-forwarded onto (the working branch). */
+const MIGRATION_DEV_BRANCH = 'develop';
+/**
+ * The pre-`main` default branch name. `buildGitSubstrate` renames it to
+ * {@link MIGRATION_BRANCH} before pushing, which is why the checkout guard below treats
+ * a repo sitting on it as reaching `main` after all — when that step is in the plan.
+ */
+const LEGACY_DEFAULT_BRANCH = 'master';
+/**
+ * The GREENFIELD guard: the run creates BIRTH infrastructure.
+ *
+ * 🔴 Not merely "there is no `.sql` yet". Without this guard any other door into
+ * provision — a `--services=dns` for a deferred go-live, a standalone `--domain`, a
+ * `--resume` — would generate a `0000` on one of the LIVE derivatives that have no
+ * migrations, commit it, and (with no `github` step to push it) push it too. The next
+ * deploy would run `CREATE TABLE` against a populated database and the build would die.
+ *
+ * 🔴 And the SHAPE OF THE PLAN is not birth either — that was the first version of this
+ * guard, and it left two doors open onto exactly the derivatives it was written to
+ * protect:
+ *
+ *   1. **`--force` NEVER counts as greenfield.** `runProvision` calls
+ *      `clearProvisionState` before `buildPlan`, so with `--force` there is no state to
+ *      read and the plan comes back with EVERY service in `create` — the shape of a
+ *      bootstrap, produced by a flag whose whole job is to destroy the only evidence that
+ *      this project already went through provisioning. A `--services=neon,github --force`
+ *      over a live derivative would have generated and pushed a `0000` on it.
+ *   2. **`github: create` only counts WITH a prior state.** A live derivative provisioned
+ *      before the CLI existed has no `.timekast/provision.json`, so nothing throws, the
+ *      state is `null` and the substrate reads as missing. `github` still counts — that is
+ *      the interrupted-bootstrap case retaken with `--resume`, where `neon` is already in
+ *      `skip` while the substrate is not there yet — but only when a prior state PROVES
+ *      the bootstrap started. Without it, `github: create` proves nothing.
+ *
+ *   3. **`neon: create` needs corroboration too**, and this is the subtlest of the three.
+ *      "A database is being created, so it is empty" conflates two different facts: that
+ *      a NEW database exists, and that the database THE DEPLOY WILL MIGRATE is that one.
+ *      `provisionNeon` only creates the project and uploads E2E secrets — production's
+ *      connection string is written by the `vercel` step. So on a derivative that is
+ *      already live, a new Neon project changes nothing about where the deploy points,
+ *      and the `0000` would be applied against the populated database it has always used.
+ *      Creating a database therefore counts only alongside the run also wiring the app
+ *      up: `vercel` (which writes that connection string) or `github` (which creates the
+ *      substrate carrying the code).
+ *
+ * The population this protects is specific and real: a derivative born before the kit
+ * generated migrations has its tables and its data from a `db:push`, and NO `.sql` at
+ * all — so the "already has migrations" latch does not catch it. What such a project
+ * needs is its `0000` recorded as ALREADY APPLIED (a per-environment baseline), never
+ * executed: drizzle emits `CREATE TABLE` without `IF NOT EXISTS`, so running it fails
+ * with `relation "users" already exists` and the build stops deploying. That baseline is
+ * deliberately out of this step's scope.
+ *
+ * The cost of the third rule is one degraded case, and it is the right way to be wrong:
+ * an interrupted bootstrap missing ONLY the database will not generate the migration by
+ * itself. The dev runs `pnpm db:generate`, and both `factory doctor` and `pnpm preflight`
+ * now say so. A false negative costs one command; a false positive costs a client's
+ * deploy.
+ */
+export function isGreenfieldRun({ steps, force, hadPriorState }) {
+    if (force)
+        return false;
+    const creates = (service) => steps.some((step) => step.service === service && step.action === 'create');
+    // A new database does NOT prove birth on its own — see the docblock. It needs the run
+    // to also be wiring the app up: `vercel` writes production's connection string, and
+    // `github` creates the substrate that carries the code.
+    if (creates('neon'))
+        return creates('vercel') || creates('github');
+    // No new database, but the substrate is being born and a prior state proves the
+    // bootstrap already started — the interrupted run, retaken.
+    return creates('github') && hadPriorState;
+}
+/**
+ * Will the initial-migration step do work on this run? Greenfield guard (the plan + the
+ * run's own evidence) AND the disk decision (`decideInitialMigration`). Read-only — safe
+ * to evaluate while the plan is assembled, i.e. under `--dry-run`.
+ */
+export function shouldRunInitialMigration(rootDir, evidence) {
+    return isGreenfieldRun(evidence) && decideInitialMigration(rootDir).run;
+}
+/**
+ * The branch `HEAD` points at, or `null` when git cannot name one.
+ *
+ * 🔴 Why the step reads it at all: `git add` / `git commit -- <pathspec>` land on the
+ * CURRENT branch, while the push names a REF (`push origin main`). Nothing used to read
+ * the branch, so a dev standing on `develop` — or on a detached `HEAD` — got the commit
+ * on that branch and a push of a `main` that does NOT carry the `.sql`: a green exit code
+ * over exactly the failure this step exists to prevent.
+ *
+ * Never throws, and a detached `HEAD` (which `--abbrev-ref` reports as the literal
+ * `HEAD`) is `null` too: both are "not the migration branch", which is the fail-closed
+ * answer for the push.
+ */
+async function readCurrentBranch(rootDir, runGit) {
+    try {
+        const branch = (await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], rootDir)).stdout.trim();
+        return branch && branch !== 'HEAD' ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The commit `HEAD` points at, or `null` when git cannot say. Only read for the detached
+ * warning: there the hash is the ONLY handle the dev has on the commit that was just
+ * made, so the message has to carry it.
+ */
+async function readHeadSha(rootDir, runGit) {
+    try {
+        return (await runGit(['rev-parse', 'HEAD'], rootDir)).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Confirm the just-pushed commit actually reached the remote, and SAY SO. A push that
+ * silently did not land is the failure this whole step exists to prevent, so an
+ * unconfirmable remote is a NOISY warning, never an assumption. Non-fatal: the commit
+ * is already durable locally.
+ */
+async function confirmMigrationOnRemote(rootDir, runGit) {
+    try {
+        const local = (await runGit(['rev-parse', 'HEAD'], rootDir)).stdout.trim();
+        const remoteLine = (await runGit(['ls-remote', 'origin', `refs/heads/${MIGRATION_BRANCH}`], rootDir)).stdout
+            .trim()
+            .split(/\s+/)[0];
+        if (local && remoteLine && local === remoteLine) {
+            console.log(`  ✔ Migración inicial confirmada en el remoto (origin/main ${local.slice(0, 7)}).`);
+            return;
+        }
+        console.warn('⚠ No pude confirmar que la migración inicial esté en el remoto ' +
+            `(origin/main = \`${remoteLine || 'sin respuesta'}\`, local = \`${local || 'desconocido'}\`).\n` +
+            '  Revisa `git log origin/main` ANTES del primer deploy: si el `.sql` no está en el ' +
+            'remoto, el build migrará una base vacía.');
+    }
+    catch (error) {
+        console.warn(`⚠ No pude confirmar la migración inicial en el remoto (${error?.message ?? 'error'}).\n` +
+            '  Revisa `git log origin/main` ANTES del primer deploy.');
+    }
+}
+/**
+ * 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
+ * empty database.
+ *
+ * Order and its reasons:
+ *   1. Guard + decision — greenfield run AND a derivative that needs it (see
+ *      {@link isGreenfieldRun} / `decideInitialMigration`). Anything else returns.
+ *   2. `ensureDeps` — `drizzle-kit` has to exist. Run-scoped, shared with the `vercel` step.
+ *   3. `pnpm db:generate` — writes `0000_*.sql`. No DB connection needed
+ *      (`drizzle.config.ts` reads `process.env.DATABASE_URL!` without throwing).
+ *   4. `git rev-parse --abbrev-ref HEAD` + `git add` + `git status` +
+ *      `git commit -- <pathspec>` — NEVER a bare commit: with a shared index it would
+ *      swallow whatever else is staged (GIT.md §3.6.1). The branch is read because the
+ *      commit lands on it while the push names a ref (see {@link readCurrentBranch}).
+ *   5. Push, DISCRIMINATED by the plan: when the `github` step runs it pushes `main`
+ *      itself (`buildGitSubstrate`), so pushing here would be redundant; when it does not,
+ *      this step is the only thing that can get the `.sql` to the remote.
+ *
+ * Failure policy: `install`/`generate` ABORT with a `CLIError` — the step runs before the
+ * `github` step, so aborting here means nothing was pushed and nothing was deployed. A git
+ * IDENTITY failure while committing is a non-fatal warning (the `.sql` is already on disk),
+ * mirroring `new.ts`'s precedent. A commit on a branch that is not `main`, and a failed
+ * push, are warnings too — and each push is judged on its own (step 5 below).
+ */
+export async function ensureInitialMigration(rootDir, evidence, deps = {}) {
+    const { steps } = evidence;
+    if (!isGreenfieldRun(evidence)) {
+        // Silence would be wrong in ONE case, and it is one the CLI itself recommends:
+        // `--force` is the flag this command suggests for restarting a failed bootstrap
+        // ("descártalo y empieza de cero"), and a dev who follows that advice would end up
+        // with a derivative that has no `0000` and no word about it. The step still stands
+        // down — `--force` cannot prove birth — but it says so and hands over the remedy.
+        if (evidence.force) {
+            console.log('  ⏭ Con `--force` no genero la migración inicial: el flag descarta el estado de ' +
+                'provision, que es la única evidencia de si este proyecto ya nació — y sobre un ' +
+                'derivado vivo la generaría contra una base poblada.\n' +
+                '     Si esto ES un bootstrap: retómalo con `--resume`, o genera la migración a mano ' +
+                '(`pnpm db:generate`) y commitéala antes del primer deploy. `factory doctor` te lo ' +
+                'recuerda si falta.');
+        }
+        return;
+    }
+    const decision = decideInitialMigration(rootDir);
+    if (!decision.run) {
+        console.log(`  ⏭ ${MIGRATION_SKIP_MESSAGES[decision.reason]}`);
+        return;
+    }
+    const runGenerate = deps.runGenerate ?? drizzleGenerate;
+    const runGit = deps.runGit ?? gitInDir;
+    // 2. Dependencies (drizzle-kit). Run-scoped — the `vercel` step reuses this install.
+    try {
+        await ensureDeps(rootDir, deps.runInstall);
+    }
+    catch (error) {
+        throw new CLIError(`No se pudieron instalar las dependencias del derivado (${error?.message ?? 'error'}).\n` +
+            'Sin ellas no hay `drizzle-kit` para generar la migración inicial, y el primer deploy ' +
+            'correría contra una base vacía. Corre `pnpm install` a mano y reintenta con `--resume`.');
+    }
+    // 3. Generate the `0000`.
+    try {
+        await runGenerate(rootDir);
+    }
+    catch (error) {
+        throw new CLIError(`\`pnpm db:generate\` falló en el derivado (${error?.message ?? 'error'}).\n` +
+            'Sin la migración inicial el primer deploy correría contra una base vacía. Revisa el ' +
+            'schema en `src/lib/db/schema/`, genera a mano y reintenta con `--resume`.');
+    }
+    if (!hasGeneratedMigrations(rootDir)) {
+        console.warn(`⚠ \`pnpm db:generate\` terminó sin escribir ningún \`.sql\` en \`${MIGRATIONS_DIR}/\`.\n` +
+            '  Revisa el schema antes del primer deploy: no hay migración inicial que commitear.');
+        return;
+    }
+    console.log(`  ＋ ${MIGRATIONS_DIR}/ (migración inicial generada)`);
+    // 4. Commit with its OWN pathspec, preceded by a status of that same path. The branch
+    //    is read BEFORE the commit — that is the only thing that says where the commit
+    //    will actually land (`readCurrentBranch`).
+    const branch = await readCurrentBranch(rootDir, runGit);
+    try {
+        await runGit(['add', '--', MIGRATIONS_DIR], rootDir);
+        const pending = (await runGit(['status', '--porcelain', '--', MIGRATIONS_DIR], rootDir)).stdout.trim();
+        if (!pending) {
+            console.log('  ⏭ La migración inicial ya estaba commiteada — nada que pushear.');
+            return;
+        }
+        await runGit(['commit', '-m', INITIAL_MIGRATION_COMMIT, '--', MIGRATIONS_DIR], rootDir);
+    }
+    catch (error) {
+        // Precedent `new.ts`: a git identity failure is a warning, not an abort — the
+        // migration is on disk and the dev can commit it.
+        //
+        // UNSTAGE FIRST. The `add` above already staged the path, and leaving it there hands
+        // the `.sql` to whatever commits next: `commitProvisionState` reads the WHOLE index
+        // and commits bare, so the migration would ride into the run's own state commit
+        // under an unrelated subject. Failing to unstage is not fatal either — the file is
+        // on disk regardless, which is the guarantee this catch exists to state.
+        try {
+            await runGit(['reset', '--', MIGRATIONS_DIR], rootDir);
+        }
+        catch {
+            /* best-effort: the warning below is still true */
+        }
+        console.warn(`⚠ No pude commitear la migración inicial (${error?.message ?? 'error'}).\n` +
+            `  El \`.sql\` quedó en \`${MIGRATIONS_DIR}/\`: commitéalo y pushéalo ANTES del primer deploy ` +
+            '(configura tu identidad con `git config user.email` si ese fue el motivo).');
+        return;
+    }
+    // 5. Push — discriminated by whether the `github` step runs in THIS run.
+    const githubPushes = steps.some((step) => step.service === 'github' && step.action === 'create');
+    // 4b. The commit landed on `branch`, not necessarily on the branch the push names.
+    //     A mismatch is NOISY and stops the push: pushing `main` from here would send a
+    //     `main` that does NOT carry the `.sql` and exit 0 — the very failure this step
+    //     exists to prevent, in green. The `.sql` is on disk and committed where the dev is.
+    //
+    //     ONE exception, and it is not a loophole: a repo still on `master` when the
+    //     `github` step is about to run. That step RENAMES `master` → `main` before
+    //     pushing (`buildGitSubstrate`, step 1), so the commit does reach `main` with the
+    //     `.sql` inside — warning there would be alarmist about a case that works.
+    const substrateWillRename = githubPushes && branch === LEGACY_DEFAULT_BRANCH;
+    if (branch !== MIGRATION_BRANCH && !substrateWillRename) {
+        // A detached HEAD has no branch to merge, so the commit is reachable ONLY by its
+        // hash — naming it is the difference between an actionable warning and a scavenger
+        // hunt through the reflog.
+        const headSha = branch === null ? await readHeadSha(rootDir, runGit) : null;
+        console.warn(`⚠ La migración inicial se commiteó en \`${branch ?? `HEAD desprendido (${headSha ?? 'sha desconocido'})`}\`, no en ` +
+            `\`${MIGRATION_BRANCH}\` — no la pusheo.\n` +
+            `  El push nombra la rama \`${MIGRATION_BRANCH}\` y el commit quedó en otra: pushear ` +
+            `mandaría un \`${MIGRATION_BRANCH}\` SIN el \`.sql\` y el build migraría una base vacía.\n` +
+            (branch === null
+                ? `  Con \`HEAD\` desprendido no hay rama que mergear: el commit \`${headSha ?? '(desconocido)'}\` ` +
+                    `solo es alcanzable por su hash. Recupéralo con \`git branch <nombre> ${headSha ?? '<sha>'}\`, ` +
+                    `mergéalo a \`${MIGRATION_BRANCH}\` y pushea a mano ANTES del primer deploy.\n`
+                : `  Pásate a \`${MIGRATION_BRANCH}\` (o mergea esa rama ahí) y pushea a mano ANTES del ` +
+                    'primer deploy.\n'));
+        return;
+    }
+    if (githubPushes) {
+        console.log('  ↑ Migración inicial commiteada (el push de `main` lo hace el paso de GitHub).');
+        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
+    // (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.
+    try {
+        await runGit(['push', 'origin', MIGRATION_BRANCH], rootDir);
+    }
+    catch (error) {
+        console.warn(`⚠ No pude pushear la migración inicial (${error?.message ?? 'error'}).\n` +
+            '  Pushéala a mano ANTES del primer deploy: el build corre `pnpm db:migrate` contra el ' +
+            'árbol remoto.');
+        return;
+    }
+    try {
+        await runGit(['push', 'origin', `${MIGRATION_BRANCH}:${MIGRATION_DEV_BRANCH}`], rootDir);
+        console.log(`  ↑ Migración inicial commiteada + pusheada (${MIGRATION_BRANCH} + ${MIGRATION_DEV_BRANCH}).`);
+    }
+    catch (error) {
+        console.warn(`⚠ La migración inicial SÍ llegó a \`${MIGRATION_BRANCH}\`, pero no pude pushearla a ` +
+            `\`${MIGRATION_DEV_BRANCH}\` (${error?.message ?? 'error'}).\n` +
+            `  El deploy de producción está cubierto (\`vercel-build\` migra desde \`${MIGRATION_BRANCH}\`); ` +
+            `sincroniza \`${MIGRATION_DEV_BRANCH}\` a mano cuando puedas.`);
+    }
+    await confirmMigrationOnRemote(rootDir, runGit);
+}
 /** Map a Cloudflare REST failure to an actionable, es-MX `CLIError` (issue §8 edges). */
 function cloudflareErrorToCliError(error, context) {
     switch (error.status) {
@@ -2279,19 +2635,58 @@ async function resolveCandidate(provider, candidates, deps, recordAmbiguity) {
     const chosen = await select(provider, candidates);
     return chosen?.id ?? null;
 }
-/** Reconstruct the Vercel project id (read-only) — filter by name/slug. */
+/**
+ * Normalize a provider-side project name for slug comparison. Provider consoles
+ * hold DISPLAY names — a Neon project created as `Aditivo CRM` is the same stack
+ * as the `aditivo-crm` directory — so a raw string compare answers "was this
+ * created by the CLI", not "is this my project". Lowercase, non-alphanumerics
+ * collapsed to a single `-`, edges trimmed: `Aditivo CRM` → `aditivo-crm`.
+ */
+function normalizeProjectName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Pick the candidate pool for a slug out of a provider's project list: an EXACT
+ * (normalized) name match wins alone; otherwise every normalized name that
+ * contains the slug (or is contained by it) is surfaced for disambiguation.
+ */
+function matchProjectsBySlug(projects, slug) {
+    const target = normalizeProjectName(slug);
+    const matches = projects.filter((p) => {
+        const name = normalizeProjectName(p.name);
+        return name === target || name.includes(target) || target.includes(name);
+    });
+    const exact = matches.filter((p) => normalizeProjectName(p.name) === target);
+    return exact.length === 1 ? exact : matches;
+}
+/**
+ * Reconstruct the Vercel project id (read-only).
+ *
+ * The exact lookup goes FIRST — `GET /v9/projects/{name}` answers "is there a
+ * project called `{slug}`" in one request. The listing is the fallback for a
+ * project whose name merely resembles the directory, and it is the reason this
+ * order matters: the listing is paginated, and a team with a real fleet used to
+ * bury the project past the first page, where "not in this page" was recorded
+ * as `unknown` — indistinguishable from "does not exist".
+ */
 async function adoptVercel(slug, teamId, token, deps, recordAmbiguity) {
+    const exact = await getVercelProjectByName(slug, token, teamId, { fetchImpl: deps.fetchImpl });
+    if (exact)
+        return exact.id;
     const projects = await listVercelProjects(token, teamId, { fetchImpl: deps.fetchImpl });
     const candidates = projectsToCandidates(projects, slug, teamId);
+    if (candidates.length === 0) {
+        console.log(`  · Ningún proyecto de Vercel se parece a \`${slug}\` (revisé ${projects.length} del team \`${teamId}\`) — \`vercelProjectId: unknown\`.`);
+        return null;
+    }
     return resolveCandidate('Vercel', candidates, deps, recordAmbiguity);
 }
 /** Map Vercel project summaries to candidates, keeping only slug-name matches. */
 function projectsToCandidates(projects, slug, teamId) {
-    const matches = projects.filter((p) => p.name === slug || p.name.includes(slug) || slug.includes(p.name));
-    // Prefer an EXACT name match alone (unambiguous); otherwise surface all matches.
-    const exact = matches.filter((p) => p.name === slug);
-    const pool = exact.length === 1 ? exact : matches;
-    return pool.map((p) => ({
+    return matchProjectsBySlug(projects, slug).map((p) => ({
         id: p.id,
         name: p.name,
         url: `https://vercel.com/${teamId}/${p.name}`,
@@ -2303,16 +2698,17 @@ function projectsToCandidates(projects, slug, teamId) {
  * the `develop` one. A branch lookup failure leaves the branch id `unknown`
  * without failing the whole adopt (issue §4).
  */
-async function adoptNeon(slug, apiKey, deps, recordAmbiguity) {
-    const projects = await listNeonProjects(apiKey, { fetchImpl: deps.fetchImpl });
-    const matches = projects.filter((p) => p.name === slug || p.name.includes(slug) || slug.includes(p.name));
-    const exact = matches.filter((p) => p.name === slug);
-    const pool = exact.length === 1 ? exact : matches;
-    const candidates = pool.map((p) => ({
+async function adoptNeon(slug, apiKey, orgId, deps, recordAmbiguity) {
+    const projects = await listNeonProjects(apiKey, orgId, { fetchImpl: deps.fetchImpl });
+    const candidates = matchProjectsBySlug(projects, slug).map((p) => ({
         id: p.id,
         name: p.name,
         url: `https://console.neon.tech/app/projects/${p.id}`,
     }));
+    if (candidates.length === 0) {
+        console.log(`  · Ningún proyecto de Neon se parece a \`${slug}\` (revisé ${projects.length} de la org) — \`neonProjectId: unknown\`.`);
+        return { projectId: null, branchDevId: null };
+    }
     const projectId = await resolveCandidate('Neon', candidates, deps, recordAmbiguity);
     if (!projectId)
         return { projectId: null, branchDevId: null };
@@ -2359,17 +2755,23 @@ async function adoptGithub(slug, deps) {
  * source, through the very door DOM-001 closed from the other side.
  *
  * So it probes the org zones in order and keeps the one whose CNAMEs actually
- * exist. Deriving from the slug survives only as the LAST resort — no token, no
- * zone reachable, or a project whose CNAMEs are genuinely absent — where naming a
- * domain by convention is all anyone can do, and the narration says so.
+ * exist. When none does, it asks VERCEL where the app answers — a project living
+ * on the client's own domain (`crm.cliente.mx`) has no CNAME in any org zone, and
+ * for it the org-zone question has no true answer: the conventional name would be
+ * a host that resolves nowhere, written into the field destroy and the WebAuthn
+ * rpID both read.
+ *
+ * Deriving from the slug survives only as the LAST resort — no token, no zone
+ * reachable, and no Vercel project to ask — where naming a domain by convention
+ * is all anyone can do, and the narration says so.
  */
-async function adoptDns(slug, deps) {
+async function adoptDns(slug, deps, vercel) {
     const domains = provisionDomains(slug);
     const cfToken = readCloudflareApiKey(deps.envPath ?? defaultEnvPath());
     if (!cfToken) {
-        console.warn('⚠ No hay `CLOUDFLARE_API_TOKEN` en el rail — registro los dominios por nombre sin ' +
-            'confirmar sus CNAMEs (es read-only; corre `factory secrets <archivo>` si quieres la verificación).');
-        return domains;
+        console.warn('⚠ No hay `CLOUDFLARE_API_TOKEN` en el rail — no puedo confirmar CNAMEs ' +
+            '(es read-only; corre `factory secrets <archivo>` si quieres la verificación).');
+        return (await adoptDomainsFromVercel(vercel, deps)) ?? narrateDerivedDomains(domains);
     }
     const cfDeps = { fetchImpl: deps.fetchImpl };
     for (const zone of ORG_ZONE_NAMES) {
@@ -2407,9 +2809,60 @@ async function adoptDns(slug, deps) {
         }
     }
     console.log(`  · Sin CNAMEs en ninguna zona del org (${ORG_ZONE_NAMES.join(', ')}) — ` +
-        'registro los dominios por nombre en la zona actual.');
+        'le pregunto a Vercel dónde responde el proyecto.');
+    return (await adoptDomainsFromVercel(vercel, deps)) ?? narrateDerivedDomains(domains);
+}
+/** Say out loud that these hosts are a convention, not a confirmed fact. */
+function narrateDerivedDomains(domains) {
+    console.warn(`⚠ No pude confirmar dominios en ningún proveedor — registro los de convención ` +
+        `(\`${domains.prod}\` / \`${domains.dev}\`). Si el proyecto usa otro dominio, corrígelos ` +
+        'a mano en `.timekast/provision.json` antes de cualquier `--destroy`.');
     return domains;
 }
+/**
+ * Read the project's REAL hosts off Vercel (read-only) and split them into the
+ * dev/prod pair the state holds. A domain pinned to the `develop` branch is dev;
+ * an unpinned one is prod. Custom domains win over the `*.vercel.app` Vercel
+ * mints on its own — but the auto host is kept when a role has nothing else, so
+ * the rpID of a dev environment that never got a custom domain is still true.
+ *
+ * Returns `null` when there is no project to ask, the call fails, or the project
+ * has no domains at all — the caller falls back to the conventional names.
+ */
+async function adoptDomainsFromVercel(vercel, deps) {
+    if (!vercel)
+        return null;
+    let domains;
+    try {
+        domains = await listProjectDomains(vercel.projectId, vercel.token, vercel.teamId, {
+            fetchImpl: deps.fetchImpl,
+        });
+    }
+    catch {
+        console.warn('⚠ No se pudo leer los dominios del proyecto en Vercel (read-only) — continúo.');
+        return null;
+    }
+    if (domains.length === 0)
+        return null;
+    const isAuto = (d) => d.apexName === VERCEL_AUTO_APEX;
+    const isDev = (d) => d.gitBranch === NEON_DEVELOP_BRANCH;
+    const pick = (wantDev) => domains.find((d) => isDev(d) === wantDev && !isAuto(d)) ??
+        domains.find((d) => isDev(d) === wantDev);
+    const prod = pick(false);
+    const dev = pick(true);
+    if (!prod && !dev)
+        return null;
+    const resolved = { dev: dev?.name ?? '', prod: prod?.name ?? '' };
+    if (!resolved.prod || !resolved.dev) {
+        // One role has no host at all: report it rather than inventing its twin.
+        console.log(`  ℹ Vercel solo tiene dominio de ${resolved.prod ? 'producción' : 'develop'} para este proyecto.`);
+    }
+    console.log(`  ✔ Dominios tomados de Vercel — prod: ${resolved.prod || '(ninguno)'} · dev: ${resolved.dev || '(ninguno)'}`);
+    return {
+        dev: resolved.dev || ADOPT_UNKNOWN,
+        prod: resolved.prod || ADOPT_UNKNOWN,
+    };
+}
 /** Print the reconstructed adopt state in plain es-MX (the non-`--json` narration). */
 function printAdoptState(result) {
     const s = result.state;
@@ -2481,9 +2934,12 @@ export async function runAdopt(flags, deps = {}) {
     let neonProjectId = null;
     let neonBranchDevId = null;
     const neonApiKey = readNeonApiKey(envPath);
+    // Same rail value the create path threads (`NEON_ORGANIZATION_ID`): Neon REQUIRES
+    // it on an org-scoped key, and answers `400 org_id is required` without it.
+    const neonOrgId = readGateValue('NEON_ORGANIZATION_ID', envPath) ?? undefined;
     if (neonApiKey) {
         try {
-            const neon = await adoptNeon(slug, neonApiKey, adeps, (list) => {
+            const neon = await adoptNeon(slug, neonApiKey, neonOrgId, adeps, (list) => {
                 candidates.neon = list;
             });
             neonProjectId = neon.projectId;
@@ -2499,8 +2955,11 @@ export async function runAdopt(flags, deps = {}) {
     }
     // GitHub (gh repo view) — uses the dev's gh auth (no rail token needed).
     const githubRepo = await adoptGithub(slug, adeps);
-    // DNS (GET dns_records) — domain names always derivable; CNAME check best-effort.
-    const domains = await adoptDns(slug, adeps);
+    // DNS (GET dns_records) — the org zones first, then the project's own Vercel
+    // domains, and only then the conventional names (see `adoptDns`).
+    const domains = await adoptDns(slug, adeps, vercelProjectId && vercelToken && flags.team
+        ? { projectId: vercelProjectId, teamId: flags.team, token: vercelToken }
+        : null);
     const partial = {
         slug,
         vercelProjectId: vercelProjectId ?? ADOPT_UNKNOWN,
@@ -2575,7 +3034,7 @@ function describeDestroyPlan(target) {
         lines.push(`  － CNAME Cloudflare ${domain} — DELETE /zones/.../dns_records`);
     }
     if (target.vercelProjectId) {
-        lines.push(`  － Proyecto Vercel ${target.vercelProjectId} — \`vercel remove\` (sesión del dev)`);
+        lines.push(`  － Proyecto Vercel ${target.vercelProjectId} — DELETE /v9/projects (token del rail)`);
     }
     if (target.githubRepo) {
         lines.push(`  － Repo GitHub ${target.githubRepo} — \`gh repo delete\` (sesión del dev)`);
@@ -2704,36 +3163,44 @@ async function destroyCloudflareRecord(domain, zoneId, token, fetchImpl) {
     }
 }
 /**
- * Remove the Vercel PROJECT via the dev's `vercel` CLI (`vercel remove <slug>
- * --yes`) — issue §4: the project delete uses the DEV's session, never a shared org
- * token (the shared org Vercel token is create/configure-only). A "not found" stderr
- * is treated as already-removed (§8).
+ * Remove the Vercel PROJECT over REST, with the rail token that created it.
+ *
+ * 🔴 It used to shell out to the dev's `vercel remove <slug> --yes`, on the principle that a
+ * delete should use the DEV's session and never a shared org token. Measured teardown of a
+ * real ephemeral stack (2026-08-17) showed the principle unreachable in practice: the project
+ * is created by the rail token WITH a `teamId`, so it lives in the team, while the dev's CLI
+ * session sits in whatever scope they last logged into. The delete failed with
+ * `Not authorized … under scope "…"` and left a live, billable project behind — exactly the
+ * outcome `--ephemeral` exists to prevent.
+ *
+ * The REST path also removes the whole class of shell-argument hazards the old code had to
+ * guard against (a slug from the low-trust state file becoming a positional arg), and it
+ * targets the project by ID rather than by name.
+ *
+ * Consistency note: {@link destroyVercelDomain}, called from the same teardown, ALREADY
+ * deleted over REST with this token. The project delete was the outlier, not the rule.
  */
-async function destroyVercelProject(target, runVercel) {
+async function destroyVercelProject(target, token, fetchImpl) {
     const resource = `Proyecto Vercel ${target.slug}`;
-    // FIX 2: the slug came from the low-trust state file and is about to become a
-    // positional arg to `vercel remove`. A malformed slug (leading `-` = flag
-    // smuggling, or a non-subdomain shape) is NEVER passed to the command. It is a
-    // `failed` (not a silent skip) because a Vercel project IS recorded but cannot be
-    // torn down — so `hadFailures` keeps the state (no orphan), per FIX 3.
-    if (!isValidSubdomainSlug(target.slug)) {
+    if (!target.vercelProjectId) {
         return {
             resource: 'Proyecto Vercel',
             status: 'failed',
-            detail: `slug malformado en el estado (\`${target.slug}\`) — bórralo a mano en Vercel`,
+            detail: 'el estado no registró `vercel.projectId` — bórralo a mano en Vercel',
         };
     }
     try {
-        // `--` ends option parsing so the slug can never be read as a flag.
-        await runVercel(['remove', '--yes', '--', target.slug]);
-        return { resource, status: 'removed', detail: 'eliminado vía `vercel remove`' };
+        const outcome = await removeVercelProject(target.vercelProjectId, token, target.scope ?? '', {
+            fetchImpl,
+        });
+        return {
+            resource,
+            status: 'removed',
+            detail: outcome === 'absent' ? 'ya no existía (404)' : 'eliminado',
+        };
     }
     catch (error) {
-        const message = error?.message ?? '';
-        if (/not found|no such|does not exist|404/i.test(message)) {
-            return { resource, status: 'removed', detail: 'ya no existía (vercel)' };
-        }
-        return { resource, status: 'failed', detail: message || 'error en `vercel remove`' };
+        return { resource, status: 'failed', detail: error?.message ?? 'error' };
     }
 }
 /**
@@ -2847,6 +3314,18 @@ async function teardownProviders(target, deps) {
     // was never found and stayed behind. Keyed by domain→zone-id, resolved on demand.
     const zoneIdByDomain = new Map();
     for (const domain of target.domains) {
+        // A `*.vercel.app` host reaches the state only via `--adopt`, which records the
+        // auto host when a role has no custom domain. Vercel mints and owns it: there is
+        // no CNAME of ours to delete and no zone to resolve, so both branches below would
+        // report a `failed` for a resource that was never ours.
+        if (domain.endsWith(`.${VERCEL_AUTO_APEX}`)) {
+            outcomes.push({
+                resource: `Dominio ${domain}`,
+                status: 'skipped',
+                detail: 'host automático de Vercel — se va con el proyecto',
+            });
+            continue;
+        }
         // The domain is registered in the state, so there IS a resource to remove. If
         // a prerequisite is missing (FIX 3: e.g. `scope` null on an adopted stack, or
         // no token), emit `failed` — NOT a silent skip — so `hadFailures` keeps the
@@ -2902,9 +3381,21 @@ async function teardownProviders(target, deps) {
             }
         }
     }
-    // 3. Vercel PROJECT — the dev's `vercel remove` (NEVER a shared org token).
+    // 3. Vercel PROJECT — REST with the rail token, the same one that created it (and the same
+    //    one the domain removal above already uses). The dev's `vercel` session cannot be
+    //    assumed to sit in the team the project lives in; when it does not, the delete fails
+    //    and leaves a billable orphan.
     if (target.vercelProjectId) {
-        outcomes.push(await destroyVercelProject(target, deps.runVercel));
+        if (!vercelToken) {
+            outcomes.push({
+                resource: `Proyecto Vercel ${target.slug}`,
+                status: 'failed',
+                detail: 'sin `VERCEL_TOKEN` en el rail — bórralo a mano en Vercel',
+            });
+        }
+        else {
+            outcomes.push(await destroyVercelProject(target, vercelToken, deps.fetchImpl));
+        }
     }
     // 4. GitHub repo — the dev's `gh repo delete` (NEVER a shared org token).
     if (target.githubRepo) {
@@ -3094,6 +3585,12 @@ export async function runProvision(flags) {
     // patch — it cannot clobber, so it is treated like `--resume` for state-reading.
     const standaloneDomain = hasDomain && flags.services.length === 0;
     // 2. Resolve state. `--force` wins over `--resume` (issue §8): discard + restart.
+    //    🔴 GAP-001: capture whether this project had a provision state BEFORE the discard.
+    //    `clearProvisionState` runs ahead of `buildPlan`, so after it every service reads as
+    //    `create` and the plan is indistinguishable from a bootstrap. That fact is the only
+    //    evidence the greenfield guard has that this project already went through
+    //    provisioning, and this line is the last moment it exists (see `isGreenfieldRun`).
+    const hadPriorState = hasProvisionState(rootDir);
     if (flags.force) {
         clearProvisionState(rootDir);
     }
@@ -3136,6 +3633,14 @@ export async function runProvision(flags) {
     if (repoSlug) {
         result.repo = repoSlug;
     }
+    // GAP-001: decide the initial-migration step WITH the plan (read-only: the greenfield
+    // guard reads the plan + this run's own evidence, the rest reads disk), so `--dry-run`
+    // announces it below and the execution further down uses the very same predicate over
+    // the very same evidence object.
+    const greenfield = { steps, force: flags.force, hadPriorState };
+    if (shouldRunInitialMigration(rootDir, greenfield)) {
+        result.initialMigration = true;
+    }
     if (hasDomain) {
         result.clientDomain = { domain: flags.domain, route: flags.dns };
     }
@@ -3181,6 +3686,11 @@ export async function runProvision(flags) {
     // 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);
+    // 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
+    //      aborts here, with nothing pushed and nothing deployed.
+    await ensureInitialMigration(rootDir, greenfield);
     for (const step of steps) {
         if (step.action === 'skip')
             continue;