scriptorium 0.0.1 → 0.2.1

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

@@ -0,0 +1,170 @@
+import { stringify as stringifyYaml } from "yaml";
+import { z } from "zod";
+import { createConfigSchema, createSecretsSchema, DOCUMENTATION_CONFIG_DIR, DOCUMENTATION_DATA_DIR, DOCUMENTATION_HOME, getOptionMetadata, } from "./schema.server.js";
+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",
+            LOCALAPPDATA: "C:/Users/you/AppData/Local",
+            XDG_CONFIG_HOME: "/path/to/home/.config",
+            XDG_DATA_HOME: "/path/to/home/.local/share",
+        },
+        cli: {},
+    };
+    return {
+        config: collectSchemaDocumentation(createConfigSchema(sources)),
+        secrets: collectSchemaDocumentation(createSecretsSchema(sources)),
+    };
+}
+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/.config/scriptorium", DOCUMENTATION_CONFIG_DIR)
+        .replaceAll("/path/to/home/.local/share/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.",
+        "The configuration directory can be overridden with `--config-dir <path>` or `SCRIPTORIUM_CONFIG_DIR`.",
+        "The data directory can be overridden with `--data-dir <path>` or `SCRIPTORIUM_DATA_DIR`.",
+        "",
+        `| Platform | ${DOCUMENTATION_CONFIG_DIR} | ${DOCUMENTATION_DATA_DIR} |`,
+        "| --- | --- | --- |",
+        "| macOS | `$XDG_CONFIG_HOME/scriptorium` or `~/.config/scriptorium` | `$XDG_DATA_HOME/scriptorium` or `~/.local/share/scriptorium` |",
+        "| Linux | `$XDG_CONFIG_HOME/scriptorium` or `~/.config/scriptorium` | `$XDG_DATA_HOME/scriptorium` or `~/.local/share/scriptorium` |",
+        "| Windows | `%XDG_CONFIG_HOME%\\scriptorium` or `%USERPROFILE%\\.config\\scriptorium` | `%XDG_DATA_HOME%\\scriptorium` or `%USERPROFILE%\\.local\\share\\scriptorium` |",
+        "",
+        `Examples use \`${DOCUMENTATION_CONFIG_DIR}\` and \`${DOCUMENTATION_DATA_DIR}\` as shorthand for Scriptorium's per-user config/data directories 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");
+}

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

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { createConfigSchema, createSecretsSchema, getRuntimeConfigPaths, } from "./schema.server.js";
+const PRIVATE_FILE_MODE = 0o600;
+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 ensureRuntimeConfigFiles(paths) {
+    mkdirSync(paths.dataDirectory, { recursive: true });
+    if (!existsSync(paths.configFile)) {
+        writeYamlFile(paths.configFile, {});
+    }
+    if (!existsSync(paths.secretsFile)) {
+        writeYamlFile(paths.secretsFile, {});
+    }
+}
+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);
+    ensureRuntimeConfigFiles(paths);
+    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 };
+}

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

@@ -0,0 +1,128 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+export const CONFIG_FILE_NAME = "config.yml";
+export const SECRETS_FILE_NAME = "secrets.yml";
+export const DOCUMENTATION_HOME = "$HOME";
+export const DOCUMENTATION_CONFIG_DIR = "<scriptorium_config_dir>";
+export const DOCUMENTATION_DATA_DIR = "<scriptorium_data_dir>";
+export function meta(schema, metadata) {
+    return schema.meta(metadata);
+}
+export function section(shape) {
+    return z.object(shape).prefault(() => Object.fromEntries(Object.keys(shape).map((key) => [key, undefined])));
+}
+export function getOptionMetadata(schema) {
+    const metadata = schema.meta();
+    if (!metadata?.description) {
+        throw new Error("Missing required option metadata.");
+    }
+    return metadata;
+}
+export 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 xdgDirectory(env, name) {
+    const home = env.HOME?.trim() || homedir();
+    if (name === "config") {
+        return resolve(env.XDG_CONFIG_HOME?.trim() || join(home, ".config"), "scriptorium");
+    }
+    return resolve(env.XDG_DATA_HOME?.trim() || join(home, ".local/share"), "scriptorium");
+}
+function defaultConfigDirectory(env = process.env) {
+    return xdgDirectory(env, "config");
+}
+function defaultDataDirectory(env = process.env) {
+    return xdgDirectory(env, "data");
+}
+export function getRuntimeConfigPaths(sources = {}) {
+    const configDirectory = resolve(sources.configDir ||
+        sources.env?.SCRIPTORIUM_CONFIG_DIR?.trim() ||
+        defaultConfigDirectory(sources.env));
+    const dataDirectory = resolve(sources.dataDir ||
+        sources.env?.SCRIPTORIUM_DATA_DIR?.trim() ||
+        defaultDataDirectory(sources.env));
+    return {
+        configDirectory,
+        dataDirectory,
+        configFile: join(configDirectory, CONFIG_FILE_NAME),
+        secretsFile: join(configDirectory, SECRETS_FILE_NAME),
+    };
+}
+function getDefaultDatabasePath(sources) {
+    return join(getRuntimeConfigPaths(sources).dataDirectory, "app.db");
+}
+export 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: "SCRIPTORIUM_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: "SCRIPTORIUM_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),
+            url: override(meta(z.string().url().optional(), {
+                cli: "opencode-url",
+                env: "SCRIPTORIUM_OPENCODE_URL",
+                description: "OpenCode server base URL. When set, Scriptorium connects to this server instead of launching its own shared OpenCode process.",
+            }), 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),
+        }),
+    });
+}
+export function createSecretsSchema(sources = {}) {
+    return z.object({
+        auth: section({
+            sessionSecret: override(meta(z.string().min(32).optional(), {
+                env: "SESSION_SECRET",
+                description: "Session signing secret.",
+            }), sources),
+        }),
+    });
+}

package/build/runtime/server/index.js

@@ -0,0 +1,176 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import compression from "compression";
+import express from "express";
+import morgan from "morgan";
+import { createRequestHandler } from "@react-router/express";
+import { initializeRuntimeConfiguration } from "../app/lib/runtime-config/cache.server.js";
+import { parseRuntimeCliArgs, renderRuntimeConfigurationHelp, } from "../app/lib/runtime-config/cli.server.js";
+const MODE = process.env.NODE_ENV ?? "production";
+const IS_DEV = MODE === "development";
+function findPackageRoot() {
+    let currentDirectory = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (existsSync(path.join(currentDirectory, "package.json"))) {
+            return currentDirectory;
+        }
+        const parentDirectory = path.dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+            throw new Error("Unable to locate package root.");
+        }
+        currentDirectory = parentDirectory;
+    }
+}
+function getBuildPaths(packageRoot) {
+    return {
+        clientDirectory: path.join(packageRoot, "build/client"),
+        clientAssetsDirectory: path.join(packageRoot, "build/client/assets"),
+        serverBuildPath: path.join(packageRoot, "build/server/index.js"),
+    };
+}
+function assertBuildExists(packageRoot) {
+    const paths = getBuildPaths(packageRoot);
+    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 `npm run dev` for development.");
+    }
+    return paths;
+}
+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
+    }
+}
+function logServerAddresses(host, port) {
+    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`);
+        return;
+    }
+    process.stdout.write(`[scriptorium] http://${host}:${port}\n`);
+}
+async function createApp(runtime, packageRoot) {
+    const app = express();
+    app.disable("x-powered-by");
+    app.use(compression());
+    app.use(morgan("tiny", {
+        skip: (req) => req.path === "/session-read-status/ack",
+    }));
+    if (IS_DEV) {
+        const hmrPort = runtime.config.server.port >= 65535
+            ? runtime.config.server.port - 1
+            : runtime.config.server.port + 1;
+        const vite = await import("vite");
+        const viteDevServer = await vite.createServer({
+            appType: "custom",
+            server: {
+                hmr: {
+                    port: hmrPort,
+                },
+                middlewareMode: true,
+            },
+        });
+        app.use(viteDevServer.middlewares);
+        app.use(async (req, res, next) => {
+            try {
+                const build = await viteDevServer.ssrLoadModule("virtual:react-router/server-build");
+                const handler = createRequestHandler({
+                    build,
+                    mode: MODE,
+                });
+                return handler(req, res, next);
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    viteDevServer.ssrFixStacktrace(error);
+                }
+                return next(error);
+            }
+        });
+        return app;
+    }
+    const buildPaths = assertBuildExists(packageRoot);
+    const build = await import(__rewriteRelativeImportExtension(pathToFileURL(buildPaths.serverBuildPath).href, true));
+    app.use("/assets", express.static(buildPaths.clientAssetsDirectory, {
+        immutable: true,
+        maxAge: "1y",
+    }));
+    app.use(express.static(buildPaths.clientDirectory));
+    app.all("*", createRequestHandler({
+        build,
+        mode: MODE,
+    }));
+    return app;
+}
+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,
+        dataDir: parsedCli.dataDir,
+        env: process.env,
+    });
+    const packageRoot = findPackageRoot();
+    const app = await createApp(runtime, packageRoot);
+    const host = runtime.config.server.host;
+    const port = runtime.config.server.port;
+    const server = await new Promise((resolve, reject) => {
+        const httpServer = app.listen(port, host, () => resolve(httpServer));
+        httpServer.once("error", reject);
+    });
+    if (runtime.config.network.tailscale) {
+        startTailscale(port);
+    }
+    logServerAddresses(host, port);
+    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);
+}
+await main();