sailfork / t3code-github / .repos/ alchemy-effect/ packages/ integration-tests/ test/ Domain/ Cli.test.ts

import * as Domain from "@alchemy.run/domain";
import { CallRejected, toCli } from "@alchemy.run/domain/Cli";
import { InMemory } from "@alchemy.run/domain/InMemory";
import { describe, expect, it } from "@alchemy.run/test";
import * as Cause from "effect/Cause";
import * as Command from "effect/cli/Command";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as FileSystem from "effect/FileSystem";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Headers from "effect/http/Headers";
import * as HttpEffect from "effect/http/HttpEffect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as RpcMiddleware from "effect/rpc/RpcMiddleware";
import * as Runtime from "effect/Runtime";
import * as Schema from "effect/Schema";
import * as Stdio from "effect/Stdio";
import * as Terminal from "effect/Terminal";

// ---------------------------------------------------------------- a wallet domain

const WalletId = Schema.String.pipe(Schema.brand("WalletId"));

class Owner extends Domain.RequestContext<Owner>()("Test/Owner", Schema.String) {}
class Unauthenticated extends Domain.Rejection("Unauthenticated") {}
class Session extends RpcMiddleware.Service<Session, { provides: Owner }>()("Test/Session", {
  error: Unauthenticated,
}) {}
/** A bearer token names the owner. */
const SessionLive = Layer.succeed(Session, (effect, { headers }) =>
  Option.match(Headers.get(headers, "authorization"), {
    onNone: () => Effect.fail(new Unauthenticated()),
    onSome: (value) => Effect.provideService(effect, Owner, value.replace(/^Bearer /, "")),
  }),
);

class Deposited extends Domain.Event("Deposited", {
  amount: Schema.Int,
  balance: Schema.Int,
  note: Schema.optional(Schema.String),
}) {}
class OverLimit extends Domain.Rejection("OverLimit", { limit: Schema.Int }) {}

class Deposit extends Domain.Command("Deposit", {
  target: WalletId,
  input: {
    amount: Schema.Int.annotate({ description: "Cents to add" }),
    note: Schema.optional(Schema.String),
    method: Schema.optional(Schema.Literals(["cash", "card"])),
    express: Schema.optional(Schema.Boolean),
    tags: Schema.optional(Schema.Array(Schema.String)),
  },
  middleware: [Session],
  events: [Deposited],
  rejects: [OverLimit],
  reply: { balance: Schema.Int },
}) {}

class Wallet extends Domain.Aggregate("Wallet", {
  id: WalletId,
  state: Schema.Struct({ balance: Schema.Int }),
  initial: { balance: 0 },
  commands: [Deposit],
  decide: {
    Deposit: (s, cmd) =>
      cmd.amount > 100
        ? new OverLimit({ limit: 100 })
        : [new Deposited({ amount: cmd.amount, balance: s.balance + cmd.amount, note: cmd.note })],
  },
  evolve: { Deposited: (_, e) => ({ balance: e.balance }) },
  reply: { Deposit: (s) => ({ balance: s.balance }) },
  read: { middleware: [Session] },
}) {}

class Balance extends Domain.View("Balance", {
  from: [Wallet],
  key: Wallet,
  middleware: [Session],
  state: Schema.Struct({ balance: Schema.Int }),
  initial: { balance: 0 },
  evolve: { Deposited: (_, e) => ({ balance: e.balance }) },
}) {}

class Wallets extends Domain.Model("Wallets", { aggregates: [Wallet], views: [Balance] }) {}

class WalletApi extends Domain.Api("WalletApi", { model: Wallets, aggregates: ["Wallet"] }) {}

// ---------------------------------------------------------------- the CLI over HTTP

/** The CLI's environment, with no terminal: what a script or an agent runs it in. */
const CliEnvironment = Layer.mergeAll(
  FileSystem.layerNoop({}),
  Path.layer,
  Stdio.layerTest({}),
  Layer.succeed(
    Terminal.Terminal,
    Terminal.make({
      columns: Effect.succeed(120),
      rows: Effect.succeed(24),
      size: Effect.die("unused"),
      readInput: Effect.die("unused"),
      readLine: Effect.die("unused"),
      display: () => Effect.void,
    }),
  ),
  Layer.succeed(
    ChildProcessSpawner.ChildProcessSpawner,
    ChildProcessSpawner.make(() => Effect.die("unused")),
  ),
);

