WebTools/AGENTS.md

# Web Tools Agent Guide

This file is mandatory for AI and coding agents working in this repository. Read `README.zh-CN.md` in full before changing code. It is the authoritative product, behavior, deployment, extension, and release document; `README.md` is a complete English overview.

## First actions in a new session

1. Run `git status --short --branch` and preserve all existing tracked and untracked work. Never revert, overwrite, or clean user changes without explicit permission.
2. Read the closest existing tool component, its `src/lib/` implementation, Worker if present, and related tests before editing behavior.
3. Inspect `shared/tool-catalog.json`, `shared/default-navigation.json`, and `src/tools/registry.ts` before adding or removing a tool.
4. Do not commit, create tags, or push unless the user explicitly requests that action in the current conversation. Never place access tokens or credentials in source, Git configuration, documentation, commands committed to the repository, or release artifacts.
5. Make source changes only. Do not edit generated `dist/`; rebuild it with `npm run build`.

## Product identity and non-goals

- Web Tools is a self-hosted Vue 3 + TypeScript browser-local tools application with a zero-dependency Node.js static/configuration server.
- The default production port is `9000`. Port `8081` is only the local Vite development proxy target.
- The application is anonymous. Do not add login, accounts, favorites, sponsorship, analytics, telemetry, advertising, CDN assets, or a database.
- Tool inputs, keys, files, images, and results must remain inside the current browser tab. Do not send them to the Node server, a third-party API, or any remote service.
- `/setting` is a fixed, unlisted route for navigation management. It has no authentication and is not a security boundary. Anyone who can access the application can open it and change the globally shared navigation order.
- The server persists only navigation configuration. Preserve `data/navigation.json` and the configured external data directory; writes must remain temporary-file plus atomic-replace operations.
- Multiple users and tabs may use every tool concurrently. Their calculation state must remain independent; only navigation order is globally shared.

## Architecture rules

- `package.json` is the sole authoritative application version.
- `shared/tool-catalog.json` is the authoritative category/tool catalog. `shared/default-navigation.json` defines first-run ordering.
- Each tool is an independent lazy-loaded Vue component under `src/tools/`; register it in `src/tools/registry.ts`.
- Routes and sidebar entries are generated from the registry and catalog. Do not manually add an ordinary tool route to `src/router.ts`.
- Put parsing, encoding, cryptography, validation, and file-generation logic in testable modules under `src/lib/`. Vue components own presentation and state, not algorithm implementations.
- Put expensive file parsing and calculation in `src/workers/`. Workers still run entirely in the browser.
- Prefer browser standard APIs or existing, reviewed dependencies. Do not hand-roll established cryptographic primitives or file parsers.
- Add dependencies only when necessary. Keep the Node server runtime dependency-free unless a requirement cannot reasonably be met with the standard library.
- Define and enforce resource limits for file sizes, record counts, blocks, decoded image dimensions, random output, and rendered syntax tokens. If a limit changes, update implementation constants, tests, and the limits table in `README.zh-CN.md` together.

## Stable tool behavior

- ASCII/Hex uses UTF-8. Hex input accepts continuous text or chunks separated by whitespace, English commas, or Chinese commas, with an optional `0x` prefix on each chunk. Invalid UTF-8 must fail rather than silently replace bytes.
- Base64 supports standard and URL-safe input. Decoded output supports strict UTF-8, continuous Hex, and `0xNN, ...` byte arrays. Reject invalid characters, padding placement, lengths, and non-canonical trailing bits.
- AES-128-CMAC follows RFC 4493. The key is exactly 16 bytes of Hex and accepts continuous input or whitespace/comma/Chinese-comma-separated chunks with optional `0x` prefixes. Hex messages use the same parser.
- CRC supports BIN and multi-block Intel HEX, CRC-8/16/32/64 presets, and custom `Width`, `Poly`, `Init`, `XorOut`, `RefIn`, and `RefOut`. Combined data is ordered by address without filling gaps, and per-block results remain available.
- Firmware Hash accepts Intel HEX and computes SHA-256 and SHA-512. Effective-data mode concatenates sorted blocks without gap filling. Block-header mode prepends exactly two binary uint32 values, `startAddress` and data-only `dataLength`, to every block. Both fields are four bytes; Big Endian is the default; total input is `Header1 || Data1 || Header2 || Data2 ...`. Never hash a textual Hex representation of the header.
- RSA allows 2048, 3072, and 4096-bit keys with public exponent 65537. Prefer Web Crypto; the node-forge fallback must be seeded from `crypto.getRandomValues`. Export public SPKI PEM, private PKCS#8 PEM, and separately copyable N/E continuous Hex or byte arrays.
- Secure random output comes only from `crypto.getRandomValues`, is limited to 1-65,536 bytes, and supports continuous Hex, spaced Hex, and byte arrays. Changing display format must not regenerate bytes.
- JSON/XML formatting, minification, validation, and syntax highlighting stay local. When highlighting limits are exceeded, render the complete result as plain text rather than truncating it.
- PNG/ICO processing stays local and must enforce both compressed-file and decoded-pixel limits before costly rendering or allocation.

## Intel HEX and asynchronous safety

