@jrpool/kilotest 46.1.2 → 48.0.0

package/.claude/settings.local.json

@@ -3,7 +3,19 @@
     "allow": [
       "WebSearch",
       "Bash(gh api *)",
-      "WebFetch(domain:raw.githubusercontent.com)"
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(ls -la /Users/pool/Documents/Topics/repos/a11yTesting/kilotest/*.json)",
+      "Bash(grep -n \"^import\\\\|^export\" /Users/pool/Documents/Topics/repos/a11yTesting/qai/src/*.ts)",
+      "Bash(find /Users/pool/Documents/Topics/repos/a11yTesting/kilotest -type f \\\\\\( -name \"*.test.js\" -o -name \"*.test.cjs\" -o -name \"test.js\" \\\\\\) ! -path \"*/node_modules/*\" -exec wc -l {} +)",
+      "Bash(find /Users/pool/Documents/Topics/repos/a11yTesting/kilotest -type f \\\\\\( -name \"*.test.js\" -o -name \"*.test.cjs\" -o -name \"test.js\" \\\\\\) ! -path \"*/node_modules/*\" -exec grep -h \"^test\\(\" {} +)",
+      "Bash(npm install:*)",
+      "Bash(npm run:*)",
+      "Bash(npm test:*)",
+      "Bash(git add:*)",
+      "Bash(git rm:*)",
+      "Bash(git commit -m ':*)",
+      "Bash(git push:*)",
+      "Bash(gh auth:*)"
     ]
   }
 }

package/.devin/config.local.json

@@ -32,7 +32,11 @@
       "Exec(awk)",
       "Exec(nvm ls)",
       "Exec(.)",
-      "Exec(nvm alias)"
+      "Exec(nvm alias)",
+      "Exec(git mv)",
+      "Exec(perl)",
+      "Exec(ssh)",
+      "Exec(scp)"
     ]
   }
 }

package/.github/workflows/ci.yml

@@ -27,6 +27,3 @@ jobs:
 
       - name: Run tests with coverage
         run: npm test
-
-      - name: Run smoke test against deployed server
-        run: node smokeTest.js

package/.github/workflows/periodic-smoke-tests.yml

@@ -0,0 +1,30 @@
+name: Periodic Smoke Tests
+
+on:
+  schedule:
+    # Run daily at 14:14 UTC
+    - cron: '14 14   * * *'
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  smoke-tests:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set Node.js version
+        uses: actions/setup-node@v4
+        with:
+          node-version: '>=24.16.0'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run smoke tests against deployed service
+        run: npm exec -- node smokeTest.ts
+        env:
+          SMOKE_HOST: kilotest.com

package/.github/workflows/publish-mcp.yml

@@ -5,7 +5,7 @@ on:
     branches: [main]
     paths:
       - 'server.json'
-      - 'api/version.js'
+      - 'api/version.ts'
 
 jobs:
   publish:
@@ -23,12 +23,12 @@ jobs:
         with:
           node-version: '>=24.16.0'
 
-      - name: Verify server.json version matches api/version.js
+      - name: Verify server.json version matches api/version.ts
         run: |
-          FILE_VERSION=$(node -e "console.log(require('./api/version').version)")
+          FILE_VERSION=$(node -e "console.log(require('./api/version.ts').version)")
           JSON_VERSION=$(node -e "console.log(require('./server.json').version)")
           if [ "$FILE_VERSION" != "$JSON_VERSION" ]; then
-            echo "::error::server.json version ($JSON_VERSION) does not match api/version.js version ($FILE_VERSION)"
+            echo "::error::server.json version ($JSON_VERSION) does not match api/version.ts version ($FILE_VERSION)"
             exit 1
           fi
           echo "Versions match: $FILE_VERSION"

package/{alerts.test.js → alerts.test.ts}

@@ -1,19 +1,20 @@
 /*
-  alerts.test.js
-  Tests for alerts.js, covering the success, failure, error, timeout, and unconfigured paths.
+  alerts.test.ts
+  Tests for alerts.ts, covering the success, failure, error, timeout, and unconfigured paths.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const https = require('node:https');
-const {EventEmitter} = require('node:events');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import https from 'node:https';
+import {EventEmitter} from 'node:events';
+import {sendAlert} from './alerts.ts';
 
 // SETUP AND TEARDOWN
 
 const originalRequest = https.request;
-const savedEnv = {};
+const savedEnv: Record<string, any> = {};
 
 before(() => {
   for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
@@ -31,29 +32,27 @@ after(() => {
       delete process.env[key];
     }
   }
-  delete require.cache[require.resolve('./alerts')];
-  require('./alerts');
 });
 
 // HELPER
 
 // Replaces https.request with a function that returns a fake request and invokes the callback with a fake response. The mockHandler is called on next tick so that event listeners are attached first.
-const mockRequest = mockHandler => {
-  https.request = (options, callback) => {
-    const req = new EventEmitter();
+const mockRequest = (mockHandler: any) => {
+  https.request = ((options: any, callback: any) => {
+    const req: any = new EventEmitter();
     req.write = () => {};
     req.end = () => {};
     req.destroy = () => {
       req.emit('error', new Error('Socket destroyed'));
     };
-    req.setTimeout = (ms, fn) => {
+    req.setTimeout = (ms: any, fn: any) => {
       process.nextTick(fn);
     };
-    const res = new EventEmitter();
+    const res: any = new EventEmitter();
     res.statusCode = 200;
     process.nextTick(() => mockHandler(req, res, callback));
     return req;
-  };
+  }) as any;
 };
 
 // Sets the alert configuration env vars so that sendAlert enters the configured path.
@@ -72,29 +71,21 @@ const clearAlertConfig = () => {
   }
 };
 
-// Loads alerts.js fresh so it picks up the current env vars and https.request.
-const loadAlerts = () => {
-  delete require.cache[require.resolve('./alerts')];
-  return require('./alerts');
-};
-
 // TESTS
 
 test('sendAlert resolves without sending when configuration is incomplete', async () => {
   clearAlertConfig();
-  const {sendAlert} = loadAlerts();
   await sendAlert('Test', 'Body');
   assert.ok(true);
 });
 
 test('sendAlert logs success when the API responds with a 2xx status', async () => {
   setAlertConfig();
-  mockRequest((req, res, callback) => {
+  mockRequest((req: any, res: any, callback: any) => {
     res.statusCode = 200;
     callback(res);
     res.emit('end');
   });
-  const {sendAlert} = loadAlerts();
   await sendAlert('Test Success', 'Body');
   https.request = originalRequest;
   assert.ok(true);
@@ -102,13 +93,12 @@ test('sendAlert logs success when the API responds with a 2xx status', async ()
 
 test('sendAlert logs an error when the API responds with a non-2xx status', async () => {
   setAlertConfig();
-  mockRequest((req, res, callback) => {
+  mockRequest((req: any, res: any, callback: any) => {
     res.statusCode = 500;
     callback(res);
     res.emit('data', 'Server error');
     res.emit('end');
   });
-  const {sendAlert} = loadAlerts();
   await sendAlert('Test Failure', 'Body');
   https.request = originalRequest;
   assert.ok(true);
@@ -116,10 +106,9 @@ test('sendAlert logs an error when the API responds with a non-2xx status', asyn
 
 test('sendAlert logs an error when the request errors', async () => {
   setAlertConfig();
-  mockRequest((req) => {
+  mockRequest((req: any) => {
     req.emit('error', new Error('Connection refused'));
   });
-  const {sendAlert} = loadAlerts();
   await sendAlert('Test Error', 'Body');
   https.request = originalRequest;
   assert.ok(true);
@@ -130,7 +119,6 @@ test('sendAlert logs an error when the request times out', async () => {
   mockRequest(() => {
     // Do nothing; the setTimeout mock will fire and call req.destroy().
   });
-  const {sendAlert} = loadAlerts();
   await sendAlert('Test Timeout', 'Body');
   https.request = originalRequest;
   assert.ok(true);

package/{alerts.js → alerts.ts}

@@ -1,25 +1,22 @@
 /*
-  alerts.js
+  alerts.ts
   Sends alert emails to a Kilotest manager when required.
 */
 
 // IMPORTS
 
-const https = require('https');
-
-// CONSTANTS
-
-// Alert configuration.
-const MANAGER_EMAIL = process.env.MANAGER_EMAIL;
-const ALERT_API_HOST = process.env.ALERT_API_HOST;
-const ALERT_API_PATH = process.env.ALERT_API_PATH;
-const ALERT_API_KEY = process.env.ALERT_API_KEY;
-const ALERT_FROM = process.env.ALERT_FROM;
+import https from 'node:https';
 
 // FUNCTIONS
 
 // Sends an email alert to a manager.
-exports.sendAlert = (subject, body) => new Promise(resolve => {
+export const sendAlert = (subject: string, body: string): Promise<void> => new Promise(resolve => {
+  // Alert configuration, read at call time so it is not frozen when this module is loaded.
+  const MANAGER_EMAIL = process.env['MANAGER_EMAIL'];
+  const ALERT_API_HOST = process.env['ALERT_API_HOST'];
+  const ALERT_API_PATH = process.env['ALERT_API_PATH'];
+  const ALERT_API_KEY = process.env['ALERT_API_KEY'];
+  const ALERT_FROM = process.env['ALERT_FROM'];
   // If the alert configuration is complete:
   if (MANAGER_EMAIL && ALERT_API_HOST && ALERT_API_PATH && ALERT_API_KEY && ALERT_FROM) {
     const payload = JSON.stringify({
@@ -45,7 +42,7 @@ exports.sendAlert = (subject, body) => new Promise(resolve => {
       });
       res.on('end', () => {
         // If this succeeded:
-        if (res.statusCode >= 200 && res.statusCode < 300) {
+        if (res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300) {
           // Report this.
           console.log(`Alert sent (${subject})`);
         }

package/api/{getReport.test.js → getReport.test.ts}

@@ -1,21 +1,20 @@
 /*
-  getReport.test.js
-  Tests for api/getReport.js using the fixture corpus.
+  getReport.test.ts
+  Tests for api/getReport.ts using the fixture corpus.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const {response} = require('./getReport');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import {response} from './getReport.ts';
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
 
-before(() => {
-  process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
+before(async () => {
+  process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
 });
 
 after(() => {
@@ -33,8 +32,8 @@ test('getReport returns the full report for a valid report', async () => {
   const body = await response(['260101T0000', 'mix']);
   const content = body['response content'];
   assert.equal(typeof content['size of the report in bytes'], 'number');
-  assert.ok(content['size of the report in bytes'] > 0);
-  const report = content['full report'];
+  assert.ok((content['size of the report in bytes'] as number) > 0);
+  const report = content['full report'] as any;
   assert.equal(report.id, '260101T0000-mix');
   assert.equal(report.target.what, 'Mixed Outcomes Page');
   assert.equal(report.target.url, 'https://example.com/mixed');

package/api/{getReport.js → getReport.ts}

@@ -1,44 +1,43 @@
 /*
-  getReport.js
+  getReport.ts
   Returns one report.
 */
 
 // IMPORTS
 
-const {
+import {z} from 'zod';
+import {
   getResponseMetadata,
   getToolsFacts,
-  thisHost
-} = require('./util');
-const {getReport, getReportStats} = require('../util');
+  getThisHost
+} from './util.ts';
+import {getReport, getReportStats} from '../util.ts';
+import {getReportResponseSchema} from './schemas.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof getReportResponseSchema>['response content'];
 
 // FUNCTIONS
 
 // Returns the response body.
-exports.response = async args => {
+export const response = async (args: string[]) => {
   const [timeStamp = '', jobID = ''] = args;
-  // Initialize the response content.
-  const responseContent = {
-    'size of the report in bytes': null,
-    'full report': null
-  };
+  const thisHost = getThisHost();
   // Get the report size.
   const reportStats = await getReportStats(timeStamp, jobID);
-  // If this failed:
-  if (!reportStats) {
-    // Add this to the response content.
-    responseContent['size of the report in bytes'] = 'Error: The report could not be accessed for an unknown reason.';
-  }
-  // Otherwise, i.e. if it succeeded:
-  else {
-    const {reportSize} = reportStats;
-    // Add the size to the response content.
-    responseContent['size of the report in bytes'] = reportSize;
+  // Create the response content.
+  const responseContent: ResponseContent = reportStats
+  ? {
+    'size of the report in bytes': reportStats.reportSize,
     // Get the report (which may be only an error message).
-    const report = await getReport(timeStamp, jobID);
-    // Add it to the response content.
-    responseContent['full report'] = report;
+    'full report': await getReport(timeStamp, jobID)
   }
+  : {
+    'size of the report in bytes': 'Error: The report could not be accessed for an unknown reason.',
+    'full report': null
+  };
   // Create a response body.
   const body = {
     'tool collection': getToolsFacts(),

package/api/{listDiagnoses.test.js → listDiagnoses.test.ts}

@@ -1,21 +1,20 @@
 /*
-  listDiagnoses.test.js
-  Tests for api/listDiagnoses.js using the fixture corpus, with emphasis on outcome handling.
+  listDiagnoses.test.ts
+  Tests for api/listDiagnoses.ts using the fixture corpus, with emphasis on outcome handling.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const {response} = require('./listDiagnoses');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import {response} from './listDiagnoses.ts';
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
 
-before(() => {
-  process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
+before(async () => {
+  process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
 });
 
 after(() => {
@@ -31,23 +30,23 @@ after(() => {
 
 test('listDiagnoses returns 2 diagnoses for catalogIndex 0, linkNoText, in the mixed report (axe and alfa, excluding cantTell)', async () => {
   const body = await response(['0', 'linkNoText', '260101T0000', 'mix']);
-  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'];
+  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'] as any;
   assert.equal(diagnoses.length, 2);
-  const rules = diagnoses.map(d => d['identifier of the violated rule']).sort();
+  const rules = diagnoses.map((d: any) => d['identifier of the violated rule']).sort();
   assert.deepEqual(rules, ['r11', 'r11']);
-  const descriptions = diagnoses.map(d => d['description of the violation']);
-  assert.ok(descriptions.every(d => d === 'The link does not have an accessible name'));
+  const descriptions = diagnoses.map((d: any) => d['description of the violation']);
+  assert.ok(descriptions.every((d: any) => d === 'The link does not have an accessible name'));
 });
 
 test('listDiagnoses returns 0 diagnoses when all instances are cantTell', async () => {
   const body = await response(['0', 'focusIndicationBad', '260101T0001', 'ct']);
-  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'];
+  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'] as any;
   assert.equal(diagnoses.length, 0);
 });
 
 test('listDiagnoses treats missing outcome as a violation', async () => {
   const body = await response(['0', 'linkNoText', '260101T0002', 'no']);
-  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'];
+  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'] as any;
   assert.equal(diagnoses.length, 1);
   assert.equal(diagnoses[0]['description of the violation'], 'Button has no accessible name');
   assert.equal(diagnoses[0]['severity of the violation on a 0-to-3 scale'], 3);
@@ -55,7 +54,7 @@ test('listDiagnoses treats missing outcome as a violation', async () => {
 
 test('listDiagnoses returns element basics from the catalog', async () => {
   const body = await response(['0', 'linkNoText', '260101T0000', 'mix']);
-  const elementBasics = body['response content']['basics about the element'];
+  const elementBasics = body['response content']['basics about the element'] as any;
   assert.equal(elementBasics.identifier, '0');
   assert.equal(elementBasics['tag name'], 'A');
   assert.equal(elementBasics['inner text'], 'About Us');
@@ -63,7 +62,7 @@ test('listDiagnoses returns element basics from the catalog', async () => {
 
 test('listDiagnoses returns element details from the catalog', async () => {
   const body = await response(['0', 'linkNoText', '260101T0000', 'mix']);
-  const elementDetails = body['response content']['details about the element'];
+  const elementDetails = body['response content']['details about the element'] as any;
   assert.equal(elementDetails['start tag'], '<a>');
   assert.equal(elementDetails['XPath'], '/html/body/a[1]');
   assert.equal(elementDetails['x, y, width, and height of bounding box'], '10:20:80:30');
@@ -71,55 +70,55 @@ test('listDiagnoses returns element details from the catalog', async () => {
 
 test('listDiagnoses returns an error for an unknown issue ID', async () => {
   const body = await response(['0', 'nonexistentIssue', '260101T0000', 'mix']);
-  const basics = body['response content']['basics about the issue'];
+  const basics = body['response content']['basics about the issue'] as any;
   assert.ok(basics.error);
 });
 
 test('listDiagnoses returns an error for a nonexistent catalog index', async () => {
   const body = await response(['999', 'linkNoText', '260101T0000', 'mix']);
-  const basics = body['response content']['basics about the element'];
+  const basics = body['response content']['basics about the element'] as any;
   assert.ok(basics.error);
 });
 
 test('listDiagnoses returns an error for a nonexistent report', async () => {
   const body = await response(['0', 'linkNoText', '999999T9999', 'xyz']);
-  const basics = body['response content']['basics about the report'];
+  const basics = body['response content']['basics about the report'] as any;
   assert.ok(basics.error);
 });
 
 test('listDiagnoses returns guideline layer for an issue with a short WCAG code', async () => {
   const body = await response(['0', 'duplicateID', '260101T0009', 'brd']);
-  const issueBasics = body['response content']['basics about the issue'];
+  const issueBasics = body['response content']['basics about the issue'] as any;
   assert.equal(issueBasics['related WCAG standard'].layer, 'guideline');
   assert.equal(issueBasics['related WCAG standard'].identifier, '4.1');
 });
 
 test('listDiagnoses returns null tag name and inner text for a catalog item missing them', async () => {
   const body = await response(['1', 'duplicateID', '260101T0009', 'brd']);
-  const elementBasics = body['response content']['basics about the element'];
+  const elementBasics = body['response content']['basics about the element'] as any;
   assert.equal(elementBasics['tag name'], null);
   assert.equal(elementBasics['inner text'], null);
 });
 
 test('listDiagnoses returns null rule ID when ruleID equals what', async () => {
   const body = await response(['0', 'duplicateID', '260101T0009', 'brd']);
-  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'];
-  const axeDiagnosis = diagnoses.find(d => d['description of the violation'] === 'r99');
+  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'] as any;
+  const axeDiagnosis = diagnoses.find((d: any) => d['description of the violation'] === 'r99');
   assert.ok(axeDiagnosis);
   assert.equal(axeDiagnosis['identifier of the violated rule'], null);
 });
 
 test('listDiagnoses defaults count to 1 when count is missing', async () => {
   const body = await response(['1', 'duplicateID', '260101T0009', 'brd']);
-  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'];
-  const ibmDiagnosis = diagnoses.find(d => d['description of the violation'] === 'Element has no role');
+  const diagnoses = body['response content']['diagnoses of how the element exhibited the issue'] as any;
+  const ibmDiagnosis = diagnoses.find((d: any) => d['description of the violation'] === 'Element has no role');
   assert.ok(ibmDiagnosis);
   assert.equal(ibmDiagnosis['count of violations of the rule by the element'], 1);
 });
 
 test('listDiagnoses returns null for missing start tag, XPath, and bounding box', async () => {
   const body = await response(['2', 'duplicateID', '260101T0009', 'brd']);
-  const elementDetails = body['response content']['details about the element'];
+  const elementDetails = body['response content']['details about the element'] as any;
   assert.equal(elementDetails['start tag'], null);
   assert.equal(elementDetails['XPath'], null);
   assert.equal(elementDetails['x, y, width, and height of bounding box'], null);
@@ -127,6 +126,6 @@ test('listDiagnoses returns null for missing start tag, XPath, and bounding box'
 
 test('listDiagnoses returns issue error for a falsy issue ID', async () => {
   const body = await response(['0', '', '260101T0009', 'brd']);
-  const issueBasics = body['response content']['basics about the issue'];
+  const issueBasics = body['response content']['basics about the issue'] as any;
   assert.ok(issueBasics.error);
 });