@raketa-cloud/cli 1.1.0

package/CLAUDE.md

@@ -0,0 +1,248 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Local Development Setup
+```bash
+npm install              # Install dependencies
+npm link                 # Link CLI globally to use local version
+raketa-cli --help        # Test the CLI
+npm unlink -g @raketa-cloud/cli  # Unlink when done
+```
+
+After `npm link`, the `raketa-cli` command uses your local development version. Changes to source files are immediately available.
+
+### Testing Commands
+There is no test suite currently. Manual testing is done by running commands:
+```bash
+raketa-cli widgets list
+raketa-cli skills list-all
+raketa-cli commands list
+```
+
+### No Build/Compilation
+This project uses ES modules directly with no build step. Changes are immediately available after saving.
+
+## Architecture Overview
+
+### Command Registration Flow
+
+The CLI is built on Commander.js with a factory pattern for command namespaces:
+
+```
+src/index.js (entry point)
+  ├── createWidgetsCommand() → returns widgets namespace
+  ├── createSkillsCommand() → returns skills namespace
+  └── createCommandsCommand() → returns commands namespace
+```
+
+Each namespace factory (e.g., `createWidgetsCommand()`) is defined in its own directory and registers multiple sub-commands.
+
+### Command Implementation Pattern
+
+All commands follow this structure:
+
+1. **Command Class** - Extends base `Command` class from `src/lib/Command.js`
+2. **Single Process Method** - Async `process()` method is the entry point
+3. **Error Handling** - Try/catch with `console.error()` and `process.exit(1)`
+4. **Options Access** - Use `this.getOptions()` to access CLI flags/arguments
+5. **Path Resolution** - Use `this.getCWD()` to get current working directory
+
+Example structure:
+```javascript
+import { Command } from '../../../lib/Command.js';
+
+export class MyCommand extends Command {
+  async process() {
+    try {
+      const cwd = this.getCWD();
+      const options = this.getOptions();
+      // Implementation here
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  }
+}
+```
+
+### Adding a New Command
+
+To add a new sub-command to an existing namespace:
+
+1. Create directory: `src/commands/<namespace>/<command>/index.js`
+2. Create command class extending `Command` with `async process()` method
+3. Register in namespace file: `src/commands/<namespace>/index.js`
+4. Add to namespace using Commander's `.command()` and `.action()` pattern
+
+Example registration:
+```javascript
+widgets
+  .command('my-command')
+  .description('What this command does')
+  .option('--name <value>', 'Option description')
+  .action(async (options) => {
+    const command = new MyCommand(options);
+    await command.process();
+  });
+```
+
+### Path Resolution Patterns
+
+Three common patterns used throughout the codebase:
+
+1. **Project-relative paths** (from where command is run):
+```javascript
+const cwd = this.getCWD();  // process.cwd()
+const widgetsPath = join(cwd, 'src', 'components', 'widgets');
+const skillsPath = join(cwd, '.claude', 'skills');
+```
+
+2. **Home directory paths** (for global resources):
+```javascript
+import { homedir } from 'os';
+const globalSkillsPath = join(homedir(), '.claude', 'skills');
+const cachePath = join(homedir(), '.claude', 'cache', 'remote-skills');
+```
+
+3. **Relative to source file** (for discovery):
+```javascript
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const currentFile = fileURLToPath(import.meta.url);
+const commandsDir = join(dirname(currentFile), '..', '..');
+```
+
+### Skills System Architecture
+
+The skills system manages Claude AI agent capabilities with dual scope (local and global):
+
+**Data Flow:**
+```
+Remote Repo (GitHub)
+  ↓ git clone/pull
+Cache (~/.claude/cache/remote-skills/)
+  ↓ copy
+Local (./.claude/skills/) OR Global (~/.claude/skills/)
+```
+
+**Key Components:**
+- `src/lib/skillsUtils.js` - Shared utilities for skills management
+- Remote repository: `git@github.com:studioraketa/claude-skills.git`
+- SKILL.md format: YAML frontmatter with `name` and `description` fields
+
+**Local vs Global:**
+- Local skills: `.claude/skills/` (project-specific)
+- Global skills: `~/.claude/skills/` (system-wide)
+- Each has separate install/remove commands
+- `list-all` shows both with section headers
+
+### File Operations
+
+Uses modern `fs/promises` API throughout:
+- `readdir(path, { withFileTypes: true })` - List directories
+- `access(path)` - Check existence
+- `mkdir(path, { recursive: true })` - Create directories
+- `writeFile(path, content, 'utf-8')` - Write files
+- `cp(source, dest, { recursive: true })` - Copy directories
+- `rm(path, { recursive: true, force: true })` - Delete directories
+
+Templates are embedded as template literals in command files, not stored as separate files.
+
+### Error Handling Guidelines
+
+**Validation Errors:**
+```javascript
+if (!options.name) {
+  console.error('Error: --name option is required');
+  console.error('Usage: widgets new --name "Hero"');
+  process.exit(1);
+}
+```
+
+**File Operations:**
+```javascript
+try {
+  await access(skillPath);
+} catch {
+  console.error(`Error: Skill '${skillName}' not found`);
+  console.error(`Run 'skills list' to see available skills`);
+  process.exit(1);
+}
+```
+
+**External Integration (git operations):**
+```javascript
+// Provide specific guidance for common errors
+if (error.code === 'ENOENT') {
+  throw new Error('git is not installed. Please install git to use this command.');
+}
+if (stderr.includes('Permission denied')) {
+  throw new Error('SSH authentication failed. Ensure your SSH key is configured.');
+}
+```
+
+Always include helpful next steps in error messages.
+
+### Console Output Conventions
+
+- **Errors:** `console.error('Error: <message>')` followed by `process.exit(1)`
+- **Warnings:** `console.warn('Warning: <message>')` (non-fatal)
+- **Success:** `console.log('✓ Created ...')` with checkmark
+- **Instructions:** Multi-line with blank lines for readability
+- **Colors:** Use chalk for emphasis (cyan for names, dim for descriptions, yellow for warnings)
+
+### Shared Utilities
+
+`src/lib/skillsUtils.js` provides:
+- `parseSkillMetadata(skillMdPath)` - Extracts YAML frontmatter from SKILL.md
+- `formatSkillWithDescription(name, desc)` - Consistent colored output
+- `ensureRemoteRepo(repoUrl, cachePath)` - Clone/update remote skills repo
+- `getSkillsWithDescriptions(skillsPath)` - List skills with metadata
+- `copySkillFromCache(skillName, cachePath, destPath, overwrite)` - Install skill
+
+Use these instead of duplicating logic across commands.
+
+## Project Conventions
+
+### Naming Conventions
+- Widget names: PascalCase with "Widget" suffix (e.g., `HeroWidget`)
+- Skill names: kebab-case (e.g., `my-skill`)
+- Command names: kebab-case with namespace (e.g., `namespace.command`)
+
+### File Structure Conventions
+- Widgets: `src/components/widgets/<WidgetName>/` with 5 template files
+- Skills: `.claude/skills/<skill-name>/SKILL.md` (YAML frontmatter required)
+- Commands: `src/commands/<namespace>/<command>/index.js`
+
+### Import/Export Style
+- Use ES module syntax (`import`/`export`)
+- Named exports for command classes
+- Named exports for factory functions (`createWidgetsCommand`)
+- Use `.js` extensions in import paths (required for ES modules)
+
+## Important Context
+
+### Dependencies
+Only 3 production dependencies:
+- **commander** (v14.0.2) - CLI framework
+- **chalk** (v5.3.0) - Terminal colors
+- **js-yaml** (v4.1.0) - YAML parsing for skill metadata
+
+Keep dependencies minimal. Prefer Node.js built-ins when possible.
+
+### Git Integration
+Skills commands use git via `child_process.execFile()` with 30-second timeout. Git operations are error-tolerant:
+- Clone failures provide specific guidance (SSH, git not installed, etc.)
+- Pull failures in cache update are warnings only (cached data still usable)
+- Network errors show user-friendly messages
+
+### ES Modules
+This project uses `"type": "module"` in package.json:
+- Use `import`/`export` syntax
+- Use `import.meta.url` instead of `__dirname`
+- Use `.js` extensions in all imports
+- No CommonJS (`require`) syntax

