gm-pantry 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dapper Mink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# GM-Pantry
+
+A format for game repositories: a static directory served over HTTPS that lists game archives, with
+a TypeScript library, a validator and a CLI. The specification is [SPEC.md](SPEC.md), at revision 1.
+
+## The format at a glance
+
+A repo is a directory. Its entry point is `repo.json`, and the URL of that file is the repo's identity.
+
+```json
+{
+  "schema": 1,
+  "name": "Example Pantry",
+  "updated": "2026-11-15",
+  "games": [
+    {
+      "id": "my-fangame",
+      "title": "My Fangame",
+      "work": { "delfruit": 1234 },
+      "versions": [
+        { "version": "1.0", "file": { "url": "My_Fangame.zip", "sha256": "<64 hex digits>", "size": 1048576 } }
+      ]
+    }
+  ]
+}
+```
+
+- Archives are stored exactly as distributed and are never modified. Their sha256 is checked after
+  download; a mismatch discards the file.
+- File urls may be relative, so a mirror of the directory is a working repo.
+- Unknown fields are ignored; a malformed game or version is skipped and the rest of the repo still loads.
+- A big repo lists content-addressed `shards` (files of at most 1 000 games) instead of inlining its
+  games; a bad or tampered shard is skipped and the rest still loads.
+- Nothing lists or indexes repos. A private repo is an unguessable URL.
+
+## CLI
+
+```
+npx gm-pantry init <dir> [--name NAME]
+npx gm-pantry build <dir> [--shard-size N] [--prune]
+npx gm-pantry add <dir> <archive> [--id ID] [--title TITLE] [--version LABEL]
+npx gm-pantry validate <url|path> [--hosting]
+```
+
+- `build` hashes every `.zip`, `.7z` and `.rar` at the top of the folder (streaming), derives each
+  game's id and title from the file name, and writes `repo.json`. An existing `repo.json` is kept:
+  hand-edited metadata, other versions and unknown fields survive, and a changed archive only has its
+  hash and size refreshed. By default it never deletes an entry (`--prune` removes games whose archive file is gone from the
+  folder). Above `--shard-size` games (default 1000) it writes `shards/<sha16>.json` files of at most
+  N games sorted by id plus an entry `repo.json`, deletes the shards it generated earlier that are no
+  longer referenced, and gives the same bytes for the same input; at or below it the output stays
+  inline. `add` refuses a sharded repo: put the archive in the folder and run `build`. `updated` moves only when something changed, so
+  a rebuild of an unchanged folder is byte-identical.
+- `add` does the same for one archive, which must be inside the directory, as a new newest version.
+- `validate` parses a `repo.json` (a URL, a folder or a file) and reports every skipped entry; for a
+  folder it also loads every shard and checks each archive's hash. `--hosting` (URL only) fetches `repo.json` and a sample
+  archive and checks CORS, Range, content types and validators. Exit code 1 on any problem.
+
+## Library
+
+```ts
+import { loadRepo, parseRepo, parseShard, verifyArchive, validateHosting } from "gm-pantry";
+
+// repo.json plus every shard, verified by hash; throws RepoError only if repo.json is unusable
+const { repo, warnings } = await loadRepo(url, { concurrency: 4, onProgress: (done, total) => {}, shardCache });
+// parseRepo(json, url) and parseShard(json, url) read the two kinds of file you fetched yourself
+// shardCache is { get(sha256), put(sha256, bytes) }: persist shards by hash and a hit skips the network
+const result = await verifyArchive(bytes, repo.games[0].versions[0].file); // { ok: true } or { ok: false, ... }
+```
+
+The library uses Web Crypto and `fetch` only, so it runs in browsers and Node. Only the CLI uses Node
+APIs.
+
+## Hosting
+
+The host must serve HTTPS and send `Access-Control-Allow-Origin: *` on `repo.json` and the archives.
+`Range` on archives, `ETag`/`Last-Modified` on `repo.json`, and a long `Cache-Control: immutable` on
+shards (they are named after their hash) are recommended. Check with
+`gm-pantry validate <url> --hosting`.
+
+- **GitHub Pages** serves `Access-Control-Allow-Origin: *` already. Keep archives under its size limits.
+- **Amazon S3** needs a CORS rule on the bucket:
+
+  ```json
+  [{ "AllowedOrigins": ["*"], "AllowedMethods": ["GET", "HEAD"], "AllowedHeaders": ["Range", "If-None-Match", "If-Modified-Since"], "ExposeHeaders": ["Content-Length", "Content-Range", "ETag"], "MaxAgeSeconds": 86400 }]
+  ```
+
+- **Cloudflare R2** takes the same rule in the bucket's CORS policy (dashboard, Settings, CORS policy).
+- **Backblaze B2** needs CORS rules on the bucket allowing `GET`/`HEAD` from any origin (its S3
+  compatible API accepts the S3 rule above).
+
+## Development
+
+```
+pnpm install
+pnpm run typecheck && pnpm test && pnpm run build
+```
+
+`conformance/` holds `repo.json` inputs with their expected result; a reader in any language can use them.
+
+MIT licensed.

