@effected/cli-kit 0.0.0-stage → 0.26.0

package/internal/failureTarget.js

@@ -0,0 +1,195 @@
+import { CliFailure } from "../CliFailure.js";
+import { CliLinks } from "../CliLinks.js";
+import { CliTheme } from "../CliTheme.js";
+import { sanitize } from "../Fmt.js";
+import { Glyphs } from "../Glyphs.js";
+import { Render } from "../Render.js";
+import { autoFormat } from "./autoFormat.js";
+import { identity } from "./displayPath.js";
+import { Config, Context, Effect, MutableRef, Option } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+// src/internal/failureTarget.ts
+/**
+* A cell `CliRuntime.main` provides outside failure reporting and fills from inside it.
+*
+* @remarks
+* `reportFailures` catches OUTSIDE the layers `main` provides, so the theme, terminal, audience and links a report is
+* rendered with are not in its context when a failure arrives. The environment layer writes the target here as it is
+* built, and an audience flag rewrites it once the flag is read. A `Reference` defaulting to `undefined`, so a
+* program run without `main` finds no cell and falls back, and no state is shared between runs.
+*
+* @internal
+*/
+const FailureTargetCell = Context.Reference("@effected/cli-kit/FailureTargetCell", { defaultValue: () => void 0 });
+/** What a report is rendered with when nothing is known about the terminal: plain text, no limit, no escapes. */
+const fallbackTarget = {
+	ctx: {
+		width: Number.POSITIVE_INFINITY,
+		audience: "agent",
+		color: "none",
+		paint: (_token, text) => text,
+		glyphs: Glyphs.ascii,
+		link: (_target, label) => label,
+		displayPath: identity,
+		neutralizeWorkflowCommands: true
+	},
+	format: "plain",
+	assumed: true
+};
+/**
+* The target for the services in the current context, or `undefined` when it lacks any of the four.
+*
+* @remarks
+* Each is read with `serviceOption`, so this never adds a requirement. `audience` overrides the one in context: an
+* audience flag is provided deeper than the environment layer, where the report cannot see it.
+*/
+const build = (audience, settings = {}) => Effect.gen(function* () {
+	const theme = yield* Effect.serviceOption(CliTheme);
+	const terminal = yield* Effect.serviceOption(TerminalEnv);
+	const current = yield* Effect.serviceOption(Audience);
+	const links = yield* Effect.serviceOption(CliLinks);
+	if (Option.isNone(theme) || Option.isNone(terminal) || Option.isNone(links)) return void 0;
+	const shape = audience ?? (Option.isSome(current) ? current.value : void 0);
+	if (shape === void 0) return void 0;
+	const { displayPath, stackFrames, spans, appModule } = settings;
+	const ctx = yield* Render.context("stderr", displayPath === void 0 ? void 0 : { displayPath }).pipe(Effect.provideService(CliTheme, theme.value), Effect.provideService(TerminalEnv, terminal.value), Effect.provideService(CliLinks, links.value), Effect.provideService(Audience, shape));
+	return {
+		ctx,
+		format: yield* autoFormat(ctx.audience),
+		...stackFrames === void 0 ? {} : { stackFrames },
+		...spans === void 0 ? {} : { spans },
+		...appModule === void 0 ? {} : { appModule }
+	};
+});
+/**
+* Record the target for the services in context in the cell, if there is one. A no-op without a cell or services.
+*
+* @internal
+*/
+const refreshFailureTarget = (audience, settings) => Effect.gen(function* () {
+	const cell = yield* FailureTargetCell;
+	if (cell === void 0) return;
+	const recorded = MutableRef.get(cell);
+	const target = yield* build(audience, settings ?? {
+		displayPath: recorded?.ctx.displayPath,
+		stackFrames: recorded?.stackFrames,
+		spans: recorded?.spans,
+		appModule: recorded?.appModule
+	});
+	if (target !== void 0) MutableRef.set(cell, target);
+});
+/**
+* The target a report is rendered with: the cell, else the services in context, else the plain fallback.
+*
+* @internal
+*/
+const currentTarget = Effect.gen(function* () {
+	const cell = yield* FailureTargetCell;
+	const recorded = cell === void 0 ? void 0 : MutableRef.get(cell);
+	if (recorded !== void 0) return recorded;
+	return (yield* build()) ?? fallbackTarget;
+});
+/** Content with its leading status mark (and the space after it) removed. */
+const dropStatus = (content) => {
+	if (content[0]?._tag !== "StatusMark") return content;
+	const next = content[1];
+	return next?._tag === "Text" && next.value === " " ? content.slice(2) : content.slice(1);
+};
+/**
+* A failure document without its status marks. A failure's status leads its first paragraph, or a schema failure's
+* tree label; nothing else in the document carries one.
+*/
+const withoutStatus = (doc) => doc.map((block) => {
+	if (block._tag === "Paragraph") return {
+		...block,
+		content: dropStatus(block.content)
+	};
+	if (block._tag === "Tree") return {
+		...block,
+		root: {
+			...block.root,
+			label: dropStatus(block.root.label)
+		}
+	};
+	return block;
+});
+/**
+* The lines of a failure report for a target, with or without the leading status.
+*
+* @internal
+*/
+const linesOf = (cause, target, status = true, spans = target.spans) => {
+	const full = CliFailure.toDoc(cause, {
+		displayPath: target.ctx.displayPath,
+		...target.stackFrames === void 0 ? {} : { stackFrames: target.stackFrames },
+		...spans === void 0 ? {} : { spans },
+		...target.appModule === void 0 ? {} : { appModule: target.appModule }
+	});
+	const doc = status ? full : withoutStatus(full);
+	const text = Render[target.format](doc, target.ctx);
+	return text === "" ? [] : text.split("\n");
+};
+/**
+* A consumer `render`'s lines, made safe: neutralized under GitHub Actions, and stripped of escapes for an agent.
+*
+* @remarks
+* What a consumer's `render` returns is text the kit did not build and cannot vouch for: it interpolates error
+* messages, file names, whatever the failure carried. So it gets the output policy the kit's own report has. Under
+* GitHub Actions (the target says so, and with no environment services at all it is assumed) every line is neutralized,
+* a returned line break splitting it first. For an agent or a CI audience the escapes are removed too (GitHub Actions
+* detects as `ci`, and the kit's own output for it has none). For a person they are kept: the kit cannot tell the consumer's own colour from an injected sequence, so the consumer's `render` is
+* responsible for sanitising what it interpolates. An audience that was only assumed is not an agent.
+*
+* @internal
+*/
+const guardConsumerLines = (lines) => Effect.map(currentTarget, (target) => {
+	const stripped = target.assumed !== true && (target.ctx.audience === "agent" || target.ctx.audience === "ci") ? lines.map(sanitize) : lines;
+	return target.ctx.neutralizeWorkflowCommands === true ? stripped.flatMap((line) => CommandNeutralizer.lines(line)) : stripped;
+});
+/**
+* The plain lines of a failure, for a caller with no services: what `CliRuntime.defaultRender` returns.
+*
+* @internal
+*/
+const plainFailureLines = (cause, status = true, spans) => linesOf(cause, fallbackTarget, status, spans);
+const SPAN_SETTINGS = [
+	"app",
+	"all",
+	"off"
+];
+/**
+* The span trail setting, as `CliLog`'s level is read: the explicit `spans` when given (the variable is then not read
+* at all), else the variable named `envVar` through `Config`, case-insensitive, unset or empty meaning the default.
+* A value that is not a setting is ignored, with the warning to log.
+*
+* @internal
+*/
+const readSpans = (explicit, envVar) => Effect.gen(function* () {
+	if (explicit !== void 0) return {
+		spans: explicit,
+		invalid: void 0
+	};
+	if (envVar === void 0) return {
+		spans: void 0,
+		invalid: void 0
+	};
+	const raw = yield* Config.option(Config.String(envVar)).pipe(Effect.orElseSucceed(() => Option.none()));
+	if (Option.isNone(raw) || raw.value === "") return {
+		spans: void 0,
+		invalid: void 0
+	};
+	const value = raw.value.toLowerCase();
+	const spans = SPAN_SETTINGS.find((setting) => setting === value);
+	if (spans !== void 0) return {
+		spans,
+		invalid: void 0
+	};
+	return {
+		spans: void 0,
+		invalid: `${envVar}=${raw.value} is not a span setting (${SPAN_SETTINGS.join("|")}); ignoring it`
+	};
+});
+
+export { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget };

