@memnexus-ai/cli 0.1.0

package/.github/ISSUE_TEMPLATE/phase-1-foundation.md

@@ -0,0 +1,1078 @@
+---
+name: Phase 1 - Foundation (Week 1)
+about: Set up project infrastructure and core utilities for mx-cli v1.0
+title: 'Phase 1: Foundation - Project Infrastructure & Core Utilities'
+labels: 'enhancement, infrastructure, phase-1'
+assignees: ''
+---
+
+# Phase 1: Foundation (Week 1)
+
+## Goal
+Set up project infrastructure and core utilities to enable rapid CLI command development in subsequent phases.
+
+## Overview
+This phase establishes the foundational architecture for the MemNexus CLI. By the end of this phase, we'll have a working TypeScript project structure with authentication, configuration management, and output formatting ready for command implementations.
+
+## Success Criteria
+- ✅ TypeScript project compiles without errors
+- ✅ Can install `@memnexus-ai/contracts` and use types
+- ✅ Configuration can be saved/loaded from disk
+- ✅ API client connects to mx-core-api successfully
+- ✅ Output formatters work for JSON, table, and YAML
+- ✅ All utility tests pass with >80% coverage
+- ✅ ESLint and Prettier configured and passing
+
+---
+
+## Tasks
+
+### 1. Initialize TypeScript Project
+**Estimated Time**: 1-2 hours
+
+**Description**: Set up the basic Node.js + TypeScript project structure
+
+**Steps**:
+```bash
+cd /workspaces/memnexus/mx-cli
+
+# Initialize package.json
+npm init -y
+
+# Install TypeScript and core dependencies
+npm install --save-dev typescript @types/node ts-node
+
+# Install production dependencies
+npm install commander chalk ora cli-table3 inquirer configstore dotenv
+
+# Install type definitions
+npm install --save-dev @types/inquirer
+```
+
+**Create `package.json`**:
+```json
+{
+  "name": "@memnexus-ai/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for MemNexus Core API",
+  "main": "dist/index.js",
+  "bin": {
+    "mx": "./bin/mx.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "format": "prettier --write 'src/**/*.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["memnexus", "cli", "api", "memory", "ai"],
+  "author": "MemNexus Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memnexus-ai/memnexus.git",
+    "directory": "mx-cli"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "@memnexus-ai:registry": "https://npm.pkg.github.com"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+```
+
+**Create `tsconfig.json`**:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+**Acceptance Criteria**:
+- [x] `npm run build` compiles successfully
+- [x] TypeScript strict mode enabled
+- [x] Source maps generated for debugging
+
+---
+
+### 2. Add @memnexus-ai/contracts Dependency
+**Estimated Time**: 30 minutes
+
+**Description**: Install and configure the contracts package for API client access
+
+**Steps**:
+```bash
+# Configure npm to use GitHub Packages
+echo "@memnexus-ai:registry=https://npm.pkg.github.com" >> .npmrc
+
+# Install contracts package (requires GitHub authentication)
+npm install @memnexus-ai/contracts@^1.0.4
+```
+
+**Create `.npmrc`**:
+```
+@memnexus-ai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+**Test import**:
+```typescript
+// src/lib/api-client.ts
+import { CoreApiClient, createClient } from '@memnexus-ai/contracts';
+
+// Verify types are available
+const client: CoreApiClient = createClient({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'test'
+});
+```
+
+**Acceptance Criteria**:
+- [x] Package installs without errors
+- [x] TypeScript recognizes all imports
+- [x] Types from contracts package are available
+
+---
+
+### 3. Configure TypeScript, ESLint, Prettier
+**Estimated Time**: 1-2 hours
+
+**Description**: Set up code quality tools for consistent style and error prevention
+
+**Install Dev Dependencies**:
+```bash
+npm install --save-dev \
+  eslint \
+  @typescript-eslint/parser \
+  @typescript-eslint/eslint-plugin \
+  prettier \
+  eslint-config-prettier \
+  eslint-plugin-prettier
+```
+
+**Create `.eslintrc.js`**:
+```javascript
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier'
+  ],
+  plugins: ['@typescript-eslint', 'prettier'],
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    project: './tsconfig.json'
+  },
+  rules: {
+    'prettier/prettier': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn'
+  },
+  env: {
+    node: true,
+    es2022: true
+  }
+};
+```
+
+**Create `.prettierrc`**:
+```json
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}
+```
+
+**Create `.prettierignore`**:
+```
+node_modules
+dist
+coverage
+*.md
+```
+
+**Acceptance Criteria**:
+- [x] `npm run lint` passes
+- [x] `npm run format` formats all files
+- [x] ESLint catches type errors and style issues
+
+---
+
+### 4. Set Up Project Structure
+**Estimated Time**: 30 minutes
+
+**Description**: Create the directory structure for organized code
+
+**Create directories**:
+```bash
+mkdir -p src/{commands,lib,types}
+mkdir -p tests/{commands,lib}
+mkdir -p bin
+```
+
+**Create initial files**:
+
+`src/index.ts`:
+```typescript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import packageJson from '../package.json';
+
+const program = new Command();
+
+program
+  .name('mx')
+  .description('MemNexus CLI - Command-line interface for MemNexus Core API')
+  .version(packageJson.version);
+
+// Commands will be registered here
+
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}
+```
+
+`bin/mx.js`:
+```javascript
+#!/usr/bin/env node
+require('../dist/index.js');
+```
+
+`src/types/index.ts`:
+```typescript
+// Re-export types from contracts
+export type * from '@memnexus-ai/contracts';
+
+// 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;
+}
+```
+
+**Acceptance Criteria**:
+- [x] All directories created
+- [x] CLI entry point exists
+- [x] Can run `npm run dev` without errors
+
+---
+
+### 5. Implement Configuration Management
+**Estimated Time**: 2-3 hours
+
+**Description**: Create config storage using configstore for persistent settings
+
+**Create `src/lib/config.ts`**:
+```typescript
+import Configstore from 'configstore';
+import { CLIConfig } from '../types';
+import packageJson from '../../package.json';
+
+const DEFAULT_CONFIG: CLIConfig = {
+  apiUrl: 'https://api.memnexus.io',
+  defaultFormat: 'table',
+  defaultPageSize: 20,
+};
+
+class ConfigManager {
+  private store: Configstore;
+
+  constructor() {
+    this.store = new Configstore(packageJson.name, DEFAULT_CONFIG);
+  }
+
+  get(key?: keyof CLIConfig): CLIConfig | string | number | undefined {
+    if (key) {
+      return this.store.get(key);
+    }
+    return this.store.all as CLIConfig;
+  }
+
+  set(key: keyof CLIConfig, value: string | number): void {
+    this.store.set(key, value);
+  }
+
+  delete(key: keyof CLIConfig): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  reset(): void {
+    this.store.all = DEFAULT_CONFIG;
+  }
+
+  getApiUrl(): string {
+    return process.env.MX_API_URL || this.store.get('apiUrl') || DEFAULT_CONFIG.apiUrl;
+  }
+
+  getApiKey(): string | undefined {
+    return process.env.MX_API_KEY || this.store.get('apiKey');
+  }
+
+  getFormat(): 'json' | 'table' | 'yaml' {
+    return (
+      (process.env.MX_OUTPUT_FORMAT as 'json' | 'table' | 'yaml') ||
+      this.store.get('defaultFormat') ||
+      DEFAULT_CONFIG.defaultFormat
+    );
+  }
+
+  setApiKey(apiKey: string): void {
+    // TODO: Encrypt API key before storing
+    this.store.set('apiKey', apiKey);
+  }
+
+  hasApiKey(): boolean {
+    return !!(process.env.MX_API_KEY || this.store.get('apiKey'));
+  }
+}
+
+export const config = new ConfigManager();
+export const getConfig = (): CLIConfig => config.get() as CLIConfig;
+```
+
+**Create tests `tests/lib/config.test.ts`**:
+```typescript
+import { config } from '../../src/lib/config';
+
+describe('ConfigManager', () => {
+  beforeEach(() => {
+    config.reset();
+  });
+
+  it('should return default config', () => {
+    const cfg = config.get();
+    expect(cfg).toHaveProperty('apiUrl');
+    expect(cfg).toHaveProperty('defaultFormat');
+  });
+
+  it('should set and get values', () => {
+    config.set('apiUrl', 'http://localhost:3000');
+    expect(config.get('apiUrl')).toBe('http://localhost:3000');
+  });
+
+  it('should respect environment variables', () => {
+    process.env.MX_API_URL = 'http://env-url:3000';
+    expect(config.getApiUrl()).toBe('http://env-url:3000');
+    delete process.env.MX_API_URL;
+  });
+
+  it('should reset to defaults', () => {
+    config.set('apiUrl', 'http://custom:3000');
+    config.reset();
+    expect(config.get('apiUrl')).toBe('https://api.memnexus.io');
+  });
+});
+```
+
+**Acceptance Criteria**:
+- [x] Config persists between CLI runs
+- [x] Environment variables override config
+- [x] Can reset to defaults
+- [x] Tests pass
+
+---
+
+### 6. Create API Client Wrapper
+**Estimated Time**: 1-2 hours
+
+**Description**: Wrapper around @memnexus-ai/contracts with config integration
+
+**Create `src/lib/api-client.ts`**:
+```typescript
+import { CoreApiClient, createClient } from '@memnexus-ai/contracts';
+import { config } from './config';
+import chalk from 'chalk';
+
+let cachedClient: CoreApiClient | null = null;
+
+export function getApiClient(): CoreApiClient {
+  if (cachedClient) {
+    return cachedClient;
+  }
+
+  const apiKey = config.getApiKey();
+  if (!apiKey) {
+    console.error(chalk.red('Error: No API key configured.'));
+    console.log(chalk.yellow('Run: mx auth login --api-key <your-key>'));
+    process.exit(1);
+  }
+
+  const apiUrl = config.getApiUrl();
+
+  cachedClient = createClient({
+    baseURL: apiUrl,
+    apiKey: apiKey,
+    timeout: 30000,
+  });
+
+  return cachedClient;
+}
+
+export function resetApiClient(): void {
+  cachedClient = null;
+}
+
+export { CoreApiClient };
+```
+
+**Create tests `tests/lib/api-client.test.ts`**:
+```typescript
+import { getApiClient, resetApiClient } from '../../src/lib/api-client';
+import { config } from '../../src/lib/config';
+
+describe('API Client', () => {
+  beforeEach(() => {
+    resetApiClient();
+    config.reset();
+  });
+
+  it('should create client with config', () => {
+    config.setApiKey('test-key');
+    const client = getApiClient();
+    expect(client).toBeDefined();
+  });
+
+  it('should exit if no API key', () => {
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation();
+    getApiClient();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+
+  it('should cache client instance', () => {
+    config.setApiKey('test-key');
+    const client1 = getApiClient();
+    const client2 = getApiClient();
+    expect(client1).toBe(client2);
+  });
+});
+```
+
+**Acceptance Criteria**:
+- [x] Client initializes with config values
+- [x] Error shown if API key missing
+- [x] Client is cached (singleton pattern)
+- [x] Tests pass
+
+---
+
+### 7. Create Authentication Helpers
+**Estimated Time**: 1-2 hours
+
+**Description**: Helper functions for API key storage and validation
+
+**Create `src/lib/auth.ts`**:
+```typescript
+import { config } from './config';
+import chalk from 'chalk';
+
+export function storeApiKey(apiKey: string): void {
+  if (!apiKey || apiKey.trim().length === 0) {
+    throw new Error('API key cannot be empty');
+  }
+
+  // TODO: Add encryption before storing
+  config.setApiKey(apiKey);
+  console.log(chalk.green('✓ API key saved successfully'));
+}
+
+export function removeApiKey(): void {
+  config.delete('apiKey');
+  console.log(chalk.green('✓ API key removed'));
+}
+
+export function hasApiKey(): boolean {
+  return config.hasApiKey();
+}
+
+export function getApiKeyStatus(): { configured: boolean; source: 'env' | 'config' | 'none' } {
+  if (process.env.MX_API_KEY) {
+    return { configured: true, source: 'env' };
+  }
+  if (config.get('apiKey')) {
+    return { configured: true, source: 'config' };
+  }
+  return { configured: false, source: 'none' };
+}
+
+// TODO: Implement encryption/decryption
+export function encryptApiKey(apiKey: string): string {
+  // Placeholder - implement proper encryption
+  return apiKey;
+}
+
+export function decryptApiKey(encryptedKey: string): string {
+  // Placeholder - implement proper decryption
+  return encryptedKey;
+}
+```
+
+**Create tests `tests/lib/auth.test.ts`**:
+```typescript
+import { storeApiKey, removeApiKey, hasApiKey, getApiKeyStatus } from '../../src/lib/auth';
+import { config } from '../../src/lib/config';
+
+describe('Authentication Helpers', () => {
+  beforeEach(() => {
+    config.reset();
+    delete process.env.MX_API_KEY;
+  });
+
+  it('should store API key', () => {
+    storeApiKey('test-key-123');
+    expect(hasApiKey()).toBe(true);
+  });
+
+  it('should reject empty API key', () => {
+    expect(() => storeApiKey('')).toThrow();
+  });
+
+  it('should remove API key', () => {
+    storeApiKey('test-key');
+    removeApiKey();
+    expect(hasApiKey()).toBe(false);
+  });
+
+  it('should detect API key source', () => {
+    expect(getApiKeyStatus().source).toBe('none');
+
+    storeApiKey('config-key');
+    expect(getApiKeyStatus().source).toBe('config');
+
+    process.env.MX_API_KEY = 'env-key';
+    expect(getApiKeyStatus().source).toBe('env');
+  });
+});
+```
+
+**Acceptance Criteria**:
+- [x] Can store/remove API keys
+- [x] Status detection works correctly
+- [x] Tests pass
+- [x] TODO comments for encryption
+
+---
+
+### 8. Set Up Error Handling Framework
+**Estimated Time**: 2-3 hours
+
+**Description**: Centralized error handling with user-friendly messages
+
+**Create `src/lib/errors.ts`**:
+```typescript
+import chalk from 'chalk';
+import { AxiosError } from 'axios';
+
+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);
+}
+
+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('Check your internet connection and API URL'));
+    process.exit(4);
+  }
+
+  const status = error.response.status;
+  const data = error.response.data as { error?: string; message?: string };
+
+  switch (status) {
+    case 401:
+      console.error(chalk.red('Authentication Error: Invalid or missing API key'));
+      console.log(chalk.yellow('Run: mx auth login --api-key <your-key>'));
+      process.exit(3);
+
+    case 403:
+      console.error(chalk.red('Authorization Error: Insufficient permissions'));
+      process.exit(3);
+
+    case 404:
+      console.error(chalk.red('Not Found: Resource does not exist'));
+      process.exit(1);
+
+    case 422:
+      console.error(chalk.red('Validation Error: Invalid input'));
+      if (data.message) {
+        console.error(chalk.yellow(data.message));
+      }
+      process.exit(2);
+
+    case 429:
+      console.error(chalk.red('Rate Limit Exceeded: Too many requests'));
+      console.log(chalk.yellow('Please wait a moment and try again'));
+      process.exit(5);
+
+    default:
+      console.error(chalk.red(`API Error: ${status} ${error.response.statusText}`));
+      if (data.error || data.message) {
+        console.error(chalk.yellow(data.error || data.message));
+      }
+      process.exit(5);
+  }
+}
+```
+
+**Create tests `tests/lib/errors.test.ts`**:
+```typescript
+import { CLIError, handleError } from '../../src/lib/errors';
+import { AxiosError } from 'axios';
+
+describe('Error Handling', () => {
+  let exitSpy: jest.SpyInstance;
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation();
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should handle CLIError', () => {
+    const error = new CLIError('Test error', 2);
+    handleError(error);
+    expect(exitSpy).toHaveBeenCalledWith(2);
+  });
+
+  it('should handle 401 API errors', () => {
+    const error: AxiosError = {
+      isAxiosError: true,
+      response: { status: 401, statusText: 'Unauthorized', data: {} },
+    } as AxiosError;
+
+    handleError(error);
+    expect(exitSpy).toHaveBeenCalledWith(3);
+  });
+
+  it('should handle network errors', () => {
+    const error: AxiosError = {
+      isAxiosError: true,
+      response: undefined,
+    } as AxiosError;
+
+    handleError(error);
+    expect(exitSpy).toHaveBeenCalledWith(4);
+  });
+});
+```
+
+**Acceptance Criteria**:
+- [x] All error types handled appropriately
+- [x] User-friendly error messages
+- [x] Correct exit codes used
+- [x] Tests pass
+
+---
+
+### 9. Create Output Formatters
+**Estimated Time**: 3-4 hours
+
+**Description**: Format command output as JSON, table, or YAML
+
+**Install dependencies**:
+```bash
+npm install js-yaml cli-table3
+npm install --save-dev @types/js-yaml
+```
+
+**Create `src/lib/formatters.ts`**:
+```typescript
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import yaml from 'js-yaml';
+import { config } from './config';
+
+export type OutputFormat = 'json' | 'table' | 'yaml';
+
+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);
+}
+```
+
+**Create tests `tests/lib/formatters.test.ts`**:
+```typescript
+import { formatJson, formatYaml, formatTable, formatOutput } from '../../src/lib/formatters';
+
+describe('Output Formatters', () => {
+  const testData = { id: '123', name: 'Test', active: true };
+
+  it('should format as JSON', () => {
+    const output = formatJson(testData);
+    expect(output).toContain('"id"');
+    expect(output).toContain('"123"');
+  });
+
+  it('should format as YAML', () => {
+    const output = formatYaml(testData);
+    expect(output).toContain('id: ');
+    expect(output).toContain('name: Test');
+  });
+
+  it('should format object as table', () => {
+    const output = formatTable(testData);
+    expect(output).toContain('Property');
+    expect(output).toContain('Value');
+  });
+
+  it('should format array as table', () => {
+    const output = formatTable([testData, testData]);
+    expect(output).toContain('id');
+    expect(output).toContain('name');
+  });
+
+  it('should use default format from config', () => {
+    const output = formatOutput(testData);
+    expect(output).toBeDefined();
+  });
+});
+```
+
+**Acceptance Criteria**:
+- [x] JSON formatting works
+- [x] YAML formatting works
+- [x] Table formatting works for objects and arrays
+- [x] Format selection respects config/flags
+- [x] Tests pass
+
+---
+
+### 10. Write Basic Tests for Utilities
+**Estimated Time**: 2-3 hours
+
+**Description**: Set up Jest and write comprehensive tests
+
+**Install Jest**:
+```bash
+npm install --save-dev jest ts-jest @types/jest
+```
+
+**Create `jest.config.js`**:
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/index.ts',
+    '!src/**/*.d.ts'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    }
+  },
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1'
+  }
+};
+```
+
+**Run tests**:
+```bash
+npm test
+npm run test:coverage
+```
+
+**Acceptance Criteria**:
+- [x] All tests pass
+- [x] Coverage >80% for utility modules
+- [x] `npm test` works in CI/CD
+
+---
+
+## Validation Checklist
+
+Before marking this phase complete, verify:
+
+- [ ] `npm install` succeeds without errors
+- [ ] `npm run build` compiles TypeScript successfully
+- [ ] `npm run lint` passes without errors
+- [ ] `npm run format` formats code correctly
+- [ ] `npm test` passes all tests with >80% coverage
+- [ ] `npm run dev` runs CLI without crashing
+- [ ] Can import from `@memnexus-ai/contracts`
+- [ ] Config saves and loads correctly
+- [ ] API client initializes (with dummy key)
+- [ ] All three formatters work (JSON, table, YAML)
+- [ ] Error handling shows user-friendly messages
+
+---
+
+## Documentation
+
+**Create/Update**:
+- [ ] Add basic usage to `README.md`
+- [ ] Document config file location and format
+- [ ] Document environment variables
+- [ ] Add development setup instructions
+
+---
+
+## Dependencies
+
+**Production**:
+- `@memnexus-ai/contracts@^1.0.4`
+- `commander@^11.1.0`
+- `chalk@^5.3.0`
+- `ora@^7.0.1`
+- `cli-table3@^0.6.3`
+- `inquirer@^9.2.12`
+- `configstore@^7.0.0`
+- `dotenv@^16.3.1`
+- `js-yaml@^4.1.0`
+
+**Development**:
+- `typescript@^5.3.3`
+- `@types/node@^20.10.0`
+- `ts-node@^10.9.2`
+- `jest@^29.7.0`
+- `ts-jest@^29.1.1`
+- `@types/jest@^29.5.8`
+- `eslint@^8.55.0`
+- `@typescript-eslint/parser@^6.13.2`
+- `@typescript-eslint/eslint-plugin@^6.13.2`
+- `prettier@^3.1.0`
+- `eslint-config-prettier@^9.1.0`
+- `@types/js-yaml@^4.0.9`
+
+---
+
+## Timeline
+
+**Day 1-2**: Tasks 1-4 (Setup, dependencies, project structure)
+**Day 3-4**: Tasks 5-7 (Config, API client, auth)
+**Day 4-5**: Tasks 8-10 (Errors, formatters, tests)
+
+**Total**: 5 working days (1 week)
+
+---
+
+## Next Steps
+
+After Phase 1 completion:
+- **Phase 2**: Implement core commands (memories, conversations, facts)
+- Set up CI/CD workflows
+- Begin integration testing with real API
+
+---
+
+## Related Documentation
+
+- [PRD - Phase 1 Section](../docs/prd.md#phase-1-foundation-week-1)
+- [CLI-API Sync Strategy](../docs/sync-strategy.md)
+- [Code Generation Strategy](../docs/code-generation-strategy.md)
+
+---
+
+## Questions or Issues?
+
+If you encounter any blockers or need clarification:
+1. Check the [PRD documentation](../docs/prd.md)
+2. Review existing code in `@memnexus-ai/contracts`
+3. Comment on this issue or create a new one
+4. Tag relevant team members
+
+---
+
+**Estimated Total Time**: 15-20 hours (1 week)
+**Priority**: High (Blocks Phase 2)
+**Complexity**: Medium