@moku-labs/game 0.9.0 → 0.10.0

package/dist/cli.d.mts

@@ -0,0 +1,70 @@
+//#region src/cli.d.ts
+/**
+ * What the dev page of `preparePage` is written with besides the game.
+ *
+ * @example
+ * ```ts
+ * // The editor against an engine working tree: its agent on the page, the tree's recipe in Bun.
+ * const options: PreparePageOptions = {
+ *   agents: ["@moku-labs/editor/agent/page"],
+ *   preload: ["../engine/scripts/tree/preload.ts"],
+ *   servePlugins: ["../engine/scripts/tree/bundle.ts"]
+ * };
+ * ```
+ */
+type PreparePageOptions = {
+  /** Agent modules the dev page passes to startPage, in order. Each default-exports a PageAgent. Bare specifiers or absolute paths. */agents?: readonly string[]; /** Files Bun preloads in the serving process. Relative paths resolve against the cwd. */
+  preload?: readonly string[]; /** Bun plugins the dev page bundles with, after the hot plugin. Relative paths resolve against the cwd. */
+  servePlugins?: readonly string[];
+};
+/**
+ * The written dev page: what a Bun server imports, and the config it runs under.
+ *
+ * @example
+ * ```ts
+ * // The editor re-runs itself under the page's bunfig, in the game folder.
+ * const { html, bunfig } = await preparePage("games/timber");
+ * Bun.spawn([process.execPath, `--config=${bunfig}`, Bun.main, html, "--root", "games/timber"], { cwd: "games/timber" });
+ * ```
+ */
+type PreparedPage = {
+  /** Absolute path of `<root>/.moku/index.html`: the HTML a Bun server imports. */html: string; /** Absolute path of `<root>/.moku/bunfig.toml`: pass it as `bun --config=<bunfig>`. */
+  bunfig: string;
+};
+/**
+ * Runs one `moku-game` command line in this process: `dev`, `build`, `native <verb>`, `keys`,
+ * `pack` or `help`, with `--root`, `--preload` and `--serve-plugin` before or after the command
+ * word. Every line goes through the branded console; nothing exits the process.
+ *
+ * @param argv - The arguments after the bin.
+ * @returns The exit code.
+ * @example
+ * ```ts
+ * // bin/moku-game.mjs in a game folder:
+ * await runCli(["dev", "--port", "0"]); // 0 after Ctrl+C; stdout had "http://localhost:<port>/"
+ * await runCli(["help"]); // 0
+ * ```
+ */
+declare function runCli(argv: readonly string[]): Promise<number>;
+/**
+ * Writes a game's dev page into `<root>/.moku/` for a server the caller starts: `index.html`,
+ * `dev.ts`, `main.ts` with the scenarios of `tests/scenarios/` (and, with agents, the agents and
+ * the game's `.dev` modules), and `bunfig.toml` with the engine's hot plugin. It starts no server
+ * and no watcher, and throws the `[game]` errors of `moku-game dev`.
+ *
+ * @param root - The game folder, relative to the cwd or absolute.
+ * @param options - The agents, the preloads and the extra bundler plugins.
+ * @returns The absolute paths of the HTML and the bunfig.
+ * @throws {Error} When the game has no `config.ts` or `index.ts`, a config value is refused, the
+ *   game does not resolve `@moku-labs/game/hot`, or a preload or plugin is not a file.
+ * @example
+ * ```ts
+ * // The editor bin, started with --root games/timber:
+ * const { preparePage } = await import(Bun.resolveSync("@moku-labs/game/cli", root));
+ * await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
+ * // { html: "<cwd>/games/timber/.moku/index.html", bunfig: "<cwd>/games/timber/.moku/bunfig.toml" }
+ * ```
+ */
+declare function preparePage(root: string, options?: PreparePageOptions): Promise<PreparedPage>;
+//#endregion
+export { PreparePageOptions, PreparedPage, preparePage, runCli };