@timekast/factory 1.26.0 → 1.28.0

package/dist/commands/provision.js

@@ -26,13 +26,13 @@ import prompts from 'prompts';
 import { FACTORY_ORG } from '../lib/constants.js';
 import { CLIError } from '../lib/cli-error.js';
 import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, ensureCnameRecord, ensureDnsRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, resolveZoneIdForDomain, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, existingProvisionDomains, ORG_ZONE_NAMES, } 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 { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, NEON_MAIN_BRANCH, findNeonProjectAcrossOrgs, listNeonOrgs, resolveNeonOrg, 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, 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';
+import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readRemintState, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
  * `setup:e2e`) reads to create an ISOLATED Neon branch per CI run. provision sets
@@ -206,6 +206,8 @@ export function parseProvisionFlags(argv) {
         services: parseServices(readValueFlag(argv, 'services')),
         team: readValueFlag(argv, 'team'),
         orgId: readValueFlag(argv, 'org-id'),
+        neonOrg: readValueFlag(argv, 'neon-org'),
+        remint: argv.includes('--remint'),
         slug: readValueFlag(argv, 'slug'),
         repo: parseRepoFlag(readValueFlag(argv, 'repo')),
         domain: readValueFlag(argv, 'domain'),
@@ -229,11 +231,18 @@ const SERVICE_LABEL = {
     dns: 'DNS + Resend (dominio del entorno)',
     backlog: 'Backlog central (proyecto en backlog.timekast.mx + API key)',
 };
-/** Build the ordered plan: each requested service is `skip` if complete, else `create`. */
-function buildPlan(services, state) {
+/**
+ * Build the ordered plan: each requested service is `skip` if complete, else
+ * `create`.
+ *
+ * `remint` forces the `neon` step to run even when complete — the whole point of
+ * that flag is to re-enter a finished step, so skipping it here would make the flag
+ * a silent no-op. It changes nothing for any other service.
+ */
+function buildPlan(services, state, opts = {}) {
     return services.map((service) => ({
         service,
-        action: isServiceComplete(state, service) ? 'skip' : 'create',
+        action: isServiceComplete(state, service) && !(opts.remint && service === 'neon') ? 'skip' : 'create',
     }));
 }
 /** Print the plain-text plan (the `--dry-run` and pre-run narration). */
@@ -436,6 +445,51 @@ function neonErrorToCliError(error, projectName, context) {
             return new CLIError(`Falló la llamada a Neon en ${context}: ${error.message}`);
     }
 }
+/**
+ * The branch name the E2E runner clones its throwaway branches FROM, for this repo.
+ *
+ * Read from the repo's own workflow (`E2E_PARENT_BRANCH:` in
+ * `.github/workflows/e2e.yml`), because that is where the value actually lives and the
+ * runner honors the same one (`resolveParentBranchName` in `scripts/tools/neon-branch.ts`).
+ * A provisioned derivative pins `develop` there; the Factory itself pins `production`,
+ * and a project is free to pin anything. Returns `null` when there is no workflow or no
+ * pin — the caller then falls back to `develop` and finally to the project's default
+ * branch.
+ *
+ * 🔴 Assuming `develop` here is what broke `--remint` on the Factory, whose Neon project
+ * has a single branch called `production`: the re-mint would have refused (or, worse,
+ * pushed a DATABASE_URL for a branch the runner never parents on).
+ */
+export function readE2eParentBranch(rootDir) {
+    try {
+        const workflow = readFileSync(join(rootDir, '.github', 'workflows', 'e2e.yml'), 'utf8');
+        const match = workflow.match(/^\s*E2E_PARENT_BRANCH:\s*(\S+)/m);
+        const pinned = match?.[1];
+        // The template ships the placeholder with its anchor comment; an unsubstituted
+        // placeholder is not a branch name.
+        if (!pinned || pinned.startsWith('__'))
+            return null;
+        return pinned;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the branch whose connection string becomes the E2E `DATABASE_URL` secret, on
+ * a project that ALREADY exists. Preference: the repo's pinned parent branch → a branch
+ * literally named `develop` (what provision creates) → the project's default branch.
+ *
+ * Never creates anything: a re-mint repairs credentials, and creating a branch to
+ * satisfy a credential refresh would be a side effect nobody asked for.
+ */
+function pickE2eBranch(branches, pinnedName) {
+    const byName = (name) => branches.find((b) => b.name === name);
+    return ((pinnedName ? byName(pinnedName) : undefined) ??
+        byName(NEON_DEVELOP_BRANCH) ??
+        branches.find((b) => b.isDefault) ??
+        branches[0]);
+}
 /** The GitHub repo (`owner/name`) the project-scoped secret is pushed to. */
 function neonSecretRepo(state) {
     // `state.github.repo` carries the RESOLVED repo: `runProvision` seeds it before
@@ -464,13 +518,22 @@ async function setGithubSecret(key, value, repo) {
  * after `develop`, so a mid-step failure leaves a resumable partial state
  * (issue §6 + §8 Gherkin).
  *
- * Endpoint order (asserted by the unit test): POST /projects → POST branches
- * (develop) → GET connection_uri (main) → GET connection_uri (develop) →
- * POST /api_keys → `gh secret set`.
+ * Endpoint order (asserted by the unit test): GET /users/me/organizations (only
+ * when the org is not already known) → POST /projects → POST branches (develop) →
+ * GET connection_uri (develop) → POST /organizations/{org_id}/api_keys →
+ * `gh secret set`.
+ *
+ * The org resolution sits AFTER the `apiKeySecretDone` guard on purpose: a
+ * completed Neon step must still make zero network calls.
  *
  * `--resume` short-circuits ENTIRELY when `state.neon.projectId` already exists
  * (caller skips the step via `isServiceComplete`; this is a defensive guard too).
+ * `deps.remint` is the one switch that deliberately re-enters a completed step.
  *
+ * @returns the project-scoped key minted in THIS run, or `null` when nothing was
+ *   minted (completed step, no remint). The value is a credential: it is never
+ *   persisted to the state, only handed to the caller so the `.env.local` step of
+ *   the same process can write it.
  * @throws {CLIError} mapping the Neon §8 edges (401/402/409/429) and a `develop`
  *   failure (state saved partial → resumable). A failed `gh secret set` does NOT
  *   abort: it records `apiKeySecretPending` and reports (issue §8).
@@ -479,8 +542,10 @@ export async function provisionNeon(rootDir, state, deps = {}) {
     // Fully complete only when the FINAL step landed (key minted + stored as the GH
     // secret). developBranchId alone is NOT "done": re-entering must finish the
     // remaining steps WITHOUT re-minting the key. Every sub-step below is idempotent.
-    if (state.neon?.apiKeySecretDone)
-        return;
+    // `--remint` is the deliberate exception: it exists to re-issue a key that was
+    // revoked out-of-band, which is the one case a "done" step must be re-entered.
+    if (state.neon?.apiKeySecretDone && !deps.remint)
+        return null;
     const envPath = deps.envPath ?? defaultEnvPath();
     const apiKey = readNeonApiKey(envPath);
     if (!apiKey) {
@@ -489,16 +554,59 @@ export async function provisionNeon(rootDir, state, deps = {}) {
     }
     const setSecret = deps.setSecret ?? setGithubSecret;
     const apiDeps = { fetchImpl: deps.fetchImpl };
-    // Neon org-id from the rail (`NEON_ORGANIZATION_ID`), like the Vercel team-id —
-    // org-fixed config, not hardcoded. Neon REQUIRES it for org-scoped API keys.
-    const orgId = readGateValue('NEON_ORGANIZATION_ID', envPath) ?? undefined;
+    // See `persistState`: an adopted stack's state file must not be overwritten with
+    // this step's shape. `saveState` is the ONLY writer below.
+    const persist = deps.persistState ?? true;
+    const saveState = () => {
+        if (persist)
+            writeProvisionState(rootDir, state);
+    };
+    // WHICH org. Three sources, and which one applies depends on whether the project
+    // already exists — that distinction is the whole point:
+    //   - already recorded in the state → use it verbatim, no call, no guessing;
+    //   - exists in Neon but the state predates `orgId` (or this is a --remint on an
+    //     older stack) → read it OFF THE PROJECT by sweeping the orgs the key sees;
+    //   - brand new → resolve the selector / the rail default / the only org.
+    // Pointing a teardown or a re-mint at the default instead of the project's real
+    // org is exactly the class of error this whole change is fixing.
+    let orgId = state.neon?.orgId;
+    if (!orgId) {
+        try {
+            if (state.neon?.projectId) {
+                const found = await findNeonProjectAcrossOrgs(apiKey, state.projectName, apiDeps);
+                orgId = found?.org.id;
+            }
+            if (!orgId) {
+                const selector = deps.neonOrg ?? readGateValue('NEON_ORG', envPath) ?? undefined;
+                orgId = (await resolveNeonOrg(apiKey, selector, apiDeps)).id;
+            }
+        }
+        catch (error) {
+            if (error instanceof NeonApiError) {
+                throw neonErrorToCliError(error, state.projectName, 'resolver la organización de Neon');
+            }
+            // resolveNeonOrg / findNeonProjectAcrossOrgs throw plain Errors whose message
+            // is already the es-MX text the user needs; surface it as-is.
+            throw new CLIError(error instanceof Error ? error.message : String(error));
+        }
+    }
     // 1. Reuse the project from a partial run; create it only if missing. Persist it
     //    immediately so a branch failure leaves projectId + mainBranchId durable.
+    //
+    // 🔴 A RECORDED `projectId` is sufficient to reuse, and this is not a style
+    // preference. This condition used to require `mainBranchId` too, so a state that
+    // carried the project but not that branch fell through to CREATE — and produced a
+    // SECOND Neon project for a derivative that already had one, with the CLI then
+    // pointing the repo's secrets and `.env.local` at the empty one. That is exactly
+    // what happened on a real client repo (2026-09-12) the first time `--remint` ran
+    // over an adopted stack, whose shape never recorded `mainBranchId`.
+    // When the primary branch is genuinely needed (only to parent a missing `develop`),
+    // it is resolved from Neon below — never by creating anything.
     let projectId;
     let mainBranchId;
-    if (state.neon?.projectId && state.neon?.mainBranchId) {
+    if (state.neon?.projectId) {
         projectId = state.neon.projectId;
-        mainBranchId = state.neon.mainBranchId;
+        mainBranchId = state.neon.mainBranchId ?? '';
     }
     else {
         let project;
@@ -513,31 +621,73 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         }
         projectId = project.projectId;
         mainBranchId = project.mainBranchId;
-        state.neon = { projectId, mainBranchId, developBranchId: '' };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId: '' };
+        saveState();
     }
     // 2. CLEAN `develop` branch — reuse the recorded id; else create it (idempotent
     //    on a 409: createDevelopBranch reuses an existing develop) and persist the id
     //    IMMEDIATELY (FIX 6 — it was saved only at step 3, so a connection-string
     //    failure lost it and the resume re-created → 409).
     let developBranchId = state.neon?.developBranchId ?? '';
+    if (!developBranchId && deps.remint) {
+        // A re-mint over a project whose working branch the state never recorded (an
+        // adopted stack) resolves it from Neon, honoring whatever this repo pinned as the
+        // E2E parent. It must NOT create a branch: see `pickE2eBranch`.
+        let branches;
+        try {
+            branches = await listNeonBranches(apiKey, projectId, apiDeps);
+        }
+        catch (error) {
+            if (error instanceof NeonApiError) {
+                throw neonErrorToCliError(error, state.projectName, 'listar los branches del proyecto');
+            }
+            throw error;
+        }
+        const picked = pickE2eBranch(branches, readE2eParentBranch(rootDir));
+        if (!picked) {
+            throw new CLIError(`El proyecto Neon \`${projectId}\` no reporta ningún branch, así que no puedo ` +
+                'saber de cuál sacar el `DATABASE_URL` de E2E. Revísalo en la consola de Neon.');
+        }
+        developBranchId = picked.id;
+        console.log(`  · Branch de E2E para el \`DATABASE_URL\`: ${picked.name}`);
+    }
     if (!developBranchId) {
+        // The parent of a new `develop` is the project's primary branch. An adopted state
+        // does not record it, so resolve it from Neon rather than assume — and rather than
+        // let a create run with an empty parent.
+        if (!mainBranchId) {
+            try {
+                const branches = await listNeonBranches(apiKey, projectId, apiDeps);
+                mainBranchId =
+                    branches.find((b) => b.name === NEON_MAIN_BRANCH)?.id ?? branches[0]?.id ?? '';
+            }
+            catch (error) {
+                if (error instanceof NeonApiError) {
+                    throw neonErrorToCliError(error, state.projectName, 'leer los branches del proyecto para ubicar el branch primario');
+                }
+                throw error;
+            }
+            if (!mainBranchId) {
+                throw new CLIError(`El proyecto Neon \`${projectId}\` no reporta ningún branch, así que no puedo ` +
+                    'crear `develop` sin inventar recursos. Revísalo en la consola de Neon.');
+            }
+        }
         try {
             developBranchId = await createDevelopBranch(apiKey, projectId, mainBranchId, apiDeps);
         }
         catch (error) {
             // Save the partial state (issue §8 Gherkin: "guarda el state parcial").
             // IDs only — never a connection string (those are re-derived from Neon on demand).
-            state.neon = { projectId, mainBranchId, developBranchId: '' };
-            writeProvisionState(rootDir, state);
+            state.neon = { projectId, orgId, mainBranchId, developBranchId: '' };
+            saveState();
             if (error instanceof NeonApiError) {
                 throw new CLIError(`El proyecto Neon se creó pero falló la creación del branch \`develop\` (${error.message}).\n` +
                     'El estado parcial se guardó; reintenta con `--resume` para crear solo el branch develop.');
             }
             throw error;
         }
-        state.neon = { projectId, mainBranchId, developBranchId };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId };
+        saveState();
     }
     // 3. Read the develop branch's POOLED connection string (idempotent GET) — the
     //    ONLY string this step needs, for the E2E `DATABASE_URL` secret below. provision
@@ -554,14 +704,25 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         }
         throw error;
     }
-    // 4. Mint a PROJECT-SCOPED API key (blast radius = this project only). Only the
-    //    `apiKeySecretDone` guard above prevents re-minting; a resume after a pending
-    //    secret push DOES re-mint (the prior key value was never persisted — it is a
-    //    credential) and the old key is left orphaned. Acceptable: it only happens
-    //    when the GH secret push keeps failing (e.g. the repo does not exist yet).
+    // 4. Mint a PROJECT-SCOPED API key — blast radius = this project only, and now
+    //    actually so: the key comes from `POST /organizations/{org_id}/api_keys`,
+    //    which 404s on a sibling project (the old `POST /api_keys` silently returned
+    //    a personal, all-orgs key). Only the `apiKeySecretDone` guard above prevents
+    //    re-minting; a resume after a pending secret push DOES re-mint (the prior key
+    //    value was never persisted — it is a credential) and the old key is left
+    //    orphaned. Acceptable: it only happens when the GH secret push keeps failing
+    //    (e.g. the repo does not exist yet).
+    const keyName = `${state.projectName}-e2e`;
     let projectKey;
     try {
-        projectKey = await createProjectApiKey(apiKey, projectId, `${state.projectName}-e2e`, apiDeps);
+        // `--remint` revokes the live key BEFORE issuing its replacement, so the org
+        // does not accumulate a key per rotation. Best-effort by contract: a key that
+        // was already revoked out-of-band (the case that motivated --remint) is a
+        // no-op here, not an error.
+        if (deps.remint) {
+            await deleteNeonApiKeysByName(apiKey, orgId, keyName, apiDeps);
+        }
+        projectKey = await createProjectApiKey(apiKey, orgId, projectId, keyName, apiDeps);
     }
     catch (error) {
         if (error instanceof NeonApiError) {
@@ -579,17 +740,19 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         await setSecret(NEON_KEY_SECRET, projectKey, repo);
         await setSecret(NEON_PROJECT_ID_SECRET, projectId, repo);
         await setSecret(E2E_DATABASE_URL_SECRET, developDatabaseUrl, repo);
-        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretDone: true };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId, apiKeySecretDone: true };
+        saveState();
+        return projectKey;
     }
     catch {
-        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretPending: true };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId, apiKeySecretPending: true };
+        saveState();
         console.warn(`⚠ No se pudieron guardar los secrets de E2E ` +
             `(\`${NEON_KEY_SECRET}\`/\`${NEON_PROJECT_ID_SECRET}\`/\`${E2E_DATABASE_URL_SECRET}\`) ` +
             `en \`${neonSecretRepo(state)}\` (¿el repo no existe aún o falta permiso?).\n` +
             '  La API key project-scoped se creó; reintenta con `--resume` cuando el repo exista.');
     }
