@jrpool/kilotest 58.2.0 → 59.0.0

package/docs/SERVICE.md

@@ -323,7 +323,19 @@ Both logs are rotated; see “PM2 log rotation” above for the application log
 
 ## Version management
 
-When a new version of the `kilotest` package has been published, the service can be updated as follows:
+When the Kilotest web, API, or MCP interface is revised in a feature branch:
+
+1. Update the version in `package.json`
+1. Update the version in `server.json`
+1. Update the version and any changes in the API in `lhm.plugin.json`
+1. If the API has changed, run the `generate:openapi` script
+1. Execute the command `npx @lobehub/market-cli plugin update --dir .`
+1. Commit and push the changes to the feature branch
+1. Create a pull request to merge the feature branch into `main`
+1. Once the checks succeed, squash and merge the branch into `main`
+1. Execute `npm publish`
+
+When a new version of the `kilotest` package has been published, update the service as follows:
 
 1. Connect to the server: `ssh linuxuser@kilotest.com`
 1. Navigate to the package root: `cd /opt/jpdev/kilotest`
@@ -331,7 +343,6 @@ When a new version of the `kilotest` package has been published, the service can
 1. Delete the record of that discard: `git stash drop`
 1. Fetch and merge the new version: `git pull`
 1. Update the dependencies: `npm update`
-1. Update the Playwright browsers: `npx playwright install`
 1. Restart the service: `pm2 restart kilotest`
 
 ## Branch protection
@@ -498,9 +509,9 @@ Kilotest records basic counts of how it is used, so the maintainer can answer qu
 
 `recordMetric(category, name)`, in `util.ts`, increments a count for a `(category, name)` pair and writes the result to `db/metrics.json`. It is called from three places:
 
-- The generic `.html` GET dispatch in `index.ts`, once per successfully served web page, recorded under the `pageViews` category by page name (for example `tutorialWeb`, `listReports`), unless the page is a manager-only page (see "Manager page activity" below), in which case it is recorded there instead.
+- The generic `.html` GET dispatch in `index.ts`, once per successfully served web page, recorded under the `pageViews` category by page name (for example `tutorialWeb`, `listPages`), unless the page is a manager-only page (see "Manager page activity" below), in which case it is recorded there instead.
 - The home page (`/` and `/index.html`), served by its own branch in `index.ts` rather than through the generic `.html` dispatch, recorded under `pageViews` as `index`.
-- Each of the 9 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listReports`, `requestNewTest`).
+- Each of the 9 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listPages`, `requestNewTest`).
 - The `/api/*` GET and POST service branches in `index.ts`, once per call, recorded under the `apiOperations` category by operation name.
 
 `db/metrics.json` also stores a `since` time stamp, set when the file is first created, so the counts can be read as "since this date" rather than assumed to cover Kilotest's entire history. `getMetrics()` backfills any category absent from an existing `db/metrics.json` (for example one written before a category such as `managerActivity` existed), so an older file remains readable rather than causing every subsequent request to error.
@@ -513,7 +524,7 @@ This exclusion exists because manager pages reflect the maintainer operating Kil
 
 #### Excluding the maintainer's own manual testing
 
