@spacefast/common 0.0.24 → 0.0.26

package/dist/utils/static-runtime-policy.fixtures.json

@@ -1,44 +1,33 @@
 {
     "phpLike": [
-        { "path": "index.php", "expected": true },
-        { "path": "nested/app.phtml", "expected": true },
-        { "path": "lib.phar", "expected": true },
-        { "path": "legacy.php5", "expected": true },
-        { "path": "index.html", "expected": false },
-        { "path": "assets/main.js", "expected": false },
-        { "path": ".env", "expected": false }
-    ],
-    "immutable": [
-        { "path": "_next/static/chunks/main-app-4A_iFExJ.js", "expected": true },
-        { "path": "_next/static/chunks/framework-2c1d4f8a.js", "expected": true },
-        { "path": "_next/static/chunks/pages/index-a1b2c3d4e5f6.js", "expected": true },
-        { "path": "_next/static/chunks/oton0Guf.js", "expected": true },
-        { "path": "_next/static/css/app.plainname.css", "expected": true },
-        { "path": "/_next/static/chunks/oton0Guf.js", "expected": true },
-        { "path": "_app/immutable/entry/start.DYyuCeEr.js", "expected": true },
-        { "path": "_nuxt/index.oton0Guf.js", "expected": true },
-        { "path": "_astro/about.DYyuCeEr.css", "expected": true },
-        { "path": "_next/static/index.html", "expected": false },
-        { "path": "_next/static/sitemap.xml", "expected": false },
-        { "path": "_app/immutable/manifest.txt", "expected": false },
-        { "path": "_nextish/chunks/oton0Guf.js", "expected": false },
-        { "path": "nested/_next/static/chunks/oton0Guf.js", "expected": false },
-        { "path": "assets/index-BzeDGMM3.js", "expected": false },
-        { "path": "assets/auth-client-P1Tx-Cyu.js", "expected": false },
-        { "path": "assets/index-DYyuCeEr.js", "expected": false },
-        { "path": "assets/index-9f8e7d6c.js", "expected": false },
-        { "path": "assets/D3GeoMap.js", "expected": false },
-        { "path": "assets/index.js", "expected": false },
-        { "path": "assets/client-widget.js", "expected": false },
-        { "path": "app.1a2b3c4d.css", "expected": false },
-        { "path": "vendor.3f9a2b7e.js", "expected": false },
-        { "path": "static/js/main.d41d8cd98f00b204e9800998.js", "expected": false },
-        { "path": "index.html", "expected": false },
-        { "path": "robots.txt", "expected": false },
-        { "path": "config.xml", "expected": false },
-        { "path": "page.php", "expected": false },
-        { "path": "MyComponent.js", "expected": false },
-        { "path": "image01.png", "expected": false }
+        {
+            "path": "index.php",
+            "expected": true
+        },
+        {
+            "path": "nested/app.phtml",
+            "expected": true
+        },
+        {
+            "path": "lib.phar",
+            "expected": true
+        },
+        {
+            "path": "legacy.php5",
+            "expected": true
+        },
+        {
+            "path": "index.html",
+            "expected": false
+        },
+        {
+            "path": "assets/main.js",
+            "expected": false
+        },
+        {
+            "path": ".env",
+            "expected": false
+        }
     ],
     "safeContentType": [
         {
@@ -46,12 +35,20 @@
             "mime": "application/x-httpd-php",
             "expected": "text/plain; charset=utf-8"
         },
-        { "path": "lib.phar", "mime": "application/zip", "expected": "application/octet-stream" },
+        {
+            "path": "lib.phar",
+            "mime": "application/zip",
+            "expected": "application/octet-stream"
+        },
         {
             "path": "assets/main.js",
             "mime": "text/javascript; charset=utf-8",
             "expected": "text/javascript; charset=utf-8"
         },
-        { "path": "logo.svg", "mime": "image/svg+xml", "expected": "image/svg+xml" }
+        {
+            "path": "logo.svg",
+            "mime": "image/svg+xml",
+            "expected": "image/svg+xml"
+        }
     ]
 }

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

@@ -1,5 +1,5 @@
 // Single source of truth for static-runtime content policy: PHP-like inert
-// classification, immutable-asset detection, and safe content-type forcing.
+// classification and safe content-type forcing.
 //
 // This module is intentionally pure (no node:path, no I/O) so the exact same
 // rules can be mechanically code-generated into the PHP runtime (runtime
