@spacefast/common 0.0.12 → 0.0.17

package/dist/docs/catalog.js

@@ -17,6 +17,7 @@
 // and MCP search without a second hand-maintained corpus to drift.
 import { errorDocsUrl } from "../contracts/error-codes.js";
 import { ERROR_DOCS } from "./error-docs.js";
+import { renderSpacefastSkill, SPACEFAST_RECIPE_SKILLS } from "./skills.js";
 /** Which part of the docs a page belongs to (runtime list + derived type). */
 export const DOC_KINDS = ["guide", "cli", "api", "recipe", "workflow", "error"];
 /** Base URL all bundled docs links resolve against. */
@@ -43,6 +44,16 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         url: `${DOCS_BASE_URL}/publishing`,
         body: "`sf publish` snapshots your output directory into an immutable version and promotes it to the production channel. Use `--no-wait` to return before serving finishes.",
     },
+    {
+        slug: "spaces/rename",
+        title: "Rename a space",
+        kind: "guide",
+        tier: "full",
+        summary: "Change a space slug and its managed view.fast address without breaking old links.",
+        keywords: ["space", "rename", "slug", "view.fast", "redirect", "managed hostname"],
+        url: `${DOCS_BASE_URL}/spaces/rename`,
+        body: 'Run `sf spaces update --space <space> --slug <new-slug> --wait`, or PATCH `/v1/spaces/{spaceId}` with `{ "slug": "<new-slug>" }`. The managed view.fast hostname changes with the slug. Former managed addresses and branch aliases redirect directly to their current counterparts with a temporary, path- and query-preserving 307 for the life of the space unless an operator explicitly releases them. Custom domains stay attached, and immutable version URLs do not change.',
+    },
     {
         slug: "versions-and-rollback",
         title: "Versions and rollback",
@@ -89,10 +100,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "Publish receipt fields",
         kind: "workflow",
         tier: "full",
-        summary: "Use the receipt as the source of truth: space.liveUrl, version.immutableUrl, shareBlurb, claim.url, claim.expiresAt, links, diagnostics, and errors.",
+        summary: "Use the receipt as the source of truth. Present open.url and claim.url as the two user-facing links; liveUrl and immutableUrl identify resources for automation.",
         keywords: ["receipt", "share", "claim", "diagnostics"],
         url: `${DOCS_BASE_URL}/api#publish`,
-        body: "receipt liveUrl immutableUrl shareBlurb claim url expiresAt diagnostics links finalize promote upload errors docsUrl",
+        body: "receipt liveUrl open url immutableUrl claim expiresAt diagnostics links finalize promote upload errors docsUrl",
     },
     {
         slug: "workflow/continue-after-claim",
@@ -108,7 +119,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
             "continuation",
         ],
         url: `${DOCS_BASE_URL}/agents#continue-after-claim`,
-        body: "continue continuation claim token exchange voucher continue_space POST /v1/anonymous-claim/exchange space_claimed_credential_available continuation_used continuation_unavailable durable access token state.json update after claim claim_status",
+        body: "continue continuation claim token exchange voucher publish execute POST /v1/anonymous-claim/exchange space_claimed_credential_available continuation_used continuation_unavailable durable access token state.json update after claim",
     },
     {
         slug: "workflow/secret-handling",
@@ -125,10 +136,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "CLI command surface",
         kind: "workflow",
         tier: "full",
-        summary: "Use sf for repeat work: publish, versions, rollback, logs, domains, passwords, teams, API calls, and On-Device MCP serving.",
+        summary: "Use sf for repeat work: publish, versions, rollback, logs, domains, sharing, teams, API calls, and On-Device MCP serving.",
         keywords: ["sf", "cli", "spacefast", "mcp", "json"],
         url: `${DOCS_BASE_URL}/cli`,
-        body: "sf spacefast CLI publish versions rollback logs domains passwords teams api mcp setup profile login --json",
+        body: "sf spacefast CLI publish versions rollback logs domains share teams api mcp setup profile login --json",
     },
     {
         slug: "workflow/mcp-local",
@@ -140,35 +151,6 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         url: `${DOCS_BASE_URL}/agents#mcp`,
         body: "MCP on-device local CLI stdio streamable HTTP sf mcp roots files workspace tool calls structuredContent apps",
     },
