@amxts/cli 0.2.1 → 0.3.0

package/src/init.mjs

@@ -23,7 +23,7 @@ import { npmRegistry, versionsFor } from './registry.mjs';
 import { askServer, canAsk, missingServer, serverEnv, serverFolder } from './server.mjs';
 import { HOST_SYSTEM, serverSystemOf, SYSTEMS } from './system.mjs';
 import { copyTemplate, gitAuthor, writeFile } from './template.mjs';
-import { c, CliError } from './ui.mjs';
+import { banner, c, CliError } from './ui.mjs';
 
 /**
  * The tools a project gets besides the core and its modules. knip reads the
@@ -80,7 +80,8 @@ export async function initProject(options) {
 	const localCore = local ? await needLocalCore() : null;
 	const localModules = localCore?.api.localModules() ?? {};
 
-	p.intro(`${c.bold(c.cyan('amxts'))} ${c.dim(VERSION)} ${c.dim('·')} a new project`);
+	banner(VERSION, 'a new project', { logo: true });
+	p.intro();
 
 	// 1. The package manager, first: the rest is said in its words.
 	const detected = packageManagerOfAgent() ?? 'npm';

package/src/lock.mjs

@@ -0,0 +1,94 @@
+// One `amxts dev` per project: two would build and deploy at the same time.
+// The one running holds .amxts/dev.lock - its pid, when it started and its
+// script. A second one stops with where the first runs; --takeover stops the
+// first instead, once its command line shows it is still that amxts dev - a
+// pid alone could be a new process by now. A lock whose process is gone is
+// taken over quietly.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { CliError } from './ui.mjs';
+
+/** The lock of a project's dev. */
+export const lockPath = root => join(root, '.amxts', 'dev.lock');
+
+/** Whether a process is there: a signal 0 reaches it, or it is someone else's. */
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === 'EPERM';
+	}
+}
+
+/** A process's command line, or '' when it cannot be read. */
+export function commandLineOf(pid) {
+	try {
+		if (process.platform === 'win32') {
+			return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter 'ProcessId=${Number(pid)}').CommandLine`], { encoding: 'utf8', windowsHide: true }).trim();
+		}
+		if (process.platform === 'linux') return readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+		return execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+	} catch {
+		return '';
+	}
+}
+
+/** The lock's holder, when it is still the dev that wrote it: alive, and running the same script. */
+function holder(lock) {
+	if (!lock?.pid || lock.pid === process.pid || !alive(lock.pid)) return null;
+	const line = commandLineOf(lock.pid).replace(/\\/g, '/');
+	return line.includes(String(lock.script).replace(/\\/g, '/')) ? lock : null;
+}
+
+/** Stops a process and what it started: on Windows the whole tree, elsewhere it stops its own (dev does, on SIGTERM). */
+export function stopTree(pid) {
+	if (process.platform === 'win32') {
+		spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+	} else {
+		try {
+			process.kill(pid, 'SIGTERM');
+		} catch {}
+	}
+}
+
+/** Stops a process (stopTree) and waits up to `wait` ms for it to be gone. */
+function stop(pid, wait = 5000) {
+	stopTree(pid);
+	const until = Date.now() + wait;
+	while (alive(pid) && Date.now() < until) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+	return !alive(pid);
+}
+
+/**
+ * Takes the project's dev lock, released when this process exits.
+ * @param {string} root the project's folder
+ * @param {{ takeover?: boolean, script?: string, say?: (line: string) => void }} [options]
+ * @throws {CliError} when another dev holds it and `takeover` is not given
+ */
+export function takeLock(root, { takeover = false, script = process.argv[1], say = () => {} } = {}) {
+	const path = lockPath(root);
+	let lock = null;
+	try {
+		lock = JSON.parse(readFileSync(path, 'utf8'));
+	} catch {}
+	const other = holder(lock);
+	if (other) {
+		const since = new Date(other.since).toLocaleString();
+		if (!takeover) {
+			throw new CliError(`amxts dev is already running in another terminal (pid ${other.pid}, since ${since})`, 'Stop it there, or take it over: amxts dev --takeover');
+		}
+		// Read again just before stopping it: the pid must still be that dev.
+		if (holder(other) && !stop(other.pid)) throw new CliError(`amxts dev (pid ${other.pid}) did not stop`, 'Stop it in its terminal, then run amxts dev again.');
+		say(`stopped the amxts dev that ran since ${since} (pid ${other.pid})`);
+	}
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ pid: process.pid, since: new Date().toISOString(), script })}\n`);
+	process.on('exit', () => {
+		try {
+			if (JSON.parse(readFileSync(path, 'utf8')).pid === process.pid) rmSync(path, { force: true });
+		} catch {}
+	});
+}

