gesso-vite-plugin 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # gesso-vite-plugin
 
+## 0.5.0
+
+### Minor Changes
+
+- f265910: An AI agent can drive a web application while it runs in development. `gesso-vite-plugin` serves MCP at `/__gesso/mcp` on the dev server and prints the `claude mcp add` line to connect; the agent then sees every channel the open page can reach, the ones its render worker feeds and the ones its application and channel workers serve, and its commands change the page as a click would. Messages travel down the HMR socket to the page, which answers them against the render worker, which asks each worker behind it over a `gesso:agent` port. A command marked `@confirm` is put to the person with the browser's dialog first. The endpoint refuses requests from browser pages, the newest open tab answers, and `agent: false` turns it off. A build carries none of it.
+
+  `gesso-framework/agent` gains what the bridge is made of: `serveAgentPort`, `remoteSurface` and `combineSurfaces` for a surface across threads, `connectDevAgent` for the page's half, and `AgentSurfaceLike` for a surface whose answers are promises, which `handleMcpMessage` and `mcpHandler` now accept. `WorkerApp.openRenderPort(key)` opens a port to the render worker. The scaffolded `AGENTS.md` says how to connect.
+
+- c38f97e: A single-thread app can be driven by an AI agent too. `createSyncApp(...)` builders now answer `openRenderPort('gesso:agent')` from the page, with the channels fed there, whatever their channel workers serve, and the screen tools, so the dev server endpoint and WebMCP work exactly as they do for `createApp`. `useWebMcp(true | false | { confirm })` is the builder's form of `createApp({ webmcp })`. In a dev server, `gesso-vite-plugin` now hands a `createSyncApp` builder to the agent bridge and turns WebMCP on unless the app's own `useWebMcp(false)` says otherwise. The screen tools run a pending frame after each action on the main thread as they do in the render worker, so a background tab still reports what changed. `serveApplicationAgent` in `gesso-framework/agent` is the assembly both configurations share.
+- 96f4bdc: A channel can describe itself. `describeChannel(token, schema)` attaches a JSON Schema of the channel's view and of each command, and `channelSchema(token)` reads it back, so anything that meets an application only at run time can ask a channel what it holds and what its commands take: an AI agent being handed the channel as tools, a devtools panel, a test that drives an app by its commands.
+
+  `gesso-vite-plugin` writes the schema for you. It reads each contract with TypeScript 7's checker and takes the descriptions from the JSDoc you already wrote: on the token, on each view key, on each command, and `@param` for its parameters. Four tags annotate a command for an agent: `@destructive`, `@idempotent`, `@confirm` and `@hidden`. A value that cannot cross a channel, such as a `Date`, a `Map` or an untyped `[]`, is reported as a build warning naming its path. The plugin needs `typescript` 7 or later installed, says so once if it is not, and `channelSchemas: false` turns the whole thing off.
+
+- 88d93b3: A command may carry bytes. An `ArrayBuffer` or a typed array in a command's parameters is no longer reported as unable to cross a channel, because a command's argument is structured-cloned and bytes clone as themselves; a file can be sent as its bytes, with no base64 pass on the render thread. The schema describes such a field as a base64 string tagged `x-gesso-binary` with the type it becomes, and the agent surface decodes an agent's base64 back into that type before the command is sent. Bytes in a view key are still a warning, since a view is diffed.
+- fa859bb: A desktop app serves its channels to AI agents. `serveDesktopAgent(channels, options)` in `gesso-electrobun/desktop` serves them over MCP from the main process with `Bun.serve`, which Cottontail provides, on `127.0.0.1:7310` or the next free port after it, refusing any request a web page sends, and reports the URL to connect. `messageBoxConfirm(Utils.showMessageBox)` puts a `@confirm` command to the person with the native dialog, Decline by default. The screen tools are not offered there, since the screen is in each window's render worker.
+
+  Electrobun bundles the main process with its own build, which takes no plugins, so `gesso-vite-plugin` now ships `gesso-channels`, a command that reads contracts with the same TypeScript 7 checker and writes a module describing them, for the main process to import once; `--check` fails when it is out of date.
+
+  The Electrobun template uses all of it: the counter is served to agents as the app starts, `hutch run channels` writes `src/shared/channels.described.ts` before every build, `hutch run typecheck` checks it is current, and the contract's JSDoc is written for an agent to read. The template moves to TypeScript 7, clearing the projected config's `baseUrl`, which TypeScript 7 removed, and to Vite 8, with `vite.config.ts` using `import.meta.dirname` and an explicit `.ts` import as Vite 8's config loader asks.
+
+- cf3b16a: `createApp({ webmcp: true })` offers an application's channels to an AI agent in the browser through WebMCP. Once the app mounts, every tool the agent surface offers, a view tool per channel and a tool per command, is registered with `document.modelContext.registerTool` (or the older `navigator.modelContext`), and removed when the app is disposed. View tools carry `readOnlyHint`, `@destructive` commands carry `consequentialHint`, a call answers with the view it left or rejects with the sentence that says why, and a `@confirm` command is put to the person with `window.confirm` unless `webmcp: { confirm }` supplies the application's own dialog. In a browser without WebMCP nothing is registered and nothing fails. The code loads on demand, so the shell is no bigger for an app that does not ask.
+
+  `gesso-framework/agent` adds `registerWebMcpTools`, `connectWebMcp`, `pageModelContext` and `confirmInWindow`. `gesso-vite-plugin` turns `webmcp` on in a dev server; the app's own setting still decides.
+
+### Patch Changes
+
+- 4624080: Dependencies resolve their `worker` build ahead of their `browser` one. Application code runs in workers, and a package's browser build may reach for `document`: every markdown parser built on micromark imports `decode-named-character-reference`, whose browser build does, and a render worker that imported one died on start with "document is not defined". Pass `workerConditions: false` to resolve as Vite does by default.
+- f3a9544: Workers are built as ES modules, matching the module workers the plugin constructs, so a dynamic import in a worker becomes a chunk loaded when it runs instead of being inlined into the worker. Vite's default, IIFE, cannot split. An application that sets `worker.format` keeps its choice.
+
 ## 0.4.2
 
 ## 0.4.1

