@wanasapps/deluge-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wanas Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @wanasapps/deluge-core
+
+Deluge language tooling for **every** Zoho product — not just CRM.
+
+Deluge runs in Zoho CRM, Creator, Books, Inventory, Projects, Sprints, Qntrl, Catalyst and People. This package holds everything that is true about the *language*, so a CLI, a VS Code extension and a browser editor can share one implementation instead of copying it three times.
+
+**Hard rule:** no I/O, no HTTP, no editor APIs. Pure functions over source text plus portable data assets. Anything that talks to Zoho belongs in an API layer; anything that talks to an editor belongs in that editor's adapter.
+
+```bash
+npm install @wanasapps/deluge-core
+```
+
+## Formatting and source transforms
+
+```js
+const deluge = require('@wanasapps/deluge-core');
+
+deluge.format(source);                 // canonical indentation
+deluge.stripLeadingComments(source);   // see below — required before a push
+deluge.parseSignature(source);         // name, arguments, return type
+```
+
+### `stripLeadingComments` — the one that costs people an afternoon
+
+Zoho's raw function-code endpoints parse everything before the first `(` as the package declaration **without skipping comments**. A script that opens with a `// documentation header` is rejected with a bodyless, misleading 400 — while the same script pastes into the web editor fine. Only these endpoints choke.
+
+So the leading comment lines are **blanked, not deleted**: blank lines are tolerated, and keeping them means the line numbers in any `COMPILATION_ERROR` Zoho returns still match the developer's local file. Interior comments are untouched.
+
+Any tool pushing Deluge to any Zoho product needs this.
+
+## On-disk conventions
+
+```js
+deluge.namespaceForCategory('Related List');   // 'related_list'
+deluge.dsPath('sendInvoice', 'Standalone');    // 'standalone/sendInvoice.ds'
+deluge.apiNameFromDsPath('ns.sendInvoice.ds'); // 'sendInvoice'
+deluge.DELUGE_RUNTIME;                         // 'Deluge 1.0'
+```
+
+Zoho names categories in prose ("Related List"); on disk they become lowercase, underscored folders. Sharing this means every tool writes the same `functions/<namespace>/` layout.
+
+## Language assets
+
+The same JSON files VS Code consumes, exposed as data so Monaco, Shiki, a docs site or a web editor can load them without depending on an extension.
+
+```js
+deluge.language.grammar();        // TextMate grammar
+deluge.language.configuration();  // brackets, comments, auto-closing pairs
+deluge.language.snippets();       // VS Code snippet format
+deluge.language.EXTENSIONS;       // ['.ds', '.dg', '.deluge']
+deluge.language.assetPaths;       // absolute paths to the raw files
+```
+
+## Analysis
+
+Editor-agnostic: returns plain objects, so the same engine can back a `vscode.Diagnostic`, a CLI check, or a CI gate.
+
+```js
+deluge.analyze.lint(source);
+// [{ line, column, message, severity: 'error'|'warning'|'info', code }]
+
+deluge.analyze.isValid(source);   // false only on errors, warnings ignored
+```
+
+Checks balanced delimiters (ignoring braces inside strings and comments) and flags the leading-comment header described above.
+
+## License
+
+MIT © Wanas Apps FZ-LLC

