@spacefast/common 0.0.5 → 0.0.7

package/dist/utils/{access-policy.js → credential-policy.js}

@@ -1,5 +1,5 @@
 import { SPACEFAST_ACCESS_POLICY_VERSION, parseStatticResource, } from "../contracts/api-keys.js";
-const publishActions = [
+export const publishActions = [
     "spaces:read",
     "spaces:create",
     "spaces:write",
@@ -35,6 +35,9 @@ const domainActions = [
 function teamResource(input) {
     return `stt://tenant/${input.tenantId}/principal/team/${input.teamId}/*`;
 }
+function spaceResource(input) {
+    return `stt://tenant/${input.tenantId}/space/${input.spaceId}`;
+}
 export function compileApiKeyPreset(preset, input) {
     const resource = teamResource(input);
     switch (preset) {
@@ -88,6 +91,9 @@ export function compileTeamRolePolicy(input) {
             return denyAllPolicy();
     }
 }
+export function compileSpaceContinuationPolicy(input) {
+    return allowPolicy(publishActions.filter((action) => action !== "spaces:create"), [spaceResource(input)]);
+}
 export function allowPolicy(actions, resources) {
     return {
         version: SPACEFAST_ACCESS_POLICY_VERSION,
@@ -145,6 +151,7 @@ export function grantedTenantsFromPolicy(policy) {
 // Used to scope list queries; specific actions still go through `policyAllows`.
 export function grantedPrincipalsFromPolicy(policy, input) {
     const principalIds = new Set();
+    const spaceIds = new Set();
     let all = false;
     for (const statement of policy.statements) {
         if (statement.effect !== "allow") {
@@ -169,9 +176,28 @@ export function grantedPrincipalsFromPolicy(policy, input) {
                     principalIds.add(parsed.principalId);
                 }
             }
+            else if (parsed.kind === "space") {
+                spaceIds.add(parsed.spaceId);
+            }
         }
     }
-    return { all, principalIds: [...principalIds] };
+    return {
+        all,
+        principalIds: [...principalIds],
+        grants: [
+            ...[...principalIds].map((principalId) => ({
+                kind: "principal",
+                tenantId: input.tenantId,
+                principalType: input.principalType,
+                principalId,
+            })),
+            ...[...spaceIds].map((spaceId) => ({
+                kind: "space",
+                tenantId: input.tenantId,
+                spaceId,
+            })),
+        ],
+    };
 }
 // Whether the policy's allow statements reach a resource subtree at all —
 // either a statement resource covers the base, or it lives inside the base.

package/dist/utils/email.d.ts

@@ -0,0 +1 @@
+export declare function canonicalizeEmail(value: string): string;

package/dist/utils/email.js

@@ -0,0 +1,3 @@
+export function canonicalizeEmail(value) {
+    return value.trim().toLowerCase().normalize("NFC");
+}

package/dist/utils/gate-theme.d.ts

@@ -0,0 +1,61 @@
+import { type SpacePagesTheme } from "../contracts/space-config.js";
+export type GateThemeDiagnostic = {
+    severity: "info" | "warning" | "error";
+    code: string;
+    message: string;
+    path?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+};
+/** Bound on the raw `theme.json` / `sf.theme.jsonc` file size at finalize. */
+export declare const GATE_THEME_FILE_MAX_BYTES: number;
+/** Bound on the compiled additive CSS custom-property block. */
+export declare const GATE_THEME_VARS_MAX_BYTES: number;
+export type ParsedThemeJson = {
+    /** Gate-page tokens derivable from named palette slugs (accent/primary/background). */
+    theme: Partial<SpacePagesTheme>;
+    /** `--wp--preset--color--{slug}` / `--wp--preset--font-family--{slug}` declarations. */
+    themeVars: string | null;
+    diagnostics: GateThemeDiagnostic[];
+};
+/**
+ * Parses a `theme.json` file's `settings.color.palette` /
+ * `settings.typography.fontFamilies` into gate-page tokens (accent/background
+ * derived from conventionally-named slugs: `accent`|`primary`, `background`)
+ * plus a full CSS custom-property block for every safe palette/font-family
+ * entry. Any problem (oversized, invalid JSON, invalid shape) warns and
+ * yields an empty result — the next tier down still applies.
+ */
+export declare function parseThemeJsonFile(raw: string): ParsedThemeJson;
+export type ParsedSfThemeJsonc = {
+    theme: Partial<SpacePagesTheme>;
+    diagnostics: GateThemeDiagnostic[];
+};
+/**
+ * Parses the `sf.theme.jsonc` escape hatch: same JSONC tolerance and the same
+ * validated token grammar as `spacefast.jsonc "pages.theme"`
+ * (`spacePagesThemeSchema`), just from a dedicated file. Any problem warns
+ * and yields an empty result.
+ */
+export declare function parseSfThemeJsonc(raw: string): ParsedSfThemeJsonc;
+export type CompiledGateTheme = {
+    /** Merged accent/background/logo/name/fontFamily; empty object when every tier is unset. */
+    theme: Partial<SpacePagesTheme>;
+    /** Additive `--wp--preset--*` declarations from theme.json (advanced surface for custom pages). */
+    themeVars: string | null;
+    diagnostics: GateThemeDiagnostic[];
+};
+/**
+ * Compiles the full tier-3 cascade into the flat token shape the runtime
+ * already reads. `base` is the existing free-tier `spacefast.jsonc
+ * "pages.theme"` (already validated by `spaceConfigSchema` upstream — passed
+ * through as-is). `sf.theme.jsonc` only applies when `advancedThemingEntitled`
+ * is true; when it is present but NOT entitled, the tier is skipped with an
+ * info diagnostic (fail-safe by omission — the compiled artifact simply
+ * reflects the lower, entitled tiers, per access-plan §9).
+ */
+export declare function mergeGateTheme(input: {
+    base: SpacePagesTheme | null;
+    themeJsonRaw: string | null;
+    sfThemeJsoncRaw: string | null;
+    advancedThemingEntitled: boolean;
+}): CompiledGateTheme;

package/dist/utils/gate-theme.js

@@ -0,0 +1,217 @@
+import { sfThemeJsoncSchema } from "../contracts/space-config.js";
+import { themeJsonSchema } from "../contracts/theme-json.js";
+import { stripJsonComments } from "./space-config.js";
+import { isSafeThemeColor, isSafeThemeFontFamily } from "./space-theme.js";
+/** Bound on the raw `theme.json` / `sf.theme.jsonc` file size at finalize. */
+export const GATE_THEME_FILE_MAX_BYTES = 64 * 1024;
+/** Bound on the compiled additive CSS custom-property block. */
+export const GATE_THEME_VARS_MAX_BYTES = 8 * 1024;
+/**
+ * Parses a `theme.json` file's `settings.color.palette` /
+ * `settings.typography.fontFamilies` into gate-page tokens (accent/background
+ * derived from conventionally-named slugs: `accent`|`primary`, `background`)
+ * plus a full CSS custom-property block for every safe palette/font-family
+ * entry. Any problem (oversized, invalid JSON, invalid shape) warns and
+ * yields an empty result — the next tier down still applies.
+ */
+export function parseThemeJsonFile(raw) {
+    const empty = { theme: {}, themeVars: null, diagnostics: [] };
+    if (Buffer.byteLength(raw) > GATE_THEME_FILE_MAX_BYTES) {
+        return {
+            ...empty,
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "theme_json_too_large",
+                    message: `theme.json exceeds the ${GATE_THEME_FILE_MAX_BYTES} byte limit and was ignored.`,
+                    path: "theme.json",
+                },
+            ],
+        };
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ...empty,
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "theme_json_invalid",
+                    message: `theme.json is not valid JSON: ${error instanceof Error ? error.message : "parse error"}.`,
+                    path: "theme.json",
+                },
+            ],
+        };
+    }
+    const parsed = themeJsonSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return {
+            ...empty,
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "theme_json_invalid",
+                    message: "theme.json does not match the supported settings.color.palette/settings.typography.fontFamilies shape.",
+                    path: "theme.json",
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const declarations = [];
+    const theme = {};
+    const palette = parsed.data.settings?.color?.palette ?? [];
+    for (const entry of palette) {
+        if (!isSafeThemeColor(entry.color)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "theme_json_value_invalid",
+                message: `theme.json settings.color.palette[slug=${entry.slug}] is not a safe color and was dropped.`,
+                path: `theme.json:settings.color.palette.${entry.slug}`,
+            });
+            continue;
+        }
+        declarations.push(`--wp--preset--color--${entry.slug}:${entry.color.trim()}`);
+        if (entry.slug === "accent" || entry.slug === "primary") {
+            theme.accent ??= entry.color.trim();
+        }
+        if (entry.slug === "background") {
+            theme.background = entry.color.trim();
+        }
+    }
+    const fontFamilies = parsed.data.settings?.typography?.fontFamilies ?? [];
+    fontFamilies.forEach((entry, index) => {
+        if (!isSafeThemeFontFamily(entry.fontFamily)) {
+            diagnostics.push({
+                severity: "warning",
+                code: "theme_json_value_invalid",
+                message: `theme.json settings.typography.fontFamilies[slug=${entry.slug}] is not a safe font-family stack and was dropped.`,
+                path: `theme.json:settings.typography.fontFamilies.${entry.slug}`,
+            });
+            return;
+        }
+        declarations.push(`--wp--preset--font-family--${entry.slug}:${entry.fontFamily.trim()}`);
+        if (index === 0) {
+            theme.fontFamily ??= entry.fontFamily.trim();
+        }
+    });
+    let themeVars = declarations.join(";");
+    while (Buffer.byteLength(themeVars) > GATE_THEME_VARS_MAX_BYTES && declarations.length > 0) {
+        declarations.pop();
+        diagnostics.push({
+            severity: "warning",
+            code: "theme_json_value_invalid",
+            message: `theme.json compiled CSS exceeds ${GATE_THEME_VARS_MAX_BYTES} bytes; trailing tokens were dropped.`,
+            path: "theme.json",
+        });
+        themeVars = declarations.join(";");
+    }
+    return {
+        theme,
+        themeVars: themeVars.length > 0 ? themeVars : null,
+        diagnostics,
+    };
+}
+/**
+ * Parses the `sf.theme.jsonc` escape hatch: same JSONC tolerance and the same
+ * validated token grammar as `spacefast.jsonc "pages.theme"`
+ * (`spacePagesThemeSchema`), just from a dedicated file. Any problem warns
+ * and yields an empty result.
+ */
+export function parseSfThemeJsonc(raw) {
+    if (Buffer.byteLength(raw) > GATE_THEME_FILE_MAX_BYTES) {
+        return {
+            theme: {},
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "sf_theme_jsonc_too_large",
+                    message: `sf.theme.jsonc exceeds the ${GATE_THEME_FILE_MAX_BYTES} byte limit and was ignored.`,
+                    path: "sf.theme.jsonc",
+                },
+            ],
+        };
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(stripJsonComments(raw));
+    }
+    catch (error) {
+        return {
+            theme: {},
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "sf_theme_jsonc_invalid",
+                    message: `sf.theme.jsonc is not valid JSONC: ${error instanceof Error ? error.message : "parse error"}.`,
+                    path: "sf.theme.jsonc",
+                },
+            ],
+        };
+    }
+    const parsed = sfThemeJsoncSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return {
+            theme: {},
+            diagnostics: [
+                {
+                    severity: "warning",
+                    code: "sf_theme_jsonc_invalid",
+                    message: "sf.theme.jsonc does not match the gate-page theme token shape.",
+                    path: "sf.theme.jsonc",
+                },
+            ],
+        };
+    }
+    return { theme: parsed.data, diagnostics: [] };
+}
+function pickDefined(target, source) {
+    for (const key of ["accent", "background", "logo", "name", "fontFamily"]) {
+        const value = source[key];
+        if (value !== undefined) {
+            target[key] = value;
+        }
+    }
+}
+/**
+ * Compiles the full tier-3 cascade into the flat token shape the runtime
+ * already reads. `base` is the existing free-tier `spacefast.jsonc
+ * "pages.theme"` (already validated by `spaceConfigSchema` upstream — passed
+ * through as-is). `sf.theme.jsonc` only applies when `advancedThemingEntitled`
+ * is true; when it is present but NOT entitled, the tier is skipped with an
+ * info diagnostic (fail-safe by omission — the compiled artifact simply
+ * reflects the lower, entitled tiers, per access-plan §9).
+ */
+export function mergeGateTheme(input) {
+    const diagnostics = [];
+    const merged = {};
+    if (input.base) {
+        pickDefined(merged, input.base);
+    }
+    let themeVars = null;
+    if (input.themeJsonRaw !== null) {
+        const parsed = parseThemeJsonFile(input.themeJsonRaw);
+        diagnostics.push(...parsed.diagnostics);
+        pickDefined(merged, parsed.theme);
+        themeVars = parsed.themeVars;
+    }
+    if (input.sfThemeJsoncRaw !== null) {
+        if (!input.advancedThemingEntitled) {
+            diagnostics.push({
+                severity: "info",
+                code: "sf_theme_jsonc_not_entitled",
+                message: "sf.theme.jsonc is a paid (advanced theming) tier; this plan is not entitled, so it was ignored.",
+                path: "sf.theme.jsonc",
+            });
+        }
+        else {
+            const parsed = parseSfThemeJsonc(input.sfThemeJsoncRaw);
+            diagnostics.push(...parsed.diagnostics);
+            pickDefined(merged, parsed.theme);
+        }
+    }
+    return { theme: merged, themeVars, diagnostics };
+}

