@spacefast/common 0.2.2 → 0.4.1

package/dist/utils/logger.js

@@ -0,0 +1,144 @@
+/* oxlint-disable anti-slop/no-unsafe-dictionary-type, anti-slop/no-runtime-typeof, anti-slop/no-known-value-widening, anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns -- Log fields are an open bag of arbitrary application values by contract; this module's job is to serialize any runtime value safely, so the open dictionary and runtime kind checks are the boundary itself (same rationale as the Sentry processor in apps/control-plane/src/lib/sentry.ts). */
+import { inspect } from "node:util";
+const LEVEL_WEIGHT = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: Number.POSITIVE_INFINITY,
+};
+function isConfigurableLevel(value) {
+    return (value === "debug" ||
+        value === "info" ||
+        value === "warn" ||
+        value === "error" ||
+        value === "silent");
+}
+function defaultLevel() {
+    const raw = process.env.LOG_LEVEL?.toLowerCase();
+    if (isConfigurableLevel(raw))
+        return raw;
+    return process.env.NODE_ENV === "production" ? "info" : "debug";
+}
+function defaultFormat() {
+    return process.env.NODE_ENV === "production" || process.env.LOG_FORMAT === "json"
+        ? "json"
+        : "pretty";
+}
+function normalizeValue(value, projectError, seen, depth = 0) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return "[Circular]";
+    if (depth >= 12)
+        return "[Truncated]";
+    seen.add(value);
+    if (value instanceof Error) {
+        const projected = projectError?.(value);
+        if (projected)
+            return projected;
+        const record = {
+            ...value,
+            name: value.name,
+            message: value.message,
+            stack: value.stack,
+        };
+        if (value.cause !== undefined)
+            record.cause = value.cause;
+        if (value instanceof AggregateError)
+            record.errors = value.errors;
+        return normalizeValue(record, projectError, seen, depth + 1);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeValue(entry, projectError, seen, depth + 1));
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        normalizeValue(entry, projectError, seen, depth + 1),
+    ]));
+}
+function normalizeFields(fields, projectError) {
+    if (!fields)
+        return undefined;
+    return Object.fromEntries(Object.entries(fields).map(([key, value]) => [
+        key,
+        normalizeValue(value, projectError, new WeakSet()),
+    ]));
+}
+function safeJsonStringify(record) {
+    const seen = new WeakSet();
+    return (JSON.stringify(record, (_key, value) => {
+        if (typeof value === "bigint")
+            return value.toString();
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value))
+                return "[Circular]";
+            seen.add(value);
+        }
+        return value;
+    }) ?? "null");
+}
+const AUTO_STREAM = {
+    debug: "log",
+    info: "log",
+    warn: "warn",
+    error: "error",
+};
+function emit(options, level, message, fields) {
+    if (LEVEL_WEIGHT[level] < options.minWeight)
+        return;
+    const timestamp = new Date().toISOString();
+    const payload = normalizeFields(fields, options.projectError);
+    const stream = options.stream === "stderr" ? "error" : AUTO_STREAM[level];
+    if (options.format === "json") {
+        console[stream](safeJsonStringify({ ts: timestamp, level, message, ...payload }));
+    }
+    else {
+        const prefix = `${timestamp} ${level.toUpperCase().padEnd(5, " ")}`;
+        if (!payload || Object.keys(payload).length === 0) {
+            console[stream](`${prefix} ${message}`);
+        }
+        else {
+            const rendered = inspect(payload, { depth: 6, colors: true, breakLength: 120 });
+            console[stream](`${prefix} ${message} ${rendered}`);
+        }
+    }
+    if (options.onEmit) {
+        try {
+            options.onEmit(level, message, payload);
+        }
+        catch {
+            // Logging must never make application code fail.
+        }
+    }
+}
+function build(options, bindings) {
+    const hasBindings = Object.keys(bindings).length > 0;
+    function merge(fields) {
+        if (!fields)
+            return hasBindings ? { ...bindings } : undefined;
+        return { ...bindings, ...fields };
+    }
+    return {
+        debug: (message, fields) => emit(options, "debug", message, merge(fields)),
+        info: (message, fields) => emit(options, "info", message, merge(fields)),
+        warn: (message, fields) => emit(options, "warn", message, merge(fields)),
+        error: (message, fields) => emit(options, "error", message, merge(fields)),
+        child: (extraBindings) => build(options, { ...bindings, ...extraBindings }),
+    };
+}
+export function createLogger(options = {}) {
+    const resolved = {
+        minWeight: LEVEL_WEIGHT[options.level ?? defaultLevel()],
+        format: options.format ?? defaultFormat(),
+        stream: options.stream ?? "auto",
+        onEmit: options.onEmit,
+        projectError: options.projectError,
+    };
+    return build(resolved, options.bindings ?? {});
+}
+/** Env-configured logger for processes that own their stdout. */
+export const logger = createLogger();

