jevway 0.1.2 → 0.3.0

package/dist/notify/desktop.js

@@ -0,0 +1,40 @@
+import { execFile } from 'node:child_process';
+const NOTIFY_TIMEOUT_MS = 5000;
+const OFF = new Set(['off', '0', 'false', 'no']);
+const runProgram = (file, args) => new Promise((resolve) => execFile(file, args, { timeout: NOTIFY_TIMEOUT_MS }, () => resolve(undefined)));
+/**
+ * An AppleScript string literal for `text`: quotes and backslashes escaped.
+ *
+ * @example
+ * appleScriptString('Pass the "unusual traffic" check') // '"Pass the \\"unusual traffic\\" check"'
+ */
+export const appleScriptString = (text) => `"${text.replace(/[\\"]/g, '\\$&')}"`;
+/**
+ * The desktop notifier for this platform, titled "jevway": `osascript` on macOS, `notify-send` on Linux (nothing when
+ * it is not installed). Undefined on Windows and when `JEVWAY_NOTIFY` is `off` (or `0`, `false`, `no`).
+ *
+ * @example
+ * desktopNotifier()?.('Sign in to github.com in Chrome');
+ */
+export const desktopNotifier = ({ env = process.env, platform = process.platform, run = runProgram, } = {}) => {
+    if (OFF.has(env.JEVWAY_NOTIFY?.trim().toLowerCase() ?? ''))
+        return undefined;
+    const command = (message) => {
+        if (platform === 'darwin')
+            return ['osascript', ['-e', `display notification ${appleScriptString(message)} with title "jevway"`]];
+        if (platform === 'linux')
+            return ['notify-send', ['jevway', message]];
+        return undefined;
+    };
+    if (!command(''))
+        return undefined;
+    return (message) => {
+        const [file, args] = command(message);
+        try {
+            Promise.resolve(run(file, args)).catch(() => undefined);
+        }
+        catch {
+            // A notification is a courtesy: a missing program or a failed one never reaches the run.
+        }
+    };
+};

package/dist/notify/person-messages.js

@@ -0,0 +1,50 @@
+/**
+ * Every phrase jevway says to the person at a wall: the desktop notification, the countdown the agent relays, and the
+ * story line once it cleared. Built from the wall's kind, host and name only, never from the page's text.
+ */
+// '"unusual traffic" page' → 'the "unusual traffic" check'; 'Cloudflare' → 'the Cloudflare check'.
+const checkName = (check) => `the ${check.replace(/ page$/, '')} check`;
+// What the person does, as a phrase that follows "to" or starts a sentence once capitalised.
+const task = (wall) => {
+    switch (wall.kind) {
+        case 'bot_check':
+            return `pass ${checkName(wall.check)} in the Chrome window`;
+        case 'sign_in':
+            return `sign in to ${wall.host} in Chrome`;
+        case 'sso':
+            return `finish signing in with ${wall.provider} in Chrome`;
+    }
+};
+/**
+ * The desktop notification's body.
+ *
+ * @example
+ * notificationText({ kind: 'sign_in', host: 'github.com' }) // 'Sign in to github.com in Chrome'
+ */
+export const notificationText = (wall) => {
+    const text = task(wall);
+    return `${text[0].toUpperCase()}${text.slice(1)}`;
+};
+/**
+ * The countdown line the run tells while it waits.
+ *
+ * @example
+ * waitingText({ kind: 'bot_check', check: 'Cloudflare' }, 45) // 'Waiting for you to pass the Cloudflare check in the Chrome window (45 s left)'
+ */
+export const waitingText = (wall, secondsLeft) => `Waiting for you to ${task(wall)} (${secondsLeft} s left)`;
+/**
+ * The step a run's history and story carry once the person got past the wall.
+ *
+ * @example
+ * passedText({ kind: 'sso', provider: 'Google' }) // 'A person finished signing in with Google'
+ */
+export const passedText = (wall) => {
+    switch (wall.kind) {
+        case 'bot_check':
+            return `A person passed ${checkName(wall.check)}`;
+        case 'sign_in':
+            return `A person signed in to ${wall.host}`;
+        case 'sso':
+            return `A person finished signing in with ${wall.provider}`;
+    }
+};