package/dist/build.d.ts

@@ -0,0 +1,42 @@
+type Json = Record<string, any>;
+export declare const ARCHIVE_EXTENSIONS: string[];
+export declare function hashFile(path: string): Promise<{
+    sha256: string;
+    size: number;
+}>;
+export declare const slug: (s: string) => string;
+export declare function readRepoJson(dir: string): Promise<Json | undefined>;
+export declare function emptyRepo(name: string): Json;
+/** Adds an archive, or refreshes sha256 and size of the version that already points at it. */
+export declare function upsertArchive(repo: Json, url: string, hashed: {
+    sha256: string;
+    size: number;
+}, opts?: {
+    id?: string;
+    title?: string;
+    version?: string;
+}): void;
+/** Serialises repo.json; `updated` moves only when something else changed, so a rebuild is byte-identical. */
+export declare function writeRepoJson(dir: string, repo: Json, now?: string): Promise<boolean>;
+/** Every archive in `dir` (top level only), by name, as repo-relative urls. */
+export declare function listArchives(dir: string): Promise<string[]>;
+/** Splits games, sorted by id, into content-addressed shard files of at most `size` games (SPEC.md §3.7). Pure: same input, same bytes. */
+export declare function splitShards(games: Json[], size: number): {
+    files: Map<string, string>;
+    shards: Json[];
+};
+export interface BuildOptions {
+    /** Games per shard; at or below this many games the output stays inline. Default 1000. */
+    shardSize?: number;
+    /** Remove games whose archive file is gone from the folder. By default entries are kept. */
+    prune?: boolean;
+}
+export declare function buildRepo(dir: string, name?: string, now?: string, { shardSize, prune }?: BuildOptions): Promise<{
+    changed: boolean;
+    count: number;
+    shards: number;
+    pruned: number;
+}>;
+/** The repo-relative url of an archive that must live inside the repo directory. */
+export declare function relativeUrl(dir: string, archive: string): Promise<string>;
+export {};

package/dist/build.js