- Treat every address, length, end-address, offset, and allocation calculation as checked uint32 arithmetic. JavaScript bitwise operators are signed 32-bit and must not be used as unchecked address arithmetic.
- Validate record syntax, byte counts, checksums, control-record lengths/addresses, EOF placement, extended addresses, and the `0xFFFFFFFF` boundary.
- Sort records by absolute address, merge contiguous records, deduplicate identical overlaps, and reject conflicting overlaps. Enforce record, block, and effective-byte limits before allocating combined buffers.
- CRC and Firmware Hash may share the reviewed Intel HEX parser but must keep separate calculation logic, Worker protocols, and Vue state.
- File replacement, clear, mode change, option change, repeated generation, and component unmount can invalidate asynchronous work. Terminate obsolete Workers where possible and use monotonically increasing request/version IDs. A stale Worker, file read, image decode, or key-generation result must never replace current state.
- Clear the native file input value after handling a selection so choosing the same file again still emits a change event.
- Worker messages must be correlated to both the active Worker instance and active request ID. Error and completion handlers must ignore stale instances.

## UI contract

- Preserve the application shell: navigation on the left and tool content on the right on desktop; responsive navigation and a vertical content flow on mobile portrait.
- All tools use the shared visual language. Prefer `ToolPage`, `TextEditor`, `ModeTabs`, existing form/action classes, Lucide icons, and `src/styles.css`; do not create a tool-specific theme.
- Keep desktop controls compact. Use stable grid/flex constraints and allow controls to become full-width where appropriate on narrow screens.
- Prevent horizontal page overflow, clipped controls, nested scrolling accidents, text overlap, layout shifts, and unbounded result columns. Long Hex, hashes, filenames, and table cells require explicit wrapping or contained scrolling.
- Version information remains at the bottom of the sidebar and is read from `package.json`. Every page footer displays exactly `Copyright © mid All Rights Reserved.`
- Do not add a visible link to `/setting`, explanatory marketing copy, login UI, favorites, or sponsorship UI.
- For UI work, verify a wide desktop, an intermediate width around 801-1040 px, and mobile portrait around 390 x 844 in a real browser. Check direct routes, refresh, navigation, search, `/setting`, both themes, console errors, and network requests.

## Adding a tool

1. Choose a permanent, unique kebab-case ID. Published IDs must not change because routes and saved navigation depend on them.
2. Add pure logic and normal, invalid, boundary, resource-limit, and known-vector tests.
3. Add one Vue component under `src/tools/` using shared components and responsive styles.
4. Add matching metadata to `shared/tool-catalog.json` and its default position to `shared/default-navigation.json`. Only change navigation `version: 1` for a schema migration, not for a new tool.
5. Register the Lucide icon and lazy component in `src/tools/registry.ts`. Do not add a manual route.
6. Verify that an old saved `navigation.json` retains its order and receives the missing tool after the Node process restarts and navigation is next loaded.

IDs must remain synchronized across the catalog, default navigation, icon map, and component registry. Existing catalog tests enforce this contract.

## Deployment and release

- Supported deployments are Docker and Node.js 22.12.0+ with `web-tools.ps1` on Windows Server. A Windows single EXE is an optional future deliverable and is not currently built or supported.
- Keep production port changes synchronized across `server/index.mjs`, `web-tools.ps1`, `Dockerfile`, `docker-compose.yml`, `.env.example`, deployment tests, and both READMEs where applicable.
- The Windows update flow requires a clean `main` checkout and uses `git pull --ff-only`. Preserve external `C:\ProgramData\WebTools\data` state.
- New catalog data is loaded by the Node process at startup. Rebuilding `dist` alone is insufficient after catalog changes; restart the server and refresh already-open browser pages.
- If a single EXE is later authorized, use Node.js SEA with embedded read-only web/catalog assets and an external writable data directory. Add per-architecture builds, asset-read abstraction, Windows smoke tests, replacement/update instructions, and optional Authenticode signing. Derive EXE version metadata from `package.json`; do not create another manually maintained version source. Do not commit generated executables.

For a release, synchronize these five tracked files:

1. `package.json`
2. `package-lock.json`
3. `docker-compose.yml`
4. `README.zh-CN.md`
5. `CHANGELOG.md`

Use `npm version patch --no-git-tag-version` or the appropriate minor/major form so the project version in `package.json` and the two project metadata entries in `package-lock.json` remain synchronized. Other lockfile `version` fields belong to dependencies. `README.md` intentionally does not hardcode the current version.

Rebuild `dist`, the requested delivery ZIP, optional Docker image tar, and SHA-256 checksums. Generated assets are release outputs and remain ignored by Git. Never include `node_modules`, `.env`, runtime data, credentials, or local logs.

## Required validation and handoff

- After every code or documentation change, run `npm run check` and `git diff --check`.
- Before a release, also run `npm audit --audit-level=low`.
- For server/deployment changes, validate PowerShell syntax and Docker Compose configuration when the required executables are available. State clearly when a platform-specific check could not be run.
- For UI changes, complete the browser matrix in the UI contract. Automated tests and a successful build do not replace visual verification.
- Report changed behavior, important format/compatibility decisions, tests actually run, and any remaining risk. Report artifact paths and SHA-256 only when the task requested artifacts.
- Do not claim a check passed unless it was actually executed in the current worktree.