gm-pantry 0.0.0-stage → 0.1.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

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# GM-Pantry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+- 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>
+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. It never deletes an entry. `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 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 { parseRepo, resolveUrl, verifyArchive, validateHosting } from "gm-pantry";
+
+const { repo, warnings } = parseRepo(await (await fetch(url)).json(), url); // throws RepoError if unusable
+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 and `ETag`/`Last-Modified` on `repo.json` 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,29 @@
+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[]>;
+export declare function buildRepo(dir: string, name?: string, now?: string): Promise<{
+    changed: boolean;
+    count: 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,93 @@
+// 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 { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, extname, join, relative, sep } from "node:path";
+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 };
+}
+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((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    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();
+}
+export async function buildRepo(dir, name, now) {
+    const repo = (await readRepoJson(dir)) ?? emptyRepo(name ?? basename(dir));
+    const files = await listArchives(dir);
+    for (const f of files)
+        upsertArchive(repo, encodeURIComponent(f), await hashFile(join(dir, f)));
+    return { changed: await writeRepoJson(dir, repo, now), count: files.length };
+}
+/** 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,97 @@
+#!/usr/bin/env node
+import { readFile, stat } from "node:fs/promises";
+import { 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 { parseRepo } from "./parse.js";
+import { verifyArchive } from "./verify.js";
+const USAGE = `gm-pantry init <dir> [--name NAME]
+gm-pantry build <dir>
+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" } },
+    });
+    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 } = await buildRepo(dir, o.name);
+            return console.log(`${count} archive(s); 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());
+            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);
+    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"));
+    }
+    const { repo, warnings } = parseRepo(json, base);
+    console.log(`${repo.name}: ${repo.games.length} game(s)`);
+    for (const w of warnings)
+        console.log(`warning ${w.path}: ${w.message}`), (failed = true);
+    if (dir) {
+        for (const g of repo.games)
+            for (const v of g.versions) {
+                if (!v.file.url.startsWith(base))
+                    continue;
+                const path = join(dir, decodeURIComponent(v.file.url.slice(base.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,55 @@
+// SPEC.md §2: does a URL actually serve a repo the way a browser consumer needs?
+import { parseRepo } 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} game(s)`);
+    }
+    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();
+}
+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,4 @@
+export type { ArchiveFile, Format, Game, Meta, Repo, Version, Warning } from "./types.ts";
+export { LIMITS, RepoError, isSecureUrl, parseRepo, resolveUrl } from "./parse.ts";
+export { verifyArchive, type VerifyResult } from "./verify.ts";
+export { validateHosting, type Check, type HostingReport } from "./hosting.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { LIMITS, RepoError, isSecureUrl, parseRepo, resolveUrl } from "./parse.js";
+export { verifyArchive } from "./verify.js";
+export { validateHosting } from "./hosting.js";

package/dist/parse.d.ts

@@ -0,0 +1,34 @@
+import type { 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 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[];
+};

package/dist/parse.js

@@ -0,0 +1,218 @@
+// 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,
+    games: 10_000,
+    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 (!Array.isArray(json.games))
+        throw new RepoError(`"games" 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");
+    const seen = new Set();
+    json.games.slice(0, LIMITS.games).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);
+        repo.games.push(game);
+    });
+    if (json.games.length > LIMITS.games)
+        warn("games", `only the first ${LIMITS.games} entries are read`);
+    return { repo, warnings };
+}
+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,50 @@
+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[];
+}
+export interface Repo {
+    schema: 1;
+    name: string;
+    description?: string;
+    homepage?: string;
+    updated: string;
+    games: Game[];
+}
+/** 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,6 +1,50 @@
 {
   "name": "gm-pantry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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"
+  }
+}