makaron-cli 0.3.0 → 0.4.0

package/README.md

@@ -36,62 +36,111 @@ The CLI checks `MAKARON_API_KEY` first, then falls back to the saved session in
 
 ## Commands
 
-### `list` — Show all projects
+### `chat` — Send a message to Makaron Agent
+
+This is the main command. The Agent can edit images, generate videos, compose music, and create designs.
+
+**Default mode (non-blocking poll):**
 
 ```bash
-npx makaron-cli list
+npx makaron-cli chat --project <id> "make it look cinematic"
 ```
 
-Output:
-```
-📁 12 projects
+The CLI submits the request and polls every 3s for results. No long-lived connection — you can Ctrl+C and come back later with `responses get`.
 
-  abc123def  My Photo                        3 snaps  2h ago
-  xyz789ghi  Sunset Edit                     5 snaps  1d ago
+**Background mode — submit and exit immediately:**
+
+```bash
+npx makaron-cli chat --project <id> --background "make a 5s video"
+# → prints runId and exits in <1s
+
+# Later, check the result:
+npx makaron-cli responses get <runId> --wait
 ```
 
-### `create` — Create a new project
+**Structured JSON output (for programmatic use):**
 
 ```bash
-# From local image file(s)
-npx makaron-cli create --image photo.jpg
-npx makaron-cli create --image img1.jpg --image img2.jpg
+npx makaron-cli chat --project <id> --json --background "edit the photo"
+# → {"runId":"...","projectId":"...","projectUrl":"...","status":"running"}
+```
 
-# From URL(s)
-npx makaron-cli create --image-url https://example.com/photo.jpg
+**Legacy streaming mode (real-time SSE):**
 
-# Empty project (for text-to-image)
-npx makaron-cli create --title "My New Project"
+```bash
+npx makaron-cli chat --project <id> --stream "hello"
 ```
 
-Output:
-```
-✅ Project created
-   ID: abc123def456
-   Images: 1
-   [1] https://sdyrtztrjgmmpnirswxt.supabase.co/storage/v1/object/public/images/...
-   URL: https://www.makaron.app/projects/abc123def456
+**Options:**
+- `--project <id>` — target project (required)
+- `--image <file>` — upload image to project before chatting
+- `--background` / `-b` — submit and exit, print runId
+- `--json` — structured JSON output
+- `--stream` — legacy real-time SSE mode
+- `--video-model kling|seedance` — preferred video model
+- `--model <name>` — preferred image model
+
+### `responses` — Query run status and results
+
+```bash
+# Get current status (single query)
+npx makaron-cli responses get <runId>
+
+# Poll until completed
+npx makaron-cli responses get <runId> --wait
+
+# Wait for video/music rendering too (not just Agent completion)
+npx makaron-cli responses get <runId> --wait --wait-artifacts
+
+# List runs for a project
+npx makaron-cli responses list --project <id>
 ```
 
-### `chat` — Send a message to Makaron Agent
+**Result JSON structure:**
+
+```json
+{
+  "runId": "...",
+  "projectId": "...",
+  "status": "completed",
+  "eventCount": 31,
+  "result": {
+    "text": "Agent's text response...",
+    "images": [{ "snapshotId": "...", "imageUrl": "https://..." }],
+    "designs": [{
+      "snapshotId": "...",
+      "imageUrl": "https://...",
+      "width": 1080,
+      "height": 1920,
+      "animation": { "fps": 30, "durationInSeconds": 3 },
+      "props": { "title": "..." },
+      "code": "function Design(props) { ... }"
+    }],
+    "videos": [{ "taskId": "...", "status": "completed", "videoUrl": "https://..." }],
+    "music": [{ "taskId": "...", "status": "completed", "audioUrl": "https://..." }]
+  }
+}
+```
 
-This is the main command. The Agent can edit images, generate videos, compose music, and create designs.
+### `list` — Show all projects
 
 ```bash
-npx makaron-cli chat --project <id> "make it look cinematic"
+npx makaron-cli list
 ```
 
