@effected/cli-kit 0.0.0-stage → 0.27.0

package/package.json

@@ -1,6 +1,88 @@
 {
-  "name": "@effected/cli-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/cli-kit",
+	"version": "0.27.0",
+	"private": false,
+	"description": "The presentation boundary of an effect/cli program: audience-aware output, a document IR and renderers, editor links, failure reports and logging, plus opt-in Ink screens, widgets and a live view",
+	"keywords": [
+		"effect",
+		"cli",
+		"logger",
+		"terminal",
+		"ink",
+		"tui"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/cli-kit#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/cli-kit"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
+		"./ui": {
+			"types": "./ui.d.ts",
+			"import": "./ui.js",
+			"default": "./ui.js"
+		},
+		"./ui/testing": {
+			"types": "./ui-testing.d.ts",
+			"import": "./ui-testing.js",
+			"default": "./ui-testing.js"
+		},
+		"./ui/testing/serializer": {
+			"types": "./ui-testing-serializer.d.ts",
+			"import": "./ui-testing-serializer.js",
+			"default": "./ui-testing-serializer.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effected/commands": "^0.20.0",
+		"@effected/github-commands": "^0.9.0",
+		"@effected/kit": "^0.13.0",
+		"@effected/source": "^0.4.0"
+	},
+	"peerDependencies": {
+		"@effected/env": "^0.11.0",
+		"@effected/glob": "^0.19.0",
+		"@effected/walker": "^0.25.1",
+		"@types/react": "^19.3.0",
+		"effect": "~4.1.0",
+		"ink": "^8.0.0",
+		"react": "^19.3.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/react": {
+			"optional": true
+		},
+		"ink": {
+			"optional": true
+		},
+		"react": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/testing.d.ts

@@ -0,0 +1,283 @@
+import { Duration, Effect, FileSystem, Layer, Path, PlatformError, Schema, Scope, Stream, Terminal } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+/**
+ * A hermetic temp directory minted by {@link CliTest.sandbox}, removed when its
+ * scope closes.
+ *
+ * @public
+ */
+interface Sandbox {
+  /** The temp directory itself; the default working directory of {@link CliTest.run}. */
+  readonly root: string;
+  /** The fresh `HOME` inside `root`; the XDG base directories live under it. */
+  readonly home: string;
+  /**
+   * The complete child environment: `HOME`, the four `XDG_*_HOME` variables,
+   * the injected `PATH` and `NO_COLOR=1`. Nothing is inherited from the host.
+   */
+  readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * How {@link CliTest.run} spawns a bin.
+ *
+ * @public
+ */
+interface RunOptions {
+  /** The sandbox whose environment and root the child runs in. */
+  readonly sandbox: Sandbox;
+  /** The node binary — pass `process.execPath` from the test file, never a PATH lookup. */
+  readonly execPath: string;
+  /** The child's working directory. Defaults to the sandbox `root`. */
+  readonly cwd?: string | undefined;
+  /**
+   * Extra environment variables, merged over the sandbox environment — the
+   * way to override `PATH` for one run.
+   */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Text written to the child's stdin, which is then closed. Omitted or `""`,
+   * the child gets an already-ended empty input, never an open pipe.
+   */
+  readonly stdin?: string | undefined;
+  /**
+   * How long a child has to exit after `SIGTERM` (or the signal `kill` sends), when its scope closes or
+   * {@link SpawnedBin.kill} is called, before it is sent `SIGKILL`; `2 seconds` by default. A finite duration: a
+   * child that ignores the signal would otherwise keep the scope from closing forever, and leave the process behind.
+   */
+  readonly forceKillAfter?: Duration.Input | undefined;
+  /**
+   * The exit code the run must end with. Any other ending, a signal included, fails with a {@link CliTestFailure}
+   * carrying the code, the signal and the child's stderr in its message. Omitted, a non-zero exit is data.
+   */
+  readonly expectExit?: number | undefined;
+}
+declare const CliTestFailure_base: Schema.Class<CliTestFailure, Schema.TaggedStruct<"CliTestFailure", {
+  readonly expected: Schema.Number;
+  readonly exitCode: Schema.NullOr<Schema.Number>;
+  readonly signal: Schema.NullOr<Schema.String>;
+  readonly stderr: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A run ended otherwise than {@link RunOptions.expectExit} required.
+ *
+ * @remarks
+ * Audience: the person reading a failed test. The message holds what the child did and its stderr, so a suite that
+ * only cares about the happy path needs no hand-rolled helper to see why it did not get it.
+ *
+ * @public
+ */
+export declare class CliTestFailure extends CliTestFailure_base {
+  /**
+   * What was expected, what happened, and the child's stderr.
+   *
+   * @remarks
+   * Assigning to it is ignored: a runner or logger that rewrites `error.message` must not make this error throw,
+   * which a getter-only property does in strict mode.
+   */
+  get message(): string;
+  set message(_value: string);
+}
+/**
+ * What a spawned bin did, as data: a non-zero exit is a result, not a failure.
+ *
+ * @public
+ */
+interface RunResult {
+  /** The child's exit code, or `null` when a signal ended it. */
+  readonly exitCode: number | null;
+  /** The signal that ended the child, or `null` when it exited with a code. */
+  readonly signal: ChildProcess.Signal | null;
+  /** Everything the child wrote to stdout, decoded as UTF-8. */
+  readonly stdout: string;
+  /** Everything the child wrote to stderr, decoded as UTF-8. */
+  readonly stderr: string;
+}
+/**
+ * A bin {@link CliTest.spawn} started and has not waited for: its output as it arrives, a way to signal it, and its
+ * exit.
+ *
+ * @public
+ */
+interface SpawnedBin {
+  /**
+   * The child's stdout as lines, each without its line break (`\r\n` included), from the first byte it wrote,
+   * ending when the child closes stdout; a last line with no line break comes when it does. Every subscription replays
+   * from the start, so a test may read it more than once, and output a test never reads is still drained, so the
+   * child never blocks on a full pipe.
+   */
+  readonly stdout: Stream.Stream<string>;
+  /** The child's stderr as lines, as `stdout` gives stdout. */
+  readonly stderr: Stream.Stream<string>;
+  /**
+   * Send `signal` (`SIGTERM` by default) and wait for the child to exit. A child still running after
+   * {@link RunOptions.forceKillAfter} is sent `SIGKILL`, so this always ends. A child that has already exited, on its
+   * own or at the same moment, is not an error: this returns normally, and `exitCode` and `result` keep reporting how
+   * it ended. A kill that fails on a child still running fails with that `PlatformError`.
+   */
+  readonly kill: (signal?: ChildProcess.Signal) => Effect.Effect<void, PlatformError.PlatformError>;
+  /**
+   * The child's exit code once it exits, or `null` when a signal ended it (the default `kill` included): `result`
+   * names the signal. Re-reading it after the exit answers at once.
+   */
+  readonly exitCode: Effect.Effect<number | null, PlatformError.PlatformError>;
+  /** Wait for the exit and the end of both streams, and read everything, as {@link CliTest.run} returns it. */
+  readonly result: Effect.Effect<RunResult, PlatformError.PlatformError>;
+}
+/**
+ * Spawn a built CLI bin hermetically and read its exit code and streams as data.
+ *
+ * @example
+ * ```ts
+ * import * as NodeServices from "@effect/platform-node/NodeServices"
+ * import { assert, it } from "@effect/vitest"
+ * import { CliTest } from "@effected/cli-kit/testing"
+ * import { Effect } from "effect"
+ *
+ * it.effect("prints its version", () =>
+ *   Effect.gen(function* () {
+ *     const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" })
+ *     const result = yield* CliTest.run("dist/bin.js", ["--version"], { sandbox, execPath: process.execPath })
+ *     assert.strictEqual(result.exitCode, 0)
+ *   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class CliTest {
+  private constructor();
+  /**
+   * A scoped temp directory with a fresh `HOME` and XDG tree, `NO_COLOR=1`,
+   * and the `PATH` you pass — the host environment is never inherited.
+   *
+   * @remarks
+   * Each call mints a fresh temp directory; bind the result to a `const`
+   * within one test rather than calling this more than once per assertion.
+   */
+  static readonly sandbox: (options: {
+    /**
+     * The `PATH` the child sees, passed explicitly because nothing else is
+     * inherited — `process.env.PATH` when the bin shells out to host tools,
+     * a narrower list to prove it does not.
+     */
+    readonly path: string;
+  }) => Effect.Effect<Sandbox, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
+  /**
+   * Run `execPath bin ...args`; a non-zero exit is returned, never failed, unless `expectExit` is set.
+   *
+   * @remarks
+   * `stdin` is never left as an inherited open pipe: when omitted or `""`
+   * the child gets an already-ended empty input (`Stream.empty`), so a
+   * stdin-reading bin exits instead of hanging on `effect/process`'s
+   * default `"pipe"` stdio, which stays open until something writes to and
+   * ends it.
+   */
+  static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError | CliTestFailure, ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * Start `execPath bin ...args` and return at once with a handle on it: its output as lines while it runs, a signal,
+   * and its exit, for a long-running command (a `--follow`, a watch mode, a server) that {@link CliTest.run} would wait
+   * on forever.
+   *
+   * @remarks
+   * The child lives in the caller's scope: when the scope closes first, the child is sent `SIGTERM`, then `SIGKILL`
+   * after `forceKillAfter` (`2 seconds` by default), so a test that ends early leaves nothing running and never waits
+   * on a child that ignores the signal. A child a signal ended reports `exitCode: null` and the signal in `result`. Both streams are drained from the start whether or not the test reads them, so a
+   * chatty child never blocks on a full pipe, and each stream replays from its first line to every reader. The
+   * options are {@link CliTest.run}'s, `stdin` included: the child gets that text, then an ended input.
+   *
+   * ```ts
+   * const child = yield* CliTest.spawn("dist/bin.js", ["logs", "--follow"], { sandbox, execPath: process.execPath })
+   * yield* Stream.runHead(child.stdout) // the first line: it is following
+   * yield* child.kill("SIGINT")
+   * assert.strictEqual(yield* child.exitCode, 0)
+   * ```
+   *
+   * @param bin - the built bin to run
+   * @param args - its arguments
+   * @param options - the sandbox, the node binary, and the working directory, environment and stdin
+   */
+  static readonly spawn: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<SpawnedBin, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
+}
+/**
+ * One key press for {@link TestTerminal}.
+ *
+ * @public
+ */
+interface KeyInput {
+  /** The key name the prompts switch on: `down`, `up`, `enter`, `space`, `escape`, or a character. */
+  readonly name: string;
+  /** Whether Ctrl is held. */
+  readonly ctrl?: boolean | undefined;
+  /** Whether Meta is held. */
+  readonly meta?: boolean | undefined;
+  /** Whether Shift is held. */
+  readonly shift?: boolean | undefined;
+}
+/**
+ * What {@link TestTerminal.make} builds: the `Terminal` layer and the means to drive and inspect it.
+ *
+ * @public
+ */
+interface TestTerminalHandle {
+  /** Provides `Terminal` backed by this double. */
+  readonly layer: Layer.Layer<Terminal.Terminal>;
+  /** Queue key presses, as if the user had typed them. */
+  readonly input: (keys: ReadonlyArray<KeyInput>) => Effect.Effect<void>;
+  /** Queue `text` one character at a time. */
+  readonly type: (text: string) => Effect.Effect<void>;
+  /** End the input, as Ctrl-C or end-of-file does: a prompt waiting for a key is quit. */
+  readonly end: Effect.Effect<void>;
+  /** Everything written to the terminal so far, prompt frames and escape codes included. */
+  readonly output: Effect.Effect<string>;
+  /**
+   * Resize the terminal: `columns` and `rows` report the new size from now on, and every open `size`
+   * subscription receives it.
+   */
+  readonly resize: (size: Terminal.Size) => Effect.Effect<void>;
+  /** How many queued key presses nobody has taken yet. */
+  readonly pending: Effect.Effect<number>;
+  /**
+   * What the program did with the input: `keys` taken from it, `lines` read with `readLine`, and
+   * `subscriptions` to `readInput`. All `0` proves a code path never touched the terminal's input. Counting the
+   * subscription matters: on a real terminal merely subscribing attaches a reader to stdin, even when no key is
+   * ever taken.
+   */
+  readonly reads: Effect.Effect<{
+    readonly keys: number;
+    readonly lines: number;
+    readonly subscriptions: number;
+  }>;
+}
+/**
+ * A scripted `Terminal` for testing prompts and anything that reads the terminal.
+ *
+ * @remarks
+ * Queue keys with `input` or `type`, run the program under `layer`, then read `output`. `size` behaves as a real
+ * terminal's does: each subscription starts with the current size, receives every `resize`, keeps only the latest,
+ * and ends when its scope closes. To assert that a code path
+ * did NOT touch the terminal, queue some keys first and check `reads` is all zero (no subscription, no key, no
+ * line) and `pending` is unchanged afterwards. Only
+ * available from `@effected/cli-kit/testing`.
+ *
+ * @public
+ */
+export declare class TestTerminal {
+  private constructor();
+  /**
+   * Build a test terminal.
+   *
+   * @remarks
+   * With `forbidInput`, `readInput` and `readLine` die with a message saying this path must not read the terminal,
+   * where the default double hands back an empty queue (a stray read hangs) and quits `readLine`. `size`, `columns`,
+   * `rows`, `display` and `resize` behave as ever, so a "this path never prompts" platform keeps a real terminal size.
+   *
+   * @param options - the reported size, 80 by 24 by default; `forbidInput` to die on any input read
+   */
+  static readonly make: (options?: {
+    readonly columns?: number | undefined;
+    readonly rows?: number | undefined;
+    readonly forbidInput?: boolean | undefined;
+  }) => Effect.Effect<TestTerminalHandle>;
+}
+export type { KeyInput, RunOptions, RunResult, Sandbox, SpawnedBin, TestTerminalHandle };
+//# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -0,0 +1,4 @@
+import { CliTest, CliTestFailure } from "./CliTest.js";
+import { TestTerminal } from "./TestTerminal.js";
+
+export { CliTest, CliTestFailure, TestTerminal };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.60.1"
+    }
+  ]
+}