@magentrix-corp/magentrix-cli 1.2.0 → 1.3.0

package/README.md

@@ -12,6 +12,7 @@ MagentrixCLI is a command-line tool that lets you:
 - Create new files with proper templates
 - Keep everything synchronized automatically
 - Work with your favorite code editor instead of the web interface
+- Deploy Vue.js (Iris) applications to your Magentrix instance
 
 ---
 
@@ -357,10 +358,25 @@ src/
 ├── Triggers/        # Trigger code (*.trigger files)
 ├── Pages/           # ASPX pages (*.aspx files)
 ├── Templates/       # Templates (*.aspx files)
-└── Contents/
-    └── Assets/      # Static assets (images, CSS, JS, etc.)
+├── Contents/
+│   └── Assets/      # Static assets (images, CSS, JS, etc.)
+└── iris-apps/       # Vue.js Iris applications (see warning below)
+    └── <app-slug>/  # Each app in its own folder
 ```
 
+> **⚠️ IMPORTANT: Deleting Iris Apps**
+>
+> **NEVER manually delete folders from `src/iris-apps/`!** Always use the `magentrix iris-delete` command to remove Iris apps. Manual deletion will cause:
+> - No recovery backup created (you cannot restore the app)
+> - App remains on the Magentrix server (orphaned)
+> - Cache becomes out of sync (causes errors on next publish)
+> - Linked Vue project not properly unlinked
+>
+> **Correct way to delete an Iris app:**
+> ```bash
+> magentrix iris-delete
+> ```
+
 ### File Extensions
 - `.ac` - Classes
 - `.ctrl` - Controllers
@@ -433,6 +449,239 @@ The tool supports all file types including:
 
 ---
 
+## Deploying Vue.js (Iris) Apps
+
+MagentrixCLI supports deploying Vue.js applications (Iris apps) to your Magentrix instance. These apps are built with Vue.js and Module Federation, allowing you to create custom frontend experiences.
+
+> **⚠️ CRITICAL: Always use `magentrix iris-delete` to remove Iris apps!**
+>
+> Never manually delete folders from `src/iris-apps/`. Manual deletion bypasses backups, leaves orphaned apps on the server, and corrupts the cache. See [Deleting an Iris app](#delete-an-iris-app) for proper deletion.
+
+### Overview
+
+The Iris deployment workflow:
+1. **Link** your Vue project to the CLI
+2. **Build and stage** the project to the CLI workspace
+3. **Publish** to Magentrix (automatically handled by `magentrix publish`)
+
+### Commands
+
+#### Link a Vue Project
+```bash
+magentrix iris-link
+```
+**What it does**: Opens an interactive menu to manage linked Vue.js projects. Projects are stored globally so they persist across Magentrix workspaces.
+
+**Options:**
+- `--path <dir>` - Specify Vue project path directly
+- `--unlink` - Remove a linked project
+- `--list` - Show all linked projects
+- `--cleanup` - Remove invalid (non-existent) linked projects
+
+**Menu options:**
+- Link a new Vue project
+- View all linked projects
+- Unlink a project
+- Cleanup invalid projects
+
+#### Build and Stage
+```bash
+magentrix vue-build-stage
+```
+**What it does**: Builds a linked Vue project and copies the output to `src/iris-apps/<slug>/` for publishing.
+
+**Options:**
+- `--path <dir>` - Specify Vue project path directly
+- `--skip-build` - Use existing `dist/` folder without rebuilding
+
+**Process:**
+1. Select from linked projects or enter path manually
+2. Run `npm run build` in the Vue project
+3. Validate the build output
+4. Copy to CLI workspace `src/iris-apps/<app-slug>/`
+
+#### Vue Development Server
+```bash
+magentrix iris-dev
+```
+**What it does**: Starts the Vue development server with platform assets (CSS, fonts) automatically injected from your Magentrix instance.
+
+**Options:**
+- `--path <dir>` - Specify Vue project path
+- `--no-inject` - Skip asset injection, just run dev server
+- `--restore` - Restore config.ts from backup without running
+
+**Process:**
+1. Fetch platform assets from Magentrix
+2. Backup `config.ts` and inject assets
+3. Run `npm run dev`
+4. Restore `config.ts` on exit (Ctrl+C)
+
+#### Delete an Iris App
+```bash
+magentrix iris-delete
+```
+**What it does**: Safely delete a published Iris app with automatic recovery backup.
+
+**Process:**
+1. Select app from list of published apps
+2. Show destructive warning
+3. Confirm by typing exact app slug
+4. Ask if you want to unlink the Vue project
+5. Create recovery backup in `.magentrix/iris-backups/`
+6. Delete from server and local files
+7. Update cache
+
+**Safety features:**
+- Automatic backup before deletion
+- Must type slug name to confirm
+- Recovery possible with `iris-recover`
+
+#### Recover a Deleted App
+```bash
+magentrix iris-recover
+```
+**What it does**: Restore a deleted Iris app from automatic backup.
+
+**Options:**
+- `--list` - Show all available recovery backups
+
+**Process:**
+1. Select backup to restore (sorted by deletion time)
+2. Check if linked Vue project still exists
+3. Restore files to `src/iris-apps/<slug>/`
+4. Re-link Vue project (if path exists)
+5. Show warnings for edge cases
+6. Optionally delete backup after recovery
+7. Run `magentrix publish` to sync to server
+
+### Vue Project Requirements
+
+Your Vue project must have a `config.ts` file with these required fields:
+
+```typescript
+// src/config.ts
+export const config = {
+  appPath: "my-app",           // App identifier (folder name on server)
+  appName: "My Application",   // Display name in navigation menu
+  siteUrl: "https://yourinstance.magentrix.com",
+  assets: []  // Injected automatically by iris-dev
+}
+```
+
+**Accepted field names:**
+- Slug: `appPath`, `slug`, or `app_path`
+- Name: `appName`, `app_name`, or `name`
+- URL: `siteUrl`, `site_url`, `baseUrl`, or `base_url`
+
+### Typical Development Workflow
+
+```bash
+# First time setup
+magentrix iris-link           # Link your Vue project
+
+# Development
+magentrix iris-dev            # Start dev server with platform assets
+# Make changes, test locally
+# Press Ctrl+C to stop
+
+# Deployment (run from Magentrix workspace, not Vue project folder)
+cd ~/magentrix-workspace      # Navigate to Magentrix workspace
+magentrix vue-build-stage --path ~/my-vue-app  # Build and stage
+# Prompted: "Do you want to publish to Magentrix now?" → Yes/No
+# If autopublish is running, it auto-deploys instead
+
+# Deleting an app
+magentrix iris-delete         # Select app, confirm, auto-backup created
+magentrix publish             # Sync deletion to server
+
+# Recovering a deleted app
+magentrix iris-recover        # Select backup, restore files
+magentrix publish             # Sync recovery to server
+```
+
+### Real-Time Deployment
+
+For automatic deployment during development:
+
+```bash
+# Terminal 1: Run autopublish
+magentrix autopublish
+
+# Terminal 2: Build and stage after making changes
+magentrix vue-build-stage
+# Autopublish will detect the changes and upload automatically
+```
+
+### Troubleshooting Iris Apps
+
+#### "Warning: Magentrix Workspace Not Detected"
+This warning appears when running `magentrix vue-build-stage` outside your Magentrix CLI workspace.
+
+**Why it happens:**
+- The command stages build files to `src/iris-apps/<slug>/` in your Magentrix workspace
+- You ran it from your Vue project directory or another location
+
+**How to fix:**
+1. Navigate to your Magentrix CLI workspace (the folder with `.magentrix/` and `src/`)
+2. Run the command from there
+3. Use `--path` to specify your Vue project: `magentrix vue-build-stage --path /path/to/vue-project`
+
+**Example:**
+```bash
+# Wrong - running from Vue project
+cd ~/my-vue-app
+magentrix vue-build-stage  # ⚠ Warning!
+
+# Right - running from Magentrix workspace
+cd ~/magentrix-workspace
+magentrix vue-build-stage --path ~/my-vue-app  # ✓ Works!
+```
+
+#### "Missing required field: slug"
+Your Vue project's `config.ts` is missing the app identifier. Add an `appPath` or `slug` field.
+
+#### "Missing required field: appName"
+Your Vue project's `config.ts` is missing the display name. Add an `appName` field.
+
+#### Build fails with "VITE_SITE_URL is not defined"
+This is a Vue project configuration issue, not a CLI issue. Check your Vue project's `.env` file or `vite.config.ts` for missing environment variables.
+
+#### "No config.ts found"
+The CLI looks for config in these locations:
+- `src/config.ts`
+- `config.ts`
+- `src/iris-config.ts`
+- `iris-config.ts`
+
+#### Deleting an Iris app
+To remove an Iris app:
+```bash
+magentrix iris-delete
+```
+This creates an automatic recovery backup before deletion. You can restore using `magentrix iris-recover`.
+
+**Permission errors:**
+If you get "Permission Denied" when deleting local files:
+- The app is still deleted from the server and cache
+- Delete the local folder manually with: `rm -rf src/iris-apps/<app-slug>`
+- Or use sudo: `sudo rm -rf src/iris-apps/<app-slug>`
+
+#### Recovering a deleted app
+To restore a deleted Iris app:
+```bash
+magentrix iris-recover --list  # See all available backups
+magentrix iris-recover         # Select and restore a backup
+magentrix publish              # Sync to server
+```
+
+**Important**: After recovery, you must run `magentrix publish` to sync the app back to the Magentrix server.
+
+#### Changes not detected after vue-build-stage
+The CLI uses content hash tracking to detect changes. If you rebuild without changes, `magentrix publish` will show "All files are in sync — nothing to publish!" This is expected behavior and saves unnecessary uploads.
+
+---
+
 ## Handling Conflicts
 
 When files have changed both locally and on the server, you'll see conflict options:
@@ -481,6 +730,31 @@ magentrix publish       # Make sure all changes are uploaded
 magentrix status        # Verify everything is in sync
 ```
 
