@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,70 +0,0 @@
-/**
- * Port resolution for the reticle CLI. Split out so it can be unit-tested independently.
- *
- * Priority (highest → lowest):
- * 1. --port flag (parsed by parseCliArgs, already overrides defaultPort)
- * 2. RETICLE_PORT env var
- * 3..reticle.json "port" field in the cwd ← per-project isolation
- * 4. RETICLE_DEFAULT_PORT (4400)
- */
-/** The project config `reticle init` writes. */
-export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
-/**
- * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
- *
- * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
- * working directory was one level away from the config behaved exactly like a project that had
- * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
- * the user to run an install they had already run. That is the shape of several field reports at
- * once — an app wired in a subdirectory, an agent running from a repo root, a worktree beside its
- * main checkout — and they are all the same missing walk.
- *
- * Returns undefined when nothing is found, which keeps every caller's existing default intact.
- */
-export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
-/**
- * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
- * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
- * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
- * diagnosis, and `cli.ts`) are unchanged.
- */
-export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
-/**
- * Read the port stored in the project's .reticle.json (written by `reticle init`).
- * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
- */
-export declare function readProjectPort(cwd: string): number | undefined;
-/**
- * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
- * uses it as the default resolve scope so auto-selection stays within the active app. Returns
- * undefined if the file is absent/unreadable or has no non-empty string projectId.
- */
-export declare function readProjectId(cwd: string): string | undefined;
-/**
- * The framework `reticle init` stamped into `.reticle.json`, when there is one.
- *
- * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
- * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
- * server older than the wiring is its single most likely cause — `init` warns about it at install
- * time and the hint the agent reads hours later never mentioned it.
- */
-export declare function readProjectFramework(cwd: string): string | undefined;
-/**
- * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
- * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env
- * wins so CI/tests can force it off without editing the project file.
- */
-export declare function readJournalEnabled(cwd: string, env: string | undefined): boolean;
-/**
- * Resolve the daemon port from all available sources in priority order.
- * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
- */
-export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
-/**
- * Detect a port mismatch between the daemon and the project's SDK configuration.
- *
- * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
- * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
- * port nothing is listening on — the silent no-connect that #261 documents.
- */
-export declare function diagnosePortMismatch(daemonPort: number, projectPort: number | undefined): string | undefined;

package/dist/cli/cli-port.js

