@step-forge/step-forge 0.0.22 → 0.0.24

package/dist/cli.cjs

@@ -1,12 +1,17 @@
 #!/usr/bin/env bun
-const require_gherkinParser = require("./gherkinParser-BT40q_i3.cjs");
+const require_gherkinParser = require("./gherkinParser-_ZgvELdy.cjs");
 const require_hooks = require("./hooks-Be0cjULN.cjs");
 const require_engine = require("./engine-vqA-eL_T.cjs");
 let node_path = require("node:path");
 node_path = require_gherkinParser.__toESM(node_path, 1);
 let node_url = require("node:url");
 let node_fs_promises = require("node:fs/promises");
+let node_fs = require("node:fs");
+node_fs = require_gherkinParser.__toESM(node_fs, 1);
 let node_util = require("node:util");
+let node_child_process = require("node:child_process");
+let node_readline = require("node:readline");
+node_readline = require_gherkinParser.__toESM(node_readline, 1);
 //#region src/runtime/config.ts
 const DEFAULT_FEATURES = "**/*.feature";
 const DEFAULT_STEPS = "**/*.steps.ts";
@@ -164,14 +169,14 @@ function selectScenarios(scenarios, options) {
 }
 //#endregion
 //#region src/runtime/reporters.ts
-const useColor = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
-const wrap = (open, close) => (s) => useColor ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+const useColor$2 = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
+const wrap$1 = (open, close) => (s) => useColor$2 ? `\x1b[${open}m${s}\x1b[${close}m` : s;
 const c = {
-	green: wrap(32, 39),
-	red: wrap(31, 39),
-	yellow: wrap(33, 39),
-	dim: wrap(2, 22),
-	bold: wrap(1, 22)
+	green: wrap$1(32, 39),
+	red: wrap$1(31, 39),
+	yellow: wrap$1(33, 39),
+	dim: wrap$1(2, 22),
+	bold: wrap$1(1, 22)
 };
 const STATUS_MARK = {
 	passed: c.green("✓"),
@@ -281,7 +286,7 @@ function renderSummary(results, durationMs) {
 		c.dim(`${(durationMs / 1e3).toFixed(2)}s`)
 	].join("\n");
 }
