@haltcase/run 3.0.1 → 4.0.0

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 { bold, gray, yellow } from "colorette";
+import { readdirSync } from "node:fs";
+import { extname } from "node:path";
+import { Spinner } from "@favware/colorette-spinner";
+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: ${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 = bold(name);
+		if (isBrandedTask(value)) {
+			if (value.kind === "strictTask") {
+				const properties = getSchemaProperties(value.schema) || 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/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,34 @@
+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 {
+		await taskFunction({
+			...options,
+			env: process.env
+		}, taskUtilities);
+	} 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 { type } from "arktype";
+import { red } from "colorette";
+//#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 `${red(`Environment variable '${String(error.path[1])}'`)}: ${messageWithoutProperty}`;
+	const optionText = propertyName === "_" ? "Positionals" : `--${propertyName}`;
+	if (error.code === "predicate" && error.expected === "removed") return `${red(optionText)}: unknown option`;
+	return `${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 { type } from "arktype";
+import { dim } from "colorette";
+//#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 dim(`[${key}]`);
+		return key;
+	}).join(", ")} }`;
+};
+//#endregion
+export { getSchemaProperties };

package/dist/util/loadTaskFile.mjs

@@ -0,0 +1,30 @@
+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
+		});
+		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 };

package/dist/util/resolveTaskFile.mjs

@@ -0,0 +1,13 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { SUPPORTED_EXTENSIONS } from "c12";
+//#region src/util/resolveTaskFile.ts
+const extensions = SUPPORTED_EXTENSIONS.filter((extension) => extension.endsWith("js") || extension.endsWith("ts"));
+const resolveTaskFile = (context) => {
+	if (context.taskFile.ext) return resolve(context.taskFile.dir, context.taskFile.name);
+	const foundConfigs = extensions.map((it) => join(context.taskFile.dir, `${context.taskFile.name}${it}`)).filter((path) => existsSync(path));
+	if (foundConfigs.length === 1) return foundConfigs[0];
+	return foundConfigs;
+};
+//#endregion
+export { extensions, resolveTaskFile };

package/package.json

@@ -1,77 +1,79 @@
 {
   "name": "@haltcase/run",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Flexible, function-based task runner where command line options are props",
   "keywords": [
-    "task",
-    "runner",
+    "arktype",
     "command",
-    "function",
-    "typescript",
     "execa",
-    "arktype"
+    "function",
+    "runner",
+    "task",
+    "typescript"
   ],
   "homepage": "https://github.com/haltcase/run#readme",
   "bugs": "https://github.com/haltcase/run/issues",
+  "license": "MIT",
+  "author": "Bo Lingen <bo@haltcase.dev> (https://haltcase.dev)",
   "repository": {
     "type": "git",
     "url": "https://github.com/haltcase/run.git"
   },
-  "license": "MIT",
-  "author": "Bo Lingen <bo@haltcase.dev> (https://haltcase.dev)",
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
-    "hr": "./dist/cli/bin.js"
+    "hr": "./dist/cli/bin.mjs"
   },
   "files": [
     "dist"
   ],
-  "lint-staged": {
-    "*.{js,jsx,ts,tsx,css,yml,yaml}": "pnpm prettier --write"
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "prettier": "@haltcase/style/prettier",
   "dependencies": {
     "@favware/colorette-spinner": "^1.0.1",
-    "arktype": "^2.1.17",
-    "c12": "^3.0.3",
+    "arktype": "^2.2.0",
+    "c12": "^3.3.4",
     "cliui": "^9.0.1",
     "colorette": "^2.0.20",
-    "execa": "^9.5.1"
+    "execa": "^9.6.1"
   },
   "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.3",
     "@haltcase/style": "^7.3.1",
-    "@types/node": "^22.8.6",
-    "eslint": "^9.24.0",
-    "husky": "^9.1.7",
-    "lint-staged": "^15.5.1",
-    "prettier": "^3.5.3",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "@types/node": "^24.13.1",
+    "@typescript/native-preview": "7.0.0-dev.20260608.1",
+    "eslint": "^9.39.4",
+    "oxlint-tsgolint": "^0.23.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.1.24",
+    "vite-plus": "0.1.24",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.24"
   },
   "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
+    "node": ">=22"
   },
   "haltcase.run": {
     "taskDirectory": "./scripts",
     "quiet": true
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "build": "vp pack",
+    "build:watch": "vp pack --watch",
+    "check": "pnpm eslint:check && vp check --no-lint",
     "eslint:check": "eslint src",
-    "format": "eslint --fix src && prettier src --write",
+    "format": "eslint --fix src && vp check --fix --no-lint",
     "hr": "tsx ./src/cli/bin.ts",
-    "prettier:check": "prettier --check src",
-    "test": "vitest",
-    "typescript:check": "tsc --noEmit && echo \"No errors reported by tsc.\""
+    "test": "vp test watch",
+    "test:run": "vp test",
+    "types": "vp check --no-fmt --no-lint"
   }
 }

package/dist/cli/bin.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/cli/bin.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { createHandler } from "./handler.js";
-import { main } from "./main.js";
-const handler = createHandler();
-void main({
-    handler
-});

package/dist/cli/handler.d.ts

@@ -1,28 +0,0 @@
-import { Spinner } from "@favware/colorette-spinner";
-import type { AppConfig } from "../config.js";
-import type { MainContextWithData } from "./main.js";
-export declare const failWith: (spinner: Spinner, message: unknown) => never;
-export declare const write: (message: string) => void;
-interface HelpContextCommand {
-    command: string;
-}
-interface HelpContextFile {
-    taskFileList: true;
-    config: AppConfig;
-}
-interface HelpContextScript extends MainContextWithData {
-    taskList: true;
-}
-type HelpContext = HelpContextCommand | HelpContextFile | HelpContextScript;
-export declare const commandHandler: (_context: HelpContextCommand) => string;
-export declare const taskFileListHandler: (context: HelpContextFile) => string;
-export declare const taskListHandler: (context: HelpContextScript) => string;
-export declare const help: (context: HelpContext) => string;
-export interface Handler {
-    spinner: Spinner;
-    help: (context: HelpContext) => string;
-    write: (message: string) => void;
-    failWith: (message: unknown) => never;
-}
-export declare const createHandler: () => Handler;
-export {};