@asvanevik/mcli 0.0.5

package/README.md

@@ -0,0 +1,76 @@
+# mcli
+
+A CLI for discovering and comparing CLI tools — optimized for AI agents.
+
+## Why?
+
+Package managers tell you *how* to install tools. mcli tells you *which* tools are best for your use case, with structured metadata about agent-friendliness.
+
+## Features
+
+- **Discovery** — Search and compare CLI tools across categories
+- **Agent Scores** — Rate tools on JSON output, idempotency, auth complexity
+- **Verification Tiers** — Know if a tool is officially verified, community-vetted, or unverified
+- **Install Commands** — Get the right install command for your platform
+
+## Quick Start
+
+```bash
+npx mcli search cloud
+npx mcli info hcloud
+npx mcli compare aws gcloud hcloud
+npx mcli install gh
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `search <query>` | Search for CLI tools |
+| `info <slug>` | Show detailed info about a tool |
+| `compare <slug> [slug...]` | Compare multiple tools side-by-side |
+| `install <slug>` | Show install commands for a tool |
+| `list` | List all tools |
+| `list --agent-friendly` | List tools sorted by agent score |
+| `categories` | List all categories |
+
+## Agent Score
+
+Tools are rated 1-10 on agent-friendliness based on:
+
+- **JSON Output** — Parseable structured output
+- **Idempotency** — Same command, same result
+- **Auth Simplicity** — Env vars vs interactive flows
+- **Error Clarity** — Actionable error messages
+- **Streaming** — Handles long-running operations
+
+## Verification Tiers
+
+- ✓ **Verified** — Traced to official vendor source
+- ○ **Community** — Submitted and reviewed by community
+- ? **Unverified** — Auto-indexed, use with caution
+
+## Roadmap
+
+- [ ] Agent reviews — Let AI agents rate tools based on real usage
+- [ ] PR reputation — Agents earn trust by contributing to CLI repos
+- [ ] Web interface — Browse the registry online
+- [ ] Skill integration — Link to skills.sh for usage instructions
+
+## Development
+
+This project follows **test-driven development (TDD)**. Tests must pass before merging.
+
+```bash
+npm test              # Run tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```
+
+## Contributing
+
+PRs welcome! To add a tool, edit `registry/tools.json`. All tools are validated by tests.
+
+## License
+
+MIT

