@amxts/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kukson777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @amxts/cli
+
+The `amxts` command of [amxts](https://amxts.github.io/): Counter-Strike 1.6
+plugins in TypeScript. It creates projects and module packages, adds
+modules, builds, deploys, type-checks and tests.
+
+A project has it already - `@amxts/core` depends on it - and runs it through
+its package manager:
+
+```sh
+npx amxts --help
+npx amxts dev              # build, deploy, again on every save
+npx amxts module add menu-core
+```
+
+A new project: `npm create amxts@latest`. Installed globally
+(`npm install -g @amxts/cli`), `amxts` works in any project with the
+project's own core.
+
+Every command: [the amxts command](https://amxts.github.io/docs/getting-started/cli).

package/bin/amxts.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The amxts command: `npx amxts --help`. Plain JavaScript, so that npm, pnpm
+// and yarn can start it with Node; the commands are in src/ (src/main.mjs
+// lists them).
+import process from 'node:process';
+import { main } from '../src/main.mjs';
+
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@amxts/cli",
+	"type": "module",
+	"version": "0.1.0",
+	"description": "The amxts command: create a project or a module, add modules, build, deploy, type-check and test",
+	"author": {
+		"name": "kukson777",
+		"url": "https://github.com/kukson777"
+	},
+	"license": "MIT",
+	"homepage": "https://amxts.github.io",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/amxts/amxts-cli.git",
+		"directory": "packages/cli"
+	},
+	"bugs": "https://github.com/amxts/amxts-cli/issues",
+	"keywords": [
+		"amxts",
+		"amxmodx",
+		"counter-strike",
+		"cli"
+	],
+	"exports": {
+		".": "./src/main.mjs",
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"amxts": "bin/amxts.mjs"
+	},
+	"files": [
+		"bin",
+		"src",
+		"templates"
+	],
+	"engines": {
+		"node": ">=20.12"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.8.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/args.mjs

@@ -0,0 +1,62 @@
+// A command's arguments: `--flag`, `--flag value`, `--flag=value`, `--no-flag`
+// for a boolean, `-y` for an alias, and the rest as positionals. An unknown
+// flag is an error that names the closest known one.
+import { CliError, closest } from './ui.mjs';
+
+/** Flags every command takes, as a command's help lists them. */
+export const GLOBAL_FLAGS = {
+	help: { type: 'boolean', alias: 'h', description: 'Show this help' },
+	debug: { type: 'boolean', description: 'Show the stack of an error' },
+};
+
+/**
+ * @param {string[]} argv
+ * @param {Record<string, { type: 'boolean' | 'string', alias?: string }>} flags
+ * @param {string} command the command's name, for the error
+ */
+export function parseArgs(argv, flags, command) {
+	const all = { ...GLOBAL_FLAGS, ...flags };
+	const aliases = new Map(Object.entries(all).filter(([, flag]) => flag.alias).map(([name, flag]) => [flag.alias, name]));
+	/** @type {Record<string, unknown>} */
+	const values = {};
+	const positionals = [];
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === '--') {
+			positionals.push(...argv.slice(i + 1));
+			break;
+		}
+		if (!arg.startsWith('-') || arg === '-') {
+			positionals.push(arg);
+			continue;
+		}
+
+		const [rawName, inline] = arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+		let name = rawName.startsWith('--') ? rawName.slice(2) : aliases.get(rawName.slice(1)) ?? rawName.slice(1);
+		let negated = false;
+		if (!(name in all) && name.startsWith('no-') && all[name.slice(3)]?.type === 'boolean') {
+			name = name.slice(3);
+			negated = true;
+		}
+		const flag = all[name];
+		if (!flag) {
+			const guess = closest(name, Object.keys(all));
+			throw new CliError(
+				`Unknown option ${rawName} for ${command}`,
+				guess ? `Did you mean --${guess}?` : `amxts ${command} --help lists the options.`,
+			);
+		}
+
+		if (flag.type === 'boolean') {
+			values[name] = negated ? false : inline === undefined ? true : !/^(?:false|0|no)$/i.test(inline);
+			continue;
+		}
+		const value = inline ?? argv[++i];
+		if (value === undefined || (inline === undefined && value.startsWith('--'))) {
+			throw new CliError(`${rawName} needs a value`, `amxts ${command} --help shows what it takes.`);
+		}
+		values[name] = value;
+	}
+	return { values, positionals };
+}

package/src/catalog.mjs