-The Agent streams its response in real-time:
-- **Text** → stdout (pipe-friendly)
-- **Status/progress** → stderr
-- **Images, videos, music** → URLs printed to stderr
+### `create` — Create a new project
 
 ```bash
-# Add extra reference images to the project before chatting
-npx makaron-cli chat --project <id> --image ref.jpg "use this style"
-```
+# From local image file(s)
+npx makaron-cli create --image photo.jpg
+npx makaron-cli create --image img1.jpg --image img2.jpg
+
+# From URL(s)
+npx makaron-cli create --image-url https://example.com/photo.jpg
 
-After the Agent finishes, the CLI automatically polls for any pending video/music tasks until they complete.
+# Empty project (for text-to-image)
+npx makaron-cli create --title "My New Project"
+```
 
 ### `abort` — Stop a running Agent
 
@@ -99,8 +148,6 @@ After the Agent finishes, the CLI automatically polls for any pending video/musi
 npx makaron-cli abort <runId>
 ```
 
-Press `Ctrl+C` during `chat` to abort automatically.
-
 ### `edit` — AI image editing (direct MCP tool call)
 
 Unlike `chat` (which uses the Agent with project context), `edit` directly calls the image generation model for one-shot results.
@@ -130,30 +177,19 @@ Options:
 - `--aspect <ratio>` — target aspect ratio (e.g. `4:5`, `1:1`, `16:9`)
 - `--out <path>` — output file path (default: `makaron-output-{timestamp}.jpg`)
 
-Output: saves image to local file, prints the file path to stdout.
-
 ### `video` — Video generation
 
 ```bash
 # Write a video script from images
 npx makaron-cli video script --image img1.jpg --image img2.jpg "cinematic story"
-npx makaron-cli video script --image img1.jpg --image img2.jpg --lang zh "电影感故事"
 
 # Submit video rendering (images must be public URLs)
 npx makaron-cli video create --script "Shot 1..." --image https://...img1.jpg --duration 10
-npx makaron-cli video create --script-file script.txt --image https://...jpg --model seedance
 
 # Check status
 npx makaron-cli video status <taskId>
 ```
 
-Options for `video create`:
-- `--script "..."` or `--script-file <path>` — video script
-- `--image <url>` — public image URL (repeatable, up to 7)
-- `--duration 3|5|7|10|15` — seconds (omit for smart mode)
-- `--aspect 9:16|16:9|1:1` — aspect ratio
-- `--model kling|seedance` — video model (default: kling)
-
 ### `music` — Music generation
 
 ```bash
@@ -167,48 +203,45 @@ npx makaron-cli music create --vocals --style "lo-fi, ambient" "rainy day vibes"
 npx makaron-cli music status <taskId>
 ```
 
-Options for `music create`:
-- `--vocals` — include vocals (default: instrumental only)
-- `--style "genre"` — genre/mood tags
-
-## Example: Full workflow
+## Agent Integration Guide
 
-```bash
-# 1. Login (once)
-npx makaron-cli login
+For AI agents (Claude Code, OpenClaw, etc.) calling this CLI programmatically:
 
-# 2. Create a project from a photo
-npx makaron-cli create --image my-photo.jpg
-# → ID: proj_abc123
+### Non-blocking workflow (recommended)
 
-# 3. Edit the image
-npx makaron-cli chat --project proj_abc123 "add dramatic lighting and film grain"
+```bash
+# 1. Submit task — returns immediately
+RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID --background "make a 5s video")
 
-# 4. Generate a video from the result
-npx makaron-cli chat --project proj_abc123 "make a 5 second cinematic video"
+# 2. Do other work while Makaron processes...
 
-# 5. Add background music
-npx makaron-cli chat --project proj_abc123 "add epic orchestral background music"
+# 3. Poll for result when ready
+npx makaron-cli responses get $RUN_ID --wait
 ```
 
-## Agent Integration Guide
+### JSON mode for structured parsing
+
+```bash
+# Submit
+RESULT=$(npx makaron-cli chat --project $ID --json --background "edit the photo")
+RUN_ID=$(echo $RESULT | jq -r .runId)
 
