hollware 0.0.1 → 0.1.0

package/dist/import-Dlpn_w3s.mjs

@@ -0,0 +1,506 @@
+import { i as UsageError, r as CliError, t as printable } from "./format-BpRYEsGB.mjs";
+import { t as readVersion } from "./version-BMhdZaNo.mjs";
+import { t as parseFlags } from "./args-CljWh-kZ.mjs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { REFUSAL_CONTRACT_IDS, createDraft, getEntry, isPersonalToken, publish, schemas, updateDraft, validate } from "@hollware/core";
+import { Client, InsufficientScopeError, ProtocolError, SdkError, SdkErrorCode, SdkHttpError, StreamableHTTPClientTransport, UnauthorizedError } from "@modelcontextprotocol/client";
+//#region src/import/corpus.ts
+/**
+* Reads the entries of a directory laid out as `<collection>/<locale>/<slug>.md`. Only `.md`
+* files count. A Markdown file at any other depth is skipped and reported; one at the right
+* depth with a slug that is not a slug, or with bytes that are not UTF-8, is a problem. Files
+* and folders whose name starts with a dot, and symbolic links, are never read: a link could
+* lead out of the directory the person pointed at.
+*/
+function readCorpus(root) {
+	const corpus = {
+		files: [],
+		skipped: [],
+		problems: []
+	};
+	walk(root, [], corpus);
+	corpus.files.sort((a, b) => compare(a.collection, b.collection) || compare(a.locale, b.locale) || compare(a.slug, b.slug));
+	corpus.skipped.sort(compare);
+	corpus.problems.sort((a, b) => compare(a.path, b.path));
+	return corpus;
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function walk(directory, segments, corpus) {
+	for (const entry of readdirSync(directory, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		if (entry.isDirectory()) walk(join(directory, entry.name), [...segments, entry.name], corpus);
+		else if (entry.isFile() && entry.name.endsWith(".md")) readFile(join(directory, entry.name), [...segments, entry.name], corpus);
+	}
+}
+function readFile(file, segments, corpus) {
+	const path = segments.join("/");
+	const [collection, locale, name] = segments;
+	if (segments.length !== 3 || collection === void 0 || locale === void 0 || name === void 0) {
+		corpus.skipped.push(path);
+		return;
+	}
+	const slug = name.slice(0, -3);
+	if (!schemas.slug.safeParse(slug).success) {
+		corpus.problems.push({
+			path,
+			reason: `${JSON.stringify(slug)} is not a slug: use lowercase letters and digits joined by hyphens, up to 200 characters.`
+		});
+		return;
+	}
+	let bytes;
+	try {
+		bytes = readFileSync(file);
+	} catch (error) {
+		corpus.problems.push({
+			path,
+			reason: `the file cannot be read: ${error instanceof Error ? error.message : String(error)}`
+		});
+		return;
+	}
+	let markdown;
+	try {
+		markdown = new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: true
+		}).decode(bytes);
+	} catch {
+		corpus.problems.push({
+			path,
+			reason: "the file is not valid UTF-8."
+		});
+		return;
+	}
+	corpus.files.push({
+		path,
+		collection,
+		locale,
+		slug,
+		markdown
+	});
+}
+//#endregion
+//#region src/import/session.ts
+/** A tool failed and said so in words, instead of answering with one of its outcomes. */
+var ToolFailure = class extends CliError {
+	name = "ToolFailure";
+};
+/**
+* Connects to `endpoint` over MCP's Streamable HTTP, with `token` as a bearer token. A refusal
+* of the connection or a failure of the transport is thrown as a `CliError` that says what to
+* do. Nothing is sent to any other address: a redirect to another origin is not followed.
+*/
+async function openSession(endpoint, token, version) {
+	const client = new Client({
+		name: "hollware-cli",
+		version
+	});
+	const transport = new StreamableHTTPClientTransport(endpoint, {
+		authProvider: { token: () => Promise.resolve(token) },
+		onInsufficientScope: "throw",
+		redirectPolicy: "same-origin"
+	});
+	try {
+		await client.connect(transport);
+	} catch (error) {
+		await client.close().catch(() => void 0);
+		throw explain(error, endpoint) ?? error;
+	}
+	return {
+		call: async (spec, input) => {
+			let result;
+			try {
+				result = await client.callTool({
+					name: spec.name,
+					arguments: spec.input.parse(input)
+				});
+			} catch (error) {
+				throw explain(error, endpoint) ?? error;
+			}
+			const answer = spec.output.safeParse(payloadOf(result));
+			if (answer.success) return answer.data;
+			throw new ToolFailure(`${spec.name} failed: ${wordsOf(result)}`);
+		},
+		close: () => client.close().catch(() => void 0)
+	};
+}
+function payloadOf(result) {
+	if (result.structuredContent !== void 0) return result.structuredContent;
+	for (const block of result.content) {
+		if (block.type !== "text") continue;
+		try {
+			return JSON.parse(block.text);
+		} catch {}
+	}
+}
+function wordsOf(result) {
+	const words = result.content.flatMap((block) => block.type === "text" ? [block.text] : []).join(" ").replace(/\s+/g, " ").trim();
+	return printable(words === "" ? "it gave neither an outcome nor a reason" : words.slice(0, 500));
+}
+/** What a failure of the transport means for the person who ran the command. */
+function explain(error, endpoint) {
+	if (error instanceof CliError) return error;
+	if (error instanceof UnauthorizedError) return rejectedToken();
+	if (error instanceof InsufficientScopeError) {
+		const needed = error.requiredScope === void 0 ? "" : `: ${printable(error.requiredScope)}`;
+		return new CliError(`the token lacks a scope this call needs (403 insufficient_scope${needed}). "hollware token create --scopes <list>" makes one that has it.`);
+	}
+	if (error instanceof SdkHttpError) return explainStatus(error, endpoint);
+	if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) return new CliError(`the server at ${endpoint.origin} did not answer in time.`);
+	if (error instanceof SdkError && error.code === SdkErrorCode.ClientHttpUnexpectedContent) return new CliError(`the server at ${endpoint.href} does not answer like an MCP server. Check --url.`);
+	if (error instanceof ProtocolError) return new CliError(`the server refused the request: ${printable(error.message)}`);
+	if (error instanceof TypeError && error.message === "fetch failed") {
+		const { cause } = error;
+		const why = cause instanceof Error ? ` (${"code" in cause ? String(cause.code) : cause.message})` : "";
+		return new CliError(`could not reach ${endpoint.origin}${why}. Check --url and that Hollware is running.`);
+	}
+}
+function rejectedToken() {
+	return new CliError("the server rejected the token (401). It may be wrong, expired or revoked: \"hollware token create\" makes a new one.");
+}
+function explainStatus(error, endpoint) {
+	if (error.status >= 300 && error.status < 400) {
+		const reason = error.message.replace(/^Error POSTing to endpoint: /, "").replace(/ \(redirectPolicy: [^)]*\)$/, "");
+		return new CliError(`the server redirected the request, and hollware does not follow a redirect with the token: ${printable(reason)}.`);
+	}
+	switch (error.status) {
+		case 401: return rejectedToken();
+		case 403: return new CliError("the server refused the request (403). The token may lack a scope, or the host in --url is not the one the server is set up for (its HOLLWARE_PUBLIC_URL).");
+		case 404: return new CliError(`there is no MCP endpoint at ${endpoint.href} (404). Check --url.`);
+		default: {
+			const status = [error.status, error.statusText].filter((part) => part !== void 0 && part !== "").join(" ");
+			const { text } = error.data;
+			const detail = typeof text === "string" && text.trim() !== "" ? `: ${printable(text.trim().slice(0, 300))}` : "";
+			return new CliError(`the server answered ${status}${detail}`);
+		}
+	}
+}
+//#endregion
+//#region src/commands/import.ts
+const IMPORT_USAGE = [
+	"Usage: hollware import <directory> --url <hollware url> (--token-file <file> | token on stdin)",
+	"                       [--publish] [--dry-run]",
+	"",
+	"Sends the Markdown files of a directory to a running Hollware over MCP, as drafts. The files",
+	"are <directory>/<collection>/<locale>/<slug>.md. Every file is validated first: if one would be",
+	"refused, nothing is written. Running it again changes nothing: an entry that is already",
+	"there with the same Markdown is \"unchanged\".",
+	"",
+	"Options:",
+	"  --url <url>          The address of your Hollware, such as https://cms.example.com (MCP is at <url>/mcp)",
+	"  --token-file <file>  A file with a personal token; without it, the token is read from stdin",
+	"  --publish            Then publish the entries that have unpublished changes, acknowledging no warnings",
+	"  --dry-run            Only validate: write nothing, publish nothing",
+	"  --help               Show this help",
+	"",
+	"The token needs content:read and content:write, and content:publish for --publish."
+].join("\n");
+async function importContent(argv, io) {
+	const { values, positionals } = parseFlags({
+		args: [...argv],
+		allowPositionals: true,
+		options: {
+			url: { type: "string" },
+			"token-file": { type: "string" },
+			publish: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+			help: { type: "boolean" }
+		}
+	});
+	if (values.help === true) {
+		io.out(IMPORT_USAGE);
+		return 0;
+	}
+	const [directory, ...extra] = positionals;
+	if (directory === void 0 || extra.length > 0) throw new UsageError("import takes one directory: hollware import <directory> --url <url>.");
+	if (values.url === void 0) throw new UsageError("--url is required: the address of your Hollware, such as https://cms.example.com.");
+	const endpoint = mcpEndpoint(values.url);
+	const root = resolve(io.cwd, directory);
+	if (!isDirectory(root)) throw new CliError(`${directory} is not a directory.`);
+	const token = await readToken(io, values["token-file"]);
+	try {
+		return await importFiles({
+			io,
+			token,
+			endpoint,
+			directory,
+			root,
+			publish: values.publish === true,
+			dryRun: values["dry-run"] === true
+		});
+	} catch (error) {
+		if (error instanceof CliError) throw new CliError(redact(error.message, token));
+		const reason = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ");
+		throw new CliError(`unexpected error: ${redact(printable(reason.slice(0, 300)), token)}. This is a bug in hollware: please report it at https://github.com/hollware/hollware/issues.`);
+	}
+}
+async function importFiles({ io, token, endpoint, directory, root, publish: publishToo, dryRun }) {
+	const out = (message) => io.out(redact(message, token));
+	const corpus = readCorpus(root);
+	if (corpus.files.length === 0 && corpus.problems.length === 0) throw new CliError(`no entries in ${directory}: expected Markdown files at <collection>/<locale>/<slug>.md, such as blog/en/hello.md.`);
+	if (corpus.files.length > 0) out(`Found ${count(corpus.files.length, "entry", "entries")} in ${directory} (${collectionSummary(corpus.files)}).`);
+	if (corpus.skipped.length > 0) out(`Skipped ${count(corpus.skipped.length, "Markdown file")} that ${corpus.skipped.length === 1 ? "is" : "are"} not at <collection>/<locale>/<slug>.md: ${listSome(corpus.skipped)}.`);
+	if (corpus.problems.length > 0) throw new CliError([
+		`${count(corpus.problems.length, "file")} cannot be imported, so nothing was sent:`,
+		...corpus.problems.map((problem) => `  ${printable(problem.path)}: ${problem.reason}`),
+		"Fix or remove them and run the import again."
+	].join("\n"));
+	const session = await openSession(endpoint, token, readVersion());
+	try {
+		const checks = await validateAll(session, corpus.files);
+		if (dryRun) out(dryRunReport(checks));
+		const refused = checks.filter((check) => check.refusals.length > 0 || check.failure !== void 0);
+		if (refused.length > 0) throw new CliError(refusalReport(refused, checks.length, dryRun));
+		if (dryRun) {
+			out(`Dry run: ${count(checks.length, "file")} validated, none would be refused. Nothing was written.`);
+			return 0;
+		}
+		out(`Validated ${count(checks.length, "file")}: none would be refused.`);
+		const drafts = await writeDrafts(session, corpus.files, out);
+		out(`Drafts: ${drafts.created} created, ${drafts.updated} updated, ${drafts.unchanged} unchanged${drafts.failed === 0 ? "" : `, ${drafts.failed} failed`}.`);
+		if (drafts.failed > 0) throw new CliError(`${count(drafts.failed, "file")} could not be imported (see above).${publishToo ? " Nothing was published." : ""} Fix ${drafts.failed === 1 ? "it" : "them"} and run the import again: what is already there stays unchanged.`);
+		if (!publishToo) return 0;
+		const published = await publishAll(session, drafts.entries.filter((imported) => imported.summary.hasUnpublishedChanges), out);
+		out(`Publishing: ${published.published} published, ${published.needsAcknowledgement} need acknowledgement, ${published.blocked} blocked${published.other === 0 ? "" : `, ${published.other} failed`}.`);
+		const problems = published.needsAcknowledgement + published.blocked + published.other;
+		if (problems > 0) throw new CliError(`${count(problems, "entry", "entries")} not published: warnings are never acknowledged here, and errors block publishing. Fix the content and run the import again with --publish: what is already published is skipped.`);
+		return 0;
+	} finally {
+		await session.close();
+	}
+}
+/** The MCP endpoint of a Hollware, from the address a person gives: `<url>/mcp`. */
+function mcpEndpoint(address) {
+	let url;
+	try {
+		url = new URL(address);
+	} catch {
+		throw new UsageError(`invalid --url ${printable(JSON.stringify(address))}: use the address of your Hollware, such as https://cms.example.com.`);
+	}
+	if (url.username !== "" || url.password !== "") throw new UsageError("--url must not hold a user name or a password: the token comes from --token-file or stdin.");
+	if (url.search !== "" || url.hash !== "") throw new UsageError("--url takes the address of Hollware only, without a query or a fragment.");
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) throw new UsageError("--url must start with https://, or the token would travel unencrypted. Plain http is accepted only for localhost.");
+	const path = url.pathname.replace(/\/+$/, "");
+	url.pathname = path.endsWith("/mcp") ? path : `${path}/mcp`;
+	return url;
+}
+function isLoopback(hostname) {
+	return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+async function readToken(io, tokenFile) {
+	let raw;
+	let source;
+	if (tokenFile === void 0) {
+		raw = await io.readStdin();
+		source = "on stdin";
+		if (raw === void 0) throw new UsageError("give the token with --token-file <file>, or pipe it into stdin.");
+	} else {
+		source = `in ${tokenFile}`;
+		try {
+			raw = readFileSync(resolve(io.cwd, tokenFile), "utf8");
+		} catch (error) {
+			throw new CliError(`could not read the token file ${tokenFile}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	const token = raw.trim();
+	if (!isPersonalToken(token)) throw new CliError(`the token ${source} is not a Hollware personal token: it is hw_pat_ followed by 52 characters. "hollware token create" makes one.`);
+	return token;
+}
+const TOKEN_SHAPE = /hw_pat_[0-9a-hjkmnp-tv-z]{52}/g;
+/** `text` without `secret`, and without anything else that has the shape of a personal token. */
+function redact(text, secret) {
+	return text.split(secret).join("hw_pat_[redacted]").replace(TOKEN_SHAPE, "hw_pat_[redacted]");
+}
+async function validateAll(session, files) {
+	const checks = [];
+	for (const file of files) try {
+		const answer = await session.call(validate, {
+			collection: file.collection,
+			locale: file.locale,
+			slug: file.slug,
+			markdown: file.markdown
+		});
+		checks.push({
+			file,
+			verdict: answer.verdict,
+			refusals: answer.verdict.errors.filter((violation) => REFUSAL_CONTRACT_IDS.includes(violation.contract)),
+			failure: void 0
+		});
+	} catch (error) {
+		if (!(error instanceof ToolFailure)) throw error;
+		checks.push({
+			file,
+			verdict: void 0,
+			refusals: [],
+			failure: error.message
+		});
+	}
+	return checks;
+}
+function dryRunReport(checks) {
+	const lines = [];
+	for (const { file, verdict, refusals, failure } of checks) {
+		const state = failure !== void 0 || refusals.length > 0 ? "refused" : "ok";
+		lines.push(`${state.padEnd(7)}  ${printable(file.path)}`);
+		for (const violation of verdict?.errors ?? []) lines.push(`         ${violationLine(violation)}`);
+		for (const violation of verdict?.warnings ?? []) lines.push(`         ${violationLine(violation)}`);
+	}
+	return lines.join("\n");
+}
+function refusalReport(refused, total, dryRun) {
+	const lines = refused.flatMap(({ file, refusals, failure }) => failure !== void 0 ? [`  ${printable(file.path)}: ${failure}`] : refusals.map((violation) => `  ${printable(file.path)}: ${violationLine(violation)}`));
+	return [
+		`${refused.length} of ${count(total, "file")} would be refused, so ${dryRun ? "a real import would write nothing" : "nothing was written"}:`,
+		...lines,
+		"Fix them and run the import again."
+	].join("\n");
+}
+function violationLine(violation) {
+	const line = violation.line === void 0 ? "" : ` (line ${violation.line})`;
+	return printable(`${violation.severity} [${violation.contract}] ${violation.path}${line}: ${violation.message} Fix: ${violation.fix}`);
+}
+/**
+* Phase one: every file becomes a draft. An entry that does not exist is created; one that
+* does is updated at the version just read, which Hollware answers with `unchanged` when the
+* Markdown is the same. A failure of one file does not stop the others.
+*/
+async function writeDrafts(session, files, out) {
+	const drafts = {
+		created: 0,
+		updated: 0,
+		unchanged: 0,
+		failed: 0,
+		entries: []
+	};
+	for (const file of files) {
+		const label = printable(file.path.replace(/\.md$/, ""));
+		try {
+			const found = await session.call(getEntry, {
+				collection: file.collection,
+				locale: file.locale,
+				slug: file.slug,
+				formats: ["markdown"]
+			});
+			if (found.outcome === "not_found" || found.entry === void 0) {
+				const created = await session.call(createDraft, {
+					collection: file.collection,
+					locale: file.locale,
+					slug: file.slug,
+					markdown: file.markdown
+				});
+				if (created.outcome !== "saved" || created.entry === void 0) throw new ToolFailure(`create_draft ${created.outcome}${refusalReasons(created.verdict)}`);
+				drafts.created += 1;
+				drafts.entries.push({
+					file,
+					summary: created.entry
+				});
+				out(draftLine("created", label, created.entry, created.verdict));
+				continue;
+			}
+			const updated = await session.call(updateDraft, {
+				id: found.entry.id,
+				version: found.entry.version,
+				markdown: file.markdown
+			});
+			if (updated.outcome === "conflict") throw new ToolFailure(`update_draft conflict: someone changed the entry while it was imported${updated.conflict === void 0 ? "" : ` (it is at version ${updated.conflict.currentVersion} now)`}`);
+			if (updated.outcome === "saved" || updated.outcome === "unchanged") {
+				const entry = updated.entry ?? found.entry;
+				const kind = updated.outcome === "saved" ? "updated" : "unchanged";
+				drafts[kind] += 1;
+				drafts.entries.push({
+					file,
+					summary: entry
+				});
+				out(draftLine(kind, label, entry, updated.verdict));
+				continue;
+			}
+			throw new ToolFailure(`update_draft ${updated.outcome}${refusalReasons(updated.verdict)}`);
+		} catch (error) {
+			if (!(error instanceof ToolFailure)) throw error;
+			drafts.failed += 1;
+			out(`${"failed".padEnd(9)}  ${label}  ${error.message}`);
+		}
+	}
+	return drafts;
+}
+function refusalReasons(verdict) {
+	const reasons = (verdict?.errors ?? []).map((violation) => violationLine(violation));
+	return reasons.length === 0 ? "" : `: ${reasons.join("; ")}`;
+}
+function draftLine(kind, label, entry, verdict) {
+	const errors = verdict?.errors.length ?? 0;
+	const warnings = verdict?.warnings.length ?? 0;
+	const notes = [errors > 0 ? count(errors, "error") : void 0, warnings > 0 ? count(warnings, "warning") : void 0].filter((note) => note !== void 0);
+	return `${kind.padEnd(9)}  ${label}  ${entry.id}  v${entry.version}${notes.length === 0 ? "" : ` (${notes.join(", ")})`}`;
+}
+/**
+* Phase two: publishes each imported entry that has unpublished changes, at the version phase
+* one left it. It acknowledges no warning: an entry with warnings is reported, not published.
+*/
+async function publishAll(session, entries, out) {
+	const result = {
+		published: 0,
+		needsAcknowledgement: 0,
+		blocked: 0,
+		other: 0
+	};
+	for (const { file, summary } of entries) {
+		const label = printable(file.path.replace(/\.md$/, ""));
+		const line = (outcome, details = []) => [`${outcome.padEnd(21)}  ${label}  ${summary.id}`, ...details.map((detail) => `    ${detail}`)].join("\n");
+		try {
+			const answer = await session.call(publish, {
+				id: summary.id,
+				version: summary.version
+			});
+			switch (answer.outcome) {
+				case "published":
+					result.published += 1;
+					out(line("published"));
+					break;
+				case "needs_acknowledgement":
+					result.needsAcknowledgement += 1;
+					out(line("needs_acknowledgement", (answer.verdict?.warnings ?? []).map(violationLine)));
+					break;
+				case "blocked":
+					result.blocked += 1;
+					out(line("blocked", (answer.verdict?.errors ?? []).map(violationLine)));
+					break;
+				case "conflict":
+					result.other += 1;
+					out(line("conflict", ["someone changed the entry after it was imported"]));
+					break;
+				case "not_found":
+					result.other += 1;
+					out(line("not_found", ["the entry is gone"]));
+			}
+		} catch (error) {
+			if (!(error instanceof ToolFailure)) throw error;
+			result.other += 1;
+			out(line("failed", [error.message]));
+		}
+	}
+	return result;
+}
+function count(n, singular, plural = `${singular}s`) {
+	return `${n} ${n === 1 ? singular : plural}`;
+}
+function collectionSummary(files) {
+	const sizes = /* @__PURE__ */ new Map();
+	for (const file of files) sizes.set(file.collection, (sizes.get(file.collection) ?? 0) + 1);
+	return [...sizes].map(([collection, size]) => `${printable(collection)}: ${size}`).join(", ");
+}
+function listSome(paths) {
+	const shown = paths.slice(0, 5).map(printable);
+	return paths.length > shown.length ? `${shown.join(", ")} and ${paths.length - shown.length} more` : shown.join(", ");
+}
+//#endregion
+export { importContent };

package/dist/index.d.mts

@@ -1,11 +1,52 @@
+//#region src/wrangler.d.ts
+/** What a run of wrangler left behind. */
+interface WranglerResult {
+  /** The exit code; 1 when wrangler was killed by a signal. */
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+/** Runs the project's wrangler with these arguments, from the project directory. */
+type RunWrangler = (args: readonly string[]) => Promise<WranglerResult>;
+/**
+ * A runner that starts the project's wrangler as a child process in `cwd`. Its stdin is closed
+ * and its output is captured, so wrangler runs without a terminal and never asks anything. It
+ * inherits the environment, which is where wrangler finds its Cloudflare credentials.
+ */
+export declare function createWranglerRunner(cwd: string): RunWrangler;
+//#endregion
+//#region src/io.d.ts
+/**
+ * Everything a command takes from the outside world. `main` gets it as an argument and nothing
+ * in this package reads `process`, so a test hands in a fake of each part. The entry point of
+ * `index.ts` builds the real one.
+ */
+interface Io {
+  /** One message for stdout. Whoever owns the stream adds the trailing newline. */
+  out: (message: string) => void;
+  /** One message for stderr. */
+  err: (message: string) => void;
+  /** The directory a command works in: the project of `init`, `migrate` and `token`. Relative paths resolve against it. */
+  cwd: string;
+  /** The current time. */
+  now: () => Date;
+  /** Bytes from a cryptographically secure source, for ids and tokens. */
+  randomBytes: (length: number) => Uint8Array;
+  /** Everything piped into stdin, as text; `undefined` when stdin is a terminal and nothing was piped. */
+  readStdin: () => Promise<string | undefined>;
+  /** Runs the project's wrangler with these arguments. */
+  wrangler: RunWrangler;
+  /** A new empty directory for temporary files. Whoever asks for it removes it. */
+  tempDir: () => string;
+}
+//#endregion
 //#region src/index.d.ts
 /**
- * Runs the CLI and returns its exit code. Each call to `io.out` or `io.err` is one
- * message; whoever owns the streams adds the trailing newline. Only the first
- * argument is looked at.
+ * Runs the CLI and returns its exit code. Each call to `io.out` or `io.err` is one message;
+ * whoever owns the streams adds the trailing newline. The command is the first argument; the
+ * rest are its own. A `CliError` becomes one message on stderr and the exit code 1, and
+ * anything else is a bug, which escapes.
  */
-export declare function main(argv: string[], io: {
-  out: (s: string) => void;
-  err: (s: string) => void;
-}): number;
-//#endregion
+export declare function main(argv: string[], io: Io): Promise<number>;
+//#endregion
+export type { Io, RunWrangler, WranglerResult };