@reticlehq/server 2.14.0 → 3.2.0

package/dist/cloud/sync-disk.js

@@ -1,191 +0,0 @@
-/**
- * The filesystem half of a sync cycle: what `.reticle/` looks like to the protocol.
- *
- * Kept apart from `sync-cycle.ts` on purpose. The cycle is the interesting part — what to send, what
- * to skip, what to do when the network is down — and it stays provable only because it never touches
- * a disk. This is the boring part, and boring is what it should be: read a file, tolerate its
- * absence, never throw.
- *
- * EVERY READ IS FORGIVING. A half-written impact.json from a process that died mid-flush must cost
- * one unsynced record, not a crashed sync. There is no state here worth defending against a parse
- * error — the file will be rewritten on the next tool call anyway.
- */
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
-import { subjectFor } from '../intent/intent-subject.js';
-const JSON_SUFFIX = '.json';
-/** Read + parse, or undefined for absent/unreadable/malformed. Never throws. */
-function readJson(path) {
-    try {
-        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Write atomically. tmp + rename, because two daemons can serve one repo at once and a half-written
- * cursor file is one the next read discards — which would silently re-pull the whole decision
- * history, or worse, skip it.
- */
-function writeJson(path, value) {
-    try {
-        mkdirSync(dirname(path), { recursive: true });
-        const tmp = `${path}.${String(process.pid)}.tmp`;
-        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-        renameSync(tmp, path);
-    }
-    catch {
-        // Bookkeeping that cannot be written must never break a sync. The next cycle re-derives it; the
-        // worst case is one redundant upload, which the server dedupes anyway.
-    }
-}
-/** Every `*.json` directly inside a directory, parsed. Absent directory reads as empty. */
-function readJsonDir(dir) {
-    try {
-        if (!existsSync(dir))
-            return [];
-        return readdirSync(dir)
-            .filter((f) => f.endsWith(JSON_SUFFIX))
-            .map((f) => readJson(join(dir, f)))
-            .filter((v) => v !== undefined);
-    }
-    catch {
-        return [];
-    }
-}
-/** Flows live one directory deeper, under the app's own project id. */
-function readFlows(root) {
-    const dir = join(root, ReticleDir.FLOWS_SUBDIR);
-    try {
-        if (!existsSync(dir))
-            return [];
-        return readdirSync(dir).flatMap((scope) => readJsonDir(join(dir, scope)));
-    }
-    catch {
-        return [];
-    }
-}
-const DERIVED_FILE = {
-    impact: ReticleDir.IMPACT_FILE,
-    flake: ReticleDir.FLAKE_FILE,
-    intent: ReticleDir.INTENT_FILE,
-};
-/** The directory the sharded intent store writes into, beside the legacy flat file. */
-const INTENT_SUBDIR = 'intent';
-const INTENT_INDEX = 'index.json';
-/**
- * Every intent this project holds, flat file and shards merged.
- *
- * The store was split into one file per subject so that writing one record stops rewriting all of
- * them. Sync was not told, and kept reading `intent.json` alone — which the migration deliberately
- * does not delete. The result was the worst shape a sync bug can take: not an error, but a corpus
- * that looked healthy on the dashboard and had silently stopped moving, because every intent
- * captured after the migration stayed on the engineer's laptop.
- *
- * Shards WIN on a collision, matching the store's own rule: an id present in both has been migrated
- * and possibly edited since, and letting the flat copy overwrite that would revert the edit on every
- * cycle. `index.json` is derived from the shards and is skipped — sending it would duplicate every
- * record as a summary of itself.
- *
- * Returns undefined when there is no memory at all, so a project with nothing to say sends nothing
- * rather than an empty envelope the server has to store.
- */
-function readIntent(reticleRoot) {
-    const legacy = readJson(join(reticleRoot, ReticleDir.INTENT_FILE));
-    const merged = {
-        ...(legacy?.intents ?? {}),
-    };
-    let shards = 0;
-    for (const file of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
-        if (!file.endsWith(JSON_SUFFIX) || INTENT_INDEX === file)
-            continue;
-        const shard = readJson(join(reticleRoot, INTENT_SUBDIR, file));
-        // A hand-edited or half-written shard costs one subject, never the whole sync.
-        if (shard?.intents === undefined)
-            continue;
-        shards++;
-        for (const [id, record] of Object.entries(shard.intents))
-            merged[id] = record;
-    }
-    if (legacy === undefined && 0 === shards)
-        return undefined;
-    /*
-     * Stamp the SUBJECT before sending, on anything that does not already carry one.
-     *
-     * The subject ladder lives here, in the engine, and knows how to read a flow, a route and a
-     * binding predicate. The server had no access to it and had reimplemented a far weaker version —
-     * flow-or-nothing — so records this ladder files correctly arrived at the dashboard as
-     * `unsorted`. Measured on the real corpus: 105 of 163 records the engine can place were landing
-     * in the bucket of last resort, which is what made a coverage map read as one pile with six
-     * labels.
-     *
-     * Computed HERE rather than duplicated there, because two rules for one question is how the
-     * answers start disagreeing — and the one with the evidence should be the one that decides.
-     * Records that already name a subject keep it: an agent's explicit choice outranks inference.
-     */
-    const placed = Object.fromEntries(Object.entries(merged).map(([id, record]) => {
-        const held = record;
-        if ('string' === typeof held.subject && held.subject.length > 0)
-            return [id, record];
-        const subject = subjectFor({
-            surface: held.surface,
-            binding: held.binding,
-        });
-        return [id, { ...held, subject }];
-    }));
-    return { version: 1, intents: placed };
-}
-/** Directory listing that tolerates absence — an unmigrated project has no `intent/`. */
-function safeReaddir(dir) {
-    try {
-        return readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-}
-/** What the cycle reads, backed by a real `.reticle` directory. */
-export function diskSource(reticleRoot) {
-    return {
-        runs: () => readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
-            .map((payload) => {
-            const id = payload?.runId;
-            return 'string' === typeof id ? { runId: id, payload } : undefined;
-        })
-            // A run artifact with no id cannot be diffed against the server's list, so sending it would
-            // mean re-sending it every cycle forever. Dropped rather than uploaded repeatedly.
-            .filter((r) => r !== undefined),
-        flows: () => readFlows(reticleRoot),
-        // Intent is the only derived record that is no longer one file. See readIntent.
-        derived: (kind) => 'intent' === kind ? readIntent(reticleRoot) : readJson(join(reticleRoot, DERIVED_FILE[kind])),
-    };
-}
-/** What the cycle writes back into `.reticle/`. */
-export function diskSink(reticleRoot) {
-    return {
-        writeIssues: (issues) => {
-            // MERGED, not replaced. A pull returns only what changed since the cursor, so overwriting
-            // would drop every earlier decision the moment one new decision arrived.
-            const held = readCloudIssues(reticleRoot);
-            writeJson(join(reticleRoot, ReticleDir.ISSUES_FILE), {
-                triage: { ...held.triage, ...issues.triage },
-            });
-        },
-        writeState: (state) => {
-            writeJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE), state);
-        },
-    };
-}
-/** This machine's side of the conversation, or a blank one on first run. */
-export function readCloudState(reticleRoot) {
-    const raw = readJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE));
-    return 'object' === typeof raw && null !== raw ? raw : {};
-}
-/** The decisions pulled back from the dashboard, for the HUD and for the next run to read. */
-export function readCloudIssues(reticleRoot) {
-    const raw = readJson(join(reticleRoot, ReticleDir.ISSUES_FILE));
-    const triage = 'object' === typeof raw && null !== raw ? raw.triage : undefined;
-    return { triage: 'object' === typeof triage && null !== triage ? triage : {} };
-}

