@amxts/cli 0.2.0 → 0.3.0

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. */

package/src/update-check.mjs

@@ -0,0 +1,64 @@
+// The line that says a newer amxts is out: `amxts 0.2.5 is out: npx amxts
+// upgrade`. Read from a file the last check wrote, so it costs a command
+// nothing; once a day a check runs in a process of its own, left behind, and
+// writes it again. Only in a terminal, not in CI; AMXTS_IGNORE_UPDATE_CHECK=1
+// turns it off.
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { compareVersions } from './core.mjs';
+import { execAmxts } from './pm.mjs';
+import { isCI } from './ui.mjs';
+
+/** Where the last check is kept: `{ checked, latest }`. */
+export const UPDATE_FILE = join(homedir(), '.cache', 'amxts', 'update.json');
+const DAY = 24 * 60 * 60 * 1000;
+
+function save(file, data) {
+	try {
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(data)}\n`);
+	} catch {}
+}
+
+/**
+ * The line about a newer core than the project's, or null; starts the day's
+ * check when the last one is older.
+ * @param {string} version the project's core
+ * @param {string} pm its package manager, for the words
+ * @param {{ env?: Record<string, string | undefined>, tty?: boolean, now?: number, file?: string, check?: (file: string) => void }} [options]
+ */
+export function updateLine(version, pm, { env = process.env, tty = Boolean(process.stdout.isTTY), now = Date.now(), file = UPDATE_FILE, check = startCheck } = {}) {
+	if (env.AMXTS_IGNORE_UPDATE_CHECK === '1' || !tty || isCI(env)) return null;
+	let last = {};
+	try {
+		last = JSON.parse(readFileSync(file, 'utf8'));
+	} catch {}
+	if (!(now - (last.checked ?? 0) < DAY)) {
+		// Written first: a second command in the same minute does not check again.
+		save(file, { ...last, checked: now });
+		check(file);
+	}
+	return last.latest && compareVersions(last.latest, version) > 0 ? `amxts ${last.latest} is out: ${execAmxts(pm)} upgrade` : null;
+}
+
+/** Starts the check in a process of its own, which the command does not wait for. */
+function startCheck(file) {
+	try {
+		spawn(process.execPath, [fileURLToPath(import.meta.url), file], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+	} catch {}
+}
+
+// The check itself: the latest @amxts/core on the registry npm is set to.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const file = process.argv[2];
+	const registry = (process.env.npm_config_registry || 'https://registry.npmjs.org/').replace(/\/?$/, '/');
+	try {
+		const response = await fetch(`${registry}@amxts/core/latest`, { signal: AbortSignal.timeout(10_000) });
+		const { version } = await response.json();
+		if (typeof version === 'string') save(file, { checked: Date.now(), latest: version });
+	} catch {}
+}

package/src/upgrade.mjs

@@ -240,6 +240,8 @@ export async function upgrade({ to, server = true, serverOnly = false, dryRun =
 			: { ok: true, line: `the module of amxts ${version} goes in once @amxts/core ${version} is installed` };
 	}
 	console.log(['', ...summary(outcome)].join('\n'));
+	// A script that upgrades and goes on hears that the build failed.
+	if (outcome.build === 'failed') process.exitCode = 1;
 	return outcome;
 }
 

package/templates/module/_oxlintrc.json

@@ -18,41 +18,20 @@
 		"**/node_modules/",
 		"**/*.tgz",
 		"**/bun.lock",
+		"**/bun.lockb",
 		"**/package-lock.json",
 		"**/pnpm-lock.yaml",
 		"**/yarn.lock",
+		"**/.yarn",
 		"**/.amxts/",
 		"**/dist/",
-		"**/node_modules",
-		"**/dist",
-		"**/bun.lockb",
-		"**/output",
 		"**/coverage",
-		"**/temp",
-		"**/.temp",
-		"**/tmp",
-		"**/.tmp",
-		"**/.history",
-		"**/.vitepress/cache",
-		"**/.nuxt",
-		"**/.next",
-		"**/.svelte-kit",
-		"**/.vercel",
-		"**/.changeset",
-		"**/.idea",
 		"**/.cache",
-		"**/.output",
-		"**/.vite-inspect",
-		"**/.yarn",
+		"**/__snapshots__",
 		"**/CHANGELOG*.md",
 		"**/LICENSE*",
-		"**/*.min.*",
-		"**/__snapshots__",
-		"**/vite.config.*.timestamp-*",
-		"**/auto-import.d.ts",
-		"**/auto-imports.d.ts",
-		"**/components.d.ts",
-		"**/.context",
+		"**/.history",
+		"**/.idea",
 		"**/.claude",
 		"**/.agents",
 		"**/.*/skills"

package/templates/module/src/index.ts

@@ -21,5 +21,5 @@ let greeting = "";
 
 /** Greets the player in chat. */
 export function greet(player: Player) {
-	print(player, `${greeting}, ${player.name}!`);
+	player.print(`${greeting}, ${player.name}!`);
 }

package/templates/module/test/tsconfig.json

@@ -4,7 +4,7 @@
 		"lib": ["ES2022"],
 		"module": "ESNext",
 		"moduleResolution": "bundler",
-		"types": ["bun"],
+		"types": ["{{test.types}}"],
 		"strict": true,
 		"noEmit": true,
 		"skipLibCheck": true

package/templates/module/test/{{name}}.test.ts

@@ -1,4 +1,9 @@
+// #if bun
 import { describe, expect, test } from "bun:test";
+// #endif
+// #if !bun
+import { describe, expect, test } from "vitest";
+// #endif
 import { setup } from "@amxts/core/test-utils";
 
 // The first test compiles the plugins; the next runs take them from the cache.

package/templates/project/_oxlintrc.json

@@ -18,41 +18,20 @@
 		"**/node_modules/",
 		"**/*.tgz",
 		"**/bun.lock",
+		"**/bun.lockb",
 		"**/package-lock.json",
 		"**/pnpm-lock.yaml",
 		"**/yarn.lock",
+		"**/.yarn",
 		"**/.amxts/",
 		"**/dist/",
-		"**/node_modules",
-		"**/dist",
-		"**/bun.lockb",
-		"**/output",
 		"**/coverage",
-		"**/temp",
-		"**/.temp",
-		"**/tmp",
-		"**/.tmp",
-		"**/.history",
-		"**/.vitepress/cache",
-		"**/.nuxt",
-		"**/.next",
-		"**/.svelte-kit",
-		"**/.vercel",
-		"**/.changeset",
-		"**/.idea",
 		"**/.cache",
-		"**/.output",
-		"**/.vite-inspect",
-		"**/.yarn",
+		"**/__snapshots__",
 		"**/CHANGELOG*.md",
 		"**/LICENSE*",
-		"**/*.min.*",
-		"**/__snapshots__",
-		"**/vite.config.*.timestamp-*",
-		"**/auto-import.d.ts",
-		"**/auto-imports.d.ts",
-		"**/components.d.ts",
-		"**/.context",
+		"**/.history",
+		"**/.idea",
 		"**/.claude",
 		"**/.agents",
 		"**/.*/skills"

package/templates/project/plugins/hello.ts

@@ -14,12 +14,17 @@ const greeting = "Welcome";
 // #endif
 
 server.addCommand("/hp", ({ player }) => sayHp(player));
-server.addEventListener("putInServer", event => print(0, `${greeting}, ${event.player.name}!`));
+server.addEventListener("putInServer", event => event.player.print(`${greeting}, ${event.player.name}!`));
 // #if menu-core
 
 // A menu made in code: its title and items can be functions of the player it is shown to.
 const hello = menus.create("HELLO", { title: ({ player }) => `Hello, ${player.name}` });
-hello.addItem({ title: "Wave", onSelect: ({ player }) => print(0, `${player.name} waves`) });
+hello.addItem({
+	title: "Wave",
+	onSelect: ({ player }) => {
+		server.print(`${player.name} waves`);
+	},
+});
 hello.addItem({
 	title: ({ player }) => `Heal (${player.health} HP)`,
 	visible: ({ player }) => player.health < 100,
@@ -34,7 +39,12 @@ server.addCommand("/menu", ({ player }) => hello.show(player));
 
 // A menu: its title and items can be functions of the player it is shown to.
 const hello = new Menu(({ player }) => `Hello, ${player.name}`);
-hello.addItem({ title: "Wave", onSelect: ({ player }) => print(0, `${player.name} waves`) });
+hello.addItem({
+	title: "Wave",
+	onSelect: ({ player }) => {
+		server.print(`${player.name} waves`);
+	},
+});
 hello.addItem({
 	title: ({ player }) => `Heal (${player.health} HP)`,
 	visible: ({ player }) => player.health < 100,
@@ -47,5 +57,5 @@ server.addCommand("/menu", ({ player }) => hello.show(player));
 // #endif
 
 function sayHp(player: Player) {
-	print(player, `${player.name}, your HP: ${player.health}`);
+	player.print(`${player.name}, your HP: ${player.health}`);
 }

package/templates/project/test/hello.test.ts

@@ -1,11 +1,21 @@
+// #if bun
 import { expect, setDefaultTimeout, test } from "bun:test";
+// #endif
+// #if !bun
+import { expect, test, vi } from "vitest";
+// #endif
 import { setup } from "@amxts/core/test-utils";
 // #if menu-core
 import { menusOf } from "@amxts/menu-core/testing";
 // #endif
 
 // The first run compiles the plugins; the next ones take them from the cache.
+// #if bun
 setDefaultTimeout(120_000);
+// #endif
+// #if !bun
+vi.setConfig({ testTimeout: 120_000 });
+// #endif
 
 test("a player who joins is greeted", async () => {
 	const server = await setup();
@@ -34,4 +44,15 @@ test("/menu heals a hurt player", async () => {
 	menus.press(alice, 2);
 	expect(alice.health).toBe(100);
 });
+
+test("Wave in /menu tells everyone", async () => {
+	const server = await setup();
+	const menus = menusOf(server);
+	const alice = server.join("Alice");
+	const bob = server.join("Bob");
+
+	alice.say("/menu");
+	menus.press(alice, 1);
+	expect(bob.chat).toContain("Alice waves");
+});
 // #endif

package/templates/project/test/tsconfig.json

@@ -4,7 +4,7 @@
 		"lib": ["ES2022"],
 		"module": "ESNext",
 		"moduleResolution": "bundler",
-		"types": ["bun"],
+		"types": ["{{test.types}}"],
 		"strict": true,
 		"noEmit": true,
 		"skipLibCheck": true