rowork 0.1.0

package/dist/commands/info.js

@@ -0,0 +1,50 @@
+import pc from "picocolors";
+import { syncAgentDocs } from "../core/agent-docs.js";
+import { collectInfo } from "../core/info.js";
+import { defineCommand } from "../plugins/api.js";
+import { requireProject } from "./make.js";
+export const infoCommand = defineCommand({
+    name: "info",
+    description: "Show the project, what is installed and every available command (--json for scripts and AIs).",
+    options: [{ flags: "--json", description: "print machine-readable JSON on stdout" }],
+    run(context) {
+        const info = collectInfo({
+            config: context.config,
+            projectRoot: context.projectRoot,
+            roworkVersion: context.roworkVersion,
+        });
+        if (context.options["json"] === true) {
+            process.stdout.write(`${JSON.stringify(info, undefined, 2)}\n`);
+            return;
+        }
+        const { logger } = context;
+        logger.info(`${pc.bold("Rowork")} ${context.roworkVersion}`);
+        if (info.project === null) {
+            logger.info(pc.dim("Not inside a Rowork project. `rowork start` creates one."));
+            return;
+        }
+        const dev = info.project.dev;
+        logger.info(`${pc.bold(info.project.name)} ${pc.dim(info.project.root)}`);
+        logger.info(`  dev: ${dev === null ? "not running" : `running ${dev.mode === "foreground" ? "in a terminal" : "in the background"} (pid ${dev.pid}, port ${dev.port})`}`);
+        logger.blank();
+        logger.info(pc.bold("Modules"));
+        for (const module of info.modules) {
+            logger.info(`  ${module.installed ? pc.green("installed") : pc.dim("available")}  ${module.name}: ${module.description}`);
+        }
+        logger.blank();
+        logger.info(pc.dim("`rowork info --json` prints all of this, and every command, for scripts and AIs."));
+    },
+});
+export const agentsSyncCommand = defineCommand({
+    name: "agents:sync",
+    description: "Create or refresh AGENTS.md (instructions for AIs and newcomers) from the project's current state.",
+    run(context) {
+        const { root, config } = requireProject(context, "agents:sync");
+        const touched = syncAgentDocs(root, config, context.roworkVersion);
+        if (touched.length === 0)
+            context.logger.info("AGENTS.md is already up to date.");
+        else
+            context.logger.success(`Updated ${touched.join(", ")}.`);
+    },
+});
+//# sourceMappingURL=info.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+export declare const initCommand: import("../plugins/api.js").CommandDefinition;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -0,0 +1,55 @@
+import { resolve } from "node:path";
+import pc from "picocolors";
+import { RoworkError } from "../cli/errors.js";
+import { scaffoldProject } from "../core/scaffold.js";
+import { defineCommand } from "../plugins/api.js";
+import { isInteractive } from "../ui/prompt.js";
+import { printNextSteps } from "./next-steps.js";
+import { startCommand } from "./start.js";
+export const initCommand = defineCommand({
+    name: "init",
+    guided: true,
+    description: "Create a ready-to-run Roblox project (roblox-ts + Flamework + Rojo).",
+    arguments: [
+        { name: "name", description: "project name, also used as the directory name", required: false },
+    ],
+    options: [
+        { flags: "--path <dir>", description: "parent directory to create the project in" },
+        { flags: "--no-install", description: "skip installing npm dependencies" },
+        { flags: "--no-rokit", description: "skip installing the pinned Roblox toolchain" },
+        { flags: "--install-rokit", description: "download and install Rokit if it is missing" },
+        { flags: "--no-git", description: "skip git repository initialisation" },
+        { flags: "--no-examples", description: "skip the example service and controller" },
+        { flags: "--no-lint", description: "skip the linter (ESLint with the roblox-ts rules)" },
+        { flags: "--no-format", description: "skip the formatter (Prettier)" },
+        { flags: "-f, --force", description: "allow a target directory that is not empty" },
+    ],
+    async run(context) {
+        const name = context.args["name"];
+        if (typeof name !== "string") {
+            // No name given: this is the guided version of the command.
+            if (isInteractive())
+                return startCommand.run(context);
+            throw new RoworkError("Missing project name.", {
+                hint: `Usage: rowork init <name>. In a terminal, ${pc.bold("rowork init")} alone starts the guided setup.`,
+            });
+        }
+        const result = await scaffoldProject({
+            name,
+            parent: typeof context.options["path"] === "string"
+                ? resolve(context.cwd, context.options["path"])
+                : context.cwd,
+            install: context.options["install"] !== false,
+            lint: context.options["lint"] !== false,
+            format: context.options["format"] !== false,
+            rokit: context.options["rokit"] !== false,
+            installRokit: context.options["installRokit"] === true,
+            git: context.options["git"] !== false,
+            examples: context.options["examples"] !== false,
+            force: context.options["force"] === true,
+            roworkVersion: context.roworkVersion,
+        }, context.logger);
+        printNextSteps(context.logger, name, result);
+    },
+});
+//# sourceMappingURL=init.js.map

