wanas-zcrm-extractor 1.7.2 → 1.8.1

package/README.md

@@ -28,7 +28,7 @@
 </p>
 
 <p align="center">
-  <code>zcrm login</code> &nbsp;·&nbsp; <code>zcrm pull</code> &nbsp;·&nbsp; <code>zcrm skill</code> &nbsp;·&nbsp; <code>zcrm audit</code> &nbsp;·&nbsp; <code>zcrm dashboard</code>
+  <code>zcrm login</code> &nbsp;·&nbsp; <code>zcrm pull</code> &nbsp;·&nbsp; <code>zcrm skill</code> &nbsp;·&nbsp; <code>zcrm audit</code> &nbsp;·&nbsp; <code>zcrm fn test</code> &nbsp;·&nbsp; <code>zcrm dashboard</code>
 </p>
 
 <!-- Read-only callout. Rendered as a bordered box (a single-cell table) so it
@@ -139,6 +139,27 @@ npx zcrm pull
 
 > *On Windows you may need an **Administrator** terminal; on macOS/Linux you may need `sudo` for a global install.*
 
+<details>
+<summary><strong>Alternative: install from GitHub Packages (<code>@wanas-apps</code> scope)</strong></summary>
+
+<br>
+
+The same release is also published to **GitHub Packages** as the scoped package **`@wanas-apps/wanas-zcrm-extractor`**. GitHub Packages requires authentication even for public packages, so point the `@wanas-apps` scope at GitHub and authenticate with a GitHub token that has the **`read:packages`** scope:
+
+```bash
+# ~/.npmrc  (or a project-local .npmrc)
+@wanas-apps:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+```bash
+npm install -g @wanas-apps/wanas-zcrm-extractor
+```
+
+> Most users should prefer the public npmjs package above — it needs no token. GitHub Packages is provided for org-internal/CI consumers.
+
+</details>
+
 ---
 
 ## 🔑 Setup & Registration
@@ -163,6 +184,8 @@ To authenticate, register a Zoho API client in the Zoho Developer Console:
 | [`zcrm pull`](#2-zcrm-pull) | Extract & sync all CRM metadata into a local folder. |
 | [`zcrm skill`](#6-zcrm-skill) | Generate an AI-assistant context file for your IDE. |
 | [`zcrm audit`](#7-zcrm-audit) | Export the CRM audit log (async job). |
+| [`zcrm fn create`](#9-zcrm-fn--single-function-lifecycle-create--push--pull--test) · [`push`](#9-zcrm-fn--single-function-lifecycle-create--push--pull--test) | ⚠️ Create a Standalone function / push its code on the live CRM (**writes**). |
+| [`zcrm fn test`](#9-zcrm-fn--single-function-lifecycle-create--push--pull--test) · [`pull`](#9-zcrm-fn--single-function-lifecycle-create--push--pull--test) | ⚠️ Execute a function (**not** read-only) · fetch one function's `.ds` (read-only). |
 | [`zcrm dashboard`](#3-zcrm-dashboard) | Launch the local web explorer dashboard. |
 | [`zcrm whoami`](#4-zcrm-whoami) · [`zcrm llm`](#5-zcrm-llm) · [`zcrm logout`](#8-zcrm-logout) | Session info · AI guide · Sign out. |
 
@@ -345,6 +368,81 @@ zcrm logout
 ```
 </details>
 
