@playcraft/cli 0.1.40-beta → 0.1.42

package/dist/workspace-runtime/workspaces/transfer.js

@@ -1,288 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import { constants } from 'node:fs';
-import { chmod, copyFile, lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve, sep } from 'node:path';
-import { isCredentialFile } from './git.js';
-export const WORKSPACE_TRANSFER_MAX_BYTES = 256 * 1024 * 1024;
-const MAX_FILES = 20_000;
-const EXCLUDED = new Set(['.git', 'node_modules', '.playcraft-workspace.json', '.playcraft.json']);
-export class WorkspaceTransferError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
-function excluded(path) {
-    const parts = path.split('/');
-    return parts.some(part => EXCLUDED.has(part.toLowerCase()) || /^\.playcraft-(?:credential|transfer)-.*\.tmp$/i.test(part)) ||
-        parts.some((part, index) => part === '.playcraft' && /^(?:workspace-context(?:\..*)?|video-replication)$/.test(parts[index + 1] ?? '')) ||
-        isCredentialFile(path);
-}
-export function transferGit(root, args) {
-    const env = { PATH: process.env.PATH, HOME: tmpdir(),
-        GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0', GIT_ALLOW_PROTOCOL: 'file' };
-    const result = spawnSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'commit.gpgsign=false',
-        '-c', 'core.autocrlf=false', '-c', 'user.name=PlayCraft Workspace', '-c', 'user.email=workspace@playcraft.local', ...args], { cwd: root, encoding: 'utf8', env, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 });
-    if (result.status !== 0)
-        throw new WorkspaceTransferError('workspace_transfer_git_failed');
-    return result.stdout.trim();
-}
-async function copySnapshot(source, target) {
-    let bytes = 0, files = 0;
-    async function copy(directory, prefix) {
-        const directoryInfo = await lstat(directory);
-        const directoryReal = await realpath(directory);
-        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink() ||
-            (directoryReal !== source && !directoryReal.startsWith(`${source}${sep}`)))
-            throw new WorkspaceTransferError('workspace_transfer_conflict');
-        for (const entry of await readdir(directory, { withFileTypes: true })) {
-            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
-            if (excluded(path))
-                continue;
-            const from = join(directory, entry.name), to = join(target, path);
-            const info = await lstat(from);
-            if (info.isSymbolicLink())
-                continue;
-            if (info.isDirectory()) {
-                await mkdir(to, { recursive: true });
-                await copy(from, path);
-            }
-            else if (info.isFile()) {
-                bytes += info.size;
-                files++;
-                if (bytes > WORKSPACE_TRANSFER_MAX_BYTES || files > MAX_FILES)
-                    throw new WorkspaceTransferError('workspace_transfer_too_large');
-                if (!(await realpath(from)).startsWith(`${source}${sep}`))
-                    throw new WorkspaceTransferError('workspace_transfer_conflict');
-                const handle = await open(from, constants.O_RDONLY | constants.O_NOFOLLOW);
-                try {
-                    const before = await handle.stat();
-                    if (!before.isFile() || before.dev !== info.dev || before.ino !== info.ino || before.size !== info.size ||
-                        before.mtimeMs !== info.mtimeMs || before.ctimeMs !== info.ctimeMs)
-                        throw new WorkspaceTransferError('workspace_transfer_conflict');
-                    const chunks = [];
-                    let size = 0;
-                    for await (const chunk of handle.createReadStream({ autoClose: false })) {
-                        size += chunk.length;
-                        if (size > before.size)
-                            throw new WorkspaceTransferError('workspace_transfer_conflict');
-                        chunks.push(chunk);
-                    }
-                    const after = await handle.stat();
-                    if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
-                        throw new WorkspaceTransferError('workspace_transfer_conflict');
-                    await writeFile(to, Buffer.concat(chunks));
-                }
-                finally {
-                    await handle.close();
-                }
-                await chmod(to, info.mode & 0o111 ? 0o755 : 0o644);
-            }
-        }
-    }
-    await copy(source, '');
-}
-async function matchesFile(root, path, expected) {
-    const target = await safeTarget(root, path);
-    const info = await lstat(target).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
-        return undefined; throw error; });
-    if (!expected)
-        return !info || info.isDirectory();
-    if (!info?.isFile() || Boolean(info.mode & 0o111) !== expected.executable)
-        return false;
-    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
-    try {
-        const stat = await handle.stat();
-        const hash = createHash(expected.sha.length === 64 ? 'sha256' : 'sha1');
-        hash.update(`blob ${stat.size}\0`);
-        for await (const chunk of handle.createReadStream({ autoClose: false }))
-            hash.update(chunk);
-        return hash.digest('hex') === expected.sha;
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function removeEmptyParents(root, target) {
-    let parent = dirname(target);
-    while (parent !== root) {
-        if ((await readdir(parent)).length > 0)
-            break;
-        await rmdir(parent);
-        parent = dirname(parent);
-    }
-}
-async function installFile(root, path, source, executable) {
-    const target = await safeTarget(root, path);
-    const existing = await lstat(target).catch(error => { if (error.code === 'ENOENT')
-        return undefined; throw error; });
-    if (existing?.isDirectory())
-        await rmdir(target);
-    await mkdir(dirname(target), { recursive: true });
-    const stage = join(dirname(target), `.playcraft-transfer-${randomUUID()}.tmp`);
-    try {
-        await copyFile(source, stage);
-        await chmod(stage, executable ? 0o755 : 0o644);
-        await rename(stage, target);
-    }
-    catch (error) {
-        await rm(stage, { force: true }).catch(() => undefined);
-        await removeEmptyParents(root, target).catch(() => undefined);
-        throw error;
-    }
-    finally {
-        await rm(stage, { force: true }).catch(() => undefined);
-    }
-}
-/** A fresh history contains only the current portable files, including uncommitted changes. */
-export async function createWorkspaceTransfer(root) {
-    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-transfer-'));
-    const cleanup = () => rm(temporary, { recursive: true, force: true });
-    try {
-        const checkout = join(temporary, 'checkout');
-        await mkdir(checkout);
-        await copySnapshot(await realpath(root), checkout);
-        transferGit(checkout, ['init', '--initial-branch=main']);
-        transferGit(checkout, ['add', '--force', '--all']);
-        transferGit(checkout, ['commit', '--allow-empty', '-m', 'Workspace snapshot']);
-        const tree = transferGit(checkout, ['rev-parse', 'HEAD^{tree}']);
-        const head = transferGit(checkout, ['rev-parse', 'HEAD']);
-        const bundlePath = join(temporary, 'workspace.bundle');
-        transferGit(checkout, ['bundle', 'create', bundlePath, 'HEAD']);
-        return { bundlePath, tree, head, cleanup };
-    }
-    catch (error) {
-        await cleanup();
-        throw error;
-    }
-}
-function treeEntries(root) {
-    const entries = transferGit(root, ['ls-tree', '-r', '-z', 'HEAD']).split('\0').filter(Boolean).map(line => {
-        const match = /^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/s.exec(line);
-        if (!match)
-            throw new WorkspaceTransferError('invalid_workspace_transfer');
-        const path = match[3];
-        if (path.length > 1024 || path.includes('\\') || path.startsWith('/') || /[\x00-\x1f\x7f]/.test(path) ||
-            path.split('/').some(part => !part || part === '.' || part === '..') || excluded(path))
-            throw new WorkspaceTransferError('invalid_workspace_transfer');
-        return { path, sha: match[2], executable: match[1] === '100755' };
-    });
-    if (entries.length > MAX_FILES)
-        throw new WorkspaceTransferError('workspace_transfer_too_large');
-    const normalized = entries.map(entry => entry.path.toLowerCase());
-    if (new Set(normalized).size !== entries.length)
-        throw new WorkspaceTransferError('invalid_workspace_transfer');
-    return entries;
-}
-async function safeTarget(root, path) {
-    const target = resolve(root, path);
-    if (!target.startsWith(`${root}${sep}`))
-        throw new WorkspaceTransferError('invalid_workspace_transfer');
-    let current = root;
-    for (const segment of path.split('/')) {
-        current = join(current, segment);
-        const info = await lstat(current).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
-            return undefined; throw error; });
-        if (info?.isSymbolicLink())
-            throw new WorkspaceTransferError('workspace_transfer_symlink');
-    }
-    return target;
-}
-/** Compare the entire checkout before applying local commits, so cloud edits are never overwritten. */
-export async function applyWorkspaceTransfer(root, bundle, expectedTree) {
-    if (!/^[a-f0-9]{40,64}$/.test(expectedTree))
-        throw new WorkspaceTransferError('invalid_workspace_transfer');
-    if (!bundle.byteLength || bundle.byteLength > WORKSPACE_TRANSFER_MAX_BYTES)
-        throw new WorkspaceTransferError('workspace_transfer_too_large');
-    const rootReal = await realpath(root);
-    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-import-'));
-    let current;
-    try {
-        const bundlePath = join(temporary, 'incoming.bundle'), incoming = join(temporary, 'checkout');
-        await writeFile(bundlePath, bundle, { mode: 0o600 });
-        transferGit(temporary, ['clone', '--no-checkout', '--', bundlePath, incoming]);
-        const entries = treeEntries(incoming);
-        const tree = transferGit(incoming, ['rev-parse', 'HEAD^{tree}']);
-        const head = transferGit(incoming, ['rev-parse', 'HEAD']);
-        let bytes = 0;
-        for (const entry of entries) {
-            bytes += Number(transferGit(incoming, ['cat-file', '-s', entry.sha]));
-            if (bytes > WORKSPACE_TRANSFER_MAX_BYTES)
-                throw new WorkspaceTransferError('workspace_transfer_too_large');
-        }
-        current = await createWorkspaceTransfer(rootReal);
-        if (current.tree === tree)
-            return { tree, head, changedPaths: [] };
-        if (current.tree !== expectedTree)
-            throw new WorkspaceTransferError('workspace_transfer_conflict');
-        const baseline = join(dirname(current.bundlePath), 'checkout');
-        const previous = new Map(treeEntries(baseline).map(entry => [entry.path, entry]));
-        const next = new Map(entries.map(entry => [entry.path, entry]));
-        const changedPaths = [...new Set([...previous.keys(), ...next.keys()])]
-            .filter(path => previous.get(path)?.sha !== next.get(path)?.sha || previous.get(path)?.executable !== next.get(path)?.executable);
-        for (const path of changedPaths) {
-            const target = await safeTarget(rootReal, path);
-            const info = await lstat(target).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
-                return undefined; throw error; });
-            if (next.has(path) && info?.isDirectory()) {
-                const children = await readdir(target, { recursive: true });
-                for (const child of children) {
-                    const childPath = `${path}/${child.split(sep).join('/')}`;
-                    const childInfo = await lstat(join(target, child));
-                    if (!childInfo.isDirectory() && (!previous.has(childPath) || next.has(childPath)))
-                        throw new WorkspaceTransferError('workspace_transfer_conflict');
-                }
-            }
-        }
-        transferGit(incoming, ['checkout', '--force']);
-        const recheck = await createWorkspaceTransfer(rootReal);
-        try {
-            if (recheck.tree !== expectedTree)
-                throw new WorkspaceTransferError('workspace_transfer_conflict');
-        }
-        finally {
-            await recheck.cleanup();
-        }
-        const applied = [];
-        try {
-            // Deleting files first also permits a file to become a directory, or the reverse.
-            for (const path of changedPaths.filter(path => !next.has(path)).sort((a, b) => b.length - a.length)) {
-                if (!await matchesFile(rootReal, path, previous.get(path)))
-                    throw new WorkspaceTransferError('workspace_transfer_conflict');
-                await rm(await safeTarget(rootReal, path), { force: true });
-                applied.push(path);
-                await removeEmptyParents(rootReal, join(rootReal, path));
-            }
-            for (const path of changedPaths.filter(path => next.has(path))) {
-                if (!await matchesFile(rootReal, path, previous.get(path)))
-                    throw new WorkspaceTransferError('workspace_transfer_conflict');
-                const entry = next.get(path);
-                await installFile(rootReal, path, join(incoming, path), entry.executable);
-                applied.push(path);
-            }
-        }
-        catch (error) {
-            // Roll back only our writes; never replace another writer's intervening content.
-            for (const path of applied.reverse()) {
-                if (!await matchesFile(rootReal, path, next.get(path)))
-                    throw new WorkspaceTransferError('workspace_transfer_rollback_conflict');
-                const old = previous.get(path);
-                if (old)
-                    await installFile(rootReal, path, join(baseline, path), old.executable);
-                else {
-                    await rm(await safeTarget(rootReal, path), { force: true });
-                    await removeEmptyParents(rootReal, join(rootReal, path));
-                }
-            }
-            throw error;
-        }
-        return { tree, head, changedPaths };
-    }
-    finally {
-        await current?.cleanup();
-        await rm(temporary, { recursive: true, force: true });
-    }
-}

