@effected/schemastore-cli 0.9.0

package/ConfigLoader.js

@@ -0,0 +1,160 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { isSchemastoreConfig } from "@effected/schemastore";
+import { createJiti } from "jiti";
+
+//#region src/ConfigLoader.ts
+/**
+* No `schemastore.config.*` was found — by upward discovery from the working
+* directory, or at the explicit path handed to `--config`.
+*
+* @public
+*/
+var ConfigNotFoundError = class extends Schema.TaggedError()("ConfigNotFoundError", { 
+/** The directories walked (discovery) or the one explicit path checked. */
+searched: Schema.Array(Schema.String) }) {
+	get message() {
+		return `No schemastore config found. Searched for ${ConfigLoader.CONFIG_NAMES.join(", ")} in: ${this.searched.join(", ")}`;
+	}
+};
+/**
+* The config file exists but could not be turned into a `SchemastoreConfig`:
+* the module threw on import, its default export is not a `defineConfig(...)`
+* value, a `schemas` element is not `SchemaTarget`-shaped, or two outputs
+* resolve to one absolute path.
+*
+* @public
+*/
+var ConfigLoadError = class extends Schema.TaggedError()("ConfigLoadError", {
+	path: Schema.String,
+	reason: Schema.String
+}) {
+	get message() {
+		return `Failed to load schemastore config ${this.path}: ${this.reason}`;
+	}
+};
+const jitiImport = (path) => createJiti(path, { interopDefault: true }).import(path);
+const describeCause = (cause) => cause instanceof Error ? cause.stack ?? cause.message : String(cause);
+const describeMalformedTarget = (schemas) => {
+	if (!Array.isArray(schemas)) return "schemas is not an array";
+	for (const [index, target] of schemas.entries()) {
+		const record = typeof target === "object" && target !== null ? target : void 0;
+		if (!(record !== void 0 && Schema.isSchema(record.schema) && typeof record.$id === "string" && typeof record.path === "string" && typeof record.published === "boolean")) return `schemas[${index}] is not a SchemaTarget (missing schema/$id/path/published)`;
+	}
+};
+const describeDuplicatePath = (config) => {
+	const seen = /* @__PURE__ */ new Set();
+	const paths = [...config.schemas.map((target) => target.path), ...config.catalog.map((c) => c.config.path)];
+	for (const p of paths) {
+		if (seen.has(p)) return `output path "${p}" is declared twice after resolution`;
+		seen.add(p);
+	}
+};
+/**
+* Finds and loads a `schemastore.config.*` file.
+*
+* @remarks
+* `discover` walks upward from a start directory checking
+* {@link ConfigLoader.CONFIG_NAMES} in order at each level, so the nearest
+* directory wins and, within one directory, `.ts` beats `.mjs`. `load` either
+* takes the explicit path or discovers one, imports it, checks the default
+* export is a `defineConfig(...)` value, and resolves relative paths against
+* the config's directory.
+*
+* @public
+*/
+var ConfigLoader = class ConfigLoader {
+	constructor() {}
+	/** The file names discovery looks for, in preference order. */
+	static CONFIG_NAMES = [
+		"schemastore.config.ts",
+		"schemastore.config.mts",
+		"schemastore.config.js",
+		"schemastore.config.mjs"
+	];
+	/**
+	* Walk upward from `start` until a config file is found; fails with the
+	* list of directories searched when none is.
+	*/
+	static discover = Effect.fn("ConfigLoader.discover")(function* (start) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const searched = [];
+		let dir = path.resolve(start);
+		for (;;) {
+			searched.push(dir);
+			for (const name of ConfigLoader.CONFIG_NAMES) {
+				const candidate = path.join(dir, name);
+				if (yield* fs.exists(candidate).pipe(Effect.orElseSucceed(() => false))) return candidate;
+			}
+			const parent = path.dirname(dir);
+			if (parent === dir) return yield* Effect.fail(new ConfigNotFoundError({ searched }));
+			dir = parent;
+		}
+	});
+	/**
+	* Resolve every relative `path` in the config (schema targets and catalog
+	* entries) against `directory`; absolute paths are left alone. The result
+	* keeps the `defineConfig` brand.
+	*/
+	static resolvePaths = Effect.fn("ConfigLoader.resolvePaths")(function* (config, directory) {
+		const path = yield* Path.Path;
+		const absolute = (p) => path.isAbsolute(p) ? p : path.resolve(directory, p);
+		return {
+			...config,
+			schemas: config.schemas.map((target) => ({
+				...target,
+				path: absolute(target.path)
+			})),
+			catalog: config.catalog.map((c) => ({
+				...c,
+				config: {
+					...c.config,
+					path: absolute(c.config.path)
+				}
+			}))
+		};
+	});
+	/** Locate, import and validate the config; see {@link ConfigLoadOptions}. */
+	static load = Effect.fn("ConfigLoader.load")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const importModule = options.importModule ?? jitiImport;
+		let configPath;
+		if (options.explicit !== void 0) {
+			configPath = path.resolve(options.cwd, options.explicit);
+			if (!(yield* fs.exists(configPath).pipe(Effect.orElseSucceed(() => false)))) return yield* Effect.fail(new ConfigNotFoundError({ searched: [configPath] }));
+		} else configPath = yield* ConfigLoader.discover(options.cwd);
+		const module = yield* Effect.tryPromise({
+			try: () => importModule(configPath),
+			catch: (cause) => new ConfigLoadError({
+				path: configPath,
+				reason: describeCause(cause)
+			})
+		});
+		const exported = module?.default ?? module;
+		if (!isSchemastoreConfig(exported)) return yield* Effect.fail(new ConfigLoadError({
+			path: configPath,
+			reason: "default export is not a defineConfig(...) value from @effected/schemastore"
+		}));
+		const malformed = describeMalformedTarget(exported.schemas);
+		if (malformed !== void 0) return yield* Effect.fail(new ConfigLoadError({
+			path: configPath,
+			reason: malformed
+		}));
+		const directory = path.dirname(configPath);
+		const config = yield* ConfigLoader.resolvePaths(exported, directory);
+		const duplicate = describeDuplicatePath(config);
+		if (duplicate !== void 0) return yield* Effect.fail(new ConfigLoadError({
+			path: configPath,
+			reason: duplicate
+		}));
+		return {
+			path: configPath,
+			directory,
+			config
+		};
+	});
+};
+
+//#endregion
+export { ConfigLoadError, ConfigLoader, ConfigNotFoundError };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @effected/schemastore-cli
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fschemastore-cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/schemastore-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 `schemastore` command: build and check SchemaStore-shaped JSON Schema documents from a `schemastore.config.ts`. It is the command-line companion to [`@effected/schemastore`](https://www.npmjs.com/package/@effected/schemastore), which owns the pipeline; this package ships the plumbing every consumer used to write by hand — flag parsing, the contract gate, the drift test — once, as a `bin`.
+
+It is not a library: nothing is importable from it. Every type a config file needs comes from `@effected/schemastore`, which the CLI declares as a peer so your config and the pipeline share one `effect` and one `@effected/schemastore` instance.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 prerelease. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **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).
+
+## Install
+
+`@effected/schemastore` and `@effected/schemastore-cli` release together at one version; install them at the same version.
+
+```bash
+npm install --save-dev @effected/schemastore-cli @effected/schemastore effect
+```
+
+```bash
+pnpm add -D @effected/schemastore-cli @effected/schemastore effect
+```
+
+## Configure
+
+Create `schemastore.config.ts` (also `.mts`, `.js`, `.mjs`). The CLI finds it by walking upward from the working directory, or takes its path as a positional argument. Relative `path` values resolve against the config file's directory.
+
+```ts
+import { defineConfig, SchemaTarget } from "@effected/schemastore";
+import { ReleaseOutput, SCHEMA_URL } from "./src/schema/release-output.js";
+
+export default defineConfig({
+ schemas: [
+  SchemaTarget.make({
+   schema: ReleaseOutput,
+   $id: SCHEMA_URL,
+   name: "silk-release-action",
+   version: "5.0.0",
+   path: "schemas/silk-release-action-5.0.0.json",
+   published: true,
+   jsonSchema: { onExcessProperty: "error" },
+  }),
+ ],
+ catalog: [
+  {
+   name: "silk-release-action",
+   description: "Structured output of the silk-release GitHub Action",
+   fileMatch: ["silk-release-output.json"],
+   baseUrl: "https://raw.githubusercontent.com/savvy-web/silk-release-action/main/schemas",
+   path: "schemas/catalog-entry.json",
+  },
+ ],
+ drift: { policy: "semantic", onDrift: "error" },
+});
+```
+
+- `schemas` — at least one `SchemaTarget`; `published` (default `false`) marks a version other people depend on.
+- `catalog` — zero or more SchemaStore catalog entries; `versions` is derived from every versioned schema of that name. The entry's `url` and each `versions` value are derived as `<baseUrl>/<name>-<version>.json`, so every schema's `path` must sit directly under the directory `baseUrl` names and its `$id` must be that exact URL — the CLI does not yet cross-check them.
+- `drift` — the default policy for published schemas (`strict`, `semantic` or `allow`) and what drift means (`error` or `warn`). Defaults to `{ policy: "semantic", onDrift: "error" }`.
+
+Then add two scripts:
+
+```json
+{
+ "scripts": {
+  "schema:build": "schemastore build",
+  "schema:check": "schemastore check"
+ }
+}
+```
+
+## Commands
+
+```text
+schemastore build [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
+schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
+```
+
+- `build` generates every schema, runs the gates (structural lints and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so unchanged files are untouched — along with each catalog entry.
+- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits under the same conditions. It is the CI gate, so it also fails (exit `1`) whenever a build would write anything — a committed schema or catalog entry that differs from what the config generates, or is missing, is stale; run `schemastore build` and commit the result.
+- `--drift` and `--on-drift` override the config's `drift` block for one run; `--force` is sugar for `--drift=allow`.
+- `--format=json` emits one JSON document on stdout (config path, per-schema outcome, per-catalog-entry outcome, effective drift policy and its source); human text moves to stderr.
+- When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown summary table.
+
+An unpublished schema is never drift: a contract change at a pinned but unpublished version rewrites the file in place.
+
+## Exit codes
+
+| code | meaning |
+| ---- | -------------------------------------------------------------------------- |
+| 0 | success, including drift under `onDrift: warn` |
+| 1 | drift under `onDrift: error`, a gate failure, or — for `check` — any document `build` would write |
+| 2 | config not found, failed to load, or failed `SchemastoreConfig` validation |
+| 3 | infrastructure failure |
+| 64 | usage error |
+
+## License
+
+MIT

package/Report.js

@@ -0,0 +1,140 @@
+//#region src/Report.ts
+const findingLine = (finding) => `  ${finding.label} at "${finding.path}": ${finding.message}`;
+const blockingCount = (findings) => findings.filter((finding) => finding.severity === "warning").length;
+const suggestionClause = (schema) => schema.nextVersion !== void 0 && schema.nextVersion !== schema.version ? ` → suggest ${schema.nextVersion}` : "";
+const publishedClause = (schema) => schema.version !== void 0 ? ` at published ${schema.version}` : "";
+const schemaLines = (schema, report) => {
+	switch (schema.outcome) {
+		case "written": return [`written (${schema.change}) ${schema.path}`];
+		case "unchanged": return [`unchanged ${schema.path}`];
+		case "would-write": return [`would write (${schema.change}) ${schema.path}`];
+		case "drift": return [`DRIFT ${schema.change}${publishedClause(schema)}${suggestionClause(schema)} — ${schema.path}`];
+		case "held": return [`held (${report.gateFailed ? "gate failed elsewhere" : "drift elsewhere"}) ${schema.path}`];
+		case "gate-failed": return [`GATE FAILED ${schema.path} (${blockingCount(schema.findings)} blocking finding(s))`, ...schema.findings.map(findingLine)];
+		default: return schema.outcome;
+	}
+};
+const catalogLine = (entry) => {
+	switch (entry.outcome) {
+		case "written": return `written catalog ${entry.path}`;
+		case "unchanged": return `unchanged catalog ${entry.path}`;
+		case "would-write": return `would write catalog ${entry.path}`;
+		case "held": return `held catalog ${entry.path}`;
+		default: return entry.outcome;
+	}
+};
+const summaryLine = (report) => {
+	const written = report.schemas.filter((schema) => schema.outcome === "written").length;
+	const unchanged = report.schemas.filter((schema) => schema.outcome === "unchanged").length;
+	const drift = report.schemas.filter((schema) => schema.verdict === "drift").length;
+	const gateFailed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
+	return `${report.schemas.length} schema(s): ${written} written, ${unchanged} unchanged, ${drift} drift, ${gateFailed} gate failed — drift policy ${report.drift.policy}/${report.drift.onDrift} (${report.drift.source})`;
+};
+const warningLine = (schema, report) => `warning: DRIFT ${schema.change}${publishedClause(schema)} ${report.mode === "build" ? "written" : "would write"} under --on-drift=warn — ${schema.path}`;
+const tableRow = (columns) => `| ${columns.join(" | ")} |`;
+/**
+* Renders a {@link RunReport} for a terminal, a JSON consumer or a GitHub
+* step summary.
+*
+* @public
+*/
+var Report = class {
+	constructor() {}
+	/** stdout lines. */
+	static human(report) {
+		const lines = [];
+		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
+		for (const entry of report.catalog) lines.push(catalogLine(entry));
+		lines.push(summaryLine(report));
+		return lines;
+	}
+	/**
+	* stderr lines: one per drift written (or, under `check`, would be written)
+	* under `onDrift: "warn"`. Empty when the gate failed — nothing was (or
+	* would be) written, so there is no drift to warn about.
+	*/
+	static warnings(report) {
+		if (report.drift.onDrift !== "warn" || report.gateFailed) return [];
+		return report.schemas.filter((schema) => schema.verdict === "drift").map((schema) => warningLine(schema, report));
+	}
+	/** One JSON document, stable key order. */
+	static json(report) {
+		const doc = {
+			mode: report.mode,
+			configPath: report.configPath,
+			drift: {
+				policy: report.drift.policy,
+				onDrift: report.drift.onDrift,
+				source: report.drift.source
+			},
+			schemas: report.schemas.map((schema) => ({
+				$id: schema.$id,
+				path: schema.path,
+				...schema.name !== void 0 ? { name: schema.name } : {},
+				...schema.version !== void 0 ? { version: schema.version } : {},
+				published: schema.published,
+				change: schema.change,
+				verdict: schema.verdict,
+				outcome: schema.outcome,
+				...schema.nextVersion !== void 0 ? { nextVersion: schema.nextVersion } : {},
+				findings: schema.findings.map((finding) => ({
+					source: finding.source,
+					severity: finding.severity,
+					...finding.check !== void 0 ? { check: finding.check } : {},
+					path: finding.path,
+					message: finding.message
+				}))
+			})),
+			catalog: report.catalog.map((entry) => ({
+				name: entry.name,
+				path: entry.path,
+				outcome: entry.outcome
+			})),
+			drifted: report.drifted,
+			gateFailed: report.gateFailed,
+			wrote: report.wrote
+		};
+		return JSON.stringify(doc, null, "	");
+	}
+	/** The step-summary table; ends with a newline so a later append starts on its own line. */
+	static markdown(report) {
+		const lines = [`### schemastore ${report.mode}`, ""];
+		lines.push(tableRow([
+			"schema",
+			"version",
+			"published",
+			"change",
+			"outcome"
+		]), tableRow([
+			"---",
+			"---",
+			"---",
+			"---",
+			"---"
+		]));
+		for (const schema of report.schemas) lines.push(tableRow([
+			schema.name ?? schema.$id,
+			schema.version ?? "",
+			schema.published ? "yes" : "no",
+			schema.change,
+			schema.outcome
+		]));
+		if (report.catalog.length > 0) {
+			lines.push("", tableRow(["catalog", "outcome"]), tableRow(["---", "---"]));
+			for (const entry of report.catalog) lines.push(tableRow([entry.name, entry.outcome]));
+		}
+		lines.push("");
+		if (report.gateFailed) {
+			const failed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
+			lines.push(`**Gate:** ${failed} schema(s) failed`);
+		} else if (report.drifted) {
+			const drifted = report.schemas.filter((schema) => schema.verdict === "drift").length;
+			lines.push(`**Drift:** ${drifted} schema(s) drifted under ${report.drift.policy}/${report.drift.onDrift}`);
+		} else lines.push("**Drift:** none");
+		lines.push("");
+		return lines.join("\n");
+	}
+};
+
+//#endregion
+export { Report };

package/Runner.js

@@ -0,0 +1,125 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { CanonicalJson, CatalogEntry, DriftPolicy, SchemaPipeline, SchemaVersioning } from "@effected/schemastore";
+
+//#region src/Runner.ts
+const pipelineOptions = { contractChanges: "allow" };
+const catalogText = (target) => CanonicalJson.serialize(Schema.encodeSync(CatalogEntry)(target.entry));
+const jsonEqual = (a, b) => {
+	if (a === b) return true;
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	const left = a;
+	const right = b;
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((k) => Object.hasOwn(right, k) && jsonEqual(left[k], right[k]));
+};
+const sameJson = (existing, text) => {
+	try {
+		return jsonEqual(JSON.parse(existing), JSON.parse(text));
+	} catch {
+		return false;
+	}
+};
+/**
+* The shared `build` / `check` walk: classify every schema through
+* {@link DriftPolicy} over `SchemaPipeline.check`, then write through
+* `SchemaPipeline.run` only when nothing is refused.
+*
+* @remarks
+* A build writes NOTHING when any schema fails its gate, or when any schema
+* drifts under `onDrift: "error"` — a partial write would leave a
+* repository half-bumped. Every otherwise-writable schema then reports
+* `held`, so a reader sees why a clean schema was not written — in both
+* modes, since `check` reports what `build` would do under the same
+* flags. Both modes share one `SchemaFile`; the single `writing`
+* predicate (`mode === "build" && !refused`) gates every write, schemas
+* and catalog entries alike. Under `onDrift: "warn"` drifting schemas are
+* written and keep their `"drift"` verdict for the renderer to shout
+* about.
+*
+* Catalog entries follow the schemas: serialized canonically, compared by
+* parsed content against the file on disk, written only when different and
+* only when the run is writing.
+*
+* @public
+*/
+var Runner = class {
+	constructor() {}
+	static run = Effect.fn("Runner.run")(function* (config, options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const checks = yield* SchemaPipeline.check(config.schemas, pipelineOptions);
+		const gateFailed = checks.some((check) => check.blocked);
+		const classified = checks.map((check, i) => {
+			const target = config.schemas[i];
+			return {
+				target,
+				check,
+				verdict: DriftPolicy.classify({
+					published: target.published,
+					change: check.change
+				}, options.drift.policy),
+				nextVersion: target.version !== void 0 && check.change === "contract" && SchemaVersioning.isPinned(target.version) ? SchemaVersioning.next(target.version, "contract") : void 0
+			};
+		});
+		const drifted = classified.some((entry) => entry.verdict === "drift");
+		const refused = gateFailed || drifted && options.drift.onDrift === "error";
+		const writing = options.mode === "build" && !refused;
+		const written = writing ? yield* SchemaPipeline.run(config.schemas, pipelineOptions).pipe(Effect.catchTags({
+			SchemaGateError: (error) => Effect.die(error),
+			SchemaContractChangeError: (error) => Effect.die(error)
+		})) : void 0;
+		const schemas = classified.map(({ target, check, verdict, nextVersion }, i) => {
+			const outcome = check.blocked ? "gate-failed" : written !== void 0 ? written[i].outcome : verdict === "drift" ? "drift" : refused && check.wouldWrite ? "held" : check.wouldWrite ? "would-write" : "unchanged";
+			return {
+				$id: target.$id,
+				path: target.path,
+				published: target.published,
+				change: check.change,
+				verdict,
+				outcome,
+				findings: check.findings,
+				...target.name !== void 0 ? { name: target.name } : {},
+				...target.version !== void 0 ? { version: target.version } : {},
+				...nextVersion !== void 0 ? { nextVersion } : {}
+			};
+		});
+		const catalog = [];
+		for (const entry of config.catalog) {
+			const { name, path: file } = entry.config;
+			const text = yield* catalogText(entry);
+			if ((yield* fs.exists(file)) && sameJson(yield* fs.readFileString(file), text)) catalog.push({
+				name,
+				path: file,
+				outcome: "unchanged"
+			});
+			else if (!writing) catalog.push({
+				name,
+				path: file,
+				outcome: refused ? "held" : "would-write"
+			});
+			else {
+				yield* fs.makeDirectory(path.dirname(file), { recursive: true });
+				yield* fs.writeFileString(file, text);
+				catalog.push({
+					name,
+					path: file,
+					outcome: "written"
+				});
+			}
+		}
+		return {
+			mode: options.mode,
+			configPath: options.configPath,
+			drift: options.drift,
+			schemas,
+			catalog,
+			drifted,
+			gateFailed,
+			wrote: schemas.some((s) => s.outcome === "written") || catalog.some((c) => c.outcome === "written")
+		};
+	});
+};
+
+//#endregion
+export { Runner };

package/StepSummary.js

@@ -0,0 +1,31 @@
+import { Config, Effect, FileSystem, Option } from "effect";
+
+//#region src/StepSummary.ts
+const summaryTarget = Config.String("GITHUB_STEP_SUMMARY").pipe(Config.option);
+/**
+* Appends a rendered {@link Report.markdown} document to `GITHUB_STEP_SUMMARY`.
+*
+* @public
+*/
+var StepSummary = class {
+	constructor() {}
+	/**
+	* `true` when appended; `false` when `GITHUB_STEP_SUMMARY` is unset or
+	* empty, or when the read/write failed — a failure is logged at warning
+	* and never fails the run it is reporting on.
+	*/
+	static append = Effect.fn("StepSummary.append")(function* (markdown) {
+		const fs = yield* FileSystem.FileSystem;
+		return yield* Effect.gen(function* () {
+			const target = yield* summaryTarget;
+			if (Option.isNone(target)) return false;
+			const existing = (yield* fs.exists(target.value)) ? yield* fs.readFileString(target.value) : "";
+			const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+			yield* fs.writeFileString(target.value, existing + separator + markdown);
+			return true;
+		}).pipe(Effect.catch((error) => Effect.logWarning("StepSummary.append: could not update GITHUB_STEP_SUMMARY", error).pipe(Effect.as(false))));
+	});
+};
+
+//#endregion
+export { StepSummary };

package/bin/schemastore.js

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

package/cli/commands/build.js

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

package/cli/commands/check.js

@@ -0,0 +1,16 @@
+import { execute } from "../execute.js";
+import { commandFlags } from "../flags.js";
+import { Command } from "effect/unstable/cli";
+
+//#region src/cli/commands/check.ts
+/**
+* `schemastore check`: the same walk as `build`, reported and never written.
+* The CI drift gate: it also fails when the committed documents are stale,
+* i.e. whenever `build` would write anything.
+*
+* @public
+*/
+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, and write nothing"));
+
+//#endregion
+export { makeCheckCommand };

package/cli/execute.js

@@ -0,0 +1,102 @@
+import { ConfigLoader } from "../ConfigLoader.js";
+import { Report } from "../Report.js";
+import { Runner } from "../Runner.js";
+import { StepSummary } from "../StepSummary.js";
+import { CliRuntime } from "@effected/cli";
+import { Console, Effect, Option, Schema } from "effect";
+import { SchemaFile, SchemaValidator } from "@effected/schemastore";
+
+//#region src/cli/execute.ts
+/**
+* A published schema drifted under `onDrift: "error"`, so nothing was
+* written. Exit `1`.
+*
+* @public
+*/
+var DriftError = class extends Schema.TaggedError()("DriftError", { count: Schema.Number }) {
+	get message() {
+		return `${this.count} published schema(s) drifted; nothing was written. Bump 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.`;
+	}
+};
+/**
+* `check` found committed documents that differ from what the config
+* generates (or are missing), so a `build` would write. `check` is the CI
+* drift gate, so a stale tree fails it. Exit `1`.
+*
+* @public
+*/
+var StaleError = class extends Schema.TaggedError()("StaleError", { count: Schema.Number }) {
+	get message() {
+		return `${this.count} document(s) are stale; run \`schemastore build\` and commit the result.`;
+	}
+};
+const reported = (error, exitCode) => CliRuntime.reported(error, exitCode);
+const effectiveDrift = (configured, input) => {
+	return {
+		policy: input.force ? "allow" : Option.getOrElse(input.drift, () => configured.policy),
+		onDrift: Option.getOrElse(input.onDrift, () => configured.onDrift),
+		source: input.force || Option.isSome(input.drift) || Option.isSome(input.onDrift) ? "flag" : "config"
+	};
+};
+const emit = Effect.fn("schemastore.emit")(function* (report, format) {
+	if (format === "json") {
+		yield* Console.log(Report.json(report));
+		for (const line of Report.human(report)) yield* Effect.logInfo(line);
+	} else for (const line of Report.human(report)) yield* Console.log(line);
+	for (const line of Report.warnings(report)) yield* Effect.logWarning(line);
+});
+/**
+* Run one `build` or `check`.
+*
+* @remarks
+* Loads the config, applies the flag overrides, runs the shared walk,
+* emits the report in the requested format, appends the step summary, and
+* fails typed — `GateError`, then `DriftError`, then (for `check` only)
+* `StaleError`, each carrying exit `1` — when the report says the run
+* refused to write or, under `check`, that a build would write. `SchemaFile` is built
+* here over the environment's `FileSystem`; the validator is
+* `deps.validator` or the real engine.
+*
+* @public
+*/
+const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
+	const loaded = yield* ConfigLoader.load({
+		cwd: deps.cwd,
+		...Option.isSome(input.config) ? { explicit: input.config.value } : {},
+		...deps.importModule !== void 0 ? { importModule: deps.importModule } : {}
+	});
+	const drift = effectiveDrift(loaded.config.drift, input);
+	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.`);
+	const report = yield* Runner.run(loaded.config, {
+		mode,
+		configPath: loaded.path,
+		drift
+	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? SchemaValidator.layer));
+	yield* emit(report, input.format);
+	yield* StepSummary.append(Report.markdown(report));
+	if (report.gateFailed) {
+		const count = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
+		return yield* Effect.fail(reported(new GateError({ count }), 1));
+	}
+	if (report.drifted && drift.onDrift === "error") {
+		const count = report.schemas.filter((schema) => schema.verdict === "drift").length;
+		return yield* Effect.fail(reported(new DriftError({ count }), 1));
+	}
+	if (mode === "check") {
+		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + report.catalog.filter((entry) => entry.outcome === "would-write").length;
+		if (count > 0) return yield* Effect.fail(reported(new StaleError({ count }), 1));
+	}
+});
+
+//#endregion
+export { DriftError, GateError, StaleError, execute };

package/cli/flags.js

@@ -0,0 +1,53 @@
+import { Argument, Flag } from "effect/unstable/cli";
+
+//#region src/cli/flags.ts
+/**
+* The optional positional config path; omitted, the config is discovered
+* upward from the working directory.
+*
+* @public
+*/
+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);
+/**
+* `--drift`: the tolerance for published schemas, overriding the config.
+*
+* @public
+*/
+const driftFlag = Flag.Literals("drift", [
+	"strict",
+	"semantic",
+	"allow"
+]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides the config's drift.policy"), Flag.optional);
+/**
+* `--on-drift`: what drift does, overriding the config.
+*
+* @public
+*/
+const onDriftFlag = Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides drift.onDrift"), Flag.optional);
+/**
+* `--force`: shorthand for `--drift=allow`.
+*
+* @public
+*/
+const forceFlag = Flag.Boolean("force").pipe(Flag.withDefault(false), Flag.withDescription("Shorthand for --drift=allow"));
+/**
+* `--format`: `human` (default) or `json`.
+*
+* @public
+*/
+const formatFlag = Flag.Literals("format", ["human", "json"]).pipe(Flag.withDefault("human"), Flag.withDescription("Output format; json writes one document to stdout and moves human text to stderr"));
+/**
+* The config both commands take.
+*
+* @public
+*/
+const commandFlags = {
+	config: configArgument,
+	drift: driftFlag,
+	onDrift: onDriftFlag,
+	force: forceFlag,
+	format: formatFlag
+};
+
+//#endregion
+export { commandFlags, configArgument, driftFlag, forceFlag, formatFlag, onDriftFlag };

package/cli/program.js

@@ -0,0 +1,42 @@
+import { ConfigLoadError } from "../ConfigLoader.js";
+import { makeCommands } from "./root.js";
+import { CliLogger, CliRuntime } from "@effected/cli";
+import { Effect } from "effect";
+import { Command } from "effect/unstable/cli";
+
+//#region src/cli/program.ts
+/**
+* The logger the program writes through: stdout is `Console.log` only,
+* so EVERY log level is routed to stderr — warnings, the human lines under
+* `--format=json`, and the rendered failure.
+*
+* @public
+*/
+const loggerLayer = CliLogger.layer({ stderrFrom: "All" });
+const trimLoadError = Effect.fn("schemastore.trimLoadError")(function* (error) {
+	const [first = "", ...rest] = error.reason.split("\n");
+	if (rest.length > 0) yield* Effect.logDebug(rest.join("\n"));
+	return new ConfigLoadError({
+		path: error.path,
+		reason: first
+	});
+});
+/**
+* Parse `args` and run the selected command.
+*
+* @remarks
+* Fails with the marked error the runtime maps to the exit code:
+* `ShowHelp` is `64` with parse errors and `0` without (help itself was
+* already rendered); `ConfigNotFoundError` / `ConfigLoadError` are `2`;
+* `DriftError` / `GateError` / `StaleError` arrive already marked `1`.
+*
+* @public
+*/
+const program = (args, deps) => Command.runWith(makeCommands(deps).root, { version: deps.version })(args).pipe(Effect.catchTags({
+	ShowHelp: (help) => Effect.fail(CliRuntime.reported(help, help.errors.length > 0 ? 64 : 0)),
+	ConfigNotFoundError: (error) => Effect.fail(CliRuntime.reported(error, 2)),
+	ConfigLoadError: (error) => trimLoadError(error).pipe(Effect.flatMap((trimmed) => Effect.fail(CliRuntime.reported(trimmed, 2))))
+}));
+
+//#endregion
+export { loggerLayer, program };

package/cli/root.js

@@ -0,0 +1,23 @@
+import { makeBuildCommand } from "./commands/build.js";
+import { makeCheckCommand } from "./commands/check.js";
+import { Command } from "effect/unstable/cli";
+
+//#region src/cli/root.ts
+/**
+* The command tree, closed over the process boundary it runs against:
+* `main.ts` hands in the process values, tests hand in their own.
+*
+* @public
+*/
+const makeCommands = (deps) => {
+	const build = makeBuildCommand(deps);
+	const check = makeCheckCommand(deps);
+	return {
+		root: Command.make("schemastore", {}).pipe(Command.withDescription("Build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts"), Command.withSubcommands([build, check])),
+		build,
+		check
+	};
+};
+
+//#endregion
+export { makeCommands };

package/main.js

@@ -0,0 +1,27 @@
+import { loggerLayer, program } from "./cli/program.js";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { CliRuntime } from "@effected/cli";
+import { Effect } from "effect";
+import { CliError } from "effect/unstable/cli";
+
+//#region src/main.ts
+/**
+* The assembled schemastore CLI program.
+*
+* @packageDocumentation
+*/
+const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp" ? [] : [error instanceof Error ? error.message : String(error)];
+const main = () => {
+	const run = program(process.argv.slice(2), {
+		cwd: process.cwd(),
+		version: "0.9.0"
+	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
+		exitCode: 3,
+		render
+	}), Effect.provide(loggerLayer));
+	NodeRuntime.runMain(run);
+};
+
+//#endregion
+export { main };

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@effected/schemastore-cli",
+	"version": "0.9.0",
+	"private": false,
+	"description": "The schemastore command: build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts, with a per-schema published flag and a drift policy.",
+	"keywords": [
+		"schemastore",
+		"json-schema",
+		"draft-07",
+		"cli",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/schemastore-cli#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/schemastore-cli"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"schemastore": "bin/schemastore.js"
+	},
+	"dependencies": {
+		"@effect/platform-node": "4.0.0-rc.115",
+		"@effected/cli": "^0.4.1",
+		"jiti": "^2.6.0"
+	},
+	"peerDependencies": {
+		"@effected/schemastore": "0.9.0",
+		"effect": "4.0.0-rc.115"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}