@t0.labs/daxta 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,128 +1,185 @@
1
1
  # DAxTA
2
2
 
3
- **Document API × Test API** — NestJS integration tests already hit your real endpoints. DAxTA records that traffic and turns it into living OpenAPI docs on your app port (`/docs`), with DTO required/optional fields and a Try-it workbench.
3
+ **Tested behavior. Trusted API docs.**
4
4
 
5
- Swagger asks you to decorate controllers. DAxTA learns from what your tests actually call.
6
-
7
- DAxTA docs — recorded request, response, Try-it
8
-
9
- ## What you get
10
-
11
-
12
- | After tests | On the app |
13
- | ------------------------------------- | -------------------------------------------------------- |
14
- | OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
15
- | POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
16
- | DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
5
+ DAxTA generates and publishes API documentation from API behavior observed during automated tests.
17
6
 
7
+ ```ts
8
+ import { apiDocs, generateApiDocs } from '@t0.labs/daxta';
18
9
 
19
- Jest finishes — Docs ready on /docs
10
+ await generateApiDocs();
11
+ apiDocs(app);
12
+ ```
20
13
 
21
- ## How it works
14
+ Swagger asks you to decorate controllers. DAxTA records what your tests actually call.
22
15
 
23
16
  ```text
24
- your Jest suite
25
- │ supertest / superagent hits
26
- ▼
27
- DAxTA records hits to disk
28
- │ (no OpenAPI rebuild mid-run)
29
- ▼
30
- onRunComplete → one full build
31
- │
32
- ▼
33
- Docs ready → http://localhost:3000/docs
17
+ Tests
18
+ ↓
19
+ Observed API Behavior
20
+ ↓
21
+ DAxTA
22
+ ↓
23
+ Verified API Docs
24
+ ↓
25
+ Hosted Documentation
34
26
  ```
35
27
 
36
- 1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter, and `globalSetup` when you don’t already have one). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
37
- 2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is rebuilt once when Jest finishes, from **this run’s hits only** (previous worker shards are cleared so examples do not stack).
38
- 3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
39
-
28
+ The documentation shows what tests really exercise — not what the code claims to do.
40
29
 
30
+ ## Install
41
31
 
42
- ## CLI ile kurulum
43
-
44
- Tek komut — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts` ve sidebar tercihler:
32
+ One command — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts`, and sidebar preferences:
45
33
 
46
34
  ```bash
47
35
  pnpm dlx @t0.labs/daxta install
48
- # veya
36
+ # or
49
37
  npx @t0.labs/daxta install
50
38
  ```
51
39
 
52
- Kurulum sırasında sorulur: Nest entry, test script, docs folder order (`role-resource` / `resource-role`), `{id}` fold, example label stili.
53
- `DAXTA_DOCS=true` otomatik `.env`’e yazılır (yoksa oluşturulur).
40
+ Install asks for the Nest entry, test script, sidebar folder order (`role-resource` / `resource-role`), `{id}` fold, and example label style.
41
+ `DAXTA_DOCS=true` is written to `.env` (created if missing).
54
42
 
55
- Sonra:
43
+ Then:
56
44
 
57
45
  ```bash
58
- pnpm run test:integration # test bitince Docs ready
59
- pnpm start:dev # app portunda /docs (DAXTA_DOCS already set)
46
+ pnpm run test:integration # generates API docs when Jest finishes
47
+ pnpm start:dev # API docs on the app port at /api-docs
60
48
  ```
61
49
 
62
50
  ```ts
63
51
  import { apiDocs } from '@t0.labs/daxta';
64
52
 
65
- apiDocs(app); // DAXTA_DOCS zorunlu (true | false)
53
+ apiDocs(app); // DAXTA_DOCS is required (true | false)
66
54
  ```
67
55
 
68
56
  Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>` · `--fast`
69
57
 
70
- ## CLI ile kaldırma
58
+ ## Uninstall
71
59
 
72
60
  ```bash
73
61
  pnpm dlx @t0.labs/daxta uninstall
74
- # veya
62
+ # or
75
63
  npx @t0.labs/daxta uninstall
76
64
  ```
77
65
 
78
- Otomatik temizler:
66
+ Removes:
79
67
 
80
68
  - `apiDocs` + `@t0.labs/daxta` import (`main.ts`)
81
- - Jest `setup` + `jest-reporter` (+ `globalSetup` when missing)
82
- - `daxta.config.*` ve `daxta/` output
83
- - `.gitignore` / `.env` içindeki DAxTA satırları
84
- - `@t0.labs/daxta` paketi
85
-
86
- Flags: `--yes` · `--dry-run` · `--keep-dep` (paketi bırakıp sadece wiring’i sök) · `--fast`
69
+ - Jest `setup` + `jest-reporter` (+ `globalSetup` when DAxTA added it)
70
+ - `daxta.config.*` and `.daxta/` output
71
+ - DAxTA lines in `.gitignore` / `.env`
72
+ - `@t0.labs/daxta` package
87
73
 
74
+ Flags: `--yes` · `--dry-run` · `--keep-dep` (leave the package, unwind wiring only) · `--fast`
88
75
 
76
+ ## How it works
89
77
 
90
- ## Docs UI
91
-
92
- Recorded scenarios (success, validation, missing auth) stay tied to the request that produced them — headers included. Empty auth on a 401 scenario stays empty; env tokens only override keys that were actually recorded.
93
-
94
- Scenario picker — success, validation, auth
78
+ ```text
79
+ your Jest suite
80
+ │ supertest / superagent hits
81
+ ▼
82
+ DAxTA records hits to disk
83
+ │ (no OpenAPI rebuild mid-run)
84
+ ▼
85
+ onRunComplete → generate API docs
86
+ │
87
+ ▼
88
+ API docs ready → http://localhost:3000/api-docs
89
+ ```
95
90
 
96
- Field metadata comes from class-validator / class-transformer DTOs plus observed traffic:
91
+ 1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter, and `globalSetup` when you don’t already have one). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
92
+ 2. **During the run** only traffic is recorded. The API spec and HTML are generated once when Jest finishes, from **this run’s hits only**.
93
+ 3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
97
94
 
98
- Required vs optional DTO fields
95
+ | After tests | On the app |
96
+ | --- | --- |
97
+ | OpenAPI + HTML from real hits | `/api-docs` on the same port as Nest |
98
+ | POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
99
+ | DTO field map (required vs optional) | `DAXTA_DOCS=true\|false` gate |
99
100
 
100
101
  ## `DAXTA_DOCS` (required)
101
102
 
102
103
  Same idea as Nest Swagger’s “don’t call `setup` in prod”:
103
104
 
104
105
  ```bash
105
- DAXTA_DOCS=true # mount /docs (install writes this)
106
+ DAXTA_DOCS=true # mount /api-docs (install writes this)
106
107
  DAXTA_DOCS=false # no-op (must still be set)
107
108
  # unset / empty → throws — make the choice explicit
108
109
  ```
109
110
 
110
- `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting `/docs`.
111
+ `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting API docs.
111
112
 
112
- ## Commands
113
+ ## Config
113
114
 
114
- ```bash
115
- daxta install # CLI kurulum (+ sidebar prompts)
116
- daxta uninstall # CLI kaldırma (komple)
117
- daxta migrate # paket bump sonrası upgrade (+ sidebar prompts)
118
- daxta build # OpenAPI/HTML rebuild
119
- daxta serve # standalone viewer (opsiyonel)
120
- daxta tree # sidebar / example tercihlerini yeniden sor
121
- daxta fields … # field map export
122
- daxta call … # CLI Try-it
115
+ `daxta.config.ts`:
116
+
117
+ ```ts
118
+ import { defineConfig } from '@t0.labs/daxta';
119
+
120
+ export default defineConfig({
121
+ specInfo: () => ({
122
+ title: 'Merchant API',
123
+ version: '1.0.0',
124
+ }),
125
+ baseUrl: 'http://localhost:3000',
126
+ docsPath: '/api-docs',
127
+ outDir: '.daxta/out',
128
+ viewerStoreFile: '.daxta/viewer-store.json',
129
+ envPresets: {
130
+ local: { baseUrl: 'http://localhost:3000' },
131
+ staging: { baseUrl: 'https://api.staging.example.com' },
132
+ production: { baseUrl: 'https://api.example.com' },
133
+ },
134
+ });
123
135
  ```