+<br>
+
+<details>
+<summary><h3>9. <code>zcrm fn</code> — single-function lifecycle (create · push · pull · test)</h3></summary>
+
+Work with **one** Deluge function at a time — the full loop: **create** a Standalone function, **push** code edits, **pull** the latest, and **test**-run it.
+
+> ⚠️ `fn create`, `fn push`, and `fn test` **write to / execute on** your live Zoho CRM org and are **outside** the read-only guarantee. Each is confirm-gated (use `--force` to skip in CI). `fn pull` is read-only.
+
+<h4><code>zcrm fn create &lt;apiName&gt;</code> — create a Standalone function (writes)</h4>
+
+Creates a new Standalone function on CRM and writes its `.ds` into your metadata tree. With `--from`, it also pushes that file's code; without it, you get an empty stub to edit and `fn push` later.
+
+> **Names are lowercased.** Zoho lowercases generated function code signatures, so `zcrm` normalizes api_names to lowercase end-to-end (`My_Fn` → `my_fn`, file `standalone.my_fn.ds`) to keep the function, its code, and the filename consistent. Lookups (`push`/`test`/`pull`) are case-insensitive.
+
+```bash
+zcrm fn create My_Fn                                   # empty stub + local .ds
+zcrm fn create My_Fn --from ./My_Fn.ds                 # create + push code in one step
+zcrm fn create My_Fn --return-type string              # stub with a chosen return type
+```
+
+| Option | Description |
+| :--- | :--- |
+| `--from <file.ds>` | Seed the function with code from a local `.ds` (its signature name must match `<apiName>`). |
+| `--return-type <t>` | Return type for an empty stub (default `void`; ignored with `--from`). |
+| `-o, --output <dir>` | Metadata root for the written `.ds` (default `./metadata`). |
+| `--force` | Skip the write-confirmation prompt. |
+
+<h4><code>zcrm fn push &lt;file.ds&gt;</code> — save local code to CRM (writes)</h4>
+
+Reads a local `.ds`, resolves the function from its signature, and uploads the code to the matching **existing** function. Create it first with `fn create` if it doesn't exist yet.
+
+```bash
+zcrm fn push ./metadata/crm/functions/standalone/standalone.My_Fn.ds
+```
+
+<h4>⚠️ <code>zcrm fn test &lt;function&gt;</code> — run it on the live CRM (NOT read-only)</h4>
+
+Unlike every other command, `fn test` **executes** Deluge in your **live** Zoho CRM org (the function editor's "test" action). It can **create/update/delete records, send mail/SMS, and call external APIs** — exactly what the script does. It is therefore an **explicit, opt-in** command, gated behind a confirmation prompt (use `--force` to skip it in CI).
+
+`<function>` is either a **local `.ds` file** (runs *your local edits*) or the **api_name** of a Standalone function (fetches & runs the saved code). Only **Standalone** functions can be tested.
+
+```bash
+# Test local edits to a function before saving them in CRM:
+zcrm fn test ./metadata/crm/functions/standalone/standalone.My_Fn.ds
+
+# Run a live function with arguments:
+zcrm fn test My_Fn --args '{"Data":"hello"}'
+
+# No prompt + raw JSON (automation):
+zcrm fn test My_Fn --force --json
+```
+
+| Option | Description |
+| :--- | :--- |
+| `--args <json>` | Inline JSON argument map, e.g. `'{"Data":"hi"}'`. |
+| `--args-file <path>` | JSON file containing the argument map. |
+| `-o, --output <dir>` | Where to save the result artifact — `<dir>/crm/function_tests/` (default `./metadata`). |
+| `--json` | Print Zoho's raw JSON response to stdout. |
+| `--force` | Skip the execution warning + confirmation prompt (CI/automation). |
+
+It prints the **return value**, `info` **logs**, every **network/integration call** (with its HTTP status), and execution **metrics**, and saves the full response to `<output>/crm/function_tests/<api_name>-<timestamp>.json`. The exit code is non-zero if the run failed.
+
+<h4><code>zcrm fn pull &lt;api_name&gt;</code> — fetch one function (read-only)</h4>
+
+Fetches a single function's Deluge code into `<output>/crm/functions/<namespace>/<namespace>.<api_name>.ds` — the **same path** `zcrm pull` uses — without running a full pull. Strictly read-only; never deletes anything.
+
+```bash
+zcrm fn pull My_Fn
+zcrm fn pull My_Fn -o ./metadata
+```
+
+> **Typical loop:** `zcrm fn create My_Fn` → edit the `.ds` → `zcrm fn push <file>` → `zcrm fn test My_Fn`. Only **Standalone** functions are supported (the namespace these endpoints resolve).
+</details>
+
 ---
 
 ## 📂 Generated Directory Structure

package/bin/cli.js

@@ -14,7 +14,9 @@ const configStore = require('../src/utils/configStore');
 const authService = require('../src/services/authService');
 const crmMetadataService = require('../src/services/metadata/crmMetadataService');
 const auditLogService = require('../src/services/auditLogService');
+const functionService = require('../src/services/functionService');
 const skillGenerator = require('../src/utils/skillGenerator');
+const { formatValue } = require('../src/utils/prettyJson');
 const { addSessionLog, logInfo, shortErrorMessage } = require('../src/utils/logger');
 
 // ---------------------------------------------------------------------------
@@ -25,7 +27,7 @@ const { addSessionLog, logInfo, shortErrorMessage } = require('../src/utils/logg
 // and full API error bodies that are not printed to the console. The path is
 // shown if the command fails. (Command args are intentionally NOT logged, to
 // avoid writing secrets like --client-secret / --refresh-token to disk.)
-const LOGGED_COMMANDS = ['login', 'logout', 'whoami', 'status', 'pull', 'audit', 'llm', 'skill'];
+const LOGGED_COMMANDS = ['login', 'logout', 'whoami', 'status', 'pull', 'audit', 'llm', 'skill', 'fn'];
 let debugLogPath = null;
 (function setupDebugLog() {
   try {
@@ -807,5 +809,364 @@ program
     require('../server.js');
   });
 
+// ---------------------------------------------------------------------------
+// fn — single-function operations (test / pull)
+// ---------------------------------------------------------------------------
+
+/**
+ * Colorizes an HTTP status code: green for 2xx, red otherwise.
+ * @param {number} code
+ * @returns {string}
+ */
+function colorStatus(code) {
+  const ok = code >= 200 && code < 300;
+  return `${ok ? '\x1b[32m' : '\x1b[1;31m'}${code}\x1b[0m`;
+}
+
+// Maps functionService error codes to a short, actionable hint so routine,
+// user-facing failures render as clean CliErrors (concise hint, no "report a
+// bug / contact support" footer). Anything without a known code falls through
+// to the generic unexpected-error handler.
+const FN_ERROR_HINTS = {
+  DS_NOT_FOUND: 'Check the path to your .ds file.',
+  NO_API_NAME: 'Ensure the .ds starts with a signature like `string standalone.My_Fn()`.',
+  FN_NOT_FOUND: 'Check the api_name (case-sensitive), or create it first with `zcrm fn create`.',
+  NAME_INVALID: 'Create the function first with `zcrm fn create`, then test it.',
+  NOT_STANDALONE: 'The CRM test/authoring actions resolve names in the standalone namespace only.',
+  NAME_MISMATCH: 'Rename the function or the .ds so the signature name matches.',
+  EMPTY_CODE: 'The function exists but Zoho returned no code for it.',
+  CREATE_FAILED: 'The name may already exist, or a field was rejected. Try a different name.',
+  PUSH_FAILED: 'Open the .ds in the Zoho editor to check it compiles.',
+};
+
+/**
+ * Funnels an `fn`-command error: known functionService codes become clean
+ * CliErrors; anything else (e.g. a raw API error) goes through fail()'s generic
+ * unexpected-error path.
+ * @param {Error} err
+ */
+function failFn(err) {
+  if (err && err.code && FN_ERROR_HINTS[err.code] && !err.isCliError) {
+    fail(new CliError(err.message, FN_ERROR_HINTS[err.code]), 'fn');
+  }
+  fail(err, 'fn');
+}
+
+/**
+ * Parse a JSON argument map from a string, enforcing that it is a plain object.
+ * Exits with a clean CliError on parse failure or a non-object value.
+ * @param {string} raw
+ * @param {string} sourceLabel - e.g. '--args' or '--args-file'
+ * @returns {object}
+ */
+function parseArgMap(raw, sourceLabel) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    fail(new CliError(`Invalid ${sourceLabel} JSON: ${e.message}`, 'Pass a JSON object, e.g. \'{"Data":"hi"}\''), 'fn');
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    fail(new CliError(`${sourceLabel} must be a JSON object map, e.g. {"Data":"hi"}.`), 'fn');
+  }
+  return parsed;
+}
+
+/**
+ * Coerce an interactively-entered (always-string) argument to its declared
+ * Deluge type, so a function expecting `int`/`bool` receives a number/boolean.
+ * @param {string} value
+ * @param {string} type
+ */
+function coerceArg(value, type) {
+  const t = (type || '').toLowerCase();
+  if (/^(int|integer|long|bigint)$/.test(t)) { const n = parseInt(value, 10); return Number.isNaN(n) ? value : n; }
+  if (/^(double|float|decimal|number|percent|currency)$/.test(t)) { const n = Number(value); return Number.isNaN(n) ? value : n; }
+  if (/^(bool|boolean)$/.test(t)) return /^(true|yes|y|1)$/i.test(String(value).trim());
+  return value;
+}
+
+/**
+ * Confirmation prompt that treats a non-TTY / EOF (e.g. CI without --force) as a
+ * decline rather than crashing — so a skipped confirmation cancels cleanly.
+ * @param {string} message
+ * @returns {Promise<boolean>}
+ */
+async function confirmOrCancel(message) {
+  try {
+    const { proceed } = await inquirer.prompt([{ type: 'confirm', name: 'proceed', message, default: false }]);
+    return proceed;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Indents a (possibly multi-line) string by `n` spaces on every line.
+function indentLines(text, n) {
+  const pad = ' '.repeat(n);
+  return String(text).split('\n').map((l) => pad + l).join('\n');
+}
+
+/**
+ * Renders a single value beneath a label. JSON values (objects, or strings that
+ * parse to JSON) are pretty-printed + syntax-colored on their own indented
+ * lines; plain scalars render inline after the label.
+ */
+function printValue(label, value) {
+  const { isJson, text } = formatValue(value, 0);
+  if (isJson) {
+    console.log(`  \x1b[1m${label}\x1b[0m`);
+    console.log(indentLines(text, 4));
+  } else {
+    console.log(`  \x1b[1m${label}\x1b[0m ${text}`);
+  }
+}
+
+/**
+ * Renders a `fn test` result (status, return value, info logs, network/
+ * integration calls, metrics, saved artifact path) to the console. JSON in the
+ * return value or `info` logs is parsed and pretty-printed for readability.
+ * @param {object} result - The structured result from functionService.executeTest.
+ */
+function renderTestResult(result) {
+  const { resolved, fnResult, savedPath, success } = result;
+  const bar = '\x1b[90m──────────────────────────────────────────────────────────────\x1b[0m';
+  const badge = success ? '\x1b[1;42;30m SUCCESS \x1b[0m' : '\x1b[1;41;37m FAILED \x1b[0m';
+  const m = fnResult.metrics || {};
+
+  console.log('');
+  console.log(`${badge}  \x1b[1m🧪 standalone.${resolved.apiName}\x1b[0m`);
+  console.log(bar);
+
+  // Return value (unwrap Zoho's {value,...} envelope; pretty-print JSON).
+  let out = fnResult.output;
+  if (out && typeof out === 'object' && 'value' in out) out = out.value;
+  if (out === null || out === undefined || out === '') {
+    console.log('  \x1b[1mReturn\x1b[0m \x1b[90m(empty)\x1b[0m');
+  } else {
+    printValue('Return', out);
+  }
+
+  // info logs (with line numbers; JSON values pretty-printed)
+  const logs = fnResult.logs || [];
+  if (logs.length) {
+    console.log(`\n  \x1b[1mLogs\x1b[0m \x1b[90m(${logs.length})\x1b[0m`);
+    for (const l of logs) {
+      const cat = l.category && l.category !== 'info' ? `\x1b[33m${l.category}\x1b[0m ` : '';
+      const loc = l.line_number != null ? `\x1b[90mL${l.line_number}\x1b[0m ` : '';
+      const { isJson, text } = formatValue(l.value, 0);
+      if (isJson) {
+        console.log(`   ${loc}${cat}`);
+        console.log(indentLines(text, 6));
+      } else {
+        console.log(`   ${loc}${cat}${text}`);
+      }
+    }
+  }
+
+  // network / integration calls
+  const net = fnResult.network_logs || [];
+  if (net.length) {
+    console.log(`\n  \x1b[1mNetwork / integration calls\x1b[0m \x1b[90m(${net.length})\x1b[0m`);
+    for (const n of net) {
+      // invoke_url rows carry http_method; integration_task rows don't — label them TASK.
+      const method = (n.http_method || (n.details && n.details.task ? 'TASK' : '—')).toUpperCase().padEnd(5);
+      const where = (n.details && (n.details.url || n.details.task)) || n.function_name || '';
+      console.log(`   \x1b[90m${method}\x1b[0m ${colorStatus(n.status_code)}  ${where}  \x1b[90m${n.time_taken_in_ms}ms\x1b[0m`);
+    }
+  }
+
+  console.log(bar);
+  console.log(`  \x1b[90m${m.statements_executed || 0} statements · ${m.integration_task || 0} integration · ${m.send_mail || 0} mail · ${m.send_sms || 0} sms · ${m.time_taken_in_ms || 0}ms\x1b[0m`);
+  if (savedPath) console.log(`  \x1b[90mSaved → ${savedPath}\x1b[0m`);
+  console.log('');
+}
+
+const fnCmd = program
+  .command('fn')
+  .description('Work with a single Deluge function (create / push / pull / test)');
+
+// fn test — EXECUTES code; outside the read-only guarantee.
+fnCmd
+  .command('test <function>')
+  .description('Execute a Standalone Deluge function on the live CRM (EXECUTES code — NOT read-only)')
+  .option('--args <json>', 'Inline JSON map of arguments, e.g. --args \'{"Data":"hi"}\'')
+  .option('--args-file <path>', 'Path to a JSON file containing the arguments map')
+  .option('-o, --output <dir>', 'Result folder to save the test artifact into (its crm/function_tests/ subfolder)', './metadata')
+  .option('--json', 'Print the raw Zoho JSON response to stdout (artifact still saved)')
+  .option('--force', 'Skip the execution warning + confirmation prompt (for automation/CI)')
+  .action(async (functionArg, options) => {
+    console.log(getBanner());
+    authService.loadTokens();
+    if (!authService.isAuthenticated()) {
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'fn');
+    }
+
+    try {
+      // 1. Resolve the script + identity (local .ds or live api_name), then the
+      //    standalone-only guard (single source of truth; mapped to a clean
+      //    CliError by failFn). Both run before any execution.
+      logInfo(`fn test target: ${functionArg}`, 'cli');
+      const resolved = await functionService.resolveTarget(functionArg);
+      functionService.assertStandalone(resolved);
+
+      // 2. Resolve arguments: --args / --args-file / interactive prompt / none.
+      let args = {};
+      if (options.args) {
+        args = parseArgMap(options.args, '--args');
+      } else if (options.argsFile) {
+        const fsx = require('fs');
+        const p = path.resolve(options.argsFile);
+        if (!fsx.existsSync(p)) fail(new CliError(`--args-file not found: ${p}`), 'fn');
+        args = parseArgMap(fsx.readFileSync(p, 'utf8'), '--args-file');
+      } else if (resolved.args.length && process.stdin.isTTY && !options.force) {
+        try {
+          const answers = await inquirer.prompt(resolved.args.map((a) => ({
+            type: 'input',
+            name: a.name,
+            message: `${a.name} \x1b[90m(${a.type})\x1b[0m:`,
+          })));
+          // Coerce each answer to its declared type (prompts return strings).
+          args = {};
+          for (const a of resolved.args) args[a.name] = coerceArg(answers[a.name], a.type);
+        } catch (e) {
+          console.log('\n\x1b[33mℹ Cancelled.\x1b[0m\n');
+          process.exit(0);
+        }
+      }
+
+      // 3. Confirmation gate — fn test EXECUTES code in the live org.
+      if (!options.force) {
+        console.log('\x1b[1;33m⚠  fn test EXECUTES this Deluge in your LIVE Zoho CRM org.\x1b[0m It is \x1b[1mNOT\x1b[0m a dry run —');
+        console.log('   it can create/update/delete records, send mail/SMS, and call external APIs.');
+        console.log(`   Function: \x1b[36mstandalone.${resolved.apiName}\x1b[0m`);
+        if (!(await confirmOrCancel('Proceed?'))) {
+          console.log('\n\x1b[33mℹ Cancelled. Nothing was executed.\x1b[0m\n');
+          process.exit(0);
+        }
+      }
+
+      // 4. Execute, render, and exit with the run's success status.
+      const result = await functionService.executeTest({ resolved, args, outputDir: options.output });
+
+      if (options.json) {
+        console.log(JSON.stringify(result.response, null, 2));
+        if (result.savedPath) console.log(`\x1b[90mSaved: ${result.savedPath}\x1b[0m`);
+      } else {
+        renderTestResult(result);
+      }
+      process.exit(result.success ? 0 : 1);
+    } catch (err) {
+      failFn(err);
+    }
+  });
+
+// fn pull — read-only single-function code fetch.
+fnCmd
+  .command('pull <apiName>')
+  .description('Fetch one function\'s Deluge code into its .ds file (read-only)')
+  .option('-o, --output <dir>', 'Metadata root to write the .ds into', './metadata')
+  .action(async (apiNameArg, options) => {
+    console.log(getBanner());
+    authService.loadTokens();
+    if (!authService.isAuthenticated()) {
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'fn');
+    }
+
+    try {
+      logInfo(`fn pull api_name: ${apiNameArg}`, 'cli');
+      const res = await functionService.pullOne({ apiName: apiNameArg, outputDir: options.output });
+      console.log('\n\x1b[1;32m====================================================================\x1b[0m');
+      console.log('📥 \x1b[1;32mFunction Deluge script pulled successfully!\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m');
+      console.log(` \x1b[1mFunction:\x1b[0m  \x1b[36m${res.apiName}\x1b[0m`);
+      console.log(` \x1b[1mCategory:\x1b[0m  \x1b[35m${res.category || 'N/A'}\x1b[0m`);
+      console.log(` \x1b[1mSaved To:\x1b[0m  \x1b[34m${res.filePath}\x1b[0m`);
+      console.log('\x1b[1;32m====================================================================\x1b[0m\n');
+      process.exit(0);
+    } catch (err) {
+      failFn(err);
+    }
+  });
+
+// fn create — creates a Standalone function on CRM (writes) + writes the .ds locally.
+fnCmd
+  .command('create <apiName>')
+  .description('Create a Standalone function on the live CRM and write its .ds locally (WRITES to CRM)')
+  .option('--from <file>', 'Seed the new function with code from a local .ds file')
+  .option('--return-type <type>', 'Return type for an empty stub (ignored when --from is used; default void)')
+  .option('-o, --output <dir>', 'Metadata root to write the .ds into', './metadata')
+  .option('--force', 'Skip the write confirmation prompt (for automation/CI)')
+  .action(async (apiNameArg, options) => {
+    console.log(getBanner());
+    authService.loadTokens();
+    if (!authService.isAuthenticated()) {
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'fn');
+    }
+    try {
+      if (!options.force) {
+        console.log('\x1b[1;33m⚠  fn create WRITES to your LIVE Zoho CRM org\x1b[0m — it creates a new Standalone function.');
+        console.log(`   Function: \x1b[36mstandalone.${apiNameArg}\x1b[0m${options.from ? `  \x1b[90m(seeded from ${options.from})\x1b[0m` : ''}`);
+        if (!(await confirmOrCancel('Proceed?'))) {
+          console.log('\n\x1b[33mℹ Cancelled. Nothing was created.\x1b[0m\n');
+          process.exit(0);
+        }
+      }
+      logInfo(`fn create: ${apiNameArg}${options.from ? ' from ' + options.from : ''}`, 'cli');
+      const res = await functionService.createFunction({
+        apiName: apiNameArg,
+        returnType: options.returnType,
+        fromFile: options.from,
+        outputDir: options.output,
+      });
+      console.log('\n\x1b[1;32m====================================================================\x1b[0m');
+      console.log('✨ \x1b[1;32mStandalone function created!\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m');
+      console.log(` \x1b[1mFunction:\x1b[0m  \x1b[36m${res.apiName}\x1b[0m  \x1b[90m(id ${res.id})\x1b[0m`);
+      console.log(` \x1b[1mCode:\x1b[0m      ${res.pushed ? 'pushed from your --from file' : 'empty stub'}`);
+      console.log(` \x1b[1mSaved To:\x1b[0m  \x1b[34m${res.filePath}\x1b[0m`);
+      console.log('\n \x1b[90mNext: edit the .ds, `zcrm fn push` it, then `zcrm fn test` to run it.\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m\n');
+      process.exit(0);
+    } catch (err) {
+      failFn(err);
+    }
+  });
+
+// fn push — pushes a local .ds file's code to its matching live function (writes).
+fnCmd
+  .command('push <file>')
+  .description('Push (save) a local .ds file\'s code to its matching live function (WRITES to CRM)')
+  .option('--force', 'Skip the write confirmation prompt (for automation/CI)')
+  .action(async (fileArg, options) => {
+    console.log(getBanner());
+    authService.loadTokens();
+    if (!authService.isAuthenticated()) {
+      fail(new CliError('Not authenticated. Please log in first.', 'Run: zcrm login'), 'fn');
+    }
+    try {
+      if (!options.force) {
+        console.log('\x1b[1;33m⚠  fn push WRITES to your LIVE Zoho CRM org\x1b[0m — it overwrites the function\'s saved code.');
+        console.log(`   File: \x1b[36m${fileArg}\x1b[0m`);
+        if (!(await confirmOrCancel('Proceed?'))) {
+          console.log('\n\x1b[33mℹ Cancelled. Nothing was changed.\x1b[0m\n');
+          process.exit(0);
+        }
+      }
+      logInfo(`fn push: ${fileArg}`, 'cli');
+      const res = await functionService.pushCode({ file: fileArg });
+      console.log('\n\x1b[1;32m====================================================================\x1b[0m');
+      console.log('⬆️  \x1b[1;32mCode pushed successfully!\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m');
+      console.log(` \x1b[1mFunction:\x1b[0m  \x1b[36m${res.apiName}\x1b[0m  \x1b[90m(id ${res.id})\x1b[0m`);
+      console.log(` \x1b[1mFrom:\x1b[0m      \x1b[34m${res.filePath}\x1b[0m`);
+      console.log(' \x1b[90mTip: run `zcrm fn test` to execute it.\x1b[0m');
+      console.log('\x1b[1;32m====================================================================\x1b[0m\n');
+      process.exit(0);
+    } catch (err) {
+      failFn(err);
+    }
+  });
+
 // Run parser
 program.parse(process.argv);

package/llm.md

@@ -4,11 +4,16 @@ This guide is designed for **Large Language Models (LLMs) and AI agents** to ing
 
 > ⚠️ **Read-only schema metadata.** This folder describes only the *structure* of a Zoho CRM
 > org — modules, fields, layouts, picklists, related lists, and function source. It contains
-> **no CRM record data**. It is produced by the `zcrm` extractor CLI, which can **only read
-> metadata** and **cannot create, read, update, or delete** anything in Zoho CRM. Use it to look
-> up exact API names, data types, and constraints — never assume the tooling can run scripts
-> against the live CRM. Any Deluge/REST code you generate must be deployed and executed by a
-> human inside Zoho.
+> **no CRM record data**. The `zcrm` **extraction** (`pull`/`audit`/`fn pull`) is **read-only** —
+> it **cannot create, read, update, or delete** records. Use this metadata to look up exact API
+> names, data types, and constraints. Any record-level Deluge/REST code you generate must be
+> deployed and executed by a human inside Zoho.
+>
+> **Exception — the `zcrm fn` commands:** `fn create` (create a Standalone function),
+> `fn push` (upload code), and `fn test` (execute it) all **write to / run on** the live org
+> (they can create/update records, send mail, call APIs), so each is gated behind a confirmation
+> prompt and kept separate from the read-only guarantee. `fn pull` (fetch one function's code)
+> stays read-only. All `fn` commands operate on **Standalone** functions only.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wanas-zcrm-extractor",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "Local Zoho CRM V8 Metadata Extractor CLI and Web Dashboard Utility",
   "main": "server.js",
   "bin": {