@scm-js/cli 0.8.8 → 0.8.9

package/dist/THIRD-PARTY-NOTICES.txt

@@ -1,4 +1,4 @@
-Third-party notices for scmjs 0.8.8
+Third-party notices for scmjs 0.8.9
 
 scmjs is MIT-licensed (LICENSE). It is built into one file from scmJS's own code and the
 packages below, whose license texts this file carries. Who wrote what, and where the

package/dist/scmjs.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
+import path, { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
-import childProcess, { execFileSync, spawn } from "node:child_process";
-import path, { basename, join, resolve } from "node:path";
-import fs, { existsSync, readFileSync } from "node:fs";
+import childProcess, { execFileSync, spawn, spawnSync } from "node:child_process";
+import fs, { existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
 import { createServer } from "node:http";
@@ -6081,6 +6081,8 @@ var catalogues = {
 		"Closed {name} — {next} is in front.": "{name}을(를) 닫음 — {next}이(가) 앞에 있습니다.",
 		"Closed the scenario — File ▸ New or Open to continue.": "시나리오를 닫음 — 파일 ▸ 새로 만들기 또는 열기로 계속하세요.",
 		"A copy of {name} to edit — Save asks where to keep it.": "편집할 {name}의 사본 — 저장할 때 위치를 묻습니다.",
+		"Reloaded {name}": "{name}{name|을} 다시 불러왔습니다",
+		"{name} did not build": "{name}{name|을} 빌드하지 못했습니다",
 		"The link uses the {name} plugin, which is turned off.": "이 링크는 꺼져 있는 {name} 플러그인을 사용합니다.",
 		"Turn It On": "켜기",
 		"Preparing workspace": "작업 공간 준비 중",
@@ -6597,6 +6599,79 @@ var CliError = class extends Error {
 		this.exitCode = exitCode;
 	}
 };
+var BOT_GUIDE = "https://github.com/scm-js/scmbot";
+/** Docker's version, or null when there is no Docker to run (not installed, or its engine not started). */
+function dockerVersion() {
+	const r = spawnSync("docker", [
+		"version",
+		"--format",
+		"{{.Server.Version}}"
+	], {
+		encoding: "utf8",
+		timeout: 1e4
+	});
+	return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+/**
+* `docker run`'s arguments: the folder mounted at /bot, its name given for `new` (the toolchain sees only /bot), this
+* command's name for the toolchain's messages, and on Linux and macOS the files written as the person running this
+* rather than as root.
+*/
+function dockerArgs(o) {
+	return [
+		"run",
+		"--rm",
+		...o.tty ? ["-it"] : ["-i"],
+		"-v",
+		`${o.folder}:/bot`,
+		"-e",
+		`SCMBOT_FOLDER=${basename(o.folder)}`,
+		"-e",
+		"SCMBOT_COMMAND=scmjs bot",
+		...o.user ? ["-u", o.user] : [],
+		o.image,
+		...o.args
+	];
+}
+var hasImage = (image) => spawnSync("docker", [
+	"image",
+	"inspect",
+	image
+], { stdio: "ignore" }).status === 0;
+function needDocker() {
+	if (dockerVersion()) return;
+	const installed = spawnSync("docker", ["--version"], { stdio: "ignore" }).status === 0;
+	throw new CliError(installed ? "Docker is installed but not running" : "scmjs bot needs Docker", installed ? "Start Docker (Docker Desktop on Windows and macOS), then run this again." : "Install it from https://docs.docker.com/get-docker/, then run this again.");
+}
+/** Runs the toolchain with `args` in this folder; the toolchain's own output and exit code are the command's. */
+async function runBot(args, image = process.env.SCMBOT_IMAGE || "ghcr.io/scm-js/scmbot") {
+	needDocker();
+	if (!hasImage(image)) print(import_picocolors.default.dim(`Downloading the bot toolchain (${image}), once. It is a few GB.`));
+	const user = process.platform === "win32" || !process.getuid ? null : `${process.getuid()}:${process.getgid?.()}`;
+	const child = spawn("docker", dockerArgs({
+		folder: process.cwd(),
+		args,
+		image,
+		tty: !!process.stdout.isTTY && !!process.stdin.isTTY,
+		user
+	}), { stdio: "inherit" });
+	const code = await new Promise((resolve) => {
+		child.on("error", () => resolve(1));
+		child.on("close", (c) => resolve(c ?? 1));
+	});
+	if (code) process.exitCode = code;
+}
+/** `scmjs bot update`: the newest toolchain, the one the play page expects. */
+async function updateBot(image = process.env.SCMBOT_IMAGE || "ghcr.io/scm-js/scmbot") {
+	needDocker();
+	print(import_picocolors.default.dim(`Fetching ${image}…`));
+	const child = spawn("docker", ["pull", image], { stdio: "inherit" });
+	if (await new Promise((resolve) => {
+		child.on("error", () => resolve(1));
+		child.on("close", (c) => resolve(c ?? 1));
+	})) throw new CliError("The toolchain could not be fetched", `docker pull ${image} said why, above.`);
+	print(`${mark.ok} The bot toolchain is up to date`);
+}
 //#endregion
 //#region cli/src/open.ts
 /**
@@ -6781,9 +6856,9 @@ document.getElementById("go").onclick = go;
 }
 //#endregion
 //#region cli/src/about.ts
-/** `scmjs about`: this build, the machine it runs on, the desktop app, and where everything is. */
-var VERSION = "0.8.8";
-var COMMIT = "a48a77c";
+/** `scmjs about`: this build, who made it, the machine it runs on, the desktop app and Docker, and where everything is. */
+var VERSION = "0.8.9";
+var COMMIT = "0469680";
 var BUILT = "2026-11-06";
 function aboutReport() {
 	return {
@@ -6793,6 +6868,7 @@ function aboutReport() {
 		node: process.version,
 		platform: `${process.platform} ${process.arch}`,
 		desktopApp: findDesktopApp(),
+		docker: dockerVersion(),
 		pluginApi: 1,
 		reads: {
 			maps: [
@@ -6800,21 +6876,25 @@ function aboutReport() {
 				".scx",
 				".chk"
 			],
-			replays: [".rep"]
+			replays: [".rep"],
+			bots: [".scmbot"]
 		},
 		links: {
 			editor: EDITOR_URL,
+			play: "https://scmjs.dev/play/",
 			docs: "https://docs.scmjs.dev",
+			bots: BOT_GUIDE,
 			source: "https://github.com/scm-js/scm-js",
 			issues: "https://github.com/scm-js/scm-js/issues"
 		},
+		author: "Jeany",
 		license: "MIT"
 	};
 }
 function printAbout(r) {
 	return [
 		`${import_picocolors.default.bold(import_picocolors.default.cyan("scmjs"))} ${import_picocolors.default.bold(r.version)}`,
-		import_picocolors.default.dim("StarCraft: Brood War maps and replays from the command line, by scmJS"),
+		import_picocolors.default.dim("StarCraft: Brood War maps, replays and bots from the command line, by scmJS"),
 		"",
 		...rows([
 			["Version", [
@@ -6824,13 +6904,18 @@ function printAbout(r) {
 			].filter(Boolean).join(dot)],
 			["Node", `${r.node}${dot}${r.platform}`],
 			["Desktop app", r.desktopApp ?? import_picocolors.default.dim("not found (scmjs … open uses the browser)")],
+			["Docker", r.docker ? `${r.docker}` : import_picocolors.default.dim("not found (scmjs bot needs it)")],
 			["Plugin API", String(r.pluginApi)],
-			["Reads", `maps ${r.reads.maps.join(" ")}${dot}replays ${r.reads.replays.join(" ")}`],
+			["Reads", `maps ${r.reads.maps.join(" ")}${dot}replays ${r.reads.replays.join(" ")}${dot}bots ${r.reads.bots.join(" ")}`],
 			null,
 			["Editor", import_picocolors.default.cyan(r.links.editor)],
+			["Play", import_picocolors.default.cyan(r.links.play)],
 			["Docs", import_picocolors.default.cyan(r.links.docs)],
+			["Bots", import_picocolors.default.cyan(r.links.bots)],
 			["Source", import_picocolors.default.cyan(r.links.source)],
 			["Issues", import_picocolors.default.cyan(r.links.issues)],
+			null,
+			["Made by", import_picocolors.default.bold(r.author)],
 			["Licence", r.license]
 		])
 	];
@@ -15225,6 +15310,690 @@ function wrap(text, width, most = 4) {
 	return lines.slice(0, most).join("\n") + (lines.length > most ? " …" : "");
 }
 //#endregion
+//#region src/plugins/loader.ts
+var PluginLoadError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PluginLoadError";
+	}
+};
+var ENTRY_EXT = /\.(?:ts|tsx|mts|js|mjs)$/i;
+function dirOf(url) {
+	return url.slice(0, url.lastIndexOf("/") + 1);
+}
+/**
+* `builtin:name`; `github:owner/repo[@ref][/dir]`; a github.com repository URL (with
+* an optional `/tree/ref/dir`); or any URL — a `.json` is the manifest, a script file
+* is the entry, anything else is a directory holding `plugin.json`.
+*/
+function parseSpec(spec) {
+	const s = spec.trim();
+	if (s === "") throw new PluginLoadError(t("Enter a plugin location."));
+	const builtin = /^builtin:([\w-]+)$/i.exec(s);
+	if (builtin) return {
+		kind: "builtin",
+		name: builtin[1]
+	};
+	const gh = /^github:([^/@\s]+)\/([^/@\s]+)(?:@([^/\s]+))?(?:\/(.*))?$/i.exec(s);
+	if (gh) return githubSource(gh[1], gh[2], gh[3], gh[4]);
+	const ghUrl = /^https?:\/\/(?:www\.)?github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?(?:\/tree\/([^/\s]+)(?:\/(.*?))?)?\/?$/i.exec(s);
+	if (ghUrl) return githubSource(ghUrl[1], ghUrl[2], ghUrl[3], ghUrl[4]);
+	if (/^https?:\/\//i.test(s)) {
+		let url;
+		try {
+			url = new URL(s);
+		} catch {
+			throw new PluginLoadError(t("Not a valid URL: {url}", { url: s }));
+		}
+		url.hash = "";
+		const path = url.pathname;
+		if (/\.json$/i.test(path)) return {
+			kind: "remote",
+			manifestUrl: url.href,
+			entryUrl: null,
+			base: dirOf(url.href),
+			display: s
+		};
+		if (ENTRY_EXT.test(path)) return {
+			kind: "remote",
+			manifestUrl: null,
+			entryUrl: url.href,
+			base: dirOf(url.href),
+			display: s
+		};
+		const base = url.href.endsWith("/") ? url.href : `${url.href}/`;
+		return {
+			kind: "remote",
+			manifestUrl: `${base}plugin.json`,
+			entryUrl: null,
+			base,
+			display: s
+		};
+	}
+	throw new PluginLoadError(t("Unrecognised plugin location \"{location}\". Paste a GitHub repository link such as https://github.com/owner/repo, the short form github:owner/repo, or a URL to a plugin.json or plugin.ts.", { location: s }));
+}
+function githubSource(owner, repo, ref, dir) {
+	const sub = dir ? dir.replace(/^\/+|\/+$/g, "") : "";
+	const base = `https://raw.githubusercontent.com/${owner}/${repo}/${ref ?? "HEAD"}/${sub ? `${sub}/` : ""}`;
+	const web = `https://github.com/${owner}/${repo}${ref || sub ? `/tree/${ref ?? "HEAD"}${sub ? `/${sub}` : ""}` : ""}`;
+	return {
+		kind: "remote",
+		manifestUrl: `${base}plugin.json`,
+		entryUrl: null,
+		base,
+		display: `github:${owner}/${repo}${ref ? `@${ref}` : ""}${sub ? `/${sub}` : ""}`,
+		webUrl: web,
+		github: {
+			owner,
+			repo,
+			ref: ref ?? null,
+			dir: sub
+		}
+	};
+}
+function validateManifest(raw, where) {
+	if (!raw || typeof raw !== "object") throw new PluginLoadError(t("{where} is not a JSON object.", { where }));
+	const m = raw;
+	if (typeof m.name !== "string" || m.name.trim() === "") throw new PluginLoadError(t("{where} needs a \"name\".", { where }));
+	const str = (k) => typeof m[k] === "string" ? m[k] : void 0;
+	const out = { name: m.name.trim() };
+	for (const k of [
+		"id",
+		"version",
+		"description",
+		"author",
+		"homepage",
+		"entry",
+		"build",
+		"icon"
+	]) {
+		const v = str(k);
+		if (v !== void 0) out[k] = v;
+	}
+	if (typeof m.api === "number") out.api = m.api;
+	for (const k of ["entry", "build"]) if (out[k] && /^(?:[a-z]+:)?\/\//i.test(out[k])) throw new PluginLoadError(t("{where}: \"{field}\" must be a path relative to the manifest.", {
+		where,
+		field: k
+	}));
+	if (Array.isArray(m.requires)) {
+		const requires = [];
+		for (const r of m.requires) {
+			if (typeof r !== "string" || r.trim() === "") continue;
+			let spec;
+			try {
+				spec = canonicalSpec(parseSpec(r));
+			} catch (err) {
+				throw new PluginLoadError(t("{where}: \"requires\" names a plugin location the editor cannot use, \"{location}\": {error}", {
+					where,
+					location: r,
+					error: err instanceof Error ? err.message : String(err)
+				}));
+			}
+			if (!requires.includes(spec)) requires.push(spec);
+		}
+		if (requires.length > 0) out.requires = requires;
+	}
+	return out;
+}
+var IMAGE_EXT = /\.(?:png|svg|jpe?g|gif|webp|avif|ico)$/i;
+var HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/**
+* A manifest `icon` string as the chrome should show it. Four forms are understood —
+* a short glyph (an emoji), a `data:image/…` URI, an `http(s)` image, and a path
+* relative to the manifest — and nothing else is: any other scheme (`javascript:`
+* above all) and any long non-path string resolve to null and the plugin simply shows
+* the default icon. `base` is where relative paths resolve from; a built-in has none
+* (its file comes through `BuiltinPlugin.iconUrl` instead).
+*/
+function resolveIcon(icon, base) {
+	const s = icon?.trim();
+	if (!s) return null;
+	if (/^data:image\//i.test(s) || /^https?:\/\//i.test(s)) return {
+		kind: "image",
+		url: s
+	};
+	if (HAS_SCHEME.test(s)) return null;
+	if (s.includes("/") || IMAGE_EXT.test(s)) {
+		if (!base) return null;
+		try {
+			return {
+				kind: "image",
+				url: new URL(s, base).href
+			};
+		} catch {
+			return null;
+		}
+	}
+	return [...s].length <= 4 ? {
+		kind: "text",
+		text: s
+	} : null;
+}
+/** The spec as it is stored and shown: the short form for a repository, `builtin:name` for a built-in. */
+function canonicalSpec(source) {
+	return source.kind === "builtin" ? `builtin:${source.name}` : source.display;
+}
+//#endregion
+//#region cli/src/plugin.ts
+/**
+* `scmjs plugin new | check | dev`: writing a plugin for the editor (docs/plugins.md, .claude/internals/cli.md).
+*
+* - `new` writes a plugin to start from, set up as the project's own are (Hello World's layout: manifest, source,
+*   Korean catalogue and its test, typings, build, the shared CI).
+* - `check` reads the plugin as the editor would load it (`validateManifest`, the file it would import, the imports
+*   it would refuse) and says what would go wrong, for a person or a CI step.
+* - `dev` serves the folder on the loopback address, builds it when it names a build, and opens the editor with
+*   `?plugin-dev=` (src/hooks/usePluginDev.ts), which installs it the usual way the first time and reloads it on
+*   every change the page is told of here.
+*/
+/** `Base Check` → `base-check`. */
+var pluginId = (name) => name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "my-plugin";
+/** `base-check` or `plugin-base-check` → `Base Check`. */
+var nameFromFolder = (folder) => basename(folder).replace(/^(?:scmjs-)?plugin-/, "").split(/[-_\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ") || "My Plugin";
+function gitUser() {
+	const r = spawnSync("git", ["config", "user.name"], { encoding: "utf8" });
+	return r.status === 0 ? r.stdout.trim() : "";
+}
+/** The files of a new plugin, by path. */
+function pluginFiles(o) {
+	const json = (v) => JSON.stringify(v, null, 2) + "\n";
+	const lit = JSON.stringify(o.name);
+	return {
+		"plugin.json": json({
+			name: o.name,
+			id: o.id,
+			version: "0.1.0",
+			description: `${o.name}: a plugin for the scmJS map editor.`,
+			...o.author ? { author: o.author } : {},
+			entry: "plugin.ts",
+			build: "dist/plugin.js",
+			icon: "🧩",
+			api: 1
+		}),
+		"plugin.ts": `/**
+ * ${o.name}: a plugin for the scmJS map editor.
+ *
+ * It adds Tools ▸ ${o.name}…, which opens a pane about the map that is open. Change it into your own; the API is
+ * documented at https://docs.scmjs.dev/plugins/.
+ *
+ *   npm start           the editor with this plugin, reloaded each time you save (scmjs plugin dev)
+ *   npm test            the tests, including the one that keeps ko.ts complete
+ *   npm run check       what the editor would make of this folder (scmjs plugin check)
+ */
+import type { PluginApi } from "@scm-js/plugin-api";
+import { KO } from "./ko";
+
+export default function activate(api: PluginApi) {
+  // The Korean for what the plugin shows (ko.ts). English is the key: pass every string to t() as a literal.
+  api.i18n.register({ ko: KO });
+  const t = api.i18n.t;
+
+  api.menu.add("Tools", {
+    label: ${JSON.stringify(`${o.name}…`)},
+    enabled: () => api.document.isOpen(),
+    run: () => {
+      const info = api.document.info();
+      const units = api.document.scenario()?.units.length ?? 0;
+      api.ui.dialog({
+        title: ${lit},
+        size: "sm",
+        mount(body) {
+          // Plain DOM: the editor gives the plugin an empty element to fill.
+          const name = document.createElement("p");
+          name.textContent = info?.name ?? ""; // the map's own text, never translated
+          const count = document.createElement("p");
+          count.textContent = t("{n, plural, one {# unit} other {# units}} on the map", { n: units });
+          body.append(name, count);
+        },
+        buttons: [{ label: t("Close") }],
+      });
+    },
+  });
+}
+`,
+		"ko.ts": `// Korean for every string the plugin shows; English is the key. tests/ko.test.ts keeps it complete.
+export const KO: Record<string, string> = {
+  "Close": "닫기",
+  "{n, plural, one {# unit} other {# units}} on the map": "맵의 유닛 {n, plural, other {#개}}",
+};
+`,
+		"tests/ko.test.ts": `import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { KO } from "../ko";
+
+// Every string the plugin shows through \`t("…")\`, or hands the editor as \`msg("…")\`, read from the source.
+// A plugin with more files lists them here.
+const files = ["plugin.ts"];
+const sources = files.map((f) => readFileSync(new URL(\`../\${f}\`, import.meta.url), "utf8"));
+const keys = new Set(sources.flatMap((source) => [...source.matchAll(/\\b(?:t|msg)\\("((?:[^"\\\\]|\\\\.)*)"/g)].map((m) => JSON.parse(\`"\${m[1]}"\`) as string)));
+
+describe("the Korean catalogue", () => {
+  it("has every string the plugin shows", () => {
+    expect([...keys].filter((k) => !(k in KO))).toEqual([]);
+  });
+  it("has nothing the plugin no longer shows", () => {
+    expect(Object.keys(KO).filter((k) => !keys.has(k))).toEqual([]);
+  });
+});
+`,
+		"package.json": json({
+			name: `scmjs-plugin-${o.id}`,
+			version: "0.1.0",
+			private: true,
+			description: `${o.name}: a plugin for the scmJS map editor.`,
+			...o.author ? { author: o.author } : {},
+			license: "MIT",
+			type: "module",
+			scripts: {
+				start: "scmjs plugin dev",
+				check: "scmjs plugin check",
+				build: "esbuild plugin.ts --bundle --format=esm --target=es2022 --platform=browser --outfile=dist/plugin.js --banner:js=\"// Generated by npm run build - do not edit; the source is plugin.ts.\"",
+				typecheck: "tsc -p tsconfig.json",
+				test: "vitest run"
+			},
+			devDependencies: {
+				"@scm-js/cli": `^${VERSION}`,
+				"@scm-js/plugin-api": `^1`,
+				esbuild: "^0.28.2",
+				typescript: "~6.0.2",
+				vitest: "^5.1.0"
+			}
+		}),
+		"tsconfig.json": json({
+			compilerOptions: {
+				target: "ES2022",
+				lib: [
+					"ES2022",
+					"DOM",
+					"DOM.Iterable"
+				],
+				module: "ESNext",
+				moduleResolution: "bundler",
+				types: [],
+				strict: true,
+				noUnusedLocals: true,
+				noUnusedParameters: true,
+				verbatimModuleSyntax: true,
+				erasableSyntaxOnly: true,
+				isolatedModules: true,
+				skipLibCheck: true,
+				noEmit: true
+			},
+			include: ["plugin.ts", "ko.ts"]
+		}),
+		".gitignore": "node_modules/\n*.tsbuildinfo\n",
+		".github/workflows/ci.yml": `# Type-check, test, and build dist/plugin.js, the bundle the editor loads (\`build\` in plugin.json), with the
+# workflow every scm-js plugin uses: on a push to main it commits the rebuilt bundle, on a v* tag it checks the
+# committed one matches, and weekly it type-checks against the newest @scm-js/plugin-api.
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  ci:
+    uses: scm-js/.github/.github/workflows/plugin-ci.yml@main
+`,
+		"README.md": `# ${o.name}
+
+A plugin for [scmJS](https://scmjs.dev/editor/), the StarCraft: Brood War map editor.
+
+## Developing
+
+\`\`\`sh
+npm install
+npm start          # opens the editor with the plugin, and reloads it each time you save
+\`\`\`
+
+\`npm test\` runs the tests, \`npm run typecheck\` the type-check, and \`npm run check\` says what the editor would
+make of the folder. The plugin guide is at [docs.scmjs.dev/plugins](https://docs.scmjs.dev/plugins/).
+
+## Installing
+
+Once this is a public GitHub repository, paste \`github:<you>/<repository>\` into Plugins ▸ Manage Plugins….
+Tag releases (\`v1.0.0\`): they are what the editor's update check offers.
+`,
+		LICENSE: `MIT License
+
+Copyright (c) ${o.year} ${o.author || "the authors"}
+
+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.
+`
+	};
+}
+/** `scmjs plugin new [name]`: a folder `plugin-<id>` (or `--dir`) with a plugin to start from. */
+function newPlugin(o) {
+	const name = (o.name?.trim() || (o.dir ? nameFromFolder(resolve(o.dir)) : "")).slice(0, 64);
+	if (!name) throw new CliError("Name the plugin", "scmjs plugin new \"Base Check\"  (or --dir <folder>)", 2);
+	const id = pluginId(name);
+	const dir = resolve(o.dir ?? `plugin-${id}`);
+	if (existsSync(dir) && readdirSync(dir).filter((f) => f !== ".git").length > 0) throw new CliError(`${relative(process.cwd(), dir) || "."} is not empty`, "Give an empty or new folder with --dir.", 2);
+	const files = pluginFiles({
+		name,
+		id,
+		author: gitUser(),
+		year: (/* @__PURE__ */ new Date()).getFullYear()
+	});
+	for (const [path, text] of Object.entries(files)) {
+		mkdirSync(dirname(join(dir, path)), { recursive: true });
+		writeFileSync(join(dir, path), text);
+	}
+	return {
+		dir,
+		files: Object.keys(files)
+	};
+}
+var SOURCE_EXT = [
+	".ts",
+	".tsx",
+	".mts",
+	".js",
+	".mjs"
+];
+/** The imports of a source file the editor would follow or refuse (type-only imports are erased first). */
+function sourceImports(code) {
+	const text = code.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'`])\/\/.*$/gm, "$1");
+	const out = [];
+	for (const m of text.matchAll(/\b(import|export)\s+(type\s+)?(?:[^'"`;]*?\sfrom\s*)?(['"])([^'"\n]+)\3|\bimport\s*\(\s*(['"])([^'"\n]+)\5\s*\)/g)) {
+		if (m[2]) continue;
+		out.push(m[4] ?? m[6]);
+	}
+	return out;
+}
+/** The file a relative import names, as the editor's loader looks for it (`./x`, `./x.js` meaning `x.ts`, `./dir`). */
+function importedFile(from, spec) {
+	const base = resolve(dirname(from), spec);
+	return [
+		base,
+		...SOURCE_EXT.map((e) => base + e),
+		base.replace(/\.js$/, ".ts"),
+		...SOURCE_EXT.map((e) => join(base, "index" + e))
+	].find((f) => existsSync(f) && statSync(f).isFile()) ?? null;
+}
+var newest = (dir, skip) => {
+	let t = 0;
+	for (const e of readdirSync(dir, { withFileTypes: true })) {
+		if (e.name.startsWith(".") || e.name === "node_modules" || skip.has(join(dir, e.name))) continue;
+		const p = join(dir, e.name);
+		if (e.isDirectory()) t = Math.max(t, newest(p, skip));
+		else if (SOURCE_EXT.includes(extname(e.name)) && !e.name.endsWith(".d.ts") && !p.includes(`${sep}tests${sep}`)) t = Math.max(t, statSync(p).mtimeMs);
+	}
+	return t;
+};
+/** `scmjs plugin check`: the plugin in `dir` as the editor would load it. */
+function checkPlugin(dirArg = ".") {
+	const dir = resolve(dirArg);
+	const out = {
+		dir,
+		name: null,
+		id: null,
+		version: null,
+		loads: null,
+		issues: []
+	};
+	const add = (level, message, hint) => out.issues.push({
+		level,
+		message,
+		...hint ? { hint } : {}
+	});
+	const file = join(dir, "plugin.json");
+	if (!existsSync(file)) throw new CliError(`No plugin.json in ${relative(process.cwd(), dir) || "this folder"}`, "Run this in the plugin's folder, or start one with scmjs plugin new.", 2);
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(file, "utf8"));
+	} catch (e) {
+		add("error", `plugin.json is not valid JSON: ${e.message}`);
+		return out;
+	}
+	let m;
+	try {
+		m = validateManifest(raw, "plugin.json");
+	} catch (e) {
+		add("error", e.message);
+		return out;
+	}
+	out.name = m.name;
+	out.id = m.id ?? pluginId(m.name);
+	out.version = m.version ?? null;
+	if (m.api === void 0) add("warn", "plugin.json names no \"api\"", `Add "api": 1, so an older editor says it is too old instead of failing.`);
+	else if (m.api > 1) add("error", `It needs plugin API ${m.api}; the editor provides 1`);
+	if (!m.id) add("info", `No "id": the editor uses "${out.id}", made from the name`, "An id keeps storage and commands the same if the name changes.");
+	for (const k of [
+		"version",
+		"description",
+		"author",
+		"homepage"
+	]) if (!m[k]) add("info", `No "${k}": shown when someone adds the plugin`);
+	const icon = resolveIcon(m.icon, "file:///plugin/plugin.json");
+	if (!m.icon) add("info", "No \"icon\": the default plugin mark is shown");
+	else if (!icon) add("warn", `The icon "${m.icon}" is not one the editor shows`, "An image beside plugin.json, an https or data: image, or up to four characters.");
+	else if (icon.kind === "image" && icon.url.startsWith("file:///plugin/") && !existsSync(join(dir, decodeURIComponent(icon.url.slice(15))))) add("error", `The icon ${m.icon} is not in the folder`);
+	const entry = m.entry ?? ["plugin.ts", "plugin.js"].find((f) => existsSync(join(dir, f)));
+	const entryFile = entry ? join(dir, entry) : null;
+	if (!entryFile || !existsSync(entryFile)) add("error", entry ? `The entry ${entry} is not there` : "No \"entry\", and neither plugin.ts nor plugin.js is there");
+	if (m.build) {
+		const built = join(dir, m.build);
+		out.loads = m.build;
+		if (!existsSync(built)) add("error", `The build ${m.build} is not there, and the editor loads it instead of ${entry ?? "the source"}`, existsSync(join(dir, "package.json")) ? "Run npm run build (scmjs plugin dev builds it for you)." : "Build it, or take \"build\" out of plugin.json.");
+		else if (newest(dir, /* @__PURE__ */ new Set([built])) > statSync(built).mtimeMs + 1e3) add("warn", `${m.build} is older than the source`, "Run npm run build, or the editor loads what it was.");
+	} else if (entryFile && existsSync(entryFile)) {
+		out.loads = entry;
+		const seen = /* @__PURE__ */ new Set(), todo = [entryFile];
+		while (todo.length) {
+			const f = todo.pop();
+			if (seen.has(f)) continue;
+			seen.add(f);
+			for (const spec of sourceImports(readFileSync(f, "utf8"))) if (/^(?:\.{1,2}\/|\/)/.test(spec)) {
+				const to = importedFile(f, spec);
+				if (to) todo.push(to);
+				else add("error", `${relative(dir, f)} imports ${spec}, which is not there`);
+			} else if (!/^https?:\/\//.test(spec)) add("error", `${relative(dir, f)} imports the package "${spec}"`, "The editor loads source without a module resolver: bundle the plugin and name the bundle as \"build\".");
+		}
+	}
+	if (out.issues.some((i) => i.level === "error")) out.loads = null;
+	return out;
+}
+function printPluginCheck(c, all) {
+	const shown = c.issues.filter((i) => all || i.level !== "info");
+	const errors = c.issues.filter((i) => i.level === "error").length, warns = c.issues.filter((i) => i.level === "warn").length;
+	const head = `${import_picocolors.default.bold(c.name ?? basename(c.dir))}${c.version ? import_picocolors.default.dim(` ${c.version}`) : ""}  ${errors ? `${mark.error} ${plural(errors, "error")}` : warns ? `${mark.warn} ${plural(warns, "warning")}` : `${mark.ok} loads`}${c.loads && !errors ? import_picocolors.default.dim(` (${c.loads})`) : ""}`;
+	const order = {
+		error: 0,
+		warn: 1,
+		info: 2
+	};
+	return [head, ...shown.sort((a, b) => order[a.level] - order[b.level]).flatMap((i) => [`  ${i.level === "error" ? mark.error : i.level === "warn" ? mark.warn : mark.info} ${i.message}`, ...i.hint ? [import_picocolors.default.dim(`    ${i.hint}`)] : []])];
+}
+var TYPES = {
+	".json": "application/json",
+	".js": "text/javascript",
+	".mjs": "text/javascript",
+	".ts": "text/plain",
+	".tsx": "text/plain",
+	".mts": "text/plain",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".css": "text/css",
+	".html": "text/html",
+	".txt": "text/plain",
+	".md": "text/plain"
+};
+var HEADERS = {
+	"access-control-allow-origin": "*",
+	"access-control-allow-private-network": "true",
+	"cache-control": "no-store"
+};
+/** The editor's address that loads the plugin served at `served` (src/plugins/devLink.ts reads it). */
+var devEditorUrl = (editor, served) => {
+	const u = new URL(editor);
+	u.searchParams.set("plugin-dev", served);
+	return u.href;
+};
+/** `scmjs plugin dev`: serve, build, open the editor, and tell it to reload on each change, until Ctrl+C. */
+async function devPlugin(o) {
+	const dir = resolve(o.dir ?? ".");
+	checkPlugin(dir);
+	const manifest = JSON.parse(readFileSync(join(dir, "plugin.json"), "utf8"));
+	const pkg = existsSync(join(dir, "package.json")) ? JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) : null;
+	const builds = !!(manifest.build && pkg?.scripts?.build);
+	if (builds && !existsSync(join(dir, "node_modules"))) throw new CliError("The plugin's packages are not installed", "Run npm install in its folder first.", 2);
+	const clients = /* @__PURE__ */ new Set();
+	const send = (event, data) => {
+		for (const c of clients) c.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+	};
+	let connected = false;
+	const server = createServer((req, res) => {
+		if (req.method === "OPTIONS") {
+			res.writeHead(204, {
+				...HEADERS,
+				"access-control-allow-methods": "GET",
+				"access-control-allow-headers": "*"
+			}).end();
+			return;
+		}
+		const path = decodeURIComponent(new URL(req.url ?? "/", "http://127.0.0.1").pathname);
+		if (path === "/__scmjs/events") {
+			res.writeHead(200, {
+				...HEADERS,
+				"content-type": "text/event-stream",
+				connection: "keep-alive"
+			});
+			res.write(`event: hello\ndata: ${JSON.stringify({ name: manifest.name })}\n\n`);
+			clients.add(res);
+			if (!connected) {
+				connected = true;
+				print(`${mark.ok} The editor is connected`);
+			}
+			req.on("close", () => clients.delete(res));
+			return;
+		}
+		const file = resolve(dir, "." + (path.endsWith("/") ? path + "index.html" : path));
+		if (!(file === dir || file.startsWith(dir + sep)) || /(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)/.test(relative(dir, file)) || !existsSync(file) || !statSync(file).isFile()) {
+			res.writeHead(404, HEADERS).end();
+			return;
+		}
+		res.writeHead(200, {
+			...HEADERS,
+			"content-type": TYPES[extname(file).toLowerCase()] ?? "application/octet-stream"
+		});
+		res.end(readFileSync(file));
+	});
+	await new Promise((ok, fail) => {
+		server.once("error", (e) => fail(e.code === "EADDRINUSE" ? new CliError(`Port ${o.port} is in use`, `Pick another with --port. The editor keeps one install per address, so stay with the one you choose.`) : e));
+		server.listen(o.port, "127.0.0.1", () => ok());
+	});
+	const served = `http://127.0.0.1:${o.port}/`;
+	const heartbeat = setInterval(() => {
+		for (const c of clients) c.write(": still here\n\n");
+	}, 2e4);
+	const build = () => new Promise((done) => {
+		if (!builds) return done(null);
+		const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", [
+			"run",
+			"build",
+			"--silent"
+		], {
+			cwd: dir,
+			shell: process.platform === "win32"
+		});
+		let text = "";
+		child.stdout.on("data", (d) => {
+			text += d;
+		});
+		child.stderr.on("data", (d) => {
+			text += d;
+		});
+		child.on("close", (code) => done(code === 0 ? null : text.trim() || `npm run build exited with ${code}`));
+		child.on("error", (e) => done(e.message));
+	});
+	const failed = await build();
+	const first = checkPlugin(dir);
+	print(`${import_picocolors.default.bold(first.name ?? basename(dir))}${first.version ? import_picocolors.default.dim(` ${first.version}`) : ""}`);
+	if (failed) print(`${mark.error} The build failed`, import_picocolors.default.dim(failed.split("\n").map((l) => `  ${l}`).join("\n")));
+	else for (const line of printPluginCheck(first, false).slice(1)) print(line);
+	const url = devEditorUrl(o.editor ?? process.env.SCMJS_EDITOR_URL ?? "https://scmjs.dev/editor/", served);
+	print(`${mark.info} Serving it at ${import_picocolors.default.cyan(served)}${builds ? dot + "built with npm run build" : ""}`);
+	if (o.open && process.env.BROWSER !== "none") {
+		openBrowser(url);
+		print(`${mark.info} Opening the editor. The first time, it asks you to add the plugin.`);
+	}
+	print(import_picocolors.default.dim(`  If nothing opens, go to ${url}`), import_picocolors.default.dim("  Watching for changes. Ctrl+C stops."));
+	let timer = null, changed = /* @__PURE__ */ new Set(), running = false;
+	const built = manifest.build?.replace(/^\.\//, "") ?? null;
+	const skip = (f) => {
+		const p = f.replace(/\\/g, "/");
+		return /(^|\/)(?:node_modules|\.git)(\/|$)/.test(p) || !!built && (p === built || p === dirname(built));
+	};
+	const flush = async () => {
+		if (running) {
+			timer = setTimeout(flush, 100);
+			return;
+		}
+		running = true;
+		const files = [...changed];
+		changed = /* @__PURE__ */ new Set();
+		const err = await build();
+		const at = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+		if (err) {
+			print(`${mark.error} ${import_picocolors.default.dim(at)} The build failed`, import_picocolors.default.dim(err.split("\n").slice(0, 12).map((l) => `  ${l}`).join("\n")));
+			send("failed", { text: err.split("\n").slice(0, 3).join("\n") });
+		} else {
+			send("reload", { files });
+			print(`${mark.ok} ${import_picocolors.default.dim(at)} ${files.slice(0, 3).join(", ")}${files.length > 3 ? ` and ${files.length - 3} more` : ""}${clients.size ? "; reloaded in the editor" : import_picocolors.default.dim("; no editor connected")}`);
+		}
+		running = false;
+	};
+	const watcher = watch(dir, { recursive: true }, (_e, f) => {
+		if (!f || skip(f)) return;
+		changed.add(f.replace(/\\/g, "/"));
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(flush, 150);
+	});
+	await new Promise((done) => {
+		const stop = () => {
+			watcher.close();
+			clearInterval(heartbeat);
+			for (const c of clients) c.end();
+			server.close();
+			print("", import_picocolors.default.dim("Stopped."));
+			done();
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+	});
+}
+//#endregion
 //#region cli/src/replay.ts
 /** `scmjs replay info`: who played, on what, for how long, from the replay's header, commands and its copy of the map. */
 var RACES = [
@@ -15352,8 +16121,8 @@ function printReplayInfo(r) {
 //#endregion
 //#region cli/src/main.ts
 /**
-* scmjs: StarCraft: Brood War maps and replays from the command line. One command, a noun for each kind of thing
-* (`map`, `replay`), the editor's own code underneath (docs/cli.md, .claude/internals/cli.md).
+* scmjs: StarCraft: Brood War maps, replays and bots from the command line. One command, a noun for each kind of
+* thing (`map`, `replay`, `plugin`, `bot`), the editor's own code underneath (docs/cli.md, .claude/internals/cli.md).
 */
 var json = new Option("--json", "print JSON instead of text, for scripts");
 /** Runs `fn` on each file in turn; a file that fails is said and the rest go on. JSON: one value, or a list for several. */
@@ -15442,7 +16211,11 @@ async function botInfo(input) {
 		]
 	};
 }
-var program = new Command$1("scmjs").description("StarCraft: Brood War maps and replays from the command line").version(VERSION, "-v, --version", "print the version").helpOption("-h, --help", "show help for a command").addOption(new Option("--no-color", "plain text, no colour (also NO_COLOR=1)")).showSuggestionAfterError().helpCommand("help [command]", "show help for a command").configureOutput({ outputError: (text, write) => write(text.replace(/^error: /, `${mark.error} `)) }).showHelpAfterError(import_picocolors.default.dim("(scmjs --help lists the commands)")).configureHelp({
+for (const stream of [process.stdout, process.stderr]) stream.on("error", (e) => {
+	if (e.code === "EPIPE") process.exit(process.exitCode ?? 0);
+	else throw e;
+});
+var program = new Command$1("scmjs").description("StarCraft: Brood War maps, replays, plugins and bots from the command line").version(VERSION, "-v, --version", "print the version").helpOption("-h, --help", "show help for a command").addOption(new Option("--no-color", "plain text, no colour (also NO_COLOR=1)")).showSuggestionAfterError().helpCommand("help [command]", "show help for a command").configureOutput({ outputError: (text, write) => write(text.replace(/^error: /, `${mark.error} `)) }).showHelpAfterError(import_picocolors.default.dim("(scmjs --help lists the commands)")).configureHelp({
 	styleTitle: (s) => import_picocolors.default.bold(s),
 	styleCommandText: (s) => import_picocolors.default.cyan(s),
 	styleSubcommandText: (s) => import_picocolors.default.cyan(s),
@@ -15453,6 +16226,8 @@ ${import_picocolors.default.bold("Examples:")}
   ${import_picocolors.default.dim("$")} scmjs info "(2)Destination.scx"       what a map or a replay holds
   ${import_picocolors.default.dim("$")} scmjs map check *.scx                 Check Map on every map here
   ${import_picocolors.default.dim("$")} scmjs replay open game.rep            watch it in the editor
+  ${import_picocolors.default.dim("$")} scmjs plugin new "Base Check"         a plugin for the editor to start from
+  ${import_picocolors.default.dim("$")} scmjs bot new                         a BWAPI bot to start from, for scmjs.dev/play
   ${import_picocolors.default.dim("$")} scmjs about                           this version, and where things are
 
 ${import_picocolors.default.dim("Docs: https://docs.scmjs.dev")}`);
@@ -15498,6 +16273,47 @@ replay.command("open").description("watch a replay in the scmJS app, or the edit
 	expectKind(input, "replay");
 	await openInScmjs(input, o);
 });
+var plugin = program.command("plugin").description("write a plugin for the editor: start one, check it, run it");
+plugin.command("new").description("a plugin to start from, in a new folder").argument("[name]", "the plugin's name, such as \"Base Check\"").option("--dir <folder>", "the folder to write it in (default plugin-<id>)").action((name, o) => {
+	const made = newPlugin({
+		name,
+		dir: o.dir
+	});
+	const rel = relative(process.cwd(), made.dir) || ".";
+	print(`${mark.ok} ${import_picocolors.default.bold(name ?? rel)} written in ${import_picocolors.default.cyan(rel)}${dot}${plural(made.files.length, "file")}`, "", import_picocolors.default.dim("  Next:"), `    cd ${rel.includes(" ") ? JSON.stringify(rel) : rel}`, "    npm install", `    npm start            ${import_picocolors.default.dim("the editor with your plugin, reloaded each time you save")}`, "", import_picocolors.default.dim("  plugin.ts is the plugin; plugin.json describes it. Guide: https://docs.scmjs.dev/plugins/"));
+});
+plugin.command("check").description("what the editor would make of the plugin").argument("[folder]", "the plugin's folder", ".").addOption(json).option("--all", "list notes too, not only errors and warnings").option("--strict", "fail on warnings as well as errors").addHelpText("after", `\nExits 1 when the editor would not load it (or on warnings, with --strict): fit for a CI step.`).action((folder, o) => {
+	const c = checkPlugin(folder);
+	if (c.issues.some((i) => i.level === "error" || o.strict && i.level === "warn")) process.exitCode = 1;
+	print(...o.json ? [JSON.stringify(c, null, 2)] : printPluginCheck(c, !!o.all));
+});
+plugin.command("dev").description("the editor with your plugin, reloaded on every save").argument("[folder]", "the plugin's folder", ".").option("--port <port>", "the port to serve it on; the editor remembers the plugin by it", "5310").option("--no-open", "do not open the editor; print its address instead").addOption(new Option("--editor <url>", "the editor's address (SCMJS_EDITOR_URL), such as a local one").hideHelp()).addHelpText("after", `\nBuilds it first when plugin.json names a "build" and package.json has a build script.`).action(async (folder, o) => {
+	const port = Number(o.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new CliError(`--port ${o.port} is not a port`, null, 2);
+	await devPlugin({
+		dir: folder,
+		port,
+		open: o.open,
+		editor: o.editor
+	});
+});
+var bot = program.command("bot").description("build your own BWAPI bot for scmjs.dev/play (needs Docker)").addHelpText("after", () => `
+Run these in your bot's folder. The toolchain is a Docker image, downloaded the first time.
+A built bot is added on the play page: Options → Community bots → Add a bot from a file…
+
+${import_picocolors.default.dim(`Guide: ${BOT_GUIDE}`)}`);
+bot.command("new").description("a bot to start from, in this folder").action(async () => {
+	await runBot(["new"]);
+});
+bot.command("init").description("scmbot.json from the bot's Visual Studio project").argument("[project]", "the .vcxproj, when the folder has several").action(async (project) => {
+	await runBot(project ? ["init", project] : ["init"]);
+});
+bot.command("build").description("out/<key>.scmbot, to add on the play page").action(async () => {
+	await runBot(["build"]);
+});
+bot.command("update").description("the newest toolchain, the one the play page expects").action(async () => {
+	await updateBot();
+});
 try {
 	await program.parseAsync();
 } catch (e) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@scm-js/cli",
-  "version": "0.8.8",
-  "description": "StarCraft: Brood War maps and replays from the command line: what a map or replay holds, Check Map, and opening them in scmJS",
+  "version": "0.8.9",
+  "description": "StarCraft: Brood War maps, replays and bots from the command line: what a map or replay holds, Check Map, opening them in scmJS, and building a BWAPI bot for the play page",
   "keywords": [
     "starcraft",
     "brood war",
@@ -10,9 +10,12 @@
     "scm",
     "scx",
     "rep",
-    "cli"
+    "cli",
+    "bwapi",
+    "bot"
   ],
   "license": "MIT",
+  "author": "Jeany",
   "type": "module",
   "bin": {
     "scmjs": "dist/scmjs.mjs"