wanas-zcrm-extractor 1.6.0 → 1.6.2

package/README.md

@@ -420,7 +420,9 @@ metadata/
 
 ## 🩺 Troubleshooting
 
-Every command writes a timestamped **debug log** to `~/.zcrm/logs/` (e.g. `pull-<timestamp>.log`, `audit-<timestamp>.log`) capturing all activity for that run — including the quiet "skipped" lines and the **full API error bodies** that aren't printed to the console. When a command fails, its log path is shown in the output. `zcrm pull` additionally writes a copy into its output folder at `<output>/.zcrm/.logs/`.
+Errors are reported in a single, consistent format: **expected** problems (e.g. not logged in, bad input) show a clean message with an actionable hint, while **unexpected** errors show the real underlying reason plus how to reach support — so you're never left with a raw stack trace.
+
+Every command also writes a timestamped **debug log** to `~/.zcrm/logs/` (e.g. `pull-<timestamp>.log`, `audit-<timestamp>.log`) capturing all activity for that run — including the quiet "skipped" lines and the **full API error bodies** that aren't printed to the console. When a command fails, its log path is shown in the output. `zcrm pull` additionally writes a copy into its output folder at `<output>/.zcrm/.logs/`.
 
 ---
 

package/bin/cli.js

@@ -40,9 +40,33 @@ let debugLogPath = null;
   }
 })();
 
-// Point the user at the debug log when a command exits with an error.
+const { CliError, reportError } = require('../src/utils/errorReporter');
+
+let errorReported = false;
+/**
+ * Unified fatal-error handler: render one consistent error response (with a
+ * "contact support" block for unexpected errors), then exit non-zero.
+ * @param {Error|object|string} error
+ * @param {string} context
+ */
+function fail(error, context) {
+  errorReported = true;
+  reportError(error, { context, debugLogPath });
+  process.exit(1);
+}
+
+// Anything that escapes a command handler is funnelled through the same unified
+// response, so the user never sees a raw stack trace — they always get a clean
+// message and a way to contact support.
+process.on('uncaughtException', (err) => fail(err, 'uncaughtException'));
+process.on('unhandledRejection', (reason) => {
+  fail(reason instanceof Error ? reason : new Error(`Unhandled rejection: ${reason}`), 'unhandledRejection');
+});
+
+// Fallback: if something exits non-zero without going through fail(), still
+// point the user at the debug log.
 process.on('exit', (code) => {
-  if (code && debugLogPath) {
+  if (code && !errorReported && debugLogPath) {
     try { process.stderr.write(`\x1b[90mℹ Debug log: ${debugLogPath}\x1b[0m\n`); } catch (e) { /* ignore */ }
   }
 });
@@ -88,10 +112,13 @@ const getBanner = () => {
   try {
     const fs = require('fs');
     const bannerPath = path.join(__dirname, '../banner.txt');
+    const version = require('../package.json').version;
     if (fs.existsSync(bannerPath)) {
       const banner = fs.readFileSync(bannerPath, 'utf8');
-      return `\x1b[34m${banner}\x1b[0m\n`;
+      return `\x1b[34m${banner}\x1b[0m\n\x1b[1;36m                          zcrm v${version}\x1b[0m\n`;
     }
+    // Banner art missing — still show the version line.
+    return `\x1b[1;36m zcrm v${version}\x1b[0m\n`;
   } catch (err) {
     // Fail silently
   }
@@ -315,8 +342,7 @@ program
       console.log('\x1b[1;32m====================================================================\x1b[0m\n');
       process.exit(0);
     } catch (err) {
-      console.error('\n❌ Login error:', err.message);
-      process.exit(1);
+      fail(err, 'login');
     }
   });
 
@@ -339,8 +365,7 @@ program
     authService.loadTokens();
 
     if (!authService.isAuthenticated()) {
-      console.error('\n❌ Error: Not authenticated. Please login first using:\n   zcrm login');
-      process.exit(1);
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'auth');
     }
 
     try {
@@ -374,8 +399,7 @@ program
       
       process.exit(0);
     } catch (err) {
-      console.error(`\n❌ Failed to query session info: ${err.message}`);
-      process.exit(1);
+      fail(err, 'whoami');
     }
   });
 
@@ -455,8 +479,7 @@ program
     authService.loadTokens();
 
     if (!authService.isAuthenticated()) {
-      console.error('\n❌ Error: Not authenticated. Please login first using:\n   zcrm login');
-      process.exit(1);
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'auth');
     }
 
     const outputDir = path.resolve(options.output);
@@ -536,10 +559,11 @@ program
             }
             break;
           case 'FAILURE':
+            // Clean up an in-progress bar line; the unified handler (catch
+            // below) renders the actual error.
             if (inModulesPhase || inFunctionsPhase) {
               process.stdout.write('\n');
             }
