@cervio/plugin-core 1.0.0 → 1.0.1
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/README.md +62 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,20 +1,75 @@
|
|
|
1
1
|
# @cervio/plugin-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Cervio plugin contract: manifest parsing and validation, ZIP safety checks, the
|
|
4
|
+
content hash, release version helpers and packing.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
The Cervio host validates every plugin upload with this package, and `@cervio/cli` uses
|
|
7
|
+
the same code for `cervio validate` and `cervio pack`: a plugin that passes locally passes
|
|
8
|
+
on upload. You rarely need it directly: plugin code uses
|
|
9
|
+
[`@cervio/plugin-sdk`](https://www.npmjs.com/package/@cervio/plugin-sdk) and the
|
|
10
|
+
[`cervio` CLI](https://www.npmjs.com/package/@cervio/cli). Use it to build your own
|
|
11
|
+
tooling around plugin archives.
|
|
12
|
+
|
|
13
|
+
Requires Node.js 26 or later. ESM only.
|
|
6
14
|
|
|
7
15
|
```bash
|
|
8
|
-
|
|
16
|
+
npm install @cervio/plugin-core
|
|
9
17
|
```
|
|
10
18
|
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
11
21
|
```ts
|
|
12
|
-
import {
|
|
22
|
+
import { packPlugin, parseZipManifest, readPluginZip } from '@cervio/plugin-core'
|
|
13
23
|
|
|
14
|
-
|
|
24
|
+
// Pack a built plugin folder (manifest.json + dist/) exactly as the CLI does.
|
|
15
25
|
const packed = await packPlugin({ dir: '.' })
|
|
26
|
+
if (!packed.ok) throw new Error(packed.error)
|
|
27
|
+
console.log(packed.value.pluginKey, packed.value.contentSha256)
|
|
28
|
+
|
|
29
|
+
// Read and validate an existing archive.
|
|
30
|
+
const manifest = await parseZipManifest(packed.value.buffer)
|
|
31
|
+
|
|
32
|
+
// Open a ZIP with the same safety checks as the host.
|
|
33
|
+
const zip = await readPluginZip(packed.value.buffer)
|
|
34
|
+
if (zip.ok) console.log(zip.value.paths)
|
|
16
35
|
```
|
|
17
36
|
|
|
18
|
-
|
|
37
|
+
Functions return `{ ok: true, value }` or `{ ok: false, error }`, where `error` is a stable
|
|
38
|
+
code such as `manifest_not_found_in_zip`, `build_index_missing` or `zip_nested_archive`.
|
|
39
|
+
|
|
40
|
+
## API
|
|
41
|
+
|
|
42
|
+
| Area | Exports |
|
|
43
|
+
|---|---|
|
|
44
|
+
| Manifest | `parseManifestObject`, `parseZipManifest`, `normalizePluginKey`, `manifestJsonForContentHash`, `parsePluginEntityRequirements`, `parsePluginCervioApiRequirements`, `parsePluginBootRequests`, `isDeclarableCervioApiRequirement`, `isDeclaredCervioApiRequest` |
|
|
45
|
+
| ZIP | `readPluginZip` (safety checks before inflating: entry count, paths, nested archives, sizes, compression ratio), `assertZipFile`, limits `MAX_PLUGIN_ZIP_BYTES`, `MAX_PLUGIN_ZIP_ENTRIES`, `MAX_PLUGIN_UNCOMPRESSED_BYTES` |
|
|
46
|
+
| Packing | `packPlugin` (reproducible archives), `validatePluginDir`, `validatePluginZipBuffer` |
|
|
47
|
+
| Hash and versions | `computePluginContentSha256`, `sha256Hex`, `nextPatchVersion`, `compareSemverDesc` |
|
|
48
|
+
| Write-gate plugins | `isPolicyPluginType`, `normalizeToPolicyPluginType`, policy contract types |
|
|
49
|
+
|
|
50
|
+
`@cervio/plugin-core/browser` is the subset that runs in a browser (no `fs`): ZIP checks
|
|
51
|
+
and the API declaration helpers. `@cervio/plugin-core/manifest.schema.json` is the JSON
|
|
52
|
+
schema of `manifest.json`: point your editor at it with `"$schema"`.
|
|
53
|
+
|
|
54
|
+
The export list is the public API and follows semver; anything else is internal.
|
|
55
|
+
|
|
56
|
+
## Versions
|
|
57
|
+
|
|
58
|
+
This package's version is independent of the release versions of your plugins, which
|
|
59
|
+
the Cervio host assigns on upload: never put `version` in `manifest.json`.
|
|
60
|
+
|
|
61
|
+
Documentation: [docs.cervio.app](https://docs.cervio.app).
|
|
62
|
+
|
|
63
|
+
## License
|
|
64
|
+
|
|
65
|
+
MIT, see [LICENSE](LICENSE).
|
|
66
|
+
|
|
67
|
+
**Trademark.** "Cervio" and the Cervio logo are trademarks of Cervio S.r.l. This license
|
|
68
|
+
does not grant permission to use them. You may say that a plugin "works with Cervio"; you
|
|
69
|
+
may not imply endorsement or ship a product named Cervio.
|
|
70
|
+
|
|
71
|
+
**Platform.** Using a Cervio organization is governed by your partner or customer
|
|
72
|
+
agreement, not by this license.
|
|
19
73
|
|
|
20
|
-
**
|
|
74
|
+
**Your plugins.** Plugins you write are yours: using this package gives Cervio no rights
|
|
75
|
+
over your plugin, and does not require you to open-source it.
|