@effected/runtimes 0.1.0

package/BunResolver.js

@@ -0,0 +1,79 @@
+import { bunDefaults } from "./internal/defaults/bun.js";
+import { Increments } from "./ResolvedVersions.js";
+import { build } from "./internal/githubRuntime.js";
+import { populateAuto, populateFresh, populateOffline } from "./internal/strategy.js";
+import { SemVer } from "@effected/semver";
+import { Context, Schema } from "effect";
+
+//#region src/BunResolver.ts
+/**
+* One published Bun release.
+*
+* @public
+*/
+var BunRelease = class extends Schema.Class("BunRelease")({
+	/** The released version. */
+	version: SemVer,
+	/** When it was published. */
+	date: Schema.DateTimeUtc
+}) {};
+/**
+* How to resolve Bun versions.
+*
+* @public
+*/
+const BunResolverOptions = Schema.Struct({
+	/** The semver range to match. Defaults to `*`. */
+	range: Schema.optionalKey(Schema.String),
+	/** How to group matches. Defaults to `latest`. */
+	increments: Schema.optionalKey(Increments),
+	/** A range whose newest match becomes the `default` field. */
+	defaultVersion: Schema.optionalKey(Schema.String)
+});
+/**
+* The Bun resolver.
+*
+* @example
+* ```ts
+* import { BunResolver } from "@effected/runtimes";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* BunResolver;
+*   return (yield* resolver.resolve({ range: "^1.0.0" })).latest;
+* }).pipe(Effect.provide(BunResolver.layerOffline));
+* ```
+*
+* @public
+*/
+var BunResolver = class extends Context.Service()("@effected/runtimes/BunResolver") {
+	/** Try GitHub, fall back to the bundled snapshot. */
+	static layer = mk(this, (index, live, offline) => populateAuto(index, "bun", live, offline));
+	/** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
+	static layerFresh = mk(this, (index, live) => populateFresh(index, "bun", live));
+	/** The bundled snapshot only. Performs no IO and requires nothing. */
+	static layerOffline = mk(this, (index, _live, offline) => populateOffline(index, offline));
+};
+/**
+* The tag arrives as `this` rather than by name.
+*
+* A static initializer runs while the module-scope `BunResolver` binding is
+* still in its temporal dead zone, so naming the class here throws "Cannot
+* access 'BunResolver' before initialization" at import time. Inside a static
+* initializer `this` *is* the class, which is why `Layer.effect(this, ...)` is
+* the idiomatic v4 spelling.
+*/
+function mk(tag, strategy) {
+	return build({
+		tag,
+		runtime: "bun",
+		owner: "oven-sh",
+		repo: "bun",
+		spanName: "BunResolver.resolve",
+		defaults: bunDefaults,
+		make: (fields) => BunRelease.make(fields)
+	}, strategy);
+}
+
+//#endregion
+export { BunRelease, BunResolver, BunResolverOptions };

package/DenoResolver.js

@@ -0,0 +1,79 @@
+import { Increments } from "./ResolvedVersions.js";
+import { build } from "./internal/githubRuntime.js";
+import { populateAuto, populateFresh, populateOffline } from "./internal/strategy.js";
+import { denoDefaults } from "./internal/defaults/deno.js";
+import { SemVer } from "@effected/semver";
+import { Context, Schema } from "effect";
+
+//#region src/DenoResolver.ts
+/**
+* One published Deno release.
+*
+* @public
+*/
+var DenoRelease = class extends Schema.Class("DenoRelease")({
+	/** The released version. */
+	version: SemVer,
+	/** When it was published. */
+	date: Schema.DateTimeUtc
+}) {};
+/**
+* How to resolve Deno versions.
+*
+* @public
+*/
+const DenoResolverOptions = Schema.Struct({
+	/** The semver range to match. Defaults to `*`. */
+	range: Schema.optionalKey(Schema.String),
+	/** How to group matches. Defaults to `latest`. */
+	increments: Schema.optionalKey(Increments),
+	/** A range whose newest match becomes the `default` field. */
+	defaultVersion: Schema.optionalKey(Schema.String)
+});
+/**
+* The Deno resolver.
+*
+* @example
+* ```ts
+* import { DenoResolver } from "@effected/runtimes";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* DenoResolver;
+*   return (yield* resolver.resolve({ range: "^2.0.0" })).latest;
+* }).pipe(Effect.provide(DenoResolver.layerOffline));
+* ```
+*
+* @public
+*/
+var DenoResolver = class extends Context.Service()("@effected/runtimes/DenoResolver") {
+	/** Try GitHub, fall back to the bundled snapshot. */
+	static layer = mk(this, (index, live, offline) => populateAuto(index, "deno", live, offline));
+	/** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
+	static layerFresh = mk(this, (index, live) => populateFresh(index, "deno", live));
+	/** The bundled snapshot only. Performs no IO and requires nothing. */
+	static layerOffline = mk(this, (index, _live, offline) => populateOffline(index, offline));
+};
+/**
+* The tag arrives as `this` rather than by name.
+*
+* A static initializer runs while the module-scope `DenoResolver` binding is
+* still in its temporal dead zone, so naming the class here throws "Cannot
+* access 'DenoResolver' before initialization" at import time. Inside a static
+* initializer `this` *is* the class, which is why `Layer.effect(this, ...)` is
+* the idiomatic v4 spelling.
+*/
+function mk(tag, strategy) {
+	return build({
+		tag,
+		runtime: "deno",
+		owner: "denoland",
+		repo: "deno",
+		spanName: "DenoResolver.resolve",
+		defaults: denoDefaults,
+		make: (fields) => DenoRelease.make(fields)
+	}, strategy);
+}
+
+//#endregion
+export { DenoRelease, DenoResolver, DenoResolverOptions };

