jevway 0.1.0 → 0.2.0

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;
+};

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;
+};