@monimesl/dot-cli 1.0.0-beta.0 → 1.0.0-beta.10

package/README.md

@@ -1,12 +1,12 @@
 # @monimesl/dot-cli
 
-The `dotctl` command. It creates dots, builds them and runs them in the simulator. Later it will
-also package, sign and publish them.
+The `dotctl` command. It creates dots, builds them and runs them in the simulator and on phones.
+Later it will also publish them.
 
 ```sh
 dotctl create [dir]       # create a dot (asks for its name, package name and template)
 dotctl create page <path> # add a page to the dot you are in
-dotctl build [root]       # build the dot, minified, into dist/ui and dist/logic
+dotctl build [root]       # build the dot for Dash into dist/, with the ZIP Dash downloads
 dotctl dev [root]         # run the dot in the browser simulator and reload it on each change
 dotctl preview [root]     # build as `build` does, then run that build in the browser simulator
 dotctl keys show          # print this computer's developer key: its public key and key ID
@@ -18,7 +18,7 @@ dotctl lsp                # start the .dml language server (editors run this)
 | `--out-dir <dir>`     | `build`, `dev`, `preview` | Output directory (default: `<root>/dist`)                                  |
 | `--conditions <list>` | `build`, `dev`, `preview` | Extra export conditions, such as `@monimesl/dot-source`                    |
 | `--port <port>`       | `dev`, `preview`          | 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    |
+| `--device`            | `dev`                     | Also serve the dot to phones on your network, through a QR code            |
 | `--name <name>`       | `create`                  | The dot's name, instead of asking                                          |
 | `--package <name>`    | `create`                  | The dot's package name, such as `com.mysalone.thing`, instead of asking    |
 | `--template <name>`   | `create`                  | `starter` (one page to build on, the default) or `showcase` (all features) |
@@ -28,10 +28,10 @@ dotctl lsp                # start the .dml language server (editors run this)
 
 Creates a self-contained project for a new dot. It asks for:
 
-- **The name.** The default is `Dot`. The project goes in `dir`, or a folder named after the dot in
-  kebab case.
+- **The name.** The default comes from `dir`, such as `Plasas Kitchen` for `plasas-kitchen`, or is
+  `Dot`. The project goes in `dir`, or a folder named after the dot in kebab case.
 - **The package name.** A reverse domain name you own, such as `com.mysalone.thing`. It can't change
-  after the dot is published. The default is `com.example.<the folder's name>`.
+  after the dot is published. The default is `com.example.<the name in kebab case>`.
 - **The template.** `starter` is one page to build on. `showcase` has a page for each feature.
 
 The dot depends on `@monimesl/dot-runtime` and `@monimesl/dot-cli`. Inside the Dot repository it
@@ -42,6 +42,17 @@ Then it offers to install the dependencies and start the simulator. If more than
 manager is installed (npm, pnpm, yarn or bun), it asks which to use. The default is the one that
 ran `dotctl`, or npm.
 
+## `dotctl build`
+
+Builds the dot, minified, into `dist/`:
+
+- `ui/` and `logic/` hold the two bundles. `ui/` also has the dot's `statics/` images.
+- `manifest.json` tells Dash how to run the build.
+- `<package>-<version>.zip` holds all of it. It's the one file Dash downloads.
+
+The build fails if `network.hosts` in `dot.json` lists a local address, such as `localhost`. Dash
+refuses those in a published dot. `dotctl dev` allows them.
+
 ## `dotctl dev`
 
 Builds the dot, opens it in the browser simulator, and builds it again each time you save:
@@ -52,8 +63,10 @@ Builds the dot, opens it in the browser simulator, and builds it again each time
   pages it had open.
 - If a build fails, the simulator shows the error and keeps running the last good build.
 
