@spacefast/common 0.0.13 → 0.0.17

package/dist/utils/version-file-browser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the canonical MIME essence only when browsers may render the bytes
+ * on an authenticated origin. Active document formats (HTML, SVG, XML, and
+ * scripts) are intentionally absent; `nosniff` is the other half of this
+ * contract at the response boundary.
+ */
+export declare function inlineVersionFileContentType(contentType: string | null | undefined): string | null;
+export declare function versionFileContentDisposition(disposition: "attachment" | "inline", filePath: string): string;
+/**
+ * A download remains inert even if a user agent ignores attachment handling:
+ * the CSP sandbox gives it an opaque origin and permits no script or fetch.
+ */
+export declare function versionFileAttachmentHeaders(filePath: string): Record<string, string>;

package/dist/utils/version-file-browser.js

@@ -0,0 +1,59 @@
+const INLINE_VERSION_FILE_CONTENT_TYPES = new Set([
+    "application/pdf",
+    "audio/aac",
+    "audio/flac",
+    "audio/mp4",
+    "audio/mpeg",
+    "audio/ogg",
+    "audio/opus",
+    "audio/wav",
+    "audio/webm",
+    "audio/x-m4a",
+    "audio/x-wav",
+    "image/apng",
+    "image/avif",
+    "image/bmp",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/vnd.microsoft.icon",
+    "image/webp",
+    "image/x-icon",
+    "video/mp4",
+    "video/ogg",
+    "video/quicktime",
+    "video/webm",
+    "video/x-m4v",
+]);
+/**
+ * Returns the canonical MIME essence only when browsers may render the bytes
+ * on an authenticated origin. Active document formats (HTML, SVG, XML, and
+ * scripts) are intentionally absent; `nosniff` is the other half of this
+ * contract at the response boundary.
+ */
+export function inlineVersionFileContentType(contentType) {
+    const essence = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return INLINE_VERSION_FILE_CONTENT_TYPES.has(essence) ? essence : null;
+}
+function dispositionFilename(filePath) {
+    const basename = filePath.split("/").findLast(Boolean) ?? "download";
+    const ascii = basename
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\]/g, "_")
+        .slice(0, 180);
+    return ascii || "download";
+}
+export function versionFileContentDisposition(disposition, filePath) {
+    return `${disposition}; filename="${dispositionFilename(filePath)}"`;
+}
+/**
+ * A download remains inert even if a user agent ignores attachment handling:
+ * the CSP sandbox gives it an opaque origin and permits no script or fetch.
+ */
+export function versionFileAttachmentHeaders(filePath) {
+    return {
+        "content-disposition": versionFileContentDisposition("attachment", filePath),
+        "content-security-policy": "default-src 'none'; sandbox; frame-ancestors 'none'",
+        "x-content-type-options": "nosniff",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.13",
+  "version": "0.0.17",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -20,6 +20,22 @@
     "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",
@@ -94,6 +110,8 @@
     "@tanstack/react-query": "^5.101.4",
     "culori": "^4.0.2",
     "js-yaml": "^4.1.1",
+    "mime": "^4.1.0",
+    "parse5": "^7.3.0",
     "smol-toml": "^1.7.0",
     "zod": "^4.4.3"
   }

package/dist/contracts/mounts.d.ts

@@ -1,142 +0,0 @@
-import { z } from "zod";
-export declare function normalizeMountPathPrefix(value: string): string;
-export declare const mountPathPrefixSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-export declare const spaceMountCreateSchema: z.ZodObject<{
-    sourceVersionId: z.ZodCustom<`ver_${string}`, `ver_${string}`>;
-    pathPrefix: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-    targetSpaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-    channel: z.ZodDefault<z.ZodLiteral<"live">>;
-}, z.core.$strip>;
-export declare const spaceMountSchema: z.ZodObject<{
-    id: z.ZodCustom<`mnt_${string}`, `mnt_${string}`>;
-    spaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-    sourceVersionId: z.ZodCustom<`ver_${string}`, `ver_${string}`>;
-    pathPrefix: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-    targetSpaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-    targetSpaceSlug: z.ZodString;
-    channel: z.ZodLiteral<"live">;
-    versionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-    targetVersionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-    createdAt: z.ZodString;
-    updatedAt: z.ZodString;
-}, z.core.$strip>;
-export declare const spaceMountListResponseSchema: z.ZodObject<{
-    data: z.ZodArray<z.ZodObject<{
-        id: z.ZodCustom<`mnt_${string}`, `mnt_${string}`>;
-        spaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-        sourceVersionId: z.ZodCustom<`ver_${string}`, `ver_${string}`>;
-        pathPrefix: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-        targetSpaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-        targetSpaceSlug: z.ZodString;
-        channel: z.ZodLiteral<"live">;
-        versionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-        targetVersionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-        createdAt: z.ZodString;
-        updatedAt: z.ZodString;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export declare const spaceMountResponseSchema: z.ZodObject<{
-    data: z.ZodObject<{
-        id: z.ZodCustom<`mnt_${string}`, `mnt_${string}`>;
-        spaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-        sourceVersionId: z.ZodCustom<`ver_${string}`, `ver_${string}`>;
-        pathPrefix: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-        targetSpaceId: z.ZodCustom<`spc_${string}`, `spc_${string}`>;
-        targetSpaceSlug: z.ZodString;
-        channel: z.ZodLiteral<"live">;
-        versionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-        targetVersionId: z.ZodNullable<z.ZodCustom<`ver_${string}`, `ver_${string}`>>;
-        createdAt: z.ZodString;
-        updatedAt: z.ZodString;
-    }, z.core.$strip>;
-    operation: z.ZodNullable<z.ZodObject<{
-        id: z.ZodString;
-        kind: z.ZodString;
-        status: z.ZodEnum<{
-            failed: "failed";
-            canceled: "canceled";
-            queued: "queued";
-            running: "running";
-            succeeded: "succeeded";
-        }>;
-        resources: z.ZodArray<z.ZodObject<{
-            type: z.ZodString;
-            id: z.ZodString;
-        }, z.core.$strip>>;
-        progress: z.ZodOptional<z.ZodObject<{
-            total: z.ZodNumber;
-            completed: z.ZodNumber;
-            failed: z.ZodNumber;
-        }, z.core.$strip>>;
-        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            code: z.ZodString;
-            severity: z.ZodEnum<{
-                info: "info";
-                error: "error";
-                warning: "warning";
-            }>;
-            message: z.ZodString;
-            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-                registrar: "registrar";
-                wpcloud: "wpcloud";
-                dns: "dns";
-                runtime: "runtime";
-            }>>>;
-            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-        }, z.core.$strip>>>;
-        createdAt: z.ZodString;
-        finishedAt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export declare const spaceMountDeleteResponseSchema: z.ZodObject<{
-    data: z.ZodObject<{
-        id: z.ZodCustom<`mnt_${string}`, `mnt_${string}`>;
-        deleted: z.ZodLiteral<true>;
-    }, z.core.$strip>;
-    operation: z.ZodNullable<z.ZodObject<{
-        id: z.ZodString;
-        kind: z.ZodString;
-        status: z.ZodEnum<{
-            failed: "failed";
-            canceled: "canceled";
-            queued: "queued";
-            running: "running";
-            succeeded: "succeeded";
-        }>;
-        resources: z.ZodArray<z.ZodObject<{
-            type: z.ZodString;
-            id: z.ZodString;
-        }, z.core.$strip>>;
-        progress: z.ZodOptional<z.ZodObject<{
-            total: z.ZodNumber;
-            completed: z.ZodNumber;
-            failed: z.ZodNumber;
-        }, z.core.$strip>>;
-        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            code: z.ZodString;
-            severity: z.ZodEnum<{
-                info: "info";
-                error: "error";
-                warning: "warning";
-            }>;
-            message: z.ZodString;
-            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-                registrar: "registrar";
-                wpcloud: "wpcloud";
-                dns: "dns";
-                runtime: "runtime";
-            }>>>;
-            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-        }, z.core.$strip>>>;
-        createdAt: z.ZodString;
-        finishedAt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type SpaceMountCreate = z.infer<typeof spaceMountCreateSchema>;
-export type SpaceMount = z.infer<typeof spaceMountSchema>;

package/dist/contracts/mounts.js

@@ -1,56 +0,0 @@
-import { z } from "zod";
-import { dataEnvelope, mutationEnvelope } from "./common.js";
-import { registeredIdSchema } from "./ids.js";
-const RESERVED_MOUNT_PREFIXES = ["/__spacefast", "/__stattic", "/.well-known"];
-export function normalizeMountPathPrefix(value) {
-    const trimmed = value.trim();
-    if (trimmed === "" || trimmed === "/")
-        return "/";
-    return `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
-}
-export const mountPathPrefixSchema = z
-    .string()
-    .min(1)
-    .max(1024)
-    .transform(normalizeMountPathPrefix)
-    .refine((value) => value !== "/", "A mount path must be below the site root.")
-    .refine((value) => Array.from(value).every((character) => {
-    const codePoint = character.codePointAt(0) ?? 0;
-    return codePoint > 0x9f || (codePoint > 0x1f && codePoint !== 0x7f);
-}), "Mount path is invalid.")
-    .refine((value) => !value.includes("\\") && !value.includes("//"), "Mount path is invalid.")
-    .refine((value) => !value
-    .split("/")
-    .filter(Boolean)
-    .some((segment) => segment === "." || segment === ".."), "Mount path is invalid.")
-    .refine((value) => !RESERVED_MOUNT_PREFIXES.some((reserved) => value === reserved || value.startsWith(`${reserved}/`)), "Mount path uses a Spacefast-reserved prefix.")
-    .describe("Normalized path prefix on the website, for example `/docs`.");
-export const spaceMountCreateSchema = z.object({
-    sourceVersionId: registeredIdSchema("ver").describe("Immutable website version whose production activation enables this mount."),
-    pathPrefix: mountPathPrefixSchema,
-    targetSpaceId: registeredIdSchema("spc").describe("Explicitly authorized same-team space to mount."),
-    channel: z
-        .literal("live")
-        .default("live")
-        .describe("Target production channel followed by this mount."),
-});
-export const spaceMountSchema = z.object({
-    id: registeredIdSchema("mnt"),
-    spaceId: registeredIdSchema("spc"),
-    sourceVersionId: registeredIdSchema("ver"),
-    pathPrefix: mountPathPrefixSchema,
-    targetSpaceId: registeredIdSchema("spc"),
-    targetSpaceSlug: z.string(),
-    channel: z.literal("live"),
-    versionId: registeredIdSchema("ver")
-        .nullable()
-        .describe("Immutable target version currently serving from the mount."),
-    targetVersionId: registeredIdSchema("ver")
-        .nullable()
-        .describe("Target production-channel version the durable synchronizer is converging toward."),
-    createdAt: z.string().datetime(),
-    updatedAt: z.string().datetime(),
-});
-export const spaceMountListResponseSchema = dataEnvelope(z.array(spaceMountSchema));
-export const spaceMountResponseSchema = mutationEnvelope(spaceMountSchema);
-export const spaceMountDeleteResponseSchema = mutationEnvelope(z.object({ id: registeredIdSchema("mnt"), deleted: z.literal(true) }));

package/dist/utils/asset-fingerprint.d.ts

@@ -1,64 +0,0 @@
-export declare const FINGERPRINT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
-export declare const FINGERPRINT_HASH_LENGTH = 8;
-export type FingerprintCandidateFile = {
-    /** Canonical manifest path (no leading slash). */
-    path: string;
-    /** Full lowercase-hex sha256 of the file's bytes. */
-    sha256?: string | undefined;
-    /** UTF-8 text for html/css files that may need reference rewriting. */
-    text?: string | undefined;
-};
-export type FingerprintSkipReason = "css_cycle" | "alias_collision" | "user_cache_control" | "budget";
-export type FingerprintPlan = {
-    /**
-     * Alias manifest entries to add, sorted by sourcePath; content is identical
-     * to sourcePath's. This is also the "what got fingerprinted" relation —
-     * one array, `path` = the hashed alias, `sourcePath` = the original.
-     */
-    aliases: Array<{
-        path: string;
-        sourcePath: string;
-    }>;
-    /** html/css files whose published content changes (both paths, one blob). */
-    rewrites: Array<{
-        path: string;
-        text: string;
-        sha256: string;
-    }>;
-    /** Eligible-looking files the pass left on the default lane, with reasons. */
-    skipped: Array<{
-        path: string;
-        reason: FingerprintSkipReason;
-    }>;
-};
-export type StaticDocumentDependency = {
-    sourcePath: string;
-    targetPath: string;
-};
-/**
- * Advisory-only dependency discovery used by finalize diagnostics. It shares
- * the exact HTML/CSS tokenizer and URL resolver with asset fingerprinting, then
- * adds conservative static JS imports and page links. It never rewrites bytes
- * and never changes access automatically.
- */
-export declare function scanStaticDocumentDependencies(sourcePath: string, text: string): StaticDocumentDependency[];
-export declare function planAssetFingerprints(input: {
-    files: readonly FingerprintCandidateFile[];
-    /** sha256 as lowercase hex over UTF-8 bytes of `text`. */
-    hashHex: (text: string) => string;
-    /**
-     * True when a user `_headers` Cache-Control rule already covers this URL
-     * path ("/"-prefixed). Files whose original OR probe-alias path is covered
-     * are never fingerprinted — user rules always win.
-     */
-    pathCoveredByUserCacheControl?: ((urlPath: string) => boolean) | undefined;
-    /** Extra per-path exclusion (e.g. header-rule budget trimming). */
-    excludePath?: ((path: string) => boolean) | undefined;
-}): FingerprintPlan;
-/**
- * Merges the generated immutable pins into user `_headers` content. The user
- * content is preserved byte-for-byte; generated exact-path rules are appended
- * (per-path Cache-Control conflicts are impossible — files covered by a user
- * Cache-Control rule are never fingerprinted).
- */
-export declare function mergeFingerprintHeaders(userHeaders: string | undefined, aliasPaths: readonly string[]): string;