@playcraft/cli 0.1.63 → 0.1.65

package/project-templates/threejs/.claude/skills/playcraft-build-optimizer/SKILL.md

@@ -30,11 +30,11 @@ triggers: 构建优化,build optimizer,压缩,compress,WebP,pngquant,文件大
 
 ```bash
 # 检查最终输出文件大小
-playcraft image info --input dist/index.html --json  # 不适用，用 shell
+playcraft image info --input dist/preview/index.html --json  # 不适用，用 shell
 
 # Shell 方法：检查文件大小（字节）
-du -sh dist/index.html
-ls -lh dist/index.html
+du -sh dist/preview/index.html
+ls -lh dist/preview/index.html
 
 # 计算：若当前原始资产总大小为 X MB
 # 预计最终 HTML 大小 ≈ X × 1.33（Base64 膨胀）
@@ -112,34 +112,31 @@ grep -r "\.play()" game/ --include="*.js" --include="*.ts"
 
 ## 2. playcraft build 优化参数
 
+- 产物固定为单文件 `dist/preview/index.html`，用于本地 review；在云工作区中它就是产物面板里的可玩预览。
+- 下列参数只影响这份本地预览。渠道包（Meta、Google、AppLovin 等）只能通过平台导出生成，导出不会读取本地 build 的参数，渠道体积以导出时的校验为准。
+
 ### 完整优化构建命令
 
 ```bash
-# 标准优化构建（Meta 平台）
+# 标准优化构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 85 \
   --convert-webp \
   --js-minify \
-  --css-minify \
-  --output dist/
+  --css-minify
 
 # 带 3D 模型压缩的构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 80 \
   --convert-webp \
   --compress-models \
   --model-compression draco \
-  --js-minify \
-  --output dist/
+  --js-minify
 
 # 分析体积占用（不构建，只分析）
-playcraft build . \
-  --platform facebook \
-  --analyze
+playcraft build . --analyze
 ```
 
 ### 图片优化参数
@@ -170,25 +167,6 @@ playcraft build . \
 | `--js-minify`  | 启用 JS 压缩（Terser + 混淆） |
 | `--css-minify` | 启用 CSS 压缩                 |
 
-### 多平台批量构建
-
-```bash
-# 同时构建多个平台版本
-playcraft build-all . \
-  --platforms facebook,google,applovin \
-  --compress-images \
-  --image-quality 85 \
-  --convert-webp \
-  --js-minify \
-  --output dist/
-
-# 或按平台组
-playcraft build-all . \
-  --group mainstream \   # 主流平台
-  --compress-images \
-  --convert-webp
-```
-
 ---
 
 ## 3. 正确的优化执行顺序
@@ -207,9 +185,11 @@ playcraft build-all . \
    ↓
 5. playcraft build --js-minify --css-minify — 代码压缩
    ↓
-6. 检查最终文件大小（必须 < 5 MB）
+6. 检查 dist/preview/index.html 大小（仅供参考，渠道体积以平台导出校验为准）
    ↓
 7. 合规验证清单（§1）
+   ↓
+8. 通过平台导出生成各渠道包
 ```
 
 **禁止行为**：
@@ -298,9 +278,9 @@ playcraft 3d optimize \
 
 ## 6. 常见审核被拒原因速查
 
-| 被拒原因          | 占比 | 检查方法                 | 修复方法                                                |
-| ----------------- | ---- | ------------------------ | ------------------------------------------------------- |
-| 文件大小超过 5 MB | 45%  | `ls -lh dist/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
-| 包含外部请求      | 30%  | `grep -r "https://"`     | Developer 将外部资源内嵌                                |
-| CTA 未实现        | 15%  | `grep "FbPlayableAd"`    | Developer 添加平台 CTA API                              |
-| 音频自动播放      | 10%  | `grep "autoplay"`        | Developer 改为用户交互触发                              |
+| 被拒原因          | 占比 | 检查方法                         | 修复方法                                                |
+| ----------------- | ---- | -------------------------------- | ------------------------------------------------------- |
+| 文件大小超过 5 MB | 45%  | `ls -lh dist/preview/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
+| 包含外部请求      | 30%  | `grep -r "https://"`             | Developer 将外部资源内嵌                                |
+| CTA 未实现        | 15%  | `grep "FbPlayableAd"`            | Developer 添加平台 CTA API                              |
+| 音频自动播放      | 10%  | `grep "autoplay"`                | Developer 改为用户交互触发                              |

package/dist/workspace-runtime/workspaces/delivery-build.js

