heraspec 0.1.0 → 0.1.2

package/bin/heraspec.js

@@ -185,6 +185,14 @@ This document defines the workflow for AI agents working with HeraSpec.
 - Agent implements with proper colors, fonts, styles from search results
 - Agent verifies with pre-delivery checklist
 
+**Special case - Flatsome UX Element skill:**
+- Task: \`(projectType: wordpress, skill: ux-element)\`
+- Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
+- Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
+- Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
+- Agent ensures real-time preview support in AngularJS template.
+- **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
+
 - Follow tasks.md
 - Mark tasks completed: \`- [x]\`
 
@@ -320,29 +328,17 @@ var SKILLS_SECTION_TEMPLATE = `## Skills System
 - Agent follows: Steps, uses templates, runs scripts
 - Agent implements: According to skill.md guidelines
 
-**Special case - UI/UX skill:**
-- Task: \`(skill: ui-ux)\`
-- Agent reads: \`heraspec/skills/ui-ux/skill.md\`
-- Agent MUST use search scripts before implementing:
-  \`\`\`bash
-  # Search for design intelligence (BM25 - default, fast)
-  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
-  
-  # For better semantic results, use Vector or Hybrid mode:
-  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain> --mode vector
-  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain> --mode hybrid
-  
-  # Stack-specific search
-  python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
-  \`\`\`
-- **Search Modes:**
-  - **BM25 (default)**: Fast keyword-based search, zero dependencies
-  - **Vector**: Semantic search, ~15-20% better results (requires: pip install sentence-transformers scikit-learn)
-  - **Hybrid**: Best of both, ~25% better results (requires: pip install sentence-transformers scikit-learn)
-- Agent synthesizes search results
 - Agent implements with proper colors, fonts, styles from search results
 - Agent verifies with pre-delivery checklist
 
+**Special case - Flatsome UX Element skill:**
+- Task: \`(projectType: wordpress, skill: ux-element)\`
+- Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
+- Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
+- Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
+- Agent ensures real-time preview support in AngularJS template.
+- **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
+
 ### Skill Discovery
 
 - List all skills: Check \`heraspec/skills/\` directory
@@ -710,6 +706,17 @@ python3 heraspec/skills/ui-ux/scripts/search.py "pricing plans" --domain pages
 
 3. Read \`heraspec/skills/ui-ux/ui-ux-skill.md\` for complete documentation
 
+### Flatsome UX Element Skill
+
+Use the **ux-element** skill when developing elements for UX Builder in Flatsome themes.
+
+**Usage:**
+\`\`\`bash
+heraspec skill add ux-element --project-type wordpress
+\`\`\`
+
+Read \`heraspec/skills/wordpress/ux-element/skill.md\` for the **Wrapping Rule** and template usage.
+
 ## Creating New Skills
 
 1. Create skill folder structure
@@ -2353,6 +2360,12 @@ var SKILL_TEMPLATE_MAP = {
     templateFileName: "module-codebase-skill.md",
     isCrossCutting: false,
     projectType: "perfex-module"
+  },
+  "wordpress:ux-element": {
+    templateFileName: "ux-element-skill.md",
+    isCrossCutting: false,
+    projectType: "wordpress",
+    resourceDirs: ["ux-element/templates"]
   }
 };
 function getSkillTemplateInfo(skillName, projectType) {
@@ -2713,6 +2726,9 @@ var SkillCommand = class {
       process.exitCode = 1;
     }
   }
+  async update(skillName, projectType, projectPath = ".") {
+    return this.add(skillName, projectType, projectPath);
+  }
 };
 
 // src/commands/helper.ts
@@ -3641,6 +3657,222 @@ Specs analyzed: ${specFiles.length}`));
   }
 };
 
