@rhythmjs/cli 0.0.1

package/README.md

@@ -0,0 +1,44 @@
+# @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.
+
+## Example
+
+```ts
+import { RhythmCli } from "@rhythmjs/cli";
+import { toCliHandler } from "@rhythmjs/cli/adapters/bun";
+
+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));
+```
+
+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 — 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`.
+
+## API
+
+- `new RhythmCli(options?)` — `options.name`, `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()`.
+
+## Runtime adapters
+
+`RhythmCli` itself is runtime-agnostic; only stdin access and the interactive prompt's I/O touch a specific runtime.
+
+- **`@rhythmjs/cli/adapters/bun`** — uses `Bun.stdin.stream()`, Bun's own native stdin API.
+- **`@rhythmjs/cli/adapters/node`** — the portable version: `process.stdin` + `node:stream`'s `Readable.toWeb()`, and `node:readline` for `createPrompt()`. No Bun-specific API at all.
+- **`@rhythmjs/cli/adapters/deno`** — re-exports the Node adapter unchanged. Deno's Node-compat layer implements `process.stdin`, `Readable.toWeb`/`fromWeb`, and `node:readline`, so the same code works correctly under Deno.

package/dist/adapters/bun.d.ts

@@ -0,0 +1,10 @@
+import { t as RhythmPrompt } from "../prompt-DXqXd-xC.js";
+import { t as RhythmCliContext } from "../context-SCtZ6pOg.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+//#region src/adapters/bun.d.ts
+export declare function toCliHandler<TContext extends RhythmCliContext, TProviders extends object = {}>(app: Rhythm<RhythmCliContext, TContext, TProviders>): (argv: string[]) => Promise<number>;
+export declare function createPrompt(): {
+  prompt: RhythmPrompt;
+  close: () => void;
+};
+//#endregion

package/dist/adapters/bun.js

@@ -0,0 +1,39 @@
+import { parseArgv } from "../argv.js";
+import { createPrompt as createPrompt$1 } from "../prompt.js";
+import { RhythmCliResponse } from "./context.js";
+import * as readline from "node:readline";
+//#region src/adapters/bun.ts
+function toCliHandler(app) {
+	const run = app.callback();
+	return async (argv) => {
+		const { flags } = parseArgv(argv);
+		const stdin = process.stdin.isTTY ? null : Bun.stdin.stream();
+		const ctx = await run({
+			argv,
+			flags,
+			stdin,
+			response: new RhythmCliResponse()
+		});
+		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(input = process.stdin, output = process.stdout) {
+	const rl = readline.createInterface({
+		input,
+		output
+	});
+	return {
+		ask: (query) => new Promise((resolve) => rl.question(query, resolve)),
+		write: (text) => {
+			output.write(text);
+		},
+		close: () => rl.close()
+	};
+}
+function createPrompt() {
+	return createPrompt$1(defaultPromptIO());
+}
+//#endregion
+export { createPrompt, toCliHandler };

package/dist/adapters/context.d.ts

@@ -0,0 +1,2 @@
+import { n as RhythmCliResponse, t as RhythmCliContext } from "../context-SCtZ6pOg.js";
+export { RhythmCliContext, RhythmCliResponse };

package/dist/adapters/context.js

@@ -0,0 +1,22 @@
+import { RhythmMutable } from "@rhythmjs/rhythm";
+//#region src/adapters/context.ts
+var RhythmCliResponse = class {
+	[RhythmMutable] = true;
+	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;
+	}
+};
+//#endregion
+export { RhythmCliResponse };

package/dist/adapters/deno.d.ts

@@ -0,0 +1,2 @@
+import { createPrompt, toCliHandler } from "./node.js";
+export { createPrompt, toCliHandler };

package/dist/adapters/deno.js

@@ -0,0 +1,2 @@
+import { createPrompt, toCliHandler } from "./node.js";
+export { createPrompt, toCliHandler };

package/dist/adapters/node.d.ts

@@ -0,0 +1,10 @@
+import { t as RhythmPrompt } from "../prompt-DXqXd-xC.js";
+import { t as RhythmCliContext } from "../context-SCtZ6pOg.js";
+import { Rhythm } from "@rhythmjs/rhythm";
+//#region src/adapters/node.d.ts
+export declare function toCliHandler<TContext extends RhythmCliContext, TProviders extends object = {}>(app: Rhythm<RhythmCliContext, TContext, TProviders>): (argv: string[]) => Promise<number>;
+export declare function createPrompt(): {
+  prompt: RhythmPrompt;
+  close: () => void;
+};
+//#endregion

package/dist/adapters/node.js

@@ -0,0 +1,40 @@
+import { parseArgv } from "../argv.js";
+import { createPrompt as createPrompt$1 } from "../prompt.js";
+import { RhythmCliResponse } from "./context.js";
+import * as readline from "node:readline";
+import { Readable } from "node:stream";
+//#region src/adapters/node.ts
+function toCliHandler(app) {
+	const run = app.callback();
+	return async (argv) => {
+		const { flags } = parseArgv(argv);
+		const stdin = process.stdin.isTTY ? null : Readable.toWeb(process.stdin);
+		const ctx = await run({
+			argv,
+			flags,
+			stdin,
+			response: new RhythmCliResponse()
+		});
+		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(input = process.stdin, output = process.stdout) {
+	const rl = readline.createInterface({
+		input,
+		output
+	});
+	return {
+		ask: (query) => new Promise((resolve) => rl.question(query, resolve)),
+		write: (text) => {
+			output.write(text);
+		},
+		close: () => rl.close()
+	};
+}
+function createPrompt() {
+	return createPrompt$1(defaultPromptIO());
+}
+//#endregion
+export { createPrompt, toCliHandler };

package/dist/argv.d.ts

@@ -0,0 +1,7 @@
+//#region src/argv.d.ts
+export interface ParsedArgv {
+  positionals: string[];
+  flags: Record<string, string | boolean>;
+}
+export declare function parseArgv(argv: readonly string[]): ParsedArgv;
+//#endregion

package/dist/argv.js

@@ -0,0 +1,47 @@
+//#region src/argv.ts
+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 !== void 0 && !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 !== void 0 && !next.startsWith("-")) {
+				flags[name] = next;
+				i++;
+			} else flags[name] = true;
+			continue;
+		}
+		positionals.push(token);
+	}
+	return {
+		positionals,
+		flags
+	};
+}
+//#endregion
+export { parseArgv };

package/dist/context-SCtZ6pOg.d.ts

@@ -0,0 +1,19 @@
+import { RhythmMutable } from "@rhythmjs/rhythm";
+//#region src/adapters/context.d.ts
+declare class RhythmCliResponse {
+  readonly [RhythmMutable] = true;
+  exitCode: number;
+  stdout: string[];
+  stderr: string[];
+  print(line: string): this;
+  printError(line: string): this;
+  exit(code: number): this;
+}
+interface RhythmCliContext {
+  argv: string[];
+  flags: Record<string, string | boolean>;
+  stdin: ReadableStream<Uint8Array> | null;
+  response: RhythmCliResponse;
+}
+//#endregion
+export { RhythmCliResponse as n, RhythmCliContext as t };

package/dist/prompt-DXqXd-xC.d.ts

@@ -0,0 +1,26 @@
+//#region src/prompt.d.ts
+interface RhythmPrompt {
+  text(message: string, options?: {
+    default?: string;
+  }): Promise<string>;
+  confirm(message: string, options?: {
+    default?: boolean;
+  }): Promise<boolean>;
+  select<T extends string>(message: string, choices: readonly T[], options?: {
+    allowCustom?: boolean;
+  }): Promise<T | string>;
+  multiSelect<T extends string>(message: string, choices: readonly T[], options?: {
+    allowCustom?: boolean;
+  }): Promise<(T | string)[]>;
+}
+interface RhythmPromptIO {
+  ask(this: void, query: string): Promise<string>;
+  write(this: void, text: string): void;
+  close?(this: void): void;
+}
+declare function createPrompt(io: RhythmPromptIO): {
+  prompt: RhythmPrompt;
+  close: () => void;
+};
+//#endregion
+export { RhythmPromptIO as n, createPrompt as r, RhythmPrompt as t };

package/dist/prompt.d.ts

@@ -0,0 +1,2 @@
+import { n as RhythmPromptIO, r as createPrompt, t as RhythmPrompt } from "./prompt-DXqXd-xC.js";
+export { RhythmPrompt, RhythmPromptIO, createPrompt };

package/dist/prompt.js

@@ -0,0 +1,62 @@
+//#region src/prompt.ts
+const CUSTOM_LABEL = "Other (type your own)";
+function createPrompt(io) {
+	const { ask, write } = io;
+	const text = async (message, options) => {
+		const suffix = options?.default ? ` (${options.default})` : "";
+		return (await ask(`${message}${suffix} `)).trim() || options?.default || "";
+	};
+	const confirm = async (message, options) => {
+		const suffix = options?.default === void 0 ? "(y/n)" : options.default ? "(Y/n)" : "(y/N)";
+		while (true) {
+			const answer = (await ask(`${message} ${suffix} `)).trim().toLowerCase();
+			if (!answer && options?.default !== void 0) return options.default;
+			if (answer === "y" || answer === "yes") return true;
+			if (answer === "n" || answer === "no") return false;
+			write("Please answer y or n.\n");
+		}
+	};
+	function listChoices(message, choices, allowCustom) {
+		write(`${message}\n`);
+		choices.forEach((choice, i) => write(`  ${i + 1}) ${choice}\n`));
+		const customIndex = allowCustom ? choices.length + 1 : -1;
+		if (allowCustom) write(`  ${customIndex}) ${CUSTOM_LABEL}\n`);
+		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.\n");
+		}
+	};
+	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\")\n");
+		while (true) {
+			const raw = await ask("Enter numbers: ");
+			const indices = raw.split(",").map((part) => Number(part.trim())).filter((n) => n !== 0 || raw.trim() === "0");
+			if (!(indices.length > 0 && indices.every((n) => Number.isInteger(n) && n >= 1 && n <= maxIndex))) {
+				write("Invalid choices, try again.\n");
+				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?.()
+	};
+}
+//#endregion
+export { createPrompt };

package/dist/rhythm-cli.d.ts

@@ -0,0 +1,20 @@
+import { t as RhythmCliContext } from "./context-SCtZ6pOg.js";
+import { DeepReadonly, Middleware, OmitHashKeys, Rhythm } 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> {
+  #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;
+  command(path: string, ...handlers: Middleware<TContext & RhythmCliCommandContext>[]): this;
+  commands(): Middleware<TContext>;
+}
+//#endregion

package/dist/rhythm-cli.js

@@ -0,0 +1,96 @@
+import { parseArgv } from "./argv.js";
+import { Rhythm, compose } from "@rhythmjs/rhythm";
+//#region src/rhythm-cli.ts
+function toSegments(command) {
+	return command.trim().split(/\s+/).filter(Boolean);
+}
+function matchCommand(pattern, positionals) {
+	if (pattern.length !== positionals.length) return null;
+	const params = {};
+	for (let i = 0; i < pattern.length; i++) {
+		const segment = pattern[i];
+		const token = positionals[i];
+		if (segment.startsWith(":")) params[segment.slice(1)] = token;
+		else if (segment !== token) return null;
+	}
+	return params;
+}
+const RhythmCliTag = Symbol("RhythmCliTag");
+var RhythmCli = class extends Rhythm {
+	#prefixSegments;
+	#entries = [];
+	#commands = [];
+	#dispatchInstalled = false;
+	constructor(options = {}) {
+		super({
+			name: options.name ?? "cli",
+			type: "controller"
+		});
+		this.#prefixSegments = options.prefix ? toSegments(options.prefix) : [];
+	}
+	use(fn) {
+		const nested = fn[RhythmCliTag];
+		if (nested) for (const entry of nested.#entries) this.#mount(entry);
+		else {
+			this.#entries.push({
+				kind: "middleware",
+				fn
+			});
+			super.use(fn);
+		}
+		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) {
+		this.#entries.push({
+			kind: "command",
+			segments,
+			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);
+		return this;
+	}
+	commands() {
+		const mw = this.middleware();
+		mw[RhythmCliTag] = this;
+		return mw;
+	}
+};
+//#endregion
+export { RhythmCli };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@rhythmjs/cli",
+  "version": "0.0.1",
+  "description": "Command-line argument parsing, prompts, and command routing for the Rhythm middleware kernel.",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhythmjs/rhythm.git",
+    "directory": "packages/cli"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/rhythm-cli.d.ts",
+      "default": "./dist/rhythm-cli.js"
+    },
+    "./argv": {
+      "types": "./dist/argv.d.ts",
+      "default": "./dist/argv.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.d.ts",
+      "default": "./dist/prompt.js"
+    },
+    "./adapters/bun": {
+      "types": "./dist/adapters/bun.d.ts",
+      "default": "./dist/adapters/bun.js"
+    },
+    "./adapters/deno": {
+      "types": "./dist/adapters/deno.d.ts",
+      "default": "./dist/adapters/deno.js"
+    },
+    "./adapters/node": {
+      "types": "./dist/adapters/node.d.ts",
+      "default": "./dist/adapters/node.js"
+    },
+    "./adapters/context": {
+      "types": "./dist/adapters/context.d.ts",
+      "default": "./dist/adapters/context.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rhythmjs/rhythm": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vite-plus": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test"
+  }
+}