@monimesl/dot-cli 0.1.0-alpha.8 → 1.0.0-beta.0

package/dist/cli.js

@@ -1,31 +1,39 @@
 import { createRequire } from "node:module";
 import { spawn, spawnSync } from "node:child_process";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { parseArgs } from "node:util";
-import { CompileError, PAGES_DIR, build, installedRuntime, loadProject } from "@monimesl/dot-compiler";
+import { parseArgs, styleText } from "node:util";
+import { CompileError, DOT_FILE, DOT_JSON_FILE, PAGES_DIR, build, installedRuntime, isDotPackage, loadProject } from "@monimesl/dot-compiler";
 import { DEFAULT_PORT, startSimulator } from "@monimesl/dot-simulator";
 import { existsSync, readFileSync, readdirSync, watch } from "node:fs";
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { DmlParseError } from "@monimesl/dot-dml-parser";
 import { ScriptParseError, parseDotModule } from "@monimesl/dot-script-parser";
-import { isPageId } from "@monimesl/dot-core";
+import { DEFAULT_DASH_API_VERSION, isPageId } from "@monimesl/dot-core";
 import { renderUnicodeCompact } from "uqr";
 import { createHash, createHmac, createPrivateKey, createPublicKey, randomBytes, sign, timingSafeEqual } from "node:crypto";
 import { homedir, networkInterfaces } from "node:os";
 import { createServer } from "node:http";
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
 //#region src/report.ts
