@spacefast/common 0.0.5 → 0.0.6

package/dist/agents/connect-targets.d.ts

@@ -0,0 +1,133 @@
+export declare const LOCAL_MCP_PACKAGE = "spacefast";
+export declare const LOCAL_MCP_COMMAND = "npx";
+export declare const LOCAL_MCP_ARGS: readonly ["-y", "spacefast", "mcp"];
+/** The copy-paste one-liner form, e.g. `npx -y spacefast mcp`. */
+export declare const LOCAL_MCP_COMMAND_LINE: string;
+/**
+ * base64 of a UTF-8 string, without Buffer. Byte-identical to
+ * `Buffer.from(value, "utf8").toString("base64")`, so deeplinks stay stable
+ * whether they are built at the Astro build (Node) or in the dashboard (browser).
+ */
+export declare function base64Utf8(value: string): string;
+/** The on-device MCP server entry, byte-identical to the committed plugin `.mcp.json`. */
+export declare function localMcpServersJson(): {
+    mcpServers: {
+        spacefast: {
+            command: string;
+            args: ("mcp" | "spacefast" | "-y")[];
+            env: {};
+        };
+    };
+};
+/**
+ * VS Code's `.vscode/mcp.json` uses a top-level `servers` key (not the
+ * `mcpServers` key Cursor/Claude Code use), so it gets its own generator —
+ * single-sourced from the same command/args/package so it can never drift.
+ * See https://code.visualstudio.com/docs/agent-customization/mcp-servers.
+ */
+export declare function vscodeMcpServersJson(): {
+    servers: {
+        spacefast: {
+            type: string;
+            command: string;
+            args: ("mcp" | "spacefast" | "-y")[];
+        };
+    };
+};
+export declare function cursorHostedMcpDeeplink(mcpEndpoint: string): string;
+export declare function vscodeHostedMcpDeeplink(mcpEndpoint: string): string;
+/**
+ * The hosted server entry for Claude Code's `.mcp.json`. Claude Code rejects a
+ * bare `{ url }` as invalid, so the entry carries `type: "http"` — byte-identical
+ * to the committed `plugins/claude-code/.mcp.json`.
+ */
+export declare function hostedMcpServersJson(mcpEndpoint: string): {
+    mcpServers: {
+        spacefast: {
+            type: string;
+            url: string;
+        };
+    };
+};
+/**
+ * The hosted server entry for Cursor's `~/.cursor/mcp.json`. Cursor's known-good
+ * shape is a bare `{ url }` (no `type`) — matching the committed
+ * `plugins/cursor/.mcp.json`. Kept separate from the Claude Code generator
+ * rather than adding `type` everywhere, since `type: "http"` in Cursor's file is
+ * untested territory.
+ */
+export declare function cursorHostedMcpServersJson(mcpEndpoint: string): {
+    mcpServers: {
+        spacefast: {
+            url: string;
+        };
+    };
+};
+/** The hosted server entry for VS Code's `.vscode/mcp.json` (`servers` + `type: http`). */
+export declare function vscodeHostedMcpServersJson(mcpEndpoint: string): {
+    servers: {
+        spacefast: {
+            type: string;
+            url: string;
+        };
+    };
+};
+export declare function codexHostedMcpToml(mcpEndpoint: string): string;
+export declare const CODEX_MCP_TOML: string;
+/**
+ * Claude Code's one-command hosted-MCP connect (`claude mcp add`). Parameterized
+ * by the hosted endpoint so the dashboard can point it at the runtime-derived
+ * endpoint while the marketing site passes the prod constant.
+ */
+export declare function buildClaudeMcpAddCommand(mcpEndpoint: string): string;
+/**
+ * Codex's hosted-MCP connect. `codex mcp add` registers the server; OAuth is a
+ * separate `codex mcp login` step, so both are chained — a bare `add` leaves the
+ * connection unauthenticated and the tools 401.
+ */
+export declare function buildCodexMcpAddCommand(mcpEndpoint: string): string;
+export type ConnectCopyLanguage = "bash" | "json" | "toml" | "text";
+export type ConnectCopy = Readonly<{
+    /** Short label for the affordance and the copied-value toast. */
+    label: string;
+    /** The string written to the clipboard. */
+    value: string;
+    language: ConnectCopyLanguage;
+}>;
+export type ConnectDeeplink = Readonly<{
+    href: string;
+    label: string;
+}>;
+/** A downloadable artifact that wires the agent (e.g. the Claude desktop extension). */
+export type ConnectDownload = Readonly<{
+    href: string;
+    label: string;
+}>;
+/**
+ * A single connect card: one agent, one primary action (a one-click deeplink or
+ * a copy of the command/endpoint that wires it), plus an optional secondary
+ * "copy the client config file" affordance.
+ */
+export type ConnectTarget = Readonly<{
+    id: string;
+    name: string;
+    /** One short line on how this agent connects. */
+    blurb: string;
+    /** One-click URL-scheme install, when the client supports one. */
+    deeplink?: ConnectDeeplink;
+    /** The primary copy action when there is no deeplink (command or endpoint). */
+    primary?: ConnectCopy;
+    /** Secondary copy-the-config affordance (the client's MCP config file). */
+    config?: ConnectCopy;
+    /** A downloadable installer for clients that ship one (Claude Desktop). */
+    download?: ConnectDownload;
+}>;
+/**
+ * The per-agent connect catalog, parameterized by the hosted MCP endpoint.
+ * Every one-click and copy-config path carries the hosted endpoint (OAuth,
+ * nothing to install); on-device stdio is the CLI users' alternative and
+ * lives in the docs/marketing setup lanes, not here.
+ */
+export declare function buildConnectTargets({ mcpEndpoint }: {
+    mcpEndpoint: string;
+}): ConnectTarget[];

