@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/cli/tutorial.d.ts

@@ -1,19 +1,3 @@
-/**
- * The tutorial: one sequence, two audiences.
- *
- * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
- * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
- * for one and hope the other copes, and you get a page agents skip and humans skim.
- *
- * What both MUST share is the order. Two audiences taking different routes through one product is
- * how a support answer stops matching what anybody actually did.
- *
- * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
- * the page now" has taught the least valuable half: looking is not verifying, and an agent that
- * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
- * because that ordering IS the idea — naming what should happen first is the difference between a
- * check and a rationalisation written afterwards.
- */
 import { type OnboardingStep } from '@reticlehq/core/telemetry';
 /**
  * The two ONBOARD steps a SHOWN tour can honestly answer.
@@ -30,87 +14,3 @@ import { type OnboardingStep } from '@reticlehq/core/telemetry';
  * which is the only place they are a fact.
  */
 export declare function tutorialShownSteps(): OnboardingStep[];
-export declare const TutorialAudience: {
-    /** Prose, and a reason per step. */
-    readonly HUMAN: "human";
-    /** The call, and what comes back. */
-    readonly AGENT: "agent";
-};
-export type TutorialAudience = (typeof TutorialAudience)[keyof typeof TutorialAudience];
-export interface TutorialStep {
-    id: string;
-    /** What this step is, in words. Always present: an agent reading only calls learns the what, not the why. */
-    say: string;
-    /** Why it is worth doing. The half that stops a tutorial being a list of keystrokes. */
-    why: string;
-    /** The exact call, for the audience that would otherwise have to infer it from the prose. */
-    call?: string;
-}
-/**
- * The same steps, shaped for who is reading.
- *
- * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
- * type and not what it means, which is exactly the reader that later reports a green it cannot
- * explain.
- */
-export declare function tutorialScript(audience: TutorialAudience): TutorialStep[];
-/**
- * The script as text for whoever asked.
- *
- * A human gets the reason on its own line, because the reason is what makes the step worth doing and
- * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
- * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
- * the call learns what to type and not what it means, which is the reader that later reports a green
- * it cannot explain.
- */
-/**
- * What to do now the tour is over.
- *
- * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
- * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
- * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
- * how to start it. The steps above describe tools that need an instrumented, running app, and a
- * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
- * where a funnel stalls.
- *
- * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
- * string only findable by matching rendered prose.
- */
-export declare function tutorialNextSteps(audience: TutorialAudience, restartAgent?: boolean): string;
-/**
- * What the installer prints when it has finished.
- *
- * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
- * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
- * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
- *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
- */
-export declare function installClosing(registered?: boolean): string;
-export declare function renderTutorial(audience: TutorialAudience): string;
-export type DemoPlan = {
-    ok: true;
-    ref: string;
-    name: string;
-    call: string;
-} | {
-    ok: false;
-    because: string;
-};
-/**
- * Pick something safe on THIS page, and build the call that proves it moved.
- *
- * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
- * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
- * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
- * habit the tutorial exists to correct.
- *
- * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
- * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
- */
-export declare function demoPlan(controls: readonly {
-    ref: string;
-    name: string;
-    role?: string;
-}[]): DemoPlan;

package/dist/command/cli/tutorial.js

