@playcraft/cli 0.1.24 → 0.1.26

package/dist/recording/project-digest.js

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { RecordingError } from './messages.js';
+const execute = promisify(execFile);
+const excludedNames = new Set(['.git', 'node_modules', '.DS_Store']);
+const excludedRoots = new Set(['.agents', '.claude', '.codex', '.next', '.vite', '.cache', '.tmp', 'tmp', 'temp', 'dist', 'build', 'coverage', '.playcraft-preview-out', '.playcraft-temp']);
+const excludedInternalPaths = ['.playcraft/video-replication', '.playcraft/skills', '.playcraft/skill-artifacts', '.playcraft/skills.json', '.playcraft/skills.lock.json', '.playcraft/workspace-context.json'];
+const inside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const canonicalPath = async (path) => {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        if (parent === absolute)
+            throw new RecordingError('projectUnavailable', 64);
+        return resolve(await canonicalPath(parent), basename(absolute));
+    }
+};
+/** Hash source, resources, configuration and dependency manifests, including untracked inputs. */
+export async function computeProjectInputDigest(root, excludedOutputDirectories = []) {
+    try {
+        const actualRoot = await realpath(root);
+        const excluded = await Promise.all(excludedOutputDirectories.map(canonicalPath));
+        if (excluded.some(target => inside(target, actualRoot)))
+            throw new RecordingError('projectUnavailable', 64);
+        const hash = createHash('sha256');
+        let fileCount = 0;
+        let totalBytes = 0;
+        const walk = async (directory) => {
+            const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name, 'en'));
+            for (const entry of entries) {
+                if (excludedNames.has(entry.name) || directory === actualRoot && excludedRoots.has(entry.name))
+                    continue;
+                const path = resolve(directory, entry.name);
+                if (excluded.some(target => inside(target, path)))
+                    continue;
+                const rel = relative(actualRoot, path).split(sep).join('/');
+                if (excludedInternalPaths.some(target => rel === target || rel.startsWith(`${target}/`)))
+                    continue;
+                const before = await lstat(path);
+                if (before.isDirectory()) {
+                    await walk(path);
+                    continue;
+                }
+                if (before.isSymbolicLink()) {
+                    const target = await realpath(path);
+                    if (!inside(actualRoot, target) || (await lstat(target)).isDirectory())
+                        throw new RecordingError('projectUnavailable', 64);
+                }
+                else if (!before.isFile())
+                    throw new RecordingError('projectUnavailable', 64);
+                const file = await open(path, 'r');
+                try {
+                    const initial = await file.stat();
+                    totalBytes += initial.size;
+                    if (++fileCount > 50_000 || totalBytes > 1024 * 1024 * 1024)
+                        throw new RecordingError('projectUnavailable', 64);
+                    const content = createHash('sha256');
+                    for await (const bytes of file.createReadStream({ autoClose: false }))
+                        content.update(bytes);
+                    const after = await file.stat();
+                    if (initial.size !== after.size || initial.mtimeMs !== after.mtimeMs || initial.ino !== after.ino)
+                        throw new RecordingError('projectChanged', 64);
+                    hash.update(`${JSON.stringify(rel)}:${initial.mode & 0o777}:${initial.size}:${content.digest('hex')}\n`);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        };
+        await walk(actualRoot);
+        const gitCommit = await execute('git', ['-C', actualRoot, 'rev-parse', 'HEAD'], { timeout: 5000, maxBuffer: 1024, encoding: 'utf8' }).then(value => value.stdout.trim()).catch(() => null);
+        return { root: actualRoot, gitCommit: gitCommit && /^[a-f0-9]{40,64}$/.test(gitCommit) ? gitCommit : null, sha256: hash.digest('hex'), fileCount };
+    }
+    catch (error) {
+        if (error instanceof RecordingError)
+            throw error;
+        throw new RecordingError('projectUnavailable', 64);
+    }
+}

package/dist/recording/recorder.js

