@effect/platform-cloudflare 0.0.0-stage → 4.1.3

package/ai-docs/src/52_graphql/20_testing.ts

@@ -0,0 +1,45 @@
+/**
+ * @title Testing code that uses a GraphQL client
+ *
+ * Replace a client service with `GraphQLClient.layerTest`, answering each
+ * operation from a handler instead of a server.
+ */
+import { assert, describe, it } from "@effect/vitest"
+import { Effect } from "effect"
+import { GitHub } from "./10_basics.ts"
+
+// Code under test that depends on the `GitHub` client service.
+const issueTitles = (owner: string, name: string) =>
+  GitHub.use((github) => github.RepoIssues({ owner, name })).pipe(
+    Effect.map(({ repository }) => repository?.issues.nodes?.map((issue) => issue?.title) ?? [])
+  )
+
+// The service binds `GraphQLClient.layerTest(GitHub, GitHubGraphQLGroup)` once
+// as a static helper. Handlers are keyed by operation name, receive the
+// caller's variables and options, and return results in their decoded form.
+// Nothing is encoded or decoded and no middleware runs. An operation without
+// a handler dies with an `UnimplementedError` defect.
+const GitHubTest = GitHub.layerTest({
+  RepoIssues: ({ owner, name }) =>
+    Effect.succeed({
+      repository: {
+        issues: {
+          pageInfo: { hasNextPage: false, endCursor: null },
+          nodes: [{ number: 1, title: `Hello from ${owner}/${name}` }]
+        }
+      }
+    })
+})
+
+describe("issueTitles", () => {
+  it.effect("returns the titles of the first page", () =>
+    Effect.gen(function*() {
+      const titles = yield* issueTitles("Effect-TS", "effect")
+      assert.deepStrictEqual(titles, ["Hello from Effect-TS/effect"])
+    }).pipe(Effect.provide(GitHubTest)))
+})
+
+// `layerTest` uses `makeTest`, which skips the protocol and cannot return
+// partial data together with `errors`. To test that, or the encode and decode
+// path, build the real client with `GraphQLClient.make` over a scripted
+// `GraphQLProtocol` layer (see `GraphQLProtocol`).

package/ai-docs/src/52_graphql/30_batching.ts

