@timekast/factory 1.26.0 → 1.28.0

package/dist/lib/constants.js

@@ -14,6 +14,43 @@ export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
 export const PROPOSALS_HUB_REPO = `${FACTORY_ORG}/proposals`;
 /** HTTPS git URL of the hub (token is injected by the publish command). */
 export const PROPOSALS_HUB_GIT = `https://github.com/${FACTORY_ORG}/proposals.git`;
+/**
+ * Repo-relative directory that holds a derivative's factory-tickets (the
+ * derivative→Factory channel — see the `fx-factory-tickets` convention). It is
+ * the ONLY directory `factory ticket push` may read from, and the containment
+ * check resolves it with `realpath` (never a string prefix — `project/factory-backup/`
+ * must not pass, and a symlink out of the tree must not either).
+ */
+export const FACTORY_TICKET_DIR = 'project/factory';
+/**
+ * Default assignee of a delivered factory-ticket. GitHub always notifies an
+ * assignee (mail + web) without them watching the repo, so this is the channel's
+ * actual delivery mechanism — not a cosmetic field. Overridable with `--assignee`.
+ */
+export const FACTORY_TICKET_ASSIGNEE = 'echarabati';
+/**
+ * Label applied to a delivered factory-ticket, so the queue is greppable
+ * (`gh issue list -R TimeKast/TimeKast-Factory --label kit-drift`).
+ *
+ * 🔴 The command APPLIES this label; it never CREATES it. Creating a label needs
+ * `write` on the repo while applying one needs only `triage` — creating it would
+ * break the command for exactly the population that has `triage`. A maintainer
+ * creates it once by hand; a missing label degrades to a warning, never a failure.
+ */
+export const FACTORY_TICKET_LABEL = 'kit-drift';
+/**
+ * Hard cap GitHub enforces on an issue body (65,536 characters). Some files under
+ * `project/factory/` are already ~27 KB, so this is reachable — the command checks
+ * it up front and says so, instead of surfacing a raw 422 from the API.
+ */
+export const GITHUB_ISSUE_BODY_MAX = 65_536;
+/**
+ * Hard cap GitHub enforces on an issue TITLE (256 characters). Same class of input as
+ * {@link GITHUB_ISSUE_BODY_MAX} — the title is built from the ticket's H1 plus its
+ * filename, both written by hand — so it gets the same treatment: capped up front with
+ * a readable truncation, never a raw 422 from the API.
+ */
+export const GITHUB_ISSUE_TITLE_MAX = 256;
 /**
  * End-pointer printed at the tail of a SUCCESSFUL `new` / `update` flow (PVSKILL-002):
  * the next step a dev takes to finish setting up the environment. Shared by both
@@ -132,6 +169,66 @@ export const PREFLIGHT_SCRIPT_FILE = 'scripts/tools/preflight.ts';
 export const INVITE_ADMIN_SCRIPT_NAME = 'invite:admin';
 export const INVITE_ADMIN_SCRIPT_CMD = 'npx @timekast/factory invite-admin';
 export const INVITE_ADMIN_SCRIPT_FILE = 'scripts/tools/invite-admin.ts';
+/**
+ * Kit-local E2E env-var publishing alias, consumed by Fase 1 of the
+ * `e2e-ci-auth-env` retrofit (`.claude/docs/retrofits/e2e-ci-auth-env.md`).
+ * tsx-based (not npx) and FILE-GATED, same contract as `preflight`: a
+ * core/non-Factory derivative without `scripts/tools/setup-e2e.ts` never gets
+ * a broken `setup:e2e:vars`. Insert-if-missing; self-heals on the next update
+ * once the script lands. Command confirmed verbatim against `package.json:50`
+ * of the kit.
+ */
+export const SETUP_E2E_VARS_SCRIPT_NAME = 'setup:e2e:vars';
+export const SETUP_E2E_VARS_SCRIPT_CMD = 'tsx scripts/tools/setup-e2e.ts --publish-vars';
+export const SETUP_E2E_VARS_SCRIPT_FILE = 'scripts/tools/setup-e2e.ts';
+/**
+ * Kit-local Playwright browser install alias (`pnpm e2e:setup`).
+ *
+ * WHY IT EXISTS. The E2E suite needs a browser on disk and nothing ever installed one: not a
+ * postinstall, not the runner, not a line of documentation. The gap only ever surfaced as a
+ * failure minutes into a run, after a Neon branch and a production build had already been
+ * paid for. `scripts/tools/e2e-runner.ts` now refuses to start without the browsers and names
+ * this alias in the message — so the alias has to EXIST in the repo the message is printed in.
+ *
+ * FILE-GATED on the runner itself: a `core` derivative gets no `sk-*`/e2e scripts, so it never
+ * receives an alias for a suite it cannot run. Insert-if-missing like every other entry here —
+ * a team that pointed `e2e:setup` at `playwright install --with-deps` keeps its own value, byte
+ * for byte, and no OBSOLETE entry will ever heal it: the kit never shipped a previous value.
+ *
+ * Not `npx`/`tsx`: `playwright` is a devDependency binary, so the package manager resolves it
+ * from `node_modules/.bin` exactly as the rest of the boilerplate scripts do.
+ */
+export const E2E_SETUP_SCRIPT_NAME = 'e2e:setup';
+export const E2E_SETUP_SCRIPT_CMD = 'playwright install chromium';
+export const E2E_SETUP_SCRIPT_FILE = 'scripts/tools/e2e-runner.ts';
+/**
+ * `evidence:visual` — el punto de entrada del harness de evidencia visual
+ * (`fx-visual-evidence`): captura cada superficie declarada × tema × ancho y escribe el
+ * manifest que consume el agente `ui-critic`.
+ *
+ * FORWARDEA A `test:e2e`, NO A PLAYWRIGHT. El harness es una fase del runner (`optIn`,
+ * `sk-e2e §1.7`), así que `--project=evidence` entra por el mismo camino que el resto de la
+ * suite: la rama efímera de Neon, la migración, el sembrado y el servidor de producción. Nunca
+ * `playwright test` directo — `tests/global-setup.ts` rechaza cualquier corrida cuyo
+ * `DATABASE_URL` no sea esa rama (`scripts/tools/e2e-guard.ts`), y este harness no pide
+ * excepción: fotografiar pantallas vacías no demuestra nada.
+ *
+ * FILE-GATED SOBRE EL HARNESS MISMO, no sobre el runner. Los dos viajan por `scripts/**`
+ * (tracked), pero el gate correcto es el archivo que ESTE alias necesita: un derivado en perfil
+ * `core` no recibe `scripts/tools/**` y por lo tanto nunca recibe un alias que no puede correr.
+ * Insert-if-missing como el resto: un equipo que apuntó `evidence:visual` a otra cosa conserva
+ * su valor byte por byte, y no hay entrada en `OBSOLETE_SCRIPT_CMDS` porque el kit nunca shippeó
+ * un valor anterior que sanar.
+ *
+ * ⚠️ Que el alias llegue NO implica que el harness corra: `playwright.config.ts` nace congelado
+ * en el derivado (BR-FACTORY-006), así que su proyecto `evidence` y el spec de captura los
+ * agrega el equipo siguiendo `.claude/docs/retrofits/visual-evidence-adoption.md`. Mientras
+ * tanto la fase se salta con aviso (nunca revienta la suite) y `ui-critic` degrada a
+ * "no demostrado" — la cláusula que su ficha declara.
+ */
+export const EVIDENCE_VISUAL_SCRIPT_NAME = 'evidence:visual';
+export const EVIDENCE_VISUAL_SCRIPT_CMD = 'pnpm test:e2e --project=evidence';
+export const EVIDENCE_VISUAL_SCRIPT_FILE = 'scripts/tools/visual-evidence/manifest.ts';
 /**
  * Kit-local reference generators — autogen of `project/reference/*` (INVENTORY,
  * CODEBASE, HOOKS, SCHEMA, API). Each shells a `scripts/tools/generate-*.ts`
@@ -336,3 +433,39 @@ export const RETIRED_SCRIPT_CMDS = {
     ],
     [E2E_UI_SCRIPT_NAME]: [E2E_UI_SCRIPT_CMD, ...(OBSOLETE_SCRIPT_CMDS[E2E_UI_SCRIPT_NAME] ?? [])],
 };
+/**
+ * The Vercel build command of a derivative's `package.json`, and the ONE reordering the CLI
+ * performs on it.
+ *
+ * WHY THE ORDER IS THE WHOLE POINT. The kit used to ship `pnpm db:migrate && pnpm build`, with
+ * a reason on record across the kit's prose: "migrate falla → build falla → no deploya". That
+ * reasoning holds — Vercel gates on the exit code of the WHOLE command, not on the order of its
+ * two halves — but it only ever considered the migration failing. The mirror case is the one
+ * that broke a client's production: the migration SUCCEEDS, the build fails after it, Vercel
+ * refuses to promote the deployment, and the production alias keeps serving the PREVIOUS build
+ * against a database that has already moved to the new schema. A deployment rollback does not
+ * undo that, because the schema change is not part of the deployment.
+ *
+ * Building first makes every failure degrade cleanly: the build fails → nothing touched the
+ * database; the migration fails → the command still exits non-zero, the deployment still ends
+ * in ERROR, and drizzle applied each migration in its own transaction. The protection the old
+ * order provided is preserved in full; what changes is that the window where production runs
+ * old code against a new schema shrinks from indefinite to the seconds between the migration
+ * finishing and Vercel promoting — which additive migrations, the correct practice, tolerate.
+ *
+ * WHY IT IS HEAL-ONLY AND NEVER INSERTED. `vercel-build` belongs to the BOILERPLATE, not to the
+ * CLI's alias set: it arrives with `src/` at `factory new` and means nothing in a repo without
+ * Next.js. Putting it in `FACTORY_SCRIPTS` would insert it into a `core`/non-Factory repo,
+ * pointing at a stack that repo does not have. So it is maintained the way `ports.e2e` is —
+ * touched only where it already exists, and only when it carries a value the kit itself
+ * shipped. `package.json` is frozen at bootstrap (BR-FACTORY-006) and is not in the tracked
+ * file set, so the CLI is the only thing that can reach the existing fleet at all.
+ *
+ * `VERCEL_BUILD_OBSOLETE_CMDS` lists whole COMMANDS, byte for byte, exactly as the kit shipped
+ * them — same discipline as `OBSOLETE_SCRIPT_CMDS` and `SHIPPED_E2E_PORT`. A derivative that
+ * appended a flag, or wrote the same intent with different spacing, falls through to preserved:
+ * an unlisted variant erring toward "leave it alone" is the safe side of this mistake.
+ */
+export const VERCEL_BUILD_SCRIPT_NAME = 'vercel-build';
+export const VERCEL_BUILD_SCRIPT_CMD = 'pnpm build && pnpm db:migrate';
+export const VERCEL_BUILD_OBSOLETE_CMDS = ['pnpm db:migrate && pnpm build'];

