Harden the stable CLI release

Author: tzhangchi

CHANGELOG.md

@@ -7,6 +7,8 @@
 - Added independently configurable authentication and Comic API domains for local and isolated test environments.
 - Moved local API credentials into a dedicated mode-0600 credentials file with atomic writes.
 - Recognized the Comic API `PROCESSED` terminal status when waiting for generations.
+- Kept runtime version output in sync with package metadata and fixed execution through npm's symlinked binary.
+- Added strict option, range, failure-status, and zero-based page/panel validation against the official Comic SDK contract.
 - Added Comic API CLI commands with promptUrl for uploaded Word, PDF, or TXT script files.
 - Added Animation API CLI commands.
 - Added local config management, CI, tests, and npm packaging metadata.

CODEGEN_VERSION

@@ -1 +1 @@
-manual-0.1.0-beta.1
+manual-0.1.0

README.md

@@ -100,11 +100,13 @@ Inspect and continue a generation:
 llamagen comic get <generation_id>
 llamagen comic continue <generation_id> --prompt "Continue for four panels"
 llamagen comic update-panel <generation_id> \
-  --page 1 \
+  --page 0 \
   --panel 2 \
   --prompt "Move the camera closer to the hero"
 ```
 
+Page and panel indexes are zero-based, matching the Comic API and SDK.
+
 Check Comic API usage:
 
 ```bash
@@ -162,10 +164,10 @@ llamagen auth login [--no-browser] [--json]
 llamagen auth status [--offline] [--json]
 llamagen auth logout [--json]
 
-llamagen comic create --prompt <prompt> [--wait]
-llamagen comic get <generation_id>
-llamagen comic continue <generation_id> --prompt <prompt>
-llamagen comic update-panel <generation_id> --page <n> --panel <n> --prompt <prompt>
+llamagen comic create --prompt <prompt> [--fix-panel-num <1-20>] [--wait]
+llamagen comic get <generation_id> [--page <n>] [--panel <n>]
+llamagen comic continue <generation_id> --prompt <prompt> [--fix-panel-num <1-20>]
+llamagen comic update-panel <generation_id> [--page <n>] --panel <n> (--prompt <prompt> | --panel-prompt <prompt>)
 llamagen comic usage
 
 llamagen config set <site-url|api-url|api-key> <value>

bin/llamagen.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { main } from '../src/cli.js';
 
