@playcraft/cli 0.1.31 → 0.1.32

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

@@ -0,0 +1,99 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { applyWorkspaceTransfer, createWorkspaceTransfer, WORKSPACE_TRANSFER_MAX_BYTES, WorkspaceTransferError } from '../workspaces/transfer.js';
+import { revisionScope, sessionWorkspaceRoot } from '../workspaces/registry.js';
+import { workspaceDirectoryOccupied } from '../workspaces/directory-maintenance.js';
+import { publishSourceEvents } from './dispatch.js';
+export async function handleWorkspaceTransfer(state, request, response, url) {
+    const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+    const directoryName = url.searchParams.get('directoryName') ?? 'basic';
+    const root = await sessionWorkspaceRoot(state, workspaceId, directoryName);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const close = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', close);
+    try {
+        if (request.method === 'GET') {
+            const snapshot = await createWorkspaceTransfer(root);
+            try {
+                controller.signal.throwIfAborted();
+                response.writeHead(200, { 'content-type': 'application/octet-stream', 'cache-control': 'private, no-store',
+                    'content-length': (await stat(snapshot.bundlePath)).size, 'x-content-type-options': 'nosniff',
+                    'x-playcraft-workspace-tree': snapshot.tree, 'x-playcraft-workspace-head': snapshot.head });
+                await pipeline(createReadStream(snapshot.bundlePath), response, { signal: controller.signal });
+            }
+            finally {
+                await snapshot.cleanup();
+            }
+            return;
+        }
+        const expectedTree = request.headers['x-playcraft-workspace-tree'];
+        if (typeof expectedTree !== 'string' || !/^[a-f0-9]{40,64}$/.test(expectedTree))
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        if (Number(request.headers['content-length'] ?? 0) > WORKSPACE_TRANSFER_MAX_BYTES)
+            throw new WorkspaceTransferError('workspace_transfer_too_large');
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of request) {
+            size += chunk.length;
+            if (size > WORKSPACE_TRANSFER_MAX_BYTES)
+                throw new WorkspaceTransferError('workspace_transfer_too_large');
+            chunks.push(Buffer.from(chunk));
+        }
+        const directories = directoryName === 'root'
+            ? [...new Set(['root', 'basic', ...(state.journal.getWorkspace(workspaceId ?? '')?.directories ?? []).map(item => item.directoryName)])].sort()
+            : [...new Set(['root', directoryName])].sort();
+        const lockKeys = [...new Set([...directories.map(name => `directory:${workspaceId}:${name}`),
+                ...directories.map(name => `workspace:${revisionScope(state, workspaceId, name) ?? 'single'}`)])];
+        const locked = async (index) => index < lockKeys.length
+            ? state.journal.exclusive(lockKeys[index], () => locked(index + 1))
+            : apply();
+        const apply = async () => {
+            controller.signal.throwIfAborted();
+            if (state.journal.destroyed())
+                throw new WorkspaceTransferError('runtime_destroyed');
+            for (const directory of directories) {
+                if (await workspaceDirectoryOccupied(state, workspaceId ?? 'workspace', directory))
+                    throw new WorkspaceTransferError('workspace_transfer_busy');
+            }
+            return applyWorkspaceTransfer(root, Buffer.concat(chunks, size), expectedTree);
+        };
+        const result = await locked(0);
+        if (result.changedPaths.length > 0) {
+            const groups = new Map([[directoryName, result.changedPaths]]);
+            if (directoryName === 'root')
+                for (const path of result.changedPaths) {
+                    const [directory, ...parts] = path.split('/');
+                    if (directory && directories.includes(directory) && parts.length)
+                        groups.set(directory, [...(groups.get(directory) ?? []), parts.join('/')]);
+                }
+            const events = [];
+            for (const [directory, paths] of groups)
+                events.push(await state.journal.allocateSourceEvent({
+                    runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+                    workspaceId, type: 'files.changed', occurredAt: new Date().toISOString(), payload: { workspaceId, directoryName: directory, paths },
+                }));
+            await publishSourceEvents(state, events);
+        }
+        writeJson(response, 200, result);
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const code = error instanceof WorkspaceTransferError ? error.code : 'workspace_transfer_failed';
+            writeJson(response, code === 'workspace_transfer_too_large' ? 413 : code === 'invalid_workspace_transfer' ? 400 : 409, { error: code });
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', close);
+    }
+}
+function writeJson(response, status, body) {
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'private, no-store' });
+    response.end(JSON.stringify(body));
+}

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

