sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Cli/ commands/ state.ts

import { Command, Flag } from "effect/cli";
import * as Argument from "effect/cli/Argument";
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 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,
  type StateExplorerSource,
} from "../components/view/StateExplorer.tsx";
import { formatLocalTimestamp } from "../Format.ts";
import { confirmOrDecline } from "./confirm.ts";
import { failWithHelp, UserInputError } from "./errors.ts";
import { envFile, parseSince, profile, yes } from "./flags.ts";
import { instrumentCommand } from "./instrument.ts";

const backend = Flag.String("backend").pipe(
  Flag.withDescription(
    "State backend: configured (default), local, or a provider's state store (e.g. aws, cloudflare)",
  ),
  Flag.withDefault("configured"),
);
/** A provider's store other than the account's default, e.g. an S3 bucket. */
const storeName = Flag.String("name").pipe(
  Flag.withDescription(
    "State store to address instead of the account's default (e.g. an S3 bucket; with --backend)",
  ),
  Flag.optional,
  Flag.map(Option.getOrUndefined),
);
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),
);

type StateArgs = {
  readonly main: string;
  readonly envFile: Option.Option<string>;
  readonly profile: string | undefined;
  readonly backend: string;
  readonly name: string | undefined;
};

const source = (args: StateArgs): Alchemist.State.StateSource =>
  args.backend === "local"
    ? { type: "local" }
    : args.backend === "configured"
      ? {
          type: "configured",
          entrypoint: args.main,
          profile: args.profile,
          envFile: Option.getOrUndefined(args.envFile),
        }
      : {
          type: "provider",
          backend: args.backend,
          name: args.name,
          profile: args.profile,
          envFile: Option.getOrUndefined(args.envFile),
        };

/** Lifecycle commands act on a provider's state store. */
const lifecycleBackend = Flag.String("backend").pipe(
  Flag.withDescription("Provider state store to act on (e.g. aws, cloudflare)"),
);

const lifecycleSource = (
  args: Pick<StateArgs, "envFile" | "profile" | "backend" | "name">,
): Alchemist.State.ProviderSource => ({
  type: "provider",
  backend: args.backend,
  name: args.name,
  profile: args.profile,
  envFile: Option.getOrUndefined(args.envFile),
});

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("/"));
};

const provideStore =
  (store: State.StateService) =>
  <A, E>(operation: Effect.Effect<A, E, State.State>) =>
    operation.pipe(Effect.provideService(State.State, Effect.succeed(store)));

