@rhythmjs/cli 0.0.1 → 0.0.2

package/README.md

@@ -1,18 +1,23 @@
 # @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 via `.use(cli.commands())`, so an unmatched command correctly falls through to whatever's registered after it.
+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.
+
+`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 and the adapters.
 
 ## Example
 
 ```ts
+import { Rhythm } from "@rhythmjs/rhythm";
 import { RhythmCli } from "@rhythmjs/cli";
 import { toCliHandler } from "@rhythmjs/cli/adapters/bun";
+import type { RhythmCliContext } from "@rhythmjs/cli/adapters/context";
 
 const cli = new RhythmCli().command("deploy :environment", (ctx) => {
   ctx.response.print(`deploying to ${ctx.args.environment}`);
 });
 
-process.exitCode = await toCliHandler(cli)(process.argv.slice(2));
+const app = new Rhythm<RhythmCliContext>().use(cli.commands());
+process.exitCode = await toCliHandler(app)(process.argv.slice(2));
 ```
 
 A fuller runnable version, including nested command groups and interactive prompts, is at [`examples/cli`](../../examples/cli).
@@ -23,17 +28,19 @@ 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 — 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 normal `.provide()` — see the example.
-- **`register()` is disabled** on `RhythmCli`, same reasoning as `RhythmRouter`.
+- **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.name`, `options.prefix` (space-separated, e.g. `"remote"`).
+- `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, or mount a nested `RhythmCli` via `.use(child.commands())`.
-- `.commands()` — returns this CLI as a plain middleware, for mounting into a parent via `.use()`.
-- `toCliHandler(app)` — bridges a `Rhythm`/`RhythmCli` app to `(argv: string[]) => Promise<number>`.
-- `createPrompt()` — a readline-backed `{ text, confirm, select, multiSelect }` prompt, for use inside a `.provide()`.
+- `.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 readline-backed `{ text, confirm, select, multiSelect }` prompt, for use inside a `.provide()` on the host app.
 
 ## Runtime adapters
 

package/dist/rhythm-cli.d.ts

@@ -1,19 +1,17 @@
 import { t as RhythmCliContext } from "./context-SCtZ6pOg.js";
-import { DeepReadonly, Middleware, OmitHashKeys, Rhythm } from "@rhythmjs/rhythm";
+import { Middleware } from "@rhythmjs/rhythm";
 //#region src/rhythm-cli.d.ts
 export interface RhythmCliCommandContext {
   args: Record<string, string>;
 }
 export interface RhythmCliOptions {
-  name?: string;
   prefix?: string;
 }
