@spacefast/common 0.0.2 → 0.0.5

package/dist/contracts/zero.d.ts

@@ -183,9 +183,9 @@ export type ZeroMigrationOperation = z.infer<typeof zeroMigrationOperationSchema
 export declare const zeroMigrationPlanSchema: z.ZodObject<{
     format: z.ZodLiteral<"stattic.zero.migrations.v1">;
     mode: z.ZodDefault<z.ZodEnum<{
+        safe: "safe";
         drop: "drop";
         rename: "rename";
-        safe: "safe";
     }>>;
     schemaHash: z.ZodString;
     operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -480,8 +480,8 @@ export declare const zeroCapsuleArtifactSchema: z.ZodObject<{
     }, z.core.$strict>;
     limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        blob: "blob";
         ai: "ai";
+        blob: "blob";
         "generalized-js": "generalized-js";
     }>>>;
     sourceManifest: z.ZodObject<{
@@ -641,8 +641,8 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
         }, z.core.$strict>;
         limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            blob: "blob";
             ai: "ai";
+            blob: "blob";
             "generalized-js": "generalized-js";
         }>>>;
         sourceManifest: z.ZodObject<{
@@ -705,9 +705,9 @@ export declare const zeroRuntimeFinalizePayloadSchema: z.ZodObject<{
     migrations: z.ZodDefault<z.ZodNullable<z.ZodObject<{
         format: z.ZodLiteral<"stattic.zero.migrations.v1">;
         mode: z.ZodDefault<z.ZodEnum<{
+            safe: "safe";
             drop: "drop";
             rename: "rename";
-            safe: "safe";
         }>>;
         schemaHash: z.ZodString;
         operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -916,8 +916,8 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
             }, z.core.$strict>;
             limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             futureCapabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-                blob: "blob";
                 ai: "ai";
+                blob: "blob";
                 "generalized-js": "generalized-js";
             }>>>;
             sourceManifest: z.ZodObject<{
@@ -980,9 +980,9 @@ export declare const zeroDeployMetadataSchema: z.ZodObject<{
         migrations: z.ZodDefault<z.ZodNullable<z.ZodObject<{
             format: z.ZodLiteral<"stattic.zero.migrations.v1">;
             mode: z.ZodDefault<z.ZodEnum<{
+                safe: "safe";
                 drop: "drop";
                 rename: "rename";
-                safe: "safe";
             }>>;
             schemaHash: z.ZodString;
             operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1234,9 +1234,9 @@ export declare const zeroDbInspectResponseSchema: z.ZodObject<{
     artifactId: z.ZodNullable<z.ZodString>;
     backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
     migrationMode: z.ZodNullable<z.ZodEnum<{
+        safe: "safe";
         drop: "drop";
         rename: "rename";
-        safe: "safe";
     }>>;
     schemaHash: z.ZodNullable<z.ZodString>;
     tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1304,9 +1304,9 @@ export declare const zeroDbInspectPublicResponseSchema: z.ZodObject<{
         artifactId: z.ZodNullable<z.ZodString>;
         backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
         migrationMode: z.ZodNullable<z.ZodEnum<{
+            safe: "safe";
             drop: "drop";
             rename: "rename";
-            safe: "safe";
         }>>;
         schemaHash: z.ZodNullable<z.ZodString>;
         tables: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/docs/agent-prose.js

@@ -91,16 +91,20 @@ 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 when available; share it for reviews.",
+    "- `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.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.",
     "- `data.claim.url` and `data.claim.expiresAt` — the space is anonymous and expires unless claimed;",
     "  always show the user the claim link and the deadline so the space becomes theirs.",
-    "- `data.claim.token` — a secret capability. Save it only when needed to update the space later, send it as",
-    "  `Authorization: Bearer <claim-token>` with the same `spaceId`, and never print it back to the user.",
-    "- `data.links.inspect`, `resume`, `finalize`, and `promote` — follow-up API paths.",
+    "- `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`.",
+    "  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.",
     "",
     "If no files changed, the API may omit `upload`; report the receipt and diagnostics rather than",

package/dist/docs/agent-setup.js

@@ -120,8 +120,9 @@ export function aiInstructionsText() {
         "",
         "## After publishing",
         "",
-        "- Share the live URL, the immutable version URL, and — for anonymous spaces — the",
-        "  claim link with its expiry.",
+        "- 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`.",
         "",
         "## Space conventions",

package/dist/docs/error-docs.js

@@ -483,6 +483,10 @@ export const ERROR_DOCS = {
         summary: "The claim token is invalid or does not match this space.",
         fix: "Use the exact claim URL returned by the publish that created the space.",
     },
+    invalid_continuation_token: {
+        summary: "The continuation token is invalid, expired, or already finished.",
+        fix: "Restart the originating flow to obtain a fresh requiresAction envelope and continuation token.",
+    },
     invalid_data_location: {
         summary: "The requested data location is not a supported region.",
         fix: "Pick a region from the documented data locations, or use auto.",
@@ -571,6 +575,14 @@ export const ERROR_DOCS = {
         summary: "An invitation for this email already exists on the team.",
         fix: "Resend the existing invitation instead of creating a new one.",
     },
+    invitation_email_mismatch: {
+        summary: "This invitation was addressed to a different email than the accepting user.",
+        fix: "Sign in as the invited email, or ask an admin to invite your current address.",
+    },
+    invitation_expired: {
+        summary: "The invitation has expired and can no longer be accepted.",
+        fix: "Ask a team admin to send a fresh invitation, then accept the new one.",
+    },
     invitation_not_pending: {
         summary: "The invitation is no longer pending.",
         fix: "Create a new invitation if the member still needs to join.",
@@ -808,8 +820,8 @@ export const ERROR_DOCS = {
         fix: "Refresh the runtime JWKS; the signing keys may have rotated.",
     },
     runtime_logs_unavailable: {
-        summary: "Runtime logs are not available for this space right now.",
-        fix: "Retry shortly; logs may lag behind serving.",
+        summary: "Server logs are not available because Spacefast serves your space as static files.",
+        fix: "There is no running server process to log. Use the request logs in your dashboard to inspect recent traffic.",
     },
     runtime_management_unavailable: {
         summary: "The runtime management surface is unavailable for this site.",
@@ -1548,8 +1560,8 @@ export const ERROR_DOCS = {
         fix: "Use the existing shared site.",
     },
     wp_cloud_webhook_secret_not_configured: {
-        summary: "The WP.Cloud webhook secret is not configured on this deployment.",
-        fix: "Set the WP.Cloud webhook secret in the control-plane environment.",
+        summary: "The infra webhook secret is not configured on this deployment.",
+        fix: "Set the infra webhook secret in the control-plane environment.",
     },
 };
 const PRODUCT = BRAND.productName;

package/dist/utils/query-keys.d.ts

@@ -21,7 +21,7 @@ export declare const qk: {
     teamDomains: (id: string) => readonly ["teams", string, "domains"];
     teamManagedDomains: (id: string) => readonly ["teams", string, "managed-domains"];
     domainBindings: () => readonly ["domain-bindings"];
-    slugAvailability: (kind: "team" | "space", slug: string, teamId?: string, currentSlug?: string) => readonly ["slugs", "availability", "team" | "space", string, string, string];
+    slugAvailability: (kind: "team" | "space", slug: string, teamId?: string, currentSlug?: string) => readonly ["slugs", "availability", "space" | "team", string, string, string];
     teamVariables: (id: string) => readonly ["teams", string, "variables"];
     teamActivity: (id: string, limit: number) => readonly ["teams", string, "activity", number];
     space: (id: string) => readonly ["spaces", string];
@@ -63,7 +63,7 @@ export declare const qk: {
     spaceZeroRealtimeEvents: (id: string, limit: number) => readonly ["spaces", string, "zero", "realtime", "events", number];
     spaceVariables: (id: string) => readonly ["spaces", string, "variables"];
     spaceCertificates: (id: string) => readonly ["spaces", string, "runtime", "certificates"];
-    spaceLogs: (id: string, kind: "build" | "access" | "runtime") => readonly ["spaces", string, "logs", "build" | "access" | "runtime"];
+    spaceLogs: (id: string, kind: "build" | "access" | "runtime") => readonly ["spaces", string, "logs", "build" | "runtime" | "access"];
     spaceAnalytics: (id: string, window: string) => readonly ["spaces", string, "analytics", string];
     domain: (teamId: string, ref: string) => readonly ["teams", string, "domains", string];
     domainDiagnostics: (teamId: string, domainId: string) => readonly ["teams", string, "domains", string, "diagnostics"];

package/dist/utils/static-runtime-policy.d.ts

@@ -1,11 +1,32 @@
 export declare const PHP_LIKE_EXTENSIONS: string[];
 export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: string[];
 export declare const NON_IMMUTABLE_EXTENSIONS: string[];
+export declare const GUARANTEED_IMMUTABLE_PREFIXES: string[];
 /** Lowercased extension without the leading dot, posix semantics. Dotfiles have no extension. */
 export declare function pathExtension(filePath: string): string;
 /** Basename without its extension (the "stem"), posix semantics. */
 export declare function pathStem(filePath: string): string;
 export declare function isPhpLikeStaticPath(filePath: string): boolean;
+/**
+ * Classifies a candidate hash token — the final `.`/`-`-delimited tail of a
+ * filename stem (see isImmutableAssetPath) — as a real bundler content hash.
+ *
+ * Immutable caching is a one-year pin, so the test is asymmetric on purpose: a
+ * missed hash costs a cheap 304 revalidation, a false positive serves stale
+ * content for a year. When a token is ambiguous we say no. The discriminator is
+ * NOT character case — modern bundlers emit BOTH lowercase-hex and mixed-case
+ * base64url hashes — it is entropy plus the absence of dictionary-word shape.
+ *
+ * IRREDUCIBLE LIMIT: an 8-char base64url token is the same size as a short
+ * CamelCase-with-version-digit human name, and every default Vite/Rollup hash we
+ * must accept carries only one digit (BzeDGMM3, 4A_iFExJ). So a token like
+ * `D3GeoMap`, `McKayCV2`, or `v2-WebGL` is character-for-character indistinguishable
+ * from a real hash and is accepted by clause B. No filename-only rule can separate
+ * these without also rejecting the bundler hashes the spec mandates. The durable
+ * fix is to gate immutable caching on path convention (Vite `assets/`, Next
+ * `_next/static/`, SvelteKit `_app/immutable/`, …) rather than guessing from the
+ * stem; this heuristic is the best-effort fallback when that context is absent.
+ */
 export declare function looksLikeBundlerFingerprint(segment: string): boolean;
 export declare function isImmutableAssetPath(filePath: string): boolean;
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */

package/dist/utils/static-runtime-policy.js

@@ -46,7 +46,50 @@ export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
 export const NON_IMMUTABLE_EXTENSIONS = ["html", "htm", "php", "txt", "xml"];
 const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
 const NON_IMMUTABLE_EXTENSION_SET = new Set(NON_IMMUTABLE_EXTENSIONS);
-const FINGERPRINTED_ASSET_SEGMENT = /^[A-Za-z0-9_-]{8,}$/;
+// Two real bundler content-hash shapes. (A) lowercase hex (git/webpack short
+// SHAs, many tools): >=7 chars of [0-9a-f]. (B) base64url (Vite/Rollup/esbuild/
+// Next): >=8 chars of [A-Za-z0-9_-]. Both forms are recognized; the entropy
+// guards in looksLikeBundlerFingerprint are what keep human names out.
+const HEX_FINGERPRINT = /^[0-9a-f]{7,}$/;
+const BASE64URL_FINGERPRINT = /^[A-Za-z0-9_-]{8,}$/;
+// Durable path-convention layer over the filename-entropy heuristic
+// (looksLikeBundlerFingerprint). These are reserved build-output directories that the
+// framework OWNS and fills exclusively with content-addressed ([contenthash]) output by
+// construction — so every asset served from under them is safe to pin immutable for a
+// year regardless of how its individual filename reads. This recovers the real hashes the
+// filename heuristic conservatively MISSES (no-digit / single-case base64url draws like
+// `oton0Guf`, `DYyuCeEr`) without loosening the heuristic itself.
+//
+// Each prefix is HIGH-CONFIDENCE guaranteed-hashed:
+//   - `_next/static/`   Next.js immutable build assets (chunks/css/media), all
+//                       [contenthash]; Next itself serves this dir with `immutable`.
+//   - `_app/immutable/` SvelteKit (Vite) — the directory is literally named `immutable`
+//                       and holds only fingerprinted chunks/assets.
+//   - `_nuxt/`          Nuxt build dir — Vite-hashed client bundle, served from a
+//                       reserved app-owned path.
+//   - `_astro/`         Astro bundled assets — all content-hashed.
+//
+// DELIBERATELY EXCLUDED: generic user-writable dirs (Vite's `assets/`, CRA/Gatsby's
+// `static/`). Users drop NON-hashed files there, so widening to them would create
+// year-long false positives. Those stay gated by the filename heuristic only. This layer
+// is purely ADDITIVE: it can only turn a heuristic-`false` into `true` for assets under a
+// guaranteed-hashed dir; it never flips a `true` to `false`.
+export const GUARANTEED_IMMUTABLE_PREFIXES = [
+    "_next/static/",
+    "_app/immutable/",
+    "_nuxt/",
+    "_astro/",
+];
+/** True when the path lives under a framework dir where every emitted asset is content-hashed. */
+function isUnderGuaranteedImmutablePrefix(filePath) {
+    const normalized = filePath.startsWith("/") ? filePath.slice(1) : filePath;
+    for (const prefix of GUARANTEED_IMMUTABLE_PREFIXES) {
+        if (normalized.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
 function lastSegment(filePath) {
     const slash = filePath.lastIndexOf("/");
     return slash >= 0 ? filePath.slice(slash + 1) : filePath;
@@ -66,14 +109,87 @@ export function pathStem(filePath) {
 export function isPhpLikeStaticPath(filePath) {
     return PHP_LIKE_EXTENSION_SET.has(pathExtension(filePath));
 }
+/**
+ * Classifies a candidate hash token — the final `.`/`-`-delimited tail of a
+ * filename stem (see isImmutableAssetPath) — as a real bundler content hash.
+ *
+ * Immutable caching is a one-year pin, so the test is asymmetric on purpose: a
+ * missed hash costs a cheap 304 revalidation, a false positive serves stale
+ * content for a year. When a token is ambiguous we say no. The discriminator is
+ * NOT character case — modern bundlers emit BOTH lowercase-hex and mixed-case
+ * base64url hashes — it is entropy plus the absence of dictionary-word shape.
+ *
+ * IRREDUCIBLE LIMIT: an 8-char base64url token is the same size as a short
+ * CamelCase-with-version-digit human name, and every default Vite/Rollup hash we
+ * must accept carries only one digit (BzeDGMM3, 4A_iFExJ). So a token like
+ * `D3GeoMap`, `McKayCV2`, or `v2-WebGL` is character-for-character indistinguishable
+ * from a real hash and is accepted by clause B. No filename-only rule can separate
+ * these without also rejecting the bundler hashes the spec mandates. The durable
+ * fix is to gate immutable caching on path convention (Vite `assets/`, Next
+ * `_next/static/`, SvelteKit `_app/immutable/`, …) rather than guessing from the
+ * stem; this heuristic is the best-effort fallback when that context is absent.
+ */
 export function looksLikeBundlerFingerprint(segment) {
-    return (FINGERPRINTED_ASSET_SEGMENT.test(segment) &&
-        (/\d/.test(segment) || /_/.test(segment) || (/[a-z]/.test(segment) && /[A-Z]/.test(segment))));
+    // (A) Lowercase-hex hash (git short-SHA, webpack/Vite/Gatsby `[contenthash]`):
+    // a1b2c3d, 3f9a2b7e, d41d8cd98f00b204e980. Always require >=1 hex letter and
+    // >=1 digit so all-letter words (deadbeef) and digit-only runs (1234567) are out.
+    if (HEX_FINGERPRINT.test(segment) && /[a-f]/.test(segment) && /[0-9]/.test(segment)) {
+        // A long all-hex token is unambiguous: no human authors a 16+ char hex name, so
+        // length alone is entropy proof and the anti-word guards would only lose real
+        // hashes (most 16/20-char contenthashes contain an incidental 4-run).
+        if (segment.length >= 16) {
+            return true;
+        }
+        // Short hex (7-15) overlaps with hex-spelled words/years/colors, so require >=2
+        // digits and forbid a run of 4+ hex letters (deadbeef, cafe, face, decade) or
+        // 4+ digits (2024, 1234) — low-entropy human false positives.
+        if ((segment.match(/[0-9]/g) ?? []).length >= 2 &&
+            !/[a-f]{4}/.test(segment) &&
+            !/[0-9]{4}/.test(segment)) {
+            return true;
+        }
+    }
+    // (B) Base64url hash (Vite/Rollup/esbuild/Next): BzeDGMM3, 4A_iFExJ, P1Tx-Cyu,
+    // Z-cBR0Xb, 9-ygPMte. Random base64url draws — but immutable is a one-year pin, so
+    // against the human names that mimic this shape (acronym data/UI names, version
+    // and fiscal labels, dates, resolutions) we demand the full BALANCED-entropy
+    // signature of a real hash, and accept the safe cost of missing the minority of
+    // genuine hashes that fall short (a cheap 304):
+    //   - >=2 lowercase AND >=2 uppercase letters. Real base64url hashes carry several
+    //     of each; acronym-dominant human names (USMap-AKHIORWA, Map-USA_CA_TX,
+    //     MyCSS2DUI) have at most one lowercase token and are rejected here. This also
+    //     conservatively drops single-case and no-/one-lowercase hashes (DYyuCeEr,
+    //     ChJ_j-JJ) — the safe miss direction.
+    //   - at least one digit. ~1/4 of base64url hashes lack one and become cheap 304s,
+    //     but requiring it removes the all-letter acronym names that are otherwise
+    //     indistinguishable from a hash (USMap-AKHIORWA has no digit).
+    //   - no run of 3+ lowercase letters: a dictionary-word body (MyComponent
+    //     "omponent", LoginOAuth2 "ogin", HTTPClient2 "lient"). A packed hash breaks
+    //     lowercase up with caps/digits.
+    //   - no run of 2+ digits: clustered digits are human years/resolutions/sequences/
+    //     dates (2024, 1080, Win10, 01); a hash scatters single digits between letters.
+    // <8 chars (Widget2, API2, v2) never qualifies via the regex length floor.
+    if (BASE64URL_FINGERPRINT.test(segment) &&
+        (segment.match(/[a-z]/g) ?? []).length >= 2 &&
+        (segment.match(/[A-Z]/g) ?? []).length >= 2 &&
+        /[0-9]/.test(segment) &&
+        !/[a-z]{3}/.test(segment) &&
+        !/[0-9]{2}/.test(segment)) {
+        return true;
+    }
+    return false;
 }
 export function isImmutableAssetPath(filePath) {
     if (NON_IMMUTABLE_EXTENSION_SET.has(pathExtension(filePath))) {
         return false;
     }
+    // Path-convention layer (additive): anything under a guaranteed-content-hashed
+    // framework build dir is immutable regardless of filename. The extension gate above
+    // still applies, so an `index.html` accidentally under `_next/static/` is never pinned.
+    if (isUnderGuaranteedImmutablePrefix(filePath)) {
+        return true;
+    }
+    // Fallback for assets OUTSIDE those dirs: the filename-entropy heuristic.
     const stem = pathStem(filePath);
     for (let index = 0; index < stem.length; index += 1) {
         if (index > 0 && stem[index - 1] !== "." && stem[index - 1] !== "-") {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.2",
+  "version": "0.0.5",
+  "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "type": "module",
   "publishConfig": {