@@ -1,136 +0,0 @@
-/**
- * Port resolution for the reticle CLI. Split out so it can be unit-tested independently.
- *
- * Priority (highest → lowest):
- * 1. --port flag (parsed by parseCliArgs, already overrides defaultPort)
- * 2. RETICLE_PORT env var
- * 3..reticle.json "port" field in the cwd ← per-project isolation
- * 4. RETICLE_DEFAULT_PORT (4400)
- */
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-/** The project config `reticle init` writes. */
-export const RETICLE_CONFIG_BASENAME = '.reticle.json';
-/**
- * How far up to look for the project config before giving up.
- *
- * A cap rather than "walk to the filesystem root" so a process started somewhere unrelated cannot
- * silently adopt a config from a distant ancestor and dial a port that belongs to another project.
- * Deep enough for the layouts that actually broke: an app in `frontend/` or `apps/web/`, a git
- * worktree checked out beside its main repo, and an agent whose cwd is a package inside a monorepo.
- */
-const MAX_CONFIG_SEARCH_DEPTH = 6;
-/**
- * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
- *
- * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
- * working directory was one level away from the config behaved exactly like a project that had
- * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
- * the user to run an install they had already run. That is the shape of several field reports at
- * once — an app wired in a subdirectory, an agent running from a repo root, a worktree beside its
- * main checkout — and they are all the same missing walk.
- *
- * Returns undefined when nothing is found, which keeps every caller's existing default intact.
- */
-export function findProjectConfig(cwd) {
-    let dir = resolve(cwd);
-    for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
-        try {
-            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
-            const config = JSON.parse(raw);
-            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
-                return config;
-            }
-        }
-        catch {
-            // Absent, unreadable, or not JSON at this level — keep walking.
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
-}
-/**
- * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
- * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
- * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
- * diagnosis, and `cli.ts`) are unchanged.
- */
-export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
-/**
- * Read the port stored in the project's .reticle.json (written by `reticle init`).
- * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
- */
-export function readProjectPort(cwd) {
-    const p = findProjectConfig(cwd)?.['port'];
-    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
-        return p;
-    return undefined;
-}
-/**
- * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
- * uses it as the default resolve scope so auto-selection stays within the active app. Returns
- * undefined if the file is absent/unreadable or has no non-empty string projectId.
- */
-export function readProjectId(cwd) {
-    const id = findProjectConfig(cwd)?.['projectId'];
-    if ('string' === typeof id && id.length > 0)
-        return id;
-    return undefined;
-}
-/**
- * The framework `reticle init` stamped into `.reticle.json`, when there is one.
- *
- * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
- * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
- * server older than the wiring is its single most likely cause — `init` warns about it at install
- * time and the hint the agent reads hours later never mentioned it.
- */
-export function readProjectFramework(cwd) {
-    const framework = findProjectConfig(cwd)?.['framework'];
-    if ('string' === typeof framework && framework.length > 0)
-        return framework;
-    return undefined;
-}
-/**
- * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
- * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env
- * wins so CI/tests can force it off without editing the project file.
- */
-export function readJournalEnabled(cwd, env) {
-    if (env !== undefined) {
-        const v = env.trim().toLowerCase();
-        if ('0' === v || 'false' === v || 'off' === v)
-            return false;
-        if ('1' === v || 'true' === v || 'on' === v)
-            return true;
-    }
-    if (false === findProjectConfig(cwd)?.['journal'])
-        return false;
-    return true;
-}
-/**
- * Resolve the daemon port from all available sources in priority order.
- * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
- */
-export function resolvePort(portFlag, envPort, projectPort, defaultPort) {
-    return portFlag ?? envPort ?? projectPort ?? defaultPort;
-}
-/**
- * Detect a port mismatch between the daemon and the project's SDK configuration.
- *
- * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
- * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
- * port nothing is listening on — the silent no-connect that #261 documents.
- */
-export function diagnosePortMismatch(daemonPort, projectPort) {
-    if (projectPort === undefined)
-        return undefined;
-    if (projectPort === daemonPort)
-        return undefined;
-    return (`.reticle.json says "port": ${String(projectPort)} but this daemon is on :${String(daemonPort)}` +
-        ` — the SDK will dial :${String(projectPort)} and never connect. ` +
-        `Either start the daemon with --port ${String(projectPort)}, or update .reticle.json to match.`);
-}

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

