rowork 0.1.0

package/dist/modules/types.d.ts

@@ -0,0 +1,96 @@
+import type { CommandOption, Logger, RoworkConfig } from "../plugins/api.js";
+/** One file a module writes into the project. */
+export interface ModuleFile {
+    /** Template under `templates/modules/`, without the `.ts.tmpl` suffix. */
+    template: string;
+    /** Destination directory, relative to the project root. */
+    directory: string;
+    fileName: string;
+    variables: Record<string, string>;
+}
+/** Everything a module decided to do, once its options are known. */
+export interface ModulePlan {
+    files: ModuleFile[];
+    /** Flamework directories the module's classes live in, to be registered. */
+    register: {
+        side: "server" | "client";
+        directory: string;
+    }[];
+    /** tsconfig.json `compilerOptions` to set (JSX, for the UI module). See `core/tsconfig-edit.ts`. */
+    compilerOptions?: Record<string, string>;
+    /** npm scopes to map into the game in default.project.json (`@rbxts-js` for React). See `core/rojo-edit.ts`. */
+    nodeModuleScopes?: string[];
+    /** npm scripts to add to package.json. One that already exists is never overwritten. */
+    scripts?: Record<string, string>;
+    /** Short lines printed after installation: what was added, what to do next. */
+    notes: string[];
+}
+/**
+ * What two or more modules generate together once all of them are installed:
+ * the glue that would otherwise be written by hand. It applies whichever module
+ * was added last, so the order of installation never changes the result.
+ */
+export interface IntegrationDefinition {
+    /** Unique, kebab-case. Recorded in rowork.json once applied. */
+    name: string;
+    title: string;
+    description: string;
+    /** Every one of these modules must be installed. */
+    modules: string[];
+    /** How to use what it adds, for the project's AGENTS.md. */
+    agentGuide?: string[];
+    plan(input: {
+        config: RoworkConfig;
+        projectRoot: string;
+    }): ModulePlan;
+}
+export interface PlanInput {
+    /** True when the user ran the command with no options: ask the questions. */
+    guided: boolean;
+    options: Readonly<Record<string, unknown>>;
+    config: RoworkConfig;
+    /** Root of the project, for modules that read what is already there. */
+    projectRoot: string;
+}
+/**
+ * A module: a small, readable set of files copied into the user's project.
+ *
+ * The user owns those files afterwards and is expected to read and edit them,
+ * which is why a module never installs an opaque runtime of its own.
+ */
+export interface ModuleDefinition {
+    /** Kebab-case identifier, also the command suffix: `add:<name>`. */
+    name: string;
+    /** Human name shown in menus. */
+    title: string;
+    description: string;
+    /** Other modules that must be installed first. */
+    requires?: string[];
+    /** npm packages to install. Versions are resolved by npm, never hardcoded. */
+    dependencies?: string[];
+    /**
+     * How to use the module once installed, written for whoever reads the
+     * project's AGENTS.md next: a person learning it, or an AI working in it.
+     * Short imperative lines: where the code is, what to call, what to edit.
+     */
+    agentGuide?: string[];
+    /**
+     * Whether running it with no option asks questions. Defaults to "it has options".
+     * A module whose options are only switches (`--no-plugin`) sets this to false so
+     * it still runs without a terminal.
+     */
+    asksQuestions?: boolean;
+    /**
+     * Work that is not files or npm packages, run after everything else. Its failure
+     * never undoes the install: it is reported and the user can finish by hand.
+     */
+    postInstall?(input: {
+        logger: Logger;
+        projectRoot: string;
+        options: Readonly<Record<string, unknown>>;
+    }): Promise<void>;
+    /** Flags for the scripted form. */
+    options?: CommandOption[];
+    plan(input: PlanInput): Promise<ModulePlan> | ModulePlan;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/modules/ui.d.ts

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

package/dist/modules/ui.js

@@ -0,0 +1,67 @@
+import { RoworkError } from "../cli/errors.js";
+import { findStudioDataDirectories, installReleasePlugin, needsStudioSetup, UI_LABS } from "../core/studio.js";
+export const uiModule = {
+    name: "ui",
+    title: "User interface (React)",
+    description: "Build your interface with React, and preview each component in Studio without running the game.",
+    dependencies: ["@rbxts/react", "@rbxts/react-roblox", "@rbxts/ui-labs"],
+    asksQuestions: false,
+    options: [{ flags: "--no-plugin", description: "do not install the UI Labs preview plugin in Studio" }],
+    agentGuide: [
+        "The interface is React (`@rbxts/react`), in `src/client/ui/`. One component per file: a function that returns JSX. Lowercase tags (`frame`, `textbutton`, `textlabel`...) are Roblox instances; your own components start with a capital. Use hooks (`useState`, `useEffect`); do not create or change Instances by hand inside a component.",
+        "Roblox events in JSX use `Event={{ Activated: () => ... }}`; properties are the Roblox property names (`Size`, `Position`, `BackgroundColor3`...).",
+        "The interface is made of screens and elements. A **screen** is a component that returns a `screengui` (`src/client/ui/screens/<Name>Screen.tsx`); `App` lists them between the `{/* rowork:screens */}` marker, and `UiController` draws `App` into the player's PlayerGui. An **element** is a reusable component (`src/client/ui/<Name>.tsx`) with a `.story.tsx` next to it that shows it alone in Studio through the UI Labs plugin.",
+        "Create them with `rowork make:screen <name>` and `rowork make:ui <name> --kind button|label|panel|image --in <Screen>`: they put the file in the right place and add it to `App` or to the screen for you. Do not edit `App.tsx` by hand to add a screen, and keep the `{/* rowork:screens */}` and `{/* rowork:elements */}` markers: they are how Rowork knows where to add.",
+        "The interface reads data from the server: with the `player-data` and `networking` modules, use `PlayerDataController` (`get()`, `onChanged`) rather than asking again. Never trust the client for game rules: a button sends an event, the server decides.",
+    ],
+    plan({ config }) {
+        const ui = `${config.paths.source}/client/ui`;
+        return {
+            files: [
+                { template: "ui/App.tsx", directory: ui, fileName: "App.tsx", variables: {} },
+                { template: "ui/screens/HomeScreen.tsx", directory: `${ui}/screens`, fileName: "HomeScreen.tsx", variables: {} },
+                { template: "ui/Button.tsx", directory: ui, fileName: "Button.tsx", variables: {} },
+                { template: "ui/Button.story.tsx", directory: ui, fileName: "Button.story.tsx", variables: {} },
+                {
+                    template: "ui/UiController.tsx",
+                    directory: config.paths.controllers,
+                    fileName: "UiController.tsx",
+                    variables: { appImport: `@import:${ui}/App` },
+                },
+            ],
+            register: [{ side: "client", directory: config.paths.controllers }],
+            // roblox-ts turns JSX into calls to this factory: it must be React's.
+            compilerOptions: { jsx: "react", jsxFactory: "React.createElement", jsxFragmentFactory: "React.Fragment" },
+            // React is built on the @rbxts-js packages: if the game does not contain them, the interface never starts.
+            nodeModuleScopes: ["@rbxts-js"],
+            notes: [
+                `Your interface is a list of screens: ${ui}/App.tsx shows them, and UiController puts them on the player's screen. Try it: Play in Studio.`,
+                "Add a screen with `rowork make:screen`, and buttons, text, panels or images with `rowork make:ui`. To see one element without running the game, open the UI Labs plugin in Studio: it lists every *.story.tsx.",
+            ],
+        };
+    },
+    async postInstall({ logger, options }) {
+        if (options["plugin"] === false)
+            return;
+        if (!needsStudioSetup()) {
+            logger.info(`Install the UI Labs plugin in Studio to preview components: ${UI_LABS.store}`);
+            return;
+        }
+        const directories = findStudioDataDirectories();
+        if (directories.length === 0) {
+            logger.warn("Studio has not been launched yet, so the UI Labs plugin was not installed.");
+            logger.info("Run `rowork studio`, sign in, close Studio, then `rowork studio:setup`: it places the plugin.");
+            return;
+        }
+        try {
+            await installReleasePlugin(directories, UI_LABS, logger);
+            logger.info("Restart Studio to load the UI Labs plugin.");
+        }
+        catch (error) {
+            throw new RoworkError(error instanceof Error ? error.message : String(error), {
+                hint: `Install it from the Creator Store instead: ${UI_LABS.store}`,
+            });
+        }
+    },
+};
+//# sourceMappingURL=ui.js.map

package/dist/plugins/api.d.ts

@@ -0,0 +1,127 @@
+/**
+ * PUBLIC PLUGIN API CONTRACT.
+ *
+ * Everything exported here is exposed to third-party plugins through
+ * `rowork/plugin`.
+ *
+ * Non-negotiable rule (see CLAUDE.md): any breaking change to this file bumps
+ * ROWORK_PLUGIN_API_VERSION. Plugins declaring a different version are skipped
+ * with a warning, never loaded anyway.
+ */
+/** Plugin contract version. Bump on every breaking change. */
+export declare const ROWORK_PLUGIN_API_VERSION = 1;
+export interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    /** Indented progress line, for the steps of a running command. */
+    step(message: string): void;
+    blank(): void;
+}
+export interface CommandArgument {
+    /** Name used as the key in `CommandContext.args`. */
+    name: string;
+    description: string;
+    /** Defaults to true. */
+    required?: boolean;
+    /** Collects every remaining argument into an array. */
+    variadic?: boolean;
+    defaultValue?: string;
+}
+export interface CommandOption {
+    /** Commander syntax, e.g. `-f, --force` or `--path <dir>`. */
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean;
+}
+export interface CommandContext {
+    /** Positional arguments, keyed by `CommandArgument.name`. */
+    readonly args: Readonly<Record<string, string | string[] | undefined>>;
+    readonly options: Readonly<Record<string, unknown>>;
+    /** Effective working directory, honouring `--cwd`. */
+    readonly cwd: string;
+    /** Root of the Rowork project (the directory holding rowork.json), if any. */
+    readonly projectRoot: string | undefined;
+    readonly config: RoworkConfig | undefined;
+    readonly logger: Logger;
+    readonly roworkVersion: string;
+}
+export interface CommandDefinition {
+    /** Invocation name, e.g. `init` or `make:service`. */
+    name: string;
+    description: string;
+    aliases?: string[];
+    arguments?: CommandArgument[];
+    options?: CommandOption[];
+    /**
+     * True when running the command without its arguments opens interactive
+     * questions. Listed by `rowork info --json` so a script or an AI knows to
+     * pass every argument instead of waiting on a prompt that never comes.
+     */
+    guided?: boolean;
+    run(context: CommandContext): Promise<void> | void;
+}
+export interface PluginContext {
+    registerCommand(definition: CommandDefinition): void;
+    readonly logger: Logger;
+    readonly cwd: string;
+    readonly projectRoot: string | undefined;
+    readonly config: RoworkConfig | undefined;
+    readonly roworkVersion: string;
+}
+export interface RoworkPlugin {
+    /** Name shown in logs and command conflict warnings. */
+    name: string;
+    /** Must equal ROWORK_PLUGIN_API_VERSION. */
+    apiVersion: number;
+    /** Statically declared commands. */
+    commands?: CommandDefinition[];
+    /** Dynamic registration and initialisation. */
+    setup?(context: PluginContext): Promise<void> | void;
+}
+export interface RoworkConfig {
+    $schema?: string;
+    /** Game name. */
+    name: string;
+    /** Contract version this project expects. */
+    roworkApiVersion: number;
+    /** Only `roblox-ts` is supported in v1 (see CLAUDE.md, v1 scope). */
+    language: "roblox-ts";
+    paths: {
+        /** TypeScript sources. */
+        source: string;
+        /** roblox-ts compiler output. */
+        out: string;
+        /** Rojo project file. */
+        rojoProject: string;
+        /** Flamework services directory (target of make:service). */
+        services: string;
+        /** Flamework controllers directory (target of make:controller). */
+        controllers: string;
+        /** Shared code directory. */
+        shared: string;
+    };
+    /** Plugin module specifiers to load explicitly. */
+    plugins: string[];
+    /** Names of the modules installed with `rowork add`. */
+    modules?: string[];
+    /** Names of the integrations between modules already applied. */
+    integrations?: string[];
+    /** Settings of `rowork assets`, the upload of files to Roblox. */
+    assets?: {
+        /** Folder holding the files to upload, relative to the project. Defaults to `assets`. */
+        folder?: string;
+        /** Who owns the uploaded assets. */
+        creator?: {
+            type: "user" | "group";
+            id: string;
+        };
+    };
+}
+/** Type-inference helper for command authors. */
+export declare function defineCommand(definition: CommandDefinition): CommandDefinition;
+/** Type-inference helper for plugin authors. */
+export declare function definePlugin(plugin: RoworkPlugin): RoworkPlugin;
+//# sourceMappingURL=api.d.ts.map

