@monimesl/dot-cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/cli.js

@@ -1,46 +1,113 @@
 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, 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, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { DmlParseError } from "@monimesl/dot-dml-parser";
-import { ScriptParseError } from "@monimesl/dot-script-parser";
+import { ScriptParseError, parseDotModule } from "@monimesl/dot-script-parser";
+import { 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
+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 (isArgumentError(error)) {
+		const [firstSentence] = error.message.split(". ");
+		return `${firstSentence}. See dotctl --help.`;
+	}
+	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}`);
+}
+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");
+}
+//#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);
+}
+const PAGE_FILES = {
+	"view.dml": "<View>\n	<Text>My new page</Text>\n</View>\n",
+	"state.ts": "export default {};\n",
+	"controller.ts": `import state from './state';
+
+export default definePage({
+  initialState: state,
+});
+`
+};
 const TEMPLATE_FILES = [
 	"dot.ts",
 	"pages",
 	"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),
 		".gitignore": "node_modules/\ndist/\n# Types generated by dotctl\n.dot/\n",
-		"dot.json": json({
-			$schema: DOT_JSON_SCHEMA,
-			id: `com.example.${idWord(options.packageName)}`,
-			name: options.name,
-			version: "0.1.0"
-		}),
-		"README.md": readme(options.name)
+		"dot.json": dotJson(options),
+		"README.md": readme(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 },
@@ -63,7 +130,7 @@ function tsconfig({ workspace }) {
 		verbatimModuleSyntax: true
 	};
 	if (workspace) compilerOptions.customConditions = ["@monimesl/dot-source"];
-	return json({
+	return formatJson({
 		compilerOptions,
 		include: [
 			"dot.ts",
@@ -73,7 +140,39 @@ function tsconfig({ workspace }) {
 		]
 	});
 }
-function readme(name) {
+function dotJson({ name, dotPackage, template }) {
+	const dot = {
+		id: UNREGISTERED_DOT_ID,
+		$schema: DOT_JSON_SCHEMA,
+		package: dotPackage,
+		name,
+		version: "0.1.0"
+	};
+	if (template === "showcase") {
+		dot.permissions = {
+			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"
+		};
+		dot.network = { hosts: [
+			"itunes.apple.com",
+			"*.mzstatic.com",
+			"httpbin.org"
+		] };
+	}
+	return formatJson(dot);
+}
+const TEMPLATE_READMES = {
+	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}
 
 A dot: a mini app that runs inside Dash.
@@ -84,42 +183,69 @@ 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). List new pages in
-\`dot.ts\`; the first one is where the dot starts.
+${TEMPLATE_READMES[template]}
+
+## Pages
+
+Each page is a folder under \`pages/\` with three files:
+
+- \`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.
 
-\`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. Your editor completes the other fields
-from the schema it points to.
+## Which Dash opens it
 
-\`.env\` holds public configuration: variables named \`DOT_PUBLIC_…\`, which the service reads as
-\`env.DOT_PUBLIC_…\`. They are 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\`.
+Dash opens the dot unless it was built with a newer major version of \`@monimesl/dot-runtime\` than
+the one Dash has. A newer minor version can add Dash calls that an older Dash doesn't have yet.
+There, such a call fails with a \`DashError\` whose \`code\` is \`unsupported\`, so catch it and carry
+on without the feature.
 
-It starts as a counter with two pages. \`index\` counts taps with mutations. \`help/tips\` shows
-navigation: each page you open goes on top of the stack, Back returns to the one below, and the
-trail at the top shows where you are.
+## .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 }) {
+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 Error(`${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 Error(`"${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 template = templateDir();
+	const source = templateDir(template);
 	await mkdir(root, { recursive: true });
-	for (const path of TEMPLATE_FILES) await cp(join(template, path), join(root, path), { recursive: true });
-	const generated = projectFiles({
+	for (const path of TEMPLATE_FILES) await cp(join(source, path), join(root, path), { recursive: true });
+	const generated = generatedFiles({
 		name,
 		packageName,
+		dotPackage,
 		dotVersion: workspace ? "workspace:*" : `^${cliVersion()}`,
-		workspace
+		workspace,
+		template
 	});
 	for (const [path, content] of Object.entries(generated)) await writeFile(join(root, path), content);
 	return {
@@ -134,21 +260,15 @@ 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() {
-	const example = join(cliRoot(), "../../examples/counter");
-	return existsSync(example) ? example : join(cliRoot(), "dist/template");
+function templateDir(template) {
+	const example = join(cliRoot(), "../../examples", template);
+	return existsSync(example) ? example : join(cliRoot(), "dist/templates", template);
 }
 function cliVersion() {
 	return readPackageJson(join(cliRoot(), "package.json")).version;
@@ -160,6 +280,64 @@ function cliRoot() {
 	return dirname(createRequire(import.meta.url).resolve("@monimesl/dot-cli/package.json"));
 }
 //#endregion
+//#region src/create/page.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"`);
+	const root = findDotRoot(resolve(cwd));
+	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)) {
+		const file = join(dir, name);
+		await writeFile(file, content);
+		files.push(file);
+	}
+	return {
+		dir,
+		files,
+		listing: await addToDotPages(join(root, DOT_FILE), path)
+	};
+}
+async function addToDotPages(dotFile, path) {
+	if (!existsSync(dotFile)) return "manual";
+	const source = await readFile(dotFile, "utf8");
+	let dot;
+	try {
+		dot = parseDotModule(source, dotFile);
+	} catch {
+		return "manual";
+	}
+	if (dot.pages.includes(path)) return "already";
+	const updated = insertPage(source, dot.lastPage, path);
+	if (!listsPage(updated, dotFile, path)) return "manual";
+	await writeFile(dotFile, updated);
+	return "added";
+}
+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 `${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 `${before},\n${indent}${page}${after}`;
+}
+function listsPage(source, dotFile, path) {
+	try {
+		return parseDotModule(source, dotFile).pages.includes(path);
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/create/package-manager.ts
 const PACKAGE_MANAGERS = [
 	"npm",
@@ -173,73 +351,327 @@ function isPackageManager(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"
 	}).status === 0;
 }
 //#endregion
-//#region src/report.ts
-function describeError(error) {
-	if (error instanceof CompileError || error instanceof DmlParseError || error instanceof ScriptParseError) return error.message;
-	if (error.code?.startsWith("ERR_PARSE_ARGS")) {
-		const [firstSentence] = error.message.split(". ");
-		return `${firstSentence}. See dotctl --help.`;
+//#region src/device/developer-key.ts
+function defaultDeveloperKeyPath() {
+	return process.env.DOT_DEVELOPER_KEY ?? join(homedir(), ".dot", "developer-key.pem");
+}
+function missingDeveloperKeyHint(path = defaultDeveloperKeyPath()) {
+	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 run \`dotctl keys show\` and add the public key it prints to your Monime account.`;
+}
+async function loadDeveloperKey(path = defaultDeveloperKeyPath()) {
+	let pem;
+	try {
+		pem = await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
 	}
-	return error instanceof Error ? error.stack ?? error.message : String(error);
+	const privateKey = createPrivateKey(pem);
+	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 printWarnings({ warnings }) {
-	for (const warning of warnings) console.warn(`warning: ${warning.message}`);
+function toDeveloperKey(privateKey) {
+	const publicKeyJwk = createPublicKey(privateKey).export({ format: "jwk" });
+	const rawPublicKey = Buffer.from(publicKeyJwk.x, "base64url");
+	return {
+		publicKey: rawPublicKey.toString("base64"),
+		keyId: rawPublicKey.subarray(0, 8).toString("hex"),
+		sign: (bytes) => sign(null, bytes, privateKey).toString("base64")
+	};
 }
-function printBuildTime(startedAt) {
-	console.log(`Built in ${Math.round(performance.now() - startedAt)}ms`);
+//#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;
+const BUILD_MAC_HEADER = "dot-build-mac";
+function signedLinkMessage(server, secret, expires, keyId) {
+	return [
+		"dotdev-connect",
+		server,
+		secret,
+		String(expires),
+		keyId
+	].join("\n");
+}
+function deviceToken(secret) {
+	return hmacWithSecret(secret, "dotdev-token");
+}
+function buildMac(secret, body) {
+	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, 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() {
+		for (const wake of this.#waiting) wake();
+		return new Promise((resolve) => {
+			this.#server.close(() => resolve());
+			this.#server.closeAllConnections();
+		});
+	}
+	#announce() {
+		this.#generation += 1;
+		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") {
+			this.#sendSignature(response);
+			return;
+		}
+		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") 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();
+	}
+	#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 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 wake = () => {
+			clearTimeout(timer);
+			this.#waiting.delete(wake);
+			sendJson(response, { generation: this.#generation });
+		};
+		const timer = setTimeout(() => {
+			this.#waiting.delete(wake);
+			response.writeHead(204).end();
+		}, WAIT_MS);
+		this.#waiting.add(wake);
+		response.on("close", () => {
+			clearTimeout(timer);
+			this.#waiting.delete(wake);
+		});
+	}
+	#receiveLog(request, response, from) {
+		readLogText(request).then((text) => {
+			for (const line of text.split("\n")) this.#onLog(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;
+}
+async function readBuild(dir) {
+	const files = /* @__PURE__ */ new Map();
+	const entries = await readdir(dir, {
+		recursive: true,
+		withFileTypes: true
+	});
+	for (const entry of entries) {
+		if (!entry.isFile() || entry.name.endsWith(".map") || entry.name.endsWith(".zip")) continue;
+		const path = join(entry.parentPath, entry.name);
+		const bytes = await readFile(path);
+		const hash = createHash("sha256").update(bytes).digest("base64url");
+		const name = relative(dir, path).split(sep).join("/");
+		files.set(name, {
+			bytes,
+			hash
+		});
+	}
+	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);
+}
+function sendJson(response, body) {
+	response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+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(`A device sent more than ${MAX_LOG_BYTES} bytes of log at once`);
+		chunks.push(chunk);
+	}
+	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, ...options }) {
+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
-	});
+	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`);
+	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 error = await buildApp();
-		if (error) simulator.error(error);
+		const filesInThisBuild = [...changedFiles];
+		const error = await buildDot(buildOptions, project.root);
+		if (error) {
+			simulator.error(error);
+			deviceServer?.fail(error);
+			return;
+		}
+		for (const path of filesInThisBuild) changedFiles.delete(path);
+		const hot = filesInThisBuild.every((path) => path.startsWith(pagesDir));
+		if (hot) simulator.hotReload();
 		else simulator.reload();
+		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;
+		changedFiles.add(path);
 		clearTimeout(debounceTimer);
 		debounceTimer = setTimeout(() => {
 			console.log(`Changed ${relative(project.root, path)}`);
@@ -249,9 +681,41 @@ async function dev({ port, ...options }) {
 	return async () => {
 		clearTimeout(debounceTimer);
 		watcher.close();
-		await simulator.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("  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 {
 	#rebuild;
 	#building = false;
@@ -284,18 +748,136 @@ 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 = Math.max(0, choices.findIndex((choice) => choice.value === fallback));
+	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) => {
+		const moveUp = drawnLines > 0 ? 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 {
+		return (await readline.question(`${styleText("bold", question)}${hintText}${defaultMark}: `)).trim() || fallback;
+	} 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>] [--pm <npm|pnpm|yarn|bun>]
-                                        Create a dot (asks for its name)
+  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 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})
+  --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({
@@ -305,71 +887,178 @@ async function main(argv) {
 			"out-dir": { type: "string" },
 			conditions: { type: "string" },
 			port: { type: "string" },
+			device: { type: "boolean" },
 			name: { type: "string" },
+			package: { type: "string" },
+			template: { type: "string" },
 			pm: { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
-			}
+			},
+			stdio: { type: "boolean" }
 		}
 	});
-	const [command, target] = positionals;
-	if (command === "create" && !values.help) return createApp(target, values.name, values.pm);
-	if (values.help || command !== "build" && command !== "dev") {
+	const [command, target, pagePath] = positionals;
+	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
-		});
-		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-B9-F93mS.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 createApp(dir, name, packageManagerFlag) {
+function waitForCtrlC() {
+	return new Promise((resolve) => {
+		process.once("SIGINT", () => resolve());
+	});
+}
+async function showKeys(action) {
+	if (action !== "show") {
+		console.error("Usage: dotctl keys show");
+		return 1;
+	}
+	const path = defaultDeveloperKeyPath();
+	const key = await loadDeveloperKey(path);
+	if (!key) {
+		console.error(missingDeveloperKeyHint(path));
+		return 1;
+	}
+	console.log(`\n  Public key: ${key.publicKey}\n  Key ID:     ${key.keyId}\n`);
+	return 0;
+}
+async function addPage(typedPath) {
+	if (typedPath === void 0) {
+		console.error("Give the page a path, such as: dotctl create page cart/checkout");
+		return 1;
+	}
+	const path = trimSlashes(typedPath);
+	const { files, listing } = await createPage(path, process.cwd());
+	printFiles(files);
+	if (listing === "added") console.log(`\nListed '${path}' in dot.ts.`);
+	else if (listing === "manual") console.log(`\nAdd it to the pages in dot.ts so it gets built: defineDot({ pages: [..., '${path}'] })`);
+	return 0;
+}
+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;
 	}
+	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)
+		dir: dir ?? toPackageName(name),
+		dotPackage,
+		template
 	});
 	const path = relative(process.cwd(), root) || ".";
 	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) {
+function runCommand(command, args, cwd) {
 	return new Promise((resolvePromise, reject) => {
 		const child = spawn(command, args, {
 			cwd,
@@ -380,45 +1069,32 @@ function run(command, args, cwd) {
 		child.on("exit", (code) => resolvePromise(code ?? 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}`);
 	}
 }
+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;
-	const fallback = installed.includes(suggested) ? suggested : installed[0];
-	while (true) {
-		const answer = await ask(`Package manager? ${installed.join(" / ")}`, fallback);
-		if (answer === void 0) return fallback;
-		if (isPackageManager(answer) && installed.includes(answer)) return answer;
-		console.log(`Choose one of ${installed.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