kryptheon 0.1.1 → 0.1.3

package/bin/kryptheon.js

@@ -10,7 +10,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
+const replay = require('../kryptheon-replay.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -19,6 +20,10 @@ const TESTS_DIR = path.join(USER_DIR, 'tests');
 
 const MIN_NODE = [20, 6, 0];
 
+// How long to wait for a browser window to appear before giving up.
+const WINDOW_POLL_MS = 3000;
+const WINDOW_TIMEOUT_MS = 30000;
+
 function nodeIsTooOld(version) {
   const parts = String(version || process.versions.node).split('.').map(Number);
   for (let i = 0; i < MIN_NODE.length; i++) {
@@ -133,6 +138,43 @@ function listSpecFiles() {
     .filter((name) => /\.(spec|test)\.(c|m)?[jt]sx?$/.test(name));
 }
 
+// A plain GET on Node's own http/https, deliberately NOT fetch. fetch keeps
+// its sockets alive in a pool, and those were still open at exit - handles
+// being torn down while the process is ending is how libuv assertions happen
+// on Windows. agent:false closes the socket as soon as we are done with it.
+function httpGet(url, timeoutMs, redirectsLeft) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      return reject(Object.assign(new Error('bad address'), { code: 'ERR_INVALID_URL' }));
+    }
+    const lib = parsed.protocol === 'https:' ? require('https') : require('http');
+    const req = lib.get(url, { agent: false, timeout: timeoutMs || 8000 }, (res) => {
+      const location = res.headers && res.headers.location;
+      if (location && res.statusCode >= 300 && res.statusCode < 400 && (redirectsLeft || 0) > 0) {
+        res.resume();
+        req.destroy();
+        return resolve(httpGet(new URL(location, url).toString(), timeoutMs, redirectsLeft - 1));
+      }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        if (body.length < 300000) body += chunk;
+      });
+      res.on('end', () => {
+        req.destroy();
+        resolve({ status: res.statusCode, body: body });
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy(Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' }));
+    });
+    req.on('error', reject);
+  });
+}
+
 // --- is the address actually there? ----------------------------------------
 
 // "localhost:3000" is what people type; give it a scheme before using it.
