hoox

Imported from hoox-sh/hoox (AGENTS.md). Install upstream with npx skills add hoox-sh/hoox. Copyright stays with the author.

Agent Instructions

Ecosystem & websites

Local clones often sit next to each other: /home/jango/Git/{hoox,pynescript,axis}.

First-Time Setup

git clone --recursive https://github.com/hoox-sh/hoox.git
bun install

11 compute surfaces: 10 Worker isolates under workers/* (except workers/dashboard) are Git submodules — without --recursive they are empty directories. workers/dashboard is a Next.js app living in the parent repo (11th surface). pyne-worker is the Python PYNE edge evaluate host (tooling isolate; public routes use API_KEY, not mesh INTERNAL_KEY_BINDING; strategy forward to trade-worker uses mesh internal auth).

Monorepo

Bun workspaces: packages/*, workers/*, pages/*.

Dashboard lives at workers/dashboard/ (NOT pages/dashboard — that path is legacy).

Commands

bun install              # install (never npm/yarn)
bun test                 # all unit tests (bun native runner, 60s timeout, coverage on)
bun test packages/cli/   # focused: CLI tests
bun test packages/shared/ # focused: shared package
bun test packages/tui/   # TUI tests (preloads test-setup.ts)
bun test workers/hoox-worker/   # focused: single worker
bun test tests/integration/  # integration tests (vitest)
bun test tests/live/ --jobs 1 # live tests (needs Cloudflare creds)
bun test tests/security/ # security tests
bun test tests/e2e/      # end-to-end tests
bun test:load             # k6 load test suite (4 scripts)
bun test:all              # lint → typecheck → unit → live
bun run lint              # ESLint (flat config)
bun run lint:fix          # ESLint + auto-fix
bun run typecheck         # multi-project tsc via scripts/typecheck-all.ts
bun run build             # build:packages + typecheck
bun run format            # Prettier
bun run graph             # regenerate graph.json (~25s, scripts/extract-graph.ts)
hoox tui                  # launch TUI dashboard
hoox workers deploy       # deploy all workers
hoox pages deploy         # deploy dashboard (Cloudflare Workers via OpenNext)
hoox secrets update-cf    # push secrets to Cloudflare
bunx wrangler tail <name> # live worker logs

CI Pipeline

bun run lint → bun run typecheck → bun test → bun run build (sequential jobs, CI runs all).

Pre-Commit / Pre-Push

• Pre-commit: npx lint-staged (eslint --fix + prettier --write on staged *.{ts,tsx,js,jsx,mjs,cjs,json,yaml,yml,md,css,scss})
• Pre-push: bun run typecheck

Testing

• Unit: bun test (bun native runner), config in bunfig.toml — coverage always on, 60s timeout, NODE_ENV=test
• Integration: vitest + @cloudflare/vitest-pool-workers (config: vitest.config.ts)
• Live: bun test tests/live/ --jobs 1 (requires Cloudflare credentials)
• Coverage threshold: 80%+ line coverage on core paths (CLI/shared/gateway/trade); aspirational 90% line / 95% function per standards doc. Shared ~98%, CLI src/ ~95% (2026-08).
• Test files: ~250 across workers, packages/shared, packages/cli, packages/tui, dashboard (~4,600+ unit tests, ~9k expect() calls)
• ESLint relaxes rules in test files (no-unused-vars: warn, no-explicit-any: warn, ban-ts-comment: warn)

Local Development

hoox dev start                # interactive (Native vs Docker)
hoox dev start --runtime native   # force wrangler dev
hoox dev start --runtime docker   # force docker compose
hoox dev worker <name>        # single worker via wrangler dev
hoox dev dashboard            # Next.js dev server

Runtime preference saved to wrangler.jsonc.dev.runtime (not re-prompted).

Docker Compose profiles: workers, dashboard, full (workers + dashboard).

docker compose --profile workers up
docker compose --profile workers --profile dashboard up

Self-hosted production server: bun run server.js (Bun.serve, maps path prefixes to worker modules, requires HOOX_SERVER_API_KEY).

Dashboard (workers/dashboard)

• Next.js 16 + Turbopack, @opennextjs/cloudflare adapter (NOT @cloudflare/next-on-pages)
• Build: bunx opennextjs-cloudflare build → .open-next/worker.js
• Deploy: bunx wrangler deploy (Cloudflare Workers runtime, NOT Pages)
• Config: wrangler.jsonc with main: ".open-next/worker.js", assets.directory: ".open-next/assets"
• Static assets via ASSETS binding
• Framer Motion components need 'use client'
• Pages with 'use client' cannot export metadata — use separate metadata.ts

Architecture

11 compute surfaces (gateway + trade + agent + dashboard + telegram + d1 + web3 + email + analytics + report + pyne). Mesh workers communicate via Cloudflare Service Bindings (no public URLs). Gateway (workers/hoox-worker) and Dashboard are the primary public-facing endpoints; pyne-worker is a tooling isolate (API_KEY on public evaluate routes; mesh internal key on trade forward).

External Inputs → hoox (Gateway) → trade-worker → d1-worker → analytics-worker
                                  → agent-worker → trade-worker, telegram-worker
                                  → telegram-worker → analytics-worker
email-worker → trade-worker
web3-wallet-worker → telegram-worker
report-worker → telegram-worker
dashboard → d1-worker, agent-worker, pyne-worker
pyne-worker → trade-worker   (TRADE_SERVICE + X-Internal-Auth-Key)

Infrastructure: D1 (SQLite at edge; prefer named /rpc/*), R2 (zero-egress), KV (config), Durable Objects on hoox (IdempotencyStore two-phase + RateLimiterStore atomic rate limits), Queues (async + concurrency), Workers AI, Vectorize, Analytics Engine, Browser Rendering.

Security mesh (v0.13+): notify chat allowlists (TELEGRAM_ALLOWED_CHAT_IDS / AUTHORIZED_CHAT_IDS), safeWaitUntil for background work, REST-only trade orders, env-first agent API keys. Deploy notes: workers/hoox-worker/DEPLOY.md.

Smart Placement enabled on trade, d1, telegram, web3-wallet, email, analytics (30-60% latency reduction).

Edge / Worker Constraints

• No Node.js built-ins in workers — Edge runtime
• No hardcoded secrets — use wrangler secret or hoox secrets
• wrangler types generates worker-configuration.d.ts per worker
• @cloudflare/workers-types for type definitions
• tsconfig.json: strict mode, includes test files
• tsconfig.prod.json: strict (but noImplicitAny: false), excludes *.test.* and test/ dirs
• Secrets in wrangler.jsonc secrets arrays; local dev secrets in .dev.vars (gitignored) per worker

Code Graph

graph.json (large) — query only, never load fully. graph-metadata.json — architecture layer (workers, infra, data-flows); safe to load fully. After mesh/security changes:

bun scripts/extract-graph.ts   # → graph.json, graph.dot, refresh dynamic fields in graph-metadata.json

# Quick worker overview
bun -e "const g=require('./graph.json'); g.nodes.filter(n=>n.kind==='worker').forEach(w=>console.log(w.label,'| public:',w.isPublic,'| cron:',w.cron||'-','| eps:',w.entryPoint))"

# Get worker llmContext
bun -e "const g=require('./graph.json'); console.log(g.nodes.find(n=>n.id==='workspace:workers/hoox-worker').llmContext)"

# Infrastructure bindings for a worker
bun -e "const g=require('./graph.json'); g.edges.filter(e=>e.source==='workspace:workers/hoox-worker'&&e.kind==='infra-binding').forEach(e=>console.log(e.label,'→',g.nodes.find(n=>n.id===e.target)?.label))"

# All workers using a specific KV binding
bun -e "const b=require('./graph-metadata.json').infrastructure['kv:CONFIG_KV']; console.log(b.bindingName,'used by:',b.usedBy.join(', '))"

Code Style Conventions

• Prettier: semi, singleQuote: false, trailingComma: "es5", printWidth: 80, tabWidth: 2, arrowParens: "always"
• ESLint: flat config, TS strict, no-undef: off (CF worker types), @typescript-eslint/ban-ts-comment: error, no-console: off
• TypeScript: strict, noUnusedLocals, noUnusedParameters, noImplicitReturns, noFallthroughCasesInSwitch
• Path alias: @hoox-sh/hoox-shared/* → packages/shared/src/*
• bun-types + node types globally

Sister Repos

Primary stack (websites on hoox.sh):

Related:

Key dependency links:

• AXIS → pyne Pro API (:5002) or axis Worker for chart evaluation
• pyne-worker → pynescript package (editable install from pyne repo)
• pine-worker → @hoox-sh/hoox-shared (this monorepo)
• All under github.com/hoox-sh/

                    https://hoox.sh
           ┌──────────────┼──────────────┐
           ▼              ▼              ▼
         HOOX            PYNE           AXIS
    (this monorepo)  (Pine engine)  (charting UI)
           │              │              │
           └──────────────┴──────────────┘

Important File Paths