@peachlife/artisan 0.1.0 → 0.1.2

package/README.md

@@ -1,196 +1,110 @@
 # Artisan
 
-> Artifact-level dogfood tests for command-line tools.
+> **End-to-end artifact testing for CLIs.** Stop merging green unit tests for broken binaries.
 
-Artisan runs the **compiled CLI artifact your users will run** inside clean Docker
-containers, then lets you assert its real stdout, stderr, exit code, config
-handling, and filesystem side effects with familiar JavaScript tests.
+Unit tests verify your logic. Artisan proves your binary actually executes. 
 
-Unit tests can say your code works. Artisan proves the binary works.
+Artisan mounts your compiled CLI into ephemeral Linux containers across a distro matrix (Debian, Alpine, Arch) and lets you assert stdout, stderr, exit codes, and real filesystem mutations using a familiar Vitest API.
 
-## What is Artisan?
+Backed by **Testcontainers**, **Execa**, and **Vitest**.
 
-Artisan is a zero-configuration dogfood testing framework for CLI binaries. It
-mounts your artifact into isolated Linux containers across a distro matrix such
-as Debian, Alpine, and Arch, then runs `*.artisan.test.mjs` tests against it.
+## Why Artisan?
 
-It is built on:
+*   **Catch runtime blindspots:** Detect `glibc` vs `musl` mismatches, missing system dependencies, and hardcoded host paths.
+*   **Agent-proof your workflow:** LLMs are great at writing passing unit tests for code that fails at runtime. Artisan enforces that "done" means the *artifact* works.
+*   **Zero-config discovery:** Automatically finds executables in `package.json#bin`, `./dist`, or `./bin`.
 
-- **Testcontainers** for disposable Docker sandboxes.
-- **Execa** for command execution and stdout/stderr/exit-code capture.
-- **Vitest** for the `test()` and `expect()` API.
+## Quickstart
 
-## Who is it for?
-
-### Agent-assisted development
-
-LLM agents are good at making unit tests pass. They are also good at missing the
-thing users actually execute: the built artifact.
-
-Artisan makes “done” mean:
-
-- the binary exists;
-- it is executable;
-- it starts in a clean sandbox;
-- it handles real arguments, config, paths, and files;
-- it exits with the expected code.
-
-That catches the classic agent failure mode: “all green” while the CLI is broken
-in a real environment.
-
-### CLI authors
-
-If you ship CLIs in Go, Rust, C/C++, Node, Python, Swift, or any other language,
-Artisan helps verify runtime behavior across Linux environments without
-hand-writing Dockerfiles or CI matrices.
-
-It is especially useful for catching:
-
-- `glibc` vs `musl` issues;
-- missing runtime packages;
-- hardcoded host paths;
-- broken config discovery;
-- bad permissions;
-- incorrect stdout/stderr/exit codes;
-- filesystem side effects that only work on your machine.
-
-## Example
-
-Create test file:
-
-```javascript
-// tests/artisan/cli-version.artisan.test.mjs
-import { expect, test } from "@peachlife/artisan";
-
-test("CLI outputs correct version", async ({ run }) => {
-  const { stdout, exitCode } = await run("--version");
-
-  expect(exitCode).toBe(0);
-  expect(stdout).toContain("1.0.0"); // Replace with your real version.
-});
-```
-
-Run it:
+Run Artisan directly. If you don't have tests yet, it will automatically bootstrap your environment, install dependencies, and generate a starter test.
 
 ```bash
-npx @peachlife/artisan test
-```
-
-If your project has exactly one executable artifact in `package.json#bin`, `./dist`,
-or `./bin`, Artisan can usually discover it without config.
-
-## Add explicit config when needed
-
-Use `artisan.config.json` when you want to choose the artifact, distros, setup
-commands, or config fixtures:
-
-```json
-{
-  "artifact": "./dist/mycli",
-  "distros": ["debian:stable-slim", "alpine:latest", "archlinux/archlinux:latest"],
-  "testMatch": "**/*.artisan.test.mjs",
-  "parallel": true
-}
+npx @peachlife/artisan test --artifact ./dist/mycli
 ```
 
-Then run:
-
-```bash
-npx @peachlife/artisan test
 ```
 
-## Test real behavior, not internals
+## The API
 
