@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/commands/video.js

@@ -0,0 +1,122 @@
+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, ComparisonCliError } from '../video-replication/comparison-messages.js';
+import { describeVideoFailure, remoteVideoFailure } from '../video-replication/diagnostics.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]));
+        if (result.envelope.error)
+            process.stderr.write(`[video] ${result.envelope.error.message}\n`);
+        process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
+        process.exitCode = result.exitCode;
+    }
+    catch (error) {
+        const known = error instanceof VideoCliError || error instanceof ComparisonCliError;
+        const key = known ? error.code : interrupt.signal.aborted ? 'interrupted' : deadline.signal.aborted ? 'timeoutReached' : 'failed';
+        const summary = error instanceof ComparisonCliError ? c(error.code) : error instanceof VideoCliError ? t(error.code)
+            : interrupt.signal.aborted ? t('interrupted') : deadline.signal.aborted ? t('timeoutReached') : command === 'video compare' ? c('comparisonFailed') : t('failed');
+        const envelope = {
+            schemaVersion: 'playcraft.video-cli.v1', command, state: interrupt.signal.aborted || deadline.signal.aborted ? 'uncertain' : 'failed', ok: false,
+            error: { code: key, ...describeVideoFailure(summary, error, command === 'video models' ? 'models' : command === 'video jobs get' ? 'poll' : command === 'video jobs cancel' ? 'cancel' : 'prepare') },
+        };
+        process.stderr.write(`[video] ${envelope.error.message}\n`);
+        process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        process.exitCode = known ? 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);
+        const error = remoteVideoFailure(run.state, run.error);
+        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,
+                ...(error && { error }),
+            } };
+    }));
+    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 },
+                    ...(!confirmed && { error: { code: 'uncertain', ...describeVideoFailure(t('uncertain'), run.error?.code, 'cancel') } }),
+                } };
+        }
+        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 },
+                ...(!confirmed && { error: { code: 'uncertain', ...describeVideoFailure(t('uncertain'), run.error?.code, 'cancel') } }),
+            } };
+    }));
+}

package/dist/commands/workspace-runtime.js

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,40 @@
+import { workspaceClone, workspacePush } from '../workspace/transfer-client.js';
+import { workspaceMessage as message } from '../workspace/messages.js';
+import { normalizeWorkspaceTransferError, WorkspaceCliTransferError } from '../workspace/transfer-errors.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 normalized = normalizeWorkspaceTransferError(error);
+            const detail = normalized.message;
+            if (options?.json)
+                console.log(JSON.stringify({ ok: false, command: `workspace.${command}`, error: {
+                        code: normalized instanceof WorkspaceCliTransferError ? normalized.code : 'workspace_transfer_failed', message: detail,
+                        ...(normalized instanceof WorkspaceCliTransferError && normalized.details ? { details: normalized.details } : {}),
+                    } }));
+            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/config.js

@@ -2,7 +2,8 @@ import { cosmiconfig } from 'cosmiconfig';
 import { z } from 'zod';
 import path from 'path';
 import { homedir } from 'os';
