livewire

Category: Databases & Storage | Uploader: brdloush | Downloads: 0 | Version: v1.0（Latest）
Live nREPL probe for Spring Boot apps. Use when working with a Spring Boot application that has Livewire on its classpath to query the running JVM state, beans, database, and behaviour via the live REPL.
Changelog: Source: GitHub https://github.com/brdloush/livewire
Directory Structure

Current level: skills/livewire/
📁 bin/
- 📄 lw-all-bean-deps 658 B
- 📄 lw-all-bean-tx 648 B
- 📄 lw-bean-deps 503 B
- 📄 lw-bean-tx 499 B
- 📄 lw-build-entity 1.1 KB
- 📄 lw-build-test-recipe 1.1 KB
- 📄 lw-call-endpoint 2.2 KB
- 📄 lw-eval 483 B
- 📄 lw-find-beans 519 B
- 📄 lw-info 458 B
- 📄 lw-inspect-all-entities 803 B
- 📄 lw-inspect-entity 518 B
- 📄 lw-jpa-query 1.1 KB
- 📄 lw-list-endpoints 471 B
- 📄 lw-list-entities 470 B
- 📄 lw-list-queries 513 B
- 📄 lw-props 509 B
- 📄 lw-sql 511 B
- 📄 lw-start 748 B
- 📄 lw-trace-nplus1 528 B
- 📄 lw-trace-sql 506 B
📄 SKILL.md 66.6 KB
SKILL.md

---
name: livewire
description: Live nREPL probe for Spring Boot apps. Use when working with a Spring Boot application that has Livewire on its classpath to query the running JVM state, beans, database, and behaviour via the live REPL.
---

# Livewire — Live nREPL probe for Spring Boot apps

Use this skill whenever working with a Spring Boot application that has Livewire
on its classpath. Before answering any question about the running app's state,
beans, database, or behaviour — **try the live REPL first**. A live answer from
the JVM beats static analysis every time.

---

## Writing tests / creating test data

**Before writing any test setup code, always prototype test data in the live REPL using `faker/build-entity`.**

This applies whenever you need to:
- Write a new integration test (service layer, repository, or otherwise)
- Populate test data for manual exploration
- Understand what a valid entity graph looks like

### Test style — follow the project first

**Always look at existing tests before writing a new one.** Match the project's conventions for:
- `@SpringBootTest` environment (`MOCK`, `NONE`, `RANDOM_PORT`)
- How test data is set up (repositories, `JdbcTemplate`, `@Sql`, etc.)
- Transaction / rollback strategy (`@Transactional`, `@BeforeEach`/`@AfterEach` cleanup)
- Assertion library (AssertJ, JUnit 5 built-ins, Hamcrest, etc.)

The rules below are **fallback guidance** for when no existing pattern covers the case.

### Fallback rules of thumb

**Service-layer tests** — call the service bean directly; no MockMvc needed:
- Use `WebEnvironment.MOCK` (not `NONE`) when the app has a Spring Security config — `HttpSecurity` is only available in a web context and `NONE` will fail at startup with `NoSuchBeanDefinitionException`.
- `@Transactional` on the test class auto-rolls back each test, keeping the DB clean without explicit teardown.
- After all test data is set up in `@BeforeEach`, call `entityManager.flush(); entityManager.clear()` before the test body runs. Without this, service calls in the same transaction may see stale lazy collections: if a parent entity was saved before its children, its collection is already "initialized" as empty in the L1 cache and Hibernate won't re-query even when children exist in the DB.

**REST/controller tests** — use MockMvc against the HTTP layer when testing status codes, authentication, serialization, or HTTP-level behaviour.

### REPL workflow for test data prototyping

1. **Check faker is available:**
   ```bash
   clj-nrepl-eval -p 7888 "(faker/available?)"
   ```

2. **Prototype entity creation in the REPL** — use `:auto-deps? true :persist? true :rollback? true` to resolve the full dependency chain without leaving data behind:
   ```bash
   lw-build-entity Review '{:auto-deps? true :persist? true :rollback? true}'
   ```

3. **Inspect the result** — note which fields were generated, what IDs were assigned, and which associations were resolved. This tells you exactly what setup code the test will need.

   > ⚠️ **Check for narrow numeric types before prototyping.**
   > `lw-build-test-recipe` returns values but not their Java types. Before writing the Clojure
   > prototype, run `lw-inspect-entity` on each entity in the recipe and note any properties
   > with `:type "short"`, `:type "byte"`, or `:type "float"`. Clojure integer literals are
   > `Long` by default — passing them to a setter that expects `Short` throws
   > `ClassCastException` at runtime. Cast explicitly: `(short 1924)`, `(short 5)`, etc.
   >
   > ```bash
   > # Quick: grep for narrow types across all entities involved in the recipe
   > clj-nrepl-eval -p 7888 "(->> (map intro/inspect-entity [\"Review\" \"Book\" \"Author\" \"LibraryMember\"])
   >                               (mapcat :properties)
   >                               (filter #(#{\"short\" \"byte\" \"float\"} (:type %)))
   >                               (mapv #(select-keys % [:name :type])))"
   > ```

4. **Adjust with overrides** if specific field values matter for your test assertions:
   ```bash
   lw-build-entity Review '{:auto-deps? true :persist? true :rollback? true :overrides {:rating 5 :comment "Outstanding"}}'
   ```

5. **Prototype the full test logic in Clojure before writing Java** — after the entity graph is validated, prototype the entire test scenario (setup + service call + assertions) as a Clojure expression in the REPL. Use `clojure.test/is` for assertions. This catches issues with the service logic, lazy loading, and field mappings before a single line of Java is written.

   ```clojure
   ;; Example: prototype getReviewsForBook test in Clojure
   (use 'clojure.test)
   (lw/in-tx
     (let [author  (doto (com.example.Author.) (.setFirstName "Jane") (.setLastName "Austen"))
           _       (.save (lw/bean "authorRepository") author)
           book    (doto (com.example.Book.) (.setTitle "Test Book") (.setAuthor author))
           _       (.save (lw/bean "bookRepository") book)
           member  (doto (com.example.LibraryMember.) (.setUsername "jdoe") (.setFullName "John Doe")
                                                       (.setEmail "jdoe@test.com") (.setMemberSince (java.time.LocalDate/now)))
           _       (.save (lw/bean "libraryMemberRepository") member)
           review  (doto (com.example.Review.) (.setBook book) (.setMember member)
                                                (.setRating (short 5)) (.setComment "Great") (.setReviewedAt (java.time.LocalDateTime/now)))
           _       (.save (lw/bean "reviewRepository") review)
           _       (do (.flush (lw/bean "entityManager")) (.clear (lw/bean "entityManager")))
           result  (.getReviewsForBook (lw/bean "bookService") (.getId book))]
       (is (= 1 (count result)))
       (is (= 5 (.rating (first result))))
       (is (= "John Doe" (.reviewerName (first result))))))
   ```

6. **If the nREPL is unavailable, ask the user to start the app — never skip prototyping**

   The REPL-first rule is not optional. If `lw-start` finds no server, stop and ask:
   > "The app doesn't seem to be running. Could you start it so I can prototype in the REPL before writing the test?"

   Do not fall back to reasoning theoretically about what the test *should* do. A theoretical prototype defeats the entire purpose — the value is catching real issues (wrong bean names, L1 cache surprises, unexpected exceptions) against a live JVM before a single line of Java is written.

7. **`@BeforeEach` entity setup — store IDs, not entity references**

   When `@BeforeEach` ends with `entityManager.flush() + entityManager.clear()`, any entity references stored as instance fields become **detached**. Using them as `@ManyToOne` targets in test bodies relies on lenient Hibernate behaviour and is fragile.

   **Preferred pattern:** store only the IDs, re-attach in test bodies via `getReferenceById()`:

   ```java
   private Long bookId;
   private Long memberId;

   @BeforeEach
   void setUp() {
       // ... create and save book, member ...
       entityManager.flush();
       entityManager.clear();
       bookId = book.getId();     // store stable IDs
       memberId = member.getId(); // discard the detached refs
   }

   @Test
   void myTest() {
       Book book = bookRepository.getReferenceById(bookId);         // Hibernate proxy, no DB hit
       LibraryMember member = libraryMemberRepository.getReferenceById(memberId);
       // use book and member as @ManyToOne targets — managed proxies, FK resolves cleanly
   }
   ```

   `getReferenceById()` returns a Hibernate proxy with the ID set — no SELECT is fired, and Hibernate resolves the FK correctly on flush. This pattern is explicit, safe across inheritance hierarchies, and stays correct as the test class grows.

8. **Only then write the test** — translate the validated REPL recipe into the setup style already used by the project.

---

## Wrapper scripts

