@effected/cli-kit 0.0.0-stage → 0.26.0

package/Cancelled.js

@@ -0,0 +1,43 @@
+import { Runtime, Schema } from "effect";
+
+// src/Cancelled.ts
+/**
+* A person backed out of an interactive prompt: they pressed escape, or the
+* prompt was interrupted.
+*
+* @remarks
+* Exits `130`, the conventional status for a run ended by the user, through
+* core's own `Runtime.errorExitCode` marker, so `CliRuntime.reportFailures`
+* keeps it. Its default rendering is one line, `cancelled; nothing written`,
+* because nothing has been written by the time a prompt is cancelled and a
+* stack trace would only alarm. A consumer `render` still overrides the line, and can hand off to it: the line is
+* the error's `message`, so `error.message` and `String(error)` carry it.
+*
+* @public
+*/
+var Cancelled = class extends Schema.TaggedError()("Cancelled", { reason: Schema.Literals(["escape", "interrupt"]) }) {
+	/**
+	* The one line, `cancelled; nothing written`.
+	*
+	* @remarks
+	* A prototype getter, not a field, so it is not part of the encoded form, equality or a JSON dump. Assigning to
+	* it is ignored: a library that rewrites `error.message` (to prefix a context, say) must not make this error throw,
+	* which a getter-only property does in strict mode. The line is fixed.
+	*/
+	get message() {
+		return "cancelled; nothing written";
+	}
+	set message(_value) {}
+	/**
+	* The process exit code: `130`.
+	*
+	* @remarks
+	* A prototype getter rather than an own field, so a JSON or logger dump of the error does not carry the
+	* runtime marker.
+	*/
+	get [Runtime.errorExitCode]() {
+		return 130;
+	}
+};
+
+export { Cancelled };

package/CliAudience.js

