jevway 0.1.0 → 0.2.0

package/dist/cli/daemon-call.js

@@ -0,0 +1,78 @@
+import { resolve } from 'node:path';
+import { DaemonFailure } from '../daemon/client.js';
+import { outRoot } from '../output/layout.js';
+import { CliError, usageError } from './flags.js';
+import { eventPrinter } from './output.js';
+const BROWSER = /^(auto|launch|launch-headless|https?:\/\/\S+|wss?:\/\/\S+)$/;
+/** The browser and model a new session or one-shot run uses: the flags, else `JEVWAY_BROWSER` / `JEVWAY_MODEL` / `JEVWAY_SCREENSHOTS`. */
+export const runnerChoice = (flags, env) => {
+    const pick = (flag, variable) => (typeof flags[flag] === 'string' ? flags[flag] : env[variable]?.trim() || undefined);
+    const browser = pick('browser', 'JEVWAY_BROWSER') ?? 'auto';
+    if (!BROWSER.test(browser)) {
+        throw usageError('invalid_value', `--browser must be auto, launch, launch-headless or a debugging URL, got "${browser}"`, 'Example: --browser launch-headless');
+    }
+    const model = pick('model', 'JEVWAY_MODEL');
+    const screenshots = pick('screenshots', 'JEVWAY_SCREENSHOTS');
+    return { browser, ...(model && { model }), ...(screenshots && { screenshots }) };
+};
+/** A runner for `choice`; an unknown model or screenshot mode is a usage error. */
+export const runnerFor = (deps, { browser, ...choice }) => {
+    try {
+        return deps.createRunner(browser, choice);
+    }
+    catch (error) {
+        throw usageError('invalid_value', error.message, 'jevway run --help lists the models and screenshot modes');
+    }
+};
+/** Fails with `missing_key` (exit 2) before any browser or daemon starts when the model's key is not set. */
+export const requireKey = (runner) => {
+    try {
+        runner.requireKey();
+    }
+    catch (error) {
+        throw usageError('missing_key', error.message, 'Run jevway setup in a terminal, or see jevway doctor');
+    }
+};
+/** Where this caller's files go: resolved here, so they land under its working directory whoever started the daemon. */
+export const placement = ({ env, cwd }) => ({
+    outDir: outRoot(env, cwd),
+    ...(env.JEVWAY_JOURNEYS_DIR?.trim() && { journeysDir: resolve(cwd, env.JEVWAY_JOURNEYS_DIR.trim()) }),
+    cwd,
+});
+/** The running daemon, started when needed (a new session), or found (a session it should already hold). */
+export const daemonFor = async (deps, need) => {
+    if ('start' in need)
+        return deps.daemon.ensure(eventPrinter(deps.io));
+    const running = await deps.daemon.find();
+    if (running)
+        return running;
+    throw new CliError(1, 'unknown_session', `Unknown ${need.kind} "${need.session}": no jevway daemon is running, and sessions end when it stops (or after its idle time).`, need.kind === 'session' ? 'Start a new one with jevway run --session new --url <url> --goal <goal>' : 'Start a new one with jevway journey start --url <url>');
+};
+/**
+ * Calls the daemon and closes the connection. A connection lost mid-call is `outcome_unknown` for a call that may
+ * have clicked or typed (`writes`), pointing at `jevway look` for the session, else `daemon_unavailable`.
+ */
+export const callDaemon = async (connection, method, params, { writes, session, log, ...options }) => {
+    try {
+        return await connection.request(method, params, options);
+    }
+    catch (error) {
+        if (!(error instanceof DaemonFailure) || !error.lost)
+            throw error;
+        if (!writes)
+            throw new CliError(1, 'daemon_unavailable', error.message, `See ${log}; jevway stop and run the command again`);
+        const id = session?.();
+        throw new CliError(1, 'outcome_unknown', 'The daemon stopped answering while the call was running; it may already have clicked or typed.', id ? `Check the page with jevway look --session ${id} before repeating the call.` : 'Find the session with jevway sessions and check its page with jevway look --session <id> before repeating the call.');
+    }
+    finally {
+        connection.close();
+    }
+};
+/** How long a client waits for a call: always longer than the daemon's own limit for it. */
+export const TIMEOUTS = {
+    /** A task call: its time budget (`--max-seconds`, default 300; a continue may carry up to 3600) plus two minutes. */
+    task: (maxSeconds, continuing) => ((maxSeconds ?? (continuing ? 3600 : 300)) + 120) * 1000,
+    quick: 60_000,
+    /** Autopilot has no step limit of its own. */
+    journey: 30 * 60_000,
+};

