alchemy 2.0.0-beta.76 → 2.0.0-beta.77

package/src/State/Tree.ts

@@ -0,0 +1,277 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { State, type StateService, type StateStoreError } from "./State.ts";
+import { encodeState } from "./StateEncoding.ts";
+
+// The store viewed as a filesystem: `stack/stage/fqn` for a resource record,
+// `stack/stage/output` for a stage's outputs. Everything here addresses that
+// tree by slash-separated path, so a CLI or an RPC client can walk state
+// without knowing the backend's key layout.
+
+/** Reading or listing a path. Omit `path` for the root. */
+export interface TreeQuery {
+  readonly path?: string;
+  /** Recurse into every descendant instead of stopping at immediate children. */
+  readonly recursive?: boolean;
+}
+
+/** Deleting a path. The path is required — the root is not deletable. */
+export interface TreeDelete {
+  readonly path: string;
+  /** Delete every descendant when the path identifies a directory. */
+  readonly recursive?: boolean;
+}
+
+/** One decoded record produced by {@link readState}. */
+export interface StateEntry {
+  readonly path: string;
+  readonly kind: "resource" | "output";
+  readonly value: unknown;
+}
+
+/** The path does not exist, or does not support the requested operation. */
+export class InvalidStatePath extends Data.TaggedError("InvalidStatePath")<{
+  readonly path: string;
+  readonly reason: string;
+}> {}
+
+export interface StateDeleted {
+  readonly _tag: "StateDeleted";
+  readonly path: string;
+  readonly deleted: ReadonlyArray<string>;
+}
+
+/**
+ * Every `(stack, stage)` pair the store holds, or the subset a filter pins.
+ *
+ * Enumerating them means `listStacks` then a `listStages` per stack, so the
+ * fan-out runs concurrently: against a remote store a serial walk is one
+ * round trip per stack before the first stage is even known. A pinned
+ * `stack`/`stage` is taken at face value and skips the corresponding call —
+ * naming a scope is not a claim that it exists, and callers report a missing
+ * one from the emptiness of what comes back.
+ *
+ * Ordered by stack then stage so every traversal built on it is deterministic.
+ */
+export const allStages = Effect.fn("allStages")(function* (
+  filter: { readonly stack?: string; readonly stage?: string } = {},
+) {
+  return yield* stagesOf(yield* yield* State, filter);
+});
+
+const stagesOf = (
+  state: StateService,
+  filter: { readonly stack?: string; readonly stage?: string },
+): Effect.Effect<
+  ReadonlyArray<{ readonly stack: string; readonly stage: string }>,
+  StateStoreError
+> =>
+  Effect.gen(function* () {
+    const stacks =
+      filter.stack !== undefined
+        ? [filter.stack]
+        : [...(yield* state.listStacks())].sort();
+    if (filter.stage !== undefined) {
+      const stage = filter.stage;
+      return stacks.map((stack) => ({ stack, stage }));
+    }
+    const perStack = yield* Effect.forEach(
+      stacks,
+      (stack) =>
+        Effect.map(state.listStages(stack), (stages) =>
+          [...stages].sort().map((stage) => ({ stack, stage })),
+        ),
+      { concurrency: "unbounded" },
+    );
+    return perStack.flat();
+  });
+
+type StateFile =
+  | {
+      readonly kind: "resource";
+      readonly path: string;
+      readonly stack: string;
+      readonly stage: string;
+      readonly fqn: string;
+    }
+  | {
+      readonly kind: "output";
+      readonly path: string;
+      readonly stack: string;
+      readonly stage: string;
+    };
+
+const pathParts = (path: string | undefined): ReadonlyArray<string> =>
+  (path ?? "").split("/").filter((part) => part !== "" && part !== ".");
+
+const invalidPath = (path: string, reason = "path does not exist") =>
+  Effect.fail(new InvalidStatePath({ path, reason }));
+
+const parsePath = (path: string | undefined) => {
+  const parts = pathParts(path);
+  return parts.includes("..")
+    ? invalidPath(path ?? "/", "parent path segments are not allowed")
+    : Effect.succeed(parts);
+};
+
+const stageFiles = Effect.fn(function* (
+  state: StateService,
+  stack: string,
+  stage: string,
+) {
+  const fqns = yield* state.list({ stack, stage });
+  return [
+    ...fqns.map((fqn): StateFile => ({
+      kind: "resource",
+      path: `${stack}/${stage}/${fqn}`,
+      stack,
+      stage,
+      fqn,
+    })),
+    {
+      kind: "output",
+      path: `${stack}/${stage}/output`,
+      stack,
+      stage,
+    } as const,
+  ];
+});
+
+/** Every file under the given scope, listed one stage at a time in parallel. */
+const filesUnder = Effect.fn(function* (
+  state: StateService,
+  filter: { readonly stack?: string } = {},
+) {
+  const stages = yield* stagesOf(state, filter);
+  const perStage = yield* Effect.forEach(
+    stages,
+    ({ stack, stage }) => stageFiles(state, stack, stage),
+    { concurrency: "unbounded" },
+  );
+  return perStage.flat();
+});
+
+const filesAt = Effect.fn(function* (
+  state: StateService,
+  parts: ReadonlyArray<string>,
+) {
+  const path = parts.join("/");
+  if (parts.length === 0) {
+    return { directory: true as const, files: yield* filesUnder(state) };
+  }
+  if (parts.length === 1) {
+    const stack = parts[0]!;
+    if (!(yield* state.listStacks()).includes(stack)) {
+      return yield* invalidPath(path);
+    }
+    return {
+      directory: true as const,
+      files: yield* filesUnder(state, { stack }),
+    };
+  }
+  if (parts.length === 2) {
+    const [stack, stage] = parts as [string, string];
+    if (!(yield* state.listStages(stack)).includes(stage)) {
+      return yield* invalidPath(path);
+    }
+    return {
+      directory: true as const,
+      files: yield* stageFiles(state, stack, stage),
+    };
+  }
+  const files = yield* stageFiles(state, parts[0]!, parts[1]!);
+  const exact = files.find((file) => file.path === path);
+  if (exact !== undefined) return { directory: false as const, files: [exact] };
+  const descendants = files.filter((file) => file.path.startsWith(`${path}/`));
+  if (descendants.length === 0) return yield* invalidPath(path);
+  return { directory: true as const, files: descendants };
+});
+
+export const listState = Effect.fn("listState")(function* ({
+  path,
+  recursive = false,
+}: TreeQuery) {
+  const state = yield* yield* State;
+  const parts = yield* parsePath(path);
+  const normalizedPath = parts.join("/");
+  if (parts.length === 0 && !recursive) {
+    return (yield* state.listStacks()).map((stack) => `${stack}/`);
+  }
+  const { directory, files } = yield* filesAt(state, parts);
+  if (!directory) return [normalizedPath];
+  const prefix = normalizedPath === "" ? "" : `${normalizedPath}/`;
+  if (recursive) return files.map((file) => file.path);
+  return [
+    ...new Set(
+      files.map((file) => {
+        const rest = file.path.slice(prefix.length);
+        const child = rest.split("/")[0]!;
+        return rest.includes("/") ? `${prefix}${child}/` : file.path;
+      }),
+    ),
+  ];
+});
+
+export const readState = Effect.fn("readState")(function* ({
+  path,
+  recursive = false,
+}: TreeQuery) {
+  const state = yield* yield* State;
+  const parts = yield* parsePath(path);
+  const target = yield* filesAt(state, parts);
+  if (target.directory && !recursive) {
+    return yield* invalidPath(
+      path ?? "/",
+      "path is a directory; set recursive to read its descendants",
+    );
+  }
+  return yield* Effect.forEach(target.files, (file) =>
+    (file.kind === "output" ? state.getOutput(file) : state.get(file)).pipe(
+      Effect.map((value): StateEntry => ({
+        path: file.path,
+        kind: file.kind,
+        value: encodeState(value) ?? null,
+      })),
+    ),
+  );
+});
+
+export const deleteState = Effect.fn("deleteState")(function* ({
+  path,
+  recursive = false,
+}: TreeDelete) {
+  const state = yield* yield* State;
+  const parts = yield* parsePath(path);
+  if (parts.length === 0) {
+    return yield* invalidPath(path, "the state root cannot be deleted");
+  }
+  const target = yield* filesAt(state, parts);
+  if (target.directory && !recursive) {
+    return yield* invalidPath(
+      path,
+      "path is a directory; set recursive to delete its descendants",
+    );
+  }
+  if (parts.length === 1) {
+    yield* state.deleteStack({ stack: parts[0]! });
+  } else if (parts.length === 2) {
+    yield* state.deleteStack({ stack: parts[0]!, stage: parts[1]! });
+  } else {
+    const resources = target.files.filter(
+      (file): file is Extract<StateFile, { kind: "resource" }> =>
+        file.kind === "resource",
+    );
+    if (resources.length === 0) {
+      return yield* invalidPath(path, "output cannot be deleted independently");
+    }
+    yield* Effect.forEach(resources, (file) => state.delete(file), {
+      concurrency: 32,
+      discard: true,
+    });
+  }
+  return {
+    _tag: "StateDeleted" as const,
+    path: parts.join("/"),
+    deleted: target.files.map((file) => file.path),
+  };
+});