package/dist/lib/env-file.js

@@ -9,6 +9,7 @@
  */
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { CLIError } from './cli-error.js';
 import { generateAuthSecret } from './vercel-env.js';
 /**
  * Vars that provision owns and sets PER-ENVIRONMENT (or keeps local-only). The
@@ -35,8 +36,9 @@ export const PROVISION_OWNED = new Set([
     'MFA_ENCRYPTION_KEY',
     'WEBAUTHN_RP_ID',
     // LOCAL-ONLY E2E credentials (like DATABASE_URL_MAIN): the E2E runner reads them
-    // from `.env.local` to spin an isolated Neon branch per run. CI gets them as GitHub
-    // Secrets; they must NEVER reach Vercel (a day-2 push would leak the Neon key).
+    // from `.env.local` to spin an isolated Neon branch per run. Both local and CI hold
+    // the SAME project-scoped key (see `writeE2eLocalCreds`); they must NEVER reach
+    // Vercel (a day-2 push would leak it).
     'NEON_API_KEY',
     'NEON_PROJECT_ID',
     // LOCAL-ONLY backlog-central credentials (BSYNC-003): the derivative's `backlog
@@ -97,24 +99,37 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
 /**
  * Write the LOCAL E2E Neon credentials into `.env.local` so `pnpm test:e2e` runs on
  * the dev's machine without a manual `setup:e2e`. The E2E runner reads NEON_API_KEY +
- * NEON_PROJECT_ID from `.env.local` to spin an isolated branch per run. CI gets these
- * as GitHub Secrets (a project-scoped key); locally we reuse the dev's ORG key from
- * the rail (already on their host). Both stay LOCAL-ONLY (PROVISION_OWNED → never
- * pushed to Vercel). Returns false (no-op) when the key/project id is missing or
- * `.env.local` does not exist yet (`writeEnvLocal` creates it first). Safe on an
- * existing file: `setEnvLine` only touches these two keys, preserving the rest.
+ * NEON_PROJECT_ID from `.env.local` to spin an isolated branch per run.
+ *
+ * 🔴 `apiKey` is the PROJECT-SCOPED key provision just minted — the same value CI
+ * gets as a GitHub Secret — and never the rail key. This used to write the rail key
+ * ("locally we reuse the dev's ORG key, already on their host"), which is how a
+ * credential reaching every organization ended up in the `.env.local` of every
+ * derivative. A scoped key 404s on any other project, so it is the only value that
+ * belongs in a per-project file.
+ *
+ * `apiKey` of `null` means "no key was minted in this run" (a resume over an already
+ * complete Neon step, where the value is unrecoverable because it was never
+ * persisted). Then only `NEON_PROJECT_ID` is written — never a fallback to the rail —
+ * and the caller tells the dev the local key was not refreshed.
+ *
+ * Both keys stay LOCAL-ONLY (PROVISION_OWNED → never pushed to Vercel). Returns
+ * false (no-op) when the project id is missing or `.env.local` does not exist yet
+ * (`writeEnvLocal` creates it first). Safe on an existing file: `setEnvLine` only
+ * touches these two keys, preserving the rest.
  */
 export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
