maestro-flow 0.3.48 → 0.4.1

package/workflows/impeccable/ui-search/render-prototype.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * render-prototype.js
+ *
+ * Reads one or more MASTER.md files and renders HTML prototypes by injecting
+ * extracted design tokens into prototype-template.html.
+ *
+ * Zero external dependencies — uses only Node.js built-ins.
+ *
+ * Usage:
+ *   node render-prototype.js <master1.md> [master2.md ...] --output <dir> [--project <name>]
+ *   node render-prototype.js --dir <folder-with-masters> --output <dir> [--project <name>]
+ *
+ * Output:
+ *   <dir>/prototype_1.html, prototype_2.html, ...
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = { files: [], output: "", project: "Project", dir: "" };
+  let i = 2; // skip node + script
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === "--output" || a === "-o") { args.output = argv[++i]; }
+    else if (a === "--project" || a === "-p") { args.project = argv[++i]; }
+    else if (a === "--dir" || a === "-d") { args.dir = argv[++i]; }
+    else if (!a.startsWith("-")) { args.files.push(a); }
+    i++;
+  }
+  // Expand --dir to individual files
+  if (args.dir && fs.existsSync(args.dir)) {
+    const entries = fs.readdirSync(args.dir)
+      .filter(f => f.endsWith(".md") && f.toUpperCase().includes("MASTER"))
+      .map(f => path.join(args.dir, f));
+    args.files.push(...entries);
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// MASTER.md parser — extracts design tokens
+// ---------------------------------------------------------------------------
+function parseMaster(content) {
+  const tokens = {
+    projectName: "",
+    styleName: "",
+    colors: {},
+    fontHeading: "Inter",
+    fontBody: "Inter",
+    googleFontsUrl: "",
+    googleFontsLink: "",
+  };
+
+  // Project name
+  const projMatch = content.match(/\*\*Project:\*\*\s*(.+)/);
+  if (projMatch) tokens.projectName = projMatch[1].trim();
+
+  // Style name
+  const styleMatch = content.match(/\*\*Style:\*\*\s*(.+)/);
+  if (styleMatch) tokens.styleName = styleMatch[1].trim();
+
+  // Color palette table: | Role | `#hex` | `--css-var` |
+  const colorPattern = /\|\s*([^|]+?)\s*\|\s*`(#[0-9A-Fa-f]{3,8})`\s*\|\s*`(--[^`]+)`\s*\|/g;
+  let m;
+  while ((m = colorPattern.exec(content)) !== null) {
+    const cssVar = m[3].trim();
+    const hex = m[2].trim();
+    // Map --color-primary → primary
+    const key = cssVar.replace(/^--color-/, "");
+    tokens.colors[key] = hex;
+  }
+
+  // Typography
+  const headingMatch = content.match(/\*\*Heading Font:\*\*\s*(.+)/);
+  if (headingMatch) tokens.fontHeading = headingMatch[1].trim();
+
+  const bodyMatch = content.match(/\*\*Body Font:\*\*\s*(.+)/);
+  if (bodyMatch) tokens.fontBody = bodyMatch[1].trim();
+
+  // Google Fonts URL
+  const gfMatch = content.match(/\*\*Google Fonts:\*\*\s*\[.*?\]\((https:\/\/fonts\.googleapis\.com\/[^)]+)\)/);
+  if (gfMatch) {
+    tokens.googleFontsUrl = gfMatch[1];
+    tokens.googleFontsLink = `<link rel="preconnect" href="https://fonts.googleapis.com">\n  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>\n  <link href="${gfMatch[1]}" rel="stylesheet">`;
+  } else {
+    // Fallback: build Google Fonts link from font names
+    const families = [tokens.fontHeading, tokens.fontBody]
+      .filter((v, i, a) => a.indexOf(v) === i) // unique
+      .map(f => `family=${f.replace(/\s+/g, "+")}:wght@400;500;600;700`)
+      .join("&");
+    const url = `https://fonts.googleapis.com/css2?${families}&display=swap`;
+    tokens.googleFontsLink = `<link rel="preconnect" href="https://fonts.googleapis.com">\n  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>\n  <link href="${url}" rel="stylesheet">`;
+  }
+
+  // CSS import block (alternative font loading)
+  const cssImportMatch = content.match(/\*\*CSS Import:\*\*[\s\S]*?```css\n([\s\S]*?)```/);
+  if (cssImportMatch && !gfMatch) {
+    // Extract URL from @import
+    const importUrl = cssImportMatch[1].match(/url\(['"]?(https:\/\/[^'")\s]+)['"]?\)/);
+    if (importUrl) {
+      tokens.googleFontsLink = `<link rel="preconnect" href="https://fonts.googleapis.com">\n  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>\n  <link href="${importUrl[1]}" rel="stylesheet">`;
+    }
+  }
+
+  return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Template rendering
+// ---------------------------------------------------------------------------
+function render(template, tokens, projectOverride) {
+  const project = projectOverride || tokens.projectName || "Project";
+  const colors = tokens.colors;
+
+  let html = template
+    .replace(/\{\{PROJECT_NAME\}\}/g, project)
+    .replace(/\{\{STYLE_NAME\}\}/g, tokens.styleName || "Default")
+    .replace(/\{\{GOOGLE_FONTS_LINK\}\}/g, tokens.googleFontsLink || "")
+    .replace(/\{\{FONT_HEADING\}\}/g, tokens.fontHeading)
+    .replace(/\{\{FONT_BODY\}\}/g, tokens.fontBody)
+    .replace(/\{\{COLOR_PRIMARY\}\}/g, colors.primary || "#2563EB")
+    .replace(/\{\{COLOR_ON_PRIMARY\}\}/g, colors["on-primary"] || "#FFFFFF")
+    .replace(/\{\{COLOR_SECONDARY\}\}/g, colors.secondary || "#7C3AED")
+    .replace(/\{\{COLOR_ACCENT\}\}/g, colors["accent"] || colors["accent/cta"] || "#F97316")
+    .replace(/\{\{COLOR_BACKGROUND\}\}/g, colors.background || "#FFFFFF")
+    .replace(/\{\{COLOR_FOREGROUND\}\}/g, colors.foreground || "#1E293B")
+    .replace(/\{\{COLOR_MUTED\}\}/g, colors.muted || "#94A3B8")
+    .replace(/\{\{COLOR_BORDER\}\}/g, colors.border || "#E2E8F0")
+    .replace(/\{\{COLOR_DESTRUCTIVE\}\}/g, colors.destructive || "#EF4444")
+    .replace(/\{\{COLOR_RING\}\}/g, colors.ring || "#3B82F6");
+
+  return html;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.files.length === 0) {
+    console.error("Usage: node render-prototype.js <master1.md> [master2.md ...] --output <dir> [--project <name>]");
+    console.error("       node render-prototype.js --dir <folder> --output <dir> [--project <name>]");
+    process.exit(1);
+  }
+
+  if (!args.output) {
+    console.error("Error: --output <dir> is required");
+    process.exit(1);
+  }
+
+  // Load template
+  const templatePath = path.join(__dirname, "prototype-template.html");
+  if (!fs.existsSync(templatePath)) {
+    console.error(`Error: Template not found at ${templatePath}`);
+    process.exit(1);
+  }
+  const template = fs.readFileSync(templatePath, "utf-8");
+
+  // Ensure output directory
+  fs.mkdirSync(args.output, { recursive: true });
+
+  const results = [];
+
+  for (let i = 0; i < args.files.length; i++) {
+    const file = args.files[i];
+    if (!fs.existsSync(file)) {
+      console.error(`Warning: ${file} not found, skipping`);
+      continue;
+    }
+
+    const content = fs.readFileSync(file, "utf-8");
+    const tokens = parseMaster(content);
+    const html = render(template, tokens, args.project);
+
+    const label = String.fromCharCode(65 + i); // A, B, C, ...
+    const outName = `prototype_${label}.html`;
+    const outPath = path.join(args.output, outName);
+    fs.writeFileSync(outPath, html, "utf-8");
+
+    results.push({
+      file: outName,
+      style: tokens.styleName,
+      fonts: `${tokens.fontHeading} + ${tokens.fontBody}`,
+      colors: Object.keys(tokens.colors).length,
+    });
+
+    console.log(`  [${label}] ${outName} — ${tokens.styleName} (${tokens.fontHeading}/${tokens.fontBody}, ${Object.keys(tokens.colors).length} colors)`);
+  }
+
+  // Write manifest for downstream tools
+  const manifestPath = path.join(args.output, "manifest.json");
+  fs.writeFileSync(manifestPath, JSON.stringify({
+    generated: new Date().toISOString(),
+    project: args.project,
+    prototypes: results,
+  }, null, 2), "utf-8");
+
+  console.log(`\n  ${results.length} prototype(s) written to ${args.output}/`);
+  console.log(`  manifest: ${manifestPath}`);
+}
+
+main();