package/src/State/index.ts

@@ -12,3 +12,4 @@ export * from "./State.ts";
 export * from "./ActionState.ts";
 export * from "./StateEncoding.ts";
 export * from "./Sync.ts";
+export * from "./Tree.ts";

package/src/Telemetry/Layer.ts

@@ -37,15 +37,20 @@ const buildOtlpLayer = (
     resource,
     exportInterval: "1 second",
   });
-  // Replace (don't merge with) the default stdout logger here; downstream
-  // commands re-add their own `fileLogger`/`consolePretty` via
-  // `Logger.layer([...], { mergeWithExisting: true })`, which stacks on top
-  // of this OtlpLogger without resurrecting Effect's default stdout logger.
+  // Stack on top of whatever loggers are already installed. Entrypoints
+  // provide this layer *over* their terminal/file logger layer
+  // (`Layer.provideMerge(TelemetryLive, ConsoleLogLive)`), so the terminal
+  // logger has already replaced Effect's default stdout logger by the time
+  // this runs and the OTLP logger is simply added alongside it.
+  //
+  // `mergeWithExisting: false` here would make telemetry *replace* the
+  // terminal logger whenever this layer happened to be merged after it —
+  // exactly what silenced `alchemy dev`'s console output in the exec child.
   const logger = OtlpLogger.layer({
     url: LOGS_URL,
     resource,
     exportInterval: "1 second",
-    mergeWithExisting: false,
+    mergeWithExisting: true,
   });
 
   return Layer.mergeAll(tracer, metrics, logger).pipe(
@@ -60,6 +65,12 @@ const buildOtlpLayer = (
  * {@link collectAttributes} as resource-level attributes so every signal
  * carries user/project/runtime context.
  *
+ * The OTLP logger merges with the loggers already installed, so provide this
+ * layer on top of the entrypoint's terminal/file logger layer — e.g.
+ * `Layer.provideMerge(TelemetryLive, ConsoleLogLive)` — never as a sibling in
+ * a `Layer.mergeAll` (the last `CurrentLoggers` in a merge wins, silently
+ * dropping either the terminal output or the telemetry).
+ *
  * 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,

package/src/Telemetry.ts

@@ -427,6 +427,11 @@ const reference = Telemetry;
  * other: loggers and metric exporters merge; a custom `Tracer` (a single
  * Effect service) replaces the built-in one.
  *
+ * The isolate {@link Telemetry} reference stays the bound OTLP reader.
+ * The custom Layer is stored on `ctx.telemetry` and merged per event as
+ * the override, so `Layer.mergeAll` order with {@link layerOtlp} does not
+ * drop logs/metrics.
+ *
  * Provide it on the Function/Worker's init Effect (merged into the single
  * `Effect.provide`): building the returned Layer registers the exporter
  * Layer on the current runtime context, where the runtime bridges pick it
@@ -446,7 +451,7 @@ export const layer = (exporter: TelemetryLayer): Layer.Layer<never> =>
             ? exporter
             : Layer.mergeAll(ctx.telemetry, exporter);
       }
