@timekast/factory 1.26.0 → 1.28.0

package/dist/commands/doctor.js

@@ -13,8 +13,9 @@
  *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
  *     update, not yet available).
  *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
- *     generated `.sql`, so its `vercel-build` (`pnpm db:migrate && pnpm build`)
- *     would migrate an empty database. INFORMATIONAL — see below.
+ *     generated `.sql`, so its `vercel-build` (`pnpm build && pnpm db:migrate`)
+ *     has nothing to apply and its first deploy never creates the tables.
+ *     INFORMATIONAL — see below.
  *
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
@@ -65,8 +66,8 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
  */
 export const MISSING_INITIAL_MIGRATION_NOTICE = `⚠ Falta la migración inicial: hay schema en \`${SCHEMA_DIR}/\` y ningún \`.sql\` en ` +
     `\`${MIGRATIONS_DIR}/\`.\n` +
-    '  El deploy corre `pnpm db:migrate && pnpm build`, así que el primer build migraría una ' +
-    'base vacía. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
+    '  El deploy corre `pnpm build && pnpm db:migrate`, así que el primer deploy no crearía ' +
+    'ninguna tabla. Genera la migración con `pnpm db:generate` y commitéala antes del próximo ' +
     'deploy.\n' +
     '  (Aviso informativo: `factory doctor` no bloquea — sale con éxito de todos modos.)';
 /** Parse `doctor`'s argv slice into flags. Unknown flags are ignored. */

package/dist/commands/env.js

@@ -13,7 +13,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
-import { PROVISION_OWNED, setEnvLine } from '../lib/env-file.js';
+import { PER_ENV_MARKER, PER_ENV_REGISTRY_FILE, PROVISION_OWNED, addToPerEnvRegistry, findInlinePerEnvMarkers, findPerEnvMarkedKeys, listEnvKeys, readPerEnvRegistry, setEnvLine, } from '../lib/env-file.js';
 import { applyDefaultOverrides, applyWizardAnswers, buildEnvReview, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, } from '../lib/env-wizard.js';
 import { defaultEnvPath, readVercelToken } from '../lib/provision-preflight.js';
 import { readProvisionState } from '../lib/provision-state.js';
@@ -30,23 +30,40 @@ export const REDEPLOY_NOTICE = 'ℹ️  Las variables aplican en el próximo dep
 export function parseEnvPushFlags(argv) {
     return { dryRun: argv.includes('--dry-run') };
 }
+/** No extra exclusions — the common case (the derivative declared nothing). */
+const NO_PER_ENV_KEYS = new Set();
 /**
- * Parse `.env.local` into the product vars to push: skip comments/blanks, the
- * provision-owned keys, and empty values. First-`=` split; surrounding quotes
- * stripped (mirrors the rail reader in provision.ts).
+ * Read `.env.local` as text, or `''` when it is absent or unreadable.
+ *
+ * Fail-SAFE on purpose, and the polarity is the opposite of `readPerEnvRegistry`:
+ * this file is the source of VALUES, so an empty body means "there is nothing to
+ * push" — the harmless direction. The registry is the source of EXCLUSIONS, where
+ * an empty result would mean "push everything", so it throws instead. Do NOT
+ * copy this `catch` over there.
  */
