@reticlehq/server 2.14.0 → 3.2.0

package/dist/cloud/account-state.d.ts

@@ -1,20 +0,0 @@
-/**
- * Is this machine signed in to a Reticle workspace?
- *
- * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
- * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
- * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
- * in — resolves through here.
- *
- * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
- * only the SHAPE (`AccountState`) is in core, where the contract belongs.
- */
-import { type AccountState } from '@reticlehq/core';
-/**
- * Read the account state for this machine.
- *
- * The env key WINS over the session file: an agent handed a key is authenticating as that key,
- * whatever a human left on disk, and reporting the human's org there would be a lie about who is
- * acting.
- */
-export declare function readAccountState(home: string, env: NodeJS.ProcessEnv): AccountState;

package/dist/cloud/account-state.js

@@ -1,65 +0,0 @@
-/**
- * Is this machine signed in to a Reticle workspace?
- *
- * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
- * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
- * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
- * in — resolves through here.
- *
- * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
- * only the SHAPE (`AccountState`) is in core, where the contract belongs.
- */
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
-import { CloudEnv } from './cloud-sync.js';
-import { SESSION_FILE } from '../cli/cloud-kit.js';
-/** Signed OUT is the safe answer: it shows the way in, where a wrong "signed in" hides it. */
-const SIGNED_OUT = { signedIn: false };
-/**
- * The fields we read off the session file, and nothing else.
- *
- * Narrowed by hand rather than parsed with the login schema on purpose: this function must be unable
- * to carry a token even if the file grows one, and the surest way to guarantee that is never to bind
- * it to a name here.
- */
-function fromSessionFile(home) {
-    try {
-        const raw = JSON.parse(readFileSync(join(home, ReticleDir.ROOT, SESSION_FILE), 'utf8'));
-        if ('object' !== typeof raw || null === raw)
-            return undefined;
-        const record = raw;
-        // A half-written or hand-edited file must not read as authenticated. `signedIn: true` is the
-        // claim that costs something when wrong, because it hides the way in.
-        if ('string' !== typeof record['token'] || 0 === record['token'].length)
-            return undefined;
-        const org = record['orgName'];
-        const host = record['url'];
-        return {
-            signedIn: true,
-            ...('string' === typeof org && org.length > 0 ? { org } : {}),
-            ...('string' === typeof host && host.length > 0 ? { host } : {}),
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Read the account state for this machine.
- *
- * The env key WINS over the session file: an agent handed a key is authenticating as that key,
- * whatever a human left on disk, and reporting the human's org there would be a lie about who is
- * acting.
- */
-export function readAccountState(home, env) {
-    const key = env[CloudEnv.KEY];
-    const url = env[CloudEnv.URL];
-    if ('string' === typeof key && key.length > 0) {
-        return {
-            signedIn: true,
-            ...('string' === typeof url && url.length > 0 ? { host: url.replace(/\/+$/, '') } : {}),
-        };
-    }
-    return fromSessionFile(home) ?? SIGNED_OUT;
-}

package/dist/cloud/cloud-config.d.ts

@@ -1,57 +0,0 @@
-import type { FileSystemPort } from '../project/fs-port.js';
-import { type CloudConfig } from './cloud-sync.js';
-/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
-/** Re-exported so the existing importers keep working; the string itself lives in core. */
-export declare const CLOUD_LINK_FILE: "cloud.json";
-/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
-export declare const CREDENTIALS_FILE = "credentials.json";
-/** What the daemon mirrors to the cloud for a project. Each surface is independently toggleable. */
-interface SyncPolicy {
-    /** Push verification-run artifacts to the dashboard Runs tab. */
-    runs: boolean;
-    /** Push per-flow project-memory outcomes (the regression history). */
-    memory: boolean;
-    /** Sync saved flow files (the shared regression suite). */
-    flows: boolean;
-}
-/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
-export declare const VerifyMode: {
-    readonly LOCAL: "local";
-    readonly SERVER: "server";
-};
-export type VerifyMode = (typeof VerifyMode)[keyof typeof VerifyMode];
-/** The resolved cloud picture for one project. `config === null` ⇒ cloud NOT attached (stay 100% local). */
-export interface ProjectCloud {
-    config: CloudConfig | null;
-    policy: SyncPolicy;
-    verify: VerifyMode;
-    /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
-    projectId: string | null;
-}
-/** Look up the API key for a cloud project id in the user credentials map. */
-/**
- * The API key this machine holds for one project ON ONE CLOUD.
- *
- * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
- * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
- * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
- * whichever was linked last wins. Measured: two repos on one machine, and the production key was
- * being sent to a localhost server, which answered 401.
- *
- * That is the same class of defect as sending a session token to a host that did not issue it, and
- * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
- * at all is better than one belonging to somewhere else.
- *
- * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
- * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
- * refusing it would silently unlink every repo that predates this change, which is a worse outage
- * than the collision. Re-linking upgrades a repo to the safe shape.
- */
-export declare const credentialSlot: (url: string, projectId: string, orgId?: string) => string;
-/**
- * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
- * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
- * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
- */
-export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
-export {};

package/dist/cloud/cloud-config.js

@@ -1,145 +0,0 @@
-/**
- * Per-project cloud resolution for a SHARED daemon. One reticle MCP/daemon serves many projects; each
- * project declares its own cloud binding + sync policy in `<root>/.reticle/cloud.json`, and the SECRET
- * (the API key) lives once per user in `~/.reticle/credentials.json` (keyed by cloud project id) — never
- * in the repo. The daemon resolves "is cloud attached for THIS project, and what should I push where?"
- * from those two files, falling back to the global `RETICLE_CLOUD_*` env vars for the single-project /
- * CI case (backward compatible).
- *
- * Vercel-style split: `.reticle/cloud.json` is the safe-to-commit-but-gitignored binding, the key is a
- * user-level credential. "Cloud attached" = a valid link file AND a key for its project id (or env creds).
- */
-import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
-import { resolveCloudConfig } from './cloud-sync.js';
-/** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
-/** Re-exported so the existing importers keep working; the string itself lives in core. */
-export const CLOUD_LINK_FILE = ReticleDir.CLOUD_LINK_FILE;
-/** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
-export const CREDENTIALS_FILE = 'credentials.json';
-const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true };
-/** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
-export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
-const asBool = (v, fallback) => ('boolean' === typeof v ? v : fallback);
-/** Read + JSON-parse a file, or null on any problem (missing/malformed) — never throws. */
-async function readJson(fs, path) {
-    try {
-        if (!(await fs.exists(path)))
-            return null;
-        return JSON.parse(await fs.readFile(path));
-    }
-    catch {
-        return null;
-    }
-}
-/** Validate the shape of `.reticle/cloud.json`. Requires projectId + url; policy/verify default in. */
-function parseLink(raw) {
-    if (typeof raw !== 'object' || null === raw)
-        return null;
-    const o = raw;
-    if (typeof o.projectId !== 'string' || 0 === o.projectId.length)
-        return null;
-    if (typeof o.url !== 'string' || 0 === o.url.length)
-        return null;
-    const sync = 'object' === typeof o.sync && o.sync !== null ? o.sync : {};
-    return {
-        projectId: o.projectId,
-        orgId: 'string' === typeof o.orgId && o.orgId.length > 0 ? o.orgId : undefined,
-        url: o.url,
-        sync: {
-            runs: asBool(sync.runs, DEFAULT_SYNC_POLICY.runs),
-            memory: asBool(sync.memory, DEFAULT_SYNC_POLICY.memory),
-            flows: asBool(sync.flows, DEFAULT_SYNC_POLICY.flows),
-        },
-        verify: o.verify === VerifyMode.SERVER ? VerifyMode.SERVER : VerifyMode.LOCAL,
-    };
-}
-/** Look up the API key for a cloud project id in the user credentials map. */
-/**
- * The API key this machine holds for one project ON ONE CLOUD.
- *
- * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
- * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
- * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
- * whichever was linked last wins. Measured: two repos on one machine, and the production key was
- * being sent to a localhost server, which answered 401.
- *
- * That is the same class of defect as sending a session token to a host that did not issue it, and
- * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
- * at all is better than one belonging to somewhere else.
- *
- * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
- * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
- * refusing it would silently unlink every repo that predates this change, which is a worse outage
- * than the collision. Re-linking upgrades a repo to the safe shape.
- */
-export const credentialSlot = (url, projectId, orgId) => orgId === undefined || 0 === orgId.length
-    ? `${normalizeCloudUrl(url)}::${projectId}`
-    : `${normalizeCloudUrl(url)}::org::${orgId}::${projectId}`;
-function credentialFor(raw, projectId, url, orgId) {
-    if (typeof raw !== 'object' || null === raw)
-        return null;
-    const store = raw;
-    /*
-     * The ORG slot first, because cloud + project is still not an identity.
-     *
-     * `link` names every project "default", so two ACCOUNTS on one cloud both claimed the slot
-     * `<url>::default` and the last link won. Measured on a laptop: a brand-new workspace ran
-     * `reticle login` and was handed a stored key belonging to a different organisation — valid, so
-     * every validation passed, and every run it pushed would have landed in a stranger's dashboard.
-     * Keying by cloud fixed two clouds colliding; only keying by ORG fixes two tenants colliding.
-     */
-    const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
-    if ('string' === typeof orgScoped && orgScoped.length > 0)
-        return orgScoped;
-    /*
-     * Then the cloud+project slot, which is what every repo linked before this change still holds. It
-     * is ambiguous between tenants by construction, which is why it is consulted second and why the
-     * writer above stopped producing it as the only entry.
-     */
-    const composite = store[credentialSlot(url, projectId)];
-    if ('string' === typeof composite && composite.length > 0)
-        return composite;
-    const entry = store[projectId];
-    if ('string' === typeof entry)
-        return entry.length > 0 ? entry : null;
-    if (typeof entry !== 'object' || null === entry)
-        return null;
-    const record = entry;
-    const key = record['key'];
-    const forUrl = record['url'];
-    if ('string' !== typeof key || 0 === key.length)
-        return null;
-    // A credential stamped with a DIFFERENT cloud is not this project's credential, however much the
-    // project ids match. Refuse rather than dial somewhere with somebody else's key.
-    if ('string' === typeof forUrl && normalizeCloudUrl(forUrl) !== normalizeCloudUrl(url))
-        return null;
-    return key;
-}
-/** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
-const normalizeCloudUrl = (url) => url.replace(/\/+$/, '');
-/**
- * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
- * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
- * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
- */
-export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
-    const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE)));
-    if (null === link) {
-        // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
-        return {
-            config: resolveCloudConfig(env),
-            policy: DEFAULT_SYNC_POLICY,
-            verify: VerifyMode.LOCAL,
-            projectId: null,
-        };
-    }
-    const policy = {
-        runs: link.sync.runs ?? DEFAULT_SYNC_POLICY.runs,
-        memory: link.sync.memory ?? DEFAULT_SYNC_POLICY.memory,
-        flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
-    };
-    const key = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
-    const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
-    return { config, policy, verify: link.verify, projectId: link.projectId };
-}

