@amxts/cli 0.1.0 → 0.2.1

package/src/server-update.mjs

@@ -0,0 +1,173 @@
+// The server step of `amxts upgrade`: the server in AMXTS_SERVER gets the
+// module of the project's core - and the compiler for `.ts` written on the
+// server, where it has one - from that version's GitHub Release.
+//
+// The release's manifest (amxts-<system>.json) names each file with its
+// sha256. Nothing on the server changes until every file it needs is
+// 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.
+//
+// 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
+// moduleVersion()), against the project's core.
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { setting } from './core.mjs';
+import { serverFolderOrNull } from './server.mjs';
+import { c, CliError, log } from './ui.mjs';
+
+/** A path as the messages write it. */
+const slashes = path => path.replace(/\\/g, '/');
+
+const sha256 = data => createHash('sha256').update(data).digest('hex');
+
+/** A file of a release: a URL's, or a folder's (AMXTS_RELEASE_URL may name one). */
+export async function releaseFile(base, name) {
+	if (!/^https?:\/\//.test(base)) return readFileSync(join(base, name));
+	const url = new URL(name, base.endsWith('/') ? base : `${base}/`);
+	const response = await fetch(url);
+	if (!response.ok) throw new CliError(`${url} answered ${response.status}`, 'The release may not be published yet, or the network is down.');
+	return Buffer.from(await response.arrayBuffer());
+}
+
+/** Whether a file can be written: false while a process holds it - a module a running server loaded. */
+export function writable(path) {
+	try {
+		closeSync(openSync(path, 'r+'));
+		return true;
+	} catch (error) {
+		// EBUSY: a module Windows has loaded; ETXTBSY: a tool Linux is running.
+		if (['EBUSY', 'ETXTBSY', 'EPERM', 'EACCES'].includes(error.code)) return false;
+		throw error;
+	}
+}
+
+/** 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)/);
+	const kept = lines.filter(line => !/^\s*amxts_host\.amxx\b/i.test(line));
+	return kept.length === lines.length ? null : kept.join('');
+}
+
+/** The settings the core's serverSystem() reads, as the build sees them: the environment, else .env. */
+function serverEnv(dir) {
+	return { AMXTS_SERVER: setting(dir, 'AMXTS_SERVER'), AMXTS_SERVER_OS: setting(dir, 'AMXTS_SERVER_OS') };
+}
+
+/**
+ * The server's game folder and the files of `api`'s release for its system, or null when .env names no server that is there.
+ * @param {typeof import('@amxts/core/cli-api')} api
+ * @param {string} dir the project
+ * @param {string[]} [argv] --os, when the command was given one
+ */
+function serverOf(api, dir, argv = []) {
+	const amxts = serverFolderOrNull(setting(dir, 'AMXTS_SERVER'));
+	if (!amxts || !existsSync(amxts)) return null;
+	const { system } = api.serverSystem(argv, serverEnv(dir));
+	return { amxts, game: resolve(amxts, '..', '..'), system, release: api.release(system) };
+}
+
+/**
+ * The line `amxts dev` and `build` start with when the server's module is of
+ * another release than the project's core; null when it is the same, or
+ * there is no module to read.
+ * @param {import('./core.mjs').Core} core
+ * @param {string} dir the project
+ * @param {string[]} [argv] --os, when the command was given one
+ */
+export function serverMismatch(core, dir, argv = []) {
+	const server = serverOf(core.api, dir, argv);
+	const running = server && core.api.moduleVersion(join(server.game, server.release.files[0].path));
+	return running && running !== core.version ? `the server runs amxts ${running}, this project ${core.version} - run amxts upgrade` : null;
+}
+
+/**
+ * @typedef {object} ServerOutcome
+ * @property {boolean} ok whether the server is as it should be, or nothing was asked of it
+ * @property {string} line what happened, for the summary
+ */
+
+/**
+ * The server step.
+ * @param {typeof import('@amxts/core/cli-api')} api the project's core, of the version the server moves to
+ * @param {string} dir the project
+ * @param {{ dryRun?: boolean, canWrite?: typeof writable }} [options] `canWrite`: what the tests replace
+ * @returns {Promise<ServerOutcome>} what happened
+ */
+export async function updateServer(api, dir, { dryRun = false, canWrite = writable } = {}) {
+	const named = setting(dir, 'AMXTS_SERVER');
+	const version = api.version;
+	if (!named) {
+		const image = api.release('linux').image;
+		log.step('Server: no AMXTS_SERVER in .env');
+		return { ok: true, line: `none in .env; a server in Docker: docker pull ${image}` };
+	}
+	const server = serverOf(api, dir);
+	if (!server) {
+		log.step(`Server: ${slashes(named)} is not there`);
+		return { ok: false, line: `${slashes(named)} is not there: nothing was updated` };
+	}
+	const { game, system, release } = server;
+	const [module] = release.files;
+	const modulePath = join(game, module.path);
+	log.step(`Server: ${slashes(game)} ${c.dim(`(${system})`)}`);
+	if (!existsSync(modulePath)) {
+		return { ok: false, line: `there is no ${module.asset} in ${slashes(dirname(modulePath))}: install the server kit of amxts ${version}` };
+	}
+
+	const before = api.moduleVersion(modulePath) ?? 'old';
+	const manifest = JSON.parse((await releaseFile(release.url, release.manifest)).toString('utf8'));
+	if (manifest.version !== version) throw new CliError(`${release.manifest} is of amxts ${manifest.version}, not ${version}`, `It was read from ${release.url}.`);
+	const files = release.files
+		.filter(file => !file.tool || existsSync(join(game, file.path)))
+		.map((file) => {
+			const entry = manifest.files.find(one => one.name === file.asset);
+			if (!entry) throw new CliError(`${release.manifest} lists no ${file.asset}`, `It was read from ${release.url}.`);
+			const path = join(game, file.path);
+			return { ...file, path, sha256: entry.sha256, same: existsSync(path) && sha256(readFileSync(path)) === entry.sha256 };
+		});
+	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 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)}`);
+		return { ok: true, line: changing.length ? `${names} would go from amxts ${before} to ${version}` : `already amxts ${version}` };
+	}
+
+	const busy = changing.filter(file => existsSync(file.path) && !canWrite(file.path));
+	if (busy.length) {
+		log.warn(`${busy.map(file => slashes(file.path)).join(', ')} is in use: the server is running`);
+		log.hint(`Stop the server, then run: amxts upgrade --server-only`);
+		return { ok: false, line: `in use - stop the server and run amxts upgrade --server-only; nothing on it was changed` };
+	}
+
+	// Every file downloaded and checked before the first is replaced.
+	const downloads = await Promise.all(changing.map(async (file) => {
+		const data = await releaseFile(release.url, file.asset);
+		if (sha256(data) !== file.sha256) throw new CliError(`${file.asset} from ${release.url} is not the one ${release.manifest} lists (sha256)`, 'Nothing on the server was changed. Run it again; if it says the same, the download is broken.');
+		return { ...file, data };
+	}));
+	for (const file of downloads) {
+		const old = existsSync(file.path) ? statSync(file.path) : null;
+		if (old) {
+			rmSync(`${file.path}.${before}`, { force: true });
+			renameSync(file.path, `${file.path}.${before}`);
+		}
+		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' : ''}` };
+	return { ok: true, line: `${names} ${before} → ${version} - restart the server to load it` };
+}