interface Run {
  readonly stdout: string;
  readonly stderr: string;
  /** The exit code `runMain` gives the process for this run. */
  readonly code: number;
  readonly exit: Exit.Exit<void, unknown>;
}

/**
 * Serve the Api in process and run the CLI against it over the Api's HTTP
 * protocol: every call is encoded, sent as a request to the Api's `fetch`,
 * and decoded, as it is against a deployed Worker.
 */
const cliOver = Effect.gen(function* () {
  const server = yield* WalletApi;
  const handler = HttpEffect.toWebHandler(server.fetch as never);
  const fetch = ((input: RequestInfo | URL, init?: RequestInit) =>
    handler(new Request(input, init))) as typeof globalThis.fetch;
  return (
    cli: ReturnType<typeof toCli<typeof WalletApi>>,
    args: ReadonlyArray<string>,
    transport: typeof globalThis.fetch = fetch,
  ) =>
    Effect.gen(function* () {
      const stdout: Array<string> = [];
      const stderr: Array<string> = [];
      const console: Console.Console = {
        ...globalThis.console,
        log: (...line: ReadonlyArray<unknown>) => void stdout.push(line.join(" ")),
        error: (...line: ReadonlyArray<unknown>) => void stderr.push(line.join(" ")),
      };
      const exit = yield* Command.runWith(cli, { version: "1.0.0" })(args).pipe(
        Effect.provide(Domain.protocolHttp("http://wallet.test/")),
        Effect.provide(FetchHttpClient.layer),
        Effect.provideService(FetchHttpClient.Fetch, transport),
        Effect.provide(CliEnvironment),
        Effect.provideService(Console.Console, console),
        Effect.exit,
      );
      let code = -1;
      Runtime.defaultTeardown(exit, (c) => (code = c));
      return { stdout: stdout.join("\n"), stderr: stderr.join("\n"), code, exit } satisfies Run;
    });
});

const WalletsLive = Layer.mergeAll(Wallets.layer(Layer.empty), SessionLive).pipe(
  Layer.provide(InMemory),
);
const hosted = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  effect.pipe(Effect.provide(WalletsLive)) as Effect.Effect<A, E>;

const asSam = toCli(WalletApi, {
  name: "wallet",
  headers: { authorization: "Bearer sam" },
});

const json = (text: string): unknown => JSON.parse(text);

// ---------------------------------------------------------------- tests