-      return exporter;
+      return fromBoundConfig;
     }),
   );
 

package/src/Test/Core.ts

@@ -21,7 +21,9 @@ import { apply } from "../Apply.ts";
 import { provideFreshArtifactStore } from "../Artifacts.ts";
 import { AuthProviders } from "../Auth/AuthProvider.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
-import { ProfileLive, withProfileOverride } from "../Auth/Profile.ts";
+import { ProfileStoreLive } from "../Auth/Profile.ts";
+import { withProfileOverride } from "../Auth/Resolve.ts";
+import * as Interaction from "../Interaction.ts";
 import { LoggingCli } from "../Cli/LoggingCli.ts";
 import { deploy as _deploy } from "../Deploy.ts";
 import { destroy as _destroy } from "../Destroy.ts";
@@ -51,7 +53,7 @@ export interface MakeOptions<ROut = any> {
   providers: Layer.Layer<ROut, never, StackServices>;
   /** State store for top-level `deploy(Stack)` / `destroy(Stack)`; defaults to {@link State.localState}. */
   state?: Layer.Layer<State.State, never, StackServices>;
-  /** Override `ALCHEMY_PROFILE`; otherwise resolved from env / .env. */
+  /** Override the current profile; otherwise resolved from env or the built-in `default`. */
   profile?: string;
   /** Default stage for deploy/destroy (default `"test"`). */
   stage?: string;
@@ -315,11 +317,15 @@ const platformLayer = () =>
     Option.getOrElse(alchemyTestDevOverride(), () => false)
       ? flociWebsiteHttp
       : FetchHttpClient.layer,
-    Layer.provide(ProfileLive, PlatformServices),
+    Layer.provide(ProfileStoreLive, PlatformServices),
     Layer.provide(CredentialsStoreLive, PlatformServices),
   );
 
