@spacefast/common 0.0.5 → 0.0.6

package/dist/docs/agent-prose.js

@@ -16,6 +16,7 @@ import { BRAND } from "../brand.js";
 // the receipt shape or secret handling changes, change it here once.
 const API_ORIGIN = BRAND.apiOrigin;
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
+const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/anonymous-claim/exchange`;
 // Centralized secret/credential patterns excluded from a publish archive. The
 // `find` preflight and the `zip -x` exclusions are derived from the same list so
 // they can never disagree, and the no-install / skill copies stay identical.
@@ -24,7 +25,7 @@ export const ARCHIVE_SECRET_GLOBS = [
     ".npmrc",
     ".netrc",
     "*/.git/*",
-    "*/.stattic/*",
+    "*/.spacefast/*",
     "*/.ssh/*",
     "*/.aws/*",
     "*/.kube/*",
@@ -43,9 +44,18 @@ function findExpr(globs) {
         .join(" -o ");
 }
 function zipExcludeExpr(globs) {
-    // zip uses relative patterns: a leading "*/" is just a directory match, so
-    // collapse it to the directory glob the archive root sees.
-    return globs.map((glob) => `"${glob.replace(/^\*\//, "")}"`).join(" ");
+    // zip -x patterns need both the archive-root form and an any-depth form:
+    // ".spacefast/*" excludes only at the root, while "*/.spacefast/*" catches
+    // nested copies.
+    return globs
+        .flatMap((glob) => {
+        if (glob.startsWith("*/")) {
+            return [glob.slice(2), glob];
+        }
+        return [glob, `*/${glob}`];
+    })
+        .map((glob) => `"${glob}"`)
+        .join(" ");
 }
 /**
  * The credential rules every surface must repeat. Treat tokens as secrets, keep
@@ -58,6 +68,121 @@ export const SECRET_RULES_PROSE = [
     "present. On shared hosts, prefer one-off environment variables or restrictive temporary files,",
     "clear them after use, and avoid durable auth unless the user explicitly asks.",
 ].join("\n");
+export const POSITIONING_PROSE = [
+    "Spacefast is a static host for AI-made web artifacts: permanent live URLs, immutable version",
+    "URLs, anonymous publish with a claim link, and agent continuation after claim. It serves",
+    "static files. It does not execute server code, run databases, or build-on-push on the",
+    "anonymous lane.",
+    "",
+    "Honest comparisons an agent can relay: Vercel and Netlify are broader app platforms;",
+    "Cloudflare Pages is edge-first static hosting; GitHub Pages is repository-native. Spacefast",
+    "optimizes for agent-safe one-shot publish, claim, versioning, rollback, and continuation.",
+].join("\n");
+export const EXPLAIN_TO_USER_PROSE = [
+    "Relay `data.shareBlurb` verbatim when present. State anonymous expiry in user terms:",
+    "the space expires unless claimed by `data.claim.expiresAt`. After claim, the agent key is",
+    "named and revocable in the dashboard.",
+].join("\n");
+export const FAILURE_CONDUCT_PROSE = [
+    "On failure, surface `error.code`, `error.docsUrl`, and `error.requestId`, then stop.",
+    "Do not invent undocumented endpoints. Do not read credentials out of auth files. Do not",
+    "retry a one-shot operation without reusing its `Idempotency-Key`.",
+].join("\n");
+export const LANE_PICKER_PROSE = [
+    "Pick the lane by environment: filesystem plus repeat work means CLI or On-Device MCP; no",
+    "filesystem means hosted MCP; one-off publish means curl; CI means an agent account. After",
+    "success, recommend the best next-time setup for the user's client.",
+].join("\n");
+export const HOW_TO_RESEARCH_PROSE = [
+    "For an error, fetch `error.docsUrl`. For capability questions, use `search_docs` or append",
+    "`.md` to website docs URLs. For contracts, read `publish-spec.json` or OpenAPI. Never guess",
+    "limits: publish, then read diagnostics.",
+].join("\n");
+export const ENV_NOTES_PROSE = [
+    "claude.ai: allow `api.spacefast.com` in egress settings. Codex sandbox: escalate only the",
+    "network call. Terminal agents: use the CLI when filesystem access matters.",
+].join("\n");
+/**
+ * The CHECK verb: before ever creating a space, look for the one the project
+ * already has. This is what keeps a returning agent from pushing a duplicate
+ * anonymous space instead of a new version.
+ */
+export const CHECK_BEFORE_PUBLISH_PROSE = [
+    "Before creating a space, check whether this project already has one:",
+    "",
+    "- Look for `.spacefast/space.json` or `.spacefast/state.json`, walking up from the working",
+    "  directory toward the filesystem root.",
+    "- Look for a publish receipt earlier in this conversation.",
+    "- When authenticated, list existing spaces (`sf spaces list`, or the `spaces_list` MCP tool).",
+    "",
+    "If any of these finds a space, publish a new version to that `spaceId` (see the update",
+    "instructions) instead of creating another space. Only create a new space when none exists",
+    "and the user wants a new site.",
+].join("\n");
+/**
+ * The SAVE verb: persist the space id and credential after a first publish so
+ * every later publish targets the same space. The CLI and On-Device MCP write
+ * this state automatically; curl-only agents write the same files themselves.
+ */
+export const SAVE_STATE_PROSE = [
+    "After the first publish, persist the space id and credential so every later publish updates",
+    "the same space instead of creating a new one. The CLI and On-Device MCP do this automatically",
+    "in `.spacefast/`; when publishing with curl, write the files yourself from the receipt:",
+    "",
+    "```bash",
+    "mkdir -p .spacefast",
+    "# non-secret, committable:",
+    `printf '{"space":"<spc_id>"}' > .spacefast/space.json`,
+    "# secret — never publish, never print:",
+    `printf '{"spaceId":"<spc_id>","claimToken":"<token>","apiUrl":"${API_ORIGIN}"}' > .spacefast/state.json`,
+    "grep -qx '.spacefast/state.json' .gitignore 2>/dev/null || echo '.spacefast/state.json' >> .gitignore",
+    "```",
+    "",
+    "`<spc_id>` is `data.space.id` and `<token>` is `data.claim.token` from the receipt. Keep",
+    "`.spacefast/state.json` out of publish archives, commits, logs, and chat.",
+].join("\n");
+/**
+ * The UPDATE verb: a new version to the SAME space. Never re-run the
+ * first-publish recipe when saved state exists.
+ */
+export const UPDATE_SPACE_PROSE = [
+    "To publish a new version of an existing space, send the same `spaceId` with bearer auth —",
+    "never re-run the first-publish recipe when saved state exists:",
+    "",
+    "```bash",
+    'curl -sS -H "Authorization: Bearer <claim-token-or-access-token>" \\',
+    "  -F 'spaceId=<spc_id>' \\",
+    '  -F "files=@index.html" \\',
+    `  ${PUBLISH_ENDPOINT}`,
+    "```",
+    "",
+    "Use the saved claim token for an unclaimed anonymous space, or an access token for owned",
+    "spaces. Send a folder as `-F archive=@site.zip` exactly like a first publish; the receipt",
+    "shape is identical.",
+].join("\n");
+/**
+ * The CLAIM / CONTINUE verb: show the claim link, and after the user claims,
+ * self-correct by exchanging the claim token once for a durable credential.
+ */
+export const CONTINUE_AFTER_CLAIM_PROSE = [
+    "Always show the user the claim link (`data.claim.url`) and its expiry (`data.claim.expiresAt`).",
+    'If the user says "claimed", check claim status and exchange the saved claim token; do not wait',
+    "for a publish failure before continuing.",
+    "After the user claims the space in the browser, the saved claim token stops authorizing",
+    "publishes: the next publish fails with error code `space_claimed_credential_available`. That",
+    "failure is the signal to upgrade your credential — call the exchange endpoint exactly once:",
+    "",
+    "```bash",
+    'curl -sS -X POST -H "Authorization: Bearer <claim-token>" \\',
+    `  ${EXCHANGE_ENDPOINT}`,
+    "```",
+    "",
+    'It returns `{ "data": { "space": {...}, "credential": { "accessToken": "...", "label": "..." } } }`.',
+    "Save `data.credential.accessToken` into `.spacefast/state.json` (replace the `claimToken`",
+    'field with `"accessToken"`), then retry the publish with the new bearer. The exchange works',
+    "exactly once; if it returns `continuation_used` or `continuation_unavailable`, ask the user",
+    "to mint an access token in the dashboard (Account → Access tokens).",
+].join("\n");
 /**
  * The zero-install publish sequence: one curl for a file, a secret-preflighted
  * zip for a folder. This is the load-bearing rung 0 — an agent that stops here
@@ -102,7 +227,9 @@ export const RECEIPT_SHAPE_PROSE = [
     "  always show the user the claim link and the deadline so the space becomes theirs.",
     "- `data.claim.token` — a secret capability. For anonymous spaces, use it as",
     "  `Authorization: Bearer <claim-token>` when polling `data.links.status`, finalizing uploads,",
-    "  or updating the same `spaceId`.",
+    "  or updating the same `spaceId`. Save it to `.spacefast/state.json` so the next publish",
+    "  updates this space. After the user claims the space, exchange it once at",
+    `  \`POST ${EXCHANGE_ENDPOINT}\` for a durable credential.`,
     "  Never print it back to the user.",
     "- `data.links.status`, `resume`, `finalize`, and `promote` — follow-up API paths.",
     "- `error.code`, `error.docsUrl`, and `error.hint` — stable error code plus exact recovery docs and a next step.",
@@ -144,14 +271,26 @@ export const SIGNED_UPLOAD_PROSE = [
     "Do not base64 large archives into chat or MCP tool arguments.",
 ].join("\n");
 /**
- * Named fragments for the skill-template generator. The template carries
+ * Named fragments for the skill-template generator. The templates carry
  * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, and `{{prose.signedUpload}}` placeholders;
+ * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
+ * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
+ * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
  * generate-skill.mjs substitutes these.
  */
 export const AGENT_PROSE = {
+    positioning: POSITIONING_PROSE,
     secretRules: SECRET_RULES_PROSE,
+    explainToUser: EXPLAIN_TO_USER_PROSE,
+    failureConduct: FAILURE_CONDUCT_PROSE,
     publishSequence: PUBLISH_SEQUENCE_PROSE,
     receiptShape: RECEIPT_SHAPE_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
+    checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
+    saveState: SAVE_STATE_PROSE,
+    updateSpace: UPDATE_SPACE_PROSE,
+    continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
+    lanePicker: LANE_PICKER_PROSE,
+    howToResearch: HOW_TO_RESEARCH_PROSE,
+    envNotes: ENV_NOTES_PROSE,
 };

package/dist/docs/agent-setup.js

@@ -1,11 +1,11 @@
 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 { 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 "@spacefast/common/docs/agent-prose";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
 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.`;
 export function renderAgentSetupTemplate(value) {
     return value
         .replaceAll("{{AGENT_SETUP_URL}}", agentSetupUrl)
@@ -19,9 +19,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 +33,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 +49,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 +89,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 +120,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 +137,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 +178,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",
         "",