@timekast/factory 2.4.0 → 2.6.0

package/dist/commands/add.js

@@ -12,7 +12,9 @@
  * legacy auto-register lives with its safeguards) → preflight (gh) → resolve
  * profile → download + stage + validate the manifest → install ONLY the manifest
  * files via `applyPlan` (so a `full` tarball never lays down `src/`; `track`
- * excludes it) → write `.timekast/lockfile.json` → ensure `factory:update` (H5).
+ * excludes it) → write `.timekast/lockfile.json` → sync the managed
+ * `.gitattributes` / `.prettierignore` blocks → ensure `factory:update` (H5) →
+ * offer the npm packages the kit's files need and the repo lacks (`kit-deps.ts`).
  *
  * Invariants:
  *   - `add` never touches `src/`, `pj-*`, or any file outside the manifest. It
@@ -23,8 +25,11 @@
  *     is preserved (filtered out of writes) + a warning; only written when absent.
  *   - `add` is for a repo WITHOUT the brain. A repo that already has `.claude/`
  *     or a lockfile is routed to `update` (never a raw re-install).
- *   - `add` overwrites manifest files without prompting — the conflict prompt is
- *     exclusive to `update` (DIST-005).
+ *   - `add` never prompts about FILES — the conflict prompt is exclusive to `update`
+ *     (DIST-005). Its one question is the kit-deps install offer, asked only in a terminal.
+ *     It writes the brain (`.claude/`, `scripts/tools/`) without looking; a kit file
+ *     outside it that the repo already has with its own content (`ci.yml`, `.husky/*`)
+ *     is KEPT, and the kit's copy goes to `<path>.kit-example` (`initial-writes.ts`).
  *   - Atomicity (§7.5): extract + validate in a temp dir before touching the cwd.
  *
  * Expected failures throw `CLIError`; the top-level handler prints + exits.
@@ -35,6 +40,9 @@ import path from 'node:path';
 import { applyPlan, defaultBackupDir, validateStagedManifest } from '../lib/atomic-swap.js';
 import { CLIError } from '../lib/cli-error.js';
 import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
+import { syncDerivedDotfiles } from '../lib/derived-dotfiles.js';
+import { partitionInitialWrites, reportKeptRepoFiles, writeKitExamples, } from '../lib/initial-writes.js';
+import { offerKitDeps, readKitDeps } from '../lib/kit-deps.js';
 import { hasLockfile, writeInitialLockfile } from '../lib/lockfile.js';
 import { detectProfile, maintainKitScripts } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