package/internal/fallbackAnswer.js

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { CliError, Prompt } from "effect/cli";
+
+// src/internal/fallbackAnswer.ts
+/**
+* What a fallback hands core when the run is not interactive: `otherwise`, answered, when given (`undefined` counts
+* as not given); otherwise core's own missing-parameter error, so the parse fails exactly as it would with no
+* fallback and `CliRuntime.main` exits `64`. Shared by `CliPrompt.fallback` and `CliUi.fallback`.
+*
+* @internal
+*/
+const answerWithoutPerson = (target) => {
+	if ("otherwise" in target && target.otherwise !== void 0) return Effect.succeed(Prompt.succeed(target.otherwise));
+	return Effect.fail("flag" in target ? new CliError.MissingOption({ option: target.flag }) : new CliError.MissingArgument({ argument: target.argument }));
+};
+
+export { answerWithoutPerson };

package/internal/fileSink.js

@@ -0,0 +1,61 @@
+import { sanitize } from "../Fmt.js";
+import { formatNdjson, passes } from "./diagnostics.js";
+import { Cause, Console, Effect, Exit, Fiber, FileSystem, Logger, Path, Queue } from "effect";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+// src/internal/fileSink.ts
+/** How long closing the scope waits for queued lines to reach the file before giving up on a hung filesystem. */
+const CLOSE_TIMEOUT = "2 seconds";
+/**
+* An asynchronous NDJSON file logger.
+*
+* @remarks
+* `Logger.make` takes a synchronous callback, so the logger only offers the line to a queue; a fiber scoped to the
+* layer drains it and appends each batch with `FileSystem.writeFileString(..., { flag: "a" })`. The first write
+* error prints one stderr line and disables the sink: later lines, including any still queued, are discarded
+* without a message. A defect from the filesystem counts as a write error. Closing the scope ends the queue and
+* waits for the drain for at most two seconds, so lines queued before the close are flushed unless the sink had
+* already disabled itself or the filesystem hangs; past the bound the drain is interrupted and the rest is lost.
+*
+* The stderr line is held to the rules of every other kit write: the path (which a workflow can set through an env
+* var) and the error's message are sanitised, and the line is neutralized when `underActions` says the drain's fiber
+* runs under GitHub Actions, the same decision the diagnostics sink makes.
+*
+* @internal
+*/
+const makeFileSink = (path, installed, underActions) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const location = yield* Path.Path;
+	const queue = yield* Queue.unbounded();
+	let disabled = false;
+	let directoryMade = false;
+	const append = (lines) => Effect.gen(function* () {
+		if (!directoryMade) {
+			yield* fs.makeDirectory(location.dirname(path), { recursive: true });
+			directoryMade = true;
+		}
+		yield* fs.writeFileString(path, lines.map((line) => `${line}\n`).join(""), { flag: "a" });
+	});
+	const drain = Effect.gen(function* () {
+		while (true) {
+			const batch = yield* Queue.takeAll(queue);
+			if (disabled) continue;
+			const exit = yield* Effect.exit(append(batch));
+			if (Exit.isFailure(exit)) {
+				disabled = true;
+				const error = Cause.squash(exit.cause);
+				const message = error instanceof Error ? error.message : String(error);
+				const line = sanitize(`diagnostics log file ${path} failed: ${message}; further file logging disabled`);
+				yield* Effect.withFiber((self) => Console.error(underActions(self) ? CommandNeutralizer.text(line) : line));
+			}
+		}
+	}).pipe(Effect.ignore);
+	const fiber = yield* Effect.forkScoped(drain);
+	yield* Effect.addFinalizer(() => Queue.end(queue).pipe(Effect.andThen(Fiber.join(fiber).pipe(Effect.timeout(CLOSE_TIMEOUT))), Effect.ignore));
+	return Logger.make((record) => {
+		if (!passes(record, installed)) return;
+		Queue.offerUnsafe(queue, formatNdjson(record));
+	});
+});
+
+export { makeFileSink };

