@reticlehq/server 2.2.1 → 2.3.0

package/dist/telemetry/telemetry.js

@@ -19,7 +19,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION } from '@reticlehq/core';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
@@ -53,6 +53,8 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
     `body:process.argv[2],signal:AbortSignal.timeout(${SEND_TIMEOUT_MS})})` +
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
+import { isReticleSourceCheckout } from './dev-repo.js';
+import { gitFacts } from './git-facts.js';
 const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
@@ -61,12 +63,17 @@ const Env = {
     CI: 'CI', // presence marks a CI environment
     VITEST: 'VITEST', // set by vitest — unit tests must never phone home
 };
-const isDisabled = (env) => {
+const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
     if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
         return true;
     if (env[Env.VITEST] !== undefined)
         return true; // a test run is not a user
+    // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
+    // so it only exists on the machine that made it — a fresh clone would phone home on a
+    // contributor's first `reticle serve`. The repo marker is committed, so this guarantee travels.
+    if (isReticleSourceCheckout(cwd))
+        return true;
     const dnt = env[Env.DO_NOT_TRACK];
     return typeof dnt === 'string' && dnt !== '' && dnt !== '0';
 };
@@ -88,8 +95,31 @@ const resolveIdentity = () => {
         return { anonymousId: randomUUID(), firstRun: false };
     }
 };