@@ -1,440 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { constants } from 'node:fs';
-import { copyFile, cp, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, stat, symlink } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { basename, dirname, join, relative, sep } from 'node:path';
-import { createPlatformAdapter, getChannelRuleProfile, } from '@playcraft/build';
-import { DELIVERY_QUEUE_LIMIT, isWorkspaceArtifactOutputPath, } from '@playcraft/common/cloud-workspace/runtime';
-import { revisionScope, workspaceRoot } from './registry.js';
-import { excludeFromGit, ensureWorkspaceDependencies } from './dependencies.js';
-import { listWorkspaceBuildInputs } from './git.js';
-import { runDeveloperCommand } from './developer-command.js';
-import { openScratchToDevelopment } from './directory-access.js';
-import { ensureSharedDirectory } from './shared-write.js';
-import { driftScope, permissionDriftFromOutput, repairWorkspaceShares } from './workspace-shares.js';
-import { DeliveryStore } from './delivery-store.js';
-import { DeliveryValidationError, validateDeliveryArtifact } from './delivery.js';
-export const DELIVERY_BUILD_TIMEOUT_MS = 10 * 60_000;
-/** Staging under the workspace from earlier runtimes; kept out of Git so leftovers never commit. */
-const STAGING_DIRECTORY = '.playcraft-delivery';
-/** Never copied into the build copy: history, outputs and caches that the build neither reads nor owns. */
-const ISOLATE_SKIP = new Set(['.git', 'dist', '.turbo', STAGING_DIRECTORY]);
-export class DeliveryBuildError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-        this.name = 'DeliveryBuildError';
-    }
-}
-const queues = new WeakMap();
-const running = new WeakMap();
-export function trackDeliveryBuild(state, task) {
-    const tasks = running.get(state) ?? new Set();
-    running.set(state, tasks);
-    const tracked = task.finally(() => tasks.delete(tracked));
-    tasks.add(tracked);
-}
-export async function settleDeliveryBuilds(state) {
-    await Promise.all([...(running.get(state) ?? [])]);
-}
-const scopeKey = (workspaceId, directoryName) => `${workspaceId}\0${directoryName}`;
-function buildQueues(state) {
-    const known = queues.get(state) ?? new Map();
-    queues.set(state, known);
-    return known;
-}
-function queuedRecord(input, createdAt, queuePosition) {
-    return {
-        buildId: input.buildId,
-        workspaceId: input.workspaceId,
-        directoryName: input.directoryName,
-        channel: input.payload.channel,
-        format: input.payload.format,
-        status: 'queued',
-        ...(input.actor ? { actor: input.actor } : {}),
-        queuePosition,
-        createdAt,
-    };
-}
-async function refreshQueuedRecords(state, key) {
-    const queue = buildQueues(state).get(key);
-    if (!queue)
-        return;
-    const waiting = queue.queue.filter(item => !item.started && !item.canceled);
-    const workspaceId = waiting[0]?.input.workspaceId ?? queue.active?.pending.input.workspaceId;
-    if (!workspaceId)
-        return;
-    const store = new DeliveryStore(state.config.stateDir, workspaceId);
-    await Promise.all(waiting.map((item, index) => {
-        if (item.started || item.canceled)
-            return Promise.resolve();
-        return store.write(queuedRecord(item.input, item.createdAt, index + 1)).catch(() => undefined);
-    }));
-}
-function pump(state, key, queue) {
-    if (queue.active)
-        return;
-    const next = queue.queue.shift();
-    if (!next)
-        return;
-    next.started = true;
-    queue.active = { buildId: next.input.buildId, pending: next };
-    void executeBuild(state, next.input, next.controller)
-        .then(outcome => next.resolve(outcome), error => next.reject(error))
-        .finally(() => {
-        queue.active = undefined;
-        pump(state, key, queue);
-        void refreshQueuedRecords(state, key);
-    });
-}
-export function runDeliveryBuild(state, input) {
-    if (input.directoryName === 'root')
-        return Promise.reject(new DeliveryBuildError('invalid_workspace_directory'));
-    const key = scopeKey(input.workspaceId, input.directoryName);
-    const scopes = buildQueues(state);
-    const queue = scopes.get(key) ?? { queue: [] };
-    if ((queue.active ? 1 : 0) + queue.queue.length >= DELIVERY_QUEUE_LIMIT) {
-        return Promise.reject(new DeliveryBuildError('delivery_queue_full'));
-    }
-    let resolve;
-    let reject;
-    const promise = new Promise((resolvePromise, rejectPromise) => {
-        resolve = resolvePromise;
-        reject = rejectPromise;
-    });
-    const pending = {
-        input,
-        controller: new AbortController(),
-        promise,
-        resolve,
-        reject,
-        createdAt: new Date().toISOString(),
-        canceled: false,
-        started: false,
-    };
-    queue.queue.push(pending);
-    scopes.set(key, queue);
-    pump(state, key, queue);
-    void refreshQueuedRecords(state, key);
-    return promise;
-}
-export async function cancelDeliveryBuild(state, workspaceId, directoryName, buildId) {
-    const key = scopeKey(workspaceId, directoryName);
-    const queue = buildQueues(state).get(key);
-    if (!queue)
-        return false;
-    if (queue.active?.buildId === buildId) {
-        queue.active.pending.controller.abort();
-        return true;
-    }
-    const index = queue.queue.findIndex(item => item.input.buildId === buildId);
-    if (index < 0)
-        return false;
-    const [pending] = queue.queue.splice(index, 1);
-    if (!pending)
-        return false;
-    pending.canceled = true;
-    const record = {
-        ...queuedRecord(pending.input, pending.createdAt, 0),
-        status: 'canceled',
-        finishedAt: new Date().toISOString(),
-        error: 'delivery_canceled',
-    };
-    await new DeliveryStore(state.config.stateDir, workspaceId).write(record).catch(() => undefined);
-    pending.resolve({ record });
-    void refreshQueuedRecords(state, key);
-    return true;
-}
-export function activeDeliveryBuild(state, workspaceId, directoryName) {
-    return buildQueues(state).get(scopeKey(workspaceId, directoryName))?.active?.buildId;
-}
-function shellQuote(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function outputExtension(format) {
-    return format === 'zip' ? '.zip' : '.html';
-}
-async function listStagedFiles(staging, prefix = '') {
-    const entries = await readdir(join(staging, prefix), { withFileTypes: true });
-    const files = [];
-    for (const entry of entries) {
-        if (entry.isSymbolicLink() || entry.name.startsWith('.'))
-            continue;
-        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
-            files.push(...await listStagedFiles(staging, relative));
-            if (files.length > 512)
-                throw new DeliveryBuildError('delivery_output_missing');
-        }
-        else if (entry.isFile()) {
-            files.push(relative);
-        }
-    }
-    return files;
-}
-function choosePrimary(files, format) {
-    const extension = outputExtension(format);
-    const candidates = files.filter(file => file.toLowerCase().endsWith(extension));
-    if (!candidates.length)
-        throw new DeliveryBuildError('delivery_output_missing');
-    const preferred = format === 'zip' ? 'playable.zip' : 'index.html';
-    return candidates.find(file => basename(file).toLowerCase() === preferred) ?? candidates[0];
-}
-/**
- * Copies a single artifact, or the whole staging tree for fragment/mixed channels. Each file is
- * staged next to its final name and renamed, so a partially written package never appears in dist.
- */
-async function copyToDist(root, staging, channel, format) {
-    const files = await listStagedFiles(staging);
-    const primary = choosePrimary(files, format);
-    const mode = getChannelRuleProfile(channel).deliveryMode;
-    const selected = files.length > 1 && (mode === 'fragment-assets' || mode === 'mixed') ? files : [primary];
-    const paths = [];
-    let sizeBytes = 0;
-    for (const file of selected) {
-        const relative = `dist/delivery/${channel}/${file}`;
-        if (!isWorkspaceArtifactOutputPath(relative))
-            throw new DeliveryBuildError('delivery_output_missing');
-        const target = join(root, relative);
-        const directory = dirname(target);
-        await ensureSharedDirectory(root, directory);
-        const temporary = join(directory, `.${basename(file)}.${randomUUID()}.tmp`);
-        try {
-            await copyFile(join(staging, file), temporary);
-            await rename(temporary, target);
-        }
-        catch {
-            await rm(temporary, { force: true }).catch(() => undefined);
-            throw new DeliveryBuildError('delivery_copy_failed');
-        }
-        sizeBytes += (await stat(target)).size;
-        paths.push(relative);
-    }
-    return { primary: `dist/delivery/${channel}/${primary}`, paths, sizeBytes };
-}
-/** Copy-on-write clone where the filesystem supports it (APFS, btrfs, XFS); a plain copy elsewhere. */
-const CLONE = constants.COPYFILE_FICLONE;
-const COPY_CONCURRENCY = 16;
-function skipped(path) {
-    const parts = path.split(/[\\/]/);
-    return ISOLATE_SKIP.has(parts[0]) || parts.includes('node_modules');
-}
-async function copyInput(root, destination, path) {
-    const source = join(root, path);
-    const target = join(destination, path);
-    let entry;
-    try {
-        entry = await lstat(source);
-    }
-    catch (error) {
-        // A tracked file deleted in the work tree is not a build input.
-        if (error.code === 'ENOENT')
-            return;
-        throw error;
-    }
-    await mkdir(dirname(target), { recursive: true });
-    if (entry.isSymbolicLink())
-        await symlink(await readlink(source), target);
-    else if (entry.isDirectory())
-        await cp(source, target, { recursive: true, verbatimSymlinks: true, mode: CLONE });
-    else
-        await copyFile(source, target, CLONE);
-}
-/**
- * Copies the workspace into `destination` for one build, like the platform export runner, with the
- * top-level `node_modules` linked (the build only reads it). Builders rewrite project files in place
- * (`builds.config.js` and its `.bak`, `package.json` scripts, migrated imports), so the build must
- * never run in the workspace itself, where autosave would commit those rewrites.
- *
- * Only the files Git would carry are copied: tracked ones and untracked ones `.gitignore` keeps, so
- * caches, logs and local outputs stay behind. Without a repository the whole tree is copied.
- */
-export async function isolateWorkspaceForBuild(root, destination) {
-    // The build runs as the development identity and writes its scratch folder inside this copy.
-    await ensureSharedDirectory(root, destination);
-    const modules = join(root, 'node_modules');
-    const modulesEntry = await lstat(modules).catch(() => undefined);
-    if (modulesEntry?.isDirectory() || modulesEntry?.isSymbolicLink()) {
-        await symlink(modulesEntry.isSymbolicLink() ? await readlink(modules) : modules, join(destination, 'node_modules'), 'dir');
-    }
-    const inputs = await listWorkspaceBuildInputs(root).catch(() => undefined);
-    const paths = inputs
-        ?? (await readdir(root)).filter((name) => name !== 'node_modules');
-    const queue = paths.filter((path) => !skipped(path));
-    const workers = Array.from({ length: Math.min(COPY_CONCURRENCY, queue.length) }, async () => {
-        for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
-            if (inputs)
-                await copyInput(root, destination, path);
-            else {
-                await cp(join(root, path), join(destination, path), {
-                    recursive: true,
-                    verbatimSymlinks: true,
-                    mode: CLONE,
-                    // Nested dependency folders stay out as well; the build resolves through the linked root.
-                    filter: (source) => !relative(join(root, path), source).split(sep).includes('node_modules'),
-                });
-            }
-        }
-    });
-    await Promise.all(workers);
-}
-/**
- * Runs one channel build in a disposable copy of the workspace. The build writes into a disposable
- * output directory; only the final artifact is copied into dist so the builder's `--clean` can never
- * erase another delivery.
- */
-async function executeBuild(state, input, controller) {
-    if (input.directoryName === 'root')
-        throw new DeliveryBuildError('invalid_workspace_directory');
-    const root = await workspaceRoot(state, input.workspaceId, input.directoryName);
-    const store = new DeliveryStore(state.config.stateDir, input.workspaceId);
-    const startedAt = new Date().toISOString();
-    const base = {
-        buildId: input.buildId,
-        workspaceId: input.workspaceId,
-        directoryName: input.directoryName,
-        channel: input.payload.channel,
-        format: input.payload.format,
-        status: 'running',
-        ...(input.actor ? { actor: input.actor } : {}),
-        createdAt: startedAt,
-        startedAt,
-    };
-    await store.write(base);
-    let scratch;
-    let staging = '';
-    let status = 'running';
-    let error;
-    let validationError;
-    let outputPath;
-    let outputPaths;
-    let sizeBytes;
-    let sizeLimitBytes;
-    let report;
-    let logChain = Promise.resolve();
-    let record;
-    try {
-        scratch = await mkdtemp(join(tmpdir(), 'playcraft-delivery-'));
-        // The build runs as the development identity while this scratch tree belongs to the controller.
-        await openScratchToDevelopment(scratch, (await lstat(root)).gid);
-        staging = join(scratch, 'output');
-        const project = join(scratch, 'project');
-        await ensureSharedDirectory(root, staging);
-        await excludeFromGit(root, `/${STAGING_DIRECTORY}/`);
-        await excludeFromGit(root, '/dist/');
-        const dependencies = await ensureWorkspaceDependencies(state, revisionScope(state, input.workspaceId, input.directoryName) ?? input.workspaceId, root);
-        if (!dependencies.ok) {
-            if (dependencies.logTail) {
-                await store.appendLog(input.buildId, `\n${dependencies.logTail}\n`);
-            }
-            throw new DeliveryBuildError('delivery_dependencies_failed');
-        }
-        try {
-            await isolateWorkspaceForBuild(root, project);
-        }
-        catch {
-            throw new DeliveryBuildError('delivery_isolation_failed');
-        }
-        const planned = process.env.PLAYCRAFT_DELIVERY_BUILD_COMMAND || 'playcraft build';
-        const command = `umask 002 && NO_COLOR=1 CI=1 ${planned} . --platform ${input.payload.channel} --format ${input.payload.format} --output ${shellQuote(staging)} --mode full`;
-        let outputTail = '';
-        const runBuild = () => runDeveloperCommand(state, {
-            processId: `delivery-${input.buildId}`,
-            cwd: project,
-            command,
-            timeoutMs: DELIVERY_BUILD_TIMEOUT_MS,
-            signal: controller.signal,
-            onOutput: (chunk) => {
-                const text = String(chunk);
-                if (!text)
-                    return;
-                outputTail = (outputTail + text).slice(-64 * 1024);
-                logChain = logChain.then(() => store.appendLog(input.buildId, text)).catch(() => undefined);
-            },
-        });
-        let outcome = await runBuild();
-        let permissionDrift = false;
-        if (outcome.code !== 0 && !outcome.canceled && !outcome.timedOut) {
-            // The build runs as the development identity; an entry only that identity owns repairs its
-            // own shared subtree, then the build is retried exactly once.
-            const drift = permissionDriftFromOutput(outputTail);
-            if (drift) {
-                permissionDrift = true;
-                await repairWorkspaceShares(state, root, await driftScope(root, drift.path)).catch(() => undefined);
-                outcome = await runBuild();
-                permissionDrift = outcome.code !== 0;
-            }
-        }
-        if (outcome.code === undefined) {
-            status = 'failed';
-            error = 'delivery_process_unknown';
-        }
-        else if (outcome.canceled) {
-            status = 'canceled';
-            error = 'delivery_canceled';
-        }
-        else if (outcome.timedOut) {
-            status = 'failed';
-            error = 'delivery_timeout';
-        }
-        else if (outcome.code !== 0) {
-            status = 'failed';
-            error = permissionDrift ? 'workspace_permission_drift' : 'delivery_build_failed';
-        }
-        else {
-            const output = await copyToDist(root, staging, input.payload.channel, input.payload.format);
-            outputPath = output.primary;
-            outputPaths = output.paths;
-            sizeBytes = output.sizeBytes;
-            sizeLimitBytes = createPlatformAdapter({
-                platform: input.payload.channel,
-                format: input.payload.format,
-            }).getSizeLimit();
-            try {
-                const result = await validateDeliveryArtifact(root, {
-                    channel: input.payload.channel,
-                    format: input.payload.format,
-                    path: outputPath,
-                });
-                report = result.report;
-                sizeLimitBytes = result.sizeLimitBytes;
-            }
-            catch (cause) {
-                validationError = cause instanceof DeliveryValidationError ? cause.code : 'delivery_report_unavailable';
-            }
-            status = 'succeeded';
-        }
-    }
-    catch (cause) {
-        status = 'failed';
-        error = cause instanceof DeliveryBuildError ? cause.code : 'delivery_build_failed';
-    }
-    finally {
-        // `rm` removes the node_modules link, never its target.
-        if (scratch)
-            await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
-        await logChain;
-        if (report) {
-            await store.writeReport(input.buildId, report).catch(() => {
-                validationError = validationError ?? 'delivery_report_unavailable';
-            });
-        }
-        const recordValue = {
-            ...base,
-            status,
-            finishedAt: new Date().toISOString(),
-            ...(outputPath ? { outputPath } : {}),
-            ...(outputPaths && outputPaths.length > 1 ? { outputPaths } : {}),
-            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
-            ...(sizeLimitBytes !== undefined ? { sizeLimitBytes } : {}),
-            ...(report ? { summary: report.summary, buildChain: report.buildChain } : {}),
-            ...(error ? { error } : {}),
-            ...(validationError ? { validationError } : {}),
-            logBytes: await store.logBytes(input.buildId),
-        };
-        record = recordValue;
-        await store.write(recordValue);
-    }
-    return { record, ...(report ? { report } : {}) };
-}