@@ -177,10 +219,7 @@ function classifyFetchError(err) {
 
 async function reachability(url, timeoutMs) {
   try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs || 8000);
-    await fetch(url, { signal: controller.signal, redirect: 'manual' });
-    clearTimeout(timer);
+    await httpGet(url, timeoutMs || 8000, 0);
     return { ok: true, kind: 'reachable' };
   } catch (err) {
     const kind = classifyFetchError(err);
@@ -251,6 +290,19 @@ function countRecordedActions(source) {
   return found ? found.length : 0;
 }
 
+// A spec that pulls Playwright in directly gets none of our diagnostics.
+function importsPlaywrightDirectly(source) {
+  const text = String(source || '');
+  // The literal specifier is what matters; import and require both carry it.
+  return text.indexOf("'@playwright/test'") !== -1 || text.indexOf('"@playwright/test"') !== -1;
+}
+
+// codegen always writes the opening page.goto. A recording is only real if
+// something else happened as well.
+function isRealRecording(source) {
+  return countRecordedActions(source) >= 2;
+}
+
 function timestampName() {
   const d = new Date();
   const pad = (n) => String(n).padStart(2, '0');
@@ -324,13 +376,9 @@ function nameFromTitle(title) {
 // to the recorded path if this cannot be reached.
 async function fetchTitle(url) {
   try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 5000);
-    const res = await fetch(url, { signal: controller.signal });
-    clearTimeout(timer);
-    if (!res.ok) return null;
-    const html = await res.text();
-    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const res = await httpGet(url, 5000, 2);
+    if (!res || res.status < 200 || res.status >= 300) return null;
+    const m = String(res.body).match(/<title[^>]*>([\s\S]*?)<\/title>/i);
     return m ? m[1].replace(/\s+/g, ' ').trim() : null;
   } catch (err) {
     return null;
@@ -357,8 +405,13 @@ function deriveTestName(source) {
     if (name) return name;
   }
 
-  const names = [...String(source).matchAll(/name:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
-  if (names.length) return names[names.length - 1].trim();
+  // The first thing done describes a recording better than the last, and the
+  // last is often "Sign Out", which would name every recording after the way
+  // it ended rather than what it was for.
+  const names = [...String(source).matchAll(/name:\s*['"]([^'"]+)['"]/g)]
+    .map((m) => m[1].trim())
+    .filter((name) => name && !/(log|sign)[\s_-]?out/i.test(name));
+  if (names.length) return names[0];
 
   const hosts = [...String(source).matchAll(/page\.goto\(\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
   if (hosts.length) {
@@ -420,72 +473,207 @@ async function nameRecording(relativeFile) {
   }
   return target;
 }
+// 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;
+}
 
-async function record(url) {
-  if (!url) {
-    console.error('');
-    console.error('  Which address should I open?');
+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('');
+}
+
+// Is a Playwright-controlled browser actually showing a window?
+function browserWindowIsUp() {
+  try {
+    if (process.platform === 'win32') {
+      const probe = spawnSync(
+        'powershell',
+        [
+          '-NoProfile',
+          '-Command',
+          "@(Get-Process chrome,msedge -ErrorAction SilentlyContinue | " +
+            "Where-Object { $_.Path -like '*ms-playwright*' -and $_.MainWindowHandle -ne 0 }).Count",
+        ],
+        { encoding: 'utf8', windowsHide: true, timeout: 8000 }
+      );
+      return Number(String(probe.stdout || '').trim()) > 0;
+    }
+    const probe = spawnSync('ps', ['-A', '-o', 'command'], { encoding: 'utf8', timeout: 8000 });
+    return /ms-playwright/.test(String(probe.stdout || ''));
+  } catch (err) {
+    return true; // cannot tell - do not block the user
+  }
+}
+
+// Runs codegen without blocking the event loop, so SIGINT and SIGTERM can
+// still be handled. spawnSync would freeze the loop and no handler would run.
+function startCodegen(args) {
+  const cli = findPlaywrightCli();
+  if (!cli) {
     console.error('');
-    console.error('  Add the web address of your app, for example:');
-    console.error('    kryptheon record https://www.example.com');
+    console.error('  The testing engine is missing from this install.');
+    console.error('  Reinstalling usually fixes it:  npm install -g kryptheon');
     console.error('');
-    return 1;
+    return null;
   }
-  const target = normaliseRecordUrl(url);
+  return spawn(process.execPath, [cli].concat(args), {
+    cwd: USER_DIR,
+    stdio: ['inherit', 'inherit', 'pipe'],
+  });
+}
 
-  // Fail early and kindly rather than letting codegen throw a stack trace.
-  const reach = await reachability(target);
-  if (!reach.ok) {
-    explainUnreachable(target, reach.kind);
-    return 1;
-  }
+// --- making a recording fit to run twice ------------------------------------
 
-  if (!ensureBrowser()) return 1;
+function readSpec(relativeFile) {
+  try {
+    return fs.readFileSync(path.join(USER_DIR, relativeFile), 'utf8');
+  } catch (err) {
+    return null;
+  }
+}
 
-  const hadTestsDir = fs.existsSync(TESTS_DIR);
+function writeSpec(relativeFile, source) {
   try {
-    fs.mkdirSync(TESTS_DIR, { recursive: true });
+    fs.writeFileSync(path.join(USER_DIR, relativeFile), source, 'utf8');
+    return true;
   } catch (err) {
-    /* codegen will report if it cannot write */
+    return false;
   }
+}
 
-  let outFile = path.join('tests', timestampName());
+// Passwords typed during recording land in the file as plain text. Swap them
+// for environment variables before the file is left lying around.
+function takeOutSecrets(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const result = replay.scrubSecrets(source);
+  if (!result.replacements.length) return [];
+  return writeSpec(relativeFile, result.source) ? result.replacements : [];
+}
 
+function reportSecrets(replacements) {
+  if (!replacements || !replacements.length) return;
+  console.log('  What you typed into the password box was not saved in the test.');
   console.log('');
-  console.log('  Opening ' + target + ' in a browser.');
-  console.log('');
-  console.log('  Use your app normally - click, type, sign in, whatever you want');
-  console.log('  covered. Every step is recorded as you go.');
+  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');
+  }
   console.log('');
-  console.log('  When you are done, close the browser window to save the test.');
+  console.log('  Keep .env out of version control - it holds the real value.');
   console.log('');
+}
 
-  const run = runPlaywright(['codegen', '--target', 'playwright-test', '-o', outFile, target], {
-    quietErrors: true,
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve(false);
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      // Let the loop finish later: stdin stays open otherwise.
+      try {
+        process.stdin.pause();
+      } catch (err) {
+        /* nothing to do */
+      }
+      resolve(!/^\s*n/i.test(String(answer)));
+    });
   });
+}
+
+// Ending on a logout means the next run starts somewhere else. Almost nobody
+// wants that, so ask.
+async function offerToDropLogout(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return false;
+  const trimmed = replay.dropTrailingLogout(source);
+  if (!trimmed.removed) return false;
 
+  console.log('  The recording ends by logging out ("' + trimmed.removed + '").');
+  console.log('  That means the next run would not start where this one did.');
+  console.log('');
+
+  const drop = await askYesNo('  Leave that last step out? [Y/n] ');
+  if (!drop) {
+    console.log('');
+    console.log('  Kept it. If checks fail from the second run onwards, this is why.');
+    console.log('');
+    return false;
+  }
+  writeSpec(relativeFile, trimmed.source);
+  console.log('');
+  console.log('  Removed the sign-out step.');
+  console.log('');
+  return true;
+}
+
+function reportReplayRisks(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const risks = replay.findReplayRisks(source);
+  if (!risks.length) return [];
+
+  console.log('  Before you rely on this recording, one thing to know:');
+  console.log('');
+  for (const risk of risks) {
+    console.log('    "' + risk.step + '" (line ' + risk.line + ')');
+    console.log('      ' + risk.why + '.');
+    console.log('      What to do: ' + risk.fix + '.');
+    console.log('');
+  }
+  console.log('  Everything else in the recording will run again fine.');
+  console.log('');
+  return risks;
+}
+
+// Everything that has to happen to whatever codegen left behind, however
+// the run ended. Module level so it can be exercised directly.
+async function finaliseRecording(outFile, context) {
+  const ctx = context || {};
   const specPath = path.join(USER_DIR, outFile);
   let source = null;
   try {
     source = fs.readFileSync(specPath, 'utf8');
   } catch (err) {
-    source = null; // codegen wrote nothing at all
+    source = null;
   }
 
-  // Keyed off what is in the file rather than the exit code: codegen still
-  // writes a recording when the window is force-closed, and still leaves an
-  // empty shell behind when the page never loaded.
-  if (source !== null && countRecordedActions(source) > 0) {
+  if (source !== null && isRealRecording(source)) {
+    // Import rewrite first: it is instant, so even a second interruption
+    // leaves behind a spec that works.
     pointAtFixture(outFile);
-    outFile = await nameRecording(outFile);
+
+    // Anything typed into a password box is still a literal in this file at
+    // this point. Take it out before doing anything else with the file.
+    const secrets = takeOutSecrets(outFile);
+
+    const named = await nameRecording(outFile);
     console.log('');
-    console.log('  Saved to ' + outFile);
+    console.log('  Saved to ' + named);
     console.log('  Run it any time with:  kryptheon check');
     console.log('');
-    return 0;
+
+    reportSecrets(secrets);
+    await offerToDropLogout(named);
+    reportReplayRisks(named);
+
+    return { code: 0, savedAs: named };
   }
 
-  // Nothing usable: leave no empty file behind.
   if (source !== null) {
     try {
       fs.unlinkSync(specPath);
@@ -493,7 +681,7 @@ async function record(url) {
       /* nothing more we can do */
     }
   }
-  if (!hadTestsDir) {
+  if (!ctx.hadTestsDir) {
     try {
       if (fs.readdirSync(TESTS_DIR).length === 0) fs.rmdirSync(TESTS_DIR);
     } catch (err) {
@@ -501,8 +689,16 @@ async function record(url) {
     }
   }
 
-  if (run.status !== 0 || source === null) {
-    explainCodegenFailure(target, run.stderr);
+  if (ctx.reason === 'no-window') {
+    explainNoWindow(ctx.target);
+  } else if (ctx.reason === 'signal') {
+    console.log('');
+    console.log('  Recording stopped before anything was saved.');
+    console.log('');
+    console.log('  Nothing was recorded.');
+    console.log('');
+  } else if (source === null || /ERR_|Error:/.test(String(ctx.stderr || ''))) {
+    explainCodegenFailure(ctx.target, ctx.stderr);
   } else {
     console.log('');
     console.log('  Nothing was recorded.');
@@ -511,7 +707,125 @@ async function record(url) {
     console.log('  Run the same command again and use your app before closing it.');
     console.log('');
   }
-  return 1;
+  return { code: 1, savedAs: null };
+}
+
+async function record(url) {
+  if (!url) {
+    console.error('');
+    console.error('  Which address should I open?');
+    console.error('');
+    console.error('  Add the web address of your app, for example:');
+    console.error('    kryptheon record https://www.example.com');
+    console.error('');
+    return 1;
+  }
+
+  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) {
+    explainUnreachable(target, reach.kind);
+    return 1;
+  }
+
+  if (!ensureBrowser()) return 1;
+
+  const hadTestsDir = fs.existsSync(TESTS_DIR);
+  try {
+    fs.mkdirSync(TESTS_DIR, { recursive: true });
+  } catch (err) {
+    /* codegen will report if it cannot write */
+  }
+
+  const outFile = path.join('tests', timestampName());
+  const specPath = path.join(USER_DIR, outFile);
+
+  console.log('');
+  console.log('  Opening ' + target + ' in a browser.');
+  console.log('');
+  console.log('  Use your app normally - click, type, sign in, whatever you want');
+  console.log('  covered. Every step is recorded as you go.');
+  console.log('');
+  console.log('  When you are done, close the browser window to save the test.');
+  console.log('');
+
+  const child = startCodegen(['codegen', '--target', 'playwright-test', '-o', outFile, target]);
+  if (!child) return 1;
+
+  let stderr = '';
+  if (child.stderr) child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+  // Everything that has to happen no matter how this ends: tidy the file,
+  // wire it up, name it. Runs once, whether codegen exits on its own or we
+  // are interrupted.
+  let finished = false;
+  const finalise = async (reason) => {
+    if (finished) return 1;
+    finished = true;
+    const outcome = await finaliseRecording(outFile, {
+      hadTestsDir: hadTestsDir,
+      target: target,
+      stderr: stderr,
+      reason: reason,
+    });
+    return outcome.code;
+  };
+
+  const stopChild = () => {
+    try {
+      child.kill();
+    } catch (err) {
+      /* already gone */
+    }
+  };
+
+  return await new Promise((resolve) => {
+    // If no window ever appears, stop instead of waiting for someone to kill us.
+    let waited = 0;
+    const watchdog = setInterval(() => {
+      waited += WINDOW_POLL_MS;
+      if (browserWindowIsUp()) {
+        clearInterval(watchdog);
+        return;
+      }
+      if (waited >= WINDOW_TIMEOUT_MS) {
+        clearInterval(watchdog);
+        stopChild();
+        finalise('no-window').then(resolve);
+      }
+    }, WINDOW_POLL_MS);
+
+    const onSignal = () => {
+      clearInterval(watchdog);
+      stopChild();
+      finalise('signal').then(resolve);
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    process.once('SIGHUP', onSignal);
+
+    child.on('error', () => {
+      clearInterval(watchdog);
+      finalise('error').then(resolve);
+    });
+
+    child.on('close', () => {
+      clearInterval(watchdog);
+      process.removeListener('SIGINT', onSignal);
+      process.removeListener('SIGTERM', onSignal);
+      process.removeListener('SIGHUP', onSignal);
+      finalise('exit').then(resolve);
+    });
+  });
 }
 
 // Recordings import the fixture by package name, which only resolves if
@@ -545,6 +859,58 @@ function specsNeedThePackage() {
   });
 }
 
+// Older versions, and any run that was killed part way, left specs behind that
+// import Playwright directly (so they produce no diagnostics) or that contain
+// nothing but the opening navigation (so they verify nothing). Repair the
+// first kind and refuse to run the second, rather than reporting a false OK.
+function triageSpecs() {
+  const repaired = [];
+  const notRecordings = [];
+  const runnable = [];
+  const withSecrets = [];
+
+  for (const name of listSpecFiles()) {
+    const full = path.join(TESTS_DIR, name);
+    let source;
+    try {
+      source = fs.readFileSync(full, 'utf8');
+    } catch (err) {
+      continue;
+    }
+
+    if (/(from|require\()\s*(['"])@playwright\/test\2/.test(source)) {
+      const relative = path.join('tests', name);
+      if (pointAtFixture(relative)) {
+        repaired.push(name);
+        try {
+          source = fs.readFileSync(full, 'utf8');
+        } catch (err) {
+          /* keep what we had */
+        }
+      }
+    }
+
+    if (!isRealRecording(source)) {
+      notRecordings.push(name);
+      continue;
+    }
+    // Recordings made before secrets were stripped still hold the real value.
+    // Say so rather than rewriting: a spec that works today should keep
+    // working until the person has somewhere to put the password.
+    if (replay.scrubSecrets(source).replacements.length) {
+      withSecrets.push({ name: name, fields: replay.scrubSecrets(source).replacements });
+    }
+    runnable.push(name);
+  }
+
+  return {
+    repaired: repaired,
+    notRecordings: notRecordings,
+    runnable: runnable,
+    withSecrets: withSecrets,
+  };
+}
+
 function check() {
   if (!listSpecFiles().length) {
     console.log('');
@@ -570,8 +936,57 @@ function check() {
     console.log('');
     return 1;
   }
+  const triage = triageSpecs();
+
+  for (const name of triage.repaired) {
+    console.log('');
+    console.log('  Repaired ' + path.join('tests', name));
+    console.log('  It was saved without the part that explains failures. Fixed now.');
+  }
+
+  for (const item of triage.withSecrets) {
+    console.log('');
+    console.log('  Careful: ' + path.join('tests', item.name) + ' has a real password written into it.');
+    console.log('  Anyone who can read that file can read the password.');
+    console.log('  Re-record it to have the password moved into .env automatically.');
+  }
+
+  for (const name of triage.notRecordings) {
+    console.log('');
+    console.log('  Skipped ' + path.join('tests', name));
+    console.log('  This is not a real recording - it only opens a page and stops,');
+    console.log('  so it cannot tell you whether anything works.');
+    console.log('  Record it again:  kryptheon record <url>');
+  }
+
+  if (!triage.runnable.length) {
+    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>');
+    console.log('');
+    return 1;
+  }
+
   if (!ensureBrowser()) return 1;
-  return runPlaywright(['test', '--config', CONFIG]).status;
+
+  // Only the usable recordings are handed to the test runner, so a file that
+  // cannot produce diagnostics can never be counted as passing.
+  const only = triage.runnable.map((name) => path.join('tests', name).split(path.sep).join('/'));
+  const status = runPlaywright(['test', '--config', CONFIG].concat(only)).status;
+
+  // Without this, a green summary could still hide a recording that checked
+  // nothing at all.
+  if (triage.notRecordings.length) {
+    const many = triage.notRecordings.length > 1;
+    console.log(
+      '  Note: ' + triage.notRecordings.length + ' recording' + (many ? 's' : '') +
+        ' above checked nothing and ' + (many ? 'were' : 'was') + ' skipped.'
+    );
+    console.log('');
+  }
+  return status;
 }
 
 // --- accept -----------------------------------------------------------------
@@ -676,6 +1091,29 @@ function accept(name) {
 
 const [command, ...rest] = process.argv.slice(2);
 
+// process.exit() cuts the process off mid-teardown. On Windows a terminal's
+// output is written asynchronously, so exiting while the last line is still
+// queued tears down a handle that is already closing - which is what produces
+// "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)" in libuv. Setting
+// the code and letting Node wind down on its own avoids that entirely, and
+// still reports the same exit status.
+async function finishWith(code) {
+  process.exitCode = code;
+  const streams = [process.stdout, process.stderr];
+  await Promise.all(
+    streams.map(
+      (stream) =>
+        new Promise((resolve) => {
+          if (!stream || typeof stream.write !== 'function' || !stream.writableLength) return resolve();
+          const done = () => resolve();
+          stream.once('drain', done);
+          const guard = setTimeout(done, 1000);
+          if (guard.unref) guard.unref();
+        })
+    )
+  );
+}
+
 async function main() {
   if (nodeIsTooOld()) {
     console.error('');
@@ -685,31 +1123,31 @@ async function main() {
     console.error('');
     console.error('  Download the latest from https://nodejs.org and try again.');
     console.error('');
-    process.exit(1);
+    return finishWith(1);
   }
 
   switch (command) {
     case 'record':
-      process.exit(await record(rest[0]));
+      return finishWith(await record(rest[0]));
       break;
     case 'check':
-      process.exit(check());
+      return finishWith(check());
       break;
     case 'accept':
-      process.exit(accept(rest.join(' ').trim()));
+      return finishWith(accept(rest.join(' ').trim()));
       break;
     case undefined:
     case '-h':
     case '--help':
     case 'help':
       usage();
-      process.exit(0);
+      return finishWith(0);
       break;
     default:
       console.error('');
       console.error('  Unknown command: ' + command);
       usage();
-      process.exit(1);
+      return finishWith(1);
   }
 }
 
@@ -723,6 +1161,15 @@ module.exports = {
   pointAtFixture: pointAtFixture,
   listSpecFiles: listSpecFiles,
   countRecordedActions: countRecordedActions,
+  isRealRecording: isRealRecording,
+  importsPlaywrightDirectly: importsPlaywrightDirectly,
+  triageSpecs: triageSpecs,
+  record: record,
+  finaliseRecording: finaliseRecording,
+  takeOutSecrets: takeOutSecrets,
+  reportReplayRisks: reportReplayRisks,
+  offerToDropLogout: offerToDropLogout,
+  looksLikeNoDesktop: looksLikeNoDesktop,
   classifyFetchError: classifyFetchError,
   normaliseRecordUrl: normaliseRecordUrl,
   isLocalAddress: isLocalAddress,

package/kryptheon-reporter.js

@@ -477,6 +477,84 @@ function buildPromptLines(testTitle, translated, obs, lastPassIso, now) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// The first run is a special case: nothing has regressed, because nothing has
+// ever passed. Usually the recording itself contains a step that only worked
+// the once.
+// ---------------------------------------------------------------------------
+
+// Playwright works the error's file out of a stack trace, and its parser
+// stops at the first "(" - so a folder called "New folder (2)" arrives as
+// "2)\tests\thing.spec.js". The path declared for the test itself is read from
+// the file system and is always whole, so prefer that whenever the stack's
+// version does not point at a real file.
+function trustworthySpecPath(test, errorFile) {
+  const declared = (test && test.location && test.location.file) || null;
+  if (errorFile && path.isAbsolute(errorFile)) {
+    try {
+      if (fs.existsSync(errorFile)) return errorFile;
+    } catch (err) {
+      /* fall through to the declared path */
+    }
+  }
+  if (declared) {
+    try {
+      if (fs.existsSync(declared)) return declared;
+    } catch (err) {
+      /* fall through */
+    }
+  }
+  return errorFile || declared || null;
+}
+
+// Identity of the recording itself, so history cannot be inherited by a
+// different recording that happens to share a name.
+function recordingIdFor(specPath) {
+  if (!specPath) return null;
+  let source;
+  try {
+    source = fs.readFileSync(specPath, 'utf8');
+  } catch (err) {
+    return null;
+  }
+  try {
+    return require('./kryptheon-replay.js').recordingId(source);
+  } catch (err) {
+    return null;
+  }
+}
+
+function firstRunAdvice(test) {
+  const lines = [];
+  lines.push('   This is the first run of this recording, so nothing has broken yet -');
+  lines.push('   a step that cannot happen twice is the more likely explanation.');
+
+  const file = test && test.location && test.location.file;
+  if (!file) return { lines: lines, namedAStep: false };
+
+  let source;
+  try {
+    source = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return { lines: lines, namedAStep: false };
+  }
+
+  let risks = [];
+  try {
+    risks = require('./kryptheon-replay.js').findReplayRisks(source);
+  } catch (err) {
+    return { lines: lines, namedAStep: false };
+  }
+  if (!risks.length) return { lines: lines, namedAStep: false };
+
+  lines.push('   Most likely the step that cannot repeat:');
+  for (const risk of risks.slice(0, 3)) {
+    lines.push('     - "' + risk.step + '" (line ' + risk.line + ') - ' + risk.why + '.');
+  }
+  lines.push('   Record again without it, and this should settle down.');
+  return { lines: lines, namedAStep: true };
+}
+
 // ---------------------------------------------------------------------------
 // Reporter
 // ---------------------------------------------------------------------------
@@ -518,15 +596,22 @@ class KryptheonReporter {
     }
   }
 
-  // Most recent earlier run in which this same test title passed.
-  _lastPassed(title) {
+  // Most recent earlier run in which THIS recording passed. The name alone is
+  // not enough: deleting a recording and making a new one that happens to end
+  // up with the same name would otherwise inherit the old one's history, and
+  // a brand new recording would be told it "was working" yesterday.
+  _lastPassed(title, recordingId) {
     for (let i = this.previousRuns.length - 1; i >= 0; i--) {
       const run = this.previousRuns[i];
       const tests = (run && run.tests) || [];
       for (let j = tests.length - 1; j >= 0; j--) {
-        if (tests[j] && tests[j].title === title && tests[j].status === 'passed') {
-          return tests[j].timestamp || run.runAt;
-        }
+        const entry = tests[j];
+        if (!entry || entry.title !== title || entry.status !== 'passed') continue;
+        // Entries written before recordings were fingerprinted cannot be
+        // matched to one, so they are not claimed by any.
+        if (!entry.recordingId || !recordingId) continue;
+        if (entry.recordingId !== recordingId) continue;
+        return entry.timestamp || run.runAt;
       }
     }
     return null;
@@ -537,11 +622,16 @@ class KryptheonReporter {
       result.status === 'passed' ? 'passed' : result.status === 'skipped' ? 'skipped' : 'failed';
     const timestamp = (result.startTime instanceof Date ? result.startTime : new Date()).toISOString();
 
+    const specPath = trustworthySpecPath(test, null);
+    const recordingId = recordingIdFor(specPath);
+
     const record = {
       title: test.title,
       status: status,
       durationMs: result.duration,
       timestamp: timestamp,
+      recordingId: recordingId,
+      specFile: specPath ? path.relative(USER_DIR, specPath) : null,
     };
 
     if (status === 'skipped') {
@@ -585,7 +675,7 @@ class KryptheonReporter {
     const observations = readObservations(result.attachments);
     const located = primary.location || (errors.find(function (e) { return e.location; }) || {}).location;
     const line = located ? located.line : null;
-    const file = located ? located.file : null;
+    const file = trustworthySpecPath(test, located ? located.file : null);
     const locator = extractLocator(message);
     const translated = translate(message);
 
@@ -612,13 +702,28 @@ class KryptheonReporter {
 
     for (const detail of translated.details || []) out.push('   ' + detail);
 
-    const lastPass = this._lastPassed(test.title);
+    const lastPass = this._lastPassed(test.title, recordingId);
     out.push(lastPass ? '   This was working on ' + formatWhen(lastPass) + '.' : '   This has not passed before.');
 
-    if (translated.advice) {
+    // A first run that fails is a different situation from a regression:
+    // nothing has broken, because nothing ever worked. Far more often the
+    // recording contains a step that cannot happen twice.
+    let blamedTheRecording = false;
+    if (!lastPass) {
+      const advice = firstRunAdvice(test);
+      for (const line of advice.lines) out.push(line);
+      blamedTheRecording = advice.namedAStep;
+    }
+
+    // On a first run we have already named the step that cannot repeat, and
+    // the usual "your last change may have..." advice would contradict it.
+    if (blamedTheRecording) {
+      /* the first-run block above already says what to do */
+    } else if (translated.advice) {
       out.push('   What to check: ' + translated.advice.split('%TEST%').join(test.title));
+    } else {
+      out.push('   What to check: this is the raw message from the test tool - it was not recognised.');
     }
-    else out.push('   What to check: this is the raw message from the test tool - it was not recognised.');
 
     for (const observed of whereToLookLines(observations)) out.push(observed);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -11,14 +11,16 @@
     ".": "./kryptheon-fixture.js",
     "./kryptheon-fixture": "./kryptheon-fixture.js",
     "./kryptheon-reporter": "./kryptheon-reporter.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./kryptheon-replay": "./kryptheon-replay.js"
   },
   "files": [
     "bin/",
     "kryptheon-fixture.js",
     "kryptheon-reporter.js",
     "playwright.config.js",
-    "README.md"
+    "README.md",
+    "kryptheon-replay.js"
   ],
   "engines": {
     "node": ">=20.6.0"