@effected/cli 0.26.0 → 0.27.0

package/commands/root.js

@@ -1,14 +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. This release carries no subcommand: `--version`
-* and `--help` come from the framework, and the audience flags are shared on
-* the root so every future subcommand accepts them.
+* 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 rootCommand = Command.make("effected", {}).pipe(Command.withDescription("The effected tool: a toolchain for Effect v4 applications."), Command.withSharedFlags(CliAudience.flags()));
+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 { rootCommand };
+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 };

package/commands/schema/flags.js

@@ -0,0 +1,24 @@
+import { Argument, Flag } from "effect/cli";
+
+// src/commands/schema/flags.ts
+/** The optional positional config path; omitted, the config is discovered upward from the working directory. */
+const configArgument = Argument.String("config").pipe(Argument.withDescription("Path to a schemastore config module; omitted, schemastore.config.{ts,mts,js,mjs} is searched upward from the working directory"), Argument.optional);
+/** `--format`: absent, JSON for an agent and human text for everyone else. */
+const formatFlag = Flag.Literals("format", ["human", "json"]).pipe(Flag.withDescription("Output format, by default json for an agent and human otherwise; json writes one document to stdout and moves human text to stderr"), Flag.optional);
+/** `--ignore-version-mismatch`: run on past a config from another `@effected/schemastore`. */
+const ignoreVersionMismatchFlag = Flag.Boolean("ignore-version-mismatch").pipe(Flag.withDefault(false), Flag.withDescription("Run even when the config's values come from a different @effected/schemastore than this tool's; warns loudly"));
+/** What `build` and `check` take. */
+const commandFlags = {
+	config: configArgument,
+	drift: Flag.Literals("drift", [
+		"strict",
+		"semantic",
+		"allow"
+	]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides every schema's drift"), Flag.optional),
+	onDrift: Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides the config's onDrift"), Flag.optional),
+	force: Flag.Boolean("force").pipe(Flag.withDefault(false), Flag.withDescription("Shorthand for --drift=allow")),
+	format: formatFlag,
+	ignoreVersionMismatch: ignoreVersionMismatchFlag
+};
+
+export { commandFlags, configArgument, formatFlag, ignoreVersionMismatchFlag };

package/commands/schema/index.js

@@ -0,0 +1,14 @@
+import { makeBuildCommand } from "./build.js";
+import { makeCheckCommand } from "./check.js";
+import { makeValidateCommand } from "./validate.js";
+import { Command } from "effect/cli";
+
+// src/commands/schema/index.ts
+/** `effected schema`: the group, closed over the process boundary it runs against. */
+const makeSchemaCommand = (deps) => Command.make("schema", {}).pipe(Command.withDescription("Build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts, and validate payloads against them"), Command.withSubcommands([
+	makeBuildCommand(deps),
+	makeCheckCommand(deps),
+	makeValidateCommand(deps)
+]));
+
+export { makeSchemaCommand };

package/commands/schema/validate.js

@@ -0,0 +1,58 @@
+import { ValidationFailedError } from "./errors.js";
+import { configFailures, resolveFormat, warnVersionMismatch } from "./execute.js";
+import { configArgument, formatFlag, ignoreVersionMismatchFlag } from "./flags.js";
+import { CliRuntime, Doc } from "@effected/cli-kit";
+import { Argument, Command, Flag } from "effect/cli";
+import { SchemaValidate, ValidateReport } from "@effected/engine/schema";
+import { Console, Effect, Option, Schema } from "effect";
+
+// src/commands/schema/validate.ts
+const findingLine = (finding) => {
+	const at = finding.location;
+	const where = at !== void 0 ? `${at.file}:${at.line}:${at.column}: ` : "  ";
+	const keyword = finding.keyword !== void 0 ? ` [${finding.keyword}]` : "";
+	return `${where}${finding.path === "" ? "(root)" : finding.path}: ${finding.message}${keyword}`;
+};
+const humanLines = (report) => report.valid ? [`valid ${report.payload} against ${report.source}`] : [...report.findings.map(findingLine), `${report.findings.length} finding(s): ${report.payload} does not conform to ${report.$ref}`];
+/** Run one `validate`. */
+const runValidate = Effect.fn("effected.schema.validate")(function* (input, deps) {
+	const format = yield* resolveFormat(input.format);
+	const report = yield* SchemaValidate.run({
+		payload: input.payload,
+		versionMismatch: input.ignoreVersionMismatch ? "warn" : "fail",
+		...Option.isSome(input.config) ? { config: input.config.value } : {},
+		...Option.isSome(input.schema) ? { schema: input.schema.value } : {}
+	}, {
+		...deps,
+		onProgress: (event) => event._tag === "Started" && event.versionMismatch !== void 0 ? warnVersionMismatch(event.versionMismatch) : Effect.void
+	}).pipe(Effect.catchTags({
+		...configFailures("validate payload.json lib/schemastore.config.ts", input.config),
+		VersionMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 2)),
+		PayloadError: (error) => Effect.fail(CliRuntime.reported(error, 2)),
+		SchemaResolutionError: (error) => Effect.fail(CliRuntime.reported(error, 2)),
+		MissingSchemaRefError: (error) => Effect.fail(CliRuntime.reported(error, 64))
+	}));
+	const lines = humanLines(report);
+	if (format === "json") {
+		yield* Console.log(JSON.stringify(Schema.encodeSync(ValidateReport.Json)(report)));
+		for (const line of lines) yield* Effect.logInfo(line);
+	} else yield* Doc.print([Doc.lines(lines.map((line, index) => Doc.text(line, report.valid ? "success" : index === lines.length - 1 ? "emphasis" : "error")), { wrap: false })]);
+	if (!report.valid) return yield* Effect.fail(CliRuntime.reported(new ValidationFailedError({
+		count: report.findings.length,
+		payload: report.payload,
+		schema: report.$ref
+	}), 1));
+});
+/**
+* `effected schema validate`: check a payload against a published schema document, named by `--schema` or the payload's
+* `$schema`: a file path, or an identity the config derives. No network is involved.
+*/
+const makeValidateCommand = (deps) => Command.make("validate", {
+	payload: Argument.String("payload").pipe(Argument.withDescription("Path to the JSON payload to validate")),
+	schema: Flag.String("schema").pipe(Flag.optional, Flag.withDescription("The document to validate against: a file path, or a $id/url a config schema derives; omitted, the payload's own $schema property")),
+	config: configArgument,
+	format: formatFlag,
+	ignoreVersionMismatch: ignoreVersionMismatchFlag
+}, (input) => runValidate(input, deps)).pipe(Command.withDescription("Validate a JSON payload against a published schema document, resolved by path or by the config's derived $id/url identities"));
+
+export { makeValidateCommand, runValidate };

