rowork 0.1.0

package/dist/process/supervisor.js

@@ -0,0 +1,141 @@
+import spawn from "cross-spawn";
+import pc from "picocolors";
+import { pathWithLocalBinaries } from "../core/toolchain.js";
+import { createLineSplitter } from "./log-mux.js";
+import { killTree, killTreeSync } from "./tree-kill.js";
+const RECENT_OUTPUT_LINES = 12;
+/**
+ * Runs several long-lived tools side by side under one terminal.
+ *
+ * Two rules drive the design:
+ *
+ *  - A task dying is a hard stop. A `rowork dev` that keeps a Rojo server alive
+ *    after the compiler died would serve stale code while looking healthy,
+ *    which is worse than exiting.
+ *  - Nothing outlives the supervisor. Every exit path, including Ctrl+C and a
+ *    crash of the CLI itself, goes through a process-tree kill.
+ */
+export class Supervisor {
+    options;
+    running = [];
+    shuttingDown = false;
+    exitCode = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async run() {
+        const width = Math.max(...this.options.tasks.map((task) => task.name.length));
+        this.installSignalHandlers();
+        for (const definition of this.options.tasks) {
+            this.start(definition, width);
+        }
+        await Promise.all(this.running.map((task) => this.waitFor(task)));
+        return this.exitCode;
+    }
+    start(definition, width) {
+        const prefix = definition.paint(definition.name.padEnd(width));
+        const child = spawn(definition.command, definition.args, {
+            cwd: this.options.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            // A process group of its own, so the whole tree can be signalled at
+            // once. Not on Windows, where it would open a separate console window.
+            detached: process.platform !== "win32",
+            env: {
+                ...process.env,
+                // Children write to a pipe, not a TTY, so they would drop their
+                // colours. Most respect FORCE_COLOR, which keeps compiler
+                // diagnostics readable.
+                FORCE_COLOR: "1",
+                PATH: pathWithLocalBinaries(this.options.cwd),
+            },
+        });
+        const task = { definition, child, recentOutput: [], exited: false };
+        this.running.push(task);
+        const emit = (line, isStderr) => {
+            task.recentOutput.push(line);
+            if (task.recentOutput.length > RECENT_OUTPUT_LINES)
+                task.recentOutput.shift();
+            const text = `${prefix} ${pc.dim("|")} ${isStderr ? pc.yellow(line) : line}\n`;
+            process.stderr.write(text);
+            this.options.onOutput?.(text);
+        };
+        const stdout = createLineSplitter((line) => emit(line, false));
+        const stderr = createLineSplitter((line) => emit(line, true));
+        child.stdout?.on("data", (chunk) => stdout.push(chunk));
+        child.stderr?.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            emit(`could not start \`${definition.command}\`: ${error.message}`, true);
+        });
+        child.on("close", () => {
+            stdout.flush();
+            stderr.flush();
+        });
+    }
+    waitFor(task) {
+        return new Promise((resolve) => {
+            const settle = (code, signal) => {
+                if (task.exited)
+                    return;
+                task.exited = true;
+                if (!this.shuttingDown) {
+                    this.reportUnexpectedExit(task, code, signal);
+                    void this.shutdown(code ?? 1);
+                }
+                resolve();
+            };
+            task.child.on("close", settle);
+            task.child.on("error", () => settle(1, null));
+        });
+    }
+    /**
+     * Surfaces the failure loudly and replays the task's last lines.
+     *
+     * In a unified log the actual cause has usually scrolled past, buried under
+     * output from the tasks that are still healthy. Repeating it at the bottom
+     * is the difference between a usable orchestrator and a wall of text.
+     */
+    reportUnexpectedExit(task, code, signal) {
+        const reason = signal !== null ? `signal ${signal}` : `exit code ${String(code)}`;
+        const { logger } = this.options;
+        logger.blank();
+        logger.error(`Task \`${task.definition.name}\` stopped (${reason}). Shutting the others down.`);
+        if (task.recentOutput.length > 0) {
+            logger.info(pc.dim(`  last output from ${task.definition.name}:`));
+            for (const line of task.recentOutput)
+                logger.info(pc.dim(`    ${line}`));
+        }
+        logger.blank();
+    }
+    async shutdown(code) {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.exitCode = code;
+        await Promise.all(this.running.filter((task) => !task.exited).map((task) => killTree(task.child)));
+    }
+    installSignalHandlers() {
+        const onSignal = () => {
+            if (this.shuttingDown)
+                return;
+            this.options.logger.blank();
+            this.options.logger.info("Stopping...");
+            void this.shutdown(0);
+        };
+        // SIGHUP is what closing the terminal window sends. Without it the CLI
+        // dies on the spot, its "exit" handler never runs, and the tasks (each in
+        // a process group of their own) carry on with nobody to stop them,
+        // still holding the Rojo port. SIGBREAK is the Windows equivalent of
+        // Ctrl+Break and closing the console.
+        for (const signal of ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"]) {
+            process.once(signal, onSignal);
+        }
+        // Last resort: if the CLI itself throws, detached children would survive.
+        process.once("exit", () => {
+            for (const task of this.running) {
+                if (!task.exited)
+                    killTreeSync(task.child);
+            }
+        });
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/process/tree-kill.d.ts

@@ -0,0 +1,25 @@
+import { type ChildProcess } from "node:child_process";
+/**
+ * Terminates a child process AND every process it spawned.
+ *
+ * This is the single most important function in the orchestrator, and the
+ * classic failure of tools in this category: `child.kill()` only signals the
+ * direct child. `rbxtsc` and `rojo` are reached through wrapper shims, so the
+ * real worker is a grandchild that survives and keeps holding the output
+ * directory or the Rojo port. The user then hits a stale server on the next
+ * `rowork dev` with no idea why.
+ *
+ * Windows has no process groups, so we delegate to `taskkill /T`, which walks
+ * the tree itself. Elsewhere the child is spawned detached, which makes it a
+ * process-group leader, and a negative PID signals the whole group.
+ */
+export declare function killTree(child: ChildProcess, signal?: NodeJS.Signals): Promise<void>;
+/**
+ * Best-effort synchronous kill, for the `exit` handler.
+ *
+ * Node runs `exit` listeners synchronously and ignores anything asynchronous,
+ * so the promise-based path above is useless there. Detached children would
+ * otherwise outlive a crash of the CLI itself.
+ */
+export declare function killTreeSync(child: ChildProcess): void;
+//# sourceMappingURL=tree-kill.d.ts.map

package/dist/process/tree-kill.js

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+/**
+ * Terminates a child process AND every process it spawned.
+ *
+ * This is the single most important function in the orchestrator, and the
+ * classic failure of tools in this category: `child.kill()` only signals the
+ * direct child. `rbxtsc` and `rojo` are reached through wrapper shims, so the
+ * real worker is a grandchild that survives and keeps holding the output
+ * directory or the Rojo port. The user then hits a stale server on the next
+ * `rowork dev` with no idea why.
+ *
+ * Windows has no process groups, so we delegate to `taskkill /T`, which walks
+ * the tree itself. Elsewhere the child is spawned detached, which makes it a
+ * process-group leader, and a negative PID signals the whole group.
+ */
+export function killTree(child, signal = "SIGTERM") {
+    const pid = child.pid;
+    if (pid === undefined || child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve();
+    }
+    if (process.platform === "win32") {
+        return new Promise((resolve) => {
+            // /T kills the tree, /F forces it. Windows has no graceful equivalent
+            // for a non-console child, so there is nothing softer to try first.
+            const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+                stdio: "ignore",
+            });
+            killer.on("error", () => resolve());
+            killer.on("close", () => resolve());
+        });
+    }
+    try {
+        // Negative PID targets the process group, not just the leader.
+        process.kill(-pid, signal);
+    }
+    catch {
+        // Already gone, or never became a group leader. Fall back to the child.
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Nothing left to kill.
+        }
+    }
+    return Promise.resolve();
+}
+/**
+ * Best-effort synchronous kill, for the `exit` handler.
+ *
+ * Node runs `exit` listeners synchronously and ignores anything asynchronous,
+ * so the promise-based path above is useless there. Detached children would
+ * otherwise outlive a crash of the CLI itself.
+ */
+export function killTreeSync(child) {
+    const pid = child.pid;
+    if (pid === undefined || child.exitCode !== null)
+        return;
+    try {
+        if (process.platform === "win32") {
+            spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", detached: true });
+        }
+        else {
+            process.kill(-pid, "SIGKILL");
+        }
+    }
+    catch {
+        // Exiting anyway.
+    }
+}
+//# sourceMappingURL=tree-kill.js.map