package/assets/deluge.tmLanguage.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "Deluge",
+  "patterns": [
+    { "include": "#comments" },
+    { "include": "#system-variables" },
+    { "include": "#keywords" },
+    { "include": "#constants" },
+    { "include": "#numbers" },
+    { "include": "#strings" },
+    { "include": "#builtin-functions" },
+    { "include": "#operators" }
+  ],
+  "repository": {
+    "keywords": {
+      "patterns": [
+        {
+          "name": "keyword.control.deluge",
+          "match": "\\b(if|else if|else|for each|break|continue|return|try|catch|throws|in)\\b"
+        },
+        {
+          "name": "keyword.other.deluge",
+          "match": "\\b(info|sendmail|invokeurl|invokeUrl|invokeapi|invokeAPI|openUrl|postUrl|getUrl|insert|update|delete)\\b"
+        },
+        {
+          "name": "storage.type.deluge",
+          "match": "\\b(int|long|decimal|float|double|bigint|string|text|bool|boolean|list|map|key|collection|date|time|datetime|void|file|xml)\\b"
+        }
+      ]
+    },
+    "system-variables": {
+      "patterns": [
+        {
+          "name": "variable.language.deluge",
+          "match": "\\b(zoho\\.(currentdate|currenttime|loginuser(\\.name)?|loginuserid|adminuser|adminuserid|appname|appuri|environment|ipaddress|device\\.type))\\b"
+        }
+      ]
+    },
+    "constants": {
+      "patterns": [
+        {
+          "name": "constant.language.deluge",
+          "match": "\\b(true|false|null)\\b"
+        }
+      ]
+    },
+    "numbers": {
+      "patterns": [
+        {
+          "name": "constant.numeric.deluge",
+          "match": "\\b([0-9]+\\.[0-9]+|[0-9]+)\\b"
+        }
+      ]
+    },
+    "strings": {
+      "patterns": [
+        {
+          "name": "string.quoted.double.deluge",
+          "begin": "\"",
+          "end": "\"",
+          "patterns": [
+            {
+              "name": "constant.character.escape.deluge",
+              "match": "\\\\."
+            }
+          ]
+        },
+        {
+          "name": "string.quoted.single.deluge",
+          "begin": "'",
+          "end": "'",
+          "patterns": [
+            {
+              "name": "constant.character.escape.deluge",
+              "match": "\\\\."
+            }
+          ]
+        }
+      ]
+    },
+    "comments": {
+      "patterns": [
+        {
+          "name": "comment.line.double-slash.deluge",
+          "match": "//.*$"
+        },
+        {
+          "name": "comment.block.deluge",
+          "begin": "/\\*",
+          "end": "\\*/"
+        }
+      ]
+    },
+    "builtin-functions": {
+      "patterns": [
+        {
+          "name": "support.function.deluge",
+          "match": "\\b(zoho)(\\.[a-zA-Z0-9_]+)+\\b"
+        },
+        {
+          "match": "\\.([a-zA-Z_][a-zA-Z0-9_]*)\\s*(?=\\()",
+          "captures": {
+            "1": { "name": "support.function.member.deluge" }
+          }
+        },
+        {
+          "name": "entity.name.function.deluge",
+          "match": "\\b([a-zA-Z_][a-zA-Z0-9_]*)\\s*(?=\\()"
+        }
+      ]
+    },
+    "operators": {
+      "patterns": [
+        {
+          "name": "keyword.operator.deluge",
+          "match": "(\\+=|-=|\\*=|/=|%=|==|!=|<=|>=|&&|\\|\\||[=<>+\\-*/%!?:])"
+        }
+      ]
+    }
+  },
+  "scopeName": "source.deluge"
+}

package/assets/language-configuration.json

@@ -0,0 +1,29 @@
+{
+  "comments": {
+    "lineComment": "//",
+    "blockComment": [ "/*", "*/" ]
+  },
+  "brackets": [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"]
+  ],
+  "autoClosingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "\"", "close": "\"", "notIn": ["string"] },
+    { "open": "'", "close": "'", "notIn": ["string", "comment"] }
+  ],
+  "surroundingPairs": [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"],
+    ["\"", "\""],
+    ["'", "'"]
+  ],
+  "indentationRules": {
+    "increaseIndentPattern": "^.*\\{[^}\"']*$|^.*\\([^)\"']*$|^.*\\[[^\\]\"']*$",
+    "decreaseIndentPattern": "^\\s*(\\s*\\/[/*].*\\*\\/\\s*)*[})\\]]"
+  }
+}

package/assets/snippets.json

