runtime-resolver 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# 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)
+
+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.
+
+## 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
+- Resolve a single version from a semver range with `resolveVersion`
+- Control data freshness with `freshness` option (`"auto"`, `"api"`, or `"cache"`)
+- Track data provenance with the `source` field (`"api"` or `"cache"`)
+- Input validation with typed `InvalidInputError` for all resolvers
+- Offline fallback using bundled version data when GitHub is unreachable
+- CLI with structured JSON output for CI/CD pipelines
+
+## Installation
+
+```bash
+npm install runtime-resolver
+```
+
+## 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" });
+```
+
+Set a `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable
+for authenticated requests. Without one, the resolver falls back to cached data.
+
+### CLI
+
+```bash
+npx runtime-resolver --node ">=22" --bun "^1" --deno ">=2" --pretty
+```
+
+Output is structured JSON with a `$schema` reference for editor auto-complete. Print the full schema with `--schema`:
+
+```bash
+npx runtime-resolver --schema
+```
+
+#### Useful `jq` recipes
+
+```bash
+# Get the latest resolved Node.js version
+npx runtime-resolver --node ">=22" | jq -r '.results.node.latest'
+
+# List all matching versions as plain lines
+npx runtime-resolver --deno ">=2" | jq -r '.results.deno.versions[]'
+
+# Exit non-zero when any runtime fails to resolve
+npx runtime-resolver --node ">=22" --bun "^1" | jq -e '.ok'
+
+# Extract only the LTS version for Node.js
+npx runtime-resolver --node ">=20" --node-phases active-lts | jq -r '.results.node.lts'
+
+# Build a comma-separated matrix for GitHub Actions
+npx runtime-resolver --node ">=20" --increments minor \
+  | jq -r '[.results.node.versions[]] | join(",")'
+```
+
+### Effect API
+
+Power users can compose resolvers with custom layers and typed error handling instead of the Promise wrappers.
+
+```typescript
+import { Effect, Layer } from "effect";
+import {
+  NodeResolver,
+  NodeResolverLive,
+  GitHubClientLive,
+  GitHubTokenAuth,
+  VersionCacheLive,
+} from "runtime-resolver";
+
+const program = Effect.gen(function* () {
+  const resolver = yield* NodeResolver;
+  return yield* resolver.resolve({
+    semverRange: ">=22",
+    phases: ["active-lts"],
+  });
+});
+
+const layer = NodeResolverLive.pipe(
+  Layer.provide(Layer.merge(
+    GitHubClientLive.pipe(Layer.provide(GitHubTokenAuth)),
+    VersionCacheLive,
+  )),
+);
+
+Effect.runPromise(program.pipe(Effect.provide(layer)));
+```
+
+All services (`NodeResolver`, `BunResolver`, `DenoResolver`, `GitHubClient`,
+`VersionCache`), live layers, auth layers (`GitHubTokenAuth`, `GitHubAppAuth`,
+`GitHubAutoAuth`), and typed errors (`AuthenticationError`, `NetworkError`,
+`RateLimitError`, `VersionNotFoundError`, etc.) are exported from the package
+root.
+
+## Documentation
+
+For configuration, API reference, and advanced usage, see [docs](./docs/).
+
+## License
+
+[MIT](./LICENSE)