package/dist/cli/dispatch.js

@@ -0,0 +1,74 @@
+import { DOCTOR_USAGE, runDoctor } from '../setup/doctor-command.js';
+import { SETUP_USAGE, runSetup } from '../setup/setup-command.js';
+import { SKILL_USAGE, runSkill } from '../setup/skill-command.js';
+import { closestName, usageError } from './flags.js';
+import { topHelp } from './help.js';
+import { journeyCommand } from './journey-command.js';
+import { lookCommand } from './look-command.js';
+import { printFailure } from './output.js';
+import { runCommand } from './run-command.js';
+import { endCommand, serveCommand, sessionsCommand, stopCommand } from './session-commands.js';
+const COMMANDS = {
+    run: { summary: 'hand a browser goal to Jev (one-shot, or a session with --session)', run: runCommand },
+    look: { summary: 'print what a page or a session\'s tab shows, with no model call', run: lookCommand },
+    journey: { summary: 'map mobile user journeys: start, step, autopilot, annotate, finish', run: journeyCommand },
+    sessions: { summary: 'list the open sessions and journeys', run: sessionsCommand },
+    end: { summary: 'end a session and close the tabs it opened', run: endCommand },
+    serve: { summary: 'run the session daemon in the foreground', run: serveCommand },
+    stop: { summary: 'stop the session daemon', run: stopCommand },
+    doctor: { summary: 'check the key, browser, Node and ffmpeg (--json for agents)', run: (argv, deps) => runDoctor(argv, deps.fromEnvFile), usage: DOCTOR_USAGE },
+    setup: { summary: 'set up the key, browser and MCP clients (interactive; --client <name> --print for agents)', run: (argv, deps) => runSetup(argv, deps.fromEnvFile), usage: SETUP_USAGE },
+    skill: { summary: 'print the agent skill, or --install it into a skills folder', run: (argv) => runSkill(argv), usage: SKILL_USAGE },
+};
+const printUsage = async (deps, usage) => {
+    await deps.io.out(usage.endsWith('\n') ? usage : `${usage}\n`);
+    return 0;
+};
+const commandList = () => [...Object.entries(COMMANDS).map(([name, { summary }]) => ({ name, summary })), { name: 'help [command]', summary: 'this help, or a command\'s' }];
+const unknownCommand = (name) => {
+    const meant = closestName(name, Object.keys(COMMANDS));
+    return usageError('unknown_command', `Unknown command "${name}"`, `${meant ? `Did you mean jevway ${meant}? ` : ''}See jevway --help`);
+};
+/**
+ * `jevway <argv>`: runs one command and returns its exit code. Every failure, expected or not, becomes one
+ * `{ ok: false, error }` document on stdout: never a stack trace.
+ *
+ * @example
+ * process.exitCode = await runCli(['run', '--url', 'https://example.com', '--goal', 'Open the docs'], deps);
+ */
+export const runCli = async (argv, deps) => {
+    try {
+        const [first, ...rest] = argv;
+        if (first === undefined) {
+            throw usageError('missing_command', 'No command given', 'Start with jevway run --url <url> --goal "<outcome>"; jevway --help lists the commands');
+        }
+        if (first === '--version' || first === '-v') {
+            await deps.io.out(`${deps.version}\n`);
+            return 0;
+        }
+        if (first === '--help' || first === '-h' || (first === 'help' && !rest.length)) {
+            await deps.io.out(topHelp(commandList()));
+            return 0;
+        }
+        if (first === 'help') {
+            const command = COMMANDS[rest[0]];
+            if (!command)
+                throw unknownCommand(rest[0]);
+            if (command.usage)
+                return await printUsage(deps, command.usage);
+            return await command.run([...rest.slice(1), '--help'], deps);
+        }
+        // Today's form: `jevway --goal … --url …` is `jevway run …`.
+        if (first.startsWith('-'))
+            return await runCommand(argv, deps);
+        const command = COMMANDS[first];
+        if (!command)
+            throw unknownCommand(first);
+        if (command.usage && (rest.includes('--help') || rest.includes('-h')))
+            return await printUsage(deps, command.usage);
+        return await command.run(rest, deps);
+    }
+    catch (error) {
+        return printFailure(deps.io, error);
+    }
+};