@@ -0,0 +1,167 @@
+{
+	"For Each Loop": {
+		"prefix": "foreach",
+		"body": [
+			"for each ${1:item} in ${2:list}",
+			"{",
+			"\t$0",
+			"}"
+		],
+		"description": "Iterate over each element of a list with a for each loop."
+	},
+	"If Block": {
+		"prefix": "if",
+		"body": [
+			"if (${1:condition})",
+			"{",
+			"\t$0",
+			"}"
+		],
+		"description": "If block."
+	},
+	"If Else Block": {
+		"prefix": "ifelse",
+		"body": [
+			"if (${1:condition})",
+			"{",
+			"\t$2",
+			"}",
+			"else",
+			"{",
+			"\t$0",
+			"}"
+		],
+		"description": "If / else block."
+	},
+	"Try Catch": {
+		"prefix": "trycatch",
+		"body": [
+			"try",
+			"{",
+			"\t$1",
+			"}",
+			"catch (${2:e})",
+			"{",
+			"\tinfo ${2:e};",
+			"\t$0",
+			"}"
+		],
+		"description": "Try / catch block with the exception logged via info."
+	},
+	"Invoke URL (GET)": {
+		"prefix": "invokeurlget",
+		"body": [
+			"${1:response} = invokeurl",
+			"[",
+			"\turl : \"${2:https://example.com/api}\"",
+			"\ttype : GET",
+			"\tconnection : \"${3:my_connection}\"",
+			"];",
+			"$0"
+		],
+		"description": "Make a GET request with invokeurl."
+	},
+	"Invoke URL (POST)": {
+		"prefix": "invokeurlpost",
+		"body": [
+			"${1:params} = Map();",
+			"${1:params}.put(\"${2:key}\", ${3:value});",
+			"${4:response} = invokeurl",
+			"[",
+			"\turl : \"${5:https://example.com/api}\"",
+			"\ttype : POST",
+			"\tparameters : ${1:params}",
+			"\tconnection : \"${6:my_connection}\"",
+			"];",
+			"$0"
+		],
+		"description": "Make a POST request with invokeurl, including parameters and a connection."
+	},
+	"Invoke API": {
+		"prefix": "invokeapi",
+		"body": [
+			"${1:response} = invokeapi",
+			"[",
+			"\tservice : ${2:ZohoCRM}",
+			"\tpath : \"${3:crm/v3/Leads}\"",
+			"\ttype : ${4:GET}",
+			"\tconnection : \"${5:my_connection}\"",
+			"];",
+			"$0"
+		],
+		"description": "Call a Zoho service with invokeapi using service and path."
+	},
+	"Send Mail": {
+		"prefix": "sendmail",
+		"body": [
+			"sendmail",
+			"[",
+			"\tfrom : zoho.adminuserid",
+			"\tto : \"${1:recipient@example.com}\"",
+			"\tsubject : \"${2:Subject}\"",
+			"\tmessage : \"${3:Message body}\"",
+			"];",
+			"$0"
+		],
+		"description": "Send an email with the sendmail task."
+	},
+	"Info": {
+		"prefix": "info",
+		"body": [
+			"info ${1:value};"
+		],
+		"description": "Print a value to the console with info."
+	},
+	"Get Record By Id": {
+		"prefix": "getrecord",
+		"body": [
+			"${3:record} = zoho.crm.getRecordById(\"${1:Module}\", ${2:recordId});",
+			"$0"
+		],
+		"description": "Fetch a single CRM record by its id."
+	},
+	"Search Records": {
+		"prefix": "searchrecords",
+		"body": [
+			"${3:records} = zoho.crm.searchRecords(\"${1:Module}\", \"${2:(Field:equals:value)}\");",
+			"$0"
+		],
+		"description": "Search CRM records using search criteria."
+	},
+	"Create Record": {
+		"prefix": "createrecord",
+		"body": [
+			"${2:dataMap} = Map();",
+			"${2:dataMap}.put(\"${3:Field}\", ${4:value});",
+			"${5:response} = zoho.crm.createRecord(\"${1:Module}\", ${2:dataMap});",
+			"$0"
+		],
+		"description": "Build a data map and create a CRM record."
+	},
+	"Update Record": {
+		"prefix": "updaterecord",
+		"body": [
+			"${4:response} = zoho.crm.updateRecord(\"${1:Module}\", ${2:recordId}, ${3:dataMap});",
+			"$0"
+		],
+		"description": "Update an existing CRM record by id."
+	},
+	"New Map": {
+		"prefix": "mapnew",
+		"body": [
+			"${1:myMap} = Map();",
+			"${1:myMap}.put(\"${2:key}\", ${3:value});",
+			"$0"
+		],
+		"description": "Create a Map and put a key/value pair."
+	},
+	"New List": {
+		"prefix": "listnew",
+		"body": [
+			"${1:myList} = List();",
+			"${1:myList}.add(${2:value});",
+			"$0"
+		],
+		"description": "Create a List and add an element."
+	}
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@wanasapps/deluge-core",
+  "version": "1.0.0",
+  "description": "Deluge language tooling for every Zoho product — formatter, source transforms, TextMate grammar, snippets and an editor-agnostic linter. No I/O, no HTTP, no editor dependency.",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.js",
+    "prepublishOnly": "node test/run.js"
+  },
+  "keywords": [
+    "deluge",
+    "zoho",
+    "zoho-crm",
+    "zoho-creator",
+    "formatter",
+    "linter",
+    "textmate",
+    "grammar",
+    "language"
+  ],
+  "author": "Wanas Apps FZ-LLC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Wanas-Apps/deluge-core.git"
+  }
+}

