@t0.labs/daxta 0.2.1 → 0.2.5

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
@@ -2,31 +2,29 @@
2
2
 
3
3
  DAxTA — NestJS integration-test traffic → API docs, DTO required/optional, terminal Try-it, and app `/docs`.
4
4
 
5
- ## Install
5
+ ## Install (one command)
6
6
 
7
7
  ```bash
8
- npm i -D @t0.labs/daxta
9
- npx daxta install
8
+ pnpm dlx @t0.labs/daxta install
9
+ # or
10
+ npx @t0.labs/daxta install
10
11
  ```
11
12
 
12
- `daxta install`:
13
+ Adds the package as a devDependency **and** wires the project (config, scripts, `apiDocs(app)` into `main.ts`).
14
+
15
+ Flags: `--yes`, `--main src/main.ts`, `--skip-main`, `--dry-run`, `--skip-dep`, `--fast` (skip step delays)
13
16
 
14
- - writes `daxta.config.ts` + `daxta/out`
15
- - strips any `NODE_OPTIONS=--require @t0.labs/daxta/register` from start scripts
16
- - finds `main.ts`, asks **Y / n / other path**, injects:
17
17
 
18
18
  ```ts
19
- import { docs } from '@t0.labs/daxta';
20
- // ...
19
+ import { apiDocs } from '@t0.labs/daxta';
20
+
21
21
  const app = await NestFactory.create(AppModule);
22
- docs(app);
22
+ apiDocs(app);
23
23
  ```
24
24
 
25
- Flags: `--yes`, `--main src/main.ts`, `--skip-main`, `--dry-run`, `--skip-dep`
26
-
27
25
  ## Required env
28
26
 
29
- `docs(app)` **throws** if `DAXTA_DOCS` is missing:
27
+ `apiDocs(app)` **throws** if `DAXTA_DOCS` is missing:
30
28
 
31
29
  ```bash
32
30
  DAXTA_DOCS=true # enable /docs
@@ -36,20 +34,23 @@ DAXTA_DOCS=false # disable (must be set explicitly)
36
34
  ## Runtime CLI
37
35
 
38
36
  ```bash
39
- daxta test
40
- daxta test --config test/setup/jest.integration.json
37
+ daxta test # run project tests → build → serve docs
38
+ daxta test --no-serve # build only, don't open server
39
+ daxta test --script test:integration
41
40
  daxta serve
42
41
  daxta build
43
42
  daxta fields
44
43
  daxta call
45
44
  ```
46
45
 
46
+ `daxta test` uses `testScript` from `daxta.config.ts` (set during install). It injects recording into Jest, builds OpenAPI/HTML, then serves the viewer.
47
+
47
48
  ## API
48
49
 
49
50
  ```ts
50
- import { docs, docsHandler, serveDocs } from '@t0.labs/daxta';
51
+ import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
51
52
 
