Flesh out node scripts.

scripts/node/utils/commands.mjs

@@ -0,0 +1,116 @@
+/**
+ * Utility functions for running shell commands and handling their results.
+ *
+ * @import { ExecOptions } from "node:child_process"
+ */
+
+import { exec } from "node:child_process";
+import { resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+import { ConsoleLogger } from "../../../packages/logger-js/lib/node.js";
+
+const logger = ConsoleLogger.prefix("commands");
+
+export class CommandError extends Error {
+    name = "CommandError";
+
+    /**
+     * @param {string} command
+     * @param {ErrorOptions & ExecOptions} options
+     */
+    constructor(command, { cause, cwd, shell } = {}) {
+        const cwdInfo = cwd ? ` in directory ${cwd}` : "";
+        const shellInfo = shell ? ` using shell ${shell}` : "";
+
+        super(`Command failed: ${command}${cwdInfo}${shellInfo}`, { cause });
+    }
+}
+
+/**
+ * @param {string[]} positionals
+ * @returns {string} The resolved current working directory for the script
+ */
+export function parseCWD(positionals) {
+    // `INIT_CWD` is present only if the script is run via npm.
+    const initCWD = process.env.INIT_CWD || process.cwd();
+
+    const cwd = (positionals.length ? resolve(initCWD, positionals[0]) : initCWD) + sep;
+
+    return cwd;
+}
+
+const execAsync = promisify(exec);
+
+/**
+ * @param {Awaited<ReturnType<typeof execAsync>>} result
+ */
+export const trimResult = (result) => String(result.stdout).trim();
+
+/**
+ * @typedef {(strings: TemplateStringsArray, ...expressions: unknown[]) =>
+ *   (options?: ExecOptions) => Promise<string>
+ * } CommandTag
+ */
+
+function createTag(prefix = "") {
+    /** @type {CommandTag} */
+    return (strings, ...expressions) => {
+        const command = (prefix ? prefix + " " : "") + String.raw(strings, ...expressions);
+
+        logger.debug(command);
+
+        return (options) =>
+            execAsync(command, options)
+                .then(trimResult)
+                .catch((cause) => {
+                    throw new CommandError(command, { ...options, cause });
+                });
+    };
+}
+
+/**
+ * A tagged template function for running shell commands.
+ * @type {CommandTag & { bind(prefix: string): CommandTag }}
+ */
+export const $ = createTag();
+
+/**
+ * @param {string} prefix
+ * @returns {CommandTag}
+ */
+$.bind = (prefix) => createTag(prefix);
+
+/**
+ * Promisified version of {@linkcode exec} for easier async/await usage.
+ *
+ * @param {string} command The command to run, with space-separated arguments.
+ * @param {ExecOptions} [options] Optional execution options.
+ * @throws {CommandError} If the command fails to execute.
+ */
+export function $2(command, options) {
+    return execAsync(command, options)
+        .then(trimResult)
+        .catch((cause) => {
+            throw new CommandError(command, { ...options, cause });
+        });
+}
+
+/**
+ * Logs the given error and its cause (if any) and exits the process with a failure code.
+ * @param {unknown} error
+ * @param {typeof ConsoleLogger} logger
+ * @returns {never}
+ */
+export function reportAndExit(error, logger = ConsoleLogger) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error && error.cause instanceof Error ? error.cause : null;
+
+    logger.error(`❌ ${message}`);
+
+    if (cause) {
+        logger.error(`Caused by: ${cause.message}`);
+    }
+
+    process.exit(1);
+}

scripts/node/utils/corepack.mjs