@@ -0,0 +1,118 @@
+/**
+ * @title Batching lookups with GraphQLResolver
+ *
+ * Collect concurrent lookups by id into one `nodes(ids:)` request with
+ * `GraphQLResolver`, instead of one request per id.
+ */
+import { type Cause, Context, Effect, Layer, RequestResolver, Schema } from "effect"
+import { GraphQL, GraphQLClient, GraphQLGroup, GraphQLProtocol, GraphQLResolver } from "effect/graphql"
+import { FetchHttpClient } from "effect/http"
+import { GitHubAuth } from "./10_basics.ts"
+
+// The generator's output for `repo-nodes.graphql`:
+//
+//   query RepoNodes($ids: [ID!]!) {
+//     nodes(ids: $ids) { __typename ... on Repository { nameWithOwner } }
+//   }
+//
+// Generated modules import shared codecs and the possible `__typename`s of
+// each interface from the module the generator writes next to the schema
+// (`import * as Shared from "../schema.graphql.ts"`); here `Shared` is
+// declared inline.
+const Shared = { ID: Schema.String }
+declare namespace Shared {
+  export namespace Typename {
+    export type Node = "Issue" | "PullRequest" | "Repository" | "User"
+  }
+}
+
+export const Repository = Schema.Struct({
+  __typename: Schema.Literal("Repository"),
+  nameWithOwner: Schema.String
+})
+export interface Repository extends Schema.Struct.Type<typeof Repository.fields> {}
+
+// Unselected node types are represented by `otherTypename`.
+export const NodeOther = Schema.Struct({
+  __typename: GraphQL.otherTypename<Shared.Typename.Node>()(["Repository"])
+})
+export interface NodeOther extends Schema.Struct.Type<typeof NodeOther.fields> {}
+
+/** `query RepoNodes` */
+export const RepoNodes = GraphQL.query("RepoNodes", {
+  document: {
+    variables: [
+      { name: "ids", body: "[ID!]!" }
+    ],
+    selections: [
+      { name: "nodes", body: ["(ids:$", "ids", "){__typename...on Repository{nameWithOwner}}"] }
+    ],
+    fragments: []
+  },
+  variables: {
+    ids: Schema.Array(Shared.ID)
+  },
+  result: Schema.Struct({
+    nodes: Schema.Array(Schema.NullOr(Schema.Union([
+      Repository,
+      NodeOther
+    ])))
+  })
+})
+export declare namespace RepoNodes {
+  export type Variables = typeof RepoNodes.variables.Type
+  export type Result = typeof RepoNodes.result.Type
+}
+
+/** Every operation in repo-nodes.graphql. */
+export const RepoNodesGraphQLGroup = GraphQLGroup.make(RepoNodes)
+
+// Your code: attach the middleware to the generated group.
+export const GitHubGraphQLGroup = RepoNodesGraphQLGroup.middleware(GitHubAuth)
+
+export class GitHub extends Context.Service<
+  GitHub,
+  GraphQLClient.FromGroup<typeof GitHubGraphQLGroup> & {
+    getRepo(id: string): Effect.Effect<
+      Repository,
+      GraphQL.Error<typeof RepoNodes> | Cause.NoSuchElementError
+    >
+  }
+>()("app/GitHub") {
+  static readonly layer = Layer.effect(
+    GitHub,
+    Effect.gen(function*() {
+      const client = yield* GraphQLClient.make(GitHubGraphQLGroup)
+
+      // Null entries and non-Repository nodes fail with NoSuchElementError.
+      // GitHub accepts at most 100 ids per request.
+      //
+      // GitHubAuth reads one token from config, so every lookup can share a
+      // batch. If a middleware `requires` a per-request service, such as the
+      // signed-in user, `batchKey` is required and keeps lookups for different
+      // users in separate calls:
+      //
+      //   batchKey: (context) => Context.get(context, CurrentUser).id
+      const RepoById = GraphQLResolver.ordered(client.RepoNodes, {
+        variables: (ids: ReadonlyArray<string>) => ({ ids }),
+        path: ["nodes"],
+        typename: "Repository"
+      }).pipe(RequestResolver.batchN(100))
+      return { ...client, getRepo: GraphQLResolver.request(RepoById) }
+    })
+  ).pipe(
+    Layer.provide(GitHubAuth.layer),
+    Layer.provide(GraphQLProtocol.layerHttp({ url: "https://api.github.com/graphql" })),
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+export const repoNames = Effect.fn("repoNames")(function*(ids: ReadonlyArray<string>) {
+  const github = yield* GitHub
+  const repos = yield* Effect.forEach(ids, github.getRepo, { concurrency: "unbounded" })
+  return repos.map((repo) => repo.nameWithOwner)
+})
+
+export const program = repoNames(["R_1", "R_2"]).pipe(
+  Effect.provide(GitHub.layer)
+)

package/ai-docs/src/52_graphql/40_aliased-batching.ts

@@ -0,0 +1,124 @@
+/**
+ * @title Batching single-item lookups with aliases
+ *
+ * When an API has no field that takes a list of keys, `GraphQLResolver.aliased`
+ * repeats a generated operation under aliases, so concurrent lookups share one
+ * request and keep their generated types.
+ */
+import { Context, Effect, Layer, Schema } from "effect"
+import { GraphQL, GraphQLClient, GraphQLGroup, GraphQLProtocol, GraphQLResolver } from "effect/graphql"
+import { FetchHttpClient } from "effect/http"
+import { GitHubAuth } from "./10_basics.ts"
+
+// The generator's output for `pr.graphql`:
+//
+//   query PullRequest($owner: String!, $name: String!, $number: Int!) {
+//     repository(owner: $owner, name: $name) {
+//       pullRequest(number: $number) { number title }
+//     }
+//   }
+//
+// Generated modules import shared codecs, such as `Int`, from the module the
+// generator writes next to the schema (`import * as Shared from
+// "../schema.graphql.ts"`); here `Shared` is declared inline.
+const Shared = { Int: Schema.Number.check(Schema.isInt32()) }
+
+export const PullRequestPullRequest = Schema.Struct({
+  number: Shared.Int,
+  title: Schema.String
+})
+export interface PullRequestPullRequest extends Schema.Struct.Type<typeof PullRequestPullRequest.fields> {}
+
+export const Repository = Schema.Struct({
+  pullRequest: Schema.NullOr(PullRequestPullRequest)
+})
+export interface Repository extends Schema.Struct.Type<typeof Repository.fields> {}
+
+// The generator gives queries and mutations their document as a
+// `GraphQL.DocumentTemplate`. The odd entries of each `body` are the names
+// `aliased` renames per slice; joined together they are the printed document.
+/** `query PullRequest` */
+export const PullRequest = GraphQL.query("PullRequest", {
+  document: {
+    variables: [
+      { name: "owner", body: "String!" },
+      { name: "name", body: "String!" },
+      { name: "number", body: "Int!" }
+    ],
+    selections: [
+      {
+        name: "repository",
+        body: ["(owner:$", "owner", " name:$", "name", "){pullRequest(number:$", "number", "){number title}}"]
+      }
+    ],
+    fragments: []
+  },
+  variables: {
+    owner: Schema.String,
+    name: Schema.String,
+    number: Shared.Int
+  },
+  result: Schema.Struct({
+    repository: Schema.NullOr(Repository)
+  })
+})
+export declare namespace PullRequest {
+  export type Variables = typeof PullRequest.variables.Type
+  export type Result = typeof PullRequest.result.Type
+}
+
+/** Every operation in pr.graphql. */
+export const PrGraphQLGroup = GraphQLGroup.make(PullRequest)
+
+// Your code: attach the middleware to the generated group.
+export const GitHubGraphQLGroup = PrGraphQLGroup.middleware(GitHubAuth)
+
+export class GitHub extends Context.Service<
+  GitHub,
+  GraphQLClient.FromGroup<typeof GitHubGraphQLGroup> & {
+    readonly getPullRequest: (
+      variables: GraphQL.Variables<typeof PullRequest>
+    ) => Effect.Effect<GraphQL.Result<typeof PullRequest>, GraphQL.Error<typeof PullRequest>>
+  }
+>()("app/GitHub") {
+  static readonly layer = Layer.effect(
+    GitHub,
+    Effect.gen(function*() {
+      const client = yield* GraphQLClient.make(GitHubGraphQLGroup)
+
+      // Concurrent calls go out as one POST whose root fields are aliased
+      // `_0_repository`, `_1_repository`, and so on. Each slice is decoded
+      // with the generated result Schema, and a GraphQL error under
+      // `_1_repository` fails only that call.
+      //
+      // A batch holds 10 slices by default, because GitHub's query cost and
+      // timeouts grow with the size of the query. Pipe
+      // `RequestResolver.batchN` to change it.
+      const PullRequests = GraphQLResolver.aliased(client.PullRequest)
+
+      // `request` turns the resolver into a lookup by the operation's
+      // variables, as for `ordered` and `findById`.
+      return { ...client, getPullRequest: GraphQLResolver.request(PullRequests) }
+    })
+  ).pipe(
+    Layer.provide(GitHubAuth.layer),
+    Layer.provide(GraphQLProtocol.layerHttp({ url: "https://api.github.com/graphql" })),
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+export const pullRequestTitles = Effect.fn("pullRequestTitles")(function*(numbers: ReadonlyArray<number>) {
+  const github = yield* GitHub
+  const results = yield* Effect.forEach(
+    numbers,
+    (number) => github.getPullRequest({ owner: "Effect-TS", name: "effect", number }),
+    { concurrency: "unbounded" }
+  )
+  // `repository` and `pullRequest` are nullable, so a missing pull request is
+  // `null` rather than an error that would fail every slice.
+  return results.map((result) => result.repository?.pullRequest?.title ?? null)
+})
+
+export const program = pullRequestTitles([1, 2, 3]).pipe(
+  Effect.provide(GitHub.layer)
+)

package/ai-docs/src/52_graphql/50_errors-and-retries.ts

@@ -0,0 +1,74 @@
+/**
+ * @title Handling GraphQL errors, retries and rate limits
+ *
+ * Read rate-limit headers in a middleware, tell GraphQL errors apart by their
+ * fields, and retry timeouts and rate limits with `Effect.retry`.
+ */
+import { Duration, Effect, Layer, Schedule } from "effect"
+import { type GraphQLClientError, GraphQLMiddleware } from "effect/graphql"
+import { GitHub } from "./10_basics.ts"
+
+// Middleware see each response's HTTP `status` and `headers` on the result
+// `next` returns, including responses with GraphQL `errors`. A failed call
+// keeps them, and `GraphQLClientError` exposes them as `headers` and
+// `status`. Attach it with `GraphQLGroup.make(...).middleware(RateLimit)`.
+export class RateLimit extends GraphQLMiddleware.Service<RateLimit>()("app/RateLimit") {
+  static readonly layer = Layer.succeed(RateLimit, {
+    execute: ({ next, request }) =>
+      Effect.tap(next(request), (result) => {
+        const remaining = Number(result.headers?.["x-ratelimit-remaining"])
+        return remaining < 500
+          ? Effect.logWarning(`GitHub rate limit: ${remaining} points left`)
+          : Effect.void
+      }),
+    subscribe: ({ next, request }) => next(request)
+  })
+}
+
+// GraphQL errors keep fields the specification doesn't define as JSON, such
+// as GitHub's top-level `type` (`NOT_FOUND`, `FORBIDDEN`, `RATE_LIMITED`).
+export const hasErrorType = (error: GraphQLClientError.GraphQLClientError, type: string) =>
+  error.reason._tag === "ResponseError" && error.reason.errors.every((entry) => entry.type === type)
+
+// `isRetryable` is true for network failures, for 429 or 5xx responses, and
+// for any error with a `Retry-After` header, whatever its status. That covers
+// GitHub's 502 and 504 query timeouts, even with a GraphQL `errors` body, and
+// its secondary rate limits (403 or 429 with `retry-after`). A primary rate
+// limit can come without `retry-after`, with `x-ratelimit-remaining: 0`, so
+// check that header too.
+const rateLimited = (error: GraphQLClientError.GraphQLClientError) => error.headers?.["x-ratelimit-remaining"] === "0"
+
+// Wait for `retryAfter` when it is set, and until `x-ratelimit-reset` (epoch
+// seconds) on a primary rate limit. GitHub may ban an integration that keeps
+// retrying while rate limited, so don't retry with a plain backoff.
+const gitHubRetry = Schedule.exponential("1 second").pipe(
+  Schedule.setInputType<GraphQLClientError.GraphQLClientError>(),
+  Schedule.modifyDelay(({ duration, input, now }) => {
+    if (input.retryAfter !== undefined) return Effect.succeed(input.retryAfter)
+    if (!rateLimited(input)) return Effect.succeed(duration)
+    const reset = Number(input.headers?.["x-ratelimit-reset"]) * 1000
+    return Effect.succeed(Number.isFinite(reset) ? Duration.millis(Math.max(0, reset - now)) : Duration.minutes(1))
+  })
+)
+
+// The client never retries queries or mutations on its own. Retry only
+// mutations that are safe to send twice, and with `GraphQLClient.pages`,
+// retry inside a middleware, because `Stream.retry` starts again from the
+// first page. Subscriptions reconnect on their own after a retryable failure,
+// on `GraphQLClient.defaultSubscriptionRetry`, which waits for `retryAfter`.
+// A primary rate limit without `retry-after` isn't retryable, so it ends the
+// subscription; wait until `x-ratelimit-reset` before subscribing again.
+export const retryGitHub = <A, R>(effect: Effect.Effect<A, GraphQLClientError.GraphQLClientError, R>) =>
+  Effect.retry(effect, {
+    schedule: gitHubRetry,
+    while: (error) => error.isRetryable || rateLimited(error),
+    times: 5
+  })
+
+export const program = Effect.gen(function*() {
+  const github = yield* GitHub
+  const result = yield* retryGitHub(github.RepoIssues({ owner: "Effect-TS", name: "missing" })).pipe(
+    Effect.catchIf((error) => hasErrorType(error, "NOT_FOUND"), () => Effect.succeed(null))
+  )
+  yield* Effect.log(result === null ? "No such repository" : `${result.repository?.issues.nodes?.length} issues`)
+}).pipe(Effect.provide(GitHub.layer))

package/ai-docs/src/52_graphql/index.md

@@ -0,0 +1,6 @@
+## Typed GraphQL clients with `effect/graphql`
+
+Use the `effect/graphql` modules to call GraphQL APIs with typed
+operations. Run `graphqlgen` from `@effect/graphql-generator` to generate
+operations from `.graphql` documents, then build a client with
+`GraphQLClient.make` and provide a transport from `GraphQLProtocol`.

package/ai-docs/src/60_child-process/10_working-with-child-processes.ts

@@ -0,0 +1,117 @@
+/**
+ * @title Working with child processes
+ *
+ * This example shows how to collect process output, compose pipelines, and stream long-running command output.
+ */
+import { NodeServices } from "@effect/platform-node"
+import { Console, Context, Effect, Layer, Schema, Stream, String } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+export class DevToolsError extends Schema.TaggedError<DevToolsError>()("DevToolsError", {
+  cause: Schema.Defect()
+}) {}
+
+export class DevTools extends Context.Service<DevTools, {
+  readonly nodeVersion: Effect.Effect<string, DevToolsError>
+  readonly recentCommitSubjects: Effect.Effect<ReadonlyArray<string>, DevToolsError>
+  readonly runLintFix: Effect.Effect<void, DevToolsError>
+  changedTypeScriptFiles(baseRef: string): Effect.Effect<ReadonlyArray<string>, DevToolsError>
+}>()("docs/DevTools") {
+  static readonly layer = Layer.effect(
+    DevTools,
+    Effect.gen(function*() {
+      // To run child processes, we need access to a `ChildProcessSpawner`.
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+
+      // Use `spawner.string` when you want to collect the entire output of a
+      // command as a string. This runs `node --version` and collects the
+      // output.
+      const nodeVersion = spawner.string(
+        ChildProcess.make("node", ["--version"])
+      ).pipe(
+        Effect.map(String.trim),
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const changedTypeScriptFiles = Effect.fn("DevTools.changedTypeScriptFiles")(function*(baseRef: string) {
+        yield* Effect.annotateCurrentSpan({ baseRef })
+
+        // `spawner.lines` is a convenience helper for line-oriented command
+        // output.
+        const files = yield* spawner.lines(
+          ChildProcess.make("git", ["diff", "--name-only", `${baseRef}...HEAD`])
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        return files.filter((file) => file.endsWith(".ts"))
+      })
+
+      // Build a pipeline from two command values. This runs:
+      // `git log --pretty=format:%s -n 20 | head -n 5`
+      const recentCommitSubjects = spawner.lines(
+        ChildProcess.make("git", ["log", "--pretty=format:%s", "-n", "20"]).pipe(
+          ChildProcess.pipeTo(ChildProcess.make("head", ["-n", "5"]))
+        )
+      ).pipe(
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const runLintFix = Effect.gen(function*() {
+        // Use `spawn` when you want the process handle and stream output while
+        // the process is still running.
+        const handle = yield* spawner.spawn(
+          ChildProcess.make("pnpm", ["lint-fix"], {
+            env: { FORCE_COLOR: "1" },
+            extendEnv: true
+          })
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        yield* handle.all.pipe(
+          Stream.decodeText(),
+          Stream.splitLines,
+          Stream.runForEach((line) => Console.log(`[lint-fix] ${line}`)),
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        const exitCode = yield* handle.exitCode.pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+          return yield* new DevToolsError({
+            cause: new Error(`pnpm lint-fix failed with exit code ${exitCode}`)
+          })
+        }
+      }).pipe(
+        // `spawner.spawn` adds a `Scope` requirement to manage the lifecycle of
+        // the child process. We can use `Effect.scoped` to provide a `Scope`
+        // and close it when the effect completes.
+        Effect.scoped
+      )
+
+      return DevTools.of({
+        nodeVersion,
+        changedTypeScriptFiles,
+        recentCommitSubjects,
+        runLintFix
+      })
+    })
+  ).pipe(
+    // Provide the `ChildProcessSpawner` dependency from `NodeServices.layer`.
+    Layer.provide(NodeServices.layer)
+  )
+}
+
+export const program = Effect.gen(function*() {
+  const tools = yield* DevTools
+
+  const version = yield* tools.nodeVersion
+  yield* Effect.log(`node=${version}`)
+}).pipe(
+  // `ChildProcess` requires a platform implementation of
+  // `ChildProcessSpawner`. In Node.js, `NodeServices.layer` provides it.
+  Effect.provide(DevTools.layer)
+)

package/ai-docs/src/60_child-process/index.md

@@ -0,0 +1,3 @@
+## Working with child processes
+
+Use the `effect/process` modules to define child processes and run them with `ChildProcessSpawner`.

package/ai-docs/src/70_cli/10_basics.ts

@@ -0,0 +1,162 @@
+/**
+ * @title Getting started with Effect CLI modules
+ *
+ * Build a command-line app with typed arguments and flags, then wire subcommand
+ * handlers into a single executable command.
+ */
+import { NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Console, Effect, Option, Schema } from "effect"
+import { Argument, Command, Flag } from "effect/cli"
+
+// You can define flags outside of commands and reuse them across multiple
+// commands.
+const workspace = Flag.String("workspace").pipe(
+  Flag.withAlias("w"),
+  Flag.withDescription("Workspace to operate on"),
+  Flag.withDefault("personal")
+)
+
+// Start with a root command and explicitly share the parent flags that should
+// be available to all subcommands.
+const tasks = Command.make("tasks").pipe(
+  Command.withSharedFlags({
+    workspace,
+    verbose: Flag.Boolean("verbose").pipe(
+      Flag.withAlias("v"),
+      Flag.withDescription("Print diagnostic output"),
+      Flag.withDefault(false)
+    )
+  }),
+  Command.withDescription("Track and manage tasks")
+)
+
+// Arguments and flags parse plain strings; use `withSchema` to validate or
+// transform the parsed value with any schema.
+const Email = Schema.String.pipe(
+  Schema.check(Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
+    message: "Expected a valid email address"
+  }))
+)
+
+const create = Command.make(
+  "create",
+  {
+    title: Argument.String("title").pipe(
+      Argument.withDescription("Task title"),
+      // Reject empty titles at parse time, so the handler only ever sees
+      // valid input
+      Argument.withSchema(Schema.NonEmptyString)
+    ),
+    priority: Flag.Literals("priority", ["low", "normal", "high"]).pipe(
+      Flag.withDescription("Priority for the new task"),
+      Flag.withDefault("normal")
+    ),
+    assignee: Flag.String("assignee").pipe(
+      Flag.withDescription("Email address of the person to assign"),
+      Flag.withSchema(Email),
+      Flag.optional
+    )
+  },
+  Effect.fn(function*({ assignee, priority, title }) {
+    // Subcommands can read parent command input by yielding the parent command.
+    const root = yield* tasks
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=create`)
+    }
+
+    yield* Console.log(`Created "${title}" in ${root.workspace} with ${priority} priority`)
+
+    if (Option.isSome(assignee)) {
+      yield* Console.log(`Assigned to ${assignee.value}`)
+    }
+  })
+).pipe(
+  Command.withDescription("Create a task"),
+  Command.withExamples([
+    {
+      command: "tasks create \"Ship 4.0\" --priority high",
+      description: "Create a high-priority task"
+    },
+    {
+      command: "tasks create \"Ship 4.0\" --assignee dev@acme.com",
+      description: "Create a task assigned to a team member"
+    }
+  ])
+)
+
+const list = Command.make(
+  "list",
+  {
+    status: Flag.Literals("status", ["open", "done", "all"]).pipe(
+      Flag.withDescription("Filter tasks by status"),
+      Flag.withDefault("open")
+    ),
+    json: Flag.Boolean("json").pipe(
+      Flag.withDescription("Print machine-readable output"),
+      Flag.withDefault(false)
+    )
+  },
+  Effect.fn(function*({ status, json }) {
+    const root = yield* tasks
+    const items = [
+      { title: "Ship 4.0", status: "open" },
+      { title: "Update onboarding guide", status: "done" }
+    ] as const
+    const filtered = status === "all"
+      ? items
+      : items.filter((item) => item.status === status)
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=list`)
+    }
+
+    if (json) {
+      yield* Console.log(JSON.stringify(
+        {
+          workspace: root.workspace,
+          status,
+          items: filtered
+        },
+        null,
+        2
+      ))
+      return
+    }
+
+    yield* Console.log(`Listing ${status} tasks in ${root.workspace}`)
+    if (filtered.length === 0) {
+      yield* Console.log("- No tasks found")
+      return
+    }
+
+    for (const item of filtered) {
+      yield* Console.log(`- ${item.title}`)
+    }
+  })
+).pipe(
+  Command.withDescription("List tasks"),
+  Command.withAlias("ls"),
+  Command.withExamples([
+    {
+      command: "tasks --workspace team-a list --status open",
+      description: "List open tasks in a specific workspace"
+    },
+    {
+      command: "tasks --workspace team-b ls --status open",
+      description: "List open tasks in another workspace"
+    }
+  ])
+)
+
+// Finally, compose the subcommands into a single command and then run it.
+tasks.pipe(
+  Command.withSubcommands([create, list]),
+  Command.run({
+    version: "1.0.0"
+  }),
+  // Provide the services for the platform you are targeting. In this case,
+  // Node.js
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain
+)

package/ai-docs/src/70_cli/index.md

@@ -0,0 +1,5 @@
+## Building CLI applications
+
+Use the "effect/cli" modules to build CLI applications. These modules
+provide utilities for parsing command-line arguments, handling user input, and
+managing the flow of a CLI application.