@monimesl/dot-cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -4,23 +4,42 @@ The `dotctl` command: build mini apps and run them in the simulator. Platform ta
 packaging, signing and publishing mini apps will live here too.
 
 ```sh
-dotctl create [dir]  # scaffold a dot (asks for its name), with a sample home page
-dotctl build [root]   # compile the dot into dist/ui and dist/logic, minified
-dotctl dev [root]     # build, open it in the browser simulator, rebuild and reload on change
+dotctl create [dir]       # scaffold a dot (asks for its name and template)
+dotctl create page <path> # add a page to the dot you are in
+dotctl build [root]       # compile the dot into dist/ui and dist/logic, minified
+dotctl dev [root]         # build, run it in the browser simulator, and reload it on each change
+dotctl lsp                # the .dml language server, which editors start
 ```
 
-| Option                | Applies to | What it does                                            |
-| --------------------- | ---------- | ------------------------------------------------------- |
-| `--out-dir <dir>`     | both       | Output directory (default: `<root>/dist`)               |
-| `--conditions <list>` | both       | Extra export conditions, such as `@monimesl/dot-source` |
-| `--port <port>`       | `dev`      | Simulator port (default: `3680`, or the next free one)  |
+| Option                | Applies to | What it does                                                             |
+| --------------------- | ---------- | ------------------------------------------------------------------------ |
+| `--out-dir <dir>`     | both       | Output directory (default: `<root>/dist`)                                |
+| `--conditions <list>` | both       | Extra export conditions, such as `@monimesl/dot-source`                  |
+| `--port <port>`       | `dev`      | Simulator port (default: `3680`, or the next free one)                   |
+| `--device`            | `dev`      | Also serve the dot to the Dot example apps on phones, through a QR code  |
+| `--name <name>`       | `create`   | The dot's name, instead of asking                                        |
+| `--template <name>`   | `create`   | `starter` (one page to build on, the default) or `showcase` (every page) |
+| `--pm <name>`         | `create`   | The package manager to install with: npm, pnpm, yarn or bun              |
 
 ## `dotctl create`
 
-Asks for the dot's name (`Dot` by default, or pass `--name`) and creates a self-contained project
-in `dir` (by default, the name in kebab case) with one page, `home`: a short welcome, localized for
-Sierra Leone, to a dot running inside Dash. The dot depends on `@monimesl/dot-runtime` and `@monimesl/dot-cli`; inside
-the Dot repository it uses the workspace packages instead. It then offers to install the
-dependencies and start the simulator inside the new dot, asking which of the installed package
-managers to use (npm, pnpm, yarn or bun; the one that launched `dotctl`, or npm, by default).
-`--pm <name>` answers that up front.
+Asks for the dot's name (`Dot` by default) and template, and creates a self-contained project in
+`dir` (by default, the name in kebab case): `starter` is one page to build on, and `showcase` a page
+for each feature. The dot depends on `@monimesl/dot-runtime` and `@monimesl/dot-cli`; inside the Dot
+repository it uses the workspace packages instead. It then offers to install the dependencies and
+start the simulator inside the new dot, asking which of the installed package managers to use (npm,
+pnpm, yarn or bun; the one that launched `dotctl`, or npm, by default).
+
+## `dotctl dev`
+
+Builds the dot, opens it in the browser simulator, and builds it again on each save:
+
+- A change to its pages (`pages/**`) runs in place: each open page keeps its state, and runs the new
+  code. A page whose initial state changed starts over from the new one.
+- Any other change, such as to `dot.ts`, `dot.json`, `.env` or `statics/`, starts the dot again, on
+  the pages it had open.
+- A failed build shows its error, and the dot keeps its last good build.
+
+With `--device`, it also serves each build on the local network to the Dot example apps. It prints a
+QR code to scan with one, which then follows the dot in the same way: see
+[the example apps](../hosts/native/README.md#the-example-apps).

package/dist/cli.js

@@ -3,13 +3,17 @@ 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 { CompileError, PAGES_DIR, build, installedRuntime, 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, writeFile } from "node:fs/promises";
+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 { renderUnicodeCompact } from "uqr";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { networkInterfaces } from "node:os";
 //#region src/report.ts
 /** A mistake in how a command was used, which its message alone explains. */
 var CommandError = class extends Error {
@@ -31,6 +35,10 @@ function printBuildTime(startedAt) {
 }
 //#endregion
 //#region src/create/template.ts
+const TEMPLATES = ["starter", "showcase"];
+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",
@@ -54,18 +62,8 @@ function projectFiles(options) {
 		"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",
-			network: { hosts: [
-				"api.github.com",
-				"avatars.githubusercontent.com",
-				"httpbin.org"
-			] }
-		}),
-		"README.md": readme(options.name)
+		"dot.json": dotJson(options),
+		"README.md": readme(options)
 	};
 }
 function packageJson({ packageName, dotVersion, workspace }) {
@@ -109,7 +107,29 @@ function tsconfig({ workspace }) {
 		]
 	});
 }
