@showly/mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -6,37 +6,72 @@ you can preview and deploy a site directly from your terminal AI.
 ## Quickstart
 
 ```sh
-npx @showly/mcp-server install --to claude-code   # or --to codex
+npx @showly/mcp-server install --to codex --with-skill
+# or: npx @showly/mcp-server install --to claude-code --with-skill
 ```
 
 The installer writes the Showly MCP server block to `~/.claude.json`
-(or `~/.codex/config.toml`). No token to paste: the next time you call a Showly
+(or `~/.codex/config.toml`) and installs the reusable `showly-publish` skill.
+The skill activates when you ask to share, preview, deploy, host, or publish a
+web project; merely asking to build or edit a page does not deploy it.
+
+No token to paste: the next time you call a Showly
 tool, your agent discovers Showly's OAuth authorization server from the
 endpoint and opens a browser tab for you to sign in and approve the scopes
 (standard MCP authorization).
 
 ## What you get
 
+`manifest.json` in this package is the authoritative list — the server
+derives `INVOKABLE_TOOLS` and `MCP_BLOCKED_TOOLS` from it, so read it
+rather than trusting a hand-kept summary. It currently ships 33 tools,
+grouped below by its own `kind` field.
+
 Read-only tools available to any token:
 
 - `list_projects`, `list_sites`, `get_site_context`, `list_templates`
 - `get_preview_status`, `get_deployment_logs`, `diagnose_deployment`
+- `list_deployments`, `list_site_versions`, `diff_site_versions`, `get_site_files`
+- `list_site_domains`, `request_download_url`
 
 Write tools that stage and materialise previews:
 
 - `create_change_plan` — turn a natural-language request into a plan
 - `apply_site_patch` — stage one or more file edits as a _changeset_
 - `create_preview` — build the changeset and return a real preview URL
+- `create_github_preview` — build a private preview from the latest commit on a connected GitHub branch (static targets; dynamic container builds fail before enqueue)
 - `retry_deployment` — re-run a failed preview build
 - `run_checks` — read the lint / typecheck / build status of a preview
 - `create_site_from_template` — bootstrap a new site from a template
+- `create_site_from_html` — create a site from inline HTML
+- `request_upload_url` — signed URL for a file too large to pass inline
+- `set_preview_access` — change who can open a preview URL
 - `request_publish` — open a publish approval (completed in the web UI)
 