package/dist/crawl/crawl-tools.d.ts

@@ -1,7 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
- * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
- * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
- */
-export declare const CRAWL_TOOLS: ToolDef[];

package/dist/crawl/crawl-tools.js

@@ -1,87 +0,0 @@
-import { z } from 'zod';
-import { ReticleTool } from '../tools/tool-names.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { stepCountSchema, timeoutMsSchema } from '../tools/numeric-bounds.js';
-import { crawl } from './crawl.js';
-import { routeFromUrl, routesFromEvents } from '../project/learned-routes.js';
-const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/**
- * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
- * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
- * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
- */
-export const CRAWL_TOOLS = [
-    {
-        name: ReticleTool.CRAWL,
-        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
-        inputSchema: {
-            maxSteps: stepCountSchema
-                .optional()
-                .describe('Maximum number of controls to click. Default: 25.'),
-            settleMs: timeoutMsSchema
-                .optional()
-                .describe('Milliseconds to wait after each click for the app to react. Default: 500.'),
-            scope: z
-                .string()
-                .optional()
-                .describe('CSS selector or element ref to restrict crawling to a subtree.'),
-            confirmDangerous: z
-                .boolean()
-                .optional()
-                .describe('Set true to allow controls classified as destructive. Default false; those controls are blocked by the browser.'),
-            sessionId: z
-                .string()
-                .optional()
-                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
-        },
-        // An UNDECLARED field is stripped from structuredContent, so a schema-aware client never sees it
-        // even though the handler returns it. Everything crawl produces has to be listed here or it is
-        // silently lost — which is how the source pointer and the visited list were being dropped.
-        outputSchema: {
-            interactiveFound: z.number(),
-            stepsRun: z.number(),
-            // Present only when nothing was clicked, saying WHICH zero this is — an empty page, a step
-            // budget of zero, or controls found and none driven. A bare zero was unactionable.
-            note: z.string().optional(),
-            anomalies: z.array(z.object({
-                kind: z.string(),
-                ref: z.string(),
-                desc: z.string(),
-                detail: z.string().optional(),
-                source: z
-                    .string()
-                    .optional()
-                    .describe('Where the fault is written, as `file:line`; console errors prefer their own stack and fall back to the clicked control.'),
-            })),
-            counts: z.record(z.number()),
-            visited: z.array(z.string()).describe('The controls actually clicked, in order.'),
-            coverageNote: z
-                .string()
-                .optional()
-                .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
-            truncated: z.boolean(),
-        },
-        handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const since = session.elapsed();
-            const initialRoute = routeFromUrl(session.url);
-            const maxSteps = asNumber(args['maxSteps']);
-            const settleMs = asNumber(args['settleMs']);
-            const scope = asString(args['scope']);
-            const opts = {
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-                ...(settleMs !== undefined ? { settleMs } : {}),
-                ...(scope !== undefined ? { scope } : {}),
-                ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
-            };
-            const report = await crawl(session, opts, nodeSleep);
-            const routes = [
-                ...(initialRoute === undefined ? [] : [initialRoute]),
-                ...routesFromEvents(session.eventsSince(since)),
-            ];
-            if (routes.length > 0)
-                await deps.project.recordRoutes(routes);
-            return report;
-        },
-    },
-];

