@sackville-mcp/cli 0.0.1-alpha.0

package/dist/src-DM4aqvlX.mjs

@@ -0,0 +1,2752 @@
+import { parseArgs } from "node:util";
+import { detectInstalledVersion, getDoc, listVersions, openDb, resolveVersion, searchDocs } from "@sackville-mcp/core";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ArtifactStore, Redactor, importToCollection, isGraphqlEnvelope, loadCollection, resolveSecretStore, runRequest, runRequestForContract, runRequestToHar, runSequence, validateCapturedTraffic, validateGraphqlOperation, validateOpenApiRequest, validateOpenApiResponse } from "@sackville-mcp/api";
+import { tmpdir } from "node:os";
+import { ArtifactStore as ArtifactStore$1, BrowserGate, BrowserManager, PageDriver, auditA11y, createSsrfProxy, driveBrowserFlowToHar, engineLauncher, loadFlow, resolveEngine, runFlow } from "@sackville-mcp/browser";
+import { Redactor as Redactor$1, resolveAndPin } from "@sackville-mcp/safety";
+import { CoverageGateError, coveragePyToIstanbul, runScoped, runScopedPython, uncoveredInDiff } from "@sackville-mcp/coverage";
+import { CHANGELOG_FILENAMES, auditDependency, changedDependencies, comparatorFor, dependencyNames, gemRepoUrl, githubOwnerRepo, loadOsvSnapshot, matchName, normalizePypiName, npmRepoUrl, pypiJsonToPackument, pypiRepoUrl, rubygemsToPackument, sliceChangelog } from "@sackville-mcp/deps";
+import { FlakeGateError, HistoryStore, Quarantine, QuarantineGateError, quarantineCandidates, runAndRecord, runAndRecordPytest } from "@sackville-mcp/flake";
+import { LanguageServerManager, LspGateError, LspQueryEngine, LspRenameEngine, defaultListFiles, parseServerRegistry } from "@sackville-mcp/lsp";
+import { MutateGateError, parseMutmutResults, runCosmicRay, runMutation, runMutmut, summarizeMutation } from "@sackville-mcp/mutate";
+import { ArtifactStore as ArtifactStore$2 } from "@sackville-mcp/artifacts";
+import { composeVerdict, fromContractResults, fromDependencyAudits, fromDiffCoverage, fromFlakeVerdicts, fromMutationSummary } from "@sackville-mcp/verdict";
+import { orchestrate } from "@sackville-mcp/verify";
+//#region src/api.ts
+/**
+* Load an operator-supplied custom-scalar coercer module (ADR 0018 slice 6). The human is the
+* operator, so a real module path is permitted. Returns the coercer record, or `undefined` on
+* ANY failure (missing/throwing module, or a non-object default export) AFTER writing a loud
+* error — the caller MUST then exit non-zero, never silently fall back to no coercers (which
+* would look clean — an absence-laundering hazard).
+*/
+async function loadCoercers(file, io) {
+	let exported;
+	try {
+		exported = (await import(pathToFileURL(resolve(file)).href)).default;
+	} catch (err) {
+		io.err(`api: failed to load --coercers module ${file}: ${err.message}\n`);
+		return;
+	}
+	if (!exported || typeof exported !== "object") {
+		io.err(`api: --coercers module ${file} must default-export an object of scalar coercers\n`);
+		return;
+	}
+	return exported;
+}
+/** Matches `{{secret:NAME}}` references; captures the NAME only (never a value). */
+const SECRET_RE = /\{\{\s*secret:\s*([^}\s]+)\s*\}\}/g;
+/** Collect sorted, unique secret NAMES referenced anywhere in a string. */
+function secretNames(...sources) {
+	const names = /* @__PURE__ */ new Set();
+	for (const s of sources) {
+		if (!s) continue;
+		for (const m of s.matchAll(SECRET_RE)) if (m[1]) names.add(m[1]);
+	}
+	return [...names].sort();
+}
+/** Replace `{{secret:NAME}}` references with a `[secret:NAME]` placeholder. */
+function maskSecrets(s) {
+	return s.replace(SECRET_RE, (_m, name) => `[secret:${name}]`);
+}
+/** Parse repeatable `--var k=v` flags (split on the FIRST `=`) into a record. */
+function parseVars$2(raw) {
+	const vars = {};
+	for (const item of raw ?? []) {
+		const eq = item.indexOf("=");
+		if (eq === -1) vars[item] = "";
+		else vars[item.slice(0, eq)] = item.slice(eq + 1);
+	}
+	return vars;
+}
+async function runApi(args, io) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "list": return cmdList(rest, io);
+		case "get": return cmdGet$1(rest, io);
+		case "run": return cmdRun$3(rest, io);
+		case "run-collection": return cmdRunCollection(rest, io);
+		case "validate": return await cmdValidate(rest, io);
+		case "validate-request": return cmdValidateRequest(rest, io);
+		case "validate-capture": return cmdValidateCapture(rest, io);
+		case "import": return cmdImport(rest, io);
+		default:
+			io.err(`unknown api subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+function cmdList(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { json: { type: "boolean" } }
+	});
+	const dir = positionals[0];
+	if (!dir) {
+		io.err("api list needs <dir>\n");
+		return 1;
+	}
+	const requests = [...loadCollection(dir).requests.values()].map((e) => ({
+		name: e.request.name,
+		method: e.request.method,
+		url: e.request.url
+	}));
+	if (values.json) {
+		io.out(`${JSON.stringify({ requests }, null, 2)}\n`);
+		return 0;
+	}
+	for (const r of requests) io.out(`${r.method}  ${r.name}  ${r.url}\n`);
+	return 0;
+}
+function cmdGet$1(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { json: { type: "boolean" } }
+	});
+	const [dir, name] = positionals;
+	if (!dir || !name) {
+		io.err("api get needs <dir> <name>\n");
+		return 1;
+	}
+	const entry = loadCollection(dir).requests.get(name);
+	if (!entry) {
+		io.err(`no request named ${name}\n`);
+		return 1;
+	}
+	const { request } = entry;
+	const secrets = secretNames(request.url, ...request.headers.flatMap((h) => [h.name, h.value]), request.body?.content);
+	if (values.json) {
+		io.out(`${JSON.stringify({
+			name: request.name,
+			method: request.method,
+			url: request.url,
+			headers: request.headers,
+			requiredSecrets: secrets
+		}, null, 2)}\n`);
+		return 0;
+	}
+	io.out(`${request.method}  ${maskSecrets(request.url)}\n`);
+	for (const h of request.headers) io.out(`  ${h.name}: ${maskSecrets(h.value)}\n`);
+	io.out(`required secrets: ${secrets.length ? secrets.join(", ") : "(none)"}\n`);
+	return 0;
+}
+/** Shared run-option flags for `run` and `run-collection`. */
+const RUN_OPTIONS = {
+	var: {
+		type: "string",
+		multiple: true
+	},
+	env: { type: "string" },
+	unsafe: { type: "boolean" },
+	"allow-host": {
+		type: "string",
+		multiple: true
+	},
+	"block-private": { type: "boolean" },
+	"max-redirects": { type: "string" },
+	keyring: { type: "boolean" },
+	json: { type: "boolean" }
+};
+/** Parse `--max-redirects` (a non-negative integer) or undefined. */
+function parseMaxRedirects(raw) {
+	if (raw === void 0) return void 0;
+	const n = Number(raw);
+	return Number.isInteger(n) && n >= 0 ? n : void 0;
+}
+/** Secret store for a run: opt into the OS keyring (chained ahead of env) with
+* `--keyring`, else the env default (`SACKVILLE_SECRET_<NAME>`). */
+function secretsFor(keyring) {
+	return keyring ? resolveSecretStore({ keyring: true }) : void 0;
+}
+/** Read a stored response body by handle and JSON-parse it; fall back to raw. */
+function parseStoredBody(artifacts, handle) {
+	const raw = artifacts.get(handle)?.body ?? "";
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+/** Redact every finding's message AND path through a redactor that learned the run's
+* resolved secrets — a finding can echo a captured body/param/variable value. */
+function redactContract(raw, secrets) {
+	const redactor = new Redactor();
+	for (const s of secrets) redactor.register(s.name, s.value);
+	return {
+		...raw,
+		findings: raw.findings.map((f) => ({
+			...f,
+			message: redactor.redact(f.message),
+			...f.path !== void 0 ? { path: redactor.redact(f.path) } : {}
+		}))
+	};
+}
+function printContract(io, contract, label = "contract") {
+	io.out(`${label}: ${contract.valid ? "valid" : "INVALID"}\n`);
+	for (const f of contract.findings) io.out(`  ${f.severity.toUpperCase()} ${f.kind}: ${f.message}${f.path ? ` (${f.path})` : ""}\n`);
+}
+async function cmdRun$3(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...RUN_OPTIONS,
+			openapi: { type: "string" },
+			graphql: { type: "string" },
+			coercers: { type: "string" }
+		}
+	});
+	const [dir, name] = positionals;
+	if (!dir || !name) {
+		io.err("api run needs <dir> <name>\n");
+		return 1;
+	}
+	const collection = loadCollection(dir);
+	if (!collection.requests.has(name)) {
+		io.err(`no request named ${name}\n`);
+		return 1;
+	}
+	const artifacts = new ArtifactStore();
+	const runOpts = {
+		vars: parseVars$2(values.var),
+		env: values.env,
+		allowUnsafe: values.unsafe ?? false,
+		allowedHosts: values["allow-host"],
+		allowPrivate: !values["block-private"],
+		maxRedirects: parseMaxRedirects(values["max-redirects"]),
+		secrets: secretsFor(values.keyring),
+		artifacts
+	};
+	let result;
+	let reqCapture;
+	if (values.openapi || values.graphql) {
+		const driven = await runRequestForContract(collection, name, runOpts);
+		result = driven.result;
+		reqCapture = driven.capture;
+	} else result = await runRequest(collection, name, runOpts);
+	let contract;
+	let requestContract;
+	if (values.openapi) {
+		const spec = JSON.parse(readFileSync(values.openapi, "utf8"));
+		const baseDir = dirname(values.openapi);
+		if (result.sent && result.response) {
+			const url = new URL(result.request.url);
+			contract = validateOpenApiResponse(spec, {
+				method: result.request.method,
+				path: url.pathname
+			}, {
+				status: result.response.status,
+				headers: result.response.headers,
+				body: parseStoredBody(artifacts, result.response.bodyHandle)
+			}, { baseDir });
+		}
+		if (reqCapture && !isGraphqlEnvelope(reqCapture.request.body)) requestContract = redactContract(validateOpenApiRequest(spec, reqCapture.request, {
+			baseDir,
+			bodyPresenceAuthoritative: true,
+			paramsAuthoritative: true
+		}), reqCapture.registeredSecrets);
+	}
+	let graphqlContract;
+	if (values.graphql && reqCapture && isGraphqlEnvelope(reqCapture.request.body)) {
+		const sdl = readFileSync(values.graphql, "utf8");
+		let scalarCoercers;
+		if (values.coercers !== void 0) {
+			scalarCoercers = await loadCoercers(values.coercers, io);
+			if (scalarCoercers === void 0) return 1;
+		}
+		const env = reqCapture.request.body;
+		graphqlContract = redactContract(validateGraphqlOperation(sdl, env.query, {
+			operationName: env.operationName,
+			...scalarCoercers ? { scalarCoercers } : {},
+			...result.sent && result.response ? { json: parseStoredBody(artifacts, result.response.bodyHandle) } : {},
+			...env.variables !== void 0 ? {
+				variables: env.variables,
+				variablesAuthoritative: true
+			} : {}
+		}), reqCapture.registeredSecrets);
+	}
+	const assertionsOk = !!result.response?.assertions.every((a) => a.pass);
+	const ok = result.sent && assertionsOk && (contract ? contract.valid : true) && (requestContract ? requestContract.valid : true) && (graphqlContract ? graphqlContract.valid : true);
+	if (values.json) {
+		io.out(`${JSON.stringify({
+			...result,
+			...contract ? { contract } : {},
+			...requestContract ? { requestContract } : {},
+			...graphqlContract ? { graphqlContract } : {}
+		}, null, 2)}\n`);
+		return ok ? 0 : 1;
+	}
+	io.out(`${result.request.method}  ${result.request.url}\n`);
+	if (result.sent) io.out("sent\n");
+	else io.out(`dry-run (not sent)${result.reason ? `: ${result.reason}` : ""}\n`);
+	if (result.response) {
+		const res = result.response;
+		io.out(`status ${res.status}  ${res.latencyMs}ms\n`);
+		for (const a of res.assertions) io.out(`${a.pass ? "PASS" : "FAIL"}  ${a.source} ${a.op}${a.path ? ` ${a.path}` : ""}\n`);
+		for (const t of res.scriptTests) io.out(`${t.pass ? "PASS" : "FAIL"}  script: ${t.name}${t.error ? ` — ${t.error}` : ""}\n`);
+		io.out(`body: ${res.bodyHandle}\n`);
+	}
+	if (requestContract) printContract(io, requestContract, "request contract");
+	if (contract) printContract(io, contract, "response contract");
+	if (graphqlContract) printContract(io, graphqlContract, "graphql contract");
+	return ok ? 0 : 1;
+}
+async function cmdRunCollection(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...RUN_OPTIONS,
+			"stop-on-failure": { type: "boolean" }
+		}
+	});
+	const [dir, ...names] = positionals;
+	if (!dir || names.length === 0) {
+		io.err("api run-collection needs <dir> <name...>\n");
+		return 1;
+	}
+	const artifacts = new ArtifactStore();
+	const result = await runSequence(loadCollection(dir), names, {
+		vars: parseVars$2(values.var),
+		env: values.env,
+		allowUnsafe: values.unsafe ?? false,
+		allowedHosts: values["allow-host"],
+		allowPrivate: !values["block-private"],
+		maxRedirects: parseMaxRedirects(values["max-redirects"]),
+		secrets: secretsFor(values.keyring),
+		stopOnFailure: values["stop-on-failure"] ?? false,
+		artifacts
+	});
+	const ok = result.steps.every((s) => s.result.sent && (s.result.response?.assertions.every((a) => a.pass) ?? false));
+	if (values.json) {
+		io.out(`${JSON.stringify(result, null, 2)}\n`);
+		return ok ? 0 : 1;
+	}
+	for (const step of result.steps) {
+		const res = step.result;
+		const status = res.sent ? String(res.response?.status ?? "-") : "dry-run";
+		const passed = res.sent && (res.response?.assertions.every((a) => a.pass) ?? false);
+		io.out(`${step.name}  ${status}  ${passed ? "PASS" : "FAIL"}\n`);
+	}
+	io.out(`captured: ${Object.keys(result.captured).join(", ") || "(none)"}\n`);
+	return ok ? 0 : 1;
+}
+const IMPORT_FORMATS = new Set([
+	"postman",
+	"insomnia",
+	"openapi",
+	"har"
+]);
+function cmdImport(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { name: { type: "string" } }
+	});
+	const [format, source, dest] = positionals;
+	if (!format || !source || !dest) {
+		io.err("api import needs <postman|insomnia|openapi|har> <source-file> <dest-dir>\n");
+		return 1;
+	}
+	if (!IMPORT_FORMATS.has(format)) {
+		io.err(`unknown import format: ${format} (expected postman|insomnia|openapi|har)\n`);
+		return 1;
+	}
+	const count = importToCollection(format, readFileSync(source, "utf8"), dest, { name: values.name });
+	io.out(`imported ${count} request(s) into ${dest}\n`);
+	return 0;
+}
+async function cmdValidate(args, io) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			graphql: { type: "string" },
+			query: { type: "string" },
+			operation: { type: "string" },
+			variables: { type: "string" },
+			coercers: { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	if (!values.graphql || !values.query) {
+		io.err("api validate needs --graphql <schemafile> --query <queryfile>\n");
+		return 1;
+	}
+	const sdl = readFileSync(values.graphql, "utf8");
+	const query = readFileSync(values.query, "utf8");
+	let variables;
+	if (values.variables !== void 0) try {
+		variables = JSON.parse(values.variables);
+	} catch {
+		variables = JSON.parse(readFileSync(values.variables, "utf8"));
+	}
+	let scalarCoercers;
+	if (values.coercers !== void 0) {
+		scalarCoercers = await loadCoercers(values.coercers, io);
+		if (scalarCoercers === void 0) return 1;
+	}
+	const contract = validateGraphqlOperation(sdl, query, {
+		operationName: values.operation,
+		...scalarCoercers ? { scalarCoercers } : {},
+		...variables !== void 0 ? {
+			variables,
+			variablesAuthoritative: true
+		} : {}
+	});
+	if (values.json) {
+		io.out(`${JSON.stringify(contract, null, 2)}\n`);
+		return contract.valid ? 0 : 1;
+	}
+	io.out(`valid: ${contract.valid}\n`);
+	for (const f of contract.findings) io.out(`  ${f.severity.toUpperCase()} ${f.kind}: ${f.message}${f.path ? ` (${f.path})` : ""}\n`);
+	return contract.valid ? 0 : 1;
+}
+/**
+* `api validate-request --openapi <spec.json> --method <M> --path </p> [--body <file>]
+* [--query k=v]…` — a preflight: validate a request's body + params against an OpenAPI
+* operation BEFORE sending it. The human supplies the real request, so body presence
+* and params are authoritative. (A GraphQL envelope is refused, not schema-failed.)
+*/
+function cmdValidateRequest(args, io) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			openapi: { type: "string" },
+			method: { type: "string" },
+			path: { type: "string" },
+			body: { type: "string" },
+			query: {
+				type: "string",
+				multiple: true
+			},
+			header: {
+				type: "string",
+				multiple: true
+			},
+			form: {
+				type: "string",
+				multiple: true
+			},
+			"form-file": {
+				type: "string",
+				multiple: true
+			},
+			json: { type: "boolean" }
+		}
+	});
+	if (!values.openapi || !values.method || !values.path) {
+		io.err("api validate-request needs --openapi <spec.json> --method <M> --path </p>\n");
+		return 1;
+	}
+	const spec = JSON.parse(readFileSync(values.openapi, "utf8"));
+	const body = values.body !== void 0 ? JSON.parse(readFileSync(values.body, "utf8")) : void 0;
+	if (isGraphqlEnvelope(body)) {
+		io.err("the request body is a GraphQL envelope ({query}); use `api validate --graphql` instead\n");
+		return 1;
+	}
+	const query = {};
+	for (const kv of values.query ?? []) {
+		const eq = kv.indexOf("=");
+		if (eq < 0) continue;
+		const k = kv.slice(0, eq);
+		const v = kv.slice(eq + 1);
+		const cur = query[k];
+		query[k] = cur === void 0 ? v : Array.isArray(cur) ? [...cur, v] : [cur, v];
+	}
+	const headers = {};
+	for (const hv of values.header ?? []) {
+		const c = hv.indexOf(":");
+		if (c < 0) continue;
+		headers[hv.slice(0, c).trim().toLowerCase()] = hv.slice(c + 1).trim();
+	}
+	const form = {};
+	for (const kv of values.form ?? []) {
+		const eq = kv.indexOf("=");
+		if (eq < 0) continue;
+		const k = kv.slice(0, eq);
+		const v = kv.slice(eq + 1);
+		const cur = form[k];
+		form[k] = cur === void 0 ? v : Array.isArray(cur) ? [...cur, v] : [cur, v];
+	}
+	const formFileFields = values["form-file"] ?? [];
+	const contract = validateOpenApiRequest(spec, {
+		method: values.method,
+		path: values.path,
+		body,
+		...Object.keys(query).length > 0 ? { query } : {},
+		...Object.keys(headers).length > 0 ? { headers } : {},
+		...Object.keys(form).length > 0 ? { form } : {},
+		...formFileFields.length > 0 ? { formFileFields } : {}
+	}, {
+		baseDir: dirname(values.openapi),
+		bodyPresenceAuthoritative: true,
+		paramsAuthoritative: true
+	});
+	if (values.json) {
+		io.out(`${JSON.stringify(contract, null, 2)}\n`);
+		return contract.valid ? 0 : 1;
+	}
+	io.out(`valid: ${contract.valid}\n`);
+	for (const f of contract.findings) io.out(`  ${f.severity.toUpperCase()} ${f.kind}: ${f.message}${f.path ? ` (${f.path})` : ""}\n`);
+	return contract.valid ? 0 : 1;
+}
+/**
+* `api validate-capture <har.zip> --openapi <spec.json> | --graphql <schema.graphql>`
+* — validate the traffic in a captured HAR against an OpenAPI and/or GraphQL
+* contract (ADR 0013, the capture→contract bridge). The human is the operator, so
+* the local HAR file is read directly (no surface capture gate). REST entries are
+* checked against the OpenAPI spec; GraphQL entries (at `--graphql-endpoint`,
+* default `/graphql`) are checked against the SDL. Exits 1 when not clean.
+*/
+function cmdValidateCapture(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			openapi: { type: "string" },
+			graphql: { type: "string" },
+			"graphql-endpoint": { type: "string" },
+			origin: {
+				type: "string",
+				multiple: true
+			},
+			json: { type: "boolean" }
+		}
+	});
+	const [harPath] = positionals;
+	if (!harPath || !values.openapi && !values.graphql) {
+		io.err("api validate-capture needs <har.zip> and --openapi <spec.json> and/or --graphql <schema.graphql>\n");
+		return 1;
+	}
+	const verdict = validateCapturedTraffic(readFileSync(harPath), {
+		...values.openapi ? { openapi: JSON.parse(readFileSync(values.openapi, "utf8")) } : {},
+		...values.graphql ? { graphql: {
+			endpointPath: values["graphql-endpoint"] ?? "/graphql",
+			sdl: readFileSync(values.graphql, "utf8")
+		} } : {}
+	}, { allowedOrigins: values.origin });
+	if (values.json) {
+		io.out(`${JSON.stringify(verdict, null, 2)}\n`);
+		return verdict.clean ? 0 : 1;
+	}
+	io.out(`capture: ${verdict.clean ? "clean" : "NOT CLEAN"} (${verdict.entriesValidated} entries)\n`);
+	for (const [kind, count] of Object.entries(verdict.findingsByKind)) io.out(`  ${count}× ${kind}\n`);
+	if (verdict.firstFailing) {
+		const f = verdict.firstFailing;
+		io.out(`  first failing: ${f.method} ${f.path} — ${f.kind}: ${f.message}\n`);
+	}
+	io.out(`  exercised: ${verdict.exercisedOperations.join(", ") || "(none)"}\n`);
+	if (verdict.unexercisedOperations.length > 0) io.out(`  unexercised: ${verdict.unexercisedOperations.join(", ")}\n`);
+	return verdict.clean ? 0 : 1;
+}
+//#endregion
+//#region src/browser.ts
+/** Flags shared by every browser command. */
+const COMMON_OPTIONS = {
+	"allow-host": {
+		type: "string",
+		multiple: true
+	},
+	"allow-private": { type: "boolean" },
+	"no-sandbox": { type: "boolean" },
+	headed: { type: "boolean" },
+	engine: { type: "string" },
+	json: { type: "boolean" }
+};
+function flagsFrom(values) {
+	return {
+		allowHost: values["allow-host"] ?? [],
+		allowPrivate: values["allow-private"] ?? false,
+		noSandbox: values["no-sandbox"] ?? false,
+		headed: values.headed ?? false,
+		engine: resolveEngine(values.engine)
+	};
+}
+/** Launch thunk for a `BrowserManager`, honoring the selected engine + the
+* mandatory SSRF proxy (chromium gets the hardening args; firefox/webkit get the
+* proxy + the Tier-1 route allowlist). */
+function launchFor(flags, proxyUrl) {
+	return engineLauncher(flags.engine, {
+		headless: !flags.headed,
+		proxyServer: proxyUrl,
+		noSandbox: flags.noSandbox
+	});
+}
+/**
+* Stand up a gated, proxy-fronted browser, navigate to `url`, run `fn`, and tear
+* everything down. Returns `undefined` for a bad URL (after reporting it).
+*/
+async function withSession(url, flags, io, fn) {
+	let host;
+	try {
+		host = new URL(url).hostname;
+	} catch {
+		io.err(`invalid url: ${url}\n`);
+		return 1;
+	}
+	const gate = new BrowserGate({ allowedHosts: [host, ...flags.allowHost] });
+	const proxy = await createSsrfProxy({ allowPrivate: flags.allowPrivate });
+	const store = new ArtifactStore$1(mkdtempSync(join(tmpdir(), "sackville-browser-cli-")));
+	const manager = new BrowserManager({
+		gate,
+		launch: launchFor(flags, proxy.url)
+	});
+	try {
+		const page = await (await manager.createSession("cli")).newPage();
+		const driver = new PageDriver(page, {
+			runId: "cli",
+			store,
+			gate
+		});
+		await driver.navigate(url);
+		return await fn({
+			driver,
+			store,
+			page
+		});
+	} catch (err) {
+		io.err(`${err.message}\n`);
+		return 1;
+	} finally {
+		await manager.shutdown();
+		await proxy.close();
+	}
+}
+async function runBrowser(args, io) {
+	const [sub, ...rest] = args;
+	try {
+		switch (sub) {
+			case "snapshot": return await cmdSnapshot(rest, io);
+			case "audit": return await cmdAudit$1(rest, io);
+			case "screenshot": return await cmdScreenshot(rest, io);
+			case "run": return await cmdRun$2(rest, io);
+			default:
+				io.err(`unknown browser subcommand: ${sub ?? "(none)"}\n`);
+				return 1;
+		}
+	} catch (err) {
+		io.err(`${err.message}\n`);
+		return 1;
+	}
+}
+/** Parse repeatable `--var k=v` flags (split on the FIRST `=`) into a record. */
+function parseVars$1(raw) {
+	const vars = {};
+	for (const item of raw ?? []) {
+		const eq = item.indexOf("=");
+		if (eq === -1) vars[item] = "";
+		else vars[item.slice(0, eq)] = item.slice(eq + 1);
+	}
+	return vars;
+}
+/**
+* Replay a persisted browser flow (`<flow>.bru` + sidecar) — `sackville browser
+* run <flow.bru>`. Unlike the single-shot commands the flow drives its own
+* navigations, so no URL is auto-allowed: the human allowlists target hosts with
+* `--allow-host` and unlocks mutations with `--unsafe` (else they dry-run).
+* `{{secret:NAME}}` resolves from `SACKVILLE_BROWSER_SECRET_<NAME>` env (the human
+* is the operator); a `Redactor` scrubs those values from every result. Exits
+* non-zero when the flow fails (a step error or a failed assertion) — CI-usable.
+*/
+async function cmdRun$2(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...COMMON_OPTIONS,
+			unsafe: { type: "boolean" },
+			var: {
+				type: "string",
+				multiple: true
+			}
+		}
+	});
+	const flowPath = positionals[0];
+	if (!flowPath) {
+		io.err("browser run needs <flow.bru>\n");
+		return 1;
+	}
+	let flow;
+	try {
+		flow = loadFlow(flowPath);
+	} catch (err) {
+		io.err(`${err.message}\n`);
+		return 1;
+	}
+	const env = io.env ?? {};
+	const redactor = new Redactor$1();
+	const secrets = /* @__PURE__ */ new Map();
+	for (const [key, val] of Object.entries(env)) {
+		const m = /^SACKVILLE_BROWSER_SECRET_(.+)$/.exec(key);
+		if (m?.[1] && val) {
+			redactor.register(m[1], val);
+			secrets.set(m[1], val);
+		}
+	}
+	const flags = flagsFrom(values);
+	const gate = new BrowserGate({
+		allowUnsafe: values.unsafe ?? false,
+		allowedHosts: flags.allowHost
+	});
+	const proxy = await createSsrfProxy({ allowPrivate: flags.allowPrivate });
+	const store = new ArtifactStore$1(mkdtempSync(join(tmpdir(), "sackville-browser-flow-")));
+	const manager = new BrowserManager({
+		gate,
+		launch: launchFor(flags, proxy.url)
+	});
+	try {
+		const result = await runFlow(new PageDriver(await (await manager.createSession("cli")).newPage(), {
+			runId: "cli",
+			store,
+			gate,
+			redact: (v) => redactor.redact(v)
+		}), flow, {
+			vars: parseVars$1(values.var),
+			resolveSecret: (name) => secrets.get(name)
+		});
+		if (values.json) io.out(`${JSON.stringify(result, null, 2)}\n`);
+		else printFlowResult(result, io);
+		return result.passed ? 0 : 1;
+	} catch (err) {
+		io.err(`${err.message}\n`);
+		return 1;
+	} finally {
+		await manager.shutdown();
+		await proxy.close();
+	}
+}
+function printFlowResult(result, io) {
+	io.out(`flow: ${result.name}\n`);
+	for (const step of result.steps) if (step.error) io.out(`  FAIL ${step.action} — ${step.error}\n`);
+	else if (step.assertions) {
+		const passed = step.assertions.filter((a) => a.pass).length;
+		const total = step.assertions.length;
+		io.out(`  ${passed === total ? "ok  " : "FAIL"} assert (${passed}/${total} passed)\n`);
+	} else io.out(`  ok   ${step.action}${step.dryRun ? " (dry-run)" : ""}\n`);
+	io.out(`${result.passed ? "PASS" : "FAIL"}\n`);
+}
+async function cmdSnapshot(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: COMMON_OPTIONS
+	});
+	const url = positionals[0];
+	if (!url) {
+		io.err("browser snapshot needs <url>\n");
+		return 1;
+	}
+	return withSession(url, flagsFrom(values), io, async ({ driver }) => {
+		const snap = await driver.snapshot();
+		if (values.json) {
+			io.out(`${JSON.stringify(snap, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`${snap.snapshot}\n`);
+		if (snap.truncated) io.err("(snapshot truncated — re-run with --json for the full handle)\n");
+		return 0;
+	});
+}
+async function cmdAudit$1(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: COMMON_OPTIONS
+	});
+	const url = positionals[0];
+	if (!url) {
+		io.err("browser audit needs <url>\n");
+		return 1;
+	}
+	return withSession(url, flagsFrom(values), io, async ({ store, page }) => {
+		const res = await auditA11y(page, {
+			runId: "cli",
+			store
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify(res, null, 2)}\n`);
+			return res.summary.violationCount === 0 ? 0 : 1;
+		}
+		const s = res.summary;
+		io.out(`violations: ${s.violationCount}\n`);
+		for (const v of s.top) io.out(`  [${v.impact ?? "-"}] ${v.id}: ${v.nodeCount} node(s) — ${v.help}\n`);
+		const path = store.get(res.resultsHandle)?.path;
+		if (path) io.out(`full report: ${path}\n`);
+		return s.violationCount === 0 ? 0 : 1;
+	});
+}
+async function cmdScreenshot(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...COMMON_OPTIONS,
+			out: { type: "string" },
+			"full-page": { type: "boolean" }
+		}
+	});
+	const url = positionals[0];
+	if (!url) {
+		io.err("browser screenshot needs <url>\n");
+		return 1;
+	}
+	const out = values.out ?? "screenshot.png";
+	return withSession(url, flagsFrom(values), io, async ({ driver, store }) => {
+		const shot = await driver.screenshot({ fullPage: values["full-page"] ?? false });
+		const bytes = shot.handle ? store.get(shot.handle)?.body : void 0;
+		if (!bytes) {
+			io.err("screenshot capture failed\n");
+			return 1;
+		}
+		writeFileSync(out, bytes);
+		if (values.json) {
+			io.out(`${JSON.stringify({
+				...shot,
+				savedTo: out
+			}, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`saved ${shot.byteSize} bytes to ${out}\n`);
+		return 0;
+	});
+}
+//#endregion
+//#region src/coverage.ts
+/**
+* `sackville coverage` — the human surface over `@sackville-mcp/coverage`.
+*
+* `uncovered-in-diff` is the pure forgotten-assertion catch: classify a diff's new lines
+* against an istanbul or coverage.py report and surface the executable-but-unhit ones.
+* `run-scoped` is the gated impact-scoped runner (`vitest related`). The human IS the
+* operator, so the gate is a straight-through `--allow-run` flag and the typed root is
+* auto-allowed; the test runner is injectable so the suite never spawns a real vitest
+* (ADR 0010: no real spawn in the gate). Both commands exit 1 when a new line is uncovered —
+* the catch is CI-actionable, like `sackville browser audit`.
+*/
+async function runCoverage(args, io, deps = {}) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "uncovered-in-diff": return cmdUncoveredInDiff(rest, io);
+		case "run-scoped": return cmdRunScoped(rest, io, deps);
+		default:
+			io.err(`unknown coverage subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+function printReport(io, report) {
+	const s = report.summary;
+	io.out(`files: ${report.files.length} (${s.filesWithoutCoverage} without coverage)  covered ${s.covered}  uncovered ${s.uncovered}  non-executable ${s.nonExecutable}\n`);
+	if (report.uncovered.length === 0) {
+		io.out("uncovered new lines: (none)\n");
+		return;
+	}
+	io.out(`uncovered new lines (${report.uncovered.length}):\n`);
+	for (const u of report.uncovered) io.out(`  ${u.path}:${u.line}\n`);
+}
+function cmdUncoveredInDiff(args, io) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			diff: { type: "string" },
+			coverage: { type: "string" },
+			"coverage-format": { type: "string" },
+			"project-root": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	if (!values.diff || !values.coverage) {
+		io.err("coverage uncovered-in-diff needs --diff <file> and --coverage <file>\n");
+		return 1;
+	}
+	const format = values["coverage-format"] ?? "istanbul";
+	if (format !== "istanbul" && format !== "coveragepy") {
+		io.err(`unknown coverage format: ${format} (expected istanbul|coveragepy)\n`);
+		return 1;
+	}
+	const diff = readFileSync(values.diff, "utf8");
+	const parsed = JSON.parse(readFileSync(values.coverage, "utf8"));
+	const report = uncoveredInDiff(diff, format === "coveragepy" ? coveragePyToIstanbul(parsed) : parsed, { projectRoot: values["project-root"] });
+	if (values.json) io.out(`${JSON.stringify(report, null, 2)}\n`);
+	else printReport(io, report);
+	return report.uncovered.length === 0 ? 0 : 1;
+}
+async function cmdRunScoped(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			"changed-file": {
+				type: "string",
+				multiple: true
+			},
+			diff: { type: "string" },
+			python: { type: "boolean" },
+			measure: {
+				type: "string",
+				multiple: true
+			},
+			"scope-mode": { type: "string" },
+			"allow-run": { type: "boolean" },
+			"timeout-ms": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const projectRoot = positionals[0];
+	if (!projectRoot) {
+		io.err("coverage run-scoped needs a <project-root>\n");
+		return 1;
+	}
+	const scopeMode = values["scope-mode"] ?? "report-gap";
+	if (values.python && scopeMode !== "report-gap" && scopeMode !== "widen") {
+		io.err(`unknown scope mode: ${scopeMode} (expected report-gap|widen)\n`);
+		return 1;
+	}
+	const timeoutRaw = values["timeout-ms"];
+	const timeoutMs = timeoutRaw !== void 0 ? Number(timeoutRaw) : void 0;
+	try {
+		const config = {
+			projectRoot,
+			allowedRoots: [resolve(projectRoot)],
+			allowRun: values["allow-run"] ?? false,
+			timeoutMs: timeoutMs !== void 0 && Number.isFinite(timeoutMs) ? timeoutMs : void 0
+		};
+		const changedFiles = values["changed-file"] ?? [];
+		const diff = values.diff !== void 0 ? readFileSync(values.diff, "utf8") : void 0;
+		const result = values.python ? await runScopedPython(config, {
+			changedFiles,
+			diff,
+			measureTargets: values.measure ?? [],
+			scopeMode
+		}, { runner: deps.runner }) : await runScoped(config, {
+			changedFiles,
+			diff
+		}, { runner: deps.runner });
+		const py = values.python ? result : void 0;
+		if (values.json) io.out(`${JSON.stringify(result, null, 2)}\n`);
+		else if (!result.ran) io.out("no changed files — nothing to run\n");
+		else {
+			io.out(`ran ${values.python ? "pytest" : "vitest"} (exit ${result.exitCode}); tests ${py?.inconclusive ? "INCONCLUSIVE" : result.passed ? "passed" : "FAILED"}; scoped: ${result.scopedFiles.join(", ")}\n`);
+			if (py?.unmatched) io.out(`uncovered-by-scope (no mirrored test): ${py.unmatched.join(", ")}\n`);
+			if (result.report) printReport(io, result.report);
+		}
+		return result.passed && !py?.inconclusive && (result.report ? result.report.uncovered.length === 0 : true) ? 0 : 1;
+	} catch (e) {
+		if (e instanceof CoverageGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+//#endregion
+//#region src/deps.ts
+/** Map an OSV ecosystem to the `@sackville-mcp/core` installed-version detection ecosystem. */
+const DETECT_ECOSYSTEM = {
+	npm: "node",
+	PyPI: "python",
+	RubyGems: "ruby"
+};
+/**
+* `sackville deps` — the human surface over `@sackville-mcp/deps`. Answers deprecation /
+* vulnerability / freshness for the version ACTUALLY INSTALLED in a project (not "latest").
+*
+* The human invoked the audit, so the CLI fetches by default (operator intent), with the
+* same SSRF pre-flight the bins use (`resolveAndPin`: metadata/link-local always refused,
+* private registries gated by `--allow-private`). Network + comparator dispatch reuse the
+* ecosystem helpers lifted into `@sackville-mcp/deps`. `audit`/`audit-project` exit 1 on a
+* security or deprecation finding (CI-actionable); `changelog` is informational.
+*/
+async function runDeps(args, io, deps = {}) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "audit": return cmdAudit(rest, io, deps);
+		case "audit-project": return cmdAuditProject(rest, io, deps);
+		case "changelog": return cmdChangelog(rest, io, deps);
+		default:
+			io.err(`unknown deps subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+/** Operator registry/SSRF flags shared by every deps command. */
+const REGISTRY_OPTIONS = {
+	ecosystem: { type: "string" },
+	"osv-db": { type: "string" },
+	registry: { type: "string" },
+	"pypi-registry": { type: "string" },
+	"rubygems-registry": { type: "string" },
+	"allow-private": { type: "boolean" },
+	json: { type: "boolean" }
+};
+function registriesFrom(values) {
+	return {
+		registry: values.registry || "https://registry.npmjs.org",
+		pypiRegistry: values["pypi-registry"] || "https://pypi.org/pypi",
+		rubygemsRegistry: values["rubygems-registry"] || "https://rubygems.org/api/v1",
+		allowPrivate: values["allow-private"] ?? false
+	};
+}
+function ecosystemFrom(values, io) {
+	const e = values.ecosystem ?? "npm";
+	if (e !== "npm" && e !== "PyPI" && e !== "RubyGems") {
+		io.err(`unknown ecosystem: ${e} (expected npm|PyPI|RubyGems)\n`);
+		return null;
+	}
+	return e;
+}
+/** npm packument path: keep a scope's `@` but escape the `/` (registry idiom). */
+function packumentUrl(registry, packageName) {
+	return `${registry.replace(/\/+$/, "")}/${packageName.replace("/", "%2f")}`;
+}
+/** Build the SSRF-pinned packument fetcher (npm/PyPI/RubyGems), mirroring the deps bin. */
+function makeFetcher(r) {
+	return async (packageName, ecosystem) => {
+		if (ecosystem === "npm") {
+			const url = packumentUrl(r.registry, packageName);
+			await resolveAndPin(new URL(url).hostname, void 0, { allowPrivate: r.allowPrivate });
+			const res = await fetch(url, { headers: { accept: "application/json" } });
+			if (!res.ok) throw new Error(`registry returned ${res.status} for ${packageName}`);
+			return await res.json();
+		}
+		if (ecosystem === "PyPI") {
+			const url = `${r.pypiRegistry.replace(/\/+$/, "")}/${encodeURIComponent(normalizePypiName(packageName))}/json`;
+			await resolveAndPin(new URL(url).hostname, void 0, { allowPrivate: r.allowPrivate });
+			const res = await fetch(url, { headers: { accept: "application/json" } });
+			if (!res.ok) throw new Error(`PyPI returned ${res.status} for ${packageName}`);
+			return pypiJsonToPackument(await res.json());
+		}
+		const url = `${r.rubygemsRegistry.replace(/\/+$/, "")}/versions/${encodeURIComponent(packageName)}.json`;
+		await resolveAndPin(new URL(url).hostname, void 0, { allowPrivate: r.allowPrivate });
+		const res = await fetch(url, { headers: { accept: "application/json" } });
+		if (!res.ok) throw new Error(`RubyGems returned ${res.status} for ${packageName}`);
+		return rubygemsToPackument(packageName, await res.json());
+	};
+}
+/** SSRF-pinned JSON GET (pre-flight resolve-and-refuse, then fetch). */
+async function pinnedFetchJson(url, allowPrivate) {
+	await resolveAndPin(new URL(url).hostname, void 0, { allowPrivate });
+	const res = await fetch(url, { headers: { accept: "application/json" } });
+	if (!res.ok) throw new Error(`metadata fetch returned ${res.status} for ${url}`);
+	return res.json();
+}
+/**
+* Build the SSRF-pinned changelog fetcher (npm/PyPI/RubyGems). Resolves the source GitHub repo
+* from registry metadata — npm packument `repository`, PyPI `info.project_urls`, or the RubyGems
+* `/api/v1/gems/<name>.json` `source_code_uri`/`homepage_uri` — then fetches the CHANGELOG from
+* `raw.githubusercontent.com/<owner>/<repo>/HEAD/<file>`, pinning every request.
+*/
+function makeChangelogFetcher(r) {
+	const fetchPackument = makeFetcher(r);
+	const repoUrlFor = async (packageName, ecosystem) => {
+		if (ecosystem === "npm") return npmRepoUrl(await fetchPackument(packageName, "npm"));
+		if (ecosystem === "PyPI") return pypiRepoUrl(await pinnedFetchJson(`${r.pypiRegistry.replace(/\/+$/, "")}/${encodeURIComponent(normalizePypiName(packageName))}/json`, r.allowPrivate));
+		if (ecosystem === "RubyGems") return gemRepoUrl(await pinnedFetchJson(`${r.rubygemsRegistry.replace(/\/+$/, "")}/gems/${encodeURIComponent(packageName)}.json`, r.allowPrivate));
+		throw new Error(`changelog fetch supports npm, PyPI, and RubyGems (got "${ecosystem}")`);
+	};
+	return async (packageName, ecosystem) => {
+		const gh = githubOwnerRepo(await repoUrlFor(packageName, ecosystem));
+		if (!gh) throw new Error(`could not resolve a GitHub repository for "${packageName}"`);
+		for (const file of CHANGELOG_FILENAMES) {
+			const url = `https://raw.githubusercontent.com/${gh.owner}/${gh.repo}/HEAD/${file}`;
+			await resolveAndPin(new URL(url).hostname, void 0, { allowPrivate: r.allowPrivate });
+			const res = await fetch(url);
+			if (res.ok) return {
+				text: await res.text(),
+				source: url
+			};
+		}
+		throw new Error(`no CHANGELOG found in github.com/${gh.owner}/${gh.repo}`);
+	};
+}
+/** Load advisories + snapshotDate for an ecosystem, or empty when no snapshot dir is set. */
+function loadAdvisories(osvDir, ecosystem) {
+	if (osvDir === void 0) return {
+		advisories: [],
+		loaded: false
+	};
+	const snapshot = loadOsvSnapshot(osvDir, ecosystem);
+	return {
+		advisories: snapshot.advisories,
+		snapshotDate: snapshot.snapshotDate,
+		loaded: true
+	};
+}
+/** Detect → fetch → audit one package (the thin orchestration the pure core needs). */
+async function auditOne(project, packageName, ecosystem, fetchPackument, advisories, snapshotDate, versionOverride) {
+	const version = versionOverride ?? detectInstalledVersion(project, packageName, { ecosystem: DETECT_ECOSYSTEM[ecosystem] }).version;
+	if (version === null || version === void 0) throw new Error(`could not detect an installed version of "${packageName}" in ${project}`);
+	const packument = await fetchPackument(packageName, ecosystem);
+	return auditDependency({
+		packageName: matchName(packageName, ecosystem),
+		ecosystem,
+		installedVersion: version,
+		packument,
+		advisories,
+		snapshotDate,
+		comparator: comparatorFor(ecosystem)
+	});
+}
+/**
+* Detect → fetch → audit each declared (or `names`-scoped) dependency of a project,
+* isolating per-package failures — the reusable project audit the `verify run --deps`
+* path reuses (mirrors the MCP `auditProjectDependencies`). Returns the
+* `{audits, osvSnapshotLoaded}` shape the verify orchestrator's deps adapter consumes.
+*/
+async function auditProjectScoped(input) {
+	const { advisories, snapshotDate, loaded } = loadAdvisories(input.osvDir, input.ecosystem);
+	const names = input.names ?? dependencyNames(input.project, input.ecosystem, true);
+	const audits = [];
+	const errors = [];
+	for (const name of names) try {
+		audits.push(await auditOne(input.project, name, input.ecosystem, input.fetchPackument, advisories, snapshotDate));
+	} catch (e) {
+		errors.push({
+			package: name,
+			error: e.message
+		});
+	}
+	return {
+		audits,
+		osvSnapshotLoaded: loaded,
+		errors
+	};
+}
+/** A security or deprecation finding — the CI-actionable signal (outdated alone is not). */
+function isActionable(audit) {
+	return audit.worstSeverity !== "none" || audit.deprecated.isDeprecated;
+}
+function printAudit(io, audit, loaded, snapshotDate) {
+	io.out(`${audit.package}  ${audit.installedVersion}  (${audit.ecosystem})\n`);
+	io.out(audit.deprecated.isDeprecated ? `deprecated [${audit.deprecated.scope}]: ${audit.deprecated.message}\n` : "deprecated: no\n");
+	if (audit.vulnerabilities.length > 0) {
+		io.out(`vulnerabilities (${audit.vulnerabilities.length}):\n`);
+		for (const v of audit.vulnerabilities) {
+			const fixed = v.fixedIn.length ? `  fixed in: ${v.fixedIn.join(", ")}` : "";
+			io.out(`  ${v.id} [${v.severity}]  ${v.summary ?? ""}${fixed}\n`);
+		}
+	} else io.out("vulnerabilities: none\n");
+	const f = audit.freshness;
+	io.out(`freshness: installed ${f.installed}, latest ${f.latest ?? "?"}, same-major ${f.latestSameMajor ?? "?"}, outdated ${f.isOutdated ? "yes" : "no"}\n`);
+	if (audit.recommendedTarget) io.out(`recommended target: ${audit.recommendedTarget}\n`);
+	if (audit.minimumSafeUpgrade) io.out(`minimum safe upgrade: ${audit.minimumSafeUpgrade}\n`);
+	io.out(loaded ? `osv snapshot: loaded${snapshotDate ? ` (${snapshotDate})` : ""}\n` : "osv snapshot: NOT loaded — treat \"no known vulnerabilities\" as unknown, not clean\n");
+}
+async function cmdAudit(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...REGISTRY_OPTIONS,
+			version: { type: "string" }
+		}
+	});
+	const [project, packageName] = positionals;
+	if (!project || !packageName) {
+		io.err("deps audit needs <project> <package>\n");
+		return 1;
+	}
+	const ecosystem = ecosystemFrom(values, io);
+	if (!ecosystem) return 1;
+	const r = registriesFrom(values);
+	const fetchPackument = deps.fetchPackument ?? makeFetcher(r);
+	const { advisories, snapshotDate, loaded } = loadAdvisories(values["osv-db"], ecosystem);
+	try {
+		const audit = await auditOne(project, packageName, ecosystem, fetchPackument, advisories, snapshotDate, values.version);
+		if (values.json) io.out(`${JSON.stringify({
+			...audit,
+			osvSnapshotLoaded: loaded
+		}, null, 2)}\n`);
+		else printAudit(io, audit, loaded, snapshotDate);
+		return isActionable(audit) ? 1 : 0;
+	} catch (e) {
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+async function cmdAuditProject(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...REGISTRY_OPTIONS,
+			"skip-dev": { type: "boolean" }
+		}
+	});
+	const project = positionals[0];
+	if (!project) {
+		io.err("deps audit-project needs <project>\n");
+		return 1;
+	}
+	const ecosystem = ecosystemFrom(values, io);
+	if (!ecosystem) return 1;
+	const r = registriesFrom(values);
+	const fetchPackument = deps.fetchPackument ?? makeFetcher(r);
+	const { advisories, snapshotDate, loaded } = loadAdvisories(values["osv-db"], ecosystem);
+	const names = dependencyNames(project, ecosystem, !values["skip-dev"]);
+	const dependencies = [];
+	const errors = [];
+	for (const name of names) try {
+		const audit = await auditOne(project, name, ecosystem, fetchPackument, advisories, snapshotDate);
+		dependencies.push({
+			package: name,
+			installedVersion: audit.installedVersion,
+			worstSeverity: audit.worstSeverity,
+			deprecated: audit.deprecated.isDeprecated,
+			isOutdated: audit.freshness.isOutdated,
+			recommendedTarget: audit.recommendedTarget,
+			minimumSafeUpgrade: audit.minimumSafeUpgrade,
+			vulnerabilityCount: audit.vulnerabilities.length
+		});
+	} catch (err) {
+		errors.push({
+			package: name,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	const bySeverity = {};
+	for (const d of dependencies) if (d.worstSeverity !== "none") bySeverity[d.worstSeverity] = (bySeverity[d.worstSeverity] ?? 0) + 1;
+	const summary = {
+		total: dependencies.length,
+		withFindings: dependencies.filter((d) => d.worstSeverity !== "none" || d.deprecated).length,
+		deprecated: dependencies.filter((d) => d.deprecated).length,
+		outdated: dependencies.filter((d) => d.isOutdated).length,
+		bySeverity,
+		osvSnapshotLoaded: loaded,
+		snapshotDate
+	};
+	if (values.json) {
+		io.out(`${JSON.stringify({
+			project,
+			ecosystem,
+			summary,
+			dependencies,
+			errors
+		}, null, 2)}\n`);
+		return summary.withFindings > 0 ? 1 : 0;
+	}
+	io.out(`${project}  (${ecosystem})  ${summary.total} deps; findings ${summary.withFindings}, deprecated ${summary.deprecated}, outdated ${summary.outdated}\n`);
+	io.out(loaded ? `osv snapshot: loaded${snapshotDate ? ` (${snapshotDate})` : ""}\n` : "osv snapshot: NOT loaded — \"no known vulnerabilities\" is unknown, not clean\n");
+	for (const d of dependencies) {
+		if (d.worstSeverity === "none" && !d.deprecated && !d.isOutdated) continue;
+		const tags = [
+			d.worstSeverity !== "none" ? `[${d.worstSeverity}]` : "",
+			d.deprecated ? "deprecated" : "",
+			d.isOutdated ? "outdated" : ""
+		].filter(Boolean).join(" ");
+		const target = d.minimumSafeUpgrade ?? d.recommendedTarget;
+		io.out(`  ${d.package} ${d.installedVersion}  ${tags}${target ? ` → ${target}` : ""}\n`);
+	}
+	for (const e of errors) io.out(`  ! ${e.package}: ${e.error}\n`);
+	return summary.withFindings > 0 ? 1 : 0;
+}
+async function cmdChangelog(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...REGISTRY_OPTIONS,
+			project: { type: "string" },
+			from: { type: "string" },
+			to: { type: "string" }
+		}
+	});
+	const packageName = positionals[0];
+	if (!packageName) {
+		io.err("deps changelog needs <package> (with --from or --project to detect the installed version)\n");
+		return 1;
+	}
+	const ecosystem = ecosystemFrom(values, io);
+	if (!ecosystem) return 1;
+	const r = registriesFrom(values);
+	const fetchChangelog = deps.fetchChangelog ?? makeChangelogFetcher(r);
+	try {
+		let from = values.from;
+		if (from === void 0) {
+			if (!values.project) {
+				io.err("provide --from <version> or --project <dir> to determine the installed version\n");
+				return 1;
+			}
+			const detected = detectInstalledVersion(values.project, packageName, { ecosystem: DETECT_ECOSYSTEM[ecosystem] });
+			if (!detected.version) {
+				io.err(`could not detect an installed version of "${packageName}" in ${values.project}\n`);
+				return 1;
+			}
+			from = detected.version;
+		}
+		const { text: markdown, source } = await fetchChangelog(packageName, ecosystem);
+		const slice = sliceChangelog(markdown, {
+			from,
+			to: values.to,
+			comparator: comparatorFor(ecosystem)
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify({
+				package: packageName,
+				from: slice.from,
+				to: slice.to ?? null,
+				versionsCovered: slice.entries.map((e) => e.version),
+				source,
+				body: slice.entries.map((e) => e.body).join("\n\n")
+			}, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`${packageName} ${slice.from} → ${slice.to ?? "latest"}  (${slice.entries.length} section(s))  [${source}]\n`);
+		if (slice.entries.length === 0) {
+			io.out("(no changelog sections in the requested range)\n");
+			return 0;
+		}
+		for (const e of slice.entries) io.out(`\n## ${e.version}\n${e.body}\n`);
+		return 0;
+	} catch (e) {
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+//#endregion
+//#region src/flake.ts
+/**
+* `sackville flake` — the human surface over `@sackville-mcp/flake`.
+*
+* Reads (`status`/`candidates`) + `ingest`/`release` are always available against the
+* operator's private run-history DB (`--db`). `run` (spawns vitest) and `quarantine`
+* (the only write) each sit behind their own paired deny-by-default gate. The human IS
+* the operator, so those gates are straight-through flags (`--allow-run` /
+* `--allow-quarantine` + `--max-expiry-ms`), the typed root is auto-allowed, and the
+* vitest runner is injectable so the suite never spawns a real vitest (ADR 0010).
+*/
+async function runFlake(args, io, deps = {}) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "status": return withStore(rest, io, cmdStatus);
+		case "candidates": return withStore(rest, io, cmdCandidates);
+		case "ingest": return withStore(rest, io, cmdIngest);
+		case "release": return withStore(rest, io, cmdRelease);
+		case "run": return withStore(rest, io, (store, a, o) => cmdRun$1(store, a, o, deps));
+		case "quarantine": return withStore(rest, io, cmdQuarantine);
+		default:
+			io.err(`unknown flake subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+/** Open the operator's history DB (from `--db`/`SACKVILLE_FLAKE_DB`), run the command, close. */
+async function withStore(args, io, fn) {
+	const dbPath = readDbFlag(args) ?? io.env?.SACKVILLE_FLAKE_DB;
+	if (!dbPath) {
+		io.err("no run-history DB given: pass --db <file> or set SACKVILLE_FLAKE_DB\n");
+		return 1;
+	}
+	const store = HistoryStore.open(dbPath);
+	try {
+		return await fn(store, args, io);
+	} finally {
+		store.close();
+	}
+}
+/** Pull just `--db <path>` out of an argv without consuming the rest. */
+function readDbFlag(args) {
+	const i = args.indexOf("--db");
+	return i >= 0 ? args[i + 1] : void 0;
+}
+function num$2(raw) {
+	if (raw === void 0) return void 0;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+function printVerdict$1(io, v) {
+	io.out(`  [${v.state}] ${v.id}  runs ${v.runs}  fail ${v.failures}/${v.runs}  score ${v.flakeScore.toFixed(3)}\n`);
+}
+function cmdStatus(store, args, io) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			db: { type: "string" },
+			"min-runs": { type: "string" },
+			"limit-per-test": { type: "string" },
+			since: { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const verdicts = store.classify({
+		minRuns: num$2(values["min-runs"]),
+		limitPerTest: num$2(values["limit-per-test"]),
+		since: values.since
+	});
+	const quarantined = new Quarantine(store, {
+		allowQuarantine: false,
+		maxExpiryMs: 0
+	}).active();
+	if (values.json) {
+		const summary = {};
+		for (const v of verdicts) summary[v.state] = (summary[v.state] ?? 0) + 1;
+		io.out(`${JSON.stringify({
+			summary,
+			verdicts,
+			quarantined
+		}, null, 2)}\n`);
+		return 0;
+	}
+	const counts = {
+		flaky: 0,
+		reliable: 0,
+		broken: 0,
+		"insufficient-data": 0
+	};
+	for (const v of verdicts) counts[v.state]++;
+	io.out(`flaky ${counts.flaky}  reliable ${counts.reliable}  broken ${counts.broken}  insufficient-data ${counts["insufficient-data"]}\n`);
+	if (verdicts.length > 0) {
+		io.out("verdicts:\n");
+		for (const v of verdicts) printVerdict$1(io, v);
+	}
+	if (quarantined.length > 0) {
+		io.out(`quarantined (${quarantined.length}):\n`);
+		for (const q of quarantined) io.out(`  ${q.testId}  until ${q.expiresAt}  (${q.reason})\n`);
+	}
+	return 0;
+}
+function cmdCandidates(store, args, io) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			db: { type: "string" },
+			"min-flake-score": { type: "string" },
+			"min-runs": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const candidates = quarantineCandidates(store.classify({ minRuns: num$2(values["min-runs"]) }), { minFlakeScore: num$2(values["min-flake-score"]) });
+	if (values.json) {
+		io.out(`${JSON.stringify({ candidates }, null, 2)}\n`);
+		return 0;
+	}
+	if (candidates.length === 0) {
+		io.out("no quarantine candidates\n");
+		return 0;
+	}
+	io.out(`candidates (${candidates.length}):\n`);
+	for (const v of candidates) printVerdict$1(io, v);
+	return 0;
+}
+function cmdIngest(store, args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			db: { type: "string" },
+			format: { type: "string" },
+			at: { type: "string" },
+			"project-root": { type: "string" },
+			"run-group": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const reportFile = positionals[0];
+	if (!reportFile) {
+		io.err("flake ingest needs a <report-file>\n");
+		return 1;
+	}
+	const format = values.format ?? "vitest";
+	if (format !== "vitest" && format !== "pytest") {
+		io.err(`unknown report format: ${format} (expected vitest|pytest)\n`);
+		return 1;
+	}
+	const report = JSON.parse(readFileSync(reportFile, "utf8"));
+	const opts = {
+		at: values.at ?? (/* @__PURE__ */ new Date()).toISOString(),
+		projectRoot: values["project-root"],
+		runGroup: values["run-group"]
+	};
+	const recorded = format === "pytest" ? store.ingestPytestReport(report, opts) : store.ingestReport(report, opts);
+	if (values.json) {
+		io.out(`${JSON.stringify({
+			format,
+			recorded
+		}, null, 2)}\n`);
+		return 0;
+	}
+	io.out(`recorded ${recorded} run(s) from the ${format} report\n`);
+	return 0;
+}
+function cmdRelease(store, args, io) {
+	const { positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { db: { type: "string" } }
+	});
+	const testId = positionals[0];
+	if (!testId) {
+		io.err("flake release needs a <testId>\n");
+		return 1;
+	}
+	const released = new Quarantine(store, {
+		allowQuarantine: false,
+		maxExpiryMs: 0
+	}).release(testId);
+	io.out(released ? `released ${testId}\n` : `${testId} was not quarantined\n`);
+	return 0;
+}
+async function cmdRun$1(store, args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			db: { type: "string" },
+			framework: { type: "string" },
+			repeat: { type: "string" },
+			file: {
+				type: "string",
+				multiple: true
+			},
+			"run-group": { type: "string" },
+			"allow-run": { type: "boolean" },
+			"timeout-ms": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const projectRoot = positionals[0];
+	if (!projectRoot) {
+		io.err("flake run needs a <project-root>\n");
+		return 1;
+	}
+	const framework = values.framework ?? "vitest";
+	if (framework !== "vitest" && framework !== "pytest") {
+		io.err(`unknown framework: ${framework} (expected vitest|pytest)\n`);
+		return 1;
+	}
+	try {
+		const result = await (framework === "pytest" ? runAndRecordPytest : runAndRecord)(store, {
+			projectRoot,
+			allowedRoots: [resolve(projectRoot)],
+			allowRun: values["allow-run"] ?? false,
+			timeoutMs: num$2(values["timeout-ms"])
+		}, {
+			repeat: num$2(values.repeat) ?? 1,
+			files: values.file,
+			runGroup: values["run-group"]
+		}, { runner: deps.runner });
+		if (values.json) {
+			io.out(`${JSON.stringify(result, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`ran ${result.iterations} iteration(s); recorded ${result.recorded} run(s)\n`);
+		for (const v of result.verdicts) printVerdict$1(io, v);
+		return 0;
+	} catch (e) {
+		if (e instanceof FlakeGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+function cmdQuarantine(store, args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			db: { type: "string" },
+			reason: { type: "string" },
+			"expires-at": { type: "string" },
+			"flake-score": { type: "string" },
+			"allow-quarantine": { type: "boolean" },
+			"max-expiry-ms": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const testId = positionals[0];
+	if (!testId || !values.reason || !values["expires-at"]) {
+		io.err("flake quarantine needs <testId> --reason <r> --expires-at <ISO>\n");
+		return 1;
+	}
+	const policy = {
+		allowQuarantine: values["allow-quarantine"] ?? false,
+		maxExpiryMs: num$2(values["max-expiry-ms"]) ?? 0
+	};
+	try {
+		const entry = new Quarantine(store, policy).quarantine({
+			testId,
+			reason: values.reason,
+			expiresAt: values["expires-at"],
+			flakeScore: num$2(values["flake-score"])
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify({ entry }, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`quarantined ${entry.testId} until ${entry.expiresAt}  (${entry.reason})\n`);
+		return 0;
+	} catch (e) {
+		if (e instanceof QuarantineGateError) {
+			io.err(`refused: ${e.message} (pass --allow-quarantine and --max-expiry-ms)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+//#endregion
+//#region src/lsp.ts
+/**
+* `sackville lsp` — the human surface over `@sackville-mcp/lsp`. Single-shot semantic code
+* navigation: each invocation binds the operator's server registry, drives one query against
+* a live Language Server subprocess, then shuts it down.
+*
+* The human IS the operator, so the gates are straight-through flags: `--allow-run` (required
+* for any navigation — it spawns a code-executing indexing daemon, ADR 0011's
+* load-bearing gate) and `--allow-write` (lets `rename` write to disk; default = dry-run
+* preview). The typed `--project` root is the allowlist (explicit operator intent). Per ADR
+* 0011 the engine is **injectable** so the suite never spawns a real server — the production
+* path builds the real `LanguageServerManager`/`LspQueryEngine`/`LspRenameEngine` from flags
+* (mirroring `sackville-lsp-mcp`), and the gate throws *before* any spawn when `--allow-run` is
+* absent.
+*
+* Exit codes: 0 = the query ran (`ok`/`no_result`, or a rename preview/apply); 1 = denied,
+* refused, or error; 2 = `not_ready` (the server was still indexing — retry shortly).
+*/
+async function runLsp(args, io, deps = {}) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "languages": return cmdLanguages(rest, io, deps);
+		case "definition": return cmdQuery("definition", rest, io, deps);
+		case "type-definition": return cmdQuery("typeDefinition", rest, io, deps);
+		case "references": return cmdQuery("references", rest, io, deps);
+		case "hover": return cmdQuery("hover", rest, io, deps);
+		case "symbols": return cmdQuery("documentSymbols", rest, io, deps);
+		case "diagnostics": return cmdQuery("diagnostics", rest, io, deps);
+		case "workspace-symbols": return cmdWorkspaceSymbols(rest, io, deps);
+		case "call-hierarchy": return cmdQuery("callHierarchy", rest, io, deps);
+		case "rename": return cmdRename(rest, io, deps);
+		default:
+			io.err(`unknown lsp subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+const GATE_OPTIONS = {
+	project: { type: "string" },
+	"workspace-root": {
+		type: "string",
+		multiple: true
+	},
+	servers: { type: "string" },
+	"allow-run": { type: "boolean" },
+	"allow-write": { type: "boolean" },
+	"allow-partial-rename": { type: "boolean" },
+	"allow-destructive-resource-ops": { type: "boolean" },
+	"timeout-ms": { type: "string" },
+	json: { type: "boolean" }
+};
+function num$1(raw) {
+	if (raw === void 0) return void 0;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : void 0;
+}
+/**
+* Build the query/rename engines — injected stubs in tests, else the real manager + engines
+* from the operator registry (`--servers`/`SACKVILLE_LSP_SERVERS`), gated by `--allow-run` /
+* `--allow-write` and confined to the `--project` root. Returns null on a config error (the
+* caller has already had the message written).
+*/
+function makeEngines(values, io, deps) {
+	const projectRoot = resolve(values.project ?? process.cwd());
+	const workspaceRoots = (values["workspace-root"] ?? []).map((r) => resolve(r));
+	if (values["allow-destructive-resource-ops"] && !values["allow-write"]) {
+		io.err("--allow-destructive-resource-ops requires --allow-write\n");
+		return null;
+	}
+	if (deps.query || deps.rename || deps.describeServers) return {
+		query: deps.query ?? (async () => fail("query")),
+		rename: deps.rename ?? (async () => fail("rename")),
+		describeServers: deps.describeServers ?? (() => []),
+		shutdown: async () => {},
+		projectRoot,
+		workspaceRoots
+	};
+	const raw = values.servers ?? io.env?.SACKVILLE_LSP_SERVERS;
+	if (!raw || raw.trim() === "") {
+		io.err("no servers bound: pass --servers <json> or set SACKVILLE_LSP_SERVERS\n");
+		return null;
+	}
+	let registry;
+	try {
+		registry = parseServerRegistry(raw);
+	} catch (e) {
+		io.err(`invalid --servers registry: ${e.message}\n`);
+		return null;
+	}
+	const allowedRoots = [projectRoot, ...workspaceRoots];
+	const manager = new LanguageServerManager({
+		registry,
+		allowedRoots,
+		timeoutMs: num$1(values["timeout-ms"]) ?? 15e3
+	});
+	const query = new LspQueryEngine({
+		manager,
+		allowRun: values["allow-run"] ?? false,
+		allowedRoots
+	});
+	const rename = new LspRenameEngine({
+		manager,
+		allowRun: values["allow-run"] ?? false,
+		allowedRoots,
+		allowWrite: values["allow-write"] ?? false,
+		allowPartialRename: values["allow-partial-rename"] ?? false,
+		allowDestructiveResourceOps: values["allow-destructive-resource-ops"] ?? false,
+		listFiles: defaultListFiles
+	});
+	return {
+		query: (input) => query.query(input),
+		rename: (input) => rename.rename(input),
+		describeServers: () => manager.describe(),
+		shutdown: () => manager.shutdown(),
+		projectRoot,
+		workspaceRoots
+	};
+}
+function fail(what) {
+	throw new Error(`no ${what} engine available`);
+}
+function cmdLanguages(args, io, deps) {
+	const { values } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: GATE_OPTIONS
+	});
+	const raw = values.servers ?? io.env?.SACKVILLE_LSP_SERVERS;
+	let languages = [];
+	if (raw && raw.trim() !== "") try {
+		languages = Object.keys(parseServerRegistry(raw)).sort();
+	} catch (e) {
+		io.err(`invalid --servers registry: ${e.message}\n`);
+		return 1;
+	}
+	const servers = (deps.describeServers ?? (() => []))();
+	if (values.json) {
+		io.out(`${JSON.stringify({
+			languages,
+			servers
+		}, null, 2)}\n`);
+		return 0;
+	}
+	io.out(languages.length ? `bound languages: ${languages.join(", ")}\n` : "no languages bound\n");
+	for (const s of servers) {
+		const v = s.serverInfo ? `${s.serverInfo.name}${s.serverInfo.version ? ` ${s.serverInfo.version}` : ""}` : "(no serverInfo)";
+		io.out(`  ${s.language} @ ${s.projectRoot}  ${v}\n`);
+	}
+	return 0;
+}
+/** Tri-state status → exit code (ok/no_result ran; not_ready is transient). */
+function statusExit(status) {
+	return status === "not_ready" ? 2 : 0;
+}
+function rangeStr(r) {
+	return `${r.start.line}:${r.start.column}-${r.end.line}:${r.end.column}`;
+}
+function printHeader(io, r) {
+	const info = r.serverInfo ? `${r.serverInfo.name}${r.serverInfo.version ? ` ${r.serverInfo.version}` : ""}` : "unknown server";
+	io.out(`status: ${r.status}  [${r.kind}, ${r.encoding}, ${info}]\n`);
+	if (r.versionWarning) io.err(`warning: ${r.versionWarning}\n`);
+}
+function printSymbols(io, symbols, depth) {
+	for (const s of symbols) {
+		const detail = s.detail ? `  ${s.detail}` : "";
+		io.out(`${"  ".repeat(depth + 1)}${s.name}  [${s.kindName}]  ${rangeStr(s.range)}${detail}\n`);
+		if (s.children && s.children.length > 0) printSymbols(io, s.children, depth + 1);
+	}
+}
+async function cmdQuery(kind, args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			...GATE_OPTIONS,
+			direction: { type: "string" }
+		}
+	});
+	const positionLess = kind === "documentSymbols" || kind === "diagnostics";
+	const [language, file, lineRaw, colRaw] = positionals;
+	if (!language || !file || !positionLess && (lineRaw === void 0 || colRaw === void 0)) {
+		io.err(positionLess ? `lsp ${kindCommand(kind)} needs <language> <file>\n` : `lsp ${kindCommand(kind)} needs <language> <file> <line> <column>\n`);
+		return 1;
+	}
+	const engines = makeEngines(values, io, deps);
+	if (!engines) return 1;
+	try {
+		const input = {
+			language,
+			projectRoot: engines.projectRoot,
+			file,
+			kind,
+			...engines.workspaceRoots.length ? { workspaceRoots: engines.workspaceRoots } : {},
+			...positionLess ? {} : {
+				line: Number(lineRaw),
+				column: Number(colRaw)
+			},
+			...kind === "callHierarchy" ? { direction: values.direction ?? "incoming" } : {}
+		};
+		const result = await engines.query(input);
+		if (values.json) {
+			io.out(`${JSON.stringify(result, null, 2)}\n`);
+			return statusExit(result.status);
+		}
+		printHeader(io, result);
+		if (result.status === "not_ready") {
+			io.out("the server is still indexing — retry shortly\n");
+			return 2;
+		}
+		if (kind === "hover") io.out(result.hover ? `${result.hover.value}\n` : "no hover info\n");
+		else if (kind === "documentSymbols") {
+			const symbols = result.symbols ?? [];
+			io.out(`${symbols.length} symbol(s):\n`);
+			printSymbols(io, symbols, 0);
+		} else if (kind === "diagnostics") {
+			const diags = result.diagnostics ?? [];
+			io.out(`${diags.length} diagnostic(s):\n`);
+			for (const d of diags) printDiagnostic(io, d);
+		} else if (kind === "callHierarchy") {
+			const groups = result.callHierarchy ?? [];
+			for (const g of groups) {
+				io.out(`${g.source.name}  [${g.source.kindName}]  (${g.direction})\n`);
+				for (const c of g.calls) io.out(`  ${c.item.name}  ${c.item.uri}  ${c.fromRanges.map(rangeStr).join(", ")}\n`);
+			}
+		} else {
+			const locations = result.locations ?? [];
+			io.out(`${locations.length} location(s):\n`);
+			for (const loc of locations) io.out(`  ${loc.uri}  ${rangeStr(loc.range)}${loc.mapped ? "" : "  (unmapped)"}\n`);
+		}
+		return statusExit(result.status);
+	} catch (e) {
+		if (e instanceof LspGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	} finally {
+		await engines.shutdown();
+	}
+}
+/**
+* `workspace-symbols <language> <query> [anchorFile]` — position-less project-wide symbol search.
+* The optional `[anchorFile]` is opened first to establish the project; pass it for servers (like
+* `typescript-language-server`) that only build a project once a file is open.
+*/
+async function cmdWorkspaceSymbols(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: GATE_OPTIONS
+	});
+	const [language, query, anchorFile] = positionals;
+	if (!language || query === void 0) {
+		io.err("lsp workspace-symbols needs <language> <query> [anchorFile]\n");
+		return 1;
+	}
+	const engines = makeEngines(values, io, deps);
+	if (!engines) return 1;
+	try {
+		const result = await engines.query({
+			language,
+			projectRoot: engines.projectRoot,
+			kind: "workspaceSymbol",
+			query,
+			...engines.workspaceRoots.length ? { workspaceRoots: engines.workspaceRoots } : {},
+			...anchorFile !== void 0 ? { file: anchorFile } : {}
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify(result, null, 2)}\n`);
+			return statusExit(result.status);
+		}
+		printHeader(io, result);
+		if (result.status === "not_ready") {
+			io.out("the server is still indexing — retry shortly\n");
+			return 2;
+		}
+		const symbols = result.workspaceSymbols ?? [];
+		io.out(`${symbols.length} symbol(s):\n`);
+		for (const s of symbols) printWorkspaceSymbol(io, s);
+		return statusExit(result.status);
+	} catch (e) {
+		if (e instanceof LspGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	} finally {
+		await engines.shutdown();
+	}
+}
+function printDiagnostic(io, d) {
+	const sev = d.severityName ?? (d.severity !== void 0 ? `severity ${d.severity}` : "Diagnostic");
+	const where = `${d.range.start.line}:${d.range.start.column}`;
+	const code = d.code !== void 0 ? ` [${d.source ? `${d.source} ` : ""}${d.code}]` : "";
+	io.out(`  ${where}  ${sev}${code}  ${d.message}\n`);
+	for (const r of d.related ?? []) io.out(`      ↳ ${r.uri} ${r.range.start.line}:${r.range.start.column}  ${r.message}\n`);
+}
+function printWorkspaceSymbol(io, s) {
+	const container = s.container ? `  (in ${s.container})` : "";
+	const loc = s.range ? `  ${rangeStr(s.range)}${s.mapped ? "" : "  (unmapped)"}` : "";
+	io.out(`  ${s.name}  [${s.kindName}]  ${s.uri}${loc}${container}\n`);
+}
+/** Map a query kind back to its CLI subcommand name (for error messages). */
+function kindCommand(kind) {
+	if (kind === "typeDefinition") return "type-definition";
+	if (kind === "documentSymbols") return "symbols";
+	if (kind === "callHierarchy") return "call-hierarchy";
+	return kind;
+}
+async function cmdRename(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: GATE_OPTIONS
+	});
+	const [language, file, lineRaw, colRaw, newName] = positionals;
+	if (!language || !file || lineRaw === void 0 || colRaw === void 0 || !newName) {
+		io.err("lsp rename needs <language> <file> <line> <column> <newName>\n");
+		return 1;
+	}
+	const engines = makeEngines(values, io, deps);
+	if (!engines) return 1;
+	try {
+		const result = await engines.rename({
+			language,
+			projectRoot: engines.projectRoot,
+			file,
+			line: Number(lineRaw),
+			column: Number(colRaw),
+			newName,
+			...engines.workspaceRoots.length ? { workspaceRoots: engines.workspaceRoots } : {}
+		});
+		if (values.json) io.out(`${JSON.stringify(result, null, 2)}\n`);
+		else printRename(io, result);
+		if (result.status === "not_ready") return 2;
+		if (result.refused) return 1;
+		return 0;
+	} catch (e) {
+		if (e instanceof LspGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	} finally {
+		await engines.shutdown();
+	}
+}
+function printRename(io, r) {
+	const info = r.serverInfo ? `${r.serverInfo.name}${r.serverInfo.version ? ` ${r.serverInfo.version}` : ""}` : "unknown server";
+	const mode = r.applied ? "APPLIED to disk" : "dry-run (not applied)";
+	io.out(`status: ${r.status}  ${mode}  [${r.encoding}, ${info}]\n`);
+	if (r.versionWarning) io.err(`warning: ${r.versionWarning}\n`);
+	if (r.completeness === "suspect") {
+		const miss = r.suspectedMissedFiles ?? [];
+		io.err(`warning: rename may be INCOMPLETE — the symbol also appears in ${miss.length} same-language file(s) NOT in this edit: ${miss.join(", ")}\n`);
+		io.err("  the language server may scope rename to open files; re-run with --allow-partial-rename to apply anyway\n");
+	} else if (r.completeness === "unknown") io.err("warning: rename completeness unverified (file scan was truncated)\n");
+	if (r.refused) {
+		io.err(`refused: ${r.refused}\n`);
+		return;
+	}
+	io.out(`rename → ${r.newName}: ${r.totalEditCount} edit(s) across ${r.fileCount} file(s)\n`);
+	for (const f of r.edits) {
+		io.out(`  ${f.file}  ${f.editCount} edit(s)${f.outOfRoot ? "  (out of project root)" : ""}\n`);
+		for (const h of f.hunks ?? []) io.out(`    ${rangeStr(h.range)}  ${h.oldText} → ${h.newText}\n`);
+	}
+	for (const op of r.resourceOps ?? []) io.out(`  ${op.kind} file: ${op.uris.join(" → ")}\n`);
+	if (r.overwritten?.length) io.err(`warning: DESTRUCTIVELY overwrote ${r.overwritten.length} existing file(s): ${r.overwritten.join(", ")}\n`);
+	if (r.partial) io.err(`warning: PARTIAL apply (no rollback — reconcile via VCS): ${r.partialError ?? ""}\n`);
+	for (const d of r.digests ?? []) io.out(`  digest ${d.file}: ${d.before.slice(0, 12)} → ${d.after.slice(0, 12) || "(deleted)"}\n`);
+}
+//#endregion
+//#region src/mutate.ts
+/**
+* `sackville mutate` — the human surface over `@sackville-mcp/mutate`.
+*
+* `summarize` is a pure report viewer (Stryker JSON or `mutmut results` text). `run` is the
+* gated, diff-scopable mutation run. The CLI's human IS the operator, so the run gate is a
+* straight-through `--allow-run` flag (mirroring `sackville api --unsafe`): the typed project
+* root is auto-allowed (explicit operator intent). The `runner` is injectable so the suite
+* never spawns a real Stryker (ADR 0010: no real spawn in the gate).
+*/
+async function runMutate(args, io, deps = {}) {
+	const [sub, ...rest] = args;
+	switch (sub) {
+		case "summarize": return cmdSummarize(rest, io);
+		case "run": return cmdRun(rest, io, deps);
+		default:
+			io.err(`unknown mutate subcommand: ${sub ?? "(none)"}\n`);
+			return 1;
+	}
+}
+/** Format a percent metric (`null` ⇒ not applicable, e.g. zero valid mutants). */
+function pct(value) {
+	return value === null ? "n/a" : `${value.toFixed(1)}%`;
+}
+function printSummary(io, summary) {
+	const { metrics, survivors } = summary;
+	const c = metrics.counts;
+	io.out(`mutation score: ${pct(metrics.mutationScore)}  (detected ${metrics.detected} / valid ${metrics.valid})\n`);
+	io.out(`covered-code score: ${pct(metrics.mutationScoreBasedOnCoveredCode)}\n`);
+	io.out(`killed ${c.killed}  survived ${c.survived}  timeout ${c.timeout}  no-coverage ${c.noCoverage}  compile-errors ${c.compileErrors}  runtime-errors ${c.runtimeErrors}  ignored ${c.ignored}  pending ${c.pending}\n`);
+	if (survivors.length === 0) {
+		io.out("survivors: (none)\n");
+		return;
+	}
+	io.out(`survivors (${survivors.length}):\n`);
+	for (const s of survivors) io.out(`  ${s.file}:${s.line}  ${s.mutatorName}  [${s.status}]\n`);
+}
+function cmdSummarize(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			format: { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const reportFile = positionals[0];
+	if (!reportFile) {
+		io.err("mutate summarize needs a <report-file>\n");
+		return 1;
+	}
+	const format = values.format ?? "stryker";
+	if (format !== "stryker" && format !== "mutmut") {
+		io.err(`unknown report format: ${format} (expected stryker|mutmut)\n`);
+		return 1;
+	}
+	const text = readFileSync(reportFile, "utf8");
+	const summary = summarizeMutation(format === "mutmut" ? parseMutmutResults(text) : JSON.parse(text));
+	if (values.json) {
+		io.out(`${JSON.stringify(summary, null, 2)}\n`);
+		return 0;
+	}
+	printSummary(io, summary);
+	return 0;
+}
+async function cmdRun(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			tool: { type: "string" },
+			file: {
+				type: "string",
+				multiple: true
+			},
+			incremental: { type: "boolean" },
+			"config-path": { type: "string" },
+			"allow-run": { type: "boolean" },
+			"timeout-ms": { type: "string" },
+			"report-path": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const projectRoot = positionals[0];
+	if (!projectRoot) {
+		io.err("mutate run needs a <project-root>\n");
+		return 1;
+	}
+	const tool = values.tool ?? "stryker";
+	if (tool !== "stryker" && tool !== "mutmut" && tool !== "cosmic-ray") {
+		io.err(`unknown tool: ${tool} (expected stryker|mutmut|cosmic-ray)\n`);
+		return 1;
+	}
+	const timeoutRaw = values["timeout-ms"];
+	const timeoutMs = timeoutRaw !== void 0 ? Number(timeoutRaw) : void 0;
+	try {
+		const config = {
+			projectRoot,
+			allowedRoots: [resolve(projectRoot)],
+			allowRun: values["allow-run"] ?? false,
+			timeoutMs: timeoutMs !== void 0 && Number.isFinite(timeoutMs) ? timeoutMs : void 0
+		};
+		const input = {
+			mutateFiles: values.file,
+			incremental: values.incremental ?? false,
+			configPath: values["config-path"]
+		};
+		const result = tool === "mutmut" ? await runMutmut(config, input, { runner: deps.runner }) : tool === "cosmic-ray" ? await runCosmicRay(config, input, { runner: deps.runner }) : await runMutation(config, input, {
+			runner: deps.runner,
+			reportPath: values["report-path"]
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify(result, null, 2)}\n`);
+			return result.exitCode === 0 ? 0 : 1;
+		}
+		io.out(`ran ${tool} (exit ${result.exitCode}); scoped: ${result.scopedFiles.join(", ") || "(project default)"}\n`);
+		printSummary(io, result.summary);
+		return result.exitCode === 0 ? 0 : 1;
+	} catch (e) {
+		if (e instanceof MutateGateError) {
+			io.err(`refused: ${e.message} (pass --allow-run)\n`);
+			return 1;
+		}
+		io.err(`${e.message}\n`);
+		return 1;
+	}
+}
+//#endregion
+//#region src/verify.ts
+const SEVERITIES = [
+	"critical",
+	"high",
+	"moderate",
+	"low",
+	"none"
+];
+const EMPTY_COVERAGE = {
+	files: [],
+	uncovered: [],
+	summary: {
+		covered: 0,
+		uncovered: 0,
+		nonExecutable: 0,
+		total: 0,
+		filesWithoutCoverage: 0
+	}
+};
+/**
+* `sackville verify` — the human surface over the cross-pillar verdict.
+*
+* - `verify [--contract f] [--coverage f] ...` (COMPOSE): fold per-pillar JSON results
+*   on disk into one verdict (ADR 0013 §1). The human supplies each pillar's output.
+* - `verify run <root> [--coverage] [--flake --flake-db f] [--mutate [--mutate-tool T --mutate-config f]] [--deps] [--allow-run] ...`
+*   (RUN-DRIVING, ADR 0013 Addendum 5c/5d): DRIVE the selected pillars and fold them. The
+*   human is the operator, so `--allow-run` is the straight-through gate for the SPAWN
+*   pillars (coverage/flake/mutate) and the typed root is auto-allowed; each pillar's own
+*   `assertAllowed` still denies without it (⇒ `skipReason:gate-not-set`, never run —
+*   "compose, never widen"). `--mutate-tool` picks the mutation engine (stryker default |
+*   cosmic-ray | mutmut; the Python tools diff-scope via a synthesized config from
+*   `--mutate-config`, ADR 0010 addendum 2). `--deps` is gated by NETWORK not spawn (a packument fetch),
+*   so it needs no `--allow-run`; a `--diff` scopes the audit to the changed packages
+*   (`changedDependencies`). `--flow <name>` (5e) DRIVES an operator-authored browser flow
+*   to capture a HAR and validate it against `--openapi`/`--graphql` — gated by the browser
+*   egress flags (`--flows-dir`/`--allow-host` + the mandatory SSRF proxy), not `--allow-run`.
+*   Runners are injectable so the suite never spawns (ADR 0010).
+*
+* Exit codes (both modes): 0 pass / 1 fail|warn / 2 inconclusive.
+*/
+async function runVerify(args, io, deps = {}) {
+	if (args[0] === "run") return cmdVerifyRun(args.slice(1), io, deps);
+	return runVerifyCompose(args, io);
+}
+function printVerdict(io, verdict, json) {
+	if (json) {
+		io.out(`${JSON.stringify(verdict, null, 2)}\n`);
+		return;
+	}
+	io.out(`verdict: ${verdict.status.toUpperCase()} (worst severity ${verdict.worstSeverity})\n`);
+	for (const p of verdict.pillars) {
+		const sev = p.severity !== "none" ? ` [${p.severity}]` : "";
+		const why = p.skipReason ? ` (skipped: ${p.skipReason})` : p.errorReason ? " (errored)" : "";
+		io.out(`  ${p.pillar}: ${p.status}${sev}${why} — ${p.headline}\n`);
+	}
+}
+function exitFor(verdict) {
+	if (verdict.status === "pass") return 0;
+	if (verdict.status === "inconclusive") return 2;
+	return 1;
+}
+function num(value) {
+	if (value === void 0) return void 0;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : void 0;
+}
+async function cmdVerifyRun(args, io, deps) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			coverage: { type: "boolean" },
+			flake: { type: "boolean" },
+			mutate: { type: "boolean" },
+			"mutate-tool": { type: "string" },
+			"mutate-config": { type: "string" },
+			deps: { type: "boolean" },
+			"allow-run": { type: "boolean" },
+			"changed-file": {
+				type: "string",
+				multiple: true
+			},
+			diff: { type: "string" },
+			"flake-db": { type: "string" },
+			"osv-db": { type: "string" },
+			registry: { type: "string" },
+			"allow-private": { type: "boolean" },
+			flow: { type: "string" },
+			"flows-dir": { type: "string" },
+			request: { type: "string" },
+			"collection-dir": { type: "string" },
+			"allow-unsafe": { type: "boolean" },
+			"allow-host": {
+				type: "string",
+				multiple: true
+			},
+			var: {
+				type: "string",
+				multiple: true
+			},
+			openapi: { type: "string" },
+			graphql: { type: "string" },
+			"graphql-endpoint": { type: "string" },
+			engine: { type: "string" },
+			"no-sandbox": { type: "boolean" },
+			headed: { type: "boolean" },
+			"timeout-ms": { type: "string" },
+			"fail-at-or-above": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const projectRoot = positionals[0];
+	if (!projectRoot) {
+		io.err("verify run needs a <project-root>\n");
+		return 2;
+	}
+	const failAtOrAbove = values["fail-at-or-above"];
+	if (failAtOrAbove !== void 0 && !SEVERITIES.includes(failAtOrAbove)) {
+		io.err(`--fail-at-or-above must be one of ${SEVERITIES.join("|")}\n`);
+		return 2;
+	}
+	const allowRun = values["allow-run"] ?? false;
+	const allowedRoots = [resolve(projectRoot)];
+	const changedFiles = values["changed-file"] ?? [];
+	const diff = values.diff !== void 0 ? readFileSync(values.diff, "utf8") : void 0;
+	const timeoutMs = num(values["timeout-ms"]);
+	const ctx = {
+		projectRoot,
+		changedFiles,
+		diff
+	};
+	const request = {};
+	if (values.coverage) {
+		const ovr = deps.coverage;
+		request.coverage = { run: ovr ? () => ovr(ctx) : async () => {
+			return (await runScoped({
+				projectRoot,
+				allowedRoots,
+				allowRun,
+				timeoutMs
+			}, {
+				changedFiles,
+				diff
+			}, { runner: deps.coverageRunner })).report ?? EMPTY_COVERAGE;
+		} };
+	}
+	if (values.mutate) {
+		const ovr = deps.mutate;
+		const tool = values["mutate-tool"] ?? "stryker";
+		if (tool !== "stryker" && tool !== "cosmic-ray" && tool !== "mutmut") {
+			io.err(`verify run --mutate-tool must be stryker | cosmic-ray | mutmut (got ${tool})\n`);
+			return 2;
+		}
+		const configPath = values["mutate-config"];
+		request.mutate = { run: ovr ? () => ovr(ctx) : async () => {
+			const cfg = {
+				projectRoot,
+				allowedRoots,
+				allowRun,
+				timeoutMs
+			};
+			const mInput = {
+				mutateFiles: changedFiles,
+				configPath
+			};
+			return (tool === "cosmic-ray" ? await runCosmicRay(cfg, mInput, { runner: deps.mutateRunner }) : tool === "mutmut" ? await runMutmut(cfg, mInput, { runner: deps.mutateRunner }) : await runMutation(cfg, mInput, { runner: deps.mutateRunner })).summary;
+		} };
+	}
+	if (values.flake) {
+		const ovr = deps.flake;
+		if (ovr) request.flake = { run: () => ovr(ctx) };
+		else {
+			const dbPath = values["flake-db"];
+			const store = deps.historyStore ?? (dbPath ? HistoryStore.open(dbPath) : void 0);
+			if (!store) {
+				io.err("verify run --flake needs --flake-db <path>\n");
+				return 2;
+			}
+			request.flake = { run: async () => {
+				try {
+					return (await runAndRecord(store, {
+						projectRoot,
+						allowedRoots,
+						allowRun,
+						timeoutMs
+					}, { files: changedFiles }, { runner: deps.flakeRunner })).verdicts;
+				} finally {
+					if (!deps.historyStore && dbPath) store.close();
+				}
+			} };
+		}
+	}
+	if (values.deps) {
+		const ovr = deps.deps;
+		if (ovr) request.deps = { run: () => ovr(ctx) };
+		else {
+			const ecosystem = "npm";
+			const fetchPackument = deps.depsFetcher ?? makeFetcher(registriesFrom(values));
+			const osvDir = values["osv-db"];
+			request.deps = { run: async () => {
+				const scoped = diff ? changedDependencies(diff, ecosystem) : [];
+				const { audits, osvSnapshotLoaded } = await auditProjectScoped({
+					project: projectRoot,
+					ecosystem,
+					names: scoped.length > 0 ? scoped : void 0,
+					osvDir,
+					fetchPackument
+				});
+				return {
+					audits,
+					osvSnapshotLoaded
+				};
+			} };
+		}
+	}
+	if (values.request && values.flow) {
+		io.err("verify run: --request and --flow are mutually exclusive\n");
+		return 2;
+	}
+	if (values.request) {
+		const requestName = values.request;
+		const vars = parseVars(values.var);
+		const ovr = deps.contractApi;
+		if (ovr) request.contract = {
+			source: "capture-from-HAR",
+			run: () => ovr({
+				request: requestName,
+				collectionDir: values["collection-dir"],
+				vars
+			})
+		};
+		else {
+			const colDir = values["collection-dir"];
+			if (!colDir) {
+				io.err("verify run --request needs --collection-dir <dir>\n");
+				return 2;
+			}
+			const contract = readCaptureContract(values);
+			const store = new ArtifactStore$2(mkdtempSync(join(tmpdir(), "sackville-verify-cap-")), "verify");
+			request.contract = {
+				source: "capture-from-HAR",
+				run: async () => {
+					return (await runRequestToHar(loadCollection(colDir), requestName, {
+						vars,
+						allowUnsafe: values["allow-unsafe"] ?? false,
+						allowedHosts: values["allow-host"] ?? []
+					}, {
+						store,
+						redactor: new Redactor$1(),
+						contract
+					})).verdict;
+				}
+			};
+		}
+	}
+	if (values.flow) {
+		const flow = values.flow;
+		const vars = parseVars(values.var);
+		const ovr = deps.contract;
+		if (ovr) request.contract = {
+			source: "capture-from-HAR",
+			run: () => ovr({
+				flow,
+				vars
+			})
+		};
+		else {
+			if (!values["flows-dir"]) {
+				io.err("verify run --flow needs --flows-dir <dir>\n");
+				return 2;
+			}
+			const flowsDir = values["flows-dir"];
+			const contract = readCaptureContract(values);
+			const store = new ArtifactStore$2(mkdtempSync(join(tmpdir(), "sackville-verify-cap-")), "verify");
+			request.contract = {
+				source: "capture-from-HAR",
+				run: async () => {
+					const { harHandle } = await driveBrowserFlowToHar({
+						flow,
+						vars
+					}, {
+						runtimeFactory: () => captureRuntimeFromFlags(values),
+						store,
+						flowsDir
+					});
+					const har = store.get(harHandle)?.body;
+					if (!har) throw new Error("no HAR was captured for the driven flow");
+					return validateCapturedTraffic(har, contract, {}).results;
+				}
+			};
+		}
+	}
+	if (Object.keys(request).length === 0) {
+		io.err("verify run needs ≥1 pillar (--coverage / --flake / --mutate / --deps / --flow / --request)\n");
+		return 2;
+	}
+	const { verdict } = await orchestrate(request, { policy: { failAtOrAbove } });
+	printVerdict(io, verdict, values.json);
+	return exitFor(verdict);
+}
+/** Parse repeated `--var k=v` flags into a map (non-secret flow vars). */
+function parseVars(pairs) {
+	const vars = {};
+	for (const p of pairs ?? []) {
+		const i = p.indexOf("=");
+		if (i > 0) vars[p.slice(0, i)] = p.slice(i + 1);
+	}
+	return vars;
+}
+/** Build the capture→contract from the openapi/graphql flags (≥1 needed, like the MCP tool). */
+function readCaptureContract(values) {
+	const contract = {};
+	if (values.openapi) contract.openapi = JSON.parse(readFileSync(values.openapi, "utf8"));
+	if (values.graphql) contract.graphql = {
+		endpointPath: values["graphql-endpoint"] ?? "/graphql",
+		sdl: readFileSync(values.graphql, "utf8")
+	};
+	return contract;
+}
+/** Build a single-shot CaptureRuntime from the CLI's browser egress flags (mirrors
+* `sackville browser`): a gated, proxy-fronted manager with HAR recording armed. */
+async function captureRuntimeFromFlags(values) {
+	const gate = new BrowserGate({ allowedHosts: values["allow-host"] ?? [] });
+	const proxy = await createSsrfProxy({ allowPrivate: values["allow-private"] ?? false });
+	const harDir = mkdtempSync(join(tmpdir(), "sackville-verify-har-"));
+	const manager = new BrowserManager({
+		gate,
+		harDir,
+		launch: engineLauncher(resolveEngine(values.engine), {
+			headless: !values.headed,
+			proxyServer: proxy.url,
+			noSandbox: values["no-sandbox"] ?? false
+		})
+	});
+	return {
+		manager,
+		gate,
+		redact: (s) => s,
+		config: { harDir },
+		shutdown: async () => {
+			await manager.shutdown();
+			await proxy.close();
+		}
+	};
+}
+function runVerifyCompose(args, io) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			contract: { type: "string" },
+			source: { type: "string" },
+			coverage: { type: "string" },
+			deps: { type: "string" },
+			"osv-snapshot-loaded": { type: "boolean" },
+			flake: { type: "string" },
+			mutate: { type: "string" },
+			"fail-at-or-above": { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const failAtOrAbove = values["fail-at-or-above"];
+	if (failAtOrAbove !== void 0 && !SEVERITIES.includes(failAtOrAbove)) {
+		io.err(`--fail-at-or-above must be one of ${SEVERITIES.join("|")}\n`);
+		return 2;
+	}
+	const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
+	const inputs = {};
+	if (values.contract) {
+		const c = readJson(values.contract);
+		inputs.contract = fromContractResults(Array.isArray(c) ? c : c.results ?? [], values.source === "run" ? "run" : "capture-from-HAR");
+	}
+	if (values.coverage) inputs.coverage = fromDiffCoverage(readJson(values.coverage));
+	if (values.deps) inputs.deps = fromDependencyAudits(readJson(values.deps), { osvSnapshotLoaded: values["osv-snapshot-loaded"] ?? false });
+	if (values.flake) inputs.flake = fromFlakeVerdicts(readJson(values.flake));
+	if (values.mutate) inputs.mutate = fromMutationSummary(readJson(values.mutate));
+	const verdict = composeVerdict(inputs, { failAtOrAbove });
+	printVerdict(io, verdict, values.json);
+	return exitFor(verdict);
+}
+//#endregion
+//#region src/index.ts
+const HELP = `sackville — version-pinned documentation search
+
+Usage:
+  sackville search <query…>  [-l <lib>] [--version <v>] [--installed <v>] [-p <dir>] [--ecosystem <e>] [--type <t>] [--limit <n>] [--json]
+  sackville get <id>         [--json]
+  sackville versions <library>
+  sackville detect <project> <library>  [--ecosystem <node|python|ruby>]
+
+API testing:
+  sackville api list <dir>                               [--json]
+  sackville api get <dir> <name>                         [--json]
+  sackville api run <dir> <name>                         [--var k=v…] [--env <e>] [--unsafe] [--allow-host <h>…] [--keyring] [--block-private] [--max-redirects <n>] [--openapi <spec.json>] [--json]
+  sackville api run-collection <dir> <name…>             [--var k=v…] [--env <e>] [--unsafe] [--allow-host <h>…] [--keyring] [--block-private] [--max-redirects <n>] [--stop-on-failure] [--json]
+  sackville api validate --graphql <schema> --query <q>  [--operation <name>] [--json]
+  sackville api import <postman|insomnia|openapi|har> <source-file> <dest-dir>  [--name <n>]
+
+Browser testing (single-shot; the typed host is auto-allowed):
+  sackville browser snapshot <url>    [--allow-host <h>…] [--allow-private] [--no-sandbox] [--headed] [--engine chromium|firefox|webkit] [--json]
+  sackville browser audit <url>       [same flags]   (exit 1 if any a11y violations)
+  sackville browser screenshot <url>  [--out <file>] [--full-page] [same flags]
+  sackville browser run <flow.bru>    [--var k=v…] [--unsafe] [--allow-host <h>…] [same flags]  (replay a persisted flow; exit 1 on failure)
+
+Mutation testing:
+  sackville mutate summarize <report-file>  [--format stryker|mutmut] [--json]
+  sackville mutate run <project-root>        [--file <f>…] [--incremental] [--allow-run] [--timeout-ms <n>] [--report-path <p>] [--json]  (gated; needs --allow-run)
+
+Coverage (impact-scoped; exit 1 when a new line is uncovered):
+  sackville coverage uncovered-in-diff --diff <file> --coverage <file>  [--coverage-format istanbul|coveragepy] [--project-root <p>] [--json]
+  sackville coverage run-scoped <project-root>  --changed-file <f>…  [--diff <file>] [--allow-run] [--timeout-ms <n>] [--json]  (gated; needs --allow-run)
+
+Flaky-test detection (--db <run-history.db> or SACKVILLE_FLAKE_DB):
+  sackville flake status                  [--min-runs <n>] [--limit-per-test <n>] [--since <ISO>] [--json]
+  sackville flake candidates              [--min-flake-score <0..1>] [--min-runs <n>] [--json]
+  sackville flake ingest <report-file>    [--format vitest|pytest] [--at <ISO>] [--project-root <p>] [--run-group <g>] [--json]
+  sackville flake release <testId>
+  sackville flake run <project-root>      [--repeat <n>] [--file <f>…] [--run-group <g>] [--allow-run] [--timeout-ms <n>] [--json]  (gated)
+  sackville flake quarantine <testId>     --reason <r> --expires-at <ISO> [--flake-score <s>] [--allow-quarantine] [--max-expiry-ms <n>] [--json]  (gated write)
+
+Dependency/version intelligence (for the INSTALLED version; exit 1 on a finding):
+  sackville deps audit <project> <package>  [--ecosystem npm|PyPI|RubyGems] [--version <v>] [--osv-db <dir>] [--registry <url>] [--allow-private] [--json]
+  sackville deps audit-project <project>     [--ecosystem <e>] [--skip-dev] [--osv-db <dir>] [--registry <url>] [--allow-private] [--json]
+  sackville deps changelog <package>         (--from <v> | --project <dir>) [--to <v>] [--ecosystem <e>] [--registry <url>] [--json]
+
+Semantic code navigation (LSP; single-shot; --servers <json> or SACKVILLE_LSP_SERVERS binds the server registry):
+  sackville lsp languages                                          [--servers <json>] [--json]
+  sackville lsp definition|type-definition|references|hover <lang> <file> <line> <col>  --project <dir> --allow-run [--servers <json>] [--timeout-ms <n>] [--json]
+  sackville lsp symbols <lang> <file>                              --project <dir> --allow-run [--servers <json>] [--json]
+  sackville lsp call-hierarchy <lang> <file> <line> <col>          --project <dir> --allow-run [--direction incoming|outgoing] [--json]
+  sackville lsp rename <lang> <file> <line> <col> <newName>        --project <dir> --allow-run [--allow-write] [--allow-partial-rename] [--json]  (dry-run unless --allow-write)
+  (exit 2 = server still indexing, retry; a "suspect" rename — an open-files-scoped server's likely-partial edit — is refused for write unless --allow-partial-rename)
+
+Global:
+  -i, --index <file>   index to query (or set SACKVILLE_INDEX)
+`;
+async function run(argv, io) {
+	const [command, ...rest] = argv;
+	switch (command) {
+		case "search": return cmdSearch(rest, io);
+		case "get": return cmdGet(rest, io);
+		case "versions": return cmdVersions(rest, io);
+		case "detect": return cmdDetect(rest, io);
+		case "api": return runApi(rest, io);
+		case "browser": return runBrowser(rest, io);
+		case "mutate": return runMutate(rest, io);
+		case "coverage": return runCoverage(rest, io);
+		case "flake": return runFlake(rest, io);
+		case "deps": return runDeps(rest, io);
+		case "lsp": return runLsp(rest, io);
+		case "verify": return runVerify(rest, io);
+		case "help":
+		case "--help":
+		case "-h":
+			io.out(HELP);
+			return 0;
+		case void 0:
+			io.err(HELP);
+			return 1;
+		default:
+			io.err(`unknown command: ${command}\n`);
+			io.err(HELP);
+			return 1;
+	}
+}
+function openIndex(indexFlag, io) {
+	const path = indexFlag ?? io.env?.SACKVILLE_INDEX;
+	if (!path) {
+		io.err("no index given: pass --index <file> or set SACKVILLE_INDEX\n");
+		return null;
+	}
+	return openDb(path);
+}
+async function cmdSearch(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			index: {
+				type: "string",
+				short: "i"
+			},
+			library: {
+				type: "string",
+				short: "l"
+			},
+			version: { type: "string" },
+			installed: { type: "string" },
+			project: {
+				type: "string",
+				short: "p"
+			},
+			ecosystem: { type: "string" },
+			type: { type: "string" },
+			limit: { type: "string" },
+			json: { type: "boolean" }
+		}
+	});
+	const query = positionals.join(" ").trim();
+	if (!query) {
+		io.err("search needs a query\n");
+		return 1;
+	}
+	const db = openIndex(values.index, io);
+	if (!db) return 1;
+	try {
+		let effectiveVersion = values.version;
+		let note;
+		if (!values.version && (values.installed || values.project) && values.library) {
+			let requested = values.installed;
+			if (!requested && values.project) {
+				requested = detectInstalledVersion(values.project, values.library, { ecosystem: values.ecosystem }).version ?? void 0;
+				if (!requested) note = `could not detect ${values.library} in ${values.project}`;
+			}
+			if (requested) {
+				const res = resolveVersion(listVersions(db, values.library), requested);
+				note = res.note;
+				if (res.resolved) effectiveVersion = res.resolved;
+			}
+		}
+		let queryVector;
+		if (io.embedder) try {
+			queryVector = await io.embedder.embed(query);
+		} catch {
+			queryVector = void 0;
+		}
+		const results = searchDocs(db, query, {
+			library: values.library,
+			version: effectiveVersion,
+			type: values.type,
+			limit: values.limit ? Number(values.limit) : void 0,
+			queryVector
+		});
+		if (values.json) {
+			io.out(`${JSON.stringify({
+				query,
+				version: effectiveVersion ?? null,
+				note,
+				results
+			}, null, 2)}\n`);
+			return 0;
+		}
+		if (note) io.err(`${note}\n`);
+		if (results.length === 0) {
+			io.out("no matches\n");
+			return 0;
+		}
+		for (const r of results) {
+			const sym = r.symbol ? `  (${r.symbol})` : "";
+			io.out(`${r.version}  [${r.type ?? "-"}]  ${r.title}${sym}\n`);
+			io.out(`    ${r.snippet}\n`);
+			io.out(`    sackville://doc/${r.id}\n`);
+		}
+		return 0;
+	} finally {
+		db.close();
+	}
+}
+function cmdGet(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			index: {
+				type: "string",
+				short: "i"
+			},
+			json: { type: "boolean" }
+		}
+	});
+	const id = Number(positionals[0]);
+	if (!Number.isInteger(id)) {
+		io.err("get needs a numeric id\n");
+		return 1;
+	}
+	const db = openIndex(values.index, io);
+	if (!db) return 1;
+	try {
+		const doc = getDoc(db, id);
+		if (!doc) {
+			io.err(`no document with id ${id}\n`);
+			return 1;
+		}
+		if (values.json) {
+			io.out(`${JSON.stringify(doc, null, 2)}\n`);
+			return 0;
+		}
+		io.out(`${doc.title}  [${doc.type ?? "-"}]  ${doc.library} ${doc.version}\n`);
+		if (doc.headingPath) io.out(`${doc.headingPath}\n`);
+		if (doc.url) io.out(`${doc.url}\n`);
+		io.out(`\n${doc.body}\n`);
+		if (doc.attribution) io.out(`\n— ${doc.attribution}\n`);
+		return 0;
+	} finally {
+		db.close();
+	}
+}
+function cmdVersions(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { index: {
+			type: "string",
+			short: "i"
+		} }
+	});
+	const library = positionals[0];
+	if (!library) {
+		io.err("versions needs a library\n");
+		return 1;
+	}
+	const db = openIndex(values.index, io);
+	if (!db) return 1;
+	try {
+		const versions = listVersions(db, library);
+		io.out(versions.length ? `${versions.join("\n")}\n` : `no versions indexed for ${library}\n`);
+		return 0;
+	} finally {
+		db.close();
+	}
+}
+function cmdDetect(args, io) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			index: {
+				type: "string",
+				short: "i"
+			},
+			ecosystem: { type: "string" }
+		}
+	});
+	const [project, library] = positionals;
+	if (!project || !library) {
+		io.err("detect needs <project> <library>\n");
+		return 1;
+	}
+	const db = openIndex(values.index, io);
+	if (!db) return 1;
+	try {
+		const detected = detectInstalledVersion(project, library, { ecosystem: values.ecosystem });
+		const res = resolveVersion(listVersions(db, library), detected.version ?? "");
+		io.out(`detected: ${detected.version ?? "(none)"} (${detected.source})\n`);
+		io.out(`resolved: ${res.resolved ?? "(none)"}\n`);
+		io.out(`${res.note}\n`);
+		return 0;
+	} finally {
+		db.close();
+	}
+}
+//#endregion
+export { run as t };
+
+//# sourceMappingURL=src-DM4aqvlX.mjs.map