mdk-skills 2.1.3 → 2.1.5

package/.claude/profiles.json

@@ -0,0 +1,107 @@
+// {
+//   "version": 1,
+//   "profiles": [
+//     {
+//       "id": "vue3-frontend",
+//       "name": "前端 Vue3 开发",
+//       "description": "Vue 3 + 业务模式库 + 设计 + 代码审查",
+//       "skills": ["vue", "v3-fe-biz-patterns", "frontend-design", "frontend-code-review", "ui-ux-pro-max"],
+//       "always_apply": ["vue", "frontend-design", "frontend-code-review", "ui-ux-pro-max"]
+//     },
+//     {
+//       "id": "react-frontend",
+//       "name": "前端 React 开发",
+//       "description": "设计 + 审查 + 通用前端能力",
+//       "skills": ["frontend-design", "frontend-code-review", "ui-ux-pro-max"],
+//       "always_apply": ["frontend-design", "frontend-code-review", "ui-ux-pro-max"]
+//     },
+//     {
+//       "id": "backend",
+//       "name": "java后端开发",
+//       "description": "API 设计、数据库、java 后端技能",
+//       "skills": [],
+//       "always_apply": []
+//     },
+//     {
+//       "id": "backend",
+//       "name": "python后端开发",
+//       "description": "API 设计、数据库、python 后端技能",
+//       "skills": [],
+//       "always_apply": []
+//     },
+//     {
+//       "id": "backend",
+//       "name": "nodeJs后端开发",
+//       "description": "API 设计、数据库、nodeJs 后端技能",
+//       "skills": [],
+//       "always_apply": []
+//     },
+//     {
+//       "id": "custom",
+//       "name": "自定义选择",
+//       "description": "按需勾选每一个技能",
+//       "skills": null
+//     }
+//   ]
+// }
+{
+  "version": 1,
+  "profiles": [
+    {
+      "id": "vue3-frontend",
+      "name": "Vue3 前端专项",
+      "description": "Vue3 技术栈 | 业务架构 | 界面设计 | 代码规范评审",
+      "skills": [
+        "vue",
+        "v3-fe-biz-patterns",
+        "frontend-design",
+        "frontend-code-review",
+        "ui-ux-pro-max"
+      ],
+      "always_apply": [
+        "vue",
+        "frontend-design",
+        "frontend-code-review",
+        "ui-ux-pro-max"
+      ]
+    },
+    {
+      "id": "react-frontend",
+      "name": "React 前端专项",
+      "description": "React 技术栈 | 界面设计 | 代码评审 | 通用前端能力",
+      "skills": ["frontend-design", "frontend-code-review", "ui-ux-pro-max"],
+      "always_apply": [
+        "frontend-design",
+        "frontend-code-review",
+        "ui-ux-pro-max"
+      ]
+    },
+    {
+      "id": "backend-java",
+      "name": "Java 后端开发",
+      "description": "接口架构设计 | 数据库建模 | Java 后端体系能力",
+      "skills": [],
+      "always_apply": []
+    },
+    {
+      "id": "backend-python",
+      "name": "Python 后端开发",
+      "description": "接口架构设计 | 数据层设计 | Python 后端体系能力",
+      "skills": [],
+      "always_apply": []
+    },
+    {
+      "id": "backend-node",
+      "name": "Node.js 后端开发",
+      "description": "接口架构设计 | 服务端架构 | Node 后端体系能力",
+      "skills": [],
+      "always_apply": []
+    },
+    {
+      "id": "custom",
+      "name": "自定义技能组合",
+      "description": "自由勾选技能项，按需个性化配置",
+      "skills": null
+    }
+  ]
+}

package/.claude/settings.json

