1
import { describe, expect, it } from "vite-plus/test"
2
import { Context, Data, Effect } from "effect"
3

4
// =============================================================================
5
// 33 - CLI Patterns: Parse, Validate, Execute
6
// =============================================================================
7
//
8
// Parser returns a Command ADT; handler depends on a Terminal service.
9
// Production CLIs replace the hand-rolled parser with @effect/cli — the
10
// shape of the handler is identical.
11

12
class InvalidCommand extends Data.TaggedError("InvalidCommand")<{
13
  readonly message: string
14
}> {}
15

16
type Command =
17
  | { readonly _tag: "Greet"; readonly name: string; readonly shout: boolean }
18
  | { readonly _tag: "Version" }
19

20
//      ┌─── Effect<Command, InvalidCommand, never>
21
//      ▼
22
const parseArgs = (argv: ReadonlyArray<string>): Effect.Effect<Command, InvalidCommand> => {
23
  if (argv[0] === "version") {
24
    return Effect.succeed({ _tag: "Version" })
25
  }
26
  if (argv[0] === "greet") {
27
    const name = argv[1] ?? "World"
28
    const shout = argv.includes("--shout")
29
    return Effect.succeed({ _tag: "Greet", name, shout })
30
  }
31
  return Effect.fail(
32
    new InvalidCommand({ message: `Unknown command: ${argv[0] ?? "<empty>"}` }),
33
  )
34
}
35

36
class Terminal extends Context.Service<Terminal, { readonly writeLine: (line: string) => Effect.Effect<void> }>()("Terminal") {}
37

38
//      ┌─── Effect<void, never, Terminal>
39
//      ▼
40
const runCommand = (command: Command) =>
41
  Effect.gen(function* () {
42
    const terminal = yield* Terminal
43
    if (command._tag === "Version") {
44
      yield* terminal.writeLine("effect-by-effect 1.0.0")
45
      return
46
    }
47
    const message = `Hello, ${command.name}!`
48
    yield* terminal.writeLine(command.shout ? message.toUpperCase() : message)
49
  })
50

51
describe("33 - CLI Patterns", () => {
52
  // @beat
53
  //   id: parse-command
54
  //   shape: one-todo
55
  //   title: Parse argv into a typed Command ADT
56
  //   teaches: A service-free parser turns process.argv into a tagged union; the handler matches on _tag.
57
  //   hint: the Greet variant has _tag "Greet" and carries the parsed name + the shout flag
58
  it("parses argv into a typed Command", async () => {
59
    const command = await Effect.runPromise(parseArgs(["greet", "Ada", "--shout"]))
60
    // Predict the tagged Command value the parser produces.
61
    expect(command).toEqual(/* @stub */ { _tag: "Greet", name: "Ada", shout: true } /* @end */)
62
  })
63
  // @end-beat
64

65
  // @beat
66
  //   id: run-handler
67
  //   shape: one-todo
68
  //   title: Run the handler against a stub Terminal
69
  //   teaches: Side effects live behind a Context.Service so tests can replace Terminal with an in-memory buffer.
70
  //   hint: Greet without shout writes a single greeting line using the parsed name verbatim
71
  it("runs a handler against a stub Terminal service", async () => {
72
    const output: string[] = []
73

74
    await Effect.runPromise(
75
      runCommand({ _tag: "Greet", name: "Ada", shout: false }).pipe(
76
        Effect.provideService(Terminal, {
77
          writeLine: (line) =>
78
            Effect.sync(() => {
79
              output.push(line)
80
            }),
81
        }),
82
      ),
83
    )
84

85
    // Predict the captured output array after running Greet without --shout.
86
    expect(output).toEqual(/* @stub */ ["Hello, Ada!"] /* @end */)
87
  })
88
  // @end-beat
89

90
  // @beat
91
  //   id: invalid-command
92
  //   shape: one-todo
93
  //   title: Reject unknown verbs with a typed error
94
  //   teaches: Unknown subcommands become an InvalidCommand tag in E, never an uncaught throw at the entrypoint.
95
  //   hint: which Data.TaggedError above models a bad verb? that's the _tag the failure carries
96
  it("fails with InvalidCommand for unknown verbs", async () => {
97
    const exit = await Effect.runPromiseExit(parseArgs(["deploy"]))
98

99
    expect(exit._tag).toBe("Failure")
100
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
101
      // Predict the tag of the typed parser failure.
102
      expect(exit.cause.reasons[0].error._tag).toBe(/* @stub */ "InvalidCommand" /* @end */)
103
    }
104
  })
105
  // @end-beat
106

107
  // @beat
108
  //   id: add-command
109
  //   shape: one-todo
110
  //   title: Add a new command to the parser and handler
111
  //   teaches: The Command ADT and runCommand handler are both closed over _tag — adding a command means adding a variant to the union, extending parseArgs, and extending runCommand with a new branch.
112
  //   hint: add { _tag: "Help" } to the Command type, parse "help" in parseArgs, and return terminal.writeLine("Usage: ...") in runCommand
113

114
  it("parses and runs a Help command added to the ADT", async () => {
115
    type ExtendedCommand =
116
      | Command
117
      | { readonly _tag: "Help" }
118

119
    const parseExtended = (
120
      argv: ReadonlyArray<string>,
121
    ): Effect.Effect<ExtendedCommand, InvalidCommand> => {
122
      if (argv[0] === "help") {
123
        return Effect.succeed({ _tag: "Help" })
124
      }
125
      return parseArgs(argv)
126
    }
127

128
    const runExtended = (command: ExtendedCommand) =>
129
      Effect.gen(function* () {
130
        if (command._tag === "Help") {
131
          const terminal = yield* Terminal
132
          yield* terminal.writeLine("Usage: greet <name> [--shout] | version | help")
133
          return
134
        }
135
        yield* runCommand(command as Command)
136
      })
137

138
    const output: string[] = []
139

140
    // Your turn: parse ["help"] with parseExtended, then run it with runExtended
141
    // and a stub Terminal that captures output.
142
    await Effect.runPromise(
143
      /* @stub */ Effect.gen(function* () {
144
        const cmd = yield* parseExtended(["help"])
145
        yield* runExtended(cmd)
146
      }).pipe(
147
        Effect.provideService(Terminal, {
148
          writeLine: (line) =>
149
            Effect.sync(() => {
150
              output.push(line)
151
            }),
152
        }),
153
      ) /* @end */,
154
    )
155

156
    expect(output[0]).toContain("Usage:")
157
  })
158
  // @end-beat
159
})