package/dist/commands/links.d.ts

@@ -0,0 +1,32 @@
+import { type EventInfo, type StatInfo } from "../core/project-index.js";
+import type { RoworkConfig } from "../plugins/api.js";
+/** Turns typed names into the matching stats, or explains what exists. */
+export declare function resolveStats(stats: StatInfo[], typed: string, what: string): StatInfo[];
+export declare function resolveEvent(events: EventInfo[], typed: string): EventInfo;
+export declare function askStatLink(root: string, config: RoworkConfig, message: string, single: boolean): Promise<string | undefined>;
+export declare function askEventLink(root: string, config: RoworkConfig, message: string): Promise<string | undefined>;
+/**
+ * A server-side handler for an event the client sends, wired to a saved value.
+ *
+ * The amount is fixed here and never read from the event: a client that could
+ * choose the amount could give itself anything. The comments say so, because the
+ * next person to edit this file is exactly the one tempted to "just use the
+ * amount the client sent".
+ */
+export declare function createEventHandler(options: {
+    root: string;
+    config: RoworkConfig;
+    event: {
+        name: string;
+    };
+    stat: StatInfo;
+}): {
+    path: string;
+    className: string;
+};
+/** Constructor injection for a service that uses saved values. */
+export declare function serviceMembers(root: string, config: RoworkConfig, stats: StatInfo[]): {
+    imports: string;
+    members: string;
+};
+//# sourceMappingURL=links.d.ts.map

package/dist/commands/links.js

