@zfadhli/koko-cli 0.1.0 → 0.2.0

package/README.md

@@ -130,7 +130,7 @@ bar.increment(1, { package: "koko" });
 | `clearOnComplete` | `boolean` | `false` |
 | `stopOnComplete` | `boolean` | `false` |
 
-### `createCLI(name, version?)`
+### `createCLI(name, version?, options?)`
 
 Creates an opinionated CLI application builder (wraps cac).
 
@@ -138,6 +138,10 @@ Creates an opinionated CLI application builder (wraps cac).
 - Action handlers receive `(options, ctx)` with typed options
 - `ctx` provides `.spinner()`, `.progress()`, `.color`
 
+**Banner** — When a `version` is provided, a styled banner (`name v{version}`) is
+automatically printed to stderr before each command action. Customize or disable
+it with `.banner()`.
+
 ```ts
 const cli = createCLI("deploy", "1.0.0")
   .description("Deployment tool");
@@ -158,6 +162,30 @@ cli.command("build <input>", "Build project", (cmd) => {
 cli.parse();
 ```
 
+#### `.banner(text?)`
+
+Controls the startup banner shown before command actions.
+
+| Argument | Behavior |
+|----------|----------|
+| _(none)_ or `true` | Default `name v{version}` (bold cyan + yellow) |
+| `false` | Disable banner entirely |
+| `"Custom {name} {version}"` | Custom text; `{name}` and `{version}` are substituted |
+
+```ts
+// Disable the banner
+cli.banner(false)
+
+// Custom banner text
+cli.banner("=== {name} v{version} ===")
+```
+
+The banner can also be controlled via the third argument to `createCLI`:
+
+```ts
+createCLI("myapp", "1.0.0", { banner: false })
+```
+
 ### Icons
 
 Standardized icon constants:

package/dist/index.d.mts

@@ -67,9 +67,14 @@ interface CommandBuilder {
   action<T>(handler: CLIAction<T>): void;
 }
 type CommandSetup = (cmd: CommandBuilder) => void;
+type BannerOption = string | boolean;
+interface CLIOptions {
+  banner?: BannerOption;
+}
 interface CLIBuilder {
   command(name: string, description: string, setup: CommandSetup): CLIBuilder;
   description(text: string): CLIBuilder;
+  banner(text?: BannerOption): CLIBuilder;
   parse(argv?: string[]): void;
 }
 //#endregion
@@ -81,6 +86,11 @@ interface CLIBuilder {
  * receives a typed options object and a `ctx` with built-in access to
  * spinner, progress bar, and colors.
  *
+ * When a `version` is provided, a styled banner (`name v{version}`) is
+ * automatically printed to stderr before every command action. Use
+ * `.banner(false)` to disable or `.banner("Custom {name} {version}")`
+ * to customize.
+ *
  * ```ts
  * const cli = createCLI('my-app', '1.0.0').description('My CLI')
  *
@@ -98,7 +108,7 @@ interface CLIBuilder {
  * cli.parse()
  * ```
  */
-declare function createCLI(name: string, version?: string): CLIBuilder;
+declare function createCLI(name: string, version?: string, options?: CLIOptions): CLIBuilder;
 //#endregion
 //#region src/errors.d.ts
 declare class CliToolkitError extends Error {
@@ -158,4 +168,4 @@ declare function createProgress(options: ProgressOptions): ProgressInstance;
  */
 declare function createSpinner(text?: string, options?: SpinnerOptions): SpinnerInstance;
 //#endregion
-export { type CLIAction, type CLIBuilder, CliToolkitError, type ColorName, type CommandBuilder, type CommandContext, type CommandSetup, ICON_ERROR, ICON_INFO, ICON_SUCCESS, ICON_WARN, type OptionConfig, type ProgressInstance, type ProgressOptions, type SpinnerInstance, type SpinnerOptions, type SpinnerStyle, type StyleName, color, createCLI, createProgress, createSpinner };
+export { type BannerOption, type CLIAction, type CLIBuilder, type CLIOptions, CliToolkitError, type ColorName, type CommandBuilder, type CommandContext, type CommandSetup, ICON_ERROR, ICON_INFO, ICON_SUCCESS, ICON_WARN, type OptionConfig, type ProgressInstance, type ProgressOptions, type SpinnerInstance, type SpinnerOptions, type SpinnerStyle, type StyleName, color, createCLI, createProgress, createSpinner };

package/dist/index.mjs

@@ -247,12 +247,31 @@ function parsePositionalNames(rawName) {
 	return names;
 }
 /**
+* Resolve the banner text to display before a command action runs.
+*
+* Returns `null` when the banner should be suppressed.
+*/
+function resolveBanner(config, name, version) {
+	if (config === false || config === void 0) return null;
+	if (typeof config === "string") {
+		if (!config) return null;
+		return config.replace(/\{name\}/g, name).replace(/\{version\}/g, version ?? "");
+	}
+	if (!version) return null;
+	return `${color.bold(color.cyan(name))} ${color.yellow(`v${version}`)}`;
+}
+/**
 * Create a CLI application with an opinionated builder API.
 *
 * Auto-attaches `--help` and `--version`. Each command's action handler
 * receives a typed options object and a `ctx` with built-in access to
 * spinner, progress bar, and colors.
 *
+* When a `version` is provided, a styled banner (`name v{version}`) is
+* automatically printed to stderr before every command action. Use
+* `.banner(false)` to disable or `.banner("Custom {name} {version}")`
+* to customize.
+*
 * ```ts
 * const cli = createCLI('my-app', '1.0.0').description('My CLI')
 *
@@ -270,10 +289,11 @@ function parsePositionalNames(rawName) {
 * cli.parse()
 * ```
 */
-function createCLI(name, version) {
+function createCLI(name, version, options) {
 	const cli = cac(name);
 	if (version) cli.version(version);
 	cli.help();
+	let bannerConfig = options?.banner ?? (version ? true : void 0);
 	function createContext() {
 		return {
 			color,
@@ -290,6 +310,10 @@ function createCLI(name, version) {
 			cli.usage(text);
 			return builder;
 		},
+		banner(text) {
+			bannerConfig = text ?? true;
+			return builder;
+		},
 		command(rawName, description, setup) {
 			const positionalNames = parsePositionalNames(rawName);
 			const rawCmd = cli.command(rawName, description);
@@ -304,6 +328,8 @@ function createCLI(name, version) {
 				},
 				action(handler) {
 					rawCmd.action((...args) => {
+						const bannerText = resolveBanner(bannerConfig, name, version);
+						if (bannerText) console.error(bannerText);
 						const options = args[args.length - 1];
 						for (let i = 0; i < positionalNames.length; i++) options[positionalNames[i]] = args[i];
 						return handler(options, createContext());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zfadhli/koko-cli",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Composition-based CLI toolkit — wraps cac, picocolors, cli-progress, cli-spinners",
   "license": "MIT",
   "author": "Koko contributors",