Initial commit: AetherForge Linux (forge-mesh) v0.1.0-dev
Some checks failed
Test / test (push) Has been cancelled
Some checks failed
Test / test (push) Has been cancelled
This commit is contained in:
drjones
46
docs/PROBLEMS.md
Normal file
46
docs/PROBLEMS.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Known limits and honest problems
|
||||
|
||||
AetherForge Linux (forge-mesh) is built for **machines you own and authorize**. This document records deliberate gaps and platform realities—not a bug list to fix silently.
|
||||
|
||||
## Deployment and spread
|
||||
|
||||
- **No worm-style LAN spread.** WinRM/GPO/BITS-style push lanes have no Linux equivalent in scope. Authorized summon (`curl | bash` with pin/campaign), SSH keys, Ansible, and enrolled sibling spread replace blind propagation.
|
||||
- **Triple onion is enrolled-only.** The 14-tier Linux deploy chain runs on hosts you have already authorized—not arbitrary internet targets.
|
||||
- **Earn-before-burn is phenotype-scoped.** Autospread to siblings only after local hashrate exceeds threshold for N minutes, and only within the same enrolled phenotype group.
|
||||
|
||||
## Tunneling and networking
|
||||
|
||||
- **cloudflared is sidecar-only on Linux.** The deck does not embed cloudflared in-process. Use `LAUNCH.sh` or your own unit to run `cloudflared tunnel run --token …` and set `AF_TUNNEL_EXTERNAL=1`. Agents must be configured to reach the tunnel hostname, not assume in-process tunnel state.
|
||||
- **WireGuard is operator-managed.** The plan includes WireGuard mesh (tier T9) and API hooks, but Forge Mesh does not auto-provision kernel WireGuard configs, key rotation, or NAT traversal. You install `wireguard`, distribute keys, and point agents at the deck overlay IP.
|
||||
- **Subnet mapping is opt-in.** ARP/ping sweeps run only on **operator-declared CIDRs** from the dashboard. There is no blind or internet-wide probing.
|
||||
|
||||
## Mining and hardware
|
||||
|
||||
- **GPU tiers need drivers first.** lolMiner/Rigel KawPoW paths assume `nvidia-smi` or `rocm-smi` already work. The summon installer does not install proprietary GPU stacks.
|
||||
- **Huge pages and cgroups vary by host.** Agents attempt tuning (`vm.nr_hugepages`, cgroup v2 caps) but success depends on capabilities, sysctl policy, and distros.
|
||||
- **Stratum upstream is yours.** The deck proxies to pool URLs you configure; wallet policy pins one address but pool connectivity and ban risk remain operator concerns.
|
||||
|
||||
## Intelligence and Court
|
||||
|
||||
- **Court / Seer needs an LLM you operate.** Every exhaust tick that invokes prosecutor/defender/judge requires local Ollama or a configured OpenAI-compatible API. There is no bundled model.
|
||||
- **eBPF telemetry is optional.** Build tag `ebpf` enables deeper signals; default builds may lack thermal/steal-time probes Court prompts expect.
|
||||
- **Clearance gates are policy, not crypto.** L0–L4 gates remote pause, reboot, screenshot, shell, and verdict dispatch—but compromise of deck credentials bypasses the model.
|
||||
|
||||
## Packaging and install
|
||||
|
||||
- **Signature verify is a placeholder until W8 forge signing ships.** `install.sh.tpl` documents ed25519 verification; dev builds may skip verify with a warning.
|
||||
- **USB portable deck is not hardened live media.** `pack-usb.sh` bundles config templates and optional binaries; operators must rotate passwords, fleet secrets, and tunnel tokens before production use.
|
||||
- **Screenshot on headless hosts is best-effort.** `grim`/`scrot` or stubs may return placeholders without a display server.
|
||||
|
||||
## Persistence and scale
|
||||
|
||||
- **SQLite is single-node default.** Multi-deck HA and Postgres are optional future paths; do not expect active-active fleet state on SQLite alone.
|
||||
- **Erasure and torrent tiers need seeded artifacts.** T12/T13 assume shards or seeds exist and are reachable; cold start without forge output will fail those tiers.
|
||||
|
||||
## What we intentionally do not promise
|
||||
|
||||
- Windows parity for every persistence or evasion mechanism.
|
||||
- Mining profitability or algo selection optimality—only tiered fallback to one wallet.
|
||||
- Legal compliance in your jurisdiction—self-hosted fleet ops are your responsibility.
|
||||
|
||||
For architecture and workstream ownership, see the project plan at `.cursor/plans/aetherforge_linux_edition_71dd0fbb.plan.md` (or `docs/` once mirrored in-repo).
|
||||
89
docs/TESTING.md
Normal file
89
docs/TESTING.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# AetherForge Testing Guide
|
||||
|
||||
This document describes how to run backend and frontend tests for AetherForge Linux.
|
||||
|
||||
## Backend (Go)
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
make test
|
||||
# or
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## Frontend (React / Vitest)
|
||||
|
||||
The Command Deck lives in `web/`. Tests use **Vitest**, **Testing Library**, **jsdom**, and **MSW** (Mock Service Worker) for HTTP mocks.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm install
|
||||
```
|
||||
|
||||
### Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run test` | Run all frontend tests once |
|
||||
| `npm run test:watch` | Watch mode |
|
||||
| `npm run test:coverage` | Run with V8 coverage report |
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
./scripts/test-frontend.sh
|
||||
# or
|
||||
make test-frontend
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **`web/vitest.config.ts`** — merges Vite config with Vitest (`jsdom`, `@/` alias, coverage)
|
||||
- **`web/src/test/setupTests.ts`** — MSW server lifecycle, RTL cleanup, session reset
|
||||
- **`web/src/test/mocks/handlers.ts`** — REST handlers for fleet, WS ticket, calibrate, crucible
|
||||
- **`web/src/test/test-utils.tsx`** — `renderWithProviders()` with MemoryRouter + auth
|
||||
- **`web/src/test/mockWebSocket.ts`** — WebSocket mock for fleet heartbeat tests
|
||||
- **`web/src/test/mockEventSource.ts`** — EventSource mock for Seer SSE tests
|
||||
|
||||
### Test layout
|
||||
|
||||
Tests are colocated with source files:
|
||||
|
||||
```
|
||||
web/src/
|
||||
App.test.tsx
|
||||
pages/*.test.tsx
|
||||
hooks/*.test.ts
|
||||
components/**/*.test.tsx
|
||||
lib/*.test.ts
|
||||
```
|
||||
|
||||
### What is covered
|
||||
|
||||
| Area | Tests |
|
||||
|------|-------|
|
||||
| **Login gate** | `ProtectedRoute`, `App` redirect unauthenticated users |
|
||||
| **Dashboard** | Host cards from mock `/api/v1/fleet`, WS connection badge |
|
||||
| **WebSocket hook** | `useFleetWebSocket` receives heartbeat frames |
|
||||
| **Auth/session** | `sessionStorage` credentials, Basic header |
|
||||
| **Routes** | Login, Dashboard, Forge, Calibrate, Crucible, Seer render without crash |
|
||||
| **Calibrate** | Mining profile form POSTs to fleet API |
|
||||
| **Crucible** | Terminal dispatch sends batch command |
|
||||
| **Seer** | SSE connect button, live status, message ingestion |
|
||||
| **Components** | HostCard, Badge variants, hashrate formatting |
|
||||
|
||||
### Writing new tests
|
||||
|
||||
1. Add MSW handlers in `src/test/mocks/handlers.ts` for new API endpoints.
|
||||
2. Use `renderWithProviders(<Component />, { authenticated: true })` for protected views.
|
||||
3. Call `installMockWebSocket()` / `installMockEventSource()` when testing realtime features.
|
||||
4. Place new tests beside the module: `MyComponent.test.tsx`.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- **Unhandled MSW request** — add a handler or use `server.use()` in the test.
|
||||
- **WebSocket flakiness** — use `waitFor` after `MockWebSocket.latest()?.simulateMessage(...)`.
|
||||
- **Auth redirects** — pass `authenticated: false` to `renderWithProviders` or clear `sessionStorage`.
|
||||
Reference in New Issue
Block a user