@spacefast/common 0.0.23 → 0.0.26

package/dist/utils/credential-policy.js

@@ -141,7 +141,7 @@ export function policyIsSubsetOfGrantor(requested, grantor) {
         return statement.actions.every((action) => statement.resources.every((resource) => grantorAllows(grantor, action, resource, statement.conditions)));
     }) && grantorDeniesArePreserved(requested, grantor));
 }
-// Request-time evaluation (internal-docs/platform.md IAM-lite): explicit deny wins,
+// Request-time evaluation (the platform spec IAM-lite): explicit deny wins,
 // explicit allow permits, otherwise implicit deny. Condition keys are ANDed and an
 // unresolvable condition attribute fails closed (see `conditionsMatch`).
 export function policyAllows(input) {
@@ -152,7 +152,7 @@ export function policyAllows(input) {
     return resources.some((resource) => matchesEffect(input.policy, "allow", input.action, resource, input.conditions, "request"));
 }
 // The tenants a credential's policy grants any access to. Drives tenant
-// selection (internal-docs/platform.md Tenant): `X-Spacefast-Tenant-Id` may pick
+// selection (the platform spec Tenant): `X-Spacefast-Tenant-Id` may pick
 // one granted tenant but is never an authority by itself, and a token spanning
 // multiple tenants must fail ambiguous requests with `tenant_selection_required`.
 export function grantedTenantsFromPolicy(policy) {
@@ -259,7 +259,7 @@ function resourceMatches(pattern, resource) {
     if (pattern.endsWith("/*")) {
         return resource === pattern.slice(0, -2) || resource.startsWith(pattern.slice(0, -1));
     }
-    // A tenant-rooted resource is scope-wide (internal-docs/platform.md L617/L879:
+    // A tenant-rooted resource is scope-wide (the platform spec:
     // `stt://tenant/{t}` is a grantable StatticResource and resource grants cover
     // their subtree): it covers every resource inside that tenant. This is the
     // tenant-scoped (partner/agency) credential shape.
@@ -273,6 +273,7 @@ function conditionsMatch(statementConditions, contextConditions, effect, mode) {
         return true;
     }
     return Object.entries(statementConditions).every(([key, value]) => {
+        // SAFETY: Object.entries obtains key from the named RequestCondition object immediately above.
         const resolved = contextConditions?.[key];
         if (resolved === undefined && mode === "request") {
             // Fail closed on unresolvable condition attributes: the condition never

package/dist/utils/dns-instructions.js

@@ -15,15 +15,15 @@ export function addressDnsInstructionsForHostname(input) {
             normalizeDnsName(instruction.name) !== hostname) {
             return [];
         }
-        return [
-            {
-                type: instruction.type,
-                name: instruction.name,
-                value: instruction.value,
-                purpose: instruction.purpose,
-                ...(instruction.ttl === undefined ? {} : { ttl: instruction.ttl }),
-            },
-        ];
+        const result = {
+            type: instruction.type,
+            name: instruction.name,
+            value: instruction.value,
+            purpose: instruction.purpose,
+        };
+        if (instruction.ttl !== undefined)
+            result.ttl = instruction.ttl;
+        return [result];
     });
 }
 function normalizeAddress(value) {

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,8 @@
+/** 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 &&
+        // SAFETY: The preceding checks prove error is a non-null object with a code property.
+        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}`;
 }