@opys/core 0.1.2

package/README.md

@@ -0,0 +1,121 @@
+# @opys/core
+
+Data model for Opys manifests. Types, factory functions, Zod parsers, and encode/decode utilities. No I/O.
+
+## Install
+
+```sh
+npm install @opys/core @opys/rules zod
+```
+
+## Types
+
+### `Source` — artifact origin
+
+```ts
+type Source =
+  | { kind: 'url'; url: string }
+  | { kind: 'file'; file: string }
+  | { kind: 'string'; string: string }
+  | { kind: 'empty' };
+
+// Factory functions
+sourceUrl('https://example.com/file.jar');
+sourceFile('./local/file.jar');
+sourceString('inline content');
+sourceEmpty();
+
+// Parse / encode
+SourceSchema.parse(raw);
+encodeSource(source);
+```
+
+### `ExtractRule` — zip extraction instructions
+
+```ts
+type ExtractRule =
+  | { kind: 'pick'; file: string; into: string }          // single file
+  | { kind: 'scan'; matches: string; into: string; ... }  // glob match
+  | { kind: 'dump'; into: string; clean?: boolean; ... }  // full extract
+
+// Factory functions
+extractPick('lwjgl.dll', '${natives_directory}')
+extractScan('*.so', '${natives_directory}', { excludes: ['META-INF/'] })
+extractDump('${natives_directory}', { clean: true, excludes: ['META-INF/'] })
+
+// Parse / encode
+ExtractSchema.parse(raw)          // always returns ExtractRule[]
+encodeExtract(rules)
+```
+
+### `Artifact` — a single installable artifact
+
+An artifact has a source, optional integrity/size checks, optional extract rules, and optional rulesets that gate it per platform or feature.
+
+```ts
+import { ArtifactSchema, encodeArtifact } from '@opys/core';
+
+const artifact = ArtifactSchema.parse(raw);
+encodeArtifact(artifact);
+```
+
+### `Manifest` — the manifest
+
+```ts
+interface Manifest {
+  vars: ValDefs;
+  launch?: Launch;
+  artifacts: ReadonlyArray<Artifact>;
+}
+
+// Parse JSON string
+const manifest = await parseManifest(jsonString);
+
+// Filter to current platform
+const filtered = filterManifest(manifest, { name: 'linux', arch: 'x64' });
+
+// Encode back to JSON-serializable object
+encodeManifest(manifest);
+```
+
+### `ValDefs` — interpolation variables
+
+Variables support OS-conditional values and `${ref}` interpolation.
+
+```ts
+import {
+  parseValDefs,
+  encodeValDefs,
+  resolveValDefs,
+  resolveVars,
+} from '@opys/core';
+
+const defs = parseValDefs(raw);
+const flat = resolveValDefs(defs, platform); // pick OS-appropriate values
+const vars = resolveVars(flat); // resolve ${ref} chains
+const result = interpolate('${root}/assets', vars);
+```
+
+### `defineConfig` — config file helper
+
+Used as the default export in `opys.config.mjs`:
+
+```ts
+import { defineConfig } from '@opys/core';
+
+export default defineConfig({
+  output: 'opys.json',
+  manifest: {
+    artifacts: [...],
+    vars: [...],
+    launch: { ... },
+  },
+});
+
+// Or as a function for context-aware configs
+export default defineConfig((ctx) => ({
+  manifest: {
+    artifacts: ctx.mode === 'build' ? [...] : [],
+  },
+}));
+```

package/dist/index.cjs

