@ampless/runtime 1.0.0-alpha.27 → 1.0.0-alpha.29

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest } from 'ampless';
+import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
@@ -269,6 +269,45 @@ interface ThemeConfigApi {
  */
 declare function renderThemeCss(cssVars: Record<string, string>): string;
 
+/**
+ * Resolve `<packageName>/package.json`, read it, and return the
+ * `amplessPlugin` field as a typed `PluginPackageManifest`. Returns
+ * `null` for any failure — the caller skips cross-check rather than
+ * aborting plugin loading.
+ *
+ * Failure modes that resolve to `null`:
+ *   - Package not installed at this resolution root
+ *     (`ERR_MODULE_NOT_FOUND`)
+ *   - `package.json` not in the package's `exports`
+ *     (`ERR_PACKAGE_PATH_NOT_EXPORTED`) — see the spec under
+ *     `docs/tmp/plugin-extension-phase5.md` §B
+ *   - `readFileSync` throws (e.g. ENOENT, permissions)
+ *   - JSON parse error
+ *   - `amplessPlugin` field absent or not an object
+ *   - `amplessPlugin` field present but structurally invalid (e.g.
+ *     `apiVersion` not a number, `capabilities` not an array of
+ *     strings, `trustLevel` not one of the three allowed values) —
+ *     see `isValidManifest`
+ *
+ * The structural check matters: without it, a downstream consumer
+ * like `crossCheckStaticManifest`'s `for ... of` over the manifest's
+ * `capabilities` would crash on `capabilities: {}` or `capabilities: 42`,
+ * which is at odds with the "non-apiVersion mismatches warn rather
+ * than throw" policy.
+ *
+ * After this function returns a non-null value, the caller can trust
+ * every field it inspects has the declared type; mismatches against
+ * the factory return value are still surfaced as warnings (or, for
+ * `apiVersion`, throws) by the caller itself.
+ */
+declare function loadPackageManifest(packageName: string): PluginPackageManifest | null;
+/**
+ * Maximum `apiVersion` value this runtime can host. Plugins declaring
+ * a higher value are rejected at constructor time — the runtime can't
+ * safely call into surfaces it doesn't know about yet.
+ */
+declare const SUPPORTED_API_VERSION: 1;
+
 declare function renderBody(post: Post): string;
 /**
  * Convert a tiptap doc to its HTML form. Same renderer the public
@@ -450,4 +489,4 @@ interface Ampless {
  */
 declare function createAmpless(opts: CreateAmplessOpts): Ampless;
 
-export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type CreateAmplessOpts, DEFAULT_COLOR_SCHEME, type DataOutput, type EffectiveSiteSettings, type EffectiveThemeConfig, type ListPostsByTagOptions, type ListPostsOptions, type ListPostsResult, type MediaApi, type PluginHeadApi, type PluginSettingsApi, type PluginSettingsSnapshot, type PostsApi, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };
+export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type CreateAmplessOpts, DEFAULT_COLOR_SCHEME, type DataOutput, type EffectiveSiteSettings, type EffectiveThemeConfig, type ListPostsByTagOptions, type ListPostsOptions, type ListPostsResult, type MediaApi, type PluginHeadApi, type PluginSettingsApi, type PluginSettingsSnapshot, type PostsApi, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -234,6 +234,53 @@ import {
   isValidPluginKey,
   resolvePluginSettings
 } from "ampless";
+
+// src/plugin-package-manifest.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+var TRUST_LEVELS = ["untrusted", "trusted", "privileged"];
+function isValidManifest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.apiVersion !== "number") return false;
+  if (typeof v.name !== "string") return false;
+  if (typeof v.trustLevel !== "string") return false;
+  if (!TRUST_LEVELS.includes(v.trustLevel)) return false;
+  if (!Array.isArray(v.capabilities)) return false;
+  for (const c of v.capabilities) {
+    if (typeof c !== "string") return false;
+  }
+  return true;
+}
+function loadPackageManifest(packageName) {
+  let resolvedUrl;
+  try {
+    resolvedUrl = import.meta.resolve(`${packageName}/package.json`);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = readFileSync(fileURLToPath(resolvedUrl), "utf8");
+  } catch {
+    return null;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof pkg !== "object" || pkg === null || !("amplessPlugin" in pkg)) {
+    return null;
+  }
+  const manifest = pkg.amplessPlugin;
+  if (!isValidManifest(manifest)) return null;
+  return manifest;
+}
+var SUPPORTED_API_VERSION = 1;
+
+// src/plugin-head.ts
 function isPlugin2(p) {
   return typeof p === "object" && p !== null && "apiVersion" in p;
 }
