@rhythmjs/cli 0.0.16 → 0.0.17

package/README.md

@@ -1,49 +1,82 @@
 # @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.middleware())`, so an unmatched command correctly falls through to whatever's registered after it.
+The command-line layer of Rhythm, the Bun-native backend framework: command routing on top of the `@rhythmjs/rhythm` kernel. `RhythmCli` matches commands against the leading words of argv with [rou3](https://github.com/h3js/rou3), supports nested command groups (`db migrate`), optional and catch-all params, and runs per-command middleware chains.
 
-`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.
+`RhythmCli` is a `Pipeline`, like `Rhythm`: it has request-time `use()` middleware and commands, but no startup phase. It runs on its own through `toCliHandler(cli)`, or mounts into a `Rhythm` app with `mount(cli)` when you want startup work (`register`, `decorate`, `include`) around it.
 
 ## Example
 
 ```ts
-import { Rhythm } from "@rhythmjs/rhythm";
 import { RhythmCli } from "@rhythmjs/cli";
+import { withParsedArgv } from "@rhythmjs/cli/argv";
 import { toCliHandler } from "@rhythmjs/cli/run";
-import type { RhythmCliContext } from "@rhythmjs/cli/context";
 
-const cli = new RhythmCli().command("deploy :environment", (ctx) => {
-  ctx.response.print(`deploying to ${ctx.args.environment}`);
-});
+const cli = new RhythmCli({ name: "tool" })
+  .use(withParsedArgv())
+  .cmd("greet :name?", (ctx) => {
+    const message = `hello ${ctx.params.name ?? "world"}`;
+    ctx.log(ctx.flags.shout ? message.toUpperCase() : message);
+  })
+  .cmd(
+    "deploy :env",
+    (ctx, next) => {
+      if (!["staging", "production"].includes(ctx.params.env))
+        return ctx.fail(`unknown environment '${ctx.params.env}'`);
+      return next();
+    },
+    (ctx) => ctx.log(`deployed to ${ctx.params.env}`),
+  );
 
-const app = new Rhythm<RhythmCliContext>().use(cli.middleware());
-process.exitCode = await toCliHandler(app)(process.argv.slice(2));
+process.exitCode = await toCliHandler(cli)(Bun.argv.slice(2));
 ```
 
-A fuller runnable version, including nested command groups and interactive prompts, is at [`examples/cli`](../../examples/cli).
-
 ## 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, 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 `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()`.
-- **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())`.
+- **Commands.** `cmd(command, ...handlers)` takes a space-separated command (`"db migrate :name"`). Words are literal unless they start with `:`. Handlers are `(ctx, next)` middleware and form a chain; the first may be `derive()`, which widens the context type for the handlers after it. Matching uses the words before the first flag, so `deploy staging --force` matches `deploy :env`.
+- **Params.** `:name` is required, `:name?` optional (absent when not given), `:name+` / `:name*` / `**:name` capture the remaining words as a `string[]` (`*` and `**` alone land in `params["0"]`). Values are URI-decoded. Params are typed from the command string: `:name` is `string`, `:name?` is `string | undefined`, catch-alls are `string[]`, and reading a name that is not in the command is a compile error.
+- **Strict context.** The context only has what was added: `ctx.nope` is a compile error, `ctx.flags` only exists after `withParsedArgv()`, `ctx.prompt` only after `withPrompt()`, and `derive()` widens it for the handlers after it. A command-level `derive` only affects that command. `toCliHandler(app)` rejects, at compile time, an app that requires input the runner cannot supply.
+- **Request-time middleware.** `cli.use(middleware)` wraps commands and runs only when a command matched, so a guard never answers an unknown command. `derive()` extends the context type.
+- **Running and exit codes.** `toCliHandler(app, io?)` returns `(argv) => Promise<number>`: the exit code. It reports an unmatched command as `error: unknown command 'x'` (exit code 2, or `no command given`), and a thrown error as an error line (exit code 1). `app` can be a `RhythmCli`, or a `Rhythm` app that mounts one. Register `cmd("", handler)` to handle the no-argument case yourself.
+- **Output.** The context carries `argv`, `stdout`, `stderr`, `exitCode`, and the helpers `log(...)` (stdout), `error(...)` (stderr) and `fail(message, code = 1)` (prints `error: message` to stderr and sets the exit code). Pass `io: { stdout, stderr }` to `toCliHandler` to capture output, e.g. in tests.
+- **Named failures.** `new RhythmCli({ name })` labels failures when mounted: `mounted cli "tool" failed` with the original error as `cause`.
+
+## Opt-in extensions
+
+Nothing is added to the context unless you ask for it:
+
+- **`withParsedArgv()`** (`@rhythmjs/cli/argv`) adds `ctx.flags` and `ctx.positionals`. Parsing is schema-less: `--foo=bar` and `--foo bar` give a string, a bare `--foo` (or one followed by another flag) is `true`, `-f` works the same way, and everything after `--` is positional. Like `minimist`, `--force now` consumes `now` as the value. `parseArgv(argv)` is the same parser as a plain function.
+- **`withPrompt()`** (`@rhythmjs/cli/prompt`) adds `ctx.prompt` with `text()`, `confirm()`, `select()` and `multiSelect()` (the last two accept `allowCustom` to add a "type your own" choice) and closes its input when the command finishes. By default it reads lines through Bun's async-iterable `console`, only when you first ask; pass `() => ({ ask, write, close? })` to supply your own IO. `createPrompt(io)` is the same thing without the middleware.
+
+```ts
+const cli = new RhythmCli().use(withPrompt()).cmd("init", async (ctx) => {
+  const name = await ctx.prompt.text("Project name?", { default: "my-app" });
+  if (await ctx.prompt.confirm("Install dependencies?", { default: true })) ctx.log(`installing for ${name}`);
+});
+```
+
+## With a Rhythm app
+
+```ts
+import { Rhythm, decorate, mount } from "@rhythmjs/rhythm";
+
+const app = new Rhythm({ name: "tool" })
+  .register(decorate(async () => ({ config: await loadConfig() })))
+  .use(mount(cli));
+
+process.exitCode = await toCliHandler(app)(Bun.argv.slice(2));
+```
 
 ## 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"`). 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).
-- `.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 with `app.context` on the host app.
+- `new RhythmCli<I, D>(options?)`: `I` is context the CLI needs from the parent (checked by `mount()`), `D` is what its own `derive()` calls add; both are usually inferred. `options.name` labels failures (`type` defaults to `"cli"`).
+- `.cmd(command, ...handlers)`: register a command.
+- `.use(middleware)`: command-level middleware; `derive()` extends the context type.
+- `.callback()`: the CLI as a `(ctx) => Promise<ctx>` function, used by `mount()` and `toCliHandler()`.
+- `.sources` / `.parent` / `.options`: inherited from `Pipeline`.
+- `createCliContext(argv, io?)` (`@rhythmjs/cli/context`): the base context with `log`, `error`, `fail` and `exitCode`.
+- `toCliHandler(app, io?)` (`@rhythmjs/cli/run`): bridges a CLI or `Rhythm` app to `(argv) => Promise<number>`.
+- `parseArgv(argv)`, `withParsedArgv()` (`@rhythmjs/cli/argv`); `createPrompt(io)`, `createStdioPromptIO()`, `withPrompt(createIO?)` (`@rhythmjs/cli/prompt`).
 
 ## Running on Bun
 
-`@rhythmjs/cli/run` is the runtime half, coupled to Bun on purpose: `toCliHandler(app)` reads piped input through `Bun.stdin.stream()` (a TTY leaves `ctx.stdin` null), and `createPrompt()` reads answer lines through Bun's async-iterable `console`.
+The runtime half is coupled to Bun on purpose: prompts read through Bun's async-iterable `console`, and nothing is adapted for other runtimes.

package/dist/argv.d.ts

@@ -1,5 +1,9 @@
+import { type ExtensionMiddleware } from "@rhythmjs/rhythm";
 export interface ParsedArgv {
     positionals: string[];
     flags: Record<string, string | boolean>;
 }
 export declare function parseArgv(argv: readonly string[]): ParsedArgv;
+export declare function withParsedArgv(): ExtensionMiddleware<{
+    argv: readonly string[];
+}, ParsedArgv>;

package/dist/argv.js

@@ -1,7 +1,55 @@
 // @bun
-import {
-  parseArgv2
-} from "./rhythm-cli-qdf1cds9.js";
+// src/argv.ts
+import { derive } from "@rhythmjs/rhythm";
+function parseArgv(argv) {
+  const positionals = [];
+  const flags = {};
+  let rawMode = false;
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (rawMode) {
+      positionals.push(token);
+      continue;
+    }
+    if (token === "--") {
+      rawMode = true;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const eqIndex = token.indexOf("=");
+      if (eqIndex !== -1) {
+        flags[token.slice(2, eqIndex)] = token.slice(eqIndex + 1);
+        continue;
+      }
+      const name = token.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        flags[name] = next;
+        i++;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+    if (token.startsWith("-") && token.length > 1) {
+      const name = token.slice(1);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        flags[name] = next;
+        i++;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+    positionals.push(token);
+  }
+  return { positionals, flags };
+}
+function withParsedArgv() {
+  return derive((ctx) => parseArgv(ctx.argv));
+}
 export {
-  parseArgv2 as parseArgv
+  parseArgv,
+  withParsedArgv
 };

package/dist/context.d.ts

@@ -1,14 +1,17 @@
-export declare class RhythmCliResponse {
-    exitCode: number;
-    stdout: string[];
-    stderr: string[];
-    print(line: string): this;
-    printError(line: string): this;
-    exit(code: number): this;
-}
+export type CliWriter = {
+    write(text: string): unknown;
+};
+export type CliIO = {
+    stdout: CliWriter;
+    stderr: CliWriter;
+};
 export interface RhythmCliContext {
-    readonly argv: readonly string[];
-    readonly flags: Readonly<Record<string, string | boolean>>;
-    readonly stdin: ReadableStream<Uint8Array> | null;
-    readonly response: RhythmCliResponse;
+    readonly argv: string[];
+    readonly stdout: CliWriter;
+    readonly stderr: CliWriter;
+    exitCode: number;
+    log(...parts: unknown[]): void;
+    error(...parts: unknown[]): void;
+    fail(this: RhythmCliContext, message: string, code?: number): void;
 }
+export declare function createCliContext(argv: string[], io?: CliIO): RhythmCliContext;

package/dist/context.js

@@ -1,7 +1,7 @@
 // @bun
 import {
-  RhythmCliResponse2
-} from "./rhythm-cli-abdgd67x.js";
+  createCliContext2
+} from "./rhythm-cli-3w09y8wk.js";
 export {
-  RhythmCliResponse2 as RhythmCliResponse
+  createCliContext2 as createCliContext
 };

package/dist/prompt.d.ts

@@ -1,3 +1,4 @@
+import type { ExtensionMiddleware } from "@rhythmjs/rhythm";
 export interface RhythmPrompt {
     text(message: string, options?: {
         default?: string;
@@ -21,3 +22,7 @@ export declare function createPrompt(io: RhythmPromptIO): {
     prompt: RhythmPrompt;
     close: () => void;
 };
+export declare function createStdioPromptIO(): RhythmPromptIO;
+export declare function withPrompt(createIO?: () => RhythmPromptIO): ExtensionMiddleware<{}, {
+    prompt: RhythmPrompt;
+}>;

package/dist/prompt.js

@@ -1,7 +1,104 @@
 // @bun
-import {
-  createPrompt2
-} from "./rhythm-cli-28bavedc.js";
+// src/prompt.ts
+var CUSTOM_LABEL = "Other (type your own)";
+function createPrompt(io) {
+  const { ask, write } = io;
+  const text = async (message, options) => {
+    const suffix = options?.default ? ` (${options.default})` : "";
+    const answer = (await ask(`${message}${suffix} `)).trim();
+    return answer || options?.default || "";
+  };
+  const confirm = async (message, options) => {
+    const suffix = options?.default === undefined ? "(y/n)" : options.default ? "(Y/n)" : "(y/N)";
+    while (true) {
+      const answer = (await ask(`${message} ${suffix} `)).trim().toLowerCase();
+      if (!answer && options?.default !== undefined)
+        return options.default;
+      if (answer === "y" || answer === "yes")
+        return true;
+      if (answer === "n" || answer === "no")
+        return false;
+      write(`Please answer y or n.
+`);
+    }
+  };
+  function listChoices(message, choices, allowCustom) {
+    write(`${message}
+`);
+    choices.forEach((choice, i) => write(`  ${i + 1}) ${choice}
+`));
+    const customIndex = allowCustom ? choices.length + 1 : -1;
+    if (allowCustom)
+      write(`  ${customIndex}) ${CUSTOM_LABEL}
+`);
+    return customIndex;
+  }
+  const select = async (message, choices, options) => {
+    const customIndex = listChoices(message, choices, options?.allowCustom);
+    while (true) {
+      const index = Number(await ask("Enter number: "));
+      if (Number.isInteger(index) && index >= 1 && index <= choices.length)
+        return choices[index - 1];
+      if (index === customIndex)
+        return text("Enter value:");
+      write(`Invalid choice, try again.
+`);
+    }
+  };
+  const multiSelect = async (message, choices, options) => {
+    const customIndex = listChoices(message, choices, options?.allowCustom);
+    const maxIndex = options?.allowCustom ? customIndex : choices.length;
+    write(`(comma-separated numbers, e.g. "1,3")
+`);
+    while (true) {
+      const raw = await ask("Enter numbers: ");
+      const indices = raw.split(",").map((part) => Number(part.trim())).filter((n) => n !== 0 || raw.trim() === "0");
+      const valid = indices.length > 0 && indices.every((n) => Number.isInteger(n) && n >= 1 && n <= maxIndex);
+      if (!valid) {
+        write(`Invalid choices, try again.
+`);
+        continue;
+      }
+      const results = [];
+      for (const n of indices) {
+        results.push(n === customIndex ? await text("Enter value:") : choices[n - 1]);
+      }
+      return results;
+    }
+  };
+  return { prompt: { text, confirm, select, multiSelect }, close: () => io.close?.() };
+}
+function createStdioPromptIO() {
+  let lines;
+  return {
+    ask: async (query) => {
+      process.stdout.write(query);
+      lines ??= console[Symbol.asyncIterator]();
+      const { value } = await lines.next();
+      return value ?? "";
+    },
+    write: (text) => {
+      process.stdout.write(text);
+    },
+    close: () => {
+      lines?.return?.();
+    }
+  };
+}
+function withPrompt(createIO = createStdioPromptIO) {
+  const middleware = async (ctx, next) => {
+    const { prompt, close } = createPrompt(createIO());
+    ctx.prompt = prompt;
+    try {
+      await next();
+    } finally {
+      close();
+    }
+  };
+  return middleware;
+}
 export {
-  createPrompt2 as createPrompt
+  createPrompt,
+  createStdioPromptIO,
+  withPrompt
 };

package/dist/rhythm-cli-3w09y8wk.js

@@ -0,0 +1,26 @@
+// @bun
+// src/context.ts
+import { format } from "util";
+function createCliContext2(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  return {
+    argv,
+    stdout: io.stdout,
+    stderr: io.stderr,
+    exitCode: 0,
+    log(...parts) {
+      io.stdout.write(`${format(...parts)}
+`);
+    },
+    error(...parts) {
+      io.stderr.write(`${format(...parts)}
+`);
+    },
+    fail(message, code = 1) {
+      io.stderr.write(`error: ${message}
+`);
+      this.exitCode = code;
+    }
+  };
+}
+
+export { createCliContext2 };

package/dist/rhythm-cli.d.ts

@@ -1,26 +1,32 @@
-import type { Condition, DeriveMiddleware, Middleware } from "@rhythmjs/rhythm/types";
+import { type InferRouteParams } from "rou3";
+import { Pipeline, type ExtensionMiddleware, type Middleware, type Next, type PipelineOptions } from "@rhythmjs/rhythm";
 import type { RhythmCliContext } from "./context";
-export interface RhythmCliCommandContext {
-    readonly args: Readonly<Record<string, string>>;
-}
-export interface RhythmCliOptions {
-    prefix?: string;
-}
-export type CliEntry = {
-    readonly kind: "middleware";
-    readonly fn: Middleware<any>;
-} | {
-    readonly kind: "command";
-    readonly segments: readonly string[];
-    readonly handlers: readonly Middleware<any>[];
+export type CliContext<T extends object> = T & RhythmCliContext;
+export type UseContext<T extends object> = CliContext<T> & {
+    readonly params: Record<string, string | string[]>;
+};
+type ToPath<Command extends string> = Command extends `${infer Word} ${infer Rest}` ? `${Word}/${ToPath<Rest>}` : Command;
+type CatchAllWord<Word extends string> = Word extends `**:${infer Name}` ? Name : Word extends `:${infer Name}+` ? Name : Word extends `:${infer Name}*` ? Name : Word extends "*" | "**" ? "0" : never;
+type CatchAllKey<Command extends string> = Command extends `${infer Word} ${infer Rest}` ? CatchAllWord<Word> | CatchAllKey<Rest> : CatchAllWord<Command>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type CommandParams<C extends string> = Flatten<Omit<InferRouteParams<`/${ToPath<C>}`>, CatchAllKey<C> | "_"> & {
+    [K in CatchAllKey<C>]: string[];
+}>;
+export type CommandContext<T extends object, C extends string> = CliContext<T> & {
+    params: CommandParams<C>;
 };
-export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliContext, TInput extends RhythmCliContext = TContext> {
+export type CommandHandler<T extends object, C extends string> = (ctx: CommandContext<T, C>, next: Next) => unknown | Promise<unknown>;
+export type CommandHandlers<T extends object, C extends string> = [CommandHandler<T, C>, ...CommandHandler<T, C>[]];
+export declare class RhythmCli<I extends object = {}, D extends object = {}> extends Pipeline<UseContext<I & D>> {
     #private;
-    constructor(options?: RhythmCliOptions);
-    get entries(): readonly CliEntry[];
-    use<TExtra extends object>(fn: DeriveMiddleware<TContext, TExtra>): RhythmCli<TContext & TExtra, TInput>;
-    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>;
+    readonly "~input"?: I;
+    constructor(options?: PipelineOptions);
+    use<U extends object>(middleware: ExtensionMiddleware<UseContext<I & D>, U>): RhythmCli<I, D & U>;
+    use(middleware: Middleware<UseContext<I & D>>): this;
+    cmd<C extends string, U extends object>(command: C, middleware: ExtensionMiddleware<CommandContext<I & D, C>, U>, ...handlers: CommandHandler<I & D & U, C>[]): this;
+    cmd<C extends string>(command: C, ...handlers: CommandHandlers<I & D, C>): this;
+    callback(): (input: CliContext<I>) => Promise<CliContext<I & D>>;
 }
+export {};

package/dist/rhythm-cli.js

@@ -1,154 +1,77 @@
 // @bun
-import {
-  parseArgv2
-} from "./rhythm-cli-qdf1cds9.js";
-
 // src/rhythm-cli.ts
-import { compose, gate } 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) {
-  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 < fixed.length; i++) {
-    const segment = fixed[i];
-    const token = positionals[i];
-    if (segment.startsWith(":")) {
-      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(" ");
+import { addRoute, createRouter, findRoute } from "rou3";
+import {
+  Pipeline,
+  compose
+} from "@rhythmjs/rhythm";
+var isFlag = (token) => token.startsWith("-") && token !== "-";
+var lookupPath = (words) => `/${words.map(encodeURIComponent).join("/")}`;
+function catchAllKey(words) {
+  for (const word of words) {
+    const named = /^\*\*:(\w+)$/.exec(word) ?? /^:(\w+)[+*]$/.exec(word);
+    if (named)
+      return named[1];
+    if (word === "*" || word === "**")
+      return "0";
   }
-  return params;
+  return;
 }
-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}"`);
+function decodeParams(params, catchAll) {
+  const decoded = {};
+  try {
+    for (const [key, value] of Object.entries(params ?? {})) {
+      if (key === "_" && catchAll === "0")
+        continue;
+      decoded[key] = key === catchAll ? value.split("/").filter(Boolean).map(decodeURIComponent) : decodeURIComponent(value);
     }
-  }
-  if (segments.filter(isCatchAll).length > 1) {
-    throw new TypeError(`command "${path}" has more than one catch-all`);
-  }
-}
-function mountedCommands(cli, out, seen = new Set) {
-  if (seen.has(cli))
+  } catch {
     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);
