@timekast/factory 1.25.0 → 1.27.0

package/dist/lib/exit-code.js

@@ -0,0 +1,31 @@
+/**
+ * How the CLI turns a resolved `main()` into a process exit code.
+ *
+ * 🔴 The bug this exists to fix, stated plainly: `main(...).then(() => process.exit(0))`
+ * passes an EXPLICIT code, and an explicit argument to `process.exit` overrides whatever a
+ * command assigned to `process.exitCode`. So a command that finished its work successfully
+ * but wanted to report a non-zero *outcome* had its signal silently dropped.
+ *
+ * That is not hypothetical. `update --dry-run` sets `process.exitCode = 2` when it finds
+ * conflicts, and the GUI launcher chains the real apply (`--theirs-all --yes`) only when the
+ * preview exited 0 — its comment says "never clobber local edits with `--theirs-all` behind
+ * the dev's back". With the 2 discarded, that guard was dead: the launcher read 0 on every
+ * preview and applied unconditionally, overwriting local edits to tracked kit files.
+ *
+ * Note the distinction this function keeps: a **thrown** `CLIError` is a failure and still
+ * exits with its own code (that path never went through here). `process.exitCode` is for a
+ * command that succeeded and is reporting a RESULT — the dry-run's "there are conflicts" —
+ * which is exactly the case that was being swallowed.
+ */
+export function resolveSuccessExitCode(pending) {
+    // Node types `process.exitCode` as `number | string | null | undefined` — `null` included,
+    // which is why this takes the whole union instead of narrowing at the call site. A string is
+    // only reachable if something assigned one; coerce rather than forward it, because
+    // `process.exit('2')` is not the same call as `process.exit(2)`.
+    if (typeof pending === 'number' && Number.isInteger(pending))
+        return pending;
+    if (typeof pending === 'string' && /^\d+$/.test(pending))
+        return Number(pending);
+    // Unset (the overwhelmingly common case) or unusable ⇒ success.
+    return 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.

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, 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,12 +152,22 @@ 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;
     }
     if (has(GENERATE_REFERENCE_GATE_FILE))
         scripts[GENERATE_REFERENCE_NAME] = GENERATE_REFERENCE_CMD;
+    if (has(VERIFY_SCRIPT_FILE))
+        scripts[VERIFY_SCRIPT_NAME] = VERIFY_SCRIPT_CMD;
+    if (has(VERIFY_SCRIPT_FILE))
+        scripts[VERIFY_QUICK_SCRIPT_NAME] = VERIFY_QUICK_SCRIPT_CMD;
     if (has(DEV_NEXT_GATE_FILE))
         scripts[DEV_NEXT_SCRIPT_NAME] = DEV_NEXT_SCRIPT_CMD;
     return scripts;
@@ -351,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.
  *
@@ -391,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));
@@ -398,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/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/dist/lib/retrofit-reminder.js

@@ -216,13 +216,56 @@ export function renderRetrofitReminder(entries, fromVersion = null) {
     lines.push(`  No todas te aplican: cada una abre diciendo a quién le toca. En ${RETROFITS_DIR}/`, '  Si trabajas con un agente, pídele que las lea y te diga cuáles te aplican.', rule, '');
     return lines.join('\n');
 }
+/**
+ * 🔴 FROZEN WIRE FORMAT — see ADR-004 §1/§4. Once a launcher is installed on someone else's
+ * machine, renaming this marker leaves it mute forever, silently: it does not error, it just
+ * stops seeing the signal. Never rename it; the pin in the test suite is what makes that
+ * mistake loud instead of silent. Adding NEW fields to the payload is fine (ADR-004 §3) —
+ * this is about the marker string itself and the shape it prefixes.
+ */
+export const RETROFIT_SIGNAL_MARKER = '::timekast:retrofit-signal::';
+/**
+ * Render the machine-readable signal line, or `null` under the same gate as the banner
+ * (`renderRetrofitReminder` — no guides shipped, nothing to signal either).
+ *
+ * Reuses `splitByArrival` rather than recomputing the arrival cut — that logic already lives
+ * there and this must never drift from what the banner counts.
+ *
+ * 🔴 One line, no pretty-printing: `JSON.stringify` with no `indent` arg. The consumer detects
+ * this by line PREFIX (ADR-004 §1); a payload that spans multiple lines breaks that detection.
+ */
+export function renderRetrofitSignal(entries, fromVersion = null) {
+    if (renderRetrofitReminder(entries, fromVersion) === null)
+        return null;
+    const { arrived, carried } = splitByArrival(entries, fromVersion);
+    const payload = {
+        dir: RETROFITS_DIR,
+        arrived: arrived.length,
+        carried: carried.length,
+    };
+    return `${RETROFIT_SIGNAL_MARKER}${JSON.stringify(payload)}`;
+}
 /**
  * Print the reminder. Called on EVERY applied update — see the module header for why this one
  * has no headless guard and no outcome condition.
+ *
+ * 🔴 With `guiSignal: true`, the signal line is written FIRST, the banner second — not the
+ * other way around. `cli/src/index.ts` calls `process.exit(0)` right after `main` resolves, and
+ * writes to a pipe are async on Windows, where `process.exit` can truncate the tail. Under
+ * `--yes` the signal would otherwise be the LAST line written; writing it first leaves the
+ * banner (cosmetic text) as the one at risk of truncation instead of the machine-readable line.
  */
 export function printRetrofitReminder(opts) {
     const log = opts.log ?? ((m) => console.log(m));
-    const rendered = renderRetrofitReminder(listRetrofits(opts.rootDir, opts), opts.fromVersion ?? null);
-    if (rendered)
-        log(rendered);
+    const entries = listRetrofits(opts.rootDir, opts);
+    const fromVersion = opts.fromVersion ?? null;
+    const rendered = renderRetrofitReminder(entries, fromVersion);
+    if (!rendered)
+        return;
+    if (opts.guiSignal) {
+        const signal = renderRetrofitSignal(entries, fromVersion);
+        if (signal)
+            log(signal);
+    }
+    log(rendered);
 }

package/package.json

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