-import { mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { randomUUID } from 'node:crypto';
 import 'dotenv/config';
 export const ConfigSchema = z.object({
     projectId: z.string().optional(),
@@ -18,6 +19,33 @@ const explorer = cosmiconfig('playcraft', {
 });
 const GLOBAL_CONFIG_DIR = path.join(homedir(), '.playcraft');
 const GLOBAL_CONFIG_FILE = path.join(GLOBAL_CONFIG_DIR, 'config.json');
+export function normalizeEnvironmentBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+            return undefined;
+        url.hash = '';
+        url.search = '';
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readEnvironmentProfile(config, baseUrl) {
+    const key = normalizeEnvironmentBaseUrl(baseUrl);
+    const profiles = config.environmentProfiles;
+    if (!key || !profiles || typeof profiles !== 'object' || Array.isArray(profiles))
+        return undefined;
+    const profile = profiles[key];
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile))
+        return undefined;
+    const value = profile;
+    if (typeof value.token !== 'string' || !value.token || normalizeEnvironmentBaseUrl(value.backendUrl) !== key)
+        return undefined;
+    return value;
+}
 export function loadGlobalConfig() {
     try {
         const content = readFileSync(GLOBAL_CONFIG_FILE, 'utf-8');
@@ -28,7 +56,8 @@ export function loadGlobalConfig() {
     }
 }
 export function saveGlobalConfig(partial) {
-    mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
+    mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true, mode: 0o700 });
+    chmodSync(GLOBAL_CONFIG_DIR, 0o700);
     let existing = {};
     try {
         existing = JSON.parse(readFileSync(GLOBAL_CONFIG_FILE, 'utf-8'));
@@ -37,7 +66,25 @@ export function saveGlobalConfig(partial) {
         // ignore
     }
     const merged = { ...existing, ...partial };
-    writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf-8');
+    const temporary = path.join(GLOBAL_CONFIG_DIR, `.config-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, JSON.stringify(merged, null, 2), { encoding: 'utf-8', flag: 'wx', mode: 0o600 });
+        renameSync(temporary, GLOBAL_CONFIG_FILE);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+export function saveEnvironmentProfile(baseUrl, profile) {
+    const key = normalizeEnvironmentBaseUrl(baseUrl);
+    if (!key)
+        throw new Error('Invalid environment address');
+    const current = loadGlobalConfig();
+    const profiles = current.environmentProfiles && typeof current.environmentProfiles === 'object'
+        && !Array.isArray(current.environmentProfiles) ? current.environmentProfiles : {};
+    saveGlobalConfig({ environmentProfiles: { ...profiles,
+            [key]: { ...profile, backendUrl: key, updatedAt: new Date().toISOString() } },
+        token: profile.token, url: key, backendUrl: key });
 }
 export async function loadConfig(cliOptions) {
     const result = await explorer.search(cliOptions.dir || process.cwd());
@@ -46,12 +93,20 @@ export async function loadConfig(cliOptions) {
         ? (fileConfig.agent || {})
         : fileConfig;
     const globalConfig = loadGlobalConfig();
+    const explicitTarget = cliOptions.url || process.env.PLAYCRAFT_URL || agentConfig.url;
+    const targetUrl = explicitTarget || globalConfig.url;
+    const profile = typeof targetUrl === 'string' ? readEnvironmentProfile(globalConfig, targetUrl) : undefined;
+    const legacyTarget = typeof globalConfig.backendUrl === 'string' ? globalConfig.backendUrl
+        : typeof globalConfig.url === 'string' ? globalConfig.url : undefined;
+    const legacyToken = !explicitTarget || (legacyTarget && normalizeEnvironmentBaseUrl(String(targetUrl)) === normalizeEnvironmentBaseUrl(legacyTarget))
+        ? globalConfig.token : undefined;
     const config = ConfigSchema.parse({
         ...globalConfig,
         ...agentConfig,
         ...cliOptions,
         projectId: cliOptions.projectId || process.env.PLAYCRAFT_PROJECT_ID || agentConfig.projectId || globalConfig.projectId,
-        token: cliOptions.token || process.env.PLAYCRAFT_TOKEN || agentConfig.token || globalConfig.token,
+        url: targetUrl,
+        token: cliOptions.token || process.env.PLAYCRAFT_TOKEN || agentConfig.token || profile?.token || legacyToken,
         port: cliOptions.port || (process.env.PLAYCRAFT_PORT ? parseInt(process.env.PLAYCRAFT_PORT) : undefined) || agentConfig.port || globalConfig.port,
         mode: cliOptions.mode || process.env.PLAYCRAFT_MODE || agentConfig.mode || globalConfig.mode,
         skillsDir: cliOptions.skillsDir || process.env.AGENT_SKILLS_DIR || agentConfig.skillsDir || globalConfig.skillsDir,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
+import { accountActivationMessage } from './auth/messages.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -17,6 +18,8 @@ import { checkForUpdates } from './utils/version-checker.js';
 import { syncCommand } from './commands/sync.js';
 import { fixIdsCommand } from './commands/fix-ids.js';
 import { registerToolsCommands } from './commands/tools.js';
+import { registerLibraryCommands } from './commands/library.js';
+import { registerWorkspaceAssetCommands } from './commands/assets.js';
 import { registerImageCommands } from './commands/image.js';
 import { registerAudioCommands } from './commands/audio.js';
 import { registerPrefabCommands } from './commands/prefab.js';
@@ -27,16 +30,30 @@ import { registerLevelsCommands } from './commands/levels.js';
 import { registerPatternsCommands } from './commands/patterns.js';
 import { registerPradCommands } from './commands/prad.js';
 import { register3DCommands } from './commands/3d.js';
+import { registerWorkspaceRuntimeCommands } from './commands/workspace-runtime.js';
+import { registerWorkspaceCommands } from './commands/workspace.js';
+import { registerVideoCommands } from './commands/video.js';
+import { registerPlayableCommands } from './commands/playable.js';
+import { registerPreviewRuntimeCommands } from './commands/preview-runtime.js';
+import { videoMessage } from './video-replication/messages.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
+const structuredVideoTopic = ['video', 'playable'].includes(process.argv[2] ?? '');
+const assetTopic = ['assets', 'library'].includes(process.argv[2] ?? '');
+const registryTopic = process.argv[2] === 'skills' && process.argv[3] === 'registry';
+if (structuredVideoTopic)
+    program.exitOverride();
 program.name('playcraft').description(CLI_ROOT_DESCRIPTION).version(packageJson.version);
+// Registry upload commands use --version for the skill, after the command name.
+if (registryTopic)
+    program.enablePositionalOptions();
 registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
-if (!process.argv.includes('upgrade')) {
+if (!structuredVideoTopic && !assetTopic && !registryTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -65,6 +82,8 @@ program
     .command('login')
     .description('登录 PlayCraft 账号并获取 CLI token')
     .option('--url <url>', 'Portal / API 基址（默认 https://playcraft.aix.intlgame.com，可用环境变量 PLAYCRAFT_URL 覆盖）')
+    .option('--activate', accountActivationMessage('activateOption'))
+    .option('--token <token>', accountActivationMessage('tokenOption'))
     .action(async (options) => {
     const { loginCommand } = await import('./commands/login.js');
     await loginCommand(options);
@@ -350,6 +369,8 @@ program
 });
 // Agent domain tools (playcraft tools <command>)
 registerToolsCommands(program);
+registerLibraryCommands(program);
+registerWorkspaceAssetCommands(program);
 // Local image processing (playcraft image <command>)
 registerImageCommands(program);
 // Local audio processing (playcraft audio <command>)
@@ -368,4 +389,27 @@ registerPatternsCommands(program);
 registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
-program.parse(process.argv);
+registerWorkspaceRuntimeCommands(program);
+registerWorkspaceCommands(program);
+registerVideoCommands(program);
+registerPlayableCommands(program);
+registerPreviewRuntimeCommands(program);
+if (structuredVideoTopic) {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.exitCode === 0)
+            process.exitCode = 0;
+        else {
+            const command = [process.argv[2], process.argv[3]?.startsWith('-') ? undefined : process.argv[3]].filter(Boolean).join(' ');
+            process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.video-cli.v1', command, state: 'failed', ok: false,
+                error: { code: 'invalidArguments', message: videoMessage('invalidArguments') } })}\n`);
+            process.exitCode = 64;
+        }
+    }
+}
+else
+    program.parse(process.argv);