@@ -0,0 +1,293 @@
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { access, appendFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { setTimeout as delay } from 'node:timers/promises';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+import { canonicalReplicaJson, replicaRecordingMetadataSchema, } from '@playcraft/common/agent-tools';
+import { prepareArtifactDirectory, writeJsonAtomic } from '../video-replication/evidence.js';
+import { probeVideo } from '../video-replication/media.js';
+import { VideoCliError } from '../video-replication/messages.js';
+import { computeProjectInputDigest } from './project-digest.js';
+import { RecordingError, recordingMessage } from './messages.js';
+import { parseRecordingScenario, recordingControls, recordingPoint, recordingUrl } from './scenario.js';
+const execute = promisify(execFile);
+const require = createRequire(import.meta.url);
+const relativeFile = (root, path) => relative(root, path).split(sep).join('/');
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+const printableUrl = (value) => { try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+}
+catch {
+    return '[unavailable]';
+} };
+export async function hashRecordingFile(path) {
+    const hash = createHash('sha256');
+    for await (const bytes of createReadStream(path))
+        hash.update(bytes);
+    return hash.digest('hex');
+}
+async function mediaCommand(tool, args, signal) {
+    const executable = process.env[tool === 'ffmpeg' ? 'FFMPEG_PATH' : 'FFPROBE_PATH'] || tool;
+    if (executable !== tool && !isAbsolute(executable))
+        throw new RecordingError('invalidArguments', 64);
+    try {
+        return (await execute(executable, args, { timeout: 60_000, maxBuffer: 1024 * 1024, encoding: 'utf8', signal })).stdout;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw new RecordingError('recordingFailed');
+    }
+}
+export async function waitUntil(origin, atMs, signal) {
+    // Timers can wake before a fractional deadline. Never dispatch input or finish a capture early.
+    for (;;) {
+        signal.throwIfAborted();
+        const remaining = origin + atMs - performance.now();
+        if (remaining <= 0)
+            return;
+        await delay(Math.ceil(remaining), undefined, { signal });
+    }
+}
+async function dispatchStep(page, session, scenario, step, origin, signal, emit) {
+    const point = recordingPoint(scenario, step.type === 'tap' ? step : step.path[0]);
+    if (step.type === 'tap') {
+        if (scenario.pointer === 'touch')
+            await page.touchscreen.tap(point.x, point.y);
+        else
+            await page.mouse.click(point.x, point.y);
+        emit(point, 'tap', step.atMs);
+        return;
+    }
+    if (scenario.pointer === 'touch')
+        await session.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [{ ...point, id: 1 }] });
+    else {
+        await page.mouse.move(point.x, point.y);
+        await page.mouse.down();
+    }
+    emit(point, 'start', step.atMs);
+    let completed = false;
+    try {
+        for (const next of step.path.slice(1)) {
+            await waitUntil(origin, step.atMs + next.offsetMs, signal);
+            const actual = recordingPoint(scenario, next);
+            if (scenario.pointer === 'touch')
+                await session.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: [{ ...actual, id: 1 }] });
+            else
+                await page.mouse.move(actual.x, actual.y);
+            emit(actual, 'move', step.atMs + next.offsetMs);
+        }
+        completed = true;
+    }
+    finally {
+        const release = scenario.pointer === 'touch' ? session.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] }) : page.mouse.up();
+        if (completed) {
+            await release;
+            emit(recordingPoint(scenario, step.path.at(-1)), 'end', step.atMs + step.path.at(-1).offsetMs);
+        }
+        else
+            await release.catch(() => { });
+    }
+}
+async function recordOne(browser, root, url, scenario, variant, signal) {
+    const directory = variant.kind === 'candidate' ? root : join(root, 'controls', variant.id);
+    await mkdir(join(directory, 'screenshots'), { recursive: true });
+    const eventPath = join(directory, 'events.jsonl');
+    const consolePath = join(directory, 'console.jsonl');
+    await writeFile(eventPath, '', { flag: 'wx', mode: 0o600 });
+    await writeFile(consolePath, '', { flag: 'wx', mode: 0o600 });
+    const context = await browser.newContext({
+        viewport: { width: scenario.viewport.width, height: scenario.viewport.height }, deviceScaleFactor: scenario.viewport.deviceScaleFactor,
+        hasTouch: scenario.pointer === 'touch', isMobile: scenario.pointer === 'touch', serviceWorkers: 'block',
+        acceptDownloads: false, recordVideo: { dir: join(directory, 'capture'), size: { width: scenario.viewport.width, height: scenario.viewport.height } },
+    });
+    let logs = Promise.resolve();
+    let logBytes = 0;
+    let failed;
+    const runtime = { pageErrors: 0, consoleErrors: 0, failedRequests: 0 };
+    let origin = performance.now();
+    let inputOriginMs = Date.now();
+    const log = (path, value) => {
+        const line = `${JSON.stringify(value)}\n`;
+        logBytes += Buffer.byteLength(line);
+        if (logBytes > 16 * 1024 * 1024) {
+            failed = new RecordingError('recordingFailed');
+            return;
+        }
+        logs = logs.then(() => appendFile(path, line));
+    };
+    const closeOnAbort = () => { void context.close().catch(() => { }); };
+    signal.addEventListener('abort', closeOnAbort, { once: true });
+    let closed = false;
+    try {
+        signal.throwIfAborted();
+        const page = await context.newPage();
+        const video = page.video();
+        if (!video)
+            throw new RecordingError('browserUnavailable');
+        page.on('console', message => {
+            if (message.type() === 'error')
+                runtime.consoleErrors++;
+            log(consolePath, { atMs: performance.now() - origin, kind: 'console', level: message.type(), text: message.text().slice(0, 32768) });
+        });
+        page.on('pageerror', error => { runtime.pageErrors++; log(consolePath, { atMs: performance.now() - origin, kind: 'pageerror', level: 'error', text: error.message.slice(0, 32768) }); });
+        page.on('requestfailed', request => { runtime.failedRequests++; log(consolePath, { atMs: performance.now() - origin, kind: 'requestfailed', level: 'error', url: printableUrl(request.url()), text: request.failure()?.errorText }); });
+        context.on('page', popup => { if (popup !== page) {
+            runtime.pageErrors++;
+            log(consolePath, { atMs: performance.now() - origin, kind: 'popup', level: 'error', text: 'recording.popupUnsupported' });
+            void popup.close().catch(() => { });
+        } });
+        await context.route('**/*', async (route) => {
+            if (route.request().isNavigationRequest() && new URL(route.request().url()).origin !== url.origin) {
+                failed = new RecordingError('navigationFailed');
+                await route.abort();
+            }
+            else
+                await route.continue();
+        });
+        page.on('dialog', dialog => { runtime.pageErrors++; log(consolePath, { atMs: performance.now() - origin, kind: 'dialog', level: 'error', text: dialog.message().slice(0, 32768) }); void dialog.dismiss(); });
+        const response = await page.goto(url.href, { waitUntil: 'load', timeout: 30_000 });
+        if (!response?.ok() || new URL(page.url()).origin !== url.origin || page.isClosed())
+            throw new RecordingError('navigationFailed');
+        const initial = join(directory, 'screenshots', 'initial.png');
+        await page.screenshot({ path: initial, timeout: 10_000 });
+        origin = performance.now();
+        inputOriginMs = Date.now();
+        const screenshots = [{ path: relativeFile(root, initial), sha256: await hashRecordingFile(initial), atMs: 0 }];
+        const session = await context.newCDPSession(page);
+        log(eventPath, { kind: 'recording-start', plannedAtMs: 0, actualAtMs: 0, inputOriginMs, navigationUrl: printableUrl(url.href), finalUrl: printableUrl(page.url()), device: scenario.pointer, reset: scenario.reset, seedApplied: false });
+        for (const step of scenario.steps) {
+            await waitUntil(origin, step.atMs, signal);
+            if (failed)
+                throw failed;
+            const omitted = variant.omittedStepIds.includes(step.id);
+            const points = (step.type === 'tap' ? [{ offsetMs: 0, x: step.x, y: step.y }] : step.path).map(point => ({ ...point, actual: recordingPoint(scenario, point) }));
+            if (omitted) {
+                log(eventPath, { stepId: step.id, kind: step.type, plannedAtMs: step.atMs, actualAtMs: performance.now() - origin, device: scenario.pointer, points, status: 'omitted' });
+                continue;
+            }
+            const before = join(directory, 'screenshots', `${step.id}-before.png`);
+            await page.screenshot({ path: before, timeout: 10_000 });
+            screenshots.push({ path: relativeFile(root, before), sha256: await hashRecordingFile(before), atMs: Math.round(performance.now() - origin) });
+            const started = performance.now() - origin;
+            log(eventPath, { stepId: step.id, kind: step.type, plannedAtMs: step.atMs, actualAtMs: started, device: scenario.pointer, points, status: 'started' });
+            try {
+                await dispatchStep(page, session, scenario, step, origin, signal, (point, phase, plannedAtMs) => log(eventPath, { stepId: step.id, kind: 'pointer', phase, plannedAtMs, actualAtMs: performance.now() - origin, device: scenario.pointer, actual: point, status: 'dispatched' }));
+                log(eventPath, { stepId: step.id, kind: step.type, plannedAtMs: step.atMs, actualAtMs: started, completedAtMs: performance.now() - origin, device: scenario.pointer, points, status: 'dispatched' });
+            }
+            catch (error) {
+                log(eventPath, { stepId: step.id, kind: step.type, plannedAtMs: step.atMs, actualAtMs: started, device: scenario.pointer, points, status: 'failed' });
+                throw error;
+            }
+            const after = join(directory, 'screenshots', `${step.id}-after.png`);
+            await page.screenshot({ path: after, timeout: 10_000 });
+            screenshots.push({ path: relativeFile(root, after), sha256: await hashRecordingFile(after), atMs: Math.round(performance.now() - origin) });
+        }
+        await waitUntil(origin, scenario.durationMs, signal);
+        if (failed)
+            throw failed;
+        log(eventPath, { kind: 'recording-end', plannedAtMs: scenario.durationMs, actualAtMs: performance.now() - origin, status: 'completed' });
+        const closingAt = Date.now();
+        await context.close();
+        closed = true;
+        const closedAt = Date.now();
+        await logs;
+        const raw = join(directory, 'raw-capture.webm');
+        await rename(await video.path(), raw);
+        const rawProbe = JSON.parse(await mediaCommand('ffprobe', ['-v', 'error', '-show_entries', 'format=duration:stream=avg_frame_rate,codec_type', '-of', 'json', raw], signal));
+        const rawDuration = Number(rawProbe.format.duration) * 1000;
+        const stream = rawProbe.streams.find(value => value.codec_type === 'video');
+        const rate = stream?.avg_frame_rate.split('/').map(Number);
+        const fps = rate && rate[0] > 0 && rate[1] > 0 ? rate[0] / rate[1] : 0;
+        if (!Number.isFinite(rawDuration) || rawDuration <= 0 || !fps)
+            throw new RecordingError('recordingFailed');
+        // The encoder's final frame falls inside the measured context-close interval.
+        const rawOriginMs = closingAt - rawDuration;
+        const offsetMs = Math.max(0, inputOriginMs - rawOriginMs);
+        const candidate = join(directory, 'candidate.mp4');
+        await mediaCommand('ffmpeg', ['-v', 'error', '-nostdin', '-i', raw, '-ss', (offsetMs / 1000).toFixed(6), '-t', (scenario.durationMs / 1000).toFixed(6), '-an', '-c:v', 'libx264', '-preset', 'ultrafast', '-crf', '20', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', candidate], signal);
+        const probed = await probeVideo(candidate, signal);
+        const uncertaintyMs = closedAt - closingAt + 1000 / fps + Math.max(0, rawOriginMs - inputOriginMs);
+        if (probed.source.width !== scenario.viewport.width || probed.source.height !== scenario.viewport.height || probed.source.durationMs < scenario.durationMs - uncertaintyMs - 1000 / fps)
+            throw new RecordingError('recordingFailed');
+        return {
+            ...variant, video: { path: relativeFile(root, candidate), source: probed.source, fps },
+            events: { path: relativeFile(root, eventPath), sha256: await hashRecordingFile(eventPath) }, console: { path: relativeFile(root, consolePath), sha256: await hashRecordingFile(consolePath) },
+            timing: { inputOriginMs, videoOriginMs: inputOriginMs, uncertaintyMs }, runtime, screenshots,
+        };
+    }
+    finally {
+        signal.removeEventListener('abort', closeOnAbort);
+        if (!closed)
+            await context.close().catch(() => { });
+        await logs;
+    }
+}
+export async function recordPlayable(options, signal) {
+    const runId = randomUUID();
+    let out;
+    let browser;
+    let prepared = false;
+    try {
+        const url = recordingUrl(options.url);
+        if (!options.scenario || options.browserPath && !isAbsolute(options.browserPath))
+            throw new RecordingError('invalidArguments', 64);
+        const scenarioStat = await stat(options.scenario).catch(() => { throw new RecordingError('invalidArguments', 64); });
+        if (!scenarioStat.isFile() || scenarioStat.size > 1024 * 1024)
+            throw new RecordingError('invalidArguments', 64);
+        let scenario;
+        try {
+            scenario = parseRecordingScenario(JSON.parse(await readFile(options.scenario, 'utf8')));
+        }
+        catch {
+            throw new RecordingError('invalidArguments', 64);
+        }
+        const scenarioSha256 = sha(canonicalReplicaJson(scenario));
+        const configuredPath = options.browserPath || process.env.PLAYCRAFT_CHROMIUM_PATH || '/usr/bin/chromium';
+        if (!isAbsolute(configuredPath))
+            throw new RecordingError('invalidArguments', 64);
+        await access(configuredPath).catch(() => { throw new RecordingError('browserUnavailable'); });
+        out = resolve(options.out || join('.playcraft', 'video-replication', runId, 'recording'));
+        const project = await computeProjectInputDigest(process.cwd(), [out]);
+        await prepareArtifactDirectory(out, runId, false);
+        prepared = true;
+        await writeJsonAtomic(join(out, 'metadata.json'), { schemaVersion: 'playcraft.replica-recording.v1', runId, state: 'recording', scenarioSha256 });
+        const ffmpeg = (await mediaCommand('ffmpeg', ['-version'], signal)).split('\n')[0];
+        if (!process.env.PLAYWRIGHT_BROWSERS_PATH && await access('/opt/playcraft/playwright').then(() => true, () => false))
+            process.env.PLAYWRIGHT_BROWSERS_PATH = '/opt/playcraft/playwright';
+        const { chromium } = await import('playwright-core');
+        browser = await chromium.launch({ executablePath: configuredPath, headless: true, args: ['--mute-audio', '--disable-dev-shm-usage', '--enable-unsafe-swiftshader', '--use-gl=angle', '--use-angle=swiftshader', ...(process.getuid?.() === 0 ? ['--no-sandbox'] : [])] }).catch(() => { throw new RecordingError('browserUnavailable'); });
+        process.stderr.write(`[record] ${recordingMessage('recording')}\n`);
+        const candidate = await recordOne(browser, out, url, scenario, { id: 'candidate', kind: 'candidate', omittedStepIds: [] }, signal);
+        const controls = [];
+        for (const control of recordingControls(scenario))
+            controls.push(await recordOne(browser, out, url, scenario, control, signal));
+        const current = await computeProjectInputDigest(process.cwd(), [out]);
+        if (current.sha256 !== project.sha256)
+            throw new RecordingError('projectChanged', 64);
+        const metadata = replicaRecordingMetadataSchema.parse({
+            schemaVersion: 'playcraft.replica-recording.v1', runId, state: 'completed', scenario, scenarioSha256, project,
+            toolVersions: { cli: require('../../package.json').version, playwright: require('playwright-core/package.json').version, browser: browser.version(), ffmpeg },
+            conditions: { audio: 'muted', seedSupport: scenario.seed ? 'best-effort' : 'not-requested', serverStateReset: 'not-guaranteed' },
+            candidate, controls,
+        });
+        await writeJsonAtomic(join(out, 'metadata.json'), metadata);
+        return { exitCode: 0, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'playable record', runId, state: 'completed', ok: true,
+                artifacts: { metadata: join(out, 'metadata.json'), candidate: join(out, candidate.video.path), controls: controls.map(control => join(out, control.video.path)) }, result: metadata } };
+    }
+    catch (error) {
+        const code = error instanceof RecordingError ? error.code : error instanceof VideoCliError && error.code === 'outputConflict' ? 'outputConflict' : signal.aborted ? signal.reason?.name === 'TimeoutError' ? 'timedOut' : 'interrupted' : 'recordingFailed';
+        const exitCode = error instanceof RecordingError || error instanceof VideoCliError ? error.exitCode : signal.aborted ? code === 'timedOut' ? 75 : 130 : 4;
+        if (out && prepared)
+            await writeJsonAtomic(join(out, 'metadata.json'), { schemaVersion: 'playcraft.replica-recording.v1', runId, state: 'failed', error: { code } }).catch(() => { });
+        return { exitCode, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'playable record', runId, state: 'failed', ok: false, ...(out && prepared ? { artifacts: { metadata: join(out, 'metadata.json') } } : {}), error: { code, message: recordingMessage(code) } } };
+    }
+    finally {
+        await browser?.close().catch(() => { });
+    }
+}

