@leeoohoo/ui-apps-devkit 0.1.0 → 0.1.1

package/README.md

@@ -1,70 +1,76 @@
-# ChatOS UI Apps DevKit
-
-一个可通过 npm 安装的 DevKit，用来：
-
-- 生成 UI Apps 插件工程（脚手架）
-- 在本地沙箱里运行/调试 `module` 应用（Host API mock）
-- 校验 `plugin.json` 与路径边界
-- 打包/安装到本机 ChatOS（`~/.deepseek_cli/chatos/ui_apps/plugins`）
-
-## 安装
-
-```bash
-npm i -g @leeoohoo/ui-apps-devkit
-```
-
-或直接用 npx：
-
-```bash
-npx @leeoohoo/ui-apps-devkit chatos-uiapp --help
-```
-
-## 快速开始
-
-```bash
-chatos-uiapp init my-first-uiapp
-cd my-first-uiapp
-npm install
-npm run dev
-```
-
-## 模板
-
-```bash
-chatos-uiapp init --list-templates
-chatos-uiapp init my-app --template basic
-chatos-uiapp init my-app --template notepad
-```
-
-- `basic`：最小可运行骨架（含 `host.chat.*` / `ctx.llm.complete()` 示例）
-- `notepad`：完整示例应用（文件夹/标签/搜索/后端持久化）
-
-完成开发后：
-
-```bash
-npm run validate
-npm run pack
-npm run install:chatos
-```
-
-## 生成项目结构（约定）
-
-生成的工程里，**可安装产物**固定在 `plugin/` 目录：
-
-```
-my-first-uiapp/
-  docs/                # 协议文档（随工程分发）
-  chatos.config.json   # DevKit 配置（pluginDir/appId）
-  plugin/              # 直接导入/安装到 ChatOS 的插件目录
-    plugin.json
-    backend/           # (可选) Electron main 进程后端
-    apps/<appId>/      # module 前端 + AI 贡献（MCP/Prompt）
-```
-
-## CLI
-
-- `chatos-uiapp init <dir>`：生成工程
-- `chatos-uiapp dev`：启动本地运行沙箱（支持文件变更自动重载）
-- `chatos-uiapp validate`：校验 manifest 与路径边界
-- `chatos-uiapp pack`：打包 `.zip`（用于 ChatOS 导入）
-- `chatos-uiapp install`：复制到本机 ChatOS 用户插件目录
+# ChatOS UI Apps DevKit
+
+一个可通过 npm 安装的 DevKit，用来：
+
+- 生成 UI Apps 插件工程（脚手架）
+- 在本地沙箱里运行/调试 `module` 应用（Host API mock）
+- 校验 `plugin.json` 与路径边界
+- 打包/安装到本机 ChatOS（`~/.deepseek_cli/chatos/ui_apps/plugins`）
+
+## 安装
+
+```bash
+npm i -g @leeoohoo/ui-apps-devkit
+```
+
+或直接用 npx：
+
+```bash
+npx @leeoohoo/ui-apps-devkit chatos-uiapp --help
+```
+
+## 快速开始
+
+```bash
+chatos-uiapp init my-first-uiapp
+cd my-first-uiapp
+npm install
+npm run dev
+```
+
+## 沙箱能力
+
+- 模拟 `module mount()` 与 `host.*` API
+- 右上角 Theme 切换（light/dark/system），用于测试 `host.theme.onChange` 与样式响应
+- Inspect 面板展示 `host.context` 与 `--ds-*` tokens
+
+## 模板
+
+```bash
+chatos-uiapp init --list-templates
+chatos-uiapp init my-app --template basic
+chatos-uiapp init my-app --template notepad
+```
+
+- `basic`：最小可运行骨架（含 `host.chat.*` / `ctx.llm.complete()` 示例）
+- `notepad`：完整示例应用（文件夹/标签/搜索/后端持久化）
+
+完成开发后：
+
+```bash
+npm run validate
+npm run pack
+npm run install:chatos
+```
+
+## 生成项目结构（约定）
+
+生成的工程里，**可安装产物**固定在 `plugin/` 目录：
+
+```
+my-first-uiapp/
+  docs/                # 协议文档（随工程分发）
+  chatos.config.json   # DevKit 配置（pluginDir/appId）
+  plugin/              # 直接导入/安装到 ChatOS 的插件目录
+    plugin.json
+    backend/           # (可选) Electron main 进程后端
+    apps/<appId>/      # module 前端 + AI 贡献（MCP/Prompt）
+```
+
+## CLI
+
+- `chatos-uiapp init <dir>`：生成工程
+- `chatos-uiapp dev`：启动本地运行沙箱（支持文件变更自动重载）
+- `chatos-uiapp validate`：校验 manifest 与路径边界
+- `chatos-uiapp pack`：打包 `.zip`（用于 ChatOS 导入）
+- `chatos-uiapp install`：复制到本机 ChatOS 用户插件目录