package/dist/templates/engine.d.ts

@@ -0,0 +1,18 @@
+export type TemplateVariables = Readonly<Record<string, string>>;
+/** Root of the bundled templates, relative to the compiled dist/. */
+export declare function templatesRoot(): string;
+export declare function renderString(source: string, variables: TemplateVariables): string;
+/**
+ * Turns a template file name into its final name.
+ *
+ * - a trailing `.tmpl` is dropped
+ * - a leading `_` becomes `.`
+ *
+ * The `_` convention exists because npm always strips `.gitignore` files from
+ * published tarballs: a template literally named `.gitignore` would be missing
+ * from the installed package.
+ */
+export declare function resolveTemplateName(name: string, variables: TemplateVariables): string;
+/** Recursively copies a template directory, rendering both names and contents. */
+export declare function renderTree(sourceDirectory: string, targetDirectory: string, variables: TemplateVariables): string[];
+//# sourceMappingURL=engine.d.ts.map

package/dist/templates/engine.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RoworkError } from "../cli/errors.js";
+const PLACEHOLDER = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+/** Root of the bundled templates, relative to the compiled dist/. */
+export function templatesRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
+}
+export function renderString(source, variables) {
+    return source.replace(PLACEHOLDER, (match, key) => {
+        const value = variables[key];
+        if (value === undefined) {
+            throw new RoworkError(`Unknown template variable: \`${key}\`.`, {
+                hint: `Found in: ${match}`,
+            });
+        }
+        return value;
+    });
+}
+/**
+ * Turns a template file name into its final name.
+ *
+ * - a trailing `.tmpl` is dropped
+ * - a leading `_` becomes `.`
+ *
+ * The `_` convention exists because npm always strips `.gitignore` files from
+ * published tarballs: a template literally named `.gitignore` would be missing
+ * from the installed package.
+ */
+export function resolveTemplateName(name, variables) {
+    let output = name.endsWith(".tmpl") ? name.slice(0, -".tmpl".length) : name;
+    if (output.startsWith("_"))
+        output = `.${output.slice(1)}`;
+    return renderString(output, variables);
+}
+/** Recursively copies a template directory, rendering both names and contents. */
+export function renderTree(sourceDirectory, targetDirectory, variables) {
+    const written = [];
+    mkdirSync(targetDirectory, { recursive: true });
+    for (const entry of readdirSync(sourceDirectory)) {
+        const sourcePath = join(sourceDirectory, entry);
+        const targetPath = join(targetDirectory, resolveTemplateName(entry, variables));
+        if (statSync(sourcePath).isDirectory()) {
+            written.push(...renderTree(sourcePath, targetPath, variables));
+            continue;
+        }
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, renderString(readFileSync(sourcePath, "utf8"), variables), "utf8");
+        written.push(targetPath);
+    }
+    return written;
+}
+//# sourceMappingURL=engine.js.map