-Artisan tests should assert what a user can observe.
+Test what users actually observe. Assert on exit codes, output, and container filesystem side-effects.
 
 ```javascript
+// tests/artisan/cli.artisan.test.mjs
 import { expect, test } from "@peachlife/artisan";
 
-test("CLI writes an output file", async ({ run, setup }) => {
+test("writes expected output to the filesystem", async ({ run, setup }) => {
+  // Setup container state
   await setup(["rm -f /tmp/output.txt"]);
 
+  // Execute the compiled artifact
   const { stdout, exitCode } = await run([
     "write-file",
     "/tmp/output.txt",
-    "hello from the sandbox",
+    "unicorn sequence initiated",
   ]);
 
+  // Assert binary execution
   expect(exitCode).toBe(0);
   expect(stdout).toContain("wrote /tmp/output.txt");
 
+  // Assert filesystem side-effects
   await setup([
     "test -f /tmp/output.txt",
-    "grep -q '^hello from the sandbox$' /tmp/output.txt",
+    "grep -q '^unicorn sequence initiated$' /tmp/output.txt",
   ]);
 });
 ```
 
-## Test config safely
+## Matrix Testing via Config
 
-Config bugs are where many CLIs break: `~` paths, missing files, leaked
-credentials, wrong XDG paths, and “works on my machine” assumptions.
+Need to test across different environments? Drop an `artisan.config.json` in your root:
 
-After `artisan.config.json` exists, import a sanitized fixture from a real
-config directory:
-
-```bash
-npx @peachlife/artisan add config ~/.config/mycli --name mycli-config
-```
-
-Artisan copies it into `./fixtures/mycli-config`, scrubs secret-like files, and
-wires the fixture into `artisan.config.json`.
-
-Inside the container, fixture directories are copied under:
-
-```text
-$XDG_CONFIG_HOME/<artifact-name>/
+```json
+{
+  "artifact": "./dist/mycli",
+  "distros": ["debian:stable-slim", "alpine:latest", "archlinux/archlinux:latest"],
+  "testMatch": "**/*.artisan.test.mjs",
+  "parallel": true
+}
 ```
 
-Now your tests can prove the artifact reads config in a clean sandbox instead of
-depending on your host machine.
+## Config Fixtures
 
-## Common commands
+Config parsing is where most CLIs silently fail (`~` paths, wrong XDG locations, missing files). Artisan can capture your host configuration, scrub secrets, and mount it cleanly into the sandbox's `$XDG_CONFIG_HOME`.
 
 ```bash
-# Initialize Artisan in a project.
-npx @peachlife/artisan init -y --artifact ./dist/mycli --distros debian:stable-slim,alpine:latest
-
-# Run every artifact test.
-npx @peachlife/artisan test
-
-# Run one test file.
-npx @peachlife/artisan test ./tests/artisan/cli-version.artisan.test.mjs
-
-# Filter by test name.
-npx @peachlife/artisan test -t "version"
-
-# Debug one distro serially with verbose output.
-npx @peachlife/artisan test --distros alpine:latest --serial --verbose
-
-# Import a sanitized config fixture.
+# Capture, sanitize, and inject real config into your tests
 npx @peachlife/artisan add config ~/.config/mycli --name mycli-config
 ```
 
-Run `npx @peachlife/artisan --help` or `npx @peachlife/artisan <command> --help` for the full
-CLI reference.
+## CLI Reference
 
-## Exit codes
+| Command | Description |
+|---|---|
+| `npx @peachlife/artisan test` | Run all tests across the configured matrix |
+| `npx @peachlife/artisan test <file>` | Run a specific test file |
+| `npx @peachlife/artisan test -t "auth"` | Filter test execution by regex |
+| `npx @peachlife/artisan test --serial` | Run distros sequentially (ideal for debugging) |
+| `npx @peachlife/artisan init` | Scaffold setup without running tests |
+
+### Exit Codes
 
 | Code | Meaning |
-| --- | --- |
-| `0` | All tests passed. |
-| `1` | One or more tests failed, including timed-out commands. |
-| `2` | Usage or configuration error. |
-| `125` | Docker/container startup error. |
-| `130` | Interrupted by the user. |
+|---|---|
+| `0` | All tests passed |
+| `1` | One or more tests failed / timed out |
+| `2` | Usage or configuration error |
+| `125` | Docker/container startup error |
+| `130` | Interrupted by the user |
 
+## CI Integration
 
-## CI shape
+Artisan runs perfectly in CI as long as the runner has Docker access.
 
-A minimal GitHub Actions job looks like this:
+> **CI tip:** if your pipeline manages its own `npm ci` step, pass `--no-install` to `artisan init` or `artisan test --bootstrap` to skip the redundant install.
 
 ```yaml