package/dist/cli/flags.js

@@ -0,0 +1,152 @@
+/**
+ * A failure the CLI prints as `{ ok: false, error: { code, message, hint } }` and exits with: 2 for bad usage, 1 for a
+ * tool error or a hand-back.
+ */
+export class CliError extends Error {
+    exitCode;
+    code;
+    hint;
+    constructor(exitCode, code, message, hint) {
+        super(message);
+        this.exitCode = exitCode;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export const usageError = (code, message, hint) => new CliError(2, code, message, hint);
+const distance = (a, b) => {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+};
+/**
+ * The name `word` most likely meant: the nearest within two edits, else one it starts or ends.
+ *
+ * @example
+ * closestName('vales', ['values', 'goal']) // 'values'
+ */
+export const closestName = (word, names) => {
+    const [nearest] = names.map((name) => ({ name, edits: distance(word, name) })).sort((a, b) => a.edits - b.edits);
+    if (nearest && nearest.edits <= 2)
+        return nearest.name;
+    return word.length >= 3 ? names.find((name) => name.startsWith(word) || word.startsWith(name)) : undefined;
+};
+const helpHint = (spec) => `See jevway ${spec.name} --help`;
+/**
+ * Reads `argv` against the command's flags: `--name value`, `--name=value`, booleans, and up to `positionals` plain
+ * arguments. `--help`/`-h` always parse. Anything else is a `CliError` (exit 2) naming it.
+ *
+ * @example
+ * parseFlags(runSpec, ['--goal', 'Open it', '--keep-open'], { positionals: 0 })
+ * // { flags: { goal: 'Open it', 'keep-open': true }, positionals: [] }
+ */
+export const parseFlags = (spec, argv, { positionals: allowed }) => {
+    const flags = {};
+    const positionals = [];
+    // Help wins over any other mistake on the line.
+    if (argv.some((arg) => arg === '--help' || arg === '-h'))
+        return { flags: { help: true }, positionals };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!arg.startsWith('-') || arg === '-' || /^-\d/.test(arg)) {
+            positionals.push(arg);
+            continue;
+        }
+        const [rawName, ...inline] = arg.replace(/^--?/, '').split('=');
+        const flag = spec.flags[rawName];
+        if (!flag || !arg.startsWith('--')) {
+            const meant = closestName(rawName, Object.keys(spec.flags));
+            throw usageError('unknown_flag', `Unknown flag ${arg.split('=')[0]}`, `${meant ? `Did you mean --${meant}? ` : ''}${helpHint(spec)}`);
+        }
+        if (flag.type === 'boolean') {
+            if (inline.length && !['true', 'false'].includes(inline.join('='))) {
+                throw usageError('invalid_value', `--${rawName} takes no value`, `Pass --${rawName} alone. ${helpHint(spec)}`);
+            }
+            flags[rawName] = inline.join('=') !== 'false';
+            continue;
+        }
+        const value = inline.length ? inline.join('=') : argv[i + 1];
+        if (value === undefined || (!inline.length && value.startsWith('--'))) {
+            throw usageError('missing_value', `--${rawName} needs a value`, `--${rawName} ${flag.value ?? '<value>'}. ${helpHint(spec)}`);
+        }
+        if (!inline.length)
+            i++;
+        flags[rawName] = value;
+    }
+    if (positionals.length > allowed) {
+        throw usageError('unexpected_argument', `Unexpected argument "${positionals[allowed]}"`, `Quote values that hold spaces. ${helpHint(spec)}`);
+    }
+    return { flags, positionals };
+};
+/**
+ * A JSON flag parsed and checked against `schema`; errors name the flag and show `example`.
+ *
+ * @example
+ * jsonFlag('values', '{"city":"Lisbon"}', VALUES, '{"city":"Lisbon"}') // { city: 'Lisbon' }
+ */
+export const jsonFlag = (name, raw, schema, example) => {
+    if (raw === undefined)
+        return undefined;
+    const hint = `Example: --${name} '${example}'`;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw usageError('invalid_value', `--${name}: ${error.message}`, hint);
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const where = issue?.path.length ? ` at ${issue.path.join('.')}` : '';
+        throw usageError('invalid_value', `--${name}: ${issue?.message ?? 'not valid'}${where}`, hint);
+    }
+    return result.data;
+};
+/** A whole number flag within `min`..`max`. */
+export const intFlag = (name, raw, { min, max }) => {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw.trim()) || value < min || value > max) {
+        throw usageError('invalid_value', `--${name} must be a whole number from ${min} to ${max}, got "${raw}"`, `Example: --${name} ${min}`);
+    }
+    return value;
+};
+/** A flag that must be one of `choices`. */
+export const choiceFlag = (name, raw, choices) => {
+    if (raw === undefined)
+        return undefined;
+    if (!choices.includes(raw)) {
+        throw usageError('invalid_value', `--${name} must be ${choices.slice(0, -1).join(', ')} or ${choices.at(-1)}, got "${raw}"`, `Example: --${name} ${choices.at(-1)}`);
+    }
+    return raw;
+};
+/** A comma-separated list, blanks dropped. */
+export const listFlag = (raw) => raw
+    ?.split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+const UNITS = { '': 1000, s: 1000, m: 60_000, h: 3_600_000 };
+/**
+ * A duration in milliseconds: plain seconds, or a number with `s`, `m` or `h`. `0` is 0 (callers read it as never).
+ *
+ * @example
+ * durationFlag('idle-timeout', '30m') // 1800000
+ */
+export const durationFlag = (name, raw) => {
+    const match = /^(\d+(?:\.\d+)?)\s*([smh]?)$/.exec(raw.trim());
+    if (!match)
+        throw usageError('invalid_value', `--${name} must be seconds or a number with s, m or h, got "${raw}"`, `Example: --${name} 1h (0 means never)`);
+    return Math.round(Number(match[1]) * UNITS[match[2]]);
+};

