runtime-resolver 0.1.0

package/index.d.ts

@@ -0,0 +1,430 @@
+import { Context } from 'effect';
+import type { Effect } from 'effect';
+import { Equals } from 'effect/Types';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+export declare class AuthenticationError extends AuthenticationErrorBase<{
+    readonly method: "token" | "app";
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ */
+export declare const AuthenticationErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "AuthenticationError";
+} & Readonly<A>;
+
+/**
+ * Service interface for resolving Bun runtime versions.
+ */
+export declare interface BunResolver {
+    readonly resolve: (options?: BunResolverOptions) => Effect.Effect<ResolvedVersions, BunResolverError>;
+    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, BunResolverError>;
+}
+
+/**
+ * BunResolver tag for dependency injection.
+ *
+ * @internal Uses GenericTag to avoid generating un-nameable `_base` types
+ * that break the declaration bundler (api-extractor) when re-exported via
+ * `export *`.
+ */
+export declare const BunResolver: Context.Tag<BunResolver, BunResolver>;
+
+export declare type BunResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+
+export declare const BunResolverLive: Layer.Layer<BunResolver, never, GitHubClient | VersionCache>;
+
+export declare interface BunResolverOptions {
+    readonly semverRange?: string;
+    readonly defaultVersion?: string;
+    readonly increments?: Increments;
+    readonly freshness?: Freshness;
+}
+
+export declare type CachedData = CachedNodeData | CachedTagData;
+
+export declare const CachedNodeData: Schema.Struct<{
+    versions: Schema.Array$<Schema.Struct<{
+        version: typeof Schema.String;
+        date: typeof Schema.String;
+        files: Schema.Array$<typeof Schema.String>;
+        npm: Schema.optional<typeof Schema.String>;
+        v8: Schema.optional<typeof Schema.String>;
+        uv: Schema.optional<typeof Schema.String>;
+        zlib: Schema.optional<typeof Schema.String>;
+        openssl: Schema.optional<typeof Schema.String>;
+        modules: Schema.optional<typeof Schema.String>;
+        lts: Schema.Union<[Schema.Literal<[false]>, typeof Schema.String]>;
+        security: typeof Schema.Boolean;
+    }>>;
+    schedule: Schema.Record$<typeof Schema.String, Schema.Struct<{
+        start: typeof Schema.String;
+        lts: Schema.optional<typeof Schema.String>;
+        maintenance: Schema.optional<typeof Schema.String>;
+        end: typeof Schema.String;
+        codename: Schema.optional<typeof Schema.String>;
+    }>>;
+}>;
+
+export declare type CachedNodeData = typeof CachedNodeData.Type;
+
+export declare const CachedTagData: Schema.Struct<{
+    tags: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        zipball_url: typeof Schema.String;
+        tarball_url: typeof Schema.String;
+        commit: Schema.Struct<{
+            sha: typeof Schema.String;
+            url: typeof Schema.String;
+        }>;
+        node_id: typeof Schema.String;
+    }>>;
+}>;
+
+export declare type CachedTagData = typeof CachedTagData.Type;
+
+export declare class CacheError extends CacheErrorBase<{
+    readonly operation: "read" | "write";
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const CacheErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "CacheError";
+} & Readonly<A>;
+
+/**
+ * Service interface for resolving Deno runtime versions.
+ */
+export declare interface DenoResolver {
+    readonly resolve: (options?: DenoResolverOptions) => Effect.Effect<ResolvedVersions, DenoResolverError>;
+    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, DenoResolverError>;
+}
+
+/**
+ * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ */
+export declare const DenoResolver: Context.Tag<DenoResolver, DenoResolver>;
+
+export declare type DenoResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+
+export declare const DenoResolverLive: Layer.Layer<DenoResolver, never, GitHubClient | VersionCache>;
+
+export declare interface DenoResolverOptions {
+    readonly semverRange?: string;
+    readonly defaultVersion?: string;
+    readonly increments?: Increments;
+    readonly freshness?: Freshness;
+}
+
+export declare const Freshness: Schema.Literal<["auto", "api", "cache"]>;
+
+export declare type Freshness = typeof Freshness.Type;
+
+export declare class FreshnessError extends FreshnessErrorBase<{
+    readonly strategy: Freshness;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const FreshnessErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "FreshnessError";
+} & Readonly<A>;
+
+export declare const GitHubAppAuth: (config: GitHubAppAuthConfig) => Layer.Layer<OctokitInstance, AuthenticationError, never>;
+
+export declare interface GitHubAppAuthConfig {
+    readonly appId: string;
+    readonly privateKey: string;
+    readonly installationId?: number;
+}
+
+export declare const GitHubAutoAuth: Layer.Layer<OctokitInstance, AuthenticationError>;
+
+/**
+ * Service interface for GitHub API operations.
+ */
+export declare interface GitHubClient {
+    readonly listTags: (owner: string, repo: string, options?: ListOptions) => Effect.Effect<ReadonlyArray<GitHubTag>, AuthenticationError | NetworkError | RateLimitError | ParseError>;
+    readonly listReleases: (owner: string, repo: string, options?: ListOptions) => Effect.Effect<ReadonlyArray<GitHubRelease>, AuthenticationError | NetworkError | RateLimitError | ParseError>;
+    readonly getJson: <A>(url: string, schema: {
+        readonly decode: (input: unknown) => Effect.Effect<A, ParseError>;
+    }) => Effect.Effect<A, NetworkError | ParseError>;
+}
+
+/**
+ * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ */
+export declare const GitHubClient: Context.Tag<GitHubClient, GitHubClient>;
+
+export declare const GitHubClientLive: Layer.Layer<GitHubClient, never, OctokitInstance>;
+
+export declare const GitHubRelease: Schema.Struct<{
+    tag_name: typeof Schema.String;
+    name: Schema.NullOr<typeof Schema.String>;
+    draft: typeof Schema.Boolean;
+    prerelease: typeof Schema.Boolean;
+    published_at: Schema.NullOr<typeof Schema.String>;
+}>;
+
+export declare type GitHubRelease = typeof GitHubRelease.Type;
+
+export declare const GitHubTag: Schema.Struct<{
+    name: typeof Schema.String;
+    zipball_url: typeof Schema.String;
+    tarball_url: typeof Schema.String;
+    commit: Schema.Struct<{
+        sha: typeof Schema.String;
+        url: typeof Schema.String;
+    }>;
+    node_id: typeof Schema.String;
+}>;
+
+export declare type GitHubTag = typeof GitHubTag.Type;
+
+export declare const GitHubTokenAuth: Layer.Layer<OctokitInstance>;
+
+export declare const GitHubTokenAuthFromToken: (token: string) => Layer.Layer<OctokitInstance, never, never>;
+
+export declare const Increments: Schema.Literal<["latest", "minor", "patch"]>;
+
+export declare type Increments = typeof Increments.Type;
+
+export declare class InvalidInputError extends InvalidInputErrorBase<{
+    readonly field: string;
+    readonly value: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const InvalidInputErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "InvalidInputError";
+} & Readonly<A>;
+
+export declare interface ListOptions {
+    readonly perPage?: number;
+    readonly pages?: number;
+}
+
+export declare class NetworkError extends NetworkErrorBase<{
+    readonly url: string;
+    readonly status?: number;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const NetworkErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+
+export declare const NodePhase: Schema.Literal<["current", "active-lts", "maintenance-lts", "end-of-life"]>;
+
+export declare type NodePhase = typeof NodePhase.Type;
+
+/**
+ * Service interface for resolving Node.js runtime versions.
+ */
+export declare interface NodeResolver {
+    readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, NodeResolverError>;
+    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, NodeResolverError>;
+}
+
+/**
+ * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ */
+export declare const NodeResolver: Context.Tag<NodeResolver, NodeResolver>;
+
+export declare type NodeResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+
+export declare const NodeResolverLive: Layer.Layer<NodeResolver, never, GitHubClient | VersionCache>;
+
+export declare interface NodeResolverOptions {
+    readonly semverRange?: string;
+    readonly defaultVersion?: string;
+    readonly phases?: ReadonlyArray<NodePhase>;
+    readonly increments?: Increments;
+    readonly date?: Date;
+    readonly freshness?: Freshness;
+}
+
+/**
+ * Service interface for Octokit REST API client.
+ */
+export declare interface OctokitInstance {
+    readonly rest: {
+        readonly repos: {
+            readonly listTags: (params: {
+                owner: string;
+                repo: string;
+                per_page?: number;
+                page?: number;
+            }) => Promise<{
+                data: Array<unknown>;
+            }>;
+            readonly listReleases: (params: {
+                owner: string;
+                repo: string;
+                per_page?: number;
+                page?: number;
+            }) => Promise<{
+                data: Array<unknown>;
+            }>;
+        };
+    };
+}
+
+/**
+ * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ */
+export declare const OctokitInstance: Context.Tag<OctokitInstance, OctokitInstance>;
+
+export declare class ParseError extends ParseErrorBase<{
+    readonly source: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const ParseErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "ParseError";
+} & Readonly<A>;
+
+export declare class RateLimitError extends RateLimitErrorBase<{
+    readonly retryAfter?: number;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const RateLimitErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "RateLimitError";
+} & Readonly<A>;
+
+/**
+ * Resolve Bun versions matching the given options.
+ *
+ * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
+ * Falls back to build-time cache when the network is unavailable.
+ */
+export declare const resolveBun: (options?: BunResolverOptions | undefined) => Promise<{
+    readonly source: "api" | "cache";
+    readonly versions: readonly string[];
+    readonly latest: string;
+    readonly lts?: string | undefined;
+    readonly default?: string | undefined;
+}>;
+
+/**
+ * Resolve Deno versions matching the given options.
+ *
+ * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
+ * Falls back to build-time cache when the network is unavailable.
+ */
+export declare const resolveDeno: (options?: DenoResolverOptions | undefined) => Promise<{
+    readonly source: "api" | "cache";
+    readonly versions: readonly string[];
+    readonly latest: string;
+    readonly lts?: string | undefined;
+    readonly default?: string | undefined;
+}>;
+
+export declare const ResolvedVersions: Schema.Struct<{
+    source: Schema.Literal<["api", "cache"]>;
+    versions: Schema.Array$<typeof Schema.String>;
+    latest: typeof Schema.String;
+    lts: Schema.optional<typeof Schema.String>;
+    default: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare type ResolvedVersions = typeof ResolvedVersions.Type;
+
+/**
+ * Resolve Node.js versions matching the given options.
+ *
+ * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
+ * Falls back to build-time cache when the network is unavailable.
+ */
+export declare const resolveNode: (options?: NodeResolverOptions | undefined) => Promise<{
+    readonly source: "api" | "cache";
+    readonly versions: readonly string[];
+    readonly latest: string;
+    readonly lts?: string | undefined;
+    readonly default?: string | undefined;
+}>;
+
+export declare const Runtime: Schema.Literal<["node", "bun", "deno"]>;
+
+export declare type Runtime = typeof Runtime.Type;
+
+export declare const Source: Schema.Literal<["api", "cache"]>;
+
+export declare type Source = typeof Source.Type;
+
+/**
+ * Service interface for version data caching.
+ */
+export declare interface VersionCache {
+    readonly get: (runtime: Runtime) => Effect.Effect<{
+        data: CachedData;
+        source: Source;
+    }, CacheError>;
+    readonly set: (runtime: Runtime, data: CachedData) => Effect.Effect<void, CacheError>;
+}
+
+/**
+ * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ */
+export declare const VersionCache: Context.Tag<VersionCache, VersionCache>;
+
+export declare const VersionCacheLive: Layer.Layer<VersionCache>;
+
+export declare class VersionNotFoundError extends VersionNotFoundErrorBase<{
+    readonly runtime: Runtime;
+    readonly constraint: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ */
+export declare const VersionNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "VersionNotFoundError";
+} & Readonly<A>;
+
+export { }

package/index.js

@@ -0,0 +1,20 @@
+import { Layer, NodeResolver, GitHubAutoAuth, BunResolverLive, DenoResolverLive, GitHubClientLive, VersionCacheLive, Effect, BunResolver, DenoResolver, NodeResolverLive } 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 resolveNode = (options)=>Effect.runPromise(Effect.gen(function*() {
+        const resolver = yield* NodeResolver;
+        return yield* resolver.resolve(options);
+    }).pipe(Effect.provide(NodeLayer)));
+const resolveBun = (options)=>Effect.runPromise(Effect.gen(function*() {
+        const resolver = yield* BunResolver;
+        return yield* resolver.resolve(options);
+    }).pipe(Effect.provide(BunLayer)));
+const resolveDeno = (options)=>Effect.runPromise(Effect.gen(function*() {
+        const resolver = yield* DenoResolver;
+        return yield* resolver.resolve(options);
+    }).pipe(Effect.provide(DenoLayer)));
+export { AuthenticationError, AuthenticationErrorBase, BunResolver, BunResolverLive, CacheError, CacheErrorBase, DenoResolver, DenoResolverLive, FreshnessError, FreshnessErrorBase, GitHubAppAuth, GitHubAutoAuth, GitHubClient, GitHubClientLive, GitHubTokenAuth, GitHubTokenAuthFromToken, InvalidInputError, InvalidInputErrorBase, NetworkError, NetworkErrorBase, NodeResolver, NodeResolverLive, OctokitInstance, ParseError, ParseErrorBase, RateLimitError, RateLimitErrorBase, VersionCache, VersionCacheLive, VersionNotFoundError, VersionNotFoundErrorBase } from "./969.js";
+export { resolveBun, resolveDeno, resolveNode };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "runtime-resolver",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes with Effect-based architecture and offline fallback.",
+  "keywords": [
+    "node",
+    "bun",
+    "deno",
+    "runtime",
+    "version",
+    "semver",
+    "resolver",
+    "ci",
+    "github-actions",
+    "effect",
+    "cli"
+  ],
+  "homepage": "https://github.com/spencerbeggs/runtime-resolver#readme",
+  "bugs": {
+    "url": "https://github.com/spencerbeggs/runtime-resolver/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spencerbeggs/runtime-resolver.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "C. Spencer Beggs",
+    "email": "spencer@beggs.codes",
+    "url": "https://spencerbeg.gs"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "runtime-resolver": "./bin/runtime-resolver.js"
+  },
+  "dependencies": {
+    "@effect/cli": "^0.73.2",
+    "@effect/platform": "^0.94.5",
+    "@effect/platform-node": "^0.104.1",
+    "@octokit/auth-app": "^8.2.0",
+    "effect": "^3.19.19",
+    "octokit": "^5.0.5",
+    "semver": "^7.7.4"
+  },
+  "files": [
+    "!runtime-resolver.api.json",
+    "!tsconfig.json",
+    "!tsdoc.json",
+    "235.js",
+    "969.js",
+    "LICENSE",
+    "README.md",
+    "bin/runtime-resolver.js",
+    "index.d.ts",
+    "index.js",
+    "package.json",
+    "tsdoc-metadata.json"
+  ]
+}

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.57.6"
+    }
+  ]
+}