@reticlehq/server 2.11.0 → 2.13.0

package/dist/cli/cli-parse.js

@@ -17,8 +17,21 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  */
 export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
 
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+                [--flow "<what to drive>"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)
                 --app picks WHICH app in a monorepo, when several are found
+                --flow names the journey worth proving, in your own words. Only you know
+                which one matters, and naming it is the difference between a drive that
+                finishes and one that spends its budget looking for something to do
+                --env is what the app needs to reach a usable state: the key from
+                .env.example, the mock backend, the variable that skips an auth wall.
+                Repeatable, and a value may contain spaces and equals signs
+                --files-only writes the files and stops, which is what init did before it
+                learned to boot the app and prove the install works
+                --license writes the key to .env and keeps .env out of git
+                --json puts the result on stdout, so an agent reads one object
+                --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model
+                are the runtime dials: CI, a headless box, or an app you already run
                 --no-mcp skips MORE than the server registration: also the agent rule files
                 (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
                 only make sense once the tools are reachable.
@@ -29,7 +42,7 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle status [--port N]
   reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+  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)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
@@ -45,13 +58,15 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
 
-Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
-  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
+Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
+  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]
+                                                       (browser device flow by default; --email mails a code)
+  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)
   reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
   reticle whoami                                        (who am I signed in as, and is this repo attached?)
   reticle project <ls|create <name>>                   (list or create cloud projects)
   reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
-  reticle push                                          (send local run artifacts to the dashboard)
+  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)
   reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
 
 'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
@@ -69,6 +84,8 @@ const AFFECTED_COMMAND = 'affected';
 const HUNT_COMMAND = 'hunt';
 const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
+/** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
+const HOOK_FLAG = '--hook';
 const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
@@ -132,6 +149,8 @@ const KNOWN_COMMANDS = new Set([
     'config',
     'push',
     'runs',
+    'issues',
+    'memory',
     'regression',
     'share',
     'doctor',
@@ -157,12 +176,64 @@ const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
 const APP_FLAG = '--app';
+/**
+ * What only the caller can know, and what it may switch off.
+ *
+ * `--flow`, `--env` and `--app` are an AGENT's answers: which journey proves the thing the user
+ * cares about, what the app needs to reach a usable state, and which app in a monorepo. None is
+ * inferable from the repository alone, and a run without them either guesses or stops.
+ *
+ * `--files-only` is the escape hatch for a caller that wants what init used to do and nothing more.
+ */
+const FLOW_FLAG = '--flow';
+const ENV_FLAG = '--env';
+const FILES_ONLY_FLAG = '--files-only';
+/**
+ * Write `captureNetworkBodies: true` into the app's config. OFF unless asked (#705).
+ *
+ * Body capture is what makes a 2xx write's OUTCOME readable rather than just its transport, so it
+ * is worth having — but a body is the one part of a request that routinely carries personal data,
+ * and `init` runs unattended. Whoever passes this has decided; nothing decides it for them.
+ */
+const CAPTURE_BODIES_FLAG = '--capture-bodies';
+/**
+ * The rest of the runtime surface.
+ *
+ * `--json` is not a convenience: SKILL.md tells an agent to read the result and act on `agentTodo`,
+ * and reading one object is one turn where interpreting a report is several. The three opt-outs are
+ * what a machine without a browser, or a caller already running their app, actually needs.
+ */
+const JSON_FLAG = '--json';
+const NO_DRIVE_FLAG = '--no-drive';
+const NO_OPEN_FLAG = '--no-open';
+const NO_AGENTS_FLAG = '--no-agents';
+/**
+ * Restart the calling client so IT gets the tools.
+ *
+ * The flag was accepted by the prototype and not by `init`, so passing it printed the whole usage
+ * text. `init` decides what a restart should do — including refusing an id with no transcript, which
+ * is the case that looks exactly like success — and prints it; performing the restart is the
+ * caller's, because opening a terminal is not something a one-shot command should do behind a flag.
+ */
+const RELAUNCH_FLAG = '--relaunch';
+const URL_FLAG = '--url';
+const TIMEOUT_FLAG_INIT = '--timeout';
+const DRIVE_MODEL_FLAG = '--drive-model';
+/**
+ * The key, written to .env by the command rather than by hand.
+ *
+ * The instructions used to ask an agent for three steps: append to .env, check .gitignore, confirm.
+ * All three are deterministic, and the second is the one that costs something when skipped, because
+ * a key committed to git is leaked and stays leaked after the file is removed.
+ */
+const LICENSE_FLAG = '--license';
 const NO_INSTALL_FLAG = '--no-install';
 export const HTTP_FLAG = '--http';
 export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
