kryptheon 0.1.11 → 0.1.13

package/kryptheon-secrets.js

@@ -1,191 +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'),
-};
+// 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

@@ -2,17 +2,17 @@
 // 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.
+// Why it exists. A baseline used to remember only 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 under the same title, so the baseline saw no difference and the
+// run was reported as fine. The signature is the thing that notices - the
+// headings, buttons, links and fields on a 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.
+// A signature is part of the baseline: saved on a pass, compared on the next
+// run, and a difference fails the test. KRYPTHEON_DEBUG_SIGNATURE=1 additionally
+// prints what was captured, which is only ever a way to see the reasoning.
 
 const fs = require('fs');
 
@@ -495,7 +495,7 @@ function readRecorded(file) {
 }
 
 /**
- * Prints the signature. Step one does nothing else with it.
+ * Prints a signature, for when someone wants to see what was read.
  *
  * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -38,21 +38,25 @@
     "@playwright/test": "^1.62.1"
   },
   "scripts": {
-    "check": "node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-step3.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-package.check.js",
+    "check": "node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
+    "check:reporter": "node kryptheon-reporter.check.js",
+    "check:signature": "node kryptheon-signature.check.js",
     "check:stream": "node kryptheon-signature.stream.check.js",
     "check:baseline": "node kryptheon-signature.baseline.check.js",
     "check:settle": "node kryptheon-signature.settle.check.js",
-    "check:step3": "node kryptheon-step3.check.js",
+    "check:number": "node kryptheon-signature.number.check.js",
+    "check:env": "node kryptheon-env.check.js",
     "check:watchdog": "node kryptheon-watchdog.check.js",
     "check:record": "node kryptheon-record.check.js",
-    "check:package": "node kryptheon-package.check.js",
-    "prepublishOnly": "node kryptheon-package.check.js",
     "check:selectors": "node kryptheon-selectors.check.js",
-    "check:number": "node kryptheon-signature.number.check.js",
     "check:recordings": "node kryptheon-recordings.check.js",
     "check:cleanup": "node kryptheon-cleanup.check.js",
     "check:orphan": "node kryptheon-orphan.check.js",
-    "check:project": "node kryptheon-project.check.js"
+    "check:project": "node kryptheon-project.check.js",
+    "check:setup": "node kryptheon-setup.check.js",
+    "check:load": "node kryptheon-load.check.js",
+    "check:package": "node kryptheon-package.check.js",
+    "prepublishOnly": "node kryptheon-package.check.js"
   },
   "keywords": [
     "playwright",