package/dist/plugins/api.js

@@ -0,0 +1,21 @@
+/**
+ * PUBLIC PLUGIN API CONTRACT.
+ *
+ * Everything exported here is exposed to third-party plugins through
+ * `rowork/plugin`.
+ *
+ * Non-negotiable rule (see CLAUDE.md): any breaking change to this file bumps
+ * ROWORK_PLUGIN_API_VERSION. Plugins declaring a different version are skipped
+ * with a warning, never loaded anyway.
+ */
+/** Plugin contract version. Bump on every breaking change. */
+export const ROWORK_PLUGIN_API_VERSION = 1;
+/** Type-inference helper for command authors. */
+export function defineCommand(definition) {
+    return definition;
+}
+/** Type-inference helper for plugin authors. */
+export function definePlugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=api.js.map

package/dist/plugins/loader.d.ts

@@ -0,0 +1,20 @@
+import type { CommandRegistry } from "../cli/registry.js";
+import { type RoworkConfig } from "./api.js";
+export interface LoadPluginsOptions {
+    registry: CommandRegistry;
+    projectRoot: string | undefined;
+    config: RoworkConfig | undefined;
+    cwd: string;
+    roworkVersion: string;
+}
+/**
+ * Loads plugins from three sources, in order:
+ *   1. `plugins` declared in rowork.json (explicit, deterministic)
+ *   2. project dependencies whose name matches `rowork-plugin-*`
+ *   3. files in `.rowork/commands/`
+ *
+ * Invariant: a failing plugin must NEVER stop the CLI from running. Every load
+ * is isolated, and an error degrades to a warning.
+ */
+export declare function loadPlugins(options: LoadPluginsOptions): Promise<void>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/plugins/loader.js

