@spacefast/common 0.0.23 → 0.0.24

package/dist/utils/space-config.js

@@ -1,5 +1,5 @@
 import { CONFIG_PUBLIC_GRANT_SOURCE_REFERENCE, grantSchema, } from "../contracts/grants.js";
-import { SPACE_CONFIG_CAPS, SPACE_CONFIG_CANONICAL_FILE, SPACE_CONFIG_PRIVATE_FILES, spaceConfigFileSchema, spaceConfigSchema, } from "../contracts/space-config.js";
+import { SPACE_CONFIG_CAPS, SPACE_CONFIG_CANONICAL_FILE, } from "../contracts/space-config.js";
 const TEXT_BYTES = new TextEncoder();
 export const CONFIG_PUBLIC_GRANT_COMPILED_ID = "config:access.public";
 function byteLength(value) {
@@ -107,6 +107,7 @@ function capIssues(candidate) {
             ["title", SPACE_CONFIG_CAPS.metaTitleChars],
             ["description", SPACE_CONFIG_CAPS.metaDescriptionChars],
             ["image", SPACE_CONFIG_CAPS.metaImageChars],
+            ["favicon", SPACE_CONFIG_CAPS.metaImageChars],
         ];
         for (const [key, limit] of caps) {
             const value = meta[key];
@@ -123,75 +124,6 @@ function capIssues(candidate) {
     }
     return issues;
 }
-// File-only keys (`name`, `runtime`) never reach the API overlay, so their
-// checks live beside the shared caps rather than inside them. Both run BEFORE
-// zod so a bad declaration reports its stable code instead of a shape error.
-const RUNTIME_KINDS = new Set(["zero", "functions"]);
-function fileOnlyIssues(candidate) {
-    const issues = [];
-    const name = candidate.name;
-    if (typeof name === "string" && name.trim().length > SPACE_CONFIG_CAPS.nameChars) {
-        issues.push({
-            severity: "error",
-            code: "config_name_too_long",
-            message: `name supports up to ${SPACE_CONFIG_CAPS.nameChars} characters.`,
-            path: "name",
-            details: { length: name.trim().length, limit: SPACE_CONFIG_CAPS.nameChars },
-        });
-    }
-    const runtime = candidate.runtime;
-    if (runtime === undefined) {
-        return issues;
-    }
-    if (typeof runtime !== "object" || runtime === null || Array.isArray(runtime)) {
-        issues.push({
-            severity: "error",
-            code: "config_runtime_invalid_kind",
-            message: 'runtime must be an object declaring a kind of "zero" or "functions".',
-            path: "runtime",
-        });
-        return issues;
-    }
-    const declaration = runtime;
-    const kind = declaration.kind;
-    if (typeof kind !== "string" || !RUNTIME_KINDS.has(kind)) {
-        issues.push({
-            severity: "error",
-            code: "config_runtime_invalid_kind",
-            message: 'runtime.kind must be "zero" or "functions".',
-            path: "runtime.kind",
-            ...(typeof kind === "string" ? { details: { kind } } : {}),
-        });
-        return issues;
-    }
-    if (kind === "zero") {
-        // Zero is never inferred, so a declaration that names neither entry has
-        // nothing to compile — failing here beats publishing static files under a
-        // config that promised a database app.
-        for (const key of ["server", "client"]) {
-            const value = declaration[key];
-            if (typeof value !== "string" || value.trim().length === 0) {
-                issues.push({
-                    severity: "error",
-                    code: "config_runtime_entry_missing",
-                    message: `runtime.${key} is required and must name a module when runtime.kind is "zero".`,
-                    path: `runtime.${key}`,
-                });
-            }
-        }
-        return issues;
-    }
-    const entry = declaration.entry;
-    if (entry !== undefined && (typeof entry !== "string" || entry.trim().length === 0)) {
-        issues.push({
-            severity: "error",
-            code: "config_runtime_entry_missing",
-            message: "runtime.entry must name a module when present; omit it to detect the worker instead.",
-            path: "runtime.entry",
-        });
-    }
-    return issues;
-}
 /**
  * Keys a committed `sf.jsonc` owns outright: they are facts about the content
  * of a version (who may read it, what it is called, what runs it), so they roll
@@ -233,20 +165,9 @@ export function spaceConfigOverlayIssue(config) {
     }
     return capIssues(config)[0] ?? null;
 }
-// Other platforms' routing vocabulary. We have one matcher grammar; naming it
-// four more ways would be four more things to keep in sync.
-const ROUTING_KEYS = new Set(["proxies", "proxy", "routes"]);
-// OUR routing vocabulary. These keys are real sf.jsonc keys, owned end to end
-// by the routing compiler (crates/stattic-runtime-core): the strict v1 compiler
-// validates them and the merge folds them in behind `_redirects`/`_headers`.
-// This lane resolves the serving config, so it neither validates nor carries
-// them — it just leaves them alone.
-const ROUTING_RULE_KEYS = new Set(["redirects", "rewrites", "headers"]);
-// Replaced by the `runtime` declaration; never silently ignored like other
-// unknown keys, because it is the one key whose loss changes what gets served.
-const REMOVED_FUNCTIONS_KEY = "functions";
-const KNOWN_FILE_KEYS = new Set(Object.keys(spaceConfigFileSchema.shape));
-// Strips JSONC comments and trailing commas (string-aware single pass).
+// Strips JSONC comments and trailing commas (string-aware single pass). The
+// config file itself is parsed by the crate; this stays for the OTHER JSONC
+// files the CLI reads (agent configs, exported platform env).
 export function stripJsonComments(raw) {
     let output = "";
     let inString = false;
@@ -326,245 +247,3 @@ export function stripJsonComments(raw) {
     }
     return output;
 }
-/**
- * Parses a raw `sf.jsonc` at finalize: 256 KB cap, JSONC tolerance,
- * routing-key rejection, unknown-key diagnostics, shared shape caps. Errors
- * fail the version; warnings ride version diagnostics.
- */
-export function parseSpaceConfigFile(raw, options = {}) {
-    const configPath = options.path ?? SPACE_CONFIG_CANONICAL_FILE;
-    if (byteLength(raw) > SPACE_CONFIG_CAPS.fileBytes) {
-        return {
-            config: null,
-            issues: [
-                {
-                    severity: "error",
-                    code: "config_file_too_large",
-                    message: `${configPath} supports up to ${SPACE_CONFIG_CAPS.fileBytes} bytes.`,
-                    path: configPath,
-                    details: { size: byteLength(raw), limit: SPACE_CONFIG_CAPS.fileBytes },
-                },
-            ],
-        };
-    }
-    let candidate;
-    try {
-        candidate = JSON.parse(stripJsonComments(raw));
-    }
-    catch (error) {
-        return {
-            config: null,
-            issues: [
-                {
-                    severity: "error",
-                    code: "config_invalid",
-                    message: `${configPath} is not valid JSONC: ${error instanceof Error ? error.message : "parse error"}.`,
-                    path: configPath,
-                },
-            ],
-        };
-    }
-    if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
-        return {
-            config: null,
-            issues: [
-                {
-                    severity: "error",
-                    code: "config_invalid",
-                    message: `${configPath} must contain a JSON object.`,
-                    path: configPath,
-                },
-            ],
-        };
-    }
-    const record = candidate;
-    const issues = [];
-    for (const key of Object.keys(record)) {
-        if (KNOWN_FILE_KEYS.has(key)) {
-            continue;
-        }
-        if (ROUTING_RULE_KEYS.has(key)) {
-            delete record[key];
-            continue;
-        }
-        if (key === REMOVED_FUNCTIONS_KEY) {
-            // The runtime declaration replaced this key outright (spec "The old
-            // top-level functions.* key is removed in the same cutover"): warning-and-
-            // strip would publish static files under a config that asked for a
-            // worker, so it blocks with its own code instead.
-            issues.push({
-                severity: "error",
-                code: "config_functions_key_removed",
-                message: `The "${REMOVED_FUNCTIONS_KEY}" key was removed from ${configPath}; declare runtime.kind "functions" instead.`,
-                path: key,
-            });
-        }
-        else if (ROUTING_KEYS.has(key)) {
-            issues.push({
-                severity: "error",
-                code: "config_invalid",
-                message: `Routing never lives in ${configPath}; move "${key}" into _redirects/_headers.`,
-                path: key,
-            });
-        }
-        else {
-            issues.push({
-                severity: "warning",
-                code: "config_invalid",
-                message: `Unknown ${configPath} key "${key}" was ignored.`,
-                path: key,
-            });
-        }
-        delete record[key];
-    }
-    issues.push(...capIssues(record), ...fileOnlyIssues(record));
-    if (issues.some((issue) => issue.severity === "error")) {
-        return { config: null, issues };
-    }
-    const parsed = spaceConfigFileSchema.safeParse(record);
-    if (!parsed.success) {
-        for (const issue of parsed.error.issues) {
-            issues.push({
-                severity: "error",
-                code: "config_invalid",
-                message: issue.message,
-                path: issue.path.map(String).join(".") || configPath,
-            });
-        }
-        return { config: null, issues };
-    }
-    return { config: parsed.data, issues };
-}
-// Mirrors the runtime's private-file rules (_stattic_runtime_file_private):
-// convention/config files and dot-segment paths never serve, so they don't
-// count toward root HTML inference below.
-const PRIVATE_SERVING_FILES = new Set([
-    "_redirects",
-    "_headers",
-    "_config.json",
-    "_routes.json",
-    ...SPACE_CONFIG_PRIVATE_FILES,
-]);
-function privateServingPath(path) {
-    if (PRIVATE_SERVING_FILES.has(path) ||
-        path === ".well-known/spacefast-runtime" ||
-        path === ".well-known/stattic-runtime") {
-        return true;
-    }
-    const segments = path.toLowerCase().split("/");
-    return segments.some((segment, index) => !(index === 0 && segment === ".well-known") && segment.startsWith("."));
-}
-function rootHtmlPaths(manifestPaths) {
-    const htmlPaths = [];
-    for (const path of manifestPaths) {
-        if (path === "" || privateServingPath(path)) {
-            continue;
-        }
-        if (!path.includes("/") && /\.html?$/i.test(path)) {
-            htmlPaths.push(path);
-        }
-    }
-    return htmlPaths.toSorted((left, right) => left.localeCompare(right));
-}
-function normalizeFallback(fallback) {
-    if (fallback === undefined) {
-        return null;
-    }
-    if (typeof fallback === "string") {
-        return { path: fallback.replace(/^\/+/, ""), status: 200 };
-    }
-    const status = fallback.status === 404 ? 404 : 200;
-    return { path: fallback.path.replace(/^\/+/, ""), status };
-}
-/**
- * Resolves the effective SpaceConfig for a version at finalize (or
- * config-only regeneration). `manifestPaths` is the canonical committed file
- * set; `fileConfig` the parsed sf.jsonc (null when absent); `overlay`
- * the stored space config overlay (null when nothing overridden).
- */
-export function resolveEffectiveSpaceConfig(input) {
-    const rootHtml = rootHtmlPaths(input.manifestPaths);
-    const hasRootIndex = rootHtml.includes("index.html");
-    const inferredRootHtmlIndex = hasRootIndex ? "index.html" : (rootHtml[0] ?? null);
-    const explicitServingShape = input.fileConfig?.index !== undefined ||
-        input.fileConfig?.listing !== undefined ||
-        input.overlay?.index !== undefined ||
-        input.overlay?.listing !== undefined;
-    // Content-inferred defaults (spec: the old website/files modes are exactly
-    // these two default bundles; never API fields). A Functions version is an
-    // application even when it has no root HTML: unresolved requests, including
-    // `/`, belong to its worker. Static versions retain the content inference —
-    // a root index.html means website mode, any other root HTML becomes the
-    // homepage rewrite, and no root HTML means files mode.
-    const functionsApplication = input.runtimeKind === "functions";
-    const defaults = inferredRootHtmlIndex
-        ? { index: inferredRootHtmlIndex, listing: false }
-        : { index: false, listing: !functionsApplication };
-    const merged = { ...defaults };
-    for (const layer of [input.fileConfig, input.overlay]) {
-        if (!layer) {
-            continue;
-        }
-        for (const key of Object.keys(spaceConfigSchema.shape)) {
-            const value = layer[key];
-            if (value !== undefined) {
-                merged[key] = value;
-            }
-        }
-    }
-    const issues = [];
-    const fallback = normalizeFallback(merged.fallback);
-    // Invariant (spec "Serving resolution"): a fallback must point at a
-    // committed file — no implicit extension guessing, fail at finalize.
-    if (fallback && !input.manifestPaths.has(fallback.path)) {
-        issues.push({
-            severity: "error",
-            code: "config_invalid",
-            message: `fallback path "/${fallback.path}" is not a committed file in this version.`,
-            path: "fallback.path",
-            details: { path: fallback.path },
-        });
-    }
-    const listing = merged.listing ?? (!functionsApplication && !inferredRootHtmlIndex);
-    const serving = {
-        index: merged.index ?? inferredRootHtmlIndex ?? false,
-        fallback,
-        // Clean URLs (runtime W7.1): an explicit config value wins; the default is
-        // ON for plain static sites and OFF when a 200-status SPA fallback owns
-        // extensionless routes (the fallback answers them instead). The runtime
-        // resolver (management.php) applies the same default for artifacts
-        // finalized without the key.
-        cleanUrls: merged.cleanUrls ?? !(fallback && fallback.status === 200),
-        listing,
-        // The single-file viewer rides the listing bundle (artifact-style spaces).
-        viewer: listing,
-        meta: merged.meta ?? null,
-        pageTheme: merged.theme && Object.keys(merged.theme).length > 0 ? merged.theme : null,
-        experimentalGutenberg: merged.experimental_gutenberg === true,
-        inject: merged.inject ?? null,
-    };
-    if (inferredRootHtmlIndex !== null && !hasRootIndex && serving.index === inferredRootHtmlIndex) {
-        // Surfaced on the publish receipt and version diagnostics so the CLI and
-        // agents learn the rewrite without probing the live URL.
-        issues.push({
-            severity: "info",
-            code: "single_html_index",
-            message: `${inferredRootHtmlIndex} is the root HTML file selected for this version, so it serves as the homepage: / rewrites to /${inferredRootHtmlIndex}.`,
-            path: "index",
-            details: { path: inferredRootHtmlIndex, rootHtmlCount: rootHtml.length },
-        });
-    }
-    if (inferredRootHtmlIndex === null &&
-        serving.index === false &&
-        serving.listing &&
-        !explicitServingShape) {
-        issues.push({
-            severity: "info",
-            code: "files_mode_inferred",
-            message: "No HTML files were found in the root of this version, so it serves in files mode with directory listing enabled.",
-            path: "listing",
-            details: { rootHtmlCount: 0 },
-        });
-    }
-    return { config: merged, serving, issues };
-}

