ampless 1.0.0-alpha.17 → 1.0.0-alpha.19

package/dist/index.d.ts

@@ -283,9 +283,11 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * declaration-vs-implementation reconciliation warnings and (in later
  * phases) for `allowCapabilities` gating in `cms.config.ts`.
  *
- * Phase 1 active capabilities:
+ * Active capabilities:
  *   - `publicHead` / `publicBody`: descriptor-based head/body injection.
  *   - `metadata` / `eventHooks`: name-only declaration for existing surfaces.
+ *   - `adminSettings`: admin-managed public settings manifest.
+ *   - `writePublicAsset`: trusted hook context can write namespaced public assets.
  *
  * Reserved capabilities are accepted by the type so that plugins can
  * declare future intent, but the runtime does nothing with them yet —
@@ -293,7 +295,7 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * capability today is harmless, but the runtime won't expose any new
  * surface for it until the matching phase ships.
  */
-type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'schema' | 'writePublicAsset' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
 /**
  * Loading strategy for `script` / `inlineScript` descriptors.
  *
@@ -314,13 +316,27 @@ type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks'
 type ScriptStrategy = 'afterInteractive' | 'lazyOnload';
 /**
  * Context passed to `publicHead` / `publicBodyEnd`. Phase 1 carries
- * only the site-wide config block; per-route and per-post context lands
- * in Phase 4 (`plugin-per-post-rfp.md`). Plugin settings are read from
- * the factory closure today — Phase 2 (`plugin-settings-rfp.md`) adds
- * an admin-managed accessor here.
+ * only the site-wide config block. Phase 2 adds the `setting()`
+ * accessor for admin-managed `settings.public` values; per-route /
+ * per-post context lands in Phase 4 (`plugin-per-post-rfp.md`).
  */
 interface PluginPublicRenderContext {
     site: Config['site'];
+    /**
+     * Resolve a public setting value for the active plugin instance.
+     * Returns `stored ?? manifest.default ?? undefined`. Stored values
+     * are read at request time from the DDB → S3 site-settings cache
+     * pipeline. Bound by the runtime when the plugin declares
+     * `settings.public` — plugins without a manifest can still call
+     * this, in which case it always returns `undefined`.
+     *
+     * The generic type is a convenience cast: the runtime does not
+     * coerce values, so callers should pick `T` to match the field's
+     * declared type (`text` → `string`, `number` → `number`, etc.).
+     * Validation at admin save time guarantees stored values match the
+     * field's declared shape, so the cast is safe in practice.
+     */
+    setting<T = unknown>(key: string): T | undefined;
 }
 /**
  * Descriptor returned by `publicHead()`. The runtime validates each
@@ -474,6 +490,95 @@ interface OgImageConfig {
      */
     render(ctx: OgImageRenderContext): Promise<unknown> | unknown;
 }
