@playcraft/cli 0.1.34 → 0.1.36-beta1

package/dist/auth/messages.js

@@ -1,30 +0,0 @@
-const messages = {
-    en: {
-        activateOption: 'Explicitly activate the account using the current personal access token',
-        tokenOption: 'Personal access token for --activate (or use PLAYCRAFT_TOKEN)',
-        pending: 'Account activation is required. Run `playcraft login --activate` with the same token and target environment, then rerun your command.',
-        success: 'Account activated. Rerun your original command to continue.',
-        missingToken: 'No personal access token matches this target environment. Provide PLAYCRAFT_TOKEN or log in to this environment first.',
-        invalidToken: 'Account activation requires a personal access token. A sandbox token cannot activate an account.',
-        ambiguous: 'Activation credentials or target environments conflict. Specify --url, PLAYCRAFT_ENV when needed, and an explicit personal access token using --token or PLAYCRAFT_TOKEN.',
-        invalidTarget: 'Use a web service base address (http:// or https://) without credentials, a query, or a fragment.',
-        failed: 'Account activation failed. Check the target environment and token before trying again.',
-        unavailable: 'Account activation could not be confirmed. Check your account status before explicitly trying again.',
-    },
-    zh: {
-        activateOption: '明确使用当前个人访问令牌激活账号',
-        tokenOption: '用于 --activate 的个人访问令牌（也可使用 PLAYCRAFT_TOKEN）',
-        pending: '账号需要激活。请使用同一令牌和目标环境主动运行 `playcraft login --activate`，然后重新执行原命令。',
-        success: '账号已激活，请重新执行原命令继续。',
-        missingToken: '没有与目标环境匹配的个人访问令牌。请提供 PLAYCRAFT_TOKEN，或先登录此环境。',
-        invalidToken: '激活账号需要个人访问令牌，沙箱令牌不能用于激活账号。',
-        ambiguous: '激活凭据或目标环境存在冲突。请明确指定 --url、所需的 PLAYCRAFT_ENV，并通过 --token 或 PLAYCRAFT_TOKEN 提供个人访问令牌。',
-        invalidTarget: '激活目标必须是网页服务基址（http:// 或 https://），不能包含凭据、查询参数或片段。',
-        failed: '账号激活失败，请检查目标环境和令牌后再尝试。',
-        unavailable: '无法确认账号是否已激活。请先检查账号状态，再主动决定是否重试。',
-    },
-};
-export function accountActivationMessage(key) {
-    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
-    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
-}

package/dist/commands/platform-skills.generated.js

@@ -1,19 +0,0 @@
-// 此文件由 scripts/generate-platform-skills.mjs 生成，请勿手改。
-// 重新生成：pnpm --filter @playcraft/cli generate:platform-skills
-/** `@playcraft/skills/playcraft-skills/` 下的 Platform Skill 目录名。 */
-export const PLATFORM_SKILL_DIRS = [
-    'playcraft-3d-flip-sprite',
-    'playcraft-asset-management',
-    'playcraft-build',
-    'playcraft-code-editor',
-    'playcraft-create-remix',
-    'playcraft-deploy',
-    'playcraft-iteration-methodology',
-    'playcraft-platform-intro',
-    'playcraft-prefab',
-    'playcraft-project-management',
-    'playcraft-remix-workflow',
-    'playcraft-save',
-    'playcraft-template-upgrade-merge',
-    'sound-effects',
-];

package/dist/commands/playable.js

