@yolo-labs/yolo-cli 0.23.0

package/dist/deploy-client.js

@@ -0,0 +1,460 @@
+/**
+ * deploy-client — transport legs for `yolo deploy` (managed hosting, Phase 1).
+ *
+ * Implements the two-phase manifest-then-missing-files ship protocol from
+ * `docs/MANAGED_HOSTING_CLI_SPEC.md` §4 (THE contract) against the
+ * `/v1/deploy/*` routes (`docs/MANAGED_HOSTING_BACKEND_SPEC.md` §3 routes
+ * 1–8), plus thin wrappers for createProject / status / rollback / logs.
+ *
+ * Transport notes:
+ *   - Deploy routes are user-facing `/v1/deploy/*` — the user access JWT is
+ *     the credential (Bearer), same as `userRouteRequest` in work-client.ts.
+ *     No MCP-token mint is needed.
+ *   - The token is RE-RESOLVED from the rotation file (~/.config/yolo/token,
+ *     rewritten every ~10 min by yolo-token-refresh) before EVERY leg, so a
+ *     long upload can't ride a token that expired mid-ship.
+ *   - 4xx refusal envelopes ({ok:false, reason, message, detail?, hint?} or
+ *     the legacy {error, code}) pass through VERBATIM as structured failures
+ *     — the CLI and backend reason taxonomies are the same identifiers
+ *     (spec §5).
+ *   - 401 → kind 'auth' (exit 78); 5xx and transport errors → kind 'network'
+ *     (exit 4, transient); other 4xx → the backend reason (exit 2).
+ *   - finalize is the only non-JSON leg: worker modules go up as multipart
+ *     FormData (Node 20 global FormData/Blob); pure-static sends empty JSON
+ *     and the server attaches the canonical assets-only shim.
+ *
+ * All legs take an injectable `fetchImpl` (and the context an injectable
+ * `readFileImpl` for the token file) so unit tests never touch real network
+ * or the real FS — the work-client.test.ts convention.
+ */
+import { resolveUserToken } from './auth-context.js';
+import { userRouteRequest } from './work-client.js';
+/**
+ * Resolve the deploy transport context. Checks the env trio once up front
+ * (fail fast with a single auth message); the token itself is still
+ * re-resolved per leg by every client function.
+ */
+export function resolveDeployContext(env = process.env, readFileImpl, fetchImpl) {
+    const commonApiUrl = env.YOLO_COMMON_API_URL || env.YOLO_API_URL;
+    if (!commonApiUrl) {
+        return { ok: false, kind: 'auth', message: 'YOLO_COMMON_API_URL (or YOLO_API_URL) env var is required' };
+    }
+    const token = currentTokenFrom(env, readFileImpl);
+    if (!token) {
+        return {
+            ok: false,
+            kind: 'auth',
+            message: 'no user token available: expected a user access JWT in ~/.config/yolo/token or the YOLO_API_TOKEN env var',
+        };
+    }
+    return { ok: true, context: { commonApiUrl, env, readFileImpl, fetchImpl } };
+}
+/** Leg 1 — POST /v1/deploy/projects/:id/ship/start */
+export async function startShip(ctx, projectId, request) {
+    return withRetry(ctx, 'ship/start', async () => {
+        const result = await jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/ship/start`, {
+            method: 'POST',
+            jsonBody: request,
+        });
+        if (!result.ok)
+            return result;
+        const value = result.value;
+        if (!value || typeof value.shipId !== 'string' || !Array.isArray(value.missing)) {
+            return {
+                ok: false,
+                kind: 'invalid-response',
+                message: 'ship/start response missing shipId / missing buckets',
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                shipId: value.shipId,
+                missing: value.missing,
+                caps: (value.caps ?? { maxFileBytes: 0, maxTotalBytes: 0, maxFiles: 0 }),
+            },
+        };
+    });
+}
+/** Leg 2 — POST /v1/deploy/projects/:id/ship/:shipId/assets (base64 bucket). */
+export async function uploadAssetBucket(ctx, projectId, shipId, files) {
+    return withRetry(ctx, 'assets', () => jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/ship/${enc(shipId)}/assets`, {
+        method: 'POST',
+        jsonBody: { files },
+    }));
+}
+/**
+ * Leg 3 — POST /v1/deploy/projects/:id/ship/:shipId/finalize.
+ *
+ * Worker modules go as multipart FormData (Node 20 global FormData/Blob,
+ * busboy on the server route); pure-static sends empty JSON and the server
+ * attaches the canonical assets-only shim. Distinguished outcomes:
+ *   success | 409 awaiting-approval (T3 prod gate — NOT an error)
+ *           | 410 upload-expired (ship session lapsed → rerun)
+ */
+export async function finalizeShip(ctx, projectId, shipId, modules = []) {
+    // NOT auto-retried (unlike ship/start + assets). finalize is single-shot per
+    // ship session: if the first request reached the server and created the
+    // release but the response was lost to a transient 5xx/522, a blind retry
+    // hits the open→finalized CAS and returns a deterministic 410 upload-expired
+    // — masking a deploy that actually SUCCEEDED. So a transient finalize fault
+    // surfaces as kind 'network' (exit 4); the operator checks `yolo deploy
+    // status` before rerunning rather than auto-looping into a misleading error.
+    const token = currentToken(ctx);
+    if (!token)
+        return missingTokenFailure();
+    const fetchImpl = resolveFetch(ctx);
+    if (!fetchImpl)
+        return noFetchFailure();
+    const url = `${stripTrailingSlash(ctx.commonApiUrl)}/v1/deploy/projects/${enc(projectId)}/ship/${enc(shipId)}/finalize`;
+    let response;
+    try {
+        if (modules.length > 0) {
+            const form = new FormData();
+            for (const module of modules) {
+                form.append(module.name, new Blob([module.contents], { type: 'application/javascript+module' }), module.name);
+            }
+            // No explicit Content-Type — fetch sets the multipart boundary itself.
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${token}` },
+                body: form,
+            });
+        }
+        else {
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({}),
+            });
+        }
+    }
+    catch (err) {
+        return networkFailure(err);
+    }
+    if (response.ok) {
+        let value = {};
+        try {
+            value = (await response.json());
+        }
+        catch {
+            // empty/non-JSON success body — tolerate
+        }
+        const release = (value.release ?? {});
+        const releaseId = str(value.releaseId) ?? str(release.releaseId) ?? str(release.id);
+        if (!releaseId) {
+            return { ok: false, kind: 'invalid-response', message: 'finalize response missing releaseId' };
+        }
+        return {
+            ok: true,
+            value: { ...value, releaseId, url: str(value.url) ?? str(release.url), status: str(value.status) ?? str(release.status) },
+        };
+    }
+    const failure = await mapErrorResponse(response);
+    // T3 prod gate: 409 awaiting-approval is a distinct, NOT-an-error outcome
+    // (spec §5 — exit 3, PENDING prefix, never blind-retried). The backend may
+    // spell the reason 'awaiting-approval' (CLI spec §4) or 'approval-required'
+    // (backend spec route 4c) — normalize to 'awaiting-approval'.
+    if (failure.status === 409 && (failure.kind === 'awaiting-approval' || failure.kind === 'approval-required')) {
+        const body = failure.body ?? {};
+        const detail = (failure.detail ?? {});
+        const approvalId = str(body.approvalId) ?? str(detail.approvalId);
+        if (approvalId) {
+            return {
+                ok: false,
+                kind: 'awaiting-approval',
+                approvalId,
+                approvalUrl: str(body.approvalUrl) ?? str(detail.approvalUrl),
+                statement: str(body.statement) ?? str(detail.statement),
+                expiresAt: str(body.expiresAt) ?? str(detail.expiresAt),
+                releaseId: str(body.releaseId) ?? str(detail.releaseId),
+                message: failure.message,
+                status: 409,
+            };
+        }
+        // 409 claiming approval but without an approvalId — fall through as a
+        // plain backend failure so the caller doesn't print a broken PENDING.
+    }
+    return failure;
+}
+/** POST /v1/deploy/projects */
+export async function createProject(ctx, request) {
+    return jsonLeg(ctx, '/deploy/projects', { method: 'POST', jsonBody: request });
+}
+/** GET /v1/deploy/projects/:id — project + currentRelease + recentReleases + usage/caps. */
+export async function getProjectStatus(ctx, projectId) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}`, { method: 'GET' });
+}
+/**
+ * GET /v1/deploy/projects — the caller's OWN hosting projects (owner-scoped
+ * server-side). Used by `yolo deploy init`/`link` to reconcile a slug-taken
+ * error: if the taken slug is one the caller already owns, link to it instead
+ * of failing.
+ */
+export async function listProjects(ctx) {
+    const result = await jsonLeg(ctx, '/deploy/projects', { method: 'GET' });
+    if (!result.ok)
+        return result;
+    const raw = (result.value && typeof result.value === 'object' ? result.value : {});
+    const projects = Array.isArray(result.value)
+        ? result.value
+        : Array.isArray(raw.projects)
+            ? raw.projects
+            : [];
+    return { ok: true, value: projects };
+}
+/** POST /v1/deploy/projects/:id/rollback */
+export async function rollbackProject(ctx, projectId, request = {}) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/rollback`, { method: 'POST', jsonBody: request });
+}
+/**
+ * POST /v1/deploy/projects/:id/resources/:rid/query (Phase 2).
+ *
+ * The CLI does NOT know the resourceId — it targets the project's SOLE
+ * D1 by sending the `default` segment (the route's `resourceId?`
+ * contract; the server resolves the lone D1). Writes need
+ * `allowWrite:true`; DDL/PRAGMA/ATTACH are blocked server-side
+ * (`sql-not-allowed`). 4xx refusal reasons pass through verbatim as the
+ * structured failure `kind`.
+ */
+export async function queryD1(ctx, projectId, sql, options = {}) {
+    const result = await jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/resources/default/query`, {
+        method: 'POST',
+        jsonBody: {
+            sql,
+            ...(options.params !== undefined ? { params: options.params } : {}),
+            allowWrite: options.allowWrite ?? false,
+        },
+    });
+    if (!result.ok)
+        return result;
+    const value = (result.value && typeof result.value === 'object' ? result.value : {});
+    const results = Array.isArray(value.results)
+        ? value.results
+        : Array.isArray(value.rows)
+            ? value.rows
+            : [];
+    return {
+        ok: true,
+        value: { ...value, results, meta: value.meta && typeof value.meta === 'object' ? value.meta : undefined },
+    };
+}
+/**
+ * PUT /v1/deploy/projects/:id/slug — rename the project's primary slug.
+ * `keepOldAsRedirect` (default true) makes the old slug 308 → the new URL.
+ */
+export async function renameProject(ctx, projectId, request) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/slug`, { method: 'PUT', jsonBody: request });
+}
+/** POST /v1/deploy/projects/:id/aliases — add an alias hostname (slug). */
+export async function addAlias(ctx, projectId, slug) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/aliases`, { method: 'POST', jsonBody: { slug } });
+}
+/** DELETE /v1/deploy/projects/:id/aliases/:slug — remove an alias/redirect binding. */
+export async function removeAlias(ctx, projectId, slug) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/aliases/${enc(slug)}`, { method: 'DELETE' });
+}
+/** PUT /v1/deploy/projects/:id/redirects/:slug — 308 a slug to an external URL. */
+export async function setRedirect(ctx, projectId, slug, target) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/redirects/${enc(slug)}`, {
+        method: 'PUT',
+        jsonBody: { target },
+    });
+}
+/**
+ * DELETE /v1/deploy/projects/:id — delete the project. A live site is refused
+ * server-side (a `not-confirmed` refusal with a hint) unless the caller passes
+ * the current slug as `confirmSlug`; a throwaway/never-shipped project deletes
+ * without confirmation.
+ */
+export async function deleteProject(ctx, projectId, request = {}) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}`, {
+        method: 'DELETE',
+        ...(request.confirmSlug !== undefined ? { jsonBody: { confirmSlug: request.confirmSlug } } : {}),
+    });
+}
+/**
+ * POST /v1/deploy/projects/:id/clone — duplicate a project's config (env +
+ * secrets + fresh D1/KV/R2 bindings) into a new EMPTY project. No release is
+ * copied — the clone must be re-shipped to populate it. Optional `name`/`slug`
+ * name the clone; the backend derives defaults otherwise. Returns
+ * `{ project, sourceSlug, resourcesCloned, secretsCloned }`. 4xx refusal
+ * reasons (slug-taken, hosting-disabled, …) pass through as the failure `kind`.
+ */
+export async function cloneProject(ctx, projectId, request = {}) {
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/clone`, {
+        method: 'POST',
+        jsonBody: {
+            ...(request.name !== undefined ? { name: request.name } : {}),
+            ...(request.slug !== undefined ? { slug: request.slug } : {}),
+        },
+    });
+}
+/** GET /v1/deploy/projects/:id/logs (buffered variant). */
+export async function getLogs(ctx, projectId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.sinceMinutes !== undefined)
+        params.set('sinceMinutes', String(options.sinceMinutes));
+    if (options.limit !== undefined)
+        params.set('limit', String(options.limit));
+    const qs = params.toString();
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/logs${qs ? `?${qs}` : ''}`, { method: 'GET' });
+}
+/**
+ * GET /v1/deploy/projects/:id/tail — ONE long-poll over the live-tail buffer
+ * (signal C). The server waits up to ~`waitMs` for new lines and returns them
+ * plus a `cursor`; the `--tail` loop calls this repeatedly, threading the cursor
+ * so there are no gaps or duplicates. Long-poll (not an infinite stream) so it
+ * survives proxy/ingress idle timeouts.
+ */
+export async function pollTail(ctx, projectId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.releaseId !== undefined)
+        params.set('releaseId', options.releaseId);
+    if (options.cursor !== undefined)
+        params.set('cursor', options.cursor);
+    if (options.waitMs !== undefined)
+        params.set('waitMs', String(options.waitMs));
+    const qs = params.toString();
+    return jsonLeg(ctx, `/deploy/projects/${enc(projectId)}/tail${qs ? `?${qs}` : ''}`, {
+        method: 'GET',
+    });
+}
+// ─── Internals ────────────────────────────────────────────────────────────
+/**
+ * Run a ship leg with bounded-backoff retry on TRANSIENT transport faults.
+ *
+ * Retries only `{ ok:false, kind:'network' }` (5xx / CF 522 / transport error
+ * — see `mapErrorResponse`). Every other result — success, a 4xx refusal,
+ * auth, invalid-response, or awaiting-approval — returns immediately. The leg
+ * `fn` re-resolves the token per call, so a retry can't ride a token that
+ * expired mid-ship.
+ */
+async function withRetry(ctx, leg, fn) {
+    const cfg = ctx.retry;
+    // Opt-in: a context with no `retry` config runs exactly once (no retry).
+    if (!cfg)
+        return fn();
+    const maxAttempts = Math.max(1, cfg.maxAttempts ?? 3);
+    const baseDelayMs = cfg.baseDelayMs ?? 600;
+    const sleep = cfg.sleepImpl ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const result = await fn();
+        if (result.ok || result.kind !== 'network' || attempt >= maxAttempts)
+            return result;
+        const delayMs = baseDelayMs * 2 ** (attempt - 1);
+        cfg.onRetry?.({
+            leg,
+            attempt,
+            maxAttempts,
+            delayMs,
+            failure: result,
+        });
+        await sleep(delayMs);
+    }
+}
+/**
+ * Re-resolve the user token (rotation file → YOLO_API_TOKEN env). Called at
+ * the top of EVERY leg — never cache across legs (spec §0: the ~10-min
+ * rotation must not expire a multi-leg ship mid-flight).
+ */
+function currentToken(ctx) {
+    return currentTokenFrom(ctx.env, ctx.readFileImpl);
+}
+function currentTokenFrom(env, readFileImpl) {
+    return readFileImpl ? resolveUserToken(env, readFileImpl) : resolveUserToken(env);
+}
+function resolveFetch(ctx) {
+    return ctx.fetchImpl ?? globalThis.fetch;
+}
+/** Shared JSON leg: re-resolve token, hit /v1<path> via userRouteRequest, map outcomes. */
+async function jsonLeg(ctx, routePath, init) {
+    const token = currentToken(ctx);
+    if (!token)
+        return missingTokenFailure();
+    let response;
+    try {
+        response = await userRouteRequest({ commonApiUrl: ctx.commonApiUrl, userToken: token, fetchImpl: ctx.fetchImpl }, routePath, init);
+    }
+    catch (err) {
+        return networkFailure(err);
+    }
+    if (response.ok) {
+        try {
+            return { ok: true, value: await response.json() };
+        }
+        catch {
+            return { ok: true, value: {} };
+        }
+    }
+    return mapErrorResponse(response);
+}
+/**
+ * Map a non-2xx response onto the structured failure envelope. The backend's
+ * 4xx refusal body ({ok:false, reason, message, detail?, hint?} — or the
+ * legacy {error, code}) passes through verbatim: `kind` IS the reason.
+ */
+async function mapErrorResponse(response) {
+    const status = response.status;
+    let body = {};
+    try {
+        const parsed = await response.json();
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            body = parsed;
+        }
+    }
+    catch {
+        try {
+            const text = await response.text();
+            if (text)
+                body = { message: text };
+        }
+        catch {
+            // no readable body
+        }
+    }
+    const message = str(body.message) ?? str(body.error) ?? `HTTP ${status}`;
+    if (status === 401) {
+        return { ok: false, kind: 'auth', message: `authentication failed: ${message}`, status, body };
+    }
+    if (status >= 500) {
+        // Genuine server/upstream fault — transient, retry with backoff (exit 4).
+        return { ok: false, kind: 'network', message: `server error (HTTP ${status}): ${message}`, status, body };
+    }
+    let reason = str(body.reason) ?? str(body.code);
+    if (!reason && status === 410)
+        reason = 'upload-expired';
+    return {
+        ok: false,
+        kind: reason ?? `http-${status}`,
+        message,
+        status,
+        detail: body.detail && typeof body.detail === 'object' ? body.detail : undefined,
+        hint: str(body.hint),
+        body,
+    };
+}
+function missingTokenFailure() {
+    return {
+        ok: false,
+        kind: 'auth',
+        message: 'no user token available: expected a user access JWT in ~/.config/yolo/token or the YOLO_API_TOKEN env var',
+    };
+}
+function noFetchFailure() {
+    return { ok: false, kind: 'network', message: 'fetch is not available; the substrate CLI requires Node 20+' };
+}
+function networkFailure(err) {
+    return { ok: false, kind: 'network', message: `request failed: ${err instanceof Error ? err.message : String(err)}` };
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function enc(value) {
+    return encodeURIComponent(value);
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}