clearcote 0.39.0 → 0.40.1

package/README.md

@@ -140,6 +140,8 @@ npx clearcote cloud run|sessions|stop|events|recording|profile sync|webhooks ...
 
 `info` never downloads: it reports the SDK, the cached builds, which engine features the binary supports, a launch test (skipped with `--quick`), licence seats, fonts and missing system libraries.
 
+Windows: when a cached build cannot start from the cache (`spawn UNKNOWN`, "the side-by-side configuration is incorrect"; this happens when the SDK runs inside an MSIX-packaged app, whose writes to `%LOCALAPPDATA%` Windows redirects), launches use one copy of that build in `~/.clearcote/recovered/` instead, made once and reused by every later launch from Python or Node. `clear-cache` removes those copies too.
+
 ### Engine options (PRO 152 r22+)
 
 | Option | Effect |

package/dist/cli-commands.d.ts

@@ -1,4 +1,5 @@
 import { type SessionSeats } from "./index.js";
+import { type LicenseExpiry } from "./license.js";
 import { type Json } from "./cloud.js";
 export declare const USAGE: string;
 /** `clearcote cloud --help`. Kept byte-identical to CLOUD_USAGE in the Python SDK's _commands.py. */
@@ -13,6 +14,7 @@ export interface InfoReport {
     license: {
         source: string;
         key?: string;
+        expiry?: LicenseExpiry;
         seats?: SessionSeats;
     };
     binary: {
@@ -25,12 +27,15 @@ export interface InfoReport {
         }>;
         pinnedFree: string;
         releaseChannel: string;
+        /** Why `path` is the build launch() would run for the current licence state (or why there is none). */
+        selectedBy?: string;
     };
     engineFeatures?: Record<string, boolean>;
     launch?: {
         tested: boolean;
         ok?: boolean;
         version?: string;
+        build?: string;
         error?: string;
         missingLibs?: string[];
         reason?: string;
@@ -51,10 +56,70 @@ export interface InfoReport {
         };
     };
 }