-export function readProductVars(filePath) {
-    const out = {};
+function readEnvBody(filePath) {
     if (!existsSync(filePath))
-        return out;
-    let text;
+        return '';
     try {
-        text = readFileSync(filePath, 'utf8');
+        return readFileSync(filePath, 'utf8');
     }
     catch {
-        return out;
+        return '';
     }
-    for (const line of text.split('\n')) {
+}
+/**
+ * Parse an `.env.local` body into the product vars to push: skip comments/blanks,
+ * the provision-owned keys, the per-environment keys the derivative declared, and
+ * empty values. First-`=` split; surrounding quotes stripped (mirrors the rail
+ * reader in provision.ts).
+ *
+ * `perEnvKeys` only ever SUBTRACTS from the push — it is applied ALONGSIDE
+ * `PROVISION_OWNED` (a union), never instead of it, so a derivative cannot name a
+ * provision-owned key to opt it back in.
+ */
+export function parseProductVars(body, perEnvKeys = NO_PER_ENV_KEYS) {
+    const out = {};
+    for (const line of body.split('\n')) {
         const trimmed = line.trimStart();
         if (trimmed === '' || trimmed.startsWith('#'))
             continue;
@@ -54,7 +71,7 @@ export function readProductVars(filePath) {
         if (eq === -1)
             continue;
         const key = line.slice(0, eq).trim();
-        if (key === '' || PROVISION_OWNED.has(key))
+        if (key === '' || PROVISION_OWNED.has(key) || perEnvKeys.has(key))
             continue;
         let value = line.slice(eq + 1).replace(/\s+$/, '');
         if (value.length >= 2 &&
@@ -68,6 +85,10 @@ export function readProductVars(filePath) {
     }
     return out;
 }
+/** {@link parseProductVars} over the file at `filePath`. */
+export function readProductVars(filePath, perEnvKeys = NO_PER_ENV_KEYS) {
+    return parseProductVars(readEnvBody(filePath), perEnvKeys);
+}
 /** Read `{ projectId, teamId }` from `.vercel/project.json` (written by provision). */
 function readProjectLink(rootDir) {
     const file = vercelProjectPath(rootDir);
@@ -90,13 +111,65 @@ function readProjectLink(rootDir) {
     return { projectId, teamId };
 }
 export async function runEnvPush(flags, rootDir = process.cwd()) {
-    const productVars = readProductVars(path.join(rootDir, '.env.local'));
+    const body = readEnvBody(path.join(rootDir, '.env.local'));
+    // Resolve the derivative's per-environment declaration BEFORE anything can reach
+    // Vercel: a present-but-broken registry throws here and aborts the whole run
+    // (`--dry-run` included), instead of showing a plan as if nothing were protected.
+    const registry = readPerEnvRegistry(rootDir);
+    const marked = findPerEnvMarkedKeys(body);
+    const pendingAdds = marked.filter((key) => !registry.keys.includes(key));
+    // Reconciliation: a marker the registry lacks is APPENDED to it (add-only — see
+    // `addToPerEnvRegistry`). `--dry-run` reports it and writes nothing.
+    if (pendingAdds.length > 0 && !flags.dryRun) {
+        addToPerEnvRegistry(rootDir, registry, pendingAdds);
+    }
+    // Protected = registry ∪ marker ∪ PROVISION_OWNED. A union, never a replacement:
+    // the derivative's declaration can only SUBTRACT variables from the push.
+    const perEnvKeys = new Set([...registry.keys, ...marked]);
+    const productVars = parseProductVars(body, perEnvKeys);
     const keys = Object.keys(productVars).sort();
-    if (keys.length === 0) {
-        console.log('No hay variables de producto que subir en `.env.local` ' +
-            '(todo es provision-owned o está vacío).');
-        return;
+    const envKeys = listEnvKeys(body);
+    const omittedProvisionOwned = envKeys.filter((key) => PROVISION_OWNED.has(key)).sort();
+    // Provision-owned wins the label, so a redundant declaration is listed ONCE.
+    const omittedPerEnv = envKeys
+        .filter((key) => perEnvKeys.has(key) && !PROVISION_OWNED.has(key))
+        .sort();
+    const declaredButAbsent = [...perEnvKeys].filter((key) => !envKeys.includes(key)).sort();
+    if (pendingAdds.length > 0) {
+        const names = pendingAdds.join(', ');
+        console.log(flags.dryRun
+            ? `ℹ️  Agregaría a \`${PER_ENV_REGISTRY_FILE}\` por el marcador ` +
+                `\`${PER_ENV_MARKER}\`: ${names} (--dry-run: no escribí nada).`
+            : `✔ Agregué a \`${PER_ENV_REGISTRY_FILE}\` (marcador \`${PER_ENV_MARKER}\`): ${names}.`);
+    }
+    // 🔴 An INLINE marker ABORTS, it does not warn. Warning and pushing anyway shipped a value the
+    // code had ALREADY PROVEN corrupt: `parseProductVars` splits on the first `=` and strips no
+    // inline comment, so `KEY="x" # @per-env` uploads the literal `"x" # @per-env`. Aborting is
+    // exactly as loud as the warning — the dev sees the wrong form and fixes it — and it is the
+    // only option that also protects. Filtered to keys the registry does NOT already cover: for a
+    // protected one the diagnosis would be false (it does not go up at all), and a message that
+    // sometimes lies trains everyone to skip reading it.
+    const inlineMarked = findInlinePerEnvMarkers(body).filter((key) => !perEnvKeys.has(key));
+    if (inlineMarked.length > 0) {
+        throw new CLIError(`${inlineMarked.map((key) => `\`${key}\``).join(', ')} lleva \`${PER_ENV_MARKER}\` en la MISMA ` +
+            'línea de la asignación. Ahí no protege nada, y además el valor subiría con el comentario ' +
+            'pegado (a Vercel llegaría el texto literal, comillas incluidas).\n' +
+            `  El marcador va en un comentario en la línea de ARRIBA (\`SK.md §7.2\`). Aborté el push.`);
+    }
+    for (const key of declaredButAbsent) {
+        console.log(`⚠ \`${key}\` está declarada por ambiente pero no aparece en \`.env.local\` ` +
+            '— revisa si es un typo: así no está protegiendo nada.');
     }
+    /** Names + reason, NEVER values: the omitted vars are the secret-bearing ones. */
+    const printOmitted = () => {
+        if (omittedProvisionOwned.length === 0 && omittedPerEnv.length === 0)
+            return;
+        console.log('\nOmitidas (no se envían):');
+        for (const key of omittedProvisionOwned)
+            console.log(`  ${key} — provision-owned`);
+        for (const key of omittedPerEnv)
+            console.log(`  ${key} — declarada por ambiente`);
+    };
     const targets = ['production', 'preview'];
     const plan = keys.map((key) => ({
         key,
@@ -104,12 +177,23 @@ export async function runEnvPush(flags, rootDir = process.cwd()) {
         target: targets,
     }));
     if (flags.dryRun) {
-        console.log(`Plan (${plan.length} vars → production, preview):`);
-        for (const key of keys)
-            console.log(`  ${key}`);
+        if (keys.length === 0) {
+            console.log('No hay variables de producto que subir en `.env.local`.');
+        }
+        else {
+            console.log(`Plan (${plan.length} vars → production, preview):`);
+            for (const key of keys)
+                console.log(`  ${key}`);
+        }
+        printOmitted();
         console.log('\n(--dry-run: nada se envió a Vercel.)');
         return;
     }
+    if (keys.length === 0) {
+        console.log('No hay variables de producto que subir en `.env.local` ' +
+            '(todo es provision-owned, está declarado por ambiente, o está vacío).');
+        return;
+    }
     const { projectId, teamId } = readProjectLink(rootDir);
     const token = readVercelToken(defaultEnvPath());
     if (!token) {
@@ -219,9 +303,11 @@ export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {
 }
 /**
  * `factory env wizard --review [--json]` — a secret-safe summary of the resolved
- * `.env.local`. Non-secret values are shown; secret values are masked; empty ones
- * are flagged. This is what the guided flow shows the dev at the end (the agent
- * NEVER echoes raw secrets) — the dev opens `.env.local` to see the full values.
+ * `.env.local`. Non-secret values are shown; secret values are masked down to their
+ * last four characters, enough to tell WHICH value is in place while rotating and
+ * useless on their own; empty ones are flagged. This is what the guided flow shows
+ * the dev at the end (the agent NEVER echoes a raw secret) — the dev opens
+ * `.env.local` to see the full values.
  */
 export function runEnvWizardReview(flags, rootDir = process.cwd()) {
     const localPath = path.join(rootDir, '.env.local');
@@ -252,7 +338,7 @@ export function runEnvWizardReview(flags, rootDir = process.cwd()) {
         for (const w of warnings)
             console.log(`  ⚠ ${w}`);
     }
-    console.log('\nAbre `.env.local` para ver los valores completos (los secretos no se imprimen).');
+    console.log('\nAbre `.env.local` para ver los valores completos (de un secreto solo se ven sus últimos 4).');
 }
 /**
  * `factory env wizard --gen-vapid` — generate a VAPID keypair and write it to