@@ -0,0 +1,207 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createDeflateRaw } from 'node:zlib';
+import { isCredentialFile } from './git.js';
+const EXCLUDED_NAMES = new Set(['.git', 'node_modules', '.playcraft.json', '.playcraft-workspace.json']);
+const MAX_SOURCE_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 50_000;
+const UTF8_DESCRIPTOR_FLAGS = 0x0808;
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1)
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    return crc >>> 0;
+});
+/** Exports working files, including ignored deliverables, without following symbolic links. */
+export async function createWorkspaceArchive(root, options = {}) {
+    const rootReal = await realpath(root);
+    const excludedRoots = await Promise.all((options.excludedRoots ?? []).map(path => realpath(path).catch(() => path)));
+    const entries = [];
+    let bytes = 0;
+    const walk = async (directory) => {
+        options.signal?.throwIfAborted();
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || !inside(rootReal, await realpath(directory)))
+            throw new Error('workspace_archive_changed');
+        for await (const entry of await opendir(directory)) {
+            options.signal?.throwIfAborted();
+            if (EXCLUDED_NAMES.has(entry.name) || entry.name.startsWith('.playcraft-credential-'))
+                continue;
+            const target = join(directory, entry.name);
+            const path = relative(rootReal, target).split(sep).join('/');
+            if (isCredentialFile(path) || /(?:^|\/)\.playcraft\/(?:workspace-context(?:\.[^/]*)?|video-replication)(?:\/|$)/.test(path))
+                continue;
+            if (excludedRoots.some(excluded => inside(excluded, target)))
+                continue;
+            const info = await lstat(target);
+            if (info.isSymbolicLink())
+                continue;
+            if (!inside(rootReal, await realpath(target)))
+                throw new Error('workspace_archive_changed');
+            if (info.isDirectory()) {
+                await walk(target);
+                continue;
+            }
+            if (!info.isFile())
+                continue;
+            if (Buffer.byteLength(path) > 65_535 || /[\0\\]/.test(path))
+                throw new Error('workspace_archive_invalid_path');
+            bytes += info.size;
+            if (bytes > (options.maxSourceBytes ?? MAX_SOURCE_BYTES) || entries.length >= (options.maxEntries ?? MAX_ENTRIES))
+                throw new Error('workspace_archive_too_large');
+            entries.push({ path, target, info });
+        }
+    };
+    await walk(rootReal);
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    return Readable.from(zipFiles(rootReal, entries, options.signal));
+}
+/** Standard ZIP (ZIP archive format, 压缩归档格式) records are streamed with bounded buffers. */
+async function* zipFiles(root, entries, signal) {
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        signal?.throwIfAborted();
+        if (!inside(root, await realpath(entry.target)))
+            throw new Error('workspace_archive_changed');
+        const handle = await open(entry.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.dev !== entry.info.dev || info.ino !== entry.info.ino || info.size !== entry.info.size
+                || info.mtimeMs !== entry.info.mtimeMs || info.ctimeMs !== entry.info.ctimeMs)
+                throw new Error('workspace_archive_changed');
+            const name = Buffer.from(entry.path);
+            const stamp = zipTimestamp(info.mtime);
+            const header = Buffer.alloc(30);
+            header.writeUInt32LE(0x04034b50, 0);
+            header.writeUInt16LE(20, 4);
+            header.writeUInt16LE(UTF8_DESCRIPTOR_FLAGS, 6);
+            header.writeUInt16LE(8, 8);
+            header.writeUInt32LE(stamp, 10);
+            header.writeUInt16LE(name.length, 26);
+            const start = offset;
+            yield header;
+            yield name;
+            offset += header.length + name.length;
+            let crc = 0xffffffff;
+            let size = 0;
+            let compressedSize = 0;
+            const checksum = new Transform({ transform(chunk, _encoding, done) {
+                    size += chunk.length;
+                    if (size > info.size) {
+                        done(new Error('workspace_archive_changed'));
+                        return;
+                    }
+                    for (const byte of chunk)
+                        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+                    done(null, chunk);
+                } });
+            const compressed = createDeflateRaw();
+            const completion = pipeline(handle.createReadStream({ autoClose: false }), checksum, compressed, { signal });
+            void completion.catch(() => undefined);
+            try {
+                for await (const chunk of compressed) {
+                    signal?.throwIfAborted();
+                    compressedSize += chunk.length;
+                    offset += chunk.length;
+                    yield chunk;
+                }
+                await completion;
+            }
+            finally {
+                compressed.destroy();
+                checksum.destroy();
+                await completion.catch(() => undefined);
+            }
+            if (size !== info.size)
+                throw new Error('workspace_archive_changed');
+            const after = await handle.stat();
+            if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs)
+                throw new Error('workspace_archive_changed');
+            crc = (crc ^ 0xffffffff) >>> 0;
+            const descriptor = Buffer.alloc(16);
+            descriptor.writeUInt32LE(0x08074b50, 0);
+            descriptor.writeUInt32LE(crc, 4);
+            descriptor.writeUInt32LE(compressedSize, 8);
+            descriptor.writeUInt32LE(size, 12);
+            yield descriptor;
+            offset += descriptor.length;
+            const record = Buffer.alloc(46);
+            record.writeUInt32LE(0x02014b50, 0);
+            record.writeUInt16LE(0x0314, 4);
+            record.writeUInt16LE(20, 6);
+            record.writeUInt16LE(UTF8_DESCRIPTOR_FLAGS, 8);
+            record.writeUInt16LE(8, 10);
+            record.writeUInt32LE(stamp, 12);
+            record.writeUInt32LE(crc, 16);
+            record.writeUInt32LE(compressedSize, 20);
+            record.writeUInt32LE(size, 24);
+            record.writeUInt16LE(name.length, 28);
+            record.writeUInt32LE(((info.mode & 0xffff) << 16) >>> 0, 38);
+            record.writeUInt32LE(start, 42);
+            central.push(record, name);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    const centralStart = offset;
+    for (const record of central) {
+        signal?.throwIfAborted();
+        yield record;
+        offset += record.length;
+    }
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(offset - centralStart, 12);
+    end.writeUInt32LE(centralStart, 16);
+    yield end;
+}
+export async function serveWorkspaceArchive(root, request, response, options = {}) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const close = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', close);
+    try {
+        const archive = await createWorkspaceArchive(root, { ...options, signal: controller.signal });
+        response.writeHead(200, {
+            'content-type': 'application/zip', 'content-disposition': 'attachment; filename="workspace.zip"',
+            'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff',
+        });
+        if (request.method === 'HEAD') {
+            archive.destroy();
+            response.end();
+            return;
+        }
+        await pipeline(archive, response, { signal: controller.signal });
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const reason = error instanceof Error ? error.message : 'workspace_archive_failed';
+            response.writeHead(reason === 'workspace_archive_too_large' ? 413 : 409, { 'content-type': 'application/json', 'cache-control': 'private, no-store' });
+            response.end(JSON.stringify({ error: reason.startsWith('workspace_archive_') ? reason : 'workspace_archive_failed' }));
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', close);
+    }
+}
+function inside(root, target) {
+    const path = relative(root, target);
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !path.startsWith(sep));
+}
+function zipTimestamp(date) {
+    const year = Math.min(2107, Math.max(1980, date.getUTCFullYear()));
+    return (((year - 1980) << 25) | ((date.getUTCMonth() + 1) << 21) | (date.getUTCDate() << 16)
+        | (date.getUTCHours() << 11) | (date.getUTCMinutes() << 5) | (date.getUTCSeconds() >>> 1)) >>> 0;
+}

