@raketa-cloud/cli 1.1.0

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

@@ -0,0 +1,186 @@
+import { Command } from '../../../lib/Command.js';
+import { mkdir, writeFile, access } from 'fs/promises';
+import { join } from 'path';
+
+export class NewWidgetCommand extends Command {
+  async process() {
+    const options = this.getOptions();
+
+    // Validate --name option
+    if (!options.name) {
+      console.error('Error: --name option is required');
+      console.error('Usage: widgets new --name "Hero"');
+      process.exit(1);
+    }
+
+    // Normalize name (ensure PascalCase and "Widget" suffix)
+    const widgetName = normalizeName(options.name);
+
+    // Get CWD and build target path
+    const cwd = this.getCWD();
+    const widgetsDir = join(cwd, 'src', 'components', 'widgets');
+    const widgetPath = join(widgetsDir, widgetName);
+
+    try {
+      // Create widgets directory if it doesn't exist
+      await mkdir(widgetsDir, { recursive: true });
+
+      // Check if widget already exists
+      try {
+        await access(widgetPath);
+        console.error(`Error: Widget already exists at ${widgetPath}`);
+        process.exit(1);
+      } catch {
+        // Widget doesn't exist, proceed
+      }
+
+      // Create widget directory
+      await mkdir(widgetPath);
+
+      // Generate and write all 5 files
+      const configContent = generateConfigTemplate(widgetName);
+      const adminContent = generateAdminTemplate(widgetName);
+      const defaultsContent = generateDefaultsTemplate(widgetName);
+      const indexContent = generateIndexTemplate(widgetName);
+      const fetcherContent = generateFetcherTemplate();
+
+      await writeFile(join(widgetPath, 'config.js'), configContent, 'utf-8');
+      await writeFile(join(widgetPath, 'admin.js'), adminContent, 'utf-8');
+      await writeFile(join(widgetPath, 'defaults.js'), defaultsContent, 'utf-8');
+      await writeFile(join(widgetPath, 'index.js'), indexContent, 'utf-8');
+      await writeFile(join(widgetPath, 'fetcher.js'), fetcherContent, 'utf-8');
+
+      // Output success message and instructions
+      console.log(`✓ Created widget at: ${widgetPath}`);
+      console.log();
+      console.log('Files created:');
+      console.log(`  - config.js`);
+      console.log(`  - admin.js`);
+      console.log(`  - defaults.js`);
+      console.log(`  - index.js`);
+      console.log(`  - fetcher.js`);
+      console.log();
+      console.log('Next steps:');
+      console.log();
+      console.log('1. Add to src/components/widgets/index.js:');
+      console.log();
+      console.log(`   export { default as ${widgetName} } from './${widgetName}/index.js';`);
+      console.log();
+      console.log('2. Add to src/components/widgets/admin.js:');
+      console.log();
+      console.log(`   import * as ${widgetName} from "./${widgetName}/admin";`);
+      console.log();
+      console.log('   Then include in the export:');
+      console.log();
+      console.log(`   export default {`);
+      console.log(`     // other widgets...`);
+      console.log(`     ${widgetName},`);
+      console.log(`   };`);
+
+    } catch (error) {
+      console.error('Error creating widget:', error.message);
+      process.exit(1);
+    }
+  }
+}
+
+// Helper function to normalize widget name
+function normalizeName(name) {
+  // Remove any non-alphanumeric characters except hyphens
+  let normalized = name.replace(/[^a-zA-Z0-9-]/g, '');
+
+  // Convert to PascalCase
+  normalized = normalized
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+
+  // Ensure first letter is uppercase
+  normalized = normalized.charAt(0).toUpperCase() + normalized.slice(1);
+
+  // Add "Widget" suffix if not already present
+  if (!normalized.endsWith('Widget')) {
+    normalized += 'Widget';
+  }
+
+  return normalized;
+}
+
+// Helper function to convert PascalCase to kebab-case
+function kebabCase(str) {
+  return str
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+}
+
+// Template generators
+function generateConfigTemplate(widgetName) {
+  // Remove "Widget" suffix for display name
+  const displayName = widgetName.replace(/Widget$/, '');
+
+  return `export default {
+  title: '${displayName}',
+  category: 'content',
+  primaryField: 'title',
+  deprecated: false
+};
+`;
+}
+
+function generateAdminTemplate(widgetName) {
+  return `import Defaults from "./defaults";
+import Config from "./config";
+
+const Admin = {
+  title: { type: "text" },
+};
+
+export { Admin, Defaults, Config };
+`;
+}
+
+function generateDefaultsTemplate(widgetName) {
+  return `export default {
+  title: 'Default Title',
+};
+`;
+}
+
+function generateIndexTemplate(widgetName) {
+  const kebabName = kebabCase(widgetName);
+
+  return `import React from 'react';
+
+export default function ${widgetName}({ title, __ctx, __data }) {
+  return (
+    <div className="${kebabName}">
+      <h2>{title}</h2>
+    </div>
+  );
+}
+`;
+}
+
+function generateFetcherTemplate() {
+  return `/**
+ * Optional: Server-side data fetching for dynamic widgets
+ * Uncomment and implement if your widget needs to fetch data
+ */
+
+/*
+export default async function fetcher(settings, context) {
+  // Fetch data based on settings
+  // Available in context: { locale, slug, ... }
+
+  const data = await fetch('your-api-endpoint', {
+    // your fetch logic
+  });
+
+  return data;
+}
+*/
+
+export default null;
+`;
+}

