@spacefast/common 0.0.21 → 0.0.24

package/dist/utils/cast-transport.js

@@ -0,0 +1,52 @@
+/**
+ * How a client addresses Cast over Phoenix. Both Spacefast clients — the
+ * dashboard's notice subscription and the injected Collab SDK — build their
+ * socket and their topics here, and nowhere else.
+ */
+/**
+ * `~n` escapes, the inverse of `CastWeb.ApiContext.decode_path_segment/1`.
+ * `~` goes first in intent: the map is applied in one pass, so an already
+ * escaped marker can never be escaped twice.
+ */
+const ESCAPED = new Map([
+    ["~", "~0"],
+    ["/", "~1"],
+    [":", "~2"],
+    ["\\", "~3"],
+    ["%", "~4"],
+    ["\0", "~5"],
+]);
+/**
+ * The Phoenix topic a Cast room's messages travel on.
+ *
+ * Phoenix routes a broadcast by the *literal* topic string. Cast broadcasts
+ * anything computed outside a channel process — Space notices, REST-published
+ * room events — to the topic `Cast.RoomTopic.for/2` builds, so a client that
+ * encodes the room key any other way joins a real and permanently silent room.
+ * Both sides therefore encode exactly once, here and in that module: the `~n`
+ * table first (it survives round-tripping a key that itself contains `~` or
+ * `%`), then `encodeURIComponent`.
+ *
+ * Proven by delivery, not by inspection: `./cast-transport.test.ts` pins the
+ * strings, and on the other side `room_channel_notice_test.exs` and
+ * `spacefast_inbox_fanout_test.exs` join those literal topics and assert a real
+ * Cast broadcast arrives on them.
+ */
+export function castRoomTopic(resourceKey, roomKey) {
+    let escaped = "";
+    for (const character of roomKey)
+        escaped += ESCAPED.get(character) ?? character;
+    return `room:${resourceKey}:${encodeURIComponent(escaped)}`;
+}
+/**
+ * Phoenix's own `Socket` appends `/websocket` to whatever endpoint it is given,
+ * so a configured URL that already carries the suffix would otherwise become
+ * `/websocket/websocket`.
+ */
+export function phoenixEndpoint(url) {
+    const parsed = new URL(url);
+    if (parsed.pathname.endsWith("/websocket")) {
+        parsed.pathname = parsed.pathname.slice(0, -"/websocket".length);
+    }
+    return parsed.href.replace(/\/$/, "");
+}

package/dist/utils/claim-token.d.ts

@@ -1,9 +1 @@
-export type ClaimCredential = {
-    kind: "token";
-    claimToken: string;
-} | {
-    kind: "nonce";
-    nonce: string;
-};
-export declare function classifyClaimCredential(raw: string | null | undefined): ClaimCredential | undefined;
 export declare function normalizeClaimToken(token: string | null | undefined): string | undefined;

package/dist/utils/claim-token.js

@@ -1,18 +1,6 @@
-const LEGACY_WORD_TOKEN_SHAPE = /^[a-z]+(?:-[a-z]+){2,}$/;
-export function classifyClaimCredential(raw) {
-    const trimmed = raw?.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    if (trimmed.startsWith("sfc_")) {
-        return { kind: "token", claimToken: trimmed };
-    }
-    const normalized = normalizeClaimToken(trimmed);
-    if (normalized && LEGACY_WORD_TOKEN_SHAPE.test(normalized)) {
-        return { kind: "token", claimToken: normalized };
-    }
-    return { kind: "nonce", nonce: trimmed };
-}
+// The space key (`sfc_…`, or the legacy five-word form) is the one claim
+// credential; it authenticates as a `Bearer` header and rides claim-link
+// fragments verbatim.
 export function normalizeClaimToken(token) {
     const trimmed = token?.trim();
     if (!trimmed) {

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

@@ -16,7 +16,7 @@ export type PolicyAuthorizeInput = {
     resource: string | readonly string[];
     conditions?: RequestCondition;
 };
-export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:create" | "spaces:publish" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:trigger" | "builds:create")[];
+export declare const publishActions: ("spaces:read" | "spaces:write" | "spaces:publish" | "builds:trigger" | "spaces:create" | "versions:read" | "versions:promote" | "versions:download" | "builds:read" | "builds:create")[];
 export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): ApiCredentialPolicy;
 /** Expand a named API-key preset into the finite permissions sent on the public wire contract. */
 export declare function apiKeyPresetPermissions(preset: ApiKeyPreset): StatticAction[];

