ninepm 0.34.0 → 0.36.0

package/dist/index.d.ts

@@ -113,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.34.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;
@@ -244,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;
 }>;
@@ -258,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<{
@@ -294,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;
@@ -466,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.34.0";
+export const CLI_VERSION = "0.36.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -755,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;
@@ -763,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`, {
@@ -1149,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;
@@ -1167,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) {
@@ -1238,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"))) {
@@ -1291,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.
@@ -2538,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));
@@ -2576,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() {

package/package.json

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