+### Deploying a Vue.js App
+```bash
+# Important: Run from your Magentrix CLI workspace, NOT the Vue project folder
+cd ~/magentrix-workspace      # Navigate to Magentrix workspace
+
+magentrix iris-link           # Link project (first time only)
+magentrix vue-build-stage --path ~/my-vue-app  # Build and stage
+# Prompted: "Do you want to publish to Magentrix now?" (unless autopublish is running)
+```
+
+**Note:** The `vue-build-stage` command must be run from your Magentrix CLI workspace directory (where `.magentrix/` and `src/` folders are). Use `--path` to specify your Vue project location.
+
+### Deleting and Recovering Apps
+```bash
+# Delete an app (creates automatic backup)
+magentrix iris-delete         # Select app, confirm deletion
+
+# View available backups
+magentrix iris-recover --list
+
+# Recover a deleted app
+magentrix iris-recover        # Select backup, restore
+magentrix publish             # Sync recovery to server
+```
+
 ---
 
 ## Using Git Alongside MagentrixCLI
@@ -762,6 +1036,11 @@ magentrix status        # Shows sync status
 - `magentrix status` - Check sync status
 - `magentrix autopublish` - Auto-sync mode
 - `magentrix update` - Update to latest version
+- `magentrix iris-link` - Link Vue.js projects for deployment
+- `magentrix vue-build-stage` - Build and stage Vue.js apps
+- `magentrix iris-dev` - Start Vue dev server with platform assets
+- `magentrix iris-delete` - Delete an Iris app with recovery backup
+- `magentrix iris-recover` - Recover a deleted Iris app
 
 ---
 