+/**
+ * Shared shape for every `PluginSettingField` variant. `T` is the
+ * decoded value type (string for text-like fields, number for number,
+ * boolean for boolean, etc.). All variants share `key` / `label` /
+ * `default` / `required`; type-specific constraints (e.g. `pattern`,
+ * `min`, `options`) live on the discriminated branches.
+ */
+interface PluginFieldBase<T> {
+    /**
+     * Storage key. Stored as `plugins.<instanceId>.<key>`. Must match
+     * `PLUGIN_KEY_PATTERN` (`/^[a-zA-Z0-9_-]+$/`) so the `pk.sk` dotted
+     * separator survives. Violations are skipped + warned by the
+     * runtime/admin normalization pass.
+     */
+    key: string;
+    label: LocalizedString;
+    description?: LocalizedString;
+    /** Used by the runtime when no admin-stored value is present. */
+    default?: T;
+    /**
+     * When true, an empty / undefined value is rejected at save time
+     * and the resolver returns `undefined`. When false (default),
+     * string-like fields accept empty string as a valid "disabled"
+     * value while non-string fields still reject empty strings.
+     */
+    required?: boolean;
+    /** Optional UI grouping (mirrors `ThemeField.group`). */
+    group?: LocalizedString;
+}
+interface PluginTextField extends PluginFieldBase<string> {
+    type: 'text';
+    maxLength?: number;
+    /** RegExp source (e.g. `'^G-[A-Z0-9]+$'`). Validated against
+     *  non-empty values; empty string skips the check. */
+    pattern?: string;
+    /** Placeholder for the admin input. */
+    placeholder?: string;
+}
+interface PluginTextareaField extends PluginFieldBase<string> {
+    type: 'textarea';
+    maxLength?: number;
+    placeholder?: string;
+    /** Rendered rows hint for the admin textarea. */
+    rows?: number;
+}
+interface PluginBooleanField extends PluginFieldBase<boolean> {
+    type: 'boolean';
+}
+interface PluginNumberField extends PluginFieldBase<number> {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface PluginSelectField extends PluginFieldBase<string> {
+    type: 'select';
+    options: ReadonlyArray<{
+        value: string;
+        label: LocalizedString;
+    }>;
+}
+interface PluginUrlField extends PluginFieldBase<string> {
+    type: 'url';
+    placeholder?: string;
+    /** When true, relative paths (`/foo`, `./foo`) pass validation; default true. */
+    allowRelative?: boolean;
+}
+interface PluginCodeField extends PluginFieldBase<string> {
+    type: 'code';
+    /** Display-only language label (e.g. `'js'`, `'css'`, `'html'`). */
+    language?: string;
+    maxLength?: number;
+    placeholder?: string;
+    rows?: number;
+}
+interface PluginJsonField extends PluginFieldBase<unknown> {
+    type: 'json';
+    placeholder?: string;
+    rows?: number;
+}
+type PluginSettingField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField | PluginCodeField | PluginJsonField;
+/**
+ * Per-plugin settings declaration. Phase 2 implements `public`;
+ * `secret` is reserved for Phase 6a (admin-only storage; never reaches
+ * the public runtime).
+ */
+interface PluginSettingsManifest {
+    public?: readonly PluginSettingField[];
+}
 interface AmplessPlugin {
     name: string;
     /** Plugin API version. Currently 1; future versions will be additive. */
@@ -501,6 +606,15 @@ interface AmplessPlugin {
      * continue to work unchanged.
      */
     capabilities?: readonly PluginCapability[];
+    /**
+     * Public, admin-editable settings (Phase 2). Each declared field is
+     * stored under `pk='siteconfig', sk='plugins.<instanceId>.<key>'`,
+     * mirrored to S3 via the trusted processor, and surfaced to
+     * `publicHead` / `publicBodyEnd` via `ctx.setting<T>(key)`. Plugins
+     * without an admin UI continue to work — they just don't have a
+     * `settings` block.
+     */
+    settings?: PluginSettingsManifest;
     /** Async event hooks. Run in trust_level-matched Lambda. */
     hooks?: {
         [K in EventType]?: PluginEventHandler<K>;
@@ -914,6 +1028,62 @@ declare function decodeAwsJson(value: unknown): unknown;
  */
 declare function formatPublicAssetUrl(bucket: string, region: string, key: string): string;
 
+/**
+ * Validate the user-supplied key for ctx.writePublicAsset.
+ *
+ * The trusted Lambda still has a processor-wide S3 grant, so path safety is
+ * enforced at the runtime context boundary before the key is joined under the
+ * plugin namespace.
+ */
+declare function validatePublicAssetKey(key: string): string | null;
+
+declare const PLUGIN_KEY_PATTERN: RegExp;
+declare function isValidPluginKey(key: string): boolean;
+/**
+ * Validate one raw value against a field definition. Returns the
+ * (possibly-coerced) value on success, or `null` to signal rejection.
+ *
+ * Semantics:
+ *   - **string-like fields** (text / textarea / url / code) accept
+ *     `''` as valid when `required` is falsy. This is the "disable"
+ *     sentinel — e.g. `pattern: '^$|^G-...'` lets a GA4 plugin save
+ *     an empty measurementId to suppress the loader without dropping
+ *     the row.
+ *   - **non-string-like fields** (number / boolean / json / select)
+ *     always reject `''`. Allowing it would force callers to handle a
+ *     `string` reading where `number | undefined` is declared. To
+ *     "unset" these fields, delete the row (admin form's "Reset to
+ *     default" button).
+ *   - `undefined` is treated as "not set" by `resolvePluginSettings`
+ *     — `validatePluginSettingValue` itself returns `null` for it.
+ *   - Constraints (`pattern`, `min`, `max`, `maxLength`, `options`) run
+ *     only when the value is present and non-empty.
+ *
+ * The returned shape preserves the declared type — `text` stores a
+ * sanitized string, `number` stores a `number`, `boolean` stores a
+ * `boolean`, `json` stores the decoded value (object / array /
+ * primitive — never the source string), etc.
+ */
+declare function validatePluginSettingValue(field: PluginSettingField, raw: unknown): unknown | null;
+/**
+ * Merge stored values on top of manifest defaults for one plugin
+ * instance. Both sides are validated through `validatePluginSettingValue`
+ * — stored values that fail validation (manual DDB tampering, schema
+ * drift) fall back to the validated default; defaults that themselves
+ * fail validation surface as `undefined`.
+ *
+ * `stored` is a flat key → value map keyed by the field's `key` (not
+ * the full DDB SK). The runtime extracts it from the site-settings
+ * snapshot using the `plugins.<instanceId>.` prefix.
+ *
+ * Validation runs on the default too because the default can come
+ * from a plugin's constructor argument (e.g. GA4 takes a
+ * `measurementId` option and passes it through as the field's
+ * `default`). If the operator supplies a bogus value at install time
+ * we'd rather surface `undefined` than render garbage.
+ */
+declare function resolvePluginSettings(manifest: PluginSettingsManifest | undefined, stored: Record<string, unknown>): Record<string, unknown>;
+
 /**
  * Extract the first image URL from a post body. Used by plugins (e.g.
  * plugin-og-image) that want to derive an image from the post content
@@ -1019,4 +1189,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, type Page, type PluginCapability, type PluginEventHandler, type PluginMetadata, type PluginPublicRenderContext, type PluginRuntimeContext, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, 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 TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, 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 PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPublicRenderContext, type PluginRuntimeContext, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, 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 TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, 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

@@ -215,6 +215,132 @@ function definePlugin(p) {
   return p;
 }
 
+// src/plugin-asset-key.ts
+function validatePublicAssetKey(key) {
+  if (key.length === 0) return "key must not be empty";
+  if (key.length > 256) return "key must be 256 characters or less";
+  if (key.startsWith("/")) return 'key must be relative and must not start with "/"';
+  if (key.includes("\\")) return "key must not contain backslashes";
+  if (/[\u0000-\u001f\u007f]/.test(key)) {
+    return "key must not contain control characters";
+  }
+  const segments = key.split("/");
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return 'key must not contain "." or ".." path segments';
+  }
+  return null;
+}
+
+// src/plugin-settings.ts
+var PLUGIN_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function isValidPluginKey(key) {
+  return typeof key === "string" && PLUGIN_KEY_PATTERN.test(key);
+}
+function validatePluginSettingValue(field, raw) {
+  if (raw === void 0) return null;
+  switch (field.type) {
+    case "text":
+    case "textarea":
+    case "code": {
+      if (typeof raw !== "string") return null;
+      const sanitized = raw.replace(/[\x00-\x1f<>]/g, "");
+      if (sanitized === "") {
+        return field.required ? null : "";
+      }
+      const maxLength = field.type === "text" && field.maxLength || field.type === "textarea" && field.maxLength || field.type === "code" && field.maxLength || void 0;
+      if (typeof maxLength === "number" && sanitized.length > maxLength) {
+        return null;
+      }
+      if (field.type === "text" && field.pattern) {
+        let re;
+        try {
+          re = new RegExp(field.pattern);
+        } catch {
+          return null;
+        }
+        if (!re.test(sanitized)) return null;
+      }
+      return sanitized;
+    }
+    case "url": {
+      if (typeof raw !== "string") return null;
+      const trimmed = raw.trim();
+      if (trimmed === "") {
+        return field.required ? null : "";
+      }
+      if (/^\s*(javascript|vbscript|data|blob|file):/i.test(trimmed)) {
+        return null;
+      }
+      const allowRelative = field.allowRelative !== false;
+      const schemeMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+      if (schemeMatch) {
+        const scheme = schemeMatch[1].toLowerCase();
+        if (scheme !== "http" && scheme !== "https") return null;
+      } else if (!allowRelative) {
+        return null;
+      }
+      return trimmed;
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") return raw;
+      if (raw === "true" || raw === 1) return true;
+      if (raw === "false" || raw === 0) return false;
+      return null;
+    }
+    case "number": {
+      if (typeof raw === "number") {
+        if (Number.isNaN(raw)) return null;
+      } else if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (trimmed === "") return null;
+        const n2 = Number(trimmed);
+        if (Number.isNaN(n2)) return null;
+        raw = n2;
+      } else {
+        return null;
+      }
+      const n = raw;
+      if (typeof field.min === "number" && n < field.min) return null;
+      if (typeof field.max === "number" && n > field.max) return null;
+      return n;
+    }
+    case "select": {
+      if (typeof raw !== "string") return null;
+      if (raw === "") return null;
+      if (!field.options.some((opt) => opt.value === raw)) return null;
+      return raw;
+    }
+    case "json": {
+      if (raw === "") return null;
+      if (typeof raw === "string") return null;
+      return raw;
+    }
+  }
+}
+function resolvePluginSettings(manifest, stored) {
+  const out = {};
+  const fields = manifest?.public;
+  if (!fields) return out;
+  for (const field of fields) {
+    if (!isValidPluginKey(field.key)) {
+      continue;
+    }
+    let resolved = void 0;
+    if (Object.prototype.hasOwnProperty.call(stored, field.key)) {
+      const validated = validatePluginSettingValue(field, stored[field.key]);
+      if (validated !== null) resolved = validated;
+    }
+    if (resolved === void 0 && field.default !== void 0) {
+      const validatedDefault = validatePluginSettingValue(field, field.default);
+      if (validatedDefault !== null) resolved = validatedDefault;
+    }
+    if (resolved !== void 0) {
+      out[field.key] = resolved;
+    }
+  }
+  return out;
+}
+
 // src/post-images.ts
 function extractFirstImageUrl(post) {
   switch (post.format) {
@@ -560,6 +686,7 @@ var VERSION = "0.0.1";
 export {
   DEFAULT_ENTRYPOINT,
   MAX_BUNDLE_BYTES,
+  PLUGIN_KEY_PATTERN,
   SITE_CONFIG_PK,
   TEXT_EXTENSIONS,
   VERSION,
@@ -589,6 +716,7 @@ export {
   hasKvStore,
   hasPostsProvider,
   isTagListUrl,
+  isValidPluginKey,
   listPosts,
   listSiteSettings,
   mimeTypeFor,
@@ -596,6 +724,7 @@ export {
   parseLinkList,
   pickDefaultEntrypoint,
   resolveLocalized,
+  resolvePluginSettings,
   resolveThemeValues,
   setKvStore,
   setPostsProvider,
@@ -607,5 +736,7 @@ export {
   updatePost,
   validateBundle,
   validateBundlePath,
+  validatePluginSettingValue,
+  validatePublicAssetKey,
   validateThemeValue
 };