Minnow

Enhanced Blueprints

Enhanced Blueprints Roadmap

This document outlines the strategy for evolving Minnow's blueprint system from basic CRUD scaffolding to rich, behavior-aware plugin definitions.

Current State

Blueprints currently capture:

  • Database schema (tables, columns, indexes)
  • Entity definitions (properties, types)
  • API routes (CRUD endpoints)
  • Admin pages (basic list/edit with simple field types)

Vision

Blueprints should be able to express:

  1. Rich UI configurations - Field types, layouts, interactions
  2. Runtime behaviors - What the plugin actually does with its data
  3. Integrations - Hooks, events, external services

Phase 1: Enhanced Field/Column Types

Field Types for Editors

Type Description Use Case
text Single-line text input Names, titles
textarea Multi-line text Descriptions
code-editor Monaco/CodeMirror with syntax highlighting Code snippets, CSS, JSON
rich-text WYSIWYG editor Content with formatting
markdown Markdown editor with preview Documentation
number Numeric input with min/max/step Priority, quantity
toggle Boolean switch Active/inactive status
checkbox Checkbox (alternative to toggle) Boolean options
select Dropdown selection Categories, types
multi-select Multiple selection Tags, categories
radio Radio button group Mutually exclusive options
date Date picker Dates
datetime Date and time picker Timestamps
time Time picker Schedules
color Color picker Theme colors
media Media library picker Images, files
url URL input with validation Links
email Email input with validation Contact info
password Password input Credentials
json JSON editor with validation Configuration objects
tags Tag input (pills/chips) Tagging
relation Related entity selector Foreign keys
repeater Repeatable field group Multiple items

Column Types for Lists

Type Description Rendering
text Plain text Default
toggle Inline toggle switch Clickable on/off
badge Colored pill/badge Status indicators
date Formatted date Relative or absolute
datetime Formatted datetime With time
number Numeric with formatting Alignment, decimals
currency Money formatting Symbol, decimals
image Thumbnail Small preview
link Clickable URL External link icon
email Mailto link Email icon
boolean Yes/No text Or checkmark icon
progress Progress bar Percentage visual
tags Tag pills Multiple colored pills
actions Row action buttons Edit, delete, etc.

Layout Types

Layout Description Use Case
single-column Full-width fields Simple forms
two-column Main content + sidebar WordPress-style edit
tabbed Tabs containing field groups Complex forms
sections Collapsible sections Organized forms
wizard Multi-step form Onboarding, setup

Phase 2: AI-Enhanced Blueprint Generation

Concept

Use AI to analyze WordPress plugins and generate rich blueprints that capture not just the data model, but the UI patterns and behaviors.

Input Sources

  1. Static Analysis (current)

    • PHP code parsing
    • Database schema extraction
    • Hook/filter detection

  2. Screenshot Analysis (new)

    • Original plugin UI screenshots
    • AI interprets layout, field types, interactions
    • Maps visual patterns to blueprint constructs

  3. Documentation Analysis (new)

    • README files
    • Plugin descriptions
    • User documentation
    • Infer behaviors and use cases

Enhancement Workflow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  WordPress      │     │  AI Analysis    │     │  Enhanced       │
│  Plugin         │────▶│  Engine         │────▶│  Blueprint      │
│                 │     │                 │     │                 │
│ • PHP files     │     │ • Code parsing  │     │ • Rich fields   │
│ • Screenshots   │     │ • Vision AI     │     │ • Layouts       │
│ • Docs          │     │ • NLP           │     │ • Behaviors     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

CLI Command

# Basic enhancement with code analysis
minnow blueprint:enhance --plugin=code-snippets

# With screenshots for UI matching
minnow blueprint:enhance --plugin=code-snippets --screenshots=./screens/

# With original plugin for live analysis
minnow blueprint:enhance --plugin=code-snippets --source=./wp-plugins/code-snippets/

AI Prompting Strategy

  1. Field Type Detection

    • "This field contains PHP code" → code-editor with language: php
    • "This is a boolean active/inactive" → toggle
    • "This shows as a colored badge" → column type badge with color mapping

  2. Layout Detection

    • "Main content area with sidebar" → two-column layout
    • "Tabs at the top" → tabbed layout
    • "Multiple collapsible sections" → sections layout

  3. Behavior Detection

    • "Executes PHP code at runtime" → code-executor behavior
    • "Redirects URLs" → redirect behavior
    • "Sends email notifications" → email-notification behavior

Blueprint Marketplace

Pre-enhanced blueprints for popular plugins:

# Install community-enhanced blueprint
minnow blueprint:install code-snippets

# List available blueprints
minnow blueprint:search "form"

# Contribute enhancement
minnow blueprint:publish code-snippets --version=1.0.0

Quality Tiers

Tier Description Source
Auto Machine-generated, basic CRUD plugin:scan
Enhanced AI-improved UI, field types blueprint:enhance
Curated Human-reviewed, production-ready Community/official
Premium Full feature parity, behaviors Commercial

Phase 3: Behavior Primitives

Concept

Instead of requiring custom PHP for common plugin patterns, Minnow provides declarative behaviors that can be configured via blueprint.