-function write(text) {
+function write$1(text) {
 	process.stdout.write(text);
 }
 /** Feature-grouped tree of every scenario (used by `--verbose`). */
@@ -315,10 +320,10 @@ function prettyReporter(opts = {}) {
 	const verbose = opts.verbose ?? false;
 	return {
 		onScenarioEnd(result) {
-			if (!verbose) write(scenarioDot(result));
+			if (!verbose) write$1(scenarioDot(result));
 		},
 		onComplete(results, durationMs) {
-			write(`${verbose ? `\n${renderFullTree(results, cwd)}\n` : `\n\n${renderFailures(results, cwd)}`}${renderSummary(results, durationMs)}\n`);
+			write$1(`${verbose ? `\n${renderFullTree(results, cwd)}\n` : `\n\n${renderFailures(results, cwd)}`}${renderSummary(results, durationMs)}\n`);
 		}
 	};
 }
@@ -331,10 +336,10 @@ function progressReporter(opts = {}) {
 	const cwd = opts.cwd ?? process.cwd();
 	return {
 		onScenarioEnd(result) {
-			write(scenarioDot(result));
+			write$1(scenarioDot(result));
 		},
 		onComplete(results, durationMs) {
-			write(`\n\n${renderFailures(results, cwd)}${renderSummary(results, durationMs)}\n`);
+			write$1(`\n\n${renderFailures(results, cwd)}${renderSummary(results, durationMs)}\n`);
 		}
 	};
 }
@@ -425,6 +430,606 @@ async function run(config, reporter = makeReporter(config.reporter, {
 	};
 }
 //#endregion
+//#region src/runtime/prompt.ts
+const useColor$1 = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
+const wrap = (open, close) => (s) => useColor$1 ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+const color = {
+	green: wrap(32, 39),
+	cyan: wrap(36, 39),
+	dim: wrap(2, 22),
+	bold: wrap(1, 22),
+	inverse: wrap(7, 27)
+};
+/** Ranked match: lower rank sorts first; `-1` means "no match" (excluded). */
+function rank(search, query) {
+	if (!query) return 0;
+	const idx = search.indexOf(query);
+	if (idx === -1) return -1;
+	if (idx === 0) return 0;
+	return /[\s:›@/]/.test(search[idx - 1]) ? 1 : 2;
+}
+var Prompt = class {
+	handlers;
+	prefix;
+	maxVisible;
+	all = [];
+	matches = [];
+	query;
+	cursor;
+	selected = 0;
+	window = 0;
+	/** Optional dim status line shown just above the input (set by the caller). */
+	status = "";
+	/** Lines the pinned block currently occupies, so a redraw can erase them. */
+	rendered = 0;
+	started = false;
+	/** While true the block is hidden so a run's output can own the screen. */
+	suspended = false;
+	keyListener;
+	constructor(options) {
+		this.handlers = options.handlers;
+		this.prefix = options.prefix ?? "› ";
+		this.maxVisible = options.maxVisible ?? 10;
+		this.query = options.initialQuery ?? "";
+		this.cursor = this.query.length;
+	}
+	/** Replace the suggestion pool (e.g. after the feature cache rebuilds). */
+	setSuggestions(suggestions) {
+		this.all = suggestions;
+		this.refilter();
+		if (this.started) this.render();
+	}
+	get value() {
+		return this.query;
+	}
+	/** Enter raw mode, attach the keypress listener, and draw the block. */
+	start() {
+		if (this.started) return;
+		this.started = true;
+		node_readline.emitKeypressEvents(process.stdin);
+		if (process.stdin.isTTY) process.stdin.setRawMode(true);
+		this.keyListener = (str, key) => this.onKey(str, key ?? {});
+		process.stdin.on("keypress", this.keyListener);
+		process.stdin.resume();
+		this.render();
+	}
+	/** Erase the block, restore cooked mode, and detach the listener. */
+	stop() {
+		if (!this.started) return;
+		this.started = false;
+		this.erase();
+		write("\x1B[?25h");
+		if (this.keyListener) process.stdin.off("keypress", this.keyListener);
+		if (process.stdin.isTTY) process.stdin.setRawMode(false);
+		process.stdin.pause();
+	}
+	/**
+	* Erase the pinned block and hide it for the duration of an (async) run, so
+	* everything written to stdout in the meantime scrolls where the prompt was.
+	* Keypresses still update state but don't repaint until {@link endOutput}.
+	*/
+	beginOutput() {
+		if (!this.started) return;
+		this.erase();
+		this.suspended = true;
+	}
+	/** Redraw the pinned block below whatever output {@link beginOutput} let through. */
+	endOutput() {
+		if (!this.started) return;
+		this.suspended = false;
+		this.render();
+	}
+	/** Force a redraw (after mutating `status`, say). No-op while suspended. */
+	redraw() {
+		if (this.started && !this.suspended) this.render();
+	}
+	onKey(str, key) {
+		if (key.ctrl && (key.name === "c" || key.name === "d")) {
+			this.handlers.onQuit();
+			return;
+		}
+		switch (key.name) {
+			case "return":
+			case "enter": {
+				const value = this.matches[this.selected]?.value ?? null;
+				this.handlers.onSubmit(value, this.query);
+				return;
+			}
+			case "escape":
+				this.handlers.onEscape();
+				return;
+			case "up":
+				this.move(-1);
+				return;
+			case "down":
+				this.move(1);
+				return;
+			case "left":
+				this.cursor = Math.max(0, this.cursor - 1);
+				this.render();
+				return;
+			case "right":
+				this.cursor = Math.min(this.query.length, this.cursor + 1);
+				this.render();
+				return;
+			case "home":
+				this.cursor = 0;
+				this.render();
+				return;
+			case "end":
+				this.cursor = this.query.length;
+				this.render();
+				return;
+			case "backspace":
+				this.deleteBefore();
+				return;
+			case "delete":
+				this.deleteAfter();
+				return;
+		}
+		if (str && str.length === 1 && str >= " " && !key.ctrl && !key.meta) this.insert(str);
+	}
+	insert(ch) {
+		this.query = this.query.slice(0, this.cursor) + ch + this.query.slice(this.cursor);
+		this.cursor += ch.length;
+		this.afterEdit();
+	}
+	deleteBefore() {
+		if (this.cursor === 0) return;
+		this.query = this.query.slice(0, this.cursor - 1) + this.query.slice(this.cursor);
+		this.cursor--;
+		this.afterEdit();
+	}
+	deleteAfter() {
+		if (this.cursor >= this.query.length) return;
+		this.query = this.query.slice(0, this.cursor) + this.query.slice(this.cursor + 1);
+		this.afterEdit();
+	}
+	afterEdit() {
+		this.refilter();
+		this.render();
+		this.handlers.onEdit(this.query);
+	}
+	move(delta) {
+		if (this.matches.length === 0) return;
+		this.selected = Math.min(this.matches.length - 1, Math.max(0, this.selected + delta));
+		this.reWindow();
+		this.render();
+	}
+	refilter() {
+		const q = this.query.trim().toLowerCase();
+		this.matches = this.all.map((s, index) => ({
+			s,
+			index,
+			r: rank(s.search, q)
+		})).filter((m) => m.r !== -1).sort((a, b) => a.r - b.r || a.index - b.index).map((m) => m.s);
+		this.selected = 0;
+		this.window = 0;
+	}
+	reWindow() {
+		if (this.selected < this.window) this.window = this.selected;
+		else if (this.selected >= this.window + this.maxVisible) this.window = this.selected - this.maxVisible + 1;
+	}
+	/** Build the block's lines, top (suggestions) to bottom (input). */
+	buildLines() {
+		const lines = [];
+		const total = this.matches.length;
+		if (this.query.trim() && total === 0) lines.push(color.dim("  no matching tag, feature, or scenario"));
+		const end = Math.min(this.window + this.maxVisible, total);
+		for (let i = this.window; i < end; i++) {
+			const s = this.matches[i];
+			const active = i === this.selected;
+			const row = `${color.cyan(s.badge.padEnd(9))} ${s.label}`;
+			lines.push(active ? color.inverse(`❯ ${row}`) : `  ${row}`);
+		}
+		if (total > end) lines.push(color.dim(`  …and ${total - end} more`));
+		if (this.status) lines.push(color.dim(this.status));
+		lines.push(`${color.bold(this.prefix)}${this.query}`);
+		return lines;
+	}
+	render() {
+		if (this.suspended) return;
+		write("\x1B[?25l");
+		this.moveToBlockStart();
+		write("\x1B[0J");
+		const lines = this.buildLines();
+		write(lines.join("\r\n"));
+		this.rendered = lines.length;
+		write(`\r\x1b[${stringWidth(this.prefix) + this.cursor}C`);
+		write("\x1B[?25h");
+	}
+	/** Erase the block and leave the caret at the block's top-left. */
+	erase() {
+		this.moveToBlockStart();
+		write("\x1B[0J");
+		this.rendered = 0;
+	}
+	/** Move the caret to column 0 of the block's first line. */
+	moveToBlockStart() {
+		if (this.rendered > 1) write(`\x1b[${this.rendered - 1}A`);
+		write("\r");
+	}
+};
+/** Visible width, ignoring the ANSI escapes our color helpers may inject. */
+function stringWidth(s) {
+	return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function write(s) {
+	process.stdout.write(s);
+}
+//#endregion
+//#region src/runtime/watcher.ts
+/** Glob metacharacters — the same set {@link globFiles} treats as "magic". */
+const MAGIC = /[*?[\]{}!()]/;
+/** File extensions worth reacting to: features and step/world modules. */
+const WATCHED_EXT = /\.(feature|ts|mts|js|mjs|cts|cjs)$/;
+/**
+* Watch the directories implied by feature/step globs and invoke `onChange`
+* (debounced, coalesced) whenever a relevant file changes. Roots are the literal
+* directory prefixes of each glob — e.g. `features/**\/*.feature` watches
+* `features/` recursively — deduped so nested roots aren't watched twice.
+*
+* Recursive watching is supported on macOS and Windows and on modern Linux
+* (Node ≥ 20 / Bun); on older Linux only the top level of each root is seen.
+*/
+function watchFeatures(globs, cwd, onChange, debounceMs = 120) {
+	const roots = watchRoots(globs, cwd);
+	const watchers = [];
+	let timer;
+	const schedule = (filename) => {
+		if (filename && !WATCHED_EXT.test(filename)) return;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(onChange, debounceMs);
+	};
+	for (const root of roots) try {
+		const w = node_fs.watch(root, { recursive: true }, (_event, filename) => schedule(filename));
+		w.on("error", () => {});
+		watchers.push(w);
+	} catch {}
+	return { close() {
+		if (timer) clearTimeout(timer);
+		for (const w of watchers) w.close();
+	} };
+}
+/**
+* The set of directories to watch: each glob's literal prefix (the path up to
+* its first magic character), resolved against `cwd`, deduped, with any root
+* that nests inside another dropped. Falls back to `cwd` when nothing resolves.
+*/
+function watchRoots(globs, cwd) {
+	const dirs = /* @__PURE__ */ new Set();
+	for (const glob of globs) dirs.add(node_path.resolve(cwd, literalPrefix(glob)));
+	const roots = [...dirs].sort();
+	const pruned = roots.filter((r, i) => !roots.some((other, j) => j < i && isInside(r, other)));
+	return pruned.length ? pruned : [cwd];
+}
+/** The directory portion of a glob before its first magic segment. */
+function literalPrefix(glob) {
+	const segments = glob.split("/");
+	const literal = [];
+	for (const seg of segments) {
+		if (MAGIC.test(seg)) break;
+		literal.push(seg);
+	}
+	const joined = literal.join("/");
+	if (!joined) return ".";
+	return MAGIC.test(glob) ? joined : node_path.dirname(joined);
+}
+/** True when `child` is `parent` itself or nested beneath it. */
+function isInside(child, parent) {
+	if (child === parent) return true;
+	const rel = node_path.relative(parent, child);
+	return !!rel && !rel.startsWith("..") && !node_path.isAbsolute(rel);
+}
+//#endregion
+//#region src/runtime/interactive.ts
+const useColor = !process.env.NO_COLOR && (process.stdout.isTTY ?? false) === true;
+const bold = (s) => useColor ? `\x1b[1m${s}\x1b[22m` : s;
+const dim = (s) => useColor ? `\x1b[2m${s}\x1b[22m` : s;
+const red = (s) => useColor ? `\x1b[31m${s}\x1b[39m` : s;
+const yellow = (s) => useColor ? `\x1b[33m${s}\x1b[39m` : s;
+/**
+* Entry point for `step-forge -i`. Brings up the always-live typeahead prompt,
+* watches the configured feature/step directories, and re-runs the armed
+* population on every relevant file change. Requires a TTY.
+*/
+async function runInteractive(config) {
+	if (!process.stdin.isTTY) {
+		process.stderr.write("Interactive mode (-i) requires a TTY; stdin is not a terminal.\n");
+		process.exitCode = 1;
+		return;
+	}
+	await new InteractiveSession(config).start();
+}
+var InteractiveSession = class {
+	config;
+	prompt;
+	watcher;
+	catalog = [];
+	armed = null;
+	dirty = false;
+	running = false;
+	rerunQueued = false;
+	/** Increments per run so back-to-back identical output is still distinguishable. */
+	runCount = 0;
+	done;
+	constructor(config) {
+		this.config = config;
+		this.prompt = new Prompt({
+			initialQuery: config.tags ?? config.name ?? "",
+			handlers: {
+				onSubmit: (value) => this.onSubmit(value),
+				onEdit: () => this.onEdit(),
+				onEscape: () => this.onEscape(),
+				onQuit: () => this.onQuit()
+			}
+		});
+	}
+	async start() {
+		await this.rebuildCatalog();
+		this.prompt.status = this.status();
+		this.prompt.start();
+		this.watcher = watchFeatures([...this.config.features, ...this.config.steps], this.config.cwd, () => void this.onFsChange());
+		await new Promise((resolve) => {
+			this.done = resolve;
+		});
+	}
+	onSubmit(value) {
+		if (!value) return;
+		this.armed = value;
+		this.dirty = false;
+		this.prompt.status = this.status();
+		this.triggerRun();
+	}
+	onEdit() {
+		if (this.armed) this.dirty = true;
+		this.prompt.status = this.status();
+		this.prompt.redraw();
+	}
+	onEscape() {
+		if (!this.armed) return;
+		this.armed = null;
+		this.dirty = false;
+		this.prompt.status = this.status();
+		this.prompt.redraw();
+	}
+	onQuit() {
+		this.watcher?.close();
+		this.prompt.stop();
+		process.stdout.write("\n");
+		process.exitCode = 0;
+		this.done?.();
+	}
+	async onFsChange() {
+		await this.rebuildCatalog();
+		if (this.armed && !this.dirty) this.triggerRun();
+	}
+	async rebuildCatalog() {
+		try {
+			const featureFiles = await require_gherkinParser.globFiles(this.config.features, this.config.cwd);
+			this.catalog = require_gherkinParser.parseFeatureCatalog(featureFiles);
+		} catch {}
+		this.prompt.setSuggestions(buildSuggestions(this.catalog));
+	}
+	triggerRun() {
+		if (!this.armed) return;
+		if (this.running) {
+			this.rerunQueued = true;
+			return;
+		}
+		this.running = true;
+		this.prompt.beginOutput();
+		this.runLoop();
+	}
+	async runLoop() {
+		try {
+			do {
+				this.rerunQueued = false;
+				if (this.armed) await this.executeOnce(this.armed);
+			} while (this.rerunQueued && this.armed && !this.dirty);
+		} catch (err) {
+			process.stdout.write(red(`\n  run failed: ${err instanceof Error ? err.message : err}\n`));
+		} finally {
+			this.running = false;
+			this.prompt.status = this.status();
+			this.prompt.endOutput();
+		}
+	}
+	/**
+	* One run of `choice`: resolve its scenarios against the current parse, then
+	* shell out to a **fresh** `step-forge` process scoped to just that
+	* population. A child process is used deliberately — Bun caches ES modules for
+	* the life of a process and ignores query-string cache-busting, so re-running
+	* in-process would never pick up edited step code. A new process re-reads
+	* every step/feature file, which is exactly what a watch loop needs.
+	*/
+	async executeOnce(choice) {
+		const selected = resolveScenarios(choice, this.scenarios());
+		const count = `${selected.length} scenario${selected.length === 1 ? "" : "s"}`;
+		process.stdout.write(`\n${bold(`▶ ${choiceLabel(choice)}`)} ${dim(`(${count} · run #${++this.runCount} · ${clock()})`)}\n\n`);
+		if (selected.length === 0) {
+			process.stdout.write(yellow("  no scenarios match this selection\n"));
+			return;
+		}
+		const single = selected.length === 1;
+		if (single) await this.analyzeScenario(selected[0]);
+		await this.spawnRun(runArgs(choice, single, this.config));
+	}
+	/** Every scenario across the current catalog, flattened. */
+	scenarios() {
+		return this.catalog.flatMap((f) => f.scenarios);
+	}
+	/**
+	* Run `step-forge` as a child process with `args`, streaming its output to the
+	* terminal (where the erased prompt was). Re-invokes the very CLI that's
+	* running us (`process.execPath` + `argv[1]`), so it works identically from
+	* the source tree and the built bin. Never rejects — a spawn error is reported
+	* and swallowed so the watch loop survives.
+	*/
+	spawnRun(args) {
+		return new Promise((resolve) => {
+			const child = (0, node_child_process.spawn)(process.execPath, [process.argv[1], ...args], {
+				cwd: this.config.cwd,
+				stdio: [
+					"ignore",
+					"inherit",
+					"inherit"
+				]
+			});
+			child.on("error", (err) => {
+				process.stdout.write(red(`  could not start runner: ${err.message}\n`));
+				resolve();
+			});
+			child.on("close", () => resolve());
+		});
+	}
+	/**
+	* Run the static analyzer over a single scenario and print any dependency /
+	* undefined / ambiguous diagnostics. The analyzer needs the optional
+	* `typescript` peer for AST extraction; if it's absent we note that and skip,
+	* never failing the run.
+	*/
+	async analyzeScenario(scenario) {
+		let analyzer;
+		try {
+			analyzer = await Promise.resolve().then(() => require("./analyzer-DIZPMxzN.cjs")).then((n) => n.analyzer_exports);
+		} catch {
+			process.stdout.write(dim("  analysis skipped: install `typescript` to enable it\n\n"));
+			return;
+		}
+		try {
+			const stepFiles = await require_gherkinParser.globFiles(this.config.steps, this.config.cwd);
+			const defs = analyzer.extractStepDefinitions(stepFiles);
+			const matched = analyzer.matchScenarioSteps(scenario, defs);
+			printDiagnostics(analyzer.defaultRules.flatMap((rule) => rule.check(scenario, matched)), this.config.cwd);
+		} catch (err) {
+			process.stdout.write(dim(`  analysis unavailable: ${err instanceof Error ? err.message : err}\n\n`));
+		}
+	}
+	status() {
+		if (!this.armed) return "  type to filter · ↑↓ move · enter run · ctrl-c quit";
+		if (this.dirty) return "  ⏸ suspended (query edited) · enter runs the selection · esc cancel";
+		return `  ▶ watching ${choiceLabel(this.armed)} · save a file to re-run · enter forces · esc change · ctrl-c quit`;
+	}
+};
+/** Build the typeahead pool: every tag, feature, and scenario in the catalog. */
+function buildSuggestions(catalog) {
+	const suggestions = [];
+	const tags = /* @__PURE__ */ new Set();
+	for (const feature of catalog) for (const scenario of feature.scenarios) for (const tag of scenario.tags) tags.add(tag);
+	for (const tag of [...tags].sort()) suggestions.push({
+		badge: "#tag",
+		label: tag,
+		search: tag.toLowerCase(),
+		value: {
+			kind: "tag",
+			tag
+		}
+	});
+	for (const feature of catalog) {
+		const featureLabel = feature.name || node_path.basename(feature.file);
+		suggestions.push({
+			badge: "feature",
+			label: featureLabel,
+			search: `${feature.name} ${feature.file}`.toLowerCase(),
+			value: {
+				kind: "feature",
+				file: feature.file,
+				name: feature.name
+			}
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const scenario of feature.scenarios) {
+			const name = scenario.outline ? scenario.outline.name : scenario.name;
+			if (seen.has(name)) continue;
+			seen.add(name);
+			suggestions.push({
+				badge: scenario.outline ? "outline" : "scenario",
+				label: name,
+				search: `${featureLabel} ${name}`.toLowerCase(),
+				value: {
+					kind: "scenario",
+					file: scenario.file,
+					name
+				}
+			});
+		}
+	}
+	return suggestions;
+}
+/** Resolve a choice to its scenarios against the current parse. */
+function resolveScenarios(choice, scenarios) {
+	switch (choice.kind) {
+		case "tag": return scenarios.filter((s) => s.tags.includes(choice.tag));
+		case "feature": return scenarios.filter((s) => s.file === choice.file);
+		case "scenario": return scenarios.filter((s) => s.file === choice.file && (s.name === choice.name || s.outline?.name === choice.name));
+	}
+}
+function choiceLabel(choice) {
+	switch (choice.kind) {
+		case "tag": return choice.tag;
+		case "feature": return choice.name || node_path.basename(choice.file);
+		case "scenario": return choice.name;
+	}
+}
+/**
+* The `step-forge` argv that reproduces this selection in a child process. The
+* base flags forward the resolved config (steps/world/concurrency) so the child
+* matches the parent's setup regardless of its own config file; the scope flags
+* narrow to the chosen population:
+*   - tag → all configured features, filtered by `-t <tag>`
+*   - feature → that single feature file
+*   - scenario → that feature file, name-anchored with `-n "/^…$/"` (the name is
+*     the outline name for an outline, so all its rows run)
+* A single scenario runs verbose; a population uses the configured reporter.
+*/
+function runArgs(choice, single, config) {
+	const args = [];
+	for (const glob of config.steps) args.push("-s", glob);
+	if (config.world) args.push("-w", config.world);
+	args.push("-c", String(config.concurrency));
+	switch (choice.kind) {
+		case "tag":
+			args.push(...config.features, "-t", choice.tag);
+			break;
+		case "feature":
+			args.push(choice.file);
+			break;
+		case "scenario":
+			args.push(choice.file, "-n", `/^${escapeRegExp(choice.name)}$/`);
+			break;
+	}
+	if (single) args.push("-v");
+	else {
+		args.push("-r", config.reporter);
+		if (config.verbose) args.push("-v");
+	}
+	return args;
+}
+/** Escape a scenario name for use inside an anchored `-n` regex. */
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Local wall-clock time as `HH:MM:SS`, so each run's header is dated. */
+function clock() {
+	const d = /* @__PURE__ */ new Date();
+	return [
+		d.getHours(),
+		d.getMinutes(),
+		d.getSeconds()
+	].map((n) => String(n).padStart(2, "0")).join(":");
+}
+function printDiagnostics(diagnostics, cwd) {
+	if (diagnostics.length === 0) return;
+	process.stdout.write(bold("  analyzer:\n"));
+	for (const d of diagnostics) {
+		const mark = d.severity === "error" ? red("✗") : d.severity === "warning" ? yellow("!") : dim("i");
+		const loc = `${node_path.relative(cwd, d.file)}:${d.range.startLine}`;
+		process.stdout.write(`  ${mark} ${d.message} ${dim(`(${loc})`)}\n`);
+	}
+	process.stdout.write("\n");
+}
+//#endregion
 //#region src/runtime/cli.ts
 const HELP = `step-forge — native TypeScript runner for Gherkin step definitions
 
@@ -439,6 +1044,8 @@ Options:
   -c, --concurrency <n>    Max scenarios in flight (default: 1, i.e. serial)
   -r, --reporter <name>    "pretty" (default) or "progress"
   -v, --verbose            Report every scenario, not just failures
+  -i, --interactive        Interactive watch mode: pick a tag/feature/scenario
+                           and re-run it on every file change
       --config <path>      Config file directory (default: cwd)
   -h, --help               Show this help
 
@@ -479,6 +1086,10 @@ function parseCli(argv) {
 				type: "boolean",
 				short: "v"
 			},
+			interactive: {
+				type: "boolean",
+				short: "i"
+			},
 			config: { type: "string" },
 			help: {
 				type: "boolean",
@@ -508,12 +1119,18 @@ function parseCli(argv) {
 	}
 	return {
 		cwd: values.config ? node_path.resolve(process.cwd(), values.config) : process.cwd(),
-		overrides
+		overrides,
+		interactive: values.interactive ?? false
 	};
 }
 async function main() {
-	const { cwd, overrides } = parseCli(process.argv.slice(2));
-	const { passed } = await run(resolveConfig(cwd, await loadConfigFile(cwd), overrides));
+	const { cwd, overrides, interactive } = parseCli(process.argv.slice(2));
+	const config = resolveConfig(cwd, await loadConfigFile(cwd), overrides);
+	if (interactive) {
+		await runInteractive(config);
+		return;
+	}
+	const { passed } = await run(config);
 	process.exitCode = passed ? 0 : 1;
 }
 main().catch((err) => {