-/** A mistake in how a command was used, which its message alone explains. */
 var CommandError = class extends Error {
 	name = "CommandError";
 };
 function describeError(error) {
 	if (error instanceof CommandError || error instanceof CompileError || error instanceof DmlParseError || error instanceof ScriptParseError) return error.message;
-	if (error.code?.startsWith("ERR_PARSE_ARGS")) {
+	if (isArgumentError(error)) {
 		const [firstSentence] = error.message.split(". ");
 		return `${firstSentence}. See dotctl --help.`;
 	}
-	return error instanceof Error ? error.stack ?? error.message : String(error);
+	if (error instanceof Error) return error.stack ?? error.message;
+	return String(error);
+}
+function isArgumentError(error) {
+	if (!(error instanceof Error) || !("code" in error)) return false;
+	return typeof error.code === "string" && error.code.startsWith("ERR_PARSE_ARGS");
+}
+function printFiles(files) {
+	for (const file of files) console.log(`  ${relative(process.cwd(), file)}`);
 }
 function printWarnings({ warnings }) {
 	for (const warning of warnings) console.warn(`warning: ${warning.message}`);
@@ -33,11 +41,38 @@ function printWarnings({ warnings }) {
 function printBuildTime(startedAt) {
 	console.log(`Built in ${Math.round(performance.now() - startedAt)}ms`);
 }
+function printSimulatorUrl(url) {
+	console.log(`\n  Simulator running at: ${url}\n`);
+}
+//#endregion
+//#region src/utils.ts
+function findFolderWith(fileName, dir) {
+	let current = dir;
+	while (true) {
+		if (existsSync(join(current, fileName))) return current;
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+}
+function findDotRoot(dir) {
+	return findFolderWith(DOT_JSON_FILE, dir);
+}
+function resolveOutDir(root, outDir) {
+	return resolve(root, outDir ?? "dist");
+}
+function isOneOf(values, name) {
+	return values.includes(name);
+}
 //#endregion
 //#region src/create/template.ts
 const TEMPLATES = ["starter", "showcase"];
+const TEMPLATE_HINTS = {
+	starter: "one page to build on",
+	showcase: "a page for each feature, to learn from"
+};
 function isTemplate(name) {
-	return TEMPLATES.includes(name);
+	return isOneOf(TEMPLATES, name);
 }
 const PAGE_FILES = {
 	"view.dml": "<View>\n	<Text>My new page</Text>\n</View>\n",
@@ -55,9 +90,9 @@ const TEMPLATE_FILES = [
 	"statics",
 	".env"
 ];
-const DOT_JSON_SCHEMA = "./node_modules/@monimesl/dot-runtime/dot.schema.json";
-const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
-function projectFiles(options) {
+const DOT_JSON_SCHEMA = "https://unpkg.com/@monimesl/dot-runtime/dot.schema.json";
+const UNREGISTERED_DOT_ID = "<monime-Internal-Id>";
+function generatedFiles(options) {
 	return {
 		"package.json": packageJson(options),
 		"tsconfig.json": tsconfig(options),
@@ -68,13 +103,14 @@ function projectFiles(options) {
 }
 function packageJson({ packageName, dotVersion, workspace }) {
 	const conditions = workspace ? " --conditions @monimesl/dot-source" : "";
-	return json({
+	return formatJson({
 		name: packageName,
 		private: true,
 		type: "module",
 		scripts: {
 			dev: `dotctl dev${conditions}`,
 			build: `dotctl build${conditions}`,
+			preview: `dotctl preview${conditions}`,
 			typecheck: "tsc --noEmit"
 		},
 		dependencies: { "@monimesl/dot-runtime": dotVersion },
@@ -97,7 +133,7 @@ function tsconfig({ workspace }) {
 		verbatimModuleSyntax: true
 	};
 	if (workspace) compilerOptions.customConditions = ["@monimesl/dot-source"];
-	return json({
+	return formatJson({
 		compilerOptions,
 		include: [
 			"dot.ts",
@@ -107,27 +143,40 @@ function tsconfig({ workspace }) {
 		]
 	});
 }
-function dotJson({ name, packageName, template }) {
+function dotJson({ name, dotPackage, template }) {
 	const dot = {
+		id: UNREGISTERED_DOT_ID,
 		$schema: DOT_JSON_SCHEMA,
-		id: `com.example.${idWord(packageName)}`,
+		package: dotPackage,
 		name,
 		version: "0.1.0"
 	};
-	if (template === "showcase") dot.network = { hosts: [
-		"api.github.com",
-		"avatars.githubusercontent.com",
-		"httpbin.org"
-	] };
-	return json(dot);
+	if (template === "showcase") {
+		dot.permissions = {
+			account: "Show your name on your concert ticket",
+			camera: "Take a photo for your concert ticket, or scan a ticket's QR code",
+			photoLibrary: "Choose a photo for your concert ticket",
+			files: "Attach your concert ticket",
+			contacts: "Choose a friend to send a ticket to",
+			payments: "Pay for concert tickets"
+		};
+		dot.network = { hosts: [
+			"itunes.apple.com",
+			"*.mzstatic.com",
+			"httpbin.org"
+		] };
+	}
+	dot.dash = { minApiVersion: DEFAULT_DASH_API_VERSION };
+	return formatJson(dot);
 }
 const TEMPLATE_READMES = {
-	starter: `It starts with one page, \`index\`: a greeting from \`.env\` and a count to tap. Change it,
-and add pages as the dot grows. \`npx dotctl create my-tour --template showcase\` makes a dot with a
-page for each feature, to read how each is done.`,
-	showcase: `It starts as a showcase: \`index\` lists a page for each feature, from layout, text, images and
-inputs to state, navigation, and Dash's alerts, network and files. Read a page to see how it's
-done, then delete the ones you don't need, from \`pages/\` and from \`dot.ts\`.`
+	starter: `It starts with one page, \`index\`. It shows a greeting from \`.env\` and a counter you
+can tap. Change it, and add pages as the dot grows. To see how each feature works, make a showcase
+dot with \`npx dotctl create my-tour --template showcase\`.`,
+	showcase: `It starts as a showcase. The \`index\` page links to a page for each feature, in three
+folders: \`pages/basics/\` for how a page works, \`pages/components/\` for what a view can show,
+and \`pages/dash/\` for the phone's features. Read a page to see how it works. Then delete the
+pages you don't need, both from \`pages/\` and from \`dot.ts\`.`
 };
 function readme({ name, template }) {
 	return `# ${name}
@@ -140,41 +189,67 @@ npm run dev     # run it in the simulator; it reloads on every change
 npm run build   # build it for Dash
 \`\`\`
 
-Each page is a folder under \`pages/\` with three files: \`view.dml\` (what it shows),
-\`state.ts\` (what it starts with) and \`controller.ts\` (how it changes). A page's markup is one
-root \`<View>\` with everything else inside it. \`npx dotctl create page <path>\` adds a page, such
-as \`cart/checkout\`, with the three files to start from, and lists it in \`dot.ts\`. The first page
-there is where the dot starts.
+${TEMPLATE_READMES[template]}
 
-\`dot.json\` describes the dot to Dash. Change its \`id\` from \`com.example.…\` to a reverse domain
-name you own before you publish: it can't change afterwards. Its \`network.hosts\` lists every host
-the dot sends requests to with \`dash.network\`; requests to any other fail. Your editor completes
-the other fields from the schema it points to.
+## Pages
 
-\`.env\` holds public configuration, which the service reads as \`env.GREETING\`. Every variable
-there is built into the dot, so anyone who has it can read them: never put a secret there.
-\`.env.development\` and \`.env.production\` override it for \`dev\` and \`build\`.
+Each page is a folder under \`pages/\` with three files:
 
-${TEMPLATE_READMES[template]}
+- \`view.dml\`: what the page shows. It has one root \`<View>\`, with everything else inside it.
+- \`state.ts\`: the data the page starts with.
+- \`controller.ts\`: how the data changes.
+
+\`npx dotctl create page <path>\` adds a page, such as \`cart/checkout\`, with these three files. It
+also lists the page in \`dot.ts\`. The dot opens on the first page in that list.
+
+## dot.json
+
+\`dot.json\` describes the dot to Dash. Its \`package\` is a reverse domain name you own, such as
+\`com.mysalone.thing\`. You can't change it after publishing. To publish, register the dot with
+Monime first, and replace its \`id\`, \`${UNREGISTERED_DOT_ID}\`, with the ID Monime gives you.
+\`network.hosts\` lists every host the dot sends requests to with \`dash.network\`. Requests to any
+other host fail. Your editor can complete the other fields from the schema the file points to.
+
+## Which Dash opens it
+
+\`dash.minApiVersion\` in \`dot.json\` is the Dash API version the dot needs, such as \`1.0\`. Dash
+opens the dot when it offers that version, or a newer minor of the same major. Each Dash call's docs
+say which version it came in, after \`@since\`. To use a newer call and still open on older Dash,
+keep \`minApiVersion\` and check \`this.dash.supports('contacts.pickPhone')\` before the call.
+\`dotctl dev\` warns when the dot makes a newer call without checking.
+
+## .env
+
+\`.env\` holds public configuration. Code in the dot reads each variable from \`env\`, such as
+\`env.GREETING\`. Every variable is built into the dot, so anyone who has the dot can read it.
+Never put a secret there. \`.env.development\` and \`.env.production\` override it for \`dev\` and
+\`build\`.
 `;
 }
-function idWord(packageName) {
-	return packageName.slice(0, 63).replace(/-+$/, "");
+function suggestedDotPackage(packageName) {
+	return `com.example.${packageName.slice(0, 63).replace(/-+$/, "")}`;
+}
+function formatJson(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
 }
 //#endregion
 //#region src/create/create.ts
-async function create({ name, dir, template = "starter" }) {
+const DOT_PACKAGE_RULE = "Use lowercase words joined by dots, such as com.mysalone.thing.";
+async function create({ name, dir, dotPackage, template = "starter" }) {
 	const root = resolve(dir);
-	if (existsSync(root) && readdirSync(root).length > 0) throw new CommandError(`${dir} already exists and is not empty`);
+	if (existsSync(root) && readdirSync(root).length > 0) throw new CommandError(`${dir} already exists and is not empty. Choose another folder`);
 	const packageName = toPackageName(name);
-	if (!packageName) throw new CommandError(`"${name}" needs at least one letter or digit`);
+	if (!packageName) throw new CommandError(`The name "${name}" needs at least one letter or digit`);
+	dotPackage ??= suggestedDotPackage(packageName);
+	if (!isDotPackage(dotPackage)) throw new CommandError(`"${dotPackage}" isn't a package name. ${DOT_PACKAGE_RULE}`);
 	const workspace = isInDotWorkspace(root);
 	const source = templateDir(template);
 	await mkdir(root, { recursive: true });
 	for (const path of TEMPLATE_FILES) await cp(join(source, path), join(root, path), { recursive: true });
-	const generated = projectFiles({
+	const generated = generatedFiles({
 		name,
 		packageName,
+		dotPackage,
 		dotVersion: workspace ? "workspace:*" : `^${cliVersion()}`,
 		workspace,
 		template
@@ -192,21 +267,16 @@ function toDisplayName(dir) {
 	return basename(resolve(dir)).split(/[-_\s]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 function isInDotWorkspace(dir) {
-	let current = dirname(dir);
-	while (true) {
-		if (existsSync(join(current, "pnpm-workspace.yaml"))) {
-			const runtimeManifest = join(current, "packages/runtime/package.json");
-			if (!existsSync(runtimeManifest)) return false;
-			return readPackageJson(runtimeManifest).name === "@monimesl/dot-runtime";
-		}
-		const parent = dirname(current);
-		if (parent === current) return false;
-		current = parent;
-	}
+	const workspaceRoot = findFolderWith("pnpm-workspace.yaml", dirname(dir));
+	if (workspaceRoot === void 0) return false;
+	const runtimeManifest = join(workspaceRoot, "packages/runtime/package.json");
+	if (!existsSync(runtimeManifest)) return false;
+	return readPackageJson(runtimeManifest).name === "@monimesl/dot-runtime";
 }
 function templateDir(template) {
 	const example = join(cliRoot(), "../../examples", template);
-	return existsSync(example) ? example : join(cliRoot(), "dist/templates", template);
+	if (existsSync(example)) return example;
+	return join(cliRoot(), "dist/templates", template);
 }
 function cliVersion() {
 	return readPackageJson(join(cliRoot(), "package.json")).version;
@@ -219,16 +289,12 @@ function cliRoot() {
 }
 //#endregion
 //#region src/create/page.ts
-/**
-* Adds a page to the dot around `cwd`: its folder under pages/, with its three files, listed last in
-* dot.ts.
-*/
 async function createPage(path, cwd) {
-	if (!isPageId(path)) throw new CommandError(`"${path}" is not a page path: use letters, digits, "-" and "_", with "/" between folders, such as "cart/checkout"`);
+	if (!isPageId(path)) throw new CommandError(`"${path}" is not a page path. Use letters, digits, "-" and "_", with "/" between folders, such as "cart/checkout"`);
 	const root = findDotRoot(resolve(cwd));
-	if (root === void 0) throw new CommandError("There is no dot.json here or in a folder above: run it inside a dot");
-	const dir = join(root, "pages", path);
-	if (existsSync(dir)) throw new CommandError(`pages/${path} already exists`);
+	if (root === void 0) throw new CommandError("There is no dot.json in this folder or any folder above it. Run this command inside a dot");
+	const dir = join(root, PAGES_DIR, path);
+	if (existsSync(dir)) throw new CommandError(`pages/${path} already exists. Choose another path`);
 	await mkdir(dir, { recursive: true });
 	const files = [];
 	for (const [name, content] of Object.entries(PAGE_FILES)) {
@@ -239,10 +305,10 @@ async function createPage(path, cwd) {
 	return {
 		dir,
 		files,
-		listing: await listPage(join(root, "dot.ts"), path)
+		listing: await addToDotPages(join(root, DOT_FILE), path)
 	};
 }
-async function listPage(dotFile, path) {
+async function addToDotPages(dotFile, path) {
 	if (!existsSync(dotFile)) return "manual";
 	const source = await readFile(dotFile, "utf8");
 	let dot;
@@ -252,23 +318,25 @@ async function listPage(dotFile, path) {
 		return "manual";
 	}
 	if (dot.pages.includes(path)) return "already";
-	const updated = withPage(source, dot.lastPage, path);
+	const updated = insertPage(source, dot.lastPage, path);
 	if (!listsPage(updated, dotFile, path)) return "manual";
 	await writeFile(dotFile, updated);
 	return "added";
 }
-function withPage(source, lastPage, path) {
+function insertPage(source, lastPage, path) {
 	const quote = source[lastPage.start] === "\"" ? "\"" : "'";
 	const page = `${quote}${path}${quote}`;
+	const before = source.slice(0, lastPage.end);
+	const after = source.slice(lastPage.end);
 	const lineStart = source.lastIndexOf("\n", lastPage.start - 1) + 1;
 	const indent = source.slice(lineStart, lastPage.start);
-	if (!/^\s*$/.test(indent)) return `${source.slice(0, lastPage.end)}, ${page}${source.slice(lastPage.end)}`;
-	const trailingComma = /^\s*,/.exec(source.slice(lastPage.end));
+	if (!/^\s*$/.test(indent)) return `${before}, ${page}${after}`;
+	const trailingComma = /^\s*,/.exec(after);
 	if (trailingComma) {
 		const end = lastPage.end + trailingComma[0].length;
 		return `${source.slice(0, end)}\n${indent}${page},${source.slice(end)}`;
 	}
-	return `${source.slice(0, lastPage.end)},\n${indent}${page}${source.slice(lastPage.end)}`;
+	return `${before},\n${indent}${page}${after}`;
 }
 function listsPage(source, dotFile, path) {
 	try {
@@ -277,14 +345,6 @@ function listsPage(source, dotFile, path) {
 		return false;
 	}
 }
-function findDotRoot(dir) {
-	while (true) {
-		if (existsSync(join(dir, "dot.json"))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return;
-		dir = parent;
-	}
-}
 //#endregion
 //#region src/create/package-manager.ts
 const PACKAGE_MANAGERS = [
@@ -294,15 +354,15 @@ const PACKAGE_MANAGERS = [
 	"bun"
 ];
 function isPackageManager(name) {
-	return PACKAGE_MANAGERS.includes(name);
+	return isOneOf(PACKAGE_MANAGERS, name);
 }
 function launchedBy(userAgent = process.env.npm_config_user_agent ?? "") {
 	return PACKAGE_MANAGERS.find((name) => userAgent.startsWith(`${name}/`)) ?? "npm";
 }
-function installedManagers(isInstalled = onPath) {
+function installedManagers(isInstalled = isOnPath) {
 	return PACKAGE_MANAGERS.filter(isInstalled);
 }
-function onPath(name) {
+function isOnPath(name) {
 	return spawnSync(name, ["--version"], {
 		stdio: "ignore",
 		shell: process.platform === "win32"
@@ -314,9 +374,9 @@ function defaultDeveloperKeyPath() {
 	return process.env.DOT_DEVELOPER_KEY ?? join(homedir(), ".dot", "developer-key.pem");
 }
 function missingDeveloperKeyHint(path = defaultDeveloperKeyPath()) {
-	return `  This computer has no developer key in ${path}, and Dash opens only signed links.\n  Make one with OpenSSL 3 (macOS's own openssl can't; brew install openssl):
+	return `  There is no developer key at ${path}. Dash only opens signed links.\n  Make one with OpenSSL 3. macOS's built-in openssl can't, so first run brew install openssl:
 
-    mkdir -p ${dirname(path)} && openssl genpkey -algorithm ed25519 -out ${path}\n\n  Then add the public key \`dotctl keys show\` prints to your Monime account.`;
+    mkdir -p ${dirname(path)} && openssl genpkey -algorithm ed25519 -out ${path}\n\n  Then run \`dotctl keys show\` and add the public key it prints to your Monime account.`;
 }
 async function loadDeveloperKey(path = defaultDeveloperKeyPath()) {
 	let pem;
@@ -327,20 +387,22 @@ async function loadDeveloperKey(path = defaultDeveloperKeyPath()) {
 		throw error;
 	}
 	const privateKey = createPrivateKey(pem);
-	if (privateKey.asymmetricKeyType !== "ed25519") throw new Error(`${path} is not an Ed25519 key`);
+	if (privateKey.asymmetricKeyType !== "ed25519") throw new Error(`${path} is not an Ed25519 key. Make one with: openssl genpkey -algorithm ed25519 -out ${path}`);
 	return toDeveloperKey(privateKey);
 }
 function toDeveloperKey(privateKey) {
-	const raw = Buffer.from(createPublicKey(privateKey).export({ format: "jwk" }).x, "base64url");
+	const publicKeyJwk = createPublicKey(privateKey).export({ format: "jwk" });
+	const rawPublicKey = Buffer.from(publicKeyJwk.x, "base64url");
 	return {
-		publicKey: raw.toString("base64"),
-		keyId: raw.subarray(0, 8).toString("hex"),
+		publicKey: rawPublicKey.toString("base64"),
+		keyId: rawPublicKey.subarray(0, 8).toString("hex"),
 		sign: (bytes) => sign(null, bytes, privateKey).toString("base64")
 	};
 }
 //#endregion
 //#region src/device/server.ts
 const DEVICE_SCHEME = "dotdev";
+const FILES_PATH = "/dev/files/";
 const WAIT_MS = 25e3;
 const MAX_LOG_BYTES = 1048576;
 const LINK_LIFETIME_SECONDS = 43200;
@@ -355,130 +417,173 @@ function signedLinkMessage(server, secret, expires, keyId) {
 	].join("\n");
 }
 function deviceToken(secret) {
-	return createHmac("sha256", Buffer.from(secret, "base64url")).update("dotdev-token", "utf8").digest("base64url");
+	return hmacWithSecret(secret, "dotdev-token");
 }
 function buildMac(secret, body) {
-	return createHmac("sha256", Buffer.from(secret, "base64url")).update(`dotdev-build\n${body}`, "utf8").digest("base64url");
+	return hmacWithSecret(secret, `dotdev-build\n${body}`);
 }
 async function startDeviceServer({ address = localNetworkAddress(), port = 0, onLog = () => {}, onConnect = () => {}, developerKey } = {}) {
-	if (address === void 0) throw new Error("This computer has no local network address for devices to reach it on");
-	const secret = randomBytes(16).toString("base64url");
-	const token = deviceToken(secret);
-	let signature = null;
-	let build = { files: /* @__PURE__ */ new Map() };
-	let generation = 0;
-	let hotSince = 0;
-	let error = null;
-	const waiting = /* @__PURE__ */ new Set();
-	const connected = /* @__PURE__ */ new Set();
-	const announce = () => {
-		generation += 1;
-		for (const wake of waiting) wake();
-	};
-	const server = createServer((request, response) => {
+	if (address === void 0) throw new Error("This computer has no local network address, so devices can't reach it. Connect to a network and try again");
+	const deviceServer = new LocalDeviceServer(onLog, onConnect);
+	await deviceServer.listen(port, address, developerKey);
+	return deviceServer;
+}
+var LocalDeviceServer = class {
+	#onLog;
+	#onConnect;
+	#secret = randomBytes(16).toString("base64url");
+	#token = deviceToken(this.#secret);
+	#server;
+	#waiting = /* @__PURE__ */ new Set();
+	#connected = /* @__PURE__ */ new Set();
+	#link = "";
+	#signature = null;
+	#files = /* @__PURE__ */ new Map();
+	#generation = 0;
+	#hotSince = 0;
+	#error = null;
+	constructor(onLog, onConnect) {
+		this.#onLog = onLog;
+		this.#onConnect = onConnect;
+		this.#server = createServer((request, response) => {
+			this.#handle(request, response);
+		});
+	}
+	get link() {
+		return this.#link;
+	}
+	async listen(port, address, developerKey) {
+		await new Promise((resolve, reject) => {
+			this.#server.once("error", reject);
+			this.#server.listen(port, address, () => resolve());
+		});
+		const { port: listeningPort } = this.#server.address();
+		const origin = `http://${address}:${listeningPort}`;
+		if (developerKey) {
+			const expires = Math.floor(Date.now() / 1e3) + LINK_LIFETIME_SECONDS;
+			const keyId = developerKey.keyId;
+			const message = signedLinkMessage(origin, this.#secret, expires, keyId);
+			const sig = developerKey.sign(Buffer.from(message, "utf8"));
+			this.#signature = {
+				expires,
+				keyId,
+				sig
+			};
+		}
+		const server = encodeURIComponent(origin);
+		this.#link = `${DEVICE_SCHEME}://connect?server=${server}&secret=${this.#secret}`;
+	}
+	async publish(dir, { hot = false } = {}) {
+		this.#files = await readBuild(dir);
+		this.#error = null;
+		this.#announce();
+		if (!hot) this.#hotSince = this.#generation;
+	}
+	fail(message) {
+		this.#error = message;
+		this.#announce();
+	}
+	close() {
+		this.#wakeWaitingDevices();
+		return new Promise((resolve) => {
+			this.#server.close(() => resolve());
+			this.#server.closeAllConnections();
+		});
+	}
+	#announce() {
+		this.#generation += 1;
+		this.#wakeWaitingDevices();
+	}
+	#wakeWaitingDevices() {
+		for (const wake of this.#waiting) wake();
+	}
+	#handle(request, response) {
 		const from = request.socket.remoteAddress ?? "a device";
 		if (request.method === "GET" && request.url === "/dev/link") {
-			if (signature) sendJson(response, signature);
-			else response.writeHead(404).end();
+			this.#sendSignature(response);
 			return;
 		}
-		if (!isAuthorized(request, token)) {
+		if (!isAuthorized(request, this.#token)) {
 			response.writeHead(401).end();
 			return;
 		}
 		const url = new URL(request.url ?? "/", "http://device");
 		const path = url.pathname;
-		if (request.method === "GET" && path === "/dev/build") {
-			if (!connected.has(from)) {
-				connected.add(from);
-				onConnect(from);
-			}
-			const files = Object.fromEntries([...build.files].map(([name, file]) => [name, file.hash]));
-			const body = JSON.stringify({
-				generation,
-				hotSince,
-				files,
-				error
-			});
-			response.writeHead(200, {
-				"content-type": "application/json",
-				[BUILD_MAC_HEADER]: buildMac(secret, body)
-			}).end(body);
-		} else if (request.method === "GET" && path.startsWith("/dev/files/")) {
-			if (url.searchParams.get("generation") !== String(generation)) {
-				response.writeHead(409).end();
-				return;
-			}
-			const name = path.slice(11).split("/").map(decodeURIComponent).join("/");
-			const file = build.files.get(name);
-			if (!file) {
-				response.writeHead(404).end();
-				return;
-			}
-			response.writeHead(200, { "content-type": "application/octet-stream" }).end(file.bytes);
-		} else if (request.method === "GET" && path === "/dev/changes") waitForChange(response, Number(url.searchParams.get("after")));
-		else if (request.method === "POST" && path === "/dev/log") readText(request).then((text) => {
-			for (const line of text.split("\n")) onLog(line, from);
-			response.writeHead(204).end();
-		}).catch(() => response.writeHead(413).end());
+		if (request.method === "GET" && path === "/dev/build") this.#sendBuild(response, from);
+		else if (request.method === "GET" && path.startsWith(FILES_PATH)) this.#sendFile(response, path, url.searchParams.get("generation"));
+		else if (request.method === "GET" && path === "/dev/changes") this.#waitForChange(response, Number(url.searchParams.get("after")));
+		else if (request.method === "POST" && path === "/dev/log") this.#receiveLog(request, response, from);
 		else response.writeHead(404).end();
-	});
-	const waitForChange = (response, after) => {
-		if (generation > after) {
-			sendJson(response, { generation });
+	}
+	#sendSignature(response) {
+		if (this.#signature) sendJson(response, this.#signature);
+		else response.writeHead(404).end();
+	}
+	#sendBuild(response, from) {
+		if (!this.#connected.has(from)) {
+			this.#connected.add(from);
+			this.#onConnect(from);
+		}
+		const hashes = {};
+		for (const [name, file] of this.#files) hashes[name] = file.hash;
+		const body = JSON.stringify({
+			generation: this.#generation,
+			hotSince: this.#hotSince,
+			files: hashes,
+			error: this.#error
+		});
+		response.writeHead(200, {
+			"content-type": "application/json",
+			[BUILD_MAC_HEADER]: buildMac(this.#secret, body)
+		}).end(body);
+	}
+	#sendFile(response, path, generation) {
+		if (generation !== String(this.#generation)) {
+			response.writeHead(409).end();
 			return;
 		}
-		const wake = () => {
+		const fileName = buildFileName(path);
+		if (fileName === void 0) {
+			response.writeHead(400).end();
+			return;
+		}
+		const file = this.#files.get(fileName);
+		if (!file) {
+			response.writeHead(404).end();
+			return;
+		}
+		response.writeHead(200, { "content-type": "application/octet-stream" }).end(file.bytes);
+	}
+	#waitForChange(response, after) {
+		if (this.#generation > after) {
+			sendJson(response, { generation: this.#generation });
+			return;
+		}
+		const stopWaiting = () => {
 			clearTimeout(timer);
-			waiting.delete(wake);
-			sendJson(response, { generation });
+			this.#waiting.delete(wake);
+		};
+		const wake = () => {
+			stopWaiting();
+			sendJson(response, { generation: this.#generation });
 		};
 		const timer = setTimeout(() => {
-			waiting.delete(wake);
+			stopWaiting();
 			response.writeHead(204).end();
 		}, WAIT_MS);
-		waiting.add(wake);
-		response.on("close", () => {
-			clearTimeout(timer);
-			waiting.delete(wake);
-		});
-	};
-	await new Promise((resolve, reject) => {
-		server.once("error", reject);
-		server.listen(port, address, () => resolve());
-	});
-	const { port: listening } = server.address();
-	const origin = `http://${address}:${listening}`;
-	if (developerKey) {
-		const expires = Math.floor(Date.now() / 1e3) + LINK_LIFETIME_SECONDS;
-		const keyId = developerKey.keyId;
-		const message = signedLinkMessage(origin, secret, expires, keyId);
-		signature = {
-			expires,
-			keyId,
-			sig: developerKey.sign(Buffer.from(message, "utf8"))
-		};
+		this.#waiting.add(wake);
+		response.on("close", stopWaiting);
 	}
-	return {
-		link: `${DEVICE_SCHEME}://connect?server=${encodeURIComponent(origin)}&secret=${secret}`,
-		async publish(dir, { hot = false } = {}) {
-			build = await readBuild(dir);
-			error = null;
-			announce();
-			if (!hot) hotSince = generation;
-		},
-		fail(message) {
-			error = message;
-			announce();
-		},
-		close() {
-			for (const wake of waiting) wake();
-			return new Promise((resolve) => {
-				server.close(() => resolve());
-				server.closeAllConnections();
-			});
-		}
-	};
+	#receiveLog(request, response, from) {
+		readLogText(request).then((text) => {
+			for (const line of text.split("\n")) this.#onLog(withoutControlCharacters(line), from);
+			response.writeHead(204).end();
+		}).catch(() => response.writeHead(413).end());
+	}
+};
+function hmacWithSecret(secret, text) {
+	const key = Buffer.from(secret, "base64url");
+	return createHmac("sha256", key).update(text, "utf8").digest("base64url");
 }
 function localNetworkAddress() {
 	for (const addresses of Object.values(networkInterfaces())) for (const candidate of addresses ?? []) if (candidate.family === "IPv4" && !candidate.internal) return candidate.address;
@@ -494,100 +599,95 @@ async function readBuild(dir) {
 		const path = join(entry.parentPath, entry.name);
 		const bytes = await readFile(path);
 		const hash = createHash("sha256").update(bytes).digest("base64url");
-		files.set(relative(dir, path).split(sep).join("/"), {
+		const name = relative(dir, path).split(sep).join("/");
+		files.set(name, {
 			bytes,
 			hash
 		});
 	}
-	return { files };
+	return files;
+}
+function buildFileName(path) {
+	const encodedParts = path.slice(11).split("/");
+	try {
+		return encodedParts.map((part) => decodeURIComponent(part)).join("/");
+	} catch {
+		return;
+	}
 }
 function isAuthorized(request, token) {
 	const given = Buffer.from(request.headers.authorization ?? "");
 	const expected = Buffer.from(`Bearer ${token}`);
-	return given.length === expected.length && timingSafeEqual(given, expected);
+	if (given.length !== expected.length) return false;
+	return timingSafeEqual(given, expected);
 }
 function sendJson(response, body) {
 	response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(body));
 }
-async function readText(request) {
+function withoutControlCharacters(line) {
+	return line.replace(/[\u0000-\u0008\u000a-\u001f\u007f-\u009f]/g, "");
+}
+async function readLogText(request) {
 	const chunks = [];
 	let size = 0;
 	for await (const chunk of request) {
-		size += chunk.length;
-		if (size > MAX_LOG_BYTES) throw new Error("Too much log at once");
-		chunks.push(chunk);
+		const bytes = chunk;
+		size += bytes.length;
+		if (size > MAX_LOG_BYTES) throw new Error(`A device sent more than ${MAX_LOG_BYTES} bytes of log at once`);
+		chunks.push(bytes);
 	}
 	return Buffer.concat(chunks).toString("utf8");
 }
 //#endregion
+//#region src/simulator.ts
+function startDotSimulator(project, outDir, port) {
+	return startSimulator({
+		dotDir: outDir,
+		reactHostDir: installedRuntime(project.root).react.dir,
+		name: project.dotJson.name,
+		port,
+		storageDir: join(project.root, ".dot", "files")
+	});
+}
+//#endregion
 //#region src/dev.ts
 const CHANGE_DEBOUNCE_MS = 50;
 async function dev({ port, device, ...options }) {
 	const project = await loadProject(options.root);
-	const outDir = resolve(project.root, options.outDir ?? "dist");
+	const outDir = resolveOutDir(project.root, options.outDir);
 	const buildOptions = {
 		mode: "development",
 		...options,
 		outDir
 	};
-	const buildApp = async () => {
-		const started = performance.now();
-		try {
-			printWarnings(await build(buildOptions));
-			printBuildTime(started);
-			return null;
-		} catch (error) {
-			const message = describeError(error).replaceAll(project.root + sep, "");
-			console.error(`error: ${message}`);
-			return message;
-		}
-	};
-	const firstError = await buildApp();
-	const simulator = await startSimulator({
-		dotDir: outDir,
-		reactHostDir: installedRuntime(project.root).react.dir,
-		name: project.dotJson.name,
-		port,
-		storageDir: join(project.root, ".dot", "files")
-	});
+	const firstError = await buildDot(buildOptions, project.root);
+	const simulator = await startDotSimulator(project, outDir, port);
 	if (firstError) simulator.error(firstError);
-	console.log(`\n  Simulator running at: ${simulator.url}\n`);
-	let devices;
-	if (device) {
-		const developerKey = await loadDeveloperKey();
-		devices = await startDeviceServer({
-			developerKey,
-			onConnect: (from) => console.log(`A device connected from ${from}`),
-			onLog: (line) => console.log(`device ${line}`)
-		});
-		if (firstError) devices.fail(firstError);
-		else await devices.publish(outDir);
-		printDeviceLink(devices.link);
-		if (developerKey) console.log(`  Signed with developer key ${developerKey.keyId}\n`);
-		else console.log(`${missingDeveloperKeyHint()}\n`);
-	}
-	const changed = /* @__PURE__ */ new Set();
+	printSimulatorUrl(simulator.url);
+	let deviceServer;
+	if (device) deviceServer = await startDevices(outDir, firstError);
+	const changedFiles = /* @__PURE__ */ new Set();
 	const pagesDir = join(project.root, PAGES_DIR) + sep;
 	const rebuilds = new RebuildQueue(async () => {
-		const building = [...changed];
-		const error = await buildApp();
+		const filesInThisBuild = [...changedFiles];
+		const error = await buildDot(buildOptions, project.root);
 		if (error) {
 			simulator.error(error);
-			devices?.fail(error);
+			deviceServer?.fail(error);
 			return;
 		}
-		for (const path of building) changed.delete(path);
-		const hot = building.every((path) => path.startsWith(pagesDir));
+		for (const path of filesInThisBuild) changedFiles.delete(path);
+		const hot = filesInThisBuild.every((path) => path.startsWith(pagesDir));
 		if (hot) simulator.hotReload();
 		else simulator.reload();
-		await devices?.publish(outDir, { hot });
+		await deviceServer?.publish(outDir, { hot });
 	});
 	let debounceTimer;
 	const watcher = watch(project.root, { recursive: true }, (_event, file) => {
 		if (!file || isIgnored(file)) return;
 		const path = resolve(project.root, file);
 		if (path === outDir || path.startsWith(outDir + sep)) return;
-		changed.add(path);
+		changedFiles.add(path);
 		clearTimeout(debounceTimer);
 		debounceTimer = setTimeout(() => {
 			console.log(`Changed ${relative(project.root, path)}`);
@@ -597,12 +697,39 @@ async function dev({ port, device, ...options }) {
 	return async () => {
 		clearTimeout(debounceTimer);
 		watcher.close();
-		await Promise.all([simulator.close(), devices?.close()]);
+		await Promise.all([simulator.close(), deviceServer?.close()]);
 	};
 }
+async function buildDot(buildOptions, root) {
+	const startedAt = performance.now();
+	try {
+		printWarnings(await build(buildOptions));
+		printBuildTime(startedAt);
+		return null;
+	} catch (error) {
+		const message = describeError(error).replaceAll(root + sep, "");
+		console.error(`error: ${message}`);
+		return message;
+	}
+}
+async function startDevices(outDir, firstError) {
+	const developerKey = await loadDeveloperKey();
+	const deviceServer = await startDeviceServer({
+		developerKey,
+		onConnect: (from) => console.log(`A device connected from ${from}`),
+		onLog: (line) => console.log(`device ${line}`)
+	});
+	if (firstError) deviceServer.fail(firstError);
+	else await deviceServer.publish(outDir);
+	printDeviceLink(deviceServer.link);
+	if (developerKey) console.log(`  Signed with developer key ${developerKey.keyId}\n`);
+	else console.log(`${missingDeveloperKeyHint()}\n`);
+	return deviceServer;
+}
 function printDeviceLink(link) {
-	console.log("  Scan this in Dash: turn on Enable Dot Debugging in Developer Settings, then tap Live Test on\n  the Dots tab.\n");
-	console.log(renderUnicodeCompact(link, { border: 1 }).replace(/^/gm, "  "));
+	console.log("  To open it in Dash, turn on Enable Dot Debugging in Developer Settings.\n  Then tap Live Test on the Dots tab and scan this code.\n");
+	const qrCode = renderUnicodeCompact(link, { border: 1 });
+	console.log(qrCode.replace(/^/gm, "  "));
 	console.log(`\n  ${link}\n`);
 }
 var RebuildQueue = class {
@@ -637,30 +764,140 @@ function isIgnored(file) {
 	});
 }
 //#endregion
+//#region src/preview.ts
+async function preview({ port, ...options }) {
+	const project = await loadProject(options.root);
+	const outDir = resolveOutDir(project.root, options.outDir);
+	const startedAt = performance.now();
+	printWarnings(await build({
+		...options,
+		outDir,
+		mode: "production"
+	}));
+	printBuildTime(startedAt);
+	const simulator = await startDotSimulator(project, outDir, port);
+	printSimulatorUrl(simulator.url);
+	return simulator;
+}
+//#endregion
+//#region src/prompts.ts
+const TERMINAL = {
+	input: process.stdin,
+	output: process.stdout
+};
+const ERASE_BELOW = "\x1B[0J";
+const HIDE_CURSOR = "\x1B[?25l";
+const SHOW_CURSOR = "\x1B[?25h";
+async function select(question, choices, fallback, { input, output } = TERMINAL) {
+	if (!input.isTTY) return fallback;
+	let selectedIndex = choices.findIndex((choice) => choice.value === fallback);
+	if (selectedIndex < 0) selectedIndex = 0;
+	let valueWidth = 0;
+	if (choices.some((choice) => choice.hint)) valueWidth = Math.max(...choices.map((choice) => choice.value.length));
+	const formatChoice = (choice, index) => {
+		const value = choice.value.padEnd(valueWidth);
+		const hint = choice.hint ? styleText("dim", `  ${choice.hint}`) : "";
+		const defaultMark = choice.value === fallback ? styleText("green", " (default)") : "";
+		if (index === selectedIndex) return `${styleText("cyan", "❯")} ${styleText(["cyan", "bold"], value)}${hint}${defaultMark}`;
+		return `  ${value}${hint}${defaultMark}`;
+	};
+	let drawnLines = 0;
+	const draw = (lines) => {
+		let moveUp = "";
+		if (drawnLines > 0) moveUp = cursorUp(drawnLines);
+		output.write(`${moveUp}${ERASE_BELOW}${lines.join("\n")}\n`);
+		drawnLines = lines.length;
+	};
+	const drawQuestionAndChoices = () => {
+		const keysHint = styleText("dim", "↑/↓ to move, Enter to choose");
+		draw([`${styleText("bold", question)} ${keysHint}`, ...choices.map(formatChoice)]);
+	};
+	emitKeypressEvents(input);
+	input.setRawMode(true);
+	input.resume();
+	output.write(HIDE_CURSOR);
+	drawQuestionAndChoices();
+	return new Promise((resolve) => {
+		const onKeypress = (_text, key) => {
+			if (key.ctrl && key.name === "c") {
+				output.write(`${SHOW_CURSOR}\n`);
+				process.exit(130);
+			}
+			if (key.name === "up" || key.name === "k") {
+				selectedIndex = (selectedIndex - 1 + choices.length) % choices.length;
+				drawQuestionAndChoices();
+			} else if (key.name === "down" || key.name === "j") {
+				selectedIndex = (selectedIndex + 1) % choices.length;
+				drawQuestionAndChoices();
+			} else if (key.name === "return" || key.name === "enter") {
+				const { value } = choices[selectedIndex];
+				input.off("keypress", onKeypress);
+				input.setRawMode(false);
+				input.pause();
+				draw([`${styleText("bold", question)} ${styleText("cyan", value)}`]);
+				output.write(SHOW_CURSOR);
+				resolve(value);
+			}
+		};
+		input.on("keypress", onKeypress);
+	});
+}
+async function confirm(question, fallback, terminal = TERMINAL) {
+	if (!terminal.input.isTTY) return false;
+	return await select(question, [{ value: "Yes" }, { value: "No" }], fallback ? "Yes" : "No", terminal) === "Yes";
+}
+async function ask(question, fallback, hint, { input, output } = TERMINAL) {
+	if (!input.isTTY) return fallback;
+	const hintText = hint ? styleText("dim", `, ${hint}`) : "";
+	const defaultMark = fallback ? styleText("dim", ` (default: ${fallback})`) : "";
+	const readline = createInterface({
+		input,
+		output
+	});
+	try {
+		const trimmedAnswer = (await readline.question(`${styleText("bold", question)}${hintText}${defaultMark}: `)).trim();
+		if (trimmedAnswer === "") return fallback;
+		return trimmedAnswer;
+	} catch (error) {
+		if (error.name === "AbortError") return;
+		throw error;
+	} finally {
+		readline.close();
+	}
+}
+function cursorUp(lines) {
+	return `\x1b[${lines}A`;
+}
+//#endregion
 //#region src/cli.ts
 const USAGE = `Usage:
-  dotctl create [dir] [--name <name>] [--template <starter|showcase>]
-                [--pm <npm|pnpm|yarn|bun>]
-                                        Create a dot (asks for its name and template):
-                                        starter is one page to build on, showcase a page
-                                        for each feature
-  dotctl create page <path>             Add a page to the dot you are in: pages/<path>/ with
-                                        view.dml, state.ts and controller.ts
+  dotctl create [dir] [--name <name>] [--package <com.mysalone.thing>]
+                [--template <starter|showcase>] [--pm <npm|pnpm|yarn|bun>]
+                                        Create a dot. Asks for its name, its package name
+                                        (a reverse domain name you own) and its template:
+                                        starter is one page to build on, showcase has a
+                                        page for each feature
+  dotctl create page <path>             Add a page to the dot you are in. Writes
+                                        pages/<path>/ with view.dml, state.ts and controller.ts
   dotctl build [root] [options]         Build the minified bundles the host app runs
-  dotctl dev [root] [options]           Run in the browser simulator, rebuilding on change
-  dotctl keys show                      Show the public key and key ID of this computer's
-                                        developer key, which signs the links \`dev --device\`
-                                        shows, for Dash to open
-  dotctl lsp [--stdio]                  Serve .dml files to an editor over the Language Server
-                                        Protocol, on stdin and stdout
+  dotctl dev [root] [options]           Run the dot in the browser simulator and rebuild on
+                                        every change
+  dotctl preview [root] [options]       Build as \`build\` does, then run that build in the
+                                        browser simulator, exactly as the host app gets it
+  dotctl keys show                      Show this computer's developer key: its public key
+                                        and key ID. The key signs the links that
+                                        \`dev --device\` shows, so Dash will open them
+  dotctl lsp [--stdio]                  Start the .dml language server for editors. It talks
+                                        over stdin and stdout
 
 Options:
   --out-dir <dir>       Output directory (default: <root>/dist)
-  --conditions <list>   Extra export conditions, comma separated
-  --port <port>         Simulator port for \`dev\`; the next free one is used if taken
-                        (default: ${DEFAULT_PORT})
-  --device              With \`dev\`, also serve the dot to the Dot example apps on phones on
-                        the local network, through a link and QR code; they reload on each build
+  --conditions <list>   Extra export conditions, separated by commas
+  --port <port>         Simulator port for \`dev\` and \`preview\`. If it is taken, the
+                        next free port is used (default: ${DEFAULT_PORT})
+  --device              With \`dev\`, also serve the dot to the Dot example apps on phones
+                        on your local network, through a link and QR code. The apps
+                        reload after each build
   -h, --help            Show this message`;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -672,6 +909,7 @@ async function main(argv) {
 			port: { type: "string" },
 			device: { type: "boolean" },
 			name: { type: "string" },
+			package: { type: "string" },
 			template: { type: "string" },
 			pm: { type: "string" },
 			help: {
@@ -682,46 +920,87 @@ async function main(argv) {
 		}
 	});
 	const [command, target, pagePath] = positionals;
-	if (command === "lsp" && !values.help) {
-		const { serveStdio } = await import("./server-DFOUQnLA.js");
-		serveStdio();
-		return new Promise(() => {});
-	}
-	if (command === "keys" && !values.help) return keys(target);
-	if (command === "create" && target === "page" && !values.help) return addPage(pagePath);
-	if (command === "create" && !values.help) return createApp(target, values.name, values.template, values.pm);
-	if (values.help || command !== "build" && command !== "dev") {
+	if (values.help) {
 		console.log(USAGE);
-		return values.help ? 0 : 1;
+		return 0;
 	}
-	const port = values.port === void 0 ? void 0 : Number(values.port);
-	if (port !== void 0 && !Number.isInteger(port)) {
-		console.error(`Invalid --port "${values.port}"`);
-		return 1;
+	switch (command) {
+		case "lsp": return serveLanguageServer();
+		case "keys": return showKeys(target);
+		case "create":
+			if (target === "page") return addPage(pagePath);
+			return createDot(target, {
+				name: values.name,
+				dotPackage: values.package,
+				template: values.template,
+				packageManager: values.pm
+			});
+		case "build":
+		case "dev":
+		case "preview": break;
+		default:
+			console.log(USAGE);
+			return 1;
+	}
+	let port;
+	if (values.port !== void 0) {
+		port = Number(values.port);
+		if (!Number.isInteger(port)) {
+			console.error(`--port must be a whole number, not "${values.port}"`);
+			return 1;
+		}
 	}
 	const options = { root: target ?? "." };
 	if (values["out-dir"] !== void 0) options.outDir = values["out-dir"];
 	if (values.conditions !== void 0) options.conditions = values.conditions.split(",");
-	if (command === "dev") {
-		const stop = await dev({
-			...options,
-			port,
-			device: values.device
-		});
-		await new Promise((resolve) => process.once("SIGINT", resolve));
-		await stop();
-		return 0;
+	if (command === "dev") return runDev(options, port, values.device);
+	if (command === "preview") return runPreview(options, port, values.device);
+	return runBuild(options);
+}
+async function serveLanguageServer() {
+	const { serveStdio } = await import("./server-DMnWDdJ6.js");
+	serveStdio();
+	return new Promise(() => {});
+}
+async function runDev(options, port, device) {
+	const stop = await dev({
+		...options,
+		port,
+		device
+	});
+	await waitForCtrlC();
+	await stop();
+	return 0;
+}
+async function runPreview(options, port, device) {
+	if (device) {
+		console.error("--device only works with dotctl dev");
+		return 1;
 	}
-	const started = performance.now();
+	const simulator = await preview({
+		...options,
+		port
+	});
+	await waitForCtrlC();
+	await simulator.close();
+	return 0;
+}
+async function runBuild(options) {
+	const startedAt = performance.now();
 	const result = await build(options);
-	for (const file of result.files.filter((file) => !file.endsWith(".map"))) console.log(`  ${relative(process.cwd(), file)}`);
+	printFiles(result.files.filter((file) => !file.endsWith(".map")));
 	printWarnings(result);
-	printBuildTime(started);
+	printBuildTime(startedAt);
 	return 0;
 }
-async function keys(action) {
+function waitForCtrlC() {
+	return new Promise((resolve) => {
+		process.once("SIGINT", () => resolve());
+	});
+}
+async function showKeys(action) {
 	if (action !== "show") {
-		console.error("dotctl keys show");
+		console.error("Usage: dotctl keys show");
 		return 1;
 	}
 	const path = defaultDeveloperKeyPath();
@@ -733,109 +1012,110 @@ async function keys(action) {
 	console.log(`\n  Public key: ${key.publicKey}\n  Key ID:     ${key.keyId}\n`);
 	return 0;
 }
-async function addPage(path) {
-	if (path === void 0) {
-		console.error("Which page? dotctl create page <path>, such as dotctl create page cart/checkout");
+async function addPage(typedPath) {
+	if (typedPath === void 0) {
+		console.error("Give the page a path, such as: dotctl create page cart/checkout");
 		return 1;
 	}
-	if (path.startsWith("/")) path = path.substring(1);
-	if (path.endsWith("/")) path = path.substring(0, path.length - 1);
+	const path = trimSlashes(typedPath);
 	const { files, listing } = await createPage(path, process.cwd());
-	for (const file of files) console.log(`  ${relative(process.cwd(), file)}`);
+	printFiles(files);
 	if (listing === "added") console.log(`\nListed '${path}' in dot.ts.`);
-	else if (listing === "manual") console.log(`\nList it in dot.ts to build it: defineDot({ pages: [..., '${path}'] })`);
+	else if (listing === "manual") console.log(`\nAdd it to the pages in dot.ts so it gets built: defineDot({ pages: [..., '${path}'] })`);
 	return 0;
 }
-async function createApp(dir, name, templateFlag, packageManagerFlag) {
+function trimSlashes(path) {
+	let trimmed = path;
+	if (trimmed.startsWith("/")) trimmed = trimmed.substring(1);
+	if (trimmed.endsWith("/")) trimmed = trimmed.substring(0, trimmed.length - 1);
+	return trimmed;
+}
+async function createDot(dir, flags) {
+	const templateFlag = flags.template;
 	if (templateFlag !== void 0 && !isTemplate(templateFlag)) {
 		console.error(`--template must be one of ${TEMPLATES.join(", ")}`);
 		return 1;
 	}
+	const packageManagerFlag = flags.packageManager;
 	if (packageManagerFlag !== void 0 && !isPackageManager(packageManagerFlag)) {
 		console.error(`--pm must be one of ${PACKAGE_MANAGERS.join(", ")}`);
 		return 1;
 	}
-	name ??= await ask("Dot name:", dir ? toDisplayName(dir) : "Dot");
+	let name = flags.name;
+	if (name === void 0) name = await ask("Dot name", dir ? toDisplayName(dir) : "Dot");
 	if (!name) {
-		console.error("A dot needs a name: dotctl create [dir] --name \"My Dot\"");
+		console.error("The dot needs a name. Pass one with: dotctl create [dir] --name \"My Dot\"");
+		return 1;
+	}
+	const dotPackageFlag = flags.dotPackage;
+	if (dotPackageFlag !== void 0 && !isDotPackage(dotPackageFlag)) {
+		console.error(`--package "${dotPackageFlag}" isn't a package name. ${DOT_PACKAGE_RULE}`);
 		return 1;
 	}
-	const template = templateFlag ?? await chooseTemplate();
+	let dotPackage = dotPackageFlag;
+	if (dotPackage === void 0) dotPackage = await askDotPackage(suggestedDotPackage(toPackageName(name)));
+	if (!dotPackage) return 1;
+	let template = templateFlag;
+	if (template === void 0) template = await chooseTemplate();
 	const { root, workspace } = await create({
 		name,
 		dir: dir ?? toPackageName(name),
+		dotPackage,
 		template
 	});
-	const path = relative(process.cwd(), root) || ".";
+	let path = relative(process.cwd(), root);
+	if (path === "") path = ".";
 	console.log(`\nCreated ${name} in ${path}`);
 	if (workspace) console.log("It is inside the Dot repository, so it uses the workspace packages.");
-	let packageManager = workspace ? "pnpm" : packageManagerFlag ?? launchedBy();
-	if (await confirm("\nInstall and start it now?")) {
+	let packageManager;
+	if (workspace) packageManager = "pnpm";
+	else packageManager = packageManagerFlag ?? launchedBy();
+	console.log();
+	if (await confirm("Install and start it now?", true)) {
 		if (!workspace && !packageManagerFlag) packageManager = await choosePackageManager(packageManager);
-		if (await run(packageManager, ["install"], root) === 0) return run(packageManager, ["run", "dev"], root);
-		console.error(`\n${packageManager} install failed.`);
+		if (await runCommand(packageManager, ["install"], root) === 0) return runCommand(packageManager, ["run", "dev"], root);
+		console.error(`\n${packageManager} install failed. Fix the problem above, then run the steps below.`);
 	}
 	console.log(`\nNext:\n\n  cd ${path}\n  ${packageManager} install\n  ${packageManager} run dev\n`);
 	return 0;
 }
-function run(command, args, cwd) {
-	return new Promise((resolvePromise, reject) => {
+function runCommand(command, args, cwd) {
+	return new Promise((resolve, reject) => {
 		const child = spawn(command, args, {
 			cwd,
 			stdio: "inherit",
 			shell: process.platform === "win32"
 		});
 		child.on("error", reject);
-		child.on("exit", (code) => resolvePromise(code ?? 1));
+		child.on("exit", (exitCode) => resolve(exitCode ?? 1));
 	});
 }
-async function confirm(question) {
-	if (!process.stdin.isTTY) return false;
-	const answer = await readAnswer(`${question} (Y/n)`, "y");
-	return answer !== void 0 && answer.toLowerCase().startsWith("y");
-}
-async function ask(question, fallback) {
-	return readAnswer(`${question}${fallback ? ` (${fallback})` : ""}`, fallback);
-}
-async function readAnswer(prompt, fallback) {
-	if (!process.stdin.isTTY) return fallback;
-	const readline = createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	try {
-		return (await readline.question(`${prompt} `)).trim() || fallback;
-	} catch (error) {
-		if (error.name === "AbortError") return;
-		throw error;
-	} finally {
-		readline.close();
+async function askDotPackage(suggested) {
+	while (true) {
+		const answer = await ask("Package name", suggested, "a reverse domain name you own");
+		if (answer === void 0 || isDotPackage(answer)) return answer;
+		console.error(`"${answer}" isn't a package name. ${DOT_PACKAGE_RULE}`);
 	}
 }
-async function chooseTemplate() {
-	if (!process.stdin.isTTY) return "starter";
-	console.log("\nTemplates:\n  starter   one page to build on\n  showcase  a page for each feature, to read");
-	return chooseOne("Template?", TEMPLATES, "starter");
+function chooseTemplate() {
+	console.log();
+	return select("Template?", TEMPLATES.map((template) => ({
+		value: template,
+		hint: TEMPLATE_HINTS[template]
+	})), "starter");
 }
 async function choosePackageManager(suggested) {
 	const installed = installedManagers();
 	if (installed.length < 2) return installed[0] ?? suggested;
-	return chooseOne("Package manager?", installed, installed.includes(suggested) ? suggested : installed[0]);
-}
-async function chooseOne(question, options, fallback) {
-	while (true) {
-		const answer = await ask(`${question} ${options.join(" / ")}`, fallback);
-		if (answer === void 0) return fallback;
-		const chosen = options.find((option) => option === answer);
-		if (chosen) return chosen;
-		console.log(`Choose one of ${options.join(", ")}.`);
-	}
+	let fallback = installed[0];
+	if (installed.includes(suggested)) fallback = suggested;
+	return select("Package manager?", installed.map((manager) => ({ value: manager })), fallback);
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+main(process.argv.slice(2)).then((exitCode) => process.exit(exitCode), (error) => {
 	console.error(`error: ${describeError(error)}`);
 	process.exit(1);
 });
 //#endregion
-export {};
+export { findDotRoot as t };
 
 //# sourceMappingURL=cli.js.map