@effected/cli-kit 0.0.0-stage → 0.26.0

package/CliFailure.js

@@ -0,0 +1,287 @@
+import { Cancelled } from "./Cancelled.js";
+import { Doc } from "./Doc.js";
+import { Fmt } from "./Fmt.js";
+import { identity } from "./internal/displayPath.js";
+import { issueEntries, issueTreeChildren } from "./internal/format.js";
+import { failureText, readProperty, tagOf } from "./internal/inspect.js";
+import { splitFrame } from "./internal/splitFrame.js";
+import { NotInteractive } from "./NotInteractive.js";
+import { Status } from "./Status.js";
+import { Cause, Context, SchemaIssue } from "effect";
+
+// src/CliFailure.ts
+/**
+* The protocol an error class implements to say how a failure is shown: a method under this key that returns the
+* document.
+*
+* @remarks
+* `CliFailure.toDoc` calls it for a typed failure that has one, so an application error draws itself (a heading, a
+* table of what went wrong) and the default report uses it with no registration. A `Symbol.for` key, so two copies
+* of this package agree on it.
+*
+* @public
+*/
+const CliDoc = Symbol.for("@effected/cli-kit/CliDoc");
+/** The deepest an `Error.cause` chain, or a stack, is followed. */
+const MAX_DEPTH = 8;
+const MAX_SPANS = 32;
+const hasCliDoc = (value) => typeof value === "object" && value !== null && typeof value[CliDoc] === "function";
+const firstLine = (text) => text.split(/\r\n|\r|\n/, 1)[0] ?? "";
+/** The failure status and the text of a message: one block per line, the status on the first. */
+const failureBlocks = (message) => {
+	const [first = "", ...rest] = message.split(/\r\n|\r|\n/);
+	return [Doc.paragraph(Doc.status(Status.core, "failure"), " ", first), ...rest.map((line) => Doc.paragraph(line))];
+};
+/** The issue of a schema failure: the value itself, or the `issue` an error carries. */
+const issueOf = (error) => {
+	if (SchemaIssue.isIssue(error)) return error;
+	const issue = readProperty(error, "issue");
+	return SchemaIssue.isIssue(issue) ? issue : void 0;
+};
+const schemaBlocks = (error) => {
+	const entries = issueEntries(issueOf(error));
+	if (entries.length === 0) return void 0;
+	const header = typeof error === "object" && error !== null && !SchemaIssue.isIssue(error) ? firstLine(failureText(readProperty(error, "message") ?? "")) : "";
+	const root = {
+		label: [
+			Doc.status(Status.core, "failure"),
+			" ",
+			header === "" ? `invalid value (${Fmt.plural(entries.length, "problem")})` : header
+		],
+		children: issueTreeChildren(entries)
+	};
+	return [Doc.tree(root)];
+};
+/** The location of a frame as a path: a `file:` URL decoded, or an absolute POSIX or drive path; else `undefined`. */
+const asPath = (location) => {
+	if (location.startsWith("file:")) try {
+		const path = decodeURIComponent(new URL(location).pathname);
+		return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+	} catch {
+		return;
+	}
+	return location.startsWith("/") || /^[A-Za-z]:[\\/]/.test(location) ? location : void 0;
+};
+/** A location without its `:line:col`, and the position when there is one. */
+const splitPosition = (location) => {
+	const position = /^(.*):(\d+):(\d+)$/.exec(location);
+	return position === null ? { where: location } : {
+		where: position[1] ?? "",
+		line: Number(position[2]),
+		col: Number(position[3])
+	};
+};
+const parseFrame = (raw) => {
+	const { text, fn, location } = splitFrame(raw);
+	const { where, line, col } = splitPosition(location);
+	const file = asPath(where);
+	return {
+		raw: text,
+		...fn === void 0 ? {} : { fn },
+		...file === void 0 ? {} : { file },
+		...file === void 0 || line === void 0 || col === void 0 ? {} : {
+			line,
+			col
+		}
+	};
+};
+/** The file a frame ran in, as a path, or `undefined` for a frame with none: `node:`, `<anonymous>`, `native`, `eval`. */
+const frameFile = (raw) => asPath(splitPosition(splitFrame(raw).location).where);
+/** A frame under `node_modules`: a dependency's, or an installed program's own. Decided by its file alone. */
+const isDependency = (raw) => /[\\/]node_modules[\\/]/.test(frameFile(raw) ?? "");
+/**
+* A frame that is the runtime's or Effect's, never the program's, wherever the program is installed: one with no file
+* (every `node:` frame, `<anonymous>`, native), or one in Effect's own files. Decided by the file alone, never by the
+* function name: V8 names a program's own thunk by Effect's method alias (`boom [as ~effect/Effect/args]`).
+*/
+const isRuntime = (raw) => {
+	const file = frameFile(raw);
+	return file === void 0 || /[\\/]node_modules[\\/]effect[\\/]/.test(file) || /[\\/]packages[\\/]effect[\\/]src[\\/]/.test(file);
+};
+/** The frames of a stack that belong to the program, and how many were left out. */
+const cleanStack = (stack, mode) => {
+	if (typeof stack !== "string") return {
+		frames: [],
+		hidden: 0
+	};
+	const lines = stack.split(/\r\n|\r|\n/).filter((line) => /^\s*at\s/.test(line));
+	const app = lines.filter((line) => !isRuntime(line) && !isDependency(line));
+	const kept = mode === "all" ? lines : app.length > 0 ? app : lines.filter((line) => !isRuntime(line));
+	return {
+		frames: kept.map(parseFrame),
+		hidden: lines.length - kept.length
+	};
+};
+const frameBlock = (frame, displayPath) => {
+	if (frame.file === void 0) return Doc.paragraph(Doc.text("at ", "muted"), frame.raw);
+	const where = `${displayPath(frame.file)}${frame.line === void 0 ? "" : `:${frame.line}:${frame.col}`}`;
+	const target = {
+		file: frame.file,
+		...frame.line === void 0 ? {} : { line: frame.line },
+		...frame.col === void 0 ? {} : { col: frame.col }
+	};
+	return Doc.paragraph(Doc.text("at ", "muted"), ...frame.fn === void 0 ? [] : [`${frame.fn} `], Doc.link(target, where));
+};
+const stackBlock = (defect, displayPath, mode) => {
+	const { frames, hidden } = cleanStack(readProperty(defect, "stack"), mode);
+	if (frames.length > 0) {
+		const shown = frames.map((frame) => frameBlock(frame, displayPath));
+		const note = hidden === 0 ? [] : [Doc.paragraph(Doc.text(`(+${hidden} internal frames hidden)`, "muted"))];
+		return Doc.collapsible("stack", [...shown, ...note], { open: true });
+	}
+	const note = hidden === 0 ? "no stack" : `no user frames (${hidden} internal frames hidden)`;
+	return Doc.collapsible("stack", [Doc.paragraph(Doc.text(note, "muted"))], { open: true });
+};
+/** The `Error.cause` chain below a defect as a tree of one-line messages, or none. */
+const causeTree = (defect) => {
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set([defect]);
+	for (let current = readProperty(defect, "cause"); current !== void 0 && chain.length < MAX_DEPTH;) {
+		if (seen.has(current)) break;
+		seen.add(current);
+		chain.push(firstLine(failureText(current)));
+		current = current instanceof Error ? readProperty(current, "cause") : void 0;
+	}
+	if (chain.length === 0) return void 0;
+	const nest = (index) => index === chain.length - 1 ? { label: chain[index] } : {
+		label: chain[index],
+		children: [nest(index + 1)]
+	};
+	return Doc.tree({
+		label: firstLine(failureText(defect)),
+		children: [nest(0)]
+	});
+};
+const dieBlocks = (defect, spans, displayPath, mode) => {
+	if (defect instanceof Cancelled || defect instanceof NotInteractive) return [Doc.paragraph(defect.message)];
+	const header = failureBlocks(failureText(defect));
+	if (!(defect instanceof Error)) return [...header, ...spans];
+	const chain = causeTree(defect);
+	return [
+		...header,
+		...spans,
+		stackBlock(defect, displayPath, mode),
+		...chain === void 0 ? [] : [chain]
+	];
+};
+const failBlocks = (error, spans, options) => {
+	if (hasCliDoc(error)) try {
+		return [...error[CliDoc](), ...spans];
+	} catch {}
+	const tag = tagOf(error);
+	const custom = tag === void 0 || options?.render === void 0 || !Object.hasOwn(options.render, tag) ? void 0 : options.render[tag];
+	if (custom !== void 0) try {
+		return [...custom(error), ...spans];
+	} catch {}
+	if (error instanceof Cancelled || error instanceof NotInteractive) return [Doc.paragraph(error.message)];
+	const schema = schemaBlocks(error);
+	if (schema !== void 0) return [...schema, ...spans];
+	return [...failureBlocks(failureText(error)), ...spans];
+};
+/** A file of the kit's own packages or of Effect, as installed: a span defined there is not the program's. */
+const isKitFile = (file) => /[\\/]node_modules[\\/](?:@effected[\\/]|effect[\\/])/.test(file);
+/**
+* The installed package directory that holds `module`: the path through the last `node_modules/<name>` or
+* `node_modules/@scope/name` in it, or `undefined` when the module is not under `node_modules` (or not a path at all).
+* Read from the path alone, with no file system.
+*/
+const packageDirOf = (module) => {
+	if (module === void 0) return void 0;
+	const path = asPath(module);
+	if (path === void 0) return void 0;
+	return /^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//.exec(comparable(path))?.[1];
+};
+/**
+* A path in the one spelling both sides of a comparison use: `/` separators, and a Windows drive letter lower-cased. A
+* CommonJS frame on Windows reads `C:\…` where an `import.meta.url` reads `file:///C:/…`, and the drive's case is not
+* fixed (`c:` and `C:` are one drive). Lexical only: no file system, no realpath.
+*/
+const comparable = (path) => path.replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, drive) => `${drive.toLowerCase()}:`);
+/** Whether `file` is in the program's own package `appDir`, and not in a dependency nested in its `node_modules`. */
+const isAppFile = (file, appDir) => {
+	if (appDir === void 0) return false;
+	const path = comparable(file);
+	if (!path.startsWith(appDir)) return false;
+	const rest = path.slice(appDir.length);
+	return rest.startsWith("/") && !rest.includes("/node_modules/");
+};
+/** The file a span frame's captured stack points at, or `undefined` when it captured none. */
+const spanFile = (frame) => {
+	try {
+		const stack = frame.stack();
+		if (stack === void 0) return void 0;
+		const line = stack.split(/\r\n|\r|\n/).find((candidate) => /^\s*at\s/.test(candidate)) ?? stack;
+		return frameFile(line.trim().startsWith("at ") ? line : `at ${line.trim()}`);
+	} catch {
+		return;
+	}
+};
+/**
+* `in: outer › inner`, from the span stack the runtime annotates a reason with, or none. With `app`, a span the kit or
+* Effect defined is left out. An `Effect.fn` call carries its definition as its parent (`name (definition)`): the two
+* are one entry, `name`, judged by the definition's site, so a kit function the program calls goes with its
+* definition.
+*/
+const spanBlocks = (reason, mode, appDir) => {
+	if (mode === "off") return [];
+	const names = [];
+	let frame = Context.getOrUndefined(Cause.reasonAnnotations(reason), Cause.StackTrace);
+	for (let seen = 0; frame !== void 0 && seen < MAX_SPANS; seen++) {
+		const parent = frame.parent;
+		const definition = parent !== void 0 && parent.name === `${frame.name} (definition)` ? parent : void 0;
+		const file = (definition === void 0 ? void 0 : spanFile(definition)) ?? spanFile(frame);
+		if (mode === "all" || file === void 0 || isAppFile(file, appDir) || !isKitFile(file)) names.push(frame.name);
+		frame = definition === void 0 ? parent : definition.parent;
+	}
+	if (names.length === 0) return [];
+	return [Doc.paragraph(Doc.text("in: ", "muted"), Doc.path(...names.reverse()))];
+};
+/**
+* A failure as a document: what the default report prints, and a building block for a custom one.
+*
+* @remarks
+* One run of blocks per `Cause` reason. A typed failure is, in order of preference: the document of an error that
+* implements {@link CliDoc}; the document `options.render` holds for its `_tag`; for `Cancelled` and
+* `NotInteractive`, their one fixed line; a `Tree` of the rejected values, for a schema error or issue; else a failure
+* status line with its message. A defect is its message followed by a collapsible `stack` of the program's own frames,
+* each a file link (so a terminal can open it in an editor) shown through `displayPath`, with the runtime's frames (every
+* `node:` frame and every frame with no file) and every `node_modules` frame (Effect's and any other dependency's)
+* left out unless `stackFrames` is `all`. A frame is classified by its file alone, never by its function name, so a
+* program's own thunk that V8 names by Effect's method alias is still shown. When that would
+* leave no frame at all, as for a program run from its own install under `node_modules`, only the runtime's and
+* Effect's are left out. Then an
+* `Error.cause` chain as a tree. When cleaning leaves no frame the stack says
+* `no user frames (N internal frames hidden)`, never an empty block; when frames survive and some were left out, the
+* count follows them as `(+N internal frames hidden)`. A reason that ran under spans is followed by
+* `in: outer › inner`: by default only the program's own spans, the kit's and Effect's left out (`spans`). Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
+* one line `interrupted`.
+*
+* All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
+* Building it never throws: an error whose `_tag`, `message`, `stack`, `cause` or `issue` getter throws is drawn without
+* that part (an unreadable `stack` as `no stack`, an unreadable `cause` ending the chain there). Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
+*
+* @public
+*/
+var CliFailure = class {
+	constructor() {}
+	/**
+	* Build the document of a cause.
+	*
+	* @param cause - the failure
+	* @param options - per-tag documents and a path display function
+	*/
+	static toDoc = (cause, options) => {
+		const reasons = cause.reasons;
+		if (reasons.length > 0 && reasons.every(Cause.isInterruptReason)) return [Doc.paragraph("interrupted")];
+		const displayPath = options?.displayPath ?? identity;
+		return reasons.flatMap((reason) => {
+			const spans = options?.spans ?? "app";
+			const appDir = packageDirOf(options?.appModule);
+			if (Cause.isFailReason(reason)) return failBlocks(reason.error, spanBlocks(reason, spans, appDir), options);
+			if (Cause.isDieReason(reason)) return dieBlocks(reason.defect, spanBlocks(reason, spans, appDir), displayPath, options?.stackFrames ?? "app");
+			return [];
+		});
+	};
+};
+
+export { CliDoc, CliFailure };