+// src/commands/suggest.ts
+import path15 from "path";
+import chalk10 from "chalk";
+import ora8 from "ora";
+var SuggestCommand = class {
+  async execute(projectPath = ".") {
+    const spinner = ora8("Analyzing project and generating suggestions...").start();
+    try {
+      const resolvedPath = path15.resolve(projectPath);
+      const specsDir = path15.join(resolvedPath, HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+      const suggestionsDir = path15.join(resolvedPath, HERASPEC_DIR_NAME, "suggestions");
+      const projectMdPath = path15.join(resolvedPath, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD);
+      if (!await FileSystemUtils.fileExists(specsDir)) {
+        spinner.fail('Specs directory not found. Run "heraspec init" first.');
+        process.exitCode = 1;
+        return;
+      }
+      await FileSystemUtils.createDirectory(suggestionsDir);
+      let projectInfo = {};
+      if (await FileSystemUtils.fileExists(projectMdPath)) {
+        const projectContent = await FileSystemUtils.readFile(projectMdPath);
+        projectInfo = this.extractProjectInfo(projectContent);
+      }
+      const specFiles = await this.findSpecFiles(specsDir);
+      const specs = specFiles.length > 0 ? await this.readSpecs(specFiles) : [];
+      const suggestions = this.generateSuggestions(specs, projectInfo);
+      const suggestionsFilePath = path15.join(suggestionsDir, "feature-suggestions.md");
+      const suggestionsContent = this.formatSuggestions(suggestions, projectInfo);
+      await FileSystemUtils.writeFile(suggestionsFilePath, suggestionsContent);
+      spinner.succeed(`Feature suggestions generated: ${suggestionsFilePath}`);
+      console.log(chalk10.gray(`
+Found ${specs.length} existing feature(s)`));
+      console.log(chalk10.gray(`Generated ${suggestions.length} suggestion(s)`));
+    } catch (error) {
+      spinner.fail(`Error: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  }
+  /**
+   * Extract project information from project.md
+   */
+  extractProjectInfo(projectContent) {
+    const info = {};
+    const nameMatch = projectContent.match(/^#\s+(.+)$/m);
+    if (nameMatch) {
+      info.name = nameMatch[1].trim();
+    }
+    const projectTypeMatch = projectContent.match(/project[-\s]type[s]?[:\s]+([^\n]+)/i);
+    if (projectTypeMatch) {
+      info.projectType = projectTypeMatch[1].trim();
+    }
+    const stackMatch = projectContent.match(/tech[-\s]stack[:\s]+([^\n]+)/i);
+    if (stackMatch) {
+      info.stack = stackMatch[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    }
+    return info;
+  }
+  /**
+   * Find all spec files recursively
+   */
+  async findSpecFiles(specsDir) {
+    const specFiles = [];
+    await this.findSpecFilesRecursive(specsDir, specFiles);
+    return specFiles.sort();
+  }
+  /**
+   * Recursively find spec files
+   */
+  async findSpecFilesRecursive(dir, files) {
+    const fs2 = await import("fs/promises");
+    const entries = await fs2.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path15.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.findSpecFilesRecursive(entryPath, files);
+      } else if (entry.name.endsWith(".md")) {
+        files.push(entryPath);
+      }
+    }
+  }
+  /**
+   * Read all spec files
+   */
+  async readSpecs(specFiles) {
+    const specs = [];
+    for (const specFile of specFiles) {
+      const content = await FileSystemUtils.readFile(specFile);
+      const name = this.extractFeatureName(specFile, content);
+      specs.push({
+        path: specFile,
+        content,
+        name
+      });
+    }
+    return specs;
+  }
+  /**
+   * Extract feature name from spec file
+   */
+  extractFeatureName(filePath, content) {
+    const headingMatch = content.match(/^#+\s+(.+)$/m);
+    if (headingMatch) {
+      return headingMatch[1].trim();
+    }
+    return path15.basename(filePath, ".md");
+  }
+  /**
+   * Generate feature suggestions based on existing specs
+   */
+  generateSuggestions(specs, projectInfo) {
+    const suggestions = [];
+    const existingFeatures = specs.map((s) => s.name.toLowerCase());
+    if (projectInfo.projectType?.toLowerCase().includes("plugin") || projectInfo.projectType?.toLowerCase().includes("module")) {
+      if (!existingFeatures.some((f) => f.includes("settings") || f.includes("config"))) {
+        suggestions.push({
+          title: "Settings/Configuration Management",
+          description: "Add a centralized settings management feature to allow users to configure plugin/module behavior.",
+          category: "Configuration",
+          integrationPoints: ["Admin interface", "Database storage"]
+        });
+      }
+      if (!existingFeatures.some((f) => f.includes("report") || f.includes("analytics"))) {
+        suggestions.push({
+          title: "Reporting and Analytics",
+          description: "Add reporting functionality to track usage, generate analytics, and provide insights.",
+          category: "Analytics",
+          integrationPoints: ["Data collection", "Dashboard"]
+        });
+      }
+    }
+    if (!existingFeatures.some((f) => f.includes("export") || f.includes("import"))) {
+      suggestions.push({
+        title: "Data Import/Export",
+        description: "Add functionality to import and export data in various formats (CSV, JSON, XML).",
+        category: "Data Management",
+        integrationPoints: ["File handling", "Data processing"]
+      });
+    }
+    if (!existingFeatures.some((f) => f.includes("search") || f.includes("filter"))) {
+      suggestions.push({
+        title: "Advanced Search and Filtering",
+        description: "Implement advanced search and filtering capabilities to help users find information quickly.",
+        category: "User Experience",
+        integrationPoints: ["Search interface", "Data indexing"]
+      });
+    }
+    if (!existingFeatures.some((f) => f.includes("notification") || f.includes("alert"))) {
+      suggestions.push({
+        title: "Notifications and Alerts",
+        description: "Add notification system to alert users about important events and updates.",
+        category: "Communication",
+        integrationPoints: ["Event system", "User preferences"]
+      });
+    }
+    return suggestions;
+  }
+  /**
+   * Format suggestions as markdown
+   */
+  formatSuggestions(suggestions, projectInfo) {
+    const lines = [];
+    lines.push("# Feature Suggestions");
+    lines.push("");
+    lines.push(`Generated for: ${projectInfo.name || "Project"}`);
+    lines.push(`Project Type: ${projectInfo.projectType || "Not specified"}`);
+    lines.push(`Generated on: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push("## Overview");
+    lines.push("");
+    lines.push(`This document contains ${suggestions.length} feature suggestions that could enhance the project.`);
+    lines.push("Each suggestion includes integration points and considerations for implementation.");
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    const byCategory = {};
+    suggestions.forEach((suggestion) => {
+      if (!byCategory[suggestion.category]) {
+        byCategory[suggestion.category] = [];
+      }
+      byCategory[suggestion.category].push(suggestion);
+    });
+    Object.entries(byCategory).forEach(([category, categorySuggestions]) => {
+      lines.push(`## ${category}`);
+      lines.push("");
+      categorySuggestions.forEach((suggestion, index) => {
+        lines.push(`### ${index + 1}. ${suggestion.title}`);
+        lines.push("");
+        lines.push(suggestion.description);
+        lines.push("");
+        if (suggestion.integrationPoints.length > 0) {
+          lines.push("**Integration Points:**");
+          lines.push("");
+          suggestion.integrationPoints.forEach((point) => {
+            lines.push(`- ${point}`);
+          });
+          lines.push("");
+        }
+        if (index < categorySuggestions.length - 1) {
+          lines.push("---");
+          lines.push("");
+        }
+      });
+      lines.push("");
+    });
+    lines.push("---");
+    lines.push("");
+    lines.push("*These suggestions are generated based on analysis of existing features and common patterns.*");
+    lines.push("*Review and prioritize suggestions based on project requirements and goals.*");
+    lines.push("");
+    return lines.join("\n");
+  }
+};
+
 // src/cli/index.ts
 var require3 = createRequire2(import.meta.url);
 var __filename2 = fileURLToPath2(import.meta.url);
@@ -3799,5 +4031,14 @@ skillCmd.command("add <skill-name>").description("Add a default skill to the pro
     process.exit(1);
   }
 });
+skillCmd.command("update <skill-name>").description("Update an existing skill with the latest from HeraSpec templates").option("--project-type <type>", "Specify project type for project-specific skills").action(async (skillName, options) => {
+  try {
+    const skillCommand = new SkillCommand();
+    await skillCommand.update(skillName, options?.projectType, ".");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
 program.parse();
 //# sourceMappingURL=heraspec.js.map