kryptheon 0.1.51 → 0.1.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1149,9 +1149,16 @@
1149
1149
  if (!state.runs.length) { box.appendChild(el('p', 'empty', 'No recorded flows have been replayed yet. Record one with npx kryptheon record, then press Run checks.')); return; }
1150
1150
  state.runs.slice(0, 30).forEach(function (r) {
1151
1151
  var row = el('div', 'line-row');
1152
- row.appendChild(el('span', 'tag ' + (r.failed ? 'ember' : 'leaf'), r.failed ? r.failed + ' broke' : 'held'));
1152
+ var skipped = r.skipped || [];
1153
+ // Every recording left out: nothing ran, and the row says why, instead
1154
+ // of the run vanishing from this page.
1155
+ var none = r.status === 'skipped' || (!r.passed && !r.failed && skipped.length);
1156
+ row.appendChild(el('span', 'tag ' + (none ? 'muted' : r.failed ? 'ember' : 'leaf'), none ? 'nothing ran' : r.failed ? r.failed + ' broke' : 'held'));
1153
1157
  var text = el('div', 'lr-text');
1154
- text.appendChild(el('div', null, (r.passed || 0) + ' held, ' + (r.failed || 0) + ' broke'));
1158
+ text.appendChild(el('div', null, none
1159
+ ? 'Skipped ' + skipped.length + (skipped.length === 1 ? ' recording' : ' recordings')
1160
+ : (r.passed || 0) + ' held, ' + (r.failed || 0) + ' broke' + (skipped.length ? ', ' + skipped.length + ' skipped' : '')));
1161
+ skipped.forEach(function (s) { text.appendChild(el('div', 'lr-sub', s.file + ' - ' + s.why)); });
1155
1162
  text.appendChild(el('div', 'lr-sub', when(r.runAt)));
1156
1163
  row.appendChild(text);
1157
1164
  if (r.failed) row.appendChild(button('sm', 'arrow', 'See the finding', function () { go('findings', 'confirmed'); }));
@@ -558,7 +558,12 @@ function buildState(root, env) {
558
558
 
559
559
  // Recorded flows: the last run's broken tests are the findings. They were
560
560
  // replayed in a real browser, so they are confirmed at runtime.
561
- const lastRun = history.length ? history[history.length - 1] : null;
561
+ // The last run that replayed something. A run where every recording was
562
+ // skipped (no password set) is listed under Runs, but it re-checked
563
+ // nothing, so it neither clears the last real run's findings nor counts as
564
+ // the flows having been replayed.
565
+ const replayed = history.filter((r) => (r.tests || []).length);
566
+ const lastRun = replayed.length ? replayed[replayed.length - 1] : null;
562
567
  if (lastRun && config.enabled.regression) {
563
568
  for (const t of lastRun.tests || []) {
564
569
  if (t.status !== 'failed' && t.status !== 'timedOut') continue;
@@ -849,7 +854,7 @@ function buildState(root, env) {
849
854
  notChecked: NOT_CHECKED,
850
855
  findings: findings,
851
856
  allFixPrompt: combinedPrompt(forAll),
852
- runs: history.slice().reverse().map((r) => ({ runAt: r.runAt, status: r.status, passed: r.passed, failed: r.failed, durationMs: r.durationMs })),
857
+ runs: history.slice().reverse().map((r) => ({ runAt: r.runAt, status: r.status, passed: r.passed, failed: r.failed, durationMs: r.durationMs, skipped: (r.skipped || []).slice(0, 20) })),
853
858
  recordings: recordings,
854
859
  steps: steps,
855
860
  // Which app this dashboard is for: its web address, kept here, and whether
@@ -440,6 +440,15 @@ const test = base.test.extend({
440
440
  /* without it, a failure is said as before */
441
441
  }
442
442
 
443
+ // Time by length: a long recording gets longer than Playwright's flat 30
444
+ // seconds (kryptheon-replay.js timeBudget). Set here, before the page is
445
+ // handed to the recording, so every step runs under the new limit.
446
+ try {
447
+ testInfo.setTimeout(replay.timeBudget(fs.readFileSync(testInfo.file, 'utf8')));
448
+ } catch (e) {
449
+ /* Playwright's own limit stands */
450
+ }
451
+
443
452
  const key = baselineKey(testInfo.file, testInfo.title);
444
453
 
445
454
  // The steps this recording actually performs. Comments, blank lines and
@@ -459,6 +468,21 @@ const test = base.test.extend({
459
468
  const sameRecording =
460
469
  Boolean(previousEntry) && typeof previousEntry === 'object' &&
461
470
  !(previousEntry.recordingId && recordingId && previousEntry.recordingId !== recordingId);
471
+ // A value the recording types and then finds its record by gets this
472
+ // run's own number, so a second run does not find two (replay
473
+ // freshValues). Before heal.watch, which keeps getByRole as it is now.
474
+ let freshToken = null;
475
+ let freshShown = [];
476
+ try {
477
+ const values = replay.freshValues(fs.readFileSync(testInfo.file, 'utf8'));
478
+ if (values.length) {
479
+ freshToken = String(Date.now()).slice(-6);
480
+ freshShown = values.map((v) => signature.normaliseText(v));
481
+ replay.useFreshNames(page, values, freshToken);
482
+ }
483
+ } catch (e) {
484
+ freshToken = null; /* replayed exactly as recorded */
485
+ }
462
486
  const healer = heal.watch(page, {
463
487
  memory: sameRecording ? previousEntry.steps : null,
464
488
  fallback: sameRecording ? previousEntry.signature : null,
@@ -524,7 +548,8 @@ const test = base.test.extend({
524
548
  // Playwright pipes this worker's descriptors and gives whatever comes out
525
549
  // to reporter stdio hooks that this reporter does not implement, so
526
550
  // anything printed from here is dropped before it reaches a terminal.
527
- const captured = await signature.collectSignature(page, failedRequests);
551
+ // This run's number taken back out, so the page reads as it did when recorded.
552
+ const captured = replay.withoutFresh(await signature.collectSignature(page, failedRequests), freshToken, freshShown);
528
553
  if (signature.signatureEnabled()) signature.recordSignature(testInfo.title, captured);
529
554
 
530
555
  // Said once per run by the reporter, not once per test: it is a fact about
@@ -554,7 +579,7 @@ const test = base.test.extend({
554
579
  failedRequests: failedRequests,
555
580
  signature: captured,
556
581
  recordingId: recordingId,
557
- steps: heal.mergeMemory(sameRecording ? previousEntry.steps : null, healer.learned),
582
+ steps: heal.mergeMemory(sameRecording ? previousEntry.steps : null, replay.withoutFresh(healer.learned, freshToken, freshShown)),
558
583
  };
559
584
  } catch (e) {
560
585
  current = null; // page closed by the test - leave any baseline untouched
@@ -141,6 +141,23 @@ function fixPrompt(result, f) {
141
141
  'Do not change anything else. Afterwards I will run: npx kryptheon payments',
142
142
  ].join('\n');
143
143
  }
144
+ if (f.kind === 'refund-early' || f.kind === 'refund-twice' || f.kind === 'below-zero') {
145
+ return [
146
+ f.kind === 'refund-early' ? 'My app takes back what a payment gave as soon as ' + who + ' says a refund started (refund.created).'
147
+ : f.kind === 'refund-twice' ? 'My app takes back what a payment gave twice for one refund: on refund.created and again on refund.processed.'
148
+ : 'A ' + result.event.type + ' webhook took a number in my database below zero.',
149
+ '',
150
+ 'I tested it with ' + who + ' test webhooks sent to ' + where + '. The first delivery of ' + result.event.type + ' changed:',
151
+ ].concat(f.changes.map((c) => ' ' + c), [
152
+ '',
153
+ 'Fix ' + where + ' so a refund is applied once, at the right step:',
154
+ '- on refund.created, record that a refund is pending and change nothing the customer has;',
155
+ '- on refund.processed, take back what that payment gave, once - check that the payment was not already reversed,',
156
+ ' in the same transaction as the change;',
157
+ '- never take a balance below zero by accident; if it can happen, decide what it should mean and say so.',
158
+ 'Keep the signature check first. Do not change anything else. Afterwards I will run: npx kryptheon payments',
159
+ ]).join('\n');
160
+ }
144
161
  if (f.kind === 'repeat-refused') {
145
162
  return [
146
163
  'My app answers ' + f.status + ' when ' + who + ' sends the same webhook again.',
@@ -193,6 +210,27 @@ function findingLines(result, f) {
193
210
  ' are handled by hand; a hole if the app is meant to take them back.',
194
211
  ];
195
212
  }
213
+ if (f.kind === 'refund-early') {
214
+ return [
215
+ 'MEDIUM refund.created already took it back, before the refund was processed.',
216
+ '',
217
+ ' ' + who + ' sends refund.created when a refund starts; it can still fail. The first delivery changed:',
218
+ ].concat(f.changes.map((c) => ' ' + c), [' If the refund fails, the customer has lost this and kept nothing back. Fine only if that is how you want it.']);
219
+ }
220
+ if (f.kind === 'refund-twice') {
221
+ return [
222
+ 'HIGH The refund was taken back twice: once on refund.created, again on refund.processed.',
223
+ '',
224
+ ' One refund, two events, and each took the same thing back:',
225
+ ].concat(f.changes.map((c) => ' ' + c + ' (refund.processed, after refund.created had already taken it)'));
226
+ }
227
+ if (f.kind === 'below-zero') {
228
+ return [
229
+ 'HIGH ' + result.event.type + ' took a number below zero.',
230
+ '',
231
+ ' The first delivery, as ' + who + ' sent it, changed:',
232
+ ].concat(f.changes.map((c) => ' ' + c), [' A balance below zero is usually something given or taken back twice.']);
233
+ }
196
234
  if (f.kind === 'repeat-refused') {
197
235
  return [
198
236
  'MEDIUM Your app answers ' + f.status + ' to a repeat, so ' + who + ' keeps sending it.',
@@ -406,6 +444,7 @@ async function run(root, options) {
406
444
  if (again.trace && firstDelivery) again.trace.deliveries[0] = firstDelivery;
407
445
  result = again;
408
446
  }
447
+ result.findings = result.findings.concat(payments.lifecycle(result, report.results));
409
448
  report.results.push(result);
410
449
  }
411
450
  checking = false;
@@ -598,7 +598,44 @@ async function check(options) {
598
598
  return result;
599
599
  }
600
600
 
601
+ /**
602
+ * What the first delivery of a refund did to the money, judged against the
603
+ * provider's own order of events. Found on blind round 22: refund.created
604
+ * took the credits back while the invoice still said "pending", then
605
+ * refund.processed took them back again, and the balance went below zero -
606
+ * all in the trace, none of it said.
607
+ * refund-early refund.created took something back (the refund can still fail)
608
+ * refund-twice refund.processed took back what refund.created already had
609
+ * below-zero a number that was zero or more went below zero
610
+ * `earlier` is the results already judged in this run, oldest first.
611
+ */
612
+ function lifecycle(result, earlier) {
613
+ const first = result && result.trace && result.trace.deliveries && result.trace.deliveries[0];
614
+ if (!first || !first.writes) return [];
615
+ const num = (v) => (typeof v === 'number' ? v : typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v.trim()) ? Number(v) : null);
616
+ const drops = (writes) => (writes || []).filter((w) => w.class === 'business' && w.kind === 'changed').flatMap((w) =>
617
+ (w.columns || []).filter((c) => num(c.from) !== null && num(c.to) !== null && num(c.to) < num(c.from))
618
+ .map((c) => ({ table: w.table, key: JSON.stringify(w.key || []), column: c.name, from: num(c.from), to: num(c.to) })));
619
+ const line = (d) => d.table + '.' + d.column + ' ' + d.from + ' -> ' + d.to;
620
+ const out = [];
621
+ const mine = drops(first.writes);
622
+ const type = result.event && result.event.type;
623
+ if (type === 'refund.created' && mine.length) {
624
+ out.push({ kind: 'refund-early', severity: 'MEDIUM', status: first.status, changes: mine.map(line) });
625
+ }
626
+ if (type === 'refund.processed' && mine.length) {
627
+ const before = (earlier || []).filter((r) => r.event && r.event.type === 'refund.created' && r.provider === result.provider)
628
+ .flatMap((r) => drops(r.trace && r.trace.deliveries && r.trace.deliveries[0] && r.trace.deliveries[0].writes));
629
+ const again = mine.filter((d) => before.some((b) => b.table === d.table && b.column === d.column && b.key === d.key));
630
+ if (again.length) out.push({ kind: 'refund-twice', severity: 'HIGH', status: first.status, changes: again.map(line) });
631
+ }
632
+ const below = mine.filter((d) => d.from >= 0 && d.to < 0);
633
+ if (below.length) out.push({ kind: 'below-zero', severity: 'HIGH', status: first.status, changes: below.map(line) });
634
+ return out;
635
+ }
636
+
601
637
  module.exports = {
638
+ lifecycle: lifecycle,
602
639
  isLocalAddress: isLocalAddress,
603
640
  providerOf: providerOf,
604
641
  modeOf: modeOf,
@@ -33,6 +33,7 @@ const SWEEP_BUTTONS = 25;
33
33
  const SECRET_KEY = /(pass(word|code)?|secret|token|otp|card|cvv|cvc|\bpin\b|api[_-]?key|authorization)/i;
34
34
  const MARKER = require('./kryptheon-probe.js').MARKER;
35
35
  const heal = require('./kryptheon-heal.js');
36
+ const replay = require('./kryptheon-replay.js');
36
37
 
37
38
  function sleep(ms) {
38
39
  return new Promise((resolve) => setTimeout(resolve, ms));
@@ -333,6 +334,13 @@ const test = base.test.extend({
333
334
  // too, as in the plain replay (kryptheon-heal.js): the checks run the
334
335
  // recordings the replay passes, and would stop where it carried on. With
335
336
  // nothing remembered, no other rename is followed.
337
+ // The fresh names first: heal keeps the page's own getByRole as it is now
338
+ // (kryptheon-replay.js freshValues).
339
+ try {
340
+ replay.useFreshNames(page, replay.freshValues(fs.readFileSync(testInfo.file, 'utf8')), String(Date.now()).slice(-6));
341
+ } catch (e) {
342
+ /* replayed exactly as recorded */
343
+ }
336
344
  heal.watch(page, {});
337
345
 
338
346
  // A gap before every run, and a longer one after the app said "too many
@@ -75,12 +75,18 @@ const limited = (r) => eventsOf(r).some((e) => e.kind === 'limited');
75
75
  * says it adds or saves something. Not a sign-up - that makes an account -
76
76
  * and not one that only opens a form; that is found out at run time, when a
77
77
  * single click of it adds no record (singleClickWords says what it did).
78
+ * Beyond add/save/create, the words that book, reserve, order, pay or run
79
+ * something: found on blind round 22, where "Book 1 seat", "Reserve" and
80
+ * "Run overdue-notification job" each sent a write and none was tried.
78
81
  */
82
+ const ALSO_SAVES = /^[^\p{L}\p{N}]*(book|reserve|order|buy|pay|checkout|invite|apply|enrol|enroll|schedule|request|place|confirm|run|capture|claim|redeem)\b/iu;
83
+
79
84
  function saveSteps(source) {
80
85
  const lines = String(source || '').split('\n');
81
86
  const out = [];
82
87
  for (const a of clickSteps(source)) {
83
- if (!replay.CREATES.test(a.name.trim()) || replay.SIGNUP.test(a.name)) continue;
88
+ const name = a.name.trim();
89
+ if (!(replay.CREATES.test(name) || ALSO_SAVES.test(name)) || replay.SIGNUP.test(a.name)) continue;
84
90
  const m = CLICK.exec(lines[a.line - 1].replace(/\r$/, ''));
85
91
  if (!m) continue;
86
92
  out.push({ line: a.line, indent: m[1], locator: m[3], name: a.name.trim() });
@@ -119,6 +125,26 @@ function clickSteps(source) {
119
125
  return out;
120
126
  }
121
127
 
128
+ /**
129
+ * The line the sign-in ends on: the first button or link clicked (or Enter
130
+ * pressed) after the last password or .env value typed - a click into a
131
+ * field is not it. Found on blind round 22: the password was typed before
132
+ * the email, and the email, typed after it, was read back as a field the
133
+ * next save should have kept.
134
+ */
135
+ function signInEndOf(source) {
136
+ const lines = String(source || '').split('\n');
137
+ let secret = -1;
138
+ lines.forEach((line, i) => {
139
+ if (/\.fill\(/.test(line) && (replay.isSecretField(replay.nameInLine(line)) || /process\.env\./.test(line))) secret = i;
140
+ });
141
+ if (secret < 0) return 0;
142
+ for (let i = secret + 1; i < lines.length; i++) {
143
+ if (/getByRole\(\s*['"](button|link)['"][^)]*\)\s*\.click\(|type=["']?submit[^)]*\)\s*\.click\(|\.press\([^)]*Enter/.test(lines[i])) return i + 1;
144
+ }
145
+ return secret + 1;
146
+ }
147
+
122
148
  /**
123
149
  * What was typed before a saving step, to look for on the page after it:
124
150
  * each literal value filled in since the last step that saved, three
@@ -126,11 +152,7 @@ function clickSteps(source) {
126
152
  */
127
153
  function typedFor(source, steps, step) {
128
154
  const since = Math.max(0, ...steps.filter((s) => s.line < step.line).map((s) => s.line));
129
- const lines = String(source || '').split('\n');
130
- let signInEnd = 0;
131
- lines.forEach((line, i) => {
132
- if (/\.fill\(/.test(line) && (replay.isSecretField(replay.nameInLine(line)) || /process\.env\./.test(line))) signInEnd = i + 1;
133
- });
155
+ const signInEnd = signInEndOf(source);
134
156
  const out = [];
135
157
  for (const f of edge.fillSteps(source)) {
136
158
  if (f.line <= since || f.line >= step.line || f.line <= signInEnd || replay.isSecretField(f.name)) continue;
@@ -196,11 +218,7 @@ function keepSteps(source) {
196
218
  function keptFields(source, step) {
197
219
  const steps = keepSteps(source);
198
220
  const since = Math.max(0, ...steps.filter((s) => s.line < step.line).map((s) => s.line));
199
- const lines = String(source || '').split('\n');
200
- let signInEnd = 0;
201
- lines.forEach((line, i) => {
202
- if (/\.fill\(/.test(line) && (replay.isSecretField(replay.nameInLine(line)) || /process\.env\./.test(line))) signInEnd = i + 1;
203
- });
221
+ const signInEnd = signInEndOf(source);
204
222
  // Each field once: its last fill is what was saved, and what it held is
205
223
  // read before its first - a typo fixed by typing again is still one edit.
206
224
  const byLocator = new Map();
@@ -534,15 +552,24 @@ function recordIds(w) {
534
552
  if (answer == null) return [];
535
553
  const rows = Array.isArray(answer) ? answer : answer && typeof answer === 'object' && answer.data !== undefined
536
554
  ? [].concat(answer.data) : [answer];
555
+ const idOf = (row) => {
556
+ if (!row || typeof row !== 'object') return null;
557
+ for (const k of ['id', 'uuid', '_id']) if (typeof row[k] === 'string' || typeof row[k] === 'number') return String(row[k]);
558
+ return null;
559
+ };
537
560
  const out = [];
538
561
  for (const row of rows) {
539
- if (!row || typeof row !== 'object') continue;
540
- for (const k of ['id', 'uuid', '_id']) {
541
- if (typeof row[k] === 'string' || typeof row[k] === 'number') {
542
- out.push(String(row[k]));
543
- break;
544
- }
562
+ const id = idOf(row);
563
+ if (id !== null) {
564
+ out.push(id);
565
+ continue;
545
566
  }
567
+ // The record wrapped in one named key ({ note: { id: 7 } }). Found on
568
+ // blind round 22: an upsert answered both clicks with the same note, and
569
+ // with its id unread the two answers were taken for two notes.
570
+ const inner = row && typeof row === 'object' && !Array.isArray(row)
571
+ ? Object.values(row).filter((v) => v && typeof v === 'object' && !Array.isArray(v) && idOf(v) !== null) : [];
572
+ if (inner.length === 1) out.push(idOf(inner[0]));
546
573
  }
547
574
  return out;
548
575
  }
@@ -300,8 +300,148 @@ function recordingId(source) {
300
300
  return require('crypto').createHash('sha1').update(steps.join('\n')).digest('hex').slice(0, 12);
301
301
  }
302
302
 
303
+ // How long one replay of this recording may take, in milliseconds.
304
+ //
305
+ // Playwright's own limit is 30 seconds for the whole test, whatever its
306
+ // length. A correct recording of 40 steps against a live site needs more than
307
+ // that, ran out of time partway, and was reported as the app's fault (a real
308
+ // user's app, 2026-10-22). So: 30 seconds plus 3 per step, never under 60
309
+ // seconds and never over 3 minutes - past that, something really is stuck.
310
+ const BUDGET = { base: 30000, perStep: 3000, min: 60000, max: 180000 };
311
+ // Past this many steps a recording is said to be long when it is made.
312
+ const LONG_RECORDING = 40;
313
+
314
+ function timeBudget(source) {
315
+ const steps = readActions(source).length;
316
+ return Math.min(BUDGET.max, Math.max(BUDGET.min, BUDGET.base + steps * BUDGET.perStep));
317
+ }
318
+
319
+ // A value the recording types and then finds its own record by: "nothing"
320
+ // typed as a work order's title, then the list row "nothing Morgan Owner"
321
+ // clicked. Replayed, every run adds one more "nothing", the click finds two,
322
+ // and the recording never passes again (blind round 22: three of eleven).
323
+ // Each run types such a value with a number after it - "nothing 482173" -
324
+ // and looks for that; page text compares numbers as '#', so the page still
325
+ // reads the same to the regression check. Emails, addresses and numbers are
326
+ // left as typed: a field may refuse them with anything added.
327
+ const FRESH_SKIP = /@|^https?:|^[\d\s.,:/+#-]+$/;
328
+ const QUOTED = /(['"`])((?:\\.|(?!\1).)*)\1/g;
329
+
330
+ function freshValues(source) {
331
+ const lines = String(source || '').split('\n');
332
+ const fills = [];
333
+ lines.forEach((line, i) => {
334
+ const m = /\.fill\(\s*(['"`])((?:\\.|(?!\1).)*)\1\s*\)/.exec(line);
335
+ if (!m || /process\.env\./.test(line) || isSecretField(nameInLine(line))) return;
336
+ const value = m[2].trim();
337
+ if (value.length >= 3 && !FRESH_SKIP.test(value)) fills.push({ value: value, line: i });
338
+ });
339
+ const out = [];
340
+ for (const f of fills) {
341
+ const later = lines.slice(f.line + 1).some((l) => /getBy(Role|Text|Label|Title|AltText)\(/.test(l) && !/\.fill\(/.test(l) &&
342
+ Array.from(l.matchAll(QUOTED)).some((q) => q[2].includes(f.value)));
343
+ if (later && !out.includes(f.value)) out.push(f.value);
344
+ }
345
+ return out.sort((a, b) => b.length - a.length);
346
+ }
347
+
348
+ // Which page gets which fresh names. Set per page, read by the locators it
349
+ // makes, so two tests in one process never share a run's number.
350
+ const FRESH = new WeakMap();
351
+ const GETTERS = ['getByRole', 'getByText', 'getByLabel', 'getByTitle', 'getByAltText', 'getByPlaceholder'];
352
+
353
+ /** "nothing" -> "nothing 482173" wherever a looked-for or typed text holds it. */
354
+ function freshText(state, text) {
355
+ return state && typeof text === 'string' ? text.replace(state.pattern, (m) => m + ' ' + state.token) : text;
356
+ }
357
+
358
+ function wrapGetters(proto, stateOf) {
359
+ for (const name of GETTERS) {
360
+ const orig = proto[name];
361
+ if (typeof orig !== 'function' || orig.__kxFresh) continue;
362
+ const wrapped = function (arg, options) {
363
+ let state = null;
364
+ try {
365
+ state = stateOf(this);
366
+ } catch (e) {
367
+ state = null;
368
+ }
369
+ if (!state) return orig.call(this, arg, options);
370
+ if (name === 'getByRole') {
371
+ return orig.call(this, arg, options && typeof options.name === 'string' ? Object.assign({}, options, { name: freshText(state, options.name) }) : options);
372
+ }
373
+ return orig.call(this, freshText(state, arg), options);
374
+ };
375
+ wrapped.__kxFresh = true;
376
+ proto[name] = wrapped;
377
+ }
378
+ }
379
+
380
+ /** Gives this page's run its own names for the values freshValues found. */
381
+ function useFreshNames(page, values, token) {
382
+ if (!page || !values || !values.length) return;
383
+ const escaped = values.map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
384
+ FRESH.set(page, { pattern: new RegExp(escaped.join('|'), 'g'), token: String(token) });
385
+ const pageProto = Object.getPrototypeOf(page);
386
+ wrapGetters(pageProto, (p) => FRESH.get(p));
387
+ const locatorProto = Object.getPrototypeOf(page.locator('body'));
388
+ wrapGetters(locatorProto, (l) => FRESH.get(l.page()));
389
+ if (!locatorProto.fill.__kxFresh) {
390
+ const fill = locatorProto.fill;
391
+ const wrapped = function (value, options) {
392
+ let state = null;
393
+ try {
394
+ state = FRESH.get(this.page());
395
+ } catch (e) {
396
+ state = null;
397
+ }
398
+ // Only a value typed whole, as the recording typed it, gets the number.
399
+ const typed = state && typeof value === 'string' && new RegExp('^\\s*(?:' + state.pattern.source + ')\\s*$').test(value);
400
+ return fill.call(this, typed ? freshText(state, value) : value, options);
401
+ };
402
+ wrapped.__kxFresh = true;
403
+ locatorProto.fill = wrapped;
404
+ }
405
+ }
406
+
407
+ /**
408
+ * Every text in `value` with this run's " 482173" taken back out (keys too).
409
+ * `shown` is each fresh value as the page signature writes it, numbers as
410
+ * '#' ("nothing 2" -> "nothing #"): there the number is already "#", and
411
+ * "nothing # #" goes back to "nothing #".
412
+ */
413
+ function withoutFresh(value, token, shown) {
414
+ if (!token) return value;
415
+ const forms = (shown || []).filter(Boolean).sort((a, b) => b.length - a.length);
416
+ // One pass, longest form first, so "nothing # #" loses one "#" and keeps
417
+ // the "2" of "nothing 2".
418
+ const numbered = forms.length ? new RegExp('(' + forms.map((f) => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + ') #', 'g') : null;
419
+ const strip = (s) => {
420
+ const out = s.split(' ' + token).join('');
421
+ return numbered ? out.replace(numbered, '$1') : out;
422
+ };
423
+ const walk = (v) => {
424
+ if (typeof v === 'string') return strip(v);
425
+ if (Array.isArray(v)) return v.map(walk);
426
+ if (v && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype) {
427
+ const out = {};
428
+ for (const k of Object.keys(v)) out[strip(k)] = walk(v[k]);
429
+ return out;
430
+ }
431
+ return v;
432
+ };
433
+ return walk(value);
434
+ }
435
+
303
436
  module.exports = {
437
+ withoutFresh: withoutFresh,
438
+ freshValues: freshValues,
439
+ useFreshNames: useFreshNames,
440
+ freshText: freshText,
304
441
  recordingId: recordingId,
442
+ timeBudget: timeBudget,
443
+ BUDGET: BUDGET,
444
+ LONG_RECORDING: LONG_RECORDING,
305
445
  readActions: readActions,
306
446
  findReplayRisks: findReplayRisks,
307
447
  scrubSecrets: scrubSecrets,
@@ -1029,6 +1029,14 @@ class KryptheonReporter {
1029
1029
  failed: failed,
1030
1030
  tests: this.records,
1031
1031
  };
1032
+ // Recordings the CLI left out before the run (no password set, not a real
1033
+ // recording), so the Runs page can say what was not replayed.
1034
+ try {
1035
+ const skipped = JSON.parse(process.env.KRYPTHEON_SKIPPED || '[]');
1036
+ if (Array.isArray(skipped) && skipped.length) entry.skipped = skipped;
1037
+ } catch (e) {
1038
+ // a malformed list is left out, never a reason to lose the run
1039
+ }
1032
1040
 
1033
1041
  // Append only - existing lines are never rewritten.
1034
1042
  let saved = false;
@@ -76,27 +76,44 @@ function missingSecrets(names, options) {
76
76
  }
77
77
 
78
78
  /**
79
- * How to create the file without a byte order mark.
79
+ * How to add the names to .env without a byte order mark.
80
80
  *
81
81
  * PowerShell's own `Out-File -Encoding utf8` writes one, and so does Notepad,
82
82
  * which is why this spells out a command that does not rather than leaving it
83
83
  * to whatever the person reaches for first.
84
+ *
85
+ * Always an append, never a write. The app's own .env is usually already
86
+ * there, holding its database URL and live payment keys; a command that
87
+ * replaced the file would wipe all of them for the sake of one test password
88
+ * (a real user's app, 2026-10-22). Appending also creates the file when there
89
+ * is none, so one command serves both. The leading newline keeps the first
90
+ * name off the end of a last line that has none; a blank line is harmless.
84
91
  */
85
92
  function howToWriteEnv(names, platform) {
86
- const line = names.map((name) => name + '=yourpassword').join('\\n');
87
- if ((platform || process.platform) === 'win32') {
93
+ const windows = (platform || process.platform) === 'win32';
94
+ const pairs = names.map((name) => name + '=yourpassword');
95
+ if (windows) {
96
+ // PowerShell's newline is `n inside double quotes. "\n" would be written
97
+ // as a backslash and an n, all on one line.
88
98
  return [
89
- ' In PowerShell, this writes it without a byte order mark:',
90
- ' [IO.File]::WriteAllText("$PWD\\.env", "' + line + '`n")',
99
+ ' In PowerShell, this adds it to the end of .env (it keeps what is',
100
+ ' already there, and writes no byte order mark):',
101
+ ' [IO.File]::AppendAllText("$PWD\\.env", "`n' + pairs.join('`n') + '`n")',
91
102
  '',
92
- ' Avoid Out-File and Notepad here: both add a mark that makes the first',
93
- ' line unreadable, and the password would silently come out blank.',
103
+ // Not "avoid Notepad" any more: readEnvFile drops a byte order mark, so
104
+ // editing the file in any editor afterwards is fine.
105
+ ' Then open .env and replace yourpassword with the real one.',
94
106
  ];
95
107
  }
96
- return [' For example:', " printf '" + line.replace(/\\n/g, "\\n") + "\\n' > .env"];
108
+ return [
109
+ ' This adds it to the end of .env and keeps what is already there:',
110
+ " printf '\\n" + pairs.join('\\n') + "\\n' >> .env",
111
+ '',
112
+ ' Then open .env and replace yourpassword with the real one.',
113
+ ];
97
114
  }
98
115
 
99
- /** What to tell somebody who has not created the file yet. */
116
+ /** What to tell somebody who has not set the secret yet. */
100
117
  function missingSecretLines(specName, names, options) {
101
118
  const opts = options || {};
102
119
  const many = names.length > 1;
@@ -105,13 +122,15 @@ function missingSecretLines(specName, names, options) {
105
122
  ' This recording needs a password' + (many ? ' and other secrets' : '') + ', and there is none set.',
106
123
  '',
107
124
  ];
108
- if (opts.examplePath) {
109
- lines.push(' There is a ' + opts.examplePath + ' here already. Put the real value in it');
110
- lines.push(' and save it as .env, in the same folder.');
125
+ // Never "save .env.example as .env": the example may be the app's own, and
126
+ // saving over an existing .env loses every value the app runs on.
127
+ if (opts.envExists) {
128
+ lines.push(' Add ' + (many ? 'these lines' : 'this line') + ' to the .env in this folder. Keep everything');
129
+ lines.push(' already in it - your app needs those values:');
111
130
  } else {
112
131
  lines.push(' Create a .env file in this folder containing:');
113
- for (const name of names) lines.push(' ' + name + '=yourpassword');
114
132
  }
133
+ for (const name of names) lines.push(' ' + name + '=yourpassword');
115
134
  lines.push('');
116
135
  for (const line of howToWriteEnv(names, opts.platform)) lines.push(line);
117
136
  lines.push('');
@@ -128,6 +147,11 @@ function missingSecretLines(specName, names, options) {
128
147
  * names from an earlier recording, and clobbering it would lose them. A name
129
148
  * it does not have yet is added at the end - each account now has its own
130
149
  * (blind round 19), so a second account's recording brings a second name.
150
+ *
151
+ * Only a file Kryptheon wrote is added to. Many apps ship their own
152
+ * .env.example, listing their own settings; that file is the app's, committed
153
+ * with it, and is left exactly as it is. A file is Kryptheon's when every name
154
+ * in it is one of Kryptheon's (KRYPTHEON_...).
131
155
  * Returns the file when it wrote to it, null when there was nothing to add.
132
156
  */
133
157
  function writeEnvExample(dir, names) {
@@ -137,6 +161,7 @@ function writeEnvExample(dir, names) {
137
161
  let raw = fs.readFileSync(file, 'utf8');
138
162
  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
139
163
  const there = readEnvFile(file);
164
+ if (!isOwnExample(there)) return null;
140
165
  const add = (names || []).filter((name) => !(name in there));
141
166
  if (!add.length) return null;
142
167
  fs.appendFileSync(file, (raw.length && !raw.endsWith('\n') ? '\n' : '') + add.map((name) => name + '=yourpassword').join('\n') + '\n', { encoding: 'utf8' });
@@ -150,6 +175,11 @@ function writeEnvExample(dir, names) {
150
175
  }
151
176
  }
152
177
 
178
+ /** An example file holding only Kryptheon's names (or nothing yet). */
179
+ function isOwnExample(values) {
180
+ return Object.keys(values).every((name) => /^KRYPTHEON_/.test(name));
181
+ }
182
+
153
183
  // What must never be committed from a project: the real password. The three
154
184
  // files of machine state that used to be listed here - baselines, history and
155
185
  // test-results/ - are no longer written into the project at all; they live in
@@ -197,6 +227,7 @@ module.exports = {
197
227
  missingSecretLines: missingSecretLines,
198
228
  howToWriteEnv: howToWriteEnv,
199
229
  writeEnvExample: writeEnvExample,
230
+ isOwnExample: isOwnExample,
200
231
  updateGitignore: updateGitignore,
201
232
  GITIGNORE_ENTRIES: GITIGNORE_ENTRIES,
202
233
  isSet: isSet,