package/README.md

@@ -0,0 +1,153 @@
+# Raketa CLI
+
+A collection of useful CLI tools for humans and coding agents.
+
+## Overview
+
+Raketa CLI is a command-line toolkit designed to streamline the creation and management of three key artifact types in your projects:
+
+- **Widgets** - React UI components
+- **Skills** - Claude AI agent capabilities and prompts
+- **Commands** - Custom CLI commands
+
+## Exploring Available Commands
+
+To see all available commands and options:
+
+```bash
+npx @raketa-cloud/cli --help
+```
+
+To get detailed help for a specific command:
+
+```bash
+npx @raketa-cloud/cli widgets --help
+npx @raketa-cloud/cli skills --help
+npx @raketa-cloud/cli commands --help
+```
+
+Each command namespace has multiple sub-commands. Use the `--help` flag to discover what's available and explore the full capabilities of the tool.
+
+## Usage Examples
+
+### Working with Widgets
+
+List all widgets in your project:
+
+```bash
+npx @raketa-cloud/cli widgets list
+```
+
+Create a new widget:
+
+```bash
+npx @raketa-cloud/cli widgets new --name MyWidget
+```
+
+### Working with Skills
+
+List all skills (local and global):
+
+```bash
+npx @raketa-cloud/cli skills list-all
+```
+
+View available skills from the remote repository:
+
+```bash
+npx @raketa-cloud/cli skills list-remote
+```
+
+Install a skill locally to your project:
+
+```bash
+npx @raketa-cloud/cli skills install my-skill-name
+```
+
+Install a skill globally for system-wide use:
+
+```bash
+npx @raketa-cloud/cli skills install-global my-skill-name
+```
+
+Create a new custom skill:
+
+```bash
+npx @raketa-cloud/cli skills new --name my-custom-skill
+```
+
+### Working with Commands
+
+List all custom commands:
+
+```bash
+npx @raketa-cloud/cli commands list
+```
+
+Create a new command:
+
+```bash
+npx @raketa-cloud/cli commands new --name "namespace.command"
+```
+
+## Local Development
+
+If you want to develop or contribute to Raketa CLI itself, follow these steps:
+
+### Setup
+
+1. Clone the repository and navigate to the project directory:
+
+```bash
+git clone <repository-url>
+cd raketa-cli
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Link the package globally to use your local version:
+
+```bash
+npm link
+```
+
+After running `npm link`, the `raketa-cli` command will use your local development version instead of the published package. Any changes you make to the source code will be immediately available.
+
+### Testing Your Changes
+
+Run commands directly to test your changes:
+
+```bash
+raketa-cli widgets list
+raketa-cli skills --help
+```
+
+### Cleanup
+
+When you're done developing, unlink the package:
+
+```bash
+npm unlink -g @raketa-cloud/cli
+```
+
+This removes the global symlink and restores the default behavior.
+
+## Project Structure
+
+The CLI is built using Commander.js and follows a modular command structure:
+
+- `src/commands/` - Command implementations organized by namespace
+- `src/index.js` - Main entry point and command registration
+- Each command extends a base `Command` class for consistency
+
+## Contributing
+
+Contributions are welcome! Please follow the existing patterns when adding new commands or features.
+
+## License
+
+See LICENSE file for details.

package/bin/tmux

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+# Get the absolute path to the project root (where this script lives)
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Session name
+SESSION="raketa-cli"
+
+# Check if session already exists
+tmux has-session -t $SESSION 2>/dev/null
+
+if [ $? != 0 ]; then
+  tmux new-session -d -s $SESSION -n "ai" -c "$PROJECT_ROOT"
+  tmux send-keys -t $SESSION "claude --dangerously-skip-permissions" C-m
+
+  tmux new-window -t $SESSION -n "editor" -c "$PROJECT_ROOT"
+  tmux send-keys -t $SESSION "vim" C-m
+
+  # Create blank window in project root
+  tmux new-window -t $SESSION -c "$PROJECT_ROOT"
+
+  # Select the blank window
+  tmux select-window -t $SESSION:3
+fi
+
+# Attach to the session
+tmux attach-session -t $SESSION

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@raketa-cloud/cli",
+  "version": "1.1.0",
+  "description": "Collection of useful CLI tools for humans and coding agents. ",
+  "license": "MIT",
+  "author": "Vestimir Markov",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "raketa-cli": "./src/index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^14.0.2",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/commands/commands/index.js

@@ -0,0 +1,27 @@
+import { createCommand } from 'commander';
+import { ListCommandsCommand } from './list/index.js';
+import { NewCommandCommand } from './new/index.js';
+
+export function createCommandsCommand() {
+  const commands = createCommand('commands');
+  commands.description('Manage CLI commands');
+
+  commands
+    .command('list')
+    .description('List all commands')
+    .action(async (options) => {
+      const command = new ListCommandsCommand(options);
+      await command.process();
+    });
+
+  commands
+    .command('new')
+    .description('Create a new command')
+    .option('--name <value>', 'Command name in format "namespace.command"')
+    .action(async (options) => {
+      const command = new NewCommandCommand(options);
+      await command.process();
+    });
+
+  return commands;
+}

package/src/commands/commands/list/index.js

@@ -0,0 +1,43 @@
+import { Command } from '../../../lib/Command.js';
+import { readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+export class ListCommandsCommand extends Command {
+  async process() {
+    try {
+      // Get the path to src/commands directory
+      const currentFile = fileURLToPath(import.meta.url);
+      const commandsDir = join(dirname(currentFile), '..', '..');
+
+      // Read all namespace directories
+      const namespaces = await readdir(commandsDir, { withFileTypes: true });
+
+      // Filter only directories
+      const namespaceDirs = namespaces.filter(dirent => dirent.isDirectory());
+
+      // Iterate through each namespace
+      for (const namespace of namespaceDirs) {
+        const namespacePath = join(commandsDir, namespace.name);
+
+        // Read commands in this namespace
+        const items = await readdir(namespacePath, { withFileTypes: true });
+        const commands = items.filter(dirent =>
+          dirent.isDirectory() && dirent.name !== 'node_modules'
+        );
+
+        // Print namespace and its commands
+        if (commands.length > 0) {
+          console.log(namespace.name);
+          commands.forEach(cmd => {
+            console.log(`  ${cmd.name}`);
+          });
+          console.log(); // Blank line between namespaces
+        }
+      }
+    } catch (error) {
+      console.error('Error listing commands:', error.message);
+      process.exit(1);
+    }
+  }
+}

package/src/commands/commands/new/index.js

@@ -0,0 +1,109 @@
+import { Command } from '../../../lib/Command.js';
+import { mkdir, writeFile, access } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+export class NewCommandCommand extends Command {
+  async process() {
+    const options = this.getOptions();
+
+    // Validate --name option
+    if (!options.name) {
+      console.error('Error: --name option is required');
+      console.error('Usage: commands new --name "namespace.command"');
+      process.exit(1);
+    }
+
+    // Parse namespace and command
+    const parts = options.name.split('.');
+    if (parts.length !== 2) {
+      console.error('Error: --name must be in format "namespace.command"');
+      console.error('Example: commands new --name "commands.install"');
+      process.exit(1);
+    }
+
+    const [namespace, commandName] = parts;
+
+    // Validate names (alphanumeric and hyphens only)
+    const validNameRegex = /^[a-z0-9-]+$/;
+    if (!validNameRegex.test(namespace) || !validNameRegex.test(commandName)) {
+      console.error('Error: Namespace and command names must contain only lowercase letters, numbers, and hyphens');
+      process.exit(1);
+    }
+
+    // Calculate paths
+    const currentFile = fileURLToPath(import.meta.url);
+    const commandsDir = join(dirname(currentFile), '..', '..');
+    const namespacePath = join(commandsDir, namespace);
+    const commandPath = join(namespacePath, commandName);
+    const indexPath = join(commandPath, 'index.js');
+
+    try {
+      // Check if command already exists
+      try {
+        await access(indexPath);
+        console.error(`Error: Command already exists at ${indexPath}`);
+        process.exit(1);
+      } catch {
+        // File doesn't exist, proceed
+      }
+
+      // Create directories
+      await mkdir(commandPath, { recursive: true });
+
+      // Generate class name (PascalCase)
+      const className = toPascalCase(commandName) + 'Command';
+
+      // Generate boilerplate
+      const boilerplate = generateBoilerplate(className, commandName);
+
+      // Write file
+      await writeFile(indexPath, boilerplate, 'utf-8');
+
+      // Output success and instructions
+      console.log(`✓ Created command at: ${indexPath}`);
+      console.log();
+      console.log('Next steps:');
+      console.log(`1. Implement the logic in ${indexPath}`);
+      console.log(`2. Add the following to ${join(namespacePath, 'index.js')}:`);
+      console.log();
+      console.log('   Import statement (add at top):');
+      console.log(`   import { ${className} } from './${commandName}/index.js';`);
+      console.log();
+      console.log(`   Command registration (add in create${toPascalCase(namespace)}Command function):`);
+      console.log(`   ${namespace}`);
+      console.log(`     .command('${commandName}')`);
+      console.log(`     .description('Description of ${commandName} command')`);
+      console.log(`     .action(async (options) => {`);
+      console.log(`       const command = new ${className}(options);`);
+      console.log(`       await command.process();`);
+      console.log(`     });`);
+      console.log();
+      console.log(`3. If the namespace is new, register it in /src/index.js:`);
+      console.log(`   import { create${toPascalCase(namespace)}Command } from './commands/${namespace}/index.js';`);
+      console.log(`   program.addCommand(create${toPascalCase(namespace)}Command());`);
+
+    } catch (error) {
+      console.error('Error creating command:', error.message);
+      process.exit(1);
+    }
+  }
+}
+
+function toPascalCase(str) {
+  return str
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+function generateBoilerplate(className, commandName) {
+  return `import { Command } from '../../../lib/Command.js';
+
+export class ${className} extends Command {
+  async process() {
+    console.log(\`${commandName} called with \${JSON.stringify(this.getOptions())} from \${this.getCWD()}\`);
+  }
+}
+`;
+}