@joplo-app/server 0.0.0-stage → 0.1.1

package/dist/dev.js

@@ -0,0 +1,667 @@
+/**
+ * `joplo dev`：本机只运行一个看板进程（D39），同时服务多个项目。
+ *
+ * - 界面：一个 Vite 开发服务（packages/web 源码或 @joplo-app/web 的 dist），HMR。
+ * - 项目：每个项目一个不监听端口的 Vite 加载器（middlewareMode），ssrLoadModule 载入作者 TSX →
+ *   core.loadAuthoring → core.compile(…, 'dev')。项目按需编译：首页选中、打开演示页或注册时才启动。
+ * - 热更新：界面服务的文件监听覆盖所有已启动的项目目录；某个项目的文件变化 → 只重新编译这个项目 →
+ *   HMR 自定义事件 `joplo:ir`（带 projectId）推送，看板只接收当前项目的事件。
+ * - 记住项目：`<JOPLO_HOME>/projects.json`；运行中的看板：`<JOPLO_HOME>/server.json`（见 home.ts）。
+ *   createDev 缺省不持久化（renderStep、测试）；startDev（CLI）持久化，并在已有存活看板时只注册、不启动第二个进程。
+ *
+ * 安全（沿用 M0）：只监听 127.0.0.1；每个请求校验 Host；写接口校验 Origin、Content-Type 与本地令牌。
+ * 端口被占用时直接报错（strictPort），不静默换端口。
+ */
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import tailwindcss from '@tailwindcss/vite';
+import { createLogger, createServer } from 'vite';
+import { JoploError } from '@joplo-app/core';
+import { ExportHub } from "./export.js";
+import { Registry, clearServerInfo, joploHome, normalizeSettings, pidAlive, projectIdOf, readServerInfo, readSettings, writeServerInfo, writeSettings } from "./home.js";
+import { compileProject, invalidateProjectModules } from "./project.js";
+import { SelectionBody, readSelection, resolveSelection, writeSelection } from "./selection.js";
+import { IGNORED_DIRS, cssSourcePlugin, isProjectSource, joploProjectPlugin, kitAliases, locateWebAssets, realProjectDir } from "./vite-shared.js";
+export const IR_EVENT = 'joplo:ir';
+export const PROJECTS_EVENT = 'joplo:projects';
+const MAX_BODY = 64 * 1024;
+const SECURITY_HEADERS = {
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'cache-control': 'no-store',
+};
+export function sendJson(res, status, body) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && crypto.timingSafeEqual(ab, bb);
+}
+/** Content-Type 必须是 application/json，只允许附带 charset=utf-8 参数。 */
+export function isJsonContentType(ct) {
+    if (!ct)
+        return false;
+    const [type, ...params] = ct.split(';').map((x) => x.trim().toLowerCase());
+    return type === 'application/json' && params.every((p) => p === '' || /^charset="?utf-8"?$/.test(p));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_BODY * 16) {
+                req.destroy();
+                reject(new Error('请求体过大'));
+            }
+            else if (size <= MAX_BODY)
+                chunks.push(c);
+        });
+        req.on('end', () => resolve(size > MAX_BODY ? { tooLarge: true } : { tooLarge: false, text: Buffer.concat(chunks).toString('utf8') }));
+        req.on('error', reject);
+    });
+}
+function makeLogger(log) {
+    const base = createLogger('warn', { allowClearScreen: false });
+    return {
+        ...base,
+        info: () => undefined,
+        warn: (msg) => log(`[joplo] ${msg}`),
+        warnOnce: (msg) => log(`[joplo] ${msg}`),
+        error: (msg) => log(`[joplo] ${msg}`),
+        clearScreen: () => undefined,
+    };
+}
+const MIME = {
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.json': 'application/json; charset=utf-8',
+};
+/** dist 形态：/assets/* 原样返回预构建文件（不经过 Vite 的模块转换）。返回 true 表示已处理。 */
+function serveDistAsset(web, pathname, res) {
+    if (!pathname.startsWith('/assets/'))
+        return false;
+    const assets = path.join(web.appDir, 'assets');
+    let rel;
+    try {
+        rel = decodeURIComponent(pathname.slice('/assets/'.length));
+    }
+    catch {
+        return false;
+    }
+    const file = path.resolve(assets, rel);
+    if (!file.startsWith(assets + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile())
+        return false;
+    res.writeHead(200, { 'content-type': MIME[path.extname(file)] ?? 'application/octet-stream', 'x-content-type-options': 'nosniff', 'cache-control': 'public, max-age=31536000, immutable' });
+    fs.createReadStream(file).pipe(res);
+    return true;
+}
+/** dist 形态：在看板入口脚本之前创建 HMR 句柄、导入作者 className 的 CSS。 */
+export function injectDistBoot(html, web) {
+    const css = '/@fs/' + web.projectCss.split(path.sep).join('/').replace(/^\/+/, '');
+    const boot = `<script type="module">import { createHotContext } from '/@vite/client';\nimport ${JSON.stringify(css)};\nglobalThis.__JOPLO_HOT__ = createHotContext('/@joplo-app/board');</script>`;
+    const at = html.search(/<script\b/i);
+    return at < 0 ? html.replace('</head>', `${boot}\n</head>`) : html.slice(0, at) + boot + '\n    ' + html.slice(at);
+}
+async function webPlugins(web) {
+    if (web.mode === 'dist')
+        return [tailwindcss()];
+    // 只有在仓库里编译看板源码时才需要 React 插件（devDependency）
+    const { default: react } = await import('@vitejs/plugin-react');
+    return [react(), tailwindcss()];
+}
+/** 不持久化时的项目记录（只在内存里，进程结束即消失）。 */
+class MemoryRegistry {
+    items = [];
+    list() {
+        return [...this.items].sort((a, b) => b.lastOpened.localeCompare(a.lastOpened));
+    }
+    touch(dir, name) {
+        const prev = this.items.find((p) => p.dir === dir);
+        const rec = { dir, name: name ?? prev?.name ?? path.basename(dir), lastOpened: new Date().toISOString() };
+        this.items = [rec, ...this.items.filter((p) => p.dir !== dir)];
+        return rec;
+    }
+    rename(dir, name) {
+        const rec = this.items.find((p) => p.dir === dir);
+        if (rec)
+            rec.name = name;
+    }
+    remove(dir) {
+        const n = this.items.length;
+        this.items = this.items.filter((p) => p.dir !== dir);
+        return this.items.length !== n;
+    }
+}
+const projectUrl = (base, id) => `${base}#/${encodeURIComponent(id)}`;
+export async function createHub(opts = {}) {
+    const log = opts.log ?? ((m) => process.stderr.write(m + '\n'));
+    const watch = opts.watch !== false;
+    const port = opts.port ?? 4790;
+    const token = crypto.randomBytes(24).toString('hex');
+    const web = locateWebAssets();
+    const registry = opts.home ? new Registry(opts.home) : new MemoryRegistry();
+    let memSettings = { version: 1 };
+    const slots = new Map();
+    let actualPort = port;
+    let closed = false;
+    let server;
+    const allowedHosts = () => new Set([`127.0.0.1:${actualPort}`, `localhost:${actualPort}`]);
+    const allowedOrigins = () => new Set([`http://127.0.0.1:${actualPort}`, `http://localhost:${actualPort}`]);
+    const baseUrl = () => `http://127.0.0.1:${actualPort}/`;
+    const activeDirs = () => [...slots.values()].filter((s) => !s.closed).map((s) => s.dir);
+    const slotOfFile = (file) => [...slots.values()].find((s) => !s.closed && isProjectSource(s.dir, file)) ?? null;
+    const recordOf = (id) => registry.list().find((r) => projectIdOf(r.dir) === id) ?? null;
+    const summaries = () => registry.list().map((r) => {
+        const id = projectIdOf(r.dir);
+        const s = slots.get(id);
+        const exists = fs.existsSync(r.dir);
+        const errors = s ? s.payload.diagnostics.filter((d) => d.severity === 'error').length : 0;
+        const status = !exists ? 'missing' : !s ? 'idle' : s.compiling && s.payload.version === 0 ? 'compiling' : errors > 0 || !s.payload.ok ? 'error' : 'ok';
+        return { id, dir: r.dir, name: r.name, lastOpened: r.lastOpened, status, errors: status === 'error' ? Math.max(errors, 1) : errors, version: s?.payload.version ?? 0 };
+    });
+    const broadcastProjects = () => {
+        if (!closed)
+            server?.ws.send({ type: 'custom', event: PROJECTS_EVENT, data: { projects: summaries() } });
+    };
+    // ---------- 项目：加载器与编译 ----------
+    async function startLoader(slot) {
+        slot.loader = await createServer({
+            configFile: false,
+            envDir: false,
+            root: slot.dir,
+            appType: 'custom',
+            customLogger: makeLogger(log),
+            resolve: { alias: kitAliases(web, slot.dir) },
+            plugins: [joploProjectPlugin(slot.dir, web)],
+            // 只在服务端载入模块：不开 HMR、不开 WebSocket（多个项目同时运行时不能争用端口）、不监听
+            server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+            optimizeDeps: { noDiscovery: true, include: [] },
+            cacheDir: path.join(slot.dir, '.joplo/vite'),
+        });
+    }
+    async function recompile(slot) {
+        const loader = slot.loader;
+        invalidateProjectModules(loader, slot.dir);
+        const out = await compileProject(loader, slot.dir, 'dev');
+        const prev = slot.payload;
+        slot.payload = { version: prev.version + 1, ok: out.project !== null, project: out.project ?? prev.project, diagnostics: out.diagnostics, home: out.home ?? prev.home };
+        const errors = out.diagnostics.filter((d) => d.severity === 'error');
+        if (errors.length)
+            log(`[joplo] ${path.basename(slot.dir)} 编译出错（${errors.length}）：${errors.map((d) => `${d.at ?? ''} ${d.message}`).join('；').slice(0, 400)}`);
+        if (out.project && out.project.name)
+            registry.rename(slot.dir, out.project.name);
+        if (!closed)
+            server?.ws.send({ type: 'custom', event: IR_EVENT, data: { projectId: slot.id, ...slot.payload } });
+        broadcastProjects();
+    }
+    /** 串行化：编译进行中又有变化时，结束后再编一次。 */
+    function run(slot) {
+        if (slot.closed || closed)
+            return Promise.resolve();
+        if (slot.running) {
+            slot.dirty = true;
+            return slot.running;
+        }
+        slot.compiling = true;
+        slot.running = (async () => {
+            do {
+                slot.dirty = false;
+                try {
+                    await recompile(slot);
+                }
+                catch (e) {
+                    log(`[joplo] 编译异常：${e instanceof Error ? e.message : String(e)}`);
+                }
+            } while (slot.dirty && !slot.closed);
+        })().finally(() => {
+            slot.running = null;
+            slot.compiling = false;
+        });
+        return slot.running;
+    }
+    function activate(dir) {
+        const id = projectIdOf(dir);
+        const existing = slots.get(id);
+        if (existing && !existing.closed)
+            return existing;
+        const slot = {
+            id,
+            dir,
+            loader: null,
+            ready: Promise.resolve(),
+            payload: { version: 0, ok: false, project: null, diagnostics: [], home: null },
+            compiling: true,
+            closed: false,
+            running: null,
+            dirty: false,
+            timer: null,
+        };
+        slots.set(id, slot);
+        slot.ready = (async () => {
+            await startLoader(slot);
+            if (watch && server)
+                server.watcher.add(dir);
+            await run(slot);
+        })().catch((e) => log(`[joplo] 项目启动失败：${e instanceof Error ? e.message : String(e)}`));
+        invalidateCss();
+        return slot;
+    }
+    async function deactivate(slot) {
+        slot.closed = true;
+        if (slot.timer)
+            clearTimeout(slot.timer);
+        await slot.running?.catch(() => undefined);
+        await slot.loader?.close().catch(() => undefined);
+        if (watch && server)
+            server.watcher.unwatch(slot.dir);
+        slots.delete(slot.id);
+    }
+    /** 新项目的目录加入 Tailwind @source：让 CSS 入口重新转换。 */
+    function invalidateCss() {
+        if (!server)
+            return;
+        const entry = web.mode === 'source' ? web.indexCss : web.projectCss;
+        const env = server.environments.client;
+        const mods = env.moduleGraph.getModulesByFile(entry);
+        if (!mods)
+            return;
+        for (const m of mods)
+            void env.reloadModule(m).catch(() => undefined);
+    }
+    async function ensure(id) {
+        let slot = slots.get(id);
+        if (!slot) {
+            const rec = recordOf(id);
+            if (!rec)
+                throw new JoploError('NOT_FOUND', `没有这个项目：${id}`);
+            if (!fs.existsSync(rec.dir))
+                throw new JoploError('NOT_FOUND', `找不到项目目录：${rec.dir}`);
+            slot = activate(rec.dir);
+        }
+        await slot.ready;
+        return slot;
+    }
+    function addProject(dirIn, o = {}) {
+        const dir = realProjectDir(dirIn);
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            throw new JoploError('NOT_FOUND', `项目目录不存在：${dir}`);
+        const id = projectIdOf(dir);
+        const prev = registry.list().find((r) => r.dir === dir);
+        registry.touch(dir, prev?.name);
+        const slot = o.compile === false ? (slots.get(id) ?? null) : activate(dir);
+        broadcastProjects();
+        return { id, url: projectUrl(baseUrl(), id), slot };
+    }
+    const exportsHub = new ExportHub({
+        baseUrl,
+        log,
+        deps: opts.exportDeps,
+        onEvent: () => undefined,
+    });
+    // ---------- HTTP ----------
+    const deny = (res, status, message) => sendJson(res, status, { error: { code: 'PERMISSION_DENIED', message } });
+    /** 写接口：Origin（有则必须是看板自己）、令牌、Content-Type。返回 false 表示已拒绝。 */
+    const guardWrite = (req, res, tokenStatus = 403, needJson = true) => {
+        const origin = req.headers.origin;
+        if (origin !== undefined && !allowedOrigins().has(origin))
+            return deny(res, 403, `Origin 不被允许：${origin}`), false;
+        const t = req.headers['x-joplo-token'];
+        if (typeof t !== 'string' || !safeEqual(t, token))
+            return deny(res, tokenStatus, '缺少或错误的本地令牌（x-joplo-token）'), false;
+        if (needJson && !isJsonContentType(req.headers['content-type']))
+            return sendJson(res, 415, { error: { code: 'USAGE', message: 'Content-Type 必须是 application/json' } }), false;
+        return true;
+    };
+    const jsonBody = async (req, res) => {
+        const raw = await readBody(req);
+        if (raw.tooLarge)
+            return sendJson(res, 413, { error: { code: 'USAGE', message: `请求体过大（上限 ${MAX_BODY} 字节）` } }), { ok: false };
+        try {
+            return { ok: true, body: JSON.parse(raw.text) };
+        }
+        catch (e) {
+            return sendJson(res, 400, { error: { code: 'USAGE', message: `请求体不是合法 JSON：${e instanceof Error ? e.message : String(e)}` } }), { ok: false };
+        }
+    };
+    const fail = (res, e) => {
+        const code = e instanceof JoploError ? e.code : 'INTERNAL';
+        const status = code === 'NOT_FOUND' ? 404 : code === 'USAGE' ? 400 : code === 'RENDER_FAILED' ? 503 : 500;
+        sendJson(res, status, { error: { code, message: e instanceof Error ? e.message : String(e) } });
+    };
+    async function handleProject(id, rest, req, res) {
+        const method = req.method ?? 'GET';
+        if (rest === 'ir' && method === 'GET') {
+            const slot = await ensure(id);
+            return sendJson(res, 200, { projectId: id, ...slot.payload });
+        }
+        if (rest === 'selection' && method === 'GET') {
+            const slot = await ensure(id);
+            return sendJson(res, 200, { selection: readSelection(slot.dir) });
+        }
+        if (rest === 'selection' && method === 'PUT') {
+            if (!guardWrite(req, res, 401))
+                return;
+            const b = await jsonBody(req, res);
+            if (!b.ok)
+                return;
+            const parsed = SelectionBody.safeParse(b.body);
+            if (!parsed.success)
+                return sendJson(res, 400, { error: { code: 'USAGE', message: '选中内容格式不正确', issues: parsed.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })) } });
+            const slot = await ensure(id);
+            if (parsed.data.selection === null) {
+                writeSelection(slot.dir, null);
+                return sendJson(res, 200, { ok: true, selection: null });
+            }
+            const project = slot.payload.project;
+            const r = project ? resolveSelection(project, parsed.data.selection) : { ok: false, problem: '项目还没有成功编译过' };
+            if (!r.ok) {
+                // 不变量：被拒绝时文件写为 null（不能保留旧选中而界面显示新选中）
+                writeSelection(slot.dir, null);
+                return sendJson(res, 409, { error: { code: 'INVALID_REFERENCE', message: `选中与当前项目不符：${r.problem}` }, current: null });
+            }
+            writeSelection(slot.dir, r.selection);
+            return sendJson(res, 200, { ok: true, selection: r.selection });
+        }
+        if (rest === 'open' && method === 'POST') {
+            if (!guardWrite(req, res))
+                return;
+            const b = await jsonBody(req, res);
+            if (!b.ok)
+                return;
+            const slot = await ensure(id);
+            const at = b.body?.at;
+            const m = typeof at === 'string' ? /^(.+?):(\d+)(?::(\d+))?$/.exec(at) : null;
+            if (!m)
+                return sendJson(res, 400, { error: { code: 'USAGE', message: 'at 应为 文件:行[:列]' } });
+            const file = path.resolve(slot.dir, m[1]);
+            if (!isProjectSource(slot.dir, file) || !fs.existsSync(file))
+                return sendJson(res, 400, { error: { code: 'USAGE', message: `不是项目里的源文件：${m[1]}` } });
+            // 交给 Vite 自带的 launch-editor（按 LAUNCH_EDITOR / EDITOR 或正在运行的编辑器打开）
+            req.__joploOpen = true;
+            req.url = `/__open-in-editor?file=${encodeURIComponent(`${file}:${m[2]}:${m[3] ?? 1}`)}`;
+            req.method = 'GET';
+            return 'next';
+        }
+        if (rest.startsWith('export/')) {
+            const slot = await ensure(id);
+            return exportsHub.handle(rest.slice('export/'.length), req, res, { projectId: id, dir: slot.dir, project: slot.payload.project, guardWrite: (needJson = true) => guardWrite(req, res, 403, needJson), jsonBody: () => jsonBody(req, res), fail: (e) => fail(res, e) });
+        }
+        return sendJson(res, 404, { error: { code: 'NOT_FOUND', message: `没有这个接口：${method} /__joplo/p/${id}/${rest}` } });
+    }
+    const boardPlugin = {
+        name: 'joplo:board',
+        configureServer(srv) {
+            srv.middlewares.use(async (req, res, next) => {
+                try {
+                    const host = req.headers.host ?? '';
+                    if (!allowedHosts().has(host))
+                        return deny(res, 403, `Host 头不被允许：${host || '(空)'}`);
+                    const url = new URL(req.url ?? '/', `http://127.0.0.1:${actualPort}`);
+                    if (web.mode === 'dist' && (req.method === 'GET' || req.method === 'HEAD') && serveDistAsset(web, url.pathname, res))
+                        return;
+                    // Vite 的打开编辑器中间件只能经由 /__joplo/p/<id>/open（校验令牌与路径）进入
+                    if (url.pathname === '/__open-in-editor')
+                        return req.__joploOpen ? next() : deny(res, 403, '请通过看板的“在编辑器中打开”');
+                    if (!url.pathname.startsWith('/__joplo/'))
+                        return next();
+                    const method = req.method ?? 'GET';
+                    if (url.pathname === '/__joplo/ping' && method === 'GET')
+                        return sendJson(res, 200, { joplo: true, pid: process.pid });
+                    if (url.pathname === '/__joplo/projects' && method === 'GET')
+                        return sendJson(res, 200, { projects: summaries() });
+                    // 看板设置（D51）：主题选择，存于 <JOPLO_HOME>/settings.json（没有 home 时只在内存里）
+                    if (url.pathname === '/__joplo/settings' && method === 'GET')
+                        return sendJson(res, 200, { settings: opts.home ? readSettings(opts.home) : memSettings });
+                    if (url.pathname === '/__joplo/settings' && method === 'PUT') {
+                        if (!guardWrite(req, res))
+                            return;
+                        const b = await jsonBody(req, res);
+                        if (!b.ok)
+                            return;
+                        const next = b.body?.settings;
+                        memSettings = opts.home ? writeSettings(opts.home, next) : normalizeSettings(next);
+                        return sendJson(res, 200, { settings: memSettings });
+                    }
+                    if (url.pathname === '/__joplo/projects' && method === 'POST') {
+                        if (!guardWrite(req, res))
+                            return;
+                        const b = await jsonBody(req, res);
+                        if (!b.ok)
+                            return;
+                        const dir = b.body?.dir;
+                        if (typeof dir !== 'string' || !path.isAbsolute(dir))
+                            return sendJson(res, 400, { error: { code: 'USAGE', message: 'dir 必须是项目目录的绝对路径' } });
+                        const r = addProject(dir);
+                        return sendJson(res, 200, { id: r.id, url: r.url });
+                    }
+                    const del = /^\/__joplo\/projects\/([^/]+)$/.exec(url.pathname);
+                    if (del && method === 'DELETE') {
+                        if (!guardWrite(req, res, 403, false))
+                            return;
+                        const id = decodeURIComponent(del[1]);
+                        const rec = recordOf(id);
+                        if (!rec)
+                            return sendJson(res, 404, { error: { code: 'NOT_FOUND', message: `没有这个项目：${id}` } });
+                        const slot = slots.get(id);
+                        if (slot)
+                            await deactivate(slot);
+                        registry.remove(rec.dir); // 只删记录，不碰项目目录
+                        broadcastProjects();
+                        return sendJson(res, 200, { ok: true });
+                    }
+                    const pm = /^\/__joplo\/p\/([^/]+)\/(.+)$/.exec(url.pathname);
+                    if (pm) {
+                        const r = await handleProject(decodeURIComponent(pm[1]), pm[2], req, res);
+                        if (r === 'next')
+                            return next();
+                        return;
+                    }
+                    return sendJson(res, 404, { error: { code: 'NOT_FOUND', message: `没有这个接口：${method} ${url.pathname}` } });
+                }
+                catch (e) {
+                    if (!res.headersSent)
+                        fail(res, e);
+                    else
+                        res.end();
+                }
+            });
+        },
+        transformIndexHtml(html) {
+            const out = html.replace('__JOPLO_TOKEN__', token);
+            return web.mode === 'dist' ? injectDistBoot(out, web) : out;
+        },
+        // 项目源文件只在项目加载器里使用：它们的变化由下面的重新编译处理，不交给 Vite 的默认 HMR。
+        // client 环境里只保留非项目模块（例如以项目目录为 @source 的 index.css），新 className 照常热更新。
+        hotUpdate(ctx) {
+            if (!slotOfFile(ctx.file))
+                return;
+            if (this.environment.name !== 'client')
+                return [];
+            return ctx.modules.filter((m) => !m.file || !slotOfFile(m.file));
+        },
+    };
+    server = await createServer({
+        configFile: false,
+        envDir: false,
+        root: web.mode === 'dist' ? web.appDir : web.webDir,
+        mode: 'development',
+        appType: 'spa',
+        clearScreen: false,
+        customLogger: makeLogger(log),
+        resolve: { alias: web.mode === 'source' ? kitAliases(web, web.webDir) : [] },
+        plugins: [cssSourcePlugin(activeDirs, web), boardPlugin, ...(await webPlugins(web))],
+        // dist 形态不往 node_modules 里写缓存（可能只读，或被多个项目共享）
+        cacheDir: web.mode === 'dist' ? path.join(opts.home ?? path.join(process.cwd(), '.joplo'), 'vite') : path.join(web.webDir, 'node_modules/.vite-joplo'),
+        optimizeDeps: web.mode === 'dist'
+            ? { noDiscovery: true, include: [] }
+            : {
+                include: ['react', 'react-dom', 'react-dom/client', 'react/jsx-dev-runtime', 'react/jsx-runtime', 'motion', 'motion/react', 'roughjs', 'lucide-react', 'clsx', 'tailwind-merge', '@dagrejs/dagre', 'modern-screenshot', '@joplo-app/core > zod'],
+            },
+        server: {
+            host: '127.0.0.1',
+            port,
+            strictPort: true,
+            open: false,
+            ...(web.mode === 'dist' ? { fs: { allow: [web.webDir] } } : {}),
+            ...(watch ? { watch: { ignored: (p) => { const s = slotOfFile(p) ?? [...slots.values()].find((x) => p.startsWith(x.dir + path.sep)); return !!s && IGNORED_DIRS.includes(p.slice(s.dir.length + 1).split(path.sep)[0] ?? ''); } } } : { watch: null }),
+        },
+    });
+    try {
+        await server.listen();
+    }
+    catch (e) {
+        await server.close().catch(() => undefined);
+        const err = e;
+        if (err.code === 'EADDRINUSE' || /already in use/i.test(err.message ?? ''))
+            throw new JoploError('USAGE', `端口 ${port} 已被占用，请换一个端口（--port），或先关闭占用它的进程`, { details: { code: 'EADDRINUSE' } });
+        throw e;
+    }
+    const addr = server.httpServer?.address();
+    actualPort = typeof addr === 'object' && addr ? addr.port : port;
+    if (opts.home)
+        writeServerInfo(opts.home, { port: actualPort, pid: process.pid, token });
+    if (watch) {
+        server.watcher.on('all', (_ev, file) => {
+            const slot = slotOfFile(path.resolve(file));
+            if (!slot)
+                return;
+            if (slot.timer)
+                clearTimeout(slot.timer);
+            slot.timer = setTimeout(() => void run(slot), 60);
+        });
+    }
+    return {
+        get url() {
+            return baseUrl();
+        },
+        get port() {
+            return actualPort;
+        },
+        token,
+        server,
+        addProject,
+        ensure,
+        projects: summaries,
+        close: async () => {
+            closed = true;
+            await exportsHub.close();
+            for (const s of [...slots.values()])
+                await deactivate(s);
+            await server.close();
+            if (opts.home)
+                clearServerInfo(opts.home, process.pid);
+        },
+    };
+}
+/** 启动一个看板进程并打开一个项目（等首次编译完成）。缺省不持久化。 */
+export async function createDev(opts) {
+    const hub = await createHub({ port: opts.port, log: opts.log, watch: opts.watch, home: opts.home ?? null, exportDeps: opts.exportDeps });
+    try {
+        const { id, url, slot } = hub.addProject(opts.projectDir);
+        await slot.ready;
+        return { url: hub.url, projectUrl: url, projectId: id, token: hub.token, port: hub.port, server: hub.server, hub, payload: () => slot.payload, close: () => hub.close() };
+    }
+    catch (e) {
+        await hub.close();
+        throw e;
+    }
+}
+/** 已有存活的看板：用令牌注册项目，返回项目链接；没有或不可用时返回 null。 */
+export async function attachToRunning(home, projectDir, log) {
+    const info = readServerInfo(home);
+    if (!info)
+        return null;
+    if (!pidAlive(info.pid)) {
+        clearServerInfo(home, info.pid);
+        return null;
+    }
+    const base = `http://127.0.0.1:${info.port}`;
+    try {
+        const ping = await fetch(`${base}/__joplo/ping`, { signal: AbortSignal.timeout(1500) });
+        const body = (await ping.json());
+        if (!ping.ok || body.joplo !== true || body.pid !== info.pid)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const res = await fetch(`${base}/__joplo/projects`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-joplo-token': info.token },
+        body: JSON.stringify({ dir: realProjectDir(projectDir) }),
+        signal: AbortSignal.timeout(10000),
+    });
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || !body?.url)
+        throw new JoploError('UNSUPPORTED_ACTION', `无法把项目加入正在运行的看板（${base}，pid ${info.pid}）：${body?.error?.message ?? `HTTP ${res.status}`}`);
+    log(`[joplo] 已加入正在运行的看板（pid ${info.pid}）`);
+    return { url: body.url, port: info.port };
+}
+function openBrowser(url, log) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        log(`[joplo] 无法自动打开浏览器，请手动访问 ${url}`);
+    }
+}
+/**
+ * CLI 的 `joplo dev`：同一个 JOPLO_HOME 下只运行一个看板进程。
+ * 已有存活的看板 → 注册项目、（--open 时）打开浏览器，返回 attached；否则启动新的看板并登记项目。
+ */
+export async function startDev(opts) {
+    const log = opts.log ?? ((m) => process.stderr.write(m + '\n'));
+    const home = opts.home ?? joploHome();
+    const projectDir = realProjectDir(opts.projectDir);
+    if (!fs.existsSync(projectDir))
+        throw new JoploError('NOT_FOUND', `项目目录不存在：${projectDir}`);
+    const attach = async () => {
+        const a = await attachToRunning(home, projectDir, log);
+        if (!a)
+            return null;
+        if (opts.open)
+            openBrowser(a.url, log);
+        return { url: a.url, attached: true, close: async () => undefined };
+    };
+    const existing = await attach();
+    if (existing)
+        return existing;
+    let hub;
+    try {
+        hub = await createHub({ port: opts.port, log, home, exportDeps: opts.exportDeps });
+    }
+    catch (e) {
+        // 另一个 joplo dev 恰好同时启动：端口被它占了，改为加入它
+        if (e instanceof JoploError && e.details?.code === 'EADDRINUSE') {
+            await new Promise((r) => setTimeout(r, 300));
+            const again = await attach();
+            if (again)
+                return again;
+        }
+        throw e;
+    }
+    const { url } = hub.addProject(projectDir);
+    const cleanup = () => clearServerInfo(home, process.pid);
+    process.once('exit', cleanup);
+    if (opts.open)
+        openBrowser(url, log);
+    return {
+        url,
+        attached: false,
+        close: async () => {
+            process.off('exit', cleanup);
+            await hub.close();
+        },
+    };
+}