@jsprismarine/addon-tools 0.0.0 → 0.23.0-unstable-20261120220435

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,14 @@
1
+ # @jsprismarine/addon-tools
2
+
3
+ ## 0.23.0-unstable-20261120220435
4
+
5
+ ### Patch Changes
6
+
7
+ - [#3336](https://github.com/JSPrismarine/JSPrismarine/pull/3336) [`a22d9dc`](https://github.com/JSPrismarine/JSPrismarine/commit/a22d9dc5080ea9b11b5d55da130a60a47b69120e) Thanks [@filiphsps](https://github.com/filiphsps)! - `@jsprismarine/addon-tools/addonIndex` gains `satisfiesAddonRange`, `isAddonRange` and `addonVersionsInRange`, which read the `^1.2.3`, `~1.2.3`, `1.2.3` and `*` ranges the way npm does. `fetchPublishedIndex` takes the `fetch` to download through, and `@jsprismarine/addon-tools/addon` exports `parseAddonMetadata`, the `addon.json` check the build runs.
8
+
9
+ - [#3336](https://github.com/JSPrismarine/JSPrismarine/pull/3336) [`f7d0f10`](https://github.com/JSPrismarine/JSPrismarine/commit/f7d0f10ca3e2596cdb720f7e1c17b7e212b193a8) Thanks [@filiphsps](https://github.com/filiphsps)! - `@jsprismarine/addon-tools/build` exports `readAddons`, which reads and checks every addon in a folder the way `buildAddons` does, in name order, without packing them.
10
+
11
+ - [#3336](https://github.com/JSPrismarine/JSPrismarine/pull/3336) [`bf419b8`](https://github.com/JSPrismarine/JSPrismarine/commit/bf419b82bfea52c095ca09b02c1c4ac955ac1d0a) Thanks [@filiphsps](https://github.com/filiphsps)! - Add `@jsprismarine/addon-tools`, which builds JSPrismarine addons. Its `jsp-addon build` command checks each addon's behavior pack and `addon.json`, packs it into `<name>-<version>.mcpack` and writes the `index.json` a server installs from, keeping every published version. `@jsprismarine/addon-tools/addonIndex` parses and validates that index. `@jsprismarine/packs/zip` gains `writeZip`, which writes the same bytes for the same files, and `@jsprismarine/packs/manifest` exports the manifest parser. `@jsprismarine/errors/addon-tools` holds the new errors.
12
+ - Updated dependencies [[`60edd7a`](https://github.com/JSPrismarine/JSPrismarine/commit/60edd7a1234650367fe5c2406ee402641be33ed9), [`bf419b8`](https://github.com/JSPrismarine/JSPrismarine/commit/bf419b82bfea52c095ca09b02c1c4ac955ac1d0a), [`af89e9c`](https://github.com/JSPrismarine/JSPrismarine/commit/af89e9cadd3cfd2f6652e79ada341e12ac5f66c8), [`b41035b`](https://github.com/JSPrismarine/JSPrismarine/commit/b41035be9b61570008b3405aa169418b19081915), [`7e2e6f3`](https://github.com/JSPrismarine/JSPrismarine/commit/7e2e6f3cff1f20a11a3f59aac94c68a33fa71a35), [`3e71a8d`](https://github.com/JSPrismarine/JSPrismarine/commit/3e71a8dd75bd0a97e0f8587666f60f160844ff0b), [`5d2fb0e`](https://github.com/JSPrismarine/JSPrismarine/commit/5d2fb0eb3730e59260a09e60c130e57e5fdb099c), [`56200a6`](https://github.com/JSPrismarine/JSPrismarine/commit/56200a61535d916f0c41a11d077752b194e4c08b), [`c500335`](https://github.com/JSPrismarine/JSPrismarine/commit/c5003358e3a7199593c6ddcdbe4bdf63f8c29fac), [`c500335`](https://github.com/JSPrismarine/JSPrismarine/commit/c5003358e3a7199593c6ddcdbe4bdf63f8c29fac), [`c500335`](https://github.com/JSPrismarine/JSPrismarine/commit/c5003358e3a7199593c6ddcdbe4bdf63f8c29fac), [`104bb4d`](https://github.com/JSPrismarine/JSPrismarine/commit/104bb4d4a3dbf7654c19294b4a1d66724d591ad3), [`6787fdd`](https://github.com/JSPrismarine/JSPrismarine/commit/6787fdd6ff50c80110f4951a0cea51214611eea0), [`6e758f9`](https://github.com/JSPrismarine/JSPrismarine/commit/6e758f9de80c357c12d992bf473f1bdac86fb274), [`93a1b61`](https://github.com/JSPrismarine/JSPrismarine/commit/93a1b610493f401c4ac62881f70b3dee8c882f33), [`e1c982e`](https://github.com/JSPrismarine/JSPrismarine/commit/e1c982eeed0dfd682b5680c45c69159e21fd9ec0), [`9579362`](https://github.com/JSPrismarine/JSPrismarine/commit/9579362b4070e246d6300d2f4e2dca2ab4715124), [`f18ef7c`](https://github.com/JSPrismarine/JSPrismarine/commit/f18ef7c595f58a267b5371baab96390d0282616d), [`cf88d2f`](https://github.com/JSPrismarine/JSPrismarine/commit/cf88d2f8c2184bd4e116db888d4528fa27f5338d), [`d6c69e4`](https://github.com/JSPrismarine/JSPrismarine/commit/d6c69e43051eb091f0b4a17c0f33799f5944caf3), [`0792e2a`](https://github.com/JSPrismarine/JSPrismarine/commit/0792e2a7e6e5e98729b80df412262fd549ea3cb9), [`1c3be54`](https://github.com/JSPrismarine/JSPrismarine/commit/1c3be5465a2865072ac0f16b4848ee0cd9b6b13a), [`db04d85`](https://github.com/JSPrismarine/JSPrismarine/commit/db04d8520c1d43b88196c14229f36f5c8e71f3c1)]:
13
+ - @jsprismarine/errors@0.23.0-unstable-20261120220435
14
+ - @jsprismarine/packs@0.23.0-unstable-20261120220435
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 JSPrismarine Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,45 +1,120 @@
1
1
  # @jsprismarine/addon-tools
2
2
 
3
- ## ⚠️ IMPORTANT NOTICE ⚠️
4
-
5
- **This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
6
-
7
- This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
8
-
9
- ## Purpose
10
-
11
- This package exists to:
12
- 1. Configure OIDC trusted publishing for the package name `@jsprismarine/addon-tools`
13
- 2. Enable secure, token-less publishing from CI/CD workflows
14
- 3. Establish provenance for packages published under this name
15
-
16
- ## What is OIDC Trusted Publishing?
17
-
18
- OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
19
-
20
- ## Setup Instructions
21
-
22
- To properly configure OIDC trusted publishing for this package:
23
-
24
- 1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
25
- 2. Configure the trusted publisher (e.g., GitHub Actions)
26
- 3. Specify the repository and workflow that should be allowed to publish
27
- 4. Use the configured workflow to publish your actual package
28
-
29
- ## DO NOT USE THIS PACKAGE
30
-
31
- This package is a placeholder for OIDC configuration only. It:
32
- - Contains no executable code
33
- - Provides no functionality
34
- - Should not be installed as a dependency
35
- - Exists only for administrative purposes
36
-
37
- ## More Information
38
-
39
- For more details about npm's trusted publishing feature, see:
40
- - [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
41
- - [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
42
-
43
- ---
44
-
45
- **Maintained for OIDC setup purposes only**
3
+ [![Join the Discord Server](https://img.shields.io/discord/704967868885762108?color=%237289DA&label=Discord)](https://discord.gg/kZZCDyCBbW)
4
+ [![npm](https://img.shields.io/npm/dt/@jsprismarine/addon-tools)](https://www.npmjs.com/package/@jsprismarine/addon-tools)
5
+
6
+ Builds JSPrismarine addons. `jsp-addon build` checks every addon in a folder, packs each one into
7
+ `<name>-<version>.mcpack`, and writes the index a JSPrismarine server installs addons from.
8
+ JSPrismarine builds [its own addons](https://github.com/JSPrismarine/JSPrismarine/tree/master/addons)
9
+ with it, and any GitHub repository can publish addons the same way.
10
+
11
+ ## An addon
12
+
13
+ An addon is a behavior pack in a folder named for the addon, such as `addons/tps-bar/`. The name
14
+ is lowercase letters and digits with single hyphens between them, and it is the name owners
15
+ install the addon by. The folder holds <!-- fact:addons.files -->`manifest.json`, `addon.json` and `README.md`<!-- /fact -->,
16
+ plus the pack's `scripts/` and any other pack files.
17
+
18
+ - `manifest.json` is the pack's manifest. Its header's `version` is the addon's version, and every
19
+ module carries the same version. The modules are <!-- fact:addons.moduleTypes -->`data` and `script`<!-- /fact --> only, and each script
20
+ module's `entry` exists.
21
+ - `addon.json` holds what the index needs beside the manifest:
22
+
23
+ ```json
24
+ {
25
+ "description": "Shows TPS, MSPT and ping on a boss bar.",
26
+ "minServer": "0.23.0",
27
+ "license": "MIT"
28
+ }
29
+ ```
30
+
31
+ `minServer` is the oldest JSPrismarine version the addon runs on. The file takes no other keys,
32
+ so a version written here by mistake fails the build instead of disagreeing with the manifest.
33
+
34
+ The pack holds every file in the folder except those whose names start with a dot. A symbolic link
35
+ fails the build.
36
+
37
+ ## Building
38
+
39
+ ```sh
40
+ npx @jsprismarine/addon-tools build --addons addons --out dist/addons --repository owner/repo
41
+ ```
42
+
43
+ The build downloads the index the repository has already published and merges the new packs into
44
+ it. Every published version stays in the index, since an installed addon is locked to its version's
45
+ URL and hash. A pack whose version is published with other contents fails the build: raise the
46
+ version in the manifest header instead. `--offline` skips the download.
47
+
48
+ The index's URLs point at the repository's <!-- fact:addons.releaseTag -->`addons`<!-- /fact --> release. `--base-url` points them
49
+ somewhere else. In GitHub Actions, `--repository` defaults to the repository the workflow runs in,
50
+ and `--github-output "$GITHUB_OUTPUT"` gives the release's tag and the new packs to later steps.
51
+ `jsp-addon --help` lists every option.
52
+
53
+ ## Publishing from GitHub Actions
54
+
55
+ `.github/workflows/addons-release.yml` in the JSPrismarine repository is a reusable workflow that
56
+ builds the addons and attaches the new packs and the index to the release. A repository of addons
57
+ calls it:
58
+
59
+ ```yaml
60
+ on:
61
+ pull_request:
62
+ push:
63
+ branches: [main]
64
+
65
+ # One publish at a time, so two runs cannot each upload an index that lacks the other's packs.
66
+ concurrency:
67
+ group: ${{ github.workflow }}-${{ github.ref }}
68
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
69
+
70
+ jobs:
71
+ addons:
72
+ uses: JSPrismarine/JSPrismarine/.github/workflows/addons-release.yml@<commit sha>
73
+ permissions:
74
+ contents: write
75
+ with:
76
+ tools: latest
77
+ publish: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
78
+ ```
79
+
80
+ A pull request only builds, which catches an invalid addon or a changed pack without a new version.
81
+ A push to `main` also publishes. `addons` sets the folder when it is not `addons`, and `tools` takes
82
+ an exact version of this package to pin the build.
83
+
84
+ ## The index
85
+
86
+ The release carries <!-- fact:addons.indexFile -->`index.json`<!-- /fact --> beside the packs. Schema version <!-- fact:addons.indexSchemaVersion -->`1`<!-- /fact --> lists every
87
+ published version of every addon, sorted by name and then version:
88
+
89
+ ```json
90
+ {
91
+ "schemaVersion": 1,
92
+ "addons": [
93
+ {
94
+ "name": "tps-bar",
95
+ "version": "1.0.0",
96
+ "description": "Shows TPS, MSPT and ping on a boss bar.",
97
+ "minServer": "0.23.0",
98
+ "url": "https://github.com/JSPrismarine/JSPrismarine/releases/download/addons/tps-bar-1.0.0.mcpack",
99
+ "sha256": "<the pack's SHA-256>"
100
+ }
101
+ ]
102
+ }
103
+ ```
104
+
105
+ `@jsprismarine/addon-tools/addonIndex` reads and writes it:
106
+
107
+ ```ts
108
+ import { parseAddonIndex } from '@jsprismarine/addon-tools/addonIndex';
109
+
110
+ const index = parseAddonIndex(await (await fetch(url)).json());
111
+ ```
112
+
113
+ `parseAddonIndex` throws an `InvalidAddonIndexError` from `@jsprismarine/errors/addon-tools` for
114
+ an index that breaks the schema, and drops keys an entry has beyond it. `addonVersionsInRange`
115
+ lists one addon's versions that match a range such as `^1.0.0`, `~1.2.0`, `1.2.3` or `*`, newest
116
+ first, the way npm reads those ranges, and `satisfiesAddonRange` tests one version. `mergeAddonIndex`,
117
+ `createAddonIndex` and `serializeAddonIndex` build one. `@jsprismarine/addon-tools/addon` reads
118
+ and packs one addon, and `@jsprismarine/addon-tools/build` builds a folder of them.
119
+ `fetchPublishedIndex` from `@jsprismarine/addon-tools/build` downloads a release's index, through
120
+ the `fetch` you pass it or the global one.
@@ -0,0 +1,66 @@
1
+ import type { AddonIndexEntry } from './addonIndex.js';
2
+ /**
3
+ * An addon is a behavior pack in a folder named for the addon: `manifest.json`, `scripts/` and a
4
+ * `README.md`, plus an `addon.json` with what the index and the server's installer need beside the
5
+ * manifest. The manifest header's version is the addon's version.
6
+ */
7
+ /** The files every addon folder has. */
8
+ export declare const ADDON_FILES: readonly ['manifest.json', 'addon.json', 'README.md'];
9
+ /** The manifest module types an addon may declare: a behavior pack's. */
10
+ export declare const ADDON_MODULE_TYPES: readonly string[];
11
+ /** What `addon.json` holds. */
12
+ export interface AddonMetadata {
13
+ /** A one-line description of what the addon does. */
14
+ readonly description: string;
15
+ /** The oldest JSPrismarine version the addon runs on, `major.minor.patch`. */
16
+ readonly minServer: string;
17
+ /** The addon's license, as an SPDX expression such as `MIT`. */
18
+ readonly license: string;
19
+ }
20
+ /** An addon read from its folder and checked. */
21
+ export interface Addon extends AddonMetadata {
22
+ /** The folder's name. */
23
+ readonly name: string;
24
+ /** The manifest header's version, `major.minor.patch`. */
25
+ readonly version: string;
26
+ /** Every file the pack holds, by its path in the folder with `/` separators, in path order. */
27
+ readonly files: ReadonlyMap<string, Uint8Array>;
28
+ }
29
+ /** An addon's `.mcpack`. */
30
+ export interface AddonPack {
31
+ /** `<name>-<version>.mcpack`. */
32
+ readonly fileName: string;
33
+ readonly bytes: Uint8Array;
34
+ /** The pack's SHA-256, in lowercase hexadecimal. */
35
+ readonly sha256: string;
36
+ }
37
+ /**
38
+ * Reads and checks an addon's `addon.json`: a `description` on one line, a `minServer` version
39
+ * and a `license`, each a non-empty string, and no other keys.
40
+ *
41
+ * @param addon - The addon's name, for the error message.
42
+ * @param bytes - The file's contents.
43
+ * @throws {InvalidAddonError} `InvalidAddonJson` when the file breaks any of those rules.
44
+ */
45
+ export declare const parseAddonMetadata: (addon: string, bytes: Uint8Array) => AddonMetadata;
46
+ /**
47
+ * Reads an addon from its folder and checks it: the folder's name is an addon name, the three
48
+ * {@link ADDON_FILES} are there, `manifest.json` is a behavior pack manifest whose modules carry
49
+ * the header's version, each script module's entry exists, and `addon.json` follows
50
+ * {@link AddonMetadata} with no other keys.
51
+ *
52
+ * @param directory - The addon's folder.
53
+ * @throws {InvalidAddonError} When any check fails.
54
+ */
55
+ export declare const readAddon: (directory: string) => Promise<Addon>;
56
+ /**
57
+ * Zips an addon into its `.mcpack`. Entries are stored in path order and dated 1980-01-01, so
58
+ * the same files always give the same bytes and the same hash, on any machine.
59
+ */
60
+ export declare const packAddon: (addon: Addon) => AddonPack;
61
+ /**
62
+ * The index entry for an addon's pack.
63
+ * @param baseUrl - Where the release's files download from; the pack's file name is added to it.
64
+ */
65
+ export declare const addonIndexEntry: (addon: Addon, pack: AddonPack, baseUrl: string) => AddonIndexEntry;
66
+ //# sourceMappingURL=addon.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"addon.d.ts","sources":["../src/addon.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKpD;;;;GAIG;AAEH,wCAAwC;AACxC,eAAO,MAAM,WAAW,YAAI,eAAe,EAAE,YAAY,EAAE,WAAW,CAAU,CAAC;AAEjF,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAuB,CAAC;AAExE,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,KAAM,SAAQ,aAAa;IACxC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACnD;AAED,4BAA4B;AAC5B,MAAM,WAAW,SAAS;IACtB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AA2BD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,UAAW,MAAM,SAAS,UAAU,KAAG,aAuBrE,CAAC;AAiDF;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,cAAqB,MAAM,KAAG,OAAO,CAAC,KAAK,CAUhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,UAAW,KAAK,KAAG,SAOxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,KAAK,QAAQ,SAAS,WAAW,MAAM,KAAG,eAO/E,CAAC"}
package/dist/addon.js ADDED
@@ -0,0 +1,191 @@
1
+ import { isAddonName, isAddonVersion, packFileName } from "./addonIndex.js";
2
+ import { isRecord } from "./isRecord.js";
3
+ import { fileUrl } from "./url.js";
4
+ import { AddonToolsErrors } from "@jsprismarine/errors/addon-tools";
5
+ import { readFile, readdir } from "node:fs/promises";
6
+ import { JSPrismarineError } from "@jsprismarine/errors/JSPrismarineError";
7
+ import path from "node:path";
8
+ import { createHash } from "node:crypto";
9
+ import { parseLenientJson } from "@jsprismarine/packs/lenientJson";
10
+ import { parseManifest } from "@jsprismarine/packs/manifest";
11
+ import { writeZip } from "@jsprismarine/packs/zip";
12
+ // src/addon.ts
13
+ /**
14
+ * An addon is a behavior pack in a folder named for the addon: `manifest.json`, `scripts/` and a
15
+ * `README.md`, plus an `addon.json` with what the index and the server's installer need beside the
16
+ * manifest. The manifest header's version is the addon's version.
17
+ */
18
+ /** The files every addon folder has. */
19
+ var ADDON_FILES = [
20
+ "manifest.json",
21
+ "addon.json",
22
+ "README.md"
23
+ ];
24
+ /** The manifest module types an addon may declare: a behavior pack's. */
25
+ var ADDON_MODULE_TYPES = ["data", "script"];
26
+ var METADATA_KEYS = [
27
+ "description",
28
+ "minServer",
29
+ "license"
30
+ ];
31
+ /**
32
+ * Reads every file under a folder, skipping names that start with a dot.
33
+ * @throws {InvalidAddonError} `UnsupportedAddonEntry` for a link or another special entry.
34
+ */
35
+ var readFiles = async (addon, root) => {
36
+ const paths = [];
37
+ const walk = async (relative) => {
38
+ for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
39
+ if (entry.name.startsWith(".")) continue;
40
+ const child = relative === "" ? entry.name : `${relative}/${entry.name}`;
41
+ if (entry.isDirectory()) await walk(child);
42
+ else if (entry.isFile()) paths.push(child);
43
+ else throw new AddonToolsErrors.UnsupportedAddonEntry({
44
+ addon,
45
+ path: child
46
+ });
47
+ }
48
+ };
49
+ await walk("");
50
+ paths.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
51
+ const files = /* @__PURE__ */ new Map();
52
+ for (const file of paths) files.set(file, new Uint8Array(await readFile(path.join(root, file))));
53
+ return files;
54
+ };
55
+ /**
56
+ * Reads and checks an addon's `addon.json`: a `description` on one line, a `minServer` version
57
+ * and a `license`, each a non-empty string, and no other keys.
58
+ *
59
+ * @param addon - The addon's name, for the error message.
60
+ * @param bytes - The file's contents.
61
+ * @throws {InvalidAddonError} `InvalidAddonJson` when the file breaks any of those rules.
62
+ */
63
+ var parseAddonMetadata = (addon, bytes) => {
64
+ const fail = (problem) => new AddonToolsErrors.InvalidAddonJson({
65
+ addon,
66
+ problem
67
+ });
68
+ let value;
69
+ try {
70
+ value = JSON.parse(new TextDecoder().decode(bytes));
71
+ } catch (cause) {
72
+ throw new AddonToolsErrors.InvalidAddonJson({
73
+ addon,
74
+ problem: "it is not JSON"
75
+ }, { cause });
76
+ }
77
+ if (!isRecord(value)) throw fail("it is not a JSON object");
78
+ const unknown = Object.keys(value).filter((key) => !METADATA_KEYS.includes(key));
79
+ if (unknown.length > 0) throw fail(`it has keys the schema does not, ${unknown.join(", ")}`);
80
+ const text = (key) => {
81
+ const field = value[key];
82
+ if (typeof field !== "string" || field.trim().length === 0) throw fail(`${key} must be a non-empty string`);
83
+ return field;
84
+ };
85
+ const description = text("description");
86
+ if (/[\r\n]/.test(description)) throw fail("description must be one line");
87
+ const minServer = text("minServer");
88
+ if (!isAddonVersion(minServer)) throw fail(`minServer must be a major.minor.patch version, got ${minServer}`);
89
+ return {
90
+ description,
91
+ minServer,
92
+ license: text("license")
93
+ };
94
+ };
95
+ /** The manifest's header version, after checking it is a behavior pack whose modules agree. */
96
+ var checkManifest = (addon, files) => {
97
+ const fail = (problem) => new AddonToolsErrors.InvalidAddonManifest({
98
+ addon,
99
+ problem
100
+ });
101
+ let value;
102
+ try {
103
+ value = parseLenientJson(new TextDecoder().decode(files.get("manifest.json")));
104
+ } catch (cause) {
105
+ if (cause instanceof JSPrismarineError) throw fail(cause.message);
106
+ throw cause;
107
+ }
108
+ const { manifest, diagnostics } = parseManifest(value, addon);
109
+ if (!manifest) throw fail(diagnostics.map((diagnostic) => diagnostic.message).join("; "));
110
+ const version = manifest.header.version.join(".");
111
+ if (!isAddonVersion(version)) throw fail(`the header's version must be three whole numbers, such as [1, 2, 3], got ${version}`);
112
+ for (const module of manifest.modules) {
113
+ if (!ADDON_MODULE_TYPES.includes(module.type)) throw new AddonToolsErrors.NotABehaviorPack({
114
+ addon,
115
+ type: module.type
116
+ });
117
+ const moduleVersion = module.version.join(".");
118
+ if (moduleVersion !== version) throw new AddonToolsErrors.ModuleVersionDiffers({
119
+ addon,
120
+ type: module.type,
121
+ moduleVersion,
122
+ version
123
+ });
124
+ }
125
+ const modules = isRecord(value) && Array.isArray(value.modules) ? value.modules : [];
126
+ if (modules.some((module) => isRecord(module) && module.type === "script")) try {
127
+ JSON.parse(new TextDecoder().decode(files.get("manifest.json")));
128
+ } catch (cause) {
129
+ throw fail(`a script pack's manifest must be plain JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
130
+ }
131
+ for (const module of modules) {
132
+ if (!isRecord(module) || module.type !== "script") continue;
133
+ if (typeof module.entry !== "string") throw fail("a script module needs an entry");
134
+ if (!files.has(module.entry)) throw new AddonToolsErrors.MissingScriptEntry({
135
+ addon,
136
+ entry: module.entry
137
+ });
138
+ }
139
+ return version;
140
+ };
141
+ /**
142
+ * Reads an addon from its folder and checks it: the folder's name is an addon name, the three
143
+ * {@link ADDON_FILES} are there, `manifest.json` is a behavior pack manifest whose modules carry
144
+ * the header's version, each script module's entry exists, and `addon.json` follows
145
+ * {@link AddonMetadata} with no other keys.
146
+ *
147
+ * @param directory - The addon's folder.
148
+ * @throws {InvalidAddonError} When any check fails.
149
+ */
150
+ var readAddon = async (directory) => {
151
+ const name = path.basename(path.resolve(directory));
152
+ if (!isAddonName(name)) throw new AddonToolsErrors.InvalidAddonName({ name });
153
+ const files = await readFiles(name, directory);
154
+ for (const file of ADDON_FILES) if (!files.has(file)) throw new AddonToolsErrors.MissingAddonFile({
155
+ addon: name,
156
+ file
157
+ });
158
+ return {
159
+ name,
160
+ version: checkManifest(name, files),
161
+ ...parseAddonMetadata(name, files.get("addon.json")),
162
+ files
163
+ };
164
+ };
165
+ /**
166
+ * Zips an addon into its `.mcpack`. Entries are stored in path order and dated 1980-01-01, so
167
+ * the same files always give the same bytes and the same hash, on any machine.
168
+ */
169
+ var packAddon = (addon) => {
170
+ const bytes = writeZip(addon.files);
171
+ return {
172
+ fileName: packFileName(addon.name, addon.version),
173
+ bytes,
174
+ sha256: createHash("sha256").update(bytes).digest("hex")
175
+ };
176
+ };
177
+ /**
178
+ * The index entry for an addon's pack.
179
+ * @param baseUrl - Where the release's files download from; the pack's file name is added to it.
180
+ */
181
+ var addonIndexEntry = (addon, pack, baseUrl) => ({
182
+ name: addon.name,
183
+ version: addon.version,
184
+ description: addon.description,
185
+ minServer: addon.minServer,
186
+ url: fileUrl(baseUrl, pack.fileName),
187
+ sha256: pack.sha256
188
+ });
189
+ export { ADDON_FILES, ADDON_MODULE_TYPES, addonIndexEntry, packAddon, parseAddonMetadata, readAddon };
190
+
191
+ //# sourceMappingURL=addon.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"addon.js","names":[],"sources":["../src/addon.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport { readdir, readFile } from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { AddonToolsErrors } from '@jsprismarine/errors/addon-tools';\nimport { JSPrismarineError } from '@jsprismarine/errors/JSPrismarineError';\nimport { parseLenientJson } from '@jsprismarine/packs/lenientJson';\nimport { parseManifest } from '@jsprismarine/packs/manifest';\nimport { writeZip } from '@jsprismarine/packs/zip';\n\nimport type { AddonIndexEntry } from './addonIndex';\nimport { isAddonName, isAddonVersion, packFileName } from './addonIndex';\nimport { isRecord } from './isRecord';\nimport { fileUrl } from './url';\n\n/**\n * An addon is a behavior pack in a folder named for the addon: `manifest.json`, `scripts/` and a\n * `README.md`, plus an `addon.json` with what the index and the server's installer need beside the\n * manifest. The manifest header's version is the addon's version.\n */\n\n/** The files every addon folder has. */\nexport const ADDON_FILES = ['manifest.json', 'addon.json', 'README.md'] as const;\n\n/** The manifest module types an addon may declare: a behavior pack's. */\nexport const ADDON_MODULE_TYPES: readonly string[] = ['data', 'script'];\n\n/** What `addon.json` holds. */\nexport interface AddonMetadata {\n /** A one-line description of what the addon does. */\n readonly description: string;\n /** The oldest JSPrismarine version the addon runs on, `major.minor.patch`. */\n readonly minServer: string;\n /** The addon's license, as an SPDX expression such as `MIT`. */\n readonly license: string;\n}\n\n/** An addon read from its folder and checked. */\nexport interface Addon extends AddonMetadata {\n /** The folder's name. */\n readonly name: string;\n /** The manifest header's version, `major.minor.patch`. */\n readonly version: string;\n /** Every file the pack holds, by its path in the folder with `/` separators, in path order. */\n readonly files: ReadonlyMap<string, Uint8Array>;\n}\n\n/** An addon's `.mcpack`. */\nexport interface AddonPack {\n /** `<name>-<version>.mcpack`. */\n readonly fileName: string;\n readonly bytes: Uint8Array;\n /** The pack's SHA-256, in lowercase hexadecimal. */\n readonly sha256: string;\n}\n\nconst METADATA_KEYS: readonly string[] = ['description', 'minServer', 'license'] satisfies (keyof AddonMetadata)[];\n\n/**\n * Reads every file under a folder, skipping names that start with a dot.\n * @throws {InvalidAddonError} `UnsupportedAddonEntry` for a link or another special entry.\n */\nconst readFiles = async (addon: string, root: string): Promise<Map<string, Uint8Array>> => {\n const paths: string[] = [];\n const walk = async (relative: string): Promise<void> => {\n for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {\n if (entry.name.startsWith('.')) continue;\n const child = relative === '' ? entry.name : `${relative}/${entry.name}`;\n if (entry.isDirectory()) await walk(child);\n else if (entry.isFile()) paths.push(child);\n else throw new AddonToolsErrors.UnsupportedAddonEntry({ addon, path: child });\n }\n };\n await walk('');\n paths.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));\n\n const files = new Map<string, Uint8Array>();\n for (const file of paths) files.set(file, new Uint8Array(await readFile(path.join(root, file))));\n return files;\n};\n\n/**\n * Reads and checks an addon's `addon.json`: a `description` on one line, a `minServer` version\n * and a `license`, each a non-empty string, and no other keys.\n *\n * @param addon - The addon's name, for the error message.\n * @param bytes - The file's contents.\n * @throws {InvalidAddonError} `InvalidAddonJson` when the file breaks any of those rules.\n */\nexport const parseAddonMetadata = (addon: string, bytes: Uint8Array): AddonMetadata => {\n const fail = (problem: string) => new AddonToolsErrors.InvalidAddonJson({ addon, problem });\n let value: unknown;\n try {\n value = JSON.parse(new TextDecoder().decode(bytes));\n } catch (cause) {\n throw new AddonToolsErrors.InvalidAddonJson({ addon, problem: 'it is not JSON' }, { cause });\n }\n if (!isRecord(value)) throw fail('it is not a JSON object');\n\n const unknown = Object.keys(value).filter((key) => !METADATA_KEYS.includes(key));\n if (unknown.length > 0) throw fail(`it has keys the schema does not, ${unknown.join(', ')}`);\n const text = (key: keyof AddonMetadata): string => {\n const field = value[key];\n if (typeof field !== 'string' || field.trim().length === 0) throw fail(`${key} must be a non-empty string`);\n return field;\n };\n\n const description = text('description');\n if (/[\\r\\n]/.test(description)) throw fail('description must be one line');\n const minServer = text('minServer');\n if (!isAddonVersion(minServer)) throw fail(`minServer must be a major.minor.patch version, got ${minServer}`);\n return { description, minServer, license: text('license') };\n};\n\n/** The manifest's header version, after checking it is a behavior pack whose modules agree. */\nconst checkManifest = (addon: string, files: ReadonlyMap<string, Uint8Array>): string => {\n const fail = (problem: string) => new AddonToolsErrors.InvalidAddonManifest({ addon, problem });\n let value: unknown;\n try {\n value = parseLenientJson(new TextDecoder().decode(files.get('manifest.json')));\n } catch (cause) {\n if (cause instanceof JSPrismarineError) throw fail(cause.message);\n throw cause;\n }\n\n const { manifest, diagnostics } = parseManifest(value, addon);\n if (!manifest) throw fail(diagnostics.map((diagnostic) => diagnostic.message).join('; '));\n\n // parseManifest reads a bare number such as 1.2 as [1.2, 0, 0], which no index accepts.\n const version = manifest.header.version.join('.');\n if (!isAddonVersion(version))\n throw fail(`the header's version must be three whole numbers, such as [1, 2, 3], got ${version}`);\n for (const module of manifest.modules) {\n if (!ADDON_MODULE_TYPES.includes(module.type))\n throw new AddonToolsErrors.NotABehaviorPack({ addon, type: module.type });\n const moduleVersion = module.version.join('.');\n if (moduleVersion !== version)\n throw new AddonToolsErrors.ModuleVersionDiffers({ addon, type: module.type, moduleVersion, version });\n }\n\n // parseManifest keeps what every pack shares; a script module's entry is read here.\n const modules = isRecord(value) && Array.isArray(value.modules) ? value.modules : [];\n // The script host reads a script pack's manifest with JSON.parse, so comments and trailing\n // commas that the lenient reader takes would stop the pack from loading on a server.\n if (modules.some((module) => isRecord(module) && module.type === 'script')) {\n try {\n JSON.parse(new TextDecoder().decode(files.get('manifest.json')));\n } catch (cause) {\n throw fail(\n `a script pack's manifest must be plain JSON: ${cause instanceof Error ? cause.message : String(cause)}`\n );\n }\n }\n for (const module of modules) {\n if (!isRecord(module) || module.type !== 'script') continue;\n if (typeof module.entry !== 'string') throw fail('a script module needs an entry');\n if (!files.has(module.entry)) throw new AddonToolsErrors.MissingScriptEntry({ addon, entry: module.entry });\n }\n return version;\n};\n\n/**\n * Reads an addon from its folder and checks it: the folder's name is an addon name, the three\n * {@link ADDON_FILES} are there, `manifest.json` is a behavior pack manifest whose modules carry\n * the header's version, each script module's entry exists, and `addon.json` follows\n * {@link AddonMetadata} with no other keys.\n *\n * @param directory - The addon's folder.\n * @throws {InvalidAddonError} When any check fails.\n */\nexport const readAddon = async (directory: string): Promise<Addon> => {\n const name = path.basename(path.resolve(directory));\n if (!isAddonName(name)) throw new AddonToolsErrors.InvalidAddonName({ name });\n\n const files = await readFiles(name, directory);\n for (const file of ADDON_FILES) {\n if (!files.has(file)) throw new AddonToolsErrors.MissingAddonFile({ addon: name, file });\n }\n const version = checkManifest(name, files);\n return { name, version, ...parseAddonMetadata(name, files.get('addon.json')!), files };\n};\n\n/**\n * Zips an addon into its `.mcpack`. Entries are stored in path order and dated 1980-01-01, so\n * the same files always give the same bytes and the same hash, on any machine.\n */\nexport const packAddon = (addon: Addon): AddonPack => {\n const bytes = writeZip(addon.files);\n return {\n fileName: packFileName(addon.name, addon.version),\n bytes,\n sha256: createHash('sha256').update(bytes).digest('hex')\n };\n};\n\n/**\n * The index entry for an addon's pack.\n * @param baseUrl - Where the release's files download from; the pack's file name is added to it.\n */\nexport const addonIndexEntry = (addon: Addon, pack: AddonPack, baseUrl: string): AddonIndexEntry => ({\n name: addon.name,\n version: addon.version,\n description: addon.description,\n minServer: addon.minServer,\n url: fileUrl(baseUrl, pack.fileName),\n sha256: pack.sha256\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,IAAa,cAAc;CAAC;CAAiB;CAAc;AAAW;;AAGtE,IAAa,qBAAwC,CAAC,QAAQ,QAAQ;AA+BtE,IAAM,gBAAmC;CAAC;CAAe;CAAa;AAAS;;;;;AAM/E,IAAM,YAAY,OAAO,OAAe,SAAmD;CACvF,MAAM,QAAkB,CAAC;CACzB,MAAM,OAAO,OAAO,aAAoC;EACpD,KAAK,MAAM,SAAS,MAAM,QAAQ,KAAK,KAAK,MAAM,QAAQ,GAAG,EAAE,eAAe,KAAK,CAAC,GAAG;GACnF,IAAI,MAAM,KAAK,WAAW,GAAG,GAAG;GAChC,MAAM,QAAQ,aAAa,KAAK,MAAM,OAAO,GAAG,SAAS,GAAG,MAAM;GAClE,IAAI,MAAM,YAAY,GAAG,MAAM,KAAK,KAAK;QACpC,IAAI,MAAM,OAAO,GAAG,MAAM,KAAK,KAAK;QACpC,MAAM,IAAI,iBAAiB,sBAAsB;IAAE;IAAO,MAAM;GAAM,CAAC;EAChF;CACJ;CACA,MAAM,KAAK,EAAE;CACb,MAAM,MAAM,GAAG,MAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAE;CAEjD,MAAM,wBAAQ,IAAI,IAAwB;CAC1C,KAAK,MAAM,QAAQ,OAAO,MAAM,IAAI,MAAM,IAAI,WAAW,MAAM,SAAS,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC;CAC/F,OAAO;AACX;;;;;;;;;AAUA,IAAa,sBAAsB,OAAe,UAAqC;CACnF,MAAM,QAAQ,YAAoB,IAAI,iBAAiB,iBAAiB;EAAE;EAAO;CAAQ,CAAC;CAC1F,IAAI;CACJ,IAAI;EACA,QAAQ,KAAK,MAAM,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAAC;CACtD,SAAS,OAAO;EACZ,MAAM,IAAI,iBAAiB,iBAAiB;GAAE;GAAO,SAAS;EAAiB,GAAG,EAAE,MAAM,CAAC;CAC/F;CACA,IAAI,CAAC,SAAS,KAAK,GAAG,MAAM,KAAK,yBAAyB;CAE1D,MAAM,UAAU,OAAO,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,CAAC,cAAc,SAAS,GAAG,CAAC;CAC/E,IAAI,QAAQ,SAAS,GAAG,MAAM,KAAK,oCAAoC,QAAQ,KAAK,IAAI,GAAG;CAC3F,MAAM,QAAQ,QAAqC;EAC/C,MAAM,QAAQ,MAAM;EACpB,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,WAAW,GAAG,MAAM,KAAK,GAAG,IAAI,4BAA4B;EAC1G,OAAO;CACX;CAEA,MAAM,cAAc,KAAK,aAAa;CACtC,IAAI,SAAS,KAAK,WAAW,GAAG,MAAM,KAAK,8BAA8B;CACzE,MAAM,YAAY,KAAK,WAAW;CAClC,IAAI,CAAC,eAAe,SAAS,GAAG,MAAM,KAAK,sDAAsD,WAAW;CAC5G,OAAO;EAAE;EAAa;EAAW,SAAS,KAAK,SAAS;CAAE;AAC9D;;AAGA,IAAM,iBAAiB,OAAe,UAAmD;CACrF,MAAM,QAAQ,YAAoB,IAAI,iBAAiB,qBAAqB;EAAE;EAAO;CAAQ,CAAC;CAC9F,IAAI;CACJ,IAAI;EACA,QAAQ,iBAAiB,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,IAAI,eAAe,CAAC,CAAC;CACjF,SAAS,OAAO;EACZ,IAAI,iBAAiB,mBAAmB,MAAM,KAAK,MAAM,OAAO;EAChE,MAAM;CACV;CAEA,MAAM,EAAE,UAAU,gBAAgB,cAAc,OAAO,KAAK;CAC5D,IAAI,CAAC,UAAU,MAAM,KAAK,YAAY,KAAK,eAAe,WAAW,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC;CAGxF,MAAM,UAAU,SAAS,OAAO,QAAQ,KAAK,GAAG;CAChD,IAAI,CAAC,eAAe,OAAO,GACvB,MAAM,KAAK,4EAA4E,SAAS;CACpG,KAAK,MAAM,UAAU,SAAS,SAAS;EACnC,IAAI,CAAC,mBAAmB,SAAS,OAAO,IAAI,GACxC,MAAM,IAAI,iBAAiB,iBAAiB;GAAE;GAAO,MAAM,OAAO;EAAK,CAAC;EAC5E,MAAM,gBAAgB,OAAO,QAAQ,KAAK,GAAG;EAC7C,IAAI,kBAAkB,SAClB,MAAM,IAAI,iBAAiB,qBAAqB;GAAE;GAAO,MAAM,OAAO;GAAM;GAAe;EAAQ,CAAC;CAC5G;CAGA,MAAM,UAAU,SAAS,KAAK,KAAK,MAAM,QAAQ,MAAM,OAAO,IAAI,MAAM,UAAU,CAAC;CAGnF,IAAI,QAAQ,MAAM,WAAW,SAAS,MAAM,KAAK,OAAO,SAAS,QAAQ,GACrE,IAAI;EACA,KAAK,MAAM,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,IAAI,eAAe,CAAC,CAAC;CACnE,SAAS,OAAO;EACZ,MAAM,KACF,gDAAgD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACzG;CACJ;CAEJ,KAAK,MAAM,UAAU,SAAS;EAC1B,IAAI,CAAC,SAAS,MAAM,KAAK,OAAO,SAAS,UAAU;EACnD,IAAI,OAAO,OAAO,UAAU,UAAU,MAAM,KAAK,gCAAgC;EACjF,IAAI,CAAC,MAAM,IAAI,OAAO,KAAK,GAAG,MAAM,IAAI,iBAAiB,mBAAmB;GAAE;GAAO,OAAO,OAAO;EAAM,CAAC;CAC9G;CACA,OAAO;AACX;;;;;;;;;;AAWA,IAAa,YAAY,OAAO,cAAsC;CAClE,MAAM,OAAO,KAAK,SAAS,KAAK,QAAQ,SAAS,CAAC;CAClD,IAAI,CAAC,YAAY,IAAI,GAAG,MAAM,IAAI,iBAAiB,iBAAiB,EAAE,KAAK,CAAC;CAE5E,MAAM,QAAQ,MAAM,UAAU,MAAM,SAAS;CAC7C,KAAK,MAAM,QAAQ,aACf,IAAI,CAAC,MAAM,IAAI,IAAI,GAAG,MAAM,IAAI,iBAAiB,iBAAiB;EAAE,OAAO;EAAM;CAAK,CAAC;CAG3F,OAAO;EAAE;EAAM,SADC,cAAc,MAAM,KACrB;EAAS,GAAG,mBAAmB,MAAM,MAAM,IAAI,YAAY,CAAE;EAAG;CAAM;AACzF;;;;;AAMA,IAAa,aAAa,UAA4B;CAClD,MAAM,QAAQ,SAAS,MAAM,KAAK;CAClC,OAAO;EACH,UAAU,aAAa,MAAM,MAAM,MAAM,OAAO;EAChD;EACA,QAAQ,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;CAC3D;AACJ;;;;;AAMA,IAAa,mBAAmB,OAAc,MAAiB,aAAsC;CACjG,MAAM,MAAM;CACZ,SAAS,MAAM;CACf,aAAa,MAAM;CACnB,WAAW,MAAM;CACjB,KAAK,QAAQ,SAAS,KAAK,QAAQ;CACnC,QAAQ,KAAK;AACjB"}
@@ -0,0 +1,106 @@
1
+ /**
2
+ * The index a source publishes beside its packs, `index.json` on its `addons` release: every
3
+ * version of every addon it has published, with where to download each pack and its SHA-256.
4
+ * The build writes it and the server's installer reads it, both through this module.
5
+ */
6
+ /** The schema version this module writes and reads. */
7
+ export declare const ADDON_INDEX_SCHEMA_VERSION = 1;
8
+ /** The release tag a source publishes its packs and index on. */
9
+ export declare const ADDON_RELEASE_TAG = "addons";
10
+ /** The file name of the index on the release. */
11
+ export declare const ADDON_INDEX_FILE = "index.json";
12
+ /**
13
+ * The name the release workflow gives the old index while it uploads a new one. GitHub deletes
14
+ * an asset before replacing it, so the old index is renamed first; when the upload fails, this
15
+ * file still holds every published version, and the next build merges with it.
16
+ */
17
+ export declare const ADDON_INDEX_BACKUP_FILE = "index.previous.json";
18
+ /** One published version of one addon. */
19
+ export interface AddonIndexEntry {
20
+ /** The addon's name: its folder in the source repository and its name in `addon install`. */
21
+ readonly name: string;
22
+ /** The pack's version, `major.minor.patch`, from its manifest header. */
23
+ readonly version: string;
24
+ /** A one-line description of what the addon does. */
25
+ readonly description: string;
26
+ /** The oldest JSPrismarine version the addon runs on, `major.minor.patch`. */
27
+ readonly minServer: string;
28
+ /** Where the `.mcpack` downloads from, an `https:` URL. */
29
+ readonly url: string;
30
+ /** The pack's SHA-256, in lowercase hexadecimal. */
31
+ readonly sha256: string;
32
+ }
33
+ /** A parsed addon index. */
34
+ export interface AddonIndex {
35
+ readonly schemaVersion: typeof ADDON_INDEX_SCHEMA_VERSION;
36
+ /** Every published version, sorted by name and then by version, oldest first. */
37
+ readonly addons: readonly AddonIndexEntry[];
38
+ }
39
+ /** Whether a name is an addon name: lowercase letters and digits, with single hyphens between. */
40
+ export declare const isAddonName: (name: string) => boolean;
41
+ /**
42
+ * Whether a version is `major.minor.patch` with no leading zeros, the form an index uses. Each part
43
+ * must be a safe integer, since versions compare as numbers and two larger parts could read as one.
44
+ */
45
+ export declare const isAddonVersion: (version: string) => boolean;
46
+ /** The file name of an addon's pack on the release: `<name>-<version>.mcpack`. */
47
+ export declare const packFileName: (name: string, version: string) => string;
48
+ /**
49
+ * Compares two `major.minor.patch` versions.
50
+ * @returns Negative when `a` is older than `b`, zero when they are equal.
51
+ */
52
+ export declare const compareAddonVersions: (a: string, b: string) => number;
53
+ /** Whether a string is a version range {@link satisfiesAddonRange} reads. */
54
+ export declare const isAddonRange: (range: string) => boolean;
55
+ /**
56
+ * Whether a version falls in a range, as npm reads the same range:
57
+ *
58
+ * - `1.2.3` matches that version only.
59
+ * - `~1.2.3` matches `1.2.3` and later patches of `1.2`.
60
+ * - `^1.2.3` matches `1.2.3` and anything later with the same major version. Below `1.0.0` the
61
+ * first non-zero part is the one that stays: `^0.2.3` stops before `0.3.0`, and `^0.0.3`
62
+ * matches `0.0.3` only.
63
+ * - `*` matches every version.
64
+ *
65
+ * @returns False for a version or a range neither form takes.
66
+ */
67
+ export declare const satisfiesAddonRange: (version: string, range: string) => boolean;
68
+ /**
69
+ * The versions of one addon an index lists that fall in a range, newest first: the order an
70
+ * installer tries them in.
71
+ */
72
+ export declare const addonVersionsInRange: (index: AddonIndex, name: string, range: string) => AddonIndexEntry[];
73
+ /**
74
+ * Builds an index from entries, sorted the way an index keeps them.
75
+ * @throws {InvalidAddonIndexError} When two entries share a name and a version.
76
+ */
77
+ export declare const createAddonIndex: (entries: Iterable<AddonIndexEntry>) => AddonIndex;
78
+ /**
79
+ * Validates a decoded `index.json` against the schema. Keys an entry has beyond the schema's are
80
+ * dropped, so an index that gains fields under the same schema version still reads.
81
+ *
82
+ * @param value - The index, as `JSON.parse` returned it.
83
+ * @throws {InvalidAddonIndexError} When the index does not follow the schema, has a schema version
84
+ * other than {@link ADDON_INDEX_SCHEMA_VERSION}, or lists one version of an addon twice.
85
+ */
86
+ export declare const parseAddonIndex: (value: unknown) => AddonIndex;
87
+ /** An index as the text of `index.json`: four-space indented, ending in a newline. */
88
+ export declare const serializeAddonIndex: (index: AddonIndex) => string;
89
+ /** An index with a build's entries merged in, and which of those it did not list before. */
90
+ export interface MergedAddonIndex {
91
+ readonly index: AddonIndex;
92
+ /** The built entries the earlier index did not have, in index order. */
93
+ readonly added: readonly AddonIndexEntry[];
94
+ }
95
+ /**
96
+ * Merges a build's entries into the index already published. Every published version stays, so a
97
+ * lockfile's URL keeps downloading the pack it hashed; a built version that is already listed must
98
+ * match its hash.
99
+ *
100
+ * @param published - The index on the release, or undefined before the first release.
101
+ * @param built - One entry for each addon the build packed.
102
+ * @throws {InvalidAddonError} `PublishedVersionChanged` when a built pack's version is published
103
+ * with another hash.
104
+ */
105
+ export declare const mergeAddonIndex: (published: AddonIndex | undefined, built: readonly AddonIndexEntry[]) => MergedAddonIndex;
106
+ //# sourceMappingURL=addonIndex.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"addonIndex.d.ts","sources":["../src/addonIndex.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,uDAAuD;AACvD,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,aAAa,EAAE,OAAO,0BAA0B,CAAC;IAC1D,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAMD,kGAAkG;AAClG,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,OAAgC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,cAAc,YAAa,MAAM,KAAG,OACkD,CAAC;AAEpG,kFAAkF;AAClF,eAAO,MAAM,YAAY,SAAU,MAAM,WAAW,MAAM,KAAG,MAAqC,CAAC;AAEnG;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAO,MAAM,KAAK,MAAM,KAAG,MAI3D,CAAC;AAWF,6EAA6E;AAC7E,eAAO,MAAM,YAAY,UAAW,MAAM,KAAG,OAA0D,CAAC;AAExG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,YAAa,MAAM,SAAS,MAAM,KAAG,OAcpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAAW,UAAU,QAAQ,MAAM,SAAS,MAAM,KAAG,eAAe,EACS,CAAC;AAgC/G;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAa,QAAQ,CAAC,eAAe,CAAC,KAAG,UAQrE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,UAUhD,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,UAAW,UAAU,KAAG,MAA+C,CAAC;AAExG,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,cACb,UAAU,GAAG,SAAS,SAC1B,SAAS,eAAe,EAAE,KAClC,gBAaF,CAAC"}