-The manager-page exclusion above only keeps the maintainer's use of manager-only pages out of `pageViews`; it does not, by itself, keep the maintainer's manual testing of *ordinary* pages (for example clicking through `tutorialWeb.html` or `listReports.html` after a deployment) from being counted as real usage. A separate mechanism addresses that: submitting a valid `authCode` on `/metrics.html` sets a cookie (`kilotestExclude`), valid for 30 days, whose value is a SHA-256 hash of `AUTH_CODE` rather than the code itself, so the secret is never placed in a long-lived browser cookie. Every subsequent request from that browser that carries a matching cookie is excluded from `pageViews` and `apiOperations` (not from `managerActivity`, which should keep counting regardless, since it exists to surface suspected abuse, including from the maintainer's own browser if its cookie were ever compromised).
+The manager-page exclusion above only keeps the maintainer's use of manager-only pages out of `pageViews`; it does not, by itself, keep the maintainer's manual testing of *ordinary* pages (for example clicking through `tutorialWeb.html` or `listPages.html` after a deployment) from being counted as real usage. A separate mechanism addresses that: submitting a valid `authCode` on `/metrics.html` sets a cookie (`kilotestExclude`), valid for 30 days, whose value is a SHA-256 hash of `AUTH_CODE` rather than the code itself, so the secret is never placed in a long-lived browser cookie. Every subsequent request from that browser that carries a matching cookie is excluded from `pageViews` and `apiOperations` (not from `managerActivity`, which should keep counting regardless, since it exists to surface suspected abuse, including from the maintainer's own browser if its cookie were ever compromised).
 
 A fixed or guessable cookie value was deliberately avoided: Kilotest's source is public, so anyone could otherwise read it and set the same cookie in their own browser to exclude themselves from metrics at no cost, defeating the feature. Hashing `AUTH_CODE` means only someone who has already proven they know the real code can derive the correct cookie value.
 

package/index.html

@@ -87,7 +87,7 @@
       </details>
       <h2>What do you want to know?</h2>
       <ul class="nav">
-        <li><a href="listReports.html">Which web pages have been tested?</a></li>
+        <li><a href="listPages.html">Which web pages have been tested?</a></li>
         <li><a href="listTopIssues.html">Which issues have been reported?</a></li>
         <li><a href="manage.html">What can Kilotest managers do?</a></li>
         <li><a href="privacy.html">What is the privacy policy?</a></li>

package/index.test.ts

@@ -198,7 +198,7 @@ test('routes has GET and POST arrays', () => {
 // TESTS: smoke-test short-circuit
 
 test('GET with x-kilotest-smoke header returns a perfunctory 200', async () => {
-  const res = await request('GET', '/api/listReports', null, {'x-kilotest-smoke': '1'});
+  const res = await request('GET', '/api/listPages', null, {'x-kilotest-smoke': '1'});
   assert.equal(res.statusCode, 200);
   assert.equal(res.body, '{}');
 });
@@ -210,7 +210,7 @@ test('POST with x-kilotest-smoke header returns a perfunctory 200', async () =>
 });
 
 test('GET without x-kilotest-smoke header executes the handler', async () => {
-  const res = await request('GET', '/api/listReports');
+  const res = await request('GET', '/api/listPages');
   assert.equal(res.statusCode, 200);
   assert.notEqual(res.body, '{}');
 });
@@ -332,13 +332,13 @@ test('GET /favicon.ico serves the favicon as an icon', async () => {
   assert.ok(res.headers['content-type'].includes('image/x-icon'));
 });
 
-test('GET /api/listReports returns JSON with report data and records an API-operation metric', async () => {
-  const countBefore = await getMetricCount('apiOperations', 'listReports');
-  const res = await request('GET', '/api/listReports');
+test('GET /api/listPages returns JSON with report data and records an API-operation metric', async () => {
+  const countBefore = await getMetricCount('apiOperations', 'listPages');
+  const res = await request('GET', '/api/listPages');
   assert.equal(res.statusCode, 200);
   const body = jsonBody(res);
-  assert.equal(body['tool name'], 'listReports');
-  assert.equal(await getMetricCount('apiOperations', 'listReports'), countBefore + 1);
+  assert.equal(body['tool name'], 'listPages');
+  assert.equal(await getMetricCount('apiOperations', 'listPages'), countBefore + 1);
 });
 
 test('GET /api/listIssues/260101T0000/mix returns JSON with issue data', async () => {
@@ -688,14 +688,14 @@ test('PUT / returns an invalid method error', async () => {
 
 // TESTS: requestHandler catch boundary
 
-test('GET /listReports.html returns a 500 error when an unexpected internal error occurs', {timeout: 500}, async () => {
+test('GET /listPages.html returns a 500 error when an unexpected internal error occurs', {timeout: 500}, async () => {
   // Corrupt testRequests.json so that getTestRequests throws, an error that should never occur in normal
   // operation and so is not handled by handleRequest itself, only by requestHandler's
   // outer catch boundary.
   const backup = await fs.readFile(testRequestsPath, 'utf8');
   await fs.writeFile(testRequestsPath, 'not valid json');
   try {
-    const res = await request('GET', '/listReports.html');
+    const res = await request('GET', '/listPages.html');
     assert.equal(res.statusCode, 500);
     assert.ok(res.headers['content-type'].includes('application/json'));
     const body = jsonBody(res);
@@ -932,10 +932,22 @@ test('GET /rules.html/<segment> redirects to the equivalent /listRules.html/<seg
   assert.equal(res.headers['location'], '/listRules.html/allCaps');
 });
 
-test('GET /targets.html redirects to /listReports.html', async () => {
+test('GET /targets.html redirects to /listPages.html', async () => {
   const res = await request('GET', '/targets.html', {}, {followRedirects: false});
   assert.equal(res.statusCode, 301);
-  assert.equal(res.headers['location'], '/listReports.html');
+  assert.equal(res.headers['location'], '/listPages.html');
+});
+
+test('GET /listReports.html redirects to /listPages.html', async () => {
+  const res = await request('GET', '/listReports.html', {}, {followRedirects: false});
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/listPages.html');
+});
+
+test('GET /api/listReports redirects to /api/listPages', async () => {
+  const res = await request('GET', '/api/listReports', {}, {followRedirects: false});
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/api/listPages');
 });
 
 test('GET /requestTest.html redirects to /requestNewTest.html', async () => {
@@ -1463,7 +1475,7 @@ test('GET /requestRetest.html/260202T0000/new is rejected as an invalid GET requ
 // tested by the unit tests in web/*/*.test.cjs.
 
 const htmlPagePaths = [
-  '/listReports.html',
+  '/listPages.html',
   '/listViolators.html/linkNoText/260101T0000/mix',
   '/listDiagnoses.html/linkNoText/260101T0000/mix/0',
   '/enqueueForm.html',
@@ -1520,11 +1532,11 @@ test('a request carrying the metrics-exclusion cookie does not record a pageView
   const {getExclusionCookieValue} = await import('./util.ts');
   const cookieHeader = `kilotestExclude=${getExclusionCookieValue()}`;
   const pageViewCountBefore = await getMetricCount('pageViews', 'tutorialWeb');
-  const apiOperationCountBefore = await getMetricCount('apiOperations', 'listReports');
+  const apiOperationCountBefore = await getMetricCount('apiOperations', 'listPages');
   await request('GET', '/tutorialWeb.html', null, {cookie: cookieHeader});
-  await request('GET', '/api/listReports', null, {cookie: cookieHeader});
+  await request('GET', '/api/listPages', null, {cookie: cookieHeader});
   assert.equal(await getMetricCount('pageViews', 'tutorialWeb'), pageViewCountBefore);
-  assert.equal(await getMetricCount('apiOperations', 'listReports'), apiOperationCountBefore);
+  assert.equal(await getMetricCount('apiOperations', 'listPages'), apiOperationCountBefore);
 });
 
 test('a request carrying an invalid exclusion cookie still records metrics normally', async () => {
@@ -1945,7 +1957,7 @@ test('a request logs a single-line JSON record with the expected fields', async
   const originalLog = console.log;
   console.log = (line: string) => logged.push(line);
   try {
-    await request('GET', '/listReports.html');
+    await request('GET', '/listPages.html');
   }
   finally {
     console.log = originalLog;
@@ -1961,7 +1973,7 @@ test('a request logs a single-line JSON record with the expected fields', async
   assert.equal(requestLines.length, 1);
   const record = JSON.parse(requestLines[0]!);
   assert.equal(record.method, 'GET');
-  assert.equal(record.path, '/listReports.html');
+  assert.equal(record.path, '/listPages.html');
   assert.equal(record.status, 200);
   assert.ok(record.ip);
   assert.ok(record.userAgent);
@@ -1991,7 +2003,7 @@ test('a smoke-test-flagged request is not logged as a general request', async ()
   const originalLog = console.log;
   console.log = (line: string) => logged.push(line);
   try {
-    await request('GET', '/listReports.html', null, {'x-kilotest-smoke': '1'});
+    await request('GET', '/listPages.html', null, {'x-kilotest-smoke': '1'});
   }
   finally {
     console.log = originalLog;

package/index.ts

@@ -54,7 +54,7 @@ import {answer as expungeReportsForm} from './web/expungeReportsForm/index.ts';
 import {answer as hideReportForm} from './web/hideReportForm/index.ts';
 import {answer as listDiagnosesPage} from './web/listDiagnoses/index.ts';
 import {answer as listIssuesPage} from './web/listIssues/index.ts';
-import {answer as listReportsPage} from './web/listReports/index.ts';
+import {answer as listPagesPage} from './web/listPages/index.ts';
 import {answer as listRules} from './web/listRules/index.ts';
 import {answer as listTopIssues} from './web/listTopIssues/index.ts';
 import {answer as listViolatorsPage} from './web/listViolators/index.ts';
@@ -75,7 +75,7 @@ import {answer as unhideReportForm} from './web/unhideReportForm/index.ts';
 import {response as getReportAPI} from './api/getReport.ts';
 import {response as listDiagnosesAPI} from './api/listDiagnoses.ts';
 import {response as listIssuesAPI} from './api/listIssues.ts';
-import {response as listReportsAPI} from './api/listReports.ts';
+import {response as listPagesAPI} from './api/listPages.ts';
 import {response as listViolatorsAPI} from './api/listViolators.ts';
 import {response as requestFeatureAPI} from './api/requestFeature.ts';
 import {response as requestRetestAPI} from './api/requestRetest.ts';
@@ -112,7 +112,7 @@ const answer: {
   hideReportForm: PageHandler;
   listDiagnoses: PageHandler;
   listIssues: PageHandler;
-  listReports: PageHandler;
+  listPages: PageHandler;
   listRules: PageHandler;
   listTopIssues: PageHandler;
   listViolators: PageHandler;
@@ -143,7 +143,7 @@ const answer: {
   hideReportForm,
   listDiagnoses: listDiagnosesPage,
   listIssues: listIssuesPage,
-  listReports: listReportsPage,
+  listPages: listPagesPage,
   listRules,
   listTopIssues,
   listViolators: listViolatorsPage,
@@ -171,7 +171,7 @@ const apiRespond: {
   getReport: ApiResponder;
   listDiagnoses: ApiResponder;
   listIssues: ApiResponder;
-  listReports: ApiResponder;
+  listPages: ApiResponder;
   listViolators: ApiResponder;
   requestFeature: ApiResponder;
   requestRetest: ApiResponder;
@@ -183,7 +183,7 @@ const apiRespond: {
   getReport: getReportAPI,
   listDiagnoses: listDiagnosesAPI,
   listIssues: listIssuesAPI,
-  listReports: listReportsAPI,
+  listPages: listPagesAPI,
   listViolators: listViolatorsAPI,
   requestFeature: requestFeatureAPI,
   requestRetest: requestRetestAPI,
@@ -291,12 +291,16 @@ const noDirectGetPages = new Set(['unhideReportForm']);
 // on 2026-09-28 (see the newTest/retest naming-ambiguity fix), to distinguish the
 // new-test-only page from bare "test" language used elsewhere.
 // TEMPORARY: retire this redirect after 2027-03-28 once crawlers have re-indexed.
+// listReports was renamed to listPages on 2026-10-09, since it lists tested pages, each
+// linked to its latest report.
+// TEMPORARY: retire this redirect after 2027-04-09 once crawlers have re-indexed.
 const renamedPagePrefixes: Record<string, string> = {
   diagnoses: 'listDiagnoses',
   reportIssue: 'listViolators',
   reportIssues: 'listIssues',
   rules: 'listRules',
-  targets: 'listReports',
+  targets: 'listPages',
+  listReports: 'listPages',
   requestTest: 'requestNewTest',
   requestTestForm: 'requestNewTestForm'
 };
@@ -800,15 +804,22 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     // Otherwise, if it is for an API service:
     else if (pageName === 'api') {
       const [service, ...specs] = pathTail.split('/');
-      // If the service lists the available reports:
-      if (service === 'listReports') {
+      // If the service lists the tested pages:
+      if (service === 'listPages') {
         // Get the response body.
-        const responseBody = await apiRespond.listReports([]);
-        await recordPageMetric('apiOperations', 'listReports');
+        const responseBody = await apiRespond.listPages([]);
+        await recordPageMetric('apiOperations', 'listPages');
         // Send it.
         setHeaders('application/json', null, 'ultra');
         response.end(JSON.stringify(responseBody));
       }
+      // Otherwise, if the service has the name that listPages had before 2026-10-09:
+      // TEMPORARY: retire this redirect after 2027-04-09.
+      else if (service === 'listReports') {
+        // Redirect the request to listPages.
+        response.writeHead(301, {Location: '/api/listPages'});
+        response.end();
+      }
       // Otherwise, if the service lists the issues in a report:
       else if (service === 'listIssues') {
         // Get the response body.