@spacefast/common 0.0.6 → 0.0.8

package/dist/utils/sf-config-v1.js

@@ -0,0 +1,542 @@
+import { SF_CONFIG_V1_SCHEMA_URL, } from "../contracts/sf-config-v1.js";
+import { SPACE_CONFIG_CAPS } from "../contracts/space-config.js";
+class JsoncReader {
+    source;
+    offset = 0;
+    keyOffsets = new Map();
+    constructor(source) {
+        this.source = source;
+    }
+    read() {
+        const result = this.value("$");
+        this.trivia();
+        if (this.offset !== this.source.length)
+            this.fail("Unexpected content");
+        return result;
+    }
+    value(jsonPath) {
+        this.trivia();
+        const char = this.source[this.offset];
+        if (char === "{")
+            return this.object(jsonPath);
+        if (char === "[")
+            return this.array(jsonPath);
+        if (char === '"')
+            return this.string();
+        const token = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(this.source.slice(this.offset))?.[0];
+        if (!token)
+            this.fail("Expected a JSON value");
+        this.offset += token.length;
+        return JSON.parse(token);
+    }
+    object(jsonPath) {
+        const result = Object.create(null);
+        const keys = new Set();
+        this.offset++;
+        this.trivia();
+        if (this.source[this.offset] === "}") {
+            this.offset++;
+            return result;
+        }
+        while (true) {
+            this.trivia();
+            const keyOffset = this.offset;
+            if (this.source[this.offset] !== '"')
+                this.fail("Expected an object key");
+            const key = this.string();
+            if (keys.has(key))
+                this.fail(`Duplicate key ${JSON.stringify(key)}`, keyOffset);
+            keys.add(key);
+            const childPath = `${jsonPath}.${key}`;
+            this.keyOffsets.set(childPath, keyOffset);
+            this.trivia();
+            if (this.source[this.offset] !== ":")
+                this.fail("Expected ':' after object key");
+            this.offset++;
+            result[key] = this.value(childPath);
+            this.trivia();
+            const separator = this.source[this.offset];
+            if (separator === "}") {
+                this.offset++;
+                return result;
+            }
+            if (separator !== ",")
+                this.fail("Expected ',' or '}'");
+            this.offset++;
+            this.trivia();
+            if (this.source[this.offset] === "}") {
+                this.offset++;
+                return result;
+            }
+        }
+    }
+    array(jsonPath) {
+        const result = [];
+        this.offset++;
+        this.trivia();
+        if (this.source[this.offset] === "]") {
+            this.offset++;
+            return result;
+        }
+        while (true) {
+            const itemPath = `${jsonPath}[${result.length}]`;
+            this.keyOffsets.set(itemPath, this.offset);
+            result.push(this.value(itemPath));
+            this.trivia();
+            const separator = this.source[this.offset];
+            if (separator === "]") {
+                this.offset++;
+                return result;
+            }
+            if (separator !== ",")
+                this.fail("Expected ',' or ']'");
+            this.offset++;
+            this.trivia();
+            if (this.source[this.offset] === "]") {
+                this.offset++;
+                return result;
+            }
+        }
+    }
+    string() {
+        const start = this.offset;
+        this.offset++;
+        while (this.offset < this.source.length) {
+            const charOffset = this.offset;
+            const char = this.source[this.offset++];
+            if (char === '"')
+                return JSON.parse(this.source.slice(start, this.offset));
+            if (this.source.charCodeAt(charOffset) < 0x20) {
+                this.fail("Unescaped control character in string", charOffset);
+            }
+            if (char !== "\\")
+                continue;
+            const escapeOffset = this.offset;
+            const escaped = this.source[this.offset++];
+            if (escaped === undefined)
+                this.fail("Unterminated string", start);
+            if ('"\\/bfnrt'.includes(escaped))
+                continue;
+            if (escaped !== "u")
+                this.fail("Invalid escape sequence in string", escapeOffset);
+            for (let index = 0; index < 4; index++) {
+                const hexOffset = this.offset + index;
+                if (!/[0-9a-fA-F]/.test(this.source[hexOffset] ?? "")) {
+                    this.fail("Invalid Unicode escape sequence in string", hexOffset);
+                }
+            }
+            this.offset += 4;
+        }
+        this.fail("Unterminated string", start);
+    }
+    trivia() {
+        while (this.offset < this.source.length) {
+            if ([" ", "\t", "\r", "\n"].includes(this.source[this.offset] ?? "")) {
+                this.offset++;
+            }
+            else if (this.source.startsWith("//", this.offset)) {
+                const newline = this.source.indexOf("\n", this.offset + 2);
+                this.offset = newline === -1 ? this.source.length : newline + 1;
+            }
+            else if (this.source.startsWith("/*", this.offset)) {
+                const end = this.source.indexOf("*/", this.offset + 2);
+                if (end === -1)
+                    this.fail("Unterminated block comment");
+                this.offset = end + 2;
+            }
+            else {
+                return;
+            }
+        }
+    }
+    fail(message, offset = this.offset) {
+        throw new JsoncSyntaxError(message.endsWith(".") ? message : `${message}.`, offset);
+    }
+}
+class JsoncSyntaxError extends Error {
+    offset;
+    constructor(message, offset) {
+        super(message);
+        this.offset = offset;
+    }
+}
+function locationFinder(source) {
+    const lineStarts = [0];
+    for (let index = 0; index < source.length; index++) {
+        if (source[index] === "\n")
+            lineStarts.push(index + 1);
+    }
+    return (offset) => {
+        let low = 0;
+        let high = lineStarts.length;
+        while (low + 1 < high) {
+            const middle = Math.floor((low + high) / 2);
+            if ((lineStarts[middle] ?? 0) <= offset)
+                low = middle;
+            else
+                high = middle;
+        }
+        return { line: low + 1, column: offset - (lineStarts[low] ?? 0) + 1 };
+    };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const CONFIG_FIELDS = {
+    build: {
+        installRoot: { type: "string" },
+        installCommand: { type: "string" },
+        command: { type: "string" },
+        output: { type: "string" },
+        timeoutSeconds: { type: "number" },
+    },
+    serve: {
+        index: { type: "string-or-false" },
+        spaFallback: { type: "string" },
+        cleanUrls: { type: "boolean" },
+        directoryListing: { type: "boolean" },
+    },
+    metadata: {
+        title: { type: "string" },
+        description: { type: "string" },
+        image: { type: "string" },
+    },
+    substitute: {
+        files: { type: "string-array" },
+    },
+};
+const ROOT_KEYS = new Set(["$schema", "version", ...Object.keys(CONFIG_FIELDS)]);
+const LEGACY_KEYS = {
+    index: { kind: "renamed", suggestion: "serve.index" },
+    fallback: { kind: "renamed", suggestion: "serve.spaFallback" },
+    cleanUrls: { kind: "renamed", suggestion: "serve.cleanUrls" },
+    meta: { kind: "renamed", suggestion: "metadata" },
+    listing: { kind: "removed" },
+    superpowers: { kind: "removed" },
+    templates: { kind: "removed" },
+    theme: { kind: "removed" },
+    pages: { kind: "removed" },
+    placement: { kind: "removed" },
+    markdownNegotiation: { kind: "removed" },
+    inject: { kind: "removed" },
+    access: { kind: "removed" },
+};
+export function compileSfConfigV1(source, options = {}) {
+    const locate = locationFinder(source);
+    if (new TextEncoder().encode(source).byteLength > SPACE_CONFIG_CAPS.fileBytes) {
+        return invalidResult(`Config supports up to ${SPACE_CONFIG_CAPS.fileBytes} bytes.`, 1, 1);
+    }
+    const reader = new JsoncReader(source);
+    let value;
+    try {
+        value = reader.read();
+    }
+    catch (error) {
+        const syntax = error instanceof JsoncSyntaxError ? error : new JsoncSyntaxError("Invalid JSONC.", 0);
+        const located = locate(syntax.offset);
+        return invalidResult(syntax.message, located.line, located.column);
+    }
+    const issues = [];
+    const locations = new Map();
+    for (const [jsonPath, offset] of reader.keyOffsets)
+        locations.set(jsonPath, locate(offset));
+    locations.set("$", { line: 1, column: 1 });
+    const issue = (code, jsonPath, message, suggestion) => issues.push({
+        code,
+        severity: "error",
+        path: jsonPath,
+        ...(locations.get(jsonPath) ?? { line: 1, column: 1 }),
+        message,
+        ...(suggestion ? { suggestion } : {}),
+    });
+    if (!isObject(value)) {
+        issue("config_invalid", "$", "Config must be an object.");
+        return { success: false, config: null, effective: null, issues, locations };
+    }
+    validateKeys(value, issue);
+    if (value.version !== 1)
+        issue("config_invalid", "$.version", "version must be 1.");
+    if (value.$schema !== undefined && value.$schema !== SF_CONFIG_V1_SCHEMA_URL) {
+        issue("config_invalid", "$.$schema", "$schema must identify the sf.jsonc v1 schema.");
+    }
+    validateShape(value, issue);
+    validateTemplateSources(value, options.templateSources ?? [], issue);
+    validateArtifactReferences(value, options.artifactPaths, issue);
+    if (issues.length > 0)
+        return { success: false, config: null, effective: null, issues, locations };
+    const config = projectConfig(value);
+    const artifacts = options.artifactPaths ?? [];
+    const rootHtml = artifacts.filter((entry) => !entry.includes("/") && entry.endsWith(".html"));
+    const explicitIndex = config.serve?.index;
+    let index;
+    if (explicitIndex !== undefined)
+        index = explicitIndex;
+    else if (artifacts.includes("index.html"))
+        index = "index.html";
+    else if (rootHtml.length === 1)
+        index = rootHtml[0] ?? false;
+    else if (rootHtml.length > 1) {
+        issue("serve_index_required", "$.serve.index", "Multiple root HTML files require serve.index.");
+        return { success: false, config: null, effective: null, issues, locations };
+    }
+    else
+        index = false;
+    return {
+        success: true,
+        config,
+        effective: {
+            version: 1,
+            ...(config.build ? {
+                build: {
+                    ...config.build,
+                    installRoot: config.build.installRoot ?? ".",
+                    timeoutSeconds: config.build.timeoutSeconds ?? 900,
+                },
+            } : {}),
+            serve: {
+                index,
+                ...(config.serve?.spaFallback !== undefined ? { spaFallback: config.serve.spaFallback } : {}),
+                cleanUrls: config.serve?.cleanUrls ?? true,
+                directoryListing: config.serve?.directoryListing ?? index === false,
+            },
+            ...(config.metadata ? { metadata: config.metadata } : {}),
+            ...(config.substitute ? { substitute: config.substitute } : {}),
+        },
+        issues,
+        locations,
+    };
+}
+function invalidResult(message, line, column) {
+    return {
+        success: false,
+        config: null,
+        effective: null,
+        issues: [{
+                code: "config_invalid",
+                severity: "error",
+                path: "$",
+                line,
+                column,
+                message,
+            }],
+        locations: new Map([["$", { line, column }]]),
+    };
+}
+function validateKeys(value, issue) {
+    for (const key of Object.keys(value)) {
+        if (ROOT_KEYS.has(key))
+            continue;
+        const keyPath = `$.${key}`;
+        if (key === "space") {
+            issue("config_identity_moved", keyPath, "Space identity belongs in .spacefast/space.json.");
+            continue;
+        }
+        const legacy = LEGACY_KEYS[key];
+        if (legacy?.kind === "removed") {
+            issue("config_key_removed", keyPath, `${key} is not part of sf.jsonc v1.`);
+        }
+        else if (legacy?.kind === "renamed") {
+            issue("config_unknown_key", keyPath, `Unknown config key ${key}.`, legacy.suggestion);
+        }
+        else {
+            issue("config_unknown_key", keyPath, `Unknown config key ${key}.`, nearestKey(key, [...ROOT_KEYS]));
+        }
+    }
+    for (const [section, fields] of Object.entries(CONFIG_FIELDS)) {
+        const object = value[section];
+        if (object === undefined)
+            continue;
+        if (!isObject(object)) {
+            issue("config_invalid", `$.${section}`, `${section} must be an object.`);
+            continue;
+        }
+        for (const key of Object.keys(object)) {
+            if (Object.hasOwn(fields, key))
+                continue;
+            const keyPath = `$.${section}.${key}`;
+            issue("config_unknown_key", keyPath, `Unknown config key ${key}.`, nearestKey(key, Object.keys(fields)));
+        }
+    }
+}
+function validateShape(value, issue) {
+    for (const [section, fields] of Object.entries(CONFIG_FIELDS)) {
+        const object = value[section];
+        if (!isObject(object))
+            continue;
+        for (const [key, descriptor] of Object.entries(fields)) {
+            const fieldValue = object[key];
+            if (fieldValue === undefined)
+                continue;
+            if (!matchesType(fieldValue, descriptor.type)) {
+                issue("config_invalid", `$.${section}.${key}`, typeMessage(section, key, descriptor.type));
+            }
+        }
+    }
+    if (isObject(value.build)) {
+        const timeout = value.build.timeoutSeconds;
+        if (typeof timeout === "number" && (!Number.isInteger(timeout)
+            || timeout < 60
+            || timeout > 7200)) {
+            issue("config_invalid", "$.build.timeoutSeconds", "build.timeoutSeconds must be an integer from 60 to 7200.");
+        }
+        const installRoot = value.build.installRoot;
+        if (typeof installRoot === "string" && isAbsolutePath(installRoot)) {
+            issue("config_invalid", "$.build.installRoot", "build.installRoot must be a relative path.");
+        }
+        const output = value.build.output;
+        if (typeof output === "string" && isAbsoluteOrEscaping(output)) {
+            issue("config_invalid", "$.build.output", "build.output must be a relative path that does not escape the project root.");
+        }
+    }
+    if (isObject(value.serve)) {
+        for (const key of ["index", "spaFallback"]) {
+            const candidate = value.serve[key];
+            if (typeof candidate === "string" && !isCommittedPath(candidate)) {
+                issue("config_invalid", `$.serve.${key}`, `serve.${key} must be a non-empty committed relative path.`);
+            }
+        }
+    }
+    if (isObject(value.substitute) && value.substitute.files === undefined) {
+        issue("config_invalid", "$.substitute", "substitute.files is required when substitute is present.");
+    }
+    if (isObject(value.substitute) && Array.isArray(value.substitute.files)) {
+        if (value.substitute.files.length > SPACE_CONFIG_CAPS.templates) {
+            issue("config_invalid", "$.substitute.files", `substitute.files supports up to ${SPACE_CONFIG_CAPS.templates} entries.`);
+        }
+        value.substitute.files.forEach((candidate, index) => {
+            if (typeof candidate === "string" && !isCommittedPath(candidate)) {
+                issue("config_invalid", `$.substitute.files[${index}]`, "substitute.files entries must be non-empty committed relative paths.");
+            }
+        });
+    }
+    if (isObject(value.metadata)) {
+        for (const [key, cap] of [
+            ["title", SPACE_CONFIG_CAPS.metaTitleChars],
+            ["description", SPACE_CONFIG_CAPS.metaDescriptionChars],
+            ["image", SPACE_CONFIG_CAPS.metaImageChars],
+        ]) {
+            const candidate = value.metadata[key];
+            if (typeof candidate === "string" && candidate.length > cap) {
+                issue("config_invalid", `$.metadata.${key}`, `metadata.${key} supports up to ${cap} characters.`);
+            }
+        }
+        const image = value.metadata.image;
+        if (typeof image === "string" && !isCommittedImagePath(image) && !isHttpsUrl(image)) {
+            issue("config_invalid", "$.metadata.image", "metadata.image must be a committed root-relative path or https: URL.");
+        }
+    }
+}
+function matchesType(value, type) {
+    if (type === "string-array") {
+        return Array.isArray(value) && value.every((item) => typeof item === "string");
+    }
+    if (type === "string-or-false")
+        return typeof value === "string" || value === false;
+    return typeof value === type;
+}
+function typeMessage(section, key, type) {
+    if (type === "string-array")
+        return `${section}.${key} must be an array of strings.`;
+    if (type === "string-or-false")
+        return `${section}.${key} must be a string or false.`;
+    if (type === "boolean")
+        return `${section}.${key} must be boolean.`;
+    return `${section}.${key} must be a ${type}.`;
+}
+function isAbsolutePath(candidate) {
+    return /^(?:[\\/]|[A-Za-z]:[\\/])/.test(candidate);
+}
+function isAbsoluteOrEscaping(candidate) {
+    return isAbsolutePath(candidate) || candidate.split(/[\\/]/).includes("..");
+}
+function nearestKey(candidate, keys) {
+    let nearest;
+    for (const key of keys) {
+        const distance = editDistance(candidate, key);
+        if (distance <= 2 && (!nearest || distance < nearest.distance))
+            nearest = { key, distance };
+    }
+    return nearest?.key;
+}
+function editDistance(left, right) {
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {
+        const current = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {
+            current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[right.length] ?? right.length;
+}
+function isCommittedPath(candidate) {
+    return candidate.length > 0
+        && !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(candidate)
+        && !isAbsoluteOrEscaping(candidate);
+}
+function isCommittedImagePath(candidate) {
+    return /^\/(?!\/)/.test(candidate) && !candidate.split(/[\\/]/).includes("..");
+}
+function isHttpsUrl(candidate) {
+    try {
+        return new URL(candidate).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function validateTemplateSources(value, templates, issue) {
+    const files = isObject(value.substitute) && Array.isArray(value.substitute.files)
+        ? value.substitute.files
+        : [];
+    for (const template of templates) {
+        const index = files.indexOf(template.path);
+        if (index < 0)
+            continue;
+        if (!/\{\{\s*vars\./.test(template.source))
+            continue;
+        issue("template_syntax_retired", `$.substitute.files[${index}]`, `Use {{ env.NAME }} instead of {{ vars.NAME }} in ${template.path}.`);
+    }
+}
+function validateArtifactReferences(value, artifactPaths, issue) {
+    if (artifactPaths === undefined)
+        return;
+    const artifacts = new Set(artifactPaths);
+    if (isObject(value.serve)) {
+        for (const key of ["index", "spaFallback"]) {
+            const candidate = value.serve[key];
+            if (typeof candidate === "string" && isCommittedPath(candidate) && !artifacts.has(candidate)) {
+                issue("config_invalid", `$.serve.${key}`, `serve.${key} must reference a committed artifact.`);
+            }
+        }
+    }
+    if (isObject(value.substitute) && Array.isArray(value.substitute.files)) {
+        value.substitute.files.forEach((candidate, index) => {
+            if (typeof candidate === "string" && isCommittedPath(candidate) && !artifacts.has(candidate)) {
+                issue("config_invalid", `$.substitute.files[${index}]`, "substitute.files entries must reference committed artifacts.");
+            }
+        });
+    }
+    const image = isObject(value.metadata) ? value.metadata.image : undefined;
+    if (typeof image === "string" && isCommittedImagePath(image) && !artifacts.has(image.slice(1))) {
+        issue("config_invalid", "$.metadata.image", "metadata.image must reference a committed artifact.");
+    }
+}
+function projectConfig(value) {
+    const config = {
+        version: 1,
+        ...(value.$schema !== undefined ? { $schema: SF_CONFIG_V1_SCHEMA_URL } : {}),
+    };
+    for (const [section, fields] of Object.entries(CONFIG_FIELDS)) {
+        const source = value[section];
+        if (!isObject(source))
+            continue;
+        const projected = {};
+        for (const key of Object.keys(fields)) {
+            if (source[key] !== undefined)
+                projected[key] = source[key];
+        }
+        config[section] = projected;
+    }
+    return config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacefast/common",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "license": "MIT",
   "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
   "repository": {
@@ -17,6 +17,7 @@
     "node": ">=20"
   },
   "files": [
+    "brand-assets",
     "dist"
   ],
   "exports": {
@@ -25,6 +26,19 @@
       "import": "./dist/brand.js",
       "default": "./dist/brand.js"
     },
+    "./brand-assets": {
+      "types": "./dist/brand-assets.d.ts",
+      "import": "./dist/brand-assets.js",
+      "default": "./dist/brand-assets.js"
+    },
+    "./brand-assets/build": {
+      "types": "./dist/brand-assets-build.d.ts",
+      "import": "./dist/brand-assets-build.js",
+      "default": "./dist/brand-assets-build.js"
+    },
+    "./brand-assets/spacefast-wordmark.svg": "./brand-assets/spacefast-wordmark.svg",
+    "./brand-assets/spacefast-sf-full-bleed.svg": "./brand-assets/spacefast-sf-full-bleed.svg",
+    "./brand-assets/spacefast-favicon.svg": "./brand-assets/spacefast-favicon.svg",
     "./vocabulary": {
       "types": "./dist/vocabulary.d.ts",
       "import": "./dist/vocabulary.js",
@@ -45,6 +59,11 @@
       "import": "./dist/utils/*.js",
       "default": "./dist/utils/*.js"
     },
+    "./slug-policy": {
+      "types": "./dist/slug-policy/index.d.ts",
+      "import": "./dist/slug-policy/index.js",
+      "default": "./dist/slug-policy/index.js"
+    },
     "./agents/*": {
       "types": "./dist/agents/*.d.ts",
       "import": "./dist/agents/*.js",