package/src/analyze/index.js

@@ -0,0 +1,93 @@
+/**
+ * Editor-agnostic analysis.
+ *
+ * Returns plain objects — `{ line, column, endLine, endColumn, message, severity, code }`
+ * — so a VS Code provider can map them to vscode.Diagnostic, a CLI can print
+ * them, and CI can fail a build on them. Nothing here imports an editor API.
+ */
+
+const SEVERITY = { ERROR: 'error', WARNING: 'warning', INFO: 'info' };
+
+/** Strip strings and comments so brace/paren counting is not fooled by literals. */
+function mask(source) {
+  let out = '';
+  let inS = null;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < source.length; i++) {
+    const c = source[i];
+    const n = source[i + 1];
+    if (inLine) { if (c === '\n') { inLine = false; out += c; } else out += ' '; continue; }
+    if (inBlock) { if (c === '*' && n === '/') { inBlock = false; out += '  '; i++; } else out += c === '\n' ? c : ' '; continue; }
+    if (inS) { out += c === '\n' ? c : ' '; if (c === inS && source[i - 1] !== '\\') inS = null; continue; }
+    if (c === '/' && n === '/') { inLine = true; out += '  '; i++; continue; }
+    if (c === '/' && n === '*') { inBlock = true; out += '  '; i++; continue; }
+    if (c === '"' || c === "'") { inS = c; out += ' '; continue; }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * Structural checks that do not need a full parser and are safe to run on any
+ * Deluge source: unbalanced delimiters, and the leading-comment header that
+ * Zoho's raw code endpoints reject.
+ *
+ * @param {string} source
+ * @returns {Array<{line:number,column:number,message:string,severity:string,code:string}>}
+ */
+function lint(source) {
+  const problems = [];
+  const text = String(source == null ? '' : source);
+  const masked = mask(text);
+  const lines = masked.split('\n');
+
+  const stack = [];
+  const PAIRS = { '{': '}', '(': ')', '[': ']' };
+  const CLOSERS = { '}': '{', ')': '(', ']': '[' };
+  lines.forEach((line, li) => {
+    for (let ci = 0; ci < line.length; ci++) {
+      const ch = line[ci];
+      if (PAIRS[ch]) stack.push({ ch, line: li + 1, column: ci + 1 });
+      else if (CLOSERS[ch]) {
+        const top = stack.pop();
+        if (!top) {
+          problems.push({ line: li + 1, column: ci + 1, message: `Unmatched "${ch}"`, severity: SEVERITY.ERROR, code: 'unmatched-close' });
+        } else if (top.ch !== CLOSERS[ch]) {
+          problems.push({ line: li + 1, column: ci + 1, message: `Expected "${PAIRS[top.ch]}" to close "${top.ch}" opened at line ${top.line}, found "${ch}"`, severity: SEVERITY.ERROR, code: 'mismatched-close' });
+        }
+      }
+    }
+  });
+  for (const open of stack) {
+    problems.push({ line: open.line, column: open.column, message: `Unclosed "${open.ch}"`, severity: SEVERITY.ERROR, code: 'unclosed' });
+  }
+
+  // The leading-header trap: harmless in the web editor, fatal on the raw code
+  // endpoints. A warning rather than an error, because pushing through a tool
+  // that calls stripLeadingComments is perfectly safe.
+  const raw = text.split('\n');
+  for (let i = 0; i < raw.length; i++) {
+    const t = raw[i].trim();
+    if (t === '') continue;
+    if (t.startsWith('//')) {
+      problems.push({
+        line: i + 1,
+        column: 1,
+        message: 'Leading comment header: Zoho\'s raw code endpoints read everything before the first "(" as the package name and reject this with a bodyless 400. Strip it on push (deluge-core does this for you).',
+        severity: SEVERITY.WARNING,
+        code: 'leading-comment-header'
+      });
+    }
+    break;
+  }
+
+  return problems;
+}
+
+/** True when lint found nothing of `error` severity. */
+function isValid(source) {
+  return !lint(source).some((p) => p.severity === SEVERITY.ERROR);
+}
+
+module.exports = { lint, isValid, SEVERITY, _internal: { mask } };

package/src/format/formatter.js

@@ -0,0 +1,45 @@
+/**
+ * Basic formatter for Zoho Deluge scripts.
+ * Adjusts indentation based on block scopes '{' and '}'.
+ * Note: This is a simple line-based formatter and does not fully parse the AST.
+ */
+function formatDeluge(code) {
+  if (!code || typeof code !== 'string') return code;
+
+  let formatted = '';
+  let indentLevel = 0;
+  const indentString = '    '; // 4 spaces
+
+  // Replace standard block formatting to ensure newlines before/after braces if it's on one line
+  // (We skip deep parsing, assuming the code from Zoho generally has basic newlines)
+  const lines = code.split('\n');
+
+  for (let line of lines) {
+    line = line.trim();
+    
+    // Preserve empty lines
+    if (!line) {
+      formatted += '\n';
+      continue;
+    }
+
+    // Determine if this line closes a block
+    if (line.startsWith('}') || line.startsWith(']')) {
+      indentLevel = Math.max(0, indentLevel - 1);
+    }
+
+    // Apply indentation
+    formatted += indentString.repeat(indentLevel) + line + '\n';
+
+    // Determine if this line opens a new block
+    if (line.endsWith('{') || line.endsWith('[')) {
+      indentLevel++;
+    }
+  }
+
+  return formatted.trim() + '\n';
+}
+
+module.exports = {
+  formatDeluge
+};

package/src/format/signature.js

@@ -0,0 +1,70 @@
+/**
+ * Minimal parser for the *signature line* of a Deluge function script.
+ *
+ * Zoho stores a function's code with its signature on the first meaningful
+ * line, e.g.:
+ *
+ *   string standalone.Get_Assistants()
+ *   void   automation.k_test(String Data)
+ *
+ * We only need the signature to learn the function's namespace + api name (to
+ * build the test URL and enforce the standalone-only rule) and its declared
+ * arguments (to prompt for values). The full script is still submitted verbatim
+ * to Zoho — this parser never rewrites the code.
+ */
+
+/**
+ * Parse the signature of a Deluge script.
+ * @param {string} scriptText - The full Deluge source.
+ * @returns {{returnType: string|null, namespace: string|null, apiName: string|null, args: Array<{type:string,name:string}>}}
+ */
+function parseSignature(scriptText) {
+  const result = { returnType: null, namespace: null, apiName: null, args: [] };
+  if (!scriptText || typeof scriptText !== 'string') return result;
+
+  // Find the first non-comment, non-blank line — that's the signature.
+  let sigLine = null;
+  let inBlockComment = false;
+  for (const raw of scriptText.split('\n')) {
+    let line = raw.trim();
+    if (!line) continue;
+
+    if (inBlockComment) {
+      const end = line.indexOf('*/');
+      if (end === -1) continue;
+      line = line.slice(end + 2).trim();
+      inBlockComment = false;
+      if (!line) continue;
+    }
+    if (line.startsWith('//')) continue;
+    if (line.startsWith('/*')) {
+      const end = line.indexOf('*/');
+      if (end === -1) { inBlockComment = true; continue; }
+      line = line.slice(end + 2).trim();
+      if (!line) continue;
+    }
+    sigLine = line;
+    break;
+  }
+  if (!sigLine) return result;
+
+  // <returnType> <namespace>.<apiName>(<args>)
+  const m = sigLine.match(/^(\w+)\s+([A-Za-z0-9_]+)\.([A-Za-z0-9_]+)\s*\(([^)]*)\)/);
+  if (!m) return result;
+
+  result.returnType = m[1];
+  result.namespace = m[2];
+  result.apiName = m[3];
+
+  const argsRaw = m[4].trim();
+  if (argsRaw) {
+    for (const part of argsRaw.split(',')) {
+      // each param is "<type> <name>" (e.g. "String Data", "int count")
+      const am = part.trim().match(/^(\S+)\s+([A-Za-z0-9_]+)$/);
+      if (am) result.args.push({ type: am[1], name: am[2] });
+    }
+  }
+  return result;
+}
+
+module.exports = { parseSignature };

