ninepm 0.26.0 → 0.30.0

package/dist/cli-types.d.ts

@@ -41,6 +41,7 @@ export interface ContainerImageUploadInstruction {
     expiresAt: string;
     maxBytes: number;
     partBytes?: number;
+    uploadId?: string;
     headers: Record<string, string>;
 }
 export interface AppDatabase {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import type { AccessGrant, AccessGrantType, AccessProviderKey, AppAccessSettings, AppAccessServiceToken, AppAccessToken, AppDatabase, AppRuntime, ContainerRegion, Deployment, ManagedFileObject, ManagedFileShare, ManagedFileUsage, Project } from "./cli-types.js";
+import { Agent } from "undici";
+import type { AccessGrant, AccessGrantType, AccessProviderKey, AppAccessSettings, AppAccessServiceToken, AppAccessToken, AppDatabase, AppRuntime, ContainerImageUploadInstruction, ContainerRegion, Deployment, ManagedFileObject, ManagedFileShare, ManagedFileUsage, Project } from "./cli-types.js";
 export interface DeployOptions {
     directory: string;
     apiUrl: string;
@@ -28,6 +29,7 @@ export interface DeployOptions {
     pollTimeoutMs?: number;
     fetchFn?: FetchLike;
     check?: boolean;
+    onUploadProgress?: UploadProgress;
 }
 export interface DeployResult {
     project: Project;
@@ -47,6 +49,7 @@ export interface SiteAccessOptions extends ApiOptions {
 }
 export interface DeleteSiteOptions extends SiteAccessOptions {
     confirmSlug: string;
+    keepRecord?: boolean;
 }
 export interface AccessState {
     access: AppAccessSettings;
@@ -109,7 +112,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.26.0";
+export declare const CLI_VERSION = "0.30.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface CredentialDiagnostics {
     platform: NodeJS.Platform;
@@ -264,6 +267,29 @@ export declare function getManagedFile(options: FileGetOptions): Promise<{
 }>;
 export declare function deleteManagedFile(options: FileDeleteOptions): Promise<ManagedFilePutResult>;
 export declare function shareManagedFile(options: FileShareOptions): Promise<ManagedFileShareResult>;
+export interface UploadRetryOptions {
+    attempts: number;
+    baseDelayMs: number;
+    retryNetworkErrors?: boolean;
+}
+export interface UploadProgressEvent {
+    phase: "start" | "part" | "done";
+    part: number;
+    totalParts: number;
+    uploadedBytes: number;
+    totalBytes: number;
+}
+export type UploadProgress = (event: UploadProgressEvent) => void;
+type ContainerUploadInit = RequestInit & {
+    dispatcher?: Agent;
+};
+export declare function uploadRequestWithRetry(fetchFn: FetchLike, url: string, init: ContainerUploadInit, label: string, sizeBytes: number, options?: UploadRetryOptions): Promise<Response>;
+export declare function uploadContainerImage(fetchFn: FetchLike, imagePath: string, upload: ContainerImageUploadInstruction, retry?: UploadRetryOptions, onProgress?: UploadProgress): Promise<void>;
+export interface UploadProgressReporter {
+    onProgress: UploadProgress;
+    stop(): void;
+}
+export declare function createUploadProgressReporter(stream?: NodeJS.WriteStream): UploadProgressReporter;
 type CliCommand = {
     kind: "deploy";
     options: DeployOptions;

package/dist/index.js

@@ -5,13 +5,14 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, openAsBlob, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { Agent, fetch as undiciFetch } from "undici";
 import { MAX_DEPLOY_DESCRIPTION_LENGTH, normalizeDeployDescription } from "./deploy-description.js";
 import { assetFileTooLargeMessage, oversizedAssets } from "./deploy-limits.js";
 import { buildFileManifest, readManifestFile } from "./manifest.js";
 import { API_KEY_HELP, API_URL_HELP, CLI_CLIENT_ID, DEFAULT_API_URL, reportCliError } from "./cli-config.js";
-export const CLI_VERSION = "0.26.0";
+export const CLI_VERSION = "0.30.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -196,10 +197,19 @@ export async function deployDirectory(initialOptions) {
     }
     catch (error) {
         // If this invocation created the project (vs. redeploying an existing app)
-        // and the deploy then failed, roll the project back so a rejected first
-        // deploy leaves no orphaned app holding the slug and a Sites quota slot
-        // (#195). Best-effort: a cleanup failure must not mask the deploy error.
-        if (slugHolder.created && slugHolder.slug) {
+        // and the deploy then failed, tear the project's resources back down so a
+        // rejected first deploy leaves no orphaned Worker/machine, slug, or Sites
+        // quota slot (#195). When the failure left a queryable record (`retain`), pass
+        // keepRecord so the live resources are still reclaimed now but the project +
+        // failed deployment + captured logs survive for `9pm logs` — the control plane
+        // sweeps the leftover record after a retention window (#403). A failed
+        // redeploy of a retained failed-only project (created=false, never active)
+        // gets the same keepRecord teardown: there's no live app to protect, and
+        // without it the new attempt's resources would linger until the sweep. A
+        // project this invocation didn't create is never fully deleted. Best-effort
+        // either way: a cleanup failure must not mask the deploy error.
+        const teardownRetainedRedeploy = !slugHolder.created && slugHolder.neverActive === true && slugHolder.retain === true;
+        if (slugHolder.slug && (slugHolder.created || teardownRetainedRedeploy)) {
             try {
                 await deleteSite({
                     apiUrl: initialOptions.apiUrl,
@@ -207,6 +217,7 @@ export async function deployDirectory(initialOptions) {
                     ...(initialOptions.fetchFn ? { fetchFn: initialOptions.fetchFn } : {}),
                     site: slugHolder.slug,
                     confirmSlug: slugHolder.slug,
+                    ...(slugHolder.retain ? { keepRecord: true } : {}),
                 });
             }
             catch {
@@ -220,7 +231,9 @@ export async function deployDirectory(initialOptions) {
 }
 async function runDeploy(initialOptions, slugHolder) {
     const options = prepareFrameworkDeploy(initialOptions);
-    const fetchFn = options.fetchFn ?? fetch;
+    // #374: enrich network-level fetch rejections (EPIPE, header timeouts, …)
+    // across every deploy call — create, upload, finalize, poll — with one wrap.
+    const fetchFn = withFetchDiagnostics(options.fetchFn ?? fetch);
     const apiUrl = normalizeApiUrl(options.apiUrl);
     const runtime = options.runtime ?? (options.entry ? "worker" : "static");
     if (!options.runtime && runtime === "static" && hasDockerfile(options.directory)) {
@@ -236,6 +249,7 @@ async function runDeploy(initialOptions, slugHolder) {
             const { project, created: projectCreated } = await createProject(fetchFn, apiUrl, options.token, options.slug ? { ...projectInput, slug: options.slug } : projectInput);
             slugHolder.slug = project.slug;
             slugHolder.created = projectCreated;
+            slugHolder.neverActive = project.activeDeploymentId === null;
             const database = options.withDatabase
                 ? await createDatabase(fetchFn, apiUrl, options.token, project.id, {
                     name: options.databaseName ?? `${project.slug}-db`,
@@ -279,11 +293,50 @@ async function runDeploy(initialOptions, slugHolder) {
             if (!created.containerImageUpload) {
                 throw new Error("Container deployment did not return an image upload session.");
             }
-            await uploadContainerImage(fetchFn, image.path, created.containerImageUpload);
+            // Use undici's own fetch (not Node's built-in) so it pairs with the
+            // undici Agent dispatcher from the same package version. Handing an
+            // npm undici@7 Agent to Node's bundled fetch (undici 6.x on Node 20/22)
+            // crosses a major-version dispatch-handler boundary; keeping both on the
+            // installed undici avoids that mismatch. Tests still inject their own fetch.
+            // Live upload feedback (#404): a large image over a slow uplink otherwise
+            // uploads in total silence and looks hung. options.onUploadProgress is the
+            // explicit seam; without it, an injected fetchFn is our signal for a
+            // programmatic/test caller (the bundled CLI never sets it — parseDeployArgs
+            // builds options purely from argv), so only the real CLI run gets the
+            // implicit stderr reporter. stop() in the finally is a no-op on success and
+            // closes the spinner (timer + line) on failure, so the reporter can't
+            // outlive the upload.
+            const uploadProgress = options.onUploadProgress || options.fetchFn ? undefined : createUploadProgressReporter();
+            try {
+                await uploadContainerImage(options.fetchFn ?? undiciFetchLike, image.path, created.containerImageUpload, undefined, options.onUploadProgress ?? uploadProgress?.onProgress);
+            }
+            finally {
+                uploadProgress?.stop();
+            }
             const queued = await finalizeDeployment(fetchFn, apiUrl, options.token, created.deployment.id);
             const finalized = await pollDeployment(fetchFn, apiUrl, options.token, queued.id, options.pollTimeoutMs ?? DEFAULT_CONTAINER_POLL_TIMEOUT_MS, queued);
             if (finalized.status === "failed") {
-                throw new Error(deploymentFailureMessage(finalized));
+                // The deploy left a finalized failure record. Keep it (skip the #195
+                // first-deploy rollback) so `9pm logs` / `9pm deployments ls` work for a
+                // first-time crash-on-boot — the exact moment the debugging surface used
+                // to disappear (#403). The control plane reclaims it after a retention
+                // window, so this doesn't re-introduce a permanent orphan.
+                slugHolder.retain = true;
+                // #374: the deployment's own message is the neutral reason + support ref.
+                // Inline a bounded tail of the captured container output when we can fetch
+                // it, so the output names the real cause without a separate command.
+                const parts = [deploymentFailureMessage(finalized)];
+                const detail = await containerFailureDetail({ apiUrl, token: options.token, fetchFn }, project.slug, finalized.id);
+                if (detail) {
+                    // Neutral label on purpose: the captured text is the container's own
+                    // output when the placement could obtain it (#403), else the build/push
+                    // or health detail — the server doesn't tell us which, so don't claim.
+                    parts.push(`Failure log (tail):\n${detail}`);
+                }
+                // The record now survives a failed first deploy too, so always point at
+                // `9pm logs` for the full captured log.
+                parts.push(`Run '9pm logs ${quoteSiteArg(project.slug)}' for the full failure log.`);
+                throw new Error(parts.join("\n\n"));
             }
             return {
                 project,
@@ -640,7 +693,7 @@ export async function listSites(options) {
 export async function deleteSite(options) {
     const payload = await apiRequest(options, `/v1/sites/${encodeURIComponent(options.site)}`, {
         method: "DELETE",
-        body: JSON.stringify({ confirmSlug: options.confirmSlug }),
+        body: JSON.stringify({ confirmSlug: options.confirmSlug, ...(options.keepRecord ? { keepRecord: true } : {}) }),
     });
     return payload.deleted;
 }
@@ -823,48 +876,315 @@ function deploymentFailureMessage(deployment) {
     const error = deployment.metadata["error"];
     return typeof error === "string" && error.trim() ? error.trim() : "Deployment failed.";
 }
-async function uploadContainerImage(fetchFn, imagePath, upload) {
-    const bytes = readFileSync(imagePath);
-    if (bytes.byteLength > upload.maxBytes) {
-        throw new Error(`Container image is ${bytes.byteLength} bytes; upload session allows ${upload.maxBytes} bytes.`);
+const CONTAINER_UPLOAD_RETRY = { attempts: 5, baseDelayMs: 1_000 };
+// undici's fetch is web-compatible at runtime but its types don't structurally
+// match the DOM-based FetchLike (it requires `duplex` on Request). We only ever
+// call it with string URLs, so the cast is safe.
+const undiciFetchLike = undiciFetch;
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
+}
+function uploadBackoffDelayMs(baseDelayMs, attempt) {
+    return baseDelayMs * 2 ** (attempt - 1);
+}
+async function safeReadResponseText(response) {
+    try {
+        return (await response.text()).trim();
     }
-    const partBytes = upload.partBytes && upload.partBytes > 0 ? upload.partBytes : 0;
-    if (!partBytes || !upload.completeUrl || bytes.byteLength <= partBytes) {
-        const response = await fetchFn(upload.uploadUrl, {
-            method: upload.method,
-            headers: upload.headers,
-            body: arrayBufferFromBytes(bytes),
+    catch {
+        return "";
+    }
+}
+const CONTAINER_FAILURE_TAIL_LINES = 20;
+const CONTAINER_FAILURE_TAIL_CHARS = 2048;
+// Diagnostics must never delay the failure we already have: cap the best-effort
+// logs lookup so a slow or stalled /logs can't make the CLI appear hung (#374).
+const CONTAINER_LOGS_TIMEOUT_MS = 5000;
+// #374: a container publish failure records only the neutral message + support
+// ref on the deployment; the actionable build/push detail lives on the
+// container-logs endpoint (already scrubbed server-side). Best-effort fetch a
+// bounded tail so the deploy output carries the real reason inline. Any
+// failure — including the timeout — returns "" so it can never mask or delay
+// the original deploy failure.
+async function containerFailureDetail(options, slug, deploymentId) {
+    try {
+        const result = await apiRequest(options, `/v1/sites/${encodeURIComponent(slug)}/logs`, {
+            method: "GET",
+            signal: AbortSignal.timeout(CONTAINER_LOGS_TIMEOUT_MS),
         });
-        await expectOk(response, "upload container image");
-        return;
+        // The logs route returns the app's *latest* container deployment; under a
+        // concurrent redeploy of the same slug that may be a different one, so only
+        // trust the tail when it's the deployment we just watched fail.
+        if (result.deployment?.id !== deploymentId) {
+            return "";
+        }
+        const source = result.logs && result.logs.trim() ? result.logs : result.reason ?? "";
+        return tailText(source, CONTAINER_FAILURE_TAIL_LINES, CONTAINER_FAILURE_TAIL_CHARS);
     }
-    // Large images go up in parts so no single request exceeds the platform's
-    // request-body limits.
-    const totalParts = Math.ceil(bytes.byteLength / partBytes);
-    let uploadId = "";
-    const parts = [];
-    for (let part = 1; part <= totalParts; part += 1) {
-        const chunk = bytes.subarray((part - 1) * partBytes, Math.min(part * partBytes, bytes.byteLength));
-        const query = uploadId ? `?part=${part}&uploadId=${encodeURIComponent(uploadId)}` : `?part=${part}`;
-        const response = await fetchFn(`${upload.uploadUrl}${query}`, {
-            method: upload.method,
-            headers: upload.headers,
-            body: arrayBufferFromBytes(chunk),
-        });
-        await expectOk(response, `upload container image part ${part}/${totalParts}`);
-        const payload = (await response.json());
-        if (!payload.uploadId || !payload.etag) {
-            throw new Error(`Container image part ${part} did not return an upload receipt.`);
+    catch {
+        return "";
+    }
+}
+// Last `maxLines` lines, then clamped to `maxChars` (UTF-16 code units, so an
+// approximate size cap that may cut mid-line — fine for a display tail) from the
+// end. Returns "" for blank input.
+function tailText(text, maxLines, maxChars) {
+    let trimmed = text.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const lines = trimmed.split("\n");
+    if (lines.length > maxLines) {
+        trimmed = lines.slice(-maxLines).join("\n");
+    }
+    if (trimmed.length > maxChars) {
+        trimmed = trimmed.slice(-maxChars);
+    }
+    return trimmed;
+}
+// Turn undici's opaque `fetch failed` into something actionable by surfacing the
+// underlying cause (e.g. EPIPE, UND_ERR_HEADERS_TIMEOUT).
+function describeFetchError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const cause = error.cause;
+    let causeText = "";
+    if (cause instanceof Error) {
+        const code = cause.code;
+        causeText = typeof code === "string" && code ? `${code}: ${cause.message}` : cause.message;
+    }
+    else if (cause && typeof cause === "object" && "code" in cause) {
+        causeText = String(cause.code);
+    }
+    else if (cause !== undefined && cause !== null) {
+        causeText = String(cause);
+    }
+    return causeText ? `${error.message} (${causeText})` : error.message;
+}
+// Release a successful response we don't need to read. Undici pins the
+// connection until the body is consumed or cancelled, which would otherwise
+// stall `Agent.close()` when the caller ignores the payload.
+async function discardResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Best effort: the socket is released regardless of a late cancel error.
+    }
+}
+// Send one upload request, retrying transient network failures and retryable
+// HTTP statuses (408/429/5xx) with exponential backoff. Non-retryable statuses
+// and exhausted retries throw with the cause, label, and byte size attached.
+// Idempotency is the caller's responsibility: send the uploadId-less part 1
+// with attempts=1 (a re-send starts a second multipart upload), and the
+// non-idempotent "complete" with retryNetworkErrors=false (a re-send after a
+// lost success 500s on the consumed uploadId).
+export async function uploadRequestWithRetry(fetchFn, url, init, label, sizeBytes, options = CONTAINER_UPLOAD_RETRY) {
+    const { attempts, baseDelayMs, retryNetworkErrors = true } = options;
+    let lastError = "unknown error";
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        let response;
+        try {
+            response = await fetchFn(url, init);
         }
-        uploadId = payload.uploadId;
-        parts.push({ part, etag: payload.etag });
+        catch (error) {
+            lastError = describeFetchError(error);
+            if (!retryNetworkErrors) {
+                throw new Error(`Failed to ${label}: ${lastError}. The request may have completed on the server; ` +
+                    `check the deployment status before retrying rather than re-running blindly. ` +
+                    `(${formatBytesForCli(sizeBytes)})`);
+            }
+            if (attempt >= attempts) {
+                break;
+            }
+            await sleep(uploadBackoffDelayMs(baseDelayMs, attempt));
+            continue;
+        }
+        if (response.ok) {
+            return response;
+        }
+        const body = await safeReadResponseText(response);
+        lastError = `${response.status} ${body}`.trim();
+        if (attempt >= attempts || !isRetryableStatus(response.status)) {
+            throw new Error(`Failed to ${label}: ${lastError} (${formatBytesForCli(sizeBytes)}, attempt ${attempt}/${attempts})`);
+        }
+        await sleep(uploadBackoffDelayMs(baseDelayMs, attempt));
     }
-    const completed = await fetchFn(upload.completeUrl, {
-        method: "POST",
-        headers: { ...upload.headers, "content-type": "application/json" },
-        body: JSON.stringify({ uploadId, parts }),
+    throw new Error(`Failed to ${label} after ${attempts} attempts (${formatBytesForCli(sizeBytes)}): ${lastError}`);
+}
+export async function uploadContainerImage(fetchFn, imagePath, upload, retry = CONTAINER_UPLOAD_RETRY, onProgress) {
+    // Back the body with the file on disk instead of reading it all into memory:
+    // slices are lazy views, so peak memory stays flat regardless of image size,
+    // and a retried attempt just re-reads the same blob.
+    const image = await openAsBlob(imagePath);
+    const totalBytes = image.size;
+    if (totalBytes > upload.maxBytes) {
+        throw new Error(`Container image is ${totalBytes} bytes; upload session allows ${upload.maxBytes} bytes.`);
+    }
+    // Single source of truth for the chunking decision: the start event's
+    // totalParts and the actual upload branch below both derive from these, so
+    // the advertised part count can't drift from the parts actually sent.
+    // completeUrl is non-null exactly when the upload is multipart.
+    const partBytes = upload.partBytes && upload.partBytes > 0 ? upload.partBytes : 0;
+    const completeUrl = partBytes && upload.completeUrl && totalBytes > partBytes ? upload.completeUrl : null;
+    const totalParts = completeUrl ? Math.ceil(totalBytes / partBytes) : 1;
+    onProgress?.({ phase: "start", part: 0, totalParts, uploadedBytes: 0, totalBytes });
+    // Disable undici's headers/body timeouts for the upload: on a slow link the
+    // server sends no response headers until the whole body arrives, so the
+    // default 300s timeouts abort a slow-but-live transfer. Keep a bounded
+    // connect timeout so a dead host still fails fast. This Agent must be driven
+    // by a matching-version fetch (the caller passes undici's own fetch in
+    // production) — see the call site.
+    const dispatcher = new Agent({
+        headersTimeout: 0,
+        bodyTimeout: 0,
+        keepAliveTimeout: 60_000,
+        connect: { timeout: 30_000 },
     });
-    await expectOk(completed, "complete container image upload");
+    try {
+        if (!completeUrl) {
+            // A single PUT writes the whole object at a content-addressed key, so a
+            // re-send is idempotent and safe to retry.
+            const response = await uploadRequestWithRetry(fetchFn, upload.uploadUrl, { method: upload.method, headers: upload.headers, body: image, dispatcher }, "upload container image", totalBytes, retry);
+            await discardResponseBody(response);
+            onProgress?.({ phase: "part", part: 1, totalParts, uploadedBytes: totalBytes, totalBytes });
+            onProgress?.({ phase: "done", part: 1, totalParts, uploadedBytes: totalBytes, totalBytes });
+            return;
+        }
+        // Large images go up in parts so no single request exceeds the platform's
+        // request-body limits.
+        // A modern server issues the multipart uploadId up front (#391), so part 1
+        // carries it from the start and is as retryable as parts 2..N. Fall back to
+        // an empty id for older servers: there part 1 is uploadId-less, the server
+        // starts a fresh session for it, and a blind retry would orphan the first —
+        // so the guard below keeps part 1 single-attempt only in that legacy case.
+        let uploadId = upload.uploadId ?? "";
+        const parts = [];
+        for (let part = 1; part <= totalParts; part += 1) {
+            const chunk = image.slice((part - 1) * partBytes, Math.min(part * partBytes, totalBytes));
+            const query = uploadId ? `?part=${part}&uploadId=${encodeURIComponent(uploadId)}` : `?part=${part}`;
+            const partRetry = uploadId ? retry : { ...retry, attempts: 1 };
+            const response = await uploadRequestWithRetry(fetchFn, `${upload.uploadUrl}${query}`, { method: upload.method, headers: upload.headers, body: chunk, dispatcher }, `upload container image part ${part}/${totalParts}`, chunk.size, partRetry);
+            const payload = (await response.json());
+            if (!payload.uploadId || !payload.etag) {
+                throw new Error(`Container image part ${part} did not return an upload receipt.`);
+            }
+            uploadId = payload.uploadId;
+            parts.push({ part, etag: payload.etag });
+            onProgress?.({
+                phase: "part",
+                part,
+                totalParts,
+                uploadedBytes: Math.min(part * partBytes, totalBytes),
+                totalBytes,
+            });
+        }
+        // Completing consumes the uploadId server-side, so it is not idempotent: if
+        // this succeeds but the response is lost, a blind re-send 500s on the gone
+        // uploadId. Retry only explicit retryable statuses (server says "not done"),
+        // never an ambiguous network error.
+        const completed = await uploadRequestWithRetry(fetchFn, completeUrl, {
+            method: "POST",
+            headers: { ...upload.headers, "content-type": "application/json" },
+            body: JSON.stringify({ uploadId, parts }),
+            dispatcher,
+        }, "complete container image upload", totalBytes, { ...retry, retryNetworkErrors: false });
+        await discardResponseBody(completed);
+        onProgress?.({ phase: "done", part: totalParts, totalParts, uploadedBytes: totalBytes, totalBytes });
+    }
+    finally {
+        await dispatcher.close().catch(() => { });
+    }
+}
+const UPLOAD_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function createUploadProgressReporter(stream = process.stderr) {
+    const isTty = stream.isTTY === true;
+    let timer;
+    let frame = 0;
+    let finished = false;
+    let last;
+    const label = (event) => {
+        const total = formatBytesForCli(event.totalBytes);
+        if (event.totalParts > 1) {
+            const shown = Math.max(1, event.part);
+            return `Uploading image… part ${shown}/${event.totalParts} · ${formatBytesForCli(event.uploadedBytes)} / ${total}`;
+        }
+        return `Uploading image… ${total}`;
+    };
+    const redraw = () => {
+        if (!last)
+            return;
+        stream.write(`\r\x1b[K${UPLOAD_SPINNER_FRAMES[frame % UPLOAD_SPINNER_FRAMES.length]} ${label(last)}`);
+    };
+    const stopTimer = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+    const finalize = (line) => {
+        if (finished)
+            return;
+        finished = true;
+        stopTimer();
+        if (isTty) {
+            // Clear the in-place spinner line, then leave a clean final line behind.
+            stream.write(`\r\x1b[K${line}\n`);
+        }
+        else {
+            stream.write(`${line}\n`);
+        }
+    };
+    const onProgress = (event) => {
+        if (finished)
+            return;
+        last = event;
+        if (event.phase === "done") {
+            finalize(`✓ Uploaded image (${formatBytesForCli(event.totalBytes)})`);
+            return;
+        }
+        if (isTty) {
+            if (event.phase === "start") {
+                // Animate a spinner so a single long part still visibly moves.
+                redraw();
+                timer = setInterval(() => {
+                    frame += 1;
+                    redraw();
+                }, 120);
+                if (typeof timer.unref === "function")
+                    timer.unref();
+            }
+            else {
+                redraw();
+            }
+            return;
+        }
+        // Non-TTY: one line at start, and one per part boundary for multipart uploads.
+        if (event.phase === "start") {
+            stream.write(`Uploading image (${formatBytesForCli(event.totalBytes)})…\n`);
+        }
+        else if (event.totalParts > 1) {
+            stream.write(`Uploaded part ${event.part}/${event.totalParts} (${formatBytesForCli(event.uploadedBytes)} / ${formatBytesForCli(event.totalBytes)})\n`);
+        }
+    };
+    return {
+        onProgress,
+        // Structural cleanup for the failure path: no-op after done; otherwise stop
+        // the timer and close the line. Skip the "✗" line when no progress was ever
+        // shown (a pre-upload validation throw) — the real error prints right after,
+        // and a failure label for an upload that never started would mislabel it.
+        stop() {
+            if (finished)
+                return;
+            if (last) {
+                finalize("✗ Image upload failed");
+                return;
+            }
+            finished = true;
+            stopTimer();
+        },
+    };
 }
 function buildContainerImage(directory) {
     const root = path.resolve(directory);
@@ -919,6 +1239,66 @@ async function expectOk(response, action) {
     const text = await response.text();
     throw new Error(`Failed to ${action}: ${response.status} ${text}`);
 }
+// #374: Node's fetch rejects network-level failures (no HTTP response at all)
+// as a generic "fetch failed" TypeError and stashes the real reason on
+// `error.cause` (e.g. { code: "EPIPE" }). That code never reaches the user.
+// Pull it out so a failed deploy explains itself. This is the fetch-*rejection*
+// path only — expectOk already handles non-2xx HTTP responses, which are
+// resolved fetches and never surface here.
+function describeFetchCause(error) {
+    if (!(error instanceof Error) || error.cause == null) {
+        return null;
+    }
+    const cause = error.cause;
+    if (typeof cause.code === "string" && cause.code) {
+        return cause.code;
+    }
+    if (typeof cause.message === "string" && cause.message) {
+        return cause.message;
+    }
+    return null;
+}
+// Short, platform-opaque hint for a network cause. Keyed on the Node/undici
+// error code; falls back to a generic connectivity nudge for anything else
+// (including bare cause messages).
+function fetchCauseHint(cause) {
+    switch (cause) {
+        case "EPIPE":
+        case "ECONNRESET":
+            return "connection reset — check your connection and retry; large images upload slowly";
+        case "UND_ERR_HEADERS_TIMEOUT":
+        case "UND_ERR_CONNECT_TIMEOUT":
+        case "UND_ERR_BODY_TIMEOUT":
+        case "ETIMEDOUT":
+            return "the connection timed out — check your connection and retry";
+        case "ENOTFOUND":
+        case "EAI_AGAIN":
+            return "could not resolve the host — check your connection and the API URL";
+        case "ECONNREFUSED":
+            return "the server refused the connection — check the API URL and retry";
+        default:
+            return "check your connection and retry";
+    }
+}
+// Wrap the deploy flow's fetch so a network-level rejection carries its cause
+// code + hint instead of a bare "fetch failed". Only rejections are enriched;
+// resolved responses (including non-2xx, handled by expectOk) pass straight
+// through, and any non-network error is rethrown verbatim with its cause
+// preserved for debugging.
+function withFetchDiagnostics(fetchFn) {
+    return async (input, init) => {
+        try {
+            return await fetchFn(input, init);
+        }
+        catch (error) {
+            const cause = describeFetchCause(error);
+            if (!cause) {
+                throw error;
+            }
+            throw new Error(`Network request failed: ${cause} — ${fetchCauseHint(cause)}`, { cause: error });
+        }
+    };
+}
 function normalizeApiUrl(value) {
     return value.replace(/\/+$/g, "");
 }
@@ -1455,7 +1835,13 @@ async function runLogsCommand(command) {
         if (command.lines !== undefined) {
             lines = lines.slice(-command.lines);
         }
+        // The reason above is the platform's verdict; this block is the captured
+        // failure detail — the container's own output when the placement could
+        // obtain it (#403), else the build/push or health detail. Neutral label:
+        // the server doesn't tell us which, so don't claim app output when it may
+        // be platform output.
         console.log("");
+        console.log("Failure log:");
         for (const line of lines) {
             console.log(line);
         }

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "ninepm",
-  "version": "0.26.0",
+  "version": "0.30.0",
   "description": "CLI for deploying built apps to 9pm.ai.",
+  "homepage": "https://9pm.ai",
+  "keywords": [
+    "9pm",
+    "deploy",
+    "cli"
+  ],
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -21,19 +27,10 @@
     "README.md",
     "LICENSE.md"
   ],
-  "scripts": {
-    "generate": "node ../../scripts/generate-cli-package.mjs",
-    "prebuild": "node ../../scripts/generate-cli-package.mjs",
-    "build": "tsc -p tsconfig.json",
-    "pretypecheck": "node ../../scripts/generate-cli-package.mjs",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "prepack": "npm run build"
-  },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.18.1"
   },
-  "devDependencies": {
-    "@types/node": "^24.10.1",
-    "typescript": "^5.9.3"
+  "dependencies": {
+    "undici": "^7.10.0"
   }
 }