@rhythmjs/cli 0.0.12 → 0.0.14

package/README.md

@@ -1,8 +1,8 @@
 # @rhythmjs/cli
 
-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.
+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.middleware())`, 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 (`.middleware()`). 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
 
@@ -16,7 +16,7 @@ const cli = new RhythmCli().command("deploy :environment", (ctx) => {
   ctx.response.print(`deploying to ${ctx.args.environment}`);
 });
 
-const app = new Rhythm<RhythmCliContext>().use(cli.commands());
+const app = new Rhythm<RhythmCliContext>().use(cli.middleware());
 process.exitCode = await toCliHandler(app)(process.argv.slice(2));
 ```
 
@@ -30,15 +30,16 @@ A fuller runnable version, including nested command groups and interactive promp
 - **`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())`.
+- **Registration order is execution order**: a `.use()` middleware wraps only the commands registered after it, and runs only when one of them matches the argv (so a guard never answers `help` or another cli's commands); a mounted cli (`.use(child.middleware())`) always runs; 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.middleware())`.
 
 ## 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.
+- `.middleware()`: 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.
+- `.entries`: a read-only snapshot of registered middlewares and commands, in order. `.middleware()` is tagged with the cli as its source, so a parent module lists it in `sources`.
 - `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.
 

package/dist/rhythm-cli.d.ts

@@ -6,12 +6,21 @@ export interface RhythmCliCommandContext {
 export interface RhythmCliOptions {
     prefix?: string;
 }
-export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliContext> {
+export type CliEntry = {
+    readonly kind: "middleware";
+    readonly fn: Middleware<any>;
+} | {
+    readonly kind: "command";
+    readonly segments: readonly string[];
+    readonly handlers: readonly Middleware<any>[];
+};
+export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliContext, TInput extends RhythmCliContext = TContext> {
     #private;
     constructor(options?: RhythmCliOptions);
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmCli<TContext & TExtra>;
+    get entries(): readonly CliEntry[];
+    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmCli<TContext & TExtra, TInput>;
     use(fn: Middleware<TContext>): this;
     command<TExtra extends object>(path: string, middleware: DeriveMiddleware<TContext & RhythmCliCommandContext, TExtra>, ...handlers: Middleware<TContext & RhythmCliCommandContext & TExtra>[]): this;
     command(path: string, ...handlers: Middleware<TContext & RhythmCliCommandContext>[]): this;
-    middleware(): Middleware<TContext>;
+    middleware(): Middleware<TInput>;
 }

package/dist/rhythm-cli.js

@@ -5,24 +5,45 @@ import {
 
 // src/rhythm-cli.ts
 import { compose } from "@rhythmjs/rhythm/compose";
+import { sourceOf, withSource } from "@rhythmjs/rhythm/source";
 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;
@@ -30,6 +51,9 @@ class RhythmCli {
   constructor(options = {}) {
     this.#options = options;
   }
+  get entries() {
+    return [...this.#entries];
+  }
   get #prefixSegments() {
     return this.#options.prefix ? toSegments(this.#options.prefix) : [];
   }
@@ -40,10 +64,21 @@ 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() {
+    const groups = [];
+    const reaches = (ctx, from) => {
+      const { positionals } = parseArgv2(ctx.argv);
+      for (let g = from;g < groups.length; g++) {
+        if (groups[g].some((command) => matchCommand(command.segments, positionals)))
+          return true;
+      }
+      return false;
+    };
     const dispatchFor = (compiled) => {
       return async (ctx, next) => {
         const { positionals } = parseArgv2(ctx.argv);
@@ -62,7 +97,9 @@ class RhythmCli {
     while (i < this.#entries.length) {
       const entry = this.#entries[i];
       if (entry.kind === "middleware") {
-        stack.push(entry.fn);
+        const { fn } = entry;
+        const from = groups.length;
+        stack.push(sourceOf(fn) ? fn : (ctx, next) => reaches(ctx, from) ? fn(ctx, next) : next());
         i++;
         continue;
       }
@@ -74,15 +111,16 @@ class RhythmCli {
         compiled.push({ segments: command.segments, dispatch: compose(command.handlers) });
         i++;
       }
+      groups.push(compiled);
       stack.push(dispatchFor(compiled));
     }
     return compose(stack);
   }
   middleware() {
     const fn = this.#compile();
-    return async (ctx, next) => {
+    return withSource(async (ctx, next) => {
       await fn(ctx, next);
-    };
+    }, this);
   }
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/cli",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "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.14"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",