@se-studio/contentful-cms 3.3.0 → 3.4.0

package/dist/output/print.js

@@ -22,10 +22,10 @@ export function typeLabel(label) {
 export function entryLabel(label) {
     return pc.white(`"${truncate(label, 40)}"`);
 }
-/** Emits an error. In JSON mode: {"ok":false,"error":"..."} to stderr. */
-export function errorMsg(msg) {
+/** Emits an error. In JSON mode: {"ok":false,"error":"..."} to stderr. Optional extra fields are merged in JSON mode. */
+export function errorMsg(msg, extra) {
     if (isJsonMode()) {
-        console.error(JSON.stringify({ ok: false, error: msg }));
+        console.error(JSON.stringify({ ok: false, error: msg, ...extra }));
     }
     else {
         console.error(pc.red(`Error: ${msg}`));

package/dist/output/print.js.map

@@ -1 +1 @@
-{"version":3,"file":"print.js","sourceRoot":"","sources":["../../src/output/print.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,WAAW;YACd,OAAO,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5B,KAAK,SAAS;YACZ,OAAO,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAChC,KAAK,SAAS;YACZ,OAAO,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,OAAO,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../src/output/print.ts"],"names":[],"mappings":"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"}

package/dist/session/dirty.d.ts

@@ -0,0 +1,20 @@
+import type { SessionState } from './state.js';
+/** True when the session has staged field edits or pending deletions. */
+export declare function isSessionDirty(session: SessionState): boolean;
+export interface DirtyOpenErrorPayload {
+    code: 'SESSION_DIRTY';
+    unsavedChanges: number;
+    pendingDeletions: number;
+    rootEntryId: string;
+    rootEntryType: string;
+    actions: string[];
+}
+export interface DirtyOpenError {
+    message: string;
+    payload: DirtyOpenErrorPayload;
+}
+/**
+ * Agent-facing hard-fail when `open` would replace a session that still has local work.
+ */
+export declare function formatDirtyOpenError(session: SessionState): DirtyOpenError;
+//# sourceMappingURL=dirty.d.ts.map

package/dist/session/dirty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty.d.ts","sourceRoot":"","sources":["../../src/session/dirty.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CAsC1E"}

package/dist/session/dirty.js

@@ -0,0 +1,44 @@
+/** True when the session has staged field edits or pending deletions. */
+export function isSessionDirty(session) {
+    return session.modifiedEntryIds.length > 0 || session.pendingDeletions.length > 0;
+}
+/**
+ * Agent-facing hard-fail when `open` would replace a session that still has local work.
+ */
+export function formatDirtyOpenError(session) {
+    const unsavedChanges = session.modifiedEntryIds.length;
+    const pendingDeletions = session.pendingDeletions.length;
+    const rootEntryId = session.rootEntryId;
+    const rootEntryType = session.rootEntryType;
+    const actions = [
+        'cms-edit open --resume',
+        'cms-edit diff',
+        'cms-edit save',
+        'cms-edit discard',
+        'cms-edit open --overwrite --id <entryId>',
+    ];
+    const message = [
+        `Cannot open: session has ${unsavedChanges} unsaved entry change(s) and ${pendingDeletions} pending deletion(s).`,
+        `Root: ${rootEntryId} (${rootEntryType}) — continue this work, or explicitly abandon it.`,
+        '',
+        '  Continue current work:  cms-edit open --resume',
+        '  Review changes:         cms-edit diff',
+        '  Save drafts:            cms-edit save',
+        '  Abandon all staged:     cms-edit discard',
+        '  Abandon and open new:   cms-edit open --overwrite --id <entryId>',
+        '',
+        'Do not re-run open without --overwrite while changes are staged — that previously wiped session field edits.',
+    ].join('\n');
+    return {
+        message,
+        payload: {
+            code: 'SESSION_DIRTY',
+            unsavedChanges,
+            pendingDeletions,
+            rootEntryId,
+            rootEntryType,
+            actions,
+        },
+    };
+}
+//# sourceMappingURL=dirty.js.map

package/dist/session/dirty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty.js","sourceRoot":"","sources":["../../src/session/dirty.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,OAAqB;IAClD,OAAO,OAAO,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC;AACpF,CAAC;AAgBD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,MAAM,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC;IACvD,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC;IACzD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACxC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAE5C,MAAM,OAAO,GAAG;QACd,wBAAwB;QACxB,eAAe;QACf,eAAe;QACf,kBAAkB;QAClB,0CAA0C;KAC3C,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,4BAA4B,cAAc,gCAAgC,gBAAgB,uBAAuB;QACjH,SAAS,WAAW,KAAK,aAAa,mDAAmD;QACzF,EAAE;QACF,kDAAkD;QAClD,yCAAyC;QACzC,yCAAyC;QACzC,4CAA4C;QAC5C,oEAAoE;QACpE,EAAE;QACF,8GAA8G;KAC/G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO;QACL,OAAO;QACP,OAAO,EAAE;YACP,IAAI,EAAE,eAAe;YACrB,cAAc;YACd,gBAAgB;YAChB,WAAW;YACX,aAAa;YACb,OAAO;SACR;KACF,CAAC;AACJ,CAAC"}

package/docs/help/batch.md

@@ -1,8 +1,22 @@
 # Batch edit by entry ID
 
-Edit multiple unrelated Contentful entries without opening a page tree. Useful for link variant sweeps, navigation item tweaks, and other standalone entry updates.
+Edit multiple Contentful entries by ID with scalar field updates. Useful for link variant sweeps, media flags (`autoplay`/`loop`), navigation tweaks, and other standalone updates.
 
-Batch commands use session name **`batch`** by default (override with `--session`). Page sessions from `cms-edit open` are not affected.
+## Sessions
+
+| Context | What happens |
+|---------|----------------|
+| Default CLI (`--session` omitted) | Uses session name **`batch`** (does not touch a separate page session) |
+| Page session already open (e.g. MCP `_mcp`) | `batch set` **stages into that page session** — same `diff` / `save` as article work. Do **not** re-`open`. Do **not** `batch discard` (use `cms-edit discard` only if abandoning everything). |
+| Explicit isolation | `cms-edit --session link-sweep batch set …` |
+
+You can also stay on the page session without `batch`:
+
+```bash
+cms-edit set <entryId>:autoplay=true <entryId>:loop=true
+# or
+cms-edit set <entryId> autoplay true
+```
 
 ## Workflow
 
@@ -16,17 +30,25 @@ cms-edit batch diff
 # Write all changes as drafts (single save)
 cms-edit batch save
 
-# Or discard without saving
+# Or discard without saving (pure batch sessions only)
 cms-edit batch discard
 ```
 
+Mid-page (MCP / open article session):
+
+```bash
+cms-edit batch set 5uMh54rIsJRFRQSXDuJiG:autoplay=true
+cms-edit diff
+cms-edit save
+```
+
 ## Token format
 
 ```
 <entryId>:<fieldId>=<value>
 ```
 
-- **entryId** — 22-character Contentful entry ID (no `@` prefix)
+- **entryId** — Contentful entry ID (alphanumeric, optional `_`/`-`, length 1–64; **not** fixed at 22 characters)
 - **fieldId** — field name on that entry's content type
 - **value** — literal token (no shell quotes needed for simple strings). Coercion follows the field type from Contentful:
   - **Symbol** / **Text** — always stored as strings (e.g. `order=42` stays `"42"`)
@@ -39,6 +61,7 @@ Examples:
 
 ```bash
 cms-edit batch set abcdefghijklmnopqrstuv:variant=link
+cms-edit batch set 5uMh54rIsJRFRQSXDuJiG:autoplay=true
 cms-edit batch set abcdefghijklmnopqrstuv:cmsLabel=Footer CTA
 ```
 
@@ -60,7 +83,7 @@ When a page is already open, prefer `cms-edit links set @cN <index> variant link
 
 Field types and enum validations are loaded from the Contentful Management API. Results are cached:
 
-- In the **batch session file** (`contentTypes` on the session) so `batch set` → `batch save` reuse schema without extra API calls
+- In the **session file** (`contentTypes` on the session) so `batch set` → save reuse schema without extra API calls
 - On disk at `~/.contentful-cms/content-types/<spaceId>/<environment>/` (24-hour TTL)
 
 ## v1 limits
@@ -68,11 +91,4 @@ Field types and enum validations are loaded from the Contentful Management API.
 - **Scalar fields only** — no rich text, entry links, asset links, or link arrays
 - **Draft-only** — same as `cms-edit save`; never publishes
 - **No cross-entry link arrays** — use page session + `cms-edit set --links` for parent arrays
-- **Partial save on failure** — if one entry fails during `batch save`, earlier entries may already be saved; the CLI lists failures and reminds you to run `cms-edit batch diff` for remaining changes
-
-## Named sessions
-
-```bash
-cms-edit --session link-sweep batch set idOne123456789012345678:variant=link
-cms-edit --session link-sweep batch save
-```
+- **Partial save on failure** — if one entry fails during `batch save`, earlier entries may already be saved; the CLI lists failures and reminds you to run diff for remaining changes

package/docs/help/index.md

@@ -84,6 +84,10 @@ cms-edit batch run --json '[...]'
 | Command | Description |
 |---|---|
 | `open --page-slug <slug>` | Load a page into the session (see `help lookup`) |
+| `open --resume` | Re-print active session; **keeps** staged edits (no refetch) |
+| `open --overwrite …` | Replace session even if dirty (discards staged field edits) |
+| `set <ref\|id> <field> <value>` | Set field; bare entry IDs allowed mid-session |
+| `set <id>:field=value …` | Scalar multi-set by entry ID (stays on current session) |
 | `open --id <id>` | Load by Contentful entry ID |
 | `peek --page-slug <slug>` | Print content tree + root field values without creating a session |
 | `peek --id <id>` | Same by Contentful entry ID |
@@ -137,7 +141,7 @@ cms-edit batch run --json '[...]'
 ### Batch Operations
 | Command | Description |
 |---|---|
-| `batch set <entryId>:field=value …` | Queue scalar updates on multiple entries by ID |
+| `batch set <entryId>:field=value …` | Queue scalar updates by ID (page session OK mid-edit; then `save`) |
 | `batch diff` / `batch save` / `batch discard` | Review and commit batch session |
 | `batch run --json <json> or --json-base64 <encoded>` | Execute a JSON batch of operations |
 

package/docs/help/workflow.md

@@ -26,6 +26,25 @@ cms-edit open --id 4xKpzQ2abc123
 
 `open` fetches the full entry tree and saves it to a local session file. All subsequent commands operate on this session without re-fetching from Contentful until you `save`.
 
+### Critical: do not re-open while edits are staged
+
+`set` / `rtf` / parent links from `add` stay in the session until `save`. Calling `open` again **replaces** the session.
+
+| Situation | Command |
+|-----------|---------|
+| Session has unsaved changes, need tree again | `cms-edit open --resume` (no refetch; keeps staged edits) |
+| Intentionally abandon staged work and load another entry | `cms-edit open --overwrite --id <id>` (or `discard` then `open`) |
+| Plain `open` while dirty | **Hard fail** with remediation steps |
+
+```bash
+cms-edit open --resume
+cms-edit diff
+cms-edit save
+# or abandon:
+cms-edit discard
+cms-edit open --id <other>
+```
+
 **Output:**
 ```
 ✓ Opened /solutions/hepatology (12 entries)
@@ -72,6 +91,34 @@ cms-edit set @c2 heading "New Heading"
 cms-edit set @c2 backgroundColour "Navy"
 ```
 
+### Mid-session by Contentful entry ID (e.g. media autoplay)
+
+You do **not** need to leave the page session:
+
+```bash
+# Bare entry ID (fetched into the session if not in the tree)
+cms-edit set 5uMh54rIsJRFRQSXDuJiG autoplay true
+
+# Same shape as batch set — stays on the current page session
+cms-edit set 5uMh54rIsJRFRQSXDuJiG:autoplay=true 5uMh54rIsJRFRQSXDuJiG:loop=true
+# or: cms-edit batch set … (also allowed mid-page; then cms-edit save)
+```
+
+### Entry links: `--link` vs `--links` (strict)
+
+| Field shape | Flag | Notes |
+|-------------|------|--------|
+| Single Entry link | `--link` | Exactly one id |
+| Array of Entry links | `--links` | Full replace of the array |
+| Append to array | `--links --append` | Add ids |
+| Wrong flag | hard error | Never silently coerces |
+
+```bash
+cms-edit set @c1 visual <mediaEntryId> --link
+cms-edit set @c2 contents <id1>,<id2> --links
+# To change one array item: read the array, edit the list, write all ids back with --links
+```
+
 ### Rich text fields
 ```bash
 # Inline markdown (short content)

package/package.json

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