package/dist/cli/help.js

@@ -0,0 +1,46 @@
+const FLAG_COLUMN = 30;
+/**
+ * A command's help: examples first (agents copy those), then the usage line, the flags and the notes.
+ *
+ * @example
+ * renderHelp(lookSpec) // 'Examples:\n  jevway look --url https://example.com\n…'
+ */
+export const renderHelp = (spec) => {
+    const flags = Object.entries(spec.flags).map(([name, flag]) => {
+        const left = `  --${name}${flag.value ? ` ${flag.value}` : ''}`;
+        return `${left.padEnd(FLAG_COLUMN)} ${flag.describe}`;
+    });
+    return [
+        'Examples:',
+        ...spec.examples.map((example) => `  ${example}`),
+        '',
+        `jevway ${spec.name}${spec.argument ? ` ${spec.argument}` : ''} [flags]: ${spec.summary}`,
+        '',
+        'Flags:',
+        ...flags,
+        `${'  --help, -h'.padEnd(FLAG_COLUMN)} this help`,
+        ...(spec.notes?.length ? ['', ...spec.notes] : []),
+        '',
+    ].join('\n');
+};
+/** `jevway --help`: examples, then every command in one line each. */
+export const topHelp = (commands) => [
+    'Examples:',
+    '  jevway run --url https://en.wikipedia.org --goal "Open the article about the Rosetta Stone"',
+    '  jevway run --session new --browser launch-headless --url https://example.com/signup --goal "Sign up" --values \'{"email":"ada@example.com"}\'',
+    '  jevway run --session <id> --goal "Sign up" --values \'{"code":"123456"}\'',
+    '  jevway look --session <id>',
+    '  jevway sessions',
+    '  jevway end <id>',
+    '',
+    'jevway <command> [flags]: hand a browser goal to TypeSafe Jev and get one JSON result back.',
+    '',
+    'Commands:',
+    ...commands.map(({ name, summary }) => `  ${name.padEnd(18)} ${summary}`),
+    '',
+    'Output: one JSON document on stdout ({ "ok": true, … } or { "ok": false, "error": { code, message, hint } });',
+    'progress as NDJSON events on stderr. Exit 0 on success, 1 on a hand-back or a tool error, 2 on bad usage.',
+    '`jevway --goal …` is `jevway run --goal …`. `jevway help <command>` or `jevway <command> --help` for its flags.',
+    'Keys come from the environment or ~/.config/jevway/env (jevway setup, jevway doctor).',
+    '',
+].join('\n');