-function readme(name) {
+function dotJson({ name, packageName, template }) {
+	const dot = {
+		$schema: DOT_JSON_SCHEMA,
+		id: `com.example.${idWord(packageName)}`,
+		name,
+		version: "0.1.0"
+	};
+	if (template === "showcase") dot.network = { hosts: [
+		"api.github.com",
+		"avatars.githubusercontent.com",
+		"httpbin.org"
+	] };
+	return json(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\`.`
+};
+function readme({ name, template }) {
 	return `# ${name}
 
 A dot: a mini app that runs inside Dash.
@@ -135,9 +155,7 @@ the other fields from the schema it points to.
 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\`.
 
-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\`.
+${TEMPLATE_READMES[template]}
 `;
 }
 function idWord(packageName) {
@@ -145,20 +163,21 @@ function idWord(packageName) {
 }
 //#endregion
 //#region src/create/create.ts
-async function create({ name, dir }) {
+async function create({ name, dir, template = "starter" }) {
 	const root = resolve(dir);
 	if (existsSync(root) && readdirSync(root).length > 0) throw new CommandError(`${dir} already exists and is not empty`);
 	const packageName = toPackageName(name);
 	if (!packageName) throw new CommandError(`"${name}" needs at least one letter or digit`);
 	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 });
+	for (const path of TEMPLATE_FILES) await cp(join(source, path), join(root, path), { recursive: true });
 	const generated = projectFiles({
 		name,
 		packageName,
 		dotVersion: workspace ? "workspace:*" : `^${cliVersion()}`,
-		workspace
+		workspace,
+		template
 	});
 	for (const [path, content] of Object.entries(generated)) await writeFile(join(root, path), content);
 	return {
@@ -185,9 +204,9 @@ function isInDotWorkspace(dir) {
 		current = parent;
 	}
 }
-function templateDir() {
-	const example = join(cliRoot(), "../../examples/showcase");
-	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;
@@ -290,9 +309,152 @@ function onPath(name) {
 	}).status === 0;
 }
 //#endregion
+//#region src/device/server.ts
+const DEVICE_SCHEME = "dotdev";
+const WAIT_MS = 25e3;
+const MAX_LOG_BYTES = 1048576;
+async function startDeviceServer({ address = localNetworkAddress(), port = 0, onLog = () => {}, onConnect = () => {} } = {}) {
+	if (address === void 0) throw new Error("This computer has no local network address for devices to reach it on");
+	const token = randomBytes(18).toString("base64url");
+	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) => {
+		const from = request.socket.remoteAddress ?? "a device";
+		if (!isAuthorized(request, 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]));
+			sendJson(response, {
+				generation,
+				hotSince,
+				files,
+				error
+			});
+		} 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());
+		else response.writeHead(404).end();
+	});
+	const waitForChange = (response, after) => {
+		if (generation > after) {
+			sendJson(response, { generation });
+			return;
+		}
+		const wake = () => {
+			clearTimeout(timer);
+			waiting.delete(wake);
+			sendJson(response, { generation });
+		};
+		const timer = setTimeout(() => {
+			waiting.delete(wake);
+			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}`;
+	return {
+		link: `${DEVICE_SCHEME}://connect?server=${encodeURIComponent(origin)}&token=${token}`,
+		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();
+			});
+		}
+	};
+}
+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");
+		files.set(relative(dir, path).split(sep).join("/"), {
+			bytes,
+			hash
+		});
+	}
+	return { files };
+}
+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 readText(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);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+//#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 buildOptions = {
@@ -322,16 +484,38 @@ async function dev({ port, ...options }) {
 	});
 	if (firstError) simulator.error(firstError);
 	console.log(`\n  Simulator running at: ${simulator.url}\n`);
