kryptheon 0.1.6 → 0.1.8

package/bin/kryptheon.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // The kryptheon CLI. A thin wrapper so nobody has to remember Playwright's
 // command line or edit a config file. Everything here shells out to the
 // Playwright binary that ships with this package.
@@ -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'),
+};