sproutboat 0.4.2 → 0.4.3

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.4.2 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.4.3 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -13,16 +13,16 @@
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `build` | `[project-dir]` | Cross-compile the native-fetch sprout (Porffor + Zig). |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]` | Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check. |
-| `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
-| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `versions` | `list [project-dir]` | List the project's deployed versions. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
+| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `domains` | `[list | add <host> | verify <host> | rm <host>] [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
 | `secrets` | `[list | set <NAME> [value] | rm <NAME>] [project-dir]` | Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy. |
 | `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
+| `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | login [--api-url <url>] [--token <token>] | tail [project-dir] [--sprout] | versions list [project-dir] | rollback <version-id> [project-dir] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes>
+usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | versions list [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>]>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",

package/src/main.ts

@@ -7,7 +7,7 @@ import { buildArtifact } from "./build";
 import { validateManifest, type ArtifactManifest } from "./manifest";
 import { printDeployReport } from "./report";
 import { activeApiUrl, savedToken, saveToken } from "./credentials";
-import { usageLine } from "./surface";
+import { helpText, usageLine } from "./surface";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
@@ -473,12 +473,20 @@ async function deleteProject(args: string[]) {
   if (failed.length) console.log(`  ! ${failed.length} artifact file(s) left on disk — remove them manually`);
 }
 
+/** `sproutboat` alone or with -h/--help/help: the friendly grouped list, exit 0. */
+function help(): never {
+  console.log(helpText());
+  process.exit(0);
+}
+
+/** An unrecognised command: a short pointer on stderr, exit 1. */
 function usage(): never {
-  console.error(usageLine());
+  console.error(`unknown command "${command}"\n${usageLine()}\nrun \`sproutboat\` with no arguments for the grouped command list`);
   process.exit(1);
 }
 
 const [command, ...args] = process.argv.slice(2);
