@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/cli-flow-commands.d.ts

@@ -9,6 +9,7 @@ import { type ChangedFiles } from '../../language/flows/change/git-changed.js';
 import { type ProjectId } from '@reticlehq/core';
 import { type FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import { type NamedFlow } from '../../language/flows/change/flow-sources.js';
+import { type GateCompleted } from '@reticlehq/core/telemetry';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 /**
@@ -30,4 +31,9 @@ export declare function handleGate(files: string[], since: string | undefined,
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook?: boolean, 
 /** Accept today's coverage levels as the best before judging, for a drop that was intended. */
-acceptCoverage?: boolean): Promise<void>;
+acceptCoverage?: boolean, 
+/**
+ * Called once with how the gate ended, on every path. `cli.ts` passes the `gate_completed`
+ * sender: telemetry already reaches this directory, so this directory does not reach back.
+ */
+reportGateCompleted?: (gate: GateCompleted) => void): Promise<void>;

package/dist/command/cli/cli-flow-commands.js

@@ -5,7 +5,7 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
-import { GateExit, MSG_GATE_NO_FLOWS, msgGateRegression, msgGateRefused, gateExitWith, } from './answers/gate-exit.js';
+import { GATE_OUTCOME, GateExit, MSG_GATE_NO_FLOWS, msgGateRegression, msgGateRefused, gateExitWith, } from './answers/gate-exit.js';
 import { knownRegression } from './known-regression.js';
 import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
@@ -13,6 +13,7 @@ import { changedFilesSince } from '../../language/flows/change/git-changed.js';
 import { isAbsolute, join, sep } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
+import { namedFlowsIn } from '../../language/flows/flow-store-for-session.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { affectedSavedFlows, toFlowSources, } from '../../language/flows/change/flow-sources.js';
@@ -25,6 +26,7 @@ import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js
 import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
 import { readFileSync, statSync } from 'node:fs';
 import { log } from '../../log.js';
