@spacefast/common 0.0.23 → 0.0.26

package/dist/utils/grants.d.ts

@@ -44,6 +44,8 @@ export type GrantEvaluation = {
     matches: GrantMatch[];
 };
 export declare function grantResourcePatternMatches(pattern: string, resource: string, resourceKind?: "route" | "artifact"): boolean;
+/** Does a Grant's resource set reach this path? Include, minus exclude. */
+export declare function grantResourceSetMatches(resources: Grant["resources"], resource: string, resourceKind?: "route" | "artifact"): boolean;
 export type GrantEvaluationExplanation = {
     grantId: string;
     failures: GrantCheckFailure[];

package/dist/utils/grants.js

@@ -27,6 +27,8 @@ function targetMatches(selector, target) {
             return target.kind === "version" && target.versionId === selector.versionId;
         case "branch":
             return target.kind === "branch" && target.branch === selector.branch;
+        // Immutable Version hosts only. The live host is its own target: sharing
+        // "every Version" does not thereby publish the live site.
         case "all_versions":
             return target.kind === "version";
     }
@@ -70,6 +72,29 @@ export function grantResourcePatternMatches(pattern, resource, resourceKind = "r
     };
     return matches(0, 0);
 }
+/**
+ * Exclude patterns read wider than include patterns, and that asymmetry is the
+ * rule, not an accident: the route lane collapses a terminal `index.html`
+ * (normalizeAccessScopePath) while the artifact lane keeps it, so an exclude
+ * naming an index artifact must also close the route that artifact serves.
+ * Include never gets the same courtesy — granting the stripped route would hand
+ * out access nobody wrote down. The serving engine compiles the identical pair
+ * (access-rules.php _stattic_grant_exclude_pattern_variants).
+ */
+function grantExcludePatternMatches(pattern, resource, resourceKind) {
+    if (grantResourcePatternMatches(pattern, resource, resourceKind))
+        return true;
+    const canonical = normalizeGrantResourcePattern(pattern);
+    if (!canonical.endsWith("/index.html"))
+        return false;
+    const stripped = canonical.slice(0, -"/index.html".length);
+    return grantResourcePatternMatches(stripped === "" ? "/" : stripped, resource, resourceKind);
+}
+/** Does a Grant's resource set reach this path? Include, minus exclude. */
+export function grantResourceSetMatches(resources, resource, resourceKind = "route") {
+    return (resources.include.some((pattern) => grantResourcePatternMatches(pattern, resource, resourceKind)) &&
+        !resources.exclude.some((pattern) => grantExcludePatternMatches(pattern, resource, resourceKind)));
+}
 function grantCheckFailures(grant, input, principal, now) {
     const failures = [];
     if (grant.source.kind === "config" && !input.spaceClaimed) {
@@ -120,7 +145,7 @@ function grantCheckFailures(grant, input, principal, now) {
     if (!included) {
         failures.push("resource_not_included");
     }
-    else if (grant.resources.exclude.some((pattern) => grantResourcePatternMatches(pattern, input.resource, input.resourceKind))) {
+    else if (grant.resources.exclude.some((pattern) => grantExcludePatternMatches(pattern, input.resource, input.resourceKind ?? "route"))) {
         failures.push("resource_excluded");
     }
     return failures;

package/dist/utils/gravatar.d.ts

@@ -0,0 +1,9 @@
+/** Gravatar's canonical address form: trimmed and lowercased. */
+export declare function normalizeGravatarEmail(email: string | null | undefined): string | null;
+/** The canonical avatar URL for an already-computed SHA-256 hash. */
+export declare function gravatarUrlFromHash(hashHex: string): string;
+/**
+ * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
+ * a browser can derive it locally and never send the raw address anywhere.
+ */
+export declare function gravatarEmailHash(email: string | null | undefined): Promise<string | null>;

package/dist/utils/gravatar.js

@@ -0,0 +1,31 @@
+/**
+ * The one Gravatar URL shape Spacefast emits. Every surface — control-plane
+ * profiles, the Comments SDK, Slack notifications — derives the same address
+ * for the same person, so an avatar is recognizable wherever it appears and
+ * Cast can validate a guest avatar against a single pattern.
+ *
+ * `d=404` is deliberate: a person without a Gravatar gets no image at all, and
+ * the consumer renders its own initials/palette fallback instead of a stock
+ * silhouette. `s=160` covers the largest avatar we render, retina included.
+ */
+const GRAVATAR_AVATAR_QUERY = "d=404&r=g&s=160";
+/** Gravatar's canonical address form: trimmed and lowercased. */
+export function normalizeGravatarEmail(email) {
+    const normalized = email?.trim().toLowerCase();
+    return normalized ? normalized : null;
+}
+/** The canonical avatar URL for an already-computed SHA-256 hash. */
+export function gravatarUrlFromHash(hashHex) {
+    return `https://gravatar.com/avatar/${hashHex}?${GRAVATAR_AVATAR_QUERY}`;
+}
+/**
+ * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
+ * a browser can derive it locally and never send the raw address anywhere.
+ */
+export async function gravatarEmailHash(email) {
+    const normalized = normalizeGravatarEmail(email);
+    if (!normalized || !globalThis.crypto?.subtle)
+        return null;
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(normalized));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/utils/idempotency.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Stable, secret-safe key for one exact logical mutation attempt. Shared by
+ * every client surface: the same publish issued through the CLI and through
+ * MCP must land on one key or the API stops deduplicating the retry.
+ */
+export declare function stableIdempotencyKey(prefix: string, parts: unknown): string;

package/dist/utils/idempotency.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+/**
+ * Key-sorted JSON that treats an absent key and an `undefined` value as the
+ * same thing. Deliberately *not* `canonicalJson`: a key the CLI omits and one
+ * the MCP server sets to `undefined` describe the same mutation, so they have
+ * to hash alike. Merging the two spellings would change every minted key.
+ */
+function keyJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(keyJson).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${keyJson(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+/**
+ * Stable, secret-safe key for one exact logical mutation attempt. Shared by
+ * every client surface: the same publish issued through the CLI and through
+ * MCP must land on one key or the API stops deduplicating the retry.
+ */
+export function stableIdempotencyKey(prefix, parts) {
+    return `${prefix}-${createHash("sha256").update(keyJson(parts)).digest("hex")}`;
+}

package/dist/utils/local-space-state.d.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
 export declare const LOCAL_SPACE_STATE_DIR_NAME = ".spacefast";
-export declare const LEGACY_LOCAL_SPACE_STATE_DIR_NAME = ".stattic";
 export declare const LOCAL_SPACE_LINK_FILE_NAME = "space.json";
 export declare const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
 /**
@@ -23,6 +22,12 @@ export declare const localSpaceLinkSchema: z.ZodObject<{
     apiBaseUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export declare const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
+export declare const creationAttemptSchema: z.ZodObject<{
+    key: z.ZodString;
+    principal: z.ZodString;
+    kind: z.ZodLiteral<"authenticated">;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
 export declare const localSpaceStateSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     spaceId: z.ZodOptional<z.ZodString>;
@@ -42,22 +47,14 @@ export declare const localSpaceStateSchema: z.ZodObject<{
     pendingPublish: z.ZodOptional<z.ZodObject<{
         key: z.ZodString;
         principal: z.ZodString;
-        kind: z.ZodEnum<{
-            anonymous: "anonymous";
-            authenticated: "authenticated";
-        }>;
-        intent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"authenticated">;
         createdAt: z.ZodString;
     }, z.core.$strict>>;
     /** Settled creation receipt identity retained for invocations that began before its commit. */
     creationReplay: z.ZodOptional<z.ZodObject<{
         key: z.ZodString;
         principal: z.ZodString;
-        kind: z.ZodEnum<{
-            anonymous: "anonymous";
-            authenticated: "authenticated";
-        }>;
-        intent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"authenticated">;
         createdAt: z.ZodString;
     }, z.core.$strict>>;
     /** Random replay capability reserved before consuming a claim credential. */
@@ -127,10 +124,7 @@ export declare function localSpaceStateDir(root: string): string;
 export declare function localSpaceStatePath(root: string): string;
 export declare function localSpaceLinkPath(root: string): string;
 export declare function readLocalSpaceLink(root: string): Promise<LocalSpaceLink | null>;
-/**
- * Like readLocalSpaceLink, but reports WHICH file matched — callers surface the
- * legacy `.stattic/space.json` path to users so migrations stay visible.
- */
+/** Like readLocalSpaceLink, but reports the file path alongside the link. */
 export declare function readLocalSpaceLinkWithPath(root: string): Promise<{
     link: LocalSpaceLink;
     path: string;
@@ -151,7 +145,6 @@ export declare function mutateLocalSpaceState(root: string, mutate: (current: Lo
     /** Fault-injection observer used to synchronize concurrency tests. */
     onConflict?: (() => void | Promise<void>) | undefined;
 }): Promise<LocalSpaceStateFile>;
-export declare function writeLocalSpaceState(root: string, state: LocalSpaceStateWrite): Promise<string>;
 /** Reserve random replay custody before a claim token can be consumed. */
 export declare function reserveLocalCredentialReplay(root: string, input: {
     operation: LocalCredentialReplayOperation;

package/dist/utils/local-space-state.js

@@ -5,7 +5,6 @@ import { z } from "zod";
 import { createOneShotReplayIdentity } from "./one-shot-replay.js";
 import { SecureLocalFileConflictError, secureReadFile, secureWriteFile, } from "./secure-local-file.js";
 export const LOCAL_SPACE_STATE_DIR_NAME = ".spacefast";
-export const LEGACY_LOCAL_SPACE_STATE_DIR_NAME = ".stattic";
 export const LOCAL_SPACE_LINK_FILE_NAME = "space.json";
 export const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
 /**
@@ -30,6 +29,17 @@ export const localSpaceLinkSchema = z
 })
     .loose();
 export const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
+// One reservation, two slots: it is written as `pendingPublish` and moved to
+// `creationReplay` once its receipt commits. Space creation is the only
+// mutation that reserves one — credential-free publishes are not idempotent.
+export const creationAttemptSchema = z
+    .object({
+    key: z.string().min(1),
+    principal: z.string().regex(/^[0-9a-f]{64}$/),
+    kind: z.literal("authenticated"),
+    createdAt: z.string().datetime(),
+})
+    .strict();
 export const localSpaceStateSchema = z.strictObject({
     schemaVersion: z.literal(LOCAL_SPACE_STATE_SCHEMA_VERSION),
     spaceId: z.string().min(1).optional(),
@@ -46,27 +56,9 @@ export const localSpaceStateSchema = z.strictObject({
     /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
     anonymousPublishNonce: z.string().min(32).optional(),
     /** Unsettled first-publish mutation. Retries must reuse this exact key. */
-    pendingPublish: z
-        .object({
-        key: z.string().min(1),
-        principal: z.string().regex(/^[0-9a-f]{64}$/),
-        kind: z.enum(["anonymous", "authenticated"]),
-        intent: z.string().min(1).optional(),
-        createdAt: z.string().datetime(),
-    })
-        .strict()
-        .optional(),
+    pendingPublish: creationAttemptSchema.optional(),
     /** Settled creation receipt identity retained for invocations that began before its commit. */
-    creationReplay: z
-        .object({
-        key: z.string().min(1),
-        principal: z.string().regex(/^[0-9a-f]{64}$/),
-        kind: z.enum(["anonymous", "authenticated"]),
-        intent: z.string().min(1).optional(),
-        createdAt: z.string().datetime(),
-    })
-        .strict()
-        .optional(),
+    creationReplay: creationAttemptSchema.optional(),
     /** Random replay capability reserved before consuming a claim credential. */
     pendingCredentialReplay: z
         .object({
@@ -99,9 +91,6 @@ export function localSpaceStatePath(root) {
 export function localSpaceLinkPath(root) {
     return path.join(localSpaceStateDir(root), LOCAL_SPACE_LINK_FILE_NAME);
 }
-function legacyLinkPath(root) {
-    return path.join(root, LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME);
-}
 async function readJsonFileWithRaw(root, relativePath) {
     const raw = await secureReadFile({ root, relativePath, encoding: "utf8" }).catch((error) => {
         if (error.code === "ENOENT")
@@ -156,28 +145,17 @@ function linkSpaceId(link) {
 export async function readLocalSpaceLink(root) {
     return (await readLocalSpaceLinkWithPath(root))?.link ?? null;
 }
-/**
- * Like readLocalSpaceLink, but reports WHICH file matched — callers surface the
- * legacy `.stattic/space.json` path to users so migrations stay visible.
- */
+/** Like readLocalSpaceLink, but reports the file path alongside the link. */
 export async function readLocalSpaceLinkWithPath(root) {
     const primary = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
-    if (primary) {
-        return { link: primary, path: localSpaceLinkPath(root) };
-    }
-    const legacy = parseLink(await readJsonFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
-    return legacy ? { link: legacy, path: legacyLinkPath(root) } : null;
+    return primary ? { link: primary, path: localSpaceLinkPath(root) } : null;
 }
 export async function readLocalSpaceStateAt(root) {
     const statePath = localSpaceStatePath(root);
     const primaryState = await readStateFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
-    const legacyState = primaryState
-        ? undefined
-        : await readStateFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
-    const state = primaryState?.state ?? legacyState?.state ?? null;
+    const state = primaryState?.state ?? null;
     const linkPath = localSpaceLinkPath(root);
-    const link = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME))) ??
-        parseLink(await readJsonFile(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
+    const link = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
     if (!state && !link)
         return null;
     const committedSpaceId = linkSpaceId(link);
@@ -334,11 +312,7 @@ export async function mutateLocalSpaceState(root, mutate, options = {}) {
     /* eslint-disable no-await-in-loop -- compare-and-swap retries are intentionally serialized against the latest committed state. */
     for (let attempt = 1; attempt <= LOCAL_STATE_MUTATION_ATTEMPTS; attempt += 1) {
         try {
-            const primaryState = await readJsonFileWithRaw(root, stateRelativePath);
-            const legacyState = primaryState
-                ? undefined
-                : await readJsonFileWithRaw(root, path.join(LEGACY_LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME));
-            const source = primaryState ?? legacyState;
+            const source = await readJsonFileWithRaw(root, stateRelativePath);
             const parsed = source ? localSpaceStateSchema.safeParse(source.value) : null;
             if (source && !parsed?.success) {
                 throw new Error(`Local Spacefast state at ${localSpaceStatePath(root)} is invalid.`);
@@ -353,14 +327,14 @@ export async function mutateLocalSpaceState(root, mutate, options = {}) {
                 schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION,
             });
             const serialized = `${JSON.stringify(payload, null, 2)}\n`;
-            if (primaryState?.raw === serialized)
+            if (source?.raw === serialized)
                 return payload;
             await writeJsonAtomic({
                 root,
                 relativePath: stateRelativePath,
                 value: payload,
                 mode: 0o600,
-                expectedContent: primaryState?.raw ?? null,
+                expectedContent: source?.raw ?? null,
                 ...(options.beforeCommit ? { beforeCommit: options.beforeCommit } : {}),
                 ...(options.afterBackup ? { afterBackup: options.afterBackup } : {}),
             });
@@ -379,10 +353,6 @@ export async function mutateLocalSpaceState(root, mutate, options = {}) {
     /* eslint-enable no-await-in-loop */
     throw new LocalSpaceStateConflictError("Local Spacefast state stayed busy for too long.");
 }
-export async function writeLocalSpaceState(root, state) {
-    await mutateLocalSpaceState(root, () => state);
-    return localSpaceStatePath(root);
-}
 function credentialFingerprint(credential) {
     return createHash("sha256").update(credential).digest("hex");
 }

package/dist/utils/one-shot-replay.d.ts

@@ -11,4 +11,7 @@ export type OneShotReplayIdentity = {
  */
 export declare function createOneShotReplayIdentity(prefix: string): OneShotReplayIdentity;
 /** Production headers for one one-shot attempt (or one device-poll sequence). */
-export declare function oneShotReplayHeaders(identity: OneShotReplayIdentity, sequence?: number): Record<"idempotency-key" | "x-spacefast-idempotency-principal", string>;
+export declare function oneShotReplayHeaders(identity: OneShotReplayIdentity, sequence?: number): {
+    "idempotency-key": string;
+    "x-spacefast-idempotency-principal": string;
+};

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

@@ -1,17 +1,19 @@
 import type { SpacePageTheme } from "../contracts/space-config.js";
-/** Default page palette (mirrored into the shared template CSS). */
+/** Default page palette (mirrored into the shared template CSS) — the
+ * printed-matter scheme: warm canvas, ink type, marker accent (always a
+ * ground with ink on top; the link derivation handles its text-grade). */
 export declare const PAGE_COLOR_DEFAULTS: {
-    readonly accent: "#ff4217";
-    readonly bg: "#f9f8f4";
-    readonly fg: "#1a1913";
-    readonly muted: "#6f6b62";
-    readonly card: "#f9f8f4";
-    readonly border: "#ddd9cf";
-    readonly darkBg: "#141313";
-    readonly darkFg: "#e9e7e2";
-    readonly darkMuted: "#8f8b84";
-    readonly darkCard: "#141313";
-    readonly darkBorder: "#2b2a27";
+    readonly accent: "#d8f24b";
+    readonly bg: "#f7f5ef";
+    readonly fg: "#0c0c0c";
+    readonly muted: "#6e6a5e";
+    readonly card: "#f7f5ef";
+    readonly border: "#e5e1d4";
+    readonly darkBg: "#0c0c0c";
+    readonly darkFg: "#f0eee6";
+    readonly darkMuted: "#a6a193";
+    readonly darkCard: "#0c0c0c";
+    readonly darkBorder: "#2b2823";
 };
 export type PageSchemeColors = {
     bg: string;

package/dist/utils/page-colors.js

@@ -18,19 +18,21 @@
 // Everything is pure and deterministic: publish finalize, dashboard previews,
 // and tests all call the same functions and get the same pixels.
 import { formatHex, oklch, parse, wcagContrast } from "culori";
-/** Default page palette (mirrored into the shared template CSS). */
+/** Default page palette (mirrored into the shared template CSS) — the
+ * printed-matter scheme: warm canvas, ink type, marker accent (always a
+ * ground with ink on top; the link derivation handles its text-grade). */
 export const PAGE_COLOR_DEFAULTS = {
-    accent: "#ff4217",
-    bg: "#f9f8f4",
-    fg: "#1a1913",
-    muted: "#6f6b62",
-    card: "#f9f8f4",
-    border: "#ddd9cf",
-    darkBg: "#141313",
-    darkFg: "#e9e7e2",
-    darkMuted: "#8f8b84",
-    darkCard: "#141313",
-    darkBorder: "#2b2a27",
+    accent: "#d8f24b",
+    bg: "#f7f5ef",
+    fg: "#0c0c0c",
+    muted: "#6e6a5e",
+    card: "#f7f5ef",
+    border: "#e5e1d4",
+    darkBg: "#0c0c0c",
+    darkFg: "#f0eee6",
+    darkMuted: "#a6a193",
+    darkCard: "#0c0c0c",
+    darkBorder: "#2b2823",
 };
 /** WCAG AA for body-size text. */
 const TEXT_CONTRAST = 4.5;
@@ -139,7 +141,7 @@ function schemeFromBackground(background) {
 /** The one entry point: raw theme in, everything the templates paint with out. */
 export function derivePageColors(theme) {
     const accentInput = theme.accent?.trim();
-    const accent = safeParse(accentInput) ? accentInput : PAGE_COLOR_DEFAULTS.accent;
+    const accent = accentInput && safeParse(accentInput) ? accentInput : PAGE_COLOR_DEFAULTS.accent;
     const onAccent = onAccentColor(accent);
     const background = theme.background?.trim();
     if (background && safeParse(background)) {