@timekast/factory 1.14.2 → 1.15.0

package/dist/commands/env.js

@@ -0,0 +1,186 @@
+/**
+ * `factory env push` — day-2 environment variable sync to Vercel.
+ *
+ * Reads `.env.local` and pushes ONLY the product vars (everything EXCEPT the
+ * provision-owned, per-environment vars) to `production` + `preview` via the
+ * Vercel REST API. Reuses `pushEnvPlan` + `readVercelToken` + the existing
+ * `.vercel/project.json` link — no `vercel link`, no re-implemented REST push,
+ * no risk of clobbering the per-env DATABASE_URL/AUTH_SECRET that provision set.
+ *
+ * Exposed to derivatives as `pnpm env:push` (an npx alias). Run it after editing
+ * `.env.local` to add a new product variable post-provision.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from '../lib/cli-error.js';
+import { PROVISION_OWNED } from '../lib/env-file.js';
+import { applyWizardAnswers, buildQuestionPlan, parseEnvExample, } from '../lib/env-wizard.js';
+import { defaultEnvPath, readVercelToken } from '../lib/provision-preflight.js';
+import { pushEnvPlan, vercelProjectPath, VercelApiError, } from '../lib/vercel-env.js';
+// Re-exported so existing importers (and `cli/tests/unit/env-push.test.ts`) keep
+// resolving PROVISION_OWNED from this module after it moved to `lib/env-file.js`.
+export { PROVISION_OWNED };
+export function parseEnvPushFlags(argv) {
+    return { dryRun: argv.includes('--dry-run') };
+}
+/**
+ * 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).
+ */
+export function readProductVars(filePath) {
+    const out = {};
+    if (!existsSync(filePath))
+        return out;
+    let text;
+    try {
+        text = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.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 === '' || PROVISION_OWNED.has(key))
+            continue;
+        let value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        if (value === '')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/** Read `{ projectId, teamId }` from `.vercel/project.json` (written by provision). */
+function readProjectLink(rootDir) {
+    const file = vercelProjectPath(rootDir);
+    if (!existsSync(file)) {
+        throw new CLIError('No encontré `.vercel/project.json`. Corre `/provision` (o `factory provision`) ' +
+            'para vincular el proyecto Vercel antes de subir variables.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError('No pude parsear `.vercel/project.json`.');
+    }
+    const projectId = parsed.projectId;
+    const teamId = parsed.teamId ?? parsed.orgId;
+    if (!projectId || !teamId) {
+        throw new CLIError('`.vercel/project.json` no tiene `projectId`/`teamId`.');
+    }
+    return { projectId, teamId };
+}
+export async function runEnvPush(flags, rootDir = process.cwd()) {
+    const productVars = readProductVars(path.join(rootDir, '.env.local'));
+    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 targets = ['production', 'preview'];
+    const plan = keys.map((key) => ({
+        key,
+        value: productVars[key],
+        target: targets,
+    }));
+    if (flags.dryRun) {
+        console.log(`Plan (${plan.length} vars → production, preview):`);
+        for (const key of keys)
+            console.log(`  ${key}`);
+        console.log('\n(--dry-run: nada se envió a Vercel.)');
+        return;
+    }
+    const { projectId, teamId } = readProjectLink(rootDir);
+    const token = readVercelToken(defaultEnvPath());
+    if (!token) {
+        throw new CLIError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`. ' +
+            'Corre `factory secrets <archivo>` para bajar el token y reintenta.');
+    }
+    try {
+        const result = await pushEnvPlan(projectId, token, teamId, plan);
+        console.log(`✔ env push: ${result.created.length} creadas, ${result.updated.length} actualizadas ` +
+            '(production, preview).');
+    }
+    catch (error) {
+        if (error instanceof VercelApiError) {
+            throw new CLIError(`Vercel rechazó el push de env: ${error.message}`);
+        }
+        throw error;
+    }
+}
+export function parseEnvWizardFlags(argv) {
+    return {
+        plan: argv.includes('--plan'),
+        apply: argv.includes('--apply'),
+        json: argv.includes('--json'),
+        push: argv.includes('--push'),
+    };
+}
+function readEnvExamplePlan(rootDir) {
+    const examplePath = path.join(rootDir, '.env.example');
+    if (!existsSync(examplePath)) {
+        throw new CLIError('No encontré `.env.example` en este proyecto. El wizard deriva las preguntas de ahí.');
+    }
+    return buildQuestionPlan(parseEnvExample(readFileSync(examplePath, 'utf8')));
+}
+/** `factory env wizard --plan [--json]` — emit the question plan. */
+export function runEnvWizardPlan(flags, rootDir = process.cwd()) {
+    const questions = readEnvExamplePlan(rootDir);
+    if (flags.json) {
+        process.stdout.write(`${JSON.stringify({ questions }, null, 2)}\n`);
+        return;
+    }
+    console.log(`Plan del wizard de env — ${questions.length} variables:\n`);
+    let section = '';
+    for (const q of questions) {
+        if (q.section !== section) {
+            section = q.section;
+            console.log(`## ${section}`);
+        }
+        const gate = q.showWhen ? `  (si ${q.showWhen.key} ∈ {${q.showWhen.in.join(', ')}})` : '';
+        console.log(`  - ${q.key} [${q.kind}]${gate}`);
+    }
+}
+async function readStdinJson() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * `factory env wizard --apply [--push]` — read `{ answers, push? }` JSON from
+ * stdin, write the answers to `.env.local`, and optionally push product vars.
+ */
+export async function runEnvWizardApply(flags, rootDir = process.cwd(), deps = {}) {
+    const raw = await (deps.readStdin ?? readStdinJson)();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CLIError('Esperaba JSON `{ "answers": { KEY: "value" }, "push"?: bool }` por stdin.');
+    }
+    const answers = parsed.answers ?? {};
+    const written = applyWizardAnswers(rootDir, answers);
+    console.log(`✔ Escribí ${written.length} variable(s) en \`.env.local\`.`);
+    const shouldPush = flags.push || parsed.push === true;
+    if (!shouldPush) {
+        console.log('ℹ️  Para subirlas a Vercel cuando quieras: `pnpm env:push`.');
+        return;
+    }
+    const push = deps.push ?? ((dir) => runEnvPush({ dryRun: false }, dir));
+    await push(rootDir);
+}

