@amxts/core 0.1.0 → 0.2.1

package/scripts/prebuilt.ts

@@ -5,6 +5,13 @@
 // would compile the same thing; when it would not, the build says why and
 // compiles it.
 //
+// The manifest also carries the module's surface - the proxy a plugin that
+// uses the module reads in its place, and the owner's dispatcher
+// (scripts/shared-modules.ts) - which every compile of a plugin that uses
+// it would otherwise make by analysing the module with asc. It is taken on
+// the same terms as the .aot, but for what only the machine code depends on:
+// the system and the forwards' declarations.
+//
 //   bun scripts/prebuilt.ts      in a project: compile every module it lists
 //                                into the module's prebuilt/, for every
 //                                system (scripts/publish.ts runs it on the
@@ -34,15 +41,18 @@
 // no change to the code.
 import type { NativesBeside, PluginNative } from './plugin-natives';
 import type { ModulePackage, Options, Sources } from './project';
+import type { ModuleSurface } from './shared-modules';
 import type { System } from './system';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import ts from 'typescript';
+import { coreVersion } from './build-identity';
 import { compileToMachineCode, compileToWasm } from './compile';
 import { codeFiles } from './compile-cache';
 import { includeForward, nativesBeside } from './plugin-natives';
-import { CORE_DIR, CORE_PLUGINS, loadProject, optionsOf, sourcesFor } from './project';
+import { CORE_DIR, CORE_PLUGINS, loadProject, optionsOf, shared, sourcesFor } from './project';
+import { moduleSurface } from './shared-modules';
 import { SYSTEM_NAME, SYSTEMS, wamrcPath } from './system';
 import { c, log, since } from './ui';
 
@@ -76,6 +86,8 @@ export interface PrebuiltManifest {
 	natives: PluginNative[];
 	beside: NativesBeside;
 	systems: Partial<Record<System, { file: string; size: number; sha256: string }>>;
+	/** What a plugin that uses the module compiles against (scripts/shared-modules.ts); missing in a manifest made without it. */
+	surface?: ModuleSurface;
 }
 
 /** What a build does with a module's prebuilt .aot: takes it, or compiles the module and says why. */
