@cervio/plugin-core 1.0.0 → 1.2.0

package/README.md

@@ -1,20 +1,75 @@
 # @cervio/plugin-core
 
-Shared Cervio plugin contracts: manifest parsing, ZIP safety, content hashing, semver assignment helpers, and `packPlugin()`.
+The Cervio plugin contract: manifest parsing and validation, ZIP safety checks, the
+content hash, release version helpers and packing.
 
-Used by the Cervio host and by `@cervio/cli` so local `cervio validate` matches server upload checks.
+The Cervio host validates every plugin upload with this package, and `@cervio/cli` uses
+the same code for `cervio validate` and `cervio pack`: a plugin that passes locally passes
+on upload. You rarely need it directly: plugin code uses
+[`@cervio/plugin-sdk`](https://www.npmjs.com/package/@cervio/plugin-sdk) and the
+[`cervio` CLI](https://www.npmjs.com/package/@cervio/cli). Use it to build your own
+tooling around plugin archives.
+
+Requires Node.js 26 or later. ESM only.
 
 ```bash
-pnpm add @cervio/plugin-core
+npm install @cervio/plugin-core
 ```
 
+## Usage
+
 ```ts
-import { parseManifestObject, packPlugin, nextPatchVersion } from '@cervio/plugin-core'
+import { packPlugin, parseZipManifest, readPluginZip } from '@cervio/plugin-core'
 
-const fields = parseManifestObject(manifestJson)
+// Pack a built plugin folder (manifest.json + dist/) exactly as the CLI does.
 const packed = await packPlugin({ dir: '.' })
+if (!packed.ok) throw new Error(packed.error)
+console.log(packed.value.pluginKey, packed.value.contentSha256)
+
+// Read and validate an existing archive.
+const manifest = await parseZipManifest(packed.value.buffer)
+
+// Open a ZIP with the same safety checks as the host.
+const zip = await readPluginZip(packed.value.buffer)
+if (zip.ok) console.log(zip.value.paths)
 ```
 
-See docs at `docs.cervio.app` (when deployed) and [Authoring](https://docs.cervio.app/docs/authoring) in the Cervio repo.
+Functions return `{ ok: true, value }` or `{ ok: false, error }`, where `error` is a stable
+code such as `manifest_not_found_in_zip`, `build_index_missing` or `zip_nested_archive`.
+
+## API
+
+| Area | Exports |
+|---|---|
+| Manifest | `parseManifestObject`, `parseZipManifest`, `normalizePluginKey`, `manifestJsonForContentHash`, `parsePluginEntityRequirements`, `parsePluginCervioApiRequirements`, `parsePluginBootRequests`, `isDeclarableCervioApiRequirement`, `isDeclaredCervioApiRequest` |
+| 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` |
+| Packing | `packPlugin` (reproducible archives), `validatePluginDir`, `validatePluginZipBuffer` |
+| Hash and versions | `computePluginContentSha256`, `sha256Hex`, `nextPatchVersion`, `compareSemverDesc` |
+| Write-gate plugins | `isPolicyPluginType`, `normalizeToPolicyPluginType`, policy contract types |
+
+`@cervio/plugin-core/browser` is the subset that runs in a browser (no `fs`): ZIP checks
+and the API declaration helpers. `@cervio/plugin-core/manifest.schema.json` is the JSON
+schema of `manifest.json`: point your editor at it with `"$schema"`.
+
+The export list is the public API and follows semver; anything else is internal.
+
+## Versions
+
+This package's version is independent of the release versions of your plugins, which
+the Cervio host assigns on upload: never put `version` in `manifest.json`.
+
+Documentation: [docs.cervio.app](https://docs.cervio.app).
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+**Trademark.** "Cervio" and the Cervio logo are trademarks of Cervio S.r.l. This license
+does not grant permission to use them. You may say that a plugin "works with Cervio"; you
+may not imply endorsement or ship a product named Cervio.
+
+**Platform.** Using a Cervio organization is governed by your partner or customer
+agreement, not by this license.
 
-**Versioning note:** this package version is independent of plugin release versions (assigned by the host) and of `@cervio/plugin-sdk` (tracks CervioUI API).
+**Your plugins.** Plugins you write are yours: using this package gives Cervio no rights
+over your plugin, and does not require you to open-source it.

package/dist/{browser-Ddj__JFI.d.ts → browser-CWGIdJMr.d.ts}

@@ -8,6 +8,13 @@
  * Example: `{ "path": "/api/v1/entities/attivita/records?limit=200" }`.
  * `/api/v1/entities/<technical name>/...` is accepted: the host also matches
  * the same path with the entity id the plugin may use.
+ *
+ * `{settings.<key>}` takes the value of one of the plugin's `settings`, filled
+ * by the host per organization (URL-encoded). Views are chosen per organization,
+ * so their id cannot be written in the manifest:
+ * `{ "path": "/api/v1/views/{settings.view_id}/records?limit=50" }`. When the
+ * setting is empty the host skips that entry and the plugin's call goes the
+ * normal way.
  */
 type PluginBootRequest = {
     /** Absolute path + optional query under `/api/v1/`, e.g. `/api/v1/entities/x/records?limit=50`. */

package/dist/browser.d.ts

@@ -1 +1 @@
-export { M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, a as PluginActionResult, g as PluginBootRequest, e as PluginCervioApiRequirement, i as PluginZip, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';
+export { M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, a as PluginActionResult, g as PluginBootRequest, e as PluginCervioApiRequirement, i as PluginZip, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, x as readPluginZip } from './browser-CWGIdJMr.js';

package/dist/browser.js

@@ -145,10 +145,12 @@ function parsePluginCervioApiRequirements(raw) {
 // src/boot-requests.ts
 var MAX_PLUGIN_BOOT_REQUESTS = 8;
 var MAX_BOOT_PATH_LEN = 400;
+var SETTING_PLACEHOLDER_RE = /\{settings\.([A-Za-z0-9_]{1,64})\}/g;
+var PLACEHOLDER_PROBE = "x";
 function bootRequestPathname(path) {
   if (typeof path !== "string") return null;
-  const p = path.trim();
-  if (!p.startsWith("/api/v1/") || p.length > MAX_BOOT_PATH_LEN || p.includes("#")) return null;
+  const p = path.trim().replace(SETTING_PLACEHOLDER_RE, PLACEHOLDER_PROBE);
+  if (!p.startsWith("/api/v1/") || path.trim().length > MAX_BOOT_PATH_LEN || p.includes("#") || /[{}]/.test(p)) return null;
   const pathname = p.split("?")[0] ?? "";
   if (!isDeclarableCervioApiPrefix(pathname)) return null;
   return pathname;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ParseManifestOptions, a as PluginActionResult, b as PluginType, c as PluginConnectionRequirement, d as PluginEntityRequirement, e as PluginCervioApiRequirement, f as PluginSettingsFieldRequirement, g as PluginBootRequest, h as ParsedPluginManifest, i as PluginZip } from './browser-Ddj__JFI.js';
-export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, l as PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, m as PLUGIN_ARTIFACT_SOFT_WARN_BYTES, n as PLUGIN_KEY_RE, o as PluginEntityAccess, p as PluginSettingsFieldOption, q as PluginSettingsFieldType, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, w as parsePluginEntityRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';
+import { P as ParseManifestOptions, a as PluginActionResult, b as PluginType, c as PluginConnectionRequirement, d as PluginEntityRequirement, e as PluginCervioApiRequirement, f as PluginSettingsFieldRequirement, g as PluginBootRequest, h as ParsedPluginManifest, i as PluginZip } from './browser-CWGIdJMr.js';
+export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, l as PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, m as PLUGIN_ARTIFACT_SOFT_WARN_BYTES, n as PLUGIN_KEY_RE, o as PluginEntityAccess, p as PluginSettingsFieldOption, q as PluginSettingsFieldType, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, w as parsePluginEntityRequirements, x as readPluginZip } from './browser-CWGIdJMr.js';
 
 /**
  * Next patch version assigned by Cervio. Ignores pre-release/build metadata on

package/dist/index.js

@@ -139,15 +139,20 @@ function parsePluginCervioApiRequirements(raw) {
 // src/boot-requests.ts
 var MAX_PLUGIN_BOOT_REQUESTS = 8;
 var MAX_BOOT_PATH_LEN = 400;
+var SETTING_PLACEHOLDER_RE = /\{settings\.([A-Za-z0-9_]{1,64})\}/g;
+var PLACEHOLDER_PROBE = "x";
+function settingKeysOf(path2) {
+  return [...path2.matchAll(SETTING_PLACEHOLDER_RE)].map((m) => m[1]);
+}
 function bootRequestPathname(path2) {
   if (typeof path2 !== "string") return null;
-  const p = path2.trim();
-  if (!p.startsWith("/api/v1/") || p.length > MAX_BOOT_PATH_LEN || p.includes("#")) return null;
+  const p = path2.trim().replace(SETTING_PLACEHOLDER_RE, PLACEHOLDER_PROBE);
+  if (!p.startsWith("/api/v1/") || path2.trim().length > MAX_BOOT_PATH_LEN || p.includes("#") || /[{}]/.test(p)) return null;
   const pathname = p.split("?")[0] ?? "";
   if (!isDeclarableCervioApiPrefix(pathname)) return null;
   return pathname;
 }
-function validatePluginBootRequests(raw, cervioApis) {
+function validatePluginBootRequests(raw, cervioApis, settingKeys) {
   if (raw == null) return { ok: true, value: [] };
   if (!Array.isArray(raw)) return { ok: false, error: "manifest_boot_requests_invalid" };
   if (raw.length > MAX_PLUGIN_BOOT_REQUESTS) return { ok: false, error: "manifest_boot_requests_too_many" };
@@ -161,6 +166,9 @@ function validatePluginBootRequests(raw, cervioApis) {
       return { ok: false, error: "manifest_boot_requests_not_declared" };
     }
     const p = path2.trim();
+    if (settingKeys && settingKeysOf(p).some((k) => !settingKeys.includes(k))) {
+      return { ok: false, error: "manifest_boot_requests_unknown_setting" };
+    }
     if (seen.has(p)) continue;
     seen.add(p);
     out.push({ path: p });
@@ -523,7 +531,11 @@ function parseManifestObject(parsed, options) {
   if (!cervioApisRes.ok) return cervioApisRes;
   const cervioApis = cervioApisRes.value;
   const settings = parsePluginSettingsRequirements(parsed.settings);
-  const bootRequestsRes = validatePluginBootRequests(parsed.boot_requests, cervioApis);
+  const bootRequestsRes = validatePluginBootRequests(
+    parsed.boot_requests,
+    cervioApis,
+    settings.map((f) => f.key)
+  );
   if (!bootRequestsRes.ok) return bootRequestsRes;
   const bootRequests = bootRequestsRes.value;
   return {

package/manifest.schema.json

@@ -220,7 +220,7 @@
             "properties": {
               "path": {
                 "type": "string",
-                "description": "GET path + optional query under /api/v1/, covered by a GET `cervio_apis` prefix."
+                "description": "GET path + optional query under /api/v1/, covered by a GET `cervio_apis` prefix. `{settings.<key>}` takes a plugin setting (e.g. /api/v1/views/{settings.view_id}/records?limit=50)."
               }
             },
             "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cervio/plugin-core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Shared Cervio plugin manifest validation, ZIP safety, content hash, and packing.",
   "keywords": [
     "cervio",