scriptorium 0.0.1

package/build/runtime/app/lib/runtime-config.server.js

@@ -0,0 +1,422 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { z } from "zod";
+const CONFIG_FILE_NAME = "config.yml";
+const SECRETS_FILE_NAME = "secrets.yml";
+const PRIVATE_FILE_MODE = 0o600;
+const DOCUMENTATION_HOME = "$HOME";
+const DOCUMENTATION_DATA_DIR = "<scriptorium_data_dir>";
+let cachedRuntimeConfiguration = null;
+function meta(schema, metadata) {
+    return schema.meta(metadata);
+}
+function section(shape) {
+    return z.object(shape).prefault(() => Object.fromEntries(Object.keys(shape).map((key) => [key, undefined])));
+}
+function getOptionMetadata(schema) {
+    const metadata = schema.meta();
+    if (!metadata?.description) {
+        throw new Error("Missing required option metadata.");
+    }
+    return metadata;
+}
+function override(schema, sources) {
+    const metadata = getOptionMetadata(schema);
+    return z.transform((configValue) => {
+        if (metadata.cli) {
+            const cliValue = sources.cli?.[metadata.cli];
+            if (cliValue !== undefined) {
+                return cliValue;
+            }
+        }
+        if (metadata.env) {
+            const envValue = sources.env?.[metadata.env];
+            if (envValue !== undefined) {
+                return envValue;
+            }
+        }
+        return configValue;
+    }).pipe(schema);
+}
+function defaultConfigDirectory(env = process.env) {
+    const home = env.HOME?.trim() || homedir();
+    switch (platform()) {
+        case "darwin":
+            return resolve(home, "Library/Application Support/scriptorium");
+        case "win32":
+            return resolve(env.APPDATA?.trim() || join(home, "AppData/Roaming"), "scriptorium");
+        default:
+            return resolve(env.XDG_DATA_HOME?.trim() || join(home, ".local/share"), "scriptorium");
+    }
+}
+export function getRuntimeConfigPaths(sources = {}) {
+    const directory = resolve(sources.configDir ||
+        sources.env?.SCRIPTORIUM_CONFIG_DIR?.trim() ||
+        defaultConfigDirectory(sources.env));
+    return {
+        directory,
+        configFile: join(directory, CONFIG_FILE_NAME),
+        secretsFile: join(directory, SECRETS_FILE_NAME),
+    };
+}
+function getDefaultDatabasePath(sources) {
+    return join(getRuntimeConfigPaths(sources).directory, "app.db");
+}
+function createConfigSchema(sources = {}) {
+    const defaultHomeDirectory = sources.env?.HOME?.trim() || homedir();
+    return z.object({
+        server: section({
+            host: override(meta(z.string().min(1).default("0.0.0.0"), {
+                cli: "host",
+                env: "HOST",
+                description: "Host interface for the web server.",
+            }), sources),
+            port: override(meta(z.coerce.number().int().min(1).max(65535).default(5174), {
+                cli: "port",
+                env: "PORT",
+                description: "Port for the web server.",
+            }), sources),
+        }),
+        workspace: section({
+            browserRoot: override(meta(z.string().min(1).default(defaultHomeDirectory), {
+                cli: "browser-root",
+                env: "SCRIPTORIUM_BROWSER_ROOT",
+                description: "Root directory exposed in the workspace browser.",
+            }), sources),
+        }),
+        opencode: section({
+            bin: override(meta(z.string().min(1).default("opencode"), {
+                cli: "opencode-bin",
+                env: "OPENCODE_BIN",
+                description: "OpenCode executable name or path.",
+            }), sources),
+        }),
+        network: section({
+            tailscale: override(meta(z.coerce.boolean().default(false), {
+                cli: "tailscale",
+                description: "Expose the app with tailscale serve.",
+            }), sources),
+        }),
+        database: section({
+            path: override(meta(z.string().min(1).default(getDefaultDatabasePath(sources)), {
+                cli: "db-path",
+                env: "SCRIPTORIUM_DB_PATH",
+                description: "Path to the SQLite database file.",
+            }), sources),
+        }),
+    });
+}
+function createSecretsSchema(sources = {}) {
+    return z.object({
+        auth: section({
+            sessionSecret: override(meta(z.string().min(32).optional(), {
+                env: "SESSION_SECRET",
+                description: "Session signing secret.",
+            }), sources),
+        }),
+    });
+}
+function readYamlFile(filePath) {
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    const content = readFileSync(filePath, "utf8");
+    const parsed = parseYaml(content);
+    if (parsed === null || parsed === undefined) {
+        return {};
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Expected ${filePath} to contain a YAML mapping.`);
+    }
+    return parsed;
+}
+function writeYamlFile(filePath, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const content = stringifyYaml(value);
+    writeFileSync(filePath, content, { encoding: "utf8", mode: PRIVATE_FILE_MODE });
+    try {
+        chmodSync(filePath, PRIVATE_FILE_MODE);
+    }
+    catch {
+        // Best-effort only. Some platforms ignore chmod semantics.
+    }
+}
+function ensureSessionSecret(parsedSecrets, paths, sources) {
+    const configuredSecret = parsedSecrets.auth.sessionSecret;
+    if (configuredSecret) {
+        return {
+            auth: {
+                sessionSecret: configuredSecret,
+            },
+        };
+    }
+    const generatedSecret = randomBytes(32).toString("hex");
+    const persistedSecrets = {
+        auth: {
+            sessionSecret: generatedSecret,
+        },
+    };
+    if (sources.env?.SESSION_SECRET === undefined) {
+        writeYamlFile(paths.secretsFile, persistedSecrets);
+    }
+    return persistedSecrets;
+}
+export function resolveRuntimeConfiguration(sources = {}) {
+    const paths = getRuntimeConfigPaths(sources);
+    const rawConfig = readYamlFile(paths.configFile);
+    const rawSecrets = readYamlFile(paths.secretsFile);
+    const config = createConfigSchema(sources).parse(rawConfig);
+    const secrets = ensureSessionSecret(createSecretsSchema(sources).parse(rawSecrets), paths, sources);
+    return { config, secrets, paths };
+}
+export function getRuntimeConfiguration() {
+    if (!cachedRuntimeConfiguration) {
+        cachedRuntimeConfiguration = resolveRuntimeConfiguration({ env: process.env });
+    }
+    return cachedRuntimeConfiguration;
+}
+export function initializeRuntimeConfiguration(sources = {}) {
+    cachedRuntimeConfiguration = resolveRuntimeConfiguration(sources);
+    return cachedRuntimeConfiguration;
+}
+export function resetRuntimeConfigurationCache() {
+    cachedRuntimeConfiguration = null;
+}
+function unwrapSchema(schema) {
+    if (schema instanceof z.ZodDefault) {
+        return unwrapSchema(schema._def.innerType);
+    }
+    if (schema instanceof z.ZodPrefault) {
+        return unwrapSchema(schema._def.innerType);
+    }
+    if (schema instanceof z.ZodPipe) {
+        return unwrapSchema(schema._def.out);
+    }
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+        return unwrapSchema(schema._def.innerType);
+    }
+    return schema;
+}
+function getDefaultValue(schema) {
+    if (schema instanceof z.ZodDefault) {
+        return schema._def.defaultValue;
+    }
+    if (schema instanceof z.ZodPipe) {
+        return getDefaultValue(schema._def.out);
+    }
+    if (schema instanceof z.ZodPrefault) {
+        return getDefaultValue(schema._def.innerType);
+    }
+    return undefined;
+}
+function getTypeName(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped instanceof z.ZodString) {
+        return "string";
+    }
+    if (unwrapped instanceof z.ZodNumber) {
+        return "number";
+    }
+    if (unwrapped instanceof z.ZodBoolean) {
+        return "boolean";
+    }
+    if (unwrapped instanceof z.ZodEnum) {
+        return "enum";
+    }
+    return "unknown";
+}
+export function collectSchemaDocumentation(schema, path = []) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped instanceof z.ZodObject) {
+        return Object.entries(unwrapped.shape).flatMap(([key, child]) => collectSchemaDocumentation(child, [...path, key]));
+    }
+    const metadata = schema instanceof z.ZodPipe
+        ? getOptionMetadata(schema._def.out)
+        : getOptionMetadata(schema);
+    return [{
+            path,
+            type: getTypeName(schema),
+            description: metadata.description,
+            cli: metadata.cli ? `--${metadata.cli}` : undefined,
+            env: metadata.env,
+            defaultValue: getDefaultValue(schema),
+        }];
+}
+export function getRuntimeConfigurationDocumentation() {
+    const sources = {
+        env: {
+            APPDATA: "C:/Users/you/AppData/Roaming",
+            HOME: "/path/to/home",
+            XDG_DATA_HOME: "/path/to/home/.local/share",
+        },
+        cli: {},
+    };
+    return {
+        config: collectSchemaDocumentation(createConfigSchema(sources)),
+        secrets: collectSchemaDocumentation(createSecretsSchema(sources)),
+    };
+}
+function getCliRows() {
+    return getRuntimeConfigurationDocumentation().config.filter((row) => row.cli);
+}
+function getCliOptionsConfig() {
+    const options = {
+        help: {
+            type: "boolean",
+        },
+        "config-dir": {
+            type: "string",
+        },
+    };
+    for (const row of getCliRows()) {
+        const flag = row.cli.slice(2);
+        options[flag] = {
+            type: row.type === "boolean" ? "boolean" : "string",
+        };
+        if (row.type === "boolean") {
+            options[`no-${flag}`] = {
+                type: "boolean",
+            };
+        }
+    }
+    return options;
+}
+export function parseRuntimeCliArgs(args) {
+    const parsed = parseArgs({
+        args,
+        options: getCliOptionsConfig(),
+        strict: true,
+        allowPositionals: false,
+    });
+    const values = parsed.values;
+    const cli = {};
+    for (const row of getCliRows()) {
+        const flag = row.cli.slice(2);
+        const value = values[flag];
+        if (value !== undefined) {
+            cli[flag] = value;
+            continue;
+        }
+        if (row.type === "boolean" && values[`no-${flag}`] === true) {
+            cli[flag] = false;
+        }
+    }
+    return {
+        cli,
+        configDir: typeof values["config-dir"] === "string"
+            ? values["config-dir"]
+            : undefined,
+        help: values.help === true,
+    };
+}
+function stringifyDefaultValue(value) {
+    if (value === undefined) {
+        return "";
+    }
+    return `\`${String(normalizeDocumentationValue(value))}\``;
+}
+function normalizeDocumentationValue(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    return value
+        .replaceAll("/path/to/home/Library/Application Support/scriptorium", DOCUMENTATION_DATA_DIR)
+        .replaceAll("/path/to/home/.local/share/scriptorium", DOCUMENTATION_DATA_DIR)
+        .replaceAll("C:/Users/you/AppData/Roaming/scriptorium", DOCUMENTATION_DATA_DIR)
+        .replaceAll("/path/to/home", DOCUMENTATION_HOME);
+}
+function escapeTableCell(value) {
+    return (value || "").replaceAll("|", "\\|");
+}
+function setNestedValue(target, path, value) {
+    let current = target;
+    for (const segment of path.slice(0, -1)) {
+        const existing = current[segment];
+        if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+            current[segment] = {};
+        }
+        current = current[segment];
+    }
+    current[path.at(-1)] = value;
+}
+function getExampleValue(row, section) {
+    if (row.defaultValue !== undefined) {
+        return normalizeDocumentationValue(row.defaultValue);
+    }
+    if (section === "secrets") {
+        return "<generated on first run or set via env>";
+    }
+    return `<set ${row.path.join(".")}>`;
+}
+export function buildDocumentationExample(rows, section) {
+    const result = {};
+    for (const row of rows) {
+        setNestedValue(result, row.path, getExampleValue(row, section));
+    }
+    return stringifyYaml(result).trim();
+}
+function renderDocumentationTable(rows) {
+    const lines = [
+        "| Key | Type | Default | CLI | Env | Description |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ];
+    for (const row of rows) {
+        lines.push(`| \`${row.path.join(".")}\` | ${row.type} | ${escapeTableCell(stringifyDefaultValue(row.defaultValue))} | ${escapeTableCell(row.cli ? `\`${row.cli}\`` : "")} | ${escapeTableCell(row.env ? `\`${row.env}\`` : "")} | ${escapeTableCell(row.description)} |`);
+    }
+    return lines.join("\n");
+}
+export function renderRuntimeConfigurationMarkdown() {
+    const documentation = getRuntimeConfigurationDocumentation();
+    return [
+        "# Configuration Reference",
+        "",
+        "Scriptorium reads non-sensitive settings from `config.yml` and secrets from `secrets.yml` in its per-user config directory.",
+        "CLI flags override environment variables, which override YAML values, which override schema defaults.",
+        "",
+        `| Platform | ${DOCUMENTATION_DATA_DIR} |`,
+        "| --- | --- |",
+        "| macOS | `~/Library/Application Support/scriptorium` |",
+        "| Linux | `$XDG_DATA_HOME/scriptorium` or `~/.local/share/scriptorium` |",
+        "| Windows | `%APPDATA%\\scriptorium` |",
+        "",
+        `Examples use \`${DOCUMENTATION_DATA_DIR}\` as shorthand for Scriptorium's per-user data directory and \`${DOCUMENTATION_HOME}\` for the user's home directory.`,
+        "",
+        "## config.yml",
+        "",
+        "```yaml",
+        buildDocumentationExample(documentation.config, "config"),
+        "```",
+        "",
+        renderDocumentationTable(documentation.config),
+        "",
+        "## secrets.yml",
+        "",
+        "```yaml",
+        buildDocumentationExample(documentation.secrets, "secrets"),
+        "```",
+        "",
+        renderDocumentationTable(documentation.secrets),
+        "",
+    ].join("\n");
+}
+export function renderRuntimeConfigurationHelp() {
+    const rows = getCliRows();
+    return [
+        "Usage: scriptorium [options]",
+        "",
+        "Options:",
+        "  --help                  Show this help message",
+        "  --config-dir <path>     Use an alternate config directory",
+        ...rows.map((row) => {
+            const flag = row.cli;
+            const typeSuffix = row.type === "boolean" ? "" : ` <${row.type}>`;
+            const negated = row.type === "boolean" ? `, --no-${flag.slice(2)}` : "";
+            const env = row.env ? ` [env: ${row.env}]` : "";
+            return `  ${flag}${typeSuffix}${negated}  ${row.description}${env}`;
+        }),
+    ].join("\n");
+}

