@lantharos/pult 0.8.0 → 0.9.0

package/cli.mjs

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import { C as HEADER, D as sign, E as parseKey, P as findActionDef, S as kindOf, _ as normalizeFilter, a as collect, c as guards, h as isPendingAttachment, i as validate, k as eachBlock, r as toJsonSchema } from "./schema-CzG8J_9_.mjs";
+import { C as traceOrigins, L as findActionDef, M as valuesIn, S as kindOf, _ as normalizeFilter, a as collect, c as guards, d as Transport, h as hasPendingAttachments, i as validate, j as shownValue, k as eachBlock, r as toJsonSchema, x as humanize } from "./schema-DuTVNptF.mjs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs, styleText } from "node:util";
 import { Cron } from "croner";
 import { existsSync, readFileSync, watch } from "node:fs";
 import { glob, mkdir, readFile, writeFile } from "node:fs/promises";
 import net from "node:net";
-import { join, relative } from "node:path";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 //#region ../protocol/src/diff.ts
-function keyed(label, before, after, inner, prefix = "") {
+function keyed(label, before, after, nested, prefix = "") {
 	const changes = [];
 	for (const name of Object.keys(after)) if (!(name in before)) changes.push({
 		kind: "add",
@@ -24,24 +24,30 @@ function keyed(label, before, after, inner, prefix = "") {
 		const a = before[name];
 		const b = after[name];
 		if (!a || !b) continue;
-		const nested = inner?.(name, a, b) ?? [];
-		if (nested.length) changes.push(...nested);
-		else if (!sameShape(a, b)) changes.push({
+		if (nested) changes.push(...nested.diff(name, a, b));
+		if (!sameShape(a, b, nested?.covers)) changes.push({
 			kind: "change",
 			text: `changes ${label} ${prefix}${name}`
 		});
 	}
 	return changes;
 }
-function sameShape(a, b) {
-	return stableJson(a, ["source"]) === stableJson(b, ["source"]);
+function sameShape(a, b, covers = []) {
+	return shape(a, covers) === shape(b, covers);
 }
-function stableJson(value, omit = []) {
-	return JSON.stringify(value, (key, inner) => {
-		if (omit.includes(key)) return void 0;
-		if (inner && typeof inner === "object" && !Array.isArray(inner)) return Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b)));
-		return inner;
-	});
+function shape(definition, covers) {
+	const rest = {
+		...definition,
+		source: void 0
+	};
+	for (const key of covers) rest[key] = void 0;
+	return stableJson(rest);
+}
+function stableJson(value) {
+	return JSON.stringify(value, (_, inner) => inner && typeof inner === "object" && !Array.isArray(inner) ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b))) : inner);
+}
+function byName(spaces) {
+	return Object.fromEntries(spaces.map((space) => [space.name, space]));
 }
 function listDelta(subject, verb, before, after) {
 	return [...after.filter((x) => !before.includes(x)).map((x) => ({
@@ -52,6 +58,40 @@ function listDelta(subject, verb, before, after) {
 		text: `${subject} ${verb[1]} ${x}`
 	}))];
 }
+function toggled(before, after, text, kind) {
+	if (before === after) return [];
+	return [{
+		kind: kind ?? (after ? "grant" : "revoke"),
+		text: text(after)
+	}];
+}
+function delivery(target) {
+	return target.mode === "socket" ? "over a socket" : `to ${target.path}`;
+}
+function projectChanges(before, after) {
+	return [
+		...before.project !== after.project ? [{
+			kind: "change",
+			text: `moves from project ${before.project} to ${after.project}`
+		}] : [],
+		...after.environments.filter((name) => !before.environments.includes(name)).map((name) => ({
+			kind: "add",
+			text: `adds environment ${name}`
+		})),
+		...before.environments.filter((name) => !after.environments.includes(name)).map((name) => ({
+			kind: "remove",
+			text: `removes environment ${name}`
+		})),
+		...before.sync !== after.sync ? [{
+			kind: "change",
+			text: `${after.sync} follows your code instead of ${before.sync}`
+		}] : [],
+		...stableJson(before.delivery) !== stableJson(after.delivery) ? [{
+			kind: "change",
+			text: `sends requests ${delivery(after.delivery)} instead of ${delivery(before.delivery)}`
+		}] : []
+	];
+}
 function diffManifests(before, after) {
 	const base = before ?? {
 		...after,
@@ -62,83 +102,90 @@ function diffManifests(before, after) {
 		pages: {},
 		flags: {},
 		roles: {},
+		spaces: [],
 		notify: {},
 		status: null
 	};
 	return [
+		...projectChanges(base, after),
 		...keyed("status component", base.status?.components ?? {}, after.status?.components ?? {}),
-		...base.status && after.status && !sameShape({
-			...base.status,
-			components: null
-		}, {
-			...after.status,
-			components: null
-		}) ? [{
+		...base.status && after.status && !sameShape(base.status, after.status, ["components"]) ? [{
 			kind: "change",
 			text: "changes the status page"
 		}] : [],
-		...keyed("resource", base.resources, after.resources, (name, a, b) => {
-			const actions = keyed("action", a.actions, b.actions, actionChanges(`${name}.`), `${name}.`);
-			return [...sameShape({
-				...a,
-				actions: null
-			}, {
-				...b,
-				actions: null
-			}) ? [] : [{
-				kind: "change",
-				text: `changes resource ${name}`
-			}], ...actions];
+		...keyed("resource", base.resources, after.resources, {
+			covers: ["actions"],
+			diff: (name, a, b) => keyed("action", a.actions, b.actions, actionChanges(`${name}.`), `${name}.`)
 		}),
 		...keyed("action", base.actions, after.actions, actionChanges("")),
 		...keyed("inbox", base.inboxes, after.inboxes),
 		...keyed("view", base.views, after.views),
 		...keyed("page", base.pages, after.pages),
-		...keyed("flag", base.flags, after.flags, (name, a, b) => a.approval !== b.approval ? [{
-			kind: "change",
-			text: `flag ${name} ${b.approval ? "now needs" : "no longer needs"} a second approver`
-		}] : []),
+		...keyed("flag", base.flags, after.flags, flagChanges),
+		...keyed("space", byName(base.spaces), byName(after.spaces)),
 		...keyed("notification", base.notify, after.notify),
-		...keyed("role", base.roles, after.roles, (name, a, b) => {
-			const role = `role ${name}`;
-			return [
-				...listDelta(role, ["gains", "loses"], a.actions, b.actions),
-				...listDelta(role, ["sees inbox", "no longer sees inbox"], a.inboxes, b.inboxes),
-				...listDelta(role, ["sees resource", "no longer sees resource"], a.resources, b.resources),
-				...listDelta(role, ["sees page", "no longer sees page"], a.pages, b.pages),
-				...listDelta(role, ["can change flag", "can no longer change flag"], a.flags, b.flags),
-				...a.status !== b.status ? [{
-					kind: b.status ? "grant" : "revoke",
-					text: `${role} ${b.status ? "can" : "can no longer"} post to the status page`
-				}] : [],
-				...a.reveal !== b.reveal ? [{
-					kind: b.reveal ? "grant" : "revoke",
-					text: `${role} ${b.reveal ? "can" : "can no longer"} reveal sensitive fields`
-				}] : []
-			];
-		})
+		...keyed("role", base.roles, after.roles, roleChanges)
 	];
 }
-function actionChanges(prefix) {
-	return (name, a, b) => {
-		const action = `action ${prefix}${name}`;
+const flagChanges = {
+	covers: ["danger", "approval"],
+	diff: (name, a, b) => [...a.danger !== b.danger ? [{
+		kind: "change",
+		text: `flag ${name} danger ${a.danger} → ${b.danger}`
+	}] : [], ...toggled(a.approval, b.approval, (now) => `flag ${name} ${now ? "now needs" : "no longer needs"} a second approver`, "change")]
+};
+const roleChanges = {
+	covers: [
+		"actions",
+		"inboxes",
+		"resources",
+		"pages",
+		"flags",
+		"status",
+		"reveal"
+	],
+	diff: (name, a, b) => {
+		const role = `role ${name}`;
 		return [
-			...a.danger !== b.danger ? [{
-				kind: "change",
-				text: `${action} danger ${a.danger} → ${b.danger}`
-			}] : [],
-			...a.approval !== b.approval ? [{
-				kind: "change",
-				text: `${action} ${b.approval ? "now needs" : "no longer needs"} a second approver`
-			}] : [],
-			...a.schedule?.cron !== b.schedule?.cron ? [{
-				kind: "change",
-				text: b.schedule ? `${action} runs on "${b.schedule.cron}"` : `${action} no longer runs on a schedule`
-			}] : []
+			...listDelta(role, ["gains", "loses"], a.actions, b.actions),
+			...listDelta(role, ["sees inbox", "no longer sees inbox"], a.inboxes, b.inboxes),
+			...listDelta(role, ["sees resource", "no longer sees resource"], a.resources, b.resources),
+			...listDelta(role, ["sees page", "no longer sees page"], a.pages, b.pages),
+			...listDelta(role, ["can change flag", "can no longer change flag"], a.flags, b.flags),
+			...toggled(a.status, b.status, (now) => `${role} ${now ? "can" : "can no longer"} post to the status page`),
+			...toggled(a.reveal, b.reveal, (now) => `${role} ${now ? "can" : "can no longer"} reveal sensitive fields`)
 		];
+	}
+};
+function actionChanges(prefix) {
+	return {
+		covers: [
+			"danger",
+			"approval",
+			"automatable",
+			"schedule"
+		],
+		diff: (name, a, b) => {
+			const action = `action ${prefix}${name}`;
+			return [
+				...a.danger !== b.danger ? [{
+					kind: "change",
+					text: `${action} danger ${a.danger} → ${b.danger}`
+				}] : [],
+				...toggled(a.approval, b.approval, (now) => `${action} ${now ? "now needs" : "no longer needs"} a second approver`, "change"),
+				...toggled(a.automatable, b.automatable, (now) => `triage ${now ? "can now" : "can no longer"} run ${action} on its own`),
+				...stableJson(a.schedule) !== stableJson(b.schedule) ? [{
+					kind: "change",
+					text: b.schedule ? `${action} runs on "${b.schedule.cron}"${b.schedule.timezone ? ` in ${b.schedule.timezone}` : ""}` : `${action} no longer runs on a schedule`
+				}] : []
+			];
+		}
 	};
 }
 //#endregion
+//#region package.json
+var version = "0.9.0";
+//#endregion
 //#region ../protocol/src/checks.ts
 const COLUMNS = [
 	"title",
@@ -151,6 +198,59 @@ const COLUMNS = [
 	"tags",
 	"due"
 ];
+function checkSpaces(manifest, problems) {
+	if (!manifest.spaces.length) return;
+	const homes = new Set(manifest.spaces.map((space) => space.home));
+	const sections = [
+		[
+			"inbox",
+			"inboxes",
+			manifest.inboxes
+		],
+		[
+			"resource",
+			"resources",
+			manifest.resources
+		],
+		[
+			"page",
+			"pages",
+			manifest.pages
+		],
+		[
+			"flag",
+			"flags",
+			manifest.flags
+		]
+	];
+	for (const space of manifest.spaces) {
+		if (space.home && !manifest.pages[space.home]) problems.push({
+			source: space.source,
+			message: `home is unknown page "${space.home}"`
+		});
+		for (const [kind, key, defined] of sections) for (const name of space[key]) if (!defined[name]) problems.push({
+			source: space.source,
+			message: `lists unknown ${kind} "${name}"`
+		});
+		else if (kind === "page" && (name === "home" || homes.has(name))) problems.push({
+			source: space.source,
+			message: `lists page "${name}", which is already a home`
+		});
+	}
+	const navigable = (kind, name) => {
+		if (kind === "page") return name !== "home" && !homes.has(name);
+		if (kind === "resource") return manifest.resources[name].searchable || Boolean(manifest.resources[name].list);
+		return true;
+	};
+	for (const [kind, key, defined] of sections) for (const [name, def] of Object.entries(defined)) {
+		if (!navigable(kind, name)) continue;
+		if (manifest.spaces.some((space) => space[key].includes(name))) continue;
+		problems.push({
+			source: def.source,
+			message: `${kind} ${name} isn't in any space, so only search reaches it`
+		});
+	}
+}
 function checkColumns(source, inbox, columns, problems) {
 	for (const column of columns) {
 		if (COLUMNS.includes(column)) continue;
@@ -174,11 +274,21 @@ function checkManifest(manifest) {
 	}
 	for (const [name, page] of Object.entries(manifest.pages)) if (page.blocks) checkBlocks(manifest, page.source, `page ${name}`, page.blocks, problems);
 	if (manifest.status) checkStatus(manifest, problems);
-	for (const [name, flag] of Object.entries(manifest.flags)) if (flag.target && !manifest.resources[flag.target]) problems.push({
-		source: flag.source,
-		message: `flag ${name} targets unknown resource "${flag.target}"`
-	});
+	for (const [name, flag] of Object.entries(manifest.flags)) {
+		if (flag.target && !manifest.resources[flag.target]) problems.push({
+			source: flag.source,
+			message: `flag ${name} targets unknown resource "${flag.target}"`
+		});
+		for (const guard of flag.guards) if (!(guard.perHour >= 1)) problems.push({
+			source: flag.source,
+			message: `flag ${name} guards ${guard.inbox} with perHour ${guard.perHour}. Use 1 or more.`
+		});
+	}
 	for (const [name, resource] of Object.entries(manifest.resources)) {
+		if (name.includes(".")) problems.push({
+			source: resource.source,
+			message: `resource "${name}" can't contain "."`
+		});
 		for (const [relation, def] of Object.entries(resource.related)) if (!manifest.resources[def.resource]) problems.push({
 			source: resource.source,
 			message: `${name}.${relation} points at unknown resource "${def.resource}"`
@@ -228,8 +338,14 @@ function checkManifest(manifest) {
 				source: inbox.source,
 				message: `triage runs ${decision.action}, which needs a human (danger "${def.danger}"). Set automatable: true on the action to allow it.`
 			});
+			const missing = (def?.input?.required ?? []).filter((field) => !(field in (decision.input ?? {})));
+			if (missing.length) problems.push({
+				source: inbox.source,
+				message: `triage runs ${decision.action} without ${missing.join(", ")}, which it needs as input`
+			});
 		}
 	}
+	checkSpaces(manifest, problems);
 	for (const view of Object.values(manifest.views)) {
 		const inbox = manifest.inboxes[view.inbox];
 		checkColumns(view.source, inbox, view.columns, problems);
@@ -295,16 +411,23 @@ function checkBlocks(manifest, source, owner, blocks, problems) {
 	const action = (id) => {
 		if (!findActionDef(manifest, id)) problem(`uses unknown action ${id}`);
 	};
+	const resource = (name) => {
+		if (!manifest.resources[name]) problem(`shows unknown resource ${name}`);
+	};
+	const value = (field) => {
+		if (field && typeof field === "object" && "edit" in field) action(field.edit.action);
+		const shown = shownValue(field);
+		if (shown && typeof shown === "object" && "record" in shown) resource(shown.record.resource);
+	};
 	eachBlock(blocks, (block) => {
 		if (block.type === "actions") for (const button of block.actions) action(button.action);
 		if (block.type === "form") action(block.form.action);
+		if (block.type === "record") resource(block.ref.resource);
 		if (block.type === "flag" && !manifest.flags[block.flag]) problem(`shows unknown flag ${block.flag}`);
 		if ((block.type === "count" || block.type === "items" || block.type === "chart") && "inbox" in block) {
 			if (!manifest.inboxes[block.inbox]) problem(`shows unknown inbox ${block.inbox}`);
 		}
-		if (block.type === "fields") {
-			for (const { value } of block.fields) if (value && typeof value === "object" && "edit" in value) action(value.edit.action);
-		}
+		for (const field of valuesIn(block)) value(field);
 	});
 }
 //#endregion
@@ -328,7 +451,10 @@ function findConfig(root) {
 	if (!file) throw new Error(`No pult.config.ts in ${root}`);
 	return file;
 }
-async function loadProject(root, importer) {
+function loadProject(root, importer) {
+	return traceOrigins(() => load(root, importer));
+}
+async function load(root, importer) {
 	const config = (await importer(findConfig(root))).default;
 	if (kindOf(config) !== "config") throw new Error("pult.config.ts must default-export defineConfig({ ... })");
 	const { include } = config.options;
@@ -419,10 +545,6 @@ var Locator = class {
 		return this.locate(origin, new RegExp(`\\b${kind}\\(\\s*["'\`]${escapeRegExp(name)}["'\`]`));
 	}
 };
-function humanize(name) {
-	const spaced = name.replace(/[-_]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2");
-	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
-}
 function pluralize(label) {
 	return /(s|x|sh|ch)$/.test(label) ? `${label}es` : /[^aeiou]y$/.test(label) ? `${label.slice(0, -1)}ies` : `${label}s`;
 }
@@ -551,7 +673,7 @@ function pageDef(locator, page) {
 	};
 }
 function staticBlocks(page, blocks) {
-	if (blocks.some(isPendingAttachment)) throw new Error(`Page "${page}" attaches file data. Render it from a function instead.`);
+	if (hasPendingAttachments(blocks)) throw new Error(`Page "${page}" attaches file data. Render it from a function instead.`);
 	return JSON.parse(JSON.stringify(blocks));
 }
 function flagDef(locator, flag) {
@@ -573,14 +695,34 @@ function flagDef(locator, flag) {
 		approval: options.approval ?? false
 	};
 }
+function spaceDef(locator, space) {
+	const { options } = space;
+	return {
+		name: space.name,
+		source: locator.call("space", space.origin, space.name),
+		label: options.label ?? humanize(space.name),
+		icon: options.icon ?? "layout",
+		home: space.home?.name ?? null,
+		inboxes: (options.inboxes ?? []).map((inbox) => inbox.name),
+		resources: (options.resources ?? []).map((resource) => resource.name),
+		pages: (options.pages ?? []).map((page) => page.name),
+		flags: (options.flags ?? []).map((flag) => flag.name)
+	};
+}
+function byDefinition(a, b) {
+	return a.origin.file.localeCompare(b.origin.file) || a.origin.line - b.origin.line;
+}
 function notifyDef(locator, rule) {
 	return {
 		source: locator.call("notify", rule.origin, rule.name),
 		inboxes: rule.options.inboxes.map((inbox) => inbox.name),
 		on: rule.options.on,
-		to: rule.options.to.map((recipient) => "channel" in recipient ? { channel: recipient.channel } : { role: recipient.name })
+		to: recipients(rule.options.to)
 	};
 }
+function recipients(list) {
+	return list.map((recipient) => "channel" in recipient ? { channel: recipient.channel } : { role: recipient.name });
+}
 function logo(value) {
 	if (value === void 0) return null;
 	return typeof value === "string" ? {
@@ -606,7 +748,7 @@ function statusDef(locator, page, config) {
 			monitored: component.monitored ?? false,
 			check: component.check ?? null
 		}])),
-		alert: (page.options.alert ?? []).map((recipient) => "channel" in recipient ? { channel: recipient.channel } : { role: recipient.name }),
+		alert: recipients(page.options.alert ?? []),
 		after: milliseconds(page.options.after ?? "2m")
 	};
 }
@@ -636,32 +778,59 @@ function assemble(root, definitions, config) {
 		pages: map(definitions.pages, (page) => pageDef(locator, page)),
 		flags: map(definitions.flags, (flag) => flagDef(locator, flag)),
 		roles,
+		spaces: [...definitions.spaces.values()].sort(byDefinition).map((space) => spaceDef(locator, space)),
 		notify: map(definitions.notify, (rule) => notifyDef(locator, rule)),
 		status: definitions.status && statusDef(locator, definitions.status, config)
 	};
 	return {
 		...manifest,
-		version: hash(stableJson(manifest))
+		version: versionOf(manifest)
 	};
 }
-function hash(text) {
-	return createHash("sha256").update(text).digest("hex").slice(0, 12);
+function unsourced(definitions) {
+	return Object.fromEntries(Object.entries(definitions).map(([name, { source: _, ...rest }]) => [name, rest]));
+}
+function versionOf(manifest) {
+	const content = {
+		...manifest,
+		resources: Object.fromEntries(Object.entries(manifest.resources).map(([name, { source: _, actions, ...rest }]) => [name, {
+			...rest,
+			actions: unsourced(actions)
+		}])),
+		actions: unsourced(manifest.actions),
+		inboxes: unsourced(manifest.inboxes),
+		views: unsourced(manifest.views),
+		pages: unsourced(manifest.pages),
+		flags: unsourced(manifest.flags),
+		roles: unsourced(manifest.roles),
+		spaces: manifest.spaces.map(({ source: _, ...rest }) => rest),
+		notify: unsourced(manifest.notify),
+		status: manifest.status && {
+			...manifest.status,
+			source: void 0
+		}
+	};
+	return createHash("sha256").update(stableJson(content)).digest("hex").slice(0, 12);
 }
 //#endregion
 //#region src/build/codegen.ts
 const OUT_DIR = ".pult";
-function projectModule(files) {
+function projectModule(manifest, files) {
+	const component = Object.keys(manifest.status?.components ?? {}).map((name) => JSON.stringify(name)).join(" | ") || "never";
+	const entries = files.map((file) => `    ${JSON.stringify(file)}: () => import(${JSON.stringify(`../${file}`)}),`);
 	return [
 		"// Generated by `pult build`. Commit this file; don't edit it.",
-		"import type { Manifest, Project } from \"pult\"",
+		"import type { Manifest, Project } from \"@lantharos/pult\"",
 		"import manifest from \"./manifest.json\" with { type: \"json\" }",
 		"",
-		"export default {",
-		"  manifest: manifest as Manifest,",
+		`const project: Project<${component}> = {`,
+		`  manifest: manifest as Manifest<${component}>,`,
 		"  modules: {",
-		...files.map((file) => `    ${JSON.stringify(file)}: () => import(${JSON.stringify(`../${file}`)}),`),
+		...entries,
 		"  },",
-		"} satisfies Project",
+		"}",
+		"",
+		"export default project",
 		""
 	].join("\n");
 }
@@ -676,7 +845,7 @@ async function writeOutput(root, manifest, files) {
 	const dir = join(root, OUT_DIR);
 	await mkdir(dir, { recursive: true });
 	await writeFile(join(dir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-	await writeFile(join(dir, "index.ts"), projectModule(files));
+	await writeFile(join(dir, "index.ts"), projectModule(manifest, files));
 }
 //#endregion
 //#region src/build/index.ts
@@ -765,34 +934,18 @@ async function buildProject(root) {
 	}
 }
 var Remote = class {
-	environment;
-	#secret;
-	#url;
+	#transport;
 	constructor() {
 		const key = process.env.PULT_KEY;
 		if (!key) fail("Set PULT_KEY to the key of the environment you're targeting");
-		const parsed = parseKey(key);
-		this.environment = parsed.environment;
-		this.#secret = parsed.secret;
-		this.#url = (process.env.PULT_URL ?? "https://app.pult.sh").replace(/\/$/, "");
+		this.#transport = new Transport(key, process.env.PULT_URL ?? "https://app.pult.sh", fetch);
 	}
 	async #request(method, path, body) {
-		const payload = body === void 0 ? "" : JSON.stringify(body);
-		const signature = await sign(this.#secret, `${method} ${path}`, payload);
-		const response = await fetch(`${this.#url}${path}`, {
-			method,
-			body: method === "POST" ? payload : void 0,
-			headers: {
-				"content-type": "application/json",
-				[HEADER.environment]: this.environment,
-				[HEADER.timestamp]: signature.timestamp,
-				[HEADER.nonce]: signature.nonce,
-				[HEADER.signature]: signature.signature
-			}
-		});
-		const json = await response.json().catch(() => null);
-		if (!response.ok) fail(json?.error ?? `${response.status} ${response.statusText}`);
-		return json;
+		try {
+			return await this.#transport.request(method, path, body);
+		} catch (error) {
+			fail(error.message);
+		}
 	}
 	current() {
 		return this.#request("GET", "/v1/manifest");
@@ -819,7 +972,7 @@ async function checkCommand(root) {
 	const { manifest, problems } = await buildProject(root);
 	printProblems(problems);
 	if (problems.length) fail(`${problems.length} problem${problems.length === 1 ? "" : "s"}`);
-	if ((await readManifest(root))?.version !== manifest.version) fail("The committed manifest is out of date. Run `pult build`.");
+	if (stableJson(await readManifest(root)) !== stableJson(manifest)) fail("The committed manifest is out of date. Run `pult build`.");
 	done(`manifest ${manifest.version} is valid and up to date`);
 }
 //#endregion
@@ -883,14 +1036,81 @@ async function diffCommand(root) {
 	printChanges(diffManifests(current.manifest, manifest));
 }
 //#endregion
+//#region src/cli/commands/init.ts
+const WRANGLER_FILES = [
+	"wrangler.jsonc",
+	"wrangler.json",
+	"wrangler.toml"
+];
+const WEBHOOK_PATH = "/pult";
+function config(project, onWorkers) {
+	return `import { defineConfig } from "@lantharos/pult"
+
+export default defineConfig({
+  project: ${JSON.stringify(project)},
+  include: ["pult/**/*.ts"],${onWorkers ? `\n  delivery: { mode: "webhook", path: "${WEBHOOK_PATH}" },` : ""}
+})
+`;
+}
+const DEFINITIONS = `import { inbox, resource } from "@lantharos/pult"
+
+export const user = resource("user", {
+  get: (id) => ({ id, email: \`\${id}@example.com\` }),
+  title: (user) => user.email,
+})
+
+export const feedback = inbox("feedback", { resource: user })
+`;
+const SOCKET_CLIENT = `import { createPult } from "@lantharos/pult"
+import project from "../.pult"
+
+export const pult = createPult({ project })
+
+pult.listen()
+`;
+const WORKER_CLIENT = `import { env } from "cloudflare:workers"
+import { createPult } from "@lantharos/pult"
+import project from "../.pult"
+
+export const pult = createPult({ key: env.PULT_KEY, project })
+export const handlePult = pult.handler()
+`;
+async function projectName(root) {
+	return ((await readFile(join(root, "package.json"), "utf8").then((text) => JSON.parse(text)).catch(() => ({ name: void 0 }))).name ?? basename(root)).replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "app";
+}
+async function create(root, file, content) {
+	const path = join(root, file);
+	await mkdir(dirname(path), { recursive: true });
+	try {
+		await writeFile(path, content, { flag: "wx" });
+		done(`wrote ${file}`);
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		console.log(dim(`  kept ${file}, it already exists`));
+	}
+}
+async function initCommand(root) {
+	const onWorkers = WRANGLER_FILES.some((file) => existsSync(join(root, file)));
+	await create(root, "pult.config.ts", config(await projectName(root), onWorkers));
+	await create(root, "pult/feedback.ts", DEFINITIONS);
+	await create(root, "src/pult.ts", onWorkers ? WORKER_CLIENT : SOCKET_CLIENT);
+	console.log(`\nNext, run ${bold("pult build")} and set PULT_KEY to your environment's key.`);
+	if (onWorkers) console.log(`Then hand Pult's requests to it in your fetch handler:\n\n  if (new URL(request.url).pathname === "${WEBHOOK_PATH}") return handlePult(request, ctx)`);
+}
+//#endregion
 //#region src/cli/index.ts
-const USAGE = `pult <command>
+const USAGE = `pult <command> [--cwd <path>]
 
+  init     set up Pult in this project
   build    compile definitions into .pult/
-  check    type-check references and make sure the manifest is current
+  check    find broken references and make sure .pult/ is current
   diff     show what a deploy would change (uses PULT_KEY)
   deploy   push the manifest to the environment behind PULT_KEY
-  dev      rebuild on every change`;
+  dev      rebuild on every change
+
+  --cwd <path>    run in another project folder
+  -v, --version   print the version
+  -h, --help      show this help`;
 const { positionals, values } = parseArgs({
 	allowPositionals: true,
 	options: {
@@ -898,11 +1118,16 @@ const { positionals, values } = parseArgs({
 		help: {
 			type: "boolean",
 			short: "h"
+		},
+		version: {
+			type: "boolean",
+			short: "v"
 		}
 	}
 });
-const root = values.cwd ?? process.cwd();
+const root = resolve(values.cwd ?? ".");
 const commands = {
+	init: initCommand,
 	build: buildCommand,
 	check: checkCommand,
 	diff: diffCommand,
@@ -910,7 +1135,8 @@ const commands = {
 	dev: devCommand
 };
 const command = positionals[0];
-if (values.help || !command) console.log(USAGE);
+if (values.version) console.log(version);
+else if (values.help || !command) console.log(USAGE);
 else if (!commands[command]) fail(`Unknown command "${command}"\n\n${USAGE}`);
 else await commands[command](root);
 //#endregion