package/CliFormat.js

@@ -0,0 +1,124 @@
+import { Doc } from "./Doc.js";
+import { underGithubActions } from "./internal/autoFormat.js";
+import { neutralizeJson } from "./internal/logSafety.js";
+import { Console, Effect } from "effect";
+import { Flag } from "effect/cli";
+
+// src/CliFormat.ts
+const BUILT_IN = /* @__PURE__ */ new Set([
+	"auto",
+	"plain",
+	"ansi",
+	"markdown",
+	"githubLog",
+	"json"
+]);
+/**
+* A `--format` flag and the one print that honours it, so a command builds its report once as a `Doc` and its data
+* once as a value, and never writes per-format output by hand.
+*
+* @remarks
+* The flag is core's `Flag.ChoiceWithValue` with the kit's names, default and description; the print hands every
+* document format to `Doc.print` and writes `json` itself.
+*
+* ```ts
+* const format = CliFormat.flag(["auto", "markdown", "json"])
+* const doctor = Command.make("doctor", { format }, ({ format }) =>
+*   CliFormat.print(format, { doc: () => report(results), json: () => results }),
+* )
+* ```
+*
+* @public
+*/
+var CliFormat = class CliFormat {
+	constructor() {}
+	/**
+	* A `--format` flag offering `formats`, and the caller's own `aliases` and `custom` formats.
+	*
+	* @remarks
+	* Its default is `options.default`, else `auto` when it is offered, else the first format. Any other value is a
+	* usage error from core's parser, naming the accepted ones. The value is the built-in format a name stands for
+	* (`human` under `{ human: "auto" }` is `auto`), or a custom name as itself, so the value of a flag with no custom
+	* formats goes straight to {@link CliFormat.print}.
+	*
+	* Two offered names that clash (an alias or custom name reusing a built-in name, or any name offered twice) and a
+	* default that is not offered are programming mistakes: the call throws. A CLI that still accepts a `--json` of its
+	* own declares and resolves that flag itself; {@link CliFormat.printJson} prints the JSON the same way.
+	*
+	* ```ts
+	* // okfit's contract: --format human|json, and a graph command that also draws mermaid and dot
+	* const format = CliFormat.flag(["json"], { aliases: { human: "auto" }, default: "human" })
+	* const graph = CliFormat.flag(["json"], { custom: ["mermaid", "dot"], default: "mermaid" })
+	* ```
+	*
+	* @param formats - the built-in formats the command offers under their own names, at least one
+	* @param options - the default, the flag's name and description, aliases and custom formats
+	*/
+	static flag = (formats, options) => {
+		const name = options?.name ?? "format";
+		const choices = [
+			...formats.map((format) => [format, format]),
+			...Object.entries(options?.aliases ?? {}).map(([alias, target]) => [alias, target]),
+			...(options?.custom ?? []).map((custom) => [custom, custom])
+		];
+		const offered = choices.map(([spelling]) => spelling);
+		for (const [index, spelling] of offered.entries()) {
+			if (offered.indexOf(spelling) !== index) throw new Error(`CliFormat.flag: the format name "${spelling}" is offered twice`);
+			if (index >= formats.length && BUILT_IN.has(spelling)) throw new Error(`CliFormat.flag: "${spelling}" is a built-in format, not an alias or a custom one`);
+		}
+		const fallback = options?.default ?? (offered.includes("auto") ? "auto" : formats[0]);
+		const fallbackChoice = choices.find(([spelling]) => spelling === fallback);
+		if (fallbackChoice === void 0) throw new Error(`CliFormat.flag: the default "${fallback}" is not one of ${offered.join(", ")}`);
+		const flag = Flag.ChoiceWithValue(name, choices).pipe(Flag.withDescription(options?.description ?? `Output format: ${offered.join(", ")} (default ${fallback})`));
+		return Flag.withDefault(flag, fallbackChoice[1]);
+	};
+	/**
+	* Print a command's output in `format`.
+	*
+	* @remarks
+	* `json` writes `output.json()` exactly as {@link CliFormat.printJson} writes a value, which it delegates to. Every
+	* other format prints `output.doc()` with `Doc.print`, which renders it as `auto` or the named renderer would.
+	*
+	* @param format - the chosen format, usually the value of {@link CliFormat.flag}
+	* @param output - the document and the data
+	* @param options - the stream and the JSON indent
+	*/
+	static print = (format, output, options) => Effect.gen(function* () {
+		const stream = options?.stream ?? "stdout";
+		if (format !== "json") return yield* Doc.print(output.doc(), {
+			stream,
+			format
+		});
+		const data = output.json;
+		if (data === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.print: format json needs output.json"));
+		return yield* CliFormat.printJson(data(), options);
+	});
+	/**
+	* Print `value` as JSON, the way {@link CliFormat.print} prints the `json` format, for a CLI that keeps a JSON flag
+	* of its own.
+	*
+	* @remarks
+	* One `Console.log` (or `Console.error` for stderr), indented by `indent`: one document, never one line per item.
+	* Under GitHub Actions a `##[` inside it is written as the JSON escape `#\u0023[`, which decodes to the same
+	* text, so the runner cannot read it as a command. A value JSON cannot hold (a cycle, a bigint, `undefined`) is a
+	* defect. It needs no theme, terminal or audience: whether this is GitHub Actions is read from `CurrentRuntimeEnv`
+	* when the environment has it, and is "no" otherwise.
+	*
+	* ```ts
+	* const status = Command.make("status", { json: Flag.Boolean("json").pipe(Flag.withDefault(false)) }, ({ json }) =>
+	*   json ? CliFormat.printJson(results) : Doc.print(report(results)),
+	* )
+	* ```
+	*
+	* @param value - the data to print
+	* @param options - the stream and the JSON indent
+	*/
+	static printJson = (value, options) => Effect.gen(function* () {
+		const text = yield* Effect.sync(() => JSON.stringify(value, null, options?.indent ?? 2));
+		if (text === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.printJson: the value is not JSON"));
+		const safe = (yield* underGithubActions) ? neutralizeJson(text) : text;
+		yield* (options?.stream ?? "stdout") === "stdout" ? Console.log(safe) : Console.error(safe);
+	});
+};
+
+export { CliFormat };

package/CliInteractive.js

@@ -0,0 +1,94 @@
+import { canPrompt } from "./internal/canPrompt.js";
+import { Context, Effect, Layer } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { TerminalCapabilities } from "effect/cli";
+
+// src/CliInteractive.ts
+/**
+* Whether this run may prompt a person: a human audience, with a terminal on
+* both standard input and standard output, and a `TERM` that is not `dumb`.
+*
+* @remarks
+* A `Context.Reference`, not a `Context.Service`, for three reasons. It is one
+* boolean with a safe default, which is what a reference is for. A scoped
+* override, {@link CliInteractive.unless}, is a plain
+* `Effect.provideService`, so a command can switch prompting off for one
+* subtree without a layer. And forgetting to provide it is not a type error
+* but a harmless answer, since it reads `false` when no layer is provided: a
+* program that never wired it refuses to prompt rather than hanging on a
+* terminal that is not there. Read it with `yield* CliInteractive`.
+*
+* Because a reference's key type is `never`, {@link CliInteractive.layer} and
+* {@link CliInteractive.layerTest} are typed `Layer<never>`: they set the
+* reference rather than provide a service.
+*
+* Both layers also hold core's `TerminalCapabilities.canPrompt` at `true`,
+* keeping its `canColor` and `canAnimate` as they find them. Core skips a
+* `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` fallback entirely
+* when `canPrompt` is `false`, and decides that from the process's own
+* terminal, so a kit fallback (`CliPrompt.fallback`, `CliUi.fallback`) would
+* never be called in a piped run and its `otherwise` would be lost. With the
+* gate held open, this reference makes the prompt decision instead: the kit's
+* fallbacks answer without a person when it is `false`, and
+* `CliPrompt.gateTerminal` quits any other prompt at once. A
+* `TerminalCapabilities` with `canPrompt: false` provided inside the program,
+* under these layers, bypasses the kit's fallbacks again: the parameter fails
+* as missing even when an `otherwise` is given.
+*
+* @public
+*/
+var CliInteractive = class CliInteractive extends Context.Reference("@effected/cli-kit/CliInteractive", { defaultValue: () => false }) {
+	/**
+	* Decide from the audience and the terminal: `true` only for a human audience with a terminal on both
+	* standard input and standard output, and a `TERM` that is not `dumb`.
+	*
+	* @remarks
+	* A dumb terminal is a terminal, but it cannot move the cursor or take synchronized output, which a prompt or a
+	* screen redrawing in place needs: it gets what a pipe gets. `TERM` is read through the ambient `ConfigProvider`,
+	* as `@effected/env` reads the environment, so it adds no requirement; a test fixes it with
+	* `Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ TERM: "dumb" }))`.
+	*
+	* It also holds core's `TerminalCapabilities.canPrompt` at `true`; see {@link CliInteractive}.
+	*
+	* Bind the layer to a constant and provide it once; `Audience` and `TerminalEnv` come from `@effected/env`.
+	*/
+	static layer = Layer.effectContext(Effect.gen(function* () {
+		const audience = yield* Audience;
+		const terminal = yield* TerminalEnv;
+		return yield* decided(audience.kind === "human" && (yield* canPrompt(terminal)));
+	}));
+	/**
+	* A fixed answer that needs nothing. It holds core's `canPrompt` open too, as {@link CliInteractive.layer} does.
+	*
+	* @param value - whether the run is interactive
+	*/
+	static layerTest = (value) => Layer.effectContext(decided(value));
+	/**
+	* Run `self` with interactivity switched off when `condition` holds.
+	*
+	* @remarks
+	* It only narrows: `unless(false)` leaves the current value alone and never turns interactivity on, so a
+	* non-interactive scope stays non-interactive. The outer value is restored when `self` ends, whether it
+	* succeeds, fails or is interrupted.
+	*
+	* A flag that resolves the audience (`--human`, under `CliAudience.runWith` or `provide`) recomputes interactivity
+	* from the terminal facts, so it can override an outer `unless` or a `layerTest(false)`: those narrow the
+	* environment's answer, and the flag is a later, explicit one.
+	*
+	* @param condition - `true` to switch prompting off for `self`
+	*/
+	static unless = (condition) => (self) => Effect.gen(function* () {
+		const current = yield* CliInteractive;
+		return yield* Effect.provideService(self, CliInteractive, current && !condition);
+	});
+};
+/**
+* The context the two layers set: the decision, and core's capabilities as they are found with `canPrompt` held at
+* `true`, so core always hands a missing parameter to its fallback and the kit's decision governs.
+*/
+const decided = (interactive) => Effect.map(TerminalCapabilities.TerminalCapabilities, (capabilities) => Context.make(CliInteractive, interactive).pipe(Context.add(TerminalCapabilities.TerminalCapabilities, {
+	...capabilities,
+	canPrompt: true
+})));
+
+export { CliInteractive };

package/CliLinks.js

@@ -0,0 +1,153 @@
+import { sanitize } from "./Fmt.js";
+import { isAllowedLinkUrl } from "./internal/linkScheme.js";
+import { DRIVE, UNC, encodeForOsc8, fileUrlPath } from "./internal/linkTarget.js";
+import { Config, Context, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { CurrentRuntimeEnv } from "@effected/env";
+import { Walker } from "@effected/walker";
+
+// src/CliLinks.ts
+const MODES = [
+	"auto",
+	"vscode",
+	"file",
+	"off"
+];
+const parseSetting = (raw) => MODES.find((mode) => mode === raw.trim().toLowerCase());
+/** A URL with its control characters and line breaks removed: none is legal in one, and each could end an OSC 8 early. */
+const cleanUrl = (url) => sanitize(url).replace(/[\r\n]/g, "");
+const makeTarget = (mode, absolute) => (target) => {
+	if ("url" in target) {
+		const url = cleanUrl(target.url);
+		return url === "" || !isAllowedLinkUrl(url) ? Option.none() : Option.some(url);
+	}
+	if (mode === "off") return Option.none();
+	const resolved = absolute(target.file);
+	if (resolved === void 0) return Option.none();
+	const path = fileUrlPath(resolved);
+	if (path === void 0) return Option.none();
+	if (mode === "file") return Option.some(`file://${path}`);
+	const position = target.line === void 0 ? "" : target.col === void 0 ? `:${target.line}` : `:${target.line}:${target.col}`;
+	return Option.some(`vscode://file${path}${position}`);
+};
+const isDirectory = (fs, path) => fs.stat(path).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+const exists = (fs, path) => fs.exists(path).pipe(Effect.orElseSucceed(() => false));
+/**
+* The nearest directory, from `cwd` up, that holds `.git` or `pnpm-workspace.yaml`.
+*
+* It looks at `cwd` and then climbs at most {@link MAX_ASCENT} directories, through `Walker.ascend`, which also stops
+* where `dirname` reaches a fixpoint (the filesystem root). `Walker.findRoot` absorbs a failed probe as "not a root",
+* so one unreadable directory never hides a root above it. `None` when there is none.
+*/
+const findRoot = (fs, path, cwd) => Walker.ascend(cwd, { maxDepth: 65 }).pipe(Effect.provideService(Path.Path, path), Effect.flatMap((directories) => Walker.findRoot(directories, (directory) => Effect.gen(function* () {
+	return (yield* exists(fs, path.join(directory, ".git"))) || (yield* exists(fs, path.join(directory, "pnpm-workspace.yaml")));
+}))));
+const readOption = (name) => Config.option(Config.String(name)).pipe(Effect.orElseSucceed(() => Option.none()));
+const build = (options, ambient) => Effect.gen(function* () {
+	const runtime = yield* CurrentRuntimeEnv;
+	const raw = options.envVar === void 0 ? "" : Option.getOrElse(yield* readOption(options.envVar), () => "").trim();
+	const fromEnv = parseSetting(raw);
+	if (options.envVar !== void 0 && raw !== "" && fromEnv === void 0) yield* Effect.logWarning(`${options.envVar}=${raw} is not one of ${MODES.join("|")}; ignoring it`);
+	const setting = fromEnv ?? options.editorLinks ?? "auto";
+	const pwd = options.cwd === void 0 ? yield* readOption("PWD") : Option.none();
+	const cwd = options.cwd ?? Option.getOrUndefined(pwd) ?? (Option.isSome(ambient.path) ? ambient.path.value.resolve(".") : void 0);
+	const path = Option.getOrUndefined(ambient.path);
+	const absolute = (file) => {
+		if (UNC.test(file)) return void 0;
+		if (DRIVE.test(file)) return file;
+		if (path === void 0) return file.startsWith("/") ? file : void 0;
+		if (path.isAbsolute(file)) return file;
+		return cwd === void 0 ? void 0 : path.resolve(cwd, file);
+	};
+	const mode = setting !== "auto" ? setting : Option.exists(runtime.terminal, (terminal) => terminal.name === "vscode") ? "vscode" : yield* Effect.gen(function* () {
+		if (Option.isNone(ambient.fs) || path === void 0 || cwd === void 0) return "file";
+		const root = yield* findRoot(ambient.fs.value, path, cwd);
+		const base = Option.getOrElse(root, () => cwd);
+		return (yield* isDirectory(ambient.fs.value, path.join(base, ".vscode"))) ? "vscode" : "file";
+	});
+	return {
+		mode,
+		target: makeTarget(mode, absolute)
+	};
+});
+/**
+* Editor-aware links for file targets: where a link to a file opens.
+*
+* @remarks
+* The mode is decided once, when the layer is built. `auto` is `vscode` when `CurrentRuntimeEnv.terminal` is
+* `vscode` (`TERM_PROGRAM=vscode`) or a `.vscode/` directory sits at the project root, and `file` otherwise. The
+* root is the nearest directory, from the working directory up, that holds `.git` or `pnpm-workspace.yaml`; the
+* climb is bounded, at most 64 directories above the working directory, and stops where `Path.dirname` reaches the
+* filesystem root. With no root, the working directory itself is checked.
+*
+* Whether a link is written at all is a separate question, answered by {@link CliLinks.linker}.
+*
+* @public
+*/
+var CliLinks = class CliLinks extends Context.Service()("@effected/cli-kit/CliLinks") {
+	/**
+	* The links for the working directory, reading the filesystem for a `.vscode/` directory.
+	*
+	* @remarks
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - the setting, the environment variable that overrides it, and the working directory
+	*/
+	static layer = (options = {}) => Layer.effect(CliLinks, Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		return yield* build(options, {
+			fs: Option.some(fs),
+			path: Option.some(path)
+		});
+	}));
+	/**
+	* Links fixed to a mode, with no filesystem: a relative path has no link, since there is no working directory.
+	*
+	* @param mode - `vscode`, `file` or `off`
+	*/
+	static layerTest = (mode) => Layer.succeed(CliLinks, {
+		mode,
+		target: makeTarget(mode, (file) => file.startsWith("/") || DRIVE.test(file) ? file : void 0)
+	});
+	/**
+	* The function that writes a link: a target and a label in, the label out, wrapped in OSC 8 when it should be.
+	*
+	* @remarks
+	* It writes the hyperlink `ESC ] 8 ; ; URL ESC \ label ESC ] 8 ; ; ESC \` only when the stream's terminal can
+	* render it (`hyperlinks`) and the audience is not an agent, which never gets an escape of any kind; in every other
+	* case, and whenever the target has no URL, it returns the label unchanged. The URL has its control characters
+	* removed again here, so a hostile target cannot end the sequence early or start another, and a URL whose scheme is
+	* not one a link may have (`javascript:`, `data:`, and the like; the same list markdown uses) is the label alone. It is pure and cheap,
+	* which {@link RenderContext}'s `link` requires.
+	*
+	* @param options - the links, whether hyperlinks are available, and the audience
+	*/
+	static linker = (options) => (target, label) => {
+		if (!options.hyperlinks || options.audience === "agent") return label;
+		const url = options.links.target(target);
+		if (Option.isNone(url)) return label;
+		const written = encodeForOsc8(cleanUrl(url.value));
+		if (!isAllowedLinkUrl(written)) return label;
+		return `\u001B]8;;${written}\u001B\\${label}\u001B]8;;\u001B\\`;
+	};
+};
+/**
+* The links for {@link CliEnv.layer}: the same as {@link CliLinks.layer}, except that `FileSystem` and `Path` are
+* taken from the environment if it has them, not required.
+*
+* Without them there is no `.vscode/` to look for and no working directory to resolve a relative path against, so
+* `auto` is `vscode` only on the terminal signal. This keeps the requirements of `CliEnv.layer` and of every
+* `CliRuntime.main` overload unchanged.
+*
+* @internal
+*/
+const ambientLinksLayer = (options = {}) => Layer.effect(CliLinks, Effect.gen(function* () {
+	const fs = yield* Effect.serviceOption(FileSystem.FileSystem);
+	const path = yield* Effect.serviceOption(Path.Path);
+	return yield* build(options, {
+		fs,
+		path
+	});
+}));
+
+export { CliLinks, ambientLinksLayer };