@se-studio/contentful-cms 3.0.2 → 3.1.0

package/dist/staged-upload/store.d.ts

@@ -0,0 +1,19 @@
+import type { RedisClient } from '../session/session-store.js';
+import type { StagedUploadConsumeResult, StagedUploadRecord } from './types.js';
+export declare class StagedUploadStore {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(redis: RedisClient, keyPrefix?: string);
+    private fullKey;
+    assertRateLimit(userId: string): Promise<void>;
+    createPending(params: {
+        userId: string;
+        fileName: string;
+        mimeType: string;
+        byteLength?: number;
+    }): Promise<string>;
+    storeFile(userId: string, uploadId: string, buffer: Buffer, mimeType: string): Promise<StagedUploadRecord>;
+    consume(userId: string, uploadId: string): Promise<StagedUploadConsumeResult>;
+    getRecord(userId: string, uploadId: string): Promise<StagedUploadRecord | null>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/staged-upload/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/staged-upload/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAO/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0BhF,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,WAAW,EAClB,SAAS,SAAa;IAGzC,OAAO,CAAC,OAAO;IAIT,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C,aAAa,CAAC,MAAM,EAAE;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCb,SAAS,CACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC;IAgCxB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAuB7E,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAGtF"}

package/dist/staged-upload/store.js

@@ -0,0 +1,124 @@
+import * as crypto from 'node:crypto';
+import { assertUploadBufferSize } from '../contentful/upload-limits.js';
+import { hostedStagedMaxBytes, STAGED_UPLOAD_RATE_LIMIT_PER_HOUR, STAGED_UPLOAD_TTL_SECONDS, } from './limits.js';
+import { isAllowedStagedMimeType } from './mime.js';
+const KEY_PREFIX = 'cms-edit:staged:';
+const RATE_PREFIX = 'cms-edit:staged-rate:';
+function rateKey(userId, hourBucket) {
+    return `${RATE_PREFIX}${userId}:${String(hourBucket)}`;
+}
+function parseRecord(raw) {
+    if (!raw) {
+        return null;
+    }
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof raw === 'object') {
+        return raw;
+    }
+    return null;
+}
+export class StagedUploadStore {
+    redis;
+    keyPrefix;
+    constructor(redis, keyPrefix = KEY_PREFIX) {
+        this.redis = redis;
+        this.keyPrefix = keyPrefix;
+    }
+    fullKey(userId, uploadId) {
+        return `${this.keyPrefix}${userId}:${uploadId}`;
+    }
+    async assertRateLimit(userId) {
+        const hourBucket = Math.floor(Date.now() / (60 * 60 * 1000));
+        const key = rateKey(userId, hourBucket);
+        const count = await this.redis.incr(key);
+        if (count === 1) {
+            await this.redis.expire(key, 60 * 60);
+        }
+        if (count > STAGED_UPLOAD_RATE_LIMIT_PER_HOUR) {
+            throw new Error(`Staged upload rate limit exceeded (${String(STAGED_UPLOAD_RATE_LIMIT_PER_HOUR)} per hour).`);
+        }
+    }
+    async createPending(params) {
+        if (!isAllowedStagedMimeType(params.mimeType)) {
+            throw new Error(`MIME type not allowed for staged upload: ${params.mimeType}`);
+        }
+        if (params.byteLength !== undefined && params.byteLength > hostedStagedMaxBytes()) {
+            throw new Error(`Declared byteLength exceeds hosted staged upload limit (${String(hostedStagedMaxBytes())} bytes).`);
+        }
+        await this.assertRateLimit(params.userId);
+        const uploadId = crypto.randomUUID().replace(/-/g, '');
+        const record = {
+            uploadId,
+            userId: params.userId,
+            fileName: params.fileName,
+            mimeType: params.mimeType,
+            byteLength: params.byteLength,
+            status: 'pending',
+            createdAt: Date.now(),
+        };
+        const set = await this.redis.set(this.fullKey(params.userId, uploadId), JSON.stringify(record), {
+            ex: STAGED_UPLOAD_TTL_SECONDS,
+            nx: true,
+        });
+        if (set !== true) {
+            throw new Error('Failed to reserve staged upload slot.');
+        }
+        return uploadId;
+    }
+    async storeFile(userId, uploadId, buffer, mimeType) {
+        assertUploadBufferSize(buffer);
+        if (buffer.length > hostedStagedMaxBytes()) {
+            throw new Error(`File exceeds hosted staged upload limit (${String(hostedStagedMaxBytes())} bytes).`);
+        }
+        if (!isAllowedStagedMimeType(mimeType)) {
+            throw new Error(`MIME type not allowed for staged upload: ${mimeType}`);
+        }
+        const key = this.fullKey(userId, uploadId);
+        const existing = parseRecord(await this.redis.get(key));
+        if (!existing || existing.userId !== userId || existing.uploadId !== uploadId) {
+            throw new Error('Staged upload slot not found or expired.');
+        }
+        if (existing.status === 'ready') {
+            throw new Error('Staged upload already received.');
+        }
+        const record = {
+            ...existing,
+            status: 'ready',
+            mimeType,
+            byteLength: buffer.length,
+            dataBase64: buffer.toString('base64'),
+        };
+        await this.redis.set(key, JSON.stringify(record), { ex: STAGED_UPLOAD_TTL_SECONDS });
+        return record;
+    }
+    async consume(userId, uploadId) {
+        const key = this.fullKey(userId, uploadId);
+        const existing = parseRecord(await this.redis.get(key));
+        if (!existing || existing.userId !== userId || existing.uploadId !== uploadId) {
+            throw new Error('Staged upload not found or expired.');
+        }
+        if (existing.status !== 'ready' || !existing.dataBase64) {
+            throw new Error('Staged upload has no file data yet. POST the file to uploadUrl first.');
+        }
+        await this.redis.del(key);
+        const buffer = Buffer.from(existing.dataBase64, 'base64');
+        assertUploadBufferSize(buffer);
+        return {
+            buffer,
+            fileName: existing.fileName,
+            mimeType: existing.mimeType,
+            byteLength: buffer.length,
+        };
+    }
+    async getRecord(userId, uploadId) {
+        return parseRecord(await this.redis.get(this.fullKey(userId, uploadId)));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/staged-upload/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/staged-upload/store.ts"],"names":[],"mappings":"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"}

package/dist/staged-upload/types.d.ts

@@ -0,0 +1,27 @@
+export type StagedUploadStatus = 'pending' | 'ready';
+export interface StagedUploadRecord {
+    uploadId: string;
+    userId: string;
+    fileName: string;
+    mimeType: string;
+    byteLength?: number;
+    status: StagedUploadStatus;
+    dataBase64?: string;
+    createdAt: number;
+}
+export interface StagedUploadRequestResult {
+    uploadId: string;
+    uploadUrl: string;
+    expiresIn: number;
+    expiresAt: number;
+    maxBytes: number;
+    curlCommand: string;
+    consumeArgs: string[];
+}
+export interface StagedUploadConsumeResult {
+    buffer: Buffer;
+    fileName: string;
+    mimeType: string;
+    byteLength: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/staged-upload/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/staged-upload/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/staged-upload/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/staged-upload/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/staged-upload/types.ts"],"names":[],"mappings":""}

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

@@ -5,6 +5,7 @@
 - upload image
 - find existing asset
 - add photo to page or article
+- update person headshot / portrait
 
 ## Requires capabilities
 
@@ -13,6 +14,7 @@
 ## Prerequisites
 
 - **Always run `index sync` first** if the catalog may be stale
+- On **hosted MCP**, the server has **no filesystem** — use **staged upload**, `--base64`, or `--url` (never a local file path in `args`)
 
 ## Reuse-first workflow (default)
 
@@ -25,27 +27,78 @@
 
 ## Upload only when no match
 
+### Hosted MCP (default)
+
+**Prefer staged upload** for files larger than ~500 KB or when base64 in `cms_edit` args fails (agent harness message limits):
+
+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`)
+3. `cms_edit` with the returned `consumeArgs` (e.g. `["asset","upload","--staged","<uploadId>",…]`)
+
+Rules:
+
+- Staged upload keeps binary **out of MCP args** — only a short `uploadId` is passed to Contentful
+- Hosted limit: **4 MB** per file; TTL **15 minutes**; single-use
+- **PNG** when the source has transparency (portraits on brand-colour cards); JPEG flattens alpha
+- Upload alone does **not** attach the asset — follow with **link + save** (below)
+
+**Small files:** `--base64` with actual encoded bytes in `args` when the harness accepts the payload:
+
+```
+cms_edit ["asset", "upload", "--base64", "<encoded-bytes>", "--mime", "image/png", "--file-name", "icon.png", "--title", "…"]
+```
+
+Pass **raw base64 text** — not a filesystem path, not `file:///…`.
+
+**Last resort `--url`** only when staged upload and base64 are impractical:
+
 ```
-cms_edit ["asset", "upload", "./file.jpg", "--title", "…", "--if-exists-by-filename"]
+cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…"]
 ```
 
-Sources: `--url <https>` or `--base64` with `--mime` and `--file-name` (hosted MCP has no filesystem).
+The URL must be fetchable by the hosted MCP server (public HTTPS). Do not use local-only URLs or tunnel hacks unless the user explicitly approves.
 
-Optional Media wrapper:
+Optional Media wrapper (RTF embeds, not person `media`):
 
 ```
-cms_edit ["asset", "upload", "./figure.png", "--with-media", "--media-name", "Figure 1"]
+cms_edit ["asset", "upload", "--base64", "<encoded>", "--mime", "image/png", "--file-name", "figure.png", "--with-media", "--media-name", "Figure 1"]
 ```
 
+Use `--if-exists-by-filename` to avoid duplicate assets when re-running.
+
+### Local CLI (only when user approves)
+
+Local `cms-edit` may accept `--file` in some versions; hosted agents must not use local CLI without permission (see repo `Agents.md`).
+
+## Link uploaded asset to an entry
+
+Upload returns an **asset ID**. Attach it, then save:
+
+**Person portrait (`media` is an Asset link):**
+
+```
+cms_edit ["open", "--id", "<person-entry-id>"]
+cms_edit ["asset", "set", "@root", "media", "<new-asset-id>"]
+cms_edit ["diff"]
+cms_edit ["save"]
+```
+
+**Component visual / article featured image:** same pattern — `asset set <ref> <field> <asset-id>` (or `set … --asset`).
+
+Always `diff` → `save`. Verify with `preview urls` on the public path.
+
 ## Confirmation gates
 
 1. Report search results before uploading
 2. Confirm upload filename/title with user if ambiguous
+3. After upload, confirm `asset info <id>` shows expected width/height/size before linking
 
 ## Out of scope
 
 - Publish assets (draft upload; human publishes in Contentful UI if needed)
+- Deleting orphan assets from failed uploads (human cleanup in Contentful)
 
 ## Related resources
 
-- `cms-edit://customer/defaults` (featured image rules)
+- `cms-edit://customer/defaults` (featured image rules)
+- `cms-edit://customer/people` (person `media` field, when present)

package/docs/mcp/hosted-guide.md

@@ -20,6 +20,7 @@ All `save` operations create **drafts only**. A human must review and publish in
 | Tool | Purpose |
 |------|---------|
 | `cms_edit` | Run any cms-edit command via an `args` array |
+| `cms_edit_request_staged_upload` | Get a presigned upload URL for large files (then `curl` + `asset upload --staged`) |
 | `cms_edit_version` | Check the installed cms-edit version (no session required) |
 | `cms_edit_help` | Read this guide by topic (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) |
 
@@ -125,13 +126,42 @@ Always run `diff` before `save`. To abandon changes: `["discard"]`.
 
 | Task | Where |
 |------|-------|
-| Edit copy, add sections, create pages/articles | **Claude + cms-edit** (drafts) |
+| Edit copy, add sections, create pages/articles | **Agent + cms-edit** (drafts) |
+| Upload new images and files | **Agent + cms-edit** (`asset upload`) — search/reuse first |
 | Publish approved drafts | **Contentful UI** |
-| Upload new images and files | **Contentful UI** asset library |
-| Edit copy directly in Contentful | **Avoid** — use Claude instead |
+| Edit copy directly in Contentful | **Avoid** — use cms-edit instead |
 
 cms-edit saves **drafts only**. A colleague must **publish in Contentful** for changes to go live.
 
+## Asset upload (hosted MCP)
+
+Hosted connectors have **no server filesystem**. Use one source per upload:
+
+| Source | When | Example |
+|--------|------|---------|
+| **Staged upload** (preferred for files >~500 KB) | Agent harness cannot pass large base64 in `cms_edit` args | See **Staged upload** below |
+| **`--base64`** | Small files when inline base64 works | `["asset", "upload", "--base64", "<bytes>", "--mime", "image/png", "--file-name", "photo.png"]` |
+| **`--url`** (last resort) | Public HTTPS URL fetchable by the host | `["asset", "upload", "--url", "https://…/photo.png", "--mime", "image/png", "--file-name", "photo.png"]` |
+
+**Required with `--base64`:** `--mime`, `--file-name`. Pass **encoded bytes** in `args` — never a local path (`./file.png`, `file:///tmp/…`) or placeholder string.
+
+**After upload:** note the returned asset `id`, attach to the entry (`asset set @root media <id>` for person portraits), then `diff` → `save`. Upload alone does not update entries.
+
+**PNG** when transparency matters.
+
+Full workflow: `cms-edit://customer/task-media-reuse-and-upload`.
+
+### Staged upload (large files)
+
+Keeps bulk binary **out of MCP tool args**. The agent uploads via `curl`, then passes only a short `uploadId`.
+
+1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
+2. Run the returned `curlCommand` in a shell (POST multipart to `uploadUrl`)
+3. `cms_edit` with the returned `consumeArgs` (includes `asset upload --staged <uploadId>`)
+4. Link and save as usual
+
+Hosted limit: **4 MB** per staged file (Vercel body limit). TTL: **15 minutes**, single-use.
+
 ## Featured images (articles)
 
 Read `cms-edit://customer/defaults` when present. Otherwise:

package/package.json

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

package/skills/core/SKILL.md

@@ -369,11 +369,14 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Upload from local file, URL, or base64
+# Upload from local file, URL, base64, or staged ref (hosted MCP)
 cms-edit asset upload ./poster.jpg --title "Poster"
 cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
 cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
 
+# Hosted MCP — large files: cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
+# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+
 # Upload and create a Media wrapper in one step
 cms-edit asset upload ./figure.png --with-media --media-name "Figure 1" --media-position Middle