Architecture

Blueprint (YAML)          Minnow Core              Runtime
─────────────────         ──────────────           ───────────
behaviors:          ───▶  BehaviorRegistry   ───▶  Executes at
  - type: redirect        finds & configures       appropriate
    entity: Redirect      RedirectBehavior         hooks
    fromField: source
    toField: target

Common Behaviors

1. Code Executor

Safely evaluates stored code at runtime.

behaviors:
  - type: code-executor
    entity: Snippet
    config:
      codeField: code           # Field containing the code
      activeField: active       # Field for enabled/disabled
      languageField: scope      # Field determining language/context
      priorityField: priority   # Execution order

      # When to execute based on language/scope value
      contexts:
        global:                 # scope = 'global'
          hook: init
          condition: always
        admin:
          hook: admin_init
          condition: is_admin
        frontend:
          hook: template_redirect
          condition: is_frontend
        head-content:
          hook: head
          condition: is_frontend
          wrap: style           # Wrap in <style> tags
        footer-content:
          hook: footer
          condition: is_frontend
          wrap: script          # Wrap in <script> tags

      # Safety options
      sandbox: true             # Run in isolated context
      timeout: 5000             # Max execution time (ms)
      errorHandling: log        # log | throw | ignore

2. Redirect

URL redirection rules.

behaviors:
  - type: redirect
    entity: Redirect
    config:
      sourceField: source_url
      targetField: target_url
      statusField: status_code    # 301, 302, 307
      activeField: enabled

      # Optional features
      matchType: exact            # exact | contains | regex
      queryHandling: preserve     # preserve | drop | merge
      logging: true               # Log redirect hits
      hitCountField: hits         # Field to store hit count

3. Shortcode

Register shortcodes from entity data.

behaviors:
  - type: shortcode
    entity: Shortcode
    config:
      tagField: tag               # [my_shortcode]
      templateField: template     # Content/HTML template
      activeField: active

      # Attribute handling
      attributeDefaults:
        class: ''
        id: ''

      # Merge tags in template
      mergeTags: true             # Replace {field} with values

4. Scheduled Task

Run actions on schedule.

behaviors:
  - type: scheduled-task
    entity: ScheduledTask
    config:
      nameField: name
      scheduleField: schedule     # cron expression or preset
      callbackField: callback     # PHP callback string
      activeField: enabled
      lastRunField: last_run
      nextRunField: next_run

      # Presets
      schedules:
        hourly: '0 * * * *'
        daily: '0 0 * * *'
        weekly: '0 0 * * 0'

5. Webhook

Fire HTTP requests on entity events.

behaviors:
  - type: webhook
    entity: Webhook
    config:
      urlField: endpoint_url
      methodField: method         # GET, POST, PUT
      headersField: headers       # JSON field
      activeField: enabled

      # Triggers
      triggers:
        - entity: Form
          event: created
        - entity: Entry
          event: created

      # Payload
      payloadTemplate: |
        {
          "event": "{{event}}",
          "data": {{entity_json}}
        }

6. Email Notification

Send emails based on events.

behaviors:
  - type: email-notification
    entity: Notification
    config:
      toField: recipient          # Email or field reference
      subjectField: subject
      bodyField: body
      activeField: enabled

      # Triggers
      triggers:
        - entity: Entry
          event: created

      # Template processing
      mergeTags: true
      htmlEmail: true

7. REST Endpoint

Custom API endpoints beyond CRUD.

behaviors:
  - type: rest-endpoint
    endpoints:
      - path: /snippets/{id}/execute
        method: POST
        handler: execute
        capability: manage_options

      - path: /snippets/export
        method: GET
        handler: export
        capability: manage_options

8. Admin Notice

Display admin notices based on conditions.

behaviors:
  - type: admin-notice
    entity: Notice
    config:
      messageField: message
      typeField: type             # info | warning | error | success
      dismissibleField: dismissible
      conditionField: condition   # PHP expression
      activeField: active

9. Spam Protection

Protect comments and forms from spam.

behaviors:
  - type: spam-protection
    config:
      honeypotEnabled: true
      honeypotField: minnow_hp
      rateLimitEnabled: true
      rateLimitWindow: 60
      rateLimitMax: 5
      minSubmitTime: 3
      linkLimitEnabled: true
      linkLimit: 5
      keywordBlocklist:
        - viagra
        - casino
        - cryptocurrency
      logBlocked: true
      logTable: spam_log

Behavior Implementation Structure

core/
  Plugin/
    Behavior/
      BehaviorInterface.php
      BehaviorRegistry.php
      AbstractBehavior.php

      CodeExecutor/
        CodeExecutorBehavior.php
        CodeSandbox.php

      Redirect/
        RedirectBehavior.php

      Shortcode/
        ShortcodeBehavior.php

      ScheduledTask/
        ScheduledTaskBehavior.php

      Webhook/
        WebhookBehavior.php

      EmailNotification/
        EmailNotificationBehavior.php

      SpamProtection/
        SpamProtectionBehavior.php

Behavior Interface

interface BehaviorInterface
{
    /**
     * Get the behavior type identifier.
     */
    public static function getType(): string;

