@leeoohoo/ui-apps-devkit 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
   "license": "MIT",
   "type": "module",

package/src/commands/install.js

@@ -1,11 +1,29 @@
+import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import crypto from 'crypto';
 
 import { copyDir, ensureDir, isDirectory, rmForce, sanitizeDirComponent } from '../lib/fs.js';
 import { loadDevkitConfig } from '../lib/config.js';
 import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
 import { STATE_ROOT_DIRNAME } from '../lib/state-constants.js';
 
+function createActionId(prefix) {
+  const base = typeof prefix === 'string' && prefix.trim() ? prefix.trim() : 'action';
+  const short = crypto.randomUUID().split('-')[0];
+  return `${base}-${Date.now().toString(36)}-${short}`;
+}
+
+function logWith(filePath, entry) {
+  if (!filePath) return;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`, 'utf8');
+  } catch {
+    // ignore logging failures
+  }
+}
+
 function defaultStateDir(hostApp) {
   const app = typeof hostApp === 'string' && hostApp.trim() ? hostApp.trim() : 'chatos';
   return path.join(os.homedir(), STATE_ROOT_DIRNAME, app);
@@ -28,29 +46,59 @@ function copyPluginDir(srcDir, destDir) {
 
 export async function cmdInstall({ flags }) {
   const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const { pluginId, name, version } = loadPluginManifest(pluginDir);
-
+  const actionId = createActionId('devkit_install');
   const hostApp = String(flags['host-app'] || flags.hostApp || 'chatos').trim() || 'chatos';
   const stateDir = String(flags['state-dir'] || flags.stateDir || defaultStateDir(hostApp)).trim();
-  if (!stateDir) throw new Error('stateDir is required');
+  const logFile = String(flags['log-file'] || flags.logFile || path.join(stateDir, 'devkit-install-log.jsonl')).trim();
+  const log = (level, message, meta, err) => {
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      message,
+      actionId,
+      pid: process.pid,
+      meta: meta && typeof meta === 'object' ? meta : meta === undefined ? undefined : { value: meta },
+      error: err?.message || (err ? String(err) : undefined),
+    };
+    logWith(logFile, entry);
+  };
+
+  try {
+    if (!stateDir) throw new Error('stateDir is required');
+    log('info', 'devkit.install.start', { hostApp, stateDir, logFile });
+    const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+    const { pluginId, name, version } = loadPluginManifest(pluginDir);
+
+    const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
+    ensureDir(pluginsRoot);
 
-  const pluginsRoot = path.join(stateDir, 'ui_apps', 'plugins');
-  ensureDir(pluginsRoot);
+    const dirName = sanitizeDirComponent(pluginId);
+    if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
 
-  const dirName = sanitizeDirComponent(pluginId);
-  if (!dirName) throw new Error(`Invalid plugin id: ${pluginId}`);
+    const destDir = path.join(pluginsRoot, dirName);
+    const replaced = isDirectory(destDir);
+    copyPluginDir(pluginDir, destDir);
 
-  const destDir = path.join(pluginsRoot, dirName);
-  const replaced = isDirectory(destDir);
-  copyPluginDir(pluginDir, destDir);
+    log('info', 'devkit.install.complete', {
+      pluginId,
+      name,
+      version,
+      pluginDir,
+      destDir,
+      replaced,
+    });
 
-  // eslint-disable-next-line no-console
-  console.log(
-    `Installed: ${pluginId} (${name}@${version})\n` +
-      `  -> ${destDir}\n` +
-      `  replaced: ${replaced}\n\n` +
-      `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
-  );
+    // eslint-disable-next-line no-console
+    console.log(
+      `Installed: ${pluginId} (${name}@${version})\n` +
+        `  -> ${destDir}\n` +
+        `  replaced: ${replaced}\n` +
+        `  log: ${logFile}\n\n` +
+        `Open ChatOS -> 应用 -> 刷新（同 id 覆盖生效）。`
+    );
+  } catch (err) {
+    log('error', 'devkit.install.failed', {}, err);
+    throw err;
+  }
 }
 

package/src/commands/validate.js

@@ -18,11 +18,52 @@ function statSizeSafe(filePath) {
   }
 }
 