package/dist/utils/env-file.d.ts

@@ -0,0 +1,17 @@
+export type ParsedEnvFileEntry = {
+    name: string;
+    value: string;
+    line: number;
+};
+type ValidationErrorFactory = (message: string) => Error;
+export declare function parseEnvFile(content: string, options?: {
+    reservedStatticPrefix?: boolean;
+    validationError?: ValidationErrorFactory;
+}): ParsedEnvFileEntry[];
+export declare function loadEnvFileSource<const File extends string>(root: string, files: readonly File[], options?: {
+    validationError?: ValidationErrorFactory;
+}): Promise<{
+    file: File;
+    content: string;
+} | null>;
+export {};

package/dist/utils/env-file.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { variableNameSchema } from "../contracts/variables.js";
+import { hasErrorCode } from "./error-code.js";
+import { structuredValidationError } from "./structured-error.js";
+const localEnvNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function stripInlineComment(value) {
+    let quoted = null;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quoted) {
+            if (char === "\\" && quoted === '"')
+                index += 1;
+            else if (char === quoted)
+                quoted = null;
+            continue;
+        }
+        if (char === "'" || char === '"')
+            quoted = char;
+        else if (char === "#" && (index === 0 || /\s/.test(value[index - 1] ?? ""))) {
+            return value.slice(0, index).trimEnd();
+        }
+    }
+    return value.trimEnd();
+}
+function unescapeDoubleQuotedValue(value) {
+    return value.replace(/\\([nrt"\\$])/g, (_, escaped) => {
+        if (escaped === "n")
+            return "\n";
+        if (escaped === "r")
+            return "\r";
+        if (escaped === "t")
+            return "\t";
+        return escaped;
+    });
+}
+function parseEnvValue(rawValue, line, error) {
+    const value = stripInlineComment(rawValue.trim());
+    if (value.startsWith('"')) {
+        if (!value.endsWith('"') || value.length === 1) {
+            throw error(`Invalid .env value on line ${line}: missing closing double quote.`);
+        }
+        return unescapeDoubleQuotedValue(value.slice(1, -1));
+    }
+    if (value.startsWith("'")) {
+        if (!value.endsWith("'") || value.length === 1) {
+            throw error(`Invalid .env value on line ${line}: missing closing single quote.`);
+        }
+        return value.slice(1, -1);
+    }
+    return value;
+}
+export function parseEnvFile(content, options = { reservedStatticPrefix: true }) {
+    const error = options.validationError ?? structuredValidationError;
+    const entries = new Map();
+    const lines = content.replace(/^\uFEFF/, "").split(/\r?\n/);
+    for (const [index, rawLine] of lines.entries()) {
+        const line = index + 1;
+        const trimmed = rawLine.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const withoutExport = trimmed.startsWith("export ")
+            ? trimmed.slice("export ".length).trim()
+            : trimmed;
+        const equalsIndex = withoutExport.indexOf("=");
+        if (equalsIndex < 0)
+            throw error(`Invalid .env entry on line ${line}: expected NAME=value.`);
+        const name = withoutExport.slice(0, equalsIndex).trim();
+        const validName = options.reservedStatticPrefix === false
+            ? localEnvNamePattern.test(name)
+            : variableNameSchema.safeParse(name).success;
+        if (!validName)
+            throw error(`Invalid .env variable name on line ${line}: ${name}.`);
+        const value = parseEnvValue(withoutExport.slice(equalsIndex + 1), line, error);
+        if (value.length === 0) {
+            throw error(`Invalid .env value on line ${line}: empty values are not supported yet.`);
+        }
+        entries.set(name, { name, value, line });
+    }
+    return [...entries.values()];
+}
+export async function loadEnvFileSource(root, files, options = {}) {
+    const error = options.validationError ?? structuredValidationError;
+    const candidates = await Promise.all(files.map(async (file) => {
+        const content = await readFile(path.join(root, file), "utf8").catch((reason) => {
+            if (hasErrorCode(reason, "ENOENT"))
+                return null;
+            throw reason;
+        });
+        return content === null ? null : { file, content };
+    }));
+    const present = candidates.filter((candidate) => candidate !== null);
+    if (present.length > 1)
+        throw error(`Use either ${files[0]} or ${files[1]}, not both.`);
+    return present[0] ?? null;
+}

package/dist/utils/error-code.d.ts

@@ -0,0 +1,2 @@
+/** True when `error` carries the given syscall-style `code` (ENOENT, EEXIST, …). */
+export declare function hasErrorCode(error: unknown, code: string): boolean;

package/dist/utils/error-code.js

@@ -0,0 +1,7 @@
+/** True when `error` carries the given syscall-style `code` (ENOENT, EEXIST, …). */
+export function hasErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}