-    {
-        slug: "workflow/workspace-files",
-        title: "Agent workspace files",
-        kind: "workflow",
-        tier: "full",
-        summary: "Hosted MCP workspace tools edit, import, export, and publish a durable virtual workspace; On-Device MCP workspace tools edit the bounded local root.",
-        keywords: [
-            "workspace",
-            "files",
-            "patch",
-            "diff",
-            "virtual workspace",
-            "workspace import",
-            "workspace export",
-            "just-bash",
-        ],
-        url: `${DOCS_BASE_URL}/agents#workspace-files`,
-        body: "workspace file editing read write patch diff list manifest import export import_url hosted virtual workspace just-bash shell handoff on-device root SPACEFAST_MCP_WORKSPACE_ROOT secret scanning bounded files",
-    },
-    {
-        slug: "workflow/mcp-resources",
-        title: "MCP resources for account, teams, spaces, and policy",
-        kind: "workflow",
-        tier: "full",
-        summary: "Use read-only resources for bounded context before tools: account/current, teams/current, spaces/recent, space detail, recent versions, policy/current, and workspace/manifest.",
-        keywords: ["resources", "account", "teams", "spaces", "policy", "context"],
-        url: `${DOCS_BASE_URL}/agents#mcp-resources`,
-        body: "MCP resources account current teams current list spaces recent space detail versions recent domains logs summary policy current workspace manifest tools catalog read-only context redacted",
-    },
     {
         slug: "workflow/space-files",
         title: "Space file conventions",
@@ -177,7 +159,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Spacefast recognizes _redirects, _headers, nearest 404.html, and sf.jsonc. Static artifacts are served as files; server code is not executed.",
         keywords: ["_redirects", "_headers", "sf.jsonc", "spacefast.jsonc", "404"],
         url: `${DOCS_BASE_URL}/configuration`,
-        body: "_redirects _headers 404.html sf.jsonc static artifact server code not executed proxy rewrite headers basic auth",
+        body: "_redirects _headers 404.html sf.jsonc static artifact server code not executed proxy rewrite headers",
     },
     {
         slug: "workflow/domains-diagnostics",
@@ -244,10 +226,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "Access control",
         kind: "guide",
         tier: "full",
-        summary: "Password-protect a space or grant access to specific people.",
-        keywords: ["access", "password", "grant", "ban", "private", "audience", "auth"],
+        summary: "Create scoped Grants, invite People, and manage Links or credentials.",
+        keywords: ["access", "share", "people", "links", "private", "team", "public"],
         url: `${DOCS_BASE_URL}/access`,
-        body: "Gate a space with `sf password set`, grant individuals with `sf access grant`, and review effective rules with `sf access effective`.",
+        body: "Use `sf share grant`, `sf share people`, `sf share link`, `sf share password`, or `sf share token`. Inspect one route with `sf share check`; every audience uses the same path, capability, target, and constraint evaluator.",
     },
     {
         slug: "redirects",
@@ -264,10 +246,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "Custom headers",
         kind: "guide",
         tier: "full",
-        summary: "Attach response headers and path-scoped Basic Auth.",
-        keywords: ["headers", "cache", "security", "basic auth", "_headers", "cors"],
+        summary: "Attach supported response headers by path.",
+        keywords: ["headers", "cache", "security", "_headers", "cors"],
         url: `${DOCS_BASE_URL}/headers`,
-        body: "Add a `_headers` file at your publish root to set or remove response headers per path. Path-scoped Basic Auth credentials travel with the publish.",
+        body: "Add a `_headers` file at your publish root to set or remove supported response headers per path.",
     },
     {
         slug: "builds",
@@ -277,7 +259,58 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Connect a repository so pushes build and publish automatically.",
         keywords: ["build", "git", "github", "ci", "push", "connect", "preview"],
         url: `${DOCS_BASE_URL}/builds`,
-        body: "Connect a repository with `sf git connect`; each push runs your build on Spacefast and publishes a version, with branches and pull requests getting preview URLs.",
+        body: "Connect a repository with `sf git connect`; each push runs your build on Spacefast and publishes a version. Branch and pull-request previews are private by default; use Open for yourself or create a scoped Link for reviewers.",
+    },
+    {
+        slug: "runtimes",
+        title: "Runtimes",
+        kind: "guide",
+        tier: "full",
+        summary: "Run code on a space with Zero or Functions.",
+        keywords: ["runtime", "zero", "functions", "server", "dynamic", "code", "backend", "sf.jsonc"],
+        url: `${DOCS_BASE_URL}/runtimes`,
+        body: "A space serves static files until you declare a `runtime` block in sf.jsonc. Zero is a capsule with its own database and transactions; Functions is a worker with one `fetch` handler and any npm package. Both compile during `sf publish`. Zero runs on plans with dedicated runtime isolation; Functions remains in private beta.",
+    },
+    {
+        slug: "runtimes/zero",
+        title: "Spacefast Zero",
+        kind: "guide",
+        tier: "full",
+        summary: "A capsule with a database: schema, queries, mutations, endpoints.",
+        keywords: [
+            "zero",
+            "capsule",
+            "database",
+            "schema",
+            "query",
+            "mutation",
+            "endpoint",
+            "transaction",
+            "sql",
+            "sf dev",
+        ],
+        url: `${DOCS_BASE_URL}/runtimes/zero`,
+        body: "Zero is for apps where the data is the point. Write one capsule — schema, queries, mutations, endpoints — start it locally with `sf dev`, and `sf publish` puts it live with its own database on a plan with dedicated runtime isolation.",
+    },
+    {
+        slug: "runtimes/functions",
+        title: "Spacefast Functions",
+        kind: "guide",
+        tier: "full",
+        summary: "A worker for your space: one `fetch` handler, any npm package.",
+        keywords: [
+            "functions",
+            "worker",
+            "fetch",
+            "ssr",
+            "cloudflare",
+            "npm",
+            "handler",
+            "server",
+            "api",
+        ],
+        url: `${DOCS_BASE_URL}/runtimes/functions`,
+        body: 'Functions runs a worker for your space: a default export with a `fetch` method, served from your space\'s own origin, so requests no file answers reach your code. Opt into a database with `"database": true`. Private beta — the team needs the flag.',
     },
     {
         slug: "collab",
@@ -495,10 +528,10 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         title: "sf access",
         kind: "cli",
         tier: "full",
-        summary: "Grant, ban, and inspect who can view a space.",
-        keywords: ["access", "grant", "ban", "password", "effective", "rules", "policy"],
+        summary: "Emergency visitor-session revocation.",
+        keywords: ["access", "sessions", "revoke", "logout"],
         url: `${DOCS_BASE_URL}/cli`,
-        body: "`sf access grant` / `sf access ban` edit access rules; `sf access effective` shows the resolved policy. Use `sf password set` for a shared password.",
+        body: "Use `sf access logout-all` to revoke every opened visitor session. Define audience-specific network restrictions on the corresponding Grant.",
     },
     {
         slug: "cli/teams",
@@ -599,7 +632,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         summary: "Create, list, and update spaces over HTTP.",
         keywords: ["api", "spaces", "space", "create", "list", "endpoint"],
         url: `${DOCS_BASE_URL}/api`,
-        body: "`GET /v1/spaces` lists spaces; `POST /v1/spaces` creates one. Responses carry the space id, slug, and live URL.",
+        body: "`GET /v1/spaces` lists spaces; `POST /v1/spaces` creates one. `PATCH /v1/spaces/{spaceId}` with a slug-only body renames the space and managed hostname. Former managed addresses temporarily 307 to the current hostname while immutable version URLs stay unchanged. Responses carry the space id, slug, and live URL.",
     },
     {
         slug: "api/versions",
@@ -661,78 +694,17 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         url: `${DOCS_BASE_URL}/platforms`,
         body: "The platform API is the tenant-facing surface for operating Spacefast as hosting infra. It shares the `{ data }` / `{ error }` envelope and is documented via OpenAPI.",
     },
