@peachlife/artisan 0.1.0

package/src/core/container-manager.mjs

@@ -0,0 +1,240 @@
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { join as joinPosix } from "node:path/posix";
+import { GenericContainer } from "testcontainers";
+import { DockerError } from "../utils/errors.mjs";
+import { BINARY_MOUNT_DIR } from "./constants.mjs";
+
+const NO_CAP = 0;
+const SH_C = ["sh", "-c"];
+const ERR_NOT_STARTED = "Container not started";
+
+function parseChar(state, char) {
+	if (state.isEscaped) {
+		state.current += char;
+		state.isEscaped = false;
+		return;
+	}
+	if (char === "\\" && !state.isInSingle) {
+		state.isEscaped = true;
+		return;
+	}
+	if (char === "'" && !state.isInDouble) {
+		state.isInSingle = !state.isInSingle;
+		state.isInToken = true;
+		return;
+	}
+	if (char === '"' && !state.isInSingle) {
+		state.isInDouble = !state.isInDouble;
+		state.isInToken = true;
+		return;
+	}
+	if (/\s/.test(char) && !state.isInSingle && !state.isInDouble) {
+		if (state.isInToken) {
+			state.parsed.push(state.current);
+			state.current = "";
+			state.isInToken = false;
+		}
+		return;
+	}
+	state.current += char;
+	state.isInToken = true;
+}
+
+function splitArguments(arguments_) {
+	const state = {
+		parsed: [],
+		current: "",
+		isInToken: false,
+		isInSingle: false,
+		isInDouble: false,
+		isEscaped: false,
+	};
+	for (const char of arguments_) parseChar(state, char);
+	if (state.isEscaped)
+		throw new Error("Malformed args string: trailing backslash");
+	if (state.isInSingle)
+		throw new Error("Malformed args string: unmatched single quote");
+	if (state.isInDouble)
+		throw new Error("Malformed args string: unmatched double quote");
+	if (state.isInToken) state.parsed.push(state.current);
+	return state.parsed;
+}
+
+function splitExecOutput(output) {
+	if (Array.isArray(output)) return [output[0] ?? "", output[1] ?? ""];
+	if (typeof output === "string") return [output, ""];
+	return ["", ""];
+}
+
+function errorMessage(error) {
+	return error instanceof Error
+		? error.message
+		: String(error ?? "unknown error");
+}
+
+export class ContainerManager {
+	#distro;
+	#artifactPath;
+	#setupCommands;
+	#configs;
+	#env;
+	#container = undefined;
+
+	constructor(distro, artifactPath, options = {}) {
+		this.#distro = distro;
+		this.#artifactPath = artifactPath;
+		this.#setupCommands = options.setupCommands ?? [];
+		this.#configs = options.configs ?? [];
+		this.#env = options.env ?? {};
+	}
+
+	get #mountTarget() {
+		return joinPosix(BINARY_MOUNT_DIR, basename(this.#artifactPath));
+	}
+
+	/**
+	 * Shared exec with optional timeout. timeout <= 0 means no cap (the
+	 * per-test timeout is the authoritative safety net). When a timeout fires,
+	 * the container is stopped and a timedOut result is returned.
+	 */
+	async #execBounded(command, execOptions, timeout, label = "exec") {
+		let isTimedOut = false;
+		let timeoutId;
+		const execPromise = this.#container
+			.exec(command, execOptions)
+			// eslint-disable-next-line unicorn/prefer-await
+			.catch((error) => {
+				if (isTimedOut) return { output: ["", ""], exitCode: 1 };
+				throw error;
+			});
+		const timeoutPromise =
+			timeout > 0
+				? new Promise((resolve) => {
+						timeoutId = setTimeout(() => {
+							isTimedOut = true;
+							resolve({ timedOut: true });
+						}, timeout);
+					})
+				: undefined;
+		try {
+			const result = timeoutPromise
+				? await Promise.race([execPromise, timeoutPromise])
+				: await execPromise;
+			if (timeoutId) clearTimeout(timeoutId);
+			if (result?.timedOut) {
+				await this.stop();
+				return {
+					stdout: "",
+					stderr: "Command timed out",
+					exitCode: 1,
+					timedOut: true,
+				};
+			}
+			const [stdout, stderr] = splitExecOutput(result.output);
+			return {
+				stdout,
+				stderr,
+				exitCode: result.exitCode ?? 0,
+				timedOut: false,
+			};
+		} catch (error) {
+			if (timeoutId) clearTimeout(timeoutId);
+			throw new DockerError(`${label} failed: ${errorMessage(error)}`);
+		}
+	}
+
+	async start() {
+		if (this.#container) return;
+		try {
+			let builder = new GenericContainer(this.#distro)
+				.withCommand([...SH_C, "tail -f /dev/null"])
+				.withBindMounts([
+					{
+						source: this.#artifactPath,
+						target: this.#mountTarget,
+						mode: "ro",
+					},
+				])
+				.withEnvironment(this.#env);
+
+			const files = this.#configs.filter((c) => !c.isDir);
+			const directories = this.#configs.filter((c) => c.isDir);
+			if (files.length > 0) {
+				builder = builder.withCopyFilesToContainer(
+					files.map((c) => ({ source: c.source, target: c.target })),
+				);
+			}
+			if (directories.length > 0) {
+				builder = builder.withCopyDirectoriesToContainer(
+					directories.map((c) => ({ source: c.source, target: c.target })),
+				);
+			}
+
+			this.#container = await builder.start();
+
+			for (const command of this.#setupCommands) {
+				const result = await this.#execBounded([...SH_C, command], {}, NO_CAP);
+				if (result.exitCode !== 0) {
+					throw new DockerError(
+						`setup cmd failed for ${this.#distro}: ${command}\n${result.stderr || result.stdout}`,
+					);
+				}
+			}
+		} catch (error) {
+			if (this.#container) {
+				try {
+					await this.#container.stop();
+					// eslint-disable-next-line no-empty
+				} catch {}
+				this.#container = undefined;
+			}
+			if (error instanceof DockerError) throw error;
+			throw new DockerError(
+				`Failed to start container for ${this.#distro}: ${errorMessage(error)}`,
+			);
+		}
+	}
+
+	async exec(arguments_, options = {}) {
+		if (!this.#container) throw new DockerError(ERR_NOT_STARTED);
+		const {
+			env: environment = {},
+			timeout = NO_CAP,
+			cwd = BINARY_MOUNT_DIR,
+		} = options;
+		const command = [
+			this.#mountTarget,
+			...(Array.isArray(arguments_) ? arguments_ : splitArguments(arguments_)),
+		];
+		return this.#execBounded(
+			command,
+			{ env: environment, workingDir: cwd },
+			timeout,
+			"exec",
+		);
+	}
+
+	async shell(command, options = {}) {
+		if (!this.#container) throw new DockerError(ERR_NOT_STARTED);
+		const { timeout = NO_CAP } = options;
+		return this.#execBounded([...SH_C, command], {}, timeout, "shell");
+	}
+
+	async copyFile(localPath, containerPath) {
+		if (!this.#container) throw new DockerError(ERR_NOT_STARTED);
+		const st = await stat(localPath);
+		const entry = { source: localPath, target: containerPath };
+		if (st.isDirectory()) {
+			await this.#container.copyDirectoriesToContainer([entry]);
+		} else {
+			await this.#container.copyFilesToContainer([entry]);
+		}
+	}
+
+	async stop() {
+		if (!this.#container) return;
+		await this.#container.stop();
+		this.#container = undefined;
+	}
+}

package/src/core/fixture-resolver.mjs

@@ -0,0 +1,97 @@
+import { realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import { join as joinPosix } from "node:path/posix";
+import { UsageError } from "../utils/errors.mjs";
+
+/**
+ * @typedef {{ source: string; target: string; isDir: boolean }} ResolvedConfig
+ */
+
+function validateEntrySource(source_, destination) {
+	if (source_.startsWith("~")) {
+		throw new UsageError(
+			`fixture src "${source_}" must not start with "~" — scaffold it with: artisan add config ${source_}`,
+		);
+	}
+	if (isAbsolute(source_)) {
+		throw new UsageError(
+			`fixture src "${source_}" must be repo-relative, not absolute — copy it into ./fixtures/ first`,
+		);
+	}
+	if (destination !== undefined && !isAbsolute(destination)) {
+		throw new UsageError(
+			`dest "${destination}" must be an absolute container path`,
+		);
+	}
+}
+
+async function resolveEntrySource(source_, source, repoRoot) {
+	try {
+		const real = await realpath(source);
+		const relativeToRoot = relative(repoRoot, real);
+		if (relativeToRoot.startsWith("..") || isAbsolute(relativeToRoot)) {
+			throw new UsageError(
+				`fixture "${source_}" escapes the project root — copy it into ./fixtures/ first`,
+			);
+		}
+		const st = await stat(real);
+		return { real, st };
+	} catch (error) {
+		if (error instanceof UsageError) throw error;
+		if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+			throw new UsageError(
+				`fixture "${source_}" not found at ${source} — scaffold it with: artisan add config ${source_}`,
+			);
+		}
+		throw error;
+	}
+}
+
+async function resolveEntry(entry, cwd, repoRoot, defaultDestinationDirectory) {
+	const source_ = typeof entry === "string" ? entry : entry.src;
+	const destination = typeof entry === "string" ? undefined : entry.dest;
+
+	validateEntrySource(source_, destination);
+
+	const source = resolve(cwd, source_);
+	const { real, st } = await resolveEntrySource(source_, source, repoRoot);
+
+	let target;
+	if (destination) {
+		target = destination;
+	} else if (st.isDirectory()) {
+		target = defaultDestinationDirectory;
+	} else {
+		target = joinPosix(defaultDestinationDirectory, basename(source_));
+	}
+
+	return { source: real, target, isDir: st.isDirectory() };
+}
+
+/**
+ * Validate and resolve config entries to absolute source/target pairs.
+ *
+ * @param {Array<string|{src: string, dest: string}>} configs
+ * @param {string} cwd - project root (absolute)
+ * @param {string} artifactName - name used as XDG sub-directory
+ * @param {string} [xdgBase='/root/.config'] - base for XDG config dir
+ * @returns {Promise<ResolvedConfig[]>}
+ */
+export async function resolveConfigs(
+	configs,
+	cwd,
+	artifactName,
+	xdgBase = "/root/.config",
+) {
+	const defaultDestinationDirectory = joinPosix(xdgBase, artifactName);
+	const repoRoot = await realpath(cwd);
+	const resolved = [];
+
+	for (const entry of configs) {
+		resolved.push(
+			await resolveEntry(entry, cwd, repoRoot, defaultDestinationDirectory),
+		);
+	}
+
+	return resolved;
+}

package/src/core/sanitizer.mjs

@@ -0,0 +1,83 @@
+import { cp, mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+
+const SCRUB_PATTERNS = [
+	/^\.env$/,
+	/^\.env\..+$/,
+	/^credentials?$/,
+	/^creds$/,
+	/\.token$/,
+	/\.key$/,
+	/\.pem$/,
+	/^id_\w+$/,
+	/\.pfx$/,
+	/\.p12$/,
+	/^temp$/,
+	/^tmp$/,
+	/^backups?$/,
+	/^cache$/,
+	/^\.cache$/,
+];
+
+function shouldScrub(name) {
+	return SCRUB_PATTERNS.some((p) => p.test(name));
+}
+
+export async function sanitizeConfigDirectory(
+	sourceDirectory,
+	destinationDirectory,
+	options = {},
+) {
+	const { raw = false } = options;
+	const copied = [];
+	const scrubbed = [];
+
+	await mkdir(destinationDirectory, { recursive: true });
+
+	if (raw) {
+		await cp(sourceDirectory, destinationDirectory, { recursive: true });
+		return { copied: [], scrubbed: [], manifestPath: undefined, raw: true };
+	}
+
+	await copyFiltered(sourceDirectory, destinationDirectory, "");
+
+	const manifestPath = `${destinationDirectory}.artisan-sanitized`;
+	await writeFile(
+		manifestPath,
+		JSON.stringify(
+			{
+				scaffoldedFrom: basename(sourceDirectory),
+				scaffoldedAt: new Date().toISOString(),
+				scrubbed,
+				note: "Re-scaffold with: artisan add config <source>",
+			},
+			undefined,
+			2,
+		),
+	);
+
+	return { copied, scrubbed, manifestPath, raw: false };
+
+	async function copyFiltered(source, destination, relativePath) {
+		const entries = await readdir(source, { withFileTypes: true });
+		entries.sort((a, b) => a.name.localeCompare(b.name));
+		for (const entry of entries) {
+			const childRelative = relativePath
+				? `${relativePath}/${entry.name}`
+				: entry.name;
+			const sourcePath = join(source, entry.name);
+			const destinationPath = join(destination, entry.name);
+			if (shouldScrub(entry.name) || entry.isSymbolicLink()) {
+				scrubbed.push(childRelative);
+				continue;
+			}
+			if (entry.isDirectory()) {
+				await mkdir(destinationPath, { recursive: true });
+				await copyFiltered(sourcePath, destinationPath, childRelative);
+			} else {
+				await cp(sourcePath, destinationPath);
+				copied.push(childRelative);
+			}
+		}
+	}
+}

package/src/utils/errors.mjs

@@ -0,0 +1,28 @@
+export class ArtisanError extends Error {
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.name = "ArtisanError";
+		this.exitCode = exitCode;
+	}
+}
+
+export class UsageError extends ArtisanError {
+	constructor(message) {
+		super(message, 2);
+		this.name = "UsageError";
+	}
+}
+
+export class DockerError extends ArtisanError {
+	constructor(message) {
+		super(message, 125);
+		this.name = "DockerError";
+	}
+}
+
+export class InterruptError extends ArtisanError {
+	constructor(message = "Interrupted") {
+		super(message, 130);
+		this.name = "InterruptError";
+	}
+}

package/src/utils/fs.mjs

@@ -0,0 +1,11 @@
+import { access } from "node:fs/promises";
+
+export async function fileExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch (error) {
+		if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return false;
+		throw error;
+	}
+}

package/src/utils/glob.mjs

@@ -0,0 +1,5 @@
+import fg from "fast-glob";
+
+export async function resolveTestFiles(pattern, cwd) {
+	return fg(pattern, { cwd, absolute: true });
+}

package/src/utils/path.mjs

@@ -0,0 +1,9 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export function expandUserPath(path, cwd = process.cwd()) {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+	if (isAbsolute(path)) return path;
+	return resolve(cwd, path);
+}

package/src/utils/template.mjs

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function resolveTemplatesDirectory(importMetaUrl, relativePath) {
+	return join(dirname(fileURLToPath(importMetaUrl)), relativePath);
+}
+
+export async function readTemplate(templatesDirectory, name) {
+	return readFile(join(templatesDirectory, name), "utf8");
+}
+
+export function renderTemplate(tmpl, variables) {
+	return tmpl.replaceAll(/\{\{(\w+)\}\}/g, (_, key) => variables[key] ?? "");
+}

package/src/utils/validation.mjs

@@ -0,0 +1,13 @@
+import { UsageError } from "./errors.mjs";
+
+export function validateSinglePathName(name, label) {
+	if (
+		!name ||
+		name === "." ||
+		name === ".." ||
+		name.includes("/") ||
+		name.includes("\\")
+	) {
+		throw new UsageError(`--name must be a single ${label}, not a path`);
+	}
+}

package/templates/config.json.tmpl

@@ -0,0 +1,9 @@
+{
+  "artifact": "{{ARTIFACT}}",
+  "distros": [{{DISTROS}}],
+  "testMatch": "**/*.artisan.test.mjs",
+  "parallel": true,
+  "setup": {},
+  "configs": [],
+  "reporter": "default"
+}

package/templates/tests/custom.test.mjs.tmpl

@@ -0,0 +1,7 @@
+import { test, expect } from '@peachlife/artisan';
+
+test('{{TEST_NAME}}', async ({ run, copyFixture, setup }) => {
+  const { stdout, stderr, exitCode } = await run('');
+
+  expect(exitCode).toBe(0);
+});

package/templates/tests/help.test.mjs.tmpl

@@ -0,0 +1,8 @@
+import { test, expect } from '@peachlife/artisan';
+
+test('CLI help shows usage', async ({ run }) => {
+  const { stdout, exitCode } = await run('--help');
+
+  expect(exitCode).toBe(0);
+  expect(stdout).toContain('Usage');
+});

package/templates/tests/version.test.mjs.tmpl

@@ -0,0 +1,8 @@
+import { test, expect } from '@peachlife/artisan';
+
+test('CLI outputs correct version', async ({ run }) => {
+  const { stdout, exitCode } = await run('--version');
+
+  expect(exitCode).toBe(0);
+  expect(stdout).toMatch(/\d+\.\d+\.\d+/);
+});

package/templates/vitest-artisan.config.mjs

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		include: ["**/*.artisan.test.mjs"],
+		exclude: ["**/node_modules/**", "**/.review/**"],
+		testTimeout: 300_000,
+	},
+});