fluentcart-developer 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
package/.gitattributes ADDED
@@ -0,0 +1,2 @@
1
+ # Auto detect text files and perform LF normalization
2
+ * text=auto
package/CLAUDE.md ADDED
@@ -0,0 +1,22 @@
1
+ Skills are organized into bucket folders under `skills/`:
2
+
3
+ - `engineering/` — daily code work
4
+ - `productivity/` — daily non-code workflow tools
5
+ - `misc/` — kept around but rarely used, not promoted
6
+ - `personal/` — tied to my own setup, not promoted
7
+ - `in-progress/` — drafts not yet ready to ship
8
+ - `deprecated/` — no longer used
9
+
10
+ Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`. Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either.
11
+
12
+ Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.
13
+
14
+ Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `personal/`) use a flat list.
15
+
16
+ Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `personal/`, `in-progress/`, `deprecated/`) get **no** docs page.
17
+
18
+ Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).
19
+
20
+ [`ask-matt`](./skills/engineering/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
21
+
22
+ To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.
@@ -0,0 +1,73 @@
1
+ # Contributing to Atif Jubaer's Agent Skills
2
+
3
+ Thank you for your interest in contributing to this skills repository! We welcome contributions for new custom AI agent skills, updates to existing references, and improvements to our installer.
4
+
5
+ Here is a guide on how you (or your AI coding assistant) can add new skills and submit improvements.
6
+
7
+ ---
8
+
9
+ ## 1. How to Add a New Skill
10
+
11
+ To submit a new skill to the repository, follow these directory and file guidelines:
12
+
13
+ ### Step A: Create your Skill Folder
14
+ Skills are grouped under categories under the main `skills/` folder. Create a new directory matching your category and skill name:
15
+ ```bash
16
+ mkdir -p skills/skills/<category-name>/<skill-slug>
17
+ ```
18
+ *Example:* `skills/skills/productivity/wordpress-seo`
19
+
20
+ ### Step B: Create the `SKILL.md` file
21
+ Inside your skill folder, create a `SKILL.md` file containing a YAML frontmatter header and the main instruction set:
22
+ ```markdown
23
+ ---
24
+ name: "WordPress SEO Specialist"
25
+ description: "Optimizes meta tags, schema structures, and handles sitemap configurations."
26
+ ---
27
+
28
+ # WordPress SEO Specialist
29
+
30
+ Instructions for the AI assistant go here...
31
+ ```
32
+
33
+ > [!IMPORTANT]
34
+ > The `name` and `description` string values in the YAML frontmatter **must be wrapped in double quotes** (`"`). Strict YAML parsers will fail if special characters (like colons `:`) are used without quotes.
35
+
36
+ ### Step C: (Optional) Add Subdirectories
37
+ For Level 3 deep knowledge and presets, you can add:
38
+ * `references/` - For detailed developer manuals (linked from your main `SKILL.md` using relative paths).
39
+ * `assets/` - For boilerplate code, config templates, or resource assets.
40
+ * `scripts/` - For executable automation scripts (Node.js/Python).
41
+
42
+ ### Step D: Register in `skills.sh.json`
43
+ To make sure your skill displays under the correct section on the public `skills.sh` website, register your skill slug under a grouping in `skills.sh.json` at the root of the repository:
44
+ ```json
45
+ {
46
+ "title": "WordPress SEO",
47
+ "description": "Skills for search engine optimization.",
48
+ "skills": [
49
+ "wordpress-seo"
50
+ ]
51
+ }
52
+ ```
53
+
54
+ ---
55
+
56
+ ## 2. Testing Your Changes Locally
57
+
58
+ Before submitting a Pull Request, verify your skill installer executes correctly:
59
+
60
+ 1. Navigate to your repository root.
61
+ 2. Run the local installer sync:
62
+ ```bash
63
+ node bin/index.js init
64
+ ```
65
+ 3. Check that the skill files are compiled and successfully synced to your local editor profile directories (like Cursor, Claude, or Gemini).
66
+
67
+ ---
68
+
69
+ ## 3. Submitting a Pull Request
70
+
71
+ 1. Fork the repository.
72
+ 2. Commit your changes using clear commit summaries (e.g. `feat: add wordpress-seo skill`).
73
+ 3. Push to your fork and submit a Pull Request to the `main` branch.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matt Pocock
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,127 @@
1
+ # Atif Jubaer's Agent Skills Repository
2
+
3
+ [![npm version](https://img.shields.io/npm/v/fluentcart-developer.svg)](https://www.npmjs.com/package/fluentcart-developer)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+
6
+ A comprehensive, platform-agnostic knowledge base, instruction set, and CLI toolkit for FluentCart theme, plugin, shipping, and payment gateway development.
7
+
8
+ This repository provides ready-to-use configurations, reference manuals, and code boilerplates for all major AI coding assistants (Antigravity, Cursor, Claude Code, Windsurf, Cline, Zed, GitHub Copilot), enabling them to write correct, compatible code for FluentCart out-of-the-box.
9
+
10
+ ---
11
+
12
+ ## Included Skills
13
+
14
+ - **`FluentCart Developer`** (`fluentcart-developer`):
15
+ - **Complete Database Manual:** 34 DB migrations, all `wp_fct_*` schema tables, Eloquent ORM models, relationships, and Query Builder.
16
+ - **315+ Action & Filter Hooks:** 14 dedicated hook reference files covering order lifecycles, payment webhooks, cart fees, and admin UI.
17
+ - **15 REST API Modules (Core & Pro):** Orders, Products, Customers, Coupons, Subscriptions, Tax, Shipping, Settings, Email Notifications, Reports, Integrations, Files, Labels & Attributes, Dashboard & Utilities, Public Shop, Checkout, Customer Profile, Software Licensing (Pro), Roles & Permissions (Pro), Order Bumps (Pro).
18
+ - **5 Runnable Example Projects:** Custom Addon plugin, Fee Surcharge plugin, Payment Gateway plugin, Shipping Carrier, and Starter Child Theme.
19
+
20
+ ---
21
+
22
+ ## Installation & Setup
23
+
24
+ Choose the installation method that fits your environment and AI coding assistant:
25
+
26
+ ### Method 1: The `skills.sh` Method (Recommended for Cursor, Claude Code, Windsurf, Antigravity)
27
+
28
+ Install this skill directly into your project's local workspace using the official `skills.sh` manager:
29
+
30
+ ```bash
31
+ # Install specific skill into current project
32
+ npx skills add atifjubaer/skills --skill "fluentcart-developer"
33
+
34
+ # Or run interactively without flags to pick from list
35
+ npx skills add atifjubaer/skills
36
+ ```
37
+
38
+ ---
39
+
40
+ ### Method 2: Updating Installed Skills
41
+
42
+ To fetch and update your installed skills to the latest version on GitHub:
43
+
44
+ ```bash
45
+ # Update all installed skills in current workspace via skills.sh
46
+ npx skills update
47
+
48
+ # Or force reinstall the latest version from GitHub
49
+ npx skills add atifjubaer/skills --skill "fluentcart-developer" --force
50
+ ```
51
+
52
+ If you cloned this repository locally:
53
+ ```bash
54
+ git pull origin main
55
+ ```
56
+
57
+ ---
58
+
59
+ ### Method 3: Direct CLI Initializer & Interactive Wizard
60
+
61
+ Run the CLI command without arguments for an interactive selection prompt:
62
+
63
+ ```bash
64
+ npx fluentcart-developer
65
+ ```
66
+
67
+ Or pass direct command flags:
68
+
69
+ ```bash
70
+ # Initialize both global skills and current project rules for all IDEs
71
+ npx fluentcart-developer init
72
+
73
+ # Setup ONLY global skills (~/.gemini/, ~/.claude/)
74
+ npx fluentcart-developer global
75
+
76
+ # Setup ONLY local project rules
77
+ npx fluentcart-developer project
78
+
79
+ # Safely remove rule markers from project and global files
80
+ npx fluentcart-developer remove
81
+ ```
82
+
83
+ ---
84
+
85
+ ### Method 4: Manual Installation
86
+
87
+ If you prefer manual setup:
88
+ 1. **For Antigravity / Gemini**: Copy `SKILL.md`, `references/`, and `examples/` from `skills/fluentcart-developer/` into your global Gemini config path:
89
+ `~/.gemini/config/skills/fluentcart-developer/`
90
+ 2. **For Cursor / Windsurf / Cline / Zed**: Copy `.cursorrules` to your project root.
91
+ 3. **For Claude Code**: Copy `CLAUDE.md` to your project root.
92
+ 4. **For Web-based AIs**: Copy the content of `fluentcart-rules.md` and paste it into your chat session.
93
+
94
+ ---
95
+
96
+ ## Repository Folder Structure
97
+
98
+ ```
99
+ skills/
100
+ ├── README.md # Installation guide and repository overview
101
+ ├── package.json # Package configuration
102
+ ├── copy-skills.js # Automated skill sync builder
103
+ ├── skills.sh.json # skills.sh catalog layout configuration
104
+ ├── CLAUDE.md # Claude Code instructions
105
+ ├── CONTRIBUTING.md # Guidelines for repository contributors
106
+ ├── LICENSE # MIT License
107
+ ├── bin/
108
+ │ └── index.js # Interactive CLI runner
109
+ ├── .github/
110
+ │ └── workflows/
111
+ │ └── sync-docs.yml # GitHub Actions automated doc sync workflow
112
+ ├── references/ # Root reference manuals catalog
113
+ ├── examples/ # Standalone boilerplate code examples
114
+ │ ├── sample-custom-payment-gateway/
115
+ │ ├── sample-shipping-carrier/
116
+ │ └── fluentcart-starter-child-theme/
117
+ └── skills/
118
+ └── fluentcart-developer/ # 👈 Clean skill directory for skills.sh
119
+ ├── SKILL.md # Main index prompt file
120
+ ├── references/ # Complete developer manuals & schemas
121
+ └── examples/ # Standalone plugin & theme boilerplates
122
+ ```
123
+
124
+ ---
125
+
126
+ ## Created by
127
+ Developed and maintained by **Fastrsoft** (Atif Jubaer).
package/SKILL.md ADDED
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: "FluentCart Developer"
3
+ description: "Comprehensive knowledge base for FluentCart WordPress e-commerce plugin and theme development. Covers theme compatibility, template system, shortcodes, action/filter hooks, Elementor & Bricks integration, custom payment gateways, database models, REST API, fee systems, ghost products, subscriptions, and variations. Use this skill when building themes, plugins, or custom extensions for FluentCart."
4
+ ---
5
+
6
+ # FluentCart Developer Knowledge Base
7
+
8
+ This skill is the comprehensive developer index and reference guide for building WordPress themes, custom plugins, payment gateways, builder blocks, REST API extensions, and custom e-commerce workflows for FluentCart.
9
+
10
+ ---
11
+
12
+ ## 1. Advanced Developer References
13
+
14
+ For detailed code guides, schemas, and API specifications, consult the individual manuals in the `references/` directory:
15
+
16
+ - [Theme Development Guide](references/theme-development-guide.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/theme-development-guide.md)) — Complete guide for block and classic themes, template overrides, page types, and asset enqueuing.
17
+ - [Custom Payment Gateway Integration](references/payment-gateway-integration.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/payment-gateway-integration.md)) — Register custom gateways (`AbstractPaymentGateway`), settings schemas (`BaseGatewaySettings`), capture/refund methods, and card update redirect flows.
18
+ - [Paddle Payment Gateway Case Study](references/paddle-gateway-case-study.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/paddle-gateway-case-study.md)) — Implementation detail, setting fields schema, and webhook listener setup.
19
+ - [Ghost Product Selling (Non-Catalog Items)](references/ghost-product-selling.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/ghost-product-selling.md)) — Dynamically create virtual line items without adding products to the database catalog.
20
+ - [Fee System (Surcharges & Custom Fees)](references/fee-system-guide.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/fee-system-guide.md)) — Inject dynamic cart surcharges or store persistent fees in database tables.
21
+ - [Subscription Customization](references/subscription-customization.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/subscription-customization.md)) — Adjust renewal grace periods, custom billing cycles, auto-renew cancellation, and license key defaults.
22
+ - [Database Models & Query Builder](references/database-models-query-builder.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/database-models-query-builder.md)) — Query FluentCart records using Eloquent ORM models (`Order`, `Customer`, `Product`, `Subscription`, `Cart`).
23
+ - [Exhaustive Database Models Reference](references/database-models-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/database-models-reference.md)) — Deep field definitions, properties, and relationships for 30+ database models.
24
+ - [Database Schema Reference](references/database-schema-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/database-schema-reference.md)) — Tables, column types, and index catalog (`fc_orders`, `fc_order_items`, `fc_customers`, etc.).
25
+ - [Action & Filter Hooks Reference](references/hooks-actions-filters.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/hooks-actions-filters.md)) — Hook overview for order status changes, payment triggers, and UI extensions.
26
+ - [Exhaustive Action Hooks Reference](references/hooks-actions-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/hooks-actions-reference.md)) — Full catalog of actions triggered across the FluentCart lifecycle.
27
+ - [Exhaustive Filter Hooks Reference](references/hooks-filters-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/hooks-filters-reference.md)) — Full catalog of filters allowing data modification (e.g. `fluent_cart/transaction/max_refundable_amount`).
28
+ - [REST API Endpoints Reference](references/rest-api-endpoints-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/rest-api-endpoints-reference.md)) — Quick list of API paths and payload parameters.
29
+ - [Exhaustive REST API Reference](references/rest-api-reference.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/rest-api-reference.md)) — Complete request payloads, response schemas, and authentication endpoints.
30
+ - [REST API & Webhooks Guide](references/rest-api-webhooks.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/rest-api-webhooks.md)) — Authorization tokens, nonce validation, and outgoing webhook listeners.
31
+ - [Shipping, Storage, Licensing & Order Bumps](references/shipping-storage-licensing.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/shipping-storage-licensing.md)) — Custom shipping rate carriers, storage driver APIs, software license keys, and checkout bumps.
32
+ - [Gutenberg Blocks & Elementor / Bricks Widgets](references/gutenberg-blocks-elementor-widgets.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/gutenberg-blocks-elementor-widgets.md)) — Block names, elementor locations, and 15+ Bricks Builder blocks (v1.5.4+).
33
+ - [WP-CLI Commands Reference](references/wp-cli-commands.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/wp-cli-commands.md)) — CLI commands for maintenance, database synchronization, and migrations.
34
+ - [Easy Digital Downloads (EDD) Migration Guide](references/edd-migration-compatibility-guide.md) ([Online](https://raw.githubusercontent.com/atifjubaer/skills/master/references/edd-migration-compatibility-guide.md)) — Store migration steps and legacy EDD licensing endpoint emulation.
35
+
36
+ ### Standalone Code Examples (`examples/`)
37
+ For full boilerplate plugins and child theme files, consult the `examples/` directory:
38
+ - `examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php` — Complete custom payment gateway plugin boilerplate.
39
+ - `examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php` — Custom dynamic shipping calculation plugin.
40
+ - `examples/fluentcart-starter-child-theme/` — Starter child theme with `functions.php` theme support & `fluent-cart/checkout.php` override.
41
+
42
+ ---
43
+
44
+ ## 2. Core Framework & Architecture Setup
45
+
46
+ ### A. Theme Support Declaration
47
+ To enable FluentCart template loading, template overrides, and custom page detection in a theme, declare support in `functions.php`:
48
+
49
+ ```php
50
+ // Must be added to your theme's functions.php
51
+ add_action('after_setup_theme', function() {
52
+ add_theme_support('fluent_cart');
53
+ });
54
+ ```
55
+
56
+ ### B. Global Helper Functions & Formatting
57
+ ```php
58
+ // Check if FluentCart core is installed & active
59
+ if (defined('FLUENTCART_VERSION')) {
60
+ $version = FLUENTCART_VERSION; // e.g. '1.5.5'
61
+ }
62
+
63
+ // Detect current FluentCart page type
64
+ $pageType = \FluentCart\App\Services\Templates\TemplateService::getCurrentFcPageType();
65
+ // Returns: 'shop' | 'single_product' | 'product_taxonomy' | 'cart' | 'checkout' | 'receipt' | 'customer_dashboard'
66
+
67
+ // Access Store Settings API & Format Currency
68
+ $storeSettings = new \FluentCart\Api\StoreSettings();
69
+ $shopPageUrl = $storeSettings->getShopPage();
70
+ $currency = $storeSettings->getCurrency();
71
+
72
+ // Format monetary amounts using store settings
73
+ $formattedPrice = \FluentCart\App\Helpers\Helper::formatMoney(4990); // Formats $49.90
74
+ ```
75
+
76
+ ---
77
+
78
+ ## 3. Checkout Execution Lifecycle (Order of Operations)
79
+
80
+ Senior developers must understand the exact execution sequence during checkout processing:
81
+
82
+ ```
83
+ [Customer Submits Form]
84
+ │
85
+ ▼
86
+ 1. fluent_cart/checkout/before_validate_cart --> Add custom pre-checks
87
+ │
88
+ ▼
89
+ 2. fluent_cart/checkout/validate_cart --> Validate input data & stock
90
+ │
91
+ ▼
92
+ 3. fluent_cart/checkout/before_order_create --> Modify cart payload or totals
93
+ │
94
+ ▼
95
+ 4. fluent_cart/order_created --> Order model created in DB (Status: pending)
96
+ │
97
+ ▼
98
+ 5. Payment Gateway -> makePaymentFromPaymentInstance()
99
+ │
100
+ ▼
101
+ 6. (new StatusHelper($order))->syncOrderStatuses($transaction)
102
+ │
103
+ ├─► fluent_cart/payment_completed --> Payment record created
104
+ ├─► fluent_cart/order_paid --> Fired if transaction succeeded
105
+ └─► fluent_cart/order_status_updated --> Order status changed to 'processing'/'completed'
106
+ ```
107
+
108
+ ---
109
+
110
+ ## 4. Security, Nonce Validation & Capability Checks
111
+
112
+ All custom endpoints, AJAX actions, and admin settings handlers must follow strict security standards:
113
+
114
+ ```php
115
+ // 1. Check FluentCart Admin Permissions
116
+ if (!current_user_can('manage_options') && !fluent_cart_user_can('manage_fluentcart')) {
117
+ wp_send_json(['status' => 'error', 'message' => 'Unauthorized access'], 403);
118
+ }
119
+
120
+ // 2. Validate Nonce Verification in AJAX Endpoints
121
+ if (!check_ajax_referer('fluent_cart_nonce', 'nonce', false)) {
122
+ wp_send_json(['status' => 'error', 'message' => 'Invalid security token'], 403);
123
+ }
124
+
125
+ // 3. Input Sanitization Example
126
+ $cleanInput = sanitize_text_field($_POST['custom_field'] ?? '');
127
+ ```
package/bin/index.js ADDED
@@ -0,0 +1,281 @@
1
+ #!/usr/bin/env node
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const os = require('os');
6
+ const readline = require('readline');
7
+
8
+ // Helper to copy directory recursively
9
+ function copyDir(src, dest) {
10
+ fs.mkdirSync(dest, { recursive: true });
11
+ let entries = fs.readdirSync(src, { withFileTypes: true });
12
+
13
+ for (let entry of entries) {
14
+ let srcPath = path.join(src, entry.name);
15
+ let destPath = path.join(dest, entry.name);
16
+
17
+ if (entry.isDirectory()) {
18
+ copyDir(srcPath, destPath);
19
+ } else {
20
+ fs.copyFileSync(srcPath, destPath);
21
+ }
22
+ }
23
+ }
24
+
25
+ // Helper to safely write rules to a file with markers
26
+ function writeRulesWithMarkers(filePath, rulesContent, bannerName) {
27
+ try {
28
+ const dir = path.dirname(filePath);
29
+ fs.mkdirSync(dir, { recursive: true });
30
+
31
+ let existingContent = '';
32
+ if (fs.existsSync(filePath)) {
33
+ existingContent = fs.readFileSync(filePath, 'utf8');
34
+ }
35
+
36
+ const startMarker = `<!-- BEGIN ${bannerName} -->`;
37
+ const endMarker = `<!-- END ${bannerName} -->`;
38
+
39
+ if (existingContent.includes(startMarker)) {
40
+ const startIndex = existingContent.indexOf(startMarker);
41
+ const endIndex = existingContent.indexOf(endMarker) + endMarker.length;
42
+ const updatedContent = existingContent.substring(0, startIndex) +
43
+ startMarker + '\n' + rulesContent + '\n' + endMarker +
44
+ existingContent.substring(endIndex);
45
+ fs.writeFileSync(filePath, updatedContent, 'utf8');
46
+ console.log(`✓ Updated rules in: ${filePath}`);
47
+ } else {
48
+ const separator = existingContent ? '\n\n' : '';
49
+ const newContent = existingContent + separator + startMarker + '\n' + rulesContent + '\n' + endMarker;
50
+ fs.writeFileSync(filePath, newContent, 'utf8');
51
+ console.log(`✓ Added rules to: ${filePath}`);
52
+ }
53
+ } catch (err) {
54
+ console.error(`Error updating rules in ${filePath}:`, err.message);
55
+ }
56
+ }
57
+
58
+ // Helper to safely remove rules markers from a file
59
+ function removeRulesWithMarkers(filePath, bannerName) {
60
+ try {
61
+ if (!fs.existsSync(filePath)) return;
62
+ let existingContent = fs.readFileSync(filePath, 'utf8');
63
+ const startMarker = `<!-- BEGIN ${bannerName} -->`;
64
+ const endMarker = `<!-- END ${bannerName} -->`;
65
+
66
+ if (existingContent.includes(startMarker) && existingContent.includes(endMarker)) {
67
+ const startIndex = existingContent.indexOf(startMarker);
68
+ const endIndex = existingContent.indexOf(endMarker) + endMarker.length;
69
+ const updatedContent = existingContent.substring(0, startIndex) + existingContent.substring(endIndex);
70
+ fs.writeFileSync(filePath, updatedContent.trim(), 'utf8');
71
+ console.log(`✓ Removed rules from: ${filePath}`);
72
+ }
73
+ } catch (err) {
74
+ console.error(`Error removing rules from ${filePath}:`, err.message);
75
+ }
76
+ }
77
+
78
+ const args = process.argv.slice(2);
79
+ const initialCommand = args[0];
80
+
81
+ const homeDir = os.homedir();
82
+ const packageRoot = path.join(__dirname, '..');
83
+ const localSkillSrc = path.join(packageRoot, 'skills', 'fluentcart-developer');
84
+
85
+ // Global Paths
86
+ const geminiGlobalSkillDir = path.join(homeDir, '.gemini', 'config', 'skills', 'fluentcart-developer');
87
+ const geminiGlobalRulesFile = path.join(homeDir, '.gemini', 'config', 'AGENTS.md');
88
+ const claudeGlobalSkillDir = path.join(homeDir, '.claude', 'skills', 'fluentcart-developer');
89
+
90
+ // Zed Global Path
91
+ const zedGlobalRulesWin = path.join(process.env.APPDATA || path.join(homeDir, 'AppData', 'Roaming'), 'Zed', 'AGENTS.md');
92
+ const zedGlobalRulesUnix = path.join(homeDir, '.config', 'zed', 'AGENTS.md');
93
+
94
+ // Load rules source
95
+ const rulesFileSrc = path.join(packageRoot, 'fluentcart-rules.md');
96
+ let rulesContent = '';
97
+ if (fs.existsSync(rulesFileSrc)) {
98
+ rulesContent = fs.readFileSync(rulesFileSrc, 'utf8');
99
+ } else {
100
+ rulesContent = `# FluentCart Development Rules\n\nEnsure functions.php includes add_theme_support('fluent_cart');`;
101
+ }
102
+
103
+ // Global install function
104
+ function installGlobal() {
105
+ console.log('\nInstalling FluentCart Developer Skill globally for all IDEs...');
106
+
107
+ const srcSkillMd = path.join(localSkillSrc, 'SKILL.md');
108
+ const srcReferences = path.join(localSkillSrc, 'references');
109
+ const srcExamples = path.join(localSkillSrc, 'examples');
110
+
111
+ // 1. Antigravity/Gemini Global Skill & Rules
112
+ try {
113
+ fs.mkdirSync(geminiGlobalSkillDir, { recursive: true });
114
+ if (fs.existsSync(srcSkillMd)) fs.copyFileSync(srcSkillMd, path.join(geminiGlobalSkillDir, 'SKILL.md'));
115
+ if (fs.existsSync(srcReferences)) copyDir(srcReferences, path.join(geminiGlobalSkillDir, 'references'));
116
+ if (fs.existsSync(srcExamples)) copyDir(srcExamples, path.join(geminiGlobalSkillDir, 'examples'));
117
+
118
+ writeRulesWithMarkers(geminiGlobalRulesFile, rulesContent, 'FLUENTCART_RULES');
119
+ console.log('✓ Global skill and rules installed for Antigravity/Gemini!');
120
+ } catch (err) {
121
+ console.error('Error installing global Antigravity skill:', err.message);
122
+ }
123
+
124
+ // 2. Claude Code Global Skill
125
+ try {
126
+ fs.mkdirSync(claudeGlobalSkillDir, { recursive: true });
127
+ if (fs.existsSync(srcSkillMd)) fs.copyFileSync(srcSkillMd, path.join(claudeGlobalSkillDir, 'SKILL.md'));
128
+ if (fs.existsSync(srcReferences)) copyDir(srcReferences, path.join(claudeGlobalSkillDir, 'references'));
129
+ if (fs.existsSync(srcExamples)) copyDir(srcExamples, path.join(claudeGlobalSkillDir, 'examples'));
130
+
131
+ console.log('✓ Global skill installed for Claude Code!');
132
+ } catch (err) {
133
+ console.error('Error installing global Claude Code skill:', err.message);
134
+ }
135
+
136
+ // 3. Zed Global Rules
137
+ try {
138
+ const isWindows = process.platform === 'win32';
139
+ const zedGlobalRulesPath = isWindows ? zedGlobalRulesWin : zedGlobalRulesUnix;
140
+ writeRulesWithMarkers(zedGlobalRulesPath, rulesContent, 'FLUENTCART_RULES');
141
+ console.log('✓ Global rules installed for Zed!');
142
+ } catch (err) {
143
+ console.error('Error installing global Zed rules:', err.message);
144
+ }
145
+
146
+ console.log('✓ Global installation completed successfully!\n');
147
+ }
148
+
149
+ // Project install function
150
+ function installProject() {
151
+ console.log('\nInitializing project-specific skills and rules in current directory...');
152
+ const cwd = process.cwd();
153
+ const srcSkillMd = path.join(localSkillSrc, 'SKILL.md');
154
+ const srcReferences = path.join(localSkillSrc, 'references');
155
+ const srcExamples = path.join(localSkillSrc, 'examples');
156
+
157
+ try {
158
+ // A. Project rules files
159
+ if (fs.existsSync(path.join(packageRoot, '.cursorrules'))) {
160
+ fs.copyFileSync(path.join(packageRoot, '.cursorrules'), path.join(cwd, '.cursorrules'));
161
+ fs.copyFileSync(path.join(packageRoot, '.cursorrules'), path.join(cwd, '.windsurfrules'));
162
+ fs.copyFileSync(path.join(packageRoot, '.cursorrules'), path.join(cwd, '.clinerules'));
163
+ fs.copyFileSync(path.join(packageRoot, '.cursorrules'), path.join(cwd, '.rules'));
164
+ }
165
+ if (fs.existsSync(path.join(packageRoot, 'CLAUDE.md'))) {
166
+ fs.copyFileSync(path.join(packageRoot, 'CLAUDE.md'), path.join(cwd, 'CLAUDE.md'));
167
+ }
168
+
169
+ const copilotDir = path.join(cwd, '.github');
170
+ fs.mkdirSync(copilotDir, { recursive: true });
171
+ if (fs.existsSync(path.join(packageRoot, '.cursorrules'))) {
172
+ fs.copyFileSync(path.join(packageRoot, '.cursorrules'), path.join(copilotDir, 'copilot-instructions.md'));
173
+ }
174
+
175
+ console.log('✓ Created project rules files (.cursorrules, .windsurfrules, .clinerules, .rules, CLAUDE.md, .github/copilot-instructions.md)');
176
+
177
+ // B. Project-level Skills
178
+ const geminiLocalSkillDir = path.join(cwd, '.agents', 'skills', 'fluentcart-developer');
179
+ fs.mkdirSync(geminiLocalSkillDir, { recursive: true });
180
+ if (fs.existsSync(srcSkillMd)) fs.copyFileSync(srcSkillMd, path.join(geminiLocalSkillDir, 'SKILL.md'));
181
+ if (fs.existsSync(srcReferences)) copyDir(srcReferences, path.join(geminiLocalSkillDir, 'references'));
182
+ if (fs.existsSync(srcExamples)) copyDir(srcExamples, path.join(geminiLocalSkillDir, 'examples'));
183
+
184
+ console.log('✓ Created project skills directory (.agents/skills/fluentcart-developer)');
185
+ console.log('✓ Project initialization completed successfully!\n');
186
+ } catch (err) {
187
+ console.error('Error initializing project rules:', err.message);
188
+ }
189
+ }
190
+
191
+ // Remove rules function
192
+ function removeRules() {
193
+ console.log('\nRemoving FluentCart rules from global and project files...');
194
+ const cwd = process.cwd();
195
+
196
+ removeRulesWithMarkers(geminiGlobalRulesFile, 'FLUENTCART_RULES');
197
+
198
+ const isWindows = process.platform === 'win32';
199
+ const zedGlobalRulesPath = isWindows ? zedGlobalRulesWin : zedGlobalRulesUnix;
200
+ removeRulesWithMarkers(zedGlobalRulesPath, 'FLUENTCART_RULES');
201
+
202
+ // Remove project rules files
203
+ const projectFilesToRemove = [
204
+ path.join(cwd, '.cursorrules'),
205
+ path.join(cwd, '.windsurfrules'),
206
+ path.join(cwd, '.clinerules'),
207
+ path.join(cwd, '.rules'),
208
+ path.join(cwd, 'CLAUDE.md'),
209
+ path.join(cwd, '.github', 'copilot-instructions.md')
210
+ ];
211
+
212
+ projectFilesToRemove.forEach(file => {
213
+ if (fs.existsSync(file)) {
214
+ try {
215
+ fs.unlinkSync(file);
216
+ console.log(`✓ Removed: ${file}`);
217
+ } catch (err) {
218
+ console.error(`Error removing ${file}:`, err.message);
219
+ }
220
+ }
221
+ });
222
+
223
+ // Remove local skills directory
224
+ const geminiLocalSkillDir = path.join(cwd, '.agents', 'skills', 'fluentcart-developer');
225
+ if (fs.existsSync(geminiLocalSkillDir)) {
226
+ try {
227
+ fs.rmSync(geminiLocalSkillDir, { recursive: true, force: true });
228
+ console.log(`✓ Removed project skill directory: ${geminiLocalSkillDir}`);
229
+ } catch (err) {
230
+ console.error(`Error removing project skill dir:`, err.message);
231
+ }
232
+ }
233
+
234
+ console.log('✓ Removal completed!\n');
235
+ }
236
+
237
+ // CLI Command Router
238
+ if (initialCommand === 'init') {
239
+ installGlobal();
240
+ installProject();
241
+ } else if (initialCommand === 'global') {
242
+ installGlobal();
243
+ } else if (initialCommand === 'project') {
244
+ installProject();
245
+ } else if (initialCommand === 'remove') {
246
+ removeRules();
247
+ } else {
248
+ // Interactive Wizard
249
+ const rl = readline.createInterface({
250
+ input: process.stdin,
251
+ output: process.stdout
252
+ });
253
+
254
+ console.log('\n======================================================');
255
+ console.log(' FluentCart Developer Skill & Rules Installer');
256
+ console.log('======================================================');
257
+ console.log('Select an installation option:');
258
+ console.log(' 1. Initialize BOTH Global & Current Project Rules (Recommended)');
259
+ console.log(' 2. Install ONLY Global Skill (~/.gemini/, ~/.claude/, Zed)');
260
+ console.log(' 3. Setup ONLY Current Project Rules & Local Skills (.agents/)');
261
+ console.log(' 4. Remove FluentCart rules & skills');
262
+ console.log(' 5. Exit');
263
+ console.log('------------------------------------------------------');
264
+
265
+ rl.question('Enter your choice (1-5): ', (answer) => {
266
+ const choice = answer.trim();
267
+ if (choice === '1') {
268
+ installGlobal();
269
+ installProject();
270
+ } else if (choice === '2') {
271
+ installGlobal();
272
+ } else if (choice === '3') {
273
+ installProject();
274
+ } else if (choice === '4') {
275
+ removeRules();
276
+ } else {
277
+ console.log('Exiting without changes.');
278
+ }
279
+ rl.close();
280
+ });
281
+ }