dsh-webui-studio 0.1.0

package/lib/host/drafts.js

@@ -0,0 +1,394 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { chmod, copyFile, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const PACKAGE_NAME = /^(?:@[a-z0-9._~-]+\/)?[a-z0-9._~-]+$/;
+const COMMAND_OUTPUT_LIMIT = 2 * 1024 * 1024;
+export const studioCommands = {
+    run(command, args, cwd, onOutput, signal) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], signal });
+            let output = '';
+            const read = (chunk) => {
+                const text = chunk.toString();
+                output = `${output}${text}`.slice(-COMMAND_OUTPUT_LIMIT);
+                onOutput?.(text);
+            };
+            child.stdout.on('data', read);
+            child.stderr.on('data', read);
+            child.once('error', reject);
+            child.once('close', (code, signal) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`Command exited with ${code === null ? signal ?? 'a signal' : `code ${code}`}\n${output.trimEnd()}`));
+            });
+        });
+    },
+};
+function templateManifest(name) {
+    return `${JSON.stringify({
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        packageManager: 'npm@10.0.0',
+        exports: { '.': './lib/index.js', './client': './lib/client.js', './package.json': './package.json' },
+        scripts: { build: 'node --check lib/index.js && node --check lib/client.js' },
+        dsh: { client: { platform: 'web' }, harmony: { patches: [] } },
+    }, null, 2)}\n`;
+}
+function templateClient(name) {
+    return `window.__ModuleLoader__.load({
+  id: ${JSON.stringify(name)},
+  factory: () => ({
+    apply() {},
+  }),
+})
+`;
+}
+async function pluginManifest(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Plugin folder must contain a readable package.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof manifest.name !== 'string' || !PACKAGE_NAME.test(manifest.name)) {
+        throw new Error('Plugin package.json must declare a valid npm package name');
+    }
+    if (manifest.dsh?.client?.platform !== 'web') {
+        throw new Error('Plugin package.json must declare dsh.client.platform as "web"');
+    }
+    if (typeof manifest.exports !== 'object' || manifest.exports === null
+        || !Object.hasOwn(manifest.exports, '.') || !Object.hasOwn(manifest.exports, './client')) {
+        throw new Error('Plugin package.json exports must include "." and "./client"');
+    }
+    if (typeof manifest.scripts?.build !== 'string' || manifest.scripts.build.trim() === '') {
+        throw new Error('Plugin package.json must declare a non-empty scripts.build');
+    }
+    return manifest;
+}
+async function copyPluginDirectory(source, target) {
+    const info = await lstat(source);
+    if (info.isSymbolicLink())
+        throw new Error(`Plugin snapshot does not include symbolic links: ${source}`);
+    if (info.isDirectory()) {
+        try {
+            const targetInfo = await lstat(target);
+            if (targetInfo.isSymbolicLink() || !targetInfo.isDirectory()) {
+                throw new Error(`Plugin destination must contain only regular files and directories: ${target}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await mkdir(target, { mode: info.mode, recursive: true });
+        }
+        const entries = await readdir(source, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === '.git' || entry.name === 'node_modules')
+                continue;
+            await copyPluginDirectory(join(source, entry.name), join(target, entry.name));
+        }
+        return;
+    }
+    if (!info.isFile())
+        throw new Error(`Plugin snapshot only supports regular files and directories: ${source}`);
+    try {
+        const targetInfo = await lstat(target);
+        if (targetInfo.isSymbolicLink() || !targetInfo.isFile()) {
+            throw new Error(`Plugin destination must contain only regular files and directories: ${target}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await copyFile(source, target);
+    await chmod(target, info.mode);
+}
+const PRESERVED_EXPORT_ENTRIES = ['.git', 'node_modules'];
+async function replacePluginDirectory(source, target, targetExists) {
+    const parent = dirname(target);
+    const suffix = randomUUID();
+    const staging = join(parent, `.${basename(target)}.${suffix}.dsh-studio.tmp`);
+    const backup = join(parent, `.${basename(target)}.${suffix}.dsh-studio.backup`);
+    let movedTarget = false;
+    let committed = false;
+    try {
+        await copyPluginDirectory(source, staging);
+        if (targetExists) {
+            for (const entry of PRESERVED_EXPORT_ENTRIES) {
+                const info = await pathInfo(join(target, entry));
+                if (info?.isSymbolicLink())
+                    throw new Error(`Local plugin folder contains an unsafe symbolic link: ${entry}`);
+            }
+            await rename(target, backup);
+            movedTarget = true;
+            for (const entry of PRESERVED_EXPORT_ENTRIES) {
+                if (await pathInfo(join(backup, entry)) !== undefined) {
+                    await rename(join(backup, entry), join(staging, entry));
+                }
+            }
+        }
+        await rename(staging, target);
+        committed = true;
+        if (movedTarget)
+            await rm(backup, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (movedTarget && !committed) {
+            for (const entry of PRESERVED_EXPORT_ENTRIES) {
+                if (await pathInfo(join(staging, entry)) !== undefined) {
+                    await rename(join(staging, entry), join(backup, entry));
+                }
+            }
+            if (await pathInfo(target) === undefined)
+                await rename(backup, target);
+        }
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function pathInfo(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function inside(root, target) {
+    const path = relative(root, target);
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+async function validateDestinationDirectory(input, studioRoot) {
+    if (input === undefined)
+        return undefined;
+    if (typeof input !== 'string' || input.trim() === '')
+        throw new Error('Local plugin folder is required');
+    const requested = input.trim();
+    if (!isAbsolute(requested))
+        throw new Error('Local plugin folder must be an absolute path');
+    const requestedPath = resolve(requested);
+    let canonicalParent;
+    try {
+        canonicalParent = await realpath(dirname(requestedPath));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new Error('The parent of the local plugin folder must already exist');
+        throw error;
+    }
+    const target = join(canonicalParent, basename(requestedPath));
+    if (inside(await realpath(studioRoot), target))
+        throw new Error('Local plugin folder must be outside the Studio data directory');
+    const info = await pathInfo(target);
+    if (info?.isSymbolicLink() || (info !== undefined && !info.isDirectory())) {
+        throw new Error('Local plugin folder must be a directory and cannot be a symbolic link');
+    }
+    if (info !== undefined && (await readdir(target)).length > 0) {
+        throw new Error('Local plugin folder must be new or empty');
+    }
+    return target;
+}
+async function initializeRepository(root, name, commands) {
+    await mkdir(join(root, 'lib'), { recursive: true });
+    await writeFile(join(root, 'package.json'), templateManifest(name));
+    await writeFile(join(root, 'lib/index.js'), 'export const name = "draft-host"\nexport function apply() {}\n');
+    await writeFile(join(root, 'lib/client.js'), templateClient(name));
+    await writeFile(join(root, 'README.md'), `# ${name}\n\nCreated by dsh-webui-studio.\n`);
+    await commands.run('git', ['init', '--initial-branch=main'], root);
+    await commands.run('git', ['add', '.'], root);
+    await commands.run('git', ['-c', 'user.name=dsh-webui-studio', '-c', 'user.email=studio@localhost', 'commit', '-m', 'Initial Draft'], root);
+}
+function nextNewPluginLabel(records) {
+    const labels = new Set(records.map(record => record.label));
+    for (let index = records.filter(record => record.source.kind === 'new').length + 1;; index += 1) {
+        const label = `新插件_${index}`;
+        if (!labels.has(label))
+            return label;
+    }
+}
+export class StudioDraftRegistry {
+    commands;
+    root;
+    recordsDir;
+    repositoriesDir;
+    worktreesDir;
+    runtimesDir;
+    recordMutations = new Map();
+    constructor(dshHome, commands = studioCommands) {
+        this.commands = commands;
+        this.root = join(dshHome, 'studio');
+        this.recordsDir = join(this.root, 'drafts');
+        this.repositoriesDir = join(this.root, 'repositories');
+        this.worktreesDir = join(this.root, 'worktrees');
+        this.runtimesDir = join(this.root, 'runtimes');
+    }
+    async list() {
+        await mkdir(this.recordsDir, { recursive: true });
+        const files = (await readdir(this.recordsDir)).filter(file => file.endsWith('.json')).sort();
+        return Promise.all(files.map(async (file) => JSON.parse(await readFile(join(this.recordsDir, file), 'utf8'))));
+    }
+    async get(id) {
+        if (!/^[a-f0-9-]{36}$/.test(id))
+            throw new Error('invalid Draft id');
+        return JSON.parse(await readFile(join(this.recordsDir, `${id}.json`), 'utf8'));
+    }
+    async create(input) {
+        if (input.profileMode === 'custom')
+            throw new Error('Custom Draft profiles are not implemented yet');
+        const id = randomUUID();
+        const repositoryDir = join(this.repositoriesDir, id);
+        const worktreeDir = join(this.worktreesDir, id);
+        const runtimeHome = join(this.runtimesDir, id, 'dsh-home');
+        await Promise.all([
+            mkdir(this.recordsDir, { recursive: true }),
+            mkdir(this.repositoriesDir, { recursive: true }),
+            mkdir(this.worktreesDir, { recursive: true }),
+            mkdir(dirname(runtimeHome), { recursive: true }),
+        ]);
+        try {
+            let name;
+            let label;
+            let source;
+            let destinationDirectory;
+            if (input.source.kind === 'new') {
+                const packageName = input.source.packageName;
+                if (typeof packageName !== 'string' || !PACKAGE_NAME.test(packageName))
+                    throw new Error('New Draft package name is invalid');
+                name = packageName;
+                label = nextNewPluginLabel(await this.list());
+                source = { kind: 'new', packageName };
+                destinationDirectory = await validateDestinationDirectory(input.destinationDirectory, this.root);
+                await mkdir(repositoryDir);
+                await initializeRepository(repositoryDir, packageName, this.commands);
+                await this.commands.run('git', ['worktree', 'add', '-b', `dsh-studio/${id}`, worktreeDir, 'HEAD'], repositoryDir);
+            }
+            else {
+                if (input.destinationDirectory !== undefined)
+                    throw new Error('Only new plugins can have a local destination folder');
+                if (typeof input.source.directory !== 'string' || input.source.directory.trim() === '') {
+                    throw new Error('Existing plugin folder is required');
+                }
+                const directory = input.source.directory.trim();
+                if (!isAbsolute(directory))
+                    throw new Error('Existing plugin folder must be an absolute path');
+                const canonicalSource = await realpath(directory);
+                if (!(await lstat(canonicalSource)).isDirectory())
+                    throw new Error('Existing plugin path must be a directory');
+                const manifest = await pluginManifest(canonicalSource);
+                name = manifest.name;
+                label = basename(canonicalSource);
+                source = { kind: 'existing', directory: canonicalSource };
+                await mkdir(repositoryDir);
+                await copyPluginDirectory(canonicalSource, repositoryDir);
+                await this.commands.run('git', ['init', '--initial-branch=main'], repositoryDir);
+                await this.commands.run('git', ['add', '.'], repositoryDir);
+                await this.commands.run('git', [
+                    '-c', 'user.name=dsh-webui-studio', '-c', 'user.email=studio@localhost',
+                    'commit', '-m', 'Import plugin snapshot',
+                ], repositoryDir);
+                await this.commands.run('git', ['worktree', 'add', '-b', `dsh-studio/${id}`, worktreeDir, 'HEAD'], repositoryDir);
+            }
+            const canonicalWorktree = await realpath(worktreeDir);
+            const root = canonicalWorktree;
+            const record = {
+                id,
+                name,
+                label,
+                source,
+                ...(destinationDirectory === undefined ? {} : { destinationDirectory }),
+                repositoryDir: await realpath(repositoryDir),
+                worktreeDir: canonicalWorktree,
+                root,
+                runtimeHome,
+                profileMode: input.profileMode,
+                createdAt: new Date().toISOString(),
+            };
+            await writeFile(join(this.recordsDir, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
+            return record;
+        }
+        catch (error) {
+            const cleanup = await Promise.allSettled([
+                rm(worktreeDir, { recursive: true, force: true }),
+                rm(repositoryDir, { recursive: true, force: true }),
+                rm(dirname(runtimeHome), { recursive: true, force: true }),
+            ]);
+            const cleanupErrors = cleanup.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+            if (cleanupErrors.length > 0)
+                throw new AggregateError([error, ...cleanupErrors], 'Draft creation failed and cleanup was incomplete');
+            throw error;
+        }
+    }
+    async rename(id, label) {
+        const nextLabel = label.trim();
+        if (nextLabel === '' || nextLabel.length > 120)
+            throw new Error('Draft name must contain 1 to 120 characters');
+        return this.mutate(id, record => ({ ...record, label: nextLabel }));
+    }
+    async export(id) {
+        return this.mutate(id, async (record) => {
+            const sourceManifest = JSON.parse(await readFile(join(record.root, 'package.json'), 'utf8'));
+            if (sourceManifest.name !== record.name) {
+                throw new Error(`Draft package.json name must remain ${JSON.stringify(record.name)}`);
+            }
+            const target = record.destinationDirectory;
+            if (target === undefined)
+                throw new Error('This Draft does not have a local plugin folder');
+            const info = await pathInfo(target);
+            if (record.exportedAt === undefined) {
+                if (info?.isSymbolicLink() || (info !== undefined && !info.isDirectory())) {
+                    throw new Error('Local plugin folder must be a directory and cannot be a symbolic link');
+                }
+                if (info !== undefined && (await readdir(target)).length > 0) {
+                    throw new Error('Local plugin folder is no longer empty; choose another folder');
+                }
+            }
+            else {
+                if (info?.isSymbolicLink() || info === undefined || !info.isDirectory()) {
+                    throw new Error('The saved local plugin folder is missing or is no longer a regular directory');
+                }
+                const manifest = await pluginManifest(target);
+                if (manifest.name !== record.name)
+                    throw new Error('The local plugin folder now belongs to a different package');
+            }
+            await replacePluginDirectory(record.root, target, info !== undefined);
+            return { ...record, exportedAt: new Date().toISOString() };
+        });
+    }
+    async mutate(id, update) {
+        const previous = this.recordMutations.get(id)?.catch(() => undefined) ?? Promise.resolve();
+        let release;
+        const turn = new Promise(resolve => { release = resolve; });
+        const queued = previous.then(() => turn);
+        this.recordMutations.set(id, queued);
+        await previous;
+        try {
+            const next = await update(await this.get(id));
+            await this.replace(next);
+            return next;
+        }
+        finally {
+            release();
+            if (this.recordMutations.get(id) === queued)
+                this.recordMutations.delete(id);
+        }
+    }
+    async replace(record) {
+        const file = join(this.recordsDir, `${record.id}.json`);
+        const temporary = join(this.recordsDir, `.${record.id}.${randomUUID()}.tmp`);
+        await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
+        await rename(temporary, file);
+    }
+}
+export function dshHomeFromProfile(profileDir) {
+    if (basename(dirname(profileDir)) !== 'profiles')
+        throw new Error('Harmony profile is not under a DSH_HOME/profiles directory');
+    return dirname(dirname(profileDir));
+}

package/lib/host/preview-worker.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type StudioHarmonyService } from '../contracts.js';
+interface PreviewWorkerOptions {
+    root: string;
+    controlToken: string;
+    parentOrigin: string;
+    bridgeCapability: string;
+    bridge: Buffer;
+}
+export declare function applyPreviewWorker(ctx: Context, harmony: StudioHarmonyService, options: PreviewWorkerOptions): void;
+export {};

package/lib/host/preview-worker.js

@@ -0,0 +1,110 @@
+import { STUDIO_PATH, STUDIO_PREVIEW_API_PATH, } from '../contracts.js';
+import { StudioSourceResolver } from './source-resolution.js';
+function loopback(request) {
+    const address = request.socket.remoteAddress;
+    return address === '::1' || address === '127.0.0.1' || address?.startsWith('::ffff:127.') === true;
+}
+function json(response, status, body) {
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(body));
+}
+async function readJson(request) {
+    const chunks = [];
+    for await (const chunk of request)
+        chunks.push(Buffer.from(chunk));
+    if (Buffer.concat(chunks).byteLength > 1024 * 1024)
+        throw new Error('request body is too large');
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export function applyPreviewWorker(ctx, harmony, options) {
+    ctx.effect(() => {
+        let handle;
+        const ready = harmony.prepareDraft({ root: options.root }).then(value => { handle = value; return value; });
+        const sources = new StudioSourceResolver(options.root, harmony.profileDir);
+        const worker = {
+            kind: 'prefix',
+            path: STUDIO_PREVIEW_API_PATH,
+            async handler(request, response) {
+                if (!loopback(request) || request.headers.authorization !== `Bearer ${options.controlToken}`) {
+                    return json(response, 403, { ok: false, error: 'invalid Preview worker capability' });
+                }
+                if (request.method !== 'POST')
+                    return json(response, 405, { ok: false, error: 'method not allowed' });
+                try {
+                    const payload = await readJson(request);
+                    const method = new URL(request.url ?? '/', 'http://localhost').pathname.slice(`${STUDIO_PREVIEW_API_PATH}/`.length);
+                    if (method === 'health')
+                        return json(response, 200, { ok: true, value: { ready: true } });
+                    const draft = await ready;
+                    if (method === 'state')
+                        return json(response, 200, { ok: true, value: { project: draft.snapshot() } });
+                    if (method === 'activate') {
+                        if (typeof payload.graphRev !== 'string')
+                            throw new Error('graphRev is required');
+                        return json(response, 200, { ok: true, value: { project: await draft.activateAfterPreviewReady(payload.graphRev) } });
+                    }
+                    if (method === 'apply-build') {
+                        return json(response, 200, { ok: true, value: { project: await draft.applyBuild() } });
+                    }
+                    if (method === 'inspect') {
+                        const packageName = typeof payload.package === 'string' ? payload.package : undefined;
+                        const file = typeof payload.file === 'string' ? payload.file : undefined;
+                        return json(response, 200, {
+                            ok: true,
+                            value: {
+                                harmony: harmony.inspect({ ...(packageName === undefined ? {} : { package: packageName }), ...(file === undefined ? {} : { file }) }),
+                                dependencies: harmony.inspectDependencies(draft.snapshot().name),
+                            },
+                        });
+                    }
+                    if (method === 'resolve-source') {
+                        const source = payload.source;
+                        if (typeof source?.file !== 'string' || source.file === ''
+                            || (source.line !== undefined && (!Number.isInteger(source.line) || source.line < 1))
+                            || (source.column !== undefined && (!Number.isInteger(source.column) || source.column < 1))) {
+                            throw new Error('source location is invalid');
+                        }
+                        return json(response, 200, { ok: true, value: await sources.resolve(source) });
+                    }
+                    if (method === 'read-source') {
+                        if (typeof payload.package !== 'string' || typeof payload.file !== 'string') {
+                            throw new Error('dependency package and file are required');
+                        }
+                        return json(response, 200, {
+                            ok: true,
+                            value: await sources.readDependency(payload.package, payload.file),
+                        });
+                    }
+                    return json(response, 404, { ok: false, error: `unknown Preview worker method ${method}` });
+                }
+                catch (error) {
+                    return json(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        };
+        const bridge = {
+            kind: 'exact',
+            path: `${STUDIO_PATH}/bridge.js`,
+            handler(request, response) {
+                if (!loopback(request))
+                    return json(response, 403, { error: 'Preview is local only' });
+                response.writeHead(200, { 'cache-control': 'no-cache', 'content-type': 'text/javascript; charset=utf-8' });
+                response.end(request.method === 'HEAD' ? undefined : options.bridge);
+            },
+        };
+        const dispose = [ctx.webServer.register(worker), ctx.webServer.register(bridge), ctx.webServer.tapIndex(html => {
+                const config = `<script>window.__DSH_STUDIO_PREVIEW__=${JSON.stringify({
+                    parentOrigin: options.parentOrigin,
+                    capability: options.bridgeCapability,
+                })}</script><script src="${STUDIO_PATH}/bridge.js"></script>`;
+                const head = html.indexOf('<head>');
+                return head === -1 ? `${config}${html}` : `${html.slice(0, head + 6)}${config}${html.slice(head + 6)}`;
+            })];
+        return async () => {
+            for (const stop of dispose.reverse())
+                stop();
+            await ready.catch(() => undefined);
+            await handle?.deactivate();
+        };
+    }, 'harmony-studio: Preview worker');
+}

package/lib/host/preview.d.ts

@@ -0,0 +1,42 @@
+import type { StudioDraftRecord, StudioPreviewInspection, StudioProjectState, StudioSourceCandidate, StudioSourceLocation } from '../contracts.js';
+import type { StudioCommandRunner } from './drafts.js';
+export interface StudioPreviewRuntime {
+    state: 'stopped' | 'starting' | 'running' | 'failed';
+    previewUrl?: string;
+    bridgeCapability?: string;
+    error?: string;
+    log: string;
+}
+export declare class StudioPreviewSupervisor {
+    readonly draft: StudioDraftRecord;
+    private readonly mainProfileDir;
+    private readonly parentOrigin;
+    private readonly commands;
+    private readonly harmonyBinEntry;
+    private readonly stopTimeoutMs;
+    private child?;
+    private controlToken?;
+    private runtime;
+    private startAbort?;
+    private startPromise?;
+    constructor(draft: StudioDraftRecord, mainProfileDir: string, parentOrigin: string, commands: StudioCommandRunner, harmonyBinEntry: string, stopTimeoutMs?: number);
+    snapshot(): StudioPreviewRuntime;
+    start(): Promise<StudioPreviewRuntime>;
+    private startRuntime;
+    stop(): Promise<StudioPreviewRuntime>;
+    private terminateChild;
+    state(): Promise<StudioProjectState>;
+    activate(graphRev: string): Promise<StudioProjectState>;
+    applyBuild(): Promise<StudioProjectState>;
+    inspect(input?: {
+        package?: string;
+        file?: string;
+    }): Promise<StudioPreviewInspection>;
+    resolveSource(source: StudioSourceLocation): Promise<StudioSourceCandidate>;
+    readDependencySource(packageName: string, file: string): Promise<string>;
+    dispose(): Promise<void>;
+    private waitUntilRunning;
+    private waitForWorker;
+    private worker;
+    private delay;
+}