rowork 0.1.0

package/dist/core/versions.js

@@ -0,0 +1,67 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getRelease } from "./github-release.js";
+/**
+ * Used only when GitHub cannot be reached while creating a project (offline,
+ * rate limited). It is the one version Rowork writes down itself, so the weekly
+ * upstream check reports it when it falls behind.
+ */
+export const FALLBACK_ROJO_VERSION = "7.7.0";
+/**
+ * The Rojo version to use: the one forced by `ROWORK_ROJO_VERSION` if set (a team
+ * that wants every project on the same version, and no lookup), otherwise the
+ * newest release, or undefined when GitHub cannot be reached. GitHub allows 60
+ * anonymous requests per hour per address, so a shared network can hit its limit:
+ * the caller then falls back with a warning.
+ */
+export async function latestRojoVersion() {
+    const forced = process.env["ROWORK_ROJO_VERSION"]?.trim().replace(/^v/, "");
+    if (forced !== undefined && /^\d+\.\d+\.\d+/.test(forced))
+        return forced;
+    try {
+        return (await getRelease("rojo-rbx/rojo")).tag_name.replace(/^v/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The newest version of an npm package, or undefined if the registry cannot be reached. */
+export function latestNpmVersion(name) {
+    const result = spawnSync("npm", ["view", name, "version"], {
+        encoding: "utf8",
+        shell: process.platform === "win32",
+    });
+    const version = result.stdout.trim();
+    return result.status === 0 && version !== "" ? version : undefined;
+}
+const ROJO_LINE = /^(\s*rojo\s*=\s*"rojo-rbx\/rojo@)([^"]+)(")/m;
+export function readRojoPin(projectRoot) {
+    try {
+        return ROJO_LINE.exec(readFileSync(join(projectRoot, "rokit.toml"), "utf8"))?.[2];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Rewrites the Rojo version in rokit.toml, leaving the rest of the file alone. */
+export function writeRojoPin(projectRoot, version) {
+    const file = join(projectRoot, "rokit.toml");
+    const source = readFileSync(file, "utf8");
+    if (!ROJO_LINE.test(source))
+        return false;
+    writeFileSync(file, source.replace(ROJO_LINE, `$1${version}$3`), "utf8");
+    return true;
+}
+/** `^3.0.0` and `~1.2.3` both mean `3.0.0` / `1.2.3` for comparison. */
+export function baseVersion(range) {
+    return range.replace(/^[\^~>=<\s]+/, "");
+}
+/** True when `version` (like "7.7.0") is at least `major.minor`. An unknown version is not. */
+export function rojoIsAtLeast(version, major, minor) {
+    if (version === undefined)
+        return false;
+    const [m = 0, n = 0] = version.split(".").map(Number);
+    return m > major || (m === major && n >= minor);
+}
+//# sourceMappingURL=versions.js.map

package/dist/dashboard/open.d.ts

@@ -0,0 +1,3 @@
+/** Opens an address in the default browser. Best effort: the address is always printed too. */
+export declare function openBrowser(url: string): void;
+//# sourceMappingURL=open.d.ts.map

package/dist/dashboard/open.js

@@ -0,0 +1,18 @@
+import { spawn } from "node:child_process";
+/** Opens an address in the default browser. Best effort: the address is always printed too. */
+export function openBrowser(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // No browser to open: the printed address is enough.
+    }
+}
+//# sourceMappingURL=open.js.map

package/dist/dashboard/server.d.ts

@@ -0,0 +1,28 @@
+export interface DashboardOptions {
+    projectRoot: string;
+    roworkVersion: string;
+    /** 0 lets the system pick a free port. */
+    port: number;
+}
+export interface RunningDashboard {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * A local web dashboard for one project.
+ *
+ * This server can show logs and, later, run commands and use an API key, so it is
+ * built like something a hostile web page will try to reach:
+ *
+ *  - It listens on 127.0.0.1 only, never on a network interface.
+ *  - A random token, printed in the terminal, is required. It is exchanged once for a
+ *    SameSite=Strict, HttpOnly cookie and removed from the URL, so it does not stay
+ *    in the address bar, the history or a Referer header.
+ *  - The Host header must be this very address. Without that check, a web page can
+ *    point its own domain at 127.0.0.1 ("DNS rebinding") and talk to this server as
+ *    if it were the same site.
+ *  - Only GET is accepted, and only fixed files and fixed API routes exist.
+ */
+export declare function startDashboard(options: DashboardOptions): Promise<RunningDashboard>;
+//# sourceMappingURL=server.d.ts.map

package/dist/dashboard/server.js

@@ -0,0 +1,191 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createReadStream } from "node:fs";
+import { createServer } from "node:http";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logFile, tailLog } from "../core/background.js";
+import { loadConfig } from "../core/config.js";
+import { collectInfo } from "../core/info.js";
+/** Root of the shipped dashboard files, relative to the compiled dist/. */
+function dashboardRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "dashboard");
+}
+/** The only files served: a fixed list, so no request can name a path of its own. */
+const STATIC_FILES = {
+    "/": { file: "index.html", type: "text/html; charset=utf-8" },
+    "/app.js": { file: "app.js", type: "text/javascript; charset=utf-8" },
+    "/app.css": { file: "app.css", type: "text/css; charset=utf-8" },
+};
+const COOKIE = "rowork_dashboard";
+function sameToken(given, expected) {
+    if (given === undefined)
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function cookieToken(request) {
+    const header = request.headers.cookie;
+    if (header === undefined)
+        return undefined;
+    for (const part of header.split(";")) {
+        const [name, ...value] = part.trim().split("=");
+        if (name === COOKIE)
+            return value.join("=");
+    }
+    return undefined;
+}
+/**
+ * A local web dashboard for one project.
+ *
+ * This server can show logs and, later, run commands and use an API key, so it is
+ * built like something a hostile web page will try to reach:
+ *
+ *  - It listens on 127.0.0.1 only, never on a network interface.
+ *  - A random token, printed in the terminal, is required. It is exchanged once for a
+ *    SameSite=Strict, HttpOnly cookie and removed from the URL, so it does not stay
+ *    in the address bar, the history or a Referer header.
+ *  - The Host header must be this very address. Without that check, a web page can
+ *    point its own domain at 127.0.0.1 ("DNS rebinding") and talk to this server as
+ *    if it were the same site.
+ *  - Only GET is accepted, and only fixed files and fixed API routes exist.
+ */
+export function startDashboard(options) {
+    const token = randomBytes(24).toString("hex");
+    const sockets = new Set();
+    let boundPort = 0;
+    const allowedHosts = () => [`127.0.0.1:${boundPort}`, `localhost:${boundPort}`];
+    const send = (response, status, body, type = "text/plain; charset=utf-8") => {
+        response.writeHead(status, {
+            "content-type": type,
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+            "referrer-policy": "no-referrer",
+            "content-security-policy": "default-src 'self'; frame-ancestors 'none'",
+        });
+        response.end(body);
+    };
+    const server = createServer((request, response) => {
+        if (!allowedHosts().includes(request.headers.host ?? "")) {
+            send(response, 403, "Forbidden: unexpected Host header.");
+            return;
+        }
+        if (request.method !== "GET") {
+            send(response, 405, "Method not allowed.");
+            return;
+        }
+        const url = new URL(request.url ?? "/", `http://127.0.0.1:${boundPort}`);
+        // The first visit carries the token in the URL: trade it for a cookie and clean the address.
+        const queryToken = url.searchParams.get("token") ?? undefined;
+        if (queryToken !== undefined) {
+            if (!sameToken(queryToken, token)) {
+                send(response, 403, "Forbidden: wrong token.");
+                return;
+            }
+            response.writeHead(302, {
+                location: url.pathname,
+                "set-cookie": `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`,
+                "cache-control": "no-store",
+            });
+            response.end();
+            return;
+        }
+        if (!sameToken(cookieToken(request), token)) {
+            send(response, 403, "Forbidden: open the address printed by `rowork dashboard`, it carries a one-time token.");
+            return;
+        }
+        const asset = STATIC_FILES[url.pathname];
+        if (asset !== undefined) {
+            const path = join(dashboardRoot(), asset.file);
+            if (!existsSync(path)) {
+                send(response, 500, `Missing dashboard file ${asset.file}.`);
+                return;
+            }
+            send(response, 200, readFileSync(path, "utf8"), asset.type);
+            return;
+        }
+        if (url.pathname === "/api/info") {
+            let config;
+            try {
+                config = loadConfig(options.projectRoot);
+            }
+            catch {
+                config = undefined;
+            }
+            const info = collectInfo({ config, projectRoot: options.projectRoot, roworkVersion: options.roworkVersion });
+            send(response, 200, JSON.stringify(info), "application/json; charset=utf-8");
+            return;
+        }
+        if (url.pathname === "/api/dev/logs") {
+            streamLogs(request, response, options.projectRoot);
+            return;
+        }
+        send(response, 404, "Not found.");
+    });
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.on("close", () => sockets.delete(socket));
+    });
+    return new Promise((resolvePromise, rejectPromise) => {
+        server.once("error", rejectPromise);
+        server.listen(options.port, "127.0.0.1", () => {
+            const address = server.address();
+            boundPort = typeof address === "object" && address !== null ? address.port : options.port;
+            resolvePromise({
+                url: `http://127.0.0.1:${boundPort}/?token=${token}`,
+                port: boundPort,
+                close: () => new Promise((done) => {
+                    // Server-sent event streams never end on their own: cut them.
+                    for (const socket of sockets)
+                        socket.destroy();
+                    server.close(() => done());
+                }),
+            });
+        });
+    });
+}
+/**
+ * Sends the last lines of the background `rowork dev` log, then each new line as it
+ * is written, as server-sent events. Polling the file (rather than a watcher) is the
+ * same on every OS and survives the log being restarted by a new `dev -d`.
+ */
+function streamLogs(request, response, projectRoot) {
+    response.writeHead(200, {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-store",
+        connection: "keep-alive",
+        "x-content-type-options": "nosniff",
+    });
+    const emit = (line) => {
+        response.write(`data: ${JSON.stringify(line)}\n\n`);
+    };
+    for (const line of tailLog(projectRoot, 200))
+        emit(line);
+    const file = logFile(projectRoot);
+    let offset = existsSync(file) ? statSync(file).size : 0;
+    let pending = "";
+    const timer = setInterval(() => {
+        if (!existsSync(file))
+            return;
+        const size = statSync(file).size;
+        if (size < offset)
+            offset = 0; // a new `dev -d` restarted the log
+        if (size === offset)
+            return;
+        const chunks = [];
+        const stream = createReadStream(file, { start: offset, end: size - 1 });
+        stream.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        stream.on("end", () => {
+            pending += Buffer.concat(chunks).toString("utf8");
+            const lines = pending.split("\n");
+            pending = lines.pop() ?? "";
+            for (const line of lines)
+                if (line !== "")
+                    emit(line);
+        });
+        offset = size;
+    }, 400);
+    request.on("close", () => clearInterval(timer));
+}
+//# sourceMappingURL=server.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Library entry point: re-exports the public contract and nothing else. */
+export * from "./plugins/api.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+/** Library entry point: re-exports the public contract and nothing else. */
+export * from "./plugins/api.js";
+//# sourceMappingURL=index.js.map

