@ampless/backend 1.0.0-alpha.19 → 1.0.0-alpha.21

package/dist/functions/mcp-handler.d.ts

@@ -1,10 +1,10 @@
 /**
- * MCP HTTP endpoint Lambda. Phase 5: Bearer validation + JSON-RPC 2.0
- * tool dispatch over AppSync IAM auth, including `upload_media`.
+ * MCP HTTP endpoint Lambda. Bearer validation + JSON-RPC 2.0 tool
+ * dispatch over AppSync IAM auth, including `upload_media`.
  *
  *   1. Reads KvStore directly (PK = 'mcp-tokens', SK = SHA-256 hex)
- *      to validate `Authorization: Bearer amk_...`. Same narrow IAM
- *      grant as Phase 3 (`dynamodb:GetItem` on the KvStore table).
+ *      to validate `Authorization: Bearer amk_...`. The Lambda has a
+ *      narrow IAM grant: `dynamodb:GetItem` on the KvStore table.
  *   2. Parses the incoming JSON-RPC envelope by hand (no MCP SDK
  *      stdio transport in a Lambda runtime — overkill for the three
  *      verbs we actually need).

package/dist/functions/mcp-handler.js

@@ -6,7 +6,7 @@ import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";
 import { createHash } from "crypto";
 import { decodeAwsJson as decodeAwsJson2 } from "ampless";
 
-// ../mcp-server/dist/chunk-DAR6AHSX.js
+// ../mcp-server/dist/chunk-K4GTND6P.js
 import {
   decodeAwsJson
 } from "ampless";
@@ -278,11 +278,17 @@ var createPostSchema = {
     tags: { type: "array", items: { type: "string" } },
     metadata: {
       type: "object",
-      description: "Free-form per-post metadata. Reserved well-known keys: `no_layout` (boolean) \u2014 when true, the public page is served as bare HTML with no theme chrome (the route redirects to /_/<slug>); meaningful only with format=html. Other keys pass through unchanged for themes/plugins.",
+      description: "Free-form per-post metadata. Reserved well-known keys: `no_layout` (boolean) \u2014 when true, the public page is served as bare HTML with no theme chrome (middleware rewrites /<slug> to the internal bare-HTML route); meaningful only with format=html. `cache` (auto|deep|hot) \u2014 override the per-post cache strategy. See `cacheStrategy` in get_schema.notes for details. Other keys pass through unchanged for themes/plugins.",
       properties: {
         no_layout: {
           type: "boolean",
           description: "Serve the post as bare HTML with no theme chrome. Only meaningful when format=html; ignored otherwise."
+        },
+        cache: {
+          type: "string",
+          enum: ["auto", "deep", "hot"],
+          default: "auto",
+          description: "Override the response Cache-Control strategy. 'auto' (default): no-store within `cms.config.cache.cooldownMs` of updatedAt, then `max-age=freshTtlSeconds`. 'deep': always `max-age=deepTtlSeconds`. 'hot': always no-store. Independent of no_layout; applies uniformly to themed, no_layout, and static posts."
         }
       },
       additionalProperties: true
@@ -341,11 +347,17 @@ var updatePostSchema = {
     tags: { type: "array", items: { type: "string" } },
     metadata: {
       type: "object",
-      description: "Free-form per-post metadata. Reserved well-known keys: `no_layout` (boolean) \u2014 when true, the public page is served as bare HTML with no theme chrome (the route redirects to /_/<slug>); meaningful only with format=html. Passing metadata replaces the existing metadata object \u2014 read the current post first if you only want to add a key.",
+      description: "Free-form per-post metadata. Reserved well-known keys: `no_layout` (boolean) \u2014 when true, the public page is served as bare HTML with no theme chrome (middleware rewrites /<slug> to the internal bare-HTML route); meaningful only with format=html. `cache` (auto|deep|hot) \u2014 override the per-post cache strategy. See `cacheStrategy` in get_schema.notes for details. Passing metadata replaces the existing metadata object \u2014 read the current post first if you only want to add a key.",
       properties: {
         no_layout: {
           type: "boolean",
           description: "Serve the post as bare HTML with no theme chrome. Only meaningful when format=html; ignored otherwise."
+        },
+        cache: {
+          type: "string",
+          enum: ["auto", "deep", "hot"],
+          default: "auto",
+          description: "Override the response Cache-Control strategy. 'auto' (default): no-store within `cms.config.cache.cooldownMs` of updatedAt, then `max-age=freshTtlSeconds`. 'deep': always `max-age=deepTtlSeconds`. 'hot': always no-store. Independent of no_layout; applies uniformly to themed, no_layout, and static posts."
         }
       },
       additionalProperties: true
@@ -473,7 +485,7 @@ function getSchema() {
           tags: { type: "string[]" },
           metadata: {
             type: "json",
-            description: "Free-form per-post key/value bag. Reserved well-known keys (owned by ampless): `no_layout` (boolean). Other keys pass through unchanged for themes/plugins."
+            description: "Free-form per-post key/value bag. Reserved well-known keys (owned by ampless): `no_layout` (boolean), `cache` (auto|deep|hot). Other keys pass through unchanged for themes/plugins."
           }
         }
       },
@@ -506,8 +518,9 @@ function getSchema() {
     notes: {
       editorTrust: 'editor stores arbitrary HTML/JS verbatim \u2014 same trust shape as WordPress unfiltered_html capability. See docs/architecture/04-access-layer-mcp.md \xA7"editor \u306E\u4FE1\u983C\u30E2\u30C7\u30EB".',
       tiptapBody: 'When format=tiptap, body is the tiptap document JSON: { type: "doc", content: [...] }. The renderer expects this shape.',
-      noLayout: "metadata.no_layout=true serves the post as bare HTML with no theme chrome \u2014 the public route at /<slug> 308-redirects to /_/<slug>, and that route renders the body verbatim with no wrapping <html>/<head>/layout. Use this for landing pages, embeds, or any post whose body is a full HTML document. Only meaningful with format=html (the other formats need the theme renderer).",
-      staticFormat: "A fourth format value `static` exists on the underlying data model for posts whose body is a JSON manifest pointing to a pre-uploaded HTML/CSS/JS bundle in S3 at public/static/<slug>/. Public URL pattern: /_/<slug>/ for the entrypoint and /_/<slug>/<file> for every bundle file (308 redirect from /<slug> via the post dispatcher). Static posts are created/edited through the dedicated tools `upload_static_bundle` (zip in one shot), `upload_static_file` / `delete_static_file` (incremental per-file ops), and `commit_static_post` (rebuild the manifest from the current S3 prefix). `create_post` / `update_post` intentionally do NOT accept format=static \u2014 the bundle tools are the only supported entry point so the Post manifest stays in sync with the S3 prefix."
+      noLayout: "metadata.no_layout=true serves the post as bare HTML with no theme chrome \u2014 middleware rewrites the public /<slug> request to the internal bare-HTML handler, which renders the body verbatim with no wrapping <html>/<head>/layout. Use this for landing pages, embeds, or any post whose body is a full HTML document. Only meaningful with format=html (the other formats need the theme renderer).",
+      staticFormat: "A fourth format value `static` exists on the underlying data model for posts whose body is a JSON manifest pointing to a pre-uploaded HTML/CSS/JS bundle in S3 at public/static/<slug>/. Public URL pattern: /<slug>/ for the entrypoint and /<slug>/<file> for every bundle file (middleware rewrites both to an internal static-bundle handler). Static posts are created/edited through the dedicated tools `upload_static_bundle` (zip in one shot), `upload_static_file` / `delete_static_file` (incremental per-file ops), and `commit_static_post` (rebuild the manifest from the current S3 prefix). `create_post` / `update_post` intentionally do NOT accept format=static \u2014 the bundle tools are the only supported entry point so the Post manifest stays in sync with the S3 prefix.",
+      cacheStrategy: "metadata.cache controls the response Cache-Control header (set by middleware). Values:\n  - 'auto' (default): cooldown by edit time. Posts updated within cms.config.cache.cooldownMs (default 1h) emit `public, max-age=0, must-revalidate, s-maxage=0` so editors see fresh content immediately; older posts emit `public, max-age=<freshTtlSeconds>, s-maxage=<freshTtlSeconds>` (default 300 sec / 5 min).\n  - 'deep': always `public, max-age=<deepTtlSeconds>, s-maxage=<deepTtlSeconds>` (default 3600 sec / 1 hour). Use for posts whose content is fixed for the foreseeable future.\n  - 'hot': always `public, max-age=0, must-revalidate, s-maxage=0`. Use for rapidly-evolving posts or posts whose body is computed per request.\nIndependent of metadata.no_layout and post.format \u2014 applies uniformly to themed, no_layout, and static posts. Override the defaults per project via `cms.config.cache` ({ cooldownMs, freshTtlSeconds, deepTtlSeconds })."
     }
   };
 }
@@ -834,7 +847,7 @@ var tools = [
   },
   {
     name: "create_post",
-    description: "Create a new post. Title and slug are required. Body shape depends on format: tiptap=JSON node tree, markdown=source string, html=raw HTML string. Defaults to status=draft. Pass `metadata: { no_layout: true }` alongside format=html to publish the body as a bare HTML page with no theme chrome (the public route redirects to /_/<slug>).",
+    description: 'Create a new post. Title and slug are required. Body shape depends on format: tiptap=JSON node tree, markdown=source string, html=raw HTML string. Defaults to status=draft. Pass `metadata: { no_layout: true }` alongside format=html to publish the body as a bare HTML page with no theme chrome (middleware rewrites the /<slug> request to the internal bare-HTML handler). Pass `metadata: { cache: "deep" | "hot" }` to override the default cooldown-based cache strategy \u2014 see get_schema.notes.cacheStrategy for details.',
     inputSchema: createPostSchema,
     handler: (args, ctx) => createPost(ctx.graphql, args)
   },

package/dist/index.d.ts

@@ -18,10 +18,8 @@ interface DefineAmplessBackendOpts {
 }
 type AmplessBackend = any;
 /**
- * The end-to-end ampless backend wiring: identical to the 251-line
- * `backend.ts` that used to live in `templates/_shared/amplify/`,
- * but parameterised on the resource objects so users only have to
- * compose the imports.
+ * The end-to-end ampless backend wiring, parameterised on the resource
+ * objects so users only have to compose the imports.
  *
  * What it does, in order:
  *   1. Calls `defineBackend` with every Ampless resource.
@@ -201,8 +199,8 @@ interface AmplessSchemaAuthorizationOpts {
      * destructure `resource` out of their `allow` parameter), so this
      * grant applies broadly — every model the Lambda calls is reachable.
      * That's wider than strictly necessary; the MCP tools' GraphQL
-     * operations narrow the effective surface to Post / PostTag in
-     * Phase 4 and Media in Phase 5.
+     * operations narrow the effective surface to Post / PostTag for
+     * content tools and Media for `upload_media`.
      *
      * Typed as `unknown` for the same reason `userAdminFunction` /
      * `mcpHandlerFunction` are in other helpers — `defineFunction`'s

package/dist/index.js

@@ -364,6 +364,12 @@ function amplessSchemaModels(a, opts = {}) {
     ]),
     // Custom return type for public post reads. Decoupling from `Post` lets
     // AppSync skip the model-level (admin-only) auth check on fields.
+    //
+    // `updatedAt` is projected through so middleware can compute the
+    // `metadata.cache='auto'` cooldown without re-fetching the model
+    // row. It's an Amplify-managed DynamoDB attribute (set on every
+    // write); the JS resolvers pass items through verbatim so the
+    // value naturally appears here once the schema declares it.
     PublicPost: a.customType({
       postId: a.id().required(),
       slug: a.string().required(),
@@ -374,7 +380,8 @@ function amplessSchemaModels(a, opts = {}) {
       status: a.string(),
       publishedAt: a.datetime(),
       tags: a.string().array(),
-      metadata: a.json()
+      metadata: a.json(),
+      updatedAt: a.datetime()
     }),
     // Paginated wrapper for list responses.
     PublicPostConnection: a.customType({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/backend",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.21",
   "description": "Amplify Gen 2 backend factories for ampless: auth, data, storage, event processors, API key renewer",
   "license": "MIT",
   "type": "module",
@@ -65,8 +65,8 @@
     "@smithy/protocol-http": "^5.3.0",
     "@smithy/signature-v4": "^5.4.0",
     "fflate": "^0.8.2",
-    "ampless": "1.0.0-alpha.9",
-    "@ampless/mcp-server": "1.0.0-alpha.10"
+    "ampless": "1.0.0-alpha.11",
+    "@ampless/mcp-server": "1.0.0-alpha.12"
   },
   "peerDependencies": {
     "@aws-amplify/backend": "^1",