package/src/format/source.js

@@ -0,0 +1,63 @@
+/**
+ * Deluge source-text transforms that any tool pushing or storing a script needs,
+ * independent of which Zoho product the script belongs to.
+ */
+
+/**
+ * Blank out a leading `//` comment header before sending a script to Zoho.
+ *
+ * Zoho's raw code endpoints parse everything before the first `(` as the package
+ * name, without skipping comments — so a script that opens with a `//` header is
+ * rejected with a generic, bodyless 400 that says nothing about the real cause.
+ * The web editor tolerates the same header; only these endpoints choke.
+ *
+ * Blank lines ARE tolerated, so the leading comment lines are emptied rather than
+ * removed: line numbers in any COMPILATION_ERROR Zoho returns then still line up
+ * with the developer's local file. Interior comments are left alone.
+ *
+ * @param {string} script
+ * @returns {string}
+ */
+function stripLeadingComments(script) {
+  const lines = String(script).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t === '') continue;
+    if (!t.startsWith('//')) break;
+    lines[i] = lines[i].endsWith('\r') ? '\r' : '';
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Zoho names function categories in prose ("Related List"); on disk they become
+ * lowercase, underscored namespace folders. Keeping this here means every tool
+ * writes the same `functions/<namespace>/` layout.
+ *
+ * @param {string} category
+ * @returns {string}
+ */
+function namespaceForCategory(category) {
+  const cat = String(category || '').toLowerCase().trim();
+  const direct = ['standalone', 'automation', 'button', 'validation', 'schedule', 'blueprint'];
+  if (direct.includes(cat)) return cat;
+  if (cat === 'related list' || cat === 'related_list') return 'related_list';
+  return cat.replace(/\s+/g, '_') || 'standalone';
+}
+
+/** Conventional on-disk path for a function's source file. */
+function dsPath(apiName, category) {
+  if (!apiName) throw new Error('apiName is required');
+  return `${namespaceForCategory(category)}/${apiName}.ds`;
+}
+
+/** Recover the function's api name from a .ds path or filename. */
+function apiNameFromDsPath(file) {
+  const base = String(file).split(/[\\/]/).pop() || '';
+  return base.replace(/\.ds$/i, '').split('.').pop();
+}
+
+/** The runtime string Zoho requires when creating a function. */
+const DELUGE_RUNTIME = 'Deluge 1.0';
+
+module.exports = { stripLeadingComments, namespaceForCategory, dsPath, apiNameFromDsPath, DELUGE_RUNTIME };

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * @wanasapps/deluge-core — Deluge language tooling, independent of any Zoho product.
+ *
+ * Deluge is not a CRM feature: it runs in CRM, Creator, Books, Inventory,
+ * Projects, Sprints, Qntrl, Catalyst and People. This package holds everything
+ * that is true about the LANGUAGE, so a CLI, a VS Code extension and a browser
+ * editor can share one implementation.
+ *
+ * Hard rule for everything in here: NO I/O, NO HTTP, NO editor APIs. Pure
+ * functions over source text, plus portable data assets. Anything that talks to
+ * Zoho belongs in the API layer, and anything that talks to an editor belongs in
+ * that editor's adapter.
+ */
+
+const { formatDeluge } = require('./format/formatter');
+const { parseSignature } = require('./format/signature');
+const source = require('./format/source');
+const language = require('./language');
+const analyze = require('./analyze');
+
+module.exports = {
+  // formatting
+  format: formatDeluge,
+  formatDeluge,
+
+  // source transforms + on-disk conventions
+  parseSignature,
+  ...source,
+
+  // language data (builtins, catalog) and portable editor assets
+  language,
+
+  // editor-agnostic analysis engines
+  analyze
+};

