cli4ai 0.8.0

package/src/lib/cli.ts

@@ -0,0 +1,234 @@
+/**
+ * cli4ai - cliforai.com
+ * Standardized CLI framework for AI agent tools
+ */
+
+import { Command } from 'commander';
+
+export const BRAND = 'cli4ai - cliforai.com';
+export const VERSION = '0.7.17';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface CLIError {
+  error: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+export type CommandFn = (...args: unknown[]) => Promise<void> | void;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ERROR CODES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const ErrorCodes = {
+  ENV_MISSING: 'ENV_MISSING',
+  INVALID_INPUT: 'INVALID_INPUT',
+  NOT_FOUND: 'NOT_FOUND',
+  AUTH_FAILED: 'AUTH_FAILED',
+  API_ERROR: 'API_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  RATE_LIMITED: 'RATE_LIMITED',
+  TIMEOUT: 'TIMEOUT',
+  PARSE_ERROR: 'PARSE_ERROR',
+  MANIFEST_ERROR: 'MANIFEST_ERROR',
+  INSTALL_ERROR: 'INSTALL_ERROR',
+} as const;
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENV VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+// SECURITY NOTE: We intentionally do NOT auto-load .env files from the filesystem.
+// This prevents supply chain attacks where malicious .env files in parent directories
+// could inject credentials or override security settings.
+//
+// Use `cli4ai secrets set <key>` for secure credential storage, or set environment
+// variables explicitly in your shell/CI environment.
+
+/**
+ * Require environment variables to be set. Exits with parseable error if missing.
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export function requireEnv(...variables: string[]): void {
+  const missing = variables.filter(v => !process.env[v]);
+  if (missing.length > 0) {
+    outputError('ENV_MISSING', `Missing required environment variables: ${missing.join(', ')}`, {
+      variables: missing,
+      hint: 'Use "cli4ai secrets set <key>" to store securely, or set in your shell environment'
+    });
+  }
+}
+
+/**
+ * Get env var or exit with error
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export function env(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    outputError('ENV_MISSING', `Missing required environment variable: ${name}`, {
+      variables: [name],
+      hint: 'Use "cli4ai secrets set ' + name + '" to store securely, or set in your shell environment'
+    });
+  }
+  return value;
+}
+
+/**
+ * Get env var or return default
+ */
+export function envOr(name: string, defaultValue: string): string {
+  return process.env[name] || defaultValue;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Output JSON data to stdout
+ */
+export function output(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Output error and exit. Format is parseable JSON.
+ */
+export function outputError(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>
+): never {
+  console.error(JSON.stringify({
+    error: code,
+    message,
+    ...details
+  }));
+  process.exit(1);
+}
+
+/**
+ * Log to stderr (for progress messages)
+ */
+export function log(message: string): void {
+  console.error(message);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CLI CREATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a branded CLI program
+ */
+export function cli(name: string, version: string, description: string): Command {
+  const program = new Command()
+    .name(name)
+    .version(version, '-v, --version', 'Show version')
+    .description(description)
+    .addHelpText('beforeAll', `\n${BRAND}\n`)
+    .configureOutput({
+      writeErr: (str) => {
+        // Don't double-output errors
+        if (!str.includes('"error"')) {
+          process.stderr.write(str);
+        }
+      }
+    })
+    .exitOverride((err) => {
+      if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+        process.exit(0);
+      }
+      if (err.code === 'commander.missingArgument') {
+        outputError('INVALID_INPUT', err.message, { code: err.code });
+      }
+      if (err.code === 'commander.unknownCommand') {
+        outputError('INVALID_INPUT', err.message, { code: err.code });
+      }
+      if (err.code !== 'commander.help') {
+        process.exit(1);
+      }
+    });
+
+  program.addHelpCommand('help [command]', 'Show help for command');
+
+  return program;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ERROR HANDLING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wrap an async action with error handling
+ */
+export function withErrorHandling<T extends unknown[]>(
+  fn: (...args: T) => Promise<void>
+): (...args: T) => Promise<void> {
+  return async (...args: T) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      outputError('API_ERROR', message);
+    }
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITY HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse a string as JSON, or return error
+ */
+export function parseJson<T>(str: string, context?: string): T {
+  try {
+    return JSON.parse(str);
+  } catch {
+    outputError('PARSE_ERROR', `Invalid JSON${context ? ` in ${context}` : ''}`, {
+      input: str.slice(0, 100)
+    });
+  }
+}
+
+/**
+ * Sleep for ms milliseconds
+ */
+export const sleep = (ms: number): Promise<void> =>
+  new Promise(r => setTimeout(r, ms));
+
+/**
+ * Format bytes to human readable
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+
+/**
+ * Format date to ISO string (date only)
+ */
+export function formatDate(date: Date | number | string): string {
+  const d = new Date(date);
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Format date to ISO string (datetime)
+ */
+export function formatDateTime(date: Date | number | string): string {
+  const d = new Date(date);
+  return d.toISOString().slice(0, 19).replace('T', ' ');
+}

package/src/mcp/adapter.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests for mcp/adapter.ts
+ */
+
+import { describe, test, expect } from 'bun:test';
+import {
+  manifestToMcpTools,
+  commandToMcpTool,
+  type McpTool
+} from './adapter.js';
+import type { Manifest, CommandDef } from '../core/manifest.js';
+
+describe('mcp/adapter', () => {
+  describe('commandToMcpTool', () => {
+    test('converts simple command', () => {
+      const manifest: Manifest = {
+        name: 'github',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+      const cmd: CommandDef = {
+        description: 'Get notifications'
+      };
+
+      const tool = commandToMcpTool(manifest, 'notifs', cmd);
+
+      expect(tool.name).toBe('github_notifs');
+      expect(tool.description).toContain('Get notifications');
+      expect(tool.inputSchema.type).toBe('object');
+      expect(tool.inputSchema.properties).toEqual({});
+      expect(tool.inputSchema.required).toEqual([]);
+    });
+
+    test('converts command with args', () => {
+      const manifest: Manifest = {
+        name: 'search',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+      const cmd: CommandDef = {
+        description: 'Find items',
+        args: [
+          { name: 'query', description: 'Search query', required: true },
+          { name: 'limit', description: 'Max results', required: false }
+        ]
+      };
+
+      const tool = commandToMcpTool(manifest, 'find', cmd);
+
+      expect(tool.inputSchema.properties.query).toBeDefined();
+      expect(tool.inputSchema.properties.query.description).toBe('Search query');
+      expect(tool.inputSchema.properties.limit).toBeDefined();
+      expect(tool.inputSchema.required).toEqual(['query']);
+    });
+
+    test('uses manifest name as prefix', () => {
+      const manifest: Manifest = {
+        name: 'my-tool',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+      const cmd: CommandDef = { description: 'Do action' };
+
+      const tool = commandToMcpTool(manifest, 'action', cmd);
+
+      expect(tool.name).toBe('my-tool_action');
+    });
+  });
+
+  describe('manifestToMcpTools', () => {
+    test('returns empty array when no commands', () => {
+      const manifest: Manifest = {
+        name: 'tool',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+
+      const tools = manifestToMcpTools(manifest);
+      expect(tools).toEqual([]);
+    });
+
+    test('returns empty array for empty commands', () => {
+      const manifest: Manifest = {
+        name: 'tool',
+        version: '1.0.0',
+        entry: 'run.ts',
+        commands: {}
+      };
+
+      const tools = manifestToMcpTools(manifest);
+      expect(tools).toEqual([]);
+    });
+
+    test('converts single command', () => {
+      const manifest: Manifest = {
+        name: 'github',
+        version: '1.0.0',
+        entry: 'run.ts',
+        commands: {
+          notifs: { description: 'Get notifications' }
+        }
+      };
+
+      const tools = manifestToMcpTools(manifest);
+
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe('github_notifs');
+    });
+
+    test('converts multiple commands', () => {
+      const manifest: Manifest = {
+        name: 'api',
+        version: '1.0.0',
+        entry: 'run.ts',
+        commands: {
+          list: { description: 'List items' },
+          get: { description: 'Get item' },
+          create: { description: 'Create item' }
+        }
+      };
+
+      const tools = manifestToMcpTools(manifest);
+
+      expect(tools).toHaveLength(3);
+      expect(tools.map(t => t.name).sort()).toEqual([
+        'api_create',
+        'api_get',
+        'api_list'
+      ]);
+    });
+  });
+});

package/src/mcp/adapter.ts

@@ -0,0 +1,123 @@
+/**
+ * MCP Adapter - Converts CLI tools to MCP tools
+ */
+
+import { spawn } from 'child_process';
+import { type Manifest, type CommandDef } from '../core/manifest.js';
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, { type: string; description?: string }>;
+    required: string[];
+  };
+}
+
+export interface McpToolResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}
+
+/**
+ * Convert a CLI command definition to MCP tool format
+ */
+export function commandToMcpTool(manifest: Manifest, cmdName: string, cmd: CommandDef): McpTool {
+  const properties: Record<string, { type: string; description?: string }> = {};
+  const required: string[] = [];
+
+  // Convert args to JSON Schema properties
+  if (cmd.args) {
+    for (const arg of cmd.args) {
+      properties[arg.name] = {
+        type: 'string',
+        description: arg.description
+      };
+      if (arg.required) {
+        required.push(arg.name);
+      }
+    }
+  }
+
+  return {
+    name: `${manifest.name}_${cmdName}`,
+    description: `${manifest.name}: ${cmd.description || cmdName}`,
+    inputSchema: {
+      type: 'object',
+      properties,
+      required
+    }
+  };
+}
+
+/**
+ * Convert all commands in a manifest to MCP tools
+ */
+export function manifestToMcpTools(manifest: Manifest): McpTool[] {
+  const tools: McpTool[] = [];
+
+  if (manifest.commands) {
+    for (const [cmdName, cmdDef] of Object.entries(manifest.commands)) {
+      tools.push(commandToMcpTool(manifest, cmdName, cmdDef));
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Execute a CLI tool command and return MCP-formatted result
+ */
+export async function executeTool(
+  entryPath: string,
+  runtime: string,
+  command: string,
+  args: Record<string, string>
+): Promise<McpToolResult> {
+  return new Promise((resolve) => {
+    // Build command arguments
+    const cmdArgs = [command];
+    for (const [key, value] of Object.entries(args)) {
+      if (value !== undefined && value !== '') {
+        cmdArgs.push(value);
+      }
+    }
+
+    const proc = spawn(runtime, ['run', entryPath, ...cmdArgs], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env }
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        resolve({
+          content: [{ type: 'text', text: stderr || `Command failed with exit code ${code}` }],
+          isError: true
+        });
+      } else {
+        resolve({
+          content: [{ type: 'text', text: stdout || 'Command completed successfully' }]
+        });
+      }
+    });
+
+    proc.on('error', (err) => {
+      resolve({
+        content: [{ type: 'text', text: `Failed to execute: ${err.message}` }],
+        isError: true
+      });
+    });
+  });
+}

package/src/mcp/config-gen.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for mcp/config-gen.ts
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  generateServerConfig,
+  generateClaudeCodeConfig,
+  formatClaudeCodeConfig,
+  generateConfigSnippet
+} from './config-gen.js';
+import type { Manifest } from '../core/manifest.js';
+
+describe('mcp/config-gen', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli4ai-config-gen-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('generateServerConfig', () => {
+    test('generates config with cli4ai start command', () => {
+      const manifest: Manifest = {
+        name: 'github',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+
+      const config = generateServerConfig(manifest, '/path/to/package');
+
+      expect(config.command).toBe('cli4ai');
+      expect(config.args).toEqual(['start', 'github']);
+    });
+
+    test('uses package name from manifest', () => {
+      const manifest: Manifest = {
+        name: 'custom-tool',
+        version: '2.0.0',
+        entry: 'index.ts'
+      };
+
+      const config = generateServerConfig(manifest, '/any/path');
+
+      expect(config.args).toEqual(['start', 'custom-tool']);
+    });
+  });
+
+  describe('formatClaudeCodeConfig', () => {
+    test('formats empty config', () => {
+      const config = { mcpServers: {} };
+
+      const output = formatClaudeCodeConfig(config);
+      const parsed = JSON.parse(output);
+
+      expect(parsed).toEqual({ mcpServers: {} });
+    });
+
+    test('formats config with servers', () => {
+      const config = {
+        mcpServers: {
+          'cli4ai-github': {
+            command: 'cli4ai',
+            args: ['start', 'github']
+          }
+        }
+      };
+
+      const output = formatClaudeCodeConfig(config);
+      const parsed = JSON.parse(output);
+
+      expect(parsed.mcpServers['cli4ai-github'].command).toBe('cli4ai');
+    });
+
+    test('produces pretty-printed JSON', () => {
+      const config = { mcpServers: {} };
+
+      const output = formatClaudeCodeConfig(config);
+
+      expect(output).toContain('\n');
+      expect(output).toContain('  ');
+    });
+  });
+
+  describe('generateConfigSnippet', () => {
+    test('generates snippet for single package', () => {
+      const manifest: Manifest = {
+        name: 'slack',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+
+      const snippet = generateConfigSnippet(manifest, '/path/to/slack');
+
+      expect(snippet).toContain('"cli4ai-slack"');
+      expect(snippet).toContain('cli4ai');
+      expect(snippet).toContain('start');
+      expect(snippet).toContain('slack');
+    });
+
+    test('snippet is valid JSON when wrapped', () => {
+      const manifest: Manifest = {
+        name: 'tool',
+        version: '1.0.0',
+        entry: 'run.ts'
+      };
+
+      const snippet = generateConfigSnippet(manifest, '/path');
+
+      // Should be valid when wrapped in braces
+      const wrapped = `{${snippet}}`;
+      const parsed = JSON.parse(wrapped);
+
+      expect(parsed['cli4ai-tool']).toBeDefined();
+    });
+  });
+
+  describe('generateClaudeCodeConfig', () => {
+    test('returns config with only local packages when no local packages exist', () => {
+      // Note: This may include global packages, so we just check it returns a valid config
+      const config = generateClaudeCodeConfig(tempDir);
+
+      expect(config.mcpServers).toBeDefined();
+      expect(typeof config.mcpServers).toBe('object');
+    });
+
+    test('includes MCP-enabled packages', () => {
+      // Create a local package directory
+      const localDir = join(tempDir, '.cli4ai', 'packages', 'test-mcp');
+      mkdirSync(localDir, { recursive: true });
+      writeFileSync(
+        join(localDir, 'cli4ai.json'),
+        JSON.stringify({
+          name: 'test-mcp',
+          version: '1.0.0',
+          entry: 'run.ts',
+          mcp: { enabled: true }
+        })
+      );
+
+      const config = generateClaudeCodeConfig(tempDir);
+
+      expect(config.mcpServers['cli4ai-test-mcp']).toBeDefined();
+    });
+
+    test('excludes packages without MCP enabled', () => {
+      // Create a package without MCP
+      const localDir = join(tempDir, '.cli4ai', 'packages', 'no-mcp');
+      mkdirSync(localDir, { recursive: true });
+      writeFileSync(
+        join(localDir, 'cli4ai.json'),
+        JSON.stringify({
+          name: 'no-mcp',
+          version: '1.0.0',
+          entry: 'run.ts'
+          // No mcp field
+        })
+      );
+
+      const config = generateClaudeCodeConfig(tempDir);
+
+      expect(config.mcpServers['cli4ai-no-mcp']).toBeUndefined();
+    });
+
+    test('excludes packages with mcp.enabled=false', () => {
+      const localDir = join(tempDir, '.cli4ai', 'packages', 'disabled-mcp');
+      mkdirSync(localDir, { recursive: true });
+      writeFileSync(
+        join(localDir, 'cli4ai.json'),
+        JSON.stringify({
+          name: 'disabled-mcp',
+          version: '1.0.0',
+          entry: 'run.ts',
+          mcp: { enabled: false }
+        })
+      );
+
+      const config = generateClaudeCodeConfig(tempDir);
+
+      expect(config.mcpServers['cli4ai-disabled-mcp']).toBeUndefined();
+    });
+
+    test('filters by specific packages', () => {
+      // Create multiple packages
+      for (const name of ['pkg-a', 'pkg-b', 'pkg-c']) {
+        const localDir = join(tempDir, '.cli4ai', 'packages', name);
+        mkdirSync(localDir, { recursive: true });
+        writeFileSync(
+          join(localDir, 'cli4ai.json'),
+          JSON.stringify({
+            name,
+            version: '1.0.0',
+            entry: 'run.ts',
+            mcp: { enabled: true }
+          })
+        );
+      }
+
+      const config = generateClaudeCodeConfig(tempDir, {
+        packages: ['pkg-a', 'pkg-c']
+      });
+
+      expect(config.mcpServers['cli4ai-pkg-a']).toBeDefined();
+      expect(config.mcpServers['cli4ai-pkg-b']).toBeUndefined();
+      expect(config.mcpServers['cli4ai-pkg-c']).toBeDefined();
+    });
+  });
+});