kryptheon 0.1.5 → 0.1.7

package/README.md

@@ -123,9 +123,11 @@ Worth adding to `.gitignore`: `.env`, `kryptheon-baselines.json`,
 
 ## Requirements
 
-Node 20.6 or later. Recording needs a real terminal window — it opens a browser,
-so it cannot run inside an AI coding assistant. The first run downloads a browser
-(about 200MB, once).
+Node 20.6 or later. The first run downloads a browser (about 200MB, once).
+
+Recording opens a browser window, so it needs a machine with a screen. It will
+always try — if no window appears within 30 seconds it stops and says so,
+rather than refusing up front.
 
 ## Licence
 

package/bin/kryptheon.js

@@ -11,6 +11,8 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
+const os = require('os');
+const secrets = require(require('path').join(__dirname, '..', 'kryptheon-secrets.js'));
 const replay = require('../kryptheon-replay.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
@@ -33,6 +35,16 @@ function nodeIsTooOld(version) {
   return false;
 }
 
+// Read from the package rather than repeated here, so it cannot go stale.
+// Someone filing a bug report has to be able to say which version they have.
+function packageVersion() {
+  try {
+    return require(path.join(PACKAGE_DIR, 'package.json')).version || 'unknown';
+  } catch (err) {
+    return 'unknown';
+  }
+}
+
 function usage() {
   console.log('');
   console.log('  kryptheon - record and check your app');
@@ -43,6 +55,7 @@ function usage() {
   console.log('  kryptheon setup-ai       tell your AI assistant to check its work');
   console.log('');
   console.log('  add --quiet to check for one line when everything passes');
+  console.log('  kryptheon --version      print the version you have installed');
   console.log('');
 }
 
@@ -479,23 +492,51 @@ async function nameRecording(relativeFile) {
 // Recording needs a real browser window on someone's screen. Inside an AI
 // coding assistant there is no desktop to draw it on, so codegen would sit
 // there forever and the run would be killed before anything was tidied up.
-function looksLikeNoDesktop() {
-  if (process.env.KRYPTHEON_FORCE_RECORD) return false;
-  return !process.stdout.isTTY;
+// There is deliberately no up-front refusal here.
+//
+// This used to check process.stdout.isTTY and refuse before launching. That
+// was wrong: isTTY is falsy in plenty of perfectly good terminals depending on
+// how the process was started, and a real user in Command Prompt was told to
+// go and run the command in Command Prompt. Refusing on a guess is far worse
+// than trying and waiting - so we always launch, and the watchdog below
+// reports only when a window genuinely never appears.
+
+// Only ever shown after actually trying: the browser was launched and no
+// window arrived. It must never tell someone to go and run the command they
+// have plainly just run.
+function noWindowLines(seconds) {
+  return [
+    '',
+    '  No browser window appeared.',
+    '',
+    '  The browser was started, but nothing showed up on screen within ' + seconds,
+    '  seconds, so there was nowhere to record.',
+    '',
+    '  The usual reasons:',
+    '    - there is no desktop to draw on - a remote or SSH session, a',
+    '      container, or an AI coding assistant running the command for you',
+    '    - security software stopped the browser from opening',
+    '    - the machine is slow and the browser had not finished starting',
+    '',
+    '  If you are sitting at the screen, run the same command again - a slow',
+    '  first start is the most common cause, and the second attempt usually',
+    '  works.',
+    '',
+    '  If you are connected to a different machine, run it on the machine',
+    '  that has the screen.',
+    '',
+    '  If the window really is open and this keeps happening, set',
+    '  KRYPTHEON_FORCE_RECORD=1 to skip this check.',
+    '',
+    '  Nothing was recorded.',
+    '',
+  ];
 }
 
-function explainNoWindow(url) {
-  console.error('');
-  console.error('  Recording needs a real browser window on your screen.');
-  console.error('');
-  console.error('  This terminal cannot show one - that is what happens inside an');
-  console.error('  AI coding assistant, or any window-less session.');
-  console.error('');
-  console.error('  Open Command Prompt (or PowerShell) yourself and run:');
-  console.error('    npx kryptheon record ' + url);
-  console.error('');
-  console.error('  Nothing was recorded.');
-  console.error('');
+function explainNoWindow() {
+  for (const line of noWindowLines(Math.round(WINDOW_TIMEOUT_MS / 1000))) {
+    console.error(line);
+  }
 }
 
 // Is a Playwright-controlled browser actually showing a window?
@@ -567,15 +608,44 @@ function takeOutSecrets(relativeFile) {
   return writeSpec(relativeFile, result.source) ? result.replacements : [];
 }
 
+// kryptheon leaves a password file and three files of machine state in the
+// project. If there is already a .gitignore, they belong in it.
+function keepArtefactsOutOfGit() {
+  const added = secrets.updateGitignore(USER_DIR);
+  if (!added.length) return;
+  console.log('  Added to .gitignore: ' + added.join(', '));
+  console.log('');
+}
+
 function reportSecrets(replacements) {
   if (!replacements || !replacements.length) return;
+  const names = replacements.map((item) => item.envName);
   console.log('  What you typed into the password box was not saved in the test.');
   console.log('');
-  console.log('  Put it in a file called .env next to your tests, like this:');
-  for (const item of replacements) {
-    console.log('    ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here');
+
+  // Written rather than described. Asked to make the file themselves, most
+  // people on Windows reach for Notepad or Out-File, both of which add a byte
+  // order mark that makes the first line unreadable.
+  const hasEnv = fs.existsSync(path.join(USER_DIR, '.env'));
+  const example = hasEnv ? null : secrets.writeEnvExample(USER_DIR, names);
+  if (example) {
+    console.log('  A file called .env.example has been written here:');
+    for (const name of names) console.log('    ' + name + '=yourpassword');
+    console.log('');
+    console.log('  Put your real password in it and save it as .env, in this folder.');
+  } else {
+    console.log('  Before this can be checked, put it in a file called .env next to');
+    console.log('  your tests, like this:');
+    for (const item of replacements) {
+      console.log('    ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here');
+    }
   }
   console.log('');
+  // Said plainly, because the alternative is signing in with a blank password
+  // and spending an afternoon looking at the wrong thing.
+  console.log('  Until that file exists, "kryptheon check" will skip this recording');
+  console.log('  rather than sign in with a blank password.');
+  console.log('');
   console.log('  Keep .env out of version control - it holds the real value.');
   console.log('');
 }
@@ -671,6 +741,7 @@ async function finaliseRecording(outFile, context) {
     console.log('');
 
     reportSecrets(secrets);
+    keepArtefactsOutOfGit();
     await offerToDropLogout(named);
     reportReplayRisks(named);
 
@@ -693,7 +764,7 @@ async function finaliseRecording(outFile, context) {
   }
 
   if (ctx.reason === 'no-window') {
-    explainNoWindow(ctx.target);
+    explainNoWindow();
   } else if (ctx.reason === 'signal') {
     console.log('');
     console.log('  Recording stopped before anything was saved.');
@@ -726,13 +797,6 @@ async function record(url) {
 
   const target = normaliseRecordUrl(url);
 
-  // No desktop means no window means nothing to record. Say so now rather
-  // than hanging until something kills us.
-  if (looksLikeNoDesktop()) {
-    explainNoWindow(target);
-    return 1;
-  }
-
   // Fail early and kindly rather than letting codegen throw a stack trace.
   const reach = await reachability(target);
   if (!reach.ok) {
@@ -793,8 +857,14 @@ async function record(url) {
 
   return await new Promise((resolve) => {
     // If no window ever appears, stop instead of waiting for someone to kill us.
+    // Someone whose window is real but undetectable can turn this off.
+    const watchdogOff = !!process.env.KRYPTHEON_FORCE_RECORD;
     let waited = 0;
     const watchdog = setInterval(() => {
+      if (watchdogOff) {
+        clearInterval(watchdog);
+        return;
+      }
       waited += WINDOW_POLL_MS;
       if (browserWindowIsUp()) {
         clearInterval(watchdog);
@@ -871,6 +941,7 @@ function triageSpecs() {
   const notRecordings = [];
   const runnable = [];
   const withSecrets = [];
+  const missingSecrets = [];
 
   for (const name of listSpecFiles()) {
     const full = path.join(TESTS_DIR, name);
@@ -903,6 +974,18 @@ function triageSpecs() {
     if (replay.scrubSecrets(source).replacements.length) {
       withSecrets.push({ name: name, fields: replay.scrubSecrets(source).replacements });
     }
+
+    // A recording that falls back to an empty password is not run at all. It
+    // would sign in blank, fail, and send the reader looking at their app.
+    const needed = secrets.requiredSecrets(source);
+    const absent = needed.length
+      ? secrets.missingSecrets(needed, { envFile: secrets.envFileFor(USER_DIR) })
+      : [];
+    if (absent.length) {
+      missingSecrets.push({ name: name, names: absent });
+      continue;
+    }
+
     runnable.push(name);
   }
 
@@ -911,6 +994,7 @@ function triageSpecs() {
     notRecordings: notRecordings,
     runnable: runnable,
     withSecrets: withSecrets,
+    missingSecrets: missingSecrets,
   };
 }
 
@@ -947,6 +1031,8 @@ function check(options) {
     console.log('');
     return 1;
   }
+  keepArtefactsOutOfGit();
+
   const triage = triageSpecs();
 
   for (const name of triage.repaired) {
@@ -962,6 +1048,14 @@ function check(options) {
     console.log('  Re-record it to have the password moved into .env automatically.');
   }
 
+  for (const item of triage.missingSecrets) {
+    console.log('');
+    const example = fs.existsSync(path.join(USER_DIR, '.env.example')) ? '.env.example' : null;
+    for (const line of secrets.missingSecretLines(path.join('tests', item.name), item.names, { examplePath: example })) {
+      console.log(line);
+    }
+  }
+
   for (const name of triage.notRecordings) {
     console.log('');
     console.log('  Skipped ' + path.join('tests', name));
@@ -974,8 +1068,13 @@ function check(options) {
     console.log('');
     console.log('  Nothing could be checked.');
     console.log('');
-    console.log('  None of the files in tests/ is a usable recording.');
-    console.log('  Record one with:  kryptheon record <url>');
+    if (triage.missingSecrets.length) {
+      console.log('  Every recording here needs a password that is not set yet.');
+      console.log('  Create the .env file above and run this again.');
+    } else {
+      console.log('  None of the files in tests/ is a usable recording.');
+      console.log('  Record one with:  kryptheon record <url>');
+    }
     console.log('');
     return 1;
   }
@@ -986,10 +1085,34 @@ function check(options) {
   // cannot produce diagnostics can never be counted as passing.
   const only = triage.runnable.map((name) => path.join('tests', name).split(path.sep).join('/'));
   if (quiet) process.env.KRYPTHEON_QUIET = '1';
+
+  // Debug signatures. The workers cannot print: Playwright pipes their
+  // descriptors and hands the output to reporter stdio hooks that this
+  // reporter does not implement, so it is dropped. They write to this file
+  // instead and it is printed here, on stderr, where the reporter's own
+  // output on stdout is left completely alone.
+  const signatures = require(path.join(PACKAGE_DIR, 'kryptheon-signature.js'));
+  let sink = null;
+  if (signatures.signatureEnabled()) {
+    sink = path.join(os.tmpdir(), 'kryptheon-signature-' + process.pid + '.jsonl');
+    process.env[signatures.SINK_ENV] = sink;
+  }
+
   const status = runPlaywright(['test', '--config', CONFIG].concat(only)).status;
 
+  if (sink) signatures.drainSignatures(sink);
+
   // Without this, a green summary could still hide a recording that checked
   // nothing at all.
+  if (triage.missingSecrets.length) {
+    const many = triage.missingSecrets.length > 1;
+    console.log(
+      '  Note: ' + triage.missingSecrets.length + ' recording' + (many ? 's were' : ' was') +
+        ' skipped because a password is not set.'
+    );
+    console.log('');
+  }
+
   if (triage.notRecordings.length) {
     const many = triage.notRecordings.length > 1;
     console.log(
@@ -998,7 +1121,9 @@ function check(options) {
     );
     console.log('');
   }
-  return status;
+  // Skipped for a missing password is not a pass. The fix is one file away,
+  // and reporting zero would let it be mistaken for a clean run.
+  return status || (triage.missingSecrets.length ? 1 : 0);
 }
 
 // --- setup-ai ---------------------------------------------------------------
@@ -1264,6 +1389,11 @@ async function main() {
     case 'accept':
       return finishWith(accept(rest.join(' ').trim()));
       break;
+    case '-v':
+    case '--version':
+    case 'version':
+      console.log(packageVersion());
+      return finishWith(0);
     case undefined:
     case '-h':
     case '--help':
@@ -1281,6 +1411,7 @@ async function main() {
 
 // Exported so the naming logic can be checked without opening a browser.
 module.exports = {
+  packageVersion: packageVersion,
   humanisePath: humanisePath,
   nameFromTitle: nameFromTitle,
   deriveTestName: deriveTestName,
@@ -1297,9 +1428,10 @@ module.exports = {
   record: record,
   finaliseRecording: finaliseRecording,
   takeOutSecrets: takeOutSecrets,
+  reportSecrets: reportSecrets,
   reportReplayRisks: reportReplayRisks,
   offerToDropLogout: offerToDropLogout,
-  looksLikeNoDesktop: looksLikeNoDesktop,
+  noWindowLines: noWindowLines,
   classifyFetchError: classifyFetchError,
   normaliseRecordUrl: normaliseRecordUrl,
   isLocalAddress: isLocalAddress,

package/kryptheon-fixture.js

@@ -20,6 +20,7 @@ const base = require('@playwright/test');
 // Reuse the reporter's host-stripping so a baseline stores exactly the shape
 // the reporter prints.
 const { requestPath } = require('./kryptheon-reporter.js');
+const signature = require('./kryptheon-signature.js');
 
 const MAX_ITEMS = 5; // keep the failure block readable
 
@@ -53,10 +54,14 @@ function baselineKey(specFile, title) {
 function readBaselines(file) {
   let raw;
   try {
-    raw = fs.readFileSync(file, 'utf8');
+    raw = fs.readFileSync(file, { encoding: 'utf8' });
   } catch (e) {
     return {};
   }
+  // An editor that saved the file with a byte order mark would otherwise make
+  // JSON.parse throw, and every baseline would silently vanish - which reads as
+  // "all clear" on the next run rather than as the problem it is.
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -69,7 +74,9 @@ function readBaselines(file) {
 
 function saveBaselines(file, all) {
   try {
-    fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n', 'utf8');
+    // Explicit, and without a byte order mark: this file is read back by the
+    // same code and by people, and a mismatch would look like the app changed.
+    fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n', { encoding: 'utf8' });
     return true;
   } catch (e) {
     return false; // diagnostics must never become a second failure
@@ -112,12 +119,16 @@ function toStoredErrors(list) {
 }
 
 function normalisedEntry(current) {
-  return {
+  const stored = {
     url: current.url,
     title: current.title,
     consoleErrors: toStoredErrors(current.consoleErrors),
     failedRequests: toStoredRequests(current.failedRequests),
   };
+  // Only when there is one. A run whose capture failed must not write an empty
+  // signature over a good one, or the next run would report everything as gone.
+  if (current.signature) stored.signature = current.signature;
+  return stored;
 }
 
 function writeBaseline(file, key, entry) {
@@ -170,12 +181,17 @@ function normaliseTitle(value) {
   return String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
 }
 
-// Only the address and title decide pass or fail. Browser noise changing is
-// not on its own a regression.
+// The address, the title, and what the page ended up showing decide pass or
+// fail. Browser noise changing is not on its own a regression.
 function compareBaselines(previous, current) {
   const urlChanged = normaliseUrl(previous.url) !== normaliseUrl(current.url);
   const titleChanged = normaliseTitle(previous.title) !== normaliseTitle(current.title);
-  if (!urlChanged && !titleChanged) return null;
+  if (!urlChanged && !titleChanged) {
+    // Nothing moved in the address bar. This is the case the address and title
+    // alone cannot see: a single-page app with a catch-all route lands on the
+    // same URL under the same title whether the flow worked or not.
+    return signature.compareSignatures(previous.signature, current.signature);
+  }
 
   const what =
     urlChanged && titleChanged ? 'the page address and title changed'
@@ -213,6 +229,17 @@ function newObservations(current, previous) {
   };
 }
 
+// Adds a signature to an accepted baseline that predates the feature, without
+// touching anything else about it - including when it was recorded, which is
+// what the failure report means by "this last worked at".
+function upgradeBaseline(file, key, sig) {
+  const all = readBaselines(file);
+  const entry = all[key];
+  if (!entry || typeof entry !== 'object' || entry.signature || !sig) return false;
+  entry.signature = sig;
+  return saveBaselines(file, all);
+}
+
 // The whole decision in one call: create on first sight, otherwise compare.
 function applyBaseline(file, key, current) {
   const previous = readBaselines(file)[key];
@@ -221,7 +248,16 @@ function applyBaseline(file, key, current) {
     return { status: 'created', message: null };
   }
   const message = compareBaselines(previous, current);
-  return message ? { status: 'changed', message: message } : { status: 'match', message: null };
+  if (message) return { status: 'changed', message: message };
+
+  // A baseline from before signatures existed passes on address and title, and
+  // learns its signature here. Doing it on a pass rather than up front means an
+  // upgraded project never fails on its first run under the new version.
+  if (!previous.signature && current.signature) {
+    upgradeBaseline(file, key, current.signature);
+    return { status: 'learned', message: null };
+  }
+  return { status: 'match', message: null };
 }
 
 // ---------------------------------------------------------------------------
@@ -261,6 +297,9 @@ const test = base.test.extend({
         await testInfo.attach('kryptheon-observations', {
           body: JSON.stringify({
             url: url,
+            // What was actually on screen when it gave up. On a flow that
+            // stopped half way this is the most useful line in the report.
+            pageShowed: signature.describeSignature(captured),
             failedRequests: fresh.failedRequests.slice(0, MAX_ITEMS),
             consoleErrors: fresh.consoleErrors.slice(0, MAX_ITEMS),
           }),
@@ -273,6 +312,29 @@ const test = base.test.extend({
 
     await use(page);
 
+    // Read the page before anything else looks at the outcome. A test that
+    // failed is exactly the one where knowing what was on screen matters most,
+    // so this runs whether it passed or not. It is null when the page could
+    // not be read at all, and a null is never treated as a difference - not
+    // knowing what the page showed is not evidence that it changed.
+    //
+    // Printed only when asked for, and handed to the CLI through a file:
+    // Playwright pipes this worker's descriptors and gives whatever comes out
+    // to reporter stdio hooks that this reporter does not implement, so
+    // anything printed from here is dropped before it reaches a terminal.
+    const captured = await signature.collectSignature(page, failedRequests);
+    if (signature.signatureEnabled()) signature.recordSignature(testInfo.title, captured);
+
+    // Said once per run by the reporter, not once per test: it is a fact about
+    // the app, and repeating it for every recording would be noise.
+    if (captured && captured.guessedEncoding) {
+      try {
+        await testInfo.attach('kryptheon-encoding', { body: 'guessed', contentType: 'text/plain' });
+      } catch (e) {
+        /* a note, never a second failure */
+      }
+    }
+
     // The test's own assertions decide first. A test that already failed keeps
     // its own error, and never contributes a baseline.
     if (testInfo.status !== testInfo.expectedStatus) {
@@ -280,7 +342,7 @@ const test = base.test.extend({
       return;
     }
 
-    // Passed: capture what the page ended up as, noise included.
+    // Passed: keep what the page ended up as, noise included.
     let current = null;
     try {
       current = {
@@ -288,6 +350,7 @@ const test = base.test.extend({
         title: normaliseTitle(await page.title()),
         consoleErrors: consoleErrors,
         failedRequests: failedRequests,
+        signature: captured,
       };
     } catch (e) {
       current = null; // page closed by the test - leave any baseline untouched
@@ -320,5 +383,6 @@ module.exports = {
   normaliseTitle: normaliseTitle,
   compareBaselines: compareBaselines,
   applyBaseline: applyBaseline,
+  upgradeBaseline: upgradeBaseline,
   BASELINE_FILE: BASELINE_FILE,
 };

package/kryptheon-reporter.js

@@ -189,8 +189,11 @@ function translate(message) {
       return l.indexOf('Baseline changed:') !== -1;
     });
     const head = lines[headIndex].replace(/^.*Baseline changed:\s*/, '');
+    // An allowlist, so a stack trace that happens to follow the message can
+    // never leak into the report. Address and title come from the original
+    // baseline; the rest name what the page stopped or started showing.
     const details = lines.slice(headIndex + 1).filter(function (l) {
-      return /^(Address|Title) (was|now):/.test(l);
+      return /^(Address|Title) (was|now):/.test(l) || /^(Headings|Buttons and links|Form fields) that are (gone|new):/.test(l) || /^Requests that failed this time:/.test(l);
     });
     return {
       reason: capitalise(head),
@@ -406,6 +409,9 @@ function whereToLookLines(obs) {
   const lines = [];
 
   if (obs.url) lines.push('     - Browser was on: ' + obs.url);
+  // Where the flow actually got to, in words. The whole signature stays behind
+  // KRYPTHEON_DEBUG_SIGNATURE for when that much detail is wanted.
+  if (obs.pageShowed) lines.push('     - Page showed: ' + obs.pageShowed);
 
   for (const req of uniq(obs.failedRequests).slice(0, 5)) {
     const meaning = describeStatus(req.status);
@@ -568,6 +574,8 @@ class KryptheonReporter {
     this.previousRuns = [];
     this.records = [];
     this.startedAt = new Date();
+    // Set by any test whose page never said what encoding it was in.
+    this.sawGuessedEncoding = false;
   }
 
   onBegin() {
@@ -624,6 +632,9 @@ class KryptheonReporter {
   }
 
   onTestEnd(test, result) {
+    if ((result.attachments || []).some(function (a) { return a.name === 'kryptheon-encoding'; })) {
+      this.sawGuessedEncoding = true;
+    }
     const status =
       result.status === 'passed' ? 'passed' : result.status === 'skipped' ? 'skipped' : 'failed';
     const timestamp = (result.startTime instanceof Date ? result.startTime : new Date()).toISOString();
@@ -787,6 +798,15 @@ class KryptheonReporter {
       '\nSummary: ' + passed + ' working, ' + failed + ' broken.\n' +
       'History saved to ' + path.basename(HISTORY_FILE) + '\n\n'
     );
+
+    // Once per run, not once per test: it is one fact about the app, and
+    // repeating it under every recording would bury the reports themselves.
+    if (this.sawGuessedEncoding) {
+      process.stdout.write(
+        'Note: this page does not declare a character encoding, so text may look\n' +
+        'garbled here and in the browser. Add <meta charset="utf-8"> to the page.\n\n'
+      );
+    }
   }
 }