@meshy-ai/cli 0.2.0 → 0.3.1

package/dist/internal/artifacts.js

@@ -0,0 +1,280 @@
+/**
+ * Asset enumeration — which files a task exposes, under stable keys.
+ *
+ * Only known response fields are walked; an unknown string URL anywhere in
+ * `result` is reported under `unknown_urls` and never downloaded. Keys are
+ * the stable selectors of `meshy download --asset` and of the v1 download
+ * manifest; the file name is derived separately and never from the key or
+ * the URL alone.
+ *
+ * Product knowledge that changes the delivery format lives here too:
+ *   - lamp build: `lamp_stl` / `base_stl` are STL files, `bundle_zip` is a ZIP;
+ *   - keychain / fridge-magnet build: `model_urls.obj` is a ZIP bundle
+ *     (model.obj + model.mtl + texture.png), delivered as `.zip`, unextracted;
+ *   - motion clips carry their format in `result.motion_format`.
+ */
+import { safeExtension, safeSegment } from "./paths.js";
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "webp", "gif"]);
+function isUrl(v) {
+    return typeof v === "string" && /^https?:\/\//i.test(v);
+}
+/** Creative Lab product from a task type such as `creative-lab-keychain-build`. */
+export function productFromTaskType(type) {
+    if (typeof type !== "string")
+        return null;
+    const m = /^creative-lab-([a-z-]+?)-(prototype|build)$/.exec(type);
+    return m ? { product: m[1], stage: m[2] } : null;
+}
+/**
+ * The asset a `model_urls` entry stands for. Shared with the legacy `-o`
+ * downloader so both paths name Creative Lab parts the same way (`lamp.stl`,
+ * `base.stl`, `bundle.zip`, the keychain/fridge-magnet OBJ bundle as
+ * `model.obj.zip`) instead of turning the key into an extension.
+ */
+export function modelAsset(fmtKey, url, product) {
+    const key = `model.${fmtKey}`;
+    const sourcePath = `model_urls.${fmtKey}`;
+    switch (fmtKey) {
+        case "lamp_stl":
+            return { key, kind: "model", url, format: "stl", containerFormat: null, modelFormat: "stl", sourcePath, filename: "lamp.stl", dependencies: [], notes: { part: "lampshade" } };
+        case "base_stl":
+            return { key, kind: "model", url, format: "stl", containerFormat: null, modelFormat: "stl", sourcePath, filename: "base.stl", dependencies: [], notes: { part: "fixture_base" } };
+        case "bundle_zip":
+            return { key, kind: "model", url, format: "zip", containerFormat: "zip", modelFormat: null, sourcePath, filename: "bundle.zip", dependencies: [], notes: { extracted: false } };
+        case "pre_remeshed_glb":
+            return { key, kind: "model", url, format: "glb", containerFormat: null, modelFormat: "glb", sourcePath, filename: "model.pre_remeshed.glb", dependencies: [] };
+        default: {
+            const ext = safeExtension(fmtKey) || null;
+            if (ext === "obj" && (product === "keychain" || product === "fridge-magnet")) {
+                return { key, kind: "model", url, format: "zip", containerFormat: "zip", modelFormat: "obj", sourcePath, filename: "model.obj.zip", dependencies: [], notes: { extracted: false, bundle_contents: ["model.obj", "model.mtl", "texture.png"] } };
+            }
+            const deps = ext === "obj" ? ["model.mtl"] : [];
+            return { key, kind: "model", url, format: ext, containerFormat: null, modelFormat: ext, sourcePath, filename: ext ? `model.${ext}` : `model.${safeSegment(fmtKey)}`, dependencies: deps };
+        }
+    }
+}
+/**
+ * Enumerate every downloadable asset of a task object (raw API shape).
+ * `descriptor` (when known) supplies the product for Creative Lab builds.
+ */
+export function enumerateAssets(task, descriptor) {
+    const assets = [];
+    const unknown = [];
+    const product = descriptor?.creativeLab?.product ?? productFromTaskType(task["type"])?.product ?? null;
+    const modelUrls = task["model_urls"];
+    if (modelUrls && typeof modelUrls === "object" && !Array.isArray(modelUrls)) {
+        for (const [fmt, url] of Object.entries(modelUrls)) {
+            if (isUrl(url))
+                assets.push(modelAsset(fmt, url, product));
+        }
+    }
+    // OBJ depends on MTL only when the MTL exists in this task.
+    const hasMtl = assets.some((a) => a.key === "model.mtl");
+    for (const a of assets) {
+        if (a.key === "model.obj" && a.containerFormat === null) {
+            a.dependencies = hasMtl ? ["model.mtl", ...textureKeys(task)] : [];
+        }
+    }
+    if (isUrl(task["thumbnail_url"])) {
+        assets.push({ key: "thumbnail.primary", kind: "thumbnail", url: task["thumbnail_url"], format: "png", containerFormat: null, modelFormat: null, sourcePath: "thumbnail_url", filename: "thumbnail.png", dependencies: [] });
+    }
+    const thumbs = task["thumbnail_urls"];
+    if (thumbs && typeof thumbs === "object") {
+        if (Array.isArray(thumbs)) {
+            thumbs.forEach((url, i) => {
+                if (isUrl(url))
+                    assets.push({ key: `thumbnail.${i}`, kind: "thumbnail", url, format: "png", containerFormat: null, modelFormat: null, sourcePath: `thumbnail_urls[${i}]`, filename: `thumbnail_${i}.png`, dependencies: [] });
+            });
+        }
+        else {
+            for (const [view, url] of Object.entries(thumbs)) {
+                if (isUrl(url))
+                    assets.push({ key: `thumbnail.${safeSegment(view)}`, kind: "thumbnail", url, format: "png", containerFormat: null, modelFormat: null, sourcePath: `thumbnail_urls.${view}`, filename: `thumbnail_${safeSegment(view)}.png`, dependencies: [], notes: { view } });
+            }
+        }
+    }
+    if (isUrl(task["alpha_thumbnail_url"])) {
+        assets.push({ key: "thumbnail.alpha", kind: "thumbnail", url: task["alpha_thumbnail_url"], format: "png", containerFormat: null, modelFormat: null, sourcePath: "alpha_thumbnail_url", filename: "thumbnail_alpha.png", dependencies: [] });
+    }
+    const textures = task["texture_urls"];
+    if (Array.isArray(textures)) {
+        textures.forEach((set, i) => {
+            if (!set || typeof set !== "object")
+                return;
+            for (const [channel, url] of Object.entries(set)) {
+                if (isUrl(url)) {
+                    assets.push({ key: `texture.${i}.${safeSegment(channel)}`, kind: "texture", url, format: "png", containerFormat: null, modelFormat: null, sourcePath: `texture_urls[${i}].${channel}`, filename: `texture_${i}_${safeSegment(channel)}.png`, dependencies: [] });
+                }
+            }
+        });
+    }
+    const images = task["image_urls"];
+    if (Array.isArray(images)) {
+        images.forEach((url, i) => {
+            if (isUrl(url))
+                assets.push({ key: `image.${i}`, kind: "image", url, format: null, containerFormat: null, modelFormat: null, sourcePath: `image_urls[${i}]`, filename: `image_${i}`, dependencies: [] });
+        });
+    }
+    const result = task["result"];
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        const r = result;
+        const motionFormat = typeof r["motion_format"] === "string" ? safeExtension(r["motion_format"]) : "";
+        for (const [field, value] of Object.entries(r)) {
+            if (field === "basic_animations" && value && typeof value === "object" && !Array.isArray(value)) {
+                for (const [sub, url] of Object.entries(value)) {
+                    if (!isUrl(url))
+                        continue;
+                    const ext = extFromFieldName(sub);
+                    assets.push({ key: `result.basic_animations.${safeSegment(sub)}`, kind: "animation", url, format: ext, containerFormat: null, modelFormat: ext, sourcePath: `result.basic_animations.${sub}`, filename: `${safeSegment(sub.replace(/_url$/, ""))}${ext ? `.${ext}` : ""}`, dependencies: [] });
+                }
+                continue;
+            }
+            if (!isUrl(value)) {
+                if (value && typeof value === "object")
+                    collectUnknownUrls(value, `result.${field}`, unknown);
+                continue;
+            }
+            if (field === "motion_url") {
+                const ext = motionFormat === "fbx" || motionFormat === "bvh" ? motionFormat : null;
+                assets.push({ key: "result.motion_url", kind: "motion", url: value, format: ext, containerFormat: null, modelFormat: ext, sourcePath: "result.motion_url", filename: ext ? `motion.${ext}` : "motion", dependencies: [] });
+                continue;
+            }
+            if (/^rigged_character_(glb|fbx)_url$/.test(field)) {
+                const ext = extFromFieldName(field);
+                assets.push({ key: `result.${field}`, kind: "rig", url: value, format: ext, containerFormat: null, modelFormat: ext, sourcePath: `result.${field}`, filename: `rigged_character.${ext}`, dependencies: [] });
+                continue;
+            }
+            if (/^(animation_(glb|fbx)_url|processed_[a-z0-9_]+_url)$/.test(field)) {
+                const ext = extFromFieldName(field);
+                assets.push({ key: `result.${field}`, kind: "animation", url: value, format: ext, containerFormat: null, modelFormat: ext, sourcePath: `result.${field}`, filename: `${safeSegment(field.replace(/_url$/, ""))}${ext ? `.${ext}` : ""}`, dependencies: [] });
+                continue;
+            }
+            unknown.push({ path: `result.${field}`, url: value });
+        }
+    }
+    const printability = task["printability"];
+    if (printability && typeof printability === "object") {
+        assets.push({ key: "report.printability", kind: "report", url: null, format: "json", containerFormat: null, modelFormat: null, sourcePath: "printability", filename: "printability.json", dependencies: [], report: printability });
+    }
+    return { assets, unknown_urls: unknown, product };
+}
+function textureKeys(task) {
+    const keys = [];
+    const textures = task["texture_urls"];
+    if (Array.isArray(textures)) {
+        textures.forEach((set, i) => {
+            if (!set || typeof set !== "object")
+                return;
+            for (const [channel, url] of Object.entries(set)) {
+                if (isUrl(url))
+                    keys.push(`texture.${i}.${safeSegment(channel)}`);
+            }
+        });
+    }
+    return keys;
+}
+function extFromFieldName(field) {
+    const m = /_(glb|fbx|usdz|obj|bvh|png|jpg|jpeg|webp|gltf|stl|3mf)_url$/i.exec(field);
+    if (m)
+        return m[1].toLowerCase();
+    // processed_usdz_url → usdz ; processed_armature_fbx_url → fbx handled above ; processed_animation_fps_fbx_url → fbx
+    return null;
+}
+function collectUnknownUrls(value, path, out) {
+    if (isUrl(value)) {
+        out.push({ path, url: value });
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => collectUnknownUrls(v, `${path}[${i}]`, out));
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const [k, v] of Object.entries(value))
+            collectUnknownUrls(v, `${path}.${k}`, out);
+    }
+}
+/** 0.2.0 artifact keys → stable keys, so old scripts and internal tests keep resolving. */
+export const LEGACY_KEY_ALIASES = {
+    thumbnail: "thumbnail.primary",
+    motion_url: "result.motion_url",
+};
+export function resolveAssetKey(requested, assets) {
+    const direct = assets.find((a) => a.key === requested);
+    if (direct)
+        return direct;
+    const alias = LEGACY_KEY_ALIASES[requested];
+    if (alias)
+        return assets.find((a) => a.key === alias);
+    let m = /^model_([a-z0-9_]+)$/i.exec(requested);
+    if (m)
+        return assets.find((a) => a.key === `model.${m[1]}`);
+    m = /^image_(\d+)$/.exec(requested);
+    if (m)
+        return assets.find((a) => a.key === `image.${m[1]}`);
+    m = /^texture_(\d+)_([a-z0-9_]+)$/i.exec(requested);
+    if (m)
+        return assets.find((a) => a.key === `texture.${m[1]}.${m[2]}`);
+    m = /^([a-z0-9_]+_url)$/i.exec(requested);
+    if (m)
+        return assets.find((a) => a.key === `result.${m[1]}` || a.key === `result.basic_animations.${m[1]}`);
+    return undefined;
+}
+/**
+ * Apply a selector to the enumeration. Exactly one selector kind must be
+ * given; contradictory combinations are rejected by the caller (usage).
+ * With `withDependencies`, an OBJ selection pulls its MTL and textures.
+ */
+export function selectAssets(enumeration, sel, opts) {
+    const { assets } = enumeration;
+    let selected;
+    if (sel.all)
+        selected = assets.filter((a) => a.url !== null || a.kind === "report");
+    else if (sel.keys && sel.keys.length > 0) {
+        selected = [];
+        for (const k of sel.keys) {
+            const a = resolveAssetKey(k, assets);
+            if (!a)
+                throw new SelectionError(`no asset with key '${k}'`, assets);
+            if (!selected.includes(a))
+                selected.push(a);
+        }
+    }
+    else if (sel.modelFormat) {
+        const fmt = sel.modelFormat.toLowerCase();
+        selected = assets.filter((a) => a.kind === "model" && (a.key === `model.${fmt}` || a.modelFormat === fmt || a.format === fmt));
+        if (selected.length === 0)
+            throw new SelectionError(`no model asset in format '${sel.modelFormat}'`, assets);
+    }
+    else if (sel.kind) {
+        selected = assets.filter((a) => a.kind === sel.kind);
+        if (selected.length === 0)
+            throw new SelectionError(`no asset of kind '${sel.kind}'`, assets);
+    }
+    else {
+        throw new SelectionError("no selector given", assets);
+    }
+    const dependencies = [];
+    const missing = [];
+    if (opts.withDependencies) {
+        for (const a of selected) {
+            for (const dep of a.dependencies) {
+                const d = assets.find((x) => x.key === dep);
+                if (!d)
+                    missing.push(dep);
+                else if (!selected.includes(d) && !dependencies.includes(d))
+                    dependencies.push(d);
+            }
+        }
+    }
+    return { selected, dependencies, missingDependencies: missing };
+}
+export class SelectionError extends Error {
+    candidates;
+    constructor(message, assets) {
+        super(message);
+        this.name = "SelectionError";
+        this.candidates = assets.map((a) => ({ key: a.key, kind: a.kind, format: a.format }));
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/internal/artifacts.js.map

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

package/dist/internal/atomic-file.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Exclusive and atomic file publication.
+ *
+ * Two contracts:
+ *   - no-overwrite (default): the target must not exist when the file lands.
+ *     `exists → rename` is a race (POSIX rename replaces a concurrent
+ *     winner), so the temp file is published with `link()`, which fails
+ *     atomically with EEXIST. Where hard links are unsupported the fallback
+ *     opens the target with O_EXCL and copies — still exclusive, no longer
+ *     atomic, and reported as such.
+ *   - overwrite: `rename()` over a target that is a regular file (or absent).
+ *     Directories and symlinks are never replaced.
+ *
+ * Temp files always live in the target directory (same filesystem) and are
+ * removed on every failure path.
+ */
+import { CliError } from "./errors.js";
+export type PublishMethod = "link" | "rename" | "copy-exclusive";
+export interface PublishOptions {
+    overwrite?: boolean;
+}
+export interface PublishResult {
+    path: string;
+    method: PublishMethod;
+}
+export declare function tempPathFor(target: string): string;
+export declare function refuseOverwriteError(target: string): CliError;
+/**
+ * Move a fully written temp file onto `target`.
+ * The temp file is consumed (removed) whether or not publication succeeds.
+ */
+export declare function publishTempFile(tmp: string, target: string, opts?: PublishOptions): PublishResult;
+/** Serialise `value` as pretty JSON and publish it exclusively (or atomically replace with overwrite). */
+export declare function writeJsonFile(target: string, value: unknown, opts?: PublishOptions & {
+    mode?: number;
+}): PublishResult;
+/** Copy an existing file to `target` under the same publish rules. */
+export declare function copyFilePublished(source: string, target: string, opts?: PublishOptions): PublishResult;
+//# sourceMappingURL=atomic-file.d.ts.map

package/dist/internal/atomic-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkBH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AA2BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAM7D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CAyDrG;AAED,0GAA0G;AAC1G,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,cAAc,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,aAAa,CAcf;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CAc1G"}

package/dist/internal/atomic-file.js

@@ -0,0 +1,160 @@
+/**
+ * Exclusive and atomic file publication.
+ *
+ * Two contracts:
+ *   - no-overwrite (default): the target must not exist when the file lands.
+ *     `exists → rename` is a race (POSIX rename replaces a concurrent
+ *     winner), so the temp file is published with `link()`, which fails
+ *     atomically with EEXIST. Where hard links are unsupported the fallback
+ *     opens the target with O_EXCL and copies — still exclusive, no longer
+ *     atomic, and reported as such.
+ *   - overwrite: `rename()` over a target that is a regular file (or absent).
+ *     Directories and symlinks are never replaced.
+ *
+ * Temp files always live in the target directory (same filesystem) and are
+ * removed on every failure path.
+ */
+import { closeSync, copyFileSync, constants as fsConstants, linkSync, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, writeSync, readFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { CliError } from "./errors.js";
+export function tempPathFor(target) {
+    return join(dirname(target), `.${basename(target)}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`);
+}
+function errno(err) {
+    return err?.code;
+}
+function removeQuietly(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Create the target's directory; a parent that is a file (or unwritable) is a local_io error, not an internal one. */
+function ensureParentDir(target) {
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+    }
+    catch (err) {
+        throw new CliError({
+            code: "local_io",
+            message: `cannot create directory ${dirname(target)}: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        });
+    }
+}
+export function refuseOverwriteError(target) {
+    return new CliError({
+        code: "local_io",
+        message: `refusing to overwrite existing file: ${target} (pass --overwrite, or choose another path)`,
+        recovery: { action: "choose_path", automatic: false },
+    });
+}
+/**
+ * Move a fully written temp file onto `target`.
+ * The temp file is consumed (removed) whether or not publication succeeds.
+ */
+export function publishTempFile(tmp, target, opts = {}) {
+    try {
+        if (opts.overwrite) {
+            let existing = null;
+            try {
+                existing = lstatSync(target);
+            }
+            catch (err) {
+                if (errno(err) !== "ENOENT")
+                    throw err;
+            }
+            if (existing && !existing.isFile()) {
+                throw new CliError({
+                    code: "local_io",
+                    message: `refusing to replace ${target}: it is not a regular file`,
+                });
+            }
+            renameSync(tmp, target);
+            return { path: target, method: "rename" };
+        }
+        try {
+            linkSync(tmp, target);
+            unlinkSync(tmp);
+            return { path: target, method: "link" };
+        }
+        catch (err) {
+            const code = errno(err);
+            if (code === "EEXIST")
+                throw refuseOverwriteError(target);
+            if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV" && code !== "EOPNOTSUPP" && code !== "EACCES" && code !== "EMLINK") {
+                throw err;
+            }
+            // Hard links unavailable on this filesystem: exclusive create + copy.
+            let fd;
+            try {
+                fd = openSync(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+            }
+            catch (openErr) {
+                if (errno(openErr) === "EEXIST")
+                    throw refuseOverwriteError(target);
+                throw openErr;
+            }
+            try {
+                const data = readFileSync(tmp);
+                let offset = 0;
+                while (offset < data.length) {
+                    offset += writeSync(fd, data, offset, data.length - offset);
+                }
+            }
+            finally {
+                closeSync(fd);
+            }
+            unlinkSync(tmp);
+            return { path: target, method: "copy-exclusive" };
+        }
+    }
+    catch (err) {
+        removeQuietly(tmp);
+        if (err instanceof CliError)
+            throw err;
+        throw new CliError({
+            code: "local_io",
+            message: `failed to write ${target}: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        });
+    }
+}
+/** Serialise `value` as pretty JSON and publish it exclusively (or atomically replace with overwrite). */
+export function writeJsonFile(target, value, opts = {}) {
+    ensureParentDir(target);
+    const tmp = tempPathFor(target);
+    try {
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: opts.mode ?? 0o600 });
+    }
+    catch (err) {
+        removeQuietly(tmp);
+        throw new CliError({
+            code: "local_io",
+            message: `failed to write ${target}: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        });
+    }
+    return publishTempFile(tmp, target, opts);
+}
+/** Copy an existing file to `target` under the same publish rules. */
+export function copyFilePublished(source, target, opts = {}) {
+    ensureParentDir(target);
+    const tmp = tempPathFor(target);
+    try {
+        copyFileSync(source, tmp);
+    }
+    catch (err) {
+        removeQuietly(tmp);
+        throw new CliError({
+            code: "local_io",
+            message: `failed to copy ${source} → ${target}: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+        });
+    }
+    return publishTempFile(tmp, target, opts);
+}
+//# sourceMappingURL=atomic-file.js.map

package/dist/internal/atomic-file.js.map

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

package/dist/internal/command-helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Small shared pieces every command action uses:
+ *   - open the command context (name, schema, format) so the error exit can
+ *     render in the right shape;
+ *   - render a result in either schema;
+ *   - save the raw API JSON (--save-json) with exclusive publication.
+ */
+import { Command } from "commander";
+import { type CommandContext } from "./context.js";
+import { type Warning } from "./errors.js";
+import { type OutputFormat } from "./output.js";
+import { type OutputSchema } from "./result.js";
+import { type GlobalFlags } from "./runtime.js";
+import { type AuthorisedRoot } from "./paths.js";
+export interface OpenedCommand extends CommandContext {
+    flags: GlobalFlags;
+}
+/** Read global flags, decide the schema and register the command context. */
+export declare function openCommand(thisCmd: Command, command: string, defaultSchema: OutputSchema): OpenedCommand;
+/**
+ * Print a command result. Legacy keeps the bare payload (and the historical
+ * `-o <file>` meaning "write the JSON there" for non-task commands); v1 prints
+ * the envelope and treats `-o` on a non-task command as a usage error that
+ * points at --save-json.
+ */
+export declare function emitResult(opened: OpenedCommand, legacyValue: unknown, v1Result: unknown, opts?: {
+    warnings?: Warning[];
+    legacyFile?: string | undefined;
+    format?: OutputFormat;
+}): Promise<void>;
+/** v1: `-o` is reserved for assets; JSON goes through --save-json. */
+export declare function rejectOutputFlagForV1(opened: OpenedCommand, saveJson: string | undefined): void;
+export interface SavedJson {
+    path: string;
+    bytes: number;
+}
+/**
+ * Save the raw JSON the API returned (never the CLI envelope). The file is
+ * published exclusively; an existing file is an error unless `overwrite`.
+ */
+export declare function saveRawJson(target: string, raw: unknown, opts?: {
+    workspace?: string | AuthorisedRoot | undefined;
+    overwrite?: boolean;
+    cwd?: string;
+}): SavedJson;
+//# sourceMappingURL=command-helpers.d.ts.map

package/dist/internal/command-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../src/internal/command-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAkC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,GAAG,aAAa,CAKzG;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,OAAO,EACpB,QAAQ,EAAE,OAAO,EACjB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC1F,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQ/F;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAChG,SAAS,CAQX"}

package/dist/internal/command-helpers.js

@@ -0,0 +1,61 @@
+/**
+ * Small shared pieces every command action uses:
+ *   - open the command context (name, schema, format) so the error exit can
+ *     render in the right shape;
+ *   - render a result in either schema;
+ *   - save the raw API JSON (--save-json) with exclusive publication.
+ */
+import { dirname, resolve as resolvePath } from "node:path";
+import { beginCommand } from "./context.js";
+import { UsageError } from "./errors.js";
+import { emit, emitEnvelope } from "./output.js";
+import { okEnvelope } from "./result.js";
+import { readGlobalFlags, resolveSchema } from "./runtime.js";
+import { writeJsonFile } from "./atomic-file.js";
+import { resolveWithinRoot } from "./paths.js";
+/** Read global flags, decide the schema and register the command context. */
+export function openCommand(thisCmd, command, defaultSchema) {
+    const flags = readGlobalFlags(thisCmd);
+    const schema = resolveSchema(flags, defaultSchema);
+    const ctx = beginCommand({ command, schema, format: flags.format });
+    return { ...ctx, flags };
+}
+/**
+ * Print a command result. Legacy keeps the bare payload (and the historical
+ * `-o <file>` meaning "write the JSON there" for non-task commands); v1 prints
+ * the envelope and treats `-o` on a non-task command as a usage error that
+ * points at --save-json.
+ */
+export async function emitResult(opened, legacyValue, v1Result, opts = {}) {
+    const format = opts.format ?? opened.format;
+    if (opened.schema === "v1") {
+        await emitEnvelope(okEnvelope(opened.command, v1Result, opts.warnings ?? []), format);
+        return;
+    }
+    emit(legacyValue, { format, file: opts.legacyFile });
+}
+/** v1: `-o` is reserved for assets; JSON goes through --save-json. */
+export function rejectOutputFlagForV1(opened, saveJson) {
+    if (opened.schema !== "v1")
+        return;
+    if (opened.flags.output && saveJson) {
+        throw new UsageError("--output/-o and --save-json cannot be combined on this command; -o is for assets, --save-json for the raw JSON");
+    }
+    if (opened.flags.output) {
+        throw new UsageError("this command produces JSON, not assets: use --save-json <file> instead of --output/-o under --output-schema v1");
+    }
+}
+/**
+ * Save the raw JSON the API returned (never the CLI envelope). The file is
+ * published exclusively; an existing file is an error unless `overwrite`.
+ */
+export function saveRawJson(target, raw, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const abs = resolvePath(cwd, target);
+    const root = opts.workspace ?? dirname(abs);
+    const resolved = resolveWithinRoot(abs, root, { cwd, label: "--save-json target" });
+    const text = `${JSON.stringify(raw, null, 2)}\n`;
+    writeJsonFile(resolved.path, raw, { overwrite: opts.overwrite ?? false });
+    return { path: resolved.path, bytes: Buffer.byteLength(text, "utf8") };
+}
+//# sourceMappingURL=command-helpers.js.map

package/dist/internal/command-helpers.js.map

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