@peachlife/artisan 0.1.0

package/src/cli/commands/test.mjs

@@ -0,0 +1,158 @@
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { resolveArtifact } from "../../core/artifact-manager.mjs";
+import { loadConfig, mergeConfigWithFlags } from "../../core/config.mjs";
+import { DEFAULT_XDG_CONFIG_HOME } from "../../core/constants.mjs";
+import { resolveConfigs } from "../../core/fixture-resolver.mjs";
+import { DockerError, UsageError } from "../../utils/errors.mjs";
+import { resolveTestFiles } from "../../utils/glob.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const artisanVitestConfig = join(
+	__dirname,
+	"../../../templates/vitest-artisan.config.mjs",
+);
+
+function resolveTimeout(timeout) {
+	if (timeout === 0) return String(Number.MAX_SAFE_INTEGER);
+	if (timeout) return String(timeout);
+}
+
+function dockerUnavailableError(detail) {
+	return new DockerError(
+		`Docker is not available. Start Docker and retry.\n${detail}`,
+	);
+}
+
+async function ensureDockerAvailable() {
+	try {
+		const result = await execa("docker", ["info"], {
+			stdio: "pipe",
+			reject: false,
+		});
+		if (result.exitCode === 0) return;
+		throw dockerUnavailableError(result.stderr || result.stdout);
+	} catch (error) {
+		if (error instanceof DockerError) throw error;
+		const message =
+			error instanceof Error ? error.message : String(error ?? "unknown error");
+		throw dockerUnavailableError(message);
+	}
+}
+
+function buildVitestArguments({ options, merged, testFiles }) {
+	const configArguments = ["--config", artisanVitestConfig];
+	const vitestArguments = options.watch
+		? ["--watch", ...configArguments, ...testFiles]
+		: ["run", ...configArguments, ...testFiles];
+	let testNamePattern;
+	if (options.testName) {
+		testNamePattern = options.invert
+			? `^(?!.*(?:${options.testName})).*$`
+			: options.testName;
+	}
+	const flagRules = [
+		{
+			flag: "--reporter",
+			value: merged.reporter === "default" ? undefined : merged.reporter,
+		},
+		{
+			flag: "--testTimeout",
+			value: resolveTimeout(merged.timeout),
+		},
+		{ flag: "--testNamePattern", value: testNamePattern },
+		{ flag: "--bail", value: options.bail, boolean: true },
+		{
+			flag: "--retry",
+			value:
+				options.retries === undefined ? undefined : String(options.retries),
+		},
+		{ flag: "--verbose", value: options.verbose, boolean: true },
+	];
+	for (const { flag, value, boolean = false } of flagRules) {
+		if (!value) continue;
+		vitestArguments.push(flag);
+		if (!boolean) vitestArguments.push(value);
+	}
+	return vitestArguments;
+}
+
+export async function runTest(files, options) {
+	const config = await loadConfig();
+	const flags = {};
+	if (options.artifact !== undefined) flags.artifact = options.artifact;
+	if (options.distros !== undefined) {
+		flags.distros = options.distros
+			.split(",")
+			.map((d) => d.trim())
+			.filter(Boolean);
+	}
+	if (options.reporter !== undefined) flags.reporter = options.reporter;
+	if (options.timeout !== undefined) flags.timeout = options.timeout;
+	if (options.serial) flags.parallel = false;
+
+	const merged = mergeConfigWithFlags(config, flags);
+	const testFiles =
+		files.length > 0
+			? files
+			: await resolveTestFiles(merged.testMatch, process.cwd());
+	if (testFiles.length === 0) {
+		console.log("No test files found matching:", merged.testMatch);
+		// eslint-disable-next-line unicorn/no-process-exit
+		process.exit(0);
+	}
+
+	const artifactPath = await resolveArtifact(merged.artifact);
+	const distros = merged.distros;
+	if (distros.length === 0) {
+		throw new UsageError(
+			'No distros configured. Set "distros" in artisan.config.json or pass --distros',
+		);
+	}
+
+	await ensureDockerAvailable();
+	const resolvedConfigs = await resolveConfigs(
+		merged.configs ?? [],
+		process.cwd(),
+		basename(artifactPath),
+	);
+
+	let overallExitCode = 0;
+	const runForDistro = async (distro) => {
+		const setupCommands = merged.setup?.[distro.split(":", 1)[0]] ?? [];
+		const vitestArguments = buildVitestArguments({
+			options,
+			merged,
+			testFiles,
+		});
+
+		const result = await execa("vitest", vitestArguments, {
+			preferLocal: true,
+			localDir: join(__dirname, "../../.."),
+			env: {
+				...process.env,
+				ARTISAN_DISTRO: distro,
+				ARTISAN_ARTIFACT: artifactPath,
+				ARTISAN_SETUP: JSON.stringify(setupCommands),
+				ARTISAN_CONFIGS: JSON.stringify(resolvedConfigs),
+				ARTISAN_XDG_CONFIG_HOME: DEFAULT_XDG_CONFIG_HOME,
+				...(options.noColor && { NO_COLOR: "1" }),
+			},
+			stdio: options.quiet ? "pipe" : "inherit",
+			reject: false,
+		});
+		if (result.exitCode !== 0) overallExitCode = 1;
+	};
+
+	if (merged.parallel) {
+		// eslint-disable-next-line unicorn/no-array-callback-reference
+		await Promise.all(distros.map(runForDistro));
+	} else {
+		for (const distro of distros) {
+			await runForDistro(distro);
+		}
+	}
+	// eslint-disable-next-line unicorn/no-process-exit
+	process.exit(overallExitCode);
+}

