|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +LinuxDo Scripts is a browser extension built with WXT framework and Vue 3 that enhances the LinuxDo forum experience. It provides features like AI assistance, bookmark management, content filtering, theme customization, and various UI improvements. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Development (Chrome) |
| 13 | +npm run dev |
| 14 | + |
| 15 | +# Development (Firefox) |
| 16 | +npm run dev:firefox |
| 17 | + |
| 18 | +# Build for production |
| 19 | +npm run build |
| 20 | + |
| 21 | +# Build for Firefox |
| 22 | +npm run build:firefox |
| 23 | + |
| 24 | +# Create distribution zip files |
| 25 | +npm run zip |
| 26 | +npm run zip:firefox |
| 27 | + |
| 28 | +# Full publish workflow (build + zip + python script) |
| 29 | +npm run publish |
| 30 | + |
| 31 | +# TypeScript type checking |
| 32 | +npm run compile |
| 33 | + |
| 34 | +# Clean install |
| 35 | +npm run rf && npm install |
| 36 | +``` |
| 37 | + |
| 38 | +## Project Architecture |
| 39 | + |
| 40 | +### Core Technologies |
| 41 | +- **Framework**: WXT (Web Extension Framework) v0.19.13 |
| 42 | +- **UI Framework**: Vue 3 with TypeScript |
| 43 | +- **Component Library**: Arco Design Vue + Element Plus |
| 44 | +- **Styling**: Less + Sass |
| 45 | +- **Build Tool**: Vite (via WXT) |
| 46 | + |
| 47 | +### Entry Points Structure |
| 48 | + |
| 49 | +``` |
| 50 | +entrypoints/ |
| 51 | +├── background.ts # Background service worker - handles messaging, API proxies, click behavior |
| 52 | +├── content.js # Content script - injects Vue app into LinuxDo pages via shadow DOM |
| 53 | +├── App.vue # Main content script UI (floating settings button + menu) |
| 54 | +├── popup/ # Browser action popup |
| 55 | +│ ├── App.vue |
| 56 | +│ └── main.js |
| 57 | +├── sidepanel/ # Side panel UI (reuses PopupViews) |
| 58 | +│ ├── App.vue |
| 59 | +│ └── main.js |
| 60 | +├── PopupViews/ # Shared UI components for popup/sidepanel |
| 61 | +│ ├── index.vue # Main view router |
| 62 | +│ └── components/ # Feature components (Bookmark, HotPosts, NewsPosts, LDC, etc.) |
| 63 | +├── SettingComponents/ # Settings menu components |
| 64 | +│ ├── AIConfig/ # AI API configuration (GPTconfig.vue) |
| 65 | +│ ├── BasicSettings/ # Toggle switches for features |
| 66 | +│ ├── CustomCSS/ # Custom CSS editor |
| 67 | +│ ├── DataBackup/ # Import/export settings |
| 68 | +│ ├── ThemeStyle/ # Theme customization |
| 69 | +│ └── UserTags/ # User tagging system |
| 70 | +├── bookmark/ # Bookmark management interface |
| 71 | +│ ├── App.vue |
| 72 | +│ └── components/ |
| 73 | +├── share/ # Share/post export functionality |
| 74 | +└── utilities/ # Shared utilities |
| 75 | + ├── indexedDBStorage.js # IndexedDB wrapper for settings/bookmarks |
| 76 | + ├── settingsManager.js # Settings management with caching |
| 77 | + ├── storageCompat.js # Storage migration/compatibility |
| 78 | + ├── connectApi.js # Connect.linux.do API wrapper |
| 79 | + ├── componentUpdateExample.js |
| 80 | + ├── post.ts # Post utilities |
| 81 | + ├── storageDebugger.js # Storage debugging |
| 82 | + └── url.ts # URL utilities |
| 83 | +``` |
| 84 | + |
| 85 | +### Key Architecture Patterns |
| 86 | + |
| 87 | +1. **Shadow DOM Injection**: Content script uses WXT's `createShadowRootUi` to inject Vue app without conflicting with page styles |
| 88 | +2. **Background Message Routing**: Background script acts as central hub for: |
| 89 | + - AI API proxy (CORS bypass) |
| 90 | + - WebDAV requests |
| 91 | + - Connect.linux.do API calls |
| 92 | + - Tab-to-tab messaging |
| 93 | + - Click behavior management (popup vs sidepanel) |
| 94 | +3. **Storage Strategy**: |
| 95 | + - Primary: IndexedDB via `indexedDBStorage.js` for large data (bookmarks, history) |
| 96 | + - Secondary: chrome.storage.local for settings |
| 97 | +4. **Shared Components**: Popup and sidepanel share the same `PopupViews` components |
| 98 | +5. **Settings Management**: Centralized settings with caching and migration support |
| 99 | + |
| 100 | +### Feature Modules |
| 101 | + |
| 102 | +- **AI Features**: GPT integration, topic summarization, smart replies |
| 103 | +- **Bookmark System**: Category-based bookmarking with IndexedDB |
| 104 | +- **Content Filtering**: User blocking, keyword filtering, time-based filtering |
| 105 | +- **UI Enhancements**: Themes, custom CSS, display optimizations |
| 106 | +- **Utilities**: Export to image/PDF, quick actions, level lookup |
| 107 | + |
| 108 | +## Configuration Files |
| 109 | + |
| 110 | +- **wxt.config.ts**: WXT framework configuration, manifest settings, Vite CSS options |
| 111 | +- **package.json**: Dependencies, scripts, version management |
| 112 | +- **tsconfig.json**: TypeScript config extending WXT's base config |
| 113 | +- **.prettierrc**: Code formatting rules (120 char width, tabs, single quotes) |
| 114 | + |
| 115 | +## Build Output |
| 116 | + |
| 117 | +- Development: `.output/chrome-mv3/` (or `firefox-mv2/`) |
| 118 | +- Production zips: Created via `npm run zip` commands |
| 119 | +- Python script (`scripts/build.py`) auto-updates `version-log.md` based on `package.json` version |
| 120 | + |
| 121 | +## Common Development Tasks |
| 122 | + |
| 123 | +### Adding a New Feature |
| 124 | +1. Create component in appropriate `entrypoints/` subdirectory |
| 125 | +2. Import and register in `App.vue` or `PopupViews/index.vue` |
| 126 | +3. Add settings toggle in `SettingComponents/BasicSettings/` |
| 127 | +4. Update storage schema if needed in `indexedDBStorage.js` |
| 128 | + |
| 129 | +### Debugging Content Script |
| 130 | +- Content script runs in shadow DOM, inspect via DevTools Elements panel |
| 131 | +- Look for `#linuxdoscripts` shadow root |
| 132 | +- Background script logs visible in extension service worker panel |
| 133 | + |
| 134 | +### Testing AI Features |
| 135 | +- Configure API endpoint in settings (AIConfig/GPTconfig.vue) |
| 136 | +- Background script provides proxy endpoints: `ai_api_proxy`, `ai_api_stream_proxy` |
| 137 | + |
| 138 | +### Storage Migration |
| 139 | +- Check `storageCompat.js` for version handling |
| 140 | +- `indexedDBStorage.js` has `getSettingsWithMigration()` for safe upgrades |
| 141 | + |
| 142 | +## Important Notes |
| 143 | + |
| 144 | +- **Node Version**: Requires Node.js v22.12.0 (see `.nvmrc`) |
| 145 | +- **Browser Compatibility**: Chrome (Manifest V3), Firefox (Manifest V2) |
| 146 | +- **Permissions**: storage, sidePanel, tabs, host_permissions for http/https |
| 147 | +- **Side Panel**: Default entry point, can be switched to popup via settings |
| 148 | +- **IDCflare Support**: Also compatible with idcflare.com domain |
| 149 | + |
| 150 | +## Testing Checklist |
| 151 | + |
| 152 | +When making changes, verify: |
| 153 | +- [ ] Content script injection works on linux.do pages |
| 154 | +- [ ] Background message handlers respond correctly |
| 155 | +- [ ] Settings persist across sessions |
| 156 | +- [ ] Bookmarks save/load from IndexedDB |
| 157 | +- [ ] AI API proxy handles both regular and streaming responses |
| 158 | +- [ ] Popup/sidepanel UI renders correctly |
| 159 | +- [ ] Theme changes apply without conflicts |
0 commit comments