package/dist/recording/scenario.js

@@ -0,0 +1,50 @@
+import { replicaScenarioSchema } from '@playcraft/common/agent-tools';
+import { RecordingError } from './messages.js';
+export function recordingUrl(value) {
+    try {
+        if (!value)
+            throw new Error();
+        const url = new URL(value);
+        if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname) || url.username || url.password || url.hash)
+            throw new Error();
+        return url;
+    }
+    catch {
+        throw new RecordingError('invalidUrl', 64);
+    }
+}
+export function parseRecordingScenario(value) {
+    const parsed = replicaScenarioSchema.safeParse(value);
+    if (!parsed.success)
+        throw new RecordingError('invalidArguments', 64);
+    const scenario = parsed.data;
+    if (scenario.draft || scenario.viewport.width % 2 || scenario.viewport.height % 2 || scenario.steps.length > 63 || scenario.steps.some(step => step.id.length > 110))
+        throw new RecordingError('invalidArguments', 64);
+    const ids = new Set();
+    let previousEnd = -1;
+    for (const step of scenario.steps) {
+        if (ids.has(step.id) || step.atMs < previousEnd)
+            throw new RecordingError('invalidArguments', 64);
+        ids.add(step.id);
+        const end = step.atMs + (step.type === 'drag' ? step.path.at(-1).offsetMs : 0);
+        if (end >= scenario.durationMs)
+            throw new RecordingError('invalidArguments', 64);
+        if (step.type === 'drag' && (step.path[0].offsetMs !== 0 || step.path.some((point, index) => index > 0 && point.offsetMs <= step.path[index - 1].offsetMs)))
+            throw new RecordingError('invalidArguments', 64);
+        previousEnd = end;
+    }
+    const required = new Set(scenario.requiredEffects.map(effect => effect.stepId));
+    if ([...required].some(id => !ids.has(id)) || (scenario.controls.noInput ? 1 : 0) + (scenario.controls.omitRequiredSteps ? required.size : 0) > 4)
+        throw new RecordingError('invalidArguments', 64);
+    return scenario;
+}
+export function recordingControls(scenario) {
+    return [
+        ...(scenario.controls.noInput ? [{ id: 'control-no-input', kind: 'no-input', omittedStepIds: scenario.steps.map(step => step.id) }] : []),
+        ...(scenario.controls.omitRequiredSteps ? [...new Set(scenario.requiredEffects.map(effect => effect.stepId))].map(id => ({ id: `control-omit-${id}`, kind: 'omit-step', omittedStepIds: [id] })) : []),
+    ];
+}
+export function recordingPoint(scenario, point) {
+    const rect = scenario.contentRect;
+    return { x: (rect.x + point.x * rect.width) * scenario.viewport.width, y: (rect.y + point.y * rect.height) * scenario.viewport.height };
+}

