@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/vault-deploys.js

@@ -0,0 +1,898 @@
+/**
+ * A repo with several deploys (MDEP-001) — the same code deployed once per client, each deploy with
+ * its OWN vault project seeded from a shared TEMPLATE project. Contract: `fx-secrets-vault §6`
+ * ("Un repo con varios despliegues"). Decision record: ADR-007.
+ *
+ *   - The REGISTRY (`.timekast/deploys.json`, committed, no credentials) declares each deploy: its
+ *     slug, name, domains and bucket per environment, the NAMES of the keys that are its own, and
+ *     the ids of its destinations. Read as JSON and validated field by field: an unknown field or an
+ *     unreadable file aborts naming the file — never read "de menos".
+ *   - The PRINCIPAL project (the `vault` block of `.timekast/provision.json`) does not change: it
+ *     keeps the local wrapper, `invite-admin`, `backlog` and CI. The template and the N clients are
+ *     separate projects: `<repo>-defaults` (or the name the registry declares) and `<repo>-<slug>`.
+ *   - PRECEDENCE, per key and environment: a key declared in `ownKeys` with a stored non-empty value
+ *     in the client → kept; else what the registry derives (origin, rpID, bucket…); else the
+ *     template. What is NOT declared own is re-seeded from the template on every run, so a rotation
+ *     there reaches every client. `''` counts as absent.
+ *   - ADOPTION BY ID: an existing client project (or the template) is used only when its id is
+ *     annotated in the registry; a name alone could be another client's project. The apply writes
+ *     back the id of each project it creates.
+ *   - ALL-OR-NOTHING: every client is computed and checked BEFORE the first write (project creation
+ *     included). A value of one client found in another — or in the principal — aborts with zero
+ *     writes.
+ *   - NO DELETIONS: the plan never announces "quita" and the apply only creates or changes; keys the
+ *     client holds beyond the computed set are reported by NAME, informatively.
+ *
+ * Every read and write goes through the vault client (`vault-api.ts`), so its write guard applies.
+ * The credential is the PERSON's session only: {@link VaultClient.whoAmI} runs first.
+ *
+ * 🔴 NO-ECHO: plans, errors and every exported type carry key NAMES, environments and slugs —
+ * never a value. The values live only inside the closure {@link planDeploys} returns.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { RAIL_TIMEKAST } from './rail.js';
+import { isRailKey } from './vault-adopt.js';
+import { assertWriteAllowed, normalizeLocation, VAULT_CI_PATH, VAULT_ENV_DEVELOP, VAULT_ENV_MAIN, VAULT_ROOT_PATH, VaultApiError, } from './vault-api.js';
+import { relatedOriginsFor } from './vercel-env.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Where the registry lives (repo-relative). Committed: ids and names, never a credential. */
+export const DEPLOYS_REGISTRY_FILE = '.timekast/deploys.json';
+/** A deploy slug: lowercase letters, digits and hyphens, starting with a letter or digit. */
+export const DEPLOY_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+/** The deploy environments of a client project (its `local` is never seeded). */
+export const DEPLOY_ENVS = [VAULT_ENV_MAIN, VAULT_ENV_DEVELOP];
+/** The only environment the template project is read from. */
+export const TEMPLATE_ENV = VAULT_ENV_MAIN;
+/** Suffix of the template's default name: `<repo>-defaults`. */
+export const TEMPLATE_DEFAULT_SUFFIX = 'defaults';
+/**
+ * 🔴 Keys whose value belongs to ONE deploy: always compared across clients (no length or template
+ * exception) and forbidden in the template. Plus every `*_CLIENT_SECRET` and `AUTH_*_SECRET`
+ * ({@link isUniqueKey}).
+ */
+export const UNIQUE_KEYS = [
+    'DATABASE_URL',
+    'AUTH_SECRET',
+    'NEXTAUTH_SECRET',
+    'MFA_ENCRYPTION_KEY',
+    'NEON_API_KEY',
+    'NEON_PROJECT_ID',
+    'RESEND_API_KEY',
+    'CRON_SECRET',
+    'VAPID_PRIVATE_KEY',
+    'BACKLOG_API_KEY',
+    'BACKLOG_PROJECT_ID',
+];
+/** Values shorter than this are not compared across clients (`true`, `production`, a port). */
+export const FOREIGN_VALUE_MIN_LENGTH = 16;
+/** An environment suffix in a key name — never valid in the vault (`fx-secrets-vault §6`). */
+export const ENV_SUFFIX_RE = /_(MAIN|DEVELOP)$/;
+/** The keys the registry derives for every deploy (`deriveDeployValues`) — never a `bucketKey`. */
+export const DERIVED_KEYS = [
+    'NEXT_PUBLIC_APP_URL',
+    'NEXT_PUBLIC_APP_ENV',
+    'WEBAUTHN_RP_ID',
+    'WEBAUTHN_RELATED_ORIGINS',
+];
+/** How the foreign-value check names the principal project when a value of it turns up. */
+export const PRINCIPAL_OWNER = 'principal';
+/** Whether `key` holds a value that belongs to one deploy only. */
+export function isUniqueKey(key) {
+    return UNIQUE_KEYS.includes(key) || /_CLIENT_SECRET$/.test(key) || /^AUTH_.+_SECRET$/.test(key);
+}
+/** A bare host (`app.example.com`) — no scheme, no path, no port. */
+const HOST_RE = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+/** A key name as the vault and the deploys use it. */
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A registry that cannot be read or does not have the shape — names the file, never guesses. */
+export class DeploysRegistryError extends CLIError {
+    constructor(detail) {
+        super(`\`${DEPLOYS_REGISTRY_FILE}\` no se puede usar: ${detail}\n` +
+            'Ese archivo declara los despliegues del repo (fx-secrets-vault §6). No leo un registro "de menos": ' +
+            'corrígelo y vuelve a correr. No se escribió nada.');
+        this.name = 'DeploysRegistryError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function strictObject(value, where, allowed) {
+    if (!isObject(value))
+        throw new DeploysRegistryError(`\`${where}\` debe ser un objeto.`);
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw new DeploysRegistryError(`\`${where}\` tiene campos que el registro no admite: ${unknown.map((k) => `\`${k}\``).join(', ')}. ` +
+            `Admite: ${allowed.map((k) => `\`${k}\``).join(', ')}. Una credencial nunca va aquí.`);
+    }
+    return value;
+}
+function requiredString(object, key, where) {
+    const value = object[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new DeploysRegistryError(`\`${where}.${key}\` debe ser un texto no vacío.`);
+    }
+    return value.trim();
+}
+function optionalString(object, key, where) {
+    if (object[key] === undefined)
+        return undefined;
+    return requiredString(object, key, where);
+}
+function envMap(value, where, check) {
+    const object = strictObject(value, where, DEPLOY_ENVS);
+    const out = {};
+    for (const env of DEPLOY_ENVS) {
+        const entry = optionalString(object, env, where);
+        if (entry === undefined)
+            continue;
+        check(entry, `${where}.${env}`);
+        out[env] = entry;
+    }
+    return out;
+}
+function assertHost(host, at) {
+    if (!HOST_RE.test(host)) {
+        throw new DeploysRegistryError(`\`${at}\` debe ser un host (\`app.ejemplo.com\`), sin https:// ni ruta.`);
+    }
+}
+function parseDeploy(value, index) {
+    const where = `deploys[${index}]`;
+    const object = strictObject(value, where, [
+        'slug',
+        'name',
+        'domains',
+        'bucket',
+        'ownKeys',
+        'vercel',
+        'railway',
+        'neon',
+        'vault',
+    ]);
+    const slug = requiredString(object, 'slug', where);
+    if (!DEPLOY_SLUG_RE.test(slug)) {
+        throw new DeploysRegistryError(`\`${where}.slug\` (\`${slug}\`) no es un slug válido: minúsculas, dígitos y guiones, empezando por letra o dígito.`);
+    }
+    const name = requiredString(object, 'name', where);
+    const domains = envMap(object.domains ?? {}, `${where}.domains`, assertHost);
+    const bucket = object.bucket === undefined ? undefined : envMap(object.bucket, `${where}.bucket`, () => { });
+    const ownRaw = object.ownKeys ?? [];
+    if (!Array.isArray(ownRaw) || ownRaw.some((k) => typeof k !== 'string' || !KEY_RE.test(k))) {
+        throw new DeploysRegistryError(`\`${where}.ownKeys\` debe ser una lista de NOMBRES de variable (nunca valores).`);
+    }
+    const entry = { slug, name, domains, ownKeys: [...new Set(ownRaw)] };
+    if (bucket)
+        entry.bucket = bucket;
+    if (object.vercel !== undefined) {
+        const vercel = strictObject(object.vercel, `${where}.vercel`, ['projectId', 'teamId']);
+        const teamId = optionalString(vercel, 'teamId', `${where}.vercel`);
+        entry.vercel = {
+            projectId: requiredString(vercel, 'projectId', `${where}.vercel`),
+            ...(teamId ? { teamId } : {}),
+        };
+    }
+    if (object.railway !== undefined) {
+        const railway = strictObject(object.railway, `${where}.railway`, ['projectId', 'services']);
+        if (!Array.isArray(railway.services) || railway.services.length === 0) {
+            throw new DeploysRegistryError(`\`${where}.railway.services\` debe ser una lista no vacía.`);
+        }
+        const services = railway.services.map((raw, i) => {
+            const at = `${where}.railway.services[${i}]`;
+            const service = strictObject(raw, at, ['serviceId', 'env', 'railwayEnv']);
+            const env = requiredString(service, 'env', at);
+            if (!DEPLOY_ENVS.includes(env)) {
+                throw new DeploysRegistryError(`\`${at}.env\` debe ser ${DEPLOY_ENVS.join(' o ')}.`);
+            }
+            const railwayEnv = optionalString(service, 'railwayEnv', at);
+            return {
+                serviceId: requiredString(service, 'serviceId', at),
+                env: env,
+                ...(railwayEnv ? { railwayEnv } : {}),
+            };
+        });
+        entry.railway = {
+            projectId: requiredString(railway, 'projectId', `${where}.railway`),
+            services,
+        };
+    }
+    if (object.neon !== undefined) {
+        const neon = strictObject(object.neon, `${where}.neon`, ['projectId']);
+        entry.neon = { projectId: requiredString(neon, 'projectId', `${where}.neon`) };
+    }
+    if (object.vault !== undefined) {
+        const vault = strictObject(object.vault, `${where}.vault`, ['projectId']);
+        entry.vault = { projectId: requiredString(vault, 'projectId', `${where}.vault`) };
+    }
+    return entry;
+}
+/**
+ * Validate a parsed registry. Strict: an unknown field anywhere aborts (a credential never slips
+ * in as an "extra"). Also refused: duplicate slugs, and two deploys writing to the same Vercel
+ * project or Railway service (two writers on one destination).
+ */
+export function parseDeploysRegistry(raw) {
+    const root = strictObject(raw, 'la raíz', ['$comment', 'template', 'bucketKey', 'deploys']);
+    const registry = { deploys: [] };
+    if (root.template !== undefined) {
+        const template = strictObject(root.template, 'template', ['project', 'projectId']);
+        const project = optionalString(template, 'project', 'template');
+        if (project !== undefined && !DEPLOY_SLUG_RE.test(project)) {
+            throw new DeploysRegistryError(`\`template.project\` (\`${project}\`) no es un slug válido.`);
+        }
+        const projectId = optionalString(template, 'projectId', 'template');
+        registry.template = { ...(project ? { project } : {}), ...(projectId ? { projectId } : {}) };
+    }
+    const bucketKey = optionalString(root, 'bucketKey', 'la raíz');
+    if (bucketKey !== undefined) {
+        if (!KEY_RE.test(bucketKey)) {
+            throw new DeploysRegistryError('`bucketKey` debe ser un nombre de variable.');
+        }
+        if (isUniqueKey(bucketKey) || DERIVED_KEYS.includes(bucketKey)) {
+            throw new DeploysRegistryError(`\`bucketKey\` (\`${bucketKey}\`) no puede ser una clave de valor único ni una que el registro ya ` +
+                `deriva (${DERIVED_KEYS.map((k) => `\`${k}\``).join(', ')}): el bucket la pisaría.`);
+        }
+        registry.bucketKey = bucketKey;
+    }
+    if (!Array.isArray(root.deploys) || root.deploys.length === 0) {
+        throw new DeploysRegistryError('`deploys` debe ser una lista con al menos un despliegue.');
+    }
+    registry.deploys = root.deploys.map((entry, index) => parseDeploy(entry, index));
+    const seen = new Set();
+    const destinations = new Map();
+    for (const deploy of registry.deploys) {
+        if (seen.has(deploy.slug)) {
+            throw new DeploysRegistryError(`el slug \`${deploy.slug}\` aparece dos veces.`);
+        }
+        seen.add(deploy.slug);
+        if (deploy.bucket && Object.keys(deploy.bucket).length > 0 && !registry.bucketKey) {
+            throw new DeploysRegistryError(`\`${deploy.slug}\` declara un bucket, pero la raíz no declara \`bucketKey\` (la variable donde va).`);
+        }
+        const targets = [
+            ...(deploy.vercel ? [`el proyecto de Vercel \`${deploy.vercel.projectId}\``] : []),
+            ...(deploy.railway?.services ?? []).map((s) => `el servicio de Railway \`${s.serviceId}\` (${s.railwayEnv ?? s.env})`),
+        ];
+        for (const target of targets) {
+            const owner = destinations.get(target);
+            if (owner && owner !== deploy.slug) {
+                throw new DeploysRegistryError(`\`${owner}\` y \`${deploy.slug}\` escriben en ${target}: dos escritores en un destino se pisan.`);
+            }
+            destinations.set(target, deploy.slug);
+        }
+    }
+    return registry;
+}
+/** Read and validate `.timekast/deploys.json`. Missing, unreadable or malformed → aborts naming it. */
+export function readDeploysRegistry(rootDir) {
+    const file = path.join(rootDir, DEPLOYS_REGISTRY_FILE);
+    if (!existsSync(file)) {
+        throw new CLIError(`Este repo no tiene \`${DEPLOYS_REGISTRY_FILE}\`: es el registro de despliegues (slugs, dominios, ids; ` +
+            'sin credenciales) que este comando opera. Créalo y commitéalo (fx-secrets-vault §6). No se escribió nada.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new DeploysRegistryError('no es JSON válido o no se pudo leer.');
+    }
+    return parseDeploysRegistry(parsed);
+}
+/** The deploy of `slug`; an unknown one names the valid slugs. */
+export function resolveDeploy(registry, slug) {
+    if (!DEPLOY_SLUG_RE.test(slug)) {
+        throw new CLIError(`\`${slug}\` no es un slug de despliegue válido (minúsculas, dígitos y guiones). ` +
+            `Los del registro: ${registry.deploys.map((d) => `\`${d.slug}\``).join(', ')}.`);
+    }
+    const deploy = registry.deploys.find((d) => d.slug === slug);
+    if (!deploy) {
+        throw new CLIError(`\`${slug}\` no está en \`${DEPLOYS_REGISTRY_FILE}\`. Los despliegues válidos: ` +
+            `${registry.deploys.map((d) => `\`${d.slug}\``).join(', ')}.`);
+    }
+    return deploy;
+}
+/**
+ * Name every project and refuse a reserved one: a client project can never be `rail-timekast`, the
+ * template or the principal — neither by its deploy slug nor by its full name.
+ */
+export function deployProjectNames(registry, principal) {
+    const template = registry.template?.project ?? `${principal}-${TEMPLATE_DEFAULT_SUFFIX}`;
+    const reserved = new Set([RAIL_TIMEKAST.name, template, principal]);
+    if (template === principal || template === RAIL_TIMEKAST.name) {
+        throw new CLIError(`La plantilla no puede llamarse \`${template}\`: es el proyecto principal o el rail. No se escribió nada.`);
+    }
+    if (!template.startsWith(`${principal}-`)) {
+        throw new CLIError(`La plantilla \`${template}\` no empieza por \`${principal}-\` (el nombre del proyecto principal): ` +
+            'la plantilla de un repo se llama `<repo>-…`, así no se confunde con la de otro. Cambia ' +
+            `\`template.project\` en \`${DEPLOYS_REGISTRY_FILE}\`. No se escribió nada.`);
+    }
+    const clients = new Map();
+    for (const deploy of registry.deploys) {
+        const project = `${principal}-${deploy.slug}`;
+        if (reserved.has(deploy.slug) || reserved.has(project)) {
+            throw new CLIError(`El despliegue \`${deploy.slug}\` da el proyecto \`${project}\`, un nombre reservado ` +
+                `(\`${RAIL_TIMEKAST.name}\`, la plantilla \`${template}\` o el principal \`${principal}\`). ` +
+                `Cambia su slug en \`${DEPLOYS_REGISTRY_FILE}\`. No se escribió nada.`);
+        }
+        clients.set(deploy.slug, project);
+    }
+    return { principal, template, clients };
+}
+/**
+ * What the registry derives, per environment — the kit's own rules (`buildEnvPlan`): the origin of
+ * each environment, ONE rpID (the production host) with the develop origin as related origin, the
+ * deployment identity, and the bucket into `bucketKey`.
+ */
+export function deriveDeployValues(deploy, bucketKey) {
+    const out = { main: {}, develop: {} };
+    out.main.NEXT_PUBLIC_APP_ENV = 'production';
+    out.develop.NEXT_PUBLIC_APP_ENV = 'preview';
+    const prod = deploy.domains.main;
+    const dev = deploy.domains.develop;
+    for (const env of DEPLOY_ENVS) {
+        const host = deploy.domains[env];
+        if (host)
+            out[env].NEXT_PUBLIC_APP_URL = `https://${host}`;
+        if (prod)
+            out[env].WEBAUTHN_RP_ID = prod;
+        if (dev)
+            out[env].WEBAUTHN_RELATED_ORIGINS = relatedOriginsFor([dev]);
+        const bucket = deploy.bucket?.[env];
+        if (bucket && bucketKey)
+            out[env][bucketKey] = bucket;
+    }
+    return out;
+}
+/**
+ * The set of each environment by precedence: own stored non-empty value (only for a key declared
+ * in `ownKeys`) → derived from the registry → template. A key with none of the three is absent.
+ * In `develop`, a declared key with no value there, nothing derived, and an own value in `main`
+ * takes `main`'s (the apply writes it as a reference): an own value is never replaced by the
+ * template's in the other environment.
+ */
+export function buildEnvironmentSets(input) {
+    const own = new Set(input.ownKeys);
+    const out = {};
+    for (const env of DEPLOY_ENVS) {
+        const derived = input.derived[env];
+        const keys = new Set([...input.template.keys(), ...Object.keys(derived), ...own]);
+        const values = new Map();
+        const sources = new Map();
+        for (const key of keys) {
+            const stored = input.stored[env].get(key);
+            if (own.has(key) && stored !== undefined && stored !== '') {
+                values.set(key, stored);
+                sources.set(key, 'propio');
+                continue;
+            }
+            const fromRegistry = derived[key];
+            if (fromRegistry !== undefined) {
+                values.set(key, fromRegistry);
+                sources.set(key, 'registro');
+                continue;
+            }
+            const storedMain = input.stored.main.get(key);
+            if (env === VAULT_ENV_DEVELOP &&
+                own.has(key) &&
+                storedMain !== undefined &&
+                storedMain !== '') {
+                values.set(key, storedMain);
+                sources.set(key, 'propio de main');
+                continue;
+            }
+            const fromTemplate = input.template.get(key);
+            if (fromTemplate !== undefined && fromTemplate !== '') {
+                values.set(key, fromTemplate);
+                sources.set(key, 'plantilla');
+            }
+        }
+        out[env] = { values, sources };
+    }
+    return out;
+}
+/**
+ * The diff of one environment: what the apply adds or changes. Compared on EXPANDED values, so a
+ * key whose value did not change is never rewritten. Own values are never written (they are what
+ * the vault already has). Keys the client holds beyond the computed set are not here: see
+ * {@link extraKeys}.
+ */
+export function diffEnv(environment, before, after, mainAfter) {
+    const changes = [];
+    for (const [key, value] of after.values) {
+        if (after.sources.get(key) === 'propio')
+            continue;
+        const had = before.get(key);
+        if (had === value)
+            continue;
+        const reference = environment === VAULT_ENV_DEVELOP &&
+            mainAfter !== undefined &&
+            mainAfter.values.get(key) === value;
+        changes.push({
+            environment,
+            key,
+            action: had === undefined ? 'añade' : 'cambia',
+            as: reference ? 'referencia' : 'valor',
+        });
+    }
+    return changes.sort((a, b) => a.key.localeCompare(b.key));
+}
+/** Keys the client holds that the computed set does not — informative, never deleted. */
+export function extraKeys(before, after) {
+    return [...before.keys()].filter((key) => !after.values.has(key)).sort();
+}
+/** The identifiers of a deploy's registry entry (domains, buckets, ids), lowercased. */
+export function registryIdentifiers(deploy) {
+    const ids = [
+        ...Object.values(deploy.domains),
+        ...Object.values(deploy.bucket ?? {}),
+        deploy.vercel?.projectId,
+        deploy.railway?.projectId,
+        ...(deploy.railway?.services ?? []).map((s) => s.serviceId),
+        deploy.neon?.projectId,
+    ];
+    return [...new Set(ids.filter((id) => Boolean(id)).map((id) => id.toLowerCase()))];
+}
+/**
+ * The tokens of a value an identifier is compared with: the whole value and its pieces split on
+ * anything that is not part of a host or an id (`https://a.com/x` → `a.com`, `x`, …).
+ */
+function tokensOf(value) {
+    const lower = value.toLowerCase();
+    return new Set([lower, ...lower.split(/[^a-z0-9._-]+/).filter(Boolean)]);
+}
+/**
+ * Whether a registry identifier appears in `tokens`, on LABEL boundaries (`.`), never as a free
+ * substring: the whole token, or a run of its labels — `app.cliente-b.com` inside
+ * `cdn.app.cliente-b.com` (a subdomain), `cliente-b-prod` as the first label of
+ * `cliente-b-prod.<account>.r2…` (a bucket host). `cliente-b` does NOT match `cliente-bb.com`.
+ */
+export function identifierInTokens(identifier, tokens) {
+    const id = identifier.toLowerCase();
+    for (const token of tokens) {
+        if (token === id)
+            return true;
+        if (`.${token}.`.includes(`.${id}.`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Values of `deploy` that belong to another deploy. A value is compared with EVERY value (any key,
+ * any environment) of each other deploy — computed after precedence AND stored — and with the
+ * registry identifiers of the others (domains, buckets, ids). Exceptions for a non-unique key: a
+ * value identical to the template's in that key, and values shorter than
+ * {@link FOREIGN_VALUE_MIN_LENGTH}. A unique key ({@link isUniqueKey}) is always compared.
+ */
+export function findForeignValues(input) {
+    const found = new Map();
+    const add = (hit) => {
+        found.set(`${hit.environment}|${hit.key}|${hit.owner}`, hit);
+    };
+    const othersValues = input.others.map((other) => {
+        const all = new Set();
+        for (const map of other.values)
+            for (const value of map.values())
+                if (value !== '')
+                    all.add(value);
+        return { slug: other.slug, all, identifiers: other.identifiers };
+    });
+    for (const env of DEPLOY_ENVS) {
+        for (const [key, value] of input.sets[env]) {
+            if (value === '')
+                continue;
+            const unique = isUniqueKey(key);
+            const exempt = !unique && (value.length < FOREIGN_VALUE_MIN_LENGTH || input.template.get(key) === value);
+            const tokens = tokensOf(value);
+            for (const other of othersValues) {
+                if (!exempt && other.all.has(value)) {
+                    add({ deploy: input.deploy, key, environment: env, owner: other.slug });
+                    continue;
+                }
+                if (other.identifiers.some((id) => identifierInTokens(id, tokens))) {
+                    add({ deploy: input.deploy, key, environment: env, owner: other.slug });
+                }
+            }
+        }
+    }
+    return [...found.values()].sort((a, b) => a.environment.localeCompare(b.environment) || a.key.localeCompare(b.key));
+}
+/**
+ * The template's keys that would contaminate every client: a unique key, a rail token, an
+ * environment suffix, or a value identical to a client's OWN stored value (non-short).
+ */
+export function findTemplateProblems(template, ownValues) {
+    // `ownValues` must come WITHOUT the values identical to the template's in the same key: those
+    // are the template's own copy, seeded by an earlier run (see `planDeploys`).
+    const problems = [];
+    for (const [key, value] of template) {
+        if (isUniqueKey(key))
+            problems.push({ key, reason: 'única' });
+        else if (isRailKey(key))
+            problems.push({ key, reason: 'rail' });
+        else if (ENV_SUFFIX_RE.test(key))
+            problems.push({ key, reason: 'sufijo' });
+        else if (value.length >= FOREIGN_VALUE_MIN_LENGTH) {
+            const owner = ownValues.find((own) => own.values.has(value));
+            if (owner)
+                problems.push({ key, reason: 'propia', owner: owner.slug });
+        }
+    }
+    return problems.sort((a, b) => a.key.localeCompare(b.key));
+}
+const TEMPLATE_REASON = {
+    única: 'es una clave de valor único por despliegue',
+    rail: 'es un token del rail (fx-secrets-vault §2)',
+    sufijo: 'lleva sufijo de entorno (fx-secrets-vault §6: nunca `_MAIN`/`_DEVELOP`)',
+    propia: 'repite el valor propio de un despliegue',
+};
+/** A value of one client found in another: abort before the first write, naming it. */
+export class ForeignValueError extends CLIError {
+    hits;
+    constructor(hits) {
+        super('No escribo nada: un valor de un despliegue aparece en otro (o en el proyecto principal).\n' +
+            hits
+                .map((hit) => `  · \`${hit.key}\` en ${hit.environment} de \`${hit.deploy}\` es de \`${hit.owner}\``)
+                .join('\n') +
+            '\nCorrige el valor en la bóveda (o en el registro) del despliegue que lo tiene mal y repite. ' +
+            'No se creó ningún proyecto ni se escribió ningún valor.');
+        this.name = 'ForeignValueError';
+        this.hits = hits;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+const MAIN_ROOT = { env: VAULT_ENV_MAIN, path: VAULT_ROOT_PATH };
+const DEVELOP_ROOT = { env: VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH };
+const ROOT_OF = { main: MAIN_ROOT, develop: DEVELOP_ROOT };
+function emptyEnvValues() {
+    return { main: new Map(), develop: new Map() };
+}
+/**
+ * S1 — an existing project is adopted only by its ANNOTATED id. A name alone proves nothing: a
+ * project with that slug may belong to someone else, and adopting it would write this client's
+ * values into it. Names the project and the registry field, never an id to copy blindly.
+ */
+function assertAnnotated(input) {
+    const { found, annotated, project, field, owner } = input;
+    if (found && annotated === undefined) {
+        throw new CLIError(`La bóveda ya tiene un proyecto \`${project}\` (${owner}), pero \`${DEPLOYS_REGISTRY_FILE}\` no anota su ` +
+            `id en \`${field}\`. No adopto un proyecto sólo por su nombre: podría ser de otro cliente.\n` +
+            `  · Verifica en el dashboard de la bóveda que \`${project}\` es de ${owner} (sus miembros, sus ` +
+            `secretos y sus syncs), copia su id a \`${field}\` y repite.\n` +
+            '  · Si no es suyo, no lo toques: cambia el slug en el registro.\n' +
+            'No se escribió nada.');
+    }
+    if (found && annotated !== undefined && annotated !== found.id) {
+        throw new CLIError(`El proyecto \`${project}\` (${owner}) no es el que anota \`${field}\` en \`${DEPLOYS_REGISTRY_FILE}\`: ` +
+            'los ids no coinciden. O el registro está mal, o el proyecto con ese nombre es otro. Verifica en el ' +
+            'dashboard de la bóveda cuál es el de este cliente y corrige el registro. No se escribió nada.');
+    }
+    if (!found && annotated !== undefined) {
+        throw new CLIError(`\`${field}\` anota un id para \`${project}\` (${owner}), pero tu sesión no ve ese proyecto: o ya no ` +
+            'existe, o no tienes acceso a él.\n' +
+            '  · Si no tienes acceso: pídelo a un admin de la bóveda (el acceso es por proyecto).\n' +
+            `  · Si lo borraron: quita \`${field}\` del registro y repite (el \`--apply\` lo crea y anota el nuevo).\n` +
+            'No se escribió nada.');
+    }
+}
+/**
+ * S3 — every value the PRINCIPAL project holds, in each environment and in its `/ci` folders:
+ * a client value found there came from the principal and is foreign too.
+ */
+async function readPrincipalValues(client, principal) {
+    const out = [];
+    for (const env of principal.environments.map((e) => e.slug)) {
+        out.push(await client.readSecrets(principal.id, { env, path: VAULT_ROOT_PATH }, { expandReferences: true }));
+        if (env === VAULT_ENV_MAIN || env === VAULT_ENV_DEVELOP) {
+            out.push(await client.readSecrets(principal.id, { env, path: VAULT_CI_PATH }, { expandReferences: true }));
+        }
+    }
+    return out;
+}
+/**
+ * Write a created project's id back into `.timekast/deploys.json` (`deploys[i].vault.projectId`),
+ * preserving the rest of the file: JSON with two spaces and a final newline. The file stays
+ * uncommitted — whoever runs commits it.
+ */
+export function recordDeployProjectId(rootDir, slug, projectId) {
+    const file = path.join(rootDir, DEPLOYS_REGISTRY_FILE);
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    const entry = Array.isArray(raw.deploys)
+        ? raw.deploys.find((d) => isObject(d) && d.slug === slug)
+        : undefined;
+    if (!isObject(entry)) {
+        throw new DeploysRegistryError(`no encontré el despliegue \`${slug}\` para anotar su proyecto.`);
+    }
+    entry.vault = { projectId };
+    writeFileSync(file, `${JSON.stringify(raw, null, 2)}\n`);
+}
+/**
+ * Read everything, compute every client, check them all — and only then hand back an `apply`.
+ * Reads only: no project is created and no value written here, so a stop of the plan (with or
+ * without `--apply`) leaves the vault exactly as it was.
+ *
+ * The `apply` writes in a fixed order — new projects (each id handed to `onProjectCreated` right
+ * away), then values. A failure INSIDE the apply leaves what was already written; running it again
+ * adopts it (the ids are annotated) and completes the rest.
+ *
+ * @param only - the deploy of `--deploy <slug>`; the others are still read (their values and
+ *   identifiers are what the foreign-value check compares against).
+ */
+export async function planDeploys(input) {
+    const { client, registry } = input;
+    // 0. A person behind the session — before anything else is read.
+    const person = await client.whoAmI();
+    const targetedSlug = input.only === undefined ? null : resolveDeploy(registry, input.only).slug;
+    const principal = await client.getProject(input.principalProjectId);
+    const names = deployProjectNames(registry, principal.slug);
+    // 1. The template: must exist, with its id annotated; read with references expanded (the vault
+    //    cannot reference across projects, so each client gets a copy by value).
+    const templateProject = await client.findProjectBySlug(names.template);
+    if (!templateProject && registry.template?.projectId === undefined) {
+        throw new CLIError(`La bóveda no tiene la plantilla \`${names.template}\` (o tu sesión no tiene acceso a ella). Es el ` +
+            'proyecto con los valores comunes a todos los despliegues: créalo (sólo con el entorno `main`) y anota ' +
+            'su id en `template.projectId`, o pide acceso a un admin de la bóveda. No se escribió nada.');
+    }
+    assertAnnotated({
+        found: templateProject,
+        annotated: registry.template?.projectId,
+        project: names.template,
+        field: 'template.projectId',
+        owner: 'la plantilla',
+    });
+    const templateId = templateProject.id;
+    const template = await client.readSecrets(templateId, { env: TEMPLATE_ENV, path: VAULT_ROOT_PATH }, { expandReferences: true });
+    // 2. Every client: found (and annotated) → read both deploy roots; missing → created only if
+    //    targeted and not annotated.
+    const states = [];
+    for (const [index, deploy] of registry.deploys.entries()) {
+        const project = names.clients.get(deploy.slug);
+        const targeted = targetedSlug === null || targetedSlug === deploy.slug;
+        const found = await client.findProjectBySlug(project);
+        assertAnnotated({
+            found,
+            annotated: deploy.vault?.projectId,
+            project,
+            field: `deploys[${index}].vault.projectId`,
+            owner: `el despliegue \`${deploy.slug}\``,
+        });
+        if (!found) {
+            if (!targeted) {
+                throw new CLIError(`No puedo leer el proyecto \`${project}\` del despliegue \`${deploy.slug}\`: no existe todavía, o tu ` +
+                    'sesión no tiene acceso a él. Sin leerlo no puedo comprobar que otro despliegue no copie sus valores.\n' +
+                    `  · Si no existe: corre sin \`--deploy\` (o con \`--deploy ${deploy.slug}\`) para crearlo.\n` +
+                    '  · Si existe: pide acceso a ese proyecto a un admin de la bóveda (el acceso es por proyecto).\n' +
+                    'No se escribió nada.');
+            }
+            states.push({ deploy, index, project, projectId: null, stored: emptyEnvValues(), targeted });
+            continue;
+        }
+        const stored = emptyEnvValues();
+        for (const env of DEPLOY_ENVS) {
+            stored[env] = await client.readSecrets(found.id, ROOT_OF[env], { expandReferences: true });
+        }
+        states.push({ deploy, index, project, projectId: found.id, stored, targeted });
+    }
+    // 3. The template must not contaminate anyone.
+    const ownValues = states.map((state) => {
+        const values = new Set();
+        for (const env of DEPLOY_ENVS) {
+            for (const key of state.deploy.ownKeys) {
+                const value = state.stored[env].get(key);
+                // Identical to the template's value in the same key = a copy an earlier run seeded.
+                if (value && value !== template.get(key))
+                    values.add(value);
+            }
+        }
+        return { slug: state.deploy.slug, values };
+    });
+    const problems = findTemplateProblems(template, ownValues);
+    if (problems.length > 0) {
+        throw new CLIError(`La plantilla \`${names.template}\` tiene claves que no siembro a ningún despliegue:\n` +
+            problems
+                .map((p) => `  · \`${p.key}\`: ${TEMPLATE_REASON[p.reason]}${p.owner ? ` (\`${p.owner}\`)` : ''}`)
+                .join('\n') +
+            '\nQuítalas (o renómbralas) en la plantilla y repite. No se escribió nada.');
+    }
+    // 4. Compute every client (the non-targeted ones too: they are what the others compare with).
+    for (const state of states) {
+        state.computed = buildEnvironmentSets({
+            template,
+            stored: state.stored,
+            derived: deriveDeployValues(state.deploy, registry.bucketKey),
+            ownKeys: state.deploy.ownKeys,
+        });
+    }
+    // 5. All-or-nothing: every targeted client against every other AND the principal, before the
+    //    first write. A targeted client is compared by what it WILL hold (stored, overridden by the
+    //    computed set); another targeted one likewise — a stale template copy the apply replaces is
+    //    not its value. A client this run does not write is compared by what it holds AND what it
+    //    would compute. The principal, by everything it holds (every environment, `/ci` included).
+    const principalValues = await readPrincipalValues(client, principal);
+    const resultingOf = (state) => {
+        const computed = state.computed;
+        const resulting = emptyEnvValues();
+        for (const env of DEPLOY_ENVS) {
+            resulting[env] = new Map([...state.stored[env], ...computed[env].values]);
+        }
+        return resulting;
+    };
+    const hits = [];
+    for (const state of states.filter((s) => s.targeted)) {
+        const resulting = resultingOf(state);
+        hits.push(...findForeignValues({
+            deploy: state.deploy.slug,
+            sets: resulting,
+            template,
+            others: [
+                ...states
+                    .filter((other) => other !== state)
+                    .map((other) => ({
+                    slug: other.deploy.slug,
+                    values: other.targeted
+                        ? DEPLOY_ENVS.map((env) => resultingOf(other)[env])
+                        : DEPLOY_ENVS.flatMap((env) => [
+                            other.stored[env],
+                            other.computed[env].values,
+                        ]),
+                    identifiers: registryIdentifiers(other.deploy),
+                })),
+                { slug: PRINCIPAL_OWNER, values: principalValues, identifiers: [] },
+            ],
+        }));
+    }
+    if (hits.length > 0)
+        throw new ForeignValueError(hits);
+    // 6. The plan + the write guard judged for every planned write, still before any call.
+    const plans = [];
+    const writes = new Map();
+    for (const state of states.filter((s) => s.targeted)) {
+        const computed = state.computed;
+        const changes = [
+            ...diffEnv(VAULT_ENV_MAIN, state.stored.main, computed.main),
+            ...diffEnv(VAULT_ENV_DEVELOP, state.stored.develop, computed.develop, computed.main),
+        ];
+        for (const change of changes) {
+            const location = normalizeLocation(ROOT_OF[change.environment]);
+            const value = change.as === 'referencia'
+                ? `\${${VAULT_ENV_MAIN}.${change.key}}`
+                : computed[change.environment].values.get(change.key);
+            assertWriteAllowed(change.key, value, location);
+        }
+        const ownMissing = {};
+        const extra = {};
+        const folderKeys = {};
+        for (const env of DEPLOY_ENVS) {
+            extra[env] = extraKeys(state.stored[env], computed[env]);
+            ownMissing[env] = state.deploy.ownKeys.filter((key) => !computed[env].values.has(key)).sort();
+            folderKeys[env] = [
+                ...new Set([...state.stored[env].keys(), ...computed[env].values.keys()]),
+            ].sort();
+        }
+        plans.push({
+            slug: state.deploy.slug,
+            name: state.deploy.name,
+            project: state.project,
+            projectId: state.projectId,
+            create: state.projectId === null,
+            changes,
+            extra,
+            ownMissing,
+            folderKeys,
+        });
+        writes.set(state.deploy.slug, { changes, computed });
+    }
+    const plan = {
+        person: person.identity,
+        principal: { slug: principal.slug, id: principal.id },
+        template: { slug: names.template, id: templateId },
+        deploys: plans,
+        projects: [
+            { role: PRINCIPAL_OWNER, slug: principal.slug, id: principal.id },
+            { role: 'plantilla', slug: names.template, id: templateId },
+            ...states
+                .filter((state) => state.projectId !== null)
+                .map((state) => ({
+                role: state.deploy.slug,
+                slug: state.project,
+                id: state.projectId,
+            })),
+        ],
+    };
+    const apply = async () => {
+        const results = [];
+        // New projects first: if one cannot be created, only the projects created before it exist
+        // (their ids already annotated) and no value has been written.
+        const ordered = [...plans].sort((a, b) => Number(b.create) - Number(a.create));
+        const ids = new Map();
+        const createdSoFar = [];
+        for (const deploy of ordered) {
+            let layout;
+            try {
+                // `mustCreate`: a project that appears between the plan and this call is never adopted —
+                // the client stops on finding it, before any write on it (no layout, no members).
+                layout = await client.ensureProjectLayout({
+                    name: deploy.project,
+                    slug: deploy.project,
+                    ...(deploy.create ? { mustCreate: true } : {}),
+                });
+            }
+            catch (error) {
+                if (error instanceof VaultApiError && error.kind === 'project-exists') {
+                    throw new CLIError(`El proyecto \`${deploy.project}\` apareció en la bóveda entre el plan y la escritura. No lo adopto ` +
+                        `sin su id anotado (no escribí nada en él): verifica que es de \`${deploy.slug}\`, anótalo y repite.` +
+                        writtenBefore(createdSoFar));
+                }
+                if (deploy.create && error instanceof VaultApiError) {
+                    throw new CLIError(`No pude crear \`${deploy.project}\` (el plan lo marcaba "se crea" porque tu sesión no lo ve). Dos ` +
+                        'causas posibles:\n' +
+                        '  · Existe con ese slug y tu sesión no tiene acceso: pide acceso a un admin de la bóveda, ' +
+                        `verifica que es de \`${deploy.slug}\` y anota su id en el registro.\n` +
+                        `  · No existe y la bóveda no dejó crearlo: ${error.message}` +
+                        writtenBefore(createdSoFar));
+                }
+                throw error;
+            }
+            if (deploy.create !== layout.projectCreated ||
+                (!deploy.create && layout.project.id !== deploy.projectId)) {
+                throw new CLIError(`El proyecto \`${deploy.project}\` no es el que el plan leyó. Repite el comando para planear de nuevo.` +
+                    writtenBefore(createdSoFar));
+            }
+            if (layout.projectCreated) {
+                const before = [...createdSoFar];
+                createdSoFar.push(deploy.project);
+                try {
+                    input.onProjectCreated?.(deploy.slug, layout.project.id);
+                }
+                catch (error) {
+                    // The project exists and its id is nowhere else: hand it over to be annotated by hand
+                    // (an id, never a secret). Without it the next `--apply` refuses to adopt the project.
+                    const cause = error instanceof Error ? error.message : 'error desconocido';
+                    throw new CLIError(`Creé el proyecto \`${deploy.project}\` del despliegue \`${deploy.slug}\` (id \`${layout.project.id}\`), ` +
+                        `pero no pude anotar su id en \`${DEPLOYS_REGISTRY_FILE}\`: ${cause}\n` +
+                        `  · Anótalo a mano en ese archivo, en el despliegue \`${deploy.slug}\`: ` +
+                        `"vault": { "projectId": "${layout.project.id}" } (es un id, no un secreto), y repite el \`--apply\`.\n` +
+                        '  · Sin ese id anotado, la corrida siguiente no adopta el proyecto (podría ser de otro cliente).' +
+                        (before.length === 0 ? '\nNingún valor se escribió todavía.' : writtenBefore(before)));
+                }
+            }
+            ids.set(deploy.slug, { id: layout.project.id, created: layout.projectCreated });
+        }
+        for (const deploy of plans) {
+            const { id, created } = ids.get(deploy.slug);
+            const { changes, computed } = writes.get(deploy.slug);
+            const written = [];
+            for (const env of DEPLOY_ENVS) {
+                const values = {};
+                for (const change of changes) {
+                    if (change.environment !== env || change.as !== 'valor')
+                        continue;
+                    values[change.key] = computed[env].values.get(change.key);
+                }
+                if (Object.keys(values).length > 0) {
+                    await client.writeSecrets(id, ROOT_OF[env], values, 'upsert');
+                    for (const key of Object.keys(values))
+                        written.push({ environment: env, key });
+                }
+                for (const change of changes) {
+                    if (change.environment !== env || change.as !== 'referencia')
+                        continue;
+                    await client.writeReference(id, ROOT_OF[env], change.key, { ...MAIN_ROOT, key: change.key }, 'upsert');
+                    written.push({ environment: env, key: change.key });
+                }
+            }
+            results.push({ slug: deploy.slug, project: deploy.project, projectId: id, created, written });
+        }
+        return results;
+    };
+    return { plan, apply };
+}
+/** What a stop inside the apply leaves behind — the projects it already created, by name. */
+function writtenBefore(created) {
+    return created.length === 0
+        ? '\nNo se escribió nada.'
+        : `\nAntes de esta falla se crearon ${created.map((p) => `\`${p}\``).join(', ')} (sus ids ya están ` +
+            `anotados en \`${DEPLOYS_REGISTRY_FILE}\`); ningún valor se escribió todavía. Al repetir, se adoptan.`;
+}