@haltcase/run 3.0.1 → 5.0.0-beta.1

package/dist/cli/bin.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli/bin.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { createHandler } from "./handler.mjs";
+import { main } from "./main.mjs";
+//#region src/cli/bin.ts
+main({ handler: createHandler() });
+//#endregion
+export {};

package/dist/cli/handler.mjs

@@ -0,0 +1,110 @@
+import { isBrandedTask } from "../tasks/guards.mjs";
+import { getSchemaProperties } from "../util/getSchemaProperties.mjs";
+import { extensions } from "../util/resolveTaskFile.mjs";
+import { Spinner } from "./spinner.mjs";
+import { styleText } from "node:util";
+import { readdirSync } from "node:fs";
+import { extname } from "node:path";
+import cliui from "cliui";
+//#region src/cli/handler.ts
+const failWith = (spinner, message) => {
+	let text;
+	if (Array.isArray(message)) text = message.map(String).join("\n");
+	if (text == null || typeof text !== "string") text = String(message);
+	spinner.error({ text });
+	process.exit(1);
+};
+const write = (message) => {
+	process.stdout.write(`${message}\n`);
+};
+const usage = `Usage: ${styleText("yellow", "hr")} <taskFile> [task]`;
+const commandHandler = (_context) => {
+	return usage;
+};
+const taskFileListHandler = (context) => {
+	return `${[
+		usage,
+		"Available task files:",
+		readdirSync(context.config.taskDirectory).filter((file) => extensions.includes(extname(file))).map((it) => `  ${it}`).join("\n")
+	].join("\n\n")}\n`;
+};
+const taskListHandler = (context) => {
+	const ui = cliui({
+		width: Math.max(0, process.stdout.columns - 4),
+		wrap: true
+	});
+	const { config } = context.taskFile.data;
+	const baseUsage = usage.replace("<taskFile>", context.taskFile.name);
+	ui.div(`${baseUsage} <parameter> [...options]`);
+	ui.div({
+		text: "Available tasks:",
+		padding: [
+			1,
+			0,
+			1,
+			0
+		]
+	});
+	const taskListPaddingX = 2;
+	const nameColumnWidth = Object.keys(config).reduce((previous, current) => Math.max(previous, current.length), 1) + 2 + taskListPaddingX * 2;
+	for (const [name, value] of Object.entries(config)) {
+		if (!value) continue;
+		const formattedName = styleText("bold", name);
+		if (isBrandedTask(value)) {
+			if (value.kind === "strictTask") {
+				const properties = getSchemaProperties(value.schema) || styleText("gray", "not available");
+				ui.div({
+					text: formattedName,
+					width: nameColumnWidth,
+					padding: [
+						0,
+						taskListPaddingX,
+						0,
+						taskListPaddingX
+					]
+				}, properties);
+				continue;
+			}
+			ui.div({
+				text: formattedName,
+				width: nameColumnWidth,
+				padding: [
+					0,
+					taskListPaddingX,
+					0,
+					taskListPaddingX
+				]
+			});
+			continue;
+		}
+		ui.div({
+			text: formattedName,
+			width: nameColumnWidth,
+			padding: [
+				0,
+				taskListPaddingX,
+				0,
+				taskListPaddingX
+			]
+		});
+	}
+	ui.div("");
+	return ui.toString();
+};
+const help = (context) => {
+	if ("command" in context) return commandHandler(context);
+	if ("taskFileList" in context) return taskFileListHandler(context);
+	if ("taskList" in context) return taskListHandler(context);
+	return "";
+};
+const createHandler = () => {
+	const spinner = new Spinner();
+	return {
+		spinner,
+		help,
+		write,
+		failWith: (message) => failWith(spinner, message)
+	};
+};
+//#endregion
+export { createHandler };

package/dist/cli/main.mjs

