@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace-runtime/persistence/stopped-execution.js

@@ -0,0 +1,77 @@
+import { operationRecordSchema, transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+const STOP_BUCKET = 'stopped_execution_epochs';
+const ACTIVE_OPERATIONS = new Set(['queued', 'dispatched', 'accepted', 'uncertain']);
+/** Called only inside the journal writer transaction after authoritative process-stop evidence. */
+export function settleStoppedExecution(database, scope, pid, occurredAt, writer) {
+    const key = JSON.stringify([scope.runtimeId, scope.generation, scope.runtimeEpoch]);
+    if (!readRecord(database, STOP_BUCKET, key))
+        writeRecord(database, STOP_BUCKET, key, { ...scope, pid, occurredAt });
+    const events = [];
+    const stoppedSessions = new Set();
+    const rows = database.prepare(`SELECT scope_key, operation_json FROM operation_intents
+    WHERE json_extract(operation_json, '$.generation') = ? AND json_extract(operation_json, '$.runtimeEpoch') = ?
+      AND json_extract(operation_json, '$.kind') IN ('session.turn', 'session.review', 'session.compact')`)
+        .all(scope.generation, scope.runtimeEpoch);
+    for (const row of rows) {
+        const operation = operationRecordSchema.parse(JSON.parse(row.operation_json));
+        const binding = readRecord(database, 'operation_execution_scopes', JSON.stringify([row.scope_key, operation.operationId]));
+        const source = database.prepare('SELECT 1 FROM source_events WHERE runtime_id = ? AND generation = ? AND runtime_epoch = ? AND operation_id = ? LIMIT 1')
+            .get(scope.runtimeId, scope.generation, scope.runtimeEpoch, operation.operationId);
+        if ((!binding || binding.runtimeId !== scope.runtimeId || binding.generation !== scope.generation || binding.runtimeEpoch !== scope.runtimeEpoch) && !source)
+            continue;
+        if (operation.sessionId)
+            stoppedSessions.add(operation.sessionId);
+        const session = operation.sessionId ? readRecord(database, 'sessions', operation.sessionId) : undefined;
+        const appendTerminal = (threadId, turnId, subAgent) => {
+            const existing = database.prepare(`SELECT 1 FROM source_events WHERE runtime_id = ? AND generation = ? AND runtime_epoch = ?
+        AND thread_id = ? AND turn_id = ? AND type IN ('turn/completed', 'turn.completed', 'turn.interrupted', 'turn.failed') LIMIT 1`)
+                .get(scope.runtimeId, scope.generation, scope.runtimeEpoch, threadId, turnId);
+            if (existing)
+                return;
+            const payload = { sessionId: operation.sessionId, workspaceId: operation.workspaceId,
+                threadId, turnId, turn: { id: turnId, status: 'interrupted' }, reason: 'execution_group_stopped', subAgent };
+            events.push(...writer.allocate({ ...scope, type: 'turn.interrupted', payload, occurredAt,
+                sessionId: operation.sessionId, workspaceId: operation.workspaceId, operationId: operation.operationId, threadId, turnId }).committedEvents);
+        };
+        const children = database.prepare(`SELECT record_key, body_json FROM records WHERE bucket = 'native_subagent_turns'
+      AND json_extract(body_json, '$.operationScopeKey') = ?`).all(row.scope_key);
+        for (const child of children) {
+            const [threadId, turnId] = JSON.parse(child.record_key);
+            const link = readRecord(database, 'native_subagent_threads', threadId);
+            if (!link || link.sessionId !== operation.sessionId || link.workspaceId !== operation.workspaceId || link.rootThreadId !== operation.nativeThreadId)
+                continue;
+            const { sessionId: _, workspaceId: __, operationScopeKey: ___, operationConfirmed: ____, ...subAgent } = link;
+            appendTerminal(threadId, turnId, subAgent);
+        }
+        if (!ACTIVE_OPERATIONS.has(operation.status))
+            continue;
+        if (operation.nativeThreadId && operation.nativeTurnId)
+            appendTerminal(operation.nativeThreadId, operation.nativeTurnId);
+        writer.putOperation(row.scope_key, { ...transitionOperation(operation, 'interrupted', { error: 'execution_group_stopped' }), updatedAt: occurredAt });
+        if (session && session.threadId === operation.nativeThreadId &&
+            (session.activeTurnId === operation.nativeTurnId || (!session.activeTurnId && !operation.nativeTurnId && session.turnStatus === 'starting'))) {
+            writeRecord(database, 'sessions', operation.sessionId, { ...session, turnStatus: 'interrupted', turnBlock: undefined,
+                activeTurnId: undefined, recoverability: 'history_only' });
+        }
+    }
+    for (const row of database.prepare("SELECT record_key, body_json FROM records WHERE bucket = 'approvals'").all()) {
+        const approval = JSON.parse(row.body_json);
+        if (approval.status === 'pending' && approval.runtimeId === scope.runtimeId && approval.generation === scope.generation &&
+            approval.runtimeEpoch === scope.runtimeEpoch && stoppedSessions.has(String(approval.sessionId)))
+            writeRecord(database, 'approvals', row.record_key, { ...approval, status: 'expired' });
+    }
+    return events;
+}
+export function stoppedExecutionEpochs(database, runtimeId, generation) {
+    const rows = database.prepare(`SELECT body_json FROM records WHERE bucket = ?
+    AND json_extract(body_json, '$.runtimeId') = ? AND json_extract(body_json, '$.generation') = ?`).all(STOP_BUCKET, runtimeId, generation);
+    return rows.map(row => Number(JSON.parse(row.body_json).runtimeEpoch)).sort((a, b) => a - b);
+}
+function readRecord(database, bucket, key) {
+    const row = database.prepare('SELECT body_json FROM records WHERE bucket = ? AND record_key = ?').get(bucket, key);
+    return row ? JSON.parse(row.body_json) : undefined;
+}
+function writeRecord(database, bucket, key, value) {
+    database.prepare('INSERT INTO records (bucket, record_key, body_json) VALUES (?, ?, ?) ON CONFLICT(bucket, record_key) DO UPDATE SET body_json = excluded.body_json')
+        .run(bucket, key, JSON.stringify(value));
+}

package/dist/workspace-runtime/previews/diagnostics.js

@@ -0,0 +1,44 @@
+export const PREVIEW_DIAGNOSTICS_MARKER = 'data-playcraft-diagnostics';
+/**
+ * Runs only inside a published preview. It reports browser-visible failures and a small
+ * performance sample to the workspace; delivery builds never include this script.
+ */
+export const PREVIEW_DIAGNOSTICS_SCRIPT = `(function(){
+ if(window.__playcraftDiagnosticsV1)return;
+ window.__playcraftDiagnosticsV1=true;
+ var pageId=Math.random().toString(36).slice(2)+Date.now().toString(36);
+ var seq=0,buffer=[],seen={},stopped=false,start=Date.now();
+ function clean(value){try{return String(value).slice(0,2000)}catch(e){return ''}}
+ function emit(type,data){if(stopped||buffer.length>=100)return;var key=type+':'+(data.message||data.url||'');if(seen[key])return;seen[key]=1;buffer.push(Object.assign({type:type,at:Date.now()-start},data));}
+ function flush(){if(!buffer.length)return;var batch=buffer.splice(0,10);seq++;try{window.parent.postMessage({__playcraft:'diagnostics',v:1,pageId:pageId,seq:seq,events:batch},'*')}catch(e){}}
+ var timer=setInterval(flush,500);
+ window.addEventListener('error',function(event){
+   var target=event.target;
+   if(target&&target!==window&&target.tagName){emit('resource',{tag:String(target.tagName).toLowerCase(),url:clean(target.currentSrc||target.src||target.href||'')});return;}
+   emit('error',{message:clean(event.message),source:clean(event.filename),line:event.lineno,col:event.colno});
+ },true);
+ window.addEventListener('unhandledrejection',function(event){var reason=event.reason;emit('unhandledrejection',{message:clean(reason&&reason.message?reason.message:reason)});});
+ window.addEventListener('securitypolicyviolation',function(event){emit('securitypolicyviolation',{message:clean(event.violatedDirective),source:clean(event.blockedURI)});});
+ window.addEventListener('webglcontextlost',function(){emit('webgl-context-lost',{message:'webgl context lost'});},true);
+ function navigation(){
+   try{var entry=performance.getEntriesByType('navigation')[0];if(entry)emit('navigation',{duration:Math.round(entry.duration),domContentLoaded:Math.round(entry.domContentLoadedEventEnd),load:Math.round(entry.loadEventEnd)});}catch(e){}
+   try{var paint=performance.getEntriesByType('paint');for(var i=0;i<paint.length;i++){if(paint[i].name==='first-contentful-paint')emit('paint',{message:'first-contentful-paint',duration:Math.round(paint[i].startTime)});}}catch(e){}
+ }
+ if(document.readyState==='complete')navigation();else window.addEventListener('load',navigation,{once:true});
+ try{var observer=new PerformanceObserver(function(list){var entries=list.getEntries();for(var i=0;i<entries.length;i++){if(entries[i].name==='first-contentful-paint')emit('paint',{message:'first-contentful-paint',duration:Math.round(entries[i].startTime)});}});observer.observe({type:'paint',buffered:true});}catch(e){}
+ var frames=0,fpsStart=performance.now();
+ function sample(){frames++;var now=performance.now();if(now-fpsStart<5000){requestAnimationFrame(sample);}else{emit('fps',{fps:Math.round(frames/((now-fpsStart)/1000))});}}
+ requestAnimationFrame(sample);
+ window.setTimeout(function(){flush();stopped=true;clearInterval(timer);},60000);
+})();`;
+/** Injects only at preview publish time, after the builder has produced a single HTML file. */
+export function injectPreviewDiagnostics(bytes) {
+    const html = bytes.toString('utf8');
+    if (html.includes(PREVIEW_DIAGNOSTICS_MARKER))
+        return bytes;
+    const script = `<script ${PREVIEW_DIAGNOSTICS_MARKER}>${PREVIEW_DIAGNOSTICS_SCRIPT}</script>`;
+    const head = /<head[^>]*>/i.exec(html);
+    const body = /<\/body\s*>/i.exec(html);
+    const at = head ? head.index + head[0].length : body ? body.index : html.length;
+    return Buffer.from(html.slice(0, at) + script + html.slice(at), 'utf8');
+}

package/dist/workspace-runtime/previews/finalize.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH, readWorkspaceRuntimeProfile, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from '../workspaces/artifact-files.js';
+import { captureGeneratedArtifact } from '../workspaces/artifact-receipts.js';
+import { injectPreviewDiagnostics } from './diagnostics.js';
+import { saveWorkspacePlayableOutput } from './output.js';
+import { findExternalLocalReferences } from './single-file.js';
+export function validateWorkspacePlayable(bytes) {
+    const html = bytes.toString('utf8');
+    if (!bytes.length || bytes.length > PREVIEW_HTML_MAX_BYTES || !/<(?:!doctype\s+html|html|head|title|body|script|canvas)\b/i.test(html)
+        || findExternalLocalReferences(html).length || readWorkspaceRuntimeProfile(html)) {
+        throw new Error('preview_not_single_file');
+    }
+}
+/** Reads one stable regular file, never a redirected path or a partially copied output. */
+export async function readWorkspacePlayable(root) {
+    const file = await open(await artifactPath(root, WORKSPACE_PLAYABLE_OUTPUT_PATH), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > PREVIEW_HTML_MAX_BYTES)
+            throw new Error('preview_not_single_file');
+        const bytes = await file.readFile();
+        const after = await file.stat();
+        if (before.size !== bytes.length || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new Error('artifact_file_changed');
+        return { bytes, signature: JSON.stringify([before.dev, before.ino, before.size, before.mtimeMs, before.ctimeMs]) };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function workspacePlayableSignature(root) {
+    try {
+        const file = await open(await artifactPath(root, WORKSPACE_PLAYABLE_OUTPUT_PATH), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.nlink !== 1)
+                throw new Error('preview_not_single_file');
+            return JSON.stringify([stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs]);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** All build entry points retain the same validated bytes and an immutable generation receipt. */
+export async function finalizeWorkspacePlayable(root, built, tool, options = {}) {
+    validateWorkspacePlayable(built);
+    const bytes = injectPreviewDiagnostics(built);
+    validateWorkspacePlayable(bytes);
+    if ('expectedSignature' in options && await workspacePlayableSignature(root) !== options.expectedSignature)
+        throw new Error('preview_source_changed');
+    const current = await readWorkspacePlayable(root).catch(() => undefined);
+    if (!current?.bytes.equals(bytes))
+        await saveWorkspacePlayableOutput(root, bytes);
+    await captureGeneratedArtifact(WORKSPACE_PLAYABLE_OUTPUT_PATH, tool, {}, root, createHash('sha256').update(bytes).digest('hex'), options.source);
+}

package/dist/workspace-runtime/previews/output.js

@@ -0,0 +1,36 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
+/** Persist only validated, self-contained build bytes; unrelated delivery files are preserved. */
+export async function saveWorkspacePlayableOutput(root, bytes) {
+    const workspace = await realpath(root);
+    let directory = workspace;
+    for (const segment of dirname(WORKSPACE_PLAYABLE_OUTPUT_PATH).split('/')) {
+        directory = join(directory, segment);
+        const created = await mkdir(directory, { mode: 0o2775 }).then(() => true, error => {
+            if (error.code !== 'EEXIST')
+                throw error;
+            return false;
+        });
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || relative(workspace, await realpath(directory)) !== relative(workspace, directory))
+            throw new Error('preview_build_failed');
+        if (created)
+            await chmod(directory, 0o2775);
+    }
+    const target = join(workspace, WORKSPACE_PLAYABLE_OUTPUT_PATH);
+    const temporary = join(directory, `.playable-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o664 });
+        await chmod(temporary, 0o664);
+        const stat = await lstat(target).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1))
+            throw new Error('preview_build_failed');
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/workspace-runtime/previews/publish.js

@@ -0,0 +1,306 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PREVIEW_HTML_MAX_BYTES, PREVIEW_LOG_TAIL_MAX, WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, previewPublishResultSchema, previewReservationSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { excludeFromGit, readDependencies, scheduleDependencyInstall, } from '../workspaces/dependencies.js';
+import { runDeveloperCommand } from '../workspaces/developer-command.js';
+import { revisionScope, workspaceRoot } from '../workspaces/registry.js';
+import { classifyPreviewOutput, findExternalLocalReferences } from './single-file.js';
+import { finalizeWorkspacePlayable, workspacePlayableSignature } from './finalize.js';
+import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
+import { isolateWorkspaceForBuild } from '../workspaces/delivery-build.js';
+import { openScratchToDevelopment } from '../workspaces/directory-access.js';
+import { injectPreviewDiagnostics } from './diagnostics.js';
+import { OperationLogStore } from '../workspaces/operation-log.js';
+import { prepareRuntimePreview, RuntimePreviewBuildError } from './runtime-preview.js';
+const BUILD_TIMEOUT_MS = 10 * 60_000;
+/** Build output and the builder's own scratch folder live in the checkout, hidden from Git. */
+const OUTPUT_FOLDER = '.playcraft-preview-out';
+const BUILDER_TEMP_FOLDER = '.playcraft-temp';
+/**
+ * The generic single-file build. `--mode full` keeps the builder from asking which stages to run.
+ * Group-writable output lets the control user, a member of the development group, remove it.
+ */
+const BUILD_COMMAND = 'umask 002 && PLAYCRAFT_BUILD_ISOLATED=1 playcraft build --mode full --platform playcraft --format html';
+class PreviewFailure extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const running = new WeakMap();
+/**
+ * Checks what can be checked before the operation is accepted. The build itself runs later in
+ * `runPreviewPublish`; the dispatch request returns as soon as the operation is accepted.
+ */
+export async function previewWorkspaceRoot(state, operation) {
+    if (!operation.workspaceId || !/^[A-Za-z0-9_-]+$/.test(operation.operationId)) {
+        throw new PreviewFailure('invalid_preview_publish');
+    }
+    if (operation.sessionId !== undefined) {
+        const session = state.journal.getSession(operation.sessionId);
+        if (!session || (state.config.workspaceMode === 'multi' && (session.workspaceId !== operation.workspaceId || (session.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic')))) {
+            throw new PreviewFailure('session_workspace_mismatch');
+        }
+    }
+    return workspaceRoot(state, operation.workspaceId, operation.directoryName);
+}
+/** Tracks a background publish so tests and shutdown can wait for it. */
+export function trackPreviewPublish(state, task) {
+    const tasks = running.get(state) ?? new Set();
+    running.set(state, tasks);
+    const tracked = task.finally(() => tasks.delete(tracked));
+    tasks.add(tracked);
+}
+export async function settlePreviewPublishes(state) {
+    await Promise.all([...(running.get(state) ?? [])]);
+}
+/** A publish cut off by a restart has no build left running; it is closed rather than left accepted. */
+export async function recoverInterruptedPreviews(journal) {
+    for (const { scopeKey, operation } of journal.listOperations()) {
+        if (operation.kind !== 'preview.publish' || operation.status !== 'accepted')
+            continue;
+        await journal.putOperation(scopeKey, transitionOperation(operation, 'interrupted', { error: 'preview_interrupted' }));
+    }
+}
+export async function runPreviewPublish(state, operation, root) {
+    const workspaceId = operation.workspaceId;
+    const scope = operation.sessionId === undefined
+        ? {}
+        : { sessionId: operation.sessionId, clientRequestId: operation.clientRequestId };
+    const outputDir = join(root, OUTPUT_FOLDER, operation.operationId);
+    const output = { log: '' };
+    const operationLog = new OperationLogStore(state.config.stateDir);
+    let logChain = Promise.resolve();
+    let remotePreview = false;
+    let buildCopy;
+    const appendLog = (text) => {
+        logChain = logChain.then(() => operationLog.append(operation.operationId, text)).catch(() => undefined);
+    };
+    await operationLog.append(operation.operationId, `$ preview build\n`).catch(() => undefined);
+    try {
+        await ensureDependencies(state, revisionScope(state, workspaceId, operation.directoryName) ?? workspaceId, root, output);
+        const runtimePreview = await prepareRuntimePreview(state, operation, root);
+        remotePreview = Boolean(runtimePreview);
+        if (runtimePreview)
+            await excludeFromGit(root, '/.playcraft-editor-preview/');
+        await excludeFromGit(root, `/${OUTPUT_FOLDER}/`);
+        await excludeFromGit(root, `/${BUILDER_TEMP_FOLDER}/`);
+        await excludeFromGit(root, `/${WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY}/`);
+        if (!runtimePreview) {
+            const signature = await workspacePlayableSignature(root);
+            buildCopy = await mkdtemp(join(tmpdir(), 'playcraft-preview-build-'));
+            // The build runs as the development identity while this copy belongs to the controller.
+            await openScratchToDevelopment(buildCopy, (await lstat(root)).gid);
+            const project = join(buildCopy, 'project'), staged = join(buildCopy, 'output');
+            await isolateWorkspaceForBuild(root, project);
+            await buildPreview(state, project, staged, operation.operationId, output, appendLog);
+            await finalizeWorkspacePlayable(root, await readSingleHtml(staged), 'preview.publish', {
+                expectedSignature: signature, source: { operationId: operation.operationId, ...(operation.sessionId ? { sessionId: operation.sessionId } : {}) },
+            });
+            await refreshWorkspaceArtifacts(state, workspaceId, undefined, operation.directoryName ?? 'basic');
+            return;
+        }
+        await buildPreview(state, root, outputDir, operation.operationId, output, appendLog, runtimePreview.command);
+        const runtimeBuild = runtimePreview ? await runtimePreview.finish() : undefined;
+        const built = runtimeBuild?.bytes ?? await readSingleHtml(outputDir);
+        const bytes = injectPreviewDiagnostics(built);
+        if (bytes.byteLength > PREVIEW_HTML_MAX_BYTES)
+            throw new PreviewFailure('preview_not_single_file');
+        if (findExternalLocalReferences(bytes.toString('utf8')).length > 0) {
+            throw new PreviewFailure('preview_not_single_file');
+        }
+        const contentDigest = createHash('sha256').update(bytes).digest('hex');
+        const contentMd5 = createHash('md5').update(bytes).digest('base64');
+        const source = await sourceRevision(root);
+        const reserved = previewReservationSchema.parse(await postControl(state, '/runtime/internal/preview-reservations', {
+            workspaceId,
+            directoryName: operation.directoryName ?? 'basic',
+            ...scope,
+            operationId: operation.operationId,
+            contentDigest,
+            contentMd5,
+            sizeBytes: bytes.byteLength,
+            gitHead: source.head,
+            dirty: source.dirty,
+            cliVersion: state.config.cliVersion,
+        }));
+        if (reserved.sessionId !== operation.sessionId)
+            throw new PreviewFailure('preview_scope_mismatch');
+        if (!reserved.alreadyUploaded) {
+            const uploaded = await fetch(reserved.uploadUrl, {
+                method: 'PUT',
+                redirect: 'error',
+                signal: AbortSignal.timeout(120_000),
+                headers: {
+                    'content-type': 'text/html; charset=utf-8',
+                    'content-md5': contentMd5,
+                    'content-length': String(bytes.byteLength),
+                },
+                body: new Uint8Array(bytes),
+            });
+            await uploaded.body?.cancel();
+            if (!uploaded.ok)
+                throw new PreviewFailure('preview_upload_failed');
+        }
+        const published = previewPublishResultSchema.parse(await postControl(state, '/runtime/internal/preview-completions', {
+            workspaceId,
+            directoryName: operation.directoryName ?? 'basic',
+            ...scope,
+            operationId: operation.operationId,
+            artifactId: reserved.artifactId,
+            expectedPublishRevision: reserved.expectedPublishRevision,
+            logTail: tail(output.log),
+        }));
+        if (published.sessionId !== operation.sessionId || published.previewId !== reserved.previewId ||
+            published.artifactId !== reserved.artifactId ||
+            published.contentDigest !== contentDigest ||
+            (runtimeBuild && JSON.stringify(published.runtimeParameters) !== JSON.stringify(runtimeBuild.profile))) {
+            throw new PreviewFailure('preview_scope_mismatch');
+        }
+        if (published.status === 'conflict')
+            throw new PreviewFailure('publish_conflict');
+        return published;
+    }
+    catch (error) {
+        const code = error instanceof RuntimePreviewBuildError ? error.code : previewFailureCode(error);
+        if (code === 'dependencies_not_ready' && output.log)
+            appendLog(`${output.log}\n`);
+        appendLog(`\n[${code}] ${error instanceof Error ? error.message : code}\n`);
+        if (remotePreview && code !== 'publish_conflict') {
+            await postControl(state, '/runtime/internal/preview-failures', {
+                workspaceId,
+                directoryName: operation.directoryName ?? 'basic',
+                ...scope,
+                operationId: operation.operationId,
+                error: code,
+                logTail: tail(output.log || (error instanceof Error ? error.message : '')),
+            }).catch(() => undefined);
+        }
+        throw new PreviewFailure(code);
+    }
+    finally {
+        await logChain;
+        await rm(outputDir, { recursive: true, force: true }).catch(() => undefined);
+        if (buildCopy)
+            await rm(buildCopy, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export function previewFailureCode(error) {
+    const code = error instanceof PreviewFailure
+        ? error.code
+        : error instanceof Error && /^[a-z_]+$/.test(error.message)
+            ? error.message
+            : 'preview_build_failed';
+    return code.slice(0, 256);
+}
+/**
+ * Checks the install against the current manifest and lockfile before building, so a package
+ * Codex added since the workspace opened is installed first. A running install is joined rather
+ * than started twice; a failed one is retried once here.
+ */
+async function ensureDependencies(state, workspaceId, root, output) {
+    await scheduleDependencyInstall(state, workspaceId, root);
+    const dependencies = readDependencies(state, workspaceId);
+    if (dependencies.status !== 'ready' && dependencies.status !== 'none') {
+        output.log = [dependencies.error, dependencies.logTail].filter(Boolean).join('\n');
+        throw new PreviewFailure('dependencies_not_ready');
+    }
+}
+async function buildPreview(state, root, outputDir, operationId, output, onLog, runtimeCommand) {
+    // Tests replace the build; the real one needs a project and the published CLI.
+    const planned = process.env.PLAYCRAFT_PREVIEW_BUILD_COMMAND || BUILD_COMMAND;
+    const outcome = await runDeveloperCommand(state, {
+        processId: `preview-${operationId}`,
+        cwd: root,
+        command: runtimeCommand ?? `${planned} --output ${shellQuote(outputDir)} .`,
+        timeoutMs: BUILD_TIMEOUT_MS,
+        onOutput: (chunk) => {
+            const text = String(chunk);
+            output.log = (output.log + text).slice(-64 * 1024);
+            onLog?.(text);
+        },
+    });
+    if (outcome.code !== 0)
+        throw new PreviewFailure('preview_build_failed');
+}
+/** Reads the one HTML file without following links, so the uploaded bytes are what was checked. */
+async function readSingleHtml(outputDir) {
+    const listed = await readdir(outputDir, { withFileTypes: true }).catch(() => {
+        throw new PreviewFailure('preview_not_single_file');
+    });
+    const entries = listed.map((entry) => ({
+        name: entry.name,
+        kind: entry.isSymbolicLink() ? 'symlink' : entry.isFile() ? 'file' : 'dir',
+    }));
+    const classified = classifyPreviewOutput(entries);
+    if (!classified.ok)
+        throw new PreviewFailure('preview_not_single_file');
+    const source = join(outputDir, classified.entry);
+    const stat = await lstat(source);
+    if (!stat.isFile())
+        throw new PreviewFailure('preview_not_single_file');
+    const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function sourceRevision(root) {
+    const head = await git(root, ['rev-parse', 'HEAD']);
+    const status = await git(root, ['status', '--porcelain']);
+    const revision = head.stdout.trim();
+    if (head.code !== 0 || !/^[0-9a-f]{7,64}$/i.test(revision))
+        return { dirty: true };
+    return { head: revision, dirty: status.code !== 0 || status.stdout.trim().length > 0 };
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (chunk) => {
+            stdout = (stdout + String(chunk)).slice(-8_000);
+        });
+        child.once('error', () => resolve({ code: null, stdout }));
+        child.once('close', (code) => resolve({ code, stdout }));
+    });
+}
+async function postControl(state, path, body) {
+    const endpoint = platformEndpoint(state.config.publicBaseUrl, path);
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(60_000),
+        headers: {
+            authorization: `Bearer ${state.config.controlToken}`,
+            'playcraft-env': state.config.environment,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            runtimeId: state.config.runtimeId,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            ...body,
+        }),
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const record = (payload && typeof payload === 'object' ? payload : {});
+        const reason = typeof record.reason === 'string' ? record.reason : typeof record.error === 'string' ? record.error : '';
+        throw new PreviewFailure(/^[a-z_]{1,64}$/.test(reason) ? reason : 'preview_upload_failed');
+    }
+    return payload;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function tail(value) {
+    return value.slice(-PREVIEW_LOG_TAIL_MAX);
+}