runtime-resolver 0.3.22 → 1.0.1

package/README.md

@@ -1,63 +1,62 @@
 # runtime-resolver
 
-[![npm version](https://img.shields.io/npm/v/runtime-resolver)](https://www.npmjs.com/package/runtime-resolver)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Effect](https://img.shields.io/badge/Effect-3.x-6644CC)](https://effect.website/)
+[![npm](https://img.shields.io/npm/v/runtime-resolver?label=npm&color=cb3837)](https://www.npmjs.com/package/runtime-resolver)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![Effect](https://img.shields.io/badge/Effect-4.x-6644CC)](https://effect.website/)
 
-Resolve semver-compatible versions of Node.js, Bun and Deno runtimes. Fetches available versions from GitHub with automatic offline fallback via a build-time cache.
+A command-line tool that resolves semver-compatible versions of Node.js, Bun, and Deno runtimes and prints them as JSON. It fetches live version data with an automatic fallback to a bundled offline snapshot, so it keeps working in CI and air-gapped environments.
 
 ## Features
 
-- Resolve matching versions for Node.js, Bun and Deno with a single call
-- Filter Node.js results by release phase (current, active-lts, maintenance-lts)
-- Control version granularity with increment levels (latest, minor, patch) for all runtimes
-- Track data provenance with the `source` field (`"api"` or `"cache"`)
-- Offline fallback using bundled version data when GitHub is unreachable
-- CLI with structured JSON output for CI/CD pipelines
-- Full Effect API for custom layer composition and typed error handling
+- Resolve matching versions for Node.js, Bun, and Deno in a single call.
+- Filter Node.js results by release phase (current, active-lts, maintenance-lts, end-of-life).
+- Control version granularity with increment levels (latest, minor, patch) across every runtime.
+- Track data provenance with the `source` field (`"api"` for a live fetch, `"cache"` for the offline snapshot).
+- Fall back to a bundled offline snapshot when the network or GitHub API is unavailable.
+- Emit structured JSON that pairs cleanly with `jq` for CI/CD version matrices.
 
-## Installation
+## Install
 
 ```bash
-npm install runtime-resolver
+npm install -g runtime-resolver
 ```
 
-The Effect packages (`effect`, `@effect/cli`, `@effect/platform`, `@effect/platform-node`) are declared as peer dependencies. npm 7+ and pnpm auto-install them by default. If you already use Effect in your project, your existing versions will be reused.
+Or run it on demand without installing:
 
-## Quick Start
-
-```typescript
-import { resolveNode, resolveBun, resolveDeno } from "runtime-resolver";
-
-const node = await resolveNode({ semverRange: ">=20" });
-console.log(node.latest);  // e.g. "22.14.0"
-console.log(node.source);  // "api" or "cache"
-console.log(node.default); // latest LTS version
-
-const bun = await resolveBun({ semverRange: ">=1.1", increments: "minor" });
-const deno = await resolveDeno({ semverRange: ">=2", increments: "minor" });
+```bash
+npx runtime-resolver --node ">=20"
 ```
 
-Set a `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variable for authenticated requests. Without one, the resolver falls back to cached data.
+The runtime dependencies (`effect`, `@effected/runtimes`, `@effected/semver`) install automatically — there are no peer dependencies to add by hand. Requires Node.js >=24.11.0.
 
-### CLI
+## Quick start
 
 ```bash
-npx runtime-resolver --node ">=22" --bun "^1" --deno ">=2" --pretty
+npx runtime-resolver --node ">=20"
+# {"source":"api","versions":["22.14.0","20.19.0"],"latest":"22.14.0","lts":"20.19.0","default":"20.19.0"}
 ```
 
-Output is structured JSON with a `$schema` reference for editor auto-complete. Print the full schema with `--schema`:
+Request several runtimes at once and the output becomes an object keyed by runtime name:
 
 ```bash
-npx runtime-resolver --schema
+npx runtime-resolver --node ">=20" --bun ">=1" --deno ">=2" --pretty
+# {
+#   "node": { "source": "api", "versions": ["22.14.0"], "latest": "22.14.0", "lts": "20.19.0", "default": "20.19.0" },
+#   "bun":  { "source": "api", "versions": ["1.1.42"], "latest": "1.1.42" },
+#   "deno": { "source": "api", "versions": ["2.1.4"], "latest": "2.1.4" }
+# }
 ```
 
+The CLI exits `0` when every requested runtime resolves. A usage error or resolution failure writes a one-line `error: …` to stderr and exits non-zero, so scripts can branch on the exit status.
+
 ## Documentation
 
-For configuration, API reference, and advanced usage, see [docs](./docs/).
+- [CLI reference](../docs/cli.md) — flags, output format, exit codes, jq recipes, and scripting.
+- [GitHub authentication and rate limits](../docs/github.md) — why Bun and Deno need a token, rate limits, token detection order, offline fallback, and the GitHub Actions matrix example.
+
+See [docs](../docs/) for the full guide index.
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](LICENSE)

package/bin/runtime-resolver.js

@@ -1,37 +1,18 @@
 #!/usr/bin/env node
-import { appIdOption, appInstallationIdOption, appPrivateKeyOption, bunDefaultOption, bunOption, denoDefaultOption, denoOption, incrementsOption, nodeDateOption, nodeDefaultOption, nodeOption, nodePhasesOption, prettyOption, resolveHandler, schemaOption, tokenOption } from "../cli/commands/resolve.js";
-import { Cause, Console, Effect } from "effect";
-import { Command } from "@effect/cli";
-import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { NodeCliEnvironment } from "../layers.js";
+import { cli } from "../command.js";
+import { failureMessage } from "../report.js";
+import { Effect, Exit } from "effect";
+import { Command } from "effect/unstable/cli";
 
 //#region src/cli/index.ts
-/* v8 ignore start - CLI entry point requires integration testing */
-const rootCommand = Command.make("runtime-resolver", {
-	node: nodeOption,
-	bun: bunOption,
-	deno: denoOption,
-	nodePhases: nodePhasesOption,
-	increments: incrementsOption,
-	nodeDefault: nodeDefaultOption,
-	bunDefault: bunDefaultOption,
-	denoDefault: denoDefaultOption,
-	nodeDate: nodeDateOption,
-	pretty: prettyOption,
-	schema: schemaOption,
-	token: tokenOption,
-	appId: appIdOption,
-	appPrivateKey: appPrivateKeyOption,
-	appInstallationId: appInstallationIdOption
-}, resolveHandler);
-const cli = Command.run(rootCommand, {
-	name: "runtime-resolver",
-	version: "0.3.22"
-});
-const main = Effect.suspend(() => cli(process.argv)).pipe(Effect.provide(NodeContext.layer), Effect.catchAllCause((cause) => {
-	if (Cause.defects(cause).length > 0) return Console.error(Cause.pretty(cause)).pipe(Effect.andThen(Effect.failCause(cause)));
-	return Effect.failCause(cause);
-}));
-NodeRuntime.runMain(main);
+const program = Command.runWith(cli, { version: "1.0.1" })(process.argv.slice(2)).pipe(Effect.provide(NodeCliEnvironment));
+const exit = await Effect.runPromiseExit(program);
+if (Exit.isFailure(exit)) {
+	process.exitCode = 1;
+	const message = failureMessage(exit.cause);
+	if (message !== null) process.stderr.write(`${message}\n`);
+}
 
 //#endregion
 export {  };

package/command.js

@@ -0,0 +1,120 @@
+import { selectResolverLayers } from "./layers.js";
+import { NODE_PHASES, formatOutput, parsePhases } from "./output.js";
+import { Console, DateTime, Effect, Option, Result } from "effect";
+import { CliError, Command, Flag } from "effect/unstable/cli";
+import { BunResolver, DenoResolver, NodeResolver } from "@effected/runtimes";
+
+//#region src/cli/command.ts
+/**
+* Turn a resolver's typed failure into the one-line, operator-facing message
+* the process prints to stderr before exiting non-zero.
+*/
+const describeResolveError = (runtime, error) => {
+	switch (error._tag) {
+		case "InvalidRangeError": return `invalid ${runtime} range: ${error.message}`;
+		case "NoMatchingVersionError": {
+			const scope = error.phases !== void 0 ? ` within phase(s) ${error.phases.join(", ")}` : "";
+			return `no ${runtime} version matched "${error.constraint}"${scope}`;
+		}
+		case "UnresolvableDefaultError": return `no ${runtime} version matched the requested default "${error.defaultVersion}"`;
+	}
+};
+/**
+* Resolve one runtime: run its resolver effect, map any typed resolution
+* failure to a user-facing CLI error, and provide the runtime's chosen layer.
+* Extracted so the node/bun/deno branches share one resolve/map/provide shape.
+*/
+const resolveRuntime = (runtime, resolve, layer) => resolve.pipe(Effect.mapError((error) => new CliError.UserError({ cause: describeResolveError(runtime, error) })), Effect.provide(layer));
+/** Fail with the CLI framework's user-error, carrying an already-formatted message. */
+const usageError = (message) => Effect.fail(new CliError.UserError({ cause: message }));
+const nodeFlag = Flag.optional(Flag.string("node").pipe(Flag.withDescription("Resolve Node.js versions for this semver range")));
+const bunFlag = Flag.optional(Flag.string("bun").pipe(Flag.withDescription("Resolve Bun versions for this semver range")));
+const denoFlag = Flag.optional(Flag.string("deno").pipe(Flag.withDescription("Resolve Deno versions for this semver range")));
+const nodePhasesFlag = Flag.optional(Flag.string("node-phases").pipe(Flag.withDescription(`Comma-separated Node lifecycle phases (${NODE_PHASES.join(", ")})`)));
+const incrementsFlag = Flag.optional(Flag.choice("increments", [
+	"latest",
+	"minor",
+	"patch"
+]).pipe(Flag.withDescription("Grouping granularity applied to every requested runtime")));
+const nodeDefaultFlag = Flag.optional(Flag.string("node-default").pipe(Flag.withDescription("Range whose newest Node match becomes the `default` field")));
+const bunDefaultFlag = Flag.optional(Flag.string("bun-default").pipe(Flag.withDescription("Range whose newest Bun match becomes the `default` field")));
+const denoDefaultFlag = Flag.optional(Flag.string("deno-default").pipe(Flag.withDescription("Range whose newest Deno match becomes the `default` field")));
+const nodeDateFlag = Flag.optional(Flag.date("node-date").pipe(Flag.withDescription("ISO date at which to evaluate Node lifecycle phases")));
+const prettyFlag = Flag.boolean("pretty").pipe(Flag.withDescription("Pretty-print the JSON output with 2-space indentation"));
+const offlineFlag = Flag.boolean("offline").pipe(Flag.withDescription("Resolve from the bundled snapshot only; make no network requests"));
+const tokenFlag = Flag.optional(Flag.redacted("token").pipe(Flag.withDescription("GitHub personal access token used for Bun and Deno lookups")));
+/**
+* Build the `runtime-resolver` command around a resolver-layer selector.
+*
+* The selector is called once per run with the parsed `--offline` flag to pick
+* the layer set (live feeds, or the snapshot-only `.layerOffline`). Each
+* runtime's chosen layer is provided *inside* its flag-gated branch and nowhere
+* else, so an unrequested runtime's layer is never built — and, because the
+* kit's live `.layer` fetches its feed at acquisition, never touches the
+* network. Parameterizing the selector is also what lets tests inject
+* `.layerOffline` (or a tripwire that dies if built).
+*/
+const makeCli = (selectLayers) => Command.make("runtime-resolver", {
+	node: nodeFlag,
+	bun: bunFlag,
+	deno: denoFlag,
+	nodePhases: nodePhasesFlag,
+	increments: incrementsFlag,
+	nodeDefault: nodeDefaultFlag,
+	bunDefault: bunDefaultFlag,
+	denoDefault: denoDefaultFlag,
+	nodeDate: nodeDateFlag,
+	pretty: prettyFlag,
+	offline: offlineFlag,
+	token: tokenFlag
+}, (config) => Effect.gen(function* () {
+	if (Option.isNone(config.node) && Option.isNone(config.bun) && Option.isNone(config.deno)) return yield* usageError("no runtime requested; pass at least one of --node, --bun, --deno");
+	const layers = selectLayers(config.offline);
+	let phases;
+	if (Option.isSome(config.nodePhases)) {
+		const parsed = parsePhases(config.nodePhases.value);
+		if (Result.isFailure(parsed)) return yield* usageError(parsed.failure);
+		phases = parsed.success;
+	}
+	const increments = Option.getOrUndefined(config.increments);
+	const nodeDate = Option.isSome(config.nodeDate) ? DateTime.fromDateUnsafe(config.nodeDate.value) : void 0;
+	const entries = [];
+	if (Option.isSome(config.node)) {
+		const range = config.node.value;
+		const defaultVersion = Option.getOrUndefined(config.nodeDefault);
+		const resolved = yield* resolveRuntime("node", Effect.flatMap(NodeResolver, (resolver) => resolver.resolve({
+			range,
+			...phases !== void 0 ? { phases } : {},
+			...increments !== void 0 ? { increments } : {},
+			...defaultVersion !== void 0 ? { defaultVersion } : {},
+			...nodeDate !== void 0 ? { date: nodeDate } : {}
+		})), layers.node);
+		entries.push(["node", resolved]);
+	}
+	if (Option.isSome(config.bun)) {
+		const range = config.bun.value;
+		const defaultVersion = Option.getOrUndefined(config.bunDefault);
+		const resolved = yield* resolveRuntime("bun", Effect.flatMap(BunResolver, (resolver) => resolver.resolve({
+			range,
+			...increments !== void 0 ? { increments } : {},
+			...defaultVersion !== void 0 ? { defaultVersion } : {}
+		})), layers.bun(config.token));
+		entries.push(["bun", resolved]);
+	}
+	if (Option.isSome(config.deno)) {
+		const range = config.deno.value;
+		const defaultVersion = Option.getOrUndefined(config.denoDefault);
+		const resolved = yield* resolveRuntime("deno", Effect.flatMap(DenoResolver, (resolver) => resolver.resolve({
+			range,
+			...increments !== void 0 ? { increments } : {},
+			...defaultVersion !== void 0 ? { defaultVersion } : {}
+		})), layers.deno(config.token));
+		entries.push(["deno", resolved]);
+	}
+	yield* Console.log(formatOutput(entries, config.pretty));
+}));
+/** The production command: `--offline` selects snapshot-only layers, else live. */
+const cli = makeCli(selectResolverLayers);
+
+//#endregion
+export { cli, makeCli };

package/layers.js

@@ -0,0 +1,61 @@
+import { Effect, FileSystem, Layer, Option, Path, Stdio, Terminal } from "effect";
+import { BunResolver, DenoResolver, GitHubAuth, GitHubClient, NodeResolver } from "@effected/runtimes";
+import { FetchHttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+//#region src/cli/layers.ts
+/**
+* The `fetch`-backed HTTP client, bound to one constant so every resolver layer
+* shares the same reference and the runtime memoizes it to a single build.
+*/
+const httpClient = FetchHttpClient.layer;
+/**
+* Choose the GitHub credential wiring.
+*
+* With `--token`, authenticate with the supplied PAT over `fetch`. Without one,
+* `GitHubClient.layerDefault` pre-wires environment-detected auth
+* (`GITHUB_PERSONAL_ACCESS_TOKEN` → `GITHUB_TOKEN` → anonymous) over `fetch`.
+*/
+const githubClientFor = (token) => Option.match(token, {
+	onNone: () => GitHubClient.layerDefault,
+	onSome: (pat) => GitHubClient.layer.pipe(Layer.provide(Layer.mergeAll(GitHubAuth.token(pat), httpClient)))
+});
+/**
+* The live resolver layers: real feeds over `fetch`, with the kit's snapshot
+* fallback. Each is built only when its runtime's branch runs.
+*/
+const liveResolverLayers = {
+	node: NodeResolver.layer.pipe(Layer.provide(httpClient)),
+	bun: (token) => BunResolver.layer.pipe(Layer.provide(githubClientFor(token))),
+	deno: (token) => DenoResolver.layer.pipe(Layer.provide(githubClientFor(token)))
+};
+/**
+* The snapshot-only resolver layers used by `--offline`: the kit's
+* `.layerOffline`, which performs no IO, requires nothing, and needs no token.
+* Every answer is `source: "cache"`.
+*/
+const offlineResolverLayers = {
+	node: NodeResolver.layerOffline,
+	bun: () => BunResolver.layerOffline,
+	deno: () => DenoResolver.layerOffline
+};
+/** Pick the resolver layer set for a run: snapshot-only when `--offline`, else live. */
+const selectResolverLayers = (offline) => offline ? offlineResolverLayers : liveResolverLayers;
+/** A `Terminal` that dies if any member is touched — this CLI is non-interactive. */
+const deadTerminal = Terminal.make({
+	columns: Effect.die("terminal is not available in runtime-resolver"),
+	rows: Effect.die("terminal is not available in runtime-resolver"),
+	readInput: Effect.die("terminal input is not available in runtime-resolver"),
+	readLine: Effect.die("terminal input is not available in runtime-resolver"),
+	display: () => Effect.die("terminal output is not available in runtime-resolver")
+});
+/**
+* The five `Command.Environment` services, implemented for a non-interactive
+* Node bin. `Path` is real; `FileSystem`, `Terminal` and `ChildProcessSpawner`
+* are unused by this CLI and fail loudly if that ever changes; `Stdio` is inert
+* because arguments come from `process.argv` and output goes through `Console`.
+*/
+const NodeCliEnvironment = Layer.mergeAll(Path.layer, FileSystem.layerNoop({}), Stdio.layerTest({}), Layer.succeed(Terminal.Terminal, deadTerminal), Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, ChildProcessSpawner.make(() => Effect.die("subprocess spawning is not available in runtime-resolver"))));
+
+//#endregion
+export { NodeCliEnvironment, githubClientFor, liveResolverLayers, offlineResolverLayers, selectResolverLayers };

package/output.js

@@ -0,0 +1,55 @@
+import { Result } from "effect";
+
+//#region src/cli/output.ts
+/**
+* The Node.js lifecycle phases a `--node-phases` value may name, mirroring the
+* kit's `NodePhase` vocabulary. Kept as a runtime tuple so the parser can both
+* validate against it and quote it back in an error message.
+*/
+const NODE_PHASES = [
+	"current",
+	"active-lts",
+	"maintenance-lts",
+	"end-of-life"
+];
+/**
+* Parse the comma-separated `--node-phases` value into the kit's phase array.
+*
+* A malformed value is a usage error, not a data condition, so this returns a
+* `Result` whose failure is the operator-facing message the caller prints to
+* stderr before failing the process.
+*/
+const parsePhases = (csv) => {
+	const tokens = csv.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
+	if (tokens.length === 0) return Result.fail(`--node-phases was empty; expected any of: ${NODE_PHASES.join(", ")}`);
+	const known = new Set(NODE_PHASES);
+	const invalid = tokens.filter((token) => !known.has(token));
+	if (invalid.length > 0) return Result.fail(`invalid --node-phases value${invalid.length > 1 ? "s" : ""}: ${invalid.join(", ")}. Expected any of: ${NODE_PHASES.join(", ")}`);
+	return Result.succeed(tokens);
+};
+/**
+* Project a `ResolvedVersions` onto a plain object so the output is exactly the
+* kit's shape — no schema markers, and no explicit `undefined` for the optional
+* fields the resolver omitted.
+*/
+const toPlain = (resolved) => ({
+	source: resolved.source,
+	versions: resolved.versions,
+	latest: resolved.latest,
+	...resolved.lts !== void 0 ? { lts: resolved.lts } : {},
+	...resolved.default !== void 0 ? { default: resolved.default } : {}
+});
+/**
+* Render the resolution output as JSON.
+*
+* A single requested runtime emits its `ResolvedVersions` directly; several
+* emit an object keyed by runtime name, in the order the entries were supplied.
+* `pretty` selects 2-space indentation over the compact default.
+*/
+const formatOutput = (entries, pretty) => {
+	const payload = entries.length === 1 ? toPlain(entries[0][1]) : Object.fromEntries(entries.map(([runtime, resolved]) => [runtime, toPlain(resolved)]));
+	return JSON.stringify(payload, null, pretty ? 2 : void 0);
+};
+
+//#endregion
+export { NODE_PHASES, formatOutput, parsePhases, toPlain };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "runtime-resolver",
-	"version": "0.3.22",
+	"version": "1.0.1",
 	"private": false,
 	"description": "Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes with Effect-based architecture and offline fallback.",
 	"keywords": [
@@ -22,7 +22,8 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/spencerbeggs/runtime-resolver.git"
+		"url": "git+https://github.com/spencerbeggs/runtime-resolver.git",
+		"directory": "package"
 	},
 	"license": "MIT",
 	"author": {
@@ -32,26 +33,13 @@
 	},
 	"sideEffects": false,
 	"type": "module",
-	"exports": {
-		".": {
-			"types": "./index.d.ts",
-			"import": "./index.js"
-		},
-		"./package.json": "./package.json"
-	},
 	"bin": {
 		"runtime-resolver": "bin/runtime-resolver.js"
 	},
 	"dependencies": {
-		"@octokit/auth-app": "^8.2.0",
-		"octokit": "^5.0.5",
-		"semver-effect": "^0.3.1"
-	},
-	"peerDependencies": {
-		"@effect/cli": "^0.75.2",
-		"@effect/platform": "^0.96.0",
-		"@effect/platform-node": "^0.107.0",
-		"effect": "^3.21.0"
+		"@effected/runtimes": "^0.1.5",
+		"@effected/semver": "~0.2.1",
+		"effect": "4.0.0-beta.101"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/report.js

@@ -0,0 +1,24 @@
+import { Cause, Option } from "effect";
+import { CliError } from "effect/unstable/cli";
+
+//#region src/cli/report.ts
+/**
+* The stderr line to print for a failed run, or `null` when nothing should be
+* printed because the CLI framework already rendered it.
+*
+* A `ShowHelp` failure has already written help + errors to the console, so it
+* returns `null`. A `UserError` carries an already-formatted message. Anything
+* else — a defect or interrupt with no typed failure — is surfaced through the
+* full cause rather than swallowed.
+*/
+const failureMessage = (cause) => {
+	const error = Cause.findErrorOption(cause);
+	if (Option.isNone(error)) return Cause.pretty(cause);
+	const value = error.value;
+	if (CliError.isCliError(value) && value._tag === "ShowHelp") return null;
+	if (value instanceof CliError.UserError) return `error: ${String(value.cause)}`;
+	return `error: ${String(value)}`;
+};
+
+//#endregion
+export { failureMessage };