+	let devices;
+	if (device) {
+		devices = await startDeviceServer({
+			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);
+	}
+	const changed = /* @__PURE__ */ new Set();
+	const pagesDir = join(project.root, PAGES_DIR) + sep;
 	const rebuilds = new RebuildQueue(async () => {
+		const building = [...changed];
 		const error = await buildApp();
-		if (error) simulator.error(error);
+		if (error) {
+			simulator.error(error);
+			devices?.fail(error);
+			return;
+		}
+		for (const path of building) changed.delete(path);
+		const hot = building.every((path) => path.startsWith(pagesDir));
+		if (hot) simulator.hotReload();
 		else simulator.reload();
+		await devices?.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);
 		clearTimeout(debounceTimer);
 		debounceTimer = setTimeout(() => {
 			console.log(`Changed ${relative(project.root, path)}`);
@@ -341,9 +525,16 @@ async function dev({ port, ...options }) {
 	return async () => {
 		clearTimeout(debounceTimer);
 		watcher.close();
-		await simulator.close();
+		await Promise.all([simulator.close(), devices?.close()]);
 	};
 }
+function printDeviceLink(link) {
+	console.log("  Scan this in a Dot example app on a phone:\n");
+	console.log(renderUnicodeCompact(link, { border: 2 }).replace(/^/gm, "  "));
+	console.log(`\n  Or open the link on a device, an emulator or a simulator:\n\n  ${link}\n`);
+	console.log(`  Android emulator: adb shell am start -a android.intent.action.VIEW -d '${link}'`);
+	console.log(`  iOS Simulator:    xcrun simctl openurl booted '${link}'\n`);
+}
 var RebuildQueue = class {
 	#rebuild;
 	#building = false;
@@ -378,8 +569,11 @@ function isIgnored(file) {
 //#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>] [--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 build [root] [options]         Build the minified bundles the host app runs
@@ -392,6 +586,8 @@ Options:
   --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
   -h, --help            Show this message`;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -401,7 +597,9 @@ async function main(argv) {
 			"out-dir": { type: "string" },
 			conditions: { type: "string" },
 			port: { type: "string" },
+			device: { type: "boolean" },
 			name: { type: "string" },
+			template: { type: "string" },
 			pm: { type: "string" },
 			help: {
 				type: "boolean",
@@ -412,12 +610,12 @@ async function main(argv) {
 	});
 	const [command, target, pagePath] = positionals;
 	if (command === "lsp" && !values.help) {
-		const { serveStdio } = await import("./server-z7M4FLjf.js");
+		const { serveStdio } = await import("./server-DFOUQnLA.js");
 		serveStdio();
 		return new Promise(() => {});
 	}
 	if (command === "create" && target === "page" && !values.help) return addPage(pagePath);
-	if (command === "create" && !values.help) return createApp(target, values.name, values.pm);
+	if (command === "create" && !values.help) return createApp(target, values.name, values.template, values.pm);
 	if (values.help || command !== "build" && command !== "dev") {
 		console.log(USAGE);
 		return values.help ? 0 : 1;
@@ -433,7 +631,8 @@ async function main(argv) {
 	if (command === "dev") {
 		const stop = await dev({
 			...options,
-			port
+			port,
+			device: values.device
 		});
 		await new Promise((resolve) => process.once("SIGINT", resolve));
 		await stop();
@@ -459,7 +658,11 @@ async function addPage(path) {
 	else if (listing === "manual") console.log(`\nList it in dot.ts to build it: defineDot({ pages: [..., '${path}'] })`);
 	return 0;
 }
-async function createApp(dir, name, packageManagerFlag) {
+async function createApp(dir, name, templateFlag, packageManagerFlag) {
+	if (templateFlag !== void 0 && !isTemplate(templateFlag)) {
+		console.error(`--template must be one of ${TEMPLATES.join(", ")}`);
+		return 1;
+	}
 	if (packageManagerFlag !== void 0 && !isPackageManager(packageManagerFlag)) {
 		console.error(`--pm must be one of ${PACKAGE_MANAGERS.join(", ")}`);
 		return 1;
@@ -469,9 +672,11 @@ async function createApp(dir, name, packageManagerFlag) {
 		console.error("A dot needs a name: dotctl create [dir] --name \"My Dot\"");
 		return 1;
 	}
+	const template = templateFlag ?? await chooseTemplate();
 	const { root, workspace } = await create({
 		name,
-		dir: dir ?? toPackageName(name)
+		dir: dir ?? toPackageName(name),
+		template
 	});
 	const path = relative(process.cwd(), root) || ".";
 	console.log(`\nCreated ${name} in ${path}`);
@@ -519,15 +724,23 @@ async function readAnswer(prompt, fallback) {
 		readline.close();
 	}
 }
+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");
+}
 async function choosePackageManager(suggested) {
 	const installed = installedManagers();
 	if (installed.length < 2) return installed[0] ?? suggested;
-	const fallback = installed.includes(suggested) ? suggested : installed[0];
+	return chooseOne("Package manager?", installed, installed.includes(suggested) ? suggested : installed[0]);
+}
+async function chooseOne(question, options, fallback) {
 	while (true) {
-		const answer = await ask(`Package manager? ${installed.join(" / ")}`, fallback);
+		const answer = await ask(`${question} ${options.join(" / ")}`, fallback);
 		if (answer === void 0) return fallback;
-		if (isPackageManager(answer) && installed.includes(answer)) return answer;
-		console.log(`Choose one of ${installed.join(", ")}.`);
+		const chosen = options.find((option) => option === answer);
+		if (chosen) return chosen;
+		console.log(`Choose one of ${options.join(", ")}.`);
 	}
 }
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {