codex-terminal-themes 1.0.0

package/tools/serve-pages-site.mjs

@@ -0,0 +1,196 @@
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import * as path from "node:path";
+
+const defaultHost = "127.0.0.1";
+const defaultPort = 4173;
+const rootDirectory = process.cwd();
+const docsDirectory = path.join(rootDirectory, "docs");
+
+/**
+ * @param {string} docsRoot
+ *
+ * @returns {(
+ *     request: import("node:http").IncomingMessage,
+ *     response: import("node:http").ServerResponse
+ * ) => Promise<void>}
+ */
+function createRequestHandler(docsRoot) {
+    return async (request, response) => {
+        const requestUrl = request.url ?? "/";
+        const filePath = getRequestedFilePath(docsRoot, requestUrl);
+
+        if (filePath === null) {
+            sendNotFound(response);
+            return;
+        }
+
+        await sendFile(response, filePath);
+    };
+}
+
+/**
+ * @param {string} filePath
+ *
+ * @returns {string}
+ */
+function getContentType(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+
+    switch (extension) {
+        case ".css": {
+            return "text/css; charset=utf-8";
+        }
+
+        case ".html": {
+            return "text/html; charset=utf-8";
+        }
+
+        case ".js": {
+            return "text/javascript; charset=utf-8";
+        }
+
+        case ".json": {
+            return "application/json; charset=utf-8";
+        }
+
+        case ".svg": {
+            return "image/svg+xml";
+        }
+
+        default: {
+            return "application/octet-stream";
+        }
+    }
+}
+
+/**
+ * @param {string} optionName
+ * @param {number} fallback
+ *
+ * @returns {number}
+ */
+function getIntegerOption(optionName, fallback) {
+    const value = getStringOption(optionName, "");
+    const parsedValue = Number.parseInt(value, 10);
+
+    return Number.isInteger(parsedValue) && parsedValue > 0
+        ? parsedValue
+        : fallback;
+}
+
+/**
+ * @param {string} docsRoot
+ * @param {string} requestUrl
+ *
+ * @returns {null | string}
+ */
+function getRequestedFilePath(docsRoot, requestUrl) {
+    const parsedUrl = new URL(requestUrl, "http://localhost");
+    const decodedPath = decodeURIComponent(parsedUrl.pathname);
+    const relativePath =
+        decodedPath === "/" ? "index.html" : decodedPath.replace(/^\/+/v, "");
+    const filePath = path.resolve(docsRoot, relativePath);
+
+    return isPathInside(docsRoot, filePath) ? filePath : null;
+}
+
+/**
+ * @returns {{ host: string; port: number }}
+ */
+function getServerOptions() {
+    return {
+        host: getStringOption("--host", defaultHost),
+        port: getIntegerOption("--port", defaultPort),
+    };
+}
+
+/**
+ * @param {string} optionName
+ * @param {string} fallback
+ *
+ * @returns {string}
+ */
+function getStringOption(optionName, fallback) {
+    const prefix = `${optionName}=`;
+    const argument = process.argv.find((item) => item.startsWith(prefix));
+
+    return argument === undefined ? fallback : argument.slice(prefix.length);
+}
+
+/**
+ * @param {string} rootPath
+ * @param {string} candidatePath
+ *
+ * @returns {boolean}
+ */
+function isPathInside(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+
+    return (
+        relativePath.length === 0 ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+    );
+}
+
+/**
+ * @returns {void}
+ */
+function main() {
+    const { host, port } = getServerOptions();
+    const requestHandler = createRequestHandler(docsDirectory);
+    const server = createServer((request, response) => {
+        void requestHandler(request, response);
+    });
+
+    server.listen(port, host, () => {
+        process.stdout.write(
+            `Serving docs at http://${host}:${String(port)}/\n`
+        );
+    });
+}
+
+/**
+ * @returns {void}
+ */
+function run() {
+    try {
+        main();
+    } catch (error) {
+        process.stderr.write(`${String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} filePath
+ *
+ * @returns {Promise<void>}
+ */
+async function sendFile(response, filePath) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- The request path is constrained to the repo-local docs directory.
+        const contents = await readFile(filePath);
+        response.writeHead(200, {
+            "Content-Type": getContentType(filePath),
+        });
+        response.end(contents);
+    } catch {
+        sendNotFound(response);
+    }
+}
+
+/**
+ * @param {import("node:http").ServerResponse} response
+ *
+ * @returns {void}
+ */
+function sendNotFound(response) {
+    response.writeHead(404, {
+        "Content-Type": "text/plain; charset=utf-8",
+    });
+    response.end("Not found\n");
+}
+
+run();

package/tools/validate-themes.mjs

@@ -0,0 +1,272 @@
+import { XMLParser } from "fast-xml-parser";
+import { SyntaxValidator } from "fast-xml-validator";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { readdir, readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+
+const rootDirectory = process.cwd();
+const themeDirectory = path.join(rootDirectory, "themes");
+const shouldBuildBatCache = process.argv.includes("--bat-cache");
+
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    preserveOrder: true,
+    trimValues: false,
+});
+
+/**
+ * @typedef {{ filePath: string; ok: true; reason: "" }
+ *     | { filePath: string; ok: false; reason: string }} ThemeValidationResult
+ */
+
+/**
+ * @returns {Promise<number>}
+ */
+async function buildBatCache() {
+    const childProcess = spawn("bat", ["cache", "--build"], {
+        stdio: "inherit",
+    });
+
+    const closeResult = /** @type {readonly unknown[]} */ (
+        await Promise.race([
+            once(childProcess, "close"),
+            once(childProcess, "error").then((errorResult) => {
+                const errorValues = /** @type {readonly unknown[]} */ (
+                    errorResult
+                );
+                const error = errorValues[0];
+                throw error;
+            }),
+        ])
+    );
+    const [exitCode] = closeResult;
+
+    return typeof exitCode === "number" ? exitCode : 1;
+}
+
+/**
+ * @param {Record<string, unknown>} record
+ * @param {string} key
+ *
+ * @returns {readonly unknown[] | undefined}
+ */
+function getArrayProperty(record, key) {
+    const value = record[key];
+    return isUnknownArray(value) ? value : undefined;
+}
+
+/**
+ * @param {unknown} value
+ *
+ * @returns {string | undefined}
+ */
+function getTextNodeValue(value) {
+    if (!isUnknownArray(value)) {
+        return undefined;
+    }
+
+    const firstValue = value[0];
+    if (!isRecord(firstValue)) {
+        return undefined;
+    }
+
+    const textValue = firstValue["#text"];
+    return typeof textValue === "string" ? textValue : undefined;
+}
+
+/**
+ * @param {string} directory
+ *
+ * @returns {Promise<readonly string[]>}
+ */
+async function getThemeFiles(directory) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- The validator intentionally reads the repo-local themes directory.
+    const directoryEntries = await readdir(directory, { withFileTypes: true });
+
+    return directoryEntries
+        .filter(
+            (directoryEntry) =>
+                directoryEntry.isFile() &&
+                directoryEntry.name.endsWith(".tmTheme")
+        )
+        .map((directoryEntry) => directoryEntry.name)
+        .toSorted((left, right) => left.localeCompare(right))
+        .map((fileName) => path.join(directory, fileName));
+}
+
+/**
+ * @param {unknown} parsedDocument
+ *
+ * @returns {readonly string[]}
+ */
+function getTopLevelKeys(parsedDocument) {
+    if (!isUnknownArray(parsedDocument)) {
+        return [];
+    }
+
+    const plistNode = parsedDocument.find((node) =>
+        hasOwnRecordKey(node, "plist")
+    );
+
+    if (plistNode === undefined) {
+        return [];
+    }
+
+    const plistChildren = getArrayProperty(plistNode, "plist");
+    if (plistChildren === undefined) {
+        return [];
+    }
+
+    const dictNode = plistChildren.find((node) =>
+        hasOwnRecordKey(node, "dict")
+    );
+
+    if (dictNode === undefined) {
+        return [];
+    }
+
+    const dictChildren = getArrayProperty(dictNode, "dict");
+    if (dictChildren === undefined) {
+        return [];
+    }
+
+    return dictChildren.flatMap((node) => {
+        if (!hasOwnRecordKey(node, "key")) {
+            return [];
+        }
+
+        const keyName = getTextNodeValue(node.key);
+        return keyName === undefined ? [] : [keyName];
+    });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} key
+ *
+ * @returns {value is Record<string, unknown>}
+ */
+function hasOwnRecordKey(value, key) {
+    return isRecord(value) && Object.hasOwn(value, key);
+}
+
+/**
+ * @param {unknown} value
+ *
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ *
+ * @returns {value is readonly unknown[]}
+ */
+function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+
+/**
+ * @returns {Promise<number>}
+ */
+async function main() {
+    const themeDirectoryStats = await stat(themeDirectory).catch(() => null);
+
+    if (themeDirectoryStats?.isDirectory() === false) {
+        process.stderr.write(
+            `Theme path is not a directory: ${themeDirectory}\n`
+        );
+        return 1;
+    }
+
+    if (themeDirectoryStats === null) {
+        process.stderr.write(
+            `Theme directory does not exist: ${themeDirectory}\n`
+        );
+        return 1;
+    }
+
+    const themeFiles = await getThemeFiles(themeDirectory);
+    const results = await Promise.all(
+        themeFiles.map((filePath) => validateTheme(filePath))
+    );
+    const failedResults = results.filter((result) => !result.ok);
+
+    if (failedResults.length > 0) {
+        for (const result of failedResults) {
+            process.stderr.write(
+                `${path.relative(rootDirectory, result.filePath)}: ${result.reason}\n`
+            );
+        }
+
+        return 1;
+    }
+
+    process.stdout.write(`Validated ${themeFiles.length} .tmTheme files.\n`);
+
+    if (shouldBuildBatCache) {
+        return buildBatCache();
+    }
+
+    return 0;
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+async function run() {
+    try {
+        process.exitCode = await main();
+    } catch (error) {
+        process.stderr.write(`${String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+
+/**
+ * @param {string} filePath
+ *
+ * @returns {Promise<ThemeValidationResult>}
+ */
+async function validateTheme(filePath) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Theme paths come from the repo-local themes directory listing.
+    const text = await readFile(filePath, "utf8");
+    const xmlValidation = SyntaxValidator.validate(text);
+
+    if (xmlValidation !== true) {
+        const { col, line, msg } = xmlValidation.err;
+        return {
+            filePath,
+            ok: false,
+            reason: `XML parse error at ${line}:${col}: ${msg}`,
+        };
+    }
+
+    const parsedDocument = /** @type {unknown} */ (parser.parse(text));
+    const keys = getTopLevelKeys(parsedDocument);
+    const missingKeys = [
+        "name",
+        "uuid",
+        "settings",
+    ].filter((key) => !keys.includes(key));
+
+    if (missingKeys.length > 0) {
+        return {
+            filePath,
+            ok: false,
+            reason: `Missing top-level key(s): ${missingKeys.join(", ")}`,
+        };
+    }
+
+    return {
+        filePath,
+        ok: true,
+        reason: "",
+    };
+}
+
+// eslint-disable-next-line unicorn/prefer-top-level-await -- This published-module config also enforces n/no-top-level-await.
+void run();

package/types/index.d.ts

@@ -0,0 +1,49 @@
+export type ThemeAppearance = "dark" | "light" | "unknown";
+
+export interface ThemeColors {
+    readonly background: null | string;
+    readonly caret: null | string;
+    readonly foreground: null | string;
+    readonly invisibles: null | string;
+    readonly lineHighlight: null | string;
+    readonly selection: null | string;
+}
+
+export interface ThemeMetadata {
+    readonly appearance: ThemeAppearance;
+    readonly author: null | string;
+    readonly colors: ThemeColors;
+    readonly colorSpace: null | string;
+    readonly fileName: string;
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly scopes: readonly string[];
+    readonly semanticClass: null | string;
+    readonly statistics: ThemeStatistics;
+    readonly uuid: string;
+}
+
+export interface ThemeMetadataManifest {
+    readonly $schema: "./themes.schema.json";
+    readonly consumers: readonly string[];
+    readonly description: string;
+    readonly duplicateUuidGroups: Readonly<Record<string, readonly string[]>>;
+    readonly generatedBy: "npm run metadata:write";
+    readonly name: "codex-terminal-themes";
+    readonly schemaVersion: 1;
+    readonly themeCount: number;
+    readonly themeDirectory: "themes";
+    readonly themes: readonly ThemeMetadata[];
+}
+
+export interface ThemeStatistics {
+    readonly colorReferences: number;
+    readonly scopedSettings: number;
+    readonly settings: number;
+    readonly uniqueScopes: number;
+}
+
+declare const manifest: ThemeMetadataManifest;
+
+export default manifest;