@reticlehq/server 2.14.0 → 3.2.0

package/dist/cli/cli-launch.js

@@ -1,223 +0,0 @@
-import * as http from 'node:http';
-import { NodePlatform } from '../platform.js';
-import { spawn } from 'node:child_process';
-import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
-import { daemonFix, describeSkew } from '../version/version-skew.js';
-import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
-import { SERVER_VERSION } from '../version/server-version.js';
-import { log } from '../log.js';
-import { loopbackAgent } from '../loopback-agent.js';
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export function summarizeStatus(payload) {
-    if (typeof payload !== 'object' || null === payload)
-        return { sessionCount: 0, sessions: [] };
-    const obj = payload;
-    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
-    // here would silently undo the reason it is on the wire.
-    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
-    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
-    const sessions = raw
-        .map((s) => {
-        if (typeof s !== 'object' || null === s)
-            return null;
-        const r = s;
-        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
-        if ('' === sessionId)
-            return null;
-        return {
-            sessionId,
-            url: 'string' === typeof r['url'] ? r['url'] : '',
-            throttled: true === r['throttled'],
-            stale: true === r['stale'],
-            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
-            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
-        };
-    })
-        .filter((s) => s !== null);
-    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
-    return { sessionCount, sessions, ...(why === undefined ? {} : { why }) };
-}
-/** A string field off the /status body, or undefined on a daemon too old to report it. */
-function statusField(payload, key) {
-    if (typeof payload !== 'object' || null === payload)
-        return undefined;
-    const value = payload[key];
-    return 'string' === typeof value && value.length > 0 ? value : undefined;
-}
-/**
- * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
- *
- * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
- * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
- * another agent's session on a version bump, which is worse than a loud line.
- */
-export async function warnOnDaemonSkew(port) {
-    const status = await fetchStatus(port);
-    const daemonVersion = statusField(status, 'version');
-    const skew = describeSkew({
-        what: 'the daemon already running on this port',
-        version: daemonVersion,
-        contract: statusField(status, 'contract'),
-        // The daemon is the peer here and this process is the agent side.
-        fix: daemonFix(daemonVersion, SERVER_VERSION),
-    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
-    if (skew !== undefined)
-        log('reticle_daemon_skew', { port, warning: skew });
-}
-/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
-const STATUS_PROBE_TIMEOUT_MS = 1000;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export function fetchStatus(port) {
-    return new Promise((resolve) => {
-        const req = http.get({
-            host: LOOPBACK_HOST,
-            port,
-            path: STATUS_PATH,
-            timeout: STATUS_PROBE_TIMEOUT_MS,
-            // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
-            // per probe is the same churn the POST leg was fixed for.
-            agent: loopbackAgent,
-        }, (res) => {
-            let body = '';
-            res.setEncoding('utf8');
-            res.on('data', (chunk) => (body += chunk));
-            res.on('end', () => {
-                try {
-                    resolve(JSON.parse(body));
-                }
-                catch {
-                    resolve(undefined);
-                }
-            });
-        });
-        req.on('error', () => resolve(undefined));
-        req.on('timeout', () => {
-            req.destroy();
-            resolve(undefined);
-        });
-    });
-}
-function sameOrigin(a, b) {
-    try {
-        const origin = new URL(a).origin;
-        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
-        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
-        if (isOpaqueOrigin(origin))
-            return false;
-        return origin === new URL(b).origin;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
- * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
- * - no url + nothing connected → ask for one.
- * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
- * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
- * - url + no matching tab → open it.
- *
- * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
- * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
- * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
- * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
- * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
- * is a bigger surprise than being told where the tab actually is.
- */
-export function decideOpen(all, url) {
-    // A tab that has stopped answering is not a tab you can be handed. `open` is the command a caller
-    // reaches for to RECOVER, and reusing the wedged one left no way out short of killing the daemon:
-    // ending the session only flips a flag on the record, it does not make the page answer.
-    const sessions = all.filter((s) => true !== s.unresponsive);
-    if (url === undefined) {
-        const first = sessions[0];
-        return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
-    }
-    const exact = sessions.find((s) => s.url === url);
-    if (exact !== undefined)
-        return { action: 'reuse', url: exact.url };
-    const onOrigin = sessions.find((s) => sameOrigin(s.url, url));
-    return onOrigin !== undefined
-        ? { action: 'left-as-is', url: onOrigin.url, requested: url }
-        : { action: 'open', url };
-}
-/**
- * Percent-encode the cmd.exe metacharacters that `start` re-parses so a URL can't break out into
- * command execution on Windows (`?next=x&calc` → command chaining). `%` is left untouched so an
- * already-encoded URL isn't double-encoded; the browser decodes the escapes back to the real URL.
- */
-function encodeForWindowsStart(url) {
-    return url.replace(/[&^|<>()"'!]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
-}
-/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
-export function openCommand(url, platform) {
-    if (NodePlatform.MACOS === platform)
-        return { cmd: 'open', args: [url] };
-    if (NodePlatform.WINDOWS === platform) {
-        return { cmd: 'cmd', args: ['/c', 'start', '', encodeForWindowsStart(url)] };
-    }
-    return { cmd: 'xdg-open', args: [url] };
-}
-/**
- * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
- *
- * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
- * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
- * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
- * port problem while nothing had ever opened.
- */
-export async function openInBrowser(url, platform = process.platform, run = defaultRun) {
-    const { cmd, args } = openCommand(url, platform);
-    return run(cmd, args);
-}
-/**
- * What a finished launcher means, or null when nothing is wrong.
- *
- * Exported for its own tests: the headless case is the one that matters and it cannot be produced
- * by spawning a real launcher on a developer machine.
- */
-export function launcherFailure(code, signal) {
-    if (null !== signal)
-        return `the browser launcher was killed by ${signal}`;
-    // null code with no signal: it never reported an outcome in the window we waited. Some desktop
-    // launchers stay attached rather than handing off, and inventing a failure there would be worse
-    // than the silence — it would send someone to fix a browser that opened.
-    if (null === code || 0 === code)
-        return null;
-    return (`the browser launcher exited ${String(code)} — on a machine with no browser (CI, a container, ` +
-        'an SSH session, WSL with no host browser) it starts fine and then has nothing to open');
-}
-/** How long to wait for the launcher to hand off before assuming it did. */
-const LAUNCHER_EXIT_MS = 2_000;
-/** null when the launcher opened something; the failure message when it did not. */
-function defaultRun(cmd, args) {
-    return new Promise((resolve) => {
-        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            resolve(value);
-        };
-        // An unhandled 'error' on a ChildProcess throws — and ENOENT on the launcher is exactly the case
-        // this function exists to report, so it must be listened for either way.
-        child.on('error', (err) => finish(err.message));
-        // The EXIT, not the spawn. Answering "did the command begin" reported success on every headless
-        // box, where the launcher begins perfectly well and then finds nothing to open — see
-        // launcherFailure. Every launcher we use hands off and exits immediately, so this costs nothing
-        // on the path where it works.
-        child.on('exit', (code, signal) => finish(launcherFailure(code, signal)));
-        // ...and a launcher that stays attached must not hold up the install.
-        const timer = setTimeout(() => {
-            child.unref();
-            finish(null);
-        }, LAUNCHER_EXIT_MS);
-        timer.unref?.();
-    });
-}

package/dist/cli/cli-parse.d.ts

@@ -1,171 +0,0 @@
-/**
- * Pure CLI argument parsing — the command/flag grammar, the CliResult union, and parseCliArgs.
- * Split out of cli.ts (which keeps the side-effecting handlers + dispatch) to stay under the
- * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
- * imports are unchanged.
- */
-import { type ParsedFeedback } from './cli-parse-feedback.js';
-export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-/**
- * The lines below say `reticle <command>`, which is the bin this package installs and is correct
- * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
- * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
- * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
- * the usage block rather than being a footnote somewhere else.
- */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--flow \"<what to drive>\"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --flow names the journey worth proving, in your own words. Only you know\n                which one matters, and naming it is the difference between a drive that\n                finishes and one that spends its budget looking for something to do\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model\n                are the runtime dials: CI, a headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n                [--expect '<json predicate>']            (one verdict, no saved flows needed \u2014 asks\n                the daemon that is already running, so nothing is bound and nothing is stopped. This\n                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on\n                verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
-/** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
-export declare const TelemetryAction: {
-    readonly STATUS: "status";
-    readonly ENABLE: "enable";
-    readonly DISABLE: "disable";
-};
-export type TelemetryAction = (typeof TelemetryAction)[keyof typeof TelemetryAction];
-export declare const DAEMON_INNER_COMMAND = "_daemon";
-/**
- * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
- * this is what keeps that property low-cardinality and non-identifying: an argument we do not
- * recognize reports as `unknown` rather than being echoed, so a typo — which may be a path, a URL, or
- * a flow name — can never reach the wire just because someone misspelled `status`.
- *
- * Lives here rather than in the telemetry module because this is where the command names are already
- * defined; a second list somewhere else would drift the first time a command is added.
- */
-export declare const UNKNOWN_COMMAND = "unknown";
-/** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
-export declare function knownCommand(arg: string | undefined): string;
-export declare const HEADED_FLAG = "--headed";
-export declare const PORT_FLAG = "--port";
-export declare const DRIVE_FLAG = "--drive";
-export declare const HTTP_FLAG = "--http";
-export declare const HTTP_PORT_FLAG = "--http-port";
-export declare const HTTP_TOKEN_FLAG = "--http-token";
-export type CliResult = {
-    kind: 'init';
-    port: number | undefined;
-    mcp: boolean;
-    dryRun: boolean;
-    install: boolean;
-    app: string | undefined;
-    flow: string | undefined;
-    env: string[];
-    filesOnly: boolean;
-    captureBodies: boolean;
-    json: boolean;
-    drive: boolean;
-    relaunch: boolean;
-    open: boolean;
-    agents: boolean;
-    url: string | undefined;
-    timeoutSeconds: number | undefined;
-    driveModel: string | undefined;
-    licenseKey: string | undefined;
-} | {
-    kind: 'serve';
-    port: number;
-    driveUrl?: string;
-    headless: boolean;
-    http: boolean;
-    httpPort?: number;
-    httpToken?: string;
-} | {
-    kind: 'stop';
-    port: number;
-    quiet: boolean;
-} | {
-    kind: 'kill';
-    port: number;
-    force: boolean;
-} | {
-    kind: 'restart';
-    port: number;
-    force: boolean;
-} | {
-    kind: 'status';
-    port: number;
-} | {
-    kind: 'license';
-} | {
-    kind: 'telemetry';
-    action: TelemetryAction;
-} | Extract<ParsedFeedback, {
-    kind: 'feedback';
-}> | {
-    kind: 'identify';
-    context?: string;
-    company?: string;
-    email?: string;
-    forget: boolean;
-} | {
-    kind: 'version';
-} | {
-    kind: 'help';
-} | {
-    kind: 'doctor';
-    port: number;
-} | {
-    kind: 'open';
-    port: number;
-    url?: string;
-} | {
-    kind: '_daemon';
-    port: number;
-    driveUrl?: string;
-    headless: boolean;
-    http: boolean;
-    httpPort?: number;
-    httpToken?: string;
-} | {
-    kind: 'drive';
-    port: number;
-    driveUrl: string;
-    headless: boolean;
-} | {
-    kind: 'verify';
-    url: string;
-    headless: boolean;
-    port: number;
-    timeoutMs?: number;
-    storageState?: string;
-    sessionId?: string;
-    expect?: unknown;
-} | {
-    kind: 'affected';
-    files: string[];
-    since?: string;
-} | {
-    kind: 'hunt';
-    dir: string;
-} | {
-    kind: 'capsules';
-} | {
-    kind: 'gate';
-    files: string[];
-    since?: string;
-    hook?: boolean;
-} | {
-    kind: 'watch';
-    url?: string;
-} | {
-    kind: 'update';
-} | {
-    kind: 'rollback';
-} | {
-    kind: 'mcp';
-    port: number;
-    driveUrl?: string;
-    headless: boolean;
-    http: boolean;
-    httpPort?: number;
-    httpToken?: string;
-} | {
-    kind: 'error';
-    message: string;
-};
-/**
- * @param defaultHeadless Whether a browser Reticle launches should be hidden when no flag says
- *   otherwise. Injected rather than read from the environment here, because this module is pure —
- *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
- *   trustworthy, and asking people to opt into seeing their own app was backwards.
- */
-export declare function parseCliArgs(argv: string[], defaultPort: number, defaultHeadless?: boolean): CliResult;