@scm-js/cli 0.8.9 → 0.8.11

package/dist/THIRD-PARTY-NOTICES.txt

@@ -1,4 +1,4 @@
-Third-party notices for scmjs 0.8.9
+Third-party notices for scmjs 0.8.11
 
 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

@@ -6856,13 +6856,44 @@ document.getElementById("go").onclick = go;
 }
 //#endregion
 //#region cli/src/about.ts
-/** `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";
+/** `scmjs about`: this build and whether npm has a newer one, who made it, the machine it runs on, the desktop app and Docker, and where everything is. */
+var VERSION = "0.8.11";
+var COMMIT = "71d8282";
 var BUILT = "2026-11-06";
-function aboutReport() {
+var PACKAGE = "@scm-js/cli";
+/** a < b, for x.y.z versions (a prerelease or build suffix is ignored). */
+function olderThan(a, b) {
+	const n = (v) => v.split(/[-+]/)[0].split(".").map((x) => Number(x) || 0);
+	const [x, y] = [n(a), n(b)];
+	for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
+	return false;
+}
+/** The newest version on npm, or null when npm could not be asked (offline, slow): two seconds at most. */
+async function newestVersion() {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`, {
+			signal: AbortSignal.timeout(2e3),
+			headers: { accept: "application/json" }
+		});
+		if (!res.ok) return null;
+		const v = (await res.json()).version;
+		return typeof v === "string" ? v : null;
+	} catch {
+		return null;
+	}
+}
+/** About's "Newest" row: the update to install, this one, or what npm has when this is newer (a build from a clone). */
+function newestLine(version, latest) {
+	if (latest === null) return import_picocolors.default.dim("could not ask npm");
+	if (olderThan(version, latest)) return `${import_picocolors.default.yellow(latest)}${dot}npm install -g ${PACKAGE}@latest`;
+	return import_picocolors.default.dim(latest === version ? "this one" : `${latest} on npm`);
+}
+async function aboutReport() {
+	const latest = await newestVersion();
 	return {
 		version: VERSION,
+		latest,
+		outdated: latest !== null && olderThan("0.8.11", latest),
 		commit: COMMIT,
 		built: BUILT,
 		node: process.version,
@@ -6902,6 +6933,7 @@ function printAbout(r) {
 				r.commit && `commit ${r.commit}`,
 				r.built && `built ${r.built}`
 			].filter(Boolean).join(dot)],
+			["Newest", newestLine(r.version, r.latest)],
 			["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)")],
@@ -6921,6 +6953,68 @@ function printAbout(r) {
 	];
 }
 //#endregion
+//#region cli/src/banner.ts
+/**
+* The app mark, the wireframe globe of `public/favicon.svg` and the splash screen, in braille (2 × 4 dots a
+* character): the splash's sphere (`src/components/splash/starfield.ts`) with 6 rings and 8 segments, turned 0.3 rad
+* about y and −0.45 about x, its near half and its outline, on 32 × 32 dots.
+*/
+var GLOBE = [
+	"   ⣠⡴⢶⡿⣿⢿⢿⣲⢦⣄   ",
+	" ⣠⠞⣡⠟⠯⢤⡧⠬⢷⡴⠛⠮⡳⣄ ",
+	"⢰⢳⡼⠁  ⡞   ⢣  ⣘⣾⡆",
+	"⡇⡼⠉⠙⠒⢦⠧⠤⠤⠤⠼⡖⠋⠁⠘⣾",
+	"⡷⣇   ⢸     ⢧  ⣠⣿",
+	"⠸⣏⠙⠒⠦⢼⠤⠤⠤⠤⠤⢼⠒⠋⢡⠇",
+	" ⠙⢦⣀⡀⢸     ⣞⣀⡴⠋ ",
+	"   ⠙⠻⠭⣯⣓⣒⣫⠽⠟⠋   "
+];
+/** The same globe in ASCII, for a console without braille (the old Windows one, where ui.ts's marks fall back too). */
+var GLOBE_ASCII = [
+	"     .-'''-.     ",
+	"   .'/  |  \\'.   ",
+	"  /-+---+---+-\\  ",
+	" |  |   |   |  | ",
+	" |==+===+===+==| ",
+	"  \\-+---+---+-/  ",
+	"   '.\\  |  /.'   ",
+	"     '-...-'     "
+];
+/** The logo's violet (#a06cf0), or the terminal's magenta without 24-bit colour. */
+var violet = (s) => truecolor ? rgb("#a06cf0", s) : import_picocolors.default.magenta(s);
+/**
+* `text` beside the globe, centred on its height; the text alone when the terminal is narrower than both. `width` is
+* the terminal's (80 when it is not one).
+*/
+function banner(text, { width = 80, ascii = !unicode } = {}) {
+	const art = ascii ? GLOBE_ASCII : GLOBE;
+	const artWidth = Math.max(...art.map((l) => l.length));
+	const indent = "  ", gap = "   ";
+	if (2 + artWidth + 3 + Math.max(...text.map((l) => visible(l).length)) > width) return text;
+	const top = Math.max(0, Math.floor((art.length - text.length) / 2));
+	return art.map((l, i) => text[i - top] ? `${indent}${violet(l.padEnd(artWidth))}${gap}${text[i - top]}` : `${indent}${violet(l.trimEnd())}`);
+}
+/** The overview, in place of commander's: the banner, the command groups as commander lays them out, the options. */
+function rootHelp(cmd, helper, version, opts = {}) {
+	const termWidth = helper.padWidth(cmd, helper);
+	const out = banner([
+		`${import_picocolors.default.bold(import_picocolors.default.cyan(cmd.name()))} ${import_picocolors.default.bold(version)}`,
+		"scmJS on the command line",
+		import_picocolors.default.dim("StarCraft: Brood War maps, replays, plugins and bots"),
+		"",
+		`${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(cmd))}`,
+		`${helper.styleTitle("Docs:")}  ${import_picocolors.default.cyan("https://docs.scmjs.dev")}`
+	], {
+		width: helper.helpWidth ?? 80,
+		...opts
+	});
+	out.push("");
+	const groups = helper.groupItems([...cmd.commands], helper.visibleCommands(cmd), (sub) => sub.helpGroup() || "Commands:");
+	for (const [heading, commands] of groups) out.push(...helper.formatItemList(heading, commands.map((sub) => helper.formatItem(helper.styleSubcommandTerm(helper.subcommandTerm(sub)), termWidth, helper.styleSubcommandDescription(helper.subcommandDescription(sub)), helper)), helper));
+	out.push(`${helper.styleTitle("Options:")} ${helper.visibleOptions(cmd).map((o) => helper.styleOptionTerm(helper.optionTerm(o))).join("   ")}`, "");
+	return out.join("\n");
+}
+//#endregion
 //#region src/formats/chk/binary.ts
 /** Little-endian readers/writers over a Uint8Array. StarCraft data is LE throughout. */
 var Reader$1 = class {
@@ -12976,10 +13070,18 @@ async function restoreBuiltMap(chk, extras) {
 	};
 }
 //#endregion
-//#region src/services/mapIo.ts
-/** Read a picked or dropped file into a parsed document. */
-async function openMapFile(file, handle = null) {
-	const loaded = await loadMap(new Uint8Array(await file.arrayBuffer()));
+//#region src/editor/mapFile.ts
+/**
+* A map file as bytes, in and out — the half of opening and saving that needs no browser.
+*
+* `openMapBytes` is what File ▸ Open, a drop, the command line and `@scm-js/core` all run:
+* the archive read, the scenario parsed, the other members kept, a built map restored to the
+* map it was built from, and the warnings the editor would show. `writeMapBytes` is the
+* reverse. The pickers, handles and downloads around them are `services/mapIo.ts`.
+*/
+/** Read a map file's bytes (.scm, .scx or a bare .chk) into a parsed scenario and the rest of its archive. */
+async function openMapBytes(bytes, fileName) {
+	const loaded = await loadMap(bytes);
 	const problems = [];
 	let members = {
 		extras: /* @__PURE__ */ new Map(),
@@ -13025,8 +13127,7 @@ async function openMapFile(file, handle = null) {
 		scenario,
 		extras,
 		stored,
-		fileName: file.name,
-		handle,
+		fileName,
 		origin: loaded.scenarioInfo,
 		builtBy
 	};
@@ -13677,7 +13778,7 @@ function kindOf(name, bytes) {
 }
 async function loadMapInput(input) {
 	try {
-		return await openMapFile(new File([input.bytes], input.name));
+		return await openMapBytes(input.bytes, input.name);
 	} catch (e) {
 		throw new CliError(`${input.name} is not a map this can read: ${e instanceof Error ? e.message : e}`);
 	}
@@ -16215,31 +16316,23 @@ 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({
+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().commandsGroup("This tool:").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),
 	styleArgumentText: (s) => import_picocolors.default.yellow(s),
-	styleOptionText: (s) => import_picocolors.default.green(s)
-}).addHelpText("after", () => `
-${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")}`);
-program.command("about").description("this version of scmjs, and where things are").addOption(json).action((o) => {
-	const r = aboutReport();
-	print(...o.json ? [JSON.stringify(r, null, 2)] : printAbout(r));
+	styleOptionText: (s) => import_picocolors.default.green(s),
+	subcommandTerm: (cmd) => {
+		const subs = cmd.commands.map((c) => c.name()).filter((n) => n !== "help");
+		return subs.length ? `${cmd.name()} ${subs.join("|")}` : new Help$1().subcommandTerm(cmd).replace(" [options]", "");
+	},
+	formatHelp: (cmd, helper) => cmd.parent ? Help$1.prototype.formatHelp.call(helper, cmd, helper) : rootHelp(cmd, helper, VERSION)
 });
-program.command("info").description("what a map, replay or bot file holds").argument("<files...>", "maps (.scm .scx .chk), replays (.rep) or bots (.scmbot)").addOption(json).action(async (files, o) => void await eachFile(files, !!o.json, async (input) => {
+program.command("info").description("what a map, replay or bot file holds").helpGroup("Maps and replays:").argument("<files...>", "maps (.scm .scx .chk), replays (.rep) or bots (.scmbot)").addOption(json).action(async (files, o) => void await eachFile(files, !!o.json, async (input) => {
 	const kind = expectKind(input, "map", "replay", "bot");
 	return kind === "map" ? mapInfo(input) : kind === "replay" ? replayInfo(input) : botInfo(input);
 }));
-var map = program.command("map").description("read, check and open maps");
+var map = program.command("map").description("read, check and open maps").helpGroup("Maps and replays:");
 map.command("info").description("a map's size, players, units, triggers and its check").argument("<maps...>").addOption(json).action(async (files, o) => void await eachFile(files, !!o.json, mapInfo));
 map.command("check").description("Check Map, as the editor's: errors, then warnings").argument("<maps...>").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 a map has errors (or warnings, with --strict): fit for a CI step.`).action(async (files, o) => {
 	const reports = await eachFile(files, !!o.json, async (input) => {
@@ -16266,14 +16359,14 @@ map.command("open").description("open a map in the scmJS app, or the editor in y
 	expectKind(input, "map");
 	await openInScmjs(input, o);
 });
-var replay = program.command("replay").description("read and open replays");
+var replay = program.command("replay").description("read and open replays").helpGroup("Maps and replays:");
 replay.command("info").description("who played, on what map, for how long, at what APM").argument("<replays...>").addOption(json).action(async (files, o) => void await eachFile(files, !!o.json, replayInfo));
 replay.command("open").description("watch a replay in the scmJS app, or the editor in your browser").argument("<replay>").option("--browser", "the editor in the browser, even with the app installed").addOption(new Option("--editor <url>", "the editor's address (SCMJS_EDITOR_URL)").hideHelp()).action(async (file, o) => {
 	const input = await readInput(file);
 	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");
+var plugin = program.command("plugin").description("start, check and run a plugin for the editor").helpGroup("Plugins and bots:");
 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,
@@ -16297,7 +16390,7 @@ plugin.command("dev").description("the editor with your plugin, reloaded on ever
 		editor: o.editor
 	});
 });
-var bot = program.command("bot").description("build your own BWAPI bot for scmjs.dev/play (needs Docker)").addHelpText("after", () => `
+var bot = program.command("bot").description("build a BWAPI bot for scmjs.dev/play (Docker)").helpGroup("Plugins and bots:").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…
 
@@ -16314,8 +16407,13 @@ bot.command("build").description("out/<key>.scmbot, to add on the play page").ac
 bot.command("update").description("the newest toolchain, the one the play page expects").action(async () => {
 	await updateBot();
 });
-try {
-	await program.parseAsync();
+program.command("about").description("this version, any newer one, and links").helpGroup("This tool:").addOption(json).action(async (o) => {
+	const r = await aboutReport();
+	print(...o.json ? [JSON.stringify(r, null, 2)] : printAbout(r));
+});
+if (!process.env.VITEST) try {
+	if (process.argv.length <= 2) program.outputHelp();
+	else await program.parseAsync();
 } catch (e) {
 	if (e instanceof CliError) {
 		fail(e);
@@ -16326,4 +16424,4 @@ try {
 	}
 }
 //#endregion
-export {};
+export { program };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-js/cli",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "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",