kryptheon 0.1.39 → 0.1.41

package/LICENSE

@@ -5,7 +5,7 @@ Copyright (c) 2026 Kryptheon (https://kryptheon.tech). All rights reserved.
 This software is proprietary. It is not open source.
 
 1. Use. You may install and run this software, as published by Kryptheon,
-   free of charge, to check software and databases that you own or are
+   at no charge, to check software and databases that you own or are
    authorised to test. Features that kryptheon.tech offers on a paid plan
    are provided only under that plan and the Terms at
    https://kryptheon.tech/terms.

package/README.md

@@ -1,261 +1,261 @@
-# kryptheon
-
-Record a flow in your app once, replay it after every AI change, and get told in
-plain English what broke.
-
-Runs entirely on your machine. No account, no API key, nothing leaves your
-computer. It is a wrapper around [Playwright](https://playwright.dev).
-
-## The one command
-
-```
-npx kryptheon@latest dashboard
-```
-
-Run it in your project's folder. It opens a page in your browser, and
-everything else is a button on that page:
-
-| | how often |
-| --- | --- |
-| Read my code | after every change |
-| Record a flow | one time - again only when that flow changes |
-| Replay | after every change |
-| Connect your database | one time |
-| Check my database | after every change |
-| Set up the nightly check | one time |
-| Re-check a finding | after every change |
-
-Every button shows the terminal command that does the same thing, in small
-print, for when the page cannot be used. The database connection string is
-pasted into the page, used for one run, and never saved, logged or shown
-again; reload the page and it is gone.
-
-## Only have a web address?
-
-Built your app in Lovable, Bolt or v0, and there is no project folder on your
-computer? Open a terminal and run:
-
-```
-npx kryptheon record https://your-app.lovable.app
-```
-
-Before it opens anything, it looks at the folder you are in. If that folder is
-not set up for recordings it says so and asks first, then adds a `package.json`
-and kryptheon itself (about 20MB) — nothing else. A new terminal opens in your
-home folder, so from there it keeps your recordings in a `kryptheon-tests`
-folder of their own and tells you where that is.
-
-After every change to your app, from that same folder:
-
-```
-npx kryptheon check
-```
-
-## Install
-
-```
-npm i -D kryptheon
-```
-
-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`.
-
-## Record
-
-```
-npx kryptheon record https://your-app.example.com
-```
-
-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.
-
-Add `--phone` to record in a phone-sized window (390 x 844) - for a menu or a
-layout that only changes on a phone. The recording keeps that size, so every
-replay uses it too. On the dashboard it is the "Phone size" box under Record.
-
-On its own, a recording knows that every button and field is still there and
-that the last page looks the same. To say what must be true — "Reservation
-received" appears after booking — use the toolbar at the top of the page while
-recording:
-
-| Button | Click it, then click… | Kryptheon then checks |
-| --- | --- | --- |
-| Eye | any element | it is on the page |
-| `ab` | some text | that text is there |
-| Box | a filled-in field | the field still holds that value |
-| `{ }` | a part of the page | that part is laid out the same |
-
-The round red button pauses and resumes recording. The arrow only shows how an
-element would be found; it adds nothing to the test. One check at the end of a
-flow — on the success message — is usually all a recording needs.
-
-## Check
-
-```
-npx kryptheon check
-```
-
-Runs everything you have recorded:
-
-```
-OK  Sign in  (4.1s)
-
-X  Checkout
-   Could not find the button "Place order" on the page.
-   This was working on 12 Mar at 9:14 AM.
-   What to check: your last change may have renamed, hidden, or removed it.
-   Where to look:
-     - Browser was on: https://your-app.example.com/cart
-     - POST /api/orders returned 500
-       the server crashed or is unavailable - the error is in backend code, not the page
-```
-
-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.
-
-## Make your AI assistant check its own work
-
-An assistant will happily call a change done after only reading the code. This
-writes a rule into the files assistants already read, so it has to run the check
-first:
-
-```
-npx kryptheon setup-ai
-```
-
-It writes `CLAUDE.md`, `AGENTS.md` and `.cursorrules`. If a file already exists,
-it adds a marked section at the end rather than overwriting anything, and
-running it again replaces that section instead of adding a second copy.
-
-The rule: after any change, run `npx kryptheon check`, show the output, and do
-not report the work as done until it passes.
-
-For an assistant running the check after every change, `--quiet` keeps the
-conversation readable — one line when everything passes, the full explanation
-only when something breaks:
-
-```
-npx kryptheon check --quiet
-```
-
-```
-OK  3 recordings still working.
-```
-
-## 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 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:
-
-```
-npx kryptheon accept "Checkout"
-```
-
-`npx kryptheon accept` on its own lists what has been saved.
-
-## Renamed buttons
-
-A button that only changed its words has not broken anything. When a step
-cannot find "Reserve a table" and the page shows exactly one new button in its
-place — "Reserve here" — kryptheon clicks that one, carries on through the rest
-of the flow, and says so:
-
-```
-OK  Reserve a table  (16.0s)
-    Renamed: The button "Reserve a table" is now called "Reserve here" - I used "Reserve here" and carried on.
-    Nothing is broken. To stop seeing this, record the flow again.
-```
-
-It only does this when the page proves it: one name gone, the one the step
-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.
-
-## Dashboard
-
-```
-npx kryptheon
-```
-
-In a terminal, with no command, this opens a page on your own machine
-(`http://127.0.0.1:4789/`) for this project, in your browser by itself (the
-address is printed too): what is broken, what needs a look, every run, recent
-changes, and switches for each check. Every check runs from a button, one at a
-time, with its progress shown on the page as it goes. It is only reachable
-from this machine; press Ctrl+C to stop it. From a script, use
-`npx kryptheon dashboard`; set `KRYPTHEON_NO_OPEN=1` to keep the browser shut.
-
-It opens on the one thing to do next, and under it "Start here": read your
-code, record your main flows, replay them, connect and check your database,
-and set up the nightly check - each marked done only once it has actually run,
-and each labelled "one time" or "after every change".
-
-Checks that are not built yet are listed as "not available" - never as
-passed.
-
-## Reading your code
-
-```
-npx kryptheon code
-```
-
-Reads your frontend code for values put into the page as HTML - `innerHTML`,
-`insertAdjacentHTML`, `document.write`, React's `dangerouslySetInnerHTML`,
-Vue's `v-html`. If such a value can hold text someone typed, a `<` in it can
-run script with the signed-in person's session. Nothing is run; every result
-is "verification required", ranked HIGH when the value comes from a server
-response or an error message, MEDIUM when the code alone cannot say. The fix
-prompt for each one names the file, line and value.
-
-## What goes where
-
-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. When there is a password, `.env` is added to an existing `.gitignore`.
-
-## Requirements
-
-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
-
-Free to use, not open source: see LICENSE. Paid features are on kryptheon.tech.
+# kryptheon
+
+Record a flow in your app once, replay it after every AI change, and get told in
+plain English what broke.
+
+Runs entirely on your machine. No account, no API key, nothing leaves your
+computer. It is a wrapper around [Playwright](https://playwright.dev).
+
+## The one command
+
+```
+npx kryptheon@latest dashboard
+```
+
+Run it in your project's folder. It opens a page in your browser, and
+everything else is a button on that page:
+
+| | how often |
+| --- | --- |
+| Read my code | after every change |
+| Record a flow | one time - again only when that flow changes |
+| Replay | after every change |
+| Connect your database | one time |
+| Check my database | after every change |
+| Set up the nightly check | one time |
+| Re-check a finding | after every change |
+
+Every button shows the terminal command that does the same thing, in small
+print, for when the page cannot be used. The database connection string is
+pasted into the page, used for one run, and never saved, logged or shown
+again; reload the page and it is gone.
+
+## Only have a web address?
+
+Built your app in Lovable, Bolt or v0, and there is no project folder on your
+computer? Open a terminal and run:
+
+```
+npx kryptheon record https://your-app.lovable.app
+```
+
+Before it opens anything, it looks at the folder you are in. If that folder is
+not set up for recordings it says so and asks first, then adds a `package.json`
+and kryptheon itself (about 20MB) — nothing else. A new terminal opens in your
+home folder, so from there it keeps your recordings in a `kryptheon-tests`
+folder of their own and tells you where that is.
+
+After every change to your app, from that same folder:
+
+```
+npx kryptheon check
+```
+
+## Install
+
+```
+npm i -D kryptheon
+```
+
+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`.
+
+## Record
+
+```
+npx kryptheon record https://your-app.example.com
+```
+
+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.
+
+Add `--phone` to record in a phone-sized window (390 x 844) - for a menu or a
+layout that only changes on a phone. The recording keeps that size, so every
+replay uses it too. On the dashboard it is the "Phone size" box under Record.
+
+On its own, a recording knows that every button and field is still there and
+that the last page looks the same. To say what must be true — "Reservation
+received" appears after booking — use the toolbar at the top of the page while
+recording:
+
+| Button | Click it, then click… | Kryptheon then checks |
+| --- | --- | --- |
+| Eye | any element | it is on the page |
+| `ab` | some text | that text is there |
+| Box | a filled-in field | the field still holds that value |
+| `{ }` | a part of the page | that part is laid out the same |
+
+The round red button pauses and resumes recording. The arrow only shows how an
+element would be found; it adds nothing to the test. One check at the end of a
+flow — on the success message — is usually all a recording needs.
+
+## Check
+
+```
+npx kryptheon check
+```
+
+Runs everything you have recorded:
+
+```
+OK  Sign in  (4.1s)
+
+X  Checkout
+   Could not find the button "Place order" on the page.
+   This was working on 12 Mar at 9:14 AM.
+   What to check: your last change may have renamed, hidden, or removed it.
+   Where to look:
+     - Browser was on: https://your-app.example.com/cart
+     - POST /api/orders returned 500
+       the server crashed or is unavailable - the error is in backend code, not the page
+```
+
+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.
+
+## Make your AI assistant check its own work
+
+An assistant will happily call a change done after only reading the code. This
+writes a rule into the files assistants already read, so it has to run the check
+first:
+
+```
+npx kryptheon setup-ai
+```
+
+It writes `CLAUDE.md`, `AGENTS.md` and `.cursorrules`. If a file already exists,
+it adds a marked section at the end rather than overwriting anything, and
+running it again replaces that section instead of adding a second copy.
+
+The rule: after any change, run `npx kryptheon check`, show the output, and do
+not report the work as done until it passes.
+
+For an assistant running the check after every change, `--quiet` keeps the
+conversation readable — one line when everything passes, the full explanation
+only when something breaks:
+
+```
+npx kryptheon check --quiet
+```
+
+```
+OK  3 recordings still working.
+```
+
+## 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 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:
+
+```
+npx kryptheon accept "Checkout"
+```
+
+`npx kryptheon accept` on its own lists what has been saved.
+
+## Renamed buttons
+
+A button that only changed its words has not broken anything. When a step
+cannot find "Reserve a table" and the page shows exactly one new button in its
+place — "Reserve here" — kryptheon clicks that one, carries on through the rest
+of the flow, and says so:
+
+```
+OK  Reserve a table  (16.0s)
+    Renamed: The button "Reserve a table" is now called "Reserve here" - I used "Reserve here" and carried on.
+    Nothing is broken. To stop seeing this, record the flow again.
+```
+
+It only does this when the page proves it: one name gone, the one the step
+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.
+
+## Dashboard
+
+```
+npx kryptheon
+```
+
+In a terminal, with no command, this opens a page on your own machine
+(`http://127.0.0.1:4789/`) for this project, in your browser by itself (the
+address is printed too): what is broken, what needs a look, every run, recent
+changes, and switches for each check. Every check runs from a button, one at a
+time, with its progress shown on the page as it goes. It is only reachable
+from this machine; press Ctrl+C to stop it. From a script, use
+`npx kryptheon dashboard`; set `KRYPTHEON_NO_OPEN=1` to keep the browser shut.
+
+It opens on the one thing to do next, and under it "Start here": read your
+code, record your main flows, replay them, connect and check your database,
+and set up the nightly check - each marked done only once it has actually run,
+and each labelled "one time" or "after every change".
+
+Checks that are not built yet are listed as "not available" - never as
+passed.
+
+## Reading your code
+
+```
+npx kryptheon code
+```
+
+Reads your frontend code for values put into the page as HTML - `innerHTML`,
+`insertAdjacentHTML`, `document.write`, React's `dangerouslySetInnerHTML`,
+Vue's `v-html`. If such a value can hold text someone typed, a `<` in it can
+run script with the signed-in person's session. Nothing is run; every result
+is "verification required", ranked HIGH when the value comes from a server
+response or an error message, MEDIUM when the code alone cannot say. The fix
+prompt for each one names the file, line and value.
+
+## What goes where
+
+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. When there is a password, `.env` is added to an existing `.gitignore`.
+
+## Requirements
+
+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
+
+Proprietary software, not open source - see LICENSE. It runs on your own machine, with no account and no card. The nightly check, with its morning report, alerts and history, is part of the Pro and Studio plans on kryptheon.tech.

package/bin/kryptheon.js

@@ -2632,9 +2632,12 @@ function dashboardAlreadyRunning(port) {
       res.on('data', (chunk) => { if (body.length < 5000000) body += chunk; });
       res.on('end', () => {
         try {
-          const root = JSON.parse(body).project.root;
+          const state = JSON.parse(body);
+          const root = state.project.root;
           const same = (a) => (process.platform === 'win32' ? path.resolve(a).toLowerCase() : path.resolve(a));
-          resolve(res.statusCode === 200 && typeof root === 'string' && same(root) === same(USER_DIR));
+          if (res.statusCode !== 200 || typeof root !== 'string' || same(root) !== same(USER_DIR)) return resolve(false);
+          // Before 0.1.41 a dashboard did not say which it was: an old one.
+          resolve({ version: typeof state.kryptheon === 'string' ? state.kryptheon : null });
         } catch (err) {
           resolve(false);
         }
@@ -2645,6 +2648,49 @@ function dashboardAlreadyRunning(port) {
   });
 }
 
+/** The process listening on 127.0.0.1:port, or null. */
+function listenerOn(port) {
+  try {
+    if (process.platform === 'win32') {
+      const out = spawnSync('netstat', ['-ano', '-p', 'TCP'], { encoding: 'utf8', windowsHide: true, timeout: 10000 }).stdout || '';
+      for (const line of out.split(/\r?\n/)) {
+        const m = line.trim().split(/\s+/);
+        if (m.length >= 5 && m[1] === '127.0.0.1:' + port && m[3] === 'LISTENING' && /^\d+$/.test(m[4])) return Number(m[4]);
+      }
+      return null;
+    }
+    const out = spawnSync('lsof', ['-nP', '-iTCP@127.0.0.1:' + port, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', timeout: 10000 }).stdout || '';
+    const pid = Number(out.trim().split(/\s+/)[0]);
+    return pid > 0 ? pid : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * An older dashboard for this same folder, still running - from yesterday's
+ * Win+R, or started at sign-in - is stopped so this version takes its place.
+ * Found when the first paying user ran the new version and kept getting the
+ * old page: npx fetched the new one, which then only opened the old one.
+ * Only the process that answered as this folder's Kryptheon dashboard is
+ * stopped. Whether the port came free is the answer.
+ */
+async function replaceOldDashboard(port) {
+  const pid = listenerOn(port);
+  if (!pid || pid === process.pid) return false;
+  try {
+    if (process.platform === 'win32') spawnSync('taskkill', ['/PID', String(pid), '/F'], { windowsHide: true, timeout: 10000 });
+    else process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    return false;
+  }
+  for (let i = 0; i < 50; i++) {
+    if (listenerOn(port) === null) return true;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+
 /**
  * The dashboard, started from the home folder: kept in a kryptheon-tests
  * folder there, the one record already uses - set up the first time, asked
@@ -2732,7 +2778,16 @@ async function dashboardCommand() {
   }
   // Running already: open that one rather than a second, which would watch
   // the same project twice. Exit code 0 is how the launcher knows.
-  if (await dashboardAlreadyRunning(DASHBOARD_PORT)) {
+  const running = await dashboardAlreadyRunning(DASHBOARD_PORT);
+  const mine = require(path.join(PACKAGE_DIR, 'package.json')).version;
+  if (running && running.version !== mine) {
+    const was = running.version || 'from before 0.1.41';
+    console.log('');
+    console.log(await replaceOldDashboard(DASHBOARD_PORT)
+      ? '  An older Kryptheon dashboard (' + was + ') was running for this folder.\n  It was closed, and ' + mine + ' starts in its place.'
+      : '  An older Kryptheon dashboard (' + was + ') is still running and could not be\n  closed. This one starts at another address; close the old window when you can.');
+  }
+  if (running && running.version === mine) {
     const address = 'http://127.0.0.1:' + DASHBOARD_PORT + '/';
     const shown = openInBrowser(address);
     console.log('');

package/kryptheon-dashboard.js

@@ -25,6 +25,7 @@ const { spawnSync } = require('child_process');
 const store = require('./kryptheon-store.js');
 const changes = require('./kryptheon-changes.js');
 const autostart = require('./kryptheon-autostart.js');
+const VERSION = require('./package.json').version;
 
 /**
  * Every check the dashboard knows the name of, in the order the person asked
@@ -543,6 +544,9 @@ function buildState(root, env) {
 
   return {
     project: { name: path.basename(root), root: root, storeDir: paths.dir },
+    // Which kryptheon this dashboard is: a newer `dashboard` asks, and takes
+    // the place of an older one still running, instead of opening it.
+    kryptheon: VERSION,
     looks: looks,
     proven: proven,
     checks: checks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",