package/dist/workspace-runtime/workspaces/turn-changes.js

@@ -1,75 +0,0 @@
-import { TURN_FILES_CHANGED_EVENT, } from '@playcraft/common/cloud-workspace/runtime';
-import { diffWorkspaceTrees, retainTurnSnapshots, snapshotWorkspaceTree } from './git.js';
-import { shareWorkspaceGit } from './shared-git.js';
-const TURN_ENDS = new Set(['turn/completed', 'turn.completed', 'turn.interrupted', 'turn.failed']);
-/**
- * Snapshots taken when a session's turn starts, until that turn ends. Kept in memory only: a
- * restart ends the native turn as well, and that turn then simply reports no changes.
- */
-const started = new WeakMap();
-function turnsOf(state) {
-    let turns = started.get(state);
-    if (!turns)
-        started.set(state, turns = new Map());
-    return turns;
-}
-/**
- * Records the work tree before a turn is sent. A directory that cannot be snapshotted (no
- * repository, Git failure) gets no change summary; the turn itself is never held back by it.
- */
-export async function beginTurnChanges(state, sessionId, input) {
-    turnsOf(state).delete(sessionId);
-    if (input.directoryName === 'root')
-        return;
-    await shareWorkspaceGit(state, input.root).catch(() => undefined);
-    const before = await snapshotWorkspaceTree(input.root).catch(() => undefined);
-    if (before)
-        turnsOf(state).set(sessionId, { ...input, before });
-}
-/** A turn that never started has nothing to compare. */
-export function abandonTurnChanges(state, sessionId) {
-    turnsOf(state).delete(sessionId);
-}
-/**
- * When a session's turn ends, compares the work tree with its start and records the files that
- * changed for that session's conversation. Returns no event when nothing changed.
- */
-export async function finishTurnChanges(state, event) {
-    const { threadId, turnId } = event;
-    if (!TURN_ENDS.has(event.method) || !threadId || !turnId)
-        return [];
-    const session = state.journal.listSessions().find((item) => item.threadId === threadId);
-    const start = session && turnsOf(state).get(session.sessionId);
-    if (!session || !start)
-        return [];
-    turnsOf(state).delete(session.sessionId);
-    try {
-        await shareWorkspaceGit(state, start.root);
-        const after = await snapshotWorkspaceTree(start.root);
-        const { files, truncated } = await diffWorkspaceTrees(start.root, start.before, after);
-        if (!files.length)
-            return [];
-        await retainTurnSnapshots(start.root, turnId, start.before, after);
-        const changes = { threadId, turnId, before: start.before, after, files, truncated };
-        return [await state.journal.allocateSourceEvent({
-                runtimeId: state.config.runtimeId,
-                generation: state.config.generation,
-                runtimeEpoch: state.runtimeEpoch,
-                type: TURN_FILES_CHANGED_EVENT,
-                payload: {
-                    ...changes,
-                    sessionId: session.sessionId,
-                    ...(start.workspaceId ? { workspaceId: start.workspaceId } : {}),
-                    ...(start.directoryName ? { directoryName: start.directoryName } : {}),
-                },
-                occurredAt: new Date().toISOString(),
-                sessionId: session.sessionId,
-                workspaceId: start.workspaceId,
-                threadId,
-                turnId,
-            })];
-    }
-    catch {
-        return [];
-    }
-}