This skill ships named wrapper scripts in a `bin/` subdirectory located in the
same directory as this `SKILL.md` file. If you ever need to find the scripts,
locate `SKILL.md` first (e.g. `find / -name SKILL.md 2>/dev/null | grep livewire`)
and the `bin/` folder is right next to it.

Always prefer these wrapper scripts over raw `clj-nrepl-eval` calls — they
produce cleaner output in the Claude Code UI (the script name is shown instead
of the full Clojure expression) and handle namespace requiring automatically.

Use them via their full path: `~/.claude/skills/livewire/bin/<script-name>`.
The port defaults to **7888** and can be overridden with `LW_PORT`.

| Script | What it does |
|---|---|
| `lw-start` | Discover nREPL + app summary in one shot — **always run this first** |
| `lw-info` | App/env summary |
| `lw-list-entities` | All Hibernate-managed entities |
| `lw-inspect-entity <Name>` | Table, columns, relations for one entity |
| `lw-inspect-all-entities` | Table, columns, relations for **all** entities in one call |
| `lw-list-endpoints` | All HTTP endpoints with auth info |
| `lw-find-beans <regex>` | Filter bean names by regex |
| `lw-bean-deps <beanName>` | Dependencies and dependents for one bean |
| `lw-all-bean-deps` | Wiring maps for all app-level beans (auto-filtered to own package) |
| `lw-bean-tx <beanName>` | `@Transactional` surface for one bean |
| `lw-all-bean-tx` | `@Transactional` surface for all app-level beans (auto-filtered) |
| `lw-props <regex>` | Filter environment properties by regex |
| `lw-sql <query>` | Run a read-only SQL query |
| `lw-jpa-query <jpql> [page] [page-size]` | Run a JPQL query and return serialized entity maps (traced, paged) |
| `lw-trace-sql <clojure-expr>` | Capture SQL fired by an expression |
| `lw-trace-nplus1 <clojure-expr>` | Detect N+1 queries in an expression |
| `lw-call-endpoint [--limit N] <bean> <method> <role> [args...]` | Call a bean method under a single Spring Security role; list results capped at 20 by default |
| `lw-list-queries <repoBeanName>` | List all `@Query` methods on a repo with their current JPQL |
| `lw-build-entity <EntityName> [edn-opts]` | Build a fake entity instance; optional EDN opts map (`:auto-deps?`, `:persist?`, `:rollback?`) |
| `lw-build-test-recipe <EntityName> [edn-opts]` | Build a faker entity graph and extract all scalar field values into a nested map — use as seed for test setup code and assertions |
| `lw-eval <clojure-expr>` | Generic nREPL eval — **avoid, see pitfall below** |

> ⚠️ **Prefer `clj-nrepl-eval -p <port>` over `lw-eval` for arbitrary expressions.**
> Clojure naming conventions use `!` (mutating fns like `reset-all!`, `hot-swap-query!`),
> `?` (predicates like `running?`), and `->` / `->>` (threading macros). These characters
> can be misinterpreted by the shell when passed through `lw-eval`. Use the dedicated
> wrapper scripts for their named operations; for everything else, call `clj-nrepl-eval`
> directly with a double-quoted expression:
> ```bash
> clj-nrepl-eval -p 7888 "(hq/reset-all!)"
> ```

---

## Prerequisites