package/dist/agents/connect-targets.js

@@ -0,0 +1,224 @@
+/*
+ * Shared, browser-safe agent connect catalog.
+ *
+ * One source of truth for "add Spacefast to your agent": the MCP launch config,
+ * the one-click deeplinks, and the per-agent connect entries. Both the marketing
+ * site (apps/www/src/lib/llmo.ts + agent-targets.ts, with the hardcoded prod
+ * endpoint) and the dashboard (apps/my /account/agents, with the runtime-derived
+ * hosted endpoint) consume these, so every "connect an agent" surface advertises
+ * the identical command, package, and config — they can never drift apart.
+ *
+ * ISOMORPHIC ON PURPOSE: no Buffer, no process, no Node-only APIs. The dashboard
+ * renders this in the browser, so base64 goes through TextEncoder + btoa (both
+ * standard in browsers, Node 16+, and Bun) rather than Buffer.
+ */
+import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexPluginAddCommand, spacefastCodexPluginInstallCommand, } from "../docs/skill-distribution.js";
+export const LOCAL_MCP_PACKAGE = "spacefast";
+export const LOCAL_MCP_COMMAND = "npx";
+export const LOCAL_MCP_ARGS = ["-y", LOCAL_MCP_PACKAGE, "mcp"];
+/** The copy-paste one-liner form, e.g. `npx -y spacefast mcp`. */
+export const LOCAL_MCP_COMMAND_LINE = `${LOCAL_MCP_COMMAND} ${LOCAL_MCP_ARGS.join(" ")}`;
+/**
+ * base64 of a UTF-8 string, without Buffer. Byte-identical to
+ * `Buffer.from(value, "utf8").toString("base64")`, so deeplinks stay stable
+ * whether they are built at the Astro build (Node) or in the dashboard (browser).
+ */
+export function base64Utf8(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/** The on-device MCP server entry, byte-identical to the committed plugin `.mcp.json`. */
+export function localMcpServersJson() {
+    return {
+        mcpServers: {
+            [LOCAL_MCP_PACKAGE]: {
+                command: LOCAL_MCP_COMMAND,
+                args: [...LOCAL_MCP_ARGS],
+                env: {},
+            },
+        },
+    };
+}
+/**
+ * VS Code's `.vscode/mcp.json` uses a top-level `servers` key (not the
+ * `mcpServers` key Cursor/Claude Code use), so it gets its own generator —
+ * single-sourced from the same command/args/package so it can never drift.
+ * See https://code.visualstudio.com/docs/agent-customization/mcp-servers.
+ */
+export function vscodeMcpServersJson() {
+    return {
+        servers: {
+            [LOCAL_MCP_PACKAGE]: {
+                type: "stdio",
+                command: LOCAL_MCP_COMMAND,
+                args: [...LOCAL_MCP_ARGS],
+            },
+        },
+    };
+}
+/*
+ * ONE-CLICK PATHS ARE ALWAYS HOSTED. Policy: hosted MCP for cloud agents,
+ * on-device for local ones — but a one-click install must never depend on the
+ * user having npm/npx. The hosted URL server needs no runtime at all (the
+ * client speaks HTTP + OAuth), so every deeplink and every primary action
+ * carries the hosted endpoint. On-device stdio (`npx -y spacefast mcp`) stays
+ * available as the explicitly-labeled alternative for people who run the CLI —
+ * their environment already provides npx.
+ */
+// Cursor one-click MCP install link — the canonical form Cursor's own directory
+// badges emit is the HTTPS web link (`https://cursor.com/install-mcp`), which
+// renders as a normal anchor everywhere; the `cursor://` scheme still works but
+// isn't what Cursor advertises. The inner config is the hosted URL entry
+// (base64-encoded); Cursor handles the OAuth dance itself.
+export function cursorHostedMcpDeeplink(mcpEndpoint) {
+    return `https://cursor.com/install-mcp?name=${LOCAL_MCP_PACKAGE}&config=${encodeURIComponent(base64Utf8(JSON.stringify({ url: mcpEndpoint })))}`;
+}
+// VS Code one-click MCP install link — the HTTPS redirect service GitHub's
+// install badges use, which works for stable VS Code (not just Insiders). The
+// config is the server object WITHOUT the name (name is the query param), and
+// `type: "http"` is mandatory — VS Code treats a bare `url` as a stdio command
+// and fails confusingly.
+export function vscodeHostedMcpDeeplink(mcpEndpoint) {
+    return `https://insiders.vscode.dev/redirect/mcp/install?name=${LOCAL_MCP_PACKAGE}&config=${encodeURIComponent(JSON.stringify({ type: "http", url: mcpEndpoint }))}`;
+}
+/**
+ * The hosted server entry for Claude Code's `.mcp.json`. Claude Code rejects a
+ * bare `{ url }` as invalid, so the entry carries `type: "http"` — byte-identical
+ * to the committed `plugins/claude-code/.mcp.json`.
+ */
+export function hostedMcpServersJson(mcpEndpoint) {
+    return {
+        mcpServers: {
+            [LOCAL_MCP_PACKAGE]: { type: "http", url: mcpEndpoint },
+        },
+    };
+}
+/**
+ * The hosted server entry for Cursor's `~/.cursor/mcp.json`. Cursor's known-good
+ * shape is a bare `{ url }` (no `type`) — matching the committed
+ * `plugins/cursor/.mcp.json`. Kept separate from the Claude Code generator
+ * rather than adding `type` everywhere, since `type: "http"` in Cursor's file is
+ * untested territory.
+ */
+export function cursorHostedMcpServersJson(mcpEndpoint) {
+    return {
+        mcpServers: {
+            [LOCAL_MCP_PACKAGE]: { url: mcpEndpoint },
+        },
+    };
+}
+/** The hosted server entry for VS Code's `.vscode/mcp.json` (`servers` + `type: http`). */
+export function vscodeHostedMcpServersJson(mcpEndpoint) {
+    return {
+        servers: {
+            [LOCAL_MCP_PACKAGE]: { type: "http", url: mcpEndpoint },
+        },
+    };
+}
+// Codex reads MCP servers from `~/.codex/config.toml`; the hosted entry is a
+// bare streamable-HTTP url (same lane the committed codex plugin ships).
+export function codexHostedMcpToml(mcpEndpoint) {
+    return [`[mcp_servers.${LOCAL_MCP_PACKAGE}]`, `url = ${JSON.stringify(mcpEndpoint)}`].join("\n");
+}
+// The on-device stdio TOML, for CLI users whose environment provides npx.
+export const CODEX_MCP_TOML = [
+    `[mcp_servers.${LOCAL_MCP_PACKAGE}]`,
+    `command = ${JSON.stringify(LOCAL_MCP_COMMAND)}`,
+    `args = [${LOCAL_MCP_ARGS.map((arg) => JSON.stringify(arg)).join(", ")}]`,
+].join("\n");
+/**
+ * Claude Code's one-command hosted-MCP connect (`claude mcp add`). Parameterized
+ * by the hosted endpoint so the dashboard can point it at the runtime-derived
+ * endpoint while the marketing site passes the prod constant.
+ */
+export function buildClaudeMcpAddCommand(mcpEndpoint) {
+    return `claude mcp add --transport http ${LOCAL_MCP_PACKAGE} ${mcpEndpoint}`;
+}
+/**
+ * Codex's hosted-MCP connect. `codex mcp add` registers the server; OAuth is a
+ * separate `codex mcp login` step, so both are chained — a bare `add` leaves the
+ * connection unauthenticated and the tools 401.
+ */
+export function buildCodexMcpAddCommand(mcpEndpoint) {
+    return `codex mcp add ${LOCAL_MCP_PACKAGE} --url ${mcpEndpoint} && codex mcp login ${LOCAL_MCP_PACKAGE}`;
+}
+/**
+ * The per-agent connect catalog, parameterized by the hosted MCP endpoint.
+ * Every one-click and copy-config path carries the hosted endpoint (OAuth,
+ * nothing to install); on-device stdio is the CLI users' alternative and
+ * lives in the docs/marketing setup lanes, not here.
+ */
+export function buildConnectTargets({ mcpEndpoint }) {
+    const cursorConfigJson = JSON.stringify(cursorHostedMcpServersJson(mcpEndpoint), null, 2);
+    const vscodeHostedConfigJson = JSON.stringify(vscodeHostedMcpServersJson(mcpEndpoint), null, 2);
+    return [
+        {
+            // The plugin is the recommended lane for CLI agents that support one:
+            // one paste ships the publish skill AND the MCP servers (hosted primary)
+            // and stays updated through the marketplace. `claude mcp add` remains
+            // the minimal MCP-only path in the config slot and on /agents.
+            id: "claude-code",
+            name: "Claude Code",
+            blurb: "One paste installs the plugin: publish skill plus MCP, updated from the marketplace.",
+            primary: {
+                label: "Install plugin",
+                value: `${spacefastClaudePluginAddCommand} && ${spacefastClaudePluginInstallCommand}`,
+                language: "bash",
+            },
+            config: {
+                label: "MCP only: claude mcp add",
+                value: buildClaudeMcpAddCommand(mcpEndpoint),
+                language: "bash",
+            },
+        },
+        {
+            id: "cursor",
+            name: "Cursor",
+            blurb: "One click adds hosted MCP. OAuth sign-in, nothing to install.",
+            deeplink: { href: cursorHostedMcpDeeplink(mcpEndpoint), label: "Add to Cursor" },
+            config: { label: "~/.cursor/mcp.json", value: cursorConfigJson, language: "json" },
+        },
+        {
+            id: "vscode",
+            name: "VS Code",
+            blurb: "One click adds hosted MCP for Copilot agent mode.",
+            deeplink: { href: vscodeHostedMcpDeeplink(mcpEndpoint), label: "Add to VS Code" },
+            config: { label: ".vscode/mcp.json", value: vscodeHostedConfigJson, language: "json" },
+        },
+        {
+            id: "codex",
+            name: "Codex",
+            blurb: "One paste installs the plugin: publish skill plus MCP, updated from the marketplace.",
+            primary: {
+                label: "Install plugin",
+                value: `${spacefastCodexPluginAddCommand} && ${spacefastCodexPluginInstallCommand}`,
+                language: "bash",
+            },
+            config: {
+                label: "MCP only: codex mcp add",
+                value: buildCodexMcpAddCommand(mcpEndpoint),
+                language: "bash",
+            },
+        },
+        {
+            id: "claude",
+            name: "Claude",
+            blurb: "Settings → Connectors → Add custom connector, paste this endpoint. Or grab the desktop extension.",
+            primary: { label: "MCP endpoint", value: mcpEndpoint, language: "text" },
+            download: {
+                href: "https://github.com/spacefast/plugins/releases/latest/download/claude-desktop.mcpb",
+                label: "Download desktop extension",
+            },
+        },
+        {
+            id: "chatgpt",
+            name: "ChatGPT",
+            blurb: "Turn on Developer mode (Settings → Apps & Connectors → Advanced), then Connectors → Create with this endpoint.",
+            primary: { label: "MCP endpoint", value: mcpEndpoint, language: "text" },
+        },
+    ];
+}

package/dist/brand.d.ts

@@ -13,3 +13,4 @@ export declare const BRAND: {
     readonly managementHostnameApex: "view.fast";
 };
 export declare const ERROR_DOCS_BASE_URL: `${string}/docs/errors`;
+export declare const GITHUB_CHECK_RUN_NAME: "Spacefast Builds";

package/dist/brand.js

@@ -22,3 +22,8 @@ export const BRAND = {
 // plan: `${websiteOrigin}/docs/errors/{code}` forever). Lives next to the
 // brand origin it derives from; `error-codes.ts` consumes it.
 export const ERROR_DOCS_BASE_URL = `${BRAND.websiteOrigin}/docs/errors`;
+// The GitHub check-run name every build reports under. One constant because the
+// create and update paths live in different modules and drifted once
+// ("Stattic" vs "Spacefast") — GitHub keys check runs by name, so a mismatch
+// shows two orphaned checks per commit.
+export const GITHUB_CHECK_RUN_NAME = `${BRAND.productName} Builds`;

package/dist/config/domains.d.ts

@@ -12,14 +12,20 @@ export type EnvDomains = {
     /** Fully-qualified hostname per service. */
     readonly hosts: Readonly<Record<Service, string>>;
 };
-/** The full domain map for an environment. */
-export declare function domainsFor(env: DeployEnv): EnvDomains;
+/** The production apex. Everything else about prod derives from this string. */
+export declare const PROD_ENV_DOMAIN: "spacefast.com";
+/** The local-dev apex (portless serves every subdomain over HTTPS). */
+export declare const DEV_ENV_DOMAIN: "sf.localhost";
+/**
+ * Construct the full per-service host map from a single env domain
+ * (`spacefast.com`, `sf.localhost`, …). One knob — services are always
+ * `<service>.<domain>` over https, with two deliberate exceptions:
+ * the marketing site sits on the bare prod apex, and the internal handbook
+ * lives on the view.fast infra apex in prod.
+ */
+export declare function envDomainsFor(domain: string): EnvDomains;
 /** Origin (scheme + host, no trailing slash) for a service in an environment. */
 export declare function serviceOrigin(service: Service, env: DeployEnv): string;
-/** Cookie domain that scopes auth across all subdomains of an environment. */
-export declare function cookieDomainFor(env: DeployEnv): string;
-/** Domain Search Terminal (Fly.io); its web redirects to spacefast.com/domains. */
-export declare const FAST_DOMAIN_SEARCH_APEX: "fastdomainsearch.com";
 /** Atomic infrastructure apex used for public managed/custom domains. */
 export declare const VIEW_FAST_APEX: "view.fast";
 /** Apex for default space hostnames: `{hostLabel}.view.fast`. */

package/dist/config/domains.js

@@ -5,37 +5,39 @@
 //
 // Env-var NAMES intentionally stay `SPACEFAST_*` (see migration plan); only the
 // VALUES they carry are produced from this registry.
-const PROD = {
-    apex: "spacefast.com",
-    cookieDomain: ".spacefast.com",
-    protocol: "https",
-    hosts: {
-        www: "spacefast.com",
-        api: "api.spacefast.com",
-        dashboard: "my.spacefast.com",
-        superadmin: "superadmin.spacefast.com",
-        cast: "cast.spacefast.com",
-        mcp: "mcp.spacefast.com",
-        fieldguide: "fieldguide.view.fast",
-    },
-};
+/** The production apex. Everything else about prod derives from this string. */
+export const PROD_ENV_DOMAIN = "spacefast.com";
+/** The local-dev apex (portless serves every subdomain over HTTPS). */
+export const DEV_ENV_DOMAIN = "sf.localhost";
+/**
+ * Construct the full per-service host map from a single env domain
+ * (`spacefast.com`, `sf.localhost`, …). One knob — services are always
+ * `<service>.<domain>` over https, with two deliberate exceptions:
+ * the marketing site sits on the bare prod apex, and the internal handbook
+ * lives on the view.fast infra apex in prod.
+ */
+export function envDomainsFor(domain) {
+    const prod = domain === PROD_ENV_DOMAIN;
+    return {
+        apex: domain,
+        cookieDomain: `.${domain}`,
+        protocol: "https",
+        hosts: {
+            www: prod ? domain : `www.${domain}`,
+            api: `api.${domain}`,
+            dashboard: `my.${domain}`,
+            superadmin: `superadmin.${domain}`,
+            cast: `cast.${domain}`,
+            mcp: `mcp.${domain}`,
+            fieldguide: prod ? "fieldguide.view.fast" : `fieldguide.${domain}`,
+        },
+    };
+}
+const PROD = envDomainsFor(PROD_ENV_DOMAIN);
 // Local dev runs every service under *.sf.localhost via portless (HTTPS, no
 // ports in the URL — portless proxies the raw dev ports). `remove all other
 // portless records` per the migration spec: sf.localhost is the only TLD.
-const DEV = {
-    apex: "sf.localhost",
-    cookieDomain: ".sf.localhost",
-    protocol: "https",
-    hosts: {
-        www: "www.sf.localhost",
-        api: "api.sf.localhost",
-        dashboard: "my.sf.localhost",
-        superadmin: "superadmin.sf.localhost",
-        cast: "cast.sf.localhost",
-        mcp: "mcp.sf.localhost",
-        fieldguide: "fieldguide.sf.localhost",
-    },
-};
+const DEV = envDomainsFor(DEV_ENV_DOMAIN);
 // The test stack shares the sf.localhost hostname scheme but runs as its own
 // isolated compose project on its own ports/resources (see ports config), so it
 // can run side-by-side with dev. URL host scheme is identical to dev.
@@ -45,23 +47,13 @@ const BY_ENV = {
     test: TEST,
     prod: PROD,
 };
-/** The full domain map for an environment. */
-export function domainsFor(env) {
-    return BY_ENV[env];
-}
 /** Origin (scheme + host, no trailing slash) for a service in an environment. */
 export function serviceOrigin(service, env) {
     const d = BY_ENV[env];
     return `${d.protocol}://${d.hosts[service]}`;
 }
-/** Cookie domain that scopes auth across all subdomains of an environment. */
-export function cookieDomainFor(env) {
-    return BY_ENV[env].cookieDomain;
-}
 // --- Apexes that are NOT spacefast.com subdomains -------------------------------
 // These live outside the per-env map because they are stable infra identities.
-/** Domain Search Terminal (Fly.io); its web redirects to spacefast.com/domains. */
-export const FAST_DOMAIN_SEARCH_APEX = "fastdomainsearch.com";
 /** Atomic infrastructure apex used for public managed/custom domains. */
 export const VIEW_FAST_APEX = "view.fast";
 // D-4 resolved 2026-06-26: default space hostnames are