@@ -1,21 +1,5 @@
 {
   "skills": {
-    "simplify": {
-      "enabled": true,
-      "description": "审查变更代码，确保复用性、质量和效率"
-    },
-    "loop": {
-      "enabled": true,
-      "description": "按固定间隔重复执行提示词或命令"
-    },
-    "claude-api": {
-      "enabled": true,
-      "description": "构建、调试和优化 Claude API / Anthropic SDK 应用"
-    },
-    "agentation": {
-      "enabled": true,
-      "description": "Agentation React 可视化反馈工具栏"
-    },
     "frontend-code-review": {
       "enabled": true,
       "description": "前端代码全面审查"
@@ -36,29 +20,15 @@
       "enabled": true,
       "description": "Vue 3 组件/组合式函数开发，提供 Composition API 最佳实践"
     },
-    "init": {
-      "enabled": true,
-      "description": "初始化 CLAUDE.md 项目文档"
-    },
-    "review": {
-      "enabled": true,
-      "description": "Pull Request 代码审查"
-    },
-    "security-review": {
-      "enabled": true,
-      "description": "待变更代码安全审查"
-    },
-    "fe-biz-patterns": {
+    "v3-fe-biz-patterns": {
       "enabled": true,
       "description": "前端业务模式库，loading/滚动加载/导入导出/批量操作/表单联动/大列表渲染/Service层封装/Pinia Store模式/分页数据管理等常见业务场景"
     }
   },
   "always_apply_skills": [
-    "simplify",
     "frontend-design",
     "vue",
     "frontend-code-review",
-    "ui-ux-pro-max",
-    "security-review"
+    "ui-ux-pro-max"
   ]
 }

package/.claude/skills/v3-fe-biz-patterns/.meta.json

@@ -0,0 +1,6 @@
+{
+  "name": "v3-fe-biz-patterns",
+  "version": "1.0.0",
+  "description": "MaDeKang的Vue3相关前端业务模式库，收录MaDeKang在前端业务中沉淀的方案和最佳实践",
+  "tags": ["frontend", "pattern", "vue3"]
+}

package/.claude/skills/{fe-biz-patterns → v3-fe-biz-patterns}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: fe-biz-patterns
-description: 前端业务模式库，收录 XiaoMa 在实际业务中沉淀的前端方案和最佳实践。当用户要求实现包含以下特征的功能时使用：loading/加载/加载态、滚动加载/无限滚动/触底加载、数据导入导出、批量操作、表单联动、权限控制、大列表渲染、文件上传、实时搜索、拖拽排序、Service层封装/请求层/axios封装、Pinia Store模式/状态管理/分页数据管理、Tab 锚点/TabAnchor/带锚点滚动的 Tab 切换/吸顶 Tab 栏/浮动 Tab 栏/Tab 滑动指示器等常见前端业务场景。
+name: v3-fe-biz-patterns
+description: 前端Vue3业务模式库，收录 MaDeKang 在实际业务中沉淀的前端方案和最佳实践。当用户要求实现包含以下特征的功能时使用：loading/加载/加载态、滚动加载/无限滚动/触底加载、数据导入导出、批量操作、表单联动、权限控制、大列表渲染、文件上传、实时搜索、拖拽排序、Service层封装/请求层/axios封装、Pinia Store模式/状态管理/分页数据管理、Tab 锚点/TabAnchor/带锚点滚动的 Tab 切换/吸顶 Tab 栏/浮动 Tab 栏/Tab 滑动指示器等常见前端业务场景。
 ---
 
 # 前端业务模式库
 
-XiaoMa 实战沉淀的前端业务方案集合，覆盖日常开发中高频出现的业务场景。
+MaDeKang 实战沉淀的前端业务方案集合，覆盖日常开发中高频出现的业务场景。
 
 每个方案独立成篇，按需加载，避免上下文浪费。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdk-skills",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "mdk-engineer - 沉稳靠谱的前端开发助手 Claude Skills 配置包，一键注入 .claude/ 技能目录和 CLAUDE.md 人设配置",
   "author": "XiaoMa",
   "license": "MIT",

package/scripts/cli.js

@@ -115,6 +115,159 @@ function installSelectedSkills(selectedNames) {
   return installedCount;
 }
 
+// ---------- 场景选择（场景 → 一键装技能） ----------
+
+function loadProfiles() {
+  const profilesPath = path.join(packageDir, ".claude", "profiles.json");
+  if (!fs.existsSync(profilesPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(profilesPath, "utf-8")).profiles;
+  } catch {
+    return null;
+  }
+}
+
+function applyProfile(profile) {
+  const pkgSkills = fs.readdirSync(pkgSkillsSource);
+  const settings = readSettings();
+
+  // 确定要启用的技能列表
+  let selected;
+  if (profile.skills === null) {
+    // null 表示"自定义"，不做操作，由调用方处理
+    return;
+  } else if (profile.skills.length === 0) {
+    selected = [];
+  } else {
+    // 只取包内实际存在的技能
+    selected = profile.skills.filter((s) => pkgSkills.includes(s));
+  }
+
+  // 装启用的、删禁用的
+  if (!fs.existsSync(skillsDest)) {
+    fs.mkdirSync(skillsDest, { recursive: true });
+  }
+  for (const name of pkgSkills) {
+    const src = path.join(pkgSkillsSource, name);
+    const dest = path.join(skillsDest, name);
+    if (selected.includes(name)) {
+      if (!fs.existsSync(dest)) {
+        try {
+          copyDirSync(src, dest);
+        } catch (err) {
+          console.error(`  ❌ 安装技能 "${name}" 失败:`, err.message);
+        }
+      }
+    } else {
+      if (fs.existsSync(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // 更新 settings
+  if (!settings.skills) settings.skills = {};
+  for (const name of pkgSkills) {
+    const enabled = selected.includes(name);
+    if (!settings.skills[name]) settings.skills[name] = {};
+    settings.skills[name].enabled = enabled;
+  }
+
+  // 更新 always_apply_skills
+  if (profile.always_apply) {
+    settings.always_apply_skills = profile.always_apply;
+  }
+
+  // 记录当前活动场景
+  settings._active_profile = profile.id;
+  writeSettings(settings);
+
+  // 安装 CLAUDE.md（没有才装）
+  const mdSource = path.join(packageDir, "CLAUDE.md");
+  const mdDest = path.join(projectRoot, "CLAUDE.md");
+  if (fs.existsSync(mdSource) && !fs.existsSync(mdDest)) {
+    fs.copyFileSync(mdSource, mdDest);
+    console.log("  📝 CLAUDE.md 已创建\n");
+  }
+
+  // 输出结果
+  const enabledCount = selected.length;
+  const disabledCount = pkgSkills.length - enabledCount;
+  console.log(`\n  ✅ 已切换到「${profile.name}」`);
+  console.log(`    启用 ${enabledCount} 个技能，停用 ${disabledCount} 个\n`);
+}
+
+async function startSceneSelection() {
+  const { select } = await import("@inquirer/prompts");
+  const chalk = (await import("chalk")).default;
+  const profiles = loadProfiles();
+  const settings = readSettings();
+  const activeProfile = settings._active_profile;
+  const hasExistingInstall = fs.existsSync(claudeDest);
+
+  const choices = profiles.map((p) => {
+    const isActive = p.id === activeProfile;
+    const prefix = isActive ? chalk.green("● ") : "  ";
+    return {
+      name: prefix + p.name,
+      value: p.id,
+      description: isActive
+        ? chalk.dim("当前场景 · ") + (p.description || "")
+        : p.description || "",
+    };
+  });
+
+  // 底部加个分隔
+  choices.push(
+    { name: chalk.dim("────────────────"), value: "__sep__", description: "" },
+    { name: "  查看技能清单", value: "__list__", description: "列出所有技能状态" },
+  );
+
+  const selectedId = await select({
+    message: hasExistingInstall
+      ? "选择开发场景（切换将自动调整技能）"
+      : "选择你的开发场景",
+    instructions: `(↑↓ 导航, Enter 确认)`,
+    choices,
+    pageSize: 10,
+    loop: false,
+  });
+
+  if (selectedId === "__sep__") {
+    return startSceneSelection();
+  }
+
+  if (selectedId === "__list__") {
+    await cmdList();
+    // 看完列表再回到场景选择
+    console.log("");
+    return startSceneSelection();
+  }
+
+  const profile = profiles.find((p) => p.id === selectedId);
+
+  if (profile.skills === null) {
+    // "自定义选择" → 跳到 checkbox
+    await startInteractiveMenu();
+    return;
+  }
+
+  if (profile.id === activeProfile) {
+    // 选的已经是当前场景，问要不要微调
+    const { confirm } = await import("@inquirer/prompts");
+    const tweak = await confirm({
+      message: "已是当前场景，是否进入自定义模式微调技能？",
+      default: false,
+    });
+    if (tweak) {
+      await startInteractiveMenu();
+    }
+    return;
+  }
+
+  applyProfile(profile);
+}
+
 // ---------- 命令：list ----------
 
 async function cmdList() {
@@ -156,7 +309,7 @@ async function cmdList() {
   }
 
   console.log(
-    `\n  ${chalk.cyan("💡")} ${chalk.dim("运行 npx mdk-skills 进入交互选择模式")}\n`,
+    `\n  ${chalk.cyan("💡")} ${chalk.dim("运行 npx mdk-skills 进入场景选择")}\n`,
   );
 }
 
@@ -229,17 +382,24 @@ async function main() {
   const args = process.argv.slice(3);
 
   if (!command) {
-    await startInteractiveMenu();
+    const profiles = loadProfiles();
+    if (profiles) {
+      await startSceneSelection();
+    } else {
+      // 没有 profiles.json 时回退到原来的 checkbox
+      await startInteractiveMenu();
+    }
   } else if (command === "--help" || command === "-h") {
     console.log(`
   mdk-skills CLI
 
   用法:
-    npx mdk-skills             交互式选择并安装技能
+    npx mdk-skills             场景选择 → 一键安装对应技能
     npx mdk-skills list        查看已安装的技能
     npx mdk-skills --help      显示帮助
 
-  首次运行会自动创建 .claude/ 目录，勾选要安装的技能即可
+  首次运行选择场景后自动配置技能和 CLAUDE.md
+  再次运行可切换场景或进入自定义模式微调
 
   示例:
     npx mdk-skills

package/.claude/.install.log

@@ -1,4 +0,0 @@
-[2026-05-09 20:45:26] [INFO] Install started (upgrade)
-[2026-05-09 20:45:38] [INFO] Install started (upgrade)
-[2026-05-09 20:46:37] [INFO] Install started (upgrade)
-[2026-05-09 20:47:06] [INFO] Install started (upgrade)

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__chrome-devtools__evaluate_script"
-    ]
-  }
-}

package/.claude/skills/agentation/.meta.json

@@ -1,6 +0,0 @@
-{
-  "name": "agentation",
-  "version": "1.0.0",
-  "description": "Agentation React 可视化反馈工具栏",
-  "tags": ["react", "ui", "debug"]
-}

package/.claude/skills/agentation/SKILL.md

@@ -1,107 +0,0 @@
----
-name: agentation
-description: Add Agentation visual feedback toolbar to any React project
----
-
-# Agentation Setup
-
-Set up the Agentation annotation toolbar in this project.
-
-## Requirements
-
-- React 18+
-- Zero dependencies beyond React
-
-## Steps
-
-1. **Check if already installed**
-   - Look for `agentation` in package.json dependencies
-   - If not found, run `npm install agentation` (or pnpm/yarn based on lockfile)
-
-2. **Check if already configured**
-   - Search for `<Agentation` or `import { Agentation }` in src/ or app/
-   - If found, report that Agentation is already set up and exit
-
-3. **Detect project type**
-   - **Next.js App Router**: has `app/layout.tsx` or `app/layout.js`
-   - **Next.js Pages Router**: has `pages/_app.tsx` or `pages/_app.js`
-   - **Vite + React**: has `vite.config.ts/js` and `src/main.tsx/jsx`
-   - **Create React App**: has `src/index.tsx/jsx` or `src/App.tsx/jsx`
-   - **Other React projects**: look for main entry file
-
-4. **Add the component**
-
-   **For Next.js App Router**, add to `app/layout.tsx`:
-   ```tsx
-   import { Agentation } from "agentation";
-
-   export default function RootLayout({ children }) {
-     return (
-       <html>
-         <body>
-           {children}
-           {process.env.NODE_ENV === "development" && <Agentation />}
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   **For Next.js Pages Router**, add to `pages/_app.tsx`:
-   ```tsx
-   import { Agentation } from "agentation";
-
-   export default function App({ Component, pageProps }) {
-     return (
-       <>
-         <Component {...pageProps} />
-         {process.env.NODE_ENV === "development" && <Agentation />}
-       </>
-     );
-   }
-   ```
-
-   **For Vite + React**, add to `src/main.tsx`:
-   ```tsx
-   import { Agentation } from "agentation";
-
-   ReactDOM.createRoot(document.getElementById('root')!).render(
-     <React.StrictMode>
-       <App />
-       {import.meta.env.DEV && <Agentation />}
-     </React.StrictMode>
-   );
-   ```
-
-   **For Create React App**, add to `src/index.tsx`:
-   ```tsx
-   import { Agentation } from "agentation";
-
-   const root = ReactDOM.createRoot(document.getElementById('root'));
-   root.render(
-     <React.StrictMode>
-       <App />
-       {process.env.NODE_ENV === "development" && <Agentation />}
-     </React.StrictMode>
-   );
-   ```
-
-   **For other React projects**, add to the root component or main entry file:
-   ```tsx
-   import { Agentation } from "agentation";
-
-   // Add at the end of your root component
-   {process.env.NODE_ENV === "development" && <Agentation />}
-   ```
-
-5. **Confirm setup**
-   - Tell the user to run their dev server and look for the Agentation toolbar (floating button in bottom-right corner)
-   - The toolbar should appear in the bottom-right corner of the page
-
-## Notes
-
-- The environment check ensures Agentation only loads in development
-- For Vite projects, use `import.meta.env.DEV` instead of `process.env.NODE_ENV`
-- For Next.js, use `process.env.NODE_ENV === "development"`
-- No additional configuration needed — it works out of the box
-- Compatible with any React 18+ project

package/.claude/skills/fe-biz-patterns/.meta.json

@@ -1,6 +0,0 @@
-{
-  "name": "fe-biz-patterns",
-  "version": "1.0.0",
-  "description": "小马自己的前端业务模式库，收录小马在前端业务中沉淀的方案和最佳实践",
-  "tags": ["frontend", "pattern", "vue", "react"]
-}

package/.claude/skills/moai-framework-electron/.meta.json

@@ -1,6 +0,0 @@
-{
-  "name": "moai-framework-electron",
-  "version": "1.0.0",
-  "description": "Electron 桌面应用开发，含主进程/渲染进程/IPC/自动更新/打包",
-  "tags": ["electron", "desktop", "node"]
-}

package/.claude/skills/moai-framework-electron/SKILL.md

@@ -1,328 +0,0 @@
----
-name: moai-framework-electron
-description: >
-  Electron 33+ desktop app development specialist covering Main/Renderer
-  process architecture, IPC communication, auto-update, and packaging with
-  Electron Forge. Use when building cross-platform desktop applications.
-license: Apache-2.0
-compatibility: Designed for Claude Code
-allowed-tools: Read, Grep, Glob, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
-user-invocable: false
-metadata:
-  version: "2.0.0"
-  category: "framework"
-  status: "active"
-  updated: "2026-01-10"
-  modularized: "false"
-  tags: "electron, desktop, cross-platform, nodejs, chromium, ipc, auto-update, electron-builder, electron-forge"
-  context7-libraries: "/electron/electron, /electron/forge, /electron-userland/electron-builder"
-  related-skills: "moai-lang-typescript, moai-domain-frontend, moai-lang-javascript"
----
-
-# Electron 33+ Desktop Development
-
-## Quick Reference
-
-Electron 33+ Desktop App Development Specialist enables building cross-platform desktop applications with web technologies.
-
-Auto-Triggers: Electron projects detected via electron.vite.config.ts or electron-builder.yml files, desktop app development requests, IPC communication pattern implementation
-
-### Core Capabilities
-
-Electron 33 Platform:
-
-- Chromium 130 rendering engine for modern web features
-- Node.js 20.18 runtime for native system access
-- Native ESM support in main process
-- WebGPU API support for GPU-accelerated graphics
-
-Process Architecture:
-
-- Main process runs as single instance per application with full Node.js access
-- Renderer processes display web content in sandboxed environments
-- Preload scripts bridge main and renderer with controlled API exposure
-- Utility processes handle background tasks without blocking UI
-
-IPC Communication:
-
-- Type-safe invoke/handle patterns for request-response communication
-- contextBridge API for secure renderer access to main process functionality
-- Event-based messaging for push notifications from main to renderer
-
-Auto-Update Support:
-
-- electron-updater integration with GitHub and S3 publishing
-- Differential updates for smaller download sizes
-- Update notification and installation management
-
-Packaging Options:
-
-- Electron Forge for integrated build tooling and plugin ecosystem
-- electron-builder for flexible multi-platform distribution
-
-Security Features:
-
-- contextIsolation for preventing prototype pollution
-- Sandbox enforcement for renderer process isolation
-- Content Security Policy configuration
-- Input validation patterns for IPC handlers
-
-### Project Initialization
-
-Creating a new Electron application requires running the create-electron-app command with the vite-typescript template. Install electron-builder as a development dependency for packaging. Add electron-updater as a runtime dependency for auto-update functionality.
-
-For detailed commands and configuration, see reference.md Quick Commands section.
-
----
-
-## Implementation Guide
-
-### Project Structure
-
-Recommended Directory Layout:
-
-The source directory should contain four main subdirectories:
-
-Main Directory: Contains the main process entry point, IPC handler definitions organized by domain, business logic services, and window management modules
-
-Preload Directory: Contains the preload script entry point and exposed API definitions that bridge main and renderer
-
-Renderer Directory: Contains the web application built with React, Vue, or Svelte, including the HTML entry point and Vite configuration
-
-Shared Directory: Contains TypeScript types and constants shared between main and renderer processes
-
-The project root should include the electron.vite.config.ts for build configuration, electron-builder.yml for packaging options, and resources directory for app icons and assets.
-
-### Main Process Setup
-
-Application Lifecycle Management:
-
-The main process initialization follows a specific sequence. First, enable sandbox globally using app.enableSandbox() to ensure all renderer processes run in isolated environments. Then request single instance lock to prevent multiple app instances from running simultaneously.
-
-Window creation should occur after the app ready event fires. Configure BrowserWindow with security-focused webPreferences including contextIsolation enabled, nodeIntegration disabled, sandbox enabled, and webSecurity enabled. Set the preload script path to expose safe APIs to the renderer.
-
-Handle platform-specific behaviors: on macOS, re-create windows when the dock icon is clicked if no windows exist. On other platforms, quit the application when all windows close.
-
-For implementation examples, see examples.md Main Process Entry Point section.
-
-### Type-Safe IPC Communication
-
-IPC Type Definition Pattern:
-
-Define an interface that maps channel names to their payload types. Group channels by domain such as file operations, window operations, and storage operations. This enables type checking for both main process handlers and renderer invocations.
-
-Main Process Handler Registration:
-
-Register IPC handlers in a dedicated module that imports from the shared types. Each handler should validate input using a schema validation library such as Zod before processing. Use ipcMain.handle for request-response patterns and return structured results.
-
-Preload Script Implementation:
-
-Create an API object that wraps ipcRenderer.invoke calls for each channel. Use contextBridge.exposeInMainWorld to make this API available in the renderer as window.electronAPI. Include cleanup functions for event listeners to prevent memory leaks.
-
-For complete IPC implementation patterns, see examples.md Type-Safe IPC Implementation section.
-
-### Security Best Practices
-
-Mandatory Security Settings:
-
-Every BrowserWindow must have webPreferences configured with four critical settings. contextIsolation must always be enabled to prevent renderer code from accessing Electron internals. nodeIntegration must always be disabled in renderer processes. sandbox must always be enabled for process-level isolation. webSecurity must never be disabled to maintain same-origin policy enforcement.
-
-Content Security Policy:
-
-Configure session-level CSP headers using webRequest.onHeadersReceived. Restrict default-src to self, script-src to self without unsafe-inline, and connect-src to allowed API domains. This prevents XSS attacks and unauthorized resource loading.
-
-Input Validation:
-
-Every IPC handler must validate inputs before processing. Prevent path traversal attacks by rejecting paths containing parent directory references. Validate file names against reserved characters. Use allowlists for permitted directories when implementing file access.
-
-For security implementation details, see reference.md Security Best Practices section.
-
-### Auto-Update Implementation
-
-Update Service Architecture:
-
-Create an UpdateService class that manages the electron-updater lifecycle. Initialize with the main window reference to enable UI notifications. Configure autoDownload as false to give users control over bandwidth usage.
-
-Event Handling:
-
-Handle update-available events by notifying the renderer and prompting the user for download confirmation. Track download-progress events to display progress indicators. Handle update-downloaded events by prompting for restart.
-
-User Notification Pattern:
-
-Use system dialogs to prompt users when updates are available and when downloads complete. Send events to the renderer for in-app notification display. Support both immediate and deferred installation.
-
-For complete update service implementation, see examples.md Auto-Update Integration section.
-
-### App Packaging
-
-Electron Builder Configuration:
-
-Configure the appId with reverse-domain notation for platform registration. Specify productName for display in system UI. Set up platform-specific targets for macOS, Windows, and Linux.
-
-macOS Configuration:
-
-Set category for App Store classification. Enable hardenedRuntime and configure entitlements for notarization. Configure universal builds targeting both x64 and arm64 architectures.
-
-Windows Configuration:
-
-Specify icon path for executable and installer. Configure NSIS installer options including installation directory selection. Set up code signing with appropriate hash algorithms.
-
-Linux Configuration:
-
-Configure category for desktop environment integration. Set up multiple targets including AppImage for universal distribution and deb/rpm for package manager installation.
-
-For complete configuration examples, see reference.md Configuration section.
-
----
-
-## Advanced Patterns
-
-For comprehensive documentation on advanced topics, see reference.md and examples.md:
-
-Window State Persistence:
-
-- Saving and restoring window position and size across sessions
-- Handling multiple displays and display changes
-- Managing maximized and fullscreen states
-
-Multi-Window Management:
-
-- Creating secondary windows with proper parent-child relationships
-- Sharing state between multiple windows
-- Coordinating window lifecycle events
-
-System Tray and Native Menus:
-
-- Creating and updating system tray icons with context menus
-- Building application menus with keyboard shortcuts
-- Platform-specific menu patterns for macOS and Windows
-
-Utility Processes:
-
-- Spawning utility processes for CPU-intensive background tasks
-- Communicating with utility processes via MessageChannel
-- Managing utility process lifecycle and error handling
-
-Native Module Integration:
-
-- Rebuilding native modules for Electron Node.js version
-- Using better-sqlite3 for local database storage
-- Integrating keytar for secure credential storage
-
-Protocol Handlers and Deep Linking:
-
-- Registering custom URL protocols for app launching
-- Handling deep links on different platforms
-- OAuth callback handling via custom protocols
-
-Performance Optimization:
-
-- Lazy loading windows and heavy modules
-- Optimizing startup time with deferred initialization
-- Memory management for long-running applications
-
----
-
-## Works Well With
-
-- moai-lang-typescript - TypeScript patterns for type-safe Electron development
-- moai-domain-frontend - React, Vue, or Svelte renderer development
-- moai-lang-javascript - Node.js patterns for main process
-- moai-domain-backend - Backend API integration
-- moai-workflow-testing - Testing strategies for desktop apps
-
----
-
-## Troubleshooting
-
-Common Issues and Solutions:
-
-White Screen on Launch:
-
-Verify the preload script path is correctly configured relative to the built output directory. Check that loadFile or loadURL paths point to existing files. Enable devTools to inspect console errors. Review CSP settings that may block script execution.
-
-IPC Not Working:
-
-Confirm channel names match exactly between main handlers and renderer invocations. Ensure handlers are registered before windows load content. Verify contextBridge usage follows the correct pattern with exposeInMainWorld.
-
-Native Modules Fail:
-
-Run electron-rebuild after npm install to recompile native modules. Match the Node.js version embedded in Electron. Add a postinstall script to automate rebuilding.
-
-Auto-Update Not Working:
-
-Verify the application is code-signed as updates require signing. Check publish configuration in electron-builder.yml. Enable electron-updater logging to diagnose connection issues. Review firewall settings that may block update checks.
-
-Debug Commands:
-
-Rebuild native modules with npx electron-rebuild. Check Electron version with npx electron --version. Enable verbose update logging with DEBUG=electron-updater environment variable.
-
----
-
-## Resources
-
-For complete code examples and configuration templates, see:
-
-- reference.md - Detailed API documentation, version matrix, Context7 library mappings
-- examples.md - Production-ready code examples for all patterns
-
-For latest documentation, use Context7 to query:
-
-- /electron/electron for core Electron APIs
-- /electron/forge for Electron Forge tooling
-- /electron-userland/electron-builder for packaging configuration
-
----
-
-Version: 2.0.0
-Last Updated: 2026-01-10
-Changes: Restructured to comply with CLAUDE.md Documentation Standards - removed all code examples, converted to narrative text format
-
-<!-- moai:evolvable-start id="rationalizations" -->
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "I can use Node.js APIs directly in the renderer process" | Renderer process runs untrusted content. Direct Node.js access is a remote code execution vector. Use IPC through the preload bridge. |
-| "contextIsolation is unnecessary since I trust my own code" | Context isolation prevents prototype pollution from web content reaching Node.js. It is not about trusting your code, it is about isolating contexts. |
-| "Auto-update can be configured after release" | Shipping without auto-update means users stay on vulnerable versions. Configure it before the first release. |
-| "I will package the app later, development builds are enough for testing" | Development builds have different file paths, permissions, and code signing. Only production-packaged builds reveal real distribution issues. |
-| "IPC is slow, I will share state through global variables" | IPC overhead is microseconds. Global variables bypass process isolation, which exists for security. |
-
-<!-- moai:evolvable-end -->
-
-<!-- moai:evolvable-start id="red-flags" -->
-## Red Flags
-
-- nodeIntegration set to true in BrowserWindow options
-- contextIsolation set to false without documented security justification
-- Renderer process imports directly from electron or node modules (bypass preload)
-- No auto-update mechanism configured
-- IPC handler does not validate or sanitize arguments from renderer
-
-<!-- moai:evolvable-end -->
-
-<!-- moai:evolvable-start id="verification" -->
-## Verification
-
-- [ ] nodeIntegration is false and contextIsolation is true in all BrowserWindows
-- [ ] All renderer-to-main communication uses contextBridge and IPC
-- [ ] IPC handlers validate input arguments before processing
-- [ ] Auto-update configured and tested (show update configuration)
-- [ ] Application packages successfully with Electron Forge (show build output)
-- [ ] No direct require('electron') in renderer process code
-
-<!-- moai:evolvable-end -->
-
-## Telemetry Window
-
-**Status**: UNCLEAR (60-day window)
-**R4 audit verdict**: KEEP (monitor)
-**SPEC**: SPEC-V3R2-WF-001 §6.2 (REQ-WF001-013)
-**Window start**: 2026-04-25 (Wave 1.5 commit date)
-**Window end**: 2026-06-24 (60 days)
-**Re-audit trigger**: SessionStart hook activation count for this skill
-**Decision criteria**:
-- If activation count >= 5 during window → retain permanently
-- If activation count = 0 during window → schedule RETIRE in v3.1
-- If 0 < count < 5 → retain with "low-use" tag