@se-studio/contentful-cms 3.2.1 → 3.3.0

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

@@ -1,8 +1,8 @@
 # Capability: Media pipeline — prepare pack
 
-Normalize a **folder of designer masters** (or inline files) into short-lived **public HTTPS URLs** under cms-edit upload limits, then import into Contentful with reuse-first.
+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 this service to write Contentful. Pipeline → ready URLs only. **cms-edit** owns assets/entries.
+**Never** expect the media pipeline service to write Contentful. Pipeline → ready URLs only. **cms-edit** owns assets/entries.
 
 ## Intent phrases
 
@@ -19,13 +19,14 @@ Normalize a **folder of designer masters** (or inline files) into short-lived **
 
 ## Prerequisites
 
-- Media pipeline base URL (ops default for SE Studio: `https://se-media-pipeline.vercel.app`)
-- API bearer key (ops secret — e.g. env `MEDIA_PIPELINE_API_KEY` or site runbook; never invent)
-- Tenant id: `se` | `om1` | … (explicit; never infer only from Drive URL)
-- Drive folder **shared Viewer** with pipeline service account  
+- 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-only mode)
-- Profile default: `case-study-v1` (images ≤ ~3.5MB, videos H.264 mp4 ≤ ~8MB)
+  (or “anyone with the link” if using API-key Drive mode on the pipeline)
+- Profile default: `case-study-v1`
 
 ## When to use
 
@@ -35,94 +36,89 @@ Normalize a **folder of designer masters** (or inline files) into short-lived **
 | Single small image already in library | `task-media-reuse-and-upload` only |
 | Masters already under limits and catalogued | Reuse search only |
 
-## Steps
+## Steps (agent — single auth)
 
-### 1. Confirm job inputs
+### 1. Prepare
 
-1. Tenant (`se`, `om1`, …)
-2. Profile (`case-study-v1` unless overridden)
-3. Source:
-   - **Preferred:** `google_drive_folder` + folder URL  
-   - **Dev/test:** `inline_files` with base64 (small files only)
-4. Optional: `ttlHours` (1–24, default 24), `namingPrefix` (defaults from tenant)
-
-### 2. Start the pack job
-
-```http
-POST {MEDIA_PIPELINE_BASE}/api/v1/jobs
-Authorization: Bearer {MEDIA_PIPELINE_API_KEY}
-Content-Type: application/json
+Call MCP tool **`cms_edit_media`**:
 
+```json
 {
-  "tenant": "se",
-  "profile": "case-study-v1",
-  "source": {
-    "type": "google_drive_folder",
-    "url": "https://drive.google.com/drive/folders/…"
-  },
-  "options": { "ttlHours": 24 }
+  "action": "prepare",
+  "driveFolderUrl": "https://drive.google.com/drive/folders/…",
+  "profile": "case-study-v1"
 }
 ```
 
-Expect **202** with `jobId`, `runId`, `statusUrl` / poll path.
+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>" }
+```
 
-### 3. Poll until terminal
+or
 
-```http
-GET {MEDIA_PIPELINE_BASE}/api/v1/jobs/{jobId}?tenant={tenant}
-Authorization: Bearer {MEDIA_PIPELINE_API_KEY}
+```json
+{ "action": "status", "jobId": "<jobId>" }
 ```
 
 Statuses: `queued` → `running` → `succeeded` | `partial` | `failed`.
 
 - **succeeded** — all files ready  
-- **partial** — some ready; `gaps[]` lists failures (e.g. quality floor)  
+- **partial** — some ready; `gaps[]` lists failures  
 - **failed** — nothing usable; stop and report gaps  
 
-**Do not** invent assets for gaps. Carry gaps into source-readiness / GO-WITH-GAPS.
+**Do not** invent assets for gaps.
 
-### 4. Map pack → Contentful (reuse-first)
-
-For **each** ready asset in `assets[]`:
-
-1. `cms_edit ["index", "sync"]` once per session if catalog may be stale  
-2. Search: `asset search` / `--filename-match` using `fileName` or source stem  
-3. If no match: **prefer URL upload** (ready URLs are already under limits):
+### 3. Catalog
 
+```json
+{ "action": "catalog", "jobId": "<jobId>" }
 ```
-cms_edit ["asset", "upload", "--url", "<assets[i].url>", "--mime", "<mime>", "--file-name", "<fileName>", "--title", "<titleDraft>", "--if-exists-by-filename"]
-```
 
-Hosted MCP: `--url` is preferred for pipeline packs. Staged upload only if URL fetch fails (then download is unnecessary — pipeline already normalized).
+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. Set alt / description from `altDraft` when the site workflow requires it (`asset set` / asset fields per site)  
-5. Create **Media** wrappers only when needed; **reuse** existing Media entries by asset id  
-6. Record map: `sourceName` → `{ assetId, mediaId?, readyUrl }` for the article/page build  
+### 4. Import into Contentful (reuse-first)
 
-### 5. Hand off to structure build
+After drafting titles/alts from **previewUrl** / **posterUrl**:
 
-Return to:
+```json
+{
+  "action": "import",
+  "jobId": "<jobId>",
+  "withMedia": true,
+  "overrides": [
+    { "sourceName": "OM1_Hero.jpg", "title": "OM1 hero", "alt": "…" }
+  ]
+}
+```
 
-- `task-create-from-document` / `task-create-article` / customer case-study task  
-- Soft-proof component order with **real** asset/media ids in the plan  
+Optional: `"dryRun": true` to preview the map without writing.
 
-## Confirmation gates
+CLI: `cms-edit media import --job <id> [--dry-run] [--with-media] [--overrides-json '[…]']`
 
-1. Report pipeline `status` + asset count + `gaps` before CMS uploads  
-2. Report reuse hits vs new uploads  
-3. Do not start multi-block article create until the pack map is complete (or gaps accepted as GO-WITH-GAPS)
+Import:
 
-## Out of scope
+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  
 
-- Contentful publish  
-- Copy rewrite  
-- Pipeline writing CMA (forbidden permanently)  
-- Video/image creative edits beyond normalize  
+Manual `asset upload --url` remains available for one-offs.
 
-## Related resources
+### Hardening notes (for agents)
 
-- `task-media-reuse-and-upload`
-- `task-source-readiness-review`
-- `task-create-from-document`
-- `task-create-article`
-- `task-preview-verify`
+- 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/package.json

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