alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Alchemist/AuthRegistry.ts

@@ -0,0 +1,164 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type { PlatformError } from "effect/PlatformError";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import { AuthError, AuthProviders } from "../Auth/AuthProvider.ts";
+import { SuppressMissingProviderConfig } from "../Auth/Profile.ts";
+import * as Contributions from "../Contributions.ts";
+import type { ContributionError } from "../Contributions.ts";
+import { makeCachedFunction } from "../Util/cached-function.ts";
+import { DEFAULT_ENTRYPOINT, importStack } from "./Entrypoint.ts";
+import * as Operations from "./Operations.ts";
+import type { Services } from "./Runtime.ts";
+
+// Every auth provider a project can reach: what `alchemy profile` and
+// `alchemy provider check-env` list and configure. Collected by building the
+// installed providers' auth and the project's providers into one registry.
+
+/** What collecting an auth registry can fail with. */
+export type CollectAuthProvidersError = AuthError | ContributionError | PlatformError;
+
+/** What collecting an auth registry runs under. */
+export type CollectAuthProvidersServices = Services | Scope.Scope;
+
+type CollectAuthProviders = (
+  options: CollectAuthProvidersOptions,
+) => Effect.Effect<
+  AuthProviders["Service"],
+  CollectAuthProvidersError,
+  CollectAuthProvidersServices
+>;
+
+export interface CollectAuthProvidersOptions {
+  readonly main: string;
+  readonly envFile: Option.Option<string>;
+  readonly profile: string;
+}
+
+/**
+ * Every provider's auth provider, merged into one registering layer. One
+ * provider whose auth fails to load is skipped with a warning, so it can't
+ * take every other provider's auth down with it.
+ */
+const contributedAuth = Effect.gen(function* () {
+  const layers = yield* Effect.forEach(
+    yield* Contributions.load(),
+    (provider) =>
+      provider.auth
+        ? Contributions.resolve(provider, "auth", provider.auth).pipe(
+            Effect.catch((error) => Effect.as(Effect.logWarning(error.message), Layer.empty)),
+          )
+        : Effect.succeed(Layer.empty),
+    { concurrency: "unbounded" },
+  );
+  return Layer.mergeAll(Layer.empty, ...layers);
+});
+
+/** Register every installed provider's auth into the ambient registry. */
+const registerContributedAuth = Effect.fn("registerContributedAuth")(function* (options: {
+  readonly envFile: Option.Option<string>;
+  readonly profile: string;
+}) {
+  const shared = yield* Operations.configServices({
+    ...options,
+    envFile: Option.getOrUndefined(options.envFile),
+  });
+  yield* Layer.build(Layer.provide(yield* contributedAuth, shared));
+});
+
+const isMissingProviderConfig = Schema.is(
+  Schema.Struct({ _tag: Schema.Literals(["MissingProviderConfig"]) }),
+);
+
+/**
+ * Every auth provider reachable from the current project: the built-ins, plus
+ * whatever the user's stack module registers when it is importable.
+ */
+const collectAuthProvidersUncached = Effect.fn("collectAuthProvidersUncached")(
+  function* (options: CollectAuthProvidersOptions) {
+    // Everything built below registers into this one registry: the
+    // registry layers reuse an ambient registry instead of starting fresh.
+    const authProviders: AuthProviders["Service"] = {};
+    const collect = Effect.provideService(AuthProviders, authProviders);
+    yield* registerContributedAuth(options).pipe(collect);
+
+    const fs = yield* FileSystem.FileSystem;
+    const entrypointExists = yield* fs.exists(options.main);
+    const missingDefault = options.main === DEFAULT_ENTRYPOINT && !entrypointExists;
+    if (!entrypointExists && !missingDefault) {
+      return yield* AuthError.make({
+        message: `Stack entrypoint '${options.main}' does not exist.`,
+      });
+    }
+    if (!missingDefault) {
+      yield* importStack(options.main).pipe(
+        Effect.flatMap((stack) =>
+          Operations.buildProviders(stack, {
+            profile: options.profile,
+            envFile: Option.getOrUndefined(options.envFile),
+          }),
+        ),
+        collect,
+        Effect.timeoutOption(Duration.seconds(15)),
+        Effect.catchCause((cause) => {
+          const suppressed = cause.reasons.some((reason) => {
+            const error = Cause.isFailReason(reason)
+              ? reason.error
+              : Cause.isDieReason(reason)
+                ? reason.defect
+                : undefined;
+            return isMissingProviderConfig(error);
+          });
+          return suppressed
+            ? Effect.void
+            : Effect.fail(
+                AuthError.make({
+                  message: `Could not load auth providers from '${options.main}'.`,
+                  cause,
+                }),
+              );
+        }),
+      );
+    }
+    return authProviders;
+  },
+  Effect.provideService(SuppressMissingProviderConfig, true),
+);
+
+/**
+ * Collects auth registries. Uncached by default; {@link authRegistryLayer}
+ * memoizes them for its own lifetime.
+ */
+const AuthRegistry = Context.Reference<CollectAuthProviders>("Alchemy/Alchemist/AuthRegistry", {
+  defaultValue: () => collectAuthProvidersUncached,
+});
+
+/**
+ * Memoize auth registries for one command or API runtime: profile flows
+ * collect them repeatedly, and concurrent collections of the same project
+ * share one. Registries are built in this layer's scope, so a cached one
+ * never outlives the services its providers captured. Failures are not
+ * cached.
+ */
+export const authRegistryLayer = Layer.effect(
+  AuthRegistry,
+  Effect.map(Effect.scope, (scope) =>
+    makeCachedFunction(
+      (options: CollectAuthProvidersOptions) =>
+        collectAuthProvidersUncached(options).pipe(Scope.provide(scope)),
+      {
+        key: ([options]) =>
+          JSON.stringify([options.main, Option.getOrNull(options.envFile), options.profile]),
+      },
+    ),
+  ),
+);
+
+export const collectAuthProviders = (options: CollectAuthProvidersOptions) =>
+  Effect.flatMap(AuthRegistry, (collect) => collect(options));