@@ -0,0 +1,56 @@
+import { parseOptions } from "./parseOptions.mjs";
+import { resolveTaskFile } from "../util/resolveTaskFile.mjs";
+import { getAppConfig } from "../config.mjs";
+import { executeTask } from "../tasks/executeTask.mjs";
+import { loadTaskFile } from "../util/loadTaskFile.mjs";
+import { parse, resolve } from "node:path";
+//#region src/cli/main.ts
+const main = async (props) => {
+	const { config } = await getAppConfig();
+	const inputFileName = process.argv[2];
+	const taskName = process.argv[3] ?? "";
+	if (!inputFileName) {
+		props.handler.write(props.handler.help({
+			taskFileList: true,
+			config
+		}));
+		props.handler.failWith("Task file name is required");
+	}
+	const fullFilePath = resolve(config.taskDirectory, inputFileName);
+	const context = {
+		...props,
+		config,
+		taskFile: {
+			...parse(fullFilePath),
+			path: fullFilePath
+		},
+		taskName
+	};
+	const resolutions = resolveTaskFile(context);
+	if (Array.isArray(resolutions)) props.handler.failWith([
+		`Found multiple task files with the name '${context.taskFile.name}'`,
+		`Rename the ambiguous files or specify an extension and try again`,
+		resolutions.map((it) => `  ${it}`).join("\n")
+	]);
+	context.taskFile = {
+		...parse(resolutions),
+		path: resolutions
+	};
+	const taskFileResult = await loadTaskFile(context);
+	if (!taskFileResult.ok) props.handler.failWith(taskFileResult.error);
+	const contextWithData = {
+		...context,
+		taskFile: {
+			...context.taskFile,
+			data: taskFileResult.value
+		}
+	};
+	try {
+		await executeTask(contextWithData, parseOptions(process.argv.slice(4)));
+		if (!config.quiet) props.handler.spinner.success({ text: "Success" });
+	} catch (error) {
+		props.handler.failWith([`Failed to execute task`, String(error)]);
+	}
+};
+//#endregion
+export { main };

package/dist/cli/parseOptions.d.mts

@@ -0,0 +1,7 @@
+//#region src/cli/parseOptions.d.ts
+interface ParsedOptions {
+  _: string[];
+  [key: string]: unknown;
+}
+//#endregion
+export { ParsedOptions };

package/dist/cli/parseOptions.mjs

@@ -0,0 +1,36 @@
+import { parseArgs } from "node:util";
+//#region src/cli/parseOptions.ts
+const reservedNames = new Set(["_", "env"]);
+/**
+* Wrapper around Node's {@link parseArgs} that treats options as strings
+* by default, instead of boolean flags.
+*
+* @param args - argv-like string
+* @returns
+*/
+const parseOptions = (args) => {
+	const { tokens } = parseArgs({
+		args,
+		allowPositionals: true,
+		strict: false,
+		tokens: true
+	});
+	const options = { _: [] };
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index];
+		if (token.kind === "option-terminator") continue;
+		if (token.kind === "option") {
+			if (reservedNames.has(token.name)) throw new Error(`Reserved name '${token.name}' cannot be used as option`);
+			if (index + 1 < tokens.length) {
+				const next = tokens[index + 1];
+				if (next.kind !== "positional") throw new Error(`Expected value for option ${token.rawName}`);
+				options[token.name] = next.value;
+				index++;
+			} else throw new Error(`Expected option ${token.rawName} to be followed by a value`);
+		}
+		if (token.kind === "positional") options._.push(token.value);
+	}
+	return options;
+};
+//#endregion
+export { parseOptions, reservedNames };

package/dist/cli/spinner.mjs

