@timekast/factory 1.12.0 → 1.14.2

package/dist/lib/vercel-env.js

@@ -0,0 +1,490 @@
+/**
+ * Vercel REST helper for `factory provision` (PROV-003).
+ *
+ * A THIN, reusable Vercel Environment-Variables client that mirrors the proven
+ * fetch shape of `provision-preflight.ts` (`Authorization: Bearer ${token}` +
+ * `https://api.vercel.com/...`). Its single non-negotiable contract: EVERY call
+ * to the Vercel API carries `?teamId={teamId}`. A Vercel project that lives in a
+ * Pro team 403s any env-var call made WITHOUT the team scope (the resource is on
+ * the team, not the personal account), so `teamId` is threaded into one central
+ * URL builder — there is no code path here that hits Vercel without it.
+ *
+ * What this module does NOT do:
+ *   - Create the Vercel PROJECT — that is PROV-004 (`projectId` arrives via the
+ *     provision state, or the caller is told PROV-004 must run first).
+ *   - 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).
+ *
+ * Per-target push (issue §4): production-only secrets push to `["production"]`,
+ * preview/develop ones to `["preview"]`, and shared values to both. `AUTH_SECRET`
+ * is minted INDEPENDENTLY per environment (`randomBytes(32).toString('hex')`) —
+ * 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
+ * reaches stdout. The public surface returns only KEY NAMES + targets; values
+ * live solely inside the request bodies handed to `fetchImpl`.
+ *
+ * `fetchImpl` is an injectable seam so the unit tests drive endpoint order +
+ * payload shape (and assert the `?teamId=` invariant on every URL) with a mock —
+ * the live REST flow is exercised e2e by PROV-010, never here (issue §7).
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+/** Base URL of the Vercel REST API (named constant — never an inline literal). */
+export const VERCEL_API_BASE = 'https://api.vercel.com';
+/** Timeout (ms) for every Vercel REST call — a dead network must not hang provision. */
+const VERCEL_API_TIMEOUT_MS = 30_000;
+/** Directory (repo-root relative) Vercel's project link lives in. */
+export const VERCEL_DIR = '.vercel';
+/** Filename of the Vercel project-link document inside {@link VERCEL_DIR}. */
+export const VERCEL_PROJECT_FILE = 'project.json';
+/** A non-2xx response from the Vercel REST API. Carries the HTTP status for mapping. */
+export class VercelApiError extends Error {
+    status;
+    /** The raw response body (best-effort) — useful context, never a secret. */
+    body;
+    constructor(status, body, context) {
+        super(`Vercel API ${status} en ${context}: ${body || '(sin cuerpo)'}`);
+        this.name = 'VercelApiError';
+        this.status = status;
+        this.body = body;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Raised when `POST /v9/projects/{id}/link` 403s because Vercel's GitHub App is
+ * NOT installed on the org/repo (issue §8). It is NOT a hard failure: the caller
+ * prints the install URL and pauses with an HITL checkpoint, then the dev re-runs
+ * with `--resume` after installing the app. A subclass of {@link VercelApiError}
+ * so it still carries the 403 status for any generic handler.
+ */
+export class GitHubAppNotInstalledError extends VercelApiError {
+    constructor(body, context) {
+        super(403, body, context);
+        this.name = 'GitHubAppNotInstalledError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Build the shared headers for every Vercel REST call (Bearer auth + JSON). */
+function vercelHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+    };
+}
+/** Read a response body as text (best-effort) for error context — never throws. */
+async function safeBody(response) {
+    try {
+        return (await response.text()).slice(0, 500);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Build a Vercel API URL with `teamId` ALWAYS threaded in. This is the ONE place
+ * a Vercel URL is assembled, so the `?teamId=` invariant cannot be forgotten on
+ * any call — extra query params are merged in alongside it.
+ */
+export function vercelUrl(pathname, teamId, extraQuery = {}) {
+    const query = new URLSearchParams({ teamId, ...extraQuery });
+    return `${VERCEL_API_BASE}${pathname}?${query.toString()}`;
+}
+/**
+ * Make an authenticated Vercel API call. `teamId` is threaded into the URL by
+ * {@link vercelUrl} for EVERY method — a personal-account call (no team) would
+ * 403 on a team-owned project. Surfaces a typed {@link VercelApiError} on non-2xx.
+ */
+async function vercelApi(method, pathname, token, teamId, deps, body, extraQuery) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = vercelUrl(pathname, teamId, extraQuery);
+    const init = {
+        method,
+        headers: vercelHeaders(token),
+        signal: AbortSignal.timeout(VERCEL_API_TIMEOUT_MS),
+    };
+    if (body !== undefined)
+        init.body = JSON.stringify(body);
+    const response = await fetchImpl(url, init);
+    if (!response.ok) {
+        throw new VercelApiError(response.status, await safeBody(response), `${method} ${pathname}`);
+    }
+    // A 204 (no body) is valid for DELETE/PATCH — tolerate an empty body.
+    try {
+        return await response.json();
+    }
+    catch {
+        return {};
+    }
+}
+/** Framework Vercel records for a derived project — the kit is always Next.js. */
+export const VERCEL_FRAMEWORK = 'nextjs';
+/**
+ * Create the Vercel PROJECT (PROV-004 — `POST /v9/projects?teamId=`). The create
+ * body is MINIMAL — `name`, `framework: nextjs`, and the GitHub `gitRepository`
+ * link. Vercel's `POST /v9/projects` REJECTS the project SETTINGS as "additional
+ * properties" (`productionBranch`, `autoExposeSystemEnvs`, `ssoProtection`), so
+ * those are applied AFTER create via {@link patchProjectSettings} (best-effort).
+ *
+ * @throws {VercelApiError} on any non-2xx (caller maps 401/402/403/409/429).
+ */
+export async function createVercelProject(token, teamId, input, deps = {}) {
+    const data = (await vercelApi('POST', '/v9/projects', token, teamId, deps, {
+        name: input.name,
+        framework: VERCEL_FRAMEWORK,
+        gitRepository: { type: 'github', repo: input.repo },
+    }));
+    if (!data.id) {
+        throw new VercelApiError(201, JSON.stringify(data).slice(0, 500), 'POST /v9/projects (respuesta sin id)');
+    }
+    return { projectId: data.id };
+}
+/**
+ * Connect the GitHub repo to the Vercel project (PROV-004 — `POST
+ * /v9/projects/{id}/link?teamId=`). Vercel's GitHub App must be installed on the
+ * org/repo first; if it is not, Vercel 403s — surfaced as a typed
+ * {@link GitHubAppNotInstalledError} so the caller can show the install URL and
+ * pause (HITL) instead of aborting (issue §8). Any OTHER non-2xx is a plain
+ * {@link VercelApiError}.
+ */
+export async function linkGitRepo(projectId, token, teamId, repo, deps = {}) {
+    try {
+        await vercelApi('POST', `/v9/projects/${encodeURIComponent(projectId)}/link`, token, teamId, deps, {
+            type: 'github',
+            repo,
+        });
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 403) {
+            throw new GitHubAppNotInstalledError(error.body, `POST /v9/projects/${encodeURIComponent(projectId)}/link`);
+        }
+        throw error;
+    }
+}
+/**
+ * Apply the project SETTINGS via `PATCH /v9/projects/{id}?teamId=` — the kit's
+ * contract that `POST /v9/projects` refuses at create time:
+ *   - `ssoProtection: null`        — preview deployments must be PUBLIC (issue §4)
+ *   - `autoExposeSystemEnvs: true` — the env pill reads VERCEL_GIT_* (branch+sha)
+ *
+ * `productionBranch` is NOT sent here: it is not a property of this endpoint —
+ * Vercel 400s with "should NOT have additional property `productionBranch`", and
+ * that rejection drops the whole PATCH (so `ssoProtection`/`autoExposeSystemEnvs`
+ * silently never apply). The git link already tracks the repo's default branch
+ * (`main`) as production, so confirming it here is both redundant and invalid.
+ *
+ * The CALLER treats this as NON-FATAL: a rejected setting must not abort the
+ * whole provision.
+ *
+ * @throws {VercelApiError} on any non-2xx (the caller catches + warns).
+ */
+export async function patchProjectSettings(projectId, token, teamId, deps = {}) {
+    await vercelApi('PATCH', `/v9/projects/${encodeURIComponent(projectId)}`, token, teamId, deps, {
+        ssoProtection: null,
+        autoExposeSystemEnvs: true,
+    });
+}
+/**
+ * Read the NUMERIC GitHub repo id Vercel recorded when the project was linked
+ * (`GET /v9/projects/{id}` → `link.repoId`). A git deployment's `gitSource` needs
+ * this numeric id, NOT the `owner/name` slug. Returns `null` when the project is
+ * not git-linked yet, so the caller skips the first-deployment trigger instead of
+ * throwing.
+ *
+ * @throws {VercelApiError} on any non-2xx (the caller catches + warns).
+ */
+export async function getLinkedRepoId(projectId, token, teamId, deps = {}) {
+    const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}`, token, teamId, deps));
+    const repoId = data.link?.repoId;
+    return typeof repoId === 'number' ? repoId : null;
+}
+/**
+ * Trigger the FIRST git deployment for ONE branch (`POST /v13/deployments`).
+ * provision links the repo to the Vercel project AFTER `factory new`/provision
+ * already pushed `main` + `develop`, so Vercel never receives a push event and
+ * builds NOTHING — the project sits at 0 deployments. This fires the build
+ * explicitly from a git ref.
+ *
+ * `production: true` (the `main` branch) sends `target: 'production'`; `develop`
+ * omits it, so Vercel files it as a PREVIEW deployment — the kit contract
+ * (production ← main, preview ← develop). Returns as soon as the deployment is
+ * QUEUED; it does NOT wait for the build (minutes), mirroring the domain-SSL
+ * non-wait.
+ *
+ * @throws {VercelApiError} on any non-2xx (the caller treats it as NON-FATAL —
+ * the project + env are already provisioned, a build failure must not abort).
+ */
+export async function triggerDeployment(token, teamId, input, deps = {}) {
+    const body = {
+        name: input.name,
+        project: input.projectId,
+        gitSource: { type: 'github', repoId: input.repoId, ref: input.ref },
+    };
+    if (input.production)
+        body.target = 'production';
+    await vercelApi('POST', '/v13/deployments', token, teamId, deps, body);
+}
+/**
+ * Attach a domain to the Vercel project — `POST /v9/projects/{id}/domains?teamId=`
+ * (PROV-005, issue §4). The DEV domain (`{slug}-dev.timekast.mx`) carries
+ * `gitBranch: 'develop'` so Vercel routes the develop branch's preview to it; the
+ * PROD domain (`{slug}.timekast.mx`) is sent WITHOUT `gitBranch`, which makes it a
+ * production domain. The shape difference is the whole point — the unit test
+ * asserts the dev body has `gitBranch: 'develop'` and the prod body has none.
+ *
+ * Idempotency (issue §8): a domain already attached to the project returns 409.
+ * That is NOT an error — provision is resumable, so a 409 resolves to a no-op and
+ * this returns `'exists'` instead of throwing. Any OTHER non-2xx is a typed
+ * {@link VercelApiError} the caller maps. SSL provisioning by Vercel can take
+ * minutes; this call does NOT wait for it (issue §8) — it only registers the
+ * domain and returns; the e2e flow (PROV-010) waits for the cert.
+ *
+ * @throws {VercelApiError} on any non-2xx EXCEPT 409 (which → `'exists'`).
+ */
+export async function addVercelDomain(projectId, token, teamId, input, deps = {}) {
+    const body = { name: input.name };
+    // Only the DEV domain carries gitBranch; the prod domain MUST omit it.
+    if (input.gitBranch)
+        body.gitBranch = input.gitBranch;
+    try {
+        await vercelApi('POST', `/v9/projects/${encodeURIComponent(projectId)}/domains`, token, teamId, deps, body);
+        return 'added';
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 409) {
+            // Already attached (resume / re-run) — idempotent, continue (issue §8).
+            return 'exists';
+        }
+        throw error;
+    }
+}
+/**
+ * Read a single domain's verification status — `GET
+ * /v9/projects/{id}/domains/{name}?teamId=` (PROV-006, issue §4). The provision
+ * verification loop polls this until `verified: true`; the `verification` array
+ * carries the exact records the owner must create when the domain is not yet
+ * verified (the `--dns=registrar` manual path prints them).
+ *
+ * @throws {VercelApiError} on any non-2xx (caller maps it).
+ */
+export async function getVercelDomainStatus(projectId, name, token, teamId, deps = {}) {
+    const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(name)}`, token, teamId, deps));
+    return {
+        verified: data.verified === true,
+        verification: data.verification ?? [],
+    };
+}
+/**
+ * Remove a domain from the Vercel project — `DELETE
+ * /v9/projects/{id}/domains/{name}?teamId=` (PROV-006, issue §4). Used ONLY to
+ * retire an interim prod domain (`{slug}.timekast.mx`) AFTER the client domain
+ * verifies, and ONLY with the dev's explicit confirmation (the caller gates it).
+ *
+ * Idempotency (issue §8): a 404 (the domain is already gone) is NOT an error —
+ * it resolves to `'absent'` so a re-run is a no-op. Any OTHER non-2xx is a typed
+ * {@link VercelApiError} the caller treats as a non-fatal warning (the interim
+ * domain stays attached, never aborts the run).
+ *
+ * @throws {VercelApiError} on any non-2xx EXCEPT 404 (which → `'absent'`).
+ */
+export async function removeVercelDomain(projectId, name, token, teamId, deps = {}) {
+    try {
+        await vercelApi('DELETE', `/v9/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(name)}`, token, teamId, deps);
+        return 'removed';
+    }
+    catch (error) {
+        if (error instanceof VercelApiError && error.status === 404) {
+            return 'absent';
+        }
+        throw error;
+    }
+}
+/**
+ * List the team's Vercel projects — `GET /v9/projects?teamId=&limit=20` (PROV-007
+ * `--adopt`). STRICTLY read-only: it never POSTs/PATCHes/DELETEs anything. The
+ * caller filters the returned summaries by slug/name to reconstruct the adopted
+ * state; an exact-name match is preferred, but every project name that CONTAINS
+ * the slug is returned as a candidate so the caller can disambiguate (issue §4).
+ *
+ * `limit` is threaded as a query param (default 20 — issue §6); `teamId` flows
+ * through {@link vercelUrl} like every other call. Used by `--adopt` only.
+ *
+ * @throws {VercelApiError} on any non-2xx (caller maps it / records `unknown`).
+ */
+export async function listVercelProjects(token, teamId, deps = {}, limit = 20) {
+    const data = (await vercelApi('GET', '/v9/projects', token, teamId, deps, undefined, {
+        limit: String(limit),
+    }));
+    return (data.projects ?? [])
+        .filter((p) => Boolean(p.id) && Boolean(p.name))
+        .map((p) => ({ id: p.id, name: p.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
+ * the response value-free where Vercel allows it — we only ever read `id`/`key`/
+ * `target`, never the stored value.
+ */
+export async function listEnvVars(projectId, token, teamId, deps = {}) {
+    const data = (await vercelApi('GET', `/v9/projects/${encodeURIComponent(projectId)}/env`, token, teamId, deps));
+    return data.envs ?? [];
+}
+/**
+ * Idempotently set ONE env var for its targets (issue §4 + §8). If an existing
+ * var already covers any of the requested targets, it is PATCHed
+ * (`/v10/projects/{id}/env/{envId}`); otherwise it is POSTed
+ * (`/v10/projects/{id}/env`). Either way the call threads `?teamId=`.
+ *
+ * Matching is by `key` + target overlap — a var pushed for `production` does not
+ * clobber the same key's `preview` entry (they are distinct Vercel env records,
+ * which is exactly how `AUTH_SECRET` can differ per environment).
+ */
+export async function upsertEnvVar(projectId, token, teamId, plan, existing, deps = {}) {
+    const match = existing.find((e) => e.key === plan.key && (e.target ?? []).some((t) => plan.target.includes(t)));
+    if (match) {
+        await vercelApi('PATCH', `/v10/projects/${encodeURIComponent(projectId)}/env/${encodeURIComponent(match.id)}`, token, teamId, deps, {
+            value: plan.value,
+            target: plan.target,
+            type: 'encrypted',
+        });
+        return 'updated';
+    }
+    await vercelApi('POST', `/v10/projects/${encodeURIComponent(projectId)}/env`, token, teamId, deps, {
+        key: plan.key,
+        value: plan.value,
+        target: plan.target,
+        type: 'encrypted',
+    });
+    return 'created';
+}
+/**
+ * Generate a fresh, cryptographically-random `AUTH_SECRET` (issue §4: prod and
+ * preview MUST be distinct). `randomBytes(32)` → 64 hex chars (≥32). Called once
+ * per environment, so two calls return two different values.
+ */
+export function generateAuthSecret() {
+    return randomBytes(32).toString('hex');
+}
+/** Absolute path to `.vercel/project.json` under a repo root. */
+export function vercelProjectPath(rootDir) {
+    return path.join(rootDir, VERCEL_DIR, VERCEL_PROJECT_FILE);
+}
+/**
+ * Read an existing `.vercel/project.json`, returning its `projectId` (best-effort)
+ * or `null` when absent/unparsable. Used by {@link writeVercelProjectJson} to
+ * detect a directory being reused with a DIFFERENT project (issue §8).
+ */
+export function readVercelProjectId(rootDir) {
+    const file = vercelProjectPath(rootDir);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof parsed.projectId === 'string' ? parsed.projectId : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write `.vercel/project.json` with `{ projectId, orgId, teamId }` — WITHOUT ever
+ * running `vercel link`/`vercel pull` (SK.md §7.1: those overwrite `.env.local`
+ * and have locked devs out). The write is atomic (temp file + `renameSync`), so a
+ * kill mid-write leaves the previous link intact.
+ *
+ * Reuse guard (issue §8): if a link already exists for a DIFFERENT `projectId`,
+ * the dev may be reusing the directory. Without `force`, this throws a `CLIError`
+ * pointing at `--force` (headless-safe: a clear failure, never a silent clobber).
+ */
+export function writeVercelProjectJson(rootDir, link, options = {}) {
+    const existingProjectId = readVercelProjectId(rootDir);
+    if (existingProjectId && existingProjectId !== link.projectId && !options.force) {
+        throw new CLIError(`Ya existe \`${VERCEL_DIR}/${VERCEL_PROJECT_FILE}\` apuntando a otro proyecto Vercel ` +
+            `(\`${existingProjectId}\` ≠ \`${link.projectId}\`).\n` +
+            'Usa `--force` para sobrescribir el link, o elimina el archivo si reutilizas este directorio.');
+    }
+    const dir = path.join(rootDir, VERCEL_DIR);
+    mkdirSync(dir, { recursive: true });
+    const target = vercelProjectPath(rootDir);
+    const tmp = path.join(dir, `.${VERCEL_PROJECT_FILE}.tmp`);
+    const body = `${JSON.stringify({
+        projectId: link.projectId,
+        orgId: link.orgId,
+        teamId: link.teamId,
+    }, null, 2)}\n`;
+    try {
+        writeFileSync(tmp, body, 'utf8');
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw new CLIError(`No se pudo escribir \`${VERCEL_DIR}/${VERCEL_PROJECT_FILE}\`: ` +
+            `${error?.message ?? 'error desconocido'}.`);
+    }
+}
+/**
+ * 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.
+ */
+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).
+        { key: 'AUTH_SECRET', value: input.authSecretProd, target: ['production'] },
+        { key: 'AUTH_SECRET', value: input.authSecretPreview, target: ['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'] },
+    ];
+    for (const [key, value] of Object.entries(input.shared ?? {})) {
+        if (!value)
+            continue; // skip empty shared values
+        plan.push({ key, value, target: ['production', 'preview'] });
+    }
+    return plan;
+}
+/**
+ * Push an env-var plan to a Vercel project, idempotently and per-target, with
+ * `?teamId=` on EVERY call (issue §4). Lists existing vars ONCE up front, then
+ * upserts each plan entry. Returns KEY NAMES + targets only (no-echo): a secret
+ * value never crosses this boundary back to the caller, so it can never be logged.
+ *
+ * @throws {VercelApiError} on any non-2xx (the caller maps it to a `CLIError`).
+ */
+export async function pushEnvPlan(projectId, token, teamId, plan, deps = {}) {
+    const existing = await listEnvVars(projectId, token, teamId, deps);
+    const result = { created: [], updated: [] };
+    // Track records we create during this run so a second plan entry for the same
+    // key+target (shouldn't happen, but defensive) PATCHes instead of duplicating.
+    const live = [...existing];
+    for (const entry of plan) {
+        const outcome = await upsertEnvVar(projectId, token, teamId, entry, live, deps);
+        if (outcome === 'created') {
+            result.created.push({ key: entry.key, target: entry.target });
+            live.push({
+                id: `pending-${entry.key}-${entry.target.join('-')}`,
+                key: entry.key,
+                target: entry.target,
+            });
+        }
+        else {
+            result.updated.push({ key: entry.key, target: entry.target });
+        }
+    }
+    return result;
+}

package/dist/tui/index.js

@@ -0,0 +1,8 @@
+/**
+ * `cli/src/tui` — interactive terminal UI for the `factory` binary.
+ *
+ * Re-exports the public surface so callers import from `../tui/index.js`
+ * (the barrel) rather than reaching into individual modules.
+ */
+export { runTuiMenu } from './menu.js';
+export { provisionFlow, buildEphemeralFlags, validateSlug, TUI_PROVISION_SERVICES, TUI_PROVISION_DEFAULT_SERVICES, } from './provision-flow.js';

package/dist/tui/menu.js

@@ -0,0 +1,135 @@
+/**
+ * `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.
+ * No OS branching: one binary serves Mac, Windows and Linux.
+ *
+ * Edge cases this module owns:
+ *   · No TTY (CI / pipe): `process.stdout.isTTY` is falsy → degrade to printing
+ *     HELP and return; never block waiting for input that can't arrive.
+ *   · SIGINT / cancel (Ctrl+C / Esc): `prompts` `onCancel` → clean `exit(0)`,
+ *     no stack trace.
+ *   · Aprovisionar (ephemeral) delegates to the PROV-009 sub-flow
+ *     (`provision-flow.ts`) — an ephemeral-only, cross-platform provision; the
+ *     menu never reaches a destructive or live path.
+ *
+ * `factory -h` / `--help` still print HELP — those are handled in `index.ts`
+ * before this menu is ever reached, so this path is genuinely "no args".
+ */
+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 { provisionFlow } from './provision-flow.js';
+/** Prompt for the top-level action. Returns `undefined` if the user cancels. */
+async function promptAction() {
+    const { action } = await prompts({
+        type: 'select',
+        name: 'action',
+        message: 'TimeKast Factory — ¿qué quieres hacer?',
+        choices: [
+            { title: 'Nuevo proyecto', value: 'new' },
+            { title: 'Actualizar proyecto', value: 'update' },
+            { title: 'Aprovisionar (ephemeral)', value: 'provision' },
+            { title: 'Secrets', value: 'secrets' },
+        ],
+        initial: 0,
+    }, { onCancel: () => true } // let the value come back undefined; we exit cleanly below
+    );
+    return action;
+}
+/** Sub-flow: gather a project name + profile, then delegate to `runNew`. */
+async function dispatchNew(deps) {
+    const { name } = await prompts({
+        type: 'text',
+        name: 'name',
+        message: '¿Cómo se va a llamar el proyecto?',
+    }, { onCancel: () => true });
+    if (!name || typeof name !== 'string' || name.trim() === '') {
+        // Cancel or empty name — back out cleanly, no error.
+        return;
+    }
+    const { profile } = await prompts({
+        type: 'select',
+        name: 'profile',
+        message: `¿Qué quieres crear para «${name.trim()}»?`,
+        choices: [
+            { title: 'App completa (starter kit + cerebro)', value: '--full' },
+            { title: 'Solo el cerebro', value: '--core' },
+        ],
+        initial: 0,
+    }, { onCancel: () => true });
+    if (!profile) {
+        return;
+    }
+    await deps.newProject(name.trim(), parseNewFlags([profile]));
+}
+/** Sub-flow: refresh the brain of the current repo via `runUpdate`. */
+async function dispatchUpdate(deps) {
+    await deps.updateProject(parseUpdateFlags([]));
+}
+/**
+ * Sub-flow: Aprovisionar (ephemeral). Delegates to the PROV-009 provision flow,
+ * which gathers the slug (+ team/services), runs `--dry-run` first, confirms, and
+ * only then runs the real `--ephemeral` provision. Strictly ephemeral-only — the
+ * menu never exposes `--destroy`/`--force`/live from here.
+ */
+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`).
+ *
+ * @param deps Injectable seams (TTY flag, HELP printer, command dispatchers).
+ *             Defaults wire the real commands and `process.stdout.isTTY`.
+ */
+export async function runTuiMenu(deps = {}) {
+    const isTTY = deps.isTTY ?? Boolean(process.stdout.isTTY);
+    const printHelp = deps.printHelp ?? (() => { });
+    const newProject = deps.newProject ?? runNew;
+    const updateProject = deps.updateProject ?? runUpdate;
+    const secrets = deps.secrets ?? secretsCommand;
+    const provision = deps.provision ?? provisionFlow;
+    // No TTY (CI / pipe): can't read interactive input. Degrade to HELP and return
+    // immediately — never hang waiting for input that can't arrive.
+    if (!isTTY) {
+        printHelp();
+        return;
+    }
+    const action = await promptAction();
+    // Cancel (Ctrl+C / Esc): `prompts` returns no value. Exit cleanly, no trace.
+    if (action === undefined) {
+        process.exit(0);
+    }
+    switch (action) {
+        case 'new':
+            await dispatchNew({ newProject });
+            return;
+        case 'update':
+            await dispatchUpdate({ updateProject });
+            return;
+        case 'provision':
+            await dispatchProvision({ provision });
+            return;
+        case 'secrets':
+            await dispatchSecrets({ secrets });
+            return;
+    }
+}