@vc-shell/create-vc-app 1.1.98-rc.5 → 1.1.99-alpha.0

package/dist/templates/base/ai-guides/prompts/cli-usage.md

@@ -0,0 +1,640 @@
+# CLI Usage Guide
+
+Complete reference for using `create-vc-app` CLI tool to scaffold applications and generate modules.
+
+## When to Use This
+
+Use these prompts when you need to:
+- Create a new VC Shell application
+- Generate modules, blades, or widgets
+- Add functionality to existing projects
+- Automate module creation with specific configurations
+
+## Prerequisites
+
+- Node.js 18 or higher installed
+- Understanding of your project requirements
+- API structure (if integrating with backend)
+
+## Quick Reference
+
+### Create New Application
+
+**Interactive Mode (Recommended for first-time users):**
+```bash
+npx create-vc-app my-app
+```
+
+**Non-Interactive Mode:**
+```bash
+npx create-vc-app my-app \
+  --package-name "my-app" \
+  --base-path "/apps/my-app/" \
+  --skip-module-gen
+```
+
+### Generate Module
+
+**Interactive Mode:**
+```bash
+cd my-app
+npx create-vc-app blade
+# Select: "Module (with blades)"
+```
+
+**Non-Interactive Mode:**
+```bash
+npx create-vc-app blade \
+  --module products \
+  --type grid \
+  --name products-list \
+  --composable \
+  --locales \
+  --is-workspace
+```
+
+---
+
+## Detailed Examples
+
+### 1. Create New Application with Module
+
+**Scenario:** Starting completely from scratch
+
+**Prompt for AI:**
+```
+Create a new VC Shell application called "my-shop" with a products module.
+
+The products module should have:
+- Grid blade (list view) with table
+- Details blade (form view) with these fields:
+  - name (text, required)
+  - price (currency, required)
+  - description (editor, optional)
+  - category (select: Electronics, Clothing, Books)
+  - inStock (switch toggle)
+
+Use the CLI to generate everything.
+```
+
+**AI will run:**
+```bash
+# Create app
+npx create-vc-app my-shop
+
+# Then follow interactive prompts:
+# - Module name: products
+# - Entity name: Product
+# - Create both blades: yes
+# - Workspace blade: Grid blade
+# - Customize form: yes
+# - Add fields as specified
+```
+
+---
+
+### 2. Add Module to Existing Application
+
+**Scenario:** You have an app, need to add new module
+
+**Prompt for AI:**
+```
+Add an orders module to my existing application.
+
+Requirements:
+- Grid blade with columns: orderNumber, customer, total, status, date
+- Details blade with form fields:
+  - orderNumber (text, read-only)
+  - customer (text, required)
+  - total (currency, required)
+  - status (select: pending, processing, shipped, delivered)
+  - orderDate (date, required)
+  - notes (textarea, optional)
+
+Generate using CLI.
+```
+
+**AI will run:**
+```bash
+cd /path/to/your-app
+
+npx create-vc-app blade \
+  --module orders \
+  --type grid \
+  --name orders-list \
+  --composable \
+  --locales \
+  --is-workspace
+
+# Then add details blade
+npx create-vc-app blade \
+  --module orders \
+  --type details \
+  --name order-details \
+  --composable \
+  --locales \
+  --form-fields '[
+    {"name":"orderNumber","type":"VcInput","props":"{\"required\":true,\"readonly\":true}"},
+    {"name":"customer","type":"VcInput","props":"{\"required\":true}"},
+    {"name":"total","type":"VcInputCurrency","props":"{\"required\":true}"},
+    {"name":"status","type":"VcSelect","props":"{\"required\":true,\"options\":\"pending,processing,shipped,delivered\"}"},
+    {"name":"orderDate","type":"VcInput","props":"{\"type\":\"date\",\"required\":true}"},
+    {"name":"notes","type":"VcTextarea","props":"{}"}
+  ]'
+```
+
+---
+
+### 3. Generate Module with Custom Form (Non-Interactive)
+
+**Scenario:** Automated generation with specific form structure
+
+**Prompt for AI:**
+```
+Generate a complete products module using CLI in non-interactive mode.
+
+Form fields:
+- title (text input, required)
+- sku (text input, required)
+- description (rich text editor)
+- price (currency input, required)
+- compareAtPrice (currency input)
+- category (select dropdown with options: Electronics, Clothing, Books, Home)
+- tags (multivalue input)
+- featured (switch toggle)
+- images (gallery)
+- status (radio buttons: draft, active, archived)
+
+Create both list and details blades.
+```
+
+**AI will run:**
+```bash
+npx create-vc-app blade \
+  --module products \
+  --type grid \
+  --name products \
+  --composable \
+  --locales \
+  --is-workspace
+
+npx create-vc-app blade \
+  --module products \
+  --type details \
+  --name product-details \
+  --composable \
+  --locales \
+  --skip-form-editor \
+  --form-fields '[
+    {"name":"title","label":"Product Title","type":"VcInput","props":"{\"required\":true}"},
+    {"name":"sku","label":"SKU","type":"VcInput","props":"{\"required\":true}"},
+    {"name":"description","label":"Description","type":"VcEditor","props":"{}"},
+    {"name":"price","label":"Price","type":"VcInputCurrency","props":"{\"required\":true}"},
+    {"name":"compareAtPrice","label":"Compare at Price","type":"VcInputCurrency","props":"{}"},
+    {"name":"category","label":"Category","type":"VcSelect","props":"{\"required\":true,\"options\":\"Electronics,Clothing,Books,Home\"}"},
+    {"name":"tags","label":"Tags","type":"VcMultivalue","props":"{}"},
+    {"name":"featured","label":"Featured","type":"VcSwitch","props":"{}"},
+    {"name":"images","label":"Images","type":"VcGallery","props":"{}"},
+    {"name":"status","label":"Status","type":"VcRadioButton","props":"{\"options\":\"draft,active,archived\"}"}
+  ]'
+```
+
+---
+
+### 4. Add Widget to Existing Blade
+
+**Scenario:** Enhance blade with widget component
+
+**Prompt for AI:**
+```
+Add a statistics widget to the product-details blade.
+
+The widget should:
+- Show product views count
+- Show sales count
+- Show revenue
+- Be positioned on the right side
+
+Use CLI to generate and register the widget.
+```
+
+**AI will run:**
+```bash
+npx create-vc-app blade --widget
+
+# Interactive prompts:
+# - Select module: products
+# - Select blade: product-details
+# - Widget name: product-stats
+```
+
+---
+
+### 5. Generate Only Grid Blade (List Only)
+
+**Scenario:** You only need a list view, no details
+
+**Prompt for AI:**
+```
+Create a categories module with only a list view (no details blade).
+
+List should show:
+- Category name
+- Number of products
+- Status (active/inactive)
+- Last modified date
+
+Use CLI.
+```
+
+**AI will run:**
+```bash
+npx create-vc-app blade \
+  --module categories \
+  --type grid \
+  --name categories \
+  --composable \
+  --locales \
+  --is-workspace
+```
+
+---
+
+### 6. Generate Only Details Blade (Form Only)
+
+**Scenario:** You need a settings page (form without list)
+
+**Prompt for AI:**
+```
+Create a settings module with only a details form (no list).
+
+Form fields:
+- storeName (text, required)
+- storeEmail (text, required, email validation)
+- currency (select: USD, EUR, GBP)
+- timezone (select with multiple options)
+- enableNotifications (switch)
+- maintenanceMode (switch)
+
+Use CLI.
+```
+
+**AI will run:**
+```bash
+npx create-vc-app blade \
+  --module settings \
+  --type details \
+  --name settings \
+  --composable \
+  --locales \
+  --is-workspace \
+  --form-fields '[
+    {"name":"storeName","label":"Store Name","type":"VcInput","props":"{\"required\":true}"},
+    {"name":"storeEmail","label":"Store Email","type":"VcInput","props":"{\"required\":true,\"type\":\"email\"}"},
+    {"name":"currency","label":"Currency","type":"VcSelect","props":"{\"required\":true,\"options\":\"USD,EUR,GBP\"}"},
+    {"name":"timezone","label":"Timezone","type":"VcSelect","props":"{\"required\":true}"},
+    {"name":"enableNotifications","label":"Enable Notifications","type":"VcSwitch","props":"{}"},
+    {"name":"maintenanceMode","label":"Maintenance Mode","type":"VcSwitch","props":"{}"}
+  ]'
+```
+
+---
+
+## CLI Command Reference
+
+### Application Creation
+
+```bash
+npx create-vc-app [project-name] [options]
+```
+
+**Options:**
+- `--name, --app-name <name>` - Application name
+- `--package-name <name>` - Package name (defaults to app name)
+- `--base-path <path>` - Base path for the application (default: /apps/<app-name>/)
+- `--skip-module-gen` - Skip initial module generation
+- `--skip-form-editor` - Skip interactive form builder
+- `--form-fields <json>` - JSON string with form field definitions
+- `--overwrite` - Overwrite existing files without confirmation
+- `--help, -h` - Show help
+- `--version, -v` - Show version
+
+**Examples:**
+```bash
+# Basic app
+npx create-vc-app my-app
+
+# App without module
+npx create-vc-app my-app --skip-module-gen
+
+# App with custom base path
+npx create-vc-app my-app --base-path "/custom/path/"
+```
+
+---
+
+### Module/Blade Generation
+
+```bash
+npx create-vc-app blade [options]
+```
+
+**Options:**
+- `--module <name>` - Target module name
+- `--type <grid|details>` - Blade type
+- `--name <name>` - Blade name
+- `--composable` - Generate composable (default: true)
+- `--locales` - Generate locales (default: true)
+- `--is-workspace` - Mark blade as workspace blade (main module blade)
+- `--widget` - Generate widget instead of blade
+- `--path <path>` - Target path for generation
+- `--skip-form-editor` - Skip interactive form builder
+- `--form-fields <json>` - JSON array of form field definitions
+
+**Examples:**
+```bash
+# Interactive mode
+npx create-vc-app blade
+
+# Generate grid blade
+npx create-vc-app blade --module products --type grid --name products
+
+# Generate details blade with form
+npx create-vc-app blade --module products --type details --name product-details
+
+# Generate widget
+npx create-vc-app blade --widget
+```
+
+---
+
+## Form Field Types Reference
+
+When using `--form-fields` option, use this JSON structure:
+
+```typescript
+interface FormField {
+  name: string;          // Field property name
+  label?: string;        // Display label (optional, uses name if not provided)
+  type: FieldType;       // Component type (see below)
+  props?: string;        // JSON string of component props
+}
+```
+
+**Available Field Types:**
+
+| Type | Component | Use Case | Example Props |
+|------|-----------|----------|---------------|
+| `VcInput` | Text input | Basic text, numbers, dates | `{"required":true,"type":"text"}` |
+| `VcTextarea` | Multi-line text | Long text, comments | `{"rows":5}` |
+| `VcSelect` | Dropdown | Single selection | `{"required":true,"options":"Option1,Option2"}` |
+| `VcEditor` | Rich text editor | Formatted content | `{"placeholder":"Enter content"}` |
+| `VcSwitch` | Toggle | Boolean values | `{}` |
+| `VcGallery` | Image gallery | Multiple images | `{}` |
+| `VcInputCurrency` | Currency input | Money values | `{"required":true}` |
+| `VcRadioButton` | Radio buttons | Single choice from list | `{"options":"Option1,Option2,Option3"}` |
+| `VcCheckbox` | Checkbox | Single boolean | `{"label":"Agree to terms"}` |
+| `VcMultivalue` | Tag input | Multiple text values | `{"placeholder":"Add tag"}` |
+| `VcField` | Read-only field | Display-only data | `{}` |
+
+**Example JSON for --form-fields:**
+```json
+[
+  {
+    "name": "title",
+    "label": "Product Title",
+    "type": "VcInput",
+    "props": "{\"required\":true}"
+  },
+  {
+    "name": "price",
+    "label": "Price",
+    "type": "VcInputCurrency",
+    "props": "{\"required\":true}"
+  },
+  {
+    "name": "description",
+    "label": "Description",
+    "type": "VcEditor",
+    "props": "{}"
+  }
+]
+```
+
+---
+
+## Expected Output
+
+### After Creating Application
+
+```
+✨ Application created successfully!
+
+📊 Summary:
+   Location: /path/to/my-app
+   Package: my-app
+   Base path: /apps/my-app/
+   Files created: 60+
+
+🚀 Next steps:
+  1. cd my-app
+  2. yarn
+  3. yarn serve
+```
+
+**What was created:**
+- Complete Vue 3 + TypeScript application
+- Router configuration
+- Localization setup
+- Prettier and ESLint configuration
+- Base components and styles
+- Development scripts
+
+---
+
+### After Generating Module
+
+```
+✅ Module generated successfully!
+
+Created files:
+- src/modules/products/pages/products.vue
+- src/modules/products/pages/product-details.vue
+- src/modules/products/composables/useProductList.ts
+- src/modules/products/composables/useProductDetails.ts
+- src/modules/products/locales/en.json
+- src/modules/products/index.ts
+
+Module registered in src/main.ts
+```
+
+**What was created:**
+- Complete module structure
+- Grid blade with VcTable
+- Details blade with form fields
+- Composables with async logic
+- Localization files
+- Automatic module registration
+
+---
+
+## Next Steps After Generation
+
+### 1. Install Dependencies
+```bash
+cd your-app
+yarn
+```
+
+### 2. Connect to API
+See [API Client Generation Guide](./api-client-generation.md)
+
+### 3. Start Development Server
+```bash
+yarn serve
+```
+
+### 4. Access Application
+```
+http://localhost:8080/apps/your-app/
+```
+
+### 5. Customize Generated Code
+- Update TODO comments in composables
+- Replace placeholder API calls
+- Add validation rules
+- Customize UI components
+
+---
+
+## Common Patterns
+
+### Pattern 1: E-commerce Module Set
+
+**Prompt:**
+```
+Create a complete e-commerce module set:
+1. Products (list + details)
+2. Categories (list + details)
+3. Orders (list + details)
+4. Customers (list + details)
+
+Use CLI to generate all modules.
+```
+
+**AI will execute:**
+```bash
+# Products
+npx create-vc-app blade --module products --type grid --name products --is-workspace
+npx create-vc-app blade --module products --type details --name product-details
+
+# Categories
+npx create-vc-app blade --module categories --type grid --name categories --is-workspace
+npx create-vc-app blade --module categories --type details --name category-details
+
+# Orders
+npx create-vc-app blade --module orders --type grid --name orders --is-workspace
+npx create-vc-app blade --module orders --type details --name order-details
+
+# Customers
+npx create-vc-app blade --module customers --type grid --name customers --is-workspace
+npx create-vc-app blade --module customers --type details --name customer-details
+```
+
+---
+
+### Pattern 2: Settings Pages (Forms Only)
+
+**Prompt:**
+```
+Create settings pages (no lists):
+1. General Settings (store name, email, timezone)
+2. Payment Settings (payment methods, currencies)
+3. Shipping Settings (shipping zones, rates)
+
+Use CLI.
+```
+
+**AI will execute:**
+```bash
+# General
+npx create-vc-app blade --module settings-general --type details --name general --is-workspace
+
+# Payment
+npx create-vc-app blade --module settings-payment --type details --name payment --is-workspace
+
+# Shipping
+npx create-vc-app blade --module settings-shipping --type details --name shipping --is-workspace
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Module Not Created
+**Error:** `Module "xyz" not found`
+
+**Solution:** When generating a blade for non-existent module in non-interactive mode, the CLI automatically creates the module. Make sure you're in the project directory.
+
+---
+
+### Issue: Form Fields Not Generated
+**Error:** Invalid JSON in `--form-fields`
+
+**Solution:** Ensure JSON is properly escaped:
+- Use single quotes around the entire JSON
+- Use double quotes inside for JSON properties
+- Escape inner JSON in props: `"{\"required\":true}"`
+
+**Correct:**
+```bash
+--form-fields '[{"name":"title","type":"VcInput","props":"{\"required\":true}"}]'
+```
+
+---
+
+### Issue: Command Not Found
+**Error:** `create-vc-app: command not found`
+
+**Solution:** Use `npx` to run without global installation:
+```bash
+npx create-vc-app blade
+```
+
+---
+
+## Tips for Better AI Prompts
+
+1. **Be Specific:** Describe field types, validations, and requirements clearly
+2. **Use Structure:** List fields in bullet points or tables
+3. **Mention CLI:** Always say "use CLI" or "generate with create-vc-app"
+4. **Provide Context:** Mention if adding to existing app or creating new
+5. **Include Data Structure:** Describe your API data format if integrating
+
+**Good Prompt Example:**
+```
+Use create-vc-app CLI to generate an invoices module.
+
+Structure:
+- List blade with columns: invoice number, customer, date, total, status
+- Details blade with form:
+  - Invoice number (text, auto-generated, read-only)
+  - Customer (select dropdown)
+  - Date (date picker, required)
+  - Items (table with add/remove)
+  - Total (currency, auto-calculated, read-only)
+  - Status (select: draft, sent, paid)
+  - Notes (textarea)
+
+Create both grid and details blades.
+```
+
+---
+
+## Related Documentation
+
+- [Quick Start Scenarios](./quick-start-scenarios.md) - Ready-to-use examples
+- [API Client Generation](./api-client-generation.md) - Connecting to backend
+- [Complete Workflow Guide](../guides/complete-workflow.md) - End-to-end process
+- [Official Documentation](https://docs.virtocommerce.org/platform/developer-guide/custom-apps-development/vc-shell/)
+