@@ -277,6 +324,50 @@ function warn(message) {
   if (!isDev()) return;
   console.warn(`[ampless plugin-head] ${message}`);
 }
+function crossCheckStaticManifest(plugin, label) {
+  const packageName = plugin.packageName;
+  const manifest = loadPackageManifest(packageName);
+  if (!manifest) return;
+  if (typeof manifest.apiVersion !== "number") {
+    throw new Error(
+      `${label}: package.json#amplessPlugin.apiVersion is not a number (got ${JSON.stringify(manifest.apiVersion)}). Update the plugin's package.json or remove the amplessPlugin field.`
+    );
+  }
+  if (manifest.apiVersion > SUPPORTED_API_VERSION) {
+    throw new Error(
+      `${label}: package.json#amplessPlugin.apiVersion ${manifest.apiVersion} is newer than this runtime supports (max ${SUPPORTED_API_VERSION}). Upgrade @ampless/runtime, or pin an older version of the plugin.`
+    );
+  }
+  if (manifest.apiVersion !== plugin.apiVersion) {
+    throw new Error(
+      `${label}: apiVersion mismatch \u2014 package.json declares ${manifest.apiVersion}, factory declares ${plugin.apiVersion}. The two must agree.`
+    );
+  }
+  if (manifest.name !== plugin.name) {
+    warn(
+      `${label}: name mismatch \u2014 package.json#amplessPlugin.name is "${manifest.name}", factory returns name="${plugin.name}". Align them so admin UI / capability gates can identify the plugin consistently.`
+    );
+  }
+  if (manifest.trustLevel !== plugin.trust_level) {
+    warn(
+      `${label}: trustLevel mismatch \u2014 package.json declares "${manifest.trustLevel}", factory declares trust_level="${plugin.trust_level}". The processor IAM policies are wired off trust_level; drift here usually means the deployment lambda runs in the wrong context.`
+    );
+  }
+  const factoryCaps = Array.isArray(plugin.capabilities) ? plugin.capabilities : [];
+  const manifestCaps = manifest.capabilities;
+  if (!setsEqual(factoryCaps, manifestCaps)) {
+    warn(
+      `${label}: capabilities mismatch \u2014 package.json declares [${manifestCaps.join(", ")}], factory declares [${factoryCaps.join(", ")}]. The static manifest is what npm registry / admin UI surfaces show before the plugin loads, so it should match what the factory actually returns.`
+    );
+  }
+}
+function setsEqual(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const c of sb) if (!sa.has(c)) return false;
+  return true;
+}
 function applyAttrs(target, attrs, ownerLabel) {
   if (!attrs) return;
   for (const [k, v] of Object.entries(attrs)) {
@@ -549,6 +640,9 @@ function createPluginHead(cmsConfig, pluginSettings) {
       }
     }
     validPlugins.push(plugin);
+    if (plugin.packageName) {
+      crossCheckStaticManifest(plugin, label);
+    }
     const caps = plugin.capabilities;
     if (caps) {
       if (caps.includes("publicHead") && !plugin.publicHead) {
@@ -1120,12 +1214,14 @@ function createAmpless(opts) {
 export {
   COLOR_SCHEME_SETTING_KEY,
   DEFAULT_COLOR_SCHEME,
+  SUPPORTED_API_VERSION,
   _resetStreamS3Cache,
   createAmpless,
   createPluginHead,
   createPluginSettings,
   escapeJsonLdInlineBody,
   htmlToMarkdown,
+  loadPackageManifest,
   markdownToHtml,
   renderBody,
   renderThemeCss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-alpha.27",
+  "version": "1.0.0-alpha.29",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -49,8 +49,8 @@
     "lucide-react": "^1.16.0",
     "marked": "^18.0.4",
     "tailwind-merge": "^3.6.0",
-    "ampless": "1.0.0-alpha.21",
-    "@ampless/plugin-og-image": "0.2.0-alpha.21"
+    "@ampless/plugin-og-image": "0.2.0-alpha.23",
+    "ampless": "1.0.0-alpha.23"
   },
   "peerDependencies": {
     "next": "^15 || ^16",