rowork 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 julian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# Rowork
+
+**The meta-framework CLI for Roblox game development.**
+
+Rowork is to Roblox what `artisan` is to Laravel: a single CLI that sets up the
+toolchain, runs it, generates code and keeps your architecture coherent.
+
+> ## ⚠️ This is only the very beginning
+>
+> Rowork is at **version 0.0.1**. The goal is big: a real **meta-framework for Roblox**, from the first
+> line of a project to a live game. **What exists today is a small first step towards it**, and most of the
+> vision is not built yet.
+>
+> - **Expect missing features, bugs and breaking changes** without warning.
+> - **It is not on npm yet**, and it has been tried on very few games.
+> - **Do not build a serious game on it yet.** Come and look, try it, and tell us what is wrong.
+>
+> The [roadmap](docs/roadmap.md) says what exists and what is missing, without promises.
+
+## The problem
+
+Starting a modern Roblox project means wiring Rojo, roblox-ts, Flamework, a
+pinned toolchain and a package manager together by hand: either several hours of
+setup, or a GitHub template that goes stale in three months. And once the project
+is running, nothing keeps file #200 consistent with the architecture of file #1.
+
+## What Rowork does
+
+- **Generates.** `rowork start` walks you through creating a project;
+  `rowork init` does it without questions. `make:service`, `make:controller`
+  and `make:component` create Flamework classes and register them; `make:stat` and
+  `make:event` extend your saved data and networking without a forgotten line, and `make:screen` and `make:ui`
+  build your interface without plumbing.
+- **Orchestrates.** `rowork dev` runs the roblox-ts compiler, the Rojo server
+  and a sourcemap watcher together, with unified logs and a clean shutdown.
+- **Installs the toolchain.** Rokit and Rojo can be installed for you, with the
+  download verified by checksum.
+- **Extends.** A plugin system so the community can add its own commands.
+
+## What is not there yet
+
+Rowork is at the start, and a lot is still missing. Today there is **nothing** for:
+
+- **an existing project**: `rowork init` starts a new one, nothing adopts a game that already exists;
+- **changing your saved data** once players already have some (migrations);
+- **tests for your game**, several environments (development, production), feature flags, monitoring;
+- **seeing your interface in a browser** (only the UI Labs plugin inside Studio);
+- **a plugin ecosystem**: the plugin API is tiny and will change, and no plugin exists yet;
+- **Wally packages from TypeScript**, or anything outside roblox-ts, Flamework and Rojo.
+
+## What Rowork does not do
+
+Rowork does not replace Rojo, roblox-ts, Flamework or Wally: it drives them.
+`default.project.json`, `tsconfig.json` and `package.json` stay plain, visible,
+editable files, and you can drop down to the bare tools at any time.
+**No lock-in.**
+
+## Quick start
+
+Rowork is not on npm yet, so install it from the repository:
+
+```bash
+git clone https://github.com/nokogoat/Rowork
+cd Rowork && npm install && npm run build && npm link
+```
+
+Then:
+
+```bash
+rowork start         # guided setup: a few questions, then a ready project
+cd MyGame
+rowork dev           # compiler + Rojo + sourcemap, together
+```
+
+Connect the Rojo plugin in Studio and you are live. The full walkthrough,
+including Studio, is in [Getting started](docs/getting-started.md).
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | install, create a project, see it in Studio |
+| [Commands](docs/commands.md) | every command and flag |
+| [Project structure](docs/project-structure.md) | what is generated, where your code goes |
+| [Configuration](docs/configuration.md) | `rowork.json` |
+| [How `rowork dev` works](docs/dev-command.md) | orchestration, first build, shutdown |
+| [Plugins](docs/plugins.md) | write and share commands |
+| [Troubleshooting](docs/troubleshooting.md) | fix an error message |
+| [Architecture](docs/architecture.md) | the codebase and its decisions |
+| [Contributing](docs/contributing.md) | development setup and workflow |
+| [Roadmap](docs/roadmap.md) | what exists, what is next |
+
+## License
+
+MIT

