@playcraft/cli 0.1.42 → 0.1.43-beta

package/dist/workspace-runtime/workspaces/attachment-content.js

@@ -0,0 +1,73 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { attachmentIdsSchema, attachmentUploadSchema, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactMime, artifactPath } from './artifact-files.js';
+import { openLibraryAttachmentFile, readLibraryAttachmentMetadata } from './library-attachments.js';
+import { openWorkspaceDirectoryFile, readWorkspaceDirectoryMetadata } from './directory-attachments.js';
+import { serveOpenedWorkspaceContent } from './binary-content.js';
+const additionalMediaTypes = {
+    '.aac': 'audio/aac', '.opus': 'audio/ogg', '.oga': 'audio/ogg', '.aif': 'audio/aiff', '.aiff': 'audio/aiff',
+    '.bmp': 'image/bmp', '.ico': 'image/vnd.microsoft.icon', '.heic': 'image/heic', '.heif': 'image/heif',
+    '.tif': 'image/tiff', '.tiff': 'image/tiff',
+};
+const detectedImageTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+async function openAttachment(root, id, filePath) {
+    const metadataPath = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata/${id}.json`);
+    const metadataFile = await open(metadataPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let metadata;
+    try {
+        const stat = await metadataFile.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('attachment_unavailable');
+        metadata = JSON.parse(await metadataFile.readFile('utf8'));
+        if (metadata.id !== id || !attachmentUploadSchema.shape.name.safeParse(metadata.name).success)
+            throw new Error('attachment_unavailable');
+    }
+    finally {
+        await metadataFile.close();
+    }
+    if (metadata.origin?.kind === 'asset-library') {
+        const library = await readLibraryAttachmentMetadata(root, id);
+        return openLibraryAttachmentFile(root, library, filePath);
+    }
+    if (metadata.kind === 'directory') {
+        const directory = await readWorkspaceDirectoryMetadata(root, id);
+        return openWorkspaceDirectoryFile(root, directory, filePath);
+    }
+    if (filePath !== undefined)
+        throw new Error('attachment_unavailable');
+    const path = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${metadata.name}`);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        const mimeType = detectedImageTypes.has(metadata.mimeType) ? metadata.mimeType
+            : additionalMediaTypes[extname(metadata.name).toLowerCase()] ?? artifactMime(metadata.name);
+        const limit = mimeType.startsWith('video/') ? WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES : WORKSPACE_ATTACHMENT_MAX_BYTES;
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== metadata.size || stat.size > limit)
+            throw new Error('attachment_unavailable');
+        return { handle, name: metadata.name, mimeType, size: stat.size };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/** Serve only registered references; no caller-supplied file paths reach the filesystem. */
+export async function serveWorkspaceAttachment(root, attachmentId, request, response, filePath) {
+    if (!attachmentIdsSchema.safeParse([attachmentId]).success) {
+        response.writeHead(400, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+        response.end(JSON.stringify({ error: 'invalid_attachment' }));
+        return;
+    }
+    let content;
+    try {
+        content = await openAttachment(root, attachmentId, filePath);
+    }
+    catch {
+        response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+        response.end(JSON.stringify({ error: 'attachment_not_found' }));
+        return;
+    }
+    await serveOpenedWorkspaceContent(content, request, response);
+}

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

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { WORKSPACE_USER_UPLOADS_DIRECTORY, attachmentIdsSchema, attachmentUploadSchema, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, WORKSPACE_VIDEO_ATTACHMENT_MIME_TYPES, workspaceVideoAttachmentQuerySchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { NativePreparationError } from '../codex/native-adapter.js';
+import { excludeFromGit } from './dependencies.js';
+import { hashAttachment, probeAttachmentVideo } from './video-attachments.js';
+import { resolveLibraryAttachment } from './library-attachments.js';
+import { resolveWorkspaceDirectoryAttachment } from './directory-attachments.js';
+async function attachmentRoot(root) {
+    // Reject redirected upload directories, including symlinks that stay inside the workspace.
+    let directory = root;
+    for (const part of WORKSPACE_USER_UPLOADS_DIRECTORY.split('/')) {
+        directory = join(directory, part);
+        await mkdir(directory, { mode: 0o755 }).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error('invalid_attachment');
+        await chmod(directory, 0o755);
+    }
+    return directory;
+}
+export function imageMime(bytes) {
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+        return 'image/jpeg';
+    if (/^GIF8[79]a$/.test(bytes.subarray(0, 6).toString('ascii')))
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP')
+        return 'image/webp';
+    return 'application/octet-stream';
+}
+export async function readAttachmentUpload(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 4 * Math.ceil(WORKSPACE_ATTACHMENT_MAX_BYTES / 3) + 4096)
+            throw new Error('invalid_attachment');
+        chunks.push(bytes);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/** References belong to the workspace and are retained by its checkpoints. */
+export async function uploadWorkspaceAttachment(root, body) {
+    const parsed = attachmentUploadSchema.parse(body);
+    const bytes = Buffer.from(parsed.content, 'base64');
+    if (bytes.length > WORKSPACE_ATTACHMENT_MAX_BYTES || bytes.toString('base64') !== parsed.content)
+        throw new Error('invalid_attachment');
+    const attachment = {
+        id: randomUUID(),
+        name: parsed.name,
+        size: bytes.length,
+        mimeType: imageMime(bytes),
+    };
+    await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    const uploads = await attachmentRoot(root);
+    const directory = join(uploads, attachment.id);
+    const metadataDirectory = join(uploads, '.metadata');
+    await mkdir(metadataDirectory, { mode: 0o755 }).catch((error) => {
+        if (error.code !== 'EEXIST')
+            throw error;
+    });
+    if (!(await lstat(metadataDirectory)).isDirectory())
+        throw new Error('invalid_attachment');
+    // Codex can run as a different user from the sandbox control process.
+    await mkdir(directory, { mode: 0o755 });
+    await writeFile(join(directory, attachment.name), bytes, { flag: 'wx', mode: 0o644 });
+    await writeFile(join(metadataDirectory, `${attachment.id}.json`), JSON.stringify(attachment), {
+        flag: 'wx',
+        mode: 0o644,
+    });
+    return attachment;
+}
+/** Video bodies are streamed into an unpublished attachment and never decoded as base64. */
+export async function uploadWorkspaceVideoAttachment(root, request, query) {
+    const { name } = workspaceVideoAttachmentQuerySchema.parse(query);
+    const contentType = String(request.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+    const declaredSize = request.headers['content-length'];
+    if (!WORKSPACE_VIDEO_ATTACHMENT_MIME_TYPES.includes(contentType)
+        || (declaredSize !== undefined && (!/^\d+$/.test(declaredSize) || Number(declaredSize) > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)))
+        throw new Error('invalid_attachment');
+    await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    const uploads = await attachmentRoot(root);
+    const id = randomUUID(), directory = join(uploads, id), metadataDirectory = join(uploads, '.metadata');
+    await mkdir(metadataDirectory, { mode: 0o755 }).catch((error) => { if (error.code !== 'EEXIST')
+        throw error; });
+    if (!(await lstat(metadataDirectory)).isDirectory())
+        throw new Error('invalid_attachment');
+    await mkdir(directory, { mode: 0o755 });
+    const handle = await open(join(directory, name), constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o644);
+    try {
+        let size = 0;
+        for await (const data of request) {
+            const bytes = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            size += bytes.length;
+            if (size > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
+                throw new Error('invalid_attachment');
+            let offset = 0;
+            while (offset < bytes.length)
+                offset += (await handle.write(bytes, offset, bytes.length - offset, size - bytes.length + offset)).bytesWritten;
+        }
+        if (!size || (declaredSize !== undefined && Number(declaredSize) !== size))
+            throw new Error('invalid_attachment');
+        await handle.sync();
+        const media = await probeAttachmentVideo(handle);
+        if (contentType !== media.mimeType && !(contentType === 'video/quicktime' && media.mimeType === 'video/mp4'))
+            throw new Error('invalid_attachment');
+        const attachment = { id, name, size, ...media, sha256: await hashAttachment(handle) };
+        await writeFile(join(metadataDirectory, `${id}.json`), JSON.stringify(attachment), { flag: 'wx', mode: 0o644 });
+        return attachment;
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function resolveWorkspaceAttachments(root, input) {
+    try {
+        const ids = attachmentIdsSchema.parse(input ?? []);
+        const attachments = await Promise.all(ids.map(async (id) => {
+            const uploads = await attachmentRoot(root);
+            const directory = join(uploads, id);
+            if (!(await lstat(directory)).isDirectory())
+                throw new Error('invalid_attachment');
+            await chmod(directory, 0o755);
+            if (!(await lstat(join(uploads, '.metadata'))).isDirectory())
+                throw new Error('invalid_attachment');
+            const metadataHandle = await open(join(uploads, '.metadata', `${id}.json`), constants.O_RDONLY | constants.O_NOFOLLOW);
+            let metadata;
+            try {
+                const stat = await metadataHandle.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+                    throw new Error('invalid_attachment');
+                metadata = JSON.parse(await metadataHandle.readFile('utf8'));
+            }
+            finally {
+                await metadataHandle.close();
+            }
+            if (metadata.origin?.kind === 'asset-library')
+                return resolveLibraryAttachment(root, id);
+            if (metadata.kind === 'directory')
+                return resolveWorkspaceDirectoryAttachment(root, id);
+            attachmentUploadSchema.shape.name.parse(metadata.name);
+            if (metadata.id !== id)
+                throw new Error('invalid_attachment');
+            const path = join(directory, metadata.name);
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                const video = metadata.mimeType?.startsWith('video/');
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size !== metadata.size || stat.size > (video ? WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES : WORKSPACE_ATTACHMENT_MAX_BYTES))
+                    throw new Error('invalid_attachment');
+                if (video) {
+                    const media = await probeAttachmentVideo(handle);
+                    const sha256 = await hashAttachment(handle);
+                    if (sha256 !== metadata.sha256 || media.mimeType !== metadata.mimeType || media.durationMs !== metadata.durationMs
+                        || media.width !== metadata.width || media.height !== metadata.height)
+                        throw new Error('invalid_attachment');
+                    return { ...metadata, ...media, path };
+                }
+                const bytes = Buffer.alloc(12);
+                const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+                return { ...metadata, size: stat.size, mimeType: imageMime(bytes.subarray(0, bytesRead)), path };
+            }
+            finally {
+                await handle.close();
+            }
+        }));
+        if (attachments.reduce((total, attachment) => total + attachment.size, 0) > WORKSPACE_ATTACHMENT_MAX_BYTES)
+            throw new Error('invalid_attachment');
+        return attachments;
+    }
+    catch {
+        throw new NativePreparationError('attachment_unavailable');
+    }
+}

package/dist/workspace-runtime/workspaces/batch-commit.js

@@ -0,0 +1,142 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, open, realpath, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { batchCommitSourceVersion } from '@playcraft/common/cloud-workspace/runtime';
+import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
+const execute = promisify(execFile);
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const PRIVATE_NAMES = new Set([
+    '.ssh', '.aws', '.azure', '.gnupg', '.codex', '.npm', '.pnpm-store', '.config',
+    '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc', '.git-credentials', 'credentials.json',
+    'credentials', 'secrets', 'id_rsa', 'id_ed25519', 'settings.local.json', '.playcraft.json', 'playcraft.config.json',
+]);
+const DEPENDENCY_LOCKS = ['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const SKILLS_DECLARATION = '.playcraft/skills.json';
+const SKILLS_LOCK = '.playcraft/skills.lock.json';
+const sha256 = (body) => createHash('sha256').update(body).digest('hex');
+async function git(root, args, encoding = 'utf8') {
+    const { stdout } = await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+        timeout: 90_000, maxBuffer: 64 * 1024 * 1024, encoding: 'buffer',
+        env: { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+    });
+    return encoding === 'utf8' ? Buffer.from(stdout.toString('utf8').trim()) : stdout;
+}
+function assertSource(source) {
+    if (!ID.test(source.workspaceId) || !isAbsolute(source.root))
+        throw new Error('batch_snapshot_scope_invalid');
+}
+function engineeringPath(path) {
+    return !path.split('/').some((name) => PRIVATE_NAMES.has(name) || /^\.env(?:$|\.)/.test(name) || /\.(?:pem|key|p12|pfx)$/.test(name));
+}
+function lockedArtifacts(declaration, lock) {
+    const snapshot = validateProjectSkillsSnapshot(JSON.parse(declaration.toString('utf8')), JSON.parse(lock.toString('utf8')));
+    return snapshot.lock.entries.map((entry) => `.playcraft/skill-artifacts/${entry.revision.artifactHash}.tar.gz`);
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Locked skill archives are kept out of Git; each one is named by the hash of its exact bytes. */
+async function readArtifact(root, path) {
+    const full = join(root, ...path.split('/'));
+    if (!inside(root, await realpath(dirname(full)).catch(() => '')))
+        throw new Error('batch_snapshot_skill_artifact_missing');
+    const handle = await open(full, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => undefined);
+    if (!handle)
+        throw new Error('batch_snapshot_skill_artifact_missing');
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('batch_snapshot_skill_artifact_missing');
+        const body = await handle.readFile();
+        if (sha256(body) !== path.slice(path.lastIndexOf('/') + 1, -'.tar.gz'.length))
+            throw new Error('batch_snapshot_skill_artifact_missing');
+        return body;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function treeChecksum(root, commitHash) {
+    const listing = await git(root, ['ls-tree', '-r', '--full-tree', '-z', commitHash], 'buffer');
+    const paths = listing.toString('utf8').split('\0').filter(Boolean).map((line) => line.slice(line.indexOf('\t') + 1));
+    return { checksum: sha256(listing), paths };
+}
+/**
+ * Freezes a commit of `basic` as batch input. The commit is already saved by Git, so later edits to
+ * `basic` never reach the batch; nothing is copied to separate storage. A commit is accepted only
+ * when it carries the dependency lock and skill lock its build needs and no credential files.
+ */
+export async function freezeBatchCommit(input) {
+    assertSource(input.source);
+    if (!COMMIT.test(input.commitHash) || !ID.test(input.snapshotId))
+        throw new Error('batch_snapshot_commit_required');
+    const root = await realpath(input.source.root);
+    const resolved = (await git(root, ['rev-parse', '--verify', '--quiet', `${input.commitHash}^{commit}`]).catch(() => Buffer.from(''))).toString();
+    if (resolved !== input.commitHash)
+        throw new Error('batch_snapshot_commit_required');
+    const { checksum, paths } = await treeChecksum(root, input.commitHash);
+    if (paths.some((path) => !engineeringPath(path)))
+        throw new Error('batch_snapshot_path_invalid');
+    const tracked = new Set(paths);
+    if (!tracked.has('package.json') || !DEPENDENCY_LOCKS.some((path) => tracked.has(path)))
+        throw new Error('batch_snapshot_dependency_lock_required');
+    if (!tracked.has(SKILLS_DECLARATION) || !tracked.has(SKILLS_LOCK))
+        throw new Error('batch_snapshot_skills_lock_required');
+    const declaration = await git(root, ['show', `${input.commitHash}:${SKILLS_DECLARATION}`], 'buffer');
+    const lock = await git(root, ['show', `${input.commitHash}:${SKILLS_LOCK}`], 'buffer');
+    for (const path of lockedArtifacts(declaration, lock))
+        if (!tracked.has(path))
+            await readArtifact(root, path);
+    const committedAt = (await git(root, ['show', '-s', '--format=%cI', input.commitHash])).toString();
+    return {
+        snapshotId: input.snapshotId, sourceWorkspaceId: input.source.workspaceId, commitHash: input.commitHash, checksum,
+        sourceVersion: batchCommitSourceVersion(input.commitHash), skillLockDigest: sha256(lock),
+        frozenAt: new Date(committedAt).toISOString(),
+    };
+}
+/**
+ * Checks the frozen commit out into a new private directory and adds the locked skill archives. A
+ * pre-existing destination is never reused, and the checkout must still match the frozen checksum.
+ */
+export async function checkoutBatchCommit(input) {
+    assertSource(input.source);
+    if (!isAbsolute(input.destination) || !COMMIT.test(input.frozen.commitHash))
+        throw new Error('batch_snapshot_scope_invalid');
+    if (input.frozen.sourceWorkspaceId !== input.source.workspaceId)
+        throw new Error('batch_snapshot_identity_mismatch');
+    if (await lstat(input.destination).catch(() => undefined))
+        throw new Error('batch_snapshot_destination_exists');
+    const root = await realpath(input.source.root);
+    const { checksum } = await treeChecksum(root, input.frozen.commitHash);
+    if (checksum !== input.frozen.checksum)
+        throw new Error('batch_snapshot_identity_mismatch');
+    await mkdir(dirname(input.destination), { recursive: true });
+    try {
+        await execute('git', ['-c', 'core.hooksPath=/dev/null', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', root, input.destination], {
+            timeout: 90_000, maxBuffer: 1024 * 1024,
+            env: { PATH: process.env.PATH, HOME: dirname(input.destination), GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+        });
+        await git(input.destination, ['checkout', '--detach', input.frozen.commitHash]);
+        const lock = await git(input.destination, ['show', `${input.frozen.commitHash}:${SKILLS_LOCK}`], 'buffer');
+        if (sha256(lock) !== input.frozen.skillLockDigest)
+            throw new Error('batch_snapshot_identity_mismatch');
+        const declaration = await git(input.destination, ['show', `${input.frozen.commitHash}:${SKILLS_DECLARATION}`], 'buffer');
+        for (const path of lockedArtifacts(declaration, lock)) {
+            const target = join(input.destination, ...path.split('/'));
+            if (await lstat(target).catch(() => undefined))
+                continue;
+            const body = await readArtifact(root, path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, body, { flag: 'wx', mode: 0o600 });
+        }
+    }
+    catch (cause) {
+        await rm(input.destination, { recursive: true, force: true });
+        throw cause;
+    }
+}

package/dist/workspace-runtime/workspaces/binary-content.js

@@ -0,0 +1,65 @@
+import { pipeline } from 'node:stream/promises';
+function contentRange(header, size) {
+    if (!header)
+        return undefined;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match || (!match[1] && !match[2]) || !size)
+        return null;
+    const first = match[1] ? Number(match[1]) : undefined;
+    const last = match[2] ? Number(match[2]) : undefined;
+    if ((first !== undefined && !Number.isSafeInteger(first)) || (last !== undefined && !Number.isSafeInteger(last)))
+        return null;
+    const start = first ?? Math.max(0, size - (last ?? 0));
+    const end = first === undefined ? size - 1 : Math.min(last ?? size - 1, size - 1);
+    return start >= size || start > end ? null : { start, end };
+}
+/** Streams an already-authorized open file and closes its handle on completion or cancellation. */
+export async function serveOpenedWorkspaceContent(content, request, response) {
+    const abort = new AbortController();
+    const cancel = () => abort.abort();
+    const close = () => { if (!response.writableEnded)
+        cancel(); };
+    request.once('aborted', cancel);
+    response.once('close', close);
+    try {
+        const range = contentRange(request.headers.range, content.size);
+        const headers = {
+            'content-type': content.mimeType,
+            'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff',
+            'content-security-policy': "sandbox; default-src 'none'; style-src 'unsafe-inline'",
+            'referrer-policy': 'no-referrer',
+            'accept-ranges': 'bytes',
+        };
+        if (!/^(?:image|video|audio|model)\//.test(content.mimeType) || content.mimeType === 'image/svg+xml')
+            headers['content-disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(content.name).replace(/'/g, '%27')}`;
+        if (range === null) {
+            response.writeHead(416, { ...headers, 'content-range': `bytes */${content.size}`, 'content-length': '0' });
+            response.end();
+            return;
+        }
+        if (range)
+            headers['content-range'] = `bytes ${range.start}-${range.end}/${content.size}`;
+        headers['content-length'] = String(range ? range.end - range.start + 1 : content.size);
+        response.writeHead(range ? 206 : 200, headers);
+        if (request.method === 'HEAD' || !content.size) {
+            response.end();
+            return;
+        }
+        if (request.aborted || response.destroyed)
+            cancel();
+        await pipeline(content.handle.createReadStream({
+            start: range?.start ?? 0,
+            end: range?.end ?? content.size - 1,
+            autoClose: false,
+        }), response, { signal: abort.signal });
+    }
+    catch (error) {
+        response.destroy(error instanceof Error ? error : undefined);
+    }
+    finally {
+        request.off('aborted', cancel);
+        response.off('close', close);
+        await content.handle.close();
+    }
+}

package/dist/workspace-runtime/workspaces/binary-write.js

@@ -0,0 +1,112 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileBinaryWritePayloadSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from './artifact-files.js';
+import { sampleDiskFile } from './disk-snapshot.js';
+import { InvalidWorkspacePathError } from './files.js';
+export class BinaryWorkspaceWriteError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+/** Read raw bytes through the existing no-link boundary, including an absent destination. */
+export async function observeWorkspaceBinaryFile(root, path) {
+    try {
+        const target = await artifactPath(root, path);
+        const stat = await lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new InvalidWorkspacePathError(path);
+        const sample = await sampleDiskFile(target);
+        const verified = await lstat(await artifactPath(root, path));
+        if (!sameFile(stat, verified))
+            throw new BinaryWorkspaceWriteError('content_conflict');
+        return { contentHash: sample.hash, size: sample.size, modifiedAt: sample.modifiedAt };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        if (error instanceof Error && error.message === 'invalid_artifact_path')
+            throw new InvalidWorkspacePathError(path);
+        throw error;
+    }
+}
+/** Stage complete bytes and publish atomically; an absent target is never replaced. */
+export async function writeWorkspaceBinaryFile(root, input) {
+    const payload = fileBinaryWritePayloadSchema.parse(input);
+    const rootReal = await realpath(root);
+    let parent = rootReal;
+    const parts = payload.path.split('/');
+    if (parts.some(part => ['.git', 'node_modules', '.playcraft-temp'].includes(part)))
+        throw new InvalidWorkspacePathError(payload.path);
+    for (const part of parts.slice(0, -1)) {
+        parent = join(parent, part);
+        await mkdir(parent, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(parent);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new InvalidWorkspacePathError(payload.path);
+    }
+    const parentStat = await lstat(parent);
+    const target = join(parent, basename(payload.path));
+    const temporary = join(parent, `.playcraft-binary-${randomUUID()}.tmp`);
+    const bytes = Buffer.from(payload.contentBase64, 'base64');
+    let staged = false;
+    try {
+        await verifyPreconditions(rootReal, payload);
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        staged = true;
+        try {
+            const stagedPath = [...parts.slice(0, -1), basename(temporary)].join('/');
+            const authorized = await lstat(await artifactPath(rootReal, stagedPath));
+            if (!sameFile(authorized, await handle.stat()))
+                throw new InvalidWorkspacePathError(payload.path);
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // External editors bypass the journal lock. Re-sample after staging, before publishing.
+        if (!sameFile(parentStat, await lstat(parent)) || (await realpath(parent)) !== parent)
+            throw new InvalidWorkspacePathError(payload.path);
+        await verifyPreconditions(rootReal, payload);
+        if (payload.expectedContentHash === null) {
+            try {
+                await link(temporary, target);
+            }
+            catch (error) {
+                if (error.code === 'EEXIST')
+                    throw new BinaryWorkspaceWriteError('content_conflict');
+                throw error;
+            }
+        }
+        else {
+            await rename(temporary, target);
+            staged = false;
+        }
+        return { path: payload.path, contentHash: createHash('sha256').update(bytes).digest('hex'), size: bytes.byteLength,
+            modifiedAt: (await lstat(target)).mtime.toISOString() };
+    }
+    finally {
+        if (staged)
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+    }
+}
+async function verifyPreconditions(root, payload) {
+    const target = await observeWorkspaceBinaryFile(root, payload.path);
+    if ((target?.contentHash ?? null) !== payload.expectedContentHash)
+        throw new BinaryWorkspaceWriteError('content_conflict');
+    if (payload.source) {
+        const source = await observeWorkspaceBinaryFile(root, payload.source.path);
+        if (source?.contentHash !== payload.source.contentHash)
+            throw new BinaryWorkspaceWriteError('source_content_conflict');
+    }
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.isDirectory() === right.isDirectory();
+}

package/dist/workspace-runtime/workspaces/cli-context.js

@@ -0,0 +1,23 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { excludeFromGit } from './dependencies.js';
+/** Non-secret routing hint; the business service still authorizes the selected workspace. */
+export async function writeWorkspaceCliContext(root, workspaceId) {
+    const management = join(root, '.playcraft');
+    await mkdir(management, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const stat = await lstat(management);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('workspace_skills_invalid');
+    const temporary = join(management, `workspace-context.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify({ schemaVersion: 'playcraft.workspace-context.v1', workspaceId })}\n`, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, join(management, 'workspace-context.json'));
+        await excludeFromGit(root, '/.playcraft/workspace-context.json');
+        await excludeFromGit(root, '/.playcraft/video-replication/');
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}