@playcraft/cli 0.1.24 → 0.1.26

package/dist/commands/video.js

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

@@ -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/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';
@@ -27,16 +28,23 @@ 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 { registerVideoCommands } from './commands/video.js';
+import { registerPlayableCommands } from './commands/playable.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] ?? '');
+if (structuredVideoTopic)
+    program.exitOverride();
 program.name('playcraft').description(CLI_ROOT_DESCRIPTION).version(packageJson.version);
 registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
-if (!process.argv.includes('upgrade')) {
+if (!structuredVideoTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -65,6 +73,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);
@@ -368,4 +378,25 @@ registerPatternsCommands(program);
 registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
-program.parse(process.argv);
+registerWorkspaceRuntimeCommands(program);
+registerVideoCommands(program);
+registerPlayableCommands(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/project-skills/builtin-import.js

@@ -0,0 +1,225 @@
+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 });
+    }
+}

package/dist/project-skills/commands.js

@@ -0,0 +1,77 @@
+import { verifyLocalProjectSkills } from './validation.js';
+export { verifyLocalProjectSkills } from './validation.js';
+import { downloadLocalProjectSkillArtifacts } from './remote-cache.js';
+import { resolve } from 'node:path';
+import { inspectProjectSkills, } from '@playcraft/common/project-skills';
+import { syncLocalProjectSkills, enableLocalProjectSkill, installFrozenProjectSkills, explainLocalProjectSkills } from './local-store.js';
+import { runLocalProjectSkills, localProjectSkillUsage } from './local-run.js';
+import { projectSkillsMessage as t } from './messages.js';
+import { reconcileLocalProjectSkills } from './reconcile.js';
+import { importBuiltinProjectSkills } from './builtin-import.js';
+export async function inspectLocalProjectSkills(directory) {
+    const inventory = await inspectProjectSkills(directory);
+    // Report metadata only; never print complete skill bytes or project test data.
+    return { declaration: inventory.declaration, discovered: inventory.discovered, issues: inventory.issues,
+        sources: inventory.sources.map((source) => ({ entryKey: source.entryKey, root: source.root,
+            sourceTreeHash: source.sourceTreeHash, files: source.files.map((file) => file.path) })) };
+}
+export function registerProjectSkillsCommands(skills) {
+    const project = skills.command('project').description(t('description'));
+    const output = async (action) => {
+        try {
+            process.stdout.write(`${JSON.stringify(await action(), null, 2)}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error && error.message === 'workspace_skills_platform_required' ? t('platformRequired') : error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+    project.command('run <prompt>').description(t('run')).requiredOption('--model <provider/model>', t('model'))
+        .option('--dir <path>', t('directory'), '.').action((prompt, options) => output(async () => {
+        const result = await runLocalProjectSkills(resolve(options.dir), { prompt, model: options.model });
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+        return result;
+    }));
+    project.command('usage').description(t('usage')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => localProjectSkillUsage(resolve(options.dir))));
+    project.command('sync').description(t('sync')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => syncLocalProjectSkills(resolve(options.dir))));
+    project.command('import-builtins <names...>').description(t('importBuiltins')).option('--dir <path>', t('directory'), '.')
+        .requiredOption('--expected-declaration-hash <hash>', t('expectedDeclarationHash'))
+        .requiredOption('--expected-lock-hash <hash>', t('expectedLockHash'))
+        .action((names, options) => output(() => importBuiltinProjectSkills(resolve(options.dir), { ...options, names })));
+    project.command('reconcile').description(t('reconcile')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => reconcileLocalProjectSkills(resolve(options.dir), { write: true })));
+    project.command('install').description(t('install')).requiredOption('--frozen', t('frozen')).option('--dir <path>', t('directory'), '.')
+        .option('--online', t('online')).action((options) => output(async () => {
+        const directory = resolve(options.dir);
+        if (options.online)
+            await downloadLocalProjectSkillArtifacts(directory);
+        return installFrozenProjectSkills(directory);
+    }));
+    for (const enabled of [true, false])
+        project.command(enabled ? 'enable <entryKey>' : 'disable <entryKey>')
+            .description(t(enabled ? 'enable' : 'disable')).option('--dir <path>', t('directory'), '.')
+            .action((entryKey, options) => output(() => enableLocalProjectSkill(resolve(options.dir), entryKey, enabled)));
+    project.command('explain').description(t('explain')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => explainLocalProjectSkills(resolve(options.dir))));
+    project.command('inspect').description(t('inspect')).option('--dir <path>', t('directory'), '.')
+        .action(async (options) => {
+        const result = await inspectLocalProjectSkills(resolve(options.dir));
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (result.issues.length)
+            process.exitCode = 1;
+    });
+    project.command('verify').description(t('verify')).option('--dir <path>', t('directory'), '.')
+        .option('--json', t('json')).action(async (options) => {
+        try {
+            const result = await verifyLocalProjectSkills(resolve(options.dir));
+            process.stdout.write(`${options.json ? JSON.stringify(result) : t('verified')}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}