@effected/cli 0.10.0 → 0.12.0

package/CliFailure.js

@@ -0,0 +1,302 @@
+import { Cancelled } from "./Cancelled.js";
+import { Fmt } from "./Fmt.js";
+import { Doc } from "./Doc.js";
+import { issueEntries, issueTreeChildren } from "./internal/format.js";
+import { splitFrame } from "./internal/splitFrame.js";
+import { NotInteractive } from "./NotInteractive.js";
+import { Status } from "./Status.js";
+import { Cause, Context, SchemaIssue } from "effect";
+
+//#region 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/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 describe = (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 value]";
+	}
+};
+const firstLine = (text) => text.split(/\r\n|\r|\n/, 1)[0] ?? "";
+const tagOf = (value) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	const tag = value._tag;
+	return typeof tag === "string" ? tag : void 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;
+	if (typeof error === "object" && error !== null) {
+		const issue = error.issue;
+		if (SchemaIssue.isIssue(issue)) return issue;
+	}
+};
+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(describe(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(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 = defect.cause; current !== void 0 && chain.length < MAX_DEPTH;) {
+		if (seen.has(current)) break;
+		seen.add(current);
+		chain.push(firstLine(describe(current)));
+		current = current instanceof Error ? 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(describe(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(describe(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(describe(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.
+* 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 ?? ((absolute) => absolute);
+		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 [];
+		});
+	};
+};
+
+//#endregion
+export { CliDoc, CliFailure };

package/CliInteractive.js

@@ -0,0 +1,71 @@
+import { canPrompt } from "./internal/canPrompt.js";
+import { Context, Effect, Layer } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+
+//#region 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.
+*
+* @public
+*/
+var CliInteractive = class CliInteractive extends Context.Reference("@effected/cli/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" }))`.
+	*
+	* Bind the layer to a constant and provide it once; `Audience` and `TerminalEnv` come from `@effected/env`.
+	*/
+	static layer = Layer.effect(CliInteractive, Effect.gen(function* () {
+		const audience = yield* Audience;
+		const terminal = yield* TerminalEnv;
+		return audience.kind === "human" && (yield* canPrompt(terminal));
+	}));
+	/**
+	* A fixed answer that needs nothing.
+	*
+	* @param value - whether the run is interactive
+	*/
+	static layerTest = (value) => Layer.succeed(CliInteractive, 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);
+	});
+};
+
+//#endregion
+export { CliInteractive };

package/CliLinks.js

@@ -0,0 +1,154 @@
+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";
+
+//#region 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/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
+	});
+}));
+
+//#endregion
+export { CliLinks, ambientLinksLayer };