toor
1e9ea89d86
Import the client, server, skills, tests, and build scripts as the starting point for the rebuild, then trim the surfaces this project does not ship: Electron desktop packaging, the marketing website, and the ESP32 firmware tree. CI keeps the web build, e2e, lockfile, release, and Docker workflows. Rename the package and CLI entry points to hermes-ui, drop the prepare hook so npm ci no longer triggers a build, and drop the removed tsconfig and nodemon references. Rewrite AGENTS.md, ARCHITECTURE.md, DEVELOPMENT.md, and the READMEs so the documented package map and hard rules match this repository. reference_code/ is ignored: it is a read-only snapshot, not an input to the build.
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
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 |
|
|
| 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.
|
|
- Web UI release workflow: packages Web UI artifacts for published releases.
|
|
- Docker workflow: builds and publishes release images.
|
|
|
|
## 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.
|