@superblocksteam/vite-plugin-file-sync 2.0.83 → 2.0.84-next.0

package/dist/ai-service/skills/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-service/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,cAAc,YAAY,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAS3C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-service/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,cAAc,YAAY,CAAC;AAI3B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,EAAE,CA+BzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAkBjD"}

package/dist/ai-service/skills/index.js

@@ -1,36 +1,101 @@
 /**
  * Skills module - provides skill discovery and path utilities.
  *
- * System skills are bundled as markdown files in this package.
- * At runtime, the SkillFileHandler reads these files from the filesystem
- * relative to this module's location.
+ * System skills are stored as .md files and converted to TypeScript
+ * during build by the generate-skills script. This avoids runtime
+ * file I/O and path resolution issues.
  */
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { getErrorMeta, getPrefixedLogger } from "../../util/logger.js";
+import { SYSTEM_SKILLS } from "./system/_registry.generated.js";
 export * from "./types.js";
+const logger = getPrefixedLogger("[Skills]");
 /**
- * Get the absolute path to the bundled skills directory.
+ * Parse YAML frontmatter from markdown content.
  *
- * Works both in development (src/) and production (dist/).
- * System skills are stored as markdown files in the `system/` subdirectory.
+ * @param content - The markdown content to parse
+ * @param sourcePath - Path to the source file (for error logging)
+ */
+function parseFrontmatter(content, sourcePath) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match?.[1])
+        return null;
+    try {
+        return parseYaml(match[1]);
+    }
+    catch (error) {
+        logger.error(`Failed to parse YAML frontmatter${sourcePath ? ` in ${sourcePath}` : ""}`, getErrorMeta(error));
+        return null;
+    }
+}
+/**
+ * Get content of a system skill by its relative path.
+ *
+ * @param relativePath - Path relative to skills/system/ (e.g., "superblocks-frontend/SKILL.md")
+ * @returns Skill content or undefined if not found
+ */
+export function getSystemSkillContent(relativePath) {
+    return SYSTEM_SKILLS[relativePath];
+}
+/**
+ * Get all available system skills with their metadata.
  *
- * @returns Absolute path to the skills directory
+ * @returns Array of skill metadata
  */
