kryptheon 0.1.19 → 0.1.21

package/kryptheon-look.js

@@ -0,0 +1,259 @@
+// One look at a project: what changed since the last look, which checks that
+// calls for, run the ones that can run, and what is new, fixed or merely
+// deleted. Shared by `npx kryptheon verify` and the dashboard's own watch, so
+// the command and the page can never tell two different stories.
+//
+// Printing is not done here; the caller decides how to say it.
+
+const fs = require('fs');
+const path = require('path');
+const store = require('./kryptheon-store.js');
+const changes = require('./kryptheon-changes.js');
+const dash = require('./kryptheon-dashboard.js');
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Looks once. `runners` does the work that needs the caller's tools:
+ *   runners.frontend()   -> { ran, why }          (the code read)
+ *   runners.regression() -> exit code, or null     (replaying the recordings)
+ * `options.replay` false keeps the recordings from being replayed - the
+ * dashboard's automatic look does that by default, because a replay while the
+ * app is not running reports every flow broken, and that would be a lie.
+ */
+function look(root, runners, options) {
+  const opts = options || {};
+  const paths = store.pathsFor(root);
+  const previous = readJson(paths.snapshot);
+  const now = changes.takeSnapshot(root, previous);
+  const diff = changes.compare(previous, now);
+  const before = dash.buildState(root);
+  const enabled = dash.readConfig(paths).enabled;
+  const available = new Set(dash.CHECKS.filter((c) => c.available).map((c) => c.id));
+
+  // On a first look, every check that can run, so the next look has
+  // something to compare against. `force` adds checks that must run whatever
+  // changed - a re-check has to run the check that found the problem, even
+  // when the fix was made somewhere that check would not otherwise cover.
+  const wanted = (diff.first ? ['frontend', 'regression', 'data'] : diff.checks).slice();
+  for (const id of opts.force || []) if (!wanted.includes(id)) wanted.push(id);
+  const plan = wanted.map((id) => {
+    if (!available.has(id)) return { id: id, state: 'not available yet' };
+    if (!enabled[id]) return { id: id, state: 'switched off in the dashboard' };
+    if (id === 'data') return { id: id, state: 'needs your database - run npx kryptheon-night' };
+    if (id === 'regression' && !before.recordings) return { id: id, state: 'no recordings yet - npx kryptheon record <url>' };
+    if (id === 'regression' && opts.replay === false) return { id: id, state: 'not replayed automatically - press Run now when your app is running' };
+    return { id: id, state: 'run', run: true };
+  });
+
+  // What changed is said before anything runs: a replay can take a minute,
+  // and the person should not sit through it without knowing why.
+  if (typeof runners.beforeRun === 'function') runners.beforeRun(diff, now);
+
+  let regressionExit = null;
+  for (const step of plan.filter((s) => s.run)) {
+    if (step.id === 'frontend') {
+      const r = runners.frontend();
+      step.state = r.ran ? 'ran' : 'could not run: ' + r.why;
+    } else if (step.id === 'regression') {
+      regressionExit = runners.regression();
+      step.state = regressionExit === 0 ? 'ran - every recording held'
+        : regressionExit === 1 ? 'ran - something broke'
+        : 'could not run (exit ' + regressionExit + ')';
+    }
+  }
+
+  const after = dash.buildState(root);
+  const fresh = changes.newFindings(before.findings, after.findings);
+  const gone = changes.goneFindings(before.findings, after.findings);
+  // A finding whose file was deleted is gone, not fixed - the same rule as a
+  // dropped table in the database check. Kept apart, so deleting the code a
+  // finding points at is never mistaken for making it safe.
+  const fileOf = (f) => path.join(root, String(f.where || '').replace(/:\d+$/, ''));
+  const removed = gone.filter((f) => f.check !== 'data' && !fs.existsSync(fileOf(f)));
+  const fixed = gone.filter((f) => removed.indexOf(f) === -1);
+  const openConfirmed = after.findings.filter((f) => f.status === 'confirmed');
+
+  const event = {
+    at: now.takenAt,
+    by: opts.by || 'verify',
+    first: diff.first,
+    files: diff.files,
+    parts: diff.parts,
+    dependencies: diff.dependencies,
+    checks: plan.map((s) => ({ id: s.id, state: s.state })),
+    newFindings: fresh.length,
+    fixed: fixed.length,
+    goneWithFile: removed.length,
+    openConfirmed: openConfirmed.length,
+  };
+  let saveError = null;
+  try {
+    fs.mkdirSync(paths.dir, { recursive: true });
+    fs.writeFileSync(paths.snapshot, JSON.stringify(now) + '\n', 'utf8');
+    fs.appendFileSync(paths.changes, JSON.stringify(event) + '\n', 'utf8');
+  } catch (err) {
+    saveError = err.message;
+  }
+
+  return {
+    diff: diff,
+    snapshot: now,
+    plan: plan,
+    fresh: fresh,
+    fixed: fixed,
+    removed: removed,
+    openConfirmed: openConfirmed,
+    after: after,
+    regressionExit: regressionExit,
+    event: event,
+    saveError: saveError,
+  };
+}
+
+/**
+ * Whether anything changed since the last look, without looking. Cheap enough
+ * to poll: unchanged files keep their hash without being read. The signature
+ * carries each changed file's content hash, so a file still being written
+ * keeps changing it - which is what tells a pause from the end of a task.
+ */
+function pending(root) {
+  const paths = store.pathsFor(root);
+  const previous = readJson(paths.snapshot);
+  if (!previous) return { changed: false, first: true };
+  const now = changes.takeSnapshot(root, previous);
+  const diff = changes.compare(previous, now);
+  const signature = JSON.stringify(diff.files.map((f) => [f.path, f.state, now.files[f.path] ? now.files[f.path].hash : null]));
+  return { changed: diff.files.length > 0, files: diff.files.length, signature: signature };
+}
+
+/**
+ * Looks by itself whenever the project changes, and waits for the change to
+ * settle first. An AI tool writes a dozen files over half a minute; looking
+ * after the first one would report a half-finished task as broken. So a look
+ * happens once the changed files have stayed the same for `quietMs`.
+ *
+ * Recorded flows are not replayed here unless `replay` is true: an automatic
+ * replay while the app is not running reports every flow broken.
+ */
+function startWatch(root, runners, options) {
+  const opts = options || {};
+  const intervalMs = opts.intervalMs || 2000;
+  const quietMs = opts.quietMs || 4000;
+  let seen = null;
+  let since = 0;
+  let busy = false;
+  const doLook = () => {
+    busy = true;
+    try {
+      const result = look(root, runners, { by: 'watch', replay: opts.replay === true });
+      if (typeof opts.onLook === 'function') opts.onLook(result);
+    } catch (err) {
+      if (typeof opts.onError === 'function') opts.onError(err);
+    } finally {
+      busy = false;
+    }
+  };
+  const tick = () => {
+    if (busy) return;
+    const p = pending(root);
+    // Nothing to compare against yet: this first look is the starting point.
+    if (p.first) return doLook();
+    if (!p.changed) {
+      seen = null;
+      return;
+    }
+    if (p.signature !== seen) {
+      seen = p.signature;
+      since = Date.now();
+      return;
+    }
+    if (Date.now() - since >= quietMs) doLook();
+  };
+  const timer = setInterval(tick, intervalMs);
+  if (timer.unref && opts.unref) timer.unref();
+  // Now, not one interval from now: a change made in the first seconds after
+  // the page opened would otherwise land in the starting point and never be
+  // seen as a change at all.
+  tick();
+  return {
+    tick: tick,
+    stop() {
+      clearInterval(timer);
+    },
+  };
+}
+
+// What a broken flow says when the app itself did not answer - which is not
+// evidence either way about the fix.
+const APP_DID_NOT_ANSWER = /could not be opened|took too long to load|net::ERR|ECONNREFUSED/i;
+
+/**
+ * The second half of the loop: someone says a finding is fixed; prove it.
+ *
+ * The check that found it is run again - always, whatever else changed - and
+ * so is every check the changes since the last look call for, so a fix that
+ * breaks something else is caught in the same step. The verdict:
+ *
+ *   fixed               the check ran, and the finding is not there
+ *   still open          the check ran, and the finding is still there
+ *   gone with its file  the file it pointed at was deleted - not the same as fixed
+ *   could not confirm   the check did not run, or the app did not answer
+ *
+ * A fix is never assumed from a changed file. Every attempt is kept.
+ */
+function recheck(root, runners, id, options) {
+  const paths = store.pathsFor(root);
+  const target = dash.buildState(root).findings.find((f) => f.id === id);
+  if (!target) return { found: false };
+
+  const result = look(root, runners, { by: 'recheck', force: [target.check], replay: true });
+  const own = result.plan.find((s) => s.id === target.check);
+  const still = result.after.findings.find((f) => f.id === id);
+  let verdict;
+  let why = '';
+  if (!own || !/^ran/.test(own.state)) {
+    verdict = 'could not confirm';
+    why = own ? own.state : 'the check that found it did not run';
+  } else if (still && target.check === 'regression' && APP_DID_NOT_ANSWER.test(still.detail || '')) {
+    verdict = 'could not confirm';
+    why = 'your app did not answer while the flow was replayed - start it and re-check';
+  } else if (still) {
+    verdict = 'still open';
+    why = still.detail || '';
+  } else if (result.removed.some((f) => f.id === id)) {
+    verdict = 'gone with its file';
+    why = 'the file it pointed at was deleted, which is not the same as fixing it';
+  } else {
+    verdict = 'fixed';
+  }
+  // Problems that appeared with this fix. The finding itself is never one of
+  // them: it was there before, so it cannot be new.
+  const newProblems = result.fresh.map((f) => ({
+    id: f.id, check: f.check, severity: f.severity, status: f.status, where: f.where, headline: f.headline,
+  }));
+  const attempt = {
+    id: id,
+    at: new Date().toISOString(),
+    check: target.check,
+    where: target.where,
+    headline: target.headline,
+    verdict: verdict,
+    why: why,
+    newProblems: newProblems,
+  };
+  try {
+    fs.appendFileSync(paths.fixes, JSON.stringify(attempt) + '\n', 'utf8');
+  } catch (err) {
+    attempt.saveError = err.message;
+  }
+  return Object.assign({ found: true, target: target, look: result }, attempt);
+}
+
+module.exports = { look: look, pending: pending, startWatch: startWatch, recheck: recheck };

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,332 @@
+// 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)
+//     code-findings.json  the last frontend code read (kryptheon code)
+//     config.json     which checks are switched on (the dashboard)
+//     snapshot.json   a hash of each project file, to tell what changed
+//     changes.jsonl   one line per change Kryptheon noticed, and what it ran
+//     fixes.jsonl     every re-check of a finding someone tried to fix, and its verdict
+//
+// 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',
+  codeFindings: 'code-findings.json',
+  config: 'config.json',
+  snapshot: 'snapshot.json',
+  changes: 'changes.jsonl',
+  fixes: 'fixes.jsonl',
+};
+
+// 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),
+    codeFindings: path.join(dir, FILES.codeFindings),
+    config: path.join(dir, FILES.config),
+    snapshot: path.join(dir, FILES.snapshot),
+    changes: path.join(dir, FILES.changes),
+    fixes: path.join(dir, FILES.fixes),
+  };
+}
+
+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,
+};