@spacefast/common 0.0.5 → 0.0.7

package/dist/contracts/zero.d.ts

@@ -245,8 +245,8 @@ export declare const zeroRuntimePublicRealtimeModeSchema: z.ZodEnum<{
     "local-websocket": "local-websocket";
 }>;
 export declare const zeroInspectPolicySchema: z.ZodEnum<{
-    private: "private";
     public: "public";
+    private: "private";
 }>;
 export declare const zeroRuntimePublicAuthConfigSchema: z.ZodObject<{
     provider: z.ZodDefault<z.ZodLiteral<"wpcom">>;
@@ -256,7 +256,6 @@ export declare const zeroRuntimePublicAuthConfigSchema: z.ZodObject<{
     signOutUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     returnToParam: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
-export type ZeroRuntimePublicAuthConfig = z.infer<typeof zeroRuntimePublicAuthConfigSchema>;
 export declare const zeroRuntimePublicRealtimeConfigSchema: z.ZodObject<{
     mode: z.ZodEnum<{
         "stattic-central": "stattic-central";
@@ -275,7 +274,6 @@ export declare const zeroRuntimePublicRealtimeConfigSchema: z.ZodObject<{
     spaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     versionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
-export type ZeroRuntimePublicRealtimeConfig = z.infer<typeof zeroRuntimePublicRealtimeConfigSchema>;
 export declare const zeroRuntimeClientConfigSchema: z.ZodObject<{
     runtimeKind: z.ZodLiteral<"zero">;
     basePath: z.ZodOptional<z.ZodString>;
@@ -782,8 +780,8 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
     }, z.core.$strict>>;
     inspect: z.ZodDefault<z.ZodObject<{
         policy: z.ZodDefault<z.ZodEnum<{
-            private: "private";
             public: "public";
+            private: "private";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -1057,8 +1055,8 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
         }, z.core.$strict>>;
         inspect: z.ZodDefault<z.ZodObject<{
             policy: z.ZodDefault<z.ZodEnum<{
-                private: "private";
                 public: "public";
+                private: "private";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -1073,8 +1071,8 @@ export declare const zeroInspectResponseSchema: z.ZodObject<{
         serverRuntime: z.ZodLiteral<"quickjs-rust">;
         inspect: z.ZodObject<{
             policy: z.ZodEnum<{
-                private: "private";
                 public: "public";
+                private: "private";
             }>;
         }, z.core.$strict>;
         install: z.ZodObject<{
@@ -1156,8 +1154,8 @@ export declare const zeroInspectPublicResponseSchema: z.ZodObject<{
             serverRuntime: z.ZodLiteral<"quickjs-rust">;
             inspect: z.ZodObject<{
                 policy: z.ZodEnum<{
-                    private: "private";
                     public: "public";
+                    private: "private";
                 }>;
             }, z.core.$strict>;
             install: z.ZodObject<{
@@ -1372,7 +1370,6 @@ export declare const zeroDbDumpQuerySchema: z.ZodObject<{
     table: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
-export type ZeroDbDumpQuery = z.infer<typeof zeroDbDumpQuerySchema>;
 export declare const zeroDbDumpTableSchema: z.ZodObject<{
     name: z.ZodString;
     rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -1447,12 +1444,10 @@ export declare const zeroRealtimeEventIntakeResponseSchema: z.ZodObject<{
     delivered: z.ZodDefault<z.ZodNumber>;
     duplicate: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
-export type ZeroRealtimeEventIntakeResponse = z.infer<typeof zeroRealtimeEventIntakeResponseSchema>;
 export declare const zeroRealtimeEventListQuerySchema: z.ZodObject<{
     afterEventId: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
-export type ZeroRealtimeEventListQuery = z.infer<typeof zeroRealtimeEventListQuerySchema>;
 export declare const zeroRealtimeEventListResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
         eventId: z.ZodString;

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

@@ -1,9 +1,37 @@
-export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc", "*/.git/*", "*/.stattic/*", "*/.ssh/*", "*/.aws/*", "*/.kube/*", "*/.docker/*", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*"];
+export declare const ARCHIVE_SECRET_GLOBS: readonly [".env*", ".npmrc", ".netrc", "*/.git/*", "*/.spacefast/*", "*/.ssh/*", "*/.aws/*", "*/.kube/*", "*/.docker/*", "credentials.json", "*.pem", "*.key", "*.p12", "*.pfx", "*.crt", "*id_rsa*"];
 /**
  * The credential rules every surface must repeat. Treat tokens as secrets, keep
  * them out of logs and transcripts, and never echo them back.
  */
 export declare const SECRET_RULES_PROSE: string;
+export declare const POSITIONING_PROSE: string;
+export declare const EXPLAIN_TO_USER_PROSE: string;
+export declare const FAILURE_CONDUCT_PROSE: string;
+export declare const LANE_PICKER_PROSE: string;
+export declare const HOW_TO_RESEARCH_PROSE: string;
+export declare const ENV_NOTES_PROSE: string;
+/**
+ * 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 declare const CHECK_BEFORE_PUBLISH_PROSE: string;
+/**
+ * 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 declare const SAVE_STATE_PROSE: string;
+/**
+ * The UPDATE verb: a new version to the SAME space. Never re-run the
+ * first-publish recipe when saved state exists.
+ */
+export declare const UPDATE_SPACE_PROSE: string;
+/**
+ * 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 declare const CONTINUE_AFTER_CLAIM_PROSE: string;
 /**
  * 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
@@ -21,15 +49,27 @@ export declare const RECEIPT_SHAPE_PROSE: string;
  */
 export declare const SIGNED_UPLOAD_PROSE: string;
 /**
- * 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 declare const AGENT_PROSE: {
+    readonly positioning: string;
     readonly secretRules: string;
+    readonly explainToUser: string;
+    readonly failureConduct: string;
     readonly publishSequence: string;
     readonly receiptShape: string;
     readonly signedUpload: string;
+    readonly checkBeforePublish: string;
+    readonly saveState: string;
+    readonly updateSpace: string;
+    readonly continueAfterClaim: string;
+    readonly lanePicker: string;
+    readonly howToResearch: string;
+    readonly envNotes: string;
 };
 export type AgentProseKey = keyof typeof AGENT_PROSE;

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.d.ts

@@ -1,6 +1,57 @@
+import { type ConnectTargetId } from "../agents/connect-targets.js";
 export declare const agentSetupUrl: string;
 export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
+/**
+ * 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 declare const AGENT_HANDOFF_DECLINE_REASONS: readonly ["invalid_handoff", "expired", "already_redeemed", "revoked", "client_mismatch", "origin_mismatch"];
+export type AgentHandoffDeclineReason = (typeof AGENT_HANDOFF_DECLINE_REASONS)[number];
+export type AgentHandoffAction = Readonly<{
+    kind: "copy";
+    label: string;
+    sensitive: boolean;
+    value: string;
+}> | Readonly<{
+    kind: "open";
+    label: string;
+    href: string;
+}>;
+export type AgentHandoff = Readonly<{
+    actions: readonly AgentHandoffAction[];
+    documentUrl: string;
+    instructions: string;
+    prompt: string;
+}>;
+/**
+ * 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 declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): Readonly<{
+    documentId: string;
+    documentUrl: string;
+    secret: string;
+}>;
+/** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
+export declare function buildAgentHandoff(input: {
+    expectedOrigin: string;
+    mcpEndpoint: string;
+    targetId: ConnectTargetId;
+    url: string;
+}): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
 export declare function aiInstructionsText(): string;