52
- docs(app); // app /docs (needs DAXTA_DOCS)
53
- app.use(docsHandler()); // raw handler
54
- serveDocs({ port: 5199 }); // standalone viewer
53
+ apiDocs(app); // app /docs (needs DAXTA_DOCS)
54
+ app.use(apiDocsHandler()); // raw handler
55
+ serveApiDocs({ port: 5199 }); // standalone viewer
55
56
  ```
@@ -0,0 +1,21 @@
1
+ export type TestScriptChoice = {
2
+ name: string;
3
+ command: string;
4
+ };
5
+ /** package.json scripts that look like runnable test entrypoints */
6
+ export declare function listTestScripts(scripts: Record<string, string> | undefined): TestScriptChoice[];
7
+ /** Extract `--config` / `-c` path from a script command string */
8
+ export declare function extractJestConfigFromCommand(command: string): string | null;
9
+ /**
10
+ * Ask which package.json script to use for `daxta test`.
11
+ * Returns script name (e.g. test:integration) or null to skip.
12
+ */
13
+ export declare function resolveTestScript(options: {
14
+ cwd: string;
15
+ scripts?: Record<string, string>;
16
+ configured?: string;
17
+ yes?: boolean;
18
+ flag?: string;
19
+ }): Promise<string | null>;
20
+ /** Insert or update `testScript` in daxta.config.ts */
21
+ export declare function upsertTestScriptInConfig(cwd: string, testScript: string, dryRun?: boolean): string;
@@ -0,0 +1,150 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.listTestScripts = listTestScripts;
37
+ exports.extractJestConfigFromCommand = extractJestConfigFromCommand;
38
+ exports.resolveTestScript = resolveTestScript;
39
+ exports.upsertTestScriptInConfig = upsertTestScriptInConfig;
40
+ const readline_1 = require("readline");
41
+ const fs_1 = require("fs");
42
+ const path = __importStar(require("path"));
43
+ const ui_1 = require("./ui");
44
+ function prompt(question) {
45
+ const rl = (0, readline_1.createInterface)({ input: process.stdin, output: process.stdout });
46
+ return new Promise((resolve) => {
47
+ rl.question(question, (answer) => {
48
+ rl.close();
49
+ resolve(answer.trim());
50
+ });
51
+ });
52
+ }
53
+ function scoreScript(name, command) {
54
+ const n = name.toLowerCase();
55
+ const cmd = command.toLowerCase();
56
+ let score = 0;
57
+ if (n.includes('integration'))
58
+ score += 100;
59
+ if (n.includes('e2e'))
60
+ score += 80;
61
+ if (n.includes('api'))
62
+ score += 40;
63
+ if (n === 'test')
64
+ score += 10;
65
+ if (cmd.includes('jest'))
66
+ score += 30;
67
+ if (cmd.includes('integration'))
68
+ score += 20;
69
+ if (n.includes('unit') || n.includes('watch') || n.includes('cov'))
70
+ score -= 50;
71
+ return score;
72
+ }
73
+ /** package.json scripts that look like runnable test entrypoints */
74
+ function listTestScripts(scripts) {
75
+ if (!scripts)
76
+ return [];
77
+ const out = [];
78
+ for (const [name, command] of Object.entries(scripts)) {
79
+ if (name.startsWith('daxta:'))
80
+ continue;
81
+ const n = name.toLowerCase();
82
+ if (!(n === 'test' || n.startsWith('test:') || n.includes('e2e') || n.includes('integration')))
83
+ continue;
84
+ out.push({ name, command });
85
+ }
86
+ return out.sort((a, b) => scoreScript(b.name, b.command) - scoreScript(a.name, a.command));
87
+ }
88
+ /** Extract `--config` / `-c` path from a script command string */
89
+ function extractJestConfigFromCommand(command) {
90
+ const m = command.match(/--config(?:=|\s+)(['"]?)([^'"\s]+)\1/) ||
91
+ command.match(/(?:^|\s)-c(?:=|\s+)(['"]?)([^'"\s]+)\1/);
92
+ return m?.[2] ?? null;
93
+ }
94
+ /**
95
+ * Ask which package.json script to use for `daxta test`.
96
+ * Returns script name (e.g. test:integration) or null to skip.
97
+ */
98
+ async function resolveTestScript(options) {
99
+ if (options.flag)
100
+ return options.flag;
101
+ if (options.configured)
102
+ return options.configured;
103
+ const choices = listTestScripts(options.scripts);
104
+ if (!choices.length) {
105
+ if (options.yes || !process.stdin.isTTY)
106
+ return null;
107
+ const typed = await prompt(` ${ui_1.c.yellow('?')} ${ui_1.c.bold('No test script found.')} Enter script name, or ${ui_1.c.dim('n')} to skip:\n ${ui_1.c.cyan('›')} `);
108
+ if (!typed || /^n(o)?$/i.test(typed))
109
+ return null;
110
+ return typed;
111
+ }
112
+ const def = choices[0];
113
+ if (options.yes || !process.stdin.isTTY)
114
+ return def.name;
115
+ console.log(` ${ui_1.c.dim('test scripts')}`);
116
+ choices.slice(0, 8).forEach((choice, i) => {
117
+ const mark = i === 0 ? ui_1.c.cyan('●') : ui_1.c.dim('○');
118
+ const label = i === 0 ? ui_1.c.bold(choice.name) : ui_1.c.dim(choice.name);
119
+ console.log(` ${mark} ${label} ${ui_1.c.dim(choice.command.slice(0, 60))}`);
120
+ });
121
+ const answer = await prompt(` ${ui_1.c.yellow('?')} Use ${ui_1.c.cyan(def.name)} for ${ui_1.c.bold('daxta test')}?\n` +
122
+ ` ${ui_1.c.dim('Y')} yes · ${ui_1.c.dim('n')} skip · or type another script name\n ${ui_1.c.cyan('›')} `);
123
+ if (!answer || /^y(es)?$/i.test(answer))
124
+ return def.name;
125
+ if (/^n(o)?$/i.test(answer))
126
+ return null;
127
+ return answer;
128
+ }
129
+ /** Insert or update `testScript` in daxta.config.ts */
130
+ function upsertTestScriptInConfig(cwd, testScript, dryRun = false) {
131
+ const configPath = path.join(cwd, 'daxta.config.ts');
132
+ if (!(0, fs_1.existsSync)(configPath)) {
133
+ return 'no daxta.config.ts to update';
134
+ }
135
+ let text = (0, fs_1.readFileSync)(configPath, 'utf8');
136
+ if (/testScript\s*:/.test(text)) {
137
+ const next = text.replace(/testScript\s*:\s*['`][^'"`]*['`]/, `testScript: '${testScript}'`);
138
+ if (next === text)
139
+ return `testScript already '${testScript}'`;
140
+ if (!dryRun)
141
+ (0, fs_1.writeFileSync)(configPath, next);
142
+ return `updated testScript → '${testScript}'`;
143
+ }
144
+ const next = text.replace(/defineConfig\(\s*\{/, `defineConfig({\n testScript: '${testScript}',`);
145
+ if (next === text)
146
+ throw new Error('Could not insert testScript into daxta.config.ts');
147
+ if (!dryRun)
148
+ (0, fs_1.writeFileSync)(configPath, next);
149
+ return `set testScript: '${testScript}'`;
150
+ }
@@ -4,7 +4,7 @@ export declare function findMainCandidates(cwd: string): string[];
4
4
  * Ask: use detected main, or type another path / n to skip.
5
5
  */
6
6
  export declare function resolveMainPath(cwd: string, candidates: string[]): Promise<string | null>;
7
- export declare function injectDocs(filePath: string, dryRun?: boolean): string;
7
+ export declare function injectApiDocs(filePath: string, dryRun?: boolean): string;
8
8
  export type InjectMainOptions = {
9
9
  cwd?: string;
10
10
  dryRun?: boolean;
@@ -12,4 +12,5 @@ export type InjectMainOptions = {
12
12
  mainPath?: string;
13
13
  yes?: boolean;
14
14
  };
15
- export declare function promptAndInjectMain(options?: InjectMainOptions): Promise<string | null>;
15
+ /** Resolve which file to inject into (prompt / --main / --yes). Null = skip. */
16
+ export declare function resolveMainTarget(options?: InjectMainOptions): Promise<string | null>;
@@ -35,13 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.findMainCandidates = findMainCandidates;
37
37
  exports.resolveMainPath = resolveMainPath;
38
- exports.injectDocs = injectDocs;
39
- exports.promptAndInjectMain = promptAndInjectMain;
38
+ exports.injectApiDocs = injectApiDocs;
39
+ exports.resolveMainTarget = resolveMainTarget;
40
40
  const readline_1 = require("readline");
41
41
  const fs_1 = require("fs");
42
42
  const path = __importStar(require("path"));
43
- const IMPORT_LINE = `import { docs } from '@t0.labs/daxta';`;
44
- const MARKER = 'docs(';
43
+ const ui_1 = require("./ui");
44
+ const IMPORT_LINE = `import { apiDocs } from '@t0.labs/daxta';`;
45
+ const MARKER = 'apiDocs(';
45
46
  function walk(dir, match, out = [], depth = 0) {
46
47
  if (depth > 5 || !(0, fs_1.existsSync)(dir))
47
48
  return out;
@@ -93,7 +94,7 @@ function prompt(question) {
93
94
  async function resolveMainPath(cwd, candidates) {
94
95
  const def = candidates[0];
95
96
  if (!def) {
96
- const typed = await prompt('No main.ts found. Enter path (or n to skip): ');
97
+ const typed = await prompt(` ${ui_1.c.yellow('?')} ${ui_1.c.bold('No main.ts found.')} Enter path, or ${ui_1.c.dim('n')} to skip:\n ${ui_1.c.cyan('›')} `);
97
98
  if (!typed || /^n(o)?$/i.test(typed))
98
99
  return null;
99
100
  const full = path.isAbsolute(typed) ? typed : path.join(cwd, typed);
@@ -102,13 +103,17 @@ async function resolveMainPath(cwd, candidates) {
102
103
  return full;
103
104
  }
104
105
  const rel = path.relative(cwd, def);
105
- const others = candidates.length > 1
106
- ? `\n other candidates: ${candidates
107
- .slice(1, 4)
108
- .map((c) => path.relative(cwd, c))
109
- .join(', ')}${candidates.length > 4 ? ', …' : ''}`
110
- : '';
111
- const answer = await prompt(`Inject docs(app) into ${rel}? [Y/n / or type another path]${others}\n> `);
106
+ if (candidates.length > 1) {
107
+ console.log(` ${ui_1.c.dim('candidates')}`);
108
+ for (const file of candidates.slice(0, 5)) {
109
+ const r = path.relative(cwd, file);
110
+ console.log(` ${r === rel ? ui_1.c.cyan('●') : ui_1.c.dim('○')} ${r === rel ? ui_1.c.bold(r) : ui_1.c.dim(r)}`);
111
+ }
112
+ if (candidates.length > 5)
113
+ console.log(` ${ui_1.c.dim(`… +${candidates.length - 5} more`)}`);
114
+ }
115
+ const answer = await prompt(` ${ui_1.c.yellow('?')} Inject ${ui_1.c.bold('apiDocs(app)')} into ${ui_1.c.cyan(rel)}?\n` +
116
+ ` ${ui_1.c.dim('Y')} yes · ${ui_1.c.dim('n')} skip · or type another path\n ${ui_1.c.cyan('›')} `);
112
117
  if (!answer || /^y(es)?$/i.test(answer))
113
118
  return def;
114
119
  if (/^n(o)?$/i.test(answer))
@@ -120,18 +125,18 @@ async function resolveMainPath(cwd, candidates) {
120
125
  }
121
126
  function ensureImport(source) {
122
127
  if (source.includes("from '@t0.labs/daxta'") || source.includes('from "@t0.labs/daxta"')) {
123
- if (/\bdocs\b/.test(source) && /import\s*\{[^}]*\bdocs\b/.test(source))
128
+ if (/import\s*\{[^}]*\bapiDocs\b/.test(source))
124
129
  return source;
125
130
  return source.replace(/import\s*\{([^}]*)\}\s*from\s*['"]@t0\.labs\/daxta['"]\s*;?/, (full, names) => {
126
131
  let next = names;
127
- next = next.replace(/\bmountDaxtaDocs\b\s*,?\s*/g, '');
128
- if (/\bdocs\b/.test(next)) {
132
+ next = next.replace(/\b(mountDaxtaDocs|docs)\b\s*,?\s*/g, '');
133
+ if (/\bapiDocs\b/.test(next)) {
129
134
  return `import { ${next.trim().replace(/,$/, '')} } from '@t0.labs/daxta';`;
130
135
  }
131
136
  const trimmed = next.trim().replace(/,$/, '');
132
137
  return trimmed
133
- ? `import { ${trimmed}, docs } from '@t0.labs/daxta';`
134
- : `import { docs } from '@t0.labs/daxta';`;
138
+ ? `import { ${trimmed}, apiDocs } from '@t0.labs/daxta';`
139
+ : `import { apiDocs } from '@t0.labs/daxta';`;
135
140
  });
136
141
  }
137
142
  const lastImport = [...source.matchAll(/^import\s.+;?\s*$/gm)].pop();
@@ -143,17 +148,18 @@ function ensureImport(source) {
143
148
  }
144
149
  return `${IMPORT_LINE}\n\n${source}`;
145
150
  }
146
- function ensureDocsCall(source) {
147
- if (source.includes(MARKER) || source.includes('mountDaxtaDocs(')) {
148
- // upgrade legacy name in place
149
- return source.replace(/\bmountDaxtaDocs\s*\(/g, 'docs(');
151
+ function ensureApiDocsCall(source) {
152
+ if (source.includes(MARKER) || source.includes('mountDaxtaDocs(') || /\bdocs\s*\(/.test(source)) {
153
+ return source
154
+ .replace(/\bmountDaxtaDocs\s*\(/g, 'apiDocs(')
155
+ .replace(/\bdocs\s*\(/g, 'apiDocs(');
150
156
  }
151
157
  const constMatch = source.match(/(const|let|var)\s+(\w+)\s*=\s*await\s+NestFactory\.create\b[\s\S]*?;/);
152
158
  if (constMatch && constMatch.index != null) {
153
159
  const varName = constMatch[2];
154
160
  const insertAt = constMatch.index + constMatch[0].length;
155
161
  const indent = guessIndent(source, insertAt);
156
- const hook = `\n${indent}docs(${varName});`;
162
+ const hook = `\n${indent}apiDocs(${varName});`;
157
163
  return `${source.slice(0, insertAt)}${hook}${source.slice(insertAt)}`;
158
164
  }
159
165
  const assignMatch = source.match(/(\w+)\s*=\s*await\s+NestFactory\.create\b[\s\S]*?;/);
@@ -161,10 +167,10 @@ function ensureDocsCall(source) {
161
167
  const varName = assignMatch[1];
162
168
  const insertAt = assignMatch.index + assignMatch[0].length;
163
169
  const indent = guessIndent(source, insertAt);
164
- const hook = `\n${indent}docs(${varName});`;
170
+ const hook = `\n${indent}apiDocs(${varName});`;
165
171
  return `${source.slice(0, insertAt)}${hook}${source.slice(insertAt)}`;
166
172
  }
167
- throw new Error('Could not find `await NestFactory.create(...)` to inject docs(app). Add it manually near bootstrap.');
173
+ throw new Error('Could not find `await NestFactory.create(...)` to inject apiDocs(app). Add it manually near bootstrap.');
168
174
  }
169
175
  function guessIndent(source, index) {
170
176
  const lineStart = source.lastIndexOf('\n', index - 1) + 1;
@@ -172,42 +178,37 @@ function guessIndent(source, index) {
172
178
  const m = line.match(/^\s*/);
173
179
  return m?.[0] ?? ' ';
174
180
  }
175
- function injectDocs(filePath, dryRun = false) {
181
+ function injectApiDocs(filePath, dryRun = false) {
176
182
  const before = (0, fs_1.readFileSync)(filePath, 'utf8');
177
- if (before.includes(MARKER) && /import\s*\{[^}]*\bdocs\b/.test(before)) {
178
- return `already has docs() in ${filePath}`;
183
+ if (before.includes(MARKER) && /import\s*\{[^}]*\bapiDocs\b/.test(before)) {
184
+ return `already has apiDocs() in ${filePath}`;
179
185
  }
180
186
  let next = ensureImport(before);
181
- next = ensureDocsCall(next);
187
+ next = ensureApiDocsCall(next);
182
188
  if (next === before)
183
189
  return `no changes for ${filePath}`;
184
190
  if (!dryRun)
185
191
  (0, fs_1.writeFileSync)(filePath, next);
186
- return `injected docs() into ${path.relative(process.cwd(), filePath)}`;
192
+ return `injected apiDocs() into ${path.relative(process.cwd(), filePath)}`;
187
193
  }
188
- async function promptAndInjectMain(options = {}) {
194
+ /** Resolve which file to inject into (prompt / --main / --yes). Null = skip. */
195
+ async function resolveMainTarget(options = {}) {
189
196
  const cwd = options.cwd ?? process.cwd();
190
197
  const candidates = findMainCandidates(cwd);
191
- let target;
192
198
  if (options.mainPath) {
193
- target = path.isAbsolute(options.mainPath) ? options.mainPath : path.join(cwd, options.mainPath);
199
+ const target = path.isAbsolute(options.mainPath) ? options.mainPath : path.join(cwd, options.mainPath);
194
200
  if (!(0, fs_1.existsSync)(target))
195
201
  throw new Error(`File not found: ${target}`);
202
+ return target;
196
203
  }
197
- else if (options.yes) {
198
- target = candidates[0] ?? null;
204
+ if (options.yes) {
205
+ const target = candidates[0] ?? null;
199
206
  if (!target)
200
207
  throw new Error('No main.ts found; pass --main <path>');
208
+ return target;
201
209
  }
202
- else if (!process.stdin.isTTY) {
203
- target = candidates[0] ?? null;
204
- if (!target)
205
- return 'skip main inject (no TTY / no main.ts)';
206
- }
207
- else {
208
- target = await resolveMainPath(cwd, candidates);
210
+ if (!process.stdin.isTTY) {
211
+ return candidates[0] ?? null;
209
212
  }
210
- if (!target)
211
- return 'skipped main.ts inject';
212
- return injectDocs(target, options.dryRun);
213
+ return resolveMainPath(cwd, candidates);
213
214
  }
@@ -5,9 +5,11 @@ export type InstallOptions = {
5
5
  yes?: boolean;
6
6
  mainPath?: string;
7
7
  skipMain?: boolean;
8
+ /** Skip dramatic pacing delays */
9
+ fast?: boolean;
8
10
  };
9
11
  /**
10
- * Bootstrap: config, outDir, scripts, strip NODE_OPTIONS hacks,
11
- * prompt to inject `docs(app)` into main.ts.
12
+ * One-shot bootstrap with paced, colored steps.
13
+ * Prefer: `pnpm dlx @t0.labs/daxta install`
12
14
  */
13
15
  export declare function installDaxta(options?: InstallOptions): Promise<void>;