package/bin/chatos-uiapp.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from '../src/cli.js';
-
-await runCli(process.argv);
-
+import { runCli } from '../src/cli.js';
+
+await runCli(process.argv);
+

package/package.json

@@ -1,22 +1,25 @@
-{
-  "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.0",
-  "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "chatos-uiapp": "bin/chatos-uiapp.js"
-  },
-  "files": [
-    "bin/**",
-    "src/**",
-    "templates/**",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@leeoohoo/ui-apps-devkit",
+  "version": "0.1.1",
+  "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "chatos-uiapp": "bin/chatos-uiapp.js"
+  },
+  "files": [
+    "bin/**",
+    "src/**",
+    "templates/**",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -1,53 +1,53 @@
-import { cmdInit } from './commands/init.js';
-import { cmdValidate } from './commands/validate.js';
-import { cmdPack } from './commands/pack.js';
-import { cmdInstall } from './commands/install.js';
-import { cmdDev } from './commands/dev.js';
-
-import { parseArgs } from './lib/args.js';
-
-function printHelp() {
-  // Keep it short; detailed docs live in README and generated project.
-  // eslint-disable-next-line no-console
-  console.log(`chatos-uiapp
-
-Usage:
-  chatos-uiapp init <dir> [--template <name>] [--force] [--plugin-id <id>] [--name <name>] [--app-id <appId>] [--version <semver>]
-  chatos-uiapp init --list-templates
-  chatos-uiapp dev [--port 4399] [--app <appId>] [--plugin-dir <path>]
-  chatos-uiapp validate [--plugin-dir <path>]
-  chatos-uiapp pack [--out <zipPath>] [--plugin-dir <path>]
-  chatos-uiapp install [--host-app chatos] [--state-dir <path>] [--plugin-dir <path>]
-
-Examples:
-  chatos-uiapp init my-app
-  chatos-uiapp init my-app --template notepad
-  chatos-uiapp init --list-templates
-  chatos-uiapp dev --port 4399
-  chatos-uiapp install --host-app chatos
-`);
-}
-
-export async function runCli(argv) {
-  const { positionals, flags } = parseArgs(argv);
-  const cmd = String(positionals[0] || '').trim();
-
-  if (!cmd || cmd === 'help' || cmd === '--help' || flags.help) {
-    printHelp();
-    return;
-  }
-
-  try {
-    if (cmd === 'init') return await cmdInit({ positionals: positionals.slice(1), flags });
-    if (cmd === 'dev') return await cmdDev({ positionals: positionals.slice(1), flags });
-    if (cmd === 'validate') return await cmdValidate({ positionals: positionals.slice(1), flags });
-    if (cmd === 'pack') return await cmdPack({ positionals: positionals.slice(1), flags });
-    if (cmd === 'install') return await cmdInstall({ positionals: positionals.slice(1), flags });
-
-    throw new Error(`Unknown command: ${cmd}`);
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error(`[chatos-uiapp] ${err?.message || String(err)}`);
-    process.exitCode = 1;
-  }
-}
+import { cmdInit } from './commands/init.js';
+import { cmdValidate } from './commands/validate.js';
+import { cmdPack } from './commands/pack.js';
+import { cmdInstall } from './commands/install.js';
+import { cmdDev } from './commands/dev.js';
+
+import { parseArgs } from './lib/args.js';
+
+function printHelp() {
+  // Keep it short; detailed docs live in README and generated project.
+  // eslint-disable-next-line no-console
+  console.log(`chatos-uiapp
+
+Usage:
+  chatos-uiapp init <dir> [--template <name>] [--force] [--plugin-id <id>] [--name <name>] [--app-id <appId>] [--version <semver>]
+  chatos-uiapp init --list-templates
+  chatos-uiapp dev [--port 4399] [--app <appId>] [--plugin-dir <path>]
+  chatos-uiapp validate [--plugin-dir <path>]
+  chatos-uiapp pack [--out <zipPath>] [--plugin-dir <path>]
+  chatos-uiapp install [--host-app chatos] [--state-dir <path>] [--plugin-dir <path>]
+
+Examples:
+  chatos-uiapp init my-app
+  chatos-uiapp init my-app --template notepad
+  chatos-uiapp init --list-templates
+  chatos-uiapp dev --port 4399
+  chatos-uiapp install --host-app chatos
+`);
+}
+
+export async function runCli(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const cmd = String(positionals[0] || '').trim();
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || flags.help) {
+    printHelp();
+    return;
+  }
+
+  try {
+    if (cmd === 'init') return await cmdInit({ positionals: positionals.slice(1), flags });
+    if (cmd === 'dev') return await cmdDev({ positionals: positionals.slice(1), flags });
+    if (cmd === 'validate') return await cmdValidate({ positionals: positionals.slice(1), flags });
+    if (cmd === 'pack') return await cmdPack({ positionals: positionals.slice(1), flags });
+    if (cmd === 'install') return await cmdInstall({ positionals: positionals.slice(1), flags });
+
+    throw new Error(`Unknown command: ${cmd}`);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(`[chatos-uiapp] ${err?.message || String(err)}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/dev.js

@@ -1,14 +1,14 @@
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir } from '../lib/plugin.js';
-import { startSandboxServer } from '../sandbox/server.js';
-
-export async function cmdDev({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-  const portRaw = String(flags.port || flags.p || '').trim();
-  const port = portRaw ? Number(portRaw) : 4399;
-  const appId = String(flags.app || flags['app-id'] || flags.appId || config?.appId || '').trim();
-
-  await startSandboxServer({ pluginDir, port, appId });
-}
-
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir } from '../lib/plugin.js';
+import { startSandboxServer } from '../sandbox/server.js';
+
+export async function cmdDev({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+  const portRaw = String(flags.port || flags.p || '').trim();
+  const port = portRaw ? Number(portRaw) : 4399;
+  const appId = String(flags.app || flags['app-id'] || flags.appId || config?.appId || '').trim();
+
+  await startSandboxServer({ pluginDir, port, appId });
+}
+

package/src/commands/init.js

@@ -1,141 +1,142 @@
-import path from 'path';
-import readline from 'readline';
-
-import { ensureDir, isDirectory, isFile, rmForce, writeText } from '../lib/fs.js';
-import {
-  copyTemplate,
-  listTemplates,
-  readTemplateMeta,
-  maybeReplaceTokensInFile,
-  writeScaffoldConfig,
-  writeScaffoldManifest,
-  writeScaffoldPackageJson,
-} from '../lib/template.js';
-
-function canPrompt() {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-
-async function promptLine(question, { defaultValue = '' } = {}) {
-  if (!canPrompt()) throw new Error(`Missing required value: ${question}`);
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await new Promise((resolve) => rl.question(question, resolve));
-    const v = String(answer || '').trim();
-    return v || defaultValue;
-  } finally {
-    rl.close();
-  }
-}
-
-export async function cmdInit({ positionals, flags }) {
-  const list = Boolean(flags['list-templates'] || flags.listTemplates);
-  if (list) {
-    const templates = listTemplates();
-    if (templates.length === 0) {
-      // eslint-disable-next-line no-console
-      console.log('No templates found.');
-      return;
-    }
-    const lines = templates.map((t) => `- ${t.name}${t.description ? `: ${t.description}` : ''}`).join('\n');
-    // eslint-disable-next-line no-console
-    console.log(`Templates:\n${lines}\n\nUse:\n  chatos-uiapp init my-app --template <name>\n`);
-    return;
-  }
-
-  const dirArg = String(positionals[0] || '').trim();
-  if (!dirArg) throw new Error('init requires <dir>');
-
-  const templateName = String(flags.template || flags.t || '').trim() || 'basic';
-  const templateMeta = readTemplateMeta(templateName);
-
-  const destDir = path.resolve(process.cwd(), dirArg);
-  const force = Boolean(flags.force);
-
-  if (isDirectory(destDir)) {
-    const entries = await (async () => {
-      try {
-        return (await import('fs')).default.readdirSync(destDir);
-      } catch {
-        return [];
-      }
-    })();
-    if (entries.length > 0 && !force) {
-      throw new Error(`Target directory is not empty: ${destDir} (use --force to overwrite)`);
-    }
-    if (force) rmForce(destDir);
-  }
-
-  ensureDir(destDir);
-  copyTemplate({ templateName, destDir });
-
-  const pluginId =
-    String(flags['plugin-id'] || flags.pluginId || '').trim() || (await promptLine('pluginId (e.g. com.example.myapp): '));
-  const pluginName =
-    String(flags.name || '').trim() ||
-    (await promptLine('plugin name (display): ', { defaultValue: String(templateMeta?.defaults?.pluginName || '').trim() || pluginId }));
-
-  const defaultAppId = String(templateMeta?.defaults?.appId || '').trim() || 'app';
-  const appId =
-    String(flags['app-id'] || flags.appId || '').trim() ||
-    (await promptLine('appId (e.g. manager): ', { defaultValue: defaultAppId }));
-
-  const version = String(flags.version || '').trim() || String(templateMeta?.defaults?.version || '').trim() || '0.1.0';
-
-  const pluginDir = path.join(destDir, 'plugin');
-  ensureDir(pluginDir);
-
-  if (!isFile(path.join(pluginDir, 'plugin.json'))) {
-    const withBackend = templateMeta?.defaults?.withBackend !== false;
-    writeScaffoldManifest({ destPluginDir: pluginDir, pluginId, pluginName, version, appId, withBackend });
-  }
-  writeScaffoldPackageJson({ destDir, projectName: path.basename(destDir) });
-  writeScaffoldConfig({ destDir, pluginDir: 'plugin', appId });
-
-  // rename template app folder "app" -> actual appId
-  const srcAppDir = path.join(pluginDir, 'apps', 'app');
-  const dstAppDir = path.join(pluginDir, 'apps', appId);
-  try {
-    const fs = (await import('fs')).default;
-    if (fs.existsSync(srcAppDir) && fs.statSync(srcAppDir).isDirectory()) {
-      ensureDir(path.dirname(dstAppDir));
-      fs.renameSync(srcAppDir, dstAppDir);
-    }
-  } catch {
-    // ignore
-  }
-
-  // Token replacements inside README/template code.
-  const replacements = {
-    __PLUGIN_ID__: pluginId,
-    __PLUGIN_NAME__: pluginName,
-    __APP_ID__: appId,
-    __VERSION__: version,
-  };
-
-  maybeReplaceTokensInFile(path.join(destDir, 'README.md'), replacements);
-  maybeReplaceTokensInFile(path.join(destDir, 'chatos.config.json'), replacements);
-  if (isFile(path.join(pluginDir, 'plugin.json'))) {
-    maybeReplaceTokensInFile(path.join(pluginDir, 'plugin.json'), replacements);
-  }
-  maybeReplaceTokensInFile(path.join(pluginDir, 'backend', 'index.mjs'), replacements);
-  maybeReplaceTokensInFile(path.join(dstAppDir, 'index.mjs'), replacements);
-  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-server.mjs'), replacements);
-  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-prompt.zh.md'), replacements);
-  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-prompt.en.md'), replacements);
-
-  // Ensure a helpful note exists even if template is edited later.
-  writeText(
-    path.join(destDir, '.gitignore'),
-    `node_modules/\n.DS_Store\n.chatos/\n*.log\n\n# build outputs (if you add bundling later)\ndist/\n`
-  );
-
-  // eslint-disable-next-line no-console
-  console.log(`Created: ${destDir}
-
-Next:
-  cd ${dirArg}
-  npm install
-  npm run dev
-`);
-}
+import path from 'path';
+import readline from 'readline';
+
+import { ensureDir, isDirectory, isFile, rmForce, writeText } from '../lib/fs.js';
+import {
+  copyTemplate,
+  listTemplates,
+  readTemplateMeta,
+  maybeReplaceTokensInFile,
+  writeScaffoldConfig,
+  writeScaffoldManifest,
+  writeScaffoldPackageJson,
+} from '../lib/template.js';
+
+function canPrompt() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function promptLine(question, { defaultValue = '' } = {}) {
+  if (!canPrompt()) throw new Error(`Missing required value: ${question}`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    const v = String(answer || '').trim();
+    return v || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function cmdInit({ positionals, flags }) {
+  const list = Boolean(flags['list-templates'] || flags.listTemplates);
+  if (list) {
+    const templates = listTemplates();
+    if (templates.length === 0) {
+      // eslint-disable-next-line no-console
+      console.log('No templates found.');
+      return;
+    }
+    const lines = templates.map((t) => `- ${t.name}${t.description ? `: ${t.description}` : ''}`).join('\n');
+    // eslint-disable-next-line no-console
+    console.log(`Templates:\n${lines}\n\nUse:\n  chatos-uiapp init my-app --template <name>\n`);
+    return;
+  }
+
+  const dirArg = String(positionals[0] || '').trim();
+  if (!dirArg) throw new Error('init requires <dir>');
+
+  const templateName = String(flags.template || flags.t || '').trim() || 'basic';
+  const templateMeta = readTemplateMeta(templateName);
+
+  const destDir = path.resolve(process.cwd(), dirArg);
+  const force = Boolean(flags.force);
+
+  if (isDirectory(destDir)) {
+    const entries = await (async () => {
+      try {
+        return (await import('fs')).default.readdirSync(destDir);
+      } catch {
+        return [];
+      }
+    })();
+    if (entries.length > 0 && !force) {
+      throw new Error(`Target directory is not empty: ${destDir} (use --force to overwrite)`);
+    }
+    if (force) rmForce(destDir);
+  }
+
+  ensureDir(destDir);
+  copyTemplate({ templateName, destDir });
+
+  const pluginId =
+    String(flags['plugin-id'] || flags.pluginId || '').trim() || (await promptLine('pluginId (e.g. com.example.myapp): '));
+  const pluginName =
+    String(flags.name || '').trim() ||
+    (await promptLine('plugin name (display): ', { defaultValue: String(templateMeta?.defaults?.pluginName || '').trim() || pluginId }));
+
+  const defaultAppId = String(templateMeta?.defaults?.appId || '').trim() || 'app';
+  const appId =
+    String(flags['app-id'] || flags.appId || '').trim() ||
+    (await promptLine('appId (e.g. manager): ', { defaultValue: defaultAppId }));
+
+  const version = String(flags.version || '').trim() || String(templateMeta?.defaults?.version || '').trim() || '0.1.0';
+
+  const pluginDir = path.join(destDir, 'plugin');
+  ensureDir(pluginDir);
+
+  if (!isFile(path.join(pluginDir, 'plugin.json'))) {
+    const withBackend = templateMeta?.defaults?.withBackend !== false;
+    writeScaffoldManifest({ destPluginDir: pluginDir, pluginId, pluginName, version, appId, withBackend });
+  }
+  writeScaffoldPackageJson({ destDir, projectName: path.basename(destDir) });
+  writeScaffoldConfig({ destDir, pluginDir: 'plugin', appId });
+
+  // rename template app folder "app" -> actual appId
+  const srcAppDir = path.join(pluginDir, 'apps', 'app');
+  const dstAppDir = path.join(pluginDir, 'apps', appId);
+  try {
+    const fs = (await import('fs')).default;
+    if (fs.existsSync(srcAppDir) && fs.statSync(srcAppDir).isDirectory()) {
+      ensureDir(path.dirname(dstAppDir));
+      fs.renameSync(srcAppDir, dstAppDir);
+    }
+  } catch {
+    // ignore
+  }
+
+  // Token replacements inside README/template code.
+  const replacements = {
+    __PLUGIN_ID__: pluginId,
+    __PLUGIN_NAME__: pluginName,
+    __APP_ID__: appId,
+    __VERSION__: version,
+  };
+
+  maybeReplaceTokensInFile(path.join(destDir, 'README.md'), replacements);
+  maybeReplaceTokensInFile(path.join(destDir, 'chatos.config.json'), replacements);
+  if (isFile(path.join(pluginDir, 'plugin.json'))) {
+    maybeReplaceTokensInFile(path.join(pluginDir, 'plugin.json'), replacements);
+  }
+  maybeReplaceTokensInFile(path.join(pluginDir, 'backend', 'index.mjs'), replacements);
+  maybeReplaceTokensInFile(path.join(dstAppDir, 'index.mjs'), replacements);
+  maybeReplaceTokensInFile(path.join(dstAppDir, 'compact.mjs'), replacements);
+  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-server.mjs'), replacements);
+  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-prompt.zh.md'), replacements);
+  maybeReplaceTokensInFile(path.join(dstAppDir, 'mcp-prompt.en.md'), replacements);
+
+  // Ensure a helpful note exists even if template is edited later.
+  writeText(
+    path.join(destDir, '.gitignore'),
+    `node_modules/\n.DS_Store\n.chatos/\n*.log\n\n# build outputs (if you add bundling later)\ndist/\n`
+  );
+
+  // eslint-disable-next-line no-console
+  console.log(`Created: ${destDir}
+
+Next:
+  cd ${dirArg}
+  npm install
+  npm run dev
+`);
+}