@@ -30,7 +30,7 @@ export const INTERNAL_REDIRECT_RESPONSE_HEADERS = [
     "x-reproxy-url",
     "x-sendfile",
 ];
-// Rejected/platform-managed response headers (internal-docs/platform.md "Routing And
+// Rejected/platform-managed response headers (the platform spec "Routing And
 // Headers"): user `_headers` rules can never set or remove these. The
 // internal-redirect/sendfile family above is spread in, so it stays a strict subset —
 // anything the proxy lane refuses to relay is also refused from `_headers`. The rest is
@@ -87,52 +87,27 @@ export function isPlatformManagedResponseHeader(name) {
     return (PLATFORM_MANAGED_RESPONSE_HEADER_SET.has(lower) ||
         PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES.some((prefix) => lower.startsWith(prefix)));
 }
-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);
-// Immutable caching is decided by DETERMINISTIC signals only — reserved framework
-// build directories below, plus user-declared `_headers` Cache-Control rules that
-// override the baked default at serve time. There is deliberately NO filename-entropy
-// heuristic: an 8-char base64url bundler hash is character-for-character
-// indistinguishable from a short human name (D3GeoMap, McKayCV2), so any guess either
-// pins a user's mutable file for a year (stale site nobody can fix — browsers have no
-// bust channel) or silently downgrades real hashes to revalidate-every-load, which
-// under the wp.cloud edge per-IP rate limiter turned dashboard page loads into 429
-// storms (2026-07-06). Unrecognized files default to the safe direction:
-// `max-age=0, must-revalidate` for browsers, long s-maxage + purge-on-publish at the
-// edge.
-//
-// 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. Deployments of bundler output declare those dirs immutable
-// themselves via a `_headers` rule (e.g. `/assets/*` → `Cache-Control: public,
-// max-age=31536000, immutable`), which the publisher — a build we ran, an agent, a CI
-// deploy — writes because it KNOWS the output is content-hashed.
-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;
+/**
+ * The token grammar a `_headers` rule accepts for a header NAME. The routing
+ * compiler enforces it; anything that GENERATES `_headers` rules (the Next
+ * materializer's framework sections) must gate on the same pattern, so a
+ * generated rule can never fail the author's publish.
+ */
+export const HEADER_RULE_NAME_PATTERN = /^[A-Za-z0-9-]+$/;
+/** `content-type` → `Content-Type`: the casing compiled rules and generated `_headers` carry. */
+export function canonicalHeaderName(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .split("-")
+        .map((part) => (part ? `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}` : part))
+        .join("-");
 }