describe("Domain toCli", { tags: ["unit", "local"] }, () => {
  it.live("runs a command from flags and prints its receipt as JSON", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const deposit = yield* run(asSam, [
          "deposit",
          "--target",
          "w-1",
          "--amount",
          "40",
          "--note",
          "rent",
          "--method",
          "card",
        ]);
        expect(deposit.code).toBe(0);
        expect(deposit.stderr).toBe("");
        expect(json(deposit.stdout)).toEqual({
          reply: { balance: 40 },
          stream: "Wallet/w-1",
          version: 1,
        });

        // The write reached the domain: the aggregate and the view read it back.
        const wallets = yield* Wallet;
        expect((yield* wallets.state(Wallet.ref("w-1"))).balance).toBe(40);
        const get = yield* run(asSam, [
          "balance",
          "get",
          "--key",
          "w-1",
          "--at-least",
          JSON.stringify({ stream: "Wallet/w-1", version: 1 }),
        ]);
        expect(get.code).toBe(0);
        expect(json(get.stdout)).toEqual({ balance: 40 });
        const events = yield* run(asSam, ["balance", "list", "--key", "w-1", "--order", "desc"]);
        expect(json(events.stdout)).toMatchObject({
          entries: [{ event: { _tag: "Deposited", amount: 40, note: "rent" } }],
          cursor: null,
        });
      }),
    ),
  );

  it.live("exits non-zero with a typed rejection as JSON on stderr", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const refused = yield* run(asSam, ["deposit", "--target", "w-1", "--amount", "500"]);
        expect(refused.code).toBe(1);
        expect(refused.stdout).toBe("");
        expect(json(refused.stderr)).toEqual({ _tag: "OverLimit", limit: 100 });
        const failure = Exit.isFailure(refused.exit) ? refused.exit.cause : undefined;
        expect(String(failure)).toContain("CallRejected");

        // The middleware's error is typed too: no bearer, no session.
        const anonymous = yield* run(toCli(WalletApi, { name: "wallet" }), [
          "wallet",
          "get",
          "--key",
          "w-1",
        ]);
        expect(anonymous.code).toBe(1);
        expect(json(anonymous.stderr)).toEqual({ _tag: "Unauthenticated" });
      }),
    ),
  );

  it.live("checks input against the schema before it calls the Api", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const fraction = yield* run(asSam, ["deposit", "--target", "w-1", "--amount", "1.5"]);
        expect(fraction.code).toBe(1);
        expect(fraction.stdout).toBe("");
        expect(fraction.stderr).toContain("amount");
        const missing = yield* run(asSam, ["deposit", "--amount", "5"]);
        expect(missing.code).toBe(1);
        expect(missing.stderr).toContain("target");
        const wallets = yield* Wallet;
        expect((yield* wallets.state(Wallet.ref("w-1"))).balance).toBe(0);
      }),
    ),
  );

  it.live("fails as a usage error when the call does not reach the Api", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const offline = (() => Promise.reject(new TypeError("Unable to connect"))) as never;
        const lost = yield* run(asSam, ["wallet", "get", "--key", "w-1"], offline);
        expect(lost.code).toBe(1);
        expect(lost.stdout).toBe("");
        expect(lost.stderr).toContain("Wallet.get did not reach the Api");
      }),
    ),
  );

  it.live("takes the whole input as --json, and flags win over it", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const deposit = yield* run(asSam, [
          "deposit",
          "--json",
          JSON.stringify({ target: "w-2", amount: 7, tags: ["a", "b"] }),
          "--amount",
          "9",
          "--express",
        ]);
        expect(deposit.code).toBe(0);
        expect(json(deposit.stdout)).toMatchObject({ reply: { balance: 9 } });
        // `--json` alone carries the input fields, as the flags do.
        const fromJson = yield* run(asSam, [
          "deposit",
          "--json",
          JSON.stringify({ target: "w-4", amount: 4, note: "from json" }),
        ]);
        expect(fromJson.code).toBe(0);
        expect(json(fromJson.stdout)).toMatchObject({ reply: { balance: 4 } });
        // The call's own wire JSON, with its nested `input`, works too.
        const fromWire = yield* run(asSam, [
          "deposit",
          "--json",
          JSON.stringify({ target: "w-5", input: { amount: 6, note: "wire" } }),
        ]);
        expect(fromWire.code).toBe(0);
        expect(json(fromWire.stdout)).toMatchObject({ reply: { balance: 6 } });
        const bad = yield* run(asSam, ["deposit", "--json", "{not json"]);
        expect(bad.code).toBe(1);
        expect(bad.stderr).toContain("--json");
      }),
    ),
  );

  it.live("reads headers from an Effect on each run", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const fromEnv = toCli(WalletApi, {
          name: "wallet",
          headers: Effect.sync(() => ({ authorization: "Bearer kim" })),
        });
        const deposit = yield* run(fromEnv, ["deposit", "--target", "w-3", "--amount", "3"]);
        expect(deposit.code).toBe(0);
        const wallet = yield* run(fromEnv, ["wallet", "get", "--key", "w-3"]);
        expect(json(wallet.stdout)).toEqual({ balance: 3 });
      }),
    ),
  );

  it.live("lists what the Api serves and its request/response operations in --help", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        const root = yield* run(asSam, ["--help"]);
        expect(root.code).toBe(0);
        // One subcommand per entry, in kebab-case, with what it is.
        expect(root.stdout).toMatch(/^\s+deposit\s+Send the Deposit command\.$/m);
        expect(root.stdout).toMatch(/^\s+wallet\s+Read the Wallet aggregate\.$/m);
        expect(root.stdout).toMatch(/^\s+balance\s+Read the Balance view\.$/m);

        const balance = yield* run(asSam, ["balance", "--help"]);
        expect(balance.stdout).toMatch(/^\s+get\s+Print the key's current state\.$/m);
        expect(balance.stdout).toMatch(/^\s+list\s+Print a page of the key's entries\.$/m);
        expect(balance.stdout).toMatch(
          /^\s+snapshot\s+Print the key's current state and the cursor it is valid at\.$/m,
        );
        // Live reads are streams: not commands of the CLI.
        expect(balance.stdout).not.toMatch(/\bwatch\b/);
        expect(balance.stdout).not.toMatch(/\bevents\b/);

        const deposit = yield* run(asSam, ["deposit", "--help"]);
        for (const flag of ["--target", "--amount", "--note", "--method", "--express", "--tags"]) {
          expect(deposit.stdout).toContain(flag);
        }
        expect(deposit.stdout).toContain("--command-id");
        expect(deposit.stdout).toContain("--json");
        expect(deposit.stdout).toContain("Cents to add");
      }),
    ),
  );

  it.live("a command whose input names a field target takes its input as --input JSON", () =>
    hosted(
      Effect.gen(function* () {
        class Rename extends Domain.Command("Rename", {
          target: WalletId,
          // `target` here is the input's own field, not the wallet.
          input: { target: Schema.String },
        }) {}
        class Names extends Domain.Aggregate("Names", {
          id: WalletId,
          state: Schema.Struct({}),
          initial: {},
          commands: [Rename],
          decide: { Rename: () => [] },
          evolve: {},
        }) {}
        class Renames extends Domain.Model("Renames", { aggregates: [Names] }) {}
        class RenameApi extends Domain.Api("RenameApi", { model: Renames }) {}
        const run = yield* cliOver;
        const help = yield* run(toCli(RenameApi, { name: "rename" }) as typeof asSam, [
          "rename",
          "--help",
        ]);
        expect(help.code).toBe(0);
        expect(help.stdout).toContain("--target");
        expect(help.stdout).toContain("--input");
      }),
    ),
  );

  it.live("an Api whose names clash on the command line fails with a DefinitionError", () =>
    hosted(
      Effect.gen(function* () {
        const run = yield* cliOver;
        /** The defect a run of the CLI dies with. */
        const defectOf = (cli: unknown) =>
          run(cli as typeof asSam, []).pipe(
            Effect.map(({ exit }) => (Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined)),
          );
        class Clash extends Domain.Command("deposit", {
          target: WalletId,
          events: [Deposited],
        }) {}
        class Clashing extends Domain.Aggregate("Clashing", {
          id: WalletId,
          state: Schema.Struct({}),
          initial: {},
          commands: [Clash],
          decide: { deposit: () => [] },
          evolve: { Deposited: (s) => s },
        }) {}
        class Clashes extends Domain.Model("Clashes", { aggregates: [Wallet, Clashing] }) {}
        class ClashApi extends Domain.Api("ClashApi", { model: Clashes, views: [] }) {}
        expect(yield* defectOf(toCli(ClashApi, { name: "clash" }))).toMatchObject({
          _tag: "DefinitionError",
          message: "ClashApi: `Deposit` and `deposit` are both the command deposit",
        });
        class Reserved extends Domain.Command("Reserved", {
          target: WalletId,
          input: { json: Schema.String },
        }) {}
        class Reserving extends Domain.Aggregate("Reserving", {
          id: WalletId,
          state: Schema.Struct({}),
          initial: {},
          commands: [Reserved],
          decide: { Reserved: () => [] },
          evolve: {},
        }) {}
        class Reserves extends Domain.Model("Reserves", { aggregates: [Reserving] }) {}
        class ReservedApi extends Domain.Api("ReservedApi", { model: Reserves }) {}
        expect(yield* defectOf(toCli(ReservedApi, { name: "reserved" }))).toMatchObject({
          _tag: "DefinitionError",
          message: expect.stringContaining("--json, which the CLI reserves"),
        });
      }),
    ),
  );

  it("is an Effect CLI command named after the binary", () => {
    expect(asSam.name).toBe("wallet");
    expect(toCli(WalletApi).name).toBe("wallet-api");
    expect(CallRejected).toBeDefined();
  });
});