-/** One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing. */
-const projectFingerprint = (cwd) => createHash('sha256').update(cwd).digest('hex').slice(0, 32);
+/**
+ * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
+ *
+ * Prefers a hash of the git ORIGIN over a hash of the cwd. The contract in `@reticlehq/core` always
+ * said "one-way hash of the git remote (or cwd)", but the implementation only ever hashed the path —
+ * which meant the same repo cloned by four teammates, or checked out twice on one machine, counted as
+ * four separate projects. That inflates the project count and, worse, makes team adoption look like
+ * unrelated individuals. Hashing the origin dedupes a real project down to one id across every clone.
+ *
+ * Still one-way, still non-reversible, and still exactly what the published policy describes: the
+ * remote URL itself never leaves the machine, only its SHA-256. The URL is normalized first (scheme,
+ * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
+ * `https://github.com/Acme/web` are recognized as the same project rather than two.
+ */
+const projectFingerprint = (cwd) => {
+    const { origin } = gitFacts(cwd);
+    return {
+        projectId: createHash('sha256')
+            .update(origin ?? cwd)
+            .digest('hex')
+            .slice(0, 32),
+        // Reported alongside so the analytics knows whether this id is comparable to another machine's.
+        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+    };
+};
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {
@@ -106,8 +136,17 @@ const showNoticeOnce = () => {
     }
 };
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
-export const describeTelemetry = (env = process.env, dir = RETICLE_DIR) => {
-    if (isDisabled(env)) {
+export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = process.cwd()) => {
+    // Report the reason that ACTUALLY applies. Saying "environment variable" when the real cause is
+    // the source-checkout guard would send a contributor hunting for a variable that is not set.
+    if (isReticleSourceCheckout(cwd)) {
+        return {
+            enabled: false,
+            reason: 'this is a Reticle source checkout — developing it is not using it',
+            policyUrl: POLICY_URL,
+        };
+    }
+    if (isDisabled(env, cwd)) {
         return { enabled: false, reason: 'disabled by environment variable', policyUrl: POLICY_URL };
     }
     if (existsSync(join(dir, 'telemetry-opt-out'))) {
@@ -142,7 +181,8 @@ const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
  */
 export const createTelemetry = (opts) => {
     const env = opts.env ?? process.env;
-    if (isDisabled(env))
+    const cwd = opts.cwd ?? process.cwd();
+    if (isDisabled(env, cwd))
         return NOOP;
     try {
         if (existsSync(OPT_OUT_FILE))
@@ -160,7 +200,13 @@ export const createTelemetry = (opts) => {
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
     const os = platform();
     const { anonymousId, firstRun } = resolveIdentity();
-    const projectId = projectFingerprint(opts.cwd ?? process.cwd());
+    /**
+     * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
+     * IS the session, and a restarted daemon is genuinely a new one. Ephemeral by construction, so it
+     * adds no durable identifier to the machine.
+     */
+    const sessionId = randomUUID();
+    const { projectId, source: projectIdSource } = projectFingerprint(opts.cwd ?? process.cwd());
     showNoticeOnce();
     const spawnDetached = opts.spawnImpl ??
         ((command, args) => {
@@ -170,17 +216,65 @@ export const createTelemetry = (opts) => {
         const event = {
             v: TELEMETRY_EVENT_VERSION,
             anonymousId,
+            sessionId,
             projectId,
             event: kind,
             ts: now(),
             version: opts.version,
             ci,
             os,
-            ...(extra?.sessionMs !== undefined ? { sessionMs: extra.sessionMs } : {}),
-            ...(extra?.tool !== undefined ? { tool: extra.tool } : {}),
+            projectIdSource,
+            ...(extra?.actor !== undefined ? { actor: extra.actor } : {}),
+            ...(extra?.command !== undefined ? { command: extra.command } : {}),
+            ...(extra?.flags !== undefined ? { flags: extra.flags } : {}),
+            ...(extra?.session !== undefined ? { session: extra.session } : {}),
+            ...(extra?.project !== undefined ? { project: extra.project } : {}),
+            ...(extra?.verification !== undefined ? { verification: extra.verification } : {}),
+            ...(extra?.versionChange !== undefined ? { versionChange: extra.versionChange } : {}),
+            ...(extra?.crash !== undefined ? { crash: extra.crash } : {}),
+            ...(extra?.feedback !== undefined ? { feedback: extra.feedback } : {}),
+            ...(extra?.identity !== undefined ? { identity: extra.identity } : {}),
+            ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
+            ...(extra?.init !== undefined ? { init: extra.init } : {}),
+            ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
-        const { anonymousId: distinctId, event: name, ts, ...properties } = event;
+        // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
+        // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
+        // would be invisible to the exact "which stacks report the most bugs" question this exists to
+        // answer. One prefix keeps them grouped in the UI without a nested path.
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, ...rest } = event;
+        // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
+        // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
+        const properties = {
+            ...rest,
+            sessionId: eventSessionId,
+            $session_id: eventSessionId,
+        };
+        // Each block is flattened under its own prefix rather than nested. PostHog filters, breakdowns and
+        // insight builders all operate on TOP-LEVEL properties, so a nested `project.stack` is invisible to
+        // the exact "which stacks retain best" question these exist to answer — you would have to drop to
+        // raw HogQL for every chart. One prefix per block keeps them grouped in the property list without
+        // paying that cost. The two genuine maps (`toolCounts`, `errorKinds`) stay objects: their keys are
+        // open-ended, so flattening them would mint an unbounded number of property names, which is the one
+        // thing that actually degrades a PostHog project.
+        const blocks = {
+            feedback,
+            session,
+            project,
+            verification,
+            version: versionChange,
+            crash,
+            identity,
+            connection,
+            init,
+            bug,
+        };
+        for (const [prefix, block] of Object.entries(blocks)) {
+            for (const [key, value] of Object.entries(block ?? {})) {
+                properties[`${prefix}_${key}`] = value;
+            }
+        }
         const body = JSON.stringify({
             api_key: apiKey,
             batch: [
@@ -217,4 +311,3 @@ export const createTelemetry = (opts) => {
 let singleton;
 export const getTelemetry = () => (singleton ??= createTelemetry({ version: SERVER_VERSION }));
 export { TelemetryEventKind };
-//# sourceMappingURL=telemetry.js.map

package/dist/token-auth.d.ts

@@ -21,4 +21,3 @@ export declare function isLoopbackHost(hostHeader: string | undefined): boolean;
  * non-loopback value fails, which is what kills a rebound `http://evil.com` page reading the plane.
  */
 export declare function isLocalWebOrigin(origin: string | undefined, referer: string | undefined): boolean;
-//# sourceMappingURL=token-auth.d.ts.map

package/dist/token-auth.js

@@ -68,4 +68,3 @@ export function isLocalWebOrigin(origin, referer) {
     }
     return true;
 }
-//# sourceMappingURL=token-auth.js.map

package/dist/tools/act-capsule.d.ts

@@ -0,0 +1,23 @@
+import type { ExpectedLink } from '../capsule/divergence.js';
+import type { DivergenceCapsule } from '../capsule/capsule.js';
+import type { ToolDeps } from './tool-kit.js';
+interface CapsuleSaveInputs {
+    deps: ToolDeps;
+    verdict: {
+        pass: boolean;
+        failureReason?: string;
+    };
+    capsule?: DivergenceCapsule | undefined;
+    links: readonly ExpectedLink[];
+    args: Record<string, unknown>;
+    actResult: {
+        result?: unknown;
+    };
+    actedSource?: {
+        file: string;
+        line: number;
+    };
+}
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;
+export {};

package/dist/tools/act-capsule.js

@@ -0,0 +1,47 @@
+/**
+ * Persist a failed assertion as a replayable fail-to-pass capsule.
+ *
+ * : a red assertion is the ONE moment the evidence explaining it is in hand. Persist it as a
+        // replayable fail-to-pass capsule so the bug survives the turn — and becomes a regression flow
+        // the moment it goes green. Best-effort: capturing evidence must never fail the run that found it.
+ *
+ * Split out of act-tools.ts when it crossed the 600-line cap. The seam is real: this is the only
+ * part of the act path that writes to disk, and it is best-effort by design — capturing evidence
+ * must never fail the run that found it.
+ */
+import { ActionType, AnchorKind } from '@reticlehq/core';
+import { CapsuleStore, capsuleId } from '../capsule/capsule-store.js';
+import { ReticleTool } from './tool-names.js';
+import { asRecord, asString } from './tools-helpers.js';
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export async function saveFailedAssertCapsule(inputs) {
+    const { deps, verdict, capsule, links, args, actResult, actedSource } = inputs;
+    if (verdict.pass || capsule === undefined)
+        return undefined;
+    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
+    const expectedText = links
+        .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
+        .join(' AND ');
+    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
+        version: 1,
+        id,
+        createdAt: deps.now(),
+        origin: 'failed-assert',
+        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
+        observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
+        steps: [
+            {
+                tool: ReticleTool.ACT,
+                anchor: {
+                    kind: AnchorKind.TESTID,
+                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
+                    // Carried so the saved capsule — which outlives this turn and becomes a regression flow
+                    // when it goes green — still knows which file the failure came from.
+                    ...(actedSource === undefined ? {} : { source: actedSource }),
+                },
+                action: (asString(args['action']) ?? ActionType.CLICK),
+            },
+        ],
+    });
+    return saved ? id : undefined;
+}

package/dist/tools/act-danger.d.ts

@@ -0,0 +1,7 @@
+import { ActionType } from '@reticlehq/core';
+export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so.
+ */
+export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;

package/dist/tools/act-danger.js

@@ -0,0 +1,44 @@
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, isDangerousActionText } from '@reticlehq/core';
+import { asRecord, asString } from './tools-helpers.js';
+/**
+ * Refuse to drive a money-moving or destructive control by accident.
+ *
+ * A native click is indistinguishable from a user's, so an agent exploring an unfamiliar app can
+ * refund a payment or delete an account while "just looking". The guard reads every text surface the
+ * control exposes — its name, its text, its value, where it points, and the form it submits — because
+ * a button labelled only with an icon still says what it does through its `formAction`.
+ *
+ * Opt in per action with `args.confirmDangerous: true`. Deliberately a THROW rather than a warning:
+ * a caller that has not thought about it must not proceed by ignoring a field.
+ */
+function descriptorText(value) {
+    const descriptor = asRecord(value);
+    return [
+        asString(descriptor['name']) ?? '',
+        asString(descriptor['text']) ?? '',
+        asString(descriptor['value']) ?? '',
+        asString(descriptor['href']) ?? '',
+        asString(descriptor['formAction']) ?? '',
+        asString(descriptor['formText']) ?? '',
+    ].join(' ');
+}
+export function assertNotDestructive(action, innerArgs, inspected) {
+    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
+        return;
+    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+        return;
+    if (!isDangerousActionText(descriptorText(inspected)))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so.
+ */
+export function assertDragNotDestructive(innerArgs, from, to) {
+    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+        return;
+    if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}

package/dist/tools/act-helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType } from '@reticlehq/core';
+import type { ElementBox } from '../input/real-input.js';
+import { HonestyGrade } from '../honesty/honesty.js';
+import type { ExpectedLink } from '../capsule/divergence.js';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export declare function gradeOf(links: readonly ExpectedLink[]): HonestyGrade;
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export declare function asBox(value: unknown): ElementBox | undefined;
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export declare function asActionType(value: unknown): ActionType | undefined;

package/dist/tools/act-helpers.js

@@ -0,0 +1,40 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType } from '@reticlehq/core';
+import { HonestyGrade } from '../honesty/honesty.js';
+import { asNumber, asRecord, asString } from './tools-helpers.js';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export function gradeOf(links) {
+    if (links.some((l) => l.kind === 'signal'))
+        return HonestyGrade.SIGNAL;
+    if (links.some((l) => l.kind === 'net'))
+        return HonestyGrade.NET;
+    if (links.some((l) => l.kind === 'state'))
+        return HonestyGrade.STATE;
+    return HonestyGrade.PRESENCE;
+}
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export function asBox(value) {
+    const b = asRecord(asRecord(value)['box']);
+    const x = asNumber(b['x']);
+    const y = asNumber(b['y']);
+    const w = asNumber(b['width']);
+    const h = asNumber(b['height']);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    if (w <= 0 || h <= 0)
+        return undefined; // zero-area (display:none) ⇒ native click would miss
+    return { x, y, width: w, height: h };
+}
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export function asActionType(value) {
+    const raw = asString(value);
+    if (raw === undefined)
+        return undefined;
+    return Object.values(ActionType).includes(raw) ? raw : undefined;
+}

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

@@ -1,3 +1,10 @@
 import { type ToolDef } from './tool-kit.js';
+/**
+ * Narrow the wire's `action` to a real ActionType, or undefined.
+ *
+ * It used to be `asString(args['action']) ?? ''`, so an unknown or missing action became the empty
+ * string and travelled on — reaching the browser as a command it could not perform, and reported back
+ * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
+ * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
+ */
 export declare const ACT_TOOLS: ToolDef[];
-//# sourceMappingURL=act-tools.d.ts.map