@amxts/cli 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,7 @@ its package manager:
 npx amxts --help
 npx amxts dev              # build, deploy, again on every save
 npx amxts module add menu-core
+npx amxts upgrade          # the latest amxts: packages, code, build, server
 ```
 
 A new project: `npm create amxts@latest`. Installed globally

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@amxts/cli",
 	"type": "module",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "The amxts command: create a project or a module, add modules, build, deploy, type-check and test",
 	"author": {
 		"name": "kukson777",

package/src/catalog.mjs

@@ -8,7 +8,7 @@
 //   ../greeter, file:../x      the package in that folder
 //   menu-core --local          the folder the core on this machine takes an
 //                              official module from (its package.json's
-//                              `file:` link) - until they are on npm
+//                              `file:` link), for working on them
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';

package/src/core.mjs

@@ -15,7 +15,7 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { addArgs, commandLine, detectPackageManager, versionOf } from './pm.mjs';
+import { addArgs, commandLine, detectPackageManager, execAmxts, versionOf } from './pm.mjs';
 import { CliError, debug } from './ui.mjs';
 
 /** The command's own package folder: packages/cli in its repository. */
@@ -24,14 +24,15 @@ export const CLI_PACKAGE = readJson(join(CLI_DIR, 'package.json'));
 export const VERSION = String(CLI_PACKAGE.version);
 
 /** The cores this command works with: the range a new project asks for. */
-export const CORE_RANGE = '^0.1.0';
+export const CORE_RANGE = '^0.2.0';
 /** The version of `@amxts/core/cli-api` this command speaks. */
-export const CLI_API = 3;
+export const CLI_API = 5;
 
 /**
  * Run from a checkout of the command's repository (npm link, a clone) rather
  * than from npm: then a new project takes the core and the official modules
- * from this machine by default, as --local says - they are not on npm to fetch.
+ * from this machine by default, as --local says: the checkout is for working
+ * on them together.
  */
 export const FROM_SOURCE = existsSync(join(CLI_DIR, '..', '..', '.git')) && readJson(join(CLI_DIR, '..', '..', 'package.json'))?.name === 'amxts-cli';
 
@@ -85,14 +86,38 @@ function parts(version) {
 	return String(version).split('-')[0].split('.').map(each => Number.parseInt(each, 10) || 0);
 }
 
-/** Whether a version is in a caret range: `^0.1.0` takes 0.1.x from 0.1.0 up. */
+/** Two versions compared: below 0 when `a` comes first. */
+export function compareVersions(a, b) {
+	const [x, y] = [parts(a), parts(b)];
+	return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
+}
+
+/**
+ * One comparator of a range as a test of a version: `^0.2.0` (0.2.x from
+ * 0.2.0 up - below 1.0 the minor is the breaking number), `~0.2.1`, `>=0.2.0`,
+ * `<1.0.0`, `0.2.0`, `*`.
+ */
+function comparator(text) {
+	const [, op = '=', want = '*'] = /^([<>]=?|[\^~=])?v?(.*)$/.exec(text);
+	if (/^[*x]?$/i.test(want)) return () => true;
+	const [major, minor, patch] = parts(want);
+	const upper = op === '^' ? (major ? `${major + 1}.0.0` : minor ? `0.${minor + 1}.0` : `0.0.${patch + 1}`) : `${major}.${minor + 1}.0`;
+	const within = version => compareVersions(version, want) >= 0 && compareVersions(version, upper) < 0;
+	const tests = {
+		'^': within,
+		'~': within,
+		'>=': version => compareVersions(version, want) >= 0,
+		'<=': version => compareVersions(version, want) <= 0,
+		'>': version => compareVersions(version, want) > 0,
+		'<': version => compareVersions(version, want) < 0,
+		'=': version => compareVersions(version, want) === 0,
+	};
+	return tests[op];
+}
+
+/** Whether a range takes a version, as npm reads one: `^0.2.0`, `>=0.2.0 <0.4.0`, `^0.2.0 || ^0.3.0`. */
 export function satisfies(version, range = CORE_RANGE) {
-	const [major, minor, patch] = parts(version);
-	const [wantMajor, wantMinor, wantPatch] = parts(range.replace(/^\^/, ''));
-	if (major !== wantMajor) return false;
-	// Below 1.0 the minor is the breaking number: ^0.1.0 does not take 0.2.0.
-	if (major === 0 && minor !== wantMinor) return false;
-	return minor > wantMinor || (minor === wantMinor && patch >= wantPatch);
+	return range.split('||').some(alternative => alternative.trim().split(/\s+/).every(each => comparator(each)(version)));
 }
 
 /** Whether a version is past a caret range, not below it: its major, or below 1.0 its minor, is the higher. */
@@ -107,7 +132,7 @@ function updateHint(coreIsNewer) {
 	const pm = detectPackageManager();
 	return coreIsNewer
 		? `Update the command: npm install -g @amxts/cli@latest - a project's own ${pm === 'npm' ? 'npx amxts' : `${pm} amxts`} comes with its core`