package/dist/commands/invite-admin.js

@@ -0,0 +1,128 @@
+/**
+ * `factory invite-admin` — mint a single-use super_admin invite for a derivative.
+ *
+ * Replaces the old `SUPER_ADMIN_*` seed. The actual minting lives in the kit
+ * script `scripts/tools/invite-admin.ts` (it needs the kit's `@/lib/invites` +
+ * `@/lib/email`, which this CLI must not import). This command's only job is to
+ * resolve the TARGET branch's connection string from `.env.local` and spawn that
+ * script with it:
+ *
+ *   - `--target develop` (default) → `DATABASE_URL`     (the develop branch)
+ *   - `--target main`              → `DATABASE_URL_MAIN` (production)
+ *
+ * `--target main` is consumed by SETUP-002 after the first deploy+migrate; the
+ * accept link must point at production, so pass `--app-url=https://...` there.
+ *
+ * Usage:
+ *   factory invite-admin --email=you@example.com [--target develop|main] [--app-url=<url>]
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from '../lib/cli-error.js';
+/** Map a target branch to the `.env.local` var holding its connection string. */
+export const TARGET_DB_VAR = {
+    develop: 'DATABASE_URL',
+    main: 'DATABASE_URL_MAIN',
+};
+/** Repo-relative path to the kit script this command spawns. */
+export const INVITE_ADMIN_SCRIPT = 'scripts/tools/invite-admin.ts';
+function parseTarget(value) {
+    if (value === 'develop' || value === 'main')
+        return value;
+    throw new CLIError(`\`--target\` inválido: \`${value ?? '(vacío)'}\`. Usa \`develop\` o \`main\`.`);
+}
+export function parseInviteAdminFlags(argv) {
+    let email = null;
+    let target = 'develop';
+    let appUrl = null;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--email='))
+            email = arg.slice('--email='.length);
+        else if (arg === '--email')
+            email = argv[++i] ?? null;
+        else if (arg.startsWith('--target='))
+            target = parseTarget(arg.slice('--target='.length));
+        else if (arg === '--target')
+            target = parseTarget(argv[++i]);
+        else if (arg.startsWith('--app-url='))
+            appUrl = arg.slice('--app-url='.length);
+        else if (arg === '--app-url')
+            appUrl = argv[++i] ?? null;
+        else if (!arg.startsWith('-') && email === null)
+            email = arg; // bare positional email
+    }
+    return { email, target, appUrl };
+}
+/**
+ * Read a single KEY from a derivative's `.env.local`. Split on the first `=`,
+ * strip surrounding quotes (mirrors `readProductVars` in `env.ts`). Returns null
+ * when the file or the key is absent/empty.
+ */
+export function readEnvLocalVar(rootDir, key) {
+    const file = path.join(rootDir, '.env.local');
+    if (!existsSync(file))
+        return null;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1 || line.slice(0, eq).trim() !== key)
+            continue;
+        let value = line.slice(eq + 1).trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        return value || null;
+    }
+    return null;
+}
+export async function runInviteAdmin(flags, rootDir = process.cwd(), deps = {}) {
+    if (!flags.email) {
+        throw new CLIError('Falta el email. Uso: `factory invite-admin --email=you@example.com [--target develop|main]`.');
+    }
+    if (!existsSync(path.join(rootDir, INVITE_ADMIN_SCRIPT))) {
+        throw new CLIError(`No encontré \`${INVITE_ADMIN_SCRIPT}\`. Corre \`factory update\` para traer el ` +
+            'script del kit antes de invitar al admin.');
+    }
+    // Resolve the target branch's connection string. develop is the local default
+    // (the script's own dotenv loads DATABASE_URL from .env.local), but we resolve
+    // it anyway to fail early with a clear message; for main we MUST override.
+    const dbVar = TARGET_DB_VAR[flags.target];
+    const dbUrl = readEnvLocalVar(rootDir, dbVar);
+    if (!dbUrl) {
+        throw new CLIError(`No encontré \`${dbVar}\` en \`.env.local\` (target: ${flags.target}). ` +
+            'Corre `/provision` (o `factory provision`) para escribir las connection strings.');
+    }
+    const env = { ...process.env, DATABASE_URL: dbUrl };
+    // For main the accept link must point at production, not localhost — the
+    // caller (SETUP-002) passes the deployed domain via --app-url.
+    if (flags.appUrl)
+        env.NEXT_PUBLIC_APP_URL = flags.appUrl;
+    console.log(`→ Creando invitación de super_admin (${flags.target}) para ${flags.email}…`);
+    // `pnpm exec tsx` resolves the kit's local tsx (a devDependency) — same
+    // package-manager assumption provision already makes (`pnpm install`). The
+    // script reads .env.local for the rest of its config (email provider, app URL)
+    // and uses the DATABASE_URL we pass for the chosen branch.
+    const run = deps.run ?? ((file, args, options) => execa(file, args, { ...options, stdio: 'inherit' }));
+    try {
+        await run('pnpm', ['exec', 'tsx', INVITE_ADMIN_SCRIPT, `--email=${flags.email}`], {
+            cwd: rootDir,
+            env,
+        });
+    }
+    catch {
+        throw new CLIError('El script `invite-admin` falló. Revisa la salida de arriba.');
+    }
+}