package/dist/main.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lets `rowork -d dev` mean `rowork dev -d`.
+ *
+ * Commander would treat a `-d` before the command as a global option, which
+ * does not exist. It is moved to just after the command name instead.
+ */
+export declare function hoistDetach(argv: string[]): string[];
+export declare function run(rawArgv: string[]): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,135 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import pc from "picocolors";
+import { isRoworkError } from "./cli/errors.js";
+import { createProgram } from "./cli/program.js";
+import { CommandRegistry, setActiveRegistry } from "./cli/registry.js";
+import { findProjectRoot, loadConfig } from "./core/config.js";
+import { coreCommands } from "./commands/index.js";
+import { loadPlugins } from "./plugins/loader.js";
+import { logger, setLogLevel } from "./ui/logger.js";
+const require = createRequire(import.meta.url);
+function roworkVersion() {
+    try {
+        return require("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Pre-reads the global flags.
+ *
+ * Commander only exposes them once parsing has started, but we need `--cwd`
+ * and `--no-plugins` BEFORE building the command list, since plugins add to it.
+ */
+function readGlobalFlags(argv) {
+    let cwd = process.cwd();
+    let plugins = true;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--cwd") {
+            const value = argv[index + 1];
+            if (value !== undefined)
+                cwd = resolve(value);
+        }
+        else if (token !== undefined && token.startsWith("--cwd=")) {
+            cwd = resolve(token.slice("--cwd=".length));
+        }
+        else if (token === "--no-plugins") {
+            plugins = false;
+        }
+        else if (token === "--verbose") {
+            setLogLevel("debug");
+        }
+        else if (token === "--quiet") {
+            setLogLevel("error");
+        }
+    }
+    return { cwd, plugins };
+}
+/**
+ * Lets `rowork -d dev` mean `rowork dev -d`.
+ *
+ * Commander would treat a `-d` before the command as a global option, which
+ * does not exist. It is moved to just after the command name instead.
+ */
+export function hoistDetach(argv) {
+    const head = argv.slice(0, 2);
+    const rest = argv.slice(2);
+    let detach = false;
+    const kept = [];
+    let commandIndex = -1;
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (commandIndex === -1 && (token === "-d" || token === "--detach")) {
+            detach = true;
+            continue;
+        }
+        kept.push(token);
+        if (commandIndex === -1 && token === "--cwd") {
+            // The value of --cwd is not the command.
+            const value = rest[index + 1];
+            if (value !== undefined) {
+                kept.push(value);
+                index += 1;
+            }
+        }
+        else if (commandIndex === -1 && !token.startsWith("-")) {
+            commandIndex = kept.length - 1;
+        }
+    }
+    if (detach && commandIndex !== -1)
+        kept.splice(commandIndex + 1, 0, "--detach");
+    else if (detach)
+        kept.push("--detach");
+    return [...head, ...kept];
+}
+export async function run(rawArgv) {
+    const argv = hoistDetach(rawArgv);
+    const version = roworkVersion();
+    const { cwd, plugins: pluginsEnabled } = readGlobalFlags(argv.slice(2));
+    const registry = new CommandRegistry();
+    for (const definition of coreCommands) {
+        registry.register(definition, { kind: "core" });
+    }
+    const projectRoot = findProjectRoot(cwd);
+    let config;
+    if (projectRoot !== undefined) {
+        try {
+            config = loadConfig(projectRoot);
+        }
+        catch (error) {
+            // A broken config must not make the CLI unusable: `rowork --help` and
+            // project-independent commands have to keep working.
+            logger.warn(error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (pluginsEnabled) {
+        await loadPlugins({ registry, projectRoot, config, cwd, roworkVersion: version });
+    }
+    else {
+        logger.debug("Plugin loading disabled (--no-plugins).");
+    }
+    setActiveRegistry(registry);
+    const program = createProgram({ registry, cwd, projectRoot, config, roworkVersion: version });
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+}
+function reportFailure(error) {
+    if (isRoworkError(error)) {
+        logger.error(error.message);
+        if (error.hint !== undefined) {
+            process.stderr.write(`${pc.dim("      " + error.hint)}\n`);
+        }
+        process.exit(error.exitCode);
+    }
+    logger.error("Internal Rowork error. Please open an issue with the trace below.");
+    console.error(error);
+    process.exit(1);
+}
+//# sourceMappingURL=main.js.map

package/dist/modules/format.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleDefinition } from "./types.js";
+export declare const formatModule: ModuleDefinition;
+//# sourceMappingURL=format.d.ts.map

package/dist/modules/format.js

@@ -0,0 +1,28 @@
+export const formatModule = {
+    name: "format",
+    title: "Formatter",
+    description: "Format the code the same way for everyone, automatically, with Prettier.",
+    dependencies: ["prettier"],
+    agentGuide: [
+        "Run `npm run format` after editing code: Prettier rewrites `src/` in the project's style (tabs, 100 columns). `npm run format:check` only reports. Do not argue with the formatter or hand-format around it.",
+        "Settings live in `.prettierrc.json`; what is never formatted (build output) is in `.prettierignore`.",
+    ],
+    plan() {
+        return {
+            files: [
+                { template: "format/prettierrc.json", directory: ".", fileName: ".prettierrc.json", variables: {} },
+                { template: "format/prettierignore", directory: ".", fileName: ".prettierignore", variables: {} },
+            ],
+            register: [],
+            scripts: {
+                format: "prettier --write src",
+                "format:check": "prettier --check src",
+            },
+            notes: [
+                "Format your code:  npm run format      Only check:  npm run format:check",
+                "Tabs and 100 columns, to match the code Rowork generates. Change it in .prettierrc.json.",
+            ],
+        };
+    },
+};
+//# sourceMappingURL=format.js.map

package/dist/modules/index.d.ts

@@ -0,0 +1,7 @@
+import type { ModuleDefinition } from "./types.js";
+/**
+ * Modules shipped with Rowork, listed explicitly like the core commands.
+ * Rule for adding one: it must be a chore almost every game redoes.
+ */
+export declare const coreModules: ModuleDefinition[];
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/index.js

@@ -0,0 +1,12 @@
+import { formatModule } from "./format.js";
+import { leaderstatsModule } from "./leaderstats.js";
+import { lintModule } from "./lint.js";
+import { networkingModule } from "./networking.js";
+import { playerDataModule } from "./player-data.js";
+import { uiModule } from "./ui.js";
+/**
+ * Modules shipped with Rowork, listed explicitly like the core commands.
+ * Rule for adding one: it must be a chore almost every game redoes.
+ */
+export const coreModules = [playerDataModule, leaderstatsModule, networkingModule, lintModule, formatModule, uiModule];
+//# sourceMappingURL=index.js.map

package/dist/modules/integrations.d.ts

@@ -0,0 +1,8 @@
+import type { IntegrationDefinition } from "./types.js";
+/**
+ * Glue between modules. Each entry applies once every module it lists is
+ * installed, in whichever order they were added.
+ */
+export declare const dataReplication: IntegrationDefinition;
+export declare const coreIntegrations: IntegrationDefinition[];
+//# sourceMappingURL=integrations.d.ts.map

package/dist/modules/integrations.js

@@ -0,0 +1,54 @@
+/**
+ * Glue between modules. Each entry applies once every module it lists is
+ * installed, in whichever order they were added.
+ */
+export const dataReplication = {
+    name: "data-replication",
+    title: "player data on the client",
+    description: "Sends each player's saved data to their client, for interfaces to read.",
+    modules: ["player-data", "networking"],
+    agentGuide: [
+        "The server sends each player's data to that player's client when it loads and each time it changes (`DataReplicationService`, server). Do not send it by hand.",
+        "On the client, inject `PlayerDataController` and use `get()` (undefined until the server has sent it) or `onChanged(cb)`. It is read-only: change data on the server with `PlayerDataService.update`.",
+    ],
+    plan({ config }) {
+        const eventsFile = `${config.paths.shared}/data/dataEvents`;
+        const dataFile = `${config.paths.shared}/data/PlayerData`;
+        return {
+            files: [
+                {
+                    template: "data-replication/dataEvents",
+                    directory: `${config.paths.shared}/data`,
+                    fileName: "dataEvents.ts",
+                    variables: { dataImport: `@import:${dataFile}` },
+                },
+                {
+                    template: "data-replication/DataReplicationService",
+                    directory: config.paths.services,
+                    fileName: "DataReplicationService.ts",
+                    variables: {
+                        eventsImport: `@import:${eventsFile}`,
+                        rateLimitImport: `@import:${config.paths.source}/server/rateLimit`,
+                    },
+                },
+                {
+                    template: "data-replication/PlayerDataController",
+                    directory: config.paths.controllers,
+                    fileName: "PlayerDataController.ts",
+                    variables: { dataImport: `@import:${dataFile}`, eventsImport: `@import:${eventsFile}` },
+                },
+            ],
+            register: [
+                { side: "server", directory: config.paths.services },
+                { side: "client", directory: config.paths.controllers },
+            ],
+            notes: [
+                "Player data now reaches the client. Client code reads it with PlayerDataController:",
+                "  constructor(private readonly playerData: PlayerDataController) {}",
+                "  this.playerData.onChanged((data) => { /* update the interface */ });",
+            ],
+        };
+    },
+};
+export const coreIntegrations = [dataReplication];
+//# sourceMappingURL=integrations.js.map

package/dist/modules/leaderstats.d.ts

@@ -0,0 +1,3 @@
+import type { ModuleDefinition } from "./types.js";
+export declare const leaderstatsModule: ModuleDefinition;
+//# sourceMappingURL=leaderstats.d.ts.map