ampless 1.0.0-beta.57 → 1.0.0-beta.59

package/dist/index.d.ts

@@ -337,6 +337,20 @@ type ScriptStrategy = 'afterInteractive' | 'lazyOnload';
  * per-post context lands in Phase 4 (`plugin-per-post-rfp.md`).
  */
 interface PluginPublicRenderContext {
+    /**
+     * The site's `name` / `url` / `description` block. When the caller
+     * wires `@ampless/runtime`'s `createPluginHead(cmsConfig, pluginSettings,
+     * siteSettings)` with its third argument (as `createAmpless` does), this
+     * is the **effective** site settings — the S3-cached admin
+     * `settings.public` override merged over the `cms.config.ts` defaults,
+     * the same value the `/<slug>.md` route's canonical line uses — not
+     * merely a static passthrough of `cms.config.ts`. It falls back to the
+     * `cms.config.ts` block on a site-settings fetch failure, or entirely
+     * when the caller omits `siteSettings` (the two-argument
+     * `createPluginHead` call, kept for backward compatibility). The type
+     * shape (`{ name, url, description? }`) does not change either way —
+     * only which value populates it.
+     */
     site: Config['site'];
     /**
      * Resolve a public setting value for the active plugin instance.
@@ -1987,6 +2001,57 @@ declare function resolvePluginSettings(manifest: PluginSettingsManifest | undefi
  */
 declare function extractFirstImageUrl(post: Post): string | null;
 
+/** How the scan ended. `null` = the fetcher was exhausted cleanly. */
+type BoundedScanTruncation = 'limit' | 'early' | null;
+interface BoundedScanResult<T> {
+    items: T[];
+    /**
+     * - `'limit'` — a `limit + 1`th item was actually fetched, so more
+     *   items exist beyond the returned `limit`; the extra item is
+     *   dropped from `items`.
+     * - `'early'` — one of the safety bounds tripped (`maxPages` reached
+     *   or the same `nextToken` came back twice), so the scan may have
+     *   stopped with more items unread.
+     * - `null` — the fetcher signalled exhaustion (no `nextToken`) at or
+     *   below `limit`.
+     */
+    truncated: BoundedScanTruncation;
+}
+interface BoundedScanOptions {
+    /**
+     * Target item count. The walk collects until it has `limit + 1`
+     * items (the extra confirms there really are more), the fetcher is
+     * exhausted, or a safety bound trips.
+     */
+    limit: number;
+    /** Max items requested per page (default 50). */
+    pageSizeCap?: number;
+    /** Hard cap on pages walked regardless of items collected (default 21). */
+    maxPages?: number;
+}
+interface BoundedScanPage<T> {
+    items: T[];
+    nextToken: string | null;
+}
+/**
+ * Walk `fetchPage` pages until we have `limit + 1` items (the extra
+ * item confirms there really are more items beyond `limit` — a present
+ * `nextToken` alone doesn't guarantee that, since a paginated backend
+ * can return a token alongside zero remaining items), the token is
+ * exhausted, or one of the two safety bounds below trips:
+ *
+ *  - `maxPages` pages walked without reaching either stop condition
+ *  - the same `nextToken` comes back twice (defends against a
+ *    misbehaving resolver looping forever)
+ *
+ * Returns at most `limit` items (the confirming `limit + 1`th item is
+ * dropped) alongside how the scan ended.
+ */
+declare function collectBounded<T>(fetchPage: (args: {
+    limit: number;
+    nextToken?: string;
+}) => Promise<BoundedScanPage<T>>, opts: BoundedScanOptions): Promise<BoundedScanResult<T>>;
+
 type PostListStatusFilter = 'all' | 'draft' | 'published';
 type PostListSort = 'updated-desc' | 'updated-asc' | 'published-desc' | 'published-asc' | 'title-asc' | 'title-desc';
 interface PostListFilterOptions {
@@ -2088,4 +2153,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AiConfig, type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostListFilterOptions, type PostListSort, type PostListStatusFilter, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostSummary, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, type SummaryListOptions, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, collectTags, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, filterSortPostSummaries, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AiConfig, type AmplessEvent, type AmplessPlugin, type AuthContext, type BoundedScanOptions, type BoundedScanPage, type BoundedScanResult, type BoundedScanTruncation, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostListFilterOptions, type PostListSort, type PostListStatusFilter, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostSummary, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, type SummaryListOptions, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, collectBounded, collectTags, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, filterSortPostSummaries, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -501,6 +501,55 @@ function findHtmlImage(body) {
   return m ? m[1] : null;
 }
 
+// src/paging.ts
+var DEFAULT_PAGE_SIZE_CAP = 50;
+var DEFAULT_MAX_PAGES = 21;
+function requirePositiveInt(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(
+      `collectBounded: \`${name}\` must be a finite positive integer, received ${String(value)}`
+    );
+  }
+}
+async function collectBounded(fetchPage, opts) {
+  const limit = opts.limit;
+  const pageSizeCap = opts.pageSizeCap ?? DEFAULT_PAGE_SIZE_CAP;
+  const maxPages = opts.maxPages ?? DEFAULT_MAX_PAGES;
+  requirePositiveInt("limit", limit);
+  requirePositiveInt("pageSizeCap", pageSizeCap);
+  requirePositiveInt("maxPages", maxPages);
+  const items = [];
+  const seenTokens = /* @__PURE__ */ new Set();
+  let token;
+  let truncated = null;
+  for (let page = 0; page < maxPages; page++) {
+    const remaining = limit + 1 - items.length;
+    const pageLimit = Math.min(pageSizeCap, remaining);
+    const res = await fetchPage({ limit: pageLimit, nextToken: token });
+    items.push(...res.items);
+    if (items.length > limit) {
+      truncated = "limit";
+      break;
+    }
+    if (!res.nextToken) {
+      break;
+    }
+    if (seenTokens.has(res.nextToken)) {
+      truncated = "early";
+      break;
+    }
+    seenTokens.add(res.nextToken);
+    token = res.nextToken;
+    if (page === maxPages - 1) {
+      truncated = "early";
+    }
+  }
+  return {
+    items: truncated === "limit" ? items.slice(0, limit) : items,
+    truncated
+  };
+}
+
 // src/post-list-filter.ts
 function filterSortPostSummaries(rows, options = {}) {
   const query = options.query?.trim().toLowerCase() ?? "";
@@ -869,6 +918,7 @@ export {
   TEXT_EXTENSIONS,
   VERSION,
   bundlePrefix,
+  collectBounded,
   collectTags,
   createPost,
   decodeAwsJson,

package/docs/plugin-author-guide.ja.md

@@ -351,6 +351,8 @@ SSR がデッドラインなしでブロックします。ネットワーク呼
 
 `ctx.setting()` は Phase 2 で追加された admin 管理値アクセッサ — §8 参照。
 
+**`ctx.site` は `cms.config.ts` の静的な値そのままではなく、実効 site 設定です。** ホストアプリが `@ampless/runtime` の `createPluginHead(cmsConfig, pluginSettings, siteSettings)` を第 3 引数つきで配線している場合（`createAmpless` は標準でこう配線しており、サイト側のコード変更は不要）、`ctx.site` は admin の `settings.public` override を `cms.config.ts` のデフォルトにマージした値 — `/<slug>.md` ルートの canonical 行が使うのと同じ実効値 — を反映します。site settings の取得に失敗した場合は `cms.config.ts` の値にフォールバックします。型の形（`{ name, url, description? }`）は変わらず、値の意味だけが変わります。`ctx.site.url` から絶対 URL を組み立てるプラグイン（例: `@ampless/plugin-ai-actions` の外部 AI リンク）は、再デプロイなしで admin が編集した site URL の変更を自動的に反映します。
+
 ---
 
 ## 6. Descriptor リファレンス
@@ -1693,6 +1695,8 @@ it('admin が空文字保存した場合は空配列', () => {
 - [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook + 外向き HTTP + `secretSettings` (admin 管理の signing secret、Phase 6a)
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` ルートレンダラ
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability、投稿単位 Article JSON-LD。（Phase 4）
+- [`packages/plugin-reading-time`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-reading-time) — `publicHtmlForPost`、語数推定を本文の前後に `<p>` バッジとして描画。（Phase 6d）
+- [`packages/plugin-ai-actions`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-ai-actions) — `publicHtmlForPost`、`ctx.site.url`（実効 site 設定）と投稿の `/<slug>.md` URL から「Markdown で表示」+ opt-in の「Claude で開く」/「ChatGPT で開く」リンクを組み立てる。（AI-readable publishing ロードマップ Phase B）
 
 ---
 

package/docs/plugin-author-guide.md

@@ -434,6 +434,19 @@ The `ctx` object carries:
 `ctx.setting()` is the Phase 2 admin-managed values accessor — see
 §8.
 
+**`ctx.site` is the effective site settings, not a static passthrough of
+`cms.config.ts`.** When the host app wires `@ampless/runtime`'s
+`createPluginHead(cmsConfig, pluginSettings, siteSettings)` with its third
+argument (as `createAmpless` does — this is the standard wiring, no site
+code changes needed), `ctx.site` reflects admin `settings.public`
+overrides merged over the `cms.config.ts` defaults — the same effective
+value the `/<slug>.md` route's canonical line uses. It falls back to the
+`cms.config.ts` block on a site-settings fetch failure. The shape
+(`{ name, url, description? }`) is unchanged; only which value populates
+it. Plugins that build absolute URLs from `ctx.site.url` (e.g.
+`@ampless/plugin-ai-actions`'s external AI links) automatically track
+admin-edited site URL changes without a redeploy.
+
 ---
 
 ## 6. Descriptor reference
@@ -2308,6 +2321,8 @@ Worked examples to crib from:
 - [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook with outbound HTTP + `secretSettings` (admin-managed signing secret, Phase 6a).
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` route renderer.
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability; per-post Article JSON-LD. (Phase 4)
+- [`packages/plugin-reading-time`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-reading-time) — `publicHtmlForPost`; word-count estimate rendered as a `<p>` badge before/after the post body. (Phase 6d)
+- [`packages/plugin-ai-actions`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-ai-actions) — `publicHtmlForPost`; "View as Markdown" + opt-in "Open in Claude" / "Open in ChatGPT" links built from `ctx.site.url` (effective site settings) and the post's `/<slug>.md` URL. (AI-readable publishing roadmap, Phase B)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-beta.57",
+  "version": "1.0.0-beta.59",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",