@opys/cli 0.1.2

package/README.md

@@ -0,0 +1,82 @@
+# opys CLI
+
+Command-line interface for building and launching Minecraft client installations from declarative manifests.
+
+## Install
+
+```sh
+npm install -g @opys/cli
+```
+
+Or run directly without installing:
+
+```sh
+npx @opys/cli <command>
+```
+
+## Commands
+
+### `opys build`
+
+Reads a JS config file, fetches Mojang metadata, and writes a `opys.json` manifest.
+
+```sh
+opys build [--input opys.config.mjs] [--output opys.json]
+```
+
+| Flag       | Short | Default                | Description                       |
+| ---------- | ----- | ---------------------- | --------------------------------- |
+| `--input`  | `-i`  | `opys.config.mjs`      | Path to the JS config file        |
+| `--output` | `-o`  | value from config file | Output path for the manifest JSON |
+
+If `--output` is omitted and the config has no `output` field, the manifest is written to stdout.
+
+### `opys launch`
+
+Installs missing artifacts and spawns the JVM.
+
+```sh
+opys launch [manifest] [--var key=value ...]
+```
+
+Common vars to pass at launch: `username`, `uuid`, `token`.
+
+## Config file (`opys.config.mjs`)
+
+```js
+import {
+  defineConfig,
+  resolveMinecraft,
+  artifactScanner,
+} from '@opys/minecraft';
+
+export default defineConfig(async () => {
+  const mc = await resolveMinecraft({ version: '1.20.1' });
+
+  return {
+    output: 'opys.json',
+    manifest: {
+      artifacts: [
+        mc.artifacts,
+        artifactScanner({
+          directory: 'mods',
+          url: 'https://cdn.example.com/mods/${path}',
+          path: '${root}/mods/${path}',
+        }),
+      ],
+      vars: mc.vars,
+      launch: mc.launch,
+    },
+  };
+});
+```
+
+## Exit codes
+
+| Code | Meaning                         |
+| ---- | ------------------------------- |
+| 0    | Success                         |
+| 1    | Usage error (bad args / config) |
+| 2    | Network error                   |
+| 3    | Integrity check failed          |
+| 4    | Extraction failure              |