package/dist/utils/page-routes.d.ts

@@ -0,0 +1,9 @@
+export declare function matchPagePath(pattern: string, pathname: string): Record<string, string> | null;
+export declare function comparePagePaths(left: string, right: string): number;
+export declare function resolvePageRoute<T extends {
+    path: string;
+}>(pages: readonly T[], pathname: string): {
+    page: T;
+    params: Record<string, string>;
+} | null;
+export declare function pageRoutesOverlap(left: string, right: string): boolean;

package/dist/utils/page-routes.js

@@ -0,0 +1,82 @@
+function segments(path) {
+    return path
+        .replace(/^\/+|\/+$/g, "")
+        .split("/")
+        .filter(Boolean);
+}
+export function matchPagePath(pattern, pathname) {
+    const expected = segments(pattern);
+    const encoded = segments(pathname);
+    let actual;
+    try {
+        actual = encoded.map((segment) => decodeURIComponent(segment));
+    }
+    catch {
+        return null;
+    }
+    if (actual.some((segment) => segment.includes("/") || segment.includes("\\") || segment.includes("\0")))
+        return null;
+    const params = {};
+    for (const [index, segment] of expected.entries()) {
+        if (segment.startsWith("*")) {
+            if (index !== expected.length - 1 || index >= actual.length)
+                return null;
+            Object.defineProperty(params, segment.slice(1), {
+                value: actual.slice(index).join("/"),
+                enumerable: true,
+            });
+            return params;
+        }
+        const value = actual[index];
+        if (value === undefined)
+            return null;
+        if (segment.startsWith(":")) {
+            Object.defineProperty(params, segment.slice(1), { value, enumerable: true });
+        }
+        else if (segment !== value) {
+            return null;
+        }
+    }
+    return actual.length === expected.length ? params : null;
+}
+export function comparePagePaths(left, right) {
+    const a = segments(left);
+    const b = segments(right);
+    const rank = (segment) => (segment.startsWith("*") ? 1 : segment.startsWith(":") ? 2 : 3);
+    for (let index = 0; index < Math.min(a.length, b.length); index++) {
+        const x = a[index] ?? "";
+        const y = b[index] ?? "";
+        const priority = rank(y) - rank(x);
+        if (priority !== 0)
+            return priority;
+        if (rank(x) === 3 && x !== y)
+            return x < y ? -1 : 1;
+    }
+    return a.length - b.length || (left < right ? -1 : left > right ? 1 : 0);
+}
+export function resolvePageRoute(pages, pathname) {
+    let selected = null;
+    for (const page of pages) {
+        const params = matchPagePath(page.path, pathname);
+        if (params !== null &&
+            (selected === null || comparePagePaths(page.path, selected.page.path) < 0)) {
+            selected = { page, params };
+        }
+    }
+    return selected;
+}
+export function pageRoutesOverlap(left, right) {
+    const a = segments(left);
+    const b = segments(right);
+    for (let index = 0; index < Math.max(a.length, b.length); index++) {
+        const x = a[index];
+        const y = b[index];
+        if (x === undefined || y === undefined)
+            return false;
+        if (x.startsWith("*") || y.startsWith("*") || x === ":splat" || y === ":splat")
+            return true;
+        if (!x.startsWith(":") && !y.startsWith(":") && x !== y)
+            return false;
+    }
+    return true;
+}

package/dist/utils/pages.d.ts

