rowork 0.1.0

package/dist/core/studio.d.ts

@@ -0,0 +1,83 @@
+import type { Logger } from "../plugins/api.js";
+/**
+ * Roblox publishes Studio for Windows and macOS only. On Linux the working
+ * route is Vinegar, a Flatpak that runs the real Studio under Wine/Proton.
+ */
+export declare const VINEGAR_ID = "org.vinegarhq.Vinegar";
+export declare function needsStudioSetup(): boolean;
+export declare function hasFlatpak(): boolean;
+export declare function isVinegarInstalled(): boolean;
+/** Where Vinegar keeps Studio and its Wine prefix. */
+export declare function vinegarDataDirectory(): string;
+/**
+ * Installs Vinegar for the current user only, so no root access is needed and
+ * nothing outside the user's home is modified.
+ */
+export declare function installVinegar(logger: Logger): Promise<void>;
+/**
+ * Finds the `Roblox` local-data directories of every Studio Wine prefix.
+ *
+ * They exist only after Studio has been launched once, because that is when
+ * Vinegar creates the prefix. Explicit descent rather than a recursive search:
+ * a Wine prefix holds a whole fake Windows tree.
+ */
+export declare function findStudioDataDirectories(dataDirectory?: string): string[];
+/** Reads the Rojo version pinned in the project's rokit.toml, if any. */
+export declare function pinnedRojoVersion(projectRoot: string | undefined): string | undefined;
+/**
+ * Puts the Rojo plugin where Studio loads plugins from.
+ *
+ * `rojo plugin install` answers "platform not supported" on Linux, so Rowork
+ * places the release's `Rojo.rbxm` itself. The plugin has to match the Rojo
+ * server it talks to, hence the version pinned in rokit.toml. Older releases
+ * publish no checksum: the file still comes from the official repository over
+ * HTTPS, and the user is told it could not be verified.
+ */
+export declare function installRojoPlugin(dataDirectories: readonly string[], projectRoot: string | undefined, logger: Logger): Promise<void>;
+/** Where a Studio plugin can be found, for the ones Rowork places itself. */
+export declare const UI_LABS: {
+    readonly repository: "PepeElToro41/ui-labs";
+    readonly asset: "Plugin.rbxm";
+    readonly file: "UILabs.rbxm";
+    readonly store: "https://create.roblox.com/store/asset/14293316215/";
+};
+/**
+ * Places a plugin published as a GitHub release asset into Studio's plugins folder.
+ *
+ * Same reasoning as the Rojo plugin, and the same limit: on Linux the Wine prefix
+ * only exists after Studio has been launched once. Unlike Rojo's older releases,
+ * UI Labs publishes a SHA-256 for its plugin, so it is verified here.
+ */
+export declare function installReleasePlugin(dataDirectories: readonly string[], plugin: {
+    repository: string;
+    asset: string;
+    file: string;
+}, logger: Logger): Promise<void>;
+/**
+ * Finds the Creator Store copy of the Rojo plugin, if Studio installed one.
+ *
+ * Studio keeps store plugins under `Roblox/<user id>/InstalledPlugins/<asset id>`.
+ * Rowork places its own copy, matching the Rojo it runs, in `Roblox/Plugins`: with
+ * both, Studio shows two Rojo buttons, and the store one is usually older.
+ */
+export declare function findStoreRojoPlugin(dataDirectory?: string): string | undefined;
+/**
+ * Says why two Rojo plugins is a problem, and what to do about it.
+ *
+ * Rojo 7.7 replaced JSON by MessagePack for its whole API. A plugin older than the
+ * server cannot read it and Studio reports "Can't parse JSON", which says nothing
+ * about the real cause. The Creator Store copy lags behind Rojo's releases.
+ */
+export declare function warnAboutStorePlugin(logger: Logger): void;
+export interface StudioSetupResult {
+    pluginInstalled: boolean;
+}
+/** Everything `rowork studio:setup` does, reusable from `rowork start`. */
+export declare function setupStudio(options: {
+    logger: Logger;
+    projectRoot: string | undefined;
+    plugin: boolean;
+}): Promise<StudioSetupResult>;
+/** Starts Studio through Vinegar and returns immediately. */
+export declare function launchStudio(): void;
+//# sourceMappingURL=studio.d.ts.map

package/dist/core/studio.js