+import { GateOutcome } from '@reticlehq/core/telemetry';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 /**
@@ -34,8 +36,9 @@ import { log } from '../../log.js';
  */
 export async function resolveChangedFiles(files, since, cwd) {
     // No ref means no question was asked of git, which is not a failure to answer one.
-    if (since === undefined)
+    if (since === undefined) {
         return { files, failed: false };
+    }
     const changed = await changedFilesSince(since, cwd);
     return {
         files: [...new Set([...files, ...changed.files])],
@@ -52,14 +55,7 @@ export async function resolveChangedFiles(files, since, cwd) {
  * confident negative about somebody else's project, which is worse than an error.
  */
 export async function loadNamedFlows(fs, reticleRoot, projectId) {
-    const store = new FlowStore(fs, reticleRoot, { now: () => Date.now() });
-    const flows = [];
-    for (const name of await store.list(projectId)) {
-        const loaded = await store.load(name, projectId);
-        if (loaded.ok)
-            flows.push({ name: loaded.value.name, steps: loaded.value.steps });
-    }
-    return flows;
+    return await namedFlowsIn(new FlowStore(fs, reticleRoot, { now: () => Date.now() }), projectId);
 }
 /**
  * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
@@ -81,8 +77,9 @@ function atChangedPath(cwd, file, read) {
             return undefined;
         }
     };
-    if (isAbsolute(file))
+    if (isAbsolute(file)) {
         return attempt(file);
+    }
     const parts = file.split('/');
     const cwdParts = cwd.split(sep);
     for (let i = 0; i < parts.length; i += 1) {
@@ -91,8 +88,9 @@ function atChangedPath(cwd, file, read) {
             continue;
         }
         const found = attempt(join(cwd, ...parts.slice(i)));
-        if (found !== undefined)
+        if (found !== undefined) {
             return found;
+        }
     }
     return undefined;
 }
@@ -122,8 +120,9 @@ async function currentPassing(fs, root, flows, affected, changed) {
         const own = 0 === sources.length ? changed : changed.filter((f) => sourceMatchesChange(f, sources));
         const stale = affected.includes(name) &&
             own.some((f) => !((changedFileModifiedAt(cwd, f) ?? Infinity) < at));
-        if (!stale)
+        if (!stale) {
             passing.push(name);
+        }
     }
     return passing;
 }
@@ -131,7 +130,12 @@ export async function handleGate(files, since,
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook = false, 
 /** Accept today's coverage levels as the best before judging, for a drop that was intended. */
-acceptCoverage = false) {
+acceptCoverage = false, 
+/**
+ * Called once with how the gate ended, on every path. `cli.ts` passes the `gate_completed`
+ * sender: telemetry already reaches this directory, so this directory does not reach back.
+ */
+reportGateCompleted = () => undefined) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -207,13 +211,17 @@ acceptCoverage = false) {
         // once the exit code is: it said "pass": true over an exit of 1 or 3.
         const known = await knownRegression(reticleRoot);
         const regressed = known.broken;
-        const local = pass
-            ? GateExit.PASS
-            : result.pass && flowCoverage.outcome !== undefined
-                ? GateExit.NOTHING_TO_CHECK
-                : GateExit.FAIL;
+        let local = GateExit.FAIL;
+        if (pass) {
+            local = GateExit.PASS;
+        }
+        else if (result.pass && flowCoverage.outcome !== undefined) {
+            local = GateExit.NOTHING_TO_CHECK;
+        }
         // Fails closed in CI, not in an agent's stop hook, where it would block over a key, not a change.
         const code = gateExitWith(local, regressed?.length, !hook && known.refused !== undefined);
+        // What the gate judged, sent before a hook's skip can turn the exit code into a pass.
+        reportGateCompleted({ outcome: GATE_OUTCOME[code], flowsChecked: affected.length });
         log('reticle_gate', {
             pass: GateExit.PASS === code,
             uncovered: result.uncovered,
@@ -237,14 +245,18 @@ acceptCoverage = false) {
         // A regression the platform already knows fails the build here too, with `reticle runs
         // regression`'s code, so the gate is the one command CI needs. Best-effort: unlinked or offline
         // changes nothing.
-        if (regressed !== undefined && 0 < regressed.length)
+        if (regressed !== undefined && 0 < regressed.length) {
             log('reticle_gate_regression', { broken: regressed });
-        if (known.refused !== undefined)
+        }
+        if (known.refused !== undefined) {
             process.stderr.write(`${msgGateRefused(known.refused)}\n`);
-        if (GateExit.NOTHING_TO_CHECK === code && !hook)
+        }
+        if (GateExit.NOTHING_TO_CHECK === code && !hook) {
             process.stderr.write(`${MSG_GATE_NO_FLOWS}\n`);
-        if (GateExit.REGRESSION === code && !hook && regressed !== undefined)
+        }
+        if (GateExit.REGRESSION === code && !hook && regressed !== undefined) {
             process.stderr.write(`${msgGateRegression(regressed)}\n`);
+        }
         if (GateExit.PASS !== code) {
             process.exitCode = code;
             if (hook) {
@@ -267,13 +279,16 @@ acceptCoverage = false) {
                     unexecuted: result.unexecuted,
                     regressed: regressed?.length ?? 0,
                 });
-                if (message !== undefined)
+                if (message !== undefined) {
                     process.stderr.write(`${message}\n`);
+                }
             }
         }
     }
     catch (error) {
         log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
+        // No flow count: the gate broke before it judged, so a count would describe nothing.
+        reportGateCompleted({ outcome: GateOutcome.ERROR });
         process.exitCode = GateExit.FAIL;
     }
 }

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

@@ -17,6 +17,7 @@
  * written, or belongs to a daemon from another checkout. `kill` asks the PORT, which is the thing the
  * user actually wants freed, and falls back to the pid file only where the lookup cannot run.
  */