package/src/language/index.js

@@ -0,0 +1,39 @@
+/**
+ * Portable language assets.
+ *
+ * The grammar, language configuration and snippets are the same JSON files VS
+ * Code consumes, exposed as data so Monaco, Shiki, a docs site or a web editor
+ * can load them without depending on an extension.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ASSETS = path.join(__dirname, '..', '..', 'assets');
+const read = (f) => JSON.parse(fs.readFileSync(path.join(ASSETS, f), 'utf8'));
+
+/** File extensions Zoho and our tooling use for Deluge source. */
+const EXTENSIONS = ['.ds', '.dg', '.deluge'];
+
+/** TextMate grammar — VS Code, Monaco (via monaco-textmate), Shiki. */
+function grammar() {
+  return read('deluge.tmLanguage.json');
+}
+
+/** Brackets, comment tokens, auto-closing pairs. */
+function configuration() {
+  return read('language-configuration.json');
+}
+
+/** Snippet definitions in the standard VS Code snippet shape. */
+function snippets() {
+  return read('snippets.json');
+}
+
+/** Absolute paths, for tools that must point a consumer at the raw files. */
+const assetPaths = {
+  grammar: path.join(ASSETS, 'deluge.tmLanguage.json'),
+  configuration: path.join(ASSETS, 'language-configuration.json'),
+  snippets: path.join(ASSETS, 'snippets.json')
+};
+
+module.exports = { EXTENSIONS, grammar, configuration, snippets, assetPaths };