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

package/src/Report.ts

@@ -0,0 +1,365 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type { NonInteractiveTerminal } from "./Interaction.ts";
+import type { Plan } from "./Plan.ts";
+import type { ProviderMode } from "./ProviderMode.ts";
+
+// The engine's reporting contract: the events apply/sync emit while they
+// converge a plan, and the session/renderer interfaces a presentation layer
+// (the bundled CLI, a custom renderer, tests) implements to observe them.
+// Deliberately presentation-free — nothing in here knows about terminals.
+
+export type ApplyStatus =
+  | "attaching"
+  | "post-attach"
+  | "pending"
+  | "pre-creating"
+  | "creating"
+  | "creating replacement"
+  | "created"
+  | "updating"
+  | "updated"
+  | "adopting"
+  | "adopted"
+  | "deleting"
+  | "deleted"
+  | "orphaning"
+  | "orphaned"
+  | "replacing"
+  | "replaced"
+  // Action lifecycle (see {@link Action})
+  | "running"
+  | "ran"
+  | "skipped"
+  | "fail";
+
+export type ApplyEvent = ResourceAnnotated | ResourceStatusChanged;
+
+/**
+ * How append-only renderers surface a note (the interactive view treats every
+ * kind the same): `"status"` is transient spinner text that plain mode folds
+ * into the settle line's suffix, `"output"` is verbatim tool output streamed
+ * line by line, and `undefined` is a one-shot informational note.
+ */
+export type NoteKind = "status" | "output";
+
+export interface ResourceAnnotated {
+  _tag: "apply.resource.note";
+  /** Fully-qualified resource or action name used to target its plan row. */
+  fqn: string;
+  id: string;
+  message: string;
+  kind?: NoteKind;
+}
+
+export interface ResourceStatusChanged {
+  _tag: "apply.resource.status";
+  /** Fully-qualified resource or action name used to target its plan row. */
+  fqn: string;
+  id: string; // resource id (e.g. "messages", "api")
+  type: string; // resource type (e.g. "AWS::Lambda::Function", "Cloudflare::Worker")
+  status: ApplyStatus;
+  message?: string; // optional details
+  /**
+   * The {@link ProviderMode} this node's provider was resolved for.
+   * `undefined` for mode-agnostic providers (a single implementation serves
+   * both dev and deploy) and for actions — renderers show nothing special.
+   */
+  providerMode?: ProviderMode;
+  /**
+   * Set only on mode-switch replacements (local ⇄ live): the mode the OLD
+   * generation was created with, so renderers can annotate the transition
+   * (e.g. `local → live`). Always differs from `providerMode` when set.
+   */
+  fromProviderMode?: ProviderMode;
+}
+
+/** One binding row on a planned resource. */
+export interface PlannedBinding {
+  readonly sid: string;
+  readonly action: "create" | "update" | "delete" | "noop";
+}
+
+/** Serializable view of one resource row in a plan. */
+export interface PlannedResource {
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly resourceType: string;
+  /** The action the plan decided for this resource. */
+  readonly action:
+    | "create"
+    | "update"
+    | "adopted"
+    | "replace"
+    | "delete"
+    | "orphaned"
+    | "noop";
+  /** Binding rows the node carries; empty when the resource has none. */
+  readonly bindings: ReadonlyArray<PlannedBinding>;
+  /** Mode the node's provider resolved for; absent for mode-agnostic providers. */
+  readonly providerMode?: ProviderMode;
+  /** On mode-switch replacements: the mode the old generation was created with. */
+  readonly fromProviderMode?: ProviderMode;
+}
+
+/** Serializable view of one stack-action row in a plan. */
+export interface PlannedAction {
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly actionType: string;
+  readonly action: "run" | "delete" | "noop";
+}
+
+/**
+ * Emitted as a resource's diff begins. Diffs run with unbounded concurrency
+ * and may read the cloud (refresh, adoption), so a renderer that only sees
+ * completions freezes on the last *finished* node while the slow tail is
+ * still working — pairing starts with {@link ResourcePlanned} lets it show
+ * what is actually in flight.
+ */
+export interface ResourceDiffStarted {
+  readonly _tag: "plan.resource.started";
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly resourceType: string;
+  readonly total: number;
+}
+
+/** Emitted as the planner finishes diffing one resource. */
+export interface ResourcePlanned extends PlannedResource {
+  readonly _tag: "plan.resource.completed";
+  /** How many of `total` resources have been diffed so far. */
+  readonly completed: number;
+  readonly total: number;
+}
+
+/** Emitted as the planner decides one stack action. */
+export interface ActionPlanned extends PlannedAction {
+  readonly _tag: "plan.action.completed";
+  readonly completed: number;
+  readonly total: number;
+}
+
+/** Phases a stack plan moves through before it is ready. */
+export type PlanningPhase =
+  | "importing-module"
+  | "resolving-services"
+  | "loading-state"
+  | "computing-plan"
+  | "plan-ready";
+
+/**
+ * Emitted as the planning pipeline crosses a work boundary, by whoever owns
+ * that boundary: the session emits `importing-module`/`resolving-services`
+ * around the module import and service build, the engine emits
+ * `loading-state` (before the state service resolves — which may bootstrap
+ * a remote store — and the persisted rows are read) and `computing-plan`
+ * (once diffing begins), and the route emits `plan-ready`. Carries no
+ * display text — wording is the renderer's job.
+ */
+export interface PlanPhaseChanged {
+  readonly _tag: "plan.phase";
+  readonly phase: PlanningPhase;
+}
+
+/** A per-node planning event (one resource or action diffed). */
+export type PlanNodeEvent =
+  | ResourceDiffStarted
+  | ResourcePlanned
+  | ActionPlanned;
+
+export type PlanEvent = PlanPhaseChanged | PlanNodeEvent;
+
+/**
+ * Emitted around a state-store bootstrap or upgrade (e.g. deploying the
+ * Cloudflare state-store worker on first use). Bootstrap happens lazily
+ * inside "loading state", can take many seconds, and would otherwise be
+ * invisible to renderers and traces.
+ */
+export interface StateBootstrapStarted {
+  readonly _tag: "state.bootstrap.started";
+  /** The store being bootstrapped (e.g. the worker script name). */
+  readonly store: string;
+}
+
+export interface StateBootstrapCompleted {
+  readonly _tag: "state.bootstrap.completed";
+  readonly store: string;
+}
+
+export type StateEvent = StateBootstrapStarted | StateBootstrapCompleted;
+
+export interface NukeScanStarted {
+  readonly _tag: "nuke.scan.started";
+  readonly total: number;
+}
+
+export interface NukeProviderScanStarted {
+  readonly _tag: "nuke.scan.provider.started";
+  readonly provider: string;
+}
+
+export interface NukePassStarted {
+  readonly _tag: "nuke.pass.started";
+  readonly pass: number;
+}
+
+/** Emitted as a nuke scan finishes enumerating one provider's resources. */
+export interface NukeProviderScanned {
+  readonly _tag: "nuke.scan.provider.completed";
+  readonly provider: string;
+  /** Resources found for this provider (0 when the listing failed). */
+  readonly resources: number;
+  /** Listing failure, reported immediately when this provider settles. */
+  readonly error?: string;
+}
+
+export interface NukeResourceDeleted {
+  readonly _tag: "nuke.resource.deleted";
+  readonly provider: string;
+  /** Display name of the deleted resource. */
+  readonly resource: string;
+}
+
+/** Emitted when a nuke deletion attempt fails (the run keeps going). */
+export interface NukeResourceFailed {
+  readonly _tag: "nuke.resource.failed";
+  readonly provider: string;
+  readonly resource: string;
+  readonly message: string;
+}
+
+export type NukeEvent =
+  | NukeScanStarted
+  | NukeProviderScanStarted
+  | NukePassStarted
+  | NukeProviderScanned
+  | NukeResourceDeleted
+  | NukeResourceFailed;
+
+export interface ProviderConfigureStarted {
+  readonly _tag: "provider.configure.started";
+  readonly provider: string;
+}
+
+export interface ProviderConfigureCompleted {
+  readonly _tag: "provider.configure.completed";
+  readonly provider: string;
+}
+
+export interface ProviderRefreshStarted {
+  readonly _tag: "provider.refresh.started";
+  readonly provider: string;
+}
+
+export interface ProviderRefreshCompleted {
+  readonly _tag: "provider.refresh.completed";
+  readonly provider: string;
+}
+
+export type ProviderEvent =
+  | ProviderConfigureStarted
+  | ProviderConfigureCompleted
+  | ProviderRefreshStarted
+  | ProviderRefreshCompleted;
+
+/**
+ * Every progress event the engine and the Alchemist routes can report — one
+ * flat union, one `_tag` discriminator, tags namespaced `domain.subject.verb`.
+ */
+export type ProgressEvent =
+  | PlanEvent
+  | ApplyEvent
+  | StateEvent
+  | NukeEvent
+  | ProviderEvent;
+
+export type ProgressReporter = (event: ProgressEvent) => Effect.Effect<void>;
+
+/**
+ * The one ambient progress channel. Everything long-running — the planner's
+ * phase/node events, state-store bootstrap, nuke scans and deletions,
+ * provider configure/refresh — reports through it. Defaults to a no-op, so
+ * a caller that only wants the result provides nothing; a renderer provides
+ * its own handler for the events it wants to observe.
+ */
+export const Progress = Context.Reference<ProgressReporter>(
+  "alchemy/Progress",
+  { defaultValue: (): ProgressReporter => () => Effect.void },
+);
+
+export interface PlanStatusSession {
+  emit: (event: ApplyEvent) => Effect.Effect<void>;
+  done: (outcome: "success" | "failure") => Effect.Effect<void>;
+  /** Replace the dev widget's stack output view without writing scrollback. */
+  setOutput?: (value: unknown) => Effect.Effect<void>;
+  /**
+   * Tear down the session's live presentation without settling it. Dev keeps
+   * its widget mounted after `done`; an interrupted generation (reload,
+   * Ctrl+C) must remove it so the next generation does not stack another.
+   */
+  close?: Effect.Effect<void>;
+}
+
+/** A session that drops everything — the default when no renderer is ambient. */
+export const noopSession: PlanStatusSession = {
+  emit: () => Effect.void,
+  done: () => Effect.void,
+};
+
+export interface PlanningStatusSession {
+  update: (
+    label: string,
+    detail?: string,
+    options?: {
+      /**
+       * Animate the status glyph. Pass `false` for phases whose work runs
+       * synchronously on the main thread (e.g. module import) — a spinner
+       * cannot animate while the event loop is blocked, so it freezes
+       * mid-frame and reads as hung; a static row doesn't promise motion.
+       */
+      readonly spinning?: boolean;
+    },
+  ) => Effect.Effect<void>;
+  succeed: (message?: string) => Effect.Effect<void>;
+  fail: (message?: string) => Effect.Effect<void>;
+  close: Effect.Effect<void>;
+}
+
+export interface ScopedPlanStatusSession extends PlanStatusSession {
+  note: (
+    note: string,
+    options?: { readonly kind?: NoteKind },
+  ) => Effect.Effect<void>;
+}
+
+export interface PlanDisplayOptions {
+  /** Show declared resource inputs as structured YAML. */
+  detailed?: boolean;
+  /** Stage displayed in terminal lifecycle updates. */
+  stage?: string;
+  /** Keep the dev plan mounted as a collapsible widget below static logs. */
+  dev?: boolean;
+}
+
+export interface CLIService {
+  startPlanningSession: (
+    label: string,
+    detail?: string,
+    title?: string,
+  ) => Effect.Effect<PlanningStatusSession>;
+  approvePlan: <P extends Plan>(
+    plan: P,
+    options?: PlanDisplayOptions,
+  ) => Effect.Effect<boolean, NonInteractiveTerminal>;
+  displayPlan: <P extends Plan>(
+    plan: P,
+    options?: PlanDisplayOptions,
+  ) => Effect.Effect<void>;
+  startApplySession: <P extends Plan>(
+    plan: P,
+    options?: PlanDisplayOptions,
+  ) => Effect.Effect<PlanStatusSession>;
+}
+
+export class Cli extends Context.Service<Cli, CLIService>()("CLI") {}