@@ -1,34 +1,4 @@
-/**
- * The tutorial: one sequence, two audiences.
- *
- * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
- * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
- * for one and hope the other copes, and you get a page agents skip and humans skim.
- *
- * What both MUST share is the order. Two audiences taking different routes through one product is
- * how a support answer stops matching what anybody actually did.
- *
- * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
- * the page now" has taught the least valuable half: looking is not verifying, and an agent that
- * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
- * because that ordering IS the idea — naming what should happen first is the difference between a
- * check and a rationalisation written afterwards.
- */
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
-import { TOUR_STEPS } from '@reticlehq/core/tour';
-/**
- * The steps, from the one place both surfaces read them.
- *
- * They used to be a private array here, which is why the browser could not render the same tour:
- * nothing outside this package could see them. `title` and `anchor` are the carousel's business and
- * a terminal ignores them.
- */
-const STEPS = TOUR_STEPS.map((s) => ({
-    id: s.id,
-    say: s.say,
-    why: s.why,
-    ...(undefined === s.call ? {} : { call: s.call }),
-}));
 /**
  * The two ONBOARD steps a SHOWN tour can honestly answer.
  *
@@ -50,154 +20,3 @@ export function tutorialShownSteps() {
         status: OnboardingStepStatus.COMPLETED,
     }));
 }
-export const TutorialAudience = {
-    /** Prose, and a reason per step. */
-    HUMAN: 'human',
-    /** The call, and what comes back. */
-    AGENT: 'agent',
-};
-/**
- * The same steps, shaped for who is reading.
- *
- * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
- * type and not what it means, which is exactly the reader that later reports a green it cannot
- * explain.
- */
-export function tutorialScript(audience) {
-    return STEPS.map((step) => TutorialAudience.AGENT === audience
-        ? { ...step, call: step.call ?? '' }
-        : // A human is not handed a raw call to paste without understanding it; the prose carries it.
-            { id: step.id, say: step.say, why: step.why });
-}
-/**
- * The script as text for whoever asked.
- *
- * A human gets the reason on its own line, because the reason is what makes the step worth doing and
- * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
- * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
- * the call learns what to type and not what it means, which is the reader that later reports a green
- * it cannot explain.
- */
-/**
- * What to do now the tour is over.
- *
- * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
- * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
- * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
- * how to start it. The steps above describe tools that need an instrumented, running app, and a
- * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
- * where a funnel stalls.
- *
- * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
- * string only findable by matching rendered prose.
- */
-export function tutorialNextSteps(audience, restartAgent = false) {
-    const lines = TutorialAudience.AGENT === audience
-        ? [
-            'Next:',
-            '  reticle init            # instrument the project in this directory',
-            '  reticle status          # confirms the app connected, or says why it has not',
-            '  then run the four steps above against it, and report the verdict',
-        ]
-        : [
-            'Next:',
-            ...(restartAgent
-                ? ['  restart your agent                 # it loads new tools only when it starts']
-                : []),
-            '  cd <your project> && reticle init  # wire Reticle into the app',
-            '  npm run dev                        # then load it in a browser',
-            '  reticle status                     # confirms the app connected, or says why not',
-            '',
-            // One line: the terminal wraps it at the reader's width, not ours.
-            'Then ask your agent to drive one real flow and report the verdict. That is the install proving itself, and it is the agent’s job rather than a command you run.',
-        ];
-    return lines.join('\n');
-}
-/**
- * What the installer prints when it has finished.
- *
- * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
- * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
- * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
- *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
- */
-export function installClosing(registered = true) {
-    // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
-    // four-step idea into twenty-five lines of prose between the reader and the next command.
-    const steps = tutorialScript(TutorialAudience.HUMAN).map((step, index) => `  ${String(index + 1)}. ${INSTALL_SAYS[step.id] ?? step.say}`);
-    return [
-        '',
-        '✓ Reticle is installed. How it works:',
-        ...steps,
-        '',
-        tutorialNextSteps(TutorialAudience.HUMAN, registered),
-    ].join('\n');
-}
-/**
- * Tour steps reworded for a reader who has no app wired yet. The in-app tour's "That panel is
- * Reticle" points at a panel on screen; straight after an install there is none to point at.
- */
-const INSTALL_SAYS = {
-    connect: 'Once `reticle init` wires your app, a Reticle panel appears in it: your proof the SDK is connected.',
-};
-export function renderTutorial(audience) {
-    const steps = tutorialScript(audience)
-        .map((step, index) => {
-        const head = `${String(index + 1)}. ${step.say}`;
-        const why = `   why: ${step.why}`;
-        return step.call === undefined || 0 === step.call.length
-            ? `${head}\n${why}`
-            : `${head}\n${why}\n   ${step.call}`;
-    })
-        .join('\n\n');
-    return `${steps}\n\n${tutorialNextSteps(audience)}`;
-}
-/**
- * Names that must never be demonstrated on.
- *
- * Deliberately broad, and deliberately matched on the NAME a user reads rather than on anything
- * structural. A demo runs unattended against an app whose author has never seen this code, so the
- * cost of being wrong is asymmetric: refusing a harmless button wastes a demo, clicking a harmful
- * one costs somebody their data. When those are the two errors available, take the first one every
- * time.
- *
- * `cancel` is here for the case that reads backwards: "Cancel subscription" is destructive, and a
- * word-boundary match on a dismissive "Cancel" would be a false refusal — which is the cheap error.
- */
-const UNSAFE_TO_DEMO = /delete|remove|deploy|publish|pay|purchase|buy|checkout|cancel|revoke|archive|reset|destroy|drop|send|submit|confirm/i;
-/**
- * Pick something safe on THIS page, and build the call that proves it moved.
- *
- * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
- * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
- * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
- * habit the tutorial exists to correct.
- *
- * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
- * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
- */
-export function demoPlan(controls) {
-    const safe = controls.find((c) => !UNSAFE_TO_DEMO.test(c.name));
-    if (safe === undefined) {
-        return {
-            ok: false,
-            because: 0 === controls.length
-                ? 'nothing interactive is on this page yet — load the app and try again'
-                : 'no control here is safe to demonstrate on: every one reads as something that commits. ' +
-                    'Drive it yourself with a consequence you choose.',
-        };
-    }
-    return {
-        ok: true,
-        ref: safe.ref,
-        name: safe.name,
-        // `{ element: { testid } }` reads naturally and is REFUSED: a consequence is a predicate with a
-        // `kind`, and act_and_wait says so in its own refusal text. This line is a call the reader is
-        // meant to paste, so a plausible-but-unparseable spelling here teaches the exact mistake that
-        // tool exists to catch.
-        call: `reticle_act_and_wait { ref: "${safe.ref}", action: "click", ` +
-            `until: { kind: "element", by: "testid", value: "<what should appear>" } }`,
-    };
-}

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

