@jrpool/kilotest 46.1.2 → 47.0.1

package/web/requestTest/{index.js → index.ts}

@@ -1,16 +1,16 @@
 /*
-  index.js
+  index.ts
   Records a test request.
 */
 
 // IMPORTS
 
-const {isRecommendable, processTestRequest} = require('../../util');
+import {getRequestability, processTestRequest} from '../../util.ts';
 
 // FUNCTIONS
 
-exports.answer = async (what, url, why) => {
-  const status = await isRecommendable(url);
+export const answer = async (description: string, url: string, why: string) => {
+  const status = await getRequestability(url);
   // If the target is already claimed or queued and is thus not requestable:
   if (status) {
     // Return an answer reporting this.
@@ -20,5 +20,5 @@ exports.answer = async (what, url, why) => {
     };
   }
   // Otherwise, i.e. if it is requestable, process the request.
-  return await processTestRequest('test', __dirname, what, url, why);
+  return await processTestRequest('test', import.meta.dirname, description, url, why);
 };

package/web/requestTest/{requestTest.test.js → requestTest.test.ts}

@@ -1,20 +1,20 @@
 /*
-  requestTest.test.js
-  Unit tests for web/requestTest/index.js, covering the success path of answer.
+  requestTest.test.ts
+  Unit tests for web/requestTest/index.ts, covering the success path of answer.
 */
 
 // IMPORTS
 
-const {test, before, after, beforeEach} = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const {parse} = require('node-html-parser');
+import {test, before, after, beforeEach} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {parse} from 'node-html-parser';
 
 // CONSTANTS
 
-const fixtureDBDir = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
-const recsPath = path.join(fixtureDBDir, 'jobs', 'recs.json');
+import {fixtureDBDir} from '../../test/dbFixture.ts';
+const testRequestsPath = path.join(fixtureDBDir, 'jobs', 'testRequests.json');
 
 // SETUP AND TEARDOWN
 
@@ -24,8 +24,8 @@ before(async () => {
 });
 
 beforeEach(async () => {
-  // Reset recs.json and clean job directories before each test.
-  await fs.writeFile(recsPath, '{}\n');
+  // Reset testRequests.json and clean job directories before each test.
+  await fs.writeFile(testRequestsPath, '{}\n');
   for (const sub of ['claimed', 'queue', 'failed']) {
     const dir = path.join(fixtureDBDir, 'jobs', sub);
     await fs.mkdir(dir, {recursive: true});
@@ -42,8 +42,8 @@ beforeEach(async () => {
 });
 
 after(async () => {
-  // Restore recs.json and clean job directories after all tests.
-  await fs.writeFile(recsPath, '{}\n');
+  // Restore testRequests.json and clean job directories after all tests.
+  await fs.writeFile(testRequestsPath, '{}\n');
   for (const sub of ['claimed', 'queue', 'failed']) {
     const dir = path.join(fixtureDBDir, 'jobs', sub);
     await fs.mkdir(dir, {recursive: true});
@@ -63,8 +63,8 @@ after(async () => {
 
 test('answer returns ok with a populated answer page for a valid test request', {timeout: 500}, async () => {
   // Require the module after DB_DIR is set.
-  const {answer} = require('./index');
-  const result = await answer(
+  const {answer} = await import('./index.ts');
+  const result: any = await answer(
     'Test Page', 'https://example.com/test-success', 'Because accessibility'
   );
   assert.equal(result.status, 'ok');
@@ -82,7 +82,7 @@ test('answer returns ok with a populated answer page for a valid test request',
 });
 
 test('answer returns an error when the URL is already queued', {timeout: 500}, async () => {
-  const {answer} = require('./index');
+  const {answer} = await import('./index.ts');
   // Create a queued job with the target URL.
   const queueDir = path.join(fixtureDBDir, 'jobs', 'queue');
   const jobPath = path.join(queueDir, 'queuedJob.json');
@@ -91,7 +91,7 @@ test('answer returns an error when the URL is already queued', {timeout: 500}, a
     target: {what: 'Queued Page', url: 'https://example.com/queued'}
   }));
   try {
-    const result = await answer(
+    const result: any = await answer(
       'Queued Page', 'https://example.com/queued', 'Because accessibility'
     );
     assert.equal(result.status, 'error');
@@ -107,9 +107,9 @@ test('answer returns an error when the URL is already queued', {timeout: 500}, a
   }
 });
 
-test('answer returns an error for an invalid recommendation', {timeout: 500}, async () => {
-  const {answer} = require('./index');
-  const result = await answer('', 'not-a-url', 'why');
+test('answer returns an error for an invalid request', {timeout: 500}, async () => {
+  const {answer} = await import('./index.ts');
+  const result: any = await answer('', 'not-a-url', 'why');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });

package/web/requestTestForm/index.html

@@ -6,18 +6,18 @@
     <meta name="publisher" content="Jonathan Robert Pool">
     <meta name="creator" content="Jonathan Robert Pool">
     <meta name="keywords" content="report,accessibility,a11y">
-    <title>Test recommendation | Kilotest</title>
+    <title>Test request | Kilotest</title>
     <link rel="icon" href="/favicon.ico">
     <link rel="stylesheet" href="/style.css">
   </head>
   <body>
     <main>
-      <h1><a href="/">Kilotest</a>: Test recommendation</h1>
-      <p>You may recommend a web page for testing by submitting the following form. All answers are required.</p>
+      <h1><a href="/">Kilotest</a>: Test request</h1>
+      <p>You may request that a web page be tested by submitting the following form. All answers are required.</p>
       <form action="/requestTest.html" method="post">
         <p><label>
           Propose a name for the page.<br>
-          <input size="50" maxlength="70" name="what" required>
+          <input size="50" maxlength="70" name="description" required>
         </label></p>
         <p><label>
           What is the URL (starting with <code>https://</code>)?<br>

package/web/requestTestForm/index.ts

@@ -0,0 +1,21 @@
+/*
+  index.ts
+  Serves a form for requesting a test.
+*/
+
+// IMPORTS
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// FUNCTIONS
+
+export const answer = async (): Promise<{status: string; answerPage: string}> => {
+  // Get the test request form template.
+  const answerPage = await fs.readFile(path.join(import.meta.dirname, 'index.html'), 'utf8');
+  // Return it.
+  return {
+    status: 'ok',
+    answerPage
+  };
+};

package/web/requestTestForm/{requestTestForm.test.js → requestTestForm.test.ts}

@@ -1,14 +1,14 @@
 /*
-  requestTestForm.test.js
-  Unit tests for web/requestTestForm/index.js.
+  requestTestForm.test.ts
+  Unit tests for web/requestTestForm/index.ts.
 */
 
 // IMPORTS
 
-const {test} = require('node:test');
-const assert = require('node:assert/strict');
-const {parse} = require('node-html-parser');
-const {answer} = require('./index');
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {parse} from 'node-html-parser';
+import {answer} from './index.ts';
 
 // TESTS
 
@@ -17,7 +17,7 @@ test('requestTestForm returns an ok status with valid HTML', async () => {
   assert.equal(result.status, 'ok');
   assert.ok(result.answerPage);
   const html = parse(result.answerPage);
-  assert.equal(html.querySelector('title').text, 'Test recommendation | Kilotest');
+  assert.equal(html.querySelector('title')?.text, 'Test request | Kilotest');
 });
 
 test('requestTestForm includes a form that posts to /requestTest.html', async () => {
@@ -29,12 +29,12 @@ test('requestTestForm includes a form that posts to /requestTest.html', async ()
   assert.equal(form.getAttribute('method'), 'post');
 });
 
-test('requestTestForm includes required inputs for what, url, and why', async () => {
+test('requestTestForm includes required inputs for description, url, and why', async () => {
   const result = await answer();
   const html = parse(result.answerPage);
   const inputs = html.querySelectorAll('input');
   const names = inputs.map(input => input.getAttribute('name'));
-  assert.ok(names.includes('what'));
+  assert.ok(names.includes('description'));
   assert.ok(names.includes('url'));
   assert.ok(names.includes('why'));
 });

package/web/rewindReportsForm/index.ts

@@ -0,0 +1,18 @@
+/*
+  index.ts
+  Serves a form for deleting latest superseding reports.
+*/
+
+// IMPORTS
+
+import {reportDeletionForm} from '../reportDeletion.ts';
+
+// FUNCTIONS
+
+// Returns a form for deleting latest superseding reports.
+export const answer = async (_: any, search: string) => reportDeletionForm(import.meta.dirname, search, {
+  intro: 'Choose the latest superseding reports to delete.',
+  emptyIntro: 'Each target has only 1 report, so there are no reports to delete.',
+  failurePrefix: 'Deleting latest superseding reports failed',
+  isDeletable: (specs, index) => specs[index - 1]?.url === specs[index]?.url && specs[index + 1]?.url !== specs[index]?.url
+});

package/web/rewindReportsForm/{rewindReportsForm.test.js → rewindReportsForm.test.ts}

@@ -1,23 +1,23 @@
 /*
-  rewindReportsForm.test.js
-  Unit tests for web/rewindReportsForm/index.js.
+  rewindReportsForm.test.ts
+  Unit tests for web/rewindReportsForm/index.ts.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const fs = require('fs/promises');
-const {parse} = require('node-html-parser');
-const {answer} = require('./index');
-const {reportsPath} = require('../../util');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import fs from 'fs/promises';
+import {parse} from 'node-html-parser';
+import {answer} from './index.ts';
+import {reportsPath} from '../../util.ts';
 
 // SETUP AND TEARDOWN
 
 const savedAuthCode = process.env.AUTH_CODE;
 const savedDBDir = process.env.DB_DIR;
-const fixtureDBDir = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+import {fixtureDBDir} from '../../test/dbFixture.ts';
 
 before(() => {
   process.env.AUTH_CODE = 'test-auth-code';
@@ -52,7 +52,7 @@ test('rewindReportsForm returns an error for an invalid auth code', async () =>
 test('rewindReportsForm returns an error when deleting a nonexistent report', async () => {
   const result = await answer(null, 'authCode=test-auth-code&report=999999T9999-nope');
   assert.equal(result.status, 'error');
-  assert.ok(result.message.includes('Deleting latest superseding reports'));
+  assert.ok(result.message?.includes('Deleting latest superseding reports'));
 });
 
 test('rewindReportsForm deletes a latest superseding report with valid auth code', async () => {

package/web/tutorialAI/index.html

@@ -0,0 +1,184 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="publisher" content="Jonathan Robert Pool">
+    <meta name="creator" content="Jonathan Robert Pool">
+    <meta name="keywords" content="large language models,tools,model context protocol">
+    <meta name="description" content="Kilotest tutorial: how to connect an AI platform to Kilotest for technical analysis">
+    <title>Tutorial: Connect an AI Platform | Kilotest</title>
+    <link rel="icon" href="/favicon.ico">
+    <link rel="stylesheet" href="/style.css">
+  </head>
+  <body>
+    <main>
+      <h1>Connect an AI Platform to Kilotest</h1>
+      <h2>What you can do here</h2>
+      <ul>
+        <li>Do you ask questions to artificial intelligence (AI) assistants?</li>
+        <li>Do some of your questions ask for technical information?</li>
+      </ul>
+      <p>If you answered both of these questions with <q>yes</q>, this tutorial is designed for you.</p>
+      <h2>AI needs your help</h2>
+      <p>When you get AI help, you use AI platforms to interact with large language models (LLMs). LLMs are superb at understanding your questions, fetching information for you, and formulating answers from that information. But LLMs are <strong>not</strong> good at performing technical tasks to produce the accurate information they need. For those tasks, LLMs use <em>tools</em>. If you ask an LLM a question that requires a tool, you <strong>cannot assume</strong> that the LLM will know how to discover that tool. Typically, the LLM will try to answer you without the tool and will give you an inferior answer: superficial, vague, incomplete, inaccurate, or even fabricated. To ensure that the LLM uses the right tool, you can tell the AI platform to make the tool available to its LLMs.</p>
+      <p>This tutorial shows you how to do that.</p>
+      <h2>Let us begin with a concrete example</h2>
+      <p>Suppose the AI platform you want to use is Claude, and you will use it in a web browser.</p>
+      <p>Also suppose you will be asking an LLM on that platform to give you technical details about software quality: specifically, about the quality of a particular web page.</p>
+      <p>For that task, the LLM will need a tool that can test a web page to discover quality defects and report those defects to the LLM.</p>
+      <p>Finally, suppose you know about a tool that has that capability: Kilotest. You also know the URL that Kilotest makes available to LLMs: <code>https://kilotest.com/mcp</code>.</p>
+      <h2>What to do</h2>
+      <p>You can solve this problem with two steps.</p>
+      <h3>Step 1: Become a user</h3>
+      <p>If you are not already a user of the Claude AI platform, register yourself on it as a user. You can do this for free. Navigate to <a href="https://claude.ai/login">https://claude.ai/login</a> and use either Google or your email address to create an account. After you proceed through the substeps of creating a <q>Free plan</q> account, you are on the <a href="https://claude.ai/new">home page of a new task</a>.</p>
+      <h3>Step 2: Add a connector</h3>
+      <p>Now you are ready to add a connector to the Claude AI platform.</p>
+      <p>The page has a toolbar on the left side. Click it to expand it, so you can see labels, not only icons.</p>
+      <p>Now click the <q>Customize</q> tool.</p>
+      <p>A dialog opens. In the <q>Customize</q> list, click <q>Connectors</q>.</p>
+      <p>The dialog changes to a <q>Connectors</q> view.</p>
+      <p>In the <q>Add</q> dropdown list, click <q>Add custom connector</q>.</p>
+      <p>A subdialog opens, titled <q>Add custom connector</q>. It contains 4 inputs.</p>
+      <ul>
+        <li>Enter <q>Kilotest</q> into the <q>Name</q> input.</li>
+        <li>Enter <q>https://kilotest.com/mcp</q> into the <q>Remote MCP server URL</q> input.</li>
+        <li>Leave the OAuth inputs empty.</li>
+        <li>Submit the form by clicking the <q>Add</q> button.</li>
+      </ul>
+      <p>The dialog changes to a tool permissions view for the Kilotest connector. You can decide whether an LLM needs your approval to use each of the tools that Kilotest makes available.</p>
+      <p>Close the dialog by clicking the <code>x</code> button in the top-right corner or by pressing the <code>Escape</code> key.</p>
+      <h2>Finished!</h2>
+      <p>Now the platform will make the connector available to its LLMs.</p>
+      <p>Here is a simple test for you to verify that your configuration works:</p>
+      <ul>
+        <li>In the <q>How can I help you today?</q> input, choose which model you want to use.</li>
+        <li>Enter the question: <q>What quality issues exist on the World Wide Web Consortium home page?</q></li>
+        <li>Click the <q>Send message</q> up-arrow button or press the <code>Enter</code> key to submit your question.</li>
+        <li>From the answer that you get, determine whether the model used any Kilotest tools for this task.</li>
+      </ul>
+      <h2>Did this work?</h2>
+      <p>If the model used any Kilotest tools, congratulations! You know how to add tool power to the LLMs on one of the major AI platforms.</p>
+      <p>But what if it did <strong>not</strong> work? If an LLM fails to use the Kilotest connector when it should, or if you need to explicitly tell the LLM to use the connector, something is wrong, and we want to know about your experience. Please use the <a href="tutorialAIComment.html">comment form</a> to tell us about it.</p>
+      <p>You can also submit an issue on the <a href="https://github.com/jrpool/kilotest/issues">Kilotest GitHub repository</a>.</p>
+      <section id="suggest-improvement" class="main">
+        <h2>Suggest improvements</h2>
+        <p>Please submit suggestions for improving this tutorial below. The Kilotest managers will review them.</p>
+        <form id="comment-form" novalidate>
+          <p id="comment-label">Your suggestions (20–1000 characters):</p>
+          <textarea
+            id="comment-text"
+            name="content"
+            maxlength="1000"
+            minlength="20"
+            rows="5"
+            autocomplete="off"
+            aria-labelledby="comment-label"
+            aria-describedby="char-count-msg"
+          ></textarea>
+          <p class="char-count" id="char-count-msg"><span id="char-remaining">1000</span> characters remaining</p>
+          <button type="submit" id="comment-submit">Submit suggestions</button>
+        </form>
+        <div role="status" id="comment-diagnosis" aria-live="polite" aria-atomic="true" class="comment-diagnosis"></div>
+      </section>
+    </main>
+    <script>
+      const commentText = document.getElementById('comment-text');
+      const charRemaining = document.getElementById('char-remaining');
+      const charCountMsg = document.getElementById('char-count-msg');
+      const commentFeedback = document.getElementById('comment-diagnosis');
+      const commentSubmit = document.getElementById('comment-submit');
+
+      commentText.addEventListener('input', function () {
+        const remaining = 1000 - this.value.length;
+        charRemaining.textContent = remaining;
+        charCountMsg.className = remaining <= 100 ? 'char-count low' : 'char-count';
+      });
+
+      document.getElementById('comment-form').addEventListener('submit', async function (e) {
+        e.preventDefault();
+        const content = commentText.value.trim();
+        commentFeedback.className = 'comment-diagnosis';
+        commentFeedback.textContent = '';
+        if (!content) {
+          commentFeedback.className = 'comment-diagnosis error';
+          commentFeedback.textContent = 'Please enter your feedback before submitting.';
+          return;
+        }
+        commentSubmit.disabled = true;
+        try {
+          const response = await fetch('/tutorialAIComment.html', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({content})
+          });
+          const data = await response.json();
+          if (data.status === 'ok') {
+            commentFeedback.className = 'comment-diagnosis success';
+            commentFeedback.textContent =
+              'Thank you! Your suggestion has been saved and will be reviewed by the tutorial authors.';
+            this.reset();
+            charRemaining.textContent = '1000';
+            charCountMsg.className = 'char-count';
+          } else {
+            commentFeedback.className = 'comment-diagnosis error';
+            commentFeedback.textContent =
+              data.message || 'Your suggestion could not be saved. Please try again later.';
+            commentSubmit.disabled = false;
+          }
+        } catch (_) {
+          commentFeedback.className = 'comment-diagnosis error';
+          commentFeedback.textContent =
+            'A connection error occurred. Please check your connection and try again.';
+          commentSubmit.disabled = false;
+        }
+      });
+    </script>
+    <style>
+      #suggest-improvement {
+        margin-top: 2rem;
+        padding-top: 2rem;
+        border-top: solid 1px #ccc;
+      }
+      #comment-form {
+        margin: 1rem 0;
+      }
+      #comment-form p {
+        margin: 0.5rem 0;
+      }
+      #comment-text {
+        width: 100%;
+        padding: 0.5rem;
+        border: solid 1px #ccc;
+        border-radius: 0.25rem;
+        font-family: system-ui, sans-serif;
+        font-size: 1rem;
+      }
+      .char-count {
+        font-size: 0.875rem;
+        color: #666;
+        margin: 0.25rem 0;
+      }
+      .char-count.low {
+        color: #c80;
+        font-weight: 700;
+      }
+      .comment-diagnosis {
+        margin-top: 0.75rem;
+        padding: 0.5rem 0.75rem;
+        border-radius: 0.25rem;
+        min-height: 1.5rem;
+      }
+      .comment-diagnosis.error {
+        background: #fdecea;
+        border-left: solid 4px #c0392b;
+        color: #5a1a1a;
+      }
+      .comment-diagnosis.success {
+        background: #e6f4ea;
+        border-left: solid 4px #2d7a2d;
+        color: #1a4a1a;
+      }
+    </style>
+  </body>
+</html>

package/web/tutorialAI/index.ts

@@ -0,0 +1,80 @@
+/*
+  index.ts
+  Serves the AI agent tutorial (Connect an AI Platform to Kilotest) and saves AI tutorial comments.
+*/
+
+// IMPORTS
+
+import {sendAlert} from '../../alerts.ts';
+import {checkCommentLength, getJSON} from '../../util.ts';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// FUNCTIONS (helpers)
+
+const getCommentsPath = () => process.env.TUTORIAL_AI_COMMENTS_PATH || path.join(import.meta.dirname, '../../db/comments/tutorialAI.json');
+
+// FUNCTIONS
+
+// Strips HTML tags and control characters, trims, and limits to 1000 characters.
+const sanitize = (str: string) => str
+  .replace(/<[^>]*>/g, '')
+  .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '')
+  .trim()
+  .slice(0, 1000);
+
+// Returns the AI tutorial page.
+export const answer = async () => {
+  const answerPage = await fs.readFile(path.join(import.meta.dirname, 'index.html'), 'utf8');
+  return {
+    status: 'ok',
+    answerPage
+  };
+};
+
+// Sanitizes and saves an AI tutorial comment to comments.json.
+export const handleComment = async (content: unknown) => {
+  if (!content || typeof content !== 'string') {
+    return {status: 'error', message: 'No content provided'};
+  }
+  // Check length on the raw content.
+  const lengthCheck = checkCommentLength(content);
+  if (lengthCheck.status === 'error') {
+    return lengthCheck;
+  }
+  const commentsPath = getCommentsPath();
+  let comments: any[] = [];
+  try {
+    const existing = await fs.readFile(commentsPath, 'utf8');
+    comments = JSON.parse(existing);
+  }
+  catch {
+    // Initialize empty comments array.
+  }
+  const sanitized = sanitize(content);
+  if (!sanitized) {
+    return {status: 'error', message: 'Comment is empty after sanitization'};
+  }
+  // Check for duplicate submissions within the last 1000 seconds.
+  const duplicates = comments
+  .filter(comment => new Date(comment.dateTime).getTime() > Date.now() - 1000000)
+  .filter(comment => comment.content === sanitized);
+  if (duplicates.length) {
+    return {
+      status: 'error',
+      message: 'Your comment repeats a recently submitted one, but you are welcome to submit a different comment'
+    };
+  }
+  // Add the comment to the existing ones, using dateTime format.
+  comments.push({
+    dateTime: new Date().toISOString(),
+    content: sanitized
+  });
+  // Ensure the comments directory exists.
+  await fs.mkdir(path.dirname(commentsPath), {recursive: true});
+  // Save the revised comments.
+  await fs.writeFile(commentsPath, getJSON(comments));
+  // Send an alert to the manager.
+  await sendAlert('New AI tutorial comment received', 'A new AI tutorial comment has been received.');
+  return {status: 'ok'};
+};