@showly/mcp-server 0.1.0 → 0.3.0

package/dist/cli.js

@@ -4,29 +4,85 @@
 // Usage:
 //   showly-mcp install --to claude-code     # writes ~/.claude.json
 //   showly-mcp install --to codex           # writes ~/.codex/config.toml
+//   showly-mcp install --to codex --with-skill # also installs showly-hosting
 //   showly-mcp install --to stdout          # prints the snippet for manual paste
+//   showly-mcp login --to claude-code       # RFC 8628 device flow, no browser here
 //   showly-mcp manifest                     # prints manifest.json
-//   showly-mcp --help
+//   showly-mcp --help / --version
+//   showly-mcp <command> --help             # exits 0 iff this copy has <command>
 //
-// The CLI only writes the MCP server config block — it doesn't touch network.
+// Every help screen and every error names the version of THIS copy, and every
+// unrecognized command or flag exits non-zero. Both are here because the
+// opposite shipped: a 0.1.0 copy handed `--with-skill` ignored it, printed
+// "Wrote …" and exited 0, and its command list gave an agent no reason to
+// suspect a newer release existed.
+//
+// `install` only writes the MCP server config block — it doesn't touch network.
 // The agent discovers OAuth from the server and runs the browser sign-in on
 // first use (standard MCP authorization).