package/src/Stack.ts

@@ -1,6 +1,7 @@
 import type { ConfigError } from "effect/Config";
 import { ConfigProvider } from "effect/ConfigProvider";
 import * as Context from "effect/Context";
+import type { Crypto } from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import { FileSystem } from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -16,8 +17,11 @@ import { AlchemyContext, AlchemyContextLive } from "./AlchemyContext.ts";
 import { type ArtifactStore, provideFreshArtifactStore } from "./Artifacts.ts";
 import { AuthProviders } from "./Auth/AuthProvider.ts";
 import { CredentialsStore, CredentialsStoreLive } from "./Auth/Credentials.ts";
-import { AlchemyProfile, ProfileLive } from "./Auth/Profile.ts";
-import { Cli } from "./Cli/Cli.ts";
+import { ProfileStore, ProfileStoreLive } from "./Auth/Profile.ts";
+// Type-only: with verbatimModuleSyntax a value import would survive emit and
+// drag the terminal helpers (node:tty, string-width) into every unbundled
+// child process that loads Stack.ts.
+import type { Interaction } from "./Interaction.ts";
 import type { Input, InputProps } from "./Input.ts";
 import * as Output from "./Output.ts";
 import type { Provider, ProviderCollectionLike } from "./Provider.ts";
@@ -34,15 +38,16 @@ export type StackServices =
   | Stage
   | Scope.Scope
   | FileSystem