@@ -0,0 +1,152 @@
+import { RoworkError } from "../cli/errors.js";
+import { generateFile, importPath } from "../core/generate.js";
+import { listEvents, listStats, pascal, statServiceClass } from "../core/project-index.js";
+import { toFieldName } from "../modules/player-data.js";
+import { answered, prompts } from "../ui/prompt.js";
+/**
+ * "Link it to ...?" for the guided `make:` commands.
+ *
+ * The person types the name of something that already exists, or leaves it empty
+ * for no link. Free text rather than a closed list, on purpose: it is faster for
+ * someone who knows the name, and what is available is printed in the question.
+ */
+async function askName(message, available) {
+    const raw = answered(await prompts.text({
+        message: `${message} Available: ${available.join(", ")}. Leave empty for none.`,
+        placeholder: available[0] ?? "",
+        defaultValue: "",
+        validate: (value) => {
+            const typed = (value ?? "").trim();
+            if (typed === "")
+                return undefined;
+            return typed.split(",").every((part) => available.includes(toFieldName(part))) ? undefined : `Pick from: ${available.join(", ")}`;
+        },
+    }));
+    return raw.trim() === "" ? undefined : raw;
+}
+/** Turns typed names into the matching stats, or explains what exists. */
+export function resolveStats(stats, typed, what) {
+    const wanted = typed.split(",").map((part) => toFieldName(part)).filter((part) => part !== "");
+    const found = wanted.map((name) => stats.find((stat) => stat.name === name));
+    const missing = wanted.filter((_, index) => found[index] === undefined);
+    if (missing.length > 0) {
+        throw new RoworkError(`No saved value called ${missing.map((name) => `\`${name}\``).join(", ")}.`, {
+            hint: stats.length === 0 ? `There are no saved values yet: create one with \`rowork make:stat\`, then ${what}.` : `Saved values: ${stats.map((stat) => stat.name).join(", ")}.`,
+        });
+    }
+    return found;
+}
+export function resolveEvent(events, typed) {
+    const name = toFieldName(typed);
+    const event = events.find((candidate) => candidate.name === name && candidate.direction === "server");
+    if (event === undefined) {
+        const available = events.filter((candidate) => candidate.direction === "server").map((candidate) => candidate.name);
+        throw new RoworkError(`No event from the client called \`${name}\`.`, {
+            hint: available.length === 0 ? "There is none yet: create one with `rowork make:event`." : `Events the client sends: ${available.join(", ")}.`,
+        });
+    }
+    return event;
+}
+export async function askStatLink(root, config, message, single) {
+    const stats = listStats(root, config);
+    if (stats.length === 0)
+        return undefined;
+    return askName(message, stats.map((stat) => stat.name)).then((typed) => (single && typed !== undefined ? typed.split(",")[0] : typed));
+}
+export async function askEventLink(root, config, message) {
+    const events = listEvents(root, config).filter((event) => event.direction === "server");
+    if (events.length === 0)
+        return undefined;
+    return askName(message, events.map((event) => event.name));
+}
+/**
+ * How generated code reaches saved values: through a stat's own service when
+ * `make:stat` created one, otherwise through PlayerDataService.
+ */
+function accessFor(root, config, stats) {
+    const imports = [];
+    const ctor = [];
+    let usesData = false;
+    for (const stat of stats) {
+        const service = statServiceClass(root, config, stat.name);
+        if (service !== undefined) {
+            imports.push(`import { ${service} } from "./${service}";`);
+            ctor.push(`private readonly ${stat.name}: ${service}`);
+        }
+        else
+            usesData = true;
+    }
+    if (usesData) {
+        imports.push('import { PlayerDataService } from "./PlayerDataService";');
+        ctor.push("private readonly playerData: PlayerDataService");
+    }
+    return {
+        imports,
+        ctor,
+        add: (stat) => statServiceClass(root, config, stat.name) !== undefined
+            ? `this.${stat.name}.add(player, 1);`
+            : `this.playerData.update(player, (data) => {\n\t\t\t\tdata.${stat.name} += 1;\n\t\t\t\treturn data;\n\t\t\t});`,
+    };
+}
+/**
+ * A server-side handler for an event the client sends, wired to a saved value.
+ *
+ * The amount is fixed here and never read from the event: a client that could
+ * choose the amount could give itself anything. The comments say so, because the
+ * next person to edit this file is exactly the one tempted to "just use the
+ * amount the client sent".
+ */
+export function createEventHandler(options) {
+    const { root, config, event, stat } = options;
+    const className = `${pascal(event.name)}Handler`;
+    const access = accessFor(root, config, [stat]);
+    const body = stat.type === "number"
+        ? [
+            `\t\t\t// The amount is decided HERE, on the server. Do not use a number the client sent:`,
+            `\t\t\t// a player could send any amount and give themselves anything.`,
+            `\t\t\t${access.add(stat)}`,
+        ].join("\n")
+        : `\t\t\t// TODO: change \`${stat.name}\` here, deciding the new value on the server. Never copy what the client sent.`;
+    const services = config.paths.services;
+    const written = generateFile({
+        projectRoot: root,
+        directory: services,
+        fileName: `${className}.ts`,
+        template: "event-handler",
+        variables: {
+            className,
+            event: event.name,
+            networkImport: importPath(root, services, `${config.paths.source}/server/network`),
+            imports: stat.type === "number" ? access.imports.join("\n") : "",
+            ctor: stat.type === "number" ? access.ctor.join(", ") : "",
+            body,
+        },
+        force: false,
+    });
+    return { path: written ?? `${services}/${className}.ts`, className };
+}
+/** A constructor, laid out the way Prettier does: one parameter property per line as soon as there are several. */
+function constructorSource(params) {
+    if (params.length <= 1)
+        return `\tconstructor(${params.join("")}) {}`;
+    return `\tconstructor(\n${params.map((param) => `\t\t${param},`).join("\n")}\n\t) {}`;
+}
+/** Constructor injection for a service that uses saved values. */
+export function serviceMembers(root, config, stats) {
+    if (stats.length === 0)
+        return { imports: "", members: "" };
+    const access = accessFor(root, config, stats);
+    // How to reach each value, written where the next reader will look.
+    const howTo = stats.map((stat) => {
+        const viaService = statServiceClass(root, config, stat.name) !== undefined;
+        if (!viaService)
+            return `\t//   ${stat.name}: this.playerData.get(player)?.${stat.name}, or this.playerData.update(player, (data) => { ...; return data; })`;
+        return `\t//   ${stat.name}: this.${stat.name}.get(player), this.${stat.name}.set(player, value)${stat.type === "number" ? `, this.${stat.name}.add(player, amount)` : ""}`;
+    });
+    return {
+        // A blank line after the imports, as in a file written by hand.
+        imports: `${access.imports.join("\n")}\n`,
+        members: `\t// Saved values this service works with:\n${howTo.join("\n")}\n${constructorSource(access.ctor)}\n\n`,
+    };
+}
+//# sourceMappingURL=links.js.map