package/src/server.mjs

@@ -3,12 +3,48 @@
 // ask the same when it is not set - in a terminal. Elsewhere (CI, a pipe)
 // nothing is asked, and the build says it is missing.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
 import * as p from '@clack/prompts';
 import { setting } from './core.mjs';
 import { runScript } from './pm.mjs';
-import { c } from './ui.mjs';
+import { c, CliError } from './ui.mjs';
+
+// The folders a server path may name above its addons/amxts, by what is below
+// them: hlds's own (cstrike/addons), the game's (addons).
+const ABOVE_ADDONS = [join('cstrike', 'addons'), 'addons'];
+
+/** A path as .env and the messages write it: with forward slashes. */
+const slashes = path => path.replace(/\\/g, '/');
+
+/**
+ * The server's addons/amxts folder from a path a person gave: that folder
+ * itself, or the hlds folder, cstrike or cstrike/addons above it - as the
+ * core's build reads AMXTS_SERVER. A path that is not there yet is taken as
+ * it is, and so is a folder named amxts or holding the module's plugins.ini.
+ * @param {string} path
+ * @returns {string} the folder; '' for ''
+ * @throws {CliError} for a folder that is there and none of them, naming where it looked
+ */
+export function serverFolder(path) {
+	if (!path) return '';
+	const dir = resolve(path);
+	if (!existsSync(dir) || basename(dir).toLowerCase() === 'amxts' || existsSync(join(dir, 'plugins.ini'))) return path;
+	if (basename(dir).toLowerCase() === 'addons') return join(dir, 'amxts');
+	const addons = ABOVE_ADDONS.map(below => join(dir, below)).find(folder => existsSync(folder));
+	if (addons) return join(addons, 'amxts');
+	const looked = [...ABOVE_ADDONS, 'plugins.ini'].map(below => slashes(join(dir, below)));
+	throw new CliError(`${slashes(path)} is not a server: there is no ${looked.join(', ')}`, 'Give the server\'s folder (where hlds is), its cstrike, or cstrike/addons/amxts.');
+}
+
+/** The server's addons/amxts from a path, or null when the path is no server: for what only reads it. */
+export function serverFolderOrNull(path) {
+	try {
+		return serverFolder(path);
+	} catch {
+		return null;
+	}
+}
 
 /** Whether a command may ask: a terminal, and not CI. */
 export function canAsk() {
@@ -16,18 +52,28 @@ export function canAsk() {
 }
 
 /**
- * Asks for the server's addons/amxts folder. `required`: an empty answer is
- * not taken. The answer, or clack's cancel symbol on Ctrl+C.
+ * Asks for the server: its folder, its cstrike or its addons/amxts.
+ * `required`: an empty answer is not taken. The server's addons/amxts
+ * (serverFolder), '' for none, or clack's cancel symbol on Ctrl+C.
  * @param {string} pm the project's package manager, for the words
  * @param {{ required?: boolean }} [options]
  */
-export function askServer(pm, { required = false } = {}) {
-	return p.text({
-		message: `Where is the server? ${c.dim(`its addons/amxts folder, for ${runScript(pm, 'dev')}${required ? '' : ' - empty to skip'}`)}`,
-		placeholder: process.platform === 'win32' ? 'D:/hlds/cstrike/addons/amxts' : '/srv/hlds/cstrike/addons/amxts',
+export async function askServer(pm, { required = false } = {}) {
+	const answer = await p.text({
+		message: `Where is the server? ${c.dim(`its folder or its addons/amxts, for ${runScript(pm, 'dev')}${required ? '' : ' - empty to skip'}`)}`,
+		placeholder: process.platform === 'win32' ? 'D:/hlds' : '/srv/hlds',
 		defaultValue: '',
-		validate: value => (required && !value?.trim() ? 'The plugins are deployed there: the server\'s addons/amxts folder' : undefined),
+		validate: (value) => {
+			if (!value?.trim()) return required ? 'The plugins are deployed there: the server\'s folder' : undefined;
+			try {
+				serverFolder(value.trim());
+				return undefined;
+			} catch (error) {
+				return `${error.message}. ${error.hint}`;
+			}
+		},
 	});
+	return p.isCancel(answer) ? answer : serverFolder(answer.trim());
 }
 
 /** The warning for a server folder that is not there. */
@@ -67,6 +113,6 @@ export async function ensureServer(root, pm) {
 	}
 	saveServer(root, server);
 	process.env.AMXTS_SERVER = server;
-	p.log.success(`Wrote AMXTS_SERVER=${server.replace(/\\/g, '/')} to .env`);
+	p.log.success(`Wrote AMXTS_SERVER=${slashes(server)} to .env`);
 	if (!existsSync(server)) p.log.warn(missingServer(server));
 }

package/src/upgrade.mjs

@@ -0,0 +1,266 @@
+// `amxts upgrade`: a project moved to another amxts release in one command.
+//
+//   amxts upgrade [--to <version>] [--no-server] [--server-only] [--dry-run]
+//
+// 1. The packages: the core to the latest version on the registry npm is set
+//    to, or to --to; every other @amxts/ package in package.json - the
+//    official modules, the command - to its own newest version that works
+//    with that core (registry.mjs), in the style the project writes its
+//    ranges (`^0.1.0` → `^0.2.0`); then the project's own package manager
+//    installs.
+// 2. The code: the new core's rewrites (its `upgrade` task), each change listed.
+// 3. The build: `amxts build`.
+// 4. The server in AMXTS_SERVER: its module, and its compiler where it has
+//    one, from the release of the new version (server-update.mjs).
+// 5. A summary: the versions, the files rewritten, what to check by hand and
+//    the server's result.
+//
+// A command of one release drives cores of that release only, so once the
+// packages are installed a command of another version hands the rest to the
+// project's new one: `amxts upgrade --to <version>` again, with the versions
+// it started from in AMXTS_UPGRADE_FROM.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { coreDirFrom, loadCore, needProject, readJson, runTask, satisfies, VERSION } from './core.mjs';
+import { prepare } from './includes.mjs';
+import { commandLine, detectPackageManager, installArgs, installLinked, linkedFolders } from './pm.mjs';
+import { CORE, npmRegistry, versionsFor } from './registry.mjs';
+import { updateServer } from './server-update.mjs';
+import { banner, c, CliError, log } from './ui.mjs';
+
+const VERSION_TEXT = /^v?(\d+\.\d+\.\d+(?:-[\d.a-z-]+)?)$/i;
+
+/** A spec upgrade moves: a version, with `^`, `~`, `=` or `>=` before it. */
+const MOVABLE = /^([~^]|>?=)?\d+\.\d+\.\d+(?:-[\d.a-z-]+)?$/i;
+
+/**
+ * A spec at another version, in the style it was written: `^0.1.0` →
+ * `^0.2.0`, `~0.1.0` → `~0.2.0`, `0.1.0` → `0.2.0`. Null for a spec upgrade
+ * leaves as it is: a folder (`file:`, `link:`), a tag, a range of its own.
+ * @param {string} spec
+ * @param {string} version
+ */
+export function bumpSpec(spec, version) {
+	const match = MOVABLE.exec(spec.trim());
+	return match ? `${match[1] ?? ''}${version}` : null;
+}
+
+/**
+ * @typedef {object} Bump
+ * @property {string} name the package
+ * @property {string} spec as package.json has it
+ * @property {string | null} version the version it goes to; null when it is left as it is
+ * @property {string | null} to the spec at that version; null when it is left as it is
+ */
+
+/** The @amxts/ packages of a project's package.json, with their specs. */
+function amxtsPackages(pkg) {
+	return Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([name]) => name.startsWith('@amxts/')).map(([name, spec]) => ({ name, spec: String(spec) }));
+}
+
+/**
+ * The @amxts/ packages of a project's package.json, and their specs at the versions they go to.
+ * @param {Record<string, any>} pkg
+ * @param {Record<string, string | null>} versions each package's new version, by name
+ * @returns {Bump[]} the packages
+ */
+export function packageBumps(pkg, versions) {
+	return amxtsPackages(pkg).map(({ name, spec }) => {
+		const to = versions[name] ? bumpSpec(spec, versions[name]) : null;
+		return { name, spec, version: to && versions[name], to };
+	});
+}
+
+/** package.json's text with the specs moved, everything else as it was written. */
+export function writeBumps(text, bumps) {
+	return bumps.filter(bump => bump.to && bump.to !== bump.spec).reduce((out, bump) => {
+		const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		return out.replace(new RegExp(`("${escape(bump.name)}"\\s*:\\s*")${escape(bump.spec)}"`, 'g'), `$1${bump.to}"`);
+	}, text);
+}
+
+/** The version of a package the project has installed, or null. */
+function installedVersion(dir, name) {
+	return readJson(join(dir, 'node_modules', name, 'package.json'))?.version ?? null;
+}
+
+/** Runs the project's install, quietly, with a line before and after; its output when it fails. */
+async function installProject(dir, pm) {
+	const argv = installArgs(pm);
+	log.step(`Installing with ${pm}`);
+	const result = await installLinked(argv, linkedFolders(dir), { cwd: dir, quiet: true });
+	if (result.code !== 0) {
+		throw new CliError(`${commandLine(argv)} failed`, result.output.trim().split('\n').slice(-15).join('\n'));
+	}
+	log.success(`Installed with ${pm}`);
+}
+
+/** The command a project's core runs - `npx amxts` - by its folder, or null. */
+function projectCommand(coreDir) {
+	try {
+		return join(createRequire(join(coreDir, 'package.json')).resolve('@amxts/cli/package.json'), '..');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The code step: the core's rewrites, listed as they are made; with
+ * `dryRun`, listed only. What they changed and left, from the task's report.
+ */
+function rewriteCode(core, dryRun) {
+	const dir = mkdtempSync(join(tmpdir(), 'amxts-upgrade-'));
+	try {
+		const report = join(dir, 'report.json');
+		if (runTask(core, 'upgrade', ['--report', report, ...(dryRun ? ['--dry-run'] : [])]) !== 0) {
+			throw new CliError('The code was not upgraded', 'The error is above.');
+		}
+		return JSON.parse(readFileSync(report, 'utf8'));
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * @typedef {object} Outcome
+ * @property {string} version the release the project moves to: the core's version
+ * @property {{ name: string, from: string | null, version: string | null, to: string | null, spec: string }[]} packages each @amxts/ package, and the version and spec it goes to; null when left as it is
+ * @property {{ files: string[], left: { file: string, line: number, why: string }[] } | null} code what the rewrites changed and left; null when they did not run
+ * @property {'built' | 'failed' | null} build how the build went; null when it did not run
+ * @property {import('./server-update.mjs').ServerOutcome | null} server the server step's result; null with --no-server
+ * @property {boolean} dryRun whether nothing was changed
+ */
+
+/**
+ * What `amxts upgrade` prints last.
+ * @param {Outcome} outcome
+ * @returns {string[]} the lines
+ */
+export function summary(outcome) {
+	const lines = [];
+	const would = outcome.dryRun ? 'would be ' : '';
+	const moved = outcome.packages.filter(each => each.to);
+	const width = Math.max(0, ...moved.map(each => each.name.length));
+	lines.push(c.bold(outcome.dryRun ? `Dry run: amxts ${outcome.version}, nothing was changed` : `Upgraded to amxts ${outcome.version}`));
+	for (const each of moved) lines.push(`  ${each.name.padEnd(width)}  ${each.from === each.version ? `${each.version} ${c.dim('(already)')}` : `${each.from ?? each.spec} ${c.dim('→')} ${each.version}`}`);
+	for (const each of outcome.packages.filter(one => !one.to)) lines.push(`  ${each.name.padEnd(width)}  ${each.spec} ${c.dim('(left as it is)')}`);
+	if (outcome.code) {
+		lines.push(outcome.code.files.length ? `  ${c.green('✔')} ${would}rewritten: ${outcome.code.files.join(', ')}` : `  ${c.green('✔')} the code already uses this API`);
+		if (outcome.code.left.length) {
+			lines.push(`  ${c.yellow('▲')} to check by hand:`);
+			for (const each of outcome.code.left) lines.push(`      ${c.dim(`${each.file}:${each.line}`)}  ${each.why}`);
+		}
+	}
+	if (outcome.build) lines.push(outcome.build === 'built' ? `  ${c.green('✔')} built` : `  ${c.red('✖')} the build failed: see above`);
+	if (outcome.server) lines.push(`  ${outcome.server.ok ? c.green('✔') : c.yellow('▲')} server: ${outcome.server.line}`);
+	return lines;
+}
+
+/**
+ * `amxts upgrade`.
+ * @param {{ to?: string, server?: boolean, serverOnly?: boolean, dryRun?: boolean }} options
+ * @param {{ dir?: string, registry?: import('./registry.mjs').Registry, install?: typeof installProject }} [deps] what the tests replace
+ * @returns {Promise<Outcome | null>} what was done; null when it was handed to the project's command
+ */
+export async function upgrade({ to, server = true, serverOnly = false, dryRun = false }, { dir = needProject(), registry = npmRegistry(dir), install = installProject } = {}) {
+	const handedFrom = process.env.AMXTS_UPGRADE_FROM ? JSON.parse(process.env.AMXTS_UPGRADE_FROM) : null;
+	if (!handedFrom) banner(VERSION, dryRun ? 'upgrade --dry-run' : 'upgrade');
+	if (to !== undefined && !VERSION_TEXT.test(to)) throw new CliError(`--to ${to}: a version, such as 0.2.0`);
+
+	if (serverOnly) {
+		const core = await loadCore(coreDirFrom(dir) ?? needCore());
+		/** @type {Outcome} */
+		const outcome = { version: core.version, packages: [], code: null, build: null, server: await updateServer(core.api, dir, { dryRun }), dryRun };
+		console.log(['', ...summary(outcome)].join('\n'));
+		return outcome;
+	}
+
+	const pkg = readJson(join(dir, 'package.json')) ?? {};
+	const { version, versions } = handedFrom ? installed(dir, pkg, VERSION_TEXT.exec(to)[1]) : await newest(registry, dir, pkg, to ? VERSION_TEXT.exec(to)[1] : 'latest');
+	const bumps = packageBumps(pkg, versions);
+	const from = handedFrom ?? Object.fromEntries(bumps.map(bump => [bump.name, installedVersion(dir, bump.name)]));
+	const moving = bumps.filter(bump => bump.to && (bump.to !== bump.spec || from[bump.name] !== bump.version));
+
+	if (!handedFrom) {
+		log.step(`Packages: amxts ${version}${to ? '' : c.dim(' (latest)')}`);
+		for (const bump of bumps) log.info(`${bump.name}  ${bump.spec} ${!bump.to ? c.dim('(left as it is)') : moving.includes(bump) ? `${c.dim('→')} ${bump.to}` : c.dim('(already)')}`);
+		if (!dryRun && moving.length) {
+			const path = join(dir, 'package.json');
+			writeFileSync(path, writeBumps(readFileSync(path, 'utf8'), bumps));
+			await install(dir, detectPackageManager(dir));
+		}
+	}
+
+	// A core this command cannot drive is handed, with the rest, to the command it came with.
+	const coreDir = coreDirFrom(dir);
+	const coreVersion = coreDir ? readJson(join(coreDir, 'package.json'))?.version : null;
+	const command = !dryRun && coreVersion && !satisfies(coreVersion) ? projectCommand(coreDir) : null;
+	const commandVersion = command ? readJson(join(command, 'package.json'))?.version : null;
+	if (command && commandVersion && commandVersion !== VERSION) {
+		log.step(`Going on with the project's amxts ${commandVersion}`);
+		const args = [join(command, 'bin', 'amxts.mjs'), 'upgrade', '--to', version, ...(server ? [] : ['--no-server'])];
+		const result = spawnSync(process.execPath, args, { cwd: dir, stdio: 'inherit', env: { ...process.env, AMXTS_UPGRADE_FROM: JSON.stringify(from) } });
+		process.exitCode = result.status ?? 1;
+		return null;
+	}
+
+	// With the new core installed - or, in a dry run, the installed one when it is already that version.
+	const core = coreDir && (!dryRun || from[CORE] === version) ? await loadCore(coreDir) : null;
+	/** @type {Outcome} */
+	const outcome = {
+		version,
+		packages: bumps.map(bump => ({ name: bump.name, spec: bump.spec, from: from[bump.name], version: bump.version, to: bump.to })),
+		code: null,
+		build: null,
+		server: null,
+		dryRun,
+	};
+
+	if (core) {
+		log.step(dryRun ? 'Code: what the rewrites would change' : 'Code');
+		const report = rewriteCode(core, dryRun);
+		outcome.code = { files: [...new Set(report.changes.map(change => change.file))], left: report.left };
+	} else {
+		log.step(`Code: rewritten by @amxts/core ${version} once it is installed`);
+	}
+
+	if (core && !dryRun) {
+		log.step('Build');
+		await prepare(core, { quiet: true });
+		outcome.build = runTask(core, 'build') === 0 ? 'built' : 'failed';
+	}
+
+	if (server) {
+		outcome.server = core
+			? await updateServer(core.api, dir, { dryRun })
+			: { ok: true, line: `the module of amxts ${version} goes in once @amxts/core ${version} is installed` };
+	}
+	console.log(['', ...summary(outcome)].join('\n'));
+	return outcome;
+}
+
+/**
+ * The core of `core` - a version, or `latest` - and the version each @amxts/
+ * package of the project goes to: the core's own, the others' newest that
+ * works with it. Only a package whose spec moves is asked for, and nothing
+ * when the project has that core already and nothing else moves.
+ */
+async function newest(registry, dir, pkg, core) {
+	const names = amxtsPackages(pkg).filter(each => each.name !== CORE && MOVABLE.test(each.spec.trim())).map(each => each.name);
+	if (!names.length && installedVersion(dir, CORE) === core) return { version: core, versions: { [CORE]: core } };
+	const found = await versionsFor(registry, core, names);
+	return { version: found.core, versions: { ...found.versions, [CORE]: found.core } };
+}
+
+/** The versions the command that handed the upgrade on installed: the core's, and each package's. */
+function installed(dir, pkg, version) {
+	return { version, versions: Object.fromEntries(amxtsPackages(pkg).map(each => [each.name, installedVersion(dir, each.name)])) };
+}
+
+function needCore() {
+	throw new CliError('@amxts/core is not installed in this project', 'Run amxts upgrade without --server-only first.');
+}

package/templates/module/README.md

@@ -47,7 +47,7 @@ export default defineConfig({
 A plugin of a project that lists the module uses it as `{{camel}}`, without an import:
 
 ```ts
-server.addCommand("/hello", {{camel}}.greet);
+server.addCommand("/hello", ({ player }) => {{camel}}.greet(player));
 ```
 
 | Function | What it does |

package/templates/module/README.ru.md

@@ -47,7 +47,7 @@ export default defineConfig({
 Плагин проекта, в котором модуль указан, пользуется им как `{{camel}}`, без импорта:
 
 ```ts
-server.addCommand("/hello", {{camel}}.greet);
+server.addCommand("/hello", ({ player }) => {{camel}}.greet(player));
 ```
 
 | Функция | Что делает |

package/templates/module/playground/plugins/welcome.ts

@@ -1,3 +1,3 @@
 plugin({ name: "Welcome", version: "0.1.0", author: "{{author}}", description: "Tries {{title}} out" });
 
-server.addCommand("/hello", {{camel}}.greet);
+server.addCommand("/hello", ({ player }) => {{camel}}.greet(player));

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/README.md

@@ -15,7 +15,8 @@ Counter-Strike 1.6 plugins in TypeScript, built with [amxts](https://amxts.githu
 - `{{amxts}} module add <name>` - installs a module and lists it in `amxts.config.ts`
 
 `AMXTS_SERVER` in `.env` is the `addons/amxts` folder of the server `dev`
-deploys to:
+deploys to. The server's own folder or its `cstrike` will do too: the build
+finds `cstrike/addons/amxts` under it.
 
 ```sh
 AMXTS_SERVER=D:/hlds/cstrike/addons/amxts

package/templates/project/plugins/hello.ts

@@ -3,37 +3,49 @@ plugin({ name: "Hello", version: "1.0.0", author: "{{author}}", description: "Th
 // #if config-core
 // configs/hello.yaml (or hello.json) says what a player is greeted with -
 // "greeting: Hi" - and "Welcome" is what it is when the file does not say.
-const { greeting } = configs.load("hello", { greeting: "Welcome" });
+interface HelloConfig {
+	greeting: string;
+}
+
+const { greeting } = configs.load<HelloConfig>("hello", { greeting: "Welcome" });
 // #endif
 // #if !config-core
 const greeting = "Welcome";
 // #endif
 
-server.addCommand("/hp", sayHp);
-server.addEventListener("putinserver", event => print(0, `${greeting}, ${event.player.name}!`));
+server.addCommand("/hp", ({ player }) => sayHp(player));
+server.addEventListener("putInServer", event => print(0, `${greeting}, ${event.player.name}!`));
 // #if menu-core
 
-// A menu made in code: its title and items can be functions of the player.
-const hello = menus.create("HELLO", { title: player => `Hello, ${player.name}` });
-hello.addItem("Wave", { onSelect: wave });
-hello.addItem(player => `Heal (${player.health} HP)`, {
-	visible: player => player.health < 100,
-	onSelect: heal,
+// 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: ({ player }) => `Heal (${player.health} HP)`,
+	visible: ({ player }) => player.health < 100,
+	onSelect: ({ player }) => {
+		player.health = 100;
+	},
 });
 
-server.addCommand("/menu", player => hello.show(player));
+server.addCommand("/menu", ({ player }) => hello.show(player));
 // #endif
+// #if !menu-core
 
-function sayHp(player: Player) {
-	print(player, `${player.name}, your HP: ${player.health}`);
-}
-// #if menu-core
+// 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: ({ player }) => `Heal (${player.health} HP)`,
+	visible: ({ player }) => player.health < 100,
+	onSelect: ({ player }) => {
+		player.health = 100;
+	},
+});
 
-function wave(player: Player) {
-	print(0, `${player.name} waves`);
-}
+server.addCommand("/menu", ({ player }) => hello.show(player));
+// #endif
 
-function heal(player: Player) {
-	player.health = 100;
+function sayHp(player: Player) {
+	print(player, `${player.name}, your HP: ${player.health}`);
 }
-// #endif