-    if (!apiKey || !projectId)
+    if (!projectId)
         return false;
     const localPath = join(rootDir, '.env.local');
     if (!existsSync(localPath))
         return false;
     let body = readFileSync(localPath, 'utf8');
     body = setEnvLine(body, 'NEON_PROJECT_ID', projectId);
-    body = setEnvLine(body, 'NEON_API_KEY', apiKey);
+    if (apiKey)
+        body = setEnvLine(body, 'NEON_API_KEY', apiKey);
     writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
-    chmodSync(localPath, 0o600); // holds NEON_API_KEY → owner-only.
+    chmodSync(localPath, 0o600); // may hold NEON_API_KEY → owner-only.
     return true;
 }
 /**
@@ -182,3 +197,241 @@ export function writeBacklogLocalCreds(rootDir, projectId, apiKey) {
     chmodSync(localPath, 0o600);
     return true;
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// EXTPT-004 — the derivative declares ITS OWN per-environment variables.
+//
+// `PROVISION_OWNED` above is the kit's closed list, and by construction it never
+// sees the derivative's vocabulary: a storage bucket, a queue, any service whose
+// credentials differ between production and preview is born in the project, not in
+// the kit. Without a way to declare those, `env push` uploads one value to BOTH
+// targets and production ends up writing to the development bucket.
+//
+// TWO CHANNELS THAT RECONCILE, not one:
+//
+//   1. {@link PER_ENV_REGISTRY_FILE} at the repo root — the DURABLE registry. It is
+//      DATA (parsed), never a module (imported): the CLI publishes COMPILED and runs
+//      under plain `node` via `npx`, with `tsx` only as a devDependency, so a
+//      `*.project.ts` sibling — the shape the kit uses for `preflight.project.ts` and
+//      `e2e.project.ts`, both loaded by scripts that DO run under tsx — would throw
+//      ERR_UNKNOWN_FILE_EXTENSION in every derivative. It is COMMITTED on purpose:
+//      the policy of what must not reach production belongs in the PR and in every
+//      teammate's clone.
+//   2. {@link PER_ENV_MARKER} in a comment right above the variable in `.env.local` —
+//      the ergonomic channel, declared where the value lives.
+//
+// `env push` RECONCILES: every marker it finds and the registry lacks is appended to
+// the registry (idempotently). See {@link addToPerEnvRegistry} for the add-only rule.
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Repo-root file where the derivative declares its per-environment variables.
+ * Dev-owned (excluded from both distribution profiles → `factory update` never
+ * writes or deletes it) and COMMITTED (it is team policy, not a local preference).
+ */
+export const PER_ENV_REGISTRY_FILE = 'env.project.json';
+/** The JSON key inside {@link PER_ENV_REGISTRY_FILE} holding the declared names. */
+export const PER_ENV_REGISTRY_KEY = 'perEnv';
+/**
+ * Ergonomic marker: a `.env.local` COMMENT carrying this token protects the next
+ * assignment below it (`# @per-env` on the line above `STORAGE_BUCKET_URL=...`).
+ */
+export const PER_ENV_MARKER = '@per-env';
+/** The shape hint appended to every parse/shape failure, so the fix is obvious. */
+const PER_ENV_SHAPE_HINT = `Forma esperada: \`{ "${PER_ENV_REGISTRY_KEY}": ["STORAGE_BUCKET_URL"] }\` ` +
+    '— un objeto con una lista de NOMBRES de variable (nunca valores).';
+/**
+ * Read the derivative's per-environment declaration.
+ *
+ * 🔴 ERROR POLARITY — this is the whole point of the function. `readProductVars` is
+ * fail-safe by ACCIDENT OF PURPOSE: it reads VALUES, so returning `{}` on a read
+ * error means "push nothing". This reads EXCLUSIONS, where an empty result means
+ * "push EVERYTHING" — the dev would believe the lock is shut while the development
+ * bucket credentials land in production. So three conditions, kept apart on purpose:
+ *
+ * - **Absent** → a legitimately empty set, with NO message. This is the common case
+ *   today and must stay perfectly silent.
+ * - **Present but unreadable** (EACCES, EISDIR, …) → throws. Never degrade to empty.
+ * - **Present but unparseable or malformed** → throws, naming the file and the
+ *   problem. Partial exclusions are not a thing: either we know the policy or we stop.
+ *
+ * The caller must run this BEFORE anything reaches Vercel (a throw here aborts the
+ * whole push, `--dry-run` included).
+ */
+export function readPerEnvRegistry(rootDir) {
+    const file = join(rootDir, PER_ENV_REGISTRY_FILE);
+    if (!existsSync(file))
+        return { present: false, keys: [], raw: {} };
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        throw new CLIError(`No pude leer \`${PER_ENV_REGISTRY_FILE}\` (${error.message}). ` +
+            'Ahí están las variables que NO deben subir a Vercel: sin leerlo no puedo ' +
+            'garantizar que se respeten, así que aborto el push en vez de subir de más.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CLIError(`\`${PER_ENV_REGISTRY_FILE}\` no es JSON válido (${error.message}). ` +
+            `${PER_ENV_SHAPE_HINT} Aborté el push: un registro que no puedo leer no protege nada.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CLIError(`\`${PER_ENV_REGISTRY_FILE}\` debe ser un objeto JSON. ${PER_ENV_SHAPE_HINT}`);
+    }
+    const raw = parsed;
+    const declared = raw[PER_ENV_REGISTRY_KEY];
+    if (!Array.isArray(declared) ||
+        declared.some((key) => typeof key !== 'string' || key.trim() === '')) {
+        throw new CLIError(`\`${PER_ENV_REGISTRY_FILE}\` no declara \`${PER_ENV_REGISTRY_KEY}\` como una lista ` +
+            `de nombres de variable. ${PER_ENV_SHAPE_HINT}`);
+    }
+    const keys = [];
+    for (const key of declared) {
+        const name = key.trim();
+        if (!keys.includes(name))
+            keys.push(name);
+    }
+    return { present: true, keys, raw };
+}
+/**
+ * Append names to the registry, preserving every other field of the file.
+ *
+ * 🔴 ADD-ONLY, and this is a guarantee, not an implementation detail. Removing the
+ * `# @per-env` marker from `.env.local` does NOT unprotect the variable: it stays in
+ * the registry until someone edits that file by hand, in a diff a reviewer can see.
+ * Silently unprotecting is the one failure this mechanism cannot afford — a variable
+ * that quietly stops being excluded pushes the development credential to production
+ * on the very next run, with nothing on screen to notice.
+ *
+ * Idempotent: with nothing new to add, the file is not touched at all (no rewrite,
+ * no reformat, no mtime bump). Returns the names actually added.
+ *
+ * 🔴 THE GUARANTEE IS AGAINST THE DISK, NOT AGAINST THE ARGUMENT. Writing
+ * `[...registry.keys, ...added]` from the caller's snapshot cannot drop a key of the
+ * ARGUMENT — and silently drops any key that is on DISK and not in it (a teammate's
+ * commit pulled in between, a hand edit, a second process). A guarantee that holds
+ * only while the caller behaves is not a guarantee, and this module ships to the whole
+ * fleet: so the file is RE-READ here and the union is taken against what is actually
+ * there. A registry unreadable at this point throws, exactly as it does on the way in —
+ * never degrade to overwriting it with a partial list.
+ */
+export function addToPerEnvRegistry(rootDir, registry, keysToAdd) {
+    const onDisk = readPerEnvRegistry(rootDir);
+    const base = [...onDisk.keys];
+    for (const key of registry.keys)
+        if (!base.includes(key))
+            base.push(key);
+    const added = [];
+    for (const key of keysToAdd) {
+        if (!base.includes(key) && !added.includes(key))
+            added.push(key);
+    }
+    if (added.length === 0)
+        return [];
+    // The disk's other fields win: it is the version that may have grown since the read.
+    const body = { ...registry.raw, ...onDisk.raw, [PER_ENV_REGISTRY_KEY]: [...base, ...added] };
+    writeFileSync(join(rootDir, PER_ENV_REGISTRY_FILE), `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+    return added;
+}
+/** Whether an env-file COMMENT line carries the {@link PER_ENV_MARKER} token. */
+function isPerEnvMarkerComment(trimmed) {
+    if (!trimmed.startsWith('#'))
+        return false;
+    return trimmed.slice(1).trim().split(/\s+/).includes(PER_ENV_MARKER);
+}
+/**
+ * Scan an env-file body for the variables marked `# @per-env`.
+ *
+ * A marker comment protects the assignment on the NEXT non-empty line. Blank lines in
+ * between do not break the pairing; ANY other line does — another comment, a
+ * commented-out assignment, a stray word — and the marker is consumed by that one
+ * assignment (it never spills onto the following variables).
+ *
+ * 🔴 THE STRICTNESS IS THE FIX, and the cost is deliberate: an explanatory comment
+ * BETWEEN the marker and its variable no longer protects it (put the explanation on
+ * the marker line itself — `# @per-env — bucket por ambiente`). It used to, because
+ * `armed` only cleared on an assignment, and that over-capture reached the variable
+ * two lines down:
+ *
+ *   # @per-env — bucket por ambiente
+ *   # STORAGE_BUCKET_URL="…"      ← commented out
+ *   NEXT_PUBLIC_APP_NAME="Foo"    ← captured, and nobody asked for it
+ *
+ * That over-capture was once "visible and harmless" — it lived only in memory, for the
+ * duration of one push. It is neither now: `env push` RECONCILES the markers into the
+ * COMMITTED registry, and {@link addToPerEnvRegistry} is add-only by guarantee, so
+ * removing the marker does not undo it. A product variable would stop reaching Vercel
+ * permanently, with the "declared but absent" warning silent (the variable does exist),
+ * and the only remedy would be hand-editing the JSON.
+ */
+export function findPerEnvMarkedKeys(body) {
+    const marked = [];
+    let armed = false;
+    for (const line of body.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        if (trimmed.startsWith('#')) {
+            // A marker arms; any OTHER comment disarms (it is a non-empty line like any other).
+            armed = isPerEnvMarkerComment(trimmed);
+            continue;
+        }
+        const eq = line.indexOf('=');
+        const key = eq === -1 ? '' : line.slice(0, eq).trim();
+        if (armed && key !== '' && !marked.includes(key))
+            marked.push(key);
+        armed = false;
+    }
+    return marked;
+}
+/**
+ * Keys whose ASSIGNMENT line carries the {@link PER_ENV_MARKER} inline
+ * (`STORAGE_BUCKET_URL="x" # @per-env`). That form protects NOTHING — the marker is
+ * only read from a comment line ABOVE the assignment — and it also CORRUPTS the value:
+ * `parseProductVars` splits on the first `=` and does not strip inline comments, and
+ * the quote-stripping no longer applies because the value stops ending in a quote, so
+ * Vercel receives `"x" # @per-env` verbatim.
+ *
+ * Returned so the caller can WARN. Detecting it and protecting silently would be the
+ * worse fix: the dev would keep writing a form that the next reader cannot tell from
+ * the working one.
+ */
+export function findInlinePerEnvMarkers(body) {
+    const keys = [];
+    for (const line of body.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (key === '' || keys.includes(key))
+            continue;
+        if (line.slice(eq + 1).includes(PER_ENV_MARKER))
+            keys.push(key);
+    }
+    return keys;
+}
+/**
+ * Every key assigned in an env-file body, empty values included. Used to tell a
+ * declared-and-present variable (omitted from the push) from a declared-but-absent
+ * one (almost always a typo that protects nothing).
+ */
+export function listEnvKeys(body) {
+    const keys = [];
+    for (const line of body.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (key !== '' && !keys.includes(key))
+            keys.push(key);
+    }
+    return keys;
+}

package/dist/lib/env-wizard.js

@@ -15,6 +15,7 @@ import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CLIError } from './cli-error.js';
 import { PROVISION_OWNED, setEnvLine } from './env-file.js';
+import PUBLIC_ENV_KEYS from './public-env-keys.json' with { type: 'json' };
 /**
  * The real conditionals `.env.example` can't express. Keyed by the DEPENDENT var
  * → the driver answer that reveals it. Kept deliberately small — adding a new
@@ -40,13 +41,6 @@ const SELECTS = {
 const DIVIDER = /^#\s*-{3,}\s*$/;
 const ACTIVE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
 const COMMENTED = /^#\s*([A-Z][A-Z0-9_]*)=(.*)$/;
-const SECRET_KEY = /(_SECRET|_KEY|_TOKEN|_PASSWORD)$/;
-/**
- * `NEXT_PUBLIC_*` vars are public by Next.js convention — they're inlined into
- * the client bundle, so they can never be secrets regardless of their suffix
- * (e.g. NEXT_PUBLIC_AUTH_PASSWORD is a boolean feature flag, not a credential).
- */
-const PUBLIC_PREFIX = /^NEXT_PUBLIC_/;
 function unquote(raw) {
     const v = raw.trim();
     if (v.length >= 2 &&
@@ -111,15 +105,20 @@ export function parseEnvExample(text) {
     return entries;
 }
 /**
- * Classify a var into the widget the wizard renders. Secret detection delegates
- * to `isSecretKey` so classification, masking and review all share one rule
- * (secret suffix AND not `NEXT_PUBLIC_*` — public-by-convention vars are never
- * secrets, e.g. NEXT_PUBLIC_AUTH_PASSWORD="true" is a boolean flag).
+ * Classify a var into the widget the wizard renders. Secret detection delegates to
+ * {@link isPublicEnvKey} — the SAME source `maskValue` reads — so classification,
+ * masking and review can never diverge again. It is also the source of the
+ * `kind: 'secret'` that `tk-provision §205` keys its display rule off: anything the
+ * whitelist does not vouch for arrives at the agent already marked secret, and is
+ * shown masked — never its value, at most its last four characters ({@link maskValue}).
+ *
+ * A var with a fixed choice set (`EMAIL_PROVIDER`) is a `select` first: the choices
+ * are the classification, and every var that has them is public by construction.
  */
 export function questionKind(key, defaultValue) {
     if (SELECTS[key])
         return 'select';
-    if (isSecretKey(key))
+    if (!isPublicEnvKey(key))
         return 'secret';
     if (defaultValue === 'true' || defaultValue === 'false')
         return 'boolean';
@@ -202,12 +201,34 @@ export function applyWizardAnswers(rootDir, answers) {
 // setups (a provider flag on with empty creds). All pure over their inputs.
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * True when `key`'s value is a secret (never printed in review/summary output).
- * `NEXT_PUBLIC_*` keys are excluded: Next.js inlines them into the client bundle,
- * so they're public by convention even when their suffix looks secret-ish.
+ * True when `key` is PROVABLY public — the only thing whose value may be printed.
+ *
+ * 🔴 THE POLARITY IS THE POINT. This used to be `isSecretKey`, a regex over
+ * suffixes that LOOK secret (`_SECRET|_KEY|_TOKEN|_PASSWORD`), which is fail-OPEN:
+ * a name it did not recognise got its value printed verbatim. A derivative that
+ * invents `STRIPE_PRIVATE`, `GITHUB_PAT`, `TWILIO_CREDENTIALS` or `SHORTIO_APIKEY`
+ * had its credential echoed into the `--review` table and into the `--json` an agent
+ * reads — which contradicts `tk-provision §205`, where never printing a
+ * `kind: 'secret'` value is non-negotiable. Recognising what is public instead is
+ * fail-CLOSED: a var nobody declared public protects itself, and the failure mode of
+ * a name this list has not caught up with is a mask too many, not a leak.
+ *
+ * The list lives in `public-env-keys.json` so adding or removing one key is a data
+ * edit, not a code change.
+ *
+ * PREFIXES ARE SEPARATE FROM KEYS ON PURPOSE, and the reason is different for each:
+ *  - `NEXT_PUBLIC_` is a CONTRACT of Next.js, not a judgement call: those vars are
+ *    inlined into the browser bundle, so they are public by construction whatever
+ *    their suffix looks like (`NEXT_PUBLIC_AUTH_PASSWORD` is a boolean feature flag).
+ *  - `RATE_LIMIT_` is a growing FAMILY of tuning numbers; a derivative that adds
+ *    `RATE_LIMIT_CHECKOUT_REQUESTS` should not have to edit a list to see its value.
+ * The 22 explicit keys ARE judgement, one name at a time — which is why they are
+ * enumerated instead of matched.
  */
-export function isSecretKey(key) {
-    return !PUBLIC_PREFIX.test(key) && SECRET_KEY.test(key);
+export function isPublicEnvKey(key) {
+    if (PUBLIC_ENV_KEYS.prefixes.some((prefix) => key.startsWith(prefix)))
+        return true;
+    return PUBLIC_ENV_KEYS.keys.includes(key);
 }
 /** Parse an env-file body into `{ KEY: value }` (unquoted), skipping comments/blanks. */
 export function parseEnvBody(body) {
@@ -225,11 +246,77 @@ export function parseEnvBody(body) {
     }
     return out;
 }
-/** Mask a value for display: secrets → `••••••••`, everything else verbatim. */
+/** Width of a masked display, ALWAYS — suffix or not. See {@link maskValue}. */
+const MASK_WIDTH = 12;
+/** Trailing characters of a masked value left readable. */
+const MASK_VISIBLE_SUFFIX = 4;
+/**
+ * Below this length the value is hidden WHOLE — no suffix at all.
+ *
+ * The threshold is about what FRACTION four characters are: at 12 they are a third, and
+ * below that the share climbs fast — at 8 the suffix would be half the value.
+ *
+ * 🔴 MEASURE AGAINST THE POPULATION THIS FUNCTION ACTUALLY SEES, which is narrower than
+ * `.env.example`: `buildQuestionPlan` drops the provision-owned vars (`DATABASE_URL`,
+ * `AUTH_SECRET` never reach a review), and the whitelist returns the public ones in the
+ * clear. What is left masked today is four keys — the two OAuth secrets, the Resend key and
+ * `EMAIL_SERVER_PASSWORD` — plus whatever the derivative invents. The SMTP host, port and
+ * user are whitelisted: masking a hostname and a port number protected nothing and made the
+ * review less useful.
+ */
+const MASK_MIN_LENGTH = 12;
+/** Pad `visible` to {@link MASK_WIDTH} with bullets, so every masked display is one width. */
+function padMask(visible) {
+    return '•'.repeat(MASK_WIDTH - visible.length) + visible;
+}
+/**
+ * Mask a value for display: a PROVABLY PUBLIC key ({@link isPublicEnvKey}) shows its
+ * value, everything else shows its last {@link MASK_VISIBLE_SUFFIX} characters behind
+ * bullets — or nothing at all below {@link MASK_MIN_LENGTH}. An empty value stays empty:
+ * there is nothing to hide and the caller flags it as `(sin configurar)`.
+ *
+ * WHY A SUFFIX AT ALL, since `tk-provision §205` is what governs here. Fully hidden, every
+ * credential renders identically, so the review cannot answer the one question it is opened
+ * for while rotating a key: *is the value in this file the old one or the new one?* Four
+ * trailing characters answer it for a provider token and are useless on their own. The rule
+ * that survives is the one that matters: the VALUE is never printed — the dev opens
+ * `.env.local` to read it whole.
+ *
+ * 🔴 WHERE THE SUFFIX ANSWERS NOTHING, and the caller should not trust it: a value whose
+ * tail is CONSTANT rather than random. A connection string ending in `?sslmode=require`
+ * renders `••••••••uire` before and after a rotation, and `parseEnvBody` keeps an inline
+ * `# rotado 2026-08` as part of the value, so the four characters shown can be the
+ * developer's own comment. The display cannot tell those apart from a real tail, so it
+ * distinguishes provider tokens and nothing else.
+ *
+ * 🔴 AND WHERE IT COSTS MORE THAN IT DOES ELSEWHERE: a value a HUMAN typed. Against a
+ * provider token four characters are noise — 16 bits off a 160-bit GitHub secret. Against
+ * `Primavera2026!` they are the patterned tail (`026!`), which does not leak entropy but
+ * CONFIRMS the mangling rule, and that is the expensive half of a dictionary attack. Of the
+ * keys this function masks, `EMAIL_SERVER_PASSWORD` is the one someone types. One rule for
+ * all of them is a deliberate call — a name-shaped exception is the very thing this module
+ * was rewritten to remove — so the caller carries the knowledge instead: that mailbox
+ * usually sends the product's transactional mail AND recovers its accounts, so give it a
+ * generated password, not a memorable one.
+ *
+ * THE SUFFIX, NOT THE PREFIX, and the difference is not cosmetic: provider tokens are
+ * front-loaded with a family marker (`ghp_`, `sk-`, `re_`, `npg_`), so a prefix would print
+ * what every token of that provider shares and identify nothing.
+ *
+ * FIXED WIDTH, always {@link MASK_WIDTH}: a display that shrank for short values would say
+ * out loud which credentials are under twelve characters — that is, which are weak — and in
+ * the `--json` that is a machine-readable string length, not an impression.
+ *
+ * The rule is the same for the printed table and for the `--json` an agent reads. One rule,
+ * not two — the divergence between two ways of deciding what is a secret is the defect this
+ * module was rewritten to remove.
+ */
 export function maskValue(key, value) {
     if (!value)
         return value;
-    return isSecretKey(key) ? '••••••••' : value;
+    if (isPublicEnvKey(key))
+        return value;
+    return padMask(value.length >= MASK_MIN_LENGTH ? value.slice(-MASK_VISIBLE_SUFFIX) : '');
 }
 /** Override the `defaultValue` of any question whose key appears in `overrides`. */
 export function applyDefaultOverrides(questions, overrides) {
@@ -310,8 +397,10 @@ export function generateVapidKeys() {
 }
 /**
  * Build a secret-safe review of `.env.local` for the final "here's how your app is
- * configured" summary. Secret values are masked; empty values are flagged. Callers
- * pass the questions they want shown (typically the ACTIVE ones for the resolved env).
+ * configured" summary. Everything the whitelist does not vouch for is masked; empty
+ * values are flagged. Callers pass the questions they want shown (typically the ACTIVE
+ * ones for the resolved env). The `--json` of `factory env wizard --review` serialises
+ * these same rows, so the agent-facing output obeys the identical rule.
  */
 export function buildEnvReview(questions, body) {
     const env = parseEnvBody(body);