crush-commands 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# crush-commands
+
+Install Crush commands from GitHub repositories.
+
+## Installation
+
+No installation required! Just use npx:
+
+```bash
+npx crush-commands <owner>/<repo> --command <name>
+```
+
+## Usage
+
+### Install All Commands
+
+Install all commands from a repository:
+
+```bash
+npx crush-commands add <owner>/<repo>
+```
+
+Example:
+
+```bash
+npx crush-commands add myuser/my-crush-commands
+```
+
+### Install a Specific Command
+
+Install a specific command by name:
+
+```bash
+npx crush-commands <owner>/<repo> --command <name>
+```
+
+Example:
+
+```bash
+npx crush-commands myuser/my-crush-commands --command mycommand
+```
+
+### Options
+
+- `--command, -c <name>` - Install a specific command (without .md extension)
+- `--ref <branch|tag>` - Use specific branch or tag (default: default branch)
+- `--yes, -y` - Skip confirmation prompts (useful for CI/automation)
+- `--quiet, -q` - Suppress non-essential output
+- `--help, -h` - Show help message
+- `--version, -v` - Show version number
+
+### Examples
+
+Install all commands from the `main` branch:
+
+```bash
+npx crush-commands add myuser/my-crush-commands --ref main
+```
+
+Install a specific command without confirmation:
+
+```bash
+npx crush-commands myuser/my-crush-commands --command mycommand --yes
+```
+
+Install commands quietly (for scripts):
+
+```bash
+npx crush-commands add myuser/my-crush-commands --quiet
+```
+
+## How It Works
+
+1. The tool fetches the `crush/commands/` directory from the target GitHub repository
+2. It lists all `.md` files in that directory
+3. For each command file, it checks if it already exists in `~/.crush/commands`
+4. If a file exists, it asks for confirmation before overwriting (unless `--yes` is used)
+5. It writes the command files to `~/.crush/commands/<name>.md`
+
+## Repository Structure
+
+The tool expects repositories to have the following structure:
+
+```
+my-repo/
+└── crush/
+    └── commands/
+        ├── command1.md
+        ├── command2.md
+        └── command3.md
+```
+
+Each `.md` file should contain a Crush command definition.
+
+## Requirements
+
+- Node.js 18 or higher
+- Internet connection to access GitHub's public API
+- The target repository must be public and contain a `crush/commands/` directory
+
+## Limitations
+
+- Only works with public GitHub repositories
+- Only installs `.md` files from `crush/commands/` directory
+- Requires write permissions to `~/.crush/commands`
+- GitHub API rate limits apply (60 requests/hour for unauthenticated requests)
+
+## After Installation
+
+After installing commands, run:
+
+```bash
+crush reload
+```
+
+This refreshes Crush's command cache so the new commands are available.
+
+## Error Handling
+
+The tool provides helpful error messages for common issues:
+
+- **Repository not found**: Verify the repository exists and is public
+- **No commands found**: Check that the repository has a `crush/commands/` directory with `.md` files
+- **Network errors**: Check your internet connection
+- **Rate limit exceeded**: Wait before trying again
+
+## License
+
+MIT