package/dist/opys.mjs

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { encodeManifest } from "@opys/core";
+import { buildManifest, resolveConfig } from "@opys/dev";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { ExtractionError, IntegrityError, NetworkError, install, launch } from "@opys/runtime";
+import { VersionFetchError } from "@opys/mojang";
+
+//#region lib/errors.ts
+var UsageError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UsageError";
+	}
+};
+
+//#endregion
+//#region lib/args.ts
+function parseArgs$1(argv, specs) {
+	const options = {};
+	for (const s of specs) options[s.long] = {
+		type: s.type,
+		...s.short ? { short: s.short } : {}
+	};
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options,
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (e) {
+		throw new UsageError(e.message);
+	}
+	return { getString: (flag) => parsed.values[flag] };
+}
+
+//#endregion
+//#region lib/load-config.ts
+/** Import a config file, resolve it for the given mode, and report its directory. */
+async function loadConfig(inputFile, mode) {
+	const absConfig = resolve(inputFile);
+	const configDir = dirname(absConfig);
+	const mod = await import(pathToFileURL(absConfig).href);
+	if (!mod.default) throw new UsageError(`${inputFile}: no default export`);
+	return {
+		config: await resolveConfig(mod.default, { mode }),
+		configDir
+	};
+}
+
+//#endregion
+//#region lib/commands/build.ts
+async function cmdBuild(argv, logger, command) {
+	const args = parseArgs$1(argv, [
+		{
+			long: "input",
+			short: "i",
+			type: "string"
+		},
+		{
+			long: "output",
+			short: "o",
+			type: "string"
+		},
+		{
+			long: "mode",
+			type: "string"
+		}
+	]);
+	const inputFile = args.getString("input") ?? "opys.config.mjs";
+	const outputFile = args.getString("output");
+	const mode = args.getString("mode") ?? command;
+	const { config, configDir } = await loadConfig(inputFile, mode);
+	const manifest = await buildManifest(config, {
+		log: (scope, msg) => logger.info(`[${scope}] ${msg}`),
+		configDir,
+		mode
+	});
+	const json = JSON.stringify(encodeManifest(manifest), null, 2) + "\n";
+	const out = outputFile ?? config.output;
+	if (out) {
+		await writeFile(resolve(configDir, out), json);
+		logger.info(`Written to ${out}`);
+	} else process.stdout.write(json);
+}
+
+//#endregion
+//#region lib/progress.ts
+const BAR_WIDTH = 24;
+const NON_TTY_INTERVAL_MS = 3e3;
+const FILLED = "█";
+const EMPTY = "░";
+function progressBar(pct) {
+	const filled = Math.round(Math.min(pct, 1) * BAR_WIDTH);
+	return FILLED.repeat(filled) + EMPTY.repeat(BAR_WIDTH - filled);
+}
+function formatSpeed(filesPerSec) {
+	if (filesPerSec >= 1e3) return `${(filesPerSec / 1e3).toFixed(1)}k/s`;
+	return `${filesPerSec.toFixed(0)}/s`;
+}
+function formatDuration(ms) {
+	const s = ms / 1e3;
+	if (s < 60) return `${s.toFixed(1)}s`;
+	return `${Math.floor(s / 60)}m ${(s % 60).toFixed(0)}s`;
+}
+function formatEta(remaining, rate) {
+	if (rate <= 0) return "";
+	const secs = remaining / rate;
+	if (secs < 1) return "";
+	if (secs < 60) return ` eta ${secs.toFixed(0)}s`;
+	return ` eta ${(secs / 60).toFixed(1)}m`;
+}
+function elapsed(t0) {
+	return formatDuration(Date.now() - t0);
+}
+function formatBytes(bytes) {
+	if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	if (bytes >= 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+	return `${bytes} B`;
+}
+function basename(path) {
+	return path.replace(/\\/g, "/").split("/").at(-1) ?? path;
+}
+function initialProgress(total, t0) {
+	return {
+		fetched: 0,
+		total,
+		t0,
+		active: []
+	};
+}
+function renderProgress(state) {
+	const { fetched, total, t0, active } = state;
+	const pct = total === 0 ? 1 : fetched / total;
+	const rate = fetched / (Math.max(Date.now() - t0, 1) / 1e3);
+	const overall = ` [${progressBar(pct)}] ${`${Math.round(pct * 100).toString().padStart(3)}%`} ${`${fetched}/${total}`}${rate > .1 ? ` @ ${formatSpeed(rate)}` : ""}${fetched < total ? formatEta(total - fetched, rate) : ""}`;
+	const cols = process.stderr.columns ?? 80;
+	return [overall, ...active.map((f, i) => {
+		const indent = i === active.length - 1 ? " └─ " : " ├─ ";
+		const name = basename(f.name);
+		const pctF = f.total > 0 ? f.bytes / f.total : 0;
+		const barF = progressBar(pctF);
+		const pctFStr = `${Math.round(pctF * 100).toString().padStart(3)}%`;
+		const totalFmt = f.total > 0 ? formatBytes(f.total) : "";
+		const fixed = ` [${barF}] ${pctFStr}${f.total > 0 ? ` ${formatBytes(f.bytes).padStart(totalFmt.length)}/${totalFmt}` : f.bytes > 0 ? ` ${formatBytes(f.bytes)}` : ""}`;
+		const nameBudget = cols - 1 - indent.length - fixed.length;
+		return `${indent}${nameBudget > 4 ? name.slice(0, nameBudget).padEnd(nameBudget) : ""}${fixed}`;
+	})];
+}
+var ProgressWriter = class {
+	lastLines = [];
+	lastNonTty = 0;
+	constructor(isTTY, nonTtyInterval = NON_TTY_INTERVAL_MS) {
+		this.isTTY = isTTY;
+		this.nonTtyInterval = nonTtyInterval;
+	}
+	clearLines() {
+		if (!this.isTTY || this.lastLines.length === 0) return;
+		process.stderr.write("\x1B[2K\r");
+		for (let i = 1; i < this.lastLines.length; i++) process.stderr.write("\x1B[1A\x1B[2K\r");
+	}
+	update(lines) {
+		if (this.isTTY) {
+			this.clearLines();
+			process.stderr.write(lines.join("\n"));
+			this.lastLines = lines;
+		} else {
+			const now = Date.now();
+			if (now - this.lastNonTty >= this.nonTtyInterval) {
+				if (lines.length > 0) process.stderr.write(`${lines[0]}\n`);
+				this.lastNonTty = now;
+			}
+		}
+	}
+	clear() {
+		if (this.isTTY && this.lastLines.length > 0) {
+			this.clearLines();
+			this.lastLines = [];
+		}
+	}
+	redraw() {
+		if (this.isTTY && this.lastLines.length > 0) process.stderr.write(this.lastLines.join("\n"));
+	}
+	log(line) {
+		this.clear();
+		process.stderr.write(`${line}\n`);
+	}
+	finish(lines) {
+		if (this.isTTY) {
+			this.clearLines();
+			const out = lines ?? this.lastLines;
+			if (out.length > 0) process.stderr.write(`${out.join("\n")}\n`);
+			this.lastLines = [];
+		} else if (lines && lines.length > 0) process.stderr.write(`${lines[0]}\n`);
+	}
+};
+
+//#endregion
+//#region lib/commands/launch.ts
+/** Minimum gap between progress redraws, in milliseconds. */
+const RENDER_THROTTLE_MS = 80;
+async function cmdLaunch(argv, logger, command) {
+	const args = parseArgs$1(argv, [{
+		long: "input",
+		short: "i",
+		type: "string"
+	}, {
+		long: "mode",
+		type: "string"
+	}]);
+	const inputFile = args.getString("input") ?? "opys.config.mjs";
+	const mode = args.getString("mode") ?? command;
+	const { config, configDir } = await loadConfig(inputFile, mode);
+	const baseManifest = await buildManifest(config, {
+		log: (scope, msg) => logger.info(`[${scope}] ${msg}`),
+		configDir,
+		mode
+	});
+	const manifest = config.runClient ? {
+		...baseManifest,
+		...config.runClient(baseManifest)
+	} : baseManifest;
+	const t0 = Date.now();
+	const pw = new ProgressWriter(process.stderr.isTTY ?? false);
+	logger.setProgressWriter(pw);
+	logger.info("Installing...");
+	const active = /* @__PURE__ */ new Map();
+	const state = initialProgress(0, t0);
+	let lastRender = 0;
+	const render = (force = false) => {
+		const now = Date.now();
+		if (!force && now - lastRender < RENDER_THROTTLE_MS) return;
+		lastRender = now;
+		state.active = [...active.values()];
+		pw.update(renderProgress(state));
+	};
+	await install(manifest, { onProgress(p) {
+		switch (p.phase) {
+			case "download":
+				state.total = p.total;
+				state.fetched = p.fetched;
+				render(true);
+				break;
+			case "download:start":
+				active.set(p.path, {
+					name: p.path,
+					bytes: 0,
+					total: p.total
+				});
+				render();
+				break;
+			case "download:bytes": {
+				const entry = active.get(p.path);
+				if (entry) {
+					entry.bytes = p.bytes;
+					render();
+				}
+				break;
+			}
+			case "download:done":
+				active.delete(p.path);
+				pw.log(`  ✓ ${basename(p.path)}`);
+				break;
+			case "verify":
+				pw.finish();
+				pw.log(" Verifying...");
+				break;
+			case "extract":
+				pw.log(` Extracting ${p.count} archive${p.count === 1 ? "" : "s"}...`);
+				break;
+			case "sweep":
+				pw.log(` Swept ${p.removed} stale file${p.removed === 1 ? "" : "s"}`);
+				break;
+		}
+	} });
+	pw.finish();
+	logger.info(` Ready in ${elapsed(t0)}`);
+	logger.info("Launching...");
+	const child = await launch(manifest, { install: false });
+	logger.info(` PID ${child.pid}`);
+	await new Promise((res, rej) => {
+		child.on("exit", (code) => code === 0 || code === null ? res() : rej(/* @__PURE__ */ new Error(`exit ${code}`)));
+		child.on("error", rej);
+	});
+}
+
+//#endregion
+//#region lib/logger.ts
+const RANK = {
+	silent: 0,
+	error: 1,
+	warn: 2,
+	info: 3,
+	debug: 4
+};
+const LEVEL_PREFIX = {
+	error: "[error]",
+	warn: "[warn] ",
+	debug: "[debug]"
+};
+/**
+* Level-aware logger that writes to stderr.
+* Coordinates with a {@link ProgressWriter} to clear the progress bar before
+* writing debug/warn lines so they don't mangle in-flight progress output.
+*/
+var Logger = class {
+	t0 = Date.now();
+	pw;
+	constructor(level) {
+		this.level = level;
+	}
+	/** Attach a ProgressWriter so log lines clear the bar before printing. */
+	setProgressWriter(pw) {
+		this.pw = pw;
+	}
+	error(msg) {
+		this.emit("error", msg);
+	}
+	warn(msg) {
+		this.emit("warn", msg);
+	}
+	info(msg) {
+		this.emit("info", msg);
+	}
+	debug(msg) {
+		this.emit("debug", msg);
+	}
+	/** Returns true when `level` is at or below this logger's threshold. */
+	enables(level) {
+		return RANK[level] <= RANK[this.level];
+	}
+	/** Returns an `InstallOptions`-compatible log callback. */
+	installerLog() {
+		return (level, msg) => this.emit(level, msg);
+	}
+	emit(level, msg) {
+		if (!this.enables(level)) return;
+		this.pw?.clear();
+		const prefix = LEVEL_PREFIX[level];
+		const line = prefix ? `${prefix} +${Date.now() - this.t0}ms ${msg}\n` : `${msg}\n`;
+		process.stderr.write(line);
+		this.pw?.redraw();
+	}
+};
+/** Parse a log level from a string, defaulting to 'info' on unknown values. */
+function parseLogLevel(raw) {
+	if (!raw) return "info";
+	if (Object.prototype.hasOwnProperty.call(RANK, raw)) return raw;
+	process.stderr.write(`[warn]  Unknown log level '${raw}', defaulting to 'info'\n`);
+	return "info";
+}
+
+//#endregion
+//#region bin/opys.ts
+const USAGE = `\
+opys — declarative manifest toolkit
+
+USAGE
+  opys build  [-i <opys.config.mjs>] [-o <out>] [--mode <m>]  Build manifest
+  opys launch [-i <opys.config.mjs>] [--mode <m>]  Build, install, launch
+
+OPTIONS
+  -i, --input          Config file  (default: opys.config.mjs)
+  -o, --output         Output file  (default: stdout for build)
+  --mode <value>       Mode passed to config function (default: command name)
+  --log-level <level>  Log verbosity: silent|error|warn|info|debug  (default: info)
+  -v                   Shorthand for --log-level debug
+
+EXIT CODES
+  0  Success
+  1  Usage or config error
+  2  Network error
+  3  Integrity check failure
+  4  Extraction failure
+`;
+const COMMANDS = {
+	build: cmdBuild,
+	launch: cmdLaunch
+};
+/** Strip global flags from argv, returning the cleaned args and extracted values. */
+function extractGlobals(argv) {
+	const args = [];
+	let logLevel = "info";
+	let i = 0;
+	while (i < argv.length) {
+		const token = argv[i++];
+		if (token === "--log-level") logLevel = parseLogLevel(argv[i++]);
+		else if (token === "-v") logLevel = "debug";
+		else args.push(token);
+	}
+	return {
+		args,
+		logLevel
+	};
+}
+async function main() {
+	const [, , ...allArgs] = process.argv;
+	const { args, logLevel } = extractGlobals(allArgs ?? []);
+	const [command, ...rest] = args;
+	const logger = new Logger(logLevel);
+	if (!command || command === "--help" || command === "-h") {
+		process.stdout.write(USAGE);
+		return;
+	}
+	const handler = COMMANDS[command];
+	if (!handler) {
+		process.stderr.write(`Unknown command '${command}'\n\n${USAGE}`);
+		process.exit(1);
+	}
+	await handler(rest, logger, command);
+}
+main().catch((err) => {
+	if (err instanceof UsageError) {
+		process.stderr.write(`Error: ${err.message}\n`);
+		process.exit(1);
+	}
+	if (err instanceof NetworkError || err instanceof VersionFetchError) {
+		process.stderr.write(`Network error: ${err.message}\n`);
+		process.exit(2);
+	}
+	if (err instanceof IntegrityError) {
+		process.stderr.write(`Integrity check failed:\n`);
+		for (const p of err.paths) process.stderr.write(`  ${p}\n`);
+		process.exit(3);
+	}
+	if (err instanceof ExtractionError) {
+		process.stderr.write(`Extraction failed: ${err.message}\n`);
+		if (err.cause instanceof Error) process.stderr.write(`  caused by: ${err.cause.message}\n`);
+		process.exit(4);
+	}
+	const msg = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`Unexpected error: ${msg}\n`);
+	if (err instanceof Error && err.cause instanceof Error) {
+		process.stderr.write(`  caused by: ${err.cause.message}\n`);
+		if (err.cause.stack && !process.env.OPYS_QUIET) process.stderr.write(`${err.cause.stack}\n`);
+	}
+	if (err instanceof Error && err.stack && !process.env.OPYS_QUIET) process.stderr.write(`${err.stack}\n`);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@opys/cli",
+  "version": "0.1.2",
+  "bin": {
+    "opys": "dist/opys.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run tests/unit --passWithNoTests",
+    "test:int": "vitest run tests/integration --testTimeout=180000"
+  },
+  "type": "module",
+  "dependencies": {
+    "@opys/core": "^0.1.2",
+    "@opys/dev": "^0.1.2",
+    "@opys/runtime": "^0.1.2",
+    "@opys/minecraft": "^0.1.2",
+    "@opys/mojang": "^0.1.2"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harmoniya-net/opys.git",
+    "directory": "packages/cli"
+  }
+}