package/src/main.mjs

@@ -11,13 +11,15 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { GLOBAL_FLAGS, parseArgs } from './args.mjs';
-import { needBun, needProject, projectCore, runTask, runTaskOrExit, VERSION } from './core.mjs';
+import { needBun, needProject, projectCore, runTask, runTaskOrExit, setting, startTask, VERSION } from './core.mjs';
 import { prepare, TARGETS } from './includes.mjs';
+import { stopTree, takeLock } from './lock.mjs';
 import { detectPackageManager, PACKAGE_MANAGERS, run } from './pm.mjs';
 import { serverMismatch } from './server-update.mjs';
 import { ensureServer } from './server.mjs';
 import { SYSTEMS } from './system.mjs';
 import { banner, c, CliError, closest, log, report } from './ui.mjs';
+import { updateLine } from './update-check.mjs';
 
 /** --os, for the commands that compile: the plugins are built for that system. */
 const OS_FLAG = { type: 'string', value: Object.keys(SYSTEMS).join('|'), description: 'The server\'s system, when AMXTS_SERVER does not show it: the plugins are compiled for it' };
@@ -28,6 +30,12 @@ function warnServer(core, os) {
 	if (line) log.warn(line);
 }
 
+/** The line about a newer amxts, once a day at most (update-check.mjs). */
+function nudge(core) {
+	const line = updateLine(core.version, detectPackageManager());
+	if (line) log.info(line);
+}
+
 /** --os as the build task takes it. */
 function osArgs(values) {
 	if (values.os === undefined) return [];
@@ -84,25 +92,76 @@ export const COMMANDS = {
 	},
 	dev: {
 		description: 'Build, deploy to the server in AMXTS_SERVER, and again on every save',
-		usage: 'amxts dev [--os windows|linux] [--docker]',
+		usage: 'amxts dev [--os windows|linux] [--docker] [--no-tui] [--takeover]',
 		flags: {
 			os: OS_FLAG,
 			docker: { type: 'boolean', description: 'For the Docker server that mounts this project: build for Linux into dist/ on every save, which it reloads, and show its console' },
+			tui: { type: 'boolean', description: 'The panel under the build\'s lines, in a terminal (--no-tui, or AMXTS_TUI=plain, for the lines alone)' },
+			takeover: { type: 'boolean', description: 'Stop the amxts dev already running for this project, and run here' },
 		},
-		examples: ['amxts dev', 'amxts dev --os linux', 'amxts dev --docker'],
+		examples: ['amxts dev', 'amxts dev --os linux', 'amxts dev --docker', 'amxts dev --takeover'],
 		async run({ values }) {
 			if (values.docker && values.os && values.os !== 'linux')
 				throw new CliError('The Docker server is Linux: --docker builds for Linux.', 'Leave out --os.');
 			const core = await projectCore();
-			banner(core.version, 'dev');
+			const root = needProject();
+			const { devPanel, wantsPanel } = await import('./dev-panel.mjs');
+			// The panel has the logo in it; the build's lines alone start with it.
+			const panel = wantsPanel({ tui: values.tui });
+			if (!panel) banner(core.version, 'dev', { logo: true });
+			takeLock(root, { takeover: values.takeover, say: log.info });
+			nudge(core);
 			// The container reads dist/ where it is: nothing to deploy, and AMXTS_SERVER is not asked.
 			if (!values.docker) {
-				await ensureServer(needProject(), detectPackageManager());
+				await ensureServer(root, detectPackageManager());
 				warnServer(core, osArgs(values));
 			}
 			await prepare(core, { quiet: true });
-			if (values.docker) runTaskOrExit(core, 'build', ['--watch', '--docker', '--os', 'linux']);
-			else runTaskOrExit(core, 'build', ['--deploy', '--watch', ...osArgs(values)]);
+			const args = values.docker ? ['--watch', '--docker', '--os', 'linux'] : ['--deploy', '--watch', ...osArgs(values)];
+			if (panel) {
+				const { rconTarget } = await import('./rcon.mjs');
+				devPanel(core, args, { target: rconTarget(root), deployTo: values.docker ? '' : setting(root, 'AMXTS_SERVER').replace(/\\/g, '/') });
+				return;
+			}
+			const child = startTask(core, 'build', args);
+			// --takeover from another terminal: the build goes with this.
+			for (const signal of ['SIGTERM', 'SIGHUP']) {
+				process.on(signal, () => {
+					stopTree(child.pid);
+					process.exit(0);
+				});
+			}
+			child.on('exit', code => process.exit(code ?? 1));
+		},
+	},
+	rcon: {
+		description: 'Send a command to the project\'s server over rcon and print its answer',
+		usage: 'amxts rcon <command> [--json]',
+		flags: {
+			json: { type: 'boolean', description: 'Print { server, command, reply } - or { server, command, error } - as JSON' },
+		},
+		examples: ['amxts rcon amxts_plugins', 'amxts rcon status --json', 'amxts rcon changelevel de_dust2'],
+		async run({ values, positionals }) {
+			const command = positionals.join(' ').trim();
+			if (!command) throw new CliError('amxts rcon: which command?', 'amxts rcon amxts_plugins');
+			const { rcon, rconTarget } = await import('./rcon.mjs');
+			const target = rconTarget(needProject());
+			if (!target) throw new CliError('AMXTS_SERVER is not set: rcon reaches the server it names', 'Set it in .env beside package.json: AMXTS_SERVER=D:/hlds/cstrike/addons/amxts');
+			if (!target.password) throw new CliError(`rcon is not set up: no rcon_password in ${target.cfg}`, 'Add a line  rcon_password "something"  to it and restart the server.');
+			const server = `${target.host}:${target.port}`;
+			const answer = await rcon(target, command);
+			if (values.json) {
+				console.log(JSON.stringify({ server, command, ...answer }));
+				if ('error' in answer) process.exitCode = 1;
+				return;
+			}
+			if ('reply' in answer) {
+				process.stdout.write(answer.reply.endsWith('\n') || !answer.reply ? answer.reply : `${answer.reply}\n`);
+				return;
+			}
+			throw answer.error === 'no answer'
+				? new CliError(`The server at ${server} does not answer`, 'Is it running? AMXTS_PORT in .env names a port other than 27015.')
+				: new CliError(`The server refused the rcon_password of ${target.cfg}`, 'The server reads it as it starts: restart it after a change.');
 		},
 	},
 	build: {
@@ -118,6 +177,7 @@ export const COMMANDS = {
 			const os = osArgs(values);
 			const core = await projectCore();
 			banner(core.version, 'build');
+			nudge(core);
 			warnServer(core, os);
 			if (values.deploy) await ensureServer(needProject(), detectPackageManager());
 			await prepare(core, { quiet: true });
@@ -131,6 +191,7 @@ export const COMMANDS = {
 		async run() {
 			const core = await projectCore();
 			banner(core.version, 'typecheck');
+			nudge(core);
 			await prepare(core, { quiet: true });
 			if (runTask(core, 'typecheck') !== 0) {
 				throw new CliError('The plugins have type errors', 'They are listed above, file:line first.');
@@ -183,7 +244,15 @@ export const COMMANDS = {
 		description: 'Fetch the server\'s includes and write .amxts/tsconfig.json for the editor (build does it too)',
 		usage: 'amxts prepare',
 		async run() {
-			await prepare(await projectCore());
+			try {
+				await prepare(await projectCore());
+			} catch (error) {
+				// A project's postinstall: installing a newer command into a project of
+				// an older core - the upgrade's first step - is no failed install.
+				if (!(error instanceof CliError) || process.env.npm_lifecycle_event !== 'postinstall') throw error;
+				log.warn(error.message);
+				if (error.hint) log.hint(error.hint);
+			}
 		},
 	},
 	upgrade: {

package/src/modules.json

@@ -14,6 +14,21 @@
 		],
 		"requires": []
 	},
+	{
+		"name": "ftp",
+		"npm": "@amxts/ftp",
+		"repo": "amxts/ftp",
+		"description": "FTP, FTPS and SFTP - upload, download and list files on another server, every call a promise",
+		"category": "network",
+		"type": "official",
+		"logo": "https://raw.githubusercontent.com/amxts/ftp/HEAD/assets/logo.svg",
+		"maintainers": [
+			{
+				"github": "kukson777"
+			}
+		],
+		"requires": []
+	},
 	{
 		"name": "menu-core",
 		"npm": "@amxts/menu-core",

package/src/rcon.mjs

@@ -0,0 +1,134 @@
+// rcon to the project's server: GoldSrc's, over UDP. A packet starts with four
+// 0xFF; `challenge rcon` is answered with a number, and `rcon <number>
+// "<password>" <command>` with what the command printed, an `l` after the
+// 0xFFs, in as many packets as it takes.
+//
+// The server is the one AMXTS_SERVER names: on this machine (127.0.0.1), on
+// AMXTS_PORT (27015 by default), with the rcon_password of its server.cfg -
+// what the build reloads plugins with.
+import { Buffer } from 'node:buffer';
+import { createSocket } from 'node:dgram';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setting } from './core.mjs';
+import { serverFolderOrNull } from './server.mjs';
+
+const HEAD = Buffer.from([255, 255, 255, 255]);
+
+/** A connectionless packet: four 0xFF, then the text. */
+export function packet(text) {
+	return Buffer.concat([HEAD, Buffer.from(`${text}\n`, 'latin1')]);
+}
+
+/** The text of a reply: after the four 0xFF and an `l` (a printed reply), without the trailing NULs. */
+export function replyText(buffer) {
+	if (buffer.length < 4 || !buffer.subarray(0, 4).equals(HEAD)) return '';
+	return buffer.subarray(4).toString('latin1').replace(/^l/, '').replace(/\0+$/, '');
+}
+
+/** The rcon_password a server.cfg sets, or ''. */
+export function cfgPassword(text) {
+	return text.match(/^\s*rcon_password\s+"?([^"\r\n]*)"?/m)?.[1]?.trim() ?? '';
+}
+
+/**
+ * @typedef {object} RconTarget
+ * @property {string} host its address
+ * @property {number} port its UDP port
+ * @property {string} password '' when none is set
+ * @property {string} cfg the server.cfg the password is read from, for the words
+ */
+
+/** The project's server as rcon reaches it; null without AMXTS_SERVER. */
+export function rconTarget(root) {
+	const server = serverFolderOrNull(setting(root, 'AMXTS_SERVER'));
+	if (!server) return null;
+	const cfg = join(server, '..', '..', 'server.cfg').replace(/\\/g, '/');
+	return {
+		host: '127.0.0.1',
+		port: Number(setting(root, 'AMXTS_PORT') || 27015),
+		password: existsSync(cfg) ? cfgPassword(readFileSync(cfg, 'utf8')) : '',
+		cfg,
+	};
+}
+
+/**
+ * Sends one packet and collects what comes back until it goes quiet; null
+ * when nothing does.
+ */
+function ask(socket, target, text, wait) {
+	return new Promise((done) => {
+		let reply = null;
+		let timer;
+		function finish() {
+			clearTimeout(timer);
+			socket.off('message', heard);
+			socket.off('error', finish);
+			done(reply);
+		}
+		function heard(buffer) {
+			reply = (reply ?? '') + replyText(buffer);
+			clearTimeout(timer);
+			timer = setTimeout(finish, 150);
+		}
+		timer = setTimeout(finish, wait);
+		socket.on('message', heard);
+		// Windows answers a closed port with an error rather than silence.
+		socket.once('error', finish);
+		socket.send(packet(text), target.port, target.host);
+	});
+}
+
+/**
+ * Runs a command on the server: what it printed, or why it did not run -
+ * `no answer` (the server is not running there) or `bad password`.
+ * @param {RconTarget} target
+ * @param {string} command
+ * @returns {Promise<{ reply: string } | { error: 'no answer' | 'bad password' }>} the reply, or why there is none
+ */
+export async function rcon(target, command, wait = 2000) {
+	const socket = createSocket('udp4');
+	try {
+		const challenge = (await ask(socket, target, 'challenge rcon', 1000))?.match(/challenge rcon (\d+)/)?.[1];
+		if (!challenge) return { error: 'no answer' };
+		const reply = await ask(socket, target, `rcon ${challenge} "${target.password}" ${command}`, wait);
+		if (reply === null) return { error: 'no answer' };
+		if (/^Bad rcon_password/i.test(reply)) return { error: 'bad password' };
+		return { reply };
+	} finally {
+		socket.close();
+	}
+}
+
+/**
+ * What `status` and `stats` say of the server: its map, players and FPS.
+ * @returns {{ map?: string, players?: number, max?: number, fps?: number }} what was found
+ */
+export function serverState(status, stats = '') {
+	const map = /^map\s*:\s*(\S+)/m.exec(status)?.[1];
+	const players = /^players\s*:\s*(\d+) active \((\d+) max\)/m.exec(status);
+	// stats: a row of headings, then a row of numbers under them.
+	const rows = stats.split('\n').map(line => line.trim().split(/\s+/));
+	const at = rows.findIndex(row => row.includes('FPS'));
+	const fps = at >= 0 ? Number(rows[at + 1]?.[rows[at].indexOf('FPS')]) : Number.NaN;
+	return {
+		map,
+		players: players ? Number(players[1]) : undefined,
+		max: players ? Number(players[2]) : undefined,
+		fps: Number.isFinite(fps) ? fps : undefined,
+	};
+}
+
+/**
+ * The plugins `amxts_plugins` lists: `  name  state  about`.
+ * @returns {{ name: string, state: string, about: string }[]} one per plugin
+ */
+export function pluginStates(reply) {
+	return [...reply.matchAll(/^ {2}(\S+)\s+(running|unloaded|refused|waiting|loading)(?: +(\S.*))?$/gm)]
+		.map(([, name, state, about = '']) => ({ name, state, about: about.trim() }));
+}
+
+/** The maps `maps *` lists, without `.bsp`. */
+export function mapNames(reply) {
+	return [...new Set([...reply.matchAll(/^\s*([\w.-]+)\.bsp\b/gim)].map(match => match[1]))].sort();
+}

package/src/server-update.mjs

@@ -7,8 +7,9 @@
 // downloaded and checked, and none of the files it replaces is in use: a
 // running Windows server holds its module, which cannot be written then.
 // The file it replaces stays beside it, with its version
-// (amxts_amxx.dll.0.1.0). AMX Mod X's plugins.ini loses an
-// `amxts_host.amxx` line: the module loads its host plugin itself.
+// (amxts_amxx.dll.0.1.0). What an older release put into AMX Mod X goes: an
+// `amxts_host.amxx` line of its plugins.ini, that plugin and its list -
+// amxts needs no plugin.
 //
 // Also the check `amxts dev` and `build` start with: the release the
 // server's module is of, read from the module file (the core's
@@ -47,6 +48,9 @@ export function writable(path) {
 	}
 }
 
+/** The files of an older release's plugin in AMX Mod X, from the game folder. */
+const LEFTOVERS = ['addons/amxmodx/plugins/amxts_host.amxx', 'addons/amxmodx/configs/plugins-amxts.ini'];
+
 /** AMX Mod X's plugins.ini with its `amxts_host.amxx` lines left out; null when it has none. */
 export function withoutHost(text) {
 	const lines = text.split(/(?<=\n)/);
@@ -134,11 +138,13 @@ export async function updateServer(api, dir, { dryRun = false, canWrite = writab
 	const changing = files.filter(file => !file.same);
 	const pluginsIni = join(game, 'addons', 'amxmodx', 'configs', 'plugins.ini');
 	const cleaned = existsSync(pluginsIni) ? withoutHost(readFileSync(pluginsIni, 'utf8')) : null;
+	const leftovers = LEFTOVERS.map(path => join(game, path)).filter(path => existsSync(path));
+	const tidied = [...(cleaned === null ? [] : [pluginsIni]), ...leftovers].map(slashes).join(', ');
 	const names = changing.map(file => file.path.split(/[\\/]/).pop()).join(', ');
 
 	if (dryRun) {
 		for (const file of changing) log.info(`would put ${file.asset} of ${version} at ${slashes(file.path)}`);
-		if (cleaned !== null) log.info(`would take amxts_host.amxx out of ${slashes(pluginsIni)}`);
+		if (tidied) log.info(`would take an older amxts's plugin out of ${tidied}`);
 		return { ok: true, line: changing.length ? `${names} would go from amxts ${before} to ${version}` : `already amxts ${version}` };
 	}
 
@@ -164,10 +170,9 @@ export async function updateServer(api, dir, { dryRun = false, canWrite = writab
 		writeFileSync(file.path, file.data, { mode: old?.mode ?? 0o755 });
 		log.success(`${file.path.split(/[\\/]/).pop()} ${c.dim(`${before} →`)} ${version}${old ? c.dim(` (the old one: ${file.path.split(/[\\/]/).pop()}.${before})`) : ''}`);
 	}
-	if (cleaned !== null) {
-		writeFileSync(pluginsIni, cleaned);
-		log.success(`Took amxts_host.amxx out of ${slashes(pluginsIni)}: the module loads it itself`);
-	}
-	if (!changing.length) return { ok: true, line: `already amxts ${version}${cleaned !== null ? ', plugins.ini cleaned' : ''}` };
+	if (cleaned !== null) writeFileSync(pluginsIni, cleaned);
+	for (const path of leftovers) rmSync(path, { force: true });
+	if (tidied) log.success(`Took an older amxts's plugin out of ${tidied}: amxts needs no plugin`);
+	if (!changing.length) return { ok: true, line: `already amxts ${version}${tidied ? ', the old plugin taken out' : ''}` };
 	return { ok: true, line: `${names} ${before} → ${version} - restart the server to load it` };
 }

package/src/ui.mjs

@@ -2,6 +2,7 @@
 // per step, and an error as one line with a hint under it. The stack of an
 // error is printed only with --debug (or AMXTS_DEBUG=1).
 import process from 'node:process';
+import { pathToFileURL } from 'node:url';
 
 /** Whether the output takes colors: a terminal, and NO_COLOR not set; FORCE_COLOR wins. */
 function colorful(stream = process.stdout) {
@@ -66,9 +67,139 @@ export function report(error) {
 	if (debug() && error instanceof Error && error.stack) process.stderr.write(`${c.gray(error.stack)}\n`);
 }
 
-/** The line a command starts with: `amxts 0.1.0 · build`. */
-export function banner(version, what) {
-	console.log(`${c.bold(c.cyan('amxts'))} ${c.dim(version)}${what ? c.dim(` · ${what}`) : ''}`);
+/** Whether a run is CI's: `CI` set to anything but `false`. */
+export function isCI(env = process.env) {
+	return Boolean(env.CI) && env.CI !== 'false' && env.CI !== '0';
+}
+
+/**
+ * What characters the output can draw: `box` - any (the panel's spinner and
+ * bar); `bullet` - the logo's `{•}` but not the box characters, for Windows'
+ * own console, whose fonts may miss them; `ascii` - none of them, where the
+ * text is not UTF-8: the logo is `{*}`.
+ */
+export function logoGlyphs(env = process.env, platform = process.platform) {
+	if (platform === 'win32') {
+		const modern = env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuTask || env.TERMINAL_EMULATOR === 'JetBrains-JediTerm' || /^(?:xterm|alacritty)/.test(env.TERM ?? '');
+		return modern ? 'box' : 'bullet';
+	}
+	if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || 'UTF-8')) return 'ascii';
+	return env.TERM === 'linux' ? 'bullet' : 'box';
+}
+
+/**
+ * The logo's colour, amxts yellow (#F2C94C): in 24 bits where the terminal
+ * has them, plain yellow in one of 16 colours, none without a terminal, in CI
+ * or with NO_COLOR - FORCE_COLOR wins, as for every colour here.
+ * @param {{ tty?: boolean, env?: Record<string, string | undefined>, depth?: number }} [where] the output: a terminal, its environment and its colour depth in bits
+ * @returns {(text: string) => string} what paints a text
+ */
+export function logoPaint(where) {
+	return [text => text, text => `\x1B[33m${text}\x1B[39m`, text => `\x1B[38;2;242;201;76m${text}\x1B[39m`][brandDepth(where)];
+}
+
+/** How amxts yellow is drawn (logoPaint): 0 - not at all, 1 - plain yellow, 2 - in 24 bits. */
+function brandDepth({ tty = Boolean(process.stdout.isTTY), env = process.env, depth = process.stdout.getColorDepth?.(env) ?? 4 } = {}) {
+	const forced = env.FORCE_COLOR && env.FORCE_COLOR !== '0';
+	if (!forced && (!tty || isCI(env) || env.NO_COLOR !== undefined || env.TERM === 'dumb')) return 0;
+	return depth >= 24 || env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit' ? 2 : 1;
+}
+
+// The 16 colours as amxts draws them in 24 bits: green, red, yellow (amxts
+// yellow), blue, magenta, cyan - lit, where a terminal's own may be pale.
+const VIVID = { 31: '248;113;113', 32: '74;222;128', 33: '242;201;76', 34: '96;165;250', 35: '232;121;249', 36: '34;211;238' };
+
+/** A line with its 16 colours drawn vivid, where the terminal has 24 bits; as it is elsewhere. */
+export function vivid(line, where) {
+	if (brandDepth(where) !== 2) return line;
+	// eslint-disable-next-line no-control-regex
+	return line.replace(/\x1B\[(3[1-6])m/g, (_, code) => `\x1B[38;2;${VIVID[code]}m`);
+}
+
+/**
+ * A text the terminal makes a link of (OSC 8), where colours are on; the text
+ * alone elsewhere.
+ */
+export function link(text, url, where) {
+	return brandDepth(where) ? `\x1B]8;;${url}\x1B\\${text}\x1B]8;;\x1B\\` : text;
+}
+
+/**
+ * The link that opens a file at a line and column in the editor: Orca's own
+ * in Orca's terminal, else VS Code's, or Cursor's where the terminal or EDITOR
+ * is Cursor's. A `file://` link elsewhere would open a `.ts` in whatever the
+ * system opens it with - a video player, on some.
+ */
+export function editorLink(file, line, col, env = process.env) {
+	// Orca opens a file:// link in its own editor, the line and column after it.
+	if (env.TERM_PROGRAM === 'Orca') return `${pathToFileURL(file).href}:${line}:${col}`;
+	const scheme = /cursor/i.test(`${env.TERM_PROGRAM ?? ''} ${env.EDITOR ?? ''} ${env.VISUAL ?? ''}`) ? 'cursor' : 'vscode';
+	// `vscode://file/D:/x.ts:3:26`, `vscode://file/home/me/x.ts:3:26`: the path absolute.
+	const path = file.replace(/\\/g, '/');
+	return `${scheme}://file${path.startsWith('/') ? '' : '/'}${encodeURI(path)}:${line}:${col}`;
+}
+
+/**
+ * A state as a word on a ground of its colour - ` READY ` on amxts yellow,
+ * ` BUILDING ` on cyan, ` ERROR ` on red; `[READY]` without colours.
+ * @param {string} text
+ * @param {'ready' | 'busy' | 'error'} tone
+ */
+export function badge(text, tone, where) {
+	const depth = brandDepth(where);
+	if (!depth) return `[${text}]`;
+	const ground = {
+		ready: depth === 2 ? '48;2;242;201;76;38;2;21;24;29' : '43;30',
+		busy: depth === 2 ? '48;2;34;211;238;38;2;21;24;29' : '46;30',
+		error: depth === 2 ? '48;2;239;68;68;97' : '41;97',
+	}[tone];
+	return `\x1B[1;${ground}m ${text} \x1B[0m`;
+}
+
+// The logo in a line: the braces and the dot.
+const MARK = { box: '{•}', bullet: '{•}', ascii: '{*}' };
+
+// The logo - the crosshair: its arms, the braces and the dot - in braille
+// dots, four lines of them, the logo's SVG rasterised to 16 by 16.
+export const LOGO = ['⠀⢀⡀⢸⡇⢀⡀⠀', '⣀⡿⠁⣀⣀⠈⢿⣀', '⠉⣷⡀⠉⠉⢀⣾⠉', '⠀⠈⠁⢸⡇⠈⠁⠀'];
+
+/**
+ * The logo's four lines, painted. `wave`: a light that runs across it - its
+ * place, in columns - while something runs, in 24 bits; the plain colour
+ * without it. Where the font may have no braille, the mark in a line instead
+ * (`{•}` on the second).
+ * @param {number | null} [wave]
+ * @param {{ glyphs?: string, where?: object }} [options] how the output draws (logoGlyphs, and the output as logoPaint takes it)
+ * @returns {string[]} four lines, each as wide
+ */
+export function logoLines(wave = null, { glyphs = logoGlyphs(), where } = {}) {
+	if (glyphs !== 'box') return ['   ', logoPaint(where)(MARK[glyphs]), '   ', '   '];
+	const depth = brandDepth(where);
+	if (depth < 2 || wave === null) return LOGO.map(line => logoPaint(where)(line));
+	// From a darker gold to a pale one, amxts yellow between.
+	// One spot of light, gone a few columns away from its place.
+	const shade = column => Math.exp(-((column - wave) ** 2) / 4);
+	const mix = light => [[150, 110, 30], [255, 236, 150]].reduce((low, high) => low.map((each, index) => Math.round(each + (high[index] - each) * light)));
+	return LOGO.map(line => `${[...line].map((dot, column) => `\x1B[38;2;${mix(shade(column)).join(';')}m${dot}`).join('')}\x1B[39m`);
+}
+
+/**
+ * The line a command starts with: the logo, `{•} amxts 0.2.4 · build`. With
+ * `logo` (dev, a new project) the logo in its four lines, the words beside the
+ * second.
+ * @param {string} version
+ * @param {string} [what]
+ * @param {{ logo?: boolean, glyphs?: string, where?: object }} [options] how the output draws (logoGlyphs, and the output as logoPaint takes it)
+ */
+export function bannerText(version, what, { logo = false, glyphs = logoGlyphs(), where } = {}) {
+	const words = `${c.bold('amxts')} ${c.dim(version)}${what ? c.dim(` · ${what}`) : ''}`;
+	if (!logo || glyphs !== 'box') return `${logoPaint(where)(MARK[glyphs] ?? MARK.bullet)} ${words}`;
+	return logoLines(null, { glyphs, where }).map((line, index) => (index === 1 ? `${line}   ${words}` : line)).join('\n');
+}
+
+/** Prints the line a command starts with (bannerText). */
+export function banner(version, what, options) {
+	console.log(bannerText(version, what, options));
 }
 
 /** The closest of `known` to `given`, when it is close enough to be a typo. */