package/dist/cloud/cloud-sync.d.ts

@@ -1,190 +0,0 @@
-/**
- * Optional cloud sync for saved flows. "Logged in" here means the two cloud env vars are set (written by
- * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle
- * dashboard. When present, a freshly-saved flow is pushed to `POST /v1/flows` so the team's regression
- * suite lives in the cloud — surviving refactors and runnable in CI. When absent, sync is a no-op and
- * everything stays 100% local (the "no phone-home" default: nothing leaves the machine unless you opt in).
- *
- * Sync is best-effort: a network failure NEVER fails the local save. The flow is already on disk; the
- * cloud copy is an enhancement, so a push error is logged and swallowed.
- */
-import { z } from 'zod';
-import { type FlowFile, type ReticleVerificationRun, type RunRecord, type VerifyProgressEvent } from '@reticlehq/core';
-/** Env var names — the presence of BOTH is what "logged in" means for cloud sync. */
-export declare const CloudEnv: {
-    readonly URL: "RETICLE_CLOUD_URL";
-    readonly KEY: "RETICLE_CLOUD_KEY";
-};
-export interface CloudConfig {
-    url: string;
-    apiKey: string;
-}
-/** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
-export declare function resolveCloudConfig(env: NodeJS.ProcessEnv): CloudConfig | null;
-export declare const CLOUD_VERIFY_TIMEOUT_MS = 120000;
-/**
- * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
- * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
- * and the agent-facing half of this product is judged on whether its errors are actionable.
- */
-export declare function cloudFetch(url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body?: string;
-}, timeoutMs?: number): Promise<Response>;
-export declare const SyncOutcome: {
-    readonly SYNCED: "synced";
-    readonly SKIPPED: "skipped";
-    readonly FAILED: "failed";
-};
-export type SyncOutcome = (typeof SyncOutcome)[keyof typeof SyncOutcome];
-interface SyncResult {
-    outcome: SyncOutcome;
-    status?: number;
-    error?: string;
-}
-/** A fetch-shaped function, injected so the sync is testable without a real network. */
-export type FetchLike = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-}>;
-/** GET-shaped fetch (no body, reads back JSON), injected so the read is testable without a network. */
-export type FetchGetLike = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    json: () => Promise<unknown>;
-}>;
-/**
- * Push one flow to the cloud. `projectId` scopes it to this app. Returns a structured outcome; never
- * throws — a failure is reported, not propagated, so the local save is authoritative.
- */
-export declare function syncFlowToCloud(flow: FlowFile, config: CloudConfig | null, projectId: string | undefined, fetchImpl: FetchLike): Promise<SyncResult>;
-/**
- * Push one verification-run artifact to the cloud. This is what makes "runs recorded on the dashboard"
- * real once a user shifts to the server: after `reticle verify` produces a run, it lands in the team's
- * hosted history with its verdict. Same opt-in creds as flow sync — absent → no-op (stays local). The
- * cloud's `POST /v1/runs` ingests the RAW artifact (validated by the same `@reticlehq/core` schema that
- * built it), so the body is the run itself, not a wrapper. Best-effort: never throws, never blocks exit.
- */
-export declare function syncRunToCloud(run: ReticleVerificationRun, config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
-/**
- * Push one project-memory RunRecord (a flow replay/verify outcome) to the cloud so the team's server-side
- * regression history stays current: "did this development break a previously-passing flow?" is answered
- * from these. Same opt-in creds as the others — absent → no-op (project.json stays the local source of
- * truth). `projectId` scopes an org's multiple suites. Best-effort: never throws, never blocks the tool.
- */
-export declare function syncRunRecordToCloud(record: RunRecord, projectId: string | undefined, config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
-/**
- * Read the team's server-side regression report back down to the agent. This is the half that makes the
- * system "agent-friendly across context loss": a fresh agent (new session, CI box, teammate's machine)
- * whose local .reticle/project.json is empty can still ask the ONE tool it knows — reticle_project — and
- * get the durable cloud memory of what's broken vs before. Returns the raw report (shape owned by the
- * cloud), or null when not logged in / unreachable — so the caller degrades to local-only, never fails.
- */
-export declare function fetchProjectRegressionFromCloud(config: CloudConfig | null, projectId: string | undefined, fetchImpl: FetchGetLike): Promise<unknown>;
-/** POST-that-reads-JSON fetch shape (injected so the server-verify submit is testable without a network). */
-export type FetchPostJsonLike = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    json: () => Promise<unknown>;
-}>;
-/** The hosted runner's report, validated at the boundary (the full shape is owned by the cloud app). */
-declare const ServerVerificationSchema: z.ZodObject<{
-    verificationId: z.ZodString;
-    verdict: z.ZodNullable<z.ZodString>;
-    flows: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        status: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        status: string;
-        name: string;
-    }, {
-        status: string;
-        name: string;
-    }>, "many">;
-    summary: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    verificationId: string;
-    verdict: string | null;
-    flows: {
-        status: string;
-        name: string;
-    }[];
-    summary: string;
-}, {
-    verificationId: string;
-    verdict: string | null;
-    flows: {
-        status: string;
-        name: string;
-    }[];
-    summary: string;
-}>;
-export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
-/**
- * Delegate a verification to the hosted runner: submit the preview URL + flow names to `POST
- * /v1/verifications` and read back the report. This is the `verify: 'server'` half of the per-project
- * config — the WORK runs on the server (real browser pool, later), not the local machine. The server
- * records the verification itself, so there is no separate run-push. Returns null when not attached or the
- * submit fails, so the caller falls back to a local replay. Never throws.
- */
-export declare function submitServerVerification(body: {
-    previewUrl: string;
-    flows: string[];
-    source: string;
-}, config: CloudConfig | null, fetchImpl: FetchPostJsonLike): Promise<ServerVerification | null>;
-/**
- * Narrate a run in flight to the dashboard.
- *
- * ## Why this exists
- *
- * Everything else here syncs a FINISHED artifact. That is the right shape for evidence and the wrong
- * shape for the minutes a verification is actually running: a browser launches, flows replay one at
- * a time, and until the run ends the dashboard has nothing to show but a spinner. A run that is
- * working and a run that has died are indistinguishable for the whole of its duration, and somebody
- * watching sat on exactly that ambiguity for fifteen minutes.
- *
- * ## Why it is batched
- *
- * One request per flow is one request per flow. A fifty-flow suite would open a hundred connections
- * to say things that are only interesting in aggregate, so events accumulate and go out on a timer.
- * Two seconds is well under the time a person waits before deciding a page is broken, and well over
- * the time a fast flow takes — so a burst of quick replays becomes one request, not twenty.
- *
- * ## Why it can never matter
- *
- * Opt-in like every other cloud call (no credentials → no-op, nothing leaves the machine), and
- * best-effort at every layer: a failed flush is dropped, never retried and never surfaced. This is
- * narration. The run artifact is the record, it syncs separately, and nothing here is graded or
- * allowed to influence a verdict or an exit code.
- */
-export declare function syncProgressToCloud(runId: string, events: readonly VerifyProgressEvent[], config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
-/** How long events accumulate before a flush. See the batching note above. */
-export declare const PROGRESS_FLUSH_MS = 2000;
-/**
- * A listener that buffers progress and ships it on a timer.
- *
- * Returned with its own `flush` and `stop` so the caller can push the last events out when the run
- * ends — otherwise the most interesting event of all, the one saying it finished, waits for a timer
- * that is about to be cleared.
- *
- * The timer is `unref`'d where the runtime supports it: a narration timer must never be the reason a
- * CLI process stays alive after its work is done.
- */
-export declare function createProgressReporter(runId: string, config: CloudConfig | null, fetchImpl: FetchLike, flushMs?: number): {
-    onProgress: (event: VerifyProgressEvent) => void;
-    flush: () => Promise<void>;
-    stop: () => void;
-};
-export {};