@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,255 @@
+/**
+ * CLI commands that operate on SAVED FLOWS: watch, capsules, and the gate.
+ *
+ * Split out of cli.ts, which was 653 lines — over the project's own cap, and the file a contributor
+ * 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 } from './answers/gate-exit.js';
+import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
+import { readProjectId } from './ports/resolve/cli-port.js';
+import { changedFilesSince } from '../../language/flows/change/git-changed.js';
+import { join } from 'node:path';
+import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
+import { FlowStore } from '../../language/flows/flows.js';
+import { RunStore } from '../../judgement/runs/artifact/run-store.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { affectedSavedFlows } from '../../language/flows/change/flow-sources.js';
+import { gateDecision } from '../../language/flows/change/gate.js';
+import { FlakeStore } from '../../language/flows/stores/flake-store.js';
+import { formatBuddyStatus } from '../../language/flows/buddy-status.js';
+import { CapsuleStore } from '../../judgement/capsule/capsule-store.js';
+import { AssertionTiersStore } from '../../language/flows/stores/assertion-tiers-store.js';
+import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js';
+import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
+import { createWatchBatcher } from '../../language/flows/change/watch-batcher.js';
+import { watch } from 'node:fs';
+import { log } from '../../log.js';
+/** 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. */
+/**
+ * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
+ * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
+ * where `git diff` answers about the wrong repository or about none.
+ */
+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)
+        return { files, failed: false };
+    const changed = await changedFilesSince(since, cwd);
+    return {
+        files: [...new Set([...files, ...changed.files])],
+        failed: changed.failed,
+        ...(changed.reason === undefined ? {} : { reason: changed.reason }),
+    };
+}
+/**
+ * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
+ * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
+ * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
+ * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
+ * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
+ * 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;
+}
+/** File-change extensions worth reacting to (skip node_modules churn, dotfiles, build output). */
+/**
+ * The buddy channel: one ambient line a human can park in a statusline. Deliberately best-effort
+ * and silent on failure — a status line that throws is worse than no status line, and it must never
+ * interfere with the watch loop it rides on.
+ */
+async function emitBuddyStatus(fs, reticleRoot, flows, affected) {
+    try {
+        const latest = await new RunStore(fs, reticleRoot).latest();
+        const passingNames = new Set((latest?.flows ?? [])
+            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
+            .map((f) => f.name));
+        const quarantined = await new FlakeStore(fs, reticleRoot).flakyFlows();
+        const flaky = new Set(quarantined);
+        // A deviation is an at-risk flow with no passing artifact — and a quarantined flake is not a deviation.
+        const deviations = affected.filter((n) => !passingNames.has(n) && !flaky.has(n));
+        log('reticle_buddy', {
+            status: formatBuddyStatus({
+                total: flows.length,
+                passing: passingNames.size,
+                deviations,
+                quarantined,
+            }),
+        });
+    }
+    catch {
+        // never let the ambient line break the watcher
+    }
+}
+const WATCHED_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/;
+const WATCH_DEBOUNCE_MS = 200;
+/**
+ * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
+ * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
+ * change; auto-replaying the affected flows against the app is the next increment. Long-running.
+ */
+export function handleWatch() {
+    const fs = createNodeFileSystem();
+    const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
+    const batcher = createWatchBatcher({
+        debounceMs: WATCH_DEBOUNCE_MS,
+        schedule: (fn, ms) => {
+            setTimeout(fn, ms).unref();
+        },
+        onFlush: (files) => {
+            void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
+                .then(async (flows) => {
+                const result = affectedSavedFlows(flows, files);
+                if (result.affected.length > 0) {
+                    log('reticle_watch_affected', { changed: files, affected: result.affected });
+                }
+                await emitBuddyStatus(fs, reticleRoot, flows, result.affected);
+            })
+                .catch((error) => {
+                log('reticle_watch_failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        },
+    });
+    log('reticle_watch_started', { cwd: process.cwd() });
+    // Print the ambient line once at startup so the human sees where they stand before touching anything.
+    void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
+        .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
+        .catch(() => undefined);
+    watch(process.cwd(), { recursive: true }, (_event, filename) => {
+        if ('string' === typeof filename && WATCHED_EXTENSIONS.test(filename))
+            batcher.onChange(filename);
+    });
+}
+/**
+ * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
+ * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
+ */
+export async function handleCapsules() {
+    try {
+        const fs = createNodeFileSystem();
+        const capsules = await new CapsuleStore(fs, join(process.cwd(), ReticleDir.ROOT)).all();
+        log('reticle_capsules', {
+            count: capsules.length,
+            capsules: capsules.map((c) => ({
+                id: c.id,
+                ...(c.flow === undefined ? {} : { flow: c.flow }),
+                origin: c.origin,
+                expected: c.expected,
+                observed: c.observed,
+                steps: c.steps.length,
+            })),
+        });
+    }
+    catch (error) {
+        log('reticle_capsules_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+    }
+}
+/**
+ * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
+ * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
+ * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
+ */
+export async function handleGate(files, since, 
+/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
+hook = false) {
+    try {
+        const fs = createNodeFileSystem();
+        const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
+        // Same deliberate degradation as the gate: a terminal caller sees git's own error anyway.
+        const changed = (await resolveChangedFiles(files, since, process.cwd())).files;
+        const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
+        const affected = affectedSavedFlows(allFlows, changed).affected;
+        const latest = await new RunStore(fs, reticleRoot).latest();
+        const passing = (latest?.flows ?? [])
+            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
+            .map((f) => f.name);
+        const flaky = await new FlakeStore(fs, reticleRoot).flakyFlows();
+        // Anti-reward-hacking: diff each flow's CURRENT assertions against what it asserted the last
+        // time it passed. A mustHold that dropped from a real consequence to a fakeable presence check is a
+        // green bought by weakening the test — and a flow that covered a changed file but no longer exists
+        // is coverage deleted rather than satisfied. Both block.
+        const baseline = await new AssertionTiersStore(fs, reticleRoot).load();
+        const byName = new Map(allFlows.map((f) => [f.name, f]));
+        const downgraded = Object.entries(baseline)
+            .filter(([name]) => affected.includes(name) && byName.has(name))
+            .map(([name, before]) => {
+            const current = byName.get(name);
+            const after = (current?.steps ?? []).map((s, i) => ({
+                step: i,
+                ...(s.expect === undefined ? {} : { expect: s.expect }),
+            }));
+            return { flow: name, steps: detectDowngrades(before.steps, after).map((d) => d.step) };
+        })
+            .filter((d) => d.steps.length > 0);
+        // A flow with a recorded passing baseline that has since vanished, while its files changed.
+        // A flow that PASSED covering these files and has since vanished is coverage DELETED, not satisfied —
+        // and it can never appear in `affected` (that is derived from flows that still exist), so it must be
+        // matched against the baseline's own recorded sources. Missing this made deleting a flow turn the
+        // gate green, which is precisely the gaming move exists to stop.
+        const changedSet = new Set(changed);
+        const deleted = Object.entries(baseline)
+            .filter(([name, entry]) => !byName.has(name) && entry.sources.some((f) => changedSet.has(f)))
+            .map(([name]) => name);
+        const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
+        // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
+        const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
+        // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
+        // verdict already applies to `reticle verify`; see flowCoverageReport.
+        const flowCoverage = flowCoverageReport(coverage.flows);
+        const pass = result.pass && flowCoverage.outcome === undefined;
+        log('reticle_gate', {
+            pass,
+            uncovered: result.uncovered,
+            quarantined: result.quarantined,
+            ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
+            ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
+            coverage: flowCoverage,
+        });
+        // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
+        // problem to fail. A Stop hook wants to block a real regression and NOT block a project that
+        // has simply not recorded a flow yet — which is every project on its first day, and measured
+        // before this change as an exit 1 that would have blocked every stop. See GateExit.
+        if (!pass) {
+            const code = result.pass && flowCoverage.outcome !== undefined
+                ? GateExit.NOTHING_TO_CHECK
+                : GateExit.FAIL;
+            process.exitCode = code;
+            if (hook) {
+                // An honest escape hatch, because the alternative to one is not compliance — it is somebody
+                // deleting the hook, and a deleted gate protects nothing. Recorded either way.
+                if (process.env[GATE_SKIP_ENV] !== undefined) {
+                    process.stderr.write(`Reticle: gate skipped via ${GATE_SKIP_ENV}. This change is unverified.\n`);
+                    process.exitCode = GateExit.PASS;
+                    return;
+                }
+                const message = gateHookMessage(code, {
+                    uncovered: result.uncovered,
+                    quarantined: result.quarantined,
+                    // A downgrade is reported per flow with its step indices; the hook names the flow.
+                    downgraded: result.downgraded.map((d) => d.flow),
+                    deleted: result.deleted,
+                });
+                if (message !== undefined)
+                    process.stderr.write(`${message}\n`);
+            }
+        }
+    }
+    catch (error) {
+        log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = GateExit.FAIL;
+    }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * `reticle kill` — free the bridge port without taking the agent's transport with it.
+ *
+ * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
+ * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
+ * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
+ * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
+ * because the process that writes it is the one that died. That is the mechanism behind most
+ * "my MCP disconnected" reports (#114, #110).
+ *
+ * The safe form was written down, and a documented incantation is a worse answer than a command: it
+ * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
+ * the command, and it signals exactly one pid — the LISTENER.
+ *
+ * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
+ * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
+ * 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 { type PortHolder } from './ports/port-holder.js';
+/** What the plan says to do with the port. */
+export declare const KillAction: {
+    readonly NOTHING: "nothing";
+    readonly KILL: "kill";
+    readonly REFUSE: "refuse";
+};
+export type KillAction = (typeof KillAction)[keyof typeof KillAction];
+interface KillPlan {
+    action: KillAction;
+    /** The single pid to signal. Present only for `kill`. */
+    pid?: number;
+    /** True when the target was not identifiable as Reticle's and `--force` overrode the refusal. */
+    forced: boolean;
+    /** False when the listener lookup could not run, so the pid came from our own records instead. */
+    identifiedListener: boolean;
+    /** Why we will not act, for `refuse`. */
+    reason?: string;
+    holder?: PortHolder;
+}
+export declare const FORCE_FLAG = "--force";
+/**
+ * Decide what to signal. Pure.
+ *
+ * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
+ * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
+ * records. Refusing it would leave the port held by exactly the process this command exists to clear.
+ */
+export declare function planKill(input: {
+    /** The listener on the port, from a `-sTCP:LISTEN` lookup. Null when there is none, or no `lsof`. */
+    listener: PortHolder | null;
+    /** The pid our records hold for this port, or null when there is none or it is dead. */
+    recordedPid: number | null;
+    /** Whether the port answers `/status`, i.e. whatever holds it is a Reticle daemon. */
+    answersStatus: boolean;
+    force: boolean;
+}): KillPlan;
+/** `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

@@ -0,0 +1,162 @@
+/**
+ * `reticle kill` — free the bridge port without taking the agent's transport with it.
+ *
+ * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
+ * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
+ * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
+ * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
+ * because the process that writes it is the one that died. That is the mechanism behind most
+ * "my MCP disconnected" reports (#114, #110).
+ *
+ * The safe form was written down, and a documented incantation is a worse answer than a command: it
+ * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
+ * the command, and it signals exactly one pid — the LISTENER.
+ *
+ * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
+ * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
+ * 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, probePresence } from '../daemon/binding/port-presence.js';
+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';
+/** What the plan says to do with the port. */
+export const KillAction = {
+    NOTHING: 'nothing',
+    KILL: 'kill',
+    REFUSE: 'refuse',
+};
+export const FORCE_FLAG = '--force';
+/**
+ * Decide what to signal. Pure.
+ *
+ * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
+ * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
+ * records. Refusing it would leave the port held by exactly the process this command exists to clear.
+ */
+export function planKill(input) {
+    const { listener, recordedPid, answersStatus, force } = input;
+    if (null === listener) {
+        // No listener identified. On Windows and in slim containers that means the lookup could not run
+        // rather than that the port is free, so the recorded pid is the best target we have — and the
+        // report says which of the two it is rather than implying a lookup we never made.
+        if (null === recordedPid)
+            return { action: KillAction.NOTHING, forced: false, identifiedListener: false };
+        return { action: KillAction.KILL, pid: recordedPid, forced: false, identifiedListener: false };
+    }
+    const ours = answersStatus || listener.pid === recordedPid;
+    if (ours || force) {
+        return {
+            action: KillAction.KILL,
+            pid: listener.pid,
+            forced: !ours,
+            identifiedListener: true,
+            holder: listener,
+        };
+    }
+    return {
+        action: KillAction.REFUSE,
+        forced: false,
+        identifiedListener: true,
+        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. Run it again with ${FORCE_FLAG} if that is what you ` +
+            `meant, or start Reticle on another port.`,
+    };
+}
+/** How long the target gets to exit on SIGTERM before we stop asking politely. */
+const GRACEFUL_KILL_MS = 5_000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_KILL_MS = 2_000;
+const KILL_POLL_MS = 100;
+/**
+ * Signal ONE pid and wait for it to go: SIGTERM, then SIGKILL, then give up and say it survived.
+ *
+ * The escalation is the reason this exists rather than a bare SIGTERM — there is a field report of a
+ * daemon that ignored SIGTERM until a human ran `kill -9` by hand, which is the moment the `lsof -ti`
+ * pipeline gets typed and the agent's proxy dies with the daemon.
+ */
+async function terminate(pid) {
+    const signal = (name) => {
+        try {
+            process.kill(pid, name);
+        }
+        catch {
+            // Gone between the liveness check and here. The next poll reports it as gone.
+        }
+    };
+    signal('SIGTERM');
+    const started = Date.now();
+    let escalated = false;
+    for (;;) {
+        await new Promise((resolve) => setTimeout(resolve, KILL_POLL_MS));
+        if (!isAlive(pid))
+            return { gone: true, escalated };
+        const waited = Date.now() - started;
+        if (!escalated && waited > GRACEFUL_KILL_MS) {
+            escalated = true;
+            signal('SIGKILL');
+            continue;
+        }
+        if (waited > GRACEFUL_KILL_MS + FORCED_KILL_MS)
+            return { gone: false, escalated };
+    }
+}
+/**
+ * What was NOT touched, said out loud on every kill.
+ *
+ * The command exists because of a pipeline that killed more than the reader intended and never told
+ * them, so a report that lists only the casualty repeats half the mistake. An `reticle mcp` proxy on
+ * this port survives, and its own recovery from a dead daemon is good: it goes dormant and restarts
+ * one on the next request.
+ */
+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.';
+/** `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),
+        recordedPid: null !== recorded && isAlive(recorded) ? recorded : null,
+        answersStatus: presence === PortPresence.DAEMON,
+        force,
+    });
+    if (KillAction.NOTHING === plan.action) {
+        removePid(port);
+        log('reticle_kill_nothing_to_do', { port, presence });
+        return true;
+    }
+    if (KillAction.REFUSE === plan.action) {
+        log('reticle_kill_refused', { port, reason: plan.reason, holder: plan.holder?.command });
+        return false;
+    }
+    const pid = plan.pid;
+    if (pid === undefined) {
+        // Unreachable by construction (planKill never returns KILL without a pid, and a test pins that),
+        // but the alternative to this branch is a non-null assertion, which this codebase does not use.
+        log('reticle_kill_nothing_to_do', { port, presence });
+        return true;
+    }
+    const { gone, escalated } = await terminate(pid);
+    if (gone)
+        removePid(port);
+    log(gone ? 'reticle_killed' : 'reticle_kill_survived', {
+        port,
+        pid,
+        escalated,
+        ...(plan.forced ? { forced: true } : {}),
+        // Say where the pid came from. Without `lsof` this is the pid we recorded, not the pid we
+        // observed listening, and those are different claims.
+        listenerIdentified: plan.identifiedListener,
+        note: gone
+            ? PROXY_SPARED_NOTE
+            : `pid ${String(pid)} survived SIGKILL, so it is not yours to kill (permissions) or is an ` +
+                `unkillable zombie. The port is still held. ${PROXY_SPARED_NOTE}`,
+    });
+    return gone;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * The words the CLI grammar is made of, and what it says when it does not understand one.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap, and shared rather than copied for
+ * one reason: a flag name written twice is a flag name that can be renamed once. The error
+ * constructors travel with the flags because every one of them prints a flag.
+ */
+/** A command the grammar rejected, carrying the sentence the user reads. */
+export type ParseError = {
+    kind: 'error';
+    message: string;
+};
+export declare const unknownArgument: (arg: string) => ParseError;
+/**
+ * A flag that used to exist, answered by name rather than as "unknown argument".
+ *
+ * Getting started is three stages — installation, onboarding, the first run — and `init` owns the
+ * middle one. The flags that configured the drive it used to do are still written down in agent
+ * instruction files and in scripts, so the reader who passes one is following what we told them.
+ * "unknown argument '--flow'" reads as a typo; naming the stage it moved to is the whole answer.
+ */
+export declare const retiredFlag: (flag: string, moved: string) => ParseError;
+export declare const missingValue: (flag: string) => ParseError;
+export declare const notANumber: (flag: string, value: string) => ParseError;
+export declare const missingOperand: (command: string, what: string) => ParseError;
+/** Show the browser. Shared by every command that can drive one. */
+export declare const HEADED_FLAG = "--headed";
+export declare const PORT_FLAG = "--port";
+export declare const VERIFY_COMMAND = "verify";

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

@@ -0,0 +1,39 @@
+/**
+ * The words the CLI grammar is made of, and what it says when it does not understand one.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap, and shared rather than copied for
+ * one reason: a flag name written twice is a flag name that can be renamed once. The error
+ * constructors travel with the flags because every one of them prints a flag.
+ */
+export const unknownArgument = (arg) => ({
+    kind: 'error',
+    message: `unknown argument '${arg}'`,
+});
+/**
+ * A flag that used to exist, answered by name rather than as "unknown argument".
+ *
+ * Getting started is three stages — installation, onboarding, the first run — and `init` owns the
+ * middle one. The flags that configured the drive it used to do are still written down in agent
+ * instruction files and in scripts, so the reader who passes one is following what we told them.
+ * "unknown argument '--flow'" reads as a typo; naming the stage it moved to is the whole answer.
+ */
+export const retiredFlag = (flag, moved) => ({
+    kind: 'error',
+    message: `${flag} is no longer an \`init\` flag: ${moved}`,
+});
+export const missingValue = (flag) => ({
+    kind: 'error',
+    message: `${flag} needs a value`,
+});
+export const notANumber = (flag, value) => ({
+    kind: 'error',
+    message: `${flag} expects a number, got '${value}'`,
+});
+export const missingOperand = (command, what) => ({
+    kind: 'error',
+    message: `${command} needs ${what}`,
+});
+/** Show the browser. Shared by every command that can drive one. */
+export const HEADED_FLAG = '--headed';
+export const PORT_FLAG = '--port';
+export const VERIFY_COMMAND = 'verify';

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

@@ -0,0 +1,22 @@
+export type VerifySuffix = {
+    kind: 'ok';
+    url: string;
+    headless: boolean;
+    port: number;
+    timeoutMs?: number;
+    storageState?: string;
+    sessionId?: string;
+    expect?: unknown;
+    explore?: boolean;
+    persona?: string;
+    select?: string[];
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]
+ * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
+ * env + `.reticle.json` + 4400.
+ */
+export declare function parseVerifySuffix(args: string[], defaultPort: number): VerifySuffix;