+const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
+// Immutable-asset detection is NOT decided here: `compiled_cache_class` in
+// crates/stattic-runtime-core (responses.rs) is the one implementation, at
+// finalize. A TS re-implementation lived here once, drifted from the
+// enforcer, and was deleted rather than re-synced.
 function lastSegment(filePath) {
     const slash = filePath.lastIndexOf("/");
     return slash >= 0 ? filePath.slice(slash + 1) : filePath;
@@ -152,15 +127,6 @@ export function pathStem(filePath) {
 export function isPhpLikeStaticPath(filePath) {
     return PHP_LIKE_EXTENSION_SET.has(pathExtension(filePath));
 }
-export function isImmutableAssetPath(filePath) {
-    if (NON_IMMUTABLE_EXTENSION_SET.has(pathExtension(filePath))) {
-        return false;
-    }
-    // Path-convention layer: 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.
-    return isUnderGuaranteedImmutablePrefix(filePath);
-}
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
 export function runtimeFileSafety(filePath) {
     return {

package/dist/utils/upload-session.d.ts

@@ -33,8 +33,10 @@ export declare class UploadTargetError extends Error {
     readonly target: UploadTarget;
     readonly status: number;
     readonly serverError?: UploadTargetServerError | undefined;
-    constructor(target: UploadTarget, status: number, message: string, serverError?: UploadTargetServerError | undefined);
+    readonly retryAfterMs?: number | undefined;
+    constructor(target: UploadTarget, status: number, message: string, serverError?: UploadTargetServerError | undefined, retryAfterMs?: number | undefined);
 }
+export declare function uploadRetryAfterMs(value: string | null, now?: number): number | undefined;
 export declare function uploadPageHasRemainder(page: UploadSession): boolean;
 export declare const UPLOAD_STALLED_RESUME_MAX_ATTEMPTS = 3;
 export declare function uploadQueueAdvanced(before: UploadSession, after: UploadSession | null): boolean;
@@ -42,6 +44,7 @@ export declare function executeUploadSession(input: {
     session: UploadSession;
     targets?: readonly UploadTarget[] | undefined;
     concurrency?: number | undefined;
+    settleOnFailure?: boolean | undefined;
     fetch?: ((...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>) | undefined;
     prepareTarget?: ((target: UploadTarget) => Promise<UploadTargetBody> | UploadTargetBody) | undefined;
     onEvent?: ((event: UploadSessionEvent) => void) | undefined;

package/dist/utils/upload-session.js

@@ -2,14 +2,30 @@ export class UploadTargetError extends Error {
     target;
     status;
     serverError;
-    constructor(target, status, message, serverError) {
+    retryAfterMs;
+    constructor(target, status, message, serverError, retryAfterMs) {
         super(message);
         this.target = target;
         this.status = status;
         this.serverError = serverError;
+        this.retryAfterMs = retryAfterMs;
         this.name = "UploadTargetError";
     }
 }
+export function uploadRetryAfterMs(value, now = Date.now()) {
+    if (!value) {
+        return undefined;
+    }
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.ceil(seconds * 1000);
+    }
+    const date = Date.parse(value);
+    if (!Number.isFinite(date)) {
+        return undefined;
+    }
+    return Math.max(0, date - now);
+}
 function parseUploadTargetServerError(raw) {
     let parsed;
     try {
@@ -73,7 +89,7 @@ export function uploadQueueAdvanced(before, after) {
     }
     return after.targets.some((target, index) => target.path !== before.targets[index]?.path);
 }
-async function runConcurrent(items, concurrency, fn) {
+async function runConcurrent(items, concurrency, settleOnFailure, fn) {
     let nextIndex = 0;
     const runWorker = async () => {
         const item = items[nextIndex++];
@@ -83,7 +99,18 @@ async function runConcurrent(items, concurrency, fn) {
         await fn(item);
         return runWorker();
     };
-    await Promise.all(Array.from({ length: Math.min(Math.max(concurrency, 1), items.length || 1) }).map(() => runWorker()));
+    const workers = Array.from({
+        length: Math.min(Math.max(concurrency, 1), items.length || 1),
+    }).map(() => runWorker());
+    if (!settleOnFailure) {
+        await Promise.all(workers);
+        return;
+    }
+    const outcomes = await Promise.allSettled(workers);
+    const failed = outcomes.find((outcome) => outcome.status === "rejected");
+    if (failed) {
+        throw failed.reason;
+    }
 }
 export async function executeUploadSession(input) {
     const targets = input.targets ?? input.session.targets;
@@ -91,7 +118,8 @@ export async function executeUploadSession(input) {
         return;
     }
     const fetchImpl = input.fetch ?? fetch;
-    await runConcurrent(targets, input.concurrency ?? 4, async (target) => {
+    const settleOnFailure = input.settleOnFailure ?? false;
+    await runConcurrent(targets, input.concurrency ?? 4, settleOnFailure, async (target) => {
         input.onEvent?.({ type: "target-start", target });
         try {
             const prepared = input.prepareTarget
@@ -114,7 +142,7 @@ export async function executeUploadSession(input) {
                 const details = await response.text().catch(() => "");
                 const serverError = parseUploadTargetServerError(details);
                 const suffix = details.trim() ? `: ${details.trim().slice(0, 1_000)}` : "";
-                throw new UploadTargetError(target, response.status, `Upload failed for ${target.path} with ${response.status} ${response.statusText}${suffix}.`, serverError);
+                throw new UploadTargetError(target, response.status, `Upload failed for ${target.path} with ${response.status} ${response.statusText}${suffix}.`, serverError, uploadRetryAfterMs(response.headers.get("retry-after")));
             }
             input.onEvent?.({ type: "target-done", target });
         }

package/dist/utils/version-path.js

@@ -1,4 +1,4 @@
-// Canonical object-path form (internal-docs/platform.md "Upload Contract"):
+// Canonical object-path form (the platform spec "Upload Contract"):
 // UTF-8, Unicode NFC, percent-decoded exactly once. This canonical form is
 // what manifest paths, finalize's normalized paths, route-map keys, and dedup
 // keys all mean. The PHP runtime applies the same transform (rawurldecode once

package/dist/vocabulary.d.ts

@@ -104,8 +104,8 @@ export declare const CONCEPTS: {
         readonly id: "infra";
         readonly canonicalNoun: "infra";
         readonly aliases: readonly ["infrastructure"];
-        readonly externalTerms: readonly ["WP.Cloud"];
-        readonly deprecated: readonly ["code.storage", "Pierre"];
+        readonly externalTerms: readonly ["WP Cloud"];
+        readonly deprecated: readonly ["code.storage", "Pierre", "the hosting provider"];
         readonly description: string;
     };
 };
@@ -143,10 +143,10 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
     readonly replacement: "space";
     readonly reason: string;
 }, {
-    readonly term: "WP.Cloud";
+    readonly term: "WP Cloud";
     readonly concept: "infra";
-    readonly allowedContexts: readonly ["platform-api", "fixed-phrase"];
-    readonly allowedPhrases: readonly ["built on WP.Cloud"];
+    readonly allowedContexts: readonly ["fixed-phrase"];
+    readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"];
     readonly replacement: "infra";
     readonly reason: string;
 }];
@@ -208,10 +208,10 @@ export declare const PROVIDER_HYGIENE: {
         readonly reason: "The build sandbox vendor is never named; it is 'Spacefast Builds'.";
     };
     readonly wpcloud: {
-        readonly internalName: "WP.Cloud";
+        readonly internalName: "WP Cloud";
         readonly replacement: "infra";
-        readonly allowedContexts: readonly ["platform-api", "fixed-phrase"];
-        readonly allowedPhrases: readonly ["built on WP.Cloud"];
+        readonly allowedContexts: readonly ["fixed-phrase"];
+        readonly allowedPhrases: readonly ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"];
         readonly reason: string;
     };
     readonly codeStorage: {

package/dist/vocabulary.js

@@ -10,7 +10,7 @@
 //
 //   - `space` is the primitive noun everywhere, user surfaces and platform API
 //     alike. A space IS a site: there is no second host entity to name. `site`
-//     survives only as WP.Cloud's own word for the box, in operator surfaces
+//     survives only as WP Cloud's own word for the box, in operator surfaces
 //     and the warm-pool inventory.
 //   - `publish` is the verb. AMENDED 2026-07-02: `deploy` / `deployments` are
 //     first-class ALIASES of `publish` / `versions` (see DEPLOY_ALIASES) — they
@@ -22,10 +22,14 @@
 //   - `API key` — never "access token".
 //   - `Collab` is the feature; `comment` is the unit.
 //   - `Superpowers` is the page-enhancement feature.
-//   - Provider names never leak externally: never "E2B" (say "Spacefast
-//     Builds" / "Spacefast CI"), never "WP.Cloud" (say "infra", except the
-//     platform API or the fixed phrase "built on WP.Cloud"), never
-//     "code.storage" / "Pierre" (see PROVIDER_HYGIENE).
+//   - Provider names stay off public surfaces by default: never "E2B" (say
+//     "Spacefast Builds" / "Spacefast CI"), never "code.storage" / "Pierre".
+//     The infra brand is "WP Cloud" — never "WP.Cloud"/"wp-cloud" (AMENDED
+//     2026-08-13). Prefer "infra"; when an external reference is genuinely
+//     necessary (provider identity fields, domain conflicts), name WP Cloud
+//     outright — NEVER the euphemism "the hosting provider". Marketing may use
+//     the family line "the same infra as Automattic, WP Cloud, Pressable, and
+//     WordPress.com" (see PROVIDER_HYGIENE).
 export const CONCEPTS = {
     space: {
         id: "space",
@@ -102,10 +106,11 @@ export const CONCEPTS = {
         id: "infra",
         canonicalNoun: "infra",
         aliases: ["infrastructure"],
-        externalTerms: ["WP.Cloud"],
-        deprecated: ["code.storage", "Pierre"],
-        description: "The hosting substrate. Say 'infra' externally; 'WP.Cloud' only in the " +
-            "platform API or the phrase 'built on WP.Cloud'. Never 'code.storage'/'Pierre'.",
+        externalTerms: ["WP Cloud"],
+        deprecated: ["code.storage", "Pierre", "the hosting provider"],
+        description: "The hosting substrate. Prefer 'infra'; when an external reference is " +
+            "necessary, name 'WP Cloud' (its real spelling) — never the euphemism " +
+            "'the hosting provider'. Never 'code.storage'/'Pierre'.",
     },
 };
 export const EXTERNAL_TERM_ALLOWLIST = [
@@ -134,17 +139,21 @@ export const EXTERNAL_TERM_ALLOWLIST = [
         allowedContexts: ["operator"],
         replacement: "space",
         reason: "A space IS a site, so 'site' is no longer a Spacefast noun — it is only " +
-            "WP.Cloud's word for the box, which operator surfaces and warm-pool " +
+            "WP Cloud's word for the box, which operator surfaces and warm-pool " +
             "inventory may use. Every customer-facing surface says 'space'.",
     },
     {
-        term: "WP.Cloud",
+        term: "WP Cloud",
         concept: "infra",
-        allowedContexts: ["platform-api", "fixed-phrase"],
-        allowedPhrases: ["built on WP.Cloud"],
+        allowedContexts: ["fixed-phrase"],
+        allowedPhrases: ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"],
         replacement: "infra",
-        reason: "Only the platform API or the exact phrase 'built on WP.Cloud' may name " +
-            "the provider; general copy says 'infra'.",
+        reason: "AMENDED 2026-08-13: prefer 'infra'. Same day: the platform-api " +
+            "carve-out is revoked — API values say mysql/phpmyadmin/infra, never " +
+            "wpcloud. Name WP Cloud (its real spelling — never 'WP.Cloud') only " +
+            "where the external reference is necessary: domain-conflict copy and " +
+            "the marketing family line in allowedPhrases. Never the euphemism " +
+            "'the hosting provider'.",
     },
 ];
 export const DEPLOY_ALIASES = [
@@ -167,12 +176,14 @@ export const PROVIDER_HYGIENE = {
         reason: "The build sandbox vendor is never named; it is 'Spacefast Builds'.",
     },
     wpcloud: {
-        internalName: "WP.Cloud",
+        internalName: "WP Cloud",
         replacement: "infra",
-        allowedContexts: ["platform-api", "fixed-phrase"],
-        allowedPhrases: ["built on WP.Cloud"],
-        reason: "Hosting substrate; externally 'infra' except the platform API or the " +
-            "phrase 'built on WP.Cloud'.",
+        allowedContexts: ["fixed-phrase"],
+        allowedPhrases: ["the same infra as Automattic, WP Cloud, Pressable, and WordPress.com"],
+        reason: "Hosting substrate; prefer 'infra' (AMENDED 2026-08-13, same day: the " +
+            "platform-api carve-out is revoked — API values say mysql/phpmyadmin/" +
+            "infra, never wpcloud). Necessary external references name WP Cloud " +
+            "outright — never 'the hosting provider'.",
     },
     codeStorage: {
         internalName: "code.storage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -20,22 +20,6 @@
     "brand-assets",
     "dist"
   ],
-  "spacefastTestCache": {
-    "mode": "hermetic",
-    "inputs": [
-      "../../apps/www/dist/.well-known/agent-card.json",
-      "../../apps/www/dist/ai.txt",
-      "../../apps/www/dist/llms-full.txt",
-      "../../apps/www/dist/llms.txt",
-      "../cli/skill.template.md",
-      "../cli/skill.references.template.md",
-      "../cli/scripts/generate-skill.mjs",
-      "../../e2e-tests/fixtures/zero-all-features/api-finalize-request.json",
-      "../../e2e-tests/fixtures/zero-all-features/runtime-compiler-finalize-input.json",
-      "../../runtime/engine/shared/fonts",
-      "src/docs/agent-prose.ts"
-    ]
-  },
   "exports": {
     "./brand": {
       "types": "./dist/brand.d.ts",
@@ -116,6 +100,7 @@
     "culori": "^4.0.2",
     "js-yaml": "^4.1.1",
     "mime": "^4.1.0",
+    "oauth4webapi": "3.8.7",
     "parse5": "^7.3.0",
     "smol-toml": "^1.7.0",
     "zod": "^4.4.3"