@lovrabet/cli-framework 0.1.1-beta.0

package/lib/framework/schema-export.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Schema serialization for machine-readable CLI metadata.
+ *
+ * Produces a structured JSON payload describing every command, service,
+ * flag, and argument registered in the CLI. This payload is used by:
+ * - The `--schema` / `--json-schema` introspection flag.
+ * - Language-server / IDE integrations that need to enumerate available
+ *   commands and their signatures.
+ * - Documentation generators and code-skeleton scaffolding tools.
+ *
+ * Serialized types drop TypeScript-specific constructs (e.g. `RegExp` objects
+ * become `{ source, flags, description }`) for broad compatibility.
+ */
+import type { CommandDefinition, FlagDef } from "./types.js";
+/**
+ * A serialized regex pattern from a {@link FlagDef.pattern}.
+ * RegExp objects cannot be reliably serialized to JSON, so the source
+ * string, flags, and human-readable description are preserved separately.
+ */
+export interface SerializedFlagPattern {
+    /** The regex source string (e.g. `"^[a-z]{3,8}$"`). */
+    source: string;
+    /** The regex flags string (e.g. `"i"` or `""`). */
+    flags: string;
+    /** Human-readable description of the expected format. */
+    description: string;
+}
+/**
+ * A serialized {@link FlagDef} with RegExp replaced by {@link SerializedFlagPattern}.
+ */
+export interface SerializedFlag {
+    name: string;
+    type: "string" | "boolean" | "number";
+    description: string;
+    required?: boolean;
+    default?: string | boolean | number;
+    enum?: string[];
+    pattern?: SerializedFlagPattern;
+    alias?: string;
+    hidden?: boolean;
+}
+/**
+ * A serialized {@link CommandDefinition} describing one subcommand.
+ */
+export interface SchemaCommandEntry {
+    command: string;
+    description: string;
+    /** Optional tag shown in help listings. */
+    tag?: string;
+    risk: string;
+    requiresAuth: boolean;
+    requiresAppCode: boolean;
+    hasFormat: boolean;
+    supportsDryRun: boolean;
+    args?: Array<{
+        name: string;
+        description: string;
+        required?: boolean;
+    }>;
+    flags: SerializedFlag[];
+    /**
+     * Static help extra string, or `{ dynamic: true }` when the command
+     * uses a thunk so the content cannot be serialized statically.
+     */
+    helpExtra?: string | {
+        dynamic: true;
+    };
+}
+/**
+ * A serialized service containing its command list.
+ */
+export interface SchemaServiceEntry {
+    service: string;
+    label: string;
+    isSingleCommand?: boolean;
+    defaultCommand?: string;
+    /** `true` when the service has a wildcard (`<script>`) command. */
+    hasWildcard: boolean;
+    commands: SchemaCommandEntry[];
+}
+/**
+ * The root payload of the schema export.
+ * Includes CLI identity metadata, global flags, and all services.
+ */
+export interface SchemaPayload {
+    /** Schema format version; increment when the shape changes. */
+    schemaVersion: number;
+    cli: {
+        bin: string;
+        displayName: string;
+        version: string;
+        gitCommit: string;
+    };
+    /** Global flags that apply to all commands. */
+    globalFlags: Array<{
+        name: string;
+        type: "string" | "boolean";
+        description: string;
+        hint?: string;
+        hidden?: boolean;
+    }>;
+    services: SchemaServiceEntry[];
+}
+/**
+ * A stripped-down command listing used for schema generation.
+ * Contains only the metadata needed to render command summaries.
+ */
+export interface SchemaCommandListing {
+    command: string;
+    description: string;
+    tag?: string;
+}
+/**
+ * A stripped-down service entry used for schema generation.
+ */
+export interface SchemaServiceListing {
+    service: string;
+    label: string;
+    isSingleCommand?: boolean;
+    defaultCommand?: string;
+    wildcardDef?: CommandDefinition;
+    commands: SchemaCommandListing[];
+}
+/** Options for {@link buildSchemaPayload}. */
+export interface BuildSchemaOptions {
+    /** CLI binary name. */
+    cliBinName: string;
+    /** CLI display name. */
+    cliDisplayName: string;
+    /** Current CLI version string. */
+    cliVersion: string;
+    /** Current git commit SHA. */
+    gitCommit: string;
+    /** Global flag definitions. */
+    globalFlags: Array<{
+        name: string;
+        type: "string" | "boolean";
+        description: string;
+        hint?: string;
+        hidden?: boolean;
+    }>;
+    /**
+     * Simplified service registry (without full `CommandDefinition` objects)
+     * used to enumerate services and commands.
+     */
+    serviceRegistry: SchemaServiceListing[];
+    /**
+     * Resolves the effective flag list for a command.
+     * Must include built-in flags (from {@link buildAllFlags}).
+     */
+    buildAllFlags(def: CommandDefinition): FlagDef[];
+    /**
+     * Looks up a full {@link CommandDefinition} by service and command name.
+     */
+    findDefinition(service: string, command: string): CommandDefinition | undefined;
+}
+/**
+ * Builds the complete schema payload for the CLI.
+ *
+ * Iterates over every service and command in `options.serviceRegistry`,
+ * resolves the full command definition, and serializes flags (with regex
+ * patterns converted to plain objects).
+ *
+ * @param options - Schema build options.
+ * @returns A complete {@link SchemaPayload} ready for JSON serialization.
+ *
+ * @example
+ * ```ts
+ * const schema = buildSchemaPayload({
+ *   cliBinName: "rabetbase",
+ *   // ... other options from the registry
+ * });
+ * process.stdout.write(JSON.stringify(schema, null, 2));
+ * ```
+ */
+export declare function buildSchemaPayload(options: BuildSchemaOptions): SchemaPayload;