package/dist/commands/provision.js

@@ -29,6 +29,7 @@ import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, ensureCnameRecord,
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { defaultEnvPath, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
 import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, getLinkedRepoId, getVercelDomainStatus, GitHubAppNotInstalledError, linkGitRepo, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, writeVercelProjectJson, } from '../lib/vercel-env.js';
+import { writeEnvLocal } from '../lib/env-file.js';
 import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
@@ -680,7 +681,7 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
         console.log(`  ↻ ${v.key} [${v.target.join(', ')}]`);
     }
     // Generate the gitignored `.env.local` so the dev can run the app, migrations and
-    // seeds locally (`pnpm dev`/`db:migrate`/`db:seed:admin` read `.env.local`). Uses
+    // seeds locally (`pnpm dev`/`db:migrate`/`invite:admin` read `.env.local`). Uses
     // the DIRECT strings (single-process tooling/migrations, never the pooler).
     // DATABASE_URL → develop (safe default), DATABASE_URL_MAIN → main (db:query:main).
     const envLocal = writeEnvLocal(rootDir, neonSecrets, { force: deps.force });
@@ -730,47 +731,11 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
             'El proyecto + las env vars ya están listos; pushea o redeploya a mano.');
     }
 }
-/**
- * Generate the gitignored `.env.local` from the derivative's `.env.example`, filling
- * the two Neon connection strings + a fresh AUTH_SECRET. Without this the dev cannot
- * run `pnpm dev`/`db:migrate`/`db:seed:admin` locally — those read `.env.local`, which
- * provision otherwise never creates (it only syncs env to Vercel).
- *
- * Uses the DIRECT (non-pooler) strings: `.env.local` drives single-process tooling
- * (`drizzle-kit migrate`/`generate`, `db:seed`, `db:query`) + local `pnpm dev` — none
- * of which want the PgBouncer pooler (the pooled host is only for the serverless
- * runtime on Vercel). Do NOT swap these back to the pooled variants.
- *
- * DATABASE_URL → the develop branch (safe default for local work); DATABASE_URL_MAIN
- * → the main branch (read by `pnpm db:query:main`). NEVER clobbers an existing
- * `.env.local` (the dev may have edited it) unless `--force`. The `.env.example` stays
- * the SSOT of which keys exist; the keys are appended if absent (older scaffolds).
- */
-export function writeEnvLocal(rootDir, neon, opts = {}) {
-    const examplePath = join(rootDir, '.env.example');
-    if (!existsSync(examplePath))
-        return 'no-example';
-    const localPath = join(rootDir, '.env.local');
-    if (existsSync(localPath) && !opts.force)
-        return 'skipped';
-    let body = readFileSync(examplePath, 'utf8');
-    body = setEnvLine(body, 'DATABASE_URL', neon.developDirect);
-    body = setEnvLine(body, 'DATABASE_URL_MAIN', neon.mainDirect);
-    body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
-    writeFileSync(localPath, body, 'utf8');
-    return 'written';
-}
-/**
- * Replace the value of `KEY=...` in an env-file body, preserving every other line.
- * Appends `KEY="value"` when the key is absent (so an older `.env.example` without
- * `DATABASE_URL_MAIN` still gets it). The value is double-quoted — Neon URLs (pooled
- * or direct) carry `?`/`&` query params that an unquoted dotenv value would truncate.
- */
-function setEnvLine(body, key, value) {
-    const re = new RegExp(`^${key}=.*$`, 'm');
-    const line = `${key}="${value}"`;
-    return re.test(body) ? body.replace(re, line) : `${body.trimEnd()}\n${line}\n`;
-}
+// `writeEnvLocal` + `setEnvLine` moved to `../lib/env-file.js` (shared with the
+// day-2 env wizard); `writeEnvLocal` is imported above for internal use and
+// re-exported here so existing importers (and `cli/tests/unit/provision-env.test.ts`)
+// keep resolving it from this module.
+export { writeEnvLocal };
 /**
  * The HTTPS git URL of the repo `gh repo create` made (`new.ts` creates
  * `${FACTORY_ORG}/${name}` — the canonical remote is its `.git` HTTPS URL). Never

package/dist/index.js

@@ -11,6 +11,9 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
+import { parseEnvPushFlags, parseEnvWizardFlags, runEnvPush, runEnvWizardApply, runEnvWizardPlan, } from './commands/env.js';
+import { parseInviteAdminFlags, runInviteAdmin } from './commands/invite-admin.js';
+import { envWizardFlow } from './tui/env-wizard-flow.js';
 import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/doctor.js';
 import { parseNewFlags, runNew } from './commands/new.js';
 import { parseProvisionFlags, runProvision } from './commands/provision.js';
@@ -39,6 +42,8 @@ Comandos:
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
   provision        Aprovisiona la infra de un derivado (Neon/Vercel/GitHub/DNS) — flag-driven, --json
   secrets <file>   Mergea un archivo KEY=value de secretos de metodología a ~/.claude/.env (chmod 600)
+  env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura .env.local
+  invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
 
 Sobre \`new\`:
   Pregunta el perfil de forma interactiva. Los flags \`--full\` / \`--core\` lo
@@ -105,6 +110,23 @@ Sobre \`status\` y \`doctor\`:
   gh auth, membresía del org) — termina con código 1 si falla algún check, para
   que un lanzador GUI / CI / el TUI puedan ramificar sobre el resultado.
 
+Sobre \`env\`:
+  \`env push\` sube las product vars de \`.env.local\` a Vercel (production+preview),
+  sin tocar las provision-owned. \`env wizard\` configura \`.env.local\`:
+    (sin flags)      Wizard interactivo en la terminal (deriva las preguntas de \`.env.example\`)
+    --plan [--json]  Emite el plan de preguntas (lo consume el agente / la skill tk-provision)
+    --apply [--push] Lee \`{ answers, push? }\` JSON por stdin y escribe \`.env.local\`
+
+Sobre \`invite-admin\`:
+  Materializa el primer super_admin de un derivado por invitación (reemplaza el
+  viejo seed con password en texto plano). Resuelve la connection string del
+  target desde \`.env.local\` y spawnea el script del kit con ella:
+    --email=<addr>   Email que recibe la invitación y será super_admin (requerido)
+    --target=<t>     develop (default, usa DATABASE_URL) | main (usa DATABASE_URL_MAIN)
+    --app-url=<url>  Override del NEXT_PUBLIC_APP_URL del link de aceptación
+                     (úsalo con --target main para que apunte a producción)
+  Alias en el derivado: \`pnpm invite:admin --email=...\`.
+
 Opciones:
   -h, --help       Muestra esta ayuda
   -v, --version    Muestra la versión del CLI
@@ -211,6 +233,40 @@ async function main(argv) {
             await secretsCommand(file);
             return;
         }
+        case 'env': {
+            const sub = rest[0];
+            // `factory env push` — day-2 product-var sync to Vercel (reuses the
+            // provision push path; never touches the per-env provision-owned vars).
+            if (sub === 'push') {
+                await runEnvPush(parseEnvPushFlags(rest.slice(1)));
+                return;
+            }
+            // `factory env wizard` — onboarding env config. `--plan [--json]` and
+            // `--apply` are the non-interactive primitives (the agent/skill drives the
+            // questions); no flags → the interactive TUI flow (TTY-only, hints in headless).
+            if (sub === 'wizard') {
+                const wflags = parseEnvWizardFlags(rest.slice(1));
+                if (wflags.plan) {
+                    runEnvWizardPlan(wflags);
+                    return;
+                }
+                if (wflags.apply) {
+                    await runEnvWizardApply(wflags);
+                    return;
+                }
+                await envWizardFlow();
+                return;
+            }
+            throw new CLIError(`Subcomando de env desconocido: \`${sub ?? '(ninguno)'}\`. ` +
+                'Uso: `factory env push` o `factory env wizard`.');
+        }
+        case 'invite-admin': {
+            // Mint a single-use super_admin invite against the target branch's DB.
+            // Spawns the kit script `scripts/tools/invite-admin.ts` with the resolved
+            // DATABASE_URL — no plaintext admin password anywhere.
+            await runInviteAdmin(parseInviteAdminFlags(rest));
+            return;
+        }
         default:
             throw new CLIError(`Comando desconocido: \`${command}\`.\nEjecuta \`factory --help\` para ver los comandos disponibles.`);
     }

package/dist/lib/constants.js

@@ -81,6 +81,11 @@ export const PUBLISH_SCRIPT_NAME = 'factory:publish';
 export const PUBLISH_SCRIPT_CMD = 'npx @timekast/factory publish';
 export const UNPUBLISH_SCRIPT_NAME = 'factory:unpublish';
 export const UNPUBLISH_SCRIPT_CMD = 'npx @timekast/factory unpublish';
+// Day-2 env var sync. Named `env:push` (parallel to the kit's `env:check`),
+// not `factory:*`, because devs reach for it like a normal env tool. Still goes
+// through `npx` so it resolves without a global install.
+export const ENV_PUSH_SCRIPT_NAME = 'env:push';
+export const ENV_PUSH_SCRIPT_CMD = 'npx @timekast/factory env push';
 /**
  * All convenience scripts the installer ensures in a Node derivative's
  * package.json (each: add if missing, never overwrite a divergent value). Keyed
@@ -93,6 +98,7 @@ export const FACTORY_SCRIPTS = {
     [STATUS_SCRIPT_NAME]: STATUS_SCRIPT_CMD,
     [PUBLISH_SCRIPT_NAME]: PUBLISH_SCRIPT_CMD,
     [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
+    [ENV_PUSH_SCRIPT_NAME]: ENV_PUSH_SCRIPT_CMD,
 };
 /**
  * Kit-local convenience script: the readiness sweep (`pnpm preflight`, consumed
@@ -105,6 +111,16 @@ export const FACTORY_SCRIPTS = {
 export const PREFLIGHT_SCRIPT_NAME = 'preflight';
 export const PREFLIGHT_SCRIPT_CMD = 'tsx scripts/tools/preflight.ts';
 export const PREFLIGHT_SCRIPT_FILE = 'scripts/tools/preflight.ts';
+/**
+ * Kit-local super_admin invite alias. npx-based (resolves the CLI so it gets the
+ * develop/main target switching) but FILE-GATED on the script the CLI spawns —
+ * a core/non-Factory derivative without `scripts/tools/invite-admin.ts` never
+ * gets a broken `invite:admin`. Insert-if-missing; self-heals on the next
+ * update once the script lands (same contract as `preflight`).
+ */
+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 reference generators — autogen of `project/reference/*` (INVENTORY,
  * CODEBASE, HOOKS, SCHEMA, API). Each shells a `scripts/tools/generate-*.mjs`

