@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/vercel-env.js

@@ -15,6 +15,10 @@
  *   - Run `vercel link` / `vercel pull` — NEVER. It writes `.vercel/project.json`
  *     itself (`{ projectId, orgId, teamId }`) so downstream steps never depend on
  *     the Vercel CLI rewriting `.env.local` (SK.md §7.1 — overwrite locks devs out).
+ *   - Write the env of a project that lives in the vault (SYNC-001). There the vault's secret
+ *     syncs are the single writer of each target; provision gates every direct writer on the
+ *     `vault` block, and `VercelApiDeps.vaultOwned` refuses any env write that slips past it.
+ *     `listEnvVarNames` (names + targets, never values) is what such a repo may read.
  *
  * Per-target push (issue §4): production-only secrets push to `["production"]`,
  * preview/develop ones to `["preview"]`, and shared values to both. `AUTH_SECRET`
@@ -22,7 +26,7 @@
  * prod and preview must never share a secret. The push is idempotent: a var that
  * already exists for a target is PATCHed (not re-POSTed → no `ENV_ALREADY_EXISTS`).
  *
- * No-echo discipline (issue §4 + `factory secrets` pattern): a secret VALUE never
+ * No-echo discipline (issue §4 + `fx-secrets-vault`): a secret VALUE never
  * reaches stdout. The public surface returns only KEY NAMES + targets; values
  * live solely inside the request bodies handed to `fetchImpl`.
  *
@@ -42,6 +46,17 @@ const VERCEL_API_TIMEOUT_MS = 30_000;
 export const VERCEL_DIR = '.vercel';
 /** Filename of the Vercel project-link document inside {@link VERCEL_DIR}. */
 export const VERCEL_PROJECT_FILE = 'project.json';