package/src/cli/parser.mjs

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { UsageError } from "../utils/errors.mjs";
+import { runAdd } from "./commands/add.mjs";
+import { runInit } from "./commands/init.mjs";
+import { runTest } from "./commands/test.mjs";
+
+function parseNonNegativeInt(value, label) {
+	if (!/^\d+$/.test(value)) {
+		throw new UsageError(
+			`--${label} must be a non-negative integer, got: ${value}`,
+		);
+	}
+	return Number(value);
+}
+
+function parsePositiveInt(value, label) {
+	const n = parseNonNegativeInt(value, label);
+	if (n === 0) {
+		throw new UsageError(
+			`--${label} must be a positive integer (> 0), got: ${value}`,
+		);
+	}
+	return n;
+}
+
+const DEFAULT_TESTS_DIR = "./tests/";
+const OPT_DIR = "--dir <path>";
+const OPT_DIR_DESC = "Target directory";
+const OPT_FORCE_DESC = "Overwrite existing file";
+
+function addScaffoldCommand(parent, name, description, configureFunction) {
+	const command = parent
+		.command(name)
+		.description(description)
+		.option(OPT_DIR, OPT_DIR_DESC, DEFAULT_TESTS_DIR)
+		.option("--force", OPT_FORCE_DESC);
+	if (configureFunction) configureFunction(command);
+	command.action((options) => runAdd(name, options));
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const package_ = JSON.parse(
+	readFileSync(join(__dirname, "../../package.json"), "utf8"),
+);
+
+export function createProgram() {
+	const program = new Command();
+
+	program
+		.name("artisan")
+		.description("Test CLI artifacts in isolated Linux sandboxes.")
+		.version(package_.version);
+
+	program
+		.command("init")
+		.description("Scaffold Artisan into the current project")
+		.option("-a, --artifact <path>", "Path to compiled CLI binary")
+		.option("-d, --distros <list>", "Comma-separated Docker images")
+		.option("--testMatch <glob>", "Test file glob pattern")
+		.option("-y, --yes", "Skip prompts, use defaults/flags")
+		.option("--force", "Overwrite existing config/test files")
+		.action((options) => runInit(options));
+
+	program
+		.command("test [files...]")
+		.description("Run tests across configured distros")
+		.option(
+			"-t, --testName <pattern>",
+			"Filter by test name (substring or regex)",
+		)
+		.option("-i, --invert", "Run tests that do NOT match the -t filter")
+		.option("-d, --distros <list>", "Override the distro matrix")
+		.option("-a, --artifact <path>", "Override the artifact path")
+		.option("-w, --watch", "Re-run tests on file changes")
+		.option("-r, --reporter <name>", "default, junit, json, tap")
+		.option("--timeout <ms>", "Override per-test timeout (ms)", (v) =>
+			parseNonNegativeInt(v, "timeout"),
+		)
+		.option("--no-color", "Disable ANSI color codes")
+		.option("-q, --quiet", "Only output failures and summary")
+		.option("-v, --verbose", "Print full Docker and Execa output")
+		.option("--parallel", "Run distro matrix in parallel (default)")
+		.option("-s, --serial", "Run distro matrix sequentially")
+		.option("--retries <n>", "Retry failed tests up to N times", (v) =>
+			parsePositiveInt(v, "retries"),
+		)
+		.option("-b, --bail", "Stop on first failure")
+		.action((files, options) => runTest(files, options));
+
+	const add = program.command("add").description("Scaffold tests and fixtures");
+
+	addScaffoldCommand(add, "version", "Scaffold a CLI version test");
+	addScaffoldCommand(add, "help", "Scaffold a CLI help test");
+	addScaffoldCommand(add, "custom", "Scaffold a custom test", (command) => {
+		command.requiredOption("-n, --name <name>", "Test name");
+	});
+
+	add
+		.command("config <source>")
+		.description(
+			"Scaffold a committed config fixture from a local config directory",
+		)
+		.option(
+			"-n, --name <name>",
+			"Fixture directory name (default: basename of source)",
+		)
+		.option("--raw", "Copy without sanitizing secrets, caches, or temp files")
+		.option("--force", "Overwrite existing fixture directory")
+		.action((source, options) => runAdd("config", { ...options, source }));
+
+	return program;
+}

package/src/core/artifact-manager.mjs

@@ -0,0 +1,137 @@
+import {
+	access,
+	constants,
+	readdir,
+	readFile,
+	realpath,
+	stat,
+} from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { UsageError } from "../utils/errors.mjs";
+
+const COMMON_ARTIFACT_DIRS = ["dist", "bin"];
+
+async function isExecutableFile(path) {
+	try {
+		const stats = await stat(path);
+		if (!stats.isFile()) return false;
+		await access(path, constants.X_OK);
+		return true;
+	} catch (error) {
+		if (
+			error?.code === "ENOENT" ||
+			error?.code === "ENOTDIR" ||
+			error?.code === "EACCES"
+		) {
+			return false;
+		}
+		throw error;
+	}
+}
+
+async function packageBinCandidates(cwd) {
+	try {
+		const raw = await readFile(join(cwd, "package.json"), "utf8");
+		const package_ = JSON.parse(raw);
+		if (typeof package_.bin === "string") return [resolve(cwd, package_.bin)];
+		if (
+			package_.bin &&
+			typeof package_.bin === "object" &&
+			!Array.isArray(package_.bin)
+		) {
+			return Object.values(package_.bin)
+				.filter((value) => typeof value === "string" && value.trim() !== "")
+				.map((value) => resolve(cwd, value));
+		}
+		return [];
+	} catch (error) {
+		if (error?.code === "ENOENT") return [];
+		if (error instanceof SyntaxError) {
+			throw new UsageError(
+				`package.json contains invalid JSON at ${join(cwd, "package.json")}`,
+			);
+		}
+		throw error;
+	}
+}
+
+async function directoryArtifactCandidates(cwd) {
+	const candidates = [];
+	for (const directoryName of COMMON_ARTIFACT_DIRS) {
+		const directory = join(cwd, directoryName);
+		let entries;
+		try {
+			entries = await readdir(directory, { withFileTypes: true });
+		} catch (error) {
+			if (error?.code === "ENOENT" || error?.code === "ENOTDIR") continue;
+			throw error;
+		}
+		for (const entry of entries) {
+			if (entry.isFile()) candidates.push(join(directory, entry.name));
+		}
+	}
+	return candidates;
+}
+
+async function discoverArtifact(cwd) {
+	const candidates = [
+		...(await packageBinCandidates(cwd)),
+		...(await directoryArtifactCandidates(cwd)),
+	];
+	const unique = [...new Set(candidates)];
+	const realCwd = await realpath(cwd);
+	const executable = [];
+	for (const candidate of unique) {
+		try {
+			const realCandidate = await realpath(candidate);
+			const relativePath = relative(realCwd, realCandidate);
+			if (relativePath.startsWith("..") || isAbsolute(relativePath)) continue;
+		} catch {
+			continue;
+		}
+		if (await isExecutableFile(candidate)) executable.push(candidate);
+	}
+	if (executable.length === 1) return executable[0];
+	if (executable.length > 1) {
+		throw new UsageError(
+			`Multiple executable artifacts found: ${executable.join(", ")}. Pass --artifact or set "artifact" in artisan.config.json`,
+		);
+	}
+	throw new UsageError(
+		'No artifact specified and no executable artifact was auto-discovered. Set "artifact" in artisan.config.json or pass --artifact',
+	);
+}
+
+export async function resolveArtifact(artifactPath, cwd = process.cwd()) {
+	if (
+		artifactPath === undefined ||
+		artifactPath === null ||
+		artifactPath.trim?.() === ""
+	) {
+		return discoverArtifact(cwd);
+	}
+	if (typeof artifactPath !== "string") {
+		throw new UsageError("Artifact path must be a string");
+	}
+	const abs = isAbsolute(artifactPath)
+		? artifactPath
+		: resolve(cwd, artifactPath);
+	try {
+		await access(abs, constants.F_OK);
+	} catch (error) {
+		if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+			throw new UsageError(`Artifact not found: ${abs}`);
+		}
+		throw new UsageError(`Cannot access artifact at ${abs}: ${error.message}`);
+	}
+	const stats = await stat(abs);
+	if (!stats.isFile()) {
+		throw new UsageError(`Artifact is not a file: ${abs}`);
+	}
+	try {
+		await access(abs, constants.X_OK);
+	} catch {
+		throw new UsageError(`Artifact is not executable: ${abs}`);
+	}
+	return abs;
+}

