@format.dev/cli 0.0.0 → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1539 @@
+#!/usr/bin/env node
+import { a as readConfigFile, i as findConfigPath, o as writeConfigVersion, r as detectIndent, s as CliError } from "./config-Dq7O4e8N.mjs";
+import { C as joinNames, D as commandForPlatform, E as truncateForSpinner, O as detectPackageManager, S as installManifest, T as runInstall$2, c as getDocumentsDir, g as validateDocumentName, i as generateRandomName, k as installCommand, l as readExistingDocumentNames, n as maybeSetupProject, r as writeDocumentDependencies, s as createDocument, w as writeDependenciesToManifest } from "./install-BiDrmMgJ.mjs";
+import { a as rewriteFormatDependencies, i as mayHaveBreakingChanges, n as isExactVersion, r as isNewer, t as loadProjectState } from "./project-pX62Di_9.mjs";
+import { a as DEFAULT_STYLING, f as STYLING_LABELS, h as SUPPORTED_FRAMEWORKS, l as SCHEMA_KINDS, n as DEFAULT_PAGE_SIZE_ID, s as PAGE_SIZES, u as SCHEMA_LABELS, v as isValidDimension, y as methodsForFramework } from "./shared-CM3vyUlL.mjs";
+import "./draw-random-name-Dpt6YmUk.mjs";
+import { Command, Option } from "commander";
+import { spawn } from "node:child_process";
+import fs, { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import pc from "picocolors";
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+
+//#region src/cli/cli-spec.json
+var cli_spec_default = { commands: [
+	{
+		"name": "new",
+		"description": "Create a new Format project or document.",
+		"options": [],
+		"commands": [{
+			"name": "project",
+			"description": "Scaffold a new Format project. This works best for a completely empty codebase. For existing codebases, use `format init`.",
+			"arguments": [{
+				"name": "directory",
+				"description": "Where to create the project. Prompted if omitted.",
+				"required": false
+			}],
+			"options": [
+				{
+					"field": "framework",
+					"flags": "--framework <framework>",
+					"description": "The framework to build your documents with.",
+					"type": "string",
+					"choices": [
+						"react",
+						"vue",
+						"html"
+					]
+				},
+				{
+					"field": "install",
+					"flags": "--no-install",
+					"description": "Don't install dependencies after creating the project.",
+					"type": "boolean",
+					"defaultValue": true
+				},
+				{
+					"field": "yes",
+					"flags": "-y, --yes",
+					"description": "Skip all prompts and use the defaults for every option that isn't provided.",
+					"type": "boolean",
+					"defaultValue": false
+				}
+			]
+		}, {
+			"name": "document",
+			"description": "Scaffold a new document directory with an entry file, a stylesheet, and a default data variant.",
+			"arguments": [{
+				"name": "name",
+				"description": "The document directory name (kebab-case recommended). Omit it to be prompted with a random suggestion.",
+				"required": false
+			}],
+			"options": [
+				{
+					"field": "styling",
+					"flags": "--styling <method>",
+					"description": "Styling method for the document. Choices are filtered to your project framework. See the [styling docs](/docs/studio/styling) for more information.",
+					"defaultValue": "css",
+					"type": "string",
+					"choices": [
+						"css",
+						"css-modules",
+						"vue-sfc-scoped",
+						"scss",
+						"tailwind",
+						"linaria",
+						"vanilla-extract",
+						"panda-css"
+					]
+				},
+				{
+					"field": "schema",
+					"flags": "--schema <library>",
+					"description": "Scaffold a `data/schema.ts` with this validation library, or \"none\" for no schema. Format validates any Standard Schema compliant library, so you can also wire up others by hand.",
+					"type": "string",
+					"choices": [
+						"none",
+						"zod",
+						"valibot",
+						"joi",
+						"yup"
+					],
+					"defaultValue": "none"
+				},
+				{
+					"field": "data",
+					"flags": "--data <path>",
+					"description": "Path to a JSON file to seed the default data variant. Its shape is used to infer the schema and the entry's data type.",
+					"type": "string"
+				},
+				{
+					"field": "size",
+					"flags": "--size <id>",
+					"description": "Page size for the document. A4 is the default; pass \"custom\" with --width and --height for an exact size.",
+					"type": "string",
+					"defaultValue": "a4",
+					"choices": [
+						"a3",
+						"a4",
+						"a5",
+						"letter",
+						"slide-16-9",
+						"slide-4-3",
+						"custom"
+					]
+				},
+				{
+					"field": "width",
+					"flags": "--width <px>",
+					"description": "Custom page width in CSS pixels. Requires --height; ignored unless --size is \"custom\" or omitted.",
+					"type": "string"
+				},
+				{
+					"field": "height",
+					"flags": "--height <px>",
+					"description": "Custom page height in CSS pixels. Requires --width; ignored unless --size is \"custom\" or omitted.",
+					"type": "string"
+				},
+				{
+					"field": "install",
+					"flags": "--no-install",
+					"description": "Don't install missing styling/schema dependencies after creating the document.",
+					"type": "boolean",
+					"defaultValue": true
+				},
+				{
+					"field": "yes",
+					"flags": "-y, --yes",
+					"description": "Skip all prompts and use the defaults for every option that isn't provided.",
+					"type": "boolean",
+					"defaultValue": false
+				},
+				{
+					"field": "empty",
+					"flags": "--empty",
+					"description": "Scaffold the most minimal document. Can be combined with other flags.",
+					"type": "boolean",
+					"defaultValue": false
+				}
+			]
+		}]
+	},
+	{
+		"name": "init",
+		"description": "Set up Format in an existing codebase. This script writes a Format config file, adds npm scripts, gitignore entries, the Format packages, and optionally a first document. Each step will confirm before editing anything.",
+		"options": [
+			{
+				"field": "framework",
+				"flags": "--framework <framework>",
+				"description": "The framework to build your documents with — React, Vue or HTML. Detected from your dependencies when omitted.",
+				"type": "string",
+				"choices": [
+					"react",
+					"vue",
+					"html"
+				]
+			},
+			{
+				"field": "rootDir",
+				"flags": "--root-dir <dir>",
+				"description": "Where to install the Format project into. The path you give will be set in your Format config's `rootDir`.",
+				"type": "string"
+			},
+			{
+				"field": "install",
+				"flags": "--no-install",
+				"description": "Don't automatically add or install any Format packages.",
+				"type": "boolean",
+				"defaultValue": true
+			},
+			{
+				"field": "scripts",
+				"flags": "--no-scripts",
+				"description": "Don't add the npm dev and npm compile scripts to your package.json. Existing dev and compile script names are never overwritten regardless, If there's a name clash, they get a `format:` prefix.",
+				"type": "boolean",
+				"defaultValue": true
+			},
+			{
+				"field": "gitignore",
+				"flags": "--no-gitignore",
+				"description": "Don't append the `_generated` and `.env` entries to .gitignore. Existing lines are never touched.",
+				"type": "boolean",
+				"defaultValue": true
+			},
+			{
+				"field": "document",
+				"flags": "--no-document",
+				"description": "Don't offer to create a first document.",
+				"type": "boolean",
+				"defaultValue": true
+			},
+			{
+				"field": "yes",
+				"flags": "-y, --yes",
+				"description": "Skip all prompts and use the defaults for every option that isn't provided.",
+				"type": "boolean",
+				"defaultValue": false
+			}
+		]
+	},
+	{
+		"name": "add",
+		"description": "Adds and installs Format packages. Packages will be installed at the version defined in your config file.",
+		"arguments": [{
+			"name": "packages...",
+			"description": "One or more Format packages. Shorthands map to the scope: `zip` means `@format.dev/zip`.",
+			"required": true
+		}],
+		"options": []
+	},
+	{
+		"name": "remove",
+		"description": "Remove Format packages from your project. The counterpart to `format add`.",
+		"arguments": [{
+			"name": "packages...",
+			"description": "One or more Format packages. Shorthands map to the scope: `zip` means `@format.dev/zip`.",
+			"required": true
+		}],
+		"options": []
+	},
+	{
+		"name": "update",
+		"description": "Move your project to a different Format version. With no arguments, the version set in your Format config file will be used. The argument \"latest\" updates to the latest available version and pins it.",
+		"arguments": [{
+			"name": "version",
+			"description": "An exact release like `0.1.2`, or `latest` for the newest. Omit it to apply the release already pinned in your config. The version field is the source of truth, and editing it by hand then running `format update` is a supported flow.",
+			"required": false
+		}],
+		"options": []
+	},
+	{
+		"name": "version",
+		"description": "Print the current pinned Format version for your project, check every installed Format package matches it exactly, and mention when a newer version is available. Exits non-zero on any drift, so can be used in CI as a gate.",
+		"options": []
+	}
+] };
+
+//#endregion
+//#region src/versioning/js-version.ts
+const jsVersion = "0.1.0";
+
+//#endregion
+//#region src/versioning/registry.ts
+const REFERENCE_PACKAGE = "@format.dev/studio";
+function registryBaseUrl() {
+	return (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/$/, "");
+}
+async function fetchLatestVersion() {
+	const url = `${registryBaseUrl()}/${encodeURIComponent(REFERENCE_PACKAGE)}/latest`;
+	let response;
+	try {
+		response = await fetch(url, { headers: { accept: "application/json" } });
+	} catch {
+		throw new CliError("Could not reach the npm registry. Check your connection and try again.");
+	}
+	if (!response.ok) throw new CliError(`npm registry request failed (${response.status}) while resolving the latest Format version.`);
+	const data = await response.json();
+	if (!data.version) throw new CliError("Unexpected npm registry response while resolving the latest Format version.");
+	return data.version;
+}
+
+//#endregion
+//#region src/versioning/update-check.ts
+const CACHE_FILE_NAME = "update-check.json";
+const CACHE_MAX_AGE_MS = 1440 * 60 * 1e3;
+const CHANGELOG_URL = "https://format.dev/changelog";
+function cacheDir() {
+	const home = os.homedir();
+	if (process.env.XDG_CACHE_HOME) return join(process.env.XDG_CACHE_HOME, "format");
+	if (process.platform === "darwin") return join(home, "Library", "Caches", "format");
+	if (process.platform === "win32") return join(process.env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "format");
+	return join(home, ".cache", "format");
+}
+function cacheFilePath() {
+	return join(cacheDir(), CACHE_FILE_NAME);
+}
+async function readCache() {
+	try {
+		const raw = await fs.readFile(cacheFilePath(), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string") return null;
+		return {
+			checkedAt: parsed.checkedAt,
+			latest: parsed.latest
+		};
+	} catch {
+		return null;
+	}
+}
+async function writeCache(latest) {
+	try {
+		await fs.mkdir(cacheDir(), { recursive: true });
+		const cache = {
+			checkedAt: Date.now(),
+			latest
+		};
+		await fs.writeFile(cacheFilePath(), `${JSON.stringify(cache)}\n`, "utf8");
+	} catch {}
+}
+async function resolveLatest() {
+	const cached = await readCache();
+	if (cached && Date.now() - cached.checkedAt < CACHE_MAX_AGE_MS) return cached.latest;
+	try {
+		const latest = await fetchLatestVersion();
+		await writeCache(latest);
+		return latest;
+	} catch {
+		return cached?.latest ?? null;
+	}
+}
+function printNudge(pinnedVersion, latest) {
+	console.log("");
+	console.log(`A newer Format release is available: ${latest} (you're on ${pinnedVersion}).`);
+	if (mayHaveBreakingChanges(pinnedVersion, latest)) console.log(`This release may include breaking changes. See ${CHANGELOG_URL} before updating.`);
+	console.log("Run `format update latest` to move to it.");
+}
+async function reportNewerRelease(pinnedVersion) {
+	const latest = await resolveLatest();
+	if (latest && isNewer(latest, pinnedVersion)) printNudge(pinnedVersion, latest);
+}
+function startUpdateCheck(pinnedVersion) {
+	const pending = resolveLatest().catch(() => null);
+	return { report: async () => {
+		const latest = await pending;
+		if (latest && isNewer(latest, pinnedVersion)) printNudge(pinnedVersion, latest);
+	} };
+}
+
+//#endregion
+//#region src/studio.ts
+const STUDIO_PACKAGE = "@format.dev/studio";
+const COMPILE_PACKAGE = "@format.dev/compile";
+const STUDIO_BIN_NAME = "format-studio";
+const COMPILE_BIN_NAME = "format-compile";
+function targetForCommand(commandName) {
+	if (commandName === "compile") return {
+		packageName: COMPILE_PACKAGE,
+		binName: COMPILE_BIN_NAME
+	};
+	return {
+		packageName: STUDIO_PACKAGE,
+		binName: STUDIO_BIN_NAME
+	};
+}
+function findStudioPackageJson(projectDir, packageName) {
+	let dir = resolve(projectDir);
+	for (;;) {
+		const candidate = join(dir, "node_modules", packageName, "package.json");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+async function findLocalStudio(projectDir, target) {
+	const packageJsonPath = findStudioPackageJson(projectDir, target.packageName);
+	if (!packageJsonPath) return null;
+	const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+	const binRelativePath = packageJson.bin?.[target.binName];
+	if (!binRelativePath) throw new CliError(`The installed ${target.packageName} (${packageJson.version}) does not expose a "${target.binName}" bin. Run \`format update\` to align your packages.`);
+	return {
+		binPath: resolve(dirname(packageJsonPath), binRelativePath),
+		version: packageJson.version
+	};
+}
+async function runStudioCommand(cwd, argv) {
+	const state = await loadProjectState(cwd);
+	const updateCheck = argv[0] === "dev" && state.pinnedVersion ? startUpdateCheck(state.pinnedVersion) : null;
+	const exitCode = await spawnStudioForProject(state, argv);
+	if (updateCheck) await updateCheck.report();
+	return exitCode;
+}
+async function spawnStudioForProject(state, argv) {
+	const target = targetForCommand(argv[0]);
+	const localStudio = await findLocalStudio(state.projectDir, target);
+	const keepAliveOnSignal = argv[0] === "dev";
+	if (localStudio) {
+		if (state.pinnedVersion !== null && localStudio.version !== state.pinnedVersion) throw new CliError(`Installed ${target.packageName} is ${localStudio.version} but format.config.json pins ${state.pinnedVersion}. Run \`format update\` to bring them in line.`);
+		return spawnStudio(process.execPath, [localStudio.binPath, ...argv], state.projectDir, keepAliveOnSignal);
+	}
+	if (!state.pinnedVersion) throw new CliError(`No "version" field in ${state.configFile.filepath} and no local ${target.packageName} install. Run \`format update\` to pin the latest Format release.`);
+	return spawnStudio("npm", [
+		"exec",
+		"-y",
+		"--prefer-offline",
+		"--",
+		`${target.packageName}@${state.pinnedVersion}`,
+		...argv
+	], state.projectDir, keepAliveOnSignal);
+}
+async function spawnStudio(command, args, cwd, keepAliveOnSignal = false) {
+	return new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(command, args, {
+			cwd,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		let interrupts = 0;
+		const onSignal = () => {
+			interrupts += 1;
+			if (interrupts >= 2) process.exit(130);
+		};
+		if (keepAliveOnSignal) process.on("SIGINT", onSignal);
+		const cleanup = () => {
+			if (keepAliveOnSignal) process.off("SIGINT", onSignal);
+		};
+		child.on("error", (error) => {
+			cleanup();
+			rejectPromise(new CliError(`Failed to launch Studio: ${error.message}`));
+		});
+		child.on("exit", (code, signal) => {
+			cleanup();
+			if (signal) {
+				resolvePromise(1);
+				return;
+			}
+			resolvePromise(code ?? 0);
+		});
+	});
+}
+
+//#endregion
+//#region src/scaffold/project.ts
+function getBuildMode() {
+	return "prod";
+}
+const WORKSPACE_VERSION = "workspace:*";
+function formatDependencyVersion(version) {
+	return getBuildMode() === "prod" ? version : WORKSPACE_VERSION;
+}
+function devOnlyWorkspacePackages() {
+	if (getBuildMode() === "prod") return [];
+	return [STUDIO_PACKAGE, COMPILE_PACKAGE];
+}
+const _dirname = dirname(fileURLToPath(import.meta.url));
+function findCliPackageRoot() {
+	let dir = _dirname;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) throw new CliError("Could not locate the @format.dev/cli package root.");
+		dir = parent;
+	}
+}
+const DOTFILE_TEMPLATES = {
+	_gitignore: ".gitignore",
+	_env: ".env"
+};
+async function restoreDotfiles(dirPath) {
+	for (const [templateName, dotfileName] of Object.entries(DOTFILE_TEMPLATES)) {
+		const templateFile = join(dirPath, templateName);
+		if (existsSync(templateFile)) await fs.rename(templateFile, join(dirPath, dotfileName));
+	}
+}
+function resolveTemplatePath(name) {
+	const templatePath = join(findCliPackageRoot(), "templates", name);
+	if (!existsSync(templatePath)) throw new CliError(`Unknown project template "${name}".`);
+	return templatePath;
+}
+function deriveProjectName(dirInput) {
+	const name = basename(dirInput.trim().replace(/[\\/]+$/, ""));
+	return name === "" || name === "." ? "my-format-project" : name;
+}
+function replaceWorkspaceVersions(deps, version) {
+	if (!deps) return deps;
+	for (const [depName, depVersion] of Object.entries(deps)) if (depVersion === "workspace:*" && depName.startsWith("@format.dev/")) deps[depName] = version;
+	return deps;
+}
+async function updateGeneratedPackageJson(args) {
+	const { dirPath, projectName, buildMode, version } = args;
+	const packageJsonPath = resolve(dirPath, "package.json");
+	const raw = await fs.readFile(packageJsonPath, "utf8");
+	const packageJson = JSON.parse(raw);
+	packageJson.name = projectName;
+	for (const name of devOnlyWorkspacePackages()) packageJson.devDependencies = {
+		...packageJson.devDependencies,
+		[name]: WORKSPACE_VERSION
+	};
+	if (buildMode === "prod") {
+		packageJson.dependencies = replaceWorkspaceVersions(packageJson.dependencies, version);
+		packageJson.devDependencies = replaceWorkspaceVersions(packageJson.devDependencies, version);
+		packageJson.optionalDependencies = replaceWorkspaceVersions(packageJson.optionalDependencies, version);
+		packageJson.peerDependencies = replaceWorkspaceVersions(packageJson.peerDependencies, version);
+	}
+	await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "	")}\n`, "utf8");
+}
+async function updateGeneratedFormatConfig(args) {
+	const { dirPath, version } = args;
+	const configPath = resolve(dirPath, "format.config.json");
+	const raw = await fs.readFile(configPath, "utf8");
+	const config = JSON.parse(raw);
+	const withVersion = {
+		$schema: config.$schema,
+		version,
+		...config
+	};
+	await fs.writeFile(configPath, `${JSON.stringify(withVersion, null, "	")}\n`, "utf8");
+}
+function isCommandNotFoundError(error) {
+	return !!(error && "code" in error && error.code === "ENOENT");
+}
+async function installProjectDependencies(args) {
+	const { dirPath, preferredPackageManager, onProgress } = args;
+	const attempt = async (packageManager) => {
+		const { command, args: commandArgs } = installCommand(packageManager);
+		return runInstall$2({
+			command,
+			args: commandArgs,
+			cwd: dirPath,
+			onProgress
+		});
+	};
+	const first = await attempt(preferredPackageManager);
+	if (first.ok) return {
+		ok: true,
+		packageManagerUsed: preferredPackageManager,
+		fellBackToNpm: false
+	};
+	if (!(preferredPackageManager !== "npm" && isCommandNotFoundError(first.error))) return {
+		ok: false,
+		packageManagerUsed: preferredPackageManager,
+		fellBackToNpm: false,
+		message: first.error?.message ?? `${preferredPackageManager} exited with code ${first.code}`,
+		output: first.output
+	};
+	const fallback = await attempt("npm");
+	if (fallback.ok) return {
+		ok: true,
+		packageManagerUsed: "npm",
+		fellBackToNpm: true
+	};
+	return {
+		ok: false,
+		packageManagerUsed: "npm",
+		fellBackToNpm: true,
+		message: fallback.error?.message ?? `npm exited with code ${fallback.code}`,
+		output: fallback.output
+	};
+}
+async function templateUsesWorkspaceDeps(dirPath) {
+	try {
+		return (await fs.readFile(resolve(dirPath, "package.json"), "utf8")).includes("workspace:");
+	} catch {
+		return false;
+	}
+}
+async function scaffoldProject(args) {
+	const { directory, framework, cwd } = args;
+	const dirPath = resolve(cwd, directory);
+	const projectName = deriveProjectName(directory);
+	const buildMode = getBuildMode();
+	const version = jsVersion;
+	await fs.mkdir(dirPath, { recursive: true });
+	try {
+		const sharedPath = resolveTemplatePath("shared");
+		await fs.cp(sharedPath, dirPath, { recursive: true });
+	} catch {}
+	const templatePath = resolveTemplatePath(framework);
+	await fs.cp(templatePath, dirPath, { recursive: true });
+	await restoreDotfiles(dirPath);
+	await updateGeneratedPackageJson({
+		dirPath,
+		projectName,
+		buildMode,
+		version
+	});
+	await updateGeneratedFormatConfig({
+		dirPath,
+		version
+	});
+	return {
+		dirPath,
+		projectName
+	};
+}
+
+//#endregion
+//#region src/cli/commands/add.ts
+const RUNTIME_PACKAGES = ["@format.dev/client", "@format.dev/zip"];
+function normalisePackageName$1(name) {
+	if (name.startsWith("@format.dev/")) return name;
+	return `@format.dev/${name}`;
+}
+function installArgs(packageManager, packages, dev) {
+	const saveFlag = dev ? "-D" : "";
+	switch (packageManager) {
+		case "npm": return [
+			"install",
+			...dev ? ["--save-dev"] : [],
+			...packages
+		];
+		default: return [
+			"add",
+			...saveFlag ? [saveFlag] : [],
+			...packages
+		];
+	}
+}
+async function addCommand(cwd, packages) {
+	if (packages.length === 0) throw new CliError("Usage: format add <package> [...] — e.g. `format add zip` or `format add \"@format.dev/client\"`.");
+	const state = await loadProjectState(cwd);
+	if (!state.packageJsonPath) throw new CliError("No package.json found next to the config — nothing to install into.");
+	const pinnedVersion = state.pinnedVersion;
+	if (!pinnedVersion) throw new CliError(`${state.configFile.filepath} is missing its required "version" field. Run \`format init\` to set the project up.`);
+	const names = packages.map(normalisePackageName$1);
+	const runtime = names.filter((name) => RUNTIME_PACKAGES.includes(name));
+	const dev = names.filter((name) => !RUNTIME_PACKAGES.includes(name));
+	const packageManager = await detectPackageManager(state.projectDir);
+	for (const [group, isDev] of [[runtime, false], [dev, true]]) {
+		if (group.length === 0) continue;
+		const dependencyVersion = formatDependencyVersion(pinnedVersion);
+		const pinned = group.map((name) => `${name}@${dependencyVersion}`);
+		console.log(`Installing ${pinned.join(", ")} ${isDev ? "(devDependencies)" : "(dependencies)"} with ${packageManager}...`);
+		await runInstall$1(packageManager, installArgs(packageManager, pinned, isDev), state.projectDir);
+	}
+	console.log("");
+	console.log(`Done. Added at ${formatDependencyVersion(pinnedVersion)}.`);
+	return 0;
+}
+async function runInstall$1(packageManager, args, cwd) {
+	await new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(commandForPlatform(packageManager), args, {
+			cwd,
+			stdio: "inherit",
+			shell: false
+		});
+		child.on("error", (error) => {
+			rejectPromise(new CliError(`Failed to run ${packageManager}: ${error.message}`));
+		});
+		child.on("exit", (code) => {
+			if (code === 0) {
+				resolvePromise();
+				return;
+			}
+			rejectPromise(new CliError(`${packageManager} exited with code ${code}.`));
+		});
+	});
+}
+
+//#endregion
+//#region src/prompts.ts
+var PromptCancelledError = class extends Error {
+	constructor() {
+		super("Prompt cancelled");
+		this.name = "PromptCancelledError";
+	}
+};
+function isPromptCancelledError(error) {
+	return error instanceof PromptCancelledError;
+}
+function requirePrompt(value) {
+	if (isCancel(value)) {
+		cancel("Cancelled.");
+		throw new PromptCancelledError();
+	}
+	return value;
+}
+
+//#endregion
+//#region src/scaffold/finalize-dependencies.ts
+async function finalizeDependencies(args) {
+	const { projectDir, addedDependencies, install, skipPrompts } = args;
+	const hasAdded = addedDependencies.length > 0;
+	const verb = addedDependencies.length === 1 ? "has" : "have";
+	const wantInstall = await decideInstall({
+		install,
+		skipPrompts,
+		hasAdded,
+		addedLine: `${joinNames(addedDependencies.map((name) => pc.cyan(name)))} ${verb} been added to your package.json.`
+	});
+	if (!wantInstall || !hasAdded) {
+		if (hasAdded && !wantInstall) {
+			const { command, args: args$1 } = installCommand(await detectPackageManager(projectDir));
+			log.warn(`Run ${pc.cyan(`${command} ${args$1.join(" ")}`)} when you're ready.`);
+		}
+		return {
+			wantInstall,
+			installed: false
+		};
+	}
+	const installSpinner = spinner();
+	installSpinner.start("Installing dependencies");
+	const result = await installManifest({
+		projectDir,
+		onProgress: (line) => installSpinner.message(truncateForSpinner(line))
+	});
+	if (result.ok) installSpinner.stop(`Dependencies installed with ${pc.cyan(result.packageManager)}`);
+	if (!result.ok) installSpinner.error("Could not install dependencies");
+	return {
+		wantInstall,
+		installed: result.ok,
+		result
+	};
+}
+async function decideInstall(args) {
+	const { install, skipPrompts, hasAdded, addedLine } = args;
+	if (install !== void 0) {
+		if (hasAdded) log.info(addedLine);
+		return install;
+	}
+	if (!hasAdded) return true;
+	if (skipPrompts) {
+		log.info(addedLine);
+		return true;
+	}
+	return requirePrompt(await confirm({
+		message: `${addedLine} Automatically install dependencies?`,
+		initialValue: true
+	}));
+}
+
+//#endregion
+//#region src/cli/commands/new-document.ts
+const STUDIO_URL = "http://localhost:1234";
+async function resolveName(args) {
+	const { provided, existingNames, skipPrompts } = args;
+	if (provided) return provided;
+	const suggestion = generateRandomName({ existingNames });
+	if (skipPrompts) return suggestion;
+	return requirePrompt(await text({
+		message: "Document name",
+		defaultValue: suggestion,
+		placeholder: suggestion,
+		validate: (value) => {
+			if (!value) return;
+			const result = validateDocumentName({
+				name: value,
+				existingNames
+			});
+			return result.ok ? void 0 : result.reason;
+		}
+	})) || suggestion;
+}
+async function resolveStylingMethod(args) {
+	const { provided, framework, skipPrompts } = args;
+	if (provided) return provided;
+	if (skipPrompts) return DEFAULT_STYLING;
+	return requirePrompt(await select({
+		message: "Styling method",
+		initialValue: DEFAULT_STYLING,
+		options: methodsForFramework(framework).map((method) => ({
+			value: method,
+			label: STYLING_LABELS[method]
+		}))
+	}));
+}
+function isSchemaChoice(value) {
+	return value === "none" || SCHEMA_KINDS.includes(value);
+}
+async function resolveSchema(args) {
+	const { provided, skipPrompts } = args;
+	if (provided !== void 0) {
+		if (!isSchemaChoice(provided)) throw new CliError(`Invalid --schema: "${provided}". Choices: none, ${SCHEMA_KINDS.join(", ")}.`);
+		return provided;
+	}
+	if (skipPrompts) return "none";
+	return requirePrompt(await select({
+		message: "Schema",
+		initialValue: "none",
+		options: [{
+			value: "none",
+			label: "None"
+		}, ...SCHEMA_KINDS.map((kind) => ({
+			value: kind,
+			label: SCHEMA_LABELS[kind]
+		}))]
+	}));
+}
+function parseDimension(args) {
+	const { flag, value } = args;
+	const parsed = Number(value);
+	if (!isValidDimension(parsed)) throw new CliError(`Invalid ${flag}: "${value}". Enter a number of CSS pixels from 1 to 20000.`);
+	return parsed;
+}
+async function promptCustomDimensions() {
+	const dimensionValidator = (value) => {
+		if (!value) return;
+		return isValidDimension(Number(value)) ? void 0 : "Enter a number of CSS pixels from 1 to 20000.";
+	};
+	const width = requirePrompt(await text({
+		message: "Width (px)",
+		defaultValue: "794",
+		placeholder: "794",
+		validate: dimensionValidator
+	}));
+	const height = requirePrompt(await text({
+		message: "Height (px)",
+		defaultValue: "1123",
+		placeholder: "1123",
+		validate: dimensionValidator
+	}));
+	return {
+		width: Number(width || "794"),
+		height: Number(height || "1123")
+	};
+}
+async function resolveDimensions(args) {
+	const { size, width, height, skipPrompts } = args;
+	if (width !== void 0 && height !== void 0) return {
+		width: parseDimension({
+			flag: "--width",
+			value: width
+		}),
+		height: parseDimension({
+			flag: "--height",
+			value: height
+		})
+	};
+	if (size && size !== "custom") {
+		const match$1 = PAGE_SIZES.find((candidate) => candidate.id === size);
+		if (!match$1) throw new CliError(`Invalid --size: "${size}". Choices: ${PAGE_SIZES.map((candidate) => candidate.id).join(", ")}, custom.`);
+		return {
+			width: match$1.width,
+			height: match$1.height
+		};
+	}
+	if (size === "custom" && (width === void 0 || height === void 0)) {
+		if (skipPrompts) throw new CliError("--size custom requires --width and --height.");
+		return promptCustomDimensions();
+	}
+	if (skipPrompts || size !== void 0) return;
+	const choice = requirePrompt(await select({
+		message: "Page size",
+		initialValue: DEFAULT_PAGE_SIZE_ID,
+		options: [...PAGE_SIZES.map((candidate) => ({
+			value: candidate.id,
+			label: `${candidate.name} (${candidate.label})`
+		})), {
+			value: "custom",
+			label: "Custom…"
+		}]
+	}));
+	if (choice === "custom") return promptCustomDimensions();
+	const match = PAGE_SIZES.find((candidate) => candidate.id === choice);
+	return match ? {
+		width: match.width,
+		height: match.height
+	} : void 0;
+}
+async function resolveData(args) {
+	const { provided, skipPrompts } = args;
+	const path = provided ?? (skipPrompts ? void 0 : await promptDataPath());
+	if (!path) return;
+	const resolved = resolve(process.cwd(), path);
+	let raw;
+	try {
+		raw = await readFile(resolved, "utf8");
+	} catch {
+		throw new CliError(`Couldn't read the data file at "${path}".`);
+	}
+	try {
+		return JSON.parse(raw);
+	} catch {
+		throw new CliError(`The data file at "${path}" isn't valid JSON.`);
+	}
+}
+async function promptDataPath() {
+	if (!requirePrompt(await confirm({
+		message: "Seed the default variant from a JSON file?",
+		initialValue: false
+	}))) return;
+	return requirePrompt(await text({
+		message: "Path to the JSON file",
+		placeholder: "./data.json",
+		validate: (value) => value && value.trim() !== "" ? void 0 : "Enter a path, or press Ctrl+C to skip."
+	})).trim();
+}
+function reportPrerequisites(prerequisites) {
+	if (prerequisites.missingConfig.length === 0) return;
+	const steps = prerequisites.missingConfig.map((config) => `• ${config.description}`);
+	log.warn(`To finish setting up ${STYLING_LABELS[prerequisites.method]}:\n${steps.join("\n")}`);
+}
+function isFramework$2(value) {
+	return value === "react" || value === "vue" || value === "html";
+}
+async function loadProject(cwd) {
+	const configPath = findConfigPath(cwd, { baseName: process.env.FMT_CONFIG_FILE_NAME });
+	if (!configPath) throw new CliError("No Format project found here. Run `npm create format@latest` to start a project, then try again.");
+	const configFile = await readConfigFile(configPath);
+	const framework = configFile.config.framework;
+	if (!isFramework$2(framework)) throw new CliError(`Invalid "framework" in ${configPath}: expected "react", "vue", or "html".`);
+	return {
+		config: {
+			framework,
+			rootDir: typeof configFile.config.rootDir === "string" ? configFile.config.rootDir : void 0
+		},
+		projectRoot: dirname(configPath),
+		formatConfigPath: configPath
+	};
+}
+async function newDocumentCommand(cwd, name, options) {
+	const { config, projectRoot, formatConfigPath } = await loadProject(cwd);
+	const empty = options.empty === true;
+	const skipPrompts = options.yes === true;
+	const embedded = options.embedded === true;
+	const incomingDependencies = options.incomingDependencies ?? [];
+	const documentsDir = getDocumentsDir({
+		projectRoot,
+		config
+	});
+	const existingNames = await readExistingDocumentNames(documentsDir);
+	try {
+		if (!embedded) intro(pc.bgCyan(pc.black(" Format ")));
+		const resolvedName = await resolveName({
+			provided: name,
+			existingNames,
+			skipPrompts
+		});
+		const styling = await resolveStylingMethod({
+			provided: options.styling,
+			framework: config.framework,
+			skipPrompts
+		});
+		const schemaChoice = empty ? "none" : await resolveSchema({
+			provided: options.schema,
+			skipPrompts
+		});
+		const emitSchema = schemaChoice !== "none";
+		const schemaKind = schemaChoice === "none" ? void 0 : schemaChoice;
+		const data = empty ? void 0 : await resolveData({
+			provided: options.data,
+			skipPrompts
+		});
+		const dimensions = await resolveDimensions({
+			size: options.size,
+			width: options.width,
+			height: options.height,
+			skipPrompts
+		});
+		const result = await createDocument({
+			config,
+			projectRoot,
+			name: resolvedName,
+			styling,
+			emitSchema,
+			schemaKind,
+			data,
+			width: dimensions?.width,
+			height: dimensions?.height,
+			empty
+		});
+		const documentDependencies = await writeDocumentDependencies({
+			projectRoot,
+			emitSchema,
+			schemaKind,
+			missingStylingDependencies: result.prerequisites.missingDependencies.map((dependency) => dependency.name)
+		});
+		const finalize = await finalizeDependencies({
+			projectDir: projectRoot,
+			addedDependencies: [...incomingDependencies, ...documentDependencies],
+			install: options.install === false ? false : void 0,
+			skipPrompts
+		});
+		if (finalize.result && !finalize.installed) log.error(`Failed to install dependencies automatically: ${finalize.result.message ?? "unknown error"}`);
+		const projectSetup = await maybeSetupProject({
+			wanted: finalize.wantInstall,
+			styling,
+			config,
+			projectRoot,
+			formatConfigPath,
+			documentsGlobBase: relative(projectRoot, documentsDir)
+		});
+		if (projectSetup) log.success(`Set up ${styling}\n${projectSetup.summary.map((line) => pc.dim(line)).join("\n")}`);
+		log.success(`Created document ${pc.cyan(result.documentName)}\n${pc.dim(result.documentDir)}`);
+		if (!finalize.installed) reportPrerequisites(result.prerequisites);
+		const openLine = `Open it in Studio: ${pc.cyan(`${STUDIO_URL}/${result.documentName}`)}`;
+		if (embedded) log.info(openLine);
+		if (!embedded) outro(openLine);
+		return 0;
+	} catch (error) {
+		if (isPromptCancelledError(error)) return 0;
+		const message = error instanceof Error ? error.message : String(error);
+		log.error(message);
+		return 1;
+	}
+}
+
+//#endregion
+//#region src/cli/commands/init.ts
+const SCHEMA_URL = "https://format.dev/schema/format-config.json";
+const GITIGNORE_ENTRIES = [
+	"_generated",
+	".env",
+	"format-env.d.ts"
+];
+const FORMAT_ENV_TYPES = `/// <reference types="@format.dev/cli/env" />
+
+// This file is managed by Format and regenerated with your document types when
+// you compile. Do not edit.
+`;
+function isFramework$1(value) {
+	return SUPPORTED_FRAMEWORKS.includes(value);
+}
+function detectFramework(packageJson) {
+	const dependencyNames = Object.keys({
+		...packageJson.dependencies,
+		...packageJson.devDependencies
+	});
+	if (dependencyNames.includes("react")) return "react";
+	if (dependencyNames.includes("vue")) return "vue";
+	return "html";
+}
+async function resolveFramework$1(args) {
+	const { provided, detected, skipPrompts } = args;
+	if (provided !== void 0) {
+		if (!isFramework$1(provided)) throw new CliError(`Invalid --framework: "${provided}". Choices: ${SUPPORTED_FRAMEWORKS.join(", ")}.`);
+		return provided;
+	}
+	if (skipPrompts) return detected;
+	return requirePrompt(await select({
+		message: "How do you want to build your PDFs?",
+		initialValue: detected,
+		options: [
+			{
+				value: "html",
+				label: "HTML"
+			},
+			{
+				value: "react",
+				label: "React"
+			},
+			{
+				value: "vue",
+				label: "Vue"
+			}
+		]
+	}));
+}
+async function shouldRun(message, skipPrompts) {
+	if (skipPrompts) return true;
+	return requirePrompt(await confirm({
+		message,
+		initialValue: true
+	}));
+}
+function normalizeRootDir(rootDir) {
+	if (rootDir === void 0) return;
+	const trimmed = rootDir.trim();
+	if (trimmed === "" || trimmed === "." || trimmed === "./") return;
+	return trimmed;
+}
+async function writeFormatConfig(args) {
+	const { projectDir, framework, version, rootDir } = args;
+	const configPath = join(projectDir, "format.config.json");
+	const config = {
+		$schema: SCHEMA_URL,
+		version,
+		framework,
+		...rootDir ? { rootDir } : {}
+	};
+	await fs.writeFile(configPath, `${JSON.stringify(config, null, "	")}\n`, "utf8");
+	return configPath;
+}
+async function addPackageScripts(projectDir) {
+	const packageJsonPath = join(projectDir, "package.json");
+	const raw = await fs.readFile(packageJsonPath, "utf8");
+	const packageJson = JSON.parse(raw);
+	const scripts = { ...packageJson.scripts ?? {} };
+	const wanted = [["dev", "format dev"], ["compile", "format compile"]];
+	const added = [];
+	const renamed = [];
+	const resolvedName = {};
+	for (const [name, command] of wanted) {
+		if (scripts[name] === command) {
+			resolvedName[name] = name;
+			continue;
+		}
+		if (scripts[`format:${name}`] === command) {
+			resolvedName[name] = `format:${name}`;
+			continue;
+		}
+		if (scripts[name] === void 0) {
+			scripts[name] = command;
+			added.push([name, command]);
+			resolvedName[name] = name;
+			continue;
+		}
+		scripts[`format:${name}`] = command;
+		renamed.push([`format:${name}`, command]);
+		resolvedName[name] = `format:${name}`;
+	}
+	if (added.length > 0 || renamed.length > 0) {
+		packageJson.scripts = scripts;
+		const indent = detectIndent(raw);
+		await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, indent)}\n`, "utf8");
+	}
+	return {
+		added,
+		renamed,
+		devScriptName: resolvedName.dev
+	};
+}
+async function updateGitignore(projectDir) {
+	const gitignorePath = join(projectDir, ".gitignore");
+	const existing = existsSync(gitignorePath) ? await fs.readFile(gitignorePath, "utf8") : "";
+	const lines = existing.split("\n").map((line) => line.trim());
+	const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.includes(entry));
+	if (missing.length === 0) return [];
+	const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
+	await fs.writeFile(gitignorePath, `${existing}${separator}${missing.join("\n")}\n`, "utf8");
+	return missing;
+}
+function packagesForFramework(framework) {
+	if (framework === "react") return ["@format.dev/react", "@format.dev/client"];
+	if (framework === "vue") return ["@format.dev/vue", "@format.dev/client"];
+	return ["@format.dev/client"];
+}
+function formatDependencySpecs(framework, version) {
+	const dependencyVersion = formatDependencyVersion(version);
+	const packages = packagesForFramework(framework).map((name) => ({
+		name,
+		version: dependencyVersion,
+		dev: !RUNTIME_PACKAGES.includes(name)
+	}));
+	const linked = devOnlyWorkspacePackages().map((name) => ({
+		name,
+		version: WORKSPACE_VERSION,
+		dev: true
+	}));
+	return [...packages, ...linked];
+}
+async function initCommand(cwd, options) {
+	const skipPrompts = options.yes === true;
+	const configPath = join(cwd, "format.config.json");
+	const configPathJsonc = join(cwd, "format.config.jsonc");
+	if (existsSync(configPath) || existsSync(configPathJsonc)) throw new CliError("This project is already set up: a format.config file exists here.");
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) throw new CliError("No package.json found. Run `format init` in the root of an existing project, or start fresh with `npm create format`.");
+	try {
+		intro(pc.bgCyan(pc.black(" Format ")));
+		const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+		const framework = await resolveFramework$1({
+			provided: options.framework,
+			detected: detectFramework(packageJson),
+			skipPrompts
+		});
+		const version = jsVersion;
+		const rootDir = normalizeRootDir(options.rootDir);
+		await writeFormatConfig({
+			projectDir: cwd,
+			framework,
+			version,
+			rootDir
+		});
+		const documentsDir = getDocumentsDir({
+			projectRoot: cwd,
+			config: {
+				framework,
+				rootDir
+			}
+		});
+		await fs.mkdir(documentsDir, { recursive: true });
+		const documentsPath = relative(cwd, documentsDir);
+		await fs.writeFile(join(cwd, "format-env.d.ts"), FORMAT_ENV_TYPES, "utf8");
+		const configLine = `Created ${pc.cyan("format.config.json")} ${pc.dim(`(Format ${version}, ${framework})`)}`;
+		log.success(`${configLine}\n${pc.dim(`Documents directory: ${documentsPath}`)}`);
+		let devScriptName;
+		if (options.scripts && await shouldRun("Add format npm scripts to package.json?", skipPrompts)) {
+			const { added, renamed, devScriptName: resolvedDevScript } = await addPackageScripts(cwd);
+			devScriptName = resolvedDevScript;
+			const scriptLines = [...added, ...renamed].map(([name, command]) => `${pc.cyan(name)}: ${pc.dim(command)}`);
+			if (renamed.length > 0) scriptLines.push(pc.dim("Some script names were taken, so those use a format: prefix."));
+			log.success(`Added npm scripts\n${scriptLines.join("\n")}`);
+		}
+		if (options.gitignore && await shouldRun("Update .gitignore?", skipPrompts)) {
+			const appended = await updateGitignore(cwd);
+			if (appended.length > 0) log.success(`Added to .gitignore: ${pc.dim(appended.join(", "))}`);
+		}
+		const addedFormatPackages = await writeDependenciesToManifest({
+			projectDir: cwd,
+			dependencies: formatDependencySpecs(framework, version)
+		});
+		const createDocumentNow = options.document && await shouldRun("Create your first document?", skipPrompts);
+		if (createDocumentNow) {
+			const exitCode = await newDocumentCommand(cwd, void 0, {
+				yes: options.yes,
+				install: options.install,
+				embedded: true,
+				incomingDependencies: addedFormatPackages
+			});
+			if (exitCode !== 0) return exitCode;
+		}
+		if (!createDocumentNow) {
+			await fs.writeFile(join(documentsDir, ".gitkeep"), "", "utf8");
+			await finalizeDependencies({
+				projectDir: cwd,
+				addedDependencies: addedFormatPackages,
+				install: options.install ? void 0 : false,
+				skipPrompts
+			});
+		}
+		const startCommand = devScriptName ? `npm run ${devScriptName}` : "format dev";
+		outro(`Format is set up. Start Studio with ${pc.cyan(startCommand)}`);
+		return 0;
+	} catch (error) {
+		if (isPromptCancelledError(error)) return 0;
+		throw error;
+	}
+}
+
+//#endregion
+//#region src/cli/commands/remove.ts
+function normalisePackageName(name) {
+	if (name.startsWith("@format.dev/")) return name;
+	return `@format.dev/${name}`;
+}
+function removeArgs(packageManager, packages) {
+	if (packageManager === "npm") return ["uninstall", ...packages];
+	return ["remove", ...packages];
+}
+async function removeCommand(cwd, packages) {
+	if (packages.length === 0) throw new CliError("Usage: format remove <package> [...] — e.g. `format remove zip`.");
+	const state = await loadProjectState(cwd);
+	if (!state.packageJsonPath) throw new CliError("No package.json found next to the config — nothing to remove from.");
+	const names = packages.map(normalisePackageName);
+	if (names.includes("@format.dev/cli")) throw new CliError("Refusing to remove @format.dev/cli through itself. Use your package manager directly: `npm uninstall \"@format.dev/cli\"`.");
+	const installedNames = state.dependencies.map((dependency) => dependency.name);
+	const notInstalled = names.filter((name) => !installedNames.includes(name));
+	if (notInstalled.length > 0) throw new CliError(`Not installed in this project: ${notInstalled.join(", ")}.`);
+	const packageManager = await detectPackageManager(state.projectDir);
+	console.log(`Removing ${names.join(", ")} with ${packageManager}...`);
+	await runRemove(packageManager, removeArgs(packageManager, names), state.projectDir);
+	console.log("");
+	console.log("Done.");
+	return 0;
+}
+async function runRemove(packageManager, args, cwd) {
+	await new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(commandForPlatform(packageManager), args, {
+			cwd,
+			stdio: "inherit",
+			shell: false
+		});
+		child.on("error", (error) => {
+			rejectPromise(new CliError(`Failed to run ${packageManager}: ${error.message}`));
+		});
+		child.on("exit", (code) => {
+			if (code === 0) {
+				resolvePromise();
+				return;
+			}
+			rejectPromise(new CliError(`${packageManager} exited with code ${code}.`));
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/commands/new-project.ts
+function isFramework(value) {
+	return SUPPORTED_FRAMEWORKS.includes(value);
+}
+async function resolveDirectory(provided, skipPrompts) {
+	if (provided) return provided;
+	if (skipPrompts) return "./my-format-project";
+	return requirePrompt(await text({
+		message: "Where should we create your project?",
+		placeholder: "./my-format-project",
+		defaultValue: "./my-format-project"
+	}));
+}
+async function resolveFramework(provided, skipPrompts) {
+	if (provided !== void 0) {
+		if (!isFramework(provided)) throw new CliError(`Invalid --framework: "${provided}". Choices: ${SUPPORTED_FRAMEWORKS.join(", ")}.`);
+		return provided;
+	}
+	if (skipPrompts) return "react";
+	return requirePrompt(await select({
+		message: "How do you want to build your PDFs?",
+		options: [
+			{
+				value: "html",
+				label: "HTML"
+			},
+			{
+				value: "react",
+				label: "React"
+			},
+			{
+				value: "vue",
+				label: "Vue"
+			}
+		],
+		initialValue: "react"
+	}));
+}
+async function resolveInstall(provided, skipPrompts) {
+	if (provided !== void 0) return provided;
+	if (skipPrompts) return true;
+	return requirePrompt(await confirm({
+		message: "Automatically install dependencies?",
+		initialValue: true
+	}));
+}
+function runDevLine(packageManager) {
+	return packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
+}
+async function newProjectCommand(cwd, providedDirectory, options) {
+	const skipPrompts = options.yes === true;
+	intro(pc.bgCyan(pc.black(" Format ")));
+	try {
+		const directory = await resolveDirectory(providedDirectory, skipPrompts);
+		const framework = await resolveFramework(options.framework, skipPrompts);
+		const wantInstall = await resolveInstall(options.install, skipPrompts);
+		const scaffold = spinner();
+		scaffold.start("Creating project");
+		const { dirPath } = await scaffoldProject({
+			directory,
+			framework,
+			cwd
+		});
+		scaffold.stop(`Created a ${pc.cyan(framework)} project in ${pc.cyan(directory)}`);
+		let packageManager = await detectPackageManager(cwd);
+		let needsInstall = !wantInstall;
+		if (wantInstall) {
+			const install = spinner();
+			install.start(`Installing dependencies with ${packageManager}`);
+			const result = await installProjectDependencies({
+				dirPath,
+				preferredPackageManager: packageManager,
+				onProgress: (line) => install.message(truncateForSpinner(line))
+			});
+			if (result.ok) {
+				packageManager = result.packageManagerUsed;
+				needsInstall = false;
+				install.stop(`Dependencies installed with ${pc.cyan(packageManager)}`);
+				if (result.fellBackToNpm) log.warn("Could not find your package manager. Fell back to npm.");
+			}
+			if (!result.ok) {
+				needsInstall = true;
+				install.error(`Could not install dependencies with ${packageManager}`);
+				log.error(result.message ?? "unknown error");
+				if (result.output) log.message(pc.dim(result.output));
+				if (await templateUsesWorkspaceDeps(dirPath)) log.warn("This template uses `workspace:*` deps, which only install inside a workspace.");
+			}
+		}
+		const steps = [`cd ${directory}`];
+		if (needsInstall) {
+			const { command, args } = installCommand(packageManager);
+			steps.push(`${command} ${args.join(" ")}`);
+		}
+		steps.push(runDevLine(packageManager));
+		outro(`Start Studio with ${pc.cyan(steps.join(" && "))}`);
+		return 0;
+	} catch (error) {
+		if (isPromptCancelledError(error)) return 0;
+		throw error;
+	}
+}
+
+//#endregion
+//#region src/cli/commands/update.ts
+async function updateCommand(cwd, target) {
+	const state = await loadProjectState(cwd);
+	const targetVersion = await resolveTargetVersion({
+		target,
+		pinnedVersion: state.pinnedVersion
+	});
+	if (targetVersion !== state.pinnedVersion) {
+		await writeConfigVersion({
+			filepath: state.configFile.filepath,
+			version: targetVersion
+		});
+		console.log(`Pinned Format ${targetVersion} in ${state.configFile.filepath}`);
+	} else console.log(`Applying pinned Format ${targetVersion}`);
+	if (!state.packageJsonPath) {
+		console.log("No package.json found next to the config — nothing to install.");
+		return 0;
+	}
+	const rewritten = await rewriteFormatDependencies({
+		packageJsonPath: state.packageJsonPath,
+		version: targetVersion
+	});
+	if (rewritten.length === 0) {
+		console.log("All installed Format packages already match.");
+		return 0;
+	}
+	for (const change of rewritten) console.log(`  ${change.name}  ${change.from} → ${change.to}`);
+	const packageManager = await detectPackageManager(state.projectDir);
+	const { command, args } = installCommand(packageManager);
+	console.log("");
+	console.log(`Installing with ${packageManager}...`);
+	await runInstall({
+		command,
+		args,
+		cwd: state.projectDir
+	});
+	console.log("");
+	console.log(`Done. Your project is on Format ${targetVersion}.`);
+	return 0;
+}
+async function resolveTargetVersion(args) {
+	const { target, pinnedVersion } = args;
+	if (target === "latest") return fetchLatestVersion();
+	if (target) {
+		if (!isExactVersion(target)) throw new CliError(`"${target}" is not an exact version. Use a version like 0.1.2, or \`format update latest\`.`);
+		return target;
+	}
+	if (pinnedVersion) return pinnedVersion;
+	throw new CliError("format.config.json is missing its required \"version\" field. Run `format update latest` to pin the newest release, or `format init` to set the project up.");
+}
+async function runInstall(args) {
+	const { command, args: commandArgs, cwd } = args;
+	await new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(command, commandArgs, {
+			cwd,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		child.on("error", (error) => {
+			rejectPromise(new CliError(`Failed to run ${command} install: ${error.message}`));
+		});
+		child.on("exit", (code) => {
+			if (code === 0) {
+				resolvePromise();
+				return;
+			}
+			rejectPromise(new CliError(`${command} install exited with code ${code}.`));
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/commands/version.ts
+async function versionCommand(cwd) {
+	const state = await loadProjectState(cwd);
+	if (!state.pinnedVersion) {
+		console.log(`No "version" field found in ${state.configFile.filepath}.`);
+		console.log("Run `format update latest` to pin the latest Format release.");
+		return 1;
+	}
+	console.log(`Format ${state.pinnedVersion}`);
+	if (state.mismatches.length > 0) {
+		console.log("");
+		console.log("Some installed Format packages do not match the pinned version:");
+		for (const mismatch of state.mismatches) console.log(`  ${mismatch.name}  ${mismatch.actual} (expected ${mismatch.expected})`);
+		console.log("");
+		console.log("Run `format update` to bring everything in line.");
+		return 1;
+	}
+	const alignedCount = state.dependencies.length;
+	if (alignedCount > 0) {
+		const names = state.dependencies.map((dependency) => dependency.name).join(", ");
+		console.log(`${alignedCount} installed Format package${alignedCount === 1 ? "" : "s"}: ${names}`);
+	}
+	await reportNewerRelease(state.pinnedVersion);
+	return 0;
+}
+
+//#endregion
+//#region src/cli/index.ts
+const STUDIO_COMMANDS = [
+	{
+		name: "dev",
+		description: "Open Studio for this project."
+	},
+	{
+		name: "compile",
+		description: "Compile this project's documents into a renderer."
+	},
+	{
+		name: "clear-cache",
+		description: "Clear Studio's local cache."
+	}
+];
+function createCommanderOption(optionSpec) {
+	const option = new Option(optionSpec.flags, optionSpec.description);
+	if (optionSpec.choices && optionSpec.choices.length > 0) option.choices(optionSpec.choices);
+	return option;
+}
+function registerArguments(command, argumentSpecs) {
+	if (!argumentSpecs) return;
+	for (const argumentSpec of argumentSpecs) {
+		const token = argumentSpec.required ? `<${argumentSpec.name}>` : `[${argumentSpec.name}]`;
+		command.argument(token, argumentSpec.description);
+	}
+}
+function registerCommand(parent, commandSpec, path, handlers) {
+	const command = parent.command(commandSpec.name).description(commandSpec.description);
+	registerArguments(command, commandSpec.arguments);
+	for (const optionSpec of commandSpec.options) command.addOption(createCommanderOption(optionSpec));
+	const fullPath = [...path, commandSpec.name];
+	if (commandSpec.commands && commandSpec.commands.length > 0) {
+		for (const childSpec of commandSpec.commands) registerCommand(command, childSpec, fullPath, handlers);
+		return;
+	}
+	const key = fullPath.join(" ");
+	const handler = handlers[key];
+	if (!handler) throw new Error(`Missing command handler for "${key}"`);
+	command.action(async (...args) => {
+		process.exitCode = await handler(...args);
+	});
+}
+function createProgram() {
+	const program = new Command();
+	const cliSpec = cli_spec_default;
+	const cwd = process.cwd();
+	program.name("format").description("The Format CLI: create projects and documents, run Studio, compile renderers, and keep every Format package on one release.").enablePositionalOptions();
+	const handlers = {
+		"new project": (directory, options) => newProjectCommand(cwd, directory, options),
+		"new document": (name, options) => newDocumentCommand(cwd, name, options),
+		init: (options) => initCommand(cwd, options),
+		add: (packages) => addCommand(cwd, packages),
+		remove: (packages) => removeCommand(cwd, packages),
+		update: (version) => updateCommand(cwd, version),
+		version: () => versionCommand(cwd)
+	};
+	for (const commandSpec of cliSpec.commands) registerCommand(program, commandSpec, [], handlers);
+	for (const { name, description } of STUDIO_COMMANDS) program.command(name).description(description).helpOption(false).allowUnknownOption().passThroughOptions().argument("[args...]").action(async (_args, _options, command) => {
+		process.exitCode = await runStudioCommand(cwd, [name, ...command.args]);
+	});
+	return program;
+}
+
+//#endregion
+//#region src/cli/bin.ts
+try {
+	await createProgram().parseAsync();
+} catch (error) {
+	if (error instanceof CliError) {
+		console.error(error.message);
+		process.exitCode = 1;
+	} else throw error;
+}
+
+//#endregion
+export {  };