package/src/Alchemist/Drift.ts

@@ -0,0 +1,103 @@
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as EngineDrift from "../Drift.ts";
+import { emit } from "../Events.ts";
+import type { Plan } from "../Plan.ts";
+import type { ConfiguredStack } from "../Stack.ts";
+import type { State } from "../State/State.ts";
+import {
+  buildWithoutProgram,
+  summarize,
+  type BuildOptions,
+  type PlanSummary,
+} from "./Operations.ts";
+
+export interface DriftedResource {
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly resourceType: string;
+  /** `skipped`: not checked (no `read`, or an interrupted deploy); see `reason`. */
+  readonly status: "in-sync" | "drifted" | "missing" | "skipped";
+  readonly reason?: string;
+  readonly actual?: unknown;
+}
+
+/** A drift check and the repair it proposes; only {@link execute} runs it. */
+export interface DriftScan {
+  readonly stack: { readonly name: string; readonly stage: string };
+  readonly resources: ReadonlyArray<DriftedResource>;
+  /** What the repair would change. */
+  readonly summary: PlanSummary;
+  /**
+   * The repair as an engine plan, for renderers.
+   * @internal its shape may change.
+   */
+  readonly native: Plan;
+  /**
+   * The stack services drift was checked under.
+   * @internal {@link execute} runs in them.
+   */
+  readonly context: Context.Context<State>;
+}
+
+export interface ScanOptions extends BuildOptions {
+  readonly stack: ConfiguredStack<unknown, unknown>;
+}
+
+/** Whether the drift check found anything worth repairing. */
+export const hasDrift = (scan: DriftScan): boolean =>
+  scan.resources.some((resource) => resource.status === "drifted" || resource.status === "missing");
+
+const status = (action: string): DriftedResource["status"] =>
+  action === "unchanged"
+    ? "in-sync"
+    : action === "missing" || action === "skipped"
+      ? action
+      : "drifted";
+
+/**
+ * Compare deployed state against the real cloud and plan the repair. Drift
+ * reads state and providers only, so the stack's program never runs.
+ */
+export const scan = Effect.fn("Alchemist.Drift.scan")(function* (input: ScanOptions) {
+  const built = yield* buildWithoutProgram(input.stack, input);
+  const identity = {
+    name: built.stack.name,
+    stage: built.stack.stage,
+  };
+  // The engine's phase and per-resource observation events flow through the
+  // log as events; drift-flavored wording is the renderer's job
+  // (renderPlanning's computingLabel).
+  const { result, plan } = yield* EngineDrift.plan(identity).pipe(Effect.provide(built.context));
+  yield* emit({ type: "plan.phase", phase: "plan-ready" });
+  return {
+    stack: identity,
+    resources: Object.values(result.resources).map((resource) => ({
+      fqn: resource.fqn,
+      logicalId: resource.logicalId,
+      resourceType: resource.resourceType,
+      status: status(resource.action),
+      reason: resource.reason,
+      actual: resource.attr,
+    })),
+    summary: summarize(plan),
+    native: plan,
+    context: built.context,
+  } satisfies DriftScan;
+});
+
+/**
+ * Repair the drift `scan` found: reconcile each drifted or missing resource
+ * back to its last-deployed desired state. Only those resources are touched;
+ * they are re-read first, so one that is back in sync is left alone, and
+ * drift that appeared after the scan waits for the next one.
+ */
+export const execute = Effect.fn("Alchemist.Drift.execute")(function* (scan: DriftScan) {
+  const only = scan.resources
+    .filter((resource) => resource.status === "drifted" || resource.status === "missing")
+    .map((resource) => resource.fqn);
+  return yield* Effect.provide(
+    EngineDrift.repair({ name: scan.stack.name, stage: scan.stack.stage }, { only }),
+    scan.context,
+  );
+});

