@rhythmjs/cli 0.0.12 → 0.0.13

package/README.md

@@ -2,7 +2,7 @@
 
 The command-line layer of Rhythm, the Bun-native backend framework: CLI command routing on top of the `@rhythmjs/rhythm` kernel. `RhythmCli` matches commands against argv positional tokens with a simple linear scan (appropriate for the handful-to-dozens of commands a real CLI has), supports prefixes and nested command groups, and mounts flat into a parent `Rhythm` app via `.use(cli.commands())`, so an unmatched command correctly falls through to whatever's registered after it.
 
-`RhythmCli` is not an app and does not extend `Rhythm`; it is a controller that compiles commands and middleware down to a single middleware (`.commands()`). It shares the core middleware contract (`compose`, `Middleware`, `next(extra)`), but has no `provide()` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle.
+`RhythmCli` is not an app and does not extend `Rhythm`; it is a controller that compiles commands and middleware down to a single middleware (`.commands()`). It shares the core middleware contract (`compose`, `Middleware`, `derive`; `next()` takes no arguments, extend the context with `derive()`), but has no `provide()` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle.
 
 ## Example
 
@@ -36,7 +36,7 @@ A fuller runnable version, including nested command groups and interactive promp
 ## API
 
 - `new RhythmCli(options?)`: `options.prefix` (space-separated, e.g. `"remote"`).
-- `.command(path, ...handlers)`: register a command; `path` is space-separated and may contain `:param` tokens (e.g. `"deploy :environment"`).
+- `.command(path, ...handlers)`: register a command; `path` is space-separated and may contain `:param` tokens (e.g. `"deploy :environment"`). A trailing `:param?` is optional (e.g. `"new :name?"`): `ctx.args.param` is left out when the token is absent. Optional params must come last. A trailing `**` is a catch-all, like the router: it captures the remaining positionals into `ctx.args._`, joined by spaces, and is absent when there are none (e.g. `"run :script **"`). Order is required, then optional, then at most one catch-all.
 - `.use(fn)`: plain middleware. `.use(child)`: mount a nested `RhythmCli` (prefixes compose).
 - `.commands()`: this CLI as a plain middleware, for mounting into a `Rhythm` app via `.use()`; the cli's only way onto a runtime. Note: mounting a _cli_ into a _cli_ must use `.use(child)`, not `.use(child.commands())`, because an opaque middleware can't have the parent's prefix applied to its commands.
 - `toCliHandler(app)`: bridges a `Rhythm` app to `(argv: string[]) => Promise<number>`.

package/dist/rhythm-cli.js

@@ -8,21 +8,41 @@ import { compose } from "@rhythmjs/rhythm/compose";
 function toSegments(command) {
   return command.trim().split(/\s+/).filter(Boolean);
 }
+var isOptional = (segment) => segment.startsWith(":") && segment.endsWith("?");
+var isCatchAll = (segment) => segment === "**";
 function matchCommand(pattern, positionals) {
-  if (pattern.length !== positionals.length)
+  const catchAll = isCatchAll(pattern.at(-1));
+  const fixed = catchAll ? pattern.slice(0, -1) : pattern;
+  const required = fixed.filter((segment) => !isOptional(segment)).length;
+  if (positionals.length < required || !catchAll && positionals.length > fixed.length)
     return null;
   const params = {};
-  for (let i = 0;i < pattern.length; i++) {
-    const segment = pattern[i];
+  for (let i = 0;i < fixed.length; i++) {
+    const segment = fixed[i];
     const token = positionals[i];
     if (segment.startsWith(":")) {
-      params[segment.slice(1)] = token;
+      if (token !== undefined)
+        params[segment.slice(1, isOptional(segment) ? -1 : undefined)] = token;
     } else if (segment !== token) {
       return null;
     }
   }
+  if (catchAll && positionals.length > fixed.length) {
+    params._ = positionals.slice(fixed.length).join(" ");
+  }
   return params;
 }
+function assertValidPattern(path, segments) {
+  const rank = (segment) => isCatchAll(segment) ? 2 : isOptional(segment) ? 1 : 0;
+  for (let i = 1;i < segments.length; i++) {
+    if (rank(segments[i]) < rank(segments[i - 1])) {
+      throw new TypeError(`optional params and a catch-all must come last, in that order, in command "${path}"`);
+    }
+  }
+  if (segments.filter(isCatchAll).length > 1) {
+    throw new TypeError(`command "${path}" has more than one catch-all`);
+  }
+}
 
 class RhythmCli {
   #options;
@@ -40,7 +60,9 @@ class RhythmCli {
     return this;
   }
   command(path, ...handlers) {
-    this.#entries.push({ kind: "command", segments: [...this.#prefixSegments, ...toSegments(path)], handlers });
+    const segments = toSegments(path);
+    assertValidPattern(path, segments);
+    this.#entries.push({ kind: "command", segments: [...this.#prefixSegments, ...segments], handlers });
     return this;
   }
   #compile() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/cli",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Command-line argument parsing, prompts, and command routing for the Rhythm middleware kernel, running on Bun.",
   "homepage": "https://rhythm.js.org/cli",
   "license": "ISC",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rhythmjs/rhythm": "0.0.12"
+    "@rhythmjs/rhythm": "0.0.13"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",