package/dist/ui/logger.d.ts

@@ -0,0 +1,5 @@
+import type { Logger } from "../plugins/api.js";
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+export declare function setLogLevel(level: LogLevel): void;
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/ui/logger.js

@@ -0,0 +1,53 @@
+import pc from "picocolors";
+const SEVERITY = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+let currentLevel = "info";
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+function allowed(level) {
+    return SEVERITY[level] <= SEVERITY[currentLevel];
+}
+/**
+ * Diagnostics go to stderr, never to stdout: stdout stays reserved for output
+ * meant to be piped (lists, paths, JSON).
+ */
+function write(line) {
+    process.stderr.write(`${line}\n`);
+}
+export const logger = {
+    debug(message) {
+        if (allowed("debug"))
+            write(`${pc.dim("debug")} ${pc.dim(message)}`);
+    },
+    info(message) {
+        if (allowed("info"))
+            write(message);
+    },
+    success(message) {
+        if (allowed("info"))
+            write(`${pc.green("done")}  ${message}`);
+    },
+    step(message) {
+        if (allowed("info"))
+            write(`${pc.dim("  -")} ${message}`);
+    },
+    warn(message) {
+        if (allowed("warn"))
+            write(`${pc.yellow("warn")}  ${message}`);
+    },
+    error(message) {
+        if (allowed("error"))
+            write(`${pc.red("error")} ${message}`);
+    },
+    blank() {
+        if (allowed("info"))
+            write("");
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/ui/prompt.d.ts

@@ -0,0 +1,9 @@
+import * as prompts from "@clack/prompts";
+export { prompts };
+/** True when a person can answer questions: both ends are a terminal. */
+export declare function isInteractive(): boolean;
+/** Fails with the non-interactive form when the command cannot ask its questions. */
+export declare function requireInteractive(command: string, usage: string): void;
+/** Ends a guided flow cleanly on Ctrl+C or Escape instead of throwing a stack trace. */
+export declare function answered<T>(value: T): Exclude<T, symbol>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/ui/prompt.js

@@ -0,0 +1,24 @@
+import * as prompts from "@clack/prompts";
+import { RoworkError } from "../cli/errors.js";
+export { prompts };
+/** True when a person can answer questions: both ends are a terminal. */
+export function isInteractive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+/** Fails with the non-interactive form when the command cannot ask its questions. */
+export function requireInteractive(command, usage) {
+    if (!isInteractive()) {
+        throw new RoworkError(`\`rowork ${command}\` needs a terminal to ask its questions.`, {
+            hint: `Outside a terminal, give everything on the command line: ${usage}`,
+        });
+    }
+}
+/** Ends a guided flow cleanly on Ctrl+C or Escape instead of throwing a stack trace. */
+export function answered(value) {
+    if (prompts.isCancel(value)) {
+        prompts.cancel("Cancelled, nothing was created.");
+        process.exit(0);
+    }
+    return value;
+}
+//# sourceMappingURL=prompt.js.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "rowork",
+  "version": "0.1.0",
+  "description": "The meta-framework CLI for Roblox game development. Orchestrates Rojo, roblox-ts and Flamework, and scaffolds your game architecture.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nokogoat/Rowork.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nokogoat/Rowork/issues"
+  },
+  "homepage": "https://github.com/nokogoat/Rowork#readme",
+  "bin": {
+    "rowork": "bin/rowork.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin": "./dist/plugins/api.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "dashboard",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc -p tsconfig.json --watch",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "test": "npm run build && npm run test:smoke && npm run test:orphan && npm run test:assets && npm run test:integration",
+    "prepublishOnly": "npm run test",
+    "rowork": "node bin/rowork.js",
+    "test:orphan": "node scripts/dev-orphan-test.mjs",
+    "test:assets": "node scripts/assets-test.mjs",
+    "test:integration": "node scripts/integration-test.mjs"
+  },
+  "keywords": [
+    "roblox",
+    "roblox-ts",
+    "flamework",
+    "rojo",
+    "cli",
+    "framework",
+    "scaffolding",
+    "gamedev"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^12.1.0",
+    "cross-spawn": "^7.0.6",
+    "fflate": "^0.8.3",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/init/README.md.tmpl

@@ -0,0 +1,37 @@
+# {{ name }}
+
+Roblox project generated by [Rowork](https://github.com/nokogoat/Rowork) v{{ roworkVersion }}.
+
+## Stack
+
+- **roblox-ts**: TypeScript compiled to Luau
+- **Flamework**: services, controllers, dependency injection
+- **Rojo**: file syncing into Roblox Studio
+- **Rokit**: pinned tool versions
+
+## Getting started
+
+`rowork init` already installed the npm dependencies and the pinned toolchain,
+so there is nothing left to set up.
+
+```bash
+rowork dev           # compiler, Rojo server and sourcemap watcher, together
+```
+
+## Layout
+
+```
+src/
+  server/services/       Flamework services (server-side logic)
+  client/controllers/    Flamework controllers (client-side logic)
+  shared/                code shared between server and client
+```
+
+`runtime.server.ts` and `runtime.client.ts` are the entry points: they declare
+which directories to scan, then call `Flamework.ignite()`.
+
+## Rowork configuration
+
+`rowork.json` describes the project paths and the active plugins. `tsconfig.json`,
+`default.project.json` and `package.json` remain standard files you can edit
+directly: Rowork never hides them.

package/templates/init/_gitignore.tmpl

@@ -0,0 +1,23 @@
+node_modules/
+out/
+# roblox-ts runtime and Flamework build cache: both are regenerated by the compiler.
+include/
+flamework.build
+*.tsbuildinfo
+
+# Rojo / build artefacts
+*.rbxl
+*.rbxlx
+*.rbxl.lock
+*.rbxlx.lock
+sourcemap.json
+
+# Background `rowork dev`: its pid and log.
+.rowork/run/
+
+# Secrets: never commit an Open Cloud key or a Roblox cookie.
+.env
+.env.*
+
+.DS_Store
+Thumbs.db

package/templates/init/default.project.json.tmpl

@@ -0,0 +1,57 @@
+{
+  "name": "{{ name }}",
+  "globIgnorePaths": ["**/package.json", "**/tsconfig.json"],
+  "tree": {
+    "$className": "DataModel",
+
+    "ServerScriptService": {
+      "TS": {
+        "$path": "out/server"
+      }
+    },
+
+    "ReplicatedStorage": {
+      "rbxts_include": {
+        "$path": "include",
+        "node_modules": {
+          "$className": "Folder",
+          "@flamework": {
+            "$path": "node_modules/@flamework"
+          },
+          "@rbxts": {
+            "$path": "node_modules/@rbxts"
+          }
+        }
+      },
+      "TS": {
+        "$path": "out/shared"
+      }
+    },
+
+    "StarterPlayer": {
+      "StarterPlayerScripts": {
+        "TS": {
+          "$path": "out/client"
+        }
+      }
+    },
+
+    "Workspace": {
+      "$properties": {
+        "FilteringEnabled": true
+      }
+    },
+
+    "SoundService": {
+      "$properties": {
+        "RespectFilteringEnabled": true
+      }
+    },
+
+    "HttpService": {
+      "$properties": {
+        "HttpEnabled": true
+      }
+    }
+  }
+}

package/templates/init/package.json.tmpl

@@ -0,0 +1,12 @@
+{
+  "name": "{{ packageName }}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "rowork dev",
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/templates/init/rokit.toml.tmpl

@@ -0,0 +1,5 @@
+# Pinned toolchain, managed by Rokit: https://github.com/rojo-rbx/rokit
+# `rokit install` gives every contributor these exact versions.
+# Move to a newer Rojo with `rowork update`.
+[tools]
+rojo = "rojo-rbx/rojo@{{ rojoVersion }}"

package/templates/init/src/client/controllers/ExampleController.ts.tmpl

@@ -0,0 +1,12 @@
+import { Controller, OnStart } from "@flamework/core";
+
+/**
+ * A controller is the client-side counterpart of a service.
+ * Generate more with `rowork make:controller <Name>`.
+ */
+@Controller()
+export class ExampleController implements OnStart {
+	onStart(): void {
+		print("[{{ name }}] ExampleController started.");
+	}
+}

package/templates/init/src/client/runtime.client.ts.tmpl

@@ -0,0 +1,6 @@
+import { Flamework } from "@flamework/core";
+
+/** Client entry point. See runtime.server.ts for how addPaths works. */
+Flamework.addPaths("src/client/controllers");
+
+Flamework.ignite();

package/templates/init/src/server/runtime.server.ts.tmpl

@@ -0,0 +1,12 @@
+import { Flamework } from "@flamework/core";
+
+/**
+ * Server entry point.
+ *
+ * `addPaths` takes paths relative to the project root. They are resolved at
+ * compile time by the Flamework transformer, which relies on the Rojo project:
+ * any directory added here must exist and be exposed in default.project.json.
+ */
+Flamework.addPaths("src/server/services");
+
+Flamework.ignite();

package/templates/init/src/server/services/ExampleService.ts.tmpl

@@ -0,0 +1,12 @@
+import { OnStart, Service } from "@flamework/core";
+
+/**
+ * A service is a server-side singleton, instantiated and injected by Flamework.
+ * Generate more with `rowork make:service <Name>`.
+ */
+@Service()
+export class ExampleService implements OnStart {
+	onStart(): void {
+		print("[{{ name }}] ExampleService started.");
+	}
+}