@playcraft/cli 0.0.55 → 0.0.56

package/dist/commands/image.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 import yaml from 'js-yaml';
 import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
 const DEFAULT_MAX_INPUT_BYTES = 512 * 1024 * 1024;
 function getMaxInputBytes() {
@@ -20,23 +21,26 @@ function cliParseInt(value) {
     return Number.parseInt(value, 10);
 }
 function assertInputWithinLimit(filePath, label = 'input') {
+    const resolved = resolveSandboxPath(filePath);
     const max = getMaxInputBytes();
-    const st = statSync(filePath);
+    const st = statSync(resolved);
     if (!st.isFile()) {
-        console.error(`Error: ${label} is not a regular file: ${filePath}`);
+        console.error(`Error: ${label} is not a regular file: ${resolved}`);
         process.exit(1);
     }
     if (st.size > max) {
         console.error(`Error: ${label} file too large (${st.size} B > ${max} B). Raise PLAYCRAFT_IMAGE_MAX_INPUT_BYTES if needed.`);
         process.exit(1);
     }
+    return resolved;
 }
 function ensureDir(filePath) {
-    mkdirSync(dirname(filePath), { recursive: true });
+    mkdirSync(dirname(resolveSandboxPath(filePath)), { recursive: true });
 }
 function writeOutput(path, buf) {
-    ensureDir(path);
-    writeFileSync(path, buf);
+    const resolved = resolveSandboxPath(path);
+    ensureDir(resolved);
+    writeFileSync(resolved, buf);
 }
 function sizeLabelBytes(byteLength) {
     const kb = byteLength / 1024;
@@ -55,12 +59,14 @@ function handleError(err) {
  * safeToFile 自动检测同路径场景：先写临时文件，成功后原子 rename 覆盖。
  */
 async function safeToFile(pipeline, outputPath, inputPath) {
-    ensureDir(outputPath);
-    if (inputPath && resolve(inputPath) === resolve(outputPath)) {
-        const tmpPath = outputPath + '.__tmp__';
+    const resolvedOutput = resolveSandboxPath(outputPath);
+    const resolvedInput = inputPath ? resolveSandboxPath(inputPath) : undefined;
+    ensureDir(resolvedOutput);
+    if (resolvedInput && resolve(resolvedInput) === resolve(resolvedOutput)) {
+        const tmpPath = resolvedOutput + '.__tmp__';
         try {
             await pipeline.toFile(tmpPath);
-            renameSync(tmpPath, outputPath);
+            renameSync(tmpPath, resolvedOutput);
         }
         catch (e) {
             try {
@@ -74,7 +80,7 @@ async function safeToFile(pipeline, outputPath, inputPath) {
         }
     }
     else {
-        await pipeline.toFile(outputPath);
+        await pipeline.toFile(resolvedOutput);
     }
 }
 /**
@@ -94,12 +100,13 @@ function globPattern(pattern) {
  * pattern 只做文件名匹配（如 "*.png"，不支持子目录 **）。
  */
 function collectFromDir(dir, pattern = '*.png', sort = 'name') {
-    if (!existsSync(dir))
+    const resolvedDir = resolveSandboxPath(dir);
+    if (!existsSync(resolvedDir))
         return [];
     const reg = globPattern(pattern);
-    const files = readdirSync(dir)
-        .filter((f) => reg.test(f) && statSync(join(dir, f)).isFile())
-        .map((f) => join(dir, f));
+    const files = readdirSync(resolvedDir)
+        .filter((f) => reg.test(f) && statSync(join(resolvedDir, f)).isFile())
+        .map((f) => join(resolvedDir, f));
     if (sort === 'name') {
         files.sort((a, b) => basename(a).localeCompare(basename(b), undefined, { numeric: true, sensitivity: 'base' }));
     }
@@ -116,14 +123,15 @@ function expandInputPaths(raw) {
     const parts = raw.split(',').map((p) => p.trim()).filter(Boolean);
     const result = [];
     for (const part of parts) {
-        if (part.includes('*') || part.includes('?')) {
-            const dir = dirname(part);
-            const pat = basename(part);
+        const resolvedPart = resolveSandboxPath(part);
+        if (resolvedPart.includes('*') || resolvedPart.includes('?')) {
+            const dir = dirname(resolvedPart);
+            const pat = basename(resolvedPart);
             const matched = collectFromDir(dir === '.' ? process.cwd() : dir, pat, 'name');
             result.push(...matched);
         }
         else {
-            result.push(part);
+            result.push(resolvedPart);
         }
     }
     return result;
@@ -639,6 +647,8 @@ const VFX_PRESETS = [
  * 在 batch 管线中执行单个步骤（复用 sharp 逻辑，无需启动子进程）。
  */
 async function runBatchStep(cmd, args, inputPath, outputPath) {
+    inputPath = resolveSandboxPath(inputPath);
+    outputPath = resolveSandboxPath(outputPath);
     const getArg = (flag) => {
         const idx = args.indexOf(flag);
         return idx !== -1 ? args[idx + 1] : undefined;
@@ -767,7 +777,7 @@ export function registerImageCommands(program) {
         .option('--json', '以 JSON 格式输出（默认人类可读格式）')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const meta = await sharp(opts.input).metadata();
             const fileStat = statSync(opts.input);
             const channels = meta.channels ?? 0;
@@ -807,7 +817,7 @@ export function registerImageCommands(program) {
         .option('--fit <mode>', 'contain|cover|fill|inside|outside', 'cover')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const meta = await sharp(opts.input).metadata();
             const w = meta.width ?? 64;
             const h = meta.height ?? 64;
@@ -827,7 +837,7 @@ export function registerImageCommands(program) {
             }
             const fit = parseResizeFitOption(opts.fit);
             await safeToFile(sharp(opts.input).resize(targetW, targetH, { fit }), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Resized ${w}x${h} → ${targetW ?? '?'}x${targetH ?? '?'} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -845,9 +855,9 @@ export function registerImageCommands(program) {
         .requiredOption('--height <n>', '裁剪高度（像素）', cliParseInt)
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).extract({ left: opts.x, top: opts.y, width: opts.width, height: opts.height }), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Cropped to ${opts.width}x${opts.height} at (${opts.x},${opts.y}) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -863,9 +873,9 @@ export function registerImageCommands(program) {
         .option('--background <color>', '旋转后露出的背景色（CSS hex，如 #000000）', '#00000000')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).rotate(opts.angle, { background: opts.background }), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Rotated ${opts.angle}° — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -880,7 +890,7 @@ export function registerImageCommands(program) {
         .option('--direction <dir>', 'horizontal（左右）或 vertical（上下）', 'horizontal')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             let pipeline = sharp(opts.input);
             if (opts.direction === 'horizontal') {
                 pipeline = pipeline.flop();
@@ -893,7 +903,7 @@ export function registerImageCommands(program) {
                 process.exit(1);
             }
             await safeToFile(pipeline, opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Flipped ${opts.direction} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -913,13 +923,13 @@ export function registerImageCommands(program) {
         .option('--background <color>', '背景色（CSS hex）', '#00000000')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const pad = opts.all !== undefined
                 ? { top: opts.all, bottom: opts.all, left: opts.all, right: opts.all }
                 : { top: opts.top, bottom: opts.bottom, left: opts.left, right: opts.right };
             await safeToFile(sharp(opts.input).extend({ ...pad, background: opts.background }), opts.output, opts.input);
-            const meta = await sharp(opts.output).metadata();
-            const outSz = statSync(opts.output).size;
+            const meta = await sharp(resolveSandboxPath(opts.output)).metadata();
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Padded to ${meta.width}x${meta.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -936,7 +946,7 @@ export function registerImageCommands(program) {
         .option('--lossless', '无损压缩（webp/avif 有效）')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const origSize = statSync(opts.input).size;
             const fmt = (opts.format ?? opts.output.split('.').pop() ?? 'png').toLowerCase();
             let pipeline = sharp(opts.input);
@@ -957,7 +967,7 @@ export function registerImageCommands(program) {
                     break;
             }
             await safeToFile(pipeline, opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             const ratio = origSize > 0 ? ((1 - outSz / origSize) * 100).toFixed(1) : '0.0';
             console.log(`Converted to ${fmt} — ${opts.output} (${sizeLabelBytes(outSz)}, ${ratio}% reduction)`);
         }
@@ -972,9 +982,9 @@ export function registerImageCommands(program) {
         .requiredOption('--output <path>', '输出图片路径')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).grayscale(), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Grayscale — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -989,9 +999,9 @@ export function registerImageCommands(program) {
         .option('--sigma <n>', '模糊强度（0.3–1000，越大越模糊）', parseFloat, 3)
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).blur(opts.sigma), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Blurred (sigma=${opts.sigma}) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1006,9 +1016,9 @@ export function registerImageCommands(program) {
         .requiredOption('--color <hex>', '叠加颜色（CSS hex，如 #ff0000）')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).tint(opts.color), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Tinted with ${opts.color} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1023,11 +1033,11 @@ export function registerImageCommands(program) {
         .option('--threshold <n>', '颜色容差（0-255，默认 10）', cliParseInt, 10)
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const before = await sharp(opts.input).metadata();
             await safeToFile(sharp(opts.input).trim({ threshold: opts.threshold }), opts.output, opts.input);
-            const after = await sharp(opts.output).metadata();
-            const outSz = statSync(opts.output).size;
+            const after = await sharp(resolveSandboxPath(opts.output)).metadata();
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Trimmed ${before.width}x${before.height} → ${after.width}x${after.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1042,9 +1052,9 @@ export function registerImageCommands(program) {
         .option('--no-alpha', '不反转透明通道')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             await safeToFile(sharp(opts.input).negate({ alpha: opts.alpha !== false }), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Negated — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1062,8 +1072,8 @@ export function registerImageCommands(program) {
         .option('--gravity <g>', '对齐方向（center|north|south|east|west...，--x/--y 优先）', 'center')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.base, 'base');
-            assertInputWithinLimit(opts.overlay, 'overlay');
+            opts.base = assertInputWithinLimit(opts.base, 'base');
+            opts.overlay = assertInputWithinLimit(opts.overlay, 'overlay');
             const overlayOpts = { input: opts.overlay };
             if (opts.x !== undefined && opts.y !== undefined) {
                 overlayOpts.left = opts.x;
@@ -1073,8 +1083,8 @@ export function registerImageCommands(program) {
                 overlayOpts.gravity = opts.gravity;
             }
             await safeToFile(sharp(opts.base).composite([overlayOpts]), opts.output, opts.base);
-            const meta = await sharp(opts.output).metadata();
-            const outSz = statSync(opts.output).size;
+            const meta = await sharp(resolveSandboxPath(opts.output)).metadata();
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Composited — ${meta.width}x${meta.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1089,14 +1099,14 @@ export function registerImageCommands(program) {
         .option('--pixel-size <n>', '像素块大小（默认 8）', cliParseInt, 8)
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const meta = await sharp(opts.input).metadata();
             const w = meta.width ?? 64;
             const h = meta.height ?? 64;
             const smallW = Math.max(1, Math.floor(w / opts.pixelSize));
             const smallH = Math.max(1, Math.floor(h / opts.pixelSize));
             await safeToFile(sharp(opts.input).resize(smallW, smallH, { kernel: 'nearest' }).resize(w, h, { kernel: 'nearest' }), opts.output, opts.input);
-            const outSz = statSync(opts.output).size;
+            const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Pixelated (block=${opts.pixelSize}px) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
         catch (e) {
@@ -1118,7 +1128,7 @@ export function registerImageCommands(program) {
         .option('--padding <n>', '帧间距（像素，默认 0）', cliParseInt, 0)
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             let analysis;
             if (opts.autoDetect) {
                 const imageBase64 = readFileSync(opts.input).toString('base64');
@@ -1185,7 +1195,7 @@ export function registerImageCommands(program) {
         try {
             let paths;
             if (opts.inputDir) {
-                paths = collectFromDir(opts.inputDir, opts.glob ?? '*.png', opts.sort ?? 'name');
+                paths = collectFromDir(resolveSandboxPath(opts.inputDir), opts.glob ?? '*.png', opts.sort ?? 'name');
             }
             else if (opts.inputs) {
                 paths = expandInputPaths(opts.inputs);
@@ -1199,7 +1209,7 @@ export function registerImageCommands(program) {
                 process.exit(1);
             }
             for (let i = 0; i < paths.length; i++) {
-                assertInputWithinLimit(paths[i], `inputs[${i}]`);
+                paths[i] = assertInputWithinLimit(paths[i], `inputs[${i}]`);
             }
             const firstMeta = await sharp(paths[0]).metadata();
             const cellW = opts.cellWidth ?? firstMeta.width ?? 64;
@@ -1290,7 +1300,7 @@ export function registerImageCommands(program) {
                 const globPatterns = (opts.glob ?? '*.png,*.jpg,*.jpeg,*.webp').split(',').map((p) => p.trim());
                 const allFiles = [];
                 for (const pat of globPatterns) {
-                    const matched = collectFromDir(opts.inputDir, pat, 'name');
+                    const matched = collectFromDir(resolveSandboxPath(opts.inputDir), pat, 'name');
                     allFiles.push(...matched);
                 }
                 inputs = [...new Set(allFiles)];
@@ -1350,13 +1360,13 @@ export function registerImageCommands(program) {
                 console.error('Error: --steps is empty or invalid');
                 process.exit(1);
             }
-            mkdirSync(opts.outputDir, { recursive: true });
+            mkdirSync(resolveSandboxPath(opts.outputDir), { recursive: true });
             let done = 0, skipped = 0, failed = 0;
             const total = inputs.length;
             const concurrency = Math.max(1, opts.parallel);
             const processOne = async (inputPath) => {
                 const outName = basename(inputPath).replace(/\.[^.]+$/, '.png');
-                const outPath = join(opts.outputDir, outName);
+                const outPath = join(resolveSandboxPath(opts.outputDir), outName);
                 if (opts.skipExisting && existsSync(outPath)) {
                     skipped++;
                     process.stdout.write(`\r[${done + skipped + failed}/${total}] skipping ${outName} (exists)`);
@@ -1449,7 +1459,7 @@ export function registerImageCommands(program) {
         .option('--dry-run', '只打印将执行的操作，不实际处理')
         .action(async (opts) => {
         try {
-            const configRaw = readFileSync(opts.config, 'utf-8');
+            const configRaw = readFileSync(resolveSandboxPath(opts.config), 'utf-8');
             const ext = extname(opts.config).toLowerCase();
             let config;
             if (ext === '.json') {
@@ -1617,7 +1627,7 @@ export function registerImageCommands(program) {
         .option('--no-refine', '[ai] 跳过 alpha 后处理（保留模型原始软边）')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const method = opts.method ?? 'floodfill';
             if (method === 'floodfill') {
                 const t0 = Date.now();
@@ -1689,7 +1699,7 @@ export function registerImageCommands(program) {
                 console.error('Error: --input and --output are required');
                 process.exit(1);
             }
-            if (!existsSync(opts.input)) {
+            if (!existsSync(resolveSandboxPath(opts.input))) {
                 console.error(`Error: input file not found: ${opts.input}`);
                 process.exit(1);
             }
@@ -1706,11 +1716,11 @@ export function registerImageCommands(program) {
                     console.error('Error: --preset flip requires --back <backside-image>');
                     process.exit(1);
                 }
-                if (!existsSync(opts.back)) {
+                if (!existsSync(resolveSandboxPath(opts.back))) {
                     console.error(`Error: back image not found: ${opts.back}`);
                     process.exit(1);
                 }
-                await buildFlipSpriteSheet(opts.input, opts.back, frames, columns, opts.output);
+                await buildFlipSpriteSheet(resolveSandboxPath(opts.input), resolveSandboxPath(opts.back), frames, columns, resolveSandboxPath(opts.output));
             }
             else {
                 const preset = opts.preset;
@@ -1718,10 +1728,10 @@ export function registerImageCommands(program) {
                     console.error(`Error: unknown preset '${preset}'. Available: ${Object.keys(ANIMATE_PRESETS).join(', ')}, flip`);
                     process.exit(1);
                 }
-                await buildAnimationSpriteSheet(opts.input, preset, frames, columns, opts.output);
+                await buildAnimationSpriteSheet(resolveSandboxPath(opts.input), preset, frames, columns, resolveSandboxPath(opts.output));
             }
             const elapsed = ((Date.now() - t0) / 1000).toFixed(2);
-            const outBuf = readFileSync(opts.output);
+            const outBuf = readFileSync(resolveSandboxPath(opts.output));
             const meta = await sharp(opts.input).metadata();
             console.log(`Animation generated: ${opts.output} (${sizeLabel(outBuf)}, ${elapsed}s)`);
             console.log(`  Preset: ${opts.back ? 'flip' : opts.preset} | Frames: ${frames} | Layout: ${columns}×${Math.ceil(frames / columns)} | Frame size: ${meta.width}×${meta.height}`);
@@ -1775,12 +1785,12 @@ export function registerImageCommands(program) {
                 process.exit(1);
             }
             const scale = parseFloat(opts.scale);
-            const outDir = dirname(resolve(opts.output));
+            const outDir = dirname(resolve(resolveSandboxPath(opts.output)));
             if (!existsSync(outDir))
                 mkdirSync(outDir, { recursive: true });
             if (!opts.tint && scale === 1.0) {
-                copyFileSync(srcPath, opts.output);
-                const sz = sizeLabel(readFileSync(opts.output));
+                copyFileSync(srcPath, resolveSandboxPath(opts.output));
+                const sz = sizeLabel(readFileSync(resolveSandboxPath(opts.output)));
                 console.log(`VFX copied: ${opts.output} (${sz})`);
                 console.log(`  ${preset.frames} frames, ${preset.columns} cols — ${preset.description}`);
                 return;
@@ -1832,7 +1842,7 @@ export function registerImageCommands(program) {
             const style = opts.style;
             const buf = await generateTileBack(W, H, bg, border, style);
             ensureDir(opts.output);
-            writeFileSync(opts.output, buf);
+            writeFileSync(resolveSandboxPath(opts.output), buf);
             console.log(`Tile back generated: ${opts.output} (${sizeLabel(buf)}, ${W}×${H}, style: ${style})`);
         }
         catch (e) {
@@ -1873,8 +1883,8 @@ export function registerImageCommands(program) {
                 console.log(`Using image URL: ${input}`);
             }
             else {
-                assertInputWithinLimit(input);
-                payload.imageBase64 = readFileSync(input).toString('base64');
+                const resolvedDecomposeInput = assertInputWithinLimit(input);
+                payload.imageBase64 = readFileSync(resolvedDecomposeInput).toString('base64');
                 console.log(`Uploading local image: ${input}`);
             }
             console.log(`Decomposing into ${payload.numLayers} layer(s) via 302 Qwen-Image-Layered (may take 1–2 min)…`);
@@ -1938,7 +1948,7 @@ export function registerImageCommands(program) {
         .option('--output-dir <dir>', '输出目录（默认 ./segment-output）', './segment-output')
         .action(async (opts) => {
         try {
-            assertInputWithinLimit(opts.input);
+            opts.input = assertInputWithinLimit(opts.input);
             const imageBase64 = readFileSync(opts.input).toString('base64');
             // 构造 prompts 列表
             let prompts;

package/dist/commands/levels.js

@@ -0,0 +1,29 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+const cliRoot = dirname(fileURLToPath(import.meta.url));
+async function loadValidator() {
+    const scriptPath = join(cliRoot, '../../project-template/skills/_shared/scripts/validate-level-sketch.mjs');
+    return import(pathToFileURL(scriptPath).href);
+}
+export function registerLevelsCommands(program) {
+    const levels = program.command('levels').description('Level sketch validation (executable design)');
+    levels
+        .command('validate')
+        .description('Validate docs/level-sketch.json — solvability + puzzle identity metrics')
+        .option('--sketch <path>', 'Path to level sketch JSON', 'docs/level-sketch.json')
+        .option('--json', 'Output JSON')
+        .action(async (opts) => {
+        const { validateLevelSketch } = await loadValidator();
+        const result = validateLevelSketch(process.cwd(), opts.sketch);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else if (result.ok) {
+            process.stdout.write(`[levels validate] OK — paths=${result.metrics.pathCount} openingRemovable=${result.metrics.openingRemovableCount}\n`);
+        }
+        else {
+            process.stderr.write(`[levels validate] FAIL\n  - ${result.problems.join('\n  - ')}\n`);
+        }
+        process.exit(result.ok ? 0 : 2);
+    });
+}

package/dist/commands/patterns.js

@@ -0,0 +1,75 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandIntentTags } from './skills.js';
+function loadCatalog() {
+    const cliRoot = dirname(fileURLToPath(import.meta.url));
+    const catalogPath = join(cliRoot, '../../project-template/fusion-patterns/catalog.json');
+    if (!existsSync(catalogPath)) {
+        throw new Error(`fusion pattern catalog not found: ${catalogPath}`);
+    }
+    return JSON.parse(readFileSync(catalogPath, 'utf8'));
+}
+function scorePattern(pattern, intentTags) {
+    const expanded = expandIntentTags(intentTags);
+    let score = 0;
+    for (const tag of expanded) {
+        if (pattern.intentTags.some((t) => t.toLowerCase() === tag.toLowerCase()))
+            score += 3;
+        if (pattern.title.toLowerCase().includes(tag.toLowerCase()))
+            score += 1;
+        if (pattern.mechanics.toLowerCase().includes(tag.toLowerCase()))
+            score += 1;
+    }
+    const blob = intentTags.join(' ').toLowerCase();
+    if (pattern.intentTags.some((t) => blob.includes(t.toLowerCase())))
+        score += 2;
+    return score;
+}
+export function matchFusionPatterns(intent, limit = 3) {
+    const intentTags = intent
+        .split(/[,\s]+/)
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const catalog = loadCatalog();
+    return catalog.patterns
+        .map((p) => ({ pattern: p, score: scorePattern(p, intentTags) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(({ pattern }) => pattern);
+}
+export function registerPatternsCommands(program) {
+    const patterns = program.command('patterns').description('Fusion pattern library (local RAG before web research)');
+    patterns
+        .command('match')
+        .description('Match fusion pattern cards from local catalog')
+        .requiredOption('--intent <text>', 'User intent keywords')
+        .option('--json', 'Output JSON')
+        .option('--limit <n>', 'Max patterns', '3')
+        .action((opts) => {
+        const items = matchFusionPatterns(opts.intent, parseInt(opts.limit, 10) || 3);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({ intent: opts.intent, items }, null, 2)}\n`);
+            return;
+        }
+        if (items.length === 0) {
+            console.log('No fusion patterns matched — fallback to playcraft tools research --focus gameplay');
+            return;
+        }
+        console.log(`\nFusion patterns (${items.length}):\n`);
+        for (const p of items) {
+            console.log(`  [${p.id}] ${p.title}`);
+            console.log(`    skill: ${p.skillRef}`);
+            console.log(`    fantasy: ${p.playerFantasy}`);
+            console.log(`    decision: ${p.decisionMoment}`);
+            if (p.recommendedProfile)
+                console.log(`    profile: ${p.recommendedProfile}`);
+            if (p.depthHint)
+                console.log(`    depthHint: ${p.depthHint}`);
+            if (p.antiPatternRef)
+                console.log(`    avoid: ${p.antiPatternRef}`);
+            console.log();
+        }
+    });
+}

package/dist/commands/remix.js

@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs';
 import { PlayCraftApiError, PlayCraftHttpClient, isPlayCraftApiError } from '../utils/playcraft-http-client.js';
 import { IMAGE_OPTION_HELP, buildReferenceImagesPrompt, readImageAttachments, uploadImageAttachments, } from '../utils/remix-image-attachments.js';
 import { initTemplateCommand } from '../remix/init-template.js';
+import { remixClone, gitCredentialCommand, isRemoteCloneSource } from '../remix/clone.js';
 // Register autocomplete prompt
 inquirer.registerPrompt('autocomplete', autocomplete);
 const JSON_OUTPUT_HELP = '输出一条 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果';
@@ -1266,4 +1267,50 @@ export function registerRemixCommands(program) {
         .option('--token <token>', PAT_HELP)
         .option('--json', JSON_OUTPUT_HELP)
         .action((opts) => remixRun({ ...opts, images: opts.image, timeout: Math.max(1, Number(opts.timeout) || 1800) }));
+    remix.command('clone')
+        .description('经 PlayCraft Git 代理克隆 Remix 源码到本地（支持粘贴详情页 / Editor / 工蜂 URL）')
+        .argument('[source]', 'Remix 详情页、Editor 地址，或工蜂/Git 分支页 URL')
+        .argument('[dir]', '本地目标目录（默认 <projectId>-<branch>）')
+        .option('--project-id <id>', '项目 ID（未传 URL 时必填）')
+        .option('--branch <name>', 'Remix 分支名（未传 URL 或工蜂地址无 /tree 时必填）')
+        .option('--install', 'clone 后执行 npm install')
+        .option('--dev', 'install 后执行 npm run dev')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action(async (sourceArg, dirArg, opts) => {
+        try {
+            let source = sourceArg ? String(sourceArg) : undefined;
+            let dir = dirArg ? String(dirArg) : undefined;
+            // `clone ./outdir --project-id … --branch …` → first arg is dir
+            if (source && !isRemoteCloneSource(source)) {
+                dir = source;
+                source = undefined;
+            }
+            await remixClone({
+                source,
+                dir,
+                projectId: opts.projectId ? String(opts.projectId) : undefined,
+                branch: opts.branch ? String(opts.branch) : undefined,
+                install: Boolean(opts.install || opts.dev),
+                dev: Boolean(opts.dev),
+                url: opts.url,
+                token: opts.token,
+                json: Boolean(opts.json),
+            });
+        }
+        catch (error) {
+            handleCommandError('remix.clone', opts, undefined, error);
+        }
+    });
+}
+/** Register `playcraft git-credential` for local git pull/push after remix clone. */
+export function registerGitCredentialCommand(program) {
+    program
+        .command('git-credential')
+        .description('Git credential helper：从登录配置提供 PlayCraft PAT')
+        .argument('[action]', 'get | store | erase', 'get')
+        .action((action) => {
+        gitCredentialCommand(action);
+    });
 }