@timekast/factory 1.11.0 → 1.13.0

package/dist/lib/provision-preflight.js

@@ -0,0 +1,342 @@
+/**
+ * Preflight checks for `factory provision` (PROV-001).
+ *
+ * A DEDICATED preflight, independent of `lib/preflight.ts` (whose scope is the
+ * `new`/`add`/`update` org-membership gate). Provision mutates external infra
+ * (Neon, Vercel, DNS) with the shared org tokens imported into the rail
+ * (`factory secrets <archivo>`, SEC-001), so it must fail CLOSED if any credential
+ * it will use is missing or invalid — BEFORE a single resource is created.
+ *
+ * What is FAIL-CLOSED (aborts with `PreflightError`):
+ *   1. `gh` installed + a valid `gh auth status` session (the git substrate of
+ *      PROV-004 needs it; and it is the org identity that gates the secrets import).
+ *   2. The rail tokens for the requested services are PRESENT in `~/.claude/.env`
+ *      (`VERCEL_TOKEN`, `NEON_API_KEY`, …). Absent → re-run `factory secrets <archivo>`.
+ *   3. `VERCEL_TOKEN` is valid AND team-scoped: `GET /v2/teams/{teamId}` (NOT
+ *      `/v2/user` — a personal token passes `/v2/user` yet 403s on the team).
+ *      401 = invalid token; 403 = valid token without team access — distinct
+ *      messages so the dev knows whether to re-import or check team membership.
+ *
+ * What is OPTIONAL (a WARNING, never an abort — frozen plan decision):
+ *   - `neonctl`. Provision mutates Neon over REST with the rail `NEON_API_KEY`,
+ *     so a missing or un-authenticated `neonctl` is a convenience gap, not a
+ *     blocker (issue §1, §8). Absent → warn with the install hint and continue.
+ *
+ * The token reader, the `fetch`, and the `gh` spawns are all injectable seams so
+ * the unit tests drive every branch (401/403/missing-token/no-gh/no-neonctl)
+ * without touching the real `~/.claude/.env`, the real `gh`, or the network.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { PreflightError } from './cli-error.js';
+/** Timeout (ms) for the Vercel team-check fetch — a dead network must not hang. */
+const VERCEL_API_TIMEOUT_MS = 10_000;
+/** Base URL of the Vercel REST API (named constant — never an inline literal). */
+export const VERCEL_API_BASE = 'https://api.vercel.com';
+/** The gate token each provision service needs present in `~/.claude/.env`. */
+const SERVICE_TOKENS = {
+    neon: 'NEON_API_KEY',
+    vercel: 'VERCEL_TOKEN',
+    // `github` (PROV-004) uses the dev's `gh` session for the substrate AND the
+    // gate `VERCEL_TOKEN` to create the Vercel project; `dns` rides the Cloudflare
+    // token but only when a `--domain` is requested (PROV-005), so it is not gated
+    // at the scaffold stage.
+    github: 'VERCEL_TOKEN',
+    dns: 'CLOUDFLARE_API_TOKEN',
+};
+/** True when the thrown error is execa's "command not found" (ENOENT). */
+function isCommandNotFound(error) {
+    return error?.code === 'ENOENT';
+}
+/** Absolute path to the per-user secrets rail (`~/.claude/.env`). */
+export function defaultEnvPath() {
+    return path.join(homedir(), '.claude', '.env');
+}
+/**
+ * Read the SET of KEY NAMES present in a `KEY=value` rail file — NAMES ONLY, the
+ * value of every line is discarded immediately so a secret never leaves this
+ * function (no-echo discipline, mirrors `secrets.ts`). Split on the FIRST `=`;
+ * comment / blank / no-`=` lines are skipped. A missing file → empty set.
+ *
+ * `envPath` is injectable so tests point at a temp file (or a non-existent path).
+ */
+export function readEnvKeyNames(envPath = defaultEnvPath()) {
+    if (!existsSync(envPath))
+        return new Set();
+    let text;
+    try {
+        text = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return new Set(); // unreadable → treat as "no keys" (preflight will report missing)
+    }
+    const names = new Set();
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (key !== '')
+            names.add(key);
+    }
+    return names;
+}
+/** Step 1a — `gh` is installed on PATH. */
+async function assertGhInstalled(spawn) {
+    try {
+        await spawn('gh', ['--version']);
+    }
+    catch (error) {
+        if (isCommandNotFound(error)) {
+            throw new PreflightError('GitHub CLI (`gh`) no está instalado o no está en el PATH.\n' +
+                'Instálalo desde https://cli.github.com y vuelve a intentar.');
+        }
+        throw new PreflightError('No se pudo ejecutar `gh`. Verifica tu instalación de GitHub CLI (https://cli.github.com).');
+    }
+}
+/** Step 1b — `gh auth status` returns exit 0 (a valid, non-expired session). */
+async function assertGhAuthenticated(spawn) {
+    try {
+        await spawn('gh', ['auth', 'status']);
+    }
+    catch {
+        throw new PreflightError('Tu sesión de GitHub CLI no es válida o expiró.\n' +
+            'Ejecuta `gh auth login` para autenticarte y vuelve a intentar.');
+    }
+}
+/**
+ * Step 1b' — the `gh` token carries the `workflow` scope. The derived scaffold ships
+ * `.github/workflows/*.yml` (ci, e2e, …) and provision generates more (migrate.yml);
+ * GitHub REJECTS an HTTPS push that creates/updates a workflow file unless the OAuth
+ * token has the `workflow` scope ("refusing to allow an OAuth App to create or update
+ * workflow … without `workflow` scope"). Parses `gh auth status` for the scope; the
+ * fix is a one-time `gh auth refresh -h github.com -s workflow`.
+ */
+async function assertGhWorkflowScope(spawn) {
+    let output = '';
+    try {
+        const res = (await spawn('gh', ['auth', 'status']));
+        output = `${res.stdout ?? ''}\n${res.stderr ?? ''}`;
+    }
+    catch {
+        return; // a failed `gh auth status` is already surfaced by assertGhAuthenticated
+    }
+    if (!/\bworkflow\b/.test(output)) {
+        throw new PreflightError('Tu sesión de `gh` no tiene el scope `workflow`, necesario para pushear los archivos\n' +
+            '`.github/workflows/` del scaffold (GitHub rechaza el push sin él).\n' +
+            'Concédelo con:  gh auth refresh -h github.com -s workflow\ny vuelve a intentar.');
+    }
+}
+/**
+ * Step 1c — the target repo EXISTS on GitHub (`gh repo view {owner/repo}`). provision
+ * does NOT create the repo: `factory new` does (`gh repo create`). A missing repo
+ * here means `new` was never run (or the repo was deleted), so we abort with a
+ * pointer to `factory new` instead of letting the `github` step fail on an opaque
+ * `git push` to a non-existent remote. A 404/no-access both surface the same hint.
+ */
+async function assertRepoExists(repoSlug, spawn) {
+    try {
+        await spawn('gh', ['repo', 'view', repoSlug, '--json', 'name']);
+    }
+    catch (error) {
+        // `gh` itself broken was already caught by step 1a; here a failure means the
+        // repo is not viewable (does not exist or no access).
+        if (isCommandNotFound(error))
+            return;
+        const slug = repoSlug.split('/')[1] ?? repoSlug;
+        throw new PreflightError(`El repo \`${repoSlug}\` no existe en GitHub (o no tienes acceso).\n` +
+            `provision liga la infra a un repo que YA existe — créalo primero con \`factory new ${slug}\` ` +
+            '(que hace `gh repo create` + el scaffold) y vuelve a intentar.');
+    }
+}
+/**
+ * Step 2 — the rail tokens for the requested services are present.
+ *
+ * Maps each requested service to its required token (`SERVICE_TOKENS`) and
+ * asserts every one is a key in `~/.claude/.env`. A missing token → fail-closed:
+ * the dev must re-run `factory secrets <archivo>` (SEC-001) to import them. Services
+ * with no required token (e.g. `github`) are skipped.
+ */
+function assertGateTokensPresent(services, present) {
+    const required = new Set();
+    for (const service of services) {
+        const token = SERVICE_TOKENS[service];
+        if (token)
+            required.add(token);
+    }
+    const missing = [...required].filter((token) => !present.has(token));
+    if (missing.length > 0) {
+        throw new PreflightError(`Faltan tokens del archivo de secretos en \`~/.claude/.env\`: ${missing.join(', ')}.\n` +
+            'Ejecuta `factory secrets <archivo>` para bajarlos del archivo de secretos del org y vuelve a intentar.');
+    }
+}
+/**
+ * Optional `neonctl` check — NEVER aborts (frozen plan decision: provision mutates
+ * Neon over REST with the rail `NEON_API_KEY`). Returns a structured report the
+ * caller turns into a warning when `status === 'warn'`:
+ *   - not on PATH         → warn ("install neonctl")
+ *   - on PATH, `me` fails → warn ("run neonctl auth") — issue §8 edge case
+ *   - on PATH + authed    → ok
+ */
+async function checkNeonctlOptional(spawn) {
+    try {
+        await spawn('neonctl', ['--version']);
+    }
+    catch (error) {
+        if (isCommandNotFound(error)) {
+            return {
+                status: 'warn',
+                message: '`neonctl` no está instalado (opcional — provision muta Neon por REST con el `NEON_API_KEY` del archivo de secretos).\n' +
+                    'Si lo quieres para inspección manual: `npm i -g neonctl`.',
+            };
+        }
+        return {
+            status: 'warn',
+            message: 'No se pudo ejecutar `neonctl` (opcional). Continúo con la mutación por REST.',
+        };
+    }
+    // Installed → check it is authenticated (`neonctl me`). Un-authed is still only
+    // a warning: provision does not depend on the neonctl session.
+    try {
+        await spawn('neonctl', ['me']);
+    }
+    catch {
+        return {
+            status: 'warn',
+            message: '`neonctl` está instalado pero no autenticado (opcional).\n' +
+                'Autentícalo con `neonctl auth` si lo quieres para inspección; provision no lo necesita.',
+        };
+    }
+    return { status: 'ok', message: '`neonctl` instalado y autenticado.' };
+}
+/**
+ * Step 3 — `VERCEL_TOKEN` is valid and scoped to `teamId` via `GET /v2/teams/{teamId}`.
+ *
+ * Distinguishes the two failure modes the issue calls out (§8):
+ *   - 401 → the token itself is invalid/expired → re-pull
+ *   - 403 → a valid token WITHOUT access to this team (e.g. a personal-scoped
+ *           token) → check the team id / membership
+ *
+ * Any other non-2xx, or a network/timeout failure, also aborts (fail-closed —
+ * provision must not proceed on an unverifiable token).
+ */
+async function assertVercelTeamAccess(token, teamId, fetchImpl) {
+    const url = `${VERCEL_API_BASE}/v2/teams/${encodeURIComponent(teamId)}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(VERCEL_API_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new PreflightError(`No se pudo verificar el acceso al team de Vercel \`${teamId}\`: la API no respondió (¿sin conexión?).\n` +
+            'Revisa tu red y vuelve a intentar.');
+    }
+    if (response.ok)
+        return; // 2xx → token válido y con acceso al team.
+    if (response.status === 401) {
+        throw new PreflightError('El `VERCEL_TOKEN` es inválido o expiró (Vercel respondió 401).\n' +
+            'Vuelve a bajar los tokens del archivo de secretos con `factory secrets <archivo>` y reintenta.');
+    }
+    if (response.status === 403) {
+        throw new PreflightError(`El \`VERCEL_TOKEN\` no tiene acceso al team \`${teamId}\` (Vercel respondió 403).\n` +
+            'El token es válido pero no alcanza ese team; verifica el `--team` y la membresía del token en el team.');
+    }
+    throw new PreflightError(`No se pudo verificar el team de Vercel \`${teamId}\`: Vercel respondió ${response.status}.\n` +
+        'Reintenta; si persiste, revisa el `--team` y el `VERCEL_TOKEN`.');
+}
+/**
+ * Run the provision preflight (PROV-001). Fail-closed on `gh` / gate tokens /
+ * Vercel team access; returns a `neonctl` report (warning, never fatal). Reusable
+ * by the `provision` command and unit-testable via the injectable deps.
+ *
+ * @throws {PreflightError} when any fail-closed check fails — no resource is
+ *   created (the command runs this BEFORE any mutation).
+ */
+export async function runProvisionPreflight(input, deps = {}) {
+    const spawn = deps.spawn ?? execa;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const envPath = deps.envPath ?? defaultEnvPath();
+    // 1. gh installed + authenticated.
+    await assertGhInstalled(spawn);
+    await assertGhAuthenticated(spawn);
+    // 1c. github-specific gh checks (only when `github` will push): the token carries
+    //     the `workflow` scope (the scaffold + provision push `.github/workflows/*`,
+    //     which GitHub REJECTS without it) AND the target repo exists (provision is
+    //     downstream of `factory new`). Both abort BEFORE any resource is created.
+    if (input.services.includes('github')) {
+        await assertGhWorkflowScope(spawn);
+        if (input.repoSlug)
+            await assertRepoExists(input.repoSlug, spawn);
+    }
+    // 2. Gate tokens for the requested services present in the rail.
+    const present = readEnvKeyNames(envPath);
+    assertGateTokensPresent(input.services, present);
+    // 3. Vercel team-scoped token check — when provisioning Vercel (env sync), GitHub
+    //    (PROV-004 creates the team-scoped Vercel project), OR DNS (PROV-005 attaches
+    //    the interim domains to the team-scoped project).
+    if (input.services.includes('vercel') ||
+        input.services.includes('github') ||
+        input.services.includes('dns')) {
+        if (!input.teamId) {
+            throw new PreflightError('Falta `--team=<teamId>`: el provision de Vercel/GitHub/DNS requiere el team del org.\n' +
+                'Pásalo como `factory provision --services=github,vercel,dns --team=team_xxx`.');
+        }
+        const token = readVercelToken(envPath);
+        if (!token) {
+            // Defensive: step 2 already asserted presence, but guard the read path.
+            throw new PreflightError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
+                'Ejecuta `factory secrets <archivo>` y vuelve a intentar.');
+        }
+        await assertVercelTeamAccess(token, input.teamId, fetchImpl);
+    }
+    // 4. Optional neonctl — never fatal; surfaced as a warning by the caller.
+    const neonctl = await checkNeonctlOptional(spawn);
+    return { neonctl };
+}
+/**
+ * Read the VALUE of `VERCEL_TOKEN` from the rail (the team-check needs the value,
+ * not just the name). Split on the FIRST `=`; strip a single matched pair of
+ * surrounding quotes (the rail may store quoted values — `env-merge.ts`
+ * preserves them). Returns `null` when absent/unreadable.
+ *
+ * This is the ONE place a token VALUE is read; it is handed straight to the
+ * Authorization header and never logged.
+ */
+export function readVercelToken(envPath = defaultEnvPath()) {
+    if (!existsSync(envPath))
+        return null;
+    let text;
+    try {
+        text = readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    for (const line of text.split('\n')) {
+        const trimmed = line.trimStart();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (key !== 'VERCEL_TOKEN')
+            continue;
+        let value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        return value === '' ? null : value;
+    }
+    return null;
+}