milagre 0.1.0 → 0.1.1

package/README.md

@@ -15,6 +15,8 @@ npm install --global milagre
 milagre serve
 ```
 
+`milagre help` lists the commands. Use `milagre help serve` or `milagre serve --help` for a command's flags and examples. Help uses color in interactive terminals and plain text when piped; `NO_COLOR` disables color.
+
 `serve` runs in the foreground and uses `~/.milagre/server` for its persistent profile. It prints a private pairing link and, in an interactive terminal, a phone QR code. In another desktop's Settings > Devices > Add computer, paste the link. Approve the computer from another terminal on the server:
 
 ```sh
@@ -38,4 +40,4 @@ Use `MILAGRE_DATA_DIR` or an absolute `--data-dir` to select another profile. Us
 
 Ctrl+C and SIGTERM save and stop the server. Use `milagre serve --no-pair` for unattended restarts without printing links or opening a new pairing window. It retains access for devices already paired. `--no-qr` prints links without QR codes. No startup service is installed automatically; run the foreground command through your service manager for an always-on computer.
 
-From the repository, `npm run cli -- serve` runs the same command. `npm run package:cli` produces the installable tarball in `release/cli/`; it bundles the private Milagre packages, without Electron. npm installs registry dependencies and sets up native dependencies for the computer where you install it. You can also install that tarball with `npm install --global ./milagre-0.1.0.tgz`.
+From the repository, `npm run cli -- serve` runs the same command. `npm run package:cli` produces the installable tarball in `release/cli/`; it bundles the private Milagre packages, without Electron. npm installs registry dependencies and sets up native dependencies for the computer where you install it. You can also install that tarball with `npm install --global ./milagre-0.1.1.tgz`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "milagre",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Run Milagre agents on a computer without a desktop UI",
   "license": "MIT",
   "repository": {

package/src/command-help.cjs

@@ -0,0 +1,91 @@
+const GLOBAL_FLAGS = [
+  ["--data-dir <path>", "Absolute profile path (MILAGRE_DATA_DIR or ~/.milagre/server)."],
+  ["--help, -h", "Show command help."],
+  ["--version, -v", "Show the CLI version."],
+];
+
+const COMMANDS = {
+  serve: {
+    description: "Run the server without a desktop UI and print pairing details.",
+    usage: "milagre serve [flags]",
+    flags: [
+      ["--project <path>", "Open a Project on startup. Can be repeated."],
+      ["--no-pair", "Keep existing device access without opening a pairing window."],
+      ["--no-qr", "Print pairing links without terminal QR codes."],
+    ],
+    examples: ["milagre serve", "milagre serve --project /path/to/project", "milagre serve --no-pair"],
+    note: "Runs in the foreground. Ctrl+C or SIGTERM saves and stops the server.",
+  },
+  pair: {
+    description: "Open a new pairing window for phones and other desktops.",
+    usage: "milagre pair [flags]",
+    flags: [["--no-qr", "Print pairing links without terminal QR codes."]],
+    examples: ["milagre pair", "milagre pair --no-qr"],
+    note: "Pairing lasts 10 minutes. Approve computers with milagre devices allow KEY.",
+  },
+  status: {
+    description: "Show the running server's status as JSON.",
+    usage: "milagre status [flags]",
+    examples: ["milagre status"],
+  },
+  stop: {
+    description: "Save running work and stop the server.",
+    usage: "milagre stop [flags]",
+    examples: ["milagre stop"],
+  },
+  devices: {
+    description: "List, approve and remove paired devices.",
+    usage: "milagre devices <command> [key] [flags]",
+    commands: [
+      ["list", "List paired devices."],
+      ["pending", "List computers waiting for approval."],
+      ["allow <key>", "Approve a waiting computer."],
+      ["deny <key>", "Reject a waiting computer."],
+      ["remove <key>", "Remove a paired device and close its connections."],
+    ],
+    examples: ["milagre devices pending", "milagre devices allow KEY", "milagre devices list"],
+  },
+  request: {
+    description: "Call a daemon method and print its result as JSON.",
+    usage: "milagre request <method> [JSON_ARGS] [flags]",
+    arguments: [
+      ["method", "Daemon method to call, such as project:open or chat:runs."],
+      ["JSON_ARGS", "Arguments as a JSON array. Defaults to []."],
+    ],
+    examples: ["milagre request project:open '[\"/path/to/project\"]'", "milagre request chat:runs"],
+  },
+  help: {
+    description: "Show all commands or help for a specific command.",
+    usage: "milagre help [command]",
+    arguments: [["command", "Command to describe. Omit it to show all commands."]],
+    examples: ["milagre help", "milagre help serve", "milagre serve --help"],
+  },
+};
+
+function renderHelp(command, { color = false } = {}) {
+  const info = command && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : null;
+  if (command && !info) throw new Error(`Unknown command: ${command}. Use milagre help.`);
+  const style = (code, value) => (color ? `\u001b[${code}m${value}\u001b[0m` : value);
+  const sections = [];
+  const section = (title, lines) => sections.push(`${style("1", title)}\n${lines.join("\n")}`);
+  const rows = (entries) => {
+    const width = Math.max(...entries.map(([name]) => name.length)) + 3;
+    return entries.map(([name, description]) => `  ${style("36", name)}${" ".repeat(width - name.length)}${description}`);
+  };
+  section("DESCRIPTION", [`  ${info?.description ?? "Run Milagre agents on a computer without a desktop UI."}`]);
+  section("USAGE", [`  ${style("36", info?.usage ?? "milagre <command> [flags]")}`]);
+  if (info?.arguments) section("ARGUMENTS", rows(info.arguments));
+  if (!info) section("COMMANDS", rows(Object.entries(COMMANDS).map(([name, entry]) => [name, entry.description])));
+  if (info?.commands) section("COMMANDS", rows(info.commands));
+  if (info?.flags) section("FLAGS", rows(info.flags));
+  section("GLOBAL FLAGS", rows(GLOBAL_FLAGS));
+  section(
+    "EXAMPLES",
+    (info?.examples ?? ["npx milagre serve", "milagre help serve", "milagre devices pending"]).map((example) => `  ${style("36", example)}`),
+  );
+  if (info?.note) section("NOTES", [`  ${info.note}`]);
+  if (!info) section("REQUIRES", ["  Node.js 24+ and an installed, signed-in agent CLI (Claude Code or Codex)."]);
+  return sections.join("\n\n") + "\n";
+}
+
+module.exports = { COMMANDS, renderHelp };

package/src/command.cjs

@@ -3,29 +3,9 @@ const os = require("node:os");
 const path = require("node:path");
 const { parseArgs } = require("node:util");
 const { setTimeout: delay } = require("node:timers/promises");
-const { version } = require("../package.json");
-
-const HELP = `milagre serve [--project /path/to/project] [--no-pair]
-milagre pair
-milagre status
-milagre stop
-milagre devices <list|pending|allow KEY|deny KEY|remove KEY>
-milagre request METHOD [JSON_ARGS]
-
-Run a Milagre computer without a desktop UI. Requires Node 24+ and a
-signed-in agent CLI (Claude Code or Codex).
-
-Options:
-  --data-dir PATH       Absolute profile path (default: MILAGRE_DATA_DIR or ~/.milagre/server)
-  --project PATH        Open a Project on startup; can be repeated
-  --no-pair             Serve without opening or printing a new pairing window
-  --no-qr               Print pairing links without terminal QR codes
-  --help, -h            Show help
-  --version, -v         Show version
-
-serve runs in the foreground. Ctrl+C saves and stops the server.
-Use pair to reopen the pairing window. Approve computers with devices allow.
-`;
+const metadata = require("../package.json");
+const version = metadata.cliVersion ?? metadata.version;
+const { COMMANDS, renderHelp } = require("./command-help.cjs");
 
 async function printPairing(client, { output = process.stdout, qr = output.isTTY, timeoutMs = 20000 } = {}) {
   await client.call("phone:set-enabled", [true]);
@@ -62,9 +42,12 @@ async function main(args = process.argv.slice(2)) {
     },
   });
   if (values.version) return process.stdout.write(`${version}\n`);
-  if (values.help || !positionals.length) return process.stdout.write(HELP);
+  if (values.help || !positionals.length || positionals[0] === "help") {
+    const topic = positionals[0] === "help" ? positionals[1] : positionals[0];
+    return process.stdout.write(renderHelp(topic, { color: Boolean(process.stdout.isTTY && !("NO_COLOR" in process.env) && process.env.TERM !== "dumb") }));
+  }
   const [command, action, argument] = positionals;
-  if (!["serve", "pair", "status", "stop", "devices", "request"].includes(command)) throw new Error(`Unknown command: ${command}. Use milagre --help.`);
+  if (!Object.hasOwn(COMMANDS, command)) throw new Error(`Unknown command: ${command}. Use milagre help.`);
   const dataDir = values["data-dir"] ?? process.env.MILAGRE_DATA_DIR ?? path.join(os.homedir(), ".milagre", "server");
   if (!path.isAbsolute(dataDir)) throw new Error("--data-dir (or MILAGRE_DATA_DIR) must be an absolute path");
   if (command !== "serve" && (values.project || values["no-pair"])) throw new Error("--project and --no-pair are only supported by serve");