cli4ai 0.8.0

package/README.md

@@ -0,0 +1,275 @@
+# cli4ai
+
+> Official CLI4AI package • https://cli4ai.com
+
+The package manager for AI CLI tools.
+
+## Setup
+
+```bash
+# Install cli4ai
+npm i -g cli4ai
+# or (optional)
+bun install -g cli4ai
+
+# Install a package
+cli4ai add -g github
+
+# Run it
+cli4ai run github notifs
+```
+
+## Why cli4ai?
+
+AI agents need tools. MCP servers are complex to set up. cli4ai makes it simple:
+
+- **Install tools in seconds** - `cli4ai add github` just works
+- **Run from anywhere** - `cli4ai run <tool> <command>`
+- **No MCP boilerplate** - cli4ai wraps CLI tools as MCP servers automatically
+- **Local-first** - Tools are just scripts, no cloud required
+
+## Quick Start
+
+```bash
+# Add a local registry (directory containing tools)
+cli4ai config --add-registry ~/my-tools
+
+# Search for tools
+cli4ai search github
+
+# Install globally (available everywhere)
+cli4ai add -g github
+
+# Install locally (project-scoped)
+cd ~/my-project
+cli4ai add mongodb
+
+# Run tools
+cli4ai run github notifs
+cli4ai run mongodb databases
+```
+
+## Commands
+
+### Package Management
+
+| Command | Description |
+|---------|-------------|
+| `cli4ai add <pkg>` | Install package locally |
+| `cli4ai add -g <pkg>` | Install package globally |
+| `cli4ai remove <pkg>` | Uninstall package |
+| `cli4ai remove -g <pkg>` | Uninstall global package |
+| `cli4ai list` | List local packages |
+| `cli4ai list -g` | List global packages |
+
+### Discovery
+
+| Command | Description |
+|---------|-------------|
+| `cli4ai search <query>` | Search for packages |
+| `cli4ai info <pkg>` | Show package details |
+
+### Execution
+
+| Command | Description |
+|---------|-------------|
+| `cli4ai run <pkg> <cmd> [args]` | Run a tool command |
+| `cli4ai start <pkg>` | Start package as MCP server |
+
+Notes:
+- Tool flags are supported: `cli4ai run chrome screenshot https://example.com --full-page`
+- If a flag conflicts with `cli4ai run` options, use `--` to pass-through: `cli4ai run <pkg> <cmd> -- --help`
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `cli4ai config` | Show current config |
+| `cli4ai config --add-registry <path>` | Add local registry |
+| `cli4ai config --remove-registry <path>` | Remove registry |
+
+### Project Setup
+
+| Command | Description |
+|---------|-------------|
+| `cli4ai init [name]` | Create a new tool project |
+| `cli4ai mcp-config` | Generate Claude Code MCP config |
+
+## Package Format
+
+Tools are defined by a `cli4ai.json` manifest:
+
+```json
+{
+  "name": "github",
+  "version": "1.0.0",
+  "description": "GitHub CLI wrapper",
+  "entry": "run.ts",
+  "runtime": "bun",
+  "commands": {
+    "notifs": {
+      "description": "Your notifications"
+    },
+    "repos": {
+      "description": "List repositories",
+      "args": [
+        { "name": "user", "required": false }
+      ]
+    }
+  },
+  "env": {
+    "GITHUB_TOKEN": {
+      "required": false,
+      "description": "Personal access token"
+    }
+  },
+  "mcp": {
+    "enabled": true
+  }
+}
+```
+
+### Manifest Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Package name (lowercase, hyphens ok) |
+| `version` | Yes | Semver version |
+| `entry` | Yes | Entry point script |
+| `description` | No | Package description |
+| `runtime` | No | Runtime: `bun` (default), `node`, `deno` |
+| `commands` | No | Command definitions for MCP |
+| `env` | No | Environment variable requirements |
+| `mcp.enabled` | No | Enable MCP server mode |
+
+## Storage Locations
+
+```
+~/.cli4ai/
+├── config.json          # Global configuration
+├── packages/            # Globally installed packages
+│   └── github/
+└── bin/                 # PATH-linked executables (optional)
+
+./
+├── cli4ai.json            # Project manifest (if a tool)
+├── cli4ai.lock            # Lock file (reproducible installs)
+└── .cli4ai/
+    └── packages/        # Locally installed packages
+```
+
+## MCP Integration
+
+cli4ai can generate configuration for Claude Code:
+
+```bash
+# Generate config for all installed packages
+cli4ai mcp-config
+
+# Generate for specific packages
+cli4ai mcp-config --packages github,slack
+
+# Get snippet for a single package
+cli4ai mcp-config --package github --snippet
+```
+
+Output:
+```json
+{
+  "mcpServers": {
+    "cli4ai-github": {
+      "command": "cli4ai",
+      "args": ["start", "github"]
+    }
+  }
+}
+```
+
+Add this to your Claude Code MCP settings.
+
+## Local Registries
+
+cli4ai discovers packages from local directories:
+
+```bash
+# Add a registry
+cli4ai config --add-registry ~/agent-tools
+
+# Now packages in ~/agent-tools are discoverable
+cli4ai search github  # Finds ~/agent-tools/github/
+```
+
+A registry is just a directory containing tool folders, each with a `cli4ai.json`.
+
+## Creating Tools
+
+```bash
+# Create a new tool
+cli4ai init my-tool
+cd my-tool
+
+# Edit `run.ts` and `cli4ai.json`
+
+# Test locally
+bun run run.ts hello world
+
+# Install for testing
+cd ~/some-project
+cli4ai add --local ~/path/to/my-tool -y
+cli4ai run my-tool hello world
+```
+
+### Tool Entry Point
+
+Tools are simple CLI scripts that output JSON:
+
+```typescript
+#!/usr/bin/env bun
+
+import { cli, output } from '@cli4ai/lib/cli.ts';
+
+const program = cli('my-tool', '1.0.0', 'Example tool');
+
+program
+  .command('hello [name]')
+  .description('Say hello')
+  .action((name?: string) => {
+    output({ message: `Hello, ${name || 'world'}!` });
+  });
+
+program.parse();
+```
+
+When run via `cli4ai run`, these env vars are set for convenience:
+- `CLI4AI_CWD`: directory where you invoked `cli4ai`
+- `C4AI_PACKAGE_DIR`: installed package directory
+- `C4AI_PACKAGE_NAME`: resolved package name
+- `C4AI_ENTRY`: absolute path to the tool entry file
+
+## Global vs Local Install
+
+| Aspect | Global (`-g`) | Local (default) |
+|--------|---------------|-----------------|
+| Location | `~/.cli4ai/packages/` | `./.cli4ai/packages/` |
+| Scope | Available everywhere | Project only |
+| Lock file | No | Yes (`cli4ai.lock`) |
+| Use case | Utilities (github, slack) | Project-specific (mongodb) |
+
+## Environment Variables
+
+Tools can require environment variables:
+
+```json
+{
+  "env": {
+    "API_KEY": { "required": true },
+    "DEBUG": { "required": false, "default": "false" }
+  }
+}
+```
+
+Set them in your shell or `.env` file.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "cli4ai",
+  "version": "0.8.0",
+  "description": "The package manager for AI CLI tools - cliforai.com",
+  "type": "module",
+  "bin": {
+    "cli4ai": "./src/bin.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/bin.ts",
+    "build": "bun build src/bin.ts --outdir dist --target node",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "@types/node": "^22.0.0",
+    "@types/semver": "^7.5.0",
+    "typescript": "^5.7.0"
+  },
+  "author": "cliforai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cliforai/framework"
+  },
+  "homepage": "https://cliforai.com",
+  "keywords": [
+    "cli",
+    "ai",
+    "tools",
+    "mcp",
+    "package-manager",
+    "cli4ai"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "templates/**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/**
+ * cli4ai - The package manager for AI CLI tools
+ * cliforai.com
+ */
+
+import { createProgram } from './cli.js';
+import { VERSION } from './lib/cli.js';
+import { getNpmGlobalPackages } from './core/config.js';
+
+// ANSI codes
+const RESET = '\x1B[0m';
+const BOLD = '\x1B[1m';
+const DIM = '\x1B[2m';
+const CYAN = '\x1B[36m';
+const WHITE = '\x1B[37m';
+const GREEN = '\x1B[32m';
+const YELLOW = '\x1B[33m';
+const MAGENTA = '\x1B[35m';
+
+/**
+ * Sleep helper
+ */
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Robot eating dots animation
+ */
+async function showAnimation(): Promise<void> {
+  const width = 35;
+  const robot = ['[•_•]', '[•_•]', '[°_°]', '[•_•]'];
+  const food = '·';
+
+  for (let pos = 0; pos <= width; pos++) {
+    process.stdout.write('\r\x1B[K');
+    const frame = robot[pos % robot.length];
+    const trail = ' '.repeat(pos) + food.repeat(width - pos);
+    process.stdout.write(`  ${CYAN}${frame}${RESET}${DIM}${trail}${RESET}`);
+    await sleep(20);
+  }
+  process.stdout.write('\r\x1B[K');
+}
+
+/**
+ * Animate the robot face (blinking)
+ */
+async function animateRobotFace(): Promise<void> {
+  const faces = ['[•_•]', '[•_•]', '[-_-]', '[•_•]', '[•_•]', '[°_°]', '[•_•]'];
+  const line = ` ${BOLD}${CYAN}cli4ai${RESET} ${DIM}─${RESET} ${WHITE}cliforai.com${RESET}`;
+
+  for (const face of faces) {
+    process.stdout.write(`\r  ${CYAN}${face}${RESET}${line}`);
+    await sleep(120);
+  }
+  console.log('');
+}
+
+async function showBanner(): Promise<void> {
+  if (!process.stdout.isTTY) return;
+
+  console.log('');
+
+  // Fun robot eating animation
+  await showAnimation();
+
+  // Animated robot branding (blinking)
+  await animateRobotFace();
+
+  console.log(`        ${DIM}The package manager for AI CLI tools${RESET}`);
+  console.log(`        ${DIM}v${VERSION}${RESET}`);
+  console.log('');
+  console.log(`  ${BOLD}Commands${RESET}`);
+  console.log(`  ${DIM}${'─'.repeat(40)}${RESET}`);
+  console.log(`  ${GREEN}browse${RESET}              ${DIM}Browse & install packages${RESET}`);
+  console.log(`  ${GREEN}run${RESET} ${CYAN}<pkg> <cmd>${RESET}    ${DIM}Run a tool command${RESET}`);
+  console.log(`  ${GREEN}ls${RESET}                  ${DIM}List installed packages${RESET}`);
+  console.log(`  ${GREEN}update${RESET}              ${DIM}Update all packages${RESET}`);
+  console.log('');
+  console.log(`  ${DIM}Run`${RESET} ${WHITE}cli4ai --help${RESET} ${DIM}for all commands${RESET}`);
+  console.log('');
+
+  // Check for updates in background (non-blocking)
+  checkUpdatesInBackground();
+}
+
+/**
+ * Check for updates without blocking - spawns detached process
+ */
+function checkUpdatesInBackground(): void {
+  // Quick local check only - don't hit network
+  try {
+    const packages = getNpmGlobalPackages();
+    if (packages.length > 0) {
+      // Spawn a background process to check updates and cache results
+      const child = Bun.spawn(['sh', '-c', `
+        # Quick npm check (with timeout)
+        timeout 3 npm view cli4ai version 2>/dev/null > /tmp/.cli4ai-update-check 2>&1 &
+      `], {
+        detached: true,
+        stdio: ['ignore', 'ignore', 'ignore']
+      });
+      child.unref();
+    }
+  } catch {
+    // Ignore errors - this is best effort
+  }
+}
+
+// Check if running without command (just `cli4ai`)
+const args = process.argv.slice(2);
+const hasCommand = args.length > 0 && !args[0].startsWith('-');
+const isHelp = args.includes('--help') || args.includes('-h');
+const isVersion = args.includes('--version') || args.includes('-v');
+
+if (!hasCommand && !isHelp && !isVersion) {
+  showBanner().then(() => process.exit(0));
+} else {
+  const program = createProgram();
+  program.parse(process.argv);
+}

package/src/cli.ts

@@ -0,0 +1,256 @@
+/**
+ * cli4ai CLI - Main program setup
+ */
+
+import { Command } from 'commander';
+import { BRAND, VERSION, withErrorHandling } from './lib/cli.js';
+
+// Commands
+import { initCommand } from './commands/init.js';
+import { addCommand } from './commands/add.js';
+import { removeCommand } from './commands/remove.js';
+import { listCommand } from './commands/list.js';
+import { runCommand } from './commands/run.js';
+import { infoCommand } from './commands/info.js';
+import { searchCommand } from './commands/search.js';
+import { configCommand } from './commands/config.js';
+import { mcpConfigCommand } from './commands/mcp-config.js';
+import { startCommand } from './commands/start.js';
+import {
+  secretsSetCommand,
+  secretsGetCommand,
+  secretsListCommand,
+  secretsDeleteCommand,
+  secretsInitCommand
+} from './commands/secrets.js';
+import { browseCommand } from './commands/browse.js';
+import { updateCommand } from './commands/update.js';
+import { routinesListCommand, routinesRunCommand, routinesShowCommand, routinesCreateCommand, routinesEditCommand, routinesRemoveCommand } from './commands/routines.js';
+
+export function createProgram(): Command {
+  const program = new Command()
+    .name('cli4ai')
+    .version(VERSION, '-v, --version', 'Show version')
+    .description('The package manager for AI CLI tools')
+    .addHelpText('beforeAll', `\n${BRAND}\n`)
+    .configureOutput({
+      writeErr: (str) => {
+        if (!str.includes('"error"')) {
+          process.stderr.write(str);
+        }
+      }
+    });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PACKAGE MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('init [name]')
+    .description('Create a new cli4ai tool project')
+    .option('-t, --template <template>', 'Template to use (basic, api, browser)', 'basic')
+    .option('-r, --runtime <runtime>', 'Runtime (bun, node)', 'bun')
+    .option('-y, --yes', 'Skip prompts, use defaults')
+    .action(withErrorHandling(initCommand));
+
+  program
+    .command('add <packages...>')
+    .description('Install packages')
+    .option('-l, --local', 'Install from local path')
+    .option('-g, --global', 'Install globally')
+    .option('-D, --save-dev', 'Save as dev dependency')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action(withErrorHandling(addCommand));
+
+  program
+    .command('remove <packages...>')
+    .alias('rm')
+    .alias('uninstall')
+    .description('Remove packages')
+    .option('-g, --global', 'Remove from global packages')
+    .action(withErrorHandling(removeCommand));
+
+  program
+    .command('list')
+    .alias('ls')
+    .description('List installed packages')
+    .option('-g, --global', 'List global packages')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(listCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // EXECUTION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('run <package> [command] [args...]')
+    .description('Run a tool command')
+    .option('-e, --env <vars...>', 'Environment variables (KEY=value)')
+    // Allow passing tool flags through (e.g. `cli4ai run chrome screenshot --full-page`)
+    .allowUnknownOption(true)
+    .addHelpText('after', `
+
+Examples:
+  cli4ai run github trending
+  cli4ai run chrome screenshot https://example.com --full-page
+
+Pass-through:
+  Use "--" to pass flags that would otherwise be parsed by cli4ai:
+  cli4ai run <pkg> <cmd> -- --help
+`)
+    .action(withErrorHandling(runCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DISCOVERY
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('info <package>')
+    .description('Show package information')
+    .option('--versions', 'Show all available versions')
+    .action(withErrorHandling(infoCommand));
+
+  program
+    .command('search <query>')
+    .description('Search for packages')
+    .option('-l, --limit <n>', 'Max results', '20')
+    .action(withErrorHandling(searchCommand));
+
+  program
+    .command('browse')
+    .description('Interactive package browser')
+    .action(withErrorHandling(browseCommand));
+
+  program
+    .command('update')
+    .alias('upgrade')
+    .description('Update installed packages')
+    .option('-s, --self', 'Update cli4ai framework only')
+    .option('-a, --all', 'Update cli4ai framework and all packages')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action(withErrorHandling(updateCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CONFIGURATION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('config [key] [value]')
+    .description('Get or set configuration')
+    .option('--list', 'List all config values')
+    .option('--add-registry <path>', 'Add local registry path')
+    .option('--remove-registry <path>', 'Remove local registry path')
+    .action(withErrorHandling(configCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // MCP INTEGRATION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('mcp-config')
+    .description('Generate MCP configuration for Claude Code')
+    .option('-g, --global', 'Use global packages only')
+    .option('-p, --package <name>', 'Generate for specific package')
+    .option('--snippet', 'Output as config snippet (use with --package)')
+    .action(withErrorHandling(mcpConfigCommand));
+
+  program
+    .command('start <package>')
+    .description('Start MCP server for a package')
+    .option('--stdio', 'Use stdio transport (default)')
+    .action(withErrorHandling(startCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECRETS MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  const secrets = program
+    .command('secrets')
+    .description('Manage secrets for CLI tools');
+
+  secrets
+    .command('set <key> [value]')
+    .description('Set a secret (prompts for value if not provided)')
+    .action(withErrorHandling(secretsSetCommand));
+
+  secrets
+    .command('get <key>')
+    .description('Get a secret value')
+    .action(withErrorHandling(secretsGetCommand));
+
+  secrets
+    .command('list')
+    .alias('ls')
+    .description('List all secrets')
+    .option('-p, --package <name>', 'Show secrets for a specific package')
+    .action(withErrorHandling(secretsListCommand));
+
+  secrets
+    .command('delete <key>')
+    .alias('rm')
+    .description('Delete a secret')
+    .action(withErrorHandling(secretsDeleteCommand));
+
+  secrets
+    .command('init <package>')
+    .description('Interactive setup for a package\'s required secrets')
+    .action(withErrorHandling(secretsInitCommand));
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // HELP
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program.addHelpCommand('help [command]', 'Show help for command');
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ROUTINES
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  const routines = program
+    .command('routines')
+    .description('Manage and run routines');
+
+  routines
+    .command('list')
+    .alias('ls')
+    .description('List available routines')
+    .option('-g, --global', 'Use global routines only')
+    .option('--json', 'Output as JSON')
+    .action(withErrorHandling(routinesListCommand));
+
+  routines
+    .command('show <name>')
+    .description('Show routine definition')
+    .option('-g, --global', 'Use global routines only')
+    .action(withErrorHandling(routinesShowCommand));
+
+  routines
+    .command('create <name>')
+    .description('Create a new routine')
+    .option('-g, --global', 'Create routine globally')
+    .option('--type <type>', 'Routine type (bash, json)', 'bash')
+    .action(withErrorHandling(routinesCreateCommand));
+
+  routines
+    .command('edit <name>')
+    .description('Edit a routine in $EDITOR')
+    .option('-g, --global', 'Use global routine only')
+    .action(withErrorHandling(routinesEditCommand));
+
+  routines
+    .command('remove <name>')
+    .alias('rm')
+    .description('Remove a routine')
+    .option('-g, --global', 'Use global routine only')
+    .action(withErrorHandling(routinesRemoveCommand));
+
+  routines
+    .command('run <name> [args...]')
+    .description('Run a routine')
+    .option('-g, --global', 'Use global routine only')
+    .option('--var <vars...>', 'Variables (KEY=value)')
+    .option('--dry-run', 'Show execution plan without running')
+    .action(withErrorHandling(routinesRunCommand));
+
+  return program;
+}