+const SESSION_ID_FLAG = '--session-id';
 const unknownArgument = (arg) => ({
     kind: 'error',
     message: `unknown argument '${arg}'`,
@@ -179,6 +250,10 @@ const missingOperand = (command, what) => ({
     kind: 'error',
     message: `${command} needs ${what}`,
 });
+const requiresHttp = (flag) => ({
+    kind: 'error',
+    message: `${flag} requires ${HTTP_FLAG} — it configures the verify endpoint ${HTTP_FLAG} starts`,
+});
 const unknownCommand = (command) => ({
     kind: 'error',
     message: `unknown command '${command}'`,
@@ -243,6 +318,13 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
         }
         i++;
     }
+    // Without `--http` these flags configure an endpoint nothing starts, and they were accepted and
+    // silently ignored — worse than being rejected, because the whole reason to pass them is to be
+    // honoured (#687).
+    if (!http && httpPort !== undefined)
+        return requiresHttp(HTTP_PORT_FLAG);
+    if (!http && httpToken !== undefined)
+        return requiresHttp(HTTP_TOKEN_FLAG);
     return {
         kind: 'ok',
         port,
@@ -288,14 +370,17 @@ function parseDriveSuffix(args, port, defaultHeadless) {
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
- * Parse `verify <url> [--headed] [--timeout N] [--storage-state <file>]`. The first non-flag token is
- * the preview URL.
+ * 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.
  */
-function parseVerifySuffix(args) {
+function parseVerifySuffix(args, defaultPort) {
     let headless = true;
     let url;
     let timeoutMs;
     let storageState;
+    let sessionId;
+    let port = defaultPort;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
@@ -304,6 +389,16 @@ function parseVerifySuffix(args) {
         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];
@@ -321,6 +416,13 @@ function parseVerifySuffix(args) {
                 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.startsWith('--')) {
             return unknownArgument(arg);
         }
@@ -338,8 +440,10 @@ function parseVerifySuffix(args) {
         kind: 'ok',
         url,
         headless,
+        port,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(storageState !== undefined ? { storageState } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
     };
 }
 function parseInitFlags(args) {
@@ -348,6 +452,20 @@ function parseInitFlags(args) {
     let dryRun = false;
     let install = true;
     let app;
+    let flow;
+    // Repeatable: one variable per flag, so a value containing spaces or `=` needs no quoting rules.
+    const env = [];
+    let filesOnly = false;
+    let captureBodies = false;
+    let json = false;
+    let drive = true;
+    let open = true;
+    let relaunch = false;
+    let agents = true;
+    let url;
+    let timeoutSeconds;
+    let driveModel;
+    let licenseKey;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
@@ -372,6 +490,72 @@ function parseInitFlags(args) {
                 return missingValue(APP_FLAG);
             app = value;
         }
+        else if (arg === FLOW_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(FLOW_FLAG);
+            flow = value;
+        }
+        else if (arg === ENV_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(ENV_FLAG);
+            env.push(value);
+        }
+        else if (arg === FILES_ONLY_FLAG) {
+            filesOnly = true;
+        }
+        else if (arg === CAPTURE_BODIES_FLAG) {
+            captureBodies = true;
+        }
+        else if (arg === JSON_FLAG) {
+            json = true;
+        }
+        else if (arg === NO_DRIVE_FLAG) {
+            drive = false;
+        }
+        else if (arg === NO_OPEN_FLAG) {
+            open = false;
+        }
+        else if (arg === RELAUNCH_FLAG) {
+            relaunch = true;
+        }
+        else if (arg === NO_AGENTS_FLAG) {
+            agents = false;
+        }
+        else if (arg === URL_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(URL_FLAG);
+            url = value;
+        }
+        else if (arg === LICENSE_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(LICENSE_FLAG);
+            licenseKey = value;
+        }
+        else if (arg === DRIVE_MODEL_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(DRIVE_MODEL_FLAG);
+            driveModel = value;
+        }
+        else if (arg === TIMEOUT_FLAG_INIT) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(TIMEOUT_FLAG_INIT);
+            const seconds = parseInt(value, 10);
+            if (isNaN(seconds))
+                return notANumber(TIMEOUT_FLAG_INIT, value);
+            timeoutSeconds = seconds;
+        }
         else if (arg === NO_MCP_FLAG) {
             mcp = false;
         }
@@ -389,7 +573,27 @@ function parseInitFlags(args) {
         }
         i++;
     }
-    return { kind: 'ok', port, mcp, dryRun, install, app };
+    return {
+        kind: 'ok',
+        port,
+        mcp,
+        dryRun,
+        install,
+        app,
+        flow,
+        env,
+        filesOnly,
+        captureBodies,
+        json,
+        drive,
+        open,
+        relaunch,
+        agents,
+        url,
+        timeoutSeconds,
+        driveModel,
+        licenseKey,
+    };
 }
 /** Pure CLI arg parser — exported for unit tests. argv = process.argv.slice(2). */
 const SINCE_FLAG = '--since';
@@ -457,6 +661,19 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 dryRun: r.dryRun,
                 install: r.install,
                 app: r.app,
+                flow: r.flow,
+                env: r.env,
+                filesOnly: r.filesOnly,
+                captureBodies: r.captureBodies,
+                json: r.json,
+                drive: r.drive,
+                open: r.open,
+                relaunch: r.relaunch,
+                agents: r.agents,
+                url: r.url,
+                timeoutSeconds: r.timeoutSeconds,
+                driveModel: r.driveModel,
+                licenseKey: r.licenseKey,
             };
         }
         case SERVE_COMMAND: {
@@ -550,15 +767,17 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         case VERIFY_COMMAND: {
-            const r = parseVerifySuffix(rest);
+            const r = parseVerifySuffix(rest, defaultPort);
             if ('error' === r.kind)
                 return r;
             return {
                 kind: 'verify',
                 url: r.url,
                 headless: r.headless,
+                port: r.port,
                 ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
+                ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
             };
         }
         case CAPSULES_COMMAND:
@@ -575,9 +794,16 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
-            const t = parseTargetArgs(rest);
+            // `--hook` is stripped before target parsing, which would reject it as an unknown flag.
+            const hook = rest.includes(HOOK_FLAG);
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG));
             const since = t.since ?? implicitSince(t.files);
-            return { kind: 'gate', files: t.files, ...(since === undefined ? {} : { since }) };
+            return {
+                kind: 'gate',
+                files: t.files,
+                ...(since === undefined ? {} : { since }),
+                ...(hook ? { hook: true } : {}),
+            };
         }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.

package/dist/cli/cli-update-commands.js

@@ -8,9 +8,10 @@
 import { checkForUpdate } from '../update/update-checker.js';
 import { updateTarget } from '../update/update-nudge.js';
 import { applyUpdate, rollback } from '../update/updater.js';
+import { refreshAgentRules } from '../init/refresh-rules.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
 import { detectPackageManager } from '../init/detect.js';
@@ -64,6 +65,24 @@ export async function handleUpdate() {
             return;
         }
         log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
+        // Bring this project's agent rules up with the version.
+        //
+        // The managed block has always been updatable — marker-delimited, idempotent by comparing
+        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
+        // from `buildPlan` alone, so a project set up on an older release kept that release's
+        // instructions forever and every improvement to them reached new projects only.
+        //
+        // That is backwards: the people who most need better instructions are the ones already
+        // installed and not getting value, and this is the moment they are touching the install anyway.
+        // Only files that ALREADY carry the block are touched, and only inside the markers.
+        const refreshed = refreshAgentRules(process.cwd(), {
+            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+            write: (path, content) => {
+                writeFileSync(path, content, 'utf8');
+            },
+        });
+        if (0 !== refreshed.updated.length)
+            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
         // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
         // whose job is keeping an install current was itself a way to produce a version-skewed pair —
         // and the skew message told people to run it to fix an outdated SDK, which it could not do.

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

@@ -62,7 +62,8 @@ export declare function handleVerify(parsed: {
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;
+    sessionId?: string;
     /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
-    port?: number;
+    port: number;
 }): void;
 export {};

package/dist/cli/cli-verify.js

@@ -16,7 +16,7 @@ import { start } from '../index.js';
 import { probePresence, PortPresence } from '../daemon/port-presence.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { fetchStatus } from './cli-launch.js';
-import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, resolveCloudConfig, syncRunToCloud, SyncOutcome, } from '../cloud/cloud-sync.js';
 import { ReticleRunner } from '../runs/reticle-runner.js';
 import { createRunnerPort } from '../runs/runner-port.js';
 import { RunStore } from '../runs/run-store.js';