+if (command === undefined || command === "help" || command === "-h" || command === "--help") help();
 switch (command) {
   case "init": await init(args[0]); break;
   case "check": await check(args[0]); break;

package/src/surface.ts

@@ -1,24 +1,57 @@
 /**
- * The CLI's public surface, as data. `main.ts` builds its usage string from
- * this, and `surface.test.ts` renders it to `SURFACE.md` and checks that the
- * command switch, the referenced env vars, and the doc can't drift apart.
+ * The CLI's public surface, as data. `main.ts` builds its help + usage strings
+ * from this, and `surface.test.ts` renders it to `SURFACE.md` and checks that
+ * the command switch, the referenced env vars, and the doc can't drift apart.
  */
+import { bold, dim, leaf } from "./style";
+
 export const CLI_NAME = "sproutboat";
+export const TAGLINE = "Deploy JavaScript handlers as tiny native binaries on your own VPS.";
+export const REPO_URL = "https://github.com/baronunread/sproutboat";
+
+export type Group = "Develop" | "Ship" | "Configure" | "Account";
 
-export type Command = { name: string; args: string; summary: string };
+export type Command = {
+  name: string;
+  /** Full argument grammar — used by SURFACE.md and the one-line usage string. */
+  args: string;
+  /** Short argument hint shown in the grouped help list (falls back to `args`). */
+  brief?: string;
+  group: Group;
+  emoji: string;
+  summary: string;
+};
 
 export const COMMANDS: readonly Command[] = [
-  { name: "init", args: "[name]", summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
-  { name: "check", args: "[project-dir]", summary: "Validate the config and entry point without building." },
-  { name: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
-  { name: "deploy", args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]", summary: "Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check." },
-  { name: "login", args: "[--api-url <url>] [--token <token>]", summary: "Device-code browser flow, or store <token> for <url> directly." },
-  { name: "tail", args: "[project-dir] [--sprout]", summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
-  { name: "versions", args: "list [project-dir]", summary: "List the project's deployed versions." },
-  { name: "rollback", args: "<version-id> [project-dir]", summary: "Re-activate a previous version." },
-  { name: "domains", args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
-  { name: "secrets", args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
-  { name: "delete", args: "[project-dir] [--name <project>] --yes", summary: "Delete the project, every version, and its route." },
+  { name: "init", group: "Develop", emoji: "🌱", args: "[name]",
+    summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
+  { name: "check", group: "Develop", emoji: "🔍", args: "[project-dir]",
+    summary: "Validate the config and entry point without building." },
+  { name: "build", group: "Develop", emoji: "🔨", args: "[project-dir]",
+    summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
+
+  { name: "deploy", group: "Ship", emoji: "🚀",
+    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]", brief: "[project-dir] [--dry-run]",
+    summary: "Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check." },
+  { name: "versions", group: "Ship", emoji: "📜", args: "list [project-dir]",
+    summary: "List the project's deployed versions." },
+  { name: "rollback", group: "Ship", emoji: "⏮", args: "<version-id> [project-dir]", brief: "<version-id>",
+    summary: "Re-activate a previous version." },
+  { name: "tail", group: "Ship", emoji: "📡", args: "[project-dir] [--sprout]",
+    summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
+
+  { name: "domains", group: "Configure", emoji: "🌐",
+    args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", brief: "[list | add | verify | rm]",
+    summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
+  { name: "secrets", group: "Configure", emoji: "🔑",
+    args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", brief: "[list | set | rm]",
+    summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
+  { name: "delete", group: "Configure", emoji: "🗑",
+    args: "[project-dir] [--name <project>] --yes", brief: "[project-dir] --yes",
+    summary: "Delete the project, every version, and its route." },
+
+  { name: "login", group: "Account", emoji: "🔓", args: "[--api-url <url>] [--token <token>]", brief: "[--token <token>]",
+    summary: "Device-code browser flow, or store <token> for <url> directly." },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -40,8 +73,38 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SB_SPROUT_URL", purpose: "http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it." },
 ];
 
-/** One-line usage string, e.g. for `usage()` and `--help`. */
+const GROUP_ORDER: readonly Group[] = ["Develop", "Ship", "Configure", "Account"];
+
+/** One-line usage string, e.g. for `usage()` and SURFACE.md. */
 export function usageLine(): string {
   const parts = COMMANDS.map((c) => (c.args ? `${c.name} ${c.args}` : c.name));
   return `usage: ${CLI_NAME} <${parts.join(" | ")}>`;
 }
+
+/** First sentence of a summary — enough for the at-a-glance command list. */
+function firstSentence(text: string): string {
+  const end = text.indexOf(". ");
+  return end === -1 ? text.replace(/\.$/, "") : text.slice(0, end);
+}
+
+/** Wrangler-style grouped help: `sproutboat` with no command, or `--help`. */
+export function helpText(): string {
+  const invocations = COMMANDS.map((c) => `${c.name} ${c.brief ?? c.args}`.trim());
+  const width = Math.max(...invocations.map((s) => s.length));
+  const lines: string[] = [`${bold(CLI_NAME)} — ${TAGLINE}`, "", leaf("USAGE"), `  ${CLI_NAME} <command> [options]`];
+
+  for (const group of GROUP_ORDER) {
+    lines.push("", leaf(group.toUpperCase()));
+    for (const command of COMMANDS.filter((c) => c.group === group)) {
+      const invocation = `${command.name} ${command.brief ?? command.args}`.trim();
+      lines.push(`  ${invocation.padEnd(width)}  ${command.emoji}  ${firstSentence(command.summary)}`);
+    }
+  }
+
+  lines.push(
+    "",
+    dim(`Run \`${CLI_NAME} <command>\` with no/invalid args to see that command's full usage.`),
+    dim(`Docs: ${REPO_URL}  ·  runs on Bun — use \`bunx\`, not \`npx\`.`),
+  );
+  return lines.join("\n");
+}