@timekast/factory 1.26.0 → 1.28.0

package/dist/lib/initial-migration.js

@@ -4,7 +4,7 @@
  *
  * WHY THIS MODULE EXISTS. `factory provision` never ran `db:generate`, so a fresh
  * derivative was born with a schema and no migrations while its `vercel-build`
- * (`pnpm db:migrate && pnpm build`) migrated an empty database on the first deploy.
+ * (`pnpm build && pnpm db:migrate`) migrated an empty database on the first deploy.
  * The provision step that closes that gap has to decide, from disk alone, whether
  * generating and committing a `0000` is the right thing to do — and the cost of a
  * wrong "yes" is asymmetric.
@@ -12,11 +12,17 @@
  * 🔴 THE SIGNAL FAILS TOWARD "DO NOT TOUCH". `.timekast/lockfile.json` is written by
  * `new`/`add`/`update` in every derivative and does NOT exist in the Factory, so its
  * ABSENCE means "this is the Factory, or a checkout that cannot be identified" and the
- * predicate answers `false`. A false positive INSIDE the Factory would commit a `0000`
- * here, and since the `full` distribution profile is `include: ["**"]` without excluding
- * `src/lib/db/migrations/`, that `.sql` would ride the tarball into every new derivative
- * — breaking BR-FACTORY-005 from the origin. A false negative only leaves the migration
- * ungenerated, which the dev fixes with one `pnpm db:generate`.
+ * predicate answers `false`. A false positive INSIDE the Factory would commit a SECOND
+ * `0000` on top of the one the Factory now maintains for itself — a duplicate against the
+ * same schema, which `drizzle-kit check` then reports as a broken journal. A false
+ * negative only leaves the migration ungenerated, which the dev fixes with one
+ * `pnpm db:generate`.
+ *
+ * ℹ️ This used to warn that a `0000` committed here would RIDE THE TARBALL into every new
+ * derivative, because `profiles.full` was `include: ["**"]` with no exclusion for
+ * `src/lib/db/migrations/`. That hole is closed: the exclusion now exists (and is pinned
+ * by a test over the REAL profiles.json), which is precisely what let the Factory adopt
+ * migrations without breaking the born-clean rule. A derivative still generates its own.
  *
  * If this signal ever disagrees with the markdown detection `/deploy` uses (`is_factory`
  * in `project/planning/project-config.md`), the ABSENCE OF THE LOCKFILE WINS and nothing

package/dist/lib/neon-api.js

@@ -95,6 +95,113 @@ async function safeBody(response) {
         return '';
     }
 }
