ninepm 0.32.0 → 0.36.0

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export interface DeployOptions {
     environment?: string;
     withDatabase?: boolean;
     withAuth?: boolean;
+    withEmail?: boolean;
     databaseName?: string;
     bindingName?: string;
     runtime?: AppRuntime;
@@ -112,7 +113,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.32.0";
+export declare const CLI_VERSION = "0.36.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface CredentialDiagnostics {
     platform: NodeJS.Platform;
@@ -183,6 +184,9 @@ export declare class DeployError extends Error {
     constructor(message: string, slug: string | undefined);
 }
 export declare function deployDirectory(initialOptions: DeployOptions): Promise<DeployResult>;
+export type ApiReachability = "reachable" | "blocked";
+export declare function probeApiReachability(apiUrl: string, fetchFn: typeof fetch, timeoutMs?: number): Promise<ApiReachability>;
+export declare function apiUnreachableGuidance(apiUrl: string): string;
 export declare function checkDeployDirectory(options: DeployOptions): Promise<DeployCheckResult>;
 export declare function whoami(options: ApiOptions): Promise<WhoamiResult>;
 export declare function publicWhoamiResult(result: WhoamiResult): PublicWhoamiResult;
@@ -240,12 +244,19 @@ export interface ListSitesResult {
 }
 export declare function listSites(options: ApiOptions): Promise<ListSitesResult>;
 export declare function deleteSite(options: DeleteSiteOptions): Promise<DeletedSiteResult>;
+export interface DeviceAuthFeedbackOptions {
+    progressStream?: NodeJS.WriteStream;
+    openBrowserFn?: (url: string) => BrowserOpenResult;
+    storeCredentialFn?: (token: string, options: {
+        allowFileFallback?: boolean | undefined;
+    }) => string;
+}
 export declare function loginDevice(options: {
     apiUrl: string;
     fetchFn?: FetchLike;
     machineName?: string;
     allowFileCredentialStore?: boolean;
-}): Promise<{
+} & DeviceAuthFeedbackOptions): Promise<{
     email?: string;
     storage: string;
 }>;
@@ -254,10 +265,11 @@ export declare function signupDevice(options: {
     fetchFn?: FetchLike;
     machineName?: string;
     allowFileCredentialStore?: boolean;
-}): Promise<{
+} & DeviceAuthFeedbackOptions): Promise<{
     email?: string;
     storage: string;
 }>;
+export declare function expiredDeviceAuthMessage(purpose: string, userCode: string, lifetimeMs: number, verificationUri: string): string;
 export declare function listManagedFiles(options: FileCommandOptions): Promise<ManagedFileListResult>;
 export declare function putManagedFile(options: FilePutOptions): Promise<ManagedFilePutResult>;
 export declare function getManagedFile(options: FileGetOptions): Promise<{
@@ -290,6 +302,11 @@ export interface UploadProgressReporter {
     stop(): void;
 }
 export declare function createUploadProgressReporter(stream?: NodeJS.WriteStream): UploadProgressReporter;
+export interface DeviceAuthProgressReporter {
+    tick(remainingMs: number): void;
+    stop(): void;
+}
+export declare function createDeviceAuthProgressReporter(stream?: NodeJS.WriteStream): DeviceAuthProgressReporter;
 type CliCommand = {
     kind: "deploy";
     options: DeployOptions;
@@ -462,6 +479,13 @@ export declare function parseEnvFileEntries(content: string, kind: "secret" | "v
     kind: "secret" | "var";
 }>;
 export declare function credentialDiagnostics(): CredentialDiagnostics;
+export type BrowserOpenResult = "opened" | "failed" | "unknown";
+export declare function classifyBrowserOpen(input: {
+    platform: string;
+    status: number | null;
+    error?: unknown;
+}): BrowserOpenResult;
+export declare function hasNoGraphicalDisplay(platform: string, env: Record<string, string | undefined>): boolean;
 export declare class UsageError extends Error {
 }
 export {};

package/dist/index.js

@@ -12,7 +12,7 @@ import { MAX_DEPLOY_DESCRIPTION_LENGTH, normalizeDeployDescription } from "./dep
 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.32.0";
+export const CLI_VERSION = "0.36.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -229,6 +229,44 @@ export async function deployDirectory(initialOptions) {
         throw new DeployError(error instanceof Error ? error.message : String(error), slugHolder.slug);
     }
 }