@@ -142,7 +154,7 @@ function coreHash(): string {
 /** The core or a module package the project has, by name, as a prebuilt module is checked against it. */
 function installed(name: string, sources: Sources): { version: string; dir: string; hash: () => string } | null {
 	if (name === CORE_NAME) {
-		return { version: String(JSON.parse(readFileSync(join(CORE_DIR, 'package.json'), 'utf8')).version), dir: CORE_DIR, hash: coreHash };
+		return { version: coreVersion(), dir: CORE_DIR, hash: coreHash };
 	}
 	const pkg = sources.project.packages.find(each => each.name === name);
 	return pkg ? { version: pkg.version, dir: pkg.dir, hash: () => packageHash(pkg) } : null;
@@ -155,49 +167,77 @@ function declarationOf(name: string): string | null {
 }
 
 /**
- * The prebuilt .aot of a module from npm for `system`, when it is what the
- * project would compile; else why not. Null for a module that has none - a
- * folder on this machine, or a package without prebuilt/ - which is compiled
- * as any plugin is.
+ * A module package's manifest, or why it cannot be used. Null for a module
+ * that has none - a folder on this machine, or a package without prebuilt/ -
+ * which is compiled as any plugin is.
  */
-export function prebuiltOf(pkg: ModulePackage, system: System, sources: Sources): PrebuiltUse | null {
+function manifestOf(pkg: ModulePackage): PrebuiltManifest | { why: string } | null {
 	const file = join(pkg.dir, PREBUILT_DIR, MANIFEST);
 	if (!fromRegistry(pkg.dir) || !existsSync(file)) return null;
 	const named = `${pkg.short} ${pkg.version}`;
-	let manifest: PrebuiltManifest;
 	try {
-		manifest = JSON.parse(readFileSync(file, 'utf8'));
+		const manifest = JSON.parse(readFileSync(file, 'utf8')) as PrebuiltManifest;
+		return manifest.format === FORMAT ? manifest : { why: `${named} comes compiled for another build of amxts` };
 	} catch {
 		return { why: `${named}: its ${PREBUILT_DIR}/${MANIFEST} cannot be read` };
 	}
-	if (manifest.format !== FORMAT) return { why: `${named} comes compiled for another build of amxts` };
+}
+
+/**
+ * The prebuilt .aot of a module from npm for `system`, when it is what the
+ * project would compile; else why not. Null for a module that has none.
+ */
+export function prebuiltOf(pkg: ModulePackage, system: System, sources: Sources): PrebuiltUse | null {
+	const manifest = manifestOf(pkg);
+	if (!manifest || 'why' in manifest) return manifest;
+	const named = `${pkg.short} ${pkg.version}`;
 	const aot = manifest.systems[system];
 	if (!aot) return { why: `${named} comes compiled for ${Object.keys(manifest.systems).map(each => SYSTEM_NAME[each as System]).join(' and ')}, not ${SYSTEM_NAME[system]}` };
+	const why = mismatch(manifest, pkg, sources);
+	if (why) return { why };
+	for (const [name, declared] of Object.entries(manifest.forwards)) {
+		if (declarationOf(name) !== declared) return { why: `the includes declare the forward ${name} otherwise than when ${named} was built` };
+	}
+
+	const bytes = new Uint8Array(readFileSync(join(pkg.dir, aot.file)));
+	if (sha256(bytes) !== aot.sha256) return { why: `${named}: ${aot.file} is not the file its manifest lists` };
+	return { aot: bytes, natives: manifest.natives, beside: manifest.beside };
+}
+
+/**
+ * The surface a module from npm came with (scripts/shared-modules.ts), when
+ * it is what the project would make; else why not. Null for a module that
+ * has none.
+ */
+export function prebuiltSurface(pkg: ModulePackage, sources: Sources): { surface: ModuleSurface } | { why: string } | null {
+	const manifest = manifestOf(pkg);
+	if (!manifest || 'why' in manifest) return manifest;
+	if (!manifest.surface) return { why: `${pkg.short} ${pkg.version} comes without its analysis` };
+	const why = mismatch(manifest, pkg, sources);
+	return why ? { why } : { surface: manifest.surface };
+}
 
+/** Why the project would not compile a module as its manifest says it was: another core or package, other options, a file in the way; null when it would. */
+function mismatch(manifest: PrebuiltManifest, pkg: ModulePackage, sources: Sources): string | null {
+	const named = `${pkg.short} ${pkg.version}`;
 	for (const [name, built] of Object.entries(manifest.from)) {
 		const have = installed(name, sources);
-		if (!have) return { why: `${named} was built with ${name}, which the project does not have` };
-		if (have.version !== built.version) return { why: `${named} was built for ${name} ${built.version}, the project has ${have.version}` };
+		if (!have) return `${named} was built with ${name}, which the project does not have`;
+		if (have.version !== built.version) return `${named} was built for ${name} ${built.version}, the project has ${have.version}`;
 		if (!fromRegistry(have.dir) && have.hash() !== built.hash) {
-			return { why: `${named} was built from another ${name} ${built.version} than the one in ${posix(relative(sources.project.dir, have.dir)) || '.'}` };
+			return `${named} was built from another ${name} ${built.version} than the one in ${posix(relative(sources.project.dir, have.dir)) || '.'}`;
 		}
 	}
 	for (const [name, options] of Object.entries(manifest.options)) {
 		const module = sources.project.packages.find(each => each.name === name)!;
 		if (JSON.stringify(optionsOf(sources.project, module.definition)) !== JSON.stringify(options)) {
-			return { why: `${named} was built with ${name === pkg.name ? 'its' : `${module.short}'s`} default options, and amxts.config.ts sets ${module.definition.configKey}` };
+			return `${named} was built with ${name === pkg.name ? 'its' : `${module.short}'s`} default options, and amxts.config.ts sets ${module.definition.configKey}`;
 		}
 	}
-	for (const [name, declared] of Object.entries(manifest.forwards)) {
-		if (declarationOf(name) !== declared) return { why: `the includes declare the forward ${name} otherwise than when ${named} was built` };
-	}
 	const own = resolve(sources.project.pluginsDir) !== resolve(CORE_PLUGINS);
 	const shadow = own ? manifest.places.find(place => existsSync(join(sources.project.pluginsDir, place))) : undefined;
-	if (shadow) return { why: `${posix(relative(sources.project.dir, join(sources.project.pluginsDir, shadow)))} takes the place of a file ${named} was built from` };
-
-	const bytes = new Uint8Array(readFileSync(join(pkg.dir, aot.file)));
-	if (sha256(bytes) !== aot.sha256) return { why: `${named}: ${aot.file} is not the file its manifest lists` };
-	return { aot: bytes, natives: manifest.natives, beside: manifest.beside };
+	if (shadow) return `${posix(relative(sources.project.dir, join(sources.project.pluginsDir, shadow)))} takes the place of a file ${named} was built from`;
+	return null;
 }
 
 /** The `new Forward<...>("name")` calls of a package whose arguments are not all text: their names. */
@@ -255,6 +295,7 @@ async function prebuild(pkg: ModulePackage, sources: Sources): Promise<string> {
 		natives,
 		beside: nativesBeside(natives),
 		systems,
+		surface: await moduleSurface(CORE_PLUGINS, pkg.short),
 	};
 	writeFileSync(join(dir, MANIFEST), `${JSON.stringify(manifest, null, '\t')}\n`);
 	const sizes = SYSTEMS.map(system => `${SYSTEM_NAME[system]} ${(systems[system]!.size / 1024).toFixed(0)} KB`).join(', ');
@@ -264,5 +305,6 @@ async function prebuild(pkg: ModulePackage, sources: Sources): Promise<string> {
 if (import.meta.main) {
 	const project = loadProject(process.cwd());
 	if (project.problems.length) throw new Error(project.problems.join('\n'));
-	for (const pkg of project.modules) log.success(await prebuild(pkg, sourcesFor(CORE_PLUGINS)));
+	// A library has no owner to compile: it is compiled into the plugins that import it.
+	for (const pkg of shared(project.modules)) log.success(await prebuild(pkg, sourcesFor(CORE_PLUGINS)));
 }

package/scripts/prepare.ts

@@ -5,19 +5,22 @@
 //                            the line it prints only under --debug)
 //
 // The project's own tsconfig.json extends it: { "extends": "./.amxts/tsconfig.json" }.
-// It says what the build says - `~/` is the project's plugins over the
-// core's as/, "@amxts/core" is the facade, a module package is its module
-// file - and it takes in amxts.config.ts and every module the config lists, so
-// that the options each module declares (ModuleOptions) type the config.
-// Beside it, imports.d.ts makes what plugins use without an import - the
-// facade's API, the modules' namespaces - globals for the editor
-// (scripts/auto-imports.ts).
+// It says what the build says - `~/` is the project's plugins folder,
+// "@amxts/core" and its entries are the core's API, a module package is its
+// module file - and it takes in amxts.config.ts and every module the config
+// lists, so that the options each module declares (ModuleOptions) type the
+// config. Beside it, imports.d.ts makes what plugins use without an import -
+// the facade's API, the modules' namespaces - globals for the editor
+// (scripts/auto-imports.ts), and api/ holds the API with its tooltips in the
+// language AMXTS_DOCS_LANG picks, when that is not English
+// (scripts/editor-api.ts): the installed packages are never written to.
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, relative } from 'node:path';
-import { applyProject, docsLang } from './apply-docs';
+import { applySources, docsLang, moduleSources, registerFilter } from './apply-docs';
 import { importsDeclaration } from './auto-imports';
-import { CONFIG_FILE, CORE_DIR, CORE_PLUGINS, loadProject } from './project';
+import { editorApi } from './editor-api';
+import { CONFIG_FILE, CORE_DIR, CORE_ENTRIES, CORE_PLUGINS, loadProject, shared } from './project';
 import { c, debug, log } from './ui';
 
 function fail(message: string): void {
@@ -32,19 +35,18 @@ if (project.problems.length) {
 	process.exit(1);
 }
 
-// The hood's tooltips - the core's and the modules' - in the language .env
-// picks (AMXTS_DOCS_LANG), as the generated API has them. A core it cannot
-// write to keeps English: the editor still has words, only not these.
-let docs = '';
-try {
-	docs = await applyProject(project.dir, docsLang());
-} catch (error) {
-	fail(`docs: ${(error as Error).message}`);
-}
+const lang = docsLang();
 
 // A module's own folder, without a project config, has its own tsconfig.json
-// (extending the core's as/tsconfig.json): nothing to write there.
-if (!project.config && project.packages.some(pkg => pkg.dir === project.dir)) process.exit(0);
+// (extending the core's as/tsconfig.json): nothing to write there but its
+// own words, in place - its repository's filter stores them in English.
+const own = project.config ? null : project.packages.find(pkg => pkg.dir === project.dir);
+if (own) {
+	registerFilter(own.dir);
+	const changed = await applySources(moduleSources(own), lang);
+	if (!process.argv.includes('--quiet') || debug()) log.step(c.dim(`docs: ${lang}, ${changed.length ? `${changed.length} file(s) rewritten` : 'up to date'}`));
+	process.exit(0);
+}
 
 const out = join(project.dir, '.amxts');
 /** A path as the generated config writes it: from .amxts/, with forward slashes. */
@@ -74,19 +76,28 @@ function installed(name: string, dir: string) {
 	}
 }
 
-// `~/` is not a package. The core and the modules are, once installed; one
-// that is not (a module in modules/, a core run from elsewhere) is mapped to
-// its file, as the build finds it.
+// `~/` is the project's plugins folder, not a package. The core and the
+// modules are, once installed; one that is not (a module in modules/, a core
+// run from elsewhere) is mapped to its file, as the build finds it. In a
+// language other than English they are all mapped to the copy with its
+// words, which the build never reads.
 const paths: Record<string, string[]> = {
-	'~/*': [...new Set([`${from(project.pluginsDir)}/*`, `${from(CORE_PLUGINS)}/*`])],
+	'~/*': [`${from(project.pluginsDir)}/*`],
 };
 if (!installed('@amxts/core', CORE_DIR)) {
-	paths['@amxts/core'] = [from(join(CORE_PLUGINS, 'facade.ts'))];
-	paths['@amxts/core/*'] = [`${from(CORE_PLUGINS)}/*`];
+	for (const [name, file] of Object.entries(CORE_ENTRIES)) paths[name] = [from(join(CORE_PLUGINS, file))];
 }
 for (const pkg of project.modules) {
 	if (!installed(pkg.name, pkg.dir)) paths[pkg.name] = [from(pkg.module)];
 }
+let api: Awaited<ReturnType<typeof editorApi>> = null;
+try {
+	api = await editorApi(project, lang, join(out, 'api'));
+} catch (error) {
+	fail(`docs: ${(error as Error).message}`);
+}
+for (const [name, file] of Object.entries(api?.paths ?? {})) paths[name] = [from(file)];
+const docs = lang === 'en' ? '' : `docs: ${lang}${api?.written ? ', .amxts/api written' : ''}`;
 
 const tsconfig = {
 	extends: from(assembly),
@@ -104,12 +115,15 @@ const tsconfig = {
 		// plugin declares is its own, never a global another plugin's name
 		// collides with.
 		moduleDetection: 'force',
+		// `catch (error)` reads `error.message` as the compiler takes it: the
+		// base config's strict mode would make the caught value `unknown`.
+		useUnknownInCatchVariables: false,
 		paths,
 	},
 	include: [
 		`${from(project.pluginsDir)}/**/*.ts`,
 		from(join(project.dir, CONFIG_FILE)),
-		`${from(CORE_PLUGINS)}/*.d.ts`,
+		`${from(api?.core ?? CORE_PLUGINS)}/*.d.ts`,
 		'./modules.d.ts',
 		'./imports.d.ts',
 	],
@@ -120,7 +134,7 @@ writeFileSync(join(out, 'tsconfig.json'), `${JSON.stringify(tsconfig, null, '\t'
 writeFileSync(join(out, 'modules.d.ts'), [
 	'// GENERATED by amxts prepare: the modules amxts.config.ts lists, for the',
 	'// options each one adds to ModuleOptions.',
-	...project.modules.map(pkg => `import "${pkg.name}";`),
+	...shared(project.modules).map(pkg => `import "${pkg.name}";`),
 	'',
 	'export {};',
 	'',

package/scripts/project.ts

@@ -11,6 +11,10 @@
 //
 //   "amxts": { "module": "src/index.ts", "natives": "src/natives.ts", "include": "include/menu_core.inc" }
 //
+// - or, for a library, `"amxts": { "module": "src/index.ts", "library": true }`:
+// code compiled into each plugin that imports it, as an npm library is, with
+// no instance on the server, no owner, no proxy and no defineModule.
+//
 // and in its module file, with the global defineModule:
 //
 //   export default defineModule<MenuCoreOptions>({     // src/index.ts
@@ -52,6 +56,7 @@ import ts from 'typescript';
 import { coreImports, importedName, importTable, withAutoImports } from './auto-imports';
 import { includeDirs } from './includes';
 import { existsSync, readdirSync, readFileSync, statSync } from './tracked-fs';
+import { typedCommands } from './typed-commands';
 import { typedConfigs } from './typed-configs';
 
 /** The core's folder: the package this file ships in. */
@@ -123,6 +128,12 @@ export interface ModulePackage {
 	dir: string;
 	/** The module file: the API plugins import. */
 	module: string;
+	/**
+	 * `"library": true`: compiled into each plugin that imports it, like an
+	 * npm library - no instance on the server, so no owner, no proxy, no
+	 * defineModule, natives, include or test kit.
+	 */
+	library: boolean;
 	/**
 	 * Its Pawn natives: the plugin that owns the module - its one instance on
 	 * the server. Without one, the build generates an owner that only runs it.
@@ -375,7 +386,16 @@ export function readPackage(dir: string): ModulePackage | null {
 	const include = typeof amxts.include === 'string' ? resolve(dir, amxts.include) : null;
 
 	const short = String(json.name).replace(/^@[^/]+\//, '');
-	const definition = readDefinition(module) ?? { name: null, configKey: null, requires: [], defaults: {}, imports: [], optionsType: null, hasSetup: false };
+	const library = amxts.library === true;
+	const owned = ['natives', 'include', 'contract', 'testing'].filter(key => amxts[key] !== undefined);
+	if (library && owned.length) {
+		throw new Error(`${json.name}: a library is compiled into each plugin that imports it and runs no plugin of its own - it has no ${owned.map(key => `"${key}"`).join(', ')} (package.json, "amxts")`);
+	}
+	const read = readDefinition(module);
+	if (library && read) {
+		throw new Error(`${json.name}: a library has no defineModule - no options, no instance on the server; plugins import what it exports. Leave "library": true out to make it a module`);
+	}
+	const definition = read ?? { name: null, configKey: null, requires: [], defaults: {}, imports: [], optionsType: null, hasSetup: false };
 	if (definition.name && definition.name !== short) {
 		throw new Error(`${json.name}: defineModule's meta.name is "${definition.name}" - it is the package's name without the scope, "${short}"`);
 	}
@@ -387,7 +407,7 @@ export function readPackage(dir: string): ModulePackage | null {
 	if (include && amxts.contract === true && !existsSync(include)) throw new Error(`${json.name}: its contract ${amxts.include} is not there (package.json, "amxts".include)`);
 	const testing = typeof amxts.testing === 'string' ? resolve(dir, amxts.testing) : null;
 	if (testing && !existsSync(testing)) throw new Error(`${json.name}: its test kit ${amxts.testing} is not there (package.json, "amxts".testing)`);
-	return { name: json.name, short, dir: resolve(dir), module, natives, include, contract: amxts.contract === true, testing, version: String(json.version ?? '0.0.0'), description: String(json.description ?? ''), definition };
+	return { name: json.name, short, dir: resolve(dir), module, library, natives, include, contract: amxts.contract === true, testing, version: String(json.version ?? '0.0.0'), description: String(json.description ?? ''), definition };
 }
 
 /**
@@ -614,7 +634,30 @@ export function optionsOf(project: Project, definition: ModuleDefinition): Optio
  * Everything in the core's as/ that is not a plugin: the facade a plugin
  * imports, the kit a module imports and the generated native layer under them.
  */
-export const NOT_PLUGINS = new Set(['facade.ts', 'kit.ts', 'promise.ts', 'vector.ts', 'effects.ts', 'fs.ts', 'os.ts', 'natives.ts', 'remote.ts', 'constants.ts', 'events.ts', 'entities.ts', 'flags.ts', 'hooks.ts']);
+export const NOT_PLUGINS = new Set(['facade.ts', 'kit.ts', 'promise.ts', 'vector.ts', 'effects.ts', 'fetch.ts', 'fs.ts', 'os.ts', 'natives.ts', 'remote.ts', 'constants.ts', 'events.ts', 'entities.ts', 'flags.ts', 'hooks.ts', 'hlds.ts']);
+
+/**
+ * The core's API a plugin imports, by the package's name, and its file in
+ * the core's as/ - its place in the tree. package.json's "exports" gives
+ * the same files to the editor.
+ */
+export const CORE_ENTRIES: Record<string, string> = {
+	'@amxts/core': 'facade.ts',
+	'@amxts/core/natives': 'natives.ts',
+	'@amxts/core/constants': 'constants.ts',
+	'@amxts/core/fs': 'fs.ts',
+	'@amxts/core/os': 'os.ts',
+	'@amxts/core/kit': 'kit.ts',
+	'@amxts/core/check': 'lib/check.ts',
+};
+
+/** Every place of the core's as/ in the tree: what `~/` must not reach from a plugin. */
+const CORE_PLACES = new Set([...NOT_PLUGINS, ...Object.values(CORE_ENTRIES), 'amxts.d.ts']);
+
+/** How a plugin names the core's file at a place: its entry, or the facade, which exports the rest. */
+export function coreEntryOf(place: string): string {
+	return Object.entries(CORE_ENTRIES).find(([, file]) => file === place)?.[0] ?? '@amxts/core';
+}
 
 /**
  * The project's own plugins: the .ts files at the top of its plugins folder.
@@ -629,8 +672,13 @@ export function projectPlugins(project: Project): string[] {
 		.map(f => join(project.pluginsDir, f));
 }
 
+/** The modules that run on the server - each in its owner plugin: every one but a library. */
+export function shared(modules: ModulePackage[]): ModulePackage[] {
+	return modules.filter(pkg => !pkg.library);
+}
+
 /** plugins.ini: the modules' owners in load order, then the project's plugins. */
-export function pluginList(project: Project, plugins: string[], modules = project.modules): string[] {
+export function pluginList(project: Project, plugins: string[], modules = shared(project.modules)): string[] {
 	const owners = modules.map(pkg => `${pkg.short}.aot`);
 	return [...owners, ...plugins.filter(plugin => !owners.includes(plugin))];
 }
@@ -641,11 +689,12 @@ export function pluginList(project: Project, plugins: string[], modules = projec
  * the files they import - with what those modules import and require, and
  * the ones `pawn` keeps for Pawn plugins, whose use no build can see.
  * Without amxts.config.ts every module is in use: a module's own
- * repository, testing itself.
+ * repository, testing itself. A library is never one: it is compiled into
+ * the plugins, and what it imports is reached through them.
  */
 export function modulesInUse(sources: Sources, plugins: string[]): ModulePackage[] {
 	const { project } = sources;
-	if (!project.config) return project.modules;
+	if (!project.config) return shared(project.modules);
 	const used = new Set(project.config.pawn ?? []);
 	const reached = new Set<string>();
 	const reach = (source: string) => sources.reach(join(sources.root, sources.entry(source)), reached);
@@ -653,7 +702,7 @@ export function modulesInUse(sources: Sources, plugins: string[]): ModulePackage
 	// A module in use brings what its owner imports and what it requires.
 	for (let before = -1; used.size !== before;) {
 		before = used.size;
-		for (const pkg of project.modules) {
+		for (const pkg of shared(project.modules)) {
 			const imported = reached.has(join(sources.root, 'modules', `${pkg.short}.ts`));
 			if (!imported && !used.has(pkg.name)) continue;
 			reach(sources.ownerSource(pkg));
@@ -661,7 +710,7 @@ export function modulesInUse(sources: Sources, plugins: string[]): ModulePackage
 			for (const required of pkg.definition.requires) used.add(required);
 		}
 	}
-	return project.modules.filter(pkg => used.has(pkg.name));
+	return shared(project.modules).filter(pkg => used.has(pkg.name));
 }
 
 // ---------------------------------------------------------------- the tree
@@ -772,7 +821,7 @@ export class Sources {
 	generated(path: string): string | null {
 		const owner = this.rel(path).match(/^([^/]+)\.ts$/);
 		const pkg = owner ? this.moduleNamed(owner[1]) : null;
-		if (!pkg || pkg.natives || this.real(path)) return null;
+		if (!pkg || pkg.natives || pkg.library || this.real(path)) return null;
 		return [
 			`// GENERATED by scripts/project.ts: the plugin that runs ${pkg.name} - its one instance on the server.`,
 			'import { plugin } from "~/facade";',
@@ -811,7 +860,7 @@ export class Sources {
 		return this.rel(this.place(real));
 	}
 
-	/** Each file's typed configs, made once a compile (scripts/typed-configs.ts). */
+	/** Each file's typed configs and commands, made once a compile (scripts/typed-configs.ts, scripts/typed-commands.ts). */
 	private typed = new Map<string, { text: string; out: string }>();
 
 	/**
@@ -827,14 +876,14 @@ export class Sources {
 		if (known && known.text === text) return known.out;
 
 		const display = posix(relative(this.project.dir, this.real(at) ?? at));
-		const made = typedConfigs(at, display, text, (from, spec) => {
+		const reader = (from: string, spec: string) => {
 			const file = this.resolveImport(from, spec);
 			const found = file ? this.readPlain(file) : null;
 			return file && found !== null ? { path: file, text: found } : null;
-		});
-		for (const problem of made.problems) {
-			if (!this.problems.includes(problem)) this.problems.push(problem);
-		}
+		};
+		const configs = typedConfigs(at, display, text, reader);
+		const made = typedCommands(at, display, configs.text, reader);
+		for (const problem of [...configs.problems, ...made.problems]) this.problem(problem);
 		this.typed.set(at, { text, out: made.text });
 		return made.text;
 	}
@@ -843,8 +892,21 @@ export class Sources {
 	private readPlain(path: string): string | null {
 		const real = this.real(path);
 		if (!real) return this.generated(path);
+		const raw = readFileSync(real, 'utf8');
+		const at = resolve(path);
+		const known = this.plain.get(at);
+		if (known?.raw === raw) return known.out;
+		const out = this.plainOf(path, real, raw);
+		this.plain.set(at, { raw, out });
+		return out;
+	}
+
+	/** Each file's plain text, made once a compile: a build reaches the facade from every plugin. */
+	private plain = new Map<string, { raw: string; out: string }>();
+
+	private plainOf(path: string, real: string, raw: string): string {
 		// A module's ModuleOptions augmentation may be in any of its files (types.ts).
-		const text = withoutOptionsAugmentation(this.rewrite(real, this.withImports(real, readFileSync(real, 'utf8'))));
+		const text = withoutOptionsAugmentation(this.rewrite(real, this.withImports(real, raw)));
 		const pkg = this.project.modules.find(each => each.module === real);
 		if (pkg) return moduleSource(real, text, optionsOf(this.project, pkg.definition));
 		if (/^modules\/[^/]+\.ts$/.test(this.rel(path)) && text.includes('defineModule')) {
@@ -854,10 +916,49 @@ export class Sources {
 		return text;
 	}
 
+	private problem(text: string) {
+		if (!this.problems.includes(text)) this.problems.push(text);
+	}
+
+	/**
+	 * Whether a file on disk is the core's as/: the hood, which names its
+	 * places by `~/`. On a server the plugins folder holds them, by place.
+	 */
+	private isCore(real: string): boolean {
+		if (inside(CORE_PLUGINS, real)) return true;
+		const own = resolve(this.project.pluginsDir) !== resolve(CORE_PLUGINS) && inside(this.project.pluginsDir, real);
+		return !own && !this.packageOf(real) && CORE_PLACES.has(this.rel(this.place(real)));
+	}
+
+	/**
+	 * `~/` in a plugin or a module is the project's own files: the core's API
+	 * goes by `@amxts/core/<entry>` and a module package by its name. What
+	 * to write instead, or null for a file of the project's own.
+	 */
+	private notOwn(real: string, spec: string): string | null {
+		const file = this.resolveImport(this.place(real), spec);
+		const target = file ? this.real(file) : null;
+		if (!target) return file && this.generated(file) ? '' : null;
+		const pkg = this.packageOf(target);
+		if (pkg) return pkg.module === target ? pkg.name : `${pkg.name}/${posix(relative(pkg.dir, target)).replace(/\.ts$/, '')}`;
+		return this.isCore(target) ? coreEntryOf(this.rel(file!)) : null;
+	}
+
 	/** A specifier as the tree has it: a package by its place, a relative import inside a package likewise. */
 	private specifier(real: string, spec: string): string {
-		if (spec === '@amxts/core') return '~/facade';
-		if (spec.startsWith('@amxts/core/')) return `~/${spec.slice('@amxts/core/'.length)}`;
+		const display = () => posix(relative(this.project.dir, real));
+		if (spec === '@amxts/core' || spec.startsWith('@amxts/core/')) {
+			const place = CORE_ENTRIES[spec];
+			if (place) return `~/${place.replace(/\.ts$/, '')}`;
+			this.problem(`${display()}: imports ${spec}, which @amxts/core does not export - its API is ${Object.keys(CORE_ENTRIES).join(', ')}`);
+			return spec;
+		}
+
+		if (spec.startsWith('~/')) {
+			const instead = this.isCore(real) ? null : this.notOwn(real, spec);
+			if (instead !== null) this.problem(`${display()}: ${spec} is not a file of the project - \`~/\` is the plugins folder; import ${instead || 'the module by its package name'} (npx amxts upgrade rewrites these imports)`);
+			return spec;
+		}
 
 		if (spec.startsWith('.')) {
 			const pkg = this.packageOf(real);
@@ -873,7 +974,6 @@ export class Sources {
 			return `~/modules/${pkg.short}/${posix(relative(pkg.dir, target))}`;
 		}
 
-		if (spec.startsWith('~/')) return spec;
 		const name = spec.match(/^(@[^/]+\/[^/]+|[^@/][^/]*)/)?.[1];
 		const active = this.project.modules.find(pkg => pkg.name === name);
 		if (active) return spec === active.name ? `~/modules/${active.short}` : `~/modules/${active.short}/${spec.slice(name!.length + 1)}`;
@@ -885,7 +985,7 @@ export class Sources {
 	}
 
 	rewrite(real: string, text: string): string {
-		if (!text.includes('@') && !(this.packageOf(real) && /["']\.\.?\//.test(text))) return text;
+		if (!text.includes('@') && !text.includes('~/') && !(this.packageOf(real) && /["']\.\.?\//.test(text))) return text;
 		return text.replace(IMPORT, (whole, head: string, quote: string, spec: string) => {
 			const next = this.specifier(real, spec);
 			return next === spec ? whole : `${head}${quote}${next}${quote}`;

package/scripts/reapi-events.ts

@@ -0,0 +1,98 @@
+// The game events reapi alone delivers - ReGameDLL's and ReHLDS's own
+// functions - and the build's refusal of a listener for one nothing else
+// hears, in a project for plain HLDS.
+//
+// A server without reapi hears every other game event through Ham Sandwich
+// (as/hooks.ts picks it once, by hasModule), and many of these through
+// another stock hook (scripts/hlds-events.ts); a listener for one of the rest
+// is only a line in its console. A project whose amxts.config.ts says
+// `target: "hlds"` has said there is no reapi, so the build stops at such a
+// listener instead, with the file and the line.
+import { join } from 'node:path';
+// @ts-ignore - shipped as JavaScript, with types beside it we do not need here
+import * as asc from '../runtime/deps/assemblyscript/dist/assemblyscript.js';
+import { HEARD } from './hlds-events';
+import { CORE_PLUGINS } from './project';
+import { readFileSync } from './tracked-fs';
+
+let cached: { text: string; events: Set<string> } | null = null;
+
+/**
+ * The events of as/hooks.ts's GameEventMap reapi alone delivers: an event
+ * class with no Ham Sandwich function behind it (`private static readonly
+ * ham`) is a hookchain's alone.
+ */
+export function reapiEvents(hooksText = readFileSync(join(CORE_PLUGINS, 'hooks.ts'), 'utf8')): Set<string> {
+	if (cached?.text === hooksText) return cached.events;
+
+	const reapiClasses = new Set<string>();
+	for (const [, name, body] of hooksText.matchAll(/^export class (\w+) extends HookEvent \{\n([\s\S]*?)\n\}\n/gm)) {
+		if (!body.includes('private static readonly ham:')) reapiClasses.add(name);
+	}
+	const map = hooksText.slice(hooksText.indexOf('export interface GameEventMap'));
+	const events = new Set<string>();
+	for (const [, event, name] of map.slice(0, map.indexOf('\n}\n')).matchAll(/^\t(\w+): (\w+);/gm)) {
+		if (reapiClasses.has(name)) events.add(event);
+	}
+
+	cached = { text: hooksText, events };
+	return events;
+}
+
+/** The events reapi alone delivers that plain HLDS does not hear at all. */
+export function unheardEvents(hooksText?: string): Set<string> {
+	return new Set([...reapiEvents(hooksText)].filter(event => !Object.hasOwn(HEARD, event)));
+}
+
+/** The event a `game.addEventListener("name", ...)` call listens for; undefined for any other call. */
+function gameEventOf(call: any): string | undefined {
+	const callee = call.expression;
+	if (callee.kind !== asc.NodeKind.PropertyAccess || callee.property.text !== 'addEventListener') return undefined;
+	if (callee.expression.kind !== asc.NodeKind.Identifier || callee.expression.text !== 'game') return undefined;
+	const type = call.args[0];
+	return type?.kind === asc.NodeKind.Literal && type.literalKind === asc.LiteralKind.String ? type.value : undefined;
+}
+
+/** Calls `visit` on every node under `node`. */
+function walk(node: any, visit: (node: any) => void) {
+	if (Array.isArray(node)) {
+		for (const each of node) walk(each, visit);
+		return;
+	}
+	if (!node || typeof node !== 'object' || typeof node.kind !== 'number') return;
+	visit(node);
+	for (const key in node) {
+		if (key !== 'range') walk(node[key], visit);
+	}
+}
+
+/** The listeners in a compile's sources for an event plain HLDS does not hear, each where it is written. */
+export function reapiListeners(sources: any[], events = unheardEvents()): string[] {
+	const found: string[] = [];
+	for (const source of sources) {
+		if (source.normalizedPath.startsWith('~lib/') || !source.text.includes('addEventListener')) continue;
+		walk(source.statements, (node) => {
+			if (node.kind !== asc.NodeKind.Call) return;
+			const event = gameEventOf(node);
+			if (event === undefined || !events.has(event)) return;
+			const line = source.text.slice(0, node.range.start).split('\n').length;
+			found.push(`${source.normalizedPath}:${line}: "${event}" needs ReAPI, and amxts.config.ts's target is "hlds" - nothing on plain HLDS hears it. Listen for another event, or set target: "rehlds"`);
+		});
+	}
+	return found;
+}
+
+/** The transform that stops a plugin for plain HLDS at a listener nothing there could call. */
+function hldsTransform() {
+	return class {
+		afterParse(parser: any): void {
+			const problems = reapiListeners(parser.sources);
+			if (problems.length) throw new Error(problems.join('\n'));
+		}
+	};
+}
+
+/** What a project's target adds to a compile: for plain HLDS, the refusal of the events it does not hear. */
+export function targetTransforms(target: string | undefined) {
+	return target === 'hlds' ? [hldsTransform()] : [];
+}