@timekast/factory 2.2.0 → 2.3.1

package/dist/commands/provision.js

@@ -63,7 +63,8 @@ export const E2E_DATABASE_URL_SECRET = 'DATABASE_URL';
  * `${MAIL_SUBDOMAIN}.<base>` — NEVER the apex `<base>`, which holds the org's (or a
  * client's) corporate MX/SPF (Google Workspace, M365, …). Verifying Resend on the
  * apex would collide with that mail; an isolated subdomain keeps both working. Same
- * convention for the org (`updates.timekast.mx`) and every client (`updates.<client>`).
+ * convention for the org (`updates.timekast.com`) and, with `--client-mail`, a client
+ * (`updates.<client>`).
  */
 export const MAIL_SUBDOMAIN = 'updates';
 /** Build the transactional-mail domain for a base domain: `updates.<base>`. */
@@ -72,10 +73,11 @@ export function mailDomainFor(base) {
 }
 /**
  * The canonical, ORG-LEVEL sender for transactional mail on provisioned stacks
- * (issue §4 + §5). Sends from `noreply@updates.timekast.mx` — the dedicated subdomain
- * verified in Resend, NOT the apex `timekast.mx` (which is on Google Workspace). The
- * client's own sender is set in the `--domain` flow (PROV-006), using the same
- * `updates.<client>` convention. The unit test pins this value.
+ * (issue §4 + §5). Sends from `noreply@updates.timekast.com` — the dedicated subdomain
+ * verified in Resend, NOT the apex (which is on Google Workspace). It stays the sender
+ * after the `--domain` go-live (PROV-006): the Resend account has no room for a domain
+ * per client, so the client's own `updates.<client>` is opt-in (`--client-mail`). The
+ * unit test pins this value.
  */
 export const PROVISION_EMAIL_FROM = `noreply@${mailDomainFor(TIMEKAST_ZONE_NAME)}`;
 // `provisionDomains` moved to `cloudflare-api.ts` (next to TIMEKAST_ZONE_NAME) so
@@ -250,6 +252,11 @@ export function parseProvisionFlags(argv) {
         throw new CLIError('`--no-vault` y `--services=…vault…` se contradicen: uno pide omitir la bóveda y el otro ' +
             'crearla. Quita uno de los dos.');
     }
