@chaja/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @chaja/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create releases and upload sourcemaps to a self-hosted [Chajá](https://github.com/emiliodominguez/chaja) server from CI.
+
+```sh
+pnpm add -D @chaja/cli
+
+export CHAJA_URL=https://chaja.example.com CHAJA_TOKEN=<API token> CHAJA_PROJECT=<project slug>
+chaja releases new "$RELEASE"
+chaja sourcemaps upload ./dist --release "$RELEASE"
+```
+
+API tokens are created under Account in the Chajá web app. Every `*.map` under the directory is uploaded as `~/<path>`, which
+matches the bundle on any origin; change it with `--url-prefix`. Requires Node.js 22+.

package/dist/main.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import { join, posix, relative, sep } from "node:path";
+import { parseArgs } from "node:util";
+//#region src/messages.ts
+/**
+* Every line the CLI prints. Kept in one catalog so the CLI can be translated without touching command code.
+*/
+const messages = {
+	usage: [
+		"Usage: chaja <command> [options]",
+		"",
+		"Commands:",
+		"  releases new <version>                 Create a release",
+		"  sourcemaps upload <dir> --release <v>  Upload every *.map under <dir>",
+		"",
+		"Options:",
+		"  --url <url>          Chajá server (CHAJA_URL)",
+		"  --token <token>      API token (CHAJA_TOKEN)",
+		"  --project <slug>     Project slug (CHAJA_PROJECT)",
+		"  --url-prefix <p>     Prefix for uploaded file names, default ~/ (any origin)"
+	].join("\n"),
+	missingOption(option, variable) {
+		return `Missing --${option} (or ${variable}).`;
+	},
+	missingArgument(name) {
+		return `Missing <${name}>.`;
+	},
+	unknownCommand(command) {
+		return `Unknown command: ${command}. Run "chaja help".`;
+	},
+	releaseCreated(version) {
+		return `Release ${version} is ready.`;
+	},
+	noSourcemaps(directory) {
+		return `No *.map files found under ${directory}.`;
+	},
+	uploaded(name, bytes) {
+		return `Uploaded ${name} (${bytes} bytes)`;
+	},
+	uploadSummary(count, version) {
+		return `${count} sourcemap(s) uploaded to release ${version}.`;
+	},
+	requestFailed(status, code) {
+		return `Request failed with ${status}${code ? ` (${code})` : ""}.`;
+	},
+	unreachable(url) {
+		return `Could not reach ${url}.`;
+	}
+};
+//#endregion
+//#region src/cli.ts
+const EXIT = {
+	ok: 0,
+	failed: 1,
+	usage: 2
+};
+/**
+* Raised for problems the user can fix; printed without a stack.
+*/
+var CliError = class extends Error {
+	exitCode;
+	/**
+	* Create a user-facing failure.
+	*
+	* @param message - Line to print.
+	* @param exitCode - Process exit code.
+	*/
+	constructor(message, exitCode) {
+		super(message);
+		this.exitCode = exitCode;
+	}
+};
+/**
+* Find every `.map` file under a directory.
+*
+* @param directory - Root directory.
+* @returns Absolute paths.
+*/
+async function findSourcemaps(directory) {
+	return (await readdir(directory, {
+		recursive: true,
+		withFileTypes: true
+	})).filter(function isMap(entry) {
+		return entry.isFile() && entry.name.endsWith(".map");
+	}).map(function path(entry) {
+		return join(entry.parentPath, entry.name);
+	}).toSorted();
+}
+/**
+* The name a map is stored under: the URL path of the generated file it describes, under the prefix.
+*
+* @param directory - Upload root.
+* @param mapPath - Absolute map path.
+* @param map - Parsed map, whose `file` names the generated file.
+* @param prefix - URL prefix such as `~/` or `~/static`.
+* @returns Artifact name like `~/assets/index-abc.js`.
+*/
+function artifactName(directory, mapPath, map, prefix) {
+	const relativeMap = relative(directory, mapPath).split(sep).join("/");
+	const folder = posix.dirname(relativeMap);
+	const generated = typeof map.file === "string" && map.file.length > 0 ? posix.join(folder, posix.basename(map.file)) : relativeMap.replace(/\.map$/u, "");
+	return `${prefix.endsWith("/") ? prefix : `${prefix}/`}${generated.replace(/^\.\//u, "")}`;
+}
+/**
+* Call the Chajá API with the token, turning failures into CLI errors.
+*
+* @param io - Injected I/O.
+* @param connection - Server, token and project.
+* @param path - Path under `/api/v1`.
+* @param init - Fetch options.
+* @returns Parsed JSON body.
+*/
+async function call(io, connection, path, init) {
+	const url = `${connection.url}/api/v1${path}`;
+	let response;
+	try {
+		const headers = new Headers(init.headers);
+		headers.set("authorization", `Bearer ${connection.token}`);
+		response = await io.fetch(url, {
+			...init,
+			headers
+		});
+	} catch {
+		throw new CliError(messages.unreachable(connection.url), EXIT.failed);
+	}
+	const text = await response.text();
+	const body = text ? JSON.parse(text) : {};
+	if (!response.ok) {
+		const code = typeof body === "object" && body !== null && "code" in body && typeof body.code === "string" ? body.code : "";
+		throw new CliError(messages.requestFailed(response.status, code), EXIT.failed);
+	}
+	return body;
+}
+/**
+* Run the CLI.
+*
+* @param argv - Arguments after the executable.
+* @param io - Fetch, environment and output.
+* @returns Exit code.
+*/
+async function run(argv, io) {
+	try {
+		const { values, positionals } = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: {
+				url: { type: "string" },
+				token: { type: "string" },
+				project: { type: "string" },
+				release: { type: "string" },
+				"url-prefix": {
+					type: "string",
+					default: "~/"
+				},
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			}
+		});
+		const [group, command, argument] = positionals;
+		if (values.help || !group || group === "help") {
+			io.stdout(messages.usage);
+			return EXIT.ok;
+		}
+		/**
+		* Read a required setting from a flag or environment variable.
+		*
+		* @param option - Flag name.
+		* @param variable - Environment variable.
+		* @param value - Flag value.
+		* @returns The setting.
+		*/
+		function required(option, variable, value) {
+			const resolved = value ?? io.env[variable];
+			if (!resolved) throw new CliError(messages.missingOption(option, variable), EXIT.usage);
+			return resolved;
+		}
+		/**
+		* Resolve server, token and project, failing on the first missing one.
+		*
+		* @returns Connection settings.
+		*/
+		function connection() {
+			return {
+				url: required("url", "CHAJA_URL", values.url).replace(/\/+$/u, ""),
+				token: required("token", "CHAJA_TOKEN", values.token),
+				project: required("project", "CHAJA_PROJECT", values.project)
+			};
+		}
+		if (group === "releases" && command === "new") {
+			if (!argument) throw new CliError(messages.missingArgument("version"), EXIT.usage);
+			const target = connection();
+			await call(io, target, `/projects/${encodeURIComponent(target.project)}/releases`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ version: argument })
+			});
+			io.stdout(messages.releaseCreated(argument));
+			return EXIT.ok;
+		}
+		if (group === "sourcemaps" && command === "upload") {
+			if (!argument) throw new CliError(messages.missingArgument("dir"), EXIT.usage);
+			const target = connection();
+			const version = required("release", "CHAJA_RELEASE", values.release);
+			const maps = await findSourcemaps(argument);
+			if (maps.length === 0) throw new CliError(messages.noSourcemaps(argument), EXIT.failed);
+			for (const mapPath of maps) {
+				const bytes = await readFile(mapPath);
+				const parsed = JSON.parse(bytes.toString("utf8"));
+				const name = artifactName(argument, mapPath, typeof parsed === "object" && parsed !== null ? parsed : {}, values["url-prefix"]);
+				await call(io, target, `/projects/${encodeURIComponent(target.project)}/releases/${encodeURIComponent(version)}/files?name=${encodeURIComponent(name)}`, {
+					method: "PUT",
+					headers: { "content-type": "application/json" },
+					body: bytes
+				});
+				io.stdout(messages.uploaded(name, bytes.byteLength));
+			}
+			io.stdout(messages.uploadSummary(maps.length, version));
+			return EXIT.ok;
+		}
+		throw new CliError(messages.unknownCommand(positionals.join(" ")), EXIT.usage);
+	} catch (error) {
+		if (error instanceof CliError) {
+			io.stderr(error.message);
+			return error.exitCode;
+		}
+		if (error instanceof TypeError && "code" in error && typeof error.code === "string" && error.code.startsWith("ERR_PARSE_ARGS")) {
+			io.stderr(error.message);
+			return EXIT.usage;
+		}
+		throw error;
+	}
+}
+//#endregion
+//#region src/main.ts
+process.exitCode = await run(process.argv.slice(2), {
+	fetch,
+	env: process.env,
+	stdout(line) {
+		process.stdout.write(`${line}\n`);
+	},
+	stderr(line) {
+		process.stderr.write(`${line}\n`);
+	}
+});
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@chaja/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Chajá command line: create releases and upload sourcemaps from CI.",
+  "keywords": [
+    "chaja",
+    "sourcemaps",
+    "cli"
+  ],
+  "homepage": "https://github.com/emiliodominguez/chaja#readme",
+  "bugs": "https://github.com/emiliodominguez/chaja/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emiliodominguez/chaja.git",
+    "directory": "apps/cli"
+  },
+  "type": "module",
+  "nx": {
+    "tags": [
+      "scope:app",
+      "type:cli"
+    ]
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "chaja": "./dist/main.mjs"
+  },
+  "devDependencies": {
+    "tsdown": "0.23.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown src/main.ts --format esm --platform node --target node22 --out-dir dist --no-dts --clean",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }