kryptheon 0.1.12 → 0.1.14

package/README.md

@@ -6,6 +6,27 @@ 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).
 
+## 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
 
 ```

package/bin/kryptheon.js

@@ -68,14 +68,14 @@ function usage() {
   console.log('');
   console.log('  kryptheon - record and check your app');
   console.log('');
-  console.log('  kryptheon record <url>   open your app and record what you do as a test');
-  console.log('  kryptheon check          run every recorded test and report in plain language');
-  console.log('  kryptheon accept <name>  agree that one test\'s new result is the correct one');
-  console.log('  kryptheon remove [name]  list the recordings, or remove one you no longer want');
-  console.log('  kryptheon setup-ai       tell your AI assistant to check its work');
+  console.log('  npx kryptheon record <url>   open your app and record what you do as a test');
+  console.log('  npx kryptheon check          run every recorded test and report in plain language');
+  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('');
   console.log('  add --quiet to check for one line when everything passes');
-  console.log('  kryptheon --version      print the version you have installed');
+  console.log('  npx kryptheon --version      print the version you have installed');
   console.log('');
 }
 
@@ -603,7 +603,7 @@ function windowUndetectedLines(seconds) {
     '  so this is most likely the check being wrong rather than the browser.',
     '',
     '  If the window is open in front of you, run it again with the check off:',
-    '    KRYPTHEON_FORCE_RECORD=1 kryptheon record <url>',
+    '    KRYPTHEON_FORCE_RECORD=1 npx kryptheon record <url>',
     '',
     '  If there is no window on screen, the browser may have opened somewhere',
     '  with no desktop to draw on - a remote session, a container, or an AI',
@@ -626,7 +626,7 @@ function probeUnclearLines(answered, unanswered) {
     '  machine under load, or security software holding up the check itself.',
     '',
     '  If the window is open in front of you, run it again with the check off:',
-    '    KRYPTHEON_FORCE_RECORD=1 kryptheon record <url>',
+    '    KRYPTHEON_FORCE_RECORD=1 npx kryptheon record <url>',
     '',
     '  Otherwise just run the same command again.',
     '',
@@ -852,7 +852,7 @@ function reportSecrets(replacements) {
   console.log('');
   // Said plainly, because the alternative is signing in with a blank password
   // and spending an afternoon looking at the wrong thing.
-  console.log('  Until that file exists, "kryptheon check" will skip this recording');
+  console.log('  Until that file exists, "npx kryptheon check" will skip this recording');
   console.log('  rather than sign in with a blank password.');
   console.log('');
   console.log('  Keep .env out of version control - it holds the real value.');
@@ -1116,7 +1116,9 @@ async function finaliseRecording(outFile, context) {
     const named = await nameRecording(outFile);
     console.log('');
     console.log('  Saved to ' + named);
-    console.log('  Run it any time with:  kryptheon check');
+    // npx, not the bare name: somebody who started with `npx kryptheon record`
+    // has no `kryptheon` command, and would be told it does not exist.
+    console.log('  Run it any time with:  npx kryptheon check');
     console.log('');
 
     reportTidying(tidied);
@@ -1251,7 +1253,7 @@ async function remove(name) {
   } else {
     listRecordings(names);
     if (!process.stdin.isTTY) {
-      console.log("  To remove one, run:  kryptheon remove <name>");
+      console.log("  To remove one, run:  npx kryptheon remove <name>");
       console.log("");
       return 0;
     }
@@ -1268,7 +1270,7 @@ async function remove(name) {
   if (choice.action === "unclear") {
     console.error("");
     console.error("  " + choice.why + ": " + JSON.stringify(choice.said));
-    console.error("  Run \"kryptheon remove\" on its own to see the list.");
+    console.error("  Run \"npx kryptheon remove\" on its own to see the list.");
     console.error("");
     return 1;
   }
@@ -1300,13 +1302,129 @@ async function remove(name) {
   return failed.length ? 1 : 0;
 }
 
+// --- setting the folder up --------------------------------------------------
+//
+// See the setup section of kryptheon-project.js for why this exists. That file
+// decides; this one asks, writes and installs.
+
+function writeOwnPackageJson(dir) {
+  // 'wx': never over the top of one that appeared since the folder was looked
+  // at. Somebody's package.json is not ours to replace.
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ private: true }, null, 2) + '\n', { flag: 'wx' });
+    return true;
+  } catch (err) {
+    return err.code === 'EEXIST';
+  }
+}
+
+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'
+    ? spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'npm'].concat(args), { cwd: dir, encoding: 'utf8' })
+    : spawnSync('npm', args, { cwd: dir, encoding: 'utf8' });
+  // 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) {
+    console.log('  Installed.');
+    console.log('');
+  }
+  return ok;
+}
+
+// A folder `record` is about to use, made ready: its own package.json, its own
+// copy of kryptheon. Returns false, having said why, if either did not happen.
+function makeReady(dir) {
+  if (!project.hasPackageJson(dir) && !writeOwnPackageJson(dir)) {
+    console.error('');
+    console.error('  Could not create package.json in:  ' + dir);
+    console.error('  This folder may be read-only. Make a new folder of your own and');
+    console.error('  run the same command from there.');
+    console.error('');
+    return false;
+  }
+  if (!project.kryptheonInstalledIn(dir) && !installKryptheonIn(dir)) {
+    for (const line of project.installFailedLines()) console.error(line);
+    return false;
+  }
+  return true;
+}
+
+// Run again from inside the new folder rather than moving this process there:
+// every path in this file is worked out once, from the folder the command
+// started in.
+async function recordFromHome(plan, url) {
+  try {
+    fs.mkdirSync(plan.into, { recursive: true });
+  } catch (err) {
+    console.error('');
+    console.error('  Could not make the folder:  ' + plan.into);
+    console.error('  Make a new folder of your own, open a terminal in it, and run the');
+    console.error('  same command again.');
+    console.error('');
+    return 1;
+  }
+  if (!makeReady(plan.into)) return 1;
+
+  const child = spawn(process.execPath, [__filename, 'record', url], { cwd: plan.into, stdio: 'inherit' });
+  // Ctrl-C reaches the child too, and the child is the one that saves what was
+  // recorded. This process waits for it rather than exiting under it.
+  const wait = () => {};
+  process.on('SIGINT', wait);
+  process.on('SIGTERM', wait);
+  const code = await new Promise((resolve) => {
+    child.on('error', () => resolve(1));
+    child.on('close', (status) => resolve(status === null ? 1 : status));
+  });
+  process.removeListener('SIGINT', wait);
+  process.removeListener('SIGTERM', wait);
+
+  if (code === 0) for (const line of project.homeDoneLines(plan.into)) console.log(line);
+  return code;
+}
+
+// Before the browser: it is a 200MB download on a new machine, and a
+// recording that cannot be checked afterwards is somebody's five minutes
+// thrown away. Returns null to carry on recording, or an exit code to stop.
+async function prepareFolder(url) {
+  const plan = project.setupPlan(USER_DIR);
+  if (plan.action === 'ready') return null;
+
+  const refusing = plan.action === 'refuse';
+  for (const line of project.setupLines(plan, url)) (refusing ? console.error : console.log)(line);
+  if (refusing) return 1;
+
+  // Asked where there is a keyboard. Where there is not, the question's own
+  // default is taken rather than refusing: isTTY is false in plenty of
+  // perfectly good terminals (see noWindowLines), and a command that refuses
+  // there can never work for the person who ran it. The one question whose
+  // default is no - a second project inside somebody's first - stays no.
+  const question = project.setupQuestion(plan);
+  const yes = process.stdin.isTTY
+    ? project.answeredYes(await askLine(question.text), question.yesByDefault)
+    : question.yesByDefault;
+  if (!yes) {
+    console.log('');
+    console.log('  Nothing was changed, and nothing was recorded.');
+    console.log('');
+    return 1;
+  }
+
+  if (plan.action === 'home') return await recordFromHome(plan, url);
+  return makeReady(USER_DIR) ? null : 1;
+}
+
 async function record(url) {
   if (!url) {
     console.error('');
     console.error('  Which address should I open?');
     console.error('');
     console.error('  Add the web address of your app, for example:');
-    console.error('    kryptheon record https://www.example.com');
+    console.error('    npx kryptheon record https://www.example.com');
     console.error('');
     return 1;
   }
@@ -1320,6 +1438,11 @@ async function record(url) {
     return 1;
   }
 
+  // After the address is known to answer, so a typo is not the thing that
+  // gets a folder set up; before the browser, which is the expensive part.
+  const setup = await prepareFolder(url);
+  if (setup !== null) return setup;
+
   if (!ensureBrowser()) return 1;
 
   const existingBefore = listSpecFiles();
@@ -1429,20 +1552,10 @@ async function record(url) {
 // Recordings import the fixture by package name, which only resolves if
 // kryptheon is in the user's own node_modules. Running through a bare `npx`
 // puts the package somewhere the tests cannot see.
-// Deliberately a filesystem walk, not require.resolve: this file lives inside
-// the kryptheon package, and a package with a name and an "exports" map can
-// always resolve itself by name, so require.resolve would answer "yes" even
-// when the user's tests have no way to find it.
+// One walk, shared with record's setup, so that record and check can never
+// disagree about whether a folder is ready.
 function fixtureResolvesForUser() {
-  let dir = USER_DIR;
-  for (;;) {
-    if (fs.existsSync(path.join(dir, 'node_modules', 'kryptheon', 'kryptheon-fixture.js'))) {
-      return true;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return false;
-    dir = parent;
-  }
+  return project.kryptheonReachableFrom(USER_DIR);
 }
 
 // Only a problem if a recording actually asks for it: specs written against a
@@ -1553,7 +1666,7 @@ function check(options) {
     console.log('');
     console.log('    npm i -D kryptheon');
     console.log('');
-    console.log('  Then run "kryptheon check" again.');
+    console.log('  Then run "npx kryptheon check" again.');
     console.log('');
     return 1;
   }
@@ -1588,7 +1701,7 @@ function check(options) {
     console.log('  Skipped ' + path.join('tests', name));
     console.log('  This is not a real recording - it only opens a page and stops,');
     console.log('  so it cannot tell you whether anything works.');
-    console.log('  Record it again:  kryptheon record <url>');
+    console.log('  Record it again:  npx kryptheon record <url>');
   }
 
   if (!triage.runnable.length) {
@@ -1600,7 +1713,7 @@ function check(options) {
       console.log('  Create the .env file above and run this again.');
     } else {
       console.log('  None of the files in tests/ is a usable recording.');
-      console.log('  Record one with:  kryptheon record <url>');
+      console.log('  Record one with:  npx kryptheon record <url>');
     }
     console.log('');
     return 1;
@@ -1793,7 +1906,7 @@ function listBaselines(api) {
   console.log('');
   if (!keys.length) {
     console.log('  No tests have a saved result yet.');
-    console.log('  Run "kryptheon check" once and they will be saved automatically.');
+    console.log('  Run "npx kryptheon check" once and they will be saved automatically.');
     console.log('');
     return 0;
   }
@@ -1807,7 +1920,7 @@ function listBaselines(api) {
   }
   console.log('');
   console.log('  To agree that a new result is correct:');
-  console.log('    kryptheon accept "<name>"');
+  console.log('    npx kryptheon accept "<name>"');
   console.log('');
   return 0;
 }
@@ -1826,7 +1939,7 @@ function accept(name) {
   if (!matches.length) {
     console.error('');
     console.error('  No saved result for a test called "' + name + '".');
-    console.error('  Run "kryptheon accept" on its own to see the names.');
+    console.error('  Run "npx kryptheon accept" on its own to see the names.');
     console.error('');
     return 1;
   }
@@ -1956,6 +2069,7 @@ module.exports = {
   applyRules: applyRules,
   rulesBlock: rulesBlock,
   record: record,
+  prepareFolder: prepareFolder,
   finaliseRecording: finaliseRecording,
   takeOutSecrets: takeOutSecrets,
   reportSecrets: reportSecrets,

package/kryptheon-project.js

@@ -23,6 +23,12 @@ const path = require('path');
 // stumble into.
 const ESCAPE_HATCH = 'KRYPTHEON_ALLOW_NO_PACKAGE_JSON';
 
+// Where `record` keeps recordings for somebody who ran it in their home folder.
+// A new terminal opens there, so for anyone who has only a web address - an
+// app built in Lovable, no source folder anywhere - it is where the command
+// gets typed.
+const HOME_RECORDINGS = 'kryptheon-tests';
+
 function hasPackageJson(dir) {
   try {
     return fs.statSync(path.join(dir, 'package.json')).isFile();
@@ -107,6 +113,13 @@ function inspectProject(dir, env) {
   const personal = isHomeOrSystem(dir);
   const base = { dir: dir, packaged: packaged, personal: personal, allowed: allowed };
 
+  // Somebody whose recordings `record` put in a folder of their own, standing
+  // in their home folder again because that is where a new terminal opens.
+  // Pointed at by name, rather than told to go and find a project they never
+  // had.
+  const kept = tidy(dir) === tidy(os.homedir()) ? path.join(path.resolve(dir), HOME_RECORDINGS) : null;
+  if (kept && hasPackageJson(kept)) base.recordingsAt = kept;
+
   if (allowed) return Object.assign({ ok: true, reason: null }, base);
 
   // A home folder is refused even when it has a package.json, and this is not
@@ -131,6 +144,19 @@ function inspectProject(dir, env) {
 function noProjectLines(inspection) {
   const lines = [''];
 
+  if (inspection.recordingsAt) {
+    lines.push('  This is your home folder, not a project.');
+    lines.push('');
+    lines.push('  Your recordings are in:  ' + inspection.recordingsAt);
+    lines.push('');
+    lines.push('  To check them:');
+    lines.push('');
+    lines.push('    cd "' + inspection.recordingsAt + '"');
+    lines.push('    npx kryptheon check');
+    lines.push('');
+    return lines;
+  }
+
   if (inspection.personal) {
     lines.push('  This is your home or a system folder, not a project.');
     lines.push('');
@@ -161,8 +187,18 @@ function noProjectLines(inspection) {
   lines.push('  Change into your project folder and run this again:');
   lines.push('');
   lines.push('    cd path\\to\\your\\project');
-  lines.push('    kryptheon check');
+  lines.push('    npx kryptheon check');
   lines.push('');
+  // The person with a web address and no folder at all - an app built in
+  // Lovable - has no project to change into, and would be stuck on the line
+  // above. Not offered in a system folder: record refuses to set one up.
+  if (!inspection.personal || tidy(inspection.dir) === tidy(os.homedir())) {
+    lines.push('  No project folder, only a web address? Record from here and it');
+    lines.push('  will be set up for you:');
+    lines.push('');
+    lines.push('    npx kryptheon record https://your-app.example.com');
+    lines.push('');
+  }
   lines.push('  If you really do keep recordings outside a package, set');
   lines.push('  ' + ESCAPE_HATCH + '=1 and this will run anyway.');
   lines.push('');
@@ -179,7 +215,7 @@ function noRecordingsLines() {
     '',
     '  Record a flow through your app first:',
     '',
-    '    kryptheon record http://localhost:3000',
+    '    npx kryptheon record http://localhost:3000',
     '',
     '  That opens a browser window, so it has to be run by a person in a',
     '  normal terminal - it cannot be done from an AI assistant.',
@@ -187,8 +223,296 @@ function noRecordingsLines() {
   ];
 }
 
+// --- Setting a folder up, before recording into it ---------------------------
+//
+// Somebody who built their app in Lovable has an address and nothing else: no
+// source folder, no package.json, nothing to change into. Their recordings
+// still need somewhere to live, `check` refuses a folder with no package.json,
+// and a recording cannot load the fixture unless kryptheon is installed where
+// the recording is.
+//
+// `record` used to find all of that out afterwards. Measured in an empty
+// folder: it started the browser, would have let the person spend five minutes
+// using their app and saved the recording - and then `check`, in that same
+// folder, said "There is no project here". So record now works out what is
+// missing before the browser, which is a 200MB download on a new machine, and
+// offers to add it.
+
+/**
+ * Whether kryptheon can be loaded by a recording saved in this folder.
+ *
+ * A filesystem walk, not require.resolve: this file lives inside the kryptheon
+ * package, and a package with a name and an "exports" map can always resolve
+ * itself by name, so require.resolve would answer "yes" even when the user's
+ * recordings have no way to find it.
+ */
+function kryptheonReachableFrom(dir) {
+  let current = path.resolve(String(dir || ''));
+  if (insideKryptheonItself(current)) return true;
+  for (;;) {
+    if (fs.existsSync(path.join(current, 'node_modules', 'kryptheon', 'kryptheon-fixture.js'))) {
+      return true;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+/**
+ * Inside the kryptheon package's own folder - this repository.
+ *
+ * Node lets a package load itself by its own name, so a recording made here
+ * finds the fixture with no node_modules/kryptheon anywhere. Without this,
+ * record in this repository offered to npm install kryptheon into kryptheon.
+ * Only the nearest package.json counts: that is the package a file belongs to.
+ */
+function insideKryptheonItself(dir) {
+  let current = dir;
+  for (;;) {
+    if (hasPackageJson(current)) {
+      // The name alone is not enough: somebody's own app can be called that.
+      // The fixture beside it is what makes it this package.
+      try {
+        return JSON.parse(fs.readFileSync(path.join(current, 'package.json'), 'utf8')).name === 'kryptheon' &&
+          fs.existsSync(path.join(current, 'kryptheon-fixture.js'));
+      } catch (err) {
+        return false;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+/**
+ * Installed in this folder itself, not borrowed from one above it.
+ *
+ * A folder record sets up gets its own copy even when one is reachable from
+ * further up. The copy further up is, on the one machine where this was looked
+ * at, a stray install in a home folder - and recordings that lean on that stop
+ * working the day somebody tidies it away.
+ */
+function kryptheonInstalledIn(dir) {
+  return fs.existsSync(path.join(path.resolve(String(dir || '')), 'node_modules', 'kryptheon', 'kryptheon-fixture.js'));
+}
+
+/**
+ * The nearest folder above this one that is a project.
+ *
+ * Stops at a home or system folder rather than walking through it: the one
+ * package.json most likely to be found up there is the stray one a mistaken
+ * install left in a home folder, and that is nobody's project.
+ */
+function projectAbove(dir) {
+  let current = path.resolve(String(dir || ''));
+  for (;;) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    if (isHomeOrSystem(parent)) return null;
+    if (hasPackageJson(parent)) return parent;
+    current = parent;
+  }
+}
+
+/** A folder record set up on an earlier run - its package.json asks for kryptheon. */
+function setUpForKryptheon(dir) {
+  try {
+    const json = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return !!((json.devDependencies && json.devDependencies.kryptheon) ||
+              (json.dependencies && json.dependencies.kryptheon));
+  } catch (err) {
+    return false;
+  }
+}
+
+function isEmptyFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * What this folder needs before a recording made in it can be checked. Only
+ * looks; never writes.
+ *
+ *   ready    nothing
+ *   create   no package.json and no project above: make one, then install
+ *   install  a project without kryptheon: install it
+ *   above    no package.json, but a project sits above this folder
+ *   home     a home folder: record in a kryptheon-tests folder inside it
+ *   refuse   a system folder, or a home whose kryptheon-tests is taken
+ */
+function setupPlan(dir, env) {
+  const environment = env || process.env;
+  const here = path.resolve(String(dir || ''));
+
+  // Somebody who has said they keep recordings outside a package is left
+  // exactly as they were before any of this existed.
+  if (String(environment[ESCAPE_HATCH] || '') !== '') return { action: 'ready', dir: here };
+
+  if (tidy(here) === tidy(os.homedir())) {
+    const into = path.join(here, HOME_RECORDINGS);
+    // Used only if it is plainly ours or plainly nothing. A folder of that name
+    // holding something else is somebody's, and recording into it would put a
+    // package.json and node_modules in the middle of it.
+    if (!fs.existsSync(into) || isEmptyFolder(into) || setUpForKryptheon(into)) {
+      return { action: 'home', dir: here, into: into };
+    }
+    return { action: 'refuse', reason: 'taken', dir: here, into: into };
+  }
+  if (isHomeOrSystem(here)) return { action: 'refuse', reason: 'system', dir: here };
+
+  if (!hasPackageJson(here)) {
+    const above = projectAbove(here);
+    if (above) return { action: 'above', dir: here, project: above };
+    return { action: 'create', dir: here };
+  }
+  if (!kryptheonReachableFrom(here)) return { action: 'install', dir: here };
+  return { action: 'ready', dir: here };
+}
+
+/** What is about to happen to this folder, said before it happens. */
+function setupLines(plan, url) {
+  const address = url || 'https://your-app.example.com';
+  const lines = [''];
+
+  if (plan.action === 'create') {
+    lines.push('  This folder is not set up for recordings yet.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Your recordings are saved here, and kryptheon has to be installed');
+    lines.push('  beside them or they cannot be checked later. So I will add:');
+    lines.push('');
+    lines.push('    package.json     a small file that marks this folder as a project');
+    lines.push('    node_modules     kryptheon itself, about 20MB');
+    lines.push('');
+    lines.push('  Nothing already in this folder is touched.');
+  } else if (plan.action === 'install') {
+    lines.push('  kryptheon is not installed in this project yet.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Recordings load it by name, so without it here they cannot be');
+    lines.push('  checked later. I will run:');
+    lines.push('');
+    lines.push('    npm install --save-dev kryptheon');
+    lines.push('');
+    lines.push('  which adds one line to package.json and about 20MB to node_modules.');
+  } else if (plan.action === 'above') {
+    lines.push('  This folder is inside a project:');
+    lines.push('');
+    lines.push('    ' + plan.project);
+    lines.push('');
+    lines.push('  Recordings belong beside the app they test, so the usual thing is');
+    lines.push('  to run this from there:');
+    lines.push('');
+    lines.push('    cd "' + plan.project + '"');
+    lines.push('    npx kryptheon record ' + address);
+    lines.push('');
+    lines.push('  If that is not your project - a package.json can be left behind by');
+    lines.push('  an install run in the wrong place - I can set this folder up on its');
+    lines.push('  own instead.');
+  } else if (plan.action === 'home') {
+    lines.push('  You are in your home folder.');
+    lines.push('');
+    lines.push('  Recordings are kept in a folder of their own rather than loose in');
+    lines.push('  here, so I will ' + (fs.existsSync(plan.into) ? 'use this one' : 'make one') + ' and work in that:');
+    lines.push('');
+    lines.push('    ' + plan.into);
+  } else if (plan.action === 'refuse' && plan.reason === 'taken') {
+    lines.push('  You are in your home folder. Recordings are kept in a folder of');
+    lines.push('  their own, and I would normally use:');
+    lines.push('');
+    lines.push('    ' + plan.into);
+    lines.push('');
+    lines.push('  but something else is already there, and it is not one I made.');
+    lines.push('  Nothing was changed.');
+    lines.push('');
+    lines.push('  Make a new folder of your own, open a terminal in it, and run the');
+    lines.push('  same command again.');
+  } else if (plan.action === 'refuse') {
+    lines.push('  This is a system folder, not somewhere to keep recordings.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Nothing was changed. Make a new folder of your own - on the Desktop');
+    lines.push('  is fine - open a terminal in it, and run the same command again.');
+    if (process.platform === 'win32') {
+      lines.push('  (In File Explorer: right-click inside the folder, Open in Terminal.)');
+    }
+  }
+  lines.push('');
+  return lines;
+}
+
+/**
+ * The question, and which way Enter answers it.
+ *
+ * Yes by default where saying yes is what the person came for. No by default
+ * for a folder inside another project, where yes puts a second project inside
+ * somebody's first.
+ */
+function setupQuestion(plan) {
+  if (plan.action === 'above') return { text: '  Set this folder up on its own instead? [y/N] ', yesByDefault: false };
+  if (plan.action === 'install') return { text: '  Install it? [Y/n] ', yesByDefault: true };
+  if (plan.action === 'home') return { text: '  Go ahead? [Y/n] ', yesByDefault: true };
+  return { text: '  Set this folder up? [Y/n] ', yesByDefault: true };
+}
+
+/** An answer typed at the question, read the way the question offered it. */
+function answeredYes(answer, yesByDefault) {
+  const typed = String(answer || '').trim();
+  if (!typed) return !!yesByDefault;
+  return /^y/i.test(typed);
+}
+
+/** After recording from a home folder: where the recordings went, and how to get back to them. */
+function homeDoneLines(into) {
+  return [
+    '',
+    '  Your recordings are in:  ' + into,
+    '',
+    '  To check them after a change, open a terminal and run:',
+    '',
+    '    cd "' + into + '"',
+    '    npx kryptheon check',
+    '',
+  ];
+}
+
+/** The install did not finish. Nothing needs undoing: running again picks up where this stopped. */
+function installFailedLines() {
+  return [
+    '',
+    '  kryptheon could not be installed in this folder.',
+    '',
+    '  Installing needs an internet connection. Check it, then run the same',
+    '  command again - nothing needs undoing first.',
+    '',
+    '  Or install it yourself, then record:',
+    '',
+    '    npm install --save-dev kryptheon',
+    '',
+  ];
+}
+
 module.exports = {
   ESCAPE_HATCH: ESCAPE_HATCH,
+  HOME_RECORDINGS: HOME_RECORDINGS,
+  kryptheonReachableFrom: kryptheonReachableFrom,
+  kryptheonInstalledIn: kryptheonInstalledIn,
+  projectAbove: projectAbove,
+  setupPlan: setupPlan,
+  setupLines: setupLines,
+  setupQuestion: setupQuestion,
+  answeredYes: answeredYes,
+  homeDoneLines: homeDoneLines,
+  installFailedLines: installFailedLines,
   hasPackageJson: hasPackageJson,
   systemFolders: systemFolders,
   tidy: tidy,

package/kryptheon-reporter.js

@@ -292,7 +292,7 @@ function translate(message) {
       hideSource: true,
       // %TEST% is filled in with the test's name when the block is printed,
       // so the command resets only this one test.
-      advice: 'if this change is intended, run:  kryptheon accept "%TEST%"',
+      advice: 'if this change is intended, run:  npx kryptheon accept "%TEST%"',
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -38,7 +38,7 @@
     "@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-load.check.js && node kryptheon-package.check.js",
+    "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-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",
@@ -53,6 +53,7 @@
     "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:load": "node kryptheon-load.check.js",
     "check:package": "node kryptheon-package.check.js",
     "prepublishOnly": "node kryptheon-package.check.js"