-For AI agents (Claude Code, Cursor, etc.) calling this CLI programmatically:
+# Poll
+npx makaron-cli responses get $RUN_ID --wait
+```
 
-### Setup (one-time)
+### Sequential multi-turn
 
 ```bash
-export MAKARON_API_KEY=mk_live_your_key_here
-npx makaron-cli list   # verify it works
-```
+# Turn 1: edit image
+npx makaron-cli chat --project $ID "make it cinematic"
+# Wait for completion (default mode polls automatically)
 
-### Best practices
+# Turn 2: make video from the edited image
+npx makaron-cli chat --project $ID "now make a 5s video from this"
+```
 
-1. **Always capture the project ID** from `create` output — you need it for all `chat` commands
-2. **One instruction per `chat` call** — the Agent handles complex requests, but single clear instructions work best
-3. **Check results via the URL** — every project has a web URL at `https://www.makaron.app/projects/<id>`
-4. **Video generation takes 2-5 minutes** — the CLI auto-polls and prints the URL when done
-5. **Music generation takes ~60 seconds** — also auto-polled
+Note: One project runs one Agent at a time. A new message while the previous is still running will interrupt the first.
 
 ### What the Agent can do
 
@@ -224,16 +257,16 @@ npx makaron-cli list   # verify it works
 | Background music | "add calm piano music" |
 | Design/motion graphics | "create an Instagram story with animated text" |
 
-### Output parsing
+### Output types in result
 
-- **stdout** = Agent's text response (markdown)
-- **stderr** = progress, tool calls, result URLs
-- Key patterns in stderr:
-  - `🖼️  Image: <url>` — generated/edited image URL
-  - `🎬 Video done (<seconds>s): <url>` — completed video URL
-  - `🎵 Music done (<seconds>s): <url>` — completed music URL
-  - `🎨 Design published: <description>` — motion graphic/design created
-  - `🔗  <url>` — project web URL (always last)
+| Type | Field | Contains |
+|------|-------|----------|
+| Text | `result.text` | Agent's conversational response |
+| Image | `result.images[].imageUrl` | Generated/edited image URL |
+| Design (still) | `result.designs[].imageUrl` | Poster screenshot + code |
+| Design (animated) | `result.designs[].animation` | fps + duration + code |
+| Video | `result.videos[].videoUrl` | MP4 URL (after rendering) |
+| Music | `result.music[].audioUrl` | MP3 URL (after generating) |
 
 ### Environment variables
 
@@ -250,8 +283,6 @@ All generated content (images, videos, designs) is saved to the project and visi
 https://www.makaron.app/projects/<project-id>
 ```
 
-Open this URL in a browser to see the timeline of all edits, play videos, and download assets.
-
 ## Admin: Skill Marketplace Operations
 
 Admin commands require an API key with admin privileges. Ask your admin to run `makaron admin set-admin <your-email>` to grant access.
@@ -272,7 +303,7 @@ npx makaron-cli admin upload cover.jpg marketplace/covers/skill-name.jpg
 npx makaron-cli admin upload before.jpg marketplace/before/before-name.jpg
 
 # Upload skill zip
-npx makaron-cli admin upload skill.zip marketplace/skills/skill-name.zip
+npx makaron-cli admin upload skill-name.zip marketplace/skills/skill-name.zip
 ```
 
 Storage paths follow this convention:

package/bin/makaron.mjs

@@ -6,6 +6,8 @@
  *   npx makaron-cli login
  *   npx makaron-cli create --image photo.jpg
  *   npx makaron-cli chat --project <id> "make it look cinematic"
+ *   npx makaron-cli chat --project <id> -b "message"       # background, returns runId
+ *   npx makaron-cli responses get <runId> --wait            # poll until done
  *   npx makaron-cli list
  */
 