package/src/Alchemist/Entrypoint.ts

@@ -1,7 +1,12 @@
+import { pathToFileURL } from "node:url";
+import * as Context from "effect/Context";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
+import * as Predicate from "effect/Predicate";
+import { emit } from "../Events.ts";
+import type { ConfiguredStack } from "../Stack.ts";
 import { UserFacingError } from "../UserFacingError.ts";
 
 export class StackEntrypointError extends Data.TaggedError("StackEntrypointError")<{
@@ -14,9 +19,8 @@ export const DEFAULT_ENTRYPOINT = "alchemy.run.ts";
 
 /**
  * The absolute path of the stack entrypoint, or the user-facing error for
- * a missing one. Kept apart from `Session.ts` so the `alchemy dev`
- * supervisor can check the entry before it starts an exec child, without
- * loading the engine that module carries.
+ * a missing one. Kept free of the engine so the `alchemy dev` supervisor can
+ * check the entry before it starts an exec child.
  */
 export const resolveStackEntrypoint = Effect.fn(function* (main: string) {
   const fs = yield* FileSystem.FileSystem;
@@ -29,3 +33,47 @@ export const resolveStackEntrypoint = Effect.fn(function* (main: string) {
   }
   return absolutePath;
 });
+
+export interface StackModuleLoader {
+  readonly import: (url: string) => Promise<{ readonly default?: unknown }>;
+}
+
+export const StackModuleLoader = Context.Reference<StackModuleLoader>(
+  "Alchemy/Alchemist/StackModuleLoader",
+  { defaultValue: () => ({ import: (url) => import(url) }) },
+);
+
+/**
+ * Import a stack entrypoint and return its default export, the stack value
+ * every stack operation takes.
+ */
+export const importStack = Effect.fn("Alchemist.importStack")(function* (main: string) {
+  yield* emit({ type: "plan.phase", phase: "importing-module" });
+  const absolutePath = yield* resolveStackEntrypoint(main);
+  const loader = yield* StackModuleLoader;
+  const module = yield* Effect.promise(() => loader.import(pathToFileURL(absolutePath).href));
+  if (
+    !Effect.isEffect(module.default) ||
+    !Predicate.hasProperty(module.default, "stackName") ||
+    typeof module.default.stackName !== "string"
+  ) {
+    return yield* new StackEntrypointError({
+      message: `Stack entrypoint '${main}' must export a default stack definition (export default Alchemy.Stack({...})).`,
+    });
+  }
+  // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- default export shape validated at runtime above
+  return module.default as ConfiguredStack<unknown, unknown>;
+});
+
+/**
+ * Which project and credentials an operation acts under. The optional fields
+ * fall back to the same defaults the CLI uses.
+ */
+export interface Target {
+  /** Stack entrypoint. @default "alchemy.run.ts" */
+  readonly entrypoint?: string;
+  /** Profile whose credentials the run uses. Falls back to the active profile. */
+  readonly profile?: string;
+  /** `.env` file layered under the process environment. */
+  readonly envFile?: string;
+}

package/src/Alchemist/Errors.ts

@@ -13,7 +13,7 @@ export interface Diagnostic {
 // `InvalidInput` — and these errors travel in unions with cloud errors,
 // where `catchTag` discriminates by tag alone.
 
-/** The caller sent something the route cannot act on. */
+/** The caller sent something the operation cannot act on. */
 export class AlchemistInvalidInput extends Data.TaggedError("AlchemistInvalidInput")<{
   readonly message: string;
   readonly field?: string;

package/src/Alchemist/{routes/logs.ts → Logs.ts}

@@ -1,12 +1,11 @@
-import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
 import * as Stream from "effect/Stream";
-import { findProviderByType } from "../../Provider.ts";
-import { stampedMode } from "../../ProviderMode.ts";
-import * as State from "../../State/index.ts";
-import { AlchemistInvalidInput } from "../Errors.ts";
-import { open, type StackTarget } from "../Session.ts";
+import { findProviderByType } from "../Provider.ts";
+import { stampedMode } from "../ProviderMode.ts";
+import type { ConfiguredStack } from "../Stack.ts";
+import * as State from "../State/index.ts";
+import { AlchemistInvalidInput } from "./Errors.ts";
+import { buildStack, type BuildOptions } from "./Operations.ts";
 
 export interface ResourceIdentity {
   readonly fqn: string;
@@ -25,32 +24,29 @@ export interface LogEntry {
   readonly message: string;
 }
 
-export interface LogInput {
-  readonly target: StackTarget;
+export interface LogOptions extends BuildOptions {
+  readonly stack: ConfiguredStack<unknown, unknown>;
   /** Logical IDs to include. Empty or omitted means every resource. */
   readonly resources?: ReadonlyArray<string>;
 }
 
-export interface QueryInput extends LogInput {
+export interface QueryOptions extends LogOptions {
   readonly limit?: number;
   readonly since?: Date;
 }
 
 /**
- * Open the stack and pair every deployed resource with the provider that
+ * Build the stack and pair every deployed resource with the provider that
  * can speak for it. `entries` and `tail` differ only in which provider hook
- * they then call, so the selection lives here once.
+ * they then call, so the selection lives here once. The build lives in the
+ * ambient `Scope`; each public function closes its own.
  */
-const select = Effect.fn(function* (input: LogInput) {
-  const session = yield* open(input.target);
-  // The local store sits UNDER the session context, so the stack's own
-  // store wins where it configures one: a project may only wire a remote
-  // store at deploy time, and `alchemy logs` still has to resolve what was
-  // deployed.
-  const context = Context.merge(yield* Layer.build(State.localState()), session.context);
+const select = Effect.fn(function* (input: LogOptions) {
+  const built = yield* buildStack(input.stack, input);
+  const context = built.context;
   const selected = new Set(input.resources ?? []);
   const available = [
-    ...new Set(Object.values(session.stack.resources).map((resource) => resource.LogicalId)),
+    ...new Set(Object.values(built.stack.resources).map((resource) => resource.LogicalId)),
   ].sort();
   const unknown = [...selected].find((name) => !available.includes(name));
   if (unknown !== undefined) {
@@ -61,15 +57,15 @@ const select = Effect.fn(function* (input: LogInput) {
   }
   const rows = yield* Effect.provide(
     Effect.gen(function* () {
-      const state = yield* yield* State.State;
-      return yield* Effect.forEach(Object.entries(session.stack.resources), ([fqn, resource]) =>
+      const state = yield* Effect.flatten(State.State);
+      return yield* Effect.forEach(Object.entries(built.stack.resources), ([fqn, resource]) =>
         Effect.gen(function* () {
           if (selected.size > 0 && !selected.has(resource.LogicalId)) {
             return [];
           }
           const stored = yield* state.get({
-            stack: session.stack.name,
-            stage: session.stack.stage,
+            stack: built.stack.name,
+            stage: built.stack.stage,
             fqn,
           });
           if (!State.isResourceState(stored) || stored.attr === undefined) {
@@ -101,17 +97,19 @@ const select = Effect.fn(function* (input: LogInput) {
 });
 
 /** Every deployed resource, with the log capabilities its provider offers. */
-export const resources = Effect.fn("Alchemist.logs.resources")(function* (target: StackTarget) {
-  const { rows } = yield* select({ target });
+export const resources = Effect.fn("Alchemist.Logs.resources")(function* (
+  options: BuildOptions & { readonly stack: ConfiguredStack<unknown, unknown> },
+) {
+  const { rows } = yield* select(options);
   return rows.map(({ resource, provider }): LogResource => ({
     ...resource,
     supportsQuery: provider.logs !== undefined,
     supportsTail: provider.tail !== undefined,
   }));
-});
+}, Effect.scoped);
 
 /** Query past log entries across the selected resources, oldest first. */
-export const entries = Effect.fn("Alchemist.logs.entries")(function* (input: QueryInput) {
+export const entries = Effect.fn("Alchemist.Logs.entries")(function* (input: QueryOptions) {
   const { context, rows } = yield* select(input);
   const entries = yield* Effect.provide(
     Effect.forEach(rows, ({ resource, provider, request }) =>
@@ -138,10 +136,10 @@ export const entries = Effect.fn("Alchemist.logs.entries")(function* (input: Que
     context,
   );
   return entries.flat().sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
-});
+}, Effect.scoped);
 
 /** Live-stream log entries from every selected resource that supports it. */
-export const tail = (input: LogInput) =>
+export const tail = (input: LogOptions) =>
   Stream.unwrap(
     Effect.gen(function* () {
       const { context, rows } = yield* select(input);

package/src/Alchemist/Nuke.ts

@@ -0,0 +1,90 @@
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Nuke from "../Nuke.ts";
+import type { ProviderMode } from "../ProviderMode.ts";
+import type { ConfiguredStack } from "../Stack.ts";
+import { buildProviders, type ConfigOptions } from "./Operations.ts";
+
+export interface ScanOptions extends ConfigOptions {
+  /** The stack whose providers are scanned; nothing reads its state. */
+  readonly stack: ConfiguredStack<unknown, unknown>;
+  /** Scan the emulators `alchemy dev` runs instead of the real cloud. */
+  readonly dev?: boolean;
+  /** Provider-id globs to include. Omitted means every provider. */
+  readonly include?: ReadonlyArray<string>;
+  /** Provider-id globs to exclude. Applied after `include`. */
+  readonly exclude?: ReadonlyArray<string>;
+  /** Providers scanned in parallel. @default 16 */
+  readonly concurrency?: number | "unbounded";
+  /** Timeout for each provider's `list`. @default 120 */
+  readonly providerTimeoutSeconds?: number;
+}
+
+/** One discovered cloud object, bound to the provider that can delete it. */
+export type Resource = Nuke.Target;
+
+/** Everything a stack's providers can see; only {@link execute} deletes it. */
+export interface NukeScan {
+  /** `local` when the scan ran with `dev: true`, otherwise `live`. */
+  readonly mode: ProviderMode;
+  readonly resources: ReadonlyArray<Resource>;
+  /** Providers whose `list` failed; they contribute no resources. */
+  readonly failures: ReadonlyArray<Nuke.ProviderFailure>;
+  /**
+   * The built provider context; lives in the caller's `Scope`.
+   * @internal {@link execute} deletes under it.
+   */
+  readonly context: Context.Context<never>;
+}
+
+/**
+ * List everything the stack's registered providers can see in the account.
+ * The stack is imported only for its providers: nothing here reads state or
+ * is scoped to a stage.
+ */
+export const scan = Effect.fn("Alchemist.Nuke.scan")(function* (options: ScanOptions) {
+  const mode: ProviderMode = options.dev ? "local" : "live";
+  const context = yield* buildProviders(options.stack, options);
+  const { resources, failures } = yield* Nuke.list({
+    context,
+    mode,
+    include: options.include,
+    exclude: options.exclude,
+    concurrency: options.concurrency,
+    timeoutSeconds: options.providerTimeoutSeconds,
+  });
+  return { mode, resources, failures, context } satisfies NukeScan;
+});
+
+export interface ExecuteOptions {
+  /** The scan whose resources are deleted. */
+  readonly scan: NukeScan;
+  /** The subset of `scan.resources` to delete. @default every planned resource */
+  readonly resources?: ReadonlyArray<Resource>;
+  /**
+   * `coordinated` deletes in passes until one makes no progress;
+   * `independent` retries each resource on its own.
+   * @default { type: "coordinated" }
+   */
+  readonly strategy?: Nuke.Strategy;
+  /** Providers deleted in parallel. @default 16 */
+  readonly concurrency?: number | "unbounded";
+  /** Timeout for each `delete`. @default 120 */
+  readonly providerTimeoutSeconds?: number;
+}
+
+export type Result = Nuke.Result;
+
+/**
+ * Permanently delete scanned resources. Progress is emitted through
+ * events: `apply.resource.status` and `nuke.*` events.
+ */
+export const execute = Effect.fn("Alchemist.Nuke.execute")(function* (options: ExecuteOptions) {
+  return yield* Nuke.destroy({
+    targets: options.resources ?? options.scan.resources,
+    context: options.scan.context,
+    strategy: options.strategy ?? { type: "coordinated" },
+    concurrency: options.concurrency,
+    timeoutSeconds: options.providerTimeoutSeconds,
+  });
+});