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

package/src/Alchemist/Operations.ts

@@ -0,0 +1,309 @@
+/**
+ * The core of the Alchemist operations: the builds they choose from (with
+ * or without the stack's program, or providers only), and the stack
+ * {@link plan} → {@link apply} pair deploys and destroys share. Drift and
+ * nuke have their own namespaces.
+ */
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Context from "effect/Context";
+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 { CurrentLogAnnotations, CurrentLogSpans, MinimumLogLevel } from "effect/References";
+import * as Tracer from "effect/Tracer";
+import { AdoptPolicy } from "../AdoptPolicy.ts";
+import { AlchemyContext } from "../AlchemyContext.ts";
+import * as Apply from "../Apply.ts";
+import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
+import { withProfileOverride } from "../Auth/Resolve.ts";
+import { emit, type PlannedAction, type PlannedResource } from "../Events.ts";
+import * as Plan from "../Plan.ts";
+import type { ResourceSelection, SelectionOutput } from "../ResourceSelection.ts";
+import * as Stack from "../Stack.ts";
+import { Stage } from "../Stage.ts";
+import type { State } from "../State/State.ts";
+import { loadConfigProvider, StackConfigOverrides } from "../Util/ConfigProvider.ts";
+
+/** Which credentials and config a stack build sees. */
+export interface ConfigOptions {
+  /** `.env` file layered under the process environment. */
+  readonly envFile?: string;
+  /** Profile whose credentials the run uses. Falls back to the active profile. */
+  readonly profile?: string;
+}
+
+export interface BuildOptions extends ConfigOptions {
+  readonly stage: string;
+  /** Run local (emulated) providers instead of the real cloud. */
+  readonly dev?: boolean;
+  /** Adopt pre-existing cloud resources instead of failing on conflict. */
+  readonly adopt?: boolean;
+  /** Upgrade an out-of-date state store without prompting. */
+  readonly updateStateStore?: boolean;
+}
+
+/** Config services shared by every stack build. */
+export const configServices = Effect.fn("Alchemist.configServices")(function* (
+  options: ConfigOptions,
+) {
+  const envFile = Option.fromNullishOr(options.envFile);
+  const commandConfig = yield* loadConfigProvider(envFile);
+  // `envFile` only steers a stack's default secrets list and `profile`
+  // pins the profile inside it; see stackConfigLayer.
+  return Layer.mergeAll(
+    Layer.succeed(StackConfigOverrides, {
+      envFile: options.envFile,
+      profile: options.profile,
+    }),
+    ConfigProvider.layer(withProfileOverride(commandConfig, options.profile)),
+  );
+});
+
+// TODO(unify stack builds): the one stack build everything should use; see
+// the TODO in `EvalStack.ts` for the other paths still to migrate here.
+
+/** The per-build services a stack's providers and program run under. */
+const buildServices = Effect.fn("Alchemist.buildServices")(function* (options: BuildOptions) {
+  yield* emit({ type: "plan.phase", phase: "resolving-services" });
+  return yield* Layer.build(
+    Layer.mergeAll(
+      Layer.effect(
+        AlchemyContext,
+        Effect.map(AlchemyContext, (context) => ({
+          ...context,
+          dev: options.dev ?? context.dev,
+          adopt: options.adopt ?? false,
+          updateStateStore: options.updateStateStore ?? false,
+        })),
+      ),
+      Layer.succeedContext(
+        Context.make(AdoptPolicy, options.adopt ?? false).pipe(
+          Context.add(ArtifactStore, createArtifactStore()),
+          Context.add(Stage, options.stage),
+        ),
+      ),
+      yield* configServices(options),
+    ),
+  );
+});
+
+/**
+ * The building fiber's logging and tracing, dropped from a built context:
+ * a plan or scan is applied later, and possibly under other loggers (an
+ * `onEvent` subscriber around `apply`), which providing the captured ones
+ * would silently replace.
+ */
+const withoutFiberLogging = Context.omit(
+  Logger.CurrentLoggers,
+  MinimumLogLevel,
+  CurrentLogAnnotations,
+  CurrentLogSpans,
+  Tracer.ParentSpan,
+);
+
+/**
+ * Build a stack's providers and state store and run its program.
+ *
+ * @internal used by {@link plan} and `Logs`.
+ */
+export const buildStack = Effect.fn("Alchemist.build")(function* <Output, Req>(
+  stack: Stack.ConfiguredStack<Output, Req>,
+  options: BuildOptions,
+) {
+  const baseContext = yield* buildServices(options);
+  const compiled = yield* Effect.provide(stack, baseContext);
+  return {
+    stack: compiled,
+    /** The stack's own providers and state store over the build's services. */
+    context: withoutFiberLogging(Context.merge(baseContext, compiled.services)),
+  };
+});
+
+/**
+ * Build a stack's providers and state store without running its program:
+ * all that destroy, drift, and state access need, and safe when the
+ * program itself no longer runs.
+ *
+ * @internal used by {@link plan}, `Drift.scan`, and `State.store`.
+ */
+export const buildWithoutProgram = Effect.fn("Alchemist.buildWithoutProgram")(function* <Req>(
+  stack: Stack.ConfiguredStack<unknown, Req>,
+  options: BuildOptions,
+) {
+  const baseContext = yield* buildServices(options);
+  const stackServices = yield* Effect.provide(
+    Stack.build({
+      name: stack.stackName,
+      providers: stack.providers,
+      state: stack.state,
+      secrets: stack.secrets,
+    }),
+    baseContext,
+  );
+  return {
+    stack: { ...Context.get(stackServices, Stack.Stack), output: undefined },
+    context: withoutFiberLogging(Context.merge(baseContext, stackServices)),
+  };
+});
+
+export interface PlanSummary {
+  readonly create: number;
+  readonly update: number;
+  readonly adopted: number;
+  readonly replace: number;
+  readonly delete: number;
+  readonly orphaned: number;
+  /** Actions that will run. */
+  readonly run: number;
+  readonly noop: number;
+}
+
+/** Whether a plan or drift scan proposes any cloud mutations (i.e. approval-worthy work). */
+export const hasChanges = ({ summary }: { readonly summary: PlanSummary }): boolean =>
+  summary.create +
+    summary.update +
+    summary.adopted +
+    summary.replace +
+    summary.delete +
+    summary.orphaned +
+    summary.run >
+  0;
+
+export const summarize = (plan: Plan.Plan): PlanSummary => {
+  const summary: { -readonly [K in keyof PlanSummary]: PlanSummary[K] } = {
+    create: 0,
+    update: 0,
+    adopted: 0,
+    replace: 0,
+    delete: 0,
+    orphaned: 0,
+    run: 0,
+    noop: 0,
+  };
+  for (const node of Object.values(plan.resources)) summary[node.action]++;
+  for (const node of Object.values(plan.actions)) summary[node.action]++;
+  for (const node of [...Object.values(plan.deletions), ...Object.values(plan.actionDeletions)]) {
+    if (node !== undefined) summary[node.action]++;
+  }
+  return summary;
+};
+
+/** The services a stack plan is applied under. */
+type StackContext = Context.Context<State | Stack.Stack | Stage>;
+
+/**
+ * A deploy or destroy plan: what will change, and the built stack it was
+ * planned against so {@link apply} runs without rebuilding.
+ */
+export interface StackPlan<Output = unknown> {
+  readonly stack: { readonly name: string; readonly stage: string };
+  readonly summary: PlanSummary;
+  /** Serializable resource rows (including orphan deletions). */
+  readonly resources: ReadonlyArray<PlannedResource>;
+  /** Serializable stack-action rows. */
+  readonly actions: ReadonlyArray<PlannedAction>;
+  /**
+   * The engine plan `apply` executes, for renderers.
+   * @internal its shape may change.
+   */
+  readonly native: Plan.Plan<Output>;
+  /**
+   * The stack services the plan was computed under; they live in the caller's `Scope`.
+   * @internal `apply` runs in them.
+   */
+  readonly context: StackContext;
+}
+
+/** Describe an engine plan computed on a built stack. */
+export const describeStackPlan = Effect.fn("Alchemist.describeStackPlan")(function* <Output>(
+  built: {
+    readonly stack: { readonly name: string; readonly stage: string };
+    readonly context: StackContext;
+  },
+  native: Plan.Plan<Output>,
+) {
+  yield* emit({ type: "plan.phase", phase: "plan-ready" });
+  return {
+    stack: { name: built.stack.name, stage: built.stack.stage },
+    summary: summarize(native),
+    ...Plan.describePlan(native),
+    native,
+    context: built.context,
+  } satisfies StackPlan<Output>;
+});
+
+/**
+ * Run the stack's program and plan what to create, update, replace, and
+ * delete so the stage matches it.
+ */
+export interface DeployPlanOptions extends BuildOptions, ResourceSelection {
+  readonly operation: "deploy";
+  /** Re-run every Action regardless of input drift. */
+  readonly force?: boolean;
+}
+
+/**
+ * Plan deleting everything the stage owns. The program never runs, so this
+ * works even when it no longer does. Always the whole stage.
+ */
+export interface DestroyPlanOptions extends BuildOptions {
+  readonly operation: "destroy";
+}
+
+export type PlanOptions = DeployPlanOptions | DestroyPlanOptions;
+
+/** What applying a plan made with `O` returns. */
+export type PlanOutput<Output, O extends PlanOptions> = O extends { readonly operation: "destroy" }
+  ? undefined
+  : SelectionOutput<Output, O>;
+
+/**
+ * Plan a deploy or a destroy of `stack`. A filtered deploy plan applies to
+ * `undefined` and leaves the persisted stack output untouched. The build,
+ * and the stage's state-store lease, stay open until the surrounding
+ * `Scope` closes.
+ */
+export const plan = Effect.fn("Alchemist.plan")(function* <
+  Output,
+  Req,
+  const O extends PlanOptions,
+>(input: O & { readonly stack: Stack.ConfiguredStack<Output, Req> }) {
+  if (input.operation === "destroy") {
+    const built = yield* buildWithoutProgram(input.stack, input);
+    const native = yield* Plan.destroy(built.stack).pipe(Effect.provide(built.context));
+    // SAFETY: `operation: "destroy"` is exactly when PlanOutput is `undefined`.
+    return (yield* describeStackPlan(built, native)) as StackPlan<PlanOutput<Output, O>>;
+  }
+  // `operation` is "deploy" here; a generic `O` doesn't narrow.
+  const deploy: DeployPlanOptions = input;
+  const built = yield* buildStack(input.stack, deploy);
+  const native = yield* Plan.make(built.stack, {
+    force: deploy.force,
+    include: deploy.include,
+    exclude: deploy.exclude,
+  }).pipe(Effect.provide(built.context));
+  // SAFETY: for `deploy`, PlanOutput is the selection's output.
+  return (yield* describeStackPlan(built, native)) as StackPlan<PlanOutput<Output, O>>;
+});
+
+/** Run a plan; a deploy returns the stack's output. */
+export const apply = Effect.fn("Alchemist.apply")(function* <Output>(plan: StackPlan<Output>) {
+  return yield* Effect.provide(Apply.apply(plan.native), plan.context);
+});
+
+/** Stage used when a stack's providers are built without addressing a deployment. */
+export const PLACEHOLDER_STAGE = "placeholder";
+
+/**
+ * Build a stack's providers and state store without running its program or
+ * addressing a stage: what account-wide operations like `Nuke.scan` need.
+ */
+export const buildProviders = <Req>(
+  stack: Stack.ConfiguredStack<unknown, Req>,
+  options: ConfigOptions = {},
+) =>
+  Effect.map(
+    buildWithoutProgram(stack, { ...options, stage: PLACEHOLDER_STAGE }),
+    (built) => built.context,
+  );