-name: Artifact tests
+name: Artifact Tests
 on: [push, pull_request]
 
 jobs:
@@ -202,19 +116,10 @@ jobs:
         with:
           node-version: 22
       - run: npm ci
+      - run: npm run build # Ensure your artifact is compiled!
       - run: npx @peachlife/artisan test --no-color
 ```
 
-Docker must be available on the runner.
-
-## Install
-
-Run without installing:
-
-```bash
-npx @peachlife/artisan test
-```
-
 ## License
 
 MIT

package/dist/api/types.d.ts

@@ -0,0 +1,43 @@
+/// <reference lib="dom" />
+
+export type ConfigEntry = string | { src: string; dest: string };
+
+export interface ArtisanConfig {
+	artifact: string;
+	distros: string[];
+	testMatch: string;
+	timeout: number;
+	parallel: boolean;
+	setup: Record<string, string[]>;
+	configs: ConfigEntry[];
+	reporter: "default" | "junit" | "json" | "tap";
+}
+
+export interface RunResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+	timedOut: boolean;
+}
+
+export interface RunOptions {
+	env?: Record<string, string>;
+	timeout?: number;
+	cwd?: string;
+}
+
+export interface ArtisanTestContext {
+	run: (args?: string, options?: RunOptions) => Promise<RunResult>;
+	copyFixture: (localPath: string, containerPath: string) => Promise<void>;
+	setup: (commands: string[]) => Promise<void>;
+}
+
+export {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	test,
+} from "vitest";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@peachlife/artisan",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"type": "module",
 	"bin": {
 		"artisan": "./bin/artisan.mjs"
@@ -48,6 +48,9 @@
 		"fast-glob": "^3.3.3",
 		"testcontainers": "^12.0.3"
 	},
+	"peerDependencies": {
+		"vitest": "^4.0.0"
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.1",
 		"@cyclonedx/cyclonedx-npm": "^5.0.0",
@@ -67,6 +70,7 @@
 	"files": [
 		"src",
 		"bin",
+		"dist",
 		"templates"
 	],
 	"publishConfig": {

package/src/cli/bootstrap.mjs

@@ -0,0 +1,204 @@
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { DEFAULT_DISTROS } from "../core/constants.mjs";
+import { UsageError } from "../utils/errors.mjs";
+import { fileExists } from "../utils/fs.mjs";
+import {
+	readTemplate,
+	renderTemplate,
+	resolveTemplatesDirectory,
+} from "../utils/template.mjs";
+
+// Packages a bootstrapped project must be able to resolve. Artisan re-exports
+// vitest primitives and spawns the vitest CLI, so the consumer must own a single
+// shared vitest instance (declared as a peer in package.json).
+const ARTISAN_PACKAGE = "@peachlife/artisan";
+const VITEST_PACKAGE = "vitest";
+const VITEST_PEER_RANGE = "^4.0.0";
+
+const TEMPLATES_DIR = resolveTemplatesDirectory(
+	import.meta.url,
+	"../../templates",
+);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// The bootstrapping Artisan knows its own version; pin the consumer devDep to it.
+const artisanVersion = JSON.parse(
+	readFileSync(join(__dirname, "../../package.json"), "utf8"),
+).version;
+
+/**
+ * Detect whether a project already has an Artisan config. A project counts as
+ * bootstrapped once artisan.config.json exists.
+ */
+export async function detectBootstrapState(cwd = process.cwd()) {
+	return { hasConfig: await fileExists(join(cwd, "artisan.config.json")) };
+}
+
+/**
+ * Detect the package manager from lockfile presence.
+ * Order: bun > pnpm > yarn > npm (npm is the default fallback).
+ */
+export async function detectPackageManager(cwd = process.cwd()) {
+	if (await fileExists(join(cwd, "bun.lock"))) return "bun";
+	if (await fileExists(join(cwd, "bun.lockb"))) return "bun";
+	if (await fileExists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (await fileExists(join(cwd, "yarn.lock"))) return "yarn";
+	return "npm";
+}
+
+/**
+ * Merge entries into a project's devDependencies, creating package.json if absent.
+ * Fails fast on unparseable JSON instead of clobbering the user's manifest.
+ */
+export async function addDevelopmentDependencies(cwd, dependencies) {
+	const packagePath = join(cwd, "package.json");
+	let package_ = {};
+	if (await fileExists(packagePath)) {
+		const raw = await readFile(packagePath, "utf8");
+		try {
+			package_ = JSON.parse(raw);
+		} catch {
+			throw new UsageError(
+				`Cannot parse ${packagePath}; fix its JSON before bootstrapping.`,
+			);
+		}
+	}
+	package_.devDependencies = { ...package_.devDependencies, ...dependencies };
+	await writeFile(
+		packagePath,
+		`${JSON.stringify(package_, undefined, 2)}\n`,
+		"utf8",
+	);
+}
+
+/**
+ * Run the package manager's install command in a directory.
+ */
+export async function runInstall({ cwd, packageManager }) {
+	await execa(packageManager, ["install"], {
+		cwd,
+		stdio: "inherit",
+		reject: true,
+	});
+}
+
+export function parseDistros(distrosRaw) {
+	if (typeof distrosRaw !== "string") {
+		throw new UsageError("Distros must be a comma-separated string");
+	}
+	const distros = distrosRaw
+		.split(",")
+		.map((d) => d.trim())
+		.filter(Boolean);
+	if (distros.length === 0) {
+		throw new UsageError("At least one distro is required");
+	}
+	return distros;
+}
+
+async function writeConfig({ cwd, artifact, distros, force }) {
+	const configPath = join(cwd, "artisan.config.json");
+	if (!force && (await fileExists(configPath))) {
+		console.log(
+			"Skipped artisan.config.json (already exists, use --force to overwrite)",
+		);
+		return;
+	}
+	const tmpl = await readTemplate(TEMPLATES_DIR, "config.json.tmpl");
+	const distrosJson = distros.map((d) => JSON.stringify(d)).join(", ");
+	const content = renderTemplate(tmpl, {
+		ARTIFACT: artifact,
+		DISTROS: distrosJson,
+	});
+	await writeFile(configPath, content, "utf8");
+	console.log("Created artisan.config.json");
+}
+
+async function writeStarterTest({ cwd, force }) {
+	const testsDirectory = join(cwd, "tests/artisan");
+	await mkdir(testsDirectory, { recursive: true });
+	const testPath = join(testsDirectory, "cli-version.artisan.test.mjs");
+	if (!force && (await fileExists(testPath))) {
+		console.log(
+			"Skipped tests/artisan/cli-version.artisan.test.mjs (already exists)",
+		);
+		return;
+	}
+	const tmpl = await readTemplate(TEMPLATES_DIR, "tests/version.test.mjs.tmpl");
+	await writeFile(testPath, tmpl, "utf8");
+	console.log("Created ./tests/artisan/cli-version.artisan.test.mjs");
+}
+
+async function installDependencies({ cwd, installer }) {
+	await addDevelopmentDependencies(cwd, {
+		[ARTISAN_PACKAGE]: `^${artisanVersion}`,
+		[VITEST_PACKAGE]: VITEST_PEER_RANGE,
+	});
+	const packageManager = await detectPackageManager(cwd);
+	console.log(`Installing dependencies with ${packageManager}...`);
+	await installer({ cwd, packageManager });
+	console.log(`Installed dependencies with ${packageManager}`);
+}
+
+/**
+ * Scaffold Artisan into a project: config, starter test, and (optionally)
+ * devDependency install. Shared by `init` and the first-run `test` gate.
+ *
+ * Defaults to NO install so the pure function is side-effect free; the CLI
+ * layer opts into installing for the user-facing commands.
+ */
+export async function bootstrapProject({
+	cwd = process.cwd(),
+	artifact = "./dist/mycli",
+	distros = DEFAULT_DISTROS.join(","),
+	force = false,
+	install = false,
+	installer = runInstall,
+} = {}) {
+	const distroList = parseDistros(distros);
+	await writeConfig({ cwd, artifact, distros: distroList, force });
+	await writeStarterTest({ cwd, force });
+	if (install) {
+		await installDependencies({ cwd, installer });
+	}
+}
+
+/**
+ * True when stdin is a TTY and no CI runner is detected.
+ */
+export function isInteractive() {
+	return process.stdin.isTTY === true && !process.env.CI;
+}
+
+/**
+ * Ask the user a yes/no bootstrap question. Defaults to yes on empty input.
+ * input/output are injectable for tests.
+ */
+export async function promptBootstrap({
+	input = process.stdin,
+	output = process.stdout,
+} = {}) {
+	const rl = createInterface({ input, output, terminal: false });
+	try {
+		const answer = await rl.question("Bootstrap? [Y/n] ");
+		const value = answer.trim().toLowerCase();
+		return ["", "y", "yes"].includes(value);
+	} finally {
+		rl.close();
+	}
+}
+
+/**
+ * Resolve the three-state bootstrap decision from parsed CLI options.
+ * Returns "always" | "never" | "ask".
+ */
+export function resolveBootstrapDecision(options) {
+	if (options.bootstrap === true) return "always";
+	if (options.bootstrap === false) return "never";
+	return "ask";
+}

package/src/cli/commands/init.mjs

@@ -1,71 +1,19 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { DEFAULT_DISTROS } from "../../core/constants.mjs";
-import { UsageError } from "../../utils/errors.mjs";
-import { fileExists } from "../../utils/fs.mjs";
-import {
-	readTemplate,
-	renderTemplate,
-	resolveTemplatesDirectory,
-} from "../../utils/template.mjs";
+import { bootstrapProject } from "../bootstrap.mjs";
 
-const TEMPLATES_DIR = resolveTemplatesDirectory(
-	import.meta.url,
-	"../../../templates",
-);
-
-function parseDistros(distrosRaw) {
-	if (typeof distrosRaw !== "string") {
-		throw new UsageError("Distros must be a comma-separated string");
-	}
-	const distros = distrosRaw
-		.split(",")
-		.map((d) => d.trim())
-		.filter(Boolean);
-	if (distros.length === 0) {
-		throw new UsageError("At least one distro is required");
-	}
-	return distros;
-}
-
-export async function runInit(options) {
-	const cwd = process.cwd();
-	const artifact = options.artifact ?? "./dist/mycli";
-	const distrosRaw = options.distros ?? DEFAULT_DISTROS.join(",");
-	const distros = parseDistros(distrosRaw);
-	const force = options.force ?? false;
-
-	// Write artisan.config.json
-	const configPath = join(cwd, "artisan.config.json");
-	if (!force && (await fileExists(configPath))) {
-		console.log(
-			`Skipped artisan.config.json (already exists, use --force to overwrite)`,
-		);
-	} else {
-		const tmpl = await readTemplate(TEMPLATES_DIR, "config.json.tmpl");
-		const distrosJson = distros.map((d) => JSON.stringify(d)).join(", ");
-		const content = renderTemplate(tmpl, {
-			ARTIFACT: artifact,
-			DISTROS: distrosJson,
-		});
-		await writeFile(configPath, content, "utf8");
-		console.log(`Created artisan.config.json`);
-	}
-
-	// Write starter test file
-	const testsDirectory = join(cwd, "tests/artisan");
-	await mkdir(testsDirectory, { recursive: true });
-	const testPath = join(testsDirectory, "cli-version.artisan.test.mjs");
-	if (!force && (await fileExists(testPath))) {
-		console.log(
-			`Skipped tests/artisan/cli-version.artisan.test.mjs (already exists)`,
-		);
-	} else {
-		const tmpl = await readTemplate(
-			TEMPLATES_DIR,
-			"tests/version.test.mjs.tmpl",
-		);
-		await writeFile(testPath, tmpl, "utf8");
-		console.log(`Created ./tests/artisan/cli-version.artisan.test.mjs`);
-	}
+/**
+ * Scaffold Artisan into the current project.
+ *
+ * CLI (`artisan init`) installs dependencies by default; `--no-install` skips.
+ * Programmatic callers default to NO install so the function is side-effect
+ * free (unit tests stay network-free).
+ */
+export async function runInit(options = {}) {
+	await bootstrapProject({
+		cwd: process.cwd(),
+		artifact: options.artifact,
+		distros: options.distros,
+		force: options.force ?? false,
+		install: options.install === true,
+		installer: options.installer,
+	});
 }

package/src/cli/commands/test.mjs

@@ -7,6 +7,14 @@ 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";
+import {
+	bootstrapProject,
+	detectBootstrapState,
+	isInteractive,
+	parseDistros,
+	promptBootstrap,
+	resolveBootstrapDecision,
+} from "../bootstrap.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const artisanVitestConfig = join(
@@ -19,12 +27,6 @@ function resolveTimeout(timeout) {
 	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"], {
@@ -32,12 +34,19 @@ async function ensureDockerAvailable() {
 			reject: false,
 		});
 		if (result.exitCode === 0) return;
-		throw dockerUnavailableError(result.stderr || result.stdout);
+		throw new DockerError(
+			`Docker is not running. Start Docker and retry.\n${result.stderr || result.stdout}`,
+		);
 	} catch (error) {
 		if (error instanceof DockerError) throw error;
+		if (error instanceof Error && error.code === "ENOENT") {
+			throw new DockerError(
+				"Docker is not installed.\nInstall it from https://docs.docker.com/engine/install/ and retry.",
+			);
+		}
 		const message =
 			error instanceof Error ? error.message : String(error ?? "unknown error");
-		throw dockerUnavailableError(message);
+		throw new DockerError(`Docker is not available.\n${message}`);
 	}
 }
 
@@ -78,15 +87,81 @@ function buildVitestArguments({ options, merged, testFiles }) {
 	return vitestArguments;
 }
 
+function printBootstrapPlan() {
+	console.log("No Artisan setup found.\n");
+	console.log("Bootstrap this project now? This will:");
+	console.log("  - add @peachlife/artisan and vitest to devDependencies");
+	console.log("  - create artisan.config.json");
+	console.log("  - create tests/artisan/cli-version.artisan.test.mjs");
+	console.log("  - install dependencies\n");
+}
+
+function printSetupInstructions() {
+	console.error("No Artisan setup found in this project.");
+	console.error("");
+	console.error("Get started with:");
+	console.error("  npx @peachlife/artisan init");
+	console.error("");
+	console.error("Or bootstrap on the fly:");
+	console.error("  npx @peachlife/artisan test --bootstrap");
+}
+
+/**
+ * Handle a project with no artisan.config.json before `test` runs.
+ *
+ * Returns `{ exit: <code> }` to short-circuit, or `{ ran: true }` once the
+ * project has been bootstrapped. prompt/interactive/bootstrap are injectable so
+ * the full decision matrix is unit-testable without a TTY, network, or exit.
+ */
+export async function handleFreshProject({
+	cwd,
+	options,
+	prompt = promptBootstrap,
+	interactive = isInteractive,
+	bootstrap = bootstrapProject,
+}) {
+	const decision = resolveBootstrapDecision(options);
+	if (decision === "never" || (decision === "ask" && !interactive())) {
+		printSetupInstructions();
+		return { exit: 1 };
+	}
+	if (decision === "ask") {
+		printBootstrapPlan();
+	}
+	const proceed = decision === "always" ? true : await prompt();
+	if (!proceed) {
+		console.log("\nCancelled.\n");
+		printSetupInstructions();
+		return { exit: 0 };
+	}
+	console.log("\nBootstrapping Artisan...");
+	// CLI-only path: commander always supplies true/false for --install/--no-install,
+	// so `options.install !== false` defaults to install=true for interactive users.
+	await bootstrap({
+		cwd,
+		install: options.install !== false,
+		installer: options.installer,
+	});
+	console.log("\nRunning tests...");
+	return { ran: true };
+}
+
 export async function runTest(files, options) {
+	const cwd = process.cwd();
+	const { hasConfig } = await detectBootstrapState(cwd);
+	if (!hasConfig) {
+		const result = await handleFreshProject({ cwd, options });
+		if (result.exit !== undefined) {
+			// eslint-disable-next-line unicorn/no-process-exit
+			process.exit(result.exit);
+		}
+	}
+
 	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);
+		flags.distros = parseDistros(options.distros);
 	}
 	if (options.reporter !== undefined) flags.reporter = options.reporter;
 	if (options.timeout !== undefined) flags.timeout = options.timeout;

package/src/cli/parser.mjs

@@ -62,6 +62,7 @@ export function createProgram() {
 		.option("--testMatch <glob>", "Test file glob pattern")
 		.option("-y, --yes", "Skip prompts, use defaults/flags")
 		.option("--force", "Overwrite existing config/test files")
+		.option("--no-install", "Skip dependency installation")
 		.action((options) => runInit(options));
 
 	program
@@ -88,6 +89,9 @@ export function createProgram() {
 			parsePositiveInt(v, "retries"),
 		)
 		.option("-b, --bail", "Stop on first failure")
+		.option("--bootstrap", "Bootstrap a fresh project without prompting")
+		.option("--no-bootstrap", "Never bootstrap; exit with setup instructions")
+		.option("--no-install", "Skip dependency install during bootstrap")
 		.action((files, options) => runTest(files, options));
 
 	const add = program.command("add").description("Scaffold tests and fixtures");