@meshy-ai/cli 0.2.0 → 0.3.0

package/dist/internal/inspect.js

@@ -0,0 +1,111 @@
+/**
+ * Face-count gate — the verdict logic behind `meshy inspect faces`.
+ *
+ * The legacy Skill's check-faces script defaulted a missing face_count to 0 and
+ * printed a passing line for a model it never measured. Nothing here fabricates
+ * a number: only a finite, non-negative integer that the task actually carries
+ * is "known"; everything else is `unknown`, which the command turns into exit
+ * 13 rather than a pass (D-009). Strings are never parsed into numbers — a
+ * `"1234"` that the server never meant as a count must not become one here.
+ *
+ * The gate answers exactly one question — is face_count <= the caller's limit?
+ * It knows nothing about rigging eligibility (mesh shape, textures, humanoid
+ * proportions), so nothing in this module says "rig-ready". When it fails it
+ * can describe a remesh that would help; it never runs one.
+ */
+import { isTerminalStatus } from "../client/types.js";
+/** The remesh endpoint's accepted target_polycount range (see cmd/remesh.ts). */
+export const REMESH_POLYCOUNT_RANGE = { min: 100, max: 300_000 };
+/** Task ids are echoed into a shell command only when they are plain tokens. */
+const SAFE_TASK_ID = /^[A-Za-z0-9._:-]+$/;
+function assertLimit(limit) {
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) {
+        throw new RangeError(`face-count limit must be a positive integer (got ${String(limit)})`);
+    }
+}
+function describe(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (value === null)
+        return "null";
+    return typeof value;
+}
+/**
+ * Judge a raw face_count against `limit`. Only a finite, non-negative integer is
+ * a known count; `<= limit` passes, anything larger fails, everything else is
+ * unknown with a reason that names what was wrong.
+ */
+export function judgeFaceCount(raw, limit) {
+    assertLimit(limit);
+    const unknown = (reason) => ({ face_count: null, limit, comparison: "lte", verdict: "unknown", reason });
+    if (raw === undefined)
+        return unknown("face_count missing");
+    if (raw === null)
+        return unknown("face_count is null");
+    if (typeof raw === "string") {
+        const shown = raw.length > 40 ? `${raw.slice(0, 40)}…` : raw;
+        return unknown(`face_count is a string, not a number (${JSON.stringify(shown)} is not parsed)`);
+    }
+    if (typeof raw !== "number")
+        return unknown(`face_count is not a number (got ${describe(raw)})`);
+    if (!Number.isFinite(raw))
+        return unknown(`face_count is not a finite number (got ${String(raw)})`);
+    if (!Number.isInteger(raw) || raw < 0)
+        return unknown(`face_count is not a non-negative integer (got ${raw})`);
+    if (raw <= limit)
+        return { face_count: raw, limit, comparison: "lte", verdict: "pass", reason: null };
+    return {
+        face_count: raw,
+        limit,
+        comparison: "lte",
+        verdict: "fail",
+        reason: `face_count ${raw} exceeds the limit ${limit} by ${raw - limit}`,
+    };
+}
+/**
+ * Read the top-level `face_count` of a task object. Nothing is derived from
+ * other fields and nothing is defaulted: an absent key is reported as absent.
+ */
+export function faceCountFromTask(task) {
+    const status = typeof task["status"] === "string" ? task["status"] : null;
+    if (Object.prototype.hasOwnProperty.call(task, "face_count")) {
+        return { value: task["face_count"], source: "face_count", status };
+    }
+    return { value: undefined, source: "none", status };
+}
+/**
+ * Judge a whole task: the top-level face_count against `limit`. A task that
+ * has not finished and carries no count is unknown *because it is still
+ * running* — the reason says so instead of implying the field will never come.
+ */
+export function judgeTask(task, limit) {
+    const { value, status } = faceCountFromTask(task);
+    const verdict = judgeFaceCount(value, limit);
+    if (verdict.verdict === "unknown" && (value === undefined || value === null) && status !== null && !isTerminalStatus(status)) {
+        return { ...verdict, reason: `task is ${status}; no face count yet` };
+    }
+    return verdict;
+}
+/**
+ * Describe — never execute — the remesh that would bring a model under `limit`.
+ * The target is clamped to the range the remesh endpoint accepts.
+ */
+export function remeshSuggestion(taskId, limit) {
+    const target = Math.min(Math.max(Math.trunc(limit), REMESH_POLYCOUNT_RANGE.min), REMESH_POLYCOUNT_RANGE.max);
+    const flags = `--target-polycount ${target} --output-schema v1`;
+    if (taskId && SAFE_TASK_ID.test(taskId)) {
+        const command = `meshy remesh create --input-task-id ${taskId} ${flags}`;
+        return {
+            description: `Reduce the polycount with a remesh task targeting ${target} faces (billable; not executed by inspect — run it yourself): ${command}`,
+            command,
+            executed: false,
+        };
+    }
+    const why = taskId ? "the task id contains characters that are not safe to echo into a command" : "the source task id is unknown";
+    return {
+        description: `Reduce the polycount with a remesh task targeting ${target} faces (billable; not executed by inspect). ${why}; run: meshy remesh create --model-url <file-or-url> ${flags}`,
+        command: null,
+        executed: false,
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/internal/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/internal/inspect.ts"],"names":[],"mappings":"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"}

package/dist/internal/lock.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-process exclusive lock on a directory-scoped lock file.
+ *
+ * O_EXCL creation is the atomic primitive (Node exposes no flock). A lock
+ * older than `staleMs` is treated as abandoned by a crashed process and
+ * broken. Waiting is a blocking sleep because every store that uses this is
+ * synchronous by design; the wait is bounded and a timeout is a structured
+ * error rather than a hang.
+ */
+export interface LockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    /** Test hook to observe contention. */
+    onWait?: () => void;
+}
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 10000;
+export declare const DEFAULT_LOCK_STALE_MS = 60000;
+export declare function withFileLock<T>(lockPath: string, fn: () => T, opts?: LockOptions): T;
+//# sourceMappingURL=lock.d.ts.map

package/dist/internal/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/internal/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAM5C,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,GAAE,WAAgB,GAAG,CAAC,CA0CxF"}

package/dist/internal/lock.js

@@ -0,0 +1,66 @@
+/**
+ * Cross-process exclusive lock on a directory-scoped lock file.
+ *
+ * O_EXCL creation is the atomic primitive (Node exposes no flock). A lock
+ * older than `staleMs` is treated as abandoned by a crashed process and
+ * broken. Waiting is a blocking sleep because every store that uses this is
+ * synchronous by design; the wait is bounded and a timeout is a structured
+ * error rather than a hang.
+ */
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { CliError } from "./errors.js";
+export const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+export const DEFAULT_LOCK_STALE_MS = 60_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export function withFileLock(lockPath, fn, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const staleMs = opts.staleMs ?? DEFAULT_LOCK_STALE_MS;
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + timeoutMs;
+    let fd;
+    for (;;) {
+        try {
+            fd = openSync(lockPath, "wx", 0o600);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > staleMs) {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                // Holder released between open and stat — retry immediately.
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new CliError({
+                    code: "local_io",
+                    message: `timed out after ${timeoutMs}ms waiting for the lock ${lockPath}. If no other meshy process is running, delete that file.`,
+                    recovery: { action: "retry", automatic: false },
+                });
+            }
+            opts.onWait?.();
+            sleepSync(25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        closeSync(fd);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/internal/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/internal/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AASvC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,SAAS,SAAS,CAAC,EAAU;IAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,YAAY,CAAI,QAAgB,EAAE,EAAW,EAAE,IAAI,GAAgB,EAAE;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,uBAAuB,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,qBAAqB,CAAC;IACtD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,IAAI,EAAU,CAAC;IACf,SAAS,CAAC;QACR,IAAI,CAAC;YACH,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACrC,MAAM;QACR,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,IAAI,CAAC;gBACH,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,GAAG,OAAO,EAAE,CAAC;oBACtD,UAAU,CAAC,QAAQ,CAAC,CAAC;oBACrB,SAAS;gBACX,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,6DAA6D;gBAC7D,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC3B,MAAM,IAAI,QAAQ,CAAC;oBACjB,IAAI,EAAE,UAAU;oBAChB,OAAO,EAAE,mBAAmB,SAAS,2BAA2B,QAAQ,2DAA2D;oBACnI,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE;iBAChD,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAChB,SAAS,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,IAAI,CAAC;YACH,UAAU,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/internal/material-links.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Material relinking for downloaded OBJ sets.
+ *
+ * Meshy serves an OBJ, its MTL and the textures as separate URLs and the CLI
+ * saves them under stable names (model.obj, model.mtl, texture_0_base_color.png
+ * …). The OBJ, however, names its MTL the way the server knew it (`mtllib
+ * box.mtl`) and the MTL names its textures the same way, so a faithfully
+ * downloaded set can still be unloadable. Once every file of a set has landed,
+ * this module rewrites those references to the names actually on disk and
+ * reports every link it resolved — and every one it could not. Only the two
+ * text files the CLI itself just wrote are touched; nothing is renamed, the
+ * rewritten paths are listed, and their digests are re-taken by the caller.
+ *
+ * A texture reference is resolved only when exactly one downloaded texture
+ * matches, in this order: the name the server served a texture under (the
+ * URL's last segment — `body.png` for `…/body.png`), which is the only evidence
+ * of *which* image the MTL meant; a saved file of that name, but only when it
+ * is not known to come from a different source (the CLI's generated names
+ * `texture_<n>_<channel>` can collide with a server-side name of another
+ * texture — that is an ambiguity, not a match); the same name ignoring
+ * extension and directories; a channel word inside the referenced name
+ * (…_normal.png); the channel implied by the MTL key (map_Kd → base color);
+ * finally "the only texture there is" when the MTL has exactly one distinct
+ * reference. Several candidates for the same rule is an *ambiguity*: the
+ * reference stays as written, the candidates are listed and the report is
+ * `incomplete` — the CLI never picks the first of several material groups'
+ * textures.
+ *
+ * The first three rules are *identity* evidence; the channel and only-texture
+ * rules are *heuristics*. Resolution therefore runs in two passes over the
+ * whole MTL: every distinct reference is resolved on its own first, then the
+ * heuristic results are checked against each other — a texture that several
+ * different references would fall back to (whichever channel rule each one
+ * took to get there, in whichever order they appear) serves none of them, and a
+ * reference that different keys would send to different textures is not
+ * rewritten either. Two material groups collapsing onto one image without
+ * evidence that they name the same file is exactly the guess this module must
+ * not make; a reference with identity evidence keeps its texture regardless.
+ * Unresolved references are reported the same way. The whole pass is
+ * cooperative: an abort signal stops it before the next read, write or
+ * publication, leaving no temp file behind.
+ */
+import { type Warning } from "./errors.js";
+export interface LinkableFile {
+    /** Stable asset key (`model.obj`, `model_mtl`, `texture.0.base_color`, `texture_0_normal` …). */
+    key: string;
+    /** Absolute path as written. */
+    path: string;
+    /** The file name the server served the asset under (last URL path segment), when known. */
+    sourceName?: string | null;
+}
+export type LinkMethod = "unchanged" | "exact" | "source_name" | "source_stem" | "channel_in_name" | "channel_of_key" | "only_texture" | "downloaded_mtl" | "ambiguous" | "unresolved";
+export interface ReferenceLink {
+    /** 1-based line in the file that carried the reference. */
+    line: number;
+    /** `newmtl` group the map belongs to (MTL only). */
+    material: string | null;
+    /** The reference as written before relinking. */
+    reference: string;
+    /** Saved file name the reference now points at, or null when it stays as written. */
+    resolved_to: string | null;
+    /** How the link was decided. */
+    method: LinkMethod;
+    /** Saved names that matched when the reference was ambiguous. */
+    candidates?: string[];
+    /** Why an apparently matching saved name was not accepted (identity conflict). */
+    note?: string;
+}
+export interface TextureDescriptor {
+    key: string;
+    /** Saved file name. */
+    name: string;
+    /** Name the server served it under, when known. */
+    source_name: string | null;
+    /** `texture_urls` set index (material group) the texture came from. */
+    set: number | null;
+    /** Canonical channel (basecolor, normal, …) from the asset key. */
+    channel: string | null;
+}
+export interface MaterialLinkReport {
+    obj: string;
+    mtl: string | null;
+    textures: TextureDescriptor[];
+    mtllib: ReferenceLink[];
+    texture_maps: ReferenceLink[];
+    /** Absolute paths whose content was rewritten. */
+    rewritten: string[];
+    /** `complete` when every reference points at a downloaded file; `incomplete` when any stayed as written. */
+    status: "complete" | "incomplete";
+    warnings: Warning[];
+}
+/** Set index and channel encoded in an asset key: `texture.0.base_color` / `texture_0_base_color`. */
+export declare function describeTextureKey(key: string): {
+    set: number | null;
+    channel: string | null;
+};
+/** @deprecated kept for callers of the round-1 API. */
+export declare function channelOfTextureKey(key: string): string | null;
+/** Channel word inside a referenced file name (`texture_normal.png`, `Body_BaseColor.jpg`). */
+export declare function channelInFileName(name: string): string | null;
+/** sha256 + size of a file, for manifests that must describe what is actually on disk. */
+export declare function fileDigest(path: string): {
+    bytes: number;
+    sha256: string;
+};
+/**
+ * Relink the OBJ/MTL/texture files of one download. Returns null when the set
+ * has no text OBJ (nothing to relink). Never throws for unresolved or
+ * ambiguous references; those become warnings, `resolved_to: null` entries
+ * and `status: "incomplete"`.
+ */
+export declare function relinkMaterials(files: readonly LinkableFile[], opts?: {
+    signal?: AbortSignal;
+}): Promise<MaterialLinkReport | null>;
+//# sourceMappingURL=material-links.d.ts.map

package/dist/internal/material-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-links.d.ts","sourceRoot":"","sources":["../../src/internal/material-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AASH,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAGrD,MAAM,WAAW,YAAY;IAC3B,iGAAiG;IACjG,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,OAAO,GACP,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,WAAW,GACX,YAAY,CAAC;AAEjB,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gCAAgC;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uEAAuE;IACvE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,kDAAkD;IAClD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4GAA4G;IAC5G,MAAM,EAAE,UAAU,GAAG,YAAY,CAAC;IAClC,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AA2DD,sGAAsG;AACtG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAI9F;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE9D;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc7D;AAwBD,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAG1E;AA8QD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA2I7I"}