initialize Electron desktop app and remove unused files

2026-10-25 01:09:01 +08:00
commit 01d9e301fc
877 changed files with 262513 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Validation Guide
+
+Run the smallest relevant checks while iterating. Escalate to the broad checks
+when touching shared behavior, release automation, auth, persistence, or chat.
+
+## Always Run For PRs
+
+```bash
+npm run harness:check
+npm run check:orphans
+```
+
+For broad or shared changes, also run:
+
+```bash
+npm run test:coverage
+npm run test:e2e
+npm run build
+```
+
+## Change-Type Matrix
+
+| Change | Minimum local validation |
+| --- | --- |
+| Docs only | `npm run harness:check` |
+| Client component/store/API | focused `npm run test -- <pattern>`, then `npm run build` |
+| User-visible browser flow | focused Vitest plus `npm run test:e2e` |
+| Server controller/service/db | focused `npm run test -- tests/server/<file>` |
+| Auth, profile, or credential behavior | focused server tests plus relevant e2e auth tests |
+| Chat, Socket.IO, group chat | focused server tests plus relevant e2e chat tests |
+| Chat session chain, Agent Bridge, compression, or Group Chat | Add one `docs/chat-chain-changes/*.md` fragment with date, PR/commit, touched feature, and behavior impact; then run `npm run harness:check` plus focused chat/bridge/group-chat tests |
+| Electron lifecycle, preload, native packaging | `npm run build`, `npm run electron:setup`, `npm run test:electron`, `npm run pack` |
+| Docker image | `npm run harness:check` and `npm run build` |
+| GitHub workflow | `npm run harness:check` and `actionlint` when available |
+| Package manifests | `npm ci --ignore-scripts` and lockfile workflow expectations |
+
+## CI Mapping
+
+- Build workflow: installs dependencies, runs coverage, and builds production
+  assets on pushes and pull requests.
+- Playwright workflow: runs browser e2e tests.
+- NPM lockfile workflow: verifies `package-lock.json` is synchronized.
+- Electron packages workflow: manually builds native installers on macOS, Windows
+  and Linux, then uploads platform-specific artifacts without publishing.
+- Electron smoke tests: run after the browser suite on Linux, and in the manual
+  macOS verification workflow.
+
+## Release Workflow Guardrail
+
+Published GitHub Releases should still trigger Web UI artifact packaging and
+Docker image publishing, but those workflows must keep the GitHub Release out
+of latest.
+
+Web UI release jobs must upload only the artifacts their build can produce. Keep
+artifact globs in matrix data and keep `fail_on_unmatched_files: true` so a
+missing expected file still fails.
+
+## Failure Handling
+
+When a command fails:
+
+1. Read the first actionable error, not just the final stack trace.
+2. Check whether the failure indicates missing context, missing test coverage,
+   or a missing mechanical rule.
+3. Fix the product bug when there is one.
+4. Update docs or `scripts/harness-check.mjs` when the same class of mistake
+   should be prevented next time.