@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/plan.md

@@ -0,0 +1,192 @@
+# XanoScript AI Documentation v2 - Implementation Plan
+
+## Design Principles
+
+### AI-First Documentation Goals
+1. **Scannable** - AI can quickly locate relevant syntax/patterns
+2. **Self-contained** - Each doc has everything needed for its topic
+3. **Pattern-consistent** - Identical structure across all docs
+4. **Minimal but complete** - Not verbose, but covers all cases
+5. **Examples inline** - Code immediately follows syntax it demonstrates
+
+### Document Structure Template
+Every doc follows this structure:
+```
+---
+applyTo: "<glob pattern>"
+---
+
+# <Topic>
+
+## Quick Reference
+<Table or code block with syntax summary>
+
+## Overview
+<1-2 paragraph explanation>
+
+## <Concept 1>
+### Syntax
+### Example
+### Notes
+
+## <Concept 2>
+...
+
+## Best Practices
+<Bullet list>
+
+## Common Patterns
+<Real-world usage patterns>
+```
+
+---
+
+## Proposed File Structure
+
+### Core (Required for any XanoScript work)
+| File | Purpose | Source Files |
+|------|---------|--------------|
+| `README.md` | Overview, workspace structure, getting started | README.md, workspace.md |
+| `syntax.md` | Expressions, operators, filters | expression_guideline.md, query_filter.md |
+| `types.md` | Data types, input blocks, validation | input_guideline.md, functions.md (input section) |
+
+### Primary Constructs
+| File | Purpose | Source Files |
+|------|---------|--------------|
+| `tables.md` | Database schemas, indexes, relationships | table_guideline.md, table_examples.md |
+| `functions.md` | Reusable function stacks | function_guideline.md, function_examples.md |
+| `apis.md` | HTTP API endpoints | api_query_guideline.md, api_query_examples.md |
+| `tasks.md` | Scheduled jobs | task_guideline.md, task_examples.md |
+| `database.md` | All db.* operations | db_query_guideline.md, functions.md (db section) |
+
+### AI Integration
+| File | Purpose | Source Files |
+|------|---------|--------------|
+| `agents.md` | AI agents, LLM providers | agent_guideline.md, agent_examples.md |
+| `tools.md` | AI tools for agents/MCP | tool_guideline.md, tool_examples.md |
+| `mcp-servers.md` | MCP server configuration | mcp_server_guideline.md, mcp_server_examples.md |
+
+### Advanced Features
+| File | Purpose | Source Files |
+|------|---------|--------------|
+| `testing.md` | Unit tests, mocks, assertions | unit_testing_guideline.md |
+| `integrations.md` | Cloud, Redis, storage, security | functions.md (cloud/redis/security sections) |
+| `frontend.md` | Static frontend, Lovable migration | frontend_guideline.md, build_from_lovable.md |
+| `ephemeral.md` | Ephemeral services and jobs | ephemeral_environment_guideline.md |
+
+### Reference (Optional)
+| File | Purpose | Source Files |
+|------|---------|--------------|
+| `tips.md` | Tips, tricks, gotchas | tips_and_tricks.md |
+
+---
+
+## Content Reduction Strategy
+
+### V1 Verbosity Issues
+1. **Redundant examples** - Multiple examples showing same pattern
+2. **Explanation repetition** - Same concept explained in guideline AND examples
+3. **Over-commented code** - Examples have excessive inline comments
+4. **Separate files** - guideline.md + examples.md = duplication
+
+### V2 Approach
+1. **One canonical example** per feature (not 3-5)
+2. **Table-based syntax reference** - Quick scan, no prose
+3. **Inline examples** - Example immediately after syntax
+4. **Comments only for non-obvious** - Trust the reader
+
+### Example Transformation
+
+**V1 Style (verbose):**
+```xs
+// This function calculates the total cost
+// by multiplying quantity by price per item
+// and returns the result
+function "maths/calculate_total" {
+  description = "Calculate the total cost based on quantity and price per item"
+
+  input {
+    int quantity filters=min:0 {
+      description = "Number of items"
+    }
+
+    decimal price_per_item filters=min:0.01 {
+      description = "Price for each item"
+    }
+  }
+
+  stack {
+    var $total {
+      value = 0
+      description = "Initialize total"
+    }
+
+    math.add $total {
+      value = $input.quantity * $input.price_per_item
+      description = "Calculate total"
+    }
+  }
+
+  response = $total
+}
+```
+
+**V2 Style (minimal):**
+```xs
+function "calculate_total" {
+  input {
+    int quantity filters=min:0
+    decimal price filters=min:0.01
+  }
+  stack {
+    var $total { value = $input.quantity * $input.price }
+  }
+  response = $total
+}
+```
+
+---
+
+## Estimated Reduction
+
+| Metric | V1 | V2 Target | Reduction |
+|--------|-----|-----------|-----------|
+| Files | 27 | 14 | ~48% |
+| Total Lines | ~5000 | ~2000 | ~60% |
+| Avg File Size | 185 lines | 140 lines | ~25% |
+
+---
+
+## Implementation Order
+
+### Phase 1: Foundation
+1. README.md - Workspace overview
+2. syntax.md - All expressions and filters
+3. types.md - Data types and inputs
+
+### Phase 2: Core Constructs
+4. tables.md - Database tables
+5. functions.md - Functions
+6. apis.md - API endpoints
+7. tasks.md - Scheduled tasks
+8. database.md - DB operations
+
+### Phase 3: AI Features
+9. agents.md - AI agents
+10. tools.md - AI tools
+11. mcp-servers.md - MCP servers
+
+### Phase 4: Advanced
+12. testing.md - Unit testing
+13. integrations.md - Cloud/Redis/Security
+14. frontend.md - Frontend + Lovable
+15. ephemeral.md - Ephemeral environments
+
+---
+
+## Questions Resolved
+
+- [x] Structure: Consolidated (single file per concept)
+- [x] Examples: Minimal (just enough to demonstrate)
+- [x] Quick Reference: Yes (syntax cheatsheets at top)
+- [x] Scope: Complete coverage (all features)