-export function getSkillsDirectory() {
-    // __dirname equivalent for ESM
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = path.dirname(__filename);
-    // Skills are in the same directory as this file
-    // In dev: src/ai-service/skills/
-    // In dist: dist/ai-service/skills/
-    return __dirname;
+export function getSystemSkillsMetadata() {
+    const skills = [];
+    for (const [relativePath, content] of Object.entries(SYSTEM_SKILLS)) {
+        // Only process SKILL.md files for metadata
+        if (!relativePath.endsWith("SKILL.md")) {
+            continue;
+        }
+        const skillPath = `skills/system/${relativePath}`;
+        const frontmatter = parseFrontmatter(content, skillPath);
+        if (!frontmatter) {
+            logger.warn(`Skill ${skillPath} has no valid frontmatter, skipping`);
+            continue;
+        }
+        const skillDir = relativePath.replace(/\/SKILL\.md$/, "");
+        const name = frontmatter.name || skillDir;
+        let description = frontmatter.description || "";
+        // Clean up multiline description
+        description = description.trim().replace(/\s+/g, " ");
+        skills.push({
+            name,
+            description,
+            location: `skills/system/${relativePath}`,
+        });
+    }
+    return skills;
 }
 /**
- * Get the absolute path to the system skills directory.
+ * Generate XML representation of available skills for the system prompt.
  *
- * @returns Absolute path to the system skills directory
+ * @returns XML string listing all available skills, or null if no skills available
+ */
+export function generateSkillsXml() {
+    const skills = getSystemSkillsMetadata();
+    if (skills.length === 0) {
+        return null;
+    }
+    const skillEntries = skills
+        .map((skill) => `  <skill>
+    <name>${escapeXml(skill.name)}</name>
+    <description>${escapeXml(skill.description)}</description>
+    <location>${escapeXml(skill.location)}</location>
+  </skill>`)
+        .join("\n");
+    return `<available_skills>\n${skillEntries}\n</available_skills>`;
+}
+/**
+ * Escape special XML characters.
  */
-export function getSystemSkillsDirectory() {
-    return path.join(getSkillsDirectory(), "system");
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
 }
 //# sourceMappingURL=index.js.map

package/dist/ai-service/skills/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-service/skills/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,cAAc,YAAY,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,+BAA+B;IAC/B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3C,gDAAgD;IAChD,iCAAiC;IACjC,mCAAmC;IACnC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-service/skills/index.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/skills/system/_registry.generated.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Map of skill file paths to their content.
+ * Keys are relative paths from skills/system/ (e.g., "superblocks-frontend/SKILL.md")
+ */
+export declare const SYSTEM_SKILLS: Record<string, string>;
+//# sourceMappingURL=_registry.generated.d.ts.map

package/dist/ai-service/skills/system/_registry.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_registry.generated.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQhD,CAAC"}

package/dist/ai-service/skills/system/_registry.generated.js

@@ -0,0 +1,24 @@
+// Auto-generated skills registry
+// Do not edit directly - run npm run generate-skills
+/* eslint-disable prettier/prettier */
+import { content as superblocks_api_references_code_blocks } from "./superblocks-api/references/code-blocks.generated.js";
+import { content as superblocks_api_references_graphql } from "./superblocks-api/references/graphql.generated.js";
+import { content as superblocks_api_references_rest_apis } from "./superblocks-api/references/rest-apis.generated.js";
+import { content as superblocks_api_references_sql_databases } from "./superblocks-api/references/sql-databases.generated.js";
+import { content as superblocks_api_skill } from "./superblocks-api/skill.generated.js";
+import { content as superblocks_frontend_references_embedding } from "./superblocks-frontend/references/embedding.generated.js";
+import { content as superblocks_frontend_skill } from "./superblocks-frontend/skill.generated.js";
+/**
+ * Map of skill file paths to their content.
+ * Keys are relative paths from skills/system/ (e.g., "superblocks-frontend/SKILL.md")
+ */
+export const SYSTEM_SKILLS = {
+    "superblocks-api/SKILL.md": superblocks_api_skill,
+    "superblocks-api/references/code-blocks.md": superblocks_api_references_code_blocks,
+    "superblocks-api/references/graphql.md": superblocks_api_references_graphql,
+    "superblocks-api/references/rest-apis.md": superblocks_api_references_rest_apis,
+    "superblocks-api/references/sql-databases.md": superblocks_api_references_sql_databases,
+    "superblocks-frontend/SKILL.md": superblocks_frontend_skill,
+    "superblocks-frontend/references/embedding.md": superblocks_frontend_references_embedding,
+};
+//# sourceMappingURL=_registry.generated.js.map

package/dist/ai-service/skills/system/_registry.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_registry.generated.js","sourceRoot":"","sources":["../../../../src/ai-service/skills/system/_registry.generated.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,qDAAqD;AACrD,sCAAsC;AAEtC,OAAO,EAAE,OAAO,IAAI,sCAAsC,EAAE,MAAM,uDAAuD,CAAC;AAC1H,OAAO,EAAE,OAAO,IAAI,kCAAkC,EAAE,MAAM,mDAAmD,CAAC;AAClH,OAAO,EAAE,OAAO,IAAI,oCAAoC,EAAE,MAAM,qDAAqD,CAAC;AACtH,OAAO,EAAE,OAAO,IAAI,wCAAwC,EAAE,MAAM,yDAAyD,CAAC;AAC9H,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AACxF,OAAO,EAAE,OAAO,IAAI,yCAAyC,EAAE,MAAM,0DAA0D,CAAC;AAChI,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AAElG;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,0BAA0B,EAAE,qBAAqB;IACjD,2CAA2C,EAAE,sCAAsC;IACnF,uCAAuC,EAAE,kCAAkC;IAC3E,yCAAyC,EAAE,oCAAoC;IAC/E,6CAA6C,EAAE,wCAAwC;IACvF,+BAA+B,EAAE,0BAA0B;IAC3D,8CAA8C,EAAE,yCAAyC;CAC1F,CAAC"}

package/dist/ai-service/skills/system/superblocks-api/references/code-blocks.generated.d.ts

@@ -1,2 +1,2 @@
-export declare const content = "# JavaScript and Python Code Blocks\n\nReference documentation for working with JavaScript and Python code blocks in Superblocks APIs.\n\n## JavaScript Block\n\n```typescript\nimport { JavaScript } from \"@superblocksteam/library\";\n\nnew JavaScript(\"process_data\", {\n  fn: ({ input }: { input: any }) => {\n    // Your JavaScript code here\n    return processedResult;\n  }\n})\n```\n\n### Key Features\n\n- Full ES2020+ syntax support\n- Access to previous block outputs\n- Can return any JSON-serializable value\n- Runs in Node.js environment\n\n### Common Patterns\n\n```typescript\n// Data transformation\nnew JavaScript(\"transform\", {\n  fn: ({ users }) => users.output.map((user: any) => ({\n    id: user.id,\n    displayName: `${user.firstName} ${user.lastName}`,\n    email: user.email.toLowerCase()\n  }))\n})\n\n// Conditional logic\nnew JavaScript(\"validate\", {\n  fn: ({ data }: { data: any }) => {\n    if (!data.email || !data.email.includes(\"@\")) {\n      throw new Error(\"Invalid email address\");\n    }\n    return { valid: true, data };\n  }\n})\n\n// Aggregation\nnew JavaScript(\"aggregate\", {\n  fn: ({ orders }) => {\n    const output = orders.output;\n    return {\n      totalOrders: output.length,\n      totalRevenue: output.reduce((sum: number, o: any) => sum + o.amount, 0),\n      averageOrder: output.reduce((sum: number, o: any) => sum + o.amount, 0) / output.length\n    };\n  }\n})\n\n// Working with Variables block\nnew JavaScript(\"update_state\", {\n  fn: ({ counter, items, newItem }) => {\n    // Variables use .value for reading and .set() for writing\n    const currentCount = counter.value;\n    const currentItems = items.value;\n    \n    items.set([...currentItems, newItem]);\n    counter.set(currentCount + 1);\n    \n    return { added: newItem, newCount: currentCount + 1 };\n  }\n})\n```\n\n### Available Globals\n\n```typescript\nnew JavaScript(\"with_globals\", {\n  fn: ({ Global }) => {\n    // Global object contains user/org context\n    const userId = Global.user.id;\n    const userEmail = Global.user.email;\n    const userGroups = Global.groups;\n    \n    return { userId, userEmail, isAdmin: userGroups.some(g => g.name === \"Admin\") };\n  }\n})\n```\n\n## Python Block\n\n```typescript\nimport { Python } from \"@superblocksteam/library\";\n\nnew Python(\"python_transform\", {\n  code: `\nimport json\n\n# Access inputs directly\nresult = {\n    \"processed\": True,\n    \"count\": len(data)\n}\n\n# Return must be JSON serializable\nreturn result\n  `\n})\n```\n\n### Key Features\n\n- Python 3.x runtime\n- Common libraries available (pandas, numpy, etc.)\n- Access inputs as Python variables\n- Return value must be JSON serializable\n\n### Common Patterns\n\n```python\n# Data processing with pandas\nimport pandas as pd\n\ndf = pd.DataFrame(users_data)\nfiltered = df[df['status'] == 'active']\nresult = filtered.to_dict(orient='records')\nreturn result\n```\n\n```python\n# Statistical analysis\nimport numpy as np\n\nvalues = [item['amount'] for item in orders_data]\nreturn {\n    'mean': float(np.mean(values)),\n    'median': float(np.median(values)),\n    'std': float(np.std(values))\n}\n```\n\n### Python Variable Access\n\n```python\n# Inputs are available as Python variables\n# Previous block outputs are also available\n\n# Access input parameter\nemail = input_email  # Direct variable access\n\n# Access previous block output\nusers = fetch_users  # Output from previous block named 'fetch_users'\n```\n\n## Choosing JavaScript vs Python\n\n**Use JavaScript when:**\n- Simple data transformations\n- JSON manipulation\n- Working with Superblocks Variables\n- Need to use `.set()` for state updates\n\n**Use Python when:**\n- Complex data analysis (pandas)\n- Statistical computations (numpy/scipy)\n- Machine learning operations\n- Heavy numerical processing\n\n## Error Handling\n\nBoth languages throw errors that can be caught with TryCatch:\n\n```typescript\nnew TryCatch(\"safe_process\", {\n  try: [\n    new JavaScript(\"risky_operation\", {\n      fn: ({ data }) => {\n        if (!data) throw new Error(\"Data is required\");\n        return processData(data);\n      }\n    })\n  ],\n  catch: [\n    new JavaScript(\"handle_error\", {\n      fn: ({ processError }) => ({\n        success: false,\n        error: processError.value.message\n      })\n    })\n  ],\n  variables: { error: \"processError\" }\n})\n```\n\n## Best Practices\n\n1. **Keep blocks focused** - One logical operation per block\n2. **Use descriptive names** - `calculate_shipping_cost` not `calc`\n3. **Type your inputs** - `({ userId }: { userId: string })` not `({ userId })`\n4. **Handle edge cases** - Check for null/undefined/empty arrays\n5. **Return clean data** - Only return what's needed downstream\n";
+export declare const content = "# JavaScript and Python Code Blocks\n\nReference documentation for working with JavaScript and Python code blocks in Superblocks APIs.\n\n## JavaScript Block\n\n```typescript\nimport { JavaScript } from \"@superblocksteam/library\";\n\nnew JavaScript(\"process_data\", {\n  fn: ({ input }: { input: any }) => {\n    // Your JavaScript code here\n    return processedResult;\n  }\n})\n```\n\n### Key Features\n\n- Full ES2020+ syntax support\n- Access to previous block outputs\n- Can return any JSON-serializable value\n- Runs in Node.js environment\n\n### Common Patterns\n\n```typescript\n// Data transformation\nnew JavaScript(\"transform\", {\n  fn: ({ users }) => users.output.map((user: any) => ({\n    id: user.id,\n    displayName: `${user.firstName} ${user.lastName}`,\n    email: user.email.toLowerCase()\n  }))\n})\n\n// Conditional logic\nnew JavaScript(\"validate\", {\n  fn: ({ data }: { data: any }) => {\n    if (!data.email || !data.email.includes(\"@\")) {\n      throw new Error(\"Invalid email address\");\n    }\n    return { valid: true, data };\n  }\n})\n\n// Aggregation\nnew JavaScript(\"aggregate\", {\n  fn: ({ orders }) => {\n    const output = orders.output;\n    return {\n      totalOrders: output.length,\n      totalRevenue: output.reduce((sum: number, o: any) => sum + o.amount, 0),\n      averageOrder: output.reduce((sum: number, o: any) => sum + o.amount, 0) / output.length\n    };\n  }\n})\n\n// Working with Variables block\nnew JavaScript(\"update_state\", {\n  fn: ({ counter, items, newItem }) => {\n    // Variables use .value for reading and .set() for writing\n    const currentCount = counter.value;\n    const currentItems = items.value;\n    \n    items.set([...currentItems, newItem]);\n    counter.set(currentCount + 1);\n    \n    return { added: newItem, newCount: currentCount + 1 };\n  }\n})\n```\n\n### Available Globals\n\n```typescript\nnew JavaScript(\"with_globals\", {\n  fn: ({ Global }) => {\n    // Global object contains user/org context\n    const userId = Global.user.id;\n    const userEmail = Global.user.email;\n    const userGroups = Global.groups;\n    \n    return { userId, userEmail, isAdmin: userGroups.some(g => g.name === \"Admin\") };\n  }\n})\n```\n\n## Python Block\n\n```typescript\nimport { Python } from \"@superblocksteam/library\";\n\nnew Python(\"python_transform\", {\n  code: `\nimport json\n\n# Access inputs directly\nresult = {\n    \"processed\": True,\n    \"count\": len(data)\n}\n\n# Return must be JSON serializable\nreturn result\n  `\n})\n```\n\n### Key Features\n\n- Python 3.x runtime\n- Common libraries available (pandas, numpy, etc.)\n- Access inputs as Python variables\n- Return value must be JSON serializable\n\n### Common Patterns\n\n```python\n# Data processing with pandas\nimport pandas as pd\n\ndf = pd.DataFrame(users_data)\nfiltered = df[df['status'] == 'active']\nresult = filtered.to_dict(orient='records')\nreturn result\n```\n\n```python\n# Statistical analysis\nimport numpy as np\n\nvalues = [item['amount'] for item in orders_data]\nreturn {\n    'mean': float(np.mean(values)),\n    'median': float(np.median(values)),\n    'std': float(np.std(values))\n}\n```\n\n### Python Variable Access\n\n```python\n# Inputs are available as Python variables\n# Previous block outputs are also available\n\n# Access input parameter\nemail = input_email  # Direct variable access\n\n# Access previous block output\nusers = fetch_users  # Output from previous block named 'fetch_users'\n```\n\n## Choosing JavaScript vs Python\n\n**Use JavaScript when:**\n- Simple data transformations\n- JSON manipulation\n- Working with Superblocks Variables\n- Need to use `.set()` for state updates\n\n**Use Python when:**\n- Complex data analysis (pandas)\n- Statistical computations (numpy/scipy)\n- Machine learning operations\n- Heavy numerical processing\n\n## Error Handling\n\nBoth languages throw errors that can be caught with TryCatch:\n\n```typescript\nnew TryCatch(\"safe_process\", {\n  try: [\n    new JavaScript(\"risky_operation\", {\n      fn: ({ data }) => {\n        if (!data) throw new Error(\"Data is required\");\n        return processData(data);\n      }\n    })\n  ],\n  catch: [\n    new JavaScript(\"handle_error\", {\n      fn: ({ processError }) => ({\n        success: false,\n        error: processError.value.message\n      })\n    })\n  ],\n  variables: { error: \"processError\" }\n})\n```\n\n## Processing File Content\n\nWhen you need to read and process file content (parse CSV, extract text, validate, etc.):\n\nFilePicker files are stored on the orchestrator's file server.\n\n### Methods\n- `readContents(mode?)` - Synchronous\n- `readContentsAsync(mode?)` - Asynchronous\n\n### Mode Parameter\n- (none) - auto-detects: returns base64 string for binary files, UTF-8 string for text\n- `'raw'` - returns Buffer in JavaScript, bytes in Python (for direct byte access)\n- `'text'` - returns UTF-8 string\n- `'binary'` - returns base64 string\n\n### JavaScript - use await directly\n\n```typescript\nnew JavaScript(\"parse_csv\", {\n  fn: async ({ csvFile }) => {\n    const file = csvFile.files[0];\n    const content = await file.readContentsAsync();\n    const headers = content.split(\"\\n\")[0].split(\",\").map(h => h.trim());\n    return { fileName: file.name, headers };\n  }\n})\n\n// Binary file - use 'raw' mode for byte access\nnew JavaScript(\"check_jpeg\", {\n  fn: async ({ imageFile }) => {\n    const buf = await imageFile.files[0].readContentsAsync('raw'); // Buffer\n    const isJPEG = buf[0] === 0xFF && buf[1] === 0xD8 && buf[2] === 0xFF;\n    return { isJPEG };\n  }\n})\n```\n\n### Python - use sync for single file, async for parallel\n\n```python\n# Single file - use sync (simpler)\ncontent = file.readContents()\nrows = content.split('\\n')\n\n# Check file type by magic bytes\nraw = file.readContents('raw')\nis_pdf = raw[:4] == b'%PDF'\n\n# Multiple files in parallel - use async\nimport asyncio\nasync def fetch_all(files):\n    return await asyncio.gather(*[f.readContentsAsync() for f in files])\ncontents = asyncio.run(fetch_all(files))\n```\n\n## Best Practices\n\n1. **Keep blocks focused** - One logical operation per block\n2. **Use descriptive names** - `calculate_shipping_cost` not `calc`\n3. **Type your inputs** - `({ userId }: { userId: string })` not `({ userId })`\n4. **Handle edge cases** - Check for null/undefined/empty arrays\n5. **Return clean data** - Only return what's needed downstream\n";
 //# sourceMappingURL=code-blocks.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-api/references/code-blocks.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-blocks.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/code-blocks.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,2rJAwMnB,CAAC"}
+{"version":3,"file":"code-blocks.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/code-blocks.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,k1MAgQnB,CAAC"}

package/dist/ai-service/skills/system/superblocks-api/references/code-blocks.generated.js

@@ -193,6 +193,62 @@ new TryCatch("safe_process", {
 })
 \`\`\`
 
+## Processing File Content
+
+When you need to read and process file content (parse CSV, extract text, validate, etc.):
+
+FilePicker files are stored on the orchestrator's file server.
+
+### Methods
+- \`readContents(mode?)\` - Synchronous
+- \`readContentsAsync(mode?)\` - Asynchronous
+
+### Mode Parameter
+- (none) - auto-detects: returns base64 string for binary files, UTF-8 string for text
+- \`'raw'\` - returns Buffer in JavaScript, bytes in Python (for direct byte access)
+- \`'text'\` - returns UTF-8 string
+- \`'binary'\` - returns base64 string
+
+### JavaScript - use await directly
+
+\`\`\`typescript
+new JavaScript("parse_csv", {
+  fn: async ({ csvFile }) => {
+    const file = csvFile.files[0];
+    const content = await file.readContentsAsync();
+    const headers = content.split("\\n")[0].split(",").map(h => h.trim());
+    return { fileName: file.name, headers };
+  }
+})
+
+// Binary file - use 'raw' mode for byte access
+new JavaScript("check_jpeg", {
+  fn: async ({ imageFile }) => {
+    const buf = await imageFile.files[0].readContentsAsync('raw'); // Buffer
+    const isJPEG = buf[0] === 0xFF && buf[1] === 0xD8 && buf[2] === 0xFF;
+    return { isJPEG };
+  }
+})
+\`\`\`
+
+### Python - use sync for single file, async for parallel
+
+\`\`\`python
+# Single file - use sync (simpler)
+content = file.readContents()
+rows = content.split('\\n')
+
+# Check file type by magic bytes
+raw = file.readContents('raw')
+is_pdf = raw[:4] == b'%PDF'
+
+# Multiple files in parallel - use async
+import asyncio
+async def fetch_all(files):
+    return await asyncio.gather(*[f.readContentsAsync() for f in files])
+contents = asyncio.run(fetch_all(files))
+\`\`\`
+
 ## Best Practices
 
 1. **Keep blocks focused** - One logical operation per block

package/dist/ai-service/skills/system/superblocks-api/references/code-blocks.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"code-blocks.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/code-blocks.generated.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwMtB,CAAC"}
+{"version":3,"file":"code-blocks.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/code-blocks.generated.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgQtB,CAAC"}

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.d.ts

@@ -1,2 +1,2 @@
-export declare const content = "# SQL Database Integrations\n\nReference documentation for working with SQL databases in Superblocks APIs.\n\n## Supported Databases\n\n- PostgreSQL, MySQL, MariaDB, MSSQL\n- Snowflake, Redshift, BigQuery\n- Databricks, SingleStore\n- CockroachDB, YugabyteDB\n\n## SQL Block Classes\n\n```typescript\n// Available SQL integrations\nimport {\n  PostgreSQL,\n  MySQL,\n  MariaDB,\n  MSSQL,\n  Snowflake,\n  Redshift,\n  BigQuery,\n  Databricks,\n  SingleStore,\n} from \"@superblocksteam/library\";\n```\n\n## Basic Usage\n\n```typescript\nnew PostgreSQL(\"get_users\", \"postgres-integration-id\", {\n  statement: \"SELECT * FROM users WHERE active = true LIMIT 100\"\n})\n```\n\n## Parameterized Queries\n\n**ALWAYS use parameterized queries for user input:**\n\n```typescript\n// \u2705 CORRECT - String interpolation for WHERE clauses\nnew PostgreSQL(\"search\", \"postgres-id\", {\n  statement: ({ searchTerm, limit }: { searchTerm: string; limit: number }) =>\n    `SELECT * FROM users WHERE name ILIKE '%${searchTerm}%' LIMIT ${limit}`\n})\n\n// \u2705 CORRECT - For INSERT statements\nnew PostgreSQL(\"insert_user\", \"postgres-id\", {\n  statement: ({ name, email }: { name: string; email: string }) =>\n    `INSERT INTO users (name, email) VALUES ('${name}', '${email}') RETURNING *`\n})\n```\n\n## Best Practices\n\n### 1. Use Meaningful Block Names\n\n```typescript\n// \u2705 GOOD\nnew PostgreSQL(\"fetch_active_users\", \"pg-id\", { ... })\nnew PostgreSQL(\"insert_order_item\", \"pg-id\", { ... })\n\n// \u274C BAD\nnew PostgreSQL(\"query1\", \"pg-id\", { ... })\nnew PostgreSQL(\"sql\", \"pg-id\", { ... })\n```\n\n### 2. Always Specify Columns\n\n```typescript\n// \u2705 PREFERRED - Explicit columns\nSELECT id, name, email, created_at FROM users\n\n// \u26A0\uFE0F AVOID - Select all\nSELECT * FROM users\n```\n\n### 3. Use LIMIT for Safety\n\n```typescript\n// \u2705 Always include LIMIT for queries that could return many rows\nSELECT * FROM orders LIMIT 1000\n```\n\n### 4. Handle NULL Values\n\n```typescript\n// \u2705 Use COALESCE for default values\nSELECT COALESCE(description, 'No description') as description FROM products\n\n// \u2705 Use IS NULL / IS NOT NULL\nSELECT * FROM users WHERE deleted_at IS NULL\n```\n\n## Database-Specific Notes\n\n### PostgreSQL\n\n```typescript\n// Array operations\nnew PostgreSQL(\"array_query\", \"pg-id\", {\n  statement: ({ tags }: { tags: string[] }) =>\n    `SELECT * FROM posts WHERE tags && ARRAY[${tags.map(t => `'${t}'`).join(',')}]`\n})\n\n// JSON operations\nnew PostgreSQL(\"json_query\", \"pg-id\", {\n  statement: \"SELECT data->>'name' as name FROM json_data\"\n})\n```\n\n### Snowflake\n\n```typescript\n// Use QUALIFY for window function filtering\nnew Snowflake(\"ranked_query\", \"snowflake-id\", {\n  statement: `\n    SELECT *, ROW_NUMBER() OVER (PARTITION BY category ORDER BY sales DESC) as rank\n    FROM products\n    QUALIFY rank <= 3\n  `\n})\n```\n\n### BigQuery\n\n```typescript\n// Use backticks for table names\nnew BigQuery(\"query\", \"bq-id\", {\n  statement: \"SELECT * FROM \\`project.dataset.table\\` LIMIT 100\"\n})\n```\n\n## Common Patterns\n\n### Pagination\n\n```typescript\nnew PostgreSQL(\"paginated_fetch\", \"pg-id\", {\n  statement: ({ page, pageSize }: { page: number; pageSize: number }) =>\n    `SELECT * FROM orders ORDER BY created_at DESC LIMIT ${pageSize} OFFSET ${(page - 1) * pageSize}`\n})\n```\n\n### Search with Multiple Conditions\n\n```typescript\nnew PostgreSQL(\"advanced_search\", \"pg-id\", {\n  statement: ({ name, status, minAmount }: { name?: string; status?: string; minAmount?: number }) => {\n    const conditions = [\"1=1\"];\n    if (name) conditions.push(`name ILIKE '%${name}%'`);\n    if (status) conditions.push(`status = '${status}'`);\n    if (minAmount !== undefined) conditions.push(`amount >= ${minAmount}`);\n    return `SELECT * FROM orders WHERE ${conditions.join(\" AND \")} LIMIT 100`;\n  }\n})\n```\n\n### Batch Insert\n\n```typescript\nnew PostgreSQL(\"batch_insert\", \"pg-id\", {\n  statement: ({ items }: { items: Array<{ name: string; value: number }> }) => {\n    const values = items\n      .map(item => `('${item.name}', ${item.value})`)\n      .join(\", \");\n    return `INSERT INTO items (name, value) VALUES ${values} RETURNING *`;\n  }\n})\n```\n\n### Upsert (Insert or Update)\n\n```typescript\n// PostgreSQL\nnew PostgreSQL(\"upsert_user\", \"pg-id\", {\n  statement: ({ id, name, email }: { id: string; name: string; email: string }) =>\n    `INSERT INTO users (id, name, email) \n     VALUES ('${id}', '${name}', '${email}')\n     ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, email = EXCLUDED.email\n     RETURNING *`\n})\n```\n\n## Error Handling\n\nSQL errors are returned in the block's output. Common errors:\n- Syntax errors in SQL\n- Table/column doesn't exist\n- Constraint violations\n- Connection timeouts\n\nFor critical operations, wrap in TryCatch:\n\n```typescript\nnew TryCatch(\"safe_delete\", {\n  try: [\n    new PostgreSQL(\"delete_record\", \"pg-id\", {\n      statement: ({ id }: { id: string }) => `DELETE FROM sensitive_data WHERE id = '${id}'`\n    })\n  ],\n  catch: [\n    new JavaScript(\"log_error\", {\n      fn: ({ deleteError }) => ({\n        success: false,\n        error: deleteError.value.message\n      })\n    })\n  ],\n  variables: { error: \"deleteError\" }\n})\n```\n";
+export declare const content = "# SQL Database Integrations\n\nReference documentation for working with SQL databases in Superblocks APIs.\n\n## Supported Databases\n\n- PostgreSQL, MySQL, MariaDB, MSSQL\n- Snowflake, Redshift, BigQuery, Athena\n- Databricks, SingleStore, Lakebase\n- CockroachDB, YugabyteDB, OracleDB\n\n## SQL Block Classes\n\n```typescript\n// Available SQL integrations\nimport {\n  PostgreSQL,\n  MySQL,\n  MariaDB,\n  MSSQL,\n  Snowflake,\n  Redshift,\n  BigQuery,\n  Athena,\n  Databricks,\n  SingleStore,\n  OracleDB,\n} from \"@superblocksteam/library\";\n```\n\n## Basic Usage\n\n```typescript\nnew PostgreSQL(\"get_users\", \"postgres-integration-id\", {\n  statement: \"SELECT * FROM users WHERE active = true LIMIT 100\"\n})\n```\n\n## Parameterized Queries\n\n### SQL Security Priority\n\n**ALWAYS prefer parameterized queries over string interpolation for user input values.**\n\nUse `parameters: \"[var1, var2]\"` with the database-specific SQL placeholders:\n\n| Database | Placeholder Syntax | Example |\n|----------|-------------------|---------|\n| PostgreSQL, Redshift, CockroachDB | `$1`, `$2`, `$3` | `WHERE id = $1 AND status = $2` |\n| MySQL, MariaDB, Snowflake, BigQuery, Athena | `?`, `?`, `?` | `WHERE id = ? AND status = ?` |\n| MSSQL | `@PARAM_1`, `@PARAM_2` | `WHERE id = @PARAM_1 AND status = @PARAM_2` |\n| Databricks | `:PARAM_1`, `:PARAM_2` | `WHERE id = :PARAM_1 AND status = :PARAM_2` |\n| OracleDB | `:1`, `:2`, `:3` | `WHERE id = :1 AND status = :2` |\n\nOnly use binding functions for truly dynamic SQL elements like table/column names.\n\n### Parameters Syntax vs Statement Syntax\n\n**Important:** `parameters` is a JavaScript expression string that gets evaluated directly. Do NOT use `${}` interpolation or binding functions.\n\n```typescript\n// \u274C WRONG - Don't use ${} interpolation in parameters\nparameters: \"[${build_query.output.userId}, ${searchTerm}]\"\n\n// \u274C WRONG - Don't use binding functions for parameters  \nparameters: ({ build_query }) => JSON.stringify(build_query.output.params)\n\n// \u2705 CORRECT - Write expressions directly (they get evaluated as JS)\nparameters: \"[build_query.output.userId, searchTerm, limit]\"\n\n// \u2705 CORRECT - Reference block output array directly\nparameters: \"build_query.output.params\"\n```\n\nThis is different from `statement`, where binding functions with `${}` ARE used to interpolate values into SQL.\n\n### String Interpolation (Alternative)\n\nFor simpler cases, string interpolation also works:\n\n```typescript\n// \u2705 CORRECT - String interpolation for WHERE clauses\nnew PostgreSQL(\"search\", \"postgres-id\", {\n  statement: ({ searchTerm, limit }: { searchTerm: string; limit: number }) =>\n    `SELECT * FROM users WHERE name ILIKE '%${searchTerm}%' LIMIT ${limit}`\n})\n\n// \u2705 CORRECT - For INSERT statements\nnew PostgreSQL(\"insert_user\", \"postgres-id\", {\n  statement: ({ name, email }: { name: string; email: string }) =>\n    `INSERT INTO users (name, email) VALUES ('${name}', '${email}') RETURNING *`\n})\n```\n\n### Dynamic SQL with Optional Filters\n\nUse the `parameters` array with the \"OR NULL\" pattern for optional filters:\n- `WHERE (column = $1 OR $1::type IS NULL)` makes the condition a no-op when parameter is null\n- Cast parameters to their type when checking for NULL (PostgreSQL can't infer types from NULL values)\n- Always pass all parameters, using null for unused filters\n- NEVER interpolate user values directly into SQL strings\n\n## Best Practices\n\n### 1. ONE Query Per Block Rule\n\nEach SQL block (PostgreSQL, Snowflake, MySQL, MicrosoftSql, Databricks) can execute **ONLY ONE SQL query**.\n\n\u274C **WRONG - Multiple queries in one block:**\n```sql\nUPDATE users SET status = 'active';\nDELETE FROM logs WHERE created < '2023-01-01';\nINSERT INTO audit VALUES ('done');\n```\n\n\u2705 **CORRECT - One query per block:**\n```typescript\nnew PostgreSQL(\"update_status\", \"postgres-id\", {\n  statement: \"UPDATE users SET status = 'active'\"\n}),\nnew PostgreSQL(\"clean_logs\", \"postgres-id\", {\n  statement: \"DELETE FROM logs WHERE created < '2023-01-01'\"\n})\n```\n\n### 2. Use Meaningful Block Names\n\n```typescript\n// \u2705 GOOD\nnew PostgreSQL(\"fetch_active_users\", \"pg-id\", { ... })\nnew PostgreSQL(\"insert_order_item\", \"pg-id\", { ... })\n\n// \u274C BAD\nnew PostgreSQL(\"query1\", \"pg-id\", { ... })\nnew PostgreSQL(\"sql\", \"pg-id\", { ... })\n```\n\n### 3. Always Specify Columns\n\n```typescript\n// \u2705 PREFERRED - Explicit columns\nSELECT id, name, email, created_at FROM users\n\n// \u26A0\uFE0F AVOID - Select all\nSELECT * FROM users\n```\n\n### 4. Always Add Defensive Row Limits\n\nAlways include a row limit clause to prevent runaway queries. Use 100 as the default unless user specifies otherwise.\n\nDifferent SQL dialects have different syntax:\n- **MySQL/PostgreSQL/SQLite**: `LIMIT N`\n- **SQL Server**: `SELECT TOP N`\n- **ANSI SQL (SQL Server, Oracle, DB2)**: `OFFSET 0 ROWS FETCH NEXT N ROWS ONLY`\n\n```sql\n-- \u2705 PostgreSQL/MySQL\nSELECT * FROM orders ORDER BY created_at DESC LIMIT 100;\n\n-- \u2705 SQL Server\nSELECT TOP 100 * FROM orders ORDER BY created_at DESC;\n\n-- \u2705 ANSI SQL (SQL Server with ORDER BY)\nSELECT * FROM orders ORDER BY created_at DESC OFFSET 0 ROWS FETCH NEXT 100 ROWS ONLY;\n\n-- \u274C Avoid unlimited queries\nSELECT * FROM orders ORDER BY created_at DESC;  -- Can timeout or crash\n```\n\n### 5. Sort, Don't Filter by Date (Default)\n\nDo NOT add automatic date filters (e.g., \"last 90 days\") unless the user explicitly requests them. This is a common cause of unexpected empty SQL results.\n\n```sql\n-- \u2705 Default approach\nSELECT * FROM orders ORDER BY created_at DESC LIMIT 100;\n\n-- \u274C Avoid automatic filtering\nSELECT * FROM orders WHERE created_at >= CURRENT_DATE - INTERVAL '90 days';  -- Can return empty results\n```\n\nOnly add date WHERE clauses when users explicitly ask for time-based filtering.\n\n### 6. Handle NULL Values\n\n```typescript\n// \u2705 Use COALESCE for default values\nSELECT COALESCE(description, 'No description') as description FROM products\n\n// \u2705 Use IS NULL / IS NOT NULL\nSELECT * FROM users WHERE deleted_at IS NULL\n```\n\n## Database-Specific Notes\n\n### PostgreSQL\n\n```typescript\n// Array operations\nnew PostgreSQL(\"array_query\", \"pg-id\", {\n  statement: ({ tags }: { tags: string[] }) =>\n    `SELECT * FROM posts WHERE tags && ARRAY[${tags.map(t => `'${t}'`).join(',')}]`\n})\n\n// JSON operations\nnew PostgreSQL(\"json_query\", \"pg-id\", {\n  statement: \"SELECT data->>'name' as name FROM json_data\"\n})\n```\n\n- Use schema-qualified names: `schema.table` or `\"schema\".\"table\"`\n- Case sensitivity: Unquoted identifiers are lowercase\n- Use `::type` for type casting\n\n### Snowflake\n\n```typescript\n// Use QUALIFY for window function filtering\nnew Snowflake(\"ranked_query\", \"snowflake-id\", {\n  statement: `\n    SELECT *, ROW_NUMBER() OVER (PARTITION BY category ORDER BY sales DESC) as rank\n    FROM products\n    QUALIFY rank <= 3\n  `\n})\n```\n\n**Snowflake Two-Part Naming:** Snowflake uses `schema.table`\n\nWhen you see Snowflake metadata where tables have a `schema` property, **you MUST qualify table names**:\n\n```sql\n-- If table has schema property \"MASTERDATA\"\nSELECT * FROM MASTERDATA.PRODUCTLINE  -- \u2705 Fully qualified\nSELECT * FROM PRODUCTLINE             -- \u274C Will fail if no default schema\n```\n\n**Rule**: If a table object has a non-empty `schema` property, use `{schema}.{name}` format in your SQL queries.\n\n### Databricks\n\n**Databricks Three-Part Naming:** Databricks uses `catalog.schema.table`\n\nWhen you see Databricks metadata like:\n- `uber.default.orders` - Use the FULL path: `uber.default.orders`\n- `production.analytics.users` - Use: `production.analytics.users`\n\n```sql\n-- Metadata shows: uber.default.orders\nSELECT * FROM uber.default.orders     -- \u2705 Full path\nSELECT * FROM uber.orders            -- \u274C Missing schema part\nSELECT * FROM orders                 -- \u274C Missing catalog and schema\n```\n\n**Note:** The word \"default\" in Databricks paths is NOT optional - it's the actual schema name. Always include all three parts exactly as shown in the metadata.\n\n### BigQuery\n\n```typescript\n// Use backticks for table names\nnew BigQuery(\"query\", \"bq-id\", {\n  statement: \"SELECT * FROM \\`project.dataset.table\\` LIMIT 100\"\n})\n```\n\n## Common Patterns\n\n### Pagination\n\n```typescript\nnew PostgreSQL(\"paginated_fetch\", \"pg-id\", {\n  statement: ({ page, pageSize }: { page: number; pageSize: number }) =>\n    `SELECT * FROM orders ORDER BY created_at DESC LIMIT ${pageSize} OFFSET ${(page - 1) * pageSize}`\n})\n```\n\n### Search with Multiple Conditions\n\n```typescript\nnew PostgreSQL(\"advanced_search\", \"pg-id\", {\n  statement: ({ name, status, minAmount }: { name?: string; status?: string; minAmount?: number }) => {\n    const conditions = [\"1=1\"];\n    if (name) conditions.push(`name ILIKE '%${name}%'`);\n    if (status) conditions.push(`status = '${status}'`);\n    if (minAmount !== undefined) conditions.push(`amount >= ${minAmount}`);\n    return `SELECT * FROM orders WHERE ${conditions.join(\" AND \")} LIMIT 100`;\n  }\n})\n```\n\n### Batch Insert\n\n```typescript\nnew PostgreSQL(\"batch_insert\", \"pg-id\", {\n  statement: ({ items }: { items: Array<{ name: string; value: number }> }) => {\n    const values = items\n      .map(item => `('${item.name}', ${item.value})`)\n      .join(\", \");\n    return `INSERT INTO items (name, value) VALUES ${values} RETURNING *`;\n  }\n})\n```\n\n### Upsert (Insert or Update)\n\n```typescript\n// PostgreSQL\nnew PostgreSQL(\"upsert_user\", \"pg-id\", {\n  statement: ({ id, name, email }: { id: string; name: string; email: string }) =>\n    `INSERT INTO users (id, name, email) \n     VALUES ('${id}', '${name}', '${email}')\n     ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, email = EXCLUDED.email\n     RETURNING *`\n})\n```\n\n## Error Handling\n\nSQL errors are returned in the block's output. Common errors:\n- Syntax errors in SQL\n- Table/column doesn't exist\n- Constraint violations\n- Connection timeouts\n\nFor critical operations, wrap in TryCatch:\n\n```typescript\nnew TryCatch(\"safe_delete\", {\n  try: [\n    new PostgreSQL(\"delete_record\", \"pg-id\", {\n      statement: ({ id }: { id: string }) => `DELETE FROM sensitive_data WHERE id = '${id}'`\n    })\n  ],\n  catch: [\n    new JavaScript(\"log_error\", {\n      fn: ({ deleteError }) => ({\n        success: false,\n        error: deleteError.value.message\n      })\n    })\n  ],\n  variables: { error: \"deleteError\" }\n})\n```\n";
 //# sourceMappingURL=sql-databases.generated.d.ts.map

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-databases.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/sql-databases.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,4wKAqNnB,CAAC"}
+{"version":3,"file":"sql-databases.generated.d.ts","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/sql-databases.generated.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,w+UAyVnB,CAAC"}

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.js

@@ -7,9 +7,9 @@ Reference documentation for working with SQL databases in Superblocks APIs.
 ## Supported Databases
 
 - PostgreSQL, MySQL, MariaDB, MSSQL
-- Snowflake, Redshift, BigQuery
-- Databricks, SingleStore
-- CockroachDB, YugabyteDB
+- Snowflake, Redshift, BigQuery, Athena
+- Databricks, SingleStore, Lakebase
+- CockroachDB, YugabyteDB, OracleDB
 
 ## SQL Block Classes
 
@@ -23,8 +23,10 @@ import {
   Snowflake,
   Redshift,
   BigQuery,
+  Athena,
   Databricks,
   SingleStore,
+  OracleDB,
 } from "@superblocksteam/library";
 \`\`\`
 
@@ -38,7 +40,45 @@ new PostgreSQL("get_users", "postgres-integration-id", {
 
 ## Parameterized Queries
 
-**ALWAYS use parameterized queries for user input:**
+### SQL Security Priority
+
+**ALWAYS prefer parameterized queries over string interpolation for user input values.**
+
+Use \`parameters: "[var1, var2]"\` with the database-specific SQL placeholders:
+
+| Database | Placeholder Syntax | Example |
+|----------|-------------------|---------|
+| PostgreSQL, Redshift, CockroachDB | \`$1\`, \`$2\`, \`$3\` | \`WHERE id = $1 AND status = $2\` |
+| MySQL, MariaDB, Snowflake, BigQuery, Athena | \`?\`, \`?\`, \`?\` | \`WHERE id = ? AND status = ?\` |
+| MSSQL | \`@PARAM_1\`, \`@PARAM_2\` | \`WHERE id = @PARAM_1 AND status = @PARAM_2\` |
+| Databricks | \`:PARAM_1\`, \`:PARAM_2\` | \`WHERE id = :PARAM_1 AND status = :PARAM_2\` |
+| OracleDB | \`:1\`, \`:2\`, \`:3\` | \`WHERE id = :1 AND status = :2\` |
+
+Only use binding functions for truly dynamic SQL elements like table/column names.
+
+### Parameters Syntax vs Statement Syntax
+
+**Important:** \`parameters\` is a JavaScript expression string that gets evaluated directly. Do NOT use \`\${}\` interpolation or binding functions.
+
+\`\`\`typescript
+// ❌ WRONG - Don't use \${} interpolation in parameters
+parameters: "[\${build_query.output.userId}, \${searchTerm}]"
+
+// ❌ WRONG - Don't use binding functions for parameters  
+parameters: ({ build_query }) => JSON.stringify(build_query.output.params)
+
+// ✅ CORRECT - Write expressions directly (they get evaluated as JS)
+parameters: "[build_query.output.userId, searchTerm, limit]"
+
+// ✅ CORRECT - Reference block output array directly
+parameters: "build_query.output.params"
+\`\`\`
+
+This is different from \`statement\`, where binding functions with \`\${}\` ARE used to interpolate values into SQL.
+
+### String Interpolation (Alternative)
+
+For simpler cases, string interpolation also works:
 
 \`\`\`typescript
 // ✅ CORRECT - String interpolation for WHERE clauses
@@ -54,9 +94,38 @@ new PostgreSQL("insert_user", "postgres-id", {
 })
 \`\`\`
 
+### Dynamic SQL with Optional Filters
+
+Use the \`parameters\` array with the "OR NULL" pattern for optional filters:
+- \`WHERE (column = $1 OR $1::type IS NULL)\` makes the condition a no-op when parameter is null
+- Cast parameters to their type when checking for NULL (PostgreSQL can't infer types from NULL values)
+- Always pass all parameters, using null for unused filters
+- NEVER interpolate user values directly into SQL strings
+
 ## Best Practices
 
-### 1. Use Meaningful Block Names
+### 1. ONE Query Per Block Rule
+
+Each SQL block (PostgreSQL, Snowflake, MySQL, MicrosoftSql, Databricks) can execute **ONLY ONE SQL query**.
+
+❌ **WRONG - Multiple queries in one block:**
+\`\`\`sql
+UPDATE users SET status = 'active';
+DELETE FROM logs WHERE created < '2023-01-01';
+INSERT INTO audit VALUES ('done');
+\`\`\`
+
+✅ **CORRECT - One query per block:**
+\`\`\`typescript
+new PostgreSQL("update_status", "postgres-id", {
+  statement: "UPDATE users SET status = 'active'"
+}),
+new PostgreSQL("clean_logs", "postgres-id", {
+  statement: "DELETE FROM logs WHERE created < '2023-01-01'"
+})
+\`\`\`
+
+### 2. Use Meaningful Block Names
 
 \`\`\`typescript
 // ✅ GOOD
@@ -68,7 +137,7 @@ new PostgreSQL("query1", "pg-id", { ... })
 new PostgreSQL("sql", "pg-id", { ... })
 \`\`\`
 
-### 2. Always Specify Columns
+### 3. Always Specify Columns
 
 \`\`\`typescript
 // ✅ PREFERRED - Explicit columns
@@ -78,14 +147,44 @@ SELECT id, name, email, created_at FROM users
 SELECT * FROM users
 \`\`\`
 
-### 3. Use LIMIT for Safety
+### 4. Always Add Defensive Row Limits
 
-\`\`\`typescript
-// ✅ Always include LIMIT for queries that could return many rows
-SELECT * FROM orders LIMIT 1000
+Always include a row limit clause to prevent runaway queries. Use 100 as the default unless user specifies otherwise.
+
+Different SQL dialects have different syntax:
+- **MySQL/PostgreSQL/SQLite**: \`LIMIT N\`
+- **SQL Server**: \`SELECT TOP N\`
+- **ANSI SQL (SQL Server, Oracle, DB2)**: \`OFFSET 0 ROWS FETCH NEXT N ROWS ONLY\`
+
+\`\`\`sql
+-- ✅ PostgreSQL/MySQL
+SELECT * FROM orders ORDER BY created_at DESC LIMIT 100;
+
+-- ✅ SQL Server
+SELECT TOP 100 * FROM orders ORDER BY created_at DESC;
+
+-- ✅ ANSI SQL (SQL Server with ORDER BY)
+SELECT * FROM orders ORDER BY created_at DESC OFFSET 0 ROWS FETCH NEXT 100 ROWS ONLY;
+
+-- ❌ Avoid unlimited queries
+SELECT * FROM orders ORDER BY created_at DESC;  -- Can timeout or crash
 \`\`\`
 
-### 4. Handle NULL Values
+### 5. Sort, Don't Filter by Date (Default)
+
+Do NOT add automatic date filters (e.g., "last 90 days") unless the user explicitly requests them. This is a common cause of unexpected empty SQL results.
+
+\`\`\`sql
+-- ✅ Default approach
+SELECT * FROM orders ORDER BY created_at DESC LIMIT 100;
+
+-- ❌ Avoid automatic filtering
+SELECT * FROM orders WHERE created_at >= CURRENT_DATE - INTERVAL '90 days';  -- Can return empty results
+\`\`\`
+
+Only add date WHERE clauses when users explicitly ask for time-based filtering.
+
+### 6. Handle NULL Values
 
 \`\`\`typescript
 // ✅ Use COALESCE for default values
@@ -112,6 +211,10 @@ new PostgreSQL("json_query", "pg-id", {
 })
 \`\`\`
 
+- Use schema-qualified names: \`schema.table\` or \`"schema"."table"\`
+- Case sensitivity: Unquoted identifiers are lowercase
+- Use \`::type\` for type casting
+
 ### Snowflake
 
 \`\`\`typescript
@@ -125,6 +228,35 @@ new Snowflake("ranked_query", "snowflake-id", {
 })
 \`\`\`
 
+**Snowflake Two-Part Naming:** Snowflake uses \`schema.table\`
+
+When you see Snowflake metadata where tables have a \`schema\` property, **you MUST qualify table names**:
+
+\`\`\`sql
+-- If table has schema property "MASTERDATA"
+SELECT * FROM MASTERDATA.PRODUCTLINE  -- ✅ Fully qualified
+SELECT * FROM PRODUCTLINE             -- ❌ Will fail if no default schema
+\`\`\`
+
+**Rule**: If a table object has a non-empty \`schema\` property, use \`{schema}.{name}\` format in your SQL queries.
+
+### Databricks
+
+**Databricks Three-Part Naming:** Databricks uses \`catalog.schema.table\`
+
+When you see Databricks metadata like:
+- \`uber.default.orders\` - Use the FULL path: \`uber.default.orders\`
+- \`production.analytics.users\` - Use: \`production.analytics.users\`
+
+\`\`\`sql
+-- Metadata shows: uber.default.orders
+SELECT * FROM uber.default.orders     -- ✅ Full path
+SELECT * FROM uber.orders            -- ❌ Missing schema part
+SELECT * FROM orders                 -- ❌ Missing catalog and schema
+\`\`\`
+
+**Note:** The word "default" in Databricks paths is NOT optional - it's the actual schema name. Always include all three parts exactly as shown in the metadata.
+
 ### BigQuery
 
 \`\`\`typescript

package/dist/ai-service/skills/system/superblocks-api/references/sql-databases.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"sql-databases.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/sql-databases.generated.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqNtB,CAAC"}
+{"version":3,"file":"sql-databases.generated.js","sourceRoot":"","sources":["../../../../../../src/ai-service/skills/system/superblocks-api/references/sql-databases.generated.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,mDAAmD;AAEnD,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyVtB,CAAC"}