package/dist/lib/env-file.js

@@ -0,0 +1,73 @@
+/**
+ * `.env.local` authoring primitives — shared between `provision` (the first-run
+ * write of the Neon strings + AUTH_SECRET) and the day-2 env wizard (`env
+ * wizard`, which fills the rest of `.env.example` interactively).
+ *
+ * Both are pure file ops (no network, no prompts): the interactive layer (the
+ * `tk-provision` skill or the TUI) collects answers and calls `setEnvLine`; the
+ * CLI never prompts here, so it stays headless-safe.
+ */
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateAuthSecret } from './vercel-env.js';
+/**
+ * Vars that provision owns and sets PER-ENVIRONMENT (or keeps local-only). The
+ * day-2 paths (`env push`, the env wizard) NEVER touch these: re-pushing
+ * `DATABASE_URL` / `AUTH_SECRET` uniformly would overwrite the distinct
+ * prod↔preview values provision wrote, cross-wiring production to develop.
+ * `DATABASE_URL_MAIN` is local-only (`db:query:main`) and must never reach Vercel.
+ *
+ * MUST be a superset of `buildEnvPlan`'s per-env keys (vercel-env.ts) — enforced
+ * by the anti-drift test in `cli/tests/unit/env-push.test.ts`.
+ */
+export const PROVISION_OWNED = new Set([
+    'DATABASE_URL',
+    'DATABASE_URL_MAIN',
+    'AUTH_SECRET',
+    'NEXT_PUBLIC_APP_ENV',
+]);
+/**
+ * Replace the value of `KEY=...` in an env-file body, preserving every other line.
+ * Appends `KEY="value"` when the key is absent (so an older `.env.example` without
+ * `DATABASE_URL_MAIN` still gets it). The value is double-quoted — Neon URLs (pooled
+ * or direct) carry `?`/`&` query params that an unquoted dotenv value would truncate.
+ */
+export function setEnvLine(body, key, value) {
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    const line = `${key}="${value}"`;
+    return re.test(body) ? body.replace(re, line) : `${body.trimEnd()}\n${line}\n`;
+}
+/**
+ * Generate the gitignored `.env.local` from the derivative's `.env.example`, filling
+ * the two Neon connection strings + a fresh AUTH_SECRET. Without this the dev cannot
+ * run `pnpm dev`/`db:migrate`/`invite:admin` locally — those read `.env.local`, which
+ * provision otherwise never creates (it only syncs env to Vercel).
+ *
+ * Uses the DIRECT (non-pooler) strings: `.env.local` drives single-process tooling
+ * (`drizzle-kit migrate`/`generate`, `db:seed`, `db:query`) + local `pnpm dev` — none
+ * of which want the PgBouncer pooler (the pooled host is only for the serverless
+ * runtime on Vercel). Do NOT swap these back to the pooled variants.
+ *
+ * DATABASE_URL → the develop branch (safe default for local work); DATABASE_URL_MAIN
+ * → the main branch (read by `pnpm db:query:main`). NEVER clobbers an existing
+ * `.env.local` (the dev may have edited it) unless `--force`. The `.env.example` stays
+ * the SSOT of which keys exist; the keys are appended if absent (older scaffolds).
+ */
+export function writeEnvLocal(rootDir, neon, opts = {}) {
+    const examplePath = join(rootDir, '.env.example');
+    if (!existsSync(examplePath))
+        return 'no-example';
+    const localPath = join(rootDir, '.env.local');
+    if (existsSync(localPath) && !opts.force)
+        return 'skipped';
+    let body = readFileSync(examplePath, 'utf8');
+    body = setEnvLine(body, 'DATABASE_URL', neon.developDirect);
+    body = setEnvLine(body, 'DATABASE_URL_MAIN', neon.mainDirect);
+    body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
+    writeFileSync(localPath, body, 'utf8');
+    // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600). Same
+    // discipline the secrets rail uses; matters on the headless multi-tenant
+    // Agent Server where the default umask would leave it world-readable.
+    chmodSync(localPath, 0o600);
+    return 'written';
+}