package/dist/output/layout.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+const SLUG_CHARS = 40;
+const unchanged = (text) => text;
+/** Where jevway writes runs and journeys: `$JEVWAY_OUT_DIR`, else `./.jevway`, resolved against `cwd`. */
+export const outRoot = (env = process.env, cwd = process.cwd()) => resolve(cwd, env.JEVWAY_OUT_DIR || '.jevway');
+/** Creates the root with a `.gitignore` of `*`, written only when absent so an owner's own rules stand. */
+export const ensureOutRoot = (root) => {
+    mkdirSync(root, { recursive: true });
+    const ignore = join(root, '.gitignore');
+    if (!existsSync(ignore))
+        writeFileSync(ignore, '*\n');
+    return root;
+};
+/**
+ * Lowercase ASCII words joined by hyphens, at most 40 characters cut at a word; `run` when nothing is left.
+ *
+ * @example
+ * slugify('Réserver à São Paulo — 2 guests!') // 'reserver-a-sao-paulo-2-guests'
+ */
+export const slugify = (text, max = SLUG_CHARS) => {
+    const words = text
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!words)
+        return 'run';
+    if (words.length <= max)
+        return words;
+    const cut = words.slice(0, max);
+    const lastBreak = cut.lastIndexOf('-');
+    return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;
+};
+/** A slug that never holds a secret value: scrubbed before slugging, and the slug scrubbed and slugged once more. */
+export const safeSlug = (text, scrub = unchanged) => slugify(scrub(slugify(scrub(text))));
+const pad = (n) => String(n).padStart(2, '0');
+/** Local time as `2026-11-02_0905`: folders are browsed by people, and sort by start time. */
+export const folderStamp = (at) => `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}_${pad(at.getHours())}${pad(at.getMinutes())}`;
+/** `<stamp>_<goal-slug>_<first 4 of the session id>`. */
+export const runFolderName = ({ at, goal, id, scrub }) => `${folderStamp(at)}_${safeSlug(goal, scrub)}_${id.slice(0, 4)}`;
+/** `<stamp>_<host>_<first 4 of the journey id>`; a port's colon becomes a hyphen. */
+export const journeyFolderName = ({ at, host, id }) => `${folderStamp(at)}_${host.toLowerCase().replace(/[^a-z0-9.-]+/g, '-')}_${id.slice(0, 4)}`;
+/** `<stamp>_<host>_<first 4 of the look's id>`: a look's own folder under `looks/`, named like a journey's. */
+export const lookFolderName = journeyFolderName;
+const FILE_NAME_CHARS = 120;
+/**
+ * A name from outside (a site's suggested download name, a URL path) as one plain file name: no folders, no leading dots,
+ * no control or reserved characters, at most 120 characters with its extension kept; `fallback` when nothing is left.
+ *
+ * @example
+ * safeFileName('../../.ssh/config', 'cv') // 'config'
+ */
+export const safeFileName = (name, fallback) => {
+    const plain = (name.split(/[/\\]/).pop() ?? '')
+        .replace(/[\u0000-\u001f\u007f<>:"|?*]/g, '_')
+        .replace(/^[.\s]+/, '')
+        .trim();
+    if (!plain)
+        return fallback;
+    if (plain.length <= FILE_NAME_CHARS)
+        return plain;
+    const extension = extname(plain).slice(0, 16);
+    return plain.slice(0, FILE_NAME_CHARS - extension.length) + extension;
+};
+/**
+ * A path in `dir` for `name` that no file holds yet: `cv.pdf`, then `cv-2.pdf`, `cv-3.pdf`.
+ *
+ * @example
+ * uniqueFileName('/run/downloads', 'invoice.pdf') // '/run/downloads/invoice-2.pdf' when invoice.pdf is taken
+ */
+export const uniqueFileName = (dir, name) => {
+    const extension = extname(name);
+    const base = name.slice(0, name.length - extension.length);
+    let path = join(dir, name);
+    for (let n = 2; existsSync(path); n++)
+        path = join(dir, `${base}-${n}${extension}`);
+    return path;
+};
+/** A recorded step's shot, relative to its folder: `steps/01-type-destination.jpg`. */
+export const stepFileName = (n, slug) => `steps/${pad(n)}-${slug || 'step'}.jpg`;
+/** A call's end page, relative to its folder: `calls/02-needs-input.jpg`. */
+export const callShotName = (n, status) => `calls/${pad(n)}-${slugify(status)}.jpg`;
+/** A journey screen's screenshot, relative to its folder: `screens/s01-home.png`. */
+export const screenFileName = (id, type) => `screens/${id}-${slugify(type)}.png`;

package/dist/output/manifest.js

@@ -0,0 +1,86 @@
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const MANIFEST = 'manifest.json';
+/** Every file under `dir`, relative and sorted; dotfiles and dot-folders (`.frames` while encoding) are left out. */
+const filesUnder = (dir, base = dir) => readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => !entry.name.startsWith('.'))
+    .flatMap((entry) => (entry.isDirectory() ? filesUnder(join(dir, entry.name), base) : [relative(base, join(dir, entry.name))]))
+    .map((path) => path.split('\\').join('/'))
+    .sort();
+const readJson = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+/** What the folder's own records say about some of its files: step shots from `summary.json`, screens from `journey.json`. */
+const notesIn = (dir, kind) => {
+    const notes = new Map();
+    if (kind === 'run') {
+        const steps = readJson(join(dir, 'summary.json'))?.steps ?? [];
+        steps.forEach((step, i) => {
+            if (!step.file || !step.description)
+                return;
+            const finished = step.description.startsWith('Finished:');
+            notes.set(step.file, finished ? step.description : `Before step ${i + 1}, its target outlined: ${step.description}`);
+        });
+    }
+    else {
+        const screens = readJson(join(dir, 'journey.json'))?.screens ?? [];
+        for (const screen of screens)
+            if (screen.screenshot)
+                notes.set(screen.screenshot, `Screen ${screen.id} (${screen.type ?? 'unknown'}): ${screen.title ?? ''}`);
+    }
+    return notes;
+};
+/**
+ * One file as a manifest line: its kind from its name, and a description from the folder's records where they say more.
+ *
+ * @example
+ * describeFile('calls/02-needs-input.jpg', 'run', new Map()) // { path, kind: 'screenshot', description: 'The page as call 2 ended: needs_input' }
+ */
+export const describeFile = (path, kind, notes) => {
+    const line = (fileKind, description) => ({ path, kind: fileKind, description: oneLine(description) });
+    const call = /^calls\/(\d+)-(.+)\.jpg$/.exec(path);
+    if (path === MANIFEST)
+        return line('manifest', "This list of the folder's files");
+    if (path === 'index.html') {
+        return kind === 'run'
+            ? line('page', 'The run page for people: the video with every step on a timeline, and how each call ended')
+            : line('page', 'The journey map viewer: screens, flows and QA findings');
+    }
+    if (path === 'summary.json')
+        return line('summary', "Each call's summary (status, reason, steps, cost), plus the recorded steps when recorded");
+    if (path === 'journey.json')
+        return line('journey', 'The journey map as data: screens, steps, flows and QA findings');
+    if (path === 'run.mp4')
+        return line('video', 'Screencast of the whole session (idle stretches shortened)');
+    if (path === 'final.jpg')
+        return line('screenshot', 'The page as the latest call ended (viewport, JPEG)');
+    if (call)
+        return line('screenshot', `The page as call ${Number(call[1])} ended: ${call[2].replace(/-/g, '_')}`);
+    if (path.startsWith('steps/'))
+        return line('step', notes.get(path) ?? 'A recorded step, before its action');
+    if (path.startsWith('downloads/'))
+        return line('download', `Downloaded by a step of the run: ${path.slice('downloads/'.length)}`);
+    if (path.startsWith('uploads/'))
+        return line('upload', `Fetched from a URL the caller gave in files, then uploaded: ${path.slice('uploads/'.length)}`);
+    if (path.startsWith('looks/') && path.endsWith('.pdf'))
+        return line('pdf', `The page as a PDF, from a look: ${path}`);
+    if (path.startsWith('screens/'))
+        return line('screen', notes.get(path) ?? 'A journey screen');
+    return line('file', 'Not described');
+};
+/** Writes `manifest.json` for what `dir` holds now, itself included. */
+export const writeManifest = (dir, kind) => {
+    const notes = notesIn(dir, kind);
+    const paths = [...new Set([...filesUnder(dir), MANIFEST])].sort();
+    const manifest = { kind, files: paths.map((path) => describeFile(path, kind, notes)) };
+    writeFileSync(join(dir, MANIFEST), JSON.stringify(manifest, null, 1));
+    return join(dir, MANIFEST);
+};
+/** Reads a folder's `manifest.json`. */
+export const readManifest = (dir) => JSON.parse(readFileSync(join(dir, MANIFEST), 'utf8'));

package/dist/output/run-folder.js

@@ -0,0 +1,80 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { callShotName, ensureOutRoot, lookFolderName, slugify } from './layout.js';
+import { writeManifest } from './manifest.js';
+/** The files in `<dir>/downloads/`, by name. */
+const downloadsIn = (dir) => {
+    const folder = join(dir, 'downloads');
+    if (!existsSync(folder))
+        return [];
+    return readdirSync(folder, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && !entry.name.startsWith('.'))
+        .map((entry) => join(folder, entry.name))
+        .sort()
+        .map((path) => ({ path, name: path.slice(folder.length + 1), bytes: statSync(path).size }));
+};
+/**
+ * Writes what one call leaves in its run folder: its end page as `calls/NN-<status>.jpg` and `final.jpg` (a failed
+ * capture removes an older `final.jpg`, so it never shows another call's page), `summary.json` unless the recording
+ * wrote its own, and the manifest. Returns the folder's files.
+ *
+ * @example
+ * writeCall({ dir, call: 2, status: 'done', shot, summaries, recorded: false }) // { run_dir, screenshot: '…/final.jpg', manifest }
+ */
+export const writeCall = ({ dir, call, status, shot, summaries, recorded, }) => {
+    const root = resolve(dir);
+    mkdirSync(root, { recursive: true });
+    const final = join(root, 'final.jpg');
+    if (shot) {
+        const callShot = join(root, callShotName(call, status));
+        mkdirSync(dirname(callShot), { recursive: true });
+        writeFileSync(callShot, shot);
+        copyFileSync(callShot, final);
+    }
+    else
+        rmSync(final, { force: true });
+    // A recording that failed before writing its own leaves the folder without one.
+    if (!recorded || !existsSync(join(root, 'summary.json')))
+        writeFileSync(join(root, 'summary.json'), JSON.stringify({ summaries }, null, 1));
+    const manifest = writeManifest(root, 'run');
+    const page = join(root, 'index.html');
+    const video = join(root, 'run.mp4');
+    const downloads = downloadsIn(root);
+    return {
+        run_dir: root,
+        ...(shot && { screenshot: final }),
+        ...(recorded && existsSync(page) && { page }),
+        ...(recorded && existsSync(video) && { video }),
+        manifest,
+        ...(downloads.length && { downloads }),
+    };
+};
+/**
+ * Saves a session look's PDF as `looks/NN-<title>.pdf` in its run folder and refreshes the manifest. Returns its path.
+ *
+ * @example
+ * writeRunPdf({ dir, pdf, title: 'Checkout' }) // '<dir>/looks/01-checkout.pdf'
+ */
+export const writeRunPdf = ({ dir, pdf, title }) => {
+    const looks = join(resolve(dir), 'looks');
+    mkdirSync(looks, { recursive: true });
+    const n = readdirSync(looks).filter((name) => name.endsWith('.pdf')).length + 1;
+    const path = join(looks, `${String(n).padStart(2, '0')}-${slugify(title)}.pdf`);
+    writeFileSync(path, pdf);
+    writeManifest(resolve(dir), 'run');
+    return path;
+};
+/**
+ * Saves the PDF of a look with no session as `looks/<stamp>_<host>_<id4>/page.pdf` under the output root. Returns its path.
+ *
+ * @example
+ * writeLookPdf({ root, pdf, url: 'https://stays.example/pricing', at, id }) // '<root>/looks/2026-11-02_0905_stays.example_ab12/page.pdf'
+ */
+export const writeLookPdf = ({ root, pdf, url, at, id }) => {
+    const host = URL.canParse(url) ? new URL(url).host : '';
+    const dir = join(ensureOutRoot(root), 'looks', lookFolderName({ at, host: host || 'page', id }));
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'page.pdf');
+    writeFileSync(path, pdf);
+    return path;
+};

