@reticlehq/server 3.5.0 → 3.7.0

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

@@ -44,3 +44,78 @@ export const VERIFY_COMMAND = 'verify';
  * missed for a release.
  */
 export const EXPECT_FLAG = '--expect';
+/**
+ * The account and cloud commands. They are dispatched before the typed parser, and listed here so
+ * that the dispatcher and the telemetry vocabulary read one list instead of two.
+ */
+export const CLOUD_COMMANDS = [
+    'login',
+    'connect',
+    'try',
+    'logout',
+    'whoami',
+    'link',
+    'project',
+    'config',
+    'issues',
+    'memory',
+    'push',
+    'sync',
+    'runs',
+    'regression',
+    'share',
+];
+/**
+ * Old command names that still run, for one release, under the name that replaced them. Each one
+ * prints a single line saying so, then does what it always did.
+ */
+export const RENAMED_COMMANDS = new Map([
+    ['kill', 'stop --force'],
+    ['login', 'connect'],
+    ['link', 'connect'],
+    ['project', 'connect --project <name|id>'],
+    ['whoami', 'status'],
+    ['push', 'sync'],
+    ['regression', 'runs regression'],
+    ['share', 'runs share <runId>'],
+    ['issues', 'runs issues'],
+    ['memory', 'runs memory'],
+]);
+const HELP_FLAGS = new Set(['--help', '-h']);
+/** `login --email` is the documented sign-in without a browser, so it is not a renamed `connect`. */
+const BROWSERLESS_LOGIN = { command: 'login', flag: '--email' };
+/**
+ * The command an old name now goes by, when the note saying so should print; otherwise undefined.
+ * Not for a request for help (that answer names the new command itself), and not for
+ * `login --email`, which `connect --help` documents as the sign-in for CI and agents.
+ */
+export function renamedCommandFor(argv) {
+    const name = argv[0];
+    if (name === undefined || argv.some((arg) => HELP_FLAGS.has(arg)))
+        return undefined;
+    if (BROWSERLESS_LOGIN.command === name && argv.includes(BROWSERLESS_LOGIN.flag))
+        return undefined;
+    return RENAMED_COMMANDS.get(name);
+}
+/**
+ * Commands that were removed, and what to use instead. They stay in the telemetry vocabulary, so
+ * the people still typing one show up as that name rather than as `unknown`.
+ */
+export const REMOVED_COMMANDS = new Map([
+    ['hunt', 'it has no replacement'],
+    ['watch', 'use `reticle affected` after you save, or `reticle gate` before you commit'],
+    ['capsules', 'it has no replacement; saved capsules stay in .reticle/capsules'],
+    ['tutorial', "use `reticle init` in your app's folder, or `reticle try <url>`"],
+    [
+        'identify',
+        'it has no replacement; delete ~/.reticle/identity.json to forget a saved identity, and use `reticle feedback` to reach us',
+    ],
+]);
+export const removedNote = (command, instead) => `\`reticle ${command}\` was removed in this version; ${instead}`;
+const DIM = '\u001b[2m';
+const RESET = '\u001b[0m';
+/** One line on stderr when an old name ran: dim on a terminal, plain anywhere else. */
+export const renamedNote = (command, now, colour) => {
+    const line = `\`reticle ${command}\` is now \`reticle ${now}\``;
+    return colour ? `${DIM}${line}${RESET}` : line;
+};

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

