@cervio/plugin-core 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -94,6 +94,15 @@ declare function parseZipManifest(file: Blob | ArrayBuffer | Uint8Array, options
 declare function computePluginContentSha256(zip: PluginZip, rawManifest: Record<string, unknown>): PluginActionResult<string>;
 declare function sha256Hex(buffer: Buffer | Uint8Array): string;
 
+/**
+ * Non-blocking advice from `validatePluginDir` on how fast the plugin opens.
+ * A plugin with hints is still valid and can be pushed.
+ */
+type PluginStartupHint = {
+    code: 'boot_requests_missing' | 'mark_ready_missing' | 'boot_request_hardcoded_view';
+    message: string;
+};
+
 type PackPluginResult = {
     buffer: Buffer;
     pluginKey: string;
@@ -108,10 +117,14 @@ declare function packPlugin(opts: {
     dir: string;
     options?: ParseManifestOptions;
 }): Promise<PluginActionResult<PackPluginResult>>;
-/** Validate an on-disk plugin directory (or an existing ZIP) without uploading. */
+/**
+ * Validate an on-disk plugin directory without uploading. `hints` is
+ * non-blocking advice on start-up speed (boot_requests, markReady).
+ */
 declare function validatePluginDir(dir: string, options?: ParseManifestOptions): Promise<PluginActionResult<{
     pluginKey: string;
     contentSha256: string;
+    hints: PluginStartupHint[];
 }>>;
 declare function validatePluginZipBuffer(buffer: Buffer, options?: ParseManifestOptions): Promise<PluginActionResult<{
     pluginKey: string;
@@ -119,4 +132,4 @@ declare function validatePluginZipBuffer(buffer: Buffer, options?: ParseManifest
 }>>;
 
 export { ParseManifestOptions, ParsedPluginManifest, PluginActionResult, PluginBootRequest, PluginCervioApiRequirement, PluginConnectionRequirement, PluginEntityRequirement, PluginSettingsFieldRequirement, PluginType, PluginZip, compareSemverDesc, computePluginContentSha256, isPolicyPluginType, manifestJsonForContentHash, nextPatchVersion, normalizePluginKey, normalizeToPolicyPluginType, packPlugin, parseManifestObject, parseZipManifest, sha256Hex, validatePluginDir, validatePluginZipBuffer };
-export type { PackPluginResult, PolicyHookCaller, PolicyHookEvent, PolicyHookInput, PolicyHookResult, PolicyHost };
+export type { PackPluginResult, PluginStartupHint, PolicyHookCaller, PolicyHookEvent, PolicyHookInput, PolicyHookResult, PolicyHost };

package/dist/index.js

@@ -634,6 +634,44 @@ function computePluginContentSha256(zip, rawManifest) {
 function sha256Hex(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
+
+// src/startup-hints.ts
+var ANSWERED_AT_BOOT = /* @__PURE__ */ new Set(["/api/v1/me", "/api/v1/entities"]);
+var MARK_READY_MARKER = "__cervioPluginReady";
+var VIEW_ID_IN_PATH = /\/api\/v1\/views\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\//i;
+var isIframePlugin = (t) => t === "route" || t === "task" || t === "task_form" || t === "form";
+function pluginStartupHints(input) {
+  if (!isIframePlugin(input.pluginType)) return [];
+  const hints = [];
+  const readsData = input.cervioApis.some(
+    (a) => a.method.toUpperCase() === "GET" && !ANSWERED_AT_BOOT.has(a.path_prefix)
+  );
+  if (input.pluginType === "route" && readsData && input.bootRequests.length === 0) {
+    hints.push({
+      code: "boot_requests_missing",
+      message: "No boot_requests: list the GET calls of the first screen in manifest.json (same path and query as the code). Cervio starts them while the plugin loads (measured: data on screen 350-500 ms sooner on the first open, 75-220 ms on later ones)."
+    });
+  }
+  if (!input.bundleText.includes(MARK_READY_MARKER)) {
+    hints.push({
+      code: "mark_ready_missing",
+      message: "markReady() is never called: call it from '@cervio/plugin-sdk' once the first data is on screen (also on error). Cervio keeps its loading skeleton until then and uses it to time the plugin open."
+    });
+  }
+  const viewKeys = input.settings.filter((s) => s.type === "string" && /view/i.test(s.key)).map((s) => s.key);
+  for (const b of input.bootRequests) {
+    const m = VIEW_ID_IN_PATH.exec(b.path);
+    if (!m) continue;
+    const placeholder = viewKeys.length ? `{settings.${viewKeys[0]}}` : "{settings.<key>}";
+    hints.push({
+      code: "boot_request_hardcoded_view",
+      message: `boot_requests path "${b.path}" has a fixed view id: write ${placeholder} instead` + (viewKeys.length ? "" : " and add a string setting for the view") + ", so the prefetch follows the view chosen in each organization."
+    });
+  }
+  return hints;
+}
+
+// src/pack.ts
 var ZIP_MTIME = /* @__PURE__ */ new Date("2000-01-01T00:00:00Z");
 async function collectFiles(dir, base = "") {
   const entries = await promises.readdir(dir, { withFileTypes: true });
@@ -729,16 +767,43 @@ async function packPlugin(opts) {
     }
   };
 }
+async function readBundleText(root) {
+  const dist = path.join(
+    /*turbopackIgnore: true*/
+    root,
+    "dist"
+  );
+  let files;
+  try {
+    files = await collectFiles(dist);
+  } catch {
+    return "";
+  }
+  const parts = [];
+  for (const f of files) {
+    if (/\.(m?js|html)$/i.test(f.rel)) parts.push(await promises.readFile(f.abs, "utf8"));
+  }
+  return parts.join("\n");
+}
 async function validatePluginDir(dir, options) {
   const packed = await packPlugin({ dir, options });
   if (!packed.ok) return packed;
   const parsed = await parseZipManifest(packed.value.buffer, options);
   if (!parsed.ok) return parsed;
+  const fields = parsed.value;
+  const hints = pluginStartupHints({
+    pluginType: fields.pluginType,
+    cervioApis: fields.cervioApis,
+    bootRequests: fields.bootRequests,
+    settings: fields.settings,
+    bundleText: isPolicyPluginType(fields.pluginType) ? "" : await readBundleText(path.resolve(dir))
+  });
   return {
     ok: true,
     value: {
       pluginKey: packed.value.pluginKey,
-      contentSha256: packed.value.contentSha256
+      contentSha256: packed.value.contentSha256,
+      hints
     }
   };
 }

package/package.json

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