claude-pet 2.0.0

package/docs/superpowers/plans/2026-03-14-update-ux.md

@@ -0,0 +1,362 @@
+# Update UX Flow Improvement — Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Provide stage-by-stage native dialog feedback when users click "Check for Updates", replacing the current silent/confusing flow.
+
+**Architecture:** Centralize all manual update logic in `auto-updater.ts` via a new `checkForUpdatesManual()` function. Use `autoDownload = false` during manual checks to control timing. Localize the existing `update-downloaded` handler. Remove duplicate logic from `tray.ts` and `main.ts`.
+
+**Tech Stack:** Electron (dialog API), electron-updater, TypeScript
+
+**Spec:** `docs/superpowers/specs/2026-03-14-update-ux-design.md`
+
+---
+
+## Chunk 1: i18n keys and auto-updater refactor
+
+### Task 1: Add i18n translation keys
+
+**Files:**
+- Modify: `src/shared/i18n.ts`
+
+- [ ] **Step 1: Add new keys to `ko` locale**
+
+Add after `update_up_to_date` (line 75) in the `ko` block:
+
+```typescript
+    update_downloading: '업데이트 다운로드 중...',
+    update_check_failed: '업데이트 확인 실패',
+    update_ready_title: '업데이트 준비 완료',
+    update_ready_message: 'v{version} 설치 준비 완료. 지금 재시작할까요?',
+    update_btn_restart: '지금 재시작',
+    update_btn_later: '나중에',
+```
+
+- [ ] **Step 2: Add new keys to `en` locale**
+
+Add after `update_up_to_date` (line 146) in the `en` block:
+
+```typescript
+    update_downloading: 'Downloading update...',
+    update_check_failed: 'Update check failed',
+    update_ready_title: 'Update Ready',
+    update_ready_message: 'v{version} is ready to install. Restart now?',
+    update_btn_restart: 'Restart Now',
+    update_btn_later: 'Later',
+```
+
+- [ ] **Step 3: Add new keys to `ja` locale**
+
+Add after `update_up_to_date` (line 217) in the `ja` block:
+
+```typescript
+    update_downloading: 'アップデートをダウンロード中...',
+    update_check_failed: 'アップデートの確認に失敗しました',
+    update_ready_title: 'アップデート準備完了',
+    update_ready_message: 'v{version}のインストール準備ができました。今すぐ再起動しますか？',
+    update_btn_restart: '今すぐ再起動',
+    update_btn_later: '後で',
+```
+
+- [ ] **Step 4: Add new keys to `zh` locale**
+
+Add after `update_up_to_date` (line 288) in the `zh` block:
+
+```typescript
+    update_downloading: '正在下载更新...',
+    update_check_failed: '检查更新失败',
+    update_ready_title: '更新已准备就绪',
+    update_ready_message: 'v{version}已准备好安装。现在重启吗？',
+    update_btn_restart: '立即重启',
+    update_btn_later: '稍后',
+```
+
+- [ ] **Step 5: Verify build**
+
+Run: `cd /c/projects/Personal/claude-mama && npx tsc -p tsconfig.main.json --noEmit`
+Expected: No errors (type checking passes with new keys)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/shared/i18n.ts
+git commit -m "feat(i18n): add update UX translation keys for all locales"
+```
+
+---
+
+### Task 2: Refactor `auto-updater.ts` — localize existing handler + add `checkForUpdatesManual()`
+
+**Files:**
+- Modify: `src/main/auto-updater.ts`
+
+- [ ] **Step 1: Add imports and concurrency guard**
+
+Replace the current imports (line 1-2) with:
+
+```typescript
+import { autoUpdater } from 'electron-updater';
+import { BrowserWindow, app, dialog } from 'electron';
+import { getStore } from './ipc-handlers';
+import { t, DEFAULT_LOCALE } from '../shared/i18n';
+import { Locale } from '../shared/types';
+
+let isManualChecking = false;
+```
+
+- [ ] **Step 1b: Update `initAutoUpdater` to use imported `app` directly**
+
+In `initAutoUpdater()`, replace line 6:
+```typescript
+  if (!require('electron').app.isPackaged) return;
+```
+with:
+```typescript
+  if (!app.isPackaged) return;
+```
+
+- [ ] **Step 2: Localize the `update-downloaded` handler**
+
+Replace the existing `update-downloaded` handler (lines 15-31) with:
+
+```typescript
+  autoUpdater.on('update-downloaded', (info) => {
+    console.log(`[auto-updater] Update downloaded: v${info.version}`);
+
+    const locale = getStore().get('locale', DEFAULT_LOCALE) as Locale;
+    const win = BrowserWindow.getFocusedWindow();
+    dialog.showMessageBox(win ?? ({} as BrowserWindow), {
+      type: 'info',
+      title: t(locale, 'update_ready_title'),
+      message: t(locale, 'update_ready_message').replace('{version}', info.version),
+      buttons: [t(locale, 'update_btn_restart'), t(locale, 'update_btn_later')],
+      defaultId: 0,
+    }).then(({ response }) => {
+      if (response === 0) {
+        autoUpdater.quitAndInstall();
+      }
+    });
+  });
+```
+
+- [ ] **Step 3: Add `checkForUpdatesManual()` export**
+
+Add after the `initAutoUpdater` function (after line 43):
+
+```typescript
+export async function checkForUpdatesManual(): Promise<void> {
+  if (isManualChecking) return;
+  if (!app.isPackaged) {
+    dialog.showMessageBox({
+      type: 'info',
+      title: 'Claude Mama',
+      message: 'Auto-update is not available in dev mode.',
+    });
+    return;
+  }
+
+  isManualChecking = true;
+  const locale = getStore().get('locale', DEFAULT_LOCALE) as Locale;
+
+  // Temporarily disable autoDownload to control timing
+  autoUpdater.autoDownload = false;
+
+  try {
+    const result = await autoUpdater.checkForUpdates();
+
+    if (!result || !result.updateInfo || result.updateInfo.version === app.getVersion()) {
+      await dialog.showMessageBox({
+        type: 'info',
+        title: 'Claude Mama',
+        message: t(locale, 'update_up_to_date'),
+        detail: `v${app.getVersion()}`,
+      });
+      return;
+    }
+
+    // Update found — ask user to confirm download
+    const newVersion = result.updateInfo.version;
+    const { response } = await dialog.showMessageBox({
+      type: 'info',
+      title: 'Claude Mama',
+      message: t(locale, 'update_downloading'),
+      detail: `v${app.getVersion()} → v${newVersion}`,
+      buttons: ['OK', 'Cancel'],
+      defaultId: 0,
+    });
+
+    if (response === 0) {
+      await autoUpdater.downloadUpdate();
+      // update-downloaded handler will show restart prompt
+    }
+  } catch (err: any) {
+    await dialog.showMessageBox({
+      type: 'error',
+      title: 'Claude Mama',
+      message: t(locale, 'update_check_failed'),
+      detail: err.message,
+    });
+  } finally {
+    autoUpdater.autoDownload = true;
+    isManualChecking = false;
+  }
+}
+```
+
+- [ ] **Step 4: Verify build**
+
+Run: `cd /c/projects/Personal/claude-mama && npx tsc -p tsconfig.main.json --noEmit`
+Expected: No errors
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/main/auto-updater.ts
+git commit -m "feat(updater): add checkForUpdatesManual with staged dialogs and localization"
+```
+
+---
+
+## Chunk 2: Remove duplicate logic from tray.ts and main.ts
+
+### Task 3: Simplify `tray.ts` — use `checkForUpdatesManual()`
+
+**Files:**
+- Modify: `src/main/tray.ts`
+
+- [ ] **Step 1: Replace `autoUpdater` import with `checkForUpdatesManual`**
+
+Replace line 3:
+```typescript
+import { autoUpdater } from 'electron-updater';
+```
+with:
+```typescript
+import { checkForUpdatesManual } from './auto-updater';
+```
+
+- [ ] **Step 2: Replace inline update logic**
+
+Replace the entire update menu item click handler (lines 84-97):
+
+```typescript
+      click: async () => {
+        if (!app.isPackaged) {
+          dialog.showMessageBox({ type: 'info', title: 'Claude Mama', message: 'Auto-update is not available in dev mode.' });
+          return;
+        }
+        try {
+          const result = await autoUpdater.checkForUpdates();
+          if (!result || !result.updateInfo || result.updateInfo.version === app.getVersion()) {
+            dialog.showMessageBox({ type: 'info', title: 'Claude Mama', message: t(locale, 'update_up_to_date') });
+          }
+        } catch (err: any) {
+          dialog.showMessageBox({ type: 'error', title: 'Claude Mama', message: `Update check failed: ${err.message}` });
+        }
+      },
+```
+
+with:
+
+```typescript
+      click: () => { void checkForUpdatesManual(); },
+```
+
+- [ ] **Step 3: Remove unused imports**
+
+Remove `app` and `dialog` from the Electron import if they are no longer used elsewhere in this file. Check: `app` is used on lines 33, 79, 85-86 — `app` is still needed (line 33, 79). `dialog` is only used in the update handler — remove `dialog` from the import.
+
+- [ ] **Step 4: Verify build**
+
+Run: `cd /c/projects/Personal/claude-mama && npx tsc -p tsconfig.main.json --noEmit`
+Expected: No errors
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/main/tray.ts
+git commit -m "refactor(tray): use centralized checkForUpdatesManual"
+```
+
+---
+
+### Task 4: Simplify `main.ts` — use `checkForUpdatesManual()`
+
+**Files:**
+- Modify: `src/main/main.ts`
+
+- [ ] **Step 1: Replace inline update logic in context menu**
+
+Replace the update menu item click handler (lines 293-306):
+
+```typescript
+        click: async () => {
+          if (!app.isPackaged) {
+            dialog.showMessageBox({ type: 'info', title: 'Claude Mama', message: 'Auto-update is not available in dev mode.' });
+            return;
+          }
+          try {
+            const result = await autoUpdater.checkForUpdates();
+            if (!result || !result.updateInfo || result.updateInfo.version === app.getVersion()) {
+              dialog.showMessageBox({ type: 'info', title: 'Claude Mama', message: t(locale, 'update_up_to_date') });
+            }
+          } catch (err: any) {
+            dialog.showMessageBox({ type: 'error', title: 'Claude Mama', message: `Update check failed: ${err.message}` });
+          }
+        },
+```
+
+with:
+
+```typescript
+        click: () => { void checkForUpdatesManual(); },
+```
+
+- [ ] **Step 2: Update imports**
+
+Add `checkForUpdatesManual` to the import from `./auto-updater`:
+
+Replace line 14:
+```typescript
+import { initAutoUpdater } from './auto-updater';
+```
+with:
+```typescript
+import { initAutoUpdater, checkForUpdatesManual } from './auto-updater';
+```
+
+Remove `autoUpdater` import (line 18):
+```typescript
+import { autoUpdater } from 'electron-updater';
+```
+Delete this line entirely.
+
+- [ ] **Step 3: Verify build**
+
+Run: `cd /c/projects/Personal/claude-mama && npx tsc -p tsconfig.main.json --noEmit`
+Expected: No errors
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/main/main.ts
+git commit -m "refactor(main): use centralized checkForUpdatesManual"
+```
+
+---
+
+### Task 5: Final verification
+
+- [ ] **Step 1: Full build**
+
+Run: `cd /c/projects/Personal/claude-mama && npm run build`
+Expected: Build succeeds with no errors
+
+- [ ] **Step 2: Verify no remaining `autoUpdater` imports in tray/main**
+
+Run: `grep -n "from 'electron-updater'" src/main/tray.ts src/main/main.ts`
+Expected: No matches (only `auto-updater.ts` should import from `electron-updater`)
+
+- [ ] **Step 3: Commit (if any cleanup needed)**
+
+Only if fixups were required in previous steps.