-const alchemyLayer = Layer.mergeAll(LoggingCli, AlchemyContextLive);
+const alchemyLayer = Layer.mergeAll(
+  LoggingCli,
+  Interaction.layerNonInteractive(),
+  AlchemyContextLive,
+);
 
 /**
  * Build the per-test runtime and return a self-contained Effect.

package/src/UserFacingError.ts

@@ -0,0 +1,35 @@
+import * as Predicate from "effect/Predicate";
+
+/**
+ * Marker for error classes whose `message` is written for end users. The CLI's
+ * top-level handler prints a marked error's `message` as a single friendly
+ * line instead of dumping the raw cause chain.
+ *
+ * Mark a class by assigning the symbol in the class body:
+ *
+ * ```ts
+ * export class MyError extends Data.TaggedError("MyError")<{
+ *   readonly message: string;
+ * }> {
+ *   readonly [UserFacingError] = true;
+ * }
+ * ```
+ *
+ * Classes without a human-readable `message` prop derive one with a getter
+ * (see `AlchemistNotFound` in `Alchemist/Errors.ts`).
+ */
+export const UserFacingError: unique symbol = Symbol.for(
+  "alchemy/UserFacingError",
+);
+
+/** An error carrying a human-readable `message` that is safe to print as-is. */
+export interface UserFacingError {
+  readonly [UserFacingError]: true;
+  readonly message: string;
+}
+
+export const isUserFacing = (error: unknown): error is UserFacingError =>
+  Predicate.hasProperty(error, UserFacingError) &&
+  error[UserFacingError] === true &&
+  Predicate.hasProperty(error, "message") &&
+  typeof error.message === "string";

package/src/Util/AtomicFile.ts