@@ -0,0 +1,84 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { ConsoleLogger } from "../../../packages/logger-js/lib/node.js";
+import { $ } from "./commands.mjs";
+
+const REGISTRY_URL = "https://registry.npmjs.org/corepack";
+const OUTPUT_DIR = join(".corepack", "releases");
+const OUTPUT_FILENAME = "latest.tgz";
+
+export const corepack = $.bind("corepack");
+
+/**
+ * Reads the installed Corepack version.
+ *
+ * @param {string} [cwd] The directory to run the command in.
+ * @returns {Promise<string | null>} The installed Corepack version
+ */
+export function readCorepackVersion(cwd = process.cwd()) {
+    return $`corepack --version`({ cwd });
+}
+
+const logger = ConsoleLogger.prefix("setup-corepack");
+
+/**
+ * @param {string} baseDirectory
+ */
+export async function pullLatestCorepack(baseDirectory = process.cwd()) {
+    logger.info("Fetching corepack metadata from registry...");
+
+    const outputDir = join(baseDirectory, OUTPUT_DIR);
+    const outputPath = join(outputDir, OUTPUT_FILENAME);
+
+    const res = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(1000 * 60) });
+
+    if (!res.ok) {
+        throw new Error(`Failed to fetch registry metadata: ${res.status} ${res.statusText}`);
+    }
+
+    const metadata = await res.json();
+
+    const latestVersion = metadata["dist-tags"].latest;
+    const versionData = metadata.versions[latestVersion];
+    const tarballUrl = versionData.dist.tarball;
+    const expectedIntegrity = versionData.dist.integrity;
+
+    logger.info(`Latest corepack version: ${latestVersion}`);
+    logger.info(`Tarball URL: ${tarballUrl}`);
+    logger.info(`Expected integrity: ${expectedIntegrity}`);
+
+    logger.info({ url: tarballUrl }, "Downloading tarball...");
+
+    const tarballRes = await fetch(tarballUrl, {
+        signal: AbortSignal.timeout(1000 * 60),
+    });
+
+    if (!tarballRes.ok) {
+        throw new Error(
+            `Failed to download tarball: ${tarballRes.status} ${tarballRes.statusText}`,
+        );
+    }
+
+    const tarballBuffer = Buffer.from(await tarballRes.arrayBuffer());
+
+    logger.info("Verifying integrity...");
+
+    const [algorithm, expectedHash] = expectedIntegrity.split("-");
+    const actualHash = crypto.createHash(algorithm).update(tarballBuffer).digest("base64");
+
+    if (actualHash !== expectedHash) {
+        throw new Error(
+            `Integrity mismatch!\n  Expected: ${expectedHash}\n  Actual:   ${actualHash}`,
+        );
+    }
+
+    logger.info("Integrity verified.");
+
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.writeFile(outputPath, tarballBuffer);
+
+    logger.info(`Saved to ${relative(baseDirectory, outputPath)}`);
+    logger.info(`corepack@${latestVersion} (${expectedIntegrity})`);
+}

scripts/node/utils/git.mjs

@@ -0,0 +1,25 @@
+import { $ } from "./commands.mjs";
+
+/**
+ * Checks whether the given file has uncommitted changes in git.
+ *
+ * @param {string} filePath
+ * @param {string} [cwd]
+ * @returns {Promise<{ clean: boolean, available: boolean }>}
+ */
+export async function gitStatus(filePath, cwd = process.cwd()) {
+    return $`git status --porcelain ${filePath}`({ cwd })
+        .then((output) => ({ clean: !output, available: true }))
+        .catch(() => ({ clean: false, available: false }));
+}
+
+/**
+ * Finds the root directory of the git repository containing the given directory.
+ *
+ * @param {string} cwd
+ * @returns {Promise<string>} The path to the git repository root.
+ * @throws {Error} If the command fails (e.g., not a git repository).
+ */
+export function resolveRepoRoot(cwd = process.cwd()) {
+    return $`git rev-parse --show-toplevel`({ cwd });
+}

scripts/node/utils/node.mjs

