@venn-lang/cli 0.1.0

package/dist/index.mjs

@@ -0,0 +1,916 @@
+import { createRequire } from "node:module";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createNodeFs, createNodeHost, createNodeSignals } from "@venn-lang/contracts/node";
+import { HttpClientPort, HttpServerPort, createFetchClient } from "@venn-lang/http";
+import { createNodeServer } from "@venn-lang/http/node";
+import { ALL_SIGNALS, ConsolePort, VennError, dotenvFiles, parseDotenv, resolveAlias } from "@venn-lang/contracts";
+import { findProject, isInside, normalise } from "@venn-lang/project";
+import { checkImports, createNdjsonSink, createRunner, resolveImports } from "@venn-lang/runtime";
+import { formatValue, parse } from "@venn-lang/core";
+import { pathToFileURL } from "node:url";
+import { allPlugins, stdlibPortBindings } from "@venn-lang/stdlib";
+import process$1 from "node:process";
+//#region src/manifest/load-env.ts
+/**
+* Every variable a run can see, lowest precedence first:
+*
+*   1. `[env.<name>]` in `venn.toml`, the documented default, committed.
+*   2. the dotenv files, in the order they are listed.
+*   3. the real environment the process was started with.
+*
+* The real environment wins because that is how CI passes a token in, and a
+* value set on the command line should never lose to a file in the repository.
+*/
+async function loadEnv(args) {
+	const declared = {
+		...args.manifest?.env[args.name] ?? {},
+		...await readFiles(args)
+	};
+	const real = overrides(declared, args.processEnv ?? process.env);
+	return {
+		...declared,
+		...real,
+		name: args.name
+	};
+}
+/**
+* The real environment overrides what was declared. It does not add to it.
+*
+* A shell holds hundreds of entries; letting them all become `env.*` would put
+* `PATH` and `TEMP` in the editor's completion and let a typo silently read
+* something from the machine. Declaring a name, in `venn.toml` or a dotenv file
+* and with any value, is what says "this program reads this". A value that
+* exists only in CI and is never declared belongs to `secrets.*`, which reads
+* the environment directly and redacts what it returns.
+*/
+function overrides(declared, source) {
+	const out = {};
+	for (const name of Object.keys(declared)) {
+		const value = source[name];
+		if (value !== void 0) out[name] = value;
+	}
+	return out;
+}
+async function readFiles(args) {
+	const names = dotenvFiles({
+		configured: args.manifest?.envFiles,
+		name: args.name
+	});
+	const out = {};
+	for (const each of names) Object.assign(out, await readOne(resolve(args.dir, each)));
+	return out;
+}
+/** A file that is not there is not a problem: most projects have none of them. */
+async function readOne(path) {
+	const content = await readFile(path, "utf8").catch(() => void 0);
+	return content === void 0 ? {} : parseDotenv(content);
+}
+//#endregion
+//#region src/manifest/load-manifest.ts
+/**
+* The manifest that governs a `.vn` file.
+*
+* Found by walking up to the project the file belongs to, rather than by
+* reading whatever happens to sit in the same folder. That is what makes a
+* command work from anywhere: `venn test packages/api/src/login.vn` sees the
+* same environments and aliases as running it from inside `packages/api`.
+*
+* Undefined when nothing governs the file: living outside a project is normal.
+*/
+async function loadManifest(sourceUri) {
+	const file = normalise(resolve(sourceUri));
+	const { project } = await findProject({
+		fs: createNodeFs(),
+		from: normalise(dirname(file))
+	});
+	if (!project) return void 0;
+	const owner = owningPackage(project, file);
+	if (owner) return {
+		manifest: owner.manifest,
+		dir: owner.dir
+	};
+	return {
+		manifest: project.rootManifest,
+		dir: project.root
+	};
+}
+/** The innermost member holding this file: the one whose settings are nearest. */
+function owningPackage(project, file) {
+	return [...project.packages].filter((one) => isInside(file, one.dir)).sort((a, b) => b.dir.length - a.dir.length)[0];
+}
+//#endregion
+//#region src/reporters/dot-sink.ts
+/** Terminal reporter: one char per assertion, a summary line at the end. */
+function createDotSink() {
+	return { emit: (envelope) => write$1(envelope) };
+}
+function write$1(envelope) {
+	if (envelope.kind === "expect.passed") process.stdout.write(".");
+	else if (envelope.kind === "expect.failed") process.stdout.write("F");
+	else if (envelope.kind === "run.finished") writeSummary(envelope);
+}
+function writeSummary(envelope) {
+	const data = envelope.data;
+	process.stdout.write(`\n${data.passed} passed, ${data.failed} failed (${data.durationMs}ms)\n`);
+}
+//#endregion
+//#region src/reporters/error-line.ts
+/**
+* One line for one failure, however it reached us.
+*
+* A `VennError` already knows how it wants to read, and leads with its code so
+* the failure is googlable; anything else is a stray from below the language and
+* gets its message, never `[object Object]`.
+*/
+function errorLine(error) {
+	if (error instanceof VennError) return `${error.code}  ${error.message}`;
+	const message = error?.message;
+	return typeof message === "string" && message !== "" ? message : String(error);
+}
+//#endregion
+//#region src/reporters/junit-sink.ts
+const XML_ESCAPES = {
+	"<": "&lt;",
+	">": "&gt;",
+	"&": "&amp;",
+	"\"": "&quot;"
+};
+/** Accumulate flow results and emit a JUnit XML document on run.finished. */
+function createJunitSink(args) {
+	const flows = [];
+	return { emit: (envelope) => {
+		if (envelope.kind === "flow.finished") flows.push(envelope.data);
+		else if (envelope.kind === "run.finished") args.write(toJunit(flows));
+	} };
+}
+function toJunit(flows) {
+	const failures = flows.filter((flow) => flow.status === "failed").length;
+	const cases = flows.map(toCase).join("\n");
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite tests="${flows.length}" failures="${failures}">\n${cases}\n</testsuite>\n`;
+}
+function toCase(flow) {
+	const body = flow.status === "failed" ? "<failure/>" : "";
+	return `  <testcase name="${escapeXml(flow.title)}">${body}</testcase>`;
+}
+function escapeXml(text) {
+	return text.replace(/[<>&"]/g, (char) => XML_ESCAPES[char] ?? char);
+}
+//#endregion
+//#region src/reporters/ndjson-stdout.ts
+/**
+* An event sink that writes each envelope to stdout as one line of NDJSON: the
+* stream a script or a CI job parses.
+*/
+function createStdoutSink() {
+	return createNdjsonSink({ write: (line) => {
+		process.stdout.write(line);
+	} });
+}
+//#endregion
+//#region src/reporters/colors.ts
+const ESC = String.fromCharCode(27);
+const ENABLED = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+function style(open, close) {
+	return (text) => ENABLED ? `${ESC}[${open}m${text}${ESC}[${close}m` : text;
+}
+const bold = style(1, 22);
+const dim = style(2, 22);
+const red = style(31, 39);
+const green = style(32, 39);
+const cyan = style(36, 39);
+const inverse = style(7, 27);
+//#endregion
+//#region src/reporters/pretty/diff-lines.ts
+const INDENT = "     ";
+const COLUMN = 8;
+/**
+* The body of a failure: the two sides as the kernel compared them, field by
+* field (§16). The title says what went wrong in one line; this says where.
+*/
+function diffLines(diff) {
+	if (diff.kind === "fields") return fieldLines(diff.label, diff.entries);
+	if (diff.kind === "json") return [head(diff.path), ...pairLines(formatValue(diff.expected), formatValue(diff.actual))];
+	return pairLines(diff.expected, diff.actual);
+}
+function fieldLines(label, entries) {
+	const width = Math.max(0, ...entries.map((entry) => entry.path.length));
+	const lines = [head(label)];
+	for (const [index, entry] of entries.entries()) lines.push(...entryLines({
+		entry,
+		width,
+		last: index === entries.length - 1
+	}));
+	return lines;
+}
+/** One field: a single line when both sides agree, two when they do not. */
+function entryLines(args) {
+	const { entry, last, width } = args;
+	const branch = `${INDENT}${dim(last ? "└" : "├")} ${entry.path.padEnd(width)}`;
+	if (entry.same) return [`${branch}  ${column("same")}  ${dim(entry.expected)}`];
+	const gutter = `${INDENT}${dim(last ? " " : "│")} ${" ".repeat(width)}`;
+	return [`${branch}  ${column("expected")}  ${green(entry.expected)}`, `${gutter}  ${column("actual")}  ${red(entry.actual)}`];
+}
+function pairLines(expected, actual) {
+	return [`${INDENT}${column("expected")}  ${green(expected)}`, `${INDENT}${column("actual")}  ${red(actual)}`];
+}
+function head(label) {
+	return `${INDENT}${bold(label)}`;
+}
+function column(label) {
+	return dim(label.padEnd(COLUMN));
+}
+//#endregion
+//#region src/reporters/pretty/render.ts
+const PASS = "✓";
+const FAIL = "✗";
+/** The banner naming the file under test. Flows add their own leading blank line. */
+function header(file) {
+	return `\n${inverse(cyan(" RUN "))} ${dim(shorten(file))}`;
+}
+/** A flow opens a branch of the tree. */
+function flowLine(title) {
+	return `\n ${dim("❯")} ${bold(title)}`;
+}
+/** A step closes with its verdict and how long it took. */
+function stepLine(args) {
+	return `   ${args.passed ? green(PASS) : red(FAIL)} ${args.title} ${dim(`${args.ms}ms`)}`;
+}
+/** Why a step failed, shown inline right under it. */
+function reasonLine(failure) {
+	return `     ${red("→")} ${failure.title}`;
+}
+/** A `log` line the flow emitted, shown under its step like console output. */
+function logLine(message) {
+	const [first = "", ...rest] = message.split("\n");
+	return [`     ${dim("›")} ${first}`, ...rest.map((line) => `       ${line}`)].join("\n");
+}
+function failuresBlock(failures) {
+	if (failures.length === 0) return "";
+	const blocks = failures.map((failure, index) => block(failure, index + 1));
+	return `\n${inverse(red(" FAILURES "))}\n\n${blocks.join("\n\n")}\n`;
+}
+function summary(args) {
+	const line = [args.failed > 0 ? red(`${args.failed} failed`) : void 0, green(`${args.passed} passed`)].filter(Boolean).join(dim(" | "));
+	const total = dim(`(${args.passed + args.failed})`);
+	return `${args.files && args.files > 1 ? `\n ${dim("Files")}  ${args.files}` : ""}\n ${dim("Tests")}  ${line} ${total}\n ${dim(" Time")}  ${dim(`${args.ms}ms`)}\n`;
+}
+/** `examples/testing/01-first-flow.vn:12:5`, relative to where the CLI was invoked. */
+function locationOf(problem) {
+	const span = problem.span;
+	if (!span?.uri) return void 0;
+	return `${shorten(span.uri)}:${span.line}:${span.column}`;
+}
+function block(failure, index) {
+	const lines = [`  ${red(`${index})`)} ${bold(where(failure))}`, `     ${red(failure.code)}  ${failure.title}`];
+	if (failure.location) lines.push(`     ${dim(`at ${failure.location}`)}`);
+	if (failure.diff) lines.push("", ...diffLines(failure.diff));
+	return lines.join("\n");
+}
+/**
+* Which flow and step it happened in. A hook that failed belongs to neither, so
+* it says so instead of borrowing the last step's name.
+*/
+function where(failure) {
+	return [failure.flow, failure.step].filter(Boolean).join(` ${dim("›")} `) || "lifecycle";
+}
+function shorten(file) {
+	const path = relative(process.cwd(), file);
+	return path && !path.startsWith("..") ? path.replace(/\\/g, "/") : file;
+}
+//#endregion
+//#region src/reporters/pretty/pretty-reporter.ts
+/**
+* A live tree: each file opens a banner, each flow a branch, and each step
+* prints its verdict as soon as it settles. Everything that failed across every
+* file is repeated at the end with its code and source location.
+*/
+function createPrettyReporter() {
+	const state = {
+		flow: "",
+		step: "",
+		inStep: false,
+		stepStartedAt: 0,
+		current: [],
+		logs: [],
+		failures: []
+	};
+	return {
+		sink: { emit: (envelope) => handle(envelope, state) },
+		beginFile: (file) => {
+			state.pendingFile = file;
+		},
+		finish: (totals) => finishRun(state, totals)
+	};
+}
+function handle(envelope, state) {
+	const data = envelope.data;
+	if (envelope.kind === "flow.started") beginFlow(state, data);
+	else if (envelope.kind === "step.started") beginStep(state, envelope, data);
+	else if (envelope.kind === "expect.failed") failed(state, data);
+	else if (envelope.kind === "step.finished") endStep(state, envelope, data);
+	else if (envelope.kind === "flow.finished") state.flow = "";
+	else if (envelope.kind === "log") logged(state, data);
+}
+/**
+* A failure inside a step waits for that step's verdict, to print under it. One
+* that arrives between steps (a `setup` or a `teardown` that blew up) has no
+* verdict coming, and holding it would let the next `step.started` wipe it, so
+* it goes straight to the summary.
+*/
+function failed(state, data) {
+	const failure = fromProblem(state, data);
+	if (state.inStep) state.current.push(failure);
+	else state.failures.push(failure);
+}
+function beginFlow(state, data) {
+	if (state.pendingFile) {
+		write(header(state.pendingFile));
+		state.pendingFile = void 0;
+	}
+	state.flow = String(data.title ?? "");
+	write(flowLine(state.flow));
+}
+function beginStep(state, envelope, data) {
+	state.step = String(data.title ?? "");
+	state.inStep = true;
+	state.stepStartedAt = Date.parse(envelope.ts);
+	state.current = [];
+	state.logs = [];
+}
+function endStep(state, envelope, data) {
+	const ms = Math.max(0, Date.parse(envelope.ts) - state.stepStartedAt);
+	write(stepLine({
+		title: String(data.title ?? ""),
+		passed: data.status === "passed",
+		ms
+	}));
+	for (const line of state.logs) write(logLine(line));
+	for (const failure of state.current) write(reasonLine(failure));
+	state.failures.push(...state.current);
+	state.current = [];
+	state.logs = [];
+	state.inStep = false;
+}
+/**
+* `log "…"` prints under its step, like console output in vitest. An error
+* thrown mid-flow also arrives as a log, and that one is kept for the summary.
+*/
+function logged(state, data) {
+	const message = String(data.message ?? "");
+	if (data.level === "error") state.failures.push({
+		flow: state.flow,
+		step: state.step,
+		code: "VN7001",
+		title: message
+	});
+	else state.logs.push(message);
+}
+function finishRun(state, totals) {
+	write(failuresBlock(state.failures));
+	write(summary(totals));
+}
+function fromProblem(state, data) {
+	const problem = data.problem;
+	return {
+		flow: state.flow,
+		step: state.inStep ? state.step : "",
+		code: problem.code,
+		title: problem.title,
+		location: locationOf(problem),
+		diff: problem.diff
+	};
+}
+function write(text) {
+	if (text) process.stdout.write(`${text}\n`);
+}
+//#endregion
+//#region src/reporters/pick-reporter.ts
+/**
+* Choose a reporter by name. With no `--reporter`, a terminal gets the readable
+* tree and anything piped gets NDJSON, so scripts and CI keep the
+* machine-readable stream they can parse.
+*/
+function pickReporter(name) {
+	if (name === "pretty") return createPrettyReporter();
+	if (name === "ndjson") return passive(createStdoutSink());
+	if (name === "dot") return passive(createDotSink());
+	if (name === "junit") return passive(junit());
+	return process.stdout.isTTY ? createPrettyReporter() : passive(createStdoutSink());
+}
+function passive(sink) {
+	return {
+		sink,
+		beginFile: () => {},
+		finish: () => {}
+	};
+}
+function junit() {
+	return createJunitSink({ write: (xml) => process.stdout.write(xml) });
+}
+//#endregion
+//#region src/reporters/problem-reporter.ts
+/**
+* Print compile-time problems to stderr, one code and title per problem with
+* its source location beneath. The terminal surface of the §16 model.
+*/
+function reportProblems(problems) {
+	for (const problem of problems) {
+		process.stderr.write(`${problem.code} · ${problem.title}\n`);
+		const { uri, line, column } = problem.span;
+		process.stderr.write(`  at ${uri}:${line}:${column}\n`);
+	}
+}
+//#endregion
+//#region src/run/collect-files.ts
+const EXTENSION = ".vn";
+const SKIP = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	".git"
+]);
+/**
+* The `.vn` files a path names: the file itself, or every one under a
+* directory, walked recursively and sorted so runs are reproducible.
+*/
+async function collectSourceFiles(path) {
+	const info = await stat(path).catch(() => void 0);
+	if (!info) return [];
+	if (info.isFile()) return path.endsWith(EXTENSION) ? [path] : [];
+	return (await walk(path)).sort();
+}
+async function walk(directory) {
+	const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+	const found = [];
+	for (const entry of entries) if (entry.isDirectory() && !SKIP.has(entry.name)) found.push(...await walk(join(directory, entry.name)));
+	else if (entry.isFile() && entry.name.endsWith(EXTENSION)) found.push(join(directory, entry.name));
+	return found;
+}
+//#endregion
+//#region src/run/node-io.ts
+/**
+* Node-backed module IO: read files, resolve relative specifiers against the
+* importer, and `#alias/…` specifiers through `[paths]` in `venn.toml`.
+*/
+function createNodeModuleIo(roots) {
+	return {
+		read: (uri) => readFile(uri, "utf8"),
+		resolve: (base, spec) => resolveSpec(spec, base, roots)
+	};
+}
+function resolveSpec(spec, base, roots) {
+	if (spec.startsWith(".")) return resolve(dirname(base), spec);
+	const alias = resolveAlias({
+		spec,
+		paths: roots.paths
+	});
+	return alias ? resolve(roots.rootDir, alias.dir, alias.rest) : spec;
+}
+//#endregion
+//#region src/run/npm-loader.ts
+/**
+* Loading an installed package, the way Node loads one.
+*
+* Resolution is Node's own, rooted at `target/`, the directory holding the
+* generated `package.json` and the `node_modules` beside it. `exports` maps,
+* conditions, scoped names and the rest are what a package means, and a second
+* implementation of them would agree with Node right up until it did not.
+*/
+function createNpmLoader(args) {
+	const from = createRequire(pathToFileURL(join(join(args.root, "target"), "package.json")));
+	return { async load(spec) {
+		const found = resolvePath(from, spec);
+		if (!found) return void 0;
+		return await import(pathToFileURL(found).href);
+	} };
+}
+/**
+* Where the package lives, or nothing when it is not installed.
+*
+* Not installed is an ordinary state: the manifest asks for a package and
+* nobody has run `venn install` yet. The import that named it reports that
+* itself, which is a better place to say it than inside a resolver.
+*/
+function resolvePath(from, spec) {
+	try {
+		return from.resolve(spec);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/run/run-file.ts
+/**
+* Parse and run a `.vn` source with the full stdlib loaded.
+*
+* The HttpClient, HttpServer and Console ports take injected implementations
+* (real in the CLI, fakes in tests); every other port takes the binding
+* `@venn-lang/stdlib` supplies.
+*
+* @param args - The source and its uri, the host and the ports, and how to run
+* it: the filter, the mode, the environment, the module and package loaders.
+* @returns The problems and, when anything ran, the run's result. A failing
+* flow is a `Problem` here, not an exception.
+* @throws Whatever an action or a loaded module let escape the runner.
+*/
+async function runFile(args) {
+	const { ast, problems } = parse(args.source, { uri: args.uri });
+	if (problems.length > 0) return { problems };
+	const io = args.io;
+	const resolved = io ? await resolveImports({
+		document: ast,
+		uri: args.uri,
+		io,
+		npm: args.npm
+	}) : void 0;
+	const graph = resolved && io ? {
+		modules: resolved.modules,
+		resolve: io.resolve,
+		npm: resolved.npm
+	} : void 0;
+	const bad = graph ? checkImports({
+		document: ast,
+		uri: args.uri,
+		graph
+	}) : [];
+	if (bad.length > 0) return { problems: bad };
+	const runner = createRunner({
+		host: args.host,
+		plugins: allPlugins,
+		sink: args.sink,
+		ports: bindings(args),
+		uri: args.uri,
+		filter: args.filter,
+		bail: args.bail,
+		env: args.env,
+		moduleFragments: resolved?.fragments,
+		modules: graph,
+		moduleDecos: resolved?.decos,
+		cleanup: args.cleanup
+	});
+	const result = args.mode === "script" ? await runner.script(ast) : await runner.run(ast);
+	return {
+		problems: result.problems ?? [],
+		result
+	};
+}
+function bindings(args) {
+	const console = args.console ? [{
+		port: ConsolePort,
+		impl: args.console
+	}] : [];
+	return [
+		{
+			port: HttpClientPort,
+			impl: args.httpClient
+		},
+		...stdlibPortBindings,
+		{
+			port: HttpServerPort,
+			impl: args.httpServer ?? createNodeServer()
+		},
+		...console
+	];
+}
+//#endregion
+//#region src/shutdown/create-leave.ts
+/** How long a close may take before the program stops waiting for it. */
+const GRACE_MS = 5e3;
+/**
+* Leaving, done properly: close what is open, then go.
+*
+* Two things make this more than `await close(); exit()`. A second signal means
+* the user is done asking nicely, so it leaves at once. And a closer that never
+* settles must not hold the program hostage, so the wait has a deadline: an
+* unclean exit beats a process that cannot be stopped.
+*/
+function createLeave(args) {
+	let leaving = false;
+	return (code) => {
+		if (leaving) return args.exit(code);
+		leaving = true;
+		finish({
+			...args,
+			code
+		});
+	};
+}
+async function finish(args) {
+	await Promise.race([args.shutdown.close(), deadline(args.graceMs ?? GRACE_MS)]);
+	args.exit(args.code);
+}
+/** A timer that does not itself keep the program alive. */
+function deadline(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref();
+	});
+}
+//#endregion
+//#region src/shutdown/create-shutdown.ts
+/**
+* The registry: what to close, and the promise that it happened.
+*
+* Closing runs newest first, because a thing opened later may be standing on one
+* opened earlier. One closer that throws must not strand the rest: leaving is
+* the goal, and a half-closed program still has to go.
+*/
+function createShutdown() {
+	const closers = /* @__PURE__ */ new Set();
+	let closing;
+	return {
+		add: (closer) => {
+			closers.add(closer);
+			return () => {
+				closers.delete(closer);
+			};
+		},
+		close: () => {
+			closing ??= closeAll(closers);
+			return closing;
+		}
+	};
+}
+async function closeAll(closers) {
+	for (const closer of [...closers].reverse()) await Promise.resolve().then(() => closer()).catch(() => {});
+	closers.clear();
+}
+//#endregion
+//#region src/shutdown/install-exit-hook.ts
+/**
+* The quiet ending: a program that simply ran out of things to do.
+*
+* `beforeExit` is the only moment a script without a server gets, so its
+* `teardown` has to run here or it never runs at all. The timer is what buys
+* the closing its time: a promise alone does not hold the loop open, and
+* without it Node could leave mid-cleanup.
+*/
+function installExitHook(shutdown) {
+	const onBeforeExit = () => {
+		const hold = setInterval(() => {}, 1e3);
+		shutdown.close().finally(() => clearInterval(hold));
+	};
+	process$1.once("beforeExit", onBeforeExit);
+	return () => {
+		process$1.off("beforeExit", onBeforeExit);
+	};
+}
+//#endregion
+//#region src/shutdown/install-fault-hooks.ts
+/**
+* The two ways a program dies without being asked to.
+*
+* Node's default for both is to print a stack and vanish, losing the sockets,
+* the reason and the exit code at once. Catching them means the failure is
+* stated in the language's own voice and the machine gets its resources back on
+* the way out.
+*/
+function installFaultHooks(args) {
+	const onFault = (cause) => fault({
+		...args,
+		cause
+	});
+	process$1.on("uncaughtException", onFault);
+	process$1.on("unhandledRejection", onFault);
+	return () => {
+		process$1.off("uncaughtException", onFault);
+		process$1.off("unhandledRejection", onFault);
+	};
+}
+function fault(args) {
+	(args.report ?? ((message) => process$1.stderr.write(`${message}\n`)))(errorLine(args.cause));
+	args.leave(1);
+}
+//#endregion
+//#region src/shutdown/install-signal-hooks.ts
+/** What the shell means by each signal, in exit codes. */
+const CODES = {
+	SIGINT: 130,
+	SIGTERM: 143,
+	SIGBREAK: 130,
+	SIGHUP: 129
+};
+/**
+* Every way a system can ask this program to stop, wired to the same ending.
+*
+* `Ctrl+C` is the one everybody knows; `SIGTERM` is how a supervisor or a CI
+* runner asks; `SIGBREAK` is Windows' Ctrl+Break; `SIGHUP` is the terminal
+* closing with the program still inside it. All four deserve the same care.
+*/
+function installSignalHooks(args) {
+	const offs = ALL_SIGNALS.map((signal) => args.signals.on(signal, () => args.leave(CODES[signal])));
+	return () => {
+		for (const off of offs) off();
+	};
+}
+//#endregion
+//#region src/shutdown/install-hooks.ts
+/**
+* Hand the process its hooks. The three ways a program can end (asked to stop,
+* broken, or simply finished) all end the same way.
+*
+* Returns the `leave` these hooks share, so a command that decides to stop on
+* its own terms unwinds through exactly the same path.
+*/
+function installHooks(args) {
+	const leave = createLeave({
+		shutdown: args.shutdown,
+		exit: args.exit,
+		graceMs: args.graceMs
+	});
+	installSignalHooks({
+		signals: args.signals,
+		leave
+	});
+	installFaultHooks({
+		leave,
+		report: args.report
+	});
+	installExitHook(args.shutdown);
+	return leave;
+}
+//#endregion
+//#region src/title/program-title.ts
+/** How long a title may get before it stops being readable in a tab. */
+const MAX = 60;
+/**
+* What this process calls itself: `venn run server.vn`, not `node`.
+*
+* The terminal tab is the only place a long-running program announces itself,
+* and "node" says nothing about which program, which file, or whose.
+*/
+function programTitle(args) {
+	const name = args.target ? basename(args.target) : "";
+	return `venn ${args.command}${name ? ` ${name}` : ""}`.slice(0, MAX);
+}
+//#endregion
+//#region src/title/set-program-title.ts
+/**
+* Name the process after the program it is running.
+*
+* Until something says otherwise, Windows reports the executable path (the
+* `node` the terminal tab shows) and puts it back when the process exits. So
+* this is set once and never undone: restoring it by hand would write that path
+* over whatever title the terminal had before, which is worse than doing
+* nothing.
+*/
+function setProgramTitle(args) {
+	process$1.title = programTitle(args);
+}
+//#endregion
+//#region src/commands/run.ts
+/**
+* `venn test <file|directory>`: run every matching flow, then report.
+*
+* @param options - The file or directory, the reporter, and the filters.
+* @returns The exit code: whatever a flow's `exit` named, else 0 when nothing
+* failed, else 1. Also 1 when the path holds no `.vn` file.
+*/
+async function runCommand(options) {
+	const files = await collectSourceFiles(resolve(options.file));
+	if (files.length === 0) return noFiles(options.file);
+	const reporter = pickReporter(options.reporter);
+	const shutdown = createShutdown();
+	setProgramTitle({
+		command: "test",
+		target: options.file
+	});
+	installHooks({
+		signals: createNodeSignals(),
+		shutdown,
+		exit: (code) => process.exit(code)
+	});
+	const totals = await runAll({
+		files,
+		options,
+		reporter,
+		shutdown
+	});
+	reporter.finish(totals);
+	return totals.exitCode ?? (totals.failed === 0 ? 0 : 1);
+}
+async function runAll(pass) {
+	const totals = {
+		passed: 0,
+		failed: 0,
+		files: 0,
+		ms: 0
+	};
+	const started = Date.now();
+	for (const file of pass.files) {
+		pass.reporter.beginFile(file);
+		await runOne({
+			pass,
+			file,
+			totals
+		});
+		if (totals.exitCode !== void 0) break;
+		if (pass.options.bail && totals.failed > 0) break;
+	}
+	totals.ms = Date.now() - started;
+	return totals;
+}
+/**
+* One file, and the servers it started closed with it.
+*
+* A suite that leaves a port bound holds it for the whole run, so a hundred
+* files that serve would end up holding a hundred ports. They are also on the
+* shutdown list, for the run that ends by signal instead of by finishing.
+*/
+async function runOne(args) {
+	const servers = createNodeServer();
+	const forget = args.pass.shutdown.add(() => servers.closeAll());
+	try {
+		tally(args.totals, await runFile(await buildArgs(args.file, args.pass, servers)));
+	} finally {
+		await servers.closeAll();
+		forget();
+	}
+}
+function tally(totals, outcome) {
+	if (outcome.problems.length > 0) {
+		reportProblems(outcome.problems);
+		totals.files += 1;
+		totals.failed += 1;
+		return;
+	}
+	if (outcome.result?.exitCode !== void 0) totals.exitCode = outcome.result.exitCode;
+	const passed = outcome.result?.passed ?? 0;
+	const failed = outcome.result?.failed ?? 0;
+	if (passed + failed > 0) totals.files += 1;
+	totals.passed += passed;
+	totals.failed += failed;
+}
+async function buildArgs(file, pass, httpServer) {
+	const found = await loadManifest(file);
+	const manifest = found?.manifest;
+	return {
+		source: await readFile(file, "utf8"),
+		uri: file,
+		host: createNodeHost(),
+		sink: pass.reporter.sink,
+		httpClient: createFetchClient(),
+		httpServer,
+		filter: filterOf(pass.options),
+		bail: pass.options.bail,
+		env: await loadEnv({
+			manifest,
+			name: pass.options.env ?? "local",
+			dir: found?.dir ?? dirname(file)
+		}),
+		io: createNodeModuleIo({
+			paths: manifest?.paths ?? {},
+			rootDir: found?.dir ?? dirname(file)
+		}),
+		npm: createNpmLoader({ root: found?.dir ?? dirname(file) })
+	};
+}
+function filterOf(options) {
+	return {
+		tags: parseTags(options.tags),
+		flow: options.flow,
+		step: options.step
+	};
+}
+function parseTags(tags) {
+	if (!tags) return void 0;
+	return tags.split(",").map((tag) => tag.trim()).filter((tag) => tag !== "");
+}
+function noFiles(path) {
+	process.stderr.write(`No .vn files found at ${path}\n`);
+	return 1;
+}
+//#endregion
+//#region src/commands/verify-plugin.ts
+/**
+* `venn verify-plugin <path>`: import a plugin module, print what it declares,
+* and check its shape.
+*
+* @param args - `path` is the module to import, relative to the working
+* directory or absolute.
+* @returns 0 when the plugin names itself and a namespace, 1 when it does not.
+* @throws Error when the module exports nothing that looks like a plugin.
+*/
+async function verifyPluginCommand(args) {
+	const plugin = await loadPlugin(args.path);
+	const out = process.stdout;
+	out.write(`Plugin: ${plugin.name} (namespace "${plugin.namespace}")\n`);
+	out.write(`  actions:   ${plugin.actions?.length ?? 0}\n`);
+	out.write(`  matchers:  ${plugin.matchers?.length ?? 0}\n`);
+	out.write(`  resources: ${plugin.resources?.length ?? 0}\n`);
+	const ok = Boolean(plugin.name && plugin.namespace);
+	out.write(ok ? "\n✓ plugin shape is valid\n" : "\n✗ plugin shape is invalid\n");
+	return ok ? 0 : 1;
+}
+async function loadPlugin(path) {
+	const mod = await import(pathToFileURL(resolve(path)).href);
+	const plugin = mod.default ?? Object.values(mod).find(isPlugin);
+	if (!isPlugin(plugin)) throw new Error(`No plugin export found in ${path}`);
+	return plugin;
+}
+function isPlugin(value) {
+	return typeof value === "object" && value !== null && "namespace" in value && "name" in value;
+}
+//#endregion
+export { createStdoutSink, reportProblems, runCommand, runFile, verifyPluginCommand };
+
+//# sourceMappingURL=index.mjs.map