@spacefast/common 0.0.23 → 0.0.26

package/dist/utils/structured-error.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_CODES } from "../contracts/cli.js";
+export class StructuredError extends Error {
+    code;
+    details;
+    exitCode;
+    type;
+    constructor(input) {
+        super(input.message);
+        this.name = "StructuredError";
+        this.code = input.code;
+        this.details = input.details;
+        this.exitCode = input.exitCode ?? CLI_EXIT_CODES.validation;
+        this.type = input.type;
+    }
+}
+export function structuredValidationError(message, details) {
+    return new StructuredError({
+        code: "validation_error",
+        message,
+        ...(details ? { details } : {}),
+    });
+}

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,14 +1,22 @@
-// 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
 // + Normalizer::normalize) at upload and serve time.
+// oxlint-disable-next-line no-control-regex -- matching control characters is the point: they are never part of a servable path.
 const CONTROL_CHARS_PATTERN = /[\u0000-\u001f\u007f]/;
 // Structural normalization shared by lookups and intake: forward slashes,
-// no leading slashes, no empty/"."/".." segments. Idempotent; safe to apply
-// to already-canonical stored paths (NFC is idempotent, no percent-decoding).
+// no leading slashes, no control characters, no empty/"."/".." segments.
+// Idempotent; safe to apply to already-canonical stored paths (NFC is
+// idempotent, no percent-decoding).
 export function normalizeVersionPath(input) {
     const normalized = input.replace(/\\/g, "/").replace(/^\/+/, "").normalize("NFC");
+    // Here rather than only in canonicalizeVersionPath: publish-policy's
+    // staticUploadPathViolation validates with this function, so a control
+    // character in an uploaded path used to pass the policy unclassified.
+    if (CONTROL_CHARS_PATTERN.test(normalized)) {
+        throw new Error(`invalid_version_path:${input}`);
+    }
     const segments = [];
     for (const segment of normalized.split("/")) {
         if (!segment || segment === ".") {
@@ -41,7 +49,8 @@ export function canonicalizeVersionPath(input) {
     const canonical = decoded.normalize("NFC");
     // Backslashes as separators are denied at intake (spec "Static path
     // policy"); only client-side helpers translate Windows separators.
-    if (CONTROL_CHARS_PATTERN.test(canonical) || canonical.includes("\\")) {
+    // Control characters are rejected by normalizeVersionPath below.
+    if (canonical.includes("\\")) {
         throw new Error(`invalid_version_path:${input}`);
     }
     return normalizeVersionPath(canonical);

package/dist/vocabulary.d.ts

@@ -7,6 +7,8 @@ export type TermContext =
 "platform-api"
 /** The GitHub integration vocabulary (push deploys, deployment status). */
  | "github-integration"
+/** Internal operator surfaces (superadmin, ops scripts, fleet inventory). */
+ | "operator"
 /** A fixed marketing phrase, spelled out verbatim in `allowedPhrases`. */
  | "fixed-phrase";
 /** A single canonical product concept and the words allowed to express it. */
@@ -38,8 +40,8 @@ export declare const CONCEPTS: {
         readonly id: "space";
         readonly canonicalNoun: "space";
         readonly aliases: readonly [];
-        readonly externalTerms: readonly ["site"];
-        readonly deprecated: readonly ["project"];
+        readonly externalTerms: readonly [];
+        readonly deprecated: readonly ["project", "site"];
         readonly description: string;
     };
     readonly publish: {
@@ -102,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;
     };
 };
@@ -137,14 +139,14 @@ export declare const EXTERNAL_TERM_ALLOWLIST: readonly [{
 }, {
     readonly term: "site";
     readonly concept: "space";
-    readonly allowedContexts: readonly ["platform-api"];
+    readonly allowedContexts: readonly ["operator"];
     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;
 }];
@@ -206,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

@@ -8,9 +8,10 @@
 // It is additive — wiring consumers (CLI, MCP, dashboard, docs generators) onto
 // it happens in later chunks. The decisions encoded here are LOCKED:
 //
-//   - `space` is the primitive noun on every user surface. `site` survives only
-//     as the platform-API term for the shared-pool host a space is placed on
-//     (see contracts/sites.ts, internal-docs/platform.md "Site").
+//   - `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
+//     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
 //     stay listed and documented, always with the sanctioned disambiguation
@@ -21,19 +22,24 @@
 //   - `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",
         canonicalNoun: "space",
         aliases: [],
-        externalTerms: ["site"],
-        deprecated: ["project"],
-        description: "The primitive noun everywhere a user works. 'Site' is the platform-API " +
-            "term for the shared host a space lands on; 'project' is never the primitive.",
+        externalTerms: [],
+        deprecated: ["project", "site"],
+        description: "The primitive noun everywhere, user surfaces and platform API alike. A " +
+            "space IS a site, so 'site' names nothing of ours; 'project' is never " +
+            "the primitive.",
     },
     publish: {
         id: "publish",
@@ -100,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 = [
@@ -129,19 +136,24 @@ export const EXTERNAL_TERM_ALLOWLIST = [
     {
         term: "site",
         concept: "space",
-        allowedContexts: ["platform-api"],
+        allowedContexts: ["operator"],
         replacement: "space",
-        reason: "'Site' is the platform-API host primitive (shared pool capacity); user " +
-            "surfaces always say '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 " +
+            "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 = [
@@ -164,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.23",
+  "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",
-      "../../apps/www/public/skill-references.md",
-      "../../apps/www/public/skill.md",
-      "../../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",
-      "../cli/SKILL.md",
-      "../cli/references.md"
-    ]
-  },
   "exports": {
     "./brand": {
       "types": "./dist/brand.d.ts",
@@ -75,6 +59,11 @@
       "import": "./dist/utils/*.js",
       "default": "./dist/utils/*.js"
     },
+    "./test-helpers/*": {
+      "types": "./dist/test-helpers/*.d.ts",
+      "import": "./dist/test-helpers/*.js",
+      "default": "./dist/test-helpers/*.js"
+    },
     "./slug-policy": {
       "types": "./dist/slug-policy/index.d.ts",
       "import": "./dist/slug-policy/index.js",
@@ -111,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"

package/dist/config/postgres-budget.d.ts

@@ -1,129 +0,0 @@
-import { z } from "zod";
-declare const postgresConnectionBudgetSchema: z.ZodObject<{
-    server: z.ZodObject<{
-        maxConnections: z.ZodNumber;
-        superuserReservedConnections: z.ZodNumber;
-    }, z.core.$strip>;
-    migrationConnections: z.ZodNumber;
-    operationalReserveConnections: z.ZodNumber;
-    transactionPools: z.ZodRecord<z.ZodString, z.ZodObject<{
-        serverConnections: z.ZodNumber;
-    }, z.core.$strip>>;
-    services: z.ZodObject<{
-        api: z.ZodObject<{
-            enabledInProduction: z.ZodBoolean;
-            replicas: z.ZodNumber;
-            poolConnectionsPerReplica: z.ZodNumber;
-            fixedConnectionsPerReplica: z.ZodNumber;
-            maxPinnedTransactionsPerReplica: z.ZodNumber;
-            rolloutOverlapReplicas: z.ZodNumber;
-            connectionBudget: z.ZodString;
-        }, z.core.$strip>;
-        worker: z.ZodObject<{
-            enabledInProduction: z.ZodBoolean;
-            replicas: z.ZodNumber;
-            poolConnectionsPerReplica: z.ZodNumber;
-            fixedConnectionsPerReplica: z.ZodNumber;
-            maxPinnedTransactionsPerReplica: z.ZodNumber;
-            rolloutOverlapReplicas: z.ZodNumber;
-            connectionBudget: z.ZodString;
-        }, z.core.$strip>;
-        cast: z.ZodObject<{
-            enabledInProduction: z.ZodBoolean;
-            replicas: z.ZodNumber;
-            poolConnectionsPerReplica: z.ZodNumber;
-            fixedConnectionsPerReplica: z.ZodNumber;
-            maxPinnedTransactionsPerReplica: z.ZodNumber;
-            rolloutOverlapReplicas: z.ZodNumber;
-            connectionBudget: z.ZodString;
-        }, z.core.$strip>;
-        scanWorker: z.ZodObject<{
-            enabledInProduction: z.ZodBoolean;
-            replicas: z.ZodNumber;
-            poolConnectionsPerReplica: z.ZodNumber;
-            fixedConnectionsPerReplica: z.ZodNumber;
-            maxPinnedTransactionsPerReplica: z.ZodNumber;
-            rolloutOverlapReplicas: z.ZodNumber;
-            connectionBudget: z.ZodString;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export type PostgresConnectionBudget = z.infer<typeof postgresConnectionBudgetSchema>;
-export type PostgresBudgetService = keyof PostgresConnectionBudget["services"];
-export type PostgresConnectionBudgetSummary = {
-    usableServerConnections: number;
-    directSteadyConnections: number;
-    transactionPoolConnections: number;
-    transactionPoolPinnedConnections: number;
-    transactionPoolQueryHeadroom: number;
-    steadyConnections: number;
-    rollingDeploySurgeConnections: number;
-    migrationConnections: number;
-    operationalReserveConnections: number;
-    plannedConnections: number;
-    unallocatedConnections: number;
-};
-export declare const POSTGRES_CONNECTION_BUDGET: {
-    server: {
-        maxConnections: number;
-        superuserReservedConnections: number;
-    };
-    migrationConnections: number;
-    operationalReserveConnections: number;
-    transactionPools: Record<string, {
-        serverConnections: number;
-    }>;
-    services: {
-        api: {
-            enabledInProduction: boolean;
-            replicas: number;
-            poolConnectionsPerReplica: number;
-            fixedConnectionsPerReplica: number;
-            maxPinnedTransactionsPerReplica: number;
-            rolloutOverlapReplicas: number;
-            connectionBudget: string;
-        };
-        worker: {
-            enabledInProduction: boolean;
-            replicas: number;
-            poolConnectionsPerReplica: number;
-            fixedConnectionsPerReplica: number;
-            maxPinnedTransactionsPerReplica: number;
-            rolloutOverlapReplicas: number;
-            connectionBudget: string;
-        };
-        cast: {
-            enabledInProduction: boolean;
-            replicas: number;
-            poolConnectionsPerReplica: number;
-            fixedConnectionsPerReplica: number;
-            maxPinnedTransactionsPerReplica: number;
-            rolloutOverlapReplicas: number;
-            connectionBudget: string;
-        };
-        scanWorker: {
-            enabledInProduction: boolean;
-            replicas: number;
-            poolConnectionsPerReplica: number;
-            fixedConnectionsPerReplica: number;
-            maxPinnedTransactionsPerReplica: number;
-            rolloutOverlapReplicas: number;
-            connectionBudget: string;
-        };
-    };
-};
-export declare function calculatePostgresConnectionBudget(plan: PostgresConnectionBudget, server?: {
-    maxConnections: number;
-    superuserReservedConnections: number;
-}): PostgresConnectionBudgetSummary;
-export declare function assertPostgresServiceConnectionUrl(service: PostgresBudgetService, rawUrl: string, options?: {
-    allowDirectDevelopmentConnection?: boolean;
-}): void;
-export declare function assertPostgresServicePoolBudget(service: PostgresBudgetService, configuredPoolConnections: number): void;
-export declare function assertPostgresServiceNamedLockBudget(service: PostgresBudgetService, configuredNamedLockTransactions: number): void;
-export declare function assertPostgresServerBudget(server: {
-    maxConnections: number;
-    superuserReservedConnections: number;
-}): PostgresConnectionBudgetSummary;
-export declare const POSTGRES_CONNECTION_BUDGET_SUMMARY: PostgresConnectionBudgetSummary;
-export {};