@opys/dev 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,312 @@
+import { Artifact, Discovery, ExtractRule, Launch, Manifest, Ruleset, Val, ValDefs, Valset, parseShortRuleset } from "@opys/core";
+
+//#region lib/plugin.d.ts
+/** Build-time context handed to every plugin's `build` hook. */
+interface BuildContext {
+  /** Sanctioned build-time logging channel; auto-prefixed by plugin name. */
+  log: (scope: string, message: string) => void;
+  /** Absolute directory of `opys.config.mjs` — anchor for relative paths. */
+  configDir: string;
+  /** Value of `opys build --mode <m>`; empty string when unset. */
+  mode: string;
+}
+/**
+ * Named launch fragments a plugin exposes for the config's `command`/`args`
+ * accessor functions — e.g. `{ jvmArgs, mainClass, gameArgs }` or `{ bin }`.
+ */
+type LaunchGroups = Record<string, Valset | Val | string>;
+/** What a plugin's `build` hook returns. */
+interface Contribution {
+  /** Artifacts to download/copy/extract. */
+  artifacts?: Artifact[];
+  /** Manifest vars this plugin owns. */
+  vars?: ValDefs;
+  /** Named launch fragments, exposed to the config's accessor functions. */
+  launch?: LaunchGroups;
+}
+/**
+ * A opys plugin — a pure-to-construct, bundler-style hook object. The
+ * constructor (`forge('1.20.1-best')`, …) does zero I/O; all network/fs work
+ * happens inside `build`, which the engine drives.
+ */
+interface OpysPlugin {
+  name: string;
+  build(ctx: BuildContext): Promise<Contribution> | Contribution;
+}
+/** Identity helper for authoring a plugin with inferred types. */
+declare function definePlugin(plugin: OpysPlugin): OpysPlugin;
+//#endregion
+//#region lib/config.d.ts
+/** Map of plugin name → its launch groups, passed to launch accessors. */
+type PluginMap = Record<string, LaunchGroups>;
+/** One entry of a config's assembled `args` — flattened to a `Valset`. */
+type ArgItem = Valset | Val | string;
+interface OpysManifestConfig {
+  /** Hand-written literal artifacts, merged with plugin output (last wins). */
+  artifacts?: Artifact[];
+  /** Override/extra vars layered on top of the merged plugin vars. */
+  vars?: ValDefs;
+  /** Launch command — typically `({ java }) => java.bin`. */
+  command: (plugins: PluginMap) => string;
+  /** Launch args — author-ordered named groups, flattened to a `Valset`. */
+  args: (plugins: PluginMap) => ArgItem[];
+  /** Working directory for the launched process. */
+  workdir?: string | ((plugins: PluginMap) => string);
+  /** Environment variables for the launched process. */
+  envs?: ValDefs | ((plugins: PluginMap) => ValDefs);
+  /** `restrict` globs swept clean after install. */
+  restrict?: string[];
+}
+interface OpysConfig {
+  /** Default manifest output path, relative to the config file. */
+  output?: string;
+  /** The plugins whose `build` hooks produce the manifest. */
+  plugins: OpysPlugin[];
+  /** Declarative manifest fields, separate from tooling config. */
+  manifest: OpysManifestConfig;
+  /**
+   * Launch-time manifest patch. Re-run on every `opys launch`; the returned
+   * partial is shallow-merged (per field) over the loaded manifest.
+   */
+  runClient?: (manifest: Manifest) => Partial<Manifest>;
+}
+interface OpysConfigContext {
+  /** Value of `opys build --mode <m>`; empty string when unset. */
+  mode: string;
+}
+type OpysConfigInput = OpysConfig | ((ctx: OpysConfigContext) => OpysConfig | Promise<OpysConfig>);
+/** Use as the default export of `opys.config.mjs`. */
+declare function defineConfig(input: OpysConfigInput): OpysConfigInput;
+/** Resolve a config input to a concrete `OpysConfig`. */
+declare function resolveConfig(input: OpysConfigInput, ctx: OpysConfigContext): Promise<OpysConfig>;
+//#endregion
+//#region lib/engine.d.ts
+/**
+ * Run every plugin's `build` hook in parallel, merge the contributions, and
+ * assemble the final `Manifest`.
+ */
+declare function buildManifest(config: OpysConfig, ctx: BuildContext): Promise<Manifest>;
+//#endregion
+//#region lib/overrides.d.ts
+/**
+ * Targets a subset of artifacts:
+ *
+ * - `string` / `string[]` — glob(s) matched against `artifact.path`
+ *   (multiple = OR).
+ * - predicate — `(a) => boolean`, the escape hatch for matching on source
+ *   kind, size, metadata, …
+ */
+type Selector = string | string[] | ((artifact: Artifact) => boolean);
+declare function matchesSelector(selector: Selector, artifact: Artifact): boolean;
+/** A ruleset in any form `parseShortRuleset` accepts (shorthand or full). */
+type RulesetInput = Parameters<typeof parseShortRuleset>[0];
+/**
+ * A per-selector patch over the artifacts a plugin produces. Each entry
+ * names the files it `match`es and the changes to apply — drop them,
+ * attach a ruleset, or clear integrity. Overrides run in list order; a
+ * later entry sees the effect of an earlier one.
+ */
+interface ArtifactOverride {
+  /** Files this override applies to. */
+  match: Selector;
+  /** Drop matched artifacts entirely. */
+  exclude?: boolean;
+  /**
+   * Ruleset to attach to matched artifacts — shorthand (`'allow.os.osx'`)
+   * or a full `Ruleset`. Appended to each artifact's existing `rules`.
+   */
+  rules?: RulesetInput;
+  /** `null` clears `integrity` + `discovery` (skip verification). */
+  integrity?: null;
+}
+/** Apply an ordered list of {@link ArtifactOverride}s to a list of artifacts. */
+declare function applyOverrides(artifacts: readonly Artifact[], overrides: readonly ArtifactOverride[]): Artifact[];
+//#endregion
+//#region lib/artifact-plugin.d.ts
+/**
+ * Wraps a {@link OpysPlugin} so that the artifacts it contributes are passed
+ * through an ordered list of {@link ArtifactOverride}s before being returned.
+ *
+ * Use this to give artifact-producing plugins (`forge`, `curseforge`, …) the
+ * same filter/patch support that `artifactScanner` already has natively. The
+ * inner plugin's `build` runs unchanged; only `Contribution.artifacts` is
+ * rewritten. Non-artifact contribution fields (`vars`, `launch`) pass through
+ * untouched.
+ *
+ * @param plugin   The inner plugin to wrap.
+ * @param overrides Overrides applied to the inner plugin's artifacts. An empty
+ *                  list is a no-op (artifacts pass through unchanged).
+ */
+declare function defineArtifactPlugin(plugin: OpysPlugin, overrides: readonly ArtifactOverride[]): OpysPlugin;
+//#endregion
+//#region lib/paths.d.ts
+/**
+ * Per-user data directory for an application, matching OS conventions:
+ *
+ * - Windows: `%APPDATA%\<name>`            (e.g. `C:\Users\you\AppData\Roaming\<name>`)
+ * - macOS:   `~/Library/Application Support/<name>`
+ * - Linux:   `$XDG_DATA_HOME/<name>` or `~/.local/share/<name>`
+ */
+declare function userDataDir(name: string): string;
+//#endregion
+//#region lib/scanner.d.ts
+/** A file discovered by {@link artifactScanner}, passed to `path`/`url` functions. */
+interface ScannedFile {
+  /** Path relative to `directory`, POSIX separators. */
+  readonly rel: string;
+  /** Directory portion of `rel` (`''` at the root). */
+  readonly dir: string;
+  /** Final path segment. */
+  readonly filename: string;
+  /** Absolute path on the build machine. */
+  readonly abs: string;
+}
+/**
+ * A `path` / `url` value: either a template string — interpolating the
+ * per-file placeholders `${rel}` / `${dir}` / `${filename}`, with any other
+ * `${var}` left for install — or a `(file) => string` function. Only the
+ * function form receives the build-machine `abs` path.
+ */
+type ScanTemplate = string | ((file: ScannedFile) => string);
+interface ArtifactScannerOptions {
+  /** Directory to scan. */
+  directory: string;
+  /** URL for fetching each file — template string or `(file) => string`. */
+  url: ScanTemplate;
+  /** Destination path — template or function. Defaults to the file's `rel`. */
+  path?: ScanTemplate;
+  hash?: 'sha1' | 'sha256';
+  /**
+   * 'url'  → emit sourceUrl + computed hash (default)
+   * 'file' → emit sourceFile pointing at the local copy; skip hashing entirely
+   */
+  source?: 'url' | 'file';
+  /**
+   * Per-selector patches applied to the scanned artifacts — exclude files,
+   * attach rulesets (OS / feature gates), or clear integrity.
+   */
+  overrides?: ArtifactOverride[];
+}
+/** Scan a local directory tree into artifacts — a generic build-time plugin. */
+declare function artifactScanner(options: ArtifactScannerOptions): OpysPlugin;
+//#endregion
+//#region lib/github.d.ts
+/** A single asset on a GitHub release, mirroring the `/releases` API shape. */
+interface GitHubAsset {
+  name: string;
+  size: number;
+  browser_download_url: string;
+  /** `sha256:<hex>` when present (introduced 2024); older releases lack it. */
+  digest?: string;
+}
+/** A single GitHub release entry from the `/releases` API. */
+interface GitHubRelease {
+  tag_name: string;
+  prerelease: boolean;
+  draft: boolean;
+  published_at: string;
+  assets: GitHubAsset[];
+}
+/**
+ * List all releases for `repo` (`owner/name`), newest first. Fetches a
+ * single page of up to 100 releases. `token` raises the rate limit.
+ */
+declare function listGitHubReleases(repo: string, token?: string): Promise<GitHubRelease[]>;
+/**
+ * Extract the hex sha256 from an asset's `digest` field. GitHub's `digest`
+ * is `sha256:<hex>` when present (introduced 2024); older releases lack it.
+ */
+declare function gitHubAssetSha256(asset: GitHubAsset): string | undefined;
+/** Selector accepted by {@link pickGitHubRelease}. */
+type GitHubReleaseSelector = /** Newest non-prerelease. */'latest' /** Newest including prereleases. */ | 'prerelease' /** Exact `tag_name` match. */ | (string & {});
+interface PickGitHubReleaseOptions {
+  /** Optional GitHub token for higher rate limits. */
+  token?: string;
+  /**
+   * Restrict candidates before the selector runs. Returns true to keep.
+   * Use this when the loader needs specific assets present (e.g. a
+   * `version.json` next to a mod jar) — `'latest'` then falls through to
+   * the newest release that actually qualifies.
+   */
+  filter?: (release: GitHubRelease) => boolean;
+}
+/**
+ * Fetch `repo`'s releases and pick one matching `selector`. Drafts are
+ * always skipped; the optional `filter` further narrows candidates before
+ * the selector runs. Throws a descriptive error (with up to 5 available
+ * tags) when nothing matches.
+ */
+declare function pickGitHubRelease(repo: string, selector: GitHubReleaseSelector, options?: PickGitHubReleaseOptions): Promise<GitHubRelease>;
+/**
+ * One asset → Artifact mapping inside a {@link gitHubReleaseArtifacts}
+ * call. The asset's URL, size, and sha256 are auto-derived; the spec
+ * supplies the install-time path plus any extra Artifact fields.
+ */
+interface GitHubAssetSpec {
+  /** Predicate to pick the asset on the resolved release. */
+  match: (asset: GitHubAsset, release: GitHubRelease) => boolean;
+  /**
+   * Install-time destination path. Manifest template literals (`${var}`)
+   * pass through unchanged. Use the function form when the path embeds a
+   * build-time value like the release tag.
+   */
+  path: string | ((asset: GitHubAsset, release: GitHubRelease) => string);
+  /** Human description used in the error if `match` finds nothing. */
+  description?: string;
+  /** Manifest rules (OS/arch constraints). Default `[]`. */
+  rules?: Ruleset;
+  /** Extract rules for jars / tarballs. */
+  extract?: ExtractRule[];
+  /** Optional install-time discovery hints. */
+  discovery?: Discovery;
+  /** Opaque metadata, forwarded into the manifest unchanged. */
+  metadata?: unknown;
+}
+interface GitHubReleaseArtifactsOptions {
+  /** GitHub token (raises rate limits). */
+  token?: string;
+  /**
+   * Restrict candidate releases before the selector runs. Use when the
+   * loader requires multiple assets present in the same release so that
+   * `'latest'` falls through to the newest one that fully qualifies.
+   */
+  filter?: (release: GitHubRelease) => boolean;
+  /** One spec per asset → Artifact mapping, in output order. */
+  assets: GitHubAssetSpec[];
+}
+interface GitHubReleaseArtifactsResult {
+  /** The picked release — handy for downstream metadata or side-fetches. */
+  release: GitHubRelease;
+  /** Mapped artifacts in input order, one per `assets` spec. */
+  artifacts: Artifact[];
+}
+/**
+ * Pick a GitHub release and project a list of asset specs into Artifacts
+ * in one call. Throws if the release can't be picked or any spec has no
+ * matching asset on the picked release.
+ *
+ * @example
+ *   const { artifacts } = await gitHubReleaseArtifacts(
+ *     'me/myloader', version, {
+ *       assets: [{
+ *         match: (a) => a.name.endsWith('.jar'),
+ *         path: '${mods_directory}/myloader.jar',
+ *       }],
+ *     },
+ *   );
+ */
+declare function gitHubReleaseArtifacts(repo: string, selector: GitHubReleaseSelector, options: GitHubReleaseArtifactsOptions): Promise<GitHubReleaseArtifactsResult>;
+//#endregion
+//#region lib/loader.d.ts
+/** Shared shape of the vanilla / forge-family loader templates. */
+interface LoaderTemplate {
+  launch: Launch;
+  jvmArgs: Valset;
+  mainClass: Val;
+  gameArgs: Valset;
+}
+/** Project a loader template's launch surface into named groups. */
+declare function launchGroups(t: LoaderTemplate): LaunchGroups;
+//#endregion
+export { ArgItem, ArtifactOverride, ArtifactScannerOptions, BuildContext, Contribution, GitHubAsset, GitHubAssetSpec, GitHubRelease, GitHubReleaseArtifactsOptions, GitHubReleaseArtifactsResult, GitHubReleaseSelector, LaunchGroups, LoaderTemplate, OpysConfig, OpysConfigContext, OpysConfigInput, OpysManifestConfig, OpysPlugin, PickGitHubReleaseOptions, PluginMap, RulesetInput, ScanTemplate, ScannedFile, Selector, applyOverrides, artifactScanner, buildManifest, defineArtifactPlugin, defineConfig, definePlugin, gitHubAssetSha256, gitHubReleaseArtifacts, launchGroups, listGitHubReleases, matchesSelector, pickGitHubRelease, resolveConfig, userDataDir };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../lib/plugin.ts","../lib/config.ts","../lib/engine.ts","../lib/overrides.ts","../lib/artifact-plugin.ts","../lib/paths.ts","../lib/scanner.ts","../lib/github.ts","../lib/loader.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,346 @@
+import { deduplicateArtifacts, fetchWithRetry, globToRegex, interpolate, parseShortRuleset, sourceFile, sourceUrl } from "@opys/core";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+
+//#region lib/plugin.ts
+/** Identity helper for authoring a plugin with inferred types. */
+function definePlugin(plugin) {
+	return plugin;
+}
+
+//#endregion
+//#region lib/config.ts
+/** Use as the default export of `opys.config.mjs`. */
+function defineConfig(input) {
+	return input;
+}
+/** Resolve a config input to a concrete `OpysConfig`. */
+async function resolveConfig(input, ctx) {
+	return typeof input === "function" ? input(ctx) : input;
+}
+
+//#endregion
+//#region lib/engine.ts
+/** Flatten author-ordered launch groups into a single `Valset`. */
+function flattenArgs(items) {
+	const out = [];
+	for (const item of items) if (typeof item === "string") out.push({
+		rules: [],
+		value: [item]
+	});
+	else if (Array.isArray(item)) out.push(...item);
+	else out.push(item);
+	return out;
+}
+/**
+* Run every plugin's `build` hook in parallel, merge the contributions, and
+* assemble the final `Manifest`.
+*/
+async function buildManifest(config, ctx) {
+	ctx.log("opys", `resolving ${config.plugins.length} plugin(s)`);
+	const results = await Promise.all(config.plugins.map(async (p) => ({
+		name: p.name,
+		contribution: await p.build(ctx)
+	})));
+	const artifacts = [];
+	for (const r of results) if (r.contribution.artifacts) artifacts.push(...r.contribution.artifacts);
+	if (config.manifest.artifacts) artifacts.push(...config.manifest.artifacts);
+	const deduped = deduplicateArtifacts(artifacts);
+	const vars = {};
+	const owner = {};
+	for (const r of results) {
+		if (!r.contribution.vars) continue;
+		for (const [key, value] of Object.entries(r.contribution.vars)) {
+			const prev = owner[key];
+			if (prev !== void 0 && prev !== r.name) ctx.log("opys", `warning: var '${key}' set by both '${prev}' and '${r.name}' — using '${r.name}'`);
+			vars[key] = value;
+			owner[key] = r.name;
+		}
+	}
+	if (config.manifest.vars) for (const [key, value] of Object.entries(config.manifest.vars)) vars[key] = value;
+	const pluginMap = Object.fromEntries(results.map((r) => [r.name, r.contribution.launch ?? {}]));
+	const m = config.manifest;
+	const launch = {
+		command: m.command(pluginMap),
+		workdir: typeof m.workdir === "function" ? m.workdir(pluginMap) : m.workdir ?? ".",
+		args: flattenArgs(m.args(pluginMap)),
+		envs: typeof m.envs === "function" ? m.envs(pluginMap) : m.envs ?? {}
+	};
+	ctx.log("opys", `merged ${deduped.length} artifact(s) (${artifacts.length - deduped.length} deduped)`);
+	return {
+		vars,
+		launch,
+		artifacts: deduped,
+		...m.restrict && m.restrict.length > 0 ? { restrict: m.restrict } : {}
+	};
+}
+
+//#endregion
+//#region lib/overrides.ts
+function matchesSelector(selector, artifact) {
+	if (typeof selector === "function") return selector(artifact);
+	return (Array.isArray(selector) ? selector : [selector]).map(globToRegex).some((re) => re.test(artifact.path));
+}
+/** Apply an ordered list of {@link ArtifactOverride}s to a list of artifacts. */
+function applyOverrides(artifacts, overrides) {
+	if (overrides.length === 0) return [...artifacts];
+	const out = [];
+	for (const artifact of artifacts) {
+		let current = artifact;
+		for (const override of overrides) {
+			if (current === null) break;
+			if (!matchesSelector(override.match, current)) continue;
+			if (override.exclude) {
+				current = null;
+				break;
+			}
+			if (override.rules !== void 0) {
+				const extra = parseShortRuleset(override.rules);
+				current = {
+					...current,
+					rules: [...current.rules, ...extra]
+				};
+			}
+			if (override.integrity === null) current = {
+				...current,
+				integrity: void 0,
+				discovery: void 0
+			};
+		}
+		if (current !== null) out.push(current);
+	}
+	return out;
+}
+
+//#endregion
+//#region lib/artifact-plugin.ts
+/**
+* Wraps a {@link OpysPlugin} so that the artifacts it contributes are passed
+* through an ordered list of {@link ArtifactOverride}s before being returned.
+*
+* Use this to give artifact-producing plugins (`forge`, `curseforge`, …) the
+* same filter/patch support that `artifactScanner` already has natively. The
+* inner plugin's `build` runs unchanged; only `Contribution.artifacts` is
+* rewritten. Non-artifact contribution fields (`vars`, `launch`) pass through
+* untouched.
+*
+* @param plugin   The inner plugin to wrap.
+* @param overrides Overrides applied to the inner plugin's artifacts. An empty
+*                  list is a no-op (artifacts pass through unchanged).
+*/
+function defineArtifactPlugin(plugin, overrides) {
+	return {
+		name: plugin.name,
+		async build(ctx) {
+			const contribution = await plugin.build(ctx);
+			if (contribution.artifacts === void 0) return contribution;
+			return {
+				...contribution,
+				artifacts: applyOverrides(contribution.artifacts, overrides)
+			};
+		}
+	};
+}
+
+//#endregion
+//#region lib/paths.ts
+/**
+* Per-user data directory for an application, matching OS conventions:
+*
+* - Windows: `%APPDATA%\<name>`            (e.g. `C:\Users\you\AppData\Roaming\<name>`)
+* - macOS:   `~/Library/Application Support/<name>`
+* - Linux:   `$XDG_DATA_HOME/<name>` or `~/.local/share/<name>`
+*/
+function userDataDir(name) {
+	if (process.platform === "win32") return join(process.env.APPDATA ?? homedir(), name);
+	if (process.platform === "darwin") return join(homedir(), "Library", "Application Support", name);
+	return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), name);
+}
+
+//#endregion
+//#region lib/scanner.ts
+async function walkDir(dir) {
+	async function walk(cur) {
+		const entries = await readdir(cur, { withFileTypes: true });
+		return (await Promise.all(entries.map(async (e) => {
+			const abs = join(cur, e.name);
+			if (e.isDirectory()) return walk(abs);
+			if (e.isFile()) {
+				const { size } = await stat(abs);
+				const rel = relative(dir, abs).replace(/\\/g, "/");
+				const d = dirname(rel);
+				return [{
+					rel,
+					dir: d === "." ? "" : d,
+					filename: basename(rel),
+					abs,
+					size
+				}];
+			}
+			return [];
+		}))).flat();
+	}
+	return walk(dir);
+}
+async function hashFile(path, algo) {
+	return createHash(algo).update(await readFile(path)).digest("hex");
+}
+function applyTemplate(tpl, file) {
+	if (typeof tpl === "function") return tpl(file);
+	return interpolate(tpl, {
+		rel: file.rel,
+		dir: file.dir,
+		filename: file.filename
+	});
+}
+async function* scanDirectory(options, baseDir) {
+	const algo = options.hash ?? "sha1";
+	const sourceKind = options.source ?? "url";
+	const files = await walkDir(baseDir);
+	for (const file of files) {
+		const artifactPath = options.path ? applyTemplate(options.path, file) : file.rel;
+		let integrity;
+		let source;
+		if (sourceKind === "file") source = sourceFile(file.abs);
+		else {
+			source = sourceUrl(applyTemplate(options.url, file));
+			const digest = await hashFile(file.abs, algo);
+			integrity = algo === "sha1" ? { sha1: digest } : { sha256: digest };
+		}
+		yield {
+			path: artifactPath,
+			source,
+			size: file.size,
+			rules: [],
+			integrity
+		};
+	}
+}
+/** Scan a local directory tree into artifacts — a generic build-time plugin. */
+function artifactScanner(options) {
+	return definePlugin({
+		name: "artifactScanner",
+		async build(ctx) {
+			const baseDir = isAbsolute(options.directory) ? options.directory : resolve(ctx.configDir, options.directory);
+			const scanned = [];
+			for await (const a of scanDirectory(options, baseDir)) scanned.push(a);
+			const artifacts = applyOverrides(scanned, options.overrides ?? []);
+			const dropped = scanned.length - artifacts.length;
+			ctx.log("artifactScanner", `scanned ${scanned.length} file(s)` + (dropped > 0 ? `, ${dropped} excluded` : ""));
+			return { artifacts };
+		}
+	});
+}
+
+//#endregion
+//#region lib/github.ts
+/**
+* Shared GitHub Releases helpers.
+*
+* The forge-family loaders (cleanroom, lwjgl3ify, unimixins) all resolve
+* their versions straight off GitHub Releases. This module centralises the
+* release-listing request and the `sha256:<hex>` digest parsing so the
+* resolvers don't each carry their own copy.
+*/
+/**
+* List all releases for `repo` (`owner/name`), newest first. Fetches a
+* single page of up to 100 releases. `token` raises the rate limit.
+*/
+async function listGitHubReleases(repo, token) {
+	const headers = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+	if (token) headers.Authorization = `Bearer ${token}`;
+	const res = await fetchWithRetry(`https://api.github.com/repos/${repo}/releases?per_page=100`, { headers });
+	if (!res.ok) throw new Error(`GitHub API ${res.status} ${res.statusText} listing ${repo} releases`);
+	return await res.json();
+}
+/**
+* Extract the hex sha256 from an asset's `digest` field. GitHub's `digest`
+* is `sha256:<hex>` when present (introduced 2024); older releases lack it.
+*/
+function gitHubAssetSha256(asset) {
+	return asset.digest?.startsWith("sha256:") ? asset.digest.slice(7) : void 0;
+}
+/**
+* Fetch `repo`'s releases and pick one matching `selector`. Drafts are
+* always skipped; the optional `filter` further narrows candidates before
+* the selector runs. Throws a descriptive error (with up to 5 available
+* tags) when nothing matches.
+*/
+async function pickGitHubRelease(repo, selector, options = {}) {
+	const candidates = (await listGitHubReleases(repo, options.token)).filter((r) => !r.draft).filter(options.filter ?? (() => true));
+	const picked = selectGitHubRelease(candidates, selector);
+	if (picked) return picked;
+	if (selector === "latest" || selector === "prerelease") throw new Error(`No ${selector === "latest" ? "stable" : ""} GitHub release in ${repo}${options.filter ? " matching the loader filter" : ""}`.replace(/  +/g, " "));
+	const tags = candidates.slice(0, 5).map((r) => r.tag_name);
+	throw new Error(`GitHub release '${selector}' not found in ${repo}. Available: ${tags.join(", ")}${candidates.length > 5 ? ", …" : ""}`);
+}
+function selectGitHubRelease(releases, selector) {
+	if (selector === "latest") return releases.find((r) => !r.prerelease);
+	if (selector === "prerelease") return releases[0];
+	return releases.find((r) => r.tag_name === selector);
+}
+/**
+* Pick a GitHub release and project a list of asset specs into Artifacts
+* in one call. Throws if the release can't be picked or any spec has no
+* matching asset on the picked release.
+*
+* @example
+*   const { artifacts } = await gitHubReleaseArtifacts(
+*     'me/myloader', version, {
+*       assets: [{
+*         match: (a) => a.name.endsWith('.jar'),
+*         path: '${mods_directory}/myloader.jar',
+*       }],
+*     },
+*   );
+*/
+async function gitHubReleaseArtifacts(repo, selector, options) {
+	const release = await pickGitHubRelease(repo, selector, {
+		token: options.token,
+		filter: options.filter
+	});
+	return {
+		release,
+		artifacts: options.assets.map((spec) => gitHubAssetToArtifact(spec, release))
+	};
+}
+function gitHubAssetToArtifact(spec, release) {
+	const asset = release.assets.find((a) => spec.match(a, release));
+	if (!asset) {
+		const what = spec.description ? ` (${spec.description})` : "";
+		throw new Error(`No matching asset${what} on GitHub release ${release.tag_name}. Assets: ${release.assets.map((a) => a.name).join(", ") || "(none)"}`);
+	}
+	const path = typeof spec.path === "function" ? spec.path(asset, release) : spec.path;
+	const sha256 = gitHubAssetSha256(asset);
+	return {
+		path,
+		source: sourceUrl(asset.browser_download_url),
+		size: asset.size,
+		rules: spec.rules ?? [],
+		...sha256 ? { integrity: { sha256 } } : {},
+		...spec.extract ? { extract: spec.extract } : {},
+		...spec.discovery ? { discovery: spec.discovery } : {},
+		...spec.metadata !== void 0 ? { metadata: spec.metadata } : {}
+	};
+}
+
+//#endregion
+//#region lib/loader.ts
+/** Project a loader template's launch surface into named groups. */
+function launchGroups(t) {
+	return {
+		command: t.launch.command,
+		jvmArgs: t.jvmArgs,
+		mainClass: t.mainClass,
+		gameArgs: t.gameArgs
+	};
+}
+
+//#endregion
+export { applyOverrides, artifactScanner, buildManifest, defineArtifactPlugin, defineConfig, definePlugin, gitHubAssetSha256, gitHubReleaseArtifacts, launchGroups, listGitHubReleases, matchesSelector, pickGitHubRelease, resolveConfig, userDataDir };
+//# sourceMappingURL=index.mjs.map