-export { main } from '../src/cli.js';
+export { main, VERSION } from '../src/cli.js';
 
 const isDirect =
   process.argv[1] &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+  fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 
 if (isDirect) {
   const code = await main();

package.json

@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/llamagen.js && node --check src/auth.js && node --check src/cli.js && node --check src/config.js && node --check src/errors.js && node --check src/http.js",
+    "lint": "node --check bin/llamagen.js && node --check src/auth.js && node --check src/cli.js && node --check src/config.js && node --check src/errors.js && node --check src/http.js && node --check src/version.js",
     "prepack": "npm run lint && npm test"
   },
   "keywords": [

src/auth.js

@@ -13,8 +13,8 @@ import {
 } from './config.js';
 import { CliError } from './errors.js';
 import { requestJson } from './http.js';
+import { VERSION } from './version.js';
 
-const VERSION = '0.1.0-beta.1';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 
 export async function runAuth(args, globals, env, io, runtime = {}) {
@@ -30,7 +30,7 @@ export async function runAuth(args, globals, env, io, runtime = {}) {
 }
 
 async function authLogin(args, globals, env, io, runtime) {
-  const options = parseAuthOptions(args);
+  const options = parseAuthOptions(args, new Set(['json', 'noBrowser', 'loginTimeoutMs']));
   const config = readConfig(env);
   const siteUrl = resolveSiteUrl(globals, env, config);
   const verifier = randomBytes(32).toString('base64url');
@@ -55,15 +55,16 @@ async function authLogin(args, globals, env, io, runtime) {
       headers: { 'user-agent': `llamagen-cli/${VERSION}` },
       timeoutMs: Number(globals.timeoutMs || 30000),
     });
-    if (!start?.authorizeUrl) {
+    const authorizeUrl = normalizeAuthorizeUrl(start?.authorizeUrl, siteUrl);
+    if (!authorizeUrl) {
       throw new CliError('LlamaGen did not return a browser authorization URL.', 1);
     }
 
     const progressOutput = options.json ? io.stderr : io.stdout;
-    progressOutput.write(`Opening ${start.authorizeUrl}\n`);
+    progressOutput.write(`Opening ${authorizeUrl}\n`);
     if (!options.noBrowser) {
       try {
-        await (runtime.openBrowser || openBrowser)(start.authorizeUrl);
+        await (runtime.openBrowser || openBrowser)(authorizeUrl);
       } catch {
         io.stderr.write('Could not open the browser automatically. Open the URL above manually.\n');
       }
@@ -139,7 +140,7 @@ async function authLogin(args, globals, env, io, runtime) {
 }
 
 async function authStatus(args, globals, env, io) {
-  const options = parseAuthOptions(args);
+  const options = parseAuthOptions(args, new Set(['json', 'offline']));
   const resolved = resolveCredential(globals, env);
   if (!resolved.apiToken) {
     const result = { authenticated: false, status: 'not_authenticated', source: 'none' };
@@ -182,7 +183,7 @@ async function authStatus(args, globals, env, io) {
 }
 
 function authLogout(args, env, io) {
-  const options = parseAuthOptions(args);
+  const options = parseAuthOptions(args, new Set(['json']));
   const removed = removeCredential(env);
   const environmentStillActive = Boolean(env.LLAMAGEN_API_KEY);
   const result = {
@@ -302,19 +303,46 @@ function openBrowser(url) {
   });
 }
 
-function parseAuthOptions(args) {
+function parseAuthOptions(args, allowed) {
   const options = {};
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === '--json') options.json = true;
-    else if (arg === '--offline') options.offline = true;
-    else if (arg === '--no-browser') options.noBrowser = true;
-    else if (arg === '--login-timeout-ms') options.loginTimeoutMs = args[++index];
+    let key;
+    if (arg === '--json') key = 'json';
+    else if (arg === '--offline') key = 'offline';
+    else if (arg === '--no-browser') key = 'noBrowser';
+    else if (arg === '--login-timeout-ms') key = 'loginTimeoutMs';
     else throw new CliError(`Unknown auth option: ${arg}`, 2);
+    if (!allowed.has(key)) throw new CliError(`Unsupported option for this auth command: ${arg}`, 2);
+    if (key === 'loginTimeoutMs') {
+      const value = args[++index];
+      options[key] = positiveInteger(value, arg);
+    } else {
+      options[key] = true;
+    }
   }
   return options;
 }
 
+function normalizeAuthorizeUrl(value, siteUrl) {
+  if (typeof value !== 'string') return null;
+  try {
+    const authorizeUrl = new URL(value);
+    if (authorizeUrl.origin !== new URL(siteUrl).origin) return null;
+    return authorizeUrl.toString();
+  } catch {
+    return null;
+  }
+}
+
+function positiveInteger(value, flag) {
+  const parsed = Number(value);
+  if (!value || !Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new CliError(`${flag} requires a positive integer.`, 2);
+  }
+  return parsed;
+}
+
 function printStatus(io, result, json) {
   if (json) {
     io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

src/cli.js

@@ -10,8 +10,21 @@ import {
 } from './config.js';
 import { runAuth, requestComicApi } from './auth.js';
 import { CliError } from './errors.js';
+import { VERSION } from './version.js';
 
-export const VERSION = '0.1.0-beta.1';
+export { VERSION } from './version.js';
+
+const SUPPORTED_COMIC_SIZES = new Set([
+  '1024x1024',
+  '512x768',
+  '512x1024',
+  '576x1024',
+  '768x1024',
+  '1024x768',
+  '768x512',
+  '1024x576',
+  '1024x512',
+]);
 
 export async function main(
   argv = process.argv.slice(2),
@@ -30,10 +43,10 @@ export async function main(
       io.stdout.write(`llamagen ${VERSION}\n`);
       return 0;
     }
-    if (command === 'auth') return runAuth(args, globals, env, io, runtime);
+    if (command === 'auth') return await runAuth(args, globals, env, io, runtime);
     if (command === 'config') return runConfig(args, env, io);
-    if (command === 'comic') return runComic(args, globals, env, io);
-    if (command === 'animation') return runAnimation(args, globals, env, io);
+    if (command === 'comic') return await runComic(args, globals, env, io);
+    if (command === 'animation') return await runAnimation(args, globals, env, io);
     throw new CliError(`Unknown command: ${command}`, 2);
   } catch (error) {
     const code = error instanceof CliError ? error.code : 1;
@@ -50,42 +63,77 @@ async function runComic(args, globals, env, io) {
   }
   if (subcommand === 'create') {
     const options = parseOptions(args);
+    assertAllowedOptions(options, [
+      'prompt', 'promptUrl', 'size', 'preset', 'style', 'language', 'fixPanelNum', 'wait',
+    ], 'comic create');
     requireOption(options, 'prompt');
+    const size = options.size || '1024x1024';
+    if (!SUPPORTED_COMIC_SIZES.has(size)) {
+      throw new CliError(`Unsupported comic size: ${size}`, 2);
+    }
     const body = compact({
       prompt: options.prompt,
       promptUrl: options.promptUrl,
-      size: options.size,
-      preset: options.preset,
+      size,
+      preset: options.preset || 'neutral',
       style: options.style,
       language: options.language,
-      fixPanelNum: numberOption(options.fixPanelNum),
+      fixPanelNum: integerOption(options.fixPanelNum, '--fix-panel-num', 1, 20),
     });
     const job = await apiRequest('POST', '/v1/comics/generations', body, globals, env);
-    if (options.wait) writeJson(io, await waitForComic(job.id, globals, env));
-    else writeJson(io, job);
+    if (options.wait) {
+      if (typeof job.id !== 'string' || !job.id) {
+        throw new CliError('Comic API did not return a generation ID.', 1);
+      }
+      const completed = await waitForComic(job.id, globals, env);
+      writeJson(io, completed);
+      if (isFailureStatus(completed.status)) {
+        io.stderr.write(`Comic generation ${job.id} ended with status ${completed.status}.\n`);
+        return 1;
+      }
+    } else writeJson(io, job);
     return 0;
   }
   if (subcommand === 'get') {
     const id = args.shift();
     if (!id) throw new CliError('Usage: llamagen comic get <generation_id>', 2);
-    writeJson(io, await apiRequest('GET', `/v1/comics/generations/${encodeURIComponent(id)}`, undefined, globals, env));
+    const options = parseOptions(args);
+    assertAllowedOptions(options, ['page', 'panel'], 'comic get');
+    const query = new URLSearchParams();
+    const page = integerOption(options.page, '--page', 0);
+    const panel = integerOption(options.panel, '--panel', 0);
+    if (page !== undefined) query.set('page', String(page));
+    if (panel !== undefined) query.set('panel', String(panel));
+    const suffix = query.size ? `?${query.toString()}` : '';
+    writeJson(io, await apiRequest('GET', `/v1/comics/generations/${encodeURIComponent(id)}${suffix}`, undefined, globals, env));
     return 0;
   }
   if (subcommand === 'continue') {
     const id = args.shift();
     if (!id) throw new CliError('Usage: llamagen comic continue <generation_id> --prompt <prompt>', 2);
     const options = parseOptions(args);
+    assertAllowedOptions(options, ['prompt', 'fixPanelNum'], 'comic continue');
     requireOption(options, 'prompt');
-    writeJson(io, await apiRequest('PATCH', `/v1/comics/generations/${encodeURIComponent(id)}`, { prompt: options.prompt, action: 'continueWrite' }, globals, env));
+    writeJson(io, await apiRequest('PATCH', `/v1/comics/generations/${encodeURIComponent(id)}`, compact({
+      prompt: options.prompt,
+      fixPanelNum: integerOption(options.fixPanelNum, '--fix-panel-num', 1, 20),
+      action: 'continueWrite',
+    }), globals, env));
     return 0;
   }
   if (subcommand === 'update-panel') {
     const id = args.shift();
     if (!id) throw new CliError('Usage: llamagen comic update-panel <generation_id> --page <n> --panel <n> --prompt <prompt>', 2);
     const options = parseOptions(args);
+    assertAllowedOptions(options, ['page', 'panel', 'prompt', 'panelPrompt'], 'comic update-panel');
+    const panel = integerOption(options.panel, '--panel', 0);
+    if (panel === undefined) throw new CliError('Missing required option --panel', 2);
+    if (!hasNonEmptyString(options.prompt) && !hasNonEmptyString(options.panelPrompt)) {
+      throw new CliError('Missing required option --prompt or --panel-prompt', 2);
+    }
     const body = compact({
-      page: numberOption(options.page),
-      panel: numberOption(options.panel),
+      page: integerOption(options.page, '--page', 0),
+      panel,
       prompt: options.prompt,
       panelPrompt: options.panelPrompt,
       action: 'regeneratePanel',
@@ -108,6 +156,7 @@ async function runAnimation(args, globals, env, io) {
   }
   if (subcommand === 'create') {
     const options = parseOptions(args);
+    assertAllowedOptions(options, ['prompt'], 'animation create');
     requireOption(options, 'prompt');
     writeJson(io, await apiRequest('POST', '/v1/artworks/generations', { prompt: options.prompt }, globals, env));
     return 0;
@@ -222,8 +271,8 @@ function parseGlobals(argv) {
     else if (arg === '--site-url') globals.siteUrl = requiredGlobalValue(argv, ++index, arg);
     else if (arg === '--api-url') globals.apiUrl = requiredGlobalValue(argv, ++index, arg);
     else if (arg === '--base-url') globals.baseUrl = requiredGlobalValue(argv, ++index, arg);
-    else if (arg === '--timeout-ms') globals.timeoutMs = requiredGlobalValue(argv, ++index, arg);
-    else if (arg === '--poll-interval-ms') globals.pollIntervalMs = requiredGlobalValue(argv, ++index, arg);
+    else if (arg === '--timeout-ms') globals.timeoutMs = integerOption(requiredGlobalValue(argv, ++index, arg), arg, 1);
+    else if (arg === '--poll-interval-ms') globals.pollIntervalMs = integerOption(requiredGlobalValue(argv, ++index, arg), arg, 1);
     else args.push(arg);
   }
   return { args, globals };
@@ -257,13 +306,35 @@ function requireOption(options, key) {
   }
 }
 
-function numberOption(value) {
-  if (value === undefined || value === true) return undefined;
+function integerOption(value, flag, min, max = Number.MAX_SAFE_INTEGER) {
+  if (value === undefined) return undefined;
+  if (value === true) {
+    throw new CliError(`${flag} requires a value.`, 2);
+  }
   const parsed = Number(value);
-  if (!Number.isFinite(parsed)) throw new CliError(`Expected numeric value, got ${value}`, 2);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    const range = max === Number.MAX_SAFE_INTEGER ? `${min} or greater` : `${min} to ${max}`;
+    throw new CliError(`${flag} must be an integer from ${range}.`, 2);
+  }
   return parsed;
 }
 
+function assertAllowedOptions(options, allowed, command) {
+  const allowedSet = new Set(allowed);
+  const unknown = Object.keys(options).find((key) => !allowedSet.has(key));
+  if (unknown) {
+    throw new CliError(`Unknown option for ${command}: --${kebabCase(unknown)}`, 2);
+  }
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isFailureStatus(status) {
+  return ['failed', 'canceled', 'cancelled'].includes(String(status).toLowerCase());
+}
+
 function compact(value) {
   return Object.fromEntries(
     Object.entries(value).filter(([, item]) => item !== undefined && item !== null && item !== false),
@@ -287,7 +358,7 @@ function helpText() {
 }
 
 function comicHelpText() {
-  return `Usage:\n  llamagen comic create --prompt <prompt> [--prompt-url <url>] [--size 1024x1024] [--wait]\n  llamagen comic get <generation_id>\n  llamagen comic continue <generation_id> --prompt <prompt>\n  llamagen comic update-panel <generation_id> --page <n> --panel <n> --prompt <prompt>\n  llamagen comic usage\n`;
+  return `Usage:\n  llamagen comic create --prompt <prompt> [--prompt-url <url>] [--size 1024x1024] [--fix-panel-num <1-20>] [--wait]\n  llamagen comic get <generation_id> [--page <n>] [--panel <n>]\n  llamagen comic continue <generation_id> --prompt <prompt> [--fix-panel-num <1-20>]\n  llamagen comic update-panel <generation_id> [--page <n>] --panel <n> (--prompt <prompt> | --panel-prompt <prompt>)\n  llamagen comic usage\n`;
 }
 
 function animationHelpText() {

src/version.js

@@ -0,0 +1,7 @@
+import fs from 'node:fs';
+
+const packageJson = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+);
+
+export const VERSION = packageJson.version;