package/src/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { createWidgetsCommand } from './commands/widgets/index.js';
+import { createSkillsCommand } from './commands/skills/index.js';
+import { createCommandsCommand } from './commands/commands/index.js';
+
+program
+  .name('raketa-cli')
+  .description('Collection of useful CLI tools for humans and coding agents')
+  .version('1.0.0');
+
+program.addCommand(createWidgetsCommand());
+program.addCommand(createSkillsCommand());
+program.addCommand(createCommandsCommand());
+
+program.parse(process.argv);

package/src/lib/Command.js

@@ -0,0 +1,14 @@
+export class Command {
+  constructor(options = {}) {
+    this.options = options;
+    this.pwd = process.cwd();
+  }
+
+  getOptions() {
+    return this.options;
+  }
+
+  getCWD() {
+    return this.pwd;
+  }
+}

package/src/lib/skillsUtils.js

@@ -0,0 +1,246 @@
+import { readFile, readdir, access, mkdir, cp, rm } from 'fs/promises';
+import { join } from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Parse skill metadata from SKILL.md frontmatter
+ * @param {string} skillMdPath - Path to SKILL.md file
+ * @returns {Promise<{name: string, description: string}|null>} Parsed metadata or null if invalid
+ */
+export async function parseSkillMetadata(skillMdPath) {
+  try {
+    // Read file content
+    const content = await readFile(skillMdPath, 'utf-8');
+
+    // Extract YAML frontmatter
+    const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
+    const match = content.match(frontmatterRegex);
+
+    if (!match) {
+      return null; // No frontmatter found
+    }
+
+    const frontmatter = match[1];
+    let metadata;
+
+    // Try to parse YAML
+    try {
+      metadata = yaml.load(frontmatter);
+    } catch (yamlError) {
+      // If YAML parsing fails, try manual extraction as fallback
+      // This handles cases where description contains unquoted colons
+      const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+      const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+
+      if (nameMatch && descMatch) {
+        metadata = {
+          name: nameMatch[1].trim(),
+          description: descMatch[1].trim()
+        };
+      } else {
+        return null;
+      }
+    }
+
+    // Validate required fields
+    if (!metadata || typeof metadata.description !== 'string' || !metadata.description.trim()) {
+      return null; // Missing or empty description
+    }
+
+    return {
+      name: metadata.name || null,
+      description: metadata.description.trim()
+    };
+
+  } catch (error) {
+    // File read error or other unexpected error
+    return null;
+  }
+}
+
+/**
+ * Format skill name and description with colors
+ * @param {string} skillName - Name of the skill
+ * @param {string} description - Description of the skill (optional)
+ * @returns {string} Formatted output string
+ */
+export function formatSkillWithDescription(skillName, description) {
+  if (description) {
+    // Skill name on one line (bold cyan), description on next line (dim/light gray), blank line after
+    return `  ${chalk.bold.cyan(skillName)}\n  ${chalk.dim(description)}\n`;
+  }
+  // Fallback for backward compatibility
+  return `  ${skillName}`;
+}
+
+/**
+ * Ensure remote repository is cloned and up-to-date
+ * @param {string} repoUrl - Git repository URL
+ * @param {string} cachePath - Local path to cache the repository
+ * @returns {Promise<void>}
+ * @throws {Error} With specific error messages for different failure scenarios
+ */
+export async function ensureRemoteRepo(repoUrl, cachePath) {
+  try {
+    // Check if cache directory exists
+    await access(cachePath);
+
+    // Directory exists, pull updates
+    try {
+      await execFileAsync('git', ['-C', cachePath, 'pull', 'origin', 'main'], {
+        timeout: 30000
+      });
+    } catch (pullError) {
+      // If pull fails, we can still use cached data
+      // Just log a warning but don't throw
+      console.warn('Warning: Could not update cached repository, using existing data');
+    }
+
+  } catch (accessError) {
+    // Directory doesn't exist, clone it
+    try {
+      // Create parent directory
+      const parentDir = join(cachePath, '..');
+      await mkdir(parentDir, { recursive: true });
+
+      // Clone repository
+      await execFileAsync('git', ['clone', repoUrl, cachePath], {
+        timeout: 30000
+      });
+
+    } catch (cloneError) {
+      // Handle specific git errors
+      if (cloneError.code === 'ENOENT') {
+        throw new Error('git is not installed. Please install git to use this command.');
+      }
+
+      const stderr = cloneError.stderr || '';
+
+      if (stderr.includes('Could not resolve host') || stderr.includes('Failed to connect')) {
+        throw new Error('Cannot reach GitHub. Check your internet connection.');
+      }
+
+      if (stderr.includes('Permission denied') || stderr.includes('publickey')) {
+        throw new Error('SSH authentication failed. Ensure your SSH key is configured for GitHub.');
+      }
+
+      if (stderr.includes('Repository not found')) {
+        throw new Error('Remote repository not found or not accessible.');
+      }
+
+      // Generic error
+      throw new Error(`Failed to clone repository: ${cloneError.message}`);
+    }
+  }
+}
+
+/**
+ * Get all skills with their descriptions from a directory
+ * @param {string} skillsPath - Path to skills directory
+ * @returns {Promise<Array<{name: string, description: string}>>} Array of skills with descriptions
+ */
+export async function getSkillsWithDescriptions(skillsPath) {
+  const skills = [];
+
+  try {
+    // Read directory contents
+    const items = await readdir(skillsPath, { withFileTypes: true });
+
+    // Filter for directories only
+    const directories = items.filter(dirent => dirent.isDirectory());
+
+    // Process each directory
+    for (const dir of directories) {
+      const skillMdPath = join(skillsPath, dir.name, 'SKILL.md');
+
+      try {
+        // Check if SKILL.md exists
+        await access(skillMdPath);
+
+        // Parse metadata
+        const metadata = await parseSkillMetadata(skillMdPath);
+
+        // Only include if description is valid
+        if (metadata && metadata.description) {
+          skills.push({
+            name: dir.name,
+            description: metadata.description
+          });
+        }
+      } catch {
+        // Skip directories without valid SKILL.md or description
+      }
+    }
+
+  } catch (error) {
+    // If directory doesn't exist or can't be read, return empty array
+    return [];
+  }
+
+  return skills;
+}
+
+/**
+ * Copy skill directory from cache to destination
+ * @param {string} skillName - Name of the skill to copy
+ * @param {string} cachePath - Source cache path
+ * @param {string} destPath - Destination path
+ * @param {boolean} overwrite - Whether to overwrite existing skills
+ * @returns {Promise<void>}
+ * @throws {Error} If skill doesn't exist in cache or copy fails
+ */
+export async function copySkillFromCache(skillName, cachePath, destPath, overwrite = false) {
+  // Validate skill exists in cache
+  const sourceSkillPath = join(cachePath, skillName);
+  const sourceSkillMd = join(sourceSkillPath, 'SKILL.md');
+
+  try {
+    await access(sourceSkillPath);
+    await access(sourceSkillMd);
+  } catch {
+    throw new Error(`Skill '${skillName}' not found in remote repository`);
+  }
+
+  // Create destination parent directory if needed
+  await mkdir(destPath, { recursive: true });
+
+  // Check if skill already exists at destination
+  const destSkillPath = join(destPath, skillName);
+
+  try {
+    await access(destSkillPath);
+    // Skill exists
+    if (overwrite) {
+      console.log(chalk.yellow(`Skill '${skillName}' already exists, overwriting...`));
+      await rm(destSkillPath, { recursive: true, force: true });
+    } else {
+      throw new Error(`Skill '${skillName}' already exists at ${destSkillPath}`);
+    }
+  } catch (error) {
+    // If access fails, skill doesn't exist - continue with copy
+    // If it's another error, rethrow
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  // Copy the skill directory
+  try {
+    await cp(sourceSkillPath, destSkillPath, { recursive: true });
+  } catch (error) {
+    throw new Error(`Failed to copy skill: ${error.message}`);
+  }
+
+  // Verify copy succeeded by checking for SKILL.md in destination
+  const destSkillMd = join(destSkillPath, 'SKILL.md');
+  try {
+    await access(destSkillMd);
+  } catch {
+    throw new Error(`Skill copy verification failed: SKILL.md not found at ${destSkillMd}`);
+  }
+}