@jrpool/kilotest 48.0.0 → 50.0.0

package/mcp.ts

@@ -17,6 +17,7 @@ import * as requestTestAPI from './api/requestTest.ts';
 import * as requestRetestAPI from './api/requestRetest.ts';
 import * as requestFeatureAPI from './api/requestFeature.ts';
 import {version} from './api/version.ts';
+import {recordMetric} from './util.ts';
 
 import {
   getReportSchema,
@@ -68,6 +69,7 @@ export const createMCPServer = (): McpServer => {
     },
     async () => {
       const result = await listReportsAPI.response();
+      await recordMetric('mcpToolCalls', 'listReports');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -87,6 +89,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({timeStamp, jobID}) => {
       const result = await listIssuesAPI.response([timeStamp, jobID]);
+      await recordMetric('mcpToolCalls', 'listIssues');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -106,6 +109,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({issueID, timeStamp, jobID}) => {
       const result = await listViolatorsAPI.response([issueID, timeStamp, jobID]);
+      await recordMetric('mcpToolCalls', 'listViolators');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -125,6 +129,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({catalogIndex, issueID, timeStamp, jobID}) => {
       const result = await listDiagnosesAPI.response([catalogIndex, issueID, timeStamp, jobID]);
+      await recordMetric('mcpToolCalls', 'listDiagnoses');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -144,6 +149,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({timeStamp, jobID}) => {
       const result = await getReportAPI.response([timeStamp, jobID]);
+      await recordMetric('mcpToolCalls', 'getReport');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -163,6 +169,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({description, URL, reason}) => {
       const result = await requestTestAPI.response([description, URL, reason]);
+      await recordMetric('mcpToolCalls', 'requestTest');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -182,6 +189,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({timeStamp, jobID, reason}) => {
       const result = await requestRetestAPI.response([timeStamp, jobID, reason]);
+      await recordMetric('mcpToolCalls', 'requestRetest');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
@@ -201,6 +209,7 @@ export const createMCPServer = (): McpServer => {
     },
     async ({feature}) => {
       const result = await requestFeatureAPI.response([feature]);
+      await recordMetric('mcpToolCalls', 'requestFeature');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "48.0.0",
+  "version": "50.0.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",

package/smokeTest.ts

@@ -40,13 +40,21 @@ const concretePaths: Record<string, Record<string, string>> = {
   POST: {
     '/api/*': '/api/requestFeature',
     '/mcp': '/mcp',
+    '/ai0BalanceForm.html': '/ai0BalanceForm.html',
+    '/expungeReportsForm.html': '/expungeReportsForm.html',
+    '/hideReportForm.html': '/hideReportForm.html',
+    '/metrics.html': '/metrics.html',
+    '/pruneReportsForm.html': '/pruneReportsForm.html',
+    '/rewindReportsForm.html': '/rewindReportsForm.html',
     '/reannotate.html': '/reannotate.html',
     '/requestAction.html': '/requestAction.html',
     '/renewWCAG.html': '/renewWCAG.html',
     '/requestRetest.html/*': '/requestRetest.html/260101T0001/ct',
     '/requestTest.html': '/requestTest.html',
+    '/showHiddenReportsForm.html': '/showHiddenReportsForm.html',
     '/tutorialAIComment.html': '/tutorialAIComment.html',
     '/tutorialWebComment.html': '/tutorialWebComment.html',
+    '/unhideReportForm.html': '/unhideReportForm.html',
     '/worker/job': '/worker/job',
     '/worker/report': '/worker/report'
   }
@@ -55,6 +63,12 @@ const concretePaths: Record<string, Record<string, string>> = {
 const postBodies: Record<string, object> = {
   '/api/requestFeature': {feature: 'smoke test'},
   '/mcp': {},
+  '/ai0BalanceForm.html': {authCode: 'invalid'},
+  '/expungeReportsForm.html': {authCode: 'invalid'},
+  '/hideReportForm.html': {authCode: 'invalid'},
+  '/metrics.html': {authCode: 'invalid'},
+  '/pruneReportsForm.html': {authCode: 'invalid'},
+  '/rewindReportsForm.html': {authCode: 'invalid'},
   '/reannotate.html': {authCode: 'invalid'},
   '/requestAction.html': {
     target: 'https://smoketest.example.com\tSmoke Test Page', authCode: 'invalid'
@@ -62,7 +76,9 @@ const postBodies: Record<string, object> = {
   '/renewWCAG.html': {authCode: 'invalid'},
   '/requestRetest.html/260101T0001/ct': {why: 'smoke test'},
   '/requestTest.html': {description: 'Smoke Test Page', url: 'https://smoketest.example.com', why: 'smoke test'},
+  '/showHiddenReportsForm.html': {authCode: 'invalid'},
   '/tutorialAIComment.html': {content: 'smoke test'},
+  '/unhideReportForm.html': {authCode: 'invalid'},
   '/tutorialWebComment.html': {content: 'smoke test'},
   '/worker/job': {},
   '/worker/report': {}

package/test/dbFixture.ts

@@ -17,5 +17,13 @@ export const fixtureDBDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kilotest-db-'
 // Copy the tracked fixture database to the temporary directory.
 fs.cpSync(path.join(import.meta.dirname, 'fixtures', 'db'), fixtureDBDir, {recursive: true});
 
+// Git does not track empty directories, so the job-state subdirectories are absent
+// from a fresh checkout even though they are part of the fixture layout. Create them
+// here rather than tracking placeholder files, which readdir-based job listing would
+// otherwise pick up as (invalid) job files.
+for (const category of ['queue', 'claimed', 'failed']) {
+  fs.mkdirSync(path.join(fixtureDBDir, 'jobs', category), {recursive: true});
+}
+
 // Remove the copy when the process exits.
 process.on('exit', () => fs.rmSync(fixtureDBDir, {recursive: true, force: true}));

package/util.test.ts

@@ -13,6 +13,7 @@ import {
   annotateReportObject,
   checkCommentDuplicate,
   checkCommentLength,
+  checkLength,
   createLock,
   dbPath,
   getAgoDays,
@@ -45,6 +46,7 @@ import {
   isReportAvailable,
   isTimeStamp,
   isURL,
+  isValidAuthCode,
   jobsPath,
   makeBreakable,
   minifyURL,
@@ -83,6 +85,32 @@ test('checkCommentLength rejects a comment longer than 1000 characters', () => {
   });
 });
 
+test('checkLength accepts text at the minimum bound', () => {
+  const result = checkLength('a'.repeat(5), 5, 10, 'reason');
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkLength accepts text at the maximum bound', () => {
+  const result = checkLength('a'.repeat(10), 5, 10, 'reason');
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkLength rejects text shorter than the minimum bound', () => {
+  const result = checkLength('a'.repeat(4), 5, 10, 'reason');
+  assert.deepEqual(result, {
+    status: 'error',
+    message: 'The reason must be between 5 and 10 characters long'
+  });
+});
+
+test('checkLength rejects text longer than the maximum bound', () => {
+  const result = checkLength('a'.repeat(11), 5, 10, 'reason');
+  assert.deepEqual(result, {
+    status: 'error',
+    message: 'The reason must be between 5 and 10 characters long'
+  });
+});
+
 test('checkCommentDuplicate accepts a comment with no existing comments', () => {
   const result = checkCommentDuplicate([], 'a'.repeat(20));
   assert.deepEqual(result, {status: 'ok'});
@@ -337,6 +365,42 @@ test('isURL returns false for an invalid URL', () => {
   assert.equal(isURL('not-a-url'), false);
 });
 
+test('isValidAuthCode returns true when the code matches AUTH_CODE', () => {
+  const saved = process.env.AUTH_CODE;
+  process.env.AUTH_CODE = 'secret-code';
+  try {
+    assert.equal(isValidAuthCode('secret-code'), true);
+  }
+  finally {
+    if (saved === undefined) {
+      delete process.env.AUTH_CODE;
+    }
+    else {
+      process.env.AUTH_CODE = saved;
+    }
+  }
+});
+
+test('isValidAuthCode returns false when the code does not match AUTH_CODE', () => {
+  const saved = process.env.AUTH_CODE;
+  process.env.AUTH_CODE = 'secret-code';
+  try {
+    assert.equal(isValidAuthCode('wrong-code'), false);
+  }
+  finally {
+    if (saved === undefined) {
+      delete process.env.AUTH_CODE;
+    }
+    else {
+      process.env.AUTH_CODE = saved;
+    }
+  }
+});
+
+test('isValidAuthCode returns false for an undefined code', () => {
+  assert.equal(isValidAuthCode(undefined), false);
+});
+
 test('makeBreakable inserts wbr before non-initial slashes', () => {
   assert.equal(makeBreakable('/api/listReports'), '/api<wbr>/listReports');
 });
@@ -1127,3 +1191,234 @@ test('getMultiReportWhats returns descriptions that have multiple reports', asyn
   const whats = await getMultiReportWhats();
   assert.ok(whats.includes('Mixed Outcomes Page'));
 });
+
+test('getExclusionCookieValue is deterministic for a given AUTH_CODE', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  process.env.AUTH_CODE = 'test-auth-code';
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    const first = getExclusionCookieValue();
+    const second = getExclusionCookieValue();
+    assert.equal(first, second);
+    assert.equal(typeof first, 'string');
+    assert.ok(first.length > 0);
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('getExclusionCookieValue changes when AUTH_CODE changes', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    process.env.AUTH_CODE = 'code-one';
+    const first = getExclusionCookieValue();
+    process.env.AUTH_CODE = 'code-two';
+    const second = getExclusionCookieValue();
+    assert.notEqual(first, second);
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('getExclusionCookieValue does not throw when AUTH_CODE is unset', async () => {
+  const savedAuthCode = process.env.AUTH_CODE;
+  delete process.env.AUTH_CODE;
+  try {
+    const {getExclusionCookieValue} = await import('./util.ts');
+    assert.equal(typeof getExclusionCookieValue(), 'string');
+  }
+  finally {
+    process.env.AUTH_CODE = savedAuthCode;
+  }
+});
+
+test('recordMetric creates the metrics file and records a first occurrence when the file is missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-missing-metrics-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'tutorialWeb.html');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.pageViews['tutorialWeb.html'], 1);
+    assert.equal(metrics.mcpToolCalls['tutorialWeb.html'], undefined);
+    assert.equal(typeof metrics.since, 'string');
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric increments an existing count rather than overwriting it', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-existing-metrics-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('mcpToolCalls', 'listReports');
+    await recordMetric('mcpToolCalls', 'listReports');
+    await recordMetric('mcpToolCalls', 'getReport');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.mcpToolCalls.listReports, 2);
+    assert.equal(metrics.mcpToolCalls.getReport, 1);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric throws when the metrics file is not readable for a reason other than being missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-unreadable-test';
+  const fsSync = await import('node:fs');
+  // Create a directory where the metrics file should be, causing EISDIR rather than ENOENT.
+  fsSync.mkdirSync(tmpDir + '/metrics.json', {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric} = await import('./util.ts');
+    await assert.rejects(recordMetric('pageViews', 'tutorialWeb.html'), /not readable/);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric throws when the metrics file is not JSON', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-not-json-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  fsSync.writeFileSync(tmpDir + '/metrics.json', 'not json');
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric} = await import('./util.ts');
+    await assert.rejects(recordMetric('pageViews', 'tutorialWeb.html'), /not JSON/);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric keeps categories independent for the same name', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-categories-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('apiOperations', 'listReports');
+    await recordMetric('mcpToolCalls', 'listReports');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.apiOperations.listReports, 1);
+    assert.equal(metrics.mcpToolCalls.listReports, 1);
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric tracks managerActivity outcomes separately per page', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-manager-activity-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('managerActivity', 'reannotate.html', 'ok');
+    await recordMetric('managerActivity', 'reannotate.html', 'error');
+    await recordMetric('managerActivity', 'reannotate.html', 'error');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.deepEqual(metrics.managerActivity['reannotate.html'], {ok: 1, error: 2});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('recordMetric keeps managerActivity independent of pageViews for the same name', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-manager-vs-pageviews-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'hideReportForm.html');
+    await recordMetric('managerActivity', 'hideReportForm.html', 'ok');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.pageViews['hideReportForm.html'], 1);
+    assert.deepEqual(metrics.managerActivity['hideReportForm.html'], {ok: 1, error: 0});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('getMetrics backfills categories missing from a metrics.json written before they existed', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-backfill-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  // Simulate a metrics.json written before the managerActivity category was added.
+  fsSync.writeFileSync(tmpDir + '/metrics.json', JSON.stringify({
+    since: '260101T0000',
+    pageViews: {listReports: 1},
+    mcpToolCalls: {},
+    apiOperations: {}
+  }));
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    // Recording a managerActivity outcome must not throw despite the file predating that category.
+    await recordMetric('managerActivity', 'metrics', 'ok');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(metrics.since, '260101T0000');
+    assert.equal(metrics.pageViews.listReports, 1);
+    assert.deepEqual(metrics.managerActivity.metrics, {ok: 1, error: 0});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('getMetrics backfills every category, and generates a since stamp, from a bare empty file', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-metrics-backfill-empty-test';
+  const fsSync = await import('node:fs');
+  fsSync.mkdirSync(tmpDir, {recursive: true});
+  // Simulate a metrics.json with none of the known fields (an extreme case of an outdated schema).
+  fsSync.writeFileSync(tmpDir + '/metrics.json', '{}');
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {recordMetric, metricsPath} = await import('./util.ts');
+    await recordMetric('pageViews', 'tutorialWeb');
+    const metrics = JSON.parse(fsSync.readFileSync(metricsPath(), 'utf8'));
+    assert.equal(typeof metrics.since, 'string');
+    assert.ok(metrics.since.length > 0);
+    assert.equal(metrics.pageViews.tutorialWeb, 1);
+    assert.deepEqual(metrics.mcpToolCalls, {});
+    assert.deepEqual(metrics.apiOperations, {});
+    assert.deepEqual(metrics.managerActivity, {});
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});

package/util.ts

@@ -11,6 +11,7 @@
 import {sendAlert} from './alerts.ts';
 import {issues as issueSpecs, rules as ruleSpecs} from 'testaro-issues';
 import type {Act, Catalog, Report, StandardInstance} from 'testaro';
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import querystring from 'node:querystring';
@@ -29,6 +30,8 @@ export const testRequestsPath = (): string => path.join(jobsPath(), 'testRequest
 export const reportsPath = (): string => path.join(dbPath(), 'reports');
 // Path of the hidden-reports directory.
 export const hiddenReportsPath = (): string => path.join(dbPath(), 'hiddenReports');
+// Path of the usage-metrics file.
+export const metricsPath = (): string => path.join(dbPath(), 'metrics.json');
 // IDs, names, and sponsors of Testaro rule engines.
 const ruleEngines: Record<string, [string, string]> = {
   alfa: ['Alfa', 'Siteimprove'],
@@ -50,6 +53,18 @@ export {ruleEngines};
 
 // TYPES
 
+// Usage-metrics categories, each a map from an event name (page name, MCP tool name, or
+// API operation name) to a count of how many times it has occurred. managerActivity
+// counts manager-only pages separately from pageViews, by outcome, since a spike in
+// failed authCode attempts against a manager page is a signal of suspected abuse.
+export type Metrics = {
+  since: string;
+  pageViews: Record<string, number>;
+  mcpToolCalls: Record<string, number>;
+  apiOperations: Record<string, number>;
+  managerActivity: Record<string, {ok: number; error: number}>;
+};
+
 // Test request.
 export type TestRequest = {
   timeStamp: string;
@@ -158,6 +173,24 @@ export type ReportData = {
 const alphaCompare = (a: string, b: string) => a.localeCompare(b, 'en', {sensitivity: 'base'});
 // Sorts strings alphabetically and case-insensitively.
 const alphaSort = (strings: string[]) => strings.sort((a, b) => alphaCompare(a, b));
+// Returns whether a string's length is within the given bounds. Generic length check
+// shared by any field with a min/max character-count rule (e.g. a request description
+// or reason), so each caller states its own bounds and label instead of hardcoding an
+// ad hoc length comparison.
+export const checkLength = (
+  text: string, min: number, max: number, label: string
+): {status: 'ok'} | {status: 'error'; message: string} => {
+  const {length} = text;
+  // If the length is invalid:
+  if (length < min || length > max) {
+    // Return the applicable error message.
+    return {
+      status: 'error',
+      message: `The ${label} must be between ${min} and ${max} characters long`
+    };
+  }
+  return {status: 'ok'};
+};
 // Returns whether a comment's raw length is within the 20-to-1000-character bounds.
 export const checkCommentLength = (
   content: string
@@ -521,6 +554,12 @@ export const isURL = (string: string): boolean => {
     return false;
   }
 };
+// Returns whether a string is the authorization code, the shared check every
+// manager-facing page and action uses to gate a submission. Centralized so all call
+// sites compare against process.env.AUTH_CODE the same way.
+export const isValidAuthCode = (authCode: string | undefined | null): boolean => {
+  return !!authCode && authCode === process.env.AUTH_CODE;
+};
 // Makes a string breakable before non-initial slashes.
 export const makeBreakable = (string: string): string => string.replace(/\//g, '<wbr>/').replace(/^<wbr>/, '');
 // Minifies a URL for duplicate detection.
@@ -1015,3 +1054,85 @@ export const processTestRequest = (
     throw new Error('Failed to process test request', {cause: error});
   }
 });
+
+// METRICS FUNCTIONS
+
+// Name of the cookie that excludes a browser's requests from usage metrics.
+export const metricsExclusionCookieName = 'kilotestExclude';
+// Returns the value that the metrics-exclusion cookie must have to be honored: a SHA-256
+// hash of AUTH_CODE, not AUTH_CODE itself, so the secret is never placed in a long-lived
+// browser cookie, and not a fixed value, since Kilotest's source is public and a fixed
+// value would let anyone read it and exclude themselves from metrics at no cost.
+export const getExclusionCookieValue = (): string =>
+  crypto.createHash('sha256').update(process.env.AUTH_CODE ?? '').digest('hex');
+// Concurrency lock for the `metrics.json` file.
+const metricsLock = createLock();
+// Returns the usage metrics, creating the file with zeroed counts if it does not yet exist.
+export const getMetrics = async (): Promise<Metrics> => {
+  let metricsJSON: string;
+  try {
+    metricsJSON = await fs.readFile(metricsPath(), 'utf8');
+  }
+  catch(error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      const metrics: Metrics = {
+        since: getNowStamp(), pageViews: {}, mcpToolCalls: {}, apiOperations: {}, managerActivity: {}
+      };
+      await fs.writeFile(metricsPath(), getJSON(metrics));
+      return metrics;
+    }
+    throw new Error(`Metrics file not readable (${errorMessage(error)})`, {cause: error});
+  }
+  let metrics: Partial<Metrics>;
+  try {
+    metrics = JSON.parse(metricsJSON) as Partial<Metrics>;
+  }
+  catch(error: unknown) {
+    throw new Error(`Metrics file not JSON (${errorMessage(error)})`, {cause: error});
+  }
+  // Backfill any category absent from a file written before that category existed,
+  // so an older metrics.json (e.g. from before a schema change) remains readable.
+  return {
+    since: metrics.since ?? getNowStamp(),
+    pageViews: metrics.pageViews ?? {},
+    mcpToolCalls: metrics.mcpToolCalls ?? {},
+    apiOperations: metrics.apiOperations ?? {},
+    managerActivity: metrics.managerActivity ?? {}
+  };
+};
+// Records an occurrence of a named event (a web page view, an MCP tool call, or an API
+// operation call) in the usage metrics, creating the category and name if not yet present.
+export function recordMetric(
+  category: 'pageViews' | 'mcpToolCalls' | 'apiOperations', name: string
+): Promise<void>;
+// Records an outcome of a manager-page visit or submission (a distinct category from
+// pageViews, so a spike in failed authCode attempts against a manager page is visible
+// as a signal of suspected abuse, rather than being folded into ordinary page views).
+export function recordMetric(
+  category: 'managerActivity', name: string, outcome: 'ok' | 'error'
+): Promise<void>;
+export function recordMetric(
+  category: 'pageViews' | 'mcpToolCalls' | 'apiOperations' | 'managerActivity',
+  name: string,
+  outcome?: 'ok' | 'error'
+): Promise<void> {
+  return metricsLock(async (): Promise<void> => {
+    const metrics = await getMetrics();
+    if (category === 'managerActivity') {
+      const entry = metrics.managerActivity[name] ??= {ok: 0, error: 0};
+      entry[outcome!]++;
+    }
+    else {
+      metrics[category][name] = (metrics[category][name] ?? 0) + 1;
+    }
+    await fs.writeFile(metricsPath(), getJSON(metrics));
+  });
+}
+// Resets all usage metrics to empty and since to now.
+export const clearMetrics = (): Promise<Metrics> => metricsLock(async (): Promise<Metrics> => {
+  const metrics: Metrics = {
+    since: getNowStamp(), pageViews: {}, mcpToolCalls: {}, apiOperations: {}, managerActivity: {}
+  };
+  await fs.writeFile(metricsPath(), getJSON(metrics));
+  return metrics;
+});

package/web/ai0BalanceForm/ai0BalanceForm.test.ts

@@ -44,22 +44,28 @@ after(async () => {
 
 // TESTS
 
-test('ai0BalanceForm displays the current balance when no newBalance is submitted', async () => {
-  const result: any = await answer(null, '');
+test('ai0BalanceForm displays the current balance on a GET request', async () => {
+  const result: any = await answer(null, '', 'GET');
   assert.equal(result.status, 'ok');
   assert.ok(result.answerPage);
   const html = parse(result.answerPage);
   assert.ok(html.querySelector('title'));
 });
 
-test('ai0BalanceForm returns an error for an invalid auth code', async () => {
-  const result: any = await answer(null, 'authCode=wrong&newBalance=5.00');
+test('ai0BalanceForm ignores a newBalance query string on a GET request', async () => {
+  const result: any = await answer(null, 'authCode=test-auth-code&newBalance=99.00', 'GET');
+  assert.equal(result.status, 'ok');
+  assert.ok(!result.answerPage.includes('$99 is the'));
+});
+
+test('ai0BalanceForm returns an error for an invalid auth code on a POST request', async () => {
+  const result: any = await answer(null, 'authCode=wrong&newBalance=5.00', 'POST');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid authorization code');
+  assert.equal(result.message, 'Invalid request');
 });
 
-test('ai0BalanceForm records a valid new balance with valid auth code', async () => {
-  const result: any = await answer(null, 'authCode=test-auth-code&newBalance=2.50');
+test('ai0BalanceForm records a valid new balance with valid auth code on a POST request', async () => {
+  const result: any = await answer(null, 'authCode=test-auth-code&newBalance=2.50', 'POST');
   assert.equal(result.status, 'ok');
   assert.ok(result.answerPage.includes('$2.5 is the'));
   // Verify the file was written.
@@ -67,9 +73,9 @@ test('ai0BalanceForm records a valid new balance with valid auth code', async ()
   assert.equal(data.balance, 2.50);
 });
 
-test('ai0BalanceForm does not record an invalid balance', async () => {
+test('ai0BalanceForm does not record an invalid balance on a POST request', async () => {
   // 150 is out of range (>= 100).
-  const result: any = await answer(null, 'authCode=test-auth-code&newBalance=150');
+  const result: any = await answer(null, 'authCode=test-auth-code&newBalance=150', 'POST');
   assert.equal(result.status, 'ok');
   // The oldBalance should not show the new value.
   assert.ok(!result.answerPage.includes('$150 is the'));
@@ -78,7 +84,7 @@ test('ai0BalanceForm does not record an invalid balance', async () => {
 test('ai0BalanceForm shows no-balance message when balance file is missing', async () => {
   await fs.unlink(balancePath).catch(() => {});
   try {
-    const result: any = await answer(null, '');
+    const result: any = await answer(null, '', 'GET');
     assert.equal(result.status, 'ok');
     assert.ok(result.answerPage.includes('There is no'));
   }