+/** An env-var path of the Vercel API (`/v9|v10/projects/{id}/env[/{envId}]`). */
+const VERCEL_ENV_PATH_RE = /^\/v\d+\/projects\/[^/]+\/env(\/|$)/;
+/** Raised when a direct env write is attempted on a project whose env the vault owns (SYNC-001). */
+export class VercelEnvOwnedByVaultError extends CLIError {
+    constructor(method) {
+        super(`No escribo variables de entorno directo en Vercel (${method}): este repo vive en la bóveda y ` +
+            'su sync es el único escritor del proyecto (fx-secrets-vault §7). Cambia el valor en la bóveda.');
+        this.name = 'VercelEnvOwnedByVaultError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** A non-2xx response from the Vercel REST API. Carries the HTTP status for mapping. */
 export class VercelApiError extends Error {
     status;
@@ -100,6 +115,9 @@ export function vercelUrl(pathname, teamId, extraQuery = {}) {
  * 403 on a team-owned project. Surfaces a typed {@link VercelApiError} on non-2xx.
  */
 async function vercelApi(method, pathname, token, teamId, deps, body, extraQuery) {
+    if (deps.vaultOwned && method !== 'GET' && VERCEL_ENV_PATH_RE.test(pathname)) {
+        throw new VercelEnvOwnedByVaultError(method);
+    }
     const fetchImpl = deps.fetchImpl ?? fetch;
     const url = vercelUrl(pathname, teamId, extraQuery);
     const init = {
@@ -202,6 +220,22 @@ export async function getLinkedRepoId(projectId, token, teamId, deps = {}) {
     const repoId = data.link?.repoId;
     return typeof repoId === 'number' ? repoId : null;
 }
+/**
+ * Whether the project already has at least one deployment for `target` (`GET /v6/deployments`
+ * filtered by `projectId` + `target`, `limit=1` — never an unfiltered listing). The first-
+ * deployment trigger asks this per target before firing, so a re-entry never fires production
+ * again on a project that already deploys (a push, a previous run, a manual redeploy).
+ *
+ * @throws {VercelApiError} on any non-2xx (the caller treats it as NON-FATAL, like the trigger).
+ */
+export async function hasDeployment(projectId, target, token, teamId, deps = {}) {
+    const data = (await vercelApi('GET', '/v6/deployments', token, teamId, deps, undefined, {
+        projectId,
+        target,
+        limit: '1',
+    }));
+    return Array.isArray(data.deployments) && data.deployments.length > 0;
+}
 /**
  * Trigger the FIRST git deployment for ONE branch (`POST /v13/deployments`).
  * provision links the repo to the Vercel project AFTER `factory new`/provision
@@ -382,8 +416,13 @@ export async function listVercelProjects(token, teamId, deps = {}) {
             query.until = String(until);
         const data = (await vercelApi('GET', '/v9/projects', token, teamId, deps, undefined, query));
         for (const p of data.projects ?? []) {
-            if (p.id && p.name)
-                collected.push({ id: p.id, name: p.name });
+            if (!p.id || !p.name)
+                continue;
+            const link = p.link;
+            const repo = link?.type === 'github' && typeof link.org === 'string' && typeof link.repo === 'string'
+                ? `${link.org}/${link.repo}`
+                : undefined;
+            collected.push({ id: p.id, name: p.name, ...(repo ? { repo } : {}) });
         }
         const next = data.pagination?.next;
         if (next === undefined || next === null || next === until)
@@ -392,6 +431,23 @@ export async function listVercelProjects(token, teamId, deps = {}) {
     }
     return collected;
 }
+/**
+ * The team's projects CONNECTED to `repo` (`owner/name`): the WHOLE paginated listing
+ * ({@link listVercelProjects}), matched on the Git link's `owner/repo`, case-insensitive (GitHub
+ * slugs are). A project that merely has the repo's NAME but is linked to another repo (or to
+ * none) does not count. STRICTLY read-only.
+ *
+ * The one "projects by connected repo" reading of the kit: `locateVercelProject` (ADOPT-001) and
+ * EPIC-06's destination discovery (RWAY-003) both go through it. What zero or several mean is
+ * the caller's question, not this one's.
+ *
+ * @throws {VercelApiError} on any non-2xx.
+ */
+export async function listVercelProjectsConnectedTo(repo, token, teamId, deps = {}) {
+    const wanted = repo.trim().toLowerCase();
+    const projects = await listVercelProjects(token, teamId, deps);
+    return projects.filter((p) => p.repo?.toLowerCase() === wanted);
+}
 /**
  * Apex of the hosts Vercel mints on its own (`{project}.vercel.app`). Nobody
  * created these and nobody can delete them, so they are the LAST choice when
@@ -412,6 +468,20 @@ export async function listProjectDomains(projectId, token, teamId, deps = {}) {
         .filter((d) => Boolean(d.name))
         .map((d) => ({ name: d.name, apexName: d.apexName ?? '', gitBranch: d.gitBranch ?? null }));
 }
+/** The git branch whose domain is the preview host of a deploy. */
+export const PREVIEW_HOST_BRANCH = 'develop';
+/**
+ * ADOPT-009 — the candidate hosts of a project from {@link listProjectDomains}: production = every
+ * domain without `gitBranch`; preview = every domain pinned to `develop`. Pure: it never picks one
+ * among several, and never invents one — the caller asks whoever runs when a list is not exactly one.
+ */
+export function deployHostCandidates(domains) {
+    const unique = (names) => [...new Set(names)];
+    return {
+        production: unique(domains.filter((d) => !d.gitBranch).map((d) => d.name)),
+        preview: unique(domains.filter((d) => d.gitBranch === PREVIEW_HOST_BRANCH).map((d) => d.name)),
+    };
+}
 /**
  * List the project's existing env vars (issue §8 idempotency: we PATCH a var that
  * already covers a target instead of POSTing a duplicate). `decrypt=false` keeps
@@ -422,6 +492,138 @@ export async function listEnvVars(projectId, token, teamId, deps = {}) {
     const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}/env`, token, teamId, deps));
     return data.envs ?? [];
 }
+/**
+ * The project's env vars as NAMES + targets only (SYNC-001). Vercel returns the value of a
+ * non-sensitive var in the listing, so {@link listEnvVars}' objects carry it at runtime even
+ * though the type hides it; this strips it at the boundary, so the destination checks of
+ * provision (empty destination, first-sync delivery, `/ci` leak) can never print one.
+ */
+export async function listEnvVarNames(projectId, token, teamId, deps = {}) {
+    return (await listEnvVars(projectId, token, teamId, deps)).flatMap((env) => typeof env.key === 'string'
+        ? [{ key: env.key, target: Array.isArray(env.target) ? [...env.target] : [] }]
+        : []);
+}
+/** Vercel types whose value the API never returns. */
+const UNREADABLE_ENV_TYPES = new Set(['sensitive', 'secret']);
+/**
+ * Rebuild a Vercel failure WITHOUT its response body: a body could quote what was asked for,
+ * and this path handles values. Only the status and the operation name survive.
+ */
+function valueSafeError(error, operation) {
+    const status = error instanceof VercelApiError ? ` (status ${error.status})` : '';
+    return new CLIError(`Vercel no respondió bien al ${operation}${status}.`);
+}
+/**
+ * The project's env vars WITH their values (`GET /v9/projects/{id}/env?decrypt=true`), for the
+ * adoption's inventory. An `encrypted` var the listing returns still encrypted is re-read by id
+ * (`GET /v1/projects/{id}/env/{envId}`); whatever stays unreadable comes back with
+ * `value: null`. {@link listEnvVars} is untouched — its consumers keep a value-free listing.
+ *
+ * A response WITHOUT the `envs` list reads as `[]` here; {@link readEnvVarsWithValues} tells the
+ * two apart.
+ *
+ * @throws {CLIError} on any Vercel failure, rebuilt without the response body.
+ */
+export async function listEnvVarsWithValues(projectId, token, teamId, deps = {}) {
+    return (await readEnvVarsWithValues(projectId, token, teamId, deps)) ?? [];
+}
+/**
+ * ADOPT-009 — {@link listEnvVarsWithValues}, but a response that does NOT carry the `envs` list
+ * comes back as `null` instead of `[]`. `vault adopt` decides "the deploy is connected and EMPTY"
+ * only on an explicit empty list: a response without it is never proof of emptiness.
+ *
+ * @throws {CLIError} on any Vercel failure, rebuilt without the response body.
+ */
+export async function readEnvVarsWithValues(projectId, token, teamId, deps = {}) {
+    const operation = 'leer las variables del proyecto';
+    let data;
+    try {
+        data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}/env`, token, teamId, deps, undefined, { decrypt: 'true' }));
+    }
+    catch (error) {
+        throw valueSafeError(error, operation);
+    }
+    if (!Array.isArray(data.envs))
+        return null;
+    const out = [];
+    for (const env of data.envs) {
+        if (typeof env.key !== 'string')
+            continue;
+        const type = typeof env.type === 'string' ? env.type : null;
+        const target = Array.isArray(env.target) ? [...env.target] : env.target ? [env.target] : [];
+        let value = type !== null && UNREADABLE_ENV_TYPES.has(type)
+            ? null
+            : typeof env.value === 'string'
+                ? env.value
+                : null;
+        if (value !== null && type === 'encrypted' && env.decrypted === false)
+            value = null;
+        if (value === null && type === 'encrypted' && typeof env.id === 'string') {
+            try {
+                const one = (await vercelApi('GET', `/v1/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(env.id)}`, token, teamId, deps));
+                value = typeof one.value === 'string' && one.decrypted !== false ? one.value : null;
+            }
+            catch (error) {
+                throw valueSafeError(error, `leer la variable \`${env.key}\``);
+            }
+        }
+        out.push({
+            key: env.key,
+            target,
+            gitBranch: typeof env.gitBranch === 'string' && env.gitBranch !== '' ? env.gitBranch : null,
+            type,
+            value,
+        });
+    }
+    return out;
+}
+/**
+ * ADOPT-001 — locate the Vercel project of a repo, in this order:
+ *
+ *   1. the id the repo already RECORDED (`.timekast/provision.json` — the `vault` link, the
+ *      step state or the adopted shape; the caller reads it). A recorded id Vercel does not know
+ *      stops: a stale record is not silently replaced by a search.
+ *   2. the project CONNECTED to the repo: the WHOLE paginated listing, matched on the Git link's
+ *      `owner/repo`, case-insensitive (GitHub slugs are).
+ *
+ * Never `.vercel/project.json`: it is gitignored, so its absence says nothing about a deploy.
+ * The caller decides what zero or several mean (`vault adopt`: zero with another deploy is fine,
+ * several stop). Reused by `doctor`/`status` (ADOPT-004) and EPIC-06's destination choice.
+ *
+ * @throws {CLIError} when the recorded id does not exist, or Vercel fails.
+ */
+export async function locateVercelProject(input) {
+    const deps = input.deps ?? {};
+    if (input.recordedId) {
+        let project;
+        try {
+            project = await getVercelProjectByName(input.recordedId, input.token, input.teamId, deps);
+        }
+        catch (error) {
+            throw valueSafeError(error, 'leer el proyecto registrado');
+        }
+        if (!project) {
+            throw new CLIError(`El proyecto de Vercel que registra \`.timekast/provision.json\` (\`${input.recordedId}\`) no ` +
+                'existe en el team. No busco otro por mi cuenta: corrige el registro y vuelve a correr.');
+        }
+        return { kind: 'found', project, source: 'recorded' };
+    }
+    if (!input.repo)
+        return { kind: 'none' };
+    let candidates;
+    try {
+        candidates = await listVercelProjectsConnectedTo(input.repo, input.token, input.teamId, deps);
+    }
+    catch (error) {
+        throw valueSafeError(error, 'listar los proyectos del team');
+    }
+    if (candidates.length === 0)
+        return { kind: 'none' };
+    if (candidates.length === 1) {
+        return { kind: 'found', project: candidates[0], source: 'connected' };
+    }
+    return { kind: 'ambiguous', candidates };
+}
 /**
  * Idempotently set ONE env var for its targets (issue §4 + §8). If existing vars
  * already cover any of the requested targets, they are RECONCILED into a single
@@ -560,53 +762,71 @@ export function writeVercelProjectJson(rootDir, link, options = {}) {
             `${error?.message ?? 'error desconocido'}.`);
     }
 }
+/**
+ * The `WEBAUTHN_RELATED_ORIGINS` value for a set of hosts: comma-separated ORIGINS with scheme
+ * (the format `src/lib/auth/webauthn.ts#getRelatedOrigins` parses — a bare host would be dropped
+ * there with a warning). Empty/duplicate hosts are skipped; order is kept.
+ */
+export function relatedOriginsFor(hosts) {
+    const origins = [];
+    for (const host of hosts) {
+        const trimmed = host.trim();
+        if (trimmed === '')
+            continue;
+        const origin = `https://${trimmed}`;
+        if (!origins.includes(origin))
+            origins.push(origin);
+    }
+    return origins.join(',');
+}
 /**
  * Build the per-target env-var plan for a provisioned stack (issue §4).
  *
  * Production-bound values (the `main` DATABASE_URL, the prod `AUTH_SECRET`,
  * `NEXT_PUBLIC_APP_ENV=production`) → `["production"]`. Preview/develop values
  * (the `develop` DATABASE_URL, the preview `AUTH_SECRET`, `NEXT_PUBLIC_APP_ENV=
- * preview`) → `["preview"]`. Shared, non-secret values (e.g. `EMAIL_FROM`,
- * `RESEND_API_KEY`) apply to both. Each `AUTH_SECRET` is minted independently so
- * the two environments never share a secret.
- *
- * `shared` values arrive already split on the first `=` (the caller reuses the
- * `env-merge.ts` first-`=` rule); this builder does no parsing of its own.
+ * preview`) → `["preview"]`. Shared, non-environment-specific values (e.g.
+ * `RESEND_API_KEY`) apply to both. Each `AUTH_SECRET` is DISTINCT per environment, with or
+ * without a vault (in a vault repo they are `main:/AUTH_SECRET` and `develop:/AUTH_SECRET`).
+ *
+ * WebAuthn (VAULT-002, ADR-005): ONE rpID for the whole project — the PRODUCTION host — in
+ * both targets, and the develop origin as a Related Origin (`WEBAUTHN_RELATED_ORIGINS`), so a
+ * preview deployment runs its ceremonies for the production rpID and the browser authorizes it
+ * through `https://<prod>/.well-known/webauthn`. A per-target rpID made a passkey enrolled on
+ * one host die on the other and forced the rpID to move at go-live.
+ *
+ * `shared` arrives as a ready key→value map (provision's `readSharedVercelEnv`, which
+ * never includes a rail admin token such as `CLOUDFLARE_API_TOKEN` — a rail token
+ * never leaves toward a deploy); this builder does no parsing of its own.
  */
 export function buildEnvPlan(input) {
     const plan = [
         // Database — distinct connection string per environment.
         { key: 'DATABASE_URL', value: input.mainDatabaseUrl, target: ['production'] },
         { key: 'DATABASE_URL', value: input.developDatabaseUrl, target: ['preview'] },
-        // Auth secret — distinct value per environment (never shared).
+        // Auth secret — per environment record, distinct values (a preview never signs prod sessions).
         { key: 'AUTH_SECRET', value: input.authSecretProd, target: ['production'] },
         { key: 'AUTH_SECRET', value: input.authSecretPreview, target: ['preview'] },
-        // MFA encryption key — distinct per env (base64url 32 bytes). Without it a
-        // derivative with MFA enabled boots broken; minted independently so prod and
-        // preview never share it (P-1).
+        // MFA encryption key (base64url 32 bytes). Without it a derivative with MFA enabled
+        // boots broken (P-1).
         { key: 'MFA_ENCRYPTION_KEY', value: input.mfaEncryptionKeyProd, target: ['production'] },
         { key: 'MFA_ENCRYPTION_KEY', value: input.mfaEncryptionKeyPreview, target: ['preview'] },
-        // WebAuthn relying-party id — the EXACT host per env (a passkey dies if the
-        // rpID changes), so passkeys work without manual Vercel setup (P-1 / PASSKEY-002 §8).
-        { key: 'WEBAUTHN_RP_ID', value: input.webauthnRpIdProd, target: ['production'] },
-        { key: 'WEBAUTHN_RP_ID', value: input.webauthnRpIdPreview, target: ['preview'] },
+        // WebAuthn — ONE rpID (the production host) for both targets + the develop origin as a
+        // related origin, so passkeys work without manual Vercel setup (P-1 / PASSKEY-002 §8).
+        { key: 'WEBAUTHN_RP_ID', value: input.prodHost, target: ['production', 'preview'] },
+        {
+            key: 'WEBAUTHN_RELATED_ORIGINS',
+            value: relatedOriginsFor([input.previewHost]),
+            target: ['production', 'preview'],
+        },
         // Deployment identity — drives the env-aware PWA manifest (see .env.example).
         { key: 'NEXT_PUBLIC_APP_ENV', value: 'production', target: ['production'] },
         { key: 'NEXT_PUBLIC_APP_ENV', value: 'preview', target: ['preview'] },
-        // App origin — the EXACT per-env URL (same host as WEBAUTHN_RP_ID), so links,
-        // OAuth callbacks and the PWA manifest resolve to the real domain instead of the
-        // `localhost:3000` default of `.env.local`. Per-env (PROVISION_OWNED) → `env:push`
-        // never overwrites it with a single shared value (P-1 parity with the other hosts).
-        {
-            key: 'NEXT_PUBLIC_APP_URL',
-            value: `https://${input.webauthnRpIdProd}`,
-            target: ['production'],
-        },
-        {
-            key: 'NEXT_PUBLIC_APP_URL',
-            value: `https://${input.webauthnRpIdPreview}`,
-            target: ['preview'],
-        },
+        // App origin — the EXACT per-env URL, so links, OAuth callbacks and the PWA manifest
+        // resolve to the real domain instead of the `localhost:3000` default of `.env.local`.
+        // Per-env (PROVISION_OWNED) → `env:push` never overwrites it with a single shared value.
+        { key: 'NEXT_PUBLIC_APP_URL', value: `https://${input.prodHost}`, target: ['production'] },
+        { key: 'NEXT_PUBLIC_APP_URL', value: `https://${input.previewHost}`, target: ['preview'] },
     ];
     for (const [key, value] of Object.entries(input.shared ?? {})) {
         if (!value)

package/dist/lib/wrapper-wiring.js

@@ -0,0 +1,160 @@
+/**
+ * VAULT-004 — wire the vault wrapper into a derivative's `package.json` scripts.
+ *
+ * WHY THIS EXISTS. A derivative's `package.json` is born frozen (BR-FACTORY-006) and
+ * `factory update` does not rewrite the boilerplate scripts (`dev`, `build`, `db:*`, …). A repo
+ * born before the wrapper that activates the vault with `provision` would have the vault project
+ * and scripts that never read it: `pnpm dev` would start with no secrets. So `provision`, when it
+ * activates the vault, rewrites THOSE scripts — the same precedent as `healVercelBuildOrder`:
+ *
+ *   · a value the kit shipped without the wrapper (the current inner command, or a registered
+ *     historic one) → rewritten to the wrapped value;
+ *   · already wrapped → nothing;
+ *   · anything else → the team's own script (`fx-extension-points`: "wrap from outside" is a
+ *     legitimate extension point) → left intact and NAMED, because it runs without secrets until
+ *     the team adapts it;
+ *   · absent → nothing is inserted: a repo without `db:seed` is a repo that should not get one.
+ *
+ * The comparison is `classifyKitScript` — the one every heal of a kit-owned script uses — and the
+ * values come from `VAULT_WRAPPED_SCRIPTS` (`constants.ts`), the single source.
+ *
+ * The change is SHOWN before it is written (`fx-secrets-vault §8` step 5): the writer returns the
+ * line diff of the file, and the caller prints it before (or instead of, under `--dry-run`)
+ * writing. It is the REAL diff: computed between the bytes on disk and the bytes that would be
+ * written.
+ *
+ * Also consumed by the adoption of an existing repo (ADOPT-001).
+ */
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { VAULT_WRAPPED_SCRIPTS, WITH_VAULT_SCRIPT_CMD } from './constants.js';
+import { classifyKitScript, detectIndent, parsePackageJson } from './package-json.js';
+/**
+ * Decide, per wrapped kit script, what the wiring does (see the module header). Pure: the input
+ * is not mutated and nothing is read or written.
+ */
+export function planWrapperWiring(scripts) {
+    const next = { ...(scripts ?? {}) };
+    const plan = {
+        rewritten: [],
+        alreadyWrapped: [],
+        customized: [],
+        absent: [],
+        scripts: next,
+    };
+    for (const [name, spec] of Object.entries(VAULT_WRAPPED_SCRIPTS)) {
+        const existing = next[name];
+        // A value the dev ALREADY put behind the wrapper (with a step of their own after it) goes
+        // through the vault: it is wrapped, not customized — naming it as "runs without secrets"
+        // would be false.
+        if (existing !== undefined && existing.startsWith(`${WITH_VAULT_SCRIPT_CMD} `)) {
+            plan.alreadyWrapped.push(name);
+            continue;
+        }
+        const kind = classifyKitScript(existing, spec.cmd, spec.unwrapped);
+        if (kind === 'absent')
+            plan.absent.push(name);
+        else if (kind === 'current')
+            plan.alreadyWrapped.push(name);
+        else if (kind === 'shipped') {
+            next[name] = spec.cmd;
+            plan.rewritten.push(name);
+        }
+        else
+            plan.customized.push({ name, value: existing });
+    }
+    return plan;
+}
+/**
+ * Line diff between two texts, as `-`/`+` lines (unchanged lines omitted). An LCS over lines —
+ * a `package.json` is a few hundred lines at most — so the output is the real difference even
+ * when the re-serialization moved something the wiring did not intend to.
+ */
+export function diffLines(before, after) {
+    if (before === after)
+        return [];
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = length of the LCS of a[i..] and b[j..].
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            out.push(`- ${a[i]}`);
+            i += 1;
+        }
+        else {
+            out.push(`+ ${b[j]}`);
+            j += 1;
+        }
+    }
+    while (i < n)
+        out.push(`- ${a[i++]}`);
+    while (j < m)
+        out.push(`+ ${b[j++]}`);
+    return out;
+}
+/**
+ * Write `content` to `file` atomically: a sibling temp file, then `rename(2)` — a process killed
+ * mid-write leaves the old file or the new one, never half of each.
+ */
+function writeAtomic(file, content) {
+    const tmp = `${file}.tk-wiring-${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, content, 'utf8');
+        renameSync(tmp, file);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Wire the wrapper into `<rootDir>/package.json` (see the module header). Reads, plans, builds the
+ * new document with the file's own indentation (only the values of the affected scripts change),
+ * and returns the diff. Writes ONLY when the diff is not empty and `dryRun` is off — so a second
+ * run on a wired repo writes nothing (idempotent).
+ *
+ * @throws {CLIError} when `package.json` is not valid JSON (`parsePackageJson`).
+ */
+export function wireVaultWrapper(rootDir, opts = {}) {
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return {
+            rewritten: [],
+            alreadyWrapped: [],
+            customized: [],
+            absent: Object.keys(VAULT_WRAPPED_SCRIPTS),
+            diff: [],
+            written: false,
+            hasPackageJson: false,
+        };
+    }
+    const raw = readFileSync(pkgPath, 'utf8');
+    const pkg = parsePackageJson(raw);
+    const plan = planWrapperWiring(pkg.scripts);
+    const { scripts, ...summary } = plan;
+    if (plan.rewritten.length === 0) {
+        return { ...summary, diff: [], written: false, hasPackageJson: true };
+    }
+    pkg.scripts = scripts;
+    const next = `${JSON.stringify(pkg, null, detectIndent(raw))}\n`;
+    const diff = diffLines(raw, next);
+    const write = diff.length > 0 && !opts.dryRun;
+    if (write)
+        writeAtomic(pkgPath, next);
+    return { ...summary, diff, written: write, hasPackageJson: true };
+}

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

@@ -6,13 +6,16 @@
  * 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.
+ *
+ * In a repo linked to the vault (VAULT-002) the answers go to the vault — one copy in `main:/`,
+ * referenced from `develop:/` and `local` — and there is no `.env.local` nor `env:push` offer.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import prompts from 'prompts';
-import { runEnvPush } from '../commands/env.js';
+import { runEnvPush, VAULT_DEPLOYS_NOTICE, wizardVaultTarget } from '../commands/env.js';
 import { CLIError } from '../lib/cli-error.js';
-import { applyWizardAnswers, buildQuestionPlan, isQuestionActive, parseEnvExample, } from '../lib/env-wizard.js';
+import { applyWizardAnswers, applyWizardAnswersToVault, 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;
@@ -56,6 +59,9 @@ export async function envWizardFlow(rootDir = process.cwd(), deps = {}) {
         throw new CLIError('No encontré `.env.example` en este proyecto. El wizard deriva las preguntas de ahí.');
     }
     const plan = buildQuestionPlan(parseEnvExample(readFileSync(examplePath, 'utf8')));
+    // Decided up front (fail-closed on an unreadable state), so the cancel message is right too.
+    const vault = wizardVaultTarget(rootDir, { vaultClient: deps.vaultClient });
+    const destination = vault ? 'la bóveda' : '`.env.local`';
     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 = {};
@@ -69,11 +75,19 @@ export async function envWizardFlow(rootDir = process.cwd(), deps = {}) {
         }
         const value = await askOne(q);
         if (value === undefined) {
-            console.log('\nCancelado. No se escribió nada en `.env.local`.');
+            console.log(`\nCancelado. No se escribió nada en ${destination}.`);
             return;
         }
         answers[q.key] = value;
     }
+    if (vault) {
+        const { written, empty } = await applyWizardAnswersToVault(vault, answers);
+        console.log(`\n✔ Escribí ${written.length} variable(s) en la bóveda (main:/, referenciadas desde develop:/ y local).`);
+        if (empty.length > 0)
+            console.log(`  (sin valor, no se guardan: ${empty.join(', ')})`);
+        console.log(VAULT_DEPLOYS_NOTICE);
+        return;
+    }
     const written = applyWizardAnswers(rootDir, answers);
     console.log(`\n✔ Escribí ${written.length} variable(s) en \`.env.local\`.`);
     const { doPush } = await prompts({

package/dist/tui/menu.js

@@ -2,9 +2,10 @@
  * `factory` (no args) — interactive TUI menu (LTUI-001).
  *
  * Replaces the old static HELP print on the no-args path with a cross-platform
- * (pure TypeScript) menu: Nuevo / Actualizar / Aprovisionar / Secrets. The menu
- * is a thin dispatcher — each option delegates to the existing command function
- * (`runNew` / `runUpdate` / `secretsCommand`), which keep their own contracts.
+ * (pure TypeScript) menu: Nuevo / Actualizar / Aprovisionar / Variables de entorno.
+ * The menu is a thin dispatcher — each option delegates to the existing command
+ * function (`runNew` / `runUpdate` / `provisionFlow` / `envWizardFlow`), which keep
+ * their own contracts.
  * No OS branching: one binary serves Mac, Windows and Linux.
  *
  * Edge cases this module owns:
@@ -21,7 +22,6 @@
  */
 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';
@@ -36,7 +36,6 @@ async function promptAction() {
             { title: 'Actualizar proyecto', value: 'update' },
             { title: 'Aprovisionar (ephemeral)', value: 'provision' },
             { title: 'Configurar variables de entorno', value: 'env' },
-            { title: 'Secrets', value: 'secrets' },
         ],
         initial: 0,
     }, { onCancel: () => true } // let the value come back undefined; we exit cleanly below
@@ -82,19 +81,6 @@ async function dispatchUpdate(deps) {
 async function dispatchProvision(deps) {
     await deps.provision();
 }
-/** Sub-flow: pick a secrets master file, then delegate to `secretsCommand`. */
-async function dispatchSecrets(deps) {
-    const { file } = await prompts({
-        type: 'text',
-        name: 'file',
-        message: 'Ruta del archivo master de secrets (KEY=value):',
-    }, { onCancel: () => true });
-    if (!file || typeof file !== 'string' || file.trim() === '') {
-        // Cancel or empty — back out cleanly.
-        return;
-    }
-    await deps.secrets(file.trim());
-}
 /**
  * Run the interactive top-level menu. Called from `index.ts` when `factory` is
  * invoked with no command (and not `-h`/`--help`).
@@ -107,7 +93,6 @@ export async function runTuiMenu(deps = {}) {
     const printHelp = deps.printHelp ?? (() => { });
     const newProject = deps.newProject ?? runNew;
     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
@@ -134,8 +119,5 @@ export async function runTuiMenu(deps = {}) {
         case 'env':
             await envWizard();
             return;
-        case 'secrets':
-            await dispatchSecrets({ secrets });
-            return;
     }
 }