+    const clientMail = argv.includes('--client-mail');
+    const domain = readValueFlag(argv, 'domain');
+    if (clientMail && !domain) {
+        throw new CLIError('`--client-mail` solo aplica al go-live: pásalo junto con `--domain=<dominio del cliente>`.');
+    }
     return {
         services,
         noVault,
@@ -259,7 +266,8 @@ export function parseProvisionFlags(argv) {
         remint: argv.includes('--remint'),
         slug: readValueFlag(argv, 'slug'),
         repo: parseRepoFlag(readValueFlag(argv, 'repo')),
-        domain: readValueFlag(argv, 'domain'),
+        domain,
+        clientMail,
         dns: parseDnsRoute(readValueFlag(argv, 'dns')),
         verifyTimeout: parseVerifyTimeout(readValueFlag(argv, 'verify-timeout')),
         confirm: argv.includes('--confirm'),
@@ -1368,7 +1376,7 @@ const VAULT_PER_ENV_MINTED = ['AUTH_SECRET'];
  * Which keys each destination gets depends on the services the run includes: `neon` writes the
  * connection strings and the CI keys, `vercel` the runtime values, `backlog` its local creds.
  */
-export function buildVaultPlan(projectName, services) {
+export function buildVaultPlan(projectName, services, target) {
     const keys = {};
     const references = {};
     const add = (loc, names, asRef = false) => {
@@ -1408,7 +1416,9 @@ export function buildVaultPlan(projectName, services) {
     if (services.includes('backlog')) {
         add(VAULT_LOCAL_ROOT, ['BACKLOG_API_KEY', 'BACKLOG_PROJECT_ID']);
     }
-    const railway = services.includes('railway');
+    // The syncs follow the DESTINATION, not this run's steps: a run with `vault` but without the
+    // `railway` step still deploys to Railway, and never gets the Vercel syncs.
+    const railway = services.includes('railway') || target === 'railway';
     return {
         project: projectName,
         environments: VAULT_LAYOUT_ENVIRONMENTS.map((env) => env.slug),
@@ -1923,12 +1933,15 @@ const RESEND_KEY_RESUME_HINT = 'repite la corrida con `--resume` y `dns` en `--s
     'hasta publicarla';
 /**
  * NO-vault: the sending domain a fresh project key is limited to — the client's mail subdomain
- * once its go-live is recorded (Resend already knows it: the go-live registers it), else the
- * interim org domain. A `--resume` that retries the key after a go-live must not move the mail
- * back to the interim domain.
- */
-function noVaultMintDomain(state) {
-    const client = state.dns?.clientDomainStatus === 'live' ? state.dns.clientDomain : undefined;
+ * once a `--client-mail` go-live is recorded (Resend already knows it: that go-live registers
+ * it), else the org domain. A `--resume` that retries the key after such a go-live must not move
+ * the mail back to the org domain. `sharedMail` marks a go-live that kept the org sender; a
+ * `live` state without it predates the flag, when every go-live moved the mail.
+ */
+export function noVaultMintDomain(state) {
+    const client = state.dns?.clientDomainStatus === 'live' && state.dns.sharedMail !== true
+        ? state.dns.clientDomain
+        : undefined;
     return client ? mailDomainFor(client) : sendingDomainOf(PROVISION_EMAIL_FROM);
 }
 /**
@@ -4711,8 +4724,9 @@ async function resolveDnsToken(route, rail, headless, rootDir) {
 /**
  * PROV-006 — attach the client's DEFINITIVE domain to the Vercel project, create
  * (or print, for `registrar`) its DNS record, poll Vercel until verified, and on
- * success: retire the interim prod domain (with explicit confirmation), update
- * `EMAIL_FROM` + `NEXT_PUBLIC_APP_URL`, and register the domain in Resend.
+ * success: retire the interim prod domain (with explicit confirmation) and update
+ * `NEXT_PUBLIC_APP_URL`. The mail stays on the org sender unless `deps.clientMail`
+ * (`--client-mail`): then `EMAIL_FROM` moves to `updates.<domain>`, registered in Resend.
  *
  * Standalone-safe: runnable as a PATCH over an existing provision (the `dns` step
  * of PROV-005 already attached the interim domains) or inside the initial run. It
@@ -4745,6 +4759,7 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
             'Corre el paso de Vercel/GitHub primero (`--services=github,...`) y reintenta con `--resume`.');
     }
     const route = deps.dnsRoute ?? 'org';
+    const clientMail = deps.clientMail === true;
     const rail = deps.rail ?? defaultRail();
     const fetchImpl = deps.fetchImpl ?? fetch;
     const vercelToken = await readVercelToken(rail);
@@ -4823,27 +4838,32 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
     // 5. Update EMAIL_FROM + NEXT_PUBLIC_APP_URL + the WebAuthn rpID/related origins in Vercel env
     //    (idempotent — §8), and in the vault's `main:/` when the repo has one (VAULT-002).
     const hosts = existingProvisionDomains(state.projectName, state.dns);
-    await updateDomainEnv(projectId, vercelToken, teamId, domain, vercelDeps, { dev: hosts.dev, interim: hosts.prod, interimRetired }, deps.vault ?? null);
-    // 6. Register the client's MAIL SUBDOMAIN (`updates.<domain>`) in Resend — NOT the
-    //    apex, which holds the client's corporate MX/SPF (Google Workspace, M365, …).
-    //    Verifying Resend on a dedicated subdomain keeps the client's own mail intact.
-    //    BOOT-003: also CREATES the DKIM/SPF/MX records Resend returns (in the same
-    //    client zone as the CNAME) and polls until Resend reports `verified`.
-    await registerResendDomain(mailDomainFor(domain), rail, deps, fetchImpl, resendDns);
-    // 6b. VAULT-002 — the project's Resend key is limited to its sending domain, which just
-    //     changed: re-scope it to `updates.<domain>` (vault, when there is one, + deploys) and
-    //     revoke the old one once the new one reached them. Without a vault too: the deploys carry
-    //     the project's key there as well (never the rail's team key).
-    await rescopeProjectResendKey(rootDir, state, deps.vault ?? null, mailDomainFor(domain), { projectId, token: vercelToken, teamId, deps: vercelDeps }, rail, fetchImpl, { sleep: deps.sleep, now: deps.now });
+    await updateDomainEnv(projectId, vercelToken, teamId, domain, vercelDeps, { dev: hosts.dev, interim: hosts.prod, interimRetired }, deps.vault ?? null, clientMail);
+    if (clientMail) {
+        // 6. Register the client's MAIL SUBDOMAIN (`updates.<domain>`) in Resend — NOT the
+        //    apex, which holds the client's corporate MX/SPF (Google Workspace, M365, …).
+        //    Verifying Resend on a dedicated subdomain keeps the client's own mail intact.
+        //    BOOT-003: also CREATES the DKIM/SPF/MX records Resend returns (in the same
+        //    client zone as the CNAME) and polls until Resend reports `verified`.
+        await registerResendDomain(mailDomainFor(domain), rail, deps, fetchImpl, resendDns);
+        // 6b. VAULT-002 — the project's Resend key is limited to its sending domain, which just
+        //     changed: re-scope it to `updates.<domain>` (vault, when there is one, + deploys) and
+        //     revoke the old one once the new one reached them. Without a vault too: the deploys
+        //     carry the project's key there as well (never the rail's team key).
+        await rescopeProjectResendKey(rootDir, state, deps.vault ?? null, mailDomainFor(domain), { projectId, token: vercelToken, teamId, deps: vercelDeps }, rail, fetchImpl, { sleep: deps.sleep, now: deps.now });
+    }
+    else {
+        logSharedMail();
+    }
     // 7. Record the client domain as LIVE and persist.
-    state.dns = {
+    state.dns = withMailChoice({
         ...(state.dns ?? {
             domain: provisionDomains(state.projectName).prod,
             devDomain: provisionDomains(state.projectName).dev,
         }),
         clientDomain: domain,
         clientDomainStatus: 'live',
-    };
+    }, clientMail);
     writeProvisionState(rootDir, state);
 }
 /** RWAY-005 — the two records the owner creates by hand for `--dns=registrar` on Railway. */
@@ -4890,8 +4910,9 @@ async function pollRailwayDomainVerification(client, scope, dns, deps) {
  *      only PRINTS both.
  *   3. Poll the domain's state in Railway (`--verify-timeout`); timeout → `pending-verification`.
  *   4. Retire the interim `{slug}` from Railway with the same confirmation (`--confirm` headless).
- *   5. `EMAIL_FROM`, `NEXT_PUBLIC_APP_URL`, `WEBAUTHN_RP_ID`/`_RELATED_ORIGINS` → `main:/` of the
- *      vault ONLY (its sync is Railway's only writer); Resend as on Vercel.
+ *   5. `NEXT_PUBLIC_APP_URL`, `WEBAUTHN_RP_ID`/`_RELATED_ORIGINS` (+ `EMAIL_FROM` with
+ *      `--client-mail`) → `main:/` of the vault ONLY (its sync is Railway's only writer); Resend
+ *      as on Vercel (only with `--client-mail`).
  * 🔴 No request to Vercel. Requires the vault and the `railway` block (none → `--adopt`).
  */
 async function provisionRailwayClientDomain(rootDir, state, domain, deps) {
@@ -4901,6 +4922,7 @@ async function provisionRailwayClientDomain(rootDir, state, domain, deps) {
     assertRailwayDomainIds(state);
     const rw = state.railway;
     const route = deps.dnsRoute ?? 'org';
+    const clientMail = deps.clientMail === true;
     const rail = deps.rail ?? defaultRail();
     const fetchImpl = deps.fetchImpl ?? fetch;
     const client = railwayClientFor(rail, deps.railway);
@@ -4987,15 +5009,21 @@ async function provisionRailwayClientDomain(rootDir, state, domain, deps) {
         dev: hosts.dev,
         interim: hosts.prod,
         interimRetired,
-    });
-    // 6. Resend — unchanged by the destination (mail subdomain + the project's key re-scoped).
-    await registerResendDomain(mailDomainFor(domain), rail, paced, fetchImpl, resendDns);
-    await rescopeProjectResendKey(rootDir, state, vault, mailDomainFor(domain), null, rail, fetchImpl, {
-        sleep: paced.sleep,
-        now: paced.now,
-    });
+    }, clientMail);
+    // 6. Resend — unchanged by the destination (mail subdomain + the project's key re-scoped),
+    //    and only with `--client-mail`.
+    if (clientMail) {
+        await registerResendDomain(mailDomainFor(domain), rail, paced, fetchImpl, resendDns);
+        await rescopeProjectResendKey(rootDir, state, vault, mailDomainFor(domain), null, rail, fetchImpl, {
+            sleep: paced.sleep,
+            now: paced.now,
+        });
+    }
+    else {
+        logSharedMail();
+    }
     // 7. Live.
-    state.dns = { ...dnsBlock(), clientDomainStatus: 'live' };
+    state.dns = withMailChoice({ ...dnsBlock(), clientDomainStatus: 'live' }, clientMail);
     writeProvisionState(rootDir, state);
 }
 /**
@@ -5125,12 +5153,15 @@ async function deleteInterimCname(interim, rail, fetchImpl) {
  *
  * No-echo: only KEY NAMES + targets print (the values here are public, but the discipline holds).
  */
-export async function updateDomainEnv(projectId, token, teamId, domain, deps, hosts, vault = null) {
+export async function updateDomainEnv(projectId, token, teamId, domain, deps, hosts, vault = null, clientMail = false) {
     const { appOrigin, emailFrom, relatedOrigins } = domainEnvValues(domain, hosts);
     const plan = [
-        // EMAIL_FROM uses the dedicated mail subdomain (`updates.<domain>`), NOT the apex
-        // — the apex carries the client's corporate mail.
-        { key: 'EMAIL_FROM', value: emailFrom, target: ['production', 'preview'] },
+        // EMAIL_FROM only with `--client-mail`: the dedicated mail subdomain (`updates.<domain>`),
+        // NOT the apex — the apex carries the client's corporate mail. Without it the sender
+        // already in place (the org's, or one a team set by hand) is left alone.
+        ...(clientMail
+            ? [{ key: 'EMAIL_FROM', value: emailFrom, target: ['production', 'preview'] }]
+            : []),
         // 🔴 AUTH_URL / NEXTAUTH_URL are DELIBERATELY ABSENT — do not re-add them.
         // `next-auth/lib/env.js` rewrites the origin of every auth request to their value,
         // so scoping either to `preview` pins all branch deployments' callbacks to this one
@@ -5169,7 +5200,7 @@ export async function updateDomainEnv(projectId, token, teamId, domain, deps, ho
         }
     }
     if (vault) {
-        await writeDomainEnvToVault(vault, domain, hosts);
+        await writeDomainEnvToVault(vault, domain, hosts, clientMail);
     }
     else {
         warnRpIdMoved(domain);
@@ -5191,10 +5222,10 @@ function domainEnvValues(domain, hosts) {
  * reference for the shared ones; the syncs deliver them to production (Vercel or Railway, SYNC-001).
  * `NEXT_PUBLIC_APP_URL` goes to `main:/` only: `develop:/` keeps develop's origin.
  */
-async function writeDomainEnvToVault(vault, domain, hosts) {
+async function writeDomainEnvToVault(vault, domain, hosts, clientMail) {
     const { appOrigin, emailFrom, relatedOrigins } = domainEnvValues(domain, hosts);
     await vaultWrite(vault, VAULT_MAIN_ROOT, {
-        EMAIL_FROM: emailFrom,
+        ...(clientMail ? { EMAIL_FROM: emailFrom } : {}),
         NEXT_PUBLIC_APP_URL: appOrigin,
         WEBAUTHN_RP_ID: domain,
         WEBAUTHN_RELATED_ORIGINS: relatedOrigins,
@@ -5211,9 +5242,22 @@ function warnRpIdMoved(domain) {
         'bajo el rpID interino queda invalidada — esos usuarios deben registrar una nueva ' +
         'passkey en el dominio definitivo.');
 }
+/** The go-live without `--client-mail`: say where the mail stays and how to move it. */
+function logSharedMail() {
+    console.log(`  ⏭ correo: se queda en ${sendingDomainOf(PROVISION_EMAIL_FROM)} ` +
+        '(usa `--client-mail` para enviar desde el dominio del cliente)');
+}
+/**
+ * The go-live's mail choice in the state: `sharedMail: true` when the mail stayed on the org
+ * sender, absent when it moved to the client ({@link noVaultMintDomain} reads it).
+ */
+function withMailChoice(dns, clientMail) {
+    const { sharedMail: _previous, ...rest } = dns;
+    return clientMail ? rest : { ...rest, sharedMail: true };
+}
 /**
- * VAULT-002 — re-scope the project's Resend key after the go-live: the key is limited to its
- * sending domain, and `EMAIL_FROM` just moved to `updates.<client>`. Mints a new send-only key
+ * VAULT-002 — re-scope the project's Resend key after a `--client-mail` go-live: the key is
+ * limited to its sending domain, and `EMAIL_FROM` just moved to `updates.<client>`. Mints a new send-only key
  * for the new domain, upserts it into `main:/` (the one copy the other environments reference;
  * skipped without a vault) and into the deploys, records its id, and revokes the previous key.
  *
@@ -5394,12 +5438,17 @@ function goLiveRetryHint(mailDomain) {
     const client = mailDomain.startsWith(prefix) ? mailDomain.slice(prefix.length) : '<tu dominio>';
     return `repite el go-live (\`factory provision --domain=${client}\`)`;
 }
+/** Whether the state records a kit domain in that Railway environment (created, or found by adopt). */
+function hasRailwayKitDomain(state, role) {
+    const rw = state?.railway;
+    return Boolean(rw?.customDomains?.[role] || rw?.adoptedDomains?.some((d) => d.role === role));
+}
 /**
  * Print the resolved client-domain operation tree for `--domain --dry-run`
  * (PROV-006 §8): the exact domain, the DNS route, whether the CNAME is created or
  * printed, the interim-retire intent, and the env updates — mutating NOTHING.
  */
-function printClientDomainPlan(domain, interim, route, confirm, target) {
+function printClientDomainPlan(domain, hosts, route, confirm, target, clientMail = false) {
     console.log(`\nPlan de \`--domain=${domain}\` (ruta DNS: ${route}):`);
     if (target === 'railway') {
         // RWAY-005: the CNAME's destination and the TXT are what Railway returns for the domain.
@@ -5424,17 +5473,27 @@ function printClientDomainPlan(domain, interim, route, confirm, target) {
         }
         console.log(`  … sondea GET /v9/projects/.../domains/${domain} hasta verified:true (o timeout)`);
     }
-    console.log(`  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim} ` +
-        `(el dev ${domain}-dev se conserva)`);
-    console.log(`  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · NEXT_PUBLIC_APP_URL=https://${domain}`);
+    const { interim, dev } = hosts;
+    console.log(interim
+        ? `  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim}` +
+            (dev ? ` (el dev ${dev} se conserva)` : '')
+        : '  · sin dominio interino registrado: no hay nada que retirar');
+    console.log(clientMail
+        ? `  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · NEXT_PUBLIC_APP_URL=https://${domain}`
+        : `  ↻ NEXT_PUBLIC_APP_URL=https://${domain}`);
     console.log(`  ↻ WEBAUTHN_RP_ID=${domain} (production y preview — las passkeys del rpID interino quedan invalidadas) · ` +
         `WEBAUTHN_RELATED_ORIGINS = origen de develop${confirm ? '' : ' (+ el interino si se conserva)'}`);
-    console.log(`  ＋ Resend: POST /domains { name: ${mailDomainFor(domain)} } (subdominio mail, no el apex)`);
-    if (route === 'registrar') {
-        console.log('  · (registrar) los records DNS de Resend (DKIM/SPF/MX) se crean a mano en el dashboard de Resend');
+    if (clientMail) {
+        console.log(`  ＋ Resend: POST /domains { name: ${mailDomainFor(domain)} } (subdominio mail, no el apex)`);
+        if (route === 'registrar') {
+            console.log('  · (registrar) los records DNS de Resend (DKIM/SPF/MX) se crean a mano en el dashboard de Resend');
+        }
+        else {
+            console.log(`  ＋ records DNS de Resend (DKIM/SPF/MX, los que devuelva) en la zona ${apexZoneOf(domain)} + sondeo hasta verified`);
+        }
     }
     else {
-        console.log(`  ＋ records DNS de Resend (DKIM/SPF/MX, los que devuelva) en la zona ${apexZoneOf(domain)} + sondeo hasta verified`);
+        logSharedMail();
     }
     console.log('\n(`--dry-run`) No se ejecutó ninguna llamada a API ni se escribió estado.');
 }
@@ -8867,10 +8926,14 @@ export async function runProvision(flags, deps = {}) {
         result.initialMigration = true;
     }
     if (hasDomain) {
-        result.clientDomain = { domain: flags.domain, route: flags.dns };
+        result.clientDomain = {
+            domain: flags.domain,
+            route: flags.dns,
+            clientMail: flags.clientMail === true,
+        };
     }
     if (flags.services.includes('vault')) {
-        result.vault = buildVaultPlan(projectName, flags.services);
+        result.vault = buildVaultPlan(projectName, flags.services, target);
     }
     if (vaultDecision.skipped) {
         result.vaultSkipped = vaultDecision.skipped;
@@ -8903,8 +8966,12 @@ export async function runProvision(flags, deps = {}) {
             if (hasDomain) {
                 // Same rule as the real retire (DOM-001): the plan must print the interim the
                 // project ACTUALLY has, not one re-derived in the current org zone.
-                const interim = existingProvisionDomains(projectName, state?.dns).prod;
-                printClientDomainPlan(flags.domain, interim, flags.dns, flags.confirm, target);
+                const hosts = existingProvisionDomains(projectName, state?.dns);
+                // Railway records its kit domains by environment: without one there is nothing to retire.
+                const onRailway = target === 'railway';
+                const interim = onRailway && !hasRailwayKitDomain(state, 'main') ? undefined : hosts.prod;
+                const dev = onRailway && !hasRailwayKitDomain(state, 'develop') ? undefined : hosts.dev;
+                printClientDomainPlan(flags.domain, { interim, dev }, flags.dns, flags.confirm, target, flags.clientMail === true);
             }
         }
         return result;
@@ -8915,7 +8982,9 @@ export async function runProvision(flags, deps = {}) {
     const preflight = await runProvisionPreflight({
         services: preflightServices,
         teamId: flags.team,
-        repoSlug: `${FACTORY_ORG}/${projectName}`,
+        // The repo the steps target (state → `--repo` → `origin` → default), never one re-derived
+        // from the slug: a repo named apart from its slug would fail a check the run would pass.
+        ...(repoSlug ? { repoSlug } : {}),
         rootDir,
         ...(target ? { target } : {}),
     }, { rail });
@@ -9110,6 +9179,7 @@ export async function runProvision(flags, deps = {}) {
         const headless = !process.stdin.isTTY;
         await provisionClientDomain(rootDir, runState, flags.team, flags.domain, {
             dnsRoute: flags.dns,
+            clientMail: flags.clientMail === true,
             verifyTimeoutMin: flags.verifyTimeout,
             preConfirmed: flags.confirm,
             headless,

package/dist/lib/vault-api.js

@@ -946,7 +946,10 @@ export function createVaultClient(deps = {}) {
         if (app !== 'railway')
             assertDestination(app);
         const operation = `consultar la conexión de la organización con ${app}`;
-        const body = asObject(ok(await call(operation, 'GET', `/api/v1/app-connections/${app}`), operation));
+        // `/available`, not the bare list: the list needs the org `Read` permission on app
+        // connections, which only admins hold; `/available` needs `Connect` — the same one a sync
+        // needs — and the built-in `member` role has it. With the list, a member got a 403.
+        const body = asObject(ok(await call(operation, 'GET', `/api/v1/app-connections/${app}/available`), operation));
         const connections = asArray(body?.appConnections).flatMap((entry) => {
             const connection = asObject(entry);
             const id = asString(connection?.id);

package/package.json

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