@@ -0,0 +1,225 @@
+import { spawn as spawnDetached } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import spawn from "cross-spawn";
+import { RoworkError } from "../cli/errors.js";
+import { loadConfig } from "./config.js";
+import { run as runBinary } from "./exec.js";
+import { downloadAsset, getRelease } from "./github-release.js";
+import { findExecutable } from "./toolchain.js";
+/**
+ * Roblox publishes Studio for Windows and macOS only. On Linux the working
+ * route is Vinegar, a Flatpak that runs the real Studio under Wine/Proton.
+ */
+export const VINEGAR_ID = "org.vinegarhq.Vinegar";
+const FLATHUB_REPO = "https://dl.flathub.org/repo/flathub.flatpakrepo";
+export function needsStudioSetup() {
+    return process.platform === "linux";
+}
+export function hasFlatpak() {
+    return findExecutable("flatpak", process.cwd()) !== undefined;
+}
+export function isVinegarInstalled() {
+    if (!hasFlatpak())
+        return false;
+    return spawn.sync("flatpak", ["info", VINEGAR_ID], { stdio: "ignore" }).status === 0;
+}
+/** Where Vinegar keeps Studio and its Wine prefix. */
+export function vinegarDataDirectory() {
+    return join(homedir(), ".var", "app", VINEGAR_ID, "data", "vinegar");
+}
+/**
+ * Installs Vinegar for the current user only, so no root access is needed and
+ * nothing outside the user's home is modified.
+ */
+export async function installVinegar(logger) {
+    if (!hasFlatpak()) {
+        throw new RoworkError("Flatpak is not installed.", {
+            hint: "Install it with your package manager (e.g. `sudo pacman -S flatpak`, `sudo apt install flatpak`), then run this again. https://flatpak.org/setup/",
+        });
+    }
+    logger.step("adding the Flathub remote for this user (if missing)");
+    await runBinary("flatpak", ["remote-add", "--user", "--if-not-exists", "flathub", FLATHUB_REPO], {
+        cwd: process.cwd(),
+        stdio: "ignore",
+    });
+    logger.step(`installing ${VINEGAR_ID} (Roblox Studio for Linux), this downloads a few hundred MB`);
+    await runBinary("flatpak", ["install", "--user", "-y", "flathub", VINEGAR_ID], {
+        cwd: process.cwd(),
+    });
+}
+/**
+ * Finds the `Roblox` local-data directories of every Studio Wine prefix.
+ *
+ * They exist only after Studio has been launched once, because that is when
+ * Vinegar creates the prefix. Explicit descent rather than a recursive search:
+ * a Wine prefix holds a whole fake Windows tree.
+ */
+export function findStudioDataDirectories(dataDirectory = vinegarDataDirectory()) {
+    const found = [];
+    const subdirectories = (path) => {
+        try {
+            return readdirSync(path, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => join(path, entry.name));
+        }
+        catch {
+            return [];
+        }
+    };
+    for (const prefix of subdirectories(join(dataDirectory, "prefixes"))) {
+        for (const user of subdirectories(join(prefix, "drive_c", "users"))) {
+            const roblox = join(user, "AppData", "Local", "Roblox");
+            if (existsSync(roblox))
+                found.push(roblox);
+        }
+    }
+    return found;
+}
+/** Reads the Rojo version pinned in the project's rokit.toml, if any. */
+export function pinnedRojoVersion(projectRoot) {
+    if (projectRoot === undefined)
+        return undefined;
+    try {
+        const toml = readFileSync(join(projectRoot, "rokit.toml"), "utf8");
+        return /^\s*rojo\s*=\s*"rojo-rbx\/rojo@([^"]+)"/m.exec(toml)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Puts the Rojo plugin where Studio loads plugins from.
+ *
+ * `rojo plugin install` answers "platform not supported" on Linux, so Rowork
+ * places the release's `Rojo.rbxm` itself. The plugin has to match the Rojo
+ * server it talks to, hence the version pinned in rokit.toml. Older releases
+ * publish no checksum: the file still comes from the official repository over
+ * HTTPS, and the user is told it could not be verified.
+ */
+export async function installRojoPlugin(dataDirectories, projectRoot, logger) {
+    const version = pinnedRojoVersion(projectRoot);
+    logger.step(`downloading the Rojo plugin (${version === undefined ? "latest" : `v${version}`})`);
+    const release = await getRelease("rojo-rbx/rojo", version === undefined ? undefined : `v${version}`);
+    const asset = release.assets?.find((candidate) => candidate.name === "Rojo.rbxm");
+    if (asset === undefined)
+        throw new Error(`no Rojo.rbxm in Rojo ${release.tag_name}`);
+    const { data, verified } = await downloadAsset(asset, { allowUnverified: true });
+    if (!verified) {
+        logger.warn(`GitHub publishes no checksum for Rojo ${release.tag_name}: the plugin could not be verified.`);
+    }
+    for (const dataDirectory of dataDirectories) {
+        const plugins = join(dataDirectory, "Plugins");
+        mkdirSync(plugins, { recursive: true });
+        writeFileSync(join(plugins, "Rojo.rbxm"), data);
+        logger.step(`installed ${join(plugins, "Rojo.rbxm")}`);
+    }
+}
+/** Where a Studio plugin can be found, for the ones Rowork places itself. */
+export const UI_LABS = {
+    repository: "PepeElToro41/ui-labs",
+    asset: "Plugin.rbxm",
+    file: "UILabs.rbxm",
+    store: "https://create.roblox.com/store/asset/14293316215/",
+};
+/**
+ * Places a plugin published as a GitHub release asset into Studio's plugins folder.
+ *
+ * Same reasoning as the Rojo plugin, and the same limit: on Linux the Wine prefix
+ * only exists after Studio has been launched once. Unlike Rojo's older releases,
+ * UI Labs publishes a SHA-256 for its plugin, so it is verified here.
+ */
+export async function installReleasePlugin(dataDirectories, plugin, logger) {
+    logger.step(`downloading the ${plugin.file.replace(/\.rbxm$/, "")} plugin`);
+    const release = await getRelease(plugin.repository);
+    const asset = release.assets?.find((candidate) => candidate.name === plugin.asset);
+    if (asset === undefined)
+        throw new Error(`no ${plugin.asset} in ${plugin.repository} ${release.tag_name}`);
+    const { data, verified } = await downloadAsset(asset, { allowUnverified: true });
+    if (!verified)
+        logger.warn(`GitHub publishes no checksum for ${plugin.repository} ${release.tag_name}: the plugin could not be verified.`);
+    for (const dataDirectory of dataDirectories) {
+        const plugins = join(dataDirectory, "Plugins");
+        mkdirSync(plugins, { recursive: true });
+        writeFileSync(join(plugins, plugin.file), data);
+        logger.step(`installed ${join(plugins, plugin.file)}`);
+    }
+}
+/** The Rojo plugin in the Creator Store, as Studio names its folder for it. */
+const STORE_ROJO_PLUGIN_ID = "13916111004";
+/**
+ * Finds the Creator Store copy of the Rojo plugin, if Studio installed one.
+ *
+ * Studio keeps store plugins under `Roblox/<user id>/InstalledPlugins/<asset id>`.
+ * Rowork places its own copy, matching the Rojo it runs, in `Roblox/Plugins`: with
+ * both, Studio shows two Rojo buttons, and the store one is usually older.
+ */
+export function findStoreRojoPlugin(dataDirectory = vinegarDataDirectory()) {
+    for (const roblox of findStudioDataDirectories(dataDirectory)) {
+        let users;
+        try {
+            users = readdirSync(roblox, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+        }
+        catch {
+            continue;
+        }
+        for (const user of users) {
+            const candidate = join(roblox, user, "InstalledPlugins", STORE_ROJO_PLUGIN_ID);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Says why two Rojo plugins is a problem, and what to do about it.
+ *
+ * Rojo 7.7 replaced JSON by MessagePack for its whole API. A plugin older than the
+ * server cannot read it and Studio reports "Can't parse JSON", which says nothing
+ * about the real cause. The Creator Store copy lags behind Rojo's releases.
+ */
+export function warnAboutStorePlugin(logger) {
+    logger.warn("Studio has TWO Rojo plugins: the Creator Store one, and the one Rowork installed.");
+    logger.info("  The Store copy is usually older than the Rojo Rowork runs. Since Rojo 7.7 it cannot talk to the server");
+    logger.info("  and Studio only says \"Can't parse JSON\". Disable it: Plugins > Manage Plugins > Rojo (Creator Store).");
+}
+/** Everything `rowork studio:setup` does, reusable from `rowork start`. */
+export async function setupStudio(options) {
+    const { logger } = options;
+    if (isVinegarInstalled()) {
+        logger.step("Vinegar is already installed");
+    }
+    else {
+        await installVinegar(logger);
+    }
+    if (!options.plugin)
+        return { pluginInstalled: false };
+    const directories = findStudioDataDirectories();
+    if (directories.length === 0) {
+        logger.warn("Studio has not been launched yet, so there is nowhere to put the Rojo plugin.");
+        logger.info("Run `rowork studio`, sign in to Roblox, close Studio, then `rowork studio:setup` again.");
+        return { pluginInstalled: false };
+    }
+    await installRojoPlugin(directories, options.projectRoot, logger);
+    if (findStoreRojoPlugin() !== undefined)
+        warnAboutStorePlugin(logger);
+    // The UI module previews components with the UI Labs plugin: place it too.
+    if (options.projectRoot !== undefined) {
+        try {
+            if (loadConfig(options.projectRoot).modules?.includes("ui")) {
+                await installReleasePlugin(directories, UI_LABS, logger);
+            }
+        }
+        catch (error) {
+            logger.warn(`Could not place the UI Labs plugin: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { pluginInstalled: true };
+}
+/** Starts Studio through Vinegar and returns immediately. */
+export function launchStudio() {
+    const child = spawnDetached("flatpak", ["run", VINEGAR_ID], { detached: true, stdio: "ignore" });
+    child.unref();
+}
+//# sourceMappingURL=studio.js.map

package/dist/core/toolchain.d.ts

@@ -0,0 +1,31 @@
+/** Where a tool comes from, which decides the advice given when it is missing. */
+export type ToolSource = "npm" | "rokit";
+export interface ToolRequirement {
+    /** Executable name, without any Windows extension. */
+    command: string;
+    source: ToolSource;
+}
+/** PATH as the orchestrated tools will see it: project binaries first. */
+export declare function searchPath(projectRoot: string): string[];
+/**
+ * Looks a tool up on PATH without running it.
+ *
+ * Running `--version` would be more thorough, but it starts a real process per
+ * check, and a lookup is enough to turn `spawn rojo ENOENT` into an actionable
+ * message. On Windows the shims are `.cmd` files, hence PATHEXT.
+ */
+export declare function findExecutable(command: string, projectRoot: string): string | undefined;
+export declare function findMissing(requirements: readonly ToolRequirement[], projectRoot: string): ToolRequirement[];
+/** One line of advice per missing tool, grouped by where the fix lives. */
+export declare function installAdvice(missing: readonly ToolRequirement[]): string;
+/** PATH string with the project's own binaries first, the way npm scripts see it. */
+export declare function pathWithLocalBinaries(projectRoot: string): string;
+/** True when nothing is listening on the local port, checked by trying to take it. */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * True when `command` is on the plain PATH, the way a shell or an npm script
+ * sees it: no project binaries first, and none of Rowork's own fallback
+ * directories. Once a project has left Rowork, that is the only lookup left.
+ */
+export declare function isOnPlainPath(command: string): boolean;
+//# sourceMappingURL=toolchain.d.ts.map

package/dist/core/toolchain.js

@@ -0,0 +1,98 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { createServer } from "node:net";
+import { delimiter, join } from "node:path";
+import { rokitBinDirectory } from "./rokit-installer.js";
+/** PATH as the orchestrated tools will see it: project binaries first. */
+export function searchPath(projectRoot) {
+    const current = process.env["PATH"] ?? "";
+    // Rokit's own directory comes last: right after a self-install the current
+    // shell has not picked up the PATH change yet, and it should not need to.
+    return [
+        join(projectRoot, "node_modules", ".bin"),
+        ...current.split(delimiter),
+        rokitBinDirectory(),
+    ].filter((entry) => entry.length > 0);
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isExecutable(path) {
+    if (!isFile(path))
+        return false;
+    if (process.platform === "win32")
+        return true;
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Looks a tool up on PATH without running it.
+ *
+ * Running `--version` would be more thorough, but it starts a real process per
+ * check, and a lookup is enough to turn `spawn rojo ENOENT` into an actionable
+ * message. On Windows the shims are `.cmd` files, hence PATHEXT.
+ */
+export function findExecutable(command, projectRoot) {
+    const extensions = process.platform === "win32"
+        ? ["", ...(process.env["PATHEXT"] ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)]
+        : [""];
+    for (const directory of searchPath(projectRoot)) {
+        for (const extension of extensions) {
+            const candidate = join(directory, `${command}${extension}`);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+export function findMissing(requirements, projectRoot) {
+    return requirements.filter((requirement) => findExecutable(requirement.command, projectRoot) === undefined);
+}
+/** One line of advice per missing tool, grouped by where the fix lives. */
+export function installAdvice(missing) {
+    const lines = [];
+    if (missing.some((tool) => tool.source === "npm")) {
+        lines.push("Run `npm install` in the project (provides roblox-ts).");
+    }
+    if (missing.some((tool) => tool.source === "rokit")) {
+        lines.push("Run `rokit install` in the project (provides Rojo). Rokit itself: https://github.com/rojo-rbx/rokit", "If Rokit is installed but the tool is still not found, add ~/.rokit/bin to your PATH and reopen the terminal.");
+    }
+    return lines.join("\n      ");
+}
+/** PATH string with the project's own binaries first, the way npm scripts see it. */
+export function pathWithLocalBinaries(projectRoot) {
+    return searchPath(projectRoot).join(delimiter);
+}
+/** True when nothing is listening on the local port, checked by trying to take it. */
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => server.close(() => resolve(true)));
+        server.listen(port, "127.0.0.1");
+    });
+}
+/**
+ * True when `command` is on the plain PATH, the way a shell or an npm script
+ * sees it: no project binaries first, and none of Rowork's own fallback
+ * directories. Once a project has left Rowork, that is the only lookup left.
+ */
+export function isOnPlainPath(command) {
+    const extensions = process.platform === "win32"
+        ? ["", ...(process.env["PATHEXT"] ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)]
+        : [""];
+    return (process.env["PATH"] ?? "")
+        .split(delimiter)
+        .filter((entry) => entry.length > 0)
+        .some((directory) => extensions.some((extension) => isExecutable(join(directory, `${command}${extension}`))));
+}
+//# sourceMappingURL=toolchain.js.map

package/dist/core/tsconfig-edit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sets `compilerOptions` entries in tsconfig.json by editing the text.
+ *
+ * tsconfig.json belongs to the user and is often JSON with comments, which a
+ * parse-and-rewrite would destroy. So the value of an existing entry is replaced
+ * in place and a missing entry is inserted as a new line, leaving everything else,
+ * comments and layout included, exactly as it was. A value the user set to
+ * something else is never overwritten: it is reported, and nothing is written.
+ */
+export declare function setCompilerOptions(source: string, file: string, options: Record<string, string>): string;
+//# sourceMappingURL=tsconfig-edit.d.ts.map

package/dist/core/tsconfig-edit.js

@@ -0,0 +1,47 @@
+import { RoworkError } from "../cli/errors.js";
+/**
+ * Values Rowork itself used to write, that are safe to replace: the project
+ * template shipped the abandoned Roact JSX factory before React was chosen.
+ */
+const REPLACEABLE = {
+    jsxFactory: ["Roact.createElement"],
+    jsxFragmentFactory: ["Roact.Fragment"],
+};
+/**
+ * Sets `compilerOptions` entries in tsconfig.json by editing the text.
+ *
+ * tsconfig.json belongs to the user and is often JSON with comments, which a
+ * parse-and-rewrite would destroy. So the value of an existing entry is replaced
+ * in place and a missing entry is inserted as a new line, leaving everything else,
+ * comments and layout included, exactly as it was. A value the user set to
+ * something else is never overwritten: it is reported, and nothing is written.
+ */
+export function setCompilerOptions(source, file, options) {
+    let result = source;
+    for (const [key, wanted] of Object.entries(options)) {
+        const existing = new RegExp(`("${key}"\\s*:\\s*)"([^"]*)"`).exec(result);
+        if (existing !== null) {
+            const current = existing[2];
+            if (current === wanted)
+                continue;
+            if (!(REPLACEABLE[key] ?? []).includes(current)) {
+                throw new RoworkError(`${file} sets \`${key}\` to "${current}", and this needs "${wanted}".`, {
+                    hint: `Change it to "${wanted}" yourself if you are sure nothing else depends on it, then run the command again.`,
+                });
+            }
+            result = `${result.slice(0, existing.index)}${existing[1]}"${wanted}"${result.slice(existing.index + existing[0].length)}`;
+            continue;
+        }
+        const opening = /("compilerOptions"\s*:\s*\{)([ \t]*\n)([ \t]*)/.exec(result);
+        if (opening === null) {
+            throw new RoworkError(`Cannot find \`compilerOptions\` in ${file}.`, {
+                hint: `Add "${key}": "${wanted}" to it by hand.`,
+            });
+        }
+        const indent = opening[3];
+        const at = opening.index + opening[1].length + opening[2].length;
+        result = `${result.slice(0, at)}"${key}": "${wanted}",\n${indent}${result.slice(at)}`;
+    }
+    return result;
+}
+//# sourceMappingURL=tsconfig-edit.js.map

package/dist/core/ui-edit.d.ts

@@ -0,0 +1,31 @@
+import type { RoworkConfig } from "../plugins/api.js";
+/**
+ * Small, careful edits to the interface files the `ui` module generated and the user
+ * may since have changed. Same rules as `schema-edit.ts`: work on the text, refuse
+ * instead of guessing, and return the new text without touching the disk so the
+ * caller can write everything at once, or nothing.
+ *
+ * Two marker comments say where new things go. They are visible in the generated
+ * files, and moving them (or the lines above them) is how a user reorders the interface.
+ */
+export declare const SCREENS_MARKER = "{/* rowork:screens */}";
+export declare const ELEMENTS_MARKER = "{/* rowork:elements */}";
+/** Where the interface lives: `<source>/client/ui`. */
+export declare function uiDirectory(config: RoworkConfig): string;
+export declare function screensDirectory(config: RoworkConfig): string;
+/** The screens that exist, by name (`Shop` for `screens/ShopScreen.tsx`). */
+export declare function listScreens(root: string, config: RoworkConfig): string[];
+/** Shows a new screen from `App`. Refuses when it is already there. */
+export declare function addScreenToApp(source: string, file: string, className: string, importPath: string): string;
+/** Places a component inside a screen. Refuses when the screen already uses it. */
+export declare function addElementToScreen(source: string, file: string, componentName: string, importPath: string): string;
+/**
+ * True when the interface has the shape screens need: `App` lists screens between markers
+ * and `UiController` draws into `PlayerGui`. A project whose `ui` module predates screens
+ * does not, and is told what to change instead of being rewritten.
+ */
+export declare function screensSupported(root: string, config: RoworkConfig, read: (path: string) => string | undefined): {
+    ok: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=ui-edit.d.ts.map

package/dist/core/ui-edit.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { RoworkError } from "../cli/errors.js";
+import { resolveProjectPath } from "./config.js";
+/**
+ * Small, careful edits to the interface files the `ui` module generated and the user
+ * may since have changed. Same rules as `schema-edit.ts`: work on the text, refuse
+ * instead of guessing, and return the new text without touching the disk so the
+ * caller can write everything at once, or nothing.
+ *
+ * Two marker comments say where new things go. They are visible in the generated
+ * files, and moving them (or the lines above them) is how a user reorders the interface.
+ */
+export const SCREENS_MARKER = "{/* rowork:screens */}";
+export const ELEMENTS_MARKER = "{/* rowork:elements */}";
+/** Where the interface lives: `<source>/client/ui`. */
+export function uiDirectory(config) {
+    return `${config.paths.source}/client/ui`;
+}
+export function screensDirectory(config) {
+    return `${uiDirectory(config)}/screens`;
+}
+/** The screens that exist, by name (`Shop` for `screens/ShopScreen.tsx`). */
+export function listScreens(root, config) {
+    const directory = resolveProjectPath(root, screensDirectory(config));
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory)
+        .filter((file) => /Screen\.tsx$/.test(file))
+        .map((file) => file.replace(/Screen\.tsx$/, ""))
+        .sort();
+}
+function cannotFind(file, what) {
+    return new RoworkError(`Cannot find ${what} in ${file}.`, {
+        hint: `${file} no longer has the shape Rowork generated, so it was not touched. Put the marker back (or add the line by hand), then run the command again.`,
+    });
+}
+/** Adds `import { name } from "path";` after the last import, keeping the file's layout. */
+function addImport(source, name, path) {
+    const line = `import { ${name} } from "${path}";`;
+    const imports = [...source.matchAll(/^import[^;]*;[ \t]*$/gm)];
+    const last = imports.at(-1);
+    if (last === undefined)
+        return `${line}\n${source}`;
+    const end = last.index + last[0].length;
+    return `${source.slice(0, end)}\n${line}${source.slice(end)}`;
+}
+/** Puts `<Name />` on its own line just before the marker, at the marker's indentation. */
+function addBeforeMarker(source, file, marker, element) {
+    const at = source.indexOf(marker);
+    if (at < 0)
+        throw cannotFind(file, `the \`${marker}\` marker`);
+    const lineStart = source.lastIndexOf("\n", at) + 1;
+    const indent = /^[ \t]*/.exec(source.slice(lineStart, at))?.[0] ?? "";
+    return `${source.slice(0, lineStart)}${indent}${element}\n${source.slice(lineStart)}`;
+}
+/** Shows a new screen from `App`. Refuses when it is already there. */
+export function addScreenToApp(source, file, className, importPath) {
+    if (new RegExp(`<${className}[\\s/>]`).test(source)) {
+        throw new RoworkError(`${className} is already shown by ${file}.`, { hint: "Each screen is listed once." });
+    }
+    const withElement = addBeforeMarker(source, file, SCREENS_MARKER, `<${className} />`);
+    return addImport(withElement, className, importPath);
+}
+/** Places a component inside a screen. Refuses when the screen already uses it. */
+export function addElementToScreen(source, file, componentName, importPath) {
+    if (new RegExp(`<${componentName}[\\s/>]`).test(source)) {
+        throw new RoworkError(`${file} already uses ${componentName}.`, { hint: "Place a second one by hand if you need it." });
+    }
+    const withElement = addBeforeMarker(source, file, ELEMENTS_MARKER, `<${componentName} />`);
+    return addImport(withElement, componentName, importPath);
+}
+/**
+ * True when the interface has the shape screens need: `App` lists screens between markers
+ * and `UiController` draws into `PlayerGui`. A project whose `ui` module predates screens
+ * does not, and is told what to change instead of being rewritten.
+ */
+export function screensSupported(root, config, read) {
+    const app = read(resolveProjectPath(root, join(uiDirectory(config), "App.tsx")));
+    const controller = read(resolveProjectPath(root, join(config.paths.controllers, "UiController.tsx")));
+    if (app === undefined || !app.includes(SCREENS_MARKER)) {
+        return { ok: false, reason: `${uiDirectory(config)}/App.tsx has no \`${SCREENS_MARKER}\` marker` };
+    }
+    if (controller === undefined || !controller.includes("createPortal")) {
+        return { ok: false, reason: `${config.paths.controllers}/UiController.tsx does not draw into PlayerGui with createPortal` };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=ui-edit.js.map

package/dist/core/versions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Used only when GitHub cannot be reached while creating a project (offline,
+ * rate limited). It is the one version Rowork writes down itself, so the weekly
+ * upstream check reports it when it falls behind.
+ */
+export declare const FALLBACK_ROJO_VERSION = "7.7.0";
+/**
+ * The Rojo version to use: the one forced by `ROWORK_ROJO_VERSION` if set (a team
+ * that wants every project on the same version, and no lookup), otherwise the
+ * newest release, or undefined when GitHub cannot be reached. GitHub allows 60
+ * anonymous requests per hour per address, so a shared network can hit its limit:
+ * the caller then falls back with a warning.
+ */
+export declare function latestRojoVersion(): Promise<string | undefined>;
+/** The newest version of an npm package, or undefined if the registry cannot be reached. */
+export declare function latestNpmVersion(name: string): string | undefined;
+export declare function readRojoPin(projectRoot: string): string | undefined;
+/** Rewrites the Rojo version in rokit.toml, leaving the rest of the file alone. */
+export declare function writeRojoPin(projectRoot: string, version: string): boolean;
+/** `^3.0.0` and `~1.2.3` both mean `3.0.0` / `1.2.3` for comparison. */
+export declare function baseVersion(range: string): string;
+/** True when `version` (like "7.7.0") is at least `major.minor`. An unknown version is not. */
+export declare function rojoIsAtLeast(version: string | undefined, major: number, minor: number): boolean;
+//# sourceMappingURL=versions.d.ts.map