124
136
 
125
- ### Docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
137
+ Generated artifacts live under `.daxta/`:
138
+
139
+ ```text
140
+ .daxta/
141
+ ├── out/
142
+ │ ├── openapi.json
143
+ │ └── openapi.html
144
+ └── viewer-store.json
145
+ ```
146
+
147
+ DAxTA is the tool. The artifact is **API docs** (`openapi.json` + the HTML viewer). The hosted page title is your API title; the footer is a small **Generated by DAxTA**.
148
+
149
+ ## CLI
150
+
151
+ ```text
152
+ daxta generate
153
+ Generate API documentation from test execution.
154
+
155
+ daxta serve
156
+ Serve API documentation locally.
157
+
158
+ daxta install
159
+ Install DAxTA in this project.
160
+
161
+ daxta uninstall
162
+ Remove DAxTA from this project.
163
+
164
+ daxta migrate
165
+ Upgrade project wiring after a package bump.
166
+
167
+ daxta tree
168
+ Configure API docs sidebar layout.
169
+
170
+ daxta titles
171
+ Align test titles with API docs examples.
172
+
173
+ daxta fields
174
+ Export API field map.
175
+
176
+ daxta call
177
+ Send a Try-it request from the CLI.
178
+ ```
179
+
180
+ `daxta build` is an alias of `daxta generate`.
181
+
182
+ ### API docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
126
183
 
127
184
  Company-wide choices (saved in `daxta.config.ts`):
128
185
 
@@ -137,26 +194,16 @@ OpenAPI path keys in the generated spec still follow the sidebar tree. Real URLs
137
194
 
138
195
  ### Try-it env / headers (persisted)
139
196
 
140
- Env **presets** (multi-base) + header groups are editable in the docs UI.
141
-
142
- Define company defaults in `daxta.config.ts`:
143
-
144
- ```ts
145
- envPresets: {
146
- local: { baseUrl: 'http://localhost:3000' },
147
- staging: { baseUrl: 'https://api.staging.example.com' },
148
- production: { baseUrl: 'https://api.example.com', variables: { apiKey: '' } },
149
- },
150
- ```
197
+ Env **presets** (multi-base) + header groups are editable in the API docs UI.
151
198
 
152
- - Docs picker shows each preset with its own `baseUrl` + variables + header groups
153
- - Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
154
- - First `daxta build` seeds `daxta/viewer-store.json` from `envPresets` if the file is missing
199
+ - The picker shows each preset with its own `baseUrl` + variables + header groups
200
+ - Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
201
+ - First `daxta generate` seeds `.daxta/viewer-store.json` from `envPresets` if the file is missing
155
202
  - Runtime edits still persist via `GET/PUT {docsPath}/env.json`
156
203
 
157
204
  Sidebar: expand the chevron on an endpoint to list recorded examples underneath; click one to open it in the workbench.
158
205
 
159
- Export: download is **Postman Collection** (nested folders like the sidebar) plus, by default, the active Try-it **environment + header group** as a `.postman_environment.json`. Pick All / None / Success only for which examples to include. Import the collection, then the environment, and select that env in Postman.
206
+ Export: download is **Postman Collection** (nested folders like the sidebar) plus, by default, the active Try-it **environment + header group** as a `.postman_environment.json`. Pick All / None / Success only for which examples to include.
160
207
 
161
208
  Example label (`status-title-case`):
162
209
 
@@ -164,9 +211,9 @@ Example label (`status-title-case`):
164
211
  200 — Admin Find One Basket By Id API — returns basket with items when found by id
