@assethub/cli 0.1.3 → 0.1.5

package/README.md

@@ -6,11 +6,10 @@ Command line interface for AssetHub.
 export ASSETHUB_API_KEY=ah_live_xxx
 
 assethub models list
-assethub models list --domain meshGen --ids-only
 assethub files import https://example.com/input.png --media-type image
 assethub source create --file ./input.png --media-type image
 assethub image generate --prompt "stylized prop concept" --wait
-assethub mesh generate --file ./input.png --model-id meshGen.hunyuan31 --wait
+assethub mesh generate --file ./input.png --wait
 assethub jobs watch job_123 --download --out-dir ./out/job
 assethub parts split --file ./input.png --part-extractor "V1.5" --wait --all-ready --download --out-dir ./out/parts
 assethub parts compare --file ./input.png --preprocess-prompt "clean white background, centered product photo" --part-extractor "V1.5" --wait --all-ready
@@ -27,22 +26,41 @@ Agent-friendly login:
 ```sh
 printf '%s' "$ASSETHUB_API_KEY" | assethub auth login --api-key-stdin
 assethub image generate --prompt "small stylized game asset chest" --wait --download --out-dir ./out/image
-assethub mesh generate --source-url https://example.com/input.png --model-id meshGen.hunyuan31 --wait --download --out-dir ./out/mesh
+assethub mesh generate --source-url https://example.com/input.png --wait --download --out-dir ./out/mesh
 cat ./character.png | assethub parts split --stdin --file-name character.png --part-extractor "V1.5" --wait --all-ready --download --out-dir ./out/parts
+base64 -i ./character.png | assethub parts split --stdin-base64 --file-name character.png --content-type image/png --part-extractor "V1.5" --wait --all-ready
+printf '{"image_url":{"url":"data:image/png;base64,..."}}' | assethub parts split --stdin-json --part-extractor "V1.5" --wait --all-ready
+assethub parts split --clipboard --file-name character.png --part-extractor "V1.5" --wait --all-ready
 cat ./character.png | assethub parts compare --stdin --file-name character.png --preprocess-prompt "clean white background" --part-extractor "V1.5" --wait --all-ready
 ```
 
 Agent-oriented input:
 
 - `--file <path>` uploads a local image or mesh through the public file API.
-- `--stdin --file-name <name>` accepts piped bytes. Give a file name with an
-  extension when possible.
+- `--stdin --file-name <name>` accepts raw piped bytes. Give a file name with
+  an extension when possible.
+- `--stdin-base64 --file-name <name> --content-type <type>` accepts raw base64
+  from stdin. It also accepts a full `data:*;base64,...` value.
+- `--stdin-data-uri` accepts a data URI from stdin.
+- `--stdin-json` accepts common agent payload shapes from stdin, including
+  OpenAI-style `{"image_url":{"url":"..."}}`, Anthropic-style
+  `{"source":{"type":"base64","media_type":"image/png","data":"..."}}`,
+  `resourceId`, `fileRef`, `dataUri`, `base64`, `url`, and local `path`.
+- `--source-json <json|@file|@->` parses the same JSON shapes from an argument,
+  a file, or stdin.
 - `--data-uri <uri>` accepts `data:image/png;base64,...` style inputs and uploads
   them before running the target command.
+- `--clipboard` reads an image from the macOS clipboard for image inputs. It
+  uses `pngpaste` when available and falls back to the system clipboard bridge.
 - `--source-url`, `--source-id`/`--source-resource-id`, and `--file-ref-json`
   can be reused across image, mesh, and part extraction commands where the API
   supports them.
 
+For Codex or other AI agents, the important contract is: if the runtime can
+expose the attachment as bytes, base64, a data URI, a local path, an
+OpenAI/Anthropic-style JSON object, or a URL, the CLI can consume it directly.
+It does not require writing a temporary file first.
+
 Agent-oriented output:
 
 - stdout is one final JSON object.

package/dist/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 import { argv, env, exit, stdin, stderr, stdout } from 'node:process';
+import { promisify } from 'node:util';
 import { AssetHubApiError, createAssetHubClient, } from '@assethub/api-client';
 const defaultBaseUrl = 'https://app.assethub.io';
 const defaultImageModelId = 'imageGen.nanoBanana.pro.openrouter';
@@ -12,26 +14,32 @@ const defaultPartExtractorName = 'V1.5';
 const partExtractorOptions = [
     {
         publicName: 'Part Extractor V3',
+        apiValue: 'ah_part_extractor_v3',
         aliases: ['part extractor v3', 'v3'],
     },
     {
         publicName: 'V1',
+        apiValue: 'ah_part_extractor_v5',
         aliases: ['v1', '1'],
     },
     {
         publicName: 'V1.5 alpha',
+        apiValue: 'ah_part_extractor_v55',
         aliases: ['v1.5 alpha', 'v1.5-alpha', '1.5 alpha', '1.5-alpha'],
     },
     {
         publicName: 'V1.5',
+        apiValue: 'ah_part_extractor_v65',
         aliases: ['v1.5', '1.5', 'latest', 'default'],
     },
     {
         publicName: 'V2.0 alpha',
+        apiValue: 'ah_part_extractor_v20_alpha',
         aliases: ['v2.0 alpha', 'v2 alpha', 'v2.0-alpha', 'v2-alpha', '2.0 alpha'],
     },
     {
         publicName: 'V2.1 alpha',
+        apiValue: 'ah_part_extractor_v21_alpha',
         aliases: ['v2.1 alpha', 'v2.1-alpha', '2.1 alpha'],
     },
 ];