+/**
+ * List the organizations the API key can reach — `GET /users/me/organizations`.
+ *
+ * This is the ONLY way to learn an org id from a key, and it is why the rail no
+ * longer carries `NEON_ORGANIZATION_ID`: the id is derived, never configured.
+ *
+ * Only a PERSONAL key answers here (an org key gets `404 not allowed for
+ * organization API keys`), which is exactly the shape the rail now holds: the
+ * personal key of a service account that is a member of the TimeKast orgs and
+ * of nothing else. A service account that belongs to ONE org therefore returns a
+ * single entry, and {@link resolveNeonOrg} needs no configuration at all.
+ *
+ * @throws {NeonApiError} on any non-2xx.
+ */
+export async function listNeonOrgs(apiKey, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/users/me/organizations`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /users/me/organizations');
+    }
+    const data = (await response.json());
+    return (data.organizations ?? [])
+        .filter((o) => Boolean(o.id))
+        .map((o) => ({ id: o.id, name: o.name ?? o.id, handle: o.handle ?? '' }));
+}
+/**
+ * Resolve WHICH organization a new project is created in. Three tiers, in order
+ * (the caller passes tiers 1 and 2; this function owns the fallback):
+ *
+ *   1. `--neon-org <name|id>` — the explicit ask, for the deliberate detour
+ *      (an overflow org once the default one fills up, a reserved one).
+ *   2. `NEON_ORG` from the rail — the durable default, a NAME not an id, set once.
+ *   3. Neither: a key that sees exactly ONE org uses it; a key that sees several
+ *      THROWS, naming them. Fail-closed on purpose — guessing here would create a
+ *      client's database in the wrong organization, and there is no prompt to fall
+ *      back on (headless Agent Server runs have nobody to answer it).
+ *
+ * `selector` matches the `org-...` id verbatim, or the name/handle
+ * case-insensitively, so both `--neon-org TimeKast` and `--neon-org org-abc123`
+ * work. An unknown selector throws rather than falling through to a default: the
+ * caller asked for a specific org and silently using another is the failure mode
+ * this whole resolution exists to prevent.
+ *
+ * @throws {CLIError-ready Error} with an es-MX message the caller surfaces as-is.
+ * @throws {NeonApiError} if the listing itself fails.
+ */
+export async function resolveNeonOrg(apiKey, selector, deps = {}) {
+    const orgs = await listNeonOrgs(apiKey, deps);
+    if (orgs.length === 0) {
+        throw new Error('La `NEON_API_KEY` del archivo de secretos no ve ninguna organización de Neon.\n' +
+            '  Debe ser la key PERSONAL de la cuenta de servicio, y esa cuenta tiene que ser ' +
+            'Admin de la organización (solo un Admin puede acuñar API keys project-scoped).');
+    }
+    if (selector) {
+        const needle = selector.trim().toLowerCase();
+        const hit = orgs.find((o) => o.id === selector.trim() ||
+            o.name.toLowerCase() === needle ||
+            o.handle.toLowerCase() === needle);
+        if (!hit) {
+            throw new Error(`La key no ve ninguna organización de Neon llamada \`${selector}\`.\n` +
+                `  Organizaciones visibles: ${orgs.map((o) => `${o.name} (${o.id})`).join(', ')}.`);
+        }
+        return hit;
+    }
+    if (orgs.length === 1)
+        return orgs[0];
+    throw new Error(`La key ve ${orgs.length} organizaciones de Neon y no dijiste en cuál crear el proyecto.\n` +
+        `  Visibles: ${orgs.map((o) => `${o.name} (${o.id})`).join(', ')}.\n` +
+        '  Elige una con `--neon-org "<nombre>"`, o fija el default del rail con ' +
+        '`NEON_ORG=<nombre>` en `~/.claude/.env`.');
+}
+/**
+ * Find an EXISTING project by name across every org the key can reach, and
+ * return it together with the org that owns it.
+ *
+ * This is how every operation on an already-created project (`--adopt`,
+ * `--destroy`, `--remint`, a `--resume` over a state written before `orgId`
+ * existed) learns its org: read it off the project, never from a flag or a
+ * default. Using the default here would point a teardown at the wrong org.
+ *
+ * A name that exists in TWO orgs THROWS instead of picking one — an ambiguous
+ * teardown target is precisely what must not resolve silently.
+ *
+ * @returns the match, or `null` when no org holds a project with that name.
+ */
+export async function findNeonProjectAcrossOrgs(apiKey, projectName, deps = {}) {
+    const orgs = await listNeonOrgs(apiKey, deps);
+    const needle = projectName.trim().toLowerCase();
+    const hits = [];
+    for (const org of orgs) {
+        const projects = await listNeonProjects(apiKey, org.id, deps);
+        for (const project of projects) {
+            if (project.name.trim().toLowerCase() === needle)
+                hits.push({ org, project });
+        }
+    }
+    if (hits.length > 1) {
+        throw new Error(`Hay un proyecto de Neon llamado \`${projectName}\` en más de una organización: ` +
+            `${hits.map((h) => `${h.org.name} (${h.project.id})`).join(', ')}.\n` +
+            '  No elijo por ti: resuélvelo a mano en la consola de Neon (renombra uno) y reintenta.');
+    }
+    return hits[0] ?? null;
+}
 /**
  * Create a Neon project. The project is born WITH its primary branch — we name
  * that branch `main` and use it as production (issue §4: do NOT create an extra
@@ -187,6 +294,39 @@ export async function createDevelopBranch(apiKey, projectId, parentBranchId, dep
     }
     return branchId;
 }
+/**
+ * The database a branch actually holds, plus its owning role.
+ *
+ * 🔴 These were hardcoded to Neon's defaults for an API-provisioned project
+ * (`neondb` / `neondb_owner`), which is right for a project this CLI created and WRONG
+ * for every project it merely adopted. A real client project whose database is named
+ * `adi_capital` got a `DATABASE_URL` secret pointing at a `neondb` that does not exist
+ * there — CI would have run against a database nobody had. Asking the branch costs one
+ * GET and is right in both cases.
+ *
+ * Falls back to Neon's defaults when the branch reports no database (or the lookup
+ * fails), so a freshly-created project behaves exactly as before.
+ */
+export async function getBranchDatabase(apiKey, projectId, branchId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/databases`, {
+            method: 'GET',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+        const data = (await response.json());
+        const first = (data.databases ?? []).find((d) => d.name);
+        if (!first?.name)
+            return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+        return { database: first.name, role: first.owner_name ?? NEON_DEFAULT_ROLE };
+    }
+    catch {
+        return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+    }
+}
 /**
  * Read a branch's connection string for the requested mode via Neon's
  * `GET /projects/{id}/connection_uri`:
@@ -203,12 +343,15 @@ export async function createDevelopBranch(apiKey, projectId, parentBranchId, dep
  */
 export async function getConnectionUri(apiKey, projectId, branchId, pooled, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
-    // Neon's connection_uri requires database_name + role_name (the project's default
-    // db + owner role). Without them it 400s "database_name not set".
+    // Neon's connection_uri requires database_name + role_name. They come from the
+    // BRANCH (see `getBranchDatabase`), not from a constant: an adopted project's
+    // database is whatever its team named it, and assuming `neondb` there hands out a
+    // connection string to a database that does not exist.
+    const { database, role } = await getBranchDatabase(apiKey, projectId, branchId, deps);
     const query = new URLSearchParams({
         branch_id: branchId,
-        database_name: NEON_DEFAULT_DATABASE,
-        role_name: NEON_DEFAULT_ROLE,
+        database_name: database,
+        role_name: role,
         pooled: pooled ? 'true' : 'false',
     });
     const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/connection_uri?${query.toString()}`, {
@@ -300,20 +443,34 @@ export async function listNeonBranches(apiKey, projectId, deps = {}) {
     const data = (await response.json());
     return (data.branches ?? [])
         .filter((b) => Boolean(b.id) && Boolean(b.name))
-        .map((b) => ({ id: b.id, name: b.name }));
+        .map((b) => ({ id: b.id, name: b.name, isDefault: b.default === true }));
 }
 /**
- * Mint a PROJECT-SCOPED Neon API key (issue §4 + plan: the GH secret stores a
- * project-scoped key, NOT the org key — blast radius is one project's infra).
- * Neon's `POST /api_keys` with a `project_id` scopes the key to that project.
- * Returns the key value (the ONE place this value is read — it is handed
- * straight to `gh secret set` over STDIN, never logged).
+ * Mint a PROJECT-SCOPED Neon API key: `POST /organizations/{org_id}/api_keys`
+ * with a `project_id`. The result is an ORG-OWNED key restricted to that one
+ * project (Editor level), which is what the GH secret and the derivative's
+ * `.env.local` store — never the rail key. Returns the key value (the ONE place
+ * this value is read — handed straight to `gh secret set` over STDIN, never
+ * logged).
+ *
+ * 🔴 The endpoint matters, and getting it wrong was a real incident. This used to
+ * call `POST /api_keys` with the same `project_id` in the body. That endpoint
+ * takes `key_name` and NOTHING else, so Neon ignored the scope and handed back a
+ * PERSONAL key with access to every organization its owner belonged to — which
+ * provision then distributed to every repo's GitHub Secrets and `.env.local`.
+ * Verified 2026-09-12: the key this endpoint returns 404s on a sibling project in
+ * the same org and 404s on `DELETE /projects/{id}`, while still covering the whole
+ * E2E branch cycle (create branch, connection_uri, reveal_password, delete).
+ *
+ * Requires a PERSONAL key belonging to an ADMIN of the org: an org key gets
+ * `404 This endpoint requires a personal API key`, and there is no alternative
+ * route (`POST /projects/{id}/api_keys` does not exist).
  *
  * @throws {NeonApiError} on any non-2xx.
  */
-export async function createProjectApiKey(apiKey, projectId, keyName, deps = {}) {
+export async function createProjectApiKey(apiKey, orgId, projectId, keyName, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const mint = () => fetchImpl(`${NEON_API_BASE}/api_keys`, {
+    const mint = () => fetchImpl(`${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys`, {
         method: 'POST',
         headers: neonHeaders(apiKey),
         body: JSON.stringify({ key_name: keyName, project_id: projectId }),
@@ -326,33 +483,41 @@ export async function createProjectApiKey(apiKey, projectId, keyName, deps = {})
     // resume must converge, not 409. (Only the secret-pending path re-enters here;
     // the happy path sets apiKeySecretDone and short-circuits before minting again.)
     if (response.status === 409) {
-        await deleteNeonApiKeysByName(apiKey, keyName, { fetchImpl });
+        await deleteNeonApiKeysByName(apiKey, orgId, keyName, { fetchImpl });
         response = await mint();
     }
     if (!response.ok) {
-        throw new NeonApiError(response.status, await safeBody(response), 'POST /api_keys');
+        throw new NeonApiError(response.status, await safeBody(response), 'POST /organizations/{org_id}/api_keys');
     }
     const data = (await response.json());
     if (!data.key) {
-        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /api_keys (respuesta sin key)');
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /organizations/{org_id}/api_keys (respuesta sin key)');
     }
     return data.key;
 }
 /**
- * Best-effort delete of every account/org API key whose name matches `keyName`
- * (GET /api_keys → DELETE /api_keys/{id}). Two callers:
- *   - the idempotent re-mint (clear a stale key before re-minting on resume), and
+ * Best-effort delete of every ORG API key whose name matches `keyName`
+ * (`GET /organizations/{org_id}/api_keys` → `DELETE .../api_keys/{id}`). Three
+ * callers:
+ *   - the idempotent re-mint (clear a stale key before re-minting on resume),
+ *   - `--remint` (revoke the live key before issuing its replacement), and
  *   - the ephemeral `--destroy` nuke (delete the project-scoped key it minted so
  *     the org does not accumulate dead keys across provisions/tests).
+ *
+ * Org-scoped for the same reason the mint is (see {@link createProjectApiKey}):
+ * the keys provision issues are owned by the org, so the personal `/api_keys`
+ * listing never saw them — and with a service-account key it 404s outright.
+ *
  * Returns the count deleted. NEVER throws — a cleanup failure must not abort the
  * caller (the re-mint surfaces its own error; the destroy already nuked the
  * project).
  */
-export async function deleteNeonApiKeysByName(apiKey, keyName, deps = {}) {
+export async function deleteNeonApiKeysByName(apiKey, orgId, keyName, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
+    const keysBase = `${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys`;
     let deleted = 0;
     try {
-        const listResp = await fetchImpl(`${NEON_API_BASE}/api_keys`, {
+        const listResp = await fetchImpl(keysBase, {
             method: 'GET',
             headers: neonHeaders(apiKey),
             signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
@@ -366,7 +531,7 @@ export async function deleteNeonApiKeysByName(apiKey, keyName, deps = {}) {
             .filter((k) => k?.name === keyName && k?.id != null)
             .map((k) => String(k.id));
         for (const id of ids) {
-            const del = await fetchImpl(`${NEON_API_BASE}/api_keys/${encodeURIComponent(id)}`, {
+            const del = await fetchImpl(`${keysBase}/${encodeURIComponent(id)}`, {
                 method: 'DELETE',
                 headers: neonHeaders(apiKey),
                 signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),

package/dist/lib/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, VERIFY_QUICK_SCRIPT_CMD, VERIFY_QUICK_SCRIPT_NAME, VERIFY_SCRIPT_CMD, VERIFY_SCRIPT_FILE, VERIFY_SCRIPT_NAME, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, E2E_SETUP_SCRIPT_CMD, E2E_SETUP_SCRIPT_FILE, E2E_SETUP_SCRIPT_NAME, EVIDENCE_VISUAL_SCRIPT_CMD, EVIDENCE_VISUAL_SCRIPT_FILE, EVIDENCE_VISUAL_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, VERIFY_QUICK_SCRIPT_CMD, VERIFY_QUICK_SCRIPT_NAME, VERIFY_SCRIPT_CMD, VERIFY_SCRIPT_FILE, VERIFY_SCRIPT_NAME, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SETUP_E2E_VARS_SCRIPT_CMD, SETUP_E2E_VARS_SCRIPT_FILE, SETUP_E2E_VARS_SCRIPT_NAME, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, VERCEL_BUILD_OBSOLETE_CMDS, VERCEL_BUILD_SCRIPT_CMD, VERCEL_BUILD_SCRIPT_NAME, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -111,6 +111,18 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
  * backing file lands.
  *
  * - `preflight` — when its sweep script ships (full brain).
+ * - `setup:e2e:vars` — publishes the CI E2E auth env vars (Fase 1 of the
+ *   `e2e-ci-auth-env` retrofit), when `scripts/tools/setup-e2e.ts` ships (full brain).
+ * - `evidence:visual` — the visual-evidence harness (`fx-visual-evidence`), gated on the
+ *   harness itself (`scripts/tools/visual-evidence/`) rather than on the runner: it is what
+ *   this alias needs, and a `core` derivative receives neither. Forwards to `test:e2e`, so the
+ *   capture pass goes through the ephemeral Neon branch like every other phase.
+ * - `e2e:setup` — installs the Playwright browsers, gated on the e2e runner that
+ *   refuses to start without them and names this alias in its message. A repo
+ *   whose runner ships but whose `package.json` lacks the alias would be told to
+ *   run a script it does not have — which is why it is maintained here rather
+ *   than only in the Factory's own `package.json` (frozen at bootstrap in a
+ *   derivative, so it is unreachable any other way).
  * - `generate:*` — one alias per reference generator whose `scripts/tools/
  *   generate-*.mjs` ships (full brain). These arrive via the `scripts/**`
  *   tracked set on `update`/`beta`, so an existing derivative self-heals the
@@ -140,6 +152,12 @@ export function kitLocalScripts(rootDir) {
         scripts[PREFLIGHT_SCRIPT_NAME] = PREFLIGHT_SCRIPT_CMD;
     if (has(INVITE_ADMIN_SCRIPT_FILE))
         scripts[INVITE_ADMIN_SCRIPT_NAME] = INVITE_ADMIN_SCRIPT_CMD;
+    if (has(SETUP_E2E_VARS_SCRIPT_FILE))
+        scripts[SETUP_E2E_VARS_SCRIPT_NAME] = SETUP_E2E_VARS_SCRIPT_CMD;
+    if (has(E2E_SETUP_SCRIPT_FILE))
+        scripts[E2E_SETUP_SCRIPT_NAME] = E2E_SETUP_SCRIPT_CMD;
+    if (has(EVIDENCE_VISUAL_SCRIPT_FILE))
+        scripts[EVIDENCE_VISUAL_SCRIPT_NAME] = EVIDENCE_VISUAL_SCRIPT_CMD;
     for (const gen of GENERATOR_SCRIPTS) {
         if (has(gen.file))
             scripts[gen.name] = gen.cmd;
@@ -355,6 +373,48 @@ export function removeRetiredScripts(pkgPath) {
     }
     return report;
 }
+/**
+ * Reorder a derivative's `vercel-build` so the production build runs BEFORE the migration.
+ *
+ * WHY THIS IS ITS OWN FUNCTION AND NOT AN ENTRY IN `FACTORY_SCRIPTS`. Everything in that
+ * registry is INSERTED when missing, because those are the CLI's own `factory:*` aliases and a
+ * repo without them is a repo that is missing them. `vercel-build` is the opposite kind of key:
+ * it belongs to the boilerplate, arrives frozen with `src/` at `factory new` (BR-FACTORY-006),
+ * and in a `core`/non-Factory repo its absence is CORRECT — inserting it there would point a
+ * build command at a stack that repo does not have. So this heals in place and never inserts,
+ * the same shape as `emptyShippedE2EPort`.
+ *
+ * The damage it repairs is in `VERCEL_BUILD_SCRIPT_NAME`'s docstring: with the migration first,
+ * a build that fails AFTER it leaves the production database migrated while Vercel keeps
+ * serving the previous build — new schema, old code, and a deployment rollback cannot undo it.
+ *
+ * Surgical like the rest of this module: reads, mutates a single key, re-serializes with the
+ * original indentation + trailing newline, and writes ONLY on a real change — so a second run
+ * finds `already-correct` and writes nothing.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ */
+export function healVercelBuildOrder(pkgPath) {
+    const raw = readFileSync(pkgPath, 'utf8');
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    const scripts = pkg.scripts;
+    if (typeof scripts !== 'object' || scripts === null || Array.isArray(scripts))
+        return 'absent';
+    const current = scripts[VERCEL_BUILD_SCRIPT_NAME];
+    if (current === undefined)
+        return 'absent';
+    if (current === VERCEL_BUILD_SCRIPT_CMD)
+        return 'already-correct';
+    // Exact match against what the kit actually shipped, byte for byte. A dev who appended a flag
+    // — or wrote the same two halves with different spacing — keeps their command through every
+    // future update: an unlisted variant erring toward "leave it alone" is the safe side here.
+    if (!VERCEL_BUILD_OBSOLETE_CMDS.includes(current))
+        return 'preserved';
+    scripts[VERCEL_BUILD_SCRIPT_NAME] = VERCEL_BUILD_SCRIPT_CMD;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    return 'reordered';
+}
 /**
  * The kit-owned maintenance of a derivative's `package.json`, in the ONE order that is correct.
  *
@@ -395,6 +455,10 @@ export function maintainKitScripts(pkgPath) {
     // `scripts/**` can derive one per checkout. Conditional: it only ever touches that exact
     // value, so a dev-chosen port survives untouched.
     const portAction = emptyShippedE2EPort(pkgPath);
+    // Reorder `vercel-build` so the build runs before the migration. Conditional in the same way:
+    // it only ever rewrites a value the kit itself shipped, and never creates the key — a repo
+    // without it is a repo that should not have one.
+    const vercelBuildAction = healVercelBuildOrder(pkgPath);
     const removedKeys = new Set(Object.entries(retiredReport)
         .filter(([, action]) => action === 'removed')
         .map(([name]) => name));
@@ -402,7 +466,7 @@ export function maintainKitScripts(pkgPath) {
         .filter(([name, r]) => (r.action === 'added' || r.action === 'healed') && !removedKeys.has(name))
         .map(([name]) => name);
     const retired = [...removedKeys].filter((name) => insert.perScript[name]?.action !== 'added');
-    return { insert, retiredReport, portAction, inserted, retired };
+    return { insert, retiredReport, portAction, vercelBuildAction, inserted, retired };
 }
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the

package/dist/lib/preflight.js

@@ -139,6 +139,11 @@ export async function runPreflight() {
  * The methodology-rail keys the launcher expects in `~/.claude/.env` (imported
  * via `factory secrets <file>`). Provisioning tokens + their team/org ids + the
  * proposal tooling keys. Single source so the check + tests agree.
+ *
+ * `NEON_ORG` is deliberately NOT here: it only names a default organization, and
+ * its absence is a valid configuration (a key that reaches exactly one org needs
+ * no default). Listing it would warn every dev about a key they may never need.
+ * The Neon ORG ID is not here either — it is derived from the key, never stored.
  */
 export const REQUIRED_SECRET_KEYS = [
     'NEON_API_KEY',
@@ -148,7 +153,6 @@ export const REQUIRED_SECRET_KEYS = [
     'SHORTIO_API_KEY',
     'GAMMA_API_KEY',
     'VERCEL_TEAM_ID',
-    'NEON_ORGANIZATION_ID',
 ];
 /** The ordered launcher labels (single source so render + tests agree). */
 const LAUNCHER_LABELS = {

package/dist/lib/provision-preflight.js

@@ -19,8 +19,10 @@
  *
  * What is OPTIONAL (a WARNING, never an abort — frozen plan decision):
  *   - `neonctl`. Provision mutates Neon over REST with the rail `NEON_API_KEY`,
- *     so a missing or un-authenticated `neonctl` is a convenience gap, not a
+ *     so a missing or session-less `neonctl` is a convenience gap, not a
  *     blocker (issue §1, §8). Absent → warn with the install hint and continue.
+ *     The session is detected by its credentials FILE, never by running
+ *     `neonctl me` — that command starts a login instead of failing.
  *
  * The token reader, the `fetch`, and the `gh` spawns are all injectable seams so
  * the unit tests drive every branch (401/403/missing-token/no-gh/no-neonctl)
@@ -183,6 +185,14 @@ function assertGateTokensPresent(services, present) {
             'Ejecuta `factory secrets <archivo>` para bajarlos del archivo de secretos del org y vuelve a intentar.');
     }
 }
+/**
+ * Where `neonctl` keeps its OAuth session. Honors `NEONCTL_CONFIG_DIR`, which the CLI
+ * itself reads, so a dev who moved its config is not reported as session-less.
+ */
+export function neonctlCredentialsPath() {
+    const base = process.env.NEONCTL_CONFIG_DIR ?? path.join(homedir(), '.config', 'neonctl');
+    return path.join(base, 'credentials.json');
+}
 /**
  * Optional `neonctl` check — NEVER aborts (frozen plan decision: provision mutates
  * Neon over REST with the rail `NEON_API_KEY`). Returns a structured report the
@@ -208,19 +218,29 @@ async function checkNeonctlOptional(spawn) {
             message: 'No se pudo ejecutar `neonctl` (opcional). Continúo con la mutación por REST.',
         };
     }
-    // Installed → check it is authenticated (`neonctl me`). Un-authed is still only
-    // a warning: provision does not depend on the neonctl session.
-    try {
-        await spawn('neonctl', ['me']);
-    }
-    catch {
+    // Installed → is there a session? Answered by looking for the credentials file,
+    // NOT by running `neonctl me`.
+    //
+    // 🔴 `neonctl me` without a session does not fail — it STARTS A LOGIN and opens a
+    // browser. A check the plan froze as optional diagnostics ("provision does not
+    // depend on the neonctl session") therefore had two side effects it had no business
+    // having: it popped an OAuth consent in the dev's browser mid-provision, and, if
+    // approved, wrote an OAuth session to their host. Worse where nobody can see it: on
+    // a headless Agent Server there is no browser and no one to approve, so the spawn
+    // sits waiting and hangs the preflight of a run that never needed it.
+    //
+    // Reading the credentials file is the same answer with no side effects. It can go
+    // stale (an expired session still leaves the file), which is why the `ok` message
+    // says "con sesión" and not "authenticated" — and being wrong in that direction
+    // costs a wrong word in a warning, while the old one cost a credential.
+    if (!existsSync(neonctlCredentialsPath())) {
         return {
             status: 'warn',
-            message: '`neonctl` está instalado pero no autenticado (opcional).\n' +
+            message: '`neonctl` está instalado pero sin sesión (opcional).\n' +
                 'Autentícalo con `neonctl auth` si lo quieres para inspección; provision no lo necesita.',
         };
     }
-    return { status: 'ok', message: '`neonctl` instalado y autenticado.' };
+    return { status: 'ok', message: '`neonctl` instalado y con sesión.' };
 }
 /**
  * Step 3 — `VERCEL_TOKEN` is valid and scoped to `teamId` via `GET /v2/teams/{teamId}`.

package/dist/lib/provision-state.js

@@ -199,6 +199,7 @@ export function adoptState(rootDir, partial, options = {}) {
         slug,
         vercelProjectId: partial.vercelProjectId ?? ADOPT_UNKNOWN,
         neonProjectId: partial.neonProjectId ?? ADOPT_UNKNOWN,
+        neonOrgId: partial.neonOrgId ?? ADOPT_UNKNOWN,
         neonBranchDevId: partial.neonBranchDevId ?? ADOPT_UNKNOWN,
         githubRepo: partial.githubRepo ?? ADOPT_UNKNOWN,
         domains: partial.domains ?? { dev: ADOPT_UNKNOWN, prod: ADOPT_UNKNOWN },
@@ -305,6 +306,47 @@ function isAdoptedShape(obj) {
     // `projectName` + nested `vercel.projectId`. `slug` present = adopt.
     return typeof obj.slug === 'string';
 }
+/**
+ * Read the state as a {@link ProvisionState} for a `--remint`, tolerating BOTH shapes
+ * the way {@link readDestroyTarget} does.
+ *
+ * 🔴 Why this exists: the ADOPTED shape is what the whole existing fleet has — a
+ * derivative provisioned before this state file existed gets one from `--adopt`, and
+ * that shape has `slug`/`neonProjectId` instead of `projectName`/`neon`. So
+ * `readProvisionState` rejects it, and `--remint` (the command whose entire purpose is
+ * re-issuing the key of an already-provisioned project) failed on precisely the
+ * projects that need it, suggesting `--force` — which with `--services=neon` would
+ * discard the state and try to CREATE A SECOND Neon project for a derivative that
+ * already has one.
+ *
+ * Returns `null` when there is no state at all, and throws the same typed error as
+ * `readDestroyTarget` on a corrupt file. `mainBranchId` comes back empty for an
+ * adopted stack (that shape never recorded it), and so does `developBranchId` when the
+ * adopt found no branch by that name — the normal case for a project whose working
+ * branch is called something else (the Factory's is `production`). A re-mint resolves
+ * the branch it needs from Neon, honoring the repo's pinned E2E parent, and never
+ * creates one.
+ */
+export function readRemintState(rootDir) {
+    const target = readDestroyTarget(rootDir);
+    if (!target)
+        return null;
+    if (!target.neonProjectId)
+        return null;
+    return {
+        projectName: target.slug,
+        lifecycle: target.lifecycle,
+        scope: target.scope ?? '',
+        neon: {
+            projectId: target.neonProjectId,
+            orgId: target.neonOrgId ?? undefined,
+            mainBranchId: '',
+            developBranchId: target.neonBranchDevId ?? '',
+        },
+        github: target.githubRepo ? { repo: target.githubRepo } : undefined,
+        createdAt: new Date(0).toISOString(),
+    };
+}
 /**
  * Read the provision state file as a {@link DestroyTarget}, tolerating BOTH the
  * step-by-step {@link ProvisionState} and the flat {@link AdoptedState} shapes
@@ -351,6 +393,7 @@ export function readDestroyTarget(rootDir) {
             lifecycle: adopted.lifecycle === 'live' ? 'live' : 'live', // adopt is always live
             scope: null, // the adopt shape does not persist the team scope
             neonProjectId: realId(adopted.neonProjectId),
+            neonOrgId: realId(adopted.neonOrgId),
             neonBranchDevId: realId(adopted.neonBranchDevId),
             vercelProjectId: realId(adopted.vercelProjectId),
             githubRepo: realRepo(adopted.githubRepo),
@@ -388,6 +431,7 @@ export function readDestroyTarget(rootDir) {
         lifecycle,
         scope: realId(step.scope),
         neonProjectId: realId(step.neon?.projectId),
+        neonOrgId: realId(step.neon?.orgId),
         neonBranchDevId: realId(step.neon?.developBranchId),
         vercelProjectId: realId(step.vercel?.projectId),
         githubRepo: realRepo(step.github?.repo),

package/dist/lib/public-env-keys.json

@@ -0,0 +1,27 @@
+{
+    "prefixes": ["NEXT_PUBLIC_", "RATE_LIMIT_"],
+    "keys": [
+        "APP_URL",
+        "AUTH_DEBUG",
+        "AUTH_GITHUB_ID",
+        "AUTH_GOOGLE_ID",
+        "AUTH_TRUST_HOST",
+        "EMAIL_FROM",
+        "EMAIL_LOGO_URL",
+        "EMAIL_PROVIDER",
+        "EMAIL_SERVER_HOST",
+        "EMAIL_SERVER_PORT",
+        "EMAIL_SERVER_SECURE",
+        "EMAIL_SERVER_USER",
+        "MFA_ENABLED",
+        "MFA_REQUIRED_ALL",
+        "NEXTAUTH_URL",
+        "NODE_ENV",
+        "SENTRY_ORG",
+        "SENTRY_PROJECT",
+        "SUPPORT_EMAIL",
+        "VAPID_SUBJECT",
+        "WEBAUTHN_RP_ID",
+        "WEBAUTHN_RP_NAME"
+    ]
+}

package/package.json

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