⚡ WP-UIkit CLI

Scaffold. Debug. Clean. Deploy. A blazing-fast command-line toolkit for building SF Framework & SF Widget (Elementor) plugin widgets and traits — in seconds, not minutes.

📖 Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 🧭 Commands
  • sf create
  • sf clean
  • sf debug
  • sf deploy
  • sf zip
• 🧩 Traits System
• 📁 Generated File Structure
• ⚙️ How It Works
• 🛠️ Requirements
• ❓ FAQ
• 🤝 Contributing
• 📄 License

✨ Features

| | Feature | Description | |---|---|---| | 🧱 | Widget Scaffolding | Interactively generate a fully wired Elementor widget (.php, .css, .js, docs) from stubs. | | 🧩 | Trait Scaffolding | Create reusable PHP traits and auto-register them so widgets can consume shared controls. | | 🔗 | Smart Trait Wiring | Automatically parses trait method signatures and injects correct use statements + method calls into your widget class. | | 🧹 | String Localization | sf clean auto-wraps raw strings in esc_html__() with the sf-widget text-domain — for one widget or the whole project. | | 🐛 | One-Line WP Debugging | Toggle WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY in wp-config.php instantly. | | 🚀 | One-Command Deploy | Minifies JS/CSS, disables dev-mode flags, strips .gitignore, zips the plugin, and updates update.json — all in one go. | | 📦 | Instant Zipping | Package your current working directory into a distributable .zip archive. | | ⚡ | Lazy-Loaded Dependencies | Heavy libs (adm-zip, terser, clean-css) load on-demand — keeping every command snappy. | | 🎨 | Beautiful CLI UX | ASCII banners, spinners, colorized tables, and clear success/error states via figlet, ora, and chalk. |

📦 Installation

Install globally to use the sf command anywhere:

npm install -g wp-uikit-cli

Or run it on-demand without installing:

npx wp-uikit-cli create

💡 Tip: Run sf --help anytime to see all available commands.

🚀 Quick Start

# 1️⃣ Navigate to your plugin root (e.g. sf-widget/)
cd sf-widget

# 2️⃣ Scaffold a new widget or trait interactively
sf create

# 3️⃣ Localize all visible strings for WordPress i18n
sf clean --all

# 4️⃣ Turn on WP debugging while you build
sf debug on

# 5️⃣ Ship it 🚢
sf deploy --widget

🧭 Commands

🧱 sf create

Interactively scaffold a Widget or a Trait.

sf create

You'll be walked through prompts like:

? Widget name (e.g. Heading, Icon Box):  Pricing Table
? Create CSS file? (Y/n)
? Create JS file? (y/N)
? Elementor icon class (e.g. eicon-star): eicon-price-table
? Select traits to include: (Use arrow keys, <space> to select)
  ◉ ButtonTrait
  ◉ HeadingTrait
  ◯ RatingTrait

The CLI then:

• ✅ Generates widgets/<slug>.php from widget.php.stub
• ✅ Optionally generates CSS/JS companions
• ✅ Auto-detects selected traits' PHP method signatures
• ✅ Injects correct use statements, register_*_controls(), and render_*() calls
• ✅ Warns before overwriting existing files

🧹 sf clean

Wrap raw, user-visible strings in esc_html__() with the sf-widget text domain — a must for WordPress i18n and plugin review compliance.

sf clean <widgetName>      # Clean a single widget
sf clean --all             # Clean every widget & print a report

Sample output:

📊 Localization Report

│ Widget          │ Status  │ esc_html Count │ Domain     │
├─────────────────┼─────────┼─────────────────┼────────────┤
│ pricing-table    │ ✓ Done  │ 12               │ sf-widget  │
│ testimonial      │ ✓ Done  │ 7                │ sf-widget  │

✨ Summary
  ├─ Total widgets processed: 2
  ├─ Total esc_html__() added: 19
  └─ Domain used: sf-widget

It intelligently:

• Normalizes existing esc_html__() / __() calls to the correct domain
• Wraps plain label, title, description, placeholder, and raw strings
• Avoids double-wrapping already-escaped strings

🐛 sf debug

Toggle WordPress debug mode without ever opening wp-config.php yourself.