+function collectSymlinks(rootDir) {
+  const root = typeof rootDir === 'string' ? rootDir.trim() : '';
+  if (!root) return [];
+  const out = [];
+  const walk = (dir) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.forEach((entry) => {
+      if (!entry || !entry.name) return;
+      const fullPath = path.join(dir, entry.name);
+      let stat;
+      try {
+        stat = fs.lstatSync(fullPath);
+      } catch {
+        return;
+      }
+      if (stat.isSymbolicLink()) {
+        out.push(fullPath);
+        return;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      }
+    });
+  };
+  walk(root);
+  return out;
+}
+
 export async function cmdValidate({ flags }) {
   const { config } = loadDevkitConfig(process.cwd());
   const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
 
   const { manifestPath, manifest } = loadPluginManifest(pluginDir);
+  const warnings = [];
+  const warn = (message) => warnings.push(message);
+
+  const symlinks = collectSymlinks(pluginDir);
+  if (symlinks.length > 0) {
+    const rel = symlinks.map((entry) => path.relative(pluginDir, entry) || entry);
+    warn(`Symlink detected inside plugin dir (may bypass path boundaries): ${rel.join(', ')}`);
+  }
 
   const manifestSize = statSizeSafe(manifestPath);
   assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
@@ -108,6 +149,13 @@ export async function cmdValidate({ flags }) {
     }
   }
 
+  if (warnings.length > 0) {
+    warnings.forEach((message) => {
+      // eslint-disable-next-line no-console
+      console.warn(`WARN: ${message}`);
+    });
+  }
+
   // eslint-disable-next-line no-console
   console.log(`OK: ${path.relative(process.cwd(), pluginDir)} (apps=${apps.length})`);
 }

package/src/sandbox/server.js

@@ -668,10 +668,12 @@ function htmlPage() {
         border-radius:14px;
         overflow:hidden;
         box-shadow: 0 18px 60px rgba(0,0,0,0.18);
+        z-index: 1305;
+        pointer-events: auto;
       }
       #promptsPanelHeader { padding: 10px 12px; display:flex; align-items:center; justify-content:space-between; border-bottom: 1px solid var(--ds-panel-border); }
       #promptsPanelBody { padding: 10px 12px; overflow:auto; display:flex; flex-direction:column; gap:10px; }
