@se-studio/contentful-cms 3.2.0 → 3.3.0

package/dist/media-pipeline/validate.js

@@ -0,0 +1,38 @@
+import { MEDIA_TTL_HOURS_MAX, MEDIA_TTL_HOURS_MIN } from './limits.js';
+const DRIVE_FOLDER_RE = /^https:\/\/drive\.google\.com\/drive\/(?:u\/\d+\/)?folders\/([a-zA-Z0-9_-]+)(?:[/?#].*)?$/;
+export function parseDriveFolderUrl(url) {
+    const trimmed = url.trim();
+    const match = DRIVE_FOLDER_RE.exec(trimmed);
+    if (!match) {
+        return {
+            ok: false,
+            error: 'driveFolderUrl must be a Google Drive folder URL (https://drive.google.com/drive/folders/…).',
+        };
+    }
+    return {
+        ok: true,
+        folderId: match[1],
+        url: `https://drive.google.com/drive/folders/${match[1]}`,
+    };
+}
+export function clampTtlHours(value, defaultTtl) {
+    const raw = value ?? defaultTtl;
+    if (!Number.isFinite(raw)) {
+        return defaultTtl;
+    }
+    return Math.min(MEDIA_TTL_HOURS_MAX, Math.max(MEDIA_TTL_HOURS_MIN, Math.floor(raw)));
+}
+export function assertAllowedProfile(profile, allowed) {
+    if (!allowed.includes(profile)) {
+        return {
+            ok: false,
+            error: `Profile "${profile}" is not allowed on this host. Allowed: ${allowed.join(', ')}`,
+        };
+    }
+    return { ok: true };
+}
+/** Job ids from media-pipeline are URL-safe tokens; keep validation loose but bounded. */
+export function isPlausibleJobId(jobId) {
+    return /^[a-zA-Z0-9_-]{8,128}$/.test(jobId.trim());
+}
+//# sourceMappingURL=validate.js.map

package/dist/media-pipeline/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/media-pipeline/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,eAAe,GACnB,2FAA2F,CAAC;AAE9F,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAM7C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EACH,8FAA8F;SACjG,CAAC;IACJ,CAAC;IACD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAE;QACnB,GAAG,EAAE,0CAA0C,KAAK,CAAC,CAAC,CAAE,EAAE;KAC3D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAyB,EAAE,UAAkB;IACzE,MAAM,GAAG,GAAG,KAAK,IAAI,UAAU,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAiB;IAEjB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,YAAY,OAAO,2CAA2C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC1F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC"}

package/dist/runtime/context.d.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { CmsEditConfig } from '../config/types.js';
 import type { IndexCacheStore } from '../index/cache-store.js';
+import type { MediaPipelineJobStore } from '../media-pipeline/job-store.js';
 import type { SessionStore } from '../session/session-store.js';
 import type { StagedUploadStore } from '../staged-upload/store.js';
 export interface ContentfulUserIdentity {
@@ -18,6 +19,10 @@ export interface CmsEditRuntimeContext {
     user?: ContentfulUserIdentity;
     /** Staged file uploads for hosted asset upload (Redis). */
     stagedUploadStore?: StagedUploadStore;
+    /** Media pipeline job ownership + rate limits (Redis on hosted). */
+    mediaPipelineJobStore?: MediaPipelineJobStore;
+    /** Hosted project key (e.g. se2026) for media job bindings / logs. */
+    projectKey?: string;
 }
 export declare const cmsEditContext: AsyncLocalStorage<CmsEditRuntimeContext>;
 export declare function getRuntimeContext(): CmsEditRuntimeContext | undefined;

package/dist/runtime/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,qEAAqE;IACrE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gEAAgE;IAChE,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,eAAO,MAAM,cAAc,0CAAiD,CAAC;AAE7E,wBAAgB,iBAAiB,IAAI,qBAAqB,GAAG,SAAS,CAErE;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,qBAAqB,EAC9B,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhB"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,qEAAqE;IACrE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gEAAgE;IAChE,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,0CAAiD,CAAC;AAE7E,wBAAgB,iBAAiB,IAAI,qBAAqB,GAAG,SAAS,CAErE;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,qBAAqB,EAC9B,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhB"}

package/dist/runtime/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAwBrD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,iBAAiB,EAAyB,CAAC;AAE7E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAA8B,EAC9B,EAAwB;IAExB,OAAO,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA6BrD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,iBAAiB,EAAyB,CAAC;AAE7E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAA8B,EAC9B,EAAwB;IAExB,OAAO,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/docs/editor-tasks/create-from-document.md

@@ -27,14 +27,21 @@
 3. On **NO-GO**, stop. On **GO** / **GO-WITH-GAPS**, keep the soft-proof as the build plan.
 4. **Do not rewrite source copy.** Structure and place only.
 
-### Phase 1 — Plan and create
+### Phase 1 — Media pack (when the package has Drive/binary masters)
+
+1. If the package includes a **folder of images/videos** (typical case study): run **`task-media-pipeline-prepare`** **before** building blocks.
+2. Prefer pipeline **ready public URLs** + reuse-first import over mid-build staged upload of oversized masters.
+3. Keep the `sourceName → assetId` map for Phase 2 field linking.
+4. Skip this phase only when every needed visual is already in the Contentful library (confirmed via `asset search`).
+
+### Phase 2 — Plan and create
 
 1. Read `cms-edit://customer/tasks-index` and relevant playbooks (`articles` / `pages`).
 2. Map soft-proof beats to **registered** component types only — prefer **source order** over CMS convenience (do not invent side-by-side pairs unless the source is a true pair).
-3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list, gap/placeholder list — **ask user to confirm** with a light **yes** if not already confirmed.
+3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list, gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed.
 4. For pages: `list --type template` — pick template; check template `preContent` / `postContent` so heroes are not duplicated.
 5. For articles: resolve `articleType`; apply site SEO and lab rules from `articles` playbook.
-6. Build `create from-json` payload **or** prefer incremental `open` → `add` / `set` / `rtf` for large multi-block work.
+6. Build `create from-json` payload **or** prefer incremental `open` → `add` / `set` / `rtf` for large multi-block work. Link visuals using the pack map from Phase 1.
 7. `cms_edit ["create", "from-json", "--json", "<compact-json>", "--dry-run", "--strict"]` when using JSON (or `--json-base64` for large payloads).
 8. On approval, create and `save`.
 9. `cms_edit ["preview", "urls", "<slug>"]` — follow **`task-preview-verify`** (including multi-block soft-proof QA when relevant).
@@ -54,6 +61,7 @@ Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc`
 - Publish
 - **Rewriting source copy** (flag only)
 - Asset upload without reuse check (see **Media** capability)
+- Mid-article ffmpeg / Drive size thrash — use **`task-media-pipeline-prepare`** first
 - Inventing layout, section titles, or pair collections absent from the source
 
 ## Related resources
@@ -61,6 +69,7 @@ Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc`
 - `cms-edit://customer/components-index`
 - `cms-edit://customer/articles` / `pages`
 - `task-source-readiness-review`
+- `task-media-pipeline-prepare`
 - `task-create-article`
 - `task-create-page`
 - `task-media-reuse-and-upload`

package/docs/editor-tasks/media-pipeline-prepare.md

@@ -0,0 +1,124 @@
+# Capability: Media pipeline — prepare pack
+
+Normalize a **folder of designer masters** into short-lived **public HTTPS URLs** under cms-edit upload limits, then import into Contentful with reuse-first.
+
+**Never** expect the media pipeline service to write Contentful. Pipeline → ready URLs only. **cms-edit** owns assets/entries.
+
+## Intent phrases
+
+- process media folder
+- prepare Drive assets for CMS
+- media pipeline pack
+- normalize oversized images/videos
+- process case study assets
+- upload from media pipeline
+
+## Requires capabilities
+
+`assetSearch` and `assetUpload`
+
+## Prerequisites
+
+- Hosted cms-edit with media pipeline **configured on the host** (ops env):
+  - `MEDIA_PIPELINE_BASE_URL`
+  - `MEDIA_PIPELINE_SERVICE_KEY` (server-only — **never ask the agent/user for this**)
+  - `MEDIA_PIPELINE_TENANT` (e.g. `se`, not the cms-edit projectKey)
+- Drive folder shared **Viewer** with pipeline service account  
+  `media-pipeline-reader@se-media-pipeline.iam.gserviceaccount.com`  
+  (or “anyone with the link” if using API-key Drive mode on the pipeline)
+- Profile default: `case-study-v1`
+
+## When to use
+
+| Situation | Action |
+|-----------|--------|
+| Drive/Figma package with large JPEGs/videos | **This task first**, then structure build |
+| Single small image already in library | `task-media-reuse-and-upload` only |
+| Masters already under limits and catalogued | Reuse search only |
+
+## Steps (agent — single auth)
+
+### 1. Prepare
+
+Call MCP tool **`cms_edit_media`**:
+
+```json
+{
+  "action": "prepare",
+  "driveFolderUrl": "https://drive.google.com/drive/folders/…",
+  "profile": "case-study-v1"
+}
+```
+
+CLI: `cms-edit media prepare --drive-folder "https://drive.google.com/drive/folders/…"`
+
+Expect `{ ok: true, jobId, status: "queued", pollHint }`.
+
+If `{ ok: false, code: "pipeline_unconfigured" }` → host ops must set env vars. **Do not** ask the user for a pipeline API key.
+
+### 2. Wait / status
+
+```json
+{ "action": "wait", "jobId": "<jobId>" }
+```
+
+or
+
+```json
+{ "action": "status", "jobId": "<jobId>" }
+```
+
+Statuses: `queued` → `running` → `succeeded` | `partial` | `failed`.
+
+- **succeeded** — all files ready  
+- **partial** — some ready; `gaps[]` lists failures  
+- **failed** — nothing usable; stop and report gaps  
+
+**Do not** invent assets for gaps.
+
+### 3. Catalog
+
+```json
+{ "action": "catalog", "jobId": "<jobId>" }
+```
+
+Each asset includes:
+
+| Field | Use |
+|-------|-----|
+| `readyUrl` | `asset upload --url` into Contentful |
+| `previewUrl` / `posterUrl` | Agent vision for **title / fileName / alt** (when present) |
+| `altDraft` / `titleDraft` | Filename seeds only — improve before save |
+
+### 4. Import into Contentful (reuse-first)
+
+After drafting titles/alts from **previewUrl** / **posterUrl**:
+
+```json
+{
+  "action": "import",
+  "jobId": "<jobId>",
+  "withMedia": true,
+  "overrides": [
+    { "sourceName": "OM1_Hero.jpg", "title": "OM1 hero", "alt": "…" }
+  ]
+}
+```
+
+Optional: `"dryRun": true` to preview the map without writing.
+
+CLI: `cms-edit media import --job <id> [--dry-run] [--with-media] [--overrides-json '[…]']`
+
+Import:
+
+1. Searches existing assets by fileName  
+2. Else uploads from `readyUrl` as the authenticated Contentful user  
+3. Returns `map: { sourceName → { assetId, mediaId?, … } }` for page build  
+
+Manual `asset upload --url` remains available for one-offs.
+
+### Hardening notes (for agents)
+
+- Jobs are **owned by the OAuth user** who prepared them — you cannot poll another user’s `jobId`.  
+- Rate limits apply (prepares/hour, concurrent jobs).  
+- Never document or request `MEDIA_PIPELINE_API_KEY` in chat.

package/docs/editor-tasks/media-reuse-and-upload.md

@@ -28,9 +28,16 @@
 
 ## Upload only when no match
 
+### Oversized masters / whole Drive folders
+
+If files are near or over **4 MB** (hosted staged) or **10 MB** (URL/local), or the user shared a **Drive folder of masters**, do **not** improvise compression in chat.
+
+1. Run **`task-media-pipeline-prepare`** (Drive folder → ready public URLs under limits)
+2. Return here and import with **`--url`** + reuse-first filename search
+
 ### Hosted MCP (default)
 
-**Always use staged upload** for images and other binary files. Do not pass base64 in `cms_edit` args — hosted MCP rejects `asset upload --base64`.
+**Always use staged upload** for ad-hoc small binaries. Do not pass base64 in `cms_edit` args — hosted MCP rejects `asset upload --base64`.
 
 1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
 2. Run the returned `curlCommand` in a shell (POST file to `uploadUrl`)
@@ -57,10 +64,10 @@ To rename an existing Media wrapper: `cms_edit ["batch", "set", "<media-entry-id
 
 Avoid `asset upload --with-media` when multiple entries will share the same image (e.g. news composites) — it creates duplicate Media entries. Upload the asset only, then one shared `create media`, then link the media ID on each entry.
 
-**Last resort `--url`** only when the file is already on public HTTPS and staged upload is impractical:
+**Prefer `--url`** when the file is already on **public HTTPS** under size limits — especially **media-pipeline ready pack URLs**:
 
 ```
-cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…"]
+cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…", "--if-exists-by-filename"]
 ```
 
 The URL must be fetchable by the hosted MCP server. Do not use local-only URLs.
@@ -99,5 +106,7 @@ Always `diff` → `save`. Verify with `preview urls` on the public path.
 
 ## Related resources
 
+- `task-media-pipeline-prepare`
+
 - `cms-edit://customer/defaults` (featured image rules)
 - `cms-edit://customer/people` (person `media` field, when present)

package/docs/editor-tasks/source-readiness-review.md

@@ -111,5 +111,6 @@ Copy: unchanged from source (list any human decisions only)
 - `task-create-from-document`
 - `task-create-article`
 - `task-create-page`
+- `task-media-pipeline-prepare`
 - `task-media-reuse-and-upload`
 - `task-preview-verify`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",