package/GitHub.js

@@ -0,0 +1,220 @@
+import { paginate } from "./internal/http.js";
+import { Config, Context, Effect, Layer, Option, Redacted, Schema } from "effect";
+import { FetchHttpClient, HttpClient } from "effect/unstable/http";
+
+//#region src/GitHub.ts
+/**
+* Talking to GitHub: pluggable authentication, a REST client, and the typed
+* failure ladder that every network fetch in this package reports through.
+*
+* The two nodejs.org feeds reuse this ladder rather than minting a parallel
+* one, so the module is named for its dominant user rather than for the
+* lowest common denominator.
+*
+* @packageDocumentation
+*/
+/**
+* GitHub rejected the credentials.
+*
+* @public
+*/
+var AuthenticationError = class extends Schema.TaggedErrorClass()("AuthenticationError", { 
+/** How the request was authenticated when it was rejected. */
+method: Schema.Literals(["token", "anonymous"]) }) {};
+/**
+* GitHub's rate limit was exhausted.
+*
+* `retryAfter` is what a caller needs to back off correctly, which is why it is
+* a structured field rather than prose in a message.
+*
+* @public
+*/
+var RateLimitError = class extends Schema.TaggedErrorClass()("RateLimitError", {
+	/** Seconds to wait before retrying, when GitHub said. */
+	retryAfter: Schema.optionalKey(Schema.Number),
+	/** The request quota for the window. */
+	limit: Schema.Number,
+	/** Requests left in the window. */
+	remaining: Schema.Number
+}) {};
+/**
+* A request did not complete, or completed with an unusable status.
+*
+* @public
+*/
+var NetworkError = class extends Schema.TaggedErrorClass()("NetworkError", {
+	/** The URL that failed. */
+	url: Schema.String,
+	/** The HTTP status, when there was a response at all. */
+	status: Schema.optionalKey(Schema.Number),
+	/** The underlying transport failure. */
+	cause: Schema.Defect()
+}) {};
+/**
+* A feed responded, but not with the shape this package expects.
+*
+* An operator-facing signal that an upstream feed changed.
+*
+* @public
+*/
+var ResponseParseError = class extends Schema.TaggedErrorClass()("ResponseParseError", {
+	/** The URL whose body could not be decoded. */
+	source: Schema.String,
+	/** The decoding failure. */
+	cause: Schema.Defect()
+}) {};
+/**
+* Materialize the engine's raw failure record into the public error ladder.
+*
+* The engine (`internal/http.ts`) never imports these classes — it returns raw
+* records and this is the single place they become errors. That is what keeps
+* the transport layer free of the facade and the import graph acyclic.
+*
+* `method` is what the *caller* actually sent, not a guess. Hardcoding it to
+* `"token"` made the `"anonymous"` arm of `AuthenticationError` unreachable and
+* mislabelled every anonymous rejection — the same shape of lie as v3's
+* hardcoded `source: "api"`.
+*
+* @internal
+*/
+const mapHttpFailure = (failure, method) => {
+	switch (failure._kind) {
+		case "auth": return new AuthenticationError({ method });
+		case "rateLimit": return new RateLimitError({
+			...failure.retryAfter !== void 0 ? { retryAfter: failure.retryAfter } : {},
+			limit: failure.limit,
+			remaining: failure.remaining
+		});
+		case "network": return new NetworkError({
+			url: failure.url,
+			...failure.status !== void 0 ? { status: failure.status } : {},
+			cause: failure.cause
+		});
+		case "parse": return new ResponseParseError({
+			source: failure.source,
+			cause: failure.cause
+		});
+	}
+};
+/**
+* A tag as `GET /repos/{owner}/{repo}/tags` returns it.
+*
+* @public
+*/
+var GitHubTag = class extends Schema.Class("GitHubTag")({ name: Schema.String }) {};
+/**
+* A release as `GET /repos/{owner}/{repo}/releases` returns it.
+*
+* @public
+*/
+var GitHubRelease = class extends Schema.Class("GitHubRelease")({
+	tag_name: Schema.String,
+	draft: Schema.Boolean,
+	prerelease: Schema.Boolean,
+	published_at: Schema.NullOr(Schema.String)
+}) {};
+const bearer = (token) => ({ authorization: `Bearer ${Redacted.value(token)}` });
+/**
+* Read the credentials as `Redacted` from the start.
+*
+* `Config.string` would hand back a plain string that only becomes `Redacted` at
+* the `bearer` call — a window in which the secret is an ordinary value that any
+* log, span annotation or error rendering could pick up. `Config.redacted` closes
+* the window: the token is never a bare string anywhere in this module.
+*/
+const patConfig = Config.redacted("GITHUB_PERSONAL_ACCESS_TOKEN").pipe(Config.option);
+const tokenConfig = Config.redacted("GITHUB_TOKEN").pipe(Config.option);
+/**
+* How GitHub requests are authenticated.
+*
+* @public
+*/
+var GitHubAuth = class GitHubAuth extends Context.Service()("@effected/runtimes/GitHubAuth") {
+	/**
+	* Send no credentials. GitHub allows this, at a much lower rate limit.
+	*/
+	static anonymous = Layer.succeed(GitHubAuth)({ headers: Effect.succeed({}) });
+	/**
+	* Authenticate with a personal access token.
+	*
+	* This returns a fresh layer per call, so bind it to a constant rather than
+	* calling it inline twice — layers are memoized by reference.
+	*/
+	static token = (token) => Layer.succeed(GitHubAuth)({ headers: Effect.succeed(bearer(token)) });
+	/**
+	* Detect a credential from the environment, preferring an explicit PAT.
+	*
+	* Precedence is `GITHUB_PERSONAL_ACCESS_TOKEN`, then `GITHUB_TOKEN`, then
+	* unauthenticated — the v3 policy, kept, but read through `Config` so a test
+	* can swap the `ConfigProvider` instead of mutating `process.env`.
+	*/
+	static layer = Layer.effect(GitHubAuth, Effect.gen(function* () {
+		const pat = yield* patConfig;
+		const token = yield* tokenConfig;
+		if (Option.isSome(pat)) {
+			if (Option.isSome(token)) yield* Effect.logWarning("Both GITHUB_PERSONAL_ACCESS_TOKEN and GITHUB_TOKEN are set; using the former");
+			return { headers: Effect.succeed(bearer(pat.value)) };
+		}
+		if (Option.isSome(token)) return { headers: Effect.succeed(bearer(token.value)) };
+		return { headers: Effect.succeed({}) };
+	}).pipe(Effect.orDie));
+};
+const TagList = Schema.Array(GitHubTag);
+const ReleaseList = Schema.Array(GitHubRelease);
+const listUrl = (owner, repo, kind) => (page, perPage) => `https://api.github.com/repos/${owner}/${repo}/${kind}?per_page=${perPage}&page=${page}`;
+const GITHUB_HEADERS = {
+	accept: "application/vnd.github+json",
+	"x-github-api-version": "2022-11-28"
+};
+/**
+* A GitHub REST client over `HttpClient`.
+*
+* v3 reached for `octokit` here, which cost two large dependency graphs to fund
+* two GET requests. Programming against `HttpClient` from `effect` core keeps
+* the package boundary tier and lets a consumer supply any transport.
+*
+* @public
+*/
+var GitHubClient = class GitHubClient extends Context.Service()("@effected/runtimes/GitHubClient") {
+	/**
+	* The client, requiring an `HttpClient` and a `GitHubAuth` from the context.
+	*/
+	static layer = Layer.effect(GitHubClient, Effect.gen(function* () {
+		const auth = yield* GitHubAuth;
+		const http = yield* HttpClient.HttpClient;
+		const list = (owner, repo, kind, schema, options) => Effect.gen(function* () {
+			const headers = yield* auth.headers;
+			const method = headers.authorization === void 0 ? "anonymous" : "token";
+			return yield* paginate(listUrl(owner, repo, kind), schema, {
+				...GITHUB_HEADERS,
+				...headers
+			}, options).pipe(Effect.mapError((failure) => mapHttpFailure(failure, method)));
+		}).pipe(Effect.provideService(HttpClient.HttpClient, http));
+		return {
+			listTags: Effect.fn("GitHubClient.listTags")(function* (owner, repo, options) {
+				yield* Effect.annotateCurrentSpan({
+					owner,
+					repo
+				});
+				return yield* list(owner, repo, "tags", TagList, options);
+			}),
+			listReleases: Effect.fn("GitHubClient.listReleases")(function* (owner, repo, options) {
+				yield* Effect.annotateCurrentSpan({
+					owner,
+					repo
+				});
+				return yield* list(owner, repo, "releases", ReleaseList, options);
+			})
+		};
+	}));
+	/**
+	* The client with batteries: environment-detected auth over `fetch`.
+	*
+	* The common wiring, in one import. Use {@link GitHubClient.layer} directly
+	* to supply your own credential or transport.
+	*/
+	static layerDefault = GitHubClient.layer.pipe(Layer.provide(Layer.mergeAll(GitHubAuth.layer, FetchHttpClient.layer)));
+};
+
+//#endregion
+export { AuthenticationError, GitHubAuth, GitHubClient, GitHubRelease, GitHubTag, NetworkError, RateLimitError, ResponseParseError, mapHttpFailure };

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/NodeRelease.js