@@ -0,0 +1,165 @@
+// Writing a repo.json (SPEC.md §7): node-only, kept out of the library entry point.
+// Works on the raw JSON, never on a parsed Repo, so hand-edited fields and unknown fields survive.
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { basename, extname, join, relative, sep } from "node:path";
+import { LIMITS } from "./parse.js";
+export const ARCHIVE_EXTENSIONS = [".zip", ".7z", ".rar"];
+export async function hashFile(path) {
+    const hash = createHash("sha256");
+    let size = 0;
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+        size += chunk.length;
+    }
+    return { sha256: hash.digest("hex"), size };
+}
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+const SHARD_FILE = /^[0-9a-f]{16}\.json$/;
+const isRelative = (url) => !/^([a-z][a-z0-9+.-]*:|\/)/i.test(url);
+export const slug = (s) => s.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+/** "My_Game-v2.zip" -> "My Game-v2" */
+const titleOf = (file) => basename(file, extname(file)).replace(/_+/g, " ").trim();
+export async function readRepoJson(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, "repo.json"), "utf8"));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw new Error(`repo.json in ${dir} is unreadable: ${e.message}`);
+    }
+}
+export function emptyRepo(name) {
+    return { schema: 1, name, updated: new Date().toISOString(), games: [] };
+}
+/** Adds an archive, or refreshes sha256 and size of the version that already points at it. */
+export function upsertArchive(repo, url, hashed, opts = {}) {
+    const file = { url, ...hashed };
+    const games = (repo.games ??= []);
+    for (const game of games) {
+        for (const v of game.versions ?? []) {
+            if (v.file?.url === url) {
+                v.file = { ...v.file, ...hashed };
+                return;
+            }
+        }
+    }
+    const id = opts.id ?? slug(titleOf(decodeURIComponent(url)));
+    if (id === "")
+        throw new Error(`cannot derive an id from ${url}; pass --id`);
+    let game = games.find((g) => g.id === id);
+    if (!game) {
+        game = { id, title: opts.title ?? titleOf(decodeURIComponent(url)), versions: [] };
+        games.push(game);
+        games.sort(byId);
+    }
+    game.versions.unshift({ version: opts.version ?? String(game.versions.length + 1), file });
+}
+/** Serialises repo.json; `updated` moves only when something else changed, so a rebuild is byte-identical. */
+export async function writeRepoJson(dir, repo, now = new Date().toISOString()) {
+    const before = await readFile(join(dir, "repo.json"), "utf8").catch(() => undefined);
+    const stable = (r) => JSON.stringify({ ...r, updated: undefined });
+    let old;
+    try {
+        old = before ? JSON.parse(before) : undefined;
+    }
+    catch { /* rewritten below */ }
+    const next = { ...repo, updated: old && stable(old) === stable(repo) ? old.updated : now };
+    const out = JSON.stringify(next, null, 2) + "\n";
+    if (out === before)
+        return false;
+    await writeFile(join(dir, "repo.json"), out);
+    return true;
+}
+/** Every archive in `dir` (top level only), by name, as repo-relative urls. */
+export async function listArchives(dir) {
+    return (await readdir(dir, { withFileTypes: true }))
+        .filter((e) => e.isFile() && ARCHIVE_EXTENSIONS.includes(extname(e.name).toLowerCase()))
+        .map((e) => e.name)
+        .sort();
+}
+/** Splits games, sorted by id, into content-addressed shard files of at most `size` games (SPEC.md §3.7). Pure: same input, same bytes. */
+export function splitShards(games, size) {
+    const sorted = [...games].sort(byId);
+    const files = new Map();
+    const shards = [];
+    for (let i = 0; i < sorted.length; i += size) {
+        const chunk = sorted.slice(i, i + size);
+        const content = JSON.stringify({ games: chunk }) + "\n";
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        const url = `shards/${sha256.slice(0, 16)}.json`;
+        files.set(url, content);
+        shards.push({ url, sha256, size: Buffer.byteLength(content), count: chunk.length });
+    }
+    return { files, shards };
+}
+/** Moves the games of a sharded repo.json inline, so build can edit one flat list. */
+async function inlineShards(dir, repo) {
+    for (const shard of repo.shards ?? []) {
+        if (!isRelative(shard.url))
+            throw new Error(`shard ${shard.url} is not a relative url; build can only rewrite shards inside ${dir}`);
+        const file = join(dir, decodeURIComponent(shard.url));
+        try {
+            (repo.games ??= []).push(...JSON.parse(await readFile(file, "utf8")).games);
+        }
+        catch (e) {
+            throw new Error(`shard ${file} is unreadable: ${e.message}`);
+        }
+    }
+    delete repo.shards;
+}
+/** Drops versions whose relative archive url no longer exists in `dir`, then games left with none. */
+async function pruneMissing(dir, repo) {
+    for (const game of repo.games) {
+        const kept = [];
+        for (const v of game.versions ?? []) {
+            const url = v.file?.url ?? "";
+            if (!isRelative(url) || (await stat(join(dir, decodeURIComponent(url))).then(() => true, () => false)))
+                kept.push(v);
+        }
+        game.versions = kept;
+    }
+    const before = repo.games.length;
+    repo.games = repo.games.filter((g) => g.versions.length > 0);
+    return before - repo.games.length;
+}
+export async function buildRepo(dir, name, now, { shardSize = 1000, prune = false } = {}) {
+    if (!Number.isInteger(shardSize) || shardSize < 1 || shardSize > LIMITS.gamesPerFile) {
+        throw new Error(`--shard-size must be an integer from 1 to ${LIMITS.gamesPerFile}`);
+    }
+    const repo = (await readRepoJson(dir)) ?? emptyRepo(name ?? basename(dir));
+    await inlineShards(dir, repo);
+    const files = await listArchives(dir);
+    for (const f of files)
+        upsertArchive(repo, encodeURIComponent(f), await hashFile(join(dir, f)));
+    const pruned = prune ? await pruneMissing(dir, repo) : 0;
+    let out = repo;
+    let written = new Map();
+    if (repo.games.length > shardSize) {
+        const { files: shardFiles, shards } = splitShards(repo.games, shardSize);
+        if (shards.length > LIMITS.shards)
+            throw new Error(`${shards.length} shards exceeds the cap of ${LIMITS.shards}; raise --shard-size`);
+        await mkdir(join(dir, "shards"), { recursive: true });
+        for (const [url, content] of shardFiles)
+            await writeFile(join(dir, url), content);
+        written = shardFiles;
+        out = { ...repo, games: [], shards };
+    }
+    const changed = await writeRepoJson(dir, out, now);
+    // Only files shaped like ours are touched; anything else in shards/ is the owner's.
+    for (const f of await readdir(join(dir, "shards")).catch(() => [])) {
+        if (SHARD_FILE.test(f) && !written.has(`shards/${f}`))
+            await rm(join(dir, "shards", f));
+    }
+    return { changed, count: files.length, shards: written.size, pruned };
+}
+/** The repo-relative url of an archive that must live inside the repo directory. */
+export async function relativeUrl(dir, archive) {
+    await stat(archive);
+    const rel = relative(dir, archive);
+    if (rel.startsWith("..") || rel.startsWith(sep))
+        throw new Error(`${archive} is outside the repo directory ${dir}`);
+    return rel.split(sep).map(encodeURIComponent).join("/");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { readFile, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { buildRepo, emptyRepo, hashFile, readRepoJson, relativeUrl, upsertArchive, writeRepoJson } from "./build.js";
+import { validateHosting } from "./hosting.js";
+import { loadRepo } from "./load.js";
+import { verifyArchive } from "./verify.js";
+const USAGE = `gm-pantry init <dir> [--name NAME]
+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]`;
+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" }, prune: { type: "boolean" }, "shard-size": { type: "string" } },
+    });
+    if (!cmd || !target)
+        return console.error(USAGE), 2;
+    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()));
+            return console.log(`wrote ${join(dir, "repo.json")}`), 0;
+        }
+        case "build": {
+            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;
+            upsertArchive(repo, await relativeUrl(dir, resolve(archive)), await hashFile(resolve(archive)), o);
+            await writeRepoJson(dir, repo);
+            return console.log("repo.json updated"), 0;
+        }
+        case "validate":
+            return validate(target, o.hosting === true);
+        default:
+            return console.error(USAGE), 2;
+    }
+}
+async function validate(target, hosting) {
+    let failed = false;
+    const isUrl = /^https?:\/\//.test(target);
+    // 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 } = 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 (!isUrl) {
+        for (const g of repo.games)
+            for (const v of g.versions) {
+                if (!v.file.url.startsWith(origin))
+                    continue;
+                const path = join(dir, decodeURIComponent(v.file.url.slice(origin.length)));
+                try {
+                    const r = await verifyArchive(await readFile(path), v.file);
+                    if (!r.ok)
+                        console.log(`error ${g.id} ${v.version}: ${r.reason} is ${r.actual}, repo.json says ${r.expected}`), (failed = true);
+                }
+                catch {
+                    console.log(`error ${g.id} ${v.version}: ${path} is missing`), (failed = true);
+                }
+            }
+    }
+    if (hosting) {
+        if (!isUrl)
+            return console.error("--hosting needs a url"), 2;
+        const report = await validateHosting(target);
+        for (const c of report.checks)
+            console.log(`${c.status.padEnd(4)} ${c.name}: ${c.message}`);
+        if (!report.ok)
+            failed = true;
+    }
+    return failed ? 1 : 0;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => (console.error(e.message), process.exit(1)));

