api-tracer-kit 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.1.0
+
+- `api-tracer setup` wires the tracer into an application in one command. It
+  detects the framework, writes the module that configures the tracer with the
+  environment gate that bundler will actually fold, adds the import to the entry
+  file, gitignores the data directory, and warns if anything else already calls
+  `init()`. Safe to re-run.
+- Full documentation set under `docs/`, shipped in the package.
+
 ## 1.0.1
 
 - `init()` now warns when it is called a second time with options, naming the

package/README.md

@@ -3,13 +3,17 @@
 Trace every API call an application makes — and map, exercise and watch the
 endpoints it has.
 
+[![npm](https://img.shields.io/npm/v/api-tracer-kit.svg)](https://www.npmjs.com/package/api-tracer-kit)
+[![license](https://img.shields.io/npm/l/api-tracer-kit.svg)](./LICENSE)
+
 Two halves that work on their own or together:
 
-- **the tracer** — a framework-free library that records every `fetch`, `XMLHttpRequest`
-  and axios call, with no change to your API layer and no bundler configuration.
+- **the tracer** — a framework-free library that records every `fetch`,
+  `XMLHttpRequest` and axios call, with no change to your API layer and no
+  bundler configuration
 - **the console** — a CLI and web UI that reads your source into an endpoint
   catalog, receives the tracer's traffic, and lets you re-send any call, watch
-  for response-shape drift, and export what it captured.
+  for response-shape drift, and export what it captured
 
 ```bash
 npm install api-tracer-kit
@@ -17,26 +21,45 @@ npm install api-tracer-kit
 
 ## Quick start
 
+One command wires it into your app — it detects the framework, writes the module
+that configures the tracer, and adds the import to your entry file:
+
+```bash
+npx api-tracer setup
+```
+
+Or do it by hand, which is two lines:
+
 ```ts
 import { apiTracer } from 'api-tracer-kit';
 
 apiTracer.init();
 ```
 
-That is the whole setup. Every call made afterwards is traced:
+Either way, that is the whole setup. Every call made afterwards is traced:
 
 ```ts
 await fetch('/api/users');
 
 apiTracer.getTraces();
-// [{ id, request: { url, method, headers, params, body }, response: { status, headers, body },
+// [{ id, request: { url, method, headers, params, body },
+//    response: { status, headers, body },
 //    timing: { startedAt, completedAt, duration }, status: 'success' }]
 ```
 
 Nothing happens at import time, so the package is safe to import during SSR, in
 a build step, or in a test. `init()` is the only thing that patches anything.
 
-Then, optionally, the console:
+**Using axios?** Hand yours over — an axios instance has no global to patch:
+
+```ts
+apiTracer.useAxios(axios);
+```
+
+One call covers the default export and every instance `axios.create()` makes
+afterwards.
+
+**Want the console?**
 
 ```bash
 npx api-tracer start
@@ -46,6 +69,22 @@ It reads your source, finds your endpoints, and opens at
 `http://localhost:4400`. Point the tracer at it with `reportTo: true` and your
 app's own traffic fills it in as you click around.
 
+> Configure the tracer in exactly one place. `init()` is idempotent — a second
+> call keeps the first one's configuration and warns about what it ignored.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Getting started](./docs/getting-started.md) | install, first trace, seeing them |
+| [Tracer API](./docs/tracer.md) | every option, the `ApiTrace` model, storage, axios, lifecycle |
+| [The console](./docs/console.md) | CLI, dashboard, replay, drift, coverage, import/export, deployment |
+| [Configuration](./docs/configuration.md) | the config file, scanner presets, custom parsers, sign-in flows |
+| [Frameworks](./docs/frameworks.md) | React, Next.js, Vite, CRA, Node, testing |
+| [Troubleshooting](./docs/troubleshooting.md) | when nothing is being recorded |
+| [Security](./docs/security.md) | redaction, what is stored, what is safe to share |
+| [Architecture](./docs/architecture.md) | how it works inside, and why |
+
 ## Features
 
 **Tracing**
@@ -60,24 +99,23 @@ app's own traffic fills it in as you click around.
 - files in a `FormData` recorded as `<file: scan.pdf, 20418 bytes>`
 - a unique id per call, and no mixing between concurrent requests
 - credential redaction in headers and bodies, on by default
-- envelope reading, for APIs that answer `200` and put the real verdict in the body
-- subscribers, a replaceable storage layer, and a capped in-memory store by default
+- envelope reading, for APIs that answer `200` and put the verdict in the body
+- subscribers, a replaceable storage layer, a capped in-memory store by default
 
 **Console**
 
-- an endpoint catalog read straight out of your source — no hand-maintained list
+- an endpoint catalog read straight out of your source — nothing hand-maintained
 - live recording: your app's traffic lands on the endpoint it belongs to, with
   the real params, payload and path ids already filled in
-- send any endpoint, with a Postman-style tabbed editor (params, headers, body,
-  capture rules) and a syntax-highlighted JSON editor
-- bulk runs, and a full replay of every captured call, with a plan shown before
-  anything is sent
+- send any endpoint, with a Postman-style tabbed editor and a syntax-highlighted
+  JSON editor
+- bulk runs, and a full replay of every captured call, with a plan shown first
 - response-shape contracts, so a backend that quietly drops a field is caught
   even though it answered `200`
 - coverage: which endpoints your app has never exercised
 - an insight report — coverage, failures, drift, risks, hygiene, auth surface,
-  latency, inventory and a trend line — exportable as Markdown or JSON
-- HAR / cURL / Postman export, and HAR / cURL import
+  latency, inventory, trend — as Markdown or JSON
+- HAR / cURL / Postman export, HAR / cURL import
 - `{{variables}}`, captured from responses and chained between calls
 
 ## Supported environments
@@ -85,13 +123,13 @@ app's own traffic fills it in as you click around.
 | | |
 | --- | --- |
 | Browsers | ✅ `fetch`, `XMLHttpRequest`, axios |
-| Node 18+ | ✅ `fetch` and axios; `XMLHttpRequest` is skipped when absent |
+| Node 18+ | ✅ `fetch` and axios; `XMLHttpRequest` skipped when absent |
 | React / Next.js / Vite / CRA / webpack | ✅ no plugin, loader, alias or config change |
 | SSR and build-time execution | ✅ importing does nothing; `init()` no-ops without a runtime |
-| TypeScript | ✅ types shipped, `strict`-clean |
+| TypeScript | ✅ types shipped, `strict`-clean, `bundler` and `node16` resolution |
 | Deno / Bun | ⚠️ untested, but the tracer only uses standard globals |
 
-Nothing in the core imports React or axios. Both are optional peer dependencies
+Nothing in the core imports React or axios. Both are optional peer dependencies,
 used only by the entry points that need them.
 
 ## Entry points
@@ -103,295 +141,19 @@ import { useApiTraces } from 'api-tracer-kit/react';  // hooks
 import { ApiTracerPanel } from 'api-tracer-kit/ui';   // in-app panel
 ```
 
-Each is bundled separately, so importing the tracer never pulls in React.
-
-## Configuration
-
-All of it is optional.
-
-```ts
-apiTracer.init({
-  // which transports to patch. Default: all of them that exist.
-  transports: ['fetch', 'xhr'],
-
-  // only trace URLs matching one of these. Strings match by substring.
-  include: ['/api/'],
-  exclude: [/\/health$/],
-
-  // header names replaced with "<redacted>"
-  redactHeaders: ['authorization', 'cookie', 'set-cookie', 'x-api-key'],
-
-  // body and query field names replaced with "<redacted>"
-  redactFields: /(token|password|secret|api[-_]?key)/i,
-
-  // bodies bigger than this are recorded as omitted rather than kept
-  maxBodyBytes: 200_000,
-
-  // how many traces to keep; the oldest fall off the end
-  maxTraces: 500,
-
-  // for APIs that answer 200 and put the verdict in the body
-  envelope: { codeFields: ['status', 'code'], okField: 'success', failFrom: 400 },
-
-  // stream finished traces to the console; `true` means http://localhost:4400
-  reportTo: true,
-
-  // replace the in-memory store
-  storage: myStorage,
-
-  onTrace: (trace) => console.log(trace),
-});
-```
-
-There is no config file, and the consuming project needs no changes to its
-webpack, Vite, Babel, TypeScript, Next.js, CRA or ESLint setup.
-
-## API reference
-
-### `apiTracer`
-
-| | |
-| --- | --- |
-| `init(options?)` | installs the interceptors. Idempotent — calling it twice does not double-install, and the second call's options are ignored with a warning. Configure it in one place, or `destroy()` first. |
-| `useAxios(axios)` | traces an axios object and everything `axios.create()` makes from it |
-| `getTraces()` | every trace held, oldest first |
-| `getTrace(id)` | one trace |
-| `subscribe(fn)` | called with each finished trace; returns the unsubscribe function |
-| `clear()` | drops every trace |
-| `remove(id)` | drops one |
-| `destroy()` | restores every patched global; the app behaves exactly as it did before `init()` |
-| `isActive` | whether tracing is installed |
-
-Standalone equivalents are exported too, for callers who prefer functions:
-`initApiTracer`, `getApiTraces`, `clearApiTraces`, `subscribeToApiTraces`,
-`destroyApiTracer`.
-
-### `ApiTrace`
-
-```ts
-interface ApiTrace {
-  id: string;
-  transport: 'fetch' | 'xhr' | 'axios';
-  status: 'pending' | 'success' | 'error' | 'network-error' | 'cancelled';
-
-  request: {
-    url: string;
-    path: string;                       // origin + pathname, for grouping
-    method: string;
-    headers: Record<string, string>;
-    params: Record<string, unknown>;    // parsed query string
-    body?: unknown;                     // parsed and redacted
-    bodyType: 'json' | 'formdata' | 'urlencoded' | 'text' | 'binary' | 'none';
-    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
-  };
-
-  response?: {
-    status: number;
-    statusText?: string;
-    headers: Record<string, string>;
-    body?: string;
-    bodyOmitted?: 'too-large' | 'stream' | 'binary' | 'unreadable';
-    size?: number;
-  };
-
-  timing: { startedAt: number; completedAt?: number; duration?: number };
-  error?: { message: string; name?: string; stack?: string };
-
-  envelopeOk?: boolean;                 // false when a 2xx carried an error code
-  envelopeCode?: number;
-}
-```
-
-### Storage
-
-```ts
-interface TraceStorage {
-  add(trace: ApiTrace): void;
-  update(id: string, patch: Partial<ApiTrace>): ApiTrace | undefined;
-  get(id: string): ApiTrace | undefined;
-  getAll(): ApiTrace[];
-  remove(id: string): void;
-  clear(): void;
-}
-```
-
-The default is `MemoryTraceStorage`, a capped ring — an unbounded store in a
-long-lived tab is a memory leak. Nothing is persisted; supply your own storage
-if you want it to be.
-
-## React
-
-```tsx
-import { useApiTracer, useApiTraces } from 'api-tracer-kit/react';
-
-function App() {
-  useApiTracer();                         // init once, StrictMode-safe
-  const { traces, clear } = useApiTraces();
-  return <span>{traces.length} calls</span>;
-}
-```
-
-Updates are batched on an animation frame, so a burst of calls on page load
-re-renders once rather than once per request.
+Each is bundled separately with `sideEffects: false`, so importing the tracer
+never pulls in React, and an unused import is dropped entirely.
 
-## The in-app panel
+## It will not break your API calls
 
-```tsx
-import { ApiTracerPanel } from 'api-tracer-kit/ui';
+Removing the tracer changes nothing. Responses are read through
+`Response.clone()` after the original is handed back; streaming responses are
+never buffered; request-body streams are never consumed; errors are rethrown
+exactly as they arrived; nothing is retried and no request is made twice; XHR is
+observed with `addEventListener` rather than by taking `onload`; and `destroy()`
+restores every patched global.
 
-<ApiTracerPanel enabled={process.env.NODE_ENV !== 'production'} />;
-```
-
-A floating panel with the call list, per-call detail (request and response
-headers, params, bodies, status, duration, errors), search, method and status
-filters, sorting, expand/collapse and clear. Styles are inline, so there is no
-stylesheet to import and nothing to collide with your app's CSS.
-
-## Axios
-
-axios calls are traced two ways.
-
-In a browser axios rides on `XMLHttpRequest`, so `apiTracer.init()` alone
-already sees them. For richer data — the params object as axios received it, the
-config, and Node's `http` adapter, which no global patch can reach — attach it
-explicitly:
-
-```ts
-import axios from 'axios';
-import { apiTracer } from 'api-tracer-kit';
-
-apiTracer.init();
-apiTracer.useAxios(axios);
-```
-
-One call covers the default export **and every instance `axios.create()` makes
-afterwards**. That matters in codebases that send some requests through per-page
-instances and the rest through the default object — patching only the default
-misses half the traffic.
-
-A call seen by both adapters is recorded once, not twice.
-
-Why an explicit call at all: an axios instance is a plain object with no global
-to patch, so there is no way for the tracer to reach one it was never handed.
-This is the smallest integration that works, and it is the only one in the
-package.
-
-## SSR
-
-Importing the package evaluates no browser global and installs nothing. `init()`
-checks for each runtime capability before patching it, so on a server it simply
-finds nothing to patch and returns.
-
-```ts
-// safe anywhere
-import { apiTracer } from 'api-tracer-kit';
-
-if (typeof window !== 'undefined') apiTracer.init();
-```
-
-The guard is not required — `init()` is already a no-op without a runtime — but
-it makes the intent obvious in a Next.js file that runs on both sides.
-
-## Not breaking your API calls
-
-The tracer is built so that removing it changes nothing. Specifically:
-
-- responses are read through `Response.clone()`, after the original has been
-  handed back, so your `.json()` still works
-- streaming responses (`text/event-stream`) are never buffered
-- binary and non-textual responses are described, not read
-- request bodies that are `ReadableStream`s are never consumed
-- bodies over `maxBodyBytes` are recorded as omitted rather than copied
-- errors are rethrown exactly as they arrived; aborts stay `AbortError`
-- `AbortSignal`, redirects, credentials and headers are passed through untouched
-- nothing is retried, and no request is ever made twice
-- XHR is observed with `addEventListener`, never by taking `onload` or
-  `onreadystatechange`
-- a subscriber that throws is caught, so a bad listener cannot break a request
-- `destroy()` restores every patched global and every axios adapter
-
-## The console
-
-```bash
-npx api-tracer scan      # read the source, write the endpoint catalog
-npx api-tracer serve     # the UI, at http://127.0.0.1:4400
-npx api-tracer start     # both
-npx api-tracer report    # the insight report, Markdown or JSON
-npx api-tracer init      # write a config file, if the guesses need help
-```
-
-### How it finds your endpoints
-
-It runs every scanner preset over your codebase and keeps whichever actually
-reads it:
-
-| preset | what it reads |
-| --- | --- |
-| `service-object` | `const request = { subUrl: '/users' }; return get(request)` |
-| `axios-direct` | `axios.get('/users')`, `api.post(\`/users/${id}\`, body)` |
-| `fetch-direct` | `fetch('/api/users', { method: 'POST' })` |
-
-Base URLs and the auth header name are read from your source too, so your
-environments stay in sync with the app rather than being copied into a config.
-
-If none of the presets fit, supply your own in `api-tracer.config.mjs`:
-
-```js
-export default {
-  parse: (src, config) => [
-    { name, method, subUrl, usesParams, usesData, chunk, index },
-  ],
-};
-```
-
-### Config file
-
-Optional. `api-tracer init` writes one filled in with what the scan worked out.
-Every field has a default:
-
-```js
-export default {
-  name: 'My API',
-  preset: 'service-object',
-  sources: ['src'],
-  baseUrls: { dev: 'https://dev.example.com/api' },
-  auth: { header: 'Authorization' },
-  envelope: { codeFields: ['status', 'code'], okField: 'success', failFrom: 400 },
-  login: { steps: [/* an optional multi-step sign-in chain */] },
-};
-```
-
-### Environment variables
-
-| | |
-| --- | --- |
-| `API_TRACER_DATA` | where captures are kept (default `<project>/.api-tracer`) |
-| `PORT` / `HOST` | default `4400` / `127.0.0.1` |
-| `BASE_PATH` | serve under a path, e.g. `/api-console`, behind a proxy |
-| `ALLOWED_ORIGINS` | comma-separated origins allowed to post recordings |
-| `CONSOLE_USER` / `CONSOLE_PASS` | basic auth on everything except `/api/record` |
-| `LOCK_RECORDING` / `LOCK_ENV` | stop one person's click changing a shared console |
-
-## Security
-
-The tracer sees whatever your API sees, which on some products means
-credentials and personal data. So:
-
-- `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` and the usual token
-  header names are redacted by default, and the list is configurable
-- any field whose **name** looks like a credential (`token`, `password`,
-  `secret`, `api_key`, `otp`, …) is replaced with `<redacted>`, keeping the
-  surrounding shape so the sample stays useful
-- redaction happens before a trace is stored, so a redacted value is never held
-  in memory either
-- the console redacts again before writing anything to disk
-- HAR, cURL and Postman exports carry `<paste your token>` in place of a real
-  token, so an export is safe to attach to a ticket
-
-The console's data directory holds captured request and response bodies from a
-real environment. Treat it as sensitive: keep it out of version control (it is
-`.api-tracer/`, add it to `.gitignore`) and keep a deployed console behind VPN
-or SSO.
+The full list is in [Tracer API](./docs/tracer.md#what-the-tracer-will-not-do-to-your-app).
 
 ## Limitations
 
@@ -399,52 +161,23 @@ Worth knowing before you rely on it.
 
 - **An axios instance must be handed over.** There is no global to patch. In a
   browser the XHR adapter catches axios anyway; in Node it cannot.
-- **A request body that is a stream is never read**, because reading it would
-  empty it. It is recorded as `omitted: 'stream'`.
+- **Request bodies that are streams are never read**, because reading one would
+  empty it.
 - **Files in a `FormData` are described, not captured**, so a captured upload
   cannot be replayed with its file.
 - **Response bodies over `maxBodyBytes` are omitted**, not truncated — a partial
   JSON body is more misleading than none.
 - **`Response.clone()` buffers.** For a large non-streaming response the clone
   holds a second copy until it is read. The size cap keeps this bounded.
-- **The scanner is regex-based.** It reads the three shapes above well and says
+- **The scanner is regex-based.** It reads three common shapes well and says
   what it could not read; it does not understand a URL assembled from three
-  variables. Live recording covers what the scan misses — an unexplained call
-  becomes an endpoint of its own.
+  variables. Live recording covers the rest.
 - **The "unused endpoint" count is a substring count**, so `import * as services`
-  or a re-export would hide a real usage. Confirm with a grep before deleting.
-- **The console is single-user by design**: one token, one selected environment,
-  one set of results.
-
-## Architecture
-
-```
-api-tracer-kit
-├── src/
-│   ├── core/         tracer, data model, redaction, bodies, URLs, envelopes, runtime detection
-│   ├── adapters/     fetch, xhr, axios, and the suppression that stops double-counting
-│   ├── storage/      the TraceStorage interface and the capped in-memory default
-│   ├── transport/    posting finished traces to a console
-│   ├── ui/           the React panel (optional entry point)
-│   ├── index.ts      the public API
-│   ├── axios.ts      api-tracer-kit/axios
-│   └── react.ts      api-tracer-kit/react
-└── cli/
-    ├── bin/          the api-tracer command
-    ├── presets.mjs   how to find endpoints in a codebase
-    ├── config.mjs    defaults, and guessing what was not configured
-    ├── scan.mjs      source -> endpoint catalog
-    ├── server.mjs    the console: forwards calls, replays, exports, records
-    ├── import.mjs    HAR and cURL, matched back to the catalog
-    ├── shape.mjs     response shapes and drift diffing
-    ├── report.mjs    the insight report model and its Markdown export
-    └── web/          the dashboard (no framework, no build step)
-```
-
-The core is framework-free and knows nothing about any particular application.
-The console knows nothing about it either: the catalog supplies the endpoints,
-base URLs, auth header and envelope convention, and the config file supplies the
-sign-in flow if there is one worth automating.
+  would hide a real usage. Confirm with a grep before deleting.
+- **The console is single-user by design**: one token, one environment, one set
+  of results.
+- **Redaction is name-based.** A field called `notes` containing personal data is
+  not a credential and is not touched. See [Security](./docs/security.md).
 
 ## Development
 
@@ -461,6 +194,8 @@ The example project doubles as an end-to-end check:
 cd examples/basic && npm install && npm start
 ```
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Licence
 
 MIT

package/cli/bin/api-tracer.mjs

@@ -13,8 +13,19 @@
  * rather than a blank page.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { loadConfig, guessConfig, defaults, CONFIG_NAMES } from '../config.mjs';
+import { join, resolve, relative, dirname } from 'node:path';
+import { loadConfig, guessConfig, defaults, CONFIG_NAMES, collectFiles } from '../config.mjs';
+import {
+  FRAMEWORKS,
+  addImport,
+  detectFramework,
+  ensureGitignore,
+  findEntry,
+  findExistingInits,
+  recorderSource,
+  usesAxios,
+  usesTypeScript,
+} from '../setup.mjs';
 import { scanToFile, scanProject } from '../scan.mjs';
 import { buildReport, toMarkdown } from '../report.mjs';
 
@@ -148,6 +159,76 @@ async function init() {
   say('Nothing else is needed: `api-tracer start` works from here.');
 }
 
+/* ------------------------------------------------------------------ setup */
+
+async function setup() {
+  const framework = String(flag('framework', detectFramework(ROOT)));
+  if (!FRAMEWORKS[framework]) {
+    say(`unknown framework "${framework}"; expected one of: ${Object.keys(FRAMEWORKS).join(', ')}`);
+    process.exit(1);
+  }
+
+  const axios = flag('axios') !== undefined ? flag('axios') !== 'false' : usesAxios(ROOT);
+  const ts = usesTypeScript(ROOT);
+  const out = String(flag('out', `src/apiTracer.${ts ? 'ts' : 'js'}`));
+  const entry = flag('entry') ? String(flag('entry')) : findEntry(ROOT, framework);
+
+  say(`project    ${ROOT}`);
+  say(`framework  ${FRAMEWORKS[framework].label}${flag('framework') ? ' (given)' : ' (detected)'}`);
+  say(`axios      ${axios ? 'yes, will be attached' : 'no'}`);
+
+  /*
+   * A second init() elsewhere would keep its own configuration and silently
+   * ignore this one's, so say so before writing rather than after.
+   */
+  const existing = findExistingInits(ROOT, collectFiles(ROOT, defaults).map((f) => relative(ROOT, f)));
+  const notOurs = existing.filter((f) => f !== out);
+  if (notOurs.length) {
+    say('');
+    say(`Something already calls apiTracer.init():`);
+    for (const f of notOurs) say(`  ${f}`);
+    say('The tracer must be configured in one place -- remove those calls, or this');
+    say('file will be the one whose options are ignored.');
+  }
+
+  const target = join(ROOT, out);
+  if (existsSync(target) && !flag('force')) {
+    say('');
+    say(`${out} already exists; pass --force to overwrite it`);
+  } else {
+    writeFileSync(target, recorderSource({ framework, axios, envelope: flag('envelope') !== 'false' }));
+    say('');
+    say(`wrote      ${out}`);
+  }
+
+  if (!entry) {
+    say('');
+    say(`Could not find an entry file. Add this line to yours yourself:`);
+    say(`  import "./${out.replace(/^src\//, '').replace(/\.[jt]sx?$/, '')}";`);
+  } else {
+    const entryPath = join(ROOT, entry);
+    const source = readFileSync(entryPath, 'utf8');
+    // a relative specifier from the entry file to the module we just wrote
+    let spec = relative(dirname(entryPath), target).replace(/\.[jt]sx?$/, '');
+    if (!spec.startsWith('.')) spec = `./${spec}`;
+
+    const { source: next, added } = addImport(source, spec);
+    if (added) {
+      writeFileSync(entryPath, next);
+      say(`imported   ${entry}  ->  import "${spec}"`);
+    } else {
+      say(`already imported from ${entry}`);
+    }
+  }
+
+  if (ensureGitignore(ROOT)) say('gitignored .api-tracer/');
+
+  say('');
+  say('Next:');
+  say('  npx api-tracer start      # scan your source and open the console');
+  say('  <start your app>          # its calls stream in as you click');
+}
+
 /* ----------------------------------------------------------------- report */
 
 async function report() {
@@ -223,6 +304,7 @@ const HELP = `api-tracer
   api-tracer serve           run the console (default http://127.0.0.1:4400)
   api-tracer start           scan, then serve
   api-tracer report          build the insight report
+  api-tracer setup           wire the tracer into this app, in one command
   api-tracer init            write a config file from what the scan guessed
 
 Options
@@ -235,11 +317,20 @@ Options
   --out <file>       write the report to a file    (default: stdout)
   --env <name>       which base URL the report describes
 
+setup options
+  --framework <name> cra | vite | next | node        (default: detected)
+  --entry <file>     the entry file to import from   (default: detected)
+  --out <file>       where to write the module       (default: src/apiTracer.js)
+  --axios false      do not attach axios
+  --envelope false   the API reports failure in the status line, not the body
+  --force            overwrite an existing file
+
 No configuration file is required.
 `;
 
 const commands = {
   scan,
+  setup,
   init,
   report,
   serve,