package/dist/recording/describe-step.js

@@ -0,0 +1,69 @@
+// The one wording of a step that people read: the recording's shots (what happens next) and a summary's story (what
+// happened). Kept apart from the recording so the pages and the story share it without importing the recorder.
+// Row labels carry a whole table row; a sentence needs its first words.
+const shorten = (label, max = 70) => {
+    const text = label.replace(/\s+/g, ' ').trim();
+    return text.length > max ? `${text.slice(0, max).replace(/\s+\S*$/, '')}…` : text;
+};
+// Each verb as Jev is about to do it (`next`, the recording's step shots) and as done (`done`, a summary's story).
+const VERBS = {
+    click: ['Click', 'Clicked'],
+    type: ['Type', 'Typed'],
+    choose: ['Choose', 'Chose'],
+    press: ['Press', 'Pressed'],
+    scroll: ['Scroll', 'Scrolled'],
+    wait: ['Wait', 'Waited'],
+    upload: ['Upload', 'Uploaded'],
+};
+/**
+ * A step as one plain sentence for people reading a recording (`next`, what happens on this screen) or a summary's
+ * story (`done`, what happened).
+ *
+ * @example
+ * describeStep({ operation: 'TYPE_TEXT', element: 'Search traces', valueKey: 'search_query' })
+ * // 'Type the "search_query" value into "Search traces"'
+ * describeStep({ operation: 'CLICK', element: 'Search' }, 'done') // 'Clicked "Search"'
+ */
+export const describeStep = ({ operation, element = '', valueKey, fileKey, option }, tense = 'next') => {
+    const target = `"${shorten(element)}"`;
+    const verb = (name) => VERBS[name][tense === 'next' ? 0 : 1];
+    switch (operation) {
+        case 'CLICK':
+            return `${verb('click')} ${target}`;
+        case 'CLICK_AT':
+            return `${verb('click')} the control at ${target} by its on-screen position`;
+        case 'TYPE_TEXT':
+            return `${verb('type')} the "${valueKey}" value into ${target}`;
+        case 'UPLOAD':
+            return fileKey ? `${verb('upload')} the "${fileKey}" file into ${target}` : `${verb('upload')} a file into ${target}`;
+        case 'SELECT':
+            return option ? `${verb('choose')} "${option}" in ${target}` : `${verb('choose')} an option in ${target}`;
+        case 'PRESS_ENTER':
+            return `${verb('press')} Enter in ${target} to submit it`;
+        case 'PRESS_ESCAPE':
+            return `${verb('press')} Escape to close the open menu or popup`;
+        case 'SCROLL_DOWN':
+            return `${verb('scroll')} down to reveal more of the page`;
+        case 'SCROLL_UP':
+            return `${verb('scroll')} back up`;
+        case 'WAIT':
+            return `${verb('wait')} for the page to finish updating`;
+        // Says itself: "A person passed the Cloudflare check".
+        case 'WAIT_FOR_PERSON':
+            return element;
+        default:
+            return `${operation} ${target}`;
+    }
+};
+const PAST = new Map(Object.values(VERBS));
+/**
+ * A recorded step's description (the `next` tense) in the past tense, as a sentence.
+ *
+ * @example
+ * pastTense('Type the "email" value into "Email"') // 'Typed the "email" value into "Email".'
+ */
+export const pastTense = (description) => {
+    const [verb] = description.split(' ', 1);
+    const told = PAST.has(verb) ? `${PAST.get(verb)}${description.slice(verb.length)}` : description;
+    return /[.!?]$/.test(told) ? told : `${told}.`;
+};