dsh-webui-studio 0.1.0

package/lib/host/preview.js

@@ -0,0 +1,249 @@
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { STUDIO_PREVIEW_API_PATH } from '../contracts.js';
+import { installDraftDependencies, materializeDraftProfile, terminalCommandLine } from './runtime-profile.js';
+const START_TIMEOUT_MS = 30_000;
+const LOG_LIMIT = 64_000;
+function appendLog(current, chunk) {
+    return `${current}${chunk.toString()}`.slice(-LOG_LIMIT);
+}
+function studioPackageRoot() {
+    return fileURLToPath(new URL('../../', import.meta.url));
+}
+function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise(resolve => {
+        const exited = () => {
+            clearTimeout(timeout);
+            resolve(true);
+        };
+        const timeout = setTimeout(() => {
+            child.removeListener('exit', exited);
+            resolve(false);
+        }, timeoutMs);
+        child.once('exit', exited);
+    });
+}
+export class StudioPreviewSupervisor {
+    draft;
+    mainProfileDir;
+    parentOrigin;
+    commands;
+    harmonyBinEntry;
+    stopTimeoutMs;
+    child;
+    controlToken;
+    runtime = { state: 'stopped', log: '' };
+    startAbort;
+    startPromise;
+    constructor(draft, mainProfileDir, parentOrigin, commands, harmonyBinEntry, stopTimeoutMs = 5_000) {
+        this.draft = draft;
+        this.mainProfileDir = mainProfileDir;
+        this.parentOrigin = parentOrigin;
+        this.commands = commands;
+        this.harmonyBinEntry = harmonyBinEntry;
+        this.stopTimeoutMs = stopTimeoutMs;
+    }
+    snapshot() {
+        return { ...this.runtime };
+    }
+    async start() {
+        if (this.runtime.state === 'running')
+            return this.snapshot();
+        if (this.startPromise !== undefined)
+            return this.startPromise;
+        const abort = new AbortController();
+        const startPromise = this.startRuntime(abort.signal);
+        this.startAbort = abort;
+        this.startPromise = startPromise;
+        try {
+            return await startPromise;
+        }
+        finally {
+            if (this.startPromise === startPromise) {
+                this.startAbort = undefined;
+                this.startPromise = undefined;
+            }
+        }
+    }
+    async startRuntime(signal) {
+        this.runtime = { state: 'starting', log: '[studio] Preparing Draft dependencies and isolated profile\n' };
+        try {
+            await installDraftDependencies(this.draft, this.commands, chunk => { this.runtime.log = appendLog(this.runtime.log, chunk); }, signal);
+            await materializeDraftProfile(this.draft, this.mainProfileDir, studioPackageRoot(), this.commands, chunk => { this.runtime.log = appendLog(this.runtime.log, chunk); }, signal);
+            signal.throwIfAborted();
+            const hostArgs = [this.harmonyBinEntry, 'web', '--port', '0'];
+            this.runtime.log = appendLog(this.runtime.log, `[studio] Profile dependencies ready\n[studio] Starting Preview Host\nDSH_HOME=${this.draft.runtimeHome}\n${terminalCommandLine(this.draft.worktreeDir, process.execPath, hostArgs)}`);
+            const controlToken = randomBytes(32).toString('hex');
+            const bridgeCapability = randomBytes(24).toString('base64url');
+            this.controlToken = controlToken;
+            const child = spawn(process.execPath, hostArgs, {
+                cwd: this.draft.worktreeDir,
+                env: {
+                    ...process.env,
+                    DSH_HOME: this.draft.runtimeHome,
+                    DSH_STUDIO_PREVIEW_DRAFT_ROOT: this.draft.root,
+                    DSH_STUDIO_PREVIEW_CONTROL_TOKEN: controlToken,
+                    DSH_STUDIO_PREVIEW_PARENT_ORIGIN: this.parentOrigin,
+                    DSH_STUDIO_PREVIEW_BRIDGE_CAPABILITY: bridgeCapability,
+                    DSH_HARMONY_REACT_TRACE: '1',
+                },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            this.child = child;
+            child.stdout?.on('data', chunk => {
+                this.runtime.log = appendLog(this.runtime.log, chunk);
+                const match = this.runtime.log.match(/dsh web:\s+(http:\/\/127\.0\.0\.1:\d+)/);
+                if (match?.[1] !== undefined) {
+                    this.runtime = {
+                        ...this.runtime,
+                        state: 'running',
+                        previewUrl: `${match[1]}/#dsh-studio-preview=${encodeURIComponent(bridgeCapability)}`,
+                        bridgeCapability,
+                        error: undefined,
+                    };
+                }
+            });
+            child.stderr?.on('data', chunk => { this.runtime.log = appendLog(this.runtime.log, chunk); });
+            child.once('exit', (code, signal) => {
+                if (this.child !== child)
+                    return;
+                this.child = undefined;
+                this.controlToken = undefined;
+                if (this.runtime.state === 'stopped')
+                    return;
+                const error = `Preview Host exited (${signal ?? code ?? 'unknown'})`;
+                this.runtime = { state: 'failed', error, log: this.runtime.log };
+            });
+            await this.waitUntilRunning(child, signal);
+            await this.waitForWorker(child, signal);
+            await this.worker('state', {}, signal);
+            return this.snapshot();
+        }
+        catch (error) {
+            await this.terminateChild();
+            if (signal.aborted) {
+                this.runtime = { state: 'stopped', log: this.runtime.log };
+                throw signal.reason;
+            }
+            this.runtime = { state: 'failed', error: error instanceof Error ? error.message : String(error), log: this.runtime.log };
+            throw error;
+        }
+    }
+    async stop() {
+        this.startAbort?.abort(new Error('Preview start canceled'));
+        const start = this.startPromise;
+        this.controlToken = undefined;
+        this.runtime = { state: 'stopped', log: this.runtime.log };
+        await this.terminateChild();
+        if (start !== undefined) {
+            try {
+                await start;
+            }
+            catch { }
+        }
+        this.controlToken = undefined;
+        this.runtime = { state: 'stopped', log: this.runtime.log };
+        return this.snapshot();
+    }
+    async terminateChild() {
+        const child = this.child;
+        if (child !== undefined && child.exitCode === null) {
+            child.kill('SIGTERM');
+            if (!await waitForExit(child, this.stopTimeoutMs)) {
+                child.kill('SIGKILL');
+                if (!await waitForExit(child, this.stopTimeoutMs)) {
+                    const error = 'Preview Host did not exit after SIGTERM and SIGKILL';
+                    this.runtime = { state: 'failed', error, log: this.runtime.log };
+                    throw new Error(error);
+                }
+            }
+        }
+        if (this.child === child)
+            this.child = undefined;
+    }
+    async state() {
+        return (await this.worker('state', {})).project;
+    }
+    async activate(graphRev) {
+        return (await this.worker('activate', { graphRev })).project;
+    }
+    async applyBuild() {
+        return (await this.worker('apply-build', {})).project;
+    }
+    async inspect(input = {}) {
+        return this.worker('inspect', input);
+    }
+    async resolveSource(source) {
+        return this.worker('resolve-source', { source });
+    }
+    async readDependencySource(packageName, file) {
+        return this.worker('read-source', { package: packageName, file });
+    }
+    async dispose() {
+        await this.stop();
+    }
+    async waitUntilRunning(child, signal) {
+        const started = Date.now();
+        while (this.child === child && this.runtime.state === 'starting' && Date.now() - started < START_TIMEOUT_MS) {
+            await this.delay(50, signal);
+        }
+        signal.throwIfAborted();
+        if (this.runtime.state !== 'running')
+            throw new Error(this.runtime.error ?? 'Preview Host did not publish its URL before timeout');
+    }
+    async waitForWorker(child, signal) {
+        const started = Date.now();
+        let lastError = 'worker route was not reachable';
+        while (this.child === child && Date.now() - started < START_TIMEOUT_MS) {
+            try {
+                const requestSignal = AbortSignal.any([signal, AbortSignal.timeout(1_000)]);
+                await this.worker('health', {}, requestSignal);
+                return;
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                lastError = error instanceof Error ? error.message : String(error);
+                await this.delay(50, signal);
+            }
+        }
+        signal.throwIfAborted();
+        throw new Error(`Preview worker did not become ready before timeout: ${lastError}`);
+    }
+    async worker(method, payload, signal) {
+        if (this.runtime.previewUrl === undefined || this.controlToken === undefined)
+            throw new Error('Preview Host is not running');
+        const endpoint = new URL(`${STUDIO_PREVIEW_API_PATH}/${method}`, this.runtime.previewUrl);
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${this.controlToken}`, 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal,
+        });
+        const text = await response.text();
+        if (text === '')
+            throw new Error(`Preview worker returned an empty HTTP ${response.status} response`);
+        const body = JSON.parse(text);
+        if (!response.ok || !body.ok)
+            throw new Error(body.ok ? `Preview worker failed with HTTP ${response.status}` : body.error);
+        return body.value;
+    }
+    async delay(milliseconds, signal) {
+        signal.throwIfAborted();
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(done, milliseconds);
+            const aborted = () => done(signal.reason);
+            function done(error) {
+                clearTimeout(timeout);
+                signal.removeEventListener('abort', aborted);
+                if (error === undefined)
+                    resolve();
+                else
+                    reject(error);
+            }
+            signal.addEventListener('abort', aborted, { once: true });
+        });
+    }
+}

package/lib/host/project-files.d.ts

@@ -0,0 +1,8 @@
+export interface StudioProjectFile {
+    path: string;
+    size: number;
+}
+export declare function listProjectFiles(root: string): Promise<StudioProjectFile[]>;
+export declare function readProjectFile(root: string, path: string): Promise<string>;
+export declare function writeProjectFile(root: string, path: string, content: string): Promise<void>;
+export declare function applyProjectPatch(root: string, path: string, before: string, after: string): Promise<'created' | 'updated'>;

package/lib/host/project-files.js

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, readFile, readdir, realpath, rename, unlink, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+const MAX_FILE_BYTES = 1024 * 1024;
+const SKIP_DIRECTORIES = new Set(['.git', 'node_modules']);
+function inside(root, target) {
+    const path = relative(root, target);
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+function relativePath(input) {
+    if (input === '' || isAbsolute(input) || input.includes('\\'))
+        throw new Error('path must be a relative project path');
+    const parts = input.split('/');
+    if (parts.some(part => part === '' || part === '.' || part === '..'))
+        throw new Error('path contains an invalid segment');
+    return parts.join(sep);
+}
+async function projectRoot(root) {
+    return realpath(root);
+}
+async function existingPath(root, input) {
+    const base = await projectRoot(root);
+    const target = await realpath(resolve(base, relativePath(input)));
+    if (!inside(base, target))
+        throw new Error('path escapes the Draft root');
+    return target;
+}
+export async function listProjectFiles(root) {
+    const base = await projectRoot(root);
+    const files = [];
+    const walk = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRECTORIES.has(entry.name))
+                    await walk(absolute);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const info = await lstat(absolute);
+            files.push({ path: relative(base, absolute).split(sep).join('/'), size: info.size });
+        }
+    };
+    await walk(base);
+    return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+export async function readProjectFile(root, path) {
+    const target = await existingPath(root, path);
+    const info = await lstat(target);
+    if (!info.isFile())
+        throw new Error('path does not point to a file');
+    if (info.size > MAX_FILE_BYTES)
+        throw new Error('file exceeds the 1 MiB Studio limit');
+    const content = await readFile(target);
+    if (content.includes(0))
+        throw new Error('binary files cannot be opened in Studio');
+    return content.toString('utf8');
+}
+export async function writeProjectFile(root, path, content) {
+    if (Buffer.byteLength(content) > MAX_FILE_BYTES)
+        throw new Error('file exceeds the 1 MiB Studio limit');
+    const base = await projectRoot(root);
+    const target = resolve(base, relativePath(path));
+    if (!inside(base, target))
+        throw new Error('path escapes the Draft root');
+    const parent = await realpath(resolve(target, '..'));
+    if (!inside(base, parent))
+        throw new Error('path parent escapes the Draft root');
+    try {
+        if ((await lstat(target)).isSymbolicLink())
+            throw new Error('Studio does not write through symbolic links');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temporary = join(parent, `.${randomUUID()}.dsh-studio.tmp`);
+    try {
+        await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+export async function applyProjectPatch(root, path, before, after) {
+    let source;
+    try {
+        source = await readProjectFile(root, path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        if (before !== '')
+            throw new Error('cannot patch a missing file unless before is empty');
+        await writeProjectFile(root, path, after);
+        return 'created';
+    }
+    const first = source.indexOf(before);
+    if (first === -1)
+        throw new Error('patch before text was not found');
+    if (source.indexOf(before, first + before.length) !== -1)
+        throw new Error('patch before text is not unique');
+    await writeProjectFile(root, path, `${source.slice(0, first)}${after}${source.slice(first + before.length)}`);
+    return 'updated';
+}

package/lib/host/readiness.d.ts

@@ -0,0 +1,11 @@
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import type { StudioHarmonyInspection, StudioPackResult, StudioReadinessReport, StudioPatchDependency } from '../contracts.js';
+export declare function inspectReadiness(root: string, projectName: string, inspection: StudioHarmonyInspection, profileDir: string, dependencies?: StudioPatchDependency[]): StudioReadinessReport;
+export declare class StudioPackRunner {
+    private readonly subprocess;
+    private readonly timeoutMs;
+    private active?;
+    constructor(subprocess: SubprocessRuntime, timeoutMs?: number);
+    run(root: string): Promise<StudioPackResult>;
+    dispose(): Promise<void>;
+}

package/lib/host/readiness.js

@@ -0,0 +1,247 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+const PACK_TIMEOUT_MS = 120_000;
+const OUTPUT_LIMIT_BYTES = 256 * 1024;
+function finding(level, code, message, fields = {}) {
+    return { level, code, message, ...fields };
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function exportPath(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    return exportPath(record.import) ?? exportPath(record.default) ?? exportPath(record.require);
+}
+function clientExport(manifest) {
+    if (typeof manifest.exports !== 'object' || manifest.exports === null)
+        return undefined;
+    return exportPath(manifest.exports['./client']);
+}
+function rootExport(manifest) {
+    if (typeof manifest.main === 'string')
+        return manifest.main;
+    if (typeof manifest.exports !== 'object' || manifest.exports === null)
+        return undefined;
+    return exportPath(manifest.exports['.']);
+}
+function within(root, path) {
+    const remainder = relative(root, path);
+    return remainder === '' || (!remainder.startsWith('..') && !isAbsolute(remainder));
+}
+function artifactFinding(root, path, label) {
+    const target = resolve(root, path);
+    if (!within(root, target))
+        return finding('error', 'artifact-escapes-root', `${label} ${JSON.stringify(path)} escapes the Draft root`, { file: path });
+    if (!existsSync(target))
+        return finding('error', 'artifact-missing', `${label} ${JSON.stringify(path)} does not exist; build the Draft before publishing`, { file: path });
+    return undefined;
+}
+function readManifest(root) {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+}
+export function inspectReadiness(root, projectName, inspection, profileDir, dependencies = []) {
+    const manifest = readManifest(root);
+    const findings = [];
+    if (typeof manifest.name !== 'string' || manifest.name === '') {
+        findings.push(finding('error', 'manifest-name', 'package.json must declare a non-empty name', { file: 'package.json' }));
+    }
+    else if (manifest.name !== projectName) {
+        findings.push(finding('error', 'manifest-identity', `package.json name must remain ${JSON.stringify(projectName)}`, { file: 'package.json' }));
+    }
+    if (typeof manifest.version !== 'string' || manifest.version === '') {
+        findings.push(finding('error', 'manifest-version', 'package.json must declare a publishable version', { file: 'package.json' }));
+    }
+    if (manifest.dsh?.client?.platform !== 'web') {
+        findings.push(finding('error', 'client-platform', 'dsh.client.platform must be "web"', { file: 'package.json' }));
+    }
+    if (typeof manifest.scripts?.build !== 'string' || manifest.scripts.build.trim() === '') {
+        findings.push(finding('error', 'build-script', 'package.json must declare a non-empty scripts.build', { file: 'package.json' }));
+    }
+    const client = clientExport(manifest);
+    if (client === undefined) {
+        findings.push(finding('error', 'client-export', 'package.json must export "./client"', { file: 'package.json' }));
+    }
+    else {
+        const missing = artifactFinding(root, client, 'Client export');
+        if (missing !== undefined)
+            findings.push(missing);
+    }
+    if (typeof manifest.exports !== 'object' || manifest.exports === null
+        || manifest.exports['./package.json'] === undefined) {
+        findings.push(finding('error', 'package-json-export', 'package.json must export "./package.json" for DSH Client discovery', { file: 'package.json' }));
+    }
+    const host = rootExport(manifest);
+    if (host === undefined) {
+        findings.push(finding('error', 'host-export', 'package.json must expose a root Host entry through main or exports["."]', { file: 'package.json' }));
+    }
+    else {
+        const missing = artifactFinding(root, host, 'Host export');
+        if (missing !== undefined)
+            findings.push(missing);
+    }
+    for (const [path, label] of [[manifest.types, 'Types entry']]) {
+        if (typeof path !== 'string')
+            continue;
+        const missing = artifactFinding(root, path, label);
+        if (missing !== undefined)
+            findings.push(missing);
+    }
+    const harmony = manifest.dsh?.harmony;
+    const patchFiles = stringArray(harmony?.patches);
+    if (harmony?.patches !== undefined && (!Array.isArray(harmony.patches) || patchFiles.length !== harmony.patches.length)) {
+        findings.push(finding('error', 'patch-manifest', 'dsh.harmony.patches must contain only file paths', { file: 'package.json' }));
+    }
+    for (const path of patchFiles) {
+        const target = resolve(root, path);
+        if (!within(root, target)) {
+            findings.push(finding('error', 'patch-escapes-root', `Harmony patch ${JSON.stringify(path)} escapes the Draft root`, { file: path }));
+            continue;
+        }
+        if (!existsSync(target)) {
+            findings.push(finding('error', 'patch-file-missing', `Harmony patch ${JSON.stringify(path)} does not exist`, { file: path }));
+            continue;
+        }
+        if (!within(realpathSync(root), realpathSync(target))) {
+            findings.push(finding('error', 'patch-symlink-escape', `Harmony patch ${JSON.stringify(path)} resolves outside the Draft root`, { file: path }));
+        }
+    }
+    const declared = new Set([...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.peerDependencies ?? {})]);
+    const declaredAfter = new Set(stringArray(harmony?.after));
+    for (const dependency of stringArray(manifest.dsh?.client?.inject)) {
+        if (!declared.has(dependency)) {
+            findings.push(finding('warning', 'ambient-client-service', `Client inject ${JSON.stringify(dependency)} is supplied by the current profile but is not declared as a dependency or peer dependency`));
+        }
+    }
+    for (const dependency of [...stringArray(harmony?.before), ...stringArray(harmony?.after), ...stringArray(harmony?.conflicts)]) {
+        if (!declared.has(dependency)) {
+            findings.push(finding('warning', 'ambient-provider', `Harmony provider ${JSON.stringify(dependency)} affects ordering or compatibility but is not declared as a dependency or peer dependency`));
+        }
+    }
+    const patches = inspection.patches.filter(patch => patch.owner === projectName);
+    for (const patch of patches) {
+        if (!declared.has(patch.target.package)) {
+            findings.push(finding('warning', 'ambient-patch-target', `Patch target ${JSON.stringify(patch.target.package)} is available in this Preview but is not declared as a dependency or peer dependency`, { patch: patch.key }));
+        }
+        if (patch.target.version === undefined) {
+            findings.push(finding('warning', 'unbounded-target-version', `Patch ${JSON.stringify(patch.key)} does not constrain the target package version`, { patch: patch.key }));
+        }
+        if (patch.state === 'failed') {
+            findings.push(finding('error', 'patch-failed', patch.error ?? `Patch ${JSON.stringify(patch.key)} failed against the current provider stack`, { patch: patch.key, file: patch.file }));
+        }
+        else if (patch.state === 'disabled') {
+            findings.push(finding('warning', 'patch-disabled', `Patch ${JSON.stringify(patch.key)} is disabled in the current profile`, { patch: patch.key, file: patch.file }));
+        }
+        else if (patch.state === 'pending' || !patch.loaded) {
+            findings.push(finding('warning', 'patch-unverified', `Patch ${JSON.stringify(patch.key)} has not been exercised by the current Preview`, { patch: patch.key, file: patch.file }));
+        }
+    }
+    for (const dependency of dependencies) {
+        const explicit = dependency.providerCandidates.filter(provider => declared.has(provider) && declaredAfter.has(provider));
+        if (dependency.providerCandidates.length === 1 && explicit.length === 1)
+            continue;
+        findings.push(finding('warning', 'differential-provider-stack', `Patch ${JSON.stringify(dependency.patch)} fails against the base target but succeeds against the current transformed stack. Earlier provider candidates: ${dependency.providerCandidates.map(provider => JSON.stringify(provider)).join(', ')}. Inspect the ordered Patch steps before declaring a dependency or dsh.harmony.after relationship`, { patch: dependency.patch, file: dependency.target.file }));
+    }
+    const orderPath = join(profileDir, 'harmony.json');
+    if (existsSync(orderPath)) {
+        const order = JSON.parse(readFileSync(orderPath, 'utf8')).order;
+        if (Array.isArray(order) && order.every((item) => typeof item === 'string')) {
+            const position = new Map(order.map((name, index) => [name, index]));
+            for (const target of stringArray(harmony?.before)) {
+                if ((position.get(projectName) ?? -1) > (position.get(target) ?? Number.MAX_SAFE_INTEGER)) {
+                    findings.push(finding('info', 'effective-order', `Current Preview places ${projectName} after ${target}, contrary to its before declaration`));
+                }
+            }
+            for (const target of stringArray(harmony?.after)) {
+                if ((position.get(target) ?? -1) > (position.get(projectName) ?? Number.MAX_SAFE_INTEGER)) {
+                    findings.push(finding('info', 'effective-order', `Current Preview places ${projectName} before ${target}, contrary to its after declaration`));
+                }
+            }
+        }
+    }
+    const rank = { error: 0, warning: 1, info: 2 };
+    findings.sort((left, right) => rank[left.level] - rank[right.level] || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
+    return { findings };
+}
+function outputOf(handle, argv) {
+    const stdout = handle.collected.stdout?.readFrom(0);
+    const stderr = handle.collected.stderr?.readFrom(0);
+    return {
+        ok: false,
+        argv,
+        files: [],
+        stdout: stdout?.text ?? '',
+        stderr: stderr?.text ?? '',
+        truncated: stdout?.lossy === true || stderr?.lossy === true,
+    };
+}
+export class StudioPackRunner {
+    subprocess;
+    timeoutMs;
+    active;
+    constructor(subprocess, timeoutMs = PACK_TIMEOUT_MS) {
+        this.subprocess = subprocess;
+        this.timeoutMs = timeoutMs;
+    }
+    async run(root) {
+        if (this.active !== undefined)
+            throw new Error('a package dry-run is already running');
+        const controller = new AbortController();
+        const active = { controller };
+        this.active = active;
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const argv = ['npm', 'pack', '--dry-run', '--json', '--ignore-scripts'];
+        let handle;
+        try {
+            argv[0] = await this.subprocess.resolveExecutable('npm', undefined, controller.signal);
+            handle = this.subprocess.spawn({
+                argv,
+                cwd: root,
+                stdio: {
+                    stdin: 'ignore',
+                    stdout: { maxBytes: OUTPUT_LIMIT_BYTES },
+                    stderr: { maxBytes: OUTPUT_LIMIT_BYTES },
+                },
+                graceMs: 2_000,
+                signal: controller.signal,
+            });
+            active.handle = handle;
+            const outcome = await handle.done;
+            const output = outputOf(handle, argv);
+            if (outcome.exitCode !== 0)
+                return output;
+            try {
+                const records = JSON.parse(output.stdout);
+                if (!Array.isArray(records) || records.length !== 1 || !Array.isArray(records[0]?.files)) {
+                    return { ...output, stderr: `${output.stderr}${output.stderr === '' ? '' : '\n'}npm pack returned an unexpected JSON result` };
+                }
+                return {
+                    ...output,
+                    ok: true,
+                    files: records[0].files.flatMap(file => typeof file.path === 'string' ? [file.path] : []).sort(),
+                };
+            }
+            catch (error) {
+                return { ...output, stderr: `${output.stderr}${output.stderr === '' ? '' : '\n'}${error instanceof Error ? error.message : String(error)}` };
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            if (controller.signal.aborted && handle !== undefined)
+                await handle.waitForExit();
+            if (this.active === active)
+                this.active = undefined;
+        }
+    }
+    async dispose() {
+        const active = this.active;
+        if (active === undefined)
+            return;
+        active.controller.abort();
+        if (active.handle !== undefined)
+            await active.handle.waitForExit();
+    }
+}

package/lib/host/routes.d.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { StudioBackend } from './backend.js';
+export interface StudioAssets {
+    script: Buffer;
+    style: Buffer;
+    bridge: Buffer;
+    icon: Buffer;
+    iconMono: Buffer;
+}
+export interface StudioRouteSecurity {
+    token: string;
+    origin: string;
+    host: string;
+}
+export declare function isTrustedStudioRequest(request: IncomingMessage): boolean;
+export declare function createStudioRoutes(backend: StudioBackend, assets: StudioAssets, security: StudioRouteSecurity): WebRoute[];