package/bin/mcli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { searchTools, findTool, getCategories, sortByAgentScore, tierBadge, filterByMinScore, filterByCategory } from './lib.js';
+import { loadRegistry, RegistryError } from './registry.js';
+// Parse --flag and --flag=value from args
+function parseFlag(args, flag) {
+    for (const arg of args) {
+        if (arg === flag)
+            return 'true';
+        if (arg.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return null;
+}
+function parseNumericFlag(args, flag) {
+    const val = parseFlag(args, flag);
+    if (val === null)
+        return null;
+    const num = parseInt(val, 10);
+    return isNaN(num) ? null : num;
+}
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const registryPath = join(__dirname, '..', 'registry', 'tools.json');
+function scoreColor(score) {
+    if (score >= 8)
+        return '\x1b[32m'; // green
+    if (score >= 5)
+        return '\x1b[33m'; // yellow
+    return '\x1b[31m'; // red
+}
+function reset() {
+    return '\x1b[0m';
+}
+function printTool(tool, verbose = false) {
+    const badge = tierBadge(tool.tier);
+    const color = scoreColor(tool.agentScore);
+    console.log(`${badge} ${tool.name} (${tool.slug}) - Agent Score: ${color}${tool.agentScore}/10${reset()}`);
+    console.log(`  ${tool.description}`);
+    if (verbose) {
+        console.log(`  Vendor: ${tool.vendor.name} (${tool.vendor.domain})`);
+        console.log(`  Categories: ${tool.categories.join(', ')}`);
+        // Show agent score breakdown if available
+        if (tool.agentScores) {
+            console.log(`  Agent Scores (1-5 each):`);
+            console.log(`    JSON Output:     ${tool.agentScores.jsonOutput}/5`);
+            console.log(`    Non-Interactive: ${tool.agentScores.nonInteractive}/5`);
+            console.log(`    Token Efficiency:${tool.agentScores.tokenEfficiency}/5`);
+            console.log(`    Safety Features: ${tool.agentScores.safetyFeatures}/5`);
+            console.log(`    Pipeline Friend: ${tool.agentScores.pipelineFriendly}/5`);
+        }
+        console.log(`  Install:`);
+        for (const [method, cmd] of Object.entries(tool.install)) {
+            if (cmd)
+                console.log(`    ${method}: ${cmd}`);
+        }
+        console.log(`  Capabilities:`);
+        console.log(`    JSON output: ${tool.capabilities.jsonOutput ? 'yes' : 'no'}`);
+        console.log(`    Idempotent: ${tool.capabilities.idempotent ? 'yes' : 'no'}`);
+        console.log(`    Interactive: ${tool.capabilities.interactive ? 'yes' : 'no'}`);
+        if (tool.capabilities.auth.length > 0) {
+            console.log(`    Auth: ${tool.capabilities.auth.join(', ')}`);
+        }
+        if (tool.repo)
+            console.log(`  Repo: ${tool.repo}`);
+        if (tool.docs)
+            console.log(`  Docs: ${tool.docs}`);
+    }
+    console.log();
+}
+// search function moved to lib.ts as searchTools
+function compare(registry, slugs) {
+    const tools = slugs.map(slug => registry.tools.find(t => t.slug === slug)).filter((t) => t !== undefined);
+    if (tools.length === 0) {
+        console.log('No tools found');
+        return;
+    }
+    // Header
+    console.log('Tool'.padEnd(20) + tools.map(t => t.slug.padEnd(15)).join(''));
+    console.log('-'.repeat(20 + tools.length * 15));
+    // Rows
+    console.log('Agent Score'.padEnd(20) + tools.map(t => `${t.agentScore}/10`.padEnd(15)).join(''));
+    console.log('JSON Output'.padEnd(20) + tools.map(t => (t.capabilities.jsonOutput ? 'yes' : 'no').padEnd(15)).join(''));
+    console.log('Idempotent'.padEnd(20) + tools.map(t => (t.capabilities.idempotent ? 'yes' : 'no').padEnd(15)).join(''));
+    console.log('Interactive'.padEnd(20) + tools.map(t => (t.capabilities.interactive ? 'yes' : 'no').padEnd(15)).join(''));
+    console.log('Verified'.padEnd(20) + tools.map(t => (t.tier === 'verified' ? '✓' : '○').padEnd(15)).join(''));
+    console.log('Install (brew)'.padEnd(20) + tools.map(t => (t.install.brew || '-').padEnd(15)).join(''));
+}
+function installCmd(tool) {
+    console.log(`# Install ${tool.name}\n`);
+    if (tool.install.brew)
+        console.log(`# macOS (Homebrew)\nbrew install ${tool.install.brew}\n`);
+    if (tool.install.apt)
+        console.log(`# Debian/Ubuntu\nsudo apt install ${tool.install.apt}\n`);
+    if (tool.install.npm)
+        console.log(`# npm\nnpm install -g ${tool.install.npm}\n`);
+    if (tool.install.cargo)
+        console.log(`# Cargo (Rust)\ncargo install ${tool.install.cargo}\n`);
+    if (tool.install.go)
+        console.log(`# Go\ngo install ${tool.install.go}\n`);
+    if (tool.install.binary)
+        console.log(`# Binary download\n${tool.install.binary}\n`);
+    if (tool.install.script)
+        console.log(`# Install script\n${tool.install.script}\n`);
+}
+function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === 'help' || command === '--help') {
+        console.log(`
+mcli - A CLI for discovering CLI tools
+
+Commands:
+  search <query>           Search for CLI tools
+  info <slug>              Show detailed info about a tool
+  compare <slug> [slug...] Compare multiple tools
+  install <slug>           Show install commands for a tool
+  list                     List all tools
+  categories               List all categories
+
+Filters (for search and list):
+  --min-score=N            Only show tools with agent score >= N
+  --category=NAME          Filter by category
+  --agent-friendly         Sort by agent score (highest first)
+
+Tier Badges:
+  ✓ = Verified (traced to official vendor source)
+  ○ = Community (reviewed but not vendor-verified)
+  ? = Unverified (auto-indexed, use with caution)
+
+Examples:
+  mcli search cloud
+  mcli search git --category=git
+  mcli list --agent-friendly --min-score=8
+  mcli info gh
+  mcli compare aws gcloud hcloud
+`);
+        return;
+    }
+    let registry;
+    try {
+        registry = loadRegistry(registryPath);
+    }
+    catch (err) {
+        if (err instanceof RegistryError) {
+            console.error(`Error: ${err.message}`);
+            if (err.cause) {
+                console.error(`  Caused by: ${err.cause.message}`);
+            }
+        }
+        else {
+            console.error('Unexpected error loading registry:', err);
+        }
+        process.exit(1);
+    }
+    switch (command) {
+        case 'search': {
+            // Extract query (non-flag args after command)
+            const queryParts = args.slice(1).filter(a => !a.startsWith('--'));
+            const query = queryParts.join(' ');
+            if (!query) {
+                console.log('Usage: mcli search <query> [--min-score=N] [--category=NAME]');
+                return;
+            }
+            let results = searchTools(registry, query);
+            // Apply filters
+            const minScore = parseNumericFlag(args, '--min-score');
+            if (minScore !== null) {
+                results = filterByMinScore(results, minScore);
+            }
+            const category = parseFlag(args, '--category');
+            if (category && category !== 'true') {
+                results = filterByCategory(results, category);
+            }
+            // Sort by score if requested
+            if (args.includes('--agent-friendly')) {
+                results = sortByAgentScore(results);
+            }
+            if (results.length === 0) {
+                console.log('No tools found');
+            }
+            else {
+                results.forEach(t => printTool(t));
+            }
+            break;
+        }
+        case 'info': {
+            const slug = args[1];
+            if (!slug) {
+                console.log('Usage: mcli info <slug>');
+                return;
+            }
+            const tool = findTool(registry, slug);
+            if (!tool) {
+                console.log(`Tool not found: ${slug}`);
+            }
+            else {
+                printTool(tool, true);
+            }
+            break;
+        }
+        case 'compare': {
+            const slugs = args.slice(1);
+            if (slugs.length < 2) {
+                console.log('Usage: mcli compare <slug> <slug> [slug...]');
+                return;
+            }
+            compare(registry, slugs);
+            break;
+        }
+        case 'install': {
+            const slug = args[1];
+            if (!slug) {
+                console.log('Usage: mcli install <slug>');
+                return;
+            }
+            const tool = findTool(registry, slug);
+            if (!tool) {
+                console.log(`Tool not found: ${slug}`);
+            }
+            else {
+                installCmd(tool);
+            }
+            break;
+        }
+        case 'list': {
+            let tools = [...registry.tools];
+            // Apply filters
+            const minScore = parseNumericFlag(args, '--min-score');
+            if (minScore !== null) {
+                tools = filterByMinScore(tools, minScore);
+            }
+            const category = parseFlag(args, '--category');
+            if (category && category !== 'true') {
+                tools = filterByCategory(tools, category);
+            }
+            // Sort by score if requested
+            if (args.includes('--agent-friendly')) {
+                tools = sortByAgentScore(tools);
+            }
+            if (tools.length === 0) {
+                console.log('No tools found matching filters');
+            }
+            else {
+                tools.forEach(t => printTool(t));
+            }
+            break;
+        }
+        case 'categories': {
+            const cats = getCategories(registry);
+            console.log('Categories:', cats.join(', '));
+            break;
+        }
+        default:
+            console.log(`Unknown command: ${command}\nRun 'mcli help' for usage.`);
+    }
+}
+main();

