makaron-cli 0.13.9 → 0.14.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.0",
   "description": "Give Claude Code a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.0",
   "description": "Give Codex a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/README.md

@@ -170,26 +170,37 @@ npx makaron-cli project media <projectId> --json
 
 This is project-scoped. `responses get <runId> --pick output` only returns artifacts from one run; `project media` returns the whole project timeline: original uploads, references, generated images, video snapshots, and editable compositions.
 
-External source ranges can be added without uploading either the original video or a derivative clip:
+Typed external images and video ranges can be added without uploading the original media:
 
 ```bash
 npx makaron-cli project media add <projectId> \
+  --type image \
+  --source-url "https://cdn.example.com/product.jpg" \
+  --description "Hero product image"
+
+npx makaron-cli project media add <projectId> \
+  --type video \
   --source-url "https://cdn.example.com/source.mp4" \
   --start 12.5 --end 19 \
   --description "Racket frame molding"
 
 # Batch form: a JSON array or {"clips": [...]}
-npx makaron-cli project media add <projectId> --input ranges.json --json
+npx makaron-cli project media add <projectId> --input media.json --json
 ```
 
-The returned `<<<media_N>>>` is immediately usable by a later Agent run. Its range remains non-destructive metadata; Remotion must trim the original URL to these exact source bounds.
+Every item must declare `type` as `image` or `video`. Images contain
+`source_url + type + description` and do not have a time range. Videos contain
+`source_url + type + start + end + description`; their ranges remain
+non-destructive metadata, and Remotion must trim the original URL to those exact
+source bounds. The returned `<<<media_N>>>` is immediately usable by a later
+Agent run.
 Use `description` as the provider-neutral media-understanding field. Put any
 already-known summary, editorial purpose, concrete scene evidence, confidence,
 and limitations there. Makaron exposes the full description in Media List
 context so the Agent can edit from it without repeating image/video analysis
 unless a required detail is missing or uncertain.
 
-For an agent-to-agent handoff, create the project, import the external ranges,
+For an agent-to-agent handoff, create the project, import the typed external media,
 and start the Agent in one command:
 
 ```bash
@@ -200,9 +211,9 @@ npx makaron-cli chat --project auto \
 ```
 
 The manifest is a JSON array or `{ "title": "...", "clips": [...] }`. Every
-clip contains exactly `source_url`, `start`, `end`, and `description`; the time
-values are seconds and array order is edit order. It is validated before project
-creation and supports up to 20 clips for one Makaron task. Batch planning remains
+item declares `type`. Images omit `start` and `end`; videos require both values
+in seconds. Array order is edit order. It is validated before project creation
+and supports up to 20 media items for one Makaron task. Batch planning remains
 the upstream orchestrator's responsibility: convert each plan into one manifest
 and start one independent Makaron task.
 
@@ -341,9 +352,12 @@ npx makaron-cli edit --image photo.jpg --ref style.jpg "match this style"
 
 # Output to file
 npx makaron-cli edit --image photo.jpg --out result.jpg "make it dramatic"
+
+# Strict transparent PNG/WebP output through GPT Image 2 (fails rather than returning opaque)
+npx makaron-cli edit --image-model openai --background transparent --out sticker.png "a magenta star sticker"
 ```
 
-Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--background auto|opaque|transparent`, `--out <path>`. Transparent output routes strictly to GPT Image 2 and is returned only when the provider supplies real PNG/WebP alpha.
 
 ### `video` — Standalone video tools (no project timeline)
 

package/bin/makaron.mjs

@@ -174,25 +174,19 @@ function readJsonInput(filePath) {
   return JSON.parse(raw);
 }
 
-const MAX_MEDIA_MANIFEST_RANGES = 20;
+const MAX_MEDIA_MANIFEST_ITEMS = 20;
 
 function normalizeMediaManifest(input) {
   const manifest = Array.isArray(input) ? { clips: input } : input;
   if (!manifest || typeof manifest !== 'object') {
-    throw new Error('Media manifest must be a JSON object or an array of source ranges.');
-  }
-  const rawRanges = Array.isArray(manifest.clips)
-    ? manifest.clips
-    : Array.isArray(manifest.source_ranges)
-      ? manifest.source_ranges
-      : Array.isArray(manifest.sourceRanges)
-        ? manifest.sourceRanges
-        : null;
+    throw new Error('Media manifest must be a JSON object or an array of media items.');
+  }
+  const rawRanges = Array.isArray(manifest.clips) ? manifest.clips : null;
   if (!rawRanges?.length) {
     throw new Error('Media manifest must contain a non-empty clips array.');
   }