package/dist/remix/clone.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
@@ -151,6 +152,7 @@ export async function remixClone(options) {
     };
     writePlaycraftMeta(targetDir, meta);
     configureRepoCredentialHelper(targetDir);
+    await prepareLocalSkillLifecycle(targetDir, 'checkout');
     let projectType;
     try {
         const project = await client.get(`/projects/${encodeURIComponent(projectId)}`);

package/dist/remix/init-template.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import * as path from 'node:path';
 import { applyEnginePackToProject, bakeFullTemplate, KNOWN_ADAPTERS, readAdapterFromAtomTree, readEngineMarker, resolveCliPackageRoot, } from '../scaffold/compose.js';
 import { autoLinkSkillsFromAtomTree } from '../commands/skills.js';
@@ -68,6 +69,7 @@ export async function initTemplateCommand(opts) {
             console.log(`  ⚠ auto-link skipped: ${err.message}`);
         }
     }
+    await prepareLocalSkillLifecycle(projectDir, 'create');
     console.log('\n下一步：');
     console.log('  npm install');
     console.log('  阅读 .claude/skills/<atom>/SKILL.md（已自动 link）并填 logs/developer-log.md § Skill Preflight');

package/dist/remix/pull.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -44,6 +45,7 @@ export async function remixPull(options = {}) {
         const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
         throw new Error(detail || `git pull 失败（exit ${result.status}）`);
     }
