@lovrabet/cli-framework 0.1.1-beta.0

package/README.md

@@ -0,0 +1,246 @@
+# @lovrabet/cli-framework
+
+[![English](https://img.shields.io/badge/-English-blue?style=flat-square)](README.md)
+[![中文](https://img.shields.io/badge/-中文-red?style=flat-square)](README_zh-CN.md)
+[![Bahasa Indonesia](https://img.shields.io/badge/-Bahasa%20Indonesia-green?style=flat-square)](README_id-ID.md)
+[![日本語](https://img.shields.io/badge/-日本語-orange?style=flat-square)](README_ja-JP.md)
+[![Türkçe](https://img.shields.io/badge/-Türkçe-purple?style=flat-square)](README_tr-TR.md)
+
+A lightweight, type-safe CLI framework for building structured command-line tools with built-in flag parsing, output formatting, risk control, and dry-run support.
+
+## Features
+
+- **Type-Safe Commands** — Define commands with TypeScript interfaces for flags, arguments, and results
+- **Flexible Flag Parsing** — Supports string, boolean, number types with validation, enums, and regex patterns
+- **Multiple Output Formats** — JSON, pretty-printed, and compress modes
+- **Risk Control** — Built-in risk levels (read/write/high-risk-write) with configurable policies
+- **Dry-Run Mode** — Preview commands without executing them
+- **Context-Aware Runtime** — Unified runtime context with helper methods for flags and output
+- **Help Generation** — Automatic help text generation from command definitions
+- **Schema Export** — Export command schemas for tooling and documentation
+
+## Installation
+
+```bash
+bun add @lovrabet/cli-framework
+```
+
+## Quick Start
+
+`runCommandWithAdapter(def, env, adapter)` needs:
+- `def`: declarative command definition
+- `env`: raw CLI input/environment values
+- `adapter`: CLI-specific bridge implementation (errors, output, prepare, confirmation, risk policy)
+
+```typescript
+import {
+  createCliErrors,
+  formatOutput,
+  runCommandWithAdapter,
+  type CommandDefinition,
+  type RunnerAdapter,
+  type RunnerEnvBase,
+} from "@lovrabet/cli-framework";
+
+const myCommand: CommandDefinition = {
+  service: "app",
+  command: "list",
+  description: "List all applications",
+  risk: "read",
+  requiresAuth: true,
+  flags: [
+    { name: "format", type: "string", description: "Output format", default: "compress" },
+    { name: "page", type: "number", description: "Page number", default: 1 },
+  ],
+  async execute(ctx) {
+    const apps = await fetchApps({ page: ctx.num("page") });
+    return { ok: true, data: apps };
+  },
+};
+
+const env: RunnerEnvBase = {
+  rawFlags: { format: "compress", page: 1 },
+  isNonInteractive: true,
+  args: [],
+};
+
+const CliErrors = createCliErrors({ programName: "my-cli" });
+
+const adapter: RunnerAdapter<RunnerEnvBase> = {
+  cliErrors: CliErrors,
+  formatOutput,
+  getCommandLabel: (def) => `${def.service} ${def.command}`,
+  prepare: async () => ({ extras: {} }),
+  confirmHighRisk: async () => {},
+  riskPolicy: {
+    createError: (message) => CliErrors.validation(message),
+  },
+};
+
+await runCommandWithAdapter(myCommand, env, adapter);
+```
+
+## Core Concepts
+
+### Command Definition
+
+A command consists of:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `service` | `string` | Service/namespace grouping |
+| `command` | `string` | Command name |
+| `description` | `string` | Help text description |
+| `risk` | `Risk` | Risk level: `read`, `write`, `high-risk-write` |
+| `flags` | `FlagDef[]` | Flag definitions |
+| `args` | `ArgDef[]` | Positional argument definitions |
+| `validate` | `(ctx) => Promise<void>` | Pre-execution validation |
+| `dryRun` | `(ctx) => Promise<DryRunResult>` | Dry-run implementation |
+| `execute` | `(ctx) => Promise<CommandResult>` | Main execution logic |
+
+### Flag Types
+
+```typescript
+// String flag with enum
+{ name: "format", type: "string", enum: ["json", "pretty", "compress"], default: "compress" }
+
+// Boolean flag
+{ name: "dry-run", type: "boolean", description: "Preview without executing" }
+
+// Number flag with validation
+{ name: "page", type: "number", default: 1 }
+
+// String with regex pattern
+{ name: "appcode", type: "string", pattern: { regex: /^[a-z0-9-]+$/, description: "lowercase alphanumeric with dashes" } }
+```
+
+### Output Formats
+
+| Format | Description |
+|--------|-------------|
+| `json` | Raw JSON output |
+| `pretty` | Formatted JSON with colors |
+| `compress` | Minified single-line JSON (default) |
+
+### Risk Levels
+
+| Level | Order | Description |
+|-------|-------|-------------|
+| `read` | 0 | Safe read operations |
+| `write` | 1 | Data modification |
+| `high-risk-write` | 2 | Destructive operations |
+
+## API Reference
+
+### Types
+
+```typescript
+// Core types
+export type { CommandDefinition, CommandResult, RuntimeContext, FlagDef, Risk }
+
+// Runner types
+export type { RunnerAdapter, RunnerEnvBase, RiskPolicy }
+
+// Help types
+export type { HelpGeneratorOptions, HelpServiceEntry }
+```
+
+### Functions
+
+```typescript
+// Command execution
+runCommandWithAdapter(def, env, adapter)
+
+// Flag helpers
+createFlagHelpers(cliErrors) → { parseFlags, validateFlags }
+
+// Output formatting
+formatOutput(result, options)
+
+// Runtime context builders
+buildRuntimeContext(options)
+resolveOutputConfig(options)
+assertRiskWithinLevel(options)
+runDryRunIfNeeded(options)
+
+// Help generation
+createHelpGenerators(options)
+
+// Schema export
+buildSchemaPayload(commands, options)
+
+// Utilities
+extractList(data) → ListResponse
+extractPaging(data) → Paging
+resolveJqFilter(filter, data)
+```
+
+### Error Handling
+
+```typescript
+import { CliError, createCliErrors } from "@lovrabet/cli-framework";
+
+const CliErrors = createCliErrors({ programName: "my-cli" });
+
+throw CliErrors.flagMissing("appcode", "App code is required");
+throw CliErrors.validation("Invalid format value");
+throw CliErrors.authRequired("Login first with: my-cli auth login");
+```
+
+## Example: Complete CLI Setup
+
+```typescript
+import { 
+  runCommandWithAdapter, 
+  createFlagHelpers,
+  formatOutput,
+  CliError,
+} from "@lovrabet/cli-framework";
+import type { CommandDefinition, RunnerAdapter } from "@lovrabet/cli-framework";
+
+const adapter: RunnerAdapter<any> = {
+  cliErrors: createCliErrors({ programName: "myapp" }),
+  formatOutput,
+  getCommandLabel: (def) => `${def.service} ${def.command}`,
+  prepare: async (def, env, flags) => ({
+    appCode: flags["appcode"] as string,
+    cookie: env.cookie,
+    apiDomain: "https://api.example.com",
+    apiDir: "/v1",
+  }),
+  confirmHighRisk: async ({ commandLabel }) => {
+    const confirmed = await confirm(`${commandLabel}?`);
+    if (!confirmed) throw new CliError("cancelled");
+  },
+  riskPolicy: {
+    createError: (msg) => new Error(msg),
+  },
+};
+
+// Define and run commands
+const commands: CommandDefinition[] = [listCommand, createCommand, deleteCommand];
+
+for (const def of commands) {
+  await runCommandWithAdapter(def, env, adapter);
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Type check
+bun run typecheck
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+## License
+
+MIT

package/lib/errors.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Error types, factory interfaces, and creator for CLI-specific errors.
+ * All CLI errors are expressed as {@link CliError} instances with a machine-readable
+ * `code`, numeric `exitCode`, human-readable `message`, and optional `hint`.
+ */
+/**
+ * Unified CLI error class thrown by command handlers and caught by the top-level
+ * error handler in the runner/adapter.
+ *
+ * @example
+ * ```ts
+ * throw new CliError("flag_missing", 1, "Missing required flag: --appcode", "Use --appcode=<code>");
+ * ```
+ */
+export declare class CliError extends Error {
+    /** Machine-readable error code (e.g. "auth_required", "flag_missing"). */
+    readonly code: string;
+    /**
+     * Numeric exit code to emit on process exit.
+     * - `0` = success or user-cancelled
+     * - `1` = validation / user error
+     * - `2` = network / API / system error
+     */
+    readonly exitCode: number;
+    /** Optional hint shown after the error message to guide the user. */
+    readonly hint?: string;
+    /**
+     * @param code     - Machine-readable error identifier.
+     * @param exitCode - Process exit code.
+     * @param message  - Human-readable error message.
+     * @param hint     - Optional actionable hint displayed below the message.
+     */
+    constructor(code: string, exitCode: number, message: string, hint?: string);
+}
+/**
+ * Shape of the error factory returned by {@link createCliErrors}.
+ * Each method produces a typed {@link CliError} with a known `code` and `exitCode`.
+ */
+export interface CliErrorsShape {
+    /**
+     * Creates an error when the command requires authentication but none is present.
+     * @param hint - Optional override of the default auth hint.
+     */
+    authRequired(hint?: string): CliError;
+    /**
+     * Creates an error when the configuration file cannot be found.
+     * @param hint - Optional override of the default config hint.
+     */
+    configMissing(hint?: string): CliError;
+    /** Creates an error when the current directory is not inside a project. */
+    notInProject(): CliError;
+    /**
+     * Creates an error for a failed API call.
+     * @param message - Raw API error message.
+     * @param hint    - Optional hint for recovery.
+     */
+    apiError(message: string, hint?: string): CliError;
+    /**
+     * Creates an error for a network-level failure.
+     * @param message - Brief description of the network problem.
+     */
+    networkError(message: string): CliError;
+    /**
+     * Creates an error for an unrecognized command or subcommand.
+     * @param cmd - The command string that was not recognized.
+     */
+    unknownCommand(cmd: string): CliError;
+    /**
+     * Creates an error when a required flag is missing.
+     * @param flagName - Name of the missing flag (without leading `--`).
+     * @param hint     - Optional hint describing how to provide the flag.
+     */
+    flagMissing(flagName: string, hint?: string): CliError;
+    /**
+     * Creates an error for general business-logic validation failures.
+     * @param message - Description of the validation failure.
+     * @param hint    - Optional hint for correcting the input.
+     */
+    validation(message: string, hint?: string): CliError;
+    /**
+     * Creates an error signalling the user cancelled an interactive prompt (Ctrl+C).
+     * Exit code is `0`; the top-level handler treats this as a silent success.
+     * @param message - Optional override of the default cancellation message.
+     */
+    cancelled(message?: string): CliError;
+}
+/**
+ * Configuration options passed to {@link createCliErrors}.
+ * These supply the CLI binary name and the default hint messages used when
+ * callers do not provide explicit hints.
+ */
+export interface CliErrorFactoryOptions {
+    /** CLI binary name used in auto-generated hint messages (e.g. "rabetbase"). */
+    cliBinName: string;
+    /** Default hint shown when `authRequired()` is called without an explicit hint. */
+    authRequiredHint: string;
+    /** Default hint shown when `configMissing()` is called without an explicit hint. */
+    configMissingHint: string;
+    /** Default hint shown when `notInProject()` is called without an explicit hint. */
+    notInProjectHint: string;
+}
+/**
+ * Creates a pre-configured {@link CliErrorsShape} instance.
+ * The returned factory uses `options.cliBinName` and the default hints from
+ * `options` for any method call that does not receive an explicit hint.
+ *
+ * @param options - Bin name and default hint messages.
+ * @returns A fully-populated error factory.
+ *
+ * @example
+ * ```ts
+ * const cliErrors = createCliErrors({
+ *   cliBinName: "mycli",
+ *   authRequiredHint: "Run `mycli auth login` first.",
+ *   configMissingHint: "Run `mycli init` to create a project.",
+ *   notInProjectHint: " cd into your project directory and try again.",
+ * });
+ * throw cliErrors.flagMissing("appcode");
+ * ```
+ */
+export declare function createCliErrors(options: CliErrorFactoryOptions): CliErrorsShape;

package/lib/errors.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Error types, factory interfaces, and creator for CLI-specific errors.
+ * All CLI errors are expressed as {@link CliError} instances with a machine-readable
+ * `code`, numeric `exitCode`, human-readable `message`, and optional `hint`.
+ */
+/**
+ * Unified CLI error class thrown by command handlers and caught by the top-level
+ * error handler in the runner/adapter.
+ *
+ * @example
+ * ```ts
+ * throw new CliError("flag_missing", 1, "Missing required flag: --appcode", "Use --appcode=<code>");
+ * ```
+ */
+export class CliError extends Error {
+    /** Machine-readable error code (e.g. "auth_required", "flag_missing"). */
+    code;
+    /**
+     * Numeric exit code to emit on process exit.
+     * - `0` = success or user-cancelled
+     * - `1` = validation / user error
+     * - `2` = network / API / system error
+     */
+    exitCode;
+    /** Optional hint shown after the error message to guide the user. */
+    hint;
+    /**
+     * @param code     - Machine-readable error identifier.
+     * @param exitCode - Process exit code.
+     * @param message  - Human-readable error message.
+     * @param hint     - Optional actionable hint displayed below the message.
+     */
+    constructor(code, exitCode, message, hint) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.exitCode = exitCode;
+        this.hint = hint;
+    }
+}
+/**
+ * Creates a pre-configured {@link CliErrorsShape} instance.
+ * The returned factory uses `options.cliBinName` and the default hints from
+ * `options` for any method call that does not receive an explicit hint.
+ *
+ * @param options - Bin name and default hint messages.
+ * @returns A fully-populated error factory.
+ *
+ * @example
+ * ```ts
+ * const cliErrors = createCliErrors({
+ *   cliBinName: "mycli",
+ *   authRequiredHint: "Run `mycli auth login` first.",
+ *   configMissingHint: "Run `mycli init` to create a project.",
+ *   notInProjectHint: " cd into your project directory and try again.",
+ * });
+ * throw cliErrors.flagMissing("appcode");
+ * ```
+ */
+export function createCliErrors(options) {
+    const { cliBinName, authRequiredHint, configMissingHint, notInProjectHint } = options;
+    return {
+        authRequired: (hint) => new CliError("auth_required", 1, "Authentication required", hint ?? authRequiredHint),
+        configMissing: (hint) => new CliError("config_missing", 1, "Configuration file not found", hint ?? configMissingHint),
+        notInProject: () => new CliError("not_in_project", 1, `Not in a ${cliBinName} project directory`, notInProjectHint),
+        apiError: (message, hint) => new CliError("api_error", 2, message, hint),
+        networkError: (message) => new CliError("network_error", 2, `Network error: ${message}`, "Check your internet connection and try again."),
+        unknownCommand: (cmd) => new CliError("unknown_command", 1, `Unknown command: ${cmd}`, `Run \`${cliBinName} --help\` to see available commands.`),
+        flagMissing: (flagName, hint) => new CliError("flag_missing", 1, `Missing required flag: --${flagName}`, hint),
+        validation: (message, hint) => new CliError("validation_error", 1, message, hint),
+        cancelled: (message) => new CliError("cancelled", 0, message ?? "Operation cancelled.", undefined),
+    };
+}

package/lib/framework/build-all-flags.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Builds the complete effective flag list for a command.
+ *
+ * Injects framework-managed built-in flags (`--dry-run`, `--format`, `--yes`)
+ * alongside the command's own flag definitions, so the runner only needs to
+ * pass a single merged list to {@link createFlagHelpers}.
+ */
+import type { CommandDefinition, FlagDef } from "./types.js";
+/**
+ * Options for {@link buildAllFlags}.
+ */
+export interface BuildAllFlagsOptions {
+    /**
+     * The global default output format, used as the fallback for `--format`
+     * when the command does not define its own `defaultOutputFormat`.
+     */
+    defaultOutputFormat: "json" | "pretty" | "compress";
+}
+/**
+ * Builds the full effective flag list for a command by appending
+ * framework-injected flags when appropriate:
+ *
+ * - `--dry-run` (boolean) — added only when the command defines a `dryRun` hook.
+ * - `--format` (string)   — added unless `hasFormat === false`; defaults to
+ *   `def.defaultOutputFormat ?? options.defaultOutputFormat`.
+ * - `--yes` (boolean)     — added only for `high-risk-write` commands.
+ *
+ * @param def     - Command definition to extend.
+ * @param options - Global options supplying the default format.
+ * @returns A new array containing command flags plus any applicable built-in flags.
+ *
+ * @example
+ * ```ts
+ * const allFlags = buildAllFlags(myCommandDef, { defaultOutputFormat: "compress" });
+ * const { parseFlags } = createFlagHelpers(cliErrors);
+ * const flags = parseFlags(allFlags, rawFlags);
+ * ```
+ */
+export declare function buildAllFlags(def: CommandDefinition, options: BuildAllFlagsOptions): FlagDef[];

package/lib/framework/build-all-flags.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Builds the complete effective flag list for a command.
+ *
+ * Injects framework-managed built-in flags (`--dry-run`, `--format`, `--yes`)
+ * alongside the command's own flag definitions, so the runner only needs to
+ * pass a single merged list to {@link createFlagHelpers}.
+ */
+/**
+ * Builds the full effective flag list for a command by appending
+ * framework-injected flags when appropriate:
+ *
+ * - `--dry-run` (boolean) — added only when the command defines a `dryRun` hook.
+ * - `--format` (string)   — added unless `hasFormat === false`; defaults to
+ *   `def.defaultOutputFormat ?? options.defaultOutputFormat`.
+ * - `--yes` (boolean)     — added only for `high-risk-write` commands.
+ *
+ * @param def     - Command definition to extend.
+ * @param options - Global options supplying the default format.
+ * @returns A new array containing command flags plus any applicable built-in flags.
+ *
+ * @example
+ * ```ts
+ * const allFlags = buildAllFlags(myCommandDef, { defaultOutputFormat: "compress" });
+ * const { parseFlags } = createFlagHelpers(cliErrors);
+ * const flags = parseFlags(allFlags, rawFlags);
+ * ```
+ */
+export function buildAllFlags(def, options) {
+    const flags = [...def.flags];
+    if (def.dryRun) {
+        flags.push({
+            name: "dry-run",
+            type: "boolean",
+            description: "Preview the operation without executing",
+        });
+    }
+    if (def.hasFormat !== false) {
+        flags.push({
+            name: "format",
+            type: "string",
+            default: def.defaultOutputFormat ?? options.defaultOutputFormat,
+            enum: ["json", "pretty", "compress"],
+            description: "Output format",
+        });
+    }
+    if (def.risk === "high-risk-write") {
+        flags.push({
+            name: "yes",
+            type: "boolean",
+            description: "Skip confirmation prompt",
+        });
+    }
+    return flags;
+}

package/lib/framework/flags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Flag parsing and validation helpers.
+ *
+ * Provides the {@link createFlagHelpers} factory which returns `parseFlags`
+ * and `validateFlags` — the two-phase pipeline used by the runner adapter.
+ *
+ * Phase 1 (`parseFlags`): coerce raw CLI inputs into typed values using
+ * {@link FlagDef} metadata.
+ *
+ * Phase 2 (`validateFlags`): enforce `required`, `enum`, and `pattern`
+ * constraints and throw typed {@link CliError} on violation.
+ */
+import type { CliErrorsShape } from "../errors.js";
+import type { FlagDef } from "./types.js";
+/**
+ * Result of {@link parseFlags}: a flat map of flag names to their coerced
+ * typed values. Missing flags with defaults are populated; missing flags
+ * without defaults are `undefined`.
+ */
+export type ParsedFlags = Record<string, string | boolean | number | undefined>;
+/**
+ * Creates a paired set of flag helpers used by the framework runner.
+ *
+ * @param cliErrors - Subset of the error factory providing `flagMissing` and `validation`.
+ * @returns An object with `parseFlags` and `validateFlags` functions.
+ *
+ * @example
+ * ```ts
+ * const { parseFlags, validateFlags } = createFlagHelpers(cliErrors);
+ * const flags = parseFlags(flagDefs, rawInput);
+ * validateFlags(flagDefs, flags, "api list");
+ * ```
+ */
+export declare function createFlagHelpers(cliErrors: Pick<CliErrorsShape, "flagMissing" | "validation">): {
+    parseFlags: (defs: FlagDef[], rawFlags: Record<string, any>) => ParsedFlags;
+    validateFlags: (defs: FlagDef[], parsed: ParsedFlags, commandLabel: string) => void;
+};