-            console.error(`\n❌ Error: ${message}`);
             break;
           case 'COMPLETE':
             console.log('\n\x1b[1;32m====================================================================\x1b[0m');
@@ -575,8 +599,7 @@ program
 
       process.exit(0);
     } catch (error) {
-      console.error(`\n❌ Metadata pull failed: ${error.message}`);
-      process.exit(1);
+      fail(error, 'pull');
     }
   });
 
@@ -597,8 +620,7 @@ program
     // Ensure user is authenticated
     authService.loadTokens();
     if (!authService.isAuthenticated()) {
-      console.error('\n❌ You are not logged in. Please run `zcrm login` first.');
-      process.exit(1);
+      fail(new CliError('You are not logged in.', 'Run: zcrm login'), 'audit');
     }
 
     try {
@@ -611,15 +633,14 @@ program
     } catch (error) {
       const apiMsg = shortErrorMessage(error);
       const isScope = error.response?.data?.code === 'OAUTH_SCOPE_MISMATCH' || /scope/i.test(apiMsg || '');
-      console.error(`\n❌ Audit log export failed: ${apiMsg}`);
       if (isScope) {
-        console.error('\n\x1b[33mThis needs the audit-log scopes \x1b[1mZohoCRM.settings.audit_logs.CREATE\x1b[0m\x1b[33m and');
-        console.error('\x1b[1mZohoCRM.settings.audit_logs.READ\x1b[0m\x1b[33m, which your current session was not granted.');
-        console.error('Re-authenticate to add them:\x1b[0m  \x1b[36mzcrm logout\x1b[0m  then  \x1b[36mzcrm login\x1b[0m');
-        console.error('\x1b[90m(If the download step then reports a file-scope error, add ZohoFiles.files.READ');
-        console.error('to ZOHO_SCOPES and log in again.)\x1b[0m');
+        fail(new CliError(
+          `Audit log export failed: ${apiMsg}`,
+          'Needs scopes ZohoCRM.settings.audit_logs.CREATE & .READ — re-authenticate: zcrm logout then zcrm login.\n   (If the download step then reports a file-scope error, add ZohoFiles.files.READ to ZOHO_SCOPES and log in again.)'
+        ), 'audit');
+      } else {
+        fail(error, 'audit');
       }
-      process.exit(1);
     }
   });
 
@@ -636,13 +657,11 @@ program
         console.log('\n\x1b[36m📘 Wanas Extractor - LLM System Manual:\x1b[0m\n');
         console.log(content);
       } else {
-        console.error('\n❌ Error: llm.md file not found in package directory.');
-        process.exit(1);
+        fail(new Error('llm.md file not found in package directory.'), 'llm');
       }
       process.exit(0);
     } catch (err) {
-      console.error('\n❌ Error reading llm.md:', err.message);
-      process.exit(1);
+      fail(err, 'llm');
     }
   });
 
@@ -673,9 +692,7 @@ program
       }
 
       if (!skillGenerator.TARGETS[ide]) {
-        console.error(`\n❌ Unknown IDE/AI target: "${ide}".`);
-        console.error(`   Valid values: ${Object.keys(skillGenerator.TARGETS).join(', ')}`);
-        process.exit(1);
+        fail(new CliError(`Unknown IDE/AI target: "${ide}".`, `Valid values: ${Object.keys(skillGenerator.TARGETS).join(', ')}`), 'skill');
       }
 
       const projectDir = path.resolve(options.dir);
