alchemy 2.0.0-beta.30 → 2.0.0-beta.32

package/src/State/InMemoryState.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
 import type { ResourceState } from "./ResourceState.ts";
 import { State } from "./State.ts";
 
@@ -12,12 +13,17 @@ export const inMemoryState = (
     StackId,
     Record<StageId, Record<Fqn, ResourceState>>
   > = {},
-) => Layer.succeed(State, InMemoryService(initialState));
+) =>
+  Layer.effect(
+    State,
+    Effect.succeed(InMemoryService(initialState)).pipe(recordStateStoreInit),
+  );
 
 export const InMemoryService = (
   state: Record<StackId, Record<StageId, Record<Fqn, ResourceState>>> = {},
 ) =>
   State.of({
+    id: "inmemory",
     listStacks: () => Effect.succeed(Array.from(Object.keys(state))),
     listStages: (stack: string) =>
       Effect.succeed(

package/src/State/LocalState.ts

@@ -4,10 +4,12 @@ import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
 import { decodeFqn, encodeFqn } from "../FQN.ts";
+import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
 import { State, StateStoreError, type StateService } from "./State.ts";
 import { encodeState, reviveState } from "./StateEncoding.ts";
 
-export const localState = () => Layer.effect(State, makeLocalState());
+export const localState = () =>
+  Layer.effect(State, makeLocalState().pipe(recordStateStoreInit));
 
 export const makeLocalState = () =>
   Effect.gen(function* () {
@@ -54,6 +56,7 @@ export const makeLocalState = () =>
             .pipe(Effect.tap(() => Effect.sync(() => created.add(dir))));
 
     const state: StateService = {
+      id: "local",
       listStacks: () =>
         fs.readDirectory(stateDir).pipe(
           recover,

package/src/State/State.ts

@@ -21,6 +21,15 @@ export class State extends Context.Service<State, StateService>()(
  * for provider operations.
  */
 export interface StateService {
+  /**
+   * Stable identifier for the State store implementation, used for
+   * telemetry tagging (`alchemy.state_store.id`) so we can answer
+   * "which backends are people using" without hard-coding a closed
+   * union. Examples: `"local"`, `"inmemory"`, `"http"`,
+   * `"cloudflare-http"`. Third-party state stores should pick a short,
+   * stable, kebab-case slug.
+   */
+  readonly id: string;
   listStacks(): Effect.Effect<readonly string[], StateStoreError, never>;
   listStages(
     stack: string,

package/src/Tags.ts

@@ -7,7 +7,7 @@ export type Tags =
   | [string, string][]
   | { Key: string; Value: string }[];
 
-const normalizeTags = (tags: Tags) =>
+export const normalizeTags = (tags: Tags) =>
   Array.isArray(tags)
     ? Object.fromEntries(
         tags.map((tag) =>
@@ -16,6 +16,13 @@ const normalizeTags = (tags: Tags) =>
       )
     : tags;
 
+export const tagRecord = (tags: Tags | undefined): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(normalizeTags(tags ?? {})).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+
 export const hasTags = (expectedTags: Tags, tags: Tags | undefined) => {
   const actualTags = normalizeTags(tags ?? []);
   return Object.entries(normalizeTags(expectedTags)).every(

package/src/Telemetry/Metrics.ts

@@ -48,13 +48,28 @@ export const stateStoreCounter = Metric.counter(
 
 export type StateStoreOp = "deploy";
 
+/**
+ * Counter for State store layer construction. Tagged with `id` (the
+ * `StateService.id` slug) so we can answer "how many distinct projects
+ * are using each backend" from the corresponding `state_store.init`
+ * spans. Open-ended on purpose: third-party state stores get counted
+ * automatically by setting their `StateService.id`.
+ */
+export const stateStoreInitCounter = Metric.counter(
+  "alchemy.state_store.inits",
+  {
+    description: "Number of times a State store layer is constructed.",
+    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"))
+ * provider.reconcile(input).pipe(recordResourceOp(node.resource.Type, "create"))
  * ```
  */
 export const recordResourceOp =
@@ -113,6 +128,38 @@ export const recordStateStoreOp =
       ),
     );
 
+/**
+ * Wraps a State store construction Effect to:
+ *
+ * 1. Bump {@link stateStoreInitCounter} tagged with `id`.
+ * 2. Open a `state_store.init` span carrying
+ *    `alchemy.state_store.id` so Axiom (which can't query metric
+ *    datasets via APL) can group projects by backend.
+ *
+ * The `id` is read off the constructed `StateService.id` field, so any
+ * third-party state-store implementation gets tracked just by setting
+ * a stable slug there. Apply at every `Layer.effect(State, …)` site
+ * exactly once.
+ */
+export const recordStateStoreInit = <A extends { readonly id: string }, E, R>(
+  self: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  self.pipe(
+    Effect.tap((service) =>
+      Effect.all(
+        [
+          Metric.update(
+            Metric.withAttributes(stateStoreInitCounter, { id: service.id }),
+            1,
+          ),
+          Effect.annotateCurrentSpan("alchemy.state_store.id", service.id),
+        ],
+        { discard: true },
+      ),
+    ),
+    Effect.withSpan("state_store.init"),
+  );
+
 export type ResourceOp = "precreate" | "create" | "update" | "delete" | "read";
 
 const elapsed = (startNs: bigint): Duration.Duration =>

package/src/Test/Core.ts

@@ -1,17 +1,16 @@
 import { ConfigProvider } from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 
-import type { AlchemyContext } from "../AlchemyContext.ts";
-import { AlchemyContextLive } from "../AlchemyContext.ts";
+import { AdoptPolicy } from "../AdoptPolicy.ts";
+import { AlchemyContext, AlchemyContextLive } from "../AlchemyContext.ts";
 import { apply } from "../Apply.ts";
 import { provideFreshArtifactStore } from "../Artifacts.ts";
 import { AuthProviders } from "../Auth/AuthProvider.ts";
 import { withProfileOverride } from "../Auth/Profile.ts";
-import { LoggingCli } from "../Cli/LoggingCli.ts";
+import { TestCli } from "./TestCli.ts";
 import { deploy as _deploy } from "../Deploy.ts";
 import { destroy as _destroy } from "../Destroy.ts";
 import type { Input } from "../Input.ts";
@@ -41,17 +40,41 @@ export interface MakeOptions<ROut = any> {
   profile?: string;
   /** Default stage for deploy/destroy (default `"test"`). */
   stage?: string;
+  /**
+   * Engine-level adoption policy for this test run. When `true`, resources
+   * without prior state will be adopted from the cloud via `provider.read`
+   * (matching the CLI's `--adopt` flag). Defaults to `false`.
+   */
+  adopt?: boolean;
+  /**
+   * Run providers in local-dev mode (matching the CLI's `alchemy dev` flag).
+   * When `true`, resources like Cloudflare Workers run locally via workerd
+   * instead of being deployed to the cloud. When omitted, falls back to the
+   * `ALCHEMY_DEV` environment variable (`"1"` / `"true"` enable it).
+   */
+  dev?: boolean;
 }
 
+/** Resolve the effective `dev` flag from explicit options or `ALCHEMY_DEV`. */
+export const resolveDev = (options: { dev?: boolean }): boolean => {
+  if (options.dev !== undefined) return options.dev;
+  const env = process.env.ALCHEMY_DEV;
+  return env === "1" || env?.toLowerCase() === "true";
+};
+
+const overrideAlchemyContext = (overrides: { dev: boolean }) =>
+  Layer.effect(
+    AlchemyContext,
+    AlchemyContext.asEffect().pipe(
+      Effect.map((ctx) => ({ ...ctx, ...overrides })),
+    ),
+  );
+
 export type TestEffect<A, Req = never> = StackEffect<A, any, Req>;
 
 const platformLayer = Layer.mergeAll(PlatformServices, FetchHttpClient.layer);
 
-const alchemyLayer = Layer.mergeAll(
-  LoggingCli,
-  Logger.layer([Logger.consolePretty()], { mergeWithExisting: true }),
-  AlchemyContextLive,
-);
+const alchemyLayer = Layer.mergeAll(TestCli, AlchemyContextLive);
 
 /**
  * Build the per-test runtime and return a self-contained Effect.
@@ -74,8 +97,14 @@ export const toEffect = <A>(
       Effect.provide(Layer.succeed(ConfigProvider, configProvider)),
     );
   }).pipe(
-    Effect.provideService(AuthProviders, {}),
+    Effect.provideService(AdoptPolicy, options.adopt ?? false),
+    Effect.provide(overrideAlchemyContext({ dev: resolveDev(options) })),
+    // `options.state` (e.g. `Cloudflare.state()`) itself requires
+    // `AuthProviders` to read credentials, so AuthProviders must be provided
+    // AFTER the state layer or the state layer's requirement is never
+    // satisfied — which surfaces as `Service not found: AuthProviders`.
     Effect.provide(options.state ?? State.localState()),
+    Effect.provideService(AuthProviders, {}),
     Effect.provide(Layer.provideMerge(alchemyLayer, platformLayer)),
     Effect.scoped,
   ) as Effect.Effect<A, any, never>;
@@ -122,6 +151,7 @@ export const deploy = <A>(
   _deploy({
     stack: stack as Effect.Effect<CompiledStack<A>, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
+    dev: resolveDev(options),
   }).pipe(Effect.provide(TelemetryLive));
 
 export const destroy = (
@@ -132,6 +162,7 @@ export const destroy = (
   _destroy({
     stack: stack as Effect.Effect<CompiledStack, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
+    dev: resolveDev(options),
   }).pipe(Effect.provide(TelemetryLive));
 
 /**

package/src/Test/TestCli.ts

@@ -0,0 +1,221 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import { Cli, type PlanStatusSession } from "../Cli/Cli.ts";
+import type { ApplyEvent, ApplyStatus } from "../Cli/Event.ts";
+import type { Plan } from "../Plan.ts";
+
+const ESC = "\x1b[";
+const C = {
+  reset: `${ESC}0m`,
+  bold: `${ESC}1m`,
+  dim: `${ESC}2m`,
+  red: `${ESC}31m`,
+  green: `${ESC}32m`,
+  yellow: `${ESC}33m`,
+  blue: `${ESC}34m`,
+  magenta: `${ESC}35m`,
+  cyan: `${ESC}36m`,
+  gray: `${ESC}90m`,
+  brightGreen: `${ESC}92m`,
+  brightYellow: `${ESC}93m`,
+  brightBlue: `${ESC}94m`,
+  brightMagenta: `${ESC}95m`,
+  brightCyan: `${ESC}96m`,
+};
+
+const useColor =
+  process.env.NO_COLOR == null &&
+  process.env.FORCE_COLOR !== "0" &&
+  (process.env.FORCE_COLOR != null || process.stdout.isTTY === true);
+
+const paint = (color: string, s: string) =>
+  useColor ? `${color}${s}${C.reset}` : s;
+
+const TYPE_PALETTE = [
+  C.cyan,
+  C.green,
+  C.yellow,
+  C.magenta,
+  C.blue,
+  C.brightCyan,
+  C.brightGreen,
+  C.brightYellow,
+  C.brightMagenta,
+  C.brightBlue,
+];
+
+const stableHash = (s: string) => {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0;
+  return Math.abs(h);
+};
+
+const colorForType = (type: string) =>
+  TYPE_PALETTE[stableHash(type) % TYPE_PALETTE.length];
+
+const ACTION_STYLE: Record<
+  "create" | "update" | "replace" | "delete" | "noop",
+  { symbol: string; color: string; label: string }
+> = {
+  create: { symbol: "+", color: C.green, label: "create" },
+  update: { symbol: "~", color: C.yellow, label: "update" },
+  replace: { symbol: "!", color: C.magenta, label: "replace" },
+  delete: { symbol: "-", color: C.red, label: "delete" },
+  noop: { symbol: "·", color: C.gray, label: "noop" },
+};
+
+const STATUS_COLOR: Partial<Record<ApplyStatus, string>> = {
+  pending: C.gray,
+  attaching: C.gray,
+  "post-attach": C.gray,
+  "pre-creating": C.gray,
+  creating: C.green,
+  "creating replacement": C.magenta,
+  created: C.brightGreen,
+  updating: C.yellow,
+  updated: C.brightYellow,
+  deleting: C.red,
+  deleted: C.gray,
+  replacing: C.magenta,
+  replaced: C.brightMagenta,
+  fail: C.red + C.bold,
+};
+
+const TERMINAL_STATUSES: ReadonlySet<ApplyStatus> = new Set([
+  "created",
+  "updated",
+  "deleted",
+  "replaced",
+  "fail",
+]);
+
+const print = (line: string) =>
+  Effect.sync(() => {
+    process.stdout.write(`${line}\n`);
+  });
+
+const formatPlanLine = (
+  action: keyof typeof ACTION_STYLE,
+  type: string,
+  id: string,
+) => {
+  const a = ACTION_STYLE[action];
+  return [
+    paint(a.color, a.symbol),
+    paint(a.color, a.label.padEnd(7)),
+    paint(colorForType(type), type.padEnd(28)),
+    paint(C.bold, id),
+  ].join(" ");
+};
+
+const displayPlan = <P extends Plan>(plan: P): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const entries = Object.entries(plan.resources ?? {})
+      .map(([id, node]) => ({
+        id,
+        action: node.action,
+        type: node.resource.Type,
+      }))
+      .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+    const deletions = Object.entries(plan.deletions ?? {})
+      .filter(([, n]) => n != null)
+      .map(([id, node]) => ({
+        id,
+        action: "delete" as const,
+        type: node!.resource.Type,
+      }))
+      .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+
+    const all = [...entries, ...deletions];
+    if (all.length === 0) {
+      yield* print(paint(C.gray, "Plan: no changes"));
+      return;
+    }
+
+    const counts = all.reduce<Record<string, number>>((acc, e) => {
+      acc[e.action] = (acc[e.action] ?? 0) + 1;
+      return acc;
+    }, {});
+    const summary = (["create", "update", "replace", "delete", "noop"] as const)
+      .filter((a) => counts[a])
+      .map((a) =>
+        paint(ACTION_STYLE[a].color, `${counts[a]} ${ACTION_STYLE[a].label}`),
+      )
+      .join(paint(C.gray, ", "));
+
+    yield* print(paint(C.bold, `Plan (${summary})`));
+    for (const e of all) {
+      yield* print(`  ${formatPlanLine(e.action as any, e.type, e.id)}`);
+    }
+  });
+
+const formatStatusLine = (
+  event: Extract<ApplyEvent, { kind: "status-change" }>,
+) => {
+  const statusColor = STATUS_COLOR[event.status] ?? C.gray;
+  const statusLabel = paint(statusColor, event.status.padEnd(22));
+  const typeLabel = paint(colorForType(event.type), event.type);
+  const idLabel = paint(C.bold, event.id);
+  const binding = event.bindingId ? paint(C.gray, `[${event.bindingId}] `) : "";
+  const message = event.message ? paint(C.dim, ` — ${event.message}`) : "";
+  return `  ${statusLabel} ${binding}${typeLabel} ${idLabel}${message}`;
+};
+
+const formatAnnotateLine = (event: Extract<ApplyEvent, { kind: "annotate" }>) =>
+  `  ${paint(C.gray, "·".padEnd(22))} ${paint(C.bold, event.id)} ${paint(C.dim, event.message)}`;
+
+const startApplySession = <P extends Plan>(_plan: P) =>
+  Effect.sync<PlanStatusSession>(() => {
+    const counts: Record<string, number> = {};
+    return {
+      emit: (event) =>
+        Effect.sync(() => {
+          if (event.kind === "status-change") {
+            if (TERMINAL_STATUSES.has(event.status)) {
+              counts[event.status] = (counts[event.status] ?? 0) + 1;
+            }
+            process.stdout.write(`${formatStatusLine(event)}\n`);
+          } else {
+            process.stdout.write(`${formatAnnotateLine(event)}\n`);
+          }
+        }),
+      done: () =>
+        Effect.sync(() => {
+          const parts = (
+            ["created", "updated", "replaced", "deleted", "fail"] as const
+          )
+            .filter((s) => counts[s])
+            .map((s) => paint(STATUS_COLOR[s] ?? C.gray, `${counts[s]} ${s}`));
+          if (parts.length > 0) {
+            process.stdout.write(
+              `${paint(C.bold, "Apply complete")} ${paint(C.gray, "(")}${parts.join(paint(C.gray, ", "))}${paint(C.gray, ")")}\n`,
+            );
+          }
+        }),
+    };
+  });
+
+/**
+ * CLI implementation tailored for test runners.
+ *
+ * - `approvePlan` auto-approves so `beforeAll(deploy(Stack))` doesn't hang.
+ * - `displayPlan` prints a colored summary with one line per change.
+ * - `startApplySession` streams colored status lines for each resource
+ *   transition and a final summary count from `done()`.
+ *
+ * Output goes straight to `process.stdout` rather than through Effect's
+ * Logger, so it isn't shadowed by `Stack.ts`'s file logger.
+ *
+ * No `react`/`ink` dependency — this layer is safe to import from
+ * `Test/Bun.ts` / `Test/Vitest.ts` without dragging the TUI deps into
+ * every consumer's test setup.
+ */
+export const TestCli = Layer.succeed(
+  Cli,
+  Cli.of({
+    approvePlan: () => Effect.succeed(true),
+    displayPlan,
+    startApplySession,
+  }),
+);

package/src/Util/proxy-chain.ts

@@ -0,0 +1,80 @@
+import * as Effect from "effect/Effect";
+
+type Op =
+  | { kind: "get"; prop: PropertyKey }
+  | { kind: "call"; args: unknown[] };
+
+/**
+ * Replay an op chain against a real value. `get` reads a property,
+ * `call` invokes — bound to the previous receiver so `this` resolves
+ * to the object the method was read from (drizzle's `select()` etc.
+ * read `this._.session`, so dropping `this` would throw).
+ */
+const replay = (root: unknown, ops: ReadonlyArray<Op>): unknown => {
+  let cur: any = root;
+  let receiver: any = root;
+  for (const op of ops) {
+    if (op.kind === "get") {
+      receiver = cur;
+      cur = cur[op.prop];
+    } else {
+      cur = cur.apply(receiver, op.args);
+      receiver = cur;
+    }
+  }
+  return cur;
+};
+
+/**
+ * Wrap a cached `Effect<T>` in a chainable Proxy so callers can use the
+ * returned value as if it were `T` itself — every property read and call
+ * records a step, and the chain is replayed against the resolved value
+ * when it's finally yielded as an Effect.
+ *
+ * Compare:
+ *
+ * ```typescript
+ * // Without proxyChain — caller has to yield the cached Effect first:
+ * const conn = yield* makeConnection();      // Effect<Db>
+ * fetch: Effect.gen(function* () {
+ *   const db = yield* conn;
+ *   const rows = yield* db.select().from(users);
+ * });
+ *
+ * // With proxyChain — caller treats the return as the value directly:
+ * const db = proxyChain(yield* Effect.cached(makeDb));   // T
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * The chain ends when the proxy is yielded as an Effect — the resolved
+ * value at that point must be a `Yieldable` (an Effect, drizzle query
+ * builder, etc). Anything before that is recorded as ops.
+ */
+export const proxyChain = <T>(cached: Effect.Effect<T, any, any>): T =>
+  chain(cached) as T;
+
+const chain = (
+  cached: Effect.Effect<unknown, any, any>,
+  ops: ReadonlyArray<Op> = [],
+): unknown =>
+  new Proxy(function () {} as any, {
+    get(_, prop) {
+      if (prop === Symbol.iterator) {
+        // `yield* proxy` — produce the resolved Effect's iterator.
+        return function () {
+          const eff = Effect.flatMap(
+            cached,
+            (root) =>
+              replay(root, ops) as Effect.Effect<unknown, unknown, unknown>,
+          );
+          return (eff as any)[Symbol.iterator]();
+        };
+      }
+      return chain(cached, [...ops, { kind: "get", prop }]);
+    },
+    apply(_, __, args) {
+      return chain(cached, [...ops, { kind: "call", args }]);
+    },
+  });

package/src/index.ts

@@ -36,12 +36,12 @@ export * as Construct from "./Construct.ts";
 // downstream `.d.ts` emissions (fixes TS2883 in user files).
 export { AuthProviders } from "./Auth/AuthProvider.ts";
 export { Cli } from "./Cli/Cli.ts";
-export {
-  ExecutionContext,
-  type BaseExecutionContext,
-  type ExecutionContext as ExecutionContextInterface,
-} from "./ExecutionContext.ts";
 export type * from "./Platform.ts";
 export { Platform } from "./Platform.ts";
 export type { ProviderCollectionLike } from "./Provider.ts";
+export {
+  RuntimeContext,
+  type BaseRuntimeContext,
+  type RuntimeContext as RuntimeContextInterface,
+} from "./RuntimeContext.ts";
 export type * from "./Stack.ts";