@assethub/cli 0.1.1 → 0.1.3

package/README.md

@@ -8,10 +8,12 @@ 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 jobs watch job_123
-assethub production analyze --image-url https://example.com/input.png --part-extractor "V1.5"
+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
 ```
 
 Configuration:
@@ -24,11 +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 --interval-ms 5000 --timeout-ms 900000
-assethub mesh generate --source-url https://example.com/input.png --model-id meshGen.hunyuan31 --wait --interval-ms 5000 --timeout-ms 900000
-assethub production analyze --image-url https://example.com/input.png --part-extractor "V1.5"
+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
+cat ./character.png | assethub parts split --stdin --file-name character.png --part-extractor "V1.5" --wait --all-ready --download --out-dir ./out/parts
+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.
+- `--data-uri <uri>` accepts `data:image/png;base64,...` style inputs and uploads
+  them before running the target command.
+- `--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.
+
+Agent-oriented output:
+
+- stdout is one final JSON object.
+- polling progress goes to stderr.
+- `--download --out-dir <dir>` recursively downloads public artifact URLs from
+  job or production status payloads and writes a `manifest.json`.
+
+`assethub parts compare` runs the normal part split first. When
+`--preprocess-prompt <text>` is provided, it then uses the Nano Banana image
+model to generate a preprocessed image, waits for that image job to finish, and
+runs a second split on the generated image. The final JSON contains `direct`
+and `preprocessed` sections so agents can compare both outputs. If
+preprocessing fails, the direct result is still printed with
+`preprocessed.ok: false`; pass `--fail-on-preprocess-error` when a non-zero exit
+is preferred. Use `--all-ready` rather than explicit `--task-id` values when
+preprocessing is enabled, because the generated-image split creates a separate
+production order.
+
 Image generation defaults to the deployed `v1` endpoint. Pass `--api-version v2`
 only when the `v2` image endpoint is available in the target environment.
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, extname, join } from 'node:path';
 import { argv, env, exit, stdin, stderr, stdout } from 'node:process';
 import { AssetHubApiError, createAssetHubClient, } from '@assethub/api-client';
 const defaultBaseUrl = 'https://app.assethub.io';
