alchemy 0.69.0 → 0.70.0

package/src/scope.ts

@@ -29,7 +29,7 @@ import {
 import { logger } from "./util/logger.ts";
 import { AsyncMutex } from "./util/mutex.ts";
 import { ALCHEMY_ROOT } from "./util/root-dir.ts";
-import type { ITelemetryClient } from "./util/telemetry/client.ts";
+import { createAndSendEvent } from "./util/telemetry.ts";
 
 export class RootScopeStateAttemptError extends Error {
   constructor() {
@@ -76,10 +76,11 @@ export interface ScopeOptions extends ProviderCredentials {
    */
   destroyStrategy?: DestroyStrategy;
   /**
-   * The telemetry client to use for the scope.
+   * Whether to disable telemetry for the scope.
    *
+   * @default false
    */
-  telemetryClient?: ITelemetryClient;
+  noTrack?: boolean;
   /**
    * The logger to use for the scope.
    */
@@ -197,7 +198,7 @@ export class Scope {
   public readonly adopt: boolean;
   public readonly destroyStrategy: DestroyStrategy;
   public readonly logger: LoggerApi;
-  public readonly telemetryClient: ITelemetryClient;
+  public readonly noTrack: boolean;
   public readonly dataMutex: AsyncMutex;
   public readonly rootDir: string;
   public readonly dotAlchemy: string;
@@ -235,12 +236,12 @@ export class Scope {
       tunnel,
       force,
       destroyStrategy,
-      telemetryClient,
       logger,
       adopt,
       dotAlchemy,
       rootDir,
       isSelected,
+      noTrack,
       ...providerCredentials
     } = options;
 
@@ -273,6 +274,7 @@ export class Scope {
       throw new Error("Scope name is required when creating a child scope");
     }
     this.password = password ?? this.parent?.password;
+    this.noTrack = noTrack ?? this.parent?.noTrack ?? false;
     const resolvedPhase = phase ?? this.parent?.phase;
     if (resolvedPhase === undefined) {
       throw new Error("Phase is required");
@@ -307,14 +309,7 @@ export class Scope {
       stateStore ??
       this.parent?.stateStore ??
       ((scope) => new FileSystemStateStore(scope));
-    this.telemetryClient = telemetryClient ?? this.parent?.telemetryClient!;
-    this.state = new InstrumentedStateStore(
-      this.stateStore(this),
-      this.telemetryClient,
-    );
-    if (!telemetryClient && !this.parent?.telemetryClient) {
-      throw new Error("Telemetry client is required");
-    }
+    this.state = new InstrumentedStateStore(this.stateStore(this));
     this.dataMutex = new AsyncMutex();
   }
 
@@ -413,12 +408,7 @@ export class Scope {
   }
 
   public async init() {
-    await Promise.all([
-      this.state.init?.(),
-      this.telemetryClient.ready.catch((error) => {
-        this.logger.warn("Telemetry initialization failed:", error);
-      }),
-    ]);
+    await Promise.all([this.state.init?.()]);
   }
 
   public async deinit() {
@@ -515,26 +505,15 @@ export class Scope {
     return this.finalize();
   }
 
-  /**
-   * The telemetry client for the root scope.
-   * This is used so that app-level hooks are only called once.
-   */
-  private get rootTelemetryClient(): ITelemetryClient | null {
-    if (!this.parent) {
-      return this.telemetryClient;
-    }
-    return null;
-  }
-
   public async finalize(options?: { force?: boolean; noop?: boolean }) {
     const shouldForce =
       options?.force ||
       this.parent === undefined ||
       this?.parent?.scopeName === this.root.scopeName;
     if (this.phase === "read") {
-      this.rootTelemetryClient?.record({
-        event: "app.success",
-        elapsed: performance.now() - this.startedAt,
+      createAndSendEvent({
+        event: "alchemy.success",
+        duration: performance.now() - this.startedAt,
       });
       return;
     }
@@ -583,23 +562,21 @@ export class Scope {
         force: shouldForce,
         noop: options?.noop,
       });
-      this.rootTelemetryClient?.record({
-        event: "app.success",
-        elapsed: performance.now() - this.startedAt,
+      createAndSendEvent({
+        event: "alchemy.success",
+        duration: performance.now() - this.startedAt,
       });
     } else if (this.isErrored) {
       this.logger.warn("Scope is in error, skipping finalize");
-      this.rootTelemetryClient?.record({
-        event: "app.error",
-        error: new Error("Scope failed"),
-        elapsed: performance.now() - this.startedAt,
-      });
+      createAndSendEvent(
+        {
+          event: "alchemy.error",
+          duration: performance.now() - this.startedAt,
+        },
+        new Error("Scope failed"),
+      );
     }
 
-    await this.rootTelemetryClient?.finalize()?.catch((error) => {
-      this.logger.warn("Telemetry finalization failed:", error);
-    });
-
     if (!this.parent && process.env.ALCHEMY_TEST_KILL_ON_FINALIZE) {
       await this.cleanup();
       process.exit(0);

package/src/state/instrumented-state-store.ts

@@ -1,6 +1,8 @@
 import type { State, StateStore } from "../state.ts";
-import type { ITelemetryClient } from "../util/telemetry/client.ts";
-import type { Telemetry } from "../util/telemetry/types.ts";
+import {
+  createAndSendEvent,
+  type StateStoreTelemetryData,
+} from "../util/telemetry.ts";
 
 //todo(michael): we should also handle serde here
 export class InstrumentedStateStore<T extends StateStore>
@@ -9,17 +11,15 @@ export class InstrumentedStateStore<T extends StateStore>
   /** @internal */
   __phantom?: T;
   private readonly stateStore: StateStore;
-  private readonly telemetryClient: ITelemetryClient;
   private readonly stateStoreClass: string;
 
-  constructor(stateStore: StateStore, telemetryClient: ITelemetryClient) {
+  constructor(stateStore: StateStore) {
     this.stateStore = stateStore;
-    this.telemetryClient = telemetryClient;
     this.stateStoreClass = stateStore.constructor.name;
   }
 
   private async callWithTelemetry<T>(
-    event: Telemetry.StateStoreEvent["event"],
+    event: StateStoreTelemetryData["event"],
     fn: () => Promise<T>,
   ): Promise<T> {
     const start = performance.now();
@@ -30,17 +30,18 @@ export class InstrumentedStateStore<T extends StateStore>
       error = err;
       throw err;
     } finally {
-      this.telemetryClient.record({
-        event,
-        stateStoreClass: this.stateStoreClass,
-        elapsed: performance.now() - start,
-        error:
-          error instanceof Error
-            ? error
-            : error
-              ? new Error(String(error))
-              : undefined,
-      });
+      createAndSendEvent(
+        {
+          event,
+          stateStore: this.stateStoreClass,
+          duration: performance.now() - start,
+        },
+        error instanceof Error
+          ? error
+          : error
+            ? new Error(String(error))
+            : undefined,
+      );
     }
   }
 
@@ -49,7 +50,7 @@ export class InstrumentedStateStore<T extends StateStore>
       return;
     }
     await this.callWithTelemetry(
-      "stateStore.init",
+      "statestore.init",
       this.stateStore.init.bind(this.stateStore),
     );
   }
@@ -58,49 +59,49 @@ export class InstrumentedStateStore<T extends StateStore>
       return;
     }
     await this.callWithTelemetry(
-      "stateStore.deinit",
+      "statestore.deinit",
       this.stateStore.deinit.bind(this.stateStore),
     );
   }
   async list() {
     return await this.callWithTelemetry(
-      "stateStore.list",
+      "statestore.list",
       this.stateStore.list.bind(this.stateStore),
     );
   }
   async count() {
     return await this.callWithTelemetry(
-      "stateStore.count",
+      "statestore.count",
       this.stateStore.count.bind(this.stateStore),
     );
   }
   async get(key: string) {
     return await this.callWithTelemetry(
-      "stateStore.get",
+      "statestore.get",
       this.stateStore.get.bind(this.stateStore, key),
     );
   }
   async getBatch(ids: string[]) {
     return await this.callWithTelemetry(
-      "stateStore.getBatch",
+      "statestore.getBatch",
       this.stateStore.getBatch.bind(this.stateStore, ids),
     );
   }
   async all() {
     return await this.callWithTelemetry(
-      "stateStore.all",
+      "statestore.all",
       this.stateStore.all.bind(this.stateStore),
     );
   }
   async set(key: string, value: State) {
     await this.callWithTelemetry(
-      "stateStore.set",
+      "statestore.set",
       this.stateStore.set.bind(this.stateStore, key, value),
     );
   }
   async delete(key: string) {
     await this.callWithTelemetry(
-      "stateStore.delete",
+      "statestore.delete",
       this.stateStore.delete.bind(this.stateStore, key),
     );
   }

package/src/test/bun.ts

@@ -4,7 +4,6 @@ import { afterAll, beforeAll, it } from "bun:test";
 import path from "node:path";
 import { alchemy } from "../alchemy.ts";
 import { Scope } from "../scope.ts";
-import { NoopTelemetryClient } from "../util/telemetry/index.ts";
 import type { TestOptions } from "./options.ts";
 
 /**
@@ -103,7 +102,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
     // parent: globalTestScope,
     stateStore: defaultOptions?.stateStore,
     phase: "up",
-    telemetryClient: new NoopTelemetryClient(),
+    noTrack: true,
     local: defaultOptions.local,
   });
 

package/src/test/vitest.ts

@@ -8,7 +8,6 @@ import {
   FileSystemStateStore,
   SQLiteStateStore,
 } from "../state/index.ts";
-import { NoopTelemetryClient } from "../util/telemetry/client.ts";
 import type { TestOptions } from "./options.ts";
 
 /**
@@ -132,7 +131,7 @@ export function test(
     scopeName: `${defaultOptions.prefix ? `${defaultOptions.prefix}-` : ""}${path.basename(meta.filename)}`,
     stateStore: defaultOptions?.stateStore,
     phase: "up",
-    telemetryClient: new NoopTelemetryClient(),
+    noTrack: true,
     quiet: defaultOptions.quiet,
     password: process.env.ALCHEMY_PASSWORD,
     local: defaultOptions.local,

package/src/util/diff.ts

@@ -0,0 +1,14 @@
+import { isDeepStrictEqual } from "node:util";
+
+/**
+ * Returns an array of keys in `b` that are different from `a`.
+ */
+export const diff = <T>(a: T, b: NoInfer<T>) => {
+  const keys: (keyof T)[] = [];
+  for (const key in a) {
+    if (!isDeepStrictEqual(a[key], b[key])) {
+      keys.push(key);
+    }
+  }
+  return keys;
+};

package/src/util/telemetry.ts

@@ -0,0 +1,297 @@
+import envPaths from "env-paths";
+import { exec } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "pathe";
+import pkg from "../../package.json" with { type: "json" };
+import type { Phase } from "../alchemy.ts";
+import { Scope } from "../scope.ts";
+import { logger } from "./logger.ts";
+import { memoize } from "./memoize.ts";
+
+export const CONFIG_PATH = path.join(os.homedir(), ".alchemy", "id");
+export const CONFIG_PATH_LEGACY = path.join(
+  envPaths("alchemy", { suffix: "" }).config,
+  "id",
+);
+
+export const TELEMETRY_DISABLED =
+  !!process.env.ALCHEMY_TELEMETRY_DISABLED || !!process.env.DO_NOT_TRACK;
+
+export const TELEMETRY_API_URL =
+  process.env.ALCHEMY_TELEMETRY_API_URL ?? "https://telemetry.alchemy.run";
+export const SUPPRESS_TELEMETRY_ERRORS =
+  !!process.env.ALCHEMY_TELEMETRY_SUPPRESS_ERRORS;
+
+async function getOrCreateUserId() {
+  async function readUserId(path: string) {
+    try {
+      return (await readFile(path, "utf-8")).trim();
+    } catch {
+      return null;
+    }
+  }
+
+  const id = await readUserId(CONFIG_PATH);
+  if (id) {
+    return id;
+  }
+
+  const legacyId = await readUserId(CONFIG_PATH_LEGACY);
+
+  try {
+    const id = legacyId ?? crypto.randomUUID();
+    await mkdir(path.dirname(CONFIG_PATH), { recursive: true });
+    await writeFile(CONFIG_PATH, id);
+    if (!legacyId) {
+      console.warn(
+        [
+          "Attention: To help improve Alchemy, we collect anonymous usage, performance, and error data.",
+          "You can opt out by setting the ALCHEMY_TELEMETRY_DISABLED or DO_NOT_TRACK environment variable to a truthy value.",
+        ].join("\n"),
+      );
+    }
+    return id;
+  } catch {
+    return null;
+  }
+}
+
+async function getRootCommitHash() {
+  return new Promise<string | null>((resolve) => {
+    exec("git rev-list --max-parents=0 HEAD", (err, stdout) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+async function getGitOriginUrlHash() {
+  return new Promise<string | null>((resolve) => {
+    exec("git config --get remote.origin.url", (err, stdout) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(hashString(stdout.trim()));
+    });
+  });
+}
+
+async function getBranchName() {
+  return new Promise<string | null>((resolve) => {
+    exec("git rev-parse --abbrev-ref HEAD", (err, stdout) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+function getRuntime() {
+  if (globalThis.Bun) return { name: "bun", version: Bun.version };
+  // @ts-expect-error
+  if (globalThis.Deno)
+    // @ts-expect-error
+    return { name: "deno", version: Deno.version?.deno ?? null };
+  // @ts-expect-error
+  if (globalThis.EdgeRuntime) return { name: "workerd", version: null };
+  if (globalThis.process?.versions?.node)
+    return { name: "node", version: process.versions.node };
+  return { name: null, version: null };
+}
+
+const PROVIDERS = [
+  { env: "GITHUB_ACTIONS", provider: "GitHub Actions", isCI: true },
+  { env: "GITLAB_CI", provider: "GitLab CI", isCI: true },
+  { env: "CIRCLECI", provider: "CircleCI", isCI: true },
+  { env: "JENKINS_URL", provider: "Jenkins", isCI: true },
+  { env: "TRAVIS", provider: "Travis CI", isCI: true },
+  { env: "NOW_BUILDER", provider: "Vercel", isCI: true },
+  { env: "VERCEL", provider: "Vercel", isCI: false },
+] as const;
+
+function getEnvironment() {
+  for (const provider of PROVIDERS) {
+    if (process.env[provider.env]) {
+      return {
+        provider: provider.provider,
+        isCI: provider.isCI,
+      };
+    }
+  }
+  return {
+    provider: null,
+    isCI: !!process.env.CI,
+  };
+}
+
+export const collectData = memoize(async (): Promise<GenericTelemetryData> => {
+  const [
+    userId,
+    rootCommitHash,
+    gitOriginUrlHash,
+    branchHash,
+    runtime,
+    environment,
+  ] = await Promise.all([
+    getOrCreateUserId(),
+    getRootCommitHash(),
+    getGitOriginUrlHash(),
+    getBranchName().then(hashString),
+    getRuntime(),
+    getEnvironment(),
+  ]);
+  return {
+    userId: userId ?? "",
+    sessionId: crypto.randomUUID(),
+    platform: os.platform(),
+    osVersion: os.release(),
+    arch: os.arch(),
+    cpus: os.cpus().length,
+    memory: Math.round(os.totalmem() / 1024 / 1024),
+    rootCommitHash: rootCommitHash ?? "",
+    gitOriginUrl: gitOriginUrlHash ?? "",
+    gitBranchHash: branchHash ?? "",
+    runtime: runtime.name ?? "",
+    runtimeVersion: runtime.version ?? "",
+    ciProvider: environment.provider ?? "",
+    isCI: environment.isCI,
+    alchemyVersion: pkg.version,
+  };
+});
+
+export type GenericTelemetryData = {
+  userId: string;
+  sessionId: string;
+  platform: string;
+  osVersion: string;
+  arch: string;
+  cpus: number;
+  memory: number;
+  rootCommitHash: string;
+  gitOriginUrl: string;
+  gitBranchHash: string;
+  runtime: string;
+  runtimeVersion: string;
+  ciProvider: string;
+  isCI: boolean;
+  alchemyVersion: string;
+};
+
+export type ErrorData = {
+  errorTag: string;
+  errorMessage: string;
+  errorStack: string;
+};
+
+export type CliTelemetryData = {
+  command: string;
+  event: "cli.start" | "cli.success" | "cli.error";
+};
+
+export type ResourceTelemetryData = {
+  phase: Phase;
+  event:
+    | "resource.start"
+    | "resource.success"
+    | "resource.error"
+    | "resource.skip"
+    | "resource.read";
+  resource: string;
+  status:
+    | "creating"
+    | "created"
+    | "updating"
+    | "updated"
+    | "deleting"
+    | "deleted"
+    | "unknown";
+  duration: number;
+  replaced: boolean;
+};
+
+export type StateStoreTelemetryData = {
+  event:
+    | "statestore.init"
+    | "statestore.deinit"
+    | "statestore.list"
+    | "statestore.count"
+    | "statestore.get"
+    | "statestore.getBatch"
+    | "statestore.all"
+    | "statestore.set"
+    | "statestore.delete";
+  stateStore: string;
+  duration: number;
+};
+
+export type AlchemyTelemetryData = {
+  event: "alchemy.start" | "alchemy.success" | "alchemy.error";
+  duration: number;
+};
+
+export async function createAndSendEvent(
+  data:
+    | CliTelemetryData
+    | ResourceTelemetryData
+    | StateStoreTelemetryData
+    | AlchemyTelemetryData,
+  error?: Error,
+) {
+  if (Scope.getScope()?.noTrack || TELEMETRY_DISABLED) {
+    return;
+  }
+  try {
+    const eventData = {
+      ...data,
+      ...("duration" in data
+        ? { duration: Math.round(data.duration * 1000) }
+        : {}),
+      ...(await collectData()),
+      ...serializeError(error),
+    };
+    await fetch(TELEMETRY_API_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(eventData),
+    });
+  } catch (error) {
+    if (!SUPPRESS_TELEMETRY_ERRORS) {
+      logger.warn("Failed to send telemetry event:", error);
+    }
+  }
+}
+
+async function hashString(input: string | null): Promise<string | null> {
+  if (input == null) {
+    return null;
+  }
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hashBuffer), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
+function serializeError(error: Error | undefined) {
+  if (error instanceof Error) {
+    return {
+      errorTag: error.name ?? "",
+      errorMessage: error.message?.replaceAll(os.homedir(), "~") ?? "", // redact home directory
+      errorStack: error.stack?.replaceAll(os.homedir(), "~") ?? "",
+    };
+  }
+  return {
+    errorTag: "",
+    errorMessage: "",
+    errorStack: "",
+  };
+}

package/templates/tanstack-start/.cta.json

@@ -0,0 +1,13 @@
+{
+  "projectName": "@alchemy.run/tanstack-start-template",
+  "mode": "file-router",
+  "typescript": true,
+  "tailwind": true,
+  "packageManager": "bun",
+  "git": true,
+  "version": 1,
+  "framework": "react-cra",
+  "chosenAddOns": [
+    "start"
+  ]
+}