package/dist/workspace-runtime/workspaces/video-attachments.js

@@ -1,49 +0,0 @@
-import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
-/** Probe the opened descriptor so replacing a pathname cannot redirect the media reader. */
-export async function probeAttachmentVideo(handle) {
-    const output = await new Promise((resolve, reject) => {
-        const child = spawn(process.env.PLAYCRAFT_FFPROBE_PATH ?? 'ffprobe', [
-            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-show_entries',
-            'format=format_name,duration:stream=codec_type,width,height', '-of', 'json',
-            process.platform === 'linux' ? '/proc/self/fd/3' : '/dev/fd/3',
-        ], { stdio: ['ignore', 'pipe', 'ignore', handle.fd] });
-        let text = '';
-        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('invalid_attachment')); }, 15_000);
-        timer.unref();
-        child.stdout.on('data', (chunk) => {
-            text += chunk.toString('utf8');
-            if (text.length > 64 * 1024) {
-                child.kill('SIGKILL');
-                reject(new Error('invalid_attachment'));
-            }
-        });
-        child.once('error', () => { clearTimeout(timer); reject(new Error('video_probe_unavailable')); });
-        child.once('close', code => { clearTimeout(timer); code === 0 ? resolve(text) : reject(new Error('invalid_attachment')); });
-    });
-    const result = JSON.parse(output);
-    const stream = result.streams?.find(item => item.codec_type === 'video');
-    const durationMs = Math.round(Number(result.format?.duration) * 1000);
-    const formats = result.format?.format_name?.split(',') ?? [];
-    const mimeType = formats.includes('webm') ? 'video/webm' : formats.includes('mp4') ? 'video/mp4' : formats.includes('mov') ? 'video/quicktime' : undefined;
-    if (!stream || !mimeType || !Number.isFinite(durationMs) || durationMs <= 0 || durationMs > WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS
-        || !Number.isSafeInteger(stream.width) || !Number.isSafeInteger(stream.height) || stream.width <= 0 || stream.height <= 0
-        || stream.width > 16384 || stream.height > 16384)
-        throw new Error('invalid_attachment');
-    return { mimeType, durationMs, width: stream.width, height: stream.height };
-}
-export async function hashAttachment(handle) {
-    const digest = createHash('sha256');
-    const chunk = Buffer.allocUnsafe(64 * 1024);
-    let position = 0;
-    for (;;) {
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
-        if (!bytesRead)
-            return digest.digest('hex');
-        digest.update(chunk.subarray(0, bytesRead));
-        position += bytesRead;
-        if (position > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
-            throw new Error('invalid_attachment');
-    }
-}

package/project-template/.claude/skills/playcraft-replica-validation/SKILL.md

@@ -1,25 +0,0 @@
----
-name: playcraft-replica-validation
-description: Record a reconstructed browser playable with real inputs, compare it with its reference video, and use timestamped differences to improve the replica. Use after implementation or fixes; use video understanding first when the reference has not been analyzed.
-version: 1.0.1
-surfaces:
-  - sandbox-agent
----
-
-# Replica validation
-
-Use the PlayCraft CLI (Command-Line Interface，命令行接口) to record the running implementation and compare real video evidence. Codex chooses the scenario, reads the evidence, edits the playable, and repeats the checks. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
-
-Read [command and evidence contracts](references/contracts.md) before the first recording or comparison. Check `playcraft playable record --help`, `playcraft video compare --help`, and `playcraft video models --json`. If a required command is unavailable, report that the workspace CLI needs upgrading. Provider credentials and model requests belong to Model Proxy; do not call Gemini directly or copy a key into the project.
-
-Use a completed reference `analysis.json` from `playcraft-video-understanding`. Inspect its original keyframes and distinguish observed actions from inferred controls. Run from the project root. Write an explicit, versioned scenario for the current implementation, using real browser coordinates and inputs. Include the initial view, first action and result, principal feedback, and ending when demonstrated. Keep hidden rules and unshown branches unknown. Start or restart the current project using its own development command; do not depend on internal auto-play hooks. Confirm that the supplied development address belongs to this process and serves this round's version. If that cannot be confirmed, do not claim validation of the current version. The project digest proves the recorded checkout stayed unchanged, but does not attest which source version an already-running server serves.
-
-Record into a fresh directory under `.playcraft/video-replication/`. Keep the original recording, its input logs, scenario, control recordings, and project snapshot together. Do not edit the video or its manifest to repair a failing check. Match the reference viewport when practical and record enough time for every expected result. A completed recording proves capture succeeded; it does not prove the interaction worked.
-
-Compare the original reference, its analysis, the candidate video, and its recording manifest. Inspect `comparison.md`, `comparison.json`, paired keyframes, contact sheets, input logs, and controls using available image and file-reading tools. Review event alignment before judging motion or feedback timing. The model can suggest differences; the CLI derives the final status from validated evidence and the comparison policy. A single similarity score is insufficient. Keep the default full comparison policy for delivery; an explicitly limited diagnostic must be reported as partial coverage. Do not loosen thresholds just to obtain a passing result.
-
-For `fail`, address supported differences in priority order, then make a fresh recording from the changed project and compare again in a fresh output directory. For `inconclusive`, resolve missing controls, insufficient duration, unpaired required events, low confidence, or unknown input intent before declaring completion. Preserve valid differences even when other dimensions lack evidence. Report the tested path, unsupported branches, and unevaluated audio explicitly.
-
-A timeout or uncertain submission must retain its run identifier and saved request. Resume the same comparison with `playcraft video compare --resume <runId> --out <same-directory>`; recovery reads the existing task and never creates another paid request. Explicit cancellation is separate from ending the local wait. Do not resubmit because the command exited early. Treat malformed model output, stale recordings, changed hashes, or missing frames as errors, never as a passing comparison.
-
-Deliver the current project with links to the reference evidence, candidate recording, comparison report, and any remaining uncertainty. Keep validation evidence in workspace checkpoints and out of Git and deliverable builds.

package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md

@@ -1,79 +0,0 @@
-# Commands and evidence contracts
-
-The workspace CLI (Command-Line Interface，命令行接口) owns capture, upload, validation, frame extraction, and final status. The Skill supplies guidance only. Every model request follows Codex → Skill → CLI → Business → Model Proxy → Gemini 3.8 Flash.
-
-```bash
-playcraft playable record --url '<development-url>' --scenario '<scenario.json>' \
-  --out .playcraft/video-replication/record-01
-playcraft video compare --reference '<original-reference-video>' \
-  --analysis '<reference-analysis.json>' \
-  --candidate '.playcraft/video-replication/record-01/candidate.mp4' \
-  --recording '.playcraft/video-replication/record-01/metadata.json' \
-  --out .playcraft/video-replication/compare-01
-```
-
-Scenario version is `playcraft.replica-scenario.v1`; positions are normalized to the declared `contentRect`. Replace event identifiers with actual IDs from `analysis.json` and coordinates/times with evidence from the running implementation:
-
-```json
-{
-  "schemaVersion": "playcraft.replica-scenario.v1",
-  "draft": false,
-  "referenceEventIds": ["initial", "first-result", "main-result", "ending"],
-  "requiredEffects": [
-    { "stepId": "drag-one", "eventId": "first-result" },
-    { "stepId": "tap-two", "eventId": "main-result" }
-  ],
-  "controls": { "noInput": true, "omitRequiredSteps": true },
-  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 1 },
-  "contentRect": { "x": 0, "y": 0, "width": 1, "height": 1 },
-  "pointer": "touch",
-  "reset": { "kind": "fresh-context", "storage": "empty" },
-  "durationMs": 15000,
-  "steps": [
-    {
-      "id": "drag-one",
-      "atMs": 1000,
-      "type": "drag",
-      "path": [
-        { "offsetMs": 0, "x": 0.3, "y": 0.6 },
-        { "offsetMs": 600, "x": 0.7, "y": 0.6 }
-      ]
-    },
-    { "id": "tap-two", "atMs": 4000, "type": "tap", "x": 0.5, "y": 0.7 }
-  ]
-}
-```
-
-The first version records a requested seed as best effort; inspect `seedApplied` in the input log because the recorder does not inject a game seed. Fresh browser storage does not guarantee reset of server-side state.
-
-Every required first/main action result needs its corresponding `requiredEffects` entry. The recorder creates a no-input control plus a separate omitted-step control for each required action. Maximum three distinct required steps yield at most four controls. Disabling controls leaves interaction acceptance inconclusive.
-
-Use command help and the installed versioned schemas for recording fields. Do not guess manifest fields or synthesize a successful recording. Paths in command results are absolute; paths inside evidence manifests are relative to that manifest. Model output cannot provide artifact paths.
-
-`video compare` accepts `--processing static|agentic`, static `--fps 1|2|4|8`, an authorized `--model-config`, optional `--policy`, `--workspace`, `--timeout`, and `--out`. Static sampling is the default. Agentic execution cannot be combined with fixed sampling. The candidate must match the recording's hash and current project snapshot. The reference hash must match the completed analysis. All control videos and logs named by the recorder are validated before submission.
-
-The recording manifest version is `playcraft.replica-recording.v1`; the comparison result is `playcraft.replica-validation.v1`, and its evidence manifest is `playcraft.replica-evidence.v1`.
-
-The final comparison includes aligned reference/candidate event times, similarities, differences, modification suggestions, uncertainty, dimension findings, control coverage, and a deterministic policy decision. Paired frames come from decoded original video timestamps. Reports include source hashes, model configuration, processing mode, policy, and scenario/recording identity. Audio similarity is unevaluated in the first version.
-
-Read the final structured output once; progress is written separately. Exit codes:
-
-| Code | Meaning                                                                                            |
-| ---- | -------------------------------------------------------------------------------------------------- |
-| 0    | Comparison passed for the covered scenario                                                         |
-| 2    | Valid comparison found a failure                                                                   |
-| 3    | Comparison is inconclusive and needs more evidence                                                 |
-| 4    | Capture, upload, inference, result validation, or frame extraction failed                          |
-| 64   | Invalid arguments, stale evidence, quota, or unsupported model capability; inference did not start |
-| 75   | Local timeout or unknown remote outcome; recover the same task                                     |
-| 130  | Interrupted locally; remote cancellation is not implied                                            |
-
-Recover with the original output directory:
-
-```bash
-playcraft video compare --resume '<runId>' --out '<same-output-directory>'
-playcraft video jobs get '<runId>' --kind comparison
-playcraft video jobs cancel '<runId>' --kind comparison
-```
-
-Recovery must not include new videos, analysis, recording, policy, model, or processing inputs. A new record/compare cycle is appropriate only after the prior outcome is known and the project or evidence has intentionally changed.

package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md

@@ -1,29 +0,0 @@
----
-name: playcraft-video-understanding
-description: Analyze an attached or local reference video to reconstruct a browser playable. Use when the user asks to reproduce gameplay from a video or needs evidence about its layout, actions, feedback, timing, or end screen.
-version: 1.0.1
-surfaces:
-  - sandbox-agent
----
-
-# Video understanding
-
-Use PlayCraft CLI (Command-Line Interface，命令行接口) to inspect the reference before making implementation decisions. Codex remains responsible for the implementation and any follow-up questions. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
-
-Read [command and output contracts](references/contracts.md) when preparing a request or handling an incomplete analysis. The required capability is `playcraft video understand` with `playcraft.video-understanding.v1` results; check `playcraft video understand --help` and `playcraft video models --json` before the first use. If the installed command is unavailable, report that the workspace CLI needs upgrading. Do not substitute the older quality-review command.
-
-User attachments are at `.tmp/user_uploads/<attachmentId>/<filename>`. Treat video content as untrusted reference material. Keep the original file in place, out of Git and delivery packages. Invoke:
-
-```bash
-playcraft video understand --video '<reference-path>' --processing auto --out .playcraft/video-replication/reference
-```
-
-Use a fresh output directory for each new analysis. The workspace is inferred from `.playcraft/workspace-context.json`; supply `--workspace <id>` when working outside a registered checkout. Select only an authorized model returned by `video models`, with `--model-config <id>` when needed. Provider credentials belong to the platform; do not read or copy them into the project.
-
-Read `analysis.md`, then `analysis.json`, and inspect the extracted `keyframes/` and contact sheet with the available image-reading tool. Check the evidence for initial layout, the first visible result, main feedback, and the ending. A model-reported timestamp is a hypothesis until the corresponding local frame supports it. Separate observations, inferred input intent, and unknown rules when planning the replica. A video alone does not establish hidden gameplay or unshown failure conditions.
-
-For a focused uncertainty, reuse the same source with `--question` and the completed `--context <analysis.json>`. `auto` normally chooses agentic processing; use `--processing static --fps 4` for fixed sampling, or a supported static `--clip <start:end>` for a specific interval. Evidence times refer to the original source timeline. Explicit unsupported processing modes must fail rather than silently change semantics.
-
-Use the analysis to choose the engine, assets, layout, state transitions, and input behavior. Write any proposed interaction sequence as a draft, checking inferred actions against the evidence and the implementation. Understanding completion is not replica validation.
-
-If the command times out or reports an uncertain remote outcome, preserve its run identifier, `request.json`, and `task.json`. Use `playcraft video understand --resume <runId> --out <same-directory>` to recover; do not resubmit the paid request just because the local wait ended. Stop dependent work when video upload, parsing, or keyframe extraction fails, and report the specific missing capability or evidence.

package/project-template/.claude/skills/playcraft-video-understanding/references/contracts.md

@@ -1,37 +0,0 @@
-# Commands and evidence
-
-The command uses the platform authorization already installed in Cloud Workspace. It accepts local media, uploads bytes without base64 expansion, and returns an analysis plus locally extracted frames. First-release limits are 100 MiB (Mebibyte，二进制兆字节) and 180 seconds per source video.
-
-```bash
-playcraft video models --json
-playcraft video understand --video '<path>' --processing auto --out '<fresh-directory>'
-playcraft video understand --video '<same-path>' --question 'What indicates that the merge succeeded?' --context '<previous>/analysis.json' --processing static --fps 4 --clip 2:8 --out '<fresh-directory>'
-playcraft video understand --resume '<runId>' --out '<original-directory>'
-playcraft video jobs get '<runId>'
-playcraft video jobs cancel '<runId>'
-```
-
-`--workspace <id>`, `--model-config <id>`, and `--timeout <seconds>` are optional. New-input parameters cannot accompany `--resume`. `--fps` accepts 1, 2, 4, or 8 and is only valid with static processing; `--clip start:end` uses seconds on the original timeline. A follow-up context must refer to the same source digest. Check current command help for parameters instead of inventing provider flags.
-
-Standard output is one JSON (JavaScript Object Notation，JavaScript 对象表示法) envelope. Progress appears on standard error. The envelope has `schemaVersion: playcraft.video-cli.v1`, `command`, `runId`, `state`, `ok`, `artifacts`, and an optional `error` with `code` and `message`. Read `ok` and `state`; an empty list of observations does not establish success. Artifact paths returned by the command are absolute.
-
-| Artifact                     | How to use it                                                                                              |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `manifest.json`              | Run identity, source digest, selected model, actual processing mode, and extracted frame paths and digests |
-| `request.json`, `task.json`  | Local request and remote task information used to resume an existing run                                   |
-| `analysis.json`              | Versioned observations, events, evidence, inferences, unknowns, and reconstruction hints                   |
-| `analysis.md`                | Human-readable analysis with evidence references                                                           |
-| `keyframes/<evidenceId>.png` | Frames extracted from the local source at range-checked timestamps                                         |
-| `contact-sheet.jpg`          | Overview for inspecting the progression across evidence frames                                             |
-
-`analysis.json` uses `schemaVersion: playcraft.video-understanding.v1`. Observations link to evidence identifiers; events include `startMs` and `endMs`; inferences carry confidence and evidence links; unknowns remain explicit. Model text cannot create a real frame file. Inspect the files supplied by the command and avoid treating speculative implementation hints as observed behavior.
-
-| Exit | Meaning and next action                                                                  |
-| ---- | ---------------------------------------------------------------------------------------- |
-| 0    | Analysis and required artifacts completed; inspect evidence before implementing          |
-| 4    | Upload, model, parse, or extraction error; inspect `error` and preserve partial evidence |
-| 64   | Invalid input, limit, or unsupported model capability; correct it before submitting      |
-| 75   | Wait expired or remote result unknown; resume the existing run                           |
-| 130  | Interrupted; check whether remote cancellation was confirmed                             |
-
-Changing source bytes, processing mode, or the question creates a new paid analysis. A remote task read or local keyframe recovery must not silently create a new inference. Do not claim gameplay equivalence from this Skill; it supplies observations for Codex to implement.