package/bin/runtime-resolver.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { Command, Options } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { readFileSync } from "node:fs";
+import { BunResolver, Console, NodeResolverLive, Layer, GitHubAppAuth, GitHubAutoAuth, BunResolverLive, DenoResolverLive, GitHubClientLive, Cause, Effect, GitHubTokenAuthFromToken, VersionCacheLive, Option, NodeResolver, DenoResolver } from "../969.js";
+const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+const SharedLayer = Layer.merge(GitHubLayer, VersionCacheLive);
+const NodeLayer = NodeResolverLive.pipe(Layer.provide(SharedLayer));
+const BunLayer = BunResolverLive.pipe(Layer.provide(SharedLayer));
+const DenoLayer = DenoResolverLive.pipe(Layer.provide(SharedLayer));
+const SCHEMA_URL = "https://raw.githubusercontent.com/spencerbeggs/runtime-resolver/main/runtime-resolver.schema.json";
+const nodeOption = Options.text("node").pipe(Options.optional);
+const bunOption = Options.text("bun").pipe(Options.optional);
+const denoOption = Options.text("deno").pipe(Options.optional);
+const nodePhasesOption = Options.text("node-phases").pipe(Options.optional);
+const incrementsOption = Options.text("increments").pipe(Options.optional);
+const nodeDefaultOption = Options.text("node-default").pipe(Options.optional);
+const bunDefaultOption = Options.text("bun-default").pipe(Options.optional);
+const denoDefaultOption = Options.text("deno-default").pipe(Options.optional);
+const freshnessOption = Options.text("freshness").pipe(Options.optional);
+const nodeDateOption = Options.text("node-date").pipe(Options.optional);
+const prettyOption = Options.boolean("pretty").pipe(Options.withDefault(false));
+const schemaOption = Options.boolean("schema").pipe(Options.withDefault(false));
+const tokenOption = Options.text("token").pipe(Options.optional);
+const appIdOption = Options.text("app-id").pipe(Options.optional);
+const appPrivateKeyOption = Options.text("app-private-key").pipe(Options.optional);
+const appInstallationIdOption = Options.text("app-installation-id").pipe(Options.optional);
+const VALID_PHASES = [
+    "current",
+    "active-lts",
+    "maintenance-lts",
+    "end-of-life"
+];
+const VALID_INCREMENTS = [
+    "latest",
+    "minor",
+    "patch"
+];
+const VALID_FRESHNESS = [
+    "auto",
+    "api",
+    "cache"
+];
+const validatePhases = (raw)=>{
+    const phases = raw.split(",").map((s)=>s.trim());
+    for (const p of phases)if (!VALID_PHASES.includes(p)) throw new Error(`Invalid phase: "${p}". Valid values: ${VALID_PHASES.join(", ")}`);
+    return phases;
+};
+const validateIncrements = (raw)=>{
+    if (!VALID_INCREMENTS.includes(raw)) throw new Error(`Invalid increments value: "${raw}". Valid values: ${VALID_INCREMENTS.join(", ")}`);
+    return raw;
+};
+const validateFreshness = (raw)=>{
+    if (!VALID_FRESHNESS.includes(raw)) throw new Error(`Invalid freshness value: "${raw}". Valid values: ${VALID_FRESHNESS.join(", ")}`);
+    return raw;
+};
+const serializeError = (error)=>{
+    if (error && "object" == typeof error && "_tag" in error && "message" in error) {
+        const { _tag, message, ...rest } = error;
+        return {
+            _tag,
+            message,
+            ...rest
+        };
+    }
+    return {
+        _tag: "UnknownError",
+        message: error instanceof Error ? error.message : String(error)
+    };
+};
+const toSuccess = (name, result)=>[
+        name,
+        {
+            ok: true,
+            source: result.source,
+            versions: [
+                ...result.versions
+            ],
+            latest: result.latest,
+            ...void 0 !== result.lts ? {
+                lts: result.lts
+            } : {},
+            ...void 0 !== result.default ? {
+                default: result.default
+            } : {}
+        }
+    ];
+const toError = (name, error)=>[
+        name,
+        {
+            ok: false,
+            error: serializeError(error)
+        }
+    ];
+const resolveNode = (semverRange, phases, increments, defaultVersion, date, freshness, authOverride)=>Effect.gen(function*() {
+        const resolver = yield* NodeResolver;
+        const result = yield* resolver.resolve({
+            semverRange,
+            ...phases ? {
+                phases
+            } : {},
+            ...increments ? {
+                increments
+            } : {},
+            ...defaultVersion ? {
+                defaultVersion
+            } : {},
+            ...date ? {
+                date
+            } : {},
+            ...freshness ? {
+                freshness
+            } : {}
+        });
+        return toSuccess("node", result);
+    }).pipe(Effect.provide(authOverride ? NodeResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : NodeLayer), Effect.catchAll((error)=>Effect.succeed(toError("node", error))));
+const resolveBun = (semverRange, increments, defaultVersion, freshness, authOverride)=>Effect.gen(function*() {
+        const resolver = yield* BunResolver;
+        const result = yield* resolver.resolve({
+            semverRange,
+            ...increments ? {
+                increments
+            } : {},
+            ...defaultVersion ? {
+                defaultVersion
+            } : {},
+            ...freshness ? {
+                freshness
+            } : {}
+        });
+        return toSuccess("bun", result);
+    }).pipe(Effect.provide(authOverride ? BunResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : BunLayer), Effect.catchAll((error)=>Effect.succeed(toError("bun", error))));
+const resolveDeno = (semverRange, increments, defaultVersion, freshness, authOverride)=>Effect.gen(function*() {
+        const resolver = yield* DenoResolver;
+        const result = yield* resolver.resolve({
+            semverRange,
+            ...increments ? {
+                increments
+            } : {},
+            ...defaultVersion ? {
+                defaultVersion
+            } : {},
+            ...freshness ? {
+                freshness
+            } : {}
+        });
+        return toSuccess("deno", result);
+    }).pipe(Effect.provide(authOverride ? DenoResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : DenoLayer), Effect.catchAll((error)=>Effect.succeed(toError("deno", error))));
+const formatResponse = (ok, results, pretty)=>{
+    const response = {
+        $schema: SCHEMA_URL,
+        ok,
+        results
+    };
+    return JSON.stringify(response, null, pretty ? 2 : void 0);
+};
+const resolveHandler = (args)=>Effect.gen(function*() {
+        if (args.schema) {
+            const resolveFlags = [
+                args.node,
+                args.bun,
+                args.deno,
+                args.nodePhases,
+                args.increments,
+                args.freshness,
+                args.nodeDefault,
+                args.bunDefault,
+                args.denoDefault,
+                args.nodeDate,
+                args.token,
+                args.appId,
+                args.appPrivateKey,
+                args.appInstallationId
+            ];
+            const hasResolveFlags = resolveFlags.some((f)=>Option.isSome(f));
+            if (hasResolveFlags) return void (yield* Console.error("Error: --schema cannot be combined with resolve flags (--node, --bun, --deno, etc.)"));
+            const { cliJsonSchema } = yield* Effect.promise(()=>import("../235.js").then((mod)=>({
+                        cliJsonSchema: mod.cliJsonSchema
+                    })));
+            yield* Console.log(JSON.stringify(cliJsonSchema, null, 2));
+            return;
+        }
+        const hasToken = Option.isSome(args.token);
+        const hasAppId = Option.isSome(args.appId);
+        const hasAppPrivateKey = Option.isSome(args.appPrivateKey);
+        const hasAppInstallationId = Option.isSome(args.appInstallationId);
+        if (hasToken && (hasAppId || hasAppPrivateKey)) return void (yield* Console.error("Error: --token and --app-id/--app-private-key are mutually exclusive"));
+        if (hasAppId !== hasAppPrivateKey) return void (yield* Console.error("Error: --app-id and --app-private-key must both be provided"));
+        if (hasAppInstallationId && !hasAppId) return void (yield* Console.error("Error: --app-installation-id requires --app-id and --app-private-key"));
+        let resolvedPrivateKey;
+        if (hasAppPrivateKey) {
+            const keyValue = args.appPrivateKey.value;
+            if (keyValue.startsWith("@")) {
+                const filePath = keyValue.slice(1);
+                try {
+                    resolvedPrivateKey = readFileSync(filePath, "utf-8");
+                } catch  {
+                    yield* Console.error(`Error: Cannot read private key file: ${filePath}`);
+                    return;
+                }
+            } else resolvedPrivateKey = keyValue;
+        }
+        let authLayerOverride;
+        if (hasToken) authLayerOverride = GitHubTokenAuthFromToken(args.token.value);
+        else if (hasAppId && resolvedPrivateKey) authLayerOverride = GitHubAppAuth({
+            appId: args.appId.value,
+            privateKey: resolvedPrivateKey,
+            ...hasAppInstallationId ? {
+                installationId: Number(args.appInstallationId.value)
+            } : {}
+        });
+        const hasNode = Option.isSome(args.node);
+        const hasBun = Option.isSome(args.bun);
+        const hasDeno = Option.isSome(args.deno);
+        if (!hasNode && !hasBun && !hasDeno) return void (yield* Console.error("No runtime specified. Use --node, --bun, or --deno to resolve versions.\nRun with --help for usage information."));
+        let validatedPhases;
+        if (Option.isSome(args.nodePhases)) try {
+            validatedPhases = validatePhases(args.nodePhases.value);
+        } catch (e) {
+            yield* Console.error(e.message);
+            return;
+        }
+        let validatedIncrements;
+        if (Option.isSome(args.increments)) try {
+            validatedIncrements = validateIncrements(args.increments.value);
+        } catch (e) {
+            yield* Console.error(e.message);
+            return;
+        }
+        let validatedFreshness;
+        if (Option.isSome(args.freshness)) try {
+            validatedFreshness = validateFreshness(args.freshness.value);
+        } catch (e) {
+            yield* Console.error(e.message);
+            return;
+        }
+        let nodeDate;
+        if (Option.isSome(args.nodeDate)) {
+            nodeDate = new Date(args.nodeDate.value);
+            if (Number.isNaN(nodeDate.getTime())) return void (yield* Console.error(`Invalid date: "${args.nodeDate.value}". Use ISO 8601 format (e.g. 2024-01-15).`));
+        }
+        const tasks = [];
+        if (hasNode) {
+            const nodeDefaultVersion = Option.isSome(args.nodeDefault) ? args.nodeDefault.value : void 0;
+            tasks.push(resolveNode(args.node.value, validatedPhases, validatedIncrements, nodeDefaultVersion, nodeDate, validatedFreshness, authLayerOverride));
+        }
+        if (hasBun) {
+            const bunDefaultVersion = Option.isSome(args.bunDefault) ? args.bunDefault.value : void 0;
+            tasks.push(resolveBun(args.bun.value, validatedIncrements, bunDefaultVersion, validatedFreshness, authLayerOverride));
+        }
+        if (hasDeno) {
+            const denoDefaultVersion = Option.isSome(args.denoDefault) ? args.denoDefault.value : void 0;
+            tasks.push(resolveDeno(args.deno.value, validatedIncrements, denoDefaultVersion, validatedFreshness, authLayerOverride));
+        }
+        const entries = yield* Effect.all(tasks, {
+            concurrency: "unbounded"
+        });
+        const results = Object.fromEntries(entries);
+        const hasError = Object.values(results).some((r)=>!r.ok);
+        yield* Console.log(formatResponse(!hasError, results, args.pretty));
+    });
+const rootCommand = Command.make("runtime-resolver", {
+    node: nodeOption,
+    bun: bunOption,
+    deno: denoOption,
+    nodePhases: nodePhasesOption,
+    increments: incrementsOption,
+    freshness: freshnessOption,
+    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.1.0"
+});
+const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(NodeContext.layer), Effect.catchAllCause((cause)=>{
+    const defects = Cause.defects(cause);
+    if (defects.length > 0) return Console.error(Cause.pretty(cause)).pipe(Effect.andThen(Effect.failCause(cause)));
+    return Effect.failCause(cause);
+}));
+NodeRuntime.runMain(main);