package/dist/lib/env-wizard.js

@@ -0,0 +1,184 @@
+/**
+ * Env wizard — parse a derivative's `.env.example` into a question plan the
+ * INTERACTIVE layer renders (the `tk-provision` skill via AskUserQuestion, or the
+ * TUI via `prompts`). Everything here is pure + non-interactive: the CLI never
+ * prompts, so it stays headless-safe — the front-end collects the answers and
+ * hands them back to `applyWizardAnswers`.
+ *
+ * `.env.example` is the SSOT of WHICH keys exist; this module derives the
+ * questions (+ their help text) from it. Only the few real conditionals
+ * (EMAIL_PROVIDER → its creds, the OAuth flags → their creds) are encoded as a
+ * small `GATES` map — the one piece of domain knowledge the file can't express.
+ */
+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';
+/**
+ * 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
+ * env var does NOT require touching this unless it is genuinely conditional.
+ */
+const GATES = {
+    EMAIL_FROM: { key: 'EMAIL_PROVIDER', in: ['resend', 'smtp'] },
+    RESEND_API_KEY: { key: 'EMAIL_PROVIDER', in: ['resend'] },
+    EMAIL_SERVER_HOST: { key: 'EMAIL_PROVIDER', in: ['smtp'] },
+    EMAIL_SERVER_PORT: { key: 'EMAIL_PROVIDER', in: ['smtp'] },
+    EMAIL_SERVER_USER: { key: 'EMAIL_PROVIDER', in: ['smtp'] },
+    EMAIL_SERVER_PASSWORD: { key: 'EMAIL_PROVIDER', in: ['smtp'] },
+    EMAIL_SERVER_SECURE: { key: 'EMAIL_PROVIDER', in: ['smtp'] },
+    AUTH_GOOGLE_ID: { key: 'NEXT_PUBLIC_AUTH_GOOGLE', in: ['true'] },
+    AUTH_GOOGLE_SECRET: { key: 'NEXT_PUBLIC_AUTH_GOOGLE', in: ['true'] },
+    AUTH_GITHUB_ID: { key: 'NEXT_PUBLIC_AUTH_GITHUB', in: ['true'] },
+    AUTH_GITHUB_SECRET: { key: 'NEXT_PUBLIC_AUTH_GITHUB', in: ['true'] },
+};
+/** Vars that get a `select` with a fixed choice set instead of free text. */
+const SELECTS = {
+    EMAIL_PROVIDER: ['none', 'resend', 'smtp'],
+};
+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)$/;
+function unquote(raw) {
+    const v = raw.trim();
+    if (v.length >= 2 &&
+        ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/**
+ * Parse `.env.example` into entries, preserving file order. A section title is a
+ * comment line sandwiched between two `# ----` dividers; other comment lines
+ * become the help text of the next var.
+ */
+export function parseEnvExample(text) {
+    const lines = text.split('\n');
+    const entries = [];
+    let section = '';
+    let comment = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].replace(/\s+$/, '');
+        const prev = (lines[i - 1] ?? '').trim();
+        const next = (lines[i + 1] ?? '').trim();
+        if (DIVIDER.test(line))
+            continue; // structural — skip
+        // Section header: a comment sandwiched between two dividers.
+        if (line.startsWith('#') && DIVIDER.test(prev) && DIVIDER.test(next)) {
+            section = line.replace(/^#\s*/, '').trim();
+            comment = [];
+            continue;
+        }
+        const active = line.match(ACTIVE);
+        if (active) {
+            entries.push({
+                key: active[1],
+                section,
+                defaultValue: unquote(active[2]),
+                commented: false,
+                help: comment.join(' ').trim(),
+            });
+            comment = [];
+            continue;
+        }
+        const commented = line.match(COMMENTED);
+        if (commented) {
+            entries.push({
+                key: commented[1],
+                section,
+                defaultValue: unquote(commented[2]),
+                commented: true,
+                help: comment.join(' ').trim(),
+            });
+            comment = [];
+            continue;
+        }
+        if (line.startsWith('#')) {
+            comment.push(line.replace(/^#\s*/, '').trim());
+            continue;
+        }
+        // Blank / other line → break the comment run.
+        comment = [];
+    }
+    return entries;
+}
+function questionKind(key, defaultValue) {
+    if (SELECTS[key])
+        return 'select';
+    if (SECRET_KEY.test(key))
+        return 'secret';
+    if (defaultValue === 'true' || defaultValue === 'false')
+        return 'boolean';
+    return 'text';
+}
+/**
+ * Turn parsed entries into the ordered question plan. Includes:
+ *  - every ACTIVE non-provision-owned var (the product config the dev reviews), and
+ *  - the GATED dependents (email creds, OAuth creds), active or commented.
+ * Excludes provision-owned vars and advanced commented vars (rate-limit, VAPID,
+ * Upstash, Sentry, NextAuth aliases) that aren't gated — those stay manual +
+ * `pnpm env:push`.
+ */
+export function buildQuestionPlan(entries) {
+    const questions = [];
+    const seen = new Set();
+    for (const e of entries) {
+        if (seen.has(e.key))
+            continue;
+        if (PROVISION_OWNED.has(e.key))
+            continue;
+        const gate = GATES[e.key];
+        // A commented var is only included when it's a gated dependent; advanced
+        // commented vars (no gate) are skipped.
+        if (e.commented && !gate)
+            continue;
+        seen.add(e.key);
+        const q = {
+            key: e.key,
+            section: e.section,
+            help: e.help,
+            defaultValue: e.defaultValue,
+            kind: questionKind(e.key, e.defaultValue),
+        };
+        if (SELECTS[e.key])
+            q.choices = SELECTS[e.key];
+        if (gate)
+            q.showWhen = gate;
+        questions.push(q);
+    }
+    return questions;
+}
+/** True when `q`'s gate is satisfied by the answers collected so far. */
+export function isQuestionActive(q, answers) {
+    if (!q.showWhen)
+        return true;
+    const driver = answers[q.showWhen.key];
+    return driver !== undefined && q.showWhen.in.includes(driver);
+}
+/**
+ * Write the collected answers into `.env.local` via `setEnvLine`, preserving
+ * every other line. Falls back to `.env.example` as the base when `.env.local`
+ * doesn't exist yet. NEVER writes provision-owned keys (provision sets those
+ * per-environment). Returns the keys actually written.
+ */
+export function applyWizardAnswers(rootDir, answers) {
+    const localPath = join(rootDir, '.env.local');
+    const examplePath = join(rootDir, '.env.example');
+    const basePath = existsSync(localPath) ? localPath : examplePath;
+    if (!existsSync(basePath)) {
+        throw new CLIError('No encontré `.env.local` ni `.env.example` para escribir las variables.');
+    }
+    let body = readFileSync(basePath, 'utf8');
+    const written = [];
+    for (const [key, value] of Object.entries(answers)) {
+        if (PROVISION_OWNED.has(key))
+            continue; // provision owns these per-env
+        body = setEnvLine(body, key, value);
+        written.push(key);
+    }
+    writeFileSync(localPath, body, 'utf8');
+    // `.env.local` may now hold secrets (API keys, OAuth) → owner-only (0600).
+    chmodSync(localPath, 0o600);
+    return written;
+}

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 { FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { 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, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, UPDATE_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,8 @@ export function kitLocalScripts(rootDir) {
     const scripts = {};
     if (has(PREFLIGHT_SCRIPT_FILE))
         scripts[PREFLIGHT_SCRIPT_NAME] = PREFLIGHT_SCRIPT_CMD;
+    if (has(INVITE_ADMIN_SCRIPT_FILE))
+        scripts[INVITE_ADMIN_SCRIPT_NAME] = INVITE_ADMIN_SCRIPT_CMD;
     for (const gen of GENERATOR_SCRIPTS) {
         if (has(gen.file))
             scripts[gen.name] = gen.cmd;

package/dist/tui/env-wizard-flow.js

@@ -0,0 +1,92 @@
+/**
+ * Env wizard — interactive TUI flow (Capa B). Walks the question plan derived
+ * from `.env.example` with `prompts`, respecting the gates as answers come in,
+ * then applies the answers to `.env.local` and offers to push to Vercel.
+ *
+ * Shares the SAME pure primitives as the agent path (`lib/env-wizard.ts` +
+ * `commands/env.ts`): this file only adds the terminal interaction. No TTY →
+ * degrade with a hint to the headless `--plan`/`--apply` primitives.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import prompts from 'prompts';
+import { runEnvPush } from '../commands/env.js';
+import { CLIError } from '../lib/cli-error.js';
+import { applyWizardAnswers, buildQuestionPlan, isQuestionActive, parseEnvExample, } from '../lib/env-wizard.js';
+/** Ask one question by kind. Returns `undefined` when the user cancels (Ctrl+C). */
+async function askOne(q) {
+    const message = q.help ? `${q.key} — ${q.help}` : q.key;
+    const onCancel = { onCancel: () => true };
+    if (q.kind === 'select') {
+        const choices = (q.choices ?? []).map((c) => ({ title: c, value: c }));
+        const initial = Math.max(0, (q.choices ?? []).indexOf(q.defaultValue));
+        const { v } = await prompts({ type: 'select', name: 'v', message, choices, initial }, onCancel);
+        return v === undefined ? undefined : String(v);
+    }
+    if (q.kind === 'boolean') {
+        const { v } = await prompts({
+            type: 'toggle',
+            name: 'v',
+            message,
+            initial: q.defaultValue === 'true',
+            active: 'true',
+            inactive: 'false',
+        }, onCancel);
+        return v === undefined ? undefined : v ? 'true' : 'false';
+    }
+    if (q.kind === 'secret') {
+        const { v } = await prompts({ type: 'password', name: 'v', message }, onCancel);
+        return v === undefined ? undefined : String(v);
+    }
+    const { v } = await prompts({ type: 'text', name: 'v', message, initial: q.defaultValue }, onCancel);
+    return v === undefined ? undefined : String(v);
+}
+/**
+ * Run the interactive env wizard in `rootDir`. Reachable from `factory env
+ * wizard` (no flags) and from the TUI menu.
+ */
+export async function envWizardFlow(rootDir = process.cwd(), deps = {}) {
+    const isTTY = deps.isTTY ?? Boolean(process.stdout.isTTY);
+    if (!isTTY) {
+        throw new CLIError('El wizard interactivo necesita una terminal. En headless usa ' +
+            '`factory env wizard --plan --json` y `factory env wizard --apply`.');
+    }
+    const examplePath = path.join(rootDir, '.env.example');
+    if (!existsSync(examplePath)) {
+        throw new CLIError('No encontré `.env.example` en este proyecto. El wizard deriva las preguntas de ahí.');
+    }
+    const plan = buildQuestionPlan(parseEnvExample(readFileSync(examplePath, 'utf8')));
+    console.log('\nConfiguremos las variables de entorno del proyecto.\n' +
+        '(Enter conserva el valor por defecto · Ctrl+C cancela sin escribir nada.)\n');
+    const answers = {};
+    let section = '';
+    for (const q of plan) {
+        if (!isQuestionActive(q, answers))
+            continue;
+        if (q.section !== section) {
+            section = q.section;
+            console.log(`\n— ${section} —`);
+        }
+        const value = await askOne(q);
+        if (value === undefined) {
+            console.log('\nCancelado. No se escribió nada en `.env.local`.');
+            return;
+        }
+        answers[q.key] = value;
+    }
+    const written = applyWizardAnswers(rootDir, answers);
+    console.log(`\n✔ Escribí ${written.length} variable(s) en \`.env.local\`.`);
+    const { doPush } = await prompts({
+        type: 'confirm',
+        name: 'doPush',
+        message: '¿Subir las variables de producto a Vercel ahora? (production + preview)',
+        initial: false,
+    }, { onCancel: () => true });
+    if (doPush) {
+        const push = deps.push ?? ((dir) => runEnvPush({ dryRun: false }, dir));
+        await push(rootDir);
+    }
+    else {
+        console.log('ℹ️  Cuando quieras subirlas: `pnpm env:push`.');
+    }
+}

package/dist/tui/menu.js

@@ -23,6 +23,7 @@ import prompts from 'prompts';
 import { parseNewFlags, runNew } from '../commands/new.js';
 import { secretsCommand } from '../commands/secrets.js';
 import { parseUpdateFlags, runUpdate } from '../commands/update.js';
+import { envWizardFlow } from './env-wizard-flow.js';
 import { provisionFlow } from './provision-flow.js';
 /** Prompt for the top-level action. Returns `undefined` if the user cancels. */
 async function promptAction() {
@@ -34,6 +35,7 @@ async function promptAction() {
             { title: 'Nuevo proyecto', value: 'new' },
             { title: 'Actualizar proyecto', value: 'update' },
             { title: 'Aprovisionar (ephemeral)', value: 'provision' },
+            { title: 'Configurar variables de entorno', value: 'env' },
             { title: 'Secrets', value: 'secrets' },
         ],
         initial: 0,
@@ -107,6 +109,7 @@ export async function runTuiMenu(deps = {}) {
     const updateProject = deps.updateProject ?? runUpdate;
     const secrets = deps.secrets ?? secretsCommand;
     const provision = deps.provision ?? provisionFlow;
+    const envWizard = deps.envWizard ?? envWizardFlow;
     // No TTY (CI / pipe): can't read interactive input. Degrade to HELP and return
     // immediately — never hang waiting for input that can't arrive.
     if (!isTTY) {
@@ -128,6 +131,9 @@ export async function runTuiMenu(deps = {}) {
         case 'provision':
             await dispatchProvision({ provision });
             return;
+        case 'env':
+            await envWizard();
+            return;
         case 'secrets':
             await dispatchSecrets({ secrets });
             return;

package/package.json

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