-  if (rawRanges.length > MAX_MEDIA_MANIFEST_RANGES) {
-    throw new Error(`Media manifest supports at most ${MAX_MEDIA_MANIFEST_RANGES} source ranges per Makaron task.`);
+  if (rawRanges.length > MAX_MEDIA_MANIFEST_ITEMS) {
+    throw new Error(`Media manifest supports at most ${MAX_MEDIA_MANIFEST_ITEMS} media items per Makaron task.`);
   }
 
   const sourceRanges = rawRanges.map((raw, index) => {
@@ -207,8 +201,19 @@ function normalizeMediaManifest(input) {
     if (!['http:', 'https:'].includes(parsed.protocol)) {
       throw new Error(`clips[${index}].source_url must use HTTP or HTTPS.`);
     }
-    const start = Number(raw.start ?? raw.start_sec);
-    const end = Number(raw.end ?? raw.end_sec);
+    const declaredType = raw.type;
+    if (declaredType !== 'image' && declaredType !== 'video') {
+      throw new Error(`clips[${index}].type must be image or video.`);
+    }
+    const description = typeof raw.description === 'string' ? raw.description.trim() : '';
+    if (declaredType === 'image') {
+      if (raw.start !== undefined || raw.end !== undefined || raw.start_sec !== undefined || raw.end_sec !== undefined) {
+        throw new Error(`clips[${index}] image items must not include start or end.`);
+      }
+      return { source_url: sourceUrl, type: 'image', description };
+    }
+    const start = Number(raw.start);
+    const end = Number(raw.end);
     if (!Number.isFinite(start) || start < 0) {
       throw new Error(`clips[${index}].start must be a finite number >= 0.`);
     }
@@ -217,9 +222,10 @@ function normalizeMediaManifest(input) {
     }
     return {
       source_url: sourceUrl,
+      type: declaredType,
       start,
       end,
-      description: typeof raw.description === 'string' ? raw.description.trim() : '',
+      description,
     };
   });
 
@@ -447,7 +453,7 @@ Options:
   --image <file|url>        Attach a reference image or screenshot. Repeatable.
   --video <file|url>        Attach a video to the project timeline. Repeatable.
   --audio <file|url>        Attach a song, beat, or voice reference. MP3/WAV, repeatable.
-  --media-manifest <file|-> Import source_url + start + end + description clips before this run.
+  --media-manifest <file|-> Import typed image/video media before this run.
   --skill <id|label|name>   Use an installed skill or auto-install a matched marketplace skill.
   --agent-model <id>        Agent LLM only: auto, gpt-5.6-terra, gpt-5.6-sol,
                             gpt-5.6-luna, grok-4.5, or deepseek-v4-pro.
@@ -1031,7 +1037,10 @@ async function addProjectMediaSourceRanges(baseUrl, headers, projectId, ranges,
   }
   if (!opts.silent) {
     for (const item of data.media || []) {
-      console.log(`${item.ref} ${item.source_url} ${formatSeconds(item.start_sec)}-${formatSeconds(item.end_sec)}s${item.created ? '' : ' (existing)'}`);
+      const range = item.type === 'video' && Number.isFinite(item.start_sec) && Number.isFinite(item.end_sec)
+        ? ` ${formatSeconds(item.start_sec)}-${formatSeconds(item.end_sec)}s`
+        : '';
+      console.log(`${item.ref} [${item.type || 'media'}] ${item.source_url}${range}${item.created ? '' : ' (existing)'}`);
     }
   }
   return data;
@@ -1787,7 +1796,22 @@ function saveMcpImage(result, outputPath) {
   const imageBlock = content.find(c => c.type === 'image');
   if (textBlock) process.stderr.write(`${textBlock.text}\n`);
   if (imageBlock) {
-    const out = outputPath || `makaron-output-${Date.now()}.jpg`;
+    const extension = imageBlock.mimeType === 'image/png'
+      ? 'png'
+      : imageBlock.mimeType === 'image/webp'
+        ? 'webp'
+        : 'jpg';
+    let out = outputPath || `makaron-output-${Date.now()}.${extension}`;
+    if (outputPath) {
+      const requestedExtension = path.extname(outputPath).slice(1).toLowerCase();
+      const compatible = extension === 'jpg'
+        ? ['jpg', 'jpeg'].includes(requestedExtension)
+        : requestedExtension === extension;
+      if (!compatible) {
+        out = `${outputPath.slice(0, outputPath.length - path.extname(outputPath).length)}.${extension}`;
+        process.stderr.write(`Output is ${imageBlock.mimeType}; saving as ${out} so bytes and filename agree.\n`);
+      }
+    }
     fs.writeFileSync(out, Buffer.from(imageBlock.data, 'base64'));
     console.log(out);
     return out;
@@ -1838,8 +1862,10 @@ Commands:
   credits                            Show current credit balance
   list (ls)                          List all projects
   project media <projectId> --json    List timeline media for a project
-  project media add <projectId> --source-url <url> --start <n> --end <n>
-                                     Add an external source range without uploading video
+  project media add <projectId> --type image --source-url <url>
+                                     Add an external image without uploading it
+  project media add <projectId> --type video --source-url <url> --start <n> --end <n>
+                                     Add an external video range without uploading it
   create --image <file>              Create project from local image
   create --image-url <url>           Create project from URL
   create --title "name"              Create empty project (text-to-image)
@@ -1851,7 +1877,7 @@ Commands:
   chat --project <id> --video <file> Attach video to conversation
   chat --project <id> --audio <file> Attach song/beat/voice reference
   chat --project auto --media-manifest <file> "message"
-                                     Create, import external ranges, and run Agent
+                                     Create, import typed external media, and run Agent
   chat --project <id> -b "message"   Background: submit and print runId
   chat --project <id> --stream "msg" Legacy: stream SSE in real-time
   chat --project <id> --json "msg"   Output structured JSON result
@@ -1961,11 +1987,12 @@ function printHelp(topic, subtopic) {
     console.log('Usage: makaron credits [--json]');
   } else if (topic === 'project' || topic === 'projects') {
     if (subtopic === 'media') console.log(`Usage: makaron project media <projectId> [--json]
-  makaron project media add <projectId> --source-url <url> --start <n> --end <n> [--description <text>] [--json]
-  makaron project media add <projectId> --input <ranges.json> [--json]`);
+  makaron project media add <projectId> --type image --source-url <url> [--description <text>] [--json]
+  makaron project media add <projectId> --type video --source-url <url> --start <n> --end <n> [--description <text>] [--json]
+  makaron project media add <projectId> --input <media.json> [--json]`);
     else console.log(`Project commands:
   project media <projectId> --json      List timeline media for a project
-  project media add <projectId> ...     Add external source_url + start + end media
+  project media add <projectId> ...     Add typed external image/video media
 `);
   } else if (topic === 'abort') {
     console.log('Usage: makaron abort <runId>');
@@ -2005,7 +2032,7 @@ Not sure which built-in skill to use? Start with:
   composition status <jobId> [--wait] [--json]
 `);
   } else if (topic === 'edit') {
-    console.log('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--skill enhance|creative|wild|captions] [--ref <file>] [--out <file>] "prompt"');
+    console.log('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--skill enhance|creative|wild|captions] [--ref <file>] [--aspect <ratio>] [--background auto|opaque|transparent] [--out <file>] "prompt"');
   } else if (topic === 'analyze') {
     console.log('Usage: makaron analyze --video <file|url> ["question"]');
   } else if (topic === 'video') {
@@ -2269,12 +2296,12 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     );
     importedManifestMedia = imported.media || [];
     if (importedManifestMedia.length !== mediaManifest.sourceRanges.length) {
-      process.stderr.write(`❌ Imported ${importedManifestMedia.length}/${mediaManifest.sourceRanges.length} source range(s); aborting run.\n`);
+      process.stderr.write(`❌ Imported ${importedManifestMedia.length}/${mediaManifest.sourceRanges.length} media item(s); aborting run.\n`);
       process.exit(1);
     }
     uploadedTurnMediaCount += importedManifestMedia.length;
-    uploadedTurnVideoCount += importedManifestMedia.length;
-    process.stderr.write(`📎 Imported ${importedManifestMedia.length} external source range(s) from media manifest\n`);
+    uploadedTurnVideoCount += importedManifestMedia.filter(item => item.type === 'video').length;
+    process.stderr.write(`📎 Imported ${importedManifestMedia.length} typed external media item(s) from media manifest\n`);
   }
   // Upload additional images to existing project
   if (imageFileList.length > 0 || imageUrlList.length > 0) {
@@ -2432,9 +2459,12 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
           ...(importedManifestMedia.length ? {
             importedMedia: importedManifestMedia.map(item => ({
               ref: item.ref,
+              type: item.type,
               source_url: item.source_url,
-              start_sec: item.start_sec,
-              end_sec: item.end_sec,
+              ...(item.type === 'video' ? {
+                start_sec: item.start_sec,
+                end_sec: item.end_sec,
+              } : {}),
             })),
           } : {}),
         }));
