jevway 0.1.2 → 0.3.0

package/dist/recording/run-page.js

@@ -0,0 +1,155 @@
+import { BASE_STYLE, clock, dollars, embeddedJson, escapeHtml as escape, fact, FONT_STYLESHEET, GENERATOR_META, indexLabel, JEVWAY_VERSION, pathOf, playerMarkup, plural, PLAYER_SCRIPT, seconds, sentencesOf, statusLabel, statusTone, statusWord, storyOfRecording, thousands, } from './recording-page.js';
+const total = (summaries, pick) => summaries.reduce((sum, s) => sum + pick(s), 0);
+// Unknown when any call has no estimate (a model without a published rate).
+const estimatedCost = (summaries) => summaries.reduce((sum, s) => (sum === null || s.jev.est_cost_usd == null ? null : sum + s.jev.est_cost_usd), 0);
+// epoch seconds → "2026-11-01 18:39 UTC"
+const utc = (at) => `${new Date(at * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+const RUN_STYLE = `
+.run-top { padding-block: 2.5rem 0; display: grid; gap: 1.75rem; }
+.run-top .label { padding-top: 0.5rem; }
+.done-when { margin-top: 0.75rem; }
+.outcome-line { font-size: 1.125rem; line-height: 1.625rem; overflow-wrap: anywhere; }
+.status { display: inline-flex; align-items: center; gap: 0.5rem; font-weight: 500; margin-right: 0.5rem; }
+.status::before { content: ""; flex: none; width: 0.625rem; height: 0.625rem; border-radius: 99px; background: var(--muted-foreground); }
+.status.held::before { background: var(--held); } .status.reached::before { background: var(--reached); } .status.missed::before { background: var(--missed); }
+.glance { border-top: 1px solid var(--muted); padding-top: 1.25rem; grid-template-columns: repeat(2, minmax(0, 1fr)); row-gap: 1.25rem; }
+@media (min-width: 64rem) { .glance { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
+.glance dt { margin-bottom: 0.25rem; }
+.glance dd { font-size: 1.125rem; line-height: 1.5rem; font-weight: 500; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+.glance dd .small { display: block; font-weight: 400; }
+.run-top .facts .fact { padding-block: 0.875rem; }
+.block { margin-top: 4rem; }
+.block-head { margin-bottom: 1.5rem; }
+#recording .screen { margin-top: 0; }
+.call + .call { margin-top: 1.5rem; }
+.call-head { padding-top: 0.875rem; }
+.call-asked { margin-top: 0.25rem; }
+.story { border-bottom: 1px solid var(--muted); }
+.entry { display: grid; grid-template-columns: 2.25rem minmax(0, 1fr); gap: 0.125rem 0.75rem; padding: 0.875rem 0.75rem 0.875rem 0.5rem; border-top: 1px solid var(--muted); scroll-margin-top: 4rem; }
+.entry .n { padding-top: 0.2rem; }
+.entry .sentence { font-size: 1rem; line-height: 1.5rem; overflow-wrap: anywhere; }
+.entry .links { grid-column: 2; display: flex; flex-wrap: wrap; gap: 0.125rem 1rem; font-size: 0.75rem; line-height: 1.25rem; color: var(--muted-foreground); }
+.entry .links > * { min-width: 0; }
+.entry .where { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.entry .links a { text-decoration: underline; text-decoration-color: var(--muted); text-underline-offset: 3px; }
+.entry .links a:hover { color: var(--foreground); text-decoration-color: currentColor; }
+.entry.unshot .sentence { color: var(--muted-foreground); }
+.entry.ended .sentence { font-weight: 500; }
+.entry:target, .entry[aria-current="step"] { box-shadow: inset 2px 0 0 var(--foreground); background: color-mix(in oklch, var(--muted) 35%, transparent); }
+.entry[aria-current="step"] .n { color: var(--foreground); }
+.files dt { text-transform: none; letter-spacing: 0; font-family: var(--font-mono); }
+.files dd a { text-decoration: underline; text-decoration-color: var(--muted); text-underline-offset: 3px; }
+.run-page { padding-bottom: 4rem; }
+`;
+/** One line of a call's story: its number and sentence, then its time in the video, its shot file and its address. */
+const storyEntry = ({ sentence, shot }, steps, video) => {
+    if (shot === undefined)
+        return `<li class="entry unshot"><span class="n meta num" aria-hidden="true">·</span><p class="sentence">${escape(sentence)}</p></li>`;
+    const step = steps[shot];
+    const id = `s${shot + 1}`;
+    const name = step.file.split('/').pop();
+    const links = [
+        ...(video && step.video_at !== undefined ? [`<a class="at num" data-seek="${shot}" href="#${id}" aria-label="Play from step ${shot + 1}, at ${clock(step.video_at)}">${clock(step.video_at)}</a>`] : []),
+        `<a href="${escape(step.file)}">${escape(name)}</a>`,
+        `<span class="where">${escape(pathOf(step.url))}</span>`,
+    ];
+    const ended = step.operation === step.operation.toLowerCase();
+    return `<li class="entry${ended ? ' ended' : ''}" id="${id}" data-shot="${shot}"><span class="n meta num">${indexLabel(shot)}</span><p class="sentence">${escape(sentence)}</p><p class="links">${links.join('')}</p></li>`;
+};
+const callStories = (stories, record) => {
+    const several = stories.length > 1;
+    return stories
+        .map((story, n) => {
+        const asked = record.asked?.[n];
+        const before = record.asked?.[n - 1];
+        const differs = n > 0 && asked && before && (asked.goal !== before.goal || asked.done_when !== before.done_when);
+        const status = story.status ?? record.summaries[n]?.status;
+        const head = several ? `<h3 class="meta">Call ${n + 1}${status ? ` · ${escape(statusWord(status))}` : ''}</h3>` : '';
+        return `<div class="call grid4"><div class="call-head">${head}${differs ? `<p class="small call-asked">Asked: ${escape(asked.goal)}${asked.done_when ? `<br>Done when: ${escape(asked.done_when)}` : ''}</p>` : ''}</div><ol class="story c2s3">${story.entries.map((entry) => storyEntry(entry, record.steps, record.video)).join('')}</ol></div>`;
+    })
+        .join('\n');
+};
+/**
+ * The page for a recorded run folder, from its `summary.json` record. The top says what was asked, how the run ended
+ * and why, when, how long, what it cost, and where it started and ended; then the screencast (or the first shot); then
+ * each call's story, every step linking its shot file and its video time (`#s<n>`, also a deep link); then the
+ * details and the folder's files. The record itself is embedded as `#jevway-summary`.
+ *
+ * @example
+ * writeFileSync('runs/a/index.html', renderRunPage(JSON.parse(readFileSync('runs/a/summary.json', 'utf8'))));
+ */
+export const renderRunPage = (record) => {
+    const { summaries, steps, video, viewport } = record;
+    const last = summaries.at(-1);
+    const goal = record.asked?.[0]?.goal;
+    const doneWhen = record.asked?.[0]?.done_when;
+    // Actions that ran: a step told back to Jev as not done (`not_executed`) is in the story, not in the count.
+    const actions = total(summaries, (s) => s.steps.filter((step) => !step.not_executed).length);
+    const cost = estimatedCost(summaries);
+    const stories = storyOfRecording(steps, summaries);
+    const outcome = last ? statusLabel(last.status) : 'Recorded';
+    const title = `${outcome}${goal ? `: ${goal}` : ''} · jevway run`;
+    const bar = `<div class="player-bar grid4"><p class="meta c1s3">${plural(steps.length, 'step')}${video ? ' · pick one to play from there' : ''}</p><span class="meta clock c4 end">${video ? clock(0) : ''}</span></div>`;
+    const player = steps.length
+        ? playerMarkup({ dir: '', video, steps, label: 'this run', featured: true, viewport, bar, preload: 'metadata', sentences: sentencesOf(stories) })
+        : '<div class="screen quiet"><p class="small">No step was recorded.</p></div>';
+    const glance = [
+        ['Started', steps.length ? utc(steps[0].at) : 'unknown'],
+        ['Took', summaries.length ? seconds(total(summaries, (s) => s.elapsed_ms)) : 'unknown'],
+        ['Cost', `${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}<span class="small">${plural(total(summaries, (s) => s.jev.requests), 'Jev request')}</span>`],
+        ['Steps', `${plural(summaries.length, 'call')} · ${plural(actions, 'action')}`],
+    ];
+    const header = `<header class="wrapper run-top">
+<div class="grid4"><p class="meta label">Asked</p><div class="c2s3"><h1 class="job-title">${goal ? escape(goal) : 'Goal not recorded'}</h1>${doneWhen ? `<p class="small done-when"><span class="kv">Done when</span> ${escape(doneWhen)}</p>` : ''}${goal ? '' : '<p class="small done-when">This run was recorded before jevway kept the goal in its folder.</p>'}</div></div>
+<div class="grid4"><p class="meta label">Outcome</p><p class="c2s3 outcome-line">${last ? `<span class="status ${statusTone(last.status)}">${escape(outcome)}</span> ${escape(last.reason)}` : 'No call finished.'}</p></div>
+<dl class="glance grid4">${glance.map(([label, value]) => `<div><dt class="meta">${label}</dt><dd>${value}</dd></div>`).join('')}</dl>
+<dl class="facts">${[
+        ...(steps.length ? [fact('Start page', `<span class="address">${escape(steps[0].url)}</span>`)] : []),
+        ...(last ? [fact('End page', `<span class="address">${escape(last.url)}</span>${last.title ? ` · ${escape(last.title)}` : ''}`)] : []),
+    ].join('\n')}</dl>
+</header>`;
+    const details = [
+        ...(summaries.length ? [fact('Calls', `${escape(summaries.map((s) => statusWord(s.status)).join(' → '))} · ${plural(actions, 'action')}`)] : []),
+        ...(last ? [fact('Final page', `${escape(last.title)}<br><span class="address">${escape(last.url)}</span>`)] : []),
+        ...(summaries.length
+            ? [fact('Cost', `<span class="num">${plural(total(summaries, (s) => s.jev.requests), 'Jev request')} · ${thousands(total(summaries, (s) => s.jev.input_tokens))} input tokens · ${seconds(total(summaries, (s) => s.elapsed_ms))} · ${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}</span>`)]
+            : []),
+        ...(last?.jev.model ? [fact('Model', escape(last.jev.model))] : []),
+        ...(viewport ? [fact('Viewport', `<span class="num">${viewport.width} × ${viewport.height}</span> CSS pixels`)] : []),
+    ];
+    const files = [
+        fact('<a href="summary.json">summary.json</a>', "Each call's summary and the recorded steps: the same data this page embeds as <code>#jevway-summary</code>"),
+        fact('<a href="manifest.json">manifest.json</a>', 'Every file in this folder, with what it is'),
+        ...(video ? [fact(`<a href="${escape(video)}">${escape(video)}</a>`, 'Screencast of the whole session, idle stretches shortened')] : []),
+        fact('steps/', `${plural(steps.length, 'shot')}: one before each action, its target outlined, and one as each call ended; each step above links its own`),
+    ];
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${escape(title)}</title>
+<meta name="description" content="${escape(`${goal ?? 'A jevway run'}: ${outcome.toLowerCase()}${last ? `. ${last.reason}` : ''}`)}">
+${GENERATOR_META}
+<meta name="color-scheme" content="light dark">
+<link rel="alternate" type="application/json" href="summary.json" title="This run as data">
+${FONT_STYLESHEET}
+<style>${BASE_STYLE}${RUN_STYLE}</style>
+</head><body>
+<nav class="top" aria-label="This page"><div class="wrapper"><span>jevway · run</span><div class="links"><a href="#steps">Steps</a><a href="#details">Details</a><a href="#files">Files</a></div></div></nav>
+${header}
+<main class="wrapper run-page">
+<div class="run player current" data-step-links>
+<section id="recording" class="block" aria-labelledby="recording-title"><h2 class="block-head meta" id="recording-title">Recording</h2>
+${player}
+</section>
+<section id="steps" class="block" aria-labelledby="steps-title"><h2 class="section-title block-head" id="steps-title">Steps</h2>
+${callStories(stories, record)}
+</section>
+</div>
+<section id="details" class="block" aria-labelledby="details-title"><h2 class="section-title block-head" id="details-title">Details</h2><dl class="facts">${details.join('\n')}</dl></section>
+<section id="files" class="block" aria-labelledby="files-title"><h2 class="section-title block-head" id="files-title">Files</h2><dl class="facts files">${files.join('\n')}</dl></section>
+</main>
+<footer><div class="wrapper"><span>Recorded by jevway ${escape(JEVWAY_VERSION)} for people to read; the model never sees these shots.</span><span>${plural(steps.length, 'step')}${video ? ` · ${escape(video)}` : ' · no video (recording one needs ffmpeg)'}</span></div></footer>
+${embeddedJson('jevway-summary', record)}
+${PLAYER_SCRIPT}
+</body></html>
+`;
+};

package/dist/session/session-service.js

@@ -0,0 +1,213 @@
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { scrubberFor } from '../jev/secrets.js';
+import { ensureOutRoot, journeyFolderName, outRoot, runFolderName } from '../output/layout.js';
+import { writeLookPdf, writeRunPdf } from '../output/run-folder.js';
+import { lookAt } from '../task/look.js';
+import { storyLine } from '../task/present.js';
+import { checkTotpSecrets, totpMasks } from '../task/totp.js';
+/** A session id the service does not hold: it ended, expired, or never existed. `code` is for structured CLI errors. */
+export class UnknownSession extends Error {
+    code = 'unknown_session';
+}
+// 3600000 → '1 h', 1800000 → '30 min'.
+const idleWords = (ms) => (ms % 3_600_000 === 0 ? `${ms / 3_600_000} h` : `${Math.round(ms / 60_000)} min`);
+/**
+ * The sessions behind every adapter (the MCP server, the CLI daemon): task sessions and journeys by opaque UUID, each
+ * with its folder under the output root, calls that wait for a session's still-running call, and errors that say what
+ * to do next. Transport-free: adapters translate parameters in and present results out.
+ *
+ * @example
+ * const sessions = createSessionService(createRunner('auto'));
+ * const first = await sessions.task({ goal: 'Book a stay', url: 'https://stays.example' }, { onEvent: console.error });
+ * presentSummary(first); // { session, status: 'needs_input', next: 'Add the missing values …', story, files, … }
+ * await sessions.task({ goal: 'Book a stay', session: first.session, values: { email: 'ada@example.com' } });
+ * await sessions.end(first.session);
+ */
+export const createSessionService = (runner, options = {}) => {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const root = resolve(cwd, options.outDir ?? outRoot(env, cwd));
+    const now = options.now ?? (() => new Date());
+    const newId = options.newId ?? randomUUID;
+    const sessions = new Map();
+    const journeys = new Map();
+    const lifetime = `when the server restarts${options.idleMs ? ` or after ${idleWords(options.idleMs)} idle` : ''}`;
+    const findTask = (id) => {
+        const entry = sessions.get(id);
+        if (!entry)
+            throw new UnknownSession(`Unknown session "${id}". Sessions end ${lifetime}; start a new one with \`url\` (or \`tab\`).`);
+        entry.lastUsedAt = now();
+        return entry;
+    };
+    const findJourney = (id) => {
+        const entry = journeys.get(id);
+        if (!entry)
+            throw new UnknownSession(`Unknown journey "${id}". Journeys end when finished or ${lifetime}; start a new one with its \`url\`.`);
+        entry.lastUsedAt = now();
+        return entry;
+    };
+    const startTask = async ({ session: _session, record, recordDir, ...request }) => {
+        const id = newId();
+        const at = now();
+        const values = request.values ?? {};
+        // An authenticator key is secret for the session, even if a later call gives it a plain value.
+        const secretKeys = [...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})];
+        // A bad authenticator secret is refused before a tab opens.
+        const moreSecrets = totpMasks(checkTotpSecrets(request.totp, request.values));
+        const scrub = scrubberFor(values, secretKeys, moreSecrets);
+        const runDir = recordDir ? resolve(cwd, recordDir) : join(ensureOutRoot(root), 'runs', runFolderName({ at, goal: request.goal, id, scrub }));
+        const task = await runner.start({ ...request, output: { dir: runDir, record: Boolean(record || recordDir) } });
+        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, moreSecrets, runDir, startedAt: at, lastUsedAt: at };
+        sessions.set(id, entry);
+        return { id, entry };
+    };
+    const continueTask = async (id, request) => {
+        const entry = findTask(id);
+        await entry.running;
+        // Only what a later call may change: start-only fields (url, tab, coordinate clicks, recording) stay as started.
+        entry.task.update({
+            goal: request.goal,
+            values: request.values,
+            secretKeys: request.secretKeys,
+            files: request.files,
+            totp: request.totp,
+            doneWhen: request.doneWhen,
+            checks: request.checks,
+            maxSteps: request.maxSteps,
+            maxSeconds: request.maxSeconds,
+            waitForPersonSeconds: request.waitForPersonSeconds,
+            allowedHosts: request.allowedHosts,
+            blockedHosts: request.blockedHosts,
+            confirmIrreversible: request.confirmIrreversible,
+            confirmTarget: request.confirmTarget,
+        });
+        entry.values = { ...entry.values, ...request.values };
+        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})])];
+        entry.moreSecrets.push(...totpMasks(checkTotpSecrets(request.totp)));
+        entry.goal = scrubberFor(entry.values, entry.secretKeys, entry.moreSecrets)(request.goal);
+        return { id, entry };
+    };
+    const journeysRoot = () => env.JEVWAY_JOURNEYS_DIR ? resolve(cwd, env.JEVWAY_JOURNEYS_DIR) : join(ensureOutRoot(root), 'journeys');
+    const journeyReply = async (id, journey, report) => ({
+        journey: id,
+        report: report,
+        preview: await journey.preview(),
+    });
+    return {
+        /** The output root this service writes under. */
+        outDir: root,
+        /**
+         * Runs one call: a new session (with `url` or `tab`) or the next call of `session`, which first waits for that
+         * session's still-running call. `signal` cancels this call (the run ends `blocked` at its next check).
+         */
+        async task(request, { signal, onEvent } = {}) {
+            const { id, entry } = request.session ? await continueTask(request.session, request) : await startTask(request);
+            // A listener is the adapter's (progress, NDJSON): it never decides how the run goes.
+            const tell = (event) => {
+                try {
+                    onEvent?.(event);
+                }
+                catch {
+                    // ignored
+                }
+            };
+            tell({ type: 'started', session: id });
+            entry.busy = true;
+            const running = entry.task.run({
+                signal,
+                onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }),
+                onWait: ({ message, seconds_left }, url) => tell({ type: 'waiting', session: id, message, seconds_left, url }),
+            });
+            entry.running = running.catch(() => undefined);
+            try {
+                const summary = await running;
+                entry.status = summary.status;
+                entry.url = summary.url;
+                tell({ type: 'finished', session: id, status: summary.status });
+                const call = entry.task.lastCall;
+                return { session: id, summary, ...(call && { files: call.files }), ...(call?.screenshot && { screenshot: call.screenshot }) };
+            }
+            finally {
+                entry.busy = false;
+                entry.lastUsedAt = now();
+            }
+        },
+        /**
+         * Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or
+         * a URL opened and closed again. With `pdf`, the page is saved as a PDF too: in the session's run folder
+         * (`looks/NN-<title>.pdf`), else in a look folder of its own (`<root>/looks/<stamp>_<host>_<id4>/page.pdf`).
+         */
+        async look({ session, tab, url, pdf }) {
+            if ([session, tab, url].filter(Boolean).length !== 1)
+                throw new Error('Pass exactly one of session, tab or url.');
+            if (session) {
+                const entry = findTask(session);
+                const looked = await entry.task.look({ pdf });
+                return { ...lookAt(looked), ...(looked.pdf && { pdf: writeRunPdf({ dir: entry.runDir, pdf: looked.pdf, title: looked.title }) }) };
+            }
+            const looked = await runner.look({ url, tab, pdf });
+            return { ...lookAt(looked), ...(looked.pdf && { pdf: writeLookPdf({ root, pdf: looked.pdf, url: looked.url, at: now(), id: newId() }) }) };
+        },
+        /** Forgets a session and closes the tabs it opened (its first tab only when it started from `url`), unless `keepTab`. */
+        async end(session, { keepTab = false } = {}) {
+            const entry = findTask(session);
+            sessions.delete(session);
+            if (!keepTab)
+                await entry.task.closeTabs({ keepFirst: !entry.ownsTab });
+            return { session, run_dir: entry.runDir };
+        },
+        /** Every open task session and journey, oldest first, with what it is doing and where its files are. */
+        listSessions() {
+            const tasks = [...sessions].map(([session, entry]) => ({
+                session,
+                kind: 'task',
+                goal: entry.goal,
+                ...(entry.status && { status: entry.status }),
+                ...(entry.url && { url: entry.url }),
+                running: entry.busy,
+                started_at: entry.startedAt.toISOString(),
+                last_used_at: entry.lastUsedAt.toISOString(),
+                run_dir: entry.runDir,
+            }));
+            const maps = [...journeys].map(([session, entry]) => ({
+                session,
+                kind: 'journey',
+                url: entry.url,
+                started_at: entry.startedAt.toISOString(),
+                last_used_at: entry.lastUsedAt.toISOString(),
+                run_dir: entry.outDir,
+            }));
+            return [...tasks, ...maps].sort((a, b) => a.started_at.localeCompare(b.started_at));
+        },
+        /** Opens `url` on an emulated phone and maps its first screen, into `<root>/journeys/<stamp>_<host>_<id4>/` (or `outDir`). */
+        async journeyStart({ url, device, intent, values, stayWithin, outDir }) {
+            const id = newId();
+            const at = now();
+            const dir = outDir ? resolve(cwd, outDir) : join(journeysRoot(), journeyFolderName({ at, host: new URL(url).host, id }));
+            const journey = await runner.startJourney({ startUrl: url, device, intent, values, stayWithin, outDir: dir });
+            journeys.set(id, { journey, url, outDir: dir, startedAt: at, lastUsedAt: at });
+            return journeyReply(id, journey, journey.report());
+        },
+        async journeyStep(id, input) {
+            const { journey } = findJourney(id);
+            return journeyReply(id, journey, await journey.step(input));
+        },
+        async journeyAutopilot(id, input) {
+            const { journey } = findJourney(id);
+            return journeyReply(id, journey, await journey.autopilot(input));
+        },
+        journeyAnnotate(id, screen, notes, relabel) {
+            findJourney(id).journey.annotate(screen, notes, relabel);
+        },
+        /** Writes the final map, closes the journey's tab unless `keepTab`, and forgets the journey. */
+        async journeyFinish(id, { keepTab = false } = {}) {
+            const { journey, outDir } = findJourney(id);
+            const summary = await journey.finish({ closeTab: !keepTab });
+            journeys.delete(id);
+            return { ...summary, manifest: join(outDir, 'manifest.json') };
+        },
+        /** Closes the browser connection (a launched browser closes with it). */
+        close: () => runner.close(),
+    };
+};

