@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace-runtime/workspaces/delivery-build.js

@@ -0,0 +1,421 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { copyFile, cp, chmod, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { createPlatformAdapter, getChannelRuleProfile, } from '@playcraft/build';
+import { DELIVERY_QUEUE_LIMIT, isWorkspaceArtifactOutputPath, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot } from './registry.js';
+import { excludeFromGit, ensureWorkspaceDependencies } from './dependencies.js';
+import { listWorkspaceBuildInputs } from './git.js';
+import { runDeveloperCommand } from './developer-command.js';
+import { openScratchToDevelopment } from './directory-access.js';
+import { DeliveryStore } from './delivery-store.js';
+import { DeliveryValidationError, validateDeliveryArtifact } from './delivery.js';
+export const DELIVERY_BUILD_TIMEOUT_MS = 10 * 60_000;
+/** Staging under the workspace from earlier runtimes; kept out of Git so leftovers never commit. */
+const STAGING_DIRECTORY = '.playcraft-delivery';
+/** Never copied into the build copy: history, outputs and caches that the build neither reads nor owns. */
+const ISOLATE_SKIP = new Set(['.git', 'dist', '.turbo', STAGING_DIRECTORY]);
+export class DeliveryBuildError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'DeliveryBuildError';
+    }
+}
+const queues = new WeakMap();
+const running = new WeakMap();
+export function trackDeliveryBuild(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 settleDeliveryBuilds(state) {
+    await Promise.all([...(running.get(state) ?? [])]);
+}
+const scopeKey = (workspaceId, directoryName) => `${workspaceId}\0${directoryName}`;
+function buildQueues(state) {
+    const known = queues.get(state) ?? new Map();
+    queues.set(state, known);
+    return known;
+}
+function queuedRecord(input, createdAt, queuePosition) {
+    return {
+        buildId: input.buildId,
+        workspaceId: input.workspaceId,
+        directoryName: input.directoryName,
+        channel: input.payload.channel,
+        format: input.payload.format,
+        status: 'queued',
+        ...(input.actor ? { actor: input.actor } : {}),
+        queuePosition,
+        createdAt,
+    };
+}
+async function refreshQueuedRecords(state, key) {
+    const queue = buildQueues(state).get(key);
+    if (!queue)
+        return;
+    const waiting = queue.queue.filter(item => !item.started && !item.canceled);
+    const workspaceId = waiting[0]?.input.workspaceId ?? queue.active?.pending.input.workspaceId;
+    if (!workspaceId)
+        return;
+    const store = new DeliveryStore(state.config.stateDir, workspaceId);
+    await Promise.all(waiting.map((item, index) => {
+        if (item.started || item.canceled)
+            return Promise.resolve();
+        return store.write(queuedRecord(item.input, item.createdAt, index + 1)).catch(() => undefined);
+    }));
+}
+function pump(state, key, queue) {
+    if (queue.active)
+        return;
+    const next = queue.queue.shift();
+    if (!next)
+        return;
+    next.started = true;
+    queue.active = { buildId: next.input.buildId, pending: next };
+    void executeBuild(state, next.input, next.controller)
+        .then(outcome => next.resolve(outcome), error => next.reject(error))
+        .finally(() => {
+        queue.active = undefined;
+        pump(state, key, queue);
+        void refreshQueuedRecords(state, key);
+    });
+}
+export function runDeliveryBuild(state, input) {
+    if (input.directoryName === 'root')
+        return Promise.reject(new DeliveryBuildError('invalid_workspace_directory'));
+    const key = scopeKey(input.workspaceId, input.directoryName);
+    const scopes = buildQueues(state);
+    const queue = scopes.get(key) ?? { queue: [] };
+    if ((queue.active ? 1 : 0) + queue.queue.length >= DELIVERY_QUEUE_LIMIT) {
+        return Promise.reject(new DeliveryBuildError('delivery_queue_full'));
+    }
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    const pending = {
+        input,
+        controller: new AbortController(),
+        promise,
+        resolve,
+        reject,
+        createdAt: new Date().toISOString(),
+        canceled: false,
+        started: false,
+    };
+    queue.queue.push(pending);
+    scopes.set(key, queue);
+    pump(state, key, queue);
+    void refreshQueuedRecords(state, key);
+    return promise;
+}
+export async function cancelDeliveryBuild(state, workspaceId, directoryName, buildId) {
+    const key = scopeKey(workspaceId, directoryName);
+    const queue = buildQueues(state).get(key);
+    if (!queue)
+        return false;
+    if (queue.active?.buildId === buildId) {
+        queue.active.pending.controller.abort();
+        return true;
+    }
+    const index = queue.queue.findIndex(item => item.input.buildId === buildId);
+    if (index < 0)
+        return false;
+    const [pending] = queue.queue.splice(index, 1);
+    if (!pending)
+        return false;
+    pending.canceled = true;
+    const record = {
+        ...queuedRecord(pending.input, pending.createdAt, 0),
+        status: 'canceled',
+        finishedAt: new Date().toISOString(),
+        error: 'delivery_canceled',
+    };
+    await new DeliveryStore(state.config.stateDir, workspaceId).write(record).catch(() => undefined);
+    pending.resolve({ record });
+    void refreshQueuedRecords(state, key);
+    return true;
+}
+export function activeDeliveryBuild(state, workspaceId, directoryName) {
+    return buildQueues(state).get(scopeKey(workspaceId, directoryName))?.active?.buildId;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function outputExtension(format) {
+    return format === 'zip' ? '.zip' : '.html';
+}
+async function listStagedFiles(staging, prefix = '') {
+    const entries = await readdir(join(staging, prefix), { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.isSymbolicLink() || entry.name.startsWith('.'))
+            continue;
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...await listStagedFiles(staging, relative));
+            if (files.length > 512)
+                throw new DeliveryBuildError('delivery_output_missing');
+        }
+        else if (entry.isFile()) {
+            files.push(relative);
+        }
+    }
+    return files;
+}
+function choosePrimary(files, format) {
+    const extension = outputExtension(format);
+    const candidates = files.filter(file => file.toLowerCase().endsWith(extension));
+    if (!candidates.length)
+        throw new DeliveryBuildError('delivery_output_missing');
+    const preferred = format === 'zip' ? 'playable.zip' : 'index.html';
+    return candidates.find(file => basename(file).toLowerCase() === preferred) ?? candidates[0];
+}
+/**
+ * Copies a single artifact, or the whole staging tree for fragment/mixed channels. Each file is
+ * staged next to its final name and renamed, so a partially written package never appears in dist.
+ */
+async function copyToDist(root, staging, channel, format) {
+    const files = await listStagedFiles(staging);
+    const primary = choosePrimary(files, format);
+    const mode = getChannelRuleProfile(channel).deliveryMode;
+    const selected = files.length > 1 && (mode === 'fragment-assets' || mode === 'mixed') ? files : [primary];
+    const paths = [];
+    let sizeBytes = 0;
+    for (const file of selected) {
+        const relative = `dist/delivery/${channel}/${file}`;
+        if (!isWorkspaceArtifactOutputPath(relative))
+            throw new DeliveryBuildError('delivery_output_missing');
+        const target = join(root, relative);
+        const directory = dirname(target);
+        await mkdir(directory, { recursive: true });
+        const temporary = join(directory, `.${basename(file)}.${randomUUID()}.tmp`);
+        try {
+            await copyFile(join(staging, file), temporary);
+            await rename(temporary, target);
+        }
+        catch {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw new DeliveryBuildError('delivery_copy_failed');
+        }
+        sizeBytes += (await stat(target)).size;
+        paths.push(relative);
+    }
+    return { primary: `dist/delivery/${channel}/${primary}`, paths, sizeBytes };
+}
+/** Copy-on-write clone where the filesystem supports it (APFS, btrfs, XFS); a plain copy elsewhere. */
+const CLONE = constants.COPYFILE_FICLONE;
+const COPY_CONCURRENCY = 16;
+function skipped(path) {
+    const parts = path.split(/[\\/]/);
+    return ISOLATE_SKIP.has(parts[0]) || parts.includes('node_modules');
+}
+async function copyInput(root, destination, path) {
+    const source = join(root, path);
+    const target = join(destination, path);
+    let entry;
+    try {
+        entry = await lstat(source);
+    }
+    catch (error) {
+        // A tracked file deleted in the work tree is not a build input.
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    if (entry.isSymbolicLink())
+        await symlink(await readlink(source), target);
+    else if (entry.isDirectory())
+        await cp(source, target, { recursive: true, verbatimSymlinks: true, mode: CLONE });
+    else
+        await copyFile(source, target, CLONE);
+}
+/**
+ * Copies the workspace into `destination` for one build, like the platform export runner, with the
+ * top-level `node_modules` linked (the build only reads it). Builders rewrite project files in place
+ * (`builds.config.js` and its `.bak`, `package.json` scripts, migrated imports), so the build must
+ * never run in the workspace itself, where autosave would commit those rewrites.
+ *
+ * Only the files Git would carry are copied: tracked ones and untracked ones `.gitignore` keeps, so
+ * caches, logs and local outputs stay behind. Without a repository the whole tree is copied.
+ */
+export async function isolateWorkspaceForBuild(root, destination) {
+    await mkdir(destination, { recursive: true });
+    // The build runs as the development identity and writes its scratch folder inside this copy.
+    await chmod(destination, 0o2770);
+    const modules = join(root, 'node_modules');
+    const modulesEntry = await lstat(modules).catch(() => undefined);
+    if (modulesEntry?.isDirectory() || modulesEntry?.isSymbolicLink()) {
+        await symlink(modulesEntry.isSymbolicLink() ? await readlink(modules) : modules, join(destination, 'node_modules'), 'dir');
+    }
+    const inputs = await listWorkspaceBuildInputs(root).catch(() => undefined);
+    const paths = inputs
+        ?? (await readdir(root)).filter((name) => name !== 'node_modules');
+    const queue = paths.filter((path) => !skipped(path));
+    const workers = Array.from({ length: Math.min(COPY_CONCURRENCY, queue.length) }, async () => {
+        for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+            if (inputs)
+                await copyInput(root, destination, path);
+            else {
+                await cp(join(root, path), join(destination, path), {
+                    recursive: true,
+                    verbatimSymlinks: true,
+                    mode: CLONE,
+                    // Nested dependency folders stay out as well; the build resolves through the linked root.
+                    filter: (source) => !relative(join(root, path), source).split(sep).includes('node_modules'),
+                });
+            }
+        }
+    });
+    await Promise.all(workers);
+}
+/**
+ * Runs one channel build in a disposable copy of the workspace. The build writes into a disposable
+ * output directory; only the final artifact is copied into dist so the builder's `--clean` can never
+ * erase another delivery.
+ */
+async function executeBuild(state, input, controller) {
+    if (input.directoryName === 'root')
+        throw new DeliveryBuildError('invalid_workspace_directory');
+    const root = await workspaceRoot(state, input.workspaceId, input.directoryName);
+    const store = new DeliveryStore(state.config.stateDir, input.workspaceId);
+    const startedAt = new Date().toISOString();
+    const base = {
+        buildId: input.buildId,
+        workspaceId: input.workspaceId,
+        directoryName: input.directoryName,
+        channel: input.payload.channel,
+        format: input.payload.format,
+        status: 'running',
+        ...(input.actor ? { actor: input.actor } : {}),
+        createdAt: startedAt,
+        startedAt,
+    };
+    await store.write(base);
+    let scratch;
+    let staging = '';
+    let status = 'running';
+    let error;
+    let validationError;
+    let outputPath;
+    let outputPaths;
+    let sizeBytes;
+    let sizeLimitBytes;
+    let report;
+    let logChain = Promise.resolve();
+    let record;
+    try {
+        scratch = await mkdtemp(join(tmpdir(), 'playcraft-delivery-'));
+        // The build runs as the development identity while this scratch tree belongs to the controller.
+        await openScratchToDevelopment(scratch, (await lstat(root)).gid);
+        staging = join(scratch, 'output');
+        const project = join(scratch, 'project');
+        await mkdir(staging, { recursive: true });
+        await chmod(staging, 0o2770);
+        await excludeFromGit(root, `/${STAGING_DIRECTORY}/`);
+        await excludeFromGit(root, '/dist/');
+        const dependencies = await ensureWorkspaceDependencies(state, input.workspaceId, root);
+        if (!dependencies.ok) {
+            if (dependencies.logTail) {
+                await store.appendLog(input.buildId, `\n${dependencies.logTail}\n`);
+            }
+            throw new DeliveryBuildError('delivery_dependencies_failed');
+        }
+        try {
+            await isolateWorkspaceForBuild(root, project);
+        }
+        catch {
+            throw new DeliveryBuildError('delivery_isolation_failed');
+        }
+        const planned = process.env.PLAYCRAFT_DELIVERY_BUILD_COMMAND || 'playcraft build';
+        const command = `umask 002 && NO_COLOR=1 CI=1 ${planned} . --platform ${input.payload.channel} --format ${input.payload.format} --output ${shellQuote(staging)} --mode full`;
+        const outcome = await runDeveloperCommand(state, {
+            processId: `delivery-${input.buildId}`,
+            cwd: project,
+            command,
+            timeoutMs: DELIVERY_BUILD_TIMEOUT_MS,
+            signal: controller.signal,
+            onOutput: (chunk) => {
+                const text = String(chunk);
+                if (!text)
+                    return;
+                logChain = logChain.then(() => store.appendLog(input.buildId, text)).catch(() => undefined);
+            },
+        });
+        if (outcome.canceled) {
+            status = 'canceled';
+            error = 'delivery_canceled';
+        }
+        else if (outcome.timedOut) {
+            status = 'failed';
+            error = 'delivery_timeout';
+        }
+        else if (outcome.code !== 0) {
+            status = 'failed';
+            error = 'delivery_build_failed';
+        }
+        else {
+            const output = await copyToDist(root, staging, input.payload.channel, input.payload.format);
+            outputPath = output.primary;
+            outputPaths = output.paths;
+            sizeBytes = output.sizeBytes;
+            sizeLimitBytes = createPlatformAdapter({
+                platform: input.payload.channel,
+                format: input.payload.format,
+            }).getSizeLimit();
+            try {
+                const result = await validateDeliveryArtifact(root, {
+                    channel: input.payload.channel,
+                    format: input.payload.format,
+                    path: outputPath,
+                });
+                report = result.report;
+                sizeLimitBytes = result.sizeLimitBytes;
+            }
+            catch (cause) {
+                validationError = cause instanceof DeliveryValidationError ? cause.code : 'delivery_report_unavailable';
+            }
+            status = 'succeeded';
+        }
+    }
+    catch (cause) {
+        status = 'failed';
+        error = cause instanceof DeliveryBuildError ? cause.code : 'delivery_build_failed';
+    }
+    finally {
+        // `rm` removes the node_modules link, never its target.
+        if (scratch)
+            await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
+        await logChain;
+        if (report) {
+            await store.writeReport(input.buildId, report).catch(() => {
+                validationError = validationError ?? 'delivery_report_unavailable';
+            });
+        }
+        const recordValue = {
+            ...base,
+            status,
+            finishedAt: new Date().toISOString(),
+            ...(outputPath ? { outputPath } : {}),
+            ...(outputPaths && outputPaths.length > 1 ? { outputPaths } : {}),
+            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+            ...(sizeLimitBytes !== undefined ? { sizeLimitBytes } : {}),
+            ...(report ? { summary: report.summary, buildChain: report.buildChain } : {}),
+            ...(error ? { error } : {}),
+            ...(validationError ? { validationError } : {}),
+            logBytes: await store.logBytes(input.buildId),
+        };
+        record = recordValue;
+        await store.write(recordValue);
+    }
+    return { record, ...(report ? { report } : {}) };
+}