-      #promptsFab { position: fixed; right: 16px; bottom: 16px; width: 44px; height: 44px; border-radius: 999px; display:flex; align-items:center; justify-content:center; }
+      #promptsFab { position: fixed; right: 16px; bottom: 16px; width: 44px; height: 44px; border-radius: 999px; display:flex; align-items:center; justify-content:center; z-index: 1305; pointer-events: auto; }
       .card { border: 1px solid var(--ds-panel-border); border-radius: 12px; padding: 10px; background: var(--ds-panel-bg); }
       .row { display:flex; gap:10px; }
       .toolbar-group { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
@@ -867,8 +869,8 @@ function htmlPage() {
         <div class="card">
           <div class="section-title">Paths</div>
           <pre id="mcpPaths" class="mono"></pre>
-          <label for="mcpWorkdir">Workdir Override (optional)</label>
-          <input id="mcpWorkdir" type="text" placeholder="留空则使用默认 workdir" />
+          <label for="mcpWorkdir">ProjectRoot Override (optional)</label>
+          <input id="mcpWorkdir" type="text" placeholder="留空则使用默认 projectRoot" />
         </div>
         <div class="card">
           <div class="section-title">Model</div>
@@ -1146,9 +1148,15 @@ const appendMcpOutput = (label, payload) => {
   mcpOutput.scrollTop = mcpOutput.scrollHeight;
 };
 
+const resolveMcpPaths = () => {
+  const projectRootOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
+  if (!projectRootOverride) return sandboxPaths;
+  return { ...sandboxPaths, projectRoot: projectRootOverride };
+};
+
 const refreshMcpPaths = () => {
   if (!mcpPaths) return;
-  mcpPaths.textContent = formatJson(sandboxPaths);
+  mcpPaths.textContent = formatJson(resolveMcpPaths());
 };
 
 const refreshMcpConfigHint = async () => {
@@ -1193,9 +1201,11 @@ const runMcpTest = async () => {
       systemPrompt: mcpSystem ? String(mcpSystem.value || '').trim() : '',
       disableTools: Boolean(mcpDisableTools?.checked),
     };
-    const workdirOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
-    if (workdirOverride) {
-      payload.callMeta = { workdir: workdirOverride };
+    const projectRootOverride = mcpWorkdir ? String(mcpWorkdir.value || '').trim() : '';
+    if (projectRootOverride) {
+      payload.callMeta = {
+        chatos: { uiApp: { projectRoot: projectRootOverride } },
+      };
     }
     setMcpStatus('Sending...');
     appendMcpOutput('request', payload);
@@ -1327,6 +1337,7 @@ if (btnLlmClear) btnLlmClear.addEventListener('click', () => saveLlmConfig({ cle
 if (btnMcpTest) btnMcpTest.addEventListener('click', () => setMcpPanelOpen(!isMcpPanelOpen()));
 if (btnHalfApp) btnHalfApp.addEventListener('click', () => toggleCompactSurface());
 if (btnMcpClose) btnMcpClose.addEventListener('click', () => setMcpPanelOpen(false));
+if (mcpWorkdir) mcpWorkdir.addEventListener('input', () => refreshMcpPaths());
 if (btnMcpClear)
   btnMcpClear.addEventListener('click', () => {
     if (mcpOutput) mcpOutput.textContent = '';

package/templates/basic/README.md

@@ -34,6 +34,7 @@ npm run dev
 
 - `plugin/plugin.json`：`apps[i].entry.type` 必须是 `module`，且 `path` 在插件目录内。
 - `plugin/plugin.json`：可选 `apps[i].entry.compact.path`，用于 compact UI。
+- 安全：插件目录内尽量避免 symlink（`npm run validate` 会提示），以免路径边界与打包行为不一致。
 - `mount()`：返回卸载函数并清理事件/订阅；滚动放在应用内部，固定内容用 `slots.header`。
 - 主题：用 `host.theme.*` 与 `--ds-*` tokens；避免硬编码颜色。
 - 宿主能力：先判断 `host.bridge.enabled`，非宿主环境要可降级运行。
@@ -49,6 +50,7 @@ npm run dev
 2) **后端调用 LLM**：在 `plugin/backend/index.mjs` 里通过 `ctx.llm.complete()` 调用模型；前端用 `host.backend.invoke('llmComplete', { input })` 触发。
 
 说明：本地沙箱默认是 mock；可通过右上角 `AI Config` 配置 `API Key / Base URL / Model ID` 后启用真实模型调用，并用于测试应用 MCP（需配置 `ai.mcp`）。
+补充：沙箱默认把 `_meta.workdir` 设为 `dataDir`；如需模拟其它工作目录，可在 `AI Config` 里设置 `Workdir` 覆盖（支持 `$dataDir/$pluginDir/$projectRoot`）。
 
 ## 安装到本机 ChatOS
 

package/templates/basic/docs/CHATOS_UI_APPS_AI_CONTRIBUTIONS.md

@@ -85,6 +85,8 @@
 
 同时，宿主默认注入 `_meta.workdir`（默认等于 `dataDir`；如需指定其它目录，可在 `ai.mcp.callMeta.workdir` 覆盖）。
 
+> DevKit sandbox：右上角 `AI Config` 支持设置 `Workdir` 覆盖；留空即使用 `dataDir`（也支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 示例（`plugin.json`）：
 
 ```json

package/templates/notepad/README.md

@@ -9,6 +9,11 @@ npm install
 npm run dev
 ```
 
+## 本地沙箱 AI Config（可选）
+
+- 右上角 `AI Config` 可配置 `API Key / Base URL / Model ID`，用于测试真实模型调用（以及 MCP 调用）。
+- 沙箱默认把 `_meta.workdir` 设为 `dataDir`；如需模拟其它工作目录，可在 `AI Config` 里设置 `Workdir` 覆盖（支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 ## 目录说明
 
 - `plugin/plugin.json`：插件清单（应用列表、入口、后端、AI 贡献）
@@ -29,6 +34,7 @@ npm run dev
 
 - `plugin/plugin.json`：`apps[i].entry.type` 必须是 `module`，且 `path` 在插件目录内。
 - `plugin/plugin.json`：可选 `apps[i].entry.compact.path`，用于 compact UI。
+- 安全：插件目录内尽量避免 symlink（`npm run validate` 会提示），以免路径边界与打包行为不一致。
 - `mount()`：返回卸载函数并清理事件/订阅；滚动放在应用内部，固定内容用 `slots.header`。
 - 主题：用 `host.theme.*` 与 `--ds-*` tokens；避免硬编码颜色。
 - 宿主能力：先判断 `host.bridge.enabled`，非宿主环境要可降级运行。

package/templates/notepad/docs/CHATOS_UI_APPS_AI_CONTRIBUTIONS.md

@@ -85,6 +85,8 @@
 
 同时，宿主默认注入 `_meta.workdir`（默认等于 `dataDir`；如需指定其它目录，可在 `ai.mcp.callMeta.workdir` 覆盖）。
 
+> DevKit sandbox：右上角 `AI Config` 支持设置 `Workdir` 覆盖；留空即使用 `dataDir`（也支持 `$dataDir/$pluginDir/$projectRoot`）。
+
 示例（`plugin.json`）：
 
 ```json