sf debug on     # Enables WP_DEBUG, WP_DEBUG_LOG, WP_DEBUG_DISPLAY
sf debug off    # Cleanly reverts back to production settings

• 🔍 Automatically walks up the directory tree to locate wp-config.php
• 📝 Appends/updates the debug block safely without breaking existing config
• 📣 Prints exactly where to check your logs (wp-content/debug.log)

🚀 sf deploy

The release button for sf-framework and sf-widget plugins.

sf deploy --framework   # Deploy the SF Framework plugin
sf deploy --widget      # Deploy the SF Widget plugin

You'll be prompted for a destination folder and a new version (X.Y.Z), then the CLI automatically:

1. 🗜️ Minifies every .js file with Terser → *.min.js
2. 🎨 Minifies every .css file with CleanCSS → *.min.css
3. 🚩 Flips the dev-mode constant (SF_DEVELOPMENT_MODE / SF_FRAMEWORK_DEVELOPMENT_MODE) to false
4. 🧹 Removes .gitignore (and the fonts folder for widget builds)
5. 📦 Zips the plugin (excluding .git, node_modules)
6. 📤 Moves the zip to your destination folder
7. 📝 Updates update.json with the new version & download URL
8. ✅ Prints a full summary + suggested git commands

Sample output:

  ✔  Deploy complete — sf-widget v1.4.0

  Output
  ├─ Zip   D:\Releases\sf-widget-1.4.0.zip
  └─ JSON  D:\Releases\update.json

  Next steps
  ├─  Open the destination folder in your file manager
  ├─  Review the changes — check update.json & zip
  ├─  Stage all changes:  git add .
  ├─  Commit:             git commit -m "Release sf-widget v1.4.0"
  └─  Push:               git push

📦 sf zip

Quickly zip the current working directory.

sf zip                 # Uses the current folder name as the zip name
sf zip my-plugin        # Custom output name → my-plugin.zip

🧩 Traits System

Traits let you share reusable Elementor controls (buttons, ratings, badges, avatars, progress bars, etc.) across multiple widgets without duplicating code.

• Trait files live in core/includes/traits/*-trait.php
• Registered traits are tracked in traits.json
• Running sf create automatically syncs this registry by scanning your traits folder
• When you attach traits to a widget, the CLI reads the trait's PHP source, extracts its register_*_controls() / render_*() method signatures, and generates matching use + call-site code — no manual wiring required

AvatarTrait · BadgeTrait · ButtonTrait · DescriptionTrait · FancyAnimatedTextTrait · HeaderTrait · HeadingTrait · HtmlSnippetTrait · ListTrait · ParagraphTrait · ProgressbarTrait · RatingTrait · RepeaterAvatarTrait · RepeaterBadgeTrait · RepeaterButtonTrait · RepeaterListTrait · RepeaterRadialProgressbarTrait · ...and more

📁 Generated File Structure

Running sf create for a widget named "Pricing Table" produces:

📁 your-plugin/
├── widgets/
│   └── pricing-table.php        # Widget class with traits wired in
└── assets/
    ├── css/
    │   └── pricing-table.css
    └── js/
        └── pricing-table.js

⚙️ How It Works

flowchart LR
    A[sf create] --> B{Widget or Trait?}
    B -->|Widget| C[Prompt for name, assets, icon, traits]
    C --> D[Parse selected trait PHP files]
    D --> E[Inject use + register/render calls]
    E --> F[Write from stubs/*.stub]
    B -->|Trait| G[Prompt for trait name]
    G --> H[Write trait.php.stub → core/includes/traits/]

All generated files come from customizable templates in stubs/:

| Stub | Purpose | |---|---| | widget.php.stub | Base Elementor widget class | | style.css.stub | Widget stylesheet | | script.js.stub | Widget frontend script | | trait.php.stub | Reusable trait skeleton |

🛠️ Requirements

• Node.js ≥ 16
• A project following the SF Framework / SF Widget directory conventions (widgets/, assets/, core/includes/traits/)
• WordPress + Elementor installation for sf debug (looks for wp-config.php)

❓ FAQ

📄 License

Released under the MIT License.

Made with ❤️ from WP-UIkit Team for the SF Framework & SF Widget ecosystem.