package/dist/utils/generate-space-name.d.ts

@@ -1,14 +1,12 @@
 /**
- * Generates a whimsical, WordPress-flavored space title.
+ * Generates a short, readable space title.
  *
- * The pool mixes WordPress jargon (Codex, Permalink, Gutenberg, Pingback)
- * with engineering/web adjectives so the output reads like a tiny inside
- * joke instead of an auto-increment. Users can rename later, so the only
- * requirement is that two back-to-back calls almost never collide.
+ * The pool mixes a little WordPress and web flavor with broad nature, color,
+ * motion, and craft vocabulary. The result should suit any site instead of
+ * reading like a CMS inside joke, while staying compact enough for a hostname.
  *
- * Pool size: 32 × 32 = 1024 combinations. Combined with the collision
- * handling in `uniqueSpaceSlug`, per-team conflicts are very
- * unlikely. The generator is intentionally dependency-free so it can be
- * shared by the control-plane, the CLI, and any future surface.
+ * The generator is intentionally dependency-free so it can be shared by the
+ * control-plane, dashboard, CLI, and future publishing surfaces.
  */
-export declare function generateSpaceTitle(): string;
+export declare const SPACE_TITLE_COMBINATION_COUNT: number;
+export declare function generateSpaceTitle(random?: () => number): string;

package/dist/utils/generate-space-name.js