package/dist/utils/storage-policy.d.ts

@@ -1,6 +1,6 @@
 export declare const STORAGE_OBJECT_MAX_FILE_BYTES: number;
-export declare const STORAGE_OBJECT_MAX_OWNER_BYTES: number;
 export declare const STORAGE_CONTENT_SNIFF_BYTES = 512;
+export declare const STORAGE_ANON_DAILY_BYTES: number;
 export declare const STORAGE_BLOCKED_CONTENT_TYPES: string[];
 export declare const STORAGE_BLOCKED_CONTENT_TYPE_FRAGMENTS: string[];
 export declare const STORAGE_BLOCKED_MAGIC_HEX: string[];

package/dist/utils/storage-policy.js

@@ -5,8 +5,10 @@
 // `bun --filter @spacefast/control-plane runtime:codegen-policy`. Both execute
 // the same storage-policy.fixtures.json corpus.
 export const STORAGE_OBJECT_MAX_FILE_BYTES = 5 * 1024 * 1024;
-export const STORAGE_OBJECT_MAX_OWNER_BYTES = 100 * 1024 * 1024;
 export const STORAGE_CONTENT_SNIFF_BYTES = 512;
+// Anonymous commenters share a per-space rolling daily upload budget; identified
+// principals and Functions relays are accountable and carry no budget.
+export const STORAGE_ANON_DAILY_BYTES = 200 * 1024 * 1024;
 export const STORAGE_BLOCKED_CONTENT_TYPES = [
     "application/java-archive",
     "application/java-vm",

package/dist/utils/structured-error.d.ts

@@ -0,0 +1,14 @@
+export declare class StructuredError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    readonly exitCode: number;
+    readonly type: string | undefined;
+    constructor(input: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+        exitCode?: number | undefined;
+        type?: string | undefined;
+    });
+}
+export declare function structuredValidationError(message: string, details?: Record<string, unknown>): StructuredError;

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/version-path.js

@@ -3,12 +3,20 @@
 // 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: {
@@ -137,7 +139,7 @@ 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;
 }, {

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
@@ -30,10 +31,11 @@ export const CONCEPTS = {
         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",
@@ -129,10 +131,11 @@ 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -27,13 +27,13 @@
       "../../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",
+      "../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",
-      "../cli/SKILL.md",
-      "../cli/references.md"
+      "src/docs/agent-prose.ts"
     ]
   },
   "exports": {
@@ -75,6 +75,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",