package/dist/format.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Formatting helpers for CLI output.
+ * Extracted for testability.
+ */
+import type { CliTool } from './types.js';
+/**
+ * ANSI color code for agent score.
+ */
+export declare function scoreColor(score: number): string;
+/**
+ * ANSI reset code.
+ */
+export declare function reset(): string;
+/**
+ * Format a tool's header line.
+ */
+export declare function formatToolHeader(tool: CliTool): string;
+/**
+ * Format a tool for brief display.
+ */
+export declare function formatToolBrief(tool: CliTool): string;
+/**
+ * Format a tool for detailed display.
+ */
+export declare function formatToolDetailed(tool: CliTool): string;
+/**
+ * Format a comparison table for multiple tools.
+ */
+export declare function formatCompareTable(tools: CliTool[]): string;
+/**
+ * Format install commands for a tool.
+ */
+export declare function formatInstallCommands(tool: CliTool): string;

package/dist/format.js

@@ -0,0 +1,137 @@
+import { tierBadge, compareTools } from './lib.js';
+/**
+ * ANSI color code for agent score.
+ */
+export function scoreColor(score) {
+    if (score >= 8)
+        return '\x1b[32m'; // green
+    if (score >= 5)
+        return '\x1b[33m'; // yellow
+    return '\x1b[31m'; // red
+}
+/**
+ * ANSI reset code.
+ */
+export function reset() {
+    return '\x1b[0m';
+}
+/**
+ * Format a tool's header line.
+ */
+export function formatToolHeader(tool) {
+    const badge = tierBadge(tool.tier);
+    const color = scoreColor(tool.agentScore);
+    return `${badge} ${tool.name} (${tool.slug}) - Agent Score: ${color}${tool.agentScore}/10${reset()}`;
+}
+/**
+ * Format a tool for brief display.
+ */
+export function formatToolBrief(tool) {
+    return `${formatToolHeader(tool)}\n  ${tool.description}`;
+}
+/**
+ * Format a tool for detailed display.
+ */
+export function formatToolDetailed(tool) {
+    const lines = [formatToolHeader(tool), `  ${tool.description}`];
+    lines.push(`  Vendor: ${tool.vendor.name} (${tool.vendor.domain})`);
+    lines.push(`  Categories: ${tool.categories.join(', ')}`);
+    lines.push(`  Install:`);
+    for (const [method, cmd] of Object.entries(tool.install)) {
+        if (cmd)
+            lines.push(`    ${method}: ${cmd}`);
+    }
+    lines.push(`  Capabilities:`);
+    lines.push(`    JSON output: ${tool.capabilities.jsonOutput ? 'yes' : 'no'}`);
+    lines.push(`    Idempotent: ${tool.capabilities.idempotent ? 'yes' : 'no'}`);
+    lines.push(`    Interactive: ${tool.capabilities.interactive ? 'yes' : 'no'}`);
+    if (tool.capabilities.auth.length > 0) {
+        lines.push(`    Auth: ${tool.capabilities.auth.join(', ')}`);
+    }
+    if (tool.repo)
+        lines.push(`  Repo: ${tool.repo}`);
+    if (tool.docs)
+        lines.push(`  Docs: ${tool.docs}`);
+    return lines.join('\n');
+}
+/**
+ * Format a comparison table for multiple tools.
+ */
+export function formatCompareTable(tools) {
+    if (tools.length === 0) {
+        return 'No tools found';
+    }
+    const rows = compareTools(tools);
+    const lines = [];
+    // Header
+    lines.push('Tool'.padEnd(20) + tools.map(t => t.slug.padEnd(15)).join(''));
+    lines.push('-'.repeat(20 + tools.length * 15));
+    // Format values
+    const formatValue = (v) => {
+        if (typeof v === 'boolean')
+            return v ? 'yes' : 'no';
+        if (v === 'verified')
+            return '✓';
+        if (v === 'community')
+            return '○';
+        if (v === 'unverified')
+            return '?';
+        return String(v);
+    };
+    for (const row of rows) {
+        const label = row.field === 'Agent Score' ? 'Agent Score' :
+            row.field === 'JSON Output' ? 'JSON Output' :
+                row.field === 'Idempotent' ? 'Idempotent' :
+                    row.field === 'Interactive' ? 'Interactive' :
+                        row.field === 'Streaming' ? 'Streaming' :
+                            row.field === 'Tier' ? 'Verified' : row.field;
+        const values = row.values.map(v => {
+            const formatted = formatValue(v);
+            return (row.field === 'Agent Score' ? `${formatted}/10` : formatted).padEnd(15);
+        }).join('');
+        lines.push(label.padEnd(20) + values);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format install commands for a tool.
+ */
+export function formatInstallCommands(tool) {
+    const lines = [`# Install ${tool.name}`, ''];
+    if (tool.install.brew) {
+        lines.push('# macOS (Homebrew)');
+        lines.push(`brew install ${tool.install.brew}`);
+        lines.push('');
+    }
+    if (tool.install.apt) {
+        lines.push('# Debian/Ubuntu');
+        lines.push(`sudo apt install ${tool.install.apt}`);
+        lines.push('');
+    }
+    if (tool.install.npm) {
+        lines.push('# npm');
+        lines.push(`npm install -g ${tool.install.npm}`);
+        lines.push('');
+    }
+    if (tool.install.cargo) {
+        lines.push('# Cargo (Rust)');
+        lines.push(`cargo install ${tool.install.cargo}`);
+        lines.push('');
+    }
+    if (tool.install.go) {
+        lines.push('# Go');
+        lines.push(`go install ${tool.install.go}`);
+        lines.push('');
+    }
+    if (tool.install.binary) {
+        lines.push('# Binary download');
+        lines.push(tool.install.binary);
+        lines.push('');
+    }
+    if (tool.install.script) {
+        lines.push('# Install script');
+        lines.push(tool.install.script);
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/lib.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Core library functions for mcli.
+ * Extracted from CLI for testability.
+ */
+import type { Registry, CliTool, AgentScores } from './types.js';
+/**
+ * Compute overall agentScore from detailed agentScores.
+ * Weighted average: json(3) + nonInteractive(3) + tokenEfficiency(2) + safety(1) + pipeline(1)
+ * Returns 1-10 scale.
+ */
+export declare function computeAgentScore(scores: AgentScores): number;
+/**
+ * Validate agentScores object.
+ */
+export declare function validateAgentScores(scores: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Search tools by query string.
+ * Matches against slug, name, description, and categories.
+ */
+export declare function searchTools(registry: Registry, query: string): CliTool[];
+/**
+ * Find a tool by exact slug match.
+ */
+export declare function findTool(registry: Registry, slug: string): CliTool | undefined;
+/**
+ * Get all unique categories from the registry.
+ */
+export declare function getCategories(registry: Registry): string[];
+/**
+ * Sort tools by agent score (descending).
+ */
+export declare function sortByAgentScore(tools: CliTool[]): CliTool[];
+/**
+ * Filter tools by minimum agent score.
+ */
+export declare function filterByMinScore(tools: CliTool[], minScore: number): CliTool[];
+/**
+ * Filter tools by category.
+ */
+export declare function filterByCategory(tools: CliTool[], category: string): CliTool[];
+/**
+ * Filter tools by verification tier.
+ */
+export declare function filterByTier(tools: CliTool[], tier: CliTool['tier']): CliTool[];
+/**
+ * Get tier badge character.
+ */
+export declare function tierBadge(tier: string): string;
+/**
+ * Validate a tool object has required fields.
+ */
+export declare function validateTool(tool: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validate entire registry.
+ */
+export declare function validateRegistry(registry: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Generate install command string for a tool and platform.
+ */
+export declare function getInstallCommand(tool: CliTool, platform: keyof CliTool['install']): string | null;
+/**
+ * Compare tools and return a comparison matrix.
+ */
+export interface ComparisonRow {
+    field: string;
+    values: (string | boolean | number)[];
+}
+export declare function compareTools(tools: CliTool[]): ComparisonRow[];