@@ -2699,7 +2729,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     const jsonOutput = args.includes('--json');
     if (args[2] === 'add') {
       const projectId = args[3];
-      if (!projectId) { console.error('Usage: makaron project media add <projectId> --source-url <url> --start <n> --end <n>'); process.exit(1); }
+      if (!projectId) { console.error('Usage: makaron project media add <projectId> --type <image|video> --source-url <url> [--start <n> --end <n>]'); process.exit(1); }
       const readOption = (name) => {
         const index = args.indexOf(name);
         return index >= 0 ? args[index + 1] : undefined;
@@ -2707,26 +2737,25 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       const inputPath = readOption('--input');
       let ranges;
       if (inputPath) {
-        const input = readJsonInput(inputPath);
-        ranges = Array.isArray(input) ? input : input.clips || input.source_ranges || input.sourceRanges;
+        const normalized = normalizeMediaManifest(readJsonInput(inputPath));
+        ranges = normalized.sourceRanges;
       } else {
         const sourceUrl = readOption('--source-url');
-        const start = Number(readOption('--start') ?? readOption('--start-sec'));
-        const end = Number(readOption('--end') ?? readOption('--end-sec'));
-        if (!sourceUrl || !Number.isFinite(start) || !Number.isFinite(end)) {
-          console.error('Provide --source-url, --start, and --end, or --input <manifest.json>.');
+        const type = readOption('--type');
+        const start = readOption('--start');
+        const end = readOption('--end');
+        if (!sourceUrl || (type !== 'image' && type !== 'video')) {
+          console.error('Provide --type <image|video> and --source-url <url>, or --input <manifest.json>.');
           process.exit(1);
         }
-        ranges = [{
+        const normalized = normalizeMediaManifest([{
           source_url: sourceUrl,
-          start,
-          end,
+          type,
+          ...(start !== undefined ? { start } : {}),
+          ...(end !== undefined ? { end } : {}),
           ...(readOption('--description') ? { description: readOption('--description') } : {}),
-        }];
-      }
-      if (!Array.isArray(ranges) || !ranges.length) {
-        console.error('Input must contain a non-empty clips array.');
-        process.exit(1);
+        }]);
+        ranges = normalized.sourceRanges;
       }
       await addProjectMediaSourceRanges(baseUrl, headers, projectId, ranges, { json: jsonOutput });
     } else {
@@ -2737,7 +2766,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   } else {
     console.log(`Project commands:
   project media <projectId> --json      List timeline media for a project
-  project media add <projectId> ...     Add external source_url + start + end media
+  project media add <projectId> ...     Add typed external image/video media
 `);
   }
 } else if (command === 'abort') {
@@ -2775,11 +2804,19 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       editArgs.referenceImages.push(imageToArg(args[++i]));
     }
     else if (args[i] === '--aspect' && args[i + 1]) editArgs.aspectRatio = args[++i];
+    else if (args[i] === '--background' && args[i + 1]) {
+      const background = args[++i];
+      if (!['auto', 'opaque', 'transparent'].includes(background)) {
+        console.error('Invalid --background. Use auto, opaque, or transparent.');
+        process.exit(1);
+      }
+      editArgs.background = background;
+    }
     else if (args[i] === '--out' && args[i + 1]) outputPath = args[++i];
     else promptParts.push(args[i]);
   }
   editArgs.editPrompt = promptParts.join(' ');