@@ -0,0 +1,196 @@
+// The modules the amxts command knows by their names - the amxts catalog,
+// the registry github.com/amxts/modules - and how a name given on the
+// command line becomes a package to install.
+//
+//   menu-core                  the catalog's menu-core: @amxts/menu-core, from npm
+//   @you/greeter               that package, from npm - with a warning when
+//                              the catalog does not list it
+//   ../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
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+import { readJson } from './core.mjs';
+import { CliError } from './ui.mjs';
+
+export const OFFICIAL_SCOPE = '@amxts';
+
+/** The registry's modules.json: CI rebuilds it on every change to the catalog. */
+export const CATALOG_URL = 'https://raw.githubusercontent.com/amxts/modules/main/modules.json';
+
+/**
+ * @typedef {object} CatalogModule a module of the catalog, as modules.json lists it
+ * @property {string} name its name in the catalog: "menu-core"
+ * @property {string} npm its package: "@amxts/menu-core"
+ * @property {string} repo its GitHub repository: "amxts/menu-core"
+ * @property {string} description what it is, in a line
+ * @property {string} category its category: "ui", "config"...
+ * @property {'official' | 'community'} type official: by the amxts team, under @amxts
+ * @property {string[]} requires the other modules of the catalog it needs, by npm name
+ */
+
+/** A modules.json as read: an array of modules with names, each with its `requires`; else an error. */
+function checked(modules) {
+	if (!Array.isArray(modules) || !modules.every(each => typeof each?.name === 'string' && typeof each.npm === 'string')) throw new Error('not a modules.json');
+	return modules.map(each => ({ ...each, requires: each.requires ?? [] }));
+}
+
+/** A modules.json from a file: a path or a file: URL. */
+const readCatalog = source => checked(JSON.parse(readFileSync(source, 'utf8')));
+
+/** A modules.json from a URL, or from a file when it is not one. */
+async function fetchCatalog(source) {
+	if (!/^https?:/.test(source)) return readCatalog(source);
+	const response = await fetch(source, { signal: AbortSignal.timeout(3000) });
+	if (!response.ok) throw new Error(`${source}: HTTP ${response.status}`);
+	return checked(await response.json());
+}
+
+/** @type {Promise<CatalogModule[]> | undefined} */
+let catalog;
+
+/**
+ * The catalog, read once per run: the registry's modules.json, or - offline,
+ * or when it does not answer in 3 seconds - the copy this package was
+ * published with. `AMXTS_CATALOG` reads another URL or a file instead.
+ * @returns {Promise<CatalogModule[]>} the catalog's modules
+ */
+export function loadCatalog() {
+	catalog ??= fetchCatalog(process.env.AMXTS_CATALOG || CATALOG_URL).catch(() => readCatalog(new URL('./modules.json', import.meta.url)));
+	return catalog;
+}
+
+export const shortName = name => name.replace(/^@[^/]+\//, '');
+
+/** A package folder's tagline: the italic line under its README's title, else its description. */
+export function taglineOf(dir) {
+	const readme = join(dir, 'README.md');
+	if (existsSync(readme)) {
+		const line = readFileSync(readme, 'utf8').split(/\r?\n/).find(each => /^\*[^*].*\*$/.test(each.trim()));
+		if (line) return line.trim().slice(1, -1);
+	}
+	return readJson(join(dir, 'package.json'))?.description ?? '';
+}
+
+const looksLikePath = arg => arg.startsWith('file:') || arg.startsWith('.') || isAbsolute(arg) || /^[a-z]:[\\/]/i.test(arg);
+
+/**
+ * @typedef {object} ModuleRef
+ * @property {string} name the package name: "@amxts/menu-core"
+ * @property {string | null} dir its folder, when it is installed from one
+ * @property {string} tagline what it is, in a line: its README's, else its description
+ * @property {string[]} requires the other modules it needs, as far as known before installing it
+ * @property {boolean} listed whether the catalog lists it
+ */
+
+/**
+ * What a name on the command line means.
+ * @param {string} arg
+ * @param {{ catalog?: CatalogModule[], local?: boolean, localModules?: Record<string, string>, cwd?: string }} options
+ *   `catalog`: loadCatalog()'s modules; `localModules`: where the core on
+ *   this machine takes the official modules from (its cli-api's
+ *   localModules()), for `local`
+ * @returns {ModuleRef} the package, and its folder when it comes from one
+ */
+export function resolveModule(arg, { catalog = [], local = false, localModules = {}, cwd = process.cwd() } = {}) {
+	if (looksLikePath(arg)) {
+		const dir = resolve(cwd, arg.replace(/^file:/, ''));
+		const json = readJson(join(dir, 'package.json'));
+		if (!json?.name) throw new CliError(`${arg} is not a package: no package.json with a name there`);
+		return { name: json.name, dir, tagline: taglineOf(dir), requires: requiresOf(json), listed: catalog.some(each => each.npm === json.name) };
+	}
+
+	const listed = catalog.find(each => each.name === arg || each.npm === arg);
+	const name = listed?.npm ?? arg;
+	if (!/^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(?:@.+)?$/i.test(name)) {
+		throw new CliError(`"${arg}" is not a package name`, 'A module is named as npm names it: menu-core, @amxts/menu-core, @you/greeter, or a folder: ../greeter');
+	}
+	if (local && listed?.type === 'official') {
+		const dir = localModules[name];
+		if (!dir) throw new CliError(`--local: the core has no folder for ${name}`, `Its package.json links the official modules with file: - ${name} is not among them.`);
+		return { name, dir, tagline: taglineOf(dir), requires: listed.requires, listed: true };
+	}
+	return { name, dir: null, tagline: listed?.description ?? '', requires: listed?.requires ?? [], listed: Boolean(listed) };
+}
+
+/**
+ * The modules, each followed by what it requires and was not given - and
+ * what that requires, in turn: the order `modules` lists them in.
+ * @param {ModuleRef[]} modules
+ * @param {{ catalog?: CatalogModule[], local?: boolean, localModules?: Record<string, string> }} options how a required one is resolved
+ * @returns {ModuleRef[]} the modules with all they require
+ */
+export function withRequired(modules, options) {
+	const names = new Set(modules.map(each => each.name));
+	const all = [];
+	const next = modules.toReversed();
+	while (next.length) {
+		const module = next.pop();
+		all.push(module);
+		const required = module.requires.filter(name => !names.has(name)).map(name => resolveModule(name, options));
+		for (const each of required) names.add(each.name);
+		next.push(...required.toReversed());
+	}
+	return all;
+}
+
+/**
+ * @typedef {object} ConfigEntry a module as `modules` in amxts.config.ts lists it
+ * @property {string} name its package: "@amxts/config-core"
+ * @property {string[]} [by] the modules that need it, when it is listed for them: "menu-core"
+ */
+
+/**
+ * What `modules` lists for the chosen modules: withRequired()'s order, a
+ * module that was not chosen with the ones that need it.
+ * @param {ModuleRef[]} all withRequired()'s modules
+ * @param {ModuleRef[]} chosen the ones asked for
+ * @returns {ConfigEntry[]} the entries
+ */
+export function configEntries(all, chosen) {
+	return all.map(module => ({
+		name: module.name,
+		by: chosen.includes(module) ? [] : all.filter(other => other.requires.includes(module.name)).map(other => shortName(other.name)),
+	}));
+}
+
+/** The other @amxts modules a package says it needs: its peer dependencies but the core. */
+function requiresOf(json) {
+	return Object.keys(json.peerDependencies ?? {}).filter(name => name.startsWith(`${OFFICIAL_SCOPE}/`) && name !== '@amxts/core');
+}
+
+/**
+ * The spec a package.json gives a package: the version asked for, or a link
+ * to its folder. A link, not a copy: a copy is what the package would publish
+ * (npm pack), and the core's folder has more than that - the patched
+ * compiler, the generated API. npm links a `file:` folder; pnpm and yarn copy
+ * it and link a `link:` one.
+ */
+export function specFor(ref, projectDir, pm = 'npm', version = 'latest') {
+	if (!ref.dir) return version;
+	// bun copies a file: folder and fails on it on Windows; its own link:
+	// takes a package registered with `bun link`, so it is registered first.
+	if (pm === 'bun') return bunLink(ref);
+	const path = relative(projectDir, ref.dir).replace(/\\/g, '/');
+	const protocol = pm === 'pnpm' || pm === 'yarn' ? 'link:' : 'file:';
+	return `${protocol}${isAbsolute(path) ? path : path.startsWith('.') ? path : `./${path}`}`;
+}
+
+/** What the package manager is given to install it: its folder or its name. */
+export function installTarget(ref, projectDir, pm) {
+	return ref.dir ? specFor(ref, projectDir, pm) : ref.name;
+}
+
+const bunLinked = new Set();
+
+/** `link:<name>` for bun, after `bun link` in the package's folder registered it. */
+function bunLink(ref) {
+	if (!bunLinked.has(ref.dir)) {
+		spawnSync('bun', ['link'], { cwd: ref.dir, stdio: 'ignore' });
+		bunLinked.add(ref.dir);
+	}
+	return `link:${ref.name}`;
+}

package/src/config.mjs

@@ -0,0 +1,191 @@
+// amxts.config.ts, read and edited as source: the TypeScript parser finds
+// `modules` in `export default defineConfig({ ... })`, and an edit touches
+// only the text it adds - the user's formatting, comments and other options
+// stay as they are. The parser is the core's TypeScript (core.mjs), so the
+// command itself does not install it.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { coreTypeScript } from './core.mjs';
+import { CliError } from './ui.mjs';
+
+export const CONFIG_FILE = 'amxts.config.ts';
+
+/** @type {typeof import('typescript')} */
+let ts;
+
+/** Loads the parser, once. */
+async function useTypeScript() {
+	ts ??= await coreTypeScript();
+}
+
+/** The object `export default defineConfig({ ... })` (or `export default { ... }`) gives. */
+function configObject(file) {
+	for (const statement of file.statements) {
+		if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+		let expression = statement.expression;
+		while (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)) expression = expression.expression;
+		if (ts.isCallExpression(expression)) expression = expression.arguments[0];
+		if (expression && ts.isObjectLiteralExpression(expression)) return expression;
+	}
+	return null;
+}
+
+function parse(text) {
+	return ts.createSourceFile(CONFIG_FILE, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+
+/** The object's `key: ...` property, or null. */
+function propertyOf(object, key) {
+	return object.properties.find(property => ts.isPropertyAssignment(property)
+		&& (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
+		&& property.name.text === key) ?? null;
+}
+
+/** The names a `modules` property lists: none when it is missing or not a list written out. */
+function namesIn(property) {
+	return property && ts.isArrayLiteralExpression(property.initializer)
+		? property.initializer.elements.filter(ts.isStringLiteralLike).map(element => element.text)
+		: [];
+}
+
+/** What `read` makes of the project's amxts.config.ts, or null without the file. */
+function readConfig(dir, read) {
+	const path = join(dir, CONFIG_FILE);
+	return existsSync(path) ? read(readFileSync(path, 'utf8')) : null;
+}
+
+/** The module names amxts.config.ts lists; null when it has no config object to read. */
+export async function configModules(text) {
+	await useTypeScript();
+	const object = configObject(parse(text));
+	return object ? namesIn(propertyOf(object, 'modules')) : null;
+}
+
+/** The project's amxts.config.ts modules, or null without the file. */
+export async function readConfigModules(dir) {
+	return readConfig(dir, configModules);
+}
+
+/** `target` as amxts.config.ts writes it - "rehlds" or "hlds" - or null when it does not. */
+export async function configTarget(text) {
+	await useTypeScript();
+	const object = configObject(parse(text));
+	const property = object && propertyOf(object, 'target');
+	return property && ts.isStringLiteralLike(property.initializer) ? property.initializer.text : null;
+}
+
+/** The project's amxts.config.ts target, or null without the file or the property. */
+export async function readConfigTarget(dir) {
+	return readConfig(dir, configTarget);
+}
+
+/**
+ * @typedef {import('./catalog.mjs').ConfigEntry} ConfigEntry
+ * @typedef {{ text: string, comment: string }} Item an entry as the list writes it: quoted, and its comment
+ */
+
+/** An entry in these quotes, with a comment naming the modules that need it. */
+function itemOf(entry, quote = '"') {
+	return {
+		text: `${quote}${entry.name.replaceAll(quote, `\\${quote}`)}${quote}`,
+		comment: entry.by?.length ? ` // needed by ${entry.by.join(', ')}` : '',
+	};
+}
+
+/** Items one per line, each after a line break and this indent. */
+function linesOf(items, indent) {
+	return items.map(each => `\n${indent}${each.text},${each.comment}`).join('');
+}
+
+/** A list of items for a property at `indent`: on one line, or one per line when one has a comment. */
+function listOf(items, indent, unit) {
+	return items.some(each => each.comment)
+		? `[${linesOf(items, indent + unit)}\n${indent}]`
+		: `[${items.map(each => each.text).join(', ')}]`;
+}
+
+/** `modules`' list for a new config, its property at `indent`. */
+export function modulesList(entries, indent = '\t') {
+	return listOf(entries.map(each => itemOf(each)), indent, '\t');
+}
+
+/** A new amxts.config.ts with these modules. */
+export function newConfig(entries) {
+	return `export default defineConfig({\n\tmodules: ${modulesList(entries)},\n});\n`;
+}
+
+/** The whitespace a line starts with. */
+function indentAt(text, position) {
+	const start = text.lastIndexOf('\n', position - 1) + 1;
+	return text.slice(start).match(/^[ \t]*/)[0];
+}
+
+/** The text's indent step: a tab, unless it indents with spaces. */
+const unitOf = text => (/\n\t/.test(text) || !/\n {2}/.test(text) ? '\t' : '  ');
+
+/**
+ * The config with these modules added to `modules`, in the quotes and the
+ * layout the list already has: one per line, or on one line - one per line
+ * when an entry has a comment.
+ *
+ * @param {string} text
+ * @param {(string | ConfigEntry)[]} modules the names, or entries that say who needs them
+ * @returns {Promise<{ text: string, added: string[] }>} the new text, and the names it did not list before
+ */
+export async function addToConfig(text, modules) {
+	await useTypeScript();
+	const entries = modules.map(each => (typeof each === 'string' ? { name: each } : each));
+	const file = parse(text);
+	const object = configObject(file);
+	if (!object) {
+		throw new CliError(`${CONFIG_FILE} has no \`export default defineConfig({ ... })\` to add the module to`, `Add it by hand: modules: ${modulesList(entries)}`);
+	}
+	const property = propertyOf(object, 'modules');
+	const listed = namesIn(property);
+	const adding = entries.filter((entry, i) => !listed.includes(entry.name) && entries.findIndex(each => each.name === entry.name) === i);
+	const added = adding.map(each => each.name);
+	if (added.length === 0) return { text, added };
+
+	if (property && !ts.isArrayLiteralExpression(property.initializer)) {
+		throw new CliError(`${CONFIG_FILE}: modules is not a list written out`, `Add it by hand: ${added.map(name => JSON.stringify(name)).join(', ')}`);
+	}
+
+	const firstString = property?.initializer.elements.find(ts.isStringLiteralLike);
+	const items = adding.map(entry => itemOf(entry, firstString ? firstString.getText(file)[0] : '"'));
+	const commented = items.some(each => each.comment);
+	const unit = unitOf(text);
+	const replace = (start, end, insert) => ({ text: text.slice(0, start) + insert + text.slice(end), added });
+
+	if (property) {
+		const array = property.initializer;
+		const elements = array.elements;
+		const indent = indentAt(text, property.getStart(file));
+		const last = elements.at(-1);
+		if (!last) return replace(array.getStart(file), array.end, listOf(items, indent, unit));
+		const line = position => file.getLineAndCharacterOfPosition(position).line;
+		// The end of the last element's line, past its comma and its comment.
+		const lineEnd = last.end + text.slice(last.end).search(/\r?\n|$/);
+		if (line(elements[0].getStart(file)) > line(array.getStart(file)) && array.end - 1 > lineEnd) {
+			// One per line: the new ones go after the last one's line, with a
+			// comma after it when it has none.
+			const comma = elements.hasTrailingComma ? '' : ',';
+			const lines = linesOf(items, indentAt(text, elements[0].getStart(file)));
+			return { text: text.slice(0, last.end) + comma + text.slice(last.end, lineEnd) + lines + text.slice(lineEnd), added };
+		}
+		if (!commented) return replace(last.end, last.end, items.map(each => `, ${each.text}`).join(''));
+		// On one line, and a comment to write: the list goes one per line.
+		return replace(array.getStart(file), array.end, listOf([...elements.map(each => ({ text: each.getText(file), comment: '' })), ...items], indent, unit));
+	}
+
+	// No `modules` yet: it goes first in the object.
+	const first = object.properties[0];
+	if (first) {
+		const start = first.getStart(file);
+		const indent = indentAt(text, start);
+		const entry = `modules: ${listOf(items, indent, unit)},`;
+		const sameLine = file.getLineAndCharacterOfPosition(start).line === file.getLineAndCharacterOfPosition(object.getStart(file)).line;
+		return replace(start, start, sameLine ? `${entry} ` : `${entry}\n${indent}`);
+	}
+	const indent = indentAt(text, object.getStart(file));
+	return replace(object.getStart(file), object.end, `{\n${indent}${unit}modules: ${listOf(items, indent + unit, unit)},\n${indent}}`);
+}