+    await prepareLocalSkillLifecycle(repoDir, 'checkout');
     if (options.json) {
         console.log(JSON.stringify({
             schemaVersion: '1.0',

package/dist/remix/push.js

@@ -1,3 +1,6 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
+import { reconcileLocalProjectSkills } from '../project-skills/reconcile.js';
+import { projectSkillsMessage as skillMessage } from '../project-skills/messages.js';
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -41,6 +44,7 @@ export async function remixPush(options = {}) {
         process.stderr.write(`[push] ${meta.cloneUrl}\n`);
         process.stderr.write(`[push] branch=${meta.branch} dir=${repoDir}\n`);
     }
+    const skills = await prepareLocalSkillLifecycle(repoDir, 'push');
     const result = runAuthenticatedGit(['push', ...effectiveArgs], {
         cwd: repoDir,
         token: client.token,
@@ -50,10 +54,24 @@ export async function remixPush(options = {}) {
         const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
         throw new Error(detail || `git push 失败（exit ${result.status}）`);
     }
+    let skillIndex;
+    let skillIndexFailed = false;
+    if (skills.managed) {
+        try {
+            skillIndex = await reconcileLocalProjectSkills(repoDir, { url: options.url, token: options.token });
+        }
+        catch (error) {
+            skillIndexFailed = true;
+            skillIndex = { indexed: false, message: skillMessage('pushIndexFailed'), detail: error instanceof Error ? error.message : String(error) };
+            process.exitCode = 1;
+        }
+        if (!options.json)
+            process.stderr.write(`${JSON.stringify(skillIndex)}\n`);
+    }
     if (options.json) {
         console.log(JSON.stringify({
             schemaVersion: '1.0',
-            ok: true,
+            ok: !skillIndexFailed,
             command: 'remix.push',
             requestId: client.requestId,
             data: {
@@ -62,6 +80,8 @@ export async function remixPush(options = {}) {
                 cloneUrl: meta.cloneUrl,
                 dir: repoDir,
                 gitArgs: effectiveArgs,
+                gitPushed: true,
+                skills: skillIndex,
             },
         }));
         return;