@@ -1,53 +0,0 @@
-import { recordPlayable } from '../recording/recorder.js';
-import { RecordingError, recordingMessage as t } from '../recording/messages.js';
-import { dirname, join } from 'node:path';
-import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
-export async function runPlayableRecord(options) {
-    const interrupted = new AbortController();
-    const deadline = new AbortController();
-    const onInterrupt = () => interrupted.abort(new DOMException('Interrupted', 'AbortError'));
-    process.once('SIGINT', onInterrupt);
-    let timer;
-    try {
-        const seconds = options.timeout === undefined ? 1200 : Number(options.timeout);
-        if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 1800)
-            throw new RecordingError('invalidArguments', 64);
-        timer = setTimeout(() => deadline.abort(new DOMException('Timed out', 'TimeoutError')), seconds * 1000);
-        const result = await recordPlayable(options, AbortSignal.any([interrupted.signal, deadline.signal]));
-        const metadata = result.envelope.result;
-        const output = result.envelope.artifacts;
-        if (result.envelope.ok && metadata && output?.candidate) {
-            const artifacts = [metadata.candidate, ...metadata.controls];
-            const paths = [output.candidate, ...(output.controls ?? [])];
-            for (let index = 0; index < artifacts.length; index++) {
-                const artifact = artifacts[index], path = paths[index];
-                if (!path)
-                    continue;
-                const thumbnail = artifact.screenshots?.[0]?.path;
-                await captureGeneratedArtifact(path, 'playable record', {
-                    width: artifact.video.source.width, height: artifact.video.source.height,
-                    duration: artifact.video.source.durationMs / 1000,
-                    ...(thumbnail ? { thumbnailPath: join(dirname(output.metadata), thumbnail) } : {}),
-                });
-            }
-        }
-        process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
-        process.exitCode = result.exitCode;
-    }
-    catch (error) {
-        const code = error instanceof RecordingError ? error.code : 'recordingFailed';
-        process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.video-cli.v1', command: 'playable record', state: 'failed', ok: false, error: { code, message: t(code) } })}\n`);
-        process.exitCode = error instanceof RecordingError ? error.exitCode : 4;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-        process.removeListener('SIGINT', onInterrupt);
-    }
-}
-export function registerPlayableCommands(program) {
-    program.command('playable').description(t('topic')).command('record').description(t('record'))
-        .option('--url <url>', t('url')).option('--scenario <file>', t('scenario')).option('--out <directory>', t('out'))
-        .option('--browser-path <path>', t('browser')).option('--timeout <seconds>', t('timeout'))
-        .action(runPlayableRecord);
-}

package/dist/commands/tools-batch.js