@@ -0,0 +1,413 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let zod = require("zod");
+let _opys_core_binding = require("@opys/core-binding");
+_opys_core_binding = __toESM(_opys_core_binding);
+
+//#region lib/fetch.ts
+/**
+* Wrap `fetch()` with bounded retry on transient network failures and
+* 5xx-class responses. Errors that won't recover from a retry (4xx,
+* `AbortError`, JSON parse failures downstream of the response) are
+* surfaced unchanged so callers handle them with their own logic.
+*
+* Network-level retries cover the AggregateError ETIMEDOUT / ECONNRESET
+* / ENOTFOUND / EAI_AGAIN / ECONNREFUSED cases that node:undici reports
+* as `TypeError: fetch failed` with a populated `cause`. Without this
+* one DNS hiccup mid-`opys launch` aborts the whole config evaluation.
+*/
+/**
+* Default `User-Agent` for every opys HTTP request. The bare `undici`
+* agent gets rejected or rate-limited by some CDNs and by the CurseForge
+* API, so we identify ourselves. The patch component is omitted so the
+* string doesn't churn against `package.json` on every release.
+*/
+const OPYS_USER_AGENT = "opys/1.0";
+const DEFAULT_RETRY_STATUSES = new Set([
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const TRANSIENT_CODES = new Set([
+	"ETIMEDOUT",
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EPIPE",
+	"UND_ERR_SOCKET",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_HEADERS_TIMEOUT",
+	"UND_ERR_BODY_TIMEOUT"
+]);
+function isTransientFetchError(err) {
+	if (!err || typeof err !== "object") return false;
+	const cause = err.cause;
+	if (cause) {
+		const code = cause.code;
+		if (code && TRANSIENT_CODES.has(code)) return true;
+		const inner = cause.errors;
+		if (Array.isArray(inner) && inner.length > 0) return inner.every((e) => {
+			const c = e?.code;
+			return c !== void 0 && TRANSIENT_CODES.has(c);
+		});
+	}
+	const code = err.code;
+	if (code && TRANSIENT_CODES.has(code)) return true;
+	return err instanceof TypeError && typeof err.message === "string" && err.message.toLowerCase().includes("fetch failed");
+}
+function backoffMs(attempt, base, max) {
+	const exp = base * 2 ** (attempt - 1);
+	const capped = Math.min(exp, max);
+	return Math.floor(capped * (.5 + Math.random() * .5));
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			return;
+		}
+		const t = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(t);
+			reject(signal?.reason ?? /* @__PURE__ */ new Error("aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+async function fetchWithRetry(input, init = {}, retry = {}) {
+	const attempts = Math.max(1, retry.attempts ?? 4);
+	const base = retry.baseDelayMs ?? 250;
+	const max = retry.maxDelayMs ?? 5e3;
+	const retryStatuses = retry.retryStatuses instanceof Set ? retry.retryStatuses : retry.retryStatuses ? new Set(retry.retryStatuses) : DEFAULT_RETRY_STATUSES;
+	const signal = retry.signal ?? init.signal ?? void 0;
+	const headers = new Headers(init.headers);
+	if (!headers.has("user-agent")) headers.set("user-agent", OPYS_USER_AGENT);
+	let lastErr;
+	for (let attempt = 1; attempt <= attempts; attempt++) try {
+		const res = await fetch(input, {
+			...init,
+			headers,
+			signal
+		});
+		if (res.ok || attempt === attempts || !retryStatuses.has(res.status)) return res;
+		try {
+			await res.body?.cancel();
+		} catch {}
+		const delay = backoffMs(attempt, base, max);
+		retry.onRetry?.({
+			attempt,
+			delayMs: delay,
+			status: res.status
+		});
+		await sleep(delay, signal);
+	} catch (err) {
+		lastErr = err;
+		if (signal?.aborted) throw err;
+		if (!isTransientFetchError(err) || attempt === attempts) throw err;
+		const delay = backoffMs(attempt, base, max);
+		retry.onRetry?.({
+			attempt,
+			delayMs: delay,
+			error: err
+		});
+		await sleep(delay, signal);
+	}
+	throw lastErr;
+}
+
+//#endregion
+//#region lib/index.ts
+/**
+* `@opys/core` — the frozen-manifest contract. Behaviors are backed by the
+* Rust `opys-core` crate (via napi-rs); domain types, factories and small
+* sugar helpers are hand-written TS.
+*
+* Strategy:
+*   - Algorithms that touch the manifest contract (decode, encode, resolve,
+*     filter, interpolate, glob) → typed wrappers around the Rust binding.
+*   - Domain types → hand-typed here, matching the frozen wire shape. These
+*     are pure data shapes; consumers construct them as plain JS objects.
+*   - Factories / type guards / small dedup helpers → pure TS, no boundary
+*     crossing. They are sugar over the typed shapes.
+*   - `parseShortRuleset` is implemented in TS as the shorthand sugar — the
+*     Rust binding accepts shorthand directly via `satisfiesRuleset` so the
+*     TS impl exists for consumers that need expanded `Rule` objects.
+*/
+const OsNameSchema = zod.z.enum([
+	"linux",
+	"windows",
+	"osx"
+]);
+const OsArchSchema = zod.z.enum([
+	"x86",
+	"x86_64",
+	"arm",
+	"aarch64",
+	"any"
+]);
+const OsConstraintSchema = zod.z.object({
+	name: OsNameSchema.optional(),
+	version: zod.z.string().optional(),
+	arch: OsArchSchema.optional()
+});
+const RuleActionSchema = zod.z.enum(["allow", "disallow"]);
+const RuleSchema = zod.z.union([
+	zod.z.object({
+		action: RuleActionSchema,
+		os: OsConstraintSchema
+	}),
+	zod.z.object({
+		action: RuleActionSchema,
+		features: zod.z.record(zod.z.string(), zod.z.boolean())
+	}),
+	zod.z.object({ action: RuleActionSchema })
+]);
+function decodeManifest(wire) {
+	return _opys_core_binding.decodeManifest(wire);
+}
+function encodeManifest(domain) {
+	return _opys_core_binding.encodeManifest(domain);
+}
+function parseManifest(input) {
+	return _opys_core_binding.parseManifest(input);
+}
+function filterManifest(manifest, platform, features = []) {
+	return _opys_core_binding.filterManifest(manifest, platform, features);
+}
+function resolveVars(vars) {
+	return _opys_core_binding.resolveVars(vars);
+}
+function interpolate(template, vars) {
+	return _opys_core_binding.interpolate(template, vars);
+}
+function resolvedArgs(launch, platform, features = []) {
+	return _opys_core_binding.resolvedArgs(launch, platform, features);
+}
+function resolvedEnvs(launch, platform, features = []) {
+	return _opys_core_binding.resolvedEnvs(launch, platform, features);
+}
+function satisfiesRuleset(rules, platform, features = []) {
+	return _opys_core_binding.satisfiesRuleset(rules, platform, features);
+}
+function globBase(glob) {
+	return _opys_core_binding.globBase(glob);
+}
+function globToRegexSource(glob) {
+	return _opys_core_binding.globToRegexSource(glob);
+}
+/** Compile a glob to a real `RegExp` (the binding returns the source string). */
+function globToRegex(glob) {
+	return new RegExp(_opys_core_binding.globToRegexSource(glob));
+}
+const sourceUrl = (url) => ({
+	kind: "url",
+	url
+});
+const sourceFile = (file) => ({
+	kind: "file",
+	file
+});
+const sourceString = (string) => ({
+	kind: "string",
+	string
+});
+const sourcePointer = (pointer) => ({
+	kind: "pointer",
+	pointer
+});
+const sourceBytes = (bytes) => ({
+	kind: "bytes",
+	bytes: Buffer.from(bytes).toString("base64")
+});
+const isSourceUrl = (s) => s.kind === "url";
+const isSourceFile = (s) => s.kind === "file";
+const isSourceString = (s) => s.kind === "string";
+const isSourceBytes = (s) => s.kind === "bytes";
+const isSourcePointer = (s) => s.kind === "pointer";
+const extractPick = (file, into) => ({
+	kind: "pick",
+	file,
+	into
+});
+const extractScan = (matches, into, opts) => ({
+	kind: "scan",
+	matches,
+	into,
+	...opts
+});
+const extractDump = (into, opts) => ({
+	kind: "dump",
+	into,
+	...opts
+});
+const emptyRuleset = () => [];
+const allowOsRuleset = (name) => [{
+	action: "allow",
+	os: { name }
+}];
+/** Deduplicate by normalized (posix) path; later entries win. */
+function deduplicateArtifacts(artifacts) {
+	const norm = (p) => {
+		const parts = p.split("/");
+		const stack = [];
+		const lead = p.startsWith("/");
+		for (const seg of parts) {
+			if (seg === "" || seg === ".") continue;
+			if (seg === "..") {
+				if (stack.length > 0 && stack[stack.length - 1] !== "..") stack.pop();
+				else if (!lead) stack.push("..");
+			} else stack.push(seg);
+		}
+		const joined = stack.join("/");
+		if (lead) return "/" + joined;
+		return joined === "" ? "." : joined;
+	};
+	const map = /* @__PURE__ */ new Map();
+	for (const u of artifacts) map.set(norm(u.path), u);
+	return [...map.values()];
+}
+function parseShortRule(raw) {
+	if (typeof raw !== "string") return raw;
+	const parts = raw.split(".");
+	const action = parts[0];
+	if (action !== "allow" && action !== "disallow") throw new Error(`Unknown action '${action}'`);
+	const type = parts[1];
+	if (!type) return { action };
+	const rest = parts.slice(2).join(".");
+	switch (type) {
+		case "os": {
+			if (!rest) throw new Error("missing OS name");
+			const atIdx = rest.indexOf("@");
+			const name = atIdx === -1 ? rest : rest.slice(0, atIdx);
+			if (![
+				"linux",
+				"windows",
+				"osx"
+			].includes(name)) throw new Error(`invalid os name '${name}'`);
+			const version = atIdx === -1 ? void 0 : rest.slice(atIdx + 1);
+			return version ? {
+				action,
+				os: {
+					name,
+					version
+				}
+			} : {
+				action,
+				os: { name }
+			};
+		}
+		case "features":
+			if (!rest) throw new Error("missing feature name");
+			return {
+				action,
+				features: { [rest]: true }
+			};
+		case "arch": {
+			if (!rest) throw new Error("missing arch");
+			const arch = rest;
+			if (![
+				"x86",
+				"x86_64",
+				"arm",
+				"aarch64",
+				"any"
+			].includes(arch)) throw new Error(`invalid arch '${arch}'`);
+			return {
+				action,
+				os: { arch }
+			};
+		}
+		default: throw new Error(`unknown rule type '${type}'`);
+	}
+}
+function parseShortRuleset(raw) {
+	return (Array.isArray(raw) ? raw : [raw]).map(parseShortRule);
+}
+function parseValset(raw) {
+	if (!Array.isArray(raw)) throw new Error("parseValset: expected an array");
+	return raw.map((entry) => {
+		if (typeof entry === "string") return {
+			rules: [],
+			value: [entry]
+		};
+		if (entry && typeof entry === "object") {
+			const obj = entry;
+			return {
+				rules: obj.rules ? parseShortRuleset(obj.rules) : [],
+				value: Array.isArray(obj.value) ? obj.value : [obj.value]
+			};
+		}
+		throw new Error("parseValset: invalid entry");
+	});
+}
+
+//#endregion
+exports.OPYS_USER_AGENT = OPYS_USER_AGENT;
+exports.OsArchSchema = OsArchSchema;
+exports.OsNameSchema = OsNameSchema;
+exports.RuleSchema = RuleSchema;
+exports.allowOsRuleset = allowOsRuleset;
+exports.decodeManifest = decodeManifest;
+exports.deduplicateArtifacts = deduplicateArtifacts;
+exports.emptyRuleset = emptyRuleset;
+exports.encodeManifest = encodeManifest;
+exports.extractDump = extractDump;
+exports.extractPick = extractPick;
+exports.extractScan = extractScan;
+exports.fetchWithRetry = fetchWithRetry;
+exports.filterManifest = filterManifest;
+exports.globBase = globBase;
+exports.globToRegex = globToRegex;
+exports.globToRegexSource = globToRegexSource;
+exports.interpolate = interpolate;
+exports.isSourceBytes = isSourceBytes;
+exports.isSourceFile = isSourceFile;
+exports.isSourcePointer = isSourcePointer;
+exports.isSourceString = isSourceString;
+exports.isSourceUrl = isSourceUrl;
+exports.parseManifest = parseManifest;
+exports.parseShortRuleset = parseShortRuleset;
+exports.parseValset = parseValset;
+exports.resolveVars = resolveVars;
+exports.resolvedArgs = resolvedArgs;
+exports.resolvedEnvs = resolvedEnvs;
+exports.satisfiesRuleset = satisfiesRuleset;
+exports.sourceBytes = sourceBytes;
+exports.sourceFile = sourceFile;
+exports.sourcePointer = sourcePointer;
+exports.sourceString = sourceString;
+exports.sourceUrl = sourceUrl;