kryptheon 0.1.6 → 0.1.7

package/bin/kryptheon.js

@@ -11,6 +11,8 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
+const os = require('os');
+const secrets = require(require('path').join(__dirname, '..', 'kryptheon-secrets.js'));
 const replay = require('../kryptheon-replay.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
@@ -33,6 +35,16 @@ function nodeIsTooOld(version) {
   return false;
 }
 
+// Read from the package rather than repeated here, so it cannot go stale.
+// Someone filing a bug report has to be able to say which version they have.
+function packageVersion() {
+  try {
+    return require(path.join(PACKAGE_DIR, 'package.json')).version || 'unknown';
+  } catch (err) {
+    return 'unknown';
+  }
+}
+
 function usage() {
   console.log('');
   console.log('  kryptheon - record and check your app');
@@ -43,6 +55,7 @@ function usage() {
   console.log('  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('');
 }
 
@@ -595,15 +608,44 @@ 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() {
+  const added = secrets.updateGitignore(USER_DIR);
+  if (!added.length) return;
+  console.log('  Added to .gitignore: ' + added.join(', '));
+  console.log('');
+}
+
 function reportSecrets(replacements) {
   if (!replacements || !replacements.length) return;
+  const names = replacements.map((item) => item.envName);
   console.log('  What you typed into the password box was not saved in the test.');
   console.log('');
-  console.log('  Put it in a file called .env next to your tests, like this:');
-  for (const item of replacements) {
-    console.log('    ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here');
+
+  // Written rather than described. Asked to make the file themselves, most
+  // people on Windows reach for Notepad or Out-File, both of which add a byte
+  // order mark that makes the first line unreadable.
+  const hasEnv = fs.existsSync(path.join(USER_DIR, '.env'));
+  const example = hasEnv ? null : secrets.writeEnvExample(USER_DIR, names);
+  if (example) {
+    console.log('  A file called .env.example has been written here:');
+    for (const name of names) console.log('    ' + name + '=yourpassword');
+    console.log('');
+    console.log('  Put your real password in it and save it as .env, in this folder.');
+  } else {
+    console.log('  Before this can be checked, put it in a file called .env next to');
+    console.log('  your tests, like this:');
+    for (const item of replacements) {
+      console.log('    ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here');
+    }
   }
   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('  rather than sign in with a blank password.');
+  console.log('');
   console.log('  Keep .env out of version control - it holds the real value.');
   console.log('');
 }
@@ -699,6 +741,7 @@ async function finaliseRecording(outFile, context) {
     console.log('');
 
     reportSecrets(secrets);
+    keepArtefactsOutOfGit();
     await offerToDropLogout(named);
     reportReplayRisks(named);
 
@@ -898,6 +941,7 @@ function triageSpecs() {
   const notRecordings = [];
   const runnable = [];
   const withSecrets = [];
+  const missingSecrets = [];
 
   for (const name of listSpecFiles()) {
     const full = path.join(TESTS_DIR, name);
@@ -930,6 +974,18 @@ function triageSpecs() {
     if (replay.scrubSecrets(source).replacements.length) {
       withSecrets.push({ name: name, fields: replay.scrubSecrets(source).replacements });
     }
+
+    // A recording that falls back to an empty password is not run at all. It
+    // would sign in blank, fail, and send the reader looking at their app.
+    const needed = secrets.requiredSecrets(source);
+    const absent = needed.length
+      ? secrets.missingSecrets(needed, { envFile: secrets.envFileFor(USER_DIR) })
+      : [];
+    if (absent.length) {
+      missingSecrets.push({ name: name, names: absent });
+      continue;
+    }
+
     runnable.push(name);
   }
 
@@ -938,6 +994,7 @@ function triageSpecs() {
     notRecordings: notRecordings,
     runnable: runnable,
     withSecrets: withSecrets,
+    missingSecrets: missingSecrets,
   };
 }
 
@@ -974,6 +1031,8 @@ function check(options) {
     console.log('');
     return 1;
   }
+  keepArtefactsOutOfGit();
+
   const triage = triageSpecs();
 
   for (const name of triage.repaired) {
@@ -989,6 +1048,14 @@ function check(options) {
     console.log('  Re-record it to have the password moved into .env automatically.');
   }
 
+  for (const item of triage.missingSecrets) {
+    console.log('');
+    const example = fs.existsSync(path.join(USER_DIR, '.env.example')) ? '.env.example' : null;
+    for (const line of secrets.missingSecretLines(path.join('tests', item.name), item.names, { examplePath: example })) {
+      console.log(line);
+    }
+  }
+
   for (const name of triage.notRecordings) {
     console.log('');
     console.log('  Skipped ' + path.join('tests', name));
@@ -1001,8 +1068,13 @@ function check(options) {
     console.log('');
     console.log('  Nothing could be checked.');
     console.log('');
-    console.log('  None of the files in tests/ is a usable recording.');
-    console.log('  Record one with:  kryptheon record <url>');
+    if (triage.missingSecrets.length) {
+      console.log('  Every recording here needs a password that is not set yet.');
+      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('');
     return 1;
   }
@@ -1013,10 +1085,34 @@ function check(options) {
   // cannot produce diagnostics can never be counted as passing.
   const only = triage.runnable.map((name) => path.join('tests', name).split(path.sep).join('/'));
   if (quiet) process.env.KRYPTHEON_QUIET = '1';
+
+  // Debug signatures. The workers cannot print: Playwright pipes their
+  // descriptors and hands the output to reporter stdio hooks that this
+  // reporter does not implement, so it is dropped. They write to this file
+  // instead and it is printed here, on stderr, where the reporter's own
+  // output on stdout is left completely alone.
+  const signatures = require(path.join(PACKAGE_DIR, 'kryptheon-signature.js'));
+  let sink = null;
+  if (signatures.signatureEnabled()) {
+    sink = path.join(os.tmpdir(), 'kryptheon-signature-' + process.pid + '.jsonl');
+    process.env[signatures.SINK_ENV] = sink;
+  }
+
   const status = runPlaywright(['test', '--config', CONFIG].concat(only)).status;
 
+  if (sink) signatures.drainSignatures(sink);
+
   // Without this, a green summary could still hide a recording that checked
   // nothing at all.
+  if (triage.missingSecrets.length) {
+    const many = triage.missingSecrets.length > 1;
+    console.log(
+      '  Note: ' + triage.missingSecrets.length + ' recording' + (many ? 's were' : ' was') +
+        ' skipped because a password is not set.'
+    );
+    console.log('');
+  }
+
   if (triage.notRecordings.length) {
     const many = triage.notRecordings.length > 1;
     console.log(
@@ -1025,7 +1121,9 @@ function check(options) {
     );
     console.log('');
   }
-  return status;
+  // Skipped for a missing password is not a pass. The fix is one file away,
+  // and reporting zero would let it be mistaken for a clean run.
+  return status || (triage.missingSecrets.length ? 1 : 0);
 }
 
 // --- setup-ai ---------------------------------------------------------------
@@ -1291,6 +1389,11 @@ async function main() {
     case 'accept':
       return finishWith(accept(rest.join(' ').trim()));
       break;
+    case '-v':
+    case '--version':
+    case 'version':
+      console.log(packageVersion());
+      return finishWith(0);
     case undefined:
     case '-h':
     case '--help':
@@ -1308,6 +1411,7 @@ async function main() {
 
 // Exported so the naming logic can be checked without opening a browser.
 module.exports = {
+  packageVersion: packageVersion,
   humanisePath: humanisePath,
   nameFromTitle: nameFromTitle,
   deriveTestName: deriveTestName,
@@ -1324,6 +1428,7 @@ module.exports = {
   record: record,
   finaliseRecording: finaliseRecording,
   takeOutSecrets: takeOutSecrets,
+  reportSecrets: reportSecrets,
   reportReplayRisks: reportReplayRisks,
   offerToDropLogout: offerToDropLogout,
   noWindowLines: noWindowLines,

package/kryptheon-fixture.js

@@ -20,6 +20,7 @@ const base = require('@playwright/test');
 // Reuse the reporter's host-stripping so a baseline stores exactly the shape
 // the reporter prints.
 const { requestPath } = require('./kryptheon-reporter.js');
+const signature = require('./kryptheon-signature.js');
 
 const MAX_ITEMS = 5; // keep the failure block readable
 
@@ -53,10 +54,14 @@ function baselineKey(specFile, title) {
 function readBaselines(file) {
   let raw;
   try {
-    raw = fs.readFileSync(file, 'utf8');
+    raw = fs.readFileSync(file, { encoding: 'utf8' });
   } catch (e) {
     return {};
   }
+  // An editor that saved the file with a byte order mark would otherwise make
+  // JSON.parse throw, and every baseline would silently vanish - which reads as
+  // "all clear" on the next run rather than as the problem it is.
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -69,7 +74,9 @@ function readBaselines(file) {
 
 function saveBaselines(file, all) {
   try {
-    fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n', 'utf8');
+    // Explicit, and without a byte order mark: this file is read back by the
+    // same code and by people, and a mismatch would look like the app changed.
+    fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n', { encoding: 'utf8' });
     return true;
   } catch (e) {
     return false; // diagnostics must never become a second failure
@@ -112,12 +119,16 @@ function toStoredErrors(list) {
 }
 
 function normalisedEntry(current) {
-  return {
+  const stored = {
     url: current.url,
     title: current.title,
     consoleErrors: toStoredErrors(current.consoleErrors),
     failedRequests: toStoredRequests(current.failedRequests),
   };
+  // Only when there is one. A run whose capture failed must not write an empty
+  // signature over a good one, or the next run would report everything as gone.
+  if (current.signature) stored.signature = current.signature;
+  return stored;
 }
 
 function writeBaseline(file, key, entry) {
@@ -170,12 +181,17 @@ function normaliseTitle(value) {
   return String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
 }
 
-// Only the address and title decide pass or fail. Browser noise changing is
-// not on its own a regression.
+// The address, the title, and what the page ended up showing decide pass or
+// fail. Browser noise changing is not on its own a regression.
 function compareBaselines(previous, current) {
   const urlChanged = normaliseUrl(previous.url) !== normaliseUrl(current.url);
   const titleChanged = normaliseTitle(previous.title) !== normaliseTitle(current.title);
-  if (!urlChanged && !titleChanged) return null;
+  if (!urlChanged && !titleChanged) {
+    // Nothing moved in the address bar. This is the case the address and title
+    // alone cannot see: a single-page app with a catch-all route lands on the
+    // same URL under the same title whether the flow worked or not.
+    return signature.compareSignatures(previous.signature, current.signature);
+  }
 
   const what =
     urlChanged && titleChanged ? 'the page address and title changed'
@@ -213,6 +229,17 @@ function newObservations(current, previous) {
   };
 }
 
+// Adds a signature to an accepted baseline that predates the feature, without
+// touching anything else about it - including when it was recorded, which is
+// what the failure report means by "this last worked at".
+function upgradeBaseline(file, key, sig) {
+  const all = readBaselines(file);
+  const entry = all[key];
+  if (!entry || typeof entry !== 'object' || entry.signature || !sig) return false;
+  entry.signature = sig;
+  return saveBaselines(file, all);
+}
+
 // The whole decision in one call: create on first sight, otherwise compare.
 function applyBaseline(file, key, current) {
   const previous = readBaselines(file)[key];
@@ -221,7 +248,16 @@ function applyBaseline(file, key, current) {
     return { status: 'created', message: null };
   }
   const message = compareBaselines(previous, current);
-  return message ? { status: 'changed', message: message } : { status: 'match', message: null };
+  if (message) return { status: 'changed', message: message };
+
+  // A baseline from before signatures existed passes on address and title, and
+  // learns its signature here. Doing it on a pass rather than up front means an
+  // upgraded project never fails on its first run under the new version.
+  if (!previous.signature && current.signature) {
+    upgradeBaseline(file, key, current.signature);
+    return { status: 'learned', message: null };
+  }
+  return { status: 'match', message: null };
 }
 
 // ---------------------------------------------------------------------------
@@ -261,6 +297,9 @@ const test = base.test.extend({
         await testInfo.attach('kryptheon-observations', {
           body: JSON.stringify({
             url: url,
+            // What was actually on screen when it gave up. On a flow that
+            // stopped half way this is the most useful line in the report.
+            pageShowed: signature.describeSignature(captured),
             failedRequests: fresh.failedRequests.slice(0, MAX_ITEMS),
             consoleErrors: fresh.consoleErrors.slice(0, MAX_ITEMS),
           }),
@@ -273,6 +312,29 @@ const test = base.test.extend({
 
     await use(page);
 
+    // Read the page before anything else looks at the outcome. A test that
+    // failed is exactly the one where knowing what was on screen matters most,
+    // so this runs whether it passed or not. It is null when the page could
+    // not be read at all, and a null is never treated as a difference - not
+    // knowing what the page showed is not evidence that it changed.
+    //
+    // Printed only when asked for, and handed to the CLI through a file:
+    // Playwright pipes this worker's descriptors and gives whatever comes out
+    // to reporter stdio hooks that this reporter does not implement, so
+    // anything printed from here is dropped before it reaches a terminal.
+    const captured = await signature.collectSignature(page, failedRequests);
+    if (signature.signatureEnabled()) signature.recordSignature(testInfo.title, captured);
+
+    // Said once per run by the reporter, not once per test: it is a fact about
+    // the app, and repeating it for every recording would be noise.
+    if (captured && captured.guessedEncoding) {
+      try {
+        await testInfo.attach('kryptheon-encoding', { body: 'guessed', contentType: 'text/plain' });
+      } catch (e) {
+        /* a note, never a second failure */
+      }
+    }
+
     // The test's own assertions decide first. A test that already failed keeps
     // its own error, and never contributes a baseline.
     if (testInfo.status !== testInfo.expectedStatus) {
@@ -280,7 +342,7 @@ const test = base.test.extend({
       return;
     }
 
-    // Passed: capture what the page ended up as, noise included.
+    // Passed: keep what the page ended up as, noise included.
     let current = null;
     try {
       current = {
@@ -288,6 +350,7 @@ const test = base.test.extend({
         title: normaliseTitle(await page.title()),
         consoleErrors: consoleErrors,
         failedRequests: failedRequests,
+        signature: captured,
       };
     } catch (e) {
       current = null; // page closed by the test - leave any baseline untouched
@@ -320,5 +383,6 @@ module.exports = {
   normaliseTitle: normaliseTitle,
   compareBaselines: compareBaselines,
   applyBaseline: applyBaseline,
+  upgradeBaseline: upgradeBaseline,
   BASELINE_FILE: BASELINE_FILE,
 };

package/kryptheon-reporter.js

@@ -189,8 +189,11 @@ function translate(message) {
       return l.indexOf('Baseline changed:') !== -1;
     });
     const head = lines[headIndex].replace(/^.*Baseline changed:\s*/, '');
+    // An allowlist, so a stack trace that happens to follow the message can
+    // never leak into the report. Address and title come from the original
+    // baseline; the rest name what the page stopped or started showing.
     const details = lines.slice(headIndex + 1).filter(function (l) {
-      return /^(Address|Title) (was|now):/.test(l);
+      return /^(Address|Title) (was|now):/.test(l) || /^(Headings|Buttons and links|Form fields) that are (gone|new):/.test(l) || /^Requests that failed this time:/.test(l);
     });
     return {
       reason: capitalise(head),
@@ -406,6 +409,9 @@ function whereToLookLines(obs) {
   const lines = [];
 
   if (obs.url) lines.push('     - Browser was on: ' + obs.url);
+  // Where the flow actually got to, in words. The whole signature stays behind
+  // KRYPTHEON_DEBUG_SIGNATURE for when that much detail is wanted.
+  if (obs.pageShowed) lines.push('     - Page showed: ' + obs.pageShowed);
 
   for (const req of uniq(obs.failedRequests).slice(0, 5)) {
     const meaning = describeStatus(req.status);
@@ -568,6 +574,8 @@ class KryptheonReporter {
     this.previousRuns = [];
     this.records = [];
     this.startedAt = new Date();
+    // Set by any test whose page never said what encoding it was in.
+    this.sawGuessedEncoding = false;
   }
 
   onBegin() {
@@ -624,6 +632,9 @@ class KryptheonReporter {
   }
 
   onTestEnd(test, result) {
+    if ((result.attachments || []).some(function (a) { return a.name === 'kryptheon-encoding'; })) {
+      this.sawGuessedEncoding = true;
+    }
     const status =
       result.status === 'passed' ? 'passed' : result.status === 'skipped' ? 'skipped' : 'failed';
     const timestamp = (result.startTime instanceof Date ? result.startTime : new Date()).toISOString();
@@ -787,6 +798,15 @@ class KryptheonReporter {
       '\nSummary: ' + passed + ' working, ' + failed + ' broken.\n' +
       'History saved to ' + path.basename(HISTORY_FILE) + '\n\n'
     );
+
+    // Once per run, not once per test: it is one fact about the app, and
+    // repeating it under every recording would bury the reports themselves.
+    if (this.sawGuessedEncoding) {
+      process.stdout.write(
+        'Note: this page does not declare a character encoding, so text may look\n' +
+        'garbled here and in the browser. Add <meta charset="utf-8"> to the page.\n\n'
+      );
+    }
   }
 }
 

package/kryptheon-secrets.js

@@ -0,0 +1,191 @@
+// Which environment variables a recording needs, and whether they are there.
+//
+// Why this exists. When a password is typed during recording it is taken out
+// of the spec and replaced with `process.env.KRYPTHEON_PASSWORD || ''`. If
+// nobody ever creates the .env file, that expression quietly evaluates to an
+// empty string: the run submits a blank password, the login fails for the most
+// boring reason imaginable, and the report blames the app. Two hours can go
+// into that before anyone thinks to check the environment.
+//
+// So the names are read out of the spec before anything runs, and a recording
+// whose secret is missing is not run at all - a blank password is never sent.
+
+const fs = require('fs');
+const path = require('path');
+
+// The exact shape the scrubber writes. Anything else in the file that happens
+// to mention process.env is the author's own business and left alone.
+const SECRET_USE = /process\.env\.([A-Z][A-Z0-9_]*)\s*\|\|\s*(['"])\2/g;
+
+/** Every environment variable this recording falls back to an empty string for. */
+function requiredSecrets(source) {
+  const out = [];
+  const seen = Object.create(null);
+  let match;
+  SECRET_USE.lastIndex = 0;
+  while ((match = SECRET_USE.exec(String(source || '')))) {
+    const name = match[1];
+    if (seen[name]) continue;
+    seen[name] = true;
+    out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Reads a .env file into a plain object. Never throws: a missing file simply
+ * means nothing was defined there.
+ *
+ * Values are not expanded or unescaped beyond stripping one layer of quotes -
+ * this only has to answer "is it set", and guessing at more would be a second
+ * dialect of .env for people to trip over.
+ */
+function readEnvFile(file) {
+  const out = Object.create(null);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    return out;
+  }
+  // A byte order mark would otherwise become part of the first name.
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+  for (const line of raw.split('\n')) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!match) continue;
+    out[match[1]] = match[2].replace(/^(['"])([\s\S]*)\1$/, '$2');
+  }
+  return out;
+}
+
+/** A value that is present and not blank. An empty variable is not set. */
+function isSet(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+/**
+ * Which of the names a recording needs are missing, looking at both the real
+ * environment and the project's .env - the same two places the test itself
+ * will look when it runs.
+ */
+function missingSecrets(names, options) {
+  const opts = options || {};
+  const env = opts.env || process.env;
+  const fromFile = opts.envFile ? readEnvFile(opts.envFile) : {};
+  return (names || []).filter((name) => !isSet(env[name]) && !isSet(fromFile[name]));
+}
+
+/**
+ * How to create the file without a byte order mark.
+ *
+ * PowerShell's own `Out-File -Encoding utf8` writes one, and so does Notepad,
+ * which is why this spells out a command that does not rather than leaving it
+ * to whatever the person reaches for first.
+ */
+function howToWriteEnv(names, platform) {
+  const line = names.map((name) => name + '=yourpassword').join('\\n');
+  if ((platform || process.platform) === 'win32') {
+    return [
+      '  In PowerShell, this writes it without a byte order mark:',
+      '    [IO.File]::WriteAllText("$PWD\\.env", "' + line + '`n")',
+      '',
+      '  Avoid Out-File and Notepad here: both add a mark that makes the first',
+      '  line unreadable, and the password would silently come out blank.',
+    ];
+  }
+  return ['  For example:', "    printf '" + line.replace(/\\n/g, "\\n") + "\\n' > .env"];
+}
+
+/** What to tell somebody who has not created the file yet. */
+function missingSecretLines(specName, names, options) {
+  const opts = options || {};
+  const many = names.length > 1;
+  const lines = [
+    '  Skipped ' + specName,
+    '  This recording needs a password' + (many ? ' and other secrets' : '') + ', and there is none set.',
+    '',
+  ];
+  if (opts.examplePath) {
+    lines.push('  There is a ' + opts.examplePath + ' here already. Put the real value in it');
+    lines.push('  and save it as .env, in the same folder.');
+  } else {
+    lines.push('  Create a .env file in this folder containing:');
+    for (const name of names) lines.push('    ' + name + '=yourpassword');
+  }
+  lines.push('');
+  for (const line of howToWriteEnv(names, opts.platform)) lines.push(line);
+  lines.push('');
+  lines.push('  Without it the recording would sign in with a blank password and');
+  lines.push('  fail for a reason that has nothing to do with your app, so it was');
+  lines.push('  not run. Keep .env out of version control.');
+  return lines;
+}
+
+/**
+ * Writes .env.example so nobody has to get the encoding right by hand.
+ *
+ * Plain UTF-8, no byte order mark. Never overwrites: the file may already hold
+ * names from an earlier recording, and clobbering it would lose them.
+ */
+function writeEnvExample(dir, names) {
+  const file = path.join(dir, '.env.example');
+  if (fs.existsSync(file)) return null;
+  const body = (names || []).map((name) => name + '=yourpassword').join('\n') + '\n';
+  try {
+    fs.writeFileSync(file, body, { encoding: 'utf8' });
+    return file;
+  } catch (e) {
+    return null; // a convenience, never a reason to fail a recording
+  }
+}
+
+// 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/'];
+
+/**
+ * Adds the missing entries to an existing .gitignore. Returns what it added.
+ *
+ * Only touches a file that is already there - creating one in a project that
+ * has deliberately gone without is not this tool's decision to make.
+ */
+function updateGitignore(dir, entries) {
+  const file = path.join(dir, '.gitignore');
+  let raw;
+  try {
+    raw = fs.readFileSync(file, { encoding: 'utf8' });
+  } catch (e) {
+    return [];
+  }
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+  const present = new Set(
+    raw
+      .split('\n')
+      .map((line) => line.trim().replace(/^\/+/, '').replace(/\/+$/, ''))
+      .filter(Boolean),
+  );
+  const wanted = entries || GITIGNORE_ENTRIES;
+  const missing = wanted.filter((entry) => !present.has(entry.replace(/\/+$/, '')));
+  if (!missing.length) return [];
+  const needsNewline = raw.length && !raw.endsWith('\n');
+  const block = (needsNewline ? '\n' : '') + '\n# kryptheon\n' + missing.join('\n') + '\n';
+  try {
+    fs.appendFileSync(file, block, { encoding: 'utf8' });
+    return missing;
+  } catch (e) {
+    return [];
+  }
+}
+
+module.exports = {
+  requiredSecrets: requiredSecrets,
+  readEnvFile: readEnvFile,
+  missingSecrets: missingSecrets,
+  missingSecretLines: missingSecretLines,
+  howToWriteEnv: howToWriteEnv,
+  writeEnvExample: writeEnvExample,
+  updateGitignore: updateGitignore,
+  GITIGNORE_ENTRIES: GITIGNORE_ENTRIES,
+  isSet: isSet,
+  envFileFor: (dir) => path.join(dir, '.env'),
+};

package/kryptheon-signature.js

@@ -0,0 +1,530 @@
+// A "DOM signature": a small, plain description of what a page ended up
+// showing. Not a screenshot and not a pixel comparison - just the words a
+// person would use to say what is on screen.
+//
+// Why it exists. Automatic baselines currently remember the final address and
+// the page title. In a single-page app with a catch-all route those both stay
+// the same when a flow breaks: a login that no longer logs anyone in still
+// lands on the same URL with the same title, so the baseline sees no
+// difference and the run is reported as fine. The signature is the thing that
+// would have noticed - the headings, buttons, links and fields on the page
+// change even when the address does not.
+//
+// STEP ONE ONLY. This module captures and prints. Nothing here is written to a
+// baseline, compared against anything, or allowed to affect whether a test
+// passes. Collection does not even run unless KRYPTHEON_DEBUG_SIGNATURE=1.
+
+const fs = require('fs');
+
+const MAX_TEXT = 80;
+const MAX_ACTIONS = 40;
+
+// ---------------------------------------------------------------------------
+// Pure helpers. No browser, no filesystem - so the unit checks can exercise
+// them directly.
+// ---------------------------------------------------------------------------
+
+/**
+ * One line, no digits, capped.
+ *
+ * The digits are the important part. "Savings rate 0%" and "Savings rate 12%"
+ * are the same page as far as this is concerned, and a signature that treated
+ * them as different would report a regression every time a number moved.
+ */
+function normaliseText(value) {
+  const line = String(value == null ? '' : value)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\d+/g, '#');
+  return line.length > MAX_TEXT ? line.slice(0, MAX_TEXT) : line;
+}
+
+function uniqueSorted(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const item of list || []) {
+    const text = normaliseText(item);
+    if (!text || seen[text]) continue;
+    seen[text] = true;
+    out.push(text);
+  }
+  return out.sort();
+}
+
+function uniqueInOrder(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const item of list || []) {
+    const text = normaliseText(item);
+    if (!text || seen[text]) continue;
+    seen[text] = true;
+    out.push(text);
+  }
+  return out;
+}
+
+/**
+ * Path only: no host, no query string, no fragment.
+ *
+ * Deliberately not the reporter's requestPath, which keeps the query string so
+ * a person reading a failure can see it. A signature is stored and compared,
+ * and query strings routinely carry tokens, ids and search terms.
+ */
+function signaturePath(requestUrl) {
+  let s = String(requestUrl == null ? '' : requestUrl);
+  try {
+    s = new URL(s).pathname || '/';
+  } catch (e) {
+    // Not absolute: strip any scheme://host by hand, then the query and hash.
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]*/, '');
+    const hash = s.indexOf('#');
+    if (hash !== -1) s = s.slice(0, hash);
+    const query = s.indexOf('?');
+    if (query !== -1) s = s.slice(0, query);
+  }
+  return s || '/';
+}
+
+/** Method, path and status. Never a query string, never a body. */
+function toSignatureRequests(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const req of list || []) {
+    const status = Number(req && req.status);
+    if (!(status >= 400 && status <= 599)) continue;
+    const entry = {
+      method: (req && req.method) || 'GET',
+      path: signaturePath((req && req.url) != null ? req.url : req && req.path),
+      status: status,
+    };
+    const key = entry.method + ' ' + entry.path + ' ' + entry.status;
+    if (seen[key]) continue;
+    seen[key] = true;
+    out.push(entry);
+  }
+  return out;
+}
+
+/** Assembles the signature from raw, page-shaped input. */
+function buildSignature(raw) {
+  const input = raw || {};
+  return {
+    headings: uniqueInOrder(input.headings),
+    actions: uniqueSorted(input.actions).slice(0, MAX_ACTIONS),
+    fields: uniqueSorted(input.fields),
+    failedRequests: toSignatureRequests(input.failedRequests),
+  };
+}
+
+/**
+ * One plain line saying what was on screen, for a failure report.
+ *
+ * Deliberately not the JSON. Somebody reading a failure wants "it was still on
+ * the sign-in page", not a structure to parse; the whole object stays behind
+ * the debug flag for when the detail is actually wanted.
+ */
+function describeSignature(signature) {
+  if (!signature || typeof signature !== 'object') return null;
+  const headings = (signature.headings || []).slice(0, 2);
+  const actions = (signature.actions || []).slice(0, 3);
+  const fields = (signature.fields || []).slice(0, 3);
+
+  let what;
+  if (headings.length) what = quoteList(headings);
+  else if (fields.length) what = 'a form';
+  else if (actions.length) what = 'no headings';
+  else return null; // nothing readable was on the page
+
+  const parts = [];
+  if (actions.length) parts.push(actions.join(', '));
+  if (!headings.length && fields.length) parts.push(fields.join(', '));
+  return parts.length ? what + ' with ' + parts.join('; ') : what;
+}
+
+// ---------------------------------------------------------------------------
+// Comparing two signatures.
+// ---------------------------------------------------------------------------
+
+/**
+ * What left and what arrived, as sets.
+ *
+ * Sets, not sequences: a page that moves its buttons around is the same page.
+ * Only something appearing or disappearing is worth stopping a run over.
+ */
+function setDifference(before, after) {
+  const had = new Set(before || []);
+  const has = new Set(after || []);
+  return {
+    gone: [...had].filter((item) => !has.has(item)),
+    added: [...has].filter((item) => !had.has(item)),
+  };
+}
+
+function requestLabel(req) {
+  return (req.method || 'GET') + ' ' + req.path + ' ' + req.status;
+}
+
+function quoteList(items) {
+  return items.map((item) => '"' + item + '"').join(', ');
+}
+
+/**
+ * Compares a stored signature with what this run saw. Returns a message
+ * describing the change, or null when nothing worth failing over moved.
+ *
+ * Returns null when either side is missing. A baseline recorded before this
+ * feature existed has no signature and must keep working on address and title
+ * alone, and a run whose capture failed knows nothing - neither is evidence of
+ * a regression, and treating them as one would fail every old project on
+ * upgrade.
+ */
+function compareSignatures(previous, current) {
+  if (!previous || typeof previous !== 'object') return null;
+  if (!current || typeof current !== 'object') return null;
+
+  const headings = setDifference(previous.headings, current.headings);
+  const actions = setDifference(previous.actions, current.actions);
+  const fields = setDifference(previous.fields, current.fields);
+
+  // Only new failures matter. A 500 that has been fixed since the baseline was
+  // taken is an improvement, and failing the run for it would be perverse.
+  const knownRequests = new Set((previous.failedRequests || []).map(requestLabel));
+  const newRequests = (current.failedRequests || [])
+    .map(requestLabel)
+    .filter((label) => !knownRequests.has(label));
+
+  const moved =
+    headings.gone.length ||
+    headings.added.length ||
+    actions.gone.length ||
+    actions.added.length ||
+    fields.gone.length ||
+    fields.added.length ||
+    newRequests.length;
+  if (!moved) return null;
+
+  const lines = ['Baseline changed: the page ended up somewhere different than before.'];
+  if (headings.gone.length) lines.push('Headings that are gone: ' + quoteList(headings.gone));
+  if (headings.added.length) lines.push('Headings that are new: ' + quoteList(headings.added));
+  if (actions.gone.length) lines.push('Buttons and links that are gone: ' + quoteList(actions.gone));
+  if (actions.added.length) lines.push('Buttons and links that are new: ' + quoteList(actions.added));
+  if (fields.gone.length) lines.push('Form fields that are gone: ' + quoteList(fields.gone));
+  if (fields.added.length) lines.push('Form fields that are new: ' + quoteList(fields.added));
+  if (newRequests.length) lines.push('Requests that failed this time: ' + newRequests.join(', '));
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// The browser side.
+// ---------------------------------------------------------------------------
+
+// Runs inside the page. Written as a single self-contained function because
+// page.evaluate serialises it across the wire - it cannot close over anything
+// in this file.
+function readPage() {
+  const isVisible = (el) => {
+    if (!el) return false;
+    // checkVisibility covers display:none, visibility:hidden, content-visibility
+    // and the hidden attribute in one call where it exists.
+    if (typeof el.checkVisibility === 'function') {
+      if (!el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true })) return false;
+    } else {
+      const style = window.getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden') return false;
+    }
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 || rect.height > 0;
+  };
+
+  const text = (el) => (el && el.innerText ? el.innerText : (el && el.textContent) || '');
+
+  const headings = [];
+  for (const el of document.querySelectorAll('h1, h2, h3')) {
+    if (isVisible(el)) headings.push(text(el));
+  }
+
+  const actions = [];
+  const actionSelector =
+    'button, a[href], [role="button"], [role="link"], input[type="submit"], input[type="button"]';
+  for (const el of document.querySelectorAll(actionSelector)) {
+    if (!isVisible(el)) continue;
+    const label =
+      el.getAttribute('aria-label') ||
+      (el.tagName === 'INPUT' ? el.value : '') ||
+      text(el) ||
+      el.getAttribute('title') ||
+      '';
+    if (label) actions.push(label);
+  }
+
+  const fields = [];
+  for (const el of document.querySelectorAll('input, select, textarea')) {
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    if (type === 'hidden' || type === 'submit' || type === 'button') continue;
+    if (!isVisible(el)) continue;
+    // What a person would call this field, in the order they would find it.
+    let label = '';
+    if (el.id) {
+      const tag = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+      if (tag) label = text(tag);
+    }
+    if (!label && el.closest('label')) label = text(el.closest('label'));
+    if (!label) label = el.getAttribute('aria-label') || '';
+    if (!label) label = el.getAttribute('placeholder') || '';
+    if (!label) label = el.getAttribute('name') || '';
+    if (!label) label = el.id || '';
+    if (label) fields.push(label);
+  }
+
+  // A page that never declares its encoding is decoded by guesswork, and the
+  // text really does come out as mojibake - on screen and therefore in here.
+  // That is the app's bug, not this tool's, but it is worth saying once.
+  const declared = !!document.querySelector('meta[charset], meta[http-equiv="Content-Type" i]');
+  const guessedEncoding = !declared && String(document.characterSet || '').toUpperCase() !== 'UTF-8';
+
+  return { headings: headings, actions: actions, fields: fields, guessedEncoding: guessedEncoding };
+}
+
+/** True only for an explicit opt-in. */
+function signatureEnabled(env) {
+  const source = env || process.env;
+  return String(source.KRYPTHEON_DEBUG_SIGNATURE || '') === '1';
+}
+
+// How often the page is read while waiting for it to hold still.
+const SETTLE_GAP = 200;
+// How long it has to hold still before the reading is believed. Measured, not
+// guessed: against a page that renders 1.5s after its request answers, 700ms
+// still read the screen from before the click and 1200ms read the right one.
+const SETTLE_QUIET = 1200;
+// Never spend longer than this on one signature, however restless the page.
+const SETTLE_BUDGET = 4000;
+// A pending request is worth waiting out first, but not for the whole budget.
+const NETWORK_BUDGET = 1500;
+
+/** Two readings of the same page, exactly. */
+function sameSignature(a, b) {
+  if (!a || !b) return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+async function pause(page, ms) {
+  try {
+    await page.waitForTimeout(ms);
+  } catch (e) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+async function readSignature(page, failedRequests) {
+  const raw = await page.evaluate(readPage);
+  const signature = buildSignature({
+    headings: raw.headings,
+    actions: raw.actions,
+    fields: raw.fields,
+    failedRequests: failedRequests,
+  });
+  // Not part of the signature itself - it describes the page's markup, not
+  // what the page showed, and it must never count as a difference.
+  Object.defineProperty(signature, 'guessedEncoding', {
+    value: !!raw.guessedEncoding,
+    enumerable: false,
+  });
+  return signature;
+}
+
+/**
+ * Reads the page once it has stopped changing, and returns a signature - or
+ * null if it could not be read at all. Never throws: this is a diagnostic and
+ * must not become a second failure.
+ *
+ * Why it is not just networkidle. In a single-page app a click causes no
+ * navigation: the request answers and the framework swaps the DOM a moment
+ * later. Playwright's networkidle means "no requests for 500ms", which is a
+ * fact about the network, not about the page - so a render that lands even
+ * 300ms after the response is missed entirely and the reading describes the
+ * screen the user was on *before* the click. That is exactly how a working
+ * login came back as the login form.
+ *
+ * Why it is not a fixed sleep either: whatever number is picked is too short
+ * for a slow machine and wasted on a fast one.
+ *
+ * So: wait out any pending request, then read the page repeatedly until it has
+ * held still for a while. The quiet window matters more than the gap between
+ * reads - two identical readings 200ms apart prove nothing on a page that is
+ * simply waiting, which is why stability is measured from the last change seen
+ * rather than from the first pair that happened to agree. A page that never
+ * settles is capped, and whatever it looked like at the cap is used; running
+ * out of patience is not a reason to fail somebody's test.
+ */
+function positiveNumber(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * The quiet window and the cap, either of which a slow app may need more of.
+ *
+ * No amount of waiting can predict a render that has not happened yet, so
+ * these are a judgement about how long a page is given to prove it has
+ * finished. An app that renders later than the window still reads early, and
+ * raising this is the way out of that.
+ */
+function settleSettings(env) {
+  const source = env || process.env;
+  return {
+    quiet: positiveNumber(source.KRYPTHEON_SIGNATURE_QUIET_MS, SETTLE_QUIET),
+    budget: positiveNumber(source.KRYPTHEON_SIGNATURE_BUDGET_MS, SETTLE_BUDGET),
+  };
+}
+
+async function collectSignature(page, failedRequests, options) {
+  const opts = options || {};
+  const fromEnv = settleSettings(opts.env);
+  const gap = opts.settleGap == null ? SETTLE_GAP : opts.settleGap;
+  const quiet = opts.settleQuiet == null ? fromEnv.quiet : opts.settleQuiet;
+  const budget = opts.settleBudget == null ? fromEnv.budget : opts.settleBudget;
+
+  try {
+    const started = Date.now();
+
+    // An answer still in flight will change the page the moment it lands, so
+    // it is worth waiting out before deciding the page has stopped moving.
+    try {
+      await page.waitForLoadState('networkidle', {
+        timeout: Math.min(NETWORK_BUDGET, Math.max(0, budget - (Date.now() - started))),
+      });
+    } catch (e) {
+      /* still talking, or the state is unavailable - the loop below copes */
+    }
+
+    let current = await readSignature(page, failedRequests);
+    let lastChange = Date.now();
+
+    for (;;) {
+      const now = Date.now();
+      if (now - lastChange >= quiet) return current;
+      if (now - started >= budget) return current;
+      await pause(page, gap);
+      const next = await readSignature(page, failedRequests);
+      if (!sameSignature(current, next)) lastChange = Date.now();
+      current = next;
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Getting the signature out of the worker and onto the terminal.
+//
+// Nothing written from inside a Playwright worker reaches the terminal here.
+// Playwright pipes the worker's real file descriptors and hands whatever comes
+// out to reporter.onStdOut / onStdErr; kryptheon's reporter implements neither
+// hook and the config runs no other reporter, so it is collected and dropped.
+// Measured, not assumed: console.log, process.stdout.write, process.stderr.write
+// and fs.writeSync to both fd 1 and fd 2 all vanish.
+//
+// So the worker hands the signature over through a file, and the CLI - whose
+// stderr really is the terminal - prints it once the run is over. The reporter
+// and its output format are untouched.
+// ---------------------------------------------------------------------------
+
+const SINK_ENV = 'KRYPTHEON_SIGNATURE_FILE';
+
+/** Where the worker should leave signatures, or null if nobody asked for them. */
+function sinkPath(env) {
+  const source = env || process.env;
+  const file = source[SINK_ENV];
+  return file ? String(file) : null;
+}
+
+/** One JSON line per test. Append-only, so parallel workers cannot interleave. */
+function recordSignature(label, signature, env) {
+  const file = sinkPath(env);
+  if (!file) return false;
+  try {
+    fs.appendFileSync(file, JSON.stringify({ test: label, signature: signature }) + '\n', 'utf8');
+    return true;
+  } catch (e) {
+    return false; // a diagnostic must never become a second failure
+  }
+}
+
+/** Reads what the workers left, newest run last. Missing file means nothing ran. */
+function readRecorded(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (e) {
+      /* a torn line is not worth failing over */
+    }
+  }
+  return out;
+}
+
+/**
+ * Prints the signature. Step one does nothing else with it.
+ *
+ * Goes to stderr so the reporter's own output, which is stdout, stays exactly
+ * as it was - a person or a script reading the report sees no difference.
+ */
+function printSignature(signature, label, out) {
+  const write = out || ((line) => process.stderr.write(line + '\n'));
+  if (!signature) {
+    write('[kryptheon signature] ' + label + ': could not read the page');
+    return;
+  }
+  write('[kryptheon signature] ' + label);
+  write(JSON.stringify(signature, null, 2));
+}
+
+/** Prints everything the workers recorded, then clears the file. */
+function drainSignatures(file, out) {
+  const records = readRecorded(file);
+  for (const record of records) {
+    printSignature(record.signature, record.test, out);
+  }
+  try {
+    fs.rmSync(file, { force: true });
+  } catch (e) {
+    /* leftover temp file is not worth failing over */
+  }
+  return records.length;
+}
+
+module.exports = {
+  SINK_ENV: SINK_ENV,
+  sinkPath: sinkPath,
+  recordSignature: recordSignature,
+  readRecorded: readRecorded,
+  drainSignatures: drainSignatures,
+  normaliseText: normaliseText,
+  uniqueSorted: uniqueSorted,
+  uniqueInOrder: uniqueInOrder,
+  signaturePath: signaturePath,
+  toSignatureRequests: toSignatureRequests,
+  buildSignature: buildSignature,
+  compareSignatures: compareSignatures,
+  describeSignature: describeSignature,
+  setDifference: setDifference,
+  signatureEnabled: signatureEnabled,
+  collectSignature: collectSignature,
+  printSignature: printSignature,
+  readPage: readPage,
+  sameSignature: sameSignature,
+  settleSettings: settleSettings,
+  MAX_TEXT: MAX_TEXT,
+  SETTLE_GAP: SETTLE_GAP,
+  SETTLE_QUIET: SETTLE_QUIET,
+  SETTLE_BUDGET: SETTLE_BUDGET,
+  MAX_ACTIONS: MAX_ACTIONS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -12,12 +12,16 @@
     "./kryptheon-fixture": "./kryptheon-fixture.js",
     "./kryptheon-reporter": "./kryptheon-reporter.js",
     "./package.json": "./package.json",
-    "./kryptheon-replay": "./kryptheon-replay.js"
+    "./kryptheon-replay": "./kryptheon-replay.js",
+    "./kryptheon-signature": "./kryptheon-signature.js",
+    "./kryptheon-secrets": "./kryptheon-secrets.js"
   },
   "files": [
     "bin/",
     "kryptheon-fixture.js",
     "kryptheon-reporter.js",
+    "kryptheon-signature.js",
+    "kryptheon-secrets.js",
     "playwright.config.js",
     "README.md",
     "kryptheon-replay.js"
@@ -29,7 +33,11 @@
     "@playwright/test": "^1.62.1"
   },
   "scripts": {
-    "check": "node kryptheon-reporter.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-step3.check.js",
+    "check:stream": "node kryptheon-signature.stream.check.js",
+    "check:baseline": "node kryptheon-signature.baseline.check.js",
+    "check:settle": "node kryptheon-signature.settle.check.js",
+    "check:step3": "node kryptheon-step3.check.js"
   },
   "keywords": [
     "playwright",

package/playwright.config.js

@@ -12,27 +12,27 @@ const USER_DIR = process.cwd();
 // .env is not fatal: CI can supply the same variables as real env vars.
 // loadEnvFile only exists from Node 20.12, and the package supports 20.6, so
 // fall back to a small parser rather than silently skipping the file.
+// Deliberately not process.loadEnvFile, and this is the whole reason:
+//
+// On Windows, PowerShell's `Out-File -Encoding utf8` and Notepad's "Save as
+// UTF-8" both write a byte order mark. loadEnvFile keeps it, so the first line
+// of the file defines "KRYPTHEON_PASSWORD" rather than
+// "KRYPTHEON_PASSWORD" - measured, not assumed. The variable then reads as
+// undefined, the recording signs in with an empty password, and the login
+// fails for a reason nothing in the report mentions. The file is right there,
+// so nothing warns either.
+//
+// One parser, shared with the CLI, is also what stops the command that decides
+// whether a password is present from disagreeing with the test that uses it.
 function loadEnv(file) {
-  if (typeof process.loadEnvFile === 'function') {
-    try {
-      process.loadEnvFile(file);
-      return;
-    } catch (err) {
-      if (err && err.code !== 'ENOENT') throw err;
-      return;
-    }
-  }
-  let raw;
-  try {
-    raw = require('fs').readFileSync(file, 'utf8');
-  } catch (err) {
-    return; // no .env is fine
-  }
-  for (const line of raw.split('\n')) {
-    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
-    if (!match) continue;
-    const value = match[2].replace(/^(['"])(.*)\1$/, '$2');
-    if (process.env[match[1]] === undefined) process.env[match[1]] = value;
+  const secrets = require(path.join(PACKAGE_DIR, 'kryptheon-secrets.js'));
+  const values = secrets.readEnvFile(file);
+  for (const name of Object.keys(values)) {
+    // A real environment variable wins over the file - but only a real one.
+    // A variable that exists and is empty is how "unset" arrives from a shell
+    // or a CI job, and letting that beat the file would leave the password
+    // blank with the answer sitting right there on disk.
+    if (!secrets.isSet(process.env[name])) process.env[name] = values[name];
   }
 }