@exla/rudder 0.0.0-stage → 3.4.0

package/assets/sounds/NOTICE.md

@@ -0,0 +1,8 @@
+`ping.mp3` is copied from:
+
+https://github.com/superset-sh/superset/tree/main/apps/desktop/src/resources/sounds
+
+Superset is distributed under the Elastic License 2.0. The relevant license text
+is available at:
+
+https://github.com/superset-sh/superset/blob/main/LICENSE.md

package/dist/agent-attention.d.ts

@@ -0,0 +1,5 @@
+export type AgentAttention = {
+    needsPermission: boolean;
+    summary?: string;
+};
+export declare function permissionAttentionFromOutput(output: string): AgentAttention;

package/dist/agent-attention.js

@@ -0,0 +1,54 @@
+const PERMISSION_WORD = /\b(permission|approval|approve|allow|authorize|authorization|confirmation|proceed|deny)\b/i;
+const PERMISSION_PATTERNS = [
+    /\b(do you want|would you like|are you sure)\b[\s\S]{0,180}\b(allow|approve|run|execute|continue|proceed)\b/i,
+    /\b(allow|approve|authorize)\b[\s\S]{0,120}\b(command|tool|edit|write|file|access|execution|network|shell|operation)\b/i,
+    /\b(permission|approval|authorization|confirmation)\b[\s\S]{0,160}\b(required|need(?:ed)?|request(?:ed|ing)?|waiting|prompt)\b[\s\S]{0,160}\b(approve|allow|deny|yes|no|enter|return|press)\b/i,
+    /\b(approve|allow|deny|yes|no|enter|return|press)\b[\s\S]{0,160}\b(permission|approval|authorization|confirmation)\b/i,
+    /\bpress\b[\s\S]{0,80}\b(y|yes|enter|return)\b[\s\S]{0,120}\b(allow|approve|continue|proceed)\b/i,
+    /\b(yes|no)\b[\s\S]{0,100}\b(approve|deny|allow|permission)\b/i,
+];
+export function permissionAttentionFromOutput(output) {
+    const recentLines = recentTerminalLines(output, 60);
+    const recentText = recentLines.join("\n");
+    if (!PERMISSION_WORD.test(recentText)) {
+        return { needsPermission: false };
+    }
+    if (!PERMISSION_PATTERNS.some((pattern) => pattern.test(recentText))) {
+        return { needsPermission: false };
+    }
+    return {
+        needsPermission: true,
+        summary: summarizePermissionPrompt(recentLines),
+    };
+}
+function summarizePermissionPrompt(lines) {
+    const line = [...lines]
+        .reverse()
+        .find((candidate) => PERMISSION_WORD.test(candidate));
+    if (!line) {
+        return undefined;
+    }
+    return truncate(line.replace(/\s+/g, " ").trim(), 120);
+}
+function recentTerminalLines(output, maxLines) {
+    return stripTerminalControls(output)
+        .replace(/\r/g, "\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-maxLines);
+}
+function stripTerminalControls(value) {
+    return value
+        .replace(/\x1b\][^\u0007]*(?:\u0007|\x1b\\)/g, "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b[()][A-Za-z0-9]/g, "")
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+}
+function truncate(value, width) {
+    if (value.length <= width) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, width - 3))}...`;
+}
+//# sourceMappingURL=agent-attention.js.map

package/dist/agent-attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-attention.js","sourceRoot":"","sources":["../src/agent-attention.ts"],"names":[],"mappings":"AAKA,MAAM,eAAe,GAAG,4FAA4F,CAAC;AACrH,MAAM,mBAAmB,GAAG;IAC1B,6GAA6G;IAC7G,wHAAwH;IACxH,+LAA+L;IAC/L,sHAAsH;IACtH,iGAAiG;IACjG,+DAA+D;CAChE,CAAC;AAEF,MAAM,UAAU,6BAA6B,CAAC,MAAc;IAC1D,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;IACpC,CAAC;IACD,OAAO;QACL,eAAe,EAAE,IAAI;QACrB,OAAO,EAAE,yBAAyB,CAAC,WAAW,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAe;IAChD,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC;SACpB,OAAO,EAAE;SACT,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAc,EAAE,QAAgB;IAC3D,OAAO,qBAAqB,CAAC,MAAM,CAAC;SACjC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;SACpB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,OAAO,KAAK;SACT,OAAO,CAAC,oCAAoC,EAAE,EAAE,CAAC;SACjD,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC;SACvC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC;SACnC,OAAO,CAAC,iDAAiD,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa,EAAE,KAAa;IAC5C,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AACxD,CAAC"}

package/dist/analytics.d.ts

@@ -0,0 +1,36 @@
+export declare const TELEMETRY_NOTICE = "rudder sends anonymous usage events (which backend, which commands, merge outcomes) \u2014 never your prompts, code, paths, or repo names. Turn it off with `rudder telemetry off`.";
+export type EventProperties = Record<string, string | number | boolean | undefined>;
+/**
+ * Off when the user said so, and off in the places where events would be noise
+ * rather than signal: CI, the fake-backend test harness, and any run with no
+ * project key configured.
+ */
+export declare function telemetryEnabled(): Promise<boolean>;
+export declare function setTelemetryEnabled(enabled: boolean): Promise<void>;
+/**
+ * A stable anonymous id per install, minted once and kept in the global config.
+ * It identifies a machine's rudder, not a person: no email, no username, no
+ * hostname. Without it every event would look like a new user and retention
+ * would be meaningless.
+ */
+export declare function installId(): Promise<string>;
+/**
+ * Show the telemetry notice exactly once per install and record that we did.
+ * Returns the text to print, or undefined when it has already been shown (or
+ * telemetry is off, in which case there is nothing to disclose).
+ */
+export declare function pendingTelemetryNotice(): Promise<string | undefined>;
+/**
+ * A repository identity that cannot be turned back into a path or a name:
+ * "how many distinct projects" without saying which. Truncated because a full
+ * digest is no more useful here and reads as more identifying than it is.
+ */
+export declare function projectHash(repoRoot: string): string;
+/** Drop undefined values and anything that smells like a path or a secret. */
+export declare function sanitizeProperties(properties: EventProperties): EventProperties;
+/**
+ * Send one event. Resolves whether or not it worked: a failed capture is never
+ * worth surfacing, and never worth retrying (the next session will tell the
+ * same story). Returns true only when PostHog accepted it, for tests.
+ */
+export declare function capture(event: string, properties?: EventProperties): Promise<boolean>;

package/dist/analytics.js

@@ -0,0 +1,178 @@
+// ---------------------------------------------------------------------------
+// USAGE TELEMETRY.
+//
+// Rudder emits a small set of anonymous product events so the parts people get
+// stuck on are visible: how many installs ever start an agent, how many ever
+// merge, which backend they pick, which errors fire most. npm downloads cannot
+// answer any of that.
+//
+// The rules this file exists to enforce:
+//   * NEVER send prompts, diffs, file contents, paths, repo names, or session
+//     ids. Only the whitelisted properties each call site passes, plus a hashed
+//     project id when a cardinality signal is genuinely needed.
+//   * NEVER block the caller. A dashboard that stutters because analytics is
+//     slow is a worse product than one with no analytics.
+//   * ALWAYS be trivially switchable off, and say so on first run. Dev tools
+//     that phone home silently get uninstalled, deservedly.
+//
+// Transport is PostHog's public capture endpoint: one POST with the PROJECT
+// token (a write-only key, safe to ship) and `$process_person_profile: false`,
+// which keeps events anonymous — no person profile per install.
+// ---------------------------------------------------------------------------
+import { createHash, randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { loadConfig, saveConfig } from "./state.js";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+/** Project write key. Public by design; overridable so forks can point elsewhere. */
+const POSTHOG_PROJECT_KEY = "phc_2KfOzM4nSxjAgPDfgEikP7Kp7JVcU5aJ0kAyEQykkmn";
+/** A hung network must never hold up a CLI command or the dashboard's shutdown. */
+const CAPTURE_TIMEOUT_MS = 2_000;
+export const TELEMETRY_NOTICE = "rudder sends anonymous usage events (which backend, which commands, merge outcomes) — never your prompts, code, paths, or repo names. Turn it off with `rudder telemetry off`.";
+function posthogKey() {
+    return (process.env.RUDDER_POSTHOG_KEY ?? POSTHOG_PROJECT_KEY).trim();
+}
+function posthogHost() {
+    return (process.env.RUDDER_POSTHOG_HOST ?? POSTHOG_HOST).trim().replace(/\/+$/, "");
+}
+/**
+ * Off when the user said so, and off in the places where events would be noise
+ * rather than signal: CI, the fake-backend test harness, and any run with no
+ * project key configured.
+ */
+export async function telemetryEnabled() {
+    if (!posthogKey()) {
+        return false;
+    }
+    const flag = (process.env.RUDDER_TELEMETRY ?? "").trim().toLowerCase();
+    if (["0", "off", "false", "no"].includes(flag)) {
+        return false;
+    }
+    if (process.env.CI || process.env.RUDDER_FAKE_BACKEND === "1") {
+        return false;
+    }
+    const config = await loadConfig();
+    return config.telemetry !== false;
+}
+export async function setTelemetryEnabled(enabled) {
+    const config = await loadConfig();
+    await saveConfig({ ...config, telemetry: enabled });
+}
+/**
+ * A stable anonymous id per install, minted once and kept in the global config.
+ * It identifies a machine's rudder, not a person: no email, no username, no
+ * hostname. Without it every event would look like a new user and retention
+ * would be meaningless.
+ */
+export async function installId() {
+    const config = await loadConfig();
+    if (config.installId && /^[0-9a-f-]{8,}$/i.test(config.installId)) {
+        return config.installId;
+    }
+    const minted = randomUUID();
+    await saveConfig({ ...config, installId: minted });
+    return minted;
+}
+/**
+ * Show the telemetry notice exactly once per install and record that we did.
+ * Returns the text to print, or undefined when it has already been shown (or
+ * telemetry is off, in which case there is nothing to disclose).
+ */
+export async function pendingTelemetryNotice() {
+    if (!(await telemetryEnabled())) {
+        return undefined;
+    }
+    const config = await loadConfig();
+    if (config.telemetryNoticeShownAt) {
+        return undefined;
+    }
+    await saveConfig({ ...config, telemetryNoticeShownAt: new Date().toISOString() });
+    return TELEMETRY_NOTICE;
+}
+/**
+ * A repository identity that cannot be turned back into a path or a name:
+ * "how many distinct projects" without saying which. Truncated because a full
+ * digest is no more useful here and reads as more identifying than it is.
+ */
+export function projectHash(repoRoot) {
+    return createHash("sha256").update(repoRoot).digest("hex").slice(0, 12);
+}
+/** The shipped version, read from the package rather than a baked constant. */
+async function packageVersion() {
+    const packageFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const raw = await fsp.readFile(packageFile, "utf8").catch(() => "");
+    try {
+        return JSON.parse(raw).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function baseProperties() {
+    return {
+        $process_person_profile: false,
+        rudder_version: await packageVersion(),
+        platform: `${process.platform}-${process.arch}`,
+        node_version: process.versions.node,
+        ci: Boolean(process.env.CI),
+    };
+}
+/** Drop undefined values and anything that smells like a path or a secret. */
+export function sanitizeProperties(properties) {
+    const clean = {};
+    for (const [key, value] of Object.entries(properties)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (typeof value === "string") {
+            // A property carrying an absolute path or a token is a bug at the call
+            // site; drop it rather than shipping it and apologising later.
+            if (value.startsWith("/") || value.startsWith("~/") || /^[A-Za-z]:\\/.test(value)) {
+                continue;
+            }
+            if (/(sk-|ghp_|phc_|xox[baprs]-)/.test(value)) {
+                continue;
+            }
+            clean[key] = value.length > 500 ? `${value.slice(0, 500)}…` : value;
+            continue;
+        }
+        clean[key] = value;
+    }
+    return clean;
+}
+/**
+ * Send one event. Resolves whether or not it worked: a failed capture is never
+ * worth surfacing, and never worth retrying (the next session will tell the
+ * same story). Returns true only when PostHog accepted it, for tests.
+ */
+export async function capture(event, properties = {}) {
+    if (!(await telemetryEnabled())) {
+        return false;
+    }
+    const payload = {
+        api_key: posthogKey(),
+        event,
+        distinct_id: await installId(),
+        properties: { ...(await baseProperties()), ...sanitizeProperties(properties) },
+        timestamp: new Date().toISOString(),
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CAPTURE_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${posthogHost()}/i/v0/e/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/attach-session.d.ts

@@ -0,0 +1,91 @@
+import { EchoPredictor } from "./predict.js";
+export type SessionInput = {
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    setRawMode?(mode: boolean): unknown;
+};
+export type SessionOutput = {
+    columns?: number;
+    rows?: number;
+    write(text: string): unknown;
+    on(event: "resize", listener: () => void): unknown;
+    off(event: "resize", listener: () => void): unknown;
+};
+export type SessionOptions = {
+    interactive: boolean;
+    /** false keeps the screen model but never draws predicted keystrokes. */
+    predict?: boolean;
+    /** Where a non-interactive session reports a drop (stderr). */
+    log?: (text: string) => void;
+    now?: () => number;
+};
+export declare const KITTY_KEYBOARD_PUSH = "\u001B[>5u";
+export declare const KITTY_KEYBOARD_POP = "\u001B[<u";
+export declare function containsCtrlC(data: Buffer): boolean;
+export declare class AttachSession {
+    /** Sent as `?client=`: the relay lets this terminal take its own place back. */
+    readonly clientId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly interactive: boolean;
+    /** The cloud's screen as last drawn (and predictive echo on top of it). */
+    readonly predictor: EchoPredictor | null;
+    /** Connections that reached `open`. */
+    connections: number;
+    /** The cloud has drawn on this terminal: a reconnect resumes that picture. */
+    drewFrame: boolean;
+    hasLeft: boolean;
+    private readonly input;
+    private readonly output;
+    private readonly label;
+    private readonly log;
+    private readonly now;
+    private held;
+    private released;
+    private inGap;
+    private status;
+    private badge;
+    private queued;
+    private queuedBytes;
+    private lastCtrlC;
+    private leaveListeners;
+    constructor(label: string, input: SessionInput, output: SessionOutput, options: SessionOptions);
+    /** Take the terminal: alternate screen, raw keys, mouse and keyboard flags. */
+    hold(): void;
+    /** Give the terminal back exactly once, whatever state it is in. */
+    release(): void;
+    /**
+     * The link dropped and a reconnect follows. The screen stays as it was, a
+     * badge says what is happening, and keys are kept for the next connection.
+     */
+    enterGap(): void;
+    /** A retry is about to start; the badge counts them once it is slow. */
+    noteAttempt(attempt: number): void;
+    /** A connection opened: it reads the keys from here on. */
+    exitGap(): void;
+    /** Keys typed while the link was down, in order, for the new connection. */
+    takeQueued(): Buffer | null;
+    /** Wait out a retry delay; true if the user left meanwhile. */
+    wait(ms: number): Promise<boolean>;
+    onLeave(listener: () => void): () => void;
+    /**
+     * Ctrl+C while nothing on the other end can take it: the first press says
+     * how to leave, a second within a few seconds leaves. True when leaving.
+     */
+    ctrlCToLeave(): boolean;
+    leave(): void;
+    /** A lasting state worth a badge (worker away, read-only, reconnecting). */
+    showStatus(text: string): void;
+    /** The state is over: take the badge off and repaint what it covered. */
+    clearStatus(): void;
+    get statusText(): string | null;
+    /** The terminal changed size while connected: redraw the badge to fit. */
+    noteResize(): void;
+    private onGapInput;
+    private onGapResize;
+    private stopGapInput;
+    private closeOpenSequence;
+    private drawBadge;
+    private eraseBadge;
+    private setTitle;
+}