-export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliContext, TProviders extends object = {}> extends Rhythm<RhythmCliContext, TContext, TProviders> {
+export declare class RhythmCli<TContext extends RhythmCliContext = RhythmCliContext> {
   #private;
   constructor(options?: RhythmCliOptions);
-  use<TExtra extends object = {}>(fn: Middleware<TContext>): RhythmCli<TContext & TExtra, TProviders>;
-  provide<TValue extends object>(factory: (deps: DeepReadonly<TProviders>) => TValue | Promise<TValue>, dispose?: (value: TValue) => void | Promise<void>): RhythmCli<TContext & OmitHashKeys<TValue>, TProviders & OmitHashKeys<TValue>>;
-  register(): never;
+  use(child: RhythmCli<any>): this;
+  use<TExtra extends object = {}>(fn: Middleware<TContext>): RhythmCli<TContext & TExtra>;
   command(path: string, ...handlers: Middleware<TContext & RhythmCliCommandContext>[]): this;
   commands(): Middleware<TContext>;
 }

package/dist/rhythm-cli.js

@@ -1,5 +1,5 @@
 import { parseArgv } from "./argv.js";
-import { Rhythm, compose } from "@rhythmjs/rhythm";
+import { compose } from "@rhythmjs/rhythm";
 //#region src/rhythm-cli.ts
 function toSegments(command) {
 	return command.trim().split(/\s+/).filter(Boolean);
@@ -15,81 +15,85 @@ function matchCommand(pattern, positionals) {
 	}
 	return params;
 }
-const RhythmCliTag = Symbol("RhythmCliTag");
-var RhythmCli = class extends Rhythm {
-	#prefixSegments;
+var RhythmCli = class RhythmCli {
+	#options;
 	#entries = [];
-	#commands = [];
-	#dispatchInstalled = false;
+	#composed = null;
 	constructor(options = {}) {
-		super({
-			name: options.name ?? "cli",
-			type: "controller"
-		});
-		this.#prefixSegments = options.prefix ? toSegments(options.prefix) : [];
+		this.#options = options;
+	}
+	get #prefixSegments() {
+		return this.#options.prefix ? toSegments(this.#options.prefix) : [];
 	}
-	use(fn) {
-		const nested = fn[RhythmCliTag];
-		if (nested) for (const entry of nested.#entries) this.#mount(entry);
+	use(arg) {
+		if (arg instanceof RhythmCli) for (const entry of arg.#entries) this.#entries.push(entry.kind === "command" ? {
+			...entry,
+			segments: [...this.#prefixSegments, ...entry.segments]
+		} : entry);
 		else {
+			if (typeof arg !== "function") throw new TypeError("middleware must be a function!");
 			this.#entries.push({
 				kind: "middleware",
-				fn
+				fn: arg
 			});
-			super.use(fn);
 		}
+		this.#composed = null;
 		return this;
 	}
-	provide(factory, dispose) {
-		super.provide(factory, dispose);
-		return this;
-	}
-	register() {
-		throw new Error("RhythmCli is a controller and cannot register() other modules or controllers");
-	}
-	#mount(entry) {
-		if (entry.kind === "middleware") {
-			this.#entries.push(entry);
-			super.use(entry.fn);
-			return;
-		}
-		this.#registerCommand([...this.#prefixSegments, ...entry.segments], entry.handlers);
-	}
-	#registerCommand(segments, handlers) {
+	command(path, ...handlers) {
 		this.#entries.push({
 			kind: "command",
-			segments,
+			segments: [...this.#prefixSegments, ...toSegments(path)],
 			handlers
 		});
-		this.#commands.push({
-			segments,
-			dispatch: compose(handlers)
-		});
-		if (this.#dispatchInstalled) return;
-		this.#dispatchInstalled = true;
-		const commands = this.#commands;
-		super.use(async (ctx, next) => {
-			const { positionals } = parseArgv(ctx.argv);
-			for (const cmd of commands) {
-				const params = matchCommand(cmd.segments, positionals);
-				if (!params) continue;
-				await cmd.dispatch({
-					...ctx,
-					args: params
-				}, next);
-				return;
-			}
-			await next();
-		});
-	}
-	command(path, ...handlers) {
-		this.#registerCommand([...this.#prefixSegments, ...toSegments(path)], handlers);
+		this.#composed = null;
 		return this;
 	}
+	#compile() {
+		if (this.#composed) return this.#composed;
+		const dispatchFor = (compiled) => {
+			return async (ctx, next) => {
+				const { positionals } = parseArgv(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();
+			};
+		};
+		const stack = [];
+		let i = 0;
+		while (i < this.#entries.length) {
+			const entry = this.#entries[i];
+			if (entry.kind === "middleware") {
+				stack.push(entry.fn);
+				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++;
+			}
+			stack.push(dispatchFor(compiled));
+		}
+		this.#composed = compose(stack);
+		return this.#composed;
+	}
 	commands() {
-		const mw = this.middleware();
-		mw[RhythmCliTag] = this;
-		return mw;
+		return async (ctx, next) => {
+			await this.#compile()(ctx, next);
+		};
 	}
 };
 //#endregion

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rhythmjs/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Command-line argument parsing, prompts, and command routing for the Rhythm middleware kernel.",
+  "homepage": "https://rhythm.js.org/cli",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -48,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rhythmjs/rhythm": "0.0.1"
+    "@rhythmjs/rhythm": "0.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
@@ -58,10 +59,5 @@
   },
   "engines": {
     "node": ">=20.19.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "typecheck": "tsc --noEmit",
-    "test": "vp test"
   }
 }