jevway 0.1.2 → 0.3.0

package/dist/setup/doctor-command.js

@@ -4,12 +4,18 @@ import { parseArgs } from 'node:util';
 import { devToolsActivePort, findChrome } from '../browser/chrome.js';
 import { createLiveAsk, resolveModel } from '../jev/model.js';
 import { replayDir } from '../jev/replay.js';
-import { diagnose, exitCode, liveCheck, planSteps, render } from './doctor.js';
+import { diagnose, doctorJson, exitCode, liveCheck, planSteps, render } from './doctor.js';
 import { envFilePath, shownEnvFilePath } from './env-file.js';
-const USAGE = `jevway doctor [--plan] [--live] [--browser <source>] [--model <name>]
+export const DOCTOR_USAGE = `Examples:
+  jevway doctor
+  jevway doctor --json
+  jevway doctor --plan --browser launch-headless
+
+jevway doctor [--plan | --json] [--live] [--browser <source>] [--model <name>]
 
   Checks Node, the API key and the route it selects, the browser source and ffmpeg. Never prints a key.
   --plan     print the setup steps still missing, numbered
+  --json     print { ready, findings: [{ check, level, message, fix? }] }
   --live     also make ONE real Jev request (costs a fraction of a cent)
   --browser  check this source instead of $JEVWAY_BROWSER (auto, launch, launch-headless or a URL)
   --model    check this model instead of $JEVWAY_MODEL
@@ -26,7 +32,8 @@ const envFileMode = () => {
         return undefined;
     }
 };