@@ -94,9 +94,9 @@ async function pushRunToCloud(run, ports) {
     const config = resolveCloudConfig(process.env);
     if (null === config)
         return;
-    const result = await syncRunToCloud(run, config, (url, init) => fetch(url, init));
+    const result = await syncRunToCloud(run, config, cloudFetch);
     if (result.outcome === SyncOutcome.SYNCED) {
-        ports.out(`↑ run ${run.runId} recorded on the Reticle Cloud dashboard`);
+        ports.out(`↑ run ${run.runId} recorded on the Reticle dashboard`);
     }
     else {
         ports.fail(`cloud run sync failed (${result.status ?? result.error ?? 'error'}); run kept locally`);
@@ -175,7 +175,7 @@ async function openLiveConnection(opts) {
         ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
     });
     const deps = buildVerifyDeps(running, opts.reticleRoot, opts.now);
-    const runner = new ReticleRunner(createRunnerPort(deps));
+    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId));
     return {
         sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
         listFlows: () => deps.flows.list(),
@@ -244,6 +244,7 @@ export function handleVerify(parsed) {
             now,
             port: parsed.port ?? RETICLE_DEFAULT_PORT,
             ...(parsed.storageState !== undefined ? { storageState: parsed.storageState } : {}),
+            ...(parsed.sessionId !== undefined ? { sessionId: parsed.sessionId } : {}),
         }),
         out: (line) => process.stdout.write(`${line}\n`),
         fail: (line) => process.stderr.write(`${line}\n`),