alchemy 0.25.0 → 0.26.0

package/src/util/logger.ts

@@ -0,0 +1,17 @@
+import { Scope } from "../scope.ts";
+import type { LoggerApi } from "./cli.tsx";
+
+export const logger = new Proxy({} as LoggerApi, {
+  get: (_, prop: keyof LoggerApi) => {
+    const logger =
+      Scope.get()?.logger ??
+      ({
+        log: console.log,
+        error: console.error,
+        warn: console.warn,
+        task: () => {},
+        exit: () => {},
+      } as LoggerApi);
+    return logger[prop].bind(logger);
+  },
+});

package/src/util/retry.ts

@@ -22,7 +22,6 @@ export async function withExponentialBackoff<T>(
     try {
       return await operation();
     } catch (error: any) {
-      console.log(error.message);
       attempt++;
       if (attempt >= maxAttempts || !isRetryable(error)) {
         throw error;

package/src/util/safe-fetch.ts

@@ -1,4 +1,5 @@
 import type { Agent } from "undici";
+import { logger } from "./logger.ts";
 
 export async function safeFetch(
   url: string | URL | Request,
@@ -25,7 +26,7 @@ export async function safeFetch(
         throw err;
       }
 
-      console.warn(`Retry ${attempt}/${retries} for ${url}: ${err.code}`);
+      logger.warn(`Retry ${attempt}/${retries} for ${url}: ${err.code}`);
       await new Promise((r) => setTimeout(r, 250 * attempt)); // exponential backoff
     }
   }

package/src/util/telemetry/client.ts

@@ -0,0 +1,127 @@
+import os from "node:os";
+import type { Phase } from "../../alchemy.ts";
+import { INGEST_URL, TELEMETRY_DISABLED } from "./constants.ts";
+import { context } from "./context.ts";
+import type { Telemetry } from "./types.ts";
+
+export interface TelemetryClientOptions {
+  sessionId: string;
+  phase: Phase;
+  enabled: boolean;
+  quiet: boolean;
+}
+
+export interface ITelemetryClient {
+  ready: Promise<void>;
+  record(event: Telemetry.EventInput): void;
+  finalize(): Promise<void>;
+}
+
+export class NoopTelemetryClient implements ITelemetryClient {
+  ready = Promise.resolve();
+  record(_: Telemetry.EventInput) {}
+  finalize() {
+    return Promise.resolve();
+  }
+}
+
+export class TelemetryClient implements ITelemetryClient {
+  ready: Promise<void>;
+
+  private events: Telemetry.Event[] = [];
+  private context?: Telemetry.Context;
+
+  constructor(readonly options: TelemetryClientOptions) {
+    this.ready = this.init();
+  }
+
+  private async init() {
+    const now = Date.now();
+    this.context = await context({
+      sessionId: this.options.sessionId,
+      phase: this.options.phase,
+    });
+    this.record(
+      {
+        event: "app.start",
+      },
+      now,
+    );
+  }
+
+  record(event: Telemetry.EventInput, timestamp = Date.now()) {
+    if (!this.context) {
+      throw new Error("Context not initialized");
+    }
+    const payload = {
+      ...event,
+      error: this.serializeError(event.error),
+      context: this.context,
+      timestamp,
+    } as Telemetry.Event;
+    this.events.push(payload);
+  }
+
+  private serializeError(
+    error: Telemetry.ErrorInput | undefined,
+  ): Telemetry.SerializedError | undefined {
+    if (!error) {
+      return undefined;
+    }
+    if (error instanceof Error) {
+      return {
+        ...error, // include additional properties from error object
+        name: error.name,
+        message: error.message,
+        // TODO: maybe redact more of the stack trace?
+        stack: error.stack?.replaceAll(os.homedir(), "~"), // redact home directory
+      };
+    }
+    return error;
+  }
+
+  async finalize() {
+    await this.send(this.events).catch((error) => {
+      if (!this.options.quiet) {
+        console.warn(error);
+      }
+    });
+  }
+
+  private async send(events: Telemetry.Event[]) {
+    if (events.length === 0) {
+      return;
+    }
+    const response = await fetch(INGEST_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(events),
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to send telemetry: ${response.status} ${response.statusText} - ${await response.text()}`,
+      );
+    }
+  }
+
+  static create({
+    phase,
+    enabled,
+    quiet,
+  }: Omit<TelemetryClientOptions, "sessionId">): ITelemetryClient {
+    if (!enabled || TELEMETRY_DISABLED) {
+      if (!quiet) {
+        console.warn("[Alchemy] Telemetry is disabled.");
+      }
+      return new NoopTelemetryClient();
+    }
+    return new TelemetryClient({
+      sessionId: crypto.randomUUID(),
+      phase,
+      enabled,
+      quiet,
+    });
+  }
+}

package/src/util/telemetry/constants.ts

@@ -0,0 +1,13 @@
+import { createXdgAppPaths } from "../xdg-paths.js";
+
+const xdg = createXdgAppPaths("alchemy");
+
+export const CONFIG_DIR = xdg.config();
+
+export const TELEMETRY_DISABLED =
+  !!process.env.ALCHEMY_TELEMETRY_DISABLED || !!process.env.DO_NOT_TRACK;
+
+// TODO(sam): replace with permanent URL
+export const INGEST_URL =
+  process.env.ALCHEMY_TELEMETRY_URL ??
+  "https://5fbb5d5ca66f44b685468684cfceb325.pipelines.cloudflare.com";

package/src/util/telemetry/context.ts

@@ -0,0 +1,154 @@
+import { exec } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import { join } from "node:path";
+import pkg from "../../../package.json" with { type: "json" };
+import type { Phase } from "../../alchemy.ts";
+import { CONFIG_DIR } from "./constants.ts";
+import type { Telemetry } from "./types.ts";
+
+async function userId() {
+  const path = join(CONFIG_DIR, "id");
+
+  try {
+    return (await readFile(path, "utf-8")).trim();
+  } catch {}
+
+  try {
+    await mkdir(CONFIG_DIR, { recursive: true });
+  } catch {}
+
+  const id = crypto.randomUUID();
+  try {
+    await writeFile(path, id);
+    console.warn(
+      [
+        "Attention: To help improve Alchemy, we now 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"),
+    );
+  } catch {
+    return null;
+  }
+
+  return id;
+}
+
+function projectId() {
+  return new Promise<string | null>((resolve) => {
+    exec("git rev-list --max-parents=0 HEAD", (err, stdout) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+function system(): Telemetry.Context["system"] {
+  return {
+    platform: os.platform(),
+    osVersion: os.release(),
+    arch: os.arch(),
+    cpus: os.cpus().length,
+    memory: os.totalmem() / 1024 / 1024,
+  };
+}
+
+declare global {
+  var Deno:
+    | {
+        version: {
+          deno: string;
+        };
+      }
+    | undefined;
+  var EdgeRuntime: Record<string, unknown> | undefined;
+}
+
+const RUNTIMES = [
+  {
+    name: "bun",
+    detect: () => !!globalThis.Bun,
+    version: () => globalThis.Bun?.version,
+  },
+  {
+    name: "deno",
+    detect: () => !!globalThis.Deno,
+    version: () => globalThis.Deno?.version?.deno,
+  },
+  {
+    name: "workerd",
+    detect: () => !!globalThis.EdgeRuntime,
+    version: () => null,
+  },
+  {
+    name: "node",
+    detect: () => !!globalThis.process?.versions?.node,
+    version: () => process.versions.node,
+  },
+] as const;
+
+function runtime(): Telemetry.Context["runtime"] {
+  for (const runtime of RUNTIMES) {
+    if (runtime.detect()) {
+      return {
+        name: runtime.name,
+        version: runtime.version() ?? null,
+      };
+    }
+  }
+  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 },
+];
+
+function environment(): Telemetry.Context["environment"] {
+  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 async function context(input: {
+  sessionId: string;
+  phase: Phase;
+}): Promise<Telemetry.Context> {
+  const env = environment();
+  const [uid, pid] = await Promise.all([
+    env.isCI ? null : userId(),
+    projectId(),
+  ]);
+  return {
+    userId: uid,
+    projectId: pid,
+    sessionId: input.sessionId,
+    system: system(),
+    runtime: runtime(),
+    environment: env,
+    alchemy: {
+      version: pkg.version,
+      phase: input.phase,
+    },
+  };
+}

package/src/util/telemetry/index.ts

@@ -0,0 +1,2 @@
+export * from "./client.ts";
+export * from "./types.ts";

package/src/util/telemetry/types.ts

@@ -0,0 +1,83 @@
+import type { Phase } from "../../alchemy.ts";
+
+export namespace Telemetry {
+  export interface Context {
+    /** Random UUID generated once per machine and stored in XDG config directory (e.g. `~/Library/Preferences/alchemy` on Mac). Null for CI environments. */
+    userId: string | null;
+    /** Root commit hash for the git repository. Anonymous, stable identifier for anyone using git. */
+    projectId: string | null;
+    /** UUID generated once per application run. */
+    sessionId: string;
+
+    system: {
+      platform: string;
+      osVersion: string;
+      arch: string;
+      cpus: number;
+      memory: number;
+    };
+
+    runtime: {
+      name: string | null;
+      version: string | null;
+    };
+
+    environment: {
+      provider: string | null;
+      isCI: boolean;
+    };
+
+    alchemy: {
+      version: string;
+      phase: Phase;
+    };
+  }
+
+  export interface BaseEvent {
+    event: string;
+    context: Context;
+    timestamp: number;
+  }
+
+  export interface SerializedError {
+    name?: string;
+    message: string;
+    stack?: string;
+  }
+
+  export type ErrorInput = Error | SerializedError;
+
+  export interface AppEvent extends BaseEvent {
+    event: "app.start" | "app.success" | "app.error";
+    elapsed?: number;
+    error?: SerializedError;
+  }
+
+  export interface ResourceEvent extends BaseEvent {
+    event:
+      | "resource.start"
+      | "resource.success"
+      | "resource.error"
+      | "resource.skip"
+      | "resource.read";
+    resource: string;
+    status?:
+      | "creating"
+      | "created"
+      | "updating"
+      | "updated"
+      | "deleting"
+      | "deleted";
+    elapsed?: number;
+    error?: SerializedError;
+    replaced?: boolean;
+  }
+
+  export type Event = AppEvent | ResourceEvent;
+  export type EventInput = (
+    | Omit<AppEvent, "context" | "timestamp" | "error">
+    | Omit<ResourceEvent, "context" | "timestamp" | "error">
+  ) & {
+    error?: ErrorInput;
+  };
+}

package/src/util/xdg-paths.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Vendored XDG Base Directory Specification implementation
+ * Provides cross-platform directory paths for config and state
+ */
+export function createXdgAppPaths(appName: string) {
+  const platform = process.platform;
+  const home = homedir();
+
+  function config(): string {
+    if (platform === "win32") {
+      return join(
+        process.env.LOCALAPPDATA || join(home, "AppData", "Local"),
+        appName,
+      );
+    } else if (platform === "darwin") {
+      return join(home, "Library", "Preferences", appName);
+    } else {
+      // Linux/Unix - follow XDG Base Directory Specification
+      const xdgConfigHome =
+        process.env.XDG_CONFIG_HOME || join(home, ".config");
+      return join(xdgConfigHome, appName);
+    }
+  }
+
+  function state(): string {
+    if (platform === "win32") {
+      return join(
+        process.env.LOCALAPPDATA || join(home, "AppData", "Local"),
+        appName,
+      );
+    } else if (platform === "darwin") {
+      return join(home, "Library", "Application Support", appName);
+    } else {
+      // Linux/Unix - follow XDG Base Directory Specification
+      const xdgStateHome =
+        process.env.XDG_STATE_HOME || join(home, ".local", "state");
+      return join(xdgStateHome, appName);
+    }
+  }
+
+  return {
+    config,
+    state,
+  };
+}

package/src/vercel/project.ts

@@ -1,6 +1,7 @@
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { isSecret, type Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
 import { createVercelApi, type VercelApi } from "./api.ts";
 
 type TargetEnvironment = "production" | "preview" | "development";
@@ -380,7 +381,7 @@ export const Project = Resource(
             await api.delete(`/projects/${this.output.id}`);
           }
         } catch (error) {
-          console.error("Error deleting project:", error);
+          logger.error("Error deleting project:", error);
         }
 
         return this.destroy();

package/src/web/astro.ts

@@ -8,6 +8,7 @@ import { StaticJsonFile } from "../fs/static-json-file.ts";
 import { StaticTextFile } from "../fs/static-text-file.ts";
 import { StaticTypeScriptFile } from "../fs/static-typescript-file.ts";
 import { Resource } from "../resource.ts";
+import { logger } from "../util/logger.ts";
 import { ShadcnUI } from "./shadcn.ts";
 
 const execAsync = promisify(exec);
@@ -208,7 +209,7 @@ export const AstroProject = Resource(
           }
         }
       } catch (error) {
-        console.error(`Error deleting project ${id}:`, error);
+        logger.error(`Error deleting project ${id}:`, error);
       }
       return this.destroy();
     }

package/src/web/shadcn.ts

@@ -6,6 +6,7 @@ import { Folder } from "../fs/folder.ts";
 import { StaticJsonFile } from "../fs/static-json-file.ts";
 import { StaticTypeScriptFile } from "../fs/static-typescript-file.ts";
 import { Resource } from "../resource.ts";
+import { logger } from "../util/logger.ts";
 import { ShadcnComponent } from "./shadcn-component.ts";
 
 const execAsync = promisify(exec);
@@ -127,7 +128,7 @@ export const ShadcnUI = Resource(
       // For a delete phase, we don't perform any action
       // as removing Shadcn UI would require removing many files
       // which could be destructive to the project
-      console.log(
+      logger.log(
         "Note: ShadcnUI delete phase does not remove installed components",
       );
 

package/src/web/vite.ts

@@ -6,6 +6,7 @@ import { Folder } from "../fs/folder.ts";
 import { StaticJsonFile } from "../fs/static-json-file.ts";
 import { StaticTypeScriptFile } from "../fs/static-typescript-file.ts";
 import { Resource } from "../resource.ts";
+import { logger } from "../util/logger.ts";
 import { rm } from "../util/rm.ts";
 import { ShadcnComponent } from "./shadcn-component.ts";
 import { TailwindConfig } from "./tailwind.ts";
@@ -147,7 +148,7 @@ export const ViteProject = Resource(
           await execAsync(`rm -rf ${props.name}`);
         }
       } catch (error) {
-        console.error(`Error deleting project ${id}:`, error);
+        logger.error(`Error deleting project ${id}:`, error);
       }
       return this.destroy();
     }
@@ -156,7 +157,7 @@ export const ViteProject = Resource(
       if (props.overwrite) {
         await modifyConfig(props);
       } else {
-        console.warn(
+        logger.warn(
           "ViteProject does not support updates - the project must be recreated to change the template",
         );
       }

package/src/web/vitepress/dependencies.ts

@@ -2,6 +2,7 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import type { Context } from "../../context.ts";
 import { Resource } from "../../resource.ts";
+import { logger } from "../../util/logger.ts";
 
 const execAsync = promisify(exec);
 
@@ -63,6 +64,6 @@ export async function installDependencies(
     .join(" ");
 
   const cmd = `bun add ${args.join(" ")} ${deps}`;
-  console.log(cmd);
+  logger.log(cmd);
   await execAsync(cmd, { cwd });
 }

package/src/web/vitepress/vitepress.ts

@@ -8,6 +8,7 @@ import { StaticJsonFile } from "../../fs/static-json-file.ts";
 import { StaticTextFile } from "../../fs/static-text-file.ts";
 import { StaticTypeScriptFile } from "../../fs/static-typescript-file.ts";
 import { Resource } from "../../resource.ts";
+import { logger } from "../../util/logger.ts";
 import { InstallDependencies, fixedDependencies } from "./dependencies.ts";
 
 const _execAsync = promisify(exec);
@@ -121,7 +122,7 @@ export const VitepressProject = Resource(
           }
         }
       } catch (error) {
-        console.error(`Error deleting VitePress project ${id}:`, error);
+        logger.error(`Error deleting VitePress project ${id}:`, error);
       }
       return this.destroy();
     }