package/bin/crush-commands.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'util';
+import chalk from 'chalk';
+import { installAllCommands, installSpecificCommand } from '../lib/installer.js';
+import { validateRepoFormat, stripMdExtension } from '../lib/utils.js';
+
+const PACKAGE_VERSION = '1.0.0';
+
+/**
+ * Parse command line arguments
+ */
+function parseCliArgs() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      command: {
+        type: 'string',
+      },
+      ref: {
+        type: 'string',
+      },
+      yes: {
+        type: 'boolean',
+        short: 'y',
+      },
+      quiet: {
+        type: 'boolean',
+        short: 'q',
+      },
+      help: {
+        type: 'boolean',
+        short: 'h',
+      },
+      version: {
+        type: 'boolean',
+        short: 'v',
+      },
+    },
+    allowPositionals: true,
+  });
+
+  return { values, positionals };
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+${chalk.bold('crush-commands')} - Install Crush commands from GitHub repositories
+
+${chalk.bold('Usage:')}
+  ${chalk.cyan('npx crush-commands add')} ${chalk.gray('<owner>/<repo>')}${chalk.dim('      ')}Install all commands
+  ${chalk.cyan('npx crush-commands')} ${chalk.gray('<owner>/<repo> --command <name>')}${chalk.dim(' ')}Install specific command
+
+${chalk.bold('Options:')}
+  ${chalk.cyan('--command, -c <name>')} ${chalk.dim('Install a specific command (without .md extension)')}
+  ${chalk.cyan('--ref <branch|tag>')} ${chalk.dim('Use specific branch or tag (default: default branch)')}
+  ${chalk.cyan('--yes, -y')}         ${chalk.dim('Skip confirmation prompts')}
+  ${chalk.cyan('--quiet, -q')}       ${chalk.dim('Suppress non-essential output')}
+  ${chalk.cyan('--help, -h')}        ${chalk.dim('Show this help message')}
+  ${chalk.cyan('--version, -v')}     ${chalk.dim('Show version number')}
+
+${chalk.bold('Examples:')}
+  ${chalk.cyan('npx crush-commands add')} ${chalk.gray('myusername/my-crush-commands')}
+  ${chalk.cyan('npx crush-commands')} ${chalk.gray('myusername/my-crush-commands --command mycommand')}
+  ${chalk.cyan('npx crush-commands')} ${chalk.gray('myusername/my-crush-commands --command mycommand --ref main')}
+
+${chalk.bold('Notes:')}
+  - Commands are installed from the ${chalk.cyan('crush/commands/')} directory in the target repository
+  - Files are installed to ${chalk.cyan('~/.crush/commands')}
+  - Only ${chalk.cyan('.md')} files are installed
+  - Run ${chalk.cyan('crush reload')} after installing to refresh commands
+`);
+}
+
+/**
+ * Show version
+ */
+function showVersion() {
+  console.log(`crush-commands v${PACKAGE_VERSION}`);
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const { values, positionals } = parseCliArgs();
+
+  // Handle --help
+  if (values.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  // Handle --version
+  if (values.version) {
+    showVersion();
+    process.exit(0);
+  }
+
+  // Check if we have the required positional argument
+  if (positionals.length === 0) {
+    console.error(chalk.red('Error: Missing repository argument'));
+    console.error('');
+    console.error('Usage: npx crush-commands <owner>/<repo> [options]');
+    console.error('   or: npx crush-commands add <owner>/<repo> [options]');
+    console.error('');
+    console.error('Run --help for more information');
+    process.exit(1);
+  }
+
+  // Check if it's the 'add' command or direct repo specification
+  let repo;
+  let command = values.command;
+
+  if (positionals[0] === 'add') {
+    if (positionals.length < 2) {
+      console.error(
+        chalk.red('Error: Missing repository after "add" command')
+      );
+      process.exit(1);
+    }
+    repo = positionals[1];
+  } else {
+    repo = positionals[0];
+  }
+
+  // Validate repo format
+  let owner, repoName;
+  try {
+    ({ owner, repo: repoName } = validateRepoFormat(repo));
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+
+  // Strip .md extension from command name if provided
+  if (command) {
+    command = stripMdExtension(command);
+  }
+
+  // Install commands
+  try {
+    let result;
+    if (command) {
+      result = await installSpecificCommand(owner, repoName, command, {
+        ref: values.ref,
+        yes: values.yes,
+        quiet: values.quiet,
+      });
+    } else {
+      result = await installAllCommands(owner, repoName, {
+        ref: values.ref,
+        yes: values.yes,
+        quiet: values.quiet,
+      });
+    }
+
+    // Exit with error if any installations failed
+    if (result.failed.length > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('');
+    console.error(chalk.red(`Error: ${error.message}`));
+    console.error('');
+    
+    // Provide helpful troubleshooting hints
+    if (error.message.includes('Not found')) {
+      console.error(chalk.yellow('Troubleshooting:'));
+      console.error('  - Verify the repository exists and is public');
+      console.error('  - Check that the repository has a crush/commands/ directory');
+      console.error('  - Ensure the repository name and owner are spelled correctly');
+    } else if (error.message.includes('Network error')) {
+      console.error(chalk.yellow('Troubleshooting:'));
+      console.error('  - Check your internet connection');
+      console.error('  - Verify GitHub is accessible');
+    } else if (error.message.includes('rate limit')) {
+      console.error(chalk.yellow('Troubleshooting:'));
+      console.error('  - GitHub API rate limit exceeded');
+      console.error('  - Wait a while before trying again');
+    }
+
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(chalk.red(`Unexpected error: ${error.message}`));
+  process.exit(1);
+});

package/lib/github.js

@@ -0,0 +1,138 @@
+import https from 'https';
+
+const GITHUB_API_BASE = 'api.github.com';
+const USER_AGENT = 'crush-commands/1.0.0';
+
+/**
+ * Fetch from GitHub API
+ */
+async function fetchGitHub(path) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: GITHUB_API_BASE,
+      path: path,
+      method: 'GET',
+      headers: {
+        'User-Agent': USER_AGENT,
+        Accept: 'application/vnd.github.v3+json',
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(new Error('Failed to parse GitHub API response'));
+          }
+        } else if (res.statusCode === 404) {
+          reject(new Error('Not found'));
+        } else if (res.statusCode === 403) {
+          reject(new Error('GitHub API rate limit exceeded'));
+        } else {
+          reject(
+            new Error(
+              `GitHub API returned status ${res.statusCode}: ${res.statusMessage}`
+            )
+          );
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Network error: ${error.message}`));
+    });
+
+    req.setTimeout(30000, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    req.end();
+  });
+}
+
+/**
+ * List all .md files in crush/commands directory
+ */
+export async function listCommandFiles(owner, repo, ref = null) {
+  let path = `/repos/${owner}/${repo}/contents/crush/commands`;
+  if (ref) {
+    path += `?ref=${encodeURIComponent(ref)}`;
+  }
+
+  try {
+    const data = await fetchGitHub(path);
+    
+    if (!Array.isArray(data)) {
+      throw new Error('Not a directory');
+    }
+
+    return data
+      .filter((item) => item.type === 'file' && item.name.endsWith('.md'))
+      .map((item) => ({
+        name: item.name,
+        path: item.path,
+        size: item.size,
+      }));
+  } catch (error) {
+    if (error.message === 'Not found') {
+      throw new Error(
+        `Could not find 'crush/commands' directory in ${owner}/${repo}. ` +
+        'Make sure the repository exists and contains a crush/commands folder.'
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch content of a specific file
+ */
+export async function fetchFileContent(owner, repo, filepath, ref = null) {
+  let path = `/repos/${owner}/${repo}/contents/${filepath}`;
+  if (ref) {
+    path += `?ref=${encodeURIComponent(ref)}`;
+  }
+
+  try {
+    const data = await fetchGitHub(path);
+
+    if (data.encoding === 'base64') {
+      return Buffer.from(data.content, 'base64').toString('utf-8');
+    }
+
+    return data.content;
+  } catch (error) {
+    if (error.message === 'Not found') {
+      throw new Error(
+        `File not found: ${filepath} in ${owner}/${repo}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Find command file by name (case-insensitive)
+ */
+export function findCommandFile(files, name) {
+  const normalizedName = name.toLowerCase();
+  return files.find(
+    (f) => f.name.toLowerCase() === `${normalizedName}.md`
+  );
+}
+
+/**
+ * Get all command names available
+ */
+export function getAvailableCommands(files) {
+  return files.map((f) => f.name.replace(/\.md$/, ''));
+}

package/lib/installer.js

@@ -0,0 +1,195 @@
+import fs from 'fs/promises';
+import chalk from 'chalk';
+import path from 'path';
+
+import {
+  listCommandFiles,
+  fetchFileContent,
+  findCommandFile,
+  getAvailableCommands,
+} from './github.js';
+import { getTargetDirectory, ensureDirectory, stripMdExtension } from './utils.js';
+import { confirmOverwrite, askOverwritePreference } from './prompts.js';
+
+/**
+ * Install all commands from a repo
+ */
+export async function installAllCommands(
+  owner,
+  repo,
+  options = {}
+) {
+  const { ref = null, yes = false, quiet = false } = options;
+
+  log(quiet, chalk.blue(`Fetching commands from ${owner}/${repo}...`));
+
+  // List all command files
+  const files = await listCommandFiles(owner, repo, ref);
+
+  if (files.length === 0) {
+    log(quiet, chalk.yellow('No command files found in crush/commands/'));
+    return { installed: [], skipped: [], failed: [] };
+  }
+
+  log(
+    quiet,
+    chalk.green(`Found ${files.length} command(s) to install`)
+  );
+
+  // Install each command
+  return installCommands(owner, repo, files.map(f => f.name), { ref, yes, quiet });
+}
+
+/**
+ * Install a specific command
+ */
+export async function installSpecificCommand(
+  owner,
+  repo,
+  commandName,
+  options = {}
+) {
+  const { ref = null, yes = false, quiet = false } = options;
+
+  log(quiet, chalk.blue(`Fetching command '${commandName}' from ${owner}/${repo}...`));
+
+  // List all command files
+  const files = await listCommandFiles(owner, repo, ref);
+
+  // Find the specific command
+  const name = stripMdExtension(commandName);
+  const file = findCommandFile(files, name);
+
+  if (!file) {
+    const available = getAvailableCommands(files);
+    throw new Error(
+      `Command '${commandName}' not found. ` +
+      (available.length > 0
+        ? `Available commands: ${available.join(', ')}`
+        : 'No commands available in this repository.')
+    );
+  }
+
+  return installCommands(owner, repo, [file.name], { ref, yes, quiet });
+}
+
+/**
+ * Install commands by file names
+ */
+async function installCommands(
+  owner,
+  repo,
+  fileNames,
+  options = {}
+) {
+  const { ref = null, yes = false, quiet = false } = options;
+  const targetDir = getTargetDirectory();
+
+  await ensureDirectory(targetDir);
+
+  const installed = [];
+  const skipped = [];
+  const failed = [];
+
+  let overwritePreference = null;
+  let yesToAll = yes;
+  let noToAll = false;
+
+  // Check for existing files
+  const existingFiles = [];
+  for (const fileName of fileNames) {
+    const commandName = fileName.replace(/\.md$/, '');
+    const targetPath = path.join(targetDir, fileName);
+    try {
+      await fs.access(targetPath);
+      existingFiles.push(commandName);
+    } catch {
+      // File doesn't exist, that's fine
+    }
+  }
+
+  // Ask about overwrites if needed
+  if (existingFiles.length > 0 && !yes) {
+    overwritePreference = await askOverwritePreference(existingFiles.length);
+    if (overwritePreference === 'all') {
+      yesToAll = true;
+    } else if (overwritePreference === 'none') {
+      noToAll = true;
+    }
+  }
+
+  // Install each command
+  for (const fileName of fileNames) {
+    const commandName = fileName.replace(/\.md$/, '');
+    const targetPath = path.join(targetDir, fileName);
+    const sourcePath = `crush/commands/${fileName}`;
+
+    try {
+      // Check if file exists
+      try {
+        await fs.access(targetPath);
+        if (noToAll) {
+          log(quiet, chalk.gray(`  Skipped ${commandName} (already exists)`));
+          skipped.push(commandName);
+          continue;
+        }
+        if (!yesToAll) {
+          const shouldOverwrite = await confirmOverwrite(
+            commandName,
+            yesToAll,
+            noToAll
+          );
+          if (!shouldOverwrite) {
+            log(quiet, chalk.gray(`  Skipped ${commandName}`));
+            skipped.push(commandName);
+            continue;
+          }
+        }
+      } catch {
+        // File doesn't exist, that's fine
+      }
+
+      // Fetch content
+      const content = await fetchFileContent(owner, repo, sourcePath, ref);
+
+      // Write file
+      await fs.writeFile(targetPath, content, 'utf-8');
+
+      log(quiet, chalk.green(`  ✓ Installed ${commandName}`));
+      installed.push(commandName);
+    } catch (error) {
+      log(quiet, chalk.red(`  ✗ Failed to install ${commandName}: ${error.message}`));
+      failed.push({ command: commandName, error: error.message });
+    }
+  }
+
+  // Print summary
+  if (!quiet) {
+    console.log('');
+    if (installed.length > 0) {
+      console.log(chalk.green(`Installed ${installed.length} command(s):`));
+      installed.forEach((name) => console.log(`  - ${name}`));
+    }
+    if (skipped.length > 0) {
+      console.log(chalk.yellow(`Skipped ${skipped.length} command(s):`));
+      skipped.forEach((name) => console.log(`  - ${name}`));
+    }
+    if (failed.length > 0) {
+      console.log(chalk.red(`Failed to install ${failed.length} command(s):`));
+      failed.forEach(({ command, error }) => console.log(`  - ${command}: ${error}`));
+    }
+    if (installed.length > 0) {
+      console.log('');
+      console.log(chalk.blue('Next steps:'));
+      console.log('  Run `crush reload` to refresh your commands');
+    }
+  }
+
+  return { installed, skipped, failed };
+}
+
+function log(quiet, message) {
+  if (!quiet) {
+    console.log(message);
+  }
+}

package/lib/prompts.js

@@ -0,0 +1,44 @@
+import inquirer from 'inquirer';
+
+/**
+ * Ask user for confirmation to overwrite a file
+ */
+export async function confirmOverwrite(commandName, yesToAll, noToAll) {
+  if (yesToAll) {
+    return true;
+  }
+  if (noToAll) {
+    return false;
+  }
+
+  const answer = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Overwrite existing command '${commandName}'?`,
+      default: false,
+    },
+  ]);
+
+  return answer.overwrite;
+}
+
+/**
+ * Ask user for overwrite preference (yes, no, yes to all, no to all)
+ */
+export async function askOverwritePreference(fileCount) {
+  const answer = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'preference',
+      message: `${fileCount} command(s) already exist. How would you like to proceed?`,
+      choices: [
+        { name: 'Ask for each file individually', value: 'ask' },
+        { name: 'Overwrite all', value: 'all' },
+        { name: 'Skip all', value: 'none' },
+      ],
+    },
+  ]);
+
+  return answer.preference;
+}

package/lib/utils.js

@@ -0,0 +1,64 @@
+import os from 'os';
+import path from 'path';
+
+/**
+ * Expand ~ to user home directory
+ */
+export function expandHome(filepath) {
+  if (filepath.startsWith('~')) {
+    return path.join(os.homedir(), filepath.slice(1));
+  }
+  return filepath;
+}
+
+/**
+ * Get default target directory for commands
+ */
+export function getTargetDirectory() {
+  return expandHome('~/.crush/commands');
+}
+
+/**
+ * Validate repository format (owner/repo)
+ */
+export function validateRepoFormat(repo) {
+  const parts = repo.split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(
+      'Invalid repository format. Expected format: <owner>/<repo>'
+    );
+  }
+  return { owner: parts[0], repo: parts[1] };
+}
+
+/**
+ * Strip .md extension from command name
+ */
+export function stripMdExtension(name) {
+  if (name.toLowerCase().endsWith('.md')) {
+    return name.slice(0, -3);
+  }
+  return name;
+}
+
+/**
+ * Check if file exists (basic check)
+ */
+export async function fileExists(filepath) {
+  try {
+    await import('fs').then((fs) =>
+      fs.promises.access(filepath, fs.constants.F_OK)
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure directory exists, create if not
+ */
+export async function ensureDirectory(dirpath) {
+  const fs = await import('fs');
+  await fs.promises.mkdir(dirpath, { recursive: true });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "crush-commands",
+  "version": "1.0.0",
+  "description": "Install Crush commands from GitHub repositories",
+  "main": "lib/installer.js",
+  "bin": {
+    "crush-commands": "./bin/crush-commands.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "crush",
+    "commands",
+    "github",
+    "installer",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.12",
+    "user": "^0.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "prettier": "^3.1.1"
+  }
+}

package/tasks/prd-github-installer.md

@@ -0,0 +1,243 @@
+# PRD: Crush Commands Installer
+
+## Introduction
+
+A Node.js CLI library called `crush-commands` that can be invoked via `npx` to install Crush command documentation files from a GitHub repository into `~/.crush/commands`. The tool provides a simple interface to either install all commands from a repo or install a specific command by name. Files are sourced from the `crush/commands/` directory in the target repository.
+
+## Goals
+
+- Enable installing all Crush commands from a repo via `npx crush-commands add <owner>/<repo>`
+- Enable installing a specific command via `npx crush-commands <owner>/<repo> --command <name>`
+- Provide a frictionless experience for extending Crush with custom commands
+- Ensure safe file installation with confirmation before overwriting
+- Source command files from `crush/commands/` directory in target repo
+- Deliver clear, helpful error messages with troubleshooting guidance
+- Require zero configuration for basic use cases
+
+## User Stories
+
+### US-001: Parse CLI arguments and commands
+
+**Description:** As a user, I want to use a simple CLI format so that I can easily install commands.
+
+**Acceptance Criteria:**
+
+- [ ] Support `npx crush-commands add <owner>/<repo>` to install all commands
+- [ ] Support `npx crush-commands <owner>/<repo> --command <name>` to install specific command
+- [ ] Validate repo format (owner/repo)
+- [ ] Show help message with `--help` flag
+- [ ] Show version with `--version` flag
+- [ ] Validate required arguments and provide clear error if missing
+- [ ] Validate <name> doesn't include .md extension (strip if provided)
+- [ ] Typecheck passes
+
+### US-002: Fetch crush/commands directory from GitHub API
+
+**Description:** As a system, I need to list all .md files in the crush/commands directory so that I can find command files.
+
+**Acceptance Criteria:**
+
+- [ ] Use GitHub REST API to fetch directory listing for `crush/commands/`
+- [ ] Handle both default branch and specific branch/tag references (via optional `--ref` flag)
+- [ ] Parse GitHub API response to extract file list
+- [ ] Filter to only .md files
+- [ ] Handle 404 errors if repo or directory doesn't exist
+- [ ] Follow API rate limiting with proper error handling
+- [ ] Handle 404 gracefully if crush/commands/ doesn't exist with helpful message
+- [ ] Typecheck passes
+
+### US-003: Resolve command files to install
+
+**Description:** As a system, I need to determine which files to install based on the command used.
+
+**Acceptance Criteria:**
+
+- [ ] For `add` command: include all .md files in crush/commands/ directory
+- [ ] For `--command <name>`: include only crush/commands/<name>.md
+- [ ] Validate that specified command exists when using --command
+- [ ] Return ordered list of files to install with full paths
+- [ ] Handle case where no .md files found in directory
+- [ ] Show list of available commands when --command specifies invalid name
+- [ ] Typecheck passes
+
+### US-004: Fetch file content from GitHub API
+
+**Description:** As a system, I need to retrieve the actual content of each command file.
+
+**Acceptance Criteria:**
+
+- [ ] Use GitHub REST API to fetch raw content for each file
+- [ ] Handle git blob content encoding (base64, utf-8)
+- [ ] Parse content correctly with proper encoding
+- [ ] Handle fetch failures for individual files with clear error messages
+- [ ] Support fetching from specific branch/tag if --ref flag provided
+- [ ] Typecheck passes
+
+### US-005: Check for existing files and prompt for overwrite
+
+**Description:** As a user, I want to be asked before overwriting existing commands so that I don't accidentally lose customizations.
+
+**Acceptance Criteria:**
+
+- [ ] Check if target files exist in ~/.crush/commands directory
+- [ ] For each existing file, display command name and ask for confirmation
+- [ ] Support "yes", "no", "yes to all", "no to all" responses
+- [ ] Remember user's choice for remaining files
+- [ ] Show count of commands that will be overwritten
+- [ ] Allow `-y/--yes` flag to skip prompts for CI/automation
+- [ ] Typecheck passes
+
+### US-006: Write files to ~/.crush/commands
+
+**Description:** As a system, I need to write command files with proper permissions so they're usable immediately.
+
+**Acceptance Criteria:**
+
+- [ ] Create ~/.crush/commands directory if it doesn't exist
+- [ ] Write each command file to destination with proper permissions (644)
+- [ ] Use the command name (without .md) as filename: ~/.crush/commands/<name>.md
+- [ ] Show progress indicator for each command (verbose mode)
+- [ ] Handle write failures gracefully with clear error messages
+- [ ] Rollback partially installed files on critical failure
+- [ ] Typecheck passes
+
+### US-007: Display success summary and file locations
+
+**Description:** As a user, I want to see what was installed so that I can verify and use the new commands.
+
+**Acceptance Criteria:**
+
+- [ ] Show list of installed commands with their names
+- [ ] Display count of commands installed
+- [ ] Show any skipped commands and reason
+- [ ] Provide next steps (e.g., "Run `crush reload` to refresh commands")
+- [ ] Format output clearly
+- [ ] Support `--quiet` flag to suppress non-essential output
+- [ ] Typecheck passes
+
+### US-008: Handle errors with friendly messages and troubleshooting
+
+**Description:** As a user, I want helpful error messages so that I can quickly diagnose and fix issues.
+
+**Acceptance Criteria:**
+
+- [ ] Network errors: suggest checking internet connection
+- [ ] 404 errors: suggest verifying repo URL and that crush/commands/ exists
+- [ ] Rate limiting: suggest waiting and retrying
+- [ ] Permission errors: suggest checking write permissions on ~/.crush/commands
+- [ ] Invalid command name: show list of available commands
+- [ ] GitHub API errors: display error code and suggest checking if repo is public
+- [ ] Exit with appropriate error codes (0=success, 1=error)
+- [ ] Typecheck passes
+
+### US-009: Package as npx-executable Node library
+
+**Description:** As a user, I want to run the tool with `npx` without installation so that it's always available.
+
+**Acceptance Criteria:**
+
+- [ ] Package as executable npm package with proper bin entry named `crush-commands`
+- [ ] Include Node.js engine requirement in package.json
+- [ ] Set up proper file structure for npm publishing
+- [ ] Test npx execution: `npx crush-commands add owner/repo`
+- [ ] Test npx execution: `npx crush-commands owner/repo --command mycommand`
+- [ ] Include README with usage examples
+- [ ] Publish to npm registry (or provide install instructions)
+- [ ] Typecheck passes
+
+## Functional Requirements
+
+- FR-1: Parse command format: `add <owner>/<repo>` for all commands, or `<owner>/<repo> --command <name>` for specific command
+- FR-2: Validate repository format and extract owner/repo components
+- FR-3: Fetch directory listing from GitHub API for `crush/commands/` path in target repo
+- FR-4: Parse GitHub API response to extract all .md files from the directory
+- FR-5: When `add` command is used: include all .md files from crush/commands/
+- FR-6: When `--command <name>` flag is used: include only crush/commands/<name>.md
+- FR-7: Strip .md extension from command name if user provides it
+- FR-8: Validate that specified command exists when using --command flag
+- FR-9: Fetch raw content of each file from GitHub API
+- FR-10: Decode file content properly (handle base64 and utf-8 encodings)
+- FR-11: Check for existing files in ~/.crush/commands directory before writing
+- FR-12: Prompt user for confirmation before overwriting existing files
+- FR-13: Support `-y/--yes` flag to skip all prompts
+- FR-14: Create ~/.crush/commands directory if it doesn't exist
+- FR-15: Write command files to ~/.crush/commands/<name>.md with appropriate permissions (644)
+- FR-16: Display progress, success summary, and next steps to user
+- FR-17: Provide friendly error messages with troubleshooting hints for all error cases
+- FR-18: Exit with appropriate error codes (0 for success, non-zero for errors)
+- FR-19: Support optional `--ref` flag to specify branch or tag (defaults to default branch)
+- FR-20: Support `--help` and `--version` flags
+- FR-21: Support `--quiet` flag to suppress non-essential output
+
+## Non-Goals
+
+- No support for private GitHub repositories (requires authentication tokens)
+- No support for installing files outside of crush/commands/ directory
+- No support for installing non-.md files
+- No support for glob patterns or wildcards (must use specific command names or "add" for all)
+- No support for other version control systems (GitLab, Bitbucket, etc.)
+- No web UI or interactive prompts beyond overwrite confirmation
+- No background monitoring or auto-update capabilities
+- No command execution or testing of installed commands
+- No support for installing commands from local directories
+- No command aliasing or renaming during installation
+
+## Design Considerations
+
+- **CLI UX**: Follow common CLI conventions (flags, help text, exit codes)
+- **User feedback**: Provide clear, human-readable messages at each step
+- **Error recovery**: Continue installation if non-critical errors occur (e.g., skip one file, continue with others)
+- **Progress indication**: Show what's happening during installation (especially for multiple files)
+- **Backward compatibility**: Ensure default target directory (`~/.crush/commands`) works even if Crush changes structure
+
+## Technical Considerations
+
+- **Dependencies**: Minimal dependencies - use Node.js built-in modules where possible
+  - Use native `https` or `fetch` (Node 18+) for HTTP requests
+  - `inquirer` or native `readline` for user prompts
+  - `chalk` for colored output (optional, enhance readability)
+- **GitHub API**: Use `https://api.github.com` endpoints
+  - Endpoint for directory listing: `GET /repos/{owner}/{repo}/contents/crush/commands/{path}`
+  - Endpoint for file content: `GET /repos/{owner}/{repo}/contents/crush/commands/{file}`
+  - Rate limit: 60 requests/hour for unauthenticated IP
+  - Support `?ref={branch|tag|sha}` parameter for specific references
+- **Target directory**: Always use `~/.crush/commands` (expand `~` to user home directory)
+- **File naming**: Strip .md extension from source files, write as `<name>.md` in destination
+- **Encoding**: All command files are markdown (UTF-8), decode base64 if API returns it
+- **Node.js version**: Target Node 18+ for native fetch support
+- **Package structure**:
+  ```
+  crush-commands/
+  ├── package.json
+  ├── README.md
+  ├── bin/
+  │   └── crush-commands.js
+  ├── lib/
+  │   ├── github.js (API client)
+  │   ├── installer.js (core logic)
+  │   ├── prompts.js (user interaction)
+  │   └── utils.js (helpers)
+  └── test/
+      ├── github.test.js
+      ├── installer.test.js
+      └── e2e.test.js
+  ```
+
+## Success Metrics
+
+- Users can install all commands with one command: `npx crush-commands add owner/repo`
+- Users can install a specific command: `npx crush-commands owner/repo --command mycommand`
+- Installation completes in under 5 seconds for typical command files
+- Error messages successfully guide users to resolution in under 2 attempts
+- Zero data loss incidents (overwrites always confirmed)
+- Works with all public GitHub repos with crush/commands/ directory
+- Command name matching is case-insensitive or matches exactly (needs decision)
+
+## Open Questions
+
+- Should command name matching be case-insensitive (e.g., `MyCommand` matches `mycommand.md`)?
+- Should we add a `--list` flag to show available commands without installing?
+- Should we support a `--dry-run` flag to preview changes without installing?
+- Should command names with spaces be supported (e.g., `--command "my command"`)?
+- Should we validate that installed .md files are valid markdown or Crush command format?
+- What's the maximum number of commands we should allow in a single `add` operation?

package/test/github.test.js

@@ -0,0 +1,56 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+import {
+  findCommandFile,
+  getAvailableCommands,
+} from '../lib/github.js';
+
+describe('github', () => {
+  describe('findCommandFile', () => {
+    const mockFiles = [
+      { name: 'command1.md', path: 'crush/commands/command1.md', size: 100 },
+      { name: 'command2.md', path: 'crush/commands/command2.md', size: 200 },
+      { name: 'MyCommand.md', path: 'crush/commands/MyCommand.md', size: 150 },
+    ];
+
+    it('should find command by name (case-insensitive)', () => {
+      const result = findCommandFile(mockFiles, 'command1');
+      assert.ok(result);
+      assert.strictEqual(result.name, 'command1.md');
+    });
+
+    it('should find command with different case', () => {
+      const result = findCommandFile(mockFiles, 'COMMAND1');
+      assert.ok(result);
+      assert.strictEqual(result.name, 'command1.md');
+    });
+
+    it('should find command with mixed case', () => {
+      const result = findCommandFile(mockFiles, 'mycommand');
+      assert.ok(result);
+      assert.strictEqual(result.name, 'MyCommand.md');
+    });
+
+    it('should return undefined for non-existent command', () => {
+      const result = findCommandFile(mockFiles, 'nonexistent');
+      assert.strictEqual(result, undefined);
+    });
+  });
+
+  describe('getAvailableCommands', () => {
+    const mockFiles = [
+      { name: 'command1.md', path: 'crush/commands/command1.md', size: 100 },
+      { name: 'command2.md', path: 'crush/commands/command2.md', size: 200 },
+    ];
+
+    it('should return command names without .md extension', () => {
+      const result = getAvailableCommands(mockFiles);
+      assert.deepStrictEqual(result, ['command1', 'command2']);
+    });
+
+    it('should return empty array for no files', () => {
+      const result = getAvailableCommands([]);
+      assert.deepStrictEqual(result, []);
+    });
+  });
+});

package/test/utils.test.js

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  expandHome,
+  getTargetDirectory,
+  validateRepoFormat,
+  stripMdExtension,
+} from '../lib/utils.js';
+
+describe('utils', () => {
+  describe('expandHome', () => {
+    it('should expand ~ to home directory', () => {
+      const result = expandHome('~/test');
+      assert.ok(result.includes('/test'));
+      assert.ok(!result.startsWith('~'));
+    });
+
+    it('should not modify paths without ~', () => {
+      const result = expandHome('/test/path');
+      assert.strictEqual(result, '/test/path');
+    });
+  });
+
+  describe('getTargetDirectory', () => {
+    it('should return ~/.crush/commands with ~ expanded', () => {
+      const result = getTargetDirectory();
+      assert.ok(result.endsWith('.crush/commands'));
+      assert.ok(!result.includes('~'));
+    });
+  });
+
+  describe('validateRepoFormat', () => {
+    it('should validate correct owner/repo format', () => {
+      const result = validateRepoFormat('owner/repo');
+      assert.deepStrictEqual(result, { owner: 'owner', repo: 'repo' });
+    });
+
+    it('should validate format with hyphens', () => {
+      const result = validateRepoFormat('my-user/my-repo');
+      assert.deepStrictEqual(result, { owner: 'my-user', repo: 'my-repo' });
+    });
+
+    it('should throw error for missing owner', () => {
+      assert.throws(() => {
+        validateRepoFormat('/repo');
+      }, /Invalid repository format/);
+    });
+
+    it('should throw error for missing repo', () => {
+      assert.throws(() => {
+        validateRepoFormat('owner/');
+      }, /Invalid repository format/);
+    });
+
+    it('should throw error for single component', () => {
+      assert.throws(() => {
+        validateRepoFormat('owner');
+      }, /Invalid repository format/);
+    });
+
+    it('should throw error for too many components', () => {
+      assert.throws(() => {
+        validateRepoFormat('owner/repo/extra');
+      }, /Invalid repository format/);
+    });
+  });
+
+  describe('stripMdExtension', () => {
+    it('should strip .md extension', () => {
+      assert.strictEqual(stripMdExtension('command.md'), 'command');
+    });
+
+    it('should not modify name without .md', () => {
+      assert.strictEqual(stripMdExtension('command'), 'command');
+    });
+
+    it('should handle uppercase .MD', () => {
+      assert.strictEqual(stripMdExtension('command.MD'), 'command');
+    });
+
+    it('should handle mixed case', () => {
+      assert.strictEqual(stripMdExtension('command.Md'), 'command');
+    });
+  });
+});