@memnexus-ai/cli 0.1.0

package/src/lib/errors.ts

@@ -0,0 +1,143 @@
+import chalk from 'chalk';
+
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public exitCode: number = 1,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'CLIError';
+  }
+}
+
+export function handleError(error: unknown): never {
+  if (error instanceof CLIError) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    if (error.details && process.env.DEBUG) {
+      console.error(chalk.gray(JSON.stringify(error.details, null, 2)));
+    }
+    process.exit(error.exitCode);
+  }
+
+  if (isAxiosError(error)) {
+    handleApiError(error);
+  }
+
+  // Unknown error
+  console.error(chalk.red('An unexpected error occurred'));
+  if (error instanceof Error) {
+    console.error(chalk.gray(error.message));
+    if (process.env.DEBUG && error.stack) {
+      console.error(chalk.gray(error.stack));
+    }
+  }
+  process.exit(1);
+}
+
+interface AxiosError {
+  isAxiosError: boolean;
+  response?: {
+    status: number;
+    statusText: string;
+    data: { error?: string; message?: string };
+  };
+}
+
+function isAxiosError(error: unknown): error is AxiosError {
+  return (error as AxiosError).isAxiosError === true;
+}
+
+function handleApiError(error: AxiosError): never {
+  if (!error.response) {
+    console.error(chalk.red('❌ Network Error: Unable to connect to API'));
+    console.log(chalk.yellow('\n💡 Troubleshooting steps:'));
+    console.log(chalk.yellow('   1. Check your internet connection'));
+    console.log(chalk.yellow('   2. Verify API URL: mx config get apiUrl'));
+    console.log(chalk.yellow('   3. Test API connectivity: curl <api-url>/health'));
+    console.log(chalk.yellow('   4. Update API URL if needed: mx config set apiUrl <url>'));
+    process.exit(4);
+  }
+
+  const status = error.response.status;
+  const data = error.response.data;
+
+  // Each case calls process.exit() which never returns, so break statements are unnecessary
+  // eslint-disable-next-line no-fallthrough
+  switch (status) {
+    case 401:
+      console.error(chalk.red('❌ Authentication Error: Invalid or missing API key'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Check auth status: mx auth status'));
+      console.log(
+        chalk.yellow('   2. Login with your API key: mx auth login --api-key <your-key>')
+      );
+      console.log(chalk.yellow('   3. Or use interactive mode: mx auth login --interactive'));
+      process.exit(3);
+    // eslint-disable-next-line no-fallthrough
+    case 403:
+      console.error(chalk.red('❌ Authorization Error: Insufficient permissions'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Verify your API key has the required permissions'));
+      console.log(chalk.yellow('   2. Contact your administrator if you need additional access'));
+      console.log(chalk.yellow('   3. Check your current auth status: mx auth status'));
+      process.exit(3);
+    // eslint-disable-next-line no-fallthrough
+    case 404:
+      console.error(chalk.red('❌ Not Found: Resource does not exist'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Verify the resource ID is correct'));
+      console.log(chalk.yellow('   2. List available resources to find the correct ID'));
+      console.log(chalk.yellow('   3. Check if the resource was deleted'));
+      process.exit(1);
+    // eslint-disable-next-line no-fallthrough
+    case 422:
+      console.error(chalk.red('❌ Validation Error: Invalid input'));
+      if (data.message) {
+        console.error(chalk.yellow(`\n${data.message}`));
+      }
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Check the command syntax: mx <command> --help'));
+      console.log(chalk.yellow('   2. Verify all required fields are provided'));
+      console.log(chalk.yellow('   3. Use --interactive mode for guided input'));
+      process.exit(2);
+    // eslint-disable-next-line no-fallthrough
+    case 429:
+      console.error(chalk.red('❌ Rate Limit Exceeded: Too many requests'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Wait a few moments before retrying'));
+      console.log(chalk.yellow('   2. Reduce the frequency of your requests'));
+      console.log(chalk.yellow('   3. Contact support if you need a higher rate limit'));
+      process.exit(5);
+    // eslint-disable-next-line no-fallthrough
+    case 500:
+      console.error(chalk.red('❌ Server Error: Internal server error'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. Try again in a few moments'));
+      console.log(chalk.yellow('   2. Check API status: mx system health'));
+      console.log(chalk.yellow('   3. Contact support if the issue persists'));
+      if (data.error || data.message) {
+        console.error(chalk.gray(`\nDetails: ${data.error || data.message}`));
+      }
+      process.exit(5);
+    // eslint-disable-next-line no-fallthrough
+    case 503:
+      console.error(chalk.red('❌ Service Unavailable: API is temporarily unavailable'));
+      console.log(chalk.yellow('\n💡 To fix this:'));
+      console.log(chalk.yellow('   1. The service may be undergoing maintenance'));
+      console.log(chalk.yellow('   2. Try again in a few minutes'));
+      console.log(chalk.yellow('   3. Check API status: mx system health'));
+      process.exit(5);
+    // eslint-disable-next-line no-fallthrough
+    default:
+      console.error(chalk.red(`❌ API Error: ${status} ${error.response.statusText}`));
+      if (data.error || data.message) {
+        console.error(chalk.yellow(`\n${data.error || data.message}`));
+      }
+      console.log(chalk.yellow('\n💡 For help:'));
+      console.log(chalk.yellow('   1. Run with DEBUG=1 for more details'));
+      console.log(chalk.yellow('   2. Check command syntax: mx <command> --help'));
+      console.log(chalk.yellow('   3. Contact support if the issue persists'));
+      process.exit(5);
+  }
+}

package/src/lib/formatters.ts

@@ -0,0 +1,123 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import yaml from 'js-yaml';
+import { config } from './config';
+import { OutputFormat } from '../types';
+
+export function formatOutput(
+  data: unknown,
+  format?: OutputFormat,
+  tableOptions?: TableOptions
+): string {
+  const outputFormat = format || config.getFormat();
+
+  switch (outputFormat) {
+    case 'json':
+      return formatJson(data);
+    case 'yaml':
+      return formatYaml(data);
+    case 'table':
+      return formatTable(data, tableOptions);
+    default:
+      return formatJson(data);
+  }
+}
+
+export function formatJson(data: unknown): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export function formatYaml(data: unknown): string {
+  return yaml.dump(data, { indent: 2, lineWidth: 120 });
+}
+
+interface TableOptions {
+  columns?: string[];
+  maxColumnWidth?: number;
+}
+
+export function formatTable(data: unknown, options?: TableOptions): string {
+  if (!data) {
+    return 'No data';
+  }
+
+  // Single object
+  if (typeof data === 'object' && !Array.isArray(data)) {
+    return formatObjectAsTable(data as Record<string, unknown>);
+  }
+
+  // Array of objects
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      return 'No results';
+    }
+    return formatArrayAsTable(data, options);
+  }
+
+  // Primitive value
+  return String(data);
+}
+
+function formatObjectAsTable(obj: Record<string, unknown>): string {
+  const table = new Table({
+    head: [chalk.cyan('Property'), chalk.cyan('Value')],
+    colWidths: [30, 70],
+    wordWrap: true,
+  });
+
+  Object.entries(obj).forEach(([key, value]) => {
+    table.push([key, formatValue(value)]);
+  });
+
+  return table.toString();
+}
+
+function formatArrayAsTable(data: unknown[], options?: TableOptions): string {
+  const firstItem = data[0];
+  if (typeof firstItem !== 'object' || firstItem === null) {
+    // Array of primitives
+    const table = new Table({ head: [chalk.cyan('Value')] });
+    data.forEach((item) => table.push([formatValue(item)]));
+    return table.toString();
+  }
+
+  // Array of objects - use keys from first object
+  const keys = options?.columns || Object.keys(firstItem as Record<string, unknown>);
+  const table = new Table({
+    head: keys.map((k) => chalk.cyan(k)),
+    wordWrap: true,
+    colWidths: keys.map(() => options?.maxColumnWidth || 30),
+  });
+
+  data.forEach((item) => {
+    const row = keys.map((key) => {
+      const value = (item as Record<string, unknown>)[key];
+      return formatValue(value);
+    });
+    table.push(row);
+  });
+
+  return table.toString();
+}
+
+function formatValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return chalk.gray('null');
+  }
+  if (typeof value === 'boolean') {
+    return value ? chalk.green('true') : chalk.red('false');
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+export function printOutput(
+  data: unknown,
+  format?: OutputFormat,
+  tableOptions?: TableOptions
+): void {
+  const output = formatOutput(data, format, tableOptions);
+  console.log(output);
+}

package/src/lib/spinner.ts

@@ -0,0 +1,113 @@
+import ora, { Ora } from 'ora';
+import { OutputFormat } from '../types';
+
+/**
+ * Conditional spinner that only shows when output format is not JSON
+ * This prevents spinners from interfering with JSON output that may be piped to other tools
+ */
+export class ConditionalSpinner {
+  private spinner: Ora | null = null;
+  private enabled: boolean;
+
+  constructor(text: string, format?: OutputFormat | string) {
+    // Disable spinner for JSON output format
+    this.enabled = format !== 'json';
+
+    if (this.enabled) {
+      this.spinner = ora(text);
+    }
+  }
+
+  /**
+   * Start the spinner
+   */
+  start(): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.start();
+    }
+    return this;
+  }
+
+  /**
+   * Stop the spinner and show success message
+   */
+  succeed(text?: string): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.succeed(text);
+    }
+    return this;
+  }
+
+  /**
+   * Stop the spinner and show failure message
+   */
+  fail(text?: string): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.fail(text);
+    }
+    return this;
+  }
+
+  /**
+   * Stop the spinner and show warning message
+   */
+  warn(text?: string): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.warn(text);
+    }
+    return this;
+  }
+
+  /**
+   * Stop the spinner and show info message
+   */
+  info(text?: string): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.info(text);
+    }
+    return this;
+  }
+
+  /**
+   * Stop the spinner
+   */
+  stop(): this {
+    if (this.enabled && this.spinner) {
+      this.spinner.stop();
+    }
+    return this;
+  }
+
+  /**
+   * Update spinner text
+   */
+  set text(value: string) {
+    if (this.enabled && this.spinner) {
+      this.spinner.text = value;
+    }
+  }
+
+  /**
+   * Get spinner text
+   */
+  get text(): string {
+    return this.enabled && this.spinner ? this.spinner.text : '';
+  }
+
+  /**
+   * Check if spinner is currently spinning
+   */
+  get isSpinning(): boolean {
+    return this.enabled && this.spinner ? this.spinner.isSpinning : false;
+  }
+}
+
+/**
+ * Create a conditional spinner that respects output format
+ * @param text - Initial spinner text
+ * @param format - Output format (spinner disabled for 'json')
+ * @returns ConditionalSpinner instance
+ */
+export function createSpinner(text: string, format?: OutputFormat | string): ConditionalSpinner {
+  return new ConditionalSpinner(text, format);
+}

