@biggora/claude-plugins 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 biggora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# claude-plugins
+
+CLI marketplace for discovering, installing, and managing Claude Code plugins.
+
+## Installation
+
+```bash
+npm install -g claude-plugins
+```
+
+Or use directly with npx:
+
+```bash
+npx claude-plugins search
+```
+
+## Commands
+
+### Browse & Search
+
+```bash
+# List all available plugins
+claude-plugins search
+
+# Search by name or keyword
+claude-plugins search typescript
+claude-plugins search code-quality
+```
+
+### Install & Remove
+
+```bash
+# Install a plugin
+claude-plugins install code-optimizer
+
+# Remove a plugin
+claude-plugins uninstall code-optimizer
+```
+
+### Manage
+
+```bash
+# List installed plugins
+claude-plugins list
+
+# Show plugin details
+claude-plugins info code-optimizer
+
+# Update all plugins
+claude-plugins update
+
+# Update a specific plugin
+claude-plugins update code-optimizer
+```
+
+### Publish
+
+```bash
+# From your plugin directory
+cd my-plugin
+claude-plugins publish
+```
+
+This validates your plugin and generates a registry entry. Submit a PR to [claude-plugins-registry](https://github.com/biggora/claude-plugins-registry) to list it.
+
+## Plugin Structure
+
+Plugins must have this minimum structure:
+
+```
+my-plugin/
+  .claude-plugin/
+    plugin.json       # Required: name, version, description
+  README.md           # Required
+  commands/           # Slash commands
+  agents/             # Agent definitions
+  skills/             # Skill files
+  hooks/              # Hook definitions
+```
+
+### plugin.json
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What it does",
+  "author": { "name": "you", "url": "https://github.com/you" },
+  "repository": "https://github.com/you/my-plugin",
+  "keywords": ["keyword1", "keyword2"],
+  "license": "MIT"
+}
+```
+
+## Registry
+
+The plugin registry is hosted at [github.com/biggora/claude-plugins-registry](https://github.com/biggora/claude-plugins-registry). The CLI fetches it on demand and caches for 15 minutes.
+
+To add your plugin to the registry:
+
+1. Ensure your plugin is on GitHub
+2. Run `claude-plugins publish` to validate and generate a registry entry
+3. Submit a PR adding the entry to `registry.json`
+
+## How It Works
+
+- Plugins are installed to `~/.claude/plugins/<name>` via `git clone`
+- Updates use `git pull --ff-only`
+- Claude Code automatically discovers plugins in `~/.claude/plugins/`
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')
+);
+
+const program = new Command();
+
+program
+  .name('claude-plugins')
+  .description('CLI marketplace for Claude Code plugins')
+  .version(pkg.version);
+
+program
+  .command('search [query]')
+  .description('Search plugins by name or keyword')
+  .action(async (query) => {
+    const { search } = await import('../src/commands/search.js');
+    await search(query);
+  });
+
+program
+  .command('install <name>')
+  .description('Install a plugin from the registry')
+  .action(async (name) => {
+    const { install } = await import('../src/commands/install.js');
+    await install(name);
+  });
+
+program
+  .command('uninstall <name>')
+  .alias('remove')
+  .description('Remove an installed plugin')
+  .action(async (name) => {
+    const { uninstall } = await import('../src/commands/uninstall.js');
+    await uninstall(name);
+  });
+
+program
+  .command('list')
+  .alias('ls')
+  .description('List installed plugins')
+  .action(async () => {
+    const { list } = await import('../src/commands/list.js');
+    await list();
+  });
+
+program
+  .command('info <name>')
+  .description('Show details about a plugin')
+  .action(async (name) => {
+    const { info } = await import('../src/commands/info.js');
+    await info(name);
+  });
+
+program
+  .command('update [name]')
+  .alias('upgrade')
+  .description('Update one or all installed plugins')
+  .action(async (name) => {
+    const { update } = await import('../src/commands/update.js');
+    await update(name);
+  });
+
+program
+  .command('publish')
+  .description('Validate current directory and generate registry entry')
+  .action(async () => {
+    const { publish } = await import('../src/commands/publish.js');
+    await publish();
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@biggora/claude-plugins",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "CLI marketplace for discovering, installing, and managing Claude Code plugins",
+  "main": "src/index.js",
+  "bin": {
+    "claude-plugins": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "plugins",
+    "marketplace",
+    "cli"
+  ],
+  "author": {
+    "name": "biggora",
+    "url": "https://github.com/biggora"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/biggora/claude-plugins"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ora": "^8.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module"
+}

package/registry/registry.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "./schema.json",
+  "version": "1.0.0",
+  "updated": "2026-02-08",
+  "plugins": [
+    {
+      "name": "code-optimizer",
+      "version": "1.0.0",
+      "description": "Pragmatic code optimization plugin that finds duplicates, extracts constants, and suggests concise solutions without over-engineering",
+      "author": {
+        "name": "biggora",
+        "url": "https://github.com/biggora"
+      },
+      "repository": "https://github.com/biggora/code-optimizer",
+      "keywords": ["optimization", "refactoring", "duplicates", "constants", "code-quality"],
+      "license": "MIT",
+      "commands": ["/optimize", "/optimize-project"],
+      "category": "code-quality"
+    },
+    {
+      "name": "github-issues-solver",
+      "version": "1.0.0",
+      "description": "Analyze, investigate, and fix GitHub issues with AI assistance. Full workflow from issue to PR.",
+      "author": {
+        "name": "biggora",
+        "url": "https://github.com/biggora"
+      },
+      "repository": "https://github.com/biggora/github-issues-solver",
+      "keywords": ["github", "issues", "bug-fix", "automation", "workflow"],
+      "license": "MIT",
+      "commands": ["/gh-solve-issue", "/gh-list-issues"],
+      "category": "workflow"
+    },
+    {
+      "name": "typescript-eslint-fixer",
+      "version": "1.0.0",
+      "description": "Automatically detect and fix TypeScript type errors and ESLint violations in TypeScript/JavaScript projects",
+      "author": {
+        "name": "biggora",
+        "url": "https://github.com/biggora"
+      },
+      "repository": "https://github.com/biggora/typescript-eslint-fixer",
+      "keywords": ["typescript", "eslint", "linting", "code-quality", "auto-fix"],
+      "license": "MIT",
+      "commands": ["/fix-typescript-eslint"],
+      "category": "code-quality"
+    }
+  ]
+}

package/registry/schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Plugins Registry",
+  "type": "object",
+  "required": ["version", "plugins"],
+  "properties": {
+    "version": { "type": "string" },
+    "updated": { "type": "string", "format": "date" },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "version", "description", "repository"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$",
+            "description": "Unique plugin identifier (lowercase, hyphens only)"
+          },
+          "version": { "type": "string" },
+          "description": { "type": "string", "maxLength": 200 },
+          "author": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "url": { "type": "string", "format": "uri" }
+            },
+            "required": ["name"]
+          },
+          "repository": { "type": "string", "format": "uri" },
+          "keywords": {
+            "type": "array",
+            "items": { "type": "string" },
+            "maxItems": 10
+          },
+          "license": { "type": "string" },
+          "commands": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "category": {
+            "type": "string",
+            "enum": ["code-quality", "workflow", "testing", "documentation", "security", "devops", "other"]
+          }
+        }
+      }
+    }
+  }
+}

package/src/commands/info.js

@@ -0,0 +1,45 @@
+import chalk from 'chalk';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginsDir } from '../config.js';
+import { fetchRegistry, findPlugin } from '../registry.js';
+import { log } from '../utils.js';
+
+export async function info(name) {
+  const registry = await fetchRegistry();
+  const plugin = findPlugin(registry, name);
+
+  if (!plugin) {
+    log.error(`Plugin "${name}" not found in registry`);
+    process.exit(1);
+  }
+
+  const installed = existsSync(join(getPluginsDir(), plugin.name));
+
+  console.log();
+  console.log(chalk.bold.cyan(`  ${plugin.name}`) + chalk.dim(` v${plugin.version}`));
+  console.log();
+  console.log(`  ${plugin.description}`);
+  console.log();
+
+  const fields = [
+    ['Author', plugin.author?.name || '-'],
+    ['License', plugin.license || '-'],
+    ['Category', plugin.category || '-'],
+    ['Repository', plugin.repository || '-'],
+    ['Keywords', (plugin.keywords || []).join(', ') || '-'],
+    ['Commands', (plugin.commands || []).join(', ') || '-'],
+    ['Installed', installed ? chalk.green('yes') : chalk.dim('no')],
+  ];
+
+  for (const [label, value] of fields) {
+    console.log(`  ${chalk.dim(label.padEnd(12))} ${value}`);
+  }
+
+  console.log();
+
+  if (!installed) {
+    log.dim(`  Run "claude-plugins install ${plugin.name}" to install`);
+    console.log();
+  }
+}

package/src/commands/install.js

@@ -0,0 +1,48 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginsDir } from '../config.js';
+import { fetchRegistry, findPlugin } from '../registry.js';
+import { log, spinner } from '../utils.js';
+
+export async function install(name) {
+  const registry = await fetchRegistry();
+  const plugin = findPlugin(registry, name);
+
+  if (!plugin) {
+    log.error(`Plugin "${name}" not found in registry`);
+    log.dim('Run "claude-plugins search <query>" to find plugins');
+    process.exit(1);
+  }
+
+  const pluginsDir = getPluginsDir();
+  const dest = join(pluginsDir, plugin.name);
+
+  if (existsSync(dest)) {
+    log.warn(`Plugin "${plugin.name}" is already installed at ${dest}`);
+    log.dim('Run "claude-plugins update ' + plugin.name + '" to update it');
+    return;
+  }
+
+  const spin = spinner(`Installing ${plugin.name}...`);
+  spin.start();
+
+  try {
+    execFileSync('git', ['clone', `${plugin.repository}.git`, dest], {
+      stdio: 'pipe',
+    });
+    spin.succeed(`Installed ${plugin.name} v${plugin.version}`);
+    log.dim(`  ${dest}`);
+    log.dim(`  ${plugin.description}`);
+
+    if (plugin.commands?.length) {
+      log.info(`Commands: ${plugin.commands.join(', ')}`);
+    }
+
+    log.dim('\nRestart Claude Code to load the plugin.');
+  } catch (err) {
+    spin.fail(`Failed to install ${plugin.name}`);
+    log.error(err.message);
+    process.exit(1);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,42 @@
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getPluginsDir } from '../config.js';
+import { log, formatTable, truncate } from '../utils.js';
+
+export async function list() {
+  const pluginsDir = getPluginsDir();
+  const entries = readdirSync(pluginsDir, { withFileTypes: true }).filter(
+    (e) => e.isDirectory()
+  );
+
+  if (!entries.length) {
+    log.info('No plugins installed');
+    log.dim('Run "claude-plugins search" to browse available plugins');
+    return;
+  }
+
+  console.log(chalk.bold(`\n  ${entries.length} plugin${entries.length === 1 ? '' : 's'} installed\n`));
+
+  const rows = entries.map((entry) => {
+    const dir = join(pluginsDir, entry.name);
+    const manifestPath = join(dir, '.claude-plugin', 'plugin.json');
+    let version = '-';
+    let description = '';
+
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        version = manifest.version || '-';
+        description = manifest.description || '';
+      } catch {
+        // ignore parse errors
+      }
+    }
+
+    return [entry.name, truncate(description, 55), version];
+  });
+
+  formatTable(rows, ['Name', 'Description', 'Version']);
+  console.log();
+}

package/src/commands/publish.js

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { log } from '../utils.js';
+
+const REQUIRED_FILES = [
+  '.claude-plugin/plugin.json',
+  'README.md',
+];
+
+export async function publish() {
+  const cwd = process.cwd();
+  const errors = [];
+  const warnings = [];
+
+  // Check required files
+  for (const file of REQUIRED_FILES) {
+    if (!existsSync(join(cwd, file))) {
+      errors.push(`Missing required file: ${file}`);
+    }
+  }
+
+  if (errors.length) {
+    log.error('Plugin validation failed:\n');
+    errors.forEach((e) => console.log(chalk.red(`  - ${e}`)));
+    console.log();
+    process.exit(1);
+  }
+
+  // Read and validate plugin.json
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      readFileSync(join(cwd, '.claude-plugin/plugin.json'), 'utf-8')
+    );
+  } catch (err) {
+    log.error('Invalid plugin.json: ' + err.message);
+    process.exit(1);
+  }
+
+  const required = ['name', 'version', 'description'];
+  for (const field of required) {
+    if (!manifest[field]) {
+      errors.push(`plugin.json missing required field: "${field}"`);
+    }
+  }
+
+  if (!/^[a-z0-9-]+$/.test(manifest.name || '')) {
+    errors.push('plugin.json "name" must be lowercase with hyphens only');
+  }
+
+  // Check for recommended fields
+  if (!manifest.repository) {
+    warnings.push('plugin.json missing "repository" field');
+  }
+  if (!manifest.keywords?.length) {
+    warnings.push('plugin.json missing "keywords" - helps with search');
+  }
+  if (!manifest.license) {
+    warnings.push('plugin.json missing "license" field');
+  }
+
+  // Check for git remote
+  let repoUrl = manifest.repository || '';
+  if (!repoUrl) {
+    try {
+      repoUrl = execFileSync('git', ['remote', 'get-url', 'origin'], {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+      }).trim();
+    } catch {
+      warnings.push('No git remote found - you will need a GitHub repository');
+    }
+  }
+
+  if (errors.length) {
+    log.error('Plugin validation failed:\n');
+    errors.forEach((e) => console.log(chalk.red(`  - ${e}`)));
+    console.log();
+    process.exit(1);
+  }
+
+  // Output result
+  console.log();
+  log.success('Plugin validation passed!\n');
+
+  if (warnings.length) {
+    warnings.forEach((w) => log.warn(w));
+    console.log();
+  }
+
+  console.log(chalk.bold('  Plugin Details:\n'));
+  console.log(`  ${chalk.dim('Name')}         ${manifest.name}`);
+  console.log(`  ${chalk.dim('Version')}      ${manifest.version}`);
+  console.log(`  ${chalk.dim('Description')}  ${manifest.description}`);
+  if (repoUrl) {
+    console.log(`  ${chalk.dim('Repository')}   ${repoUrl}`);
+  }
+  console.log();
+
+  // Generate registry entry
+  const entry = {
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    author: manifest.author || { name: 'unknown' },
+    repository: repoUrl.replace(/\.git$/, ''),
+    keywords: manifest.keywords || [],
+    license: manifest.license || 'MIT',
+    commands: manifest.commands || [],
+    category: manifest.category || 'other',
+  };
+
+  console.log(chalk.bold('  Registry entry (add to registry.json):\n'));
+  console.log(chalk.dim('  ' + JSON.stringify(entry, null, 2).split('\n').join('\n  ')));
+  console.log();
+  log.info(
+    'To publish, submit a PR to:\n  https://github.com/biggora/claude-plugins-registry'
+  );
+  log.dim('  Add the entry above to the "plugins" array in registry.json');
+  console.log();
+}

package/src/commands/search.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginsDir } from '../config.js';
+import { fetchRegistry, searchPlugins } from '../registry.js';
+import { log, formatTable, truncate } from '../utils.js';
+
+export async function search(query) {
+  const registry = await fetchRegistry();
+  const results = query
+    ? searchPlugins(registry, query)
+    : registry.plugins;
+
+  if (!results.length) {
+    log.warn(`No plugins found for "${query}"`);
+    return;
+  }
+
+  const pluginsDir = getPluginsDir();
+
+  console.log(
+    chalk.bold(`\n  ${results.length} plugin${results.length === 1 ? '' : 's'} found\n`)
+  );
+
+  const rows = results.map((p) => {
+    const installed = existsSync(join(pluginsDir, p.name));
+    const status = installed ? chalk.green('installed') : '';
+    return [p.name, truncate(p.description, 55), p.version, status];
+  });
+
+  formatTable(rows, ['Name', 'Description', 'Version', 'Status']);
+  console.log();
+}

package/src/commands/uninstall.js

@@ -0,0 +1,27 @@
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginsDir } from '../config.js';
+import { log, spinner } from '../utils.js';
+
+export async function uninstall(name) {
+  const dest = join(getPluginsDir(), name);
+
+  if (!existsSync(dest)) {
+    log.error(`Plugin "${name}" is not installed`);
+    log.dim('Run "claude-plugins list" to see installed plugins');
+    process.exit(1);
+  }
+
+  const spin = spinner(`Uninstalling ${name}...`);
+  spin.start();
+
+  try {
+    rmSync(dest, { recursive: true, force: true });
+    spin.succeed(`Uninstalled ${name}`);
+    log.dim('Restart Claude Code to apply changes.');
+  } catch (err) {
+    spin.fail(`Failed to uninstall ${name}`);
+    log.error(err.message);
+    process.exit(1);
+  }
+}

package/src/commands/update.js

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginsDir } from '../config.js';
+import { log, spinner } from '../utils.js';
+
+function updateOne(name, pluginsDir) {
+  const dest = join(pluginsDir, name);
+
+  if (!existsSync(dest)) {
+    log.error(`Plugin "${name}" is not installed`);
+    return false;
+  }
+
+  const gitDir = join(dest, '.git');
+  if (!existsSync(gitDir)) {
+    log.warn(`Plugin "${name}" was not installed via git, skipping`);
+    return false;
+  }
+
+  const spin = spinner(`Updating ${name}...`);
+  spin.start();
+
+  try {
+    const output = execFileSync('git', ['pull', '--ff-only'], {
+      cwd: dest,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+
+    if (output.includes('Already up to date')) {
+      spin.info(`${name} is already up to date`);
+    } else {
+      spin.succeed(`Updated ${name}`);
+    }
+    return true;
+  } catch (err) {
+    spin.fail(`Failed to update ${name}`);
+    log.error(err.message);
+    return false;
+  }
+}
+
+export async function update(name) {
+  const pluginsDir = getPluginsDir();
+
+  if (name) {
+    updateOne(name, pluginsDir);
+    return;
+  }
+
+  // Update all installed plugins
+  const entries = readdirSync(pluginsDir, { withFileTypes: true }).filter(
+    (e) => e.isDirectory()
+  );
+
+  if (!entries.length) {
+    log.info('No plugins installed');
+    return;
+  }
+
+  log.info(`Updating ${entries.length} plugin${entries.length === 1 ? '' : 's'}...\n`);
+
+  let updated = 0;
+  for (const entry of entries) {
+    if (updateOne(entry.name, pluginsDir)) updated++;
+  }
+
+  console.log();
+  log.success(`${updated}/${entries.length} plugins updated`);
+  log.dim('Restart Claude Code to apply changes.');
+}

package/src/config.js

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+
+const home = homedir();
+const isWindows = process.platform === 'win32';
+
+export const PLUGINS_DIR = join(home, '.claude', 'plugins');
+export const CACHE_DIR = join(home, '.claude', '.cache', 'claude-plugins');
+export const CACHE_TTL = 1000 * 60 * 15; // 15 minutes
+export const REGISTRY_URL =
+  'https://raw.githubusercontent.com/biggora/claude-plugins-registry/main/registry/registry.json';
+
+export function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+export function getPluginsDir() {
+  return ensureDir(PLUGINS_DIR);
+}
+
+export function getCacheDir() {
+  return ensureDir(CACHE_DIR);
+}

package/src/registry.js

@@ -0,0 +1,67 @@
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCacheDir, CACHE_TTL, REGISTRY_URL } from './config.js';
+import { log } from './utils.js';
+
+const CACHE_FILE = 'registry.json';
+
+function getCachePath() {
+  return join(getCacheDir(), CACHE_FILE);
+}
+
+function isCacheValid() {
+  const cachePath = getCachePath();
+  if (!existsSync(cachePath)) return false;
+  const stat = statSync(cachePath);
+  return Date.now() - stat.mtimeMs < CACHE_TTL;
+}
+
+export async function fetchRegistry({ force = false } = {}) {
+  const cachePath = getCachePath();
+
+  if (!force && isCacheValid()) {
+    try {
+      return JSON.parse(readFileSync(cachePath, 'utf-8'));
+    } catch {
+      // Cache corrupted, refetch
+    }
+  }
+
+  const res = await fetch(REGISTRY_URL);
+  if (!res.ok) {
+    // Fall back to cache if available
+    if (existsSync(cachePath)) {
+      log.warn('Could not fetch registry, using cached version');
+      return JSON.parse(readFileSync(cachePath, 'utf-8'));
+    }
+    // Fall back to bundled registry
+    const bundledPath = new URL('../registry/registry.json', import.meta.url);
+    log.warn('Could not fetch registry, using bundled version');
+    return JSON.parse(readFileSync(bundledPath, 'utf-8'));
+  }
+
+  const data = await res.json();
+  writeFileSync(cachePath, JSON.stringify(data, null, 2));
+  return data;
+}
+
+export function searchPlugins(registry, query) {
+  const q = query.toLowerCase();
+  return registry.plugins.filter((p) => {
+    const haystack = [
+      p.name,
+      p.description,
+      ...(p.keywords || []),
+      p.author?.name || '',
+    ]
+      .join(' ')
+      .toLowerCase();
+    return haystack.includes(q);
+  });
+}
+
+export function findPlugin(registry, name) {
+  return registry.plugins.find(
+    (p) => p.name.toLowerCase() === name.toLowerCase()
+  );
+}

package/src/utils.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import ora from 'ora';
+
+export const log = {
+  info: (msg) => console.log(chalk.blue('i'), msg),
+  success: (msg) => console.log(chalk.green('\u2713'), msg),
+  warn: (msg) => console.log(chalk.yellow('!'), msg),
+  error: (msg) => console.error(chalk.red('\u2717'), msg),
+  dim: (msg) => console.log(chalk.dim(msg)),
+};
+
+export function spinner(text) {
+  return ora({ text, color: 'cyan' });
+}
+
+export function formatTable(rows, headers) {
+  const cols = headers.length;
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => String(r[i] || '').length))
+  );
+
+  const sep = widths.map((w) => '-'.repeat(w)).join('--+-');
+  const formatRow = (row) =>
+    row.map((cell, i) => String(cell || '').padEnd(widths[i])).join('  | ');
+
+  console.log(chalk.bold(formatRow(headers)));
+  console.log(chalk.dim(sep));
+  rows.forEach((row) => console.log(formatRow(row)));
+}
+
+export function truncate(str, len = 60) {
+  if (!str) return '';
+  return str.length > len ? str.slice(0, len - 3) + '...' : str;
+}