backlens 0.2.3 → 0.2.4

package/README.md

@@ -1,29 +1,68 @@
 # backlens
 
-See every request your Node backend handles, every query it makes, and what is wrong with them. No code changes, no account, nothing leaves your machine.
+**See what your Node backend really does on every request, find what is slow, and get the fix proven before you keep it.**
+
+[![npm](https://img.shields.io/npm/v/backlens)](https://www.npmjs.com/package/backlens)
+[![license](https://img.shields.io/npm/l/backlens)](LICENSE)
+[![node](https://img.shields.io/node/v/backlens)](package.json)
 
 ```
 npx backlens
 ```
 
-Run it in your server's folder. Your browser opens the dashboard; the first time, pick which package.json script starts the app and which runs the tests. From then on everything happens in the browser: start, stop and restart the app, read its logs, run the tests, accept known issues, compare before and after.
+One command, in your server's folder. No code changes, no account, nothing leaves your machine.
+
+---
+
+## What it does
+
+backlens runs your app with a small recorder inside it and opens a dashboard in your browser. As you use your app, every request shows up with the database queries, Redis calls and outgoing HTTP calls it made, and the line of your code behind each one.
+
+From that real traffic it finds what makes backends slow:
+
+| Issue | What it looks like | Example |
+|---|---|---|
+| **N+1** | one query run once per item in a loop | 20 reviews → 20 `select name from users where id = $1` |
+| **Repeated calls** | the same query with the same values twice in one request | two services both load the current user |
+| **Calls that wait for each other** | independent queries awaited one after another | `await getCounts(); await getRows();` |
+| **Missing indexes** | Postgres reads every row to filter a table | `where state = $1 order by updated_at desc`, no index |
+
+Each issue points at the file and line that caused it, opens in your editor, and can be explained or fixed.
+
+## Fixes, with proof
+
+**Suggest fix** shows the change as a diff. **Apply and check** then:
+
+1. keeps an exact copy of every file it touches
+2. applies the change and runs your typecheck (type errors go back to the model, up to twice)
+3. restarts your app, warms it up, and replays the request that showed the issue
+4. runs your tests
+
+Only a change that removes the issue and keeps the tests green is marked **proven**, and you see the same request before and after:
+
+```
+                    before      after
+time (median)       48 ms   →   21 ms   -56%
+database queries    22      →   2       -91%
+issue               found   →   gone
+```
 
-The link backlens prints carries a private token: keep it to yourself, it controls your app. The dashboard listens on 127.0.0.1 only, refuses requests from other sites, and only ever runs scripts from your package.json by name.
+Then **Keep** it, or **Revert** to the exact files you had.
 
-To run one exact command instead: `npx backlens -- node server.js`.
+Some fixes need no AI: running independent calls together (`Promise.all`) and missing indexes are written by backlens itself. A missing index can be created on your dev database from the dashboard, checked against the query's plan, and undone.
 
-To keep it in the project, install it as a dev dependency with your package manager (`npm i -D backlens`, `pnpm add -D backlens`, `yarn add -D backlens`). In a pnpm or yarn workspace, use that tool: npm cannot install into a project whose package.json uses `workspace:` versions.
+## AI: none, local or Claude
 
-The dashboard uses port 7777, or the next free one if it is taken. `--port` picks one.
+Set up in **AI settings**, entirely from the dashboard.
 
-## What you get
+| | Cost | Privacy | Good for |
+|---|---|---|---|
+| **No model** | free | nothing leaves your machine | plain explanations, the built-in fixes |
+| **Local model** via [Ollama](https://ollama.com) | free | code stays on your machine | explaining; fixes are hit-and-miss on small models |
+| **Claude**, your own key | a few cents per fix | what the preview shows is sent to Anthropic | the strongest fixes |
 
-- **Routes**: every endpoint your app registers (fastify and nest report them at startup; express routes appear once called), with calls, p50 and p95, and how many database, Redis and outgoing HTTP calls each request makes.
-- **Requests**: a waterfall of any single request, with the line of your code behind each call.
-- **Issues**: problems found in real traffic, worst first, each pointing at the code that caused it:
-  - **Repeated calls**: the same query with the same values twice in one request. backlens names the two places the code paths part, which is where the second fetch comes from.
-  - **N+1**: one query run three or more times with different values in one request.
-  - **Calls that wait for each other**: two or more calls of the same kind, awaited back to back in one function. Shown as a hint: if they don't depend on each other, `Promise.all` runs them together.
+- The local card links to the Ollama download, notices when it runs, suggests the `qwen2.5-coder` size that fits your memory and downloads it with a progress bar.
+- A Claude key is pasted in the dashboard, checked for free, and saved in your user folder (`~/.config/backlens`, readable by you only), never in the project. Haiku explains; Sonnet or Opus fixes, depending on how hard the issue is. The cost is estimated before sending and a daily budget (default $1) is enforced. A typical fix costs about $0.03.
 
 ## In CI: fail the build on new issues
 
@@ -31,64 +70,89 @@ The dashboard uses port 7777, or the next free one if it is taken. `--port` pick
 npx backlens test -- npx vitest run
 ```
 
-Runs your test command with recording on, prints every issue it found, and exits 1 when there is a new warning. Tests that call the app over HTTP (supertest, fetch) are recorded like real traffic.
-
-- `--update-baseline` accepts everything found in this run as known, in `backlens.baseline.json`. Commit that file. An issue keeps its identity when lines above it move.
-- `--strict` fails on new hints too.
-- `--json report.json` writes the report for a CI artifact.
+Runs your tests with recording on, prints every issue, and exits 1 on a new one. Tests that call your app over HTTP (supertest, fetch) count as real traffic.
 
 ```
 backlens  90 requests (207 queries, 241 redis, 0 http out), 11 of 47 routes called, 3 issues, 2 new
   new   3 calls are made twice in one request  GET /v1/lessons/:id, 5/11 requests
         src/modules/access/access.service.ts:75 → src/modules/access/access.service.ts:55
-  36 routes never called by these tests
 backlens: 2 new issues. Fix them, or accept with --update-baseline.
 ```
 
-## Missing indexes
+- `--update-baseline` accepts what this run found, in `backlens.baseline.json`. Commit it.
+- `--strict` fails on new hints too. `--json report.json` writes the report for a CI artifact.
 
-For each distinct SELECT, backlens asks Postgres for its plan with `EXPLAIN (GENERIC_PLAN)` (Postgres 16+). Plain EXPLAIN never runs the query, and the generic plan needs no parameter values. When a table is read row by row while filtering on columns that no index starts with, the Issues tab names the table and columns and gives the `CREATE INDEX` to add. It checks whether an index exists, not how fast the query was, so it is right on a small dev database too. When the query also sorts (`ORDER BY … LIMIT`), the sort columns go after the filter columns, so Postgres reads rows already in order.
+## The dashboard
 
-**Create on this database** builds the index on the database your app is connected to, through the app's own connection: backlens never sees a database password. It shows which database first, builds with `CONCURRENTLY` so writes are not blocked, checks that Postgres can use the index for the query, and **Undo** drops it again. Only an index on the columns backlens checked can be created this way, never arbitrary SQL. Use it on a development database, then add the SQL to a migration.
+- **Map**: a live diagram of your routes, the tables and Redis keys they touch, and where the issues are.
+- **Routes**: every endpoint with calls, p50, p95 and queries per request.
+- **Issues**: worst first, with Explain, Suggest fix and the request that showed it.
+- **Requests**: a waterfall of any request, with the code behind each call.
+- **Tests**: run your test script and see what it hit.
+- **Compare**: snapshot, change code, compare per route.
 
-## Before and after
+Start, stop, restart and read your app's logs from the same page.
+
+## Getting started
+
+```
+cd your-server
+npx backlens
+```
 
-In the Compare tab, save a snapshot, change your code, restart, use the same pages, and compare per route: queries and Redis calls per request, p50 and issues. Snapshots are kept in `.backlens/snapshots` in your project; add `.backlens/` to `.gitignore`. Timings only count as a change with 5 or more calls on both sides.
+The first time, pick which `package.json` script starts the app (like `dev`) and which runs the tests. backlens remembers this in `.backlens/` and adds it to your `.gitignore`.
 
-## Explain and fix, with proof
+- Keep it in the project: `npm i -D backlens`, `pnpm add -D backlens` or `yarn add -D backlens` (in a pnpm or yarn workspace, use that tool).
+- Run one exact command: `npx backlens -- node server.js`.
+- Port 7777, or the next free one. `--port` picks one, `--no-open` skips the browser.
 
-Every issue has **Explain** and **Suggest fix**. A fix goes: a preview of exactly what would be sent and to whom, the model's answer as a diff, **Apply and check** (with an exact copy of each file kept first, uncommitted changes included; Revert refuses to overwrite edits you made after the fix was applied), then backlens rebuilds if needed, restarts your app, replays the request that showed the issue and runs your tests. Only a fix that removes the issue and keeps the tests green is marked proven. Keep it, or revert to the exact files you had.
+## Works with
 
-Who answers is set up in **AI settings**, all from the dashboard. The first-run setup asks too.
+| | |
+|---|---|
+| Frameworks | express, fastify, nest, Next.js route handlers, plain `node:http` |
+| Database | `pg` (Client and Pool): drizzle, Kysely, knex, raw SQL on Postgres |
+| Cache | `ioredis` |
+| Outgoing calls | global `fetch` |
+| Modules | CommonJS and ESM, vitest included |
+| Runtime | Node 20+, tested on macOS; Linux should work the same way |
 
-- **Local model** (free, private): runs on your computer through [Ollama](https://ollama.com). The card walks you through it: a link to install Ollama, then it notices when Ollama is running, suggests the model that fits your memory (`qwen2.5-coder` 3B for 8 GB, 7B for 16 GB, 14B for 32 GB) and downloads it with a progress bar. Small models explain well; their fixes are hit-and-miss, and every fix is checked anyway.
-- **Claude with your own key**: paste the key and backlens checks it for free before saving it in your user folder (`~/.config/backlens`, readable by you only), never in the project. `ANTHROPIC_API_KEY` in the environment wins if set. Explaining uses Claude Haiku 5.5; fixes use Sonnet 5.5 or Opus 5.5 depending on how hard the issue looks (files involved, issue type, test coverage, your past results), one step up after a failed check. A daily budget (default $1) is enforced before sending.
-- **No model**: explanations in backlens's own words.
+Not yet: Prisma, mysql2, MongoDB, Windows.
 
-Some fixes never use a model: running independent calls together (`Promise.all`) and missing indexes are written by backlens itself, the same way every time.
+## Privacy and safety
 
-Values that look like secrets are masked, `.env` files and `node_modules` are never read, and requests kept for replay stay in memory only. Replaying a POST, PUT or DELETE runs it again against your dev database, so it is off unless you allow it in AI settings.
+- **Values never leave your app.** Query parameters and results become short hashes; emails, IPs and ids in Redis keys are masked.
+- **The dashboard is yours only.** It listens on 127.0.0.1, needs the private token in the link it prints, and refuses requests from other websites.
+- **It runs only scripts from your `package.json`,** by name.
+- **Files change only when you click Apply,** with a copy kept first. Revert never overwrites edits you made afterwards.
+- **AI sees only what the preview shows.** Secret-looking values are masked; `.env` and `node_modules` are never read.
+- **Replaying writes is off by default,** since it changes your dev database again.
+- **Indexes are built from checked table and column names** through your app's own connection: backlens never sees a database password.
 
 ## How it works
 
-`backlens` starts the dashboard, then runs your command with `NODE_OPTIONS=--require backlens/register`. Inside your app, the register script:
-
-- times each incoming request on Node's own HTTP server, so it works with express, fastify, nest, Next.js and plain `http`, and records requests the client cancels. Framework internals such as `/_next/` assets and favicons are skipped;
-- wraps `pg` (Client and Pool), `ioredis` and global `fetch`;
-- records where each call came from. For ORMs like drizzle, which call the driver from a microtask, the call site is read from V8's async stack once the query settles. Code run from bundled chunks (Next.js with Turbopack or webpack) is traced back to your source files through their source maps.
+`backlens` starts the dashboard, then runs your app with `NODE_OPTIONS=--require backlens/register`. Inside your app, the recorder:
 
-Query values are never sent, only a short hash so identical questions can be told apart from different ones. Emails, IP addresses and ids in Redis keys are masked. The dashboard listens on 127.0.0.1 only and keeps the last 1000 requests in memory.
+- times each request on Node's own HTTP server, so any framework on top of it works;
+- wraps `pg`, `ioredis` and `fetch`, and records the line of your code behind each call, through V8's async stack traces for ORMs like drizzle and through source maps for bundled code;
+- asks Postgres for each distinct SELECT's plan with `EXPLAIN (GENERIC_PLAN)` (Postgres 16+), which never runs the query, and flags full-table reads no index covers.
 
-## Limits of this version
+## Limits
 
-- Tested on macOS with Node 20+, on a nest + fastify + drizzle app and a Next.js 16 + drizzle app. Linux should work the same way; Windows is untested.
-- Requests, `pg` and `ioredis` are recorded in CommonJS and ESM apps (vitest included). The up-front route list needs fastify loaded through CommonJS, as nest does.
-- `pg`, `ioredis` and `fetch` only. No Prisma, mysql or mongo yet.
-- The index advisor needs Postgres 16 or newer, and looks at equality filters only.
-- The "wait for each other" hint skips calls whose input matches an earlier call's output, but it cannot see every dependency (a value changed before use, an order that matters for side effects), so read it as a question, not a verdict.
+- The "wait for each other" hint skips calls that use an earlier call's result, but it cannot see every dependency: read it as a question, not a verdict.
+- The index advisor needs Postgres 16+ and looks at equality filters and the sort above them.
+- Timings on a dev machine are rough; query counts are exact.
 
 ## Develop
 
 ```
+git clone https://github.com/shayandutta/backlens
+cd backlens && npm install
 node --test test/
 ```
+
+Bug reports and pull requests are welcome.
+
+## License
+
+[MIT](LICENSE) © Shayan Dutta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlens",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Run your Node backend through backlens and see every request, every query, and what is wrong with them.",
   "license": "MIT",
   "type": "module",