@@ -125,6 +133,9 @@ export async function runAdd(flags = { core: false, full: false }) {
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
     let version;
+    // The packages the kit's files need (Factory#78), read from the staged tarball before the
+    // `finally` deletes it; offered at the very end, once the brain is in place.
+    let kitDeps = null;
     try {
         const tarball = await downloadProfileTarball(profile, tmpDir);
         const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
@@ -138,19 +149,26 @@ export async function runAdd(flags = { core: false, full: false }) {
         }
         version = manifest.version;
         // Install ONLY the manifest's files (never the raw tarball payload — so a
-        // `full` tarball cannot lay down `src/`). CLAUDE.md is dev-owned: filtered out
-        // if it already exists on disk (write-if-absent + warning).
+        // `full` tarball cannot lay down `src/`). The brain is always written; CLAUDE.md
+        // only when absent; any other kit file the repo already has with its OWN content
+        // is kept, and the kit's copy lands next to it as `<path>.kit-example` (#76).
         const claudeMdExists = existsSync(path.join(root, CLAUDE_MD_FILE));
-        const writes = manifest.files
-            .map((f) => f.path)
-            .filter((p) => !(p === CLAUDE_MD_FILE && claudeMdExists));
+        const { writes, kept } = partitionInitialWrites(root, manifest);
         applyPlan(root, stagedDir, { writes, deletes: [] }, defaultBackupDir(tmpDir));
+        writeKitExamples(root, stagedDir, kept);
         // Write the lockfile = the tarball's embedded manifest (no hash recompute).
         writeInitialLockfile(root, manifestRaw);
+        // The managed `.gitattributes` / `.prettierignore` blocks, the same sync `update` runs. Here,
+        // inside the `try`, because `stagedDir` (their source) is deleted by the `finally`. Without
+        // it the repo's first commit ran its own `prettier --write` over every kit file and drifted
+        // them all from the lockfile it had just written.
+        syncDerivedDotfiles(root, stagedDir, manifest);
+        kitDeps = readKitDeps(stagedDir);
         if (claudeMdExists) {
             console.log('Conservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
                 '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');
         }
+        reportKeptRepoFiles(kept);
     }
     finally {
         process.removeListener('SIGINT', onSignal);
@@ -205,4 +223,7 @@ export async function runAdd(flags = { core: false, full: false }) {
         console.log('Para actualizar: `npx @timekast/factory update` desde la raíz del repo,');
         console.log('o instala el CLI una vez (`npm i -g @timekast/factory`) y corre `factory update`.');
     }
+    // Factory#78 — the packages the kit's files import that this repo does not declare. A
+    // terminal is asked; without one only the exact install command is printed.
+    await offerKitDeps(root, kitDeps);
 }

package/dist/commands/doctor.js

@@ -10,8 +10,8 @@
  *     are local modifications not yet reconciled via `update`.
  *   - A1 WARNING: a literal security notice (design §1 + §11, decision A1) that
  *     `src/` + boilerplate deps are the derived project's responsibility
- *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
- *     update, not yet available).
+ *     post-bootstrap, and that kit fixes for `src/` arrive as retrofit guides
+ *     under `.claude/docs/retrofits/` (shipped by `update`, applied by the agent).
  *   - MISSING INITIAL MIGRATION: a derivative that ships a Drizzle schema and no
  *     generated `.sql`, so the migration step of its deploy — `vercel-build`
  *     (`pnpm build && pnpm db:migrate`) on Vercel, the pre-deploy (`pnpm db:migrate`)
@@ -45,8 +45,10 @@ import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
 import { KIT_RULE_PATH_RE, RULES_DIR, bareImportPaths, resolveImportFrom, } from '../lib/claude-md.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
-import { CLAUDE_MD_FILE } from '../lib/constants.js';
+import { effectiveSettingsHash, KIT_SETTINGS_PATH } from '../lib/claude-settings.js';
+import { BRAIN_PREFIXES, CLAUDE_MD_FILE } from '../lib/constants.js';
 import { MIGRATIONS_DIR, SCHEMA_DIR, needsInitialMigration, readMigrationFacts, } from '../lib/initial-migration.js';
+import { kitExamplePath } from '../lib/initial-writes.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
 import { LAUNCHER_RAIL_TIMEOUT_MS, runLauncherPreflight, } from '../lib/preflight.js';
 import { readNeonRevokePending } from '../lib/provision-state.js';
@@ -76,9 +78,9 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
     'responsabilidad del proyecto derivado a partir de ahí. `factory:update` NO ' +
     'actualiza `src/` ni las dependencias: solo refresca el cerebro (`.claude/`). ' +
     'Un parche de seguridad para `src/` (un CVE en auth, middleware, headers o una ' +
