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

package/src/Cli/commands/render.ts

@@ -1,18 +1,16 @@
-import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
-import * as Exit from "effect/Exit";
-import * as Option from "effect/Option";
-import * as Scope from "effect/Scope";
-import { Progress } from "../../Alchemist/Progress.ts";
-import type { Plan } from "../../Plan.ts";
+import * as Match from "effect/Match";
+import * as Alchemist from "../../Alchemist/index.ts";
+import type { Event, PlanningPhase } from "../../Events.ts";
+import { Interaction } from "../../Interaction.ts";
 import * as Report from "../../Report.ts";
-import { CliKit } from "../CliKit/CliKit.ts";
+import { isPromptCancellation } from "./errors.ts";
 
 export const renderPlanning =
   (options: { operation: string; stage: string; computingLabel?: string; readyLabel?: string }) =>
   <A, E, R>(effect: Effect.Effect<A, E, R>) =>
     Effect.gen(function* () {
-      const phaseLabel: Record<Report.PlanningPhase, string> = {
+      const phaseLabel: Record<PlanningPhase, string> = {
         "importing-module": "Importing stack module",
         "resolving-services": "Resolving stack services",
         "loading-state": "Loading stack state",
@@ -25,7 +23,7 @@ export const renderPlanning =
         options.stage,
         `${options.operation} · ${options.stage}`,
       );
-      const interactive = (yield* CliKit).terminal.input;
+      const interactive = (yield* Interaction).terminal.input;
       const inFlight = new Set<string>();
       let done = 0;
       let total = 0;
@@ -38,70 +36,44 @@ export const renderPlanning =
             `${done}/${total} · ${current}${rest}`,
           );
         });