-    }
   }
+  if (catchAll !== undefined)
+    decoded[catchAll] ??= [];
+  return decoded;
 }
 
-class RhythmCli {
-  #options;
-  #entries = [];
-  constructor(options = {}) {
-    this.#options = options;
-  }
-  get entries() {
-    return [...this.#entries];
-  }
-  get #prefixSegments() {
-    return this.#options.prefix ? toSegments(this.#options.prefix) : [];
+class RhythmCli extends Pipeline {
+  #routes = createRouter();
+  constructor(options) {
+    super({ type: "cli", ...options });
   }
-  use(fn, condition) {
-    if (typeof fn !== "function")
-      throw new TypeError("middleware must be a function!");
-    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;
+  use(middleware) {
+    return super.use(middleware);
   }
-  command(path, ...handlers) {
-    const segments = toSegments(path);
-    assertValidPattern(path, segments);
-    this.#entries.push({ kind: "command", segments: [...this.#prefixSegments, ...segments], handlers });
+  cmd(command, ...handlers) {
+    const chain = compose(handlers);
+    const words = command.trim().split(/\s+/).filter(Boolean);
+    addRoute(this.#routes, "", `/${words.join("/")}`, {
+      run: (ctx) => chain(ctx),
+      catchAll: catchAllKey(words)
+    });
     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);
-        for (const command of compiled) {
-          const args = matchCommand(command.segments, positionals);
-          if (!args)
-            continue;
-          await command.dispatch({ ...ctx, args }, next);
-          return;
-        }
-        await next();
-      };
+  callback() {
+    const run = this.chain();
+    return async (input) => {
+      const ctx = input;
+      const match = this.#match(ctx);
+      if (!match)
+        return ctx;
+      Object.assign(ctx, { params: match.params });
+      await run(ctx, () => match.route.run(ctx));
+      return ctx;
     };
-    const stack = [];
-    let i = 0;
-    while (i < this.#entries.length) {
-      const entry = this.#entries[i];
-      if (entry.kind === "middleware") {
-        const { fn } = entry;
-        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;
-      }
-      const compiled = [];
-      while (i < this.#entries.length) {
-        const command = this.#entries[i];
-        if (command.kind !== "command")
-          break;
-        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 withSource(async (ctx, next) => {
-      await fn(ctx, next);
-    }, this);
+  #match(ctx) {
+    const end = ctx.argv.findIndex(isFlag);
+    const words = end === -1 ? ctx.argv : ctx.argv.slice(0, end);
+    const found = findRoute(this.#routes, "", lookupPath(words));
+    if (!found)
+      return;
+    const params = decodeParams(found.params, found.data.catchAll);
+    if (!params)
+      return;
+    return { route: found.data, params };
   }
 }
 export {

package/dist/run.d.ts

@@ -1,8 +1,3 @@
-import type { Rhythm } from "@rhythmjs/rhythm";
-import { type RhythmPrompt } from "./prompt";
-import { type RhythmCliContext } from "./context";
-export declare function toCliHandler<TContext extends RhythmCliContext>(app: Rhythm<RhythmCliContext, any, TContext>): (argv: string[]) => Promise<number>;
-export declare function createPrompt(): {
-    prompt: RhythmPrompt;
-    close: () => void;
-};
+import type { Mountable } from "@rhythmjs/rhythm";
+import { type CliIO, type RhythmCliContext } from "./context";
+export declare function toCliHandler<I extends object = any>(app: Mountable<I> & (RhythmCliContext extends I ? unknown : never), io?: CliIO): (argv: string[]) => Promise<number>;

package/dist/run.js

@@ -1,48 +1,26 @@
 // @bun
 import {
-  parseArgv2
-} from "./rhythm-cli-qdf1cds9.js";
-import {
-  createPrompt2
-} from "./rhythm-cli-28bavedc.js";
-import {
-  RhythmCliResponse2
-} from "./rhythm-cli-abdgd67x.js";
+  createCliContext2
+} from "./rhythm-cli-3w09y8wk.js";
 
 // src/run.ts
-function toCliHandler(app) {
+function toCliHandler(app, io) {
   const run = app.callback();
   return async (argv) => {
-    const { flags } = parseArgv2(argv);
-    const stdin = process.stdin.isTTY ? null : Bun.stdin.stream();
-    const ctx = await run({ argv, flags, stdin, response: new RhythmCliResponse2 });
-    for (const line of ctx.response.stdout)
-      console.log(line);
-    for (const line of ctx.response.stderr)
-      console.error(line);
-    return ctx.response.exitCode;
-  };
-}
-function defaultPromptIO() {
-  const lines = console[Symbol.asyncIterator]();
-  return {
-    ask: async (query) => {
-      process.stdout.write(query);
-      const { value } = await lines.next();
-      return value ?? "";
-    },
-    write: (text) => {
-      process.stdout.write(text);
-    },
-    close: () => {
-      lines.return?.();
+    const base = createCliContext2(argv, io);
+    try {
+      const result = await run(base);
+      if (result?.params === undefined) {
+        base.fail(argv.length ? `unknown command '${argv[0]}'` : "no command given", 2);
+        return base.exitCode;
+      }
+      return result.exitCode ?? base.exitCode;
+    } catch (error) {
+      base.fail(error instanceof Error ? error.message : String(error));
+      return base.exitCode;
     }
   };
 }
-function createPrompt() {
-  return createPrompt2(defaultPromptIO());
-}
 export {
-  createPrompt,
   toCliHandler
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhythmjs/cli",
-  "version": "0.0.16",
-  "description": "Command-line argument parsing, prompts, and command routing for the Rhythm middleware kernel, running on Bun.",
+  "version": "0.0.17",
+  "description": "Command-line routing for Rhythm: RhythmCli commands, argv parsing, prompts and a Bun runner.",
   "homepage": "https://rhythm.js.org/cli",
   "license": "ISC",
   "repository": {
@@ -35,21 +35,14 @@
       "types": "./dist/run.d.ts",
       "default": "./dist/run.js"
     },
-    "./adapters/context": {
-      "types": "./dist/context.d.ts",
-      "default": "./dist/context.js"
-    },
-    "./adapters/bun": {
-      "types": "./dist/run.d.ts",
-      "default": "./dist/run.js"
-    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@rhythmjs/rhythm": "0.0.16"
+    "@rhythmjs/rhythm": "0.0.17",
+    "rou3": "^1.0.0"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
@@ -60,7 +53,7 @@
     "bun": ">=1.2.0"
   },
   "scripts": {
-    "build": "bun build src/rhythm-cli.ts src/argv.ts src/prompt.ts src/context.ts src/run.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/rhythm-cli.ts src/argv.ts src/prompt.ts src/context.ts src/run.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   }

package/dist/rhythm-cli-28bavedc.js

@@ -1,72 +0,0 @@
-// @bun
-// src/prompt.ts
-var CUSTOM_LABEL = "Other (type your own)";
-function createPrompt2(io) {
-  const { ask, write } = io;
-  const text = async (message, options) => {
-    const suffix = options?.default ? ` (${options.default})` : "";
-    const answer = (await ask(`${message}${suffix} `)).trim();
-    return answer || options?.default || "";
-  };
-  const confirm = async (message, options) => {
-    const suffix = options?.default === undefined ? "(y/n)" : options.default ? "(Y/n)" : "(y/N)";
-    while (true) {
-      const answer = (await ask(`${message} ${suffix} `)).trim().toLowerCase();
-      if (!answer && options?.default !== undefined)
-        return options.default;
-      if (answer === "y" || answer === "yes")
-        return true;
-      if (answer === "n" || answer === "no")
-        return false;
-      write(`Please answer y or n.
-`);
-    }
-  };
-  function listChoices(message, choices, allowCustom) {
-    write(`${message}
-`);
-    choices.forEach((choice, i) => write(`  ${i + 1}) ${choice}
-`));
-    const customIndex = allowCustom ? choices.length + 1 : -1;
-    if (allowCustom)
-      write(`  ${customIndex}) ${CUSTOM_LABEL}
-`);
-    return customIndex;
-  }
-  const select = async (message, choices, options) => {
-    const customIndex = listChoices(message, choices, options?.allowCustom);
-    while (true) {
-      const index = Number(await ask("Enter number: "));
-      if (Number.isInteger(index) && index >= 1 && index <= choices.length)
-        return choices[index - 1];
-      if (index === customIndex)
-        return text("Enter value:");
-      write(`Invalid choice, try again.
-`);
-    }
-  };
-  const multiSelect = async (message, choices, options) => {
-    const customIndex = listChoices(message, choices, options?.allowCustom);
-    const maxIndex = options?.allowCustom ? customIndex : choices.length;
-    write(`(comma-separated numbers, e.g. "1,3")
-`);
-    while (true) {
-      const raw = await ask("Enter numbers: ");
-      const indices = raw.split(",").map((part) => Number(part.trim())).filter((n) => n !== 0 || raw.trim() === "0");
-      const valid = indices.length > 0 && indices.every((n) => Number.isInteger(n) && n >= 1 && n <= maxIndex);
-      if (!valid) {
-        write(`Invalid choices, try again.
-`);
-        continue;
-      }
-      const results = [];
-      for (const n of indices) {
-        results.push(n === customIndex ? await text("Enter value:") : choices[n - 1]);
-      }
-      return results;
-    }
-  };
-  return { prompt: { text, confirm, select, multiSelect }, close: () => io.close?.() };
-}
-
-export { createPrompt2 };

package/dist/rhythm-cli-abdgd67x.js

@@ -1,21 +0,0 @@
-// @bun
-// src/context.ts
-class RhythmCliResponse2 {
-  exitCode = 0;
-  stdout = [];
-  stderr = [];
-  print(line) {
-    this.stdout.push(line);
-    return this;
-  }
-  printError(line) {
-    this.stderr.push(line);
-    return this;
-  }
-  exit(code) {
-    this.exitCode = code;
-    return this;
-  }
-}
-
-export { RhythmCliResponse2 };

package/dist/rhythm-cli-qdf1cds9.js

@@ -1,49 +0,0 @@
-// @bun
-// src/argv.ts
-function parseArgv2(argv) {
-  const positionals = [];
-  const flags = {};
-  let rawMode = false;
-  for (let i = 0;i < argv.length; i++) {
-    const token = argv[i];
-    if (rawMode) {
-      positionals.push(token);
-      continue;
-    }
-    if (token === "--") {
-      rawMode = true;
-      continue;
-    }
-    if (token.startsWith("--")) {
-      const eqIndex = token.indexOf("=");
-      if (eqIndex !== -1) {
-        flags[token.slice(2, eqIndex)] = token.slice(eqIndex + 1);
-        continue;
-      }
-      const name = token.slice(2);
-      const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        flags[name] = next;
-        i++;
-      } else {
-        flags[name] = true;
-      }
-      continue;
-    }
-    if (token.startsWith("-") && token.length > 1) {
-      const name = token.slice(1);
-      const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        flags[name] = next;
-        i++;
-      } else {
-        flags[name] = true;
-      }
-      continue;
-    }
-    positionals.push(token);
-  }
-  return { positionals, flags };
-}
-
-export { parseArgv2 };