@rhythmjs/cli 0.0.14 → 0.0.16

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.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 (`.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.
+`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 startup `context` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle.
 
 ## Example
 
@@ -28,10 +28,11 @@ A fuller runnable version, including nested command groups and interactive promp
 - **`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.
+- **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 `app.context.prompt = ...` 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, 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())`.
+- **Conditional middleware**: `.use(fn, condition)` also needs `condition(ctx)` to return true (sync or async); the second callback only narrows, so a middleware registered after every command still never runs.
+- **A cli is a controller, not a module**: it has no startup `context` 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
 
@@ -41,7 +42,7 @@ A fuller runnable version, including nested command groups and interactive promp
 - `.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.
+- `createPrompt()`: a `{ text, confirm, select, multiSelect }` prompt reading lines through Bun's async-iterable `console`, for use with `app.context` on the host app.
 
 ## Running on Bun
 

package/dist/rhythm-cli.d.ts

@@ -1,4 +1,4 @@
-import type { DeriveMiddleware, Middleware } from "@rhythmjs/rhythm/types";
+import type { Condition, DeriveMiddleware, Middleware } from "@rhythmjs/rhythm/types";
 import type { RhythmCliContext } from "./context";
 export interface RhythmCliCommandContext {
     readonly args: Readonly<Record<string, string>>;
@@ -19,7 +19,7 @@ export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliCont
     constructor(options?: RhythmCliOptions);
     get entries(): readonly CliEntry[];
     use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmCli<TContext & TExtra, TInput>;
-    use(fn: Middleware<TContext>): this;
+    use(fn: Middleware<TContext>, condition?: Condition<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<TInput>;

package/dist/rhythm-cli.js

@@ -4,7 +4,7 @@ import {
 } from "./rhythm-cli-qdf1cds9.js";
 
 // src/rhythm-cli.ts
-import { compose } from "@rhythmjs/rhythm/compose";
+import { compose, gate } from "@rhythmjs/rhythm/compose";
 import { sourceOf, withSource } from "@rhythmjs/rhythm/source";
 function toSegments(command) {
   return command.trim().split(/\s+/).filter(Boolean);
@@ -44,6 +44,20 @@ function assertValidPattern(path, segments) {
     throw new TypeError(`command "${path}" has more than one catch-all`);
   }
 }
+function mountedCommands(cli, out, seen = new Set) {
+  if (seen.has(cli))
+    return;
+  seen.add(cli);
+  for (const entry of cli.entries) {
+    if (entry.kind === "command")
+      out.push({ segments: [...entry.segments] });
+    else {
+      const child = sourceOf(entry.fn);
+      if (child instanceof RhythmCli)
+        mountedCommands(child, out, seen);
+    }
+  }
+}
 
 class RhythmCli {
   #options;
@@ -57,10 +71,14 @@ class RhythmCli {
   get #prefixSegments() {
     return this.#options.prefix ? toSegments(this.#options.prefix) : [];
   }
-  use(fn) {
+  use(fn, condition) {
     if (typeof fn !== "function")
       throw new TypeError("middleware must be a function!");
-    this.#entries.push({ kind: "middleware", fn });
+    if (condition !== undefined && typeof condition !== "function")
+      throw new TypeError("condition must be a function!");
+    const source = sourceOf(fn);
+    const wrapped = condition ? gate(fn, condition) : fn;
+    this.#entries.push({ kind: "middleware", fn: condition && source ? withSource(wrapped, source) : wrapped });
     return this;
   }
   command(path, ...handlers) {
@@ -98,8 +116,18 @@ class RhythmCli {
       const entry = this.#entries[i];
       if (entry.kind === "middleware") {
         const { fn } = entry;
-        const from = groups.length;
-        stack.push(sourceOf(fn) ? fn : (ctx, next) => reaches(ctx, from) ? fn(ctx, next) : next());
+        const source = sourceOf(fn);
+        if (source) {
+          if (source instanceof RhythmCli) {
+            const commands = [];
+            mountedCommands(source, commands);
+            groups.push(commands);
+          }
+          stack.push(fn);
+        } else {
+          const from = groups.length;
+          stack.push((ctx, next) => reaches(ctx, from) ? fn(ctx, next) : next());
+        }
         i++;
         continue;
       }

package/dist/run.d.ts

@@ -1,7 +1,7 @@
 import type { Rhythm } from "@rhythmjs/rhythm";
 import { type RhythmPrompt } from "./prompt";
 import { type RhythmCliContext } from "./context";
-export declare function toCliHandler<TContext extends RhythmCliContext, TProviders extends object = {}>(app: Rhythm<RhythmCliContext, TContext, TProviders>): (argv: string[]) => Promise<number>;
+export declare function toCliHandler<TContext extends RhythmCliContext>(app: Rhythm<RhythmCliContext, any, TContext>): (argv: string[]) => Promise<number>;
 export declare function createPrompt(): {
     prompt: RhythmPrompt;
     close: () => void;

package/package.json

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