-const realProbes = (browser, model, fromEnvFile) => ({
+/** The doctor's view of this machine, for one browser source and model. */
+export const realProbes = (browser, model, fromEnvFile) => ({
     nodeVersion: process.versions.node,
     browser,
     model,
@@ -36,7 +43,7 @@ const realProbes = (browser, model, fromEnvFile) => ({
     devToolsActivePort,
     answers: (url) => fetch(url, { signal: AbortSignal.timeout(2_000) }).then(() => true, () => false),
     hasFfmpeg: () => new Promise((resolve) => execFile('ffmpeg', ['-version'], (error) => resolve(!error))),
-    ...(process.env.JEVWAY_REPLAY?.trim() && { replay: { mode: process.env.JEVWAY_REPLAY.trim(), dir: replayDir() } }),
+    ...(process.env.JEVWAY_REPLAY?.trim() && { replay: { mode: process.env.JEVWAY_REPLAY.trim(), dir: process.env.JEVWAY_REPLAY_DIR?.trim() ? replayDir() : '(JEVWAY_REPLAY_DIR is not set)' } }),
 });
 /**
  * `jevway doctor`: prints the report (or, with `--plan`, the steps left) and returns the exit code. `fromEnvFile` is
@@ -52,6 +59,7 @@ export const runDoctor = async (argv, fromEnvFile) => {
             args: argv,
             options: {
                 plan: { type: 'boolean' },
+                json: { type: 'boolean' },
                 live: { type: 'boolean' },
                 browser: { type: 'string' },
                 model: { type: 'string' },
@@ -60,11 +68,11 @@ export const runDoctor = async (argv, fromEnvFile) => {
         }));
     }
     catch (error) {
-        console.error(`jevway doctor: ${error.message}\n\n${USAGE}`);
+        console.error(`jevway doctor: ${error.message}\n\n${DOCTOR_USAGE}`);
         return 2;
     }
     if (options.help) {
-        console.log(USAGE);
+        console.log(DOCTOR_USAGE);
         return 0;
     }
     const findings = await diagnose(realProbes(options.browser ?? process.env.JEVWAY_BROWSER ?? 'auto', options.model, fromEnvFile));
@@ -76,6 +84,7 @@ export const runDoctor = async (argv, fromEnvFile) => {
         findings.push(await liveCheck(createLiveAsk(profile), profile.model, [process.env.TYPESAFE_API_KEY, process.env.OPENROUTER_API_KEY]));
     }
     // Written before the caller exits: on macOS a piped stdout is asynchronous.
-    await new Promise((resolve) => process.stdout.write(options.plan ? planSteps(findings) : render(findings), resolve));
+    const output = options.json ? `${JSON.stringify(doctorJson(findings), null, 2)}\n` : options.plan ? planSteps(findings) : render(findings);
+    await new Promise((resolve) => process.stdout.write(output, resolve));
     return exitCode(findings);
 };

package/dist/setup/doctor.js

@@ -45,8 +45,8 @@ const debuggingUrl = (source) => {
         return undefined;
     }
 };
-// Probes over plain HTTP only: opening the DevTools WebSocket would make the user's Chrome ask to allow it.
-const browserFinding = async ({ browser, findChrome, devToolsActivePort, answers }) => {
+/** The browser source's state, probed over plain HTTP only: the DevTools WebSocket would make Chrome ask to allow it. */
+export const browserFinding = async ({ browser, findChrome, devToolsActivePort, answers }) => {
     if (browser === 'launch' || browser === 'launch-headless') {
         const chrome = findChrome();
         return chrome
@@ -138,6 +138,21 @@ export const planSteps = (findings) => {
     ].map(({ level, fix }, index) => `${index + 1}. ${level === 'warn' ? '(optional) ' : ''}${fix}`);
     return steps.length ? `Steps left:\n${steps.join('\n')}\n` : 'Nothing left to set up: jevway is ready.\n';
 };
+/**
+ * `--json`: the findings for agents, each named by a stable `check` slug, and `ready` when nothing blocks.
+ *
+ * @example
+ * doctorJson(findings) // { ready: false, findings: [{ check: 'browser', level: 'fail', message: '…', fix: '…' }] }
+ */
+export const doctorJson = (findings) => ({
+    ready: exitCode(findings) === 0,
+    findings: findings.map(({ area, level, message, fix }) => ({
+        check: area.toLowerCase().replaceAll(' ', '_'),
+        level,
+        message,
+        ...(fix && level !== 'ok' && { fix }),
+    })),
+});
 /**
  * `--live`: one real request (the one-Choice evidence question, the cheapest the model is asked) to prove the key,
  * the route and the network. An error message has every key value replaced by `[secret]` before it is shown.

package/dist/setup/env-file.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parseEnv } from 'node:util';
+import { writeFileAtomic } from './atomic-write.js';
 // The keys and jevway's own settings; anything else (NODE_OPTIONS, PATH) could change how Node itself runs.
 const isJevwaySetting = (name) => ['TYPESAFE_API_KEY', 'OPENROUTER_API_KEY', 'CHROME_PATH'].includes(name) || name.startsWith('JEVWAY_');
 /**
@@ -48,3 +49,24 @@ export const missingKeyMessage = ({ name, apiKeyEnv }, env = process.env) => {
         ? `No API key: set TYPESAFE_API_KEY (Jev on the TypeSafe API) or OPENROUTER_API_KEY ${where}`
         : `No ${apiKeyEnv}: ${name} needs it. Set it ${where}`;
 };
+/**
+ * `text` with `name` set to `value`: the first `NAME=` line (or `export NAME=`) is replaced and later ones dropped, a
+ * missing name is appended, and `value` undefined removes the line. Every other line is kept as it was.
+ *
+ * @example
+ * setEnvValue('# mine\nTYPESAFE_API_KEY=old\n', 'TYPESAFE_API_KEY', 'new') // '# mine\nTYPESAFE_API_KEY=new\n'
+ */
+export const setEnvValue = (text, name, value) => {
+    const assigns = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=`);
+    const lines = text === '' ? [] : text.replace(/\n$/, '').split('\n');
+    const first = lines.findIndex((line) => assigns.test(line));
+    const kept = lines.flatMap((line, index) => {
+        if (!assigns.test(line))
+            return [line];
+        return index === first && value !== undefined ? [`${name}=${value}`] : [];
+    });
+    const next = first === -1 && value !== undefined ? [...kept, `${name}=${value}`] : kept;
+    return next.length ? `${next.join('\n')}\n` : '';
+};
+/** Writes the env file atomically with mode 600, creating its folder; a file other users could read becomes 600. */
+export const writeEnvFile = (path, text) => writeFileAtomic(path, text, 0o600);

package/dist/setup/setup-command.js

@@ -0,0 +1,104 @@
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+import { createLiveAsk, resolveModel } from '../jev/model.js';
+import { CLIENT_NAMES, onPathIn, printedRegistration, renderPrinted } from './clients.js';
+import { print, printError, printJson } from './command-output.js';
+import { realProbes } from './doctor-command.js';
+import { browserFinding, diagnose, exitCode, liveCheck, render } from './doctor.js';
+import { envFilePath, shownEnvFilePath } from './env-file.js';
+import { setupWizard } from './setup-wizard.js';
+import { bundledSkillDir } from './skill-command.js';
+import { terminalPrompter } from './terminal-prompter.js';
+const CLIENT_LIST = CLIENT_NAMES.join('|');
+export const SETUP_USAGE = `Examples:
+  jevway setup
+  jevway setup --client codex --print
+  jevway setup --client cursor --print --json
+
+jevway setup                                   interactive: key, browser, MCP clients (needs a terminal)
+jevway setup --client <${CLIENT_LIST}> --print [--json]
+                                               print how to register jevway with that client; changes nothing
+
+Examples:
+  jevway setup
+  jevway setup --client cursor --print
+  jevway setup --client codex --print --json   # { client, kind, command?, file?, snippet }`;
+const realMachine = () => ({ home: homedir(), env: process.env, onPath: onPathIn() });
+const isClientName = (name) => CLIENT_NAMES.includes(name);
+const liveFinding = async () => {
+    try {
+        const { profile } = resolveModel({ live: true });
+        return await liveCheck(createLiveAsk(profile), profile.model, [process.env.TYPESAFE_API_KEY, process.env.OPENROUTER_API_KEY]);
+    }
+    catch (error) {
+        return { level: 'fail', area: 'Live', message: error.message, fix: 'Run `jevway doctor` for the details' };
+    }
+};
+const runCommand = (argv) => new Promise((resolve) => execFile(argv[0], argv.slice(1), { timeout: 60_000 }, (error, stdout, stderr) => resolve({ ok: !error, output: `${stdout}${stderr}`.trim() || (error?.message ?? '') })));
+const realDeps = (fromEnvFile) => ({
+    machine: realMachine(),
+    envFile: envFilePath(),
+    fromEnvFile,
+    checkBrowser: (source) => browserFinding(realProbes(source, undefined, fromEnvFile)),
+    checkLive: liveFinding,
+    run: runCommand,
+    doctor: async () => {
+        const findings = await diagnose(realProbes(process.env.JEVWAY_BROWSER?.trim() || 'auto', undefined, fromEnvFile));
+        return { report: render(findings), ready: exitCode(findings) === 0 };
+    },
+    skillSource: bundledSkillDir(),
+});
+/** The env-file steps an agent hands to a person, who types the key in their own editor. */
+const envFileSteps = () => {
+    const path = shownEnvFilePath(envFilePath());
+    const folder = path.replace(/\/env$/, '');
+    return `mkdir -p ${folder} && touch ${path} && chmod 600 ${path}, then the person adds TYPESAFE_API_KEY=<key> in their own editor`;
+};
+/**
+ * `jevway setup`: with `--client <name> --print`, prints how to register jevway with that client and changes nothing;
+ * otherwise the interactive wizard, which needs a terminal and exits 2 without one.
+ *
+ * @example
+ * process.exit(await runSetup(process.argv.slice(3), loadEnvFile()));
+ */
+export const runSetup = async (argv, fromEnvFile = []) => {
+    let options;
+    try {
+        ({ values: options } = parseArgs({
+            args: argv,
+            options: {
+                client: { type: 'string' },
+                print: { type: 'boolean' },
+                json: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        }));
+    }
+    catch (error) {
+        return printError(2, 'usage', `jevway setup: ${error.message}`, `jevway setup --client <${CLIENT_LIST}> --print [--json]`);
+    }
+    if (options.help) {
+        await print(`${SETUP_USAGE}\n`);
+        return 0;
+    }
+    if (options.print || options.client !== undefined || options.json) {
+        if (!options.print || !options.client || !isClientName(options.client)) {
+            const problem = !options.print ? '--client and --json go with --print' : options.client ? `unknown client "${options.client}"` : '--print needs --client';
+            return printError(2, 'usage', `jevway setup: ${problem}`, `jevway setup --client <${CLIENT_LIST}> --print [--json]`);
+        }
+        const printed = printedRegistration(options.client, realMachine());
+        await (options.json ? printJson(printed) : print(renderPrinted(printed)));
+        return 0;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return printError(2, 'needs_tty', 'jevway setup asks questions and needs a terminal. An agent registers jevway with `jevway setup --client <name> --print` (add --json for the fields), which changes nothing.', `Key: ${envFileSteps()}. Client: jevway setup --client <${CLIENT_LIST}> --print. Check: jevway doctor --json.`);
+    }
+    const terminal = terminalPrompter();
+    try {
+        return await setupWizard(terminal.io, realDeps(fromEnvFile));
+    }
+    finally {
+        terminal.close();
+    }
+};

package/dist/setup/setup-wizard.js

@@ -0,0 +1,216 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { writeFileAtomic } from './atomic-write.js';
+import { detectClients, plannedChange, shownPath } from './clients.js';
+import { setEnvValue, writeEnvFile } from './env-file.js';
+import { installSkill, skillState } from './skill-command.js';
+const KEY_NAMES = ['TYPESAFE_API_KEY', 'OPENROUTER_API_KEY'];
+const KEY_ROUTES = [
+    { value: 'TYPESAFE_API_KEY', label: 'TypeSafe (recommended): Jev on the TypeSafe API, with screenshots and Box' },
+    { value: 'OPENROUTER_API_KEY', label: 'OpenRouter: Jev without Box, and the other models' },
+];
+const BROWSERS = [
+    { value: 'auto', label: `${'auto'.padEnd(16)}your running Chrome: allow it once at chrome://inspect/#remote-debugging; you see every step` },
+    { value: 'launch', label: `${'launch'.padEnd(16)}a throwaway Chrome profile jevway starts and closes, signed in nowhere` },
+    { value: 'launch-headless', label: `${'launch-headless'.padEnd(16)}the same, without a window` },
+    { value: 'port', label: `${'port'.padEnd(16)}a Chrome you started with --remote-debugging-port=<port> and its own --user-data-dir` },
+];
+const TRY_ON_CLI = `jevway --url https://en.wikipedia.org/wiki/Main_Page --goal "Open the Wikipedia article about the Rosetta Stone" --values '{"search_query":"Rosetta Stone"}'`;
+const confirm = async (io, question, fallback = false) => {
+    const reply = (await io.ask(`${question} ${fallback ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase();
+    return reply ? /^y(es)?$/.test(reply) : fallback;
+};
+const choose = async (io, question, options, fallback = 0) => {
+    options.forEach(({ label }, index) => io.say(`  ${index + 1}. ${label}`));
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const reply = (await io.ask(`${question} [${fallback + 1}] `)).trim();
+        if (!reply)
+            break;
+        const chosen = options[Number(reply) - 1] ?? options.find(({ value }) => value === reply);
+        if (chosen)
+            return chosen.value;
+        io.say(`Type a number from 1 to ${options.length}.`);
+    }
+    return options[fallback].value;
+};
+const formatFinding = ({ level, area, message, fix }) => `${level === 'fail' ? 'FAIL' : level}  ${area}: ${message}${level !== 'ok' && fix ? `\n      Fix: ${fix}` : ''}`;
+const readEnvText = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
+/**
+ * Why `key` cannot be an API key (too short, spaces, quotes or `#`), or undefined when its shape is plausible.
+ * The message never repeats the key.
+ */
+export const keyShapeProblem = (key) => {
+    if (key.length < 16)
+        return 'That is too short for an API key. Paste the whole key.';
+    if (/[^\x21-\x7e]|["'`#\\]/.test(key))
+        return 'An API key has no spaces, quotes or #. Paste just the key.';
+    return undefined;
+};
+const keyStep = async (io, { machine, envFile, fromEnvFile, checkLive }) => {
+    const shownFile = shownPath(envFile, machine.home);
+    io.say('\n1/3 The API key');
+    const existing = KEY_NAMES.find((name) => machine.env[name]?.trim());
+    if (existing) {
+        io.say(`${existing} is already set (from ${fromEnvFile.includes(existing) ? shownFile : 'your environment'}).`);
+        if (!(await confirm(io, 'Replace it?')))
+            return;
+    }
+    const name = await choose(io, 'Which route?', KEY_ROUTES);
+    let key;
+    for (let attempt = 0; attempt < 3 && !key; attempt++) {
+        const typed = (await io.askHidden(`Paste your ${name} (hidden as you type), then Enter: `)).trim();
+        const problem = keyShapeProblem(typed);
+        if (problem)
+            io.say(problem);
+        else
+            key = typed;
+    }
+    if (!key) {
+        io.say(`No key saved. Run jevway setup again, or add ${name}=<key> to ${shownFile} in your own editor.`);
+        return;
+    }
+    if (name === 'OPENROUTER_API_KEY' && !key.startsWith('sk-or-') && !(await confirm(io, 'That does not look like an OpenRouter key (they start sk-or-). Save it anyway?'))) {
+        io.say('No key saved.');
+        return;
+    }
+    writeEnvFile(envFile, setEnvValue(readEnvText(envFile), name, key));
+    io.say(`Saved ${name} to ${shownFile} (only you can read it; its other lines are kept).`);
+    if (machine.env[name]?.trim() && !fromEnvFile.includes(name)) {
+        io.say(`${name} is also set in your environment, which wins over the file: remove it there to use the new key.`);
+    }
+    else {
+        machine.env[name] = key;
+        if (!fromEnvFile.includes(name))
+            fromEnvFile.push(name);
+    }
+    if (await confirm(io, 'Check the key with one real request now? It costs a fraction of a cent.'))
+        io.say(formatFinding(await checkLive()));
+};
+const askPort = async (io) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const reply = (await io.ask('Port Chrome listens on [9222] ')).trim() || '9222';
+        if (/^\d+$/.test(reply) && Number(reply) > 0 && Number(reply) < 65536)
+            return `http://127.0.0.1:${reply}`;
+        io.say('Type a port number, such as 9222.');
+    }
+    return 'http://127.0.0.1:9222';
+};
+const browserStep = async (io, { machine, envFile, fromEnvFile, checkBrowser }) => {
+    const shownFile = shownPath(envFile, machine.home);
+    io.say('\n2/3 The browser jevway drives');
+    const current = machine.env.JEVWAY_BROWSER?.trim() || 'auto';
+    const currentIndex = BROWSERS.findIndex(({ value }) => value === (current.includes('://') ? 'port' : current));
+    let source;
+    for (;;) {
+        const choice = await choose(io, 'Which browser?', BROWSERS, Math.max(0, currentIndex));
+        source = choice === 'port' ? await askPort(io) : choice;
+        const finding = await checkBrowser(source);
+        io.say(formatFinding(finding));
+        if (finding.level !== 'fail' || !(await confirm(io, 'Choose another? (No keeps this one; fix it later.)')))
+            break;
+    }
+    const text = readEnvText(envFile);
+    const inFile = parseEnv(text).JEVWAY_BROWSER;
+    if (source === 'auto' && inFile !== undefined) {
+        writeEnvFile(envFile, setEnvValue(text, 'JEVWAY_BROWSER', undefined));
+        io.say(`Removed JEVWAY_BROWSER=${inFile} from ${shownFile}: auto is the default.`);
+    }
+    else if (source !== 'auto' && inFile !== source) {
+        writeEnvFile(envFile, setEnvValue(text, 'JEVWAY_BROWSER', source));
+        io.say(`Saved JEVWAY_BROWSER=${source} to ${shownFile}.`);
+    }
+    const fromShell = machine.env.JEVWAY_BROWSER?.trim() && !fromEnvFile.includes('JEVWAY_BROWSER');
+    if (fromShell && machine.env.JEVWAY_BROWSER !== source) {
+        io.say(`JEVWAY_BROWSER=${machine.env.JEVWAY_BROWSER} is set in your environment, which wins over the file.`);
+    }
+    else if (source === 'auto') {
+        delete machine.env.JEVWAY_BROWSER;
+    }
+    else {
+        machine.env.JEVWAY_BROWSER = source;
+    }
+};
+// Registers jevway with one client after showing exactly what changes; true when it is registered.
+const register = async (io, { machine, run }, client) => {
+    const change = plannedChange(client, machine);
+    if (change.kind === 'manual') {
+        io.say(`${client.label}: ${change.reason}. Add this to ${change.shownFile} yourself:\n${change.snippet}`);
+        return false;
+    }
+    if (change.kind === 'command') {
+        io.say(`${client.label}: setup will run\n  ${change.command}`);
+        if (!(await confirm(io, 'Run it?')))
+            return false;
+        const result = await run(change.argv);
+        io.say(result.ok ? `${client.label}: registered.` : `${client.label}: the command failed:\n${result.output.trim()}`);
+        return result.ok;
+    }
+    io.say(`${client.label}: setup will change ${change.shownFile}:\n${change.diff}`);
+    if (!(await confirm(io, `Write this change to ${change.shownFile}?`)))
+        return false;
+    if (readEnvText(change.file) !== (change.before ?? '')) {
+        io.say(`${client.label}: ${change.shownFile} changed meanwhile; nothing written. Run jevway setup again.`);
+        return false;
+    }
+    writeFileAtomic(change.file, change.next, change.before === undefined ? 0o644 : statSync(change.file).mode & 0o777);
+    io.say(`${client.label}: registered in ${change.shownFile}.`);
+    return true;
+};
+const offerSkill = async (io, { machine, skillSource }, client) => {
+    if (client.hasSkillBundled?.(machine))
+        return;
+    const folder = client.skillsDir(machine);
+    const shown = shownPath(join(folder, 'jevway'), machine.home);
+    const state = skillState(skillSource, folder);
+    if (state === 'same')
+        return io.say(`${client.label}: the jevway skill is already in ${shown}.`);
+    const question = state === 'different'
+        ? `Replace the jevway skill in ${shown} with this version's?`
+        : `Copy the jevway skill to ${shown}? It tells the agent when to hand a browser goal to jevway.`;
+    if (!(await confirm(io, question)))
+        return;
+    installSkill(skillSource, folder, { force: true });
+    io.say(`${client.label}: skill copied to ${shown}.`);
+};
+const clientsStep = async (io, deps) => {
+    io.say('\n3/3 Your MCP clients');
+    const found = detectClients(deps.machine);
+    if (!found.length) {
+        io.say('No Claude Code, Codex, Cursor or OpenCode found. For another MCP client: jevway setup --client other --print');
+        return [];
+    }
+    const registered = [];
+    for (const { client, configured } of found) {
+        if (configured)
+            io.say(`${client.label}: jevway is already registered; skipped.`);
+        if (configured || (await register(io, deps, client)))
+            registered.push(client.label);
+        await offerSkill(io, deps, client);
+    }
+    return registered;
+};
+/**
+ * The interactive setup: the key (hidden, into the env file only), the browser (tested before it is saved), and each
+ * MCP client found (every change shown, made only on a yes), then the doctor's report and what to try first. Returns
+ * 0 when the doctor finds jevway ready, 1 otherwise.
+ *
+ * @example
+ * process.exitCode = await setupWizard(terminal.io, realDeps);
+ */
+export const setupWizard = async (io, deps) => {
+    io.say(`jevway setup: the API key, the browser, then your MCP clients. Ctrl-C stops at any point; every file is either left as it was or written whole.`);
+    await keyStep(io, deps);
+    await browserStep(io, deps);
+    const registered = await clientsStep(io, deps);
+    io.say('\nChecking the setup (jevway doctor):');
+    const { report, ready } = await deps.doctor();
+    io.say(report.trimEnd());
+    if (!ready)
+        io.say('Try first: fix the FAIL lines above (`jevway doctor --plan` lists them), then run `jevway doctor` again.');
+    else if (registered.length)
+        io.say(`Try first: restart ${registered.join(' or ')} and ask it to "use jevway to open the Wikipedia article about the Rosetta Stone".`);
+    else
+        io.say(`Try first: ${TRY_ON_CLI}`);
+    return ready ? 0 : 1;
+};

package/dist/setup/skill-command.js

@@ -0,0 +1,124 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { print, printError, printJson } from './command-output.js';
+export const SKILL_USAGE = `Examples:
+  jevway skill
+  jevway skill --install ~/.claude/skills
+
+jevway skill [--name jevway-inbox]       print the SKILL.md this version ships (default jevway)
+jevway skill --install <dir> [--force]   copy both skill folders into <dir>/jevway and <dir>/jevway-inbox
+
+Examples:
+  jevway skill --install ~/.claude/skills
+  jevway skill --install ~/.codex/skills
+
+--install prints { ok, status: installed|unchanged|replaced, path, files } for jevway and the same for each skill in
+skills: [{ name, … }]. jevway-inbox is a standalone disposable inbox script for agents without jevway. A different
+skill already in either folder (or a symlink to one) is left alone, and nothing is copied, unless --force is given.`;
+/** The skills this package ships, by folder name; `--install` copies them all. */
+const BUNDLED_SKILLS = ['jevway', 'jevway-inbox'];
+/** A `skill/<name>/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
+const bundledSkillFolder = (name) => fileURLToPath(new URL(`../../skill/${name}/`, import.meta.url));
+/** The `skill/jevway/` folder of the installed package. */
+export const bundledSkillDir = () => bundledSkillFolder('jevway');
+/** Every file under `dir`, as sorted paths relative to it. */
+const filesIn = (dir) => readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+    .sort();
+/** True when `target` holds exactly the files of `source`, byte for byte (following a symlinked `target`). */
+const sameFolder = (source, target) => {
+    try {
+        const files = filesIn(source);
+        return (files.join('\n') === filesIn(target).join('\n') &&
+            files.every((file) => readFileSync(join(source, file)).equals(readFileSync(join(target, file)))));
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether `<parent>/<name>` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
+export const skillState = (source, parent, name = 'jevway') => {
+    const path = join(parent, name);
+    if (!existsSync(path) && !lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+        return 'missing';
+    return sameFolder(source, path) ? 'same' : 'different';
+};
+/**
+ * Copies `source` to `<parent>/<name>` (default `jevway`). An identical copy is left as it is; a different folder or a
+ * symlink is replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary
+ * name first, so an interrupted install never leaves half a skill.
+ *
+ * @example
+ * installSkill(bundledSkillDir(), '/Users/ada/.claude/skills', { force: false })
+ * // { status: 'installed', path: '/Users/ada/.claude/skills/jevway', files: ['SKILL.md'] }
+ */
+export const installSkill = (source, parent, { force, name = 'jevway' }) => {
+    const path = join(parent, name);
+    const files = filesIn(source);
+    const state = skillState(source, parent, name);
+    if (state === 'same')
+        return { status: 'unchanged', path, files };
+    if (state === 'different' && !force)
+        return { status: 'exists', path };
+    const present = state === 'different';
+    mkdirSync(parent, { recursive: true });
+    const incoming = join(parent, `.${name}-${process.pid}.incoming`);
+    cpSync(source, incoming, { recursive: true });
+    if (present)
+        rmSync(path, { recursive: true, force: true });
+    renameSync(incoming, path);
+    return { status: present ? 'replaced' : 'installed', path, files };
+};
+/**
+ * Installs every bundled skill into `parent`, or none: a different folder for any of them, without `force`, is
+ * `exists` with its path and nothing is copied.
+ */
+export const installSkills = (parent, { force }) => {
+    const different = BUNDLED_SKILLS.filter((name) => skillState(bundledSkillFolder(name), parent, name) === 'different');
+    if (different.length && !force)
+        return { status: 'exists', paths: different.map((name) => join(parent, name)) };
+    return {
+        status: 'done',
+        skills: BUNDLED_SKILLS.map((name) => ({ name, ...installSkill(bundledSkillFolder(name), parent, { force, name }) })),
+    };
+};
+/**
+ * `jevway skill`: prints the bundled SKILL.md, or with `--install <dir>` copies the skill folder into `<dir>/jevway`.
+ *
+ * @example
+ * process.exit(await runSkill(process.argv.slice(3)));
+ */
+export const runSkill = async (argv) => {
+    let options;
+    try {
+        ({ values: options } = parseArgs({
+            args: argv,
+            options: { install: { type: 'string' }, name: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+        }));
+    }
+    catch (error) {
+        return printError(2, 'usage', `jevway skill: ${error.message}`, 'jevway skill --install <dir> [--force]');
+    }
+    if (options.help) {
+        await print(`${SKILL_USAGE}\n`);
+        return 0;
+    }
+    if (options.install === undefined) {
+        const name = options.name ?? 'jevway';
+        if (!BUNDLED_SKILLS.includes(name)) {
+            return printError(2, 'usage', `jevway skill: --name must be ${BUNDLED_SKILLS.join(' or ')}, got "${name}"`, 'jevway skill --name jevway-inbox');
+        }
+        await print(readFileSync(join(bundledSkillFolder(name), 'SKILL.md'), 'utf8'));
+        return 0;
+    }
+    const result = installSkills(options.install, { force: Boolean(options.force) });
+    if (result.status === 'exists') {
+        return printError(1, 'skill_exists', `${result.paths.join(' and ')} already ${result.paths.length === 1 ? 'holds a different skill' : 'hold different skills'} (or a link to one); nothing was copied`, `Run again with --force to replace them with this version's skills: jevway skill --install ${options.install} --force`);
+    }
+    const [{ name: _name, ...jevway }] = result.skills;
+    await printJson({ ok: true, ...jevway, skills: result.skills });
+    return 0;
+};

package/dist/setup/terminal-prompter.js

@@ -0,0 +1,51 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+/**
+ * The real terminal for setup. Hidden answers are read through readline with its echo sent to a muted stream, and
+ * readline keeps no history, so a key is never drawn on screen nor kept after the question. Ctrl-C (or Ctrl-D) exits
+ * 130 at once: setup writes every file whole, so nothing is left half-written.
+ */
+export const terminalPrompter = () => {
+    let muted = false;
+    let closing = false;
+    const echo = new Writable({
+        write(chunk, encoding, done) {
+            if (!muted)
+                process.stdout.write(chunk, encoding);
+            done();
+        },
+    });
+    Object.defineProperty(echo, 'columns', { get: () => process.stdout.columns });
+    const rl = createInterface({ input: process.stdin, output: echo, terminal: true, historySize: 0 });
+    const stop = () => {
+        if (closing)
+            return;
+        muted = false;
+        process.stdout.write('\nStopped. Every file is as it was before, or written whole.\n');
+        process.exit(130);
+    };
+    rl.on('SIGINT', stop);
+    rl.on('close', stop);
+    const io = {
+        say: (text) => void process.stdout.write(`${text}\n`),
+        ask: (question) => rl.question(question),
+        askHidden: async (question) => {
+            process.stdout.write(question);
+            muted = true;
+            try {
+                return await rl.question('');
+            }
+            finally {
+                muted = false;
+                process.stdout.write('\n');
+            }
+        },
+    };
+    return {
+        io,
+        close: () => {
+            closing = true;
+            rl.close();
+        },
+    };
+};