@wanasapps/deluge-core 1.0.0 → 1.2.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.2.0",
+  "description": "Deluge language tooling for every Zoho product: formatter, source transforms, TextMate grammar, snippets, an editor-agnostic linter, and AI-agent skills \u2014 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/gen-skill.js

@@ -0,0 +1,137 @@
+#!/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 skill = [];
+skill.push(guide.trimEnd(), '', '---', '');
+skill.push('# Part 2 — Everything that exists (names only)', '');
+skill.push(`Every documented statement, built-in function and integration task, by name, generated from ${ref.source}. If a name is not here, it does not exist in Deluge — do not invent one. For a function's exact syntax, parameters and return type, load the companion skill \`zoho-deluge-reference\` (or run \`zone llm deluge-reference\`).`, '');
+
+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(' · '), '');
+
+skill.push('## Built-in functions', '');
+for (const cat of catOrder) {
+  const names = fnByCat.get(cat).slice().sort(byName).map((f) => `\`${f.name}\``);
+  skill.push(`**${cat}** (${names.length}): ${names.join(', ')}`, '');
+}
+
+skill.push('## Integration tasks', '');
+for (const prod of prodOrder) {
+  const names = taskByProd.get(prod).slice().sort(byName).map((t) => `\`${t.name}\``);
+  skill.push(`**${LABEL[prod] || prod}** (${names.length}): ${names.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/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 };