veogent 1.1.2 → 1.1.3

package/.claude/worktrees/vigorous-hellman/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -oE 'Skill: `[a-z][-a-z]*' /Users/tuan.nguyen12/Documents/tuan.nguyen12/Repo/ISEMI/veogent-cli/.claude/worktrees/vigorous-hellman/skills/SKILL.md)",
+      "Bash(sed 's/Skill: `//')"
+    ]
+  }
+}

package/.claude/worktrees/vigorous-hellman/README.md

@@ -0,0 +1,370 @@
+# 🎬 Veogent CLI <a href="https://veogent.com"><img src="https://veogent.com/favicon.ico" width="24" height="24" align="center" /></a>
+
+**The official Command-Line Interface for the [VEOGENT API](https://veogent.com)**.
+
+Veogent CLI gives you (and your AI Agents) the power to manage full-scale AI video and story projects directly from the terminal. Connect to projects, orchestrate multi-frame scenes, edit image prompts with professional camera cues, and trigger large-scale generation jobs natively.
+
+Perfectly engineered for **Agentic workflows** — enabling tools like OpenClaw, Claude, and Codex to autonomously generate JSON-driven movies from scratch.
+
+---
+
+## 🚀 Installation
+
+Install globally via npm:
+
+```bash
+npm install -g veogent
+```
+
+---
+
+## 🔐 Authentication
+
+Veogent CLI supports both browser callback login and headless device-code login.
+
+```bash
+# Browser callback flow (desktop)
+veogent login
+
+# Device-code flow (VM/server/headless — recommended for AI Agents)
+veogent login --device
+
+# Verify your session
+veogent status
+
+# Clear saved credentials
+veogent logout
+
+# Setup/update Google Flow Key (required for video generation & AI features)
+veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"
+```
+
+---
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output machine-readable JSON only (suppress emoji/human text) |
+| `--agent-safe` | Agent-safe mode — no emoji, no browser surprises, stable output. Auto-enables `--device` for login. |
+| `--version` | Print CLI version |
+
+> **For AI Agents:** always use `--agent-safe` to guarantee deterministic, parseable JSON output with no interactive prompts.
+
+---
+
+## 📋 Complete Command Reference
+
+### Authentication & Configuration
+
+| Command | Description |
+|---------|-------------|
+| `login` | Login via browser callback or device code flow (`--device`) |
+| `logout` | Clear saved credentials and remove stored access token |
+| `status` | Show authenticated user, Flow Key details, and payment tier |
+| `setup-flow` | Setup/update Google Flow Key and User Payment Tier |
+
+### Capabilities & Discovery
+
+| Command | Description |
+|---------|-------------|
+| `capabilities` | Get backend capabilities (models, orientations, speed modes, queue) |
+| `image-models` | List supported image generation models |
+| `video-models` | List supported video generation models |
+| `image-materials` | Get all available Image Material styles (e.g., `CINEMATIC`, `PIXAR_3D`) |
+| `custom-prompts` | Get custom prompt templates and story directives |
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `projects` | List all your available projects |
+| `project <id>` | Get details for a specific project |
+| `create-project-description` | Generate AI description for a new project based on keywords |
+| `create-project` | Create a new project with name, keywords, material, chapters, objects |
+
+### Chapters
+
+| Command | Description |
+|---------|-------------|
+| `chapters <projectId>` | Get all chapters for a project |
+| `recent-chapters` | Get recently created or updated chapters |
+| `create-chapter-content` | Generate content for a chapter (synchronous AI generation) |
+
+### Characters
+
+| Command | Description |
+|---------|-------------|
+| `characters <projectId>` | Get all characters with readiness info |
+| `edit-character` | Update character description or edit generated image via AI prompt |
+
+### Scenes
+
+| Command | Description |
+|---------|-------------|
+| `scenes <projectId> <chapterId>` | Get all scenes for a chapter |
+| `create-scene` | Create new scene(s) from text content |
+| `add-scene` | Add a single scene to a chapter with a user prompt |
+| `edit-scene` | Edit scene image prompt via AI assistance |
+
+### Generation Requests (Project-scoped)
+
+> **Clarification:** `request` (singular) = **CREATE** a new job. `requests` (plural) = **LIST** existing jobs.
+
+| Command | Description |
+|---------|-------------|
+| `request` | Create a generation job: `GENERATE_IMAGES`, `GENERATE_VIDEO`, or `VIDEO_UPSCALE` |
+| `requests` | List generation requests (filterable by project, chapter, status) |
+| `upscale` | Upscale video output for a scene (shortcut for `request --type VIDEO_UPSCALE`) |
+| `assets <projectId> <chapterId> <sceneId> <type>` | Check generated assets history/status for a scene |
+
+### Standalone Generation (No Project Needed)
+
+> These commands generate images/videos without a project. Ideal for quick one-off generations.
+
+| Command | Description |
+|---------|-------------|
+| `gen-image` | Generate image from text prompt (standalone, 3 credits, Imagen 3.5) |
+| `gen-video` | Generate video from text prompt (standalone, 5 credits, Veo 3.1 Fast) |
+| `standalone-requests` | List your standalone generation requests |
+| `standalone-request <requestId>` | Get details of a specific standalone request |
+
+### Monitoring & Status
+
+| Command | Description |
+|---------|-------------|
+| `scene-status` | Scene-level status with embedded asset URLs (image + video per scene) |
+| `workflow-status` | Full workflow snapshot: scenes + requests + assets (agent helper) |
+| `scene-materialization-status` | Check how many scenes have materialized for a chapter |
+| `failed-requests` | List failed/error/rejected requests for a project/chapter (agent helper) |
+| `wait-images` | Poll until all image requests in a chapter finish |
+| `wait-videos` | Poll until all video requests in a chapter finish |
+| `queue-status` | Get current queue/concurrency status |
+
+### YouTube Integration
+
+| Command | Description |
+|---------|-------------|
+| `generate-yt-metadata` | Generate YouTube metadata (Title, Description, Tags) for a chapter |
+| `generate-yt-thumbnail` | Trigger request to generate a YouTube thumbnail |
+| `yt-thumbnails <projectId> <chapterId>` | Get generated YouTube thumbnails for a chapter |
+
+### Flow Token & Credits
+
+| Command | Description |
+|---------|-------------|
+| `obtain-flow` | Auto-extract Flow Token (ya29.) using secure browser overlay |
+| `flow-credits` | Fetch plan and credit info from Google AI Sandbox |
+
+### Utility
+
+| Command | Description |
+|---------|-------------|
+| `skill` | Print the native Agent SKILL.md guide |
+
+---
+
+## 🛠️ Usage Examples
+
+### Project Management
+
+```bash
+# List all your active projects
+veogent projects
+
+# View available Image Material styles (e.g., CINEMATIC, PIXAR_3D)
+veogent image-materials
+
+# Create a brand new AI Story Project
+veogent create-project --name "Cyberpunk T-Rex" --keyword "T-rex, Neon, Sci-fi" \
+  --desc "A massive T-rex walking inside Tokyo" --lang "English" --material "CINEMATIC" --chapters 5 \
+  --objects '{"name":"Hero","entityType":"character","description":"brave knight"}'
+```
+
+### Storyboard, Chapters & Scenes
+
+```bash
+# Get all chapters within a project
+veogent chapters <projectId>
+
+# View characters (includes readiness info)
+veogent characters <projectId>
+# → { characters: [...], characterReadiness: {total, ready, allReady} }
+
+# Check scene materialization status
+veogent scene-materialization-status --project <projectId> --chapter <chapterId>
+# → { expectedScenes, materializedScenes, status: "PROCESSING"|"READY"|"EMPTY" }
+
+# Create scenes from narrative scripts
+veogent create-scene --project <projectId> --chapter <chapterId> --flowkey \
+  --content "The T-Rex looks up at the sky." "A meteor shower begins."
+
+# Add a single scene to an existing chapter
+veogent add-scene --project <projectId> --chapter <chapterId> \
+  --userprompt "A meteor crashes into the city." --after-scene-id <sceneId>
+```
+
+### Directing & Editing
+
+```bash
+# Edit scene image prompt with camera direction
+veogent edit-scene --project <projectId> --chapter <chapterId> --scene <sceneId> \
+  --userprompt "Low angle shot of the T-Rex, dramatic lighting."
+
+# Edit character image directly via AI
+veogent edit-character --project <projectId> --character "drelenavance" \
+  --userprompt "change outfit to dark leather jacket" --editimage
+```
+
+### Media Generation (Project-scoped)
+
+```bash
+# List supported models
+veogent image-models   # → { models: ["imagen3.5"] }
+veogent video-models   # → { models: ["veo_3_1_fast", "veo_3_1_fast_r2v"] }
+
+# Generate Image (project-scoped)
+veogent request --type "GENERATE_IMAGES" --project <projectId> --chapter <chapterId> --scene <sceneId> --imagemodel "imagen3.5"
+
+# Generate Video (project-scoped)
+veogent request --type "GENERATE_VIDEO" --project <projectId> --chapter <chapterId> --scene <sceneId> --videomodel "veo_3_1_fast"
+
+# Upscale Video
+veogent upscale --project <projectId> --chapter <chapterId> --scene <sceneId> --orientation "VERTICAL" --resolution "VIDEO_RESOLUTION_4K"
+```
+
+### Standalone Generation (No Project)
+
+```bash
+# Quick image generation (3 credits)
+veogent gen-image --prompt "A futuristic city at sunset" --orientation "HORIZONTAL"
+
+# Quick video generation (5 credits)
+veogent gen-video --prompt "A cat playing piano" --orientation "HORIZONTAL"
+
+# Check standalone request status
+veogent standalone-requests
+veogent standalone-request <requestId>
+```
+
+### Monitoring & Status
+
+```bash
+# List recent requests
+veogent requests --limit 10
+
+# Filter by project/chapter/status
+veogent requests --project <projectId> --chapter <chapterId> --status FAILED
+
+# Scene-level status with asset URLs
+veogent scene-status --project <projectId> --chapter <chapterId>
+
+# Full workflow snapshot (agent helper)
+veogent workflow-status --project <projectId> --chapter <chapterId>
+
+# Wait for all images/videos to complete (with success verification)
+veogent wait-images --project <projectId> --chapter <chapterId> --require-success
+veogent wait-videos --project <projectId> --chapter <chapterId> --require-success
+
+# Queue concurrency status
+veogent queue-status
+
+# Flow credit/plan info
+veogent flow-credits
+```
+
+### YouTube Publishing
+
+```bash
+# Generate YouTube metadata
+veogent generate-yt-metadata --project <projectId> --chapter <chapterId> --flowkey
+
+# Generate YouTube thumbnail
+veogent generate-yt-thumbnail --project <projectId> --chapter <chapterId>
+
+# Retrieve generated thumbnails
+veogent yt-thumbnails <projectId> <chapterId>
+```
+
+---
+
+## Agent Orchestration Notes
+
+### Request/Scene Semantics
+
+- `scene.requestId`: backward-compatible legacy pointer; may refer to latest relevant request but is **not type-specific**.
+- `scene.latestImageRequestId`: latest image-related request (`GENERATE_IMAGES` / `EDIT_IMAGE`) regardless of status.
+- `scene.latestVideoRequestId`: latest video request (`GENERATE_VIDEO`) regardless of status.
+- `scene.latestSuccessfulImageRequestId`: latest image-related request in `COMPLETED`.
+- `scene.latestSuccessfulVideoRequestId`: latest video request in `COMPLETED`.
+
+For robust automation:
+- Prefer `veogent scene-status` or `veogent workflow-status` for chapter-level overview.
+- Use `latestSuccessful*` fields when selecting canonical output URIs.
+
+### `request` (CREATE) vs `requests` (LIST)
+
+- **`request`** — Creates a new generation job (POST). Requires `--type` flag.
+- **`requests`** — Lists existing jobs (GET). Filterable with `--project`, `--chapter`, `--status`, `--limit`.
+
+### Project-scoped vs Standalone Generation
+
+| | Project-scoped | Standalone |
+|---|---|---|
+| **Image** | `request --type GENERATE_IMAGES --project ... --chapter ... --scene ...` | `gen-image --prompt "prompt"` |
+| **Video** | `request --type GENERATE_VIDEO --project ... --chapter ... --scene ...` | `gen-video --prompt "prompt"` |
+| **List** | `requests` | `standalone-requests` |
+| **Detail** | `requests` with filters | `standalone-request <id>` |
+
+### Status Commands: When to Use Which
+
+| Command | Use When |
+|---------|----------|
+| `requests` | Check individual request status, filter by status/project |
+| `scene-status` | Quick overview of image+video status per scene in a chapter |
+| `workflow-status` | Full snapshot with scenes + requests + assets (best for agents) |
+| `failed-requests` | Quick list of all failed/error/rejected requests for a chapter |
+| `wait-images` / `wait-videos` | Block until all generation jobs finish (polling) |
+
+---
+
+## 🤖 For AI Agents
+
+Veogent CLI ships with a comprehensive **[`skills/SKILL.md`](./skills/SKILL.md)** guide optimized for LLM/Coding Agents context processing. It defines exact DTO validations, model enumerations, camera prompting techniques, the full production pipeline, and error handling — everything an agent needs to orchestrate complete projects without hitting `400 Bad Request`.
+
+### Recommended Agent Workflow (Production)
+
+1. Resolve optional IDs first (if missing):
+   - `veogent custom-prompts`
+   - `veogent image-materials` (default fallback: `CINEMATIC`)
+2. Prepare story input (arc, summary, key notes).
+3. Generate project description:
+   - `veogent create-project-description ...`
+4. Create project from generated payload.
+5. Create chapter content with scene count:
+   - `veogent create-chapter-content --scenes <sceneCount>`
+   - Rule: each scene maps to ~8s clip.
+6. Create scenes from returned script list:
+   - `veogent create-scene --project <projectId> --chapter <chapterId> --content "scene 1" "scene 2" ... --flowkey`
+7. Wait for character generation completion (`imageUri` required for all characters):
+   - `veogent characters <projectId>` — check `characterReadiness.allReady === true`
+   - `veogent scene-materialization-status --project <projectId> --chapter <chapterId>` — verify `status: "READY"`
+   - If missing/fail: inspect `veogent requests --limit 20`, recover via `veogent edit-character`.
+8. Generate scene images:
+   - `veogent request --type "GENERATE_IMAGES" ...`
+   - If image is reported wrong, decode image to Base64 and send to AI reviewer for evaluation.
+   - If mismatch persists, fix via:
+     - `veogent edit-scene --userprompt "..."` (prompt refinement), or
+     - `veogent edit-scene --request <requestId> ...` (direct edit on prior generated image)
+9. Generate video only after matching-orientation image exists successfully:
+   - `veogent request --type "GENERATE_VIDEO" ...`
+
+> 📖 For the full detailed guide with all commands, options tables, and examples, see **[`skills/SKILL.md`](./skills/SKILL.md)**.
+
+**Concurrency:** maximum **5** requests can be processed simultaneously. If the API reports maximum limit reached, treat it as queue-full (wait/retry), not a hard failure.
+
+---
+
+## 📜 License
+
+MIT License. Crafted with ❤️ by Pym & Tuan Nguyen.

package/.claude/worktrees/vigorous-hellman/api.js

@@ -0,0 +1,43 @@
+import axios from 'axios';
+import { getToken } from './config.js';
+
+// Define the environment variables
+const API_URL = process.env.VGEN_API_URL || 'https://api.veogent.com';
+
+// API instance helper
+export const api = axios.create({
+    baseURL: API_URL,
+});
+
+// Interceptor to inject bearer token before every request
+api.interceptors.request.use((config) => {
+    const token = getToken();
+    if (token) {
+        config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+}, (error) => {
+    return Promise.reject(error);
+});
+
+// Interceptor to normalize successful payloads and throw structured errors
+api.interceptors.response.use(
+    (response) => response.data,
+    (error) => {
+        const status = error.response?.status || null;
+        const payload = error.response?.data || null;
+        const message = payload?.error?.message?.en
+            || payload?.error?.message
+            || payload?.message
+            || error.message
+            || 'Unknown API error';
+
+        const wrapped = new Error(message);
+        wrapped.name = 'VeogentApiError';
+        wrapped.status = status;
+        wrapped.payload = payload;
+        wrapped.code = payload?.errorCode || payload?.error?.code || null;
+        wrapped.retryable = status >= 500;
+        throw wrapped;
+    }
+);

package/.claude/worktrees/vigorous-hellman/auth.js

@@ -0,0 +1,77 @@
+import express from 'express';
+import cors from 'cors';
+import open from 'open';
+import crypto from 'crypto';
+
+export class WebAuthFlow {
+    constructor(port = 7890) {
+        this.port = port;
+        this.app = express();
+        this.server = null;
+        // Generate a random token to verify the callback matches our local terminal
+        this.cliToken = crypto.randomBytes(32).toString('hex');
+    }
+
+    start() {
+        return new Promise((resolve, reject) => {
+            this.app.use(cors());
+            this.app.use(express.json());
+
+            // Callback endpoint hit by the Next.js frontend
+            this.app.post('/callback', (req, res) => {
+                const { uid, idToken, cliToken } = req.body;
+
+                // Basic CSRF/validation check
+                if (cliToken !== this.cliToken) {
+                    res.status(403).json({ error: 'Mismatched CLI Token' });
+                    return;
+                }
+
+                if (!uid || !idToken) {
+                    res.status(400).json({ error: 'Missing UID or Token' });
+                    return;
+                }
+
+                // Send success immediately so the browser UI updates to "Success" quickly
+                res.status(200).json({ status: 'success' });
+                
+                // Close the server and return credentials to the CLI
+                setTimeout(() => {
+                    this.stop();
+                    resolve({ uid, accessToken: idToken });
+                }, 1000);
+            });
+
+            this.server = this.app.listen(this.port, () => {
+                // Open the default browser to the web app's authorization page (en is default)
+                const frontendUrl = process.env.VGEN_WEB_URL || 'https://veogent.com';
+                const authUrl = `${frontendUrl}/cli-auth?port=${this.port}&token=${this.cliToken}`;
+                
+                console.log('🔄 Opening browser for authentication...');
+                console.log(`\nIf your browser doesn't open automatically, click this link:\n=> ${authUrl}\n`);
+                
+                open(authUrl).catch(() => {
+                    console.log('⚠️ Could not open browser automatically.');
+                });
+            }).on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    console.error(`\n❌ Error: Port ${this.port} is already in use.`);
+                    reject(err);
+                }
+            });
+            
+            // Timeout after 5 minutes
+            setTimeout(() => {
+                this.stop();
+                reject(new Error('Authentication timeout.'));
+            }, 5 * 60 * 1000);
+        });
+    }
+
+    stop() {
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+    }
+}

