@xano/xanoscript-language-server 11.0.6 → 11.1.0

package/CLAUDE.md

@@ -30,12 +30,14 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 ### Core Components
 
 **Lexer (`lexer/`)**: Token definitions and lexical analysis
+
 - `tokens.js` - Main token registry
 - `lexer.js` - Chevrotain lexer implementation
 - Domain tokens: `api.js`, `db.js`, `cloud.js`, `function.js`, etc.
 - `utils.js` - Token creation utilities (`createToken`, `createTokenByName`)
 
 **Parser (`parser/`)**: Grammar rules and parsing logic
+
 - `base_parser.js` - Core XanoBaseParser extending Chevrotain
 - Main parsers: `query_parser.js`, `function_parser.js`, `task_parser.js`, `api_group_parser.js`, `table_parser.js`, `workflow_test_parser.js`, `table_trigger_parser.js`
 - `attributes/` - Field attributes (description, disabled, sensitive)
@@ -45,6 +47,7 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 - `generic/` - Reusable parsing components
 
 **Language Server (`server.js` + feature directories)**:
+
 - `onCompletion/` - Auto-completion logic
 - `onDidChangeContent/` - Live diagnostics and error reporting
 - `onHover/` - Documentation and hover information
@@ -53,6 +56,7 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 ### XanoScript Object Types
 
 Primary constructs parsed by dedicated parsers:
+
 - **query** - API endpoints with HTTP verbs, input validation, processing logic, responses
 - **function** - Reusable logic blocks with testing capabilities
 - **task** - Scheduled operations with cron-like triggers
@@ -63,18 +67,147 @@ Primary constructs parsed by dedicated parsers:
 
 ## Adding New Features
 
