@timekast/factory 1.12.0 → 1.13.0

package/dist/lib/neon-api.js

@@ -0,0 +1,342 @@
+/**
+ * Neon REST API v2 client for `factory provision` (PROV-002).
+ *
+ * A THIN, project-level Neon client that mirrors the proven fetch shape of
+ * `scripts/tools/neon-branch.ts` (`Authorization: Bearer ${apiKey}` +
+ * `https://console.neon.tech/api/v2/...`) — we reuse that shape rather than
+ * reinvent an HTTP client (issue §4, AC5). Where `neon-branch.ts` only creates a
+ * single E2E branch, this client operates at the PROJECT level: create a project
+ * (its primary branch becomes production `main`), create a clean `develop`
+ * branch, read POOLED connection strings, and mint a project-scoped API key.
+ *
+ * Every call surfaces a typed {@link NeonApiError} on a non-2xx response that
+ * carries the HTTP status, so the caller (`provision.ts`) can map the Neon edge
+ * cases the issue calls out (§8) to actionable, es-MX `CLIError` messages:
+ *   - 401  → `NEON_API_KEY` invalid/rotated → re-import the rail (`factory secrets <archivo>`)
+ *   - 402 / 429 → quota / billing          → billing message
+ *   - 409  → project name already exists    → suggest `--force` or another name
+ *
+ * The `fetch` impl is an INJECTABLE seam (`NeonApiDeps.fetchImpl`) so the unit
+ * tests drive endpoint order + payload shape with a mock — the live REST flow is
+ * exercised e2e by PROV-010, never here (issue §7).
+ */
+/** Neon REST v2 base — same host the E2E branch tool uses (`neon-branch.ts`). */
+export const NEON_API_BASE = 'https://console.neon.tech/api/v2';
+/** Timeout (ms) for every Neon REST call — a dead network must not hang provision. */
+const NEON_API_TIMEOUT_MS = 30_000;
+/** Production branch name — the project's primary branch is named/used as this. */
+export const NEON_MAIN_BRANCH = 'main';
+/** Name of the isolated, data-clean second branch this step creates. */
+export const NEON_DEVELOP_BRANCH = 'develop';
+/**
+ * Neon returns 423 (Locked) while a freshly-created project runs its post-create
+ * operations ("project already has running conflicting operations"). The develop
+ * branch create retries with linear backoff until that lock clears.
+ */
+const NEON_LOCK_MAX_RETRIES = 5;
+const NEON_LOCK_BACKOFF_MS = 3_000;
+/**
+ * Default database + owning role Neon auto-creates for an API-provisioned project
+ * (POST /projects without a custom db/role). Stable Neon platform defaults — same
+ * category as the branch-name constants above (a provision convention, NOT org
+ * config). The `connection_uri` endpoint requires both query params.
+ */
+const NEON_DEFAULT_DATABASE = 'neondb';
+const NEON_DEFAULT_ROLE = 'neondb_owner';
+/** A non-2xx response from the Neon REST API. Carries the HTTP status for mapping. */
+export class NeonApiError extends Error {
+    status;
+    /** The raw response body (best-effort) — useful context, never a secret. */
+    body;
+    constructor(status, body, context) {
+        super(`Neon API ${status} en ${context}: ${body || '(sin cuerpo)'}`);
+        this.name = 'NeonApiError';
+        this.status = status;
+        this.body = body;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Shared headers for every Neon REST call (Bearer auth + JSON). */
+function neonHeaders(apiKey) {
+    return {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: '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 '';
+    }
+}
+/**
+ * Create a Neon project. The project is born WITH its primary branch — we name
+ * that branch `main` and use it as production (issue §4: do NOT create an extra
+ * `main` branch). Returns the project id + the primary branch id.
+ *
+ * @throws {NeonApiError} on any non-2xx (caller maps 401/402/409/429 → CLIError).
+ */
+export async function createNeonProject(apiKey, projectName, orgId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/projects`, {
+        method: 'POST',
+        headers: neonHeaders(apiKey),
+        body: JSON.stringify({
+            project: {
+                name: projectName,
+                // org_id targets the project at the org. Neon REQUIRES it when the API key
+                // is org-scoped; omitted when absent so a personal-account key still works.
+                ...(orgId ? { org_id: orgId } : {}),
+                // Name the auto-created primary branch `main` so production reads cleanly.
+                branch: { name: NEON_MAIN_BRANCH },
+            },
+        }),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'POST /projects');
+    }
+    const data = (await response.json());
+    const projectId = data.project?.id;
+    // The create-project response returns the primary branch under `branch`
+    // (and/or the first of `branches`); accept either shape defensively.
+    const mainBranchId = data.branch?.id ?? data.branches?.[0]?.id;
+    if (!projectId || !mainBranchId) {
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /projects (respuesta sin projectId/branchId)');
+    }
+    return { projectId, mainBranchId };
+}
+/**
+ * Create a CLEAN `develop` branch off the project's primary branch. The branch
+ * carries NO snapshot of another project's data — we pass `parent_id` of the
+ * primary `main` (a branch of the SAME new project), which Neon copies as an
+ * empty schema base (issue §4 + §8: not a fork of production data of some other
+ * project; the new project starts empty anyway). A `read_write` endpoint is
+ * attached so the branch is immediately connectable.
+ *
+ * @returns the new `develop` branch id.
+ * @throws {NeonApiError} on any non-2xx.
+ */
+export async function createDevelopBranch(apiKey, projectId, parentBranchId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const postBranch = () => fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/branches`, {
+        method: 'POST',
+        headers: neonHeaders(apiKey),
+        body: JSON.stringify({
+            branch: { name: NEON_DEVELOP_BRANCH, parent_id: parentBranchId },
+            endpoints: [{ type: 'read_write' }],
+        }),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    // Retry on 423 (project locked by post-create operations) with linear backoff.
+    let response = await postBranch();
+    for (let attempt = 0; response.status === 423 && attempt < NEON_LOCK_MAX_RETRIES; attempt++) {
+        await sleep(NEON_LOCK_BACKOFF_MS * (attempt + 1));
+        response = await postBranch();
+    }
+    // Idempotent resume (409): the branch already exists from a prior run that died
+    // before persisting its id, so the resume re-entered here. Reuse the existing
+    // `develop` branch instead of failing — re-running provision must converge.
+    if (response.status === 409) {
+        const existing = await listNeonBranches(apiKey, projectId, deps);
+        const develop = existing.find((b) => b.name === NEON_DEVELOP_BRANCH);
+        if (develop)
+            return develop.id;
+    }
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'POST /projects/{id}/branches (develop)');
+    }
+    const data = (await response.json());
+    const branchId = data.branch?.id;
+    if (!branchId) {
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST branches/develop (respuesta sin branchId)');
+    }
+    return branchId;
+}
+/**
+ * Read a branch's connection string for the requested mode via Neon's
+ * `GET /projects/{id}/connection_uri`:
+ *   - `pooled: true`  → the PgBouncer-pooled URI (the `-pooler` host) for
+ *     serverless/concurrent runtime (the Drizzle Neon pool — sk-db §7).
+ *   - `pooled: false` → the DIRECT URI (no `-pooler`) for single-process
+ *     migrations + tooling (`drizzle-kit migrate`, `db:seed`/`db:query`, local dev).
+ *
+ * The discriminator is serverless/concurrency, NOT "runtime": local `pnpm dev` is
+ * runtime but uses the direct URI (one connection + drizzle-kit wants direct).
+ * Returns the connection string value.
+ *
+ * @throws {NeonApiError} on any non-2xx.
+ */
+export async function getConnectionUri(apiKey, projectId, branchId, pooled, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    // Neon's connection_uri requires database_name + role_name (the project's default
+    // db + owner role). Without them it 400s "database_name not set".
+    const query = new URLSearchParams({
+        branch_id: branchId,
+        database_name: NEON_DEFAULT_DATABASE,
+        role_name: NEON_DEFAULT_ROLE,
+        pooled: pooled ? 'true' : 'false',
+    });
+    const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/connection_uri?${query.toString()}`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /projects/{id}/connection_uri');
+    }
+    const data = (await response.json());
+    if (!data.uri) {
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'GET connection_uri (respuesta sin uri)');
+    }
+    return data.uri;
+}
+/**
+ * List the org's Neon projects — `GET /projects` (PROV-007 `--adopt`). STRICTLY
+ * read-only: it never POSTs/PATCHes/DELETEs. The caller filters by slug/name to
+ * reconstruct the adopted state and disambiguates when more than one matches
+ * (issue §4). Neon paginates with `?limit=`; one page (default 100) covers the
+ * org's project list for the adopt use case.
+ *
+ * @throws {NeonApiError} on any non-2xx (caller records the field as `unknown`).
+ */
+export async function listNeonProjects(apiKey, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/projects`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /projects');
+    }
+    const data = (await response.json());
+    return (data.projects ?? [])
+        .filter((p) => Boolean(p.id) && Boolean(p.name))
+        .map((p) => ({ id: p.id, name: p.name }));
+}
+/**
+ * List a Neon project's branches — `GET /projects/{id}/branches` (PROV-007
+ * `--adopt`). STRICTLY read-only. The caller picks the `develop` branch id to
+ * record in the adopted state.
+ *
+ * @throws {NeonApiError} on any non-2xx (caller records the field as `unknown`).
+ */
+export async function listNeonBranches(apiKey, projectId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/branches`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /projects/{id}/branches');
+    }
+    const data = (await response.json());
+    return (data.branches ?? [])
+        .filter((b) => Boolean(b.id) && Boolean(b.name))
+        .map((b) => ({ id: b.id, name: b.name }));
+}
+/**
+ * Mint a PROJECT-SCOPED Neon API key (issue §4 + plan: the GH secret stores a
+ * project-scoped key, NOT the org key — blast radius is one project's infra).
+ * Neon's `POST /api_keys` with a `project_id` scopes the key to that project.
+ * Returns the key value (the ONE place this value is read — it is handed
+ * straight to `gh secret set` over STDIN, never logged).
+ *
+ * @throws {NeonApiError} on any non-2xx.
+ */
+export async function createProjectApiKey(apiKey, projectId, keyName, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const mint = () => fetchImpl(`${NEON_API_BASE}/api_keys`, {
+        method: 'POST',
+        headers: neonHeaders(apiKey),
+        body: JSON.stringify({ key_name: keyName, project_id: projectId }),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    let response = await mint();
+    // Idempotent resume (409): a key with this name already exists from a prior run
+    // whose value we never persisted (it is a secret — unreadable after creation).
+    // The value can't be reused, so delete the stale key(s) by name and re-mint — a
+    // resume must converge, not 409. (Only the secret-pending path re-enters here;
+    // the happy path sets apiKeySecretDone and short-circuits before minting again.)
+    if (response.status === 409) {
+        await deleteNeonApiKeysByName(apiKey, keyName, { fetchImpl });
+        response = await mint();
+    }
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'POST /api_keys');
+    }
+    const data = (await response.json());
+    if (!data.key) {
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /api_keys (respuesta sin key)');
+    }
+    return data.key;
+}
+/**
+ * Best-effort delete of every account/org API key whose name matches `keyName`
+ * (GET /api_keys → DELETE /api_keys/{id}). Two callers:
+ *   - the idempotent re-mint (clear a stale key before re-minting on resume), and
+ *   - the ephemeral `--destroy` nuke (delete the project-scoped key it minted so
+ *     the org does not accumulate dead keys across provisions/tests).
+ * Returns the count deleted. NEVER throws — a cleanup failure must not abort the
+ * caller (the re-mint surfaces its own error; the destroy already nuked the
+ * project).
+ */
+export async function deleteNeonApiKeysByName(apiKey, keyName, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let deleted = 0;
+    try {
+        const listResp = await fetchImpl(`${NEON_API_BASE}/api_keys`, {
+            method: 'GET',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+        if (!listResp.ok)
+            return 0;
+        const data = (await listResp.json());
+        // Neon returns a bare array; tolerate a `{ api_keys: [...] }` wrapper too.
+        const list = Array.isArray(data) ? data : (data?.api_keys ?? []);
+        const ids = list
+            .filter((k) => k?.name === keyName && k?.id != null)
+            .map((k) => String(k.id));
+        for (const id of ids) {
+            const del = await fetchImpl(`${NEON_API_BASE}/api_keys/${encodeURIComponent(id)}`, {
+                method: 'DELETE',
+                headers: neonHeaders(apiKey),
+                signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+            });
+            if (del.ok || del.status === 404)
+                deleted++;
+        }
+    }
+    catch {
+        // best-effort — never throws; the caller does not depend on cleanup succeeding
+    }
+    return deleted;
+}
+/**
+ * Delete an ENTIRE Neon project — `DELETE /projects/{id}`. `--destroy` calls this
+ * on an `ephemeral` stack to nuke the whole project (not just the `develop`
+ * branch), which is the actual blast radius an ephemeral teardown promises. A 404
+ * means the project is already gone → treated as success (idempotent teardown).
+ * The DEV's key does this, NEVER the shared org create-only key from the rail.
+ *
+ * @throws {NeonApiError} on any non-2xx other than 404.
+ */
+export async function deleteNeonProject(apiKey, projectId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}`, {
+        method: 'DELETE',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (response.ok || response.status === 404)
+        return;
+    throw new NeonApiError(response.status, await safeBody(response), 'DELETE /projects/{id}');
+}

package/dist/lib/preflight.js

@@ -8,15 +8,57 @@
  *
  * Any failure throws a `PreflightError` with an actionable message — never a
  * cryptic spawn error or a stack trace.
+ *
+ * The launcher preflight (`runLauncherPreflight`, LTUI-002) reuses these same
+ * checks but prepends a Node-version gate and, instead of failing fast on the
+ * first throw, returns a structured per-check report so `factory doctor
+ * --launcher` can render every step with ✅ / ❌ across all platforms (the
+ * cross-platform equivalent of the macOS launcher's `checkPrereqs`).
  */
 import { execa } from 'execa';
 import { PreflightError } from './cli-error.js';
 import { FACTORY_ORG } from './constants.js';
+/** Minimum Node major version the kit requires (mirrors `engines.node` + the launcher AppleScript). */
+export const MIN_NODE_MAJOR = 22;
+/** Timeout (ms) for the GitHub API calls in the org-membership check — a slow / dead network must not hang. */
+const GH_API_TIMEOUT_MS = 10_000;
 /** True when the thrown error is execa's "command not found" (ENOENT). */
 function isCommandNotFound(error) {
     const code = error?.code;
     return code === 'ENOENT';
 }
+/** True when the thrown error is execa's timeout (the spawned command was killed for taking too long). */
+function isTimeout(error) {
+    return error?.timedOut === true;
+}
+/**
+ * Parse a Node version string (`process.version`, e.g. `v22.3.1` or `22.3.1`)
+ * into its major number. Returns `NaN` when the string is unparseable.
+ */
+export function parseNodeMajor(version) {
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : NaN;
+}
+/**
+ * Step 0 (launcher only) — the running Node is at least `minMajor` (default 22).
+ *
+ * Reads the version from the running process (`process.version` by default —
+ * always present, the process is already running). Mirrors the launcher
+ * AppleScript's `checkPrereqs` Node gate. `nodeVersion` is injectable so tests
+ * can drive both the pass and the fail branch without spawning a sub-process.
+ *
+ * @throws {PreflightError} when the major is below `minMajor` or unparseable.
+ */
+export function assertNodeVersion(minMajor = MIN_NODE_MAJOR, nodeVersion = process.version) {
+    const major = parseNodeMajor(nodeVersion);
+    if (Number.isNaN(major)) {
+        throw new PreflightError(`No se pudo determinar la versión de Node (\`${nodeVersion}\`).\n` +
+            `Instala Node ${minMajor} o superior desde https://nodejs.org`);
+    }
+    if (major < minMajor) {
+        throw new PreflightError(`Node ${nodeVersion} — requiere ≥ ${minMajor}. Instala Node ${minMajor} o superior desde https://nodejs.org`);
+    }
+}
 /** Step 1 — `gh` is installed on PATH. */
 async function assertGhInstalled() {
     try {
@@ -50,10 +92,16 @@ async function assertGhAuthenticated() {
 async function assertOrgMembership() {
     let login;
     try {
-        const { stdout } = await execa('gh', ['api', '/user', '--jq', '.login']);
+        const { stdout } = await execa('gh', ['api', '/user', '--jq', '.login'], {
+            timeout: GH_API_TIMEOUT_MS,
+        });
         login = stdout.trim();
     }
-    catch {
+    catch (error) {
+        if (isTimeout(error)) {
+            throw new PreflightError('No se pudo verificar tu usuario de GitHub: la API no respondió (¿sin conexión?).\n' +
+                'Revisa tu red y vuelve a intentar.');
+        }
         throw new PreflightError('No se pudo determinar tu usuario de GitHub con `gh api /user`.\n' +
             'Verifica tu sesión con `gh auth status`.');
     }
@@ -61,9 +109,15 @@ async function assertOrgMembership() {
         throw new PreflightError('No se pudo determinar tu usuario de GitHub. Verifica tu sesión con `gh auth status`.');
     }
     try {
-        await execa('gh', ['api', `/orgs/${FACTORY_ORG}/members/${login}`]);
+        await execa('gh', ['api', `/orgs/${FACTORY_ORG}/members/${login}`], {
+            timeout: GH_API_TIMEOUT_MS,
+        });
     }
-    catch {
+    catch (error) {
+        if (isTimeout(error)) {
+            throw new PreflightError(`No se pudo verificar tu membresía en el org \`${FACTORY_ORG}\`: la API no respondió (¿sin conexión?).\n` +
+                'Revisa tu red y vuelve a intentar.');
+        }
         throw new PreflightError(`No se pudo verificar que \`${login}\` sea miembro del org \`${FACTORY_ORG}\`.\n` +
             `Si ya eres miembro, tu token puede carecer del scope \`read:org\` (la membresía privada queda invisible): ejecuta \`gh auth refresh -s read:org\` y vuelve a intentar.\n` +
             `Si no eres miembro, solicita acceso al org \`${FACTORY_ORG}\` o verifica tu sesión con \`gh auth status\`.`);
@@ -78,3 +132,84 @@ export async function runPreflight() {
     await assertGhAuthenticated();
     await assertOrgMembership();
 }
+/** The ordered launcher labels (single source so render + tests agree). */
+const LAUNCHER_LABELS = {
+    node: `Node ≥ ${MIN_NODE_MAJOR}`,
+    gh: 'GitHub CLI (gh) instalado',
+    auth: 'Sesión de GitHub activa',
+    org: `Membresía del org ${FACTORY_ORG}`,
+};
+/** A confirmation message for a passing check (the `ok` branch). */
+const OK_MESSAGES = {
+    node: `Node ${process.version} cumple el mínimo (≥ ${MIN_NODE_MAJOR}).`,
+    gh: 'GitHub CLI (gh) está instalado.',
+    auth: 'Tu sesión de GitHub CLI está activa.',
+    org: `Eres miembro del org ${FACTORY_ORG}.`,
+};
+/**
+ * Run the launcher preflight (LTUI-002): the cross-platform equivalent of the
+ * macOS launcher's `checkPrereqs`. Verifies, IN ORDER:
+ *
+ *   1. Node ≥ 22 (`process.version`).
+ *   2. `gh` installed.
+ *   3. `gh auth status` valid.
+ *   4. Membership in `FACTORY_ORG`.
+ *
+ * Steps 2-4 reuse the SAME functions as `runPreflight()` (no reimplementation of
+ * the org-membership logic — LTUI-002 §6). Unlike `runPreflight`, this does NOT
+ * throw on the first failure: it stops running further checks (each later check
+ * depends on the previous — no auth without gh, no org without auth) but still
+ * RETURNS a full ordered report, marking the checks after the failure as
+ * `skipped`. The caller decides exit code (0 = all ok, 1 = any fail).
+ */
+export async function runLauncherPreflight(deps = {}) {
+    const ghInstalled = deps.ghInstalled ?? assertGhInstalled;
+    const ghAuthenticated = deps.ghAuthenticated ?? assertGhAuthenticated;
+    const orgMembership = deps.orgMembership ?? assertOrgMembership;
+    // The ordered pipeline. Each step is the assertion that throws PreflightError
+    // on failure; the runner turns that into a structured result.
+    const steps = [
+        {
+            id: 'node',
+            run: () => assertNodeVersion(deps.minNodeMajor ?? MIN_NODE_MAJOR, deps.nodeVersion),
+        },
+        { id: 'gh', run: ghInstalled },
+        { id: 'auth', run: ghAuthenticated },
+        { id: 'org', run: orgMembership },
+    ];
+    const results = [];
+    let failed = false;
+    for (const step of steps) {
+        if (failed) {
+            results.push({
+                id: step.id,
+                label: LAUNCHER_LABELS[step.id],
+                status: 'skipped',
+                message: 'Se omitió: depende de un check anterior que falló.',
+            });
+            continue;
+        }
+        try {
+            await step.run();
+            results.push({
+                id: step.id,
+                label: LAUNCHER_LABELS[step.id],
+                status: 'ok',
+                message: OK_MESSAGES[step.id],
+            });
+        }
+        catch (error) {
+            failed = true;
+            const message = error instanceof PreflightError
+                ? error.message
+                : `Falló la verificación (${error?.message ?? 'error desconocido'}).`;
+            results.push({
+                id: step.id,
+                label: LAUNCHER_LABELS[step.id],
+                status: 'fail',
+                message,
+            });
+        }
+    }
+    return results;
+}

package/dist/lib/provision-pointer.js

@@ -0,0 +1,32 @@
+/**
+ * Shared end-pointer for the `new` / `update` success tails (PVSKILL-002).
+ *
+ * `new` and `update` both finish by telling the dev the next step — `/provision` —
+ * to complete the environment setup. The copy lives in `PROVISION_POINTER`
+ * (constants.ts) so it is a single named string; the *gating* (when NOT to print)
+ * lives here so both commands share one rule and it is unit-testable without a real
+ * terminal (`isTTY` is injectable, mirroring `maybeOfferAdopt`).
+ *
+ * Contract (issue §4 AC): print ONLY in the successful flow, AFTER the last step.
+ * The caller is responsible for placing the call after its final success log and
+ * before returning — an error path throws earlier and never reaches it (so error /
+ * Ctrl-C / `--dry-run` aborts naturally skip it). This helper only adds the CI-noise
+ * guard: suppress when running headless (no TTY) under an auto-confirm flag (`--yes`),
+ * which marks a non-interactive launcher / pipeline run.
+ */
+import { PROVISION_POINTER } from './constants.js';
+/**
+ * Print the `/provision` end-pointer unless the run is a headless auto-confirm
+ * (`--yes` AND no TTY) — that combination is a CI / launcher run where the extra
+ * line is noise. An interactive run (TTY) prints even with `--yes`; a plain
+ * headless pipe (no `--yes`) still prints (the message is informative, not a
+ * prompt — issue §8 "output capturado en pipelines").
+ */
+export function printProvisionPointer(opts = {}) {
+    const assumeYes = opts.assumeYes ?? false;
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+    const log = opts.log ?? ((m) => console.log(m));
+    if (assumeYes && !isTTY)
+        return; // headless auto-confirm → suppress (CI noise)
+    log(`\n${PROVISION_POINTER}`);
+}