@mediaproc/core 1.2.1 → 1.3.0

package/README.md

@@ -40,7 +40,7 @@ showBranding();
 // ────────────────────────────────────────────────────────────
 
 // Show plugin branding (automatically detects version)
-showPluginBranding("Image");
+showPluginBranding("Image", "path/to/package.json");
 // Output:
 // ────────────────────────────────────────────────────────────
 //   💎 Image Plugin v1.3.3 · Powered by MediaProc

package/dist/__tests__/explainFlag.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=explainFlag.test.d.ts.map

package/dist/__tests__/explainFlag.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainFlag.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/explainFlag.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/explainFlag.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { explainFlag } from '../explain/explainFlag.js';
+import { ExplainMode } from '../types/explainTypes.js';
+describe('explainFlag', () => {
+    it('should generate enriched ExplainContext with mode and context fields', () => {
+        const mockCommand = {
+            name: () => 'resize',
+            parent: { name: () => 'image' },
+            options: [
+                { attributeName: 'width', defaultValue: 100 },
+                { attributeName: 'height', defaultValue: 100 },
+                { attributeName: 'format', defaultValue: 'jpg' },
+            ],
+        };
+        const args = { width: 200, _: [] };
+        const options = { width: 200, explain: 'details' };
+        let output = '';
+        const originalLog = console.log;
+        console.log = (msg) => { output += msg + '\n'; };
+        explainFlag({ command: mockCommand, args, options, mode: ExplainMode.Details });
+        console.log = originalLog;
+        expect(output).toContain('EXPLANATION');
+        expect(output).toContain('Timestamp:');
+        expect(output).toContain('Mode: details');
+        expect(output).toContain('- width: 200');
+    });
+    it('should fallback to human mode for unknown explain value', () => {
+        const mockCommand = {
+            name: () => 'resize',
+            parent: { name: () => 'image' },
+            options: [],
+        };
+        const args = { _: [] };
+        const options = { explain: 'unknown' };
+        let output = '';
+        const originalLog = console.log;
+        console.log = (msg) => { output += msg + '\n'; };
+        explainFlag({ command: mockCommand, args, options });
+        console.log = originalLog;
+        expect(output).toContain('EXPLANATION');
+        expect(output).toContain('Mode: human');
+    });
+});
+//# sourceMappingURL=explainFlag.test.js.map

package/dist/__tests__/explainFlag.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainFlag.test.js","sourceRoot":"","sources":["../../src/__tests__/explainFlag.test.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,sEAAsE,EAAE,GAAG,EAAE;QAC9E,MAAM,WAAW,GAAG;YAClB,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ;YACpB,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE;YAC/B,OAAO,EAAE;gBACP,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE;gBAC7C,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE;gBAC9C,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE;aACjD;SACF,CAAC;QACF,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAG,EAAE,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QACnD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;QAChC,OAAO,CAAC,GAAG,GAAG,CAAC,GAAQ,EAAE,EAAE,GAAG,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtD,WAAW,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QAChF,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,WAAW,GAAG;YAClB,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ;YACpB,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE;YAC/B,OAAO,EAAE,EAAE;SACZ,CAAC;QACF,MAAM,IAAI,GAAG,EAAE,CAAC,EAAG,EAAE,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QACvC,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;QAChC,OAAO,CAAC,GAAG,GAAG,CAAC,GAAQ,EAAE,EAAE,GAAG,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtD,WAAW,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/explainTemplates.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=explainTemplates.test.d.ts.map