@@ -0,0 +1,19 @@
+/**
+ * `reticle verify --results-json <file>`: the run, one line per journey, for a machine to read.
+ *
+ * The rendered report is for a person, and a CI step that has to post per-journey verdicts somewhere
+ * else would otherwise scrape it. Three words only, the engine's own: a skipped flow is `unknown`,
+ * never rounded up to `yes`, and the run is `yes` only when every journey is.
+ */
+import { Verified, type ReticleVerificationRun } from '@reticlehq/core';
+type JourneyVerdict = typeof Verified.YES | typeof Verified.NO | typeof Verified.UNKNOWN;
+export interface VerifyResults {
+    verdict: JourneyVerdict;
+    results: {
+        journey: string;
+        verdict: JourneyVerdict;
+        reason?: string;
+    }[];
+}
+export declare function verifyResults(run: ReticleVerificationRun): VerifyResults;
+export {};

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

@@ -0,0 +1,29 @@
+/**
+ * `reticle verify --results-json <file>`: the run, one line per journey, for a machine to read.
+ *
+ * The rendered report is for a person, and a CI step that has to post per-journey verdicts somewhere
+ * else would otherwise scrape it. Three words only, the engine's own: a skipped flow is `unknown`,
+ * never rounded up to `yes`, and the run is `yes` only when every journey is.
+ */
+import { RunFlowStatus, VerdictStatus, Verified, } from '@reticlehq/core';
+function journeyVerdict(status) {
+    if (RunFlowStatus.FAIL === status)
+        return Verified.NO;
+    // A heal is consequence-verified before it is reported, so it proves as much as a pass.
+    if (RunFlowStatus.PASS === status || RunFlowStatus.HEALED === status)
+        return Verified.YES;
+    return Verified.UNKNOWN;
+}
+export function verifyResults(run) {
+    const results = run.flows.map((flow) => ({
+        journey: flow.name,
+        verdict: journeyVerdict(flow.status),
+        ...(flow.failureReason === undefined ? {} : { reason: flow.failureReason }),
+    }));
+    const verdict = results.some((r) => Verified.NO === r.verdict)
+        ? Verified.NO
+        : VerdictStatus.PASS === run.verdict.status && results.every((r) => Verified.YES === r.verdict)
+            ? Verified.YES
+            : Verified.UNKNOWN;
+    return { verdict, results };
+}

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

@@ -8,14 +8,3 @@ import type { OnboardingStep } from '@reticlehq/core/telemetry';
  * reporter is built here and handed down to every command that needs one.
  */
 export declare const reportStepFromCli: (step: OnboardingStep) => void;
-/**
- * The two ONBOARD steps `reticle tutorial` can honestly answer.
- *
- * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
- * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
- * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
- * the dispatch chokepoint, because that is the only place they are observations rather than claims.
- * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
- * which is the same substitution the fourth step of the tour exists to warn about.
- */
-export declare function reportTutorialShown(): void;

package/dist/command/cli-onboarding.js

@@ -1,5 +1,4 @@
 import { reportOnboardingStep } from '../telemetry/onboarding-funnel.js';
-import { tutorialShownSteps } from './cli/tutorial.js';
 /**
  * The CLI's half of the setup funnel.
  *
@@ -11,17 +10,3 @@ import { tutorialShownSteps } from './cli/tutorial.js';
 export const reportStepFromCli = (step) => {
     void reportOnboardingStep(step);
 };
-/**
- * The two ONBOARD steps `reticle tutorial` can honestly answer.
- *
- * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
- * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
- * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
- * the dispatch chokepoint, because that is the only place they are observations rather than claims.
- * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
- * which is the same substitution the fourth step of the tour exists to warn about.
- */
-export function reportTutorialShown() {
-    for (const step of tutorialShownSteps())
-        reportStepFromCli(step);
-}

package/dist/command/cli.d.ts

@@ -2,5 +2,25 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
+/**
+ * Said last, when the account is linked and the one thing left is installing a dependency. Exit 0:
+ * connect's job — signing in and linking — is done, and a non-zero exit read as a failed connect.
+ */
+export declare const MSG_CONNECTED_DEPS_PENDING: string;
+/**
+ * How `reticle connect` exits: the cloud step's code when linking failed; 0 when it linked and setup
+ * finished or left only the dependency install (said in `note`); 1 when setup stopped for anything
+ * else. `initUnfinished` is why init's setup did not finish, or undefined when it did.
+ */
+export declare function connectExit(cloudCode: number, initUnfinished: string | undefined): {
+    code: number;
+    note?: string;
+};
+/**
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
+ */
+export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
 export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;