-Production paths (`publish_site`, `rollback_deployment`) are deliberately
-not exposed via MCP at all — they don't appear in `tools/list`. The agent's
-path to production is `request_publish`, whose success response includes a
-`webApprovalUrl` deep link; the user opens that link to complete approval
-and step-up MFA in the Showly web UI.
+Write tools for custom domains (ADR-0015):
+
+- `add_custom_domain`, `verify_custom_domain`
+
+Write tools for version history and deletion:
+
+- `rollback_to_version` — restore a previous site version
+- `delete_preview`, `delete_site`
+
+Write tools for the guest trial flow:
+
+- `create_trial_site`, `claim_trial_site`
+
+`publish_site` is exposed through a narrower `publish:confirm` scope and never
+publishes on its first call: it returns a short-lived, deployment-bound token
+that the agent may echo only after the user confirms. Team and Enterprise
+workspaces use `request_publish` and its `webApprovalUrl` for second-person
+approval. Ordinary Live publishing does not require OTP/MFA. The legacy
+`rollback_deployment` path remains Web-only.
+
+Both publish paths require the human user bound to the MCP token to have a
+verified Showly account email. An `email_verification_required` result includes
+`webVerificationUrl`; the agent must direct the user there and must not report
+the site as live until verification succeeds and publishing is retried.
 
 ## Environment
 

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-type Target = "claude-code" | "codex" | "stdout";
+export type Target = "claude-code" | "codex" | "stdout";
 export declare function buildClaudeCodeSnippet(opts: {
     url: string;
     apiUrl?: string;
@@ -18,8 +18,237 @@ export type InstallResult = {
     snippet: string;
     wrote: boolean;
     alreadyConfigured: boolean;
+    skill: SkillInstallResult | null;
 };
-export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv): InstallResult;
+export type SkillInstallResult = {
+    path: string;
+    wrote: boolean;
+    alreadyConfigured: boolean;
+};
+export type InstallOptions = {
+    withSkill?: boolean;
+};
+export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv, options?: InstallOptions): InstallResult;
+export declare function performSkillInstall(target: Exclude<Target, "stdout">, env?: NodeJS.ProcessEnv): SkillInstallResult;
+/**
+ * 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 declare const LOGIN_CLIENT_ID = "showly-mcp-cli";
+/** The env var name emitted into config snippets that must not hold a secret. */
+export declare const TOKEN_ENV_VAR = "SHOWLY_TOKEN";
+export type DeviceStart = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+};
+export type DeviceToken = {
+    access_token: string;
+    scope: string;
+    expires_in?: number;
+};
+/**
+ * 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 declare function buildLoginPrompt(input: {
+    verificationUri: string;
+    verificationUriComplete: string;
+    userCode: string;
+    expiresAt: Date;
+}): string;
+/** Claude Code reads a `headers` map on an http MCP server entry. */
+export declare function buildClaudeCodeAuthSnippet(opts: {
+    url: string;
+    token: string;
+}): Record<string, unknown>;
+export declare function buildCodexAuthSnippet(opts: {
+    url: string;
+    tokenEnvVar?: string;
+}): string;
+export type LoginDeps = {
+    fetchImpl?: typeof fetch;
+    /**
+     * Injectable wait. Takes the cancellation signal too, so the real one can
+     * return the instant Ctrl+C arrives instead of finishing a five-second nap
+     * first — a cancel the user has to wait out does not read as a cancel.
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Injectable clock (ms). Lets the poll deadline be tested without waiting. */
+    now?: () => number;
+    /** stderr sink. Keeps stdout clean for --print-token. */
+    log?: (line: string) => void;
+    /**
+     * Cancellation from outside — Ctrl+C, in production (see createCancelScope).
+     *
+     * Without it there was no way out of this command but killing the process,
+     * which is a poor deal for the human who is already stuck: `login` blocks for
+     * a quarter of an hour by design, and the whole reason a reader reaches it is
+     * that something else (their editor's browser window) failed to appear.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-request deadline override, in ms. Production uses the constants below;
+     * the tests use a tiny value so a hung server can be exercised in
+     * milliseconds rather than in the fifteen seconds a real one gets.
+     */
+    requestTimeoutMs?: number;
+};
+/**
+ * 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 declare const START_REQUEST_TIMEOUT_MS = 15000;
+export declare const POLL_REQUEST_TIMEOUT_MS = 30000;
+/** Thrown when the human cancels; the CLI exits 130 rather than 1 on it. */
+export declare class LoginCancelledError extends Error {
+    constructor();
+}
+/**
+ * Wire Ctrl+C (and SIGTERM) to an AbortSignal the login flow watches.
+ *
+ * Registering a SIGINT listener also SUPPRESSES Node's default "die now", which
+ * is the point: the flow gets to unwind, say what happened, and exit with the
+ * conventional 130 instead of leaving the reader guessing whether anything was
+ * half-written. Exported so the wiring itself is testable — `main` is not.
+ */
+export type SignalTarget = {
+    on(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+};
+export declare function createCancelScope(target?: SignalTarget): {
+    signal: AbortSignal;
+    release: () => void;
+};
+/**
+ * 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 declare const SERVER_EXTENSION_ALLOWANCE_MS: number;
+export declare function startDeviceFlow(apiUrl: string, deps?: LoginDeps): Promise<DeviceStart>;
+/**
+ * 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 declare function pollForDeviceToken(input: {
+    apiUrl: string;
+    deviceCode: string;
+    intervalSec: number;
+    expiresAt: Date;
+}, deps?: LoginDeps): Promise<DeviceToken>;
+export type LoginResult = {
+    target: Target;
+    token: string;
+    scope: string;
+    expiresAt: Date | null;
+    path: string | null;
+    wrote: boolean;
+    snippet: string;
+};
+/**
+ * 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 declare function performLogin(opts: {
+    target: Target;
+    env?: NodeJS.ProcessEnv;
+}, deps?: LoginDeps): Promise<LoginResult>;
+/**
+ * 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 declare function envVarsReferencedBy(configText: string): string[];
+export type LoginOutputLine = {
+    stream: "out" | "err";
+    line: string;
+};
+/**
+ * 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 declare function buildLoginOutput(result: LoginResult, opts?: {
+    printToken?: boolean;
+}): LoginOutputLine[];
 /**
  * True when this module is the program entrypoint.
  *
@@ -35,4 +264,3 @@ export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv):
  * exercised from an in-process test runner otherwise).
  */
 export declare function isMainModule(argv1: string | undefined, metaUrl: string): boolean;
-export {};

package/dist/cli.js

@@ -4,29 +4,51 @@
 // 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-publish
 //   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
 //
-// The CLI only writes the MCP server config block — it doesn't touch network.
+// `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).
+//
+// `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, 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_PUBLISH_SKILL_MARKDOWN, SHOWLY_PUBLISH_SKILL_NAME, } from "./showly-publish-skill.js";
 function usage() {
     return [
         "Showly MCP server installer",
         "",
         "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",
         "",
+        "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-publish skill for Claude Code or Codex.",
     ].join("\n");
 }
 // The MCP server config is intentionally MINIMAL: just the transport + URL.
@@ -36,8 +58,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 +93,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 +106,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 +138,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 +163,7 @@ export function performInstall(target, env = process.env) {
             snippet,
             wrote: false,
             alreadyConfigured: true,
+            skill: installSkill(),
         };
     }
     mkdirSync(dirname(path), { recursive: true });