package/dist/setup/atomic-write.js

@@ -0,0 +1,13 @@
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Writes `text` to a temporary file beside `path` and renames it into place, so an interrupted setup leaves the file
+ * either as it was or complete. `mode` applies to the result even where the file existed before.
+ */
+export const writeFileAtomic = (path, text, mode = 0o644) => {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.jevway-${process.pid}.tmp`;
+    writeFileSync(temporary, text, { mode });
+    chmodSync(temporary, mode);
+    renameSync(temporary, path);
+};

package/dist/setup/clients.js

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { envFilePath, shownEnvFilePath } from './env-file.js';
+import { unifiedDiff } from './unified-diff.js';
+const SERVER = { command: 'npx', args: ['-y', '-p', 'jevway', 'jevway-mcp'] };
+const xdgConfig = ({ home, env }) => env.XDG_CONFIG_HOME?.trim() || join(home, '.config');
+const claudeFolder = ({ home, env }) => env.CLAUDE_CONFIG_DIR?.trim() || join(home, '.claude');
+const claudeJson = (machine) => machine.env.CLAUDE_CONFIG_DIR?.trim() ? join(machine.env.CLAUDE_CONFIG_DIR.trim(), '.claude.json') : join(machine.home, '.claude.json');
+const codexFolder = ({ home, env }) => env.CODEX_HOME?.trim() || join(home, '.codex');
+const openCodeFolder = (machine) => join(xdgConfig(machine), 'opencode');
+const readText = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : undefined);
+const readJson = (path) => {
+    try {
+        const value = JSON.parse(readText(path) ?? '');
+        return value && typeof value === 'object' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+// A file that is not plain JSON (JSONC with comments) still counts when it names a jevway key.
+const namesJevway = (path, container) => {
+    const parsed = readJson(path);
+    if (parsed)
+        return Boolean(parsed[container]?.jevway);
+    return /"jevway"\s*:/.test(readText(path) ?? '');
+};
+const hasClaudePlugin = (machine) => Object.keys(readJson(join(claudeFolder(machine), 'plugins', 'installed_plugins.json'))?.plugins ?? {}).some((id) => id.startsWith('jevway@'));
+const openCodeFile = (machine) => {
+    const json = join(openCodeFolder(machine), 'opencode.json');
+    const jsonc = join(openCodeFolder(machine), 'opencode.jsonc');
+    return !existsSync(json) && existsSync(jsonc) ? jsonc : json;
+};
+/** The clients setup registers jevway with, in the order it offers them. */
+export const CLIENTS = [
+    {
+        name: 'claude-code',
+        label: 'Claude Code',
+        binary: 'claude',
+        markers: (machine) => [claudeFolder(machine), claudeJson(machine)],
+        skillsDir: (machine) => join(claudeFolder(machine), 'skills'),
+        hasSkillBundled: hasClaudePlugin,
+        isConfigured: (machine) => Boolean(readJson(claudeJson(machine))?.mcpServers?.jevway) || hasClaudePlugin(machine),
+        registration: { kind: 'command', argv: ['claude', 'mcp', 'add', 'jevway', '-s', 'user', '--', SERVER.command, ...SERVER.args] },
+    },
+    {
+        name: 'codex',
+        label: 'Codex',
+        binary: 'codex',
+        markers: (machine) => [codexFolder(machine)],
+        skillsDir: (machine) => join(codexFolder(machine), 'skills'),
+        isConfigured: (machine) => /^\s*\[mcp_servers\.(?:jevway|"jevway")\]/m.test(readText(join(codexFolder(machine), 'config.toml')) ?? ''),
+        registration: {
+            kind: 'command',
+            argv: ['codex', 'mcp', 'add', 'jevway', '--', SERVER.command, ...SERVER.args],
+            writes: {
+                file: (machine) => join(codexFolder(machine), 'config.toml'),
+                snippet: `[mcp_servers.jevway]\ncommand = "${SERVER.command}"\nargs = [${SERVER.args.map((arg) => `"${arg}"`).join(', ')}]\n`,
+            },
+        },
+    },
+    {
+        name: 'cursor',
+        label: 'Cursor',
+        binary: 'cursor',
+        markers: ({ home }) => [join(home, '.cursor')],
+        skillsDir: ({ home }) => join(home, '.cursor', 'skills'),
+        isConfigured: ({ home }) => namesJevway(join(home, '.cursor', 'mcp.json'), 'mcpServers'),
+        registration: { kind: 'config', file: ({ home }) => join(home, '.cursor', 'mcp.json'), container: 'mcpServers', entry: SERVER },
+    },
+    {
+        name: 'opencode',
+        label: 'OpenCode',
+        binary: 'opencode',
+        markers: (machine) => [openCodeFolder(machine)],
+        skillsDir: (machine) => join(openCodeFolder(machine), 'skills'),
+        isConfigured: (machine) => namesJevway(openCodeFile(machine), 'mcp'),
+        registration: {
+            kind: 'config',
+            file: openCodeFile,
+            container: 'mcp',
+            entry: { type: 'local', command: [SERVER.command, ...SERVER.args], enabled: true },
+            newFile: { $schema: 'https://opencode.ai/config.json' },
+        },
+    },
+];
+/** Names `--client` accepts: the known clients, and `other` for any stdio MCP client. */
+export const CLIENT_NAMES = [...CLIENTS.map(({ name }) => name), 'other'];
+/**
+ * Whether `binary` is an executable file in one of `PATH`'s folders. Scans the folders itself, never a shell, so a
+ * shell function or alias of the same name does not count.
+ */
+export const onPathIn = (path = process.env.PATH ?? '') => (binary) => path
+    .split(delimiter)
+    .filter(Boolean)
+    .some((folder) => (process.platform === 'win32' ? ['.exe', '.cmd', ''] : ['']).some((extension) => existsSync(join(folder, binary + extension))));
+/** `path` with the home folder written as `~`, for messages. */
+export const shownPath = (path, home) => (path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path);
+/**
+ * The clients installed on this machine (command on PATH or config present), and whether each already has a
+ * jevway server.
+ */
+export const detectClients = (machine) => CLIENTS.filter((client) => machine.onPath(client.binary) || client.markers(machine).some(existsSync)).map((client) => ({
+    client,
+    configured: client.isConfigured(machine),
+}));
+const indentOf = (text) => /^([ \t]+)\S/m.exec(text)?.[1] ?? '  ';
+const snippetFor = ({ container, entry }) => JSON.stringify({ [container]: { jevway: entry } }, null, 2);
+/**
+ * What setup would do to register jevway with `client`: run its `mcp add` command, or add only the `jevway` entry to
+ * its JSON config (the file's own indent kept, shown as a unified diff). A file that is not plain JSON, or whose server
+ * list is not an object, is never edited: the change is `manual`, with the snippet to add by hand.
+ *
+ * @example
+ * plannedChange(cursor, machine)
+ * // { kind: 'edit', file: '/Users/ada/.cursor/mcp.json', shownFile: '~/.cursor/mcp.json', next: '{…}', diff: '--- …' }
+ */
+export const plannedChange = (client, machine) => {
+    const { registration } = client;
+    if (registration.kind === 'command')
+        return { kind: 'command', argv: registration.argv, command: registration.argv.join(' ') };
+    const file = registration.file(machine);
+    const shownFile = shownPath(file, machine.home);
+    const before = readText(file);
+    const manual = (reason) => ({ kind: 'manual', file, shownFile, reason, snippet: snippetFor(registration) });
+    let config;
+    try {
+        config = before?.trim() ? JSON.parse(before) : { ...registration.newFile };
+    }
+    catch {
+        return manual(`${shownFile} is not plain JSON (comments or trailing commas), so setup leaves it alone`);
+    }
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return manual(`${shownFile} does not hold a JSON object`);
+    const servers = config[registration.container] ?? {};
+    if (typeof servers !== 'object' || Array.isArray(servers))
+        return manual(`"${registration.container}" in ${shownFile} is not an object`);
+    const next = `${JSON.stringify({ ...config, [registration.container]: { ...servers, jevway: registration.entry } }, null, before ? indentOf(before) : 2)}\n`;
+    return { kind: 'edit', file, shownFile, before, next, diff: unifiedDiff(before, next, shownFile) };
+};
+/**
+ * The exact command or config snippet that registers jevway with a client, and where it goes; for `other`, the
+ * server's command and args.
+ *
+ * @example
+ * printedRegistration('codex', machine)
+ * // { client: 'codex', kind: 'command', command: 'codex mcp add jevway -- npx …', file: '~/.codex/config.toml', snippet: '[mcp_servers.jevway]…' }
+ */
+export const printedRegistration = (name, machine) => {
+    const client = CLIENTS.find((candidate) => candidate.name === name);
+    if (!client)
+        return { client: 'other', kind: 'config', snippet: JSON.stringify(SERVER, null, 2) };
+    const { registration } = client;
+    if (registration.kind === 'command') {
+        const command = registration.argv.join(' ');
+        return registration.writes
+            ? { client: client.name, kind: 'command', command, file: shownPath(registration.writes.file(machine), machine.home), snippet: registration.writes.snippet }
+            : { client: client.name, kind: 'command', command, snippet: command };
+    }
+    return { client: client.name, kind: 'config', file: shownPath(registration.file(machine), machine.home), snippet: snippetFor(registration) };
+};
+/**
+ * `printedRegistration` as text: a `#` line saying what to do and where, then the command or snippet.
+ *
+ * @example
+ * renderPrinted(printedRegistration('cursor', machine))
+ * // '# Cursor: merge into "mcpServers" in ~/.cursor/mcp.json (keep the other servers)\n{\n  "mcpServers": …'
+ */
+export const renderPrinted = ({ client, kind, command, file, snippet }, env = process.env) => {
+    const label = CLIENTS.find(({ name }) => name === client)?.label;
+    const keyNote = `# The key stays in ${shownEnvFilePath(envFilePath(env))}, which jevway reads itself; never put it in this config.`;
+    if (!label)
+        return `# Any stdio MCP client: add a server named "jevway" that runs\n${snippet}\n${keyNote}\n`;
+    if (kind === 'command') {
+        const alternative = file && snippet !== command ? `# or add this to ${file} yourself:\n${snippet}` : '';
+        return `# ${label}: run\n${command}\n${alternative}${keyNote}\n`;
+    }
+    const container = Object.keys(JSON.parse(snippet))[0];
+    return `# ${label}: merge into "${container}" in ${file} (keep the other servers)\n${snippet}\n${keyNote}\n`;
+};

package/dist/setup/command-output.js

@@ -0,0 +1,15 @@
+/** Writes `text` to stdout and waits until it is flushed: on macOS a piped stdout is asynchronous. */
+export const print = (text) => new Promise((resolve) => process.stdout.write(text, () => resolve()));
+/** Prints `value` as indented JSON on stdout. */
+export const printJson = (value) => print(`${JSON.stringify(value, null, 2)}\n`);
+/**
+ * Prints the structured error agents read (`{ ok: false, error: { code, message, hint } }`) on stdout and returns
+ * `exitCode`, so a command can `return printError(…)`.
+ *
+ * @example
+ * return printError(2, 'usage', 'jevway skill: --install needs a folder', 'jevway skill --install ~/.claude/skills');
+ */
+export const printError = async (exitCode, code, message, hint) => {
+    await printJson({ ok: false, error: { code, message, hint } });
+    return exitCode;
+};