-  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--ref <file>] [--out <file>] "prompt"'); process.exit(1); }
+  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--ref <file>] [--aspect <ratio>] [--background auto|opaque|transparent] [--out <file>] "prompt"'); process.exit(1); }
   process.stderr.write('🎨 Generating...\n');
   const result = await callMcpTool(baseUrl, headers, 'makaron_edit_image', editArgs);
   saveMcpImage(result, outputPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.0",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {

package/skills/makaron/SKILL.md

@@ -180,16 +180,17 @@ npx makaron-cli project media <projectId> --json
 
 This is project-scoped. `responses get <runId> --pick output` only returns artifacts from one run; `project media` returns the whole project timeline: original uploads, references, generated images, video snapshots, and editable compositions.
 
-Publish an external video interval directly into that Media List without uploading the original or a derivative MP4:
+Publish typed external images and video intervals directly into that Media List without uploading the original media:
 
 ```bash
-npx makaron-cli project media add <projectId> --source-url "https://cdn.example.com/source.mp4" --start 12.5 --end 19 --description "Racket frame molding"
-npx makaron-cli project media add <projectId> --input ranges.json --json
+npx makaron-cli project media add <projectId> --type image --source-url "https://cdn.example.com/product.jpg" --description "Hero product image"
+npx makaron-cli project media add <projectId> --type video --source-url "https://cdn.example.com/source.mp4" --start 12.5 --end 19 --description "Racket frame molding"
+npx makaron-cli project media add <projectId> --input media.json --json
 ```
 
-The JSON input may be an array or `{ "clips": [...] }`. Each clip has exactly `source_url + start + end + description`; `start` and `end` are seconds, array order is edit order, and `source_url` is opaque. Do not add or request provider-specific identity fields. Put existing media understanding (summary, editorial purpose, scene evidence, confidence, and limitations) in `description`. Makaron reads that provider-neutral Media List field before deciding whether any additional image/video analysis is needed.
+The JSON input may be an array or `{ "clips": [...] }`. Every item declares `type` as `image` or `video`. Images have `source_url + type + description` and no time range. Videos have `source_url + type + start + end + description`; `start` and `end` are seconds. Array order is edit order and `source_url` is opaque. Do not add or request provider-specific identity fields. Put existing media understanding (summary, editorial purpose, scene evidence, confidence, and limitations) in `description`. Makaron reads that provider-neutral Media List field before deciding whether any additional image/video analysis is needed.
 
-For one-call orchestration, use `chat --project auto --media-manifest plan.json`. Makaron validates the manifest, creates the project, imports its ranges, and starts the Agent. If an upstream service returns multiple plans, the caller should start one independent Makaron task per plan instead of passing the provider-specific batch response into Makaron.
+For one-call orchestration, use `chat --project auto --media-manifest plan.json`. Makaron validates the manifest, creates the project, imports its media, and starts the Agent. If an upstream service returns multiple plans, the caller should start one independent Makaron task per plan instead of passing the provider-specific batch response into Makaron.
 
 ```bash
 npx makaron-cli chat --project auto --media-manifest set-01.json --json -b "Make a 30-second 9:16 TikTok with English VO and captions"
@@ -292,9 +293,12 @@ npx makaron-cli edit --image photo.jpg --ref style.jpg "match this style"
 
 # Output to file
 npx makaron-cli edit --image photo.jpg --out result.jpg "make it dramatic"
+
+# Strict transparent output through GPT Image 2
+npx makaron-cli edit --image-model openai --background transparent --out sticker.png "a magenta star sticker"
 ```
 
-Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--background auto|opaque|transparent`, `--out <path>`. Transparent output routes strictly to GPT Image 2 and fails instead of returning an opaque fallback.
 
 ### `video` — Standalone video tools (no project timeline)