@@ -39,14 +47,16 @@ const partExtractorPublicNames = partExtractorOptions
     .map(option => option.publicName)
     .join(', ');
 const normalizePartExtractorName = (value) => value.trim().toLowerCase().replace(/\s+/g, ' ');
-const partExtractorPublicNameByInput = new Map(partExtractorOptions.flatMap(option => [
-    [normalizePartExtractorName(option.publicName), option.publicName],
+const partExtractorByInput = new Map(partExtractorOptions.flatMap(option => [
+    [normalizePartExtractorName(option.publicName), option],
     ...option.aliases.map(alias => [
         normalizePartExtractorName(alias),
-        option.publicName,
+        option,
     ]),
 ]));
+const partExtractorPublicNameByApiValue = new Map(partExtractorOptions.map(option => [option.apiValue, option.publicName]));
 const isInternalPartExtractorId = (value) => value.trim().includes('_');
+const execFileAsync = promisify(execFile);
 const usage = `AssetHub CLI
 
 Usage:
@@ -58,18 +68,18 @@ Usage:
   assethub models get <model-id>
   assethub files import <url> --media-type image|mesh
   assethub files upload <file> --media-type image|mesh
-  assethub source create (--file <path> | --source-url <url> | --source-id <id> | --stdin | --data-uri <uri>) --media-type image|mesh
-  assethub image generate --prompt <text> [--file <path> | --source-url <url> | --stdin | --data-uri <uri>] [--model-id <id>] [--batch-size <n>] [--wait] [--download --out-dir <dir>] [--api-version v1|v2]
+  assethub source create (--file <path> | --source-url <url> | --source-id <id> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri> | --clipboard) --media-type image|mesh [--file-name <name>] [--content-type <type>]
+  assethub image generate --prompt <text> [--file <path> | --source-url <url> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri> | --clipboard] [--file-name <name>] [--content-type <type>] [--model-id <id>] [--batch-size <n>] [--wait] [--download --out-dir <dir>] [--api-version v1|v2]
   assethub image generate --prompt <text> --source-resource-id <id> --api-version v2 [--model-id <id>] [--batch-size <n>] [--wait]
-  assethub mesh generate (--file <path> | --source-url <url> | --source-resource-id <id> | --file-ref-json <json> | --stdin | --data-uri <uri>) [--model-id <id>] [--name <name>] [--wait] [--download --out-dir <dir>]
-  assethub mesh retopo (--source-resource-id <id> | --source-url <url> | --file-ref-json <json> | --stdin | --data-uri <uri>) --model-id <id> [--wait] [--download --out-dir <dir>]
+  assethub mesh generate (--file <path> | --source-url <url> | --source-resource-id <id> | --file-ref-json <json> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri>) [--file-name <name>] [--content-type <type>] [--model-id <id>] [--name <name>] [--wait] [--download --out-dir <dir>]
+  assethub mesh retopo (--source-resource-id <id> | --source-url <url> | --file-ref-json <json> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri>) --model-id <id> [--file-name <name>] [--content-type <type>] [--wait] [--download --out-dir <dir>]
   assethub jobs get <job-id> [--download --out-dir <dir>]
   assethub jobs watch <job-id> [--interval-ms <ms>] [--timeout-ms <ms>] [--download --out-dir <dir>]
-  assethub production analyze (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --data-uri <uri>) [--part-extractor <name>] [--name <name>] [--wait] [--download --out-dir <dir>]
+  assethub production analyze (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri> | --clipboard) [--file-name <name>] [--content-type <type>] [--part-extractor <name>] [--name <name>] [--wait] [--download --out-dir <dir>]
   assethub production status <order-id> [--wait] [--download --out-dir <dir>]
   assethub production execute --order-id <id> --mission-id <id> --task-id <id> [--task-id <id>...] [--part-extractor <name>] [--part-extraction-mode fast|high_quality] [--wait] [--download --out-dir <dir>]
-  assethub parts split (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --data-uri <uri> | --order-id <id>) [--part-extractor <name>] [--wait] [--task-id <id>...] [--mission-id <id>] [--all-ready] [--download --out-dir <dir>]
-  assethub parts compare (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --data-uri <uri>) [--preprocess-prompt <text>] [--preprocess-model-id <id>] [--fail-on-preprocess-error] [--part-extractor <name>] [--wait] [--task-id <id>...] [--mission-id <id>] [--all-ready] [--download --out-dir <dir>]
+  assethub parts split (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri> | --clipboard | --order-id <id>) [--file-name <name>] [--content-type <type>] [--part-extractor <name>] [--wait] [--task-id <id>...] [--mission-id <id>] [--all-ready] [--download --out-dir <dir>]
+  assethub parts compare (--file <path> | --source-url <url> | --source-id <id> | --image-url <url> | --file-ref-json <json> | --stdin | --stdin-base64 | --stdin-data-uri | --stdin-json | --source-json <json|@file|@-> | --data-uri <uri> | --clipboard) [--file-name <name>] [--content-type <type>] [--preprocess-prompt <text>] [--preprocess-model-id <id>] [--fail-on-preprocess-error] [--part-extractor <name>] [--wait] [--task-id <id>...] [--mission-id <id>] [--all-ready] [--download --out-dir <dir>]
 
 Global options:
   --api-key <key>       Overrides saved auth and ASSETHUB_API_KEY.
@@ -81,12 +91,16 @@ Global options:
 Examples:
   ASSETHUB_API_KEY=ah_live_xxx assethub models list
   assethub auth login --api-key-stdin
-  assethub models list --domain meshGen --ids-only
+  assethub models list --ids-only
   assethub files upload ./input.png --media-type image
   assethub source create --file ./input.png --media-type image
+  pbpaste | assethub source create --stdin-data-uri --media-type image
+  assethub source create --clipboard --media-type image --file-name clipboard.png
+  printf '{"image_url":{"url":"data:image/png;base64,..."}}' | assethub parts split --stdin-json --part-extractor "V1.5" --wait
+  base64 -i ./input.png | assethub parts split --stdin-base64 --file-name input.png --content-type image/png --part-extractor "V1.5" --wait
   cat ./input.png | assethub parts split --stdin --file-name input.png --part-extractor "V1.5" --wait
   assethub image generate --prompt "stylized prop concept" --wait
-  assethub mesh generate --file ./input.png --model-id meshGen.hunyuan31 --wait
+  assethub mesh generate --file ./input.png --wait
   assethub production analyze --file ./input.png --part-extractor "V1.5" --wait
   assethub parts split --file ./input.png --part-extractor "V1.5" --wait --all-ready
   assethub parts compare --file ./input.png --preprocess-prompt "clean white background, centered product photo" --part-extractor "V1.5" --wait --all-ready
@@ -166,18 +180,29 @@ const resolvePartExtractorPublicName = (value) => {
     if (isInternalPartExtractorId(value)) {
         throw new Error(`Internal part extractor IDs are not accepted by the public CLI. Use one of: ${partExtractorPublicNames}.`);
     }
-    const publicName = partExtractorPublicNameByInput.get(normalizePartExtractorName(value));
-    if (publicName == null) {
+    const option = partExtractorByInput.get(normalizePartExtractorName(value));
+    if (option == null) {
         throw new Error(`Unknown part extractor: ${value}. Use one of: ${partExtractorPublicNames}.`);
     }
-    return publicName;
+    return option.publicName;
 };
-const resolvePartExtractorForAnalyze = (flags) => resolvePartExtractorPublicName(getPartExtractorFlag(flags) ?? defaultPartExtractorName);
+const resolvePartExtractorApiValue = (value) => {
+    if (isInternalPartExtractorId(value)) {
+        throw new Error(`Internal part extractor IDs are not accepted by the public CLI. Use one of: ${partExtractorPublicNames}.`);
+    }
+    const option = partExtractorByInput.get(normalizePartExtractorName(value));
+    if (option == null) {
+        throw new Error(`Unknown part extractor: ${value}. Use one of: ${partExtractorPublicNames}.`);
+    }
+    return option.apiValue;
+};
+const resolvePartExtractorForAnalyze = (flags) => resolvePartExtractorApiValue(getPartExtractorFlag(flags) ?? defaultPartExtractorName);
 const publicPartExtractorName = (value) => {
     if (value == null) {
         return null;
     }
-    return (isInternalPartExtractorId(value) ? 'Unknown' : value);
+    return (partExtractorPublicNameByApiValue.get(value) ??
+        (isInternalPartExtractorId(value) ? 'Unknown' : value));
 };
 const sanitizeProductionOutput = (value) => {
     if (Array.isArray(value)) {
@@ -327,31 +352,73 @@ const createContext = async (flags) => {
         }),
     };
 };
+const isRecord = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+const isBlobLocation = (value) => {
+    if (!isRecord(value) || typeof value.type !== 'string') {
+        return false;
+    }
+    if (value.type === 'supabase' &&
+        typeof value.bucket === 'string' &&
+        typeof value.path === 'string') {
+        return true;
+    }
+    if (value.type === 'signedSupabase' &&
+        typeof value.signedUrl === 'string') {
+        return true;
+    }
+    if (value.type === 'asset' && typeof value.assetId === 'string') {
+        return true;
+    }
+    return false;
+};
 const parseFileRef = (value) => {
     const parsed = JSON.parse(value);
-    if (parsed == null || typeof parsed !== 'object' || !('type' in parsed)) {
+    if (!isBlobLocation(parsed)) {
         throw new Error('--file-ref-json must be a BlobLocation JSON object');
     }
     return parsed;
 };
-const readBlob = async (filePath) => {
-    const buffer = await readFile(filePath);
-    return new Blob([new Uint8Array(buffer)]);
+const blobFromBuffer = (buffer, type) => {
+    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    return new Blob([arrayBuffer], type == null ? undefined : { type });
 };
-const blobFromDataUri = (value) => {
-    const match = value.match(/^data:([^;,]+)?(;base64)?,(.*)$/s);
+const readBlob = async (filePath, type) => blobFromBuffer(await readFile(filePath), type);
+const getContentTypeFlag = (flags) => getFlag(flags, 'content-type') ?? getFlag(flags, 'mime-type');
+const blobFromDataUri = (value, flagName = '--data-uri') => {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^data:([^;,]+)?(;base64)?,(.*)$/s);
     if (match == null) {
-        throw new Error('--data-uri must be a valid data URI.');
+        throw new Error(`${flagName} must be a valid data URI.`);
     }
     const contentType = match[1] === '' ? undefined : match[1];
     const isBase64 = match[2] != null;
-    const payload = match[3] ?? '';
+    const payload = (match[3] ?? '').replace(/\s+/g, '');
     const buffer = isBase64
         ? Buffer.from(payload, 'base64')
         : Buffer.from(decodeURIComponent(payload), 'utf8');
-    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
     return {
-        blob: new Blob([arrayBuffer], contentType == null ? undefined : { type: contentType }),
+        blob: blobFromBuffer(buffer, contentType),
+        contentType,
+    };
+};
+const blobFromBase64 = (value, contentType, flagName) => {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('data:')) {
+        return blobFromDataUri(trimmed, flagName);
+    }
+    const normalized = trimmed.replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/');
+    if (normalized === '') {
+        throw new Error(`${flagName} input is empty.`);
+    }
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) {
+        throw new Error(`${flagName} must contain base64 data or a data URI.`);
+    }
+    const buffer = Buffer.from(normalized, 'base64');
+    if (buffer.byteLength === 0) {
+        throw new Error(`${flagName} did not decode to any bytes.`);
+    }
+    return {
+        blob: blobFromBuffer(buffer, contentType),
         contentType,
     };
 };
@@ -376,54 +443,392 @@ const ensureFileNameExtension = (fileName, mediaType, mimeType) => {
     }
     return `${fileName}.${extensionFromMimeType(mimeType, mediaType)}`;
 };
+const missingSourceMessage = 'Missing source. Pass --file, --source-url, --source-resource-id, --source-id, --file-ref-json, --stdin, --stdin-base64, --stdin-data-uri, --stdin-json, --source-json, --data-uri, or --clipboard.';
+const exactlyOneSourceMessage = 'Pass exactly one source input: --file, --source-url/--image-url, --source-id/--source-resource-id, --file-ref-json, --stdin, --stdin-base64, --stdin-data-uri, --stdin-json, --source-json, --data-uri, or --clipboard.';
+const getSourceUrlFlag = (flags) => getFlag(flags, 'source-url') ?? getFlag(flags, 'image-url') ?? getFlag(flags, 'url');
+const assertFlagHasValue = (value, flagDescription) => {
+    if (value === 'true' || value.trim() === '') {
+        throw new Error(`Missing required flag value: ${flagDescription}`);
+    }
+    return value;
+};
+const sourceInputCount = (flags) => [
+    getSourceResourceIdFlag(flags) != null,
+    getSourceUrlFlag(flags) != null,
+    getFlag(flags, 'file-ref-json') != null,
+    getFlag(flags, 'file') != null,
+    getFlag(flags, 'data-uri') != null,
+    hasFlag(flags, 'stdin'),
+    hasFlag(flags, 'stdin-base64'),
+    hasFlag(flags, 'stdin-data-uri'),
+    hasFlag(flags, 'stdin-json'),
+    getFlag(flags, 'source-json') != null,
+    hasFlag(flags, 'clipboard'),
+].filter(Boolean).length;
+const sourceFromString = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed.startsWith('data:')) {
+        return undefined;
+    }
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            return { url: trimmed };
+        }
+    }
+    catch {
+        // Ignore non-URL strings.
+    }
+    return undefined;
+};
+const getFirstString = (record, keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim() !== '') {
+            return value;
+        }
+    }
+    return undefined;
+};
+const stringFromJsonImageUrl = (value) => {
+    if (typeof value === 'string' && value.trim() !== '') {
+        return value;
+    }
+    if (isRecord(value)) {
+        return getFirstString(value, ['url']);
+    }
+    return undefined;
+};
+const descriptorFromDataUri = (value, mediaType, fileName, flagName) => {
+    const { blob, contentType } = blobFromDataUri(value, flagName);
+    return {
+        kind: 'blob',
+        blob,
+        fileName: ensureFileNameExtension(fileName, mediaType, contentType),
+        contentType,
+    };
+};
+const descriptorFromBase64 = ({ value, contentType, fileName, mediaType, flagName, }) => {
+    const decoded = blobFromBase64(value, contentType, flagName);
+    return {
+        kind: 'blob',
+        blob: decoded.blob,
+        fileName: ensureFileNameExtension(fileName, mediaType, decoded.contentType),
+        contentType: decoded.contentType,
+    };
+};
+const sourceDescriptorFromJson = (value, options) => {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '') {
+            return undefined;
+        }
+        if (trimmed.startsWith('data:')) {
+            return descriptorFromDataUri(trimmed, options.mediaType, options.fallbackFileName, '--source-json');
+        }
+        const source = sourceFromString(trimmed);
+        return source == null ? undefined : { kind: 'source', source };
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = sourceDescriptorFromJson(item, options);
+            if (found != null) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const nestedSource = value.source;
+    if (nestedSource != null) {
+        const found = sourceDescriptorFromJson(nestedSource, options);
+        if (found != null) {
+            return found;
+        }
+    }
+    const imageUrl = stringFromJsonImageUrl(value.image_url ?? value.imageUrl);
+    if (imageUrl != null) {
+        if (imageUrl.trim().startsWith('data:')) {
+            return descriptorFromDataUri(imageUrl, options.mediaType, options.fallbackFileName, '--source-json');
+        }
+        return { kind: 'source', source: { url: imageUrl } };
+    }
+    const resourceId = getFirstString(value, [
+        'resourceId',
+        'resource_id',
+        'sourceResourceId',
+        'source_resource_id',
+        'sourceId',
+        'source_id',
+        'imageAssetId',
+        'image_asset_id',
+        'assetId',
+        'asset_id',
+    ]);
+    if (resourceId != null) {
+        return { kind: 'source', source: { resourceId } };
+    }
+    const fileRefValue = value.fileRef ?? value.file_ref ?? value.imageBlobLocation ?? value.image_blob_location ?? value.blobLocation ?? value.blob_location;
+    if (isBlobLocation(fileRefValue)) {
+        return { kind: 'source', source: { fileRef: fileRefValue } };
+    }
+    const dataUri = getFirstString(value, ['dataUri', 'data_uri']);
+    if (dataUri != null) {
+        return descriptorFromDataUri(dataUri, options.mediaType, getFirstString(value, ['fileName', 'file_name', 'name']) ??
+            options.fallbackFileName, '--source-json');
+    }
+    const contentType = getFirstString(value, [
+        'contentType',
+        'content_type',
+        'mimeType',
+        'mime_type',
+        'media_type',
+    ]);
+    const base64Value = getFirstString(value, ['base64', 'data', 'content']);
+    if (base64Value != null && (value.type === 'base64' || contentType != null)) {
+        return descriptorFromBase64({
+            value: base64Value,
+            contentType,
+            fileName: getFirstString(value, ['fileName', 'file_name', 'name']) ??
+                options.fallbackFileName,
+            mediaType: options.mediaType,
+            flagName: '--source-json',
+        });
+    }
+    const url = getFirstString(value, ['sourceUrl', 'source_url', 'url', 'publicUrl', 'public_url']);
+    if (url != null) {
+        const source = sourceFromString(url);
+        if (source != null) {
+            return { kind: 'source', source };
+        }
+    }
+    const path = getFirstString(value, ['path', 'file', 'filePath', 'file_path']);
+    if (path != null) {
+        return { kind: 'file', path };
+    }
+    const preferredKeys = [
+        'input',
+        'image',
+        'asset',
+        'file',
+        'message',
+        'messages',
+        'content',
+        'attachments',
+    ];
+    for (const key of preferredKeys) {
+        const found = sourceDescriptorFromJson(value[key], options);
+        if (found != null) {
+            return found;
+        }
+    }
+    for (const entry of Object.values(value)) {
+        const found = sourceDescriptorFromJson(entry, options);
+        if (found != null) {
+            return found;
+        }
+    }
+    return undefined;
+};
+const parseJsonValue = (raw, sourceName) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${sourceName} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const readSourceJsonFlag = async (flags) => {
+    const value = getFlag(flags, 'source-json');
+    if (value == null || value === 'true' || value.trim() === '') {
+        throw new Error('Missing required flag value: --source-json <json|@file|@->');
+    }
+    if (value === '@-' || value === '-') {
+        return await readStdin();
+    }
+    if (value.startsWith('@')) {
+        return await readFile(value.slice(1), 'utf8');
+    }
+    return value;
+};
+const readClipboardImage = async () => {
+    const filePath = join(tmpdir(), `assethub-clipboard-${process.pid}-${Date.now()}.png`);
+    const readTempFile = async () => await readBlob(filePath, 'image/png');
+    try {
+        await execFileAsync('pngpaste', [filePath], { timeout: 10000 });
+        return await readTempFile();
+    }
+    catch (pngpasteError) {
+        const quoteAppleScriptString = (value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+        const pngClass = `${String.fromCharCode(0x00ab)}class PNGf${String.fromCharCode(0x00bb)}`;
+        const script = [
+            `set outPath to ${quoteAppleScriptString(filePath)}`,
+            `set pngData to the clipboard as ${pngClass}`,
+            'set fileRef to open for access (POSIX file outPath) with write permission',
+            'try',
+            'set eof fileRef to 0',
+            'write pngData to fileRef',
+            'close access fileRef',
+            'on error errMsg',
+            'try',
+            'close access fileRef',
+            'end try',
+            'error errMsg',
+            'end try',
+        ].join('\n');
+        try {
+            await execFileAsync('osascript', ['-e', script], { timeout: 10000 });
+            return await readTempFile();
+        }
+        catch (osascriptError) {
+            const details = osascriptError instanceof Error
+                ? osascriptError.message
+                : pngpasteError instanceof Error
+                    ? pngpasteError.message
+                    : 'unknown error';
+            throw new Error(`Could not read an image from the clipboard. Copy an image, install pngpaste, or pass bytes through --stdin/--stdin-base64/--stdin-json. Details: ${details}`);
+        }
+    }
+    finally {
+        await unlink(filePath).catch(() => undefined);
+    }
+};
+const uploadSourceDescriptor = async ({ descriptor, client, mediaType, }) => {
+    if (descriptor.kind === 'source') {
+        return descriptor.source;
+    }
+    const file = descriptor.kind === 'file'
+        ? await readBlob(descriptor.path, descriptor.contentType)
+        : descriptor.blob;
+    const fileName = descriptor.kind === 'file'
+        ? basename(descriptor.path)
+        : descriptor.fileName;
+    const upload = await client.v2.uploadFile({
+        file,
+        fileName: ensureFileNameExtension(fileName, mediaType, descriptor.contentType),
+        mediaType,
+    });
+    return { fileRef: upload.fileRef };
+};
 const resolveSource = async ({ flags, client, fileMediaType, }) => {
+    const providedCount = sourceInputCount(flags);
+    if (providedCount === 0) {
+        return undefined;
+    }
+    if (providedCount > 1) {
+        throw new Error(exactlyOneSourceMessage);
+    }
     const sourceResourceId = getSourceResourceIdFlag(flags);
     if (sourceResourceId != null) {
-        return { resourceId: sourceResourceId };
+        return {
+            resourceId: assertFlagHasValue(sourceResourceId, '--source-id/--source-resource-id <id>'),
+        };
     }
-    const sourceUrl = getFlag(flags, 'source-url');
+    const sourceUrl = getSourceUrlFlag(flags);
     if (sourceUrl != null) {
-        return { url: sourceUrl };
+        return {
+            url: assertFlagHasValue(sourceUrl, '--source-url/--image-url <url>'),
+        };
     }
     const fileRefJson = getFlag(flags, 'file-ref-json');
     if (fileRefJson != null) {
-        return { fileRef: parseFileRef(fileRefJson) };
+        return {
+            fileRef: parseFileRef(assertFlagHasValue(fileRefJson, '--file-ref-json <json>')),
+        };
     }
     const filePath = getFlag(flags, 'file');
     if (filePath != null) {
-        const fileRef = await client.v2.uploadFile({
-            file: await readBlob(filePath),
-            fileName: basename(filePath),
+        return await uploadSourceDescriptor({
+            descriptor: { kind: 'file', path: assertFlagHasValue(filePath, '--file <path>') },
+            client,
             mediaType: fileMediaType,
         });
-        return { fileRef: fileRef.fileRef };
     }
     const dataUri = getFlag(flags, 'data-uri');
     if (dataUri != null) {
-        const { blob, contentType } = blobFromDataUri(dataUri);
-        const fileName = ensureFileNameExtension(getFlag(flags, 'file-name') ?? 'data-uri', fileMediaType, contentType);
-        const fileRef = await client.v2.uploadFile({
-            file: blob,
-            fileName,
+        return await uploadSourceDescriptor({
+            descriptor: descriptorFromDataUri(assertFlagHasValue(dataUri, '--data-uri <uri>'), fileMediaType, getFlag(flags, 'file-name') ?? 'data-uri', '--data-uri'),
+            client,
+            mediaType: fileMediaType,
+        });
+    }
+    if (getFlag(flags, 'source-json') != null) {
+        const parsed = parseJsonValue(await readSourceJsonFlag(flags), '--source-json');
+        const descriptor = sourceDescriptorFromJson(parsed, {
+            mediaType: fileMediaType,
+            fallbackFileName: getFlag(flags, 'file-name') ?? defaultFileNameForMediaType(fileMediaType),
+        });
+        if (descriptor == null) {
+            throw new Error('--source-json did not contain a usable source. Expected url, image_url.url, resourceId, fileRef, data URI, base64 data, or path.');
+        }
+        return await uploadSourceDescriptor({ descriptor, client, mediaType: fileMediaType });
+    }
+    if (hasFlag(flags, 'stdin-json')) {
+        const parsed = parseJsonValue(await readStdin(), '--stdin-json');
+        const descriptor = sourceDescriptorFromJson(parsed, {
+            mediaType: fileMediaType,
+            fallbackFileName: getFlag(flags, 'file-name') ?? defaultFileNameForMediaType(fileMediaType),
+        });
+        if (descriptor == null) {
+            throw new Error('--stdin-json did not contain a usable source. Expected url, image_url.url, resourceId, fileRef, data URI, base64 data, or path.');
+        }
+        return await uploadSourceDescriptor({ descriptor, client, mediaType: fileMediaType });
+    }
+    if (hasFlag(flags, 'stdin-data-uri')) {
+        return await uploadSourceDescriptor({
+            descriptor: descriptorFromDataUri(await readStdin(), fileMediaType, getFlag(flags, 'file-name') ?? 'stdin-data-uri', '--stdin-data-uri'),
+            client,
+            mediaType: fileMediaType,
+        });
+    }
+    if (hasFlag(flags, 'stdin-base64')) {
+        return await uploadSourceDescriptor({
+            descriptor: descriptorFromBase64({
+                value: await readStdin(),
+                contentType: getContentTypeFlag(flags),
+                fileName: getFlag(flags, 'file-name') ?? defaultFileNameForMediaType(fileMediaType),
+                mediaType: fileMediaType,
+                flagName: '--stdin-base64',
+            }),
+            client,
+            mediaType: fileMediaType,
+        });
+    }
+    if (hasFlag(flags, 'clipboard')) {
+        if (fileMediaType !== 'image') {
+            throw new Error('--clipboard is only supported for image inputs.');
+        }
+        return await uploadSourceDescriptor({
+            descriptor: {
+                kind: 'blob',
+                blob: await readClipboardImage(),
+                fileName: ensureFileNameExtension(getFlag(flags, 'file-name') ?? 'clipboard.png', fileMediaType, 'image/png'),
+                contentType: 'image/png',
+            },
+            client,
             mediaType: fileMediaType,
         });
-        return { fileRef: fileRef.fileRef };
     }
     if (hasFlag(flags, 'stdin')) {
-        const fileName = ensureFileNameExtension(getFlag(flags, 'file-name') ?? defaultFileNameForMediaType(fileMediaType), fileMediaType);
-        const fileRef = await client.v2.uploadFile({
-            file: await readStdinBlob(),
-            fileName,
+        return await uploadSourceDescriptor({
+            descriptor: {
+                kind: 'blob',
+                blob: await readStdinBlob(getContentTypeFlag(flags)),
+                fileName: ensureFileNameExtension(getFlag(flags, 'file-name') ?? defaultFileNameForMediaType(fileMediaType), fileMediaType, getContentTypeFlag(flags)),
+                contentType: getContentTypeFlag(flags),
+            },
+            client,
             mediaType: fileMediaType,
         });
-        return { fileRef: fileRef.fileRef };
     }
     return undefined;
 };
 const requireSource = async (options) => {
     const source = await resolveSource(options);
     if (source == null) {
-        throw new Error('Missing source. Pass --file, --source-url, --source-resource-id, --source-id, --file-ref-json, --stdin, or --data-uri.');
+        throw new Error(missingSourceMessage);
     }
     return source;
 };
@@ -440,10 +845,6 @@ const sourceToV1ImageInput = (source) => {
     throw new Error('v1 image generation does not accept source-resource-id. Use --source-url, --file, or --api-version v2.');
 };
 const resolveProductionAnalyzeSource = async (ctx) => {
-    const imageUrl = getFlag(ctx.flags, 'image-url');
-    if (imageUrl != null) {
-        return { imageUrl };
-    }
     const source = await requireSource({
         flags: ctx.flags,
         client: ctx.client,
@@ -456,7 +857,7 @@ const resolveProductionAnalyzeSource = async (ctx) => {
         return { imageUrl: source.url };
     }
     if (source.fileRef == null) {
-        throw new Error('Missing source. Pass --file, --source-url, --source-id, --file-ref-json, --stdin, or --data-uri.');
+        throw new Error(missingSourceMessage);
     }
     return { imageBlobLocation: source.fileRef };
 };
@@ -522,54 +923,20 @@ const commandSource = async (subcommand, ctx) => {
         throw new Error('Unknown source command. Use "source create".');
     }
     const mediaType = parseMediaType(requireFlag(ctx.flags, 'media-type'));
-    const sourceUrl = getFlag(ctx.flags, 'source-url') ?? getFlag(ctx.flags, 'image-url');
-    const sourceResourceId = getSourceResourceIdFlag(ctx.flags);
-    const filePath = getFlag(ctx.flags, 'file');
-    const useStdin = hasFlag(ctx.flags, 'stdin');
-    const dataUri = getFlag(ctx.flags, 'data-uri');
-    const provided = [
-        sourceUrl != null,
-        sourceResourceId != null,
-        filePath != null,
-        useStdin,
-        dataUri != null,
-    ].filter(Boolean);
-    if (provided.length !== 1) {
-        throw new Error('Pass exactly one source input: --file, --source-url, --source-id, --source-resource-id, --stdin, or --data-uri.');
-    }
-    if (sourceUrl != null) {
-        print({ source: { url: sourceUrl }, url: sourceUrl, mediaType });
+    const source = await requireSource({
+        flags: ctx.flags,
+        client: ctx.client,
+        fileMediaType: mediaType,
+    });
+    if (source.url != null) {
+        print({ source, url: source.url, mediaType });
         return;
     }
-    if (sourceResourceId != null) {
-        print({
-            source: { resourceId: sourceResourceId },
-            resourceId: sourceResourceId,
-            mediaType,
-        });
+    if (source.resourceId != null) {
+        print({ source, resourceId: source.resourceId, mediaType });
         return;
     }
-    const upload = filePath != null
-        ? await ctx.client.v2.uploadFile({
-            file: await readBlob(filePath),
-            fileName: basename(filePath),
-            mediaType,
-        })
-        : dataUri != null
-            ? await (async () => {
-                const { blob, contentType } = blobFromDataUri(dataUri);
-                return await ctx.client.v2.uploadFile({
-                    file: blob,
-                    fileName: ensureFileNameExtension(getFlag(ctx.flags, 'file-name') ?? 'data-uri', mediaType, contentType),
-                    mediaType,
-                });
-            })()
-            : await ctx.client.v2.uploadFile({
-                file: await readStdinBlob(),
-                fileName: ensureFileNameExtension(getFlag(ctx.flags, 'file-name') ?? defaultFileNameForMediaType(mediaType), mediaType),
-                mediaType,
-            });
-    print({ source: { fileRef: upload.fileRef }, fileRef: upload.fileRef, mediaType });
+    print({ source, fileRef: source.fileRef, mediaType });
 };
 const commandModels = async (subcommand, positionals, ctx) => {
     if (subcommand === 'list') {
@@ -782,11 +1149,12 @@ const resolvePartExtractorFromMission = async (ctx, orderId, missionId) => {
         throw new Error('Could not infer the part extractor from the mission. Pass --part-extractor with one of: ' +
             partExtractorPublicNames);
     }
-    if (isInternalPartExtractorId(mission.agentVersion)) {
+    const publicName = publicPartExtractorName(mission.agentVersion);
+    if (publicName == null || publicName === 'Unknown') {
         throw new Error('Could not infer the public part extractor from the mission. Pass --part-extractor with one of: ' +
             partExtractorPublicNames);
     }
-    return resolvePartExtractorPublicName(mission.agentVersion);
+    return resolvePartExtractorApiValue(publicName);
 };
 const redactUrl = (value) => {
     try {
@@ -1095,7 +1463,7 @@ const commandProduction = async (subcommand, positionals, ctx) => {
         const partExtractorFlag = getPartExtractorFlag(ctx.flags);
         const agentVersion = partExtractorFlag == null
             ? await resolvePartExtractorFromMission(ctx, orderId, missionId)
-            : resolvePartExtractorPublicName(partExtractorFlag);
+            : resolvePartExtractorApiValue(partExtractorFlag);
         const executed = await ctx.client.v1.executeProduction({
             orderId,
             missionId,
@@ -1118,6 +1486,9 @@ const commandProduction = async (subcommand, positionals, ctx) => {
 const commandParts = async (subcommand, ctx) => {
     const runPartSplit = async (source) => {
         let orderId = source == null ? getFlag(ctx.flags, 'order-id') : undefined;
+        if (orderId != null) {
+            orderId = assertFlagHasValue(orderId, '--order-id <id>');
+        }
         let analyzed;
         let status;
         if (orderId == null) {
@@ -1163,7 +1534,7 @@ const commandParts = async (subcommand, ctx) => {
             const partExtractorFlag = getPartExtractorFlag(ctx.flags);
             const agentVersion = partExtractorFlag == null
                 ? await resolvePartExtractorFromMission(ctx, orderId, missionId)
-                : resolvePartExtractorPublicName(partExtractorFlag);
+                : resolvePartExtractorApiValue(partExtractorFlag);
             const partExtractionMode = getFlag(ctx.flags, 'part-extraction-mode');
             if (partExtractionMode != null &&
                 partExtractionMode !== 'fast' &&
@@ -1193,12 +1564,15 @@ const commandParts = async (subcommand, ctx) => {
         });
     };
     if (subcommand === 'split') {
+        if (getFlag(ctx.flags, 'order-id') != null && sourceInputCount(ctx.flags) > 0) {
+            throw new Error('Pass either --order-id or one image source, not both.');
+        }
         print(await withOptionalDownloads(ctx.flags, await runPartSplit()));
         return;
     }
     if (subcommand === 'compare') {
         if (getFlag(ctx.flags, 'order-id') != null) {
-            throw new Error('parts compare requires an image source. Use --file, --source-url, --source-id, --image-url, --file-ref-json, --stdin, or --data-uri.');
+            throw new Error('parts compare requires an image source. Use --file, --source-url, --source-id, --image-url, --file-ref-json, --stdin, --stdin-base64, --stdin-data-uri, --stdin-json, --source-json, --data-uri, or --clipboard.');
         }
         const preprocessPrompt = getFlag(ctx.flags, 'preprocess-prompt');
         if (preprocessPrompt === 'true') {
@@ -1210,17 +1584,15 @@ const commandParts = async (subcommand, ctx) => {
         if (preprocessPrompt != null && getFlag(ctx.flags, 'mission-id') != null) {
             throw new Error('parts compare preprocessing creates a second order. Omit --mission-id and let the CLI infer it.');
         }
-        const imageUrlFlag = getFlag(ctx.flags, 'image-url');
-        if (imageUrlFlag === 'true') {
-            throw new Error('Missing required flag value: --image-url <url>');
+        const preprocessModelId = getFlag(ctx.flags, 'preprocess-model-id');
+        if (preprocessModelId === 'true') {
+            throw new Error('Missing required flag value: --preprocess-model-id <id>');
         }
-        const inputSource = imageUrlFlag == null
-            ? productionAnalyzeSourceFromSource(await requireSource({
-                flags: ctx.flags,
-                client: ctx.client,
-                fileMediaType: 'image',
-            }))
-            : { imageUrl: imageUrlFlag };
+        const inputSource = productionAnalyzeSourceFromSource(await requireSource({
+            flags: ctx.flags,
+            client: ctx.client,
+            fileMediaType: 'image',
+        }));
         const direct = await runPartSplit(inputSource);
         let preprocessed = null;
         if (preprocessPrompt != null && preprocessPrompt !== 'true') {
@@ -1228,7 +1600,7 @@ const commandParts = async (subcommand, ctx) => {
                 const queued = await ctx.client.v2.generateImage({
                     source: sourceFromProductionAnalyzeSource(inputSource),
                     prompt: preprocessPrompt,
-                    modelId: getFlag(ctx.flags, 'preprocess-model-id') ?? defaultImageModelId,
+                    modelId: preprocessModelId ?? defaultImageModelId,
                     batchSize: 1,
                     negativePrompt: getFlag(ctx.flags, 'preprocess-negative-prompt'),
                     seed: getFlag(ctx.flags, 'preprocess-seed') == null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assethub/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Command line interface for AssetHub.",
   "type": "module",
   "bin": {