package/lib/framework/schema-export.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Schema serialization for machine-readable CLI metadata.
+ *
+ * Produces a structured JSON payload describing every command, service,
+ * flag, and argument registered in the CLI. This payload is used by:
+ * - The `--schema` / `--json-schema` introspection flag.
+ * - Language-server / IDE integrations that need to enumerate available
+ *   commands and their signatures.
+ * - Documentation generators and code-skeleton scaffolding tools.
+ *
+ * Serialized types drop TypeScript-specific constructs (e.g. `RegExp` objects
+ * become `{ source, flags, description }`) for broad compatibility.
+ */
+/**
+ * Builds the complete schema payload for the CLI.
+ *
+ * Iterates over every service and command in `options.serviceRegistry`,
+ * resolves the full command definition, and serializes flags (with regex
+ * patterns converted to plain objects).
+ *
+ * @param options - Schema build options.
+ * @returns A complete {@link SchemaPayload} ready for JSON serialization.
+ *
+ * @example
+ * ```ts
+ * const schema = buildSchemaPayload({
+ *   cliBinName: "rabetbase",
+ *   // ... other options from the registry
+ * });
+ * process.stdout.write(JSON.stringify(schema, null, 2));
+ * ```
+ */
+export function buildSchemaPayload(options) {
+    const services = [];
+    for (const entry of options.serviceRegistry) {
+        const commands = [];
+        for (const c of entry.commands) {
+            const def = c.command === "<script>" && entry.wildcardDef
+                ? entry.wildcardDef
+                : options.findDefinition(entry.service, c.command);
+            if (!def)
+                continue;
+            commands.push(serializeCommand(def, c, options.buildAllFlags));
+        }
+        services.push({
+            service: entry.service,
+            label: entry.label,
+            ...(entry.isSingleCommand ? { isSingleCommand: true } : {}),
+            ...(entry.defaultCommand ? { defaultCommand: entry.defaultCommand } : {}),
+            hasWildcard: Boolean(entry.wildcardDef),
+            commands,
+        });
+    }
+    return {
+        schemaVersion: 1,
+        cli: {
+            bin: options.cliBinName,
+            displayName: options.cliDisplayName,
+            version: options.cliVersion,
+            gitCommit: options.gitCommit,
+        },
+        globalFlags: options.globalFlags.map((f) => ({
+            name: f.name,
+            type: f.type,
+            description: f.description,
+            ...(f.hint ? { hint: f.hint } : {}),
+            ...(f.hidden ? { hidden: true } : {}),
+        })),
+        services,
+    };
+}
+/**
+ * Serializes a single command definition into a {@link SchemaCommandEntry}.
+ *
+ * @param def            - Command definition to serialize.
+ * @param listing        - Stripped listing from the registry.
+ * @param buildAllFlagsFn - Function to build the effective flag list.
+ * @returns Serialized command entry.
+ */
+function serializeCommand(def, listing, buildAllFlagsFn) {
+    const requiresAuth = def.requiresAuth !== false;
+    const requiresAppCode = def.requiresAppCode !== false;
+    const hasFormat = def.hasFormat !== false;
+    const helpExtra = serializeHelpExtra(def);
+    return {
+        command: listing.command,
+        description: listing.description,
+        ...(listing.tag ? { tag: listing.tag.trim() } : {}),
+        risk: def.risk,
+        requiresAuth,
+        requiresAppCode,
+        hasFormat,
+        supportsDryRun: Boolean(def.dryRun),
+        ...(def.args && def.args.length > 0 ? { args: def.args } : {}),
+        flags: buildAllFlagsFn(def).map(serializeFlag),
+        ...(helpExtra !== undefined ? { helpExtra } : {}),
+    };
+}
+/**
+ * Serializes the `helpExtra` field of a command.
+ *
+ * - `undefined` → `undefined`
+ * - Static string → the string
+ * - Thunk → `{ dynamic: true }` (cannot be evaluated without running the code)
+ *
+ * @param def - Command definition.
+ * @returns Serialized help extra value.
+ */
+function serializeHelpExtra(def) {
+    if (def.helpExtra === undefined)
+        return undefined;
+    if (typeof def.helpExtra === "function")
+        return { dynamic: true };
+    return def.helpExtra;
+}
+/**
+ * Serializes a single {@link FlagDef} into a {@link SerializedFlag}.
+ * Converts the `pattern.regex` RegExp into a plain `{ source, flags, description }`
+ * object so the result is safe to serialize to JSON.
+ *
+ * @param f - Flag definition to serialize.
+ * @returns Serialized flag.
+ */
+function serializeFlag(f) {
+    const out = {
+        name: f.name,
+        type: f.type,
+        description: f.description,
+    };
+    if (f.required !== undefined)
+        out.required = f.required;
+    if (f.default !== undefined)
+        out.default = f.default;
+    if (f.enum && f.enum.length > 0)
+        out.enum = f.enum;
+    if (f.alias)
+        out.alias = f.alias;
+    if (f.hidden)
+        out.hidden = f.hidden;
+    if (f.pattern) {
+        out.pattern = {
+            source: f.pattern.regex.source,
+            flags: f.pattern.regex.flags,
+            description: f.pattern.description,
+        };
+    }
+    return out;
+}