-		: `Update the core: ${commandLine(addArgs(pm, ['@amxts/core@latest']))}`;
+		: `Move the project to amxts ${VERSION}: ${execAmxts(pm)} upgrade`;
 }
 
 /**

package/src/includes.mjs

@@ -23,6 +23,7 @@ import process from 'node:process';
 import { inflateRawSync } from 'node:zlib';
 import { readConfigTarget } from './config.mjs';
 import { findProject, runTaskOrExit, setting } from './core.mjs';
+import { serverFolderOrNull } from './server.mjs';
 import { c, CliError, log } from './ui.mjs';
 
 /** The servers a project can be for, as `target` in amxts.config.ts and `--target` name them. */
@@ -132,7 +133,7 @@ export async function fetchIncludes(source) {
  * @returns {Promise<Includes>} where the includes are
  */
 export async function ensureIncludes(core, root, options = {}) {
-	const own = serverIncludes(setting(root, 'AMXTS_SERVER'));
+	const own = serverIncludes(serverFolderOrNull(setting(root, 'AMXTS_SERVER')));
 	if (own) return { from: 'server', target: targetOf(own), dir: own };
 
 	const target = options.target ?? (await readConfigTarget(root)) ?? 'rehlds';

package/src/info.mjs

@@ -8,6 +8,7 @@ import process from 'node:process';
 import { readConfigModules } from './config.mjs';
 import { bunFor, bunVersion, CLI_DIR, installedCore, readJson, setting, VERSION } from './core.mjs';
 import { detectPackageManager, versionOf } from './pm.mjs';
+import { serverFolderOrNull } from './server.mjs';
 import { c, CliError } from './ui.mjs';
 
 /** The project's core, or why it cannot be used: not installed, or not one this command works with. */
@@ -21,6 +22,14 @@ async function core(dir) {
 	}
 }
 
+/** After AMXTS_SERVER: the addons/amxts it names when it is a folder above it, or why it is no server. */
+function serverNote(server) {
+	const folder = serverFolderOrNull(server);
+	if (folder === null) return c.red(' (not a server)');
+	const shown = folder === server ? '' : ` - ${folder.replace(/\\/g, '/')}`;
+	return existsSync(folder) ? c.dim(shown) : c.red(`${shown} (not found)`);
+}
+
 /**
  * The system the build compiles for, as the core decides it from .env and the
  * server's folder: "Linux (hlds_linux)". A core without serverSystem() builds
@@ -73,7 +82,7 @@ export async function info() {
 						const version = readJson(join(dir, 'node_modules', name, 'package.json'))?.version;
 						return version ? `${name} ${version}` : `${name} ${c.red('(not installed)')}`;
 					}).join(', ')],
-		['AMXTS_SERVER', server ? `${server}${existsSync(server) ? '' : c.red(' (not found)')}` : c.dim('not set')],
+		['AMXTS_SERVER', server ? `${server}${serverNote(server)}` : c.dim('not set')],
 		['Server system', system],
 		['AMXTS_DOCS_LANG', setting(dir, 'AMXTS_DOCS_LANG') || c.dim('en')],
 	];

package/src/init-module.mjs

@@ -10,7 +10,7 @@
 // user.name) as {{placeholders}}; `// #if natives` blocks are kept only with
 // --natives. The core is a peer dependency, the range this command works with;
 // with --local (the default from a checkout) it is also a dev dependency
-// linked to the core on this machine, since it is not on npm to install.
+// linked to the core on this machine, which it is developed against.
 import { existsSync, readdirSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import process from 'node:process';

package/src/init.mjs

@@ -18,15 +18,22 @@ import { modulesList } from './config.mjs';
 import { bunFor, CLI_DIR, CORE_RANGE, coreDirFrom, FROM_SOURCE, loadCore, needLocalCore, readJson, VERSION } from './core.mjs';
 import { ensureIncludes, FETCHED, serverIncludes, targetOf, TARGETS } from './includes.mjs';
 import { LINT_DEPENDENCIES, LINT_FILES, LINT_SCRIPTS } from './lint.mjs';
-import { commandLine, execAmxts, installArgs, PACKAGE_MANAGERS, packageManagerOfAgent, run, runScript, versionOf } from './pm.mjs';
-import { askServer, canAsk, missingServer, serverEnv } from './server.mjs';
+import { commandLine, execAmxts, installArgs, installLinked, linkedFolders, PACKAGE_MANAGERS, packageManagerOfAgent, run, runScript, versionOf } from './pm.mjs';
+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';
 
-/** The tools a project gets besides the core and its modules. */
+/**
+ * The tools a project gets besides the core and its modules. knip reads the
+ * knip.json the template writes; from 6 on it counts a package imported by
+ * its name as used wherever the name resolves, so a core and modules linked
+ * from this machine's folders (--local) are not called unused.
+ */
 const TOOLS = {
 	'@types/bun': '^1.4.2',
+	'knip': '^6.39.0',
 };
 
 const DEFAULT_DIR = 'my-server';
@@ -144,7 +151,8 @@ export async function initProject(options) {
 	const git = hasGit && (options.git ?? (interactive
 		? answer(await p.confirm({ message: 'Initialize a git repository?', initialValue: true }))
 		: true));
-	const server = options.server ?? (interactive ? answer(await askServer(pm)) : '');
+	// Its folder, cstrike or addons/amxts: .env keeps the addons/amxts.
+	const server = options.server === undefined ? (interactive ? answer(await askServer(pm)) : '') : serverFolder(options.server);
 
 	// 7. Which server the project is for: its includes say, when it has them
 	// (addons/amxmodx/scripting/include beside AMXTS_SERVER); else asked.
@@ -196,9 +204,10 @@ export async function initProject(options) {
 	const written = copyTemplate(join(CLI_DIR, 'templates', 'project'), root, values, flags, path => LINT_FILES.includes(path) && !lint);
 
 	const core = { name: '@amxts/core', dir: localCore?.dir ?? null };
+	const versions = await moduleVersions(installed);
 	const devDependencies = {
 		[core.name]: specFor(core, root, pm, CORE_RANGE),
-		...Object.fromEntries(installed.map(module => [module.name, specFor(module, root, pm)])),
+		...Object.fromEntries(installed.map(module => [module.name, specFor(module, root, pm, versions[module.name] ? `^${versions[module.name]}` : 'latest')])),
 		...TOOLS,
 		...(lint ? LINT_DEPENDENCIES : {}),
 	};
@@ -245,7 +254,7 @@ export async function initProject(options) {
 		// A spinner in a terminal; in a log (CI, a pipe) one line before and one after.
 		const spinner = process.stdout.isTTY ? p.spinner() : { start: text => p.log.step(text), stop: (text, code) => (code ? p.log.error(text) : p.log.success(text)) };
 		spinner.start(`Installing dependencies with ${pm}`);
-		const result = await run(installArgs(pm), { cwd: root, quiet: true });
+		const result = await installLinked(installArgs(pm), linkedFolders(root), { cwd: root, quiet: true });
 		if (result.code === 0) {
 			pinLatest(root);
 			installedOk = true;
@@ -301,6 +310,25 @@ export async function initProject(options) {
 	if (options.install !== false && pmVersion && !installedOk) process.exitCode = 1;
 }
 
+/**
+ * The modules from the registry, each at its newest version that works with
+ * the newest core of CORE_RANGE - the core the project gets; a module from a
+ * folder, or a package named with its version, is left to its spec. When the
+ * registry does not answer, none: `latest`, and the install says why.
+ * @param {import('./catalog.mjs').ModuleRef[]} modules
+ * @returns {Promise<Record<string, string>>} the versions, by name
+ */
+async function moduleVersions(modules) {
+	const names = modules.filter(module => !module.dir && !/^@?[^@]+@/.test(module.name)).map(module => module.name);
+	if (!names.length) return {};
+	try {
+		return (await versionsFor(npmRegistry(process.cwd()), CORE_RANGE, names)).versions;
+	} catch (error) {
+		if (error instanceof CliError && !/npm view/.test(error.message)) throw error;
+		return {};
+	}
+}
+
 /** `"latest"` in package.json, after the install, as the version it installed: `^1.6.2`. */
 function pinLatest(root) {
 	const path = join(root, 'package.json');

package/src/main.mjs

@@ -12,6 +12,7 @@ import { GLOBAL_FLAGS, parseArgs } from './args.mjs';
 import { needBun, needProject, projectCore, runTask, runTaskOrExit, VERSION } from './core.mjs';
 import { prepare, TARGETS } from './includes.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';
@@ -19,6 +20,12 @@ import { banner, c, CliError, closest, log, report } from './ui.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' };
 
+/** The line for a server whose module is of another release than the project's core. */
+function warnServer(core, os) {
+	const line = serverMismatch(core, needProject(), os);
+	if (line) log.warn(line);
+}
+
 /** --os as the build task takes it. */
 function osArgs(values) {
 	if (values.os === undefined) return [];
@@ -31,7 +38,7 @@ const INIT_FLAGS = {
 	modules: { type: 'string', value: 'list', description: 'Modules to add, comma-separated: menu-core,config-core ("" for none)' },
 	lint: { type: 'boolean', description: 'oxlint and oxfmt, with @antfu/eslint-config\'s rules (--no-lint to leave them out)' },
 	git: { type: 'boolean', description: 'git init (--no-git to skip)' },
-	server: { type: 'string', value: 'path', description: 'The server\'s addons/amxts folder, written to .env as AMXTS_SERVER; the build takes its includes' },
+	server: { type: 'string', value: 'path', description: 'The server: its folder, its cstrike or its addons/amxts; .env keeps the addons/amxts as AMXTS_SERVER, and the build takes its includes' },
 	os: { type: 'string', value: Object.keys(SYSTEMS).join('|'), description: 'The server\'s system, when the server\'s folder does not show it: written to .env as AMXTS_SERVER_OS' },
 	target: { type: 'string', value: Object.keys(TARGETS).join('|'), description: 'The server the project is for, when no server is given: rehlds - ReHLDS, ReGameDLL and ReAPI (recommended) - or hlds' },
 	install: { type: 'boolean', description: 'Install the dependencies (--no-install to skip)' },
@@ -87,7 +94,10 @@ export const COMMANDS = {
 			const core = await projectCore();
 			banner(core.version, 'dev');
 			// The container reads dist/ where it is: nothing to deploy, and AMXTS_SERVER is not asked.
-			if (!values.docker) await ensureServer(needProject(), detectPackageManager());
+			if (!values.docker) {
+				await ensureServer(needProject(), 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)]);
@@ -106,6 +116,7 @@ export const COMMANDS = {
 			const os = osArgs(values);
 			const core = await projectCore();
 			banner(core.version, 'build');
+			warnServer(core, os);
 			if (values.deploy) await ensureServer(needProject(), detectPackageManager());
 			await prepare(core, { quiet: true });
 			runTaskOrExit(core, 'build', [...(values.deploy ? ['--deploy'] : []), ...(values.watch ? ['--watch'] : []), ...os]);
@@ -168,6 +179,21 @@ export const COMMANDS = {
 			await prepare(await projectCore());
 		},
 	},
+	upgrade: {
+		description: 'Move the project to the latest amxts: its packages, its code, the build and the server',
+		usage: 'amxts upgrade [--to <version>] [--no-server] [--server-only] [--dry-run]',
+		flags: {
+			to: { type: 'string', value: 'version', description: 'The version to move to (the latest on the registry by default)' },
+			server: { type: 'boolean', description: 'Update the server in AMXTS_SERVER: its module, from the release (--no-server to leave it)' },
+			serverOnly: { type: 'boolean', description: 'Only update the server - once it is stopped, when the upgrade found it running' },
+			dryRun: { type: 'boolean', description: 'Say what would change, and change nothing' },
+		},
+		examples: ['amxts upgrade', 'amxts upgrade --dry-run', 'amxts upgrade --to 0.2.0 --no-server', 'amxts upgrade --server-only'],
+		async run({ values }) {
+			const { upgrade } = await import('./upgrade.mjs');
+			await upgrade({ to: values.to, server: values.server !== false, serverOnly: values.serverOnly, dryRun: values.dryRun });
+		},
+	},
 	info: {
 		description: 'Versions and settings, for a bug report',
 		usage: 'amxts info',

package/src/module.mjs

@@ -16,7 +16,8 @@ import { configEntries, installTarget, loadCatalog, resolveModule, taglineOf, wi
 import { addToConfig, CONFIG_FILE, newConfig, readConfigModules } from './config.mjs';
 import { FROM_SOURCE, installedCore, needLocalCore, needProject, readJson } from './core.mjs';
 import { prepare } from './includes.mjs';
-import { addArgs, commandLine, detectPackageManager, execAmxts, run, versionOf } from './pm.mjs';
+import { addArgs, commandLine, detectPackageManager, execAmxts, installLinked, linkedFolders, versionOf } from './pm.mjs';
+import { npmRegistry, versionsFor } from './registry.mjs';
 import { c, CliError, log } from './ui.mjs';
 
 /**
@@ -46,9 +47,12 @@ export async function moduleAdd(names, options = {}) {
 
 	if (!options.skipInstall) {
 		if (!versionOf(pm)) throw new CliError(`${pm} is not installed, and this project uses it`, `Install ${pm}, or add the package by hand and run amxts module add ${names.join(' ')} --skip-install.`);
-		const argv = addArgs(pm, toInstall.map(module => installTarget(module, dir, pm)));
+		// A module from the registry at its newest version that works with the project's core.
+		const fromRegistry = core ? toInstall.filter(module => !module.dir && !/^@?[^@]+@/.test(module.name)).map(module => module.name) : [];
+		const { versions } = fromRegistry.length ? await versionsFor(npmRegistry(dir), core.version, fromRegistry) : { versions: {} };
+		const argv = addArgs(pm, toInstall.map(module => (versions[module.name] ? `${module.name}@^${versions[module.name]}` : installTarget(module, dir, pm))));
 		log.step(`${commandLine(argv)}`);
-		const result = await run(argv, { cwd: dir });
+		const result = await installLinked(argv, linkedFolders(dir, toInstall.map(module => module.dir).filter(Boolean)), { cwd: dir });
 		if (result.code !== 0) throw new CliError(`${commandLine(argv)} failed`, 'The package manager says why, above.');
 	}
 

package/src/pm.mjs

@@ -1,7 +1,7 @@
 // The package manager a project uses - npm, pnpm, yarn or bun - and the
 // commands each one spells its own way.
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
 
@@ -75,9 +75,64 @@ export function execAmxts(pm) {
 	return { npm: 'npx amxts', pnpm: 'pnpm amxts', yarn: 'yarn amxts', bun: 'bunx amxts' }[pm] ?? 'npx amxts';
 }
 
-/** A command line as it is shown: arguments with spaces quoted. */
+/**
+ * The folders a project's package.json takes packages from - `link:` and
+ * `file:` specs: the core and the modules of this machine (--local).
+ * @param {string} projectDir
+ * @param {string[]} [more] folders about to be added
+ * @returns {string[]} the folders
+ */
+export function linkedFolders(projectDir, more = []) {
+	let json = {};
+	try {
+		json = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+	} catch {}
+	const specs = Object.values({ ...json.dependencies, ...json.devDependencies });
+	const linked = specs.filter(spec => /^(?:link|file):(?:[./]|[a-z]:)/i.test(spec)).map(spec => resolve(projectDir, spec.replace(/^\w+:/, '')));
+	return [...new Set([...linked, ...more])];
+}
+
+/**
+ * Runs an install and leaves the `node_modules/.bin` of each linked folder
+ * as it was. yarn 1 installs a `link:` folder's dependencies into the
+ * project and points that folder's own `.bin` at them: the core's `tsc`,
+ * `amxts` and `bun` would start the project's copies.
+ * @param {string[]} argv
+ * @param {string[]} linked the linked folders, `linkedFolders`
+ * @param {Parameters<typeof run>[1]} [options]
+ */
+export async function installLinked(argv, linked, options) {
+	const bins = linked.map(dir => join(dir, 'node_modules', '.bin'));
+	const saved = bins.map(binsOf);
+	const result = await run(argv, options);
+	bins.forEach((dir, i) => putBack(dir, saved[i]));
+	return result;
+}
+
+/** A `.bin` folder's entries: a link's target, or a file's bytes. Null when there is none. */
+function binsOf(dir) {
+	if (!existsSync(dir)) return null;
+	return new Map(readdirSync(dir).map((name) => {
+		const path = join(dir, name);
+		const stat = lstatSync(path);
+		return [name, stat.isSymbolicLink() ? { link: readlinkSync(path) } : { data: readFileSync(path), mode: stat.mode }];
+	}));
+}
+
+/** Writes a `.bin` folder back as `binsOf` read it; what the install added goes. */
+function putBack(dir, saved) {
+	if (!saved) return;
+	mkdirSync(dir, { recursive: true });
+	for (const name of readdirSync(dir)) rmSync(join(dir, name), { force: true });
+	for (const [name, entry] of saved) {
+		if (entry.link) symlinkSync(entry.link, join(dir, name));
+		else writeFileSync(join(dir, name), entry.data, { mode: entry.mode });
+	}
+}
+
+/** A command line as it is shown, and as Windows' shell runs it: arguments with spaces, or with what that shell reads (`^0.2.0`), quoted. */
 export function commandLine(argv) {
-	return argv.map(arg => (/\s/.test(arg) ? `"${arg}"` : arg)).join(' ');
+	return argv.map(arg => (/[\s^&|<>]/.test(arg) ? `"${arg}"` : arg)).join(' ');
 }
 
 /**
@@ -85,7 +140,7 @@ export function commandLine(argv) {
  * .cmd files; `quiet` collects the output instead of showing it, for a
  * spinner, and hands it back for an error.
  *
- * @returns {Promise<{ code: number, output: string }>} its exit code, and its output when quiet
+ * @returns {Promise<{ code: number, output: string, stdout: string }>} its exit code, and its output when quiet - all of it, and what went to stdout alone
  */
 export function run(argv, { cwd = process.cwd(), quiet = false, env } = {}) {
 	return new Promise((done) => {
@@ -99,13 +154,15 @@ export function run(argv, { cwd = process.cwd(), quiet = false, env } = {}) {
 			windowsHide: true,
 		});
 		let output = '';
+		let stdout = '';
 		child.stdout?.on('data', (chunk) => {
 			output += chunk;
+			stdout += chunk;
 		});
 		child.stderr?.on('data', (chunk) => {
 			output += chunk;
 		});
-		child.on('error', error => done({ code: 127, output: `${output}${error.message}` }));
-		child.on('close', code => done({ code: code ?? 1, output }));
+		child.on('error', error => done({ code: 127, output: `${output}${error.message}`, stdout }));
+		child.on('close', code => done({ code: code ?? 1, output, stdout }));
 	});
 }

package/src/registry.mjs

@@ -0,0 +1,83 @@
+// The versions of the @amxts packages that go together. Every package has a
+// version of its own: a module versions by its own API and names the cores it
+// works with as a range (`peerDependencies`: `"@amxts/core": "^0.2.0"`); the
+// core names the command and wamrc it comes with the same way. So for a core,
+// each package's newest version that works with it - what `amxts upgrade`
+// moves a project to, and what a new project and `amxts module add` install.
+import { compareVersions, satisfies } from './core.mjs';
+import { run } from './pm.mjs';
+import { CliError } from './ui.mjs';
+
+export const CORE = '@amxts/core';
+
+/**
+ * @typedef {object} Release a version of a package, as the registry has it
+ * @property {string} version its version
+ * @property {Record<string, string>} [dependencies] what it depends on, by range
+ * @property {Record<string, string>} [peerDependencies] what it needs beside it: a module's core and modules
+ * @property {Record<string, string>} [optionalDependencies] what it takes when there is one for the system: the core's wamrc
+ */
+
+/**
+ * @typedef {object} Registry
+ * @property {(name: string, spec?: string) => Promise<Release[]>} versions a package's versions of `spec` - `*`, a version, a tag - with what they depend on; none when it has none
+ */
+
+/**
+ * The registry npm is set to - NPM_CONFIG_REGISTRY, .npmrc - through npm itself.
+ * @param {string} dir the folder whose .npmrc npm reads
+ * @returns {Registry} the registry
+ */
+export function npmRegistry(dir) {
+	return {
+		versions: async (name, spec = '*') => {
+			const result = await run(['npm', 'view', `${name}@${spec}`, 'version', 'dependencies', 'peerDependencies', 'optionalDependencies', '--json'], { cwd: dir, quiet: true });
+			if (result.code !== 0) {
+				if (/E404|404 Not Found|No match found/.test(result.output)) return [];
+				throw new CliError(`npm view ${name}@${spec} failed`, result.output.trim().split('\n').slice(-5).join('\n'));
+			}
+			// One version is an object, more a list; a version that depends on nothing, its version alone.
+			return [JSON.parse(result.stdout.trim() || '[]')].flat().map(each => (typeof each === 'string' ? { version: each } : each));
+		},
+	};
+}
+
+/**
+ * The newest of a package's releases that works with a core: one whose own
+ * range for the core takes the core's version; for a package that names no
+ * core, one the core's own range for it takes (the command, wamrc); else the
+ * newest.
+ * @param {Release[]} releases
+ * @param {string} name
+ * @param {Release} core
+ * @returns {string | null} the version; null when none works with the core
+ */
+export function newestFor(releases, name, core) {
+	const asked = core.dependencies?.[name] ?? core.optionalDependencies?.[name];
+	const fits = (release) => {
+		const range = release.peerDependencies?.[CORE] ?? release.dependencies?.[CORE];
+		return range ? satisfies(core.version, range) : !asked || satisfies(release.version, asked);
+	};
+	return releases.filter(fits).map(each => each.version).sort(compareVersions).at(-1) ?? null;
+}
+
+/**
+ * A core and, for it, the newest version of each package that works with it,
+ * asked of the registry all at once. The core is a version, a tag (`latest`),
+ * or a range, whose newest version it is. Throws, saying which, when the core
+ * or a package has no such version.
+ * @param {Registry} registry
+ * @param {string} core
+ * @param {string[]} names
+ * @returns {Promise<{ core: string, versions: Record<string, string> }>} the core's version, and each package's
+ */
+export async function versionsFor(registry, core, names) {
+	const range = !/^(?:\d+\.\d+\.\d+(?:-[\w.-]+)?|[a-z][\w-]*)$/i.test(core);
+	const [cores, ...lists] = await Promise.all([registry.versions(CORE, range ? '*' : core), ...names.map(name => registry.versions(name))]);
+	const found = cores.filter(each => !range || satisfies(each.version, core)).sort((a, b) => compareVersions(a.version, b.version)).at(-1);
+	if (!found) throw new CliError(`${CORE} ${core} is not on the registry`, 'npm config get registry says which one npm asks.');
+	const versions = names.map((name, i) => newestFor(lists[i], name, found));
+	const missing = names.map((name, i) => !versions[i] && (lists[i].length ? `${name} has no version for ${CORE} ${found.version}` : `${name} is not on the registry`)).filter(Boolean);
+	if (missing.length) throw new CliError(missing.join('\n'), `Each package takes its newest version that works with the core; a module that has none is not released for ${CORE} ${found.version} yet.`);
+	return { core: found.version, versions: Object.fromEntries(names.map((name, i) => [name, versions[i]])) };
+}

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