-### New Object Type
-1. Create a new parser in `parser/` (e.g., `my_object_parser.js`)
-2. Follow existing parser patterns (see `query_parser.js`, `function_parser.js`)
-3. Register it in `server.js`
+### New Top-Level Parser (e.g., `run.job`, `run.service`)
+
+Follow this step-by-step process:
+
+**1. Create lexer tokens (`lexer/my_feature.js`)**
+
+```javascript
+import { Identifier } from "./identifier.js";
+import { createTokenByName } from "./utils.js";
+
+export const MyToken = createTokenByName("my_keyword", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+export const MyFeatureTokens = [MyToken];
+
+export function mapTokenToType(token) {
+  switch (token) {
+    case MyToken.name:
+      return "keyword";
+    default:
+      return null;
+  }
+}
+```
+
+**2. Register tokens in `lexer/tokens.js`**
+
+- Import tokens and mapper at the top
+- Add `...MyFeatureTokens` to `allTokens` array
+- Add `mapMyFeatureTokenToType` to `tokenMappers` array
+
+**3. Create parser (`parser/my_feature_parser.js`)**
+
+```javascript
+import { StringLiteral } from "../lexer/literal.js";
+import { MyToken } from "../lexer/my_feature.js";
+import { Identifier, NewlineToken } from "../lexer/tokens.js";
+
+export function myFeatureDeclaration($) {
+  return () => {
+    $.sectionStack.push("myFeatureDeclaration");
+    $.SUBRULE($.optionalCommentBlockFn);
+
+    const parent = $.CONSUME(MyToken);
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    // Use schemaParseAttributeFn for body with declarative schema
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          required_attr: "[string]",
+          "optional_attr?": "[boolean]",
+          "nested?": {
+            name: "[string]",
+            "value?": { "[string]": "[constant]" },
+          },
+          "array_of_strings?": ["[string]"],
+        },
+      ],
+    });
+
+    $.MANY2(() => $.CONSUME2(NewlineToken));
+    $.sectionStack.pop();
+  };
+}
+```
+
+**4. Register parser in `parser/register.js`**
+
+```javascript
+import { myFeatureDeclaration } from "./my_feature_parser.js";
+// In register function:
+$.myFeatureDeclaration = $.RULE(
+  "myFeatureDeclaration",
+  myFeatureDeclaration($)
+);
+```
+
+**5. Add scheme detection in `utils.js`**
+
+```javascript
+const schemeByFirstWord = {
+  // ... existing entries
+  my_feature: "my_feature",
+};
+```
+
+**6. Route scheme in `parser/parser.js`**
+
+```javascript
+case "my_feature":
+  parser.myFeatureDeclaration();
+  return parser;
+```
+
+**7. Write tests (`parser/my_feature_parser.spec.js`)**
+
+```javascript
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { xanoscriptParser } from "./parser.js";
+
+describe("my_feature", () => {
+  it("should parse a basic my_feature", () => {
+    const parser = xanoscriptParser(`my_feature "name" {
+      required_attr = "value"
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+});
+```
+
+### Schema Definition Types (for `schemaParseAttributeFn`)
+
+| Schema                         | Description                        | Example                   |
+| ------------------------------ | ---------------------------------- | ------------------------- |
+| `"[string]"`                   | String literal                     | `"hello"`                 |
+| `"[number]"`                   | Number literal                     | `123`                     |
+| `"[boolean]"`                  | Boolean value                      | `true` / `false`          |
+| `"[constant]"`                 | Value expression (no variables)    | `"text"`, `123`, `{a: 1}` |
+| `"[expression]"`               | Any expression including variables | `$var`, `$input.name`     |
+| `["[string]"]`                 | Array of strings                   | `["a", "b"]`              |
+| `{ "[string]": "[constant]" }` | Object with string keys            | `{key: "value"}`          |
+| `"attr?"`                      | Optional attribute                 | May be omitted            |
+| `"!attr"`                      | Can be disabled                    | `!attr = value`           |
 
 ### New Keyword/Function
+
 1. Add token definition in appropriate `lexer/` file
 2. Create function implementation in `parser/functions/[domain]/`
 3. Register in parent clause or parser
 4. Add comprehensive tests in corresponding `.spec.js` file
 
 ### Token Creation Pattern
+
 ```javascript
 export const MyToken = createTokenByName("keyword", {
   longer_alt: Identifier,
@@ -83,6 +216,7 @@ export const MyToken = createTokenByName("keyword", {
 ```
 
 ### Parser Rule Pattern
+
 ```javascript
 myRule = this.RULE("myRule", () => {
   this.CONSUME(MyToken);
@@ -100,6 +234,7 @@ myRule = this.RULE("myRule", () => {
 - CI requires all tests to pass
 
 ### Test Pattern
+
 ```javascript
 function parse(inputText) {
   const lexResult = lexDocument(inputText);
@@ -118,4 +253,4 @@ function parse(inputText) {
 - Follow existing code conventions when adding features
 - Check neighboring files for patterns and conventions
 - Never assume a library is available - check `package.json` first
-- 3 low-severity npm audit warnings are known and acceptable
+- 3 low-severity npm audit warnings are known and acceptable

package/lexer/run.js

@@ -0,0 +1,37 @@
+import { Identifier } from "./identifier.js";
+import { createTokenByName } from "./utils.js";
+
+// "run"
+export const RunToken = createTokenByName("run", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+// "job"
+export const JobToken = createTokenByName("job", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+// "service"
+export const ServiceToken = createTokenByName("service", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+export const RunTokens = [RunToken, JobToken, ServiceToken];
+
+/**
+ * Maps a token name to a type
+ * @param {string} token the token name
+ */
+export function mapTokenToType(token) {
+  switch (token) {
+    case RunToken.name:
+    case JobToken.name:
+    case ServiceToken.name:
+      return "keyword";
+    default:
+      return null;
+  }
+}

package/lexer/tokens.js

@@ -93,6 +93,7 @@ import {
   RealtimeTriggerTokens,
 } from "./realtime_trigger.js";
 import { mapTokenToType as mapRedisTokenToType, RedisTokens } from "./redis.js";
+import { mapTokenToType as mapRunTokenToType, RunTokens } from "./run.js";
 import {
   mapTokenToType as mapSecurityTokenToType,
   SecurityTokens,
@@ -382,6 +383,7 @@ export const allTokens = uniq([
   ...DbTokens,
   ...RedisTokens,
   ...TextTokens,
+  ...RunTokens,
   ...ObjectTokens,
   ...StreamTokens,
   ...DebugTokens,
@@ -430,6 +432,7 @@ const tokenMappers = [
   mapQueryTokenToType,
   mapRealtimeTriggerTokenToType,
   mapRedisTokenToType,
+  mapRunTokenToType,
   mapSecurityTokenToType,
   mapStorageTokenToType,
   mapStreamTokenToType,

package/onHover/functions.md

@@ -287,6 +287,62 @@ A `task` file defines a scheduled job that runs automatically at specified times
 
 Tasks are ideal for automating recurring operations like generating reports or syncing data.
 
+# run.job
+
+```xs
+run.job "Gemini -> Image Understanding" {
+  main = {
+    name: "Gemini -> Image Understanding"
+    input: {
+      model: "gemini-1.5-flash"
+      prompt: "Describe what is happening in this image."
+      image: "(attach image file)"
+    }
+  }
+  env = ["gemini_api_key"]
+}
+```
+
+A `run.job` file defines a job configuration for execution in the Xano Job Runner. It includes:
+
+- A name (e.g., `"Gemini -> Image Understanding"`) to identify the job,
+- A required `main` attribute specifying the function to execute:
+  - `name`: The name of the function to call,
+  - `input`: Optional input parameters to pass to the function,
+- An optional `env` array listing environment variable names required by the job.
+
+Jobs are used to run functions as standalone processes, typically for long-running or resource-intensive operations.
+
+# run.service
+
+```xs
+run.service "email proxy" {
+  pre = {
+    name: "email_proxy_init"
+    input: {
+      config: "default"
+    }
+  }
+  env = ["email_proxy_api_key"]
+}
+```
+
+A `run.service` file defines a service configuration for the Xano Job Runner. It includes:
+
+- A name (e.g., `"email proxy"`) to identify the service,
+- An optional `pre` attribute specifying an initialization function to run before the service starts:
+  - `name`: The name of the initialization function,
+  - `input`: Optional input parameters for the initialization,
+- An optional `env` array listing environment variable names required by the service.
+
+Services can also be defined in minimal form without a body:
+
+```xs
+run.service "email proxy"
+```
+
+Services are ideal for long-running background processes like proxies, webhooks listeners, or daemon-style operations.
+
 # action.call
 
 ```xs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/xanoscript-language-server",
-  "version": "11.0.6",
+  "version": "11.1.0",
   "description": "Language Server Protocol implementation for XanoScript",
   "type": "module",
   "main": "server.js",

package/parser/attributes/docsFieldAttribute.spec.js

@@ -32,6 +32,11 @@ describe("docsFieldAttribute", () => {
     expect(parser.errors).to.be.empty;
   });
 
+  it("docsFieldAttribute can be multiline", () => {
+    const parser = parse('docs="""\nanother docs\n"""');
+    expect(parser.errors).to.be.empty;
+  });
+
   it("docsFieldAttribute does not require a new line", () => {
     const parser = parse('docs="some docs"');
     expect(parser.errors).to.be.empty;

package/parser/functions/api/apiCallFn.spec.js

@@ -47,12 +47,12 @@ describe("apiCallFn", () => {
   });
 
   it("apiCallFn requires a url and method field", () => {
-    let parser = parse(`request {
+    let parser = parse(`call foo {
       url = "https://www.example.com"
     } as $user`);
     expect(parser.errors).to.not.be.empty;
 
-    parser = parse(`request {
+    parser = parse(`call foo {
       method = "GET"
     } as $user`);
     expect(parser.errors).to.not.be.empty;

package/parser/functions/controls/tryCatchFn.spec.js

@@ -59,7 +59,6 @@ describe("tryCatchFn", () => {
         }
       }
     }`);
-    console.log(parser.errors);
     expect(parser.errors).to.be.empty;
   });
 

package/parser/generic/objectWithAttributes.js

@@ -5,6 +5,7 @@ import { Identifier, NewlineToken } from "../../lexer/tokens.js";
 import { getVarName } from "./utils.js";
 
 /**
+ * @deprecated use parser/functions/schema/schemaParseAttributeFn.js instead
  * @param {import('../base_parser.js').XanoBaseParser} $
  */
 export function objectWithAttributes($) {

package/parser/parser.js

@@ -53,6 +53,9 @@ export function xanoscriptParser(text, scheme, preTokenized = null) {
     case "realtime_channel":
       parser.realtimeChannelDeclaration();
       return parser;
+    case "run":
+      parser.runDeclaration();
+      return parser;
     case "table_trigger":
       parser.tableTriggerDeclaration();
       return parser;

package/parser/register.js

@@ -16,6 +16,11 @@ import { middlewareDeclaration } from "./middleware_parser.js";
 import { queryDeclaration } from "./query_parser.js";
 import { realtimeChannelDeclaration } from "./realtime_channel_parser.js";
 import { realtimeTriggerDeclaration } from "./realtime_trigger_parser.js";
+import {
+  runDeclaration,
+  runJobClause,
+  runServiceClause,
+} from "./run_parser.js";
 import { tableDeclaration } from "./table_parser.js";
 import { tableTriggerDeclaration } from "./table_trigger_parser.js";
 import { taskDeclaration } from "./task_parser.js";
@@ -66,6 +71,9 @@ export const register = ($) => {
     "realtimeChannelDeclaration",
     realtimeChannelDeclaration($)
   );
+  $.runDeclaration = $.RULE("runDeclaration", runDeclaration($));
+  $.runJobClause = $.RULE("runJobClause", runJobClause($));
+  $.runServiceClause = $.RULE("runServiceClause", runServiceClause($));
   $.tableTriggerDeclaration = $.RULE(
     "tableTriggerDeclaration",
     tableTriggerDeclaration($)

package/parser/run_parser.js

@@ -0,0 +1,70 @@
+import { StringLiteral } from "../lexer/literal.js";
+import { JobToken, RunToken, ServiceToken } from "../lexer/run.js";
+import { DotToken, Identifier, NewlineToken } from "../lexer/tokens.js";
+
+export function runDeclaration($) {
+  return () => {
+    $.sectionStack.push("runDeclaration");
+    // Allow leading comments and newlines before the run declaration
+    $.SUBRULE($.optionalCommentBlockFn);
+
+    $.CONSUME(RunToken); // "run"
+    $.CONSUME(DotToken); // "."
+
+    $.OR([
+      { ALT: () => $.SUBRULE($.runJobClause) },
+      { ALT: () => $.SUBRULE($.runServiceClause) },
+    ]);
+
+    $.MANY2(() => $.CONSUME2(NewlineToken)); // optional trailing newlines
+    $.sectionStack.pop();
+  };
+}
+
+export function runJobClause($) {
+  return () => {
+    const parent = $.CONSUME(JobToken); // "job"
+
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          main: {
+            name: "[string]",
+            input: { "[string]?": "[constant]" },
+          },
+          "env?": ["[string]"],
+        },
+      ],
+    });
+  };
+}
+
+export function runServiceClause($) {
+  return () => {
+    const parent = $.CONSUME(ServiceToken); // "service"
+
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          "pre?": {
+            name: "[string]",
+            input: { "[string]?": "[constant]" },
+          },
+          "env?": ["[string]"],
+        },
+      ],
+    });
+  };
+}

package/parser/run_parser.spec.js

@@ -0,0 +1,100 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { xanoscriptParser } from "./parser.js";
+
+describe("run", () => {
+  it("should parse a basic run.job", () => {
+    const parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("should parse a basic run.job with inputs", () => {
+    const parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {left: 1, right: 2}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.job requires a main attribute", () => {
+    let parser = xanoscriptParser(`run.job "Average of values" {
+      pre = {name: "avg_value", input: {left: 1, right: 2}}
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.job "Average of values" {}`);
+    expect(parser.errors).to.not.be.empty;
+  });
+
+  it("should accept env variable", () => {
+    const parser = xanoscriptParser(`run.job "Gemini -> Image Understanding" {
+      main = {
+        name : "Gemini -> Image Understanding"
+        input: {
+          model : "gemini-1.5-flash"
+          prompt: "Describe what is happening in this image."
+          image : "(attach image file)"
+        }
+      }
+    
+      env = ["gemini_api_key"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("should parse a basic run.service", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      pre = {name: "email_proxy_fn", input: {}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service has a minimal form", () => {
+    const parser = xanoscriptParser(`run.service "email proxy"`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("environment variables can only be an array of strings", () => {
+    let parser = xanoscriptParser(`run.service "email proxy" {
+      env = ["email_proxy_api_key", 123, true]
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {}}
+      env = ["email_proxy_api_key", 123, true]
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.service "email proxy" {
+      env = []
+    }`);
+    expect(parser.errors).to.be.empty;
+
+    parser = xanoscriptParser(`run.service "email proxy" {
+      env = ["a_value", "another value"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service does not require a pre", () => {
+    const parser = xanoscriptParser(`run.service "email proxy"`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service does not accept a main", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      main = { name : "some_fn", input: {} }
+    }`);
+    expect(parser.errors).to.not.be.empty;
+  });
+
+  it("run.service accepts env variables", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      pre = {name: "email_proxy_init", input: {}}
+      env = ["email_proxy_api_key"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+});

package/utils.js

@@ -30,6 +30,7 @@ const schemeByFirstWord = {
   query: "api",
   realtime_trigger: "realtime_trigger",
   realtime_channel: "realtime_channel",
+  run: "run",
   table: "db",
   table_trigger: "table_trigger",
   task: "task",

package/.claude/settings.local.json

@@ -1,36 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test:*)",
-      "Bash(npm run lint)",
-      "Bash(npm run test:*)",
-      "Bash(npx eslint:*)",
-      "Bash(node:*)",
-      "Bash(npm install)",
-      "Bash(grep:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all --pretty=format:\"%h %s\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all -S \"password\\\\|secret\\\\|api_key\\\\|token\" --oneline)",
-      "Bash(xargs file:*)",
-      "Bash(find:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -p --all -S \"webhook\\\\|Bearer\\\\|discord\\\\|slack\\\\|xano_insiders\" -- \"*.xs\" \"*.js\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server ls-files:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server status)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server diff --stat)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --oneline -5)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server add README.md LICENSE package.json lexer/tests/query/valid_sources/basic_query.xs parser/functions/stream/streamFromRequestFn.js parser/functions/stream/streamFromRequestFn.spec.js parser/tests/function/valid_sources/discord_poll_send_to_slack.xs parser/tests/query/valid_sources/all_basics.xs)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server commit -m \"$\\(cat <<''EOF''\nPrepare package for public npm release as @xano/xanoscript-language-server\n\n- Rename package to @xano/xanoscript-language-server\n- Add MIT LICENSE file\n- Add npm metadata \\(description, repository, author, license, bugs, homepage\\)\n- Remove private flag to allow publishing\n- Sanitize test files: replace internal URLs, IDs, and env var names with placeholders\n- Simplify README maintainer section\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -1 --oneline)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git push)",
-      "Bash(npm whoami:*)",
-      "Bash(npm view:*)",
-      "Bash(npm version:*)",
-      "Bash(npm publish:*)",
-      "Bash(wc:*)",
-      "Bash(git push:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}