package/lib/framework/types.d.ts

@@ -0,0 +1,338 @@
+/**
+ * @fileoverview Core domain types for the CLI framework.
+ *
+ * Defines the primitive risk levels, output formats, and the central
+ * {@link CommandDefinition} interface that every declarative command must implement.
+ */
+/**
+ * Risk level of a command, used for policy enforcement and user confirmation.
+ *
+ * - `read` – read-only operations; no confirmation required.
+ * - `write` – modifies data; may require confirmation in some contexts.
+ * - `high-risk-write` – destructive or irreversible operations; always requires
+ *   either `--yes` or an interactive `--yes/-y` confirmation prompt.
+ */
+export type Risk = "read" | "write" | "high-risk-write";
+/**
+ * Returns a numeric ordering value for a given risk level.
+ * Higher numbers indicate greater risk. Used by {@link assertRiskWithinLevel}
+ * to compare the command's risk against the configured risk ceiling.
+ *
+ * @param risk - A `Risk` value, an arbitrary string, or `undefined`.
+ * @returns `0` for `read`, `1` for `write`, `2` for `high-risk-write`, or `0` as fallback.
+ *
+ * @example
+ * ```ts
+ * riskLevelOrder("high-risk-write") > riskLevelOrder("read") // true
+ * ```
+ */
+export declare function riskLevelOrder(risk: Risk | string | undefined): number;
+/**
+ * Supported CLI output formats.
+ *
+ * - `json`     – Full JSON object with indentation (for scripting / debugging).
+ * - `pretty`   – Human-readable plain-text layout (for interactive use).
+ * - `compress` – Single-line JSON without indentation (default; for piping).
+ */
+export type OutputFormat = "json" | "pretty" | "compress";
+/**
+ * Type guard that checks whether a value is a valid {@link OutputFormat}.
+ *
+ * @param v - Any value to test.
+ * @returns `true` if `v` is `"json"`, `"pretty"`, or `"compress"`.
+ */
+export declare function isValidFormat(v: unknown): v is OutputFormat;
+/**
+ * Converts legacy or alternative format aliases to the canonical {@link OutputFormat}.
+ * The legacy alias `"table"` maps to `"pretty"`.
+ *
+ * @param v - Any value to normalize.
+ * @returns The canonical `OutputFormat`, or `undefined` if `v` cannot be mapped.
+ *
+ * @example
+ * ```ts
+ * normalizeLegacyOutputFormat("table") // "pretty"
+ * normalizeLegacyOutputFormat("compress") // "compress"
+ * normalizeLegacyOutputFormat(123) // undefined
+ * ```
+ */
+export declare function normalizeLegacyOutputFormat(v: unknown): OutputFormat | undefined;
+/**
+ * Defines a positional argument accepted by a command.
+ */
+export interface ArgDef {
+    /**
+     * Argument name shown in usage strings as `<name>`.
+     */
+    name: string;
+    /**
+     * Human-readable description shown in help output.
+     */
+    description: string;
+    /**
+     * When `true`, the argument is mandatory.
+     * @default true
+     */
+    required?: boolean;
+}
+/**
+ * Defines a named flag (CLI option) accepted by a command.
+ */
+export interface FlagDef {
+    /**
+     * Flag name, used as `--name`. Hyphens are converted internally (e.g. `--app-code`).
+     */
+    name: string;
+    /** Value type of the flag. */
+    type: "string" | "boolean" | "number";
+    /** Human-readable description shown in help output. */
+    description: string;
+    /**
+     * When `true`, the flag must be provided.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Default value applied when the flag is absent from the command line.
+     */
+    default?: string | boolean | number;
+    /**
+     * Permitted values for a string flag. Rejects any value not in this list.
+     */
+    enum?: string[];
+    /**
+     * A regex constraint with a human-readable description.
+     * Applied after parsing; throws a validation error if the value does not match.
+     */
+    pattern?: {
+        regex: RegExp;
+        description: string;
+    };
+    /**
+     * Single-character shorthand (e.g. `-f`). Short names may not be mixed-case.
+     */
+    alias?: string;
+    /**
+     * When `true`, the flag is excluded from generated help text.
+     */
+    hidden?: boolean;
+}
+/**
+ * Return type produced by every command's `execute` function.
+ * The result is passed to {@link formatOutput} for rendering.
+ */
+export interface CommandResult<T = any> {
+    /** Indicates whether the command succeeded. */
+    ok: boolean;
+    /**
+     * Structured command payload. `undefined` is valid when `ok === false`.
+     */
+    data?: T;
+    /**
+     * Human-readable message, typically shown on failure or as a fallback
+     * when `data` is empty in `pretty` mode.
+     */
+    message?: string;
+}
+/**
+ * Preview payload returned by a command's `dryRun` hook.
+ * Describes what the command *would* do without actually performing it.
+ */
+export interface DryRunResult {
+    /** HTTP method that would be used (e.g. "GET", "POST"). */
+    method: string;
+    /** Full URL that would be requested. */
+    url: string;
+    /**
+     * Request body that would be sent, if any.
+     */
+    body?: Record<string, any> | unknown[];
+    /**
+     * Optional free-text description of the operation (shown in `--help`).
+     */
+    description?: string;
+}
+/**
+ * Wraps a {@link CommandResult} with command metadata injected by the framework.
+ * This is the shape written to stdout in `json` / `compress` output modes.
+ */
+export interface OutputEnvelope<T = any> {
+    /** Mirrors `CommandResult.ok`. */
+    ok: boolean;
+    /** Full command label used to invoke the command (e.g. `"api list"`). */
+    command: string;
+    /** Risk level of the executed command. */
+    risk: Risk;
+    /**
+     * Present when the command returned data.
+     */
+    data?: T;
+    /**
+     * Present only in dry-run mode (`--dry-run`).
+     */
+    dryRun?: boolean;
+    /**
+     * Present only when `ok === false`.
+     */
+    error?: {
+        /** Fixed error code emitted alongside the message. */
+        code: string;
+        /** Human-readable error message. */
+        message: string;
+        /** Optional actionable hint. */
+        hint?: string;
+    };
+}
+/**
+ * Base interface mixed into every runtime context object passed to commands.
+ * Provides uniform access to parsed flags, positional arguments, and the
+ * `output()` helper that renders a {@link CommandResult} through the formatter.
+ */
+export interface RuntimeContextBase {
+    /**
+     * The raw parsed flags map — key is the flag name (kebab or camelCase)
+     * and value is the coerced typed value.
+     */
+    rawFlags: Record<string, any>;
+    /** Effective output format resolved from flag → config → definition default. */
+    format: OutputFormat;
+    /**
+     * `true` when the session is non-interactive (stdin is not a TTY or
+     * `--yes` / `-y` was supplied).
+     */
+    nonInteractive: boolean;
+    /**
+     * Positional arguments after the command name, in order.
+     */
+    args: string[];
+    /**
+     * Retrieves a positional argument by its name (from {@link ArgDef.name}) or
+     * by its zero-based index.
+     *
+     * @param nameOrIndex - Argument name or numeric position.
+     * @param defaultVal - Value returned when the argument is absent.
+     * @returns The argument value, `defaultVal`, or `""` if neither is available.
+     */
+    arg(nameOrIndex: string | number, defaultVal?: string): string;
+    /**
+     * Retrieves a string flag value, returning `""` when absent.
+     *
+     * @param name - Flag name.
+     */
+    str(name: string): string;
+    /**
+     * Retrieves a boolean flag value. Falls back to the boolean defaults map.
+     *
+     * @param name - Flag name.
+     */
+    bool(name: string): boolean;
+    /**
+     * Retrieves a numeric flag value. Falls back to the number defaults map or
+     * `defaultVal`.
+     *
+     * @param name       - Flag name.
+     * @param defaultVal - Fallback value when the flag is absent.
+     */
+    num(name: string, defaultVal?: number): number;
+    /**
+     * Reads a flag by name, returning the raw coerced value.
+     *
+     * @template T - Expected value type.
+     * @param name - Flag name.
+     */
+    flag<T extends string | boolean | number>(name: string): T;
+    /**
+     * Formats and prints a {@link CommandResult} using the configured format.
+     * Preferred over calling `console.log` directly so output respects the
+     * `--format` / `--jq` pipeline settings.
+     *
+     * @param result - Command result to render.
+     */
+    output<T>(result: CommandResult<T>): void;
+}
+/**
+ * Intersection of the base context with caller-supplied extra properties.
+ * The `extras` type parameter carries app-code, session cookie, and other
+ * runtime dependencies into the command's closure.
+ *
+ * @template Extras - Object shape merged on top of {@link RuntimeContextBase}.
+ */
+export type RuntimeContext<Extras extends object = {}> = RuntimeContextBase & Extras;
+/**
+ * Declarative command descriptor consumed by the framework runner.
+ *
+ * All declared commands are registered in `registry.ts` and executed through
+ * {@link runCommandWithAdapter} via a {@link RunnerAdapter} implementation.
+ *
+ * @template Ctx - Concrete context type, defaults to the untyped base.
+ */
+export interface CommandDefinition<Ctx extends RuntimeContext = RuntimeContext> {
+    /** Service namespace (e.g. `"api"`, `"dataset"`). */
+    service: string;
+    /** Subcommand name within the service (e.g. `"list"`, `"create"`). */
+    command: string;
+    /** One-line description shown in help listings. */
+    description: string;
+    /** Risk level governing confirmation and policy checks. */
+    risk: Risk;
+    /**
+     * When `false`, the command skips auth checks entirely.
+     * @default true
+     */
+    requiresAuth?: boolean;
+    /**
+     * When `false`, the command does not require an app-code context.
+     * @default true
+     */
+    requiresAppCode?: boolean;
+    /**
+     * When `true`, the command requires an active session cookie in addition to
+     * any API key credentials.
+     * @default false
+     */
+    requiresCookieAuth?: boolean;
+    /**
+     * When `false`, the `--format` flag is suppressed from this command.
+     * @default true
+     */
+    hasFormat?: boolean;
+    /**
+     * Default `--format` value specific to this command, used only when neither
+     * the CLI flag nor the config default is set.
+     */
+    defaultOutputFormat?: OutputFormat;
+    /** Ordered list of positional argument definitions. */
+    flags: FlagDef[];
+    /** Ordered list of positional argument definitions. */
+    args?: ArgDef[];
+    /**
+     * Extra text appended below the standard help block for this command.
+     * Can be a static string or a thunk for lazy / dynamic content.
+     */
+    helpExtra?: string | (() => string);
+    /**
+     * Business-level validation hook called after flag parsing but before
+     * execution. Throw a {@link CliError} (via the error factory) to halt
+     * with a formatted error.
+     *
+     * @param ctx - Fully constructed runtime context.
+     * @throws Any {@link CliError} to abort; return normally to proceed.
+     */
+    validate?: (ctx: Ctx) => Promise<void>;
+    /**
+     * Dry-run hook. When present, `--dry-run` is automatically added to the
+     * flag list and the hook is called instead of `execute`.
+     *
+     * @param ctx - Fully constructed runtime context.
+     * @returns A preview describing what would happen.
+     */
+    dryRun?: (ctx: Ctx) => Promise<DryRunResult>;
+    /**
+     * Command implementation. Return a {@link CommandResult}.
+     * Throw a {@link CliError} (via the error factory) on any failure.
+     *
+     * @param ctx - Fully constructed runtime context.
+     * @returns The command result, rendered by {@link formatOutput}.
+     */
+    execute: (ctx: Ctx) => Promise<CommandResult>;
+}