-    'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
-    '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
-    'dependencias al día por tu cuenta mientras tanto.';
+    'dependencia) NO llega por este canal. Las correcciones del kit para `src/` llegan ' +
+    'como guías en `.claude/docs/retrofits/`: viajan con `update` y tu agente las aplica. ' +
+    'Mantén `src/` y tus dependencias al día por tu cuenta.';
 /**
  * The literal notice for a derivative whose schema has no generated migration.
  * Named constant (never an inline string — CODING.md §5) and built from the SAME
@@ -260,6 +262,8 @@ export function computeDoctor(deps = {}) {
         return {
             orphans: [],
             conflicts: [],
+            formatterDrift: [],
+            repoOwned: [],
             unimportedRules: [],
             claudeMdMissing: false,
             a1Warning: A1_WARNING,
@@ -285,16 +289,26 @@ export function computeDoctor(deps = {}) {
     // Pending conflicts: tracked file whose normalized on-disk hash drifted from
     // the recorded hash (a local modification not yet resolved by `update`).
     const conflicts = [];
+    const repoOwned = [];
     for (const entry of lock.files) {
         const abs = path.join(rootDir, entry.path);
         if (!existsSync(abs) || !statSync(abs).isFile())
             continue;
-        const localHash = normalizeThenHash(readFileSync(abs, 'utf8'));
+        const raw = readFileSync(abs, 'utf8');
+        // settings.json: only the kit's keys count (the project's own are not a conflict).
+        const localHash = entry.path === KIT_SETTINGS_PATH
+            ? effectiveSettingsHash(raw, [entry])
+            : normalizeThenHash(raw);
         if (localHash !== entry.hash) {
-            conflicts.push(entry.path);
+            if (existsSync(path.join(rootDir, kitExamplePath(entry.path))))
+                repoOwned.push(entry.path);
+            else
+                conflicts.push(entry.path);
         }
     }
     conflicts.sort();
+    repoOwned.sort();
+    const formatterDrift = conflicts.filter((p) => p !== CLAUDE_MD_FILE && !BRAIN_PREFIXES.some((prefix) => p.startsWith(prefix)));
     // Unimported kit rules: a kit-shipped always-on rule (`.claude/rules/*.md`)
     // that is NOT `@import`ed by CLAUDE.md → it does NOT load at runtime. The check
     // is strict on the `@import` directive (a prose mention does NOT count — a
@@ -322,6 +336,8 @@ export function computeDoctor(deps = {}) {
     return {
         orphans,
         conflicts,
+        formatterDrift,
+        repoOwned,
         unimportedRules,
         claudeMdMissing,
         a1Warning: A1_WARNING,
@@ -373,6 +389,12 @@ function renderDoctor(result, repoVault) {
             for (const p of result.conflicts) {
                 console.log(`  • ${p} — modificado localmente respecto al lockfile`);
             }
+            if (result.formatterDrift.length > 0) {
+                console.log(`  Pista: ${result.formatterDrift.map((p) => `\`${p}\``).join(', ')} ` +
+                    'vive(n) fuera de `.claude/` y `scripts/tools/`. Si solo cambió el formato, ' +
+                    'probablemente lo reformateó el prettier del repo. Guía: ' +
+                    '.claude/docs/retrofits/prettier-drifted-kit-files.md');
+            }
             console.log('  Sugerencia: corre `factory:update --verify` para re-chequear, o `factory:update` para reconciliar.');
         }
         if (result.unimportedRules.length > 0) {
@@ -388,6 +410,13 @@ function renderDoctor(result, repoVault) {
             }
         }
     }
+    // Repo-owned kit files (#76): informative, never a conflict. Shown whatever the rest says.
+    if (result.repoOwned.length > 0) {
+        console.log('\nArchivos propios del repo (el kit dejó su versión al lado, en `.kit-example`):');
+        for (const p of result.repoOwned) {
+            console.log(`  • ${p} — archivo propio del repo; compáralo con \`${kitExamplePath(p)}\``);
+        }
+    }
     // Initial-migration gap (GAP-002): reported, never enforced. It sits outside the
     // orphans/conflicts block because it is about the derivative's `src/`, not about
     // brain drift — a repo with a spotless brain can still be missing its `0000`.

package/dist/commands/env.js

@@ -14,12 +14,13 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from '../lib/cli-error.js';
+import { senderAddressOf } from '../lib/email-from.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, applyWizardAnswersToVault, buildEnvReview, buildEnvReviewFromEnv, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, readVaultLocalEnv, readVaultMain, writeSharedToVault, } from '../lib/env-wizard.js';
+import { applyDefaultOverrides, applyWizardAnswers, applyWizardAnswersToVault, buildEnvReview, buildEnvReviewFromEnv, buildQuestionPlan, checkEnvCompleteness, generateVapidKeys, isPublicEnvKey, isQuestionActive, parseEnvBody, parseEnvExample, provisionEmailDefaults, readVaultLocalEnv, readVaultMain, writeSharedToVault, } from '../lib/env-wizard.js';
 import { defaultRail, railTokenRejectedHint, readVercelToken } from '../lib/provision-preflight.js';
-import { readProvisionState, readVaultLink } from '../lib/provision-state.js';
-import { createVaultClient } from '../lib/vault-api.js';
-import { pushEnvPlan, vercelProjectPath, VercelApiError, } from '../lib/vercel-env.js';
+import { readProvisionState, readProvisionTarget, readVaultLink, } from '../lib/provision-state.js';
+import { VAULT_ENV_DEVELOP, VAULT_ENV_MAIN, VAULT_ROOT_PATH, createVaultClient, } from '../lib/vault-api.js';
+import { listEnvVars, pushEnvPlan, readEnvVarsWithValues, upsertEnvVar, 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 };
@@ -479,16 +480,27 @@ export function runEnvWizardGenVapid(rootDir = process.cwd(), deps = {}) {
     const subjectMissing = !env['VAPID_SUBJECT'];
     if (subjectMissing) {
         const from = env['EMAIL_FROM'];
-        body = setEnvLine(body, 'VAPID_SUBJECT', from ? `mailto:${from}` : 'mailto:admin@example.com');
+        body = setEnvLine(body, 'VAPID_SUBJECT', vapidSubjectFor(from));
     }
     writeFileSync(localPath, body, 'utf8');
     chmodSync(localPath, 0o600); // holds VAPID_PRIVATE_KEY → owner-only.
     console.log('✔ Llaves VAPID generadas y escritas a `.env.local` (la privada queda oculta).');
     console.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY=${publicKey}`);
-    if (subjectMissing && !env['EMAIL_FROM']) {
+    if (subjectMissing && vapidSubjectFor(env['EMAIL_FROM']) === VAPID_SUBJECT_PLACEHOLDER) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }
+/** Placeholder push contact when there is no sender to derive one from. */
+const VAPID_SUBJECT_PLACEHOLDER = 'mailto:admin@example.com';
+/**
+ * The push contact (`VAPID_SUBJECT`) derived from `EMAIL_FROM`. RFC 8292 wants a `mailto:` URL,
+ * so only the bare address goes in: the display-name form (`Name <addr>`) would yield
+ * `mailto:Name <addr>`, which push services reject (Factory#62).
+ */
+export function vapidSubjectFor(emailFrom) {
+    const address = emailFrom ? senderAddressOf(emailFrom) : '';
+    return address.includes('@') ? `mailto:${address}` : VAPID_SUBJECT_PLACEHOLDER;
+}
 /**
  * `--gen-vapid` in a vault repo (VAULT-002): the keypair is upserted (a new pair per run, as on
  * the file path) and `VAPID_SUBJECT` is seeded only when missing, from `main:/EMAIL_FROM`.
@@ -499,11 +511,331 @@ async function genVapidIntoVault(vault) {
     const main = await readVaultMain(vault);
     const subjectMissing = !main['VAPID_SUBJECT'];
     const from = main['EMAIL_FROM'];
-    await writeSharedToVault(vault, { VAPID_SUBJECT: from ? `mailto:${from}` : 'mailto:admin@example.com' }, 'create-if-missing');
+    await writeSharedToVault(vault, { VAPID_SUBJECT: vapidSubjectFor(from) }, 'create-if-missing');
     console.log('✔ Llaves VAPID generadas y escritas en la bóveda (main:/, referenciadas desde develop:/ y local; ' +
         'la privada queda oculta).');
     console.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY=${publicKey}`);
-    if (subjectMissing && !from) {
+    if (subjectMissing && vapidSubjectFor(from) === VAPID_SUBJECT_PLACEHOLDER) {
         console.log('  ℹ️  Revisa VAPID_SUBJECT — puse un placeholder (correo de contacto para push).');
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// `factory env get|set` (PVMCP-003) — read or change ONE public flag of ONE deploy environment.
+//
+// What `/deploy` uses to see whether the questions section is still on in production and, if the
+// developer decides so, turn it off before releasing. Two lists bound it, and both are checked
+// BEFORE any call to the vault, to Vercel or to the rail:
+//   · `get` reads only keys `isPublicEnvKey` accepts — it can never be a secret reader;
+//   · `set` writes only {@link SETTABLE_ENV_KEYS}, and only `true`/`false`. A public key is not
+//     enough for a write: `WEBAUTHN_RP_ID` or `NEXT_PUBLIC_APP_URL` are public and moving them
+//     breaks passkeys or the login, and a free value could carry a `${…}` reference that would
+//     make the vault resolve another secret into a public variable.
+//
+// With the vault it touches ONE location per environment (`main:/` or `develop:/`) through the
+// client's own read/write — never the wizard's shared-value helpers, which write `main:/` and
+// REFERENCE it from `develop:/` (a `set --env develop` must never touch production, and the other
+// way round). Without the vault it goes to Vercel (`main` → production, `develop` → preview);
+// Railway without the vault is refused: its values only arrive through the vault's sync.
+// ─────────────────────────────────────────────────────────────────────────────
+/** The only keys `factory env set` writes (SK.md §7.2: the second allowed writer of these two). */
+export const SETTABLE_ENV_KEYS = ['QUESTIONS_ENABLED', 'MCP_ENABLED'];
+/** The only values `factory env set` writes — literal, case-sensitive. */
+export const SETTABLE_ENV_VALUES = ['true', 'false'];
+/**
+ * Exit codes of `env get|set` — what `/deploy` branches on, never the text. `1` stays the generic
+ * "could not read / could not do it", which is also what an older CLI answers ("Subcomando de env
+ * desconocido"). The others avoid every code the CLI already uses (2 `update --dry-run`, 3 sealed
+ * key of `vault adopt`, 10-12 `provision --resolve-target`, 130 cancelled).
+ */
+export const ENV_GET_SET_EXIT = {
+    ok: 0,
+    error: 1,
+    /** The key does not exist in that environment (the location was read fine). */
+    notFound: 20,
+    /** The key (or, for `set`, the value) is outside what the command accepts. */
+    rejected: 21,
+    /** `get`: in that environment the key is a REFERENCE to another one — not a value of its own. */
+    reference: 22,
+};
+/** A recognized subcommand error with its own exit code. */
+function envGetSetError(message, code) {
+    return new CLIError(message, code);
+}
+export const ENV_GET_SET_USAGE = 'Uso: `factory env get <KEY> --env main|develop` · `factory env set <KEY> <true|false> --env main|develop`.';
+/**
+ * Parse `get <KEY>` / `set <KEY> <VALUE>` + `--env main|develop` (also `--env=…`). A `--help`/`-h`
+ * anywhere short-circuits: nothing else is validated and nothing runs. `--env` has no default —
+ * nobody touches production by omission.
+ *
+ * @throws {CLIError} (exit 1) on a missing/extra argument, an unknown flag or a bad `--env`.
+ */
+export function parseEnvGetSetArgs(argv, sub) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        return { help: true, key: '', value: '', env: 'main' };
+    }
+    const positional = [];
+    let env;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--env') {
+            env = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--env=')) {
+            env = arg.slice('--env='.length);
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw envGetSetError(`Flag desconocido: \`${arg}\`. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+        }
+        positional.push(arg);
+    }
+    const expected = sub === 'get' ? 1 : 2;
+    if (positional.length !== expected) {
+        throw envGetSetError(`\`env ${sub}\` espera ${expected === 1 ? 'una clave' : 'una clave y un valor'}. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+    }
+    if (env === undefined) {
+        throw envGetSetError(`Falta \`--env\` (main o develop): no hay entorno por omisión. ${ENV_GET_SET_USAGE}`, ENV_GET_SET_EXIT.error);
+    }
+    if (env !== 'main' && env !== 'develop') {
+        throw envGetSetError(`\`--env\` acepta \`main\` o \`develop\`, no \`${env}\`.`, ENV_GET_SET_EXIT.error);
+    }
+    return {
+        help: false,
+        key: positional[0],
+        value: sub === 'set' ? positional[1] : '',
+        env,
+    };
+}
+/** `get`'s gate: public keys only. Runs before any call. The rejection names the key, never a value. */
+function assertReadableKey(key) {
+    if (isPublicEnvKey(key))
+        return;
+    throw envGetSetError(`No leo \`${key}\`: \`factory env get\` sólo opera claves públicas (las de public-env-keys.json). ` +
+        'Un secreto se consulta en la bóveda o en el dashboard del despliegue, nunca por este comando.', ENV_GET_SET_EXIT.rejected);
+}
+/** `set`'s gate: its own write list + `true`/`false`. Runs before any call. Never echoes the value. */
+function assertWritable(key, value) {
+    if (!SETTABLE_ENV_KEYS.includes(key)) {
+        throw envGetSetError(`No escribo \`${key}\`: \`factory env set\` sólo cambia ${SETTABLE_ENV_KEYS.map((k) => `\`${k}\``).join(' y ')}. ` +
+            'Otra clave se cambia donde vive (la bóveda, o el dashboard del despliegue sin bóveda).', ENV_GET_SET_EXIT.rejected);
+    }
+    if (!SETTABLE_ENV_VALUES.includes(value)) {
+        throw envGetSetError(`No escribo ese valor en \`${key}\`: \`factory env set\` sólo acepta \`true\` o \`false\` (literal).`, ENV_GET_SET_EXIT.rejected);
+    }
+}
+/** A raw (unexpanded) vault value that is — or contains — a `${…}` reference. */
+const VAULT_REFERENCE_RE = /\$\{[^}]*\}/;
+/** Where a `${env.KEY}` / `${env.folder.KEY}` reference points, for the message; `null` for `${KEY}`. */
+function referencedEnv(raw) {
+    const match = /\$\{([^}]*)\}/.exec(raw);
+    const parts = match?.[1]?.split('.') ?? [];
+    return parts.length >= 2 ? parts[0] : null;
+}
+const VERCEL_TARGET_OF = {
+    main: 'production',
+    develop: 'preview',
+};
+/**
+ * Vault or Vercel — decided the way `env push` and `env wizard` decide it (`readVaultLink`,
+ * fail-closed on a malformed or unreadable state file). Railway without the vault is refused
+ * here, before any call.
+ */
+function routeOf(rootDir) {
+    const link = readVaultLink(rootDir);
+    const target = readProvisionTarget(rootDir);
+    if (link)
+        return { kind: 'vault', link, railway: target === 'railway' };
+    if (target === 'railway') {
+        throw envGetSetError('Este repo despliega en Railway y no tiene bóveda: Railway exige bóveda (sus valores sólo llegan ' +
+            'por el sync de la bóveda), así que no hay a dónde leer ni escribir. Pásalo a la bóveda con ' +
+            '`factory vault adopt` (sin `--apply` sólo enseña el plan). No consulté nada.', ENV_GET_SET_EXIT.error);
+    }
+    return { kind: 'vercel' };
+}
+function vaultLocationOf(env) {
+    return { env: env === 'main' ? VAULT_ENV_MAIN : VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH };
+}
+/** What a vault read asks for: the raw value of ONE location — never expanded, never imported. */
+const RAW_READ = { expandReferences: false, includeImports: false };
+/** Map a Vercel failure to a value-free CLIError (the response body may quote the request). */
+function vercelFailure(error, operation) {
+    if (error instanceof VercelApiError) {
+        if (error.status === 401) {
+            throw new CLIError(`El \`VERCEL_TOKEN\` del rail es inválido o expiró (Vercel respondió 401 al ${operation}).\n` +
+                railTokenRejectedHint('VERCEL_TOKEN'));
+        }
+        throw new CLIError(`Vercel no respondió bien al ${operation} (status ${error.status}).`);
+    }
+    throw error;
+}
+/** The record of `key` for the whole `target` (not pinned to a git branch), if any. */
+function recordFor(records, key, target) {
+    return records.find((r) => r.key === key && !r.gitBranch && (r.target ?? []).includes(target));
+}
+/** Read the project's values from Vercel; a response without the list is an error, never "absent". */
+async function readVercelValues(rootDir, deps) {
+    const { projectId, teamId } = readProjectLink(rootDir);
+    const token = await readVercelToken(deps.rail ?? defaultRail());
+    const values = await readEnvVarsWithValues(projectId, token, teamId, deps.vercel ?? {});
+    if (values === null) {
+        throw new CLIError('Vercel respondió sin la lista de valores del proyecto: no puedo saber si la clave existe. ' +
+            'Vuelve a intentar; no escribí nada.');
+    }
+    return { projectId, teamId, token, values };
+}
+/**
+ * `factory env get <KEY> --env main|develop` — prints ONLY the value on stdout (for
+ * `$(factory env get …)`). Exit codes: {@link ENV_GET_SET_EXIT}.
+ */
+export async function runEnvGet(argv, rootDir = process.cwd(), deps = {}) {
+    const args = parseEnvGetSetArgs(argv, 'get');
+    if (args.help) {
+        console.log(ENV_GET_SET_USAGE);
+        return;
+    }
+    assertReadableKey(args.key);
+    const route = routeOf(rootDir);
+    const writeOut = deps.writeOut ?? ((text) => process.stdout.write(text));
+    if (route.kind === 'vault') {
+        const client = deps.vaultClient ?? createVaultClient();
+        const location = vaultLocationOf(args.env);
+        const raw = (await client.readSecrets(route.link.projectId, location, RAW_READ)).get(args.key);
+        if (raw === undefined) {
+            throw envGetSetError(`\`${args.key}\` no existe en \`${location.env}:/\` de la bóveda.`, ENV_GET_SET_EXIT.notFound);
+        }
+        if (VAULT_REFERENCE_RE.test(raw)) {
+            // Not a value of its own: print the reference as such and say where the value lives.
+            writeOut(`${raw}\n`);
+            const where = referencedEnv(raw);
+            console.error(`ℹ️  En \`${location.env}:/\` \`${args.key}\` es una referencia, no un valor propio` +
+                (where
+                    ? `: el valor vive en \`${where}\` (\`factory env get ${args.key} --env ${where}\`).`
+                    : '.'));
+            process.exitCode = ENV_GET_SET_EXIT.reference;
+            return;
+        }
+        writeOut(`${raw}\n`);
+        return;
+    }
+    const target = VERCEL_TARGET_OF[args.env];
+    let values;
+    try {
+        ({ values } = await readVercelValues(rootDir, deps));
+    }
+    catch (error) {
+        vercelFailure(error, 'leer los valores del proyecto');
+    }
+    const record = recordFor(values, args.key, target);
+    if (!record) {
+        throw envGetSetError(`\`${args.key}\` no existe en Vercel ${target}.`, ENV_GET_SET_EXIT.notFound);
+    }
+    if (record.value === null) {
+        throw new CLIError(`Vercel no devuelve el valor de \`${args.key}\` en ${target} (tipo ${record.type ?? 'desconocido'}).`);
+    }
+    writeOut(`${record.value}\n`);
+}
+/**
+ * `factory env set <KEY> <true|false> --env main|develop` — writes ONE environment, never the
+ * other. With the vault: one `writeSecrets` on `main:/` or `develop:/` (never a reference, never
+ * the wizard's shared-value path). Without it: Vercel, the requested target only.
+ */
+export async function runEnvSet(argv, rootDir = process.cwd(), deps = {}) {
+    const args = parseEnvGetSetArgs(argv, 'set');
+    if (args.help) {
+        console.log(ENV_GET_SET_USAGE);
+        return;
+    }
+    assertWritable(args.key, args.value);
+    const route = routeOf(rootDir);
+    if (route.kind === 'vault') {
+        const client = deps.vaultClient ?? createVaultClient();
+        const location = vaultLocationOf(args.env);
+        const current = (await client.readSecrets(route.link.projectId, location, RAW_READ)).get(args.key);
+        if (current !== undefined && VAULT_REFERENCE_RE.test(current)) {
+            const where = referencedEnv(current);
+            throw new CLIError(`No cambio \`${args.key}\` en \`${location.env}:/\`: ahí es una referencia` +
+                (where ? ` y el valor vive en \`${where}:/\`` : '') +
+                ', y pisarla en silencio separaría los entornos sin que nadie lo decidiera. ' +
+                (where
+                    ? `Para cambiar el valor compartido: \`factory env set ${args.key} <true|false> --env ${where}\` ` +
+                        '(afecta a los dos entornos). '
+                    : '') +
+                'Para un valor propio de este entorno, reemplaza la referencia en el dashboard de la bóveda.');
+        }
+        // One location, one write — the `develop:/` copy is never a reference to `main:/` here.
+        const result = await client.writeSecrets(route.link.projectId, location, { [args.key]: args.value }, 'upsert');
+        const outcome = result.created.includes(args.key)
+            ? 'creada'
+            : result.updated.includes(args.key)
+                ? 'actualizada'
+                : 'sin cambios';
+        const destination = route.railway
+            ? `Railway \`${args.env}\``
+            : `Vercel ${VERCEL_TARGET_OF[args.env]}`;
+        console.log(`✔ \`${args.key}\` en \`${location.env}:/\` de la bóveda: ${outcome}.`);
+        if (outcome !== 'sin cambios') {
+            const syncs = route.railway ? 'railway' : readVaultVercelSyncStatus(rootDir);
+            console.log(syncs === 'pending'
+                ? `ℹ️  Los syncs de la bóveda hacia Vercel están pendientes: el valor no llega a ${destination} ` +
+                    'hasta que existan (`factory provision --resume`).'
+                : `ℹ️  El sync de la bóveda lo lleva a ${destination}; aplica en el SIGUIENTE deploy ` +
+                    '(el que ya corre no cambia).');
+        }
+        return;
+    }
+    // Without the vault — Vercel, the requested target only; the other target keeps its value.
+    const target = VERCEL_TARGET_OF[args.env];
+    try {
+        const { projectId, teamId, token, values } = await readVercelValues(rootDir, deps);
+        const vercelDeps = deps.vercel ?? {};
+        const withValue = recordFor(values, args.key, target);
+        let outcome;
+        if (withValue && withValue.value === args.value) {
+            outcome = 'sin cambios';
+        }
+        else if (!withValue) {
+            // Nothing covers this target (the other one may have its own record — not touched).
+            await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [], vercelDeps);
+            outcome = 'creada';
+        }
+        else {
+            const withId = recordFor((await listEnvVars(projectId, token, teamId, vercelDeps)), args.key, target);
+            if (!withId) {
+                throw new CLIError(`Vercel listó \`${args.key}\` en ${target} con valor pero no con id: no escribo a ciegas. Vuelve a intentar.`);
+            }
+            const others = (withId.target ?? []).filter((t) => t !== target);
+            if (others.length === 0) {
+                // A record of this target alone: update it in place.
+                await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [withId], vercelDeps);
+            }
+            else {
+                // A COMBINED record (e.g. production + preview). Re-pointing it whole would drag the other
+                // target along, so it is SPLIT: the record keeps its value for the other target(s), and the
+                // requested target gets a record of its own. Needs the current value to keep it.
+                if (withValue.value === null) {
+                    throw new CLIError(`\`${args.key}\` vive en un solo registro para ${(withId.target ?? []).join(' y ')} y Vercel no ` +
+                        'devuelve su valor, así que no puedo separarlo sin perder el de los otros entornos. Sepáralo en ' +
+                        'el dashboard de Vercel (un registro por entorno) y repite. No escribí nada.');
+                }
+                await upsertEnvVar(projectId, token, teamId, { key: args.key, value: withValue.value, target: others }, [withId], vercelDeps);
+                try {
+                    await upsertEnvVar(projectId, token, teamId, { key: args.key, value: args.value, target: [target] }, [], vercelDeps);
+                }
+                catch (error) {
+                    throw new CLIError(`Separé el registro combinado de \`${args.key}\` (${others.join(', ')} conserva su valor), pero no ` +
+                        `pude crear el de ${target}: ${target} quedó SIN \`${args.key}\`. Repite el mismo comando para crearlo.` +
+                        (error instanceof VercelApiError ? ` (Vercel status ${error.status}.)` : ''));
+                }
+            }
+            outcome = 'actualizada';
+        }
+        console.log(`✔ \`${args.key}\` en Vercel ${target}: ${outcome}.`);
+        if (outcome !== 'sin cambios')
+            console.log(REDEPLOY_NOTICE);
+    }
+    catch (error) {
+        vercelFailure(error, `escribir \`${args.key}\` en ${target}`);
+    }
+}