package/dist/workspace-runtime/workspaces/delivery-store.js

@@ -0,0 +1,168 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { deliveryBuildRecordSchema, deliveryValidationReportSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { AppendOnlyLog } from './append-only-log.js';
+export const DELIVERY_LOG_MAX_BYTES = 2 * 1024 * 1024;
+export const DELIVERY_RECORD_LIMIT = 20;
+const BUILD_ID_PATTERN = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+function assertBuildId(buildId) {
+    if (!BUILD_ID_PATTERN.test(buildId))
+        throw new Error('invalid_delivery_build_id');
+}
+function workspaceDirectory(stateDir, workspaceId) {
+    return join(stateDir, 'deliveries', createHash('sha256').update(workspaceId).digest('hex'));
+}
+/** Control-owned delivery history; never written inside the checkout. */
+export class DeliveryStore {
+    stateDir;
+    workspaceId;
+    directory;
+    constructor(stateDir, workspaceId) {
+        this.stateDir = stateDir;
+        this.workspaceId = workspaceId;
+        this.directory = workspaceDirectory(stateDir, workspaceId);
+    }
+    async ready() {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        return this.directory;
+    }
+    recordPath(buildId) {
+        assertBuildId(buildId);
+        return join(this.directory, `${buildId}.json`);
+    }
+    reportPath(buildId) {
+        assertBuildId(buildId);
+        return join(this.directory, `${buildId}.report.json`);
+    }
+    logPath(buildId) {
+        assertBuildId(buildId);
+        return join(this.directory, `${buildId}.log`);
+    }
+    async writeJson(path, value) {
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
+            await rename(temporary, path);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async write(record) {
+        const parsed = deliveryBuildRecordSchema.parse(record);
+        await this.ready();
+        await this.writeJson(this.recordPath(parsed.buildId), parsed);
+        await this.prune(parsed.channel);
+    }
+    async read(buildId) {
+        await this.ready();
+        try {
+            const value = JSON.parse(await readFile(this.recordPath(buildId), 'utf8'));
+            const parsed = deliveryBuildRecordSchema.safeParse(value);
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async readAll() {
+        await this.ready();
+        const names = await readdir(this.directory);
+        const records = [];
+        for (const name of names) {
+            if (!/^[a-f0-9-]{36}\.json$/i.test(name))
+                continue;
+            const record = await this.read(name.slice(0, -'.json'.length));
+            if (record)
+                records.push(record);
+        }
+        return records;
+    }
+    async list(directoryName, channel, limit = DELIVERY_RECORD_LIMIT) {
+        const records = (await this.readAll())
+            .filter(record => record.directoryName === directoryName && (!channel || record.channel === channel))
+            .sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.buildId.localeCompare(left.buildId));
+        return records.slice(0, Math.min(Math.max(limit, 1), 50));
+    }
+    async writeReport(buildId, report) {
+        const parsed = deliveryValidationReportSchema.parse(report);
+        await this.ready();
+        await this.writeJson(this.reportPath(buildId), parsed);
+    }
+    async readReport(buildId) {
+        await this.ready();
+        try {
+            const value = JSON.parse(await readFile(this.reportPath(buildId), 'utf8'));
+            const parsed = deliveryValidationReportSchema.safeParse(value);
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    log(buildId) {
+        return new AppendOnlyLog(this.logPath(buildId), DELIVERY_LOG_MAX_BYTES, '[playcraft] delivery log truncated; showing the tail\n');
+    }
+    async appendLog(buildId, chunk) {
+        await this.ready();
+        await this.log(buildId).append(chunk);
+    }
+    async readLog(buildId, offset = 0) {
+        await this.ready();
+        return this.log(buildId).read(offset);
+    }
+    async logBytes(buildId) {
+        return this.log(buildId).size();
+    }
+    async prune(channel) {
+        const records = (await this.readAll())
+            .filter(record => record.channel === channel)
+            .sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.buildId.localeCompare(left.buildId));
+        if (records.length <= DELIVERY_RECORD_LIMIT)
+            return;
+        for (const record of records.slice(DELIVERY_RECORD_LIMIT)) {
+            await Promise.all([
+                rm(this.recordPath(record.buildId), { force: true }),
+                rm(this.reportPath(record.buildId), { force: true }),
+                rm(this.logPath(record.buildId), { force: true }),
+            ]);
+        }
+    }
+}
+/** A runtime restart leaves no build process behind; mark their records instead of showing them as running. */
+export async function recoverInterruptedDeliveries(stateDir) {
+    const root = join(stateDir, 'deliveries');
+    const buckets = await readdir(root, { withFileTypes: true }).catch(() => []);
+    for (const bucket of buckets) {
+        if (!bucket.isDirectory())
+            continue;
+        const directory = join(root, bucket.name);
+        const names = await readdir(directory).catch(() => []);
+        for (const name of names) {
+            if (!/^[a-f0-9-]{36}\.json$/i.test(name) || name.endsWith('.report.json'))
+                continue;
+            let record;
+            try {
+                const parsed = deliveryBuildRecordSchema.safeParse(JSON.parse(await readFile(join(directory, name), 'utf8')));
+                record = parsed.success ? parsed.data : undefined;
+            }
+            catch {
+                continue;
+            }
+            if (!record || !['queued', 'running'].includes(record.status))
+                continue;
+            await new DeliveryStore(stateDir, record.workspaceId).write({
+                ...record,
+                status: 'interrupted',
+                error: 'delivery_interrupted',
+                finishedAt: new Date().toISOString(),
+            });
+        }
+    }
+}

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

@@ -0,0 +1,64 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createPlatformAdapter, EngineDetector, runPlayableValidation, } from '@playcraft/build';
+import { deliveryValidateResultSchema, isWorkspaceArtifactOutputPath, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from './artifact-files.js';
+export class DeliveryValidationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'DeliveryValidationError';
+    }
+}
+function buildChain(buildTool) {
+    if (buildTool === 'playable-scripts')
+        return 'devkit';
+    if (buildTool === 'playcanvas-native')
+        return 'playcanvas-native';
+    return 'generic';
+}
+/**
+ * Validates an already-built artifact in the workspace's dist directory. It never builds: the
+ * delivery UI uses it to re-check a file the user or the Agent produced.
+ */
+export async function validateDeliveryArtifact(root, payload) {
+    if (!isWorkspaceArtifactOutputPath(payload.path))
+        throw new DeliveryValidationError('invalid_delivery_path');
+    let absolute;
+    try {
+        absolute = await artifactPath(root, payload.path);
+    }
+    catch {
+        throw new DeliveryValidationError('delivery_output_missing');
+    }
+    const info = await stat(absolute).catch(() => undefined);
+    if (!info?.isFile())
+        throw new DeliveryValidationError('delivery_output_missing');
+    const detection = await EngineDetector.detectFull(root).catch(() => ({
+        engine: 'generic',
+        buildTool: 'generic',
+    }));
+    const stages = payload.format === 'zip' ? ['delivery-package'] : ['html-artifact'];
+    let report;
+    try {
+        report = await runPlayableValidation({
+            projectRoot: root,
+            channel: payload.channel,
+            engine: detection.engine,
+            buildTool: detection.buildTool,
+            buildChain: buildChain(detection.buildTool),
+            ...(payload.format === 'zip' ? { packagePath: absolute } : { htmlPath: absolute }),
+            outputDir: path.dirname(absolute),
+        }, stages);
+    }
+    catch {
+        throw new DeliveryValidationError('delivery_validation_failed');
+    }
+    const adapter = createPlatformAdapter({ platform: payload.channel, format: payload.format });
+    return deliveryValidateResultSchema.parse({
+        report,
+        sizeBytes: info.size,
+        sizeLimitBytes: adapter.getSizeLimit(),
+    });
+}