@jrpool/kilotest 47.0.1 → 49.0.0

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"f44e6b44-375e-4007-879a-19e4e5ed34a0","pid":90042,"procStart":"Sun Sep 20 03:19:03 2026","acquiredAt":1789874948676}

package/api/requestFeature.test.ts

@@ -32,7 +32,9 @@ test('requestFeature rejects an empty feature request', async () => {
   const body = await response(['']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error);
-  assert.ok(!logged.some(line => line.startsWith('WARNING (MCP feature request received)')));
+  assert.ok(
+    !logged.some(line => line.startsWith('WARNING (Kilotest: MCP feature request received)'))
+  );
 });
 
 test('requestFeature accepts a non-empty feature request and notifies the manager', async () => {
@@ -42,7 +44,7 @@ test('requestFeature accepts a non-empty feature request and notifies the manage
   assert.ok(details['date and time received']);
   assert.equal(details.disposition, 'received and logged; manager notified');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (MCP feature request received)')
+    line.startsWith('WARNING (Kilotest: MCP feature request received)')
     && line.includes('Add a dark mode toggle')
   ));
 });

package/api/requestFeature.ts

@@ -30,7 +30,7 @@ export const response = async (args: string[]) => {
   // If the requested feature or improvement exists:
   if (feature) {
     // Notify the manager.
-    await sendAlert('MCP feature request received', feature);
+    await sendAlert('Kilotest: MCP feature request received', feature);
     // Add the disposition to the response content.
     responseContent['details about your request'] = {
       'date and time received': new Date().toISOString(),

package/api/requestRetest.test.ts

@@ -46,22 +46,30 @@ after(() => {
 
 test('requestRetest rejects a nonexistent report', async () => {
   const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
-  assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('does not exist'));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a superseded report', async () => {
+  // 260101T0000-mix is an earlier report of "Mixed Outcomes Page" than 260202T0000-new,
+  // so it is superseded and processTestRequest returns 'superseded', reported via the
+  // disposition rather than details.error.
   const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
-  assert.ok(details.error.includes('later report'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(
+    disposition['what happens next'].includes('a later report about a page with the same description is available.')
+  );
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a reason shorter than 20 characters', async () => {
   const body = await response(['260101T0001', 'ct', 'short']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a reason longer than 100 characters', async () => {
@@ -69,7 +77,58 @@ test('requestRetest rejects a reason longer than 100 characters', async () => {
   const body = await response(['260101T0001', 'ct', longReason]);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+test('requestRetest rejects a report matching a claimed job by description', async () => {
+  // 260101T0001-ct is the "All CantTell Page" report.
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'All CantTell Page', url: 'https://example.com/unrelated'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('requestRetest rejects a report matching a queued job by URL', async () => {
+  // 260101T0001-ct's URL is https://example.com/canttell.
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/canttell'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('requestRetest rejects a duplicate request', async () => {
+  await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('an identical request is already awaiting approval.'));
 });
 
 test('requestRetest accepts a valid retest request for the latest report of a page', async () => {
@@ -78,7 +137,7 @@ test('requestRetest accepts a valid retest request for the latest report of a pa
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Mixed Outcomes Page');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (Kilotest: new retest request in the API)')
+    line.startsWith('WARNING (Kilotest: new retest request awaits approval)')
     && line.includes('Mixed Outcomes Page')
     && line.includes('https://example.com/mixed')
   ));

package/api/requestRetest.ts

@@ -6,8 +6,8 @@
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts, processTestRequest} from './util.ts';
-import {getReportExtracts, getReportExtract} from '../util.ts';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {processTestRequest} from '../util.ts';
 import {requestRetestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -22,51 +22,67 @@ export const response = async (args: string[]) => {
   const [timeStamp = '', jobID = '', reason = ''] = args;
   const thisHost = getThisHost();
   const reasonLength = reason.length;
-  // Get data on the report.
-  const reportExtract = await getReportExtract(timeStamp, jobID);
   // Initialize the response-content properties.
   let requestDetails: ResponseContent['details about your request'];
   let requestDisposition: ResponseContent['disposition of your request'] = null;
-  // If this failed:
-  if ('error' in reportExtract) {
-    requestDetails = {
-      error: 'request invalid: the specified existing report is not an available report'
-    };
-  }
-  // Otherwise, if the report has been superseded:
-  else if (
-    (await getReportExtracts(true))
-    .every(extract => extract.timeStamp !== timeStamp || extract.jobID !== jobID)
-  ) {
-    requestDetails = {
-      error: 'request invalid: a later report about the page exists'
-    };
-  }
-  // Otherwise, if the encoded reason is too short or too long:
-  else if (reasonLength < 20 || reasonLength > 100) {
+  // If the encoded reason is too short or too long:
+  if (reasonLength < 20 || reasonLength > 100) {
     requestDetails = {
       error: 'request invalid: your reason is not between 20 and 100 characters long'
     }
   }
-  // Otherwise, i.e. if getting the report succeeded and the request is valid:
+  // Otherwise, i.e. if the request is facially valid:
   else {
-    // Process the request.
-    await processTestRequest('retest', reportExtract.description, reportExtract.url, reason);
-    // Add details about the request.
-    requestDetails = {
-      'date and time received': new Date().toISOString(),
-      'page to be retested': {
-        'description': reportExtract.description,
-        'URL': reportExtract.url
-      },
-      'reason why the page should be retested': reason
-    };
-    // Add information about the disposition of the request.
-    requestDisposition = {
-      'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
-      'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
-      'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
-    };
+    // Process the request. This resolves the cited report's description and URL itself.
+    const processResult = await processTestRequest(reason, {timeStamp, jobID});
+    // If the cited report does not exist:
+    if (processResult.result === 'nonreport') {
+      requestDetails = {
+        error: 'request invalid: the specified report does not exist'
+      };
+    }
+    // Otherwise, i.e. if the cited report was found:
+    else {
+      const {result: requestResult, description, url} = processResult;
+      // Add details about the request.
+      requestDetails = {
+        'date and time received': new Date().toISOString(),
+        'page to be retested': {
+          'description': description,
+          'URL': url
+        },
+        'reason why the page should be retested': reason
+      };
+      // Add information about the disposition of the request.
+      if (requestResult === 'ok') {
+        requestDisposition = {
+          'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
+          'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
+          'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
+        };
+      }
+      else {
+        const failureFact = 'Your request will not be processed, because ';
+        let failureReason: string;
+        if (requestResult === 'description') {
+          failureReason = 'a request to test a page with the same description is already approved.'
+        }
+        else if (requestResult === 'url') {
+          failureReason = 'a request to test a page with the same URL is already approved.'
+        }
+        else if (requestResult === 'superseded') {
+          failureReason = 'a later report about a page with the same description is available.'
+        }
+        else {
+          failureReason = 'an identical request is already awaiting approval.'
+        }
+        requestDisposition = {
+          'what happens next': `${failureFact}${failureReason}`,
+          'how you can check for completion': 'Not applicable.',
+          'how a web user can check for completion': 'Not applicable.'
+        }
+      }
+    }
   }
   // Create the response content.
   const responseContent: ResponseContent = {

package/api/requestTest.test.ts

@@ -47,34 +47,90 @@ after(() => {
 test('requestTest rejects an empty description', async () => {
   const body = await response(['', 'https://example.com/test', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a description longer than 100 characters', async () => {
   const longWhat = 'x'.repeat(101);
   const body = await response([longWhat, 'https://example.com/test', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a URL shorter than 12 characters', async () => {
   const body = await response(['Test Page', 'short', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a syntactically invalid URL with the correct length', async () => {
   const body = await response(['Test Page', 'not-a-valid-url', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('invalid URL'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects an already-tested page', async () => {
   const body = await response(['Mixed Outcomes Page', 'https://example.com/mixed', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
-  assert.ok(details.error.includes('already been tested'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  // A report for this description and URL already exists, so processTestRequest
+  // returns 'retest' and the failure is reported via the disposition, not details.error.
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(
+    disposition['what happens next']
+    .includes('a report about a page with the same description and URL is available.')
+  );
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
+});
+
+test('requestTest rejects a page matching a claimed job by description', async () => {
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'Claimed Test Page', url: 'https://example.com/claimed-job'}
+  }));
+  try {
+    const body = await response(['Claimed Test Page', 'https://example.com/other-url', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('requestTest rejects a page matching a queued job by URL', async () => {
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/queued-url'}
+  }));
+  try {
+    const body = await response(['A Different Page', 'https://example.com/queued-url', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('requestTest rejects a duplicate request', async () => {
+  await response(['Duplicate API Page', 'https://example.com/dup-api', 'A reason that is long enough.']);
+  const body = await response(['Duplicate API Page', 'https://example.com/dup-api', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('an identical request is already awaiting approval.'));
 });
 
 test('requestTest accepts a valid new page request', async () => {
@@ -83,7 +139,7 @@ test('requestTest accepts a valid new page request', async () => {
   assert.equal(details.error, undefined);
   assert.equal(details['page to be tested'].description, 'Brand New Page');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (Kilotest: new test request in the API)')
+    line.startsWith('WARNING (Kilotest: new test request awaits approval)')
     && line.includes('Brand New Page')
     && line.includes('https://example.com/brandnew')
   ));

package/api/requestTest.ts

@@ -6,8 +6,8 @@
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts, processTestRequest} from './util.ts';
-import {getReportExtracts, isURL} from '../util.ts';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {isURL, processTestRequest} from '../util.ts';
 import {requestTestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -45,36 +45,46 @@ export const response = async (args: string[]) => {
   }
   // Otherwise, i.e. if the description and URL are valid:
   else {
-    // Get an extract of the available reports.
-    const reportExtracts = await getReportExtracts();
-    // If any report is on a page with the specified description and URL:
-    if (
-      reportExtracts.some(extract => extract.description === description && extract.url === url)
-    ) {
-      requestDetails = {
-        error: 'request invalid: the page has already been tested and its report is available'
-      };
-    }
-    // Otherwise, i.e. if none is on the page:
-    else {
-      // Process the request.
-      await processTestRequest('test', description, url, reason);
-      // Add details about the request.
-      requestDetails = {
-        'date and time received': new Date().toISOString(),
-        'page to be tested': {
-          description,
-          URL: url
-        },
-        'reason why the page should be tested': reason
-      };
-      // Add information about the disposition of the request.
+    // Process the request.
+    const {result: requestResult} = await processTestRequest(reason, {description, url});
+    // Add details about the request.
+    requestDetails = {
+      'date and time received': new Date().toISOString(),
+      'page to be tested': {
+        description,
+        URL: url
+      },
+      'reason why the page should be tested': reason
+    };
+    // Add information about the disposition of the request.
+    if (requestResult === 'ok') {
       requestDisposition = {
         'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
         'how you can check for completion': 'You can call the listReports tool to learn whether the page has been tested and a report is available.',
         'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been tested and a report is available.`
       };
     }
+    else {
+      const failureFact = 'Your request will not be processed, because ';
+      let failureReason: string;
+      if (requestResult === 'description') {
+        failureReason = 'a request to test a page with the same description is already approved.'
+      }
+      else if (requestResult === 'url') {
+        failureReason = 'a request to test a page with the same URL is already approved.'
+      }
+      else if (requestResult === 'retest') {
+        failureReason = 'a report about a page with the same description and URL is available.'
+      }
+      else {
+        failureReason = 'an identical request is already awaiting approval.'
+      }
+      requestDisposition = {
+        'what happens next': `${failureFact}${failureReason}`,
+        'how you can check for completion': 'Not applicable.',
+        'how a web user can check for completion': 'Not applicable.'
+      }
+    }
   }
   // Create the response content.
   const responseContent: ResponseContent = {

package/api/util.test.ts

@@ -7,7 +7,8 @@
 
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
-import {getReportBasics, getResponseMetadata, getRuleEngineFacts, getRuleEnginesFacts, getIssueSpec, getToolsFacts, processTestRequest} from './util.ts';
+import {getReportBasics, getResponseMetadata, getRuleEngineFacts, getRuleEnginesFacts, getIssueSpec, getToolsFacts} from './util.ts';
+import {processTestRequest} from '../util.ts';
 
 // SETUP
 
@@ -98,10 +99,10 @@ test('getReportBasics returns an error for a report whose extract cannot be read
 test('processTestRequest returns an error for a duplicate request', async () => {
   process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
   // Submit the same request twice; the second should be a duplicate.
-  await processTestRequest('test', 'Dup Page', 'https://example.com/dup', 'A reason that is long enough.');
-  const result: any = await processTestRequest('test', 'Dup Page', 'https://example.com/dup', 'A reason that is long enough.');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Duplicate request');
+  const target = {description: 'Dup Page', url: 'https://example.com/dup'};
+  await processTestRequest('A reason that is long enough.', target);
+  const {result} = await processTestRequest('A reason that is long enough.', target);
+  assert.equal(result, 'duplicate');
   if (savedDBDir !== undefined) {
     process.env.DB_DIR = savedDBDir;
   }

package/api/util.ts

@@ -5,18 +5,15 @@
 
 // IMPORTS
 
-import {sendAlert} from '../alerts.ts';
 import {
   getAgoDays,
   getReportExtracts,
   getNowStamp,
-  getPlainText,
   getRandomString,
   getReportExtract,
   getReportStats,
   objectSort,
-  ruleEngines,
-  addTestRequest
+  ruleEngines
 } from '../util.ts';
 import type {ReportExtract} from '../util.ts';
 import {issues as issueSpecs} from 'testaro-issues';
@@ -83,6 +80,7 @@ export const getRuleEnginesFacts = (ruleEngineIDSet: Iterable<string>) => {
 // getReportExtracts, it carries a superseded flag; otherwise the flag is computed.
 // With an extract provided, failure is impossible, so the return type narrows
 // to ReportBasics; without one, an error object may be returned.
+// XXX Why are these overloads necessary? Can't we just have one function?
 export function getReportBasics(
   timeStamp: string, jobID: string, extract: ReportExtract
 ): Promise<ReportBasics>;
@@ -151,23 +149,3 @@ export const getIssueSpec = (issueID: string) => {
   // Otherwise, i.e. if it does not exist, return this.
   return null;
 };
-// Processes a test or retest request from the API.
-export const processTestRequest = async (testType: string, description: string, url: string, why: string): Promise<{status: string; message: string} | undefined> => {
-  // Get an email-safe version of the reason.
-  const plainWhy = getPlainText(why);
-  // Add the test request as a transaction.
-  const updateResult = await addTestRequest(description, url, plainWhy);
-  // If the request was a duplicate:
-  if (updateResult.error === 'duplicate') {
-    // Return this.
-    return {
-      status: 'error',
-      message: 'Duplicate request'
-    };
-  }
-  // Otherwise, i.e. if it was not a duplicate, alert a manager about it.
-  await sendAlert(
-    `Kilotest: new ${testType} request in the API`,
-    `Target: ${description}\nURL: ${url}\nReason: ${plainWhy}`
-  );
-};