@@ -11,32 +11,26 @@ const defaultProfileName = 'default';
 const defaultPartExtractorName = 'V1.5';
 const partExtractorOptions = [
     {
-        internalId: 'ah_part_extractor_v3',
         publicName: 'Part Extractor V3',
         aliases: ['part extractor v3', 'v3'],
     },
     {
-        internalId: 'ah_part_extractor_v5',
         publicName: 'V1',
         aliases: ['v1', '1'],
     },
     {
-        internalId: 'ah_part_extractor_v55',
         publicName: 'V1.5 alpha',
         aliases: ['v1.5 alpha', 'v1.5-alpha', '1.5 alpha', '1.5-alpha'],
     },
     {
-        internalId: 'ah_part_extractor_v65',
         publicName: 'V1.5',
         aliases: ['v1.5', '1.5', 'latest', 'default'],
     },
     {
-        internalId: 'ah_part_extractor_v20_alpha',
         publicName: 'V2.0 alpha',
         aliases: ['v2.0 alpha', 'v2 alpha', 'v2.0-alpha', 'v2-alpha', '2.0 alpha'],
     },
     {
-        internalId: 'ah_part_extractor_v21_alpha',
         publicName: 'V2.1 alpha',
         aliases: ['v2.1 alpha', 'v2.1-alpha', '2.1 alpha'],
     },
@@ -45,15 +39,14 @@ const partExtractorPublicNames = partExtractorOptions
     .map(option => option.publicName)
     .join(', ');
 const normalizePartExtractorName = (value) => value.trim().toLowerCase().replace(/\s+/g, ' ');
-const publicNameByInternalPartExtractorId = new Map(partExtractorOptions.map(option => [option.internalId, option.publicName]));
-const internalPartExtractorIdByPublicName = new Map(partExtractorOptions.flatMap(option => [
-    [normalizePartExtractorName(option.publicName), option.internalId],
+const partExtractorPublicNameByInput = new Map(partExtractorOptions.flatMap(option => [
+    [normalizePartExtractorName(option.publicName), option.publicName],
     ...option.aliases.map(alias => [
         normalizePartExtractorName(alias),
-        option.internalId,
+        option.publicName,
     ]),
 ]));
-const isInternalPartExtractorId = (value) => value === 'nano_bbox_v1' || value.startsWith('ah_part_extractor_');
+const isInternalPartExtractorId = (value) => value.trim().includes('_');
 const usage = `AssetHub CLI
 
 Usage:
@@ -65,15 +58,18 @@ Usage:
   assethub models get <model-id>
   assethub files import <url> --media-type image|mesh
   assethub files upload <file> --media-type image|mesh
-  assethub image generate --prompt <text> [--file <path> | --source-url <url>] [--model-id <id>] [--batch-size <n>] [--wait] [--api-version v1|v2]
+  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 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>) [--model-id <id>] [--name <name>] [--wait]
-  assethub mesh retopo (--source-resource-id <id> | --source-url <url> | --file-ref-json <json>) --model-id <id> [--wait]
-  assethub jobs get <job-id>
-  assethub jobs watch <job-id> [--interval-ms <ms>] [--timeout-ms <ms>]
-  assethub production analyze --image-url <url> [--part-extractor <name>] [--name <name>]
-  assethub production status <order-id>
-  assethub production execute --order-id <id> --mission-id <id> --task-id <id> [--task-id <id>...] [--part-extractor <name>] [--part-extraction-mode fast|high_quality]
+  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 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 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>]
 
 Global options:
   --api-key <key>       Overrides saved auth and ASSETHUB_API_KEY.
@@ -87,9 +83,13 @@ Examples:
   assethub auth login --api-key-stdin
   assethub models list --domain meshGen --ids-only
   assethub files upload ./input.png --media-type image
+  assethub source create --file ./input.png --media-type image
+  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 production analyze --image-url https://example.com/input.png --part-extractor "V1.5"
+  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
 `;
 const print = (value) => {
     stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -162,23 +162,22 @@ const requireFlag = (flags, name) => {
 const getPartExtractorFlag = (flags) => getFlag(flags, 'part-extractor') ??
     getFlag(flags, 'part-extractor-version') ??
     getFlag(flags, 'agent-version');
-const resolvePartExtractorInternalId = (value) => {
+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 internalId = internalPartExtractorIdByPublicName.get(normalizePartExtractorName(value));
-    if (internalId == null) {
+    const publicName = partExtractorPublicNameByInput.get(normalizePartExtractorName(value));
+    if (publicName == null) {
         throw new Error(`Unknown part extractor: ${value}. Use one of: ${partExtractorPublicNames}.`);
     }
-    return internalId;
+    return publicName;
 };
-const resolvePartExtractorForAnalyze = (flags) => resolvePartExtractorInternalId(getPartExtractorFlag(flags) ?? defaultPartExtractorName);
+const resolvePartExtractorForAnalyze = (flags) => resolvePartExtractorPublicName(getPartExtractorFlag(flags) ?? defaultPartExtractorName);
 const publicPartExtractorName = (value) => {
     if (value == null) {
         return null;
     }
-    return (publicNameByInternalPartExtractorId.get(value) ??
-        (isInternalPartExtractorId(value) ? 'Unknown' : value));
+    return (isInternalPartExtractorId(value) ? 'Unknown' : value);
 };
 const sanitizeProductionOutput = (value) => {
     if (Array.isArray(value)) {
@@ -224,6 +223,10 @@ const parseMediaType = (value) => {
     }
     throw new Error('--media-type must be "image" or "mesh"');
 };
+const defaultFileNameForMediaType = (mediaType) => mediaType === 'image' ? 'stdin.png' : 'stdin.glb';
+const getSourceResourceIdFlag = (flags) => getFlag(flags, 'source-resource-id') ??
+    getFlag(flags, 'source-id') ??
+    getFlag(flags, 'resource-id');
 const getProfileName = (flags) => getFlag(flags, 'profile') ?? defaultProfileName;
 const getConfigPath = (flags) => getFlag(flags, 'config') ??
     env.ASSETHUB_CLI_CONFIG ??
@@ -265,6 +268,18 @@ const readStdin = async () => await new Promise((resolve, reject) => {
     stdin.on('end', () => resolve(value));
     stdin.on('error', reject);
 });
+const readStdinBlob = async (type) => await new Promise((resolve, reject) => {
+    const chunks = [];
+    stdin.on('data', chunk => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    stdin.on('end', () => {
+        const buffer = Buffer.concat(chunks);
+        const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        resolve(new Blob([arrayBuffer], type == null ? undefined : { type }));
+    });
+    stdin.on('error', reject);
+});
 const resolveAuth = async (flags) => {
     const profile = getProfileName(flags);
     const baseUrlFromFlags = getFlag(flags, 'base-url');
@@ -323,8 +338,46 @@ const readBlob = async (filePath) => {
     const buffer = await readFile(filePath);
     return new Blob([new Uint8Array(buffer)]);
 };
+const blobFromDataUri = (value) => {
+    const match = value.match(/^data:([^;,]+)?(;base64)?,(.*)$/s);
+    if (match == null) {
+        throw new Error('--data-uri must be a valid data URI.');
+    }
+    const contentType = match[1] === '' ? undefined : match[1];
+    const isBase64 = match[2] != null;
+    const payload = match[3] ?? '';
+    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 }),
+        contentType,
+    };
+};
+const extensionFromMimeType = (mimeType, mediaType) => {
+    if (mimeType === 'image/png')
+        return 'png';
+    if (mimeType === 'image/jpeg')
+        return 'jpg';
+    if (mimeType === 'image/webp')
+        return 'webp';
+    if (mimeType === 'image/gif')
+        return 'gif';
+    if (mimeType === 'model/gltf-binary')
+        return 'glb';
+    if (mimeType === 'model/gltf+json')
+        return 'gltf';
+    return mediaType === 'image' ? 'png' : 'glb';
+};
+const ensureFileNameExtension = (fileName, mediaType, mimeType) => {
+    if (extname(fileName) !== '') {
+        return fileName;
+    }
+    return `${fileName}.${extensionFromMimeType(mimeType, mediaType)}`;
+};
 const resolveSource = async ({ flags, client, fileMediaType, }) => {
-    const sourceResourceId = getFlag(flags, 'source-resource-id');
+    const sourceResourceId = getSourceResourceIdFlag(flags);
     if (sourceResourceId != null) {
         return { resourceId: sourceResourceId };
     }
@@ -345,12 +398,32 @@ const resolveSource = async ({ flags, client, 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,
+            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,
+            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, or --file-ref-json.');
+        throw new Error('Missing source. Pass --file, --source-url, --source-resource-id, --source-id, --file-ref-json, --stdin, or --data-uri.');
     }
     return source;
 };
@@ -366,6 +439,62 @@ 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,
+        fileMediaType: 'image',
+    });
+    if (source.resourceId != null) {
+        return { imageAssetId: source.resourceId };
+    }
+    if (source.url != null) {
+        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.');
+    }
+    return { imageBlobLocation: source.fileRef };
+};
+const productionAnalyzeSourceFromSource = (source) => {
+    if (source.resourceId != null) {
+        return { imageAssetId: source.resourceId };
+    }
+    if (source.url != null) {
+        return { imageUrl: source.url };
+    }
+    return { imageBlobLocation: source.fileRef };
+};
+const sourceFromProductionAnalyzeSource = (source) => {
+    if (source.imageAssetId != null) {
+        return { resourceId: source.imageAssetId };
+    }
+    if (source.imageUrl != null) {
+        return { url: source.imageUrl };
+    }
+    return { fileRef: source.imageBlobLocation };
+};
+const productionAnalyzeTerminalStatuses = new Set(['ready', 'failed']);
+const productionExecuteTerminalStatuses = new Set(['completed', 'failed']);
+const pollProductionStatus = async ({ ctx, orderId, terminalStatuses, }) => {
+    const intervalMs = parsePositiveIntegerFlag(ctx.flags, 'interval-ms', 5000);
+    const timeoutMs = parsePositiveIntegerFlag(ctx.flags, 'timeout-ms', 900000);
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= timeoutMs) {
+        const status = await ctx.client.v1.getProductionStatus(orderId);
+        const orderStatus = status.order.status;
+        stderr.write(`[poll] order=${orderId} status=${orderStatus}\n`);
+        if (terminalStatuses.has(orderStatus)) {
+            return status;
+        }
+        await new Promise(resolve => setTimeout(resolve, intervalMs));
+    }
+    throw new Error(`Polling timeout: order=${orderId} did not reach terminal state within ${timeoutMs}ms`);
+};
 const pollIfRequested = async ({ ctx, jobId, apiVersion = 'v2', }) => {
     if (!hasFlag(ctx.flags, 'wait')) {
         return undefined;
@@ -388,6 +517,60 @@ const requirePositional = (positionals, index, label) => {
     }
     return value;
 };
+const commandSource = async (subcommand, ctx) => {
+    if (subcommand !== 'create') {
+        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 });
+        return;
+    }
+    if (sourceResourceId != null) {
+        print({
+            source: { resourceId: sourceResourceId },
+            resourceId: sourceResourceId,
+            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 });
+};
 const commandModels = async (subcommand, positionals, ctx) => {
     if (subcommand === 'list') {
         const domain = getFlag(ctx.flags, 'domain');
@@ -533,7 +716,7 @@ const commandImage = async (subcommand, ctx) => {
             source,
         });
     const job = await pollIfRequested({ ctx, jobId: queued.jobId, apiVersion });
-    print({ queued, job, apiVersion });
+    print(await withOptionalDownloads(ctx.flags, { queued, job, apiVersion }));
 };
 const commandMesh = async (subcommand, ctx) => {
     if (subcommand === 'generate') {
@@ -551,7 +734,7 @@ const commandMesh = async (subcommand, ctx) => {
             isLowPoly: parseBooleanFlag(ctx.flags, 'low-poly'),
         });
         const job = await pollIfRequested({ ctx, jobId: queued.jobId });
-        print({ queued, job });
+        print(await withOptionalDownloads(ctx.flags, { queued, job }));
         return;
     }
     if (subcommand === 'retopo') {
@@ -567,7 +750,7 @@ const commandMesh = async (subcommand, ctx) => {
             polygonType: getFlag(ctx.flags, 'polygon-type'),
         });
         const job = await pollIfRequested({ ctx, jobId: queued.jobId });
-        print({ queued, job });
+        print(await withOptionalDownloads(ctx.flags, { queued, job }));
         return;
     }
     throw new Error('Unknown mesh command. Use "mesh generate" or "mesh retopo".');
@@ -575,7 +758,8 @@ const commandMesh = async (subcommand, ctx) => {
 const commandJobs = async (subcommand, positionals, ctx) => {
     const jobId = requirePositional(positionals, 2, 'job-id');
     if (subcommand === 'get') {
-        print({ job: await ctx.client.v2.getJob(jobId) });
+        const job = await ctx.client.v2.getJob(jobId);
+        print(await withOptionalDownloads(ctx.flags, { job }));
         return;
     }
     if (subcommand === 'watch') {
@@ -586,7 +770,7 @@ const commandJobs = async (subcommand, positionals, ctx) => {
                 stderr.write(`[poll] job=${current.id} status=${current.status}\n`);
             },
         });
-        print({ job });
+        print(await withOptionalDownloads(ctx.flags, { job }));
         return;
     }
     throw new Error('Unknown jobs command. Use "jobs get" or "jobs watch".');
@@ -599,22 +783,300 @@ const resolvePartExtractorFromMission = async (ctx, orderId, missionId) => {
             partExtractorPublicNames);
     }
     if (isInternalPartExtractorId(mission.agentVersion)) {
-        return mission.agentVersion;
+        throw new Error('Could not infer the public part extractor from the mission. Pass --part-extractor with one of: ' +
+            partExtractorPublicNames);
+    }
+    return resolvePartExtractorPublicName(mission.agentVersion);
+};
+const redactUrl = (value) => {
+    try {
+        const url = new URL(value);
+        url.search = '';
+        url.hash = '';
+        return url.toString();
+    }
+    catch {
+        return value;
+    }
+};
+const collectHttpUrls = (value, urls = new Set()) => {
+    if (typeof value === 'string') {
+        try {
+            const url = new URL(value);
+            if (url.protocol === 'http:' || url.protocol === 'https:') {
+                urls.add(value);
+            }
+        }
+        catch {
+            // Ignore non-URL strings.
+        }
+        return urls;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectHttpUrls(item, urls);
+        }
+        return urls;
+    }
+    if (value != null && typeof value === 'object') {
+        for (const item of Object.values(value)) {
+            collectHttpUrls(item, urls);
+        }
+    }
+    return urls;
+};
+const extensionFromContentType = (contentType) => {
+    if (contentType == null) {
+        return '';
+    }
+    const clean = contentType.split(';')[0]?.trim().toLowerCase();
+    switch (clean) {
+        case 'image/png':
+            return '.png';
+        case 'image/jpeg':
+            return '.jpg';
+        case 'image/webp':
+            return '.webp';
+        case 'image/gif':
+            return '.gif';
+        case 'model/gltf-binary':
+            return '.glb';
+        case 'model/gltf+json':
+            return '.gltf';
+        case 'application/octet-stream':
+        default:
+            return '';
     }
-    return resolvePartExtractorInternalId(mission.agentVersion);
+};
+const safeDownloadFileName = (value, index, contentType) => {
+    let name = `asset-${index + 1}`;
+    try {
+        const url = new URL(value);
+        const fromPath = basename(url.pathname);
+        if (fromPath !== '' && fromPath !== '/' && fromPath !== '.') {
+            name = fromPath;
+        }
+    }
+    catch {
+        // Keep fallback name.
+    }
+    name = name.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^_+/, '');
+    if (name === '' || name === '.' || name === '..') {
+        name = `asset-${index + 1}`;
+    }
+    if (extname(name) === '') {
+        name = `${name}${extensionFromContentType(contentType)}`;
+    }
+    return `${String(index + 1).padStart(3, '0')}-${name}`;
+};
+const maybeDownloadUrls = async (flags, value) => {
+    if (!hasFlag(flags, 'download')) {
+        return undefined;
+    }
+    const outDir = getFlag(flags, 'out-dir') ?? getFlag(flags, 'out');
+    if (outDir == null || outDir === 'true') {
+        throw new Error('Missing download output directory. Pass --out-dir <dir> or --out <dir>.');
+    }
+    await mkdir(outDir, { recursive: true });
+    const urls = [...collectHttpUrls(value)];
+    const files = [];
+    for (const [index, url] of urls.entries()) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Download failed: ${redactUrl(url)} returned HTTP ${response.status}`);
+        }
+        const contentType = response.headers.get('content-type');
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const fileName = safeDownloadFileName(url, index, contentType);
+        const filePath = join(outDir, fileName);
+        await writeFile(filePath, bytes);
+        files.push({
+            url: redactUrl(url),
+            path: filePath,
+            contentType,
+            bytes: bytes.byteLength,
+        });
+    }
+    const manifest = { generatedAt: new Date().toISOString(), files };
+    await writeFile(join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { outDir, files };
+};
+const withOptionalDownloads = async (flags, value) => {
+    const downloads = await maybeDownloadUrls(flags, value);
+    return downloads == null ? value : { ...value, downloads };
+};
+const firstStringValueForKeys = (value, keys) => {
+    if (value == null || typeof value !== 'object') {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = firstStringValueForKeys(item, keys);
+            if (found != null) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (keys.has(key) && typeof entry === 'string' && entry.trim() !== '') {
+            return entry;
+        }
+        const found = firstStringValueForKeys(entry, keys);
+        if (found != null) {
+            return found;
+        }
+    }
+    return undefined;
+};
+const firstBlobLocation = (value) => {
+    if (value == null || typeof value !== 'object') {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = firstBlobLocation(item);
+            if (found != null) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    const record = value;
+    if (record.type === 'supabase' && typeof record.bucket === 'string' && typeof record.path === 'string') {
+        return {
+            type: 'supabase',
+            bucket: record.bucket,
+            path: record.path,
+        };
+    }
+    if (record.type === 'signedSupabase' && typeof record.signedUrl === 'string') {
+        return {
+            type: 'signedSupabase',
+            signedUrl: record.signedUrl,
+        };
+    }
+    if (record.type === 'asset' && typeof record.assetId === 'string') {
+        return {
+            type: 'asset',
+            assetId: record.assetId,
+        };
+    }
+    for (const entry of Object.values(record)) {
+        const found = firstBlobLocation(entry);
+        if (found != null) {
+            return found;
+        }
+    }
+    return undefined;
+};
+const imageSourceFromCompletedJob = (job) => {
+    if (job.resourceId != null && job.resourceId.trim() !== '') {
+        return { imageAssetId: job.resourceId };
+    }
+    const resourceId = firstStringValueForKeys(job, new Set(['resourceId', 'resource_id', 'assetId', 'asset_id', 'imageAssetId']));
+    if (resourceId != null) {
+        return { imageAssetId: resourceId };
+    }
+    const imageUrl = firstStringValueForKeys(job, new Set(['imageUrl', 'image_url', 'url', 'publicUrl', 'public_url']));
+    if (imageUrl != null) {
+        return { imageUrl };
+    }
+    const blobLocation = firstBlobLocation(job);
+    if (blobLocation != null) {
+        return { imageBlobLocation: blobLocation };
+    }
+    throw new Error('Preprocessing completed, but the image job did not include an image source for part splitting.');
+};
+const errorToOutput = (error) => {
+    if (error instanceof AssetHubApiError) {
+        return {
+            name: error.name,
+            message: error.message,
+            status: error.status,
+            code: error.code,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+        };
+    }
+    return { message: String(error) };
+};
+const readyTaskIdsFromStatus = (status) => {
+    const missions = status != null && typeof status === 'object' && 'missions' in status
+        ? status.missions
+        : undefined;
+    if (!Array.isArray(missions)) {
+        return [];
+    }
+    return missions.flatMap(mission => {
+        if (mission == null || typeof mission !== 'object' || !('tasks' in mission)) {
+            return [];
+        }
+        const tasks = mission.tasks;
+        if (!Array.isArray(tasks)) {
+            return [];
+        }
+        return tasks.flatMap(task => {
+            if (task == null || typeof task !== 'object') {
+                return [];
+            }
+            const id = task.id;
+            const taskStatus = task.status;
+            return typeof id === 'string' &&
+                typeof taskStatus === 'string' &&
+                ['ready', 'pending', 'pending_review'].includes(taskStatus)
+                ? [id]
+                : [];
+        });
+    });
+};
+const singleMissionIdFromStatus = (status) => {
+    const missions = status != null && typeof status === 'object' && 'missions' in status
+        ? status.missions
+        : undefined;
+    if (!Array.isArray(missions) || missions.length !== 1) {
+        throw new Error('Pass --mission-id when the production order does not have exactly one mission.');
+    }
+    const missionId = missions[0].id;
+    if (typeof missionId !== 'string' || missionId.trim() === '') {
+        throw new Error('Could not infer mission id. Pass --mission-id.');
+    }
+    return missionId;
 };
 const commandProduction = async (subcommand, positionals, ctx) => {
     if (subcommand === 'analyze') {
-        print(sanitizeProductionOutput(await ctx.client.v1.analyzeProduction({
-            imageUrl: requireFlag(ctx.flags, 'image-url'),
+        const analyzed = await ctx.client.v1.analyzeProduction({
+            ...(await resolveProductionAnalyzeSource(ctx)),
             agentVersion: resolvePartExtractorForAnalyze(ctx.flags),
             name: getFlag(ctx.flags, 'name'),
-        })));
+        });
+        const status = hasFlag(ctx.flags, 'wait')
+            ? await pollProductionStatus({
+                ctx,
+                orderId: analyzed.orderId,
+                terminalStatuses: productionAnalyzeTerminalStatuses,
+            })
+            : undefined;
+        print(await withOptionalDownloads(ctx.flags, sanitizeProductionOutput({ analyzed, status })));
         return;
     }
     if (subcommand === 'status') {
         const orderId = requirePositional(positionals, 2, 'order-id');
-        print(sanitizeProductionOutput(await ctx.client.v1.getProductionStatus(orderId)));
+        const status = hasFlag(ctx.flags, 'wait')
+            ? await pollProductionStatus({
+                ctx,
+                orderId,
+                terminalStatuses: new Set([
+                    ...productionAnalyzeTerminalStatuses,
+                    ...productionExecuteTerminalStatuses,
+                ]),
+            })
+            : await ctx.client.v1.getProductionStatus(orderId);
+        print(await withOptionalDownloads(ctx.flags, sanitizeProductionOutput({ status })));
         return;
     }
     if (subcommand === 'execute') {
@@ -633,18 +1095,185 @@ const commandProduction = async (subcommand, positionals, ctx) => {
         const partExtractorFlag = getPartExtractorFlag(ctx.flags);
         const agentVersion = partExtractorFlag == null
             ? await resolvePartExtractorFromMission(ctx, orderId, missionId)
-            : resolvePartExtractorInternalId(partExtractorFlag);
-        print(sanitizeProductionOutput(await ctx.client.v1.executeProduction({
+            : resolvePartExtractorPublicName(partExtractorFlag);
+        const executed = await ctx.client.v1.executeProduction({
             orderId,
             missionId,
             confirmedTaskIds,
             agentVersion,
             partExtractionMode,
-        })));
+        });
+        const status = hasFlag(ctx.flags, 'wait')
+            ? await pollProductionStatus({
+                ctx,
+                orderId,
+                terminalStatuses: productionExecuteTerminalStatuses,
+            })
+            : undefined;
+        print(await withOptionalDownloads(ctx.flags, sanitizeProductionOutput({ executed, status })));
         return;
     }
     throw new Error('Unknown production command. Use "production analyze", "production status", or "production execute".');
 };
+const commandParts = async (subcommand, ctx) => {
+    const runPartSplit = async (source) => {
+        let orderId = source == null ? getFlag(ctx.flags, 'order-id') : undefined;
+        let analyzed;
+        let status;
+        if (orderId == null) {
+            const result = await ctx.client.v1.analyzeProduction({
+                ...(source ?? (await resolveProductionAnalyzeSource(ctx))),
+                agentVersion: resolvePartExtractorForAnalyze(ctx.flags),
+                name: getFlag(ctx.flags, 'name'),
+            });
+            analyzed = result;
+            orderId = result.orderId;
+            if (hasFlag(ctx.flags, 'wait') || hasFlag(ctx.flags, 'all-ready')) {
+                status = await pollProductionStatus({
+                    ctx,
+                    orderId,
+                    terminalStatuses: productionAnalyzeTerminalStatuses,
+                });
+            }
+        }
+        else if (hasFlag(ctx.flags, 'wait') || hasFlag(ctx.flags, 'all-ready')) {
+            status = await pollProductionStatus({
+                ctx,
+                orderId,
+                terminalStatuses: productionAnalyzeTerminalStatuses,
+            });
+        }
+        let taskIds = getFlagValues(ctx.flags, 'task-id');
+        if (hasFlag(ctx.flags, 'all-ready')) {
+            if (status == null) {
+                status = await ctx.client.v1.getProductionStatus(orderId);
+            }
+            taskIds = readyTaskIdsFromStatus(status);
+            if (taskIds.length === 0) {
+                throw new Error('No ready tasks were found for --all-ready.');
+            }
+        }
+        let executed;
+        let executionStatus;
+        if (taskIds.length > 0) {
+            if (status == null) {
+                status = await ctx.client.v1.getProductionStatus(orderId);
+            }
+            const missionId = getFlag(ctx.flags, 'mission-id') ?? singleMissionIdFromStatus(status);
+            const partExtractorFlag = getPartExtractorFlag(ctx.flags);
+            const agentVersion = partExtractorFlag == null
+                ? await resolvePartExtractorFromMission(ctx, orderId, missionId)
+                : resolvePartExtractorPublicName(partExtractorFlag);
+            const partExtractionMode = getFlag(ctx.flags, 'part-extraction-mode');
+            if (partExtractionMode != null &&
+                partExtractionMode !== 'fast' &&
+                partExtractionMode !== 'high_quality') {
+                throw new Error('--part-extraction-mode must be "fast" or "high_quality"');
+            }
+            executed = await ctx.client.v1.executeProduction({
+                orderId,
+                missionId,
+                confirmedTaskIds: taskIds,
+                agentVersion,
+                partExtractionMode,
+            });
+            if (hasFlag(ctx.flags, 'wait')) {
+                executionStatus = await pollProductionStatus({
+                    ctx,
+                    orderId,
+                    terminalStatuses: productionExecuteTerminalStatuses,
+                });
+            }
+        }
+        return sanitizeProductionOutput({
+            analyzed,
+            status,
+            executed,
+            executionStatus,
+        });
+    };
+    if (subcommand === 'split') {
+        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.');
+        }
+        const preprocessPrompt = getFlag(ctx.flags, 'preprocess-prompt');
+        if (preprocessPrompt === 'true') {
+            throw new Error('Missing required flag value: --preprocess-prompt <text>');
+        }
+        if (preprocessPrompt != null && getFlagValues(ctx.flags, 'task-id').length > 0) {
+            throw new Error('parts compare preprocessing creates a second order. Use --all-ready instead of --task-id.');
+        }
+        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 inputSource = imageUrlFlag == null
+            ? productionAnalyzeSourceFromSource(await requireSource({
+                flags: ctx.flags,
+                client: ctx.client,
+                fileMediaType: 'image',
+            }))
+            : { imageUrl: imageUrlFlag };
+        const direct = await runPartSplit(inputSource);
+        let preprocessed = null;
+        if (preprocessPrompt != null && preprocessPrompt !== 'true') {
+            try {
+                const queued = await ctx.client.v2.generateImage({
+                    source: sourceFromProductionAnalyzeSource(inputSource),
+                    prompt: preprocessPrompt,
+                    modelId: getFlag(ctx.flags, 'preprocess-model-id') ?? defaultImageModelId,
+                    batchSize: 1,
+                    negativePrompt: getFlag(ctx.flags, 'preprocess-negative-prompt'),
+                    seed: getFlag(ctx.flags, 'preprocess-seed') == null
+                        ? undefined
+                        : parsePositiveIntegerFlag(ctx.flags, 'preprocess-seed', 1),
+                });
+                const job = await ctx.client.v2.pollJob(queued.jobId, {
+                    intervalMs: parsePositiveIntegerFlag(ctx.flags, 'interval-ms', 5000),
+                    timeoutMs: parsePositiveIntegerFlag(ctx.flags, 'timeout-ms', 900000),
+                    onPoll: current => {
+                        stderr.write(`[poll] preprocess job=${current.id} status=${current.status}\n`);
+                    },
+                });
+                if (job.status !== 'completed') {
+                    throw new Error(`Preprocessing failed: job=${job.id} status=${job.status}`);
+                }
+                const generatedSource = imageSourceFromCompletedJob(job);
+                preprocessed = {
+                    ok: true,
+                    image: {
+                        queued,
+                        job,
+                        source: generatedSource,
+                    },
+                    split: await runPartSplit(generatedSource),
+                };
+            }
+            catch (error) {
+                if (hasFlag(ctx.flags, 'fail-on-preprocess-error')) {
+                    throw error;
+                }
+                preprocessed = {
+                    ok: false,
+                    error: errorToOutput(error),
+                };
+            }
+        }
+        print(await withOptionalDownloads(ctx.flags, {
+            direct,
+            preprocessed,
+        }));
+        return;
+    }
+    throw new Error('Unknown parts command. Use "parts split" or "parts compare".');
+};
 const run = async () => {
     const parsed = parseArgs(argv.slice(2));
     if (hasFlag(parsed.flags, 'help') || parsed.positionals.length === 0) {
@@ -664,6 +1293,9 @@ const run = async () => {
         case 'files':
             await commandFiles(subcommand, parsed.positionals, ctx);
             return;
+        case 'source':
+            await commandSource(subcommand, ctx);
+            return;
         case 'image':
             await commandImage(subcommand, ctx);
             return;
@@ -676,6 +1308,9 @@ const run = async () => {
         case 'production':
             await commandProduction(subcommand, parsed.positionals, ctx);
             return;
+        case 'parts':
+            await commandParts(subcommand, ctx);
+            return;
         default:
             throw new Error(`Unknown command: ${command}`);
     }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@assethub/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command line interface for AssetHub.",
   "type": "module",
   "bin": {
-    "assethub": "./dist/index.js"
+    "assethub": "dist/index.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,19 +20,19 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
+  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@assethub/api-client": "^0.1.0"
+    "@assethub/api-client": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "24.10.1",
     "typescript": "5.9.3"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
-    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
   }
-}
+}