@@ -0,0 +1,73 @@
+import { isLtsPhase } from "./NodeSchedule.js";
+import { SemVer } from "@effected/semver";
+import { Option, Schema } from "effect";
+
+//#region src/NodeRelease.ts
+/**
+* A published Node.js release.
+*
+* @packageDocumentation
+*/
+/**
+* One Node.js release.
+*
+* Unlike its v3 ancestor this is an ordinary immutable value. v3's `NodeRelease`
+* carried a `Ref<NodeSchedule>` so that `release.phase()` could reach the
+* schedule, which meant every release held shared mutable state and could not be
+* a data class at all. Phase is now a question you ask *with* a schedule rather
+* than a property the release drags around.
+*
+* @example
+* ```ts
+* import { NodeRelease, NodeSchedule } from "@effected/runtimes";
+* import { DateTime, Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const schedule = yield* NodeSchedule.fromData({
+*     v20: { start: "2023-04-18", lts: "2023-10-24", end: "2026-04-30" },
+*   });
+*   const release = NodeRelease.make({
+*     version: yield* SemVer.parse("20.11.0"),
+*     npm: yield* SemVer.parse("10.2.4"),
+*     date: DateTime.makeUnsafe("2024-01-09"),
+*   });
+*   return release.isLts(schedule, DateTime.makeUnsafe("2024-06-01")); // true
+* });
+* ```
+*
+* @public
+*/
+var NodeRelease = class extends Schema.Class("NodeRelease")({
+	/** The released version. */
+	version: SemVer,
+	/** The npm version bundled with it. */
+	npm: SemVer,
+	/** When it was published. */
+	date: Schema.DateTimeUtc
+}) {
+	/**
+	* This release's lifecycle phase at a point in time.
+	*
+	* The release line, not the major, is what the schedule is keyed by: `0.10`
+	* and `0.12` are separate lines with separate end dates, so asking by major
+	* alone would answer `0.12` with `0.8`'s schedule.
+	*
+	* `Option.none()` when the schedule does not cover this line, or when `now`
+	* predates the line's release.
+	*/
+	phase(schedule, now) {
+		return schedule.phaseFor(this.version, now);
+	}
+	/**
+	* Whether this release is in Long-Term Support at a point in time.
+	*/
+	isLts(schedule, now) {
+		return Option.match(this.phase(schedule, now), {
+			onNone: () => false,
+			onSome: isLtsPhase
+		});
+	}
+};
+
+//#endregion
+export { NodeRelease };