-With `--device`, it also serves each build to the Dot example apps on your local network. It prints
-a QR code. Scan it with an example app, and the app follows the dot in the same way. See
+With `--device`, it also serves each build to phones on your local network. It prints a QR code.
+Scan it with Live Test in Dash, or with a Dot example app, and the phone follows the dot in the
+same way. To scan it in Dash, turn on Enable Dot Debugging in Developer Settings, then tap Live
+Test on the Dots tab. Dash needs a [developer key](#developer-keys). See also
 [the example apps](../hosts/native/README.md#the-example-apps).
 
 ## `dotctl preview`

package/dist/cli.js

@@ -158,6 +158,7 @@ function dotJson({ name, dotPackage, template }) {
 			photoLibrary: "Choose a photo for your concert ticket",
 			files: "Attach your concert ticket",
 			contacts: "Choose a friend to send a ticket to",
+			reminders: "Remind you before your concert",
 			payments: "Pay for concert tickets"
 		};
 		dot.network = { hosts: [
@@ -234,7 +235,7 @@ function formatJson(value) {
 }
 //#endregion
 //#region src/create/create.ts
-const DOT_PACKAGE_RULE = "Use lowercase words joined by dots, such as com.mysalone.thing.";
+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. Choose another folder`);
@@ -387,7 +388,7 @@ async function loadDeveloperKey(path = defaultDeveloperKeyPath()) {
 		throw 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}`);
+	if (privateKey.asymmetricKeyType !== "ed25519") throw new CommandError(`${path} isn't an Ed25519 key. Make one with: openssl genpkey -algorithm ed25519 -out ${path}`);
 	return toDeveloperKey(privateKey);
 }
 function toDeveloperKey(privateKey) {
@@ -423,7 +424,7 @@ 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");
+	if (address === void 0) throw new CommandError("This computer has no local network address, so phones can't reach it. Connect to Wi-Fi and try again");
 	const deviceServer = new LocalDeviceServer(onLog, onConnect);
 	await deviceServer.listen(port, address, developerKey);
 	return deviceServer;
@@ -585,8 +586,15 @@ 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;
+const UNREACHABLE_INTERFACE = /^(bridge|utun|tun|tap|ipsec|ppp|awdl|llw|vmnet|vboxnet|docker|br-|veth|virbr|zt|tailscale|wg)/i;
+function localNetworkAddress(interfaces = networkInterfaces()) {
+	let fallback;
+	for (const [name, addresses] of Object.entries(interfaces)) for (const candidate of addresses ?? []) {
+		if (candidate.family !== "IPv4" || candidate.internal) continue;
+		if (!candidate.address.startsWith("169.254.") && !UNREACHABLE_INTERFACE.test(name)) return candidate.address;
+		fallback ??= candidate.address;
+	}
+	return fallback;
 }
 async function readBuild(dir) {
 	const files = /* @__PURE__ */ new Map();
@@ -879,14 +887,15 @@ const USAGE = `Usage:
                                         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 build [root] [options]         Build the dot for Dash: minified bundles in dist/, and
+                                        the ZIP that Dash downloads
   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
+                                        browser simulator, exactly as Dash 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
+                                        \`dev --device\` shows, so Dash opens them
   dotctl lsp [--stdio]                  Start the .dml language server for editors. It talks
                                         over stdin and stdout
 
@@ -895,9 +904,9 @@ Options:
   --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
+  --device              With \`dev\`, also serve the dot to phones on your local network,
+                        through a link and QR code. Open it with Live Test in Dash, or
+                        with a Dot example app. Phones reload after each build
   -h, --help            Show this message`;
 async function main(argv) {
 	const { values, positionals } = parseArgs({
@@ -939,6 +948,7 @@ async function main(argv) {
 		case "dev":
 		case "preview": break;
 		default:
+			if (command !== void 0) console.error(`There is no "${command}" command. See the commands below.\n`);
 			console.log(USAGE);
 			return 1;
 	}
@@ -958,7 +968,7 @@ async function main(argv) {
 	return runBuild(options);
 }
 async function serveLanguageServer() {
-	const { serveStdio } = await import("./server-DMnWDdJ6.js");
+	const { serveStdio } = await import("./server-BhnO9_Zu.js");
 	serveStdio();
 	return new Promise(() => {});
 }
@@ -974,7 +984,7 @@ async function runDev(options, port, device) {
 }
 async function runPreview(options, port, device) {
 	if (device) {
-		console.error("--device only works with dotctl dev");
+		console.error("--device only works with dotctl dev. Run dotctl dev --device instead");
 		return 1;
 	}
 	const simulator = await preview({
@@ -1000,7 +1010,7 @@ function waitForCtrlC() {
 }
 async function showKeys(action) {
 	if (action !== "show") {
-		console.error("Usage: dotctl keys show");
+		console.error("Run dotctl keys show to see this computer's developer key");
 		return 1;
 	}
 	const path = defaultDeveloperKeyPath();