@t0.labs/daxta 0.5.0 → 0.5.2

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.
@@ -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
+ };