@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/errors/format-validation.ts

@@ -0,0 +1,144 @@
+/**
+ * @module @kb-labs/shared-command-kit/errors/format-validation
+ * User-friendly formatting for flag validation errors
+ */
+
+import type { FlagValidationError, StringFlagSchema } from '../flags/types';
+import type { FlagSchemaDefinition } from '../flags/types';
+
+/**
+ * Format a validation error into a user-friendly message
+ *
+ * @example
+ * ```
+ * ❌ Missing required flag: --text
+ *
+ * Usage: kb mind rag-query --text <query>
+ * Hint: Try kb mind rag-query --help
+ * ```
+ */
+export function formatValidationError(
+  error: FlagValidationError,
+  options: {
+    commandName?: string;
+    schema?: FlagSchemaDefinition;
+  } = {}
+): string {
+  const { commandName, schema } = options;
+  const lines: string[] = [];
+
+  // Main error message with emoji
+  const errorMsg = error.message;
+
+  // Determine error type and format accordingly
+  if (errorMsg.includes('is required')) {
+    lines.push(`❌ Missing required flag: --${error.flag}`);
+  } else if (errorMsg.includes('must be one of')) {
+    // Extract the invalid value if available
+    const valueStr = error.value !== undefined ? ` ${error.value}` : '';
+    lines.push(`❌ Invalid value for --${error.flag}:${valueStr}`);
+  } else if (errorMsg.includes('must be a')) {
+    lines.push(`❌ Invalid type for --${error.flag}`);
+  } else if (errorMsg.includes('conflicts with')) {
+    lines.push(`❌ Flag conflict: --${error.flag}`);
+  } else if (errorMsg.includes('depends on')) {
+    lines.push(`❌ Missing dependency for --${error.flag}`);
+  } else {
+    // Fallback: use the original message
+    lines.push(`❌ ${errorMsg}`);
+  }
+
+  lines.push(''); // Empty line for spacing
+
+  // Generate usage hint if we have schema and command name
+  if (commandName && schema) {
+    const usageLine = generateUsageLine(commandName, schema, error.flag);
+    if (usageLine) {
+      lines.push(`Usage: ${usageLine}`);
+    }
+  }
+
+  // Add help hint
+  if (commandName) {
+    lines.push(`Hint: Try ${commandName} --help`);
+  } else {
+    lines.push('Hint: Try --help for more information');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a usage line from command name and schema
+ *
+ * @example
+ * generateUsageLine('kb mind rag-query', schema, 'text')
+ * // Returns: 'kb mind rag-query --text <query> [options]'
+ */
+function generateUsageLine(
+  commandName: string,
+  schema: FlagSchemaDefinition,
+  errorFlag: string
+): string {
+  const parts: string[] = [commandName];
+
+  // Add the flag that caused the error first
+  const errorFlagSchema = schema[errorFlag];
+  if (errorFlagSchema) {
+    const flagStr = formatFlagForUsage(errorFlag, errorFlagSchema);
+    parts.push(flagStr);
+  }
+
+  // Check if there are other required flags
+  const otherRequiredFlags = Object.entries(schema)
+    .filter(([name, flagSchema]) =>
+      name !== errorFlag && flagSchema.required
+    );
+
+  if (otherRequiredFlags.length > 0) {
+    // Add other required flags
+    for (const [name, flagSchema] of otherRequiredFlags) {
+      parts.push(formatFlagForUsage(name, flagSchema));
+    }
+  }
+
+  // Add [options] if there are optional flags
+  const hasOptionalFlags = Object.values(schema).some(s => !s.required);
+  if (hasOptionalFlags) {
+    parts.push('[options]');
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Format a single flag for usage display
+ *
+ * @example
+ * formatFlagForUsage('text', { type: 'string', required: true })
+ * // Returns: '--text <text>'
+ *
+ * formatFlagForUsage('mode', { type: 'string', choices: ['local', 'auto'] })
+ * // Returns: '[--mode <local|auto>]'
+ */
+function formatFlagForUsage(
+  name: string,
+  schema: FlagSchemaDefinition[string]
+): string {
+  let valueHint: string;
+
+  if ('choices' in schema && (schema as StringFlagSchema).choices && (schema as StringFlagSchema).choices!.length > 0) {
+    // Show choices: <local|auto>
+    valueHint = `<${(schema as StringFlagSchema).choices!.join('|')}>`;
+  } else if (schema.type === 'boolean') {
+    // Boolean flags don't need a value hint
+    return schema.required ? `--${name}` : `[--${name}]`;
+  } else {
+    // Generic type hint: <text>, <number>, etc.
+    valueHint = `<${name}>`;
+  }
+
+  const flagPart = `--${name} ${valueHint}`;
+
+  return schema.required ? flagPart : `[${flagPart}]`;
+}

package/packages/shared-command-kit/src/errors/format.ts

@@ -0,0 +1,92 @@
+/**
+ * @module @kb-labs/shared-command-kit/errors/format
+ * Error formatting utilities
+ */
+
+import type { FormattedError, FormatErrorOptions } from './types';
+import { FlagValidationError } from '../flags/types';
+import { formatValidationError } from './format-validation';
+
+/**
+ * Format error for display
+ * 
+ * @example
+ * ```typescript
+ * const formatted = formatError(error, {
+ *   jsonMode: Boolean(flags.json),
+ *   showStack: Boolean(flags.debug),
+ *   timingMs: tracker.total(),
+ * });
+ * 
+ * if (flags.json) {
+ *   ctx.output?.json(formatted.json);
+ * } else {
+ *   ctx.output?.error(formatted.message);
+ * }
+ * ```
+ */
+export function formatError(
+  error: unknown,
+  options: FormatErrorOptions = {}
+): FormattedError {
+  const { showStack = false, timingMs } = options;
+
+  // Special handling for FlagValidationError
+  if (error instanceof FlagValidationError) {
+    const friendlyMessage = formatValidationError(error, {
+      commandName: error.commandName,
+      schema: error.schema,
+    });
+
+    const json: FormattedError['json'] = {
+      ok: false,
+      error: error.message,
+    };
+
+    if (timingMs !== undefined) {
+      json.timingMs = timingMs;
+    }
+
+    if (showStack && error.stack) {
+      json.stack = error.stack;
+    }
+
+    let message = friendlyMessage;
+    if (showStack && error.stack) {
+      message = `${friendlyMessage}\n\nStack trace:\n${error.stack}`;
+    }
+
+    return {
+      message,
+      json,
+    };
+  }
+
+  // Standard error formatting for other errors
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : undefined;
+
+  const json: FormattedError['json'] = {
+    ok: false,
+    error: errorMessage,
+  };
+
+  if (timingMs !== undefined) {
+    json.timingMs = timingMs;
+  }
+
+  if (showStack && errorStack) {
+    json.stack = errorStack;
+  }
+
+  let message = errorMessage;
+  if (showStack && errorStack) {
+    message = `${errorMessage}\n\n${errorStack}`;
+  }
+
+  return {
+    message,
+    json,
+  };
+}
+

package/packages/shared-command-kit/src/errors/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module @kb-labs/shared-command-kit/errors
+ * Error formatting utilities and error factory
+ */
+
+export * from './types';
+export * from './format';
+export * from './factory';
+

package/packages/shared-command-kit/src/errors/types.ts

@@ -0,0 +1,32 @@
+/**
+ * @module @kb-labs/shared-command-kit/errors/types
+ * Types for error formatting
+ */
+
+/**
+ * Formatted error result
+ */
+export interface FormattedError {
+  /** Human-readable error message */
+  message: string;
+  /** JSON representation */
+  json: {
+    ok: false;
+    error: string;
+    timingMs?: number;
+    stack?: string;
+  };
+}
+
+/**
+ * Error formatting options
+ */
+export interface FormatErrorOptions {
+  /** Output in JSON format */
+  jsonMode?: boolean;
+  /** Include stack trace */
+  showStack?: boolean;
+  /** Timing information */
+  timingMs?: number;
+}
+

package/packages/shared-command-kit/src/flags/define.ts

@@ -0,0 +1,92 @@
+/**
+ * @module @kb-labs/shared-command-kit/flags/define
+ * Define flag schemas with automatic type inference
+ */
+
+import type {
+  FlagSchemaDefinition,
+  BooleanFlagSchema,
+  StringFlagSchema,
+  NumberFlagSchema,
+  ArrayFlagSchema,
+} from './types';
+
+/**
+ * Flag schema with type inference
+ */
+export interface FlagSchemaWithInfer<T extends FlagSchemaDefinition> {
+  /** Original schema definition */
+  readonly schema: T;
+  /** Infer TypeScript type from schema */
+  infer: InferFlags<T>;
+}
+
+/**
+ * Infer TypeScript type from flag schema definition
+ */
+export type InferFlags<T extends FlagSchemaDefinition> = {
+  [K in keyof T]: T[K] extends BooleanFlagSchema
+    ? T[K]['default'] extends boolean
+      ? boolean
+      : T[K]['required'] extends true
+        ? boolean
+        : boolean | undefined
+    : T[K] extends StringFlagSchema
+      ? T[K]['choices'] extends readonly string[]
+        ? T[K]['required'] extends true
+          ? T[K]['choices'][number]
+          : T[K]['default'] extends string
+            ? T[K]['choices'][number]
+            : T[K]['choices'][number] | undefined
+        : T[K]['required'] extends true
+          ? string
+          : T[K]['default'] extends string
+            ? string
+            : string | undefined
+      : T[K] extends NumberFlagSchema
+        ? T[K]['required'] extends true
+          ? number
+          : T[K]['default'] extends number
+            ? number
+            : number | undefined
+        : T[K] extends ArrayFlagSchema
+          ? T[K]['items'] extends 'string'
+            ? string[]
+            : T[K]['items'] extends 'number'
+              ? number[]
+              : T[K]['items'] extends 'boolean'
+                ? boolean[]
+                : unknown[]
+          : unknown;
+};
+
+/**
+ * Define a flag schema with automatic type inference
+ *
+ * @example
+ * ```typescript
+ * const schema = defineFlags({
+ *   scope: {
+ *     type: 'string',
+ *     required: true,
+ *     pattern: /^[@a-z0-9-/]+$/i,
+ *   },
+ *   'dry-run': {
+ *     type: 'boolean',
+ *     default: false,
+ *   },
+ * });
+ *
+ * type Flags = typeof schema.infer;
+ * // Flags = { scope: string; 'dry-run': boolean }
+ * ```
+ */
+export function defineFlags<T extends FlagSchemaDefinition>(
+  definition: T
+): FlagSchemaWithInfer<T> {
+  return {
+    schema: definition,
+    infer: {} as InferFlags<T>,
+  };
+}
+

package/packages/shared-command-kit/src/flags/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module @kb-labs/shared-command-kit/flags
+ * Flag validation and schema definition
+ */
+
+export * from './types';
+export * from './define';
+export * from './validate';
+

package/packages/shared-command-kit/src/flags/types.ts

@@ -0,0 +1,153 @@
+/**
+ * @module @kb-labs/shared-command-kit/flags/types
+ * Types for flag validation and schema definition
+ */
+
+/**
+ * Flag type definition
+ */
+export type FlagType = 'boolean' | 'string' | 'number' | 'array';
+
+/**
+ * Base flag schema definition
+ */
+export interface BaseFlagSchema<T extends FlagType = FlagType> {
+  /** Flag name */
+  name?: string;
+  /** Flag type */
+  type: T;
+  /** Short alias (e.g., 'n' for 'dry-run') */
+  alias?: string;
+  /** Description for help text */
+  description?: string;
+  /** Default value if flag is not provided */
+  default?: unknown;
+  /** Whether flag is required */
+  required?: boolean;
+  /** Flags that conflict with this flag */
+  conflicts?: string[];
+  /** Flags that this flag depends on */
+  dependsOn?: string[];
+  /** Flags that are implied when this flag is set */
+  implies?: string[] | [string, unknown][];
+  // Note: transform is defined in child interfaces with specific types
+}
+
+/**
+ * Boolean flag schema
+ */
+export interface BooleanFlagSchema extends BaseFlagSchema<'boolean'> {
+  type: 'boolean';
+  default?: boolean;
+  /** Transform function to apply to the value */
+  transform?: (value: boolean) => boolean | Promise<boolean>;
+}
+
+/**
+ * String flag schema
+ */
+export interface StringFlagSchema extends BaseFlagSchema<'string'> {
+  type: 'string';
+  default?: string;
+  /** Allowed values (enum) */
+  choices?: readonly string[];
+  /** Regex pattern for validation */
+  pattern?: RegExp;
+  /** Minimum string length */
+  minLength?: number;
+  /** Maximum string length */
+  maxLength?: number;
+  /** Custom validation function */
+  validate?: (value: string) => true | string | Promise<true | string>;
+  /** Transform function to apply to the value */
+  transform?: (value: string) => string | Promise<string>;
+}
+
+/**
+ * Number flag schema
+ */
+export interface NumberFlagSchema extends BaseFlagSchema<'number'> {
+  type: 'number';
+  default?: number;
+  /** Minimum value */
+  min?: number;
+  /** Maximum value */
+  max?: number;
+  /** Custom validation function */
+  validate?: (value: number) => true | string | Promise<true | string>;
+  /** Transform function to apply to the value */
+  transform?: (value: number) => number | Promise<number>;
+}
+
+/**
+ * Array flag schema
+ */
+export interface ArrayFlagSchema extends BaseFlagSchema<'array'> {
+  type: 'array';
+  default?: unknown[];
+  /** Type of array items */
+  items?: 'string' | 'number' | 'boolean';
+  /** Minimum array length */
+  minLength?: number;
+  /** Maximum array length */
+  maxLength?: number;
+  /** Transform function to apply to the value */
+  transform?: (value: unknown[]) => unknown[] | Promise<unknown[]>;
+}
+
+/**
+ * Union of all flag schema types
+ */
+export type FlagSchema =
+  | BooleanFlagSchema
+  | StringFlagSchema
+  | NumberFlagSchema
+  | ArrayFlagSchema;
+
+/**
+ * Flag schema definition object (for defineFlags)
+ */
+export type FlagSchemaDefinition = Record<string, Omit<FlagSchema, 'name'>>;
+
+/**
+ * Validation error
+ */
+export class FlagValidationError extends Error {
+  constructor(
+    public readonly flag: string,
+    message: string,
+    public readonly value?: unknown,
+    public readonly schema?: FlagSchemaDefinition,
+    public readonly commandName?: string
+  ) {
+    super(message);
+    this.name = 'FlagValidationError';
+  }
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult<T = Record<string, unknown>> {
+  success: boolean;
+  data?: T;
+  errors?: Array<{
+    flag: string;
+    message: string;
+    value?: unknown;
+  }>;
+}
+
+/**
+ * Safe validation result (doesn't throw)
+ */
+export interface SafeValidationResult<T = Record<string, unknown>> {
+  success: boolean;
+  data?: T;
+  errors: Array<{
+    flag: string;
+    message: string;
+    value?: unknown;
+  }>;
+}
+