@@ -226,6 +228,138 @@ async function streamAgent(baseUrl, headers, projectId, prompt) {
   return { runId, results };
 }
 
+// ─── Run + Poll (non-blocking) ──────────────────────────────────────────────
+
+async function submitRun(baseUrl, headers, projectId, prompt, opts = {}) {
+  const body = { projectId, prompt };
+  if (opts.preferredModel) body.preferredModel = opts.preferredModel;
+  if (opts.videoModel) body.videoModel = opts.videoModel;
+  if (opts.currentSnapshotIndex != null) body.currentSnapshotIndex = opts.currentSnapshotIndex;
+  if (opts.isNsfw) body.isNsfw = opts.isNsfw;
+
+  const res = await fetch(`${baseUrl}/api/agent/run`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    console.error(`Error ${res.status}: ${text}`);
+    process.exit(1);
+  }
+
+  return await res.json();
+}
+
+async function pollRun(baseUrl, headers, runId, opts = {}) {
+  const { json = false, waitForArtifacts = false, background = false } = opts;
+  if (background) return;
+
+  let lastSeq = -1;
+  let printedText = '';
+  const start = Date.now();
+
+  while (true) {
+    await new Promise(r => setTimeout(r, 3000));
+    const elapsed = Math.round((Date.now() - start) / 1000);
+
+    const params = new URLSearchParams({ events: 'true' });
+    if (lastSeq >= 0) params.set('after', String(lastSeq));
+    if (waitForArtifacts) params.set('wait_for_artifacts', 'true');
+
+    let data;
+    try {
+      const res = await fetch(`${baseUrl}/api/agent/run/${runId}?${params}`, { headers });
+      if (!res.ok) {
+        if (elapsed > 800) { process.stderr.write(`\n❌ Timeout after ${elapsed}s\n`); process.exit(1); }
+        continue;
+      }
+      data = await res.json();
+    } catch {
+      continue;
+    }
+
+    // Process incremental events
+    if (data.events?.length) {
+      for (const ev of data.events) {
+        if (ev.seq > lastSeq) lastSeq = ev.seq;
+        if (json) continue; // skip printing in json mode
+        switch (ev.type) {
+          case 'content': {
+            const newText = ev.data?.text || '';
+            process.stdout.write(newText);
+            printedText += newText;
+            break;
+          }
+          case 'status':
+            process.stderr.write(`\r⏳ ${ev.data?.text || ''}`);
+            break;
+          case 'tool_call':
+            process.stderr.write(`\n🔧 ${ev.data?.tool || ''}`);
+            if (ev.data?.input?.editPrompt) process.stderr.write(`\n   editPrompt: ${ev.data.input.editPrompt}`);
+            if (ev.data?.input?.model) process.stderr.write(`\n   model: ${ev.data.input.model}`);
+            if (ev.data?.input?.description) process.stderr.write(`: ${ev.data.input.description.substring(0, 80)}`);
+            process.stderr.write('\n');
+            break;
+          case 'image':
+            process.stderr.write(`\n🖼️  Image: ${ev.data?.imageUrl || '(uploading...)'}\n`);
+            break;
+          case 'render':
+            if (ev.data?.published) {
+              const desc = ev.data.animation
+                ? `${ev.data.animation.durationInSeconds}s video (${ev.data.width}x${ev.data.height})`
+                : `still design (${ev.data.width}x${ev.data.height})`;
+              process.stderr.write(`\n🎨 Design published: ${desc}\n`);
+            }
+            break;
+          case 'animation_task':
+            process.stderr.write(`\n🎬 Video submitted: ${ev.data?.taskId}\n`);
+            break;
+          case 'music_task':
+            process.stderr.write(`\n🎵 Music submitted: ${ev.data?.taskId}\n`);
+            break;
+          case 'error':
+            process.stderr.write(`\n❌ Error: ${ev.data?.message}\n`);
+            break;
+        }
+      }
+    } else if (!json) {
+      process.stderr.write(`\r⏳ Working... ${elapsed}s (${data.eventCount || 0} events)`);
+    }
+
+    // Check terminal status
+    if (data.status === 'completed' || data.status === 'failed' || data.status === 'aborted') {
+      if (printedText && !json) process.stdout.write('\n');
+
+      if (json) {
+        // Structured JSON output — add projectUrl
+        data.projectUrl = `${APP_URL}/projects/${data.projectId}`;
+        console.log(JSON.stringify(data, null, 2));
+      } else {
+        process.stderr.write('\n━━━ Results ━━━\n');
+        if (data.result) {
+          for (const img of data.result.images || []) process.stderr.write(`🖼️  Image: ${img.imageUrl}\n`);
+          for (const d of data.result.designs || []) process.stderr.write(`🎨  Design (${d.width}x${d.height})\n`);
+          for (const v of data.result.videos || []) {
+            if (v.videoUrl) process.stderr.write(`🎬  Video: ${v.videoUrl}\n`);
+            else process.stderr.write(`🎬  Video ${v.taskId}: ${v.status || 'submitted'}\n`);
+          }
+          for (const m of data.result.music || []) {
+            if (m.audioUrl) process.stderr.write(`🎵  Music: ${m.audioUrl}\n`);
+            else process.stderr.write(`🎵  Music ${m.taskId}: ${m.status || 'submitted'}\n`);
+          }
+          if (data.result.error) process.stderr.write(`❌  ${data.result.error}\n`);
+        }
+        process.stderr.write(`🔗  ${APP_URL}/projects/${data.projectId}\n`);
+      }
+
+      if (data.status === 'failed') process.exit(1);
+      return data;
+    }
+  }
+}
+
 // ─── Async Task Polling ──────────────────────────────────────────────────────
 
 async function pollVideo(baseUrl, headers, taskId) {
@@ -401,16 +535,27 @@ if (command === 'login') {
   let projectId = null;
   const chatImages = [];
   const promptParts = [];
+  let useStream = false;
+  let background = false;
+  let jsonOutput = false;
+  let videoModel = undefined;
+  let preferredModel = undefined;
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
     else if (args[i] === '--image' && args[i + 1]) chatImages.push(args[++i]);
+    else if (args[i] === '--stream') useStream = true;
+    else if (args[i] === '--background' || args[i] === '-b') background = true;
+    else if (args[i] === '--json') jsonOutput = true;
+    else if (args[i] === '--video-model' && args[i + 1]) videoModel = args[++i];
+    else if (args[i] === '--model' && args[i + 1]) preferredModel = args[++i];
     else promptParts.push(args[i]);
   }
   const prompt = promptParts.join(' ');
   if (!projectId || !prompt) {
-    console.error('Usage: makaron chat --project <id> [--image <file>] "your message"');
+    console.error('Usage: makaron chat --project <id> [--image <file>] [--stream] [--background|-b] [--json] "your message"');
     process.exit(1);
   }
+  // Upload images if provided
   if (chatImages.length > 0) {
     const base64s = chatImages.map(imgPath => {
       process.stderr.write(`📤 Uploading ${path.basename(imgPath)}...\n`);
@@ -429,13 +574,83 @@ if (command === 'login') {
       process.stderr.write(`⚠️ Failed to upload images: ${await res.text()}\n`);
     }
   }
-  const { results } = await streamAgent(baseUrl, headers, projectId, prompt);
-  process.stderr.write('\n━━━ Results ━━━\n');
-  for (const img of results.images) process.stderr.write(`🖼️  Image: ${img.imageUrl}\n`);
-  for (const d of results.designs) process.stderr.write(`🎨  ${d.desc}\n`);
-  process.stderr.write(`🔗  ${APP_URL}/projects/${projectId}\n`);
-  for (const task of results.animationTasks) await pollVideo(baseUrl, headers, task.taskId);
-  for (const task of results.musicTasks) await pollMusic(baseUrl, headers, task.taskId);
+
+  if (useStream) {
+    // Legacy SSE mode
+    const { results } = await streamAgent(baseUrl, headers, projectId, prompt);
+    process.stderr.write('\n━━━ Results ━━━\n');
+    for (const img of results.images) process.stderr.write(`🖼️  Image: ${img.imageUrl}\n`);
+    for (const d of results.designs) process.stderr.write(`🎨  ${d.desc}\n`);
+    process.stderr.write(`🔗  ${APP_URL}/projects/${projectId}\n`);
+    for (const task of results.animationTasks) await pollVideo(baseUrl, headers, task.taskId);
+    for (const task of results.musicTasks) await pollMusic(baseUrl, headers, task.taskId);
+  } else {
+    // Default: fire-and-forget + poll
+    const { runId } = await submitRun(baseUrl, headers, projectId, prompt, { videoModel, preferredModel });
+    if (background) {
+      // Just print runId and exit
+      if (jsonOutput) {
+        console.log(JSON.stringify({ runId, projectId, projectUrl: `${APP_URL}/projects/${projectId}`, status: 'running' }));
+      } else {
+        console.log(runId);
+      }
+    } else {
+      process.stderr.write(`🚀 Run started: ${runId}\n`);
+      await pollRun(baseUrl, headers, runId, { json: jsonOutput });
+    }
+  }
+} else if (command === 'responses' || command === 'run') {
+  const { headers, baseUrl } = getAuth();
+  const sub = args[1];
+
+  if (sub === 'get') {
+    const runId = args[2];
+    if (!runId) { console.error('Usage: makaron responses get <runId> [--wait] [--json]'); process.exit(1); }
+    let wait = false, jsonOutput = false, waitForArtifacts = false;
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--wait') wait = true;
+      if (args[i] === '--json') jsonOutput = true;
+      if (args[i] === '--wait-artifacts') waitForArtifacts = true;
+    }
+
+    if (wait) {
+      await pollRun(baseUrl, headers, runId, { json: jsonOutput, waitForArtifacts });
+    } else {
+      const params = new URLSearchParams();
+      if (waitForArtifacts) params.set('wait_for_artifacts', 'true');
+      const res = await fetch(`${baseUrl}/api/agent/run/${runId}?${params}`, { headers });
+      if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+      const data = await res.json();
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+  } else if (sub === 'list') {
+    let projectId = null;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
+    }
+    if (!projectId) { console.error('Usage: makaron responses list --project <id>'); process.exit(1); }
+    // Query runs for project
+    const res = await fetch(`${baseUrl}/api/agent/run?projectId=${projectId}`, { headers });
+    if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+    const data = await res.json();
+    if (data.runs?.length) {
+      for (const r of data.runs) {
+        const age = timeSince(new Date(r.started_at));
+        console.log(`  ${r.id}  ${r.status.padEnd(10)} ${age}  ${(r.prompt || '').slice(0, 50)}`);
+      }
+    } else {
+      console.log('No runs found for this project.');
+    }
+
+  } else {
+    console.log(`Responses commands:
+  responses get <runId>                  Get run status and results
+  responses get <runId> --wait           Poll until completed
+  responses get <runId> --wait-artifacts Wait for video/music too
+  responses list --project <id>          List runs for a project
+`);
+  }
 } else if (command === 'list' || command === 'ls') {
   const { headers, baseUrl } = getAuth();
   await listProjects(baseUrl, headers);
@@ -696,8 +911,15 @@ Commands:
   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)
-  chat --project <id> "message"      Chat with Makaron Agent
-  chat --project <id> --image <file> "message"  Add image + chat
+
+  chat --project <id> "message"      Chat (non-blocking, polls for result)
+  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
+
+  responses get <runId>              Get run status and results
+  responses get <runId> --wait       Poll until completed
+  responses list --project <id>      List runs for a project
   abort <runId>                      Abort a running Agent
 
   edit [--image <file>] "prompt"     AI image edit / text-to-image

package/package.json

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