Enhance server logic validation and documentation

- ✏️ Update SKILL.md to clarify async function usage with Dataverse.
- ✅ Add validation tests for server logic functions, including checks for async/await usage and error handling.
- 📝 Implement detailed error messages for validation failures.

-Priyanshu

Author: priyanshu92

plugins/power-pages/scripts/tests/validate-serverlogic.test.js

@@ -0,0 +1,172 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { createTempProject, writeProjectFile } = require('./test-utils');
+
+const VALIDATOR_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  'skills',
+  'integrate-serverlogic',
+  'scripts',
+  'validate-serverlogic.js'
+);
+
+function runValidator(projectRoot) {
+  const input = JSON.stringify({ cwd: projectRoot });
+  return spawnSync(process.execPath, [VALIDATOR_PATH], {
+    input,
+    encoding: 'utf8',
+  });
+}
+
+function setupProject(projectRoot) {
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+}
+
+function writeServerLogic(projectRoot, name, jsContent, ymlContent) {
+  const dir = `.powerpages-site/server-logic/${name}`;
+  writeProjectFile(projectRoot, `${dir}/${name}.js`, jsContent);
+  if (ymlContent) {
+    writeProjectFile(projectRoot, `${dir}/${name}.serverlogic.yml`, ymlContent);
+  }
+}
+
+const VALID_YML = `adx_serverlogic_adx_webrole:
+  - 11111111-1111-1111-1111-111111111111
+description: Test endpoint
+display_name: Test
+id: 22222222-2222-2222-2222-222222222222
+name: test-endpoint`;
+
+const VALID_JS = `function get() {
+    try {
+        Server.Logger.Log("test-endpoint GET called");
+        return JSON.stringify({ status: "success" });
+    } catch (err) {
+        Server.Logger.Error("test-endpoint GET failed: " + err.message);
+        return JSON.stringify({ status: "error", message: err.message });
+    }
+}`;
+
+test('valid server logic passes validation', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  writeServerLogic(projectRoot, 'test-endpoint', VALID_JS, VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('async function without await is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const asyncNoAwaitJs = `async function get() {
+    try {
+        Server.Logger.Log("test-endpoint GET called");
+        var records = Server.Connector.Dataverse.RetrieveMultipleRecords("contacts", "?$top=10");
+        return JSON.stringify({ status: "success", data: records });
+    } catch (err) {
+        Server.Logger.Error("test-endpoint GET failed: " + err.message);
+        return JSON.stringify({ status: "error", message: err.message });
+    }
+}`;
+  writeServerLogic(projectRoot, 'test-endpoint', asyncNoAwaitJs, VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /function 'get' is marked async but contains no await/);
+});
+
+test('async function with await passes validation', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const asyncWithAwaitJs = `async function post() {
+    try {
+        Server.Logger.Log("test-endpoint POST called");
+        var response = await Server.Connector.HttpClient.PostAsync("https://api.example.com/data", JSON.stringify({ key: "value" }));
+        return JSON.stringify({ status: "success", data: response });
+    } catch (err) {
+        Server.Logger.Error("test-endpoint POST failed: " + err.message);
+        return JSON.stringify({ status: "error", message: err.message });
+    }
+}`;
+  writeServerLogic(projectRoot, 'test-endpoint', asyncWithAwaitJs, VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('missing js file is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const dir = path.join(projectRoot, '.powerpages-site', 'server-logic', 'test-endpoint');
+  fs.mkdirSync(dir, { recursive: true });
+  writeProjectFile(projectRoot, '.powerpages-site/server-logic/test-endpoint/test-endpoint.serverlogic.yml', VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing \.js file/);
+});
+
+test('missing yml file is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  writeServerLogic(projectRoot, 'test-endpoint', VALID_JS, null);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing metadata file/);
+});
+
+test('missing try/catch is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const noTryCatchJs = `function get() {
+    Server.Logger.Log("test-endpoint GET called");
+    return JSON.stringify({ status: "success" });
+}`;
+  writeServerLogic(projectRoot, 'test-endpoint', noTryCatchJs, VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing try\/catch/);
+});
+
+test('disallowed function name is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const badFnJs = `function get() {
+    try {
+        Server.Logger.Log("test-endpoint GET called");
+        return JSON.stringify({ status: "success" });
+    } catch (err) {
+        Server.Logger.Error("test-endpoint GET failed: " + err.message);
+        return JSON.stringify({ status: "error", message: err.message });
+    }
+}
+
+function helper() {
+    return "not allowed";
+}`;
+  writeServerLogic(projectRoot, 'test-endpoint', badFnJs, VALID_YML);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /found additional top-level functions: helper/);
+});
+
+test('yml name mismatch is flagged', (t) => {
+  const projectRoot = createTempProject(t);
+  setupProject(projectRoot);
+  const mismatchYml = VALID_YML.replace('name: test-endpoint', 'name: wrong-name');
+  writeServerLogic(projectRoot, 'test-endpoint', VALID_JS, mismatchYml);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /does not match folder name/);
+});

plugins/power-pages/skills/integrate-serverlogic/SKILL.md

@@ -325,7 +325,7 @@ Repeat this step for each approved server logic item. Create or update `<PROJECT
 4. **Each function logs**: Use `Server.Logger.Log()` at entry and `Server.Logger.Error()` in catch blocks.
 5. **No imports or requires**: No `import`, `require`, or external dependencies.
 6. **No browser APIs**: No `fetch`, `XMLHttpRequest`, `setTimeout`, `setInterval`, `console.log`, or DOM APIs.
-7. **Async when needed**: Mark functions as `async` only when they use `await` (HttpClient or Dataverse calls).
+7. **Async when needed**: Mark functions as `async` only when they use `await` (HttpClient calls). Dataverse connector methods (`Server.Connector.Dataverse.*`) are **synchronous** — do NOT use `async`/`await` with them.
 
 #### Code Template
 
@@ -334,7 +334,7 @@ Repeat this step for each approved server logic item. Create or update `<PROJECT
 // Purpose: <description>
 // API URL: https://<site-url>/_api/serverlogics/<name>
 
-async function get() {
+function get() {
     try {
         Server.Logger.Log("<name> GET called");
 

plugins/power-pages/skills/integrate-serverlogic/scripts/validate-serverlogic.js

@@ -129,17 +129,22 @@ runValidation((cwd) => {
     }
 
     // Check: each function has try/catch (scan until next top-level function or end of file)
+    // Check: async functions must contain await (unnecessary async causes runtime errors with synchronous Dataverse calls)
     for (const fn of foundFunctions) {
-      const fnRegex = new RegExp(`(?:async\\s+)?function\\s+${fn}\\s*\\([^)]*\\)\\s*\\{`, 'g');
+      const fnRegex = new RegExp(`(async\\s+)?function\\s+${fn}\\s*\\([^)]*\\)\\s*\\{`, 'g');
       const match = fnRegex.exec(content);
       if (match) {
+        const isAsync = !!match[1];
         const bodyStart = match.index + match[0].length;
         const nextFnMatch = content.slice(bodyStart).match(/\n(?:async\s+)?function\s+[a-zA-Z]/);
         const bodyEnd = nextFnMatch ? bodyStart + nextFnMatch.index : content.length;
         const fnBody = content.slice(bodyStart, bodyEnd);
         if (!/\btry\s*\{/.test(fnBody)) {
           errors.push(`${dirName}.js: function '${fn}' is missing try/catch error handling`);
         }
+        if (isAsync && !/\bawait\b/.test(fnBody)) {
+          errors.push(`${dirName}.js: function '${fn}' is marked async but contains no await — remove async to avoid runtime errors (Dataverse calls are synchronous, only HttpClient requires async/await)`);
+        }
       }
     }