@@ -0,0 +1,128 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "../ui/logger.js";
+import { ROWORK_PLUGIN_API_VERSION, } from "./api.js";
+/**
+ * Directory for one-off, project-specific commands that do not warrant an npm
+ * package.
+ *
+ * Prefer the .mjs extension: a roblox-ts package.json is not
+ * `"type": "module"`, so Node emits a MODULE_TYPELESS_PACKAGE_JSON warning for
+ * every .js file loaded from here.
+ */
+const LOCAL_COMMANDS_DIR = join(".rowork", "commands");
+const PLUGIN_NAME_PATTERN = /^(@[^/]+\/)?rowork-plugin-/;
+/**
+ * Loads plugins from three sources, in order:
+ *   1. `plugins` declared in rowork.json (explicit, deterministic)
+ *   2. project dependencies whose name matches `rowork-plugin-*`
+ *   3. files in `.rowork/commands/`
+ *
+ * Invariant: a failing plugin must NEVER stop the CLI from running. Every load
+ * is isolated, and an error degrades to a warning.
+ */
+export async function loadPlugins(options) {
+    const { projectRoot } = options;
+    if (projectRoot === undefined)
+        return;
+    const specifiers = new Set(options.config?.plugins ?? []);
+    for (const name of autoDetectedPlugins(projectRoot))
+        specifiers.add(name);
+    for (const specifier of specifiers) {
+        await loadPluginModule(specifier, projectRoot, options);
+    }
+    await loadLocalCommands(projectRoot, options.registry);
+}
+/** Picks up `rowork-plugin-*` packages from the project manifest. */
+function autoDetectedPlugins(projectRoot) {
+    const manifestPath = join(projectRoot, "package.json");
+    if (!existsSync(manifestPath))
+        return [];
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return [
+            ...Object.keys(manifest.dependencies ?? {}),
+            ...Object.keys(manifest.devDependencies ?? {}),
+        ].filter((name) => PLUGIN_NAME_PATTERN.test(name));
+    }
+    catch {
+        logger.debug(`Unreadable manifest in ${projectRoot}, skipping plugin auto-detection.`);
+        return [];
+    }
+}
+async function loadPluginModule(specifier, projectRoot, options) {
+    try {
+        // Resolve from the user project, not from the node_modules of Rowork
+        // itself: the CLI may well be installed globally.
+        const requireFromProject = createRequire(join(projectRoot, "package.json"));
+        const resolved = requireFromProject.resolve(specifier);
+        const module = (await import(pathToFileURL(resolved).href));
+        const plugin = (module.default ?? module.plugin);
+        if (plugin === undefined || typeof plugin !== "object") {
+            logger.warn(`Skipping plugin \`${specifier}\`: no valid default export.`);
+            return;
+        }
+        if (plugin.apiVersion !== ROWORK_PLUGIN_API_VERSION) {
+            logger.warn(`Skipping plugin \`${plugin.name || specifier}\`: targets API v${String(plugin.apiVersion)}, ` +
+                `this CLI provides v${ROWORK_PLUGIN_API_VERSION}.`);
+            return;
+        }
+        const origin = { kind: "plugin", pluginName: plugin.name || specifier };
+        for (const definition of plugin.commands ?? []) {
+            options.registry.register(definition, origin);
+        }
+        if (typeof plugin.setup === "function") {
+            const context = {
+                registerCommand: (definition) => options.registry.register(definition, origin),
+                logger,
+                cwd: options.cwd,
+                projectRoot: options.projectRoot,
+                config: options.config,
+                roworkVersion: options.roworkVersion,
+            };
+            await plugin.setup(context);
+        }
+        logger.debug(`Loaded plugin: ${plugin.name || specifier}`);
+    }
+    catch (error) {
+        logger.warn(`Could not load plugin \`${specifier}\`: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Loads ad hoc commands from `.rowork/commands/`. */
+async function loadLocalCommands(projectRoot, registry) {
+    const directory = join(projectRoot, LOCAL_COMMANDS_DIR);
+    if (!existsSync(directory))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(directory).filter((file) => /\.(?:js|mjs)$/.test(file));
+    }
+    catch (error) {
+        logger.warn(`Unreadable ${LOCAL_COMMANDS_DIR} directory: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    for (const file of entries) {
+        const fullPath = join(directory, file);
+        try {
+            const module = (await import(pathToFileURL(fullPath).href));
+            const exported = module.default;
+            const definitions = (Array.isArray(exported) ? exported : [exported]).filter((value) => typeof value === "object" &&
+                value !== null &&
+                typeof value.name === "string" &&
+                typeof value.run === "function");
+            if (definitions.length === 0) {
+                logger.warn(`${join(LOCAL_COMMANDS_DIR, file)} exports no valid command.`);
+                continue;
+            }
+            for (const definition of definitions) {
+                registry.register(definition, { kind: "local", file });
+            }
+        }
+        catch (error) {
+            logger.warn(`Could not load ${join(LOCAL_COMMANDS_DIR, file)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/process/log-mux.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Splits a child process stream into whole lines.
+ *
+ * A child writes in chunks that do not respect line boundaries: a single TypeScript
+ * diagnostic can arrive split across two `data` events. Prefixing raw chunks
+ * would tear messages in half and interleave them with other tasks, which is
+ * exactly what makes unified logs unreadable.
+ */
+export declare function createLineSplitter(onLine: (line: string) => void): {
+    push(chunk: Buffer | string): void;
+    flush(): void;
+};
+//# sourceMappingURL=log-mux.d.ts.map

package/dist/process/log-mux.js

@@ -0,0 +1,31 @@
+/**
+ * Splits a child process stream into whole lines.
+ *
+ * A child writes in chunks that do not respect line boundaries: a single TypeScript
+ * diagnostic can arrive split across two `data` events. Prefixing raw chunks
+ * would tear messages in half and interleave them with other tasks, which is
+ * exactly what makes unified logs unreadable.
+ */
+export function createLineSplitter(onLine) {
+    let buffer = "";
+    return {
+        push(chunk) {
+            buffer += chunk.toString();
+            let newline = buffer.indexOf("\n");
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).replace(/\r$/, "");
+                buffer = buffer.slice(newline + 1);
+                onLine(line);
+                newline = buffer.indexOf("\n");
+            }
+        },
+        flush() {
+            if (buffer.length === 0)
+                return;
+            const line = buffer.replace(/\r$/, "");
+            buffer = "";
+            onLine(line);
+        },
+    };
+}
+//# sourceMappingURL=log-mux.js.map

package/dist/process/supervisor.d.ts

@@ -0,0 +1,48 @@
+import type { Logger } from "../plugins/api.js";
+export interface TaskDefinition {
+    /** Short label shown as the log prefix. */
+    name: string;
+    command: string;
+    args: string[];
+    /** Colourises this task's prefix. */
+    paint: (text: string) => string;
+}
+export interface SupervisorOptions {
+    tasks: TaskDefinition[];
+    cwd: string;
+    logger: Logger;
+    /** Receives, verbatim, every line the supervisor prints for a task (prefix and colours included). */
+    onOutput?: (text: string) => void;
+}
+/**
+ * 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 declare class Supervisor {
+    private readonly options;
+    private readonly running;
+    private shuttingDown;
+    private exitCode;
+    constructor(options: SupervisorOptions);
+    run(): Promise<number>;
+    private start;
+    private waitFor;
+    /**
+     * 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.
+     */
+    private reportUnexpectedExit;
+    private shutdown;
+    private installSignalHandlers;
+}
+//# sourceMappingURL=supervisor.d.ts.map