[pull] main from jason5ng32:main

.dockerignore

@@ -0,0 +1,23 @@
+.git
+.github
+.VSCodeCounter
+.claude
+.vscode
+
+node_modules
+dist
+logs
+localtest
+package-lock.json
+
+.DS_Store
+.env
+*.log
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+common/maxmind-db/.maxmind-update-*.json
+common/maxmind-db/.maxmind-update.lock
+common/maxmind-db/*.bak
+common/maxmind-db/*.next

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+# Least-privilege GITHUB_TOKEN: tests + build only need to read the repo.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Test + Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          # Intentionally no `cache: npm` — that requires a package-lock.json, and this
+          # repo gitignores the lockfile by design. `npm install` below runs cold every
+          # run; dependency install on this project takes ~30s, which is acceptable
+          # versus the drift risk of committing a lockfile we don't otherwise use.
+
+      - name: Install dependencies
+        run: npm install --no-audit --no-fund
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build

.github/workflows/docker-image.yml

@@ -9,26 +9,35 @@ on:
         description: 'Version tag'
         required: true
 
+# Least-privilege GITHUB_TOKEN:
+# - contents: read  → checkout the source
+# - packages: write → push the built image to ghcr.io/${owner}/myip
+# Docker Hub push uses DOCKER_HUB_ACCESS_TOKEN (a repo secret), not GITHUB_TOKEN,
+# so no extra scopes are needed for that half of the job.
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
     environment: production
 
     steps:
     - name: Check Out Repo
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
+      uses: docker/setup-buildx-action@v4
 
     - name: Login to Docker Hub
-      uses: docker/login-action@v3
+      uses: docker/login-action@v4
       with:
         username: ${{ secrets.DOCKER_HUB_USERNAME }}
         password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
     - name: Login to GitHub Packages
-      uses: docker/login-action@v3
+      uses: docker/login-action@v4
       with:
         registry: ghcr.io
         username: ${{ github.repository_owner }}
@@ -47,7 +56,7 @@ jobs:
         echo "RELEASE_NOTES=Manually triggered build" >> $GITHUB_ENV
 
     - name: Build and Push Docker Image
-      uses: docker/build-push-action@v5
+      uses: docker/build-push-action@v7
       with:
         push: true
         tags: |

.github/workflows/dockerhub-readme.yml

@@ -0,0 +1,37 @@
+name: Sync README to Docker Hub
+
+# Keeps the Docker Hub overview page in sync with README.md in this repo.
+# Triggers on any push to main that touches README.md (or this workflow file
+# itself), so documentation edits propagate without waiting for the next
+# release or a manual step. Also exposes `workflow_dispatch` for a manual
+# one-shot push (useful the first time this workflow is enabled, or to force
+# a resync after rotating the Docker Hub token).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'README.md'
+      - '.github/workflows/dockerhub-readme.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    name: Push README to Docker Hub
+    runs-on: ubuntu-latest
+    environment: production
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Update Docker Hub description
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
+          repository: jason5ng32/myip
+          readme-filepath: ./README.md

.github/workflows/sync.yml

@@ -5,7 +5,7 @@ permissions:
 
 on:
   schedule:
-    - cron: "0 0 * * *" # 每天 UTC 时间 0 点
+    - cron: "0 0 * * *" # every day at 00:00 UTC
   workflow_dispatch:
 
 jobs:
@@ -15,27 +15,26 @@ jobs:
     if: ${{ github.event.repository.fork }}
 
     steps:
-      # 步骤 1: 运行标准的签出动作
+      # step 1: checkout target repo
       - name: Checkout target repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
 
-      # 步骤 2: 运行同步动作
+      # step 2: sync upstream changes
       - name: Sync upstream changes
         id: sync
         uses: aormsby/Fork-Sync-With-Upstream-action@v3.4
         with:
           upstream_sync_repo: jason5ng32/MyIP
           upstream_sync_branch: main
           target_sync_branch: main
-          target_repo_token: ${{ secrets.GITHUB_TOKEN }} # 自动生成，无需设置
+          target_repo_token: ${{ secrets.GITHUB_TOKEN }} # auto-generated, no need to set
 
-          # 将 test_mode 设置为 true 来运行测试而不是真正的动作！
+          # set test_mode to true to run tests instead of the real action!
           test_mode: false
 
-      # 出错检查
+      # error check
       - name: Sync check
         if: failure()
         run: |
-          echo "[Error] 由于上游仓库的 workflow 文件变更，导致 GitHub 自动暂停了本次自动更新，你需要手动 Sync Fork 一次。"
-          echo "[Error] Due to a change in the workflow file of the upstream repository, GitHub has automatically suspended the scheduled automatic update. You need to manually sync your fork."
+          echo "[Error] Due to a change in the workflow file of the upstream repository, GitHub has automatically suspended the scheduled automatic update. You need to manually sync your fork again."
           exit 1

.gitignore

@@ -6,6 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
+.claude
 
 node_modules
 dist
@@ -34,3 +35,5 @@ common/maxmind-db/.maxmind-update-*.json
 common/maxmind-db/.maxmind-update.lock
 common/maxmind-db/*.bak
 common/maxmind-db/*.next
+common/maxmind-db/*.mmdb
+.learnings/

AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+Single source of truth for anyone — human or AI — contributing to MyIP.
+
+For area-specific details, see:
+
+- Frontend (Vue 3 SPA): @frontend/AGENTS.md
+- Backend API (Express): @api/AGENTS.md
+
+## Overview
+
+**MyIP** (IPCheck.ing) is an open-source IP toolbox: IP lookup, connectivity tests, WebRTC / DNS-leak detection, speed test, MTR, Whois, security checklist, browser fingerprint, anonymity checks, and more.
+
+Single repo, two halves: a Vue 3 SPA front-end and an Express 5 back-end API, served side by side.
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Vue 3 (`<script setup>`, Composition API) |
+| State | Pinia |
+| Router | vue-router (hash mode) |
+| i18n | vue-i18n — `en` / `zh` / `fr` / `tr` |
+| Build | Vite + `@vitejs/plugin-vue` |
+| CSS | Tailwind CSS v4 (`@tailwindcss/vite`) + `tw-animate-css` |
+| UI primitives | shadcn-vue copy-in style, built on `reka-ui` |
+| Icons | `lucide-vue-next` (inline SVG components) |
+| Flags | `@iconify-json/circle-flags` via `@iconify/vue` |
+| Bottom drawer | `vaul-vue` |
+| Toast | `vue-sonner` |
+| Backend | Express 5 |
+| Auth | Firebase Auth (optional, env-gated) |
+| PWA | Serwist |
+| Tests | Node built-in test runner (`node --test`) |
+| Runtime libs | chart.js · svgmap · @cloudflare/speedtest · maxmind · whoiser · thumbmarkjs · ua-parser-js · detect-gpu · circle-progress.vue · @vueuse/core (used by shadcn-vue primitives) |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | Vite + backend (nodemon) together — front-end 5173, back-end 11966 |
+| `npm run build` | Front-end production build |
+| `npm run preview` | Vite preview of the build output |
+| `npm run start` | Built front-end + backend (static file server) |
+| `npm test` | Run all `tests/*.test.js` specs |
+| `npm run check` | `test` + `build`, the pre-commit self-check |
+
+## Project layout
+
+```
+.
+├── AGENTS.md                    ← this file
+├── CLAUDE.md                    ← Claude-specific pointer to AGENTS.md
+│
+├── frontend/                    ← Vue 3 SPA (see frontend/AGENTS.md)
+├── api/                         ← Express handlers (see api/AGENTS.md)
+├── common/                      ← code shared between front- and back-end
+│                                  (valid-ip / fetch-with-timeout / guards /
+│                                   referer-check / maxmind-service / …)
+├── tests/                       ← Node test runner specs
+│
+├── backend-server.js            ← Express app (default port 11966)
+├── frontend-server.js           ← static file server for `npm start`
+├── index.html                   ← Vite entry; #app mounts vaul-drawer-wrapper
+├── vite.config.js
+├── jsconfig.json                ← JS project, alias @ → frontend/
+└── package.json
+```
+
+## Conventions
+
+### Language
+
+- **JavaScript only.** New files are `.js` / `.vue`; `<script setup>` has no `lang="ts"`. Do not rename `jsconfig.json` to `tsconfig.json` or otherwise introduce TypeScript.
+- **English by default** for source-code comments , commit messages and AGENTS.md files. Planning docs can be in other languages. Locale packs are obviously the exception — they contain user-facing copy in their respective language.
+
+### Comments
+
+- **Every new file opens with a header comment** stating its purpose. One or two lines is usually enough; enough that a reader opening the file cold understands what it is.
+- **Large templates or functions carry block comments** on each meaningful section — enough for a maintainer six months later to orient quickly. Not every line, but every region / branch / step.
+
+### i18n coverage
+
+- Any feature that surfaces copy must land in **all four locales** (`en` / `zh` / `fr` / `tr`) in the same change. No English-only or Chinese-only keys slipping through.
+- Same rule applies to `frontend/data/changelog.json` — every entry's `change` object must have all four languages. `tests/changelog.test.js` enforces this.
+
+## Testing
+
+- **Test runner:** Node built-in (`node --test`), no third-party framework. Specs live in `tests/*.test.js`.
+- **Coverage expectation:** any non-visual logic that can be exercised without a network call — pure functions, composables with mockable inputs, transform utilities, validators — ships with a test in `tests/` and is wired into `npm test`. UI rendering, real network behavior, and browser-API-dependent code are out of scope.
+- **Big new features:** write the tests in the same change. Don't defer.
+- **Modifying a tested feature:** check the related tests; update them in the same change if behavior shifts.
+- **Tests must pass locally before you hand off.** If `npm run check` is red, don't ask the user to review.
+
+## Security & Boundaries
+
+The backend enforces access control and timeouts through shared middleware rather than per-handler code. Full details live in @api/AGENTS.md; the rules that matter at the project level:
+
+- `requireReferer` is mounted globally on `/api/*` — handlers must not repeat the referer check.
+- `requireValidIP()` is attached per-route where `?ip` is a required param — handlers must not repeat the IP check.
+- Every upstream HTTP call goes through `fetchUpstream` (`common/fetch-with-timeout.js`) with an 8s timeout. Never add a bare `fetch()` to an `api/` handler.
+
+## Workflow
+
+- **Do not commit without explicit user approval.** The flow is: AI edits → user reviews → user tests → user says "commit" → AI commits. Silent commits are a breach of trust.
+- **One concern per commit.** Don't mix unrelated changes into a single commit. Split at the right seam.
+- **Self-test before handing off.** Run `npm run check` (or at least `npm test`) for every change. If the change is visual (UI layout, styling, interactions) and can't be verified headless, say so explicitly so the user can test it in `npm run dev`.
+- **Every commit is gated on user testing.** Even with tests green, a visual change needs the user to have looked at it before it lands.
+- **Add yourself as a co-author to the commit.** If you are an AI.
+- **Commit message style** follows recent `git log` — `Refactor(xxx): …` / `Fix(ui): …` / `Feat(xxx): …` / `Style: …` / `Chore: …` prefix.
+- **On every commit, scan AGENTS.md (root + relevant sub-file) for staleness** — if the change adds a convention, renames a shared module, flips a rule, or invalidates an example, update the doc in the same commit. AGENTS.md drifting from reality is the main failure mode of this kind of document.

CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+Authoritative project instructions: @AGENTS.md
+
+Claude-specific additions below; on conflict, AGENTS.md wins.
+
+## Claude-specific
+
+None at the moment. This file exists so Claude Code auto-loads AGENTS.md at
+session start; additional Claude-only guidance goes here if it ever diverges
+from what all contributors should follow.

Dockerfile

@@ -1,13 +1,13 @@
-# 第一阶段：构建
-FROM node:20-alpine as build-stage
+# Build stage
+FROM node:24-alpine AS build-stage
 WORKDIR /app
 COPY package*.json ./
 RUN npm install
 COPY . .
 RUN npm run build
 
-# 第二阶段：运行
-FROM node:20-alpine as production-stage
+# Production stage
+FROM node:24-alpine AS production-stage
 WORKDIR /app
 COPY --from=build-stage /app/node_modules ./node_modules
 COPY --from=build-stage /app/package.json ./
@@ -19,5 +19,5 @@ COPY --from=build-stage /app/common ./common
 
 EXPOSE 18966
 
-# 启动应用
+# Start application
 CMD ["npm", "start"]