package/dist/hosting.d.ts

@@ -0,0 +1,11 @@
+export interface Check {
+    name: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+}
+export interface HostingReport {
+    ok: boolean;
+    checks: Check[];
+}
+/** Fetches repo.json and the newest archive of the first game; checks CORS, Range, content types and validators. */
+export declare function validateHosting(url: string, fetchImpl?: typeof fetch): Promise<HostingReport>;

package/dist/hosting.js

@@ -0,0 +1,73 @@
+// SPEC.md §2: does a URL actually serve a repo the way a browser consumer needs?
+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 = [];
+    const add = (name, status, message) => checks.push({ name, status, message });
+    const report = () => ({ ok: !checks.some((c) => c.status === "fail"), checks });
+    let res;
+    try {
+        res = await fetchImpl(url);
+    }
+    catch (e) {
+        add("repo.json", "fail", `fetch failed (no CORS or unreachable): ${e.message}`);
+        return report();
+    }
+    add("repo.json", res.ok ? "pass" : "fail", `HTTP ${res.status}`);
+    if (!res.ok)
+        return report();
+    cors(res, "repo.json cors", add);
+    const type = res.headers.get("content-type") ?? "";
+    add("repo.json content-type", /json|text\/plain/.test(type) ? "pass" : "warn", type || "missing");
+    const hasValidator = res.headers.has("etag") || res.headers.has("last-modified");
+    add("repo.json validators", hasValidator ? "pass" : "warn", hasValidator ? "ETag or Last-Modified present" : "no ETag or Last-Modified");
+    let archive;
+    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} 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);
+        return report();
+    }
+    if (!archive)
+        return add("archive", "warn", "no game to sample"), report();
+    try {
+        const a = await fetchImpl(archive, { headers: { Range: "bytes=0-0" } });
+        await a.body?.cancel();
+        add("archive", a.ok ? "pass" : "fail", `HTTP ${a.status}`);
+        if (!a.ok)
+            return report();
+        cors(a, "archive cors", add);
+        add("archive range", a.status === 206 ? "pass" : "warn", a.status === 206 ? "206 Partial Content" : `Range ignored (HTTP ${a.status}); optional`);
+        const t = a.headers.get("content-type") ?? "";
+        add("archive content-type", /text\/html/.test(t) ? "fail" : "pass", t || "missing");
+    }
+    catch (e) {
+        add("archive", "fail", `fetch failed (no CORS or unreachable): ${e.message}`);
+    }
+    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

