devtools
Development-only library providing x-ray vision into running Wagoe applications. Zero production overhead — it lives in a dev alias, so it is on no production classpath.
|
Note
|
Published to Clojars as com.wagoe/wagoe-devtools, in lockstep with the
rest of the suite. In a project created by wagoe new it is in the :repl
alias, so clojure -M:repl has it and -M:run, the uberjar and the Docker
image do not. Inside this monorepo it is a local dependency on libs/devtools,
reached through the :dev and :repl-clj aliases.
|
Features
The DX Vision feature set spans six phases:
-
Guidance Engine — startup dashboard, post-scaffold tips, contextual help, command palette
-
Introspection — route table, config tree (secrets redacted), module/migration/test state analysis, schema exploration
-
Error Pipeline — WGE-xxx error codes, classifier → enricher → formatter chain, auto-fix suggestions
-
Dev Dashboard — browser-based UI at
localhost:9999with live system views -
Advanced REPL — request/response recording, route testing, rapid prototyping
-
Dashboard Extensions + AI — jobs monitoring, config editor, security status, AI-powered code review
Error Pipeline
Layered pipeline: classify → enrich → format → output. All pure functions in core/, side effects in shell/.
WGE Error Codes
| Range | Category |
|---|---|
WGE-1xx |
Configuration errors |
WGE-2xx |
Validation errors |
WGE-3xx |
Persistence errors |
WGE-4xx |
Authentication / authorization |
WGE-5xx |
Interceptor pipeline |
WGE-6xx |
FC/IS violations |
WGE-7xx |
Tooling / build errors |
WGE-8xx |
MCP guardrails ( |
Auto-Fix
;; Fix the last error (safe fixes auto-apply, risky ones confirm)
(fix!)
;; Fix a specific exception
(fix! ex)Safe fixes (e.g. setting an env var) apply automatically. Risky fixes (e.g. running a migration) always prompt for confirmation regardless of guidance level.
Dev Dashboard
Local web UI at http://localhost:9999 providing live insight into the running system.
Pages
| Page | What it shows |
|---|---|
|
System overview: components, routes, modules, environment |
|
Filterable route table with interceptor chains |
|
Live request stream (HTMX polling, 2s interval) |
|
Malli schema browser with example generation |
|
Database explorer: migrations, pool stats, query runner |
|
WGE-coded errors with fix suggestions |
|
Job queue stats, failed jobs with retry button |
|
Editable config tree with secret redaction and diff preview |
|
Security posture: password policy, auth methods, MFA, CSRF, rate limiting |
|
In-app documentation browser |
Architecture
-
Integrant component (
:wagoe/dashboard) starts Jetty on port 9999 -
Server-rendered Hiccup + HTMX polling for live updates
-
Request capture middleware wraps the main HTTP handler (port 3000)
-
Dark theme CSS in
resources/dashboard/assets/dashboard.css
Editing a config value from the dashboard rebuilds the system with the prep function your REPL gave integrant.repl/set-prep!. To rebuild from something else, set :ig-config-fn on :wagoe/dashboard to a zero-argument function returning your Integrant config. Functions in a config section are left out of the editor and kept when you apply.
Introspection & REPL Tools
;; Route table
(routes)
;; Config tree (secrets redacted)
(config :database)
;; Module summary
(modules)The five above — plus (status), (fix!) and (commands) — are in the
dev/user.clj of every project created by wagoe new. The rest of this page
describes helpers wired in this monorepo’s own dev/repl/user.clj; in your
project, call them through their namespaces:
;; Schema exploration
(require (quote [wagoe.devtools.core.schema-tools :as schema-tools]))
(schema-tools/format-schema-tree [:map [:email :string] [:name {:optional true} :string]])Request Recording
Capture HTTP request/response pairs for debugging and replay.
(require (quote [wagoe.devtools.shell.recording :as recording]))
;; Start a session; requests pass through recording/capture-middleware
(recording/start-recording!)
;; Inspect captured entries
(recording/list-entries)
(recording/diff-entries 0 1)
;; Stop, save and load sessions (.edn files)
(recording/stop-recording!)
(recording/save-session! "login-flow")
(recording/load-session! "login-flow")Route Testing
Add or remove routes on a running system without restart.
(require (quote [wagoe.devtools.shell.router :as router]))
;; Add a temporary test route
(router/add-dynamic-route! :get "/test" my-handler)
;; Tap a handler by its route :name; takes effect on the next (reset)
(router/add-tap! :create-user (fn [ctx] (println (:request ctx)) ctx))AI REPL Commands
Three AI-powered commands from wagoe.ai.shell.repl (require an AI provider to be configured):
(require (quote [wagoe.ai.shell.repl :as ai]))
;; Code review
(ai/review "path/to/file.clj")
;; Suggest missing test cases
(ai/test-ideas "path/to/file.clj")
;; FC/IS refactoring guide
(ai/refactor-fcis 'wagoe.product.core.validation)(new-feature!) Workflow
End-to-end feature scaffolding from a single REPL call:
(new-feature! "invoicing"
"Invoice module with customer, line-items, PDF export")Steps: AI spec generation → confirm → scaffold → integrate → test.
Key namespaces
| Namespace | Layer | Responsibility |
|---|---|---|
|
core |
Exception → WGE-xxx code mapping (5 strategies) |
|
core |
Adds stacktrace, suggestions, fix descriptor, URLs |
|
core |
Rich formatted output with WGE code header |
|
core |
Pure fix descriptor registry |
|
core |
WGE error catalog (WGE-1xx through WGE-8xx) |
|
core |
Startup dashboard, tips, command palette |
|
core |
Route table, config tree, module summary |
|
core |
Schema tree, diff, example generation |
|
core |
Request/response session management |
|
core |
Route addition/removal, tap interceptor injection |
|
core |
Malli schema → scaffold spec conversion |
|
core |
Config redaction, formatting, diff |
|
core |
Security posture analysis |
|
shell |
Unified REPL API |
|
shell |
Integrant component, Reitit router for dashboard |
|
shell |
Dev error enrichment middleware |
Testing
clojure -M:test:test/http :devtools