wp-uikit-cli 1.0.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 WP-UIkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,330 @@
+<div align="center">
+
+# ⚡ 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.
+
+[![npm version](https://img.shields.io/npm/v/wp-uikit-cli.svg?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/wp-uikit-cli)
+[![npm downloads](https://img.shields.io/npm/dm/wp-uikit-cli.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/wp-uikit-cli)
+[![license](https://img.shields.io/npm/l/wp-uikit-cli.svg?style=flat-square&color=green)](./LICENSE)
+[![node](https://img.shields.io/node/v/wp-uikit-cli.svg?style=flat-square)](https://nodejs.org)
+
+</div>
+
+---
+
+## 📖 Table of Contents
+
+- [✨ Features](#-features)
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [🧭 Commands](#-commands)
+  - [`sf create`](#-sf-create)
+  - [`sf clean`](#-sf-clean)
+  - [`sf debug`](#-sf-debug)
+  - [`sf deploy`](#-sf-deploy)
+  - [`sf zip`](#-sf-zip)
+- [🧩 Traits System](#-traits-system)
+- [📁 Generated File Structure](#-generated-file-structure)
+- [⚙️ How It Works](#️-how-it-works)
+- [🛠️ Requirements](#️-requirements)
+- [❓ FAQ](#-faq)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-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:
+
+```bash
+npm install -g wp-uikit-cli
+```
+
+Or run it on-demand without installing:
+
+```bash
+npx wp-uikit-cli create
+```
+
+> 💡 **Tip:** Run `sf --help` anytime to see all available commands.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 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**.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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`](./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
+
+<details>
+<summary>📋 Example traits already available in this project</summary>
+
+`AvatarTrait` · `BadgeTrait` · `ButtonTrait` · `DescriptionTrait` · `FancyAnimatedTextTrait` · `HeaderTrait` · `HeadingTrait` · `HtmlSnippetTrait` · `ListTrait` · `ParagraphTrait` · `ProgressbarTrait` · `RatingTrait` · `RepeaterAvatarTrait` · `RepeaterBadgeTrait` · `RepeaterButtonTrait` · `RepeaterListTrait` · `RepeaterRadialProgressbarTrait` · ...and more
+
+</details>
+
+---
+
+## 📁 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
+
+```mermaid
+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/`](./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
+
+<details>
+<summary><strong>Does <code>sf deploy</code> modify my source files permanently?</strong></summary>
+<br>
+Yes — minification replaces original <code>.js</code>/<code>.css</code> files with <code>.min.js</code>/<code>.min.css</code> in your working directory, and the dev-mode flag is flipped to <code>false</code>. Always deploy from a clean git state so you can diff/revert if needed.
+</details>
+
+<details>
+<summary><strong>Why does the first command feel slightly slower the very first time?</strong></summary>
+<br>
+Heavy dependencies (<code>adm-zip</code>, <code>terser</code>, <code>clean-css</code>) are <strong>lazy-loaded</strong> only when a command that needs them (<code>deploy</code>, <code>zip</code>) actually runs — keeping <code>create</code>, <code>clean</code>, and <code>debug</code> fast at all times.
+</details>
+
+<details>
+<summary><strong>Can I customize the generated widget/trait templates?</strong></summary>
+<br>
+Yes! Edit the files in the <code>stubs/</code> directory. They support <code>{{PLACEHOLDER}}</code> tokens which are replaced at generation time.
+</details>
+
+---
+
+## 🤝 Contributing
+
+Contributions, issue reports, and feature ideas are welcome!
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feature/amazing-thing`
+3. Commit your changes: `git commit -m "Add amazing thing"`
+4. Push and open a Pull Request
+
+---
+
+## 📄 License
+
+Released under the **[MIT License](./LICENSE)**.
+
+<div align="center">
+
+Made with ❤️ for the **SF Framework** & **SF Widget** ecosystem.
+
+</div>