package/dist/commands/make-event.d.ts

@@ -0,0 +1,2 @@
+export declare const makeEventCommand: import("../plugins/api.js").CommandDefinition;
+//# sourceMappingURL=make-event.d.ts.map

package/dist/commands/make-event.js

@@ -0,0 +1,160 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { RoworkError } from "../cli/errors.js";
+import { resolveProjectPath } from "../core/config.js";
+import { addEventToNetworking, addRateLimit } from "../core/schema-edit.js";
+import { askEventParameters, checkParameters } from "../modules/networking.js";
+import { toFieldName } from "../modules/player-data.js";
+import { installModule } from "../core/modules.js";
+import { networkingModule } from "../modules/networking.js";
+import { defineCommand } from "../plugins/api.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { listStats, pascal } from "../core/project-index.js";
+import { answered, prompts, requireInteractive } from "../ui/prompt.js";
+import { askStatLink, createEventHandler, resolveStats } from "./links.js";
+import { requireProject } from "./make.js";
+const IDENTIFIER = /^[a-z][A-Za-z0-9]*$/;
+export const makeEventCommand = defineCommand({
+    name: "make:event",
+    description: "Add an event (a typed message between client and server) to the networking file where it belongs.",
+    guided: true,
+    arguments: [{ name: "name", description: "the message, e.g. buyItem (omit it for the guided version)", required: false }],
+    options: [
+        { flags: "--to <side>", description: "who receives it: server (default) or client" },
+        { flags: "--args <list>", description: 'what it carries, e.g. "itemId: string, amount: number"' },
+        { flags: "--link <value>", description: "a saved value the server changes when it receives this (a client event only)" },
+    ],
+    async run(context) {
+        const { root, config } = requireProject(context, "make:event");
+        const missingModule = !(config.modules ?? []).includes("networking");
+        const given = context.args["name"];
+        if (missingModule && typeof given === "string") {
+            // Scripted: no question to ask. Say the one command that does both.
+            throw new RoworkError("There is no networking file to add an event to.", {
+                hint: `Run \`rowork add:networking --event "${given}:server()"\`: it installs typed networking and starts with that event.`,
+            });
+        }
+        let rawName;
+        let side = "server";
+        let parameters = "";
+        let linkTyped;
+        if (typeof given === "string") {
+            rawName = given;
+            const to = context.options["to"];
+            if (to !== undefined) {
+                if (to !== "server" && to !== "client") {
+                    throw new RoworkError(`Unknown side \`${String(to)}\`.`, { hint: "--to server (the client sends it) or --to client (the server sends it)." });
+                }
+                side = to;
+            }
+            parameters = checkParameters(typeof context.options["args"] === "string" ? context.options["args"] : "");
+            if (typeof context.options["link"] === "string")
+                linkTyped = context.options["link"];
+        }
+        else {
+            requireInteractive("make:event", 'rowork make:event <name> --to server --args "itemId: string"');
+            rawName = answered(await prompts.text({
+                message: "Name of the message (anything you like, e.g. buy item)",
+                placeholder: "buy item",
+                validate: (value) => (IDENTIFIER.test(toFieldName(value ?? "")) ? undefined : "Use letters and digits, starting with a letter."),
+            }));
+            side = answered(await prompts.select({
+                message: `Who sends ${toFieldName(rawName)}?`,
+                options: [
+                    { value: "server", label: "The player's client, to the server", hint: "a button click, a purchase" },
+                    { value: "client", label: "The server, to the player(s)", hint: "a notification, a result" },
+                ],
+            }));
+            parameters = await askEventParameters(toFieldName(rawName));
+            // "Link it to...?" only makes sense for what the client sends: that is what the server reacts to.
+            if (side === "server") {
+                linkTyped = await askStatLink(root, config, "Should the server change a saved value when it receives this? Type its name.", true);
+            }
+        }
+        const name = toFieldName(rawName);
+        if (!IDENTIFIER.test(name)) {
+            throw new RoworkError(`\`${rawName}\` cannot be used as a name.`, { hint: "Use letters and digits, starting with a letter." });
+        }
+        // A link is checked before anything is written.
+        let linkStat;
+        if (linkTyped !== undefined) {
+            if (side !== "server") {
+                throw new RoworkError("A link only applies to an event the client sends.", {
+                    hint: "The server reacts to events from the client. Use --to server, or drop --link.",
+                });
+            }
+            linkStat = resolveStats(listStats(root, config), linkTyped, "then link it")[0];
+            const handlerFile = join(config.paths.services, `${pascal(name)}Handler.ts`);
+            if (existsSync(join(root, handlerFile))) {
+                throw new RoworkError(`${handlerFile} already exists.`, { hint: "Pick another name for the event." });
+            }
+        }
+        const linkNow = () => {
+            if (linkStat === undefined)
+                return;
+            const handler = createEventHandler({ root, config, event: { name }, stat: linkStat });
+            context.logger.step(`${handler.path}: runs on the server when \`${name}\` arrives, linked to \`${linkStat.name}\``);
+            context.logger.info("It decides the amount on the server: do not use a number the client sent.");
+        };
+        // Guided and typed networking is not installed: offer to install it, starting with this event.
+        if (missingModule) {
+            const proceed = answered(await prompts.confirm({
+                message: `Events need the Typed networking module, which is not installed. Add it now, starting with \`${name}\`?`,
+                initialValue: true,
+            }));
+            if (!proceed) {
+                prompts.cancel("Nothing changed.");
+                return;
+            }
+            await installModule({ ...context, options: { event: [`${name}:${side}(${parameters})`] } }, networkingModule, root, false);
+            linkNow();
+            return;
+        }
+        const file = `${config.paths.shared}/networking.ts`;
+        const path = resolveProjectPath(root, file);
+        let source;
+        try {
+            source = readFileSync(path, "utf8");
+        }
+        catch {
+            throw new RoworkError(`Cannot read ${file}.`, { hint: "It is created by `rowork add:networking`." });
+        }
+        const newNetworking = addEventToNetworking(source, file, side, { name, parameters });
+        // An event the client sends is rate limited like the others: its line is added to the
+        // server's list. Computed before anything is written, like every edit here.
+        const serverFile = `${config.paths.source}/server/network.ts`;
+        let newServer;
+        let unprotected = false;
+        if (side === "server") {
+            try {
+                newServer = addRateLimit(readFileSync(resolveProjectPath(root, serverFile), "utf8"), name);
+            }
+            catch {
+                newServer = undefined;
+            }
+            unprotected = newServer === undefined;
+        }
+        writeFileSync(path, newNetworking, "utf8");
+        context.logger.step(`${file}: added ${name}(${parameters})`);
+        if (newServer !== undefined) {
+            writeFileSync(resolveProjectPath(root, serverFile), newServer, "utf8");
+            context.logger.step(`${serverFile}: ${name} is rate limited per player`);
+        }
+        if (unprotected) {
+            context.logger.warn(`${serverFile} has no \`middleware\` list: \`${name}\` is NOT rate limited. Add \`${name}: [limit()]\` yourself, or a cheater can flood it.`);
+        }
+        linkNow();
+        context.logger.success(`Event \`${name}\` added (${side === "server" ? "client to server" : "server to client"}).`);
+        context.logger.blank();
+        const args = parameters === "" ? "" : "...";
+        if (side === "server") {
+            context.logger.info(`Server listens:  Events.${name}.connect((player${args === "" ? "" : ", ..."}) => { ... });`);
+            context.logger.info(`Client sends:    Events.${name}.fire(${args});`);
+        }
+        else {
+            context.logger.info(`Client listens:  Events.${name}.connect((${args}) => { ... });`);
+            context.logger.info(`Server sends:    Events.${name}.fire(player${args === "" ? "" : ", ..."});`);
+        }
+    },
+});
+//# sourceMappingURL=make-event.js.map

