@spacefast/common 0.0.21 → 0.0.24

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

@@ -28,7 +28,7 @@ function targetMatches(selector, target) {
         case "branch":
             return target.kind === "branch" && target.branch === selector.branch;
         case "all_versions":
-            return target.kind === "version";
+            return target.kind === "live" || target.kind === "version";
     }
     throw new Error("Unsupported Grant target.");
 }
@@ -70,6 +70,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 +143,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";
 /**
@@ -127,10 +126,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;

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";
 /**
@@ -99,9 +98,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 +152,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 +319,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 +334,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 } : {}),
             });