kryptheon 0.1.2 → 0.1.4

package/README.md

@@ -1,36 +1,39 @@
 # kryptheon
 
-Record what you do in your app, and get told in plain English when it breaks.
+Record a flow in your app once, replay it after every AI change, and get told in
+plain English what broke.
 
-No test code to write, no config to edit.
+Runs entirely on your machine. No account, no API key, nothing leaves your
+computer. It is a wrapper around [Playwright](https://playwright.dev).
 
-## Use it
+Made by a 17-year-old vibecoder who kept having AI break things in his own app.
 
-Install it into your project first:
+## Install
 
 ```
 npm i -D kryptheon
 ```
 
-This step is not optional. Every recording kryptheon writes starts with
-`import { test, expect } from 'kryptheon/kryptheon-fixture'`, and your tests can
-only find that import if kryptheon lives in your project's `node_modules`.
-Running `npx kryptheon` without installing will record fine but fail to check.
+Install it into your project, not globally — every recording imports
+`kryptheon/kryptheon-fixture`, and your tests can only find that if kryptheon is
+in your project's `node_modules`.
 
-Then record:
+## Record
 
 ```
 npx kryptheon record https://your-app.example.com
 ```
 
-A browser opens. Use your app the way a customer would — click, type, sign in.
-Close the browser when you are done, and the recording is saved as a test.
+A browser opens. Use your app the way a customer would. Close the browser when
+you are done, and the recording is saved as a test.
+
+## Check
 
 ```
 npx kryptheon check
 ```
 
-Runs everything you have recorded and reports what happened:
+Runs everything you have recorded:
 
 ```
 OK  Sign in  (4.1s)
@@ -45,15 +48,28 @@ X  Checkout
        the server crashed or is unavailable - the error is in backend code, not the page
 ```
 
-Every failure also ends with a short summary you can paste straight into an AI
-coding tool.
+Every failure ends with a short summary you can paste straight into an AI coding
+tool.
+
+## Recording something that replays
+
+A recording is only useful if it still works the second time. So:
+
+- **Record one simple flow.** Sign in and look at a page. Open a thing and check
+  it loaded. Short beats thorough.
+- **Sign in with an account that already exists.** Do not sign up during a
+  recording — the account exists next time, and the signup step fails.
+- **Avoid steps that cannot repeat.** Adding data piles up a row on every run.
+  Logging out at the end means the next run does not start where this one did.
+
+Kryptheon warns you about these after a recording, and names the exact step.
 
 ## Automatic checks
 
-The first time a test passes, kryptheon remembers where the browser ended up
-and what the page was called. If either changes later, the test fails and tells
-you what changed — so a recording catches regressions without you writing a
-single assertion.
+The first time a test passes, kryptheon remembers where the browser ended up and
+what the page was called. If either changes later, the test fails and says what
+changed — so a recording catches regressions without you writing a single
+assertion.
 
 When a change is intentional, accept it for that one test:
 
@@ -71,15 +87,18 @@ npx kryptheon accept "Checkout"
 | `kryptheon-baselines.json` | the remembered result for each test |
 | `kryptheon-history.jsonl` | one line per run, used for "this was working on …" |
 
-`.env` in the same folder is loaded automatically, so a recording can sign in
-without the password living in the test file.
+A `.env` in the same folder is loaded automatically, and anything you type into a
+password box is replaced with an environment variable rather than written into
+the test.
 
 Worth adding to `.gitignore`: `.env`, `kryptheon-baselines.json`,
 `kryptheon-history.jsonl`, `test-results/`.
 
 ## Requirements
 
-Node 20.6 or later. The first run downloads a browser (about 200MB, once).
+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).
 
 ## Licence
 

package/bin/kryptheon.js

@@ -11,6 +11,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
+const replay = require('../kryptheon-replay.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -404,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) {
@@ -529,6 +535,111 @@ function startCodegen(args) {
   });
 }
 
+// --- making a recording fit to run twice ------------------------------------
+
+function readSpec(relativeFile) {
+  try {
+    return fs.readFileSync(path.join(USER_DIR, relativeFile), 'utf8');
+  } catch (err) {
+    return null;
+  }
+}
+
+function writeSpec(relativeFile, source) {
+  try {
+    fs.writeFileSync(path.join(USER_DIR, relativeFile), source, 'utf8');
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// 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('  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('  Keep .env out of version control - it holds the real value.');
+  console.log('');
+}
+
+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) {
@@ -545,11 +656,21 @@ async function finaliseRecording(outFile, context) {
     // Import rewrite first: it is instant, so even a second interruption
     // leaves behind a spec that works.
     pointAtFixture(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 ' + named);
     console.log('  Run it any time with:  kryptheon check');
     console.log('');
+
+    reportSecrets(secrets);
+    await offerToDropLogout(named);
+    reportReplayRisks(named);
+
     return { code: 0, savedAs: named };
   }
 
@@ -746,6 +867,7 @@ function triageSpecs() {
   const repaired = [];
   const notRecordings = [];
   const runnable = [];
+  const withSecrets = [];
 
   for (const name of listSpecFiles()) {
     const full = path.join(TESTS_DIR, name);
@@ -772,10 +894,21 @@ function triageSpecs() {
       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 };
+  return {
+    repaired: repaired,
+    notRecordings: notRecordings,
+    runnable: runnable,
+    withSecrets: withSecrets,
+  };
 }
 
 function check() {
@@ -811,6 +944,13 @@ function check() {
     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));
@@ -1026,6 +1166,9 @@ module.exports = {
   triageSpecs: triageSpecs,
   record: record,
   finaliseRecording: finaliseRecording,
+  takeOutSecrets: takeOutSecrets,
+  reportReplayRisks: reportReplayRisks,
+  offerToDropLogout: offerToDropLogout,
   looksLikeNoDesktop: looksLikeNoDesktop,
   classifyFetchError: classifyFetchError,
   normaliseRecordUrl: normaliseRecordUrl,

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.2",
+  "version": "0.1.4",
   "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"
@@ -34,5 +36,13 @@
     "testing",
     "end-to-end",
     "cli"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhashantanu987-beep/kryptheon-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhashantanu987-beep/kryptheon-cli/issues"
+  },
+  "homepage": "https://github.com/jhashantanu987-beep/kryptheon-cli#readme"
 }