package/xanoscript_docs/syntax.md

@@ -0,0 +1,314 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Syntax Reference
+
+Complete reference for XanoScript expressions, operators, and filters.
+
+## Quick Reference
+
+### Operators
+| Category | Operators |
+|----------|-----------|
+| Comparison | `==`, `!=`, `>`, `<`, `>=`, `<=` |
+| Logical | `&&`, `||`, `!` |
+| Math | `+`, `-`, `*`, `/`, `%` |
+| String | `~` (concat) |
+| Null-safe | `==?`, `!=?`, `>=?`, `<=?` (ignore if null) |
+
+### Common Filters
+| Filter | Purpose | Example |
+|--------|---------|---------|
+| `trim` | Remove whitespace | `$s\|trim` |
+| `lower` / `upper` | Case conversion | `$s\|to_lower` |
+| `first` / `last` | Array endpoints | `$arr\|first` |
+| `count` | Array/object length | `$arr\|count` |
+| `get` | Object property | `$obj\|get:"key"` |
+| `set` | Set property | `$obj\|set:"key":"val"` |
+| `json_encode` / `json_decode` | JSON conversion | `$obj\|json_encode` |
+
+---
+
+## Expressions
+
+Expressions are wrapped in backticks for evaluation:
+
+```xs
+conditional {
+  if (`$input.age >= 18`) { ... }
+}
+
+var $total { value = `$input.qty * $input.price` }
+```
+
+### Comparison
+```xs
+$a == $b      # Equal
+$a != $b      # Not equal
+$a > $b       # Greater than
+$a >= $b      # Greater or equal
+$a < $b       # Less than
+$a <= $b      # Less or equal
+```
+
+### Logical
+```xs
+$a && $b      # AND
+$a || $b      # OR
+!$a           # NOT
+```
+
+### Null-Safe Comparisons (DB Queries)
+```xs
+# In db.query where clauses - ignore condition if value is null
+$db.post.category ==? $input.category
+$db.post.date >=? $input.start_date
+```
+
+---
+
+## Math Filters
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `add` | `10\|add:5` | `15` |
+| `subtract` | `10\|subtract:3` | `7` |
+| `multiply` | `10\|multiply:2` | `20` |
+| `divide` | `10\|divide:2` | `5` |
+| `modulus` | `10\|modulus:3` | `1` |
+| `floor` | `2.7\|floor` | `2` |
+| `ceil` | `2.3\|ceil` | `3` |
+| `round` | `2.567\|round:2` | `2.57` |
+| `abs` | `-5\|abs` | `5` |
+| `sqrt` | `9\|sqrt` | `3` |
+| `pow` | `2\|pow:3` | `8` |
+| `min` | `5\|min:3` | `3` |
+| `max` | `5\|max:10` | `10` |
+
+### Array Math
+```xs
+[1,2,3,4]|sum        # 10
+[1,2,3,4]|avg        # 2.5
+[1,2,3,4]|product    # 24
+[5,2,8,1]|array_min  # 1
+[5,2,8,1]|array_max  # 8
+```
+
+### Trigonometry
+`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `deg2rad`, `rad2deg`
+
+---
+
+## String Filters
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `trim` | `"  hi  "\|trim` | `"hi"` |
+| `ltrim` / `rtrim` | `"  hi"\|ltrim` | `"hi"` |
+| `to_lower` | `"Hi"\|to_lower` | `"hi"` |
+| `to_upper` | `"Hi"\|to_upper` | `"HI"` |
+| `capitalize` | `"hi there"\|capitalize` | `"Hi There"` |
+| `strlen` | `"hello"\|strlen` | `5` |
+| `substr` | `"hello"\|substr:1:3` | `"ell"` |
+| `split` | `"a,b,c"\|split:","` | `["a","b","c"]` |
+| `replace` | `"hello"\|replace:"l":"x"` | `"hexxo"` |
+| `contains` | `"hello"\|contains:"ell"` | `true` |
+| `starts_with` | `"hello"\|starts_with:"he"` | `true` |
+| `ends_with` | `"hello"\|ends_with:"lo"` | `true` |
+| `concat` | `"a"\|concat:"b":"-"` | `"a-b"` |
+
+### Case-Insensitive Variants
+`icontains`, `istarts_with`, `iends_with`, `iindex`
+
+### Regex
+```xs
+"/pattern/"|regex_matches:"subject"           # Boolean match
+"/(\w+)/"|regex_get_first_match:"test"        # First match
+"/\w+/"|regex_get_all_matches:"a b c"         # All matches
+"/\s+/"|regex_replace:"-":"a  b"              # Replace: "a-b"
+```
+
+---
+
+## Array Filters
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `first` | `[1,2,3]\|first` | `1` |
+| `last` | `[1,2,3]\|last` | `3` |
+| `count` | `[1,2,3]\|count` | `3` |
+| `reverse` | `[1,2,3]\|reverse` | `[3,2,1]` |
+| `unique` | `[1,1,2]\|unique` | `[1,2]` |
+| `flatten` | `[[1,2],[3]]\|flatten` | `[1,2,3]` |
+| `shuffle` | `[1,2,3]\|shuffle` | Random order |
+| `slice` | `[1,2,3,4]\|slice:1:2` | `[2,3]` |
+| `push` | `[1,2]\|push:3` | `[1,2,3]` |
+| `pop` | `[1,2,3]\|pop` | `3` |
+| `shift` | `[1,2,3]\|shift` | `1` |
+| `unshift` | `[1,2]\|unshift:0` | `[0,1,2]` |
+| `merge` | `[1,2]\|merge:[3,4]` | `[1,2,3,4]` |
+| `diff` | `[1,2,3]\|diff:[2]` | `[1,3]` |
+| `intersect` | `[1,2,3]\|intersect:[2,3,4]` | `[2,3]` |
+| `join` | `["a","b"]\|join:","` | `"a,b"` |
+| `range` | `\|range:1:5` | `[1,2,3,4,5]` |
+
+### Functional Operations
+```xs
+# Map - transform each element
+[{v:1},{v:2}]|map:$$.v*2                    # [2,4]
+
+# Filter - keep matching elements
+[1,2,3,4]|filter:$$%2==0                    # [2,4]
+
+# Find - first matching element
+[{id:1},{id:2}]|find:$$.id==2               # {id:2}
+
+# FindIndex - index of first match
+[{id:1},{id:2}]|findIndex:$$.id==2          # 1
+
+# Some - any element matches?
+[1,2,3]|some:$$>2                           # true
+
+# Every - all elements match?
+[2,4,6]|every:$$%2==0                       # true
+
+# Reduce - accumulate to single value
+[1,2,3,4]|reduce:$$+$result:0               # 10
+```
+
+### Grouping & Indexing
+```xs
+# Group by property
+[{g:"a",v:1},{g:"b",v:2},{g:"a",v:3}]|index_by:g
+# {"a":[{g:"a",v:1},{g:"a",v:3}],"b":[{g:"b",v:2}]}
+
+# Sort
+[{n:"z"},{n:"a"}]|sort:n:text:false         # Ascending by n
+```
+
+---
+
+## Object Filters
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `get` | `{a:1}\|get:"a"` | `1` |
+| `set` | `{a:1}\|set:"b":2` | `{a:1,b:2}` |
+| `unset` | `{a:1,b:2}\|unset:"b"` | `{a:1}` |
+| `has` | `{a:1}\|has:"a"` | `true` |
+| `keys` | `{a:1,b:2}\|keys` | `["a","b"]` |
+| `values` | `{a:1,b:2}\|values` | `[1,2]` |
+| `entries` | `{a:1}\|entries` | `[{key:"a",value:1}]` |
+| `pick` | `{a:1,b:2,c:3}\|pick:[a,c]` | `{a:1,c:3}` |
+| `unpick` | `{a:1,b:2,c:3}\|unpick:[b]` | `{a:1,c:3}` |
+
+### Conditional Set
+```xs
+{a:1}|set_conditional:"b":2:true            # {a:1,b:2} if condition true
+{a:1}|set_ifnotempty:"b":"val"              # Set only if val not empty
+{a:1}|set_ifnotnull:"b":$var                # Set only if $var not null
+```
+
+---
+
+## Type Filters
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `to_int` | `"123"\|to_int` | `123` |
+| `to_decimal` | `"1.5"\|to_decimal` | `1.5` |
+| `to_text` | `123\|to_text` | `"123"` |
+| `to_bool` | `"true"\|to_bool` | `true` |
+| `is_null` | `null\|is_null` | `true` |
+| `is_empty` | `[]\|is_empty` | `true` |
+| `is_array` | `[1]\|is_array` | `true` |
+| `is_object` | `{}\|is_object` | `true` |
+| `is_int` | `1\|is_int` | `true` |
+| `is_text` | `"a"\|is_text` | `true` |
+
+### Null Handling
+```xs
+null|first_notnull:0                        # 0
+""|first_notempty:"default"                 # "default"
+```
+
+---
+
+## Date/Time Filters
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `to_timestamp` | `"now"\|to_timestamp` | Parse to timestamp |
+| `to_ms` | `"now"\|to_ms` | Milliseconds since epoch |
+| `to_seconds` | `"now"\|to_seconds` | Seconds since epoch |
+| `format_timestamp` | `$ts\|format_timestamp:"Y-m-d":"UTC"` | Format timestamp |
+| `transform_timestamp` | `$ts\|transform_timestamp:"-7 days"` | Relative time |
+| `add_secs_to_timestamp` | `$ts\|add_secs_to_timestamp:60` | Add seconds |
+| `add_ms_to_timestamp` | `$ts\|add_ms_to_timestamp:1000` | Add milliseconds |
+
+### Timestamp Parts
+```xs
+$ts|timestamp_year           # Year
+$ts|timestamp_month          # Month (1-12)
+$ts|timestamp_day_of_month   # Day (1-31)
+$ts|timestamp_hour           # Hour (0-23)
+$ts|timestamp_minute         # Minute (0-59)
+$ts|timestamp_day_of_week    # Day (0=Sunday)
+```
+
+---
+
+## Encoding Filters
+
+| Filter | Example |
+|--------|---------|
+| `json_encode` | `{a:1}\|json_encode` |
+| `json_decode` | `'{"a":1}'\|json_decode` |
+| `base64_encode` | `"hello"\|base64_encode` |
+| `base64_decode` | `"aGVsbG8="\|base64_decode` |
+| `url_encode` | `"a b"\|url_encode` |
+| `url_decode` | `"a%20b"\|url_decode` |
+| `xml_decode` | `"<a>1</a>"\|xml_decode` |
+| `yaml_encode` / `yaml_decode` | YAML conversion |
+| `hex2bin` / `bin2hex` | Hex conversion |
+
+---
+
+## Security Filters
+
+| Filter | Example |
+|--------|---------|
+| `md5` | `"text"\|md5` |
+| `sha1` / `sha256` / `sha512` | Hash functions |
+| `hmac_sha256` | `"msg"\|hmac_sha256:"key"` |
+| `encrypt` | `"data"\|encrypt:"aes-256-cbc":"key":"iv"` |
+| `decrypt` | `$enc\|decrypt:"aes-256-cbc":"key":"iv"` |
+| `jws_encode` / `jws_decode` | JWT signing |
+| `jwe_encode` / `jwe_decode` | JWT encryption |
+| `secureid_encode` / `secureid_decode` | ID obfuscation |
+| `uuid` | `\|uuid` |
+
+---
+
+## DB Query Filters
+
+Used in `db.query` where clauses:
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `contains` | `$db.tags\|contains:"featured"` | Array contains value |
+| `includes` | `$db.title\|includes:"tutorial"` | String includes text |
+| `overlaps` | `$db.tags\|overlaps:["a","b"]` | Arrays share elements |
+| `between` | `$db.price\|between:10:100` | Value in range |
+| `within` | `$db.geo\|within:$point:1000` | Geo within radius (meters) |
+| `distance` | `$db.geo\|distance:$point` | Geo distance (meters) |
+| `search_rank` | `$db.content\|search_rank:"query"` | Full-text search ranking |
+| `cosine_similarity` | `$db.vector\|cosine_similarity:$vec` | Vector similarity |
+| `l2_distance_euclidean` | `$db.vector\|l2_distance_euclidean:$vec` | Vector distance |
+
+### Timestamp Arithmetic (DB)
+```xs
+$db.created_at|timestamp_add_days:7
+$db.created_at|timestamp_subtract_hours:24
+```