+      const completed = (event: { fqn: string; completed: number; total: number }) => {
+        if (!interactive) return Effect.void;
+        inFlight.delete(event.fqn);
+        done = event.completed;
+        total = event.total;
+        return showCounter(event.fqn);
+      };
       return yield* effect.pipe(
-        Effect.provideService(Progress, (event) => {
-          switch (event._tag) {
-            case "plan.phase":
-              return event.phase === "plan-ready"
-                ? planning.succeed(phaseLabel["plan-ready"])
-                : planning.update(phaseLabel[event.phase], options.stage, {
-                    spinning: event.phase !== "importing-module",
-                  });
-            case "state.bootstrap.started":
-              return planning.update(`Bootstrapping state store '${event.store}'`, options.stage);
-            case "state.bootstrap.completed":
-              return planning.update(phaseLabel["loading-state"], options.stage);
-            case "plan.resource.started":
-              if (!interactive) return Effect.void;
-              inFlight.add(event.fqn);
-              total = Math.max(total, event.total);
-              return showCounter(event.fqn);
-            case "plan.resource.completed":
-            case "plan.action.completed":
-              if (!interactive) return Effect.void;
-              inFlight.delete(event.fqn);
-              done = event.completed;
-              total = event.total;
-              return showCounter(event.fqn);
-            default:
-              return Effect.void;
-          }
-        }),
-        Effect.tapError(() => planning.fail("Planning failed")),
-        Effect.ensuring(planning.close),
-      );
-    });
-
-export const renderApply =
-  (plan: Plan, options?: Report.PlanDisplayOptions) =>
-  <A, E, R>(effect: Effect.Effect<A, E, R>) =>
-    Effect.gen(function* () {
-      const cli = yield* Report.Cli;
-      const session = yield* cli.startApplySession(plan, options);
-      // Dev keeps the widget mounted after apply settles and parks in the
-      // ambient scope; bind the widget's teardown to that scope so a reload
-      // or Ctrl+C removes it instead of stacking it under the next one.
-      if (options?.dev && session.close !== undefined) {
-        const scope = yield* Effect.serviceOption(Scope.Scope);
-        if (Option.isSome(scope)) {
-          yield* Scope.addFinalizer(scope.value, session.close);
-        }
-      }
-      return yield* effect.pipe(
-        Effect.provideService(Progress, (event) =>
-          event._tag === "apply.resource.status" || event._tag === "apply.resource.note"
-            ? session.emit(event)
-            : Effect.void,
+        Alchemist.onEvent(
+          Match.type<Event>().pipe(
+            Match.discriminators("type")({
+              "plan.phase": (event) =>
+                event.phase === "plan-ready"
+                  ? planning.succeed(phaseLabel["plan-ready"])
+                  : planning.update(phaseLabel[event.phase], options.stage, {
+                      spinning: event.phase !== "importing-module",
+                    }),
+              "state.bootstrap.started": (event) =>
+                planning.update(`Bootstrapping state store '${event.store}'`, options.stage),
+              "state.bootstrap.completed": () =>
+                planning.update(phaseLabel["loading-state"], options.stage),
+              "plan.resource.started": (event) => {
+                if (!interactive) return Effect.void;
+                inFlight.add(event.fqn);
+                total = Math.max(total, event.total);
+                return showCounter(event.fqn);
+              },
+              "plan.resource.completed": completed,
+              "plan.action.completed": completed,
+            }),
+            Match.orElse(() => Effect.void),
+          ),
         ),
-        Effect.tap((value) =>
-          options?.dev && session.setOutput !== undefined ? session.setOutput(value) : Effect.void,
-        ),
-        Effect.onExit((exit) =>
-          Exit.isSuccess(exit)
-            ? session.done("success")
-            : Cause.hasInterruptsOnly(exit.cause)
-              ? Effect.void
-              : session.done("failure"),
+        // A prompt dismissed mid-plan (e.g. a provider asking the user to
+        // resolve an ambiguity) is a cancellation, not a planning failure.
+        Effect.tapError((error) =>
+          planning.fail(isPromptCancellation(error) ? "Planning was canceled" : "Planning failed"),
         ),
+        Effect.ensuring(planning.close),
       );
     });

package/src/Cli/commands/state.ts

@@ -4,10 +4,9 @@ import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
-import * as AlchemistState from "../../Alchemist/routes/state.ts";
-import type { ProviderSource, StateSource } from "../../Alchemist/routes/state.ts";
-import * as CliKit from "../../Cli/CliKit/index.ts";
+import * as Alchemist from "../../Alchemist/index.ts";
 import type { StateStoreLogEntry } from "../../Contributions.ts";
+import * as Interaction from "../../Interaction.ts";
 import * as State from "../../State/index.ts";
 import {
   stateExplorerScreen,
@@ -59,18 +58,18 @@ type StateArgs = {
   readonly name: string | undefined;
 };
 
-const source = (args: StateArgs): StateSource =>
+const source = (args: StateArgs): Alchemist.State.StateSource =>
   args.backend === "local"
-    ? { _tag: "Local" }
+    ? { type: "local" }
     : args.backend === "configured"
       ? {
-          _tag: "Configured",
+          type: "configured",
           entrypoint: args.main,
           profile: args.profile,
           envFile: Option.getOrUndefined(args.envFile),
         }
       : {
-          _tag: "Provider",
+          type: "provider",
           backend: args.backend,
           name: args.name,
           profile: args.profile,
@@ -84,8 +83,8 @@ const lifecycleBackend = Flag.String("backend").pipe(
 
 const lifecycleSource = (
   args: Pick<StateArgs, "envFile" | "profile" | "backend" | "name">,
-): ProviderSource => ({
-  _tag: "Provider",
+): Alchemist.State.ProviderSource => ({
+  type: "provider",
   backend: args.backend,
   name: args.name,
   profile: args.profile,
@@ -120,7 +119,7 @@ const listCommand = Command.make(
   { path: pathArgument, recursive, main: config, envFile, profile, backend, name: storeName },
   instrumentCommand("state.list")(
     Effect.fn(function* ({ path, recursive, ...args }) {
-      const store = yield* AlchemistState.store(source(args));
+      const store = yield* Alchemist.State.store(source(args));
       const items = yield* usingStore(store)(
         State.listState({
           path: yield* path.pipe(Option.getOrUndefined, normalizedPath),
@@ -137,7 +136,7 @@ const readCommand = Command.make(
   { path: pathArgument, recursive, main: config, envFile, profile, backend, name: storeName },
   instrumentCommand("state.read")(
     Effect.fn(function* ({ path, recursive, ...args }) {
-      const store = yield* AlchemistState.store(source(args));
+      const store = yield* Alchemist.State.store(source(args));
       const requested = yield* path.pipe(Option.getOrUndefined, normalizedPath);
       const entries = yield* usingStore(store)(State.readState({ path: requested, recursive }));
       yield* Console.log(
@@ -170,9 +169,9 @@ const deleteCommand = Command.make(
       if (requested === "") {
         return yield* new UserInputError({ message: "cannot delete the state root" });
       }
-      const store = yield* AlchemistState.store(source(args));
+      const store = yield* Alchemist.State.store(source(args));
       yield* usingStore(store)(State.deleteState({ path: requested, recursive }));
-      yield* CliKit.accessors.output.success(`Deleted state at ${requested}`);
+      yield* Interaction.success(`Deleted state at ${requested}`);
     }),
   ),
 ).pipe(
@@ -182,8 +181,8 @@ const deleteCommand = Command.make(
 
 const stateExplorer = (args: StateArgs) =>
   Effect.gen(function* () {
-    const cli = yield* CliKit.CliKit;
-    const store = yield* AlchemistState.store(source(args));
+    const cli = yield* Interaction.Interaction;
+    const store = yield* Alchemist.State.store(source(args));
     const on = provideStore(store);
     const explorer: StateExplorerSource = {
       backend: store.id,
@@ -229,10 +228,9 @@ const stateExplorer = (args: StateArgs) =>
     // Captured here so the explorer's forked fibers run with the command's
     // ambient services (tracing, terminal) rather than the default runtime.
     const services = yield* Effect.context<never>();
-    yield* cli.application(cli.prompt.custom(stateExplorerScreen(explorer, services))).pipe(
-      CliKit.Application.alternate,
-      Effect.catchTag("TerminalCancelled", () => Effect.void),
-    );
+    yield* cli
+      .session(cli.prompt.screen(stateExplorerScreen(explorer, services)), { alternate: true })
+      .pipe(Effect.catchTag("TerminalCancelled", () => Effect.void));
   });
 
 const nukeCommand = Command.make(
@@ -240,10 +238,10 @@ const nukeCommand = Command.make(
   { main: config, envFile, profile, backend, name: storeName, yes },
   instrumentCommand("state.unsafe.nuke")(
     Effect.fn(function* ({ yes, ...args }) {
-      const store = yield* AlchemistState.store(source(args));
+      const store = yield* Alchemist.State.store(source(args));
       const stacks = [...(yield* store.listStacks())].sort();
       if (stacks.length === 0) {
-        yield* CliKit.accessors.output.info("Nothing to clear.");
+        yield* Interaction.info("Nothing to clear.");
         return;
       }
       yield* Console.log(stacks.map((stack) => `• ${stack}`).join("\n"));
@@ -256,7 +254,7 @@ const nukeCommand = Command.make(
         (stack) =>
           store
             .deleteStack({ stack })
-            .pipe(Effect.andThen(CliKit.accessors.output.success(`Cleared ${stack}`))),
+            .pipe(Effect.andThen(Interaction.success(`Cleared ${stack}`))),
         { concurrency: 32, discard: true },
       );
     }),
@@ -269,19 +267,44 @@ const nukeCommand = Command.make(
 const bootstrapCommand = Command.make(
   "bootstrap",
   {
+    main: config,
     envFile,
     profile,
-    backend: lifecycleBackend,
+    backend: Flag.String("backend").pipe(
+      Flag.withDescription(
+        "Provider state store to act on (e.g. aws, cloudflare); defaults to the one the config sets",
+      ),
+      Flag.optional,
+      Flag.map(Option.getOrUndefined),
+    ),
     name: storeName,
     force: Flag.Boolean("force").pipe(
-      Flag.withDescription("Redeploy an existing state store instead of adopting it"),
+      Flag.withDescription(
+        "Redeploy an existing state store instead of adopting it (with --backend)",
+      ),
       Flag.withDefault(false),
     ),
   },
   instrumentCommand("state.bootstrap")(
-    Effect.fn(function* ({ force, ...args }) {
-      const result = yield* AlchemistState.bootstrap({ ...lifecycleSource(args), force });
-      yield* CliKit.accessors.output.success(
+    Effect.fn(function* ({ force, main, backend, ...args }) {
+      if (backend === undefined) {
+        if (force || args.name !== undefined) {
+          return yield* new UserInputError({ message: "--force and --name need --backend." });
+        }
+        const { version } = yield* Alchemist.State.bootstrapConfigured({
+          type: "configured",
+          entrypoint: main,
+          profile: args.profile,
+          envFile: Option.getOrUndefined(args.envFile),
+        });
+        yield* Interaction.success(`State store configured in '${main}' is ready (v${version})`);
+        return;
+      }
+      const result = yield* Alchemist.State.bootstrap({
+        ...lifecycleSource({ ...args, backend }),
+        force,
+      });
+      yield* Interaction.success(
         `State store '${result.store}' ${result.status} (${Object.values(result.location).join(", ")})`,
       );
     }),
@@ -299,14 +322,70 @@ const teardownCommand = Command.make(
         confirmLabel: "Destroy",
         cancelLabel: "Cancel",
       });
-      const result = yield* AlchemistState.teardown(lifecycleSource(args));
-      yield* CliKit.accessors.output.success(
+      const result = yield* Alchemist.State.teardown(lifecycleSource(args));
+      yield* Interaction.success(
         result.deleted.length === 0 ? "Nothing to delete" : `Deleted ${result.deleted.join(", ")}`,
       );
     }),
   ),
 ).pipe(Command.withDescription("Delete a state store and its backing resources"), Command.unlisted);
 
+const migrateCommand = Command.make(
+  "migrate",
+  {
+    main: config,
+    envFile,
+    profile,
+    backend,
+    name: storeName,
+    stack: Flag.String("stack").pipe(
+      Flag.withDescription("Only migrate this stack's stages"),
+      Flag.optional,
+      Flag.map(Option.getOrUndefined),
+    ),
+    stage: Flag.String("stage").pipe(
+      Flag.withDescription("Only migrate stages of this name"),
+      Flag.optional,
+      Flag.map(Option.getOrUndefined),
+    ),
+    rollback: Flag.Boolean("rollback").pipe(
+      Flag.withDescription("Move stages back to the state store this one replaces"),
+      Flag.withDefault(false),
+    ),
+  },
+  instrumentCommand("state.migrate")(
+    Effect.fn(function* ({ stack, stage, rollback, ...args }) {
+      const result = yield* Alchemist.State.migrate(source(args), { stack, stage, rollback });
+      if (result.stages.length === 0) {
+        yield* Interaction.info("No stages to migrate.");
+        return;
+      }
+      for (const entry of result.stages) {
+        const detail =
+          entry.reason ?? (entry.records === undefined ? "" : `${entry.records} records`);
+        yield* Console.log(
+          `${entry.stack}/${entry.stage}: ${entry.status}${detail === "" ? "" : ` (${detail})`}`,
+        );
+      }
+      const unfinished = result.stages.filter(
+        (entry) => entry.status === "blocked" || entry.status === "failed",
+      );
+      if (unfinished.length > 0) {
+        return yield* new UserInputError({
+          message: `${unfinished.length} stage(s) did not move. Run the command again once the deploys holding them finish, or fix the failures above.`,
+        });
+      }
+      yield* Interaction.success(
+        rollback ? "Rolled back the state store" : "Migrated the state store",
+      );
+    }),
+  ),
+).pipe(
+  Command.withDescription(
+    "Move stages into the configured state store from the one it replaces (or --backend)",
+  ),
+);
+
 const logsCommand = Command.make(
   "logs",
   {
@@ -335,13 +414,13 @@ const logsCommand = Command.make(
       const format = (entry: StateStoreLogEntry) =>
         `${formatLocalTimestamp(entry.timestamp)} ${entry.message}`;
       if (tail) {
-        yield* CliKit.accessors.output.info(`Tailing the ${args.backend} state store...`);
-        yield* AlchemistState.tailLogs(target).pipe(
+        yield* Interaction.info(`Tailing the ${args.backend} state store...`);
+        yield* Alchemist.State.tailLogs(target).pipe(
           Stream.runForEach((entry) => Console.log(format(entry))),
         );
         return;
       }
-      const entries = yield* AlchemistState.logs({
+      const entries = yield* Alchemist.State.logs({
         ...target,
         limit,
         since: since ? yield* parseSince(since) : undefined,
@@ -366,7 +445,7 @@ export const stateCommand = Command.make(
   { main: config, envFile, profile, backend, name: storeName },
   instrumentCommand("state")(
     Effect.fn(function* (args) {
-      if (!(yield* CliKit.CliKit).terminal.input) {
+      if (!(yield* Interaction.Interaction).terminal.input) {
         return yield* failWithHelp(["alchemy", "state"]);
       }
       yield* stateExplorer(args);
@@ -380,6 +459,7 @@ export const stateCommand = Command.make(
     deleteCommand,
     bootstrapCommand,
     teardownCommand,
+    migrateCommand,
     logsCommand,
     unsafeCommand,
   ]),

package/src/Cli/components/capabilities.ts

@@ -0,0 +1,20 @@
+import { detectCapabilities } from "@alchemy.run/sigil/capabilities";
+import type { TerminalCapabilities, TerminalOptions } from "../../Interaction.ts";
+import { isNonInteractive } from "../../Util/interactive.ts";
+
+/** Detect what the terminal behind the given streams supports. */
+export const resolveCapabilities = (options: TerminalOptions = {}): TerminalCapabilities => {
+  const stdout = options.stdout ?? process.stdout;
+  const stdin = options.stdin ?? process.stdin;
+  const detected = detectCapabilities({ stdout });
+  const input =
+    options.input ?? (stdin.isTTY === true && stdout.isTTY === true && !isNonInteractive());
+  return {
+    input,
+    columns: detected.size.columns,
+    rows: detected.size.rows,
+    colors: options.colors ?? detected.supports.color,
+    unicode: options.unicode ?? detected.supports.unicode,
+    alternateScreen: detected.supports.alternateScreen,
+  };
+};

package/src/Cli/components/types.ts

@@ -1,37 +1,27 @@
-import type * as Effect from "effect/Effect";
-import type { ReactNode } from "react";
-import type { ProgressOptions, SelectOptions } from "../../Interaction.ts";
-
-// The interaction vocabulary (message/prompt option shapes, progress
-// options, interaction errors) belongs to the engine's core `Interaction`
-// contract — CliKit implements a superset of it. Re-exported here so the
-// CLI's components keep one local import for their whole type surface.
+// The interaction vocabulary belongs to the engine's `Interaction` contract.
+// Re-exported here so the CLI's components keep one local import for their
+// whole type surface.
 export type {
-  AwaitExternalOptions,
+  BrowserLoginOptions,
   Choice,
   ConfirmOptions,
   InteractionError,
+  LiveViewHandle,
+  LiveViewOptions,
   MessageOptions,
   MultiSelectOptions,
   PasswordInputOptions,
+  ProgressHandle,
   ProgressOptions,
+  ScreenController,
   SelectOptions,
+  SessionOptions,
+  TerminalCapabilities,
+  TerminalOptions,
   TextInputOptions,
+  View,
 } from "../../Interaction.ts";
-
-/** A composable CLI layout. Views are inert; only CliKit renders them. */
-export type View = ReactNode;
-
-export interface CliKitCapabilities {
-  /** Whether this process has usable terminal input for prompts and apps. */
-  readonly input: boolean;
-  readonly columns: number;
-  readonly rows: number;
-  readonly colors: boolean;
-  readonly unicode: boolean;
-  /** Whether full-screen applications may use the terminal's alternate buffer. */
-  readonly alternateScreen: boolean;
-}
+export { Screen } from "../../Interaction.ts";
 
 export interface RenderOptions {
   readonly columns?: number;
@@ -57,79 +47,3 @@ export interface CycleSelectOptions<State> {
   readonly requireChange?: boolean;
   readonly unchangedMessage?: string;
 }
-
-/** A navigable application menu. Selecting an item does not commit output. */
-export interface MenuOptions<Value> extends SelectOptions<Value> {
-  readonly header?: View;
-  readonly footer?: View;
-  /**
-   * Value returned by Escape. Without it, Escape cancels the application.
-   * `undefined` is a valid back value when it is part of `Value`; presence of
-   * the property, rather than its value, determines whether a back target
-   * exists.
-   */
-  readonly back?: Value;
-}
-
-export interface ScreenController<Value> {
-  readonly submit: (value: Value, summary?: View) => void;
-  readonly cancel: () => void;
-}
-
-/**
- * A custom interactive scene. The scene owns its local component state while
- * CliKit owns input streams, serialization, rendering and teardown.
- */
-export interface Screen<Value> {
-  readonly name: string;
-  readonly render: (controller: ScreenController<Value>) => View;
-}
-
-export const Screen = {
-  make: <Value>(
-    name: string,
-    render: (controller: ScreenController<Value>) => View,
-  ): Screen<Value> => ({ name, render }),
-};
-
-/**
- * Handle for a live progress row. Acquired within a `Scope`: the enclosing
- * scope's close is a release backstop, so an interrupted fiber can never leave
- * an orphaned row pinning the renderer. Settling early via `succeed`/`fail`/
- * `close` is the normal path; every settle operation is idempotent.
- */
-export interface ProgressHandle {
-  readonly update: (options: ProgressOptions) => Effect.Effect<void>;
-  readonly succeed: (message?: string) => Effect.Effect<void>;
-  readonly fail: (message?: string) => Effect.Effect<void>;
-  readonly close: Effect.Effect<void>;
-}
-
-/**
- * A mounted live view. The view itself is immutable — dynamic content flows
- * through a caller-owned store that its component subscribes to — so the
- * handle only controls the block's lifetime. Scope-bound the same way as
- * {@link ProgressHandle}; `close` settles early and is idempotent.
- */
-export interface LiveViewHandle {
-  readonly close: Effect.Effect<void>;
-}
-
-export interface LiveViewOptions {
-  /** Place an application shell/header before completed prompt output. */
-  readonly placement?: "beforeTranscript" | "afterTranscript";
-  /** Commit the final view to the static transcript when it closes. */
-  readonly persistOnClose?: boolean;
-}
-
-export interface CliKitOptions {
-  readonly stdin?: NodeJS.ReadStream;
-  readonly stdout?: NodeJS.WriteStream;
-  readonly stderr?: NodeJS.WriteStream;
-  /** Override automatic TTY input detection. Primarily useful for tests. */
-  readonly input?: boolean;
-  readonly colors?: boolean;
-  readonly unicode?: boolean;
-  /** Capture console output while the interactive renderer owns the tty. */
-  readonly captureConsole?: boolean;
-}

package/src/Cli/components/ui/Environment.tsx

@@ -4,9 +4,9 @@ import { useWindowSize } from "@alchemy.run/sigil";
 import { createContext, useContext, useMemo } from "@alchemy.run/sigil/react";
 import type { ReactNode } from "react";
 import { glyphsFor, theme, type KeyHint } from "../../../Util/Theme.ts";
-import type { CliKitCapabilities } from "../types.ts";
+import type { TerminalCapabilities } from "../types.ts";
 
-const defaults: CliKitCapabilities = {
+const defaults: TerminalCapabilities = {
   input: false,
   columns: 80,
   rows: 24,
@@ -15,14 +15,14 @@ const defaults: CliKitCapabilities = {
   alternateScreen: false,
 };
 
-const EnvironmentContext = createContext<CliKitCapabilities>(defaults);
+const EnvironmentContext = createContext<TerminalCapabilities>(defaults);
 
 /**
  * Resize-following variant, split out so the static renderer (`renderToString`
  * for every print/format) never attaches a `resize` listener to stdout.
  */
 type ObservingEnvironmentProps = {
-  readonly capabilities: CliKitCapabilities;
+  readonly capabilities: TerminalCapabilities;
   readonly children?: ReactNode;
 };
 
@@ -36,7 +36,7 @@ function ObservingEnvironment({ capabilities, children }: ObservingEnvironmentPr
 }
 
 type CliEnvironmentProps = {
-  readonly capabilities: CliKitCapabilities;
+  readonly capabilities: TerminalCapabilities;
   /** Follow Sigil's terminal resize subscription for a live renderer. */
   readonly observeWindow?: boolean;
   readonly children?: ReactNode;