package/dist/preview-runtime/distribution.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+export const PREVIEW_RUNTIME_DIRECTORY = '.playcraft/preview-runtime';
+const relativePath = z.string().min(1).refine(value => !value.startsWith('/') && !value.includes('\\') && value.split('/').every(part => part && part !== '.' && part !== '..'));
+export const previewRuntimeDistributionSchema = z.object({
+    version: z.literal(1), sdkVersion: z.string().min(1), protocolVersion: z.literal(1),
+    files: z.record(relativePath, z.string().regex(/^[a-f0-9]{64}$/)),
+}).strict();
+export const previewRuntimeSdkArtifactSchema = z.object({
+    path: z.literal('.playcraft/preview-runtime/runtime.mjs'),
+    sdkVersion: z.string().min(1), protocolVersion: z.literal(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+}).strict();
+export const previewRuntimeHash = (value) => createHash('sha256').update(value).digest('hex');
+export function previewRuntimeDistributionRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '../../templates/preview-runtime/v1');
+}
+export async function readPreviewRuntimeDistribution(source = previewRuntimeDistributionRoot()) {
+    const manifestBytes = await readFile(join(source, 'manifest.json'));
+    const manifest = previewRuntimeDistributionSchema.parse(JSON.parse(manifestBytes.toString()));
+    if (!manifest.files['runtime.mjs'] || !manifest.files['build-preview.mjs'] || !manifest.files['runtime.d.mts'])
+        throw new Error('preview_runtime_distribution_invalid');
+    return { source, manifest, manifestBytes };
+}
+async function safeTarget(root, relative) {
+    const segments = relativePath.parse(relative).split('/');
+    let current = root;
+    for (const segment of segments) {
+        current = join(current, segment);
+        const stat = await lstat(current).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (stat?.isSymbolicLink())
+            throw new Error('preview_runtime_path_invalid');
+    }
+    return current;
+}
+export async function initializePreviewRuntime(directory, source = previewRuntimeDistributionRoot()) {
+    const root = await realpath(directory);
+    const { manifest, manifestBytes } = await readPreviewRuntimeDistribution(source);
+    const files = new Map([['manifest.json', manifestBytes]]);
+    for (const [name, expected] of Object.entries(manifest.files)) {
+        const bytes = await readFile(await safeTarget(source, name));
+        if (previewRuntimeHash(bytes) !== expected)
+            throw new Error('preview_runtime_distribution_invalid');
+        files.set(name, bytes);
+    }
+    // Preflight every destination before writing, so known user changes are never partly overwritten.
+    const missing = [];
+    for (const [name, bytes] of files) {
+        const path = await safeTarget(root, PREVIEW_RUNTIME_DIRECTORY + '/' + name);
+        const existing = await readFile(path).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (existing && !existing.equals(bytes))
+            throw new Error('preview_runtime_modified:' + name);
+        if (!existing)
+            missing.push({ path, bytes });
+    }
+    for (const file of missing) {
+        await mkdir(dirname(file.path), { recursive: true });
+        await safeTarget(root, PREVIEW_RUNTIME_DIRECTORY + '/' + file.path.slice(join(root, PREVIEW_RUNTIME_DIRECTORY).length + 1));
+        try {
+            await writeFile(file.path, file.bytes, { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || !(await readFile(file.path)).equals(file.bytes))
+                throw error;
+        }
+    }
+    return {
+        status: missing.length ? 'initialized' : 'unchanged', directory: PREVIEW_RUNTIME_DIRECTORY,
+        sdkVersion: manifest.sdkVersion, protocolVersion: manifest.protocolVersion,
+        filesCreated: missing.length, requiresGameAdapter: true,
+    };
+}