@ampless/runtime 1.0.0-beta.66 → 1.0.0-beta.68

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Post, MediaMetadata, AmplessPlugin, ContentFieldRenderer, PluginPublicRenderContext, TiptapNodeHtmlAdapters, TiptapNodeMarkdownAdapters, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
+import { Post, MediaMetadata, AmplessPlugin, ContentFieldRenderer, TiptapNodeMarkdownAdapters, PluginPublicRenderContext, TiptapNodeHtmlAdapters, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
@@ -188,6 +188,21 @@ interface ContentFieldRegistry {
  * render that happens to walk the conflicting node.
  */
 declare function buildContentFieldRegistry(plugins: readonly AmplessPlugin[]): ContentFieldRegistry;
+/**
+ * Merge every plugin's server-safe `tiptapNodeToMarkdown` map into a
+ * single `TiptapNodeMarkdownAdapters` registry. Eagerly errors on
+ * duplicate `nodeType` registration across plugins (two different
+ * functions) so the misuse surfaces at config time, not at the first
+ * markdown conversion that happens to walk the conflicting node. The
+ * exact same function registered twice (e.g. one shared adapter map
+ * reused by two plugin instances) is tolerated.
+ *
+ * Non-function entries are skipped with a warning rather than thrown:
+ * `definePlugin` already warns about them at definition time, and one
+ * broken plugin shouldn't take the whole site's markdown output down
+ * (a nodeType conflict, by contrast, is a config error — that throws).
+ */
+declare function buildMarkdownAdapterRegistry(plugins: readonly AmplessPlugin[]): TiptapNodeMarkdownAdapters;
 interface RenderBodyOptions {
     contentFields?: ContentFieldRegistry;
     /**
@@ -280,6 +295,54 @@ declare function tiptapToMarkdown(doc: unknown, opts?: {
  * relied on.
  */
 declare function htmlToMarkdown(html: string): string;
+interface PostToMarkdownOptions {
+    /**
+     * Per-nodeType tiptap→markdown serialisers (plugin embed nodes →
+     * bare URL lines). `createAmpless` injects
+     * `pluginHead.markdownAdapters`; a raw direct caller can omit this
+     * to fall back to the built-in switch (unknown atom nodes then emit
+     * unsupported-node placeholder comments).
+     */
+    nodeAdapters?: TiptapNodeMarkdownAdapters;
+    /** Prepend YAML frontmatter (default: true). */
+    frontmatter?: boolean;
+    /**
+     * Absolute site origin used to build the frontmatter's `canonical`
+     * line (`<siteUrl>/<slug>`). Omitted → no canonical line.
+     */
+    siteUrl?: string;
+}
+/**
+ * Convert a public post into its canonical Markdown representation:
+ * YAML frontmatter + format-dependent body. This is the single
+ * conversion point for every AI-readable surface (the `/<slug>.md`
+ * route, llms-full, public MCP `get_post`) — new surfaces should call
+ * this rather than reimplementing the format branches.
+ *
+ * Frontmatter carries **public fields only** (title / slug /
+ * publishedAt / updatedAt / tags / excerpt / canonical) — never
+ * postId, status, or metadata. Values are encoded with
+ * `JSON.stringify`: a JSON string is a valid YAML double-quoted
+ * scalar and a JSON array is a valid YAML flow sequence, so quoting /
+ * escaping is correct without a YAML library.
+ *
+ * Body quality varies by format:
+ *   - `markdown`: the stored source, verbatim.
+ *   - `tiptap`: `tiptapToMarkdown` with `opts.nodeAdapters` (plugin
+ *     embeds become bare URL lines; unknown atom nodes emit an
+ *     `ampless:unsupported-node` placeholder comment).
+ *   - `html`: `htmlToMarkdown` — regex-based and approximate; complex
+ *     markup may not fully survive (see htmlToMarkdown's limits).
+ *   - `static`: no body conversion (the bundle bytes live in S3) — a
+ *     markdown link to the served entrypoint, plus the excerpt when
+ *     present.
+ *
+ * Pure, synchronous, and node-safe — same tier as `tiptapToMarkdown` /
+ * `htmlToMarkdown`. Themes / routes should usually call it through
+ * `ampless.postToMarkdown(post)`, which injects the plugin adapter
+ * registry and the effective site URL.
+ */
+declare function postToMarkdown(post: Post, opts?: PostToMarkdownOptions): string;
 
 interface PluginHeadApi {
     /**
@@ -328,6 +391,15 @@ interface PluginHeadApi {
      * `contentFields`.
      */
     readonly contentFieldsRegistry: ContentFieldRegistry;
+    /**
+     * Merged tiptap→markdown adapter registry across all valid plugins
+     * (server-safe `tiptapNodeToMarkdown` manifests). Built once at
+     * `createPluginHead` construction time so duplicate `nodeType`
+     * registrations across plugins throw eagerly (config error).
+     * Threaded into `rendering.ts:postToMarkdown()` via
+     * `Ampless.postToMarkdown`.
+     */
+    readonly markdownAdapters: TiptapNodeMarkdownAdapters;
     /**
      * Resolve the per-plugin `PluginPublicRenderContext` snapshot used by
      * `contentFields` renderers. Same `settings()` binding the public
@@ -652,6 +724,22 @@ interface Ampless {
      * complete HTML documents that don't expand embed shortcuts.
      */
     renderBodyHtmlString(post: Post): string;
+    /**
+     * Convert a post into its canonical Markdown representation (YAML
+     * frontmatter + body). This is the **single conversion point** for
+     * every AI-readable surface — the `/<slug>.md` route, llms-full, and
+     * the public MCP `get_post` all go through here rather than
+     * reimplementing the format branches. Plugin embed nodes are
+     * serialised via `pluginHead.markdownAdapters` (bare URL lines);
+     * `format: 'html'` bodies go through the regex-based `htmlToMarkdown`
+     * and are approximate. Async because the frontmatter's `canonical`
+     * line needs the effective `site.url` from the S3 site-settings
+     * cache; with `frontmatter: false` that read is skipped entirely and
+     * only the body is returned.
+     */
+    postToMarkdown(post: Post, opts?: {
+        frontmatter?: boolean;
+    }): Promise<string>;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
     isStorageConfigured(): boolean;
@@ -677,4 +765,4 @@ interface Ampless {
  */
 declare function createAmpless(opts: CreateAmplessOpts): Ampless;
 
-export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type ContentFieldRegistry, 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 PublicHtmlForPostResult, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type RenderBodyOptions, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, buildContentFieldRegistry, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, renderBody, renderBodyHtmlString, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };
+export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type ContentFieldRegistry, 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 PostToMarkdownOptions, type PostsApi, type PublicHtmlForPostResult, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type RenderBodyOptions, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, buildContentFieldRegistry, buildMarkdownAdapterRegistry, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, postToMarkdown, renderBody, renderBodyHtmlString, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -399,6 +399,29 @@ function buildContentFieldRegistry(plugins) {
   }
   return { tiptap, markdownUrl, htmlPlaceholder };
 }
+function buildMarkdownAdapterRegistry(plugins) {
+  const merged = {};
+  for (const plugin of plugins) {
+    const adapters = plugin.tiptapNodeToMarkdown;
+    if (!adapters) continue;
+    for (const [nodeType, adapter] of Object.entries(adapters)) {
+      if (typeof adapter !== "function") {
+        console.warn(
+          `[ampless markdownAdapters] plugin "${plugin.instanceId ?? plugin.name}" declares a non-function tiptapNodeToMarkdown entry for nodeType "${nodeType}". Skipping the entry.`
+        );
+        continue;
+      }
+      const existing = merged[nodeType];
+      if (existing && existing !== adapter) {
+        throw new Error(
+          `[ampless markdownAdapters] duplicate tiptap nodeType "${nodeType}" \u2014 already registered by another plugin. Each nodeType may be claimed by at most one plugin.`
+        );
+      }
+      merged[nodeType] = adapter;
+    }
+  }
+  return merged;
+}
 function htmlPassthrough(html) {
   return createElement("span", { dangerouslySetInnerHTML: { __html: html } });
 }
@@ -776,9 +799,19 @@ function tiptapNodeToMarkdown(node, opts) {
 `;
     }
     default:
-      return children;
+      if (children) return children;
+      console.warn(
+        `[ampless] tiptapToMarkdown: no adapter for node type "${String(node.type)}" \u2014 emitting placeholder`
+      );
+      return `
+<!-- ampless:unsupported-node type="${sanitizeNodeTypeForComment(node.type)}" -->
+
+`;
   }
 }
+function sanitizeNodeTypeForComment(type) {
+  return String(type).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+}
 function tiptapTableToMarkdown(node, opts) {
   const rows = node.content ?? [];
   if (rows.length === 0) return "";
@@ -902,6 +935,62 @@ function convertHtmlTaskList(items) {
   }
   return out.join("\n");
 }
+function postToMarkdown(post, opts = {}) {
+  const frontmatter = opts.frontmatter !== false ? postFrontmatter(post, opts.siteUrl) : "";
+  return frontmatter + postBodyToMarkdown(post, opts);
+}
+function postFrontmatter(post, siteUrl) {
+  const lines = [];
+  lines.push(`title: ${JSON.stringify(post.title)}`);
+  lines.push(`slug: ${JSON.stringify(post.slug)}`);
+  if (post.publishedAt) lines.push(`publishedAt: ${JSON.stringify(post.publishedAt)}`);
+  if (post.updatedAt) lines.push(`updatedAt: ${JSON.stringify(post.updatedAt)}`);
+  if (post.tags && post.tags.length > 0) lines.push(`tags: ${JSON.stringify(post.tags)}`);
+  if (post.excerpt) lines.push(`excerpt: ${JSON.stringify(post.excerpt)}`);
+  if (siteUrl) {
+    const origin = siteUrl.replace(/\/+$/, "");
+    lines.push(`canonical: ${JSON.stringify(`${origin}/${post.slug}`)}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+`;
+}
+function postBodyToMarkdown(post, opts) {
+  switch (post.format) {
+    case "markdown":
+      return typeof post.body === "string" ? post.body : String(post.body ?? "");
+    case "tiptap":
+      return tiptapToMarkdown(post.body, { nodeAdapters: opts.nodeAdapters });
+    case "html":
+      return htmlToMarkdown(String(post.body));
+    case "static": {
+      const link = `[${staticEntrypoint(post.body)}](/${post.slug}/)`;
+      return post.excerpt ? `${link}
+
+${post.excerpt}
+` : `${link}
+`;
+    }
+    default:
+      return "";
+  }
+}
+function staticEntrypoint(body) {
+  let manifest = body;
+  if (typeof manifest === "string") {
+    try {
+      manifest = JSON.parse(manifest);
+    } catch {
+      return "index.html";
+    }
+  }
+  if (typeof manifest === "object" && manifest !== null && typeof manifest.entrypoint === "string" && manifest.entrypoint.length > 0) {
+    return manifest.entrypoint;
+  }
+  return "index.html";
+}
 
 // src/plugin-package-manifest.ts
 var TRUST_LEVELS = ["untrusted", "trusted", "privileged"];
@@ -1520,6 +1609,7 @@ function createPluginHead(cmsConfig, pluginSettings) {
     }
   }
   const contentFieldsRegistry = buildContentFieldRegistry(validPlugins);
+  const markdownAdapters = buildMarkdownAdapterRegistry(validPlugins);
   for (const plugin of validPlugins) {
     const caps = plugin.capabilities;
     if (!caps) continue;
@@ -1581,6 +1671,7 @@ function createPluginHead(cmsConfig, pluginSettings) {
       return collectPostScriptsForPage(validPlugins, cmsConfig.site, snapshot, posts);
     },
     contentFieldsRegistry,
+    markdownAdapters,
     async contextForPlugins() {
       const snapshot = await pluginSettings.loadAll();
       return (plugin) => makeCtx(plugin, cmsConfig.site, snapshot);
@@ -1847,6 +1938,19 @@ function createAmpless(opts) {
       });
     },
     renderBodyHtmlString: (post) => renderBodyHtmlString(post),
+    postToMarkdown: async (post, o) => {
+      if (o?.frontmatter === false) {
+        return postToMarkdown(post, {
+          nodeAdapters: pluginHead.markdownAdapters,
+          frontmatter: false
+        });
+      }
+      const { site } = await settings.loadSiteSettings();
+      return postToMarkdown(post, {
+        nodeAdapters: pluginHead.markdownAdapters,
+        siteUrl: site.url || void 0
+      });
+    },
     renderThemeCss: (cssVars) => renderThemeCss(cssVars),
     publicAssetUrl: (key) => storage.publicAssetUrl(key),
     isStorageConfigured: () => storage.isStorageConfigured(),
@@ -1870,6 +1974,7 @@ export {
   SUPPORTED_API_VERSION,
   _resetStreamS3Cache,
   buildContentFieldRegistry,
+  buildMarkdownAdapterRegistry,
   createAmpless,
   createPluginHead,
   createPluginSettings,
@@ -1877,6 +1982,7 @@ export {
   htmlToMarkdown,
   loadPackageManifest,
   markdownToHtml,
+  postToMarkdown,
   renderBody,
   renderBodyHtmlString,
   renderThemeCss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-beta.66",
+  "version": "1.0.0-beta.68",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -51,8 +51,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "tailwind-merge": "^3.6.0",
-    "@ampless/plugin-og-image": "0.2.0-beta.54",
-    "ampless": "1.0.0-beta.54"
+    "@ampless/plugin-og-image": "0.2.0-beta.55",
+    "ampless": "1.0.0-beta.55"
   },
   "peerDependencies": {
     "@aws-amplify/adapter-nextjs": "^1",