@@ -773,5 +1052,6 @@ Once you're comfortable with basic usage:
 2. **Learn the autopublish workflow** for faster development
 3. **Explore conflict resolution** if you work in a team
 4. **Check out templates** created by the `create` command to understand best practices
+5. **Deploy Vue.js apps** using `iris-link`, `vue-build-stage`, and `iris-dev` commands
 
 Happy coding with MagentrixCLI! 🚀

package/actions/autopublish.js

@@ -2,61 +2,21 @@ import chokidar from 'chokidar';
 import { ensureValidCredentials } from '../utils/cli/helpers/ensureCredentials.js';
 import { withSpinner } from '../utils/spinner.js';
 import { EXPORT_ROOT } from '../vars/global.js';
-import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { runPublish } from './publish.js';
+import {
+    acquireAutopublishLock,
+    releaseAutopublishLock,
+    getLockFilePath
+} from '../utils/autopublishLock.js';
 
-const LOCK_FILE = path.join(process.cwd(), '.magentrix', 'autopublish.lock');
+const LOCK_FILE = getLockFilePath();
 
 let credentials = {};
 let isProcessing = false;
 let pendingFiles = new Set(); // Track files that have changed while processing
 
-/**
- * Creates a lock file to prevent multiple autopublish instances
- * @returns {boolean} True if lock was acquired, false if already locked
- */
-const acquireLock = () => {
-    try {
-        if (fs.existsSync(LOCK_FILE)) {
-            // Check if the lock is stale (process might have crashed)
-            const lockData = JSON.parse(fs.readFileSync(LOCK_FILE, 'utf-8'));
-            const lockAge = Date.now() - lockData.timestamp;
-
-            // If lock is older than 1 hour, consider it stale
-            if (lockAge < 3600000) {
-                return false;
-            }
-        }
-
-        // Create lock file
-        fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true });
-        fs.writeFileSync(LOCK_FILE, JSON.stringify({
-            pid: process.pid,
-            timestamp: Date.now()
-        }));
-
-        return true;
-    } catch (err) {
-        console.error(chalk.red(`Failed to acquire lock: ${err.message}`));
-        return false;
-    }
-};
-
-/**
- * Releases the lock file
- */
-const releaseLock = () => {
-    try {
-        if (fs.existsSync(LOCK_FILE)) {
-            fs.unlinkSync(LOCK_FILE);
-        }
-    } catch (err) {
-        console.error(chalk.red(`Failed to release lock: ${err.message}`));
-    }
-};
-
 /**
  * Debounce timer for batching changes
  */
@@ -220,6 +180,7 @@ const startWatcher = () => {
     console.log(chalk.gray('─'.repeat(48)));
     console.log(chalk.green('Watching for file changes in:'));
     console.log(chalk.cyan(`  ${path.join(process.cwd(), EXPORT_ROOT)}`));
+    console.log(chalk.gray('  Includes: Code, Assets, and Iris apps'));
     console.log(chalk.gray('Press Ctrl+C to stop'));
     console.log();
 
@@ -244,7 +205,7 @@ const startWatcher = () => {
     const cleanup = () => {
         console.log(chalk.yellow('\n\nStopping auto-publish...'));
         watcher.close();
-        releaseLock();
+        releaseAutopublishLock();
         process.exit(0);
     };
 
@@ -259,7 +220,7 @@ export const autoPublish = async () => {
     process.stdout.write('\x1Bc');
 
     // Check for existing lock
-    if (!acquireLock()) {
+    if (!acquireAutopublishLock()) {
         console.log(chalk.bgRed.bold.white('  ✖ Already Running  '));
         console.log(chalk.redBright('─'.repeat(48)));
         console.log(chalk.red('Another instance of autopublish is already running.'));