-import { readFileSync, mkdirSync, writeFileSync, existsSync, realpathSync, } from "node:fs";
+//
+// `login` is the headless path, and it exists because nothing else could start
+// one. The API has implemented RFC 8628 the whole time, but no product surface
+// ever kicked it off: this CLI had `install` and `manifest` and no `login`, and
+// MCP clients will not drive it either — the MCP Authorization spec never
+// mentions RFC 8628, and Claude Code ignores `device_authorization_endpoint`
+// even when it is advertised. So a human whose agent runs on a box with no
+// browser, or who is holding a phone rather than sitting at the machine, had a
+// working server-side flow and no way to reach it.
+import { readFileSync, mkdirSync, rmSync, writeFileSync, existsSync, realpathSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
 import { loadManifest } from "./index.js";
+import { SHOWLY_HOSTING_SKILL_MARKDOWN, SHOWLY_HOSTING_SKILL_NAME, SHOWLY_LEGACY_SKILL_NAME, } from "./showly-hosting-skill.js";
+/**
+ * The version of THIS copy of the package, read from the manifest that ships
+ * beside it. `manifest.test.ts` pins manifest.json, package.json,
+ * claude-code-skill and codex-plugin to one string, so this cannot print a
+ * version the package does not actually have.
+ *
+ * It is printed on every help screen and on every unknown-command error, and
+ * that is the whole point. When an agent runs `showly-mcp` from a stale npx
+ * cache and sees a command list that is missing what the docs told it to run,
+ * the most natural inference is "the docs are wrong" or "I misremembered the
+ * name" — because nothing on screen suggests a newer copy exists. A version
+ * string plus the `@latest` hint is the one signal that redirects that guess
+ * from "the instructions are wrong" to "my copy is old".
+ */
+export const CLI_VERSION = loadManifest().version;
+/** The commands this copy dispatches. Anything else is an error, never a no-op. */
+export const KNOWN_COMMANDS = ["install", "login", "manifest"];
+/**
+ * The sentence that turns "this tool cannot do that" into "this COPY cannot do
+ * that". Printed on unknown commands and on unknown flags, because both are
+ * reached by the same route: documentation written against a newer release
+ * than the one npx resolved.
+ */
+export const UPGRADE_HINT = "If you expected this, your copy is out of date — re-run with `npx @showly/mcp-server@latest`.";
 function usage() {
     return [
-        "Showly MCP server installer",
+        `Showly MCP server installer (@showly/mcp-server ${CLI_VERSION})`,
         "",
         "Usage:",
-        "  showly-mcp install --to <claude-code|codex|stdout>",
+        "  showly-mcp install --to <claude-code|codex|stdout> [--with-skill]",
+        "  showly-mcp login   [--to <claude-code|codex|stdout>] [--print-token]",
         "  showly-mcp manifest",
+        "  showly-mcp --version",
+        "",
+        "login authorizes this machine without a browser on it: it prints a short",
+        "code, you approve it on any device, and the credential lands in your host",
+        "config. --to codex writes a config that reads the token from SHOWLY_TOKEN,",
+        "so login also prints the export line that sets it. --print-token writes",
+        "ONLY the token to stdout (everything else goes to stderr) so CI can",
+        "capture it without it touching a file.",
         "",
         "Environment overrides:",
         "  SHOWLY_MCP_URL    full URL to your MCP endpoint (default https://mcp.showly.ai)",
         "  SHOWLY_API_URL    full URL to your API (default https://api.showly.ai)",
+        "",
+        "--with-skill installs a reusable showly-hosting skill for Claude Code or Codex.",
+        "",
+        UPGRADE_HINT,
     ].join("\n");
 }
 // The MCP server config is intentionally MINIMAL: just the transport + URL.
@@ -36,8 +92,8 @@ function usage() {
 // authorization-server metadata, dynamically registers, and runs
 // authorization_code + PKCE in the browser. There is no client-readable
 // `oauth` field in the host config schema, so emitting one (as a prior version
-// did) was a no-op that misled rather than helped. `apiUrl` is retained in the
-// signature for the stdout help text + the device-flow fallback docs.
+// did) was a no-op that misled rather than helped. `apiUrl` is threaded through
+// for the stdout help text and for `login`, which POSTs the device flow there.
 export function buildClaudeCodeSnippet(opts) {
     return {
         mcpServers: {
@@ -71,7 +127,7 @@ export function resolveUrls(env = process.env) {
         apiUrl: env[manifest.mcp.endpoints.api_url_env] ?? "https://api.showly.ai",
     };
 }
-export function performInstall(target, env = process.env) {
+export function performInstall(target, env = process.env, options = {}) {
     const { url, apiUrl } = resolveUrls(env);
     if (target === "stdout") {
         const obj = buildClaudeCodeSnippet({ url, apiUrl });
@@ -84,8 +140,10 @@ export function performInstall(target, env = process.env) {
                 buildCodexSnippet({ url, apiUrl }),
             wrote: false,
             alreadyConfigured: false,
+            skill: null,
         };
     }
+    const installSkill = () => options.withSkill ? performSkillInstall(target, env) : null;
     if (target === "claude-code") {
         // User-scope MCP servers live in ~/.claude.json (top-level `mcpServers`),
         // NOT ~/.claude/settings.json — Claude Code never reads mcpServers from
@@ -114,16 +172,18 @@ export function performInstall(target, env = process.env) {
                 snippet: JSON.stringify(merged, null, 2),
                 wrote: false,
                 alreadyConfigured: true,
+                skill: installSkill(),
             };
         }
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        writeCredentialFile(path, JSON.stringify(merged, null, 2) + "\n");
         return {
             target,
             path,
             snippet: JSON.stringify(merged, null, 2),
             wrote: true,
             alreadyConfigured: false,
+            skill: installSkill(),
         };
     }
     // codex
@@ -137,6 +197,7 @@ export function performInstall(target, env = process.env) {
             snippet,
             wrote: false,
             alreadyConfigured: true,
+            skill: installSkill(),
         };
     }
     mkdirSync(dirname(path), { recursive: true });
@@ -149,8 +210,58 @@ export function performInstall(target, env = process.env) {
         snippet,
         wrote: true,
         alreadyConfigured: false,
+        skill: installSkill(),
     };
 }
+export function performSkillInstall(target, env = process.env) {
+    const codexHome = env.CODEX_HOME?.trim();
+    const hostDirectory = target === "codex"
+        ? codexHome || join(homedir(), ".codex")
+        : join(homedir(), ".claude");
+    const skillsRoot = join(hostDirectory, "skills");
+    const path = join(skillsRoot, SHOWLY_HOSTING_SKILL_NAME, "SKILL.md");
+    const removedLegacyPath = removeLegacySkill(skillsRoot);
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+    if (existing === SHOWLY_HOSTING_SKILL_MARKDOWN) {
+        return { path, wrote: false, alreadyConfigured: true, removedLegacyPath };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, SHOWLY_HOSTING_SKILL_MARKDOWN, "utf8");
+    return { path, wrote: true, alreadyConfigured: false, removedLegacyPath };
+}
+/**
+ * Delete the superseded showly-publish skill directory, if we wrote it.
+ *
+ * Leaving it behind is not neutral: hosts list every skill they find, so the
+ * old name and its publish-only description would keep competing with the new
+ * one at selection time — the exact failure this rename fixes. The guard is
+ * the front matter: we only remove a directory whose SKILL.md still declares
+ * `name: showly-publish`, so a user's own skill that happens to sit at that
+ * path is never touched.
+ */
+function removeLegacySkill(skillsRoot) {
+    const legacyDir = join(skillsRoot, SHOWLY_LEGACY_SKILL_NAME);
+    const legacyFile = join(legacyDir, "SKILL.md");
+    if (!existsSync(legacyFile))
+        return null;
+    let contents;
+    try {
+        contents = readFileSync(legacyFile, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (!new RegExp(`^name:\\s*${SHOWLY_LEGACY_SKILL_NAME}\\s*$`, "m").test(contents)) {
+        return null;
+    }
+    try {
+        rmSync(legacyDir, { recursive: true, force: true });
+    }
+    catch {
+        return null;
+    }
+    return legacyDir;
+}
 function safeReadJson(path) {
     try {
         return JSON.parse(readFileSync(path, "utf8"));
@@ -159,48 +270,797 @@ function safeReadJson(path) {
         return {};
     }
 }
-function main(argv) {
+/**
+ * Write a file that holds (or will hold) a credential, 0600 on creation.
+ *
+ * `login` puts a raw 90-day bearer into ~/.claude.json, and this command
+ * exists for exactly the hosts where "another local user" is not hypothetical:
+ * shared build boxes, container images, CI runners. writeFileSync's default is
+ * 0666 & ~umask — 0644 under the usual umask, i.e. world-readable.
+ *
+ * `mode` is consulted only when the file is CREATED (it goes to open(2) with
+ * O_CREAT), so an existing file keeps whatever mode its owner chose: this
+ * never widens a mode and never silently narrows one that was set on purpose.
+ * `install` writes through here too, so the common install-then-login sequence
+ * does not leave the file created loose before the token arrives.
+ */
+function writeCredentialFile(path, contents) {
+    writeFileSync(path, contents, { encoding: "utf8", mode: 0o600 });
+}
+// ───────────────────────────────────────────────────────────────────────────
+// login — RFC 8628 device authorization
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The client_id this CLI starts device flows under.
+ *
+ * Deliberately NOT a first-party id (the API rejects those on /oauth/device
+ * precisely so nobody can wear the product's identity on a consent screen),
+ * and deliberately not registered: a device client_id is free text, so the
+ * consent page treats whatever name it carries as self-declared and asks the
+ * human to check the code echo instead.
+ */
+export const LOGIN_CLIENT_ID = "showly-mcp-cli";
+/** The env var name emitted into config snippets that must not hold a secret. */
+export const TOKEN_ENV_VAR = "SHOWLY_TOKEN";
+/**
+ * The exact text `login` prints while it waits. Pure, and pinned by a test,
+ * because this block is the entire user interface of headless sign-in — the
+ * docs quote it verbatim so the page and the binary cannot drift.
+ *
+ * Reading order is not cosmetic:
+ *   • The bare URL plus the separately-printed code comes FIRST, because that
+ *     is the pair that works when the human is on a phone or another machine —
+ *     which is the entire reason this flow exists. The one-click deep link is
+ *     offered second, for the case where the browser is on this box.
+ *   • The code is repeated three times on purpose. RFC 8628 §3.3.1's code echo
+ *     is the ONLY anti-phishing signal that survives an attacker-controlled
+ *     client_name (Storm-2372 phished 340+ M365 tenants on exactly this flow),
+ *     so the human has to be told what they will see and what to do if it
+ *     differs.
+ *   • The expiry is a wall-clock time, not a duration. A human who wanders off
+ *     to create an account and verify an email cannot subtract "15 minutes"
+ *     from a moment they have forgotten.
+ */
+export function buildLoginPrompt(input) {
+    const clock = input.expiresAt.toLocaleTimeString(undefined, {
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false,
+    });
+    // Three things this wording deliberately does NOT do, each from a review of
+    // the first shipped draft:
+    //   • no "takes about a minute". The population this path exists for is the
+    //     cold-start user who must still sign up and verify an email — exactly the
+    //     people who used to run the clock out. A minute is a promise we break at
+    //     the worst possible moment; naming the signup sets the real expectation.
+    //   • no button label. The consent page is localized (拒绝 / 拒否 / 거부 /
+    //     Denegar / Refuser), so "press Deny" names a control five readers in six
+    //     never see — and this sentence is the ONE human check standing between
+    //     them and a device-code phish. It must not depend on an English label.
+    //   • no first person. An agent relays this block verbatim to a human who is
+    //     talking to that agent, so "I will continue" reads as the agent speaking.
+    //     Name the actor instead.
+    return [
+        "Showly needs one approval from you. If you do not have a Showly",
+        "account yet, you will be asked to create one first.",
+        "",
+        `  1. Open this page:   ${input.verificationUri}`,
+        `  2. Enter this code:  ${input.userCode}`,
+        "",
+        "Same machine as your browser? Use the direct link instead:",
+        `  ${input.verificationUriComplete}`,
+        "",
+        `The page will show the code ${input.userCode} before you approve.`,
+        "Approve ONLY if it matches the code above. If it shows a",
+        "different code, someone else is trying to get in - refuse it.",
+        "",
+        `Waiting for approval until ${clock} local. Once you approve, this`,
+        "command picks it up on its own - no need to come back and tell it.",
+        "",
+        // The last line of the block is the one thing it never said: how to stop.
+        // This command blocks for up to fifteen minutes, and the population it
+        // exists for arrived here because a sign-in window did not open — so the
+        // reader is already unsure whether anything is happening. Without an exit
+        // that is named, "wait" and "give up on the whole session" are the only two
+        // moves visible, and the second is the one the report describes people
+        // taking. Ctrl+C is safe to name because nothing is connected until the
+        // approval lands, and the CLI now handles the signal rather than dying on
+        // it mid-write.
+        "Changed your mind? Press Ctrl+C to stop waiting. Nothing is",
+        "connected until you approve, and the command can be run again.",
+    ].join("\n");
+}
+/** Claude Code reads a `headers` map on an http MCP server entry. */
+export function buildClaudeCodeAuthSnippet(opts) {
+    return {
+        mcpServers: {
+            showly: {
+                type: "http",
+                url: opts.url,
+                headers: { Authorization: `Bearer ${opts.token}` },
+            },
+        },
+    };
+}
+// Codex's streamable-HTTP MCP config takes `bearer_token_env_var` — the name
+// of an env var to read, never the token itself. Verified against the
+// installed binary rather than assumed: `codex mcp add --url` exposes
+// `--bearer-token-env-var`, the config struct carries
+// `bearer_token_env_var` / `http_headers` / `env_http_headers`, and the loader
+// rejects a literal `bearer_token` with "uses unsupported `bearer_token`; set
+// `bearer_token_env_var`". That check mattered — Codex's TOML deserialization
+// refuses unknown keys, so guessing at a `headers` table here would not just
+// fail to authorize, it would make the user's whole config.toml unloadable.
+//
+// The env indirection is also the right shape for CI: the credential lives in
+// the secret store, and the file we write is safe to commit.
+export function buildCodexAuthSnippet(opts) {
+    return [
+        "# Added by @showly/mcp-server login",
+        "",
+        "[mcp_servers.showly]",
+        `url = "${opts.url}"`,
+        `bearer_token_env_var = "${opts.tokenEnvVar ?? TOKEN_ENV_VAR}"`,
+        "",
+    ].join("\n");
+}
+/**
+ * How long ONE HTTP request may take before it is abandoned.
+ *
+ * Neither fetch had any bound at all, and both are inside the flow whose entire
+ * job is to unstick a human: a TCP connection that opens and then goes quiet
+ * (a captive portal, a proxy that swallows the response, a machine suspended
+ * mid-poll) leaves `login` hanging with no output and no deadline — the same
+ * silent wait, one layer down, that this command exists to replace.
+ *
+ * The start POST is short because nothing has been printed yet: until it
+ * returns there is no code, no URL, and nothing on screen, so the reader cannot
+ * tell a slow network from a dead one. A poll gets longer, because by then the
+ * prompt is on screen and the loop can absorb a slow answer without the reader
+ * seeing anything at all.
+ */
+export const START_REQUEST_TIMEOUT_MS = 15_000;
+export const POLL_REQUEST_TIMEOUT_MS = 30_000;
+/** Thrown when the human cancels; the CLI exits 130 rather than 1 on it. */
+export class LoginCancelledError extends Error {
+    constructor() {
+        super("Cancelled. Nothing was connected — run `npx @showly/mcp-server login` again when you are ready.");
+        this.name = "LoginCancelled";
+    }
+}
+/**
+ * A wait that also ends on cancellation.
+ *
+ * Resolves rather than rejects on abort: the caller re-checks the signal
+ * immediately after, so there is exactly one place that decides what a cancel
+ * means and one error to throw for it.
+ */
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const finish = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", finish);
+        resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+});
+/**
+ * One signal per HTTP request: the request deadline OR the human's Ctrl+C,
+ * whichever lands first, plus the cleanup that keeps neither leaking.
+ *
+ * Hand-rolled instead of `AbortSignal.any()` because this package publishes
+ * `engines.node: ">=18"` and `any()` only exists from 20.3 — a published CLI
+ * that throws TypeError on a supported runtime would replace the hang with a
+ * crash rather than a fix.
+ */
+function requestSignal(timeoutMs, external) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException("timeout", "TimeoutError")), timeoutMs);
+    const onAbort = () => controller.abort(external?.reason);
+    if (external?.aborted)
+        onAbort();
+    else
+        external?.addEventListener("abort", onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        release: () => {
+            clearTimeout(timer);
+            external?.removeEventListener("abort", onAbort);
+        },
+    };
+}
+export function createCancelScope(target = process) {
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    target.on("SIGINT", onSignal);
+    target.on("SIGTERM", onSignal);
+    return {
+        signal: controller.signal,
+        release: () => {
+            target.off("SIGINT", onSignal);
+            target.off("SIGTERM", onSignal);
+        },
+    };
+}
+/**
+ * How far PAST the expiry we were handed at start the poll keeps going.
+ *
+ * `expires_in` from POST /oauth/device is a floor, not a deadline: when a
+ * signed-in human lands on the consent page the server pushes expires_at out
+ * (see DEVICE_LOOKUP_EXTENSION_MS), so a client that stopped at the advertised
+ * expiry would hang up on the human mid-approval. It is still bounded — the
+ * server caps a device flow at 30 minutes from creation whatever happens — so
+ * one absolute cap past the advertised expiry is comfortably beyond any answer
+ * that could still become a token, and stopping there is what keeps a deploy
+ * that stops resolving dead rows from turning this loop into a permanent 300
+ * requests/min against the token endpoint.
+ */
+export const SERVER_EXTENSION_ALLOWANCE_MS = 30 * 60 * 1000;
+/**
+ * Did this request die on its own deadline?
+ *
+ * undici reports an aborted fetch as a DOMException on `cause`, not as the
+ * thrown error itself, so the name has to be read through both.
+ */
+function isTimeoutError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const named = error;
+    return named.name === "TimeoutError" || named.cause?.name === "TimeoutError";
+}
+/** One short clause naming why a request failed, for the deadline message. */
+function errorSummary(error, timeoutMs) {
+    if (isTimeoutError(error))
+        return `no answer within ${timeoutMs}ms`;
+    return error instanceof Error ? error.message : String(error);
+}
+/** Said on both routes to a dead code: the server's answer, and our deadline. */
+const EXPIRED_MESSAGE = "The code expired before it was approved. Run this command again for a fresh one.";
+export async function startDeviceFlow(apiUrl, deps = {}) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    // `scope` is optional on /oauth/device, and this used to send none at all.
+    // The consent screen then listed no permissions, the human approved that,
+    // and the token that came back could invoke none of the tools this package
+    // exists to reach — while `showly-mcp login` printed "Connected" and the
+    // connect screen agreed, because a call denied for insufficient_scope still
+    // stamps last_used_at. The API now applies its own default to clients that
+    // omit `scope`, but a client that knows what it needs should say so. The
+    // manifest is the one place this list is written down and is the same list
+    // the API falls back to; asking through it is what keeps the request, the
+    // package's own advertised scopes, and the server default from drifting.
+    const manifest = loadManifest();
+    const timeoutMs = deps.requestTimeoutMs ?? START_REQUEST_TIMEOUT_MS;
+    const { signal, release } = requestSignal(timeoutMs, deps.signal);
+    let res;
+    try {
+        res = await doFetch(`${apiUrl}/oauth/device`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                client_id: LOGIN_CLIENT_ID,
+                scope: manifest.mcp.auth.default_scopes.join(" "),
+            }),
+            signal,
+        });
+    }
+    catch (error) {
+        // Nothing is on screen yet at this point, so an unexplained hang here is
+        // indistinguishable from a broken install. Name which of the two ended it.
+        if (deps.signal?.aborted)
+            throw new LoginCancelledError();
+        if (isTimeoutError(error)) {
+            throw new Error(`Showly did not answer within ${Math.round(timeoutMs / 1000)}s (${apiUrl}/oauth/device). Check SHOWLY_API_URL and your network, then run the command again.`);
+        }
+        throw error;
+    }
+    finally {
+        release();
+    }
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || !body?.data) {
+        throw new Error(`Could not start Showly sign-in (${res.status}). ${body?.error_description ?? "Check SHOWLY_API_URL and your network."}`);
+    }
+    return body.data;
+}
+/**
+ * Poll /oauth/token until the human decides, per RFC 8628 §3.4-3.5.
+ *
+ * Every terminal answer is turned into a sentence a human can act on. The
+ * server sends `error_description` for exactly this reason, so we prefer it
+ * over anything we could invent, and fall back only when an older deploy
+ * sends the bare code.
+ *
+ * `expiresAt` is the client-side backstop, not the contract: the server's own
+ * `expired_token` / `invalid_grant` is what normally ends the loop, and this
+ * only fires when no answer ever arrives at all. It sits a full
+ * SERVER_EXTENSION_ALLOWANCE_MS past the advertised expiry so an arrival
+ * extension is never cut short.
+ */
+export async function pollForDeviceToken(input, deps = {}) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? (() => Date.now());
+    const cancel = deps.signal;
+    const timeoutMs = deps.requestTimeoutMs ?? POLL_REQUEST_TIMEOUT_MS;
+    let intervalMs = Math.max(1, input.intervalSec) * 1000;
+    const stopAt = input.expiresAt.getTime() + SERVER_EXTENSION_ALLOWANCE_MS;
+    // Kept for the deadline message. A loop that quietly swallowed every network
+    // failure and then said only "the code expired" would send the human to look
+    // at their approval when the fault was never on their side.
+    let lastTransportError;
+    for (;;) {
+        if (cancel?.aborted)
+            throw new LoginCancelledError();
+        if (now() >= stopAt) {
+            throw new Error(lastTransportError
+                ? `${EXPIRED_MESSAGE} (the last attempt to reach Showly failed: ${lastTransportError})`
+                : EXPIRED_MESSAGE);
+        }
+        await sleep(intervalMs, cancel);
+        if (cancel?.aborted)
+            throw new LoginCancelledError();
+        const attempt = requestSignal(timeoutMs, cancel);
+        let res;
+        try {
+            res = await doFetch(`${input.apiUrl}/oauth/token`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: input.deviceCode,
+                    client_id: LOGIN_CLIENT_ID,
+                }),
+                signal: attempt.signal,
+            });
+        }
+        catch (error) {
+            if (cancel?.aborted)
+                throw new LoginCancelledError();
+            // A stalled or failed request is NOT a terminal answer. The human may
+            // already be approving on their phone, and their one approval is spent
+            // either way — throwing on a dropped packet would burn it and make them
+            // start over. Fall through to the next tick; `stopAt` still bounds this.
+            lastTransportError = errorSummary(error, timeoutMs);
+            continue;
+        }
+        finally {
+            attempt.release();
+        }
+        lastTransportError = undefined;
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok && body.access_token) {
+            return {
+                access_token: body.access_token,
+                scope: body.scope ?? "",
+                expires_in: body.expires_in,
+            };
+        }
+        switch (body.error) {
+            case "authorization_pending":
+                continue;
+            // RFC 8628 §3.5: back off by 5 seconds and keep going. This is the one
+            // error that is not terminal and not a no-op.
+            case "slow_down":
+                intervalMs += 5_000;
+                continue;
+            case "access_denied":
+                throw new Error(body.error_description ??
+                    "Approval was denied. Nothing was connected.");
+            case "expired_token":
+                throw new Error(body.error_description ?? EXPIRED_MESSAGE);
+            default:
+                throw new Error(body.error_description ??
+                    `Sign-in failed (${body.error ?? res.status}).`);
+        }
+    }
+}
+/**
+ * Run the whole headless sign-in and put the credential where the host will
+ * find it.
+ *
+ * No secret is ever accepted on argv — there is no `--token` flag, and the
+ * only credential this command handles is the one it just fetched. Anything
+ * pasted from /app/admin/mcp-tokens goes in through the environment
+ * (SHOWLY_TOKEN) or the host config by hand, so it stays out of shell history
+ * and out of every `ps` listing on the machine.
+ */
+export async function performLogin(opts, deps = {}) {
+    const env = opts.env ?? process.env;
+    const { url, apiUrl } = resolveUrls(env);
+    const log = deps.log ?? ((line) => console.error(line));
+    const started = await startDeviceFlow(apiUrl, deps);
+    const expiresAt = new Date(Date.now() + started.expires_in * 1000);
+    log(buildLoginPrompt({
+        verificationUri: started.verification_uri,
+        verificationUriComplete: started.verification_uri_complete,
+        userCode: started.user_code,
+        expiresAt,
+    }));
+    const token = await pollForDeviceToken({
+        apiUrl,
+        deviceCode: started.device_code,
+        intervalSec: started.interval,
+        expiresAt,
+    }, deps);
+    // Showly issues no refresh token, so this date is the moment a working agent
+    // stops working and a human has to approve again. Say it out loud now, while
+    // there is context, instead of leaving a 401 to be diagnosed in 90 days.
+    const tokenExpiresAt = token.expires_in
+        ? new Date(Date.now() + token.expires_in * 1000)
+        : null;
+    if (opts.target === "claude-code") {
+        const path = join(homedir(), ".claude.json");
+        const existing = existsSync(path)
+            ? safeReadJson(path)
+            : { mcpServers: {} };
+        const snippet = buildClaudeCodeAuthSnippet({
+            url,
+            token: token.access_token,
+        });
+        const merged = {
+            ...existing,
+            mcpServers: {
+                ...(typeof existing.mcpServers === "object" && existing.mcpServers
+                    ? existing.mcpServers
+                    : {}),
+                showly: snippet.mcpServers.showly,
+            },
+        };
+        mkdirSync(dirname(path), { recursive: true });
+        writeCredentialFile(path, JSON.stringify(merged, null, 2) + "\n");
+        return {
+            target: opts.target,
+            token: token.access_token,
+            scope: token.scope,
+            expiresAt: tokenExpiresAt,
+            path,
+            wrote: true,
+            snippet: JSON.stringify(snippet, null, 2),
+        };
+    }
+    if (opts.target === "codex") {
+        // Append only when there is no [mcp_servers.showly] block yet. Rewriting
+        // an existing one would mean editing TOML in place, and a bad edit there
+        // takes down the user's entire config rather than just our entry — so
+        // when the block exists we print the single line to add and touch
+        // nothing.
+        const path = join(homedir(), ".codex", "config.toml");
+        const snippet = buildCodexAuthSnippet({ url });
+        const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+        if (existing.includes("[mcp_servers.showly]")) {
+            return {
+                target: opts.target,
+                token: token.access_token,
+                scope: token.scope,
+                expiresAt: tokenExpiresAt,
+                path,
+                wrote: false,
+                snippet: `bearer_token_env_var = "${TOKEN_ENV_VAR}"`,
+            };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, existing.length > 0 && !existing.endsWith("\n")
+            ? `${existing}\n${snippet}`
+            : `${existing}${snippet}`, "utf8");
+        return {
+            target: opts.target,
+            token: token.access_token,
+            scope: token.scope,
+            expiresAt: tokenExpiresAt,
+            path,
+            wrote: true,
+            snippet,
+        };
+    }
+    return {
+        target: opts.target,
+        token: token.access_token,
+        scope: token.scope,
+        expiresAt: tokenExpiresAt,
+        path: null,
+        wrote: false,
+        snippet: `# claude-code (~/.claude.json):\n` +
+            JSON.stringify(buildClaudeCodeAuthSnippet({
+                url,
+                token: `\${${TOKEN_ENV_VAR}}`,
+            }), null, 2) +
+            `\n\n# codex (~/.codex/config.toml):\n` +
+            buildCodexAuthSnippet({ url }),
+    };
+}
+/**
+ * The env var names a host config tells its client to read the credential
+ * from: Codex's `bearer_token_env_var = "NAME"`, and the `${NAME}` placeholder
+ * in the pasteable snippet.
+ *
+ * Deliberately derived FROM the config text rather than hardcoded, because the
+ * bug this closes was a config and an output that disagreed. Whatever a future
+ * host schema calls its indirection, the name it references is what the human
+ * has to be handed a value for.
+ */
+export function envVarsReferencedBy(configText) {
+    const names = new Set();
+    for (const m of configText.matchAll(/_env_var\s*=\s*"([A-Za-z_][A-Za-z0-9_]*)"/g)) {
+        names.add(m[1]);
+    }
+    for (const m of configText.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) {
+        names.add(m[1]);
+    }
+    return [...names];
+}
+/**
+ * Everything `login` says after the token lands. Pure, so the one property
+ * that matters can be tested: a human who ran this command ends up CONNECTED.
+ *
+ * `--to codex` used to break that. It writes `bearer_token_env_var =
+ * "SHOWLY_TOKEN"` — Codex reads the credential from the environment, never
+ * from the file — and then printed `Connected. Wrote <path>` and dropped the
+ * token on the floor. Nothing on the machine ever set SHOWLY_TOKEN, so every
+ * tool call went out with no Authorization header and 401'd, after the human
+ * had already spent their one approval; recovering meant a second device flow
+ * and a second approval, which is the dead end this whole command exists to
+ * remove. `--to stdout` had the same hole with a sentence over it ("re-run
+ * with --print-token"), which is also a second approval.
+ *
+ * So the value is supplied here, once, on stderr — the only place it can go
+ * without landing in a file. The config keeps the env indirection, which is
+ * what makes it safe to commit; stdout keeps carrying only the snippet (or,
+ * under --print-token, only the token) so both remain pipeable.
+ */
+export function buildLoginOutput(result, opts = {}) {
+    // stdout carries the token and NOTHING else, so
+    // `TOKEN=$(showly-mcp login --print-token)` is correct.
+    if (opts.printToken)
+        return [{ stream: "out", line: result.token }];
+    const lines = [];
+    if (result.wrote) {
+        lines.push({ stream: "err", line: `Connected. Wrote ${result.path}` });
+    }
+    else if (result.path) {
+        lines.push({
+            stream: "err",
+            line: `Connected. ${result.path} already has a [mcp_servers.showly] block — add this line to it:\n${result.snippet}`,
+        });
+    }
+    else {
+        lines.push({
+            stream: "err",
+            line: "Connected. Add this to your host config:",
+        });
+        lines.push({ stream: "out", line: result.snippet });
+    }
+    for (const name of envVarsReferencedBy(result.snippet)) {
+        lines.push({
+            stream: "err",
+            line: `That config reads the token from ${name}, and nothing sets it yet. Put this in the environment your agent starts in:`,
+        });
+        lines.push({ stream: "err", line: `  export ${name}=${result.token}` });
+        lines.push({
+            stream: "err",
+            line: "That line is the credential itself. It is printed here once, and kept out of the config file so the file stays safe to commit.",
+        });
+    }
+    if (result.expiresAt) {
+        lines.push({
+            stream: "err",
+            line: `This credential expires ${result.expiresAt.toISOString().slice(0, 10)}. Showly issues no refresh token, so run \`npx @showly/mcp-server login\` again before then — it needs a human approval each time.`,
+        });
+    }
+    return lines;
+}
+/**
+ * Which flags each command accepts, and whether the flag consumes the next
+ * argv token as its value.
+ *
+ * This table exists so an UNRECOGNIZED flag can be an error. It used to be
+ * impossible for one to be: the old parser only ever asked `rest.indexOf`
+ * / `rest.includes` about the flags it knew, so everything else fell through
+ * untouched and the command ran to completion, exit 0.
+ *
+ * That is the worst possible outcome and it shipped. `/drop` hands out
+ * `install --to claude-code --with-skill`; every copy older than 0.2.0 ignored
+ * `--with-skill`, wrote no skill file, printed "Wrote …" and exited 0. The
+ * human was told it worked, the agent had no reason to doubt it, and the
+ * feature was simply absent. A non-zero exit with the flag named is strictly
+ * better than a success that is not one — a broken command that says so can be
+ * retried, a broken command that stays quiet cannot.
+ */
+const COMMAND_FLAGS = {
+    install: { "--to": true, "--with-skill": false },
+    login: { "--to": true, "--print-token": false },
+    manifest: {},
+};
+/** Accepted after any command, and handled before the command runs. */
+const HELP_FLAGS = new Set(["--help", "-h"]);
+/**
+ * Strict argv parse for one command: every token must be a flag this command
+ * declares, a value for a flag that takes one, or `--help`.
+ *
+ * Bare positionals are rejected too, for the same reason flags are: `install
+ * claude-code` (no `--to`) is a plausible typo whose only old outcome was a
+ * usage error about the missing `--to`, and `manifest extra` simply printed the
+ * manifest as if the word were not there.
+ */
+export function parseCommandArgs(command, rest) {
+    const spec = COMMAND_FLAGS[command];
+    const flags = new Set();
+    const values = new Map();
+    let help = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const token = rest[i];
+        if (HELP_FLAGS.has(token)) {
+            help = true;
+            continue;
+        }
+        if (!token.startsWith("-")) {
+            return {
+                ok: false,
+                message: `${command}: unexpected argument "${token}". ${UPGRADE_HINT}`,
+            };
+        }
+        // `--to=codex` is a shape the old parser silently ignored (indexOf("--to")
+        // never matched), so accept it here rather than leave a second quiet
+        // no-op behind while closing the first.
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        if (!(name in spec)) {
+            return {
+                ok: false,
+                message: `${command}: unknown option "${name}". ${UPGRADE_HINT}`,
+            };
+        }
+        if (!spec[name]) {
+            if (eq !== -1) {
+                return {
+                    ok: false,
+                    message: `${command}: "${name}" takes no value.`,
+                };
+            }
+            flags.add(name);
+            continue;
+        }
+        const value = eq === -1 ? rest[++i] : token.slice(eq + 1);
+        if (value === undefined || value.length === 0) {
+            return { ok: false, message: `${command}: "${name}" needs a value.` };
+        }
+        values.set(name, value);
+    }
+    return { ok: true, help, flags, values };
+}
+function parseTarget(parsed, fallback) {
+    const value = parsed.values.get("--to");
+    if (value === undefined)
+        return fallback;
+    if (!["claude-code", "codex", "stdout"].includes(value))
+        return null;
+    return value;
+}
+const consoleIo = {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+};
+/**
+ * The whole command dispatcher, as a function that RETURNS its exit code.
+ *
+ * It used to be a `main` that assigned `process.exitCode` and was neither
+ * exported nor reachable from a test, which is why nothing noticed that the
+ * failure paths through it were not failures at all. The code is the contract
+ * here — the strings around it are not — so it is what a caller gets back.
+ */
+export async function runCli(argv, io = consoleIo, env = process.env) {
     const [cmd, ...rest] = argv.slice(2);
-    if (!cmd || cmd === "--help" || cmd === "-h") {
-        console.log(usage());
-        return;
+    if (!cmd || HELP_FLAGS.has(cmd)) {
+        io.out(usage());
+        return 0;
+    }
+    if (cmd === "--version" || cmd === "-v") {
+        io.out(CLI_VERSION);
+        return 0;
+    }
+    if (!KNOWN_COMMANDS.includes(cmd)) {
+        io.err(`unknown command: ${cmd}`);
+        // Said BEFORE the usage block, because the usage block is exactly what
+        // misleads here: a reader who is shown a short command list and no version
+        // concludes the tool never had the command, not that this copy is behind.
+        io.err(`If you expected this command, your copy is out of date — re-run with \`npx @showly/mcp-server@latest\`. This copy is @showly/mcp-server ${CLI_VERSION}.`);
+        io.err(usage());
+        return 2;
+    }
+    const command = cmd;
+    const parsed = parseCommandArgs(command, rest);
+    if (!parsed.ok) {
+        io.err(parsed.message);
+        io.err(`This copy is @showly/mcp-server ${CLI_VERSION}.`);
+        return 2;
+    }
+    // `<command> --help` exits 0 for every command this copy has. That is a
+    // probe a CI gate can run against the tarball npm currently serves as
+    // `latest`, so "main documents a subcommand the published package does not
+    // have" fails a build instead of failing a user.
+    if (parsed.help) {
+        io.out(usage());
+        return 0;
     }
-    if (cmd === "manifest") {
-        console.log(JSON.stringify(loadManifest(), null, 2));
-        return;
+    if (command === "manifest") {
+        io.out(JSON.stringify(loadManifest(), null, 2));
+        return 0;
     }
-    if (cmd === "install") {
-        const toIdx = rest.indexOf("--to");
-        if (toIdx === -1 || !rest[toIdx + 1]) {
-            console.error("install: --to <target> is required");
-            process.exitCode = 2;
-            console.error(usage());
-            return;
+    if (command === "login") {
+        // --to defaults to stdout: printing a snippet can never corrupt a config
+        // file the user did not ask us to touch.
+        const target = parseTarget(parsed, "stdout");
+        if (!target) {
+            io.err("login: --to must be claude-code, codex or stdout");
+            return 2;
         }
-        const target = rest[toIdx + 1];
-        if (!["claude-code", "codex", "stdout"].includes(target)) {
-            console.error(`install: unknown target "${target}"`);
-            process.exitCode = 2;
-            return;
+        const printToken = parsed.flags.has("--print-token");
+        // This command blocks for up to fifteen minutes waiting on a human, so
+        // Ctrl+C has to mean something here. Handling the signal (rather than
+        // letting Node's default kill the process) is what turns "the terminal went
+        // quiet and I don't know what happened" into one sentence and exit 130.
+        const cancel = createCancelScope();
+        try {
+            const result = await performLogin({ target, env }, { signal: cancel.signal });
+            for (const { stream, line } of buildLoginOutput(result, { printToken })) {
+                if (stream === "out")
+                    io.out(line);
+                else
+                    io.err(line);
+            }
+            return 0;
         }
-        const result = performInstall(target);
-        if (target === "stdout") {
-            console.log(result.snippet);
+        catch (error) {
+            io.err(error instanceof Error ? error.message : String(error));
+            // 130 is the shell's own "terminated by SIGINT". A cancel is not a
+            // failure of the command, and a script wrapping it should be able to
+            // tell the two apart.
+            return error instanceof LoginCancelledError ? 130 : 1;
         }
-        else if (result.alreadyConfigured) {
-            console.log(`Already configured at ${result.path}`);
+        finally {
+            cancel.release();
         }
-        else {
-            console.log(`Wrote ${result.path}`);
-            console.log("");
-            console.log("Next: open Claude Code / Codex and run any read tool (e.g. list_sites).");
-            console.log("The agent will pop a browser tab for you to authorize the connection.");
+    }
+    // install
+    const rawTarget = parsed.values.get("--to");
+    if (rawTarget === undefined) {
+        io.err("install: --to <target> is required");
+        io.err(usage());
+        return 2;
+    }
+    if (!["claude-code", "codex", "stdout"].includes(rawTarget)) {
+        io.err(`install: unknown target "${rawTarget}"`);
+        return 2;
+    }
+    const target = rawTarget;
+    const withSkill = parsed.flags.has("--with-skill");
+    if (withSkill && target === "stdout") {
+        io.err("install: --with-skill requires --to claude-code or --to codex");
+        return 2;
+    }
+    const result = performInstall(target, env, { withSkill });
+    if (target === "stdout") {
+        io.out(result.snippet);
+        return 0;
+    }
+    io.out(result.alreadyConfigured
+        ? `Already configured at ${result.path}`
+        : `Wrote ${result.path}`);
+    if (result.skill) {
+        io.out(result.skill.alreadyConfigured
+            ? `Skill already installed at ${result.skill.path}`
+            : `Installed reusable skill at ${result.skill.path}`);
+        if (result.skill.removedLegacyPath) {
+            io.out(`Removed the superseded showly-publish skill at ${result.skill.removedLegacyPath}`);
         }
-        return;
     }
-    console.error(`unknown command: ${cmd}`);
-    process.exitCode = 2;
-    console.error(usage());
+    io.out("");
+    io.out(withSkill
+        ? "Next: open your agent and ask “list my Showly sites”."
+        : "Next: open Claude Code / Codex and run any read tool (e.g. list_sites).");
+    io.out("The agent will pop a browser tab for you to authorize the connection.");
+    return 0;
 }
 /**
  * True when this module is the program entrypoint.
@@ -227,5 +1087,7 @@ export function isMainModule(argv1, metaUrl) {
     }
 }
 if (isMainModule(process.argv[1], import.meta.url)) {
-    main(process.argv);
+    void runCli(process.argv).then((code) => {
+        process.exitCode = code;
+    });
 }