alchemy 2.0.0-beta.17 → 2.0.0-beta.19

package/src/GitHub/index.ts

@@ -3,4 +3,5 @@ export * from "./Comment.ts";
 export { GitHubCredentials, fromEnv, fromToken } from "./Credentials.ts";
 export * from "./Providers.ts";
 export * from "./Secret.ts";
+export * from "./Secrets.ts";
 export * from "./Variable.ts";

package/src/Output.ts

@@ -353,7 +353,8 @@ function proxy(self: any): any {
       prop === ExprSymbol || prop === inspect ? true : prop in self,
     get: (target, prop) =>
       prop === Symbol.toPrimitive
-        ? (hint: string) => (hint === "string" ? self.toString() : self)
+        ? (hint: string) =>
+            hint === "number" ? Number.NaN : self.toString()
         : prop === ExprSymbol
           ? self
           : prop === inspect

package/src/Plan.ts

@@ -397,7 +397,7 @@ export const make = <A>(
     const resourceGraph = Object.fromEntries(
       (yield* Effect.all(
         resources.map(
-          Effect.fn(function* (resource) {
+          Effect.fn("plan.diff.resource")(function* (resource) {
             const provider = yield* findProviderByType(resource.Type);
             const id = resource.LogicalId;
             const fqn = resource.FQN;
@@ -723,8 +723,7 @@ export const make = <A>(
     const deletions = Object.fromEntries(
       (yield* Effect.all(
         (yield* state.list({ stack: stackName, stage: stage })).map(
-          Effect.fn(function* (fqn) {
-            // Check if this FQN is in the new resources
+          Effect.fn("plan.diff.deletion")(function* (fqn) {
             if (newResourceFqns.has(fqn)) {
               return;
             }
@@ -805,7 +804,17 @@ export const make = <A>(
       deletions,
       output: stack.output,
     } satisfies Plan<A> as Plan<A>;
-  }).pipe(ensureArtifactStore);
+  }).pipe(
+    ensureArtifactStore,
+    Effect.withSpan("plan.make", {
+      attributes: {
+        "alchemy.stack": stack.name,
+        "alchemy.stage": stack.stage,
+        "alchemy.resources.count": Object.keys(stack.resources).length,
+        "alchemy.force": !!options.force,
+      },
+    }),
+  );
 
 const providePlanScope =
   (fqn: string, instanceId: string) =>

package/src/Resource.ts

@@ -3,7 +3,7 @@ import * as Option from "effect/Option";
 import { pipeArguments, type Pipeable } from "effect/Pipeable";
 import { SingleShotGen } from "effect/Utils";
 import { toFqn } from "./FQN.ts";
-import type { Input } from "./Input.ts";
+import type { Input, InputProps } from "./Input.ts";
 import { CurrentNamespace, type NamespaceNode } from "./Namespace.ts";
 import * as Output from "./Output.ts";
 import { Provider } from "./Provider.ts";
@@ -33,7 +33,7 @@ export type ResourceConstructor<R extends ResourceLike, Req = never> = {
   ): Effect.Effect<R, never, Req>;
   <PropsReq = never>(
     id: string,
-    props: Effect.Effect<Input<R["Props"]>, never, PropsReq>,
+    props: Effect.Effect<InputProps<R["Props"]>, never, PropsReq>,
   ): Effect.Effect<R, never, PropsReq | Req>;
 };
 

package/src/Telemetry/Attributes.ts

@@ -0,0 +1,216 @@
+import { exec } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+
+import * as Effect from "effect/Effect";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+const ALCHEMY_DIR = nodePath.join(os.homedir(), ".alchemy");
+const ID_PATH = nodePath.join(ALCHEMY_DIR, "id");
+const DISABLED_PATH = nodePath.join(ALCHEMY_DIR, "telemetry-disabled");
+
+/**
+ * OTel resource attributes describing the user, project, runtime, and
+ * environment running the alchemy CLI. Computed once per process and
+ * attached to every span and metric exported by `TelemetryLive`.
+ */
+export interface TelemetryAttributes {
+  readonly "alchemy.user.id": string;
+  readonly "alchemy.session.id": string;
+  readonly "alchemy.version": string;
+  readonly "alchemy.git.root_commit": string;
+  readonly "alchemy.git.origin_hash": string;
+  readonly "alchemy.git.branch_hash": string;
+  readonly "alchemy.runtime.name": string;
+  readonly "alchemy.runtime.version": string;
+  readonly "alchemy.ci.provider": string;
+  readonly "alchemy.ci": boolean;
+  readonly "host.arch": string;
+  readonly "os.type": string;
+  readonly "os.version": string;
+  readonly "host.cpus": number;
+  readonly "host.memory_mb": number;
+}
+
+const tryRead = (path: string): Effect.Effect<string | null> =>
+  Effect.tryPromise({
+    try: () => fs.readFile(path, "utf-8").then((s) => s.trim()),
+    catch: () => null as never,
+  }).pipe(Effect.catch(() => Effect.succeed(null)));
+
+const sha256Hex = (input: string): string =>
+  crypto.createHash("sha256").update(input).digest("hex");
+
+const hashStringOrEmpty = (input: string | null): string =>
+  input == null || input === "" ? "" : sha256Hex(input);
+
+const execCapture = (cmd: string): Effect.Effect<string | null> =>
+  Effect.callback<string | null>((resume) => {
+    exec(cmd, { timeout: 1500 }, (err, stdout) => {
+      if (err) {
+        resume(Effect.succeed(null));
+        return;
+      }
+      resume(Effect.succeed(stdout.toString().trim()));
+    });
+  });
+
+const getOrCreateUserId: Effect.Effect<string> = Effect.gen(function* () {
+  const existing = yield* tryRead(ID_PATH);
+  if (existing) return existing;
+
+  const id = crypto.randomUUID();
+  yield* Effect.tryPromise({
+    try: async () => {
+      await fs.mkdir(ALCHEMY_DIR, { recursive: true });
+      await fs.writeFile(ID_PATH, id);
+    },
+    catch: () => null as never,
+  }).pipe(Effect.catch(() => Effect.void));
+  return id;
+});
+
+const getRootCommitHash: Effect.Effect<string | null> = execCapture(
+  process.platform === "win32"
+    ? `git rev-list --max-parents=0 HEAD | ForEach-Object { if (-not (git cat-file -p $_ | Select-String "^parent ")) { $_ } }`
+    : `git rev-list --max-parents=0 HEAD | xargs -r -I{} sh -c 'git cat-file -p {} | grep -q "^parent " || echo {}'`,
+);
+
+const getGitOriginUrl: Effect.Effect<string | null> = execCapture(
+  "git config --get remote.origin.url",
+);
+
+const getBranchName: Effect.Effect<string | null> = execCapture(
+  "git rev-parse --abbrev-ref HEAD",
+);
+
+const getRuntime = (): { name: string; version: string } => {
+  const g = globalThis as unknown as {
+    Bun?: { version: string };
+    Deno?: { version?: { deno?: string } };
+  };
+  if (typeof g.Bun !== "undefined") {
+    return { name: "bun", version: g.Bun.version };
+  }
+  if (typeof g.Deno !== "undefined") {
+    return { name: "deno", version: g.Deno.version?.deno ?? "" };
+  }
+  if (globalThis.process?.versions?.node) {
+    return { name: "node", version: process.versions.node };
+  }
+  return { name: "", version: "" };
+};
+
+const CI_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: "BUILDKITE", provider: "Buildkite", isCI: true },
+  { env: "NOW_BUILDER", provider: "Vercel", isCI: true },
+  { env: "VERCEL", provider: "Vercel", isCI: false },
+] as const;
+
+const getCIEnvironment = (): { provider: string; isCI: boolean } => {
+  for (const p of CI_PROVIDERS) {
+    if (process.env[p.env]) {
+      return { provider: p.provider, isCI: p.isCI };
+    }
+  }
+  return { provider: "", isCI: !!process.env.CI };
+};
+
+const TELEMETRY_DISABLED_ENV = (): boolean =>
+  !!process.env.ALCHEMY_TELEMETRY_DISABLED ||
+  !!process.env.DO_NOT_TRACK ||
+  !!process.env.NO_TRACK;
+
+/**
+ * `true` if telemetry is disabled via environment variable
+ * (`DO_NOT_TRACK`, `NO_TRACK`, `ALCHEMY_TELEMETRY_DISABLED`) or via a
+ * persisted opt-out file at `~/.alchemy/telemetry-disabled`.
+ */
+export const isTelemetryDisabled: Effect.Effect<boolean> = Effect.gen(
+  function* () {
+    if (TELEMETRY_DISABLED_ENV()) return true;
+    const persisted = yield* tryRead(DISABLED_PATH);
+    return persisted === "true";
+  },
+);
+
+/**
+ * Persists an opt-out so future invocations skip telemetry without needing
+ * an env var.
+ */
+export const setTelemetryDisabled: Effect.Effect<void> = Effect.tryPromise({
+  try: async () => {
+    await fs.mkdir(ALCHEMY_DIR, { recursive: true });
+    await fs.writeFile(DISABLED_PATH, "true");
+  },
+  catch: () => null as never,
+}).pipe(Effect.catch(() => Effect.void));
+
+export const setTelemetryEnabled: Effect.Effect<void> = Effect.tryPromise({
+  try: () => fs.rm(DISABLED_PATH, { force: true }),
+  catch: () => null as never,
+}).pipe(Effect.catch(() => Effect.void));
+
+const collectAttributesUncached: Effect.Effect<TelemetryAttributes> =
+  Effect.gen(function* () {
+    const [userId, rootCommit, originUrl, branch] = yield* Effect.all(
+      [
+        getOrCreateUserId,
+        getRootCommitHash,
+        getGitOriginUrl,
+        getBranchName,
+      ] as const,
+      { concurrency: "unbounded" },
+    );
+
+    const runtime = getRuntime();
+    const ci = getCIEnvironment();
+
+    return {
+      "alchemy.user.id": userId,
+      "alchemy.session.id":
+        process.env.ALCHEMY_TELEMETRY_SESSION_ID ?? crypto.randomUUID(),
+      "alchemy.version": packageJson.version,
+      "alchemy.git.root_commit": rootCommit ?? "",
+      "alchemy.git.origin_hash": hashStringOrEmpty(originUrl),
+      "alchemy.git.branch_hash": hashStringOrEmpty(branch),
+      "alchemy.runtime.name": runtime.name,
+      "alchemy.runtime.version": runtime.version,
+      "alchemy.ci.provider": ci.provider,
+      "alchemy.ci": ci.isCI,
+      "host.arch": os.arch(),
+      "os.type": os.platform(),
+      "os.version": os.release(),
+      "host.cpus": os.cpus().length,
+      "host.memory_mb": Math.round(os.totalmem() / 1024 / 1024),
+    } satisfies TelemetryAttributes;
+  });
+
+let cachedAttrs: TelemetryAttributes | undefined;
+
+/**
+ * Resolves the {@link TelemetryAttributes} for the current process. Cached
+ * so file I/O and `git` invocations only run once per CLI invocation; every
+ * subsequent caller gets the same record (and therefore the same session
+ * id).
+ */
+export const collectAttributes: Effect.Effect<TelemetryAttributes> =
+  Effect.suspend(() =>
+    cachedAttrs !== undefined
+      ? Effect.succeed(cachedAttrs)
+      : collectAttributesUncached.pipe(
+          Effect.tap((a) =>
+            Effect.sync(() => {
+              cachedAttrs = a;
+            }),
+          ),
+        ),
+  );

package/src/Telemetry/Layer.ts

@@ -0,0 +1,65 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as OtlpMetrics from "effect/unstable/observability/OtlpMetrics";
+import * as OtlpSerialization from "effect/unstable/observability/OtlpSerialization";
+import * as OtlpTracer from "effect/unstable/observability/OtlpTracer";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+import { collectAttributes, isTelemetryDisabled } from "./Attributes.ts";
+
+const TRACES_URL = "https://otel.alchemy.run/v1/traces";
+const METRICS_URL = "https://otel.alchemy.run/v1/metrics";
+
+const SERVICE_NAME = "alchemy-cli";
+
+const buildOtlpLayer = (
+  attrs: Record<string, unknown>,
+): Layer.Layer<never, never, never> => {
+  const resource = {
+    serviceName: SERVICE_NAME,
+    serviceVersion: packageJson.version,
+    attributes: attrs,
+  };
+
+  // Short export intervals so even sub-second CLI invocations flush at
+  // least one batch before the process exits.
+  const tracer = OtlpTracer.layer({
+    url: TRACES_URL,
+    resource,
+    exportInterval: "1 second",
+  });
+  const metrics = OtlpMetrics.layer({
+    url: METRICS_URL,
+    resource,
+    exportInterval: "1 second",
+  });
+
+  return Layer.mergeAll(tracer, metrics).pipe(
+    Layer.provide(OtlpSerialization.layerJson),
+    Layer.provide(FetchHttpClient.layer),
+  );
+};
+
+/**
+ * The CLI's telemetry layer. Builds an OTLP HTTP exporter that ships spans
+ * to {@link TRACES_URL} and metrics to {@link METRICS_URL}, attaching
+ * {@link collectAttributes} as resource-level attributes so every signal
+ * carries user/project/runtime context.
+ *
+ * If the user has opted out (via `DO_NOT_TRACK`, `NO_TRACK`,
+ * `ALCHEMY_TELEMETRY_DISABLED`, or `~/.alchemy/telemetry-disabled`), this
+ * resolves to {@link Layer.empty}. Effect's default `Tracer` is a no-op,
+ * so all `withSpan`/`Effect.fn` instrumentation in core stays free.
+ */
+export const TelemetryLive: Layer.Layer<never, never, never> =
+  Layer.unwrap(
+    Effect.gen(function* () {
+      if (yield* isTelemetryDisabled) {
+        return Layer.empty;
+      }
+      const attrs = yield* collectAttributes;
+      return buildOtlpLayer(attrs as unknown as Record<string, unknown>);
+    }),
+  );

package/src/Telemetry/Metrics.ts

@@ -0,0 +1,101 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Metric from "effect/Metric";
+
+/**
+ * Counter for resource lifecycle operations. Tagged per call with
+ * `resource_type`, `op` (`precreate`/`create`/`update`/`delete`/`read`),
+ * and `status` (`success`/`error`).
+ */
+export const resourceCounter = Metric.counter("alchemy.resource.operations", {
+  description:
+    "Number of resource lifecycle operations dispatched by alchemy apply.",
+  incremental: true,
+});
+
+/**
+ * Histogram of how long each lifecycle operation takes.
+ */
+export const resourceDuration = Metric.timer("alchemy.resource.duration", {
+  description:
+    "Wall-clock duration of resource lifecycle operations dispatched by alchemy apply.",
+});
+
+/**
+ * Counter for CLI command invocations.
+ */
+export const cliCounter = Metric.counter("alchemy.cli.invocations", {
+  description: "Number of alchemy CLI command invocations.",
+  incremental: true,
+});
+
+/**
+ * Wraps a resource lifecycle Effect to record a counter + timer entry,
+ * tagged with `resource_type`, `op`, and `status` (`success`/`error`).
+ *
+ * Usage:
+ * ```ts
+ * provider.create(input).pipe(recordResourceOp(node.resource.Type, "create"))
+ * ```
+ */
+export const recordResourceOp =
+  (resourceType: string, op: ResourceOp) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.suspend(() => {
+      const startNs = process.hrtime.bigint();
+      const baseAttrs = { resource_type: resourceType, op } as const;
+      return self.pipe(
+        Effect.onExit((exit) =>
+          recordOutcome(
+            baseAttrs,
+            Exit.isSuccess(exit) ? "success" : "error",
+            elapsed(startNs),
+          ),
+        ),
+      );
+    });
+
+/**
+ * Wraps a CLI command Effect to bump {@link cliCounter} with the
+ * outcome (`success`/`error`).
+ */
+export const recordCli =
+  (command: string) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    self.pipe(
+      Effect.onExit((exit) =>
+        Metric.update(
+          Metric.withAttributes(cliCounter, {
+            command,
+            status: Exit.isSuccess(exit) ? "success" : "error",
+          }),
+          1,
+        ),
+      ),
+    );
+
+export type ResourceOp =
+  | "precreate"
+  | "create"
+  | "update"
+  | "delete"
+  | "read";
+
+const elapsed = (startNs: bigint): Duration.Duration =>
+  Duration.nanos(process.hrtime.bigint() - startNs);
+
+const recordOutcome = (
+  baseAttrs: { resource_type: string; op: ResourceOp },
+  status: "success" | "error",
+  duration: Duration.Duration,
+): Effect.Effect<void> => {
+  const attrs = { ...baseAttrs, status };
+  return Effect.all(
+    [
+      Metric.update(Metric.withAttributes(resourceCounter, attrs), 1),
+      Metric.update(Metric.withAttributes(resourceDuration, attrs), duration),
+    ],
+    { discard: true },
+  );
+};