package/.claude/worktrees/vigorous-hellman/config.js

@@ -0,0 +1,37 @@
+import fs from 'fs';
+import path from 'path';
+
+// Define the path for the config directory and file
+const configDir = path.join(process.env.HOME || process.env.USERPROFILE, '.vgen-cli');
+const configPath = path.join(configDir, 'config.json');
+
+// Get the current configuration
+export const getConfig = () => {
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    const data = fs.readFileSync(configPath, 'utf8');
+    return JSON.parse(data);
+};
+
+// Get the stored token
+export const getToken = () => {
+    const config = getConfig();
+    return config.token || null;
+};
+
+// Set and save the configuration
+export const setConfig = (newConfig) => {
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    const config = { ...getConfig(), ...newConfig };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+};
+
+// Clear the configuration
+export const clearConfig = () => {
+    if (fs.existsSync(configPath)) {
+        fs.unlinkSync(configPath);
+    }
+};

package/.claude/worktrees/vigorous-hellman/device-auth.js

@@ -0,0 +1,128 @@
+import axios from 'axios';
+
+const API_URL = process.env.VGEN_API_URL || 'https://api.veogent.com';
+
+export class DeviceAuthFlow {
+  constructor(options = {}) {
+    this.options = options;
+    this.http = axios.create({
+      baseURL: API_URL,
+      timeout: 15000,
+      validateStatus: () => true,
+    });
+  }
+
+  async start() {
+    const createResp = await this.http.post('/app/cli/device-code', {});
+    const payload = this.getSuccessData(createResp.data);
+
+    if (createResp.status < 200 || createResp.status >= 300 || !payload?.deviceCode) {
+      throw new Error(this.extractError(createResp.data) || 'Failed to initialize device authorization');
+    }
+
+    const {
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete,
+      expiresIn,
+      interval,
+    } = payload;
+
+    const deviceInfo = {
+      userCode,
+      verificationUri,
+      verificationUriComplete: verificationUriComplete || verificationUri,
+      expiresIn: Number(expiresIn) || 600,
+      interval: Number(interval) || 5,
+    };
+
+    if (typeof this.options.onDeviceCode === 'function') {
+      this.options.onDeviceCode(deviceInfo);
+    } else {
+      console.log('\n--- 🔐 VEOGENT CLI Device Login ---');
+      console.log(`1) Open this URL on any device/browser:\n   ${verificationUriComplete || verificationUri}`);
+      console.log(`2) Confirm the code: ${userCode}`);
+      console.log('3) Approve access, then return to this terminal.\n');
+    }
+
+    return await this.pollForToken({
+      deviceCode,
+      interval: Number(interval) || 5,
+      expiresIn: Number(expiresIn) || 600,
+    });
+  }
+
+  async pollForToken({ deviceCode, interval, expiresIn }) {
+    const deadline = Date.now() + expiresIn * 1000;
+    let pollInterval = Math.max(1, interval);
+
+    while (Date.now() < deadline) {
+      const resp = await this.http.post('/app/cli/device-token', { deviceCode });
+      const successData = this.getSuccessData(resp.data);
+
+      if (resp.status >= 200 && resp.status < 300 && successData?.access_token) {
+        return successData;
+      }
+
+      const errorCode = this.extractErrorCode(resp.data);
+
+      if (errorCode === 'authorization_pending') {
+        await this.sleep(pollInterval * 1000);
+        continue;
+      }
+
+      if (errorCode === 'slow_down') {
+        pollInterval += 2;
+        await this.sleep(pollInterval * 1000);
+        continue;
+      }
+
+      if (errorCode === 'expired_token') {
+        throw new Error('Device code expired. Please run `veogent login --device` again.');
+      }
+
+      if (errorCode === 'access_denied') {
+        throw new Error('Authorization was denied. Please run `veogent login --device` again.');
+      }
+
+      throw new Error(this.extractError(resp.data) || 'Device authorization failed');
+    }
+
+    throw new Error('Authentication timeout. Please run `veogent login --device` again.');
+  }
+
+  getSuccessData(body) {
+    if (body?.data?.data) return body.data.data;
+    if (body?.data) return body.data;
+    return body;
+  }
+
+  extractErrorCode(body) {
+    return (
+      body?.error?.code ||
+      body?.data?.error?.code ||
+      body?.errorCode ||
+      body?.data?.errorCode ||
+      body?.error?.message?.en ||
+      body?.data?.error?.message?.en ||
+      body?.error?.message ||
+      body?.message ||
+      ''
+    );
+  }
+
+  extractError(body) {
+    return (
+      body?.error?.message?.en ||
+      body?.data?.error?.message?.en ||
+      body?.error?.message ||
+      body?.message ||
+      null
+    );
+  }
+
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}