gm-pantry 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,43 +1,132 @@
 #!/usr/bin/env node
+import { openAsBlob } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { buildRepo, emptyRepo, hashFile, readRepoJson, relativeUrl, upsertArchive, writeRepoJson } from "./build.js";
+import { emptyRepo, serialize, upsertArchive } from "./builder.js";
+import { buildRepo, hashFile, readRepoJson, relativeUrl, writeRepoJson } from "./build.js";
 import { validateHosting } from "./hosting.js";
-import { parseRepo } from "./parse.js";
+import { loadRepo } from "./load.js";
+import { S3Store, checkCors, corsSnippets, publishRepo } from "./s3.js";
 import { verifyArchive } from "./verify.js";
 const USAGE = `gm-pantry init <dir> [--name NAME]
-gm-pantry build <dir>
+gm-pantry build <dir> [--shard-size N] [--prune]
 gm-pantry add <dir> <archive> [--id ID] [--title TITLE] [--version LABEL]
-gm-pantry validate <url|path> [--hosting]`;
+gm-pantry validate <url|path> [--hosting]
+gm-pantry publish <dir> --endpoint URL --bucket NAME --region R [--prefix P] [--shard-size N] [--path-style|--virtual-host]
+gm-pantry cors --endpoint URL --bucket NAME --region R [--prefix P] [--origin O] [--public-url URL] [--apply]
+
+publish and cors read credentials from AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN)
+or --access-key-id / --secret-access-key / --session-token.`;
+const S3_OPTIONS = {
+    endpoint: { type: "string" }, bucket: { type: "string" }, region: { type: "string" }, prefix: { type: "string" },
+    "access-key-id": { type: "string" }, "secret-access-key": { type: "string" }, "session-token": { type: "string" },
+    "path-style": { type: "boolean" }, "virtual-host": { type: "boolean" },
+    origin: { type: "string" }, "public-url": { type: "string" }, apply: { type: "boolean" },
+};
+function s3Config(o) {
+    const env = process.env;
+    const cfg = {
+        endpoint: o.endpoint ?? env.AWS_ENDPOINT_URL,
+        bucket: o.bucket,
+        region: o.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION,
+        accessKeyId: o["access-key-id"] ?? env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: o["secret-access-key"] ?? env.AWS_SECRET_ACCESS_KEY,
+        sessionToken: o["session-token"] ?? env.AWS_SESSION_TOKEN,
+    };
+    const missing = Object.entries(cfg).filter(([k, v]) => !v && k !== "sessionToken").map(([k]) => k);
+    if (missing.length)
+        throw new Error(`missing ${missing.join(", ")} (see usage)`);
+    return { ...cfg, prefix: o.prefix, forcePathStyle: o["path-style"] ? true : o["virtual-host"] ? false : undefined };
+}
+/** Builds the folder's repo.json, then uploads the archives it lists, the shards and repo.json (in that order). */
+async function publish(dir, o) {
+    const store = new S3Store(s3Config(o));
+    const shardSize = o["shard-size"] === undefined ? undefined : Number(o["shard-size"]);
+    await buildRepo(dir, o.name, undefined, { shardSize });
+    const repoJson = await readFile(join(dir, "repo.json"), "utf8");
+    const repo = JSON.parse(repoJson);
+    const shards = new Map();
+    for (const s of repo.shards ?? [])
+        shards.set(s.url, await readFile(join(dir, decodeURIComponent(s.url)), "utf8"));
+    const archives = [];
+    for (const g of [...repo.games, ...[...shards.values()].flatMap((c) => JSON.parse(c).games)]) {
+        for (const v of g.versions) {
+            const url = v.file.url;
+            if (/^([a-z][a-z0-9+.-]*:|\/)/i.test(url))
+                continue; // not ours to upload
+            archives.push({ url, body: await openAsBlob(join(dir, decodeURIComponent(url))), sha256: v.file.sha256 });
+        }
+    }
+    const t = await store.testConnection();
+    if (!t.ok)
+        return t.checks.forEach((c) => console.error(`${c.status.padEnd(4)} ${c.name}: ${c.message}`)), 1;
+    const r = await publishRepo(store, { repoJson, shards }, {
+        archives,
+        onProgress: (url, done, total) => process.stderr.write(`\r${url}: ${Math.floor((done / total) * 100)}%   `),
+    });
+    console.log(`\nuploaded ${r.uploaded.length}, skipped ${r.skipped.length}, deleted ${r.deleted.length} old shard(s)`);
+    if (!r.conditional)
+        console.log("warning: the service ignores conditional writes, so a concurrent publisher could be overwritten (last writer wins)");
+    return 0;
+}
+async function cors(o) {
+    const store = new S3Store(s3Config(o));
+    const origin = o.origin;
+    if (o.apply) {
+        await store.setCors(origin ? [origin] : ["*"]);
+        return console.log("bucket CORS configuration replaced"), 0;
+    }
+    const publicUrl = o["public-url"];
+    const snippets = corsSnippets(origin);
+    if (publicUrl) {
+        const report = await checkCors(publicUrl, origin, { writeUrl: store.url("repo.json").href });
+        for (const c of report.checks)
+            console.log(`${c.status.padEnd(4)} ${c.name}: ${c.message}`);
+        if (report.ok)
+            return 0;
+    }
+    console.log(`S3 (${snippets.s3.command}):\n${snippets.s3.json}\n\nR2 dashboard JSON (or: ${snippets.r2.command}, with the wrangler JSON below):\n${snippets.r2.json}\n${snippets.r2.wranglerJson}\n\nB2: ${snippets.b2.command}\n\nor run this command again with --apply (needs a key that may call PutBucketCors).`);
+    return publicUrl ? 1 : 0;
+}
 async function main(argv) {
     const { positionals: [cmd, target, archive], values: o } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { name: { type: "string" }, id: { type: "string" }, title: { type: "string" }, version: { type: "string" }, hosting: { type: "boolean" } },
+        options: { ...S3_OPTIONS, name: { type: "string" }, id: { type: "string" }, title: { type: "string" }, version: { type: "string" }, hosting: { type: "boolean" }, prune: { type: "boolean" }, "shard-size": { type: "string" } },
     });
-    if (!cmd || !target)
+    if (!cmd || (!target && cmd !== "cors"))
         return console.error(USAGE), 2;
-    const dir = resolve(target);
+    const dir = resolve(target ?? ".");
     switch (cmd) {
         case "init": {
             if (await readRepoJson(dir))
                 return console.error("repo.json already exists"), 1;
-            await writeRepoJson(dir, emptyRepo(o.name ?? dir.split("/").pop()));
+            await writeRepoJson(dir, (await serialize(emptyRepo(o.name ?? dir.split("/").pop()))).repoJson);
             return console.log(`wrote ${join(dir, "repo.json")}`), 0;
         }
         case "build": {
-            const { changed, count } = await buildRepo(dir, o.name);
-            return console.log(`${count} archive(s); repo.json ${changed ? "written" : "unchanged"}`), 0;
+            const { changed, count, shards, pruned } = await buildRepo(dir, o.name, undefined, {
+                shardSize: o["shard-size"] === undefined ? undefined : Number(o["shard-size"]),
+                prune: o.prune,
+            });
+            return console.log(`${count} archive(s), ${shards} shard(s), ${pruned} pruned; repo.json ${changed ? "written" : "unchanged"}`), 0;
         }
         case "add": {
             if (!archive)
                 return console.error(USAGE), 2;
             const repo = (await readRepoJson(dir)) ?? emptyRepo(o.name ?? dir.split("/").pop());
+            if (repo.shards?.length)
+                return console.error("repo.json is sharded; put the archive in the folder and run build"), 1;
+            const previous = structuredClone(repo);
             upsertArchive(repo, await relativeUrl(dir, resolve(archive)), await hashFile(resolve(archive)), o);
-            await writeRepoJson(dir, repo);
+            await writeRepoJson(dir, (await serialize(repo, { previous })).repoJson);
             return console.log("repo.json updated"), 0;
         }
+        case "publish":
+            return publish(dir, o);
+        case "cors":
+            return cors(o);
         case "validate":
             return validate(target, o.hosting === true);
         default:
@@ -47,32 +136,34 @@ async function main(argv) {
 async function validate(target, hosting) {
     let failed = false;
     const isUrl = /^https?:\/\//.test(target);
-    let json;
-    let base;
-    let dir;
-    if (isUrl) {
-        base = target;
-        const res = await fetch(target);
-        if (!res.ok)
-            return console.error(`HTTP ${res.status}`), 1;
-        json = await res.json();
-    }
-    else {
-        dir = (await stat(target)).isDirectory() ? resolve(target) : resolve(target, "..");
-        // Relative urls are checked against the folder itself below; resolution only needs a valid https base.
-        base = "https://repo.invalid/";
-        json = JSON.parse(await readFile((await stat(target)).isDirectory() ? join(target, "repo.json") : target, "utf8"));
+    // A local path is served to the loader through a virtual origin, so relative urls (shards, archives) resolve as they would online.
+    const origin = "http://localhost/";
+    let url = target;
+    let dir = "";
+    let localFetch;
+    if (!isUrl) {
+        const isDir = (await stat(target)).isDirectory();
+        dir = isDir ? resolve(target) : resolve(target, "..");
+        url = origin + (isDir ? "repo.json" : encodeURIComponent(basename(target)));
+        localFetch = async (u) => {
+            try {
+                return new Response(await readFile(join(dir, decodeURIComponent(new URL(String(u)).pathname))));
+            }
+            catch {
+                return new Response(null, { status: 404 });
+            }
+        };
     }
-    const { repo, warnings } = parseRepo(json, base);
-    console.log(`${repo.name}: ${repo.games.length} game(s)`);
+    const { repo, warnings } = await loadRepo(url, { fetch: localFetch });
+    console.log(`${repo.name}: ${repo.games.length} game(s)${repo.shards ? ` in ${repo.shards.length} shard(s) plus inline` : ""}`);
     for (const w of warnings)
         console.log(`warning ${w.path}: ${w.message}`), (failed = true);
-    if (dir) {
+    if (!isUrl) {
         for (const g of repo.games)
             for (const v of g.versions) {
-                if (!v.file.url.startsWith(base))
+                if (!v.file.url.startsWith(origin))
                     continue;
-                const path = join(dir, decodeURIComponent(v.file.url.slice(base.length)));
+                const path = join(dir, decodeURIComponent(v.file.url.slice(origin.length)));
                 try {
                     const r = await verifyArchive(await readFile(path), v.file);
                     if (!r.ok)

package/dist/hash.d.ts

@@ -0,0 +1,15 @@
+export interface HashOptions {
+    /** Called after every chunk with the bytes hashed so far. */
+    onProgress?: (bytes: number) => void;
+    signal?: AbortSignal;
+}
+export interface Hashed {
+    sha256: string;
+    size: number;
+}
+/** Hashes a stream chunk by chunk; memory use is one chunk, whatever the size. */
+export declare function hashStream(stream: ReadableStream<Uint8Array>, { onProgress, signal }?: HashOptions): Promise<Hashed>;
+/** Hashes a Blob or File (a 4 GB file works: it is read as a stream, never as one buffer). */
+export declare const hashBlob: (blob: Blob, options?: HashOptions) => Promise<Hashed>;
+/** Lowercase hex SHA-256 of bytes already in memory. */
+export declare function sha256Hex(bytes: BufferSource): Promise<string>;

package/dist/hash.js

@@ -0,0 +1,31 @@
+// Streaming SHA-256 for archives too big to buffer. Web Crypto has no incremental digest, so hash-wasm does the work.
+// Browser-safe: no Node APIs.
+import { createSHA256 } from "hash-wasm";
+/** Hashes a stream chunk by chunk; memory use is one chunk, whatever the size. */
+export async function hashStream(stream, { onProgress, signal } = {}) {
+    const hasher = await createSHA256();
+    const reader = stream.getReader();
+    let size = 0;
+    try {
+        for (;;) {
+            signal?.throwIfAborted();
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            hasher.update(value);
+            size += value.byteLength;
+            onProgress?.(size);
+        }
+    }
+    catch (e) {
+        await reader.cancel().catch(() => { });
+        throw e;
+    }
+    return { sha256: hasher.digest(), size };
+}
+/** Hashes a Blob or File (a 4 GB file works: it is read as a stream, never as one buffer). */
+export const hashBlob = (blob, options) => hashStream(blob.stream(), options);
+/** Lowercase hex SHA-256 of bytes already in memory. */
+export async function sha256Hex(bytes) {
+    return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/hosting.js

@@ -1,5 +1,5 @@
 // SPEC.md §2: does a URL actually serve a repo the way a browser consumer needs?
-import { parseRepo } from "./parse.js";
+import { parseRepo, parseShard } from "./parse.js";
 /** Fetches repo.json and the newest archive of the first game; checks CORS, Range, content types and validators. */
 export async function validateHosting(url, fetchImpl = fetch) {
     const checks = [];
@@ -25,7 +25,9 @@ export async function validateHosting(url, fetchImpl = fetch) {
     try {
         const { repo } = parseRepo(await res.json(), res.url || url);
         archive = repo.games[0]?.versions[0]?.file.url;
-        add("repo.json parses", "pass", `${repo.games.length} game(s)`);
+        add("repo.json parses", "pass", `${repo.games.length} inline game(s), ${repo.shards?.length ?? 0} shard(s)`);
+        if (repo.shards?.length)
+            archive ??= await checkShard(repo.shards[0].url, res.url || url, fetchImpl, add);
     }
     catch (e) {
         add("repo.json parses", "fail", e.message);
@@ -49,6 +51,22 @@ export async function validateHosting(url, fetchImpl = fetch) {
     }
     return report();
 }
+/** Fetches one shard; returns the first archive url in it, if any. */
+async function checkShard(url, repoUrl, fetchImpl, add) {
+    try {
+        const res = await fetchImpl(url);
+        add("shard", res.ok ? "pass" : "fail", `HTTP ${res.status}`);
+        if (!res.ok)
+            return;
+        cors(res, "shard cors", add);
+        const type = res.headers.get("content-type") ?? "";
+        add("shard content-type", /json|text\/plain/.test(type) ? "pass" : "warn", type || "missing");
+        return parseShard(await res.json(), repoUrl).games[0]?.versions[0]?.file.url;
+    }
+    catch (e) {
+        add("shard", "fail", `fetch failed (no CORS or unreachable): ${e.message}`);
+    }
+}
 function cors(res, name, add) {
     const v = res.headers.get("access-control-allow-origin");
     add(name, v === "*" ? "pass" : "fail", `Access-Control-Allow-Origin: ${v ?? "missing"}`);

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-export type { ArchiveFile, Format, Game, Meta, Repo, Version, Warning } from "./types.ts";
-export { LIMITS, RepoError, isSecureUrl, parseRepo, resolveUrl } from "./parse.ts";
+export type { ArchiveFile, Format, Game, Meta, Repo, Shard, Version, Warning } from "./types.ts";
+export { LIMITS, RepoError, isSecureUrl, parseRepo, parseShard, resolveUrl } from "./parse.ts";
+export { loadRepo, type LoadOptions, type ShardCache } from "./load.ts";
 export { verifyArchive, type VerifyResult } from "./verify.ts";
 export { validateHosting, type Check, type HostingReport } from "./hosting.ts";
+export { hashBlob, hashStream, type HashOptions, type Hashed } from "./hash.ts";
+export { addVersion, emptyRepo, inlineShards, removeGame, removeVersion, serialize, slug, splitShards, updateGame, type GamePatch, type Json, type NewVersion, type SerializeOptions, type Serialized, } from "./builder.ts";

package/dist/index.js

@@ -1,3 +1,6 @@
-export { LIMITS, RepoError, isSecureUrl, parseRepo, resolveUrl } from "./parse.js";
+export { LIMITS, RepoError, isSecureUrl, parseRepo, parseShard, resolveUrl } from "./parse.js";
+export { loadRepo } from "./load.js";
 export { verifyArchive } from "./verify.js";
 export { validateHosting } from "./hosting.js";
+export { hashBlob, hashStream } from "./hash.js";
+export { addVersion, emptyRepo, inlineShards, removeGame, removeVersion, serialize, slug, splitShards, updateGame, } from "./builder.js";

package/dist/load.d.ts

@@ -0,0 +1,19 @@
+import type { Repo, Warning } from "./types.ts";
+/** Lets a consumer keep shards by hash: a hit skips the network. */
+export interface ShardCache {
+    get(sha256: string): Promise<Uint8Array | undefined>;
+    put(sha256: string, bytes: Uint8Array): Promise<void>;
+}
+export interface LoadOptions {
+    fetch?: typeof fetch;
+    /** Parallel shard downloads. Default 4. */
+    concurrency?: number;
+    /** Called after each shard is settled, loaded or skipped. */
+    onProgress?: (done: number, total: number) => void;
+    shardCache?: ShardCache;
+}
+/** Fetches repo.json and its shards. Throws RepoError only if repo.json itself is unusable; a bad shard is skipped and reported. */
+export declare function loadRepo(url: string, opts?: LoadOptions): Promise<{
+    repo: Repo;
+    warnings: Warning[];
+}>;

package/dist/load.js

@@ -0,0 +1,61 @@
+// SPEC.md §4.6: loading a whole repo, shards included. Web Crypto and fetch only, so it runs in a browser.
+import { RepoError, parseRepo, parseShard } from "./parse.js";
+import { verifyArchive } from "./verify.js";
+/** Fetches repo.json and its shards. Throws RepoError only if repo.json itself is unusable; a bad shard is skipped and reported. */
+export async function loadRepo(url, opts = {}) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new RepoError(`repo.json: HTTP ${res.status}`);
+    const entryUrl = res.url || url;
+    const { repo, warnings } = parseRepo(await res.json(), entryUrl);
+    const shards = repo.shards ?? [];
+    const seen = new Set(repo.games.map((g) => g.id));
+    const results = new Array(shards.length);
+    let next = 0;
+    let done = 0;
+    const worker = async () => {
+        while (next < shards.length) {
+            const i = next++;
+            results[i] = await loadShard(shards[i], fetchImpl, opts.shardCache);
+            opts.onProgress?.(++done, shards.length);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(opts.concurrency ?? 4, shards.length)) }, worker));
+    // Merged in shard order, after all downloads, so the result does not depend on which one finished first.
+    results.forEach((r, i) => {
+        if ("error" in r)
+            return void warnings.push({ path: `shards[${i}]`, message: `skipped: ${r.error}` });
+        try {
+            const shard = parseShard(r.json, entryUrl, seen);
+            repo.games.push(...shard.games);
+            for (const w of shard.warnings)
+                warnings.push({ path: `shards[${i}].${w.path}`, message: w.message });
+        }
+        catch (e) {
+            warnings.push({ path: `shards[${i}]`, message: `skipped: ${e.message}` });
+        }
+    });
+    return { repo, warnings };
+}
+async function loadShard(shard, fetchImpl, cache) {
+    try {
+        let bytes = await cache?.get(shard.sha256);
+        if (bytes && !(await verifyArchive(bytes, shard)).ok)
+            bytes = undefined; // a corrupt cache entry is a miss
+        if (!bytes) {
+            const res = await fetchImpl(shard.url);
+            if (!res.ok)
+                return { error: `HTTP ${res.status}` };
+            bytes = new Uint8Array(await res.arrayBuffer());
+            const check = await verifyArchive(bytes, shard);
+            if (!check.ok)
+                return { error: `${check.reason} is ${check.actual}, repo.json says ${check.expected}` };
+            await cache?.put(shard.sha256, bytes).catch(() => { }); // a failing cache must not lose the shard
+        }
+        return { json: JSON.parse(new TextDecoder().decode(bytes)) };
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+}

package/dist/parse.d.ts

@@ -1,9 +1,10 @@
-import type { Repo, Warning } from "./types.ts";
+import type { Game, Repo, Warning } from "./types.ts";
 /** The caps of SPEC.md §4.4. */
 export declare const LIMITS: {
     readonly name: 80;
     readonly repoDescription: 280;
-    readonly games: 10000;
+    readonly gamesPerFile: 2000;
+    readonly shards: 1000;
     readonly id: 64;
     readonly title: 200;
     readonly versions: 200;
@@ -32,3 +33,8 @@ export declare function parseRepo(json: unknown, baseUrl: string): {
     repo: Repo;
     warnings: Warning[];
 };
+/** Parses a shard file already decoded from JSON (SPEC.md §3.7). `baseUrl` is the url of repo.json, not of the shard. `seen` carries ids already taken elsewhere in the repo. Throws RepoError. */
+export declare function parseShard(json: unknown, baseUrl: string, seen?: Set<string>): {
+    games: Game[];
+    warnings: Warning[];
+};

package/dist/parse.js

@@ -4,7 +4,8 @@
 export const LIMITS = {
     name: 80,
     repoDescription: 280,
-    games: 10_000,
+    gamesPerFile: 2000,
+    shards: 1000,
     id: 64,
     title: 200,
     versions: 200,
@@ -67,8 +68,12 @@ export function parseRepo(json, baseUrl) {
         throw new RepoError(`"name" must be a non-empty string of at most ${LIMITS.name} characters`);
     if (!validDate(json.updated))
         throw new RepoError(`"updated" must be an ISO-8601 date or timestamp`);
-    if (!Array.isArray(json.games))
+    if (json.games === undefined && json.shards === undefined)
+        throw new RepoError(`"games" or "shards" must be present`);
+    if (json.games !== undefined && !Array.isArray(json.games))
         throw new RepoError(`"games" must be an array`);
+    if (json.shards !== undefined && !Array.isArray(json.shards))
+        throw new RepoError(`"shards" must be an array`);
     const repo = { schema: 1, name, updated: json.updated, games: [] };
     const description = text(json.description, LIMITS.repoDescription);
     if (description)
@@ -79,8 +84,32 @@ export function parseRepo(json, baseUrl) {
         repo.homepage = json.homepage;
     else if (json.homepage !== undefined)
         warn("homepage", "dropped: not an https url");
-    const seen = new Set();
-    json.games.slice(0, LIMITS.games).forEach((entry, i) => {
+    repo.games = parseGames(json.games ?? [], baseUrl, new Set(), warn);
+    if (json.shards) {
+        const shards = [];
+        json.shards.slice(0, LIMITS.shards).forEach((entry, i) => {
+            const shard = parseShardRef(entry, `shards[${i}]`, baseUrl, warn);
+            if (shard)
+                shards.push(shard);
+        });
+        if (json.shards.length > LIMITS.shards)
+            warn("shards", `only the first ${LIMITS.shards} entries are read`);
+        if (shards.length)
+            repo.shards = shards;
+    }
+    return { repo, warnings };
+}
+/** Parses a shard file already decoded from JSON (SPEC.md §3.7). `baseUrl` is the url of repo.json, not of the shard. `seen` carries ids already taken elsewhere in the repo. Throws RepoError. */
+export function parseShard(json, baseUrl, seen = new Set()) {
+    const warnings = [];
+    if (!isObject(json) || !Array.isArray(json.games))
+        throw new RepoError(`a shard must be an object with a "games" array`);
+    const games = parseGames(json.games, baseUrl, seen, (path, message) => warnings.push({ path, message }));
+    return { games, warnings };
+}
+function parseGames(list, baseUrl, seen, warn) {
+    const games = [];
+    list.slice(0, LIMITS.gamesPerFile).forEach((entry, i) => {
         const path = `games[${i}]`;
         const game = parseGame(entry, path, baseUrl, warn);
         if (!game)
@@ -88,11 +117,28 @@ export function parseRepo(json, baseUrl) {
         if (seen.has(game.id))
             return warn(path, `skipped: duplicate id "${game.id}"`);
         seen.add(game.id);
-        repo.games.push(game);
+        games.push(game);
     });
-    if (json.games.length > LIMITS.games)
-        warn("games", `only the first ${LIMITS.games} entries are read`);
-    return { repo, warnings };
+    if (list.length > LIMITS.gamesPerFile)
+        warn("games", `only the first ${LIMITS.gamesPerFile} entries are read`);
+    return games;
+}
+function parseShardRef(entry, path, baseUrl, warn) {
+    if (!isObject(entry))
+        return void warn(path, "skipped: not an object");
+    const url = typeof entry.url === "string" && entry.url.length <= LIMITS.url ? resolveUrl(entry.url, baseUrl) : undefined;
+    if (url === undefined || !isSecureUrl(url))
+        return void warn(path, `skipped: "url" must resolve to an https url`);
+    if (typeof entry.sha256 !== "string" || !SHA256.test(entry.sha256))
+        return void warn(path, `skipped: "sha256" must be 64 lowercase hex digits`);
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0)
+        return void warn(path, `skipped: "size" must be a non-negative integer`);
+    const shard = { url, sha256: entry.sha256, size: entry.size };
+    if (Number.isSafeInteger(entry.count) && entry.count >= 0)
+        shard.count = entry.count;
+    else if (entry.count !== undefined)
+        warn(`${path}.count`, "dropped: not a non-negative integer");
+    return shard;
 }
 function parseGame(entry, path, baseUrl, warn) {
     if (!isObject(entry))