@@ -731,8 +748,7 @@ program
       console.log('\x1b[1;32m====================================================================\x1b[0m\n');
       process.exit(0);
     } catch (err) {
-      console.error(`\n❌ Skill generation failed: ${err.message}`);
-      process.exit(1);
+      fail(err, 'skill');
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wanas-zcrm-extractor",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Local Zoho CRM V8 Metadata Extractor CLI and Web Dashboard Utility",
   "main": "server.js",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "start": "node server.js",
-    "dev": "nodemon server.js"
+    "dev": "nodemon server.js",
+    "test": "node test/run.js",
+    "prepublishOnly": "node test/run.js"
   },
   "files": [
     "bin",

package/src/services/auditLogService.js

@@ -11,11 +11,13 @@ async function delay(ms) {
 
 async function exportAuditLog(filterFile) {
   try {
-    // For a full export the request body is OPTIONAL — and sending an object
-    // without a non-empty `criteria` is rejected by Zoho (400). So the default
-    // (no filter) sends NO body, and a filter file (which must contain a valid
-    // `audit_log_export` criteria object) overrides it when supplied.
-    let requestBody = null;
+    // For a full export the request body is OPTIONAL. Sending an object WITH an
+    // empty `criteria` is rejected (400), and sending NO body trips a 415
+    // (missing content type). So the default (no filter) sends an empty JSON
+    // object `{}` — which carries the JSON content type and contains no
+    // criteria, i.e. "export everything". A filter file (which must contain a
+    // valid `audit_log_export` criteria object) overrides it when supplied.
+    let requestBody = {};
 
     if (filterFile) {
       const filterPath = path.resolve(process.cwd(), filterFile);

package/src/utils/apiClient.js

@@ -73,15 +73,14 @@ async function request(method, endpoint, params = {}, data = null, retryCount =
 
     logInfo(`${method.toUpperCase()} request to ${url} (Retry: ${retryCount})`, 'apiClient.request');
 
-    const response = await apiClient({
-      method,
-      url,
-      params,
-      data,
-      headers: {
-        'Authorization': `Zoho-oauthtoken ${accessToken}`
-      }
-    });
+    const headers = { 'Authorization': `Zoho-oauthtoken ${accessToken}` };
+    // Zoho requires an explicit JSON content type on write requests — even when
+    // the body is empty — otherwise it responds 415 MEDIA_TYPE_NOT_SUPPORTED.
+    if (method && method.toLowerCase() !== 'get') {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const response = await apiClient({ method, url, params, data, headers });
 
     // Zoho API sometimes returns error statuses inside a 200 OK response, e.g. code: 'INVALID_TOKEN'
     if (response.data && response.data.status === 'error') {

package/src/utils/errorReporter.js

@@ -0,0 +1,81 @@
+const { logError, shortErrorMessage } = require('./logger');
+
+const SUPPORT_EMAIL = 'support@wanasapps.com';
+const SUPPORT_SITE = 'https://www.wanasapps.com';
+const ISSUES_URL = 'https://github.com/Wanas-Apps/Module-fields-metadata-extractor/issues';
+
+const C = {
+  reset: '\x1b[0m',
+  red: '\x1b[1;31m',
+  redPlain: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  blue: '\x1b[34m',
+  dim: '\x1b[90m',
+  bold: '\x1b[1m'
+};
+const BAR = `${C.red}====================================================================${C.reset}`;
+
+/**
+ * A known, expected CLI failure (bad input, not authenticated, missing file…).
+ * These are shown cleanly with an optional actionable hint — and intentionally
+ * WITHOUT the "report a bug / contact support" footer, which is reserved for
+ * genuinely unexpected errors.
+ */
+class CliError extends Error {
+  /**
+   * @param {string} message - User-facing message.
+   * @param {string} [hint] - Optional next-step hint.
+   */
+  constructor(message, hint) {
+    super(message);
+    this.name = 'CliError';
+    this.isCliError = true;
+    this.hint = hint;
+  }
+}
+
+const write = (s) => { try { process.stderr.write(s); } catch (e) { /* ignore */ } };
+
+/**
+ * Renders a single, unified error response for the CLI and records full details
+ * to the log files. Expected errors (CliError) are concise + actionable;
+ * everything else is treated as unexpected and gets a clear "contact support"
+ * block so the user always knows how to get help.
+ *
+ * @param {Error|object|string} error
+ * @param {object} [opts]
+ * @param {string} [opts.context] - Where the error came from (for the log).
+ * @param {string|null} [opts.debugLogPath] - Per-run debug log to reference.
+ */
+function reportError(error, opts = {}) {
+  const { context = 'cli', debugLogPath = null } = opts;
+
+  // Always capture the full error (incl. API response bodies) to the log files.
+  try { logError(error, context); } catch (e) { /* never let logging break reporting */ }
+
+  if (error && error.isCliError) {
+    write(`\n${C.red}❌ ${error.message}${C.reset}\n`);
+    if (error.hint) write(`${C.yellow}   ${error.hint}${C.reset}\n`);
+    if (debugLogPath) write(`${C.dim}   Debug log: ${debugLogPath}${C.reset}\n`);
+    return;
+  }
+
+  // Unexpected error → unified block + how to get help.
+  const message = shortErrorMessage(error);
+  write(`\n${BAR}\n`);
+  write(` ${C.red}❌ Unexpected Error${C.reset}\n`);
+  write(`${BAR}\n`);
+  write(` ${C.redPlain}${message}${C.reset}\n\n`);
+  write(` ${C.bold}This shouldn't have happened — sorry about that.${C.reset}\n`);
+  write(` Please report it and we'll get it fixed:\n`);
+  write(`   ✉  ${C.cyan}${SUPPORT_EMAIL}${C.reset}\n`);
+  write(`   🌐 ${C.cyan}${SUPPORT_SITE}${C.reset}\n`);
+  write(`   🐛 ${C.cyan}${ISSUES_URL}${C.reset}\n`);
+  if (debugLogPath) {
+    write(`   📄 ${C.bold}Attach this debug log:${C.reset} ${C.blue}${debugLogPath}${C.reset}\n`);
+  }
+  write(`${BAR}\n`);
+}
+
+module.exports = { CliError, reportError, SUPPORT_EMAIL, SUPPORT_SITE, ISSUES_URL };