@@ -0,0 +1,36 @@
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type { PlatformError } from "effect/PlatformError";
+
+/**
+ * Write `contents` to `filePath` via a same-directory temp file + rename.
+ *
+ * A plain `writeFileString` truncates the target before writing, so a crash
+ * mid-write (or a concurrent reader — another CLI process, the RPC sidecar)
+ * can observe empty/partial JSON. rename(2) is atomic on the same
+ * filesystem, so readers see either the old contents or the new, never a
+ * torn write. When `mode` is given it is applied to the temp file *before*
+ * the rename, so a secret is never visible at its final path with default
+ * permissions. The temp file is removed on failure.
+ *
+ * Used for `~/.alchemy/profiles.json`, the per-provider credential files,
+ * and local state files.
+ */
+export const writeFileAtomic = (
+  fs: FileSystem.FileSystem,
+  filePath: string,
+  contents: string,
+  mode?: number,
+): Effect.Effect<void, PlatformError> =>
+  Effect.suspend(() => {
+    const tmp = `${filePath}.${process.pid}.${Math.random()
+      .toString(36)
+      .slice(2)}.tmp`;
+    return fs.writeFileString(tmp, contents).pipe(
+      Effect.flatMap(() =>
+        mode === undefined ? Effect.void : fs.chmod(tmp, mode),
+      ),
+      Effect.flatMap(() => fs.rename(tmp, filePath)),
+      Effect.tapError(() => fs.remove(tmp).pipe(Effect.ignore)),
+    );
+  });

package/src/Util/ConsoleSink.ts

@@ -0,0 +1,23 @@
+import * as Logger from "effect/Logger";
+import { ANSI_RESET, colorsEnabled } from "./Terminal.ts";
+
+/** Effect pretty prefixes with selective color and untouched message styling. */
+export const makePlainConsoleSink = (colors = colorsEnabled()) => {
+  const pretty = Logger.consolePretty({ colors });
+  if (!colors) return pretty;
+  return Logger.make<unknown, void>((options) => {
+    const messages = Array.isArray(options.message)
+      ? options.message
+      : [options.message];
+    pretty.log({
+      ...options,
+      // consolePretty applies bold cyan around the first string. Reset that
+      // wrapper before the content; any intentional ANSI inside the message
+      // still takes effect normally.
+      message: [
+        `${ANSI_RESET}${String(messages[0] ?? "")}`,
+        ...messages.slice(1),
+      ],
+    });
+  });
+};

package/src/Util/LineBuffer.ts

@@ -0,0 +1,20 @@
+/**
+ * Buffers arbitrary text chunks and emits complete lines. Call `flush` when
+ * the source closes to emit a trailing partial line.
+ */
+export const makeLineBuffer = (onLine: (line: string) => void) => {
+  let buffer = "";
+  return {
+    push(chunk: string) {
+      buffer += chunk;
+      const lines = buffer.split(/\r\n|\n|\r/);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) onLine(line);
+    },
+    flush() {
+      if (buffer === "") return;
+      onLine(buffer);
+      buffer = "";
+    },
+  };
+};

package/src/Util/Memoize.ts

@@ -0,0 +1,48 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+
+/**
+ * A lazily evaluated, memoized effect whose computation runs in a fiber of
+ * its own, owned by `scope`.
+ *
+ * `Effect.cached` evaluates on the fiber of whichever caller gets there
+ * first. When that caller is interrupted while others are waiting — a
+ * concurrent plan cancelling sibling diffs — every waiter fails
+ * interrupt-only and the cache stays poisoned for the rest of the process.
+ * A computation that many fibers share must not have that failure mode: here
+ * it runs detached from every caller, so interrupting a waiter never touches
+ * it, and only closing `scope` cancels it (its waiters then see the
+ * interruption, as they should).
+ *
+ * Requirements are captured from the first caller, exactly as
+ * `Effect.cached` does.
+ */
+export const cachedInScope =
+  (scope: Scope.Scope) =>
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<Effect.Effect<A, E>, never, R> =>
+    Effect.gen(function* () {
+      const context = yield* Effect.context<R>();
+      const deferred = yield* Deferred.make<A, E>();
+      let started = false;
+      return Effect.suspend(() => {
+        if (started) return Deferred.await(deferred);
+        started = true;
+        return effect.pipe(
+          Effect.provideContext(context),
+          // `onExit` also runs on interruption, so the waiters always learn
+          // how the computation ended.
+          Effect.onExit((exit) => Deferred.done(deferred, exit)),
+          // Not a child of the caller: the caller's interruption must not
+          // reach it. The scope owns its lifetime instead.
+          Effect.forkDetach,
+          Effect.flatMap((fiber) =>
+            Scope.addFinalizer(scope, Fiber.interrupt(fiber)),
+          ),
+          Effect.andThen(Deferred.await(deferred)),
+        );
+      });
+    });