    /**
     * Initialize the behavior with configuration.
     */
    public function configure(array $config, Plugin $plugin): void;

    /**
     * Register hooks and handlers.
     */
    public function register(): void;

    /**
     * Validate the configuration.
     */
    public function validate(): array; // Returns validation errors
}

Phase 4: Full Plugin Portability

Goal

A WordPress plugin can be fully described in a Minnow blueprint, including:

  • Data model
  • Admin UI (with full fidelity)
  • Runtime behaviors
  • Frontend rendering
  • Integrations

Coverage Target by Plugin Type

Plugin Type Blueprint Coverage Notes
Snippet managers 95% Behavior: code-executor
Redirect managers 98% Behavior: redirect
Contact forms 80% Need form builder UI
SEO plugins 70% Many unique features
E-commerce 40% Complex business logic
Page builders 20% Highly custom UI

What Still Needs Custom Code

  1. Complex UI interactions - Drag-and-drop, visual builders
  2. External API integrations - Payment gateways, third-party services
  3. Complex business logic - Calculations, validations
  4. Performance-critical code - Caching strategies, query optimization
  5. Security-sensitive operations - Authentication, encryption

Implementation Priority

Now (Phase 1) ✅ COMPLETE

  • [x] Implement enhanced field types in admin components
    • text, number, textarea, toggle, checkbox, select, code-editor, date, datetime, url, email, json, color
  • [x] Implement enhanced column types in list components
    • toggle (inline), badge (colored), boolean, number, currency, date, datetime, relative, image, link, email, progress, tags, truncate, code
  • [x] Add layout system (two-column, sections)
    • layout: two-column with sidebar sections in blueprint
    • mainFields and sidebarSections computed from config
  • [x] Update blueprint schema (code-snippets/plugin.yaml as reference)

Backlog

  • [ ] Improve code-editor component
    • Currently using plain textarea as fallback (Monaco had performance issues)
    • Consider: CodeMirror 6, Ace Editor, or lighter Monaco config
    • Add syntax highlighting for common languages (PHP, JS, CSS, HTML, JSON)
    • Line numbers, proper tab handling, auto-indent

Next (Phase 2)

  • [ ] Build blueprint:enhance CLI command
  • [ ] Integrate vision AI for screenshot analysis
  • [ ] Create blueprint marketplace infrastructure

Later (Phase 3)

  • [ ] Design behavior interface and registry
  • [ ] Implement code-executor behavior
  • [ ] Implement redirect behavior
  • [ ] Add more behaviors based on demand

Future (Phase 4)

  • [ ] Measure coverage across popular plugins
  • [ ] Identify gaps and prioritize improvements
  • [ ] Build community contribution workflow

Phase 1 Implementation Details

Files Modified

/admin/index.php

  • PluginListPage - Enhanced column rendering with 14 column types
  • PluginEditorPage - Added 13 field sub-components and two-column layout support

Blueprint Schema for Enhanced UI

List Page with Enhanced Columns

admin:
  pages:
    - slug: my-items
      type: list
      columns:
        - field: name
          label: Name
          format: truncate
          maxWidth: 250
        - field: status
          label: Status
          format: badge
          badges:
            active:
              label: Active
              color: green
            draft:
              label: Draft
              color: yellow
            archived:
              label: Archived
              color: gray
        - field: active
          label: Enabled
          format: toggle         # Clickable inline toggle
        - field: tags
          label: Tags
          format: tags           # Comma-separated or JSON array
        - field: modified
          label: Updated
          format: relative       # "2h ago", "3d ago"

Editor Page with Two-Column Layout

admin:
  pages:
    - slug: edit-item
      type: editor
      layout: two-column
      fields:
        - name: title
          type: text
          style: title           # Larger input
          required: true
        - name: content
          type: code-editor
          language: php
          minHeight: 400px
      sidebar:
        - section: Status
          fields:
            - field: active
              type: toggle
            - field: category
              type: select
              options:
                - value: general
                  label: General
                - value: admin
                  label: Admin Only
        - section: Settings
          fields:
            - field: priority
              type: number
              min: 1
              max: 100

Available Field Types (Implemented)

Type Component Props
text field-text style, placeholder, required
number field-number min, max, step, required
textarea field-textarea rows, placeholder, required
toggle field-toggle label
checkbox field-checkbox label
select field-select options, required
code-editor field-code-editor language, minHeight
date field-date required
datetime field-datetime required
url field-url placeholder, required
email field-email placeholder, required
json field-json rows
color field-color -

Available Column Formats (Implemented)

Format Description Config Options
toggle Clickable inline switch -
badge Colored status pill badges: { value: { label, color } }
boolean Yes/No badge -
number Formatted number decimals
currency Money format currency (default: USD)
date Formatted date -
datetime Formatted datetime -
relative Relative time -
image Thumbnail -
link External link -
email Mailto link -
progress Progress bar -
tags Tag pills -
truncate Truncated text maxWidth
code Monospace code -

Reference Implementation

See data/plugins/code-snippets/plugin.yaml for a complete example of enhanced blueprint configuration.