package/src/lib/validators.ts

@@ -0,0 +1,302 @@
+import chalk from 'chalk';
+
+/**
+ * Validation result type
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Validate URL format
+ * @param url - URL string to validate
+ * @returns Validation result with helpful error message
+ */
+export function validateUrl(url: string): ValidationResult {
+  if (!url || url.trim().length === 0) {
+    return {
+      valid: false,
+      error: 'URL cannot be empty',
+    };
+  }
+
+  try {
+    const urlObj = new URL(url);
+
+    // Check for valid protocol
+    if (!['http:', 'https:'].includes(urlObj.protocol)) {
+      return {
+        valid: false,
+        error: `Invalid protocol "${urlObj.protocol}". Must be http: or https:\nExample: https://api.memnexus.ai`,
+      };
+    }
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Invalid URL format\nExample: https://api.memnexus.ai\nProvided: ${url}`,
+    };
+  }
+}
+
+/**
+ * Validate number within range
+ * @param value - Value to validate
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with helpful error message
+ */
+export function validateNumber(
+  value: any,
+  min?: number,
+  max?: number,
+  fieldName: string = 'Value'
+): ValidationResult {
+  const num = typeof value === 'string' ? parseFloat(value) : value;
+
+  if (isNaN(num)) {
+    return {
+      valid: false,
+      error: `${fieldName} must be a valid number\nProvided: ${value}`,
+    };
+  }
+
+  if (min !== undefined && num < min) {
+    return {
+      valid: false,
+      error: `${fieldName} must be at least ${min}\nProvided: ${num}`,
+    };
+  }
+
+  if (max !== undefined && num > max) {
+    return {
+      valid: false,
+      error: `${fieldName} must be at most ${max}\nProvided: ${num}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate integer within range
+ * @param value - Value to validate
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with helpful error message
+ */
+export function validateInteger(
+  value: any,
+  min?: number,
+  max?: number,
+  fieldName: string = 'Value'
+): ValidationResult {
+  const num = typeof value === 'string' ? parseInt(value, 10) : value;
+
+  if (isNaN(num) || !Number.isInteger(num)) {
+    return {
+      valid: false,
+      error: `${fieldName} must be a valid integer\nProvided: ${value}`,
+    };
+  }
+
+  if (min !== undefined && num < min) {
+    return {
+      valid: false,
+      error: `${fieldName} must be at least ${min}\nProvided: ${num}`,
+    };
+  }
+
+  if (max !== undefined && num > max) {
+    return {
+      valid: false,
+      error: `${fieldName} must be at most ${max}\nProvided: ${num}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate confidence score (0-1)
+ * @param value - Confidence score to validate
+ * @returns Validation result with helpful error message
+ */
+export function validateConfidence(value: any): ValidationResult {
+  const result = validateNumber(value, 0, 1, 'Confidence score');
+
+  if (!result.valid) {
+    return {
+      valid: false,
+      error: `${result.error}\nConfidence must be between 0 and 1 (e.g., 0.85 for 85% confidence)`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate JSON string
+ * @param jsonString - JSON string to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with helpful error message and parsed object
+ */
+export function validateJson(
+  jsonString: string,
+  fieldName: string = 'JSON'
+): ValidationResult & { parsed?: any } {
+  if (!jsonString || jsonString.trim().length === 0) {
+    return {
+      valid: false,
+      error: `${fieldName} cannot be empty`,
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(jsonString);
+    return { valid: true, parsed };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    return {
+      valid: false,
+      error: `Invalid ${fieldName} format: ${errorMessage}\nExample: {"key": "value"}`,
+    };
+  }
+}
+
+/**
+ * Validate output format
+ * @param format - Output format to validate
+ * @returns Validation result with helpful error message
+ */
+export function validateOutputFormat(format: string): ValidationResult {
+  const validFormats = ['json', 'table', 'yaml'];
+
+  if (!format || format.trim().length === 0) {
+    return {
+      valid: false,
+      error: 'Output format cannot be empty',
+    };
+  }
+
+  const normalizedFormat = format.toLowerCase();
+
+  if (!validFormats.includes(normalizedFormat)) {
+    return {
+      valid: false,
+      error: `Invalid output format: ${format}\nValid formats: ${validFormats.join(', ')}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate page number
+ * @param page - Page number to validate
+ * @returns Validation result with helpful error message
+ */
+export function validatePage(page: any): ValidationResult {
+  return validateInteger(page, 0, undefined, 'Page number');
+}
+
+/**
+ * Validate limit/page size
+ * @param limit - Limit to validate
+ * @returns Validation result with helpful error message
+ */
+export function validateLimit(limit: any): ValidationResult {
+  return validateInteger(limit, 1, 1000, 'Limit');
+}
+
+/**
+ * Validate required string field
+ * @param value - Value to validate
+ * @param fieldName - Name of the field for error messages
+ * @param minLength - Minimum length (default: 1)
+ * @returns Validation result with helpful error message
+ */
+export function validateRequiredString(
+  value: any,
+  fieldName: string,
+  minLength: number = 1
+): ValidationResult {
+  if (value === undefined || value === null) {
+    return {
+      valid: false,
+      error: `${fieldName} is required`,
+    };
+  }
+
+  const str = String(value).trim();
+
+  if (str.length === 0) {
+    return {
+      valid: false,
+      error: `${fieldName} cannot be empty`,
+    };
+  }
+
+  if (str.length < minLength) {
+    return {
+      valid: false,
+      error: `${fieldName} must be at least ${minLength} characters\nProvided: ${str.length} characters`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate enum value
+ * @param value - Value to validate
+ * @param allowedValues - Array of allowed values
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with helpful error message
+ */
+export function validateEnum(
+  value: any,
+  allowedValues: string[],
+  fieldName: string
+): ValidationResult {
+  if (!value || value.trim().length === 0) {
+    return {
+      valid: false,
+      error: `${fieldName} is required\nAllowed values: ${allowedValues.join(', ')}`,
+    };
+  }
+
+  if (!allowedValues.includes(value)) {
+    return {
+      valid: false,
+      error: `Invalid ${fieldName}: ${value}\nAllowed values: ${allowedValues.join(', ')}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Print validation error with formatting
+ * @param error - Error message to print
+ */
+export function printValidationError(error: string): void {
+  console.log(chalk.red('❌ Validation Error:'));
+  console.log(chalk.yellow(error));
+}
+
+/**
+ * Validate and throw if invalid
+ * @param result - Validation result
+ * @throws Error if validation fails
+ */
+export function assertValid(result: ValidationResult): void {
+  if (!result.valid && result.error) {
+    printValidationError(result.error);
+    process.exit(1);
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,17 @@
+// Re-export types from SDK
+export type * from '@memnexus-ai/mx-typescript-sdk';
+
+// CLI-specific types
+export interface CLIConfig {
+  apiUrl: string;
+  apiKey?: string;
+  defaultFormat: 'json' | 'table' | 'yaml';
+  defaultPageSize: number;
+}
+
+export interface CommandOptions {
+  format?: 'json' | 'table' | 'yaml';
+  verbose?: boolean;
+}
+
+export type OutputFormat = 'json' | 'table' | 'yaml';

package/tests/__mocks__/chalk.ts

@@ -0,0 +1,16 @@
+// Mock chalk for Jest tests
+const createChalk = (color: string) => (text: string) => text;
+
+const chalk = {
+  red: createChalk('red'),
+  green: createChalk('green'),
+  yellow: createChalk('yellow'),
+  blue: createChalk('blue'),
+  cyan: createChalk('cyan'),
+  gray: createChalk('gray'),
+  grey: createChalk('grey'),
+  white: createChalk('white'),
+  black: createChalk('black'),
+};
+
+export default chalk;