package/dist/crawl/crawl.d.ts

@@ -1,98 +0,0 @@
-import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
-/** The slice of Session the crawler needs — so tests inject a fake without a live browser. */
-export interface CrawlSession {
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-    elapsed(): number;
-    eventsSince(cursor: number): ReticleEvent[];
-    /**
-     * Which document is on screen now, so a finding is never drawn from a page the crawl has already
-     * navigated away from. Optional for the same reason `beginAction` is: a test fake supplies a
-     * minimal session, and its absence leaves the scoping inert rather than broken.
-     */
-    readonly currentDocumentId?: string | undefined;
-    /** Which round of source edits is in force, so a finding drawn entirely from pre-edit evidence
-     *  says so. Optional for the same reason `currentDocumentId` is. */
-    readonly currentEditEpoch?: number | undefined;
-    /** The page under test, so a third-party beacon cannot be reported against a control. Optional
-     *  for the same reason `currentDocumentId` is. */
-    readonly url?: string | undefined;
-    /**
-     * Attribution window around each click. Optional so a caller can supply a minimal session, but a real
-     * session MUST provide it: without a window the click's own effects carry no actionId, and an
-     * unattributed ref-bearing event is learned as ambient background churn. A crawl clicks up to 25
-     * controls, so it can single-handedly teach the settle oracle to ignore the regions the app actually
-     * reacts in — turning a later `{kind:"settled"}` into a false green.
-     */
-    beginAction?(tool: string, args: Record<string, unknown>): void;
-    finishAction?(error?: string, settled?: boolean, settleMs?: number): void;
-}
-type CrawlSleep = (ms: number) => Promise<void>;
-export interface CrawlAnomaly {
-    /**
-     * A single-channel fault (something bad in one stream) or a CONTRADICTION (two channels
-     * disagreeing about the same click). The second kind is why an autonomous crawl is worth more
-     * than a human clicking the same buttons: a person sees only the screen, so a UI that advanced
-     * while its write failed looks like success to them and always will.
-     *
-     * `CrawlAnomalyKind` and `ContradictionKind` are what THIS package puts here, and both are still
-     * enforced at the emit sites below. The type is a plain string because a rule registered by a
-     * consumer contributes kinds this package has never heard of, and a closed union here would mean
-     * a consumer's private vocabulary had to ship in the free product to be reportable.
-     */
-    kind: string;
-    /** The control that triggered it. */
-    ref: string;
-    desc: string;
-    detail: string;
-    /**
-     * Where the fault is written, as `file:line`.
-     *
-     * Console faults prefer their own component/error stack. The clicked control stays in `ref` and
-     * `desc`, and its source is only the fallback: a navigation link explains what exposed a render
-     * crash, while the crashing component explains what to fix. Other anomaly kinds still use the
-     * control source captured alongside the action. Absent when neither source can be localized.
-     */
-    source?: string;
-}
-/** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
-export declare const CAPPED_SNAPSHOT_NOTE = "the page exceeded one snapshot, so controls past the cap were never seen \u2014 interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest";
-export interface CrawlReport {
-    interactiveFound: number;
-    stepsRun: number;
-    anomalies: CrawlAnomaly[];
-    counts: {
-        consoleErrors: number;
-        failedRequests: number;
-        deadControls: number;
-        contradictions: number;
-    };
-    /** Descriptions of the controls actually clicked. */
-    visited: string[];
-    /** True when coverage was bounded — by the step budget, or by the page exceeding one snapshot. */
-    truncated: boolean;
-    /** Present only when the snapshot itself was capped, i.e. controls exist that were never listed. */
-    coverageNote?: string;
-}
-export interface CrawlOptions {
-    maxSteps?: number;
-    settleMs?: number;
-    scope?: string;
-    confirmDangerous?: boolean;
-}
-/**
- * The autonomous "smart monkey". Discovers every reachable interactive control once,
- * then clicks each (bounded by maxSteps) and classifies the reaction into anomalies — console
- * errors, failed requests, and DEAD controls (dispatched but the app did nothing). Pure
- * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
- * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
- */
-/**
- * Controls whose correct behaviour IS to do nothing when clicked.
- *
- * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
- * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
- * focuses it rather than changing anything.
- */
-export declare function legitimatelyInert(desc: string): boolean;
-export declare function crawl(session: CrawlSession, opts: CrawlOptions, sleep: CrawlSleep): Promise<CrawlReport>;
-export {};