+    return projectKey;
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // BSYNC-003 — `backlog`: register the project in backlog.timekast.mx
@@ -961,13 +1124,18 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     else if (envLocal === 'skipped') {
         console.log('  ⏭ .env.local ya existía (no se sobrescribe — usa --force para regenerarlo)');
     }
-    // Local E2E creds: write NEON_API_KEY (the org key from the rail — already on the
-    // dev's host) + NEON_PROJECT_ID so `pnpm test:e2e` runs locally with zero manual
+    // Local E2E creds: write the PROJECT-SCOPED key minted by `provisionNeon` in this
+    // same process + NEON_PROJECT_ID, so `pnpm test:e2e` runs locally with zero manual
     // `setup:e2e`. Both are PROVISION_OWNED → never pushed to Vercel. Safe on a skipped
-    // `.env.local` (setEnvLine touches only these two keys). The key value is never printed.
-    if (state.neon?.projectId &&
-        writeE2eLocalCreds(rootDir, state.neon.projectId, readNeonApiKey(envPath))) {
-        console.log('  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)');
+    // `.env.local` (setEnvLine touches only these two keys). The key value is never
+    // printed. NEVER falls back to the rail key: that is what leaked an all-orgs
+    // credential into every derivative's `.env.local`.
+    const e2eKey = deps.neonProjectKey ?? null;
+    if (state.neon?.projectId && writeE2eLocalCreds(rootDir, state.neon.projectId, e2eKey)) {
+        console.log(e2eKey
+            ? '  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)'
+            : '  ＋ .env.local (NEON_PROJECT_ID) · ⚠ sin NEON_API_KEY: la key de este run no se acuñó — ' +
+                'córrelo con `--remint` para refrescarla');
     }
     // Email config: write the org Resend key (from the rail) + the fixed EMAIL_FROM so local
     // sends (`invite:admin`, magic-link, `db:seed`) DELIVER instead of the console fallback.
@@ -1245,7 +1413,7 @@ export function writeE2eWorkflow(rootDir) {
  * PROV-004 — the `github` step: build the git substrate, create the Vercel PROJECT,
  * connect the GitHub repo (GitHub App gate), confirm `productionBranch: main`,
  * write `.vercel/project.json`, and activate the E2E workflow. Migrations run in the
- * Vercel build (`vercel-build`: `pnpm db:migrate && pnpm build`), NOT a GitHub Actions
+ * Vercel build (`vercel-build`: `pnpm build && pnpm db:migrate`), NOT a GitHub Actions
  * workflow. HIGH-risk: every failure is recoverable via `--resume`.
  *
  * Order (asserted by the unit test): git substrate (rename → remote add → push
@@ -1334,7 +1502,7 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
     //    the template is absent. It lands in the working tree and is committed below.
     //
     //    Migrations are NOT a GitHub Actions workflow: they run in the Vercel build
-    //    (`vercel-build`: `pnpm db:migrate && pnpm build`, shipped in package.json),
+    //    (`vercel-build`: `pnpm build && pnpm db:migrate`, shipped in package.json),
     //    so every deployment migrates ITS target's DB (production←main, preview←develop)
     //    before building — no migrate.yml, no Deploy Hook, no manual step.
     const e2e = writeE2eWorkflow(rootDir);
@@ -1367,7 +1535,7 @@ export async function provisionGithubVercel(rootDir, state, teamId, deps = {}) {
  * before provision activated this workflow, so it lives only in the working tree
  * until committed here. (Migrations are not part of THIS commit, but they do have one:
  * `ensureInitialMigration` commits the `0000` earlier in the run, with its own pathspec.
- * The Vercel build only APPLIES it — `vercel-build` runs `pnpm db:migrate && pnpm build`,
+ * The Vercel build only APPLIES it — `vercel-build` runs `pnpm build && pnpm db:migrate`,
  * there is no migration workflow.) Idempotent — when a `--resume`
  * finds it already committed, `git add` stages nothing and the commit/push is skipped.
  */
@@ -1418,7 +1586,7 @@ const INITIAL_MIGRATION_COMMIT = 'chore(db): add the initial database migration'
 const INITIAL_MIGRATION_LABEL = 'Migración inicial de la base (0000 de Drizzle)';
 /**
  * The branch the step commits on and pushes: the one `vercel-build` runs
- * `pnpm db:migrate && pnpm build` from for PRODUCTION. Named, never inlined
+ * `pnpm build && pnpm db:migrate` from for PRODUCTION. Named, never inlined
  * (CODING.md §5) — it appears in the checkout guard, in both pushes and in the
  * remote confirmation, and those four have to mean the same branch.
  */
@@ -1567,7 +1735,7 @@ async function confirmMigrationOnRemote(rootDir, runGit) {
 /**
  * Generate the initial Drizzle migration, commit it with its OWN pathspec and get it to
  * the remote BEFORE Vercel builds the tree (PROV-004 pushes `main`; `vercel-build` runs
- * `pnpm db:migrate && pnpm build`). Without this a fresh derivative deploys against an
+ * `pnpm build && pnpm db:migrate`). Without this a fresh derivative deploys against an
  * empty database.
  *
  * Order and its reasons:
@@ -1706,7 +1874,7 @@ export async function ensureInitialMigration(rootDir, evidence, deps = {}) {
         return;
     }
     // Un `try` por push, y no uno compartido: `main` es el que le importa a producción
-    // (`vercel-build` = `pnpm db:migrate && pnpm build`) y `develop` puede fallar solo
+    // (`vercel-build` = `pnpm build && pnpm db:migrate`) y `develop` puede fallar solo
     // (non-fast-forward con un remoto divergido). Con un `try` compartido, esa falla de
     // `develop` imprimía "no pude pushear la migración" y se saltaba la confirmación —
     // un diagnóstico falso justo cuando `main` SÍ había llegado.
@@ -2233,7 +2401,7 @@ async function resolveDnsToken(route, envPath, headless) {
  * PROV-006 — attach the client's DEFINITIVE domain to the Vercel project, create
  * (or print, for `registrar`) its DNS record, poll Vercel until verified, and on
  * success: retire the interim prod domain (with explicit confirmation), update
- * `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL`, and register the domain in Resend.
+ * `EMAIL_FROM` + `NEXT_PUBLIC_APP_URL`, and register the domain in Resend.
  *
  * Standalone-safe: runnable as a PATCH over an existing provision (the `dns` step
  * of PROV-005 already attached the interim domains) or inside the initial run. It
@@ -2246,7 +2414,7 @@ async function resolveDnsToken(route, envPath, headless) {
  *   - Resend DNS records (BOOT-003) → `ensureDnsRecord` create-or-PATCH (a rotated
  *     DKIM is PATCHed in place, never deleted); a Resend poll timeout is a WARNING
  *     (pending-verification, resumable), never a step failure.
- *   - `AUTH_URL`/`NEXTAUTH_URL` already correct → the upsert PATCH is omitted.
+ *   - `EMAIL_FROM`/`NEXT_PUBLIC_APP_URL` already correct → the upsert PATCH is omitted.
  *
  * On timeout the state is left `clientDomainStatus: pending-verification` (resumable);
  * on success it is `live`.
@@ -2462,7 +2630,7 @@ async function deleteInterimCname(interim, envPath, fetchImpl) {
     }
 }
 /**
- * Update `EMAIL_FROM` + `AUTH_URL`/`NEXTAUTH_URL` + `NEXT_PUBLIC_APP_URL` +
+ * Update `EMAIL_FROM` + `NEXT_PUBLIC_APP_URL` +
  * `WEBAUTHN_RP_ID` to the client domain in the Vercel env, per-target and
  * idempotently (PROV-006 §4 + BOOT-004). Lists the existing vars once and upserts
  * each entry via `upsertEnvVar`, which reconciles a key that the substrate left
@@ -2483,20 +2651,27 @@ async function deleteInterimCname(interim, envPath, fetchImpl) {
  * discipline holds).
  */
 async function updateDomainEnv(projectId, token, teamId, domain, deps) {
-    const authUrl = `https://${domain}`;
+    const appOrigin = `https://${domain}`;
     const plan = [
         // EMAIL_FROM uses the dedicated mail subdomain (`updates.<domain>`), NOT the apex
-        // — the apex carries the client's corporate mail. AUTH_URL stays the app domain.
+        // — the apex carries the client's corporate mail.
         {
             key: 'EMAIL_FROM',
             value: `noreply@${mailDomainFor(domain)}`,
             target: ['production', 'preview'],
         },
-        { key: 'AUTH_URL', value: authUrl, target: ['production', 'preview'] },
-        { key: 'NEXTAUTH_URL', value: authUrl, target: ['production', 'preview'] },
-        // Keep the public app origin in lockstep with AUTH_URL once a client domain lands
+        // 🔴 AUTH_URL / NEXTAUTH_URL are DELIBERATELY ABSENT — do not re-add them.
+        // `next-auth/lib/env.js` rewrites the origin of every auth request to their value,
+        // so scoping either to `preview` pins all branch deployments' callbacks to this one
+        // host and kills their sign-in. `trustHost` (auth.config.ts) already infers the
+        // origin per request, which is correct on production AND on each preview.
+        // Auth needs nothing here; the domain reaches the app through NEXT_PUBLIC_APP_URL
+        // below, which is what `getAppUrl()` reads for email links (src/lib/env.ts).
+        // A project that enables OAuth and must pin the callback to a fixed host sets it
+        // manually, `production` only, knowing it forfeits preview sign-in.
+        // Keep the public app origin pointing at the client domain once it lands
         // (the substrate set it to the interim domain in buildEnvPlan; this re-points it).
-        { key: 'NEXT_PUBLIC_APP_URL', value: authUrl, target: ['production', 'preview'] },
+        { key: 'NEXT_PUBLIC_APP_URL', value: appOrigin, target: ['production', 'preview'] },
         // WebAuthn rpID is the registrable HOST, never a URL — the bare domain (BOOT-004).
         // PRODUCTION only: the interim dev domain remains the preview rpID (the dev domain
         // is never retired), so the intentional split pair from buildEnvPlan is preserved.
@@ -2532,7 +2707,7 @@ function printClientDomainPlan(domain, interim, route, confirm) {
     console.log(`  … sondea GET /v9/projects/.../domains/${domain} hasta verified:true (o timeout)`);
     console.log(`  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim} ` +
         `(el dev ${domain}-dev se conserva)`);
-    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · AUTH_URL=https://${domain} · NEXTAUTH_URL=https://${domain} · NEXT_PUBLIC_APP_URL=https://${domain}`);
+    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · NEXT_PUBLIC_APP_URL=https://${domain}`);
     console.log(`  ↻ WEBAUTHN_RP_ID=${domain} (solo production — las passkeys del rpID interino quedan invalidadas; el preview conserva el rpID dev)`);
     console.log(`  ＋ Resend: POST /domains { name: ${mailDomainFor(domain)} } (subdominio mail, no el apex)`);
     if (route === 'registrar') {
@@ -2548,15 +2723,28 @@ function printClientDomainPlan(domain, interim, route, confirm) {
  * `vercel` (PROV-003) and `dns` (PROV-005) are implemented. `teamId` is required
  * for the Vercel + GitHub + DNS steps (validated upstream).
  */
-async function runServiceStep(service, rootDir, state, flags) {
+async function runServiceStep(service, rootDir, state, flags, 
+/**
+ * Carries the project-scoped Neon key from the `neon` step to the `vercel` step
+ * (which writes `.env.local`) WITHIN this process. A credential, so it is never
+ * persisted — the state has no field for it and must not grow one.
+ */
+runCtx = {}) {
     switch (service) {
         case 'neon':
-            await provisionNeon(rootDir, state);
+            runCtx.neonProjectKey = await provisionNeon(rootDir, state, {
+                neonOrg: flags.neonOrg,
+                remint: flags.remint,
+                persistState: runCtx.persistState,
+            });
             break;
         case 'vercel':
             // PROV-003: push env (teamId on every call) + write .vercel/project.json +
             // pnpm install. The Vercel PROJECT itself is created by PROV-004.
-            await provisionVercel(rootDir, state, flags.team, { force: flags.force });
+            await provisionVercel(rootDir, state, flags.team, {
+                force: flags.force,
+                neonProjectKey: runCtx.neonProjectKey,
+            });
             break;
         case 'github':
             // PROV-004: git substrate (rename → remote add → push main) + create the
@@ -2693,25 +2881,48 @@ function projectsToCandidates(projects, slug, teamId) {
     }));
 }
 /**
- * Reconstruct the Neon project id + `develop` branch id (read-only). Filters the
- * org's projects by slug; once the project resolves, lists its branches to find
- * the `develop` one. A branch lookup failure leaves the branch id `unknown`
- * without failing the whole adopt (issue §4).
+ * Reconstruct the Neon project id + its org + the `develop` branch id (read-only).
+ *
+ * Sweeps EVERY org the rail key can reach (`GET /users/me/organizations`, then one
+ * project listing per org) and filters by slug across all of them. The org is
+ * therefore READ OFF the project that matches — never taken from a configured
+ * default, which may well point somewhere else: a backfill that recorded the
+ * default's org id would aim a later `--destroy` at the wrong organization.
+ *
+ * The per-org listing still passes `org_id`, which Neon REQUIRES (it answers
+ * `400 org_id is required` without it).
+ *
+ * Once the project resolves, lists its branches to find the `develop` one. A branch
+ * lookup failure leaves the branch id `unknown` without failing the whole adopt
+ * (issue §4).
  */
-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}`,
-    }));
+async function adoptNeon(slug, apiKey, deps, recordAmbiguity) {
+    const apiDeps = { fetchImpl: deps.fetchImpl };
+    const orgs = await listNeonOrgs(apiKey, apiDeps);
+    const candidates = [];
+    /** projectId → owning org id, so the chosen candidate can report its org. */
+    const orgOfProject = new Map();
+    let scanned = 0;
+    for (const org of orgs) {
+        const projects = await listNeonProjects(apiKey, org.id, apiDeps);
+        scanned += projects.length;
+        for (const p of matchProjectsBySlug(projects, slug)) {
+            orgOfProject.set(p.id, org.id);
+            candidates.push({
+                id: p.id,
+                name: `${p.name} · ${org.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 };
+        console.log(`  · Ningún proyecto de Neon se parece a \`${slug}\` (revisé ${scanned} en ${orgs.length} organización(es)) — \`neonProjectId: unknown\`.`);
+        return { projectId: null, orgId: null, branchDevId: null };
     }
     const projectId = await resolveCandidate('Neon', candidates, deps, recordAmbiguity);
     if (!projectId)
-        return { projectId: null, branchDevId: null };
+        return { projectId: null, orgId: null, branchDevId: null };
+    const orgId = orgOfProject.get(projectId) ?? null;
     // Resolve the develop branch (best-effort — a failure → unknown, not a hard stop).
     let branchDevId = null;
     try {
@@ -2721,7 +2932,7 @@ async function adoptNeon(slug, apiKey, orgId, deps, recordAmbiguity) {
     catch {
         branchDevId = null;
     }
-    return { projectId, branchDevId };
+    return { projectId, orgId, branchDevId };
 }
 /**
  * Reconstruct the GitHub repo (read-only) via `gh repo view {org}/{slug} --json
@@ -2932,17 +3143,16 @@ export async function runAdopt(flags, deps = {}) {
     // Neon (GET /projects + branches) — needs the rail key. Absent → `unknown` (the
     // Gherkin "Provider Neon sin token disponible" path).
     let neonProjectId = null;
+    let neonOrgId = 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, neonOrgId, adeps, (list) => {
+            const neon = await adoptNeon(slug, neonApiKey, adeps, (list) => {
                 candidates.neon = list;
             });
             neonProjectId = neon.projectId;
+            neonOrgId = neon.orgId;
             neonBranchDevId = neon.branchDevId;
         }
         catch {
@@ -2964,6 +3174,7 @@ export async function runAdopt(flags, deps = {}) {
         slug,
         vercelProjectId: vercelProjectId ?? ADOPT_UNKNOWN,
         neonProjectId: neonProjectId ?? ADOPT_UNKNOWN,
+        neonOrgId: neonOrgId ?? ADOPT_UNKNOWN,
         neonBranchDevId: neonBranchDevId ?? ADOPT_UNKNOWN,
         githubRepo: githubRepo ?? ADOPT_UNKNOWN,
         domains,
@@ -2976,6 +3187,7 @@ export async function runAdopt(flags, deps = {}) {
         slug,
         vercelProjectId: partial.vercelProjectId,
         neonProjectId: partial.neonProjectId,
+        neonOrgId: partial.neonOrgId,
         neonBranchDevId: partial.neonBranchDevId,
         githubRepo: partial.githubRepo,
         domains,
@@ -3086,18 +3298,42 @@ async function destroyNeonBranch(target, apiKey, fetchImpl) {
  * project id, so it also tears down a PARTIAL stack whose develop branch never got
  * created (FIX 9). A 404 → already gone (§8). The dev's key does this, never the
  * shared org create-only key.
+ *
+ * The org id is resolved BEFORE the nuke, because after it the project is gone and
+ * nothing can say which org owned it any more. It comes from the state when present
+ * and is read off the project otherwise (every stack provisioned before `orgId`
+ * existed takes that path). Unresolvable → the project is still nuked and only the
+ * key cleanup is skipped, with the key named so it can be revoked by hand.
  */
 async function destroyNeonProject(target, apiKey, fetchImpl) {
     const resource = `Neon project (${target.neonProjectId})`;
     if (!target.neonProjectId) {
         return { resource: 'Neon project', status: 'skipped', detail: 'sin id en el estado' };
     }
+    const keyName = `${target.slug}-e2e`;
+    let orgId = target.neonOrgId;
+    if (!orgId) {
+        try {
+            const found = await findNeonProjectAcrossOrgs(apiKey, target.slug, { fetchImpl });
+            orgId = found?.org.id ?? null;
+        }
+        catch {
+            orgId = null;
+        }
+    }
     try {
         await deleteNeonProject(apiKey, target.neonProjectId, { fetchImpl });
+        if (!orgId) {
+            return {
+                resource,
+                status: 'removed',
+                detail: `proyecto eliminado (nuke) — no pude resolver la org, revoca \`${keyName}\` a mano`,
+            };
+        }
         // Project gone — clean the project-scoped API key(s) it minted (`{slug}-e2e`)
         // so the Neon org does not accumulate dead keys across provisions/tests.
         // Best-effort (never throws): the project nuke already succeeded.
-        const keysDeleted = await deleteNeonApiKeysByName(apiKey, `${target.slug}-e2e`, { fetchImpl });
+        const keysDeleted = await deleteNeonApiKeysByName(apiKey, orgId, keyName, { fetchImpl });
         return {
             resource,
             status: 'removed',
@@ -3594,17 +3830,51 @@ export async function runProvision(flags) {
     if (flags.force) {
         clearProvisionState(rootDir);
     }
+    // `--remint` re-enters an EXISTING stack by definition: it re-issues the key of a
+    // project that is already provisioned. Requiring `--resume` alongside it would be a
+    // trap with no upside — there is nothing to start fresh — so it reads the state the
+    // same way a resume does, and the existing-state guard below lets it through.
+    const reentersState = flags.resume || flags.remint || standaloneDomain;
     let state = null;
-    if ((flags.resume || standaloneDomain) && !flags.force) {
-        state = readProvisionState(rootDir); // throws CLIError on corrupt → hints --force
+    // A `--remint` reads the state through the SHAPE-TOLERANT reader, because the whole
+    // existing fleet carries the adopted shape (`slug`/`neonProjectId`, no `neon` block)
+    // and `readProvisionState` rejects it. Without this, the one command written to
+    // repair those projects failed on exactly them. When that shape is what we got, the
+    // step must not persist (see `persistState`): writing this step's shape over an
+    // adopted file would drop `vercelProjectId`, `githubRepo` and the domains.
+    let remintOverAdopted = false;
+    if (reentersState && !flags.force) {
+        try {
+            state = readProvisionState(rootDir); // throws CLIError on corrupt → hints --force
+        }
+        catch (error) {
+            // `readProvisionState` THROWS on a shape it does not recognize, and the adopted
+            // shape is one of those — so for a re-mint the throw is not an error, it is the
+            // signal to read the other shape. Any other flag keeps the original behavior:
+            // a genuinely corrupt file must still abort loudly.
+            if (!flags.remint)
+                throw error;
+            state = null;
+        }
+        if (!state && flags.remint) {
+            state = readRemintState(rootDir);
+            remintOverAdopted = state !== null;
+        }
         if (!state) {
             throw new CLIError(standaloneDomain
                 ? '`--domain` en modo patch requiere un provision existente (`.timekast/provision.json`), ' +
                     'pero no hay estado. Corre el provision inicial (`--services=...`) primero.'
-                : 'No hay estado de provision para retomar (`--resume`). Corre sin `--resume` para empezar.');
+                : flags.remint
+                    ? '`--remint` reacuña la key de un proyecto YA provisionado, pero no hay estado ' +
+                        '(`.timekast/provision.json`) en este directorio. Corre el provision inicial ' +
+                        '(`--services=neon`) primero.'
+                    : 'No hay estado de provision para retomar (`--resume`). Corre sin `--resume` para empezar.');
         }
     }
-    else if (!flags.force && flags.services.length > 0 && hasProvisionState(rootDir)) {
+    else if (!flags.force &&
+        !flags.remint &&
+        flags.services.length > 0 &&
+        hasProvisionState(rootDir)) {
         // A fresh (non-resume, non-force) service run must not clobber a prior state.
         throw new CLIError('Ya existe un estado de provision (`.timekast/provision.json`). ' +
             'Usa `--resume` para retomarlo o `--force` para descartarlo y empezar de cero.');
@@ -3622,7 +3892,7 @@ export async function runProvision(flags) {
     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 steps = buildPlan(flags.services, state, { remint: flags.remint });
     const result = {
         projectName,
         lifecycle: state?.lifecycle ?? lifecycle,
@@ -3685,20 +3955,35 @@ 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);
+    //
+    // 🔴 Never for a re-mint over an ADOPTED stack. This baseline write is the one that
+    // actually clobbered a client repo's adopted state file on 2026-09-12: the step
+    // itself was already guarded, and this line — three screens away from it — was not.
+    // An adopted file holds `vercelProjectId`, `githubRepo` and the domains, none of
+    // which this shape carries, so writing it here loses them for good.
+    if (!remintOverAdopted)
+        writeProvisionState(rootDir, runState);
     // 5.0. Initial migration (GAP-001) — BEFORE the steps, so the `.sql` is committed
     //      before the `github` step pushes `main` and Vercel builds the remote tree
-    //      (`vercel-build` = `pnpm db:migrate && pnpm build`). A failed generate/install
+    //      (`vercel-build` = `pnpm build && pnpm db:migrate`). A failed generate/install
     //      aborts here, with nothing pushed and nothing deployed.
     await ensureInitialMigration(rootDir, greenfield);
+    // In-memory carrier for the project-scoped Neon key (see `runServiceStep`), plus
+    // whether this run may persist the step-by-step state at all.
+    const runCtx = {
+        persistState: !remintOverAdopted,
+    };
     for (const step of steps) {
         if (step.action === 'skip')
             continue;
-        await runServiceStep(step.service, rootDir, runState, flags);
+        await runServiceStep(step.service, rootDir, runState, flags, runCtx);
         // Persist after each create. PROV-002 (neon) already writes its state
         // atomically inside the step; the remaining stubs record nothing yet, and
-        // this write keeps the baseline durable for them too.
-        writeProvisionState(rootDir, runState);
+        // this write keeps the baseline durable for them too. Skipped entirely for a
+        // re-mint over an adopted stack, whose state file is a different shape we must
+        // not overwrite.
+        if (!remintOverAdopted)
+            writeProvisionState(rootDir, runState);
     }
     // 5a. Retry the E2E GitHub Secrets if Neon recorded them pending. Neon runs BEFORE
     //     the git substrate, so on a fresh bootstrap the repo may not exist yet when it
@@ -3709,16 +3994,25 @@ export async function runProvision(flags) {
     //     Without this, CI E2E stays credential-less until a MANUAL `--resume`.
     if (!flags.dryRun && runState.neon?.apiKeySecretPending && runState.github?.repo) {
         console.log('\n↻ Reintentando los secrets de E2E ahora que el repo existe...');
-        await provisionNeon(rootDir, runState);
-        writeProvisionState(rootDir, runState);
+        runCtx.neonProjectKey = await provisionNeon(rootDir, runState, {
+            neonOrg: flags.neonOrg,
+            remint: flags.remint,
+            persistState: !remintOverAdopted,
+        });
+        if (!remintOverAdopted)
+            writeProvisionState(rootDir, runState);
     }
     // 5a.2. Ensure the local E2E creds are in `.env.local` even on a resume/adopt where
     //       the Vercel substrate was already `done` (writeE2eLocalCreds only runs inside
     //       that step's first pass). Idempotent — `setEnvLine` replaces/appends the two
     //       keys — so `pnpm test:e2e` works locally without a manual edit after a re-run.
     if (!flags.dryRun && runState.neon?.projectId) {
-        if (writeE2eLocalCreds(rootDir, runState.neon.projectId, readNeonApiKey())) {
-            console.log('  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)');
+        const e2eKey = runCtx.neonProjectKey ?? null;
+        if (writeE2eLocalCreds(rootDir, runState.neon.projectId, e2eKey)) {
+            console.log(e2eKey
+                ? '  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)'
+                : '  ＋ .env.local (NEON_PROJECT_ID) · ⚠ sin NEON_API_KEY: no se acuñó una key en este run — ' +
+                    'corre `factory provision --services=neon --remint` para refrescarla');
         }
     }
     // Same for email config on resume/adopt (writeEmailLocalCreds only runs in the first