package/src/Alchemist/{routes/profile.ts → Profile.ts}

@@ -1,17 +1,18 @@
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Redacted from "effect/Redacted";
-import { AuthError } from "../../Auth/AuthProvider.ts";
-import { CredentialsStore } from "../../Auth/Credentials.ts";
-import { inspectProvider, type ProviderConnection } from "../../Auth/Inspect.ts";
-import { withProfileCredentialsLock } from "../../Auth/Lock.ts";
-import { ProfileStore } from "../../Auth/Profile.ts";
-import type { Interaction } from "../../Interaction.ts";
-import { AlchemistInvalidInput, AlchemistNotFound } from "../Errors.ts";
-import { Progress } from "../Progress.ts";
-import { collectAuthProviders, DEFAULT_ENTRYPOINT, type Target } from "../Session.ts";
+import { AuthError } from "../Auth/AuthProvider.ts";
+import { CredentialsStore } from "../Auth/Credentials.ts";
+import { inspectProvider, type ProviderConnection } from "../Auth/Inspect.ts";
+import { withProfileCredentialsLock } from "../Auth/Lock.ts";
+import { ProfileStore, reloadProviderConfig } from "../Auth/Profile.ts";
+import { emit } from "../Events.ts";
+import type { Interaction } from "../Interaction.ts";
+import { collectAuthProviders } from "./AuthRegistry.ts";
+import { DEFAULT_ENTRYPOINT, type Target } from "./Entrypoint.ts";
+import { AlchemistInvalidInput, AlchemistNotFound } from "./Errors.ts";
 
