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

package/src/Cli/commands/state.ts

@@ -1,444 +1,307 @@
-import * as ConfigProvider from "effect/ConfigProvider";
 import * as Console from "effect/Console";
 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 * as Argument from "effect/unstable/cli/Argument";
 import { Command, Flag } from "effect/unstable/cli";
-
-import { AuthProviders } from "../../Auth/AuthProvider.ts";
-import { withProfileOverride } from "../../Auth/Profile.ts";
-import { Stage } from "../../Stage.ts";
+import * as AlchemistState from "../../Alchemist/routes/state.ts";
+import type { StateSource } from "../../Alchemist/routes/state.ts";
 import * as State from "../../State/index.ts";
-import { encodeState } from "../../State/StateEncoding.ts";
-import * as Clank from "../../Util/Clank.ts";
-import { loadConfigProvider } from "../../Util/ConfigProvider.ts";
-import { fileLogger } from "../../Util/FileLogger.ts";
-
+import * as CliKit from "../../Cli/CliKit/index.ts";
 import {
-  envFile,
-  importStack,
-  instrumentCommand,
-  profile,
-  script,
-  yes,
-} from "./_shared.ts";
+  stateExplorerScreen,
+  type StateExplorerSource,
+} from "../components/view/StateExplorer.tsx";
+import { failWithHelp, UserInputError } from "./errors.ts";
+import { envFile, profile, yes } from "./flags.ts";
+import { confirmOrDecline } from "./confirm.ts";
+import { instrumentCommand } from "./instrument.ts";
 