/** 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}` })),
      ),
    );

const listCommand = Command.make(
  "list",
  { path: pathArgument, recursive, main: config, envFile, profile, backend, name: storeName },
  instrumentCommand("state.list")(
    Effect.fn(function* ({ path, recursive, ...args }) {
      const store = yield* Alchemist.State.store(source(args));
      const items = yield* usingStore(store)(
        State.listState({
          path: yield* path.pipe(Option.getOrUndefined, normalizedPath),
          recursive,
        }),
      );
      yield* Console.log([...items].sort().join("\n"));
    }),
  ),
).pipe(Command.withAlias("ls"), Command.withDescription("List a state-store directory"));

const readCommand = Command.make(
  "read",
  { path: pathArgument, recursive, main: config, envFile, profile, backend, name: storeName },
  instrumentCommand("state.read")(
    Effect.fn(function* ({ path, recursive, ...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(
        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 deleteCommand = Command.make(
  "delete",
  {
    path: requiredPathArgument,
    recursive,
    main: config,
    envFile,
    profile,
    backend,
    name: storeName,
  },
  instrumentCommand("state.delete")(
    Effect.fn(function* ({ path, recursive, ...args }) {
      const requested = yield* normalizedPath(path);
      if (requested === "") {
        return yield* new UserInputError({ message: "cannot delete the state root" });
      }
      const store = yield* Alchemist.State.store(source(args));
      yield* usingStore(store)(State.deleteState({ path: requested, recursive }));
      yield* Interaction.success(`Deleted state at ${requested}`);
    }),
  ),
).pipe(
  Command.withAlias("rm"),
  Command.withDescription("Delete state records without deleting cloud resources"),
);

const stateExplorer = (args: StateArgs) =>
  Effect.gen(function* () {
    const cli = yield* Interaction.Interaction;
    const store = yield* Alchemist.State.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
      .session(cli.prompt.screen(stateExplorerScreen(explorer, services)), { alternate: true })
      .pipe(Effect.catchTag("TerminalCancelled", () => Effect.void));
  });

const nukeCommand = Command.make(
  "nuke",
  { main: config, envFile, profile, backend, name: storeName, yes },
  instrumentCommand("state.unsafe.nuke")(
    Effect.fn(function* ({ yes, ...args }) {
      const store = yield* Alchemist.State.store(source(args));
      const stacks = [...(yield* store.listStacks())].sort();
      if (stacks.length === 0) {
        yield* Interaction.info("Nothing to clear.");
        return;
      }
      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(Interaction.success(`Cleared ${stack}`))),
        { concurrency: 32, discard: true },
      );
    }),
  ),
).pipe(
  Command.withDescription("Delete all stacks, stages, and outputs from the state store"),
  Command.unlisted,
);

const bootstrapCommand = Command.make(
  "bootstrap",
  {
    main: config,
    envFile,
    profile,
    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 (with --backend)",
      ),
      Flag.withDefault(false),
    ),
  },
  instrumentCommand("state.bootstrap")(
    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(", ")})`,
      );
    }),
  ),
).pipe(Command.withDescription("Provision (or adopt) a state store"));

const teardownCommand = Command.make(
  "teardown",
  { envFile, profile, backend: lifecycleBackend, name: storeName, yes },
  instrumentCommand("state.teardown")(
    Effect.fn(function* ({ yes: approved, ...args }) {
      yield* confirmOrDecline({
        yes: approved,
        message: `Tear down the ${args.backend} state store and its backing resources?`,
        confirmLabel: "Destroy",
        cancelLabel: "Cancel",
      });
      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",
  {
    envFile,
    profile,
    backend: lifecycleBackend,
    name: storeName,
    tail: Flag.Boolean("tail").pipe(
      Flag.withAlias("t"),
      Flag.withDescription("Stream logs as they happen instead of fetching past entries"),
      Flag.withDefault(false),
    ),
    limit: Flag.Int("limit").pipe(
      Flag.withDescription("Number of log entries to fetch (ignored with --tail)"),
      Flag.withDefault(100),
    ),
    since: Flag.String("since").pipe(
      Flag.withDescription("Fetch logs since this time (e.g. '1h', '30m', '2024-01-01T00:00:00Z')"),
      Flag.optional,
      Flag.map(Option.getOrUndefined),
    ),
  },
  instrumentCommand("state.logs")(
    Effect.fn(function* ({ tail, limit, since, ...args }) {
      const target = lifecycleSource(args);
      const format = (entry: StateStoreLogEntry) =>
        `${formatLocalTimestamp(entry.timestamp)} ${entry.message}`;
      if (tail) {
        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* Alchemist.State.logs({
        ...target,
        limit,
        since: since ? yield* parseSince(since) : undefined,
      });
      if (entries.length === 0) {
        yield* Console.log(`(no log entries for the ${args.backend} state store)`);
        return;
      }
      for (const entry of entries) yield* Console.log(format(entry));
    }),
  ),
).pipe(Command.withDescription("Fetch or stream a state store's own logs"));

const unsafeCommand = Command.make("unsafe", {}).pipe(
  Command.withDescription("Destructive state operations"),
  Command.withSubcommands([nukeCommand]),
  Command.unlisted,
);

export const stateCommand = Command.make(
  "state",
  { main: config, envFile, profile, backend, name: storeName },
  instrumentCommand("state")(
    Effect.fn(function* (args) {
      if (!(yield* Interaction.Interaction).terminal.input) {
        return yield* failWithHelp(["alchemy", "state"]);
      }
      yield* stateExplorer(args);
    }),
  ),
).pipe(
  Command.withDescription("Inspect and manage deployment state"),
  Command.withSubcommands([
    listCommand,
    readCommand,
    deleteCommand,
    bootstrapCommand,
    teardownCommand,
    migrateCommand,
    logsCommand,
    unsafeCommand,
  ]),
);