@rhythmjs/cli 0.0.11 → 0.0.13

package/README.md

@@ -1,8 +1,8 @@
 # @rhythmjs/cli
 
-CLI command routing on top of `@rhythmjs/rhythm`. `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.
+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
 
@@ -24,23 +24,23 @@ A fuller runnable version, including nested command groups and interactive promp
 
 ## Concepts
 
-- **`ctx.response`** — `print(line)`, `printError(line)`, `exit(code)`, all chainable. Flushed to the console and returned as the process exit code by the adapter.
-- **`ctx.args`** — captured `:name` command tokens, added once a command matches.
-- **`ctx.flags`** — parsed `--foo` / `--foo=bar` / `-f` options. Schema-less: a bare `--foo` is boolean `true`, `--foo bar` takes the next token as its value unless the token itself looks like a flag — same default behavior as `minimist`.
-- **`ctx.stdin`** — a `ReadableStream`, or `null` when stdin is a TTY (nothing piped in).
-- **Interactive prompts** — `createPrompt()` gives `text()`/`confirm()`/`select()`/`multiSelect()` (the latter two support an `allowCustom` option that adds a "type your own" choice). Wire it in via a `.provide()` on the host `Rhythm` app — see the example.
-- **Prefixes compose across nesting** — a child cli mounted into a prefixed parent via `.use(child)` gets the parent's prefix segments joined onto every one of its commands, at any nesting depth. Mounting copies the child's commands and middleware at that moment; commands added to the child afterwards don't appear in the parent, and the child keeps working standalone.
-- **Registration order is execution order** — a `.use()` middleware wraps only the commands registered after it; commands registered before it are untouched, and a matched command that doesn't call `next()` returns without reaching anything registered later. An unmatched command falls through, entry by entry, to the outer `next()`.
-- **A cli is a controller, not a module** — it has no `provide()` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A cli mounts into an app exactly one way: koa-style, via `.use(cli.commands())`.
+- **`ctx.response`**: `print(line)`, `printError(line)`, `exit(code)`, all chainable. Flushed to the console and returned as the process exit code by the adapter.
+- **`ctx.args`**: captured `:name` command tokens, added once a command matches.
+- **`ctx.flags`**: parsed `--foo` / `--foo=bar` / `-f` options. Schema-less: a bare `--foo` is boolean `true`, `--foo bar` takes the next token as its value unless the token itself looks like a flag, the same default behavior as `minimist`.
+- **`ctx.stdin`**: a `ReadableStream`, or `null` when stdin is a TTY (nothing piped in).
+- **Interactive prompts**: `createPrompt()` gives `text()`/`confirm()`/`select()`/`multiSelect()` (the latter two support an `allowCustom` option that adds a "type your own" choice). Wire it in via a `.provide()` on the host `Rhythm` app; see the example.
+- **Prefixes compose across nesting**: a child cli mounted into a prefixed parent via `.use(child)` gets the parent's prefix segments joined onto every one of its commands, at any nesting depth. Mounting copies the child's commands and middleware at that moment; commands added to the child afterwards don't appear in the parent, and the child keeps working standalone.
+- **Registration order is execution order**: a `.use()` middleware wraps only the commands registered after it; commands registered before it are untouched, and a matched command that doesn't call `next()` returns without reaching anything registered later. An unmatched command falls through, entry by entry, to the outer `next()`.
+- **A cli is a controller, not a module**: it has no `provide()` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A cli mounts into an app exactly one way: koa-style, via `.use(cli.commands())`.
 
 ## 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"`).
-- `.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())` — 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>`.
-- `createPrompt()` — a `{ text, confirm, select, multiSelect }` prompt reading lines through Bun's async-iterable `console`, for use inside a `.provide()` on the host app.
+- `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"`). 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>`.
+- `createPrompt()`: a `{ text, confirm, select, multiSelect }` prompt reading lines through Bun's async-iterable `console`, for use inside a `.provide()` on the host app.
 
 ## Running on Bun
 

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.11",
+  "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.11"
+    "@rhythmjs/rhythm": "0.0.13"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",