@playcraft/cli 0.1.39-prod → 0.1.41-prod

package/dist/commands/tools-generation.js

@@ -3,9 +3,9 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
-import { readImageAssetContext } from '../utils/image-asset-context.js';
+import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
-import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
+import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
     if (opts.aspectRatio === '45:16')
         return true;
@@ -154,6 +154,7 @@ export function registerGenerationCommands(tools) {
         .option('--aspect-ratio <ratio>', '宽高比 (1:1|45:16|16:9|9:16|3:4|4:3|2:3|3:2|21:9)', '1:1')
         .requiredOption('--output <path>', '保存路径（--count>1 时自动追加 _1/_2 等后缀）')
         .option('--target-asset <path>', 'Existing asset to replace; read its schema references and delivery constraints')
+        .option('--target-field-path <path>', 'Target image field as an array of keys, e.g. ["endUI","playButton"]', parseImageTargetFieldPath)
         .option('--no-target-reference', 'Generate without the existing asset reference only when explicitly requested')
         .option('--output-format <format>', 'Final format: png, webp or jpeg')
         .option('--fit-mode <mode>', 'Canvas fitting: contain, cover or fill')
@@ -176,9 +177,16 @@ export function registerGenerationCommands(tools) {
                 throw new Error('Conflicting background options. Use --background transparent or --background opaque; no image request was sent.');
             }
             opts = { ...opts, removeBackground: explicitBackground };
+            if (opts.targetFieldPath && !opts.targetAsset) {
+                throw new Error('--target-field-path requires --target-asset; no image request was sent.');
+            }
             const explicitOutputFormat = opts.outputFormat;
+            const { dir: outputDir, name: outputName, ext: outputExt } = parse(opts.output);
+            const outputCandidates = [opts.output, ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`))];
             const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
                 referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
+                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                outputPaths: outputCandidates,
                 prompt: opts.prompt, removeBackground: opts.removeBackground,
             }) : undefined;
             opts = { ...opts,
@@ -343,6 +351,8 @@ export function registerGenerationCommands(tools) {
                         console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
                     }
                 }
+                if (assetContext)
+                    assertImageAssetOutputPaths(assetContext, [resolvedPath]);
                 mkdirSync(dirname(resolvedPath), { recursive: true });
                 writeFileSync(resolvedPath, imgBuf);
                 let actualWidth = null;

package/dist/commands/tools-image-context.js

@@ -1,9 +1,12 @@
 import { readImageAssetContext } from '../utils/image-asset-context.js';
-import { collectReferenceImagePaths, handleError } from './tools-utils.js';
+import { collectReferenceImagePaths, handleError, parseImageTargetFieldPath } from './tools-utils.js';
 export function registerImageContextCommand(tools) {
     tools.command('image-context')
         .description('Read image asset reference and delivery constraints locally; does not generate an image')
         .requiredOption('--asset-path <path>', 'Existing image asset path relative to the project')
+        .option('--target-field-path <path>', 'Target image field as an array of keys, e.g. ["endUI","playButton"]', parseImageTargetFieldPath)
+        .option('--output-path <path>', 'Intended output path; checks shared asset protection before generation', collectReferenceImagePaths, [])
+        .option('--allowed-output-root <path>', 'Additional output directory authorized by the caller; does not allow external references', collectReferenceImagePaths, [])
         .option('--reference-image <path>', 'Explicit local reference; may be repeated', collectReferenceImagePaths, [])
         .option('--no-target-reference', 'Do not use the target schema or current asset as a reference')
         .option('--prompt <text>', 'Generation request used to resolve background intent')
@@ -13,6 +16,9 @@ export function registerImageContextCommand(tools) {
         try {
             console.log(JSON.stringify(await readImageAssetContext(opts.assetPath, process.cwd(), {
                 referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
+                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                outputPaths: opts.outputPath,
+                allowedOutputRoots: opts.allowedOutputRoot,
                 prompt: opts.prompt, removeBackground: opts.removeBackground,
             })));
         }

package/dist/commands/tools-utils.js

@@ -1,8 +1,20 @@
 import { writeFileSync, mkdirSync, readFileSync } from 'fs';
 import { join, parse } from 'path';
 import { tmpdir } from 'os';
+import { InvalidArgumentError } from 'commander';
 export const TMP_DIR = join(tmpdir(), 'playcraft');
 export const MAX_REFERENCE_IMAGES = 8;
+export function parseImageTargetFieldPath(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch { /* Report the expected shape below. */ }
+    if (!Array.isArray(parsed) || !parsed.length || parsed.some(key => typeof key !== 'string' || !key.length)) {
+        throw new InvalidArgumentError('Expected an array of field names, e.g. ["endUI","playButton"].');
+    }
+    return parsed;
+}
 export function ensureTmpDir() {
     mkdirSync(TMP_DIR, { recursive: true });
 }

package/dist/utils/image-asset-context.js

@@ -1,27 +1,87 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import JSON5 from 'json5';
 import sharp from 'sharp';
 import { extractAssetFields, getByPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
+function isWithinDirectory(root, file) {
+    const relative = path.relative(root, file);
+    return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** Resolve existing ancestors so a new workspace need not have been created yet. */
+function realPathWithParents(file) {
+    let ancestor = file;
+    while (!existsSync(ancestor)) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw new Error(`Image path has no existing ancestor: ${file}`);
+        ancestor = parent;
+    }
+    return path.resolve(realpathSync(ancestor), path.relative(ancestor, file));
+}
+/** Resolve aliases and existing parent symlinks, including for a new output file. */
+function canonicalProjectPath(root, input) {
+    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
+    const file = path.resolve(root, mapped);
+    if (!isWithinDirectory(root, file)) {
+        throw new Error(`Image asset path is outside the project: ${input}`);
+    }
+    const real = realPathWithParents(file);
+    if (!isWithinDirectory(realPathWithParents(root), real)) {
+        throw new Error(`Image asset symlink is outside the project: ${input}`);
+    }
+    return real;
+}
+/** Check every extension a writer may choose before sending a generation request. */
+export function assertImageAssetOutputPaths(context, outputPaths, projectDir = process.cwd(), allowedOutputRoots = []) {
+    if (!context.requiresSeparateOutput)
+        return;
+    const root = path.resolve(projectDir);
+    const target = canonicalProjectPath(root, context.targetAssetPath);
+    const targetStat = statSync(target);
+    const outputRoots = [root, ...allowedOutputRoots.map(outputRoot => path.resolve(root, outputRoot))];
+    for (const output of outputPaths) {
+        const mapped = output.startsWith('/project/') ? output.slice('/project/'.length) : output;
+        const { dir, name } = path.parse(mapped);
+        // The response encoding can change the requested extension.
+        const candidates = [mapped, ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map(ext => path.join(dir, `${name}${ext}`))];
+        for (const candidate of candidates) {
+            const candidatePath = path.resolve(root, candidate);
+            const outputRoot = outputRoots.find(allowed => isWithinDirectory(allowed, candidatePath));
+            if (!outputRoot)
+                throw new Error(`Image output path is outside the project and allowed output roots: ${output}`);
+            const file = canonicalProjectPath(outputRoot, candidatePath);
+            const fileStat = existsSync(file) ? statSync(file) : undefined;
+            if (!path.relative(target, file) || (targetStat.ino !== 0 && fileStat?.ino === targetStat.ino && fileStat.dev === targetStat.dev)) {
+                throw new Error(`Cannot overwrite shared image asset ${context.targetAssetPath}: other fields have different requirements. Use a separate outputPath, then explicitly update the selected field reference; no shared asset was changed.`);
+            }
+        }
+    }
+}
 /** Resolve only real files in this project, including legacy /project aliases. */
 function projectFile(root, input) {
     const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
     const file = path.resolve(root, mapped);
-    const prefix = path.resolve(root) + path.sep;
-    if (!file.startsWith(prefix))
+    if (!isWithinDirectory(root, file))
         throw new Error(`Image asset path is outside the project: ${input}`);
     const real = realpathSync(file);
-    if (!real.startsWith(realpathSync(root) + path.sep))
+    if (!isWithinDirectory(realpathSync(root), real))
         throw new Error(`Image asset symlink is outside the project: ${input}`);
     return file;
 }
 /** Read the same per-field constraints used by the asset image dialog. */
 export async function readImageAssetContext(assetPath, projectDir = process.cwd(), options = {}) {
+    const targetFieldPath = options.targetFieldPath;
+    if (targetFieldPath !== undefined && (!Array.isArray(targetFieldPath)
+        || !targetFieldPath.length || targetFieldPath.some(key => typeof key !== 'string' || !key.length))) {
+        throw new Error('targetFieldPath must be a non-empty array of non-empty field names.');
+    }
     const root = path.resolve(projectDir);
     const target = projectFile(root, assetPath);
+    const realTarget = realpathSync(target);
+    const targetStat = statSync(target);
     const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
     const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
-    let field;
+    let fields = [];
     const schemaFile = path.join(root, THEME_SCHEMA_PATH);
     if (themeMatch && existsSync(schemaFile)) {
         const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
@@ -37,70 +97,132 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
             const value = typeof configured === 'string' ? configured : candidate.schema.default;
             if (typeof value !== 'string' || /^https?:\/\//i.test(value))
                 return false;
-            return path.resolve(themeRoot, value) === target;
+            const configuredPath = value.startsWith('/project/') ? path.resolve(root, value.slice('/project/'.length))
+                : path.resolve(themeRoot, value);
+            if (configuredPath === target)
+                return true;
+            try {
+                const candidateFile = projectFile(root, configuredPath);
+                if (!path.relative(realTarget, realpathSync(candidateFile)))
+                    return true;
+                const candidateStat = statSync(candidateFile);
+                return targetStat.ino !== 0 && candidateStat.ino === targetStat.ino && candidateStat.dev === targetStat.dev;
+            }
+            catch {
+                // Other fields may reference missing files or paths outside this project.
+                return false;
+            }
         });
-        if (matches.length > 1)
-            throw new Error('Multiple image fields use this asset; specify an unambiguous target asset.');
-        field = matches[0];
-        if (!field)
+        if (!matches.length)
             throw new Error(`No image schema field matches ${relativeTarget}; check theme.data.json5 before generating.`);
+        fields = matches;
+        if (targetFieldPath && !fields.some(candidate => candidate.path.length === targetFieldPath.length
+            && candidate.path.every((key, index) => key === targetFieldPath[index]))) {
+            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map(candidate => JSON.stringify(candidate.path)).join(', ')}.`);
+        }
+    }
+    else if (targetFieldPath) {
+        throw new Error('targetFieldPath requires an asset with a matching theme schema.');
     }