package/src/Util/Node.ts

@@ -46,24 +46,45 @@ export const disableCrossSpawnChdir = (): void => {
   (process.chdir as { disabled?: boolean }).disabled = true;
 };
 
-export const isTransformTypesSupported = (
-  version = process.versions.node,
-): boolean => {
-  const [major, minor] = version.split(".").map(Number);
-  return (major === 22 && minor >= 7) || (major >= 23 && major < 26);
-};
+/**
+ * Node arguments that install alchemy's Oxc loader in a child process, the
+ * same way `bin/cli.js` installs it for the CLI itself. Every `.ts`/`.tsx`
+ * a Node process loads — alchemy's own source in a checkout, the user's
+ * stack everywhere — goes through it; nothing relies on Node's built-in
+ * TypeScript support (strip-only, and Node 26 removed the transform flag).
+ *
+ * A `.ts` entry means a checkout: `bin/register-dev-mode.js` adds the
+ * src-condition resolution for workspace packages on top of the loader.
+ * A `.js` entry means a published install: `bin/register-oxc.js` is the
+ * loader alone.
+ */
+export const nodeLoaderArgs = (entry: string): string[] => [
+  "--import",
+  import.meta.resolve(
+    /\.[cm]?tsx?$/.test(entry)
+      ? "../../bin/register-dev-mode.js"
+      : "../../bin/register-oxc.js",
+  ),
+];
 
 /**
- * Node CLI flags that transparently transform TypeScript types so `.ts`
- * entry points work the same way they do under Bun. Empty when the running
- * Node doesn't support (or no longer needs) the experimental flag.
+ * Whether this Node supports the synchronous in-thread loader hooks
+ * (`module.registerHooks`, v22.15 / v23.5) that `bin/register-dev-mode.js`
+ * needs. This is THE capability gate for running the CLI from source under
+ * node: with the hooks installed, the Oxc loader handles every `.ts`/`.tsx`
+ * file regardless of Node's own TypeScript support.
+ *
+ * `bin/cli.js` mirrors this predicate inline — it must run under plain node
+ * before any `.ts` can load. Keep the two in sync.
  */
-export const transformTypesFlags = (
+export const isRegisterHooksSupported = (
   version = process.versions.node,
-): string[] =>
-  isTransformTypesSupported(version)
-    ? ["--experimental-transform-types", "--no-warnings=ExperimentalWarning"]
-    : [];
+): boolean => {
+  const [major = 0, minor = 0] = version.split(".").map(Number);
+  return (
+    (major === 22 && minor >= 15) || (major === 23 && minor >= 5) || major >= 24
+  );
+};
 
 /**
  * Ask the OS for an unused TCP port, release it, and return its number.

package/src/Util/PlatformServices.ts

@@ -1,3 +1,5 @@
+import type { Crypto } from "effect/Crypto";
+import type { Input as DurationInput } from "effect/Duration";
 import * as Effect from "effect/Effect";
 import type { FileSystem } from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -47,6 +49,7 @@ export const platformLayer = <A, E, R>(constructors: {
 
 export type PlatformServices =
   | ChildProcessSpawner
+  | Crypto
   | FileSystem
   | Path
   | Stdio
@@ -134,6 +137,9 @@ export const runMain = <E, A>(
 export const httpServer = (
   port: number = 0,
   host: string = "127.0.0.1",
+  options?: {
+    readonly gracefulShutdownTimeout?: DurationInput | undefined;
+  },
 ): Layer.Layer<HttpServer, ServeError> =>
   platformLayer({
     bun: async () => {
@@ -155,6 +161,10 @@ export const httpServer = (
         ),
         import("node:http"),
       ]);
-      return NodeHttpServer.layerServer(Http.createServer, { host, port });
+      return NodeHttpServer.layerServer(Http.createServer, {
+        host,
+        port,
+        gracefulShutdownTimeout: options?.gracefulShutdownTimeout,
+      });
     },
   });