@amxts/cli 0.1.0 → 0.2.1

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.1",
 	"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,14 +10,14 @@
 // 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';
 import { shortName, specFor } from './catalog.mjs';
 import { CLI_DIR, CORE_RANGE, FROM_SOURCE, needLocalCore } from './core.mjs';
 import { LINT_DEPENDENCIES, LINT_SCRIPTS } from './lint.mjs';
-import { detectPackageManager, execAmxts, installArgs, runScript } from './pm.mjs';
+import { detectPackageManager, execAmxts, installArgs, runScript, testRunner } from './pm.mjs';
 import { copyTemplate, gitAuthor, writeFile } from './template.mjs';
 import { c, CliError, log } from './ui.mjs';
 
@@ -57,9 +57,11 @@ export async function initModule(options) {
 	}
 
 	const pm = options.pm ?? detectPackageManager();
+	const runner = testRunner(pm);
+	values['test.types'] = runner.types;
 	const localCore = (options.local ?? FROM_SOURCE) ? await needLocalCore() : null;
 
-	const written = copyTemplate(join(CLI_DIR, 'templates', 'module'), dir, values, { natives }, path => path === 'src/natives.ts' && !natives);
+	const written = copyTemplate(join(CLI_DIR, 'templates', 'module'), dir, values, { natives, bun: pm === 'bun' }, path => path === 'src/natives.ts' && !natives);
 
 	const amxts = { module: 'src/index.ts' };
 	if (natives) Object.assign(amxts, { natives: 'src/natives.ts', include: `include/${values.include}.inc` });
@@ -78,15 +80,15 @@ export async function initModule(options) {
 		scripts: {
 			build: 'amxts build',
 			check: 'amxts check',
-			test: 'amxts test',
+			test: runner.script,
 			...LINT_SCRIPTS,
 		},
 		peerDependencies: { '@amxts/core': CORE_RANGE },
 		devDependencies: Object.fromEntries(Object.entries({
 			...(localCore ? { '@amxts/core': specFor({ name: '@amxts/core', dir: localCore.dir }, dir, pm) } : {}),
 			...LINT_DEPENDENCIES,
-			'@types/bun': '^1.4.2',
-			'typescript': '^6.0.3',
+			...runner.devDependencies,
+			typescript: '^6.0.3',
 		}).sort(([a], [b]) => a.localeCompare(b))),
 	}, null, '\t')}\n`);
 	written.push('package.json');

package/src/init.mjs

@@ -18,15 +18,21 @@ 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, testRunner, 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 +150,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.
@@ -179,6 +186,7 @@ export async function initProject(options) {
 	// The files.
 	const amxts = execAmxts(pm);
 	const install = installArgs(pm).join(' ');
+	const runner = testRunner(pm);
 	const values = {
 		'name': packageName(root),
 		'author': gitAuthor(),
@@ -191,15 +199,18 @@ export async function initProject(options) {
 		'run.typecheck': runScript(pm, 'typecheck'),
 		'run.test': runScript(pm, 'test'),
 		'run.lint': runScript(pm, 'lint'),
+		'test.types': runner.types,
 	};
-	const flags = { lint, ...Object.fromEntries(installed.map(module => [shortName(module.name), true])) };
+	const flags = { lint, bun: pm === 'bun', ...Object.fromEntries(installed.map(module => [shortName(module.name), true])) };
 	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,
+		...runner.devDependencies,
 		...(lint ? LINT_DEPENDENCIES : {}),
 	};
 	writeFile(join(root, 'package.json'), `${JSON.stringify({
@@ -212,7 +223,7 @@ export async function initProject(options) {
 			dev: 'amxts dev',
 			build: 'amxts build',
 			typecheck: 'amxts typecheck',
-			test: 'amxts test',
+			test: runner.script,
 			...(lint ? LINT_SCRIPTS : {}),
 		},
 		devDependencies: Object.fromEntries(Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b))),
@@ -245,7 +256,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 +312,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

@@ -6,12 +6,15 @@
 // It runs on Node. Commands that make or change a project (init, module,
 // info) run here; the ones that compile (build, dev, typecheck, check,
 // prepare) are tasks of the project's core, which runs them on Bun
-// (core.mjs); test runs bun test.
+// (core.mjs); test runs the project's Vitest, or bun test.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import process from 'node:process';
 import { GLOBAL_FLAGS, parseArgs } from './args.mjs';
 import { needBun, needProject, projectCore, runTask, runTaskOrExit, VERSION } from './core.mjs';
 import { 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 +22,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 +40,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 +96,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 +118,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]);
@@ -126,12 +139,17 @@ export const COMMANDS = {
 		},
 	},
 	test: {
-		description: 'Run the project\'s tests on a fake server (bun test)',
-		usage: 'amxts test [bun test options]',
+		description: 'Run the project\'s tests on a fake server (Vitest when the project has it, else bun test)',
+		usage: 'amxts test [test runner options]',
 		passThrough: true,
 		examples: ['amxts test', 'amxts test hello', 'amxts test --watch'],
 		async run({ raw }) {
-			const result = await run([needBun(await projectCore(), 'runs tests'), 'test', ...raw]);
+			const core = await projectCore();
+			// A project with Vitest tests on Node; any other on bun test.
+			const vitest = join(needProject(), 'node_modules', 'vitest', 'vitest.mjs');
+			const result = await run(existsSync(vitest)
+				? [process.execPath, vitest, ...(raw.includes('--watch') ? [] : ['run']), ...raw]
+				: [needBun(core, 'runs tests'), 'test', ...raw]);
 			process.exitCode = result.code;
 		},
 	},
@@ -168,6 +186,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,75 @@ 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. */
+/**
+ * What a new project's or module's tests run on: `bun test` with Bun as the
+ * package manager, Vitest on Node with any other. `types` is the test
+ * folder's tsconfig `types`.
+ */
+export function testRunner(pm) {
+	return pm === 'bun'
+		? { script: 'amxts test', types: 'bun', devDependencies: { '@types/bun': '^1.4.2' } }
+		: { script: 'vitest run', types: 'node', devDependencies: { '@types/node': '^24.0.0', 'vitest': '^5.0.3' } };
+}
+
+/**
+ * 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 +151,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 +165,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]])) };
+}