package/README.md

@@ -33,6 +33,10 @@ Nothing in `gesso-core` or `gesso-framework` mentions Vite, and no bundler is im
 
 One failure looks exactly like a bug in the framework: a save that reloads the whole page instead of replacing a module. The cause is a module reached from the main thread as well as from the render worker, which Vite cannot hot-replace because it propagates the invalidation to a main-thread importer that does not accept it. The plugin says so, and names the module, instead of leaving you to guess.
 
+## Channels an agent can read
+
+A channel contract is types and comments, and both are gone at run time. The plugin reads each contract with TypeScript 7's checker and attaches a JSON Schema of the view and every command to the token, with descriptions taken from your JSDoc, so `channelSchema(token)` can tell an AI agent what the application holds and what it can be asked to do. `channelSchemas: false` turns it off.
+
 ## Documentation
 
 [The Vite plugin](https://gesso-docs.vercel.app/tooling/vite-plugin)

package/dist/gesso-channels.mjs

@@ -0,0 +1,530 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+//#region src/contracts.ts
+/**
+* A module that describes channels when it is imported, for a bundle
+* this plugin never sees.
+*
+* The plugin describes a contract by appending to it as Vite bundles
+* it. An Electrobun main process is bundled by Electrobun's own build,
+* which takes no plugins, so there the description is written ahead of
+* time instead: `gesso-channels` reads the contracts with the same
+* checker and writes this module, and the main process imports it once.
+* A token is imported from its contract, so the schema lands on the
+* same object the application serves.
+*
+* `outFile` and every `file` are absolute POSIX paths.
+*/
+function describedModule(contracts, outFile) {
+	const lines = [
+		"// Written by gesso-channels from the channel contracts it names below.",
+		"// Run it again after changing a contract rather than editing this file.",
+		"import { describeChannel } from 'gesso-framework';"
+	];
+	const from = outFile.slice(0, outFile.lastIndexOf("/"));
+	for (const contract of contracts) if (contract.channels.size > 0) {
+		const names = [...contract.channels.keys()].join(", ");
+		lines.push(`import { ${names} } from '${importPath(from, contract.file)}';`);
+	}
+	for (const contract of contracts) for (const [name, schema] of contract.channels) lines.push("", `describeChannel(${name}, ${JSON.stringify(schema, null, 2)});`);
+	return `${lines.join("\n")}\n`;
+}
+/** `./Counter` from `/app/src/shared` to `/app/src/shared/Counter.ts`, without the extension. */
+function importPath(fromDir, file) {
+	const from = fromDir.split("/").filter(Boolean);
+	const to = file.replace(/\.[cm]?[jt]sx?$/, "").split("/").filter(Boolean);
+	let shared = 0;
+	while (shared < from.length && shared < to.length - 1 && from[shared] === to[shared]) shared++;
+	const up = from.length - shared;
+	const rest = to.slice(shared).join("/");
+	return up === 0 ? `./${rest}` : `${"../".repeat(up)}${rest}`;
+}
+/**
+* The checker, held open across reads.
+*
+* Spawning it and loading a project costs about a hundred
+* milliseconds; a question after that costs well under one. So one
+* reader lives as long as the dev server or the build, is told which
+* files changed between reads, and is closed at the end, because the
+* process it holds would otherwise keep the build from exiting.
+*/
+var ContractReader = class {
+	api = null;
+	changed = /* @__PURE__ */ new Set();
+	/** Each contract's tsconfig, found once. */
+	configs = /* @__PURE__ */ new Map();
+	/**
+	* @param fs Callbacks the checker reads through before the disk, for
+	*   a spec that keeps its project in memory.
+	*/
+	ts;
+	cwd;
+	fs;
+	constructor(ts, cwd, fs) {
+		this.ts = ts;
+		this.cwd = cwd;
+		this.fs = fs;
+	}
+	/** A file changed on disk since the last read. */
+	invalidate(file) {
+		this.changed.add(file);
+	}
+	/** Every channel `file` exports, described. */
+	read(file) {
+		const api = this.api ??= new this.ts.API({
+			cwd: this.cwd,
+			...this.fs === void 0 ? {} : { fs: this.fs }
+		});
+		this.changed.add(file);
+		let snapshot = api.updateSnapshot({ fileChanges: { changed: [...this.changed] } });
+		this.changed.clear();
+		let config = this.configs.get(file);
+		if (config === void 0) {
+			config = api.updateSnapshot({ openFiles: [file] }).getDefaultProjectForFile(file)?.configFileName;
+			snapshot = api.updateSnapshot({
+				...config === void 0 ? {} : { openProjects: [config] },
+				closeFiles: [file]
+			});
+			if (config !== void 0) this.configs.set(file, config);
+		}
+		const project = config === void 0 ? void 0 : snapshot.getProject(config);
+		const source = project?.program.getSourceFile(file);
+		if (project === void 0 || source === void 0) return {
+			channels: /* @__PURE__ */ new Map(),
+			warnings: [`TypeScript has no project that includes ${file}.`]
+		};
+		const checker = project.checker;
+		const module = checker.getSymbolAtLocation(source);
+		const describer = new Describer(this.ts, checker);
+		const channels = /* @__PURE__ */ new Map();
+		for (const exported of module === void 0 ? [] : checker.getExportsOfModule(module)) {
+			const type = checker.getTypeOfSymbol(exported);
+			if (type === void 0 || type.getSymbol()?.name !== "ChannelToken") continue;
+			const [view, commands] = checker.getTypeArguments(type);
+			channels.set(exported.name, describer.channel(exported, view, commands));
+		}
+		return {
+			channels,
+			warnings: describer.warnings
+		};
+	}
+	close() {
+		this.api?.close();
+		this.api = null;
+	}
+};
+/**
+* Library types that are objects to the checker and not plain data to
+* a channel. They compare by reference, so `provide` rejects them on
+* their first value; describing their methods as properties would be
+* describing something that never arrives.
+*/
+const NOT_PLAIN = /* @__PURE__ */ new Set([
+	"Date",
+	"Map",
+	"ReadonlyMap",
+	"Set",
+	"ReadonlySet",
+	"WeakMap",
+	"WeakSet",
+	"Promise",
+	"RegExp",
+	"Error",
+	"ArrayBuffer",
+	"SharedArrayBuffer",
+	"DataView",
+	"Blob",
+	"File",
+	"URL",
+	"Int8Array",
+	"Uint8Array",
+	"Uint8ClampedArray",
+	"Int16Array",
+	"Uint16Array",
+	"Int32Array",
+	"Uint32Array",
+	"Float32Array",
+	"Float64Array",
+	"BigInt64Array",
+	"BigUint64Array"
+]);
+/**
+* Bytes, which a command may carry and a view key may not.
+*
+* A command's argument is structured-cloned onto the owning thread, and
+* a typed array or an `ArrayBuffer` clones as itself: a file a person
+* dropped crosses as its bytes, with no encoding pass on the render
+* thread. A view key is diffed, and a differ that compares bytes by
+* reference reports a change on every emission, so there they stay
+* unplain. In a command's schema they are a base64 string, which is
+* what an agent can write, tagged with the type the command expects so
+* the agent surface can turn the string back into it.
+*/
+const BINARY = /* @__PURE__ */ new Set([
+	"ArrayBuffer",
+	"Int8Array",
+	"Uint8Array",
+	"Uint8ClampedArray",
+	"Int16Array",
+	"Uint16Array",
+	"Int32Array",
+	"Uint32Array",
+	"Float32Array",
+	"Float64Array",
+	"BigInt64Array",
+	"BigUint64Array"
+]);
+/** Turns checker types into JSON Schema for one module's channels. */
+var Describer = class {
+	warnings = [];
+	flags;
+	/** Describing a command's parameters, where bytes are allowed; see `BINARY`. */
+	inCommand = false;
+	/** Types being described right now, to notice a type that contains itself. */
+	inProgress = /* @__PURE__ */ new Set();
+	/** Types found to contain themselves, which are described once in `$defs`. */
+	recursive = /* @__PURE__ */ new Set();
+	/** `$defs` for the schema being built. Reset per root, so each schema stands alone. */
+	defs = /* @__PURE__ */ new Map();
+	defNames = /* @__PURE__ */ new Map();
+	ts;
+	checker;
+	constructor(ts, checker) {
+		this.ts = ts;
+		this.checker = checker;
+		this.flags = ts.TypeFlags;
+	}
+	channel(token, view, commands) {
+		const out = {
+			view: this.root(view, `${token.name}.view`),
+			commands: {}
+		};
+		const description = this.checker.getDocumentationCommentOfSymbol(token);
+		if (description !== "") out.description = description;
+		if (commands !== void 0) for (const command of this.checker.getPropertiesOfType(commands)) {
+			const described = this.command(command, `${token.name}.commands.${command.name}`);
+			if (described !== null) out.commands[command.name] = described;
+		}
+		return out;
+	}
+	/** A schema that stands alone: its own `$defs`, if anything in it recurs. */
+	root(type, path) {
+		this.defs = /* @__PURE__ */ new Map();
+		const schema = this.describe(type, path);
+		if (this.defs.size > 0) return {
+			...schema,
+			$defs: Object.fromEntries(this.defs)
+		};
+		return schema;
+	}
+	command(symbol, path) {
+		const type = this.checker.getTypeOfSymbol(symbol);
+		const signatures = type === void 0 ? [] : this.checker.getSignaturesOfType(type, this.ts.SignatureKind.Call);
+		if (signatures.length === 0) {
+			this.warnings.push(`${path} is not a function, so it is not a command an agent can send.`);
+			return null;
+		}
+		if (signatures.length > 1) this.warnings.push(`${path} is overloaded; only its first signature is described.`);
+		const signature = signatures[0];
+		const tags = this.checker.getJsDocTagsOfSymbol(symbol);
+		const parameters = signature.getParameters();
+		this.defs = /* @__PURE__ */ new Map();
+		const properties = {};
+		const required = [];
+		this.inCommand = true;
+		parameters.forEach((parameter, index) => {
+			const parameterType = this.checker.getTypeOfSymbol(parameter);
+			const optional = parameterType !== void 0 && this.includesUndefined(parameterType);
+			const schema = parameterType === void 0 ? {} : this.describe(parameterType, `${path}(${parameter.name})`);
+			const description = this.parameterDescription(parameter, tags);
+			properties[parameter.name] = description === "" ? schema : {
+				...schema,
+				description
+			};
+			const rest = signature.hasRestParameter && index === parameters.length - 1;
+			if (!optional && !rest) required.push(parameter.name);
+		});
+		this.inCommand = false;
+		const input = {
+			type: "object",
+			properties,
+			additionalProperties: false
+		};
+		if (required.length > 0) input.required = required;
+		if (this.defs.size > 0) input.$defs = Object.fromEntries(this.defs);
+		const out = {
+			parameters: parameters.map((parameter) => parameter.name),
+			input
+		};
+		const description = this.checker.getDocumentationCommentOfSymbol(symbol);
+		if (description !== "") out.description = description;
+		if (signature.hasRestParameter) out.rest = true;
+		for (const annotation of [
+			"destructive",
+			"idempotent",
+			"confirm",
+			"hidden"
+		]) if (tags.some((tag) => tag.name === annotation)) out[annotation] = true;
+		return out;
+	}
+	/**
+	* A parameter's own comment, or failing that its `@param` line.
+	*
+	* The checker attaches `@param` text to the parameter of a method
+	* signature. A command written as a property, `move: (from: number)
+	* => void`, keeps its comment on the property, so the tag is read
+	* from there instead.
+	*/
+	parameterDescription(parameter, tags) {
+		const own = this.checker.getDocumentationCommentOfSymbol(parameter);
+		if (own !== "") return own;
+		for (const tag of tags) {
+			const match = tag.name === "param" ? /^\s*(\S+)\s*(?:-\s*)?([\s\S]*)$/.exec(tag.text ?? "") : null;
+			if (match !== null && match[1] === parameter.name) return match[2].trim();
+		}
+		return "";
+	}
+	includesUndefined(type) {
+		const { Undefined, Void } = this.flags;
+		if (type.isUnionType()) return (type.getTypes() ?? []).some((member) => (member.flags & (Undefined | Void)) !== 0);
+		return (type.flags & (Undefined | Void)) !== 0;
+	}
+	describe(type, path) {
+		const f = this.flags;
+		const flags = type.flags;
+		if (flags & (f.Any | f.Unknown)) return {};
+		if (flags & f.Never) {
+			this.warnings.push(`${path} is never, which describes no value. An empty array literal is never[] unless it says what it holds: write \`[] as Row[]\`.`);
+			return { not: {} };
+		}
+		if (flags & (f.String | f.TemplateLiteral | f.StringMapping)) return { type: "string" };
+		if (flags & f.Number) return { type: "number" };
+		if (flags & f.Boolean) return { type: "boolean" };
+		if (flags & f.Null) return { type: "null" };
+		if (flags & (f.Undefined | f.Void)) return {};
+		if (flags & f.BooleanLiteral) return { const: type.intrinsicName === "true" };
+		if (flags & (f.StringLiteral | f.NumberLiteral)) return { const: type.value };
+		if (flags & (f.BigInt | f.BigIntLiteral | f.ESSymbol | f.UniqueESSymbol)) return this.unplain(path, flags & f.BigIntLike ? "a bigint" : "a symbol");
+		if (type.isUnionType()) return this.union(type, path);
+		if (flags & f.TypeParameter) return {};
+		if (flags & (f.Object | f.Intersection)) {
+			if (this.checker.isArrayType(type)) {
+				const [element] = this.checker.getTypeArguments(type);
+				return {
+					type: "array",
+					items: element === void 0 ? {} : this.describe(element, `${path}[]`)
+				};
+			}
+			if (this.checker.isTupleType(type)) return this.tuple(type, path);
+			return this.named(type, path);
+		}
+		this.warnings.push(`${path} has a type this reader does not describe, so it is left open.`);
+		return {};
+	}
+	/**
+	* A union, with `undefined` taken out (optionality is said by
+	* `required`), `true | false` folded back into `boolean`, and a union
+	* of nothing but literals written as an `enum`.
+	*/
+	union(type, path) {
+		const f = this.flags;
+		let members = (type.getTypes() ?? []).filter((member) => (member.flags & (f.Undefined | f.Void)) === 0);
+		const booleans = members.filter((member) => member.flags & f.BooleanLiteral);
+		const schemas = [];
+		if (booleans.length === 2) {
+			members = members.filter((member) => !(member.flags & f.BooleanLiteral));
+			schemas.push({ type: "boolean" });
+		}
+		if (members.length > 0 && schemas.length === 0 && members.every((member) => member.flags & (f.StringLiteral | f.NumberLiteral))) return { enum: members.map((member) => member.value) };
+		members.sort((a, b) => Number((a.flags & f.Null) !== 0) - Number((b.flags & f.Null) !== 0));
+		schemas.push(...members.map((member) => this.describe(member, path)));
+		return schemas.length === 1 ? schemas[0] : { anyOf: schemas };
+	}
+	/**
+	* An object type, described once however often it appears, and by
+	* reference when it contains itself.
+	*/
+	named(type, path) {
+		const id = type.id;
+		if (this.inProgress.has(id)) {
+			this.recursive.add(id);
+			return { $ref: `#/$defs/${this.defName(type)}` };
+		}
+		this.inProgress.add(id);
+		const schema = this.object(type, path);
+		this.inProgress.delete(id);
+		if (this.recursive.has(id)) {
+			const name = this.defName(type);
+			this.defs.set(name, schema);
+			return { $ref: `#/$defs/${name}` };
+		}
+		return schema;
+	}
+	defName(type) {
+		let name = this.defNames.get(type.id);
+		if (name === void 0) {
+			const base = (type.getAliasSymbol() ?? type.getSymbol())?.name ?? "Type";
+			name = new Set(this.defNames.values()).has(base) ? `${base}${type.id}` : base;
+			this.defNames.set(type.id, name);
+		}
+		return name;
+	}
+	object(type, path) {
+		const checker = this.checker;
+		const symbolName = type.getSymbol()?.name;
+		if (symbolName !== void 0 && this.inCommand && BINARY.has(symbolName)) return {
+			type: "string",
+			contentEncoding: "base64",
+			"x-gesso-binary": symbolName
+		};
+		if (symbolName !== void 0 && NOT_PLAIN.has(symbolName)) return this.unplain(path, `a ${symbolName}`);
+		if (type.objectFlags & this.ts.ObjectFlags.Class) return this.unplain(path, `an instance of ${symbolName ?? "a class"}`);
+		if (checker.getSignaturesOfType(type, this.ts.SignatureKind.Call).length > 0) return this.unplain(path, "a function");
+		const properties = {};
+		const required = [];
+		for (const property of checker.getPropertiesOfType(type)) {
+			const propertyType = checker.getTypeOfSymbol(property);
+			const at = `${path}.${property.name}`;
+			if (propertyType === void 0) {
+				properties[property.name] = {};
+				continue;
+			}
+			const schema = this.describe(propertyType, at);
+			const description = checker.getDocumentationCommentOfSymbol(property);
+			properties[property.name] = description === "" ? schema : {
+				...schema,
+				description
+			};
+			if (!((property.flags & this.ts.SymbolFlags.Optional) !== 0 || this.includesUndefined(propertyType))) required.push(property.name);
+		}
+		const schema = {
+			type: "object",
+			properties
+		};
+		if (required.length > 0) schema.required = required;
+		const index = checker.getIndexInfosOfType(type).find((info) => info.keyType.flags & this.flags.String);
+		if (index !== void 0) schema.additionalProperties = this.describe(index.valueType, `${path}[key]`);
+		return schema;
+	}
+	tuple(type, path) {
+		const elements = this.checker.getTypeArguments(type);
+		const elementFlags = type.getTarget().elementFlags ?? [];
+		const { Required, Rest } = this.ts.ElementFlags;
+		const prefixItems = [];
+		let items = false;
+		let minItems = 0;
+		elements.forEach((element, index) => {
+			const schema = this.describe(element, `${path}[${index}]`);
+			if (elementFlags[index] & Rest) items = schema;
+			else {
+				prefixItems.push(schema);
+				if (elementFlags[index] & Required) minItems = index + 1;
+			}
+		});
+		return {
+			type: "array",
+			prefixItems,
+			items,
+			minItems
+		};
+	}
+	unplain(path, what) {
+		this.warnings.push(`${path} is ${what}, which is not plain data and cannot cross a channel.`);
+		return {};
+	}
+};
+//#endregion
+//#region bin/gesso-channels.ts
+/**
+* `gesso-channels`: describes channel contracts for a bundle Vite does
+* not build.
+*
+*   gesso-channels src/shared/Counter.ts --out src/shared/channels.described.ts
+*   gesso-channels src/shared/*.ts --out src/shared/channels.described.ts --check
+*
+* `gesso-vite-plugin` describes a contract as Vite bundles it. An
+* Electrobun main process is bundled by Electrobun's own build, which
+* takes no plugins, so its channels would reach an agent undescribed:
+* no descriptions, and arguments as a positional list. This reads the
+* same contracts with the same checker and writes a module that
+* describes them when imported; the main process imports it once.
+*
+* `--check` writes nothing and fails when the module on disk is not
+* what it would write, for a gate that wants to know a contract
+* changed without the module following.
+*
+* It needs TypeScript 7 in the project, whose checker does the reading.
+*/
+const USAGE = `Usage: gesso-channels <contract.ts>... --out <file> [--check]
+
+Writes a module that attaches a JSON Schema to every channel the
+contracts export, for a bundle gesso-vite-plugin does not build, such as
+an Electrobun main process. Import the module once from that bundle.
+
+  --out <file>  Where to write the module.
+  --check       Write nothing; fail if the module is out of date.
+`;
+function fail(message) {
+	console.error(message);
+	process.exit(1);
+}
+async function main() {
+	const args = process.argv.slice(2);
+	const files = [];
+	let out;
+	let check = false;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--out") out = args[++i];
+		else if (arg === "--check") check = true;
+		else if (arg === "-h" || arg === "--help") {
+			console.log(USAGE);
+			return;
+		} else if (arg.startsWith("-")) fail(`Unknown option ${arg}.\n\n${USAGE}`);
+		else files.push(arg);
+	}
+	if (out === void 0 || files.length === 0) fail(USAGE);
+	let ts;
+	try {
+		ts = await import("typescript/unstable/sync");
+	} catch {
+		fail("gesso-channels needs TypeScript 7 or later in the project: npm install --save-dev typescript@^7.");
+	}
+	const cwd = realpathSync(process.cwd());
+	const outFile = resolve(realpathSync(dirname(resolve(cwd, out))), out.split(/[\\/]/).pop());
+	const reader = new ContractReader(ts, cwd);
+	const contracts = [];
+	let warned = false;
+	try {
+		for (const file of files) {
+			const path = realpathSync(resolve(cwd, file));
+			const reading = reader.read(path);
+			for (const warning of reading.warnings) {
+				console.warn(`gesso-channels: ${warning}`);
+				warned = true;
+			}
+			contracts.push({
+				file: path,
+				channels: reading.channels
+			});
+		}
+	} finally {
+		reader.close();
+	}
+	const described = contracts.reduce((count, contract) => count + contract.channels.size, 0);
+	if (described === 0) fail(`None of ${files.join(", ")} exports a channel.`);
+	const module = describedModule(contracts, outFile);
+	if (check) {
+		if ((existsSync(outFile) ? readFileSync(outFile, "utf8") : null) !== module) fail(`${out} is out of date. Run gesso-channels without --check to write it.`);
+		console.log(`${out} describes ${described} channel${described === 1 ? "" : "s"} and is current.`);
+		return;
+	}
+	writeFileSync(outFile, module);
+	console.log(`Wrote ${out}: ${described} channel${described === 1 ? "" : "s"} described${warned ? ", with warnings above" : ""}.`);
+}
+main();
+//#endregion
+export {};
+
+//# sourceMappingURL=gesso-channels.mjs.map