@wanasapps/deluge-core 1.0.0 → 1.3.0

package/package.json

@@ -1,17 +1,20 @@
 {
   "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.",
+  "version": "1.3.0",
+  "description": "Deluge language tooling for every Zoho product: formatter, source transforms, TextMate grammar, snippets, an editor-agnostic linter, and AI-agent skills — a guide with runtime traps verified on a live org, plus a complete reference of every statement, data type, built-in function and integration task generated from Zoho's Deluge documentation. No I/O, no HTTP, no editor dependency.",
   "main": "src/index.js",
   "files": [
     "src",
     "assets",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node test/run.js",
-    "prepublishOnly": "node test/run.js"
+    "prepublishOnly": "node scripts/gen-skill.js && node test/run.js",
+    "gen:skill": "node scripts/gen-skill.js",
+    "scrape:docs": "node scripts/scrape-deluge-docs.js"
   },
   "keywords": [
     "deluge",
@@ -22,7 +25,11 @@
     "linter",
     "textmate",
     "grammar",
-    "language"
+    "language",
+    "skill",
+    "ai-agent",
+    "claude-code",
+    "cursor"
   ],
   "author": "Wanas Apps FZ-LLC",
   "license": "MIT",

package/scripts/check-cores-published.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Refuse to publish before the @wanasapps packages this one depends on.
+ *
+ * These five packages are independent repos, not a workspace. Publishing a
+ * consumer before its cores yields a package npm cannot install — it has
+ * happened before (zone 0.4.3). CI runs this before `npm ci`, so the failure
+ * names the missing package instead of surfacing as a bare ETARGET.
+ */
+'use strict';
+const cp = require('child_process');
+const pj = require('../package.json');
+
+const deps = { ...(pj.dependencies || {}), ...(pj.peerDependencies || {}) };
+const wanas = Object.entries(deps).filter(([n]) => n.startsWith('@wanasapps'));
+
+if (!wanas.length) {
+  console.log('no @wanasapps dependencies — nothing to check');
+  process.exit(0);
+}
+
+// A lockfile that records a local link resolves on the dev machine and
+// nowhere else: `npm ci` creates the link, exits 0, and the module is
+// missing at runtime. Caught zoho-api 1.1.1 in CI.
+try {
+  const lock = require('../package-lock.json');
+  const linked = Object.entries(lock.packages || {})
+    .filter(([, v]) => v && v.link)
+    .map(([k]) => k.replace('node_modules/', ''));
+  if (linked.length) {
+    console.error(`  LINKED   ${linked.join(', ')} recorded as a local link in package-lock.json`);
+    console.error('           Regenerate it against the registry: npm install --package-lock-only');
+    process.exit(1);
+  }
+} catch { /* no lockfile is fine */ }
+
+let missing = 0;
+for (const [name, range] of wanas) {
+  let found = '';
+  try {
+    // --json so a range matching several versions returns an array, rather
+    // than npm's "<name>@<ver> '<ver>'" lines, which are awkward to parse.
+    const raw = cp.execSync(`npm view ${name}@"${range}" version --json`, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    const parsed = raw ? JSON.parse(raw) : null;
+    found = Array.isArray(parsed) ? parsed[parsed.length - 1] : (parsed || '');
+  } catch { /* not published, or the range matches nothing */ }
+
+  if (found) {
+    console.log(`  ok       ${name}@${range} -> ${found}`);
+  } else {
+    console.error(`  MISSING  ${name}@${range} does not resolve on npm`);
+    missing++;
+  }
+}
+
+if (missing) {
+  console.error('\nPublish bottom-up:');
+  console.error('  deluge-core -> zoho-auth -> zoho-api -> zcrm-core -> wanas-zone-cli');
+  process.exit(1);
+}
+console.log('all @wanasapps dependencies resolve on npm');

package/scripts/gen-skill.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Render the two agent-facing Deluge documents from two sources:
+ *
+ *   assets/DELUGE_GUIDE.md        hand-written: how to think, contracts, verified traps
+ *   assets/deluge-reference.json  generated from Zoho's Deluge help (scripts/scrape-deluge-docs.js):
+ *                                 every statement, data type, built-in function, integration task
+ *
+ * Outputs:
+ *   assets/DELUGE_SKILL.md      the skill an agent loads whenever it writes Deluge:
+ *                               the guide + a complete INDEX of every function and task
+ *                               by name (~6k tokens), pointing at the reference for syntax
+ *   assets/DELUGE_REFERENCE.md  the full reference: statements, data types, operators,
+ *                               system variables, every function and task with Zoho's own
+ *                               syntax, returns and description, documented limits (~25k)
+ *
+ * Two files because only a skill's description is resident per prompt while
+ * its body loads on trigger: the guide is what every Deluge task needs; the
+ * exact signature of one function is needed rarely, so it costs nothing until
+ * asked for. Edit the sources, never the outputs; `npm run gen:skill` rebuilds
+ * them and the tests fail when they are stale.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ASSETS = path.join(__dirname, '..', 'assets');
+const guide = fs.readFileSync(path.join(ASSETS, 'DELUGE_GUIDE.md'), 'utf8');
+const ref = JSON.parse(fs.readFileSync(path.join(ASSETS, 'deluge-reference.json'), 'utf8'));
+
+const esc = (s) => String(s || '').replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+const code = (s) => `\`${String(s || '').replace(/`/g, "'").replace(/\s+/g, ' ').trim()}\``;
+/** Trim the TOC/footer text that occasionally trails a section on Zoho's pages. */
+const untoc = (s) => String(s || '').split(/Related Links|Sample Response|Table of Contents|Get Started Now/)[0];
+/** First syntax line only, for tables; the "(OR)" alternates are noise there. */
+const firstSyntax = (s) => untoc(s).split('\n').map((l) => l.trim()).filter((l) => l && !/^\(OR\)$/i.test(l))[0] || '';
+const byName = (a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' });
+
+const CAT_ORDER = ['Text', 'Number', 'List', 'Key-value (Map)', 'Collection', 'Date-time', 'Common / conversion', 'Encryption', 'XML'];
+const LABEL = { crm: 'Zoho CRM', books: 'Zoho Books', desk: 'Zoho Desk', creator: 'Zoho Creator', people: 'Zoho People', projects: 'Zoho Projects', recruit: 'Zoho Recruit', mail: 'Zoho Mail', cliq: 'Zoho Cliq', sheet: 'Zoho Sheet', writer: 'Zoho Writer', workdrive: 'Zoho WorkDrive', analytics: 'Zoho Analytics', invoice: 'Zoho Invoice', inventory: 'Zoho Inventory', subscriptions: 'Zoho Billing (Subscriptions)', bookings: 'Zoho Bookings', calendar: 'Zoho Calendar', salesiq: 'Zoho SalesIQ' };
+
+function grouped(items, keyOf) {
+  const m = new Map();
+  for (const it of items || []) {
+    const k = keyOf(it);
+    if (!m.has(k)) m.set(k, []);
+    m.get(k).push(it);
+  }
+  return m;
+}
+const fnByCat = grouped(ref.functions, (f) => f.category);
+const taskByProd = grouped(ref.tasks, (t) => (t.product === 'subscription' ? 'subscriptions' : t.product));
+const catOrder = [...CAT_ORDER, ...[...fnByCat.keys()].filter((k) => !CAT_ORDER.includes(k))].filter((k) => fnByCat.has(k));
+const prodOrder = ['crm', ...[...taskByProd.keys()].filter((k) => k !== 'crm').sort()];
+
+// ---------------------------------------------------------------------------
+// DELUGE_SKILL.md — guide + complete name index
+// ---------------------------------------------------------------------------
+const fnCount = [...fnByCat.values()].reduce((n, v) => n + v.length, 0);
+const taskCount = [...taskByProd.values()].reduce((n, v) => n + v.length, 0);
+
+const skill = [];
+skill.push(guide.trimEnd(), '', '---', '');
+skill.push('# Part 2 — Everything that exists (names only)', '');
+skill.push(`What exists in Deluge, generated from ${ref.source}. Statements and data types are listed in full below because they are few. The ${fnCount} built-in functions and ${taskCount} integration tasks are summarised by category — **every one of them is named, with its exact syntax, parameters and return type, in the companion reference**: read \`references/REFERENCE.md\` in this skill folder, or run \`zone llm deluge-reference\`. If a name is not there, it does not exist in Deluge — do not invent one.`, '');
+
+skill.push('## Statements', '');
+skill.push((ref.statements || []).map((s) => `\`${s.name}\``).concat(['`invokeurl`', '`info`', '`return`']).join(' · '), '');
+
+skill.push('## Data types', '');
+skill.push((ref.datatypes || []).map((d) => `\`${d.name}\``).join(' · '), '');
+
+// Categories and counts, not 337 names. Every one of those names already
+// appears in DELUGE_REFERENCE.md WITH its syntax, so listing them here bought
+// nothing and cost ~1,800 tokens on every trigger — pushing the skill body over
+// the Agent Skills spec's 5,000-token recommendation. The agent is told where
+// to look instead, which preserves the "do not invent a name" guarantee.
+skill.push('## Built-in functions — ' + fnCount + ' across ' + catOrder.length + ' categories', '');
+skill.push(catOrder.map((cat) => `**${cat}** (${fnByCat.get(cat).length})`).join(' · '), '');
+
+skill.push('## Integration tasks — ' + taskCount + ' across ' + prodOrder.length + ' products', '');
+skill.push(prodOrder.map((prod) => `**${LABEL[prod] || prod}** (${taskByProd.get(prod).length})`).join(' · '), '');
+
+skill.push('## System variables', '');
+skill.push('`zoho.currentdate`, `zoho.currenttime`, `zoho.loginuser`, `zoho.loginuser.name` (Creator), `zoho.loginuserid`, `zoho.adminuser`, `zoho.adminuserid`, `zoho.appname` (Creator), `zoho.appuri` (Creator), `zoho.ipaddress`, `zoho.device.type` (Creator).', '');
+
+// ---------------------------------------------------------------------------
+// DELUGE_REFERENCE.md — the full thing
+// ---------------------------------------------------------------------------
+const out = [];
+out.push('# Zoho Deluge — complete reference', '');
+out.push(`Generated from ${ref.source}. Every entry is one documented statement, data type, built-in function or integration task; the syntax is Zoho's own. The companion \`zoho-deluge\` skill carries the guidance and the traps verified on a live org; where its **(verified)** notes disagree with wording here, they take precedence.`, '');
+
+out.push('## Statements', '');
+for (const s of ref.statements || []) {
+  out.push(`### ${s.name}`, '');
+  if (s.overview) out.push(untoc(s.overview).trim(), '');
+  if (s.syntax) out.push('```deluge', untoc(s.syntax).trim(), '```', '');
+}
+if (ref.invokeurl) {
+  out.push('### invokeurl', '');
+  if (ref.invokeurl.overview) out.push(untoc(ref.invokeurl.overview).trim(), '');
+  out.push('```deluge', untoc(ref.invokeurl.syntax).trim(), '```', '');
+  if (ref.invokeurl.params) out.push('Parameters, as documented:', '', '```text', untoc(ref.invokeurl.params).trim(), '```', '');
+}
+out.push('### info / return', '', '`info <expression>;` writes to the execution log. `return <expression>;` (or bare `return;` in a `void` function) ends the function with that value.', '');
+
+out.push('## Data types', '', '| Type | Summary | Example |', '|---|---|---|');
+for (const d of ref.datatypes || []) out.push(`| **${esc(d.name)}** | ${esc(untoc(d.notes || d.overview)).slice(0, 380)} | ${d.example ? code(d.example.split('\n')[0]) : ''} |`);
+out.push('', 'Reserved keywords (not usable as variable names): ' + (ref.keywords || []).map((k) => `\`${k}\``).join(', '), '');
+
+if (ref.operators) out.push('## Operators', '', '```text', ref.operators.trim(), '```', '');
+if (ref.systemVariables) out.push('## System variables', '', '```text', ref.systemVariables.trim(), '```', '');
+
+out.push('## Built-in functions', '', "Columns: how it is called (Zoho's syntax, first form), what it returns, what it does. `<variable>` is the result; the receiver is the value before the dot.", '');
+for (const cat of catOrder) {
+  const list = fnByCat.get(cat).slice().sort(byName);
+  out.push(`### ${cat} (${list.length})`, '', '| Function | Syntax | Returns | Does |', '|---|---|---|---|');
+  for (const f of list) out.push(`| \`${f.name}\` | ${code(firstSyntax(f.syntax))} | ${esc(f.returns)} | ${esc(untoc(f.overview))} |`);
+  out.push('');
+}
+
+out.push('## Integration tasks (`zoho.<product>.*`)', '', 'Each task is one API call against a daily limit of 2,000 per user; inside a loop it counts once per iteration. Product-specific arguments (connection names, module names, ids) follow the REST API behind each task.', '');
+for (const prod of prodOrder) {
+  const list = taskByProd.get(prod).slice().sort(byName);
+  out.push(`### ${LABEL[prod] || prod} (${list.length})`, '', '| Task | Syntax | Does |', '|---|---|---|');
+  for (const t of list) out.push(`| \`${esc(t.name)}\` | ${code(firstSyntax(t.syntax))} | ${esc(untoc(t.overview))} |`);
+  out.push('');
+}
+
+if (ref.limits) out.push('## Documented limits', '', '```text', ref.limits.trim(), '```', '');
+
+const tidy = (arr) => arr.join('\n').replace(/\n{3,}/g, '\n\n') + '\n';
+const skillText = tidy(skill);
+const refText = tidy(out);
+fs.writeFileSync(path.join(ASSETS, 'DELUGE_SKILL.md'), skillText);
+fs.writeFileSync(path.join(ASSETS, 'DELUGE_REFERENCE.md'), refText);
+const tok = (s) => Math.round(s.length / 4).toLocaleString('en-US');
+console.log(`DELUGE_SKILL.md      ${skillText.length.toLocaleString('en-US')} chars (~${tok(skillText)} tokens)`);
+console.log(`DELUGE_REFERENCE.md  ${refText.length.toLocaleString('en-US')} chars (~${tok(refText)} tokens) — ${(ref.functions || []).length} functions, ${(ref.tasks || []).length} tasks, ${(ref.statements || []).length} statements, ${(ref.datatypes || []).length} data types`);

package/scripts/scrape-deluge-docs.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * Rebuild assets/deluge-reference.json from Zoho's Deluge documentation.
+ *
+ *   npm run scrape:docs      # then: npm run gen:skill
+ *
+ * Why a scraper and not a hand-written list: the reference has 209 functions
+ * and 139 integration tasks. Typing them from memory is how an agent ends up
+ * with `getJSONType()` — a function that does not exist. Every entry here is
+ * read from the page Zoho publishes for it, and the page URL is kept so a
+ * disputed signature can be checked at the source.
+ *
+ * How the site is laid out (discovered, not documented — the navigation is
+ * rendered client-side, so category and product index pages are fetched
+ * directly and their links followed):
+ *
+ *   /deluge/help/functions/<category>.html         category index -> /functions/<cat>/<fn>.html
+ *   /deluge/help/<product>-tasks.html              product index  -> /<product>/<task>.html
+ *   /deluge/help/conditional-statements/*.html, /misc-statements/*.html, /list-manipulations/*.html
+ *   /deluge/help/web-data/invokeurl-task.html, /datatypes/*.html, operators.html, system-variables.html, limitations.html
+ *
+ * Each page has a client-side TOC that repeats the heading names, so sections
+ * are located by their <h2>/<h3> tag (not by the first occurrence of the word).
+ * Network only; no dependency beyond Node's fetch.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const BASE = 'https://www.zoho.com';
+const HELP = `${BASE}/deluge/help/`;
+const OUT = path.join(__dirname, '..', 'assets', 'deluge-reference.json');
+const UA = 'Mozilla/5.0 (deluge-core reference scraper; +https://www.npmjs.com/package/@wanasapps/deluge-core)';
+
+const FUNCTION_CATEGORIES = ['text', 'number', 'list', 'key-value', 'date-time', 'time', 'logical', 'collection', 'conversion', 'type-check', 'utilities', 'xml'];
+const FUNCTION_EXTRA_INDEXES = ['functions-returning-boolean', 'encryption-tasks'];
+const PRODUCT_INDEXES = ['crm-integration-tasks-V8', 'crm-tasks', 'books-tasks', 'creator-tasks', 'desk-tasks', 'people-tasks', 'mail-tasks', 'cliq-tasks',
+  'projects-tasks', 'recruit-tasks', 'sheet-tasks', 'writer-tasks', 'workdrive-tasks', 'analytics-tasks', 'invoice-tasks', 'inventory-tasks',
+  'subscriptions-tasks', 'bookings-tasks', 'calendar-tasks', 'salesiq-tasks'];
+const STATEMENTS = [
+  ['conditional-statements/condition', 'if / else if / else / conditional if / ifNull'],
+  ['list-manipulations/for-each-element', 'for each'],
+  ['misc-statements/break', 'break'], ['misc-statements/continue', 'continue'],
+  ['misc-statements/try-catch', 'try / catch'], ['misc-statements/throw', 'throw'],
+  ['misc-statements/send-mail', 'sendmail']
+];
+const DATATYPES = ['datatypes/text', 'datatypes/number', 'datatypes/decimal', 'datatypes/boolean', 'datatypes/date-time', 'datatypes/time', 'datatypes/list', 'datatypes/key-value', 'datatypes/collection', 'create-list-datatype'];
+const CATEGORY_LABEL = { string: 'Text', text: 'Text', number: 'Number', list: 'List', map: 'Key-value (Map)', datetime: 'Date-time', collection: 'Collection', common: 'Common / conversion', encryption: 'Encryption', xml: 'XML' };
+
+/** Pages whose indexed URL 404s; Zoho's own search snippets describe them. */
+const MOVED_FUNCTIONS = [
+  ['getPrefixIgnoreCase', 'Text', '<variable> = <text>.getPrefixIgnoreCase(<search_text>);', 'Gets the prefix of the specified search text in the input text, performing a case-insensitive search.'],
+  ['getSuffixIgnoreCase', 'Text', '<variable> = <text>.getSuffixIgnoreCase(<search_text>);', 'Gets the suffix of the specified search text in the input text, performing a case-insensitive search.'],
+  ['replaceAllIgnoreCase', 'Text', '<variable> = <text>.replaceAllIgnoreCase(<search_text>, <new_text>);', 'Replaces all occurrences of the search text with the new text, performing a case-insensitive search.'],
+  ['replaceFirstIgnoreCase', 'Text', '<variable> = <text>.replaceFirstIgnoreCase(<search_text>, <new_text>);', 'Replaces the first occurrence of the search text with the new text, performing a case-insensitive search.'],
+  ['isAscii', 'Text', '<variable> = <text>.isAscii();', 'Returns true if every character of the text is ASCII.'],
+  ['previousWeekDay', 'Date-time', '<variable> = <date>.previousWeekDay();', 'Returns the previous weekday (Monday to Friday) before the given date.']
+];
+
+// ---- html helpers --------------------------------------------------------------
+
+const ZWSP = /​/g;
+function clean(html) {
+  let t = html.replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>/gi, '');
+  t = t.replace(/<br\s*\/?>/gi, '\n').replace(/<\/(p|div|li|tr|h[1-6]|pre|td|th)>/gi, '\n');
+  t = t.replace(/<[^>]+>/g, '');
+  t = t.replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  t = t.replace(ZWSP, '').replace(/ /g, ' ').replace(/�/g, ' ');
+  return t.replace(/[ \t]+/g, ' ').replace(/\n\s*\n+/g, '\n\n');
+}
+function section(html, name) {
+  const re = new RegExp(`<h[23][^>]*>(?:<a[^>]*></a>)?\\s*${name}\\s*</h[23]>([\\s\\S]*?)(?=<h[23]|$)`, 'i');
+  const m = re.exec(html);
+  return m ? clean(m[1]).trim() : '';
+}
+const first = (s) => (s.trim() ? s.trim().split(/(?<=[.!?])\s/)[0] : '');
+const untoc = (s) => String(s || '').split(/Related Links|Sample Response|Table of Contents|Get Started Now/)[0];
+
+async function get(url) {
+  const r = await fetch(url, { headers: { 'User-Agent': UA } });
+  if (!r.ok) return null;
+  return (await r.text()).replace(ZWSP, '');
+}
+const helpLinks = (html) => [...new Set([...html.matchAll(/href="([^"#?]*\/deluge\/help\/[^"#?]*\.html)"/g)].map((m) => m[1].replace(/^https?:\/\/www\.zoho\.com/, '')))];
+
+async function pageRecord(rel) {
+  const html = await get(BASE + rel);
+  if (!html) return null;
+  const title = clean((/<h1[^>]*>([\s\S]*?)<\/h1>/.exec(html) || [])[1] || '').trim();
+  const syn = section(html, 'Syntax');
+  const cut = /\n(?:where[:,]?|Param|Parameter|Params)\b/.exec(syn);
+  const syntax = untoc(cut ? syn.slice(0, cut.index) : syn).trim();
+  const params = cut ? untoc(syn.slice(cut.index)).trim() : '';
+  let overview = section(html, 'Overview').split('\n').filter((l) => l.trim() && !/^Note/.test(l.trim())).join('\n').trim();
+  if (!overview) overview = (/<meta name="description" content="([^"]*)"/.exec(html) || [])[1] || '';
+  const returns = section(html, 'Return Type').split('\n')[0].trim();
+  return { url: BASE + rel, title, syntax, params, overview: first(untoc(overview)), returns };
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  await Promise.all(Array.from({ length: limit }, async () => {
+    for (;;) { const n = i++; if (n >= items.length) return; out[n] = await fn(items[n], n); }
+  }));
+  return out;
+}
+
+// ---- main ----------------------------------------------------------------------
+
+(async () => {
+  const log = (m) => process.stderr.write(m + '\n');
+
+  // 1. function pages from every category index
+  const fnLinks = new Set();
+  for (const cat of FUNCTION_CATEGORIES) {
+    const html = await get(`${HELP}functions/${cat}.html`);
+    if (!html) { log(`  (no index for functions/${cat})`); continue; }
+    for (const l of helpLinks(html)) if (/\/functions\/[^/]+\/[^/]+\.html$/.test(l)) fnLinks.add(l);
+  }
+  for (const idx of FUNCTION_EXTRA_INDEXES) {
+    const html = await get(`${HELP}${idx}.html`);
+    if (html) for (const l of helpLinks(html)) if (/\/functions\//.test(l)) fnLinks.add(l);
+  }
+  log(`function pages: ${fnLinks.size}`);
+
+  // 2. task pages from every product index
+  const taskLinks = new Set();
+  for (const idx of PRODUCT_INDEXES) {
+    const html = await get(`${HELP}${idx}.html`);
+    if (!html) { log(`  (no index for ${idx})`); continue; }
+    for (const l of helpLinks(html)) if (!/\/functions\/|-tasks\.html$|integration-tasks|built-in-functions/.test(l)) taskLinks.add(l);
+  }
+  log(`task pages: ${taskLinks.size}`);
+
+  // 3. fetch + parse
+  const functions = [];
+  for (const rec of await mapLimit([...fnLinks], 8, pageRecord)) {
+    if (!rec || !rec.syntax) continue;
+    const cat = (/\/functions\/([^/]+)\//.exec(rec.url) || [])[1];
+    const name = (/\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/.exec(rec.syntax) || /\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/.exec(rec.syntax) || [])[1] || path.basename(rec.url, '.html');
+    functions.push({ category: CATEGORY_LABEL[cat] || cat, name, syntax: rec.syntax.slice(0, 800), returns: rec.returns.slice(0, 60), overview: rec.overview.slice(0, 260), params: rec.params.slice(0, 700), url: rec.url });
+  }
+  for (const [name, category, syntax, overview] of MOVED_FUNCTIONS) {
+    if (!functions.some((f) => f.name.toLowerCase() === name.toLowerCase())) functions.push({ category, name, syntax, returns: '', overview, params: '', url: null });
+  }
+
+  const tasks = [];
+  for (const rec of await mapLimit([...taskLinks], 8, pageRecord)) {
+    if (!rec || !rec.syntax) continue;
+    const m = /\/deluge\/help\/([^/]+)\/([^/]+)\.html$/.exec(rec.url);
+    if (!m) continue;
+    const product = m[1] === 'subscription' ? 'subscriptions' : m[1];
+    const slugWords = m[2].replace(/-v8$/i, '').split('-');
+    const camel = slugWords[0] + slugWords.slice(1).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+    const cands = [...rec.syntax.matchAll(/(zoho\.[a-zA-Z0-9_.]+)\s*\(/g)].map((x) => x[1]);
+    let name = cands.find((c) => c.split('.').pop().toLowerCase() === camel.toLowerCase()) || cands[0] || null;
+    if (!name || (cands.length && name.split('.').pop().toLowerCase() !== camel.toLowerCase() && /invokeconnector/i.test(name) && !/invoke-connector/.test(m[2]))) {
+      name = `zoho.${product}.${camel} (via invokeConnector)`;
+    }
+    tasks.push({ product, name, syntax: rec.syntax.slice(0, 400), overview: rec.overview.slice(0, 220), url: rec.url });
+  }
+
+  // 4. statements, invokeurl, data types, limits, operators, system variables
+  const statements = [];
+  for (const [rel, name] of STATEMENTS) {
+    const rec = await pageRecord(`/deluge/help/${rel}.html`);
+    if (rec) statements.push({ name, syntax: rec.syntax.slice(0, 900), overview: rec.overview.slice(0, 300), url: rec.url });
+  }
+  const iu = await pageRecord('/deluge/help/web-data/invokeurl-task.html');
+  const invokeurl = iu ? { syntax: iu.syntax.slice(0, 900), params: iu.params.slice(0, 4000), overview: iu.overview.slice(0, 300), url: iu.url } : null;
+
+  const datatypes = [];
+  for (const rel of DATATYPES) {
+    const html = await get(`${HELP}${rel}.html`);
+    if (!html) continue;
+    const t = clean(html);
+    const i = t.indexOf('Overview');
+    const body = i >= 0 ? t.slice(i + 8, i + 1400) : '';
+    const ex = /Example\n([\s\S]*?)(?:\nNote|\nSupported|\nGet Started|$)/.exec(body);
+    datatypes.push({ name: rel.replace('datatypes/', '').replace('create-list-datatype', 'typed list'), overview: first(body.split('\n')[0] || '').slice(0, 260), notes: untoc(body.slice(0, 700)).replace(/\s+/g, ' '), example: (ex ? ex[1].trim() : '').slice(0, 300) });
+  }
+
+  const slice = (t, from, to, max) => { const i = t.indexOf(from); if (i < 0) return ''; const j = to ? t.indexOf(to, i) : -1; return t.slice(i, j > i ? j : i + max).slice(0, max); };
+  const limitsHtml = await get(`${HELP}limitations.html`);
+  const limits = limitsHtml ? slice(clean(limitsHtml), 'Statement Limitation\nThe', 'Time Zone Limitations', 3200) : '';
+  const sysHtml = await get(`${HELP}system-variables.html`);
+  const systemVariables = sysHtml ? slice(clean(sysHtml), 'Date Variables', null, 2600) : '';
+  const opsHtml = await get(`${HELP}operators.html`);
+  const operators = opsHtml ? slice(clean(opsHtml), 'Types of Operators', null, 2200) : '';
+  const keywords = 'bool collection date false for-each else else-if float from if ifnull in int is list map null permissions portal reload return string thisapp true void zoho'.split(' ');
+
+  const out = { source: `${HELP} (scraped ${new Date().toISOString().slice(0, 10)})`, functions, tasks, statements, invokeurl, datatypes, limits, systemVariables, operators, keywords };
+  fs.writeFileSync(OUT, JSON.stringify(out, null, 1) + '\n');
+  log(`wrote ${path.relative(process.cwd(), OUT)}: ${functions.length} functions, ${tasks.length} tasks, ${statements.length} statements, ${datatypes.length} data types`);
+  log('now run: npm run gen:skill');
+})().catch((e) => { console.error(e); process.exit(1); });

package/src/format/signature.js

@@ -1,70 +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 };
+/**
+ * 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/index.js

@@ -33,3 +33,7 @@ module.exports = {
   // editor-agnostic analysis engines
   analyze
 };
+
+/** The agent-facing Deluge guide (also `language.skill()`). */
+module.exports.delugeSkill = module.exports.language.skill;
+module.exports.delugeReference = module.exports.language.reference;

package/src/language/index.js

@@ -29,11 +29,42 @@ function snippets() {
   return read('snippets.json');
 }
 
+/**
+ * The Deluge skill: a guide written for AI coding agents — syntax, control
+ * flow, the standard library, calling Zoho, HTTP, and the runtime traps that
+ * were verified against a live org. Tools install it where an agent reads
+ * (`zone skill deluge`), so the agent writes Deluge instead of JavaScript with
+ * Deluge punctuation. Plain Markdown, no frontmatter; the installer adds
+ * whatever header its target needs.
+ */
+function skill() {
+  return fs.readFileSync(path.join(ASSETS, 'DELUGE_SKILL.md'), 'utf8');
+}
+
+/**
+ * The complete reference — every statement, data type, built-in function and
+ * integration task with Zoho's own syntax — rendered from deluge-reference.json.
+ * Separate from skill() because it is ~22k tokens: an agent needs the guide on
+ * every Deluge task, but the exact signature of one function only occasionally.
+ */
+function reference() {
+  return fs.readFileSync(path.join(ASSETS, 'DELUGE_REFERENCE.md'), 'utf8');
+}
+
+/** The structured data behind reference(): functions, tasks, statements, data types, limits. */
+function referenceData() {
+  return JSON.parse(fs.readFileSync(path.join(ASSETS, 'deluge-reference.json'), 'utf8'));
+}
+
 /** 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')
+  snippets: path.join(ASSETS, 'snippets.json'),
+  skill: path.join(ASSETS, 'DELUGE_SKILL.md'),
+  reference: path.join(ASSETS, 'DELUGE_REFERENCE.md'),
+  referenceData: path.join(ASSETS, 'deluge-reference.json'),
+  guide: path.join(ASSETS, 'DELUGE_GUIDE.md')
 };
 
-module.exports = { EXTENSIONS, grammar, configuration, snippets, assetPaths };
+module.exports = { EXTENSIONS, grammar, configuration, snippets, skill, reference, referenceData, assetPaths };