package/src/core/config.mjs

@@ -0,0 +1,139 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { UsageError } from "../utils/errors.mjs";
+import { DEFAULT_DISTROS } from "./constants.mjs";
+
+const DEFAULTS = {
+	artifact: "",
+	distros: DEFAULT_DISTROS,
+	testMatch: "**/*.artisan.test.mjs",
+	timeout: undefined,
+	parallel: true,
+	setup: {},
+	reporter: "default",
+	configs: [],
+};
+
+function validateConfigEntry(entry) {
+	if (typeof entry === "string") {
+		if (entry.trim() === "")
+			throw new UsageError("configs entry must be a non-empty path");
+		return;
+	}
+	if (typeof entry === "object" && entry !== null) {
+		if (typeof entry.src !== "string" || entry.src.trim() === "") {
+			throw new UsageError('configs object entry missing valid "src"');
+		}
+		if (typeof entry.dest !== "string" || entry.dest.trim() === "") {
+			throw new UsageError('configs object entry missing valid "dest"');
+		}
+		return;
+	}
+	throw new UsageError(
+		`configs entry must be a string or {src, dest} object, got: ${typeof entry}`,
+	);
+}
+
+function validateConfigs(configs) {
+	if (!Array.isArray(configs)) {
+		throw new UsageError('"configs" in artisan.config.json must be an array');
+	}
+	for (const entry of configs) validateConfigEntry(entry);
+}
+
+function assertStringArray(value, label) {
+	if (
+		!Array.isArray(value) ||
+		value.some((v) => typeof v !== "string" || v.trim() === "")
+	) {
+		throw new UsageError(`"${label}" must be an array of non-empty strings`);
+	}
+}
+
+function validateSetup(setup) {
+	if (typeof setup !== "object" || Array.isArray(setup) || setup === null) {
+		throw new UsageError('"setup" must be an object of distro -> command[]');
+	}
+	for (const [key, cmds] of Object.entries(setup)) {
+		assertStringArray(cmds, `setup["${key}"]`);
+	}
+}
+
+function validateConfigShape(config) {
+	if (config.artifact !== undefined && typeof config.artifact !== "string") {
+		throw new UsageError('"artifact" must be a string');
+	}
+	if (config.distros !== undefined)
+		assertStringArray(config.distros, "distros");
+	if (
+		config.timeout !== undefined &&
+		(typeof config.timeout !== "number" || config.timeout < 0)
+	) {
+		throw new UsageError(
+			'"timeout" must be a non-negative number (ms), 0 means no timeout',
+		);
+	}
+	if (config.parallel !== undefined && typeof config.parallel !== "boolean") {
+		throw new UsageError('"parallel" must be a boolean');
+	}
+	if (config.setup !== undefined) validateSetup(config.setup);
+	if (config.reporter !== undefined && typeof config.reporter !== "string") {
+		throw new UsageError('"reporter" must be a string');
+	}
+	if (config.testMatch !== undefined && typeof config.testMatch !== "string") {
+		throw new UsageError('"testMatch" must be a string');
+	}
+}
+
+export async function readJsonConfig(configPath, { optional = false } = {}) {
+	try {
+		const raw = await readFile(configPath, "utf8");
+		try {
+			const config = JSON.parse(raw);
+			if (
+				config === null ||
+				Array.isArray(config) ||
+				typeof config !== "object"
+			) {
+				throw new UsageError(
+					`artisan.config.json must contain a JSON object at ${configPath}`,
+				);
+			}
+			return config;
+		} catch (error) {
+			if (error instanceof UsageError) throw error;
+			throw new UsageError(
+				`artisan.config.json contains invalid JSON at ${configPath}`,
+			);
+		}
+	} catch (error) {
+		if (error instanceof UsageError) throw error;
+		if (optional && error?.code === "ENOENT") return {};
+		if (error?.code === "ENOENT") {
+			throw new UsageError(
+				"artisan.config.json not found — run `artisan init` first",
+			);
+		}
+		throw error;
+	}
+}
+
+export async function loadConfig(cwd = process.cwd()) {
+	const configPath = join(cwd, "artisan.config.json");
+	const fileConfig = await readJsonConfig(configPath, { optional: true });
+	if (fileConfig.configs !== undefined) {
+		validateConfigs(fileConfig.configs);
+	}
+	validateConfigShape(fileConfig);
+	return { ...DEFAULTS, ...fileConfig };
+}
+
+export function mergeConfigWithFlags(config, flags) {
+	const merged = { ...config };
+	for (const [key, value] of Object.entries(flags)) {
+		if (value !== undefined && value !== null) {
+			merged[key] = value;
+		}
+	}
+	return merged;
+}

package/src/core/constants.mjs

@@ -0,0 +1,5 @@
+// No default timeout. Pass --timeout <ms> or set "timeout" in artisan.config.json.
+// Per-command timeout is also uncapped by default.
+export const DEFAULT_XDG_CONFIG_HOME = "/root/.config";
+export const BINARY_MOUNT_DIR = "/usr/local/bin";
+export const DEFAULT_DISTROS = ["alpine:3", "debian:bookworm-slim"];