@@ -51,6 +51,8 @@ export declare function escapePageHtml(value: string): string;
  * dashboard preview paints the same tokens from an unsaved draft.
  */
 export declare function pageThemeCss(theme: PageTheme, derived?: DerivedPageColors): string;
+/** Site-wide theme tokens plus low-priority defaults that authored CSS can override. */
+export declare function siteThemeCss(theme: PageTheme): string;
 export declare function expandPageHtml(source: string, context: PageExpansionContext): string;
 export declare function validatePageSources(input: {
     pages: Readonly<Record<string, string>>;

package/dist/utils/pages.js

@@ -61,6 +61,13 @@ export function pageThemeCss(theme, derived = derivePageColors(theme)) {
     const darkBlock = dark.length > 0 ? `@media(prefers-color-scheme:dark){:root{${dark.join(";")}}}` : "";
     return `:root{${root.join(";")}}${darkBlock}`;
 }
+/** Site-wide theme tokens plus low-priority defaults that authored CSS can override. */
+export function siteThemeCss(theme) {
+    const tokens = pageThemeCss(theme);
+    if (tokens === "")
+        return "";
+    return `${tokens}@layer spacefast-theme{body{background:var(--sf-bg,Canvas);color:var(--sf-fg,CanvasText);font-family:var(--sf-font,system-ui,sans-serif)}a{color:var(--sf-link,var(--sf-accent,LinkText))}}`;
+}
 function themeStyle(theme) {
     const css = pageThemeCss(theme);
     return css ? `<style>${css}</style>` : "";

package/dist/utils/publish-form-data.d.ts

@@ -20,6 +20,8 @@ export declare function createPublishFormData(input: {
     slug?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
+    /** Initial root access for a new team-owned Space. */
+    access?: "private" | "team" | "public" | undefined;
     /** Live promotion intent for archive builds; null produces an unpromoted ready version. */
     channel?: "live" | null | undefined;
     /**

package/dist/utils/publish-form-data.js

@@ -5,6 +5,8 @@ export function createPublishFormData(input) {
         form.append("spaceId", input.spaceId);
     if (input.teamId)
         form.append("teamId", input.teamId);
+    if (input.access)
+        form.append("access", input.access);
     if (input.description)
         form.append("description", input.description);
     if (input.sourceMetadata || input.buildLog || input.channel !== undefined) {

package/dist/utils/publish-policy-spacefast.d.ts

@@ -0,0 +1,13 @@
+export declare const ANONYMOUS_SERVE_CONTENT_TYPES: readonly ["text/*", "image/*", "font/*", "application/json", "application/manifest+json", "application/javascript", "application/gzip", "application/xml", "application/rss+xml", "application/atom+xml"];
+export type FreePlanContentPolicyOptions = {
+    claimedSpace?: boolean;
+};
+export declare function freePlanCanUploadPath(filePath: string, options?: FreePlanContentPolicyOptions): boolean;
+export declare function freePlanCanUploadContentType(contentType: string | undefined): boolean;
+export declare function filterFreePlanManifest<T extends {
+    path: string;
+    contentType?: string | undefined;
+}>(files: readonly T[], options?: FreePlanContentPolicyOptions): {
+    allowed: T[];
+    ignored: string[];
+};

package/dist/utils/publish-policy-spacefast.js

@@ -0,0 +1,117 @@
+import { SPACE_CONFIG_PRIVATE_FILES } from "../contracts/space-config.js";
+import { normalizePublishPath, publishPathIsConvention } from "./publish-policy.js";
+// Free-plan publish content policy (spec "Plans And Limits"). What a plan lets a
+// space publish and serve is Spacefast's commerce model, not the publish format,
+// so it extends the shared static policy in `./publish-policy.js` rather than
+// living inside it.
+const FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS = new Set([
+    ".html",
+    ".htm",
+    ".css",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".map",
+    ".webmanifest",
+    ".txt",
+    ".md",
+    ".csv",
+    // Migration fixtures, served as application/octet-stream.
+    ".customtype",
+    ".xml",
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".avif",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+]);
+// THE anonymous content enforcement: uploads are accepted like any free
+// publish, but until the space is claimed the runtime serves only these types,
+// pushed as the route-config `content_types` allowlist. Web-page content only.
+// Gzip is the one archive, because pagefind search indexes need it.
+export const ANONYMOUS_SERVE_CONTENT_TYPES = [
+    "text/*",
+    "image/*",
+    "font/*",
+    "application/json",
+    "application/manifest+json",
+    "application/javascript",
+    "application/gzip",
+    "application/xml",
+    "application/rss+xml",
+    "application/atom+xml",
+];
+function extensionForPath(filePath) {
+    const normalized = normalizePublishPath(filePath).toLowerCase();
+    const fileName = normalized.split("/").at(-1) ?? normalized;
+    const extensionIndex = fileName.lastIndexOf(".");
+    return extensionIndex > 0 ? fileName.slice(extensionIndex) : "";
+}
+function freePlanDeniedExecutablePath(filePath) {
+    return normalizePublishPath(filePath)
+        .toLowerCase()
+        .split("/")
+        .some((segment) => segment === "bin");
+}
+// Acceptance is deliberately identical for claimed-free and unclaimed spaces:
+// rejecting types at upload adds no safety, since the bytes reach us before
+// any scan either way. ANONYMOUS_SERVE_CONTENT_TYPES is what keeps opaque
+// binaries dark until the space is claimed.
+export function freePlanCanUploadPath(filePath, options) {
+    const path = normalizePublishPath(filePath);
+    // Platform machinery, not user content: same lifecycle as
+    // `_redirects`/`_headers`, so the content-extension gate must never eat them.
+    if (SPACE_CONFIG_PRIVATE_FILES.some((privateFile) => privateFile === path)) {
+        return true;
+    }
+    if (freePlanDeniedExecutablePath(path)) {
+        return false;
+    }
+    const extension = extensionForPath(path);
+    return (publishPathIsConvention(path) ||
+        extension === "" ||
+        FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS.has(extension) ||
+        (options?.claimedSpace === true && extension === ".sh"));
+}
+export function freePlanCanUploadContentType(contentType) {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    return (normalized === "text/html" ||
+        normalized === "text/plain" ||
+        normalized === "text/css" ||
+        normalized === "text/csv" ||
+        normalized === "text/markdown" ||
+        normalized === "text/javascript" ||
+        normalized === "application/javascript" ||
+        normalized === "application/json" ||
+        normalized === "application/manifest+json" ||
+        // pagefind ships gzip fragments, and ClamAV decompresses gzip when scanning.
+        normalized === "application/gzip" ||
+        normalized === "image/svg+xml" ||
+        normalized === "application/xml" ||
+        normalized === "text/xml" ||
+        normalized?.startsWith("image/") ||
+        normalized?.startsWith("font/") ||
+        false);
+}
+export function filterFreePlanManifest(files, options) {
+    const allowed = [];
+    const ignored = [];
+    for (const file of files) {
+        if (freePlanCanUploadPath(file.path, options) ||
+            freePlanCanUploadContentType(file.contentType)) {
+            allowed.push(file);
+        }
+        else {
+            ignored.push(file.path);
+        }
+    }
+    return { allowed, ignored };
+}

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

@@ -3,6 +3,12 @@ export declare const MANIFEST_MAX_FILES_CEILING = 100000;
 export declare const MANIFEST_MAX_PATH_BYTES = 1024;
 export declare const MANIFEST_MAX_BODY_BYTES: number;
 export declare const MAX_VERSION_FILE_SIZE_BYTES: number;
+/**
+ * Per-version artifact ceiling, summed over file bytes at manifest intake. The
+ * abuse table in `contracts/quotas.js` names this same value as
+ * `maxArtifactBytes` by importing it, so the ceiling has one literal without the
+ * shared validator depending on the host's quota model.
+ */
 export declare const MAX_VERSION_TOTAL_BYTES: number;
 export declare const STATIC_EXECUTION_CONTROL_FILES: string[];
 export declare const STATIC_RUNTIME_CONTROL_SEGMENT_PREFIXES: string[];
@@ -23,7 +29,12 @@ export declare const PUBLISHABLE_BUILD_ARTIFACT_PREFIX = "__spacefast/functions/
 export declare const PUBLISHABLE_SEED_ARTIFACT_PREFIX = "__spacefast/functions/seeds/";
 export declare function publishPathIgnored(relativePath: string): boolean;
 export declare function publishPathIsConvention(relativePath: string): boolean;
-export declare function providerRuntimeFeatureWarnings(paths: readonly string[]): PublishManifestWarning[];
+/**
+ * `productName` is the host's own name, injected: the warning tells an author
+ * which platform will not execute the file it found. It defaults to the
+ * compiled-in Spacefast name, checked against `brand.js` by this module's test.
+ */
+export declare function providerRuntimeFeatureWarnings(paths: readonly string[], productName?: string): PublishManifestWarning[];
 export type StaticUploadPolicyOptions = {
     reservedRuntimeControlFiles?: Iterable<string>;
 };
@@ -78,6 +89,13 @@ export type PublishRouteOwnership = {
     requestedRoute: string;
     artifactPath: string;
 };
+export type PublishRouteArtifact = {
+    path: string;
+    size: number;
+    sha256?: string | undefined;
+    contentType?: string | undefined;
+};
+export declare function isEquivalentHtmlDirectoryIndexCollision(collision: PublishRouteAnalysis["collisions"][number], filesByPath: ReadonlyMap<string, PublishRouteArtifact>, directoryIndex: string | false): boolean;
 /**
  * Canonicalizes a route expanded from an already-canonical manifest path.
  * Manifest intake has decoded percent escapes exactly once, so this must not
@@ -86,12 +104,13 @@ export type PublishRouteOwnership = {
 export declare function canonicalizePublishRequestedRoute(route: string): string;
 /**
  * Expands artifact paths into the request routes they can serve: literal
- * files, directory indexes and clean `.html` aliases. Two artifacts owning one
- * route is rejected at publish rather than left to lookup order.
+ * files, directory indexes and clean `.html` aliases. Multiple artifacts owning
+ * one route are reported so finalize can reject ambiguous content.
  * `routeOwnership` restates the expansion in canonical access-route form.
  */
 export declare function analyzePublishRoutes(paths: readonly string[], options?: {
     index?: string | false;
+    directoryIndex?: string;
     cleanUrls?: boolean;
 }): PublishRouteAnalysis;
 export declare function resolveManifestFileCap(maxFiles?: number | null): number;
@@ -99,16 +118,3 @@ export declare function validatePublishManifest<T extends {
     path: string;
     size: number;
 }>(files: readonly T[], caps?: PublishManifestCaps): PublishManifestResult<T>;
-export declare const ANONYMOUS_SERVE_CONTENT_TYPES: readonly ["text/*", "image/*", "font/*", "application/json", "application/manifest+json", "application/javascript", "application/gzip", "application/xml", "application/rss+xml", "application/atom+xml"];
-export type FreePlanContentPolicyOptions = {
-    claimedSpace?: boolean;
-};
-export declare function freePlanCanUploadPath(filePath: string, options?: FreePlanContentPolicyOptions): boolean;
-export declare function freePlanCanUploadContentType(contentType: string | undefined): boolean;
-export declare function filterFreePlanManifest<T extends {
-    path: string;
-    contentType?: string | undefined;
-}>(files: readonly T[], options?: FreePlanContentPolicyOptions): {
-    allowed: T[];
-    ignored: string[];
-};

package/dist/utils/publish-policy.fixtures.json

@@ -98,6 +98,21 @@
         "path": "nested/__span/x.json",
         "expected": null
     },
+    {
+        "path": "__zero/config",
+        "expected": "static_runtime_control_path_not_supported",
+        "why": "the front door claims the whole /__zero control namespace"
+    },
+    {
+        "path": "__zeroed/index.html",
+        "expected": null,
+        "why": "the Zero namespace is a whole segment, not a string prefix"
+    },
+    {
+        "path": "assets/__zero-client.js",
+        "expected": null,
+        "why": "reserved at the root only, exactly as far as the front door reaches"
+    },
     {
         "path": "__spacefast/x.txt",
         "expected": "static_runtime_control_path_not_supported"