@opys/core 0.1.2

package/dist/index.mjs

@@ -0,0 +1,351 @@
+import { z } from "zod";
+import * as napi from "@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 = z.enum([
+	"linux",
+	"windows",
+	"osx"
+]);
+const OsArchSchema = z.enum([
+	"x86",
+	"x86_64",
+	"arm",
+	"aarch64",
+	"any"
+]);
+const OsConstraintSchema = z.object({
+	name: OsNameSchema.optional(),
+	version: z.string().optional(),
+	arch: OsArchSchema.optional()
+});
+const RuleActionSchema = z.enum(["allow", "disallow"]);
+const RuleSchema = z.union([
+	z.object({
+		action: RuleActionSchema,
+		os: OsConstraintSchema
+	}),
+	z.object({
+		action: RuleActionSchema,
+		features: z.record(z.string(), z.boolean())
+	}),
+	z.object({ action: RuleActionSchema })
+]);
+function decodeManifest(wire) {
+	return napi.decodeManifest(wire);
+}
+function encodeManifest(domain) {
+	return napi.encodeManifest(domain);
+}
+function parseManifest(input) {
+	return napi.parseManifest(input);
+}
+function filterManifest(manifest, platform, features = []) {
+	return napi.filterManifest(manifest, platform, features);
+}
+function resolveVars(vars) {
+	return napi.resolveVars(vars);
+}
+function interpolate(template, vars) {
+	return napi.interpolate(template, vars);
+}
+function resolvedArgs(launch, platform, features = []) {
+	return napi.resolvedArgs(launch, platform, features);
+}
+function resolvedEnvs(launch, platform, features = []) {
+	return napi.resolvedEnvs(launch, platform, features);
+}
+function satisfiesRuleset(rules, platform, features = []) {
+	return napi.satisfiesRuleset(rules, platform, features);
+}
+function globBase(glob) {
+	return napi.globBase(glob);
+}
+function globToRegexSource(glob) {
+	return napi.globToRegexSource(glob);
+}
+/** Compile a glob to a real `RegExp` (the binding returns the source string). */
+function globToRegex(glob) {
+	return new RegExp(napi.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
+export { OPYS_USER_AGENT, OsArchSchema, OsNameSchema, RuleSchema, allowOsRuleset, decodeManifest, deduplicateArtifacts, emptyRuleset, encodeManifest, extractDump, extractPick, extractScan, fetchWithRetry, filterManifest, globBase, globToRegex, globToRegexSource, interpolate, isSourceBytes, isSourceFile, isSourcePointer, isSourceString, isSourceUrl, parseManifest, parseShortRuleset, parseValset, resolveVars, resolvedArgs, resolvedEnvs, satisfiesRuleset, sourceBytes, sourceFile, sourcePointer, sourceString, sourceUrl };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../lib/fetch.ts","../lib/index.ts"],"sourcesContent":["/**\n * Wrap `fetch()` with bounded retry on transient network failures and\n * 5xx-class responses. Errors that won't recover from a retry (4xx,\n * `AbortError`, JSON parse failures downstream of the response) are\n * surfaced unchanged so callers handle them with their own logic.\n *\n * Network-level retries cover the AggregateError ETIMEDOUT / ECONNRESET\n * / ENOTFOUND / EAI_AGAIN / ECONNREFUSED cases that node:undici reports\n * as `TypeError: fetch failed` with a populated `cause`. Without this\n * one DNS hiccup mid-`opys launch` aborts the whole config evaluation.\n */\n\n/**\n * Default `User-Agent` for every opys HTTP request. The bare `undici`\n * agent gets rejected or rate-limited by some CDNs and by the CurseForge\n * API, so we identify ourselves. The patch component is omitted so the\n * string doesn't churn against `package.json` on every release.\n */\nexport const OPYS_USER_AGENT = 'opys/1.0';\n\nexport interface FetchRetryOptions {\n  /** Total attempts including the first. Default 4 (so up to 3 retries). */\n  attempts?: number;\n  /** Initial delay before retry #2, in ms. Default 250. */\n  baseDelayMs?: number;\n  /** Cap on per-attempt delay, in ms. Default 5000. */\n  maxDelayMs?: number;\n  /** HTTP status codes that trigger a retry. Default 408, 425, 429, 500, 502, 503, 504. */\n  retryStatuses?: ReadonlySet<number> | readonly number[];\n  /** Forward to the underlying `fetch`'s signal — abort cancels remaining retries. */\n  signal?: AbortSignal;\n  /** Callback for diagnostics / logging on each retry. */\n  onRetry?: (info: {\n    attempt: number;\n    delayMs: number;\n    error?: unknown;\n    status?: number;\n  }) => void;\n}\n\nconst DEFAULT_RETRY_STATUSES: ReadonlySet<number> = new Set([\n  408, 425, 429, 500, 502, 503, 504,\n]);\n\nconst TRANSIENT_CODES: ReadonlySet<string> = new Set([\n  'ETIMEDOUT',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'ENOTFOUND',\n  'EAI_AGAIN',\n  'EPIPE',\n  'UND_ERR_SOCKET',\n  'UND_ERR_CONNECT_TIMEOUT',\n  'UND_ERR_HEADERS_TIMEOUT',\n  'UND_ERR_BODY_TIMEOUT',\n]);\n\nfunction isTransientFetchError(err: unknown): boolean {\n  if (!err || typeof err !== 'object') return false;\n  // Direct undici/Node fetch failure surfaces as `TypeError: fetch failed`\n  // with a `cause` carrying the underlying socket error (or AggregateError\n  // when Happy Eyeballs raced multiple addresses).\n  const cause = (err as { cause?: unknown }).cause;\n  if (cause) {\n    const code = (cause as { code?: string }).code;\n    if (code && TRANSIENT_CODES.has(code)) return true;\n    const inner = (cause as { errors?: unknown[] }).errors;\n    if (Array.isArray(inner) && inner.length > 0) {\n      // AggregateError — retry only if every inner error is transient.\n      return inner.every((e) => {\n        const c = (e as { code?: string } | undefined)?.code;\n        return c !== undefined && TRANSIENT_CODES.has(c);\n      });\n    }\n  }\n  const code = (err as { code?: string }).code;\n  if (code && TRANSIENT_CODES.has(code)) return true;\n  return (\n    err instanceof TypeError &&\n    typeof (err as Error).message === 'string' &&\n    (err as Error).message.toLowerCase().includes('fetch failed')\n  );\n}\n\nfunction backoffMs(attempt: number, base: number, max: number): number {\n  // Exponential with full jitter — `attempt` is 1-indexed; first retry uses base.\n  const exp = base * 2 ** (attempt - 1);\n  const capped = Math.min(exp, max);\n  return Math.floor(capped * (0.5 + Math.random() * 0.5));\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason ?? new Error('aborted'));\n      return;\n    }\n    const t = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    const onAbort = () => {\n      clearTimeout(t);\n      reject(signal?.reason ?? new Error('aborted'));\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nexport async function fetchWithRetry(\n  input: string | URL,\n  init: RequestInit = {},\n  retry: FetchRetryOptions = {},\n): Promise<Response> {\n  const attempts = Math.max(1, retry.attempts ?? 4);\n  const base = retry.baseDelayMs ?? 250;\n  const max = retry.maxDelayMs ?? 5000;\n  const retryStatuses =\n    retry.retryStatuses instanceof Set\n      ? retry.retryStatuses\n      : retry.retryStatuses\n        ? new Set(retry.retryStatuses)\n        : DEFAULT_RETRY_STATUSES;\n  const signal = retry.signal ?? init.signal ?? undefined;\n\n  // Default the User-Agent without clobbering a caller-supplied one.\n  const headers = new Headers(init.headers);\n  if (!headers.has('user-agent')) headers.set('user-agent', OPYS_USER_AGENT);\n\n  let lastErr: unknown;\n  for (let attempt = 1; attempt <= attempts; attempt++) {\n    try {\n      const res = await fetch(input, { ...init, headers, signal });\n      if (res.ok || attempt === attempts || !retryStatuses.has(res.status)) {\n        return res;\n      }\n      // Drain so the connection isn't held open across retries.\n      try {\n        await res.body?.cancel();\n      } catch {\n        /* ignore */\n      }\n      const delay = backoffMs(attempt, base, max);\n      retry.onRetry?.({ attempt, delayMs: delay, status: res.status });\n      await sleep(delay, signal);\n    } catch (err) {\n      lastErr = err;\n      if (signal?.aborted) throw err;\n      if (!isTransientFetchError(err) || attempt === attempts) throw err;\n      const delay = backoffMs(attempt, base, max);\n      retry.onRetry?.({ attempt, delayMs: delay, error: err });\n      await sleep(delay, signal);\n    }\n  }\n  // Defensive — the loop always returns or throws above.\n  throw lastErr;\n}\n","/**\n * `@opys/core` — the frozen-manifest contract. Behaviors are backed by the\n * Rust `opys-core` crate (via napi-rs); domain types, factories and small\n * sugar helpers are hand-written TS.\n *\n * Strategy:\n *   - Algorithms that touch the manifest contract (decode, encode, resolve,\n *     filter, interpolate, glob) → typed wrappers around the Rust binding.\n *   - Domain types → hand-typed here, matching the frozen wire shape. These\n *     are pure data shapes; consumers construct them as plain JS objects.\n *   - Factories / type guards / small dedup helpers → pure TS, no boundary\n *     crossing. They are sugar over the typed shapes.\n *   - `parseShortRuleset` is implemented in TS as the shorthand sugar — the\n *     Rust binding accepts shorthand directly via `satisfiesRuleset` so the\n *     TS impl exists for consumers that need expanded `Rule` objects.\n */\n\nimport { z } from 'zod';\nimport * as napi from '@opys/core-binding';\n\n// `fetchWithRetry` is a build-time HTTP utility (used by Mojang/Forge/Java\n// plugins). It's not part of the manifest contract, so it stays as TS —\n// build-time consumers can't reach into `@opys/runtime`, so it lives here.\nexport { fetchWithRetry, OPYS_USER_AGENT } from './fetch';\nexport type { FetchRetryOptions } from './fetch';\n\n// `RuleSchema` is a zod schema typed to produce a domain `Rule`. Used by\n// the Forge recipe parser to validate upstream JSON. Kept for build-time\n// consumers — the manifest contract itself doesn't need zod (the napi\n// binding does its own serde validation).\nexport const OsNameSchema = z.enum(['linux', 'windows', 'osx']);\nexport const OsArchSchema = z.enum(['x86', 'x86_64', 'arm', 'aarch64', 'any']);\nconst OsConstraintSchema = z.object({\n  name: OsNameSchema.optional(),\n  version: z.string().optional(),\n  arch: OsArchSchema.optional(),\n});\nconst RuleActionSchema = z.enum(['allow', 'disallow']);\nexport const RuleSchema = z.union([\n  z.object({ action: RuleActionSchema, os: OsConstraintSchema }),\n  z.object({\n    action: RuleActionSchema,\n    features: z.record(z.string(), z.boolean()),\n  }),\n  z.object({ action: RuleActionSchema }),\n]);\n\n// ──────────────────────────────────────────────────────────────────────────\n// Behaviors — typed wrappers around the Rust binding.\n//\n// The codegen'd `.d.ts` types every return value as `Json` (≈ unknown), so\n// each wrapper carries one `as`-cast at the boundary. No `as unknown as`.\n// ──────────────────────────────────────────────────────────────────────────\n\nexport function decodeManifest(wire: unknown): Manifest {\n  return napi.decodeManifest(wire) as Manifest;\n}\nexport function encodeManifest(domain: Manifest): unknown {\n  return napi.encodeManifest(domain);\n}\nexport function parseManifest(input: string): Manifest {\n  return napi.parseManifest(input) as Manifest;\n}\nexport function filterManifest(\n  manifest: Manifest,\n  platform: OsOptions,\n  features: string[] = [],\n): Manifest {\n  return napi.filterManifest(manifest, platform, features) as Manifest;\n}\nexport function resolveVars(\n  vars: Record<string, string>,\n): Record<string, string> {\n  return napi.resolveVars(vars);\n}\nexport function interpolate(\n  template: string,\n  vars: Record<string, string>,\n): string {\n  return napi.interpolate(template, vars);\n}\nexport function resolvedArgs(\n  launch: Launch,\n  platform: OsOptions,\n  features: string[] = [],\n): string[] {\n  return napi.resolvedArgs(launch, platform, features);\n}\nexport function resolvedEnvs(\n  launch: Launch,\n  platform: OsOptions,\n  features: string[] = [],\n): Record<string, string> {\n  return napi.resolvedEnvs(launch, platform, features);\n}\nexport function satisfiesRuleset(\n  rules: Ruleset | string | unknown,\n  platform: OsOptions,\n  features: string[] = [],\n): boolean {\n  return napi.satisfiesRuleset(rules, platform, features);\n}\nexport function globBase(glob: string): string {\n  return napi.globBase(glob);\n}\nexport function globToRegexSource(glob: string): string {\n  return napi.globToRegexSource(glob);\n}\n\n/** Compile a glob to a real `RegExp` (the binding returns the source string). */\nexport function globToRegex(glob: string): RegExp {\n  return new RegExp(napi.globToRegexSource(glob));\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Domain types — frozen wire shape.\n// ──────────────────────────────────────────────────────────────────────────\n\nexport type OsOptions = napi.OsOptions;\nexport type OsName = 'linux' | 'windows' | 'osx';\nexport type OsArch = 'x86' | 'x86_64' | 'arm' | 'aarch64' | 'any';\n\nexport interface OsConstraint {\n  readonly name?: OsName;\n  readonly version?: string;\n  readonly arch?: OsArch;\n}\n\nexport type RuleAction = 'allow' | 'disallow';\nexport type FeatureConstraint = Record<string, boolean>;\n\nexport type Rule =\n  | { action: RuleAction; os: OsConstraint }\n  | { action: RuleAction; features: FeatureConstraint }\n  | { action: RuleAction };\n\nexport type Ruleset = Rule[];\n\nexport type Source =\n  | { readonly kind: 'url'; readonly url: string }\n  | { readonly kind: 'file'; readonly file: string }\n  | { readonly kind: 'string'; readonly string: string }\n  | { readonly kind: 'bytes'; readonly bytes: string }\n  | { readonly kind: 'pointer'; readonly pointer: string };\n\nexport type HashEntry = { sha1: string } | { sha256: string } | { md5: string };\nexport type Integrity = HashEntry | HashEntry[];\nexport type HashAlgo = 'sha1' | 'sha256' | 'md5';\n\nexport type HashRef =\n  | { readonly sha256: string }\n  | { readonly sha1: string }\n  | { readonly md5: string };\n\nexport interface IntegrityProbes {\n  readonly header?: HashRef;\n  readonly url?: HashRef;\n}\nexport interface SizeProbes {\n  readonly header?: string;\n}\nexport interface Discovery {\n  readonly integrity?: IntegrityProbes;\n  readonly size?: SizeProbes;\n}\n\nexport interface ExtractPick {\n  readonly kind: 'pick';\n  readonly file: string;\n  readonly into: string;\n}\nexport interface ExtractScan {\n  readonly kind: 'scan';\n  readonly matches: string;\n  readonly into: string;\n  readonly strip?: string[];\n  readonly includes?: string[];\n  readonly excludes?: string[];\n}\nexport interface ExtractDump {\n  readonly kind: 'dump';\n  readonly into: string;\n  readonly clean?: boolean;\n  readonly includes?: string[];\n  readonly excludes?: string[];\n}\nexport type ExtractRule = ExtractPick | ExtractScan | ExtractDump;\n\nexport interface Artifact {\n  readonly path: string;\n  readonly source: Source;\n  readonly size?: number;\n  readonly rules: Ruleset;\n  readonly integrity?: Integrity;\n  readonly discovery?: Discovery;\n  readonly metadata?: unknown;\n  readonly extract?: ExtractRule[];\n}\n\nexport interface Val {\n  readonly rules: Ruleset;\n  readonly value: string[];\n}\nexport type Valset = Val[];\n\nexport interface ConditionalVal {\n  readonly value: string;\n  readonly rules: Ruleset;\n}\nexport type ValDefs = Readonly<\n  Record<string, string | readonly ConditionalVal[]>\n>;\n\nexport interface Launch {\n  readonly command: string;\n  readonly workdir: string;\n  readonly args: Valset;\n  readonly envs: ValDefs;\n}\n\nexport interface Manifest {\n  readonly vars: ValDefs;\n  readonly launch?: Launch;\n  readonly artifacts: ReadonlyArray<Artifact>;\n  readonly restrict?: ReadonlyArray<string>;\n}\n\nexport interface PointerDescriptor {\n  readonly source: Source;\n  readonly integrity?: Integrity;\n  readonly size?: number;\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Factories — pure TS, no boundary crossing.\n// ──────────────────────────────────────────────────────────────────────────\n\nexport const sourceUrl = (url: string): Source => ({ kind: 'url', url });\nexport const sourceFile = (file: string): Source => ({ kind: 'file', file });\nexport const sourceString = (string: string): Source => ({\n  kind: 'string',\n  string,\n});\nexport const sourcePointer = (pointer: string): Source => ({\n  kind: 'pointer',\n  pointer,\n});\nexport const sourceBytes = (bytes: Uint8Array): Source => ({\n  kind: 'bytes',\n  bytes: Buffer.from(bytes).toString('base64'),\n});\n\nexport const isSourceUrl = (s: Source): s is Extract<Source, { kind: 'url' }> =>\n  s.kind === 'url';\nexport const isSourceFile = (\n  s: Source,\n): s is Extract<Source, { kind: 'file' }> => s.kind === 'file';\nexport const isSourceString = (\n  s: Source,\n): s is Extract<Source, { kind: 'string' }> => s.kind === 'string';\nexport const isSourceBytes = (\n  s: Source,\n): s is Extract<Source, { kind: 'bytes' }> => s.kind === 'bytes';\nexport const isSourcePointer = (\n  s: Source,\n): s is Extract<Source, { kind: 'pointer' }> => s.kind === 'pointer';\n\nexport const extractPick = (file: string, into: string): ExtractPick => ({\n  kind: 'pick',\n  file,\n  into,\n});\nexport const extractScan = (\n  matches: string,\n  into: string,\n  opts?: Omit<ExtractScan, 'kind' | 'matches' | 'into'>,\n): ExtractScan => ({ kind: 'scan', matches, into, ...opts });\nexport const extractDump = (\n  into: string,\n  opts?: Omit<ExtractDump, 'kind' | 'into'>,\n): ExtractDump => ({ kind: 'dump', into, ...opts });\n\nexport const emptyRuleset = (): Ruleset => [];\nexport const allowOsRuleset = (name: OsName): Ruleset => [\n  { action: 'allow', os: { name } },\n];\n\n/** Deduplicate by normalized (posix) path; later entries win. */\nexport function deduplicateArtifacts(artifacts: Artifact[]): Artifact[] {\n  const norm = (p: string): string => {\n    const parts = p.split('/');\n    const stack: string[] = [];\n    const lead = p.startsWith('/');\n    for (const seg of parts) {\n      if (seg === '' || seg === '.') continue;\n      if (seg === '..') {\n        if (stack.length > 0 && stack[stack.length - 1] !== '..') stack.pop();\n        else if (!lead) stack.push('..');\n      } else stack.push(seg);\n    }\n    const joined = stack.join('/');\n    if (lead) return '/' + joined;\n    return joined === '' ? '.' : joined;\n  };\n  const map = new Map<string, Artifact>();\n  for (const u of artifacts) map.set(norm(u.path), u);\n  return [...map.values()];\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Shorthand expansion — pure TS sugar over canonical `Rule` objects.\n// ──────────────────────────────────────────────────────────────────────────\n\ntype RawSingle = string | Rule;\ntype RawRuleset = RawSingle | RawSingle[];\n\nfunction parseShortRule(raw: RawSingle): Rule {\n  if (typeof raw !== 'string') return raw;\n  const parts = raw.split('.');\n  const action = parts[0] as RuleAction;\n  if (action !== 'allow' && action !== 'disallow') {\n    throw new Error(`Unknown action '${action}'`);\n  }\n  const type = parts[1];\n  if (!type) return { action };\n  const rest = parts.slice(2).join('.');\n  switch (type) {\n    case 'os': {\n      if (!rest) throw new Error('missing OS name');\n      const atIdx = rest.indexOf('@');\n      const name = (atIdx === -1 ? rest : rest.slice(0, atIdx)) as OsName;\n      if (!['linux', 'windows', 'osx'].includes(name))\n        throw new Error(`invalid os name '${name}'`);\n      const version = atIdx === -1 ? undefined : rest.slice(atIdx + 1);\n      return version\n        ? { action, os: { name, version } }\n        : { action, os: { name } };\n    }\n    case 'features': {\n      if (!rest) throw new Error('missing feature name');\n      return { action, features: { [rest]: true } };\n    }\n    case 'arch': {\n      if (!rest) throw new Error('missing arch');\n      const arch = rest as OsArch;\n      if (!['x86', 'x86_64', 'arm', 'aarch64', 'any'].includes(arch))\n        throw new Error(`invalid arch '${arch}'`);\n      return { action, os: { arch } };\n    }\n    default:\n      throw new Error(`unknown rule type '${type}'`);\n  }\n}\n\nexport function parseShortRuleset(raw: RawRuleset): Ruleset {\n  const arr: RawSingle[] = Array.isArray(raw) ? raw : [raw];\n  return arr.map(parseShortRule);\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// `parseValset` — used by the Mojang version-JSON mapper. Build-time-only;\n// not part of the napi boundary surface.\n// ──────────────────────────────────────────────────────────────────────────\n\nexport function parseValset(raw: unknown): Valset {\n  if (!Array.isArray(raw)) {\n    throw new Error('parseValset: expected an array');\n  }\n  return raw.map((entry): Val => {\n    if (typeof entry === 'string') return { rules: [], value: [entry] };\n    if (entry && typeof entry === 'object') {\n      const obj = entry as { rules?: unknown; value: string | string[] };\n      const rules = obj.rules ? parseShortRuleset(obj.rules as RawRuleset) : [];\n      const value = Array.isArray(obj.value) ? obj.value : [obj.value];\n      return { rules, value };\n    }\n    throw new Error('parseValset: invalid entry');\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@opys/core",
+  "version": "0.1.2",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown lib/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run tests/unit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@opys/core-binding": "^0.1.2",
+    "@opys/mojang-rules": "^0.1.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harmoniya-net/opys.git",
+    "directory": "packages/core"
+  }
+}