package/build/runtime/cli/scriptorium.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { initializeRuntimeConfiguration, parseRuntimeCliArgs, renderRuntimeConfigurationHelp, } from "../app/lib/runtime-config.server.js";
+import { serveProductionApp } from "./serve.js";
+function getPackageRoot() {
+    return path.resolve(fileURLToPath(new URL("../../..", import.meta.url)));
+}
+export async function main(args = process.argv.slice(2)) {
+    const parsedCli = parseRuntimeCliArgs(args);
+    if (parsedCli.help) {
+        process.stdout.write(`${renderRuntimeConfigurationHelp()}\n`);
+        return;
+    }
+    const runtime = initializeRuntimeConfiguration({
+        cli: parsedCli.cli,
+        configDir: parsedCli.configDir,
+        env: process.env,
+    });
+    await serveProductionApp(runtime, getPackageRoot());
+}
+await main();

package/build/runtime/cli/serve.js

@@ -0,0 +1,101 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import compression from "compression";
+import express from "express";
+import morgan from "morgan";
+import { createRequestHandler } from "@react-router/express";
+function getBuildPaths(packageRoot) {
+    return {
+        packageRoot,
+        clientDirectory: path.join(packageRoot, "build/client"),
+        clientAssetsDirectory: path.join(packageRoot, "build/client/assets"),
+        serverBuildPath: path.join(packageRoot, "build/server/index.js"),
+    };
+}
+function assertBuildExists(paths) {
+    if (!existsSync(paths.serverBuildPath) || !existsSync(paths.clientDirectory)) {
+        throw new Error("Scriptorium has not been built yet. Run `npm run build` before `npm start`, or use the published package with `npx scriptorium`.");
+    }
+}
+async function loadServerBuild(serverBuildPath) {
+    return import(pathToFileURL(serverBuildPath).href);
+}
+function startTailscale(port) {
+    try {
+        execSync(`tailscale serve --bg http://localhost:${port}`, { stdio: "inherit" });
+    }
+    catch {
+        // tailscale not available - ignore
+    }
+}
+function stopTailscale() {
+    try {
+        execSync("tailscale serve --https=443 off", { stdio: "ignore" });
+    }
+    catch {
+        // tailscale not available - ignore
+    }
+}
+export async function serveProductionApp(runtime, packageRoot) {
+    const buildPaths = getBuildPaths(packageRoot);
+    assertBuildExists(buildPaths);
+    process.env.NODE_ENV = process.env.NODE_ENV ?? "production";
+    const build = await loadServerBuild(buildPaths.serverBuildPath);
+    const app = express();
+    const port = runtime.config.server.port;
+    const host = runtime.config.server.host;
+    app.disable("x-powered-by");
+    app.use(compression());
+    app.use("/assets", express.static(buildPaths.clientAssetsDirectory, {
+        immutable: true,
+        maxAge: "1y",
+    }));
+    app.use(express.static(buildPaths.clientDirectory));
+    app.use(morgan("tiny"));
+    app.all("*", createRequestHandler({
+        build,
+        mode: process.env.NODE_ENV,
+    }));
+    if (runtime.config.network.tailscale) {
+        startTailscale(port);
+    }
+    const server = await new Promise((resolve, reject) => {
+        const httpServer = app.listen(port, host, () => resolve(httpServer));
+        httpServer.once("error", reject);
+    });
+    const networkAddress = Object.values(os.networkInterfaces())
+        .flat()
+        .find((entry) => String(entry?.family).includes("4") && !entry?.internal)?.address;
+    if (networkAddress) {
+        process.stdout.write(`[scriptorium] http://${host}:${port} (http://${networkAddress}:${port})\n`);
+    }
+    else {
+        process.stdout.write(`[scriptorium] http://${host}:${port}\n`);
+    }
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        if (runtime.config.network.tailscale) {
+            stopTailscale();
+        }
+        server.close((error) => {
+            if (error) {
+                process.stderr.write(`${error.message}\n`);
+                process.exitCode = 1;
+            }
+        });
+    };
+    server.once("close", () => {
+        if (runtime.config.network.tailscale) {
+            stopTailscale();
+        }
+    });
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}