+import { PortPresence } from '../daemon/binding/port-presence.js';
 import { type PortHolder } from './ports/port-holder.js';
 /** What the plan says to do with the port. */
 export declare const KillAction: {
@@ -62,6 +63,26 @@ export declare function planKill(input: {
  * wrong token, or no answer: the caller then sends the signal as before.
  */
 export declare function requestShutdown(port: number, token?: string | undefined): Promise<boolean>;
+/**
+ * How long the second look waits for `/status`. The usual probe gives up after 1 second, and on a
+ * busy machine a healthy daemon took longer than that. A daemon that answers slowly is busy, not
+ * stuck, and other agents can use it.
+ */
+export declare const WEDGED_STATUS_TIMEOUT_MS = 10000;
+/**
+ * Stop a Reticle daemon that holds `port` and does not answer. True when it stopped one (#1937).
+ *
+ * The MCP proxy used to move to another port when it found one. The app's SDK dials the old port,
+ * so the new daemon got no page. Stopping the stuck daemon keeps the port the app dials. The holder
+ * must have a Reticle daemon's command line, so a stranger and the proxy itself are never signalled.
+ */
+export declare function stopWedgedDaemon(port: number, deps?: {
+    /** `statusTimeoutMs`: how long to wait for `/status`. Absent: the usual short probe. */
+    presence: (statusTimeoutMs?: number) => Promise<PortPresence>;
+    holder: () => PortHolder | null;
+    kill: () => Promise<boolean>;
+    wait: (ms: number) => Promise<void>;
+}): Promise<boolean>;
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export declare function runKill(port: number, force: boolean): Promise<boolean>;
 export {};

package/dist/command/cli/cli-kill.js

@@ -22,7 +22,8 @@ import { isAlive, readPid, removePid } from '../daemon/daemon.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { log } from '../../log.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { captureLookup, findPortHolder } from './ports/port-holder.js';
+import { captureLookup } from './ports/port-holder.js';
+import { identifyPortHolder } from '../daemon/port-state.js';
 import * as http from 'node:http';
 import { LOOPBACK_HOST, SHUTDOWN_PATH } from '@reticlehq/core';
 import { storedPairingToken } from '../../portal/bridge/pairing-token.js';
@@ -50,7 +51,8 @@ export function planKill(input) {
             return { action: KillAction.NOTHING, forced: false, identifiedListener: false };
         return { action: KillAction.KILL, pid: recordedPid, forced: false, identifiedListener: false };
     }
-    const ours = answersStatus || listener.pid === recordedPid;
+    // `reticleDaemon`: its command line says so, though it answers nothing and no pid file names it.
+    const ours = answersStatus || listener.pid === recordedPid || true === listener.reticleDaemon;
     if (ours || force) {
         return {
             action: KillAction.KILL,
@@ -67,7 +69,7 @@ export function planKill(input) {
         holder: listener,
         reason: `pid ${String(listener.pid)} ("${listener.command}") is listening, and it is not a Reticle ` +
             `daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would ` +
-            `be killing someone else's process. If that is what you meant, \`reticle restart ${FORCE_FLAG}\` ` +
+            `be killing someone else's process. If that is what you meant, \`reticle serve --restart ${FORCE_FLAG}\` ` +
             `stops it and starts Reticle there (\`stop ${FORCE_FLAG}\` never does); or start Reticle on ` +
             `another port.`,
     };
@@ -156,12 +158,53 @@ async function terminate(pid, asked = false) {
  */
 const PROXY_SPARED_NOTE = 'only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, ' +
     'not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call.';
+/**
+ * How long a daemon that holds the port gets to answer before it counts as stuck. A daemon that has
+ * just bound answers in far less, so a second look after this does not stop one that is starting.
+ */
+const WEDGED_GRACE_MS = 2_000;
+/**
+ * How long the second look waits for `/status`. The usual probe gives up after 1 second, and on a
+ * busy machine a healthy daemon took longer than that. A daemon that answers slowly is busy, not
+ * stuck, and other agents can use it.
+ */
+export const WEDGED_STATUS_TIMEOUT_MS = 10_000;
+/**
+ * Stop a Reticle daemon that holds `port` and does not answer. True when it stopped one (#1937).
+ *
+ * The MCP proxy used to move to another port when it found one. The app's SDK dials the old port,
+ * so the new daemon got no page. Stopping the stuck daemon keeps the port the app dials. The holder
+ * must have a Reticle daemon's command line, so a stranger and the proxy itself are never signalled.
+ */
+export async function stopWedgedDaemon(port, deps = {
+    presence: (statusTimeoutMs) => probePresence(port, {
+        tcpOpen: probeDaemon,
+        status: (p) => fetchStatus(p, LOOPBACK_HOST, false, statusTimeoutMs),
+    }),
+    holder: () => identifyPortHolder(port, captureLookup),
+    kill: () => runKill(port, false),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+    if (PortPresence.FOREIGN !== (await deps.presence())) {
+        return false;
+    }
+    const holder = deps.holder();
+    if (true !== holder?.reticleDaemon) {
+        return false;
+    }
+    await deps.wait(WEDGED_GRACE_MS);
+    if (PortPresence.FOREIGN !== (await deps.presence(WEDGED_STATUS_TIMEOUT_MS))) {
+        return false;
+    }
+    log('reticle_wedged_daemon_stopping', { port, pid: holder.pid });
+    return deps.kill();
+}
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export async function runKill(port, force) {
     const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
     const recorded = readPid(port);
     const plan = planKill({
-        listener: findPortHolder(port, captureLookup),
+        listener: identifyPortHolder(port, captureLookup),
         recordedPid: null !== recorded && isAlive(recorded) ? recorded : null,
         answersStatus: presence === PortPresence.DAEMON,
         force,

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

@@ -0,0 +1,22 @@
+/**
+ * `reticle compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]`. The
+ * command has one recipe. `--state` names the app's stored data to read, and `--port` names the
+ * daemon, as on every command that uses one.
+ *
+ * Split out of `cli-parse.ts` when that file came near the 1000-line cap.
+ */
+import { type ParseError } from './cli-parse-grammar.js';
+export declare const COMPARE_COMMAND = "compare";
+export type CompareArgs = {
+    kind: 'ok';
+    reference: string;
+    candidate: string;
+    base?: string;
+    /** The path of the state sources file. */
+    state?: string;
+    /** Where to write the HTML report. */
+    report?: string;
+    json: boolean;
+    port: number;
+} | ParseError;
+export declare function parseCompareArgs(args: readonly string[], defaultPort: number): CompareArgs;

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

@@ -0,0 +1,75 @@
+/**
+ * `reticle compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]`. The
+ * command has one recipe. `--state` names the app's stored data to read, and `--port` names the
+ * daemon, as on every command that uses one.
+ *
+ * Split out of `cli-parse.ts` when that file came near the 1000-line cap.
+ */
+import { JSON_FLAG, PORT_FLAG, missingOperand, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+export const COMPARE_COMMAND = 'compare';
+/** `compare --base <url>`: the build before the change. */
+const BASE_FLAG = '--base';
+/** `compare --state <file.json>`: the declared state sources to read after each sequence. */
+const STATE_FLAG = '--state';
+/** `compare --report <file>`: also write the result as one HTML page. */
+const REPORT_FLAG = '--report';
+/** `compare` takes exactly a reference url and a candidate url. */
+const COMPARE_URLS = 2;
+export function parseCompareArgs(args, defaultPort) {
+    const urls = [];
+    let base;
+    let state;
+    let report;
+    let json = false;
+    let port = defaultPort;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (JSON_FLAG === arg) {
+            json = true;
+            continue;
+        }
+        if (BASE_FLAG === arg || STATE_FLAG === arg || REPORT_FLAG === arg || PORT_FLAG === arg) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return missingValue(arg);
+            }
+            i += 1;
+            if (BASE_FLAG === arg) {
+                base = value;
+                continue;
+            }
+            if (STATE_FLAG === arg) {
+                state = value;
+                continue;
+            }
+            if (REPORT_FLAG === arg) {
+                report = value;
+                continue;
+            }
+            const n = Number(value);
+            if (!Number.isInteger(n)) {
+                return notANumber(arg, value);
+            }
+            port = n;
+            continue;
+        }
+        if (arg.startsWith('--') || COMPARE_URLS === urls.length) {
+            return unknownArgument(arg);
+        }
+        urls.push(arg);
+    }
+    const [reference, candidate] = urls;
+    if (reference === undefined || candidate === undefined) {
+        return missingOperand(COMPARE_COMMAND, 'a reference url and a candidate url');
+    }
+    return {
+        kind: 'ok',
+        reference,
+        candidate,
+        ...(base === undefined ? {} : { base }),
+        ...(state === undefined ? {} : { state }),
+        ...(report === undefined ? {} : { report }),
+        json,
+        port,
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * `reticle grade <snapshot|judge|tables|suggest> [flags]`: grade a finished run of an app from
+ * snapshots of its stored data. The rules are in `@/features/grade/`.
+ */
+import { type ParseError } from './cli-parse-grammar.js';
+export declare const GRADE_COMMAND = "grade";
+export declare const GradeStep: {
+    readonly SNAPSHOT: "snapshot";
+    readonly JUDGE: "judge";
+    readonly TABLES: "tables";
+    readonly SUGGEST: "suggest";
+};
+export type GradeStep = (typeof GradeStep)[keyof typeof GradeStep];
+/** Each flag that takes a value, and the field it fills. */
+declare const VALUE_FLAGS: {
+    readonly '--state': "state";
+    readonly '--out': "out";
+    readonly '--url': "url";
+    readonly '--reference': "reference";
+    readonly '--again': "again";
+    readonly '--candidate': "candidate";
+    readonly '--expect': "expect";
+    readonly '--answer': "answer";
+    readonly '--list': "list";
+    readonly '--rows': "rows";
+    readonly '--container': "container";
+    readonly '--skip': "skip";
+};
+type GradeField = (typeof VALUE_FLAGS)[keyof typeof VALUE_FLAGS];
+export type GradeArgs = ({
+    kind: 'ok';
+    step: GradeStep;
+    json: boolean;
+} & Partial<Record<GradeField, string>>) | ParseError;
+export declare function parseGradeArgs(args: readonly string[]): GradeArgs;
+export {};

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

@@ -0,0 +1,75 @@
+/**
+ * `reticle grade <snapshot|judge|tables|suggest> [flags]`: grade a finished run of an app from
+ * snapshots of its stored data. The rules are in `@/features/grade/`.
+ */
+import { JSON_FLAG, missingOperand, missingValue, unknownArgument, } from './cli-parse-grammar.js';
+export const GRADE_COMMAND = 'grade';
+export const GradeStep = {
+    SNAPSHOT: 'snapshot',
+    JUDGE: 'judge',
+    TABLES: 'tables',
+    SUGGEST: 'suggest',
+};
+/** Each flag that takes a value, and the field it fills. */
+const VALUE_FLAGS = {
+    '--state': 'state',
+    '--out': 'out',
+    '--url': 'url',
+    '--reference': 'reference',
+    '--again': 'again',
+    '--candidate': 'candidate',
+    '--expect': 'expect',
+    '--answer': 'answer',
+    '--list': 'list',
+    '--rows': 'rows',
+    '--container': 'container',
+    '--skip': 'skip',
+};
+/** The flags each step needs, and the flags it also takes. */
+const STEP_FLAGS = {
+    [GradeStep.SNAPSHOT]: { needs: ['state', 'out'], takes: ['url'] },
+    [GradeStep.JUDGE]: {
+        needs: ['reference', 'again', 'candidate'],
+        takes: ['expect', 'answer'],
+    },
+    [GradeStep.TABLES]: { needs: ['list', 'rows', 'out'], takes: ['container', 'skip'] },
+    [GradeStep.SUGGEST]: { needs: ['state', 'reference', 'again', 'out'], takes: [] },
+};
+const isStep = (word) => Object.values(GradeStep).some((step) => step === word);
+const isValueFlag = (arg) => arg in VALUE_FLAGS;
+const flagOf = (field) => Object.keys(VALUE_FLAGS).find((f) => VALUE_FLAGS[f] === field) ??
+    field;
+export function parseGradeArgs(args) {
+    const [step, ...rest] = args;
+    if (!isStep(step)) {
+        // A known flag before the step is a missing step, not an unknown flag.
+        return step === undefined || isValueFlag(step) || JSON_FLAG === step
+            ? missingOperand(GRADE_COMMAND, `a step first: ${Object.values(GradeStep).join(', ')}`)
+            : unknownArgument(step);
+    }
+    const allowed = new Set([...STEP_FLAGS[step].needs, ...STEP_FLAGS[step].takes]);
+    const values = {};
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i] ?? '';
+        if (JSON_FLAG === arg && GradeStep.JUDGE === step) {
+            json = true;
+            continue;
+        }
+        if (!isValueFlag(arg) || !allowed.has(VALUE_FLAGS[arg])) {
+            return unknownArgument(arg);
+        }
+        const value = rest[i + 1];
+        // An answer may start with "--"; every other value may not.
+        if (value === undefined || ('--answer' !== arg && value.startsWith('--'))) {
+            return missingValue(arg);
+        }
+        values[VALUE_FLAGS[arg]] = value;
+        i += 1;
+    }
+    const missing = STEP_FLAGS[step].needs.filter((field) => values[field] === undefined);
+    if (missing.length > 0) {
+        return missingOperand(`${GRADE_COMMAND} ${step}`, missing.map(flagOf).join(', '));
+    }
+    return { kind: 'ok', step, json, ...values };
+}

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

@@ -26,6 +26,8 @@ export declare const missingOperand: (command: string, what: string) => ParseErr
 /** Show the browser. Shared by every command that can drive one. */
 export declare const HEADED_FLAG = "--headed";
 export declare const PORT_FLAG = "--port";
+/** Print one JSON object. */
+export declare const JSON_FLAG = "--json";
 export declare const VERIFY_COMMAND = "verify";
 /**
  * The predicate flag, shared for the same reason the rest of this file is: two places have to name

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

@@ -36,6 +36,8 @@ export const missingOperand = (command, what) => ({
 /** Show the browser. Shared by every command that can drive one. */
 export const HEADED_FLAG = '--headed';
 export const PORT_FLAG = '--port';
+/** Print one JSON object. */
+export const JSON_FLAG = '--json';
 export const VERIFY_COMMAND = 'verify';
 /**
  * The predicate flag, shared for the same reason the rest of this file is: two places have to name
@@ -49,37 +51,22 @@ export const EXPECT_FLAG = '--expect';
  * 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'],
+    ['affected', 'gate --list'],
+    ['license', 'status'],
+    ['rollback', 'update --rollback'],
+    ['restart', 'serve --restart'],
 ]);
 const HELP_FLAGS = new Set(['--help', '-h']);
 /**
@@ -98,13 +85,24 @@ export function renamedCommandFor(argv) {
  */
 export const REMOVED_COMMANDS = new Map([
     ['hunt', 'it has no replacement'],
-    ['watch', 'use `reticle affected` after you save, or `reticle gate` before you commit'],
+    ['watch', 'use `reticle gate --list` 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',
     ],
+    // Renamed one release earlier, and kept for that one release.
+    ['kill', 'use `reticle stop --force`'],
+    ['login', 'use `reticle connect`'],
+    ['link', 'use `reticle connect`'],
+    ['project', 'use `reticle connect --project <name|id>`'],
+    ['whoami', 'use `reticle status`'],
+    ['push', 'use `reticle sync`'],
+    ['regression', 'use `reticle runs regression`'],
+    ['share', 'use `reticle runs share <runId>`'],
+    ['issues', 'use `reticle runs issues`'],
+    ['memory', 'use `reticle runs memory`'],
 ]);
 export const removedNote = (command, instead) => `\`reticle ${command}\` was removed in this version; ${instead}`;
 const DIM = '\u001b[2m';

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

@@ -1,3 +1,9 @@
+/** A missing step 1 control on a freshly loaded start page fails the flow (#2061). */
+export declare const REQUIRE_START_CONTROL_FLAG = "--require-start-control";
+/** Keep judging after a step whose consequence failed, so every step gets a verdict (the score). */
+export declare const SWEEP_FLAG = "--sweep";
+/** Compare the url with this reference build, and report each difference in what users see. */
+export declare const AGAINST_FLAG = "--against";
 export type VerifySuffix = {
     kind: 'ok';
     url: string;
@@ -14,6 +20,10 @@ export type VerifySuffix = {
     select?: string[];
     resultsJson?: string;
     confirmDangerous?: boolean;
+    requireStartControl?: boolean;
+    sweep?: boolean;
+    /** The reference build's url, when the url is to be compared with it. */
+    against?: string;
 } | {
     kind: 'error';
     message: string;