kryptheon 0.1.18 → 0.1.20

package/README.md

@@ -161,20 +161,28 @@ wanted, and one new name of the same kind. A button that is gone with nothing
 in its place, or a rename next to other new buttons, fails as it always did.
 Checks you added with the toolbar are never redirected.
 
-## Files it creates in your folder
+## What goes where
 
-| File | What it is |
-| --- | --- |
-| `tests/` | your recordings |
-| `kryptheon-baselines.json` | the remembered result for each test |
-| `kryptheon-history.jsonl` | one line per run, used for "this was working on …" |
+Only your recordings go in your project, in `tests/`. Everything Kryptheon
+remembers about the project is kept outside it, so it can never end up in your
+repo:
+
+    ~/.kryptheon/projects/<folder-name>-<id>/
+      baselines.json   the remembered result for each test
+      history.jsonl    one line per run, used for "this was working on …"
+      test-results/    the screenshot of the last failure
+
+Set `KRYPTHEON_HOME` to keep them somewhere else. Each project folder gets its
+own store, so two projects are never mixed. A project folder that is moved or
+renamed starts a new store.
+
+Older versions kept `kryptheon-baselines.json`, `kryptheon-history.jsonl` and
+`test-results/` in the project. The first run of this version moves them out,
+once, and says so.
 
 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/`.
+the test. When there is a password, `.env` is added to an existing `.gitignore`.
 
 ## Requirements
 

package/bin/kryptheon.js

@@ -5,8 +5,11 @@
 //
 // Two roots matter, and they are not the same once this is installed:
 //   PACKAGE_DIR - the tool's own files (fixture, reporter, config, this file)
-//   USER_DIR    - the folder the command was run in, which owns tests/,
-//                 kryptheon-baselines.json, kryptheon-history.jsonl and .env
+//   USER_DIR    - the folder the command was run in, which owns tests/ and .env
+//
+// Everything Kryptheon remembers about USER_DIR - baselines, history, the last
+// run's screenshots - is kept in its store under ~/.kryptheon, never in the
+// project (kryptheon-store.js).
 
 const fs = require('fs');
 const path = require('path');
@@ -19,6 +22,11 @@ const recordings = require('../kryptheon-recordings.js');
 const cleanup = require('../kryptheon-cleanup.js');
 const baselines = require('../kryptheon-baselines.js');
 const project = require('../kryptheon-project.js');
+const store = require('../kryptheon-store.js');
+
+// The first version that keeps its records in the store. An older copy in a
+// project folder still looks for them inside the project.
+const FIRST_STORE_VERSION = '0.1.20';
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -864,15 +872,49 @@ 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() {
+// The password file is the one thing of kryptheon's in a project that must not
+// be committed. If there is already a .gitignore, it belongs in it - but only
+// once there is a password to protect: a .env here, or a recording that just
+// had one taken out. A landing page with no sign-in has nothing to hide, and
+// an edit to its .gitignore would be one more change of Kryptheon's in the repo.
+function keepArtefactsOutOfGit(passwordTakenOut) {
+  if (!passwordTakenOut && !fs.existsSync(path.join(USER_DIR, '.env'))) return;
   const added = secrets.updateGitignore(USER_DIR);
   if (!added.length) return;
   console.log('  Added to .gitignore: ' + added.join(', '));
   console.log('');
 }
 
+// The project's store, opened before anything reads a record, so whatever an
+// older version left in this folder is moved out first - and said once, here,
+// rather than by the fixture or the reporter, which run inside the test runner.
+//
+// Returns null when the store cannot be made. Carrying on would mean every
+// recording is compared against nothing, which reads as "all fine" and is
+// the one answer that must never be given by accident.
+function openStore() {
+  let opened;
+  try {
+    opened = store.open(USER_DIR);
+  } catch (err) {
+    console.error('');
+    console.error('  Kryptheon keeps what it remembers about this project in');
+    console.error('    ' + store.dirFor(USER_DIR));
+    console.error('  and could not write there: ' + err.message);
+    console.error('');
+    console.error('  Without it every recording would look new, so nothing was checked.');
+    console.error('  Set KRYPTHEON_HOME to a folder you can write to, and run this again.');
+    console.error('');
+    return null;
+  }
+  const lines = store.migrationLines(opened);
+  if (lines.length) {
+    console.log('');
+    for (const line of lines) console.log(line);
+  }
+  return opened;
+}
+
 function reportSecrets(replacements) {
   if (!replacements || !replacements.length) return;
   const names = replacements.map((item) => item.envName);
@@ -1170,7 +1212,7 @@ async function finaliseRecording(outFile, context) {
 
     reportTidying(tidied);
     reportSecrets(secrets);
-    keepArtefactsOutOfGit();
+    keepArtefactsOutOfGit(!!(secrets && secrets.length));
     await offerToDropLogout(named);
     reportReplayRisks(named);
     reportFragileSelectors(named);
@@ -1321,6 +1363,7 @@ async function remove(name) {
     console.error("");
     return 1;
   }
+  if (!openStore()) return 1;
 
   const gone = [];
   const failed = [];
@@ -1365,15 +1408,20 @@ function writeOwnPackageJson(dir) {
   }
 }
 
-function installKryptheonIn(dir) {
-  console.log('  Installing kryptheon here - this usually takes under a minute.');
-  const args = ['install', '--save-dev', 'kryptheon', '--no-audit', '--no-fund', '--loglevel=error'];
-  // npm is npm.cmd on Windows, and Node will not start a .cmd directly
-  // (spawnSync EINVAL), so there it goes through cmd.exe. Every argument is a
-  // fixed string; nothing anybody typed reaches this command line.
-  const result = process.platform === 'win32'
+// `npm install --save-dev <spec>` in a folder. npm is npm.cmd on Windows, and
+// Node will not start a .cmd directly (spawnSync EINVAL), so there it goes
+// through cmd.exe. The spec is always "kryptheon" or "kryptheon@" and a
+// version made of digits and dots; nothing anybody typed reaches this line.
+function npmInstallDev(dir, spec) {
+  const args = ['install', '--save-dev', spec, '--no-audit', '--no-fund', '--loglevel=error'];
+  return process.platform === 'win32'
     ? spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'npm'].concat(args), { cwd: dir, encoding: 'utf8' })
     : spawnSync('npm', args, { cwd: dir, encoding: 'utf8' });
+}
+
+function installKryptheonIn(dir) {
+  console.log('  Installing kryptheon here - this usually takes under a minute.');
+  const result = npmInstallDev(dir, 'kryptheon');
   // Judged by what is on disk afterwards, not by npm's exit code alone.
   const ok = !result.error && result.status === 0 && project.kryptheonInstalledIn(dir);
   if (ok) {
@@ -1489,6 +1537,9 @@ async function record(url) {
   // gets a folder set up; before the browser, which is the expensive part.
   const setup = await prepareFolder(url);
   if (setup !== null) return setup;
+  // Before an old recording can be replaced, because replacing one also drops
+  // its saved result - which has to be found where it now lives.
+  if (!openStore()) return 1;
 
   if (!ensureBrowser()) return 1;
 
@@ -1700,6 +1751,7 @@ function check(options) {
     for (const line of project.noProjectLines(here)) console.error(line);
     return 1;
   }
+  if (!openStore()) return 1;
 
   // Deliberately not a failure. An assistant told to run this after every
   // change will read a non-zero exit as "something broke" and start fixing
@@ -1978,6 +2030,9 @@ function listBaselines(api) {
 }
 
 function accept(name) {
+  // Only where there are recordings: anywhere else there is nothing to accept,
+  // and no reason to make a store for a folder that is not a project.
+  if (fs.existsSync(TESTS_DIR) && !openStore()) return 1;
   const api = baselineApi();
   if (!api) return 1;
   if (!name) return listBaselines(api);
@@ -2085,6 +2140,57 @@ function handToFolderCopy() {
     /* said as unknown */
   }
   const mine = packageVersion();
+
+  // An older copy is brought up to this one first. Found the day 0.1.18
+  // shipped: the fix was on the registry, `npx kryptheon@latest check` and
+  // every AI tool asked for it, and the folder's 0.1.17 ran anyway - the
+  // person would have had to type an npm command to get what they had
+  // already asked for. Never downwards: a folder that is ahead of a cached
+  // npx copy keeps what it has.
+  if (project.olderVersion(theirVersion, mine)) {
+    const root = path.dirname(path.dirname(theirs)); // <root>/node_modules/kryptheon
+    if (project.hasPackageJson(root)) {
+      console.log('');
+      console.log('  This folder has kryptheon ' + theirVersion + ' and this is ' + mine + '. Updating the folder\'s');
+      console.log('  copy, because your recordings load that one - usually under a minute.');
+      const result = npmInstallDev(root, 'kryptheon@' + mine);
+      let now = null;
+      try {
+        now = JSON.parse(fs.readFileSync(path.join(theirs, 'package.json'), 'utf8')).version;
+      } catch (err) {
+        now = null;
+      }
+      // Believed only when the folder now holds exactly this version.
+      if (!result.error && result.status === 0 && now === mine && project.kryptheonCopyFor(USER_DIR) === theirs) {
+        console.log('  Updated.');
+        theirVersion = now;
+      } else {
+        console.log('  Could not update it just now (no internet?), so the ' + (now || theirVersion) + ' that is here runs.');
+        if (now) theirVersion = now;
+      }
+    }
+  }
+
+  // A copy from before the store looks for its records inside the project. If
+  // they have already moved out, it finds none, takes every recording as new,
+  // and learns whatever the app does today as correct - a broken page would
+  // pass. So it is not run; the one fix is to bring it up to date.
+  if (project.olderVersion(theirVersion, FIRST_STORE_VERSION)) {
+    const kept = store.pathsFor(USER_DIR);
+    if (fs.existsSync(kept.baselines) || fs.existsSync(kept.history)) {
+      console.error('');
+      console.error('  This folder has kryptheon ' + theirVersion + ', which looks for its saved results');
+      console.error('  inside the project. They have moved out, to');
+      console.error('    ' + kept.dir);
+      console.error('  so ' + theirVersion + ' would see none, treat every recording as new, and could');
+      console.error('  miss a real change. Nothing was checked. Update this folder\'s copy:');
+      console.error('    npm i -D kryptheon@latest');
+      console.error('  then run this again.');
+      console.error('');
+      return 1;
+    }
+  }
+
   if (theirVersion !== mine) {
     // Not an error: the folder's copy is the one its recordings are written
     // against. Said, so an older one is never mistaken for this one.

package/kryptheon-fixture.js

@@ -26,10 +26,13 @@ const heal = require('./kryptheon-heal.js');
 
 const MAX_ITEMS = 5; // keep the failure block readable
 
-// Baselines describe the user's app, so they live in the folder the command
-// was run from - never inside the installed package.
+const store = require('./kryptheon-store.js');
+
+// Baselines describe the user's app, so they belong to the folder the command
+// was run from - but they are kept in that folder's store, outside it, so the
+// project's repo never grows because Kryptheon is watching it.
 const USER_DIR = process.cwd();
-const BASELINE_FILE = path.join(USER_DIR, 'kryptheon-baselines.json');
+const BASELINE_FILE = store.pathsFor(USER_DIR).baselines;
 
 function oneLine(text) {
   return String(text).replace(/\s+/g, ' ').trim();
@@ -78,6 +81,7 @@ function saveBaselines(file, all) {
   try {
     // 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.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n', { encoding: 'utf8' });
     return true;
   } catch (e) {

package/kryptheon-project.js

@@ -526,8 +526,29 @@ function installFailedLines() {
   ];
 }
 
+/**
+ * Whether version `a` is older than `b`, by their numbers. Anything that is
+ * not plain x.y.z is never called older: updating on a guess would change
+ * somebody's package.json for nothing, and only digits and dots ever reach
+ * the npm command line built from the answer.
+ */
+function olderVersion(a, b) {
+  const parse = (v) => {
+    const m = String(v == null ? '' : v).match(/^(\d+)\.(\d+)\.(\d+)$/);
+    return m ? m.slice(1).map(Number) : null;
+  };
+  const x = parse(a);
+  const y = parse(b);
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] < y[i];
+  }
+  return false;
+}
+
 module.exports = {
   ESCAPE_HATCH: ESCAPE_HATCH,
+  olderVersion: olderVersion,
   HOME_RECORDINGS: HOME_RECORDINGS,
   kryptheonReachableFrom: kryptheonReachableFrom,
   kryptheonCopyFor: kryptheonCopyFor,

package/kryptheon-reporter.js

@@ -1,20 +1,29 @@
 // Plain-language Playwright reporter for non-technical readers.
 // Prints a short line per passing test and a readable block per failure,
-// and appends one JSON line per run to kryptheon-history.jsonl.
+// and appends one JSON line per run to the project's history.jsonl.
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const recordings = require('./kryptheon-recordings.js');
 const heal = require('./kryptheon-heal.js');
+const store = require('./kryptheon-store.js');
 
 // An assistant runs this after every change, so it needs a mode that says
 // nothing at all when the news is good.
 const QUIET = !!process.env.KRYPTHEON_QUIET;
 
-// The history belongs to whoever is running the tests, so it lives in their
-// folder - not inside the installed package.
+// The history belongs to whoever is running the tests, so it is kept in their
+// project's store - not inside the installed package, and not in the project.
 const USER_DIR = process.cwd();
-const HISTORY_FILE = path.join(USER_DIR, 'kryptheon-history.jsonl');
+const HISTORY_FILE = store.pathsFor(USER_DIR).history;
+
+// Said with ~ for the home folder: the full path is long, and the person only
+// needs to know it is outside their project and where to look.
+function shortHome(file) {
+  const home = os.homedir();
+  return file.toLowerCase().startsWith(home.toLowerCase() + path.sep) ? '~' + file.slice(home.length) : file;
+}
 
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sept', 'Oct', 'Nov', 'Dec'];
 
@@ -962,10 +971,13 @@ class KryptheonReporter {
     };
 
     // Append only - existing lines are never rewritten.
+    let saved = false;
     try {
+      fs.mkdirSync(path.dirname(HISTORY_FILE), { recursive: true });
       fs.appendFileSync(HISTORY_FILE, JSON.stringify(entry) + '\n', 'utf8');
+      saved = true;
     } catch (err) {
-      process.stdout.write('\n(could not write ' + path.basename(HISTORY_FILE) + ': ' + err.message + ')\n');
+      process.stdout.write('\n(could not write ' + shortHome(HISTORY_FILE) + ': ' + err.message + ')\n');
     }
 
     // "Broken" is kept for recordings that used to work. The ones that never
@@ -1011,7 +1023,7 @@ class KryptheonReporter {
 
     process.stdout.write(
       '\n' + recordings.summaryLines(counts).join('\n') + '\n' +
-      'History saved to ' + path.basename(HISTORY_FILE) + '\n\n'
+      (saved ? 'History saved outside your project, in ' + shortHome(HISTORY_FILE) + '\n' : '') + '\n'
     );
 
     // Once per run, not once per test: it is one fact about the app, and

package/kryptheon-secrets.js

@@ -139,9 +139,11 @@ function writeEnvExample(dir, names) {
   }
 }
 
-// Everything kryptheon leaves in a project that should not be committed: the
-// real password, and three files that are machine state rather than source.
-const GITIGNORE_ENTRIES = ['.env', 'kryptheon-baselines.json', 'kryptheon-history.jsonl', 'test-results/'];
+// What must never be committed from a project: the real password. The three
+// files of machine state that used to be listed here - baselines, history and
+// test-results/ - are no longer written into the project at all; they live in
+// its store (kryptheon-store.js), so there is nothing of Kryptheon's to ignore.
+const GITIGNORE_ENTRIES = ['.env'];
 
 /**
  * Adds the missing entries to an existing .gitignore. Returns what it added.

package/kryptheon-store.js

@@ -0,0 +1,317 @@
+// Where Kryptheon keeps what it remembers about a project.
+//
+// It used to be the project itself: kryptheon-baselines.json,
+// kryptheon-history.jsonl, test-results/ and .kryptheon-last.json all appeared
+// next to the person's own code. A plain landing page picked up six or seven
+// files that way, and an AI assistant that commits "everything that changed"
+// commits them too - the repo grows because Kryptheon is watching it.
+//
+// So every record now lives in one folder per project, outside it:
+//
+//   ~/.kryptheon/projects/<folder-name>-<hash>/     (KRYPTHEON_HOME moves ~/.kryptheon)
+//     project.json    which folder this store belongs to
+//     baselines.json  was kryptheon-baselines.json
+//     history.jsonl   was kryptheon-history.jsonl
+//     test-results/   was test-results/ (Playwright's screenshots of a failure)
+//     night-last.json was .kryptheon-last.json (kryptheon-night)
+//
+// Only tests/ - the recordings the person made - stays in the project.
+//
+// The hash is of the project's full path, so two folders that happen to share
+// a name are never mixed. kryptheon-night carries a copy of this file and must
+// land in the same folder for the same project; both packages check the ids
+// below against the same fixed examples, so the two copies cannot drift apart.
+//
+// Records an older version left in a project are moved here the first time a
+// project is opened, and only moved: nothing is thrown away, and when both
+// places already hold a file the project's copy is kept in parked/ rather than
+// overwriting what is here.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const HOME_ENV = 'KRYPTHEON_HOME';
+
+const FILES = {
+  project: 'project.json',
+  baselines: 'baselines.json',
+  history: 'history.jsonl',
+  testResults: 'test-results',
+  nightLast: 'night-last.json',
+};
+
+// What older versions wrote into the project, and where each one goes now.
+//   append - history: lines the store does not have yet are added to it
+//   park   - both exist: the project's copy goes to parked/, the store's stays
+const LEGACY = [
+  { from: 'kryptheon-baselines.json', to: FILES.baselines, onBoth: 'park' },
+  { from: 'kryptheon-history.jsonl', to: FILES.history, onBoth: 'append' },
+  { from: '.kryptheon-last.json', to: FILES.nightLast, onBoth: 'park' },
+  { from: 'test-results', to: FILES.testResults, onBoth: 'park', dir: true },
+];
+
+// A project with a Playwright config of its own owns its test-results/ -
+// Playwright's default output folder. Moving that would take the person's own
+// screenshots away, so it is left exactly where it is.
+const OWN_PLAYWRIGHT = /^playwright\.config\.(js|cjs|mjs|ts|cts|mts)$/;
+
+/** ~/.kryptheon, or wherever KRYPTHEON_HOME points. */
+function home(env) {
+  const source = env || process.env;
+  const set = source[HOME_ENV];
+  if (set && String(set).trim()) return path.resolve(String(set).trim());
+  return path.join(os.homedir(), '.kryptheon');
+}
+
+/** The project folder as one exact path, whatever form it was given in. */
+function canonicalRoot(dir) {
+  const resolved = path.resolve(dir || process.cwd());
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch (err) {
+    return resolved;
+  }
+}
+
+/**
+ * <folder-name>-<12 hex>. Pure: the same path always gives the same id.
+ *
+ * Windows paths are compared without regard to case, because C:\Users\a and
+ * c:\users\a are the same folder there and must be the same project.
+ */
+function projectId(root, platform) {
+  const plat = platform || process.platform;
+  const P = plat === 'win32' ? path.win32 : path.posix;
+  // resolve() also drops a trailing separator and turns / into \ on Windows.
+  let key = P.resolve(String(root));
+  if (plat === 'win32') key = key.toLowerCase();
+  const hash = crypto.createHash('sha256').update(key, 'utf8').digest('hex').slice(0, 12);
+  const base = P.basename(key) || 'project';
+  const name = base.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|-+$/g, '').slice(0, 40) || 'project';
+  return name + '-' + hash;
+}
+
+/**
+ * The store folder for a project. Only reads: nothing is created or moved, so
+ * the fixture and the reporter can ask for it just by being loaded.
+ */
+function dirFor(dir, env) {
+  const root = canonicalRoot(dir);
+  const short = path.join(home(env), 'projects', projectId(root));
+  const owner = readProject(path.join(short, FILES.project));
+  if (!owner || !owner.root || sameRoot(owner.root, root)) return short;
+  // Two different folders with the same short hash. Astronomically rare, but
+  // the one thing a store must never do is hold two projects, so the second
+  // one gets the full hash instead.
+  const full = crypto.createHash('sha256').update(root, 'utf8').digest('hex');
+  return short.replace(/-[0-9a-f]{12}$/, '-' + full);
+}
+
+/** Every file in a project's store, by name. Only reads, like dirFor. */
+function pathsFor(dir, env) {
+  return pathsIn(dirFor(dir, env));
+}
+
+function pathsIn(dir) {
+  return {
+    dir: dir,
+    project: path.join(dir, FILES.project),
+    baselines: path.join(dir, FILES.baselines),
+    history: path.join(dir, FILES.history),
+    testResults: path.join(dir, FILES.testResults),
+    nightLast: path.join(dir, FILES.nightLast),
+  };
+}
+
+function exists(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function hasOwnPlaywright(root) {
+  try {
+    return fs.readdirSync(root).some((name) => OWN_PLAYWRIGHT.test(name));
+  } catch (err) {
+    return false;
+  }
+}
+
+// rename is the whole move when both sides are on one drive. Across drives it
+// fails with EXDEV, and then it is copy, check the copy, and only then remove.
+function move(from, to, isDir) {
+  try {
+    fs.renameSync(from, to);
+    return;
+  } catch (err) {
+    // Anything else - a file held open by an editor, say - is reported and the
+    // record stays where it is, whole.
+    if (err.code !== 'EXDEV') throw err;
+  }
+  if (isDir) {
+    fs.cpSync(from, to, { recursive: true, errorOnExist: true, force: false });
+    fs.rmSync(from, { recursive: true, force: true });
+    return;
+  }
+  const tmp = to + '.moving';
+  fs.copyFileSync(from, tmp);
+  if (fs.statSync(tmp).size !== fs.statSync(from).size) {
+    fs.rmSync(tmp, { force: true });
+    throw new Error('the copy of ' + from + ' came out a different size');
+  }
+  fs.renameSync(tmp, to);
+  fs.rmSync(from, { force: true });
+}
+
+// Lines of the project's history the store does not have yet, in their order.
+// Checked line by line so moving twice - say the project file could not be
+// removed the first time - never writes a run down twice.
+function appendHistory(from, to) {
+  const have = new Set(fs.readFileSync(to, 'utf8').split('\n').filter((l) => l.trim()));
+  const extra = fs.readFileSync(from, 'utf8').split('\n').filter((l) => l.trim() && !have.has(l));
+  if (extra.length) {
+    const current = fs.readFileSync(to, 'utf8');
+    const lead = current.length && !current.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(to, lead + extra.join('\n') + '\n', 'utf8');
+  }
+  fs.rmSync(from, { force: true });
+  return extra.length;
+}
+
+function stamp(now) {
+  return (now || new Date()).toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * Moves what an older version left in the project into the store.
+ * Returns { moved: [names], parked: [{ name, to }], appended: [{ name, lines }],
+ * kept: [{ name, why }], failed: [{ name, why }] }.
+ */
+function migrate(root, dir, options) {
+  const out = { moved: [], parked: [], appended: [], kept: [], failed: [] };
+  const ownPlaywright = hasOwnPlaywright(root);
+  for (const item of LEGACY) {
+    const from = path.join(root, item.from);
+    if (!exists(from)) continue;
+    const label = item.from + (item.dir ? '/' : '');
+    if (item.dir && ownPlaywright) {
+      out.kept.push({ name: label, why: 'this project has its own Playwright config, so it is theirs' });
+      continue;
+    }
+    const to = path.join(dir, item.to);
+    try {
+      if (!exists(to)) {
+        move(from, to, item.dir);
+        out.moved.push(label);
+      } else if (item.onBoth === 'append') {
+        out.appended.push({ name: label, lines: appendHistory(from, to) });
+      } else {
+        const parkedDir = path.join(dir, 'parked');
+        fs.mkdirSync(parkedDir, { recursive: true });
+        const parked = path.join(parkedDir, stamp(options && options.now) + '-' + item.from.replace(/^\./, ''));
+        move(from, parked, item.dir);
+        out.parked.push({ name: label, to: parked });
+      }
+    } catch (err) {
+      out.failed.push({ name: label, why: err.message });
+    }
+  }
+  return out;
+}
+
+/**
+ * The store for the project in `dir` (default: the current folder), created if
+ * it is not there yet, with anything an older version left in the project moved
+ * into it. Safe to call again: once moved, there is nothing left to move.
+ *
+ * Throws when the store cannot be created. A record that silently cannot be
+ * written makes every run look like the first one - which reads as "nothing to
+ * compare against, all fine" - so that is never swallowed here.
+ */
+function open(dir, options) {
+  const env = (options && options.env) || process.env;
+  const root = canonicalRoot(dir);
+  const storeDir = dirFor(root, env);
+  fs.mkdirSync(storeDir, { recursive: true });
+  const paths = pathsIn(storeDir);
+  if (!exists(paths.project)) {
+    fs.writeFileSync(paths.project, JSON.stringify({
+      root: root,
+      name: path.basename(root),
+      id: path.basename(storeDir),
+      createdAt: new Date().toISOString(),
+    }, null, 2) + '\n', 'utf8');
+  }
+  return Object.assign({ root: root, id: path.basename(storeDir) }, paths, {
+    migration: migrate(root, storeDir, options),
+  });
+}
+
+function sameRoot(a, b, platform) {
+  const plat = platform || process.platform;
+  const norm = (p) => {
+    const r = path.resolve(String(p)).replace(/[\\/]+$/, '');
+    return plat === 'win32' ? r.split('/').join('\\').toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+
+function readProject(file) {
+  try {
+    let raw = fs.readFileSync(file, 'utf8');
+    if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/** What to tell the person about a migration, or nothing when nothing moved. */
+function migrationLines(store) {
+  const m = store && store.migration;
+  if (!m) return [];
+  const lines = [];
+  const movedNames = m.moved.concat(m.appended.map((a) => a.name)).concat(m.parked.map((p) => p.name));
+  if (movedNames.length) {
+    lines.push('  Kryptheon now keeps its records outside your project, so they can never');
+    lines.push('  end up in your repo. Moved out of this folder:');
+    for (const name of movedNames) lines.push('    ' + name);
+    lines.push('  They are now in:');
+    lines.push('    ' + store.dir);
+    for (const p of m.parked) {
+      lines.push('  ' + p.name + ' was already there too, so this folder\'s copy is kept aside in:');
+      lines.push('    ' + p.to);
+    }
+    lines.push('');
+  }
+  for (const k of m.kept) {
+    lines.push('  Left ' + k.name + ' where it is: ' + k.why + '.');
+    lines.push('');
+  }
+  for (const f of m.failed) {
+    lines.push('  Could not move ' + f.name + ' out of this folder: ' + f.why);
+    lines.push('  It is still here. Close anything that has it open and run this again.');
+    lines.push('');
+  }
+  return lines;
+}
+
+module.exports = {
+  HOME_ENV: HOME_ENV,
+  FILES: FILES,
+  LEGACY: LEGACY,
+  home: home,
+  canonicalRoot: canonicalRoot,
+  projectId: projectId,
+  dirFor: dirFor,
+  pathsFor: pathsFor,
+  open: open,
+  migrate: migrate,
+  migrationLines: migrationLines,
+};

package/package.json

@@ -1,78 +1,80 @@
-{
-  "name": "kryptheon",
-  "version": "0.1.18",
-  "description": "Record what you do in your app and get plain-language reports when it breaks.",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "kryptheon": "bin/kryptheon.js"
-  },
-  "exports": {
-    ".": "./kryptheon-fixture.js",
-    "./kryptheon-fixture": "./kryptheon-fixture.js",
-    "./kryptheon-reporter": "./kryptheon-reporter.js",
-    "./package.json": "./package.json",
-    "./kryptheon-replay": "./kryptheon-replay.js",
-    "./kryptheon-signature": "./kryptheon-signature.js",
-    "./kryptheon-secrets": "./kryptheon-secrets.js"
-  },
-  "files": [
-    "bin/",
-    "kryptheon-fixture.js",
-    "kryptheon-reporter.js",
-    "kryptheon-signature.js",
-    "kryptheon-secrets.js",
-    "playwright.config.js",
-    "README.md",
-    "kryptheon-replay.js",
-    "kryptheon-heal.js",
-    "kryptheon-selectors.js",
-    "kryptheon-recordings.js",
-    "kryptheon-cleanup.js",
-    "kryptheon-baselines.js",
-    "kryptheon-project.js"
-  ],
-  "engines": {
-    "node": ">=20.6.0"
-  },
-  "dependencies": {
-    "@playwright/test": "^1.62.1"
-  },
-  "scripts": {
-    "check": "node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
-    "check:reporter": "node kryptheon-reporter.check.js",
-    "check:signature": "node kryptheon-signature.check.js",
-    "check:stream": "node kryptheon-signature.stream.check.js",
-    "check:baseline": "node kryptheon-signature.baseline.check.js",
-    "check:settle": "node kryptheon-signature.settle.check.js",
-    "check:number": "node kryptheon-signature.number.check.js",
-    "check:env": "node kryptheon-env.check.js",
-    "check:watchdog": "node kryptheon-watchdog.check.js",
-    "check:record": "node kryptheon-record.check.js",
-    "check:selectors": "node kryptheon-selectors.check.js",
-    "check:recordings": "node kryptheon-recordings.check.js",
-    "check:cleanup": "node kryptheon-cleanup.check.js",
-    "check:orphan": "node kryptheon-orphan.check.js",
-    "check:project": "node kryptheon-project.check.js",
-    "check:setup": "node kryptheon-setup.check.js",
-    "check:browser": "node kryptheon-browser.check.js",
-    "check:heal": "node kryptheon-heal.check.js",
-    "check:load": "node kryptheon-load.check.js",
-    "check:package": "node kryptheon-package.check.js",
-    "prepublishOnly": "node kryptheon-package.check.js"
-  },
-  "keywords": [
-    "playwright",
-    "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"
-}
+{
+  "name": "kryptheon",
+  "version": "0.1.20",
+  "description": "Record what you do in your app and get plain-language reports when it breaks.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "kryptheon": "bin/kryptheon.js"
+  },
+  "exports": {
+    ".": "./kryptheon-fixture.js",
+    "./kryptheon-fixture": "./kryptheon-fixture.js",
+    "./kryptheon-reporter": "./kryptheon-reporter.js",
+    "./package.json": "./package.json",
+    "./kryptheon-replay": "./kryptheon-replay.js",
+    "./kryptheon-signature": "./kryptheon-signature.js",
+    "./kryptheon-secrets": "./kryptheon-secrets.js"
+  },
+  "files": [
+    "bin/",
+    "kryptheon-fixture.js",
+    "kryptheon-reporter.js",
+    "kryptheon-signature.js",
+    "kryptheon-secrets.js",
+    "playwright.config.js",
+    "README.md",
+    "kryptheon-replay.js",
+    "kryptheon-heal.js",
+    "kryptheon-selectors.js",
+    "kryptheon-recordings.js",
+    "kryptheon-cleanup.js",
+    "kryptheon-baselines.js",
+    "kryptheon-project.js",
+    "kryptheon-store.js"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.62.1"
+  },
+  "scripts": {
+    "check": "node kryptheon-store.check.js && node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
+    "check:store": "node kryptheon-store.check.js",
+    "check:reporter": "node kryptheon-reporter.check.js",
+    "check:signature": "node kryptheon-signature.check.js",
+    "check:stream": "node kryptheon-signature.stream.check.js",
+    "check:baseline": "node kryptheon-signature.baseline.check.js",
+    "check:settle": "node kryptheon-signature.settle.check.js",
+    "check:number": "node kryptheon-signature.number.check.js",
+    "check:env": "node kryptheon-env.check.js",
+    "check:watchdog": "node kryptheon-watchdog.check.js",
+    "check:record": "node kryptheon-record.check.js",
+    "check:selectors": "node kryptheon-selectors.check.js",
+    "check:recordings": "node kryptheon-recordings.check.js",
+    "check:cleanup": "node kryptheon-cleanup.check.js",
+    "check:orphan": "node kryptheon-orphan.check.js",
+    "check:project": "node kryptheon-project.check.js",
+    "check:setup": "node kryptheon-setup.check.js",
+    "check:browser": "node kryptheon-browser.check.js",
+    "check:heal": "node kryptheon-heal.check.js",
+    "check:load": "node kryptheon-load.check.js",
+    "check:package": "node kryptheon-package.check.js",
+    "prepublishOnly": "node kryptheon-package.check.js"
+  },
+  "keywords": [
+    "playwright",
+    "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"
+}

package/playwright.config.js

@@ -42,8 +42,11 @@ module.exports = defineConfig({
   // The tests belong to the user, so they are found in their folder.
   testDir: path.join(USER_DIR, 'tests'),
   // Screenshots and other artefacts default to sitting next to the config,
-  // which once installed means inside node_modules. Keep them with the user.
-  outputDir: path.join(USER_DIR, 'test-results'),
+  // which once installed means inside node_modules. They belong to the user's
+  // project, so they go to its store - outside the project, where a commit of
+  // "everything that changed" cannot pick them up. Playwright empties this
+  // folder at the start of every run, so it never grows.
+  outputDir: require(path.join(PACKAGE_DIR, 'kryptheon-store.js')).pathsFor(USER_DIR).testResults,
   // These tests all run against one live site, so in parallel they interfere
   // with each other - a shared logged-in session, and rate limiting on the
   // real endpoints. Serial is the safe default here.