package/dist/commands/make-menu.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDefinition } from "../plugins/api.js";
+export declare const makeCommand: CommandDefinition;
+//# sourceMappingURL=make-menu.d.ts.map

package/dist/commands/make-menu.js

@@ -0,0 +1,36 @@
+import { defineCommand } from "../plugins/api.js";
+import { answered, prompts, requireInteractive } from "../ui/prompt.js";
+import { makeEventCommand } from "./make-event.js";
+import { makeStatCommand } from "./make-stat.js";
+import { makeScreenCommand, makeUiCommand } from "./make-ui.js";
+import { makeComponentCommand, makeControllerCommand, makeServiceCommand, requireProject } from "./make.js";
+/** Everything `rowork make` can create, in the order most people need it. */
+const CHOICES = [
+    { command: makeStatCommand, label: "Stat (saved value)", hint: "kills, coins, level: added to the player data everywhere it must be" },
+    { command: makeEventCommand, label: "Event", hint: "a typed message between client and server" },
+    { command: makeServiceCommand, label: "Service", hint: "server-side logic: data, rules, spawning" },
+    { command: makeControllerCommand, label: "Controller", hint: "client-side logic: input, camera, effects" },
+    { command: makeScreenCommand, label: "Screen", hint: "a full-screen layer of the interface (a ScreenGui), shown by App" },
+    { command: makeUiCommand, label: "UI element", hint: "a button, text, panel or image, with its Studio preview" },
+    { command: makeComponentCommand, label: "Component", hint: "behaviour for objects you tag in Studio: doors, pickups" },
+];
+export const makeCommand = defineCommand({
+    name: "make",
+    guided: true,
+    description: "Create a file in the right place and connect it where it is needed (choose from a list).",
+    async run(context) {
+        requireProject(context, "make");
+        requireInteractive("make", "rowork make:service <name>, make:controller <name>, make:component <name>, make:stat <name>, make:event <name>, make:screen <name> or make:ui <name>");
+        prompts.intro("rowork make");
+        const chosen = answered(await prompts.select({
+            message: "Which file do you want to create? (Rowork puts it in the right place and connects it)",
+            options: CHOICES.map((choice) => ({ value: choice.command.name, label: choice.label, hint: choice.hint })),
+        }));
+        const choice = CHOICES.find((candidate) => candidate.command.name === chosen);
+        if (choice === undefined)
+            return;
+        // No argument and no option: the chosen command runs its guided version.
+        await choice.command.run({ ...context, args: {}, options: {} });
+    },
+});
+//# sourceMappingURL=make-menu.js.map

package/dist/commands/make-stat.d.ts

@@ -0,0 +1,2 @@
+export declare const makeStatCommand: import("../plugins/api.js").CommandDefinition;
+//# sourceMappingURL=make-stat.d.ts.map