package/bin/rowork.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, "..", "dist", "main.js");
+
+if (!existsSync(entry)) {
+	console.error("Rowork is not built. Run `npm run build` at the repository root.");
+	process.exit(1);
+}
+
+// pathToFileURL is mandatory: `import("G:\...\main.js")` fails on Windows,
+// because an absolute Windows path is not a valid URL.
+const { run } = await import(pathToFileURL(entry).href);
+
+await run(process.argv);

package/dashboard/app.css

@@ -0,0 +1,234 @@
+:root {
+	--bg: #f6f7f9;
+	--card: #ffffff;
+	--text: #1c2330;
+	--muted: #5b6577;
+	--line: #dfe3ea;
+	--accent: #3b6cff;
+	--good: #1c8c4e;
+	--warn: #b76e00;
+	--code: #eef1f6;
+	--log-bg: #10141c;
+	--log-text: #d5dbe8;
+}
+@media (prefers-color-scheme: dark) {
+	:root {
+		--bg: #0e1218;
+		--card: #161c26;
+		--text: #e7ebf3;
+		--muted: #93a0b5;
+		--line: #262f3d;
+		--accent: #7b9bff;
+		--good: #4cc38a;
+		--warn: #e0a545;
+		--code: #1f2733;
+		--log-bg: #0a0d13;
+		--log-text: #d5dbe8;
+	}
+}
+* {
+	box-sizing: border-box;
+}
+body {
+	margin: 0;
+	background: var(--bg);
+	color: var(--text);
+	font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+.top {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px 24px;
+	align-items: baseline;
+	justify-content: space-between;
+	padding: 16px 24px 8px;
+}
+.logo {
+	font-size: 20px;
+	font-weight: 700;
+	letter-spacing: 0.2px;
+}
+.version {
+	margin-left: 8px;
+	color: var(--muted);
+}
+.project {
+	color: var(--muted);
+	overflow-wrap: anywhere;
+}
+.tabs {
+	display: flex;
+	gap: 4px;
+	padding: 0 24px;
+	border-bottom: 1px solid var(--line);
+}
+.tab {
+	appearance: none;
+	border: 0;
+	background: none;
+	color: var(--muted);
+	padding: 10px 14px;
+	font: inherit;
+	cursor: pointer;
+	border-bottom: 2px solid transparent;
+}
+.tab.active {
+	color: var(--text);
+	border-bottom-color: var(--accent);
+}
+main {
+	max-width: 1100px;
+	margin: 0 auto;
+	padding: 20px 24px 40px;
+}
+.panel {
+	display: none;
+}
+.panel.active {
+	display: block;
+}
+.grid {
+	display: grid;
+	gap: 16px;
+	grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+	margin-bottom: 16px;
+}
+.card {
+	background: var(--card);
+	border: 1px solid var(--line);
+	border-radius: 12px;
+	padding: 16px 18px;
+}
+h2 {
+	margin: 0 0 4px;
+	font-size: 16px;
+}
+.hint {
+	margin: 0 0 12px;
+	color: var(--muted);
+	font-size: 13px;
+}
+code {
+	background: var(--code);
+	padding: 1px 6px;
+	border-radius: 5px;
+	font: 13px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+.list {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+}
+.list li {
+	display: flex;
+	gap: 10px;
+	align-items: baseline;
+	padding: 8px 0;
+	border-top: 1px solid var(--line);
+}
+.list li:first-child {
+	border-top: 0;
+}
+.list .name {
+	font-weight: 600;
+	min-width: 110px;
+}
+.list .desc {
+	color: var(--muted);
+	flex: 1;
+}
+.badge {
+	font-size: 11px;
+	padding: 1px 8px;
+	border-radius: 999px;
+	border: 1px solid var(--line);
+	white-space: nowrap;
+}
+.badge.installed,
+.badge.applied {
+	color: var(--good);
+	border-color: var(--good);
+}
+.badge.guided {
+	color: var(--warn);
+	border-color: var(--warn);
+}
+.commands {
+	display: grid;
+	gap: 2px 24px;
+	grid-template-columns: repeat(auto-fit, minmax(380px, 1fr));
+}
+.command {
+	display: flex;
+	gap: 10px;
+	align-items: baseline;
+	padding: 6px 0;
+	border-top: 1px solid var(--line);
+}
+.command .cmd {
+	font: 13px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+	min-width: 150px;
+}
+.command .desc {
+	color: var(--muted);
+	font-size: 13px;
+	flex: 1;
+}
+.row {
+	display: flex;
+	gap: 12px;
+	align-items: center;
+	justify-content: space-between;
+}
+.status {
+	font-size: 13px;
+	color: var(--muted);
+}
+.status.on {
+	color: var(--good);
+}
+.check {
+	color: var(--muted);
+	font-size: 13px;
+}
+.ghost {
+	appearance: none;
+	background: none;
+	border: 1px solid var(--line);
+	color: var(--text);
+	border-radius: 8px;
+	padding: 4px 12px;
+	font: inherit;
+	font-size: 13px;
+	cursor: pointer;
+}
+.log {
+	margin: 10px 0 0;
+	height: 60vh;
+	overflow: auto;
+	background: var(--log-bg);
+	color: var(--log-text);
+	border-radius: 10px;
+	padding: 12px 14px;
+	font: 12.5px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+	white-space: pre-wrap;
+	overflow-wrap: anywhere;
+}
+footer {
+	text-align: center;
+	color: var(--muted);
+	font-size: 12px;
+	padding: 0 0 24px;
+}
+@media (max-width: 600px) {
+	.top,
+	.tabs,
+	main {
+		padding-left: 14px;
+		padding-right: 14px;
+	}
+	.list .name,
+	.command .cmd {
+		min-width: 0;
+	}
+}

package/dashboard/app.js

@@ -0,0 +1,117 @@
+/*
+ * Rowork dashboard. No framework, no build step, no network access beyond the
+ * server that served this page.
+ *
+ * Everything that comes from outside (tool output, command names, descriptions) is
+ * put on the page with textContent, never as HTML: a hostile line in a log must not
+ * be able to run script in this page.
+ */
+(() => {
+	"use strict";
+
+	const $ = (id) => document.getElementById(id);
+
+	/** Builds an element with text only. */
+	function el(tag, className, text) {
+		const node = document.createElement(tag);
+		if (className) node.className = className;
+		if (text !== undefined) node.textContent = text;
+		return node;
+	}
+
+	function clear(node) {
+		while (node.firstChild) node.removeChild(node.firstChild);
+	}
+
+	// ---- tabs
+	for (const tab of document.querySelectorAll(".tab")) {
+		tab.addEventListener("click", () => {
+			for (const other of document.querySelectorAll(".tab")) other.classList.toggle("active", other === tab);
+			for (const panel of document.querySelectorAll(".panel")) {
+				panel.classList.toggle("active", panel.id === tab.dataset.tab);
+			}
+		});
+	}
+
+	// ---- overview
+	function renderInfo(info) {
+		$("version").textContent = `v${info.rowork.version}`;
+		$("project").textContent = info.project
+			? `${info.project.name}  ·  ${info.project.root}`
+			: "Not inside a Rowork project";
+
+		const modules = $("modules");
+		clear(modules);
+		for (const module of info.modules) {
+			const item = el("li");
+			item.appendChild(el("span", "name", module.title));
+			item.appendChild(el("span", "desc", module.description));
+			item.appendChild(
+				module.installed ? el("span", "badge installed", "installed") : el("code", "", `rowork add ${module.name}`),
+			);
+			modules.appendChild(item);
+		}
+
+		const integrations = $("integrations");
+		clear(integrations);
+		for (const integration of info.integrations) {
+			const item = el("li");
+			item.appendChild(el("span", "name", integration.modules.join(" + ")));
+			item.appendChild(el("span", "desc", integration.description));
+			item.appendChild(
+				integration.applied ? el("span", "badge applied", "wired") : el("span", "badge", "waiting for both"),
+			);
+			integrations.appendChild(item);
+		}
+
+		const commands = $("commands");
+		clear(commands);
+		for (const command of info.commands) {
+			const item = el("div", "command");
+			item.appendChild(el("span", "cmd", `rowork ${command.name}`));
+			item.appendChild(el("span", "desc", command.description));
+			if (command.guided) item.appendChild(el("span", "badge guided", "guided"));
+			commands.appendChild(item);
+		}
+
+		const dev = info.project && info.project.dev;
+		const status = $("dev-status");
+		status.textContent = dev
+			? `running ${dev.mode === "foreground" ? "in a terminal" : "in the background"} (pid ${dev.pid}, port ${dev.port})`
+			: "not running";
+		status.className = dev ? "status on" : "status";
+	}
+
+	async function refresh() {
+		try {
+			const response = await fetch("/api/info", { cache: "no-store" });
+			if (response.ok) renderInfo(await response.json());
+		} catch {
+			// The server stopped: keep what is on screen.
+		}
+	}
+	refresh();
+	setInterval(refresh, 3000);
+
+	// ---- dev output
+	const ANSI = /\u001b\[[0-9;?]*[A-Za-z]/g;
+	const log = $("log");
+	const MAX_LINES = 2000;
+
+	function addLine(text) {
+		log.appendChild(document.createTextNode(`${text.replace(ANSI, "")}\n`));
+		while (log.childNodes.length > MAX_LINES) log.removeChild(log.firstChild);
+		if ($("follow").checked) log.scrollTop = log.scrollHeight;
+	}
+
+	const stream = new EventSource("/api/dev/logs");
+	stream.onmessage = (event) => {
+		try {
+			addLine(JSON.parse(event.data));
+		} catch {
+			// Ignore a malformed message rather than break the stream.
+		}
+	};
+
+	$("clear").addEventListener("click", () => clear(log));
+})();

package/dashboard/index.html

@@ -0,0 +1,67 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>Rowork dashboard</title>
+		<link rel="stylesheet" href="/app.css" />
+	</head>
+	<body>
+		<header class="top">
+			<div class="brand">
+				<span class="logo">Rowork</span>
+				<span class="version" id="version"></span>
+			</div>
+			<div class="project" id="project">Loading…</div>
+		</header>
+
+		<nav class="tabs" role="tablist">
+			<button class="tab active" role="tab" data-tab="overview">Overview</button>
+			<button class="tab" role="tab" data-tab="dev">Dev output</button>
+		</nav>
+
+		<main>
+			<section id="overview" class="panel active">
+				<div class="grid">
+					<div class="card">
+						<h2>Features</h2>
+						<p class="hint">Ready-made features. Add one with <code>rowork add</code>.</p>
+						<ul class="list" id="modules"></ul>
+					</div>
+					<div class="card">
+						<h2>Wired together</h2>
+						<p class="hint">Glue Rowork generated between features.</p>
+						<ul class="list" id="integrations"></ul>
+					</div>
+				</div>
+				<div class="card">
+					<h2>Commands</h2>
+					<p class="hint">
+						<span class="badge guided">guided</span> commands ask their questions in the terminal.
+					</p>
+					<div class="commands" id="commands"></div>
+				</div>
+			</section>
+
+			<section id="dev" class="panel">
+				<div class="card">
+					<div class="row">
+						<h2>Dev</h2>
+						<span class="status" id="dev-status"></span>
+					</div>
+					<p class="hint">
+						Output of <code>rowork dev</code>, live, compiler errors included.
+					</p>
+					<div class="row">
+						<label class="check"><input type="checkbox" id="follow" checked /> Follow</label>
+						<button class="ghost" id="clear">Clear</button>
+					</div>
+					<pre class="log" id="log" aria-live="polite"></pre>
+				</div>
+			</section>
+		</main>
+
+		<footer>Local only. This page is served by <code>rowork dashboard</code> on your computer.</footer>
+		<script src="/app.js"></script>
+	</body>
+</html>

package/dist/cli/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An expected, user-facing error: short message plus a resolution hint.
+ * Anything else (an internal bug) surfaces as a full stack trace.
+ */
+export declare class RoworkError extends Error {
+    readonly hint: string | undefined;
+    readonly exitCode: number;
+    constructor(message: string, options?: {
+        hint?: string;
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
+export declare function isRoworkError(error: unknown): error is RoworkError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cli/errors.js

@@ -0,0 +1,18 @@
+/**
+ * An expected, user-facing error: short message plus a resolution hint.
+ * Anything else (an internal bug) surfaces as a full stack trace.
+ */
+export class RoworkError extends Error {
+    hint;
+    exitCode;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "RoworkError";
+        this.hint = options.hint;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+export function isRoworkError(error) {
+    return error instanceof RoworkError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/program.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import type { RoworkConfig } from "../plugins/api.js";
+import type { CommandRegistry } from "./registry.js";
+export interface ProgramOptions {
+    registry: CommandRegistry;
+    cwd: string;
+    projectRoot: string | undefined;
+    config: RoworkConfig | undefined;
+    roworkVersion: string;
+}
+/**
+ * Builds the Commander instance from the registry.
+ *
+ * Core commands and plugin commands go through exactly the same path: the core
+ * consumes its own public contract, which guarantees that a regression in the
+ * plugin API also breaks the CLI, and is therefore noticed immediately.
+ */
+export declare function createProgram(options: ProgramOptions): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/program.js

@@ -0,0 +1,59 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../ui/logger.js";
+/**
+ * Builds the Commander instance from the registry.
+ *
+ * Core commands and plugin commands go through exactly the same path: the core
+ * consumes its own public contract, which guarantees that a regression in the
+ * plugin API also breaks the CLI, and is therefore noticed immediately.
+ */
+export function createProgram(options) {
+    const program = new Command();
+    program
+        .name("rowork")
+        .description("The meta-framework CLI for Roblox game development.")
+        .version(options.roworkVersion, "-v, --version")
+        .option("--cwd <dir>", "working directory")
+        .option("--verbose", "verbose logging")
+        .option("--quiet", "only print errors")
+        .option("--no-plugins", "start without loading any plugin")
+        .showHelpAfterError()
+        .configureHelp({ sortSubcommands: true });
+    for (const { definition } of options.registry.all()) {
+        const command = program.command(definition.name).description(definition.description);
+        for (const alias of definition.aliases ?? [])
+            command.alias(alias);
+        for (const argument of definition.arguments ?? []) {
+            const required = argument.required ?? true;
+            const inner = argument.variadic ? `${argument.name}...` : argument.name;
+            const token = required ? `<${inner}>` : `[${inner}]`;
+            command.argument(token, argument.description, argument.defaultValue);
+        }
+        for (const option of definition.options ?? []) {
+            command.option(option.flags, option.description, option.defaultValue);
+        }
+        command.action(async (...invocation) => {
+            // Commander passes: ...positional arguments, options, then the Command.
+            const positional = invocation.slice(0, -2);
+            const commandOptions = (invocation.at(-2) ?? {});
+            const args = {};
+            (definition.arguments ?? []).forEach((argument, index) => {
+                args[argument.name] = positional[index];
+            });
+            const context = {
+                args,
+                options: commandOptions,
+                cwd: options.cwd,
+                projectRoot: options.projectRoot,
+                config: options.config,
+                logger,
+                roworkVersion: options.roworkVersion,
+            };
+            await definition.run(context);
+        });
+    }
+    program.addHelpText("after", `\n${pc.dim("Docs: https://github.com/nokogoat/Rowork")}\n`);
+    return program;
+}
+//# sourceMappingURL=program.js.map