@jrpool/kilotest 39.0.1 → 40.0.0

package/api/requestFeature.js

@@ -12,13 +12,13 @@ const {sendAlert} = require('../alerts');
 
 // Returns the response body.
 exports.response = async args => {
-  const [request = ''] = args;
+  const [feature = ''] = args;
   // Initialize the response content.
   const responseContent = {
     'details about your request': null
   };
-  // If the request is empty:
-  if (!request) {
+  // If the requested feature or improvement is empty:
+  if (!feature) {
     // Add this to the response content.
     responseContent['details about your request'] = {
       error: 'request invalid: request is empty'
@@ -27,7 +27,7 @@ exports.response = async args => {
   // Otherwise, i.e. if it exists:
   else {
     // Notify the manager.
-    await sendAlert('MCP feature request received', request);
+    await sendAlert('MCP feature request received', feature);
     // Add the disposition to the response content.
     responseContent['details about your request'] = {
       'date and time received': new Date().toISOString(),
@@ -43,7 +43,7 @@ exports.response = async args => {
       method: 'POST',
       URL: `${thisHost}/api/requestFeature`,
       body: {
-        request
+        feature
       },
       'closest ancestor request': null
     },

package/api/routes.js

@@ -90,7 +90,7 @@ module.exports = [
     operationId: 'requestFeature',
     method: 'post',
     path: '/api/requestFeature',
-    summary: 'Request a new feature or feature improvement',
+    summary: 'Request a feature improvement or new feature',
     bodySchema: z.object(requestFeatureSchema),
     responseSchema: requestFeatureResponseSchema
   }

package/api/schemas.js

@@ -52,7 +52,7 @@ exports.requestRetestSchema = {
 
 // requestFeature: POST /api/requestFeature
 exports.requestFeatureSchema = {
-  request: z.string().describe('description of requested new feature or feature improvement')
+  feature: z.string().describe('description of requested feature improvement or new feature')
 };
 
 // listReports takes no input; omitted (mcp.js already uses inputSchema: {}).
@@ -105,11 +105,16 @@ const thisRequestSchema = (method, bodySchema) => z.object({
   'closest ancestor request': requestReferenceSchema.nullable()
 });
 
-const envelope = (method, responseContentSchema, bodySchema) => z.object({
+const envelope = (
+  method,
+  responseContentSchema,
+  bodySchema,
+  /** @type {z.ZodType} */ similarWebSchema = similarWebRequestsSchema
+) => z.object({
   'tool collection': toolsFactsSchema,
   'tool name': z.string(),
   'this request': thisRequestSchema(method, bodySchema),
-  'URLs of similar requests for web users': similarWebRequestsSchema,
+  'URLs of similar requests for web users': similarWebSchema,
   'response metadata': responseMetadataSchema,
   'response content': responseContentSchema
 });
@@ -293,5 +298,6 @@ exports.requestFeatureResponseSchema = envelope(
       disposition: z.string()
     })
   ])}),
-  z.object(exports.requestFeatureSchema)
+  z.object(exports.requestFeatureSchema),
+  z.null()
 );

package/api/testSuite.js

@@ -272,13 +272,17 @@ const requestService = async () => {
     return;
   }
   console.log('======================\nRequest: Make a feature request');
-  path = `/api/requestFeature/${timeStamp}/${jobID}`;
+  path = '/api/requestFeature';
+  const featureRequest = 'Do the impossible';
   body = await submitRequest(path, method, {
-    feature: 'Do the impossible'
+    feature: featureRequest
   });
-  responseContent = body?.['response content'] ?? {};
-  requestDetails = responseContent['details about your request'] ?? {};
-  if (!requestDetails.disposition?.includes('received and logged')) {
+  const feature = body?.['this request']?.body?.feature ?? {};
+  requestDetails = body?.['response content']?.['details about your request'] ?? {};
+  if (
+    feature !== featureRequest
+    || !requestDetails.disposition?.includes('received and logged')
+  ) {
     console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
     return;
   }

package/docs/SERVICE.md

@@ -280,6 +280,50 @@ Experimentation revealed that a high-frequency instance could decrease the elaps
 
 ## Security
 
+### Report protection
+
+Jobs and reports are not tracked, so there are no duplicates in any other copy of the repository. Jobs are typically ephemeral, but reports typically remain in existence until deemed obsolete and useless even for historical comparison. Therefore, reports risk deletion unless duplicates are made externally. Other files, including application code, dependencies, and `db/reportsExtract.json`, are not at risk, because they can be pushed from the local repository or regenerated.
+
+Reports created on the deployed server are currently protected with an external archive at the [Cloudflare R2 object storage service](https://developers.cloudflare.com/r2/). On that service, the current Kilotest maintainer has an account, subscribes to the R2 service, has created two _buckets_ named `kilotest-reports` and `kilotest-hidden-reports`, and has created an API token scoped to those buckets with object read-write permissions, access and secret access keys for S3 clients, and a restriction to the IPv4 and IPv6 addresses of the server.
+
+The server host uses `rclone` for file synchronization with external storage locations. Two files on the server host enable `rclone` for use by Kilotest. One file is `/home/linuxuser/.config/rclone/rclone.conf`. Its content, with secrets replaced, is:
+
+```ini
+[r2]
+type = s3
+provider = Cloudflare
+access_key_id = <access_key_id>
+secret_access_key = <secret_access_key>
+endpoint = https://<account_id>.r2.cloudflarestorage.com
+acl = private
+no_head = true
+no_check_bucket = true
+```
+
+The other file is the `crontab` configuration file for `linuxuser`, which is managed with `crontab -e`. The commands in that file (shown with `crontab -l`) are:
+
+```crontab
+11 9 * * * /usr/bin/rclone copy /opt/jpdev/kilotest/db/hiddenReports r2:kilotest-hidden-reports/ -v --backup-dir r2:kilotest-hidden-reports-old/$(date +\%F) > /home/linuxuser/kilotest-to-r2.log 2>&1
+12 9 * * * /usr/bin/rclone copy /opt/jpdev/kilotest/db/reports r2:kilotest-reports/ -v --backup-dir r2:kilotest-reports-old/$(date +\%F) >> /home/linuxuser/kilotest-to-r2.log 2>&1
+```
+
+This configuration every morning (UTC) copies reports to R2 as follows:
+
+- Reports already on R2 are not copied again.
+- Reports not yet on R2 are copied to it.
+- Reports on R2 that differ from and are older than the same-name reports on the server are moved to the corresponding `-old` directory, and the newer reports are copied to R2.
+
+Each daily copy operation is logged in `/home/linuxuser/kilotest-to-r2.log`. That file is replaced with a new one each day documenting only the operation on that day.
+
+If restoration becomes necessary, the files can be copied in the opposite direction with:
+
+```bash
+/usr/bin/rclone copy r2:kilotest-reports /opt/jpdev/kilotest/db/restored-reports -v
+/usr/bin/rclone copy r2:kilotest-hidden-reports /opt/jpdev/kilotest/db/restored-hidden-reports -v
+```
+
+After that the maintainer can inspect the original and restored directories and delete or move report files as needed. After that the `db/reportsExtract.json` file should be deleted, so it will be regenerated when next needed.
+
 ### Possible future Testaro integration
 
 Kilotest uses Testaro to run jobs. In previous versions of Kilotest, Testaro was a dependency. It is currently not a dependenc. Instead, Testaro instances are installed on one or more other hosts, and each instance polls Kilotest to ask for jobs to run.
@@ -292,7 +336,7 @@ Testaro uses Playwright to launch and control headless browsers, often `chromium
 
 When either Playwright or Puppeteer launches a `chromium` browser, in most environments it is [sandboxed](https://www.geeksforgeeks.org/ethical-hacking/what-is-browser-sandboxing/). Sandboxing is a security feature that prevents the browser from accessing potentially unsafe system resources. But in the Ubuntu Linux operating system that was installed on the Vultr Cloud Compute host a sandboxed browser requires an [unprivileged user namespace](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces), and when Ubuntu was installed its configuration disallowed such namespaces. The file `/etc/sysctl.d/99-kilotest-userns.conf` with the content `kernel.apparmor_restrict_unprivileged_userns = 1` prohibited unprivileged user namespaces and thereby made sandboxed browsers unlaunchable.
 
-### Potential modification
+#### Potential modification
 
 One modification to cope with this prohibition on the Vultr Cloud Compute host would be to configure Playwright and Puppeteer to launch `chromium` non-sandboxed. In both cases, launch arguments `'--no-sandbox'` and `'--disable-setuid-sandbox'` are available to specify this.
 
@@ -300,7 +344,7 @@ One modification to cope with this prohibition on the Vultr Cloud Compute host w
 - For the `qualWeb` tool, this would be done in the Testaro `tests/qualweb.js` file, where the `qualWeb.start` method is called with an options argument. Its `args` array property would include `'--no-sandbox'` and `'--disable-setuid-sandbox'`.
 - The `ibm` tool, too, could launch a Puppeteer `chromium` browser, if page content instead of a Playwright page were passed to the `accessibilityChecker.getCompliance` method, or if the implementation of the tool were changed in the future. For anticipation of such a case, the Testaro `aceconfig.js` file, of which a copy has been created at the root of the Kilotest project, would be modified. That file defines a `module.exports` object with a `puppeteerArgs` property, and, `--no-sandbox` and `--disable-setuid-sandbox` would be added to its array value.
 
-### Current modification
+#### Current modification
 
 However, non-sandboxed browsers are less secure than sandboxed ones, particularly when there is no restriction on who can use the service and what web pages they can test with it. Such restrictions are currently in place, but still permit testing of arbitrary web pages and may be relaxed in the future. Therefore, the potential modification described above would introduce nontrivial risk. An alternative solution was adopted instead. In it, the `chromium` configuration was left unchanged.
 

package/index.js

@@ -750,10 +750,10 @@ const requestHandler = async (request, response) => {
           }
           // Otherwise, if the service is to receive a feature request:
           else if (segments[0] === 'requestFeature') {
-            const {request} = postData;
+            const {feature} = postData;
             // Get the response body.
             const responseBody = await require(path.join(__dirname, 'api', 'requestFeature'))
-            .response(segments.slice(1).concat(request));
+            .response([feature]);
             // Send it.
             setHeaders('application/json', null, 'ultra');
             response.end(JSON.stringify(responseBody));

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 info:
   title: Kilotest API
   description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 10 rule engines to test public web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
-  version: 39.0.0
+  version: 39.0.3
   license:
     name: MIT
     identifier: MIT
@@ -1045,21 +1045,21 @@ paths:
   /api/requestFeature:
     post:
       operationId: requestFeature
-      summary: Request a new feature or feature improvement
+      summary: Request a feature improvement or new feature
       requestBody:
         content:
           application/json:
             schema:
               type: object
               properties:
-                request:
+                feature:
                   type: string
-                  description: description of requested new feature or feature improvement
+                  description: description of requested feature improvement or new feature
               required:
-                - request
+                - feature
       responses:
         '200':
-          description: Request a new feature or feature improvement
+          description: Request a feature improvement or new feature
           content:
             application/json:
               schema:
@@ -1082,11 +1082,11 @@ paths:
                       body:
                         type: object
                         properties:
-                          request:
+                          feature:
                             type: string
-                            description: description of requested new feature or feature improvement
+                            description: description of requested feature improvement or new feature
                         required:
-                          - request
+                          - feature
                         additionalProperties: false
                       closest ancestor request:
                         anyOf:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "39.0.1",
+  "version": "40.0.0",
   "description": "Ensemble testing for front-end web quality",
   "main": "index.js",
   "scripts": {

package/scripts/generate-openapi.js

@@ -20,6 +20,7 @@ const outputPath = path.join(__dirname, '..', 'openapi.yaml');
 
 // Builds the paths object for createDocument from the route table.
 const buildPaths = () => {
+  /** @type {import('zod-openapi').ZodOpenApiPathsObject} */
   const paths = {};
   routes.forEach(route => {
     const {method, path: routePath, summary, pathParamsSchema, bodySchema, responseSchema} = route;

package/CLAUDE.md

@@ -1,5 +0,0 @@
-# Cascade Rules
-
-- Ask mode: If the current mode is Ask, answer questions and provide code, diffs, or edit suggestions in code blocks or as plain text. Do not invite the user to switch to Normal or Code mode or any mode that permits writing files.
-- Comply with the current convention to omit line breaks in long lines in `.md` files and in code comments.
-- In conversation responses (not files), when a Markdown table cell would contain a line longer than 120 characters divided by the number of columns, insert `<br>` tags to keep displayed line lengths shorter than that maximum, since raw newlines are not valid inside table cells. If this rule makes any table cumbersome, use a non-tabular format, such as a list, instead.