package/dist/__tests__/explainTemplates.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainTemplates.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/explainTemplates.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/explainTemplates.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { explainHumanTemplate } from '../explain/templates/explainHumanTemplate.js';
+import { explainDetailsTemplate } from '../explain/templates/explainDetailsTemplate.js';
+import { ExplainMode } from '../types/explainTypes.js';
+describe('explain templates', () => {
+    const baseContext = {
+        command: 'resize',
+        plugin: 'image',
+        cliVersion: '1.0.0',
+        pluginVersion: '1.0.0',
+        timestamp: '2026-01-18T12:00:00Z',
+        user: 'testuser',
+        platform: 'linux x64',
+        mode: ExplainMode.Human,
+        inputs: { inputPath: 'in.jpg', width: 200 },
+        outputs: { outputPath: 'out.jpg' },
+        usedFlags: { width: { value: 200, source: 'user' } },
+        decisions: [
+            { key: 'width', value: 200, reason: 'user specified' }
+        ],
+        outcome: { result: 'A new file will be created at out.jpg' },
+        explainFlow: ['step 1', 'step 2'],
+    };
+    it('should render enriched context in human template', () => {
+        const result = explainHumanTemplate(baseContext);
+        expect(result).toContain('Timestamp: 2026-01-18T12:00:00Z');
+        expect(result).toContain('User: testuser');
+        expect(result).toContain('Platform: linux x64');
+        expect(result).toContain('Mode: human');
+        expect(result).toContain('width will be set to 200');
+    });
+    it('should render enriched context in details template', () => {
+        const ctx = { ...baseContext, mode: ExplainMode.Details };
+        const result = explainDetailsTemplate(ctx);
+        expect(result).toContain('Timestamp: 2026-01-18T12:00:00Z');
+        expect(result).toContain('User: testuser');
+        expect(result).toContain('Platform: linux x64');
+        expect(result).toContain('Mode: details');
+        expect(result).toContain('Inputs:');
+        expect(result).toContain('Outputs:');
+    });
+});
+//# sourceMappingURL=explainTemplates.test.js.map

package/dist/__tests__/explainTemplates.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainTemplates.test.js","sourceRoot":"","sources":["../../src/__tests__/explainTemplates.test.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,EAAE,WAAW,EAAkB,MAAM,0BAA0B,CAAC;AAEvE,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,MAAM,WAAW,GAAmB;QAClC,OAAO,EAAE,QAAQ;QACjB,MAAM,EAAE,OAAO;QACf,UAAU,EAAE,OAAO;QACnB,aAAa,EAAE,OAAO;QACtB,SAAS,EAAE,sBAAsB;QACjC,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,WAAW;QACrB,IAAI,EAAE,WAAW,CAAC,KAAK;QACvB,MAAM,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE;QAC3C,OAAO,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE;QAClC,SAAS,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;QACpD,SAAS,EAAE;YACT,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE;SACvD;QACD,OAAO,EAAE,EAAE,MAAM,EAAE,uCAAuC,EAAE;QAC5D,WAAW,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;KAClC,CAAC;IAEF,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;QACjD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,iCAAiC,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,GAAG,GAAG,EAAE,GAAG,WAAW,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,iCAAiC,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/branding/index.d.ts

@@ -0,0 +1,2 @@
+export * from './branding.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/branding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/branding/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC"}

package/dist/branding/index.js

@@ -0,0 +1,3 @@
+// Branding
+export * from './branding.js';
+//# sourceMappingURL=index.js.map

package/dist/branding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/branding/index.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,cAAc,eAAe,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,3 @@
+export * from './errorTypes.js';
+export * from './exitCodes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+// Errors & Exit Codes
+export * from './errorTypes.js';
+export * from './exitCodes.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,sBAAsB;AACtB,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/{explainFlag.d.ts → explain/explainFlag.d.ts}

@@ -1,14 +1,14 @@
-import { ExplainFormat } from './formatters/explainFormatter.js';
+import { ExplainMode } from '../types/explainTypes.js';
 /**
  * explainFlag - Automatically gathers command context, prints explanation, then runs the handler.
  * @param params - { commandName, args, options, handler }
  */