package/internal/format.js

@@ -0,0 +1,175 @@
+import { Fmt } from "../Fmt.js";
+import { SchemaAST, SchemaIssue } from "effect";
+
+// src/internal/format.ts
+/** The message an unknown key renders as: the leaf hook below writes it and the "did you mean" hint reads it. */
+const UNKNOWN_KEY = "unknown key";
+/**
+* Core's structured formatter, with one phrasing override.
+*
+* @remarks
+* Built once: it is a pure function of the issue tree and carries no state.
+*
+* Core renders an excess property as `"Expected no excess property"`, which
+* describes the **schema's rule** rather than the **user's mistake**. The path
+* already names the key, so `unknown key at groups.g.cleanup.rulesetz` says the
+* same thing in the words someone editing a config file would use. Every other
+* leaf keeps core's phrasing, which is why this goes through `defaultLeafHook`
+* rather than a table of our own.
+*
+* @internal
+*/
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag === "UnexpectedKey" ? UNKNOWN_KEY : SchemaIssue.defaultLeafHook(issue) });
+/**
+* Flatten an issue tree to one line per rejected value.
+*
+* @remarks
+* Shared by `SchemaIssueRenderer` and `ConfigIssueRenderer` and imported by
+* nothing else. It lives here rather than in either module so that
+* `ConfigIssueRenderer` — the only export that references the optional
+* `@effected/config-file` peer — can stay a module no other module imports.
+*
+* **No walker of our own.** `makeFormatterStandardSchemaV1` already flattens the
+* tree to `{ message, path }` entries, and `defaultLeafHook` covers every leaf
+* variant, so a wrong *type* renders as sensibly as an unknown key and a
+* variant added upstream is covered without a change here.
+*
+* Nodes are never stringified: each carries the entire AST inline, annotations
+* included, so `String(node)` would dump the schema rather than describe the
+* failure. Only `message` and `path` are read.
+*
+* @internal
+*/
+const formatIssue = (issue) => issueEntries(issue).map((entry) => entry.path.length === 0 ? entry.message : `${entry.message} at ${entry.path.join(".")}`);
+/**
+* {@link formatIssue}, with a "did you mean" hint on an unknown key the schema has a near match for.
+*
+* @remarks
+* Used by `ConfigIssueRenderer` only. The declared keys come from the issue tree itself: core's `UnexpectedKey` leaf
+* carries the AST of the struct being decoded, whose property signatures are the keys the schema accepts at that
+* path, so no schema is passed in and no `@effected/config-file` value is needed. The hint is `Fmt.suggest`'s list,
+* each key sanitised, and a line with no near match is exactly the line {@link formatIssue} draws.
+*
+* @internal
+*/
+const formatIssueWithHints = (issue) => {
+	const declared = declaredKeys(issue);
+	return issueEntries(issue).map((entry) => {
+		if (entry.path.length === 0) return entry.message;
+		const line = `${entry.message} at ${entry.path.join(".")}`;
+		if (entry.message !== UNKNOWN_KEY) return line;
+		const candidates = declared.get(pathKey(entry.path));
+		const input = entry.path[entry.path.length - 1];
+		if (candidates === void 0 || input === void 0) return line;
+		const near = Fmt.suggest(input, candidates);
+		if (near.length === 0) return line;
+		return `${line} (did you mean ${orList(near.map((key) => `"${Fmt.sanitize(key)}"`))}?)`;
+	});
+};
+/** A path as a map key: `JSON.stringify` keeps `["a.b"]` and `["a", "b"]` apart, which joining on `.` would not. */
+const pathKey = (path) => JSON.stringify(path);
+/** `"a"`, `"a" or "b"`, `"a", "b" or "c"`. */
+const orList = (items) => items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+/**
+* The keys each unknown key's struct declares, by the unknown key's own path.
+*
+* @remarks
+* Walks the tree the way core's formatter does (a `Pointer` extends the path; a `Filter`, `Encoding`, `Composite` or
+* `AnyOf` passes it through), so a path here is the path the formatter gives the same leaf. A union reports one
+* `UnexpectedKey` per branch at one path, and every branch's keys are candidates. Only string keys are offered: a
+* symbol key is never something a person typed into a config file.
+*/
+const declaredKeys = (issue) => {
+	const found = /* @__PURE__ */ new Map();
+	if (!SchemaIssue.isIssue(issue)) return found;
+	const walk = (node, path) => {
+		switch (node._tag) {
+			case "Filter":
+			case "Encoding":
+				walk(node.issue, path);
+				return;
+			case "Pointer":
+				walk(node.issue, [...path, ...node.path.map(String)]);
+				return;
+			case "Composite":
+			case "AnyOf":
+				for (const child of node.issues) walk(child, path);
+				return;
+			case "UnexpectedKey": {
+				if (!SchemaAST.isObjects(node.ast)) return;
+				const key = pathKey(path);
+				const keys = found.get(key) ?? /* @__PURE__ */ new Set();
+				for (const signature of node.ast.propertySignatures) if (typeof signature.name === "string") keys.add(signature.name);
+				found.set(key, keys);
+				return;
+			}
+			default: return;
+		}
+	};
+	walk(issue, []);
+	return found;
+};
+/**
+* The rejected values of an issue tree, once each: what both the lines and the tree are built from.
+*
+* @remarks
+* Anything that is not an issue tree yields none rather than throwing. A rendering helper on an error path must never
+* become the reason a program dies: it is called when something has already gone wrong. A union reports every branch
+* it tried, so one wrong key in a three-member union is the same entry three times; the per-branch "Missing key"
+* entries differ and are kept, since they say which shapes were allowed, but the repeat is pure noise in front of them.
+*
+* @internal
+*/
+const issueEntries = (issue) => {
+	if (!SchemaIssue.isIssue(issue)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const entry of formatter(issue).issues) {
+		const path = (entry.path ?? []).map(String);
+		const key = path.length === 0 ? entry.message : `${entry.message} at ${path.join(".")}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		entries.push({
+			message: entry.message,
+			path
+		});
+	}
+	return entries;
+};
+const emptyNode = () => ({
+	messages: [],
+	children: /* @__PURE__ */ new Map()
+});
+/**
+* The entries as the input of a `Doc.tree`: one node per path segment, so `groups.g.extra` is three nested nodes, and
+* the message at the end of a path is the node's label (`extra: unknown key`) or, when the node has more to say, its
+* leaves.
+*
+* @internal
+*/
+const issueTreeChildren = (entries) => {
+	const root = emptyNode();
+	for (const entry of entries) {
+		let node = root;
+		for (const segment of entry.path) {
+			let next = node.children.get(segment);
+			if (next === void 0) {
+				next = emptyNode();
+				node.children.set(segment, next);
+			}
+			node = next;
+		}
+		node.messages.push(entry.message);
+	}
+	const leaves = (node) => node.messages.map((message) => ({ label: message }));
+	const named = (segment, node) => {
+		if (node.children.size === 0 && node.messages.length === 1) return { label: `${segment}: ${node.messages[0]}` };
+		return {
+			label: segment,
+			children: [...leaves(node), ...[...node.children].map(([name, child]) => named(name, child))]
+		};
+	};
+	return [...leaves(root), ...[...root.children].map(([name, child]) => named(name, child))];
+};
+
+export { formatIssue, formatIssueWithHints, issueEntries, issueTreeChildren };

package/internal/inspect.js

@@ -0,0 +1,40 @@
+// src/internal/inspect.ts
+/** The value's `_tag` when it is a string; `undefined` otherwise, and when reading it throws. */
+const tagOf = (value) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	try {
+		const tag = value._tag;
+		return typeof tag === "string" ? tag : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* A failure value as report text: `String(value)`, except that a plain object whose `String` says only
+* `[object Object]` is its string `message` when it has one. `String(value)` throws for an object with no prototype or
+* a hostile `toString`: that value is `unprintable`.
+*/
+const failureText = (value, unprintable = "[unprintable value]") => {
+	try {
+		const text = String(value);
+		if (text !== "[object Object]") return text;
+		const message = value?.message;
+		return typeof message === "string" ? message : text;
+	} catch {
+		return unprintable;
+	}
+};
+/**
+* A property of a failure value, or `undefined` when it has none or reading it throws: a report must never fail on a
+* hostile getter. An `Error`'s `stack` counts, since V8 formats it on first read and the formatting reads `message`.
+*/
+const readProperty = (value, key) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	try {
+		return value[key];
+	} catch {
+		return;
+	}
+};
+
+export { failureText, readProperty, tagOf };

package/internal/isExitCode.js

@@ -0,0 +1,11 @@
+// src/internal/isExitCode.ts
+/**
+* Whether `code` is an exit status a POSIX process can carry: an integer in
+* `0..255`. `NaN`, fractions and out-of-range values all fail — a relational
+* check alone would admit `NaN`.
+*
+* @internal
+*/
+const isExitCode = (code) => Number.isInteger(code) && code >= 0 && code <= 255;
+
+export { isExitCode };