@e2edev/e2e 0.6.1 → 0.7.0

package/dist/telemetry/project.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The anonymous project id. Feature counts need to tell "one project run
+ * many times" from "many projects", and a per-machine id cannot: the same
+ * repository on two laptops would count twice, and one laptop with ten
+ * projects would count once.
+ *
+ * Inside a git repository the id is the SHA-256 of the repository's root
+ * commit, which every clone shares and no one can produce without the
+ * repository itself; a commit hash carries no name, path, or remote. A
+ * shallow clone has no root to offer: its boundary commits pose as roots and
+ * move with every fetch, so it is treated like a directory outside git.
+ * There, the project root path is hashed together with the machine's local
+ * salt, so the id is stable on that machine and unrecoverable anywhere else.
+ * In CI there is no salt, so a runner without a full history has no id: its
+ * working directory is not a project.
+ */
+export declare function anonymousProjectId(projectRoot: string, salt: string | undefined): Promise<string | undefined>;
+//# sourceMappingURL=project.d.ts.map

package/dist/telemetry/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/telemetry/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkCH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK7B"}

package/dist/telemetry/project.js

@@ -0,0 +1,55 @@
+/**
+ * The anonymous project id. Feature counts need to tell "one project run
+ * many times" from "many projects", and a per-machine id cannot: the same
+ * repository on two laptops would count twice, and one laptop with ten
+ * projects would count once.
+ *
+ * Inside a git repository the id is the SHA-256 of the repository's root
+ * commit, which every clone shares and no one can produce without the
+ * repository itself; a commit hash carries no name, path, or remote. A
+ * shallow clone has no root to offer: its boundary commits pose as roots and
+ * move with every fetch, so it is treated like a directory outside git.
+ * There, the project root path is hashed together with the machine's local
+ * salt, so the id is stable on that machine and unrecoverable anywhere else.
+ * In CI there is no salt, so a runner without a full history has no id: its
+ * working directory is not a project.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { sha256Hex } from '../internal/ids.js';
+const execFileAsync = promisify(execFile);
+const COMMIT_HASH = /^[a-f0-9]{40,64}$/u;
+/** One git command's stdout; undefined when git is missing, slow, or refuses. */
+async function git(cwd, args) {
+    try {
+        const { stdout } = await execFileAsync('git', args, { cwd, timeout: 1_000, windowsHide: true, encoding: 'utf8' });
+        return stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The lexically first root commit reachable from HEAD; undefined outside git and in a shallow clone. */
+async function rootCommit(cwd) {
+    const [shallow, roots] = await Promise.all([
+        git(cwd, ['rev-parse', '--is-shallow-repository']),
+        git(cwd, ['rev-list', '--max-parents=0', 'HEAD']),
+    ]);
+    // Only an explicit `false` counts: a git too old for the flag echoes it back instead.
+    if (shallow?.trim() !== 'false' || roots === undefined)
+        return undefined;
+    return roots
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => COMMIT_HASH.test(line))
+        .toSorted()[0];
+}
+export async function anonymousProjectId(projectRoot, salt) {
+    const commit = await rootCommit(projectRoot);
+    if (commit !== undefined)
+        return sha256Hex(`git\n${commit}`);
+    if (salt === undefined)
+        return undefined;
+    return sha256Hex(`path\n${salt}\n${projectRoot}`);
+}
+//# sourceMappingURL=project.js.map

package/dist/telemetry/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/telemetry/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC1C,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEzC,iFAAiF;AACjF,KAAK,UAAU,GAAG,CAAC,GAAW,EAAE,IAAuB;IACrD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAClH,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,yGAAyG;AACzG,KAAK,UAAU,UAAU,CAAC,GAAW;IACnC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACzC,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,yBAAyB,CAAC,CAAC;QAClD,GAAG,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;KAClD,CAAC,CAAC;IACH,sFAAsF;IACtF,IAAI,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzE,OAAO,KAAK;SACT,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACxC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,IAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;IAC7C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,SAAS,CAAC,SAAS,IAAI,KAAK,WAAW,EAAE,CAAC,CAAC;AACpD,CAAC"}

package/dist/telemetry/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The user-level telemetry preferences: `~/.config/e2e/telemetry.json`
+ * (`$XDG_CONFIG_HOME/e2e` when set, `%APPDATA%\e2e` on Windows). The file
+ * holds the opt-out, the random id every event from this machine is
+ * attributed to, the salt that keeps a hashed path unrecoverable, and which
+ * notice was shown when. Nothing in it names the person or the machine: the
+ * id and the salt are random bytes, generated here and never derived.
+ *
+ * The store fails closed. `open` completes the file in one write when the id
+ * or the salt is missing, and when that write cannot happen there is no
+ * store: telemetry treats the absence as an opt-out rather than sending
+ * events it could neither attribute nor de-duplicate. After `open`, only the
+ * user's own choice and the notice mark write, so an ordinary command never
+ * rewrites the file while another process may be saving a choice to it.
+ */
+/** The preferences file inside a config directory. */
+export declare function preferencesPath(directory: string): string;
+/** Where the preferences live for this platform and environment. */
+export declare function telemetryConfigDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export declare class TelemetryStore {
+    /** The preferences file, for messages that tell the user where a choice was saved. */
+    readonly path: string;
+    private preferences;
+    private constructor();
+    /**
+     * Opens the store in `directory`. A complete file is only read, so a
+     * read-only preferences file keeps working. A missing file, a file that is
+     * not JSON, or one without an id or a salt is completed in one write that
+     * also creates the directory; a torn write must not turn into a permanent
+     * opt-in or opt-out either way. Returns undefined when that write fails,
+     * which the caller reads as off.
+     */
+    static open(directory: string): TelemetryStore | undefined;
+    /** The user's choice; unset means participating. */
+    get enabled(): boolean;
+    /** The random per-machine id every event from this machine is attributed to. */
+    get anonymousId(): string;
+    /** The local salt that keeps a hashed project path unrecoverable; never leaves the machine. */
+    get pathSalt(): string;
+    /** Saves the choice; false when the file could not be written and the choice stayed in memory. */
+    saveEnabled(value: boolean): boolean;
+    /**
+     * Re-reads the file, so a choice another process saved since `open` is
+     * seen before anything is sent. An unreadable file changes nothing.
+     */
+    reload(): void;
+    /** Whether this version of the notice has been shown. */
+    wasNotified(version: number): boolean;
+    /** Records that the notice was shown; a failed write only means it may show once more. */
+    markNotified(version: number, at: string): void;
+    private write;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/telemetry/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/telemetry/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwBH,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAOR;AA8BD,qBAAa,cAAc;IACzB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,WAAW,CAAa;IAEhC,OAAO,eAGN;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAezD;IAED,oDAAoD;IACpD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gFAAgF;IAChF,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,+FAA+F;IAC/F,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,kGAAkG;IAClG,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGnC;IAED;;;OAGG;IACH,MAAM,IAAI,IAAI,CAQb;IAED,yDAAyD;IACzD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpC;IAED,0FAA0F;IAC1F,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAI9C;IAED,OAAO,CAAC,KAAK;CAQd"}

package/dist/telemetry/store.js

@@ -0,0 +1,153 @@
+/**
+ * The user-level telemetry preferences: `~/.config/e2e/telemetry.json`
+ * (`$XDG_CONFIG_HOME/e2e` when set, `%APPDATA%\e2e` on Windows). The file
+ * holds the opt-out, the random id every event from this machine is
+ * attributed to, the salt that keeps a hashed path unrecoverable, and which
+ * notice was shown when. Nothing in it names the person or the machine: the
+ * id and the salt are random bytes, generated here and never derived.
+ *
+ * The store fails closed. `open` completes the file in one write when the id
+ * or the salt is missing, and when that write cannot happen there is no
+ * store: telemetry treats the absence as an opt-out rather than sending
+ * events it could neither attribute nor de-duplicate. After `open`, only the
+ * user's own choice and the notice mark write, so an ordinary command never
+ * rewrites the file while another process may be saving a choice to it.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { writeFileAtomicSync } from '../internal/atomic-write.js';
+import { envValue } from '../internal/env.js';
+const FILE_NAME = 'telemetry.json';
+const HEX = /^[a-f0-9]{16,128}$/u;
+/** The preferences file inside a config directory. */
+export function preferencesPath(directory) {
+    return path.join(directory, FILE_NAME);
+}
+/** Where the preferences live for this platform and environment. */
+export function telemetryConfigDir(env = process.env, platform = process.platform) {
+    if (platform === 'win32') {
+        const appData = envValue(env, 'APPDATA') ?? path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'e2e');
+    }
+    const configHome = envValue(env, 'XDG_CONFIG_HOME') ?? path.join(os.homedir(), '.config');
+    return path.join(configHome, 'e2e');
+}
+/** Keeps only the fields this version knows, each with the type it expects. */
+function sanitize(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    const raw = value;
+    const preferences = {};
+    if (typeof raw['enabled'] === 'boolean')
+        preferences.enabled = raw['enabled'];
+    if (typeof raw['anonymousId'] === 'string' && HEX.test(raw['anonymousId'])) {
+        preferences.anonymousId = raw['anonymousId'];
+    }
+    if (typeof raw['salt'] === 'string' && HEX.test(raw['salt']))
+        preferences.salt = raw['salt'];
+    if (typeof raw['notifiedAt'] === 'string')
+        preferences.notifiedAt = raw['notifiedAt'];
+    if (typeof raw['noticeVersion'] === 'number')
+        preferences.noticeVersion = raw['noticeVersion'];
+    return preferences;
+}
+/** The file's preferences, or undefined when it is missing or not JSON. */
+function readPreferences(filePath) {
+    try {
+        return sanitize(JSON.parse(readFileSync(filePath, 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+function randomHex() {
+    return randomBytes(16).toString('hex');
+}
+export class TelemetryStore {
+    /** The preferences file, for messages that tell the user where a choice was saved. */
+    path;
+    preferences;
+    constructor(filePath, preferences) {
+        this.path = filePath;
+        this.preferences = preferences;
+    }
+    /**
+     * Opens the store in `directory`. A complete file is only read, so a
+     * read-only preferences file keeps working. A missing file, a file that is
+     * not JSON, or one without an id or a salt is completed in one write that
+     * also creates the directory; a torn write must not turn into a permanent
+     * opt-in or opt-out either way. Returns undefined when that write fails,
+     * which the caller reads as off.
+     */
+    static open(directory) {
+        const filePath = preferencesPath(directory);
+        const read = readPreferences(filePath);
+        const store = new TelemetryStore(filePath, {
+            ...read,
+            anonymousId: read?.anonymousId ?? randomHex(),
+            salt: read?.salt ?? randomHex(),
+        });
+        if (read !== undefined && read.anonymousId !== undefined && read.salt !== undefined)
+            return store;
+        try {
+            mkdirSync(directory, { recursive: true });
+        }
+        catch {
+            return undefined;
+        }
+        return store.write() ? store : undefined;
+    }
+    /** The user's choice; unset means participating. */
+    get enabled() {
+        return this.preferences.enabled !== false;
+    }
+    /** The random per-machine id every event from this machine is attributed to. */
+    get anonymousId() {
+        return this.preferences.anonymousId;
+    }
+    /** The local salt that keeps a hashed project path unrecoverable; never leaves the machine. */
+    get pathSalt() {
+        return this.preferences.salt;
+    }
+    /** Saves the choice; false when the file could not be written and the choice stayed in memory. */
+    saveEnabled(value) {
+        this.preferences.enabled = value;
+        return this.write();
+    }
+    /**
+     * Re-reads the file, so a choice another process saved since `open` is
+     * seen before anything is sent. An unreadable file changes nothing.
+     */
+    reload() {
+        const read = readPreferences(this.path);
+        if (read === undefined)
+            return;
+        this.preferences = {
+            ...read,
+            anonymousId: read.anonymousId ?? this.preferences.anonymousId,
+            salt: read.salt ?? this.preferences.salt,
+        };
+    }
+    /** Whether this version of the notice has been shown. */
+    wasNotified(version) {
+        return this.preferences.notifiedAt !== undefined && (this.preferences.noticeVersion ?? 0) >= version;
+    }
+    /** Records that the notice was shown; a failed write only means it may show once more. */
+    markNotified(version, at) {
+        this.preferences.notifiedAt = at;
+        this.preferences.noticeVersion = version;
+        this.write();
+    }
+    write() {
+        try {
+            writeFileAtomicSync(this.path, `${JSON.stringify(this.preferences, null, 2)}\n`, { mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/telemetry/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/telemetry/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAc9C,MAAM,SAAS,GAAG,gBAAgB,CAAC;AACnC,MAAM,GAAG,GAAG,qBAAqB,CAAC;AAElC,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAChC,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAE5C,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC1F,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnF,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,WAAW,GAAgB,EAAE,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS;QAAE,WAAW,CAAC,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IAC9E,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;QAC3E,WAAW,CAAC,WAAW,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAAE,WAAW,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7F,IAAI,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,QAAQ;QAAE,WAAW,CAAC,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACtF,IAAI,OAAO,GAAG,CAAC,eAAe,CAAC,KAAK,QAAQ;QAAE,WAAW,CAAC,aAAa,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;IAC/F,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,2EAA2E;AAC3E,SAAS,eAAe,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,cAAc;IACzB,sFAAsF;IAC7E,IAAI,CAAS;IACd,WAAW,CAAa;IAEhC,YAAoB,QAAgB,EAAE,WAAuB;QAC3D,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,SAAiB;QAC3B,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE;YACzC,GAAG,IAAI;YACP,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,SAAS,EAAE;YAC7C,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,SAAS,EAAE;SAChC,CAAC,CAAC;QACH,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAClG,IAAI,CAAC;YACH,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3C,CAAC;IAED,oDAAoD;IACpD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,KAAK,KAAK,CAAC;IAC5C,CAAC;IAED,gFAAgF;IAChF,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC;IACtC,CAAC;IAED,+FAA+F;IAC/F,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED,kGAAkG;IAClG,WAAW,CAAC,KAAc;QACxB,IAAI,CAAC,WAAW,CAAC,OAAO,GAAG,KAAK,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,IAAI,CAAC,WAAW,GAAG;YACjB,GAAG,IAAI;YACP,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,WAAW;YAC7D,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI;SACzC,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,WAAW,CAAC,OAAe;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,aAAa,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC;IACvG,CAAC;IAED,0FAA0F;IAC1F,YAAY,CAAC,OAAe,EAAE,EAAU;QACtC,IAAI,CAAC,WAAW,CAAC,UAAU,GAAG,EAAE,CAAC;QACjC,IAAI,CAAC,WAAW,CAAC,aAAa,GAAG,OAAO,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAEO,KAAK;QACX,IAAI,CAAC;YACH,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAClG,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Anonymous usage telemetry for the CLI.
+ *
+ * One instance lives for one CLI invocation. Commands hand it events; at the
+ * end of the invocation `flush` sends them in a single bounded request, so a
+ * command never waits on telemetry for more than the flush budget and never
+ * fails because of it. Telemetry is a CLI concern only: a host embedding the
+ * runner through `@e2edev/e2e/run` never constructs this class, and its runs
+ * send nothing.
+ *
+ * Off means off at every step. `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, an
+ * `e2e telemetry disable`, or a preferences directory that cannot be written
+ * each stop events from being queued, and `flush` reads the preferences file
+ * again before sending, so a choice saved from another terminal while the
+ * command ran wins too. `E2E_TELEMETRY_DEBUG` prints every event to stderr
+ * instead of sending it, so anyone can read exactly what would have left the
+ * machine.
+ *
+ * Identity is deliberately weak: a random per-machine id from the preferences
+ * file, a random per-invocation session id, and a hashed project id. In CI
+ * there is no preferences file and every run is attributed to the CI vendor,
+ * so a fleet of ephemeral runners does not masquerade as a crowd of users.
+ */
+import type { TelemetryEvent } from './events.ts';
+import { anonymousProjectId } from './project.ts';
+/** Bumped when what is collected changes enough that the notice must show again. */
+export declare const NOTICE_VERSION = 1;
+export type TelemetryDisabledBy = 'E2E_TELEMETRY_DISABLED' | 'DO_NOT_TRACK' | 'preference' | 'store';
+export interface TelemetryOptions {
+    /** The e2e version, sent with every event. */
+    readonly version: string;
+    readonly env?: NodeJS.ProcessEnv;
+    /** The project directory the command runs in; hashed into the project id, never sent. */
+    readonly cwd?: string;
+    /** Where the preferences file lives; the platform default when absent. */
+    readonly configDir?: string;
+    readonly fetch?: typeof fetch;
+    /** Where the notice and the debug output go; stderr when absent. */
+    readonly write?: (text: string) => void;
+    /** Resolves the anonymous project id; git and the salted path when absent. */
+    readonly projectId?: typeof anonymousProjectId;
+}
+export declare class Telemetry {
+    /** Random per-invocation id, so one invocation's events can be grouped. */
+    readonly sessionId: string;
+    private readonly version;
+    private readonly env;
+    private readonly cwd;
+    private readonly configDir;
+    private readonly fetchImpl;
+    private readonly write;
+    private readonly projectId;
+    private readonly ci;
+    /** The store once `store()` opened it, whether or not the file could exist. */
+    private opened;
+    private readonly queue;
+    private project;
+    constructor(options: TelemetryOptions);
+    /** Opened on first use, so `--version` and `--help` never touch the disk; undefined when the file cannot exist. */
+    private store;
+    /** Why telemetry is off, or undefined when it is on. */
+    get disabledBy(): TelemetryDisabledBy | undefined;
+    get enabled(): boolean;
+    /** `E2E_TELEMETRY_DEBUG`: print every event, send nothing. */
+    get debug(): boolean;
+    /** The preferences file, whether or not it exists yet. */
+    get preferencesPath(): string;
+    /**
+     * Saves the user's choice. Returns the file it was saved to, or undefined
+     * when the file could not be written, in which case telemetry is off anyway
+     * because there is no store to attribute events with.
+     */
+    setEnabled(value: boolean): string | undefined;
+    /**
+     * Prints the notice the first time this machine runs a version of it, and
+     * records that it did. Nothing in CI, where the output is a log nobody is
+     * reading and there is no file to remember it in; nothing when off.
+     */
+    notice(): void;
+    /** Queues one event for the flush; a no-op when off. */
+    record(event: TelemetryEvent): void;
+    /**
+     * Sends everything queued in one request, or prints it under debug. One
+     * deadline covers the project lookup still running and the request; a
+     * lost batch is the accepted cost of a command that never waits on
+     * telemetry.
+     */
+    flush(maxWaitMs?: number): Promise<void>;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,oFAAoF;AACpF,eAAO,MAAM,cAAc,IAAI,CAAC;AAIhC,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GAAG,cAAc,GAAG,YAAY,GAAG,OAAO,CAAC;AAErG,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,kBAAkB,CAAC;CAChD;AAmBD,qBAAa,SAAS;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,SAAmC;IAErD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAU;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,MAAM,CAA6D;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,OAAO,CAA0C;IAEzD,YAAY,OAAO,EAAE,gBAAgB,EASpC;IAED,mHAAmH;IACnH,OAAO,CAAC,KAAK;IAKb,wDAAwD;IACxD,IAAI,UAAU,IAAI,mBAAmB,GAAG,SAAS,CAOhD;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,8DAA8D;IAC9D,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,0DAA0D;IAC1D,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI7C;IAED;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAMb;IAED,wDAAwD;IACxD,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAQlC;IAED;;;;;OAKG;IACG,KAAK,CAAC,SAAS,GAAE,MAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC/D;CACF"}

package/dist/telemetry/telemetry.js

@@ -0,0 +1,188 @@
+/**
+ * Anonymous usage telemetry for the CLI.
+ *
+ * One instance lives for one CLI invocation. Commands hand it events; at the
+ * end of the invocation `flush` sends them in a single bounded request, so a
+ * command never waits on telemetry for more than the flush budget and never
+ * fails because of it. Telemetry is a CLI concern only: a host embedding the
+ * runner through `@e2edev/e2e/run` never constructs this class, and its runs
+ * send nothing.
+ *
+ * Off means off at every step. `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, an
+ * `e2e telemetry disable`, or a preferences directory that cannot be written
+ * each stop events from being queued, and `flush` reads the preferences file
+ * again before sending, so a choice saved from another terminal while the
+ * command ran wins too. `E2E_TELEMETRY_DEBUG` prints every event to stderr
+ * instead of sending it, so anyone can read exactly what would have left the
+ * machine.
+ *
+ * Identity is deliberately weak: a random per-machine id from the preferences
+ * file, a random per-invocation session id, and a hashed project id. In CI
+ * there is no preferences file and every run is attributed to the CI vendor,
+ * so a fleet of ephemeral runners does not masquerade as a crowd of users.
+ */
+import { randomBytes } from 'node:crypto';
+import picocolors from 'picocolors';
+import { DOCS_URL } from '../cli/docs-url.js';
+import { isCiMode } from '../config/resolve.js';
+import { envFlag } from '../internal/env.js';
+import { timestamp } from '../internal/ids.js';
+import { ciName, collectEnvironment } from './environment.js';
+import { postBatch } from './posthog.js';
+import { anonymousProjectId } from './project.js';
+import { preferencesPath, TelemetryStore, telemetryConfigDir } from './store.js';
+/** Bumped when what is collected changes enough that the notice must show again. */
+export const NOTICE_VERSION = 1;
+/** The longest a flush may hold the process; the project lookup and the request share it. */
+const DEFAULT_FLUSH_MS = 2_000;
+/** The one-time notice: what is collected, and the two ways out. */
+function noticeText() {
+    return [
+        `${picocolors.bold('e2e collects anonymous usage telemetry')} to improve the framework: the command, the versions, the OS, and run counts. Never test names, app data, or credentials.`,
+        `Opt out with ${picocolors.cyan('e2e telemetry disable')} or ${picocolors.cyan('E2E_TELEMETRY_DISABLED=1')}. What is sent: ${picocolors.underline(`${DOCS_URL}/telemetry`)}`,
+        '',
+        '',
+    ].join('\n');
+}
+/** Resolves to undefined when the signal aborts; whatever loses a race against it is abandoned. */
+function aborted(signal) {
+    return new Promise((resolve) => {
+        signal.addEventListener('abort', () => resolve(undefined), { once: true });
+    });
+}
+export class Telemetry {
+    /** Random per-invocation id, so one invocation's events can be grouped. */
+    sessionId = randomBytes(16).toString('hex');
+    version;
+    env;
+    cwd;
+    configDir;
+    fetchImpl;
+    write;
+    projectId;
+    ci;
+    /** The store once `store()` opened it, whether or not the file could exist. */
+    opened;
+    queue = [];
+    project;
+    constructor(options) {
+        this.version = options.version;
+        this.env = options.env ?? process.env;
+        this.cwd = options.cwd ?? process.cwd();
+        this.configDir = options.configDir ?? telemetryConfigDir(this.env);
+        this.fetchImpl = options.fetch ?? fetch;
+        this.write = options.write ?? ((text) => void process.stderr.write(text));
+        this.projectId = options.projectId ?? anonymousProjectId;
+        this.ci = isCiMode(this.env);
+    }
+    /** Opened on first use, so `--version` and `--help` never touch the disk; undefined when the file cannot exist. */
+    store() {
+        this.opened ??= { store: TelemetryStore.open(this.configDir) };
+        return this.opened.store;
+    }
+    /** Why telemetry is off, or undefined when it is on. */
+    get disabledBy() {
+        if (envFlag(this.env, 'E2E_TELEMETRY_DISABLED'))
+            return 'E2E_TELEMETRY_DISABLED';
+        if (envFlag(this.env, 'DO_NOT_TRACK'))
+            return 'DO_NOT_TRACK';
+        if (this.ci)
+            return undefined;
+        const store = this.store();
+        if (store === undefined)
+            return 'store';
+        return store.enabled ? undefined : 'preference';
+    }
+    get enabled() {
+        return this.disabledBy === undefined;
+    }
+    /** `E2E_TELEMETRY_DEBUG`: print every event, send nothing. */
+    get debug() {
+        return envFlag(this.env, 'E2E_TELEMETRY_DEBUG');
+    }
+    /** The preferences file, whether or not it exists yet. */
+    get preferencesPath() {
+        return preferencesPath(this.configDir);
+    }
+    /**
+     * Saves the user's choice. Returns the file it was saved to, or undefined
+     * when the file could not be written, in which case telemetry is off anyway
+     * because there is no store to attribute events with.
+     */
+    setEnabled(value) {
+        const store = this.store();
+        if (store === undefined)
+            return undefined;
+        return store.saveEnabled(value) ? store.path : undefined;
+    }
+    /**
+     * Prints the notice the first time this machine runs a version of it, and
+     * records that it did. Nothing in CI, where the output is a log nobody is
+     * reading and there is no file to remember it in; nothing when off.
+     */
+    notice() {
+        if (this.ci || !this.enabled)
+            return;
+        const store = this.store();
+        if (store === undefined || store.wasNotified(NOTICE_VERSION))
+            return;
+        store.markNotified(NOTICE_VERSION, timestamp());
+        this.write(noticeText());
+    }
+    /** Queues one event for the flush; a no-op when off. */
+    record(event) {
+        if (!this.enabled)
+            return;
+        this.queue.push(event);
+        // Git is asked for the project id now, while the command runs, so the
+        // flush at the end waits on the network alone. In CI there is no store,
+        // so a path outside git has nothing to salt it and yields no id.
+        const store = this.ci ? undefined : this.store();
+        this.project ??= this.projectId(this.cwd, store?.pathSalt);
+    }
+    /**
+     * Sends everything queued in one request, or prints it under debug. One
+     * deadline covers the project lookup still running and the request; a
+     * lost batch is the accepted cost of a command that never waits on
+     * telemetry.
+     */
+    async flush(maxWaitMs = DEFAULT_FLUSH_MS) {
+        const events = this.queue.splice(0);
+        if (events.length === 0)
+            return;
+        // A choice saved from another process while this command ran wins over the snapshot taken at its start.
+        const store = this.ci ? undefined : this.store();
+        store?.reload();
+        if (!this.enabled)
+            return;
+        const deadline = AbortSignal.timeout(maxWaitMs);
+        const project = await Promise.race([this.project, aborted(deadline)]);
+        // Outside CI, `enabled` has just vouched for the store; no store means a CI run, attributed to the vendor.
+        const distinctId = store === undefined ? `ci:${ciName(this.env) ?? 'unknown'}` : store.anonymousId;
+        const environment = collectEnvironment({ env: this.env, cwd: this.cwd, version: this.version });
+        // The debug output and the request body are the same objects, so what
+        // `E2E_TELEMETRY_DEBUG` shows is what would have been sent, key for key.
+        const items = events.map((event) => ({
+            event: event.name,
+            timestamp: event.at ?? timestamp(),
+            properties: {
+                ...environment,
+                ...event.properties,
+                distinct_id: distinctId,
+                project_id: project ?? null,
+                session_id: this.sessionId,
+                $lib: 'e2e',
+                $lib_version: this.version,
+                // Anonymous events: PostHog keeps no person profile for the id.
+                $process_person_profile: false,
+            },
+        }));
+        if (this.debug) {
+            for (const item of items)
+                this.write(`[telemetry] ${JSON.stringify(item)}\n`);
+            return;
+        }
+        await postBatch(items, { signal: deadline, fetch: this.fetchImpl });
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry/telemetry.js.map

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

package/dist/types.d.ts

@@ -101,24 +101,21 @@ export type VisionMode = boolean | 'fallback' | 'only';
 export interface VisionOption {
     vision?: VisionMode;
 }
-export interface AgentOptions extends VisionOption {
+/**
+ * Per-call budgets for `act`. Structured output and vision are judgment-tier
+ * options: `extract` takes `schema`; `assert`, `waitFor`, and `extract`
+ * take `vision`.
+ */
+export interface AgentOptions {
     timeout?: number;
     maxSteps?: number;
     maxModelCalls?: number;
 }
-export interface AgentSchemaOptions<Schema extends StandardSchemaV1> extends AgentOptions {
-    schema: Schema;
-}
 export interface AgentResult {
     readonly ok: true;
 }
-export interface AgentResultWithData<Output> extends AgentResult {
-    readonly data: Output;
-}
 export type AgentErrorCode = 'AUTH_CREDENTIAL_UNAVAILABLE' | 'AUTH_CREDENTIAL_INVALID' | 'AUTHENTICATION_FAILED' | 'ENVIRONMENT_UNAVAILABLE' | 'SEED_DATA_MISSING' | 'TEST_SETUP_FAILED' | 'MODEL_UNAVAILABLE' | 'MODEL_PROVIDER_FAILED' | 'MODEL_OUTPUT_INVALID' | 'APP_UNREACHABLE' | 'APP_ALREADY_RUNNING' | 'APP_NOT_OPEN' | 'LOCATOR_NOT_FOUND' | 'LOCATOR_AMBIGUOUS' | 'ACTION_FAILED' | 'AUTOMATION_UNSUPPORTED' | 'POLICY_DENIED' | 'STEP_BUDGET_EXHAUSTED' | 'STEP_TIMEOUT' | 'STEP_NO_CONCLUSION' | 'ASSERTION_FAILED' | 'CANCELLED';
 export interface Agent {
-    /** Plans a flow and validates its structured result with Standard Schema v1. */
-    act<Schema extends StandardSchemaV1>(instruction: string, params: AgentParams | undefined, options: AgentSchemaOptions<Schema>): Promise<AgentResultWithData<StandardSchemaV1.InferOutput<Schema>>>;
     /** Plans and executes a bounded multi-action flow. */
     act(instruction: string, params?: AgentParams, options?: AgentOptions): Promise<AgentResult>;
     /** Polls a natural-language condition until true or timed out. */