tripo-cli 0.1.0

package/dist/src/config/history.js

@@ -0,0 +1,104 @@
+/**
+ * Task history at ~/.tripo/history.jsonl — powers implicit context (@last),
+ * positional references (@2), named references (@my-knight), and redo.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tripoHome } from './config.js';
+function historyPath() {
+    return join(tripoHome(), 'history.jsonl');
+}
+export function appendHistory(entry) {
+    mkdirSync(tripoHome(), { recursive: true, mode: 0o700 });
+    appendFileSync(historyPath(), JSON.stringify(entry) + '\n');
+}
+export function readHistory() {
+    let raw;
+    try {
+        raw = readFileSync(historyPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch { }
+    }
+    // Later entries for the same task id override earlier ones (status updates).
+    const merged = new Map();
+    for (const e of entries)
+        merged.set(e.task_id, { ...merged.get(e.task_id), ...e });
+    return [...merged.values()];
+}
+export function updateHistoryStatus(taskId, status, patch) {
+    const existing = readHistory().find((e) => e.task_id === taskId);
+    if (!existing)
+        return;
+    appendHistory({ ...existing, ...patch, status, task_id: taskId });
+}
+export class RefError extends Error {
+}
+/**
+ * Resolve a history reference:
+ *   @last          → most recent successful task
+ *   @last:any      → most recent task regardless of status
+ *   @2             → 2nd most recent successful task
+ *   @some-name     → unique match on entry name (slug); ambiguity is an error
+ * Returns undefined when `ref` is not a reference at all.
+ */
+export function resolveReference(ref) {
+    if (!ref.startsWith('@'))
+        return undefined;
+    const body = ref.slice(1);
+    const entries = readHistory();
+    const successes = entries.filter((e) => e.status === 'success');
+    if (body === 'last' || body === '') {
+        const hit = successes[successes.length - 1];
+        if (!hit)
+            throw new RefError('no successful task in history yet');
+        return hit;
+    }
+    if (body === 'last:any') {
+        const hit = entries[entries.length - 1];
+        if (!hit)
+            throw new RefError('history is empty');
+        return hit;
+    }
+    if (/^\d+$/.test(body)) {
+        const n = Number(body);
+        const hit = successes[successes.length - n];
+        if (!hit)
+            throw new RefError(`history has only ${successes.length} successful task(s), cannot resolve @${n}`);
+        return hit;
+    }
+    const matches = entries.filter((e) => e.name === body);
+    if (matches.length === 0) {
+        const fuzzy = entries.filter((e) => e.name?.includes(body));
+        if (fuzzy.length === 1)
+            return fuzzy[0];
+        if (fuzzy.length > 1) {
+            throw new RefError(`"@${body}" matches ${fuzzy.length} tasks: ${fuzzy.map((e) => `${e.name} (${e.task_id.slice(0, 8)})`).join(', ')} — use a task id instead`);
+        }
+        throw new RefError(`no task named "@${body}" in history`);
+    }
+    if (matches.length > 1) {
+        throw new RefError(`"@${body}" matches ${matches.length} tasks: ${matches.map((e) => e.task_id.slice(0, 8)).join(', ')} — use a task id instead`);
+    }
+    return matches[0];
+}
+/** Build a filesystem/name-safe slug from a prompt or filename. */
+export function slugify(text, maxLen = 32) {
+    const slug = text
+        .toLowerCase()
+        .replace(/\.[a-z0-9]+$/i, '')
+        .replace(/[^a-z0-9\u4e00-\u9fff]+/gi, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, maxLen)
+        .replace(/-+$/, '');
+    return slug || 'task';
+}

package/dist/src/core/client.js