package/dist/workspace-runtime/workspaces/artifact-files.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, realpath, link, unlink } from 'node:fs/promises';
 import { extname, join, posix, resolve, sep } from 'node:path';
-import { WORKSPACE_ARTIFACT_MAX_BYTES, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
 const formats = {
     '.png': ['image', 'image/png'], '.jpg': ['image', 'image/jpeg'], '.jpeg': ['image', 'image/jpeg'],
     '.webp': ['image', 'image/webp'], '.gif': ['image', 'image/gif'], '.avif': ['image', 'image/avif'], '.svg': ['image', 'image/svg+xml'],
@@ -105,7 +105,7 @@ function resourcePath(primary, uri) {
         throw new Error('invalid_artifact_resource');
     const decoded = decodeURIComponent(uri);
     const path = posix.normalize(posix.join(posix.dirname(primary), decoded));
-    if (!workspaceRelativePathSchema.safeParse(path).success || path.split('/').some(part => part.startsWith('.')))
+    if (!isWorkspaceArtifactOutputPath(path) || path.split('/').some(part => part.startsWith('.')))
         throw new Error('invalid_artifact_resource');
     return path;
 }
@@ -173,6 +173,8 @@ export async function artifactResources(root, path) {
     return [...resources].sort();
 }
 export async function snapshotArtifactBundle(root, path, objects, thumbnailPath) {
+    if (!isWorkspaceArtifactOutputPath(path) || (thumbnailPath !== undefined && !isWorkspaceArtifactOutputPath(thumbnailPath)))
+        throw new Error('invalid_artifact_path');
     const resources = await artifactResources(root, path);
     const files = [await snapshotArtifactFile(root, path, objects)];
     for (const resource of resources)

package/dist/workspace-runtime/workspaces/artifact-receipts.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, open, rename, unlink } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { workspaceArtifactReceiptSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { isWorkspaceArtifactOutputPath, workspaceArtifactReceiptSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactDirectory, artifactFormat, relativeArtifactPath, snapshotArtifactBundle } from './artifact-files.js';
 import { excludeFromGit } from './dependencies.js';
 export const ARTIFACT_RECEIPTS_DIRECTORY = '.playcraft/artifact-receipts';
@@ -32,7 +32,7 @@ async function generatedWorkspace(cwd) {
             return undefined;
     }
 }
-/** Generation finishes only after its bytes have been preserved, even if the next command overwrites the output. */
+/** Preserve final outputs before another command overwrites them; intermediate project assets are not registered. */
 export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd = process.cwd()) {
     const context = await generatedWorkspace(cwd);
     if (!context)
@@ -45,7 +45,7 @@ export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd
     catch {
         return;
     }
-    if (!artifactFormat(path))
+    if (!isWorkspaceArtifactOutputPath(path) || !artifactFormat(path))
         return;
     const receipts = await artifactDirectory(context.root, ARTIFACT_RECEIPTS_DIRECTORY);
     const objects = await artifactDirectory(context.root, `${ARTIFACT_RECEIPTS_DIRECTORY}/objects`);

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

@@ -3,13 +3,22 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import sharp from 'sharp';
-import { workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactBundleDigest, artifactDirectory, artifactFormat, artifactPath, artifactResources, snapshotArtifactBundle, snapshotArtifactFile } from './artifact-files.js';
 import { ARTIFACT_RECEIPTS_DIRECTORY, readArtifactReceipt } from './artifact-receipts.js';
-const skippedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'vendor', 'tmp', 'temp', 'cache']);
 const serial = new Map();
 function digest(text) { return createHash('sha256').update(text).digest('hex'); }
 function artifactId(workspaceId, path) { return `artifact_${digest(`${workspaceId}\0${path}`).slice(0, 40)}`; }
