@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 +14 -0
- package/LICENSE +21 -0
- package/README.md +118 -43
- package/dist/addon.d.ts +66 -0
- package/dist/addon.d.ts.map +1 -0
- package/dist/addon.js +191 -0
- package/dist/addon.js.map +1 -0
- package/dist/addonIndex.d.ts +106 -0
- package/dist/addonIndex.d.ts.map +1 -0
- package/dist/addonIndex.js +180 -0
- package/dist/addonIndex.js.map +1 -0
- package/dist/build.d.ts +58 -0
- package/dist/build.d.ts.map +1 -0
- package/dist/build.js +91 -0
- package/dist/build.js.map +1 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +11 -0
- package/dist/cli.js.map +1 -0
- package/dist/command.d.ts +14 -0
- package/dist/command.d.ts.map +1 -0
- package/dist/command.js +97 -0
- package/dist/command.js.map +1 -0
- package/dist/isRecord.d.ts +3 -0
- package/dist/isRecord.d.ts.map +1 -0
- package/dist/isRecord.js +6 -0
- package/dist/isRecord.js.map +1 -0
- package/dist/url.d.ts +10 -0
- package/dist/url.d.ts.map +1 -0
- package/dist/url.js +22 -0
- package/dist/url.js.map +1 -0
- package/package.json +69 -6
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
##
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
3
|
+
[](https://discord.gg/kZZCDyCBbW)
|
|
4
|
+
[](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.
|
package/dist/addon.d.ts
ADDED
|
@@ -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":"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"}
|
|
@@ -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"}
|