This skill relies on `clj-nrepl-eval` — a lightweight CLI from
[clojure-mcp-light](https://github.com/bhauman/clojure-mcp-light) that lets
Claude evaluate Clojure expressions against a running nREPL server.

Install it once with [bbin](https://github.com/babashka/bbin):

```bash
# Install bbin (if not already installed — e.g. via Homebrew)
brew install babashka/brew/bbin

# Install clj-nrepl-eval
bbin install https://github.com/bhauman/clojure-mcp-light.git \
  --tag v0.2.1 \
  --as clj-nrepl-eval \
  --main-opts '["-m" "clojure-mcp-light.nrepl-eval"]'
```

Verify it works:
```bash
clj-nrepl-eval --discover-ports
```

---

## Workflow

1. **Start the session** — always run `lw-start` first:
   ```bash
   lw-start
   ```
   This discovers running nREPL servers and prints an app summary (name, profiles,
   Java/Spring/Hibernate versions) in one shot. The default port is **7888** and can
   be overridden with `LW_PORT`. If nothing is found, the app may not be running or
   `livewire.enabled=true` may not be set.

2. **Namespaces are pre-aliased** — the boot sequence wires these into the `user` ns
   automatically, so no manual `require` is needed:
   `lw`, `q`, `intro`, `trace`, `qw`, `hq`, `jpa`, `mvc`, `faker`

3. **Evaluate** snippets iteratively — the session persists between calls:
   ```bash
   clj-nrepl-eval -p <port> "<clojure-code>"
   # with an explicit timeout (milliseconds)
   clj-nrepl-eval -p <port> --timeout 5000 "<clojure-code>"
   ```

4. **Run independent read queries in parallel** — when multiple `clj-nrepl-eval` calls have
   no dependencies on each other (e.g. inspecting several entities, fetching unrelated
   properties), fire them all in a single message as parallel Bash tool calls. This
   significantly reduces wall-clock time. Only serialize calls when one result feeds
   into the next.

5. **Present results readably:**
   - Collections of maps → markdown table
   - Single map → inline key/value list
   - Scalars → inline code in prose

6. **Hot-patching:** Do not use `:reload` to pick up a newly built JAR — it
   re-reads the same old class already on the classpath. Instead, evaluate the
   new `ns` form and function bodies directly into the live REPL.

7. **After writing a source-code fix:** Once a hypothesis has been validated in
   the REPL and the fix has been written to source, remind the user that a
   restart may be required before the new code takes effect — unless the change
   is limited to `@Query` JPQL strings that the query-watcher can pick up
   automatically on recompile. For structural changes (new methods, service
   logic, new beans), a friendly nudge is appropriate:
   > The fix is in source. If the change involves new methods or service logic,
   > a restart will be needed to activate it. Once you restart, we can continue
   > from the live REPL.

---

## Core API — `net.brdloush.livewire.core`

| Expression | What it returns |
|---|---|
| `(lw/ctx)` | Live Spring `ApplicationContext` |
| `(lw/info)` | Env summary (Spring version, Java, OS, active profiles) |
| `(lw/bean "name")` | Bean by name |
| `(lw/bean MyService)` | Bean by type |
| `(lw/beans-of-type DataSource)` | All beans of a type → map |
| `(lw/bean-names)` | All registered bean names |
| `(lw/find-beans-matching ".*Repo.*")` | Filter bean names by regex |
| `(lw/bean-deps "name")` | Wiring map for one bean: `:class`, `:dependencies`, `:dependents` |
| `(lw/all-bean-deps)` | Wiring maps for app-level beans (`:app-only true` by default) |
| `(lw/all-bean-deps :app-only false)` | Wiring maps for all beans including Spring infrastructure |
| `(lw/bean-tx "name")` | `@Transactional` surface for one bean: `:methods` with propagation, isolation, `:read-only`, rollback rules |
| `(lw/all-bean-tx)` | `@Transactional` surface for all app-level beans (`:app-only true` by default); only beans with ≥1 transactional method included |
| `(lw/all-bean-tx :app-only false)` | Include Spring infrastructure beans (verbose — JPA repos expose many overloaded variants) |
| `(lw/all-properties)` | All resolved environment properties → map |
| `(lw/props-matching "spring\\.ds.*")` | Filter properties by regex |
| `(lw/bean->map obj)` | Convert any Java object to a Clojure map — handles both regular JavaBeans and Java records (use this instead of `clojure.core/bean`) |
| `(lw/in-tx & body)` | Run body in a transaction — **always rolls back** |
| `(lw/in-readonly-tx & body)` | Run body in a read-only transaction |
| `(lw/run-as user & body)` | Run body with a Spring `SecurityContext` set — required for `@PreAuthorize`-guarded beans |

### `bean-tx` / `all-bean-tx` — `@Transactional` boundary introspection

Use these functions to map the effective transactional configuration of every bean method.
They query Spring's `AnnotationTransactionAttributeSource` at runtime — no static analysis
required. Both class-level and method-level `@Transactional` are resolved correctly,
including JPA repository defaults from `SimpleJpaRepository`.

`bean-tx` returns the full transactional surface of a single bean:

```clojure
(lw/bean-tx "bookService")
;; => {:bean    "bookService"
;;     :class   "com.example.BookService"
;;     :methods [{:method "archiveBook" :propagation :required :isolation :default
;;                :read-only false :timeout -1 :rollback-for [] :no-rollback-for []}
;;               {:method "getAllBooks"  :propagation :required :isolation :default
;;                :read-only true  :timeout -1 :rollback-for [] :no-rollback-for []}]}
```

`all-bean-tx` returns the same for every app-level bean that has at least one transactional
method (`:app-only true` default, same auto-detection as `all-bean-deps`).

> ⚠️ **JPA repository beans are verbose.** `SimpleJpaRepository` exposes many overloaded
> method variants — calling `lw/bean-tx "bookRepository"` will return 50+ entries. The
> `:app-only true` default on `all-bean-tx` excludes repository beans automatically.

> ⚠️ **Programmatic transactions are not visible.** Methods using `TransactionTemplate` or
> `PlatformTransactionManager` directly leave no annotation trail and will not appear here.

**Common patterns:**

```clojure
;; Full transactional surface of the app — clean summary
(lw/all-bean-tx)

;; Methods that look like reads but are not marked read-only — performance smell
(->> (lw/all-bean-tx)
     (mapcat (fn [b] (map #(assoc % :bean (:bean b)) (:methods b))))
     (filter #(and (not (:read-only %))
                   (re-find #"(?i)^(get|find|list|count|search|fetch)" (:method %)))))

;; All REQUIRES_NEW methods — potential nested transaction complexity
(->> (lw/all-bean-tx)
     (mapcat (fn [b] (map #(assoc % :bean (:bean b)) (:methods b))))
     (filter #(= :requires-new (:propagation %))))

;; Non-default rollback rules
(->> (lw/all-bean-tx)
     (mapcat (fn [b] (map #(assoc % :bean (:bean b)) (:methods b))))
     (filter #(or (seq (:rollback-for %)) (seq (:no-rollback-for %)))))
```

---

### `bean-deps` / `all-bean-deps` — wiring graph introspection

Use these functions to map the runtime dependency graph of the Spring context.
They rely on Spring's internal dependency tracking — populated during context refresh —
which captures constructor injection, `@Autowired` fields, and `@Inject` fields.

`bean-deps` returns a map for a single bean:

```clojure
(lw/bean-deps "bookService")
;; => {:bean         "bookService"
;;     :class        "com.example.BookService"
;;     :dependencies ["bookRepository"]          ; beans bookService injects
;;     :dependents   ["adminController"           ; beans that inject bookService
;;                    "bookController"]}
```

`all-bean-deps` returns the same map for every bean matching the filter.
By default (`:app-only true`) it restricts results to beans whose class belongs
to the application's own root package — auto-detected from `@SpringBootApplication`.
This collapses the "which beans are mine?" lookup into the same call.
Pass `:app-only false` to include all Spring infrastructure beans.

```clojure
;; App beans only — the default, typically a handful of your own classes
(lw/all-bean-deps)

;; Full context including Spring Boot infrastructure (~250+ beans)
(lw/all-bean-deps :app-only false)
```

**Common patterns:**

```clojure
;; Find beans with the most dependencies — coupling smell candidates
(->> (lw/all-bean-deps)
     (sort-by #(count (:dependencies %)) >)
     (take 10)
     (mapv #(select-keys % [:bean :class :dependencies])))

;; Find beans with the most dependents — high-impact, highest-risk to change
(->> (lw/all-bean-deps)
     (sort-by #(count (:dependents %)) >)
     (take 10)
     (mapv #(select-keys % [:bean :dependents])))

;; Inspect a specific bean's full wiring context
(lw/bean-deps "adminService")

;; Find all beans that depend on a given bean (inverse lookup)
(->> (lw/all-bean-deps)
     (filter #(some #{"bookRepository"} (:dependencies %)))
     (mapv :bean))
```

---

### `run-as` — when and how to use it

Use `run-as` whenever calling a bean that is protected by Spring Security (`@PreAuthorize`,
`@Secured`, etc.). Without it the REPL has no `SecurityContext` and throws
`AuthenticationCredentialsNotFoundException`.

`user` accepts three forms:

| Form | Effect |
|---|---|
| `"alice"` | Token for `alice` with `ROLE_USER` + `ROLE_ADMIN` |
| `["alice" "ROLE_X" "ROLE_Y"]` | Token with exactly the specified roles |
| an `Authentication` object | Used as-is |

```clojure
;; Call a @PreAuthorize-guarded controller or service
(lw/run-as "admin"
  (.getBookById (lw/bean "bookController") 25))

;; Combine with in-readonly-tx for repository access under a security context
;; Always page or limit — never call .findAll on a large table (see pitfalls)
(lw/run-as "admin"
  (lw/in-readonly-tx
    (->> (.findAll (lw/bean "bookRepository")
                   (org.springframework.data.domain.PageRequest/of 0 3))
         .getContent
         (mapv #(select-keys (clojure.core/bean %) [:id :title :isbn])))))

;; Use a specific role set when the method checks for a non-admin role
(lw/run-as ["auditor@example.com" "ROLE_AUDITOR"]
  (.getAuditLog (lw/bean "auditService")))
```

**Prefer `run-as` over bypassing to the service layer** when you want to exercise
the real secured code path — including AOP advice, `@PostAuthorize` filters, etc.

#### ⚠️ Plain string form only grants `ROLE_USER` + `ROLE_ADMIN`

If an endpoint requires a custom role (e.g. `ROLE_MEMBER`, `ROLE_VIEWER`, `ROLE_LIBRARIAN`),
the plain string form will fail with `AuthorizationDeniedException` — not
`AuthenticationCredentialsNotFoundException`. **Always use the vector form for non-admin roles.**

```clojure
;; ❌ fails with AuthorizationDeniedException if endpoint requires ROLE_VIEWER
(lw/run-as "viewer"
  (.getAuthors (lw/bean "authorController")))

;; ✅ explicitly specify the required role
(lw/run-as ["viewer" "ROLE_VIEWER"]
  (.getAuthors (lw/bean "authorController")))
```

---

## Introspection API — `net.brdloush.livewire.introspect`

| Expression | What it returns |
|---|---|
| `(intro/list-endpoints)` | All registered HTTP endpoints (path, method, controller, handler, params, `:pre-authorize`) |
| `(intro/list-entities)` | All Hibernate-managed entities — simple name, FQN, and DB table name |
| `(intro/inspect-entity "Name")` | Table name, columns, and relations for one entity |
| `(intro/inspect-all-entities)` | Table name, columns, and relations for **all** entities in one call |

### Inspecting entity structure

**Prefer `intro/inspect-all-entities` over calling `intro/inspect-entity` in a loop** when
you need the full domain model — e.g. to build an ER diagram, reason about relationships, or
generate a data dictionary. It returns all entities in a single REPL round-trip.

**Prefer `intro/list-entities` + `intro/inspect-entity` over raw SQL schema queries** when
exploring entity mappings, table names, columns, or relations. The introspection API reads
directly from Hibernate's metamodel — it reflects the actual JPA mapping including column
overrides, join tables, and relation types, without needing to know the DB dialect or schema name.

**When presenting entity listings to the user, always include:**
- Entity name (`:name`)
- Fully-qualified class name (`:class`)
- DB table name (`:table-name`) — included directly in `list-entities` output, no extra calls needed

```clojure
;; ✅ preferred: list all entities, then inspect one
(->> (intro/list-entities) (map :name) (filter #(re-find #"Book" %)))
;; => ("Book")

(intro/inspect-entity "Book")
;; => {:table-name "book",
;;     :identifier {:name "id", :columns ["id"], :type "long"},
;;     :properties [{:name "title", :columns ["title"], :type "string"} ...],
;;     :relations [{:name "author", :type :many-to-one, :target "Author"} ...]}

;; ✅ also fine: raw SQL for schema questions the metamodel can't answer
;;    (e.g. indexes, constraints, DB-level defaults)
(lw/in-readonly-tx (q/sql "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'book'"))
```

Raw SQL schema queries are a valid fallback for DB-level details (indexes, constraints,
sequences) that are outside Hibernate's metamodel.

### Calling controller methods from the REPL

#### ⚠️ Never invoke mutating endpoints without explicit user instruction

Only call controller methods that correspond to **read-only (`GET`) endpoints** on your own
initiative. `GET` endpoints are expected to be side-effect free and are safe to invoke for
inspection or debugging.

For any **mutating endpoint** (`POST`, `PUT`, `PATCH`, `DELETE`, or anything else that writes,
deletes, or triggers side effects), you **must not** call it unless one of the following is true:

- The user has **explicitly instructed** you to call it (e.g. "go ahead and create that record").
- You have **asked the user for permission** and received confirmation.

If in doubt, describe what you would call and why, and wait for the user's go-ahead.

When you discover an endpoint via `list-endpoints`, check its `:pre-authorize` value before calling it.
If one is present, **always wrap the call in `lw/run-as`** — without it the REPL has no
`SecurityContext` and Spring Security throws `AuthenticationCredentialsNotFoundException`.

```clojure
;; Discover what auth an endpoint requires
(->> (intro/list-endpoints)
     (filter #(re-find #"books" (str (:paths %))))
     (mapv #(select-keys % [:paths :handler-method :pre-authorize])))
;; => [{:paths ["/api/books"], :handler-method "getBooks", :pre-authorize "hasRole('MEMBER')"}
;;     ...]

;; Call it with the appropriate role
(lw/run-as "member1"
  (.getBooks (lw/bean "bookController")))
```

`:pre-authorize` reflects both method-level and class-level `@PreAuthorize` annotations —
so it's always populated when security is in play, regardless of where the annotation lives.

**When presenting `list-endpoints` results to the user, always include these fields for each endpoint:**
- HTTP method(s) (`:methods`)
- Path(s) (`:paths`)
- Controller class name (`:controller`)
- Handler method name (`:handler-method`)
- Required role / `@PreAuthorize` expression (`:pre-authorize`, or "none" if absent)

#### CLI shortcut: `lw-call-endpoint`

For one-shot calls from the shell, `lw-call-endpoint` handles the require and `run-as`
boilerplate automatically. It accepts a single role (the `ROLE_` prefix is required).

**List results are capped at 20 items by default** — the same convention as `lw-sql` and
`lw-jpa-query`. Use `--limit N` to override. The returned value is a Clojure vector with
metadata attached so you can see how many items were omitted. Single-object results (non-list)
are unaffected and always return in full as pretty-printed JSON.

**Always report the following to the user when a limited list is returned:**
- `:returned` / `:total` — how many rows were shown vs how many exist
- `:content-size` — raw JSON byte size of the **full uncapped** response (all `:total` items, not just the `:returned` ones — do NOT use this to judge whether the returned payload is too large to display)
- `:content-size-gzip` — gzip-compressed byte size of the full uncapped response

**The actual returned payload contains only `:returned` items** — always render it directly as a markdown table without piping through external tools (Python, jq, etc.), even when `:content-size` looks large.

**If the saved output file is too large for the Read tool** (error: token limit exceeded), do NOT fall back to Python/jq/shell tools to parse it. Instead, re-call the same endpoint using `lw-call-endpoint --limit 1`:

```bash
# Re-call with a single item — always fits in the Read tool
lw-call-endpoint --limit 1 bookController getBooks ROLE_MEMBER
```

**Always render the returned items as a markdown table**, using the keys of the first item as
column headers. The number of rows to display in the table follows this rule:
- If the result has `:total` metadata, show up to `:returned` rows — but if the tool result is too large to fully process, show at least 3 rows and note that the rest were omitted due to response size
- Otherwise cap the table at **20 rows** unless the user explicitly asked for more
- Never silently truncate — if rows were omitted, add a note such as
  `_Showing N of M total rows. Use --limit to retrieve more._`

```bash
# List endpoint — capped at 20 by default
lw-call-endpoint bookController getBooks ROLE_MEMBER

# Raise the cap
lw-call-endpoint --limit 5 bookController getBooks ROLE_MEMBER

# Single-object endpoint — limit has no effect, returns full pretty-printed JSON
lw-call-endpoint bookController getBookById ROLE_MEMBER 25

# String argument — quote carefully
lw-call-endpoint bookController searchBooks ROLE_MEMBER '"spring"'
```

When you need **multiple roles** or a custom username, use `clj-nrepl-eval` directly:

```bash
clj-nrepl-eval -p 7888 '(lw/run-as ["alice" "ROLE_LIBRARIAN" "ROLE_VIEWER"] (.getMembers (lw/bean "memberController")))'
```

---

## Trace API — `net.brdloush.livewire.trace`

| Expression | What it does |
|---|---|
| `(trace/trace-sql & body)` | Captures every SQL fired by Hibernate on the current thread |
| `(trace/trace-sql-global & body)` | Same, but captures across *all* threads (useful for `@Async`) |
| `(trace/detect-n+1 trace-res)` | Analyzes a trace result and flags repeated queries |

---

## JPA Query API — `net.brdloush.livewire.jpa-query`

Executes a JPQL query against the live `EntityManager` inside a read-only transaction and
returns a vector of plain Clojure maps. Lazy collections are rendered as `"<lazy>"` rather
than triggering surprise queries; ancestor-chain cycles become `"<circular>"`.

**Prefer this over raw `q/sql`** when you want to work at the JPA/entity level — `JOIN FETCH`
clauses control exactly what gets loaded, and the result is already a readable Clojure structure
with no need to manually call `clojure.core/bean`.

| Expression | What it does |
|---|---|
| `(jpa/jpa-query jpql)` | Run JPQL, return first 20 results as entity maps |
| `(jpa/jpa-query jpql :page 1 :page-size 5)` | Paginate — offset = `page × page-size` |

### Serialization behaviour

| Scenario | Result |
|---|---|
| Scalar property | Value as-is |
| Temporal type (`LocalDate`, etc.) | `#object[LocalDate ...]` (not coerced) |
| Eagerly fetched `@ManyToOne` | Recursed into (full nested map) |
| Eagerly fetched collection (within cap) | `[{…} {…} …]` |
| Collection beyond page-size cap | Truncated to cap |
| Uninitialized lazy collection | `"<lazy>"` |
| Ancestor-chain cycle | `"<circular>"` |
| Sibling reuse of same object | Fully rendered (not falsely circular) |
| Non-entity Java object | `(.toString obj)` |

### Examples

```clojure
;; Basic — lazy associations render as "<lazy>"
(jpa/jpa-query "SELECT b FROM Book b ORDER BY b.id")
;; => [{:id 1, :title "All the King's Men", :isbn "...",
;;      :author {:id 6, :firstName "Kip", :lastName "O'Reilly", :books "<lazy>"},
;;      :genres "<lazy>", :reviews "<lazy>", :loanRecords "<lazy>"} ...]

;; JOIN FETCH to eagerly load genres — they come back as real vectors
(jpa/jpa-query "SELECT DISTINCT b FROM Book b LEFT JOIN FETCH b.genres ORDER BY b.id"
               :page 0 :page-size 5)
;; => [{:id 1, ..., :genres [{:id 3, :name "Fiction"} {:id 7, :name "Drama"}], :reviews "<lazy>"} ...]

;; Paginate — page 2 of 10 (rows 20–29)
(jpa/jpa-query "SELECT b FROM Book b ORDER BY b.id" :page 2 :page-size 10)

;; Combine with trace-sql to inspect query count and SQL shape
(trace/trace-sql
  (jpa/jpa-query "SELECT DISTINCT b FROM Book b LEFT JOIN FETCH b.genres"))
;; => {:result [...], :count 1, :duration-ms 12, :queries [{:sql "select ..."}]}
```

### CLI: `lw-jpa-query`

```bash
# Default: page 0, page-size 20
lw-jpa-query 'SELECT b FROM Book b ORDER BY b.id'

# With JOIN FETCH, first 5 results
lw-jpa-query 'SELECT DISTINCT b FROM Book b LEFT JOIN FETCH b.genres' 0 5

# Page 2 with 10 per page
lw-jpa-query 'SELECT b FROM Book b ORDER BY b.id' 2 10
```

The CLI output is wrapped in `trace/trace-sql`, so you always get `:result`, `:count`,
`:queries`, and `:duration-ms` in one shot.

### Scalar projections

`jpa/jpa-query` and `lw-jpa-query` also work for **scalar projections** — queries that select
expressions or aggregates rather than full entities. `Object[]` rows are automatically unpacked
into maps with positional keys `:col0`, `:col1`, etc.

```bash
# Aggregate query — returns {:col0 <title>, :col1 <count>} maps
lw-jpa-query 'SELECT b.title, COUNT(lr) FROM Book b JOIN b.loanRecords lr GROUP BY b.id, b.title ORDER BY COUNT(lr) DESC' 0 5
```

```clojure
;; => {:duration-ms 26,
;;     :result [{:col0 "Vanity Fair",                  :col1 7}
;;              {:col0 "Let Us Now Praise Famous Men", :col1 7}
;;              {:col0 "The Green Bay Tree",           :col1 7}
;;              {:col0 "The Mermaids Singing",         :col1 6}
;;              {:col0 "This Lime Tree Bower",         :col1 6}],
;;     :count 1, ...}
```

If you want named keys instead of `:col0`/`:col1`, rename them in Clojure after the fact:

```clojure
(->> (:result (jpa/jpa-query "SELECT b.title, COUNT(lr) FROM Book b JOIN b.loanRecords lr GROUP BY b.id, b.title ORDER BY COUNT(lr) DESC"
                              :page 0 :page-size 5))
     (mapv #(clojure.set/rename-keys % {:col0 :title :col1 :loan-count})))
;; => [{:title "Vanity Fair", :loan-count 7} ...]
```

---

## Mutation Observer API — `net.brdloush.livewire.query`

`q/diff-entity` answers the question *"what did this service call actually write to the database?"* —
the observability gap that `trace/trace-sql` and `jpa/jpa-query` leave open. Those tools cover
the *query* dimension; `diff-entity` covers the *mutation* dimension.

| Expression | What it does |
|---|---|
| `(q/diff-entity entity-class id thunk)` | Snapshot entity before and after calling `thunk`, return `{:before … :after … :changed {key [old new]}}` |

- `entity-class` — Hibernate entity name (string, e.g. `"Book"`) or Java class
- `id` — primary key value
- `thunk` — zero-argument function that performs the mutation

The thunk always runs inside `lw/in-tx` — **the change is always rolled back**. The database is
never affected. The snapshot of the mutated state is captured inside the transaction, before the
rollback fires.

### When to use it

- **Exploration** — "what fields does `.archiveBook` actually touch?" without reading service code
- **Debugging** — "why is entity 42 in this unexpected state?" — call candidate service methods and inspect their diffs
- **Fix verification** — confirm a patched service method now writes the correct fields before committing
- **AI agent mutation investigation** — the primary use case: an agent can systematically call candidate service methods and reason about which one caused an unexpected state change

### Example

```clojure
;; Observe what a repository save would change (rolled back — nothing persists)
(q/diff-entity "Book" 1
  (fn []
    (let [repo (lw/bean "bookRepository")
          book (.get (.findById repo (Long. 1)))]
      (.setAvailableCopies book (short 2))
      (.save repo book))))
;; => {:before  {:id 1, :title "All the King's Men", :availableCopies 3, ...}
;;     :after   {:id 1, :title "All the King's Men", :availableCopies 2, ...}
;;     :changed {:availableCopies [3 2]}}

;; No-op thunk — confirms rollback and baseline
(q/diff-entity "Book" 1 (fn []))
;; => {:before {...}, :after {...}, :changed {}}

;; Non-existent entity — safe, returns nils
(q/diff-entity "Book" 99999 (fn []))
;; => {:before nil, :after nil, :changed {}}
```

### Using it from the shell

There is no dedicated wrapper script — the thunk is Clojure logic, not a data argument.
Use `clj-nrepl-eval` directly:

```bash
clj-nrepl-eval -p 7888 '(q/diff-entity "Book" 1 (fn [] (.save (lw/bean "bookRepository") ...)))'
```

---

## Hot Queries API — `net.brdloush.livewire.hot-queries`

Swap a Spring Data JPA `@Query` live without restarting the app. Works by replacing the
`queryString` Lazy field inside `SimpleJpaQuery` with an atom-backed one — Spring Data's
full result-type coercion stays intact. The first swap uses reflection; subsequent swaps
for the same method are reflection-free (just `reset!` the atom).

| Expression | What it does |
|---|---|
| `(hq/list-queries "repoBean")` | Lists all `@Query` methods on the repo with their current JPQL |
| `(hq/hot-swap-query! "repoBean" "method" new-jpql)` | Swaps the JPQL live; first call uses reflection, subsequent calls just `reset!` the atom |
| `(hq/list-swapped)` | Shows all currently swapped queries across all repos |
| `(hq/reset-query! "repoBean" "method")` | Restores the original JPQL for one method |
| `(hq/reset-all!)` | Restores **every** currently swapped query at once; always call this to clean up after an exploratory session |

### When to use hot-queries

- **Iterating on a JPQL fix** without a restart — swap, call the method, observe, refine.
- **Reproducing a query bug** by temporarily substituting a known-bad query.
- **Testing a `JOIN FETCH` or `@EntityGraph`** addition before writing it to source.
- Works best combined with `trace/trace-sql` to verify the resulting SQL.

### Last-one-wins swap policy

**A recompile always overrides a REPL pin.** When the query-watcher detects a `.class` file
change, it applies the new JPQL regardless of whether you had previously swapped the query
from the REPL. Similarly, a subsequent REPL swap overrides whatever the watcher last applied.
Whoever wrote last wins — no manual cleanup required between iterations.

`(hq/list-swapped)` shows `:manual? true` for REPL-initiated swaps and `:manual? false` for
watcher-initiated ones — informational only, it no longer blocks overwrites.

```clojure
(hq/list-swapped)
;; => [{:bean "bookRepository", :method "findByIdWithDetails",
;;      :manual? true, :jpql "select b from Book b where b.id = :id"}]
```

### ⚠️ Hot-swaps are persistent side effects — clean up when done

Unlike `lw/in-tx` (which always rolls back), hot-swapped queries **persist** in the live JVM.
A recompile will override your swap automatically (last-one-wins), but if you finish an
exploratory session without recompiling, the patched query stays live and can silently affect
other callers or monitoring.

**Rule: call `reset-all!` when you're done experimenting.**

```clojure
;; Restore everything in one call
(hq/reset-all!)
;; => [["bookRepository" "findByIdWithDetails"] ...]   ← keys that were restored

;; Or verify nothing is left swapped
(hq/list-swapped)
;; => []
```

---

```clojure
;; See what @Query methods exist on a repo
(hq/list-queries "bookRepository")
;; => ({:method "findByIdWithDetails", :query-class "SimpleJpaQuery",
;;      :jpql "select b from Book b where b.id = :id ..."} ...)

;; Swap to a fixed query (e.g. add JOIN FETCH to fix N+1)
(hq/hot-swap-query! "bookRepository" "findByIdWithDetails"
  "select b from Book b join fetch b.author join fetch b.reviews where b.id = :id")

;; Verify the fix — combine with trace-sql to confirm query shape
(trace/trace-sql
  (lw/run-as "admin"
    (lw/in-readonly-tx
      (.findByIdWithDetails (lw/bean "bookRepository") 25))))

;; Swap again (reflection-free atom reset)
(hq/hot-swap-query! "bookRepository" "findByIdWithDetails"
  "SELECT DISTINCT b FROM Book b JOIN FETCH b.author LEFT JOIN FETCH b.genres WHERE b.id = :id")

;; Check registry
(hq/list-swapped)
;; => [{:bean "bookRepository", :method "findByIdWithDetails", :jpql "..."}]

;; Restore original when done
(hq/reset-query! "bookRepository" "findByIdWithDetails")
;; => :restored
```

---

## Query Watcher API — `net.brdloush.livewire.query-watcher`

The query-watcher runs automatically in the background (started by Livewire on boot). It polls
compiled output directories (`target/classes`, `build/classes/…`) every 500 ms, detects `.class`
file changes via mtime, and auto-applies updated `@Query` JPQL strings live — no restart needed.

| Expression | What it does |
|---|---|
| `(qw/status)` | Returns `{:running? true/false, :disk-state-size N, :disk-state {...}}` |
| `(qw/start-watcher!)` | Starts the watcher (idempotent — called automatically on boot) |
| `(qw/stop-watcher!)` | Stops the watcher |
| `(qw/force-rescan!)` | Clears the mtime cache — next poll re-examines every `.class` file |

`qw/force-rescan!` is rarely needed manually. `hq/reset-all!` and `hq/reset-query!` call it
automatically after restoring a query so the watcher immediately re-applies whatever is on disk.

---

## ⚠️ Hibernate lazy loading — always convert inside the transaction

Returning a raw Hibernate entity from `in-tx` / `in-readonly-tx` will throw
`LazyInitializationException` when the REPL tries to print it — the session is
already closed. **Always eagerly convert to a plain Clojure map inside the
transaction boundary.**

```clojure
;; ❌ blows up — printed after session closes
(lw/in-readonly-tx
  (.findById (lw/bean "bookRepository") 1))

;; ✅ convert while the session is still open
(lw/in-readonly-tx
  (-> (.findById (lw/bean "bookRepository") 1)
      .get
      clojure.core/bean                              ; all getter properties → map
      (select-keys [:id :title :isbn])))             ; narrow to what you need
```

`clojure.core/bean` introspects all getter methods and returns a Clojure map.
Wrap it in `select-keys` to avoid triggering lazy associations you don't need.

---

## ⚠️ Important Rules

### Always limit SQL queries when fetching sample data or IDs
Tables in a live app can contain millions of rows. **Always add a `TOP` / `LIMIT` / `FETCH FIRST`
clause** when querying for sample data, example IDs, or exploratory results. The default cap is
**20 rows**.

```clojure
;; ❌ may return millions of rows and hang the REPL
(lw/in-readonly-tx (q/sql "SELECT id FROM book"))

;; ✅ safe — cap at 20 (PostgreSQL / most dialects)
(lw/in-readonly-tx (q/sql "SELECT id, title FROM book LIMIT 20"))

;; ✅ also fine with FETCH FIRST (SQL standard)
(lw/in-readonly-tx (q/sql "SELECT id, title FROM book FETCH FIRST 20 ROWS ONLY"))
```

Apply the same discipline to JPQL queries via `EntityManager` and to repository calls —
if a method returns a `List`, confirm the table is small before calling it without a
`Pageable` / `limit`.

---

## N+1 Hunting — Tips & Gotchas

### N+1 presence is data-dependent — always test multiple IDs
An N+1 only fires when the problematic association actually has rows. A query that looks
fine on one record may blow up on another. **Always test several representative IDs**
before concluding there is no N+1.

```clojure
;; ✅ test multiple IDs in one shot and compare query counts
(mapv (fn [id]
        (let [res (trace/trace-sql
                    (lw/run-as "admin"
                      (.myEndpoint (lw/bean "myController") id)))]
          {:id id :total-queries (:count res) :suspicious (count (:suspicious-queries (trace/detect-n+1 res)))}))
      [1 2 3 4 5])
;; => look for outliers — the problematic ID will stand out with a much higher :total-queries count
```

### `FetchType.LAZY` on a non-PK `@ManyToOne` is silently ignored by Hibernate
If a `@ManyToOne` uses `referencedColumnName` pointing to a **non-primary-key** column,
Hibernate cannot create a lazy proxy (it needs the PK to do so). The association is
effectively loaded eagerly regardless of the `LAZY` declaration, firing one SELECT per
parent row — a hidden N+1 that is invisible from reading the code alone.

```kotlin
// ⚠️ looks lazy, but Hibernate fires a SELECT per row because Uid is not the @Id
@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(name = "book_isbn", referencedColumnName = "isbn")   // ← non-PK join
open var bookIsbn: Book? = null
```

**Fix:** add an explicit `left join fetch` in the JPQL for the owning query so Hibernate
loads the full entity (including its PK) in the main query instead of per-row selects.

### Quick-test a service fix by re-implementing the core flow in Clojure

When a fix involves service-layer logic (not just a JPQL change), you can prototype it
directly in the REPL without restarting. The nREPL runs inside the same JVM, so it can
call any Spring bean — repositories, services, anything. Write a temporary Clojure
expression that reimplements the **core flow** of the service method with your candidate
fix, wrap it in `trace/trace-sql`, and measure query count live against real data.

The expression doesn't need to be a perfect replica — just enough to exercise the query
pattern you're changing. Once `trace-sql` confirms the query count drops, write the real
fix to Java and rebuild.

```clojure
;; Example: service currently does bookRepo.findAll() then lazy-loads genres/reviews/members
;; (481 queries for 200 books). Candidate fix: two eager queries + manual grouping.
;; Prototype in Clojure first:

(import '[com.example.myapp.dto AuthorSummaryDto BookWithReviewsDto ReviewDto])

(defn get-all-books-fixed []
  (let [book-repo   (lw/bean "bookRepository")
        review-repo (lw/bean "reviewRepository")
        books       (.findAllWithAuthorAndGenres book-repo)
        reviews-by-book-id
          (->> (.findAllWithMember review-repo)
               (group-by #(.getId (.getBook %)))
               (into {} (map (fn [[k vs]] [k (mapv ReviewDto/from vs)]))))]
    (mapv (fn [b]
            (BookWithReviewsDto.
              (.getId b) (.getTitle b)
              (AuthorSummaryDto/from (.getAuthor b))
              (->> (.getGenres b) (map #(.getName %)) sort vec)
              (get reviews-by-book-id (.getId b) [])))
          books)))

;; Measure — zero restarts needed
(let [res (trace/trace-sql (lw/in-readonly-tx (count (get-all-books-fixed))))]
  (select-keys res [:count :duration-ms]))
;; => {:count 2, :duration-ms 43}   ← was 481 queries, now 2
```

**Key points:**
- Access `.getId()` on a lazy proxy is safe — Hibernate does not fire a query for PKs
- `ReviewDto/from` works here because `JOIN FETCH r.member` already loaded member into L1 cache
- The expression is throwaway — only the Java fix goes to source

### Use hot-swap to confirm a JPQL fix before touching source code
Rather than edit → restart → retest, hot-swap the candidate fix, verify with `trace-sql`,
then swap back to the original to confirm the N+1 returns. Only then write the fix to
source. This round-trip gives high confidence with zero restarts.

```clojure
;; 1. swap in the fix
(hq/hot-swap-query! "myRepo" "myMethod" "select ... join fetch ...")
;; 2. confirm N+1 is gone
(trace/detect-n+1 (trace/trace-sql (lw/run-as "admin" (.myMethod ...))))
;; 3. swap back to broken — confirm N+1 returns
(hq/hot-swap-query! "myRepo" "myMethod" "select ... -- original without fetch")
(trace/detect-n+1 (trace/trace-sql (lw/run-as "admin" (.myMethod ...))))
;; 4. restore and write the fix to source
(hq/reset-query! "myRepo" "myMethod")
```

---

## Faker API — `net.brdloush.livewire.faker`

Build valid, optionally-persistable Hibernate entity instances using realistic fake data.
All datafaker access is reflective — the namespace loads safely on apps without datafaker.

### Preflight check

Always call `faker/available?` first to confirm `net.datafaker.Faker` is on the classpath:

```clojure
(faker/available?)
;; => true   (or false if datafaker is not in the project)
```

If it returns `false`, add the dependency to the target application:

```xml
<!-- Maven -->
<dependency>
  <groupId>net.datafaker</groupId>
  <artifactId>datafaker</artifactId>
  <version>2.5.4</version>
</dependency>
```

```groovy
// Gradle
implementation 'net.datafaker:datafaker:2.5.4'
```

### `faker/build-entity` API

```clojure
(faker/build-entity entity-name)
(faker/build-entity entity-name opts)
```

| Option | Type | Default | Description |
|---|---|---|---|
| `:overrides` | map | `{}` | Keyword/symbol field-name → value. Applied last; always wins. |
| `:auto-deps?` | boolean | `false` | Recursively build and wire required `@ManyToOne` associations not in `:overrides`. |
| `:persist?` | boolean | `false` | Persist the entity (and auto-built deps) via the live `EntityManager`. |
| `:rollback?` | boolean | `false` | Wrap the whole operation in a transaction that always rolls back. Meaningful only when `:persist? true`. |

### Common patterns

```clojure
;; Simple entity with no required FKs
(faker/build-entity "Author")
;; => #object[Author ... ]

;; With overrides — they always win over heuristics
(faker/build-entity "Author" {:overrides {:firstName "Agatha" :lastName "Christie"}})

;; Entity with a required FK — provide the dependency yourself
(let [author (faker/build-entity "Author" {:persist? true})]
  (faker/build-entity "Book" {:overrides {:author author} :persist? true}))

;; Let Livewire resolve the full dependency chain automatically
(faker/build-entity "Book" {:auto-deps? true :persist? true})

;; Speculative pattern: persist + rollback — get a real DB-assigned id without leaving data behind.
;; Useful for calling a service with a real entity while ensuring nothing persists.
(let [review (faker/build-entity "Review" {:auto-deps? true :persist? true :rollback? true})]
  (println "Got id:" (.getId review))
  ;; Call your service here — entity has a real id from the DB sequence
  ;; Everything is rolled back when the block exits
  )

;; Combine with trace/trace-sql to inspect what the cascade generates
(trace/trace-sql
  (faker/build-entity "Review" {:auto-deps? true :persist? true :rollback? true}))
;; => {:result #object[Review ...], :count 4, :duration-ms 23, :queries [...]}
```

### Heuristics and skip rules

The generator matches property names case-insensitively against a priority table:
`firstName` → `faker.name().firstName()`, `isbn` → `faker.code().isbn13()`,
`*Year` suffix → year between 1850–2024, `*At`/`*Since` suffix → past date, etc.
String values are clamped to `@Column(length=…)` when available.

**Skipped automatically:**
- `@Id` / identifier property (auto-generated by the DB)
- `@OneToMany` / `@ManyToMany` collections (use `:overrides {:genres [...]}` if needed)
- Any property present in `:overrides`

### Lookup-table detection (Genre problem)

Entities with a `unique=true` string column and no required `@ManyToOne` associations
are detected as reference/lookup tables (e.g. `Genre`). When `:auto-deps? true` encounters
one as a dependency, it fetches a random existing row instead of creating a new one —
preventing unique-constraint violations on seeded data.

### Throws

`faker/build-entity` throws a descriptive `ex-info` with `:missing-association` when a
required `@ManyToOne` is unresolved and `:auto-deps?` is false:

```clojure
(faker/build-entity "Book")
;; throws: "Cannot build Book: required association 'author' (→ Author) is not provided.
;;          Either:
;;           • pass it via :overrides {:author <instance>}
;;           • set :auto-deps? true to let Livewire resolve it automatically"
```

### CLI

```bash
# Build an Author (no required FKs)
lw-build-entity Author

# Build a Book, auto-resolving its Author dependency
lw-build-entity Book '{:auto-deps? true}'

# Build a Review, persist + rollback (speculative — nothing left in DB)
lw-build-entity Review '{:auto-deps? true :persist? true :rollback? true}'
```

---

### `faker/build-test-recipe` — extract assertable values from a faker entity graph

**Problem it solves:** after prototyping with `faker/build-entity`, the generated values
(names, ratings, ISBNs, dates) are transient. Without capturing them, you have to *invent*
equivalent values when writing the Java test — severing the connection between the validated
prototype and the written test. `build-test-recipe` captures them for you.

**Always run `lw-build-test-recipe` before writing any integration test setup code.**
Read the output and use those exact values in `@BeforeEach` and assertions.

```clojure
(faker/build-test-recipe entity-name)
(faker/build-test-recipe entity-name opts)   ;; opts: :overrides only (auto-deps/persist/rollback are always true)
```

The entity graph is always built with `:auto-deps? true :persist? true :rollback? true` —
nothing is left in the database.

**Output format:** ordered map keyed by entity class name (root entity first, `@ManyToOne`
deps after in resolution order). Each value is a map of scalar fields only — strings, numbers,
booleans, dates. `@Id` and collection properties are excluded. `null` values are included.

```clojure
(faker/build-test-recipe "Review")
;; => {:Review  {:rating 5
;;               :comment "A remarkable journey through the highs and lows of modern life."
;;               :reviewedAt #object[LocalDateTime "2024-07-14T11:23:05"]}
;;     :Book    {:title "The Midnight Crisis" :isbn "978-3-16-148410-0"
;;               :publishedYear 1998 :availableCopies 3 :archived false}
;;     :Author  {:firstName "Kip" :lastName "O'Reilly" :birthYear 1951 :nationality "American"}
;;     :LibraryMember {:username "kelsey.schaden" :fullName "Kelsey Schaden"
;;                     :email "kelsey.schaden@example.com"
;;                     :memberSince #object[LocalDate "2019-03-22"]}}
```

**Workflow:**

1. Run `lw-build-test-recipe Review` — note all the values.
2. Write `@BeforeEach` using those exact values:
   `member.setFullName("Kelsey Schaden")`, `review.setRating((short) 5)`, etc.
3. Write assertions using the same values:
   `assertThat(dto.reviewerName()).isEqualTo("Kelsey Schaden")`
4. Run the Clojure service prototype (`lw-build-entity` + REPL call) to validate the happy path.
5. Only then write the final Java test.

**Overrides flow through to the recipe:**

```clojure
;; Specific values for assertions — they appear in the output as supplied
(faker/build-test-recipe "Review" {:overrides {:rating 1 :comment "Terrible."}})
;; => {:Review {:rating 1, :comment "Terrible.", ...} ...}
```

**CLI:**

```bash
lw-build-test-recipe Review
lw-build-test-recipe Review '{:overrides {:rating 1 :comment "Terrible."}}'
```

---

## ⚠️ Known Pitfalls

### New repository methods require a restart — the query-watcher cannot inject them

The query-watcher can only hot-swap JPQL strings in `@Query` methods that **already existed at startup**.
If you add a brand-new method to a Spring Data repository interface, compile it, and update the service
to call it, the running JVM will not pick up the change — for two reasons:

1. **The JVM classloader** won't reload an already-loaded interface. The new `.class` on disk is ignored;
   the old interface definition (without the new method) stays live in memory.
2. **The Spring Data proxy** was created at startup from the old interface. It has no knowledge of methods
   added after the fact, so calling the new method throws `NoSuchMethodError` or simply isn't reachable.

This is distinct from editing an existing `@Query` JPQL string, which the watcher handles transparently.

**Rule of thumb:** if `javap` shows the new method on disk but the REPL proxy doesn't have it, this is
the cause. A restart is the correct fix — not cache flushing or `force-rescan!`.

```bash
# Confirm the compiled artifact is correct
javap -p target/classes/com/example/yourapp/repository/YourRepository.class

# Confirm the proxy is missing the method
clj-nrepl-eval -p 7888 '(->> (.getClass (lw/bean "yourRepository")) .getMethods (map #(.getName %)) sort)'
# If the new method is absent here but present in javap output → restart required
```

### `lw-eval` mangles Clojure-idiomatic characters — use `clj-nrepl-eval` directly

`lw-eval` passes its argument through the shell, where characters common in Clojure
symbol names are misinterpreted:

| Character | Clojure use | Shell hazard |
|---|---|---|
| `!` | Mutating fns: `reset-all!`, `hot-swap-query!`, `swap!` | zsh history expansion |
| `?` | Predicates: `running?`, `empty?` | Glob / conditional |
| `->`, `->>` | Threading macros | Redirect / `>>` append |

**Rule: never use `lw-eval` for expressions containing these characters.** Use
`clj-nrepl-eval -p <port>` directly with a double-quoted string instead — the
expression reaches the JVM unmodified:

```bash
# ❌ lw-eval silently drops the ! — "No such var: hq/reset-all"
lw-eval '(hq/reset-all!)'

# ✅ clj-nrepl-eval passes the expression verbatim
clj-nrepl-eval -p 7888 "(hq/reset-all!)"
```

Use the dedicated wrapper scripts (`lw-sql`, `lw-jpa-query`, `lw-call-endpoint`, etc.)
for their named operations. For everything else, go straight to `clj-nrepl-eval`.

### Wrapper script string arguments inherit the same shell hazards — avoid `!` in string values

All wrapper scripts (`lw-build-entity`, `lw-build-test-recipe`, `lw-call-endpoint`, etc.) pass
their arguments through the shell. **Any `!` inside a string literal in an EDN opts map will be
treated as a zsh history expansion**, causing it to be mangled before Clojure ever sees it.

This applies to `:overrides` comment strings or any other string value — not just Clojure symbol
names:

```bash
# ❌ ! in string value triggers zsh history expansion
lw-build-test-recipe Review '{:overrides {:comment "Absolutely wonderful!"}}'
# Error: Unsupported escape character: \!

# ✅ simply avoid ! in string values passed via wrapper scripts
lw-build-test-recipe Review '{:overrides {:comment "Absolutely wonderful"}}'

# ✅ or use clj-nrepl-eval directly with a double-quoted outer string
clj-nrepl-eval -p 7888 "(faker/build-test-recipe \"Review\" {:overrides {:comment \"Absolutely wonderful!\"}})"
```

**Rule: when an override string needs `!`, switch to `clj-nrepl-eval` directly.**

### `intro/list-entities` uses `:name` and `:class`, not `:simple-name`
The docstring mentions "simple name + FQN" but the actual map keys are `:name` and `:class`.
Using `:simple-name` returns nil for every entry and causes a NullPointerException in regex filters.

```clojure
;; ❌ NullPointerException
(->> (intro/list-entities) (map :simple-name) (filter #(re-find #"Foo" %)))

;; ✅ correct
(->> (intro/list-entities) (map :name) (filter some?) (filter #(re-find #"Foo" %)))
```

### Never call `.findAll` without a `Pageable` — it may return millions of rows
`.findAll()` on a `JpaRepository` has no built-in limit and will eagerly load every row in
the table. On large production-like datasets this will hang the REPL and potentially OOM the JVM.
Always pass a `PageRequest` to cap results, or use a more specific query method.

```clojure
;; ❌ danger: fetches every row in the table
(.findAll (lw/bean "bookRepository"))

;; ✅ cap at 20 rows using Pageable
(->> (.findAll (lw/bean "bookRepository")
               (org.springframework.data.domain.PageRequest/of 0 20))
     .getContent
     (mapv #(select-keys (clojure.core/bean %) [:id :title :isbn])))

;; ✅ or use a native/JPQL query with an explicit limit
(lw/in-readonly-tx (q/sql "SELECT id, title FROM book LIMIT 20"))
```

### `lw/bean SomeClass` only resolves Spring beans, not JPA entities
JPA entity classes are not Spring beans. Passing an entity class throws `NoSuchBeanDefinitionException`.
Use `lw/bean "repositoryBeanName"` to access data — find the right name with `lw/find-beans-matching`.

```clojure
;; ❌ NoSuchBeanDefinitionException
(lw/bean eu.example.MyEntity)

;; ✅ find the repository instead
(lw/find-beans-matching ".*MyEntity.*[Rr]epo.*")
(lw/bean "myEntityRepository")
```

### `EntityManager` is not registered as a named bean — use type-based lookup

`EntityManager` is a scoped proxy tied to the current persistence context. Spring does **not** register it under the name `"entityManager"`, so `(lw/bean "entityManager")` throws `NoSuchBeanDefinitionException`. Use the type-based form instead, which resolves the shared proxy bean (`jpaSharedEM_entityManagerFactory`) correctly:

```clojure
;; ❌ NoSuchBeanDefinitionException — "entityManager" is not a registered bean name
(lw/bean "entityManager")

;; ✅ type-based lookup resolves the shared proxy
(let [em (lw/bean jakarta.persistence.EntityManager)]
  (lw/in-tx
    ;; ... persist entities ...
    (.flush em)
    (.clear em)))
```

This pattern is needed in REPL test prototyping when you need to flush and clear the L1 cache between setup and the service call under test.

### `lw-call-endpoint` and `lw/bean` expect the Spring bean name, not the class name

`intro/list-endpoints` reports `:controller` as the **fully-qualified class name** (e.g.
`"com.example.myapp.web.AdminController"`). The Spring bean name is **not** the simple class
name — it is the camelCase version with a lowercase first letter (e.g. `adminController`).
Passing the class simple name directly to `lw-call-endpoint` or `lw/bean` throws
`NoSuchBeanDefinitionException`.

**Rule:** when calling an endpoint discovered via `list-endpoints`, always derive the bean
name by lowercasing the first letter of the simple class name, or verify with
`lw/find-beans-matching` before calling.

```bash
# ❌ NoSuchBeanDefinitionException — AdminController is the class name, not the bean name
lw-call-endpoint AdminController archiveBook ROLE_ADMIN 1

# ✅ correct — lowercase first letter
lw-call-endpoint adminController archiveBook ROLE_ADMIN 1

# ✅ or verify the exact bean name first
clj-nrepl-eval -p 7888 "(lw/find-beans-matching \".*[Aa]dmin.*\")"
# => ("adminController" ...)
lw-call-endpoint adminController archiveBook ROLE_ADMIN 1
```

### `clojure.core/bean` silently returns `{}` for Java records

Java records (DTOs, projections) generate accessor methods without the `get` prefix —
`rating()`, `comment()`, etc. `clojure.core/bean` only sees `getX()` methods, so it returns
an empty map `{}` with no error.

**Always use `lw/bean->map` instead of `clojure.core/bean`** when converting any result object
to a map — it dispatches to `getRecordComponents()` for records and falls back to
`clojure.core/bean` for everything else:

```clojure
;; ❌ silent empty map for a Java record DTO
(clojure.core/bean some-stats-dto)
;; => {:class com.example.StatsDto}   ← only :class, all fields missing

;; ✅ correct — full field map regardless of record vs plain class
(lw/bean->map some-stats-dto)
;; => {:totalBooks 200, :totalAuthors 30, :totalMembers 50, ...}
```

### `clojure.core/bean` on a Spring proxy exposes proxy internals, not domain properties
Controllers and services are CGLIB proxies. Calling `(clojure.core/bean proxy)` returns proxy metadata
(`:advisors`, `:callbacks`, `:frozen`, etc.), not the bean's own fields or properties.
To discover what methods to call on a bean, read the source code instead.

### `@PreAuthorize` on controllers blocks direct REPL invocation
Calling a controller or service method directly from the REPL throws
`AuthenticationCredentialsNotFoundException` because there is no Spring Security context.
Use `lw/run-as` to set one, or bypass to the underlying service if security is not relevant.

```clojure
;; ❌ AuthenticationCredentialsNotFoundException
(.myEndpoint (lw/bean "myController") someArg)

;; ✅ preferred: use run-as to exercise the real secured code path
(lw/run-as "admin"
  (.myEndpoint (lw/bean "myController") someArg))

;; ✅ alternative: call the service the controller delegates to (skips security entirely)
(.myServiceMethod (lw/bean "myService") someArg)
```

### Use `jakarta.persistence` not `javax.persistence` on Spring Boot 3+

Spring Boot 3 migrated to Jakarta EE. When importing `EntityManager` or other JPA types
directly in REPL expressions, use the `jakarta.persistence` package.

```clojure
;; ❌ ClassNotFoundException on Spring Boot 3+
(import 'javax.persistence.EntityManager)

;; ✅ correct
(import 'jakarta.persistence.EntityManager)
(lw/bean EntityManager)
```

### `q/sql` is query-only — use raw JDBC for DDL

`q/sql` executes via `executeQuery` and expects a result set. DDL statements (`CREATE INDEX`,
`ALTER TABLE`, etc.) return no rows and throw `PSQLException: No results were returned by the query`.
Use a raw JDBC connection instead.

```clojure
;; ❌ PSQLException: No results were returned by the query
(lw/in-tx (q/sql "CREATE INDEX idx_foo ON bar(baz)"))

;; ✅ raw JDBC for DDL
(let [ds (lw/bean javax.sql.DataSource)]
  (with-open [conn (.getConnection ds)]
    (-> conn .createStatement (.execute "CREATE INDEX idx_foo ON bar(baz)"))))
```

### First call after restart inflates timing — always warm up before measuring

The JVM JIT hasn't compiled anything on a fresh restart. The first call can be 5–10× slower
than steady-state. Always run several iterations before drawing conclusions about performance.

```clojure
;; ❌ misleading — first call may show 98ms due to cold JIT
(:duration-ms (trace/trace-sql (lw/run-as "admin" (.myEndpoint (lw/bean "myController")))))

;; ✅ warm up first, then measure
(mapv (fn [_] (:duration-ms (trace/trace-sql (lw/run-as "admin" (.myEndpoint (lw/bean "myController"))))))
      (range 5))
;; => [98 25 15 12 12]  ← ignore the first result
```

### `trace/trace-sql` requires Livewire ≥ 0.1.0-SNAPSHOT (post Hibernate 7 fix)
SQL tracing works with both Hibernate 6 and 7. Older Livewire builds silently registered
no `StatementInspector` on Hibernate 7 apps, resulting in `{:count 0, :queries []}`.
Ensure the app is running with a current Livewire JAR.

---

## Examples

```clojure
;; What DB URL is the app actually using?
(lw/props-matching "spring\\.datasource\\.url")
;; => {"spring.datasource.url" "jdbc:postgresql://localhost:5432/myapp"}

;; Which repository beans exist?
(lw/find-beans-matching ".*Repository.*")
;; => ("bookRepository" "authorRepository" ...)

;; Query a repository safely — always page or limit (see pitfalls)
(lw/in-readonly-tx
  (->> (.findAll (lw/bean "bookRepository")
                 (org.springframework.data.domain.PageRequest/of 0 3))
       .getContent
       (mapv #(select-keys (clojure.core/bean %) [:id :title :isbn]))))
;; => [{:id 1, :title "All the King's Men", :isbn "..."}
;;     {:id 2, :title "A Handful of Dust", :isbn "..."}
;;     {:id 3, :title "Butter In a Lordly Dish", :isbn "..."}]

;; Mutate safely — rolls back automatically
;; (count here is intentional — we want the total, not a page of rows)
(lw/in-tx
  (.save (lw/bean "bookRepository") (->Book "New Title"))
  (.count (lw/bean "bookRepository")))

;; Capture the SQL a service method fires
(trace/trace-sql
  (lw/in-readonly-tx
    (.count (lw/bean "bookRepository"))))
;; => {:result 200, :queries [{:sql "select count(*) ...", :caller "..."}], :count 1, :duration-ms 15}

;; Hunt for N+1 queries
(trace/detect-n+1
  (trace/trace-sql
    (lw/run-as "member1"
      (.getBooks (lw/bean "bookController")))))
;; => {:suspicious-queries [{:sql "select ...", :caller "...", :count 200} ...],
;;     :total-queries 481, :duration-ms 1271}

;; Discover all HTTP endpoints
(first (intro/list-endpoints))
;; => {:methods ["GET"], :paths ["/api/authors/{id}"], :controller "AuthorController", ...}

;; Inspect a Hibernate entity's DB mappings
(intro/inspect-entity "Book")
;; => {:table-name "book", :identifier {:name "id", :columns ["id"], :type "long"},
;;     :properties [{:name "title", :columns ["title"], :type "string"} ...],
;;     :relations [{:name "author", :type :many-to-one, :target "Author"} ...]}

;; Call a @PreAuthorize-guarded controller method directly
(lw/run-as "admin"
  (.getBookById (lw/bean "bookController") 25))
;; => #object[BookDto ...]

;; Live-swap a JPQL query, verify with trace-sql, then restore
(hq/hot-swap-query! "bookRepository" "findByIdWithDetails"
  "select b from Book b join fetch b.author join fetch b.reviews where b.id = :id")
(trace/trace-sql
  (lw/run-as "admin"
    (lw/in-readonly-tx
      (.findByIdWithDetails (lw/bean "bookRepository") 25))))
;; => {:result [...], :queries [{:sql "select ... join addresses ..."}], :count 1, :duration-ms 8}
(hq/reset-query! "bookRepository" "findByIdWithDetails")
;; => :restored
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
livewire

Directory Structure

SKILL.md

Report

Notice
