kryptheon 0.1.19 → 0.1.21

package/README.md

@@ -161,20 +161,58 @@ 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
+## Dashboard
 
-| 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 …" |
+```
+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: what is broken, what needs a
+look, every run, recent changes, and switches for each check. `Run now`
+replays your recordings or reads your code from the page. It is only
+reachable from this machine; press Ctrl+C to stop it. From a script, use
+`npx kryptheon dashboard`.
+
+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.
-
-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();
@@ -77,6 +85,10 @@ function usage() {
   console.log('  npx kryptheon accept <name>  agree that one test\'s new result is the correct one');
   console.log('  npx kryptheon remove [name]  list the recordings, or remove one you no longer want');
   console.log('  npx kryptheon setup-ai       tell your AI assistant to check its work');
+  console.log('  npx kryptheon verify         after a change: what changed, what broke, what got fixed');
+  console.log('  npx kryptheon recheck [id]   prove a fix: run the check again, and say FIXED or not');
+  console.log('  npx kryptheon code           read your frontend code for text inserted as HTML');
+  console.log('  npx kryptheon dashboard      open this project\'s dashboard (also: npx kryptheon, in a terminal)');
   console.log('');
   console.log('  add --quiet to check for one line when everything passes');
   console.log('  npx kryptheon --version      print the version you have installed');
@@ -864,15 +876,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 +1216,7 @@ async function finaliseRecording(outFile, context) {
 
     reportTidying(tidied);
     reportSecrets(secrets);
-    keepArtefactsOutOfGit();
+    keepArtefactsOutOfGit(!!(secrets && secrets.length));
     await offerToDropLogout(named);
     reportReplayRisks(named);
     reportFragileSelectors(named);
@@ -1321,6 +1367,7 @@ async function remove(name) {
     console.error("");
     return 1;
   }
+  if (!openStore()) return 1;
 
   const gone = [];
   const failed = [];
@@ -1494,6 +1541,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;
 
@@ -1705,6 +1755,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
@@ -1937,6 +1988,377 @@ function setupAi() {
   return results.some((r) => r.action === 'failed') ? 1 : 0;
 }
 
+// --- code -------------------------------------------------------------------
+//
+// A read of the project's own frontend code for text inserted as HTML
+// (kryptheon-code.js). Nothing is run and nothing is sent; every finding is
+// "verification required", so the exit code is 0 unless the read could not
+// happen at all - a script must never take an unproven risk for a break.
+
+// How many fix prompts are printed in full. The rest are saved in the store
+// and shown by the dashboard; forty prompts in a terminal is a wall nobody reads.
+const CODE_PROMPTS_SHOWN = 5;
+
+// The read itself, saved to the store. Shared by the command and the
+// dashboard's "Run now", so both leave the same record behind.
+function readCodeAndSave(opened) {
+  const reader = require(path.join(PACKAGE_DIR, 'kryptheon-code.js'));
+  const result = reader.scanProject(USER_DIR, { packageDir: PACKAGE_DIR });
+  if (!result.ran) return result;
+  try {
+    fs.writeFileSync(opened.codeFindings, JSON.stringify({
+      checkedAt: new Date().toISOString(),
+      filesRead: result.filesRead,
+      findings: result.findings,
+      unreadable: result.unreadable,
+    }, null, 2) + String.fromCharCode(10), 'utf8');
+  } catch (err) {
+    result.saveError = err.message;
+  }
+  return result;
+}
+
+function codeRead() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+
+  const result = readCodeAndSave(opened);
+  if (!result.ran) {
+    console.error('');
+    console.error('  I could not read your code this time: ' + result.why + '.');
+    console.error('  Nothing was checked - this is not a pass.');
+    console.error('');
+    return 2;
+  }
+  if (result.saveError) console.error('  (could not save this read: ' + result.saveError + ')');
+
+  const high = result.findings.filter((f) => f.severity === 'HIGH');
+  const medium = result.findings.filter((f) => f.severity !== 'HIGH');
+  console.log('');
+  console.log('  I read ' + result.filesRead + ' file' + (result.filesRead === 1 ? '' : 's') + ' of your app\'s code.');
+  if (!result.findings.length) {
+    console.log('  I found no place where text that could come from outside the page is');
+    console.log('  inserted as HTML. That is what this read looks for, and only that.');
+  } else {
+    console.log('  ' + result.findings.length + ' place' + (result.findings.length === 1 ? '' : 's') +
+      ' where text may be inserted as HTML (' + high.length + ' HIGH, ' + medium.length + ' MEDIUM).');
+    console.log('  I did not run anything, so each one needs a look before it is called a bug.');
+    for (const f of high.concat(medium)) {
+      console.log('');
+      console.log('  ' + f.severity + '   ' + f.file + ':' + f.line + '   (verification required)');
+      console.log('    ' + f.headline);
+      console.log('    ' + f.sink + ':  ' + f.expression);
+    }
+    const prompted = high.slice(0, CODE_PROMPTS_SHOWN);
+    if (prompted.length) {
+      console.log('');
+      console.log('  ' + '-'.repeat(68));
+      console.log('  For the HIGH ones, paste this into your AI tool - one at a time:');
+      for (const f of prompted) {
+        console.log('');
+        f.fixPrompt.split(String.fromCharCode(10)).forEach((l) => console.log('    ' + l));
+      }
+    }
+    if (result.findings.length > prompted.length) {
+      console.log('');
+      console.log('  The fix for every one is saved in:');
+      console.log('    ' + opened.codeFindings);
+    }
+  }
+  if (result.unreadable.length) {
+    console.log('');
+    console.log('  What I could not read (unknown, not clear):');
+    for (const u of result.unreadable) console.log('    ' + u.file + ' - ' + u.why);
+  }
+  console.log('');
+  return 0;
+}
+
+// --- verify -----------------------------------------------------------------
+//
+// The command for the end of an AI task: what changed since Kryptheon last
+// looked, which checks that calls for, run the ones that can run here, and
+// say what broke and what got fixed. "The AI said done" is not the answer;
+// this is. The looking itself is kryptheon-look.js, shared with the dashboard.
+
+function verify() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+
+  const result = looker.look(USER_DIR, {
+    beforeRun: (diff, now) => {
+      console.log('');
+      if (diff.first) {
+        console.log('  First look at this project: ' + Object.keys(now.files).length + ' files noted.');
+        console.log('  Next time, I will say exactly what changed since now.');
+      } else if (!diff.files.length) {
+        console.log('  Nothing changed since the last look.');
+      } else {
+        console.log('  WHAT CHANGED   ' + diff.files.length + ' file' + (diff.files.length === 1 ? '' : 's') + ', in: ' + diff.parts.join(', '));
+        for (const part of diff.parts) {
+          const inPart = diff.files.filter((f) => f.part === part);
+          console.log('');
+          console.log('    ' + part);
+          for (const f of inPart.slice(0, 15)) console.log('      ' + f.state.padEnd(9) + f.path);
+          if (inPart.length > 15) console.log('      ... and ' + (inPart.length - 15) + ' more');
+          if (part === 'dependencies') {
+            for (const d of diff.dependencies) {
+              console.log('      package ' + d.name + ': ' + (d.change === 'added' ? 'added ' + d.to : d.change === 'removed' ? 'removed (was ' + d.from + ')' : d.from + ' -> ' + d.to));
+            }
+          }
+        }
+      }
+    },
+    frontend: () => readCodeAndSave(opened),
+    regression: () => {
+      console.log('');
+      console.log('  Replaying your recordings...');
+      const r = spawnSync(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+        cwd: USER_DIR,
+        stdio: 'inherit',
+        env: process.env,
+      });
+      return r.status;
+    },
+  }, { by: 'verify' });
+
+  const { diff, plan, fresh, fixed, removed, openConfirmed, after } = result;
+  console.log('');
+  if (plan.length) {
+    console.log('  CHECKS');
+    for (const step of plan) console.log('    ' + step.id.padEnd(12) + step.state);
+  } else if (!diff.first && diff.files.length) {
+    console.log('  CHECKS   none apply to this change (' + diff.parts.join(', ') + ').');
+  }
+
+  console.log('');
+  if (diff.first) {
+    console.log('  STARTING POINT   ' + after.findings.length + ' finding' + (after.findings.length === 1 ? '' : 's') +
+      ' already here (see npx kryptheon dashboard). Only what changes from now on will be called new.');
+  } else {
+    if (fresh.length) {
+      console.log('  WHAT BROKE   ' + fresh.length + ' new');
+      for (const f of fresh) {
+        console.log('    ' + f.severity + '   ' + f.status + '   ' + f.where);
+        console.log('      ' + f.headline);
+      }
+    } else {
+      console.log('  WHAT BROKE   nothing new that the checks above could see.');
+    }
+    if (fixed.length) {
+      console.log('');
+      console.log('  WHAT GOT FIXED   ' + fixed.length);
+      for (const f of fixed) console.log('    ' + f.where + '   ' + f.headline);
+    }
+    if (removed.length) {
+      console.log('');
+      console.log('  GONE WITH ITS FILE   ' + removed.length + ' (the file was deleted - not the same as fixed)');
+      for (const f of removed) console.log('    ' + f.where + '   ' + f.headline);
+    }
+  }
+  if (openConfirmed.length) {
+    console.log('');
+    console.log('  Still broken: ' + openConfirmed.length + ' confirmed problem' + (openConfirmed.length === 1 ? '' : 's') + '. The fix prompts are in the dashboard.');
+  }
+  console.log('');
+  if (result.saveError) console.error('  (could not save this look: ' + result.saveError + ')');
+
+  // Non-zero while anything confirmed is broken - new or not - so an AI tool
+  // reading only the exit code is never told its work left things fine when
+  // they are not. Findings that only need a look do not count.
+  return openConfirmed.length || result.regressionExit === 1 ? 1 : 0;
+}
+
+// --- recheck ----------------------------------------------------------------
+//
+// The end of the fix loop: prove a fix. The finding's own check runs again,
+// and so does everything the changes since call for, so "fixed" never means
+// "the code changed", and a fix that broke something else says so.
+
+function replayForLoop() {
+  console.log('');
+  console.log('  Replaying your recordings...');
+  const r = spawnSync(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+    cwd: USER_DIR,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  return r.status;
+}
+
+const VERDICT_WORDS = {
+  fixed: 'FIXED',
+  'still open': 'STILL OPEN',
+  'gone with its file': 'GONE WITH ITS FILE (not the same as fixed)',
+  'could not confirm': 'COULD NOT CONFIRM',
+};
+
+function recheckCommand(id) {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+  const dash = require(path.join(PACKAGE_DIR, 'kryptheon-dashboard.js'));
+
+  if (!id) {
+    const open = dash.buildState(USER_DIR).findings;
+    console.log('');
+    if (!open.length) {
+      console.log('  Nothing is open. There is nothing to re-check.');
+    } else {
+      console.log('  Open findings - re-check one after fixing it:  npx kryptheon recheck <id>');
+      console.log('');
+      for (const f of open) console.log('    ' + f.id + '   ' + f.severity.padEnd(8) + f.status.padEnd(23) + f.where + '   ' + f.headline);
+    }
+    console.log('');
+    return 0;
+  }
+
+  const r = looker.recheck(USER_DIR, { frontend: () => readCodeAndSave(opened), regression: replayForLoop }, String(id).trim());
+  console.log('');
+  if (!r.found) {
+    console.error('  There is no open finding with the id ' + id + '.');
+    console.error('  npx kryptheon recheck, on its own, lists the ones that are open.');
+    console.error('');
+    return 1;
+  }
+  console.log('  RE-CHECK   ' + r.id + '   ' + r.where);
+  console.log('    ' + r.headline);
+  console.log('');
+  console.log('  VERDICT    ' + VERDICT_WORDS[r.verdict] + (r.why ? ' - ' + r.why : ''));
+  if (r.newProblems.length) {
+    console.log('');
+    console.log('  NEW PROBLEMS   ' + r.newProblems.length + ' appeared with this change:');
+    for (const p of r.newProblems) console.log('    ' + p.id + '   ' + p.severity + '   ' + p.status + '   ' + p.where + '   ' + p.headline);
+  } else if (r.verdict === 'fixed') {
+    console.log('');
+    console.log('  Nothing new broke that the checks could see.');
+  }
+  console.log('');
+  if (r.verdict === 'could not confirm') return 2;
+  return r.verdict === 'fixed' && !r.newProblems.length ? 0 : 1;
+}
+
+// --- dashboard --------------------------------------------------------------
+//
+// One page on this machine for everything Kryptheon knows about this project
+// (kryptheon-dashboard.js). Runs until Ctrl+C.
+
+const DASHBOARD_PORT = 4789;
+
+function runFromDashboard(id, opened) {
+  if (id === 'frontend') {
+    const result = readCodeAndSave(opened);
+    return result.ran ? { ok: true } : { ok: false, why: result.why };
+  }
+  if (id === 'regression') {
+    // The same command a person types, as a separate process, so the page
+    // stays answerable while a browser replays the flows.
+    return new Promise((resolve) => {
+      const child = spawn(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'check', '--quiet'], {
+        cwd: USER_DIR,
+        stdio: 'ignore',
+        env: process.env,
+      });
+      child.on('error', (err) => resolve({ ok: false, why: err.message }));
+      // A run that found broken flows is a run that finished; its results are
+      // in the history the page reads next.
+      child.on('close', (code) => resolve(code === 0 || code === 1 ? { ok: true, exit: code } : { ok: false, why: 'the run stopped with exit ' + code }));
+    });
+  }
+  return { ok: false, why: '"' + id + '" cannot be run from the dashboard' };
+}
+
+async function dashboardCommand() {
+  const here = project.inspectProject(USER_DIR);
+  if (!here.ok) {
+    for (const line of project.noProjectLines(here)) console.error(line);
+    return 1;
+  }
+  const opened = openStore();
+  if (!opened) return 1;
+  const dash = require(path.join(PACKAGE_DIR, 'kryptheon-dashboard.js'));
+  const app = dash.createServer(USER_DIR, {
+    run: (id) => runFromDashboard(id, opened),
+    // The same `recheck` a person types, in its own process, so the page stays
+    // answerable while a flow is replayed. Its verdict is read from the store.
+    recheck: (id) => new Promise((resolve) => {
+      // Only a verdict written by this re-check counts: an older one for the
+      // same finding, read after a child that failed early, would be a stale
+      // answer shown as a fresh one.
+      const startedAt = new Date().toISOString();
+      const child = spawn(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js'), 'recheck', id], {
+        cwd: USER_DIR,
+        stdio: 'ignore',
+        env: process.env,
+      });
+      child.on('error', (err) => resolve({ ok: false, why: err.message }));
+      child.on('close', () => {
+        let last = null;
+        try {
+          const lines = fs.readFileSync(opened.fixes, 'utf8').split(String.fromCharCode(10)).filter(Boolean);
+          for (let i = lines.length - 1; i >= 0 && !last; i--) {
+            const a = JSON.parse(lines[i]);
+            if (a.id === id && a.at >= startedAt) last = a;
+          }
+        } catch (err) {
+          last = null;
+        }
+        resolve(last || { ok: false, why: 'the re-check did not record a verdict' });
+      });
+    }),
+  });
+  let port;
+  try {
+    port = await app.listen(DASHBOARD_PORT);
+  } catch (err) {
+    // Taken - by another project's dashboard, most likely. Any free port will do.
+    port = await app.listen(0);
+  }
+  console.log('');
+  console.log('  Kryptheon dashboard for ' + path.basename(USER_DIR) + ':');
+  console.log('');
+  console.log('    http://127.0.0.1:' + port + '/');
+  console.log('');
+  console.log('  Open that address in your browser. It is only reachable from this');
+  console.log('  machine. Press Ctrl+C here to stop it.');
+  console.log('');
+
+  // While the page is open, Kryptheon notices changes by itself: once a change
+  // has settled, it looks, runs the fast checks, and the page shows what
+  // changed and what came of it. Recordings are replayed only from the page's
+  // Run now - a replay while the app is down would call every flow broken.
+  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
+  looker.startWatch(USER_DIR, {
+    frontend: () => readCodeAndSave(opened),
+    regression: () => null,
+  }, {
+    onLook: (r) => {
+      if (r.diff.first) return;
+      const when = new Date().toLocaleTimeString();
+      console.log('  ' + when + '  ' + r.diff.files.length + ' file' + (r.diff.files.length === 1 ? '' : 's') + ' changed (' +
+        r.diff.parts.join(', ') + ') - ' + r.fresh.length + ' new, ' + r.fixed.length + ' fixed. See the page.');
+    },
+    onError: (err) => console.error('  (could not look at a change: ' + err.message + ')'),
+  });
+  return new Promise(() => {});
+}
+
 // --- accept -----------------------------------------------------------------
 
 function baselineApi() {
@@ -1983,6 +2405,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);
@@ -2121,6 +2546,26 @@ function handToFolderCopy() {
     }
   }
 
+  // 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.
@@ -2173,12 +2618,27 @@ async function main() {
     case 'accept':
       return finishWith(accept(rest.join(' ').trim()));
       break;
+    case 'code':
+      return finishWith(codeRead());
+    case 'verify':
+      return finishWith(verify());
+    case 'recheck':
+      return finishWith(recheckCommand(rest[0]));
     case '-v':
     case '--version':
     case 'version':
       console.log(packageVersion());
       return finishWith(0);
+    case 'dashboard':
+      return finishWith(await dashboardCommand());
     case undefined:
+      // One command starts Kryptheon - in a terminal a person is looking at.
+      // Run by a script or an AI tool there is nobody to open a page for, and
+      // a server that never exits would hang it, so it prints the usage as it
+      // always did.
+      if (process.stdin.isTTY && process.stdout.isTTY) return finishWith(await dashboardCommand());
+      usage();
+      return finishWith(0);
     case '-h':
     case '--help':
     case 'help':