-/**
- * When set, the State service is replaced with the on-disk
- * `LocalState` (`.alchemy/state` under the cwd) instead of whatever
- * the stack file configures (e.g. the Cloudflare HTTP state store).
- * Useful for inspecting orphaned local state after a partially-failed
- * bootstrap.
- */
-const localFlag = Flag.boolean("local").pipe(
-  Flag.withDescription(
-    "Read from local .alchemy/state instead of the stack's configured state store",
-  ),
+const backend = Flag.choice("backend", [
+  "configured",
+  "local",
+  "cloudflare",
+  "aws",
+] as const).pipe(
+  Flag.withDescription("State backend (default: configured)"),
+  Flag.withDefault("configured" as const),
+);
+const config = Flag.file("config").pipe(
+  Flag.withDescription("Alchemy entrypoint file (default: alchemy.run.ts)"),
+  Flag.withAlias("c"),
+  Flag.withDefault("alchemy.run.ts"),
+);
+const pathArgument = Argument.string("path").pipe(
+  Argument.withDescription("State path (stack/stage/namespace/resource)"),
+  Argument.optional,
+);
+const requiredPathArgument = Argument.string("path").pipe(
+  Argument.withDescription("State path (stack/stage/namespace/resource)"),
+);
+const recursive = Flag.boolean("recursive").pipe(
+  Flag.withAlias("r"),
+  Flag.withDescription("Operate recursively on directories"),
   Flag.withDefault(false),
 );
 
-const stackFlag = Flag.string("stack").pipe(
-  Flag.withDescription("Stack name (e.g. AlchemyEffectWebsite)"),
-);
+type StateArgs = {
+  readonly main: string;
+  readonly envFile: Option.Option<string>;
+  readonly profile: string | undefined;
+  readonly backend: "configured" | "local" | "cloudflare" | "aws";
+};
 
-const stageFlag = Flag.string("stage").pipe(
-  Flag.withDescription("Stage name (e.g. dev, prod)"),
-);
+const source = (args: StateArgs): StateSource =>
+  args.backend === "local"
+    ? { backend: "local" }
+    : args.backend === "cloudflare" || args.backend === "aws"
+      ? {
+          backend: args.backend,
+          profile: args.profile,
+          envFile: Option.getOrUndefined(args.envFile),
+        }
+      : {
+          backend: "configured",
+          entrypoint: args.main,
+          profile: args.profile,
+          envFile: Option.getOrUndefined(args.envFile),
+        };
 
-const fqnFlag = Flag.string("fqn").pipe(
-  Flag.withDescription("Fully-qualified resource name"),
-);
+const normalizedPath = (path: string | undefined) => {
+  const parts = (path ?? "")
+    .split("/")
+    .filter((part) => part !== "" && part !== ".");
+  return parts.includes("..")
+    ? Effect.fail(
+        new UserInputError({ message: `invalid state path: ${path ?? "/"}` }),
+      )
+    : Effect.succeed(parts.join("/"));
+};
 
-/**
- * Build the layer stack used by every `alchemy state ...` subcommand.
- *
- * The stack file is imported and evaluated so that its `state` layer
- * (Cloudflare HTTP store, in-memory, etc.) is in scope. Pass `local`
- * to swap the configured State for an on-disk LocalState instead.
- *
- * The Stage service is only needed to build the stack's state layer;
- * state operations address (stack, stage) explicitly, so a placeholder
- * value (same as `alchemy unsafe nuke`) is sufficient.
- */
-const withStateService = <A, E>(
-  args: {
-    main: string;
-    envFile: Option.Option<string>;
-    profile: string;
-    local: boolean;
-  },
-  body: (state: State.StateService) => Effect.Effect<A, E, never>,
-) =>
-  Effect.gen(function* () {
-    const stackEffect = yield* importStack(args.main);
+const provideStore =
+  (store: State.StateService) =>
+  <A, E>(operation: Effect.Effect<A, E, State.State>) =>
+    operation.pipe(Effect.provideService(State.State, Effect.succeed(store)));
 
-    const services = Layer.mergeAll(
-      Layer.succeed(AuthProviders, {}),
-      ConfigProvider.layer(
-        withProfileOverride(
-          yield* loadConfigProvider(args.envFile),
-          args.profile,
+/** Run a state tree operation against a resolved store, mapping a bad path
+ * to a single-line user error instead of a cause dump. */
+const usingStore =
+  (store: State.StateService) =>
+  <A>(
+    operation: Effect.Effect<
+      A,
+      State.InvalidStatePath | State.StateStoreError,
+      State.State
+    >,
+  ) =>
+    provideStore(store)(operation).pipe(
+      Effect.catchTag("InvalidStatePath", (error) =>
+        Effect.fail(
+          new UserInputError({ message: `${error.path}: ${error.reason}` }),
         ),
       ),
-      Logger.layer([fileLogger("out")], { mergeWithExisting: true }),
-      Layer.succeed(Stage, "placeholder"),
-      // When --local is set we still build the stack to get its other
-      // services, but force State to be LocalState. Without --local the
-      // stack's configured State (httpState, etc.) wins.
-      args.local ? State.localState() : Layer.empty,
     );
 
-    return yield* Effect.gen(function* () {
-      const stack = yield* stackEffect;
-      return yield* Effect.gen(function* () {
-        const state = yield* yield* State.State;
-        return yield* body(state);
-      }).pipe(Effect.provide(stack.services));
-    }).pipe(Effect.provide(services));
-  });
-
-const stacksCommand = Command.make(
-  "stacks",
-  { main: script, envFile, profile, local: localFlag },
-  instrumentCommand("state.stacks")(
-    Effect.fn(function* (args) {
-      yield* withStateService(args, (state) =>
-        Effect.gen(function* () {
-          const stacks = yield* state.listStacks();
-          if (stacks.length === 0) {
-            yield* Console.log("(no stacks)");
-            return;
-          }
-          for (const s of [...stacks].sort()) {
-            yield* Console.log(s);
-          }
+const listCommand = Command.make(
+  "list",
+  { path: pathArgument, recursive, main: config, envFile, profile, backend },
+  instrumentCommand("state.list")(
+    Effect.fn(function* ({ path, recursive, ...args }) {
+      const store = yield* AlchemistState.store(source(args));
+      const items = yield* usingStore(store)(
+        State.listState({
+          path: yield* normalizedPath(Option.getOrUndefined(path)),
+          recursive,
         }),
       );
+      yield* Console.log([...items].sort().join("\n"));
     }),
   ),
+).pipe(
+  Command.withAlias("ls"),
+  Command.withDescription("List a state-store directory"),
 );
 
-const stagesCommand = Command.make(
-  "stages",
-  { stack: stackFlag, main: script, envFile, profile, local: localFlag },
-  instrumentCommand("state.stages")(
-    Effect.fn(function* ({ stack: stackName, ...rest }) {
-      yield* withStateService(rest, (state) =>
-        Effect.gen(function* () {
-          const stages = yield* state.listStages(stackName);
-          if (stages.length === 0) {
-            yield* Console.log(`(no stages in ${stackName})`);
-            return;
-          }
-          for (const s of [...stages].sort()) {
-            yield* Console.log(s);
-          }
-        }),
+const readCommand = Command.make(
+  "read",
+  { path: pathArgument, recursive, main: config, envFile, profile, backend },
+  instrumentCommand("state.read")(
+    Effect.fn(function* ({ path, recursive, ...args }) {
+      const store = yield* AlchemistState.store(source(args));
+      const requested = yield* normalizedPath(Option.getOrUndefined(path));
+      const entries = yield* usingStore(store)(
+        State.readState({ path: requested, recursive }),
       );
-    }),
-  ),
-);
-
-const resourcesCommand = Command.make(
-  "resources",
-  {
-    stack: stackFlag,
-    stageName: stageFlag,
-    main: script,
-    envFile,
-    profile,
-    local: localFlag,
-  },
-  instrumentCommand("state.resources")(
-    Effect.fn(function* ({ stack: stackName, stageName, ...rest }) {
-      yield* withStateService(rest, (state) =>
-        Effect.gen(function* () {
-          const fqns = yield* state.list({
-            stack: stackName,
-            stage: stageName,
-          });
-          if (fqns.length === 0) {
-            yield* Console.log(`(no resources in ${stackName}/${stageName})`);
-            return;
-          }
-          for (const f of [...fqns].sort()) {
-            yield* Console.log(f);
-          }
-        }),
+      yield* Console.log(
+        JSON.stringify(
+          entries.length === 1
+            ? entries[0]!.value
+            : Object.fromEntries(
+                entries.map((entry) => [entry.path, entry.value]),
+              ),
+          null,
+          2,
+        ),
       );
     }),
   ),
+).pipe(
+  Command.withAlias("cat"),
+  Command.withDescription("Read a state-store file or directory"),
 );
 
-const getCommand = Command.make(
-  "get",
+const deleteCommand = Command.make(
+  "delete",
   {
-    stack: stackFlag,
-    stageName: stageFlag,
-    fqn: fqnFlag,
-    main: script,
+    path: requiredPathArgument,
+    recursive,
+    main: config,
     envFile,
     profile,
-    local: localFlag,
+    backend,
   },
-  instrumentCommand("state.get")(
-    Effect.fn(function* ({ stack: stackName, stageName, fqn, ...rest }) {
-      yield* withStateService(rest, (state) =>
-        Effect.gen(function* () {
-          const value = yield* state.get({
-            stack: stackName,
-            stage: stageName,
-            fqn,
-          });
-          if (value === undefined) {
-            yield* Console.log(`(not found: ${stackName}/${stageName}/${fqn})`);
-            return;
-          }
-          // encodeState produces a JSON-friendly view: redacted secrets
-          // are unwrapped into `{ __redacted__: ... }`, Resources are
-          // flattened, etc. Same shape the store persists.
-          yield* Console.log(JSON.stringify(encodeState(value), null, 2));
-        }),
-      );
-    }),
-  ),
-);
-
-const treeCommand = Command.make(
-  "tree",
-  { main: script, envFile, profile, local: localFlag },
-  instrumentCommand("state.tree")(
-    Effect.fn(function* (args) {
-      yield* withStateService(args, (state) =>
-        Effect.gen(function* () {
-          const stacks = [...(yield* state.listStacks())].sort();
-          if (stacks.length === 0) {
-            yield* Console.log("(empty state store)");
-            return;
-          }
-          // Fetch the entire tree in parallel: for each stack, list its
-          // stages; for each (stack, stage), list its resources. All
-          // network round-trips happen concurrently; output is rendered
-          // once at the end so the user doesn't see stuttered partial
-          // output.
-          const tree = yield* Effect.forEach(
-            stacks,
-            (stk) =>
-              Effect.gen(function* () {
-                const stages = [...(yield* state.listStages(stk))].sort();
-                const stageEntries = yield* Effect.forEach(
-                  stages,
-                  (stg) =>
-                    Effect.map(
-                      state.list({ stack: stk, stage: stg }),
-                      (fqns) => ({ stage: stg, fqns: [...fqns].sort() }),
-                    ),
-                  { concurrency: "unbounded" },
-                );
-                return { stack: stk, stages: stageEntries };
-              }),
-            { concurrency: "unbounded" },
-          );
-
-          const lines: string[] = [];
-          for (const { stack: stk, stages } of tree) {
-            lines.push(stk);
-            for (let i = 0; i < stages.length; i++) {
-              const { stage: stg, fqns } = stages[i]!;
-              const stageBranch = i === stages.length - 1 ? "└─" : "├─";
-              lines.push(`${stageBranch} ${stg}`);
-              const indent = i === stages.length - 1 ? "   " : "│  ";
-              for (let j = 0; j < fqns.length; j++) {
-                const leaf = j === fqns.length - 1 ? "└─" : "├─";
-                lines.push(`${indent}${leaf} ${fqns[j]}`);
-              }
-            }
-          }
-          yield* Console.log(lines.join("\n"));
-        }),
+  instrumentCommand("state.delete")(
+    Effect.fn(function* ({ path, recursive, ...args }) {
+      const requested = yield* normalizedPath(path);
+      if (requested === "") {
+        return yield* Effect.fail(
+          new UserInputError({ message: "cannot delete the state root" }),
+        );
+      }
+      const store = yield* AlchemistState.store(source(args));
+      yield* usingStore(store)(
+        State.deleteState({ path: requested, recursive }),
       );
+      yield* CliKit.accessors.output.success(`Deleted state at ${requested}`);
     }),
   ),
-);
-
-const optionalStackFlag = Flag.string("stack").pipe(
-  Flag.withDescription(
-    "Stack name to export. Omit to export ALL stacks in the store.",
+).pipe(
+  Command.withAlias("rm"),
+  Command.withDescription(
+    "Delete state records without deleting cloud resources",
   ),
-  Flag.optional,
-  Flag.map(Option.getOrUndefined),
 );
 
-const optionalStageFlag = Flag.string("stage").pipe(
-  Flag.withDescription(
-    "Stage to export within the stack. Omit to export all stages.",
-  ),
-  Flag.optional,
-  Flag.map(Option.getOrUndefined),
-);
+const stateExplorer = (args: StateArgs) =>
+  Effect.gen(function* () {
+    const cli = yield* CliKit.CliKit;
+    const store = yield* AlchemistState.store(source(args));
+    const on = provideStore(store);
+    const explorer: StateExplorerSource = {
+      backend: store.id,
+      listStacks: on(State.listState({})).pipe(
+        Effect.map((paths) => paths.map((path) => path.slice(0, -1))),
+      ),
+      listStages: (stack) =>
+        on(State.listState({ path: stack })).pipe(
+          Effect.map((paths) =>
+            paths.map((path) => path.slice(stack.length + 1, -1)),
+          ),
+        ),
+      listResources: (stack, stage) =>
+        on(
+          State.listState({ path: `${stack}/${stage}`, recursive: true }),
+        ).pipe(
+          Effect.map((paths) =>
+            paths
+              .filter((path) => path !== `${stack}/${stage}/output`)
+              .map((path) => path.slice(`${stack}/${stage}/`.length)),
+          ),
+        ),
+      readFile: (file) =>
+        on(
+          State.readState({
+            path: `${file.stack}/${file.stage}/${file.kind === "output" ? "output" : file.fqn}`,
+          }),
+        ).pipe(Effect.map((entries) => entries[0]?.value)),
+      deleteNodes: (nodes) =>
+        Effect.forEach(
+          nodes.filter(
+            (node, index) =>
+              !nodes.some(
+                (parent, parentIndex) =>
+                  parentIndex !== index &&
+                  ["stack", "stage", "namespace"].includes(parent.kind) &&
+                  node.path.startsWith(`${parent.path}/`),
+              ),
+          ),
+          (node) =>
+            node.kind === "output"
+              ? Effect.void
+              : on(
+                  State.deleteState({ path: node.path, recursive: true }),
+                ).pipe(Effect.asVoid),
+          { concurrency: 32, discard: true },
+        ),
+    };
+    // 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)
+      .pipe(Effect.catchTag("TerminalCancelled", () => Effect.void));
+  });
 
-/**
- * Bulk state read: every matching resource record as one JSON
- * document, so a whole estate is read in a single CLI invocation
- * instead of `state resources` + one `state get` per FQN per
- * stack/stage. Filter locally, e.g.:
- *
- * ```sh
- * alchemy state export | jq '.resources[] | select(.state.resourceType == "AWS.EC2.Instance")'
- * ```
- */
-const exportCommand = Command.make(
-  "export",
-  {
-    stack: optionalStackFlag,
-    stageName: optionalStageFlag,
-    main: script,
-    envFile,
-    profile,
-    local: localFlag,
-  },
-  instrumentCommand("state.export")(
-    Effect.fn(function* ({ stack: stackName, stageName, ...rest }) {
-      if (stageName !== undefined && stackName === undefined) {
-        yield* Console.log(
-          "Error: cannot specify --stage without --stack. Pass the stack name via --stack.",
-        );
-        return yield* Effect.fail(new Error("missing stack"));
+const nukeCommand = Command.make(
+  "nuke",
+  { main: config, envFile, profile, backend, yes },
+  instrumentCommand("state.unsafe.nuke")(
+    Effect.fn(function* ({ yes, ...args }) {
+      const store = yield* AlchemistState.store(source(args));
+      const stacks = [...(yield* store.listStacks())].sort();
+      if (stacks.length === 0) {
+        yield* CliKit.accessors.output.info("Nothing to clear.");
+        return;
       }
-
-      yield* withStateService(rest, (state) =>
-        Effect.gen(function* () {
-          const exported = yield* State.exportState(state, {
-            stack: stackName,
-            stage: stageName,
-          });
-          // Same JSON-friendly view `state get` prints: redacted
-          // secrets become `{ __redacted__: ... }`, Resources are
-          // flattened, etc.
-          yield* Console.log(
-            JSON.stringify(
-              {
-                resources: exported.resources.map((r) => ({
-                  ...r,
-                  state: encodeState(r.state),
-                })),
-              },
-              null,
-              2,
+      yield* Console.log(stacks.map((stack) => `• ${stack}`).join("\n"));
+      yield* confirmOrDecline({
+        yes,
+        message: `Permanently delete ALL ${stacks.length} stacks from the state store? This cannot be undone. Cloud resources will remain.`,
+      });
+      yield* Effect.forEach(
+        stacks,
+        (stack) =>
+          store
+            .deleteStack({ stack })
+            .pipe(
+              Effect.andThen(
+                CliKit.accessors.output.success(`Cleared ${stack}`),
+              ),
             ),
-          );
-        }),
+        { concurrency: 32, discard: true },
       );
     }),
   ),
-);
-
-const clearStackFlag = Flag.string("stack").pipe(
-  Flag.withDescription(
-    "Stack name to clear. Omit to clear ALL stacks in the store.",
+).pipe(
+  Command.withDescription(
+    "Delete all stacks, stages, and outputs from the state store",
   ),
-  Flag.optional,
-  Flag.map(Option.getOrUndefined),
+  Command.unlisted,
 );
 
-const clearStageFlag = Flag.string("stage").pipe(
-  Flag.withDescription(
-    "Stage to clear within the stack. Omit to clear all stages in the stack.",
-  ),
-  Flag.optional,
-  Flag.map(Option.getOrUndefined),
+const unsafeCommand = Command.make("unsafe", {}).pipe(
+  Command.withDescription("Destructive state operations"),
+  Command.withSubcommands([nukeCommand]),
+  Command.unlisted,
 );
 
-/**
- * Destructive: removes resource state from the store. The actual cloud
- * resources are NOT touched — this only affects what alchemy thinks
- * exists. Always confirms before deleting unless `--yes` is passed.
- */
-const clearCommand = Command.make(
-  "clear",
-  {
-    stack: clearStackFlag,
-    stageName: clearStageFlag,
-    main: script,
-    envFile,
-    profile,
-    local: localFlag,
-    yes,
-  },
-  instrumentCommand("state.clear")(
-    Effect.fn(function* ({
-      stack: stackName,
-      stageName,
-      yes: yesFlag,
-      ...rest
-    }) {
-      if (stageName !== undefined && stackName === undefined) {
-        yield* Console.log(
-          "Error: cannot specify --stage without --stack. Pass the stack name via --stack.",
-        );
-        return yield* Effect.fail(new Error("missing stack"));
+export const stateCommand = Command.make(
+  "state",
+  { main: config, envFile, profile, backend },
+  instrumentCommand("state")(
+    Effect.fn(function* (args) {
+      if (!(yield* CliKit.CliKit).terminal.input) {
+        return yield* failWithHelp(["alchemy", "state"]);
       }
-
-      yield* withStateService(rest, (state) =>
-        Effect.gen(function* () {
-          const targets: ReadonlyArray<{ stack: string; stage?: string }> =
-            stackName === undefined
-              ? [...(yield* state.listStacks())]
-                  .sort()
-                  .map((s) => ({ stack: s }))
-              : stageName === undefined
-                ? [{ stack: stackName }]
-                : [{ stack: stackName, stage: stageName }];
-
-          if (targets.length === 0) {
-            yield* Console.log("(nothing to clear)");
-            return;
-          }
-
-          const scope =
-            stackName === undefined
-              ? `ALL stacks (${targets.length}): ${targets.map((t) => t.stack).join(", ")}`
-              : stageName === undefined
-                ? `stack '${stackName}' (all stages)`
-                : `stage '${stageName}' in stack '${stackName}'`;
-
-          if (!yesFlag) {
-            const ok = yield* Clank.confirm({
-              message: `About to delete ${scope} from the state store. This cannot be undone. Continue?`,
-              initialValue: false,
-            });
-            if (!ok) {
-              yield* Console.log("Cancelled.");
-              return;
-            }
-          }
-
-          yield* Effect.forEach(
-            targets,
-            (target) =>
-              Effect.gen(function* () {
-                yield* state.deleteStack(target);
-                yield* Console.log(
-                  `cleared ${target.stack}${target.stage ? `/${target.stage}` : ""}`,
-                );
-              }),
-            { concurrency: 32 },
-          );
-        }),
-      );
+      yield* stateExplorer(args);
     }),
   ),
-);
-
-export const stateCommand = Command.make("state", {}).pipe(
+).pipe(
+  Command.withDescription("Inspect and manage deployment state"),
   Command.withSubcommands([
-    stacksCommand,
-    stagesCommand,
-    resourcesCommand,
-    getCommand,
-    exportCommand,
-    treeCommand,
-    clearCommand,
+    listCommand,
+    readCommand,
+    deleteCommand,
+    unsafeCommand,
   ]),
 );