@kb-labs/shared-cli-ui 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1037 @@
+export { DebugContext, DebugDetailLevel, DebugEntry, DebugExportOptions, DebugFilterOptions, DebugFormat, DebugLevel, DebugMeta, DebugOutput, DebugOutputOptions, DebugSection, DebugTrace, DebugTree, DebugTreeNode, DebugTreeOptions, HumanFormatterOptions, TraceOptions, createDebugTree, describeEntriesAI, describeEntriesHuman, describeEntriesTimeline, exportDebugEntries, exportToChromeFormat, exportToJSON, exportToPlainText, filterByLevel, filterByNamespace, filterByTimeRange, filterDebugEntries, formatDebugEntriesAI, formatDebugEntriesHuman, formatDebugEntryAI, formatDebugEntryHuman, formatDebugOutput, formatDebugOutputs, formatTimeline, formatTimelineNode, formatTimelineWithSummary, groupByGroup, groupByNamespace, searchInLogs, shouldUseAIFormat } from './debug.js';
+
+/**
+ * Minimalist color utilities for CLI output
+ * Uses strategic color application - only for status, not decoration
+ */
+declare const colors: {
+    success: (text: string) => string;
+    error: (text: string) => string;
+    warning: (text: string) => string;
+    info: (text: string) => string;
+    primary: (text: string) => string;
+    accent: (text: string) => string;
+    highlight: (text: string) => string;
+    secondary: (text: string) => string;
+    emphasis: (text: string) => string;
+    muted: (text: string) => string;
+    foreground: (text: string) => string;
+    dim: (text: string) => string;
+    bold: (text: string) => string;
+    underline: (text: string) => string;
+    inverse: (text: string) => string;
+};
+declare const symbols: {
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    bullet: string;
+    clock: string;
+    folder: string;
+    package: string;
+    pointer: string;
+    section: string;
+};
+declare const supportsColor: boolean;
+declare const safeColors: {
+    success: (text: string) => string;
+    error: (text: string) => string;
+    warning: (text: string) => string;
+    info: (text: string) => string;
+    accent: (text: string) => string;
+    primary: (text: string) => string;
+    highlight: (text: string) => string;
+    secondary: (text: string) => string;
+    emphasis: (text: string) => string;
+    foreground: (text: string) => string;
+    muted: (text: string) => string;
+    dim: (text: string) => string;
+    bold: (text: string) => string;
+    underline: (text: string) => string;
+    inverse: (text: string) => string;
+};
+declare const safeSymbols: {
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    bullet: string;
+    clock: string;
+    folder: string;
+    package: string;
+    pointer: string;
+    section: string;
+    separator: string;
+    border: string;
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    leftT: string;
+    rightT: string;
+};
+
+/**
+ * Progress indicators and loaders for CLI operations
+ *
+ * Periodic animation implementation (works in child processes as multi-line output).
+ */
+interface LoaderOptions {
+    /** Text to show while loading */
+    text?: string;
+    /** Whether to show spinner (true) or progress bar (false) */
+    spinner?: boolean;
+    /** Total items for progress bar */
+    total?: number;
+    /** Current item for progress bar */
+    current?: number;
+    /** Whether JSON mode is enabled (disables all visual feedback) */
+    jsonMode?: boolean;
+}
+declare class Loader {
+    private isActive;
+    private options;
+    private frameIndex;
+    private intervalId?;
+    private currentText;
+    constructor(options?: LoaderOptions);
+    start(): void;
+    update(options: Partial<LoaderOptions>): void;
+    stop(): void;
+    succeed(message?: string): void;
+    fail(message?: string): void;
+    private clearInterval;
+    private updateProgress;
+}
+/**
+ * Create a simple spinner
+ */
+declare function createSpinner(text: string, jsonMode?: boolean): Loader;
+/**
+ * Create a progress bar
+ */
+declare function createProgressBar(text: string, total: number, jsonMode?: boolean): Loader;
+/**
+ * Simple loading message without spinner
+ */
+declare function showLoading(text: string, jsonMode?: boolean): void;
+/**
+ * Show completion message
+ */
+declare function showSuccess(text: string, jsonMode?: boolean): void;
+/**
+ * Show error message
+ */
+declare function showError(text: string, jsonMode?: boolean): void;
+/**
+ * Create a loader for progress indication
+ *
+ * @param text - Text to display while loading
+ * @param options - Optional configuration
+ * @returns Loader instance
+ *
+ * @example
+ * ```typescript
+ * import { useLoader } from '@kb-labs/sdk';
+ *
+ * const loader = useLoader('Processing data...');
+ * loader.start();
+ * // ... do work ...
+ * loader.succeed('Processing complete!');
+ * ```
+ */
+declare function useLoader(text: string, options?: Partial<LoaderOptions>): Loader;
+
+/**
+ * Output formatting utilities for structured CLI output
+ */
+declare function stripAnsi(input: string): string;
+declare function hasAnsi(input: string): boolean;
+/**
+ * Create a boxed section with title
+ */
+declare function box(title: string, content?: string[], maxWidth?: number): string;
+/**
+ * Add consistent indentation to lines
+ */
+declare function indent(lines: string[], level?: number): string[];
+/**
+ * Create a section with header and content
+ */
+declare function section(header: string, content: string[]): string[];
+/**
+ * Format a table with consistent spacing
+ */
+declare function table(rows: (string | number)[][], headers?: string[]): string[];
+/**
+ * Format key-value pairs
+ */
+interface KeyValueOptions {
+    padKeys?: boolean;
+}
+declare function keyValue(pairs: Record<string, string | number>, options?: KeyValueOptions): string[];
+/**
+ * Format a list with bullets
+ */
+declare function bulletList(items: string[]): string[];
+interface SafeKeyValueOptions {
+    indent?: number;
+    pad?: boolean;
+    valueColor?: (value: string, key: string) => string;
+}
+declare function safeKeyValue(pairs: Record<string, string | number>, options?: SafeKeyValueOptions): string[];
+/**
+ * Apply primary headline styling
+ */
+declare function headline(text: string): string;
+/**
+ * Accent label style (used for tags/pills)
+ */
+declare function accentLabel(text: string): string;
+/**
+ * Muted helper
+ */
+declare function muted(text: string): string;
+/**
+ * Format file size
+ */
+declare function formatSize(bytes: number): string;
+/**
+ * Format relative time
+ */
+declare function formatRelativeTime(timestamp: string | Date): string;
+interface FormatTimestampOptions {
+    mode?: 'local' | 'iso';
+    timeZone?: string;
+    includeSeconds?: boolean;
+    includeMilliseconds?: boolean;
+    includeOffset?: boolean;
+}
+/**
+ * Format timestamps as absolute values (local or ISO) with optional offsets
+ */
+declare function formatTimestamp(timestamp: string | Date, options?: FormatTimestampOptions): string;
+/**
+ * Truncate text with ellipsis
+ */
+declare function truncate(text: string, maxLength: number): string;
+/**
+ * Pad string to specific width
+ */
+declare function pad(text: string, width: number, align?: 'left' | 'right' | 'center'): string;
+
+/**
+ * Command output formatting utilities
+ * Provides consistent formatting for CLI command results
+ */
+interface CommandResult {
+    title: string;
+    summary: Record<string, string | number>;
+    timing?: number | Record<string, number>;
+    diagnostics?: string[];
+    warnings?: string[];
+    errors?: string[];
+    suggestions?: string[];
+}
+/**
+ * Format timing in milliseconds to human-readable string
+ */
+declare function formatTiming(ms: number): string;
+/**
+ * Format timing breakdown as array of strings
+ */
+declare function formatTimingBreakdown(timings: Record<string, number>): string[];
+/**
+ * Format complete command output with box, summary, timing, and additional info
+ */
+declare function formatCommandOutput(result: CommandResult): string;
+/**
+ * Create a simple command result with just title, summary, and timing
+ */
+declare function createSimpleResult(title: string, summary: Record<string, string | number>, timing?: number): CommandResult;
+/**
+ * Create a detailed command result with all optional fields
+ */
+declare function createDetailedResult(title: string, summary: Record<string, string | number>, options?: {
+    timing?: number | Record<string, number>;
+    diagnostics?: string[];
+    warnings?: string[];
+    errors?: string[];
+    suggestions?: string[];
+}): CommandResult;
+
+/**
+ * Timing tracker utility for CLI commands
+ * Provides checkpoint-based timing measurement
+ */
+declare class TimingTracker {
+    private start;
+    private checkpoints;
+    constructor();
+    /**
+     * Record a timing checkpoint
+     */
+    checkpoint(name: string): void;
+    /**
+     * Get total elapsed time in milliseconds
+     */
+    total(): number;
+    /**
+     * Get timing breakdown including total
+     */
+    breakdown(): Record<string, number>;
+    /**
+     * Get timing breakdown without total
+     */
+    checkpointsOnly(): Record<string, number>;
+    /**
+     * Reset the timer
+     */
+    reset(): void;
+    /**
+     * Get elapsed time since last checkpoint or start
+     */
+    sinceLastCheckpoint(): number;
+    /**
+     * Get elapsed time since a specific checkpoint
+     */
+    sinceCheckpoint(checkpointName: string): number | null;
+}
+
+/**
+ * Command suggestions and validation utilities
+ */
+interface CommandSuggestion {
+    id: string;
+    command: string;
+    args: string[];
+    description: string;
+    impact: 'safe' | 'disruptive';
+    when: string;
+    available?: boolean;
+}
+interface CommandRegistry {
+    commands: Set<string>;
+    groups: Map<string, Set<string>>;
+}
+/**
+ * Create a command registry from available commands
+ */
+declare function createCommandRegistry(commands: string[]): CommandRegistry;
+/**
+ * Check if a command is available in the registry
+ */
+declare function isCommandAvailable(command: string, registry: CommandRegistry): boolean;
+/**
+ * Validate suggestions against available commands
+ */
+declare function validateSuggestions(suggestions: CommandSuggestion[], registry: CommandRegistry): CommandSuggestion[];
+/**
+ * Generate common devlink suggestions
+ */
+declare function generateDevlinkSuggestions(warningCodes: Set<string>, context: {
+    undo?: {
+        available: boolean;
+    };
+}, registry: CommandRegistry): CommandSuggestion[];
+/**
+ * Generate quick actions for common scenarios
+ */
+declare function generateQuickActions(hasWarnings: boolean, registry: CommandRegistry, group?: string): CommandSuggestion[];
+
+/**
+ * Command discovery utilities for CLI systems
+ */
+interface CommandInfo {
+    id: string;
+    group: string;
+    name: string;
+    description: string;
+    available: boolean;
+}
+/**
+ * Discover available commands from CLI manifest or registry
+ * This is a generic interface that can be implemented by different CLI systems
+ */
+interface CommandDiscovery {
+    /**
+     * Get all available commands
+     */
+    getAvailableCommands(): Promise<string[]>;
+    /**
+     * Get command info by ID
+     */
+    getCommandInfo(commandId: string): Promise<CommandInfo | null>;
+    /**
+     * Check if a command is available
+     */
+    isCommandAvailable(commandId: string): Promise<boolean>;
+}
+/**
+ * Simple command discovery that works with a predefined list
+ * Can be extended to work with actual CLI registries
+ */
+declare class StaticCommandDiscovery implements CommandDiscovery {
+    private commands;
+    constructor(commands: string[]);
+    getAvailableCommands(): Promise<string[]>;
+    getCommandInfo(commandId: string): Promise<CommandInfo | null>;
+    isCommandAvailable(commandId: string): Promise<boolean>;
+}
+/**
+ * Create a command discovery instance from a command list
+ */
+declare function createCommandDiscovery(commands: string[]): CommandDiscovery;
+
+/**
+ * CLI manifest parsing utilities
+ */
+interface CommandManifest {
+    manifestVersion: string;
+    id: string;
+    aliases?: string[];
+    group: string;
+    describe: string;
+    longDescription?: string;
+    requires?: string[];
+    flags?: FlagDefinition[];
+    examples?: string[];
+    loader: () => Promise<{
+        run: any;
+    }>;
+}
+interface FlagDefinition {
+    name: string;
+    type: 'string' | 'boolean' | 'number' | 'array';
+    alias?: string;
+    default?: any;
+    description?: string;
+    choices?: string[];
+    required?: boolean;
+}
+/**
+ * Extract command IDs from a manifest
+ */
+declare function extractCommandIds(manifest: CommandManifest[]): string[];
+/**
+ * Extract command groups from a manifest
+ */
+declare function extractCommandGroups(manifest: CommandManifest[]): string[];
+/**
+ * Find commands by group
+ */
+declare function findCommandsByGroup(manifest: CommandManifest[], group: string): CommandManifest[];
+/**
+ * Find command by ID
+ */
+declare function findCommandById(manifest: CommandManifest[], id: string): CommandManifest | undefined;
+/**
+ * Get command info for suggestions
+ */
+declare function getCommandInfo(manifest: CommandManifest[], commandId: string): {
+    id: string;
+    group: string;
+    name: string;
+    description: string;
+    available: boolean;
+} | null;
+/**
+ * Generate suggestions for a specific group
+ */
+declare function generateGroupSuggestions(manifest: CommandManifest[], group: string, _warningCodes: Set<string>, _context: any): Array<{
+    id: string;
+    command: string;
+    args: string[];
+    description: string;
+    impact: 'safe' | 'disruptive';
+    when: string;
+    available: boolean;
+}>;
+
+/**
+ * Multi-CLI suggestions system
+ * Supports multiple CLI packages with their own manifests
+ */
+
+interface MultiCLIContext {
+    warningCodes: Set<string>;
+    [key: string]: any;
+}
+interface CLIPackage {
+    name: string;
+    group: string;
+    commands: CommandManifest[];
+    priority: number;
+}
+/**
+ * Multi-CLI suggestions manager
+ */
+declare class MultiCLISuggestions {
+    private packages;
+    private globalRegistry;
+    /**
+     * Register a CLI package
+     */
+    registerPackage(pkg: CLIPackage): void;
+    /**
+     * Get or create global command registry
+     */
+    private getGlobalRegistry;
+    /**
+     * Generate suggestions for a specific group
+     */
+    generateGroupSuggestions(group: string, context: MultiCLIContext): CommandSuggestion[];
+    /**
+     * Generate all suggestions across all packages
+     */
+    generateAllSuggestions(context: MultiCLIContext): CommandSuggestion[];
+    /**
+     * Get available commands for a group
+     */
+    getAvailableCommands(group: string): string[];
+    /**
+     * Get all registered packages
+     */
+    getPackages(): CLIPackage[];
+}
+
+/**
+ * Dynamic command discovery that loads commands from actual manifests
+ */
+
+interface ManifestLoader {
+    loadManifest(packageName: string): Promise<any[]>;
+}
+/**
+ * Dynamic command discovery that loads commands from manifests
+ */
+declare class DynamicCommandDiscovery implements CommandDiscovery {
+    private manifestLoader;
+    private packageNames;
+    private manifestCache;
+    private commandCache;
+    constructor(manifestLoader: ManifestLoader, packageNames: string[]);
+    getAvailableCommands(): Promise<string[]>;
+    getCommandInfo(commandId: string): Promise<CommandInfo | null>;
+    isCommandAvailable(commandId: string): Promise<boolean>;
+    private loadManifest;
+}
+/**
+ * Create a dynamic command discovery for KB Labs packages
+ */
+declare function createKBLabsCommandDiscovery(): DynamicCommandDiscovery;
+
+interface ArtifactInfo {
+    name: string;
+    path: string;
+    size?: number;
+    modified?: Date;
+    description: string;
+}
+interface ArtifactDisplayOptions {
+    showSize?: boolean;
+    showTime?: boolean;
+    showDescription?: boolean;
+    maxItems?: number;
+    title?: string;
+    groupBy?: 'none' | 'type' | 'time';
+}
+/**
+ * Display artifacts information in CLI
+ */
+declare function displayArtifacts(artifacts: ArtifactInfo[], options?: ArtifactDisplayOptions): string[];
+/**
+ * Display a single artifact with full details
+ */
+declare function displaySingleArtifact(artifact: ArtifactInfo, title?: string): string[];
+/**
+ * Display artifacts in a compact format (for status-like displays)
+ */
+declare function displayArtifactsCompact(artifacts: ArtifactInfo[], options?: {
+    maxItems?: number;
+    showSize?: boolean;
+    sortByTime?: boolean;
+    showTime?: boolean;
+    title?: string;
+}): string[];
+/**
+ * Discover artifacts in a directory based on patterns
+ *
+ * @param baseDir - Base directory to search for artifacts
+ * @param patterns - Array of artifact patterns to search for
+ * @returns Array of discovered artifacts
+ *
+ * @example
+ * ```typescript
+ * const artifacts = await discoverArtifacts('.kb/mind', [
+ *   { name: 'Index', pattern: 'index.json', description: 'Main index' },
+ *   { name: 'API Index', pattern: 'api-index.json', description: 'API index' },
+ * ]);
+ * ```
+ */
+declare function discoverArtifacts(baseDir: string, patterns: Array<{
+    name: string;
+    pattern: string;
+    description?: string;
+}>): Promise<ArtifactInfo[]>;
+
+/**
+ * Table formatting utilities for CLI output
+ * Handles proper column alignment accounting for emoji/unicode width
+ */
+interface TableColumn {
+    header: string;
+    width?: number;
+    align?: 'left' | 'right' | 'center';
+}
+interface TableOptions {
+    header?: boolean;
+    separator?: string;
+    padding?: number;
+}
+/**
+ * Format data as a table with proper column alignment
+ */
+declare function formatTable(columns: TableColumn[], rows: string[][], options?: TableOptions): string[];
+/**
+ * Format simple key-value pairs as a table
+ */
+declare function formatKeyValueTable(data: Record<string, string | number>, options?: {
+    keyWidth?: number;
+    valueWidth?: number;
+}): string[];
+
+interface CommandPresenter {
+    info(message: string): void;
+    warn?(message: string): void;
+    error(message: string): void;
+    write(payload: string): void;
+    json(payload: unknown): void;
+}
+interface CommandContext {
+    cwd: string;
+    presenter: CommandPresenter;
+}
+interface CommandExecutionResult {
+    summary: Record<string, string | number>;
+    artifacts?: ArtifactInfo[];
+    artifactsOptions?: ArtifactDisplayOptions;
+    timing?: number | Record<string, number>;
+    diagnostics?: string[];
+    warnings?: string[];
+    errors?: string[];
+    data?: Record<string, unknown>;
+}
+interface AnalyticsConfig {
+    actor: string;
+    started: string;
+    finished: string;
+    getPayload?: (flags: Record<string, unknown>, result?: CommandExecutionResult) => Record<string, unknown>;
+}
+interface CommandRunnerOptions {
+    title: string;
+    analytics?: AnalyticsConfig;
+    execute: (ctx: CommandContext, flags: Record<string, unknown>, tracker: TimingTracker) => Promise<CommandExecutionResult>;
+}
+declare function createCommandRunner(options: CommandRunnerOptions): (ctx: CommandContext, argv: string[], flags: Record<string, unknown>) => Promise<number>;
+
+/**
+ * Flag system for declarative CLI flag definition with type safety
+ *
+ * Usage:
+ * ```typescript
+ * // In contracts
+ * export const myFlags = defineFlags({
+ *   scope: { type: 'string', description: 'Filter by scope' },
+ *   verbose: { type: 'boolean', default: false },
+ * });
+ *
+ * // In command
+ * export default defineCommand({
+ *   flags: myFlags,
+ *   handler: {
+ *     async execute(ctx, input: typeof myFlags.type) {
+ *       const { scope, verbose } = input;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type FlagType = 'string' | 'boolean' | 'number';
+interface BaseFlagSpec<T extends FlagType> {
+    type: T;
+    description?: string;
+    examples?: string[];
+    deprecated?: boolean | string;
+}
+interface StringFlagSpec extends BaseFlagSpec<'string'> {
+    default?: string;
+    validate?: (value: string) => void | Promise<void>;
+}
+interface BooleanFlagSpec extends BaseFlagSpec<'boolean'> {
+    default?: boolean;
+}
+interface NumberFlagSpec extends BaseFlagSpec<'number'> {
+    default?: number;
+    validate?: (value: number) => void | Promise<void>;
+}
+type FlagSpec = StringFlagSpec | BooleanFlagSpec | NumberFlagSpec;
+type FlagsSchema = Record<string, FlagSpec>;
+type InferFlagType<T extends FlagSpec> = T extends StringFlagSpec ? T extends {
+    default: string;
+} ? string : string | undefined : T extends BooleanFlagSpec ? T extends {
+    default: boolean;
+} ? boolean : boolean | undefined : T extends NumberFlagSpec ? T extends {
+    default: number;
+} ? number : number | undefined : never;
+type InferFlagsType<T extends FlagsSchema> = {
+    [K in keyof T]: InferFlagType<T[K]>;
+};
+interface FlagsDefinition<T extends FlagsSchema> {
+    /** Schema for manifest */
+    schema: T;
+    /** Inferred TypeScript type */
+    type: InferFlagsType<T>;
+    /** Parse and validate flags from raw input */
+    parse: (input: unknown) => InferFlagsType<T>;
+}
+/**
+ * Define CLI flags with type safety and validation
+ *
+ * @example
+ * ```typescript
+ * export const commitFlags = defineFlags({
+ *   scope: {
+ *     type: 'string',
+ *     description: 'Limit to package or path',
+ *     examples: ['@kb-labs/core', 'packages/**'],
+ *   },
+ *   'dry-run': {
+ *     type: 'boolean',
+ *     description: 'Preview without applying',
+ *     default: false,
+ *   },
+ * });
+ *
+ * // Use in command
+ * type MyInput = typeof commitFlags.type;
+ * // Result: { scope?: string; 'dry-run': boolean }
+ * ```
+ */
+declare function defineFlags<T extends FlagsSchema>(schema: T): FlagsDefinition<T>;
+/**
+ * Parse flags from raw input with type validation and defaults
+ */
+declare function parseFlagsFromInput<T extends FlagsSchema>(input: unknown, schema: T): InferFlagsType<T>;
+declare function parseBoolean(value: unknown, flagName: string): boolean;
+declare function parseString(value: unknown, flagName: string): string;
+declare function parseNumber(value: unknown, flagName: string): number;
+declare function parseNumberFlag(value: unknown): number | undefined;
+/**
+ * Merge input.flags into input root (V3 compatibility helper)
+ *
+ * @example
+ * ```typescript
+ * const raw = { scope: 'old', flags: { scope: 'new', json: true } };
+ * const merged = mergeFlags(raw);
+ * // Result: { scope: 'new', json: true, flags: {...} }
+ * ```
+ */
+declare function mergeFlags<T extends Record<string, unknown>>(input: T): T;
+
+/**
+ * Environment variable system for declarative env definition with type safety
+ *
+ * Usage:
+ * ```typescript
+ * // In contracts
+ * export const myEnv = defineEnv({
+ *   MY_API_KEY: { type: 'string', description: 'API key for service' },
+ *   MY_ENABLED: { type: 'boolean', default: true },
+ *   MY_TIMEOUT: { type: 'number', default: 5000 },
+ * });
+ *
+ * // In command
+ * export default defineCommand({
+ *   handler: {
+ *     async execute(ctx, input) {
+ *       const env = myEnv.parse(ctx.runtime);
+ *       console.log(env.MY_API_KEY); // string | undefined
+ *       console.log(env.MY_ENABLED); // boolean
+ *     }
+ *   }
+ * });
+ * ```
+ */
+
+/**
+ * Runtime API interface (minimal for env parsing)
+ * Avoids dependency on @kb-labs/plugin-contracts
+ */
+interface RuntimeLike {
+    env(key: string): string | undefined;
+}
+/**
+ * Environment variable schema (reuses FlagSpec types)
+ */
+type EnvSchema = FlagsSchema;
+/**
+ * Environment variable definition with parse method
+ */
+interface EnvDefinition<T extends EnvSchema> {
+    /** Schema for documentation and validation */
+    schema: T;
+    /** Inferred TypeScript type */
+    type: InferFlagsType<T>;
+    /** Parse environment variables from RuntimeLike */
+    parse: (runtime: RuntimeLike) => InferFlagsType<T>;
+}
+/**
+ * Define environment variables with type safety and validation
+ *
+ * @example
+ * ```typescript
+ * export const commitEnv = defineEnv({
+ *   KB_COMMIT_LLM_ENABLED: {
+ *     type: 'boolean',
+ *     default: true,
+ *     description: 'Enable LLM analysis',
+ *   },
+ *   KB_COMMIT_LLM_TEMPERATURE: {
+ *     type: 'number',
+ *     default: 0.3,
+ *     description: 'LLM temperature (0-1)',
+ *     validate: (v) => {
+ *       if (v < 0 || v > 1) throw new Error('Must be 0-1');
+ *     },
+ *   },
+ * });
+ *
+ * // Use in command
+ * const env = commitEnv.parse(ctx.runtime);
+ * // Type: { KB_COMMIT_LLM_ENABLED: boolean; KB_COMMIT_LLM_TEMPERATURE: number }
+ * ```
+ */
+declare function defineEnv<T extends EnvSchema>(schema: T): EnvDefinition<T>;
+/**
+ * Parse environment variables from RuntimeLike with validation and defaults
+ */
+declare function parseEnvFromRuntime<T extends EnvSchema>(runtime: RuntimeLike, schema: T): InferFlagsType<T>;
+
+/**
+ * Resolve the current working directory from a CLI context-like object.
+ * Falls back to the process cwd when the context does not provide one.
+ */
+declare function getContextCwd(input: {
+    cwd?: string;
+} | undefined): string;
+
+/**
+ * Normalize filesystem paths to POSIX (forward-slash) form.
+ */
+declare function toPosixPath(input: string): string;
+
+/**
+ * Modern CLI formatting utilities with side border design
+ * Provides minimalist, modern UI components for CLI output
+ */
+
+/**
+ * Side border box - modern minimalist design
+ *
+ * @example
+ * ```
+ * ┌── Command Name
+ * │
+ * │ Section Header
+ * │  Key: value
+ * │
+ * └── ✓ Success / 12ms
+ * ```
+ */
+interface SideBorderBoxOptions {
+    title: string;
+    sections: SectionContent[];
+    footer?: string;
+    status?: 'success' | 'error' | 'warning' | 'info';
+    timing?: number;
+}
+interface SectionContent {
+    header?: string;
+    items: string[];
+}
+/**
+ * Create a side-bordered box with modern design
+ */
+declare function sideBorderBox(options: SideBorderBoxOptions): string;
+/**
+ * Format a section header
+ */
+declare function sectionHeader(text: string): string;
+/**
+ * Format metrics list (key: value pairs with aligned values)
+ */
+declare function metricsList(metrics: Record<string, string | number>): string[];
+/**
+ * Format status line for footer
+ */
+declare function statusLine(status: 'success' | 'error' | 'warning' | 'info', timing?: number): string;
+/**
+ * Format command help in modern side-border style
+ *
+ * @example
+ * ```typescript
+ * const help = formatCommandHelp({
+ *   title: 'kb version',
+ *   description: 'Show CLI version',
+ *   longDescription: 'Displays the current version...',
+ *   examples: ['kb version', 'kb version --json'],
+ *   flags: [{name: 'json', description: 'Output in JSON'}]
+ * });
+ * ```
+ */
+declare function formatCommandHelp(options: {
+    title: string;
+    description?: string;
+    longDescription?: string;
+    examples?: string[];
+    flags?: Array<{
+        name: string;
+        alias?: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    aliases?: string[];
+}): string;
+
+/**
+ * Command result formatting utilities
+ * Provides high and low-level APIs for formatting command output
+ */
+/**
+ * Command output with human and machine-readable formats
+ * Extends CommandResult contract from command-kit
+ */
+interface CommandOutput {
+    /** Whether command executed successfully - required by CommandResult contract */
+    ok: boolean;
+    /** Execution status */
+    status?: 'success' | 'error' | 'warning' | 'info' | 'failed' | 'cancelled' | 'skipped';
+    /** Human-readable output (side border format) */
+    human: string;
+    /** Machine-readable output (JSON) */
+    json: object;
+    /** Agent-specific output (optional, for --agent flag) */
+    agent?: object;
+}
+/**
+ * Parameters for formatting command results
+ */
+interface CommandResultParams {
+    title: string;
+    summary?: Record<string, string | number>;
+    details?: Array<{
+        section: string;
+        items: string[];
+    }>;
+    warnings?: string[];
+    errors?: string[];
+    timing?: number;
+    status: 'success' | 'error' | 'warning' | 'info';
+    /** Custom JSON data (optional) */
+    jsonData?: object;
+}
+/**
+ * Low-level: Format command result with full control
+ *
+ * @example
+ * ```typescript
+ * const output = formatCommandResult({
+ *   title: 'System Diagnostics',
+ *   summary: { 'Total Checks': 4, 'OK': 3 },
+ *   details: [
+ *     { section: 'Environment', items: ['Node 20.11.0'] }
+ *   ],
+ *   warnings: ['Cache is old'],
+ *   timing: 150,
+ *   status: 'success',
+ * });
+ *
+ * console.log(output.human);  // Pretty CLI output
+ * console.log(output.json);   // JSON for --json flag
+ * ```
+ */
+declare function formatCommandResult(params: CommandResultParams): CommandOutput;
+/**
+ * High-level: Quick success result
+ *
+ * @example
+ * ```typescript
+ * return successResult('Version Info', {
+ *   summary: { 'CLI Version': '0.1.0' },
+ *   timing: 5,
+ * });
+ * ```
+ */
+declare function successResult(title: string, data?: {
+    summary?: Record<string, string | number>;
+    details?: Array<{
+        section: string;
+        items: string[];
+    }>;
+    timing?: number;
+    json?: object;
+}): CommandOutput;
+/**
+ * High-level: Quick error result
+ *
+ * @example
+ * ```typescript
+ * return errorResult('Command Failed', new Error('Something went wrong'), {
+ *   timing: 100,
+ *   suggestions: ['Try running with --debug flag'],
+ * });
+ * ```
+ */
+declare function errorResult(title: string, error: Error | string, options?: {
+    timing?: number;
+    suggestions?: string[];
+}): CommandOutput;
+/**
+ * High-level: Quick warning result
+ *
+ * @example
+ * ```typescript
+ * return warningResult('Configuration Updated', ['Deprecated option used'], {
+ *   summary: { 'Files Updated': 3 },
+ *   timing: 50,
+ * });
+ * ```
+ */
+declare function warningResult(title: string, warnings: string[], options?: {
+    summary?: Record<string, string | number>;
+    timing?: number;
+}): CommandOutput;
+/**
+ * High-level: Info result
+ *
+ * @example
+ * ```typescript
+ * return infoResult('Help Information', {
+ *   details: [
+ *     { section: 'Usage', items: ['kb command --flag'] }
+ *   ],
+ * });
+ * ```
+ */
+declare function infoResult(title: string, data?: {
+    summary?: Record<string, string | number>;
+    details?: Array<{
+        section: string;
+        items: string[];
+    }>;
+    timing?: number;
+}): CommandOutput;
+
+export { type AnalyticsConfig, type ArtifactDisplayOptions, type ArtifactInfo, type BaseFlagSpec, type BooleanFlagSpec, type CLIPackage, type CommandContext, type CommandDiscovery, type CommandExecutionResult, type CommandInfo, type CommandManifest, type CommandOutput, type CommandPresenter, type CommandRegistry, type CommandResult, type CommandResultParams, type CommandRunnerOptions, type CommandSuggestion, DynamicCommandDiscovery, type EnvDefinition, type EnvSchema, type FlagDefinition, type FlagSpec, type FlagType, type FlagsDefinition, type FlagsSchema, type FormatTimestampOptions, type InferFlagsType, type KeyValueOptions, Loader, type LoaderOptions, type ManifestLoader, type MultiCLIContext, MultiCLISuggestions, type NumberFlagSpec, type RuntimeLike, type SafeKeyValueOptions, type SectionContent, type SideBorderBoxOptions, StaticCommandDiscovery, type StringFlagSpec, type TableColumn, type TableOptions, TimingTracker, accentLabel, box, bulletList, colors, createCommandDiscovery, createCommandRegistry, createCommandRunner, createDetailedResult, createKBLabsCommandDiscovery, createProgressBar, createSimpleResult, createSpinner, defineEnv, defineFlags, discoverArtifacts, displayArtifacts, displayArtifactsCompact, displaySingleArtifact, errorResult, extractCommandGroups, extractCommandIds, findCommandById, findCommandsByGroup, formatCommandHelp, formatCommandOutput, formatCommandResult, formatKeyValueTable, formatRelativeTime, formatSize, formatTable, formatTimestamp, formatTiming, formatTimingBreakdown, generateDevlinkSuggestions, generateGroupSuggestions, generateQuickActions, getCommandInfo, getContextCwd, hasAnsi, headline, indent, infoResult, isCommandAvailable, keyValue, mergeFlags, metricsList, muted, pad, parseBoolean, parseEnvFromRuntime, parseFlagsFromInput, parseNumber, parseNumberFlag, parseString, safeColors, safeKeyValue, safeSymbols, section, sectionHeader, showError, showLoading, showSuccess, sideBorderBox, statusLine, stripAnsi, successResult, supportsColor, symbols, table, toPosixPath, truncate, useLoader, validateSuggestions, warningResult };