+  | Crypto
   | Path
   | AlchemyContext
   | HttpClient
   | ChildProcessSpawner
   | AuthProviders
-  | AlchemyProfile
+  | ProfileStore
   | ArtifactStore
   | CredentialsStore
-  | Cli;
+  | Interaction;
 
 export type ProviderServices =
   | ProviderCollectionLike
@@ -73,8 +78,8 @@ export type StackEffect<A, Err = never, Req = never> = Effect.Effect<
   | Scope.Scope
   | AuthProviders
   | AlchemyContext
-  | Cli
-  | AlchemyProfile
+  | Interaction
+  | ProfileStore
   | CredentialsStore
   | ArtifactStore
   | State
@@ -305,13 +310,12 @@ const platform = Layer.mergeAll(
   PlatformServices,
   FetchHttpClient.layer,
   Logger.layer([fileLogger("out")], { mergeWithExisting: true }),
-  Layer.provide(ProfileLive, PlatformServices),
+  Layer.provide(ProfileStoreLive, PlatformServices),
   Layer.provide(CredentialsStoreLive, PlatformServices),
 );
 // override alchemy state store, CLI/reporting, state, and Config
 const alchemy = (overrides?: { dev?: boolean }) =>
   Layer.mergeAll(
-    // CLI.inkCLI(),
     // optional
     overrides?.dev
       ? Layer.provide(

package/src/State/Export.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
-import type { PersistedState, StateService, StateStoreError } from "./State.ts";
+import { State, type PersistedState } from "./State.ts";
+import { allStages } from "./Tree.ts";
 
 /**
  * One resource record in a state export, addressed by the
@@ -40,8 +41,8 @@ export interface ExportStateFilter {
  * Read every resource record in scope from the state store as one
  * document.
  *
- * Traverses `listStacks → listStages → list → get` with the listing
- * fan-out unbounded and the per-resource reads bounded, so a whole
+ * Fans out over every `(stack, stage)` the store holds — see
+ * {@link allStages} — with the per-resource reads bounded, so a whole
  * estate is fetched in a single pass instead of a call per resource.
  * Records that disappear between `list` and `get` (a concurrent
  * deploy/destroy) are skipped rather than failing the export.
@@ -49,48 +50,28 @@ export interface ExportStateFilter {
  * Results are ordered deterministically: by stack, then stage, then
  * FQN.
  */
-export const exportState = (
-  state: StateService,
+export const exportState = Effect.fn("exportState")(function* (
   filter: ExportStateFilter = {},
-): Effect.Effect<StateExport, StateStoreError> =>
-  Effect.gen(function* () {
-    const stacks =
-      filter.stack !== undefined
-        ? [filter.stack]
-        : [...(yield* state.listStacks())].sort();
-
-    const perStack = yield* Effect.forEach(
-      stacks,
-      (stack) =>
-        Effect.gen(function* () {
-          const stages =
-            filter.stage !== undefined
-              ? [filter.stage]
-              : [...(yield* state.listStages(stack))].sort();
-          return yield* Effect.forEach(
-            stages,
-            (stage) =>
-              Effect.gen(function* () {
-                const fqns = [...(yield* state.list({ stack, stage }))].sort();
-                const records = yield* Effect.forEach(
-                  fqns,
-                  (fqn) =>
-                    Effect.map(state.get({ stack, stage, fqn }), (value) =>
-                      value === undefined
-                        ? undefined
-                        : ({ stack, stage, fqn, state: value } as const),
-                    ),
-                  { concurrency: 16 },
-                );
-                return records.filter(
-                  (r): r is ExportedResource => r !== undefined,
-                );
-              }),
-            { concurrency: "unbounded" },
-          );
-        }),
-      { concurrency: "unbounded" },
-    );
-
-    return { resources: perStack.flat(2) };
-  });
+) {
+  const state = yield* yield* State;
+  const perStage = yield* Effect.forEach(
+    yield* allStages(filter),
+    ({ stack, stage }) =>
+      Effect.gen(function* () {
+        const fqns = [...(yield* state.list({ stack, stage }))].sort();
+        const records = yield* Effect.forEach(
+          fqns,
+          (fqn) =>
+            Effect.map(state.get({ stack, stage, fqn }), (value) =>
+              value === undefined
+                ? undefined
+                : ({ stack, stage, fqn, state: value } as const),
+            ),
+          { concurrency: 16 },
+        );
+        return records.filter((r): r is ExportedResource => r !== undefined);
+      }),
+    { concurrency: "unbounded" },
+  );
+  return { resources: perStage.flat() } satisfies StateExport;
+});

package/src/State/HttpStateStore.ts

@@ -4,6 +4,7 @@ import * as Schedule from "effect/Schedule";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import { profileCommandHint } from "../Util/interactive.ts";
 import { StateApi } from "./HttpStateApi.ts";
 
 import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
@@ -242,7 +243,10 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
  * `_tag`/name, and append the HTTP status and any distinct `cause`
  * message when available.
  */
-export const describeStateStoreFailure = (e: unknown): string => {
+export const describeStateStoreFailure = (
+  e: unknown,
+  profileCommand = "alchemy profile edit",
+): string => {
   if (!(e instanceof Error)) return String(e);
   const tag = (e as { _tag?: unknown })._tag;
   let message =
@@ -253,7 +257,7 @@ export const describeStateStoreFailure = (e: unknown): string => {
   if (typeof tag === "string" && tag.startsWith("Unauthorized")) {
     message =
       "State store rejected the request as unauthorized. " +
-      "The stored state-store credentials may be stale — run 'alchemy login' to refresh them.";
+      `The stored state-store credentials may be stale. Run \`${profileCommand}\` to reconfigure them.`;
   }
   const status = (e as { response?: { status?: unknown } }).response?.status;
   if (typeof status === "number" && !message.includes(String(status))) {
@@ -274,11 +278,14 @@ const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
     retryTransient,
     Effect.tapError(Effect.log),
     Effect.catch((e: E) =>
-      Effect.fail(
-        new StateStoreError({
-          message: describeStateStoreFailure(e),
-          cause: e instanceof Error ? e : undefined,
-        }),
-      ),
+      Effect.gen(function* () {
+        const command = yield* profileCommandHint("alchemy profile edit");
+        return yield* Effect.fail(
+          new StateStoreError({
+            message: describeStateStoreFailure(e, command),
+            cause: e instanceof Error ? e : undefined,
+          }),
+        );
+      }),
     ),
   ) as Effect.Effect<A, StateStoreError, R>;

package/src/State/LocalState.ts

@@ -6,6 +6,7 @@ import type { PlatformError } from "effect/PlatformError";
 import { existsSync } from "node:fs";
 import { decodeFqn, encodeFqn } from "../FQN.ts";
 import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
+import { writeFileAtomic } from "../Util/AtomicFile.ts";
 import { STATE_STORE_VERSION } from "./HttpStateApi.ts";
 import { State, StateStoreError, type StateService } from "./State.ts";
 import { encodeState, reviveState } from "./StateEncoding.ts";
@@ -118,23 +119,12 @@ export const makeLocalState = () =>
     const outputFile = ({ stack, stage }: { stack: string; stage: string }) =>
       path.join(stateDir, stack, stage, `__stack_output__.json`);
 
-    // Write state files atomically: write to a unique sibling temp file, then
-    // rename it over the target. Rename within a directory is atomic on POSIX
-    // filesystems, so a concurrent `get` (e.g. a parallel test reading shared
-    // `.alchemy/state`) never observes a truncated, mid-write file — which
-    // would otherwise surface as `JSON.parse("")` → "Unexpected end of JSON
-    // input". The temp suffix is unique per process+call so concurrent writers
-    // of the same file don't clobber each other's temp.
+    // Write state files atomically so a concurrent `get` (e.g. a parallel
+    // test reading shared `.alchemy/state`) never observes a truncated,
+    // mid-write file — which would otherwise surface as `JSON.parse("")` →
+    // "Unexpected end of JSON input".
     const writeAtomic = (file: string, contents: string) =>
-      Effect.suspend(() => {
-        const tmp = `${file}.${process.pid}.${Math.random()
-          .toString(36)
-          .slice(2)}.tmp`;
-        return fs.writeFileString(tmp, contents).pipe(
-          Effect.flatMap(() => fs.rename(tmp, file)),
-          Effect.tapError(() => fs.remove(tmp).pipe(Effect.ignore)),
-        );
-      });
+      writeFileAtomic(fs, file, contents);
 
     // Parse a state file, tolerating an empty read. A zero-length file can
     // linger from a write that was interrupted before this atomic-write change