+/** Whether a cached licensed build's tag (pro-<version>-r<N>) is what `version` selects: a revision ("r30",
+ * "154.0.8037.57-r30"), an exact version (its newest revision), a major ("154"), or "latest". */
+export declare function proTagMatches(tag: string, version: string): boolean;
+/**
+ * The build launch() would run for the current licence state, from what is already cached (`info` never
+ * downloads). CLEARCOTE_BINARY wins. A version selector (CLEARCOTE_BROWSER_VERSION) is resolved the way
+ * launch() resolves it -- through the version catalog (the bundled copy when `offline`), a licensed revision
+ * straight to the licensed builds -- and picks the cached build it names. Otherwise, with a licence key,
+ * launch() runs a licensed build: the newest one cached (launch() itself asks the licence server, which may
+ * name a newer one). Without a key it runs the open build this SDK pins (the newest cached open build with
+ * CLEARCOTE_AUTO_UPDATE). A cached licensed build is never picked for a keyless setup: it cannot run without
+ * a key, which is what made the old "newest cached build" launch test fail for open-build users.
+ */
+export declare function launchBuild(cached: Array<{
+    tag: string;
+    path: string;
+}>, envBinary?: string, licenseKey?: string, autoUpdate?: boolean, version?: string, offline?: boolean): Promise<{
+    pick?: {
+        path: string;
+        tag?: string;
+    };
+    selectedBy: string;
+}>;
 export declare function buildInfo(flags: {
     quick?: boolean;
     proxy?: string;
-}): Promise<InfoReport>;
+}, launchFn?: (o: Record<string, unknown>) => Promise<{
+    version(): string;
+    close(): Promise<void>;
+}>): Promise<InfoReport>;
+/**
+ * `clearcote login --device`: show a link and a short code, wait for the approval in the browser, then
+ * save the key it issues exactly as `clearcote login <key>` does. The key is never printed.
+ * Instructions go to stderr and the result to stdout, like the paste login's prompt. Output and exit
+ * codes match the Python CLI (test/device-login.test.ts).
+ *
+ * Ctrl-C is deterministic: it never tears down a request already on its way (its answer may be the key,
+ * which the server hands out once). Ctrl-C before the key arrives saves nothing (exit 130); one that lands
+ * while the request that brings the key is in flight still saves it, and says so.
+ */
+export declare function deviceLogin(opts?: {
+    sleep?: (s: number, signal?: AbortSignal) => Promise<void>;
+    clock?: () => number;
+}): Promise<void>;
+/** The parts of a TTY input stream readHidden uses. */
+export interface HiddenInput {
+    isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    setEncoding(enc: BufferEncoding): unknown;
+    on(ev: "data", fn: (chunk: string) => void): unknown;
+    removeListener(ev: "data", fn: (chunk: string) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+/**
+ * Read one line from a terminal without echoing it: raw mode, so the terminal shows nothing of what is typed
+ * or pasted (a screen share, a recording or the scrollback must not show a key). Enter ends it, Backspace
+ * edits, Ctrl-C rejects with "cancelled". Terminal escape sequences (bracketed paste) are dropped.
+ */
+export declare function readHidden(input: HiddenInput, output: {
+    write(s: string): unknown;
+}, prompt: string): Promise<string>;
+/** `clearcote <cmd> --help`: that command's lines from USAGE (with their flag sections) and a note. */
+export declare function commandUsage(cmd: string): string;
 export declare function main(argv?: string[]): Promise<void>;
 /** The human summary `clearcote cloud run` prints. */
 export declare function formatRun(run: Json): string[];

package/dist/cli-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../src/cli-commands.ts"],"names":[],"mappings":"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"}

package/dist/cli-commands.js

@@ -4,22 +4,26 @@
 //   clearcote info    [--quick] [--json] [--proxy URL]      diagnostics (alias: doctor)
 //   clearcote update  [--channel preview]                   fetch a newer build if one exists
 //   clearcote clear-cache                                   delete every cached binary
-//   clearcote login   [key]                                 save a licence key (validated first)
+//   clearcote login   [key] | --device                      save a licence key (validated first), or sign in
+//                                                           from a browser and save the key it issues
 //   clearcote logout                                        remove the saved key
 //   clearcote serve   [--port 9222] [--idle-timeout 300] …  multi-identity CDP endpoint
 //   clearcote cloud   run|sessions|stop|events|recording|profile sync|webhooks …  the hosted API
 //
 // `info` never downloads: it reports what is already cached and what a launch would resolve to.
 import { parseArgs } from "node:util";
-import * as readline from "node:readline";
 import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { download, launch, getSessionSeats, saveLicenseKey, removeLicenseKey, licenseKeySource, licenseKeyPath, resolveLicenseKey, resolveGeoDetailed, resolveReleaseChannel, engineSupportsSwitch, serveMultiplex, RELEASE, } from "./index.js";
-import { defaultCacheRoot, listCachedBuilds } from "./download.js";
+import { autoUpdateRequested, defaultCacheRoot, isProRevisionSelector, listCachedBuilds, resolveVersion } from "./download.js";
+import { CATALOG_FALLBACK } from "./release.js";
+import { DeviceLoginError, pollForKey, requestDeviceCode } from "./devicelogin.js";
+import { licenseExpiry, removeLicenseMeta, saveLicenseMeta } from "./license.js";
 import { geoCacheRoot } from "./geoip.js";
 import { GATED_ENGINE_SWITCHES } from "./launchopts.js";
 import { toProxySpec } from "./net.js";
+import { clearRecovered, recoverRoot } from "./winlaunch.js";
 import { Cloud, CloudError, announceHandoff } from "./cloud.js";
 const SDK_VERSION = (() => {
     try {
@@ -37,6 +41,7 @@ USAGE
   clearcote update [--channel stable|preview]
   clearcote clear-cache
   clearcote login [key]
+  clearcote login --device                               (sign in from a browser; no key to paste)
   clearcote logout
   clearcote serve [--port 9222] [--host 127.0.0.1] [--idle-timeout <s>] [--data-dir <dir>]
                   [--max-browsers 16] [--allow-origin <origin>]... [--allow-host <name>]... [--headed]
@@ -97,7 +102,72 @@ function missingSharedLibs(exe) {
     const r = spawnSync("ldd", ["--", exe], { encoding: "utf8" });
     return (r.stdout || "").split("\n").filter((l) => l.includes("not found")).map((l) => l.trim().split(" ")[0]);
 }
-export async function buildInfo(flags) {
+/** Whether a cached licensed build's tag (pro-<version>-r<N>) is what `version` selects: a revision ("r30",
+ * "154.0.8037.57-r30"), an exact version (its newest revision), a major ("154"), or "latest". */
+export function proTagMatches(tag, version) {
+    if (!tag.startsWith("pro-"))
+        return false;
+    const t = tag.slice(4).toLowerCase();
+    const v = String(version).trim().toLowerCase();
+    if (v === "latest" || v === "newest")
+        return true;
+    if (/^r\d+$/.test(v))
+        return t.endsWith(`-${v}`);
+    if (/^\d+$/.test(v))
+        return t.startsWith(`${v}.`);
+    return t === v || t.startsWith(`${v}-`);
+}
+/**
+ * The build launch() would run for the current licence state, from what is already cached (`info` never
+ * downloads). CLEARCOTE_BINARY wins. A version selector (CLEARCOTE_BROWSER_VERSION) is resolved the way
+ * launch() resolves it -- through the version catalog (the bundled copy when `offline`), a licensed revision
+ * straight to the licensed builds -- and picks the cached build it names. Otherwise, with a licence key,
+ * launch() runs a licensed build: the newest one cached (launch() itself asks the licence server, which may
+ * name a newer one). Without a key it runs the open build this SDK pins (the newest cached open build with
+ * CLEARCOTE_AUTO_UPDATE). A cached licensed build is never picked for a keyless setup: it cannot run without
+ * a key, which is what made the old "newest cached build" launch test fail for open-build users.
+ */
+export async function launchBuild(cached, envBinary, licenseKey, autoUpdate = false, version, offline = false) {
+    if (envBinary)
+        return { pick: { path: envBinary }, selectedBy: "CLEARCOTE_BINARY" };
+    const sel = String(version ?? "").trim();
+    if (sel) {
+        const named = `CLEARCOTE_BROWSER_VERSION=${sel}`;
+        let plan;
+        try {
+            plan = licenseKey && isProRevisionSelector(sel)
+                ? { kind: "pro", version: sel }
+                : await resolveVersion(sel, !!licenseKey, true, offline ? CATALOG_FALLBACK : undefined);
+        }
+        catch (e) {
+            return { selectedBy: `${named}: ${e.message.split("\n")[0]}` };
+        }
+        if (plan.kind === "pro") {
+            const m = cached.find((c) => proTagMatches(c.tag, plan.version));
+            return m ? { pick: m, selectedBy: `licensed: the newest cached build ${named} selects` }
+                : { selectedBy: `no licensed build for ${named} is cached — run: clearcote install --version ${sel}` };
+        }
+        const hit = cached.find((c) => c.tag === plan.rel.tag);
+        return hit ? { pick: hit, selectedBy: `open build ${plan.rel.tag} (${named})` }
+            : { selectedBy: `the open build ${plan.rel.tag} (${named}) is not installed — run: clearcote install --version ${sel}` };
+    }
+    if (licenseKey) {
+        const licensed = cached.filter((c) => c.tag.startsWith("pro-"));
+        return licensed.length
+            ? { pick: licensed[0], selectedBy: "licensed: the newest cached licensed build (launch() asks the licence server, which may name a newer one)" }
+            : { selectedBy: "no licensed build is cached — run: clearcote install" };
+    }
+    if (autoUpdate) {
+        const open = cached.filter((c) => !c.tag.startsWith("pro-"));
+        if (open.length)
+            return { pick: open[0], selectedBy: "open build: the newest cached (CLEARCOTE_AUTO_UPDATE)" };
+    }
+    const pinned = cached.find((c) => c.tag === RELEASE.tag);
+    return pinned
+        ? { pick: pinned, selectedBy: `open build pinned by this SDK (${RELEASE.tag})` }
+        : { selectedBy: `the open build this SDK pins (${RELEASE.tag}) is not installed — run: clearcote install` };
+}
+export async function buildInfo(flags, launchFn = launch) {
     const src = licenseKeySource();
     let channel;
     try {
@@ -108,20 +178,24 @@ export async function buildInfo(flags) {
     }
     const cached = listCachedBuilds();
     const envBinary = process.env.CLEARCOTE_BINARY;
-    const pick = envBinary ? { path: envBinary } : cached[0];
+    const { pick, selectedBy } = await launchBuild(cached, envBinary, resolveLicenseKey(), autoUpdateRequested(undefined), process.env.CLEARCOTE_BROWSER_VERSION, !!flags.quick);
     const report = {
         sdk: { version: SDK_VERSION, node: process.version, platform: `${process.platform}-${process.arch}` },
         license: { source: src.source, ...(src.masked ? { key: src.masked } : {}) },
         binary: {
             source: envBinary ? "CLEARCOTE_BINARY" : pick ? "cache" : "none",
             ...(pick ? { path: pick.path } : {}),
-            ...(!envBinary && pick ? { tag: pick.tag } : {}),
+            ...(!envBinary && pick?.tag ? { tag: pick.tag } : {}),
             cached,
             pinnedFree: `${RELEASE.version} (${RELEASE.tag})`,
             releaseChannel: channel,
+            selectedBy,
         },
         geoip: { databaseCached: existsSync(geoDbPath()), path: geoDbPath() },
     };
+    const expiry = licenseExpiry(); // a local record only: no network, so --quick reports it too
+    if (expiry)
+        report.license.expiry = expiry;
     if (pick && existsSync(pick.path)) {
         report.engineFeatures = Object.fromEntries(["proxy-auth", "socks5-credentials", "socks5-udp", ...Object.keys(GATED_ENGINE_SWITCHES).map((s) => s.slice(2))]
             .map((name) => [name, engineSupportsSwitch(pick.path, name)]));
@@ -139,19 +213,19 @@ export async function buildInfo(flags) {
         report.launch = { tested: false, reason: "skipped (--quick)" };
     }
     else if (!pick) {
-        report.launch = { tested: false, reason: "no binary installed — run: clearcote install" };
+        report.launch = { tested: false, reason: cached.length ? selectedBy : "no binary installed — run: clearcote install" };
     }
     else {
         try {
             // cloud: false — this tests the LOCAL install, whatever CLEARCOTE_CLOUD says.
-            const b = await launch({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false, cloud: false });
+            const b = await launchFn({ executablePath: pick.path, headless: true, quiet: true, ephemeralProfile: false, cloud: false });
             const version = b.version();
             await b.close();
-            report.launch = { tested: true, ok: true, version };
+            report.launch = { tested: true, ok: true, version, build: pick.tag ?? pick.path };
         }
         catch (e) {
             const libs = missingSharedLibs(pick.path);
-            report.launch = { tested: true, ok: false, error: e.message.split("\n")[0], ...(libs.length ? { missingLibs: libs } : {}) };
+            report.launch = { tested: true, ok: false, error: e.message.split("\n")[0], build: pick.tag ?? pick.path, ...(libs.length ? { missingLibs: libs } : {}) };
         }
     }
     if (flags.proxy) {
@@ -166,6 +240,9 @@ function printInfo(r) {
     const ok = (b) => (b ? "yes" : "no");
     out(`clearcote SDK   ${r.sdk.version}  (node ${r.sdk.node}, ${r.sdk.platform})`);
     out(`Licence         ${r.license.source === "none" ? "none (free build)" : `${r.license.key} from ${r.license.source}`}`);
+    const exp = r.license.expiry;
+    if (exp && exp.source === "device-login")
+        out(`Expires         ${exp.expiresAt || "never"}  (as reported at device login)`);
     const seats = r.license.seats;
     if (seats) {
         if (seats.state === "ok")
@@ -173,7 +250,16 @@ function printInfo(r) {
         else
             out(`Seats           unavailable: ${seats.reason ?? seats.state}`);
     }
-    out(`Binary          ${r.binary.path ? `${r.binary.path}${r.binary.tag ? `  [${r.binary.tag}]` : ""} (${r.binary.source})` : "not installed — run: clearcote install"}`);
+    if (r.binary.path) {
+        out(`Binary          ${r.binary.path}${r.binary.tag ? `  [${r.binary.tag}]` : ""} (${r.binary.source})`);
+        out(`                launch() runs this one: ${r.binary.selectedBy}`);
+    }
+    else if (r.binary.cached.length) {
+        out(`Binary          none for this setup: ${r.binary.selectedBy}`);
+    }
+    else {
+        out("Binary          not installed — run: clearcote install");
+    }
     out(`Release channel ${r.binary.releaseChannel}`);
     out(`Free pin        ${r.binary.pinnedFree}`);
     if (r.binary.cached.length > 1)
@@ -185,9 +271,9 @@ function printInfo(r) {
         if (!r.launch.tested)
             out(`Launch test     ${r.launch.reason}`);
         else if (r.launch.ok)
-            out(`Launch test     ok (${r.launch.version})`);
+            out(`Launch test     ok (${r.launch.version}) with ${r.launch.build}`);
         else {
-            out(`Launch test     FAILED: ${r.launch.error}`);
+            out(`Launch test     FAILED with ${r.launch.build}: ${r.launch.error}`);
             for (const lib of r.launch.missingLibs ?? [])
                 out(`                missing library: ${lib}`);
         }
@@ -200,14 +286,166 @@ function printInfo(r) {
         out(p.error ? `Proxy geo       FAILED: ${p.error}` : `Proxy geo       exit ${p.exitIp} (${p.country})  timezone ${p.timezone}  language ${p.acceptLanguage}`);
     }
 }
+function err(line = "") {
+    process.stderr.write(line + "\n");
+}
+/**
+ * `clearcote login --device`: show a link and a short code, wait for the approval in the browser, then
+ * save the key it issues exactly as `clearcote login <key>` does. The key is never printed.
+ * Instructions go to stderr and the result to stdout, like the paste login's prompt. Output and exit
+ * codes match the Python CLI (test/device-login.test.ts).
+ *
+ * Ctrl-C is deterministic: it never tears down a request already on its way (its answer may be the key,
+ * which the server hands out once). Ctrl-C before the key arrives saves nothing (exit 130); one that lands
+ * while the request that brings the key is in flight still saves it, and says so.
+ */
+export async function deviceLogin(opts = {}) {
+    const ctrl = new AbortController(); // Ctrl-C: stop between requests; one already sent is answered first
+    const hard = new AbortController(); // a second Ctrl-C: give up on the request in flight too
+    const onSigint = () => {
+        if (ctrl.signal.aborted) {
+            hard.abort();
+            return;
+        }
+        ctrl.abort();
+        err("");
+        err("stopping (a request already sent is answered first; press Ctrl-C again to stop at once)");
+    };
+    process.on("SIGINT", onSigint);
+    let grant;
+    try {
+        const code = await requestDeviceCode();
+        if (ctrl.signal.aborted)
+            throw new DeviceLoginError("cancelled", "cancelled");
+        err("To sign in, open this link in a browser and approve the code shown there:");
+        err("");
+        err(`  ${code.verification_uri_complete}`);
+        err("");
+        err(`Code: ${code.user_code}  (or enter it at ${code.verification_uri})`);
+        err("Waiting for the approval (Ctrl-C to cancel)...");
+        let warned = false;
+        grant = await pollForKey(code, {
+            ...opts,
+            signal: ctrl.signal,
+            abort: hard.signal,
+            onRetry: (reason) => {
+                if (!warned) { // once: a flaky network must not flood the terminal
+                    warned = true;
+                    err(`note: ${reason}; still waiting`);
+                }
+            },
+        });
+    }
+    catch (e) {
+        if (e instanceof DeviceLoginError) {
+            if (e.code === "cancelled")
+                fail("cancelled. Nothing was saved.", 130);
+            if (e.code === "aborted")
+                fail("stopped at once (second Ctrl-C). Nothing was saved.", 130);
+            const again = e.code === "expired_token" || e.code === "outcome_unknown" ? " Run `clearcote login --device` again." : "";
+            fail(`${e.message}. Nothing was saved.${again}`);
+        }
+        throw e;
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+    }
+    const where = saveLicenseKey(grant.licenseKey);
+    saveLicenseMeta(grant.licenseKey, grant.plan, grant.expiresAt);
+    if (grant.accountEmail)
+        out(`Signed in as ${grant.accountEmail}`);
+    out(`saved to ${where}`);
+    out(`plan ${grant.plan || "unknown"}, ${grant.expiresAt ? `expires ${grant.expiresAt}` : "no expiry"}`);
+    if (ctrl.signal.aborted)
+        out("note: Ctrl-C came after the licence server had sent the key, so it was saved anyway");
+    if (process.env.CLEARCOTE_LICENSE_KEY)
+        out("note: CLEARCOTE_LICENSE_KEY is set in this environment and takes precedence over the saved key");
+}
+/**
+ * Read one line from a terminal without echoing it: raw mode, so the terminal shows nothing of what is typed
+ * or pasted (a screen share, a recording or the scrollback must not show a key). Enter ends it, Backspace
+ * edits, Ctrl-C rejects with "cancelled". Terminal escape sequences (bracketed paste) are dropped.
+ */
+export function readHidden(input, output, prompt) {
+    return new Promise((resolve, reject) => {
+        output.write(prompt);
+        let value = "";
+        const finish = (err) => {
+            input.removeListener("data", onData);
+            input.setRawMode?.(false);
+            input.pause();
+            output.write("\n");
+            if (err)
+                reject(err);
+            else
+                resolve(value.replace(/\x1b\[[0-9;]*[~A-Za-z]/g, "").trim());
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n" || ch === "\u0004")
+                    return finish();
+                if (ch === "\u0003")
+                    return finish(new Error("cancelled"));
+                if (ch === "\u007f" || ch === "\b")
+                    value = value.slice(0, -1);
+                else
+                    value += ch;
+            }
+        };
+        input.setRawMode?.(true);
+        input.setEncoding("utf8");
+        input.on("data", onData);
+        input.resume();
+    });
+}
 async function promptKey() {
     if (!process.stdin.isTTY) {
         fail("no key given. Run `clearcote login <key>`, or copy a key from https://www.clearcotelabs.com/dashboard/licenses");
     }
-    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-    const key = await new Promise((resolve) => rl.question("Paste your licence key (https://www.clearcotelabs.com/dashboard/licenses): ", (a) => resolve(a)));
-    rl.close();
-    return key.trim();
+    try {
+        return await readHidden(process.stdin, process.stderr, "Paste your licence key (https://www.clearcotelabs.com/dashboard/licenses; it is not shown): ");
+    }
+    catch {
+        return fail("cancelled. Nothing was saved.", 130);
+    }
+}
+/** What `clearcote <command> --help` adds to that command's USAGE lines. */
+const COMMAND_NOTES = {
+    login: "Saves a licence key to ~/.clearcote/license.key, where every launch finds it.\n"
+        + "  <key>      the key, checked with the licence server first\n"
+        + "  (no key)   asks for it on the terminal; what you paste is not shown\n"
+        + "  --device   sign in from a browser instead: shows a link and a code, and saves the key the\n"
+        + "             site issues once you approve it there. Nothing to copy or paste.",
+    logout: "Removes the saved key (and what device login recorded about it).",
+    info: "Reports the SDK, the licence, the cached builds and what a launch would use. Never downloads.",
+    install: "Downloads and verifies the build a launch would use.",
+    update: "Fetches a newer build if one exists.",
+    "clear-cache": "Deletes every cached browser build (nothing else in the cache directory), and on Windows the " +
+        "recovered copies in ~/.clearcote/recovered.",
+    serve: "A CDP endpoint that gives every connection its own browser and identity.",
+};
+/** `clearcote <cmd> --help`: that command's lines from USAGE (with their flag sections) and a note. */
+export function commandUsage(cmd) {
+    const name = cmd === "doctor" ? "info" : cmd;
+    const lines = USAGE.split("\n");
+    const picked = [];
+    let keep = false;
+    for (const line of lines.slice(lines.indexOf("USAGE") + 1)) {
+        if (!line.trim())
+            break;
+        if (line.startsWith("  clearcote "))
+            keep = line.trim().split(/\s+/)[1] === name;
+        if (keep)
+            picked.push(line);
+    }
+    let text = `USAGE\n${picked.join("\n")}`;
+    if (name === "info") {
+        const flags = lines.slice(lines.indexOf("INFO FLAGS"));
+        const end = flags.indexOf("");
+        text += `\n\n${flags.slice(0, end < 0 ? flags.length : end).join("\n")}`;
+    }
+    const note = COMMAND_NOTES[name];
+    return note ? `clearcote ${name} -- ${note}\n\n${text}` : text;
 }
 function dirSize(p) {
     let total = 0;
@@ -236,6 +474,11 @@ export async function main(argv = process.argv.slice(2)) {
             process.exitCode = code;
         return;
     }
+    const known = ["info", "doctor", "install", "update", "clear-cache", "login", "logout", "serve"];
+    if (known.includes(cmd) && rest.some((a) => a === "-h" || a === "--help")) {
+        out(commandUsage(cmd));
+        return;
+    }
     if (cmd === "info" || cmd === "doctor") {
         const { values } = parseArgs({ args: rest, options: { quick: { type: "boolean" }, "no-launch": { type: "boolean" }, json: { type: "boolean" }, proxy: { type: "string" } } });
         const report = await buildInfo({ quick: !!(values.quick || values["no-launch"]), proxy: values.proxy });
@@ -263,34 +506,49 @@ export async function main(argv = process.argv.slice(2)) {
         const root = defaultCacheRoot();
         if (!existsSync(root)) {
             out(`nothing to clear (${root} does not exist)`);
-            return;
         }
-        // Only build directories: a CLEARCOTE_CACHE pointing at $HOME or a shared directory must not
-        // become `rm -rf` of that directory. A build dir carries a .verified marker once complete; a
-        // half-finished download has the build-tag name but no marker yet.
-        let bytes = 0;
-        const removed = [];
-        for (const name of readdirSync(root)) {
-            const dir = join(root, name);
-            let isDir = false;
-            try {
-                isDir = statSync(dir).isDirectory();
+        else {
+            // Only build directories: a CLEARCOTE_CACHE pointing at $HOME or a shared directory must not
+            // become `rm -rf` of that directory. A build dir carries a .verified marker once complete; a
+            // half-finished download has the build-tag name but no marker yet.
+            let bytes = 0;
+            const removed = [];
+            for (const name of readdirSync(root)) {
+                const dir = join(root, name);
+                let isDir = false;
+                try {
+                    isDir = statSync(dir).isDirectory();
+                }
+                catch { /* vanished */ }
+                if (!isDir)
+                    continue;
+                if (!existsSync(join(dir, ".verified")) && !/^(pro-\d|v\d)/.test(name))
+                    continue;
+                bytes += dirSize(dir);
+                rmSync(dir, { recursive: true, force: true });
+                removed.push(name);
             }
-            catch { /* vanished */ }
-            if (!isDir)
-                continue;
-            if (!existsSync(join(dir, ".verified")) && !/^(pro-\d|v\d)/.test(name))
-                continue;
-            bytes += dirSize(dir);
-            rmSync(dir, { recursive: true, force: true });
-            removed.push(name);
+            out(removed.length
+                ? `removed ${removed.length} cached build${removed.length === 1 ? "" : "s"} from ${root} (${(bytes / 1e6).toFixed(0)} MB)`
+                : `no cached builds in ${root}`);
+        }
+        // Windows: the copies launches fall back to when a cached build cannot start in place.
+        const rec = clearRecovered();
+        if (rec.removed) {
+            out(`removed ${rec.removed} recovered build cop${rec.removed === 1 ? "y" : "ies"} from ${recoverRoot()} (${(rec.bytes / 1e6).toFixed(0)} MB)`);
+        }
+        if (rec.inUse) {
+            out(`kept ${rec.inUse} recovered build cop${rec.inUse === 1 ? "y" : "ies"} a running browser is using (in ${recoverRoot()})`);
         }
-        out(removed.length
-            ? `removed ${removed.length} cached build${removed.length === 1 ? "" : "s"} from ${root} (${(bytes / 1e6).toFixed(0)} MB)`
-            : `no cached builds in ${root}`);
         return;
     }
     if (cmd === "login") {
+        if (rest.includes("--device")) {
+            if (rest.some((a) => a !== "--device"))
+                fail("pass a key or --device, not both", 2);
+            await deviceLogin();
+            return;
+        }
         const key = rest[0] ?? (await promptKey());
         if (!key)
             fail("empty key");
@@ -298,6 +556,7 @@ export async function main(argv = process.argv.slice(2)) {
         if (seats.state === "invalid")
             fail(`the licence server rejected this key (${seats.reason}). Nothing was saved.`);
         const where = saveLicenseKey(key);
+        removeLicenseMeta(key.trim()); // a device login's record of another key no longer applies
         out(`saved to ${where}`);
         if (seats.state === "ok")
             out(`valid: ${seats.used} of ${seats.limit ?? "unlimited"} seats in use${seats.plan ? `, plan ${seats.plan}` : ""}`);