+// Cheap unauthenticated probe of the control-plane API before a deploy. The
+// sandbox egress proxy blocks at CONNECT, so ANY HTTP response (even a 5xx)
+// proves the host is reachable — only a thrown/aborted request signals a block.
+// A tight timeout keeps the reachable path fast and the blocked path from
+// hanging.
+export async function probeApiReachability(apiUrl, fetchFn, 
+// Comfortably above /health tail latency so a slow-but-reachable link isn't
+// aborted and misread as blocked; the reachable path returns well under this.
+timeoutMs = 5000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        await fetchFn(`${apiUrl}/health`, { method: "GET", signal: controller.signal });
+        return "reachable";
+    }
+    catch {
+        return "blocked";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Actionable message when the API host can't be reached — the two fixes for a
+// default ("Trusted") sandbox, matching the #258 byte-channel design.
+export function apiUnreachableGuidance(apiUrl) {
+    let host = apiUrl;
+    try {
+        host = new URL(apiUrl).host;
+    }
+    catch {
+        // keep the raw value if it isn't a full URL
+    }
+    return (`Can't reach ${host}. Most often a default ("Trusted") cloud sandbox is blocking the host, ` +
+        `but it can also be a transient network issue or a ${host} outage (check status if the fixes below don't help). ` +
+        `If it's the sandbox, fix it either way:\n` +
+        `  1. Add ${host} to your environment's Allowed domains (switch network access to Custom), then re-run.\n` +
+        `  2. Or deploy through the 9pm MCP connector — your agent can enable it and deploy with the 9pm tools, no network change needed.`);
+}
 async function runDeploy(initialOptions, slugHolder) {
     const options = prepareFrameworkDeploy(initialOptions);
     // #374: enrich network-level fetch rejections (EPIPE, header timeouts, …)
@@ -259,6 +297,9 @@ async function runDeploy(initialOptions, slugHolder) {
             if (options.withAuth) {
                 await enableEndUserAuth(fetchFn, apiUrl, options.token, project.id);
             }
+            if (options.withEmail) {
+                await enableAppEmail(fetchFn, apiUrl, options.token, project.id);
+            }
             const created = await createDeployment(fetchFn, apiUrl, options.token, project.id, {
                 files: [],
                 environment: options.environment ?? "production",
@@ -385,6 +426,9 @@ async function runDeploy(initialOptions, slugHolder) {
     if (options.withAuth) {
         await enableEndUserAuth(fetchFn, apiUrl, options.token, project.id);
     }
+    if (options.withEmail) {
+        await enableAppEmail(fetchFn, apiUrl, options.token, project.id);
+    }
     const created = await createDeployment(fetchFn, apiUrl, options.token, project.id, {
         files: manifest,
         environment: options.environment ?? "production",
@@ -711,6 +755,12 @@ async function deviceAuthFlow(options) {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ machineName: options.machineName ?? os.hostname(), purpose: options.purpose }),
     });
+    // The control plane refuses a signup it knows can never be approved (#507) with
+    // a message written for the tester. Surface it alone and stop here, rather than
+    // opening a browser and polling for something that will never arrive.
+    if (!startResponse.ok) {
+        throw new Error(await apiErrorMessage(startResponse, `start device ${options.purpose}`));
+    }
     const start = await expectJson(startResponse, `start device ${options.purpose}`);
     const userCode = start.user_code ?? start.code;
     const deviceCode = start.device_code;
@@ -719,29 +769,104 @@ async function deviceAuthFlow(options) {
     }
     console.log(`Open ${start.verification_uri}`);
     console.log(`Device code: ${userCode}`);
-    openBrowser(start.verification_uri);
+    // Everything new below goes to stderr (#509): stdout keeps exactly the two
+    // lines above plus the caller's unchanged result line, so anything already
+    // reading it is unaffected.
+    const progressStream = options.progressStream ?? process.stderr;
+    const browser = (options.openBrowserFn ?? openBrowser)(start.verification_uri);
+    if (browser === "failed") {
+        // Say it the moment it happens. A swallowed browser failure used to look
+        // exactly like a flow nobody had approved yet.
+        progressStream.write("Could not open a browser automatically.\n");
+    }
+    // Stated on every device auth, not only after a failure: the printed URL
+    // carries the code, so opening it anywhere finishes the flow. That recovery
+    // path has to be known before it is needed, not discovered by guesswork.
+    progressStream.write("Open the URL above in any browser — on this machine or another — to approve this device.\n");
     const deadline = Date.now() + start.expires_in * 1000;
     const intervalMs = Math.max(1, start.interval ?? 2) * 1000;
-    while (Date.now() < deadline) {
-        await sleep(intervalMs);
-        const pollResponse = await fetchFn(`${apiUrl}/v1/oauth/device/poll`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ code: deviceCode }),
-        });
-        if (pollResponse.status === 400) {
-            continue;
-        }
-        if (pollResponse.status === 410) {
-            const body = await pollResponse.text();
-            throw new Error(`Device ${options.purpose} expired or was denied: ${body}`);
+    // stop() in a finally so no outcome — approval, denial, network throw,
+    // expiry — can leave the spinner timer alive or the line half-drawn.
+    const progress = createDeviceAuthProgressReporter(progressStream);
+    try {
+        while (Date.now() < deadline) {
+            // Tick before the sleep so the first feedback is immediate rather than
+            // one poll interval late. Remaining time is derived from the deadline the
+            // server's expires_in produced, never from a CLI-side constant.
+            progress.tick(deadline - Date.now());
+            await sleep(intervalMs);
+            const pollResponse = await fetchFn(`${apiUrl}/v1/oauth/device/poll`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ code: deviceCode }),
+            });
+            if (pollResponse.status === 400) {
+                continue;
+            }
+            if (pollResponse.status === 410) {
+                // The server distinguishes three terminal states behind this one status
+                // (expired / denied / consumed); the old branch collapsed them into one
+                // message and appended the raw JSON envelope. It also swallowed the
+                // actionable expiry guidance below: the server starts the clock before the
+                // client computes `deadline`, so a login left unapproved almost always ends
+                // HERE rather than by the loop running out — which made that guidance
+                // unreachable in the normal case (#514 review).
+                const state = await deviceTerminalState(pollResponse);
+                if (state === "denied") {
+                    throw new Error(`Device ${options.purpose} was declined in the browser. ` +
+                        `Run "9pm ${options.purpose}" again if that was not intended.`);
+                }
+                if (state === "consumed") {
+                    throw new Error(`Device ${options.purpose} code ${userCode} was already used. ` +
+                        `Run "9pm ${options.purpose}" again to get a fresh code.`);
+                }
+                // "expired", and anything unrecognised: expiry is what a 410 means here by
+                // default, and the guidance is useful either way.
+                throw new Error(expiredDeviceAuthMessage(options.purpose, userCode, start.expires_in * 1000, start.verification_uri));
+            }
+            const poll = await expectJson(pollResponse, `poll device ${options.purpose}`);
+            // Retire the spinner the moment approval lands, BEFORE credential storage
+            // and the account lookup. storeCredential can fall back to plaintext and
+            // warn on stderr, and whoami is an awaited round trip — either would have
+            // its output appended to an unterminated spinner line, and the redraw timer
+            // could fire again underneath it, corrupting the tail of a *successful*
+            // login (#514 review). stop() is idempotent, so the finally below stays as
+            // the fallback for every other exit path.
+            progress.stop();
+            const storage = (options.storeCredentialFn ?? storeCredential)(poll.token, {
+                allowFileFallback: options.allowFileCredentialStore,
+            });
+            const me = await whoami({ apiUrl, token: poll.token, fetchFn });
+            return { email: me.user.email, storage };
         }
-        const poll = await expectJson(pollResponse, `poll device ${options.purpose}`);
-        const storage = storeCredential(poll.token, { allowFileFallback: options.allowFileCredentialStore });
-        const me = await whoami({ apiUrl, token: poll.token, fetchFn });
-        return { email: me.user.email, storage };
     }
-    throw new Error(`Device ${options.purpose} expired before approval.`);
+    finally {
+        progress.stop();
+    }
+    // Reached only when the client's own deadline elapses without the server having
+    // said anything terminal — rarer than the 410 route above, but it must say the
+    // same thing, so both share one message.
+    throw new Error(expiredDeviceAuthMessage(options.purpose, userCode, start.expires_in * 1000, start.verification_uri));
+}
+// The actionable timeout guidance, shared by both routes out of an unapproved
+// device flow (the server's 410 and the client's own deadline) so they can never
+// drift into saying different things.
+export function expiredDeviceAuthMessage(purpose, userCode, lifetimeMs, verificationUri) {
+    return (`Device ${purpose} expired: code ${userCode} was not approved within ${formatRemainingForCli(lifetimeMs)}. ` +
+        `Run "9pm ${purpose}" again, then open the printed URL in any browser — on this machine or another — to approve it. ` +
+        `If no page ever loaded, check that ${verificationUri} is reachable from this network.`);
+}
+// Which terminal state the control plane meant by its 410. Returns "" when the
+// body is not the expected envelope, so callers fall back rather than guess.
+async function deviceTerminalState(response) {
+    const text = await response.text();
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.state === "string" ? parsed.state : "";
+    }
+    catch {
+        return "";
+    }
 }
 async function createProject(fetchFn, apiUrl, token, body) {
     const response = await fetchFn(`${apiUrl}/v1/sites`, {
@@ -835,6 +960,14 @@ async function enableEndUserAuth(fetchFn, apiUrl, token, projectId) {
     });
     await expectJson(response, "enable end-user auth");
 }
+async function enableAppEmail(fetchFn, apiUrl, token, projectId) {
+    const response = await fetchFn(`${apiUrl}/v1/sites/${encodeURIComponent(projectId)}/email/enable`, {
+        method: "POST",
+        headers: jsonHeaders(token),
+        body: "{}",
+    });
+    await expectJson(response, "enable app email");
+}
 async function createDeployment(fetchFn, apiUrl, token, projectId, body) {
     const response = await fetchFn(`${apiUrl}/v1/sites/${encodeURIComponent(projectId)}/deployments`, {
         method: "POST",
@@ -1097,7 +1230,8 @@ export async function uploadContainerImage(fetchFn, imagePath, upload, retry = C
         await dispatcher.close().catch(() => { });
     }
 }
-const UPLOAD_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+// Shared by every in-place stderr reporter in this file; do not duplicate.
+const CLI_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export function createUploadProgressReporter(stream = process.stderr) {
     const isTty = stream.isTTY === true;
     let timer;
@@ -1115,7 +1249,7 @@ export function createUploadProgressReporter(stream = process.stderr) {
     const redraw = () => {
         if (!last)
             return;
-        stream.write(`\r\x1b[K${UPLOAD_SPINNER_FRAMES[frame % UPLOAD_SPINNER_FRAMES.length]} ${label(last)}`);
+        stream.write(`\r\x1b[K${CLI_SPINNER_FRAMES[frame % CLI_SPINNER_FRAMES.length]} ${label(last)}`);
     };
     const stopTimer = () => {
         if (timer) {
@@ -1186,6 +1320,72 @@ export function createUploadProgressReporter(stream = process.stderr) {
         },
     };
 }
+// Off-TTY ceiling: at most one line per 30s of the window (~20 lines over 600s).
+const DEVICE_AUTH_PROGRESS_LINE_INTERVAL_MS = 30_000;
+export function createDeviceAuthProgressReporter(stream = process.stderr) {
+    const isTty = stream.isTTY === true;
+    let timer;
+    let frame = 0;
+    let finished = false;
+    let remainingMs;
+    let lastLineRemainingMs;
+    const label = (ms) => `Waiting for approval… ${formatRemainingForCli(ms)} left`;
+    const redraw = () => {
+        if (remainingMs === undefined)
+            return;
+        stream.write(`\r\x1b[K${CLI_SPINNER_FRAMES[frame % CLI_SPINNER_FRAMES.length]} ${label(remainingMs)}`);
+    };
+    const stopTimer = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+    return {
+        tick(nextRemainingMs) {
+            if (finished)
+                return;
+            const first = remainingMs === undefined;
+            remainingMs = nextRemainingMs;
+            if (isTty) {
+                redraw();
+                if (first) {
+                    // Sub-second liveness: the countdown itself only advances on a poll
+                    // boundary, which would look frozen for a whole interval at a time.
+                    timer = setInterval(() => {
+                        frame += 1;
+                        redraw();
+                    }, 120);
+                    // Never hold the process open on the reporter's account.
+                    if (typeof timer.unref === "function")
+                        timer.unref();
+                }
+                return;
+            }
+            if (lastLineRemainingMs !== undefined && lastLineRemainingMs - nextRemainingMs < DEVICE_AUTH_PROGRESS_LINE_INTERVAL_MS) {
+                return;
+            }
+            lastLineRemainingMs = nextRemainingMs;
+            stream.write(`${label(nextRemainingMs)}\n`);
+        },
+        // Idempotent; called from a finally around the poll loop. On a TTY it erases
+        // the in-place line and writes nothing in its place: unlike the upload
+        // reporter this deliberately leaves no ✓/✗ summary, because the flow's own
+        // success line or its thrown error is the outcome, and a second line here
+        // would be exactly the leftover progress noise #509 forbids. Off-TTY the
+        // lines are already terminated, and before the first tick there is nothing
+        // to clean up.
+        stop() {
+            if (finished)
+                return;
+            finished = true;
+            stopTimer();
+            if (isTty && remainingMs !== undefined) {
+                stream.write("\r\x1b[K");
+            }
+        },
+    };
+}
 function buildContainerImage(directory) {
     const root = path.resolve(directory);
     if (!existsSync(path.join(root, "Dockerfile"))) {
@@ -1239,6 +1439,25 @@ async function expectOk(response, action) {
     const text = await response.text();
     throw new Error(`Failed to ${action}: ${response.status} ${text}`);
 }
+// Pull the control plane's own message out of its {error:{code,message}} envelope,
+// for the few refusals whose message is written for the tester and is the whole
+// point of the response (e.g. device signup being unavailable, #507). Dumping the
+// raw envelope the way expectOk does would bury it in JSON. Falls back to
+// expectOk's text when the body isn't that shape, so this can never lose detail.
+async function apiErrorMessage(response, action) {
+    const text = await response.text();
+    try {
+        const parsed = JSON.parse(text);
+        const message = parsed.error?.message;
+        if (typeof message === "string" && message.trim()) {
+            return message.trim();
+        }
+    }
+    catch {
+        // Not JSON (proxy error page, empty body) — fall through to the raw form.
+    }
+    return `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.
@@ -1323,6 +1542,8 @@ const VALID_DEPLOY_FLAGS = new Set([
     "db",
     "with-auth",
     "auth",
+    "with-email",
+    "email",
     "name",
     "slug",
     "description",
@@ -1442,9 +1663,12 @@ export function parseArgs(argv) {
         directory,
         apiUrl: readApiUrl(flags, DEFAULT_API_URL),
         token: token ?? "",
-        // --with-auth implies a managed database (somewhere to store per-user data).
-        withDatabase: flags.has("with-db") || flags.has("db") || flags.has("with-auth") || flags.has("auth"),
-        withAuth: flags.has("with-auth") || flags.has("auth"),
+        // --with-auth implies a managed database (somewhere to store per-user data);
+        // --with-email implies --with-auth (invitations need managed accounts), so it
+        // pulls in the database too.
+        withDatabase: flags.has("with-db") || flags.has("db") || flags.has("with-auth") || flags.has("auth") || flags.has("with-email") || flags.has("email"),
+        withAuth: flags.has("with-auth") || flags.has("auth") || flags.has("with-email") || flags.has("email"),
+        withEmail: flags.has("with-email") || flags.has("email"),
         check,
     };
     const name = readStringFlag(flags, "name");
@@ -2481,10 +2705,45 @@ function deleteLinuxSecretServiceCredential() {
     const result = spawnSync("secret-tool", ["clear", "service", TOKEN_SERVICE, "account", TOKEN_ACCOUNT], { encoding: "utf8" });
     return result.status === 0;
 }
+// Pure and exported so the per-platform mapping is unit-testable without
+// spawning anything (#509). A spawn error or a non-zero exit is a real failure.
+// A zero exit means the handler ran — except on Windows, where the launcher
+// returns 0 whether or not anything actually rendered the page, so "opened"
+// there would be a claim we cannot back: report "unknown" and say nothing about
+// the browser rather than mislead. The unconditional paste-the-URL hint covers
+// that case anyway.
+export function classifyBrowserOpen(input) {
+    if (input.error !== undefined) {
+        return "failed";
+    }
+    if (input.status !== 0) {
+        return "failed";
+    }
+    return input.platform === "win32" ? "unknown" : "opened";
+}
+// Headless boxes, containers and remote SSH sessions — the cases where the
+// browser handoff is least likely to work, and where `xdg-open` often exits 0
+// having done nothing, so the absence of any display is the stronger signal.
+// Pure and exported for the same reason as classifyBrowserOpen: the branch has
+// to be assertable without a real platform or a real spawn. Note
+// noUncheckedIndexedAccess makes these `string | undefined`; an empty value is
+// as useless as an absent one, so test truthiness, not presence.
+export function hasNoGraphicalDisplay(platform, env) {
+    return platform === "linux" && !env["DISPLAY"] && !env["WAYLAND_DISPLAY"];
+}
 function openBrowser(url) {
+    if (hasNoGraphicalDisplay(process.platform, process.env)) {
+        return "failed";
+    }
     const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    spawnSync(command, args, { stdio: "ignore" });
+    // stdio stays ignored: a browser's own chatter must not pollute the terminal.
+    const result = spawnSync(command, args, { stdio: "ignore" });
+    return classifyBrowserOpen({
+        platform: process.platform,
+        status: result.status,
+        ...(result.error ? { error: result.error } : {}),
+    });
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -2519,6 +2778,16 @@ function formatBytesForCli(value) {
     }
     return `${(bytes / 1024 / 1024 / 1024).toFixed(1)}GB`;
 }
+// Human remaining time for the device-auth wait (#509). Ceil so a window with
+// any time left never reads "0s", and clamp so a passed deadline reads "0s"
+// rather than a negative.
+function formatRemainingForCli(value) {
+    const totalSeconds = Math.max(0, Math.ceil(value / 1000));
+    if (totalSeconds < 60) {
+        return `${totalSeconds}s`;
+    }
+    return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`;
+}
 export class UsageError extends Error {
 }
 async function main() {
@@ -2549,6 +2818,16 @@ async function main() {
                 }
                 return;
             }
+            // Fail fast with actionable guidance when the API host is unreachable — a
+            // default ("Trusted") cloud sandbox blocks it at CONNECT, and the deploy
+            // would otherwise hang/error cryptically on the first request (#83/#258).
+            // Real invocations only; a programmatic caller injecting fetchFn opts out.
+            if (!command.options.fetchFn &&
+                (await probeApiReachability(normalizeApiUrl(command.options.apiUrl), fetch)) === "blocked") {
+                console.error(apiUnreachableGuidance(command.options.apiUrl));
+                process.exitCode = 1;
+                return;
+            }
             let result;
             try {
                 result = await deployDirectory(command.options);
@@ -2829,7 +3108,7 @@ async function runFilesCommand(command) {
 function printUsage() {
     console.log(`Usage:
   9pm --version
-  9pm deploy [directory] --name <site-name> [--slug <slug>] [--description "<note>"] [--with-db] [--with-auth]
+  9pm deploy [directory] --name <site-name> [--slug <slug>] [--description "<note>"] [--with-db] [--with-auth] [--with-email]
   9pm deploy [directory] --runtime worker --entry src/index.js [--with-db]
   9pm deploy [directory] --runtime container --port 8080 [--health-path /health] [--region auto] [--with-db] [--always-on] [--volume <gb> | --no-volume] [--cpus <n>] [--memory <size>]
   9pm deploy [directory]                   framework projects (Next.js, Vite) are detected and built automatically; --no-build skips
@@ -2877,6 +3156,7 @@ Container deploys:
   The app must listen on 0.0.0.0:$PORT or the selected --port. Use --health-path for a cheap readiness endpoint.
   With --with-db, containers receive NINEPM_SQL_URL and NINEPM_DB_BINDINGS for the managed SQL bridge.
   With --with-auth, the app gets 9pm-managed end-user accounts (email one-time codes); it implies --with-db and is one-way (enable-only).
+  With --with-email, a signed-in end user can send app invitation emails; it implies --with-auth and works on public apps only.
   9pm env set <app> KEY=value [KEY2=value2 ...] [--var]   (secret by default; --var = readable config)
   9pm env set <app> --from-file <path> [--var]            (KEY=value lines; # comments, export prefix, quotes ok)
   9pm env set <app> <NAME> --stdin [--var]                (value read verbatim from stdin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ninepm",
-  "version": "0.32.0",
+  "version": "0.36.0",
   "description": "CLI for deploying built apps to 9pm.ai.",
   "homepage": "https://9pm.ai",
   "keywords": [