@@ -0,0 +1,175 @@
+/**
+ * Utility functions for working with npm packages and versions.
+ *
+ * @import { ExecOptions } from "node:child_process"
+ */
+
+import * as fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { $ } from "./commands.mjs";
+
+/**
+ * Find the nearest directory containing both package.json and package-lock.json,
+ * starting from the given directory and walking upward.
+ *
+ * @param {string} start The directory to start searching from.
+ * @returns {Promise<{ packageJSONPath: string, packageLockPath: string }>}
+ * @throws {Error} If no co-located package.json and package-lock.json are found.
+ */
+export async function findNPMPackage(start) {
+    let currentDir = start;
+
+    while (currentDir !== dirname(currentDir)) {
+        const packageJSONPath = join(currentDir, "package.json");
+        const packageLockPath = join(currentDir, "package-lock.json");
+
+        try {
+            await Promise.all([fs.access(packageJSONPath), fs.access(packageLockPath)]);
+            return {
+                packageJSONPath,
+                packageLockPath,
+            };
+        } catch {
+            // Continue searching up the directory tree
+        }
+
+        currentDir = dirname(currentDir);
+    }
+
+    throw new Error(`No co-located package.json and package-lock.json found above ${start}`);
+}
+
+/**
+ * @typedef {object} PackageJSON
+ * @property {string} name
+ * @property {string} version
+ * @property {Record<string, string>} [dependencies]
+ * @property {Record<string, string>} [devDependencies]
+ * @property {Record<string, string>} [peerDependencies]
+ * @property {Record<string, string>} [optionalDependencies]
+ * @property {Record<string, string>} [peerDependenciesMeta]
+ * @property {Record<string, string>} [engines]
+ * @property {Record<string, string>} [devEngines]
+ * @property {string} [packageManager]
+ */
+
+/**
+ * @param {string} jsonPath
+ * @returns {Promise<PackageJSON>}
+ */
+export function loadJSON(jsonPath) {
+    return fs
+        .readFile(jsonPath, "utf-8")
+        .then(JSON.parse)
+        .catch((cause) => {
+            throw new Error(`Failed to load JSON file at ${jsonPath}`, { cause });
+        });
+}
+
+const PackageJSONComparisionFields = /** @type {const} */ ([
+    "name",
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+    "peerDependenciesMeta",
+]);
+
+/**
+ * @typedef {typeof PackageJSONComparisionFields[number]} PackageJSONComparisionField
+ */
+
+/**
+ * Extracts only the dependency fields from a package.json object for comparison purposes.
+ *
+ * @param {PackageJSON} data
+ * @returns {Pick<PackageJSON, PackageJSONComparisionField>}
+ */
+export function pluckDependencyFields(data) {
+    /**
+     * @type {Record<string, unknown>}
+     */
+    const result = {};
+
+    for (const field of PackageJSONComparisionFields) {
+        if (data[field]) {
+            result[field] = data[field];
+        }
+    }
+
+    return /** @type {Pick<PackageJSON, PackageJSONComparisionField>} */ (result);
+}
+
+//#region Versioning
+
+/**
+ * Compares two semantic version strings (e.g., "14.17.0").
+ *
+ * @param {string} a The first version string.
+ * @param {string} b The second version string.
+ * @returns {number}
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i]) return 1;
+        if (pa[i] < pb[i]) return -1;
+    }
+    return 0;
+}
+
+/**
+ * Runs a Node.js command and returns its stdout output as a string.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param  {...unknown} expressions
+ * @returns {(options?: ExecOptions) => Promise<string>}
+ */
+export const node = $.bind("node");
+
+/**
+ * @typedef {object} NPMCommandOptions
+ * @property {boolean} [useCorepack] Whether to prefix the command with "corepack " to use Corepack's shims.
+ * @returns {Promise<string>}
+ */
+
+/**
+ * Runs an npm command and returns its stdout output as a string.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param  {...unknown} expressions
+ * @returns {(options?: ExecOptions & NPMCommandOptions) => Promise<string>}
+ */
+export function npm(strings, ...expressions) {
+    const subcommand = String.raw(strings, ...expressions);
+
+    return ({ useCorepack, ...options } = {}) => {
+        const command = [useCorepack ? "corepack" : "", "npm", subcommand]
+            .filter(Boolean)
+            .join(" ");
+
+        return $`${command}`(options);
+    };
+}
+
+/**
+ * Parses a version range string, stripping any leading >= and normalizing to three parts.
+ * @param {string} range
+ * @returns {{ operator: ">=" | "=", version: string }}
+ */
+export function parseRange(range) {
+    const hasGte = range.startsWith(">=");
+    const raw = hasGte ? range.slice(2) : range;
+    const parts = raw.split(".").map(Number);
+
+    while (parts.length < 3) parts.push(0);
+
+    return {
+        operator: hasGte ? ">=" : "=",
+        version: parts.join("."),
+    };
+}
+
+//#endregion