@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/bin/magentrix.js

@@ -1,393 +1,393 @@
-#!/usr/bin/env node
-
-// Imports
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { VERSION } from '../vars/config.js';
-import { setup } from '../actions/setup.js';
-import { main } from '../actions/main.js';
-import { pull } from '../actions/pull.js';
-import { create } from '../actions/create.js';
-import { autoPublish } from '../actions/autopublish.js';
-import { status } from '../actions/status.js';
-import { cacheDir, recacheFileIdIndex } from '../utils/cacher.js';
-import { CWD, EXPORT_ROOT, HASHED_CWD } from '../vars/global.js';
-import { publish } from '../actions/publish.js';
-import { update } from '../actions/update.js';
-import { configWizard } from '../actions/config.js';
-import { irisLink, irisDev, irisDelete, irisRecover, vueBuildStage } from '../actions/iris/index.js';
-import Config from '../utils/config.js';
-import { registerWorkspace, getRegisteredWorkspaces } from '../utils/workspaces.js';
-import { ensureVSCodeFileAssociation } from '../utils/preferences.js';
-import debug from '../utils/debug.js';
-
-const config = new Config();
-
-// ── Debug Mode ───────────────────────────────
-// Check early (before Commander parses) so debug logging covers the full lifecycle
-if (process.argv.includes('--debug') || process.env.DEBUG === 'true') {
-    debug.enable();
-    debug.env();
-}
-
-// ── Vue Project Detection ────────────────────────────────
-/**
- * Check if current directory is a Vue project (has config.ts)
- */
-function isInVueProject() {
-    const configLocations = [
-        'src/config.ts',
-        'config.ts',
-        'src/iris-config.ts',
-        'iris-config.ts'
-    ];
-    return configLocations.some(loc => existsSync(join(process.cwd(), loc)));
-}
-
-/**
- * Block non-iris commands when in a Vue project
- */
-function requireMagentrixWorkspace(fn) {
-    return async (...args) => {
-        if (isInVueProject()) {
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command must be run in a Magentrix workspace')}\n`);
-            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
-            console.error(chalk.gray('This command requires a Magentrix workspace with global API key and instance URL.\n'));
-            console.error(chalk.cyan('Available commands in Vue projects:'));
-            console.error(chalk.gray('  • magentrix iris-app-link'));
-            console.error(chalk.gray('  • magentrix vue-run-build'));
-            console.error(chalk.gray('  • magentrix vue-run-dev'));
-            console.error(chalk.gray('  • magentrix update\n'));
-            process.exit(1);
-        }
-        // Execute the command
-        await fn(...args);
-    };
-}
-
-/**
- * Block commands that should not run in Vue projects (but don't require a workspace)
- */
-function blockInVueProject(fn) {
-    return async (...args) => {
-        if (isInVueProject()) {
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command cannot be run in a Vue project')}\n`);
-            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
-            console.error(chalk.gray('Please run this command from a Magentrix workspace or an empty directory.\n'));
-            process.exit(1);
-        }
-        // Execute the command
-        await fn(...args);
-    };
-}
-
-// ── Middleware ────────────────────────────────
-
-/**
- * Auto-register existing workspaces for backwards compatibility.
- * If the current directory has credentials configured but isn't in the
- * global workspace registry, register it automatically.
- */
-function ensureWorkspaceRegistered() {
-    // Check if current directory has credentials configured
-    const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
-    const apiKey = config.read('apiKey', { global: true, pathHash: HASHED_CWD });
-
-    if (!instanceUrl || !apiKey) {
-        return; // Not a configured workspace
-    }
-
-    // Check if already registered
-    const workspaces = getRegisteredWorkspaces();
-    const alreadyRegistered = workspaces.some(w => w.path === CWD);
-
-    if (!alreadyRegistered) {
-        // Auto-register for backwards compatibility
-        registerWorkspace(CWD, instanceUrl);
-    }
-}
-
-async function preMiddleware() {
-    ensureWorkspaceRegistered();
-
-    // Ensure .vscode folder exists in project root (not in src/) for Magentrix projects
-    const magentrixDir = join(CWD, '.magentrix');
-    if (existsSync(magentrixDir)) {
-        await ensureVSCodeFileAssociation(CWD);
-    }
-
-    await recacheFileIdIndex(EXPORT_ROOT);
-    await cacheDir(EXPORT_ROOT);
-}
-async function postMiddleware() {
-    await cacheDir(EXPORT_ROOT);
-}
-
-const withMiddleware = ({ pre, post }) => (fn) => async (...args) => {
-    if (pre) await pre(...args);
-    await fn(...args);
-    if (post) await post(...args);
-};
-
-const withDefault = withMiddleware({ pre: preMiddleware, post: postMiddleware });
-
-// Combined wrapper: check for Vue project + run middleware
-const withWorkspaceCheck = (fn) => requireMagentrixWorkspace(withDefault(fn));
-
-// ── CLI Setup ────────────────────────────────
-const program = new Command();
-program
-    .name('magentrix')
-    .description('Manage Magentrix assets and automation')
-    .version(VERSION)
-    .option('--debug', 'Enable debug logging')
-    .configureHelp({
-        formatHelp: (_cmd, _helper) => {
-            const divider = chalk.gray('━'.repeat(60));
-            const titleBar = chalk.bold.bgBlue.white(' Magentrix CLI ');
-            const version = chalk.dim(`v${VERSION}`);
-
-            let help = `\n${divider}\n${titleBar} ${version}\n${divider}\n\n`;
-            help += `${chalk.dim('Manage Magentrix assets and automation')}\n\n`;
-
-            // Usage section
-            help += `${chalk.bold.yellow('USAGE')}\n`;
-            help += `  ${chalk.cyan('magentrix')} ${chalk.dim('<command> [options]')}\n\n`;
-
-            // Commands section
-            help += `${chalk.bold.yellow('COMMANDS')}\n`;
-            const commands = [
-                { name: 'setup', desc: 'Configure your Magentrix API key', icon: '⚙️  ' },
-                { name: 'config', desc: 'Manage CLI settings', icon: '🔧 ' },
-                { name: 'pull', desc: 'Pull files from the remote server', icon: '📥 ' },
-                { name: 'create', desc: 'Create files locally', icon: '✨ ' },
-                { name: 'status', desc: 'Show file conflicts and sync status', icon: '📊 ' },
-                { name: 'publish', desc: 'Publish pending changes to the remote server', icon: '📤 ' },
-                { name: 'autopublish', desc: 'Watch & sync changes in real time', icon: '🔄 ' },
-                { name: 'update', desc: 'Update MagentrixCLI to the latest version', icon: '⬆️  ' },
-                { name: 'iris-app-link', desc: 'Link a Vue project to the CLI', icon: '🔗 ' },
-                { name: 'vue-run-build', desc: 'Build Vue project and stage for publish', icon: '🏗️  ' },
-                { name: 'vue-run-dev', desc: 'Start Vue dev server with platform assets', icon: '🌐 ' },
-                { name: 'iris-app-delete', desc: 'Delete an Iris app with backup', icon: '🗑️  ' },
-                { name: 'iris-app-recover', desc: 'Recover a deleted Iris app from backup', icon: '♻️  ' }
-            ];
-
-            const maxNameLen = Math.max(...commands.map(c => c.name.length));
-            commands.forEach(cmd => {
-                const padding = ' '.repeat(maxNameLen - cmd.name.length);
-                help += `  ${cmd.icon}${chalk.cyan.bold(cmd.name)}${padding}  ${chalk.dim(cmd.desc)}\n`;
-            });
-
-            help += `\n${chalk.bold.yellow('OPTIONS')}\n`;
-            help += `  ${chalk.cyan('-V, --version')}  ${chalk.dim('Output the version number')}\n`;
-            help += `  ${chalk.cyan('--debug')}        ${chalk.dim('Enable debug logging to .magentrix/logs/')}\n`;
-            help += `  ${chalk.cyan('-h, --help')}     ${chalk.dim('Display this help message')}\n`;
-
-            help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
-            help += `  ${chalk.dim('# Initial setup')}\n`;
-            help += `  ${chalk.cyan('magentrix setup')}\n\n`;
-            help += `  ${chalk.dim('# Pull remote files')}\n`;
-            help += `  ${chalk.cyan('magentrix pull')}\n\n`;
-            help += `  ${chalk.dim('# Auto-sync on file changes')}\n`;
-            help += `  ${chalk.cyan('magentrix autopublish')}\n`;
-
-            help += `\n${divider}\n`;
-
-            return help;
-        }
-    });
-
-// ── Error Handlers ───────────────────────────
-program.showHelpAfterError(false);
-program.configureOutput({
-    outputError: (str, _write) => {
-        // Custom error message for unknown options
-        if (str.includes('unknown option')) {
-            const match = str.match(/'([^']+)'/);
-            const option = match ? match[1] : str;
-
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('Unknown option:')} ${chalk.bold(option)}`);
-            console.error(`${chalk.yellow('💡 Tip:')} Run ${chalk.cyan('magentrix --help')} to see available options.\n`);
-        }
-        // Custom error message for unknown commands
-        else if (str.includes('unknown command')) {
-            const match = str.match(/'([^']+)'/);
-            const command = match ? match[1] : str;
-
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('Unknown command:')} ${chalk.bold(command)}`);
-            console.error(`${chalk.yellow('💡 Tip:')} Run ${chalk.cyan('magentrix --help')} to see available commands.\n`);
-        }
-        // Generic errors
-        else {
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright(str.trim())}\n`);
-        }
-    }
-});
-
-// ── Commands ─────────────────────────────────
-program
-    .command('setup')
-    .description('Configure your Magentrix API key')
-    .option('--api-key <apiKey>', 'Magentrix API key')
-    .option('--instance-url <instanceUrl>', 'Magentrix instance URL (e.g., https://example.magentrixcloud.com)')
-    .action(blockInVueProject(setup));
-program.command('pull').description('Pull files from the remote server').action(withWorkspaceCheck(pull));
-const createCommand = program
-    .command('create')
-    .description('Create files locally')
-    .option('--type <type>', 'Entity type: class, page, or template')
-    .option('--class-type <classType>', 'Class type: controller, utility, or trigger (for --type class)')
-    .option('--name <name>', 'Name of the file to create')
-    .option('--description <description>', 'Optional description')
-    .option('--entity-id <entityId>', 'Entity ID (required for triggers)')
-    .action(withWorkspaceCheck(create));
-
-// Override help for create command to show options
-createCommand.configureHelp({
-    formatHelp: () => {
-        const divider = chalk.gray('━'.repeat(60));
-        const titleBar = chalk.bold.bgBlue.white(' Magentrix CLI - Create Command ');
-
-        let help = `\n${divider}\n${titleBar}\n${divider}\n\n`;
-        help += `${chalk.dim('Create files locally with optional parameters to bypass interactive prompts')}\n\n`;
-
-        help += `${chalk.bold.yellow('USAGE')}\n`;
-        help += `  ${chalk.cyan('magentrix create')} ${chalk.dim('[options]')}\n\n`;
-
-        help += `${chalk.bold.yellow('OPTIONS')}\n`;
-        const options = [
-            { name: '--type <type>', desc: 'Entity type: class, page, or template' },
-            { name: '--class-type <classType>', desc: 'Class type: controller, utility, or trigger (for --type class)' },
-            { name: '--name <name>', desc: 'Name of the file to create' },
-            { name: '--description <description>', desc: 'Optional description' },
-            { name: '--entity-id <entityId>', desc: 'Entity ID (required for triggers)' },
-            { name: '-h, --help', desc: 'Display this help message' }
-        ];
-
-        const maxNameLen = Math.max(...options.map(o => o.name.length));
-        options.forEach(opt => {
-            const padding = ' '.repeat(maxNameLen - opt.name.length);
-            help += `  ${chalk.cyan(opt.name)}${padding}  ${chalk.dim(opt.desc)}\n`;
-        });
-
-        help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
-        help += `  ${chalk.dim('# Create a controller non-interactively')}\n`;
-        help += `  ${chalk.cyan('magentrix create --type class --class-type controller --name UserController')}\n\n`;
-        help += `  ${chalk.dim('# Create a trigger')}\n`;
-        help += `  ${chalk.cyan('magentrix create --type class --class-type trigger --entity-id abc123 --name AccountTrigger')}\n\n`;
-        help += `  ${chalk.dim('# Create a page')}\n`;
-        help += `  ${chalk.cyan('magentrix create --type page --name HomePage --description "Main landing page"')}\n\n`;
-        help += `  ${chalk.dim('# Create a template')}\n`;
-        help += `  ${chalk.cyan('magentrix create --type template --name EmailTemplate')}\n\n`;
-        help += `  ${chalk.dim('# Mix interactive and non-interactive (will prompt for missing info)')}\n`;
-        help += `  ${chalk.cyan('magentrix create --name MyClass')}\n`;
-
-        help += `\n${divider}\n`;
-
-        return help;
-    }
-});
-program.command('status').description('Show file conflicts').action(withWorkspaceCheck(status));
-program.command('autopublish').description('Watch & sync changes in real time').action(withWorkspaceCheck(autoPublish));
-// Publish does its own comprehensive file scanning, so skip the pre-cache middleware
-program.command('publish').description('Publish pending changes to the remote server').action(withWorkspaceCheck(publish));
-program.command('update').description('Update MagentrixCLI to the latest version').action(update);
-
-// Config command - interactive wizard
-program
-    .command('config')
-    .description('Configure CLI settings')
-    .action(requireMagentrixWorkspace(configWizard));
-
-// Iris commands for Vue.js app management
-program
-    .command('iris-app-link')
-    .description('Link a Vue project to the CLI for deployment')
-    .option('--path <path>', 'Path to the Vue project')
-    .option('--unlink', 'Unlink a project instead of linking')
-    .option('--list', 'List all linked projects')
-    .option('--cleanup', 'Remove invalid (non-existent) linked projects')
-    .action(irisLink);
-
-program
-    .command('vue-run-build')
-    .description('Build a Vue project and stage it for publishing')
-    .option('--path <path>', 'Path to the Vue project')
-    .option('--skip-build', 'Skip build step and use existing dist/')
-    .option('--workspace <workspace>', 'Path to Magentrix workspace to stage into')
-    .action(vueBuildStage);
-
-program
-    .command('vue-run-dev')
-    .description('Start Vue dev server with platform assets injected')
-    .option('--path <path>', 'Path to the Vue project')
-    .option('--no-inject', 'Skip asset injection')
-    .action(irisDev);
-
-program
-    .command('iris-app-delete')
-    .description('Delete a published Iris app with recovery backup')
-    .action(irisDelete);
-
-program
-    .command('iris-app-recover')
-    .description('Recover a deleted Iris app from backup')
-    .option('--list', 'List available recovery backups')
-    .action(irisRecover);
-
-// ── Unknown Command Handler ──────────────────
-program.argument('[command]', 'command to run').action((cmd) => {
-    const runMain = async () => {
-        // Check if in Vue project
-        if (isInVueProject()) {
-            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command must be run in a Magentrix workspace')}\n`);
-            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
-            console.error(chalk.gray('This command requires a Magentrix workspace with global API key and instance URL.\n'));
-            console.error(chalk.cyan('Available commands in Vue projects:'));
-            console.error(chalk.gray('  • magentrix iris-app-link'));
-            console.error(chalk.gray('  • magentrix vue-run-build'));
-            console.error(chalk.gray('  • magentrix vue-run-dev'));
-            console.error(chalk.gray('  • magentrix update\n'));
-            process.exit(1);
-        }
-
-        await preMiddleware();
-        await main();
-        await postMiddleware();
-    };
-
-    if (cmd) {
-        console.log(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright(`Unknown command:`)} ${chalk.bold(cmd)}\n`);
-        console.log(`${chalk.yellow('💡  Tip:')} Run ${chalk.cyan('magentrix --help')} to view available commands.\n`);
-        process.exit(1);
-    } else {
-        runMain().catch(handleFatal);
-    }
-});
-
-// ── Global Error Handler ─────────────────────
-function handleFatal(err) {
-    const divider = chalk.gray('──────────────────────────────────────────────');
-    const header = `${chalk.bgRed.white.bold(' FATAL ERROR ')}`;
-
-    console.error(`\n${divider}\n${header}`);
-    console.error(`${chalk.redBright(err?.message || 'An unexpected error occurred.')}\n`);
-
-    if (debug.enabled) {
-        debug.log('FATAL', err?.message, err?.stack);
-        debug.close();
-        if (err?.stack) {
-            console.error(chalk.dim(err.stack));
-            console.error();
-        }
-    } else {
-        console.log(`${chalk.yellow('💡  Run with')} ${chalk.cyan('--debug')} ${chalk.yellow('for full details.')}`);
-    }
-
-    console.log(divider + '\n');
-    process.exit(1);
-}
-
-program.parseAsync(process.argv).catch(handleFatal);
+#!/usr/bin/env node
+
+// Imports
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { VERSION } from '../vars/config.js';
+import { setup } from '../actions/setup.js';
+import { main } from '../actions/main.js';
+import { pull } from '../actions/pull.js';
+import { create } from '../actions/create.js';
+import { autoPublish } from '../actions/autopublish.js';
+import { status } from '../actions/status.js';
+import { cacheDir, recacheFileIdIndex } from '../utils/cacher.js';
+import { CWD, EXPORT_ROOT, HASHED_CWD } from '../vars/global.js';
+import { publish } from '../actions/publish.js';
+import { update } from '../actions/update.js';
+import { configWizard } from '../actions/config.js';
+import { irisLink, irisDev, irisDelete, irisRecover, vueBuildStage } from '../actions/iris/index.js';
+import Config from '../utils/config.js';
+import { registerWorkspace, getRegisteredWorkspaces } from '../utils/workspaces.js';
+import { ensureVSCodeFileAssociation } from '../utils/preferences.js';
+import debug from '../utils/debug.js';
+
+const config = new Config();
+
+// ── Debug Mode ───────────────────────────────
+// Check early (before Commander parses) so debug logging covers the full lifecycle
+if (process.argv.includes('--debug') || process.env.DEBUG === 'true') {
+    debug.enable();
+    debug.env();
+}
+
+// ── Vue Project Detection ────────────────────────────────
+/**
+ * Check if current directory is a Vue project (has config.ts)
+ */
+function isInVueProject() {
+    const configLocations = [
+        'src/config.ts',
+        'config.ts',
+        'src/iris-config.ts',
+        'iris-config.ts'
+    ];
+    return configLocations.some(loc => existsSync(join(process.cwd(), loc)));
+}
+
+/**
+ * Block non-iris commands when in a Vue project
+ */
+function requireMagentrixWorkspace(fn) {
+    return async (...args) => {
+        if (isInVueProject()) {
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command must be run in a Magentrix workspace')}\n`);
+            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
+            console.error(chalk.gray('This command requires a Magentrix workspace with global API key and instance URL.\n'));
+            console.error(chalk.cyan('Available commands in Vue projects:'));
+            console.error(chalk.gray('  • magentrix iris-app-link'));
+            console.error(chalk.gray('  • magentrix vue-run-build'));
+            console.error(chalk.gray('  • magentrix vue-run-dev'));
+            console.error(chalk.gray('  • magentrix update\n'));
+            process.exit(1);
+        }
+        // Execute the command
+        await fn(...args);
+    };
+}
+
+/**
+ * Block commands that should not run in Vue projects (but don't require a workspace)
+ */
+function blockInVueProject(fn) {
+    return async (...args) => {
+        if (isInVueProject()) {
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command cannot be run in a Vue project')}\n`);
+            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
+            console.error(chalk.gray('Please run this command from a Magentrix workspace or an empty directory.\n'));
+            process.exit(1);
+        }
+        // Execute the command
+        await fn(...args);
+    };
+}
+
+// ── Middleware ────────────────────────────────
+
+/**
+ * Auto-register existing workspaces for backwards compatibility.
+ * If the current directory has credentials configured but isn't in the
+ * global workspace registry, register it automatically.
+ */
+function ensureWorkspaceRegistered() {
+    // Check if current directory has credentials configured
+    const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
+    const apiKey = config.read('apiKey', { global: true, pathHash: HASHED_CWD });
+
+    if (!instanceUrl || !apiKey) {
+        return; // Not a configured workspace
+    }
+
+    // Check if already registered
+    const workspaces = getRegisteredWorkspaces();
+    const alreadyRegistered = workspaces.some(w => w.path === CWD);
+
+    if (!alreadyRegistered) {
+        // Auto-register for backwards compatibility
+        registerWorkspace(CWD, instanceUrl);
+    }
+}
+
+async function preMiddleware() {
+    ensureWorkspaceRegistered();
+
+    // Ensure .vscode folder exists in project root (not in src/) for Magentrix projects
+    const magentrixDir = join(CWD, '.magentrix');
+    if (existsSync(magentrixDir)) {
+        await ensureVSCodeFileAssociation(CWD);
+    }
+
+    await recacheFileIdIndex(EXPORT_ROOT);
+    await cacheDir(EXPORT_ROOT);
+}
+async function postMiddleware() {
+    await cacheDir(EXPORT_ROOT);
+}
+
+const withMiddleware = ({ pre, post }) => (fn) => async (...args) => {
+    if (pre) await pre(...args);
+    await fn(...args);
+    if (post) await post(...args);
+};
+
+const withDefault = withMiddleware({ pre: preMiddleware, post: postMiddleware });
+
+// Combined wrapper: check for Vue project + run middleware
+const withWorkspaceCheck = (fn) => requireMagentrixWorkspace(withDefault(fn));
+
+// ── CLI Setup ────────────────────────────────
+const program = new Command();
+program
+    .name('magentrix')
+    .description('Manage Magentrix assets and automation')
+    .version(VERSION)
+    .option('--debug', 'Enable debug logging')
+    .configureHelp({
+        formatHelp: (_cmd, _helper) => {
+            const divider = chalk.gray('━'.repeat(60));
+            const titleBar = chalk.bold.bgBlue.white(' Magentrix CLI ');
+            const version = chalk.dim(`v${VERSION}`);
+
+            let help = `\n${divider}\n${titleBar} ${version}\n${divider}\n\n`;
+            help += `${chalk.dim('Manage Magentrix assets and automation')}\n\n`;
+
+            // Usage section
+            help += `${chalk.bold.yellow('USAGE')}\n`;
+            help += `  ${chalk.cyan('magentrix')} ${chalk.dim('<command> [options]')}\n\n`;
+
+            // Commands section
+            help += `${chalk.bold.yellow('COMMANDS')}\n`;
+            const commands = [
+                { name: 'setup', desc: 'Configure your Magentrix API key', icon: '⚙️  ' },
+                { name: 'config', desc: 'Manage CLI settings', icon: '🔧 ' },
+                { name: 'pull', desc: 'Pull files from the remote server', icon: '📥 ' },
+                { name: 'create', desc: 'Create files locally', icon: '✨ ' },
+                { name: 'status', desc: 'Show file conflicts and sync status', icon: '📊 ' },
+                { name: 'publish', desc: 'Publish pending changes to the remote server', icon: '📤 ' },
+                { name: 'autopublish', desc: 'Watch & sync changes in real time', icon: '🔄 ' },
+                { name: 'update', desc: 'Update MagentrixCLI to the latest version', icon: '⬆️  ' },
+                { name: 'iris-app-link', desc: 'Link a Vue project to the CLI', icon: '🔗 ' },
+                { name: 'vue-run-build', desc: 'Build Vue project and stage for publish', icon: '🏗️  ' },
+                { name: 'vue-run-dev', desc: 'Start Vue dev server with platform assets', icon: '🌐 ' },
+                { name: 'iris-app-delete', desc: 'Delete an Iris app with backup', icon: '🗑️  ' },
+                { name: 'iris-app-recover', desc: 'Recover a deleted Iris app from backup', icon: '♻️  ' }
+            ];
+
+            const maxNameLen = Math.max(...commands.map(c => c.name.length));
+            commands.forEach(cmd => {
+                const padding = ' '.repeat(maxNameLen - cmd.name.length);
+                help += `  ${cmd.icon}${chalk.cyan.bold(cmd.name)}${padding}  ${chalk.dim(cmd.desc)}\n`;
+            });
+
+            help += `\n${chalk.bold.yellow('OPTIONS')}\n`;
+            help += `  ${chalk.cyan('-V, --version')}  ${chalk.dim('Output the version number')}\n`;
+            help += `  ${chalk.cyan('--debug')}        ${chalk.dim('Enable debug logging to .magentrix/logs/')}\n`;
+            help += `  ${chalk.cyan('-h, --help')}     ${chalk.dim('Display this help message')}\n`;
+
+            help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
+            help += `  ${chalk.dim('# Initial setup')}\n`;
+            help += `  ${chalk.cyan('magentrix setup')}\n\n`;
+            help += `  ${chalk.dim('# Pull remote files')}\n`;
+            help += `  ${chalk.cyan('magentrix pull')}\n\n`;
+            help += `  ${chalk.dim('# Auto-sync on file changes')}\n`;
+            help += `  ${chalk.cyan('magentrix autopublish')}\n`;
+
+            help += `\n${divider}\n`;
+
+            return help;
+        }
+    });
+
+// ── Error Handlers ───────────────────────────
+program.showHelpAfterError(false);
+program.configureOutput({
+    outputError: (str, _write) => {
+        // Custom error message for unknown options
+        if (str.includes('unknown option')) {
+            const match = str.match(/'([^']+)'/);
+            const option = match ? match[1] : str;
+
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('Unknown option:')} ${chalk.bold(option)}`);
+            console.error(`${chalk.yellow('💡 Tip:')} Run ${chalk.cyan('magentrix --help')} to see available options.\n`);
+        }
+        // Custom error message for unknown commands
+        else if (str.includes('unknown command')) {
+            const match = str.match(/'([^']+)'/);
+            const command = match ? match[1] : str;
+
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('Unknown command:')} ${chalk.bold(command)}`);
+            console.error(`${chalk.yellow('💡 Tip:')} Run ${chalk.cyan('magentrix --help')} to see available commands.\n`);
+        }
+        // Generic errors
+        else {
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright(str.trim())}\n`);
+        }
+    }
+});
+
+// ── Commands ─────────────────────────────────
+program
+    .command('setup')
+    .description('Configure your Magentrix API key')
+    .option('--api-key <apiKey>', 'Magentrix API key')
+    .option('--instance-url <instanceUrl>', 'Magentrix instance URL (e.g., https://example.magentrixcloud.com)')
+    .action(blockInVueProject(setup));
+program.command('pull').description('Pull files from the remote server').action(withWorkspaceCheck(pull));
+const createCommand = program
+    .command('create')
+    .description('Create files locally')
+    .option('--type <type>', 'Entity type: class, page, or template')
+    .option('--class-type <classType>', 'Class type: controller, utility, or trigger (for --type class)')
+    .option('--name <name>', 'Name of the file to create')
+    .option('--description <description>', 'Optional description')
+    .option('--entity-id <entityId>', 'Entity ID (required for triggers)')
+    .action(withWorkspaceCheck(create));
+
+// Override help for create command to show options
+createCommand.configureHelp({
+    formatHelp: () => {
+        const divider = chalk.gray('━'.repeat(60));
+        const titleBar = chalk.bold.bgBlue.white(' Magentrix CLI - Create Command ');
+
+        let help = `\n${divider}\n${titleBar}\n${divider}\n\n`;
+        help += `${chalk.dim('Create files locally with optional parameters to bypass interactive prompts')}\n\n`;
+
+        help += `${chalk.bold.yellow('USAGE')}\n`;
+        help += `  ${chalk.cyan('magentrix create')} ${chalk.dim('[options]')}\n\n`;
+
+        help += `${chalk.bold.yellow('OPTIONS')}\n`;
+        const options = [
+            { name: '--type <type>', desc: 'Entity type: class, page, or template' },
+            { name: '--class-type <classType>', desc: 'Class type: controller, utility, or trigger (for --type class)' },
+            { name: '--name <name>', desc: 'Name of the file to create' },
+            { name: '--description <description>', desc: 'Optional description' },
+            { name: '--entity-id <entityId>', desc: 'Entity ID (required for triggers)' },
+            { name: '-h, --help', desc: 'Display this help message' }
+        ];
+
+        const maxNameLen = Math.max(...options.map(o => o.name.length));
+        options.forEach(opt => {
+            const padding = ' '.repeat(maxNameLen - opt.name.length);
+            help += `  ${chalk.cyan(opt.name)}${padding}  ${chalk.dim(opt.desc)}\n`;
+        });
+
+        help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
+        help += `  ${chalk.dim('# Create a controller non-interactively')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type class --class-type controller --name UserController')}\n\n`;
+        help += `  ${chalk.dim('# Create a trigger')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type class --class-type trigger --entity-id abc123 --name AccountTrigger')}\n\n`;
+        help += `  ${chalk.dim('# Create a page')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type page --name HomePage --description "Main landing page"')}\n\n`;
+        help += `  ${chalk.dim('# Create a template')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type template --name EmailTemplate')}\n\n`;
+        help += `  ${chalk.dim('# Mix interactive and non-interactive (will prompt for missing info)')}\n`;
+        help += `  ${chalk.cyan('magentrix create --name MyClass')}\n`;
+
+        help += `\n${divider}\n`;
+
+        return help;
+    }
+});
+program.command('status').description('Show file conflicts').action(withWorkspaceCheck(status));
+program.command('autopublish').description('Watch & sync changes in real time').action(withWorkspaceCheck(autoPublish));
+// Publish does its own comprehensive file scanning, so skip the pre-cache middleware
+program.command('publish').description('Publish pending changes to the remote server').action(withWorkspaceCheck(publish));
+program.command('update').description('Update MagentrixCLI to the latest version').action(update);
+
+// Config command - interactive wizard
+program
+    .command('config')
+    .description('Configure CLI settings')
+    .action(requireMagentrixWorkspace(configWizard));
+
+// Iris commands for Vue.js app management
+program
+    .command('iris-app-link')
+    .description('Link a Vue project to the CLI for deployment')
+    .option('--path <path>', 'Path to the Vue project')
+    .option('--unlink', 'Unlink a project instead of linking')
+    .option('--list', 'List all linked projects')
+    .option('--cleanup', 'Remove invalid (non-existent) linked projects')
+    .action(irisLink);
+
+program
+    .command('vue-run-build')
+    .description('Build a Vue project and stage it for publishing')
+    .option('--path <path>', 'Path to the Vue project')
+    .option('--skip-build', 'Skip build step and use existing dist/')
+    .option('--workspace <workspace>', 'Path to Magentrix workspace to stage into')
+    .action(vueBuildStage);
+
+program
+    .command('vue-run-dev')
+    .description('Start Vue dev server with platform assets injected')
+    .option('--path <path>', 'Path to the Vue project')
+    .option('--no-inject', 'Skip asset injection')
+    .action(irisDev);
+
+program
+    .command('iris-app-delete')
+    .description('Delete a published Iris app with recovery backup')
+    .action(irisDelete);
+
+program
+    .command('iris-app-recover')
+    .description('Recover a deleted Iris app from backup')
+    .option('--list', 'List available recovery backups')
+    .action(irisRecover);
+
+// ── Unknown Command Handler ──────────────────
+program.argument('[command]', 'command to run').action((cmd) => {
+    const runMain = async () => {
+        // Check if in Vue project
+        if (isInVueProject()) {
+            console.error(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright('This command must be run in a Magentrix workspace')}\n`);
+            console.error(chalk.yellow('It looks like you\'re in a Vue project directory.'));
+            console.error(chalk.gray('This command requires a Magentrix workspace with global API key and instance URL.\n'));
+            console.error(chalk.cyan('Available commands in Vue projects:'));
+            console.error(chalk.gray('  • magentrix iris-app-link'));
+            console.error(chalk.gray('  • magentrix vue-run-build'));
+            console.error(chalk.gray('  • magentrix vue-run-dev'));
+            console.error(chalk.gray('  • magentrix update\n'));
+            process.exit(1);
+        }
+
+        await preMiddleware();
+        await main();
+        await postMiddleware();
+    };
+
+    if (cmd) {
+        console.log(`\n${chalk.bgRed.white.bold(' ERROR ')} ${chalk.redBright(`Unknown command:`)} ${chalk.bold(cmd)}\n`);
+        console.log(`${chalk.yellow('💡  Tip:')} Run ${chalk.cyan('magentrix --help')} to view available commands.\n`);
+        process.exit(1);
+    } else {
+        runMain().catch(handleFatal);
+    }
+});
+
+// ── Global Error Handler ─────────────────────
+function handleFatal(err) {
+    const divider = chalk.gray('──────────────────────────────────────────────');
+    const header = `${chalk.bgRed.white.bold(' FATAL ERROR ')}`;
+
+    console.error(`\n${divider}\n${header}`);
+    console.error(`${chalk.redBright(err?.message || 'An unexpected error occurred.')}\n`);
+
+    if (debug.enabled) {
+        debug.log('FATAL', err?.message, err?.stack);
+        debug.close();
+        if (err?.stack) {
+            console.error(chalk.dim(err.stack));
+            console.error();
+        }
+    } else {
+        console.log(`${chalk.yellow('💡  Run with')} ${chalk.cyan('--debug')} ${chalk.yellow('for full details.')}`);
+    }
+
+    console.log(divider + '\n');
+    process.exit(1);
+}
+
+program.parseAsync(process.argv).catch(handleFatal);