-export declare function explainFlag({ command, args, options, inputKeys, outputKeys, format, }: {
+export declare function explainFlag({ command, args, options, inputKeys, outputKeys, mode, }: {
     command: any;
     args?: Record<string, any>;
     options?: Record<string, any>;
     inputKeys?: string[];
     outputKeys?: string[];
-    format?: ExplainFormat;
+    mode?: ExplainMode;
 }): void;
 //# sourceMappingURL=explainFlag.d.ts.map

package/dist/explain/explainFlag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainFlag.d.ts","sourceRoot":"","sources":["../../src/explain/explainFlag.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAIvE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,IAAS,EACT,OAAY,EACZ,SAAkC,EAClC,UAA0C,EAC1C,IAAwB,GACzB,EAAE;IACD,OAAO,EAAE,GAAG,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB,QAgKA"}

package/dist/{explainFlag.js → explain/explainFlag.js}

@@ -1,12 +1,13 @@
 import chalk from 'chalk';
-import { explainFormatter } from './formatters/explainFormatter.js';
-import { getCliVersion, getVersion } from './branding/branding.js';
+import { explainFormatter } from '../formatters/explainFormatter.js';
+import { getCliVersion, getVersion } from '../branding/branding.js';
+import { ExplainMode } from '../types/explainTypes.js';
 import os from 'os';
 /**
  * explainFlag - Automatically gathers command context, prints explanation, then runs the handler.
  * @param params - { commandName, args, options, handler }
  */
-export function explainFlag({ command, args = {}, options = {}, inputKeys = ['input', 'inputPath'], outputKeys = ['output', 'outputPath', 'o'], format = 'human', }) {
+export function explainFlag({ command, args = {}, options = {}, inputKeys = ['input', 'inputPath'], outputKeys = ['output', 'outputPath', 'o'], mode = ExplainMode.Human, }) {
     // Auto-detect command name
     const commandName = command?.name?.() || command?._name || 'unknown';
     const environment = {
@@ -15,41 +16,105 @@ export function explainFlag({ command, args = {}, options = {}, inputKeys = ['in
         nodeVersion: process.version,
         shell: process.env.SHELL || process.env.TERM || 'unknown',
     };
-    // Detect input/output paths
+    // Detect input/output paths and gather all input/output arguments
     let inputPath = '';
     let outputPath = '';
+    let allInputs = {};
+    let allOutputs = {};
     for (const k of inputKeys) {
-        if (args[k])
+        if (args[k]) {
             inputPath = args[k];
-        if (options[k])
+            allInputs[k] = args[k];
+        }
+        if (options[k]) {
             inputPath = options[k];
+            allInputs[k] = options[k];
+        }
     }
     for (const k of outputKeys) {
-        if (args[k])
+        if (args[k]) {
             outputPath = args[k];
-        if (options[k])
+            allOutputs[k] = args[k];
+        }
+        if (options[k]) {
             outputPath = options[k];
+            allOutputs[k] = options[k];
+        }
     }
     // Gather used flags
     let explainValue = undefined;
+    let explainOnly = false;
     if (typeof options.explain === 'string') {
         explainValue = options.explain;
+        if (explainValue === 'only')
+            explainOnly = true;
     }
     else if (Array.isArray(args._) && args._.length > 0) {
         // Check for --explain details as positional
         const idx = args._.findIndex((v) => v === 'explain');
         if (idx !== -1 && args._[idx + 1]) {
             explainValue = args._[idx + 1];
+            if (explainValue === 'only')
+                explainOnly = true;
         }
     }
-    if (explainValue === 'details' || explainValue === 'json' || explainValue === 'human') {
-        format = explainValue;
+    if (explainValue === 'details') {
+        mode = ExplainMode.Details;
+    }
+    else if (explainValue === 'json') {
+        mode = ExplainMode.Json;
+    }
+    else if (explainValue === 'human') {
+        mode = ExplainMode.Human;
     }
+    else if (explainValue) {
+        // fallback for unknown explain values
+        console.warn(chalk.yellow(`Unknown explain mode: ${explainValue}, using 'human' mode.`));
+        mode = ExplainMode.Human;
+    }
+    // Gather all possible flags from command (Commander.js API)
     const usedFlags = {};
-    for (const [key, value] of Object.entries(options)) {
-        if (key === 'explain')
-            continue;
-        usedFlags[key] = { value, source: value !== undefined ? 'user' : 'system' };
+    const omittedFlags = {};
+    if (command && typeof command.options === 'object') {
+        for (const opt of command.options) {
+            const flagName = opt.attributeName || opt.long?.replace(/^--/, '') || opt.short?.replace(/^-/, '');
+            if (!flagName)
+                continue;
+            let userValue = options[flagName];
+            // Handle boolean flags
+            if (typeof userValue === 'boolean')
+                userValue = userValue ? 'enabled' : 'disabled';
+            // Handle array flags
+            if (Array.isArray(userValue))
+                userValue = userValue.join(', ');
+            if (userValue !== undefined) {
+                usedFlags[flagName] = { value: userValue, source: 'user' };
+            }
+            else if (Object.prototype.hasOwnProperty.call(opt, 'defaultValue')) {
+                let defVal = opt.defaultValue;
+                if (typeof defVal === 'boolean')
+                    defVal = defVal ? 'enabled' : 'disabled';
+                if (Array.isArray(defVal))
+                    defVal = defVal.join(', ');
+                usedFlags[flagName] = { value: defVal, source: 'default' };
+                omittedFlags[flagName] = { defaultValue: defVal, source: 'default' };
+            }
+            else {
+                usedFlags[flagName] = { value: undefined, source: 'system' };
+            }
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(options)) {
+            if (key === 'explain')
+                continue;
+            let val = value;
+            if (typeof val === 'boolean')
+                val = val ? 'enabled' : 'disabled';
+            if (Array.isArray(val))
+                val = val.join(', ');
+            usedFlags[key] = { value: val, source: val !== undefined ? 'user' : 'system' };
+        }
     }
     // Build ExplainContext with plugin/command info and version
     // Get CLI and plugin version using branding utilities
@@ -73,12 +138,19 @@ export function explainFlag({ command, args = {}, options = {}, inputKeys = ['in
         plugin: command?.parent?.name?.() || undefined,
         cliVersion,
         pluginVersion,
-        inputs: { inputPath, outputPath },
+        // Context enrichment
+        timestamp: new Date().toISOString(),
+        user: process.env.USER || process.env.USERNAME || 'unknown',
+        platform: `${os.platform()} ${os.arch()}`,
+        mode,
+        inputs: { inputPath, outputPath, ...allInputs },
+        outputs: Object.keys(allOutputs).length > 0 ? allOutputs : undefined,
         usedFlags,
+        omittedFlags: Object.keys(omittedFlags).length > 0 ? omittedFlags : undefined,
         decisions: Object.entries(usedFlags).map(([key, v]) => ({
             key,
             value: v.value,
-            reason: v.source === 'user' ? 'user specified' : 'default',
+            reason: v.source === 'user' ? 'user specified' : (v.source === 'default' ? 'default' : 'system'),
         })),
         outcome: {
             result: outputPath ? `A new file will be created at ${outputPath}` : 'Operation will complete',
@@ -100,6 +172,7 @@ export function explainFlag({ command, args = {}, options = {}, inputKeys = ['in
             '6. Show summary and any errors encountered.'
         ],
         environment,
+        explainOnly,
         technical: {
             library: 'sharp',
             tool: 'mediaproc',
@@ -111,8 +184,8 @@ export function explainFlag({ command, args = {}, options = {}, inputKeys = ['in
         },
     };
     // Print explanation only
-    const explanation = explainFormatter(context, format);
-    if (format === 'json') {
+    const explanation = explainFormatter(context, mode);
+    if (mode === ExplainMode.Json) {
         // Add a styled header for JSON output
         // Print JSON with a clear header
         console.log(chalk.bold.bgBlueBright.white(' EXPLANATION (JSON) '));

package/dist/explain/explainFlag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainFlag.js","sourceRoot":"","sources":["../../src/explain/explainFlag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAkB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGpB;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,OAAO,EACP,IAAI,GAAG,EAAE,EACT,OAAO,GAAG,EAAE,EACZ,SAAS,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,EAClC,UAAU,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,CAAC,EAC1C,IAAI,GAAG,WAAW,CAAC,KAAK,GAQzB;IACC,2BAA2B;IAC3B,MAAM,WAAW,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,OAAO,EAAE,KAAK,IAAI,SAAS,CAAC;IACrE,MAAM,WAAW,GAAG;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,GAAG;QACrD,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,SAAS;KAC1D,CAAC;IACF,kEAAkE;IAClE,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,SAAS,GAAwB,EAAE,CAAC;IACxC,IAAI,UAAU,GAAwB,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAAC,CAAC;QAC7D,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,CAAC;IACxE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAAC,CAAC;QAC/D,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAAC,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,CAAC;IAC1E,CAAC;IAED,oBAAoB;IACpB,IAAI,YAAY,GAAuB,SAAS,CAAC;IACjD,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACxC,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,YAAY,KAAK,MAAM;YAAE,WAAW,GAAG,IAAI,CAAC;IAClD,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,4CAA4C;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QAC1D,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;YAClC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YAC/B,IAAI,YAAY,KAAK,MAAM;gBAAE,WAAW,GAAG,IAAI,CAAC;QAClD,CAAC;IACH,CAAC;IACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC;IAC7B,CAAC;SAAM,IAAI,YAAY,KAAK,MAAM,EAAE,CAAC;QACnC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC;IAC1B,CAAC;SAAM,IAAI,YAAY,KAAK,OAAO,EAAE,CAAC;QACpC,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC;IAC3B,CAAC;SAAM,IAAI,YAAY,EAAE,CAAC;QACxB,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,yBAAyB,YAAY,uBAAuB,CAAC,CAAC,CAAC;QACzF,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC;IAC3B,CAAC;IACD,4DAA4D;IAC5D,MAAM,SAAS,GAA0E,EAAE,CAAC;IAC5F,MAAM,YAAY,GAA6D,EAAE,CAAC;IAClF,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACnG,IAAI,CAAC,QAAQ;gBAAE,SAAS;YACxB,IAAI,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAClC,uBAAuB;YACvB,IAAI,OAAO,SAAS,KAAK,SAAS;gBAAE,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;YACnF,qBAAqB;YACrB,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;gBAAE,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YAC7D,CAAC;iBAAM,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,CAAC;gBACrE,IAAI,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC;gBAC9B,IAAI,OAAO,MAAM,KAAK,SAAS;oBAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;gBAC1E,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtD,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAC3D,YAAY,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YACvE,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS;YAChC,IAAI,GAAG,GAAG,KAAK,CAAC;YAChB,IAAI,OAAO,GAAG,KAAK,SAAS;gBAAE,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;YACjE,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;gBAAE,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7C,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,sDAAsD;IACtD,IAAI,UAAU,GAAuB,SAAS,CAAC;IAC/C,IAAI,aAAa,GAAuB,SAAS,CAAC;IAClD,IAAI,CAAC;QACH,UAAU,GAAG,aAAa,EAAE,CAAC;QAC7B,4EAA4E;QAC5E,IAAI,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;YAC9B,uEAAuE;YACvE,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,UAAU,GAAG,iBAAiB,UAAU,eAAe,CAAC;YAC9D,aAAa,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,uCAAuC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,OAAO,GAAmB;QAC9B,OAAO,EAAE,WAAW;QACpB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,SAAS;QAC9C,UAAU;QACV,aAAa;QACb,qBAAqB;QACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,SAAS;QAC3D,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QACzC,IAAI;QACJ,MAAM,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,SAAS,EAAE;QAC/C,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACpE,SAAS;QACT,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;QAC7E,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtD,GAAG;YACH,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;SACjG,CAAC,CAAC;QACH,OAAO,EAAE;YACP,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,iCAAiC,UAAU,EAAE,CAAC,CAAC,CAAC,yBAAyB;YAC9F,WAAW,EAAE;gBACX,4EAA4E;gBAC5E,sDAAsD;gBACtD,qEAAqE;gBACrE,4DAA4D;aAC7D;YACD,MAAM,EAAE,EAAE,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,EAAE,EAAE,oCAAoC;SACnD;QACD,WAAW,EAAE;YACX,8DAA8D;YAC9D,6DAA6D;YAC7D,+EAA+E;YAC/E,4DAA4D;YAC5D,2CAA2C;YAC3C,6CAA6C;SAC9C;QACD,WAAW;QACX,WAAW;QACX,SAAS,EAAE;YACT,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,sCAAsC;YACnD,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC;YACnC,gBAAgB,EAAE,8BAA8B;YAChD,aAAa,EAAE,mCAAmC;YAClD,WAAW,EAAE,4CAA4C;SAC1D;KACF,CAAC;IAEF,yBAAyB;IACzB,MAAM,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,IAAI,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC;QAC9B,sCAAsC;QACtC,iCAAiC;QACjC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC;QACnE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/explain/hook/explainPreActionHook.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+/**
+ * Global preAction hook for Commander.js to support --explain and --explain=only.
+ * Prints explanation before command runs. If --explain=only, exits after explanation.
+ */
+export declare function explainPreActionHook(thisCmd: Command, actionCmd?: Command): void;
+//# sourceMappingURL=explainPreActionHook.d.ts.map

package/dist/explain/hook/explainPreActionHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainPreActionHook.d.ts","sourceRoot":"","sources":["../../../src/explain/hook/explainPreActionHook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,IAAI,CAsBhF"}

package/dist/explain/hook/explainPreActionHook.js

@@ -0,0 +1,29 @@
+import { explainFlag } from '../explainFlag.js';
+/**
+ * Global preAction hook for Commander.js to support --explain and --explain=only.
+ * Prints explanation before command runs. If --explain=only, exits after explanation.
+ */
+export function explainPreActionHook(thisCmd, actionCmd) {
+    // Commander passes the command instance as 'thisCmd', and the subcommand as 'actionCmd'.
+    // We'll use 'actionCmd' if available (for subcommands), otherwise 'thisCmd'.
+    const cmd = actionCmd || thisCmd;
+    const opts = cmd.opts ? cmd.opts() : {};
+    // Gather positional arguments if available (Commander stores them in cmd.args or cmd._args)
+    let positionalArgs = {};
+    if (Array.isArray(cmd.args) && cmd.args.length > 0) {
+        positionalArgs = { _: cmd.args };
+    }
+    // Support --explain, --explain=details, --explain=only, etc.
+    if (opts.explain) {
+        explainFlag({
+            command: cmd,
+            args: positionalArgs,
+            options: opts,
+        });
+        // If --explain=only, do not execute the command
+        if (opts.explain === 'only') {
+            process.exit(0);
+        }
+    }
+}
+//# sourceMappingURL=explainPreActionHook.js.map

package/dist/explain/hook/explainPreActionHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainPreActionHook.js","sourceRoot":"","sources":["../../../src/explain/hook/explainPreActionHook.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB,EAAE,SAAmB;IACxE,yFAAyF;IACzF,6EAA6E;IAC7E,MAAM,GAAG,GAAY,SAAS,IAAI,OAAO,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,4FAA4F;IAC5F,IAAI,cAAc,GAAwB,EAAE,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAE,GAAW,CAAC,IAAI,CAAC,IAAK,GAAW,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrE,cAAc,GAAG,EAAE,CAAC,EAAG,GAAW,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,6DAA6D;IAC7D,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,WAAW,CAAC;YACV,OAAO,EAAE,GAAG;YACZ,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;QACH,gDAAgD;QAChD,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/explain/index.d.ts

@@ -0,0 +1,5 @@
+export * from './templates/explainHumanTemplate.js';
+export * from './templates/explainDetailsTemplate.js';
+export * from './explainFlag.js';
+export * from './hook/explainPreActionHook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/explain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explain/index.ts"],"names":[],"mappings":"AACA,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,gCAAgC,CAAC"}

package/dist/explain/index.js

@@ -0,0 +1,6 @@
+// Explain System (Templates, Flag, Hook)
+export * from './templates/explainHumanTemplate.js';
+export * from './templates/explainDetailsTemplate.js';
+export * from './explainFlag.js';
+export * from './hook/explainPreActionHook.js';
+//# sourceMappingURL=index.js.map

package/dist/explain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/explain/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,gCAAgC,CAAC"}

package/dist/explain/templates/explainDetailsTemplate.d.ts

@@ -0,0 +1,3 @@
+import { ExplainContext } from '../../types/explainTypes.js';
+export declare function explainDetailsTemplate(context: ExplainContext): string;
+//# sourceMappingURL=explainDetailsTemplate.d.ts.map

package/dist/explain/templates/explainDetailsTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainDetailsTemplate.d.ts","sourceRoot":"","sources":["../../../src/explain/templates/explainDetailsTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CA8FtE"}

package/dist/explain/templates/explainDetailsTemplate.js

@@ -0,0 +1,97 @@
+import chalk from 'chalk';
+export function explainDetailsTemplate(context) {
+    let output = '';
+    output += chalk.bold.bgMagenta.white('╔════════════════════════════════════════════════════════════════╗') + '\n';
+    output += chalk.bold.bgMagenta.white('║                  EXPLANATION (DETAILS)                       ║') + '\n';
+    output += chalk.bold.bgMagenta.white('╚════════════════════════════════════════════════════════════════╝') + '\n';
+    if (context.explainOnly) {
+        output += chalk.bgYellow.black(' [EXPLAIN-ONLY MODE: No command will be executed] ') + '\n';
+    }
+    // Context enrichment (timestamp, user, platform, mode)
+    output += chalk.gray(`Timestamp: ${context.timestamp ?? 'N/A'} | User: ${context.user ?? 'N/A'} | Platform: ${context.platform ?? 'N/A'} | Mode: ${context.mode ?? 'N/A'}`) + '\n';
+    if (context.plugin || context.cliVersion || context.pluginVersion) {
+        output += chalk.bold(`Plugin: ${context.plugin || 'N/A'} | CLI Version: ${context.cliVersion || 'N/A'} | Plugin Version: ${context.pluginVersion || 'N/A'}`) + '\n';
+    }
+    // Inputs/Outputs section
+    if (context.inputs || context.outputs) {
+        output += chalk.bold.bgGray.white('\n──────────────────────── Inputs & Outputs ────────────────────────') + '\n';
+        if (context.inputs && Object.keys(context.inputs).length > 0) {
+            output += chalk.whiteBright('Inputs:') + '\n';
+            for (const [k, v] of Object.entries(context.inputs)) {
+                output += chalk.gray(`  - ${k}: ${v}`) + '\n';
+            }
+        }
+        if (context.outputs && Object.keys(context.outputs).length > 0) {
+            output += chalk.whiteBright('Outputs:') + '\n';
+            for (const [k, v] of Object.entries(context.outputs)) {
+                output += chalk.gray(`  - ${k}: ${v}`) + '\n';
+            }
+        }
+    }
+    // Technical workflow
+    output += chalk.bold.underline(`\n${chalk.cyan('Technical Workflow:')}`) + '\n';
+    if (context.explainFlow && Array.isArray(context.explainFlow) && context.explainFlow.length > 0) {
+        for (const step of context.explainFlow) {
+            output += chalk.greenBright(`• ${step}`) + '\n';
+        }
+    }
+    // Flags used
+    output += chalk.bold.underline(`\n${chalk.cyan('Flags Used:')}`) + '\n';
+    if (context.usedFlags) {
+        const userFlags = Object.entries(context.usedFlags).filter(([_, v]) => v.source === 'user');
+        const defaultFlags = Object.entries(context.usedFlags).filter(([_, v]) => v.source === 'default');
+        const systemFlags = Object.entries(context.usedFlags).filter(([_, v]) => v.source === 'system');
+        if (userFlags.length > 0) {
+            output += chalk.bold.bgGray.white('\n──────────────────────────── User Flags ──────────────────────────') + '\n';
+            for (const [k, v] of userFlags) {
+                let valueStr = (v.value === undefined || Number.isNaN(v.value)) ? 'N/A' : v.value;
+                output += chalk.gray(`  - ${k}: ${valueStr}`) + '\n';
+            }
+        }
+        if (defaultFlags.length > 0) {
+            output += chalk.bold.bgGray.white('\n─────────────────────────── Default Flags ───────────────────────') + '\n';
+            for (const [k, v] of defaultFlags) {
+                let valueStr = (v.value === undefined || Number.isNaN(v.value)) ? 'N/A' : v.value;
+                output += chalk.gray(`  - ${k}: ${valueStr}`) + '\n';
+            }
+        }
+        if (systemFlags.length > 0) {
+            output += chalk.bold.bgGray.white('\n─────────────────────────── System Flags ────────────────────────') + '\n';
+            for (const [k, v] of systemFlags) {
+                let valueStr = (v.value === undefined || Number.isNaN(v.value)) ? 'N/A' : v.value;
+                output += chalk.gray(`  - ${k}: ${valueStr}`) + '\n';
+            }
+        }
+    }
+    // Errors and warnings
+    if (context.outcome && Array.isArray(context.outcome.errors) && context.outcome.errors.length > 0) {
+        output += chalk.redBright.bold('\nErrors:') + '\n';
+        for (const err of context.outcome.errors) {
+            output += chalk.redBright(`  - ${err}`) + '\n';
+        }
+    }
+    if (context.outcome && Array.isArray(context.outcome.warnings) && context.outcome.warnings.length > 0) {
+        output += chalk.yellowBright.bold('\nWarnings:') + '\n';
+        for (const warn of context.outcome.warnings) {
+            output += chalk.yellowBright(`  - ${warn}`) + '\n';
+        }
+    }
+    // Developer info
+    if (context.technical && typeof context.technical === 'object') {
+        output += chalk.bold.bgGray.white('\n──────────────────────── Technical Details ──────────────────────') + '\n';
+        for (const [k, v] of Object.entries(context.technical)) {
+            let valueStr = (v === undefined || Number.isNaN(v)) ? 'N/A' : v;
+            output += chalk.gray(`  - ${k}: ${valueStr}`) + '\n';
+        }
+    }
+    if (context.environment && typeof context.environment === 'object') {
+        output += chalk.bold.bgGray.white('\n─────────────────────────── Environment ────────────────────────') + '\n';
+        output += chalk.bold(`  cwd: ${context.environment.cwd ?? 'N/A'}`) + '\n';
+        output += chalk.bold(`  OS: ${context.environment.os ?? 'N/A'}`) + '\n';
+        output += chalk.bold(`  Node: ${context.environment.nodeVersion ?? 'N/A'}`) + '\n';
+        output += chalk.bold(`  Shell: ${context.environment.shell ?? 'N/A'}`) + '\n';
+    }
+    output += chalk.gray('\nTip: Use --explain for a simple summary.');
+    return output.trim();
+}
+//# sourceMappingURL=explainDetailsTemplate.js.map

package/dist/explain/templates/explainDetailsTemplate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainDetailsTemplate.js","sourceRoot":"","sources":["../../../src/explain/templates/explainDetailsTemplate.ts"],"names":[],"mappings":"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"}

package/dist/explain/templates/explainHumanTemplate.d.ts

@@ -0,0 +1,3 @@
+import { ExplainContext } from '../../types/explainTypes.js';
+export declare function explainHumanTemplate(context: ExplainContext): string;
+//# sourceMappingURL=explainHumanTemplate.d.ts.map

package/dist/explain/templates/explainHumanTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainHumanTemplate.d.ts","sourceRoot":"","sources":["../../../src/explain/templates/explainHumanTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAyCpE"}

package/dist/explain/templates/explainHumanTemplate.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+export function explainHumanTemplate(context) {
+    let output = '';
+    output += chalk.bold.bgBlueBright.white('╔════════════════════════════════════════════════════════════════╗') + '\n';
+    output += chalk.bold.bgBlueBright.white('║                        EXPLANATION                           ║') + '\n';
+    output += chalk.bold.bgBlueBright.white('╚════════════════════════════════════════════════════════════════╝') + '\n';
+    if (context.explainOnly) {
+        output += chalk.bgYellow.black(' [EXPLAIN-ONLY MODE: No command will be executed] ') + '\n';
+    }
+    // Context enrichment (timestamp, user, platform, mode)
+    output += chalk.gray(`Timestamp: ${context.timestamp ?? 'N/A'} | User: ${context.user ?? 'N/A'} | Platform: ${context.platform ?? 'N/A'} | Mode: ${context.mode ?? 'N/A'}`) + '\n';
+    // Friendly, conversational summary
+    if (context.plugin) {
+        output += chalk.bold(`This command uses the "${context.plugin}" plugin.`) + '\n';
+    }
+    // What will happen
+    output += chalk.bold.underline(`\nWhat will happen:`) + '\n';
+    if (context.decisions && context.decisions.length > 0) {
+        for (const d of context.decisions) {
+            let valueStr = (d.value === undefined || Number.isNaN(d.value)) ? 'N/A' : d.value;
+            output += chalk.green(`• ${d.key} will be set to ${valueStr}`) + '\n';
+        }
+    }
+    else {
+        output += chalk.green('• The command will use default settings.') + '\n';
+    }
+    // Result
+    if (context.outcome && context.outcome.result) {
+        output += chalk.bold.underline(`\nResult:`) + '\n';
+        output += chalk.yellow(`• ${context.outcome.result}`) + '\n';
+        if (context.outcome.sideEffects && Array.isArray(context.outcome.sideEffects) && context.outcome.sideEffects.length > 0) {
+            for (const s of context.outcome.sideEffects) {
+                output += chalk.yellow(`• ${s}`) + '\n';
+            }
+        }
+    }
+    // Tip
+    output += chalk.gray('\nTip: Use --explain=details for a technical breakdown.');
+    return output.trim();
+}
+//# sourceMappingURL=explainHumanTemplate.js.map