package/workflows/impeccable/ui-search/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help=f"Stack-specific search. Available: {', '.join(AVAILABLE_STACKS)}")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/workflows/maestro-chain-execute.md

@@ -76,7 +76,7 @@ context = {
    {milestone_num} → context.milestone_num
 
 2. In auto_mode, append per-command flag if not already present:
-   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-ui-design → -y
+   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-impeccable → -y
    maestro-plan → --auto
    quality-test → --auto-fix
    quality-retrospective → --auto-yes
@@ -95,7 +95,7 @@ Read `step.engine` from status.json (pre-computed by selection workflow Step 3e)
 If `step.engine` is missing or null, fallback to auto selection:
 ```
   CLI: maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
-       maestro-roadmap, maestro-ui-design, quality-refactor
+       maestro-roadmap, maestro-impeccable, quality-refactor
   Internal: everything else (current-session Skill() call)
 ```
 

package/workflows/maestro.codex.md

@@ -105,7 +105,7 @@ const chainMap = {
   'status':             [{ cmd: 'manage-status' }],
   'init':               [{ cmd: 'maestro-init' }],
   'analyze':            [{ cmd: 'maestro-analyze',        args: '{phase}' }],
-  'ui_design':          [{ cmd: 'maestro-ui-design',       args: '{phase}' }],
+  'ui_design':          [{ cmd: 'maestro-impeccable',         args: '"{phase}" --chain build' }],
   'plan':               [{ cmd: 'maestro-plan',            args: '{phase}' }],
   'execute':            [{ cmd: 'maestro-execute',         args: '{phase}' }],
   'verify':             [{ cmd: 'maestro-verify',          args: '{phase}' }],
@@ -150,8 +150,8 @@ const chainMap = {
     { cmd: 'maestro-execute',    args: '{phase}' },
     { cmd: 'maestro-verify',     args: '{phase}' }
   ],
-  'ui-design-driven': [
-    { cmd: 'maestro-ui-design', args: '{phase}' },
+  'impeccable-build': [
+    { cmd: 'maestro-impeccable', args: '"{phase}" --chain build' },
     { cmd: 'maestro-plan',      args: '{phase}' },
     { cmd: 'maestro-execute',   args: '{phase}' },
     { cmd: 'maestro-verify',    args: '{phase}' }