165
212
  ```
166
213
 
167
- Then `daxta build` to refresh `/docs` and export.
214
+ Then `daxta generate` to refresh `/api-docs` and export.
168
215
 
169
- ## Test titles (docs / Postman names)
216
+ ## Test titles (API docs / Postman names)
170
217
 
171
218
  Readable `TEST_TITLE` (path stays after the em dash so DAxTA can still bind the route):
172
219
 
@@ -192,14 +239,14 @@ Suggested titles (method + path, never `:id` as a name):
192
239
 
193
240
  Old `{path} [METHOD] (integration)` still parses. `daxta titles --yes` rewrites to the new form.
194
241
 
195
- `it()` keeps a unique sentence; `/docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
242
+ `it()` keeps a unique sentence; `/api-docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
196
243
 
197
244
  | Layer | Rule | Example |
198
245
  | --- | --- | --- |
199
246
  | Positive `it()` | `{creates\|returns\|updates\|…} … when {diff}` | `creates mock tbs TRNC record when cyprus payload shape` |
200
247
  | Error `it()` | `returns error when {diff}` | `returns error when tax id already exists in mock TBS` |
201
248
  | Invalid fields | leave interpolated | `` `${property} - should not be ${description}` `` |
202
- | Docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
249
+ | API docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
203
250
 
204
251
  `--yes` / `a` rewrite **this case’s own text**, not one shared template. Interpolated `it(\`${…}\`)` is never rewritten.
205
252
 
@@ -209,16 +256,17 @@ daxta titles --yes # rewrite every hit with the recommended name
209
256
  daxta titles --check # report only
210
257
  ```
211
258
 
212
-
213
-
214
-
215
259
  ## API
216
260
 
217
261
  ```ts
218
- import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
262
+ import { apiDocs, apiDocsHandler, generateApiDocs, getApiDocUrl, getApiDocs, serveApiDocs } from '@t0.labs/daxta';
219
263
 
264
+ await generateApiDocs(); // OpenAPI spec + HTML from recorded test hits
220
265
  apiDocs(app); // preferred — same origin as the API
221
266
  app.use(apiDocsHandler()); // Express-style mount
222
267
  serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
268
+ getApiDocUrl(); // e.g. http://localhost:3000/api-docs
269
+ getApiDocs(); // { url, specPath, htmlPath }
223
270
  ```
224
271
 
272
+ Capture during tests is an implementation detail. The public surface is generate, then mount or serve.
package/assets/empty.html CHANGED
@@ -3,7 +3,7 @@
3
3
  <head>
4
4
  <meta charset="utf-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
- <title>DAxTA</title>
6
+ <title>API Documentation</title>
7
7
  <link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
8
8
  <link rel="preconnect" href="https://fonts.googleapis.com" />
9
9
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -134,16 +134,16 @@
134
134
  </head>
135
135
  <body>
136
136
  <header class="topnav">
137
- <span class="nav-meta">/docs</span>
137
+ <span class="nav-meta">/api-docs</span>
138
138
  </header>
139
139
  <main class="stage">
140
140
  <div class="panel">
141
141
  <p class="kicker">Waiting</p>
142
- <h1>No documentation yet</h1>
142
+ <h1>No API documentation yet</h1>
143
143
  <p>This page publishes when API traffic has been recorded. Run your integration tests, then refresh.</p>
144
144
  <ol class="steps">
145
145
  <li><span class="n">1</span><span>Run the integration suite that hits your API.</span></li>
146
- <li><span class="n">2</span><span>DAxTA writes the docs from those requests and responses.</span></li>
146
+ <li><span class="n">2</span><span>DAxTA writes API docs from those requests and responses.</span></li>
147
147
  <li><span class="n">3</span><span>Reload this page to open the workbench.</span></li>
148
148
  </ol>
149
149
  <pre class="cmd">pnpm run test:integration</pre>
@@ -3,7 +3,7 @@
3
3
  <head>
4
4
  <meta charset="utf-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
- <title>DAxTA</title>
6
+ <title>API Documentation</title>
7
7
  <link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
8
8
  <link rel="apple-touch-icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
9
9
  <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -1305,7 +1305,7 @@
1305
1305
  "x-viewer": {
1306
1306
  "workspace": "token-x",
1307
1307
  "baseUrl": "http://localhost:3000",
1308
- "docsPath": "/docs",
1308
+ "docsPath": "/api-docs",
1309
1309
  "envPresets": {
1310
1310
  "local": { "baseUrl": "http://localhost:3000" }
1311
1311
  }
@@ -1504,7 +1504,7 @@
1504
1504
  const viewer = spec["x-viewer"] || {};
1505
1505
  const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
1506
1506
  const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
1507
- const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
1507
+ const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
1508
1508
 
1509
1509
  const inferBaseUrlFromLocation = () => {
1510
1510
  if (typeof location === "undefined") return null;
@@ -1524,9 +1524,9 @@
1524
1524
  };
1525
1525
 
1526
1526
  const locationBaseUrl = inferBaseUrlFromLocation();
1527
- // Prefer the URL that is serving the viewer (strip /docs), else fall back to spec.
1527
+ // Prefer the URL that is serving the viewer (strip the docs path), else fall back to spec.
1528
1528
  const defaultBaseUrl = locationBaseUrl || defaultBaseUrlFromSpec;
1529
- const title = (spec.info && spec.info.title) || "API Docs";
1529
+ const title = (spec.info && spec.info.title) || "API Documentation";
1530
1530
  const STORE_KEY = "openapi-docs-env:" + (workspace || "default");
1531
1531
  const SIDEBAR_STORE_KEY = "openapi-docs-sidebar:" + (workspace || "default");
1532
1532
  const SIDEBAR_MIN = 200;
@@ -2258,7 +2258,7 @@
2258
2258
  };
2259
2259
  };
2260
2260
 
2261
- document.title = title ? "DAxTA · " + title : "DAxTA";
2261
+ document.title = title || "API Documentation";
2262
2262
  const brandEl = document.getElementById("brand");
2263
2263
  if (brandEl) brandEl.textContent = title;
2264
2264
  const specVersion = (spec.info && spec.info.version) || "";
@@ -2512,7 +2512,7 @@
2512
2512
  }
2513
2513
  return {
2514
2514
  id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
2515
- name: (workspace || title || "DAxTA") + " · " + store.activeEnv,
2515
+ name: (workspace || title || "API") + " · " + store.activeEnv,
2516
2516
  values,
2517
2517
  _postman_variable_scope: "environment",
2518
2518
  _postman_exported_at: new Date().toISOString(),
@@ -2685,8 +2685,8 @@
2685
2685
  return {
2686
2686
  info: {
2687
2687
  _postman_id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
2688
- name: (openapi.info && openapi.info.title) || workspace || title || "DAxTA",
2689
- description: (openapi.info && openapi.info.description) || "Exported from DAxTA with named examples",
2688
+ name: (openapi.info && openapi.info.title) || workspace || title || "API",
2689
+ description: (openapi.info && openapi.info.description) || "Exported from API docs with named examples",
2690
2690
  schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
2691
2691
  },
2692
2692
  item,
@@ -3582,7 +3582,7 @@
3582
3582
  body: undefined,
3583
3583
  error:
3584
3584
  message +
3585
- "\n\nTip: open docs at the same app port: http://localhost:3000/docs",
3585
+ "\n\nTip: open API docs at the same app port: http://localhost:3000" + docsPathSuffix,
3586
3586
  };
3587
3587
  }
3588
3588
  renderMain();
@@ -3,7 +3,7 @@
3
3
  <head>
4
4
  <meta charset="utf-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
- <title>DAxTA</title>
6
+ <title>API Documentation</title>
7
7
  <link rel="icon" href="__FAVICON_DATA_URI__" />
8
8
  <link rel="apple-touch-icon" href="__FAVICON_DATA_URI__" />
9
9
  <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -1302,7 +1302,7 @@
1302
1302
  const viewer = spec["x-viewer"] || {};
1303
1303
  const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
1304
1304
  const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
1305
- const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
1305
+ const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
1306
1306
 
1307
1307
  const inferBaseUrlFromLocation = () => {
1308
1308
  if (typeof location === "undefined") return null;
@@ -1322,9 +1322,9 @@
1322
1322
  };
1323
1323
 
1324
1324
  const locationBaseUrl = inferBaseUrlFromLocation();
1325
- // Prefer the URL that is serving the viewer (strip /docs), else fall back to spec.
1325
+ // Prefer the URL that is serving the viewer (strip the docs path), else fall back to spec.
1326
1326
  const defaultBaseUrl = locationBaseUrl || defaultBaseUrlFromSpec;
1327
- const title = (spec.info && spec.info.title) || "API Docs";
1327
+ const title = (spec.info && spec.info.title) || "API Documentation";
1328
1328
  const STORE_KEY = "openapi-docs-env:" + (workspace || "default");
1329
1329
  const SIDEBAR_STORE_KEY = "openapi-docs-sidebar:" + (workspace || "default");
1330
1330
  const SIDEBAR_MIN = 200;
@@ -2056,7 +2056,7 @@
2056
2056
  };
2057
2057
  };
2058
2058
 
2059
- document.title = title ? "DAxTA · " + title : "DAxTA";
2059
+ document.title = title || "API Documentation";
2060
2060
  const brandEl = document.getElementById("brand");
2061
2061
  if (brandEl) brandEl.textContent = title;
2062
2062
  const specVersion = (spec.info && spec.info.version) || "";
@@ -2310,7 +2310,7 @@
2310
2310
  }
2311
2311
  return {
2312
2312
  id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
2313
- name: (workspace || title || "DAxTA") + " · " + store.activeEnv,
2313
+ name: (workspace || title || "API") + " · " + store.activeEnv,
2314
2314
  values,
2315
2315
  _postman_variable_scope: "environment",
2316
2316
  _postman_exported_at: new Date().toISOString(),
@@ -2483,8 +2483,8 @@
2483
2483
  return {
2484
2484
  info: {
2485
2485
  _postman_id: typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
2486
- name: (openapi.info && openapi.info.title) || workspace || title || "DAxTA",
2487
- description: (openapi.info && openapi.info.description) || "Exported from DAxTA with named examples",
2486
+ name: (openapi.info && openapi.info.title) || workspace || title || "API",
2487
+ description: (openapi.info && openapi.info.description) || "Exported from API docs with named examples",
2488
2488
  schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
2489
2489
  },
2490
2490
  item,
@@ -3380,7 +3380,7 @@
3380
3380
  body: undefined,
3381
3381
  error:
3382
3382
  message +
3383
- "\n\nTip: open docs at the same app port: http://localhost:3000/docs",
3383
+ "\n\nTip: open API docs at the same app port: http://localhost:3000" + docsPathSuffix,
3384
3384
  };
3385
3385
  }
3386
3386
  renderMain();
@@ -24,5 +24,7 @@ export declare function buildDaxtaSpec(options?: {
24
24
  requireHits?: boolean;
25
25
  html?: boolean;
26
26
  }): BuildResult;
27
- /** @deprecated Use `buildDaxtaSpec` */
27
+ /** Generate API documentation (OpenAPI spec + HTML viewer) from recorded test execution. */
28
+ export declare const generateApiDocs: typeof buildDaxtaSpec;
29
+ /** @deprecated Use `generateApiDocs` */
28
30
  export declare const buildOpenApi: typeof buildDaxtaSpec;
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.buildOpenApi = void 0;
36
+ exports.buildOpenApi = exports.generateApiDocs = void 0;
37
37
  exports.loadHits = loadHits;
38
38
  exports.buildDaxtaSpec = buildDaxtaSpec;
39
39
  const fs_1 = require("fs");
@@ -75,7 +75,7 @@ function readPackageMeta() {
75
75
  };
76
76
  }
77
77
  catch {
78
- return { title: 'API', version: '0.0.0', description: 'Generated from integration test traffic.' };
78
+ return { title: 'API', version: '0.0.0', description: 'Generated from observed test execution.' };
79
79
  }
80
80
  }
81
81
  function specInfo() {
@@ -807,7 +807,7 @@ function buildDaxtaSpec(options = {}) {
807
807
  };
808
808
  if (!options.silent) {
809
809
  if (!changed) {
810
- console.log(`DAxTA unchanged (${hits.length} hits, ${operations} operations — ${unchanged} kept as-is)`);
810
+ console.log(`API spec unchanged (${hits.length} hits, ${operations} operations — ${unchanged} kept as-is)`);
811
811
  }
812
812
  else {
813
813
  console.log(`Wrote ${(0, paths_1.getSpecJsonPath)()} from ${hits.length} hits (${operations} operations — ${updated} updated, ${unchanged} unchanged)`);
@@ -816,5 +816,7 @@ function buildDaxtaSpec(options = {}) {
816
816
  }
817
817
  return result;
818
818
  }
819
- /** @deprecated Use `buildDaxtaSpec` */
819
+ /** Generate API documentation (OpenAPI spec + HTML viewer) from recorded test execution. */
820
+ exports.generateApiDocs = buildDaxtaSpec;
821
+ /** @deprecated Use `generateApiDocs` */
820
822
  exports.buildOpenApi = buildDaxtaSpec;
@@ -110,17 +110,20 @@ function writeConfig(cwd, dryRun) {
110
110
  const body = `import { defineConfig } from '@t0.labs/daxta';
111
111
 
112
112
  export default defineConfig({
113
+ specInfo: () => ({
114
+ title: 'API',
115
+ version: '1.0.0',
116
+ }),
113
117
  workspace: 'API',
114
118
  baseUrl: 'http://localhost:3000',
115
119
  controllersRoot: 'src',
116
- outDir: 'daxta/out',
117
- docsPath: '/docs',
120
+ outDir: '.daxta/out',
121
+ docsPath: '/api-docs',
118
122
  treeLayout: 'role-resource',
119
123
  treeSkipParams: true,
120
124
  exampleLabelStyle: 'status-title-case',
121
- fieldsFile: 'daxta/out/daxta.fields.json',
122
- viewerStoreFile: 'daxta/viewer-store.json',
123
- // Multi-base Try-it presets (docs env picker). Secrets stay in viewer-store / UI.
125
+ fieldsFile: '.daxta/out/fields.json',
126
+ viewerStoreFile: '.daxta/viewer-store.json',
124
127
  envPresets: {
125
128
  local: { baseUrl: 'http://localhost:3000' },
126
129
  staging: { baseUrl: 'https://api.staging.example.com' },
@@ -134,7 +137,7 @@ export default defineConfig({
134
137
  }
135
138
  function ensureGitignore(cwd, dryRun) {
136
139
  const gitignorePath = path.join(cwd, '.gitignore');
137
- const entries = ['daxta/out/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
140
+ const entries = ['.daxta/out/', '.daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
138
141
  if (!(0, fs_1.existsSync)(gitignorePath)) {
139
142
  if (!dryRun)
140
143
  (0, fs_1.writeFileSync)(gitignorePath, `${entries.join('\n')}\n`);
@@ -145,7 +148,7 @@ function ensureGitignore(cwd, dryRun) {
145
148
  const added = [];
146
149
  let next = text;
147
150
  for (const entry of entries) {
148
- if (lines.has(entry) || lines.has('daxta/') || (entry === 'daxta/out/' && lines.has('daxta/out')))
151
+ if (lines.has(entry) || lines.has('.daxta/') || lines.has('daxta/') || (entry === '.daxta/out/' && (lines.has('.daxta/out') || lines.has('daxta/out/'))))
149
152
  continue;
150
153
  next = next.endsWith('\n') ? `${next}${entry}\n` : `${next}\n${entry}\n`;
151
154
  added.push(entry);
@@ -225,7 +228,7 @@ async function installDaxta(options = {}) {
225
228
  await (0, ui_1.step)('Package dependency', () => 'already installed — skip add', { paceMs, n: 1, of });
226
229
  }
227
230
  }
228
- (0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, docs env flag');
231
+ (0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, API docs env flag');
229
232
  await (0, ui_1.step)('Write daxta.config.ts', () => {
230
233
  const { created, rel } = writeConfig(cwd, dryRun);
231
234
  return created ? `created ${rel}` : `exists · ${rel}`;
@@ -246,8 +249,8 @@ async function installDaxta(options = {}) {
246
249
  }, { paceMs, n: 2, of });
247
250
  await (0, ui_1.step)('Prepare output dir', () => {
248
251
  if (!dryRun)
249
- (0, fs_1.mkdirSync)(path.join(cwd, 'daxta', 'out'), { recursive: true });
250
- return 'daxta/out';
252
+ (0, fs_1.mkdirSync)(path.join(cwd, '.daxta', 'out'), { recursive: true });
253
+ return '.daxta/out';
251
254
  }, { paceMs, n: 2, of });
252
255
  await (0, ui_1.step)('Update .gitignore', () => {
253
256
  const notes = ensureGitignore(cwd, dryRun);
@@ -334,14 +337,14 @@ async function installDaxta(options = {}) {
334
337
  else {
335
338
  await (0, ui_1.step)('Attach test hooks', () => 'skipped', { paceMs, n: 4, of });
336
339
  }
337
- (0, ui_1.phase)(5, of, 'Docs taste', 'sidebar folders + test titles for the viewer');
340
+ (0, ui_1.phase)(5, of, 'API docs taste', 'sidebar folders + test titles for the viewer');
338
341
  if (!dryRun) {
339
342
  await (0, tree_1.runTreeWizard)({ embedded: true, yes: Boolean(options.yes) });
340
343
  await (0, titles_1.runTitleCheck)({ cwd, yes: Boolean(options.yes) });
341
344
  }
342
345
  (0, ui_1.box)('Ready', [
343
346
  `${ui_1.c.mint('✔')} ${ui_1.c.bold(project)} · DAxTA ${ui_1.c.gold(`v${version}`)}`,
344
- `${ui_1.c.dim('docs')} ${ui_1.c.ice('/docs')} · ${ui_1.c.ice('DAXTA_DOCS=true')}`,
347
+ `${ui_1.c.dim('api docs')} ${ui_1.c.ice('/api-docs')} · ${ui_1.c.ice('DAXTA_DOCS=true')}`,
345
348
  `${ui_1.c.dim('tests')} same script — titles first, spec after`,
346
349
  `${ui_1.c.dim('retune')} ${ui_1.c.ice('daxta tree')} · ${ui_1.c.ice('daxta titles')}`,
347
350
  ]);
@@ -353,7 +356,7 @@ async function installDaxta(options = {}) {
353
356
  },
354
357
  {
355
358
  cmd: `${pm} start:dev`,
356
- why: 'open /docs (DAXTA_DOCS already in .env)',
359
+ why: 'open /api-docs (DAXTA_DOCS already in .env)',
357
360
  },
358
361
  ]);
359
362
  }
package/dist/cli/main.js CHANGED
@@ -15,24 +15,24 @@ const ui_1 = require("./ui");
15
15
  function usage() {
16
16
  const cmd = (name) => ui_1.c.bold(ui_1.c.ice(name));
17
17
  console.log('');
18
- console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))} ${ui_1.c.dim('docs from Nest traffic · @t0.labs/daxta')}`);
18
+ console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))}`);
19
+ console.log(` ${ui_1.c.dim('Tested behavior. Trusted API docs.')}`);
19
20
  console.log('');
20
21
  console.log(` ${ui_1.c.gold('Setup')}`);
21
- console.log(` ${cmd('daxta install')} ${ui_1.c.dim('[--yes] [--dry-run] [--skip-dep] [--skip-main] [--fast]')}`);
22
- console.log(` ${cmd('daxta init')} ${ui_1.c.dim('alias of install')}`);
23
- console.log(` ${cmd('daxta uninstall')} ${ui_1.c.dim('[--yes] [--dry-run] [--keep-dep]')}`);
24
- console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('[--yes]')}`);
22
+ console.log(` ${cmd('daxta install')} ${ui_1.c.dim('Install DAxTA in this project')}`);
23
+ console.log(` ${cmd('daxta uninstall')} ${ui_1.c.dim('Remove DAxTA from this project')}`);
24
+ console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('Upgrade project wiring after a package bump')}`);
25
25
  console.log('');
26
- console.log(` ${ui_1.c.gold('Docs & tests')}`);
27
- console.log(` ${cmd('daxta titles')} ${ui_1.c.dim('[--check] [--yes] [--strict]')}`);
28
- console.log(` ${cmd('daxta test')} ${ui_1.c.dim('your Jest script + plugin')}`);
29
- console.log(` ${cmd('daxta build')} ${ui_1.c.dim('OpenAPI + viewer from hits')}`);
30
- console.log(` ${cmd('daxta serve')} ${ui_1.c.dim('[--port]')}`);
31
- console.log(` ${cmd('daxta tree')} ${ui_1.c.dim('sidebar layout')}`);
26
+ console.log(` ${ui_1.c.gold('API docs')}`);
27
+ console.log(` ${cmd('daxta generate')} ${ui_1.c.dim('Generate API documentation from test execution')}`);
28
+ console.log(` ${cmd('daxta serve')} ${ui_1.c.dim('Serve API documentation locally')}`);
29
+ console.log(` ${cmd('daxta tree')} ${ui_1.c.dim('Configure API docs sidebar layout')}`);
30
+ console.log(` ${cmd('daxta titles')} ${ui_1.c.dim('Align test titles with API docs examples')}`);
31
+ console.log(` ${cmd('daxta test')} ${ui_1.c.dim('Run the project test script (Jest stays parent)')}`);
32
32
  console.log('');
33
33
  console.log(` ${ui_1.c.gold('Try-it')}`);
34
- console.log(` ${cmd('daxta fields')} ${ui_1.c.dim('[METHOD] [PATH]')}`);
35
- console.log(` ${cmd('daxta call')} ${ui_1.c.dim('[METHOD] [PATH] | --file')}`);
34
+ console.log(` ${cmd('daxta fields')} ${ui_1.c.dim('Export API field map')}`);
35
+ console.log(` ${cmd('daxta call')} ${ui_1.c.dim('Send a Try-it request from the CLI')}`);
36
36
  console.log('');
37
37
  console.log(` ${ui_1.c.mint('First time')} ${ui_1.c.ice('pnpm dlx @t0.labs/daxta install')}`);
38
38
  console.log('');
@@ -126,8 +126,8 @@ async function main() {
126
126
  await (0, test_1.runDaxtaTest)({ argv });
127
127
  return;
128
128
  }
129
- if (command === 'build') {
130
- (0, build_spec_1.buildDaxtaSpec)({ requireHits: true });
129
+ if (command === 'generate' || command === 'build') {
130
+ (0, build_spec_1.generateApiDocs)({ requireHits: true });
131
131
  return;
132
132
  }
133
133
  if (command === 'serve') {
@@ -181,9 +181,9 @@ function migrateMainApiDocs(cwd) {
181
181
  function migrateConfigDefaults(configPath, configText) {
182
182
  const notes = [];
183
183
  const fields = readStringField(configText, 'fieldsFile');
184
- const outDir = readStringField(configText, 'outDir') || 'daxta/out';
184
+ const outDir = readStringField(configText, 'outDir') || '.daxta/out';
185
185
  if (fields === 'daxta.fields.json' || fields === './daxta.fields.json') {
186
- const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/daxta.fields.json`;
186
+ const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/fields.json`;
187
187
  if (upsertConfigField(configPath, 'fieldsFile', next)) {
188
188
  notes.push(`fieldsFile → ${next}`);
189
189
  }
@@ -128,17 +128,17 @@ async function runTitleCheck(options) {
128
128
  (0, scan_1.printNamingFindings)(report, ui_1.c);
129
129
  return options.strict ? 1 : 0;
130
130
  }
131
- (0, ui_1.banner)('Test naming', 'runs before Jest — docs / Postman labels');
131
+ (0, ui_1.banner)('Test naming', 'runs before Jest — API docs / Postman labels');
132
132
  console.log(` ${ui_1.c.dim('Title')} Create Mock Tbs — POST /v1/admin/mock-tbs`);
133
133
  console.log(` ${ui_1.c.dim('it()+')} creates mock tbs when cyprus payload shape`);
134
134
  console.log(` ${ui_1.c.dim('it()-')} returns error when tax id already exists`);
135
- console.log(` ${ui_1.c.dim('docs')} 201 — cyprus payload shape`);
135
+ console.log(` ${ui_1.c.dim('label')} 201 — cyprus payload shape`);
136
136
  console.log(` ${ui_1.c.gold(String(total))} to review — ${ui_1.c.ice('y')} one recommended, ${ui_1.c.ice('a')} all remaining, ${ui_1.c.ice('s')} skip.`);
137
137
  let written = 0;
138
138
  let skipped = 0;
139
139
  for (let i = 0; i < report.titles.length; i += 1) {
140
140
  const finding = report.titles[i];
141
- const choice = await pickFromSuggestions(finding, `docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
141
+ const choice = await pickFromSuggestions(finding, `API docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
142
142
  if (choice === 'all') {
143
143
  const rest = applyAllRecommended(cwd, report.titles, report.cases, i, 0);
144
144
  written += rest.written;
@@ -5,6 +5,6 @@ export type TreeWizardOptions = {
5
5
  yes?: boolean;
6
6
  };
7
7
  /**
8
- * Company docs presentation wizard — install / migrate / `daxta tree`.
8
+ * Company API docs presentation wizard — install / migrate / `daxta tree`.
9
9
  */
10
10
  export declare function runTreeWizard(options?: TreeWizardOptions): Promise<void>;
package/dist/cli/tree.js CHANGED
@@ -169,7 +169,7 @@ async function pickSegments(pathTemplate, layout, skipParams) {
169
169
  return typed.split(/›|>|,|\s+/).map((part) => part.trim()).filter(Boolean);
170
170
  }
171
171
  /**
172
- * Company docs presentation wizard — install / migrate / `daxta tree`.
172
+ * Company API docs presentation wizard — install / migrate / `daxta tree`.
173
173
  */
174
174
  async function runTreeWizard(options = {}) {
175
175
  if (options.yes || !process.stdin.isTTY) {
@@ -178,14 +178,14 @@ async function runTreeWizard(options = {}) {
178
178
  return;
179
179
  }
180
180
  if (!options.embedded)
181
- (0, ui_1.banner)('DAxTA tree', 'docs presentation');
181
+ (0, ui_1.banner)('DAxTA tree', 'API docs presentation');
182
182
  const configPath = (0, config_edit_1.findDaxtaConfigPath)();
183
183
  if (!configPath)
184
184
  throw new Error('No daxta.config.ts found. Run `daxta install` first.');
185
185
  (0, config_1.resetConfig)();
186
186
  const config = (0, config_1.getConfig)(true);
187
187
  console.log('');
188
- console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('Docs presentation')} ${ui_1.c.dim('— sidebar + OpenAPI export')}`);
188
+ console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('API docs presentation')} ${ui_1.c.dim('— sidebar + OpenAPI export')}`);
189
189
  let layout = (0, config_1.normalizeTreeLayout)(options.layout === 'resource-first' || options.layout === 'resource-role'
190
190
  ? 'resource-role'
191
191
  : options.layout === 'url-order' || options.layout === 'role-resource'
@@ -219,7 +219,7 @@ async function runTreeWizard(options = {}) {
219
219
  }
220
220
  if (!options.embedded) {
221
221
  console.log(` ${ui_1.c.dim('saved')} ${configPath}`);
222
- console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta build')}`);
222
+ console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta generate')}`);
223
223
  console.log('');
224
224
  }
225
225
  }
package/dist/cli/ui.js CHANGED
@@ -74,7 +74,7 @@ function divider(width = 52) {
74
74
  }
75
75
  function splash(options) {
76
76
  const title = 'DAxTA';
77
- const tag = 'Document API × Test API';
77
+ const tag = 'Tested behavior. Trusted API docs.';
78
78
  const meta = `v${options.version} · ${options.project}${options.dryRun ? ' · dry-run' : ''}`;
79
79
  const inner = 50;
80
80
  const pad = (s) => s + ' '.repeat(Math.max(0, inner - s.length));
@@ -62,7 +62,15 @@ function stripGitignore(cwd, dryRun) {
62
62
  const gitignorePath = path.join(cwd, '.gitignore');
63
63
  if (!(0, fs_1.existsSync)(gitignorePath))
64
64
  return [];
65
- const remove = new Set(['daxta/out/', 'daxta/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json']);
65
+ const remove = new Set([
66
+ 'daxta/out/',
67
+ 'daxta/',
68
+ 'daxta/viewer-store.json',
69
+ '.daxta/out/',
70
+ '.daxta/',
71
+ '.daxta/viewer-store.json',
72
+ '**/.jest.daxta.runtime.json',
73
+ ]);
66
74
  const before = (0, fs_1.readFileSync)(gitignorePath, 'utf8');
67
75
  const lines = before.split(/\r?\n/);
68
76
  const kept = lines.filter((line) => !remove.has(line.trim()));
@@ -232,11 +240,13 @@ async function uninstallDaxta(options = {}) {
232
240
  (0, fs_1.rmSync)(configPath, { force: true });
233
241
  details.push(path.relative(cwd, configPath));
234
242
  }
235
- const outDir = path.join(cwd, 'daxta');
236
- if ((0, fs_1.existsSync)(outDir)) {
237
- if (!dryRun)
238
- (0, fs_1.rmSync)(outDir, { recursive: true, force: true });
239
- details.push('daxta/');
243
+ for (const dir of ['daxta', '.daxta']) {
244
+ const outDir = path.join(cwd, dir);
245
+ if ((0, fs_1.existsSync)(outDir)) {
246
+ if (!dryRun)
247
+ (0, fs_1.rmSync)(outDir, { recursive: true, force: true });
248
+ details.push(`${dir}/`);
249
+ }
240
250
  }
241
251
  if (!details.length)
242
252
  return 'already gone';
package/dist/config.d.ts CHANGED
@@ -19,7 +19,7 @@ export type DaxtaConfig = {
19
19
  baseUrl?: string;
20
20
  /**
21
21
  * Multi-base Try-it presets (local / staging / production, …).
22
- * Seeded into the docs env picker and `daxta/viewer-store.json` on first write.
22
+ * Seeded into the API docs env picker and `.daxta/viewer-store.json` on first write.
23
23
  * Default: `{ local: { baseUrl } }` from `baseUrl`.
24
24
  */
25
25
  envPresets?: Record<string, EnvPreset>;
@@ -42,14 +42,14 @@ export type DaxtaConfig = {
42
42
  * - status-case → `201 — cyprus payload shape`
43
43
  * - status-title-case → `201 — Create Mock Tbs — cyprus payload shape`
44
44
  * - full → includes path + POSITIVE CASES + clause
45
- * Test it() stays `creates mock tbs when cyprus payload shape`; docs take the `when` clause.
45
+ * Test it() stays `creates mock tbs when cyprus payload shape`; API docs take the `when` clause.
46
46
  */
47
47
  exampleLabelStyle?: ExampleLabelStyle;
48
48
  port?: number;
49
49
  fieldsFile?: string;
50
50
  docsPath?: string;
51
51
  /**
52
- * Persisted Try-it env/header store (survives rebuild). Default `daxta/viewer-store.json`.
52
+ * Persisted Try-it env/header store (survives rebuild). Default `.daxta/viewer-store.json`.
53
53
  * Served at `{docsPath}/env.json`. Keep out of git if it holds secrets.
54
54
  */
55
55
  viewerStoreFile?: string;
package/dist/config.js CHANGED
@@ -45,15 +45,15 @@ const DEFAULTS = {
45
45
  workspace: 'API',
46
46
  baseUrl: 'http://localhost:3000',
47
47
  controllersRoot: 'src',
48
- outDir: 'daxta/out',
48
+ outDir: '.daxta/out',
49
49
  treeLayout: 'role-resource',
50
50
  treeSkipParams: true,
51
51
  treePathOverrides: {},
52
52
  exampleLabelStyle: 'status-title-case',
53
53
  port: 5199,
54
- fieldsFile: 'daxta.fields.json',
55
- docsPath: '/docs',
56
- viewerStoreFile: 'daxta/viewer-store.json',
54
+ fieldsFile: '.daxta/out/fields.json',
55
+ docsPath: '/api-docs',
56
+ viewerStoreFile: '.daxta/viewer-store.json',
57
57
  envPresets: {
58
58
  local: { baseUrl: 'http://localhost:3000' },
59
59
  },
package/dist/index.d.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type EnvPreset, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
2
- export { buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
2
+ export { generateApiDocs, buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
3
3
  export { rebuildFromDisk, flushAndRebuild, clearPartialMarker, touchPartialMarker } from './build/incremental';
4
4
  export { install, flush, clearWorkerHits, getHits, type RecordedHit } from './recorder';
5
5
  export { dtoRequired, type FieldLocation } from './fields/dto-fields';
6
6
  export { buildFieldsFile, writeFieldsFile, readFieldsFile, type FieldsFile } from './fields/export-fields';
7
- export { apiDocs, apiDocsHandler, serveApiDocs, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
7
+ export { apiDocs, apiDocsHandler, serveApiDocs, getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
8
8
  export { runInteractiveCall, runFileCall, executeCall, type CallValues } from './call';
9
9
  export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, docsScenarioClause, type FieldDoc, type OperationDoc, } from './catalog';
10
10
  export { installDaxta, type InstallOptions } from './cli/install';
package/dist/index.js CHANGED
@@ -1,12 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
3
+ exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.generateApiDocs = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
4
4
  var config_1 = require("./config");
5
5
  Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
6
6
  Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
7
7
  Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
8
8
  Object.defineProperty(exports, "normalizeTreeLayout", { enumerable: true, get: function () { return config_1.normalizeTreeLayout; } });
9
9
  var build_spec_1 = require("./build/build-spec");
10
+ Object.defineProperty(exports, "generateApiDocs", { enumerable: true, get: function () { return build_spec_1.generateApiDocs; } });
10
11
  Object.defineProperty(exports, "buildDaxtaSpec", { enumerable: true, get: function () { return build_spec_1.buildDaxtaSpec; } });
11
12
  Object.defineProperty(exports, "buildOpenApi", { enumerable: true, get: function () { return build_spec_1.buildOpenApi; } });
12
13
  Object.defineProperty(exports, "loadHits", { enumerable: true, get: function () { return build_spec_1.loadHits; } });
@@ -30,6 +31,8 @@ var serve_1 = require("./serve");
30
31
  Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return serve_1.apiDocs; } });
31
32
  Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return serve_1.apiDocsHandler; } });
32
33
  Object.defineProperty(exports, "serveApiDocs", { enumerable: true, get: function () { return serve_1.serveApiDocs; } });
34
+ Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return serve_1.getApiDocs; } });
35
+ Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return serve_1.getApiDocUrl; } });
33
36
  Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return serve_1.getDocsBasePath; } });
34
37
  Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return serve_1.getHtmlPath; } });
35
38
  Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return serve_1.getOutDir; } });
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Optional jest globalTeardown — silent build only.
3
- * Docs ready is printed by the Jest reporter so we don't own the test process.
2
+ * Optional jest globalTeardown — silent generate only.
3
+ * API docs ready is printed by the Jest reporter so we don't own the test process.
4
4
  */
5
5
  export default function daxtaGlobalTeardown(): Promise<void>;
@@ -4,12 +4,12 @@ exports.default = daxtaGlobalTeardown;
4
4
  const incremental_1 = require("../build/incremental");
5
5
  const build_spec_1 = require("../build/build-spec");
6
6
  /**
7
- * Optional jest globalTeardown — silent build only.
8
- * Docs ready is printed by the Jest reporter so we don't own the test process.
7
+ * Optional jest globalTeardown — silent generate only.
8
+ * API docs ready is printed by the Jest reporter so we don't own the test process.
9
9
  */
10
10
  async function daxtaGlobalTeardown() {
11
11
  try {
12
- (0, build_spec_1.buildDaxtaSpec)({ silent: true, html: true });
12
+ (0, build_spec_1.generateApiDocs)({ silent: true, html: true });
13
13
  (0, incremental_1.clearPartialMarker)();
14
14
  }
15
15
  catch {
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Jest reporter — only builds OpenAPI/HTML when the full run completes.
2
+ * Jest reporter — only generates API docs when the full run completes.
3
3
  * During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
4
4
  */
5
5
  declare class DaxtaJestReporter {
@@ -6,15 +6,14 @@ const paths_1 = require("../serve/paths");
6
6
  function printDocsReady(hits, operations) {
7
7
  try {
8
8
  (0, config_1.resetConfig)();
9
- const config = (0, config_1.getConfig)(true);
10
- const docsBase = (0, paths_1.getDocsBasePath)();
11
- const url = `${config.baseUrl.replace(/\/$/, '')}${docsBase}`;
9
+ (0, config_1.getConfig)(true);
10
+ const url = (0, paths_1.getApiDocUrl)();
12
11
  const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
13
12
  const green = (s) => `\x1b[32m${s}\x1b[0m`;
14
13
  const dim = (s) => `\x1b[2m${s}\x1b[0m`;
15
14
  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
16
15
  console.log('');
17
- console.log(` ${bold('Docs ready')}`);
16
+ console.log(` ${bold('API docs ready')}`);
18
17
  console.log(` ${dim('│')} ${green('✔')} ${cyan(url)} ${dim(`(${hits} hits · ${operations} ops)`)}`);
19
18
  console.log(` ${dim('│')} ${dim('DAXTA_DOCS=true')} required on app start`);
20
19
  console.log('');
@@ -24,11 +23,11 @@ function printDocsReady(hits, operations) {
24
23
  console.log('');
25
24
  }
26
25
  catch {
27
- console.log(`\nDAxTA docs ready (${hits} hits · ${operations} ops)\n`);
26
+ console.log(`\nDAxTA: API docs ready (${hits} hits · ${operations} ops)\n`);
28
27
  }
29
28
  }
30
29
  /**
31
- * Jest reporter — only builds OpenAPI/HTML when the full run completes.
30
+ * Jest reporter — only generates API docs when the full run completes.
32
31
  * During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
33
32
  */
34
33
  class DaxtaJestReporter {
@@ -43,7 +42,7 @@ class DaxtaJestReporter {
43
42
  printDocsReady(result.hits ?? 0, result.operations ?? 0);
44
43
  return;
45
44
  }
46
- const build = (0, build_spec_1.buildDaxtaSpec)({ silent: true, html: true });
45
+ const build = (0, build_spec_1.generateApiDocs)({ silent: true, html: true });
47
46
  (0, incremental_1.clearPartialMarker)();
48
47
  if (!build.skipped)
49
48
  printDocsReady(build.hits, build.operations);
@@ -1,7 +1,7 @@
1
1
  import * as http from 'http';
2
2
  export { apiDocs, apiDocsHandler, type ApiDocsHandler, type ApiDocsOptions } from './middleware';
3
- export { getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
4
- /** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
3
+ export { getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
4
+ /** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
5
5
  export declare function serveApiDocs(options?: {
6
6
  port?: number;
7
7
  }): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.apiDocsHandler = exports.apiDocs = void 0;
36
+ exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.apiDocsHandler = exports.apiDocs = void 0;
37
37
  exports.serveApiDocs = serveApiDocs;
38
38
  const fs_1 = require("fs");
39
39
  const http = __importStar(require("http"));
@@ -47,6 +47,8 @@ var middleware_1 = require("./middleware");
47
47
  Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return middleware_1.apiDocs; } });
48
48
  Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return middleware_1.apiDocsHandler; } });
49
49
  var paths_2 = require("./paths");
50
+ Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return paths_2.getApiDocs; } });
51
+ Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return paths_2.getApiDocUrl; } });
50
52
  Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return paths_2.getDocsBasePath; } });
51
53
  Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return paths_2.getHtmlPath; } });
52
54
  Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return paths_2.getOutDir; } });
@@ -61,7 +63,7 @@ async function readBody(req) {
61
63
  chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
62
64
  return Buffer.concat(chunks);
63
65
  }
64
- /** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
66
+ /** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
65
67
  function serveApiDocs(options = {}) {
66
68
  const config = (0, config_1.getConfig)();
67
69
  const port = options.port ?? Number(process.env.DAXTA_DOCS_PORT || process.env.OPENAPI_DOCS_PORT || config.port);
@@ -138,7 +140,7 @@ function serveApiDocs(options = {}) {
138
140
  if (url.pathname === '/openapi.json' || url.pathname === `${docsBase}/openapi.json`) {
139
141
  const body = (0, spec_utils_1.readStrippedOpenApiJson)();
140
142
  if (!body) {
141
- send(res, 404, 'openapi.json not found. Run `daxta build` first.');
143
+ send(res, 404, 'openapi.json not found. Run `daxta generate` first.');
142
144
  return;
143
145
  }
144
146
  send(res, 200, body, {
@@ -151,9 +153,9 @@ function serveApiDocs(options = {}) {
151
153
  send(res, 404, 'Not found');
152
154
  });
153
155
  server.listen(port, '127.0.0.1', () => {
154
- console.log(`DAxTA docs: http://127.0.0.1:${port}${docsBase}`);
155
- console.log(`DAxTA OpenAPI: http://127.0.0.1:${port}${docsBase}/openapi.json`);
156
- console.log(`DAxTA env: http://127.0.0.1:${port}${docsBase}/env.json`);
156
+ console.log(`API docs: http://127.0.0.1:${port}${docsBase}`);
157
+ console.log(`API spec: http://127.0.0.1:${port}${docsBase}/openapi.json`);
158
+ console.log(`API docs env: http://127.0.0.1:${port}${docsBase}/env.json`);
157
159
  });
158
160
  return server;
159
161
  }
@@ -1,5 +1,5 @@
1
1
  export type ApiDocsOptions = {
2
- /** URL prefix for the viewer. Default from config (`docsPath`) or `/docs`. */
2
+ /** URL prefix for the API docs viewer. Default from config (`docsPath`) or `/api-docs`. */
3
3
  basePath?: string;
4
4
  };
5
5
  type LooseRequest = {
@@ -22,16 +22,16 @@ type LooseResponse = {
22
22
  };
23
23
  export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
24
24
  /**
25
- * Express / Nest handler that serves the DAxTA viewer under `/docs`
25
+ * Express / Nest handler that serves generated API docs under `/api-docs`
26
26
  * (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
27
27
  */
28
28
  export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler;
29
29
  /**
30
- * Enable DAxTA `/docs` on a Nest / Express app (`app.use(...)`).
30
+ * Mount generated API docs on a Nest / Express app (`app.use(...)`).
31
31
  *
32
32
  * Requires `DAXTA_DOCS` in the environment:
33
33
  * - missing / empty → throws (app must set it explicitly)
34
- * - `true` | `1` | `yes` | `on` → serve `/docs`
34
+ * - `true` | `1` | `yes` | `on` → serve API docs
35
35
  * - `false` | `0` | `no` | `off` → no-op
36
36
  */
37
37
  export declare function apiDocs(app: {
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
96
96
  }
97
97
  }
98
98
  /**
99
- * Express / Nest handler that serves the DAxTA viewer under `/docs`
99
+ * Express / Nest handler that serves generated API docs under `/api-docs`
100
100
  * (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
101
101
  */
102
102
  function apiDocsHandler(options = {}) {
103
- const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
103
+ const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/api-docs';
104
104
  return async (req, res, next) => {
105
105
  const method = (req.method || 'GET').toUpperCase();
106
106
  const pathname = requestPathname(req);
@@ -163,7 +163,7 @@ function apiDocsHandler(options = {}) {
163
163
  if (isDocsSpec) {
164
164
  const body = (0, spec_utils_1.readStrippedOpenApiJson)();
165
165
  if (!body) {
166
- write(res, 404, 'openapi.json not found. Run `daxta build` first.', { 'content-type': 'text/plain; charset=utf-8' });
166
+ write(res, 404, 'openapi.json not found. Run `daxta generate` first.', { 'content-type': 'text/plain; charset=utf-8' });
167
167
  return;
168
168
  }
169
169
  write(res, 200, body, {
@@ -190,17 +190,17 @@ function apiDocsHandler(options = {}) {
190
190
  };
191
191
  }
192
192
  /**
193
- * Enable DAxTA `/docs` on a Nest / Express app (`app.use(...)`).
193
+ * Mount generated API docs on a Nest / Express app (`app.use(...)`).
194
194
  *
195
195
  * Requires `DAXTA_DOCS` in the environment:
196
196
  * - missing / empty → throws (app must set it explicitly)
197
- * - `true` | `1` | `yes` | `on` → serve `/docs`
197
+ * - `true` | `1` | `yes` | `on` → serve API docs
198
198
  * - `false` | `0` | `no` | `off` → no-op
199
199
  */
200
200
  function apiDocs(app, options = {}) {
201
201
  const raw = process.env.DAXTA_DOCS;
202
202
  if (raw == null || String(raw).trim() === '') {
203
- throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable /docs, or DAXTA_DOCS=false to disable.');
203
+ throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable API docs, or DAXTA_DOCS=false to disable.');
204
204
  }
205
205
  const normalized = String(raw).trim().toLowerCase();
206
206
  const enabled = ['1', 'true', 'yes', 'on'].includes(normalized);
@@ -9,3 +9,11 @@ export declare function getEmptyViewerAssetPath(): string;
9
9
  export declare function readEmptyDocsHtml(): Buffer;
10
10
  export declare function getFaviconAssetPath(): string;
11
11
  export declare function getDocsBasePath(): string;
12
+ /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
13
+ export declare function getApiDocUrl(): string;
14
+ /** Paths and URL for the generated API docs artifact. */
15
+ export declare function getApiDocs(): {
16
+ url: string;
17
+ specPath: string;
18
+ htmlPath: string;
19
+ };
@@ -43,6 +43,8 @@ exports.getEmptyViewerAssetPath = getEmptyViewerAssetPath;
43
43
  exports.readEmptyDocsHtml = readEmptyDocsHtml;
44
44
  exports.getFaviconAssetPath = getFaviconAssetPath;
45
45
  exports.getDocsBasePath = getDocsBasePath;
46
+ exports.getApiDocUrl = getApiDocUrl;
47
+ exports.getApiDocs = getApiDocs;
46
48
  const fs_1 = require("fs");
47
49
  const path = __importStar(require("path"));
48
50
  const config_1 = require("../config");
@@ -68,9 +70,9 @@ function getViewerAssetPath() {
68
70
  function getEmptyViewerAssetPath() {
69
71
  return path.join(__dirname, '..', '..', 'assets', 'empty.html');
70
72
  }
71
- const EMPTY_DOCS_FALLBACK = `<!doctype html><html lang="en"><head><meta charset="utf-8"/><title>DAxTA</title></head><body style="font:13px/1.45 system-ui;background:#fafafa;color:#111;margin:0;padding:48px 24px">
73
+ const EMPTY_DOCS_FALLBACK = `<!doctype html><html lang="en"><head><meta charset="utf-8"/><title>API Documentation</title></head><body style="font:13px/1.45 system-ui;background:#fafafa;color:#111;margin:0;padding:48px 24px">
72
74
  <p style="font:600 10px/1 ui-monospace,monospace;letter-spacing:.08em;text-transform:uppercase;color:#666">Waiting</p>
73
- <h1 style="font-size:22px;letter-spacing:-.04em">No documentation yet</h1>
75
+ <h1 style="font-size:22px;letter-spacing:-.04em">No API documentation yet</h1>
74
76
  <p>Run your integration tests, then refresh this page.</p>
75
77
  </body></html>`;
76
78
  function readEmptyDocsHtml() {
@@ -86,6 +88,19 @@ function getFaviconAssetPath() {
86
88
  return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
87
89
  }
88
90
  function getDocsBasePath() {
89
- const configured = (0, config_1.getConfig)().docsPath ?? '/docs';
90
- return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/docs' : `/${configured}`.replace(/\/$/, '');
91
+ const configured = (0, config_1.getConfig)().docsPath ?? '/api-docs';
92
+ return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/api-docs' : `/${configured}`.replace(/\/$/, '');
93
+ }
94
+ /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
95
+ function getApiDocUrl() {
96
+ const config = (0, config_1.getConfig)();
97
+ return `${String(config.baseUrl || '').replace(/\/$/, '')}${getDocsBasePath()}`;
98
+ }
99
+ /** Paths and URL for the generated API docs artifact. */
100
+ function getApiDocs() {
101
+ return {
102
+ url: getApiDocUrl(),
103
+ specPath: getSpecJsonPath(),
104
+ htmlPath: getHtmlPath(),
105
+ };
91
106
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@t0.labs/daxta",
3
- "version": "0.5.0",
4
- "description": "DAxTA \u2014 docs from Nest integration traffic + DTO field CLI / Try-it",
3
+ "version": "0.5.1",
4
+ "description": "DAxTA — Tested behavior. Trusted API docs. Generate API documentation from observed test execution.",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",