skill-search 0.0.1

package/README.md

@@ -0,0 +1,381 @@
+# Skill Search
+
+> A lightweight Node.js CLI tool for quick retrieval of skill documentation from GitHub repositories 🚀
+
+**Skill Search** is a command-line interface tool designed to help developers and users quickly access skill documentation (Markdown format) stored on GitHub, enhancing learning and reference efficiency.
+
+## ✨ Features
+
+- 🖥️ **Interactive TUI**: Modern text-based user interface with keyboard navigation
+- 🔍 **Fast Access**: Retrieve skill documentation with a single command, no browser required
+- 💾 **Smart Caching**: Local caching to reduce network requests and support offline access
+- 🎯 **Intelligent Matching**: Supports exact matching, keyword matching, and fuzzy search
+- 🎨 **Beautiful Output**: Terminal-friendly Markdown formatting and display
+- 📋 **Convenient Operations**: Support for copying to clipboard or saving to files
+- 🔧 **Flexible Configuration**: Support for multiple skill directory sources and API configurations
+
+## 📦 Installation & Development
+
+### Multi-Device Development Environment Setup (Recommended)
+
+If you sync code across multiple devices using OneDrive/Dropbox, use the following installation method to avoid `node_modules` conflicts between devices:
+
+1. **Run Setup Script** (Windows):
+   Double-click to run `scripts/setup-env.bat`
+
+   Or execute in terminal:
+   ```bash
+   .\scripts\setup-env.bat
+   ```
+   *This will create independent dependency directories based on device names in `.local/DEVICE_NAME/node_modules` and link them to the root directory.*
+
+2. **Link Command**:
+   ```bash
+   npm link
+   ```
+
+### Standard Installation
+
+```bash
+# Global installation
+npm install -g skill-search
+
+# Local development
+npm install
+npm link
+```
+
+## 🛠️ Usage Guide
+
+### 0. TUI Interactive Mode (Recommended)
+
+Launch the interactive TUI interface by running `skill` without arguments:
+
+```bash
+skill          # Launch TUI (default when no arguments provided)
+skill --tui    # Explicitly specify TUI mode
+```
+
+**Keyboard Shortcuts**:
+- `↑↓` Navigate up/down | `Tab` Switch panes | `Enter` Select
+- `/` Search | `l` List | `y` Sync | `c` Config | `q` Quit
+
+### 1. Get Skill Documentation
+
+Retrieve documentation by skill ID or keyword:
+
+```bash
+skill <keyword> [options]
+```
+
+**Examples**:
+```bash
+# Get React-related documentation
+skill react
+
+# Copy Git workflow documentation to clipboard
+skill git-workflow --copy
+
+# Save Docker documentation to local file
+skill docker -o ./docker-guide.md
+
+# Force refresh from remote (ignore cache)
+skill typescript --no-cache
+```
+
+**Options**:
+- `-c, --copy`: Copy content to clipboard
+- `-r, --raw`: Output raw Markdown content (no terminal formatting)
+- `-o, --output <file>`: Save content to specified file
+- `--no-cache`: Ignore local cache, force remote fetch
+
+### 2. Search Skills
+
+Search for skills locally:
+
+```bash
+skill search <query>
+# Alias
+skill s <query>
+```
+
+**Examples**:
+```bash
+skill search frontend
+skill s hooks
+```
+
+### 3. List All Skills
+
+Display all locally available skills:
+
+```bash
+skill list
+# Alias
+skill ls
+```
+
+### 4. Cache Management
+
+Manage local cache (stored by default in `~/.skill-search/`):
+
+```bash
+# List cached documentation
+skill cache list
+
+# Clear all cache
+skill cache clear
+```
+
+### 5. Directory Management
+
+#### Add Custom Skill Paths
+
+Add custom skill directory paths beyond the default locations:
+
+```bash
+skill add <path>
+```
+
+**Example**:
+```bash
+skill add /path/to/my/custom/skills
+```
+
+#### Remove Custom Skill Paths
+
+Remove a custom skill directory path:
+
+```bash
+skill remove <path>
+# Alias
+skill rm <path>
+```
+
+#### Set Primary Directory
+
+Configure the primary skill directory:
+
+```bash
+skill primary [directory]
+```
+
+Available directories:
+- `.skill-search` - Default Skill Search directory
+- `.claude` - Claude AI directory
+- `.codex` - OpenAI Codex directory
+- `.gemini` - Google Gemini directory
+- `.copilot` - GitHub Copilot directory
+
+**Example**:
+```bash
+skill primary claude
+```
+
+### 6. Theme Management
+
+Switch between dark and light themes in TUI mode:
+
+```bash
+skill theme [mode]
+```
+
+**Examples**:
+```bash
+skill theme dark
+skill theme light
+skill theme  # Toggle between themes
+```
+
+## ⚙️ Configuration
+
+Default API configuration is located in `src/config.js`. You can modify this file to point to your own GitHub repository:
+
+```javascript
+module.exports = {
+    api: {
+        baseUrl: 'https://skillsmp.com/api/v1',
+        // API Key should be configured by user
+    },
+    github: {
+        owner: 'your-username',     // Your GitHub username
+        repo: 'your-skills-repo',   // Your repository name
+        branch: 'main',             // Branch name
+        // ...
+    }
+};
+```
+
+### API Configuration
+
+Set up API access for remote skill search:
+
+```bash
+skill config --api-key <your-api-key>
+```
+
+## 📂 Project Structure
+
+```
+skill-search/
+├── bin/
+│   ├── skill.js            # CLI entry point
+│   └── tui.js              # TUI entry point
+├── scripts/
+│   └── setup-env.bat       # Multi-device environment setup
+├── src/
+│   ├── config.js           # Configuration management
+│   ├── api.js              # SkillsMP API client
+│   ├── store.js            # Local data storage
+│   ├── syncer.js           # Sync operations
+│   ├── cache.js            # Cache management
+│   ├── matcher.js          # Skill matching and search (Fuse.js)
+│   ├── localCrawler.js     # Local skill directory scanning
+│   ├── interactive.js      # Interactive skill selection
+│   ├── actions.js          # Action handlers (sync, move, delete)
+│   ├── utils.js            # Utility functions (Markdown rendering, clipboard)
+│   ├── theme.js            # Theme management
+│   └── tui/                # TUI components
+│       ├── App.js          # Main TUI application
+│       ├── SearchView.js   # Search interface
+│       ├── SyncView.js     # Sync management
+│       ├── ConfigView.js   # Configuration interface
+│       ├── ThemeView.js    # Theme selection
+│       ├── PrimaryView.js  # Primary directory selection
+│       ├── AddDelView.js   # Custom path management
+│       ├── ActionModal.js  # Action confirmation modal
+│       └── ...             # Other UI components
+├── package.json
+└── README.md
+```
+
+## 🔄 Sync Operations
+
+### Local Sync
+
+Sync locally discovered skills to the primary directory:
+
+```bash
+skill sync --docs
+```
+
+### Remote Sync
+
+Download all remote skills to the primary directory:
+
+```bash
+skill sync --full
+```
+
+### Sync Specific Skill
+
+Sync only a specific skill:
+
+```bash
+skill sync --id <skill-id>
+```
+
+### Full Sync
+
+Sync both local and remote skills:
+
+```bash
+skill sync --force
+```
+
+### Sync Status
+
+Check sync status and history:
+
+```bash
+skill sync --status
+```
+
+## 🎨 TUI Interface
+
+The Text User Interface provides a modern, keyboard-driven experience:
+
+- **Dual-Pane Layout**: Local and remote skill results side by side
+- **Keyboard Navigation**: Arrow keys, Tab, and shortcuts for efficient browsing
+- **Real-time Search**: Instant local search as you type
+- **Action Modals**: Context menus for sync, move, delete, and open operations
+- **Theme Support**: Dark and light themes with customizable colors
+
+### TUI Navigation
+
+- **Search**: Type to search locally, press Enter for remote search
+- **Navigation**: Tab between local/remote panes, arrows to select items
+- **Actions**: Enter to open action modal, Shift+O to open directly
+- **Pagination**: `[` and `]` for previous/next page
+- **Commands**: `/` to access command palette
+
+## 📋 Dependencies
+
+**Runtime Dependencies**:
+- `axios`: HTTP client for API requests
+- `chalk`: Terminal text styling
+- `clipboardy`: Clipboard operations
+- `commander`: CLI argument parsing
+- `fuse.js`: Fuzzy search implementation
+- `ink`: React-based terminal UI framework
+- `inquirer`: Interactive CLI prompts
+- `marked`: Markdown parser
+- `marked-terminal`: Terminal Markdown rendering
+- `ora`: Terminal spinners
+- `react`: UI framework for TUI
+
+**Development Dependencies**:
+- `eslint`: Code linting
+- `jest`: Testing framework
+- `pkg`: Binary packaging
+- `prettier`: Code formatting
+
+## 🔧 Development
+
+### Building
+
+Create executable binaries for multiple platforms:
+
+```bash
+npm run build
+```
+
+This generates binaries in the `dist/` directory for Linux, macOS, and Windows.
+
+### Testing
+
+```bash
+npm test
+```
+
+### Code Quality
+
+```bash
+# Lint code
+npx eslint src/
+
+# Format code
+npx prettier --write src/
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📝 License
+
+ISC
+
+## 🙏 Acknowledgments
+
+- Built with [Ink](https://github.com/vadimdemedes/ink) for terminal UI
+- Powered by [Fuse.js](https://fusejs.io/) for fuzzy search
+- Markdown rendering with [Marked](https://marked.js.org/)
+
+---
+
+**Happy Skill Hunting! 🎯**