@@ -1,87 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { batchCreateSchema, batchPromptCreateSchema } from '@playcraft/common/cloud-workspace/runtime';
-import { AgentApiClient } from '../utils/agent-api-client.js';
-import { handleError } from './tools-utils.js';
-const messages = {
-    en: {
-        create: 'Create and automatically run independent Remix variants from one prompt',
-        input: 'Path to the batch draft JSON (JavaScript Object Notation, 数据交换格式) file',
-        status: 'Read a batch and its generation status',
-        id: 'Batch identifier',
-        created: 'Batch created',
-        prompt: 'The complete batch generation request', workspace: 'Source workspace identifier',
-        directory: 'Source engineering directory; defaults to basic', request: 'Stable batch creation identity for retries',
-        team: 'Team identifier for a standalone workspace', invalidMode: 'Provide either --prompt with --workspace-id or --input, exclusively.',
-        requestRequired: 'Prompt creation requires a stable --client-request-id; reuse it when retrying the same request.',
-        help: '\nUse --prompt with --workspace-id and a stable --client-request-id. The platform plans and generates independent Remix directories while preserving the source. An omitted count defaults to 3; maximum 10. --input also accepts existing structured drafts.\n',
-        confirmation: 'Generation is queued. Read the batch status to track its results.',
-        review: 'This existing draft requires baseline approval in the browser.',
-    },
-    zh: {
-        create: '用一个 prompt 创建并自动生成独立 Remix 变体',
-        input: '批次草案 JSON (JavaScript Object Notation, 数据交换格式) 文件路径',
-        status: '查询批次及生成状态',
-        id: '批次标识',
-        created: '批次已创建',
-        prompt: '完整的批量生成需求', workspace: '来源 workspace 标识',
-        directory: '来源工程目录，默认 basic', request: '用于重试的稳定批次创建标识',
-        team: '独立工作区所属团队标识', invalidMode: '请选择 --prompt 配合 --workspace-id，或 --input，两种方式不能同时使用。',
-        requestRequired: '使用 prompt 创建时必须提供稳定的 --client-request-id，重试同一请求时复用该标识。',
-        help: '\n使用 --prompt、--workspace-id 和稳定的 --client-request-id。平台自动规划，在副本中生成独立 Remix，保持来源不变。未指定数量默认 3 个，最多 10 个。--input 也兼容现有结构化草案。\n',
-        confirmation: '生成已排队，可查询批次状态追踪各项成果。',
-        review: '此历史草案需要在浏览器确认基准。',
-    },
-};
-const language = () => /^zh/i.test(process.env.PLAYCRAFT_LANG ?? process.env.LANG ?? '') ? messages.zh : messages.en;
-export async function createBatchDraft(path, client = new AgentApiClient()) {
-    const draft = batchCreateSchema.parse(JSON.parse(await readFile(path, 'utf8')));
-    return client.post('/create-batch', draft);
-}
-export async function createPromptBatch(input, client = new AgentApiClient()) {
-    return client.post('/create-batch', batchPromptCreateSchema.parse(input));
-}
-export function registerBatchCommands(tools) {
-    const t = language();
-    tools.command('create-batch')
-        .description(t.create)
-        .option('--input <path>', t.input)
-        .option('--prompt <text>', t.prompt)
-        .option('--workspace-id <id>', t.workspace)
-        .option('--source-directory <name>', t.directory, 'basic')
-        .option('--client-request-id <id>', t.request)
-        .option('--team-id <id>', t.team)
-        .option('--json', 'JSON (JavaScript Object Notation, 数据交换格式)')
-        .addHelpText('after', t.help)
-        .action(async (opts) => {
-        try {
-            if (Boolean(opts.input) === Boolean(opts.prompt))
-                throw new Error(t.invalidMode);
-            if (opts.prompt && !opts.workspaceId)
-                throw new Error(t.invalidMode);
-            if (opts.prompt && !opts.clientRequestId)
-                throw new Error(t.requestRequired);
-            const result = opts.input ? await createBatchDraft(opts.input) : await createPromptBatch({
-                clientRequestId: opts.clientRequestId, prompt: opts.prompt,
-                sourceWorkspaceId: opts.workspaceId, sourceDirectoryName: opts.sourceDirectory,
-                ...(opts.teamId ? { teamId: opts.teamId } : {}),
-            });
-            console.log(opts.json ? JSON.stringify(result, null, 2) : `${t.created}: ${result.batchId}\n${result.manifest.autoStart ? t.confirmation : t.review}`);
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    tools.command('get-batch')
-        .description(t.status)
-        .requiredOption('--batch-id <id>', t.id)
-        .action(async (opts) => {
-        try {
-            const client = new AgentApiClient();
-            const result = await client.get('/get-batch', { batchId: opts.batchId });
-            console.log(JSON.stringify(result, null, 2));
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-}

package/dist/commands/video.js

@@ -1,111 +0,0 @@
-import { videoAnalysisRunSchema, videoModelCatalogSchema } from '@playcraft/common/agent-tools';
-import { AgentApiClient } from '../utils/agent-api-client.js';
-import { executeVideoUnderstanding, readVideoRun, requireVideoId, resolveVideoWorkspace, videoTimeout, } from '../video-replication/client.js';
-import { materializeVideoEvidence } from '../video-replication/evidence.js';
-import { probeVideo } from '../video-replication/media.js';
-import { VideoCliError, videoMessage as t } from '../video-replication/messages.js';
-import { comparisonMessage as c } from '../video-replication/comparison-messages.js';
-import { executeVideoComparison, readComparisonRun, comparisonRunResult } from '../video-replication/comparison.js';
-import { materializeComparisonEvidence } from '../video-replication/comparison-evidence.js';
-/** One final structured stdout record; progress and diagnostics stay on stderr. */
-export async function runVideoCliAction(command, options, action) {
-    const interrupt = new AbortController();
-    const onInterrupt = () => interrupt.abort(new DOMException('Interrupted', 'AbortError'));
-    process.once('SIGINT', onInterrupt);
-    let timer;
-    const deadline = new AbortController();
-    try {
-        timer = setTimeout(() => deadline.abort(new DOMException('Timed out', 'TimeoutError')), videoTimeout(options));
-        const result = await action(AbortSignal.any([interrupt.signal, deadline.signal]));
-        process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
-        process.exitCode = result.exitCode;
-    }
-    catch (error) {
-        const key = error instanceof VideoCliError ? error.code : interrupt.signal.aborted ? 'interrupted' : deadline.signal.aborted ? 'timeoutReached' : 'failed';
-        const envelope = {
-            schemaVersion: 'playcraft.video-cli.v1', command, state: interrupt.signal.aborted || deadline.signal.aborted ? 'uncertain' : 'failed', ok: false,
-            error: { code: key, message: t(key) },
-        };
-        process.stdout.write(`${JSON.stringify(envelope)}\n`);
-        process.exitCode = error instanceof VideoCliError ? error.exitCode : interrupt.signal.aborted ? 130 : deadline.signal.aborted ? 75 : 4;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-        process.removeListener('SIGINT', onInterrupt);
-    }
-}
-function shared(command) {
-    return command.option('--workspace <id>', t('workspace')).option('--timeout <seconds>', t('timeout'));
-}
-export function registerVideoCommands(program) {
-    const video = program.command('video').description(t('topic'));
-    shared(video.command('models').description(t('models')))
-        .option('--json', t('json'))
-        .action((options) => runVideoCliAction('video models', options, async (signal) => {
-        const workspaceId = await resolveVideoWorkspace(options.workspace);
-        const catalog = videoModelCatalogSchema.parse(await new AgentApiClient().get('/video-models', { workspaceId }, { signal }));
-        return { exitCode: 0, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video models', state: 'completed', ok: true, result: catalog } };
-    }));
-    shared(video.command('understand').description(t('understand')))
-        .option('--video <path>', t('video')).option('--question <text>', t('question'))
-        .option('--context <path>', t('context')).option('--processing <mode>', t('processing'))
-        .option('--fps <number>', t('fps')).option('--clip <start:end>', t('clip'))
-        .option('--model-config <id>', t('model')).option('--out <directory>', t('out'))
-        .option('--resume <runId>', t('resume'))
-        .action((options) => runVideoCliAction('video understand', options, signal => executeVideoUnderstanding(options, signal, {
-        client: new AgentApiClient(), probe: probeVideo, materialize: materializeVideoEvidence,
-        progress: key => process.stderr.write(`[video] ${t(key)}\n`),
-    })));
-    shared(video.command('compare').description(c('compare')))
-        .option('--reference <path>', c('reference')).option('--analysis <path>', c('analysis'))
-        .option('--candidate <path>', c('candidate')).option('--recording <path>', c('recording'))
-        .option('--policy <path>', c('policy')).option('--processing <mode>', c('processing'))
-        .option('--fps <number>', t('fps')).option('--model-config <id>', t('model'))
-        .option('--out <directory>', t('out')).option('--resume <runId>', t('resume'))
-        .action((options) => runVideoCliAction('video compare', options, signal => executeVideoComparison(options, signal, {
-        client: new AgentApiClient(), probe: probeVideo, materialize: materializeComparisonEvidence,
-        progress: key => process.stderr.write(`[video] ${t(key)}\n`),
-    })));
-    const jobs = video.command('jobs').description(t('jobs'));
-    shared(jobs.command('get <runId>').description(t('get')))
-        .option('--kind <kind>', c('kind'))
-        .action((runId, options) => runVideoCliAction('video jobs get', options, async (signal) => {
-        const workspaceId = await resolveVideoWorkspace(options.workspace);
-        if (options.kind !== undefined && !['understanding', 'comparison'].includes(options.kind))
-            throw new VideoCliError('invalidArguments', 64);
-        if (options.kind === 'comparison') {
-            const run = await readComparisonRun(new AgentApiClient(), requireVideoId(runId), workspaceId, signal);
-            return comparisonRunResult('video jobs get', run);
-        }
-        const run = await readVideoRun(new AgentApiClient(), requireVideoId(runId), workspaceId, signal);
-        return { exitCode: run.state === 'uncertain' ? 75 : run.state === 'failed' || run.state === 'cancelled' ? 4 : 0, envelope: {
-                schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs get', runId: run.runId, state: run.state,
-                ok: !['failed', 'uncertain', 'cancelled'].includes(run.state), result: run,
-            } };
-    }));
-    shared(jobs.command('cancel <runId>').description(t('cancel')))
-        .option('--kind <kind>', c('kind'))
-        .action((identifier, options) => runVideoCliAction('video jobs cancel', options, async (signal) => {
-        const workspaceId = await resolveVideoWorkspace(options.workspace);
-        const runId = requireVideoId(identifier);
-        if (options.kind !== undefined && !['understanding', 'comparison'].includes(options.kind))
-            throw new VideoCliError('invalidArguments', 64);
-        if (options.kind === 'comparison') {
-            const run = await readComparisonRun(new AgentApiClient(), runId, workspaceId, signal, true);
-            const confirmed = run.state === 'cancelled';
-            return { exitCode: confirmed ? 0 : 75, envelope: {
-                    schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs cancel', runId, state: run.state,
-                    ok: confirmed, result: { ...run, cancellationConfirmed: confirmed },
-                } };
-        }
-        const run = videoAnalysisRunSchema.parse(await new AgentApiClient().post(`/video-analysis/${runId}/cancel`, { workspaceId, runId }, { signal }));
-        if (run.runId !== runId || run.workspaceId !== workspaceId)
-            throw new VideoCliError('invalidResult');
-        const confirmed = run.state === 'cancelled';
-        return { exitCode: confirmed ? 0 : 75, envelope: {
-                schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs cancel', runId, state: run.state,
-                ok: confirmed, result: { ...run, cancellationConfirmed: confirmed },
-            } };
-    }));
-}

package/dist/commands/workspace-runtime.js

@@ -1,54 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { INCOMPATIBLE_EXIT_CODE, parseSandboxRuntimeConfig, } from '@playcraft/common/cloud-workspace/runtime';
-import { startWorkspaceRuntime } from '../workspace-runtime/serve.js';
-export async function runWorkspaceRuntimeServe(configPath) {
-    process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
-    let config;
-    try {
-        config = parseSandboxRuntimeConfig(JSON.parse(await readFile(configPath, 'utf8')));
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`workspace-runtime config invalid: ${message}`);
-        process.exitCode = INCOMPATIBLE_EXIT_CODE;
-        return;
-    }
-    try {
-        const runtime = await startWorkspaceRuntime(config, { configPath });
-        console.log(JSON.stringify({
-            status: 'listening',
-            url: runtime.url,
-            phase: 'awaiting_native',
-            protocolMajor: runtime.config.protocolMajor,
-            protocolMinor: runtime.config.protocolMinor,
-        }));
-        await new Promise((resolve) => {
-            const stop = () => {
-                void runtime.close().finally(resolve);
-            };
-            process.once('SIGINT', stop);
-            process.once('SIGTERM', stop);
-        });
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === 'protocol_incompatible' || code === 'duplicate_instance') {
-            console.error(error instanceof Error ? error.message : code);
-            process.exitCode = INCOMPATIBLE_EXIT_CODE;
-            return;
-        }
-        throw error;
-    }
-}
-export function registerWorkspaceRuntimeCommands(program) {
-    const workspaceRuntime = program
-        .command('workspace-runtime')
-        .description('沙箱内 Sandbox Agent Server（Cloud Workspace 常驻运行入口）');
-    workspaceRuntime
-        .command('serve')
-        .description('前台常驻：读取 Runtime Server 下发的配置，不启动本地 backend 或旧同步')
-        .requiredOption('--config <path>', 'Runtime 引导配置 JSON')
-        .action(async (options) => {
-        await runWorkspaceRuntimeServe(options.config);
-    });
-}

package/dist/commands/workspace.js

@@ -1,35 +0,0 @@
-import { workspaceClone, workspacePush } from '../workspace/transfer-client.js';
-import { workspaceMessage as message } from '../workspace/messages.js';
-export function registerWorkspaceCommands(program) {
-    const run = async (command, options) => {
-        try {
-            if (command === 'clone')
-                await workspaceClone({ ...options, workspaceId: options?.workspaceId ?? '' });
-            else
-                await workspacePush(options);
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            if (options?.json)
-                console.log(JSON.stringify({ ok: false, command: `workspace.${command}`, error: { message: detail } }));
-            else
-                console.error(detail);
-            process.exitCode = 1;
-        }
-    };
-    const workspace = program.command('workspace').description(message('description'));
-    workspace.command('clone').description(message('clone'))
-        .requiredOption('--workspace-id <id>', message('workspaceId'))
-        .option('--directory <name>', message('directory'), 'basic')
-        .option('--dir <path>', message('target'))
-        .option('--url <url>', message('url'))
-        .option('--token <token>', message('token'))
-        .option('--json', message('json'))
-        .action(options => run('clone', options));
-    workspace.command('push').description(message('push'))
-        .option('--dir <path>', message('target'))
-        .option('--url <url>', message('url'))
-        .option('--token <token>', message('token'))
-        .option('--json', message('json'))
-        .action(options => run('push', options));
-}

package/dist/project-skills/builtin-import.js

@@ -1,225 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
-import { canonicalProjectSkillsJson, declarationDigest, dependencyDigest, extractBundleArchive, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
-import { LEGACY_VIDEO_SOURCE_HASHES } from '@playcraft/common/cloud-workspace/runtime';
-import { projectSkillsCache } from './local-store.js';
-export const IMPORTABLE_BUILTIN_SKILLS = ['playcraft-video-understanding', 'playcraft-replica-validation'];
-export const platformSkillRef = (name) => `remix/${name}`;
-const hash = (value) => createHash('sha256').update(canonicalProjectSkillsJson(value)).digest('hex');
-async function safeDirectory(root, path) {
-    let current = root;
-    for (const part of path.split('/')) {
-        current = join(current, part);
-        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(current);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
-            throw new Error('workspace_skills_invalid');
-    }
-    return current;
-}
-/** Selects published platform revisions once; neither directory contents nor names authorize a replacement. */
-export async function selectPlatformSkillSnapshot(names, access) {
-    if (!names.length || new Set(names).size !== names.length
-        || names.some(name => !IMPORTABLE_BUILTIN_SKILLS.includes(name)))
-        throw new Error('workspace_skills_builtin_unknown');
-    if (!access)
-        throw new Error('workspace_skills_platform_required');
-    const requested = names.map(platformSkillRef);
-    const response = await access.resolve(requested);
-    const snapshot = validateProjectSkillsSnapshot(response?.declaration, response?.lock);
-    if (snapshot.declaration.entries.length !== names.length || snapshot.lock.entries.length !== names.length)
-        throw new Error('workspace_skills_invalid');
-    for (const name of names) {
-        const entry = snapshot.declaration.entries.find(item => item.entryKey === name);
-        const locked = snapshot.lock.entries.find(item => item.entryKey === name);
-        if (!entry || !locked || entry.source.kind !== 'registry' || entry.source.skillRef !== platformSkillRef(name)
-            || entry.surface !== 'sandbox-agent' || !entry.enabled || locked.revision.kind !== 'release'
-            || locked.dependencies.length !== 0 || locked.dependencyLockHash !== dependencyDigest([], []))
-            throw new Error('workspace_skills_invalid');
-    }
-    const artifacts = await Promise.all(snapshot.lock.entries.map(async (entry) => {
-        const archive = await access.loadArtifact(entry);
-        if (archive.length > 80 * 1024 * 1024 || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
-            throw new Error('workspace_skills_digest_mismatch');
-        const extracted = extractBundleArchive(archive);
-        if (extracted.issues.length || !extracted.files.some(file => file.path === 'SKILL.md'))
-            throw new Error('workspace_skills_invalid_bundle');
-        return { artifactHash: entry.revision.artifactHash, archive };
-    }));
-    return { ...snapshot, artifacts };
-}
-async function commitSnapshot(directory, snapshot, originalDeclaration, staged) {
-    const declarationPath = join(directory, PROJECT_SKILLS_DECLARATION_PATH);
-    const pending = [];
-    for (const [path, value] of [[PROJECT_SKILLS_DECLARATION_PATH, snapshot.declaration], [PROJECT_SKILLS_LOCK_PATH, snapshot.lock]]) {
-        const temporary = `${join(directory, path)}.${randomUUID()}.tmp`;
-        staged.push(temporary);
-        await writeFile(temporary, `${canonicalProjectSkillsJson(value)}\n`, { flag: 'wx', mode: 0o644 });
-        pending.push(temporary);
-    }
-    await rename(pending[0], declarationPath);
-    try {
-        await rename(pending[1], join(directory, PROJECT_SKILLS_LOCK_PATH));
-    }
-    catch (error) {
-        // The old lock still exists. Restore its exact declaration before releasing the writer lease.
-        const restore = `${declarationPath}.${randomUUID()}.tmp`;
-        staged.push(restore);
-        await writeFile(restore, originalDeclaration, { flag: 'wx', mode: 0o644 });
-        await rename(restore, declarationPath);
-        throw error;
-    }
-}
-async function cacheArtifacts(cache, selected) {
-    await mkdir(cache, { recursive: true, mode: 0o700 });
-    for (const artifact of selected.artifacts) {
-        const path = join(cache, `${artifact.artifactHash}.tar.gz`);
-        try {
-            await writeFile(path, artifact.archive, { flag: 'wx', mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || !(await readFile(path)).equals(artifact.archive))
-                throw error;
-        }
-    }
-}
-/** Explicit imports keep prior locks and unsynced repository sources byte-for-byte. */
-export async function importBuiltinProjectSkills(directory, options, cache = projectSkillsCache(), access, selected, enabled = false) {
-    if (!options.names.length || new Set(options.names).size !== options.names.length
-        || options.names.some(name => !IMPORTABLE_BUILTIN_SKILLS.includes(name)))
-        throw new Error('workspace_skills_builtin_unknown');
-    const management = await safeDirectory(directory, '.playcraft');
-    const lease = join(management, 'skills-write.lock');
-    await writeFile(lease, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
-    const staged = [];
-    try {
-        const declarationPath = join(directory, PROJECT_SKILLS_DECLARATION_PATH);
-        const declarationStat = await lstat(declarationPath);
-        if (!declarationStat.isFile() || declarationStat.isSymbolicLink() || declarationStat.size > 1024 * 1024)
-            throw new Error('workspace_skills_invalid');
-        const originalDeclaration = await readFile(declarationPath);
-        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), await readProjectSkillsLockFile(directory));
-        if (options.expectedDeclarationHash !== previous.lock.declarationHash || options.expectedLockHash !== hash(previous.lock))
-            throw new Error('skills_revision_conflict');
-        const next = structuredClone(previous);
-        const unchanged = [], missing = [];
-        for (const name of options.names) {
-            const existing = previous.declaration.entries.find(entry => entry.source.kind === 'registry' && entry.source.skillRef === platformSkillRef(name));
-            if (existing) {
-                unchanged.push(existing.entryKey);
-                continue;
-            }
-            if (previous.declaration.entries.some(entry => entry.entryKey === name || entry.source.kind === 'repository' && basename(entry.source.root) === name))
-                throw new Error('workspace_skills_builtin_conflict');
-            for (const sourceRoot of ['.agents/skills', '.claude/skills', '.opencode/skills', '.opencode/skill']) {
-                if (await lstat(join(directory, sourceRoot, name)).then(() => true, error => { if (error.code === 'ENOENT')
-                    return false; throw error; }))
-                    throw new Error('workspace_skills_builtin_conflict');
-            }
-            missing.push(name);
-        }
-        const imported = [];
-        if (missing.length) {
-            const resolved = selected ?? await selectPlatformSkillSnapshot(missing, access);
-            await cacheArtifacts(cache, resolved);
-            for (const name of missing) {
-                const entry = resolved.declaration.entries.find(item => item.entryKey === name);
-                const locked = resolved.lock.entries.find(item => item.entryKey === name);
-                if (!entry || !locked)
-                    throw new Error('workspace_skills_invalid');
-                next.declaration.entries.push({ ...entry, enabled });
-                next.lock.entries.push(locked);
-                imported.push(name);
-            }
-            next.lock.declarationHash = declarationDigest(next.declaration);
-            validateProjectSkillsSnapshot(next.declaration, next.lock);
-            await commitSnapshot(directory, next, originalDeclaration, staged);
-        }
-        return { ...next, imported, unchanged, lockHash: hash(next.lock) };
-    }
-    finally {
-        for (const path of staged)
-            await rm(path, { force: true });
-        await rm(lease, { force: true });
-    }
-}
-/** Only original bundled sources qualify; changed or forked skills require a separate explicit user decision. */
-export async function migrateVideoProjectSkills(directory, options, cache, access) {
-    const management = await safeDirectory(directory, '.playcraft');
-    const lease = join(management, 'skills-write.lock');
-    await writeFile(lease, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
-    const moved = [];
-    const staged = [];
-    let committed = false;
-    try {
-        const declarationPath = join(directory, PROJECT_SKILLS_DECLARATION_PATH);
-        const declarationStat = await lstat(declarationPath);
-        if (!declarationStat.isFile() || declarationStat.isSymbolicLink() || declarationStat.size > 1024 * 1024)
-            throw new Error('workspace_skills_invalid');
-        const originalDeclaration = await readFile(declarationPath);
-        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), await readProjectSkillsLockFile(directory));
-        const oldLockHash = hash(previous.lock);
-        if (options.expectedDeclarationHash !== previous.lock.declarationHash || options.expectedLockHash !== oldLockHash)
-            throw new Error('skills_revision_conflict');
-        if (!options.entryKeys.length || options.entryKeys.length > 2 || new Set(options.entryKeys).size !== options.entryKeys.length)
-            throw new Error('workspace_skills_builtin_unknown');
-        const replacements = [];
-        for (const key of options.entryKeys) {
-            const entry = previous.declaration.entries.find(item => item.entryKey === key);
-            const locked = previous.lock.entries.find(item => item.entryKey === key);
-            if (!entry || !locked || entry.source.kind !== 'repository' || locked.revision.kind !== 'source'
-                || entry.surface !== 'sandbox-agent' || entry.projectFiles?.length || locked.dependencies.length
-                || previous.lock.entries.some(item => item.entryKey !== key && item.dependencies.includes(key)))
-                throw new Error('workspace_skills_builtin_conflict');
-            const name = basename(entry.source.root);
-            const known = LEGACY_VIDEO_SOURCE_HASHES[name];
-            if (!known || locked.sourceTreeHash !== known || (await readProjectSkillSource(directory, entry)).sourceTreeHash !== known
-                || previous.declaration.entries.some(item => item.entryKey !== key && (item.entryKey === name || item.source.kind === 'registry' && item.source.skillRef === platformSkillRef(name))))
-                throw new Error('workspace_skills_builtin_conflict');
-            replacements.push({ entry, name });
-        }
-        const selected = await selectPlatformSkillSnapshot(replacements.map(item => item.name), access);
-        await cacheArtifacts(cache, selected);
-        const next = structuredClone(previous);
-        for (const { entry, name } of replacements) {
-            const replacement = selected.declaration.entries.find(item => item.entryKey === name);
-            const locked = selected.lock.entries.find(item => item.entryKey === name);
-            next.declaration.entries[next.declaration.entries.findIndex(item => item.entryKey === entry.entryKey)] = { ...replacement, entryKey: entry.entryKey, enabled: entry.enabled };
-            next.lock.entries[next.lock.entries.findIndex(item => item.entryKey === entry.entryKey)] = { ...locked, entryKey: entry.entryKey };
-        }
-        for (const locked of next.lock.entries)
-            locked.dependencyLockHash = dependencyDigest(next.lock.entries, locked.dependencies);
-        next.lock.declarationHash = declarationDigest(next.declaration);
-        validateProjectSkillsSnapshot(next.declaration, next.lock);
-        const history = await safeDirectory(directory, `.playcraft/skill-migrations/${oldLockHash}`);
-        const receipt = { schemaVersion: 'playcraft.skill-migration.v1', previous, next, entryKeys: options.entryKeys };
-        const historyFile = join(history, 'migration.json');
-        try {
-            await writeFile(historyFile, `${canonicalProjectSkillsJson(receipt)}\n`, { flag: 'wx', mode: 0o644 });
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || await readFile(historyFile, 'utf8') !== `${canonicalProjectSkillsJson(receipt)}\n`)
-                throw error;
-        }
-        for (const { entry } of replacements) {
-            if (entry.source.kind !== 'repository')
-                throw new Error('workspace_skills_invalid');
-            const from = join(directory, entry.source.root), to = join(history, entry.entryKey);
-            await rename(from, to);
-            moved.push({ from, to });
-        }
-        await commitSnapshot(directory, next, originalDeclaration, staged);
-        committed = true;
-        return { ...next, migrated: options.entryKeys, history: `.playcraft/skill-migrations/${oldLockHash}/migration.json`, lockHash: hash(next.lock) };
-    }
-    finally {
-        if (!committed)
-            for (const item of moved.reverse())
-                await rename(item.to, item.from).catch(() => undefined);
-        for (const path of staged)
-            await rm(path, { force: true });
-        await rm(lease, { force: true });
-    }
-}