+function outputArtifacts(artifacts) {
+    return artifacts.flatMap(artifact => {
+        const versions = artifact.versions.filter(isWorkspaceArtifactOutputVersion);
+        if (!versions.length)
+            return [];
+        const current = versions.find(version => version.id === artifact.currentVersionId)
+            ?? versions.reduce((latest, version) => version.createdAt > latest.createdAt ? version : latest);
+        return [{ ...artifact, versions, currentVersionId: current.id, updatedAt: current.createdAt }];
+    }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+}
 /** Catalogs and immutable bytes are control-owned, outside the mutable checkout. */
 export class WorkspaceArtifactStore {
     stateDir;
@@ -73,13 +82,13 @@ export class WorkspaceArtifactStore {
     }
     async list() {
         const catalog = await this.read(await this.directory());
-        return workspaceArtifactListSchema.parse({ artifacts: catalog.artifacts, scannedAt: catalog.scannedAt });
+        return workspaceArtifactListSchema.parse({ artifacts: outputArtifacts(catalog.artifacts), scannedAt: catalog.scannedAt });
     }
     async scan(root, source, sourcePaths) {
         const directory = await this.directory();
         const objects = await artifactDirectory(directory, 'objects');
         const catalog = await this.read(directory);
-        const original = JSON.stringify(catalog.artifacts);
+        const original = JSON.stringify(outputArtifacts(catalog.artifacts));
         const receipts = await this.receipts(root, catalog);
         for (const receipt of receipts) {
             try {
@@ -106,12 +115,13 @@ export class WorkspaceArtifactStore {
         const candidates = await discoverPaths(root);
         // Models are inspected before images so their explicitly referenced textures stay under the model.
         candidates.sort((a, b) => Number(artifactFormat(b)?.[0] === 'model') - Number(artifactFormat(a)?.[0] === 'model') || a.localeCompare(b));
-        const members = new Set(catalog.artifacts.flatMap(artifact => artifact.versions.flatMap(version => version.files.filter(file => file.role !== 'primary').map(file => file.path))));
+        const visible = outputArtifacts(catalog.artifacts);
+        const members = new Set(visible.flatMap(artifact => artifact.versions.flatMap(version => version.files.filter(file => file.role !== 'primary').map(file => file.path))));
         for (const path of candidates) {
             if (members.has(path))
                 continue;
             try {
-                const current = catalog.artifacts.find(artifact => artifact.id === artifactId(this.workspaceId, path));
+                const current = visible.find(artifact => artifact.id === artifactId(this.workspaceId, path));
                 const version = current?.versions.find(entry => entry.id === current.currentVersionId);
                 const knownWrite = sourcePaths.includes(path) && Boolean(source.operationId) && version?.source.operationId !== source.operationId;
                 const observation = catalog.observations[path];
@@ -145,13 +155,13 @@ export class WorkspaceArtifactStore {
         }
         catalog.artifacts = catalog.artifacts.filter(artifact => {
             const current = artifact.versions.find(version => version.id === artifact.currentVersionId);
-            return current.source.kind !== 'discovered' || !members.has(current.path);
+            return !isWorkspaceArtifactOutputVersion(current) || current.source.kind !== 'discovered' || !members.has(current.path);
         });
         catalog.artifacts.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
         catalog.scannedAt = new Date().toISOString();
-        const list = workspaceArtifactListSchema.parse({ artifacts: catalog.artifacts, scannedAt: catalog.scannedAt });
+        const list = workspaceArtifactListSchema.parse({ artifacts: outputArtifacts(catalog.artifacts), scannedAt: catalog.scannedAt });
         await this.write(directory, catalog);
-        return { list, changed: original !== JSON.stringify(catalog.artifacts) };
+        return { list, changed: original !== JSON.stringify(list.artifacts) };
     }
     add(catalog, version) {
         const id = artifactId(this.workspaceId, version.path);
@@ -186,7 +196,7 @@ export class WorkspaceArtifactStore {
                 continue;
             try {
                 const receipt = await readArtifactReceipt(join(directory, name));
-                if (receipt.workspaceId === this.workspaceId && `${receipt.id}.json` === name)
+                if (receipt.workspaceId === this.workspaceId && `${receipt.id}.json` === name && isWorkspaceArtifactOutputVersion(receipt))
                     receipts.push(receipt);
             }
             catch { /* Malformed output metadata is never trusted as a completed artifact. */ }
@@ -208,7 +218,7 @@ export class WorkspaceArtifactStore {
         const query = workspaceArtifactContentQuerySchema.parse(input);
         const directory = await this.directory(), catalog = await this.read(directory);
         const artifact = catalog.artifacts.find(item => item.id === query.artifactId);
-        const version = artifact?.versions.find(item => item.id === query.versionId);
+        const version = artifact?.versions.find(item => item.id === query.versionId && isWorkspaceArtifactOutputVersion(item));
         const file = version?.files.find(item => item.path === (query.path ?? version.path));
         if (!file)
             throw new Error('artifact_not_found');
@@ -244,14 +254,26 @@ async function fileSignature(root, paths) {
     }
     return JSON.stringify(records);
 }
-async function discoverPaths(root, directory = '', result = []) {
-    for (const entry of await readdir(join(root, directory), { withFileTypes: true })) {
+async function discoverPaths(root, directory = WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, result = []) {
+    if (directory !== WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY && !isWorkspaceArtifactOutputPath(directory))
+        throw new Error('invalid_artifact_path');
+    let target;
+    try {
+        target = await artifactPath(root, directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return result;
+        throw error;
+    }
+    if (!(await lstat(target)).isDirectory())
+        throw new Error('invalid_artifact_directory');
+    for (const entry of await readdir(target, { withFileTypes: true })) {
         if (entry.name.startsWith('.') || entry.isSymbolicLink())
             continue;
-        const path = directory ? `${directory}/${entry.name}` : entry.name;
+        const path = `${directory}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (!skippedDirectories.has(entry.name))
-                await discoverPaths(root, path, result);
+            await discoverPaths(root, path, result);
         }
         else if (entry.isFile() && artifactFormat(path))
             result.push(path);

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

@@ -4,6 +4,8 @@ import { extname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 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';
 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',
@@ -24,13 +26,13 @@ function attachmentRange(header, size) {
     const end = first === undefined ? size - 1 : Math.min(last ?? size - 1, size - 1);
     return start >= size || start > end ? null : { start, end };
 }
-async function openAttachment(root, id) {
+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 > 8192)
+        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)
@@ -39,6 +41,16 @@ async function openAttachment(root, id) {
     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 {
@@ -56,7 +68,7 @@ async function openAttachment(root, id) {
     }
 }
 /** Serve only registered references; no caller-supplied file paths reach the filesystem. */
-export async function serveWorkspaceAttachment(root, attachmentId, request, response) {
+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' }));
@@ -64,7 +76,7 @@ export async function serveWorkspaceAttachment(root, attachmentId, request, resp
     }
     let content;
     try {
-        content = await openAttachment(root, attachmentId);
+        content = await openAttachment(root, attachmentId, filePath);
     }
     catch {
         response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });

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

@@ -6,6 +6,8 @@ import { WORKSPACE_USER_UPLOADS_DIRECTORY, attachmentIdsSchema, attachmentUpload
 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;
@@ -136,13 +138,17 @@ export async function resolveWorkspaceAttachments(root, input) {
             let metadata;
             try {
                 const stat = await metadataHandle.stat();
-                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 8192)
+                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');

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

@@ -11,6 +11,7 @@ import { readDependencies, scheduleDependencyInstall } from './dependencies.js';
 import { revisionScope } from './registry.js';
 import { ensureWorkspaceSkills } from './skills.js';
 import { checkoutBatchCommit, freezeBatchCommit } from './batch-commit.js';
+import { ensureWorkspaceArtifactInstructions } from './instructions.js';
 const execute = promisify(execFile);
 /** Trusted Runtime registration clones an immutable local commit; it never follows basic's current branch head. */
 export async function registerWorkspaceDirectory(state, input, leaseFence, sourceDirectoryName) {
@@ -68,6 +69,7 @@ export async function registerWorkspaceDirectory(state, input, leaseFence, sourc
                 await rm(staging, { recursive: true, force: true });
             }
         }
+        await ensureWorkspaceArtifactInstructions(root);
         await openDirectoryToDevelopment(root, (await lstat(state.config.workspaceRoot)).gid);
         await state.journal.exclusive(`workspace:${directory.workspaceId}`, async () => {
             state.acceptedLeaseFence = Math.max(state.acceptedLeaseFence, leaseFence);
@@ -87,8 +89,12 @@ export async function restoreWorkspaceDirectory(state, workspaceId, directoryNam
     await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
         const binding = state.journal.getWorkspace(workspaceId);
         const directory = binding?.directories?.find(item => item.directoryName === directoryName);
-        if (!binding || directory?.status !== 'reclaimed')
+        if (!binding)
             return;
+        if (directory?.status !== 'reclaimed') {
+            await ensureWorkspaceArtifactInstructions(await workspaceRoot(state, workspaceId, directoryName));
+            return;
+        }
         if (binding.targetKind === 'standalone' || !state.gitCredentials)
             throw new WorkspaceContextError('workspace_recovery_required');
         const preparation = await state.gitCredentials.prepareDirectory(workspaceId, directoryName);
@@ -98,6 +104,7 @@ export async function restoreWorkspaceDirectory(state, workspaceId, directoryNam
         if (!await lstat(root).catch(() => undefined))
             await prepareWorkspaceCheckout(state, target, preparation, state.acceptedLeaseFence, directoryName, true);
         await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'));
+        await ensureWorkspaceArtifactInstructions(root);
         await openDirectoryToDevelopment(root, (await lstat(state.config.workspaceRoot)).gid);
         await state.journal.putWorkspace({ ...binding, directories: binding.directories?.map(item => item.directoryName === directoryName ? { ...item, status: 'ready' } : item) });
         try {