@@ -149,8 +176,23 @@ 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 path = join(hostDirectory, "skills", SHOWLY_PUBLISH_SKILL_NAME, "SKILL.md");
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+    if (existing === SHOWLY_PUBLISH_SKILL_MARKDOWN) {
+        return { path, wrote: false, alreadyConfigured: true };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, SHOWLY_PUBLISH_SKILL_MARKDOWN, "utf8");
+    return { path, wrote: true, alreadyConfigured: false };
+}
 function safeReadJson(path) {
     try {
         return JSON.parse(readFileSync(path, "utf8"));
@@ -159,7 +201,596 @@ 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;
+}
+function parseTarget(rest, fallback) {
+    const toIdx = rest.indexOf("--to");
+    if (toIdx === -1)
+        return fallback;
+    const value = rest[toIdx + 1];
+    if (!value || !["claude-code", "codex", "stdout"].includes(value))
+        return null;
+    return value;
+}
+async function main(argv) {
     const [cmd, ...rest] = argv.slice(2);
     if (!cmd || cmd === "--help" || cmd === "-h") {
         console.log(usage());
@@ -169,6 +800,42 @@ function main(argv) {
         console.log(JSON.stringify(loadManifest(), null, 2));
         return;
     }
+    if (cmd === "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(rest, "stdout");
+        if (!target) {
+            console.error("login: --to must be claude-code, codex or stdout");
+            process.exitCode = 2;
+            return;
+        }
+        const printToken = rest.includes("--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 }, { signal: cancel.signal });
+            for (const { stream, line } of buildLoginOutput(result, { printToken })) {
+                if (stream === "out")
+                    console.log(line);
+                else
+                    console.error(line);
+            }
+        }
+        catch (error) {
+            console.error(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.
+            process.exitCode = error instanceof LoginCancelledError ? 130 : 1;
+        }
+        finally {
+            cancel.release();
+        }
+        return;
+    }
     if (cmd === "install") {
         const toIdx = rest.indexOf("--to");
         if (toIdx === -1 || !rest[toIdx + 1]) {
@@ -183,17 +850,29 @@ function main(argv) {
             process.exitCode = 2;
             return;
         }
-        const result = performInstall(target);
+        const withSkill = rest.includes("--with-skill");
+        if (withSkill && target === "stdout") {
+            console.error("install: --with-skill requires --to claude-code or --to codex");
+            process.exitCode = 2;
+            return;
+        }
+        const result = performInstall(target, process.env, { withSkill });
         if (target === "stdout") {
             console.log(result.snippet);
         }
-        else if (result.alreadyConfigured) {
-            console.log(`Already configured at ${result.path}`);
-        }
         else {
-            console.log(`Wrote ${result.path}`);
+            console.log(result.alreadyConfigured
+                ? `Already configured at ${result.path}`
+                : `Wrote ${result.path}`);
+            if (result.skill) {
+                console.log(result.skill.alreadyConfigured
+                    ? `Skill already installed at ${result.skill.path}`
+                    : `Installed reusable skill at ${result.skill.path}`);
+            }
             console.log("");
-            console.log("Next: open Claude Code / Codex and run any read tool (e.g. list_sites).");
+            console.log(withSkill
+                ? "Next: open your agent and ask “publish this site as a private preview”."
+                : "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.");
         }
         return;
@@ -227,5 +906,5 @@ export function isMainModule(argv1, metaUrl) {
     }
 }
 if (isMainModule(process.argv[1], import.meta.url)) {
-    main(process.argv);
+    void main(process.argv);
 }

package/dist/showly-publish-skill.d.ts

@@ -0,0 +1,2 @@
+export declare const SHOWLY_PUBLISH_SKILL_NAME = "showly-publish";
+export declare const SHOWLY_PUBLISH_SKILL_MARKDOWN: string;

package/dist/showly-publish-skill.js

@@ -0,0 +1,3 @@
+import { readFileSync } from "node:fs";
+export const SHOWLY_PUBLISH_SKILL_NAME = "showly-publish";
+export const SHOWLY_PUBLISH_SKILL_MARKDOWN = readFileSync(new URL("../skills/showly-publish/SKILL.md", import.meta.url), "utf8");

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://showly.ai/schemas/skill-manifest-v1.json",
   "name": "showly",
   "displayName": "Showly",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deploy and manage Showly sites from inside Claude Code / Codex.",
   "homepage": "https://showly.ai/docs/skills",
   "publisher": "Showly",
@@ -18,6 +18,7 @@
         "preview:create",
         "checks:run",
         "publish:request",
+        "publish:confirm",
         "logs:read",
         "template:read",
         "template:create"
@@ -48,6 +49,38 @@
     { "name": "create_change_plan", "kind": "write", "scopes": ["site:read"] },
     { "name": "apply_site_patch", "kind": "write", "scopes": ["site:write"] },
     { "name": "create_preview", "kind": "write", "scopes": ["preview:create"] },
+    {
+      "name": "create_github_preview",
+      "kind": "write",
+      "scopes": ["preview:create"]
+    },
+    {
+      "name": "set_preview_access",
+      "kind": "write",
+      "scopes": ["preview:create"]
+    },
+    { "name": "delete_preview", "kind": "write", "scopes": ["preview:create"] },
+    { "name": "delete_site", "kind": "write", "scopes": ["site:delete"] },
+    { "name": "list_site_domains", "kind": "read", "scopes": ["site:read"] },
+    {
+      "name": "add_custom_domain",
+      "kind": "write",
+      "scopes": ["site:write"]
+    },
+    {
+      "name": "verify_custom_domain",
+      "kind": "write",
+      "scopes": ["site:write"]
+    },
+    { "name": "list_site_versions", "kind": "read", "scopes": ["site:read"] },
+    { "name": "list_deployments", "kind": "read", "scopes": ["site:read"] },
+    { "name": "get_site_files", "kind": "read", "scopes": ["site:read"] },
+    { "name": "diff_site_versions", "kind": "read", "scopes": ["site:read"] },
+    {
+      "name": "rollback_to_version",
+      "kind": "write",
+      "scopes": ["rollback:confirm"]
+    },
     {
       "name": "retry_deployment",
       "kind": "write",
@@ -64,12 +97,37 @@
       "kind": "write",
       "scopes": ["template:create", "site:write"]
     },
+    {
+      "name": "create_site_from_html",
+      "kind": "write",
+      "scopes": ["site:write", "preview:create"]
+    },
+    {
+      "name": "request_upload_url",
+      "kind": "write",
+      "scopes": ["site:write", "preview:create"]
+    },
+    {
+      "name": "request_download_url",
+      "kind": "read",
+      "scopes": ["site:read"]
+    },
+    {
+      "name": "create_trial_site",
+      "kind": "write",
+      "scopes": ["site:write", "preview:create"]
+    },
+    {
+      "name": "claim_trial_site",
+      "kind": "write",
+      "scopes": ["site:write"]
+    },
     {
       "name": "publish_site",
-      "kind": "production",
-      "scopes": ["production:deploy"],
-      "mcp_origin_blocked": true,
-      "note": "Production-side deploy. MCP-origin calls are rejected; trigger from the web UI with step-up MFA + approval."
+      "kind": "confirm-publish",
+      "scopes": ["publish:confirm"],
+      "mcp_origin_blocked": false,
+      "note": "Two-step direct production publish: step 1 returns a summary + short-lived confirmation token; after the user confirms in the conversation, step 2 publishes. The MCP-bound user must have a verified email; email_verification_required returns webVerificationUrl. Solo/non-approval plans; Team/Enterprise use request_publish."
     },
     {
       "name": "rollback_deployment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showly/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Connect Claude Code / Codex to the Showly MCP server — preview and deploy sites from your agent.",
   "license": "UNLICENSED",
   "type": "module",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "manifest.json",
     "README.md"
   ],
@@ -51,7 +52,7 @@
   },
   "claude-code-skill": {
     "name": "showly",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Deploy and manage Showly sites from inside Claude Code.",
     "mcp-server": {
       "url-env": "SHOWLY_MCP_URL",
@@ -64,15 +65,15 @@
   },
   "codex-plugin": {
     "name": "showly",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "type": "mcp-server",
     "manifest": "manifest.json"
   },
   "devDependencies": {
     "@showly/eslint-config": "workspace:^",
-    "@types/node": "^25.9.1",
-    "eslint": "^9.18.0",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "tsx": "^4.23.10",
+    "typescript": "^7.0.2"
   }
 }

package/skills/showly-publish/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: showly-publish
+description: Publish, deploy, host, share, or put a website online with Showly, and create private preview links for web projects. Use when the user asks for a shareable URL, a private preview, hosting, deployment, or publishing. Do not trigger when the user only asks to build or edit a page without asking to share or put it online.
+---
+
+# Publish web projects with Showly
+
+Use Showly when the user wants a web project deployed, hosted, shared, put online, or turned into a preview URL.
+
+## Default behavior
+
+- Treat “preview”, “share”, “deploy”, “host”, and “put it online” as a request for a **private Preview**, not a public production release.
+- Build or validate the project before deploying it. Preserve the user's existing framework and files.
+- If Showly asks for authorization, tell the user to complete the browser sign-in, then retry the interrupted tool call.
+- Return the Preview URL and password together. Also report whether the Preview expires or is permanent.
+- Never claim a site is online until the Showly tool reports a successful deployment.
+
+## New sites
+
+For a simple new static site, call `create_site_from_html` with the completed HTML, CSS, and JavaScript. For larger projects, use the upload or repository workflow exposed by the available Showly tools.
+
+Do not call `create_trial_site` here. It builds a throwaway site owned by the shared guest organization, not by the connected account, and it refuses a connected caller with `authenticated_account_present`. Reaching Showly's tools at all means an account is connected, so `create_site_from_html` is the create path even when the user says "just a trial" — a private Preview is already reversible and costs nothing.
+
+## Existing Showly sites
+
+1. Call `list_sites` and identify the intended site. Ask only if more than one site is a plausible match.
+2. Use `create_change_plan` when the change is substantial or ambiguous.
+3. Stage edits with `apply_site_patch`.
+4. Call `create_preview` and return the private Preview URL and password.
+
+## Public production publishing
+
+A private Preview is reversible; a public production publish is not the default.
+
+- Publish publicly only when the user explicitly asks for a public or production release.
+- Use `publish_site` for solo publishing. Its first call only returns a summary and confirmation token. Show that summary to the user and call it a second time only after the user explicitly confirms.
+- If the workspace requires approval, use `request_publish` and return its approval URL.
+- If email verification is required, return the verification URL and do not say the site is live until verification and publishing succeed.

package/skills/showly-publish/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Showly Publish"
+  short_description: "Publish web projects as private Showly previews"
+  default_prompt: "Publish this web project as a private Showly preview and return the URL and password."