@@ -0,0 +1,128 @@
+import { styleText } from "node:util";
+import tty from "node:tty";
+//#region src/cli/spinner.ts
+/**
+* Based on `nanospinner` and `@favware/colorette-spinner` but using
+*
+* @see https://github.com/usmanyunusov/nanospinner (ISC © 2021 Usman Yunusov)
+* @see https://github.com/favware/colorette-spinner (MIT © 2022 Favware)
+*/
+var Spinner = class {
+	#isCI = process.env.CI || process.env.WT_SESSION || process.env.ConEmuTask === "{cmd::Cmder}" || process.env.TERM_PROGRAM === "vscode" || process.env.TERM === "xterm-256color" || process.env.TERM === "alacritty";
+	#isTTY = tty.isatty(1) && process.env.TERM !== "dumb" && !("CI" in process.env);
+	#supportUnicode = process.platform === "win32" ? this.#isCI : process.env.TERM !== "linux";
+	#symbols = {
+		frames: this.#isTTY ? this.#supportUnicode ? [
+			"⠋",
+			"⠙",
+			"⠹",
+			"⠸",
+			"⠼",
+			"⠴",
+			"⠦",
+			"⠧",
+			"⠇",
+			"⠏"
+		] : [
+			"-",
+			"\\",
+			"|",
+			"/"
+		] : ["-"],
+		tick: this.#supportUnicode ? "✔" : "√",
+		cross: this.#supportUnicode ? "✖" : "×"
+	};
+	#text = "";
+	#current = 0;
+	#interval = 50;
+	#stream = process.stderr;
+	#frames = this.#symbols.frames;
+	#color = "greenBright";
+	#lines = 0;
+	#timer;
+	constructor(text, options) {
+		this.#text = text ?? this.#text;
+		this.#interval = options?.interval ?? this.#interval;
+		this.#stream = options?.stream ?? this.#stream;
+		if (options?.frames?.length) this.#frames = options.frames;
+		this.#color = options?.color ?? this.#color;
+	}
+	clear() {
+		this.write("\x1B[1G");
+		for (let index = 0; index < this.#lines; index++) {
+			if (index > 0) this.write("\x1B[1A");
+			this.write("\x1B[2K\x1B[1G");
+		}
+		this.#lines = 0;
+		return this;
+	}
+	error(...[options = {}]) {
+		const mark = styleText("red", this.#symbols.cross);
+		return this.stop({
+			mark,
+			...options
+		});
+	}
+	reset() {
+		this.#current = 0;
+		this.#lines = 0;
+		if (this.#timer) clearTimeout(this.#timer);
+		return this;
+	}
+	spin() {
+		this.render();
+		this.#current = ++this.#current % this.#frames.length;
+		return this;
+	}
+	start(...[options = {}]) {
+		if (this.#timer) this.reset();
+		return this.update({
+			text: options.text ?? this.#text,
+			color: options.color ?? this.#color
+		}).loop();
+	}
+	stop(...[options = {}]) {
+		if (this.#timer) clearTimeout(this.#timer);
+		const mark = styleText(options.color || this.#color, this.#frames[this.#current] || "");
+		const optionsMark = options.mark && options.color ? styleText(options.color, options.mark) : options.mark;
+		this.write(`${optionsMark || mark} ${options.text || this.#text}\n`, true);
+		return this.#isTTY ? this.write(`\u001B[?25h`) : this;
+	}
+	success(...[options = {}]) {
+		const mark = styleText("green", this.#symbols.tick);
+		return this.stop({
+			mark,
+			...options
+		});
+	}
+	update(...[options = {}]) {
+		this.#text = options.text || this.#text;
+		this.#interval = options.interval ?? this.#interval;
+		this.#stream = options.stream ?? this.#stream;
+		if (options.frames?.length) this.#frames = options.frames;
+		this.#color = options.color ?? this.#color;
+		if (this.#frames.length - 1 < this.#current) this.#current = 0;
+		return this;
+	}
+	loop() {
+		if (this.#isTTY) this.#timer = setTimeout(() => this.loop(), this.#interval);
+		return this.spin();
+	}
+	write(value, clear = false) {
+		if (clear && this.#isTTY) this.clear();
+		this.#stream.write(value);
+		return this;
+	}
+	render() {
+		let value = `${styleText(this.#color, this.#frames[this.#current] || "")} ${this.#text}`;
+		if (this.#isTTY) this.write(`\u001B[?25l`);
+		else value += "\n";
+		this.write(value, true);
+		if (this.#isTTY) this.#lines = this.getLines(value, this.#stream.columns);
+	}
+	getLines(value = "", width = 80) {
+		return value.replaceAll(/\u001B[^m]*m/g, "").split("\n").reduce((column, line) => column + Math.max(1, Math.ceil(line.length / width)), 0);
+	}
+};
+//#endregion
+export { Spinner };

package/dist/config.d.mts

@@ -0,0 +1,18 @@
+//#region src/config.d.ts
+interface AppConfig {
+  /**
+   * Directory containing task files. Defaults to the `scripts` folder within
+   * the current working directory.
+   *
+   * @default `<cwd>/scripts`
+   */
+  taskDirectory: string;
+  /**
+   * Print no output unless errors occur.
+   *
+   * @default false
+   */
+  quiet: boolean;
+}
+//#endregion
+export { AppConfig };

package/dist/config.mjs

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import { loadConfig } from "c12";
+import { cwd } from "node:process";
+//#region src/config.ts
+const getAppConfig = async () => {
+	const configName = "haltcase.run";
+	return loadConfig({
+		name: configName,
+		configFile: configName,
+		packageJson: configName,
+		rcFile: configName,
+		defaults: {
+			taskDirectory: join(cwd(), "scripts"),
+			quiet: false
+		}
+	});
+};
+//#endregion
+export { getAppConfig };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { ParsedOptions } from "./cli/parseOptions.mjs";
+import { AppConfig } from "./config.mjs";
+import { Task } from "./tasks/types.mjs";
+import { task } from "./tasks/task.mjs";
+export { type AppConfig as HaltcaseRunConfig, type ParsedOptions, type Task, task };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { task } from "./tasks/task.mjs";
+export { task };

package/dist/tasks/executeTask.mjs

@@ -0,0 +1,83 @@
+import { $, execa } from "execa";
+const taskUtilities = {
+	command: execa,
+	$,
+	exec: execa({
+		stdin: "inherit",
+		stdout: "inherit",
+		stderr: "inherit"
+	})
+};
+const executeTask = async (context, options) => {
+	const taskFunction = context.taskFile.data.config[context.taskName];
+	const specifier = `${context.taskFile.name}::${context.taskName}`;
+	if (taskFunction == null) {
+		context.handler.write(context.handler.help({
+			taskList: true,
+			...context
+		}));
+		if (!context.taskName) context.handler.failWith(`Task name is required.`);
+		context.handler.failWith([`Task file '${context.taskFile.name}' does not export '${context.taskName}'`, `Resolved to: ${context.taskFile.path}`]);
+	}
+	try {
+		const optionsWithEnvironment = {
+			...options,
+			env: process.env
+		};
+		const isSpinnerEnabled = !context.config.quiet;
+		const pinnedSpinnerRenderInterval = 80;
+		if (isSpinnerEnabled) {
+			context.handler.spinner.start({ text: `Running ${specifier}` });
+			context.handler.spinner.update({ interval: pinnedSpinnerRenderInterval });
+		}
+		const originalStdoutWrite = Reflect.get(process.stdout, "write");
+		const originalStderrWrite = Reflect.get(process.stderr, "write");
+		const passthroughStdoutWrite = originalStdoutWrite.bind(process.stdout);
+		const passthroughStderrWrite = originalStderrWrite.bind(process.stderr);
+		let isSpinnerWrite = false;
+		let lastForcedRender = 0;
+		const clearPinnedSpinner = () => {
+			if (!isSpinnerEnabled) return;
+			isSpinnerWrite = true;
+			context.handler.spinner.clear();
+			isSpinnerWrite = false;
+		};
+		const renderPinnedSpinner = () => {
+			if (!isSpinnerEnabled) return;
+			const now = Date.now();
+			if (now - lastForcedRender < pinnedSpinnerRenderInterval) return;
+			lastForcedRender = now;
+			isSpinnerWrite = true;
+			context.handler.spinner.spin();
+			isSpinnerWrite = false;
+		};
+		const interceptWrite = (passthroughWrite) => {
+			return ((chunk, encoding, callback) => {
+				const writeArgs = [
+					chunk,
+					encoding,
+					callback
+				].filter((value) => value != null);
+				if (!isSpinnerEnabled || isSpinnerWrite) return Reflect.apply(passthroughWrite, process.stdout, writeArgs);
+				clearPinnedSpinner();
+				const didWrite = Reflect.apply(passthroughWrite, process.stdout, writeArgs);
+				renderPinnedSpinner();
+				return didWrite;
+			});
+		};
+		process.stdout.write = interceptWrite(passthroughStdoutWrite);
+		process.stderr.write = interceptWrite(passthroughStderrWrite);
+		try {
+			await taskFunction(optionsWithEnvironment, taskUtilities);
+		} finally {
+			process.stdout.write = originalStdoutWrite;
+			process.stderr.write = originalStderrWrite;
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("is not a function")) context.handler.failWith([`Failed to execute ${specifier}`, `Exported value '${context.taskName}' is not a function`]);
+		context.handler.failWith([`Failed to execute ${specifier}`, message]);
+	}
+};
+//#endregion
+export { executeTask };

package/dist/tasks/guards.mjs

@@ -0,0 +1,4 @@
+//#region src/tasks/guards.ts
+const isBrandedTask = (task) => "kind" in task;
+//#endregion
+export { isBrandedTask };

package/dist/tasks/task.d.mts

@@ -0,0 +1,10 @@
+import { BrandedTask, BrandedTaskStrict, DefaultOptionsInput, Task } from "./types.mjs";
+import { Type, type } from "arktype";
+
+//#region src/tasks/task.d.ts
+declare const task: {
+  <T = DefaultOptionsInput>(fn: Task<T>): BrandedTask<T>;
+  strict<const TShape>(shape: type.validate<TShape>, fn: Task<NoInfer<Type<type.infer<TShape>>["infer"]>>): BrandedTaskStrict<Type<type.infer<TShape>>["inferIn"]>;
+};
+//#endregion
+export { task };

package/dist/tasks/task.mjs

@@ -0,0 +1,40 @@
+import { styleText } from "node:util";
+import { type } from "arktype";
+//#region src/tasks/task.ts
+const formatValidationIssues = (errors) => errors.map((error) => {
+	const propertyName = String(error.path[0]);
+	const dottedPath = error.path.join(".");
+	if (!propertyName) return error.message;
+	const messageWithoutProperty = error.message.startsWith(dottedPath) ? error.message.slice(dottedPath.length + 1) : error.message;
+	if (propertyName === "env") return `${styleText("red", `Environment variable '${String(error.path[1])}'`)}: ${messageWithoutProperty}`;
+	const optionText = propertyName === "_" ? "Positionals" : `--${propertyName}`;
+	if (error.code === "predicate" && error.expected === "removed") return `${styleText("red", optionText)}: unknown option`;
+	return `${styleText("red", optionText)}: ${messageWithoutProperty}`;
+}).join("\n");
+const task = (fn) => {
+	fn.kind = "task";
+	return fn;
+};
+/**
+* Default schema for the options received by a {@link task}.
+*/
+const defaultOptionsInput = type({
+	_: "string[]",
+	env: "Record<string, string | undefined>"
+});
+/**
+* Create a task that validates its input against a schema.
+*/
+task.strict = (shape, fn) => {
+	const schema = defaultOptionsInput.merge(type.raw(shape)).onUndeclaredKey("reject");
+	const taskFunction = (options, utilities) => {
+		const validationResult = schema(options);
+		if (validationResult instanceof type.errors) throw new TypeError(formatValidationIssues(validationResult), { cause: validationResult });
+		return fn(validationResult, utilities);
+	};
+	taskFunction.kind = "strictTask";
+	taskFunction.schema = schema;
+	return taskFunction;
+};
+//#endregion
+export { task };

package/dist/tasks/types.d.mts

@@ -0,0 +1,60 @@
+import { ParsedOptions } from "../cli/parseOptions.mjs";
+import { Type } from "arktype";
+import { ExecaMethod, ExecaScriptMethod } from "execa";
+
+//#region src/tasks/types.d.ts
+interface TaskUtilities {
+  /**
+   * Run a command using Execa's
+   * {@link https://github.com/sindresorhus/execa/blob/main/docs/scripts.md|script mode}.
+   *
+   * @example
+   * ```ts
+   * const { stdout } = await $`echo ${"hello"}`;
+   * console.log(`stdout = ${stdout}`);
+   * ```
+   *
+   * @see {@link https://github.com/sindresorhus/execa/blob/main/docs/execution.md#%EF%B8%8F-basic-execution|Execa docs}
+   */
+  $: ExecaScriptMethod;
+  /**
+   * Run a command using {@link https://github.com/sindresorhus/execa|Execa}
+   * (e.g., shell command or script).
+   *
+   * @example
+   * ```ts
+   * const { stdout } = await execa`echo 'hello'`;
+   * console.log(stdout);
+   * ```
+   *
+   * @see {@link https://github.com/sindresorhus/execa/blob/main/docs/execution.md#%EF%B8%8F-basic-execution|Execa docs}
+   */
+  command: ExecaMethod;
+  /**
+   * Same as `command`, but inherits the parent process' stdio streams by
+   * default, i.e., logs and errors will be sent directly to the terminal.
+   * Use `command` or `$` if you want to capture the output instead.
+   */
+  exec: ExecaMethod<{
+    stdin: "inherit";
+    stdout: "inherit";
+    stderr: "inherit";
+  }>;
+}
+type DefaultOptionsInput = ParsedOptions & {
+  env: Record<string, string | undefined>;
+};
+type MergePositionals<TOptions> = "_" extends keyof TOptions ? TOptions : TOptions & ParsedOptions;
+type MergeEnvironment<TOptions> = "env" extends keyof TOptions ? TOptions : TOptions & Pick<DefaultOptionsInput, "env">;
+type Task<TOptions = unknown> = (options: MergePositionals<MergeEnvironment<TOptions>>, utilities: TaskUtilities) => unknown;
+type BrandedTaskStrict<TShape = DefaultOptionsInput> = Task<TShape> & {
+  kind: "strictTask";
+  schema: Type<TShape>;
+};
+type BrandedTaskLoose<TOptions = unknown> = Task<TOptions> & {
+  kind: "task";
+  schema: never;
+};
+type BrandedTask<TOptions = unknown> = BrandedTaskLoose<TOptions> | BrandedTaskStrict<TOptions>;
+//#endregion
+export { BrandedTask, BrandedTaskStrict, DefaultOptionsInput, Task };

package/dist/util/getSchemaProperties.mjs

@@ -0,0 +1,34 @@
+import { reservedNames } from "../cli/parseOptions.mjs";
+import { styleText } from "node:util";
+import { type } from "arktype";
+//#region src/util/getSchemaProperties.ts
+const propertyEntry = type({
+	key: "string",
+	"+": "delete"
+});
+const arktypeJson = type({
+	domain: "string",
+	required: propertyEntry.array().default(() => []),
+	optional: propertyEntry.array().default(() => [])
+});
+const getSchemaProperties = (schema) => {
+	const definition = arktypeJson.assert(schema.json);
+	if (definition instanceof type.errors || definition.domain !== "object") return "";
+	const { required, optional } = definition;
+	const requiredProperties = required.map(({ key }) => ({
+		key,
+		isOptional: false
+	}));
+	const optionalProperties = optional.map(({ key }) => ({
+		key,
+		isOptional: true
+	}));
+	const properties = [...requiredProperties, ...optionalProperties];
+	if (properties.length === 0) return "";
+	return `{ ${properties.filter(({ key }) => !reservedNames.has(key)).map(({ key, isOptional }) => {
+		if (isOptional) return styleText("dim", `[${key}]`);
+		return key;
+	}).join(", ")} }`;
+};
+//#endregion
+export { getSchemaProperties };

package/dist/util/loadTaskFile.mjs

@@ -0,0 +1,31 @@
+import { resolve } from "node:path";
+import { loadConfig } from "c12";
+//#region src/util/loadTaskFile.ts
+const loadTaskFile = async (context) => {
+	try {
+		const collection = await loadConfig({
+			cwd: context.taskFile.dir,
+			name: context.taskFile.name,
+			configFile: context.taskFile.base,
+			dotenv: false,
+			rcFile: false,
+			packageJson: false,
+			jitiOptions: { tsconfigPaths: true }
+		});
+		if (!collection.configFile || collection.layers?.length === 0) return {
+			ok: false,
+			error: /* @__PURE__ */ new Error(`Failed to load task file at path ${resolve(context.taskFile.dir, context.taskFile.base)}`)
+		};
+		return {
+			ok: true,
+			value: collection
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error : new Error(String(error))
+		};
+	}
+};
+//#endregion
+export { loadTaskFile };