@@ -0,0 +1,120 @@
+/**
+ * Lightweight V3 API client on top of global fetch (Node 20+).
+ * Handles the response envelope, error translation, timeouts, and
+ * exponential-backoff retries for transient failures (429/5xx/network).
+ */
+import { loadConfig, resolveApiBaseUrl, resolveApiKey } from '../config/config.js';
+import { ApiError, AuthError, NetworkError } from './errors.js';
+export class TripoClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    onRetry;
+    constructor(options = {}) {
+        const config = loadConfig();
+        this.baseUrl = (options.baseUrl ?? resolveApiBaseUrl(config)).replace(/\/$/, '');
+        const key = options.apiKey ?? resolveApiKey(config);
+        if (!key) {
+            throw new AuthError('no API key configured');
+        }
+        this.apiKey = key;
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.onRetry = options.onRetry;
+    }
+    async request(method, path, body) {
+        return this.send(method, path, {
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    async uploadFile(fileName, data) {
+        const form = new FormData();
+        form.append('file', data, fileName);
+        return this.send('POST', '/v3/files', { body: form });
+    }
+    async send(method, path, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (attempt > 0) {
+                const delay = Math.min(1000 * 2 ** (attempt - 1), 8000);
+                this.onRetry?.(attempt, delay, lastError?.message ?? 'retry');
+                await sleep(delay);
+            }
+            try {
+                return await this.sendOnce(method, path, init);
+            }
+            catch (err) {
+                lastError = err;
+                const retryable = err instanceof NetworkError || (err instanceof ApiError && err.retryable);
+                if (!retryable || attempt === this.maxRetries)
+                    throw err;
+            }
+        }
+        /* c8 ignore next */
+        throw lastError ?? new NetworkError('request failed');
+    }
+    async sendOnce(method, path, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(this.baseUrl + path, {
+                method,
+                headers: { Authorization: `Bearer ${this.apiKey}`, ...init.headers },
+                body: init.body,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new NetworkError(controller.signal.aborted ? `request timed out after ${this.timeoutMs}ms: ${method} ${path}` : `network error: ${reason}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let envelope;
+        try {
+            envelope = (await response.json());
+        }
+        catch {
+            if (!response.ok) {
+                throw new ApiError({ httpStatus: response.status, message: `HTTP ${response.status} with non-JSON body` });
+            }
+            throw new NetworkError(`invalid JSON response from ${path}`);
+        }
+        if (!response.ok || envelope.code !== 0) {
+            throw new ApiError({
+                apiCode: envelope.code !== 0 ? envelope.code : undefined,
+                httpStatus: response.status,
+                message: envelope.message,
+                suggestion: envelope.suggestion,
+                requestId: envelope.request_id,
+            });
+        }
+        return envelope.data;
+    }
+    // ---- typed convenience wrappers ----
+    getTask(taskId, step = false) {
+        const suffix = step ? '?step=1' : '';
+        return this.request('GET', `/v3/tasks/${encodeURIComponent(taskId)}${suffix}`);
+    }
+    listTasks(taskIds) {
+        return this.request('POST', '/v3/tasks/list', { task_ids: taskIds });
+    }
+    getBalance() {
+        return this.request('GET', '/v3/account/balance');
+    }
+    getUsage() {
+        return this.request('GET', '/v3/account/usage');
+    }
+    /** Create a task; returns its id. Response may be {task_id} or a full detail. */
+    async createTask(endpoint, payload) {
+        const data = await this.request('POST', endpoint, payload);
+        return data.task_id;
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/src/core/download.js

@@ -0,0 +1,107 @@
+/**
+ * Artifact download: walk task.output for URL-bearing fields, fetch each into
+ * the output directory, and write task.json (the reproducibility record).
+ * Output URLs expire in ~5 minutes, so downloads happen immediately after
+ * completion and URLs are never cached.
+ */
+import { createWriteStream } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { NetworkError } from './errors.js';
+const MODEL_EXTS = new Set(['.glb', '.gltf', '.fbx', '.obj', '.stl', '.3mf', '.usdz', '.zip', '.ply']);
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+/** Collect every downloadable URL in the output map (string or {url} object). */
+export function collectOutputUrls(output) {
+    if (!output)
+        return [];
+    const found = [];
+    const visit = (value, path) => {
+        if (typeof value === 'string') {
+            if (/^https?:\/\//.test(value))
+                found.push({ field: path, url: value });
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => visit(v, `${path}[${i}]`));
+            return;
+        }
+        if (value && typeof value === 'object') {
+            for (const [k, v] of Object.entries(value))
+                visit(v, path ? `${path}.${k}` : k);
+        }
+    };
+    visit(output, '');
+    return found;
+}
+function fileNameFor(field, url) {
+    const urlPath = new URL(url).pathname;
+    let ext = extname(urlPath).toLowerCase();
+    const base = field
+        .replace(/_url$/, '')
+        .replace(/[^a-z0-9_.\-[\]]/gi, '_')
+        .replace(/[[\]]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+    if (!ext) {
+        // rendered images are usually webp/png; models glb — guess from field name
+        ext = /image|preview|render/i.test(field) ? '.png' : '.bin';
+    }
+    return `${base || basename(urlPath) || 'artifact'}${ext}`;
+}
+async function downloadOne(url, dest) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body) {
+        throw new NetworkError(`download failed (HTTP ${response.status}): ${dest}`);
+    }
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(dest));
+}
+/** Download all artifacts of a finished task + write task.json. */
+export async function downloadArtifacts(task, outputDir, historyEntry, options = {}) {
+    await mkdir(outputDir, { recursive: true });
+    const urls = collectOutputUrls(task.output);
+    const files = [];
+    let modelFile;
+    let preview;
+    for (const { field, url } of urls) {
+        const name = fileNameFor(field, url);
+        const dest = join(outputDir, name);
+        options.onFile?.(name);
+        await downloadOne(url, dest);
+        files.push(dest);
+        const ext = extname(name).toLowerCase();
+        if (!modelFile && MODEL_EXTS.has(ext))
+            modelFile = dest;
+        if (!preview && (IMAGE_EXTS.has(ext) || /rendered|preview/i.test(field)))
+            preview = dest;
+    }
+    // Normalize the preview name so agents can rely on preview.png existing.
+    if (preview && basename(preview) !== 'preview.png') {
+        const { copyFile } = await import('node:fs/promises');
+        const canonical = join(outputDir, 'preview.png');
+        try {
+            await copyFile(preview, canonical);
+            files.push(canonical);
+            preview = canonical;
+        }
+        catch { }
+    }
+    const record = {
+        task_id: task.task_id,
+        type: task.type,
+        status: task.status,
+        input: task.input ?? historyEntry?.payload ?? {},
+        output_fields: urls.map((u) => u.field),
+        credits_consumed: task.credits_consumed,
+        created_at: task.created_at,
+        completed_at: task.completed_at,
+        files: files.map((f) => basename(f)),
+    };
+    await writeFile(join(outputDir, 'task.json'), JSON.stringify(record, null, 2) + '\n');
+    return { outputDir, files, modelFile, preview };
+}
+/** Default output directory: ./tripo-out/<slug>-<id8>/ */
+export function defaultOutputDir(baseDir, slug, taskId) {
+    return join(baseDir, 'tripo-out', `${slug}-${taskId.slice(0, 8)}`);
+}

package/dist/src/core/errors.js

@@ -0,0 +1,64 @@
+/** CLI error types carrying stable exit codes and human translations. */
+import { t } from '../i18n.js';
+import { EXIT, exitCodeFor, isRetryable, lookupError } from '../knowledge/error-catalog.js';
+export class CliError extends Error {
+    exitCode;
+    suggestion;
+    constructor(message, exitCode = EXIT.FATAL, suggestion) {
+        super(message);
+        this.exitCode = exitCode;
+        this.suggestion = suggestion;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message, suggestion) {
+        super(message, EXIT.USAGE, suggestion);
+    }
+}
+export class AuthError extends CliError {
+    constructor(message, suggestion) {
+        super(message, EXIT.AUTH, suggestion ?? t({ zh: '运行 tripo login 配置 API Key', en: 'run "tripo login" to configure an API key' }));
+    }
+}
+export class ApiError extends CliError {
+    apiCode;
+    httpStatus;
+    requestId;
+    retryable;
+    constructor(opts) {
+        const info = opts.apiCode !== undefined ? lookupError(opts.apiCode) : undefined;
+        const translated = info ? t(info) : undefined;
+        const parts = [translated ?? opts.message ?? `API error (HTTP ${opts.httpStatus})`];
+        if (translated && opts.message && opts.message !== translated)
+            parts.push(`(${opts.message})`);
+        super(parts.join(' '), exitCodeFor(opts.apiCode, opts.httpStatus), opts.suggestion);
+        this.apiCode = opts.apiCode;
+        this.httpStatus = opts.httpStatus;
+        this.requestId = opts.requestId;
+        this.retryable = isRetryable(opts.apiCode, opts.httpStatus);
+    }
+}
+export class NetworkError extends CliError {
+    constructor(message) {
+        super(message, EXIT.NETWORK);
+    }
+}
+export class TaskFailedError extends CliError {
+    taskId;
+    constructor(taskId, status, detail) {
+        const refundNote = t({
+            zh: '预扣积分已自动退还',
+            en: 'frozen credits have been refunded automatically',
+        });
+        super(`task ${taskId} ${status}${detail ? `: ${detail}` : ''} (${refundNote})`, EXIT.TASK_FAILED);
+        this.taskId = taskId;
+    }
+}
+/** Decorate insufficient-balance errors with the topup path and the gap. */
+export function balanceSuggestion(needed, balance) {
+    const gap = needed !== undefined && balance !== undefined ? Math.max(0, needed - balance) : undefined;
+    return t({
+        zh: `运行 tripo topup 充值${gap !== undefined ? `(还差约 ${gap} 积分)` : ''}`,
+        en: `run "tripo topup" to add credits${gap !== undefined ? ` (about ${gap} more needed)` : ''}`,
+    });
+}

package/dist/src/core/output.js

@@ -0,0 +1,72 @@
+/**
+ * Output discipline (the iron rule):
+ *   - stdout carries ONLY the final business result (JSON when piped/--json,
+ *     human-readable text when interactive).
+ *   - stderr carries all progress, logs, prompts, and decoration.
+ * Non-TTY environments automatically behave like --json --yes --no-open.
+ */
+import pc from 'picocolors';
+const state = { json: false, yes: false, quiet: false, noOpen: false };
+export function stdoutIsTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+export function stdinIsTTY() {
+    return Boolean(process.stdin.isTTY);
+}
+export function configureOutput(flags) {
+    Object.assign(state, flags);
+    // Headless environments (pipes, agents, CI) get machine output + no prompts.
+    if (!stdoutIsTTY())
+        state.json = true;
+    if (!stdinIsTTY())
+        state.yes = state.yes || !stdoutIsTTY();
+    if (!stdoutIsTTY() || !stdinIsTTY())
+        state.noOpen = true;
+}
+export function isJsonMode() {
+    return state.json;
+}
+export function isYes() {
+    return state.yes;
+}
+export function isQuiet() {
+    return state.quiet;
+}
+export function shouldOpen() {
+    return !state.noOpen;
+}
+export function isInteractive() {
+    return stdinIsTTY() && stdoutIsTTY() && !state.yes;
+}
+/** Progress/log line → stderr. */
+export function log(message) {
+    if (!state.quiet)
+        process.stderr.write(message + '\n');
+}
+export function warn(message) {
+    process.stderr.write(pc.yellow(`! ${message}`) + '\n');
+}
+export function errorLine(message) {
+    process.stderr.write(pc.red(`✗ ${message}`) + '\n');
+}
+export function success(message) {
+    if (!state.quiet)
+        process.stderr.write(pc.green(`✓ ${message}`) + '\n');
+}
+/**
+ * Final business result → stdout.
+ * JSON mode prints a single line (NDJSON-safe); human mode prints the
+ * formatted text (or a default rendering).
+ */
+export function emitResult(data, human) {
+    if (state.json) {
+        process.stdout.write(JSON.stringify(data) + '\n');
+    }
+    else {
+        process.stdout.write((human ?? JSON.stringify(data, null, 2)) + '\n');
+    }
+}
+/** Stream one NDJSON event to stdout (used by watch-style streaming output). */
+export function emitNdjson(event) {
+    process.stdout.write(JSON.stringify(event) + '\n');
+}

package/dist/src/core/requests.js

@@ -0,0 +1,169 @@
+/**
+ * Request builders: turn (step + args + resolved input) into the exact
+ * endpoint + JSON payload, applying knowledge-base validation first.
+ * Unknown extra args pass through untouched (the server maps them into
+ * `parameters`), so new API options work without a CLI release.
+ */
+import { getStep } from '../knowledge/chains.js';
+import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateRetargetParams, } from '../knowledge/params.js';
+import { CAPABILITY_DEFAULTS, normalizeModel } from '../knowledge/models.js';
+import { UsageError } from './errors.js';
+function ensure(result) {
+    if (result.errors.length > 0) {
+        throw new UsageError(result.errors.join('; '));
+    }
+}
+/** 3D generation: text-to-model. */
+export function buildTextToModel(prompt, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    return {
+        request: {
+            endpoint: '/v3/generation/text-to-model',
+            payload: { prompt, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'text_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** 3D generation: image-to-model (input = file_token/url/task_id). */
+export function buildImageToModel(input, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    return {
+        request: {
+            endpoint: '/v3/generation/image-to-model',
+            payload: { input, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'image_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** 3D generation: multiview-to-model. Views ordered [front, left, back, right]. */
+export function buildMultiviewToModel(views, model, params) {
+    const validated = validateGenerationParams(model, params);
+    ensure(validated);
+    const inputs = ['front', 'left', 'back', 'right']
+        .filter((v) => views[v])
+        .map((v) => ({ [v]: views[v] }));
+    if (!views.front)
+        throw new UsageError('multiview requires a front view');
+    if (inputs.length < 2)
+        throw new UsageError('multiview requires at least 2 views');
+    return {
+        request: {
+            endpoint: '/v3/generation/multiview-to-model',
+            payload: { inputs, model: normalizeModel(model), ...validated.params },
+        },
+        taskType: 'multiview_to_model',
+        warnings: validated.warnings,
+    };
+}
+/** Image generation: text-to-image / image-to-image. */
+export function buildTextToImage(prompt, params) {
+    return {
+        request: {
+            endpoint: '/v3/generation/text-to-image',
+            payload: { prompt, model: params.model ?? CAPABILITY_DEFAULTS.textToImage, ...omit(params, ['model']) },
+        },
+        taskType: 'generate_image',
+        warnings: [],
+    };
+}
+export function buildImageToImage(input, params) {
+    return {
+        request: {
+            endpoint: '/v3/generation/image-to-image',
+            payload: { input, model: params.model ?? CAPABILITY_DEFAULTS.imageToImage, ...omit(params, ['model']) },
+        },
+        taskType: 'image_to_image',
+        warnings: [],
+    };
+}
+export function buildImageToMultiview(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/image-to-multiview', payload: { input, ...params } },
+        taskType: 'generate_multiview_image',
+        warnings: [],
+    };
+}
+export function buildEditMultiview(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/edit-multiview', payload: { input, ...params } },
+        taskType: 'edit_multiview_image',
+        warnings: [],
+    };
+}
+export function buildImageToSplat(input, params) {
+    return {
+        request: { endpoint: '/v3/generation/image-to-splat', payload: { input, ...params } },
+        taskType: 'image_to_splat',
+        warnings: [],
+    };
+}
+/**
+ * Processing step (texture/convert/rig/...): validate per step, then build.
+ * `input` must already be a task_id / file_token / URL.
+ */
+export function buildStepRequest(stepName, input, args) {
+    const def = getStep(stepName);
+    if (!def)
+        throw new UsageError(`unknown step "${stepName}"`);
+    let params = { ...args };
+    const warnings = [];
+    switch (def.name) {
+        case 'convert': {
+            const v = validateConvertParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'decimate': {
+            const v = validateDecimateParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'retarget': {
+            const v = validateRetargetParams(params);
+            ensure(v);
+            params = v.params;
+            warnings.push(...v.warnings);
+            break;
+        }
+        case 'rig': {
+            if (params.model === undefined)
+                params.model = CAPABILITY_DEFAULTS.rig;
+            break;
+        }
+        case 'texture': {
+            if (params.model === undefined)
+                params.model = CAPABILITY_DEFAULTS.texture;
+            break;
+        }
+        case 'stylize': {
+            if (typeof params.style !== 'string') {
+                throw new UsageError('stylize requires style (lego/voxel/voronoi/minecraft)');
+            }
+            break;
+        }
+        case 'smartsegment': {
+            if (params.seg_type === undefined)
+                params.seg_type = 'model';
+            break;
+        }
+    }
+    return {
+        request: { endpoint: def.endpoint, payload: { input, ...params } },
+        taskType: def.produces,
+        warnings,
+    };
+}
+function omit(obj, keys) {
+    const out = { ...obj };
+    for (const k of keys)
+        delete out[k];
+    return out;
+}