@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/railway-api.js

@@ -0,0 +1,851 @@
+/**
+ * Railway API client (RWAY-002) — the ONLY place where the CLI talks to Railway's public GraphQL
+ * API. Railway's own CLI does not serve agents (it aborts asking for `railway setup agent`), so
+ * everything goes through `https://backboard.railway.com/graphql/v2` with `RAILWAY_TOKEN`, the org's
+ * TEAM token, read from the rail with `rail.ts` (`fx-secrets-vault §5`) — never from `process.env`
+ * nor from a file.
+ *
+ * WHAT IT FINDS BY: a Railway project is found by the REPO IT HAS CONNECTED (`source.repo` of a
+ * service instance, `owner/name`, case-insensitive) — {@link RailwayClient.findByConnectedRepo}.
+ * Names do not match repos in practice (`constela` ↔ `TimeKast/constela_front`), and one repo can be
+ * connected to several projects (one per client deploy). The single lookup by exact name is the
+ * RESUME of an alta the kit itself started, inside the deduced workspace, before the repo is
+ * connected ({@link RailwayClient.createProject} with `adoptByName`, and
+ * {@link RailwayClient.findProjectInWorkspaceByName}); it never adopts a stranger's project: without
+ * the caller's explicit `adoptByName`, or when the project does not have the kit's shape, it stops
+ * with {@link RailwayNameTakenError}, which points at `factory provision --adopt --force --target=railway`.
+ *
+ * 🔴 WRITES NO VARIABLES. In Railway the only writer of variables is the vault's sync
+ * (`fx-secrets-vault §7`, one writer per destination). This module exposes no mutation that writes
+ * them, and the service creation never forwards a `variables` field, even if a caller forces one in.
+ * Reads exist only for the inventory, the drift (names + hashes) and the wait for names.
+ *
+ * 🔴 NO-ECHO — the token never reaches stdout/stderr (this module writes to neither), an error, a
+ * URL or a child's argv: it travels only in the Authorization header built by the transport. A
+ * GraphQL error message is forwarded only after checking it carries no fragment of the token (its
+ * full value, first 8 or last 4 characters); if it does, the message is dropped. No error carries a
+ * `cause`, and the transport's own failures are rebuilt without their message.
+ *
+ * 🔴 FAIL-CLOSED UNDER TESTS — the same marker as `vault-api.ts` (`VAULT_TEST_ISOLATION_KEY`, set on
+ * `globalThis` by `cli/tests/setup/isolate-home-path.ts`): while present, a client without an
+ * injected transport THROWS on its first call, before reading the token or touching the network.
+ * `globalThis`, not `process.env.VITEST`: a CLI spawned by a test inherits the env var and would turn
+ * a real run into a refusal.
+ *
+ * The schema this client assumes (mutation inputs, the deployment-state enum, the fields it reads)
+ * is pinned by a dated introspection extract, `cli/tests/fixtures/railway-schema-2026-09-23.json`;
+ * the unit test validates every document below against it. That proves consistency against a
+ * photograph, not against the live API — the live schema is the rollout's to confirm.
+ */
+import { CLIError } from './cli-error.js';
+import { readRailSecret } from './rail.js';
+import { VAULT_TEST_ISOLATION_KEY } from './vault-api.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Railway's public GraphQL endpoint (`fx-secrets-vault §5`: its CLI does not serve agents). */
+export const RAILWAY_GRAPHQL_URL = 'https://backboard.railway.com/graphql/v2';
+/** Name of the rail key that carries the org's Railway team token. */
+export const RAILWAY_TOKEN_KEY = 'RAILWAY_TOKEN';
+/** Time budget (ms) per API call. */
+export const RAILWAY_API_TIMEOUT_MS = 30_000;
+/** Hard stop on the project pagination — far past any team. */
+export const RAILWAY_MAX_PAGES = 50;
+/** How many recent deployments a commit is looked for in. */
+export const RAILWAY_DEPLOYMENTS_PAGE = 20;
+/** The provider a branch trigger is created with (the kit only connects GitHub repos). */
+export const RAILWAY_TRIGGER_PROVIDER = 'github';
+/**
+ * The name of the ONE service the kit creates in a Railway project (`provision --target=railway`).
+ * Part of the kit's shape, read differently by its two users: `--destroy`'s proof of ownership
+ * requires the recorded service to be `web` with ≥1 instance and no source (or some service to
+ * deploy `origin`); resuming an own alta by name ({@link CreateProjectOptions.adoptByName}) is
+ * looser — any service it finds must be `web`, but zero services, or `web` with zero instances, is
+ * accepted. See {@link CreateProjectOptions} for why the two differ.
+ */
+export const RAILWAY_SERVICE_NAME = 'web';
+/** Shortest commit prefix accepted to find a deployment (shorter prefixes collide). */
+const MIN_COMMIT_PREFIX = 7;
+/** Longest GraphQL error message forwarded in an error. */
+const MAX_FORWARDED_MESSAGE = 300;
+// ---------------------------------------------------------------------------
+// GraphQL documents — every one the client sends (validated against the dated fixture)
+// ---------------------------------------------------------------------------
+const PAGE_INFO = 'pageInfo { hasNextPage endCursor }';
+const PROJECT_FIELDS = 'id name workspaceId ' +
+    'services { edges { node { id name ' +
+    `serviceInstances { edges { node { environmentId source { repo image } } } ${PAGE_INFO} } ` +
+    `} } ${PAGE_INFO} } ` +
+    `environments { edges { node { id name } } ${PAGE_INFO} }`;
+const CUSTOM_DOMAIN_FIELDS = 'id domain targetPort status { dnsRecords { requiredValue zone } verificationDnsHost verificationToken verified }';
+/** Every GraphQL document the client sends, by operation. The unit test walks this table. */
+export const RAILWAY_DOCUMENTS = {
+    projects: `query ($after: String) { projects(after: $after) { edges { node { ${PROJECT_FIELDS} } } ${PAGE_INFO} } }`,
+    project: `query ($id: String!) { project(id: $id) { ${PROJECT_FIELDS} } }`,
+    projectCreate: 'mutation ($input: ProjectCreateInput!) { projectCreate(input: $input) { id name } }',
+    projectDelete: 'mutation ($id: String!) { projectDelete(id: $id) }',
+    environmentRename: 'mutation ($id: String!, $input: EnvironmentRenameInput!) { environmentRename(id: $id, input: $input) { id name } }',
+    environmentCreate: 'mutation ($input: EnvironmentCreateInput!) { environmentCreate(input: $input) { id name } }',
+    environmentDelete: 'mutation ($id: String!) { environmentDelete(id: $id) }',
+    serviceCreate: 'mutation ($input: ServiceCreateInput!) { serviceCreate(input: $input) { id name } }',
+    serviceConnect: 'mutation ($id: String!, $input: ServiceConnectInput!) { serviceConnect(id: $id, input: $input) { id } }',
+    serviceTriggers: `query ($id: String!) { service(id: $id) { id repoTriggers { edges { node { id branch environmentId } } ${PAGE_INFO} } } }`,
+    deploymentTriggerCreate: 'mutation ($input: DeploymentTriggerCreateInput!) { deploymentTriggerCreate(input: $input) { id branch environmentId } }',
+    deploymentTriggerUpdate: 'mutation ($id: String!, $input: DeploymentTriggerUpdateInput!) { deploymentTriggerUpdate(id: $id, input: $input) { id branch environmentId } }',
+    serviceInstanceUpdate: 'mutation ($serviceId: String!, $environmentId: String, $input: ServiceInstanceUpdateInput!) { serviceInstanceUpdate(serviceId: $serviceId, environmentId: $environmentId, input: $input) }',
+    serviceInstanceAutoDeployUpdate: 'mutation ($input: ServiceInstanceAutoDeployUpdateInput!) { serviceInstanceAutoDeployUpdate(input: $input) { enabled } }',
+    variables: 'query ($projectId: String!, $environmentId: String!, $serviceId: String) { variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId) }',
+    domains: `query ($projectId: String!, $environmentId: String!, $serviceId: String!) { domains(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId) { serviceDomains { id domain targetPort } customDomains { ${CUSTOM_DOMAIN_FIELDS} } } }`,
+    serviceDomainCreate: 'mutation ($input: ServiceDomainCreateInput!) { serviceDomainCreate(input: $input) { id domain targetPort } }',
+    customDomainCreate: `mutation ($input: CustomDomainCreateInput!) { customDomainCreate(input: $input) { ${CUSTOM_DOMAIN_FIELDS} } }`,
+    customDomainDelete: 'mutation ($id: String!) { customDomainDelete(id: $id) }',
+    deployments: 'query ($first: Int, $input: DeploymentListInput!) { deployments(first: $first, input: $input) { edges { node { id status createdAt meta } } } }',
+    deployment: 'query ($id: String!) { deployment(id: $id) { id status createdAt meta } }',
+    serviceInstanceDeployV2: 'mutation ($serviceId: String!, $environmentId: String!, $commitSha: String) { serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId, commitSha: $commitSha) }',
+};
+/**
+ * Classification of every value of Railway's `DeploymentStatus` enum (dated fixture). `ended` is
+ * terminal and NOT a success (removed/skipped). `SLEEPING` is a deployment that went live and idles.
+ */
+export const DEPLOYMENT_STATE_CLASS = {
+    INITIALIZING: 'pending',
+    QUEUED: 'pending',
+    WAITING: 'pending',
+    NEEDS_APPROVAL: 'pending',
+    BUILDING: 'pending',
+    DEPLOYING: 'pending',
+    SUCCESS: 'success',
+    SLEEPING: 'success',
+    FAILED: 'failed',
+    CRASHED: 'failed',
+    REMOVING: 'ended',
+    REMOVED: 'ended',
+    SKIPPED: 'ended',
+};
+/**
+ * Class of a deployment state. A state the dated fixture does not know (Railway added a value) is
+ * `unobservable` — named by the caller as "cannot observe", NEVER taken as success.
+ */
+export function classifyDeploymentState(status) {
+    return DEPLOYMENT_STATE_CLASS[status] ?? 'unobservable';
+}
+/** Base of the client's failures. A `CLIError`: the top-level handler prints only the message. */
+export class RailwayApiError extends CLIError {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'RailwayApiError';
+        this.kind = kind;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** 401/403 on the API: the token is invalid or has no access. Names the key, never its value. */
+export class RailwayTokenError extends RailwayApiError {
+    constructor(operation) {
+        super('token-invalid', `Railway rechazó \`${RAILWAY_TOKEN_KEY}\` al ${operation}: el token es inválido o no tiene acceso. ` +
+            'Pruébalo como indica fx-secrets-vault §5 (una consulta de `projects`, nunca `me`) y, si está muerto, ' +
+            'un admin lo rota en `rail-timekast`.');
+        this.name = 'RailwayTokenError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** An existing project has the name and adopting it by name is not allowed (or not safe). */
+export class RailwayNameTakenError extends RailwayApiError {
+    projectName;
+    projectId;
+    constructor(projectName, projectId, reason) {
+        super('name-taken', `Ya existe en Railway un proyecto \`${projectName}\` (${projectId}) y no lo adopto por su nombre: ` +
+            `${reason}. Un nombre no prueba de quién es un proyecto. Si es el de este repo, adóptalo con ` +
+            '`factory provision --adopt --force --target=railway` (el `--force` rehace el estado que ya ' +
+            'existe); si no, cambia el slug. No creé ni modifiqué nada.');
+        this.name = 'RailwayNameTakenError';
+        this.projectName = projectName;
+        this.projectId = projectId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Under the CLI's Vitest setup without an injected transport: refuses before touching anything. */
+export class RailwaySeamMissingError extends RailwayApiError {
+    constructor() {
+        super('seam-missing', 'railway-api: falta el seam `transport` bajo Vitest. Un test NUNCA habla con Railway real: ' +
+            'pasa `transport` a createRailwayClient (tests/unit/railway-api.test.ts tiene el patrón).');
+        this.name = 'RailwaySeamMissingError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+/**
+ * `owner/name` of a GitHub repo given as `owner/name`, an HTTPS URL or an SSH remote, without
+ * `.git` or a trailing slash; `null` when it is none of those. Case is preserved (compare with
+ * {@link sameRepo}). Identity only — it never decides a destination (Decision 13).
+ */
+export function normalizeRepoIdentity(input) {
+    const trimmed = input.trim();
+    const url = /^(?:https:\/\/|ssh:\/\/git@|git@)github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(trimmed);
+    const plain = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(trimmed);
+    const match = url ?? plain;
+    return match ? `${match[1]}/${match[2]}` : null;
+}
+/** Whether two repo identities are the same repo (case-insensitive, any accepted spelling). */
+export function sameRepo(a, b) {
+    const left = normalizeRepoIdentity(a);
+    const right = normalizeRepoIdentity(b);
+    return left !== null && right !== null && left.toLowerCase() === right.toLowerCase();
+}
+/** The distinct projects of a connected-repo search, in order of appearance. */
+export function connectedProjects(matches) {
+    const seen = new Map();
+    for (const m of matches)
+        if (!seen.has(m.project.id))
+            seen.set(m.project.id, m.project);
+    return [...seen.values()];
+}
+/** The real transport over `fetch`: the token goes in a header, the query in the body. */
+export function railwayFetchTransport(fetchImpl = fetch, timeoutMs = RAILWAY_API_TIMEOUT_MS) {
+    return async ({ query, variables, token }) => {
+        const response = await fetchImpl(RAILWAY_GRAPHQL_URL, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, variables }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        return { status: response.status, body };
+    };
+}
+function isUnderTestIsolation() {
+    return globalThis[VAULT_TEST_ISOLATION_KEY] !== undefined;
+}
+/** A GraphQL error's message, only when it carries no fragment of the token. */
+function safeMessage(error, token) {
+    const raw = error &&
+        typeof error === 'object' &&
+        typeof error.message === 'string'
+        ? error.message
+        : '';
+    const message = raw.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    const fragments = token.length >= 12 ? [token, token.slice(0, 8), token.slice(-4)] : [token];
+    if (token !== '' && fragments.some((f) => message.includes(f))) {
+        return '(mensaje omitido: traía un fragmento de la credencial)';
+    }
+    if (message === '')
+        return '(sin mensaje)';
+    return message.length > MAX_FORWARDED_MESSAGE
+        ? `${message.slice(0, MAX_FORWARDED_MESSAGE)}…`
+        : message;
+}
+/**
+ * The nodes of a Railway connection — FAIL-CLOSED: a connection without `edges` is "not consulted",
+ * never an empty list, and one that says it has more pages is refused (a partial list is not the list).
+ */
+function nodes(connection, what) {
+    if (connection === null ||
+        typeof connection !== 'object' ||
+        Array.isArray(connection) ||
+        !Array.isArray(connection.edges)) {
+        throw new RailwayApiError('incomplete', `Railway respondió sin la lista de ${what}: no la doy por vacía. Repite; si persiste, prueba el ` +
+            'token como indica fx-secrets-vault §5.');
+    }
+    if (connection.pageInfo?.hasNextPage === true) {
+        throw new RailwayApiError('incomplete', `Railway devolvió la lista de ${what} en varias páginas y sólo leí la primera: no decido sobre ` +
+            'una lista incompleta. Repórtalo al equipo del Factory.');
+    }
+    return connection.edges.flatMap((edge) => (edge?.node ? [edge.node] : []));
+}
+function named(raw) {
+    return typeof raw.id === 'string' && typeof raw.name === 'string' && raw.id !== ''
+        ? { id: raw.id, name: raw.name }
+        : null;
+}
+function parseProject(raw) {
+    const base = named(raw);
+    if (!base)
+        return null;
+    const services = [];
+    for (const s of nodes(raw.services, `servicios de \`${base.name}\``)) {
+        const service = named(s);
+        if (!service)
+            continue;
+        // Not answered → `null` ("unknown"), never "no instances": the repo search refuses it.
+        const instances = s.serviceInstances === undefined
+            ? null
+            : nodes(s.serviceInstances, `instancias de \`${service.name}\``).flatMap((i) => typeof i.environmentId === 'string'
+                ? [
+                    {
+                        environmentId: i.environmentId,
+                        repo: typeof i.source?.repo === 'string' && i.source.repo !== ''
+                            ? i.source.repo
+                            : null,
+                        image: typeof i.source?.image === 'string' && i.source.image !== ''
+                            ? i.source.image
+                            : null,
+                    },
+                ]
+                : []);
+        services.push({ ...service, instances });
+    }
+    const environments = nodes(raw.environments, `entornos de \`${base.name}\``).flatMap((e) => {
+        const env = named(e);
+        return env ? [env] : [];
+    });
+    return {
+        ...base,
+        workspaceId: typeof raw.workspaceId === 'string' && raw.workspaceId !== '' ? raw.workspaceId : null,
+        services,
+        environments,
+    };
+}
+function parseDeployment(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const d = raw;
+    if (typeof d.id !== 'string' || typeof d.status !== 'string')
+        return null;
+    const meta = d.meta && typeof d.meta === 'object' ? d.meta : {};
+    return {
+        id: d.id,
+        status: d.status,
+        createdAt: typeof d.createdAt === 'string' ? d.createdAt : null,
+        commitHash: typeof meta.commitHash === 'string' ? meta.commitHash : null,
+    };
+}
+function parseCustomDomain(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const d = raw;
+    if (typeof d.id !== 'string' || typeof d.domain !== 'string')
+        return null;
+    const first = Array.isArray(d.status?.dnsRecords) ? d.status.dnsRecords[0] : undefined;
+    return {
+        id: d.id,
+        domain: d.domain,
+        targetPort: typeof d.targetPort === 'number' ? d.targetPort : null,
+        cnameTarget: typeof first?.requiredValue === 'string' ? first.requiredValue : null,
+        verificationHost: typeof d.status?.verificationDnsHost === 'string' ? d.status.verificationDnsHost : null,
+        verificationToken: typeof d.status?.verificationToken === 'string' ? d.status.verificationToken : null,
+        verified: d.status?.verified === true,
+    };
+}
+function serviceLabel(scope) {
+    return `\`${scope.serviceName ?? scope.serviceId}\``;
+}
+// ---------------------------------------------------------------------------
+// The client
+// ---------------------------------------------------------------------------
+/** Build a client. The token is read once, lazily, on the first call. */
+export function createRailwayClient(deps = {}) {
+    let tokenPromise;
+    function transport() {
+        if (deps.transport)
+            return deps.transport;
+        if (isUnderTestIsolation())
+            throw new RailwaySeamMissingError();
+        return railwayFetchTransport();
+    }
+    function token() {
+        if (deps.token !== undefined)
+            return Promise.resolve(deps.token);
+        tokenPromise ??= (deps.rail ? deps.rail.get(RAILWAY_TOKEN_KEY) : readRailSecret(RAILWAY_TOKEN_KEY)).catch((error) => {
+            tokenPromise = undefined;
+            throw error;
+        });
+        return tokenPromise;
+    }
+    async function call(document, variables, operation) {
+        const send = transport(); // under Vitest without a seam: throws before the token or the network
+        const bearer = await token();
+        let response;
+        try {
+            response = await send({ query: RAILWAY_DOCUMENTS[document], variables, token: bearer });
+        }
+        catch {
+            // The transport's own error may carry anything (a URL, a header): rebuilt without it.
+            throw new RailwayApiError('network', `No pude hablar con Railway al ${operation}. Revisa tu conexión.`);
+        }
+        if (response.status === 401 || response.status === 403)
+            throw new RailwayTokenError(operation);
+        const body = response.body && typeof response.body === 'object'
+            ? response.body
+            : {};
+        if (Array.isArray(body.errors) && body.errors.length > 0) {
+            const message = safeMessage(body.errors[0], bearer);
+            if (/not authori[sz]ed/i.test(message)) {
+                throw new RailwayApiError('no-access', `Railway dijo "Not Authorized" al ${operation}. Con \`${RAILWAY_TOKEN_KEY}\` (token de equipo) eso ` +
+                    'significa que el recurso no es de la organización TimeKast —la cuenta propia de un cliente usa ' +
+                    'otro token— o que el token no sirve: pruébalo con `projects` como indica fx-secrets-vault §5 ' +
+                    'antes de darlo por muerto.');
+            }
+            if (/not found/i.test(message)) {
+                throw new RailwayApiError('not-found', `Railway no encontró lo que pedí al ${operation}: ${message}`);
+            }
+            throw new RailwayApiError('graphql', `Railway respondió con un error al ${operation}: ${message}`);
+        }
+        if (response.status < 200 ||
+            response.status >= 300 ||
+            body.data === null ||
+            typeof body.data !== 'object' ||
+            Array.isArray(body.data)) {
+            throw new RailwayApiError('unrecognized', `Railway no respondió bien al ${operation} (status ${response.status}). Si dice "Not Authorized", ` +
+                'prueba el token como indica fx-secrets-vault §5 antes de darlo por muerto.');
+        }
+        return body.data;
+    }
+    /** Like {@link call}, but a "not found" answer is `null`. */
+    async function callOrNull(document, variables, operation) {
+        try {
+            return await call(document, variables, operation);
+        }
+        catch (error) {
+            if (error instanceof RailwayApiError && error.kind === 'not-found')
+                return null;
+            throw error;
+        }
+    }
+    async function listProjects() {
+        const projects = [];
+        let after = null;
+        // The top-level list is walked page by page; a nested list with more pages stops (`nodes`).
+        for (let page = 0; page < RAILWAY_MAX_PAGES; page += 1) {
+            const data = await call('projects', { after }, 'listar los proyectos');
+            const connection = data.projects;
+            const pageInfo = connection && typeof connection === 'object' ? connection.pageInfo : undefined;
+            const list = nodes({ ...connection, pageInfo: undefined }, 'proyectos');
+            for (const raw of list) {
+                const project = parseProject(raw);
+                if (project)
+                    projects.push(project);
+            }
+            if (pageInfo?.hasNextPage !== true)
+                return projects;
+            if (!pageInfo.endCursor || pageInfo.endCursor === after)
+                break;
+            after = pageInfo.endCursor;
+        }
+        throw new RailwayApiError('incomplete', 'Railway no terminó de paginar la lista de proyectos: no decido sobre una lista incompleta. Repite.');
+    }
+    function workspaceOf(projects) {
+        if (projects.length === 0) {
+            throw new RailwayApiError('workspace-unknown', `\`${RAILWAY_TOKEN_KEY}\` no ve ningún proyecto de Railway: no puedo deducir en qué workspace crear ` +
+                'y no lo adivino. Revisa que el token sea el de equipo de TimeKast (fx-secrets-vault §5).');
+        }
+        const ids = [...new Set(projects.flatMap((p) => (p.workspaceId ? [p.workspaceId] : [])))];
+        if (ids.length === 0) {
+            throw new RailwayApiError('workspace-unknown', 'Railway no dijo el workspace de ninguno de los proyectos visibles: no puedo deducir en qué ' +
+                'workspace crear y no lo adivino.');
+        }
+        if (ids.length > 1) {
+            throw new RailwayApiError('workspace-ambiguous', `\`${RAILWAY_TOKEN_KEY}\` ve proyectos de más de un workspace (${ids.join(', ')}): no elijo uno a ` +
+                'ciegas. El token de equipo de TimeKast alcanza uno solo; revisa qué token hay en `rail-timekast`.');
+        }
+        return ids[0];
+    }
+    async function projectOrThrow(projectId, operation) {
+        const project = await getProject(projectId);
+        if (!project) {
+            throw new RailwayApiError('not-found', `Railway no tiene el proyecto \`${projectId}\` (al ${operation}), o vive en la cuenta propia de un ` +
+                'cliente, que usa otro token.');
+        }
+        return project;
+    }
+    async function getProject(id) {
+        const data = await callOrNull('project', { id }, `leer el proyecto \`${id}\``);
+        if (!data || data.project === null || data.project === undefined)
+            return null;
+        return parseProject(data.project);
+    }
+    async function listTriggers(args) {
+        const data = await call('serviceTriggers', { id: args.serviceId }, `leer los triggers del servicio \`${args.serviceId}\``);
+        const service = data.service;
+        if (!service || typeof service !== 'object') {
+            throw new RailwayApiError('not-found', `Railway no tiene el servicio \`${args.serviceId}\` al leer sus triggers.`);
+        }
+        return nodes(service.repoTriggers, `triggers del servicio \`${args.serviceId}\``).flatMap((t) => typeof t.id === 'string' && t.environmentId === args.environmentId
+            ? [
+                {
+                    id: t.id,
+                    branch: typeof t.branch === 'string' ? t.branch : '',
+                    environmentId: args.environmentId,
+                },
+            ]
+            : []);
+    }
+    async function readRawVariables(scope) {
+        const data = await call('variables', {
+            projectId: scope.projectId,
+            environmentId: scope.environmentId,
+            serviceId: scope.serviceId,
+        }, `leer las variables de ${serviceLabel(scope)}`);
+        const raw = data.variables;
+        // Fail-closed: an answer without the variables is not "no variables" (an empty deploy).
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new RailwayApiError('incomplete', `Railway respondió sin las variables de ${serviceLabel(scope)}: no las doy por vacías. Repite.`);
+        }
+        return raw;
+    }
+    async function readDomains(scope) {
+        const data = await call('domains', {
+            projectId: scope.projectId,
+            environmentId: scope.environmentId,
+            serviceId: scope.serviceId,
+        }, `leer los dominios de ${serviceLabel(scope)}`);
+        const domains = data.domains;
+        if (!domains ||
+            typeof domains !== 'object' ||
+            !Array.isArray(domains.serviceDomains) ||
+            !Array.isArray(domains.customDomains)) {
+            throw new RailwayApiError('incomplete', `Railway respondió sin la lista de dominios de ${serviceLabel(scope)}: no la doy por vacía. Repite.`);
+        }
+        return {
+            serviceDomains: domains.serviceDomains.flatMap((raw) => {
+                const d = raw;
+                return d && typeof d.id === 'string' && typeof d.domain === 'string'
+                    ? [
+                        {
+                            id: d.id,
+                            domain: d.domain,
+                            targetPort: typeof d.targetPort === 'number' ? d.targetPort : null,
+                        },
+                    ]
+                    : [];
+            }),
+            customDomains: domains.customDomains.flatMap((raw) => {
+                const d = parseCustomDomain(raw);
+                return d ? [d] : [];
+            }),
+        };
+    }
+    async function listDeployments(scope) {
+        const data = await call('deployments', {
+            first: RAILWAY_DEPLOYMENTS_PAGE,
+            input: {
+                projectId: scope.projectId,
+                environmentId: scope.environmentId,
+                serviceId: scope.serviceId,
+            },
+        }, `listar los deployments de ${serviceLabel(scope)}`);
+        return nodes(data.deployments, `deployments de ${serviceLabel(scope)}`).flatMap((raw) => {
+            const d = parseDeployment(raw);
+            return d ? [d] : [];
+        });
+    }
+    const client = {
+        async verifyToken() {
+            // `projects`, NEVER `me`: a live team token answers "Not Authorized" to `me`.
+            const data = await call('projects', { after: null }, 'probar el token');
+            nodes({ ...data.projects, pageInfo: undefined }, 'proyectos');
+        },
+        listProjects,
+        async resolveWorkspaceId() {
+            return workspaceOf(await listProjects());
+        },
+        async findByConnectedRepo(repo) {
+            const wanted = normalizeRepoIdentity(repo);
+            if (!wanted) {
+                throw new CLIError(`\`${repo}\` no es un repo de GitHub (\`owner/nombre\`): no puedo buscar en Railway por repo conectado.`);
+            }
+            const matches = [];
+            for (const project of await listProjects()) {
+                for (const service of project.services) {
+                    if (service.instances === null) {
+                        throw new RailwayApiError('incomplete', `Railway respondió sin las instancias del servicio \`${service.name}\` de \`${project.name}\`: ` +
+                            'no sé a qué repo está conectado y no lo doy por desconectado. Repite.');
+                    }
+                    const connectedEnvironmentIds = service.instances
+                        .filter((i) => i.repo !== null && sameRepo(i.repo, wanted))
+                        .map((i) => i.environmentId);
+                    if (connectedEnvironmentIds.length === 0)
+                        continue;
+                    matches.push({
+                        project: { id: project.id, name: project.name, workspaceId: project.workspaceId },
+                        service: { id: service.id, name: service.name },
+                        environments: project.environments,
+                        connectedEnvironmentIds,
+                    });
+                }
+            }
+            return matches;
+        },
+        getProject,
+        async findProjectInWorkspaceByName(name) {
+            const projects = await listProjects();
+            const workspaceId = workspaceOf(projects);
+            const same = projects.filter((p) => p.workspaceId === workspaceId && p.name === name);
+            if (same.length > 1) {
+                throw new RailwayApiError('name-taken', `Hay ${same.length} proyectos de Railway llamados \`${name}\` en el workspace: ` +
+                    `${same.map((p) => p.id).join(', ')}. No elijo uno a ciegas. No hice nada.`);
+            }
+            return same[0] ?? null;
+        },
+        async createProject(args, options = {}) {
+            const projects = await listProjects();
+            const workspaceId = workspaceOf(projects);
+            const same = projects.filter((p) => p.workspaceId === workspaceId && p.name === args.name);
+            const [existing] = same;
+            if (existing) {
+                if (same.length > 1) {
+                    throw new RailwayNameTakenError(args.name, same.map((p) => p.id).join(', '), 'hay varios con ese nombre');
+                }
+                if (!options.adoptByName) {
+                    throw new RailwayNameTakenError(existing.name, existing.id, 'esta corrida no retoma un alta propia');
+                }
+                const repo = options.adoptByName.repo;
+                if (existing.services.length > 1) {
+                    throw new RailwayNameTakenError(existing.name, existing.id, `tiene ${existing.services.length} servicios y un alta del kit deja uno`);
+                }
+                for (const service of existing.services) {
+                    if (service.name !== RAILWAY_SERVICE_NAME) {
+                        throw new RailwayNameTakenError(existing.name, existing.id, `su servicio se llama \`${service.name}\` y el del kit es \`${RAILWAY_SERVICE_NAME}\``);
+                    }
+                    if (service.instances === null) {
+                        throw new RailwayNameTakenError(existing.name, existing.id, `Railway no dijo a qué repo está conectado su servicio \`${service.name}\``);
+                    }
+                    const image = service.instances.find((i) => i.image !== null);
+                    if (image) {
+                        throw new RailwayNameTakenError(existing.name, existing.id, `su servicio \`${service.name}\` corre una imagen (\`${image.image}\`), no un repo`);
+                    }
+                    const foreign = service.instances.find((i) => i.repo !== null && !sameRepo(i.repo, repo));
+                    if (foreign) {
+                        throw new RailwayNameTakenError(existing.name, existing.id, `su servicio \`${service.name}\` está conectado a otro repo (\`${foreign.repo}\`)`);
+                    }
+                }
+                return { id: existing.id, created: false };
+            }
+            const data = await call('projectCreate', { input: { name: args.name, workspaceId } }, `crear el proyecto \`${args.name}\``);
+            const created = data.projectCreate;
+            if (!created || typeof created.id !== 'string') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el id del proyecto \`${args.name}\` al crearlo. Revisa el dashboard antes de repetir.`);
+            }
+            return { id: created.id, created: true };
+        },
+        async deleteProject(id) {
+            await call('projectDelete', { id }, `borrar el proyecto \`${id}\``);
+        },
+        async renameEnvironment({ projectId, from, to }) {
+            const project = await projectOrThrow(projectId, `renombrar el entorno \`${from}\``);
+            const already = project.environments.find((e) => e.name === to);
+            if (already)
+                return { id: already.id, renamed: false };
+            const source = project.environments.find((e) => e.name === from);
+            if (!source) {
+                throw new RailwayApiError('not-found', `El proyecto \`${project.name}\` de Railway no tiene un entorno \`${from}\` ni \`${to}\`. Tiene: ` +
+                    `${project.environments.map((e) => `\`${e.name}\``).join(', ') || '(ninguno)'}.`);
+            }
+            await call('environmentRename', { id: source.id, input: { name: to } }, `renombrar el entorno \`${from}\` a \`${to}\``);
+            return { id: source.id, renamed: true };
+        },
+        async ensureEnvironment({ projectId, name, sourceEnvironmentId, skipInitialDeploys }) {
+            const project = await projectOrThrow(projectId, `crear el entorno \`${name}\``);
+            const existing = project.environments.find((e) => e.name === name);
+            if (existing)
+                return { id: existing.id, created: false };
+            const input = { name, projectId };
+            if (sourceEnvironmentId !== undefined)
+                input.sourceEnvironmentId = sourceEnvironmentId;
+            if (skipInitialDeploys !== undefined)
+                input.skipInitialDeploys = skipInitialDeploys;
+            const data = await call('environmentCreate', { input }, `crear el entorno \`${name}\``);
+            const created = data.environmentCreate;
+            if (!created || typeof created.id !== 'string') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el id del entorno \`${name}\` al crearlo.`);
+            }
+            return { id: created.id, created: true };
+        },
+        async deleteEnvironment(id) {
+            await call('environmentDelete', { id }, `borrar el entorno \`${id}\``);
+        },
+        async ensureService(args) {
+            const project = await projectOrThrow(args.projectId, `crear el servicio \`${args.name}\``);
+            const existing = project.services.find((s) => s.name === args.name);
+            if (existing)
+                return { id: existing.id, created: false };
+            // Built field by field: whatever else a caller forces into `args` never travels.
+            const input = { projectId: args.projectId, name: args.name };
+            if (args.source && 'repo' in args.source && typeof args.source.repo === 'string') {
+                input.source = { repo: args.source.repo };
+            }
+            else if (args.source && 'image' in args.source && typeof args.source.image === 'string') {
+                input.source = { image: args.source.image };
+            }
+            if (typeof args.branch === 'string')
+                input.branch = args.branch;
+            const data = await call('serviceCreate', { input }, `crear el servicio \`${args.name}\``);
+            const created = data.serviceCreate;
+            if (!created || typeof created.id !== 'string') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el id del servicio \`${args.name}\` al crearlo.`);
+            }
+            return { id: created.id, created: true };
+        },
+        async connectService({ serviceId, repo, branch }) {
+            const input = { repo };
+            if (branch !== undefined)
+                input.branch = branch;
+            await call('serviceConnect', { id: serviceId, input }, `conectar \`${repo}\` al servicio \`${serviceId}\``);
+        },
+        listTriggers,
+        async ensureBranchTrigger({ projectId, environmentId, serviceId, branch, repository }) {
+            const [existing] = await listTriggers({ serviceId, environmentId });
+            if (existing) {
+                if (existing.branch === branch)
+                    return { id: existing.id, created: false, updated: false };
+                await call('deploymentTriggerUpdate', { id: existing.id, input: { branch } }, `cambiar la rama del servicio \`${serviceId}\` a \`${branch}\``);
+                return { id: existing.id, created: false, updated: true };
+            }
+            const data = await call('deploymentTriggerCreate', {
+                input: {
+                    branch,
+                    environmentId,
+                    projectId,
+                    provider: RAILWAY_TRIGGER_PROVIDER,
+                    repository,
+                    serviceId,
+                },
+            }, `crear el trigger de \`${branch}\` del servicio \`${serviceId}\``);
+            const created = data.deploymentTriggerCreate;
+            if (!created || typeof created.id !== 'string') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el id del trigger de \`${branch}\` al crearlo.`);
+            }
+            return { id: created.id, created: true, updated: false };
+        },
+        async enableAutoDeploy(scope) {
+            // The mutation is NOT idempotent (it aborts when the pair already has its trigger): ask first.
+            const existing = await listTriggers({
+                serviceId: scope.serviceId,
+                environmentId: scope.environmentId,
+            });
+            if (existing.length > 0)
+                return { created: false };
+            await call('serviceInstanceAutoDeployUpdate', {
+                input: {
+                    projectId: scope.projectId,
+                    environmentId: scope.environmentId,
+                    serviceId: scope.serviceId,
+                    enabled: true,
+                },
+            }, `encender el auto-deploy de ${serviceLabel(scope)}`);
+            return { created: true };
+        },
+        async updateServiceInstance({ serviceId, environmentId, settings }) {
+            const input = {};
+            for (const key of [
+                'region',
+                'healthcheckPath',
+                'preDeployCommand',
+                'startCommand',
+                'buildCommand',
+            ]) {
+                if (typeof settings[key] === 'string')
+                    input[key] = settings[key];
+            }
+            if (Object.keys(input).length === 0)
+                return false;
+            await call('serviceInstanceUpdate', { serviceId, environmentId, input }, `ajustar el servicio \`${serviceId}\` en su entorno`);
+            return true;
+        },
+        async readVariableNames(scope) {
+            return Object.keys(await readRawVariables(scope)).sort();
+        },
+        async readVariableHashes(scope, hash) {
+            const hashes = new Map();
+            for (const [key, value] of Object.entries(await readRawVariables(scope))) {
+                if (typeof value === 'string')
+                    hashes.set(key, hash(value));
+            }
+            return hashes;
+        },
+        async readVariableValues(scope) {
+            const values = new Map();
+            for (const [key, value] of Object.entries(await readRawVariables(scope))) {
+                if (typeof value === 'string')
+                    values.set(key, value);
+            }
+            return values;
+        },
+        async ensureServiceDomain(scope) {
+            const { serviceDomains } = await readDomains(scope);
+            const [existing] = serviceDomains;
+            if (existing)
+                return { id: existing.id, domain: existing.domain, created: false };
+            const data = await call('serviceDomainCreate', {
+                input: {
+                    environmentId: scope.environmentId,
+                    serviceId: scope.serviceId,
+                    targetPort: scope.targetPort,
+                },
+            }, `crear el dominio de Railway de ${serviceLabel(scope)}`);
+            const created = data.serviceDomainCreate;
+            if (!created || typeof created.id !== 'string' || typeof created.domain !== 'string') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el dominio de ${serviceLabel(scope)} al crearlo.`);
+            }
+            return { id: created.id, domain: created.domain, created: true };
+        },
+        async ensureCustomDomain(scope) {
+            const host = scope.domain.trim().toLowerCase();
+            const { customDomains } = await readDomains(scope);
+            const existing = customDomains.find((d) => d.domain.toLowerCase() === host);
+            if (existing)
+                return { ...existing, created: false };
+            const data = await call('customDomainCreate', {
+                input: {
+                    domain: host,
+                    environmentId: scope.environmentId,
+                    projectId: scope.projectId,
+                    serviceId: scope.serviceId,
+                    targetPort: scope.targetPort,
+                },
+            }, `crear el dominio \`${host}\` en ${serviceLabel(scope)}`);
+            const created = parseCustomDomain(data.customDomainCreate);
+            if (!created) {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el dominio \`${host}\` al crearlo.`);
+            }
+            return { ...created, created: true };
+        },
+        async getCustomDomain(scope, domain) {
+            const host = domain.trim().toLowerCase();
+            const { customDomains } = await readDomains(scope);
+            return customDomains.find((d) => d.domain.toLowerCase() === host) ?? null;
+        },
+        async listCustomDomains(scope) {
+            return (await readDomains(scope)).customDomains;
+        },
+        async deleteCustomDomain(id) {
+            await call('customDomainDelete', { id }, `borrar el dominio \`${id}\``);
+        },
+        listDeployments,
+        async findDeploymentByCommit(scope, commit) {
+            const prefix = commit.trim().toLowerCase();
+            if (prefix.length < MIN_COMMIT_PREFIX) {
+                throw new CLIError(`El commit \`${commit}\` es muy corto para buscar su deployment (mínimo ${MIN_COMMIT_PREFIX} caracteres).`);
+            }
+            const list = await listDeployments(scope);
+            return (list.find((d) => d.commitHash !== null && d.commitHash.toLowerCase().startsWith(prefix)) ??
+                null);
+        },
+        async getDeployment(id) {
+            const data = await callOrNull('deployment', { id }, `leer el deployment \`${id}\``);
+            if (!data)
+                return null;
+            return parseDeployment(data.deployment);
+        },
+        async deployServiceInstance(scope, commit) {
+            const sha = commit.trim().toLowerCase();
+            if (sha.length < MIN_COMMIT_PREFIX) {
+                throw new CLIError(`El commit \`${commit}\` es muy corto para desplegarlo (mínimo ${MIN_COMMIT_PREFIX} caracteres).`);
+            }
+            const data = await call('serviceInstanceDeployV2', { serviceId: scope.serviceId, environmentId: scope.environmentId, commitSha: sha }, `desplegar ${serviceLabel(scope)}`);
+            const id = data.serviceInstanceDeployV2;
+            if (typeof id !== 'string' || id === '') {
+                throw new RailwayApiError('unrecognized', `Railway no devolvió el id del deployment de ${serviceLabel(scope)}. Revisa el dashboard antes de repetir.`);
+            }
+            return id;
+        },
+    };
+    return client;
+}