@reticlehq/server 2.4.0 → 2.5.0

package/dist/{cli-parse.js → cli/cli-parse.js}

@@ -5,7 +5,11 @@
  * imports are unchanged.
  */
 export const CLI_USAGE = `usage:
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+                --app picks WHICH app in a monorepo, when several are found
+                --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.
   reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
   reticle stop  [--port N] [--quiet]
   reticle status [--port N]
@@ -56,10 +60,10 @@ const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
 const IDENTIFY_COMMAND = 'identify';
-export const COMPANY_FLAG = '--company';
-export const EMAIL_FLAG = '--email';
-export const CONTEXT_FLAG = '--context';
-export const FORGET_FLAG = '--forget';
+const COMPANY_FLAG = '--company';
+const EMAIL_FLAG = '--email';
+const CONTEXT_FLAG = '--context';
+const FORGET_FLAG = '--forget';
 /** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
 export const RATING_FLAG = '--rating';
 export const BUG_FLAG = '--bug';
@@ -118,7 +122,7 @@ const KNOWN_COMMANDS = new Set([
 ]);
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
-    if (arg === undefined || arg === '')
+    if (arg === undefined || '' === arg)
         return 'help';
     return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
 }
@@ -128,25 +132,40 @@ export const HEADED_FLAG = '--headed';
  * 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 const HEADLESS_FLAG = '--headless';
+const HEADLESS_FLAG = '--headless';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
+const APP_FLAG = '--app';
 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';
-/**
- * `serve` / `mcp` / `_daemon` own the browser POOL, which backs automated work — leased contexts for
- * parallel agents, flow replay, the spec runner. Those are batch: nobody is watching, and launching
- * them headed changed timing enough to break four e2e specs. The headed default belongs to the
- * INTERACTIVE command (`drive`), where a human asked to see the run. `--headed` still opts in here.
- */
+const unknownArgument = (arg) => ({
+    kind: 'error',
+    message: `unknown argument '${arg}'`,
+});
+const missingValue = (flag) => ({
+    kind: 'error',
+    message: `${flag} needs a value`,
+});
+const notANumber = (flag, value) => ({
+    kind: 'error',
+    message: `${flag} expects a number, got '${value}'`,
+});
+const missingOperand = (command, what) => ({
+    kind: 'error',
+    message: `${command} needs ${what}`,
+});
+const unknownCommand = (command) => ({
+    kind: 'error',
+    message: `unknown command '${command}'`,
+});
 function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
@@ -157,21 +176,25 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
         else if (arg === DRIVE_FLAG) {
             i++;
             driveUrl = args[i];
             if (driveUrl === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(DRIVE_FLAG);
         }
         else if (arg === HEADED_FLAG) {
             headless = false;
@@ -186,20 +209,20 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(HTTP_PORT_FLAG, n);
             httpPort = parsed;
         }
         else if (arg === HTTP_TOKEN_FLAG) {
             i++;
             httpToken = args[i];
             if (httpToken === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_TOKEN_FLAG);
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
@@ -215,7 +238,7 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
 }
 function parsePortFlag(args, defaultPort) {
     const idx = args.indexOf(PORT_FLAG);
-    if (idx === -1)
+    if (-1 === idx)
         return defaultPort;
     const n = args[idx + 1];
     if (n === undefined)
@@ -234,17 +257,17 @@ function parseDriveSuffix(args, port, defaultHeadless) {
             headless = true;
         }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (driveUrl === undefined) {
             driveUrl = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
     }
     if (driveUrl === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(DRIVE_COMMAND, 'a url');
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
@@ -268,32 +291,32 @@ function parseVerifySuffix(args) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(TIMEOUT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(TIMEOUT_FLAG, n);
             timeoutMs = parsed;
         }
         else if (arg === STORAGE_STATE_FLAG) {
             i++;
             const v = args[i];
             if (v === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(STORAGE_STATE_FLAG);
             storageState = v;
         }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (url === undefined) {
             url = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
     if (url === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(VERIFY_COMMAND, 'a url');
     return {
         kind: 'ok',
         url,
@@ -307,19 +330,31 @@ function parseInitFlags(args) {
     let mcp = true;
     let dryRun = false;
     let install = true;
+    let app;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
+        else if (arg === APP_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(APP_FLAG);
+            app = value;
+        }
         else if (arg === NO_MCP_FLAG) {
             mcp = false;
         }
@@ -333,15 +368,29 @@ function parseInitFlags(args) {
             // Accepted for scripting/CI; init has no interactive prompts today.
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
-    return { kind: 'ok', port, mcp, dryRun, install };
+    return { kind: 'ok', port, mcp, dryRun, install, app };
 }
 /** Pure CLI arg parser — exported for unit tests. argv = process.argv.slice(2). */
 const SINCE_FLAG = '--since';
 /** Parse `[--since <ref>] [file...]` shared by `affected` and `gate`. */
+/**
+ * What `reticle gate` / `reticle affected` mean with NOTHING after them: the working tree.
+ *
+ * They used to mean a usage error — while the rule `reticle init` writes into the agent's own
+ * instruction file says, in as many words, "run `reticle gate`". An instruction the tool rejects is
+ * worse than no instruction: the agent spends a turn on it and concludes Reticle is broken.
+ *
+ * HEAD is the ref that answers the question being asked. Explicit files or an explicit --since still
+ * win; this only fills the empty case.
+ */
+const WORKING_TREE_REF = 'HEAD';
+function implicitSince(files) {
+    return 0 === files.length ? WORKING_TREE_REF : undefined;
+}
 function parseTargetArgs(rest) {
     const files = [];
     let since;
@@ -365,27 +414,37 @@ function parseTargetArgs(rest) {
  */
 export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
-    if (argv.length === 0)
+    if (0 === argv.length)
         return { kind: 'serve', port: defaultPort, headless: true, http: false };
     const [cmd, ...rest] = argv;
+    // Guaranteed by the bare-argv check above; restated so the unknown-command error can name it.
+    if (cmd === undefined)
+        return { kind: 'error', message: CLI_USAGE };
     // `version` (or the conventional -v/--version flags) prints the running version — the diagnostic the
     // troubleshooting docs lean on to confirm which npx-resolved build is actually executing.
-    if (cmd === VERSION_COMMAND || cmd === '--version' || cmd === '-v')
+    if (cmd === VERSION_COMMAND || '--version' === cmd || '-v' === cmd)
         return { kind: 'version' };
     // `help` (and the conventional -h/--help) print usage to stdout and exit 0 — the universal first move
     // for a new user, which otherwise fell through to a JSON error with exit 1.
-    if (cmd === 'help' || cmd === '--help' || cmd === '-h')
+    if ('help' === cmd || '--help' === cmd || '-h' === cmd)
         return { kind: 'help' };
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
-            return { kind: 'init', port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
+            return {
+                kind: 'init',
+                port: r.port,
+                mcp: r.mcp,
+                dryRun: r.dryRun,
+                install: r.install,
+                app: r.app,
+            };
         }
         case SERVE_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'serve',
@@ -424,7 +483,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         case IDENTIFY_COMMAND: {
             const flag = (name) => {
                 const at = rest.indexOf(name);
-                return at === -1 ? undefined : rest[at + 1];
+                return -1 === at ? undefined : rest[at + 1];
             };
             const context = flag(CONTEXT_FLAG);
             const company = flag(COMPANY_FLAG);
@@ -439,13 +498,13 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case FEEDBACK_COMMAND: {
             const ratingAt = rest.indexOf(RATING_FLAG);
-            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
+            const rating = -1 === ratingAt ? undefined : Number(rest[ratingAt + 1]);
             if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
                 return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
             }
             // Everything that is not a flag or the rating's value is the message. Quoting is the user's
             // job for shell reasons, but joining the remainder means an unquoted sentence still works.
-            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
+            const consumed = new Set(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]);
             const text = rest
                 .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
                 .join(' ')
@@ -465,13 +524,13 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case DRIVE_COMMAND: {
             const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: '_daemon',
@@ -485,7 +544,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case VERIFY_COMMAND: {
             const r = parseVerifySuffix(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'verify',
@@ -505,21 +564,13 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle affected [--since <ref>] [file...]' };
-            }
-            return {
-                kind: 'affected',
-                files: t.files,
-                ...(t.since === undefined ? {} : { since: t.since }),
-            };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle gate [--since <ref>] [file...]' };
-            }
-            return { kind: 'gate', files: t.files, ...(t.since === undefined ? {} : { since: t.since }) };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'gate', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.
@@ -532,7 +583,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'rollback' };
         case MCP_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'mcp',
@@ -545,6 +596,8 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         default:
-            return { kind: 'error', message: CLI_USAGE };
+            // A bare `reticle` never lands here — it defaults to `serve` above — so `cmd` is always a real
+            // word somebody typed, and naming it is strictly more useful than reprinting the whole help.
+            return unknownCommand(cmd);
     }
 }

package/dist/{cli-port.d.ts → cli/cli-port.d.ts}

@@ -7,6 +7,18 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+/**
+ * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
+ * Astro to 4321, and so on.
+ *
+ * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
+ * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
+ * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
+ * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
+ * asked "what port does your dev server run on?" a few lines before showing this field, which is how
+ * the confusion got manufactured in the first place.
+ */
+export declare const DEV_SERVER_PORTS: ReadonlySet<number>;
 export declare function isLikelyDevServerPort(port: number): boolean;
 /** The warning printed when a project pins the bridge to something that looks like its dev server. */
 export declare function devServerPortWarning(port: number): string;

package/dist/{cli-port.js → cli/cli-port.js}

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
  * asked "what port does your dev server run on?" a few lines before showing this field, which is how
  * the confusion got manufactured in the first place.
  */
-const DEV_SERVER_PORTS = new Set([
+export const DEV_SERVER_PORTS = new Set([
     3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000,
 ]);
 export function isLikelyDevServerPort(port) {
@@ -37,9 +37,9 @@ export function readProjectPort(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const p = config['port'];
-            if (typeof p === 'number' && Number.isInteger(p) && p > 0 && p < 65536)
+            if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
                 return p;
         }
     }
@@ -57,9 +57,9 @@ export function readProjectId(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const id = config['projectId'];
-            if (typeof id === 'string' && id.length > 0)
+            if ('string' === typeof id && id.length > 0)
                 return id;
         }
     }
@@ -76,16 +76,16 @@ export function readProjectId(cwd) {
 export function readJournalEnabled(cwd, env) {
     if (env !== undefined) {
         const v = env.trim().toLowerCase();
-        if (v === '0' || v === 'false' || v === 'off')
+        if ('0' === v || 'false' === v || 'off' === v)
             return false;
-        if (v === '1' || v === 'true' || v === 'on')
+        if ('1' === v || 'true' === v || 'on' === v)
             return true;
     }
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
-            if (config['journal'] === false)
+        if ('object' === typeof config && config !== null) {
+            if (false === config['journal'])
                 return false;
         }
     }

package/dist/cli/cli-update-commands.d.ts

@@ -0,0 +1,4 @@
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export declare function handleUpdate(): Promise<void>;
+/** `reticle rollback` — restore the previous server version and restart. */
+export declare function handleRollback(): Promise<void>;

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

@@ -0,0 +1,93 @@
+/**
+ * The self-update command pair — `reticle update` and `reticle rollback`.
+ *
+ * Split out of cli.ts, which sits at the 600-line cap: these two are one cohesive unit (swap the
+ * installed version, restart) and the file they came from is the CLI's dispatch table, which grows
+ * for entirely different reasons.
+ */
+import { checkForUpdate } from '../update/update-checker.js';
+import { updateTarget } from '../update/update-nudge.js';
+import { applyUpdate, rollback } from '../update/updater.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { log } from '../log.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+import { detectPackageManager } from '../init/detect.js';
+import { buildNodeIo } from '../init/node-io.js';
+/**
+ * Bring the SDK in the CURRENT project to the version being installed.
+ *
+ * Best-effort and non-fatal on purpose: `reticle update` is run from wherever the human happens to
+ * be, which is often not an app at all. A directory with no manifest, or one that has none of our
+ * packages, simply has nothing to sync — that is a normal outcome, not a failure, and it must never
+ * stop the CLI half from happening.
+ */
+function syncProjectSdk(target) {
+    const cwd = process.cwd();
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return; // not an app directory
+    }
+    const packages = reticleDepsOf(manifest);
+    const io = buildNodeIo(cwd);
+    const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
+    const cmd = sdkSyncCommand(pm, packages, target);
+    if (null === cmd) {
+        log('reticle_update_sdk', { synced: false, reason: 'no @reticlehq packages in this project' });
+        return;
+    }
+    const ok = io.exec(cmd.command, cmd.args);
+    log('reticle_update_sdk', { synced: ok, packages, to: target, packageManager: pm });
+    if (!ok) {
+        log('reticle_update_sdk_failed', {
+            hint: `run \`${cmd.command} ${cmd.args.join(' ')}\` by hand, then restart the dev server`,
+        });
+    }
+}
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export async function handleUpdate() {
+    try {
+        const manifest = await checkForUpdate(SERVER_VERSION, () => Date.now());
+        // Direction, not inequality: the registry being DIFFERENT is not the registry being newer, and
+        // the old gate happily installed a downgrade — reported by a user. See updateTarget.
+        const target = updateTarget(manifest);
+        if (target === undefined) {
+            log('reticle_update', {
+                ok: false,
+                message: 'already on the latest version',
+                version: SERVER_VERSION,
+            });
+            return;
+        }
+        log('reticle_update', { ok: true, from: SERVER_VERSION, 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.
+        //
+        // Before the CLI swap because `applyUpdate` never returns (it execs and exits). If this half
+        // fails the daemon is still the older one, which is the direction the HELLO check names clearly
+        // and a re-run fixes; the reverse would leave a new daemon talking to an old page.
+        syncProjectSdk(target);
+        await applyUpdate(target); // calls process.exit; Claude Code restarts
+    }
+    catch (error) {
+        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}
+/** `reticle rollback` — restore the previous server version and restart. */
+export async function handleRollback() {
+    try {
+        await rollback(); // calls process.exit
+    }
+    catch (error) {
+        log('reticle_rollback_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+    }
+}

package/dist/{cli-verify.js → cli/cli-verify.js}

@@ -12,18 +12,18 @@
 import { join, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, } from '@reticlehq/core';
-import { start } from './index.js';
-import { 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';
-import { renderRunReport } from './runs/render-report.js';
-import { BaselineStore } from './project/baselines.js';
-import { RecordingStore } from './flows/recordings.js';
-import { FlowStore } from './flows/flows.js';
-import { ProjectStore } from './project/project-store.js';
-import { AnnotationStore } from './flows/annotation-store.js';
-import { createNodeFileSystem } from './project/fs-port.js';
+import { start } from '../index.js';
+import { 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';
+import { renderRunReport } from '../runs/render-report.js';
+import { BaselineStore } from '../project/baselines.js';
+import { RecordingStore } from '../flows/recordings.js';
+import { FlowStore } from '../flows/flows.js';
+import { ProjectStore } from '../project/project-store.js';
+import { AnnotationStore } from '../flows/annotation-store.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
 const EXIT_PASS = 0;
 const EXIT_FAIL = 1;
 const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
@@ -63,7 +63,7 @@ export async function runVerify(args, ports) {
             return;
         }
         const names = await conn.listFlows();
-        if (names.length === 0) {
+        if (0 === names.length) {
             ports.fail(MSG_NO_FLOWS);
             ports.exit(EXIT_FAIL);
             return;
@@ -89,7 +89,7 @@ export async function runVerify(args, ports) {
  */
 async function pushRunToCloud(run, ports) {
     const config = resolveCloudConfig(process.env);
-    if (config === null)
+    if (null === config)
         return;
     const result = await syncRunToCloud(run, config, (url, init) => fetch(url, init));
     if (result.outcome === SyncOutcome.SYNCED) {