@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/cli-parse-verify.js

@@ -0,0 +1,143 @@
+/**
+ * The `reticle verify` grammar.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap. Cohesive on its own terms: this is
+ * the one command that takes a preview URL, a browser, a timeout, a saved storage state, a session to
+ * pin, a predicate to assert AND a persona to drive as — so it carries more grammar than the rest of
+ * the CLI put together.
+ */
+import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+const TIMEOUT_FLAG = '--timeout';
+const STORAGE_STATE_FLAG = '--storage-state';
+const EXPECT_FLAG = '--expect';
+const SESSION_ID_FLAG = '--session-id';
+/** Let Reticle drive the app itself and record what it drove, when nothing is saved yet. */
+const EXPLORE_FLAG = '--explore';
+/** Who to be while exploring — a persona, or the business outcome to reach. Implies --explore. */
+const PERSONA_FLAG = '--persona';
+/** Narrow the suite to flows carrying this label. Repeatable — a set is the union of what you name. */
+const SELECT_FLAG = '--select';
+/**
+ * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]
+ * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
+ * env + `.reticle.json` + 4400.
+ */
+export function parseVerifySuffix(args, defaultPort) {
+    let headless = true;
+    let url;
+    let timeoutMs;
+    let storageState;
+    let sessionId;
+    let expect;
+    let explore = false;
+    let persona;
+    const select = [];
+    let port = defaultPort;
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === undefined)
+            break;
+        if (arg === HEADED_FLAG) {
+            headless = false;
+        }
+        else if (arg === PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined)
+                return missingValue(PORT_FLAG);
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed))
+                return notANumber(PORT_FLAG, n);
+            port = parsed;
+        }
+        else if (arg === TIMEOUT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined)
+                return missingValue(TIMEOUT_FLAG);
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed))
+                return notANumber(TIMEOUT_FLAG, n);
+            timeoutMs = parsed;
+        }
+        else if (arg === STORAGE_STATE_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(STORAGE_STATE_FLAG);
+            storageState = v;
+        }
+        else if (arg === SESSION_ID_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(SESSION_ID_FLAG);
+            sessionId = v;
+        }
+        else if (arg === SELECT_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(SELECT_FLAG);
+            // Repeatable rather than comma-split: a label is free-form, and a comma inside one would
+            // silently become two selections that match nothing.
+            select.push(v);
+        }
+        else if (arg === EXPLORE_FLAG) {
+            explore = true;
+        }
+        else if (arg === PERSONA_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(PERSONA_FLAG);
+            // A persona is what to explore AS, so naming one is asking for the drive. Requiring both
+            // flags would only give a user a way to say something they cannot mean.
+            persona = v;
+            explore = true;
+        }
+        else if (arg === EXPECT_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(EXPECT_FLAG);
+            try {
+                expect = JSON.parse(v);
+            }
+            catch {
+                // Named as a JSON problem rather than an unknown argument: the value IS the predicate, and
+                // "unknown argument" would send the reader looking at the flag instead of at their quoting.
+                return {
+                    kind: 'error',
+                    message: `${EXPECT_FLAG} needs a JSON predicate; could not parse: ${v}`,
+                };
+            }
+        }
+        else if (arg.startsWith('--')) {
+            return unknownArgument(arg);
+        }
+        else if (url === undefined) {
+            url = arg;
+        }
+        else {
+            return unknownArgument(arg);
+        }
+        i++;
+    }
+    if (url === undefined)
+        return missingOperand(VERIFY_COMMAND, 'a url');
+    return {
+        kind: 'ok',
+        url,
+        headless,
+        port,
+        ...(expect !== undefined ? { expect } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(storageState !== undefined ? { storageState } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(explore ? { explore } : {}),
+        ...(persona !== undefined ? { persona } : {}),
+        ...(select.length > 0 ? { select } : {}),
+    };
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Pure CLI argument parsing — the command/flag grammar, the CliResult union, and parseCliArgs.
+ * The parser stays pure and unit-testable; `cli.ts` owns the side-effecting handlers and dispatch,
+ * and re-exports this surface.
+ */
+import { TutorialAudience } from './tutorial.js';
+import { type ParsedFeedback } from './cli-parse-feedback.js';
+import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
+export { HEADED_FLAG, PORT_FLAG };
+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                [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\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-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                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] [--json]                   (a readable block; --json for the event)\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                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, 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 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";
+/**
+ * A predicate for a flow-free, one-shot verdict against the daemon that is already running.
+ *
+ * The dead end this removes: a client that never loaded the `reticle_*` tools had no path to a
+ * verdict at all. `verify` refused because the daemon owned the port — the normal state after a
+ * working install — the other verdict paths need saved flows a first-install project does not have,
+ * and stopping the daemon cuts the agent's own MCP link.
+ */
+export type CliResult = {
+    kind: 'init';
+    port: number | undefined;
+    mcp: boolean;
+    dryRun: boolean;
+    install: boolean;
+    app: string | undefined;
+    env: string[];
+    filesOnly: boolean;
+    captureBodies: boolean;
+    json: boolean;
+    relaunch: boolean;
+    open: boolean;
+    agents: boolean;
+    url: string | undefined;
+    timeoutSeconds: number | 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;
+    json: boolean;
+} | {
+    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: 'setup-mcp';
+} | {
+    kind: 'setup-install';
+    runtimeSecs: number;
+    installSecs: number;
+    mcp: boolean;
+} | {
+    kind: 'tutorial';
+    audience: TutorialAudience;
+    run: boolean;
+    port: number;
+    headless: boolean;
+} | {
+    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;
+    explore?: boolean;
+    persona?: string;
+    select?: string[];
+} | {
+    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;