package/index.d.ts

@@ -1,22 +1,123 @@
-import { Command } from "effect/cli";
+import "effect/cli";
+import { SchemaRunDeps } from "@effected/engine/schema";
+import "@effected/env";
+import { Schema } from "effect";
+declare const DriftError_base: Schema.Class<DriftError, Schema.TaggedStruct<"DriftError", {
+  readonly drifted: Schema.$Array<Schema.Struct<{
+    readonly $id: Schema.String;
+    readonly change: Schema.Literals<readonly ["none", "created", "annotations", "contract"]>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly nextVersion: Schema.optionalKey<Schema.String>;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
 /**
- * The `effected` command tree. This release carries no subcommand: `--version`
- * and `--help` come from the framework, and the audience flags are shared on
- * the root so every future subcommand accepts them.
+ * A published schema drifted under `onDrift: "error"`, so nothing was written. Exit `1`.
  *
  * @public
  */
-export declare const rootCommand: Command.Command<"effected", {
-  readonly audience: readonly import("@effected/env").AudienceKind[];
-  readonly human: readonly boolean[];
-  readonly agent: readonly boolean[];
-  readonly ci: readonly boolean[];
-}, {
-  readonly audience: readonly import("@effected/env").AudienceKind[];
-  readonly human: readonly boolean[];
-  readonly agent: readonly boolean[];
-  readonly ci: readonly boolean[];
-}, never, never>;
+export declare class DriftError extends DriftError_base {
+  get count(): number;
+  get message(): string;
+}
+declare const GateError_base: Schema.Class<GateError, Schema.TaggedStruct<"GateError", {
+  readonly count: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A schema failed the lint/validation gate, so nothing was written. Exit `1`.
+ *
+ * @public
+ */
+export declare class GateError extends GateError_base {
+  get message(): string;
+}
+declare const CatalogMergeError_base: Schema.Class<CatalogMergeError, Schema.TaggedStruct<"CatalogMergeError", {
+  readonly path: Schema.String;
+  readonly conflicts: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"url">;
+    readonly url: Schema.String;
+    readonly slices: Schema.$Array<Schema.String>;
+  }>, Schema.Struct<{
+    readonly kind: Schema.Literal<"name">;
+    readonly name: Schema.String;
+    readonly slices: Schema.$Array<Schema.String>;
+  }>]>>;
+  readonly invalid: Schema.$Array<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class CatalogMergeError extends CatalogMergeError_base {
+  get message(): string;
+}
+declare const StaleError_base: Schema.Class<StaleError, Schema.TaggedStruct<"StaleError", {
+  readonly count: Schema.Number;
+  readonly orphaned: Schema.optionalKey<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `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
+ */
+export declare class StaleError extends StaleError_base {
+  get message(): string;
+}
+declare const ValidationFailedError_base: Schema.Class<ValidationFailedError, Schema.TaggedStruct<"ValidationFailedError", {
+  readonly count: Schema.Number;
+  readonly payload: Schema.String;
+  readonly schema: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class ValidationFailedError extends ValidationFailedError_base {
+  get message(): string;
+}
+declare const NoConfigError_base: Schema.Class<NoConfigError, Schema.TaggedStruct<"NoConfigError", {
+  /** The file names looked for. */
+  readonly names: Schema.$Array<Schema.String>;
+  /** The directories walked, or the one explicit path checked. */
+  readonly searched: Schema.$Array<Schema.String>;
+  /** Whether `searched` is the one path the user named. */
+  readonly explicit: Schema.Boolean;
+  /** What follows `effected schema` in the example: the subcommand and its positionals, with a config path. */
+  readonly usage: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class NoConfigError extends NoConfigError_base {
+  get message(): string;
+}
+/**
+ * What `effected schema` is given by the process boundary, and the test seams: the engine's dependencies, less the
+ * progress callback the command supplies itself. `main` reads `cwd`, and nothing else reads the process.
+ *
+ * @public
+ */
+type SchemaCommandDeps = Omit<SchemaRunDeps, "onProgress">;
+/**
+ * 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
+ */
+export declare const makeRootCommand: any;
 /**
  * The `effected` command's version. The bundler replaces the exact expression
  * `process.env.__PACKAGE_VERSION__` with the package version at build time, so
@@ -25,4 +126,5 @@ export declare const rootCommand: Command.Command<"effected", {
  * @public
  */
 export declare const CLI_VERSION: string;
+export type { SchemaCommandDeps };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,5 @@
-import { rootCommand } from "./commands/root.js";
+import { makeRootCommand } from "./commands/root.js";
+import { CatalogMergeError, DriftError, GateError, NoConfigError, StaleError, ValidationFailedError } from "./commands/schema/errors.js";
 import { CLI_VERSION } from "./version.js";
 
-export { CLI_VERSION, rootCommand };
+export { CLI_VERSION, CatalogMergeError, DriftError, GateError, NoConfigError, StaleError, ValidationFailedError, makeRootCommand };

package/main.d.ts

@@ -1,5 +1,14 @@
 import { Distribution } from "@effected/kit";
 import { Layer } from "effect";
+import { SchemaRunDeps } from "@effected/engine/schema";
+import "@effected/env";
+/**
+ * What `effected schema` is given by the process boundary, and the test seams: the engine's dependencies, less the
+ * progress callback the command supplies itself. `main` reads `cwd`, and nothing else reads the process.
+ *
+ * @public
+ */
+type SchemaCommandDeps = Omit<SchemaRunDeps, "onProgress">;
 /**
  * Options a carrier's bin shim passes to {@link main}. `distribution` names
  * the package the `effected` bin was installed through; omitted for a direct
@@ -10,6 +19,19 @@ import { Layer } from "effect";
 export interface MainOptions {
   readonly distribution?: Distribution;
 }
+/**
+ * How `CliRuntime.main` runs the command: exit `3` for a typed error that carries no code of its own, the infrastructure
+ * tier, and this module as the program's own, so the failure report's span trail keeps the command's spans when it is
+ * installed under `node_modules/@effected/` and leaves out the kit's.
+ *
+ * @public
+ */
+export declare const mainOptions: {
+  readonly exitCode: 3;
+  readonly env: {
+    readonly appModule: string;
+  };
+};
 /**
  * The `effected` program under `CliRuntime.main`, over `platform`: what
  * {@link main} runs with the Node services, and what a test runs over a test
@@ -17,7 +39,7 @@ export interface MainOptions {
  *
  * @public
  */
-export declare const run: <RP, EP>(options: MainOptions, platform: Layer.Layer<RP, EP>) => import("effect/Effect").Effect<void, Error, Exclude<import("effect/process/ChildProcessSpawner").ChildProcessSpawner, RP> | Exclude<import("effect/FileSystem").FileSystem, RP> | Exclude<import("effect/Path").Path, RP> | Exclude<import("effect/Stdio").Stdio, RP> | Exclude<import("effect/Stdio").Stdio, RP> | Exclude<import("effect/Terminal").Terminal, RP>>;
+export declare const run: <RP, EP>(options: MainOptions, deps: SchemaCommandDeps, platform: Layer.Layer<RP, EP>) => import("effect/Effect").Effect<void, Error, Exclude<import("effect/process/ChildProcessSpawner").ChildProcessSpawner, RP> | Exclude<import("effect/FileSystem").FileSystem, RP> | Exclude<import("effect/Path").Path, RP> | Exclude<import("effect/Stdio").Stdio, RP> | Exclude<import("effect/Stdio").Stdio, RP> | Exclude<import("effect/Terminal").Terminal, RP>>;
 /**
  * Run the `effected` command. Owns the process: installs the runtime teardown
  * and sets the exit code.
@@ -25,4 +47,5 @@ export declare const run: <RP, EP>(options: MainOptions, platform: Layer.Layer<R
  * @public
  */
 export declare const main: (options?: MainOptions) => void;
+export type { SchemaCommandDeps };
 //# sourceMappingURL=main.d.ts.map

package/main.js

@@ -1,6 +1,6 @@
-import { rootCommand } from "./commands/root.js";
+import { makeRootCommand } from "./commands/root.js";
 import { CLI_VERSION } from "./version.js";
-import { CliAudience, CliRuntime } from "@effected/cli-kit";
+import { CliAudience, CliLogger, CliRuntime } from "@effected/cli-kit";
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 
@@ -17,20 +17,35 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 */
 const versionFormatter = { formatVersion: (name, version) => `${name} ${version}` };
 /**
+* How `CliRuntime.main` runs the command: exit `3` for a typed error that carries no code of its own, the infrastructure
+* tier, and this module as the program's own, so the failure report's span trail keeps the command's spans when it is
+* installed under `node_modules/@effected/` and leaves out the kit's.
+*
+* @public
+*/
+const mainOptions = {
+	exitCode: 3,
+	env: { appModule: import.meta.url }
+};
+/** stdout is the report and nothing else, so every log level goes to stderr. */
+const logger = CliLogger.layer({ stderrFrom: "All" });
+/**
 * The `effected` program under `CliRuntime.main`, over `platform`: what
 * {@link main} runs with the Node services, and what a test runs over a test
 * environment.
 *
 * @public
 */
-const run = (options, platform) => CliRuntime.main(CliAudience.run(rootCommand, { version: CLI_VERSION }), {
+const run = (options, deps, platform) => CliRuntime.main(CliAudience.run(makeRootCommand(deps), { version: CLI_VERSION }), {
 	platform,
+	logger,
 	distribution: options.distribution ?? null,
-	exitCode: 3,
+	exitCode: mainOptions.exitCode,
 	helpOnUsageError: "stderr",
 	env: {
-		appModule: import.meta.url,
-		formatter: versionFormatter
+		...mainOptions.env,
+		formatter: versionFormatter,
+		helpFlags: { inheritedFlags: "summary" }
 	}
 });
 /**
@@ -40,7 +55,7 @@ const run = (options, platform) => CliRuntime.main(CliAudience.run(rootCommand,
 * @public
 */
 const main = (options = {}) => {
-	NodeRuntime.runMain(run(options, NodeServices.layer));
+	NodeRuntime.runMain(run(options, { cwd: process.cwd() }, NodeServices.layer));
 };
 
-export { main, run };
+export { main, mainOptions, run };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"private": false,
 	"description": "The effected command: the tool's command tree on the kit's front-end runtime",
 	"keywords": [
@@ -43,12 +43,15 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "~4.1.2",
-		"@effected/cli-kit": "^0.26.0",
-		"@effected/env": "^0.10.0",
-		"@effected/glob": "^0.18.0",
-		"@effected/kit": "^0.12.0",
-		"@effected/walker": "^0.25.0",
-		"effect": "~4.1.2"
+		"@effected/cli-kit": "^0.27.0",
+		"@effected/engine": "0.13.0",
+		"@effected/env": "^0.11.0",
+		"@effected/glob": "^0.19.0",
+		"@effected/kit": "^0.13.0",
+		"@effected/walker": "^0.25.1",
+		"effect": "~4.1.2",
+		"ink": "^8.0.0",
+		"react": "^19.3.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/render/DiffDoc.js

@@ -0,0 +1,51 @@
+import { Doc } from "@effected/cli-kit";
+
+// src/render/DiffDoc.ts
+/**
+* How many diff rows `DiffDoc.render` shows per schema before it cuts the rest with a "… N more lines" tail: a
+* screenful of context that keeps a many-schema report readable.
+*
+* @public
+*/
+const DEFAULT_MAX_DIFF_LINES = 40;
+const expandTabs = (text) => text.replaceAll("	", "  ");
+/**
+* A schema's line diff as a `Doc`, in git's shape: an `@@ path @@` header, context lines as they are, removes in the
+* `error` token and adds in the `success` token.
+*
+* @remarks
+* Each tab in a line's text is expanded to two spaces, so a tab-indented document keeps its shape. Every line's text
+* goes into the document as a `Doc.text` run, which is data: the renderers remove escape and control characters from it
+* and never read it as markup, so a diff of untrusted text cannot repaint the terminal.
+* A document with more than one hunk separates them with a muted `@@ -a,b +c,d @@` range row. The cap counts every
+* row after the header (diff lines, range rows and `` markers) and the tail names exactly
+* how many were cut. Nothing here loads Ink or React.
+*
+* @public
+*/
+var DiffDoc = class {
+	constructor() {}
+	/**
+	* @param path - the schema file the diff is for, shown in the header
+	* @param diff - the diff
+	* @param options - `maxLines`, the cap on shown rows
+	*/
+	static render(path, diff, options) {
+		const cap = Math.max(0, Math.floor(options?.maxLines ?? 40));
+		const rows = [];
+		diff.hunks.forEach((hunk) => {
+			if (diff.hunks.length > 1) rows.push(Doc.text(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`, "muted"));
+			for (const line of hunk.lines) {
+				const text = expandTabs(line.text);
+				rows.push(line.kind === "add" ? Doc.text(`+${text}`, "success") : line.kind === "remove" ? Doc.text(`-${text}`, "error") : Doc.text(` ${text}`));
+				if (line.noNewline === true) rows.push(Doc.text("\", "muted"));
+			}
+		});
+		const hidden = rows.length - cap;
+		const shown = hidden > 0 ? rows.slice(0, cap) : rows;
+		if (hidden > 0) shown.push(Doc.text(`… ${hidden} more ${hidden === 1 ? "line" : "lines"}`, "muted"));
+		return Doc.lines([Doc.text(`@@ ${path} @@`, "accent"), ...shown], { wrap: false });
+	}
+};
+
+export { DiffDoc };

package/version.js

@@ -6,6 +6,6 @@
 *
 * @public
 */
-const CLI_VERSION = "0.26.0";
+const CLI_VERSION = "0.27.0";
 
 export { CLI_VERSION };