@@ -1,15 +1,12 @@
 /**
- * Generates a whimsical, WordPress-flavored space title.
+ * Generates a short, readable space title.
  *
- * The pool mixes WordPress jargon (Codex, Permalink, Gutenberg, Pingback)
- * with engineering/web adjectives so the output reads like a tiny inside
- * joke instead of an auto-increment. Users can rename later, so the only
- * requirement is that two back-to-back calls almost never collide.
+ * The pool mixes a little WordPress and web flavor with broad nature, color,
+ * motion, and craft vocabulary. The result should suit any site instead of
+ * reading like a CMS inside joke, while staying compact enough for a hostname.
  *
- * Pool size: 32 × 32 = 1024 combinations. Combined with the collision
- * handling in `uniqueSpaceSlug`, per-team conflicts are very
- * unlikely. The generator is intentionally dependency-free so it can be
- * shared by the control-plane, the CLI, and any future surface.
+ * The generator is intentionally dependency-free so it can be shared by the
+ * control-plane, dashboard, CLI, and future publishing surfaces.
  */
 const ADJECTIVES = [
     "Atomic",
@@ -44,6 +41,102 @@ const ADJECTIVES = [
     "Templated",
     "Responsive",
     "Trackbacked",
+    "Agile",
+    "Amber",
+    "Ancient",
+    "Arctic",
+    "Azure",
+    "Balanced",
+    "Bold",
+    "Bright",
+    "Brisk",
+    "Calm",
+    "Candid",
+    "Celestial",
+    "Clever",
+    "Coastal",
+    "Composed",
+    "Cosmic",
+    "Crisp",
+    "Curious",
+    "Daring",
+    "Deep",
+    "Electric",
+    "Elegant",
+    "Emerald",
+    "Endless",
+    "Evergreen",
+    "Fluid",
+    "Focused",
+    "Gentle",
+    "Golden",
+    "Grand",
+    "Harmonic",
+    "Hidden",
+    "Honest",
+    "Indigo",
+    "Infinite",
+    "Keen",
+    "Kind",
+    "Lively",
+    "Lucid",
+    "Lunar",
+    "Magnetic",
+    "Mellow",
+    "Modern",
+    "Nimble",
+    "Northern",
+    "Open",
+    "Pacific",
+    "Patient",
+    "Polished",
+    "Prime",
+    "Quiet",
+    "Radiant",
+    "Rapid",
+    "Rare",
+    "Ready",
+    "Regal",
+    "Remote",
+    "Restless",
+    "Robust",
+    "Royal",
+    "Sable",
+    "Silent",
+    "Simple",
+    "Solar",
+    "Steady",
+    "Stellar",
+    "Still",
+    "Swift",
+    "Tactile",
+    "Tidy",
+    "Timeless",
+    "Tranquil",
+    "True",
+    "Vivid",
+    "Warm",
+    "Wild",
+    "Wise",
+    "Woven",
+    "Young",
+    "Zealous",
+    "Airy",
+    "Autumn",
+    "Blue",
+    "Clear",
+    "Copper",
+    "Distant",
+    "Early",
+    "Fresh",
+    "Glowing",
+    "Green",
+    "Light",
+    "Misty",
+    "Neon",
+    "Silver",
+    "Spring",
+    "Summer",
 ];
 const NOUNS = [
     "Codex",
@@ -78,18 +171,110 @@ const NOUNS = [
     "Gravatar",
     "Reblog",
     "Opengraph",
+    "Acre",
+    "Arcade",
+    "Atlas",
+    "Beacon",
+    "Birch",
+    "Bloom",
+    "Bridge",
+    "Brook",
+    "Canyon",
+    "Cedar",
+    "Circuit",
+    "Cloud",
+    "Coast",
+    "Comet",
+    "Cove",
+    "Creek",
+    "Delta",
+    "Dune",
+    "Echo",
+    "Ember",
+    "Field",
+    "Fjord",
+    "Forest",
+    "Forge",
+    "Garden",
+    "Grove",
+    "Harbor",
+    "Haven",
+    "Hill",
+    "Horizon",
+    "Island",
+    "Junction",
+    "Kite",
+    "Lake",
+    "Lantern",
+    "Meadow",
+    "Mesa",
+    "Moon",
+    "Nest",
+    "Oak",
+    "Ocean",
+    "Orchard",
+    "Peak",
+    "Pine",
+    "Plain",
+    "Pond",
+    "Prairie",
+    "Prism",
+    "Reef",
+    "Ridge",
+    "River",
+    "Road",
+    "Rock",
+    "Sage",
+    "Shore",
+    "Signal",
+    "Sky",
+    "Spark",
+    "Star",
+    "Stone",
+    "Studio",
+    "Summit",
+    "Sun",
+    "Trail",
+    "Vale",
+    "Valley",
+    "Vault",
+    "Wave",
+    "Willow",
+    "Wind",
+    "Window",
+    "Wood",
+    "Bay",
+    "Branch",
+    "Breeze",
+    "Canvas",
+    "Castle",
+    "Cavern",
+    "Cliff",
+    "Dawn",
+    "Drift",
+    "Falcon",
+    "Flame",
+    "Glade",
+    "Harborlight",
+    "Loom",
+    "Maple",
+    "Marsh",
+    "North",
+    "Pebble",
+    "Quartz",
+    "Rain",
+    "Range",
+    "Terrace",
+    "Thicket",
+    "Wren",
 ];
-function pickRandom(list) {
-    if (list.length === 0) {
-        throw new Error("generateSpaceName: word list is empty.");
+export const SPACE_TITLE_COMBINATION_COUNT = ADJECTIVES.length * NOUNS.length;
+export function generateSpaceTitle(random = Math.random) {
+    const index = Math.floor(random() * SPACE_TITLE_COMBINATION_COUNT);
+    const adjective = ADJECTIVES[Math.floor(index / NOUNS.length)];
+    const noun = NOUNS[index % NOUNS.length];
+    if (!adjective || !noun) {
+        throw new Error("generateSpaceName: random source must return a value from 0 up to 1.");
     }
-    const index = Math.floor(Math.random() * list.length);
-    const value = list[index];
-    if (value === undefined) {
-        throw new Error("generateSpaceName: word list contained a hole.");
-    }
-    return value;
-}
-export function generateSpaceTitle() {
-    return `${pickRandom(ADJECTIVES)} ${pickRandom(NOUNS)}`;
+    return `${adjective} ${noun}`;
 }