package/NodeResolver.js

@@ -0,0 +1,114 @@
+import { NodePhase, NodeSchedule } from "./NodeSchedule.js";
+import { buildNodeReleases, fetchNodeReleases, fetchNodeSchedule } from "./internal/feeds.js";
+import { make } from "./internal/releaseIndex.js";
+import { Increments } from "./ResolvedVersions.js";
+import { resolveWith } from "./internal/resolve.js";
+import { populateAuto, populateFresh, populateOffline } from "./internal/strategy.js";
+import { nodeDefaults, nodeScheduleDefaults } from "./internal/defaults/node.js";
+import { Context, DateTime, Effect, Layer, Option, Ref, Schema } from "effect";
+
+//#region src/NodeResolver.ts
+/**
+* How to resolve Node.js versions.
+*
+* @public
+*/
+const NodeResolverOptions = Schema.Struct({
+	/** The semver range to match. Defaults to `*`. */
+	range: Schema.optionalKey(Schema.String),
+	/** Lifecycle phases to accept. Defaults to `current` and `active-lts`. */
+	phases: Schema.optionalKey(Schema.Array(NodePhase)),
+	/** How to group matches. Defaults to `latest`. */
+	increments: Schema.optionalKey(Increments),
+	/** A range whose newest match becomes the `default` field. Defaults to the LTS pick. */
+	defaultVersion: Schema.optionalKey(Schema.String),
+	/** The moment to evaluate lifecycle phases at. Defaults to now, read from `Clock`. */
+	date: Schema.optionalKey(Schema.DateTimeUtc)
+});
+const DEFAULT_PHASES = ["current", "active-lts"];
+/**
+* The Node.js resolver.
+*
+* @example
+* ```ts
+* import { NodeResolver } from "@effected/runtimes";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* NodeResolver;
+*   const result = yield* resolver.resolve({ range: ">=20", phases: ["active-lts"] });
+*   return result.latest;
+* }).pipe(Effect.provide(NodeResolver.layerOffline));
+* ```
+*
+* @public
+*/
+var NodeResolver = class extends Context.Service()("@effected/runtimes/NodeResolver") {
+	/**
+	* Try the live feeds, fall back to the bundled snapshot.
+	*
+	* A fallback is recorded as `source: "cache"` and logged, so a caller can
+	* always tell a live answer from a snapshot.
+	*/
+	static layer = build(this, (index, live, offline) => populateAuto(index, "node", live, offline));
+	/**
+	* Live feeds or nothing. Fails with `FreshnessError` when they cannot be reached.
+	*/
+	static layerFresh = build(this, (index, live) => populateFresh(index, "node", live));
+	/**
+	* The bundled snapshot only. Performs no IO and requires nothing.
+	*/
+	static layerOffline = build(this, (index, _live, offline) => populateOffline(index, offline));
+};
+/**
+* Assemble a Node resolver layer around a strategy.
+*
+* The strategy's own error and requirement channels flow straight out into the
+* layer's, so `layerOffline` genuinely requires nothing and `layer` genuinely
+* cannot fail — no casts, and the types say what is true.
+*
+* The tag arrives as `this`: a static initializer runs while the module-scope
+* `NodeResolver` binding is still in its temporal dead zone, so naming the class
+* here throws at import time.
+*/
+function build(tag, strategy) {
+	return Layer.effect(tag, Effect.gen(function* () {
+		const index = yield* make();
+		const scheduleRef = yield* Ref.make(NodeSchedule.empty);
+		yield* strategy(index, Effect.gen(function* () {
+			const [raw, scheduleData] = yield* Effect.all([fetchNodeReleases(), fetchNodeSchedule()]);
+			yield* Ref.set(scheduleRef, yield* NodeSchedule.fromData(scheduleData));
+			return yield* buildNodeReleases(raw);
+		}).pipe(Effect.catchTag("InvalidVersionError", (cause) => Effect.die(cause))), Effect.gen(function* () {
+			yield* Ref.set(scheduleRef, yield* NodeSchedule.fromData(nodeScheduleDefaults));
+			return yield* buildNodeReleases(nodeDefaults);
+		}).pipe(Effect.orDie));
+		return { resolve: Effect.fn("NodeResolver.resolve")(function* (options) {
+			const range = options?.range ?? "*";
+			const phases = options?.phases ?? DEFAULT_PHASES;
+			const now = options?.date ?? (yield* DateTime.now);
+			const schedule = yield* Ref.get(scheduleRef);
+			yield* Effect.annotateCurrentSpan({
+				runtime: "node",
+				range
+			});
+			return yield* resolveWith({
+				index,
+				runtime: "node",
+				constraint: range,
+				increments: options?.increments ?? "latest",
+				defaultVersion: options?.defaultVersion,
+				phases,
+				defaultsToLts: true,
+				refine: (releases) => releases.filter((release) => Option.match(release.phase(schedule, now), {
+					onNone: () => false,
+					onSome: (phase) => phases.includes(phase)
+				})),
+				pickLts: (releases) => Option.fromUndefinedOr(releases.find((release) => release.isLts(schedule, now)))
+			});
+		}) };
+	}));
+}
+
+//#endregion
+export { NodeResolver, NodeResolverOptions };