@venn-lang/contracts 0.1.0

package/dist/index.js

@@ -0,0 +1,1342 @@
+//#region src/capabilities/host-capability.ts
+/**
+* Every capability a Host may expose. A port or plugin declares which it
+* requires, a host advertises which it provides, and negotiation compares the
+* two before anything binds.
+*/
+const ALL_CAPABILITIES = [
+	"fs",
+	"process",
+	"net",
+	"clock",
+	"random",
+	"secrets",
+	"log",
+	"io"
+];
+//#endregion
+//#region src/dotenv/dotenv-files.ts
+/**
+* The dotenv files read when `venn.toml` does not name its own.
+*
+* The order is the precedence, lowest first: what everyone shares, then what
+* this environment adds, then what this machine keeps to itself. The `.local`
+* ones are what a `.gitignore` is for.
+*/
+const DOTENV_CONVENTION = [
+	".env",
+	".env.${name}",
+	".env.local",
+	".env.${name}.local"
+];
+/**
+* Which files to read, in order, for one environment.
+*
+* The runner and the editor both ask this, so they cannot disagree about where
+* a value lives.
+*
+* @param args.configured - `[env] files` from `venn.toml`. Empty or absent
+* falls back to {@link DOTENV_CONVENTION}.
+* @param args.name - the selected environment, substituted for `${name}`.
+*/
+function dotenvFiles(args) {
+	return (args.configured?.length ? args.configured : DOTENV_CONVENTION).map((each) => each.replaceAll("${name}", args.name));
+}
+//#endregion
+//#region src/dotenv/parse-dotenv.ts
+/**
+* Read a `.env` file: `NAME=value`, one per line.
+*
+* Deliberately small. It understands comments, blank lines, an `export `
+* prefix, and quotes around a value that needs them. No variable expansion:
+* `${OTHER}` is left alone, because Venn already interpolates in its own
+* strings and two syntaxes for one idea is how people get surprised.
+*
+* @returns every name found, later lines winning over earlier ones.
+*/
+function parseDotenv(content) {
+	const out = {};
+	for (const line of content.split(/\r?\n/)) {
+		const entry = readLine(line);
+		if (entry) out[entry.name] = entry.value;
+	}
+	return out;
+}
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+function readLine(line) {
+	if (/^\s*(#|$)/.test(line)) return void 0;
+	const match = LINE.exec(line);
+	if (!match?.[1]) return void 0;
+	return {
+		name: match[1],
+		value: unquote((match[2] ?? "").trim())
+	};
+}
+/** A quoted value keeps its spaces and its `#`; an unquoted one stops at a comment. */
+function unquote(raw) {
+	const quoted = /^(['"])([\s\S]*)\1$/.exec(raw);
+	if (quoted) return quoted[2];
+	return (raw.split(" #")[0] ?? "").trim();
+}
+//#endregion
+//#region src/errors/venn-error.ts
+/**
+* The single error type that crosses a contracts boundary.
+*
+* Every failure carries a stable `VNxxxx` code, so conformance suites assert on
+* `.code` and never on prose. Messages stay free to improve.
+*/
+var VennError = class extends Error {
+	code;
+	detail;
+	constructor(args) {
+		super(args.message);
+		this.name = "VennError";
+		this.code = args.code;
+		this.detail = args.detail;
+	}
+};
+//#endregion
+//#region src/errors/contract-codes.ts
+/** VN2010: a port requires capabilities the host does not provide. */
+function hostMissingCapability(args) {
+	return new VennError({
+		code: "VN2010",
+		message: `Port "${args.portId}" requires capability ${quote(args.missing)}, which this host does not provide. Present: ${list(args.present)}.`,
+		detail: { ...args }
+	});
+}
+/** VN2011: an implementation is missing one or more methods the port declares. */
+function portShapeMismatch(args) {
+	return new VennError({
+		code: "VN2011",
+		message: `Implementation of "${args.portId}" is missing method(s): ${args.missing.join(", ")}.`,
+		detail: { ...args }
+	});
+}
+/** VN2012: code reached a capability the host declared unavailable. */
+function capabilityUnavailable(args) {
+	return new VennError({
+		code: "VN2012",
+		message: `Capability "${args.capability}" is not available on this host (called "${args.method}").`,
+		detail: { ...args }
+	});
+}
+function quote(caps) {
+	return caps.map((c) => `"${c}"`).join(", ");
+}
+function list(caps) {
+	return caps.length === 0 ? "(none)" : caps.join(", ");
+}
+//#endregion
+//#region src/logger/console-logger.ts
+/** Logger backed by the global console, so it works in a Worker and in Node. */
+function createConsoleLogger() {
+	return { log(entry) {
+		const line = `[${entry.level}] ${entry.message}`;
+		if (entry.level === "error") console.error(line);
+		else console.log(line);
+	} };
+}
+//#endregion
+//#region src/logger/memory-logger.ts
+/** The double: keeps every entry in `entries` instead of printing it. */
+function createMemoryLogger() {
+	const entries = [];
+	return {
+		entries,
+		log(entry) {
+			entries.push(entry);
+		}
+	};
+}
+//#endregion
+//#region src/ports/clock/clock.port.ts
+/**
+* The {@link Clock} contract. Implementations: `system-clock`, `virtual-clock`.
+*
+* `advance` and `setTime` are absent on purpose: they are how a test drives a
+* virtual clock, not something a caller of the port may reach for.
+*/
+const ClockPort = {
+	id: "venn.port.clock",
+	version: 1,
+	requires: ["clock"],
+	methods: ["now", "sleep"]
+};
+//#endregion
+//#region src/ports/clock/system-clock.ts
+/** Wall-clock time, on the `Date` and `setTimeout` globals. */
+function createSystemClock() {
+	return {
+		now: () => Date.now(),
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+	};
+}
+//#endregion
+//#region src/ports/clock/virtual-clock.ts
+/**
+* The double. `sleep` advances internal time and resolves at once, so a test
+* about a timeout costs nothing to run.
+*
+* @param args.start - the epoch this clock begins at. Defaults to 0.
+*/
+function createVirtualClock(args = {}) {
+	let time = args.start ?? 0;
+	const advance = (ms) => {
+		time += Math.max(0, ms);
+	};
+	return {
+		now: () => time,
+		sleep: async (ms) => advance(ms),
+		advance,
+		setTime: (epochMs) => {
+			time = epochMs;
+		}
+	};
+}
+//#endregion
+//#region src/ports/file-system/file-system.errors.ts
+/** VN8010: a read or a remove targeted a path that does not exist. */
+function fsNotFound(args) {
+	return new VennError({
+		code: "VN8010",
+		message: `File not found: "${args.path}".`,
+		detail: { path: args.path }
+	});
+}
+//#endregion
+//#region src/ports/file-system/file-system.port.ts
+/**
+* The {@link FileSystem} contract. Implementations: `node-fs`, `memory-fs`.
+*/
+const FileSystemPort = {
+	id: "venn.port.filesystem",
+	version: 1,
+	requires: ["fs"],
+	methods: [
+		"read",
+		"write",
+		"exists",
+		"remove",
+		"list"
+	]
+};
+//#endregion
+//#region src/ports/file-system/memory-fs.ts
+/** The double: byte-exact, isolated per instance, no disk. */
+function createMemoryFs() {
+	const files = /* @__PURE__ */ new Map();
+	return {
+		async read(path) {
+			const bytes = files.get(path);
+			if (!bytes) throw fsNotFound({ path });
+			return bytes.slice();
+		},
+		async write(path, bytes) {
+			files.set(path, bytes.slice());
+		},
+		async exists(path) {
+			return files.has(path);
+		},
+		async remove(path) {
+			if (!files.delete(path)) throw fsNotFound({ path });
+		},
+		async list(path) {
+			return listUnder([...files.keys()], path);
+		}
+	};
+}
+/**
+* What a directory holds, worked out from the paths written.
+*
+* There are no directories here, only paths, so a directory is whatever a path
+* implies one to be. For everything the language does with a directory that is
+* the same answer the real file system gives, which is what lets the TCK ask
+* both the same questions.
+*/
+function listUnder(paths, directory) {
+	const prefix = directory === "" || directory === "." ? "" : `${directory.replace(/\/+$/, "")}/`;
+	const seen = /* @__PURE__ */ new Map();
+	for (const path of paths) {
+		if (!path.startsWith(prefix)) continue;
+		const rest = path.slice(prefix.length);
+		const slash = rest.indexOf("/");
+		if (rest !== "") seen.set(slash < 0 ? rest : rest.slice(0, slash), slash >= 0);
+	}
+	return [...seen].map(([name, isDirectory]) => ({
+		name,
+		directory: isDirectory
+	}));
+}
+//#endregion
+//#region src/ports/lock-provider/fake-lock.ts
+/** The double: grants immediately and serialises nothing. */
+function createFakeLock() {
+	return { acquire: async () => () => {} };
+}
+//#endregion
+//#region src/ports/lock-provider/in-process-lock.ts
+/**
+* The real one: a chained-promise mutex per name. Waiters are served in the
+* order they asked, and the chain lives only in this process.
+*/
+function createInProcessLock() {
+	const tails = /* @__PURE__ */ new Map();
+	return { acquire: (name) => acquire(tails, name) };
+}
+async function acquire(tails, name) {
+	const previous = tails.get(name) ?? Promise.resolve();
+	let release = () => {};
+	const held = new Promise((resolve) => {
+		release = resolve;
+	});
+	tails.set(name, previous.then(() => held));
+	await previous;
+	return release;
+}
+//#endregion
+//#region src/ports/lock-provider/lock-provider.port.ts
+/**
+* The {@link LockProvider} contract. Implementations: `in-process-lock`,
+* `fake-lock`.
+*
+* Requires nothing: a mutex is bookkeeping, so it binds even on a host with no
+* capabilities at all.
+*/
+const LockProviderPort = {
+	id: "venn.port.lock",
+	version: 1,
+	requires: [],
+	methods: ["acquire"]
+};
+//#endregion
+//#region src/ports/process-provider/fake-process.ts
+/**
+* The double: a scripted process that never touches the OS.
+*
+* Output is streamed before the wait resolves, exactly as the real one does it,
+* so a caller that shows progress is exercised here and not only against a real
+* machine.
+*
+* @param args.exitCode - what every run reports. Defaults to 0.
+* @param args.output - what every run writes. Defaults to nothing.
+*/
+function createFakeProcess(args = {}) {
+	const code = args.exitCode ?? 0;
+	const output = args.output ?? "";
+	return { spawn: (spawned) => {
+		if (output !== "") spawned.onOutput?.(output);
+		return handle(code, output);
+	} };
+}
+function handle(code, output) {
+	return {
+		pid: 0,
+		wait: async () => ({
+			code,
+			output
+		}),
+		kill: () => {}
+	};
+}
+//#endregion
+//#region src/ports/process-provider/process-provider.port.ts
+/**
+* The {@link ProcessProvider} contract. Implementations: `node-spawn`,
+* `fake-process`.
+*/
+const ProcessProviderPort = {
+	id: "venn.port.process",
+	version: 1,
+	requires: ["process"],
+	methods: ["spawn"]
+};
+//#endregion
+//#region src/ports/random/fixed-random.ts
+/** The double: always the same value, and always `min` from `int`. */
+function createFixedRandom(args = {}) {
+	const value = args.value ?? 0;
+	return {
+		next: () => value,
+		int: (min) => min
+	};
+}
+//#endregion
+//#region src/ports/random/random.port.ts
+/**
+* The {@link Random} contract. Implementations: `seeded-random`,
+* `fixed-random`.
+*/
+const RandomPort = {
+	id: "venn.port.random",
+	version: 1,
+	requires: ["random"],
+	methods: ["next", "int"]
+};
+//#endregion
+//#region src/ports/random/seeded-random.ts
+/**
+* The real one: a mulberry32 PRNG, seeded once per worker. Same seed, same
+* sequence, so a run reproduces.
+*/
+function createSeededRandom(args) {
+	let state = args.seed >>> 0;
+	const next = () => {
+		state = state + 1831565813 | 0;
+		let t = Math.imul(state ^ state >>> 15, 1 | state);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+	return {
+		next,
+		int: (min, max) => min + Math.floor(next() * (max - min + 1))
+	};
+}
+//#endregion
+//#region src/ports/secret-provider/secret.ts
+/** What every serialised secret collapses to. */
+const REDACTED = "‹redigido›";
+/**
+* Wrap a raw value so it cannot leak through `toString` or `toJSON`.
+*
+* @param args.reveal - the raw value, reachable only via `Secret.reveal()`.
+*/
+function makeSecret(args) {
+	return {
+		reveal: () => args.reveal,
+		toString: () => REDACTED,
+		toJSON: () => REDACTED
+	};
+}
+//#endregion
+//#region src/ports/secret-provider/env-secrets.ts
+/**
+* The real one: secrets from `process.env`.
+*
+* The `process` global is probed rather than imported, so this file stays
+* neutral and reports every name as absent in a Worker instead of throwing.
+*/
+function createEnvSecrets() {
+	const env = typeof process === "undefined" ? {} : process.env;
+	return {
+		get: (name) => {
+			const value = env[name];
+			return value === void 0 ? void 0 : makeSecret({ reveal: value });
+		},
+		has: (name) => env[name] !== void 0
+	};
+}
+//#endregion
+//#region src/ports/secret-provider/memory-secrets.ts
+/**
+* The double: secrets given by name, wrapped so they still redact.
+*
+* @param args.values - the raw values, keyed by secret name.
+*/
+function createMemorySecrets(args) {
+	const values = args.values;
+	return {
+		get: (name) => name in values ? makeSecret({ reveal: values[name] }) : void 0,
+		has: (name) => name in values
+	};
+}
+//#endregion
+//#region src/ports/secret-provider/secret-provider.port.ts
+/**
+* The {@link SecretProvider} contract. Implementations: `env-secrets`,
+* `memory-secrets`.
+*/
+const SecretProviderPort = {
+	id: "venn.port.secrets",
+	version: 1,
+	requires: ["secrets"],
+	methods: ["get", "has"]
+};
+//#endregion
+//#region src/host/create-test-host.ts
+/**
+* A host of doubles, every capability granted. The default for tests.
+*
+* @param overrides - replaces individual members, e.g. a real clock.
+*/
+function createTestHost(overrides = {}) {
+	return {
+		fs: createMemoryFs(),
+		proc: createFakeProcess(),
+		clock: createVirtualClock(),
+		random: createSeededRandom({ seed: 1 }),
+		secrets: createMemorySecrets({ values: {} }),
+		log: createMemoryLogger(),
+		lock: createInProcessLock(),
+		caps: ALL_CAPABILITIES,
+		...overrides
+	};
+}
+//#endregion
+//#region src/host/unavailable.ts
+/**
+* A stand-in for a port the host cannot provide, such as `process` in a Worker.
+*
+* @param args.capability - the capability the host lacks, named in the error.
+* @param args.methods - the port's declared methods, usually `SomePort.methods`.
+* @returns an object shaped like `T` whose every method throws VN2012 when
+* called, rather than failing as a `TypeError` mid-run.
+*/
+function unavailable(args) {
+	const bag = {};
+	for (const method of args.methods) bag[method] = () => {
+		throw capabilityUnavailable({
+			capability: args.capability,
+			method
+		});
+	};
+	return bag;
+}
+//#endregion
+//#region src/host/create-worker-host.ts
+/**
+* Host for a Web Worker: an in-memory file system, no `process`, no `net`.
+*
+* `proc` is a stand-in whose every method throws VN2012, so reaching for a
+* subprocess in the editor fails with a diagnostic instead of a `TypeError`.
+*/
+function createWorkerHost() {
+	return {
+		fs: createMemoryFs(),
+		proc: unavailable({
+			capability: "process",
+			methods: ProcessProviderPort.methods
+		}),
+		clock: createSystemClock(),
+		random: createSeededRandom({ seed: 1 }),
+		secrets: createMemorySecrets({ values: {} }),
+		log: createMemoryLogger(),
+		lock: createInProcessLock(),
+		caps: [
+			"fs",
+			"clock",
+			"random",
+			"secrets",
+			"log"
+		]
+	};
+}
+//#endregion
+//#region src/host/create-host.ts
+/**
+* The neutral host assemblers.
+*
+* `node` is deliberately absent: it pulls `node:*`, so it lives behind
+* `@venn-lang/contracts/node` as `createNodeHost` and this entry stays Worker-safe.
+*/
+const createHost = {
+	worker: createWorkerHost,
+	test: createTestHost
+};
+//#endregion
+//#region src/port/missing-capabilities.ts
+/**
+* The gap between what is required and what the host offers.
+*
+* @returns the required capabilities absent from `caps`, in the order required.
+*/
+function missingCapabilities(args) {
+	const present = new Set(args.caps);
+	return args.requires.filter((cap) => !present.has(cap));
+}
+//#endregion
+//#region src/port/assert-capabilities.ts
+/**
+* Checks the host against what the port requires.
+*
+* @throws VennError VN2010 when a required capability is absent.
+*/
+function assertCapabilities(args) {
+	const missing = missingCapabilities({
+		requires: args.port.requires,
+		caps: args.caps
+	});
+	if (missing.length === 0) return;
+	throw hostMissingCapability({
+		portId: args.port.id,
+		missing,
+		present: args.caps
+	});
+}
+//#endregion
+//#region src/port/assert-port-shape.ts
+/**
+* Checks the implementation against the methods the port declares.
+*
+* @throws VennError VN2011 when a declared method is missing or is not callable.
+*/
+function assertPortShape(args) {
+	const missing = missingMethods(args.port, args.impl);
+	if (missing.length === 0) return;
+	throw portShapeMismatch({
+		portId: args.port.id,
+		missing
+	});
+}
+function missingMethods(port, impl) {
+	const bag = impl;
+	return port.methods.filter((m) => typeof bag?.[m] !== "function");
+}
+//#endregion
+//#region src/port/bind-port.ts
+/**
+* The single loader entry. Negotiates capabilities, checks the implementation's
+* shape, then hands it back typed as `T`.
+*
+* Both checks run before anything is bound, so a mismatch is reported at start
+* up rather than as a `TypeError` in the middle of a test.
+*
+* @param args.port - the descriptor to bind against.
+* @param args.impl - the candidate implementation, untrusted.
+* @param args.caps - the capabilities the host advertises.
+* @returns `args.impl` typed as `T`.
+* @throws VennError VN2010 when the host lacks a required capability, VN2011
+* when the implementation is missing a declared method.
+*/
+function bindPort(args) {
+	assertCapabilities({
+		port: args.port,
+		caps: args.caps
+	});
+	assertPortShape({
+		port: args.port,
+		impl: args.impl
+	});
+	return args.impl;
+}
+//#endregion
+//#region src/ports/console/console.port.ts
+/**
+* The {@link Console} contract. Implementations: `node-console`,
+* `memory-console`.
+*/
+const ConsolePort = {
+	id: "venn.port.console",
+	version: 1,
+	requires: ["io"],
+	methods: [
+		"write",
+		"writeError",
+		"readLine",
+		"args"
+	]
+};
+//#endregion
+//#region src/ports/console/memory-console.ts
+/**
+* The double: records what was written, reads from a scripted input.
+*
+* @param args.input - the lines `readLine` hands back, in order.
+* @param args.argv - what `args()` reports.
+*/
+function createMemoryConsole(args = {}) {
+	const state = {
+		out: "",
+		err: ""
+	};
+	const input = [...args.input ?? []];
+	return {
+		write: (text) => {
+			state.out += text;
+		},
+		writeError: (text) => {
+			state.err += text;
+		},
+		readLine: () => Promise.resolve(input.length > 0 ? input.shift() ?? null : null),
+		args: () => args.argv ?? [],
+		get out() {
+			return state.out;
+		},
+		get err() {
+			return state.err;
+		}
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/read/scalars.ts
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+function asStringMap(value) {
+	const out = {};
+	for (const [key, item] of Object.entries(asRecord(value))) out[key] = String(item);
+	return out;
+}
+function asList(value) {
+	return Array.isArray(value) ? value.map(String) : [];
+}
+function asRecords(value) {
+	return Array.isArray(value) ? value.map(asRecord) : [];
+}
+function asString(value) {
+	return value === void 0 || value === null ? void 0 : String(value);
+}
+function asNumber(value) {
+	const parsed = Number(value);
+	return value === void 0 || Number.isNaN(parsed) ? void 0 : parsed;
+}
+function asBoolean(value) {
+	if (value === void 0) return void 0;
+	return value === true || value === "true";
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-dependencies.ts
+/**
+* A dependency table, in either spelling TOML allows.
+*
+* `zod = "^4"` and `zod = { version = "^4", optional = true }` say the same
+* thing about the version, so both read into one shape rather than two the rest
+* of the code would have to keep apart.
+*/
+function readDependencies(value) {
+	return Object.entries(asRecord(value)).map(([name, spec]) => readOne(name, spec));
+}
+function readOne(name, spec) {
+	if (typeof spec === "string") return {
+		name,
+		version: spec,
+		fromWorkspace: false,
+		optional: false
+	};
+	const table = asRecord(spec);
+	return {
+		name,
+		version: asString(table.version),
+		path: asString(table.path),
+		fromWorkspace: asBoolean(table.workspace) ?? false,
+		optional: asBoolean(table.optional) ?? false
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-package.ts
+/** `[package]`: who this is. A missing table reads as a nameless package. */
+function readPackage(data) {
+	const table = asRecord(data.package);
+	return {
+		name: String(table.name ?? ""),
+		version: asString(table.version),
+		description: asString(table.description),
+		license: asString(table.license),
+		authors: asList(table.authors),
+		edition: asString(table.edition)
+	};
+}
+/**
+* The same table, reduced to what a member may inherit from its workspace.
+*
+* A name is never inherited, being the one thing that must differ between two
+* members, so `[workspace.package]` carrying one is read as carrying none.
+*/
+function readInheritable(data) {
+	const table = asRecord(data);
+	const found = {};
+	for (const key of [
+		"version",
+		"description",
+		"license",
+		"edition"
+	]) {
+		const value = asString(table[key]);
+		if (value !== void 0) found[key] = value;
+	}
+	const authors = asList(table.authors);
+	return authors.length > 0 ? {
+		...found,
+		authors
+	} : found;
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-profiles.ts
+/**
+* What each build is for, and what that costs.
+*
+* `dev` reports what it finds and carries on, because a project being worked on
+* is half-written most of the time. `release` refuses to build over a problem.
+* Neither has to be written in a manifest for the defaults to apply.
+*/
+const DEFAULT_PROFILES = {
+	dev: { strict: false },
+	release: { strict: true }
+};
+/** `[profile.<name>]`, merged over {@link DEFAULT_PROFILES}. */
+function readProfiles(data) {
+	const out = { ...DEFAULT_PROFILES };
+	for (const [name, table] of Object.entries(asRecord(data.profile))) out[name] = {
+		...out[name],
+		...readProfile(asRecord(table))
+	};
+	return out;
+}
+function readProfile(table) {
+	const found = {};
+	for (const key of ["strict"]) {
+		const value = asBoolean(table[key]);
+		if (value !== void 0) found[key] = value;
+	}
+	return found;
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-targets.ts
+/** Where a `lib` target starts when the manifest does not say. */
+const LIB_ROOT = "src/lib.vn";
+/** Where the default `bin` target starts when the manifest does not say. */
+const MAIN_ROOT = "src/main.vn";
+/** Where additional `bin` targets are looked for by convention. */
+const BIN_DIR = "src/bin";
+/**
+* `[lib]` and `[[bin]]`: what this package builds.
+*
+* Only what the manifest *declares*. The conventional roots are filled in by
+* whoever can look at the disk, because a convention is a claim about files
+* existing and this reader is pure. A manifest declaring nothing is the common
+* case, not an empty one.
+*/
+function readTargets(data, packageName) {
+	const found = [];
+	if (data.lib !== void 0) found.push(readLib(asRecord(data.lib), packageName));
+	for (const entry of asRecords(data.bin)) found.push(readBin(entry, packageName));
+	return found;
+}
+function readLib(table, packageName) {
+	return {
+		kind: "lib",
+		name: asString(table.name) ?? packageName,
+		path: asString(table.path) ?? "src/lib.vn"
+	};
+}
+function readBin(table, packageName) {
+	const name = asString(table.name) ?? packageName;
+	return {
+		kind: "bin",
+		name,
+		path: asString(table.path) ?? `src/bin/${name}.vn`
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-tooling.ts
+const MANAGERS = /* @__PURE__ */ new Set([
+	"pnpm",
+	"npm",
+	"bun",
+	"yarn"
+]);
+/**
+* `[tooling]`: which package manager runs underneath.
+*
+* An unrecognised name falls back to pnpm rather than failing, so a manifest
+* written against a newer toolchain still opens.
+*/
+function readTooling(data) {
+	const name = asString(asRecord(data.tooling).manager);
+	return { manager: name && MANAGERS.has(name) ? name : "pnpm" };
+}
+//#endregion
+//#region src/ports/manifest-provider/read/read-workspace.ts
+/**
+* `[workspace]`, or undefined when the manifest is a plain package.
+*
+* A root may also be a package, so `[workspace]` and `[package]` are read
+* separately and never merged.
+*/
+function readWorkspace(data) {
+	if (data.workspace === void 0) return void 0;
+	const table = asRecord(data.workspace);
+	return {
+		members: asList(table.members),
+		exclude: asList(table.exclude),
+		defaultMembers: asList(table["default-members"]),
+		package: readInheritable(asRecord(table.package)),
+		dependencies: readDependencies(table.dependencies)
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/default-manifest.ts
+/**
+* A manifest with nothing declared: what a project without a `venn.toml` is.
+*
+* The one place stating what a project gets for saying nothing at all, so a
+* caller who wants one field need not spell the other dozen.
+*
+* @param overrides - fields to state explicitly. `name` and `version` fall back
+* to `[package]` before falling back to the defaults.
+*/
+function defaultManifest(overrides = {}) {
+	const pkg = {
+		name: "",
+		authors: [],
+		...overrides.package
+	};
+	return {
+		name: overrides.name ?? pkg.name,
+		version: overrides.version ?? pkg.version ?? "0.0.0",
+		package: pkg,
+		targets: [],
+		dependencies: [],
+		devDependencies: [],
+		patch: [],
+		profiles: { ...DEFAULT_PROFILES },
+		tooling: { manager: "pnpm" },
+		env: {},
+		envFiles: [],
+		paths: {},
+		format: {},
+		...overrides
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/edit/table-span.ts
+/**
+* Where a `[table]` is written, or undefined when the file has none.
+*
+* Found by reading lines rather than by re-serialising the parse tree. A
+* manifest carries its author's comments, blank lines and chosen order, and
+* rebuilding it from a tree would throw all of that away.
+*/
+function tableSpan(lines, name) {
+	const header = lines.findIndex((line) => line.trim() === `[${name}]`);
+	if (header < 0) return void 0;
+	let to = header + 1;
+	for (let at = header + 1; at < lines.length; at++) {
+		if (lines[at]?.trimStart().startsWith("[")) break;
+		if (lines[at]?.trim() !== "") to = at + 1;
+	}
+	return {
+		header,
+		from: header + 1,
+		to
+	};
+}
+/** The key a `key = value` line writes, or undefined for a comment or a blank. */
+function keyOf(line) {
+	const text = line.trim();
+	if (text === "" || text.startsWith("#") || text.startsWith("[")) return void 0;
+	const equals = text.indexOf("=");
+	return equals < 0 ? void 0 : text.slice(0, equals).trim().replace(/^["']|["']$/g, "");
+}
+//#endregion
+//#region src/ports/manifest-provider/edit/edit-dependency.ts
+/** The table an edit touches unless told otherwise. */
+const DEPENDENCIES = "dependencies";
+/**
+* The manifest with one dependency written in, everything else untouched.
+*
+* Entries are kept in name order, so two people adding two packages produce two
+* one-line diffs rather than a conflict. A name already there is replaced where
+* it stands, because an upgrade should not move the line.
+*
+* @returns the whole manifest as text. A missing table is appended at the end.
+*/
+function addDependency(args) {
+	const table = args.table ?? "dependencies";
+	const lines = args.text.split("\n");
+	const entry = `${args.name} = "${args.version}"`;
+	const span = tableSpan(lines, table);
+	if (!span) return appended(args.text, table, entry);
+	const at = lines.findIndex((line, index) => inside(span, index) && keyOf(line) === args.name);
+	if (at >= 0) return replaced(lines, at, entry);
+	return replaced(lines, insertionPoint(lines, span, args.name), entry, "insert");
+}
+/**
+* The manifest without that dependency.
+*
+* @returns the text unchanged when the name is not there: absent is already the
+* wanted state.
+*/
+function removeDependency(args) {
+	const table = args.table ?? "dependencies";
+	const lines = args.text.split("\n");
+	const span = tableSpan(lines, table);
+	if (!span) return args.text;
+	const at = lines.findIndex((line, index) => inside(span, index) && keyOf(line) === args.name);
+	if (at < 0) return args.text;
+	return [...lines.slice(0, at), ...lines.slice(at + 1)].join("\n");
+}
+function inside(span, index) {
+	return index >= span.from && index < span.to;
+}
+/** Where the name belongs, in order, among the entries already there. */
+function insertionPoint(lines, span, name) {
+	for (let at = span.from; at < span.to; at++) {
+		const key = keyOf(lines[at] ?? "");
+		if (key && key > name) return at;
+	}
+	return span.to;
+}
+function replaced(lines, at, entry, how = "replace") {
+	const after = how === "insert" ? lines.slice(at) : lines.slice(at + 1);
+	return [
+		...lines.slice(0, at),
+		entry,
+		...after
+	].join("\n");
+}
+/** A table the manifest does not have yet, written at the end where it reads. */
+function appended(text, table, entry) {
+	return `${text.endsWith("\n") ? text : `${text}\n`}\n[${table}]\n${entry}\n`;
+}
+//#endregion
+//#region src/ports/manifest-provider/manifest.port.ts
+/**
+* The {@link ManifestProvider} contract. Implementations: `toml-manifest`,
+* `memory-manifest`.
+*
+* Requires nothing: reading the file is the caller's job, and what arrives here
+* is already text.
+*/
+const ManifestProviderPort = {
+	id: "venn.port.manifest",
+	version: 1,
+	requires: [],
+	methods: ["load"]
+};
+//#endregion
+//#region src/ports/manifest-provider/memory-manifest.ts
+/**
+* The double: a preset manifest, with no file involved.
+*
+* Takes only what the caller cares about. The rest is what a project that
+* declared nothing would get, which is exactly what the real provider gives a
+* `venn.toml` silent on those tables.
+*/
+function createMemoryManifest(args) {
+	const manifest = defaultManifest(args.manifest);
+	return { load: () => manifest };
+}
+//#endregion
+//#region src/ports/manifest-provider/resolve-alias.ts
+/**
+* Split a `#alias/rest` import specifier against `[paths]` from `venn.toml`.
+*
+* @returns undefined when the specifier names no configured alias, which the
+* caller reads as a relative or bare path.
+*/
+function resolveAlias(args) {
+	const alias = Object.keys(args.paths).find((key) => args.spec.startsWith(`${key}/`));
+	if (!alias) return void 0;
+	return {
+		dir: args.paths[alias],
+		rest: args.spec.slice(alias.length + 1)
+	};
+}
+//#endregion
+//#region src/ports/manifest-provider/toml/read-value.ts
+/** A cursor over `text`, positioned at the start. */
+function cursor(text) {
+	return {
+		text,
+		index: 0
+	};
+}
+/**
+* One TOML value: a string, a number, a bool, an array, or an inline table.
+*
+* Reads by walking rather than by splitting, because a comma can sit inside a
+* value: splitting turns `["a,b"]` into two items and leaves
+* `{ version = "^4" }` as the text it was written in.
+*/
+function readValue(cur) {
+	skipSpace(cur);
+	const ch = cur.text[cur.index];
+	if (ch === "\"" || ch === "'") return readString(cur);
+	if (ch === "[") return readArray(cur);
+	if (ch === "{") return readInlineTable(cur);
+	return readBare(cur);
+}
+function skipSpace(cur) {
+	while (/\s/.test(cur.text[cur.index] ?? "")) cur.index++;
+}
+/** A basic string reads escapes; a literal one, in single quotes, does not. */
+function readString(cur) {
+	const quote = cur.text[cur.index];
+	cur.index++;
+	let out = "";
+	while (cur.index < cur.text.length && cur.text[cur.index] !== quote) if (quote === "\"" && cur.text[cur.index] === "\\") out += unescaped(cur);
+	else out += cur.text[cur.index++];
+	cur.index++;
+	return out;
+}
+const ESCAPES = {
+	n: "\n",
+	t: "	",
+	r: "\r",
+	"\\": "\\",
+	"\"": "\""
+};
+function unescaped(cur) {
+	const code = cur.text[cur.index + 1] ?? "";
+	cur.index += 2;
+	return ESCAPES[code] ?? code;
+}
+function readArray(cur) {
+	cur.index++;
+	const out = [];
+	while (!atClose(cur, "]")) {
+		out.push(readValue(cur));
+		skipSeparator(cur);
+	}
+	cur.index++;
+	return out;
+}
+function readInlineTable(cur) {
+	cur.index++;
+	const out = {};
+	while (!atClose(cur, "}")) {
+		const key = readKey(cur);
+		if (key === void 0) break;
+		out[key] = readValue(cur);
+		skipSeparator(cur);
+	}
+	cur.index++;
+	return out;
+}
+function readKey(cur) {
+	skipSpace(cur);
+	const equals = cur.text.indexOf("=", cur.index);
+	if (equals < 0) return void 0;
+	const raw = cur.text.slice(cur.index, equals).trim();
+	cur.index = equals + 1;
+	return raw.replace(/^["']|["']$/g, "");
+}
+function atClose(cur, close) {
+	skipSpace(cur);
+	return cur.index >= cur.text.length || cur.text[cur.index] === close;
+}
+function skipSeparator(cur) {
+	skipSpace(cur);
+	if (cur.text[cur.index] === ",") cur.index++;
+}
+/** Anything unquoted: `true`, `12`, `1.5`, or a word the manifest gives meaning. */
+function readBare(cur) {
+	const start = cur.index;
+	while (cur.index < cur.text.length && !",]}".includes(cur.text[cur.index] ?? "")) cur.index++;
+	const raw = cur.text.slice(start, cur.index).trim();
+	if (raw === "true" || raw === "false") return raw === "true";
+	const num = Number(raw);
+	return raw !== "" && !Number.isNaN(num) ? num : raw;
+}
+//#endregion
+//#region src/ports/manifest-provider/toml/sections.ts
+/** The table `[path]` names, created along the way if it is not there yet. */
+function enterSection(root, path) {
+	let node = root;
+	for (const key of keysOf(path)) {
+		node[key] ??= {};
+		node = node[key];
+	}
+	return node;
+}
+/**
+* `[[bin]]`: one more of something there may be several of.
+*
+* Returns the table just appended, so two `[[bin]]` sections give two bins
+* rather than one bin written twice.
+*/
+function enterTableArray(root, path) {
+	const keys = keysOf(path);
+	const last = keys.pop();
+	if (!last) return root;
+	const parent = enterSection(root, keys.join("."));
+	const found = Array.isArray(parent[last]) ? parent[last] : [];
+	parent[last] = found;
+	const table = {};
+	found.push(table);
+	return table;
+}
+function keysOf(path) {
+	return path.split(".").map((part) => part.trim().replace(/^["']|["']$/g, "")).filter((part) => part !== "");
+}
+//#endregion
+//#region src/ports/manifest-provider/toml/parse-toml.ts
+/**
+* A TOML reader for `venn.toml`: sections, nested `[a.b]`, arrays of tables
+* (`[[bin]]`), `key = value`, strings, numbers, bools, arrays and inline tables.
+*
+* Not a full TOML parser. No dates, no multi-line strings, no dotted keys.
+* `venn.toml` is our own format, so the subset is a decision rather than a
+* shortfall.
+*
+* @returns the root table. Malformed lines are skipped, never thrown on.
+*/
+function parseToml(content) {
+	const root = {};
+	let section = root;
+	for (const raw of content.split(/\r?\n/)) {
+		const line = stripComment(raw).trim();
+		if (line === "") continue;
+		if (line.startsWith("[")) section = openSection(root, line);
+		else assign(section, line);
+	}
+	return root;
+}
+/** `[[bin]]` appends another table, `[bin]` opens the one and only. */
+function openSection(root, line) {
+	if (line.startsWith("[[")) return enterTableArray(root, line.slice(2, line.indexOf("]]")));
+	return enterSection(root, line.slice(1, line.indexOf("]")));
+}
+function stripComment(line) {
+	let quote;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (ch === "\"" || ch === "'") quote = quote === ch ? void 0 : quote ?? ch;
+		else if (ch === "#" && !quote) return line.slice(0, i);
+	}
+	return line;
+}
+function assign(section, line) {
+	const eq = line.indexOf("=");
+	if (eq < 0) return;
+	const key = line.slice(0, eq).trim().replace(/^["']|["']$/g, "");
+	section[key] = readValue(cursor(line.slice(eq + 1)));
+}
+//#endregion
+//#region src/ports/manifest-provider/toml-docs.ts
+const COMMENT = /^\s*#\s?(.*)$/;
+const KEY = /^\s*([A-Za-z_][\w-]*)\s*=/;
+/**
+* The comment block written directly above a key, read as that key's
+* documentation. The same idea as `##` above a declaration in a `.vn`.
+*
+* A blank line breaks the block, so a comment separated from a key belongs to
+* nobody and is never attributed to the next one down.
+*
+* @returns documentation keyed by the key it sits above.
+*/
+function tomlDocs(content) {
+	const docs = {};
+	let block = [];
+	for (const line of content.split(/\r?\n/)) {
+		const comment = COMMENT.exec(line);
+		if (comment) {
+			block.push(comment[1] ?? "");
+			continue;
+		}
+		const key = KEY.exec(line)?.[1];
+		if (key && block.length > 0) docs[key] = block.join("\n").trim();
+		block = [];
+	}
+	return docs;
+}
+//#endregion
+//#region src/ports/manifest-provider/read-run-settings.ts
+/**
+* How the project runs, as against what it is: environments, path aliases and
+* formatting.
+*/
+function readRunSettings(data) {
+	return {
+		env: readEnv(data.env),
+		envFiles: asList(asRecord(data.env).files),
+		paths: asStringMap(data.paths),
+		format: readFormat(data.format)
+	};
+}
+function readFormat(value) {
+	const table = asRecord(value);
+	return {
+		indent: asNumber(table.indent),
+		tabs: asBoolean(table.tabs),
+		organize: asBoolean(table.organize),
+		sort: asBoolean(table.sort)
+	};
+}
+/** `files` configures where to read from; every other key names an environment. */
+const RESERVED = /* @__PURE__ */ new Set(["files"]);
+function readEnv(value) {
+	const out = {};
+	for (const [name, vars] of Object.entries(asRecord(value))) if (!RESERVED.has(name)) out[name] = asStringMap(vars);
+	return out;
+}
+//#endregion
+//#region src/ports/manifest-provider/toml-manifest.ts
+/**
+* The real one: parse `venn.toml` into a {@link Manifest}.
+*
+* Parsing happens once, at construction, so repeated `load()` calls are free
+* and always agree.
+*
+* @param args.content - the manifest as written.
+*/
+function createTomlManifest(args) {
+	const manifest = toManifest(parseToml(args.content));
+	return { load: () => manifest };
+}
+function toManifest(data) {
+	const pkg = readPackage(data);
+	return {
+		name: pkg.name,
+		version: pkg.version ?? "0.0.0",
+		package: pkg,
+		targets: readTargets(data, pkg.name),
+		dependencies: readDependencies(data.dependencies),
+		devDependencies: readDependencies(data["dev-dependencies"]),
+		patch: readDependencies(data.patch),
+		profiles: readProfiles(data),
+		tooling: readTooling(data),
+		workspace: readWorkspace(data),
+		...readRunSettings(data)
+	};
+}
+//#endregion
+//#region src/ports/signal-source/fake-signals.ts
+/**
+* The double: a signal arrives because a test said so. No process, no operating
+* system, no risk of stopping the test runner along with the code under test.
+*/
+function createFakeSignals() {
+	const handlers = /* @__PURE__ */ new Map();
+	return {
+		get listening() {
+			return [...handlers].filter(([, set]) => set.size > 0).map(([signal]) => signal);
+		},
+		on: (signal, handler) => subscribe({
+			handlers,
+			signal,
+			handler
+		}),
+		raise: (signal) => {
+			for (const handler of [...handlers.get(signal) ?? []]) handler(signal);
+		}
+	};
+}
+function subscribe(args) {
+	const set = args.handlers.get(args.signal) ?? /* @__PURE__ */ new Set();
+	set.add(args.handler);
+	args.handlers.set(args.signal, set);
+	return () => {
+		set.delete(args.handler);
+	};
+}
+//#endregion
+//#region src/ports/signal-source/signal-source.port.ts
+/**
+* The {@link SignalSource} contract. Implementations: `node-signals`,
+* `fake-signals`.
+*/
+const SignalSourcePort = {
+	id: "venn.port.signals",
+	version: 1,
+	requires: ["process"],
+	methods: ["on"]
+};
+//#endregion
+//#region src/ports/signal-source/signal-source.types.ts
+/**
+* The ways a system asks a program to stop. `SIGBREAK` is Windows' Ctrl+Break,
+* `SIGHUP` is the terminal itself going away.
+*/
+const ALL_SIGNALS = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGBREAK",
+	"SIGHUP"
+];
+//#endregion
+export { ALL_CAPABILITIES, ALL_SIGNALS, BIN_DIR, ClockPort, ConsolePort, DEFAULT_PROFILES, DEPENDENCIES, DOTENV_CONVENTION, FileSystemPort, LIB_ROOT, LockProviderPort, MAIN_ROOT, ManifestProviderPort, ProcessProviderPort, REDACTED, RandomPort, SecretProviderPort, SignalSourcePort, VennError, addDependency, assertCapabilities, assertPortShape, bindPort, capabilityUnavailable, createConsoleLogger, createEnvSecrets, createFakeLock, createFakeProcess, createFakeSignals, createFixedRandom, createHost, createInProcessLock, createMemoryConsole, createMemoryFs, createMemoryLogger, createMemoryManifest, createMemorySecrets, createSeededRandom, createSystemClock, createTestHost, createTomlManifest, createVirtualClock, createWorkerHost, defaultManifest, dotenvFiles, fsNotFound, hostMissingCapability, makeSecret, missingCapabilities, parseDotenv, parseToml, portShapeMismatch, readInheritable, removeDependency, resolveAlias, tomlDocs, unavailable };
+
+//# sourceMappingURL=index.js.map