opencode-agent-skills-md 1.0.1 → 1.1.0

package/dist/cli.mjs

@@ -0,0 +1,770 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+//#region src/cli/config.ts
+/** npm package name for this plugin. */
+const PLUGIN_NAME = "opencode-agent-skills-md";
+/** Filename used for the OpenCode global config (preferred). */
+const CONFIG_FILE_BASENAME = "opencode";
+/** Subdirectory under the user config root that holds `opencode.json`. */
+const OPENCODE_CONFIG_SUBDIR = "opencode";
+/**
+* Resolve the parent directory that holds the global OpenCode config.
+* `$OPENCODE_CONFIG_DIR` wins; otherwise we fall back to
+* `$HOME/.config/opencode` (or `os.homedir()` as a last-resort).
+*
+* Exposed separately so tests and the rotation helper can reuse it
+* without re-deriving the precedence rules.
+*/
+const resolveConfigDir = (env = process.env) => {
+	const explicit = env.OPENCODE_CONFIG_DIR;
+	if (typeof explicit === "string" && explicit.trim().length > 0) return explicit;
+	const home = env.HOME;
+	if (typeof home === "string" && home.trim().length > 0) return join(home, ".config", OPENCODE_CONFIG_SUBDIR);
+	return join(homedir(), ".config", OPENCODE_CONFIG_SUBDIR);
+};
+/**
+* Resolve the global OpenCode config file path.
+*
+* Precedence:
+*   1. If `$OPENCODE_CONFIG_DIR/opencode.json` exists, use it.
+*   2. Else if `$OPENCODE_CONFIG_DIR/opencode.jsonc` exists, use it.
+*   3. Else fall back to `$HOME/.config/opencode/opencode.json`, then `.jsonc`.
+*   4. If nothing exists, return the preferred target `.json` in the
+*      resolved directory so `install` knows where to create the file.
+*
+* `.json` always wins over `.jsonc` when both exist.
+*/
+const resolveGlobalConfigPath = (fs, env = process.env) => {
+	const primaryDir = resolveConfigDir(env);
+	const explicit = env.OPENCODE_CONFIG_DIR;
+	const hasExplicit = typeof explicit === "string" && explicit.trim().length > 0 && explicit !== primaryDir;
+	const fallbackDir = computeFallbackDir(env);
+	const json = (dir) => ({
+		path: join(dir, `${CONFIG_FILE_BASENAME}.json`),
+		format: "json"
+	});
+	const jsonc = (dir) => ({
+		path: join(dir, `${CONFIG_FILE_BASENAME}.jsonc`),
+		format: "jsonc"
+	});
+	const candidateFns = [json, jsonc];
+	const dirs = hasExplicit ? [primaryDir] : fallbackDir && fallbackDir !== primaryDir ? [primaryDir, fallbackDir] : [primaryDir];
+	for (const dir of dirs) for (const fn of candidateFns) {
+		const candidate = fn(dir);
+		if (fs.existsSync(candidate.path)) return {
+			path: candidate.path,
+			format: candidate.format,
+			existed: true
+		};
+	}
+	return {
+		...json(dirs[0]),
+		existed: false
+	};
+};
+const computeFallbackDir = (env) => {
+	const explicit = env.OPENCODE_CONFIG_DIR;
+	if (typeof explicit === "string" && explicit.trim().length > 0) return null;
+	const home = env.HOME;
+	if (typeof home === "string" && home.trim().length > 0) return join(home, ".config", OPENCODE_CONFIG_SUBDIR);
+	return join(homedir(), ".config", OPENCODE_CONFIG_SUBDIR);
+};
+/**
+* Strip JSONC-style comments and trailing commas, then parse with `JSON.parse`.
+*
+* Returns `{}` for empty input or whitespace-only input.
+* **Throws** on malformed JSON — callers must handle the error to avoid
+* silently overwriting a corrupt config with an empty one.
+*/
+const parseJsonc = (text) => {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) return {};
+	const stripped = stripJsoncComments(trimmed);
+	const parsed = JSON.parse(stripped);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("config root must be a JSON object");
+	return parsed;
+};
+/**
+* Internal: walk the input, dropping `// ...` and `/* ... * /` comments
+* while preserving everything inside string literals (including strings
+* that contain URL slashes). Trailing commas are removed after the
+* comment pass.
+*/
+const stripJsoncComments = (text) => {
+	let out = "";
+	let inString = false;
+	let escaped = false;
+	let i = 0;
+	const len = text.length;
+	while (i < len) {
+		const c = text[i];
+		if (inString) {
+			out += c;
+			if (escaped) escaped = false;
+			else if (c === "\\") escaped = true;
+			else if (c === "\"") inString = false;
+			i++;
+			continue;
+		}
+		if (c === "\"") {
+			inString = true;
+			out += c;
+			i++;
+			continue;
+		}
+		if (c === "/" && text[i + 1] === "/") {
+			i += 2;
+			while (i < len && text[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "/" && text[i + 1] === "*") {
+			i += 2;
+			while (i < len && !(text[i] === "*" && text[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		out += c;
+		i++;
+	}
+	let result = "";
+	let inStr = false;
+	let esc = false;
+	let j = 0;
+	const outLen = out.length;
+	while (j < outLen) {
+		const ch = out[j];
+		if (inStr) {
+			result += ch;
+			if (esc) esc = false;
+			else if (ch === "\\") esc = true;
+			else if (ch === "\"") inStr = false;
+			j++;
+			continue;
+		}
+		if (ch === "\"") {
+			inStr = true;
+			result += ch;
+			j++;
+			continue;
+		}
+		if (ch === ",") {
+			let k = j + 1;
+			while (k < outLen && /\s/.test(out[k])) k++;
+			if (k < outLen && /[}\]]/.test(out[k])) {
+				j = k;
+				continue;
+			}
+		}
+		result += ch;
+		j++;
+	}
+	return result;
+};
+/**
+* True when `entry` is a string that resolves to this plugin by base name.
+* Matches `opencode-agent-skills-md` and any `opencode-agent-skills-md@<spec>`
+* variant. Non-string entries (legacy object-form leftover) return false.
+*/
+const matchesPlugin = (entry) => {
+	if (typeof entry !== "string") return false;
+	const at = entry.indexOf("@");
+	return (at === -1 ? entry : entry.slice(0, at)) === PLUGIN_NAME;
+};
+/**
+* Coerce the raw value of `config.plugin` into a clean string array.
+*
+* Handles:
+*   - `undefined` / `null`                 → `[]`
+*   - array of strings (or mixed)          → only the string entries
+*   - the broken object form `{ "<name>": ... }` → the keys (in declaration order)
+*   - any other non-object, non-array shape → `[]` (doctor surfaces it)
+*/
+const normalizePlugin = (raw) => {
+	if (raw === void 0 || raw === null) return [];
+	if (Array.isArray(raw)) {
+		const out = [];
+		for (const item of raw) if (typeof item === "string") out.push(item);
+		return out;
+	}
+	if (typeof raw === "object") return Object.keys(raw);
+	return [];
+};
+/**
+* Dedupe the plugin list by base name (the part before the first `@`),
+* keeping the LAST occurrence of each base. Any `opencode-agent-skills-md`
+* entries are removed entirely so the install flow can append one fresh
+* entry at the end without leaving stale versions behind.
+*
+* Order is preserved for the surviving entries (last-wins per base).
+*/
+const dedupePlugins = (entries) => {
+	const filtered = [];
+	for (const entry of entries) if (!matchesPlugin(entry)) filtered.push(entry);
+	const byBase = /* @__PURE__ */ new Map();
+	for (const raw of filtered) {
+		if (typeof raw !== "string" || raw.length === 0) continue;
+		const at = raw.indexOf("@");
+		const base = at === -1 ? raw : raw.slice(0, at);
+		if (base.length === 0) continue;
+		byBase.set(base, raw);
+	}
+	return Array.from(byBase.values());
+};
+/**
+* Build the npm specifier we will write into `plugin[]`:
+* `"opencode-agent-skills-md"` when no version is supplied, otherwise
+* `"opencode-agent-skills-md@<version>"`. Empty / whitespace-only versions
+* are treated as "no version".
+*/
+const buildSpecifier = (version) => {
+	if (typeof version !== "string") return PLUGIN_NAME;
+	const trimmed = version.trim();
+	if (trimmed.length === 0) return PLUGIN_NAME;
+	return `${PLUGIN_NAME}@${trimmed}`;
+};
+/**
+* If `configPath` already exists, copy it next to itself as a timestamped
+* sibling and prune older CLI-created backups so at most `BACKUP_LIMIT`
+* survive (newest first). Returns the backup path, or `null` when no
+* backup was needed (file missing or not writable).
+*/
+const backupIfWritable = (configPath, fs) => {
+	if (!fs.existsSync(configPath)) return null;
+	const backupPath = join(dirname(configPath), `${basename(configPath)}.bak.${backupTimestamp(/* @__PURE__ */ new Date())}`);
+	fs.copyFileSync(configPath, backupPath);
+	try {
+		rotateBackups(configPath, 3, fs);
+	} catch {}
+	return backupPath;
+};
+/**
+* Prune CLI-created backups of `configPath`, keeping only the newest
+* `limit` siblings (lexical order on the timestamp suffix is fine because
+* the stamp is fixed-width and ISO-8601-derived).
+*/
+const rotateBackups = (configPath, limit, fs) => {
+	if (limit < 1) return;
+	const dir = dirname(configPath);
+	const prefix = `${basename(configPath)}.bak.`;
+	const backups = fs.readdirSync(dir).filter((name) => name.startsWith(prefix)).sort();
+	if (backups.length <= limit) return;
+	const toRemove = backups.slice(0, backups.length - limit);
+	for (const oldName of toRemove) fs.unlinkSync(join(dir, oldName));
+};
+/**
+* Internal: build a filesystem-safe, chronologically-sortable timestamp
+* for backup filenames. Format: `YYYYMMDDTHHmmssSSSZ` — fixed-width, no
+* colons (Windows-safe), and lexical-sortable from newest to oldest.
+*/
+const backupTimestamp = (date) => {
+	const pad = (n, w = 2) => String(n).padStart(w, "0");
+	return `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}T${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}${pad(date.getUTCMilliseconds(), 3)}Z`;
+};
+/**
+* Write `content` to `targetPath` via a temp sibling + rename. The
+* rename is atomic on POSIX (and best-effort on Windows), so a crashed
+* CLI never leaves a half-written config behind. Any parent directories
+* are created with `{ recursive: true }` so first-run installs Just Work.
+*/
+const writeAtomically = (targetPath, content, fs) => {
+	const dir = dirname(targetPath);
+	fs.mkdirSync(dir, { recursive: true });
+	const tmp = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+	try {
+		fs.writeFileSync(tmp, content);
+		fs.renameSync(tmp, targetPath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {}
+		throw err;
+	}
+};
+/**
+* Resolve the global config path, read it (if it exists), and parse it.
+* Missing files yield `config = {}` and `existed = false` so the install
+* flow can treat "fresh install" and "already installed" the same way.
+*
+* Malformed JSONC is surfaced via `LoadedConfig.parseError`. Commands MUST
+* check this field and abort instead of silently overwriting the user's
+* corrupt config with an empty one.
+*/
+const loadGlobalConfig = (fs, env = process.env) => {
+	const resolved = resolveGlobalConfigPath(fs, env);
+	if (!resolved.existed) return {
+		path: resolved.path,
+		config: {},
+		existed: false
+	};
+	const raw = fs.readFileSync(resolved.path);
+	try {
+		return {
+			path: resolved.path,
+			config: parseJsonc(raw),
+			existed: true
+		};
+	} catch (err) {
+		return {
+			path: resolved.path,
+			config: {},
+			existed: true,
+			parseError: err.message
+		};
+	}
+};
+//#endregion
+//#region src/cli/real-fs.ts
+/**
+* Build a `CliFs` that delegates to `node:fs`. All methods are sync; the
+* CLI is short-lived and never benefits from async I/O.
+*/
+const createRealFs = () => ({
+	readFileSync: (path) => readFileSync(path, "utf8"),
+	writeFileSync: (path, content) => {
+		writeFileSync(path, content);
+	},
+	renameSync: (from, to) => {
+		renameSync(from, to);
+	},
+	copyFileSync: (from, to) => {
+		copyFileSync(from, to);
+	},
+	unlinkSync: (path) => {
+		unlinkSync(path);
+	},
+	mkdirSync: (path, opts) => {
+		mkdirSync(path, opts);
+	},
+	readdirSync: (path) => readdirSync(path),
+	existsSync: (path) => existsSync(path)
+});
+//#endregion
+//#region src/cli/install.ts
+const JSON_INDENT$1 = 2;
+/**
+* Run `oas install` against the global OpenCode config.
+*
+* Steps: load → normalize → drop existing oas variants → dedupe surviving
+* entries → append one requested specifier → backup → atomic write. The
+* backup is a timestamped sibling of the config file; rotation to
+* `BACKUP_LIMIT` is handled inside `backupIfWritable`.
+*
+* Idempotency: re-running with the same specifier resolves to a `noop`
+* result without touching disk. A malformed config triggers an error so
+* the user can fix the JSONC instead of silently losing it to an empty
+* overwrite.
+*/
+const runInstall = (opts = {}, fs = createRealFs()) => {
+	const specifier = buildSpecifier(opts.version);
+	const loaded = loadGlobalConfig(fs);
+	if (loaded.parseError) throw new Error(`oas: config file is malformed JSON — aborting to avoid data loss.\n  path:  ${loaded.path}\n  error: ${loaded.parseError}\nFix the JSON error, or delete the file and re-run to create a fresh config.`);
+	const config = { ...loaded.config };
+	const existing = normalizePlugin(config.plugin);
+	const finalPlugins = [...dedupePlugins(existing.filter((entry) => !matchesPlugin(entry))), specifier];
+	if (!opts.dryRun && JSON.stringify(finalPlugins) === JSON.stringify(existing)) {
+		console.log(`✓ Already installed (${specifier}) at ${loaded.path}`);
+		return {
+			status: "noop",
+			path: loaded.path,
+			specifier,
+			backup: null
+		};
+	}
+	config.plugin = finalPlugins;
+	if (opts.dryRun) {
+		console.log(`[dry-run] Would write to ${loaded.path}:`);
+		console.log(JSON.stringify(config, null, JSON_INDENT$1));
+		return {
+			status: "planned",
+			path: loaded.path,
+			specifier,
+			backup: null
+		};
+	}
+	const backup = backupIfWritable(loaded.path, fs);
+	writeAtomically(loaded.path, JSON.stringify(config, null, JSON_INDENT$1), fs);
+	console.log(`✓ Installed ${specifier}`);
+	console.log(`  config: ${loaded.path}`);
+	if (backup) console.log(`  backup: ${backup}`);
+	return {
+		status: "wrote",
+		path: loaded.path,
+		specifier,
+		backup
+	};
+};
+//#endregion
+//#region src/cli/status.ts
+const formatFromPath = (path) => path.endsWith(".jsonc") ? "jsonc" : "json";
+/**
+* Read-only status probe. Prints a human-readable report to stdout and
+* returns the same data as a structured result so callers (including
+* `main.ts` and tests) can consume it without parsing the message.
+*/
+const runStatus = (fs = createRealFs()) => {
+	const loaded = loadGlobalConfig(fs);
+	const plugins = normalizePlugin(loaded.config.plugin);
+	const oasEntries = plugins.filter(matchesPlugin);
+	const extras = plugins.filter((entry) => !matchesPlugin(entry));
+	const format = formatFromPath(loaded.path);
+	console.log(`Config path:    ${loaded.path}`);
+	console.log(`Format:         ${format}`);
+	console.log(`Exists on disk: ${loaded.existed ? "yes" : "no (will be created on install)"}`);
+	if (oasEntries.length === 0) {
+		console.log(`Installed:      no`);
+		return {
+			installed: false,
+			path: loaded.path,
+			format,
+			specifier: null,
+			extras
+		};
+	}
+	const specifier = oasEntries[0] ?? null;
+	console.log(`Installed:      yes`);
+	console.log(`Specifier:      ${specifier}`);
+	if (extras.length > 0) console.log(`Other plugins:  ${extras.join(", ")}`);
+	return {
+		installed: true,
+		path: loaded.path,
+		format,
+		specifier,
+		extras
+	};
+};
+/**
+* Health checks. The function does not exit on its own — it returns a
+* `DoctorResult` and `main.ts` maps `ok === false` to exit code 1.
+*/
+const runDoctor = (fs = createRealFs(), env = process.env) => {
+	const issues = [];
+	const warnings = [];
+	const info = [];
+	const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+	if (!Number.isFinite(nodeMajor) || nodeMajor < 18) issues.push(`Node ${process.versions.node} detected — ${PLUGIN_NAME} requires Node >= 18`);
+	else info.push(`Node ${process.versions.node} OK`);
+	const loaded = loadGlobalConfig(fs, env);
+	const format = formatFromPath(loaded.path);
+	info.push(`Config path: ${loaded.path}`);
+	info.push(`Config format: ${format}`);
+	if (!loaded.existed) warnings.push(`Config file does not exist yet — install will create it`);
+	const rawPlugin = loaded.config.plugin;
+	if (rawPlugin === void 0 || rawPlugin === null) info.push(`Plugin entries: 0`);
+	else if (!(Array.isArray(rawPlugin) || typeof rawPlugin === "object")) issues.push(`config.plugin is neither array nor object — install will reset it`);
+	else {
+		const plugins = normalizePlugin(rawPlugin);
+		info.push(`Plugin entries: ${plugins.length}`);
+		const oasCount = plugins.filter(matchesPlugin).length;
+		if (oasCount > 1) warnings.push(`${oasCount} ${PLUGIN_NAME} entries present — install will dedupe`);
+	}
+	try {
+		const dir = dirname(loaded.path);
+		try {
+			if (statSync(dir).isDirectory()) try {
+				accessSync(dir, constants.W_OK);
+				info.push(`Config directory writable: ${dir}`);
+			} catch {
+				warnings.push(`Config directory ${dir} is not writable`);
+			}
+			else issues.push(`${dir} exists but is not a directory`);
+		} catch {
+			warnings.push(`Config directory ${dir} does not exist yet — will be created on first install`);
+		}
+	} catch {}
+	for (const line of info) console.log(`  ✓ ${line}`);
+	for (const line of warnings) console.warn(`  ! ${line}`);
+	for (const line of issues) console.error(`  ✗ ${line}`);
+	const ok = issues.length === 0;
+	if (ok) console.log(`\n✓ Doctor: all checks passed`);
+	else console.log(`\n✗ Doctor: ${issues.length} issue(s) found`);
+	return {
+		ok,
+		issues,
+		warnings,
+		info
+	};
+};
+//#endregion
+//#region src/cli/uninstall.ts
+const JSON_INDENT = 2;
+/** Resolve `$HOME` (or `os.homedir()` as last resort) for purge paths. */
+const homeRoot = (env = process.env) => {
+	const home = env.HOME;
+	if (typeof home === "string" && home.trim().length > 0) return home;
+	return homedir();
+};
+/** Bun/npm-style cache path where the plugin gets installed at runtime. */
+const cachePath = (env = process.env) => join(homeRoot(env), ".cache", "opencode", "node_modules", PLUGIN_NAME);
+/** Plugin's own XDG config dir (separate from the OpenCode config it edits). */
+const pluginConfigPath = (env = process.env) => join(homeRoot(env), ".config", PLUGIN_NAME);
+/**
+* Best-effort recursive delete. Returns the path on success or `null` when
+* the target was missing (we don't want to fail the whole command if the
+* user never ran `install` to create these dirs in the first place).
+*/
+const purgeDir = (path) => {
+	try {
+		rmSync(path, {
+			recursive: true,
+			force: true
+		});
+		return path;
+	} catch {
+		return null;
+	}
+};
+const runUninstall = (opts = {}, fs = createRealFs()) => {
+	const loaded = loadGlobalConfig(fs);
+	if (loaded.parseError) throw new Error(`oas: config file is malformed JSON — aborting to avoid data loss.\n  path:  ${loaded.path}\n  error: ${loaded.parseError}\nFix the JSON error, or delete the file and re-run.`);
+	const config = { ...loaded.config };
+	const existing = normalizePlugin(config.plugin);
+	const removed = existing.filter(matchesPlugin);
+	const remaining = existing.filter((entry) => !removed.includes(entry));
+	const purgeCandidates = opts.purge ? [cachePath(), pluginConfigPath()] : [];
+	const purged = [];
+	const plannedPurge = [];
+	if (opts.purge && opts.dryRun) plannedPurge.push(...purgeCandidates);
+	if (removed.length === 0 && purgeCandidates.length === 0) {
+		console.log(`✓ Not installed: ${PLUGIN_NAME} not found in ${loaded.path}`);
+		return {
+			status: "noop",
+			path: loaded.path,
+			removed: [],
+			purged: []
+		};
+	}
+	if (removed.length > 0) if (remaining.length === 0) delete config.plugin;
+	else config.plugin = remaining;
+	if (opts.dryRun) {
+		if (plannedPurge.length > 0) {
+			console.log(`[dry-run] Would purge:`);
+			for (const p of plannedPurge) console.log(`  ${p}`);
+		}
+		console.log(`[dry-run] Would write to ${loaded.path}:`);
+		console.log(JSON.stringify(config, null, JSON_INDENT));
+		return {
+			status: "planned",
+			path: loaded.path,
+			removed,
+			purged: plannedPurge
+		};
+	}
+	let backup = null;
+	if (removed.length > 0 && loaded.existed) {
+		backup = backupIfWritable(loaded.path, fs);
+		writeAtomically(loaded.path, JSON.stringify(config, null, JSON_INDENT), fs);
+	}
+	for (const p of purgeCandidates) {
+		const result = purgeDir(p);
+		if (result) purged.push(result);
+	}
+	console.log(`✓ Uninstalled ${PLUGIN_NAME}`);
+	if (removed.length > 0) console.log(`  config: ${loaded.path}`);
+	if (backup) console.log(`  backup: ${backup}`);
+	for (const p of purged) console.log(`  purged: ${p}`);
+	return {
+		status: "wrote",
+		path: loaded.path,
+		removed,
+		purged
+	};
+};
+//#endregion
+//#region src/cli/main.ts
+const USAGE = `Usage: oas <command> [options]
+
+Commands:
+  install     Register the plugin in the global OpenCode config
+  uninstall   Remove the plugin from the global OpenCode config
+  status      Show current installation status
+  doctor      Run health checks against the global config
+
+Options (install):
+  -v, --version <v>  Install a specific version (default: latest)
+      --latest       Alias for --version latest
+      --dry-run      Print the planned change without writing
+      --yes          Skip confirmation prompts (reserved)
+
+Options (uninstall):
+      --purge        Also remove cache + ~/.config/opencode-agent-skills-md/
+      --dry-run      Print the planned change without writing
+      --yes          Skip confirmation prompts (reserved)
+
+Options (all):
+  -h, --help         Show this help and exit
+`;
+const printUsage = () => {
+	console.log(USAGE);
+};
+const setExit = (code) => {
+	process.exitCode = code;
+};
+const parseCliArgs = (argv) => {
+	const parsed = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		strict: true,
+		options: {
+			version: {
+				type: "string",
+				short: "v"
+			},
+			latest: { type: "boolean" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			"dry-run": { type: "boolean" },
+			purge: { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	return {
+		values: parsed.values,
+		positionals: parsed.positionals
+	};
+};
+/**
+* Strip Node + script argv entries when the entry point is invoked via
+* the shell (shebang) or via `node ./dist/cli.mjs`. When called from a
+* test harness with synthetic args, no stripping happens.
+*/
+const sliceProcessArgv = (argv) => {
+	if (argv.length < 2) return argv;
+	const first = argv[0] ?? "";
+	if (first === process.argv[0] || first.endsWith("node") || first.endsWith("node.exe")) return argv.slice(2);
+	return argv;
+};
+/**
+* Pure(ish) dispatcher: takes argv, runs the matching command, sets
+* `process.exitCode`, and returns a structured result so tests can assert
+* without reading the exit code.
+*/
+const runMain = (argv = process.argv) => {
+	const args = sliceProcessArgv(argv);
+	if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+		printUsage();
+		return {
+			command: "help",
+			exitCode: 0
+		};
+	}
+	let parsed;
+	try {
+		parsed = parseCliArgs(args);
+	} catch (err) {
+		console.error(`oas: ${err.message}`);
+		setExit(2);
+		return {
+			command: null,
+			exitCode: 2
+		};
+	}
+	if (parsed.values.help) {
+		printUsage();
+		return {
+			command: "help",
+			exitCode: 0
+		};
+	}
+	const command = parsed.positionals[0];
+	if (!command) {
+		console.error("oas: missing command. Run `oas --help` for usage.");
+		setExit(2);
+		return {
+			command: null,
+			exitCode: 2
+		};
+	}
+	try {
+		switch (command) {
+			case "install": {
+				const versionRaw = parsed.values.version;
+				runInstall({
+					version: parsed.values.latest === true ? "latest" : typeof versionRaw === "string" ? versionRaw : void 0,
+					dryRun: parsed.values["dry-run"] === true,
+					yes: parsed.values.yes === true
+				});
+				return {
+					command,
+					exitCode: 0
+				};
+			}
+			case "uninstall":
+				runUninstall({
+					purge: parsed.values.purge === true,
+					dryRun: parsed.values["dry-run"] === true,
+					yes: parsed.values.yes === true
+				});
+				return {
+					command,
+					exitCode: 0
+				};
+			case "status":
+				runStatus();
+				return {
+					command,
+					exitCode: 0
+				};
+			case "doctor": {
+				const result = runDoctor();
+				if (!result.ok) setExit(1);
+				return {
+					command,
+					exitCode: result.ok ? 0 : 1
+				};
+			}
+			default:
+				console.error(`oas: unknown command '${command}'. Run \`oas --help\` for usage.`);
+				setExit(2);
+				return {
+					command: null,
+					exitCode: 2
+				};
+		}
+	} catch (err) {
+		console.error(`oas: ${err.message}`);
+		setExit(1);
+		return {
+			command,
+			exitCode: 1
+		};
+	}
+};
+/**
+* `true` when the file is the program's entry point (shebang / `node
+* cli.mjs`), `false` when it was imported from a test harness. We avoid
+* `import.meta.main` because the package floor is Node 18 and that field
+* only landed in Node 22.
+*
+* Symlink-aware: when the script is invoked through a symlink (e.g. the
+* pnpm global store, where `node_modules/<pkg>` is a symlink into a
+* content-addressable store), `process.argv[1]` carries the symlink path
+* while `import.meta.url` carries the real path after symlink resolution.
+* Comparing the two verbatim would always be `false` under pnpm, causing
+* the CLI to silently exit. We resolve both sides through `realpathSync`
+* before comparing.
+*/
+const checkInvokedAsMain = () => {
+	if (!process.argv[1]) return false;
+	try {
+		const realArgv = pathToFileURL(realpathSync(process.argv[1])).href;
+		return import.meta.url === realArgv;
+	} catch {
+		try {
+			return import.meta.url === pathToFileURL(process.argv[1]).href;
+		} catch {
+			return false;
+		}
+	}
+};
+if (checkInvokedAsMain()) runMain(process.argv);
+//#endregion
+export { runMain };