@@ -0,0 +1,5 @@
+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";

package/dist/index.js

@@ -0,0 +1,4 @@
+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";

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

@@ -0,0 +1,40 @@
+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 gamesPerFile: 2000;
+    readonly shards: 1000;
+    readonly id: 64;
+    readonly title: 200;
+    readonly versions: 200;
+    readonly versionLabel: 64;
+    readonly url: 2048;
+    readonly metaText: 2000;
+    readonly author: 120;
+    readonly notes: 2000;
+    readonly tags: 20;
+    readonly tag: 40;
+    readonly screenshots: 20;
+    readonly links: 20;
+    readonly linkName: 80;
+    readonly work: 8;
+    readonly workKey: 32;
+    readonly workText: 128;
+};
+export declare class RepoError extends Error {
+}
+/** Resolves a possibly relative url against the url of repo.json. Returns undefined if it is not a url. */
+export declare function resolveUrl(url: string, baseUrl: string): string | undefined;
+/** https, or http on a loopback host (so a repo can be tried locally). */
+export declare function isSecureUrl(url: unknown): url is string;
+/** Parses a repo.json already decoded from JSON. `baseUrl` is where it was fetched from. Throws RepoError. */
+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

@@ -0,0 +1,264 @@
+// SPEC.md §4 and §5: reading a repo.json. Entries that are malformed are skipped and reported;
+// advisory fields that are malformed are dropped and reported. Only a broken envelope throws.
+/** The caps of SPEC.md §4.4. */
+export const LIMITS = {
+    name: 80,
+    repoDescription: 280,
+    gamesPerFile: 2000,
+    shards: 1000,
+    id: 64,
+    title: 200,
+    versions: 200,
+    versionLabel: 64,
+    url: 2048,
+    metaText: 2000,
+    author: 120,
+    notes: 2000,
+    tags: 20,
+    tag: 40,
+    screenshots: 20,
+    links: 20,
+    linkName: 80,
+    work: 8,
+    workKey: 32,
+    workText: 128,
+};
+export class RepoError extends Error {
+}
+const ID = /^[a-z0-9][a-z0-9._-]*$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const WORK_KEY = /^[a-z][a-z0-9_-]*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}(T[\d:.]+(Z|[+-]\d{2}:\d{2}))?$/;
+const FORMATS = ["zip", "7z", "rar"];
+/** Resolves a possibly relative url against the url of repo.json. Returns undefined if it is not a url. */
+export function resolveUrl(url, baseUrl) {
+    try {
+        return new URL(url, baseUrl).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** https, or http on a loopback host (so a repo can be tried locally). */
+export function isSecureUrl(url) {
+    if (typeof url !== "string" || url.length > LIMITS.url)
+        return false;
+    try {
+        const u = new URL(url);
+        return u.protocol === "https:" ||
+            (u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v, max) => typeof v === "string" && v.trim() !== "" && v.trim().length <= max ? v.trim() : undefined;
+const validDate = (v) => typeof v === "string" && DATE.test(v) && !isNaN(Date.parse(v));
+/** Parses a repo.json already decoded from JSON. `baseUrl` is where it was fetched from. Throws RepoError. */
+export function parseRepo(json, baseUrl) {
+    const warnings = [];
+    const warn = (path, message) => warnings.push({ path, message });
+    if (!isObject(json))
+        throw new RepoError("repo.json is not an object");
+    if (json.schema !== 1)
+        throw new RepoError(`unsupported schema ${JSON.stringify(json.schema)}; this reader implements 1`);
+    const name = text(json.name, LIMITS.name);
+    if (name === undefined)
+        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 (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)
+        repo.description = description;
+    else if (json.description !== undefined)
+        warn("description", "dropped: not a string of 1-280 characters");
+    if (isSecureUrl(json.homepage))
+        repo.homepage = json.homepage;
+    else if (json.homepage !== undefined)
+        warn("homepage", "dropped: not an https url");
+    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)
+            return;
+        if (seen.has(game.id))
+            return warn(path, `skipped: duplicate id "${game.id}"`);
+        seen.add(game.id);
+        games.push(game);
+    });
+    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))
+        return void warn(path, "skipped: not an object");
+    if (typeof entry.id !== "string" || entry.id.length > LIMITS.id || !ID.test(entry.id)) {
+        return void warn(path, `skipped: "id" must match ${ID} and be at most ${LIMITS.id} characters`);
+    }
+    const title = text(entry.title, LIMITS.title);
+    if (title === undefined)
+        return void warn(path, `skipped: "title" must be a non-empty string of at most ${LIMITS.title} characters`);
+    if (!Array.isArray(entry.versions))
+        return void warn(path, `skipped: "versions" must be an array`);
+    const versions = [];
+    entry.versions.slice(0, LIMITS.versions).forEach((v, i) => {
+        const version = parseVersion(v, `${path}.versions[${i}]`, baseUrl, warn);
+        if (version)
+            versions.push(version);
+    });
+    if (versions.length === 0)
+        return void warn(path, "skipped: no valid version");
+    const game = { id: entry.id, title, versions };
+    const work = parseWork(entry.work);
+    if (work)
+        game.work = work;
+    else if (entry.work !== undefined)
+        warn(`${path}.work`, "dropped: not an object of short string or integer values");
+    if (entry.meta !== undefined)
+        game.meta = parseMeta(entry.meta, `${path}.meta`, baseUrl, warn);
+    return game;
+}
+function parseVersion(v, path, baseUrl, warn) {
+    if (!isObject(v))
+        return void warn(path, "skipped: not an object");
+    const label = text(v.version, LIMITS.versionLabel);
+    if (label === undefined)
+        return void warn(path, `skipped: "version" must be a non-empty string of at most ${LIMITS.versionLabel} characters`);
+    const f = v.file;
+    if (!isObject(f))
+        return void warn(path, `skipped: "file" must be an object`);
+    if (typeof f.url !== "string" || f.url.length > LIMITS.url)
+        return void warn(path, `skipped: "file.url" must be a url`);
+    const url = resolveUrl(f.url, baseUrl);
+    if (url === undefined || !isSecureUrl(url))
+        return void warn(path, `skipped: "file.url" must resolve to an https url`);
+    if (typeof f.sha256 !== "string" || !SHA256.test(f.sha256))
+        return void warn(path, `skipped: "file.sha256" must be 64 lowercase hex digits`);
+    if (!Number.isSafeInteger(f.size) || f.size < 0)
+        return void warn(path, `skipped: "file.size" must be a non-negative integer`);
+    const file = { url, sha256: f.sha256, size: f.size };
+    const version = { version: label, file };
+    if (typeof v.format === "string" && FORMATS.includes(v.format))
+        version.format = v.format;
+    else if (v.format !== undefined)
+        warn(`${path}.format`, "dropped: not zip, 7z or rar");
+    if (typeof v.build === "string" && SHA256.test(v.build))
+        version.build = v.build;
+    else if (v.build !== undefined)
+        warn(`${path}.build`, "dropped: not 64 lowercase hex digits");
+    const notes = text(v.notes, LIMITS.notes);
+    if (notes)
+        version.notes = notes;
+    else if (v.notes !== undefined)
+        warn(`${path}.notes`, "dropped");
+    if (validDate(v.released))
+        version.released = v.released;
+    else if (v.released !== undefined)
+        warn(`${path}.released`, "dropped: not an ISO-8601 date");
+    return version;
+}
+function parseWork(w) {
+    if (!isObject(w))
+        return undefined;
+    const entries = Object.entries(w);
+    if (entries.length === 0 || entries.length > LIMITS.work)
+        return undefined;
+    const out = {};
+    for (const [k, val] of entries) {
+        if (k.length > LIMITS.workKey || !WORK_KEY.test(k))
+            return undefined;
+        if (typeof val === "number" ? !Number.isSafeInteger(val) : text(val, LIMITS.workText) === undefined)
+            return undefined;
+        out[k] = typeof val === "string" ? val.trim() : val;
+    }
+    return out;
+}
+function parseMeta(m, path, baseUrl, warn) {
+    if (!isObject(m))
+        return void warn(path, "dropped: not an object");
+    const meta = {};
+    const url = (v) => {
+        const resolved = typeof v === "string" ? resolveUrl(v, baseUrl) : undefined;
+        return resolved !== undefined && isSecureUrl(resolved) ? resolved : undefined;
+    };
+    const author = text(m.author, LIMITS.author);
+    if (author)
+        meta.author = author;
+    const description = text(m.description, LIMITS.metaText);
+    if (description)
+        meta.description = description;
+    if (Array.isArray(m.tags)) {
+        const tags = m.tags.map((t) => text(t, LIMITS.tag)).filter((t) => t !== undefined).slice(0, LIMITS.tags);
+        if (tags.length)
+            meta.tags = tags;
+    }
+    const cover = url(m.cover);
+    if (cover)
+        meta.cover = cover;
+    if (Array.isArray(m.screenshots)) {
+        const shots = m.screenshots.map(url).filter((u) => u !== undefined).slice(0, LIMITS.screenshots);
+        if (shots.length)
+            meta.screenshots = shots;
+    }
+    if (Array.isArray(m.links)) {
+        const links = m.links.flatMap((l) => {
+            const name = isObject(l) ? text(l.name, LIMITS.linkName) : undefined;
+            const href = isObject(l) ? url(l.url) : undefined;
+            return name && href ? [{ name, url: href }] : [];
+        }).slice(0, LIMITS.links);
+        if (links.length)
+            meta.links = links;
+    }
+    return Object.keys(meta).length ? meta : undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export type Format = "zip" | "7z" | "rar";
+export interface ArchiveFile {
+    url: string;
+    /** Lowercase hex SHA-256 of the archive, exactly as stored. */
+    sha256: string;
+    /** Bytes. */
+    size: number;
+}
+export interface Version {
+    version: string;
+    file: ArchiveFile;
+    format?: Format;
+    /** Claimed hash of the normalised game payload; a hint, consumers recompute. */
+    build?: string;
+    notes?: string;
+    /** YYYY-MM-DD, or a full ISO-8601 timestamp. */
+    released?: string;
+}
+export interface Meta {
+    author?: string;
+    description?: string;
+    tags?: string[];
+    cover?: string;
+    screenshots?: string[];
+    links?: {
+        name: string;
+        url: string;
+    }[];
+}
+export interface Game {
+    id: string;
+    title: string;
+    work?: Record<string, string | number>;
+    meta?: Meta;
+    /** Non-empty, newest first. */
+    versions: Version[];
+}
+/** A file of games listed by repo.json. Content-addressed: its bytes must hash to `sha256`. */
+export interface Shard {
+    url: string;
+    /** Lowercase hex SHA-256 of the shard file, exactly as stored. */
+    sha256: string;
+    /** Bytes. */
+    size: number;
+    /** Number of games in it; advisory. */
+    count?: number;
+}
+export interface Repo {
+    schema: 1;
+    name: string;
+    description?: string;
+    homepage?: string;
+    updated: string;
+    /** Inline games; with `shards`, these come first. */
+    games: Game[];
+    shards?: Shard[];
+}
+/** Something skipped or dropped while parsing; `path` is a JSON path such as `games[3].versions[0]`. */
+export interface Warning {
+    path: string;
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// The types of SPEC.md §3. A parsed Repo has every url resolved to an absolute one.
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,14 @@
+import type { ArchiveFile } from "./types.ts";
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "size" | "sha256";
+    expected: string | number;
+    actual: string | number;
+};
+/**
+ * Checks bytes against a `file` entry: size first, then sha256. A consumer discards the archive on `ok: false`.
+ * shortcut: a stream is buffered whole (Web Crypto has no incremental digest), upgrade when archives outgrow memory.
+ */
+export declare function verifyArchive(data: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>, file: Pick<ArchiveFile, "sha256" | "size">): Promise<VerifyResult>;

package/dist/verify.js

@@ -0,0 +1,15 @@
+// SPEC.md §6: the sha256 check on a downloaded archive. Web Crypto only, so it runs in a browser.
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+/**
+ * Checks bytes against a `file` entry: size first, then sha256. A consumer discards the archive on `ok: false`.
+ * shortcut: a stream is buffered whole (Web Crypto has no incremental digest), upgrade when archives outgrow memory.
+ */
+export async function verifyArchive(data, file) {
+    const bytes = data instanceof ReadableStream
+        ? new Uint8Array(await new Response(data).arrayBuffer())
+        : new Uint8Array(data);
+    if (bytes.byteLength !== file.size)
+        return { ok: false, reason: "size", expected: file.size, actual: bytes.byteLength };
+    const actual = hex(await crypto.subtle.digest("SHA-256", bytes));
+    return actual === file.sha256 ? { ok: true } : { ok: false, reason: "sha256", expected: file.sha256, actual };
+}

package/package.json

@@ -1 +1,50 @@
-{ "name": "gm-pantry", "version": "0.0.0", "description": "Placeholder; the real package is published from GitHub Actions.", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/QuentinJanuel/GM-Pantry.git" } }
+{
+  "name": "gm-pantry",
+  "version": "0.2.0",
+  "description": "Game repositories: static directories of game archives with a repo.json, plus a parser, validator and CLI.",
+  "keywords": [
+    "gamemaker",
+    "repository",
+    "archive",
+    "static"
+  ],
+  "homepage": "https://github.com/QuentinJanuel/GM-Pantry#readme",
+  "bugs": "https://github.com/QuentinJanuel/GM-Pantry/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuentinJanuel/GM-Pantry.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gm-pantry": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "test": "node --test test/*.test.ts scripts/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}