@spacefast/common 0.0.11 → 0.0.13

package/dist/contracts/zero.js

@@ -1,8 +1,20 @@
 import { z } from "zod";
 import { dataEnvelope } from "./common.js";
+import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, executionCapabilitiesSchema, executionEnvNameSchema, executionIdentifierSchema, executionInspectPolicySchema, executionLogEntrySchema, executionLogListQuerySchema, executionLogListResponseSchema, executionSha256Schema, executionStaticFileSchema, httpMethodSchema, PLATFORM_ROUTE_PREFIX, } from "./execution.js";
+/**
+ * Spacefast Zero: capsules — schema, queries, mutations and endpoints that run
+ * together inside one parent-owned transaction — executed by the native runner
+ * on a dedicated wp.cloud site, against that site's own MySQL.
+ *
+ * The transaction is what makes this a separate product rather than a
+ * placement option for `./functions.js`. A capsule handler's semantics depend
+ * on the transaction wrapped around it, and an isolate reaching the database
+ * over a relay cannot offer one. See `endpointIsPortable` in `./execution.js`
+ * for the narrow surface both products can host.
+ */
 export const ZERO_SOURCE_METADATA_KEY = "statticZero";
 export const ZERO_RUNTIME_KIND = "zero";
-export const ZERO_PLATFORM_ROUTE_PREFIX = "/__spacefast/zero";
+export const ZERO_PLATFORM_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
 export const ZERO_CLIENT_ENTRY = "client/index.tsx";
 export const ZERO_SERVER_ENTRY = "server/index.ts";
 export const ZERO_RUNTIME_ROUTE_PATHS = {
@@ -18,7 +30,7 @@ export const ZERO_RUNTIME_ROUTE_PATHS = {
 export const ZERO_RUNTIME_STORAGE_ROOT = "__spacefast/zero";
 export const ZERO_RUNTIME_ARTIFACT_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/artifact.json`;
 export const ZERO_RUNTIME_CONFIG_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/config.json`;
-export const ZERO_RUNTIME_BINARY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/bin/stattic-zero-runner`;
+export const ZERO_RUNTIME_BINARY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/bin/stattic-runtime`;
 export const ZERO_RUNTIME_BINARY_COMPATIBILITY_TARGET = "wpcloud-linux-x86_64-gnu-v1";
 export const ZERO_RUNTIME_BUNDLE_ROOT = `${ZERO_RUNTIME_STORAGE_ROOT}/bundles`;
 export const ZERO_RUNTIME_CLIENT_BUNDLE_PATH = `${ZERO_RUNTIME_BUNDLE_ROOT}/client.js`;
@@ -27,68 +39,74 @@ export const ZERO_SOURCE_ENV_FILE = ".env.zero.server";
 export const ZERO_CONFIG_FILE = "zero.json";
 export const ZERO_DEPLOY_FILE = ".zero/deploy.json";
 export const ZERO_RUNTIME_BUNDLE_MAX_BYTES = 786_432;
-export const ZERO_ENV_MAX_KEYS = 64;
-export const ZERO_ENV_NAME_MAX_BYTES = 128;
-export const ZERO_ENV_VALUE_MAX_BYTES = 16 * 1024;
-export const ZERO_ENV_TOTAL_VALUE_MAX_BYTES = 64 * 1024;
-export const ZERO_ENV_RESERVED_PREFIXES = ["SPACEFAST_", "ZERO_"];
 export const ZERO_MANAGED_TABLE_COLUMNS = ["id", "createdAt", "updatedAt"];
+/**
+ * Paths the Zero app shell itself answers, on top of the platform-reserved set
+ * in `./execution.js`. A capsule cannot claim these because its own client
+ * router and auth flow already do.
+ */
 export const ZERO_RESERVED_APP_ROUTE_PATHS = [
     "/",
     "/index.html",
     "/client.js",
     "/auth/callback",
-    "/__spacefast",
-    "/__span",
 ];
-export const ZERO_RESERVED_APP_ROUTE_PREFIXES = ["/auth/", "/__spacefast/", "/__span/"];
-export const zeroRuntimeKindSchema = z.enum(["static", "zero", "php", "node", "workers"]);
-const zeroNameSchema = z
-    .string()
-    .min(1)
-    .max(128)
-    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
-const zeroEnvNameSchema = z
-    .string()
-    .min(1)
-    .max(ZERO_ENV_NAME_MAX_BYTES)
-    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
-    .refine((name) => !ZERO_ENV_RESERVED_PREFIXES.some((prefix) => name.toUpperCase().startsWith(prefix)), { message: "Zero env variable name uses a reserved prefix." });
-const zeroRoutePathSchema = z
-    .string()
-    .min(1)
-    .max(2048)
-    .startsWith("/")
-    .refine((path) => !path.startsWith("//") && !path.includes("\\") && !path.includes("?") && !path.includes("#"), {
-    message: "Zero capsule routes must be absolute app paths without //, \\, ?, or #.",
-})
-    .refine((path) => !ZERO_RESERVED_APP_ROUTE_PATHS.some((reservedPath) => path === reservedPath), {
-    message: "Zero capsule route is reserved by the Zero app shell.",
-})
-    .refine((path) => !ZERO_RESERVED_APP_ROUTE_PREFIXES.some((reservedPrefix) => path.startsWith(reservedPrefix)), {
-    message: "Zero capsule route prefix is reserved by the Zero app shell.",
-})
-    .refine((path) => !path.startsWith(ZERO_PLATFORM_ROUTE_PREFIX), {
-    message: `Zero capsule routes cannot use ${ZERO_PLATFORM_ROUTE_PREFIX}.`,
-})
-    .refine((path) => path !== "/__stattic" && !path.startsWith("/__stattic/"), {
-    message: "Zero capsule routes cannot use Spacefast private control paths.",
+export const ZERO_RESERVED_APP_ROUTE_PREFIXES = ["/auth/"];
+const zeroNameSchema = executionIdentifierSchema;
+const zeroRoutePathSchema = appRoutePathSchema({
+    subject: "Zero capsule routes",
+    reservedPaths: ZERO_RESERVED_APP_ROUTE_PATHS,
+    reservedPrefixes: ZERO_RESERVED_APP_ROUTE_PREFIXES,
 });
-export const zeroHttpMethodSchema = z.enum([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "OPTIONS",
-]);
 export const zeroEndpointSchema = z
     .object({
-    method: zeroHttpMethodSchema,
+    method: httpMethodSchema,
     path: zeroRoutePathSchema,
 })
     .strict();
+function zeroEndpointRouteMatchShape(path) {
+    const segments = [];
+    let score = 0;
+    let splat = false;
+    for (const segment of path.replace(/^\/+|\/+$/g, "").split("/")) {
+        if (!segment)
+            continue;
+        if (segment === ":splat") {
+            score += 1;
+            splat = true;
+            break;
+        }
+        if (segment.startsWith(":")) {
+            segments.push(null);
+            score += 2;
+        }
+        else {
+            segments.push(segment);
+            score += 10;
+        }
+    }
+    return { score, segments, splat };
+}
+export function zeroEndpointRoutesAmbiguous(left, right) {
+    const methodsOverlap = left.method === right.method ||
+        (left.method === "GET" && right.method === "HEAD") ||
+        (left.method === "HEAD" && right.method === "GET");
+    if (!methodsOverlap)
+        return false;
+    const leftShape = zeroEndpointRouteMatchShape(left.path);
+    const rightShape = zeroEndpointRouteMatchShape(right.path);
+    if (leftShape.score !== rightShape.score)
+        return false;
+    if (!leftShape.splat && leftShape.segments.length < rightShape.segments.length)
+        return false;
+    if (!rightShape.splat && rightShape.segments.length < leftShape.segments.length)
+        return false;
+    return Array.from({ length: Math.min(leftShape.segments.length, rightShape.segments.length) }, (_, index) => index).every((index) => {
+        const segment = leftShape.segments[index];
+        const other = rightShape.segments[index];
+        return segment === null || other === null || segment === other;
+    });
+}
 function zeroDefaultMatchesColumnType(column, ctx) {
     if (!Object.prototype.hasOwnProperty.call(column, "default") || column.default === null) {
         return;
@@ -139,65 +157,44 @@ export const zeroTableSchema = z
 })
     .strict();
 export const zeroDatabaseSchema = z.record(z.string(), zeroTableSchema);
-const zeroSha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
-const zeroBase64Schema = z
-    .string()
-    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/);
-export const zeroRuntimeBundleSchema = z
+const zeroSha256Schema = executionSha256Schema;
+/**
+ * Zero's bundles travel inline in the finalize payload — a capsule's compiled
+ * client and server fit comfortably under the ceiling, and inlining keeps the
+ * whole version one atomic write. Functions bundles do the opposite and land
+ * in the content store first; see `functionsBundleRefSchema`.
+ */
+export const zeroRuntimeBundleSchema = executionBundleSchema({
+    bundleRoot: ZERO_RUNTIME_BUNDLE_ROOT,
+    maxBytes: ZERO_RUNTIME_BUNDLE_MAX_BYTES,
+});
+export const zeroRuntimeStaticFileSchema = executionStaticFileSchema({
+    storageRoot: ZERO_RUNTIME_STORAGE_ROOT,
+    maxBytes: ZERO_RUNTIME_BUNDLE_MAX_BYTES,
+});
+export const zeroRuntimeRunSourceSchema = z
     .object({
-    path: z
+    runId: z.string().min(1).max(256),
+    source: z
         .string()
         .min(1)
-        .startsWith(`${ZERO_RUNTIME_BUNDLE_ROOT}/`)
-        .refine((bundlePath) => !bundlePath.split("/").includes(".."), {
-        message: "Zero bundle paths cannot traverse outside the runtime bundle root.",
-    }),
-    sha256: zeroSha256Schema,
-    size: z.number().int().nonnegative().max(ZERO_RUNTIME_BUNDLE_MAX_BYTES),
-    contentBase64: zeroBase64Schema,
-})
-    .strict();
-const zeroPublicStaticPathSchema = z
-    .string()
-    .min(1)
-    .max(2048)
-    .refine((path) => !path.startsWith("/") && !path.split("/").includes(".."), {
-    message: "Zero static file paths must be relative and cannot traverse.",
-})
-    .refine((path) => !path.startsWith(ZERO_RUNTIME_STORAGE_ROOT + "/"), {
-    message: `Zero static files cannot use ${ZERO_RUNTIME_STORAGE_ROOT}.`,
-})
-    .refine((path) => !path.startsWith("_") && !path.startsWith("."), {
-    message: "Zero static file paths cannot use private root prefixes.",
-});
-export const zeroRuntimeStaticFileSchema = z
-    .object({
-    path: zeroPublicStaticPathSchema,
-    contentType: z.string().min(1).max(255),
-    sha256: zeroSha256Schema,
-    size: z.number().int().nonnegative().max(ZERO_RUNTIME_BUNDLE_MAX_BYTES),
-    contentBase64: zeroBase64Schema,
+        .max(2 * 1024 * 1024),
+    schemaHash: z.string().min(1).max(256).optional(),
+    capabilities: executionCapabilitiesSchema,
+    db: z.record(z.string(), z.unknown()).optional(),
 })
     .strict();
-export const zeroRuntimeRunSourceSchema = z
+export const zeroRuntimeEndpointSourceSchema = z
     .object({
-    runId: z.string().min(1).max(256),
+    method: httpMethodSchema,
+    path: zeroRoutePathSchema,
+    endpointId: z.string().min(1).max(256),
     source: z
         .string()
         .min(1)
         .max(2 * 1024 * 1024),
     schemaHash: z.string().min(1).max(256).optional(),
-    capabilities: z
-        .object({
-        db: z.boolean().default(false),
-        fetch: z.boolean().default(false),
-        auth: z.boolean().default(false),
-        env: z.boolean().default(false),
-        realtime: z.boolean().default(false),
-        logging: z.boolean().default(false),
-    })
-        .partial()
-        .default({}),
+    capabilities: zeroRuntimeRunSourceSchema.shape.capabilities,
     db: z.record(z.string(), z.unknown()).optional(),
 })
     .strict();
@@ -273,7 +270,7 @@ const zeroRuntimePublicRealtimeCanonicalModeSchema = z.enum([
 ]);
 export const zeroRealtimeModeSchema = zeroRealtimeCanonicalModeSchema;
 export const zeroRuntimePublicRealtimeModeSchema = zeroRuntimePublicRealtimeCanonicalModeSchema;
-export const zeroInspectPolicySchema = z.enum(["private", "public"]);
+export const zeroInspectPolicySchema = executionInspectPolicySchema;
 const zeroRuntimePublicPathSchema = z.string().min(1).startsWith("/");
 const zeroHttpUrlSchema = z
     .string()
@@ -398,7 +395,7 @@ export const zeroSourceManifestSchema = z
     env: z
         .object({
         file: z.literal(ZERO_SOURCE_ENV_FILE),
-        names: z.array(zeroEnvNameSchema).max(ZERO_ENV_MAX_KEYS).default([]),
+        names: z.array(executionEnvNameSchema).max(EXECUTION_ENV_MAX_KEYS).default([]),
     })
         .nullable()
         .default(null),
@@ -470,6 +467,7 @@ export const zeroRuntimeFinalizePayloadSchema = z
     artifact: zeroCapsuleArtifactSchema,
     bundles: z.array(zeroRuntimeBundleSchema).max(8).default([]),
     staticFiles: z.array(zeroRuntimeStaticFileSchema).max(16).default([]),
+    endpointSources: z.array(zeroRuntimeEndpointSourceSchema).max(128).default([]),
     runSources: z.array(zeroRuntimeRunSourceSchema).max(128).default([]),
     migrations: zeroMigrationPlanSchema.nullable().default(null),
     variables: z
@@ -519,44 +517,61 @@ export const zeroRuntimeFinalizePayloadSchema = z
         .default({ policy: "private" }),
 })
     .strict();
+export const zeroRuntimeConfigSchema = zeroRuntimeFinalizePayloadSchema
+    .pick({
+    runtimeKind: true,
+    install: true,
+    artifact: true,
+    migrations: true,
+    variables: true,
+    realtime: true,
+    auth: true,
+    inspect: true,
+})
+    .extend({
+    variableValues: z.record(z.string(), z.string()).default({}),
+})
+    .strict();
 export const zeroDeployMetadataSchema = z
     .object({
     artifactId: z.string().min(1).optional(),
     finalize: zeroRuntimeFinalizePayloadSchema,
 })
     .strict();
-export const zeroInspectResponseSchema = z
+/**
+ * What a live Zero capsule is, as the `app` member of a space's runtime status.
+ *
+ * There is no `versionId` here: this only ever describes the version the status
+ * response already names as live, and repeating it would invite the two to
+ * disagree. `artifactId` stays because it identifies the built capsule rather
+ * than the publish that carries it.
+ */
+export const zeroAppSchema = z
     .object({
-    versionId: z.string().min(1).nullable(),
-    artifactId: z.string().min(1).nullable(),
-    data: z
+    runtimeKind: z.literal(ZERO_RUNTIME_KIND),
+    artifactId: z.string().min(1),
+    appName: z.string().min(1),
+    serverRuntime: z.literal("quickjs-rust"),
+    inspect: z
         .object({
-        runtimeKind: z.literal(ZERO_RUNTIME_KIND),
-        appName: z.string().min(1),
-        serverRuntime: z.literal("quickjs-rust"),
-        inspect: z
-            .object({
-            policy: zeroInspectPolicySchema,
-        })
-            .strict(),
-        install: zeroRuntimeInstallProfileSchema,
-        tables: z.array(z.string()).default([]),
-        queries: z.array(z.string()).default([]),
-        mutations: z.array(z.string()).default([]),
-        endpoints: z.array(zeroEndpointSchema).default([]),
-        sockets: z.array(z.string()).default([]),
-        variables: z
-            .object({
-            source: z.literal("stattic-variables"),
-            names: z.array(z.string()).default([]),
-        })
-            .strict(),
-        realtime: zeroRuntimePublicRealtimeConfigSchema,
+        policy: zeroInspectPolicySchema,
     })
-        .nullable(),
+        .strict(),
+    install: zeroRuntimeInstallProfileSchema,
+    tables: z.array(z.string()).default([]),
+    queries: z.array(z.string()).default([]),
+    mutations: z.array(z.string()).default([]),
+    endpoints: z.array(zeroEndpointSchema).default([]),
+    sockets: z.array(z.string()).default([]),
+    variables: z
+        .object({
+        source: z.literal("stattic-variables"),
+        names: z.array(z.string()).default([]),
+    })
+        .strict(),
+    realtime: zeroRuntimePublicRealtimeConfigSchema,
 })
     .strict();
-export const zeroInspectPublicResponseSchema = dataEnvelope(zeroInspectResponseSchema);
 export const zeroDbInspectResponseSchema = z
     .object({
     versionId: z.string().min(1).nullable(),
@@ -590,36 +605,11 @@ export const zeroDbDumpResponseSchema = z
 })
     .strict();
 export const zeroDbDumpPublicResponseSchema = dataEnvelope(zeroDbDumpResponseSchema);
-export const zeroLogListQuerySchema = z
-    .object({
-    limit: z.coerce.number().int().min(1).max(100).default(50),
-    cursor: z.string().min(1).optional(),
-    requestId: z.string().min(1).optional(),
-    mutationName: z.string().min(1).optional(),
-})
-    .strict();
-export const zeroLogEntrySchema = z
-    .object({
-    id: z.string().min(1),
-    timestamp: z.string().datetime(),
-    level: z.enum(["debug", "info", "warn", "error"]),
-    requestId: z.string().min(1).nullable(),
-    versionId: z.string().min(1).nullable(),
-    mutationName: z.string().min(1).nullable(),
-    message: z.string(),
-    metadata: z.record(z.string(), z.unknown()).default({}),
-})
-    .strict();
-export const zeroLogListResponseSchema = z
-    .object({
-    data: z.array(zeroLogEntrySchema),
-    pagination: z
-        .object({
-        nextCursor: z.string().nullable(),
-    })
-        .strict(),
-})
-    .strict();
+// Both products emit the same log shape; `handlerName` carries the mutation
+// name here and the worker handler name on Functions.
+export const zeroLogListQuerySchema = executionLogListQuerySchema;
+export const zeroLogEntrySchema = executionLogEntrySchema;
+export const zeroLogListResponseSchema = executionLogListResponseSchema;
 export const zeroRealtimeEventIntakeResponseSchema = z
     .object({
     accepted: z.literal(true),
@@ -735,6 +725,7 @@ export function createZeroRuntimeFinalizePayload(input) {
         artifact,
         bundles: input.bundles ?? [],
         staticFiles: input.staticFiles ?? [],
+        endpointSources: input.endpointSources ?? [],
         runSources: input.runSources ?? [],
         migrations: input.migrations ?? null,
         variables: {

package/dist/dashboard-paths/index.d.ts

@@ -4,7 +4,7 @@
  * Append-only: add a new top-level static dashboard route's first segment here
  * before its route module lands. A repository structural test enforces this.
  */
-export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "account", "agent", "claim", "device", "drop", "new-team", "oauth", "sign-in", "start", "terminal", "two-factor"];
+export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "account", "access", "agent", "claim", "device", "drop", "new-team", "oauth", "sign-in", "start", "terminal", "two-factor"];
 /**
  * Dashboard route first-segments that cannot be used as space slugs.
  *
@@ -17,8 +17,8 @@ export type TeamSlugRouteReservation = (typeof TEAM_SLUG_ROUTE_RESERVATIONS)[num
 export type SpaceSlugRouteReservation = (typeof SPACE_SLUG_ROUTE_RESERVATIONS)[number];
 export declare const TEAM_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
 export declare const SPACE_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
-export type SpaceSettingsDestination = "access" | "advanced" | "appearance" | "builds" | "integrations" | "integrations/add" | "source-builds";
-export type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "developer/service-tokens" | "developer/webhooks" | "integrations";
+export type SpaceSettingsDestination = "access" | "advanced" | "builds" | "integrations" | "integrations/add" | "source-builds";
+export type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "developer/webhooks" | "integrations";
 export declare function teamPath(teamSlug: string): string;
 export declare function spacePath(teamSlug: string, spaceSlug: string): string;
 export declare function versionDetailPath(teamSlug: string, spaceSlug: string, versionRef: string): string;

package/dist/dashboard-paths/index.js

@@ -8,6 +8,7 @@ export const TEAM_SLUG_ROUTE_RESERVATIONS = [
     "accept-beta-invite",
     "accept-invitation",
     "account",
+    "access",
     // Not a TanStack route module: /agent* is the edge-served handoff-document
     // surface (apps/my/public/_redirects + vite middleware, #417). Those rewrite
     // rules deliberately swallow every /agent-prefixed path, so a team named

package/dist/docs/agent-prose.js

@@ -79,9 +79,9 @@ export const POSITIONING_PROSE = [
     "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.",
+    "Report the bare Live URL, repeatable expiring private Open URL, immutable Version URL, and Claim link",
+    "as separate actions. 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.",
@@ -181,7 +181,7 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "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).",
+    "to create an API key in the dashboard (Account → API keys).",
 ].join("\n");
 /**
  * The zero-install publish sequence: one curl for a file, a secret-preflighted
@@ -216,10 +216,12 @@ export const RECEIPT_SHAPE_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
-    "- `data.version.immutableUrl` — the permanent, frozen version URL; share it for reviews.",
-    "  It is reserved in the initial receipt. If the publish is still finalizing, poll `data.links.status`",
-    "  with the claim token until the status is `ready`.",
-    "- `data.shareBlurb` — a paste-ready one-liner with the URL and claim nudge; relay it verbatim when present.",
+    "- `data.open.url` and `data.open.expiresAt` — a repeatable private author Link until expiry, claim, or revocation.",
+    "  It is not a stable URL or recipient Link; clients must not persist it as Space state.",
+    "- `data.version.immutableUrl` — the permanent address of the frozen Version. The bare URL",
+    "  carries no authority: use the receipt's Open URL for the author's browser or create a scoped",
+    "  Link for a recipient. It is reserved in the initial receipt. If the publish is still",
+    "  finalizing, poll `data.links.status` with the claim token until the status is `ready`.",
     "- `data.upload` — signed upload instructions for manifest publishes when file bytes were not sent",
     "  with the request. Send each `data.upload.targets[]` instruction exactly as returned, treat",
     "  authorization headers and upload tokens as secrets, then finalize.",

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

@@ -31,10 +31,12 @@ export type AgentHandoff = Readonly<{
 }>;
 /**
  * The single shared grammar for handoff links:
- * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `<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.
+ * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
+ * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
+ * second host allowlist that would reject legitimate dev or container origins.
  * 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.
@@ -48,13 +50,13 @@ export declare function parseAgentHandoffUrl(value: string, expectedOrigin: stri
 }>;
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
-export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.";
+export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
 /** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
 export declare const AGENT_HANDOFF_FETCH_SAFETY = "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.";
 export declare const AGENT_HANDOFF_FRAGMENT_HYGIENE = "Keep its fragment out of commands, request URLs, logs, and replies.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
 export declare const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "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.";
+export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Open URL; create a scoped Link when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */

package/dist/docs/agent-setup.js

@@ -47,10 +47,12 @@ function isSafeHttpUrl(url) {
 }
 /**
  * The single shared grammar for handoff links:
- * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `<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.
+ * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
+ * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
+ * second host allowlist that would reject legitimate dev or container origins.
  * 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.
@@ -58,13 +60,17 @@ function isSafeHttpUrl(url) {
  * grammar can never fork.
  */
 export function parseAgentHandoffUrl(value, expectedOrigin) {
-    let canonicalExpectedOrigin;
+    let expectedUrl;
     try {
-        canonicalExpectedOrigin = new URL(expectedOrigin).origin;
+        expectedUrl = new URL(expectedOrigin);
     }
     catch {
         throw new TypeError("Agent handoff expectedOrigin must be a valid URL origin.");
     }
+    if (expectedUrl.protocol !== "https:" && expectedUrl.protocol !== "http:") {
+        throw new TypeError("Agent handoff expectedOrigin must be an HTTP(S) origin.");
+    }
+    const canonicalExpectedOrigin = expectedUrl.origin;
     let url;
     try {
         url = new URL(value);
@@ -74,14 +80,15 @@ export function parseAgentHandoffUrl(value, expectedOrigin) {
     }
     const documentId = /^\/agent\/([^/]+)$/.exec(url.pathname)?.[1];
     const secret = url.hash.slice(1);
-    if (!isSafeHttpUrl(url) ||
-        url.origin !== canonicalExpectedOrigin ||
+    if (url.origin !== canonicalExpectedOrigin ||
+        url.username !== "" ||
+        url.password !== "" ||
         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).");
+        throw new TypeError("Agent handoff URL must be an /agent/<id> URL on the app origin with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query.");
     }
     return { documentId, documentUrl: `${url.origin}${url.pathname}`, secret };
 }
@@ -105,13 +112,13 @@ function validateMcpEndpoint(value) {
  */
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export const AGENT_HANDOFF_CLI_TARGET_IDS = ["claude-code", "codex"];
-export const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.";
+export const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
 /** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
 export const AGENT_HANDOFF_FETCH_SAFETY = "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.";
 export const AGENT_HANDOFF_FRAGMENT_HYGIENE = "Keep its fragment out of commands, request URLs, logs, and replies.";
 export const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE = `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.`;
 export const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export const AGENT_HANDOFF_PUBLISH_PROSE = "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.";
+export const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Open URL; create a scoped Link when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export function agentHandoffConnectSections(target) {
     const setupSections = [target.primary, target.config].flatMap((setup) => setup ? [[setup.label, `\`\`\`${setup.language}`, setup.value, "```"].join("\n")] : []);
@@ -243,7 +250,7 @@ export function aiInstructionsText() {
         "## Install the CLI (On-Device files, updates, versions, rollback, and the rest)",
         "",
         "The CLI is the full surface: incremental publishes, version history, rollback,",
-        "passwords, domains, logs, and diagnostics. Install it when the user will keep",
+        "sharing, domains, logs, and diagnostics. Install it when the user will keep",
         "working on the space:",
         "",
         "```bash",
@@ -282,8 +289,10 @@ export function aiInstructionsText() {
         "```",
         "",
         "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
+        "`teams:create` for creating teams,",
         "`spaces:read` for status, versions, diffs, and logs, `spaces:write` for claim/create/update,",
-        "`publish:write` for publish and rollback, and `domains:read`/`domains:write` for domain",
+        "`spaces:rename` for slug and managed-address renames, `publish:write` for publish and rollback,",
+        "and `domains:read`/`domains:write` for domain",
         "inventory, DNS diagnostics, assignment, verification, and mutation. Hosted MCP does not read",
         "local paths; its workspace tools operate on a durable virtual workspace attached to the MCP",
         "session.",
@@ -321,8 +330,10 @@ export function aiInstructionsText() {
         "",
         "## 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",
+        "- Report the bare Live URL, the immutable Version URL when ready, the private Open URL, and",
+        "  — for anonymous spaces — the claim link with its expiry. Bare Live and Version URLs carry",
+        "  no authority for a private Space; create a scoped Link when a recipient needs access.",
+        "  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 `.spacefast/state.json`.",
         "",
@@ -334,7 +345,7 @@ export function aiInstructionsText() {
         "",
         "- `_redirects` — redirects, rewrites, SPA fallbacks, custom 404 rules, and external",
         "  `200` proxy rules.",
-        "- `_headers` — response headers and Basic Auth rules.",
+        "- `_headers` — supported response headers.",
         "- `404.html` — custom not-found page.",
         "- `sf.jsonc` — serving config (index, fallback, listing, meta) and the optional",
         "  `space` link. JSON Schema: https://spacefast.com/schemas/sf.json",
@@ -342,8 +353,7 @@ export function aiInstructionsText() {
         "  agent-readable too.",
         "- Plan limits surface as diagnostics, not failures you should guess at: publish the",
         "  intended artifact, then read and report what the CLI or API says. When a feature",
-        '  is plan-gated, say: "Not available on Free. Available on Personal and Work." For',
-        "  simple gated access, `sf password set` needs no plan and no `_headers` rule.",
+        '  is plan-gated, say: "Not available on Free. Available on Personal and Work."',
         "",
         "## Agent-aware routing",
         "",

package/dist/docs/agent-solutions.js

@@ -22,7 +22,7 @@ function hostedMcpText(label, guideUrl) {
         "Transport: Streamable HTTP",
         "Resource: https://mcp.spacefast.com",
         "Minimum scope: mcp:tools",
-        "Common scopes: teams:read spaces:read spaces:write publish:write domains:read domains:write",
+        "Common scopes: teams:read teams:create spaces:read spaces:write spaces:rename publish:write domains:read domains:write",
         "",
         "Hosted MCP is for cloud/browser agents. It does not read local paths; use the hosted workspace tools or signed uploads for artifacts.",
         `Guide: ${guideUrl}`,