@@ -1,112 +0,0 @@
-/**
- * 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 { refreshAgentRules, detectPackageManager, buildNodeIo, SILENT_HOST } from '@reticlehq/init';
-import { SERVER_VERSION } from '../version/server-version.js';
-import { log } from '../log.js';
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.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);
-    // Nothing to trace and nothing to report: this reads the manifest and runs one package-manager
-    // command. It never enters `runInit`, so there is no init outcome for a host to carry.
-    const io = buildNodeIo(cwd, SILENT_HOST);
-    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 });
-        // Bring this project's agent rules up with the version.
-        //
-        // The managed block has always been updatable — marker-delimited, idempotent by comparing
-        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
-        // from `buildPlan` alone, so a project set up on an older release kept that release's
-        // instructions forever and every improvement to them reached new projects only.
-        //
-        // That is backwards: the people who most need better instructions are the ones already
-        // installed and not getting value, and this is the moment they are touching the install anyway.
-        // Only files that ALREADY carry the block are touched, and only inside the markers.
-        const refreshed = refreshAgentRules(process.cwd(), {
-            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
-            write: (path, content) => {
-                writeFileSync(path, content, 'utf8');
-            },
-        });
-        if (0 !== refreshed.updated.length)
-            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
-        // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
-        // whose job is keeping an install current was itself a way to produce a version-skewed pair —
-        // and the skew message told people to run it to fix an outdated SDK, which it could not do.
-        //
-        // 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/cli-verify.d.ts

@@ -1,86 +0,0 @@
-/**
- * `reticle verify <url>` — one-shot, non-MCP verification. It boots the engine in drive mode (Reticle owns
- * a browser pointed at the preview URL), waits for the in-page SDK to dial back, replays every saved
- * flow, renders the verdict, and exits 0 on pass / 1 otherwise. The same ReticleRunner + verdict the MCP
- * and HTTP paths use — so a platform/CI agent that can only run a shell command (Lovable, Emergent,
- * GitHub Actions) gets a byte-identical artifact without speaking MCP.
- *
- * The orchestration (runVerify) is split from the live wiring (openLiveConnection) behind VerifyPorts,
- * so the decision logic — including the two honesty guards (no session, no flows ⇒ never a green pass)
- * — is unit-tested without launching a real browser.
- */
-import { type ReticleVerificationRun } from '@reticlehq/core';
-import { type VerifyProgressListener } from '../runs/reticle-runner.js';
-/** The live capabilities runVerify needs — faked in tests so the logic runs without a browser. */
-export interface VerifyConnection {
-    /** Resolve true once a browser session has connected, or false at timeout. */
-    sessionReady(timeoutMs: number): Promise<boolean>;
-    listFlows(): Promise<string[]>;
-    /**
-     * `onProgress` is narration for a run in flight — see `verify-progress.ts` in core. Optional at
-     * every layer: a connection that ignores it behaves exactly as it did before.
-     */
-    verify(onProgress?: VerifyProgressListener): Promise<ReticleVerificationRun>;
-    close(): Promise<void>;
-}
-export interface VerifyPorts {
-    connect: () => Promise<VerifyConnection>;
-    out: (line: string) => void;
-    fail: (line: string) => void;
-    exit: (code: number) => void;
-}
-interface VerifyArgs {
-    url: string;
-    timeoutMs: number;
-}
-/** Orchestration: boot → wait for a session → replay flows → verdict → exit code. Browser-free. */
-export declare function runVerify(args: VerifyArgs, ports: VerifyPorts): Promise<void>;
-/** Split a drive URL into its origin + whether it's loopback — decides token/injection pairing. */
-export declare function urlParts(url: string): {
-    origin?: string;
-    loopback: boolean;
-};
-/** CLI entry — wires the live ports and runs the one-shot verification. Exits the process itself. */
-/**
- * What a user reads when the bridge port is already taken by a daemon.
- *
- * `verify` boots its OWN daemon, and it has to do so on the port the APP dials — a loopback page
- * connects natively to the port baked into its config, so verify cannot simply pick a free one and
- * still be found. On any machine with Reticle set up, that port already belongs to a running daemon.
- *
- * It used to die there. The listen failure surfaces asynchronously on the server object, after
- * `start` has resolved, so nothing caught it and the process printed a raw `node:net` stack — the
- * worst answer available, and reached most often by the people with the fewest other options, since
- * the skill offers this command as the way to a verdict with no MCP at all.
- *
- * The message says every way out rather than picking one, and it says FIRST that a busy port is the
- * normal state rather than a fault — an install that worked leaves a daemon on it, so a reader who
- * arrives here has done nothing wrong and should not go looking for what they broke (#689).
- *
- * `reticle drive` leads, because it is the only option that works in the state most people are in
- * when they reach this message: the client exposes no `reticle_*` tools (Codex, Cursor Cloud,
- * Antigravity, a session whose MCP link dropped), which is exactly when the CLI is reached for. It
- * ATTACHES to the running daemon rather than binding — see cli/drive-attach.ts — so there is nothing
- * to stop, nothing to race, and it hands back a sessionId the daemon owns. The advice that used to
- * lead, "ask the daemon through the tools", is the one thing that reader by construction cannot do.
- *
- * Stopping the daemon stays on the list and stays LAST of the working options, with the reason: the
- * MCP proxy respawns one into the gap, so `stop` is a race the caller usually loses, and it kills
- * the agent's own link on the way past.
- *
- * `verify` itself attaching, rather than needing the port at all, is the real fix and is #689's
- * first bullet — not this change.
- */
-export declare function portBusyMessage(port: number): string;
-export declare function handleVerify(parsed: {
-    url: string;
-    /** A parsed predicate for a flow-free, one-shot verdict against the running daemon. */
-    expect?: unknown;
-    headless: boolean;
-    timeoutMs?: number;
-    storageState?: string;
-    sessionId?: string;
-    /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
-    port: number;
-}): void;
-export {};