@spacefast/common 0.0.5 → 0.0.7

package/dist/docs/agent-setup.js

@@ -1,11 +1,176 @@
-import { BRAND } from "@spacefast/common/brand";
-import { PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, } from "@spacefast/common/docs/agent-prose";
-import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
+import { getConnectTarget, } from "../agents/connect-targets.js";
+import { BRAND } from "../brand.js";
+import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_PROSE, HOW_TO_RESEARCH_PROSE, LANE_PICKER_PROSE, POSITIONING_PROSE, PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SAVE_STATE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, UPDATE_SPACE_PROSE, } from "./agent-prose.js";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "./skill-distribution.js";
 export const agentSetupUrl = `${BRAND.agentSetupOrigin}/ai`;
 export const agentSetupTextUrl = `${BRAND.agentSetupOrigin}/ai.txt`;
 const agentSetupParsedUrl = new URL(agentSetupUrl);
 export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUrl.pathname;
-export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow the instructions to publish for me. Ask me what I want to publish if it isn't obvious.`;
+export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow it to publish this project — or update it if it's already on ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+/*
+ * Agent handoff contract: links use https://<app-origin>/agent/<documentId>#<secret>, with
+ * opaque document IDs and secrets. The fragment is the secret, so ordinary document fetches
+ * never send or reveal it. Fetching never consumes a handoff; exactly one successful redemption
+ * does. Redemption is app-private, reuses the existing device/OAuth approval service, and returns
+ * the already-approved finite Space-scoped credential: there is no public AgentGrant resource,
+ * durable key table, or team-wide publisher key. The CLI accepts links only through stdin or a
+ * browser callback and redacts them from JSON output, telemetry, shell history, doctor, and
+ * receipts. The dashboard can revoke an unused handoff.
+ */
+const opaqueHandoffDocumentId = /^[A-Za-z0-9_-]{1,512}$/;
+const opaqueHandoffSecret = /^[A-Za-z0-9_-]{16,512}$/;
+const shellSafeMcpEndpoint = /^[A-Za-z0-9%+,\-./:=_[\]~]+$/;
+/**
+ * Typed, safe decline states for the app-private redemption exchange.
+ * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; state-specific reasons are returned only after the
+ * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
+ * first exchange succeeds, the second fails with this reason. Declines are terminal and never
+ * reveal whether a secret was close to correct.
+ */
+export const AGENT_HANDOFF_DECLINE_REASONS = [
+    "invalid_handoff",
+    "expired",
+    "already_redeemed",
+    "revoked",
+    "client_mismatch",
+    "origin_mismatch",
+];
+function isSafeHttpUrl(url) {
+    return ((url.protocol === "https:" ||
+        (url.protocol === "http:" &&
+            (url.hostname === "localhost" ||
+                url.hostname === "127.0.0.1" ||
+                url.hostname === "[::1]"))) &&
+        !url.username &&
+        !url.password);
+}
+/**
+ * The single shared grammar for handoff links:
+ * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
+ * high-entropy and makes the public-projection leak check meaningful); the two must differ;
+ * queries and embedded credentials are forbidden; HTTPS is required except on loopback hosts.
+ * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
+ * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
+ * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
+ * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
+ * grammar can never fork.
+ */
+export function parseAgentHandoffUrl(value, expectedOrigin) {
+    let canonicalExpectedOrigin;
+    try {
+        canonicalExpectedOrigin = new URL(expectedOrigin).origin;
+    }
+    catch {
+        throw new TypeError("Agent handoff expectedOrigin must be a valid URL origin.");
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("Agent handoff URL must be a valid HTTP(S) URL.");
+    }
+    const documentId = /^\/agent\/([^/]+)$/.exec(url.pathname)?.[1];
+    const secret = url.hash.slice(1);
+    if (!isSafeHttpUrl(url) ||
+        url.origin !== canonicalExpectedOrigin ||
+        value.includes("?") ||
+        !documentId ||
+        !opaqueHandoffDocumentId.test(documentId) ||
+        !opaqueHandoffSecret.test(secret) ||
+        documentId === secret) {
+        throw new TypeError("Agent handoff URL must be an HTTPS /agent/<id> URL with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query (HTTP is allowed on loopback hosts).");
+    }
+    return { documentId, documentUrl: `${url.origin}${url.pathname}`, secret };
+}
+function validateMcpEndpoint(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("MCP endpoint must be a valid HTTP(S) URL.");
+    }
+    if (!shellSafeMcpEndpoint.test(value) || !isSafeHttpUrl(url)) {
+        throw new TypeError("MCP endpoint must be a shell-safe HTTPS URL with no credentials, query, fragment, or control characters (HTTP is allowed on loopback hosts).");
+    }
+    return url.href.replace(/\/$/, "");
+}
+function renderAgentHandoffInstructions(documentUrl, target) {
+    const setupSections = [target.primary, target.config].flatMap((setup) => setup ? [[setup.label, `\`\`\`${setup.language}`, setup.value, "```"].join("\n")] : []);
+    const connectSections = [
+        target.blurb,
+        ...setupSections,
+        target.deeplink ? `${target.deeplink.label}: ${target.deeplink.href}` : null,
+        target.download ? `${target.download.label}: ${target.download.href}` : null,
+    ].filter((section) => section !== null);
+    const approvalGuidance = target.id === "claude-code" || target.id === "codex"
+        ? `Run \`sf setup agent\` to initiate the handoff exchange; if \`sf\` is missing, install it first (macOS/Linux: \`${spacefastInstallCurlCommand}\`; Windows PowerShell: \`${spacefastInstallPowerShellCommand}\`). When it asks for the handoff link on stdin, paste the original link into that prompt; never pass the link as an argv value. Ask the user to approve in the browser, then wait for the CLI's approval result before publishing.`
+        : "When the client opens browser approval, ask the user to approve there before publishing.";
+    const sections = [
+        `# Set up ${BRAND.productName} with ${target.name}`,
+        `This is the public setup document for ${documentUrl}.`,
+        "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.",
+        ["## Connect", ...connectSections].join("\n\n"),
+        [
+            "## Continue the approved handoff",
+            "Keep the original handoff link private. Fetching this document did not use the link or send its fragment secret; the secret is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.",
+            approvalGuidance,
+            "Keep its fragment out of commands, request URLs, logs, and replies.",
+        ].join("\n\n"),
+        [
+            "## Publish",
+            "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Share the live URL and immutable version URL from the receipt.",
+        ].join("\n\n"),
+        `General agent instructions: ${agentSetupTextUrl}`,
+    ];
+    return `${sections.join("\n\n")}\n`;
+}
+/** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
+export function buildAgentHandoff(input) {
+    const { documentUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin);
+    const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
+    const target = getConnectTarget(input.targetId, {
+        mcpEndpoint,
+    });
+    const prompt = `Fetch ${documentUrl}#${secret} and follow the ${target.name} setup instructions to publish with ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+    const instructions = renderAgentHandoffInstructions(documentUrl, target);
+    const actions = [
+        { kind: "copy", label: "Copy for my agent", sensitive: true, value: prompt },
+        { kind: "copy", label: "Copy Markdown", sensitive: false, value: instructions },
+    ];
+    if (target.deeplink) {
+        actions.push({
+            kind: "open",
+            label: target.deeplink.label,
+            href: target.deeplink.href,
+        });
+    }
+    if (target.download) {
+        actions.push({
+            kind: "open",
+            label: target.download.label,
+            href: target.download.href,
+        });
+    }
+    // The scanner-safe invariant is total, not statistical: no public projection may contain the
+    // secret, no matter what the caller fed in (a pathological mint, a poisoned MCP endpoint).
+    const publicProjections = [
+        documentUrl,
+        instructions,
+        ...actions.flatMap((action) => {
+            if (action.kind === "open")
+                return [action.href];
+            return action.sensitive ? [] : [action.value];
+        }),
+    ];
+    if (publicProjections.some((projection) => projection.includes(secret))) {
+        throw new TypeError("Agent handoff inputs would leak the fragment secret into a public projection.");
+    }
+    return { actions, documentUrl, instructions, prompt };
+}
 export function renderAgentSetupTemplate(value) {
     return value
         .replaceAll("{{AGENT_SETUP_URL}}", agentSetupUrl)
@@ -19,9 +184,13 @@ export function aiInstructionsText() {
     return [
         `# ${BRAND.productName} for AI agents`,
         "",
-        `Official instructions for AI agents publishing to ${BRAND.productName}, the static host where`,
-        "AI-made things are kept: permanent URLs, immutable versions, anonymous publish",
-        "with a claim link. Static files only — server code is never executed.",
+        `Official instructions for AI agents publishing to ${BRAND.productName}.`,
+        "",
+        POSITIONING_PROSE,
+        "",
+        "## Before you publish (check for an existing space)",
+        "",
+        CHECK_BEFORE_PUBLISH_PROSE,
         "",
         "## Publish with curl (no install, no account)",
         "",
@@ -29,6 +198,14 @@ export function aiInstructionsText() {
         "",
         RECEIPT_SHAPE_PROSE,
         "",
+        "## Save your state",
+        "",
+        SAVE_STATE_PROSE,
+        "",
+        "## Update a space",
+        "",
+        UPDATE_SPACE_PROSE,
+        "",
         "## Big files and cloud agents",
         "",
         SIGNED_UPLOAD_PROSE,
@@ -37,6 +214,14 @@ export function aiInstructionsText() {
         "",
         SECRET_RULES_PROSE,
         "",
+        "## Failure conduct",
+        "",
+        FAILURE_CONDUCT_PROSE,
+        "",
+        "## How to research",
+        "",
+        HOW_TO_RESEARCH_PROSE,
+        "",
         'Add a bearer access token with `-H "Authorization: Bearer ..."` to publish into the user\'s',
         "team instead of anonymously. Agent clients should prefer OAuth client credentials. Errors come back as JSON with stable `code` values and a",
         "`docsUrl`; fetch the `docsUrl` when you need recovery steps.",
@@ -69,15 +254,17 @@ export function aiInstructionsText() {
         "```",
         "",
         "Use `--json` on any command when the output will be parsed. Publishing the same",
-        "directory again updates the space saved in `.stattic/state.json`.",
+        "directory again updates the space saved in `.spacefast/state.json`.",
         "",
         "## MCP for agent clients",
         "",
+        LANE_PICKER_PROSE,
+        "",
         "Hosted MCP is the no-download cloud lane for ChatGPT, Codex, Claude, Cursor, and browser",
         "clients that can authenticate with OAuth/API bearer credentials:",
         "",
         "```text",
-        "https://mcp.spacefast.com/mcp",
+        "https://mcp.spacefast.com",
         "```",
         "",
         "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
@@ -98,8 +285,8 @@ export function aiInstructionsText() {
         "`spacefast://account/current`, `spacefast://teams/current`, `spacefast://spaces/recent`,",
         "`spacefast://spaces/{spaceId}`, and `spacefast://policy/current` for bounded read-only",
         "context.",
-        "`execute_spacefast` is dry-run-first; mutating multi-step workflows can return",
-        "`approval_required` and continue through `resume_spacefast` after the user approves.",
+        "`execute` is dry-run-first; mutating multi-step workflows can return",
+        "`approval_required` and continue through `resume` after the user approves.",
         "",
         "Use On-Device MCP when the agent needs the user's checkout, path-based publish, or file edits:",
         "",
@@ -115,15 +302,19 @@ export function aiInstructionsText() {
         "`SPACEFAST_AGENT_CONFIG` with private_key_jwt when available; otherwise use one-job",
         "`SPACEFAST_TOKEN` secrets and mask logs. Do not persist personal auth in ephemeral runners.",
         "",
-        "If your environment supports skill import, fetch the official skill for the",
-        `complete command reference: \`${spacefastSkillInstallCommand}\` (source: ${spacefastSkillUrl}).`,
+        "If your environment supports skill import, install the official skill:",
+        `\`${spacefastSkillInstallCommand}\`. Raw markdown source: \`${spacefastSkillFetchCommand}\` (${spacefastSkillUrl}).`,
         "",
         "## After publishing",
         "",
         "- Share the live URL, the immutable version URL when ready, and — for anonymous spaces —",
         "  the claim link with its expiry. If the receipt's immutable URL is null, poll the",
         "  operation and version links with the claim token as bearer auth until the version is ready.",
-        "- Never print access tokens, claim tokens, auth files, or `.stattic/state.json`.",
+        "- Never print access tokens, claim tokens, auth files, or `.spacefast/state.json`.",
+        "",
+        "## After the user claims",
+        "",
+        CONTINUE_AFTER_CLAIM_PROSE,
         "",
         "## Space conventions",
         "",
@@ -152,14 +343,20 @@ export function aiInstructionsText() {
         "## Going deeper",
         "",
         "- Docs index for agents: https://spacefast.com/llms.txt",
+        "- One-click connect (Claude Code, Claude, Codex, Cursor, VS Code): https://spacefast.com/agents",
         "- Agent guide: https://spacefast.com/docs/agents",
         "- CLI reference: https://spacefast.com/docs/cli",
         "- REST API + OpenAPI: https://spacefast.com/docs/api",
         "- Publish contract (machine-readable): https://spacefast.com/publish-spec.json",
+        "- Connectors-directory manifest (hosted MCP listing): https://spacefast.com/.well-known/connector.json",
         "- Every error code: https://spacefast.com/docs/errors",
         "",
         "Append `.md` to any docs URL for Markdown, or just fetch — agent user agents get",
         "Markdown automatically.",
         "",
+        "## Environment notes",
+        "",
+        ENV_NOTES_PROSE,
+        "",
     ].join("\n");
 }

package/dist/docs/agent-solutions.d.ts

@@ -1,4 +1,4 @@
-export declare const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+export declare const hostedMcpEndpointUrl = "https://mcp.spacefast.com";
 export type AgentSolutionLane = "plugin" | "hosted-mcp" | "local-mcp" | "cli" | "prompt";
 export type AgentSolutionId = "codex" | "claude-code" | "claude-cowork" | "chatgpt" | "claude-ai" | "raycast" | "cursor" | "terminal" | "generic";
 export type AgentSolution = {
@@ -20,7 +20,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "plugin";
     readonly summary: "Recommended: Codex plugin.";
     readonly description: "Install the Spacefast skill/plugin so Codex can publish, update, and inspect spaces from the same setup path.";
-    readonly commands: readonly ["npx skills add spacefast/plugins --skill spacefast -g"];
+    readonly commands: readonly ["npx -y skills add spacefast/plugins --skill spacefast -g -a codex -y"];
     readonly guideUrl: `${string}/for-codex`;
     readonly detailGuideUrl: `${string}/guides/how-to-use-with-codex`;
     readonly setupText: string;
@@ -53,7 +53,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Connect ChatGPT-style cloud agents to Spacefast through hosted MCP; use the virtual workspace or signed uploads instead of local paths.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {
@@ -63,7 +63,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Connect the web Claude app to Spacefast through hosted MCP when it cannot read your local checkout.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {
@@ -73,7 +73,7 @@ export declare const agentSolutions: readonly [{
     readonly lane: "hosted-mcp";
     readonly summary: "Recommended: direct hosted MCP.";
     readonly description: "Use hosted MCP for Raycast and similar clients that can connect to a remote MCP server but should not need a local Spacefast install.";
-    readonly commands: readonly ["https://mcp.spacefast.com/mcp"];
+    readonly commands: readonly ["https://mcp.spacefast.com"];
     readonly guideUrl: `${string}/docs/agents`;
     readonly setupText: string;
 }, {

package/dist/docs/agent-solutions.js

@@ -1,7 +1,7 @@
 import { BRAND } from "../brand.js";
 import { agentSetupPrompt, agentSetupTextUrl, agentSetupUrl } from "./agent-setup.js";
 import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexSkillInstallCommand, spacefastInstallCurlCommand, } from "./skill-distribution.js";
-export const hostedMcpEndpointUrl = "https://mcp.spacefast.com/mcp";
+export const hostedMcpEndpointUrl = "https://mcp.spacefast.com";
 function pluginText(label, commands, guideUrl) {
     return [
         `Set up ${BRAND.productName} for ${label}.`,
@@ -20,7 +20,7 @@ function hostedMcpText(label, guideUrl) {
         "",
         `MCP endpoint: ${hostedMcpEndpointUrl}`,
         "Transport: Streamable HTTP",
-        "Resource: https://api.spacefast.com/mcp",
+        "Resource: https://mcp.spacefast.com",
         "Minimum scope: mcp:tools",
         "Common scopes: teams:read spaces:read spaces:write publish:write domains:read domains:write",
         "",