@effected/cli 0.25.0 → 0.27.0

package/README.md

@@ -1,216 +1,13 @@
 # @effected/cli
 
-[![npm](https://img.shields.io/npm/v/@effected%2Fcli?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
-[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
-[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+The `effected` command: the tool's command tree on the kit's front-end runtime (`@effected/cli-kit`).
 
-The presentation boundary of a command-line program built on `effect/cli`: who the output is for, and how it reaches them. Plain log lines on the right stream. Colour, glyphs and links only where the terminal and the reader can use them. Documents rendered for a person, an agent or a CI log. Failures reported through your own logger with the right exit code. Prompts that know when there is nobody to ask. Interactive screens and live progress views drawn with Ink. `effect/cli` still owns argument parsing, flags, the command tree and help; this package adds no parser and no command model.
-
-> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
-> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
-> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
-> `@effect/*` versions on the line the kit is built and tested against, install
-> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
->
-> **Stability: unstable.** This package's API surface is not yet considered
-> complete and may change across `0.x` releases. Pin an exact version — even a
-> package marked *stable* before `1.0.0` can introduce a breaking change by
-> accident, and an exact pin turns that into a type-check error rather than a
-> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
-
-## Why @effected/cli
-
-Everything here shares one property: **you only discover you needed it by shipping bad output to a person or a machine.** None of it fails a type-check, a test, or a review of the code in isolation.
-
-Effect's default logger emits `[00:33:56.619] INFO (#2): message`, which is right for a service and noise for a tool someone is watching. A platform `runMain` reports an unhandled failure through that same default logger, outside the layers your program was given, so it prints on **stdout**, the one stream errors must not use. Colour codes end up in an agent's context window. A prompt fires inside a pipe and hangs. A file name containing `::error::` becomes a workflow command in GitHub Actions. And a decode failure arrives as a structured tree when a user needs a sentence naming the key they got wrong.
-
-This package makes those decisions once, at the edge of the program, from the environment it actually runs in.
-
-## Install
-
-```bash
-npm install @effected/cli @effected/env @effected/glob @effected/walker effect
-```
-
-```bash
-pnpm add @effected/cli @effected/env @effected/glob @effected/walker effect
-```
-
-Requires Node.js >=24.11.0. `effect` v4, `@effected/env` (the audience and terminal services), and `@effected/walker` with its `@effected/glob` peer (the project root for editor links) are peer dependencies. The one runtime dependency is `@effected/github-commands`. The package never imports a platform package, so it runs unchanged on Node, Bun and Deno.
-
-Optional peers:
-
-- **`ink` and `react`**, plus **`@types/react`** for TypeScript, for the interactive screens and live views in `@effected/cli/ui`. The root never reaches them, and `./ui` loads neither until a screen first mounts. Without `@types/react`, a program compiled with `skipLibCheck` silently types every screen as `any`.
-
-  ```bash
-  npm install ink react @types/react
-  ```
-
-- **`@effected/config-file`**, only for `ConfigIssueRenderer`. It is imported as a type, so nothing at runtime reaches for it.
-
-All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
-
-## Quick start
-
-One wiring serves every program: share the audience flags on the root command, run it through `CliAudience.run`, and hand that to `CliRuntime.main` with an `env`.
-
-```ts
-import { CliAudience, CliExit, CliMessage, CliRuntime, Doc } from "@effected/cli";
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Effect } from "effect";
-import { Command } from "effect/cli";
-
-const sync = Command.make("sync", {}, () =>
-  Effect.gen(function* () {
-    yield* CliMessage.info("syncing 2 repositories");
-    yield* Doc.print([
-      Doc.table(
-        [{ header: "Repository" }, { header: "Files", align: "right" }],
-        [
-          ["acme/widgets", "12"],
-          ["acme/gadgets", "3"],
-        ],
-      ),
-    ]);
-    yield* CliMessage.warning("acme/gadgets has no default branch");
-    // A finding, not a crash: the handler succeeds and the run still exits 1.
-    yield* CliExit.set(1);
-  }),
-);
-
-const root = Command.make("tool").pipe(Command.withSharedFlags(CliAudience.flags()), Command.withSubcommands([sync]));
-
-NodeRuntime.runMain(
-  CliRuntime.main(CliAudience.run(root, { version: "1.0.0" }), {
-    platform: NodeServices.layer,
-    env: {
-      audienceEnvVar: "TOOL_AUDIENCE",
-      stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true),
-    },
-  }),
-);
-```
-
-```text
-$ tool sync
-ℹ syncing 2 repositories
-Repository    Files
-------------  -----
-acme/widgets     12
-acme/gadgets      3
-⚠ acme/gadgets has no default branch
-$ echo $?
-1
-```
-
-At a colour terminal the glyphs are painted and the header is bold. For an agent (`--agent`, `TOOL_AUDIENCE=agent`, or an agent detected from the environment), in a pipe, or under `NO_COLOR`, the same program writes no escape sequence of any kind. Under GitHub Actions, anything the runner could read as a workflow command is neutralized. A failure anywhere renders as a short report on stderr and exits non-zero.
-
-## Audiences
-
-The audience is decided once per run: an audience flag (`--audience <human|agent|ci>`, `--human`, `--agent`, `--ci`), then the override variable you name, then an agent detected from the environment, then CI, else a human. It decides:
-
-| | Human | Agent | CI |
-| --- | --- | --- | --- |
-| Colour | When the stream has it | Never, even with `FORCE_COLOR` | When the stream has it (messages) |
-| `Doc.print` | `ansi`: painted, OSC 8 links | `plain` | `githubLog` under GitHub Actions, else `plain` |
-| Width | The terminal's | Unbounded | Unbounded |
-| Diagnostics (`CliLog`) | Pretty lines | NDJSON | NDJSON |
-| Prompts and screens | When interactive | Never | Never |
-
-Colour follows Node's precedence, per stream: `FORCE_COLOR` decides first and beats `NO_COLOR` (`1`–`3` on, even in a pipe; `0` off). Otherwise there is no colour without a terminal. On a terminal, a non-empty `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb` turns it off. `TERM=dumb` also switches to ASCII glyphs and makes the run non-interactive.
-
-## Output
-
-- **`CliMessage`**: `success`, `info`, `warning`, `failure` and `status(vocab, name, text)`. One themed line each, through `Console` rather than the logger, so no log level silences them. Warnings and failures go to stderr.
-- **`Doc` and `Render`**: a document IR (headings, paragraphs, lists, tables, trees, counts, count tables, collapsibles, callouts, code blocks, diffs, GitHub annotations) and pure `plain`, `ansi`, `markdown` and `githubLog` renderers. `Doc.print` picks the renderer for the audience, and lays out at the terminal's width only when the stream is a terminal: piped output (`tool | grep`) never wraps. `Doc.line(content, { wrap: false })` keeps one line whole at any width, glyph and colour included. `Render.contextOf` renders outside Effect, for example markdown for a step summary.
-- **`CliTheme`, `Token`, `Status`, `Glyphs`**: semantic tokens (`success`, `failure`, `warning`, `info`, `error`, `muted`, `accent`, `emphasis`), an extendable status vocabulary with glyphs and ranks, and Unicode or ASCII glyph sets. Override tokens with `env.theme`.
-- **`CliLinks`**: file links that open in VS Code (`vscode://file/…`) or as `file://` URLs, as OSC 8 hyperlinks where the terminal renders them, never for an agent.
-- **`Fmt`**: `sanitize`, `width`, `truncate`, `duration`, `percent` and `plural`.
-
-Every string that enters a document or a message is sanitised: escape sequences and control characters are removed, so data cannot paint the terminal or plant a link.
-
-## Failures and exit codes
-
-`CliRuntime.main` reports a failure as a document on stderr, through the audience's renderer: a status line for a typed failure, a tree of rejected values for a schema failure, and a defect's message with a collapsible stack of your own frames (Effect's, Node's and `node_modules` frames hidden). Give an error class a `[CliDoc]()` method to draw itself, or pass a `render` option. Its `details.lines({ status: false })` keeps the run's colour and paths behind your own prefix. The `in: outer › inner` span trail after a failure names only your own spans by default; `env.spans` (`"app"`, `"all"` or `"off"`) chooses, as `env.stackFrames` does for a defect's frames. `"app"` leaves out spans defined in files under `node_modules/@effected/` or `node_modules/effect/`, and fails open: a kit package linked into a workspace, or a bundled program, shows more, never less. A program that is itself installed under `node_modules/@effected/` passes its bin's `import.meta.url` as `env.appModule` to keep its own spans. `env.spansEnvVar` names a variable (say `TOOL_SPANS`) that sets it at run time, as `log.envVar` sets the level. An `Effect.fn` call and its definition are one entry in the trail.
-
-- `CliExit.set(code)` records a findings exit code from a handler that still succeeds. Do not provide `CliExit.layer` yourself under `main`, or the code goes to a second, unread cell.
-- `Cancelled` (a prompt quit) exits `130`, and `NotInteractive` (a prompt with nobody to ask) exits `64`, each as one fixed line.
-- A usage error exits `64`. `helpOnUsageError: "stderr"` keeps stdout clean for a caller piping it into `jq`.
-- Without `main`: `CliRuntime.reportFailures()` is the combinator to apply inside your program, and `CliRuntime.reported(error, code)` marks an error you printed yourself.
-
-`SchemaIssueRenderer.render(issue)` and `ConfigIssueRenderer.render(error)` turn an issue tree into lines like `unknown key at groups.g.rulesetz`.
-
-## Logging
-
-`CliLogger` writes plain lines, with no timestamp, level or fiber id, and routes every level to stderr by default (`stderrFrom` narrows it), so stdout carries only the program's output. Pass `env.log` to `main` for **`CliLog`**: a diagnostics level of its own (`level`, or `envVar` such as `TOOL_LOG_LEVEL`, with core's `--log-level` beating both), pretty lines for a person and NDJSON for an agent or CI, an optional NDJSON log file, and `CliLog.component(name)` tags. `CliLog.status(vocab, name, text)` logs a diagnostic with a painted status glyph (its text still sanitised), and `CliTheme.forAudience` applies the kit's "an agent never gets an escape" rule to a theme you paint with yourself.
-
-## Prompts and screens
-
-A prompt fires only when `CliInteractive` is true: a human audience, a terminal on stdin and stdout, and `TERM` not `dumb`. Otherwise it answers a default you supply, or fails cleanly.
-
-```ts
-import { CliPrompt } from "@effected/cli";
-import { Flag, Prompt } from "effect/cli";
-
-// Core's prompt as a flag fallback: asks at a terminal, uses "library" in a pipe.
-const profile = Flag.String("profile").pipe(
-  Flag.withFallbackPrompt(
-    CliPrompt.fallback(
-      Prompt.Select({ message: "Profile", choices: [{ title: "library", value: "library" }, { title: "application", value: "application" }] }),
-      { flag: "profile", otherwise: "library" },
-    ),
-  ),
-);
-```
-
-`@effected/cli/ui` adds Ink screens: `CliUi.run`, `prompt` (with an `otherwise`) and `fallback` (for a flag), over the widgets `Select`, `TextInput` (with a `mask` for secrets, always, or from the moment a predicate spots one anywhere in the value, latched until the value is cleared: its `validate` message is drawn unmasked, so never echo the value in it), `MultiSelect`, `Confirm` (with toggles), `Toggle`, `Tabs` and `Viewport`. Your own screens use the key layer (`KeyTable`, `useKeys`, `KeyHelp`) and the theme bridge (`Styled`, `useTheme`, `useGlyphs`, `useTerminalSize`).
-
-```tsx
-import { CliUi, Select } from "@effected/cli/ui";
-
-const pickProfile = Select.screen({
-  message: "Profile",
-  choices: [
-    { label: "library", value: "library" },
-    { label: "application", value: "application" },
-  ],
-});
-
-const profile = CliUi.prompt(pickProfile, { otherwise: "library" });
-```
-
-`CliUi.map(screen, f)` maps a screen's answer and leaves a cancel alone, so a `Confirm` can back a boolean flag ("confirm, or `--yes`"):
+This release answers `--version` and `--help` only. `effected --version` prints `effected <version>`; when a carrier package launched the bin, it ends with "via" and the carrier's name and version.
 
 ```ts
-import { CliUi, Confirm } from "@effected/cli/ui";
-import { Flag } from "effect/cli";
+import { main } from "@effected/cli/main";
 
-const yes = Flag.Boolean("yes").pipe(
-  Flag.withFallbackPrompt(
-    CliUi.fallback(
-      CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
-      { flag: "yes", otherwise: false },
-    ),
-  ),
-);
+main({ distribution: { name: "@effected/plugin", version: "1.0.0" } });
 ```
 
-## Live views
-
-`CliUi.live` folds a stream or a `PubSub` subscription of events into state, and draws **runs** with Ink while they are going: a run starts at `isStart`, redraws on a tick, and commits its final frame at `isTerminal`. Log lines go above the frame through `handle.logConsole`. End with `handle.close`, which folds everything still queued. When nobody is watching (a pipe, an agent, CI), each run's final frame prints once instead: give the view a `final: (state) => Document` and that run prints the document with no Ink or React loaded at all; `render` is then never called on such a run, not even to build an unused string. `render: CliUi.lazyView(() => import("./view.js"))` keeps the view's module, and React, off every run until one draws. `DocView` draws a `Doc` document inside a view byte for byte as `Doc.print` would, and `UiProvider` with `CliUi.context` gives an Ink tree you mount yourself the same theme.
-
-## Testing
-
-- **`@effected/cli/testing`**: `CliTest.sandbox` and `CliTest.run` spawn a built bin hermetically and return `{ exitCode, stdout, stderr }` as data. `TestTerminal` drives core's prompts.
-- **`@effected/cli/ui/testing`**: `CliUiTest.render` mounts a screen on in-memory streams (`press`, `type`, `chunk`, `frame`, `result`). `view` mounts a display-only element, `session` drives a whole command's screens (its `transcript` shows what reached the terminal, a live view's `logConsole` lines included, `stdoutWritten`/`stderrWritten` each stream alone as raw bytes, `stdoutTranscript`/`stderrTranscript` each stream alone as plain text, and `renderPath: "production"` makes `clear` observable), and `live` mounts a live view on the production render path with a `TestClock` tick. `CliUiTest.serializer` prints frames as token markup in snapshots: register it in the Vitest config with `snapshotSerializers: ["@effected/cli/ui/testing/serializer"]`, or with `expect.addSnapshotSerializer`. Snapshots are the one place a test needs `expect`, since `assert` has no snapshot form.
-
-In-process, provide `layerTest`s from `@effected/env` and `CliTheme.layerTest`, swap in a capturing `Console`, and assert on both streams. Neither testing entrypoint is reachable from a CLI's runtime imports.
-
-## Documentation
-
-Guides for every part, and the full API reference, are at [effected.spencerbeg.gs/cli](https://effected.spencerbeg.gs/cli): [getting started](https://effected.spencerbeg.gs/cli/getting-started), [audiences and output](https://effected.spencerbeg.gs/cli/output), [prompts and screens](https://effected.spencerbeg.gs/cli/prompts), [live views](https://effected.spencerbeg.gs/cli/live-views), [testing](https://effected.spencerbeg.gs/cli/testing) and [advanced](https://effected.spencerbeg.gs/cli/advanced).
-
-## License
-
-[MIT](LICENSE)
+> **Pre-`1.0.0`.** Part of the `@effected/*` kit; unstable across `0.x` releases. Pin an exact version.

package/bin/effected.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../main.js";
+
+// src/bin.ts
+main();
+
+export {  };

package/commands/root.js

@@ -0,0 +1,14 @@
+import { makeSchemaCommand } from "./schema/index.js";
+import { CliAudience } from "@effected/cli-kit";
+import { Command } from "effect/cli";
+
+// src/commands/root.ts
+/**
+* The `effected` command tree, closed over the process boundary it runs against: `main` hands in the process values, a
+* test its own. The audience flags are shared on the root so every subcommand accepts them.
+*
+* @public
+*/
+const makeRootCommand = (deps) => Command.make("effected", {}).pipe(Command.withDescription("The effected tool: a toolchain for Effect v4 applications."), Command.withSharedFlags(CliAudience.flags()), Command.withSubcommands([makeSchemaCommand(deps)]));
+
+export { makeRootCommand };

package/commands/schema/LiveProgress.js

@@ -0,0 +1,114 @@
+import { Console, Effect, PubSub } from "effect";
+import { CliUi, useGlyphs, useStyle } from "@effected/cli-kit/ui";
+import { Box, Text } from "ink";
+import { createElement } from "react";
+
+// src/commands/schema/LiveProgress.ts
+const SETTLED = {
+	written: {
+		label: "written",
+		token: "success"
+	},
+	unchanged: {
+		label: "unchanged",
+		token: "muted"
+	},
+	"would-write": {
+		label: "would write",
+		token: "warning"
+	},
+	drift: {
+		label: "drift",
+		token: "error"
+	},
+	held: {
+		label: "held",
+		token: "muted"
+	},
+	"gate-failed": {
+		label: "gate failed",
+		token: "error"
+	}
+};
+const reduce = (state, event) => {
+	const update = (name, row) => ({ rows: state.rows.map((current) => current.name === name ? {
+		name,
+		...row
+	} : current) });
+	switch (event._tag) {
+		case "Started": return { rows: event.names.map((name) => ({
+			name,
+			pending: true,
+			label: "checking",
+			token: "muted"
+		})) };
+		case "SchemaChecked": return update(event.name, event.blocked ? {
+			pending: true,
+			label: "gate failed",
+			token: "error"
+		} : event.verdict === "drift" ? {
+			pending: true,
+			label: "drift",
+			token: "error"
+		} : event.change === "none" ? {
+			pending: true,
+			label: "clean",
+			token: "muted"
+		} : {
+			pending: true,
+			label: event.change,
+			token: "warning"
+		});
+		case "SchemaDone": return update(event.report.name, {
+			pending: false,
+			...SETTLED[event.report.outcome]
+		});
+		case "Ended": return state;
+	}
+};
+const RowView = ({ row, frame }) => {
+	const glyphs = useGlyphs();
+	const name = useStyle("emphasis");
+	const label = useStyle(row.token);
+	const mark = row.pending ? glyphs.spinner[frame % glyphs.spinner.length] ?? "" : glyphs.bullet;
+	return createElement(Text, null, createElement(Text, label, `${mark} `), createElement(Text, name, row.name), createElement(Text, label, ` ${row.label}`));
+};
+/**
+* The view's options, less the events: one value, so the test drives what the command runs.
+*
+* @internal
+*/
+const liveProgress = {
+	initial: { rows: [] },
+	reduce,
+	render: (state, frame) => createElement(Box, { flexDirection: "column" }, ...state.rows.map((row) => createElement(RowView, {
+		key: row.name,
+		row,
+		frame
+	}))),
+	isStart: (event) => event._tag === "Started",
+	isTerminal: (event) => event._tag === "Ended"
+};
+/**
+* Run the walk under the view: its progress feeds the rows, and its log lines write above the frame.
+*
+* @remarks
+* The frame is committed before the walk's answer is handed back, whichever way it ended, so what follows prints
+* below it and a walk that failed keeps the rows it reached.
+*
+* @internal
+*/
+const withLiveProgress = (walk) => Effect.gen(function* () {
+	const pubsub = yield* PubSub.unbounded();
+	const events = yield* PubSub.subscribe(pubsub);
+	const view = yield* CliUi.live({
+		...liveProgress,
+		events
+	});
+	const exit = yield* Effect.exit(walk((event) => Effect.asVoid(PubSub.publish(pubsub, event))).pipe(Effect.provideService(Console.Console, view.logConsole)));
+	yield* PubSub.publish(pubsub, { _tag: "Ended" });
+	yield* view.close;
+	return yield* exit;
+}).pipe(Effect.scoped);
+
+export { liveProgress, withLiveProgress };

package/commands/schema/build.js

@@ -0,0 +1,9 @@
+import { execute } from "./execute.js";
+import { commandFlags } from "./flags.js";
+import { Command } from "effect/cli";
+
+// src/commands/schema/build.ts
+/** `effected schema build`: generate, gate and write every schema and catalog entry the config declares. */
+const makeBuildCommand = (deps) => Command.make("build", commandFlags, (input) => execute("build", input, deps)).pipe(Command.withDescription("Generate, gate and write every schema the config declares, its catalog slice, and the merged catalog"));
+
+export { makeBuildCommand };

package/commands/schema/check.js

@@ -0,0 +1,12 @@
+import { execute } from "./execute.js";
+import { commandFlags } from "./flags.js";
+import { Command } from "effect/cli";
+
+// src/commands/schema/check.ts
+/**
+* `effected schema check`: the same walk as `build`, reported and never written. The CI drift gate: it also fails when
+* the committed documents are stale, and on outputs nothing claims, which `build` never deletes.
+*/
+const makeCheckCommand = (deps) => Command.make("check", commandFlags, (input) => execute("check", input, deps)).pipe(Command.withDescription("Report what build would do, fail when it would write anything or refuse to, or when a catalog file or document is orphaned or the merged catalog is blocked, and write nothing"));
+
+export { makeCheckCommand };

package/commands/schema/errors.js

@@ -0,0 +1,121 @@
+import { Schema } from "effect";
+
+// src/commands/schema/errors.ts
+const DriftedSchema = Schema.Struct({
+	$id: Schema.String,
+	change: Schema.Literals([
+		"none",
+		"created",
+		"annotations",
+		"contract"
+	]),
+	version: Schema.optionalKey(Schema.String),
+	nextVersion: Schema.optionalKey(Schema.String)
+});
+/**
+* A published schema drifted under `onDrift: "error"`, so nothing was written. Exit `1`.
+*
+* @public
+*/
+var DriftError = class extends Schema.TaggedError()("DriftError", { drifted: Schema.Array(DriftedSchema) }) {
+	get count() {
+		return this.drifted.length;
+	}
+	get message() {
+		const lines = this.drifted.map((s) => `  ${s.$id}: ${s.change}${s.version !== void 0 ? ` at published ${s.version}` : ""}${s.nextVersion !== void 0 ? ` → suggest ${s.nextVersion}` : ""}`);
+		return `${this.count} published schema(s) drifted; nothing was written.\n${lines.join("\n")}\nBump the drifting versions in the config, or re-run with --force to write anyway.`;
+	}
+};
+/**
+* A schema failed the lint/validation gate, so nothing was written. Exit `1`.
+*
+* @public
+*/
+var GateError = class extends Schema.TaggedError()("GateError", { count: Schema.Number }) {
+	get message() {
+		return `${this.count} schema(s) failed the lint/validation gate; nothing was written.`;
+	}
+};
+/**
+* The merged catalog could not be assembled: a catalog URL or entry name is advertised more than once across the
+* slices, or a slice is not a catalog entry array. Nothing is merged silently, so the merged catalog was left as it
+* is. Exit `1` under both `build` and `check`: only an edit to the slices or the configs clears it.
+*
+* @public
+*/
+var CatalogMergeError = class extends Schema.TaggedError()("CatalogMergeError", {
+	path: Schema.String,
+	conflicts: Schema.Array(Schema.Union([Schema.Struct({
+		kind: Schema.Literal("url"),
+		url: Schema.String,
+		slices: Schema.Array(Schema.String)
+	}), Schema.Struct({
+		kind: Schema.Literal("name"),
+		name: Schema.String,
+		slices: Schema.Array(Schema.String)
+	})])),
+	invalid: Schema.Array(Schema.Struct({
+		path: Schema.String,
+		reason: Schema.String
+	}))
+}) {
+	get message() {
+		const lines = [...this.conflicts.map((conflict) => `  ${conflict.kind === "url" ? `url ${conflict.url}` : `name ${conflict.name}`} is advertised by ${conflict.slices.join(", ")}`), ...this.invalid.map(({ path, reason }) => `  ${path} is invalid: ${reason}`)];
+		return `The merged catalog ${this.path} was not written.\n${lines.join("\n")}\nGive each catalog URL and name to exactly one config, and fix or delete every invalid slice.`;
+	}
+};
+/**
+* `check` found committed documents that differ from what the config generates, or outputs nothing claims, which
+* `build` never deletes. `check` is the CI drift gate, so a stale tree fails it. Exit `1`. `count` is every finding;
+* `orphaned` the part of it a build cannot clear, so the message names both remedies.
+*
+* @public
+*/
+var StaleError = class extends Schema.TaggedError()("StaleError", {
+	count: Schema.Number,
+	orphaned: Schema.optionalKey(Schema.Number)
+}) {
+	get message() {
+		const orphaned = this.orphaned ?? 0;
+		const stale = this.count - orphaned;
+		return [...stale > 0 ? [`${stale} document(s) are stale; run \`effected schema build\` and commit the result.`] : [], ...orphaned > 0 ? [`${orphaned} orphaned output(s) must be deleted by hand; build never will.`] : []].join(" ");
+	}
+};
+/**
+* The payload does not conform to the resolved document: the engine answered findings, each already reported. Exit
+* `1`: a validation verdict, the reason CI runs the command.
+*
+* @public
+*/
+var ValidationFailedError = class extends Schema.TaggedError()("ValidationFailedError", {
+	count: Schema.Number,
+	payload: Schema.String,
+	schema: Schema.String
+}) {
+	get message() {
+		return `${this.count} finding(s): ${this.payload} does not conform to ${this.schema}`;
+	}
+};
+/**
+* No schemastore config was found. Exit `2`: the command could not run, where exit `1` means it ran and found a
+* problem. The engine's error says what was searched; this adds the way out, which is the front end's to state because
+* it shows the command that was run.
+*
+* @public
+*/
+var NoConfigError = class extends Schema.TaggedError()("NoConfigError", {
+	/** The file names looked for. */
+	names: Schema.Array(Schema.String),
+	/** The directories walked, or the one explicit path checked. */
+	searched: Schema.Array(Schema.String),
+	/** Whether `searched` is the one path the user named. */
+	explicit: Schema.Boolean,
+	/** What follows `effected schema` in the example: the subcommand and its positionals, with a config path. */
+	usage: Schema.String
+}) {
+	get message() {
+		return `${this.explicit ? `The schemastore config ${this.searched.join(", ")} does not exist.` : `No schemastore config found. Looked for ${this.names.join(", ")} in: ${this.searched.join(", ")}.`}\nRun next to a config, or pass its path, for example: effected schema ${this.usage}`;
+	}
+};
+
+export { CatalogMergeError, DriftError, GateError, NoConfigError, StaleError, ValidationFailedError };

package/commands/schema/execute.js

@@ -0,0 +1,141 @@
+import { DiffDoc } from "../../render/DiffDoc.js";
+import { CatalogMergeError, DriftError, GateError, NoConfigError, StaleError } from "./errors.js";
+import { CliInteractive, CliRuntime, Doc } from "@effected/cli-kit";
+import { ConfigLoadError, ConfigLoader, Report, SchemaRun, StepSummary } from "@effected/engine/schema";
+import { Audience } from "@effected/env";
+import { Console, Effect, Option } from "effect";
+
+// src/commands/schema/execute.ts
+/** `--format` as given, else what the audience reads: JSON for an agent, human text for a person and for CI. */
+const resolveFormat = (format) => Effect.map(Audience, (audience) => Option.getOrElse(format, () => audience.kind === "agent" ? "json" : "human"));
+/** Warned before the walk, because an error from the walk does not carry the mismatch. */
+const warnVersionMismatch = (mismatch) => Effect.logWarning(`VERSION MISMATCH IGNORED (--ignore-version-mismatch): ${mismatch.message}`);
+/** A missing config, with the way out; a load failure's first line, with the rest (a stack) kept at debug. */
+const configFailures = (usage, config) => ({
+	ConfigNotFoundError: (error) => Effect.fail(CliRuntime.reported(new NoConfigError({
+		names: ConfigLoader.CONFIG_NAMES,
+		searched: error.searched,
+		explicit: Option.isSome(config),
+		usage
+	}), 2)),
+	ConfigLoadError: (error) => Effect.gen(function* () {
+		const [first = "", ...rest] = error.reason.split("\n");
+		if (rest.length > 0) yield* Effect.logDebug(rest.join("\n"));
+		return yield* Effect.fail(CliRuntime.reported(new ConfigLoadError({
+			path: error.path,
+			reason: first
+		}), 2));
+	})
+});
+const LINE_TOKENS = [
+	["DRIFT", "error"],
+	["GATE FAILED", "error"],
+	["CATALOG BLOCKED", "error"],
+	["would write", "warning"],
+	["orphaned", "warning"],
+	["written", "success"],
+	["unchanged", "muted"],
+	["held", "muted"]
+];
+const paintedLine = (line) => {
+	const token = LINE_TOKENS.find(([prefix]) => line.startsWith(prefix))?.[1];
+	return token === void 0 ? Doc.text(line) : Doc.text(line, token);
+};
+/**
+* The human report: the outcome lines, each changed document's diff, then the summary, which `Report.human` writes
+* last and which stays at the bottom where a person's eye lands. `Doc.text` is data to every renderer, so a path or a
+* diff line cannot repaint the terminal.
+*/
+const humanDocument = (report) => {
+	const lines = Report.human(report);
+	const outcomes = lines.slice(0, -1);
+	const summary = lines.slice(-1);
+	return Doc.section(void 0, [
+		...outcomes.length > 0 ? [Doc.lines(outcomes.map(paintedLine), { wrap: false })] : [],
+		...report.schemas.flatMap((schema) => schema.diff !== void 0 ? [DiffDoc.render(schema.path, schema.diff)] : []),
+		Doc.lines(summary.map(paintedLine), { wrap: false })
+	]);
+};
+const emit = (report, format, versionMismatch) => Effect.gen(function* () {
+	if (format === "json") {
+		yield* Console.log(Report.json(report, versionMismatch));
+		for (const line of Report.human(report)) yield* Effect.logInfo(line);
+	} else yield* Doc.print([humanDocument(report)]);
+	for (const line of Report.warnings(report)) yield* Effect.logWarning(line);
+});
+const failOnVerdict = (result) => {
+	const { report, verdict } = result;
+	const merged = report.catalog?.merged;
+	switch (verdict) {
+		case "ok": return Effect.void;
+		case "gate-failed": {
+			const count = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
+			return Effect.fail(CliRuntime.reported(new GateError({ count }), 1));
+		}
+		case "drift": {
+			const drifted = report.schemas.filter((schema) => schema.verdict === "drift").map((schema) => ({
+				$id: schema.$id,
+				change: schema.change,
+				...schema.version !== void 0 ? { version: schema.version } : {},
+				...schema.nextVersion !== void 0 ? { nextVersion: schema.nextVersion } : {}
+			}));
+			return Effect.fail(CliRuntime.reported(new DriftError({ drifted }), 1));
+		}
+		case "catalog-blocked": return Effect.fail(CliRuntime.reported(new CatalogMergeError({
+			path: merged?.path ?? "",
+			conflicts: merged?.conflicts ?? [],
+			invalid: merged?.invalid ?? []
+		}), 1));
+		case "stale": {
+			const catalogFiles = [report.catalog?.slice?.outcome, merged?.outcome];
+			const orphaned = catalogFiles.filter((outcome) => outcome === "orphaned").length + (report.orphaned?.length ?? 0);
+			const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + catalogFiles.filter((outcome) => outcome === "would-write").length + orphaned;
+			return Effect.fail(CliRuntime.reported(new StaleError({
+				count,
+				...orphaned > 0 ? { orphaned } : {}
+			}), 1));
+		}
+	}
+};
+/**
+* Run one `build` or `check`.
+*
+* @remarks
+* The live view is for a person watching, so it needs human output and an interactive run, which `CliInteractive` only
+* ever answers `true` for a human audience with terminals. That module, and Ink and React with it, is imported only
+* then: an agent, CI or piped run never loads them. The report is emitted first and the failure follows, so a run that
+* fails has still said why.
+*/
+const execute = Effect.fn("effected.schema.execute")(function* (mode, input, deps) {
+	const format = yield* resolveFormat(input.format);
+	const interactive = yield* CliInteractive;
+	const announce = (event) => Effect.gen(function* () {
+		if (event._tag !== "Started") return;
+		if (input.force) yield* Effect.logWarning(`--force: drift policy is allow for this run; a published document ${mode === "check" ? "would be" : "may be"} rewritten in place, which breaks every consumer pinned to its URL.`);
+		if (event.versionMismatch !== void 0) yield* warnVersionMismatch(event.versionMismatch);
+	});
+	const walk = (onProgress) => SchemaRun.run({
+		mode,
+		force: input.force,
+		versionMismatch: input.ignoreVersionMismatch ? "warn" : "fail",
+		...Option.isSome(input.config) ? { config: input.config.value } : {},
+		...Option.isSome(input.drift) ? { drift: input.drift.value } : {},
+		...Option.isSome(input.onDrift) ? { onDrift: input.onDrift.value } : {}
+	}, {
+		...deps,
+		onProgress: (event) => Effect.andThen(announce(event), onProgress(event))
+	});
+	const result = yield* (format === "human" && interactive ? Effect.flatMap(Effect.promise(() => import("./LiveProgress.js")), ({ withLiveProgress }) => withLiveProgress(walk)) : walk(() => Effect.void)).pipe(Effect.catchTags({
+		...configFailures(`${mode} lib/schemastore.config.ts`, input.config),
+		ConflictingFlagsError: (error) => Effect.fail(CliRuntime.reported(error, 64)),
+		VersionMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 2)),
+		FrozenVersionMissingError: (error) => Effect.fail(CliRuntime.reported(error, 1)),
+		FrozenVersionIdMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 1)),
+		CatalogDirError: (error) => Effect.fail(CliRuntime.reported(error, 2))
+	}));
+	yield* emit(result.report, format, result.versionMismatch);
+	yield* StepSummary.append(Report.markdown(result.report));
+	yield* failOnVerdict(result);
+});
+
+export { configFailures, execute, resolveFormat, warnVersionMismatch };