-    // ----- Recipes ----------------------------------------------------------
-    {
-        slug: "recipes/github-deploys",
-        title: "Publish from GitHub",
-        kind: "recipe",
-        tier: "full",
-        summary: "Connect a repository so pushes publish automatically.",
-        keywords: ["github", "git", "ci", "push", "connect", "automatic", "recipe"],
-        url: `${DOCS_BASE_URL}/builds`,
-        body: "Connect a repository with `sf git connect`; each push builds on Spacefast and publishes a version, with pull requests getting preview URLs.",
-    },
-    {
-        slug: "recipes/preview-channels",
-        title: "Preview channels for pull requests",
-        kind: "recipe",
-        tier: "full",
-        summary: "Give every branch a shareable preview URL.",
-        keywords: ["preview", "channel", "branch", "pull request", "staging", "recipe"],
-        url: `${DOCS_BASE_URL}/builds`,
-        body: "Push a branch or open a pull request on a connected repository, or publish to a named channel, to get an isolated preview URL without touching production.",
-    },
-    {
-        slug: "recipes/agent-publish",
-        title: "Let an agent publish for you",
-        kind: "recipe",
-        tier: "full",
-        summary: "Drive a first publish from an AI agent, then claim it.",
-        keywords: ["agent", "ai", "mcp", "anonymous", "claim", "automation", "recipe"],
-        url: `${DOCS_BASE_URL}/anonymous-publish`,
-        body: "Let an agent publish anonymously for an instant URL and a claim token, then hand the token to a human who runs `sf spaces claim`.",
-    },
-    {
-        slug: "recipes/custom-domain",
-        title: "Add a custom domain",
-        kind: "recipe",
-        tier: "full",
-        summary: "Point your own domain at a space with automatic TLS.",
-        keywords: ["domain", "custom domain", "dns", "tls", "https", "recipe"],
-        url: "https://spacefast.com/help/domains",
-        body: "Add the domain with `sf domains add`, set the DNS records Spacefast prints, and wait for `sf domains check` to report a ready certificate.",
-    },
-    {
-        slug: "recipes/password-protect",
-        title: "Password-protect a space",
-        kind: "recipe",
-        tier: "full",
-        summary: "Put one shared password in front of a whole space.",
-        keywords: ["password", "protect", "private", "access", "gate", "recipe"],
-        url: "https://spacefast.com/help/access",
-        body: "Run `sf password set` to gate a space behind a single shared secret; clear it later with `sf password clear`.",
-    },
-    {
-        slug: "recipes/redirects",
-        title: "Set up redirects",
-        kind: "recipe",
-        tier: "reference",
-        summary: "Add redirect rules that ship and roll back with a version.",
-        keywords: ["redirect", "rewrite", "routing", "301", "recipe"],
-        url: "https://spacefast.com/help/redirects",
-        body: "Add redirect rules to a `_redirects` file at your publish root so they publish as part of the version and roll back with it.",
-    },
-    {
-        slug: "recipes/migrate-dns",
-        title: "Migrate DNS to a custom domain",
-        kind: "recipe",
-        tier: "reference",
-        summary: "Cut traffic over to a Spacefast-served domain safely.",
-        keywords: ["dns", "migrate", "cutover", "domain", "nameserver", "recipe"],
-        url: "https://spacefast.com/help/domains",
-        body: "Pre-stage the domain with `sf domains add`, verify the certificate is ready with `sf domains check`, then update DNS to flip traffic with zero downtime.",
-    },
 ];
+const SKILL_RECIPE_DOCS = SPACEFAST_RECIPE_SKILLS.map((skill) => ({
+    slug: skill.recipe.slug,
+    title: skill.title,
+    kind: "recipe",
+    tier: skill.recipe.tier,
+    summary: skill.description,
+    keywords: [...skill.keywords, "recipe", "skill"],
+    url: skill.recipe.url,
+    body: renderSpacefastSkill(skill, "local"),
+}));
 // ----- Error reference (generated) -----------------------------------------
 // One reference-tier catalog entry per ERROR_DOCS member, so `sf docs <code>`,
 // `GET /v1/docs?q=<code>`, and MCP search all resolve error codes in a single
@@ -752,5 +724,6 @@ function errorDocsCatalogEntries() {
 }
 export const DOCS_CATALOG = [
     ...HAND_WRITTEN_DOCS_CATALOG,
+    ...SKILL_RECIPE_DOCS,
     ...errorDocsCatalogEntries(),
 ];