package/dist/cli/journey-command.js

@@ -0,0 +1,162 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { DEVICES } from '../browser/devices.js';
+import { callDaemon, daemonFor, placement, requireKey, runnerChoice, runnerFor, TIMEOUTS } from './daemon-call.js';
+import { choiceFlag, closestName, intFlag, jsonFlag, parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { printDoc } from './output.js';
+const ID = { journey: { type: 'string', value: '<id>', describe: 'the journey (or pass it as the argument)' } };
+const NOTES = { description: { type: 'string', value: '<text>', describe: 'what the screen is, for the viewer' }, insight: { type: 'string', value: '<text>', describe: 'a UX observation' } };
+const REPORT = ['Prints { ok: true, journey, screen: { id, screenshot: <absolute path>, … }, … }: the screen report the MCP tools return, with the screenshot\'s path instead of an inline image.'];
+const specs = {
+    start: {
+        name: 'journey start',
+        summary: 'open a URL on an emulated phone and map its first screen',
+        examples: ['jevway journey start --url https://stays.example --intent "find and open a stay in Lisbon"', 'jevway journey start --url https://app.example --device pixel-8 --browser launch-headless'],
+        flags: {
+            url: { type: 'string', value: '<url>', describe: 'the first screen' },
+            device: { type: 'string', value: '<name>', describe: `${Object.keys(DEVICES).join(', ')} (default iphone-15)` },
+            intent: { type: 'string', value: '<text>', describe: 'focus on one journey; leave out to explore core journeys' },
+            values: { type: 'string', value: '<json>', describe: 'text autopilot may type (search queries, fake names)' },
+            'stay-within': { type: 'string', value: '<url prefix>', describe: 'URL prefix autopilot must stay under (default the same origin)' },
+            'out-dir': { type: 'string', value: '<dir>', describe: 'the exact folder for the map (default .jevway/journeys/<stamp>_<host>_<id4>)' },
+            browser: { type: 'string', value: '<source>', describe: 'auto, launch, launch-headless or a debugging URL' },
+            model: { type: 'string', value: '<name>', describe: 'the decision model (default $JEVWAY_MODEL or jev)' },
+            screenshots: { type: 'string', value: 'off|fallback|always', describe: 'marked screenshots for vision models' },
+        },
+        notes: REPORT,
+    },
+    step: {
+        name: 'journey step',
+        argument: '<id>',
+        summary: 'move the journey one step and note what you learned about the screen you leave',
+        examples: ['jevway journey step <id> --next 3 --flow "Homes/Searching homes" --description "Search results"', 'jevway journey step <id> --next back'],
+        flags: {
+            ...ID,
+            next: { type: 'string', value: '<move>', describe: 'an element index from elements/jev.ranked_taps ("3:2" for an option), back, restart, scroll_down, scroll_up or screen:<id>' },
+            value: { type: 'string', value: '<text>', describe: 'type this into a text field' },
+            flow: { type: 'string', value: '<name>', describe: 'the flow the step belongs to; it sticks for later steps' },
+            ...NOTES,
+        },
+        notes: REPORT,
+    },
+    autopilot: {
+        name: 'journey autopilot',
+        argument: '<id>',
+        summary: 'let Jev explore: until the intent is reached, or for --screens new screens',
+        examples: ['jevway journey autopilot <id> --screens 5', 'jevway journey autopilot <id> --intent "open a stay" --flow "Booking"'],
+        flags: {
+            ...ID,
+            screens: { type: 'string', value: '<n>', describe: 'without an intent: check back after this many new screens (1 to 30)' },
+            flow: { type: 'string', value: '<name>', describe: 'record the steps under this flow' },
+            intent: { type: 'string', value: '<text>', describe: 'keep going until this is reached or a stop condition' },
+        },
+        notes: REPORT,
+    },
+    annotate: {
+        name: 'journey annotate',
+        argument: '<id>',
+        summary: 'describe a screen, or move steps into a named flow',
+        examples: ['jevway journey annotate <id> --screen s02 --description "Search results" --insight "Filters hide below the fold"', 'jevway journey annotate <id> --screen s03 --relabel \'{"from_step":2,"to_step":4,"flow":"Checkout"}\''],
+        flags: {
+            ...ID,
+            screen: { type: 'string', value: '<screen id>', describe: 'the screen, e.g. s02' },
+            ...NOTES,
+            relabel: { type: 'string', value: '<json>', describe: 'move steps [from_step..to_step] (0-based, see journey.json) into a flow' },
+        },
+    },
+    finish: {
+        name: 'journey finish',
+        argument: '<id>',
+        summary: 'write the final map and viewer, close the tab, and list screens still missing a description',
+        examples: ['jevway journey finish <id>', 'jevway journey finish <id> --keep-tab'],
+        flags: { ...ID, 'keep-tab': { type: 'boolean', describe: 'leave the tab open' } },
+    },
+};
+const overview = [
+    'Examples:',
+    '  jevway journey start --url https://stays.example --intent "find and open a stay in Lisbon"',
+    '  jevway journey step <id> --next 3 --description "Home with a search box"',
+    '  jevway journey autopilot <id> --screens 5',
+    '  jevway journey finish <id>',
+    '',
+    'jevway journey <start|step|autopilot|annotate|finish> [flags]: map mobile user journeys through the daemon.',
+    '',
+    ...Object.values(specs).map(({ name, summary }) => `  ${name.padEnd(18)} ${summary}`),
+    '',
+    'jevway journey <subcommand> --help for its flags. Use made-up data for any typing; stop at login, payment and send steps.',
+    '',
+].join('\n');
+const LABELS = z.record(z.string(), z.string());
+const RELABEL = z.object({ from_step: z.number().int(), to_step: z.number().int(), flow: z.string() });
+/** `jevway journey <subcommand>`: the journey tools through the daemon. */
+export const journeyCommand = async (argv, deps) => {
+    const [sub, ...rest] = argv;
+    if (sub === undefined || sub === '--help' || sub === '-h') {
+        await deps.io.out(overview);
+        return 0;
+    }
+    const spec = specs[sub];
+    if (!spec) {
+        const meant = closestName(sub, Object.keys(specs));
+        throw usageError('unknown_command', `Unknown command "journey ${sub}"`, `${meant ? `Did you mean jevway journey ${meant}? ` : ''}See jevway journey --help`);
+    }
+    const { flags, positionals } = parseFlags(spec, rest, { positionals: spec.argument ? 1 : 0 });
+    if (flags.help) {
+        await deps.io.out(renderHelp(spec));
+        return 0;
+    }
+    const text = (name) => (typeof flags[name] === 'string' ? flags[name] : undefined);
+    const reply = async (method, params, connection) => {
+        const result = await callDaemon(connection, method, params, { writes: method !== 'journey.annotate', log: deps.daemon.log, timeoutMs: TIMEOUTS.journey, session: () => params.journey ?? undefined });
+        await printDoc(deps.io, { ok: true, ...result });
+        return 0;
+    };
+    if (sub === 'start') {
+        const url = text('url');
+        if (!url)
+            throw usageError('missing_flag', 'jevway journey start needs --url', 'Example: jevway journey start --url https://stays.example');
+        if (!URL.canParse(url))
+            throw usageError('invalid_value', `--url must be an absolute URL, got "${url}"`, 'Example: --url https://stays.example');
+        const outDir = text('out-dir');
+        const request = {
+            url,
+            device: choiceFlag('device', text('device'), Object.keys(DEVICES)),
+            intent: text('intent'),
+            values: jsonFlag('values', text('values'), LABELS, '{"query":"Lisbon"}'),
+            stayWithin: text('stay-within'),
+            outDir: outDir && resolve(deps.cwd, outDir),
+        };
+        const choice = runnerChoice(flags, deps.env);
+        requireKey(runnerFor(deps, choice));
+        return reply('journey.start', { request, runner: choice, place: placement(deps) }, await daemonFor(deps, { start: true }));
+    }
+    const journey = positionals[0] ?? text('journey');
+    if (!journey)
+        throw usageError('missing_flag', `jevway ${spec.name} needs the journey id`, `Example: jevway ${spec.name} <id>`);
+    const connection = () => daemonFor(deps, { session: journey, kind: 'journey' });
+    const notes = { description: text('description'), insight: text('insight') };
+    switch (sub) {
+        case 'step': {
+            const next = text('next');
+            if (!next)
+                throw usageError('missing_flag', 'jevway journey step needs --next', 'Example: jevway journey step <id> --next 3');
+            const input = { next: /^\d+$/.test(next) ? Number(next) : next, value: text('value'), flow: text('flow'), ...notes };
+            return reply('journey.step', { journey, input }, await connection());
+        }
+        case 'autopilot': {
+            const input = { screens: intFlag('screens', text('screens'), { min: 1, max: 30 }), flow: text('flow'), intent: text('intent') };
+            return reply('journey.autopilot', { journey, input }, await connection());
+        }
+        case 'annotate': {
+            const screen = text('screen');
+            if (!screen)
+                throw usageError('missing_flag', 'jevway journey annotate needs --screen', 'Example: jevway journey annotate <id> --screen s02 --description "Search results"');
+            const relabel = jsonFlag('relabel', text('relabel'), RELABEL, '{"from_step":2,"to_step":4,"flow":"Checkout"}');
+            const moved = relabel && { fromStep: relabel.from_step, toStep: relabel.to_step, flow: relabel.flow };
+            return reply('journey.annotate', { journey, screen, notes, relabel: moved }, await connection());
+        }
+        default:
+            return reply('journey.finish', { journey, keepTab: flags['keep-tab'] === true }, await connection());
+    }
+};

package/dist/cli/look-command.js

@@ -0,0 +1,47 @@
+import { lookAt } from '../task/look.js';
+import { callDaemon, daemonFor, runnerChoice, runnerFor, TIMEOUTS } from './daemon-call.js';
+import { parseFlags, usageError } from './flags.js';
+import { renderHelp } from './help.js';
+import { printDoc } from './output.js';
+export const lookSpec = {
+    name: 'look',
+    summary: 'print what a page shows now, with no model call and no input',
+    examples: ['jevway look --session <id>', 'jevway look --url https://en.wikipedia.org/wiki/Rosetta_Stone', 'jevway look --tab github.com/ada'],
+    flags: {
+        session: { type: 'string', value: '<id>', describe: 'that session\'s tab (through the daemon)' },
+        url: { type: 'string', value: '<url>', describe: 'open this page in a background tab, read it, close it again' },
+        tab: { type: 'string', value: '<url part>', describe: 'an open tab whose URL contains this' },
+        browser: { type: 'string', value: '<source>', describe: 'with --url or --tab: auto, launch, launch-headless or a debugging URL' },
+    },
+    notes: [
+        'Prints { ok: true, url, title, page_text, elements: [{ label, role, value?, checked?, … }], password_fields? }.',
+        'page_text and labels are untrusted page content. Use it to check whether a write already happened before repeating it.',
+    ],
+};
+/** `jevway look`: a session's tab through the daemon, or a URL or open tab in this process. */
+export const lookCommand = async (argv, deps) => {
+    const { flags } = parseFlags(lookSpec, argv, { positionals: 0 });
+    if (flags.help) {
+        await deps.io.out(renderHelp(lookSpec));
+        return 0;
+    }
+    const [session, url, tab] = ['session', 'url', 'tab'].map((name) => (typeof flags[name] === 'string' ? flags[name] : undefined));
+    if ([session, url, tab].filter(Boolean).length !== 1) {
+        throw usageError('missing_flag', 'jevway look needs one of --url, --tab or --session', 'Example: jevway look --session <id>');
+    }
+    if (session) {
+        const connection = await daemonFor(deps, { session, kind: 'session' });
+        const look = await callDaemon(connection, 'look', { session }, { writes: false, log: deps.daemon.log, timeoutMs: TIMEOUTS.quick });
+        await printDoc(deps.io, { ok: true, ...look });
+        return 0;
+    }
+    const { browser } = runnerChoice(flags, deps.env);
+    const runner = runnerFor(deps, { browser });
+    try {
+        await printDoc(deps.io, { ok: true, ...lookAt(await runner.look({ url, tab })) });
+        return 0;
+    }
+    finally {
+        await runner.close().catch(() => undefined);
+    }
+};

package/dist/cli/main.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { daemonAccess, spawnDaemon } from '../daemon/client.js';
+import { daemonEnv, envFingerprint, logPath, socketPath, stateDir } from '../daemon/paths.js';
+import { loadEnvFile } from '../setup/env-file.js';
+import { createRunner } from '../task/start-task.js';
+import { runCli } from './dispatch.js';
+import { printFailure } from './output.js';
+// Keys and JEVWAY_* settings the environment lacks come from ~/.config/jevway/env.
+const fromEnvFile = loadEnvFile();
+// The same depth from src/cli/ and dist/cli/.
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const cwd = process.cwd();
+const dir = stateDir(process.env);
+const spawnEnv = daemonEnv(process.env, cwd);
+let printed = false;
+const io = {
+    // Awaited, so the document is flushed before exit: on macOS a piped stdout is asynchronous.
+    out: (text) => new Promise((resolve) => {
+        printed = true;
+        process.stdout.write(text, () => resolve());
+    }),
+    err: (text) => void process.stderr.write(text),
+};
+// Nothing escapes as a stack trace: an error before the result prints as the one JSON document; one after it is dropped.
+const lastResort = async (error) => {
+    if (!printed)
+        process.exit(await printFailure(io, error));
+};
+process.on('uncaughtException', lastResort);
+process.on('unhandledRejection', lastResort);
+let presses = 0;
+const onInterrupt = (handler) => {
+    const press = () => {
+        // A second Ctrl-C leaves at once.
+        if (++presses > 1)
+            process.exit(130);
+        handler();
+    };
+    process.on('SIGINT', press);
+    process.on('SIGTERM', press);
+    return () => {
+        process.off('SIGINT', press);
+        process.off('SIGTERM', press);
+    };
+};
+const code = await runCli(process.argv.slice(2), {
+    io,
+    env: process.env,
+    cwd,
+    version,
+    fromEnvFile,
+    createRunner,
+    daemon: daemonAccess({
+        socket: socketPath(dir),
+        log: logPath(dir),
+        version,
+        fingerprint: envFingerprint(spawnEnv),
+        start: () => spawnDaemon({ entry: fileURLToPath(import.meta.url), stateDir: dir, env: spawnEnv }),
+    }),
+    onInterrupt,
+});
+process.exit(code);

package/dist/cli/output.js

@@ -0,0 +1,27 @@
+import { DaemonFailure } from '../daemon/client.js';
+import { UnknownSession } from '../session/session-service.js';
+import { CliError } from './flags.js';
+// Daemon error codes that mean the command line itself was wrong.
+const USAGE_CODES = new Set(['unknown_flag', 'unknown_command', 'missing_flag', 'missing_value', 'invalid_value', 'unexpected_argument', 'missing_command', 'missing_key']);
+export const printDoc = async (io, doc) => {
+    await io.out(`${JSON.stringify(doc, null, 2)}\n`);
+};
+/** Writes each event as one JSON line on stderr. */
+export const eventPrinter = (io) => (event) => io.err(`${JSON.stringify(event)}\n`);
+/** Any failure as the CLI reports it: its exit code and the error body, never a stack trace. */
+export const describeFailure = (error) => {
+    if (error instanceof CliError)
+        return { exitCode: error.exitCode, code: error.code, message: error.message, hint: error.hint };
+    if (error instanceof DaemonFailure)
+        return { exitCode: USAGE_CODES.has(error.code) ? 2 : 1, code: error.code, message: error.message, hint: error.hint };
+    if (error instanceof UnknownSession)
+        return { exitCode: 1, code: error.code, message: error.message, hint: 'List the open ones with jevway sessions' };
+    const message = error instanceof Error ? error.message : String(error);
+    return { exitCode: 1, code: 'failed', message, hint: 'The message says what failed; jevway doctor checks the key and the browser.' };
+};
+/** Prints `{ ok: false, error }` for `error` and returns the exit code. */
+export const printFailure = async (io, error) => {
+    const { exitCode, ...body } = describeFailure(error);
+    await printDoc(io, { ok: false, error: body });
+    return exitCode;
+};