@@ -12,6 +12,8 @@ export type VerifySuffix = {
     explore?: boolean;
     persona?: string;
     select?: string[];
+    resultsJson?: string;
+    confirmDangerous?: boolean;
 } | {
     kind: 'error';
     message: string;

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

@@ -34,6 +34,10 @@ const EXPLORE_FLAG = '--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';
+/** Write the per-journey verdicts to this file as JSON, for a CI step that posts them. */
+const RESULTS_JSON_FLAG = '--results-json';
+/** Acknowledge, for this run only, the steps the replay guard holds as destructive ("Place order"). */
+const CONFIRM_DANGEROUS_FLAG = '--confirm-dangerous';
 /**
  * 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
@@ -90,6 +94,8 @@ export function parseVerifySuffix(args, defaultPort) {
     let explore = false;
     let persona;
     const select = [];
+    let resultsJson;
+    let confirmDangerous = false;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
@@ -142,9 +148,19 @@ export function parseVerifySuffix(args, defaultPort) {
             // silently become two selections that match nothing.
             select.push(v);
         }
+        else if (arg === RESULTS_JSON_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(RESULTS_JSON_FLAG);
+            resultsJson = v;
+        }
         else if (arg === EXPLORE_FLAG) {
             explore = true;
         }
+        else if (arg === CONFIRM_DANGEROUS_FLAG) {
+            confirmDangerous = true;
+        }
         else if (arg === PERSONA_FLAG) {
             i++;
             const v = args[i];
@@ -212,5 +228,7 @@ export function parseVerifySuffix(args, defaultPort) {
         ...(explore ? { explore } : {}),
         ...(persona !== undefined ? { persona } : {}),
         ...(select.length > 0 ? { select } : {}),
+        ...(resultsJson !== undefined ? { resultsJson } : {}),
+        ...(confirmDangerous ? { confirmDangerous } : {}),
     };
 }

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

@@ -3,19 +3,12 @@
  * 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] [--hooks]  (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>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on 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>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\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 connect [--project <name|id>] [--url <cloud origin>]\n                                                       (wire this app if needed, sign in, link, send local history)\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.";
+import { CLI_USAGE } from './cli-usage.js';
+export { CLI_USAGE };
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -34,8 +27,16 @@ export declare const DAEMON_INNER_COMMAND = "_daemon";
  * defined; a second list somewhere else would drift the first time a command is added.
  */
 export declare const UNKNOWN_COMMAND = "unknown";
+/** Every command the typed parser below routes. The parser refuses any word not in this list. */
+export declare const LOCAL_COMMANDS: readonly string[];
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export declare function knownCommand(arg: string | undefined): string;
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
 export declare const DRIVE_FLAG = "--drive";
 export declare const HTTP_FLAG = "--http";
 export declare const HTTP_PORT_FLAG = "--http-port";
@@ -62,6 +63,7 @@ export type CliResult = {
     json: boolean;
     relaunch: boolean;
     open: boolean;
+    firstRun: boolean;
     agents: boolean;
     url: string | undefined;
     timeoutSeconds: number | undefined;
@@ -98,15 +100,13 @@ export type CliResult = {
 } | Extract<ParsedFeedback, {
     kind: 'feedback';
 }> | {
-    kind: 'identify';
-    context?: string;
-    company?: string;
-    email?: string;
-    forget: boolean;
-} | {
     kind: 'version';
 } | {
     kind: 'help';
+    topic?: string;
+} | {
+    kind: 'removed';
+    message: string;
 } | {
     kind: 'doctor';
     port: number;
@@ -117,12 +117,6 @@ export type CliResult = {
     runtimeSecs: number;
     installSecs: number;
     mcp: boolean;
-} | {
-    kind: 'tutorial';
-    audience: TutorialAudience;
-    run: boolean;
-    port: number;
-    headless: boolean;
 } | {
     kind: 'open';
     port: number;
@@ -153,15 +147,12 @@ export type CliResult = {
     explore?: boolean;
     persona?: string;
     select?: string[];
+    resultsJson?: string;
+    confirmDangerous?: boolean;
 } | {
     kind: 'affected';
     files: string[];
     since?: string;
-} | {
-    kind: 'hunt';
-    dir: string;
-} | {
-    kind: 'capsules';
 } | {
     kind: 'gate';
     files: string[];
@@ -173,8 +164,8 @@ export type CliResult = {
     session?: string;
     hook: boolean;
 } | {
-    kind: 'watch';
-    url?: string;
+    kind: 'context';
+    session?: string;
 } | {
     kind: 'update';
 } | {