package/dist/utils/git-repository.d.ts

@@ -1,5 +1,4 @@
 export type GitRepositoryProvider = "github" | "gitlab" | "bitbucket" | "git";
-export declare function isGitRepositoryRemote(value: string): boolean;
 export declare function gitProviderFromRepositoryRemote(value: string): GitRepositoryProvider;
 export declare function repositoryFullNameFromGitRemote(value: string): string | null;
 export declare function safeRepositoryUrlFromGitRemote(value: string): string | null;

package/dist/utils/git-repository.js

@@ -42,9 +42,6 @@ function parseGitRemote(value) {
         return null;
     }
 }
-export function isGitRepositoryRemote(value) {
-    return parseGitRemote(value) !== null;
-}
 export function gitProviderFromRepositoryRemote(value) {
     const hostname = parseGitRemote(value)?.hostname;
     if (!hostname)

package/dist/utils/id-hints.d.ts

@@ -0,0 +1,8 @@
+export declare const HINT_SCAN_CAP = 200;
+export declare const HINT_MAX_CANDIDATES = 5;
+export declare function levenshtein(a: string, b: string): number;
+export declare function refCloseness(needle: string, candidate: string): number;
+export declare function rankCandidates<T>(ref: string, rows: T[], keysOf: (row: T) => Array<string | null | undefined>, options?: {
+    max?: number;
+    tiebreak?: (a: T, b: T) => number;
+}): T[];

package/dist/utils/id-hints.js

@@ -0,0 +1,61 @@
+// Shared not-found self-correction (W1). One source for the closest-candidate
+// ranking used by every resource's 404 hint builder (spaces, versions, teams,
+// domains). Resources differ only in which caller-scoped rows they feed in and
+// which keys they expose for matching; keeping the levenshtein/closeness/ranking
+// here prevents per-resource drift. Callers are responsible for scoping the rows
+// to the caller principal — this module never touches the DB or auth.
+// How many caller-scoped rows a hint builder will scan to rank candidates. Above
+// this the collection is treated as too large to rank for free, so the builder
+// returns only the recovery hint (no candidate ids).
+export const HINT_SCAN_CAP = 200;
+export const HINT_MAX_CANDIDATES = 5;
+export function levenshtein(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let previous = Array.from({ length: cols }, (_, index) => index);
+    for (let i = 1; i < rows; i++) {
+        const current = [i, ...Array.from({ length: cols - 1 }, () => 0)];
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+        }
+        previous = current;
+    }
+    return previous[cols - 1] ?? 0;
+}
+// Returns a small finite score the closer `candidate` is to `needle`, or
+// +Infinity when they are not genuinely close. Exact match = 0; substring
+// containment = 1; otherwise a typo within a length-bounded edit distance.
+export function refCloseness(needle, candidate) {
+    if (!candidate)
+        return Number.POSITIVE_INFINITY;
+    if (candidate === needle)
+        return 0;
+    if (candidate.includes(needle) || needle.includes(candidate))
+        return 1;
+    const distance = levenshtein(needle, candidate);
+    // Only surface genuinely close typos: bound the allowed distance by the shorter
+    // string so short refs don't match everything.
+    const tolerance = Math.max(2, Math.floor(Math.min(needle.length, candidate.length) / 3));
+    return distance <= tolerance ? 1 + distance : Number.POSITIVE_INFINITY;
+}
+// Rank `rows` by how close any of their keys are to `ref`, returning at most
+// `max` closest rows. A row whose every key is far (or absent) is dropped, so
+// only genuine near-matches surface. Ties break by the optional comparator
+// (e.g. recency); keys are matched case-insensitively.
+export function rankCandidates(ref, rows, keysOf, options) {
+    const needle = ref.toLowerCase();
+    const max = options?.max ?? HINT_MAX_CANDIDATES;
+    return rows
+        .map((row) => {
+        const scores = keysOf(row).map((key) => key ? refCloseness(needle, key.toLowerCase()) : Number.POSITIVE_INFINITY);
+        return {
+            row,
+            score: scores.length > 0 ? Math.min(...scores) : Number.POSITIVE_INFINITY,
+        };
+    })
+        .filter((entry) => entry.score < Number.POSITIVE_INFINITY)
+        .toSorted((left, right) => left.score - right.score || (options?.tiebreak ? options.tiebreak(left.row, right.row) : 0))
+        .slice(0, max)
+        .map((entry) => entry.row);
+}

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