@@ -0,0 +1,177 @@
+import { CliInteractive } from "./CliInteractive.js";
+import { canPrompt } from "./internal/canPrompt.js";
+import { refreshFailureTarget } from "./internal/failureTarget.js";
+import { scanAudience, tallyAudience } from "./internal/scanAudience.js";
+import { WizardDropped } from "./internal/wizardGate.js";
+import { Effect, Option, Stdio } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CliConfig, CliError, Command, Flag, GlobalFlag } from "effect/cli";
+
+// src/CliAudience.ts
+const KINDS = [
+	"human",
+	"agent",
+	"ci"
+];
+/**
+* Whether the run may prompt once a flag has named the audience.
+*
+* Only a `human` audience prompts, and only with a terminal on both standard input and standard output and a `TERM`
+* that is not `dumb` (`canPrompt`, the decision `CliInteractive.layer` makes). With the
+* terminal facts in the environment (`TerminalEnv`) that is decided from them, not from the ambient value, so a
+* flag can WIDEN: `--human` under a detected agent on real terminals prompts, and in a pipe it still cannot. With no
+* `TerminalEnv` there is nothing to decide from and the flag only narrows.
+*/
+const interactiveWhenFlagged = (kind, current) => Effect.flatMap(Effect.serviceOption(TerminalEnv), (terminal) => {
+	if (kind !== "human") return Effect.succeed(false);
+	return Option.isSome(terminal) ? canPrompt(terminal.value) : Effect.succeed(current);
+});
+const CONFLICT = "Give at most one of --audience, --human, --agent, --ci (once).";
+/** Resolve the four flags into the audience to provide, failing when more than one occurrence was given. */
+const resolve = (input) => {
+	const { given: named, conflict } = tallyAudience(input);
+	if (conflict) return Effect.fail(new CliError.UserError({
+		cause: /* @__PURE__ */ new Error(CONFLICT),
+		userMessage: CONFLICT
+	}));
+	const [kind] = named;
+	return kind === void 0 ? Audience : Effect.succeed({
+		kind,
+		source: "flag"
+	});
+};
+/**
+* The audience flags of a CLI: `--audience <human|agent|ci>` and the shorthands `--human`, `--agent`, `--ci`,
+* resolved into `@effected/env`'s `Audience`.
+*
+* @remarks
+* The one wiring: share the flags on the root command and hand the root to {@link CliAudience.run} (or
+* {@link CliAudience.runWith}), which resolves the flags from argv before core parses and applies
+* {@link CliAudience.provide} itself:
+*
+* ```ts
+* const root = Command.make("tool").pipe(
+*   Command.withSharedFlags(CliAudience.flags()),
+*   Command.withSubcommands([verify]),
+* )
+* NodeRuntime.runMain(
+*   CliRuntime.main(CliAudience.run(root, { version }), { platform: NodeServices.layer, env: {} }),
+* )
+* ```
+*
+* Core lists a shared flag in the help of every subcommand, not only at the root: that is upstream (Effect-TS/effect
+* issue 8642), and `flags({ hidden: true })` is the way to keep them out of help altogether.
+*
+* A root that forgot `Command.withSharedFlags(CliAudience.flags())` does not compile. Giving more than one
+* occurrence across the four flags is a usage error even when they agree; a boolean set to false (`--no-agent`,
+* `--agent=false`) counts as not given. A bad `--audience` value is core's own parse error. Both exit `64` under
+* `CliRuntime.main`. A conflicting audience together with `--help` exits `0` and prints help, because core handles
+* its action flags before the resolver runs.
+*
+* A flag decides `CliInteractive` from the audience it names and the terminal facts: `--human` is interactive when
+* `TerminalEnv` says there is a terminal on stdin and on stdout, even where the environment detected an agent, so a
+* person running the tool inside an agent can ask for the human experience; in a pipe it still cannot prompt. A
+* non-human flag (`--agent`, `--ci`, `--audience agent|ci`) turns it off and drops `--wizard`, and switches
+* diagnostics to NDJSON, for the whole run including the parse step where a fallback prompt fires. Without
+* `TerminalEnv` in the environment a flag only narrows. `--wizard` follows the decision: a run a flag makes
+* interactive gets it back where the environment's gate had dropped it, and only there: a consumer's own `builtIns`
+* without it stay without it.
+* {@link CliAudience.provide} on its own, the path for a bare `Command.run`, acts only on the subcommand handler,
+* because core parses the root flags into a local context before any of it is visible.
+*
+* @public
+*/
+var CliAudience = class CliAudience {
+	constructor() {}
+	/**
+	* The four flags, for `Command.withSharedFlags` on the root command.
+	*
+	* @remarks
+	* Each is repeatable, so every occurrence is counted; a boolean given as `false` (`--agent=false`,
+	* `--no-agent`) is not an occurrence. Core lists shared flags in every command's help; pass
+	* `hidden` to remove them from all of them.
+	*/
+	static flags = (options) => {
+		const hide = options?.hidden === true;
+		const maybeHide = (flag) => hide ? Flag.withHidden(flag) : flag;
+		return {
+			audience: maybeHide(Flag.Literals("audience", KINDS).pipe(Flag.atLeast(0), Flag.withDescription("Who the output is for"))),
+			human: maybeHide(Flag.Boolean("human").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience human"))),
+			agent: maybeHide(Flag.Boolean("agent").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience agent"))),
+			ci: maybeHide(Flag.Boolean("ci").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience ci")))
+		};
+	};
+	/**
+	* Resolve the flags before every subcommand handler and re-provide `Audience`.
+	*
+	* @remarks
+	* `CliAudience.run` and `runWith` apply this themselves, so a program run through them never needs it. Use it
+	* directly only with a bare `Command.run`, which leaves a fallback prompt blind to the flags (see the class
+	* remarks).
+	*
+	* A failure report is written outside the run, where the flag is not in force, so only `runWith` and `run` carry
+	* the flag's audience to it; with this on its own the report follows the environment's audience.
+	*
+	* Pipe it onto the composite root, after `withSubcommands`, since a parent's handler does not run when a
+	* subcommand is selected. With exactly one flag the audience is `{ kind, source: "flag" }`; with none the
+	* ambient `Audience` is read and provided back unchanged, so `Audience` stays in the requirement a handler
+	* reading it already has, and is added to a program whose handlers do not read it.
+	*/
+	static provide = (command) => Command.provideEffect(command, Audience, (input) => resolve(input)).pipe(Command.provideEffect(CliInteractive, (input) => Effect.gen(function* () {
+		const current = yield* CliInteractive;
+		const [flagged] = tallyAudience(input).given;
+		return flagged === void 0 ? current : yield* interactiveWhenFlagged(flagged, current);
+	})));
+	/**
+	* Run a command the way `Command.runWith` does, with the audience flag resolved BEFORE core parses.
+	*
+	* @remarks
+	* It scans `argv` for the four audience flags first, then runs core around a provided `Audience` (when exactly
+	* one is given: `{ kind, source: "flag" }`) and a `CliInteractive` decided from it: `--human` is interactive when
+	* `TerminalEnv` reports a terminal on stdin and stdout and `TERM` is not `dumb` (it can turn prompting on under a detected agent), a
+	* non-human flag or a conflict makes it false. A fallback prompt fires while core parses, earlier than
+	* anything `CliAudience.provide` can reach, so `--agent init` on a terminal would otherwise still prompt. No
+	* flag leaves the ambient values untouched. A conflict still gets core's own usage error, exit `64`, from
+	* `CliAudience.provide`'s resolver.
+	*
+	* @param command - the composite root, with the flags shared and `CliAudience.provide` piped on
+	* @param config - the same `version` and `renderErrors` as core's
+	*/
+	static runWith = (command, config) => {
+		const core = Command.runWith(CliAudience.provide(command), config);
+		return (argv) => {
+			const run = core(argv);
+			const { given, conflict } = scanAudience(argv);
+			const [kind] = given;
+			if (kind === void 0) return run;
+			const withAudience = conflict ? run : Effect.provideService(run, Audience, {
+				kind,
+				source: "flag"
+			});
+			return Effect.gen(function* () {
+				const current = yield* CliInteractive;
+				const ambient = yield* CliConfig.CliConfig;
+				if (!conflict) yield* refreshFailureTarget({
+					kind,
+					source: "flag"
+				});
+				const interactive = !conflict && (yield* interactiveWhenFlagged(kind, current));
+				const decided = Effect.provideService(withAudience, CliInteractive, interactive);
+				const hasWizard = ambient.builtIns.includes(GlobalFlag.Wizard);
+				if (!(interactive && !hasWizard && (yield* WizardDropped) === ambient) && !(!interactive && hasWizard)) return yield* decided;
+				const builtIns = interactive ? [...ambient.builtIns, GlobalFlag.Wizard] : ambient.builtIns.filter((flag) => flag !== GlobalFlag.Wizard);
+				return yield* Effect.provideService(decided, CliConfig.CliConfig, CliConfig.make({ builtIns }));
+			});
+		};
+	};
+	/**
+	* `Command.run` with the audience flag resolved before parsing: reads `Stdio.args` and calls
+	* {@link CliAudience.runWith}.
+	*
+	* @param command - the composite root
+	* @param config - the same `version` and `renderErrors` as core's
+	*/
+	static run = (command, config) => Stdio.Stdio.use(({ args }) => Effect.flatMap(args, (argv) => CliAudience.runWith(command, config)(argv)));
+};
+
+export { CliAudience };

package/CliColor.js

@@ -0,0 +1,59 @@
+import { Effect, Layer } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { CliOutput } from "effect/cli";
+
+// src/CliColor.ts
+/**
+* Whether a CLI's output should carry ANSI colour, decided once and shared by
+* everything that renders — help text, error output, and any rendered result.
+*
+* @remarks
+* The decision is `@effected/env`'s `TerminalEnv.colorLevel("stdout")`, which
+* follows Node's `getColorDepth` precedence: `FORCE_COLOR` first (`0` or an
+* unrecognised value forces colour off; an empty value, `1` or `true` force basic colour, `2` 256 colours and
+* `3` truecolor, even without a terminal), then a non-empty `NO_COLOR` or `NODE_DISABLE_COLORS` and
+* `TERM=dumb`, then the TTY gate. `FORCE_COLOR` therefore beats `NO_COLOR`.
+* The environment
+* is read through the ambient `ConfigProvider`, never `process`, so a test
+* swaps it with `Effect.provideService(ConfigProvider.ConfigProvider, ...)`;
+* an ambient `TerminalEnv`, such as `TerminalEnv.layerTest`, answers instead
+* when one is provided.
+*
+* @public
+*/
+var CliColor = class CliColor {
+	constructor() {}
+	/**
+	* The decision, for passing to a pure renderer as a plain boolean.
+	*
+	* @public
+	*/
+	static enabled = TerminalEnv.colorLevel("stdout").pipe(Effect.map((level) => level !== "none"));
+	/**
+	* Core's default `CliOutput.Formatter`, coloured by the same decision as
+	* {@link CliColor.enabled}, so help text, parse errors and rendered
+	* output never disagree on whether colour is on.
+	*
+	* @remarks
+	* `overrides` replaces individual methods of the default formatter — for
+	* example `formatVersion`, to append a "via `<carrier>`" line without
+	* losing the other defaults. Each call mints a fresh layer; bind the
+	* result to a `const` or the decision is re-read every time it is
+	* provided.
+	*
+	* The `never` in its output does not mean it installs nothing.
+	* `CliOutput.Formatter` is a `Context.Reference`, whose key type is
+	* `never`, so this layer sets the formatter reference rather than
+	* providing a service. Every command it is provided to renders with the
+	* formatter it sets, and without it they fall back to core's default
+	* formatter.
+	*
+	* @public
+	*/
+	static formatterLayer = (overrides = {}) => Layer.unwrap(Effect.map(CliColor.enabled, (colors) => CliOutput.layer({
+		...CliOutput.defaultFormatter({ colors }),
+		...overrides
+	})));
+};
+
+export { CliColor };

package/CliEnv.js

@@ -0,0 +1,101 @@
+import { CliInteractive } from "./CliInteractive.js";
+import { ambientLinksLayer } from "./CliLinks.js";
+import { CliPrompt } from "./CliPrompt.js";
+import { CliTheme } from "./CliTheme.js";
+import { displayPathLayer } from "./internal/displayPath.js";
+import { capabilitiesLayer } from "./internal/terminalCapabilities.js";
+import { ConfigProvider, Layer, Option } from "effect";
+import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
+
+// src/CliEnv.ts
+/**
+* The environment services a CLI reads, built once and in the right order.
+*
+* @remarks
+* Builds `CurrentRuntimeEnv`, `TerminalEnv`, `Audience`, `CliTheme` and `CliLinks`, and sets `CliInteractive` from them, then
+* installs the two gates for the program: `CliPrompt.gateTerminal`, which replaces `Terminal` with a quiet one when
+* the run is not interactive so no prompt runner ever attaches to stdin, and `CliPrompt.gateWizard`, which drops
+* `--wizard` then. `TerminalEnv` is built from the real terminal first. The layer therefore also outputs
+* `Terminal`, the gated one, and consumers never compose the gates themselves. A
+* `Context.Reference`'s key type is `never`, so the layer's output type does not list `CliInteractive`: it sets
+* the reference rather than providing a service. Every read of the environment goes through `Config` and
+* degrades to "unset" when it fails, so building the layer does not fail on a bad provider; it fails only when
+* `Stdio` or `Terminal` do.
+*
+* `CliLinks` reads `FileSystem` and `Path` from the surrounding context if it has them, and does not require them: a
+* `.vscode/` directory is looked for, and a relative path resolved, only when the platform is provided OUTSIDE this
+* layer, as `CliRuntime.main` does. Without them `auto` is `vscode` on the terminal signal alone.
+*
+* Not interactive, the gated `Terminal`'s `readLine` fails as a quit, its input is already ended and its `display`
+* writes nothing. A program that reads piped data must read `Stdio.stdin`, and one that writes output must use
+* `Console` or `Stdio`, never `Terminal`. It also installs `CliTheme.promptTheme`, so core's prompts follow the
+* theme.
+*
+* It sets core's `TerminalCapabilities` from `TerminalEnv` (through `TerminalEnv.capabilities` in `@effected/env`), so
+* the colour of core's own help, version and error output follows the kit's colour rule, and `canAnimate` is stdout
+* being a terminal that is not `dumb`. `canPrompt` alone is held at `true` whatever the terminal is: core skips a
+* fallback prompt entirely when it is `false`, which would lose `CliPrompt.fallback`'s and `CliUi.fallback`'s
+* `otherwise` in every piped run, and `CliInteractive` with `CliPrompt.gateTerminal` already owns that decision (the
+* gate quits any other prompt at once when the run is not interactive). A `TerminalCapabilities` with
+* `canPrompt: false` provided inside the program bypasses the kit's fallbacks: the parameter then fails as missing even
+* when an `otherwise` is given.
+*
+* @public
+*/
+var CliEnv = class {
+	constructor() {}
+	/**
+	* The environment services for the terminal `Stdio` and `Terminal` describe.
+	*
+	* @remarks
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - the audience env var, the stderr check and the theme options
+	*/
+	static layer = (options = {}) => {
+		const base = Layer.mergeAll(CurrentRuntimeEnv.layer, TerminalEnv.layer(options.stderrIsTerminal === void 0 ? void 0 : { stderrIsTerminal: options.stderrIsTerminal }));
+		const withAudience = Audience.layer(options.audienceEnvVar === void 0 ? void 0 : { envVar: options.audienceEnvVar }).pipe(Layer.provideMerge(base));
+		const withTheme = CliTheme.layer(options.theme).pipe(Layer.provideMerge(withAudience));
+		const withLinks = ambientLinksLayer({
+			...options.editorLinks === void 0 ? {} : { editorLinks: options.editorLinks },
+			...options.editorLinksEnvVar === void 0 ? {} : { envVar: options.editorLinksEnvVar }
+		}).pipe(Layer.provideMerge(withTheme));
+		const withCapabilities = capabilitiesLayer.pipe(Layer.provideMerge(withLinks));
+		const withInteractive = CliInteractive.layer.pipe(Layer.provideMerge(withCapabilities));
+		return Layer.mergeAll(CliPrompt.gateTerminal, CliPrompt.gateWizard, CliTheme.promptTheme, displayPathLayer(options.displayPath)).pipe(Layer.provideMerge(withInteractive));
+	};
+	/**
+	* The environment services a test fixes, needing nothing and reading nothing of the host's: `TerminalEnv` and
+	* `Audience` from the answers given, `CliTheme` built from them as {@link CliEnv.layer} builds it, and
+	* `CliInteractive` set from them by the same rule (a human, every stream a terminal, and a `TERM` that is not
+	* `dumb`), and core's `TerminalCapabilities` from them as `CliEnv.layer` sets it, `canPrompt` held at `true`.
+	*
+	* @remarks
+	* `term` is handed to the theme and interactivity builds alone, through a `ConfigProvider` of their own: the
+	* program under the layer keeps its own provider, and a host's `TERM` (a test runner in a dumb terminal) never
+	* decides. A screen or a live view also needs `UiStreams` from `@effected/cli-kit/ui`, which `CliUiTest` provides; this
+	* layer provides no `Terminal` and installs neither of `CliEnv.layer`'s prompt gates.
+	*
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - whether the streams are terminals, the `TERM`, the audience, the width, the colour and the theme
+	*/
+	static layerTest = (options = {}) => {
+		const tty = options.tty ?? false;
+		const stream = {
+			isTerminal: tty,
+			color: options.color ?? "none",
+			columns: options.columns === void 0 ? Option.none() : Option.some(options.columns)
+		};
+		const facts = Layer.mergeAll(TerminalEnv.layerTest({
+			stdinIsTerminal: tty,
+			stdout: stream,
+			stderr: stream
+		}), Audience.layerTest(options.audience ?? "human"));
+		const term = ConfigProvider.layer(ConfigProvider.fromUnknown(options.term === void 0 ? {} : { TERM: options.term }));
+		const interactive = CliInteractive.layer.pipe(Layer.provideMerge(capabilitiesLayer));
+		return Layer.mergeAll(CliTheme.layer(options.theme), interactive).pipe(Layer.provide(term), Layer.provideMerge(facts));
+	};
+};
+
+export { CliEnv };

package/CliExit.js

@@ -0,0 +1,64 @@
+import { isExitCode } from "./internal/isExitCode.js";
+import { Context, Effect, Layer, MutableRef } from "effect";
+
+// src/CliExit.ts
+/**
+* The exit code a successful run wants, for commands whose findings are a
+* result rather than a failure (a linter that found problems, say).
+*
+* @remarks
+* Findings are not a failure — a JSON `tapError` must not fire, and the
+* handler must return normally — yet the process must exit non-zero. Writing
+* `process.exitCode` works only because Node's `runMain` skips
+* `process.exit(0)` on success; `process.exit(n)` in a handler skips every
+* finalizer. `CliRuntime.main` reads this cell after the program
+* succeeds and turns a non-zero code into a marked failure the runtime's
+* teardown honours, on any runtime, with finalizers intact.
+*
+* A `Service`, not a `Reference`: forgetting `CliRuntime.main` is a type error,
+* never a silently ignored global.
+*
+* @public
+*/
+var CliExit = class CliExit extends Context.Service()("@effected/cli-kit/CliExit") {
+	/**
+	* A fresh cell at `0`; `CliRuntime.main` provides it, and tests provide it
+	* directly.
+	*
+	* @remarks
+	* Every provide mints a new cell. Layers memoize by reference across
+	* `Effect.provide` calls, so without `Layer.fresh` a second provide of this
+	* layer anywhere in the program — a nested `CliRuntime.main`, a test
+	* helper — would silently share the first run's cell and inherit its code.
+	*
+	* A program run under `CliRuntime.main` must NOT provide `CliExit.layer`
+	* itself: `main` already provides one, and a second provide mints a second,
+	* unrelated cell that `main` never reads back, so `CliExit.set` calls made
+	* against it are silently discarded and the run exits `0`.
+	*/
+	static layer = Layer.fresh(Layer.sync(this, () => ({ code: MutableRef.make(0) })));
+	/**
+	* Record an exit code; the highest code set during the run wins.
+	*
+	* @remarks
+	* Highest-wins, not last-wins, so a later "clean" step cannot quietly
+	* downgrade an earlier finding's code.
+	*
+	* The code must be an integer in `0..255` — the range a POSIX exit status
+	* can carry. Anything else dies as a defect naming the value: `256` would
+	* wrap to exit `0` and silently pass a run with findings, and a fraction
+	* such as `1.5` makes `process.exit` throw `ERR_OUT_OF_RANGE` after the
+	* program has finished.
+	*
+	* The code only applies to a run that **succeeds**. A program failure beats
+	* findings: when the program fails, `CliRuntime.main` never reads this
+	* cell, and the failure's own exit code (or the `exitCode` fallback) wins.
+	*/
+	static set = (code) => Effect.gen(function* () {
+		if (!isExitCode(code)) return yield* Effect.die(/* @__PURE__ */ new Error(`CliExit.set: exit code must be an integer 0..255, received ${code}`));
+		const exit = yield* CliExit;
+		if (code > MutableRef.get(exit.code)) MutableRef.set(exit.code, code);
+	});
+};
+
+export { CliExit };