-    const xp = field?.schema.xplatform;
-    const ext = xp?.ext;
-    // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
-    const schemaReferences = Array.isArray(ext?.reference_image)
-        ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
-            const raw = ref.trim().replace(/\\/g, '/');
-            const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
-            if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
-                return normalized;
-            if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
-                return raw;
-            return path.posix.join('src/theme', themeMatch[1], normalized);
-        }) : [];
-    const referenceImagePaths = options.referenceImagePaths?.length ? options.referenceImagePaths
-        : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
-    if (referenceImagePaths.length > 8)
+    const targetMeta = await sharp(target).metadata();
+    let targetHasTransparency;
+    const contextForField = async (field) => {
+        const xp = field?.schema.xplatform;
+        const ext = xp?.ext;
+        // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
+        const schemaReferences = Array.isArray(ext?.reference_image)
+            ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
+                const raw = ref.trim().replace(/\\/g, '/');
+                const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
+                if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
+                    return normalized;
+                if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
+                    return raw;
+                return path.posix.join('src/theme', themeMatch[1], normalized);
+            }) : [];
+        const references = options.referenceImagePaths?.length ? options.referenceImagePaths
+            : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
+        const referenceImagePaths = references.map(ref => /^https?:\/\//i.test(ref) ? ref
+            : path.relative(realpathSync(root), canonicalProjectPath(root, ref)).replace(/\\/g, '/'));
+        const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
+        if (!hasSchemaBackground && targetHasTransparency === undefined) {
+            targetHasTransparency = !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
+        }
+        const removeBackground = resolveImageBackgroundRequirement({
+            prompt: options.prompt ?? '',
+            schemaRemoveBackground: hasSchemaBackground ? ext.remove_background : undefined,
+            removeBackground: options.removeBackground,
+            fallbackRemoveBackground: targetHasTransparency ?? false,
+        });
+        const delivery = resolveAiImageTargetConstraints({
+            schemaResolution: ext?.resolution,
+            schemaMimeType: xp?.mime_type,
+            schemaFitMode: xp?.fit_mode ?? ext?.fit_mode,
+            schemaRemoveBackground: removeBackground,
+            schemaPaddingColor: ext?.padding_color,
+            assetPath: relativeTarget,
+            referenceWidth: targetMeta.width,
+            referenceHeight: targetMeta.height,
+            referenceFormat: targetMeta.format,
+        });
+        if (!['png', 'webp', 'jpeg'].includes(delivery.format))
+            throw new Error('Unsupported image delivery format; use a dedicated animation or vector workflow.');
+        return {
+            targetAssetPath: relativeTarget,
+            fieldPath: field?.path,
+            referenceImagePaths,
+            width: delivery.width, height: delivery.height,
+            aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
+            outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
+                ? 'png' : delivery.format),
+            outputFormatFromSchema: delivery.fromSchemaMimeType,
+            fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
+            removeBackgroundFromSchema: hasSchemaBackground,
+            imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
+        };
+    };
+    const contexts = [];
+    let unresolvedSharedField = false;
+    for (const field of fields.length ? fields : [undefined]) {
+        try {
+            contexts.push(await contextForField(field));
+        }
+        catch (error) {
+            const selected = field?.path.length === targetFieldPath?.length
+                && field?.path.every((key, index) => key === targetFieldPath?.[index]);
+            if (!targetFieldPath || selected)
+                throw error;
+            // Invalid sibling requirements still protect the original shared file.
+            unresolvedSharedField = true;
+        }
+    }
+    const context = targetFieldPath ? contexts.find(candidate => candidate.fieldPath?.length === targetFieldPath.length
+        && candidate.fieldPath.every((key, index) => key === targetFieldPath[index])) : contexts[0];
+    const deliveryKey = ({ fieldPath: _fieldPath, outputFormatFromSchema: _formatSource, removeBackgroundFromSchema: _backgroundSource, aspectRatio, ...delivery }) => {
+        const ratio = aspectRatio.match(/^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/);
+        return JSON.stringify({ ...delivery, aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio });
+    };
+    const conflicting = unresolvedSharedField || contexts.some(candidate => deliveryKey(candidate) !== deliveryKey(context));
+    if (conflicting && !targetFieldPath) {
+        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map(field => JSON.stringify(field.path)).join(', ')}.`);
+    }
+    if (targetFieldPath) {
+        // A separate output retains exactly the selected field's requirements.
+        if (conflicting || contexts.some(candidate => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema)
+            || (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
+            context.requiresSeparateOutput = true;
+    }
+    else {
+        context.outputFormatFromSchema = contexts.some(candidate => candidate.outputFormatFromSchema);
+        context.removeBackgroundFromSchema = contexts.some(candidate => candidate.removeBackgroundFromSchema);
+    }
+    assertImageAssetOutputPaths(context, options.outputPaths ?? [], root, options.allowedOutputRoots);
+    if (context.referenceImagePaths.length > 8)
         throw new Error('At most 8 reference images are allowed.');
-    for (const ref of referenceImagePaths) {
+    for (const ref of context.referenceImagePaths) {
         if (/^https?:\/\//i.test(ref))
             throw new Error('Download the schema reference into the project before generating.');
         await sharp(projectFile(root, ref)).metadata();
     }
-    const targetMeta = await sharp(target).metadata();
-    const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
-    const targetStats = !hasSchemaBackground && targetMeta.hasAlpha ? await sharp(target).stats() : undefined;
-    const targetHasTransparency = !!targetStats && targetStats.channels.at(-1).min < 250;
-    const removeBackground = resolveImageBackgroundRequirement({
-        prompt: options.prompt ?? '',
-        schemaRemoveBackground: hasSchemaBackground ? ext.remove_background : undefined,
-        removeBackground: options.removeBackground,
-        fallbackRemoveBackground: targetHasTransparency,
-    });
-    const delivery = resolveAiImageTargetConstraints({
-        schemaResolution: ext?.resolution,
-        schemaMimeType: xp?.mime_type,
-        schemaFitMode: xp?.fit_mode ?? ext?.fit_mode,
-        schemaRemoveBackground: removeBackground,
-        schemaPaddingColor: ext?.padding_color,
-        assetPath: relativeTarget,
-        referenceWidth: targetMeta.width,
-        referenceHeight: targetMeta.height,
-        referenceFormat: targetMeta.format,
-    });
-    if (!['png', 'webp', 'jpeg'].includes(delivery.format))
-        throw new Error('Unsupported image delivery format; use a dedicated animation or vector workflow.');
-    return {
-        targetAssetPath: relativeTarget,
-        fieldPath: field?.path,
-        referenceImagePaths,
-        width: delivery.width, height: delivery.height,
-        aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
-        outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
-            ? 'png' : delivery.format),
-        outputFormatFromSchema: delivery.fromSchemaMimeType,
-        fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
-        removeBackgroundFromSchema: hasSchemaBackground,
-        imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
-    };
+    return context;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.39-prod",
+  "version": "0.1.41-prod",
   "private": false,
   "type": "module",
   "engines": {
@@ -45,8 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.38-beta",
-    "@playcraft/common": "^0.1.38-beta",
+    "@playcraft/build": "^0.1.40-beta",
+    "@playcraft/common": "^0.1.40-beta",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",