@@ -0,0 +1,91 @@
+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";
+/**
+ * Local Spacefast checkout contract.
+ *
+ * `.spacefast/space.json` is the committable selection axis: it names which
+ * space a checkout targets (`space`) and may carry non-secret provider/team
+ * coordinates (`team`, `apiBaseUrl`). It must not carry credentials.
+ *
+ * `.spacefast/state.json` is the local credential/cache axis: it records the
+ * resolved `spaceId`, provider `apiUrl`, anonymous `claimToken` before claim,
+ * durable `accessToken` after continuation, and small publish caches such as
+ * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written
+ * so newer tools preserve unknown fields from older/newer tools.
+ */
+export declare const localSpaceLinkSchema: z.ZodObject<{
+    team: z.ZodOptional<z.ZodString>;
+    space: z.ZodString;
+    apiBaseUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const localSpaceStateSchema: z.ZodObject<{
+    spaceId: z.ZodOptional<z.ZodString>;
+    apiUrl: z.ZodOptional<z.ZodString>;
+    teamSlug: z.ZodOptional<z.ZodString>;
+    claimToken: z.ZodOptional<z.ZodString>;
+    claimUrl: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    accessToken: z.ZodOptional<z.ZodString>;
+    lastVersionId: z.ZodOptional<z.ZodString>;
+    lastVersionUrl: z.ZodOptional<z.ZodString>;
+    lastSpaceUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type LocalSpaceLink = z.infer<typeof localSpaceLinkSchema>;
+export type LocalSpaceStateFile = z.infer<typeof localSpaceStateSchema>;
+export type DiscoveredLocalSpaceState = {
+    root: string;
+    statePath: string | null;
+    linkPath: string | null;
+    link: LocalSpaceLink | null;
+    state: LocalSpaceStateFile | null;
+    spaceId: string | undefined;
+    claimToken: string | undefined;
+    accessToken: string | undefined;
+    apiUrl: string | undefined;
+    claimUrl: string | undefined;
+    expiresAt: string | undefined;
+    lastVersionId: string | undefined;
+};
+export type SaveLocalSpaceStateInput = {
+    spaceId: string;
+    apiUrl: string;
+    teamSlug?: string | undefined;
+    claimToken?: string | undefined;
+    claimUrl?: string | undefined;
+    expiresAt?: string | undefined;
+    accessToken?: string | undefined;
+    lastVersionId?: string | undefined;
+    lastVersionUrl?: string | undefined;
+    lastSpaceUrl?: string | undefined;
+};
+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.
+ */
+export declare function readLocalSpaceLinkWithPath(root: string): Promise<{
+    link: LocalSpaceLink;
+    path: string;
+} | null>;
+export declare function readLocalSpaceStateAt(root: string): Promise<DiscoveredLocalSpaceState | null>;
+/**
+ * Walk up from `startDir` to the filesystem root (or `boundary`, when given),
+ * returning the first non-null result of `probe`. Shared by every "nearest
+ * checkout marker" lookup (state+link discovery here, the CLI's link-only
+ * discovery) so the traversal rules live in one place.
+ */
+export declare function findUpward<T>(probe: (dir: string) => Promise<T | null>, startDir?: string, boundary?: string): Promise<T | null>;
+export declare function discoverLocalSpaceState(startDir?: string, boundary?: string): Promise<DiscoveredLocalSpaceState | null>;
+export declare function writeLocalSpaceLink(root: string, link: LocalSpaceLink): Promise<string>;
+export declare function writeLocalSpaceState(root: string, state: LocalSpaceStateFile): Promise<string>;
+export declare function saveLocalSpaceState(root: string, input: SaveLocalSpaceStateInput): Promise<{
+    statePath: string;
+    linkPath: string;
+    wroteLink: boolean;
+}>;