-/** Which project/profile pair a provider-scoped route resolves against. */
+/** Which project/profile pair a provider-scoped operation resolves against. */
 export interface ProviderContext extends Target {
   readonly profile: string;
 }
@@ -25,7 +26,7 @@ export interface ProfileSummary {
   }>;
 }
 
-export type { ProviderConnection } from "../../Auth/Inspect.ts";
+export type { ProviderConnection } from "../Auth/Inspect.ts";
 
 export interface ProfileSnapshot {
   readonly name: string;
@@ -139,7 +140,7 @@ export const get = Effect.fn("Alchemist.profile.get")(function* (input: {
                   }),
                 ),
               ),
-            )
+            ).pipe(Effect.provideService(ProfileStore, profiles))
           : Effect.succeed({
               name: provider,
               method: config.method ?? "unknown",
@@ -234,15 +235,14 @@ export const configureForm = Effect.fn("Alchemist.profile.configureForm")(functi
 
 /**
  * Connect or reconfigure a provider in a profile. Reported through
- * {@link Progress} as `ProviderConfigureStarted`; interactive providers drive
+ * the `provider.configure.started` event; interactive providers drive
  * their own prompts.
  */
 export const configure = Effect.fn("Alchemist.profile.configure")(function* (
   input: ConfigureInput,
 ) {
-  const report = yield* Progress;
-  yield* report({
-    _tag: "provider.configure.started",
+  yield* emit({
+    type: "provider.configure.started",
     provider: input.provider,
   });
   const profiles = yield* ProfileStore;
@@ -278,8 +278,8 @@ export const configure = Effect.fn("Alchemist.profile.configure")(function* (
             : undefined,
         );
   yield* profiles.setProviderConfig(input.profile, input.provider, config);
-  yield* report({
-    _tag: "provider.configure.completed",
+  yield* emit({
+    type: "provider.configure.completed",
     provider: input.provider,
   });
   return yield* get({
@@ -317,14 +317,13 @@ export const removeProvider = Effect.fn("Alchemist.profile.removeProvider")(func
 
 /**
  * Re-run login for connected providers without reconfiguring them. Each
- * provider is reported through {@link Progress} as `ProviderRefreshStarted`.
+ * provider is reported as the `provider.refresh.started` event.
  */
 export const refresh = Effect.fn("Alchemist.profile.refresh")(function* (
   input: ProviderContext & {
     readonly providers?: ReadonlyArray<string>;
   },
 ) {
-  const report = yield* Progress;
   const profiles = yield* ProfileStore;
   const stored = yield* profiles.ensureProfile(input.profile);
   const registered = yield* registry(input);
@@ -356,7 +355,7 @@ export const refresh = Effect.fn("Alchemist.profile.refresh")(function* (
         message: `Provider '${name}' is not connected or registered.`,
       });
     }
-    yield* report({ _tag: "provider.refresh.started", provider: name });
+    yield* emit({ type: "provider.refresh.started", provider: name });
     const refreshed = yield* provider.login(
       input.profile,
       yield* provider.decodeConfig(input.profile, config),
@@ -369,11 +368,12 @@ export const refresh = Effect.fn("Alchemist.profile.refresh")(function* (
             }),
           ),
         ),
+      reloadProviderConfig(profiles, provider, input.profile),
     );
     if (refreshed !== undefined) {
       yield* profiles.setProviderConfig(input.profile, name, refreshed);
     }
-    yield* report({ _tag: "provider.refresh.completed", provider: name });
+    yield* emit({ type: "provider.refresh.completed", provider: name });
   }
   return yield* get({
     name: input.profile,

package/src/Alchemist/{routes/provider.ts → Provider.ts}

@@ -1,12 +1,13 @@
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import type { EnvironmentVariable } from "../../Auth/AuthProvider.ts";
-import { getEnv } from "../../Auth/Env.ts";
-import { resolveProfileName } from "../../Auth/Resolve.ts";
-import { loadConfigProvider } from "../../Util/ConfigProvider.ts";
-import { AlchemistInvalidInput } from "../Errors.ts";
-import { collectAuthProviders, DEFAULT_ENTRYPOINT, type Target } from "../Session.ts";
+import type { EnvironmentVariable } from "../Auth/AuthProvider.ts";
+import { getEnv } from "../Auth/Env.ts";
+import { resolveProfileName } from "../Auth/Resolve.ts";
+import { loadConfigProvider } from "../Util/ConfigProvider.ts";
+import { collectAuthProviders } from "./AuthRegistry.ts";
+import { DEFAULT_ENTRYPOINT, type Target } from "./Entrypoint.ts";
+import { AlchemistInvalidInput } from "./Errors.ts";
 
 export interface CheckEnvironmentInput extends Target {
   /** Providers to check. Omitted means every registered provider. */

package/src/Alchemist/Runtime.ts

@@ -1,20 +1,56 @@
 import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
 import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type { HttpClient } from "effect/http/HttpClient";
 import * as Layer from "effect/Layer";
-import { AlchemyContextLive } from "../AlchemyContext.ts";
+import * as Logger from "effect/Logger";
+import * as LogLevel from "effect/LogLevel";
+import type { PlatformError } from "effect/PlatformError";
+import { type AlchemyContext, AlchemyContextLive } from "../AlchemyContext.ts";
 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
-import { CredentialsStoreLive } from "../Auth/Credentials.ts";
-import { ProfileStoreLive } from "../Auth/Profile.ts";
+import { type CredentialsStore, CredentialsStoreLive } from "../Auth/Credentials.ts";
+import { type ProfileStore, ProfileStoreLive } from "../Auth/Profile.ts";
 import * as Interaction from "../Interaction.ts";
+import { makePlainConsoleSink } from "../Util/ConsoleSink.ts";
 import { PlatformServices } from "../Util/PlatformServices.ts";
-import { routeCacheLayer } from "./Session.ts";
+import { authRegistryLayer } from "./AuthRegistry.ts";
+
+/** The services {@link layer} provides; every Alchemist operation runs under them. */
+export type Services =
+  | AlchemyContext
+  | ArtifactStore
+  | CredentialsStore
+  | HttpClient
+  | Interaction.Interaction
+  | ProfileStore
+  | PlatformServices;
+
+/**
+ * Log lines on the console. The caller's own loggers stay; only Effect's
+ * default console logger gives way to this sink, so lines print once. Typed
+ * events are left to `onEvent` subscribers (a renderer, or the caller's own
+ * handler).
+ *
+ * Info and above only: records replayed from sidecars and child processes
+ * bypass the fiber's minimum level, so the sink applies its own.
+ */
+const consoleSink = makePlainConsoleSink();
+const ConsoleLog = Layer.unwrap(
+  Effect.map(Logger.CurrentLoggers, (current) =>
+    Logger.layer([
+      ...[...current].filter((logger) => logger !== Logger.defaultLogger),
+      Logger.make<unknown, void>((options) => {
+        if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Info")) consoleSink.log(options);
+      }),
+    ]),
+  ),
+);
 
 /**
  * All services required by the programmatic Alchemist API.
  *
- * Progress reporting remains caller-controlled: without an override the
- * default reporter is a no-op, while interactive and plain renderers can
- * provide {@link import("./Progress.ts").Progress} around individual calls.
+ * Log lines print on the console. Typed events are log records too; observe
+ * them around a call with {@link import("../Events.ts").onEvent}.
  * The non-interactive Interaction default serves the engine paths that need
  * one (state-store confirms fail typed; profile probes never prompt).
  *
@@ -25,10 +61,7 @@ import { routeCacheLayer } from "./Session.ts";
  * )
  * ```
  */
-/** The services {@link layer} provides; every Alchemist route runs under them. */
-export type Services = Layer.Success<ReturnType<typeof layer>>;
-
-export const layer = () =>
+export const layer = (): Layer.Layer<Services, PlatformError> =>
   Layer.mergeAll(
     Layer.mergeAll(AlchemyContextLive, ProfileStoreLive, CredentialsStoreLive).pipe(
       Layer.provideMerge(PlatformServices),
@@ -36,6 +69,7 @@ export const layer = () =>
     FetchHttpClient.layer,
     ConfigProvider.layer(ConfigProvider.fromEnv()),
     Layer.succeed(ArtifactStore, createArtifactStore()),
-    routeCacheLayer,
     Interaction.layerNonInteractive(),
+    ConsoleLog,
+    authRegistryLayer,
   );