@t0.labs/daxta 0.4.6 → 0.4.8
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 +37 -6
- package/assets/viewer.html +853 -61
- package/dist/build/build-spec.js +5 -0
- package/dist/catalog/index.d.ts +2 -2
- package/dist/catalog/index.js +10 -14
- package/dist/cli/install.js +41 -4
- package/dist/cli/tree.js +9 -30
- package/dist/cli/uninstall.js +1 -1
- package/dist/config.d.ts +18 -7
- package/dist/config.js +30 -1
- package/dist/index.d.ts +1 -1
- package/dist/serve/index.js +36 -4
- package/dist/serve/middleware.d.ts +1 -1
- package/dist/serve/middleware.js +70 -2
- package/dist/serve/paths.d.ts +2 -0
- package/dist/serve/paths.js +5 -0
- package/dist/serve/spec-utils.d.ts +8 -2
- package/dist/serve/spec-utils.js +37 -5
- package/dist/serve/viewer-store.d.ts +22 -0
- package/dist/serve/viewer-store.js +135 -0
- package/package.json +1 -1
package/dist/build/build-spec.js
CHANGED
|
@@ -43,6 +43,7 @@ const config_1 = require("../config");
|
|
|
43
43
|
const dto_fields_1 = require("../fields/dto-fields");
|
|
44
44
|
const path_util_1 = require("../path.util");
|
|
45
45
|
const paths_1 = require("../serve/paths");
|
|
46
|
+
const viewer_store_1 = require("../serve/viewer-store");
|
|
46
47
|
const METHOD_RANK = { get: 0, post: 1, put: 2, patch: 3, delete: 4 };
|
|
47
48
|
/** Re-map old/mis-templated hits onto Nest routes (or stronger heuristics). */
|
|
48
49
|
function canonicalizeHit(hit) {
|
|
@@ -706,6 +707,10 @@ function buildDaxtaSpec(options = {}) {
|
|
|
706
707
|
const existingHits = readJson((0, paths_1.getHitsJsonPath)());
|
|
707
708
|
const existingSpec = readJson((0, paths_1.getSpecJsonPath)());
|
|
708
709
|
const writeHtml = options.html !== false;
|
|
710
|
+
const seededStore = (0, viewer_store_1.ensureViewerStoreSeeded)();
|
|
711
|
+
if (seededStore && !options.silent) {
|
|
712
|
+
console.log(`Seeded ${seededStore} from envPresets`);
|
|
713
|
+
}
|
|
709
714
|
if (!hits.length) {
|
|
710
715
|
if (existingSpec && writeHtml && viewerTemplateNewerThanHtml()) {
|
|
711
716
|
const refreshed = applyViewerMeta(existingSpec);
|
package/dist/catalog/index.d.ts
CHANGED
|
@@ -15,7 +15,7 @@ export declare function declaredMethods(test?: string): string[] | null;
|
|
|
15
15
|
export declare function pathSegments(pathTemplate: string): string[];
|
|
16
16
|
/**
|
|
17
17
|
* Sidebar / export-tag folder segments for a path.
|
|
18
|
-
* Honors treeLayout, treeSkipParams,
|
|
18
|
+
* Honors treeLayout, treeSkipParams, and per-path overrides.
|
|
19
19
|
*/
|
|
20
20
|
export declare function treePathSegments(pathTemplate: string): string[];
|
|
21
21
|
export declare function viewerTreeConfig(): {
|
|
@@ -24,9 +24,9 @@ export declare function viewerTreeConfig(): {
|
|
|
24
24
|
docsPath: string;
|
|
25
25
|
treeLayout: TreeLayout;
|
|
26
26
|
treeSkipParams: boolean;
|
|
27
|
-
treeMaxDepth: number | null;
|
|
28
27
|
treePathOverrides: Record<string, string[]>;
|
|
29
28
|
exampleLabelStyle: "status-case" | "status-title-case" | "full";
|
|
29
|
+
envPresets: Record<string, import("../config").EnvPreset> | undefined;
|
|
30
30
|
};
|
|
31
31
|
export declare function operationTag(pathTemplate: string, method: string): string;
|
|
32
32
|
export declare function defaultTitle(method: string, pathTemplate: string): string;
|
package/dist/catalog/index.js
CHANGED
|
@@ -49,21 +49,17 @@ function applyLayout(parts, layout) {
|
|
|
49
49
|
}
|
|
50
50
|
return parts;
|
|
51
51
|
}
|
|
52
|
-
function applyFold(parts, skipParams
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
if (typeof maxDepth === 'number' && maxDepth > 0) {
|
|
60
|
-
next = next.slice(0, maxDepth);
|
|
61
|
-
}
|
|
62
|
-
return next;
|
|
52
|
+
function applyFold(parts, skipParams) {
|
|
53
|
+
if (!skipParams)
|
|
54
|
+
return parts;
|
|
55
|
+
const paramIdx = parts.findIndex((part) => part.startsWith('{'));
|
|
56
|
+
if (paramIdx < 0)
|
|
57
|
+
return parts;
|
|
58
|
+
return parts.slice(0, paramIdx);
|
|
63
59
|
}
|
|
64
60
|
/**
|
|
65
61
|
* Sidebar / export-tag folder segments for a path.
|
|
66
|
-
* Honors treeLayout, treeSkipParams,
|
|
62
|
+
* Honors treeLayout, treeSkipParams, and per-path overrides.
|
|
67
63
|
*/
|
|
68
64
|
function treePathSegments(pathTemplate) {
|
|
69
65
|
const config = (0, config_1.getConfig)();
|
|
@@ -75,7 +71,7 @@ function treePathSegments(pathTemplate) {
|
|
|
75
71
|
return exact;
|
|
76
72
|
const layout = (0, config_1.normalizeTreeLayout)(config.treeLayout);
|
|
77
73
|
const parts = applyLayout(pathTemplate.split('/').filter(Boolean), layout);
|
|
78
|
-
return applyFold(parts, config.treeSkipParams !== false
|
|
74
|
+
return applyFold(parts, config.treeSkipParams !== false);
|
|
79
75
|
}
|
|
80
76
|
function viewerTreeConfig() {
|
|
81
77
|
const config = (0, config_1.getConfig)();
|
|
@@ -85,9 +81,9 @@ function viewerTreeConfig() {
|
|
|
85
81
|
docsPath: config.docsPath,
|
|
86
82
|
treeLayout: (0, config_1.normalizeTreeLayout)(config.treeLayout),
|
|
87
83
|
treeSkipParams: config.treeSkipParams !== false,
|
|
88
|
-
treeMaxDepth: config.treeMaxDepth ?? null,
|
|
89
84
|
treePathOverrides: config.treePathOverrides,
|
|
90
85
|
exampleLabelStyle: config.exampleLabelStyle ?? 'status-title-case',
|
|
86
|
+
envPresets: config.envPresets,
|
|
91
87
|
};
|
|
92
88
|
}
|
|
93
89
|
function titleCase(value) {
|
package/dist/cli/install.js
CHANGED
|
@@ -116,9 +116,15 @@ export default defineConfig({
|
|
|
116
116
|
docsPath: '/docs',
|
|
117
117
|
treeLayout: 'role-resource',
|
|
118
118
|
treeSkipParams: true,
|
|
119
|
-
treeMaxDepth: null,
|
|
120
119
|
exampleLabelStyle: 'status-title-case',
|
|
121
120
|
fieldsFile: 'daxta/out/daxta.fields.json',
|
|
121
|
+
viewerStoreFile: 'daxta/viewer-store.json',
|
|
122
|
+
// Multi-base Try-it presets (docs env picker). Secrets stay in viewer-store / UI.
|
|
123
|
+
envPresets: {
|
|
124
|
+
local: { baseUrl: 'http://localhost:3000' },
|
|
125
|
+
staging: { baseUrl: 'https://api.staging.example.com' },
|
|
126
|
+
production: { baseUrl: 'https://api.example.com' },
|
|
127
|
+
},
|
|
122
128
|
});
|
|
123
129
|
`;
|
|
124
130
|
if (!dryRun)
|
|
@@ -127,7 +133,7 @@ export default defineConfig({
|
|
|
127
133
|
}
|
|
128
134
|
function ensureGitignore(cwd, dryRun) {
|
|
129
135
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
130
|
-
const entries = ['daxta/out/', '**/.jest.daxta.runtime.json'];
|
|
136
|
+
const entries = ['daxta/out/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
|
|
131
137
|
if (!(0, fs_1.existsSync)(gitignorePath)) {
|
|
132
138
|
if (!dryRun)
|
|
133
139
|
(0, fs_1.writeFileSync)(gitignorePath, `${entries.join('\n')}\n`);
|
|
@@ -147,6 +153,33 @@ function ensureGitignore(cwd, dryRun) {
|
|
|
147
153
|
(0, fs_1.writeFileSync)(gitignorePath, next);
|
|
148
154
|
return added.map((e) => `.gitignore += ${e}`);
|
|
149
155
|
}
|
|
156
|
+
const ENV_CANDIDATES = ['.env', '.env.local', '.env.development', '.env.development.local'];
|
|
157
|
+
/** Ensure DAXTA_DOCS is present (default true). Mirrors uninstall strip. */
|
|
158
|
+
function ensureEnvDaxtaDocs(cwd, dryRun) {
|
|
159
|
+
for (const name of ENV_CANDIDATES) {
|
|
160
|
+
const filePath = path.join(cwd, name);
|
|
161
|
+
if (!(0, fs_1.existsSync)(filePath))
|
|
162
|
+
continue;
|
|
163
|
+
const text = (0, fs_1.readFileSync)(filePath, 'utf8');
|
|
164
|
+
if (/^\s*DAXTA_DOCS\s*=/m.test(text))
|
|
165
|
+
return `${name} · DAXTA_DOCS already set`;
|
|
166
|
+
}
|
|
167
|
+
const targetName = ENV_CANDIDATES.find((name) => (0, fs_1.existsSync)(path.join(cwd, name))) ?? '.env';
|
|
168
|
+
const targetPath = path.join(cwd, targetName);
|
|
169
|
+
const created = !(0, fs_1.existsSync)(targetPath);
|
|
170
|
+
const line = 'DAXTA_DOCS=true';
|
|
171
|
+
if (!dryRun) {
|
|
172
|
+
if (created) {
|
|
173
|
+
(0, fs_1.writeFileSync)(targetPath, `${line}\n`);
|
|
174
|
+
}
|
|
175
|
+
else {
|
|
176
|
+
const text = (0, fs_1.readFileSync)(targetPath, 'utf8');
|
|
177
|
+
const next = text.endsWith('\n') || text.length === 0 ? `${text}${line}\n` : `${text}\n${line}\n`;
|
|
178
|
+
(0, fs_1.writeFileSync)(targetPath, next);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
return created ? `created ${targetName} (+ DAXTA_DOCS=true)` : `${targetName} += DAXTA_DOCS=true`;
|
|
182
|
+
}
|
|
150
183
|
function runPackageInstall(cwd, pm, version, dryRun) {
|
|
151
184
|
if (dryRun)
|
|
152
185
|
return 'dry-run';
|
|
@@ -218,6 +251,7 @@ async function installDaxta(options = {}) {
|
|
|
218
251
|
return 'already ignored';
|
|
219
252
|
return { summary: `${notes.length} entr${notes.length === 1 ? 'y' : 'ies'}`, details: notes };
|
|
220
253
|
}, { paceMs });
|
|
254
|
+
await (0, ui_1.step)('Set DAXTA_DOCS in env', () => ensureEnvDaxtaDocs(cwd, dryRun), { paceMs });
|
|
221
255
|
if (!options.skipMain) {
|
|
222
256
|
console.log('');
|
|
223
257
|
console.log(` ${ui_1.c.yellow(ui_1.c.bold('?'))} ${ui_1.c.bold('Nest entry')} ${ui_1.c.dim('— wire apiDocs(app)')}`);
|
|
@@ -300,16 +334,19 @@ async function installDaxta(options = {}) {
|
|
|
300
334
|
}
|
|
301
335
|
(0, ui_1.box)('Done', [
|
|
302
336
|
`${ui_1.c.green('✔')} DAxTA wired for ${ui_1.c.bold(project)}`,
|
|
303
|
-
`${ui_1.c.dim('env')} ${ui_1.c.cyan('DAXTA_DOCS=true')}
|
|
337
|
+
`${ui_1.c.dim('env')} ${ui_1.c.cyan('DAXTA_DOCS=true')} written (set ${ui_1.c.cyan('false')} to disable /docs)`,
|
|
304
338
|
`${ui_1.c.dim('tests')} run your usual script — Docs ready prints when Jest finishes`,
|
|
305
339
|
`${ui_1.c.dim('sidebar')} ${ui_1.c.cyan('daxta tree')} anytime to re-arrange folders`,
|
|
306
340
|
]);
|
|
307
341
|
const wired = testScript && pkg.scripts?.[testScript] ? testScript : null;
|
|
308
342
|
(0, ui_1.nextSteps)([
|
|
309
|
-
{ cmd: 'echo "DAXTA_DOCS=true" >> .env', why: 'enable /docs on the app port' },
|
|
310
343
|
{
|
|
311
344
|
cmd: wired ? `${pm} run ${wired}` : 'pnpm test',
|
|
312
345
|
why: 'unchanged entrypoint — DAxTA is a Jest plugin',
|
|
313
346
|
},
|
|
347
|
+
{
|
|
348
|
+
cmd: `${pm} start:dev`,
|
|
349
|
+
why: 'open /docs (DAXTA_DOCS already in .env)',
|
|
350
|
+
},
|
|
314
351
|
]);
|
|
315
352
|
}
|
package/dist/cli/tree.js
CHANGED
|
@@ -23,7 +23,7 @@ function normalizePathInput(raw) {
|
|
|
23
23
|
return trimmed;
|
|
24
24
|
return trimmed.startsWith('/') ? trimmed.replace(/\/+$/, '') || '/' : `/${trimmed.replace(/\/+$/, '')}`;
|
|
25
25
|
}
|
|
26
|
-
function layoutSegments(pathTemplate, layout, skipParams
|
|
26
|
+
function layoutSegments(pathTemplate, layout, skipParams) {
|
|
27
27
|
let parts = pathTemplate.split('/').filter(Boolean);
|
|
28
28
|
if (parts.length >= 3 && /^v\d+$/i.test(parts[0]) && layout === 'resource-role') {
|
|
29
29
|
parts = [parts[0], parts[2], parts[1], ...parts.slice(3)];
|
|
@@ -33,8 +33,6 @@ function layoutSegments(pathTemplate, layout, skipParams, maxDepth) {
|
|
|
33
33
|
if (idx >= 0)
|
|
34
34
|
parts = parts.slice(0, idx);
|
|
35
35
|
}
|
|
36
|
-
if (typeof maxDepth === 'number' && maxDepth > 0)
|
|
37
|
-
parts = parts.slice(0, maxDepth);
|
|
38
36
|
return parts;
|
|
39
37
|
}
|
|
40
38
|
function listKnownPaths() {
|
|
@@ -94,11 +92,11 @@ async function pickLayout(current) {
|
|
|
94
92
|
console.log(` ${ui_1.c.dim('sample')} ${ui_1.c.cyan(sample)}`);
|
|
95
93
|
console.log('');
|
|
96
94
|
console.log(` ${ui_1.c.cyan('1')} role → resource ${ui_1.c.dim('recommended')}`);
|
|
97
|
-
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'role-resource', true
|
|
95
|
+
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'role-resource', true))}`);
|
|
98
96
|
console.log(` ${ui_1.c.dim('v1 › admin › baskets (ops under baskets, not under {id})')}`);
|
|
99
97
|
console.log('');
|
|
100
98
|
console.log(` ${ui_1.c.cyan('2')} resource → role`);
|
|
101
|
-
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'resource-role', true
|
|
99
|
+
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'resource-role', true))}`);
|
|
102
100
|
console.log(` ${ui_1.c.dim('v1 › baskets › admin')}`);
|
|
103
101
|
console.log('');
|
|
104
102
|
console.log(` ${ui_1.c.cyan('3')} keep ${ui_1.c.dim(`(${current})`)}`);
|
|
@@ -127,22 +125,6 @@ async function pickSkipParams(current) {
|
|
|
127
125
|
return false;
|
|
128
126
|
throw new Error(`Unknown choice: ${answer}`);
|
|
129
127
|
}
|
|
130
|
-
async function pickMaxDepth(current) {
|
|
131
|
-
console.log('');
|
|
132
|
-
console.log(` ${ui_1.c.bold('Max folder depth')} ${ui_1.c.dim('(optional)')}`);
|
|
133
|
-
console.log(` ${ui_1.c.dim('Counts version. Empty = no limit beyond param fold.')}`);
|
|
134
|
-
console.log(` ${ui_1.c.dim('e.g. 3 → v1 / admin / baskets')}`);
|
|
135
|
-
const hint = current == null ? 'none' : String(current);
|
|
136
|
-
const answer = await prompt(` ${ui_1.c.yellow('?')} Depth ${ui_1.c.dim(`[${hint}]`)}\n ${ui_1.c.cyan('›')} `);
|
|
137
|
-
if (!answer)
|
|
138
|
-
return current ?? null;
|
|
139
|
-
if (/^(none|null|n)$/i.test(answer))
|
|
140
|
-
return null;
|
|
141
|
-
const n = Number(answer);
|
|
142
|
-
if (!Number.isFinite(n) || n < 1)
|
|
143
|
-
throw new Error(`Invalid depth: ${answer}`);
|
|
144
|
-
return Math.floor(n);
|
|
145
|
-
}
|
|
146
128
|
async function pickExampleStyle(current) {
|
|
147
129
|
console.log('');
|
|
148
130
|
console.log(` ${ui_1.c.bold('Example / scenario labels')}`);
|
|
@@ -164,9 +146,9 @@ async function pickExampleStyle(current) {
|
|
|
164
146
|
return 'full';
|
|
165
147
|
throw new Error(`Unknown style: ${answer}`);
|
|
166
148
|
}
|
|
167
|
-
function layoutChoicesFor(pathTemplate, layout, skipParams
|
|
168
|
-
const role = layoutSegments(pathTemplate, 'role-resource', skipParams
|
|
169
|
-
const resource = layoutSegments(pathTemplate, 'resource-role', skipParams
|
|
149
|
+
function layoutChoicesFor(pathTemplate, layout, skipParams) {
|
|
150
|
+
const role = layoutSegments(pathTemplate, 'role-resource', skipParams);
|
|
151
|
+
const resource = layoutSegments(pathTemplate, 'resource-role', skipParams);
|
|
170
152
|
const choices = [
|
|
171
153
|
{ id: 'role', label: 'role → resource', segments: role },
|
|
172
154
|
{ id: 'resource', label: 'resource → role', segments: resource },
|
|
@@ -174,8 +156,8 @@ function layoutChoicesFor(pathTemplate, layout, skipParams, maxDepth) {
|
|
|
174
156
|
];
|
|
175
157
|
return choices;
|
|
176
158
|
}
|
|
177
|
-
async function pickSegments(pathTemplate, layout, skipParams
|
|
178
|
-
const choices = layoutChoicesFor(pathTemplate, layout, skipParams
|
|
159
|
+
async function pickSegments(pathTemplate, layout, skipParams) {
|
|
160
|
+
const choices = layoutChoicesFor(pathTemplate, layout, skipParams);
|
|
179
161
|
console.log('');
|
|
180
162
|
console.log(` ${ui_1.c.bold('Override')} ${ui_1.c.cyan(pathTemplate)}`);
|
|
181
163
|
choices.forEach((choice, index) => {
|
|
@@ -226,9 +208,6 @@ async function runTreeWizard(options = {}) {
|
|
|
226
208
|
const skipParams = await pickSkipParams(config.treeSkipParams !== false);
|
|
227
209
|
(0, config_edit_1.upsertConfigValue)(configPath, 'treeSkipParams', skipParams ? 'true' : 'false');
|
|
228
210
|
console.log(` ${ui_1.c.green('✔')} treeSkipParams → ${ui_1.c.cyan(String(skipParams))}`);
|
|
229
|
-
const maxDepth = await pickMaxDepth(config.treeMaxDepth ?? null);
|
|
230
|
-
(0, config_edit_1.upsertConfigValue)(configPath, 'treeMaxDepth', maxDepth == null ? 'null' : String(maxDepth));
|
|
231
|
-
console.log(` ${ui_1.c.green('✔')} treeMaxDepth → ${ui_1.c.cyan(maxDepth == null ? 'null' : String(maxDepth))}`);
|
|
232
211
|
const exampleStyle = await pickExampleStyle(config.exampleLabelStyle ?? 'status-title-case');
|
|
233
212
|
(0, config_edit_1.upsertConfigValue)(configPath, 'exampleLabelStyle', (0, config_edit_1.formatTsString)(exampleStyle));
|
|
234
213
|
console.log(` ${ui_1.c.green('✔')} exampleLabelStyle → ${ui_1.c.cyan(exampleStyle)}`);
|
|
@@ -239,7 +218,7 @@ async function runTreeWizard(options = {}) {
|
|
|
239
218
|
if (customize && !/^n(o)?$/i.test(customize)) {
|
|
240
219
|
const pathTemplate = await pickPath(options.path);
|
|
241
220
|
if (pathTemplate) {
|
|
242
|
-
const segments = await pickSegments(pathTemplate, layout, skipParams
|
|
221
|
+
const segments = await pickSegments(pathTemplate, layout, skipParams);
|
|
243
222
|
if (segments?.length) {
|
|
244
223
|
const overrides = (0, config_edit_1.readTreePathOverrides)();
|
|
245
224
|
overrides[pathTemplate] = segments;
|
package/dist/cli/uninstall.js
CHANGED
|
@@ -72,7 +72,7 @@ function stripGitignore(cwd, dryRun) {
|
|
|
72
72
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
73
73
|
if (!(0, fs_1.existsSync)(gitignorePath))
|
|
74
74
|
return [];
|
|
75
|
-
const remove = new Set(['daxta/out/', 'daxta/', '**/.jest.daxta.runtime.json']);
|
|
75
|
+
const remove = new Set(['daxta/out/', 'daxta/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json']);
|
|
76
76
|
const before = (0, fs_1.readFileSync)(gitignorePath, 'utf8');
|
|
77
77
|
const lines = before.split(/\r?\n/);
|
|
78
78
|
const kept = lines.filter((line) => !remove.has(line.trim()));
|
package/dist/config.d.ts
CHANGED
|
@@ -8,9 +8,21 @@ export type SpecInfo = {
|
|
|
8
8
|
version?: string;
|
|
9
9
|
description?: string;
|
|
10
10
|
};
|
|
11
|
+
/** Named Try-it preset: own baseUrl + optional extra variables (tokens, etc.). */
|
|
12
|
+
export type EnvPreset = {
|
|
13
|
+
baseUrl: string;
|
|
14
|
+
/** Extra variables merged into the preset (baseUrl wins from EnvPreset.baseUrl). */
|
|
15
|
+
variables?: Record<string, string>;
|
|
16
|
+
};
|
|
11
17
|
export type DaxtaConfig = {
|
|
12
18
|
workspace?: string;
|
|
13
19
|
baseUrl?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Multi-base Try-it presets (local / staging / production, …).
|
|
22
|
+
* Seeded into the docs env picker and `daxta/viewer-store.json` on first write.
|
|
23
|
+
* Default: `{ local: { baseUrl } }` from `baseUrl`.
|
|
24
|
+
*/
|
|
25
|
+
envPresets?: Record<string, EnvPreset>;
|
|
14
26
|
controllersRoot?: string;
|
|
15
27
|
outDir?: string;
|
|
16
28
|
/**
|
|
@@ -24,12 +36,6 @@ export type DaxtaConfig = {
|
|
|
24
36
|
* Ops like POST …/{id}/lock sit under the parent resource. Default true.
|
|
25
37
|
*/
|
|
26
38
|
treeSkipParams?: boolean;
|
|
27
|
-
/**
|
|
28
|
-
* Max folder segments after (and including) version.
|
|
29
|
-
* e.g. 3 → v1 / admin / baskets — deeper segments are not folders.
|
|
30
|
-
* null/undefined = no extra limit (treeSkipParams still applies).
|
|
31
|
-
*/
|
|
32
|
-
treeMaxDepth?: number | null;
|
|
33
39
|
treePathOverrides?: Record<string, string[]>;
|
|
34
40
|
/**
|
|
35
41
|
* OpenAPI example + scenario labels:
|
|
@@ -41,6 +47,11 @@ export type DaxtaConfig = {
|
|
|
41
47
|
port?: number;
|
|
42
48
|
fieldsFile?: string;
|
|
43
49
|
docsPath?: string;
|
|
50
|
+
/**
|
|
51
|
+
* Persisted Try-it env/header store (survives rebuild). Default `daxta/viewer-store.json`.
|
|
52
|
+
* Served at `{docsPath}/env.json`. Keep out of git if it holds secrets.
|
|
53
|
+
*/
|
|
54
|
+
viewerStoreFile?: string;
|
|
44
55
|
testScript?: string;
|
|
45
56
|
testCommand?: string;
|
|
46
57
|
daxtaVersion?: string;
|
|
@@ -54,7 +65,7 @@ export type DaxtaConfig = {
|
|
|
54
65
|
includeHit?: (method: string, pathTemplate: string, test?: string) => boolean;
|
|
55
66
|
treePathSegments?: (pathTemplate: string) => string[] | undefined;
|
|
56
67
|
};
|
|
57
|
-
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath'>> & DaxtaConfig;
|
|
68
|
+
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath' | 'viewerStoreFile'>> & DaxtaConfig;
|
|
58
69
|
export declare function defineConfig(config: DaxtaConfig): DaxtaConfig;
|
|
59
70
|
export declare function normalizeTreeLayout(layout: TreeLayout | LegacyTreeLayout | undefined): TreeLayout;
|
|
60
71
|
export declare function resolveConfig(cwd?: string, overrides?: DaxtaConfig): ResolvedDaxtaConfig;
|
package/dist/config.js
CHANGED
|
@@ -48,12 +48,15 @@ const DEFAULTS = {
|
|
|
48
48
|
outDir: 'daxta/out',
|
|
49
49
|
treeLayout: 'role-resource',
|
|
50
50
|
treeSkipParams: true,
|
|
51
|
-
treeMaxDepth: null,
|
|
52
51
|
treePathOverrides: {},
|
|
53
52
|
exampleLabelStyle: 'status-title-case',
|
|
54
53
|
port: 5199,
|
|
55
54
|
fieldsFile: 'daxta.fields.json',
|
|
56
55
|
docsPath: '/docs',
|
|
56
|
+
viewerStoreFile: 'daxta/viewer-store.json',
|
|
57
|
+
envPresets: {
|
|
58
|
+
local: { baseUrl: 'http://localhost:3000' },
|
|
59
|
+
},
|
|
57
60
|
};
|
|
58
61
|
let cached = null;
|
|
59
62
|
function defineConfig(config) {
|
|
@@ -102,13 +105,39 @@ function resolveConfig(cwd = process.cwd(), overrides) {
|
|
|
102
105
|
merged.treeSkipParams = DEFAULTS.treeSkipParams;
|
|
103
106
|
if (merged.exampleLabelStyle == null)
|
|
104
107
|
merged.exampleLabelStyle = DEFAULTS.exampleLabelStyle;
|
|
108
|
+
merged.envPresets = normalizeEnvPresets(merged.envPresets, merged.baseUrl);
|
|
105
109
|
merged.controllersRoot = path.isAbsolute(merged.controllersRoot)
|
|
106
110
|
? merged.controllersRoot
|
|
107
111
|
: path.join(cwd, merged.controllersRoot);
|
|
108
112
|
merged.outDir = path.isAbsolute(merged.outDir) ? merged.outDir : path.join(cwd, merged.outDir);
|
|
109
113
|
merged.fieldsFile = path.isAbsolute(merged.fieldsFile) ? merged.fieldsFile : path.join(cwd, merged.fieldsFile);
|
|
114
|
+
merged.viewerStoreFile = path.isAbsolute(merged.viewerStoreFile)
|
|
115
|
+
? merged.viewerStoreFile
|
|
116
|
+
: path.join(cwd, merged.viewerStoreFile);
|
|
110
117
|
return merged;
|
|
111
118
|
}
|
|
119
|
+
function normalizeEnvPresets(presets, fallbackBaseUrl) {
|
|
120
|
+
const input = presets && typeof presets === 'object' ? presets : {};
|
|
121
|
+
const out = {};
|
|
122
|
+
for (const [name, preset] of Object.entries(input)) {
|
|
123
|
+
if (!name.trim() || !preset || typeof preset !== 'object')
|
|
124
|
+
continue;
|
|
125
|
+
const baseUrl = String(preset.baseUrl || fallbackBaseUrl).replace(/\/$/, '') || fallbackBaseUrl;
|
|
126
|
+
const variables = {};
|
|
127
|
+
if (preset.variables && typeof preset.variables === 'object') {
|
|
128
|
+
for (const [key, value] of Object.entries(preset.variables)) {
|
|
129
|
+
if (!key || key === 'baseUrl')
|
|
130
|
+
continue;
|
|
131
|
+
variables[key] = String(value ?? '');
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
out[name] = Object.keys(variables).length ? { baseUrl, variables } : { baseUrl };
|
|
135
|
+
}
|
|
136
|
+
if (!Object.keys(out).length) {
|
|
137
|
+
out.local = { baseUrl: String(fallbackBaseUrl).replace(/\/$/, '') || 'http://localhost:3000' };
|
|
138
|
+
}
|
|
139
|
+
return out;
|
|
140
|
+
}
|
|
112
141
|
function getConfig(forceReload = false) {
|
|
113
142
|
if (!cached || forceReload)
|
|
114
143
|
cached = resolveConfig();
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
1
|
+
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type EnvPreset, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
2
2
|
export { 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';
|
package/dist/serve/index.js
CHANGED
|
@@ -42,6 +42,7 @@ const config_1 = require("../config");
|
|
|
42
42
|
const paths_1 = require("./paths");
|
|
43
43
|
const proxy_1 = require("./proxy");
|
|
44
44
|
const spec_utils_1 = require("./spec-utils");
|
|
45
|
+
const viewer_store_1 = require("./viewer-store");
|
|
45
46
|
var middleware_1 = require("./middleware");
|
|
46
47
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return middleware_1.apiDocs; } });
|
|
47
48
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return middleware_1.apiDocsHandler; } });
|
|
@@ -54,6 +55,12 @@ function send(res, status, body, headers = {}) {
|
|
|
54
55
|
res.writeHead(status, headers);
|
|
55
56
|
res.end(body);
|
|
56
57
|
}
|
|
58
|
+
async function readBody(req) {
|
|
59
|
+
const chunks = [];
|
|
60
|
+
for await (const chunk of req)
|
|
61
|
+
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
62
|
+
return Buffer.concat(chunks);
|
|
63
|
+
}
|
|
57
64
|
/** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
58
65
|
function serveApiDocs(options = {}) {
|
|
59
66
|
const config = (0, config_1.getConfig)();
|
|
@@ -68,9 +75,7 @@ function serveApiDocs(options = {}) {
|
|
|
68
75
|
return;
|
|
69
76
|
}
|
|
70
77
|
if (url.pathname === '/__proxy') {
|
|
71
|
-
const
|
|
72
|
-
for await (const chunk of req)
|
|
73
|
-
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
78
|
+
const body = await readBody(req);
|
|
74
79
|
const headers = {};
|
|
75
80
|
for (const [key, value] of Object.entries(req.headers)) {
|
|
76
81
|
if (value == null)
|
|
@@ -84,11 +89,37 @@ function serveApiDocs(options = {}) {
|
|
|
84
89
|
target: url.searchParams.get('target') || '',
|
|
85
90
|
method,
|
|
86
91
|
headers,
|
|
87
|
-
body
|
|
92
|
+
body,
|
|
88
93
|
});
|
|
89
94
|
send(res, proxied.status, proxied.body, proxied.headers);
|
|
90
95
|
return;
|
|
91
96
|
}
|
|
97
|
+
if (url.pathname === `${docsBase}/env.json` || url.pathname === '/env.json') {
|
|
98
|
+
if (method === 'GET' || method === 'HEAD') {
|
|
99
|
+
const store = (0, viewer_store_1.readViewerEnvStore)();
|
|
100
|
+
send(res, 200, `${JSON.stringify(store ?? null)}\n`, {
|
|
101
|
+
'content-type': 'application/json; charset=utf-8',
|
|
102
|
+
'cache-control': 'no-store',
|
|
103
|
+
});
|
|
104
|
+
return;
|
|
105
|
+
}
|
|
106
|
+
if (method === 'PUT' || method === 'POST') {
|
|
107
|
+
try {
|
|
108
|
+
const raw = (await readBody(req)).toString('utf8');
|
|
109
|
+
const saved = (0, viewer_store_1.writeViewerEnvStore)(raw ? JSON.parse(raw) : null);
|
|
110
|
+
send(res, 200, `${JSON.stringify(saved)}\n`, {
|
|
111
|
+
'content-type': 'application/json; charset=utf-8',
|
|
112
|
+
'cache-control': 'no-store',
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
catch (error) {
|
|
116
|
+
send(res, 400, `${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n`, {
|
|
117
|
+
'content-type': 'application/json; charset=utf-8',
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
92
123
|
if (url.pathname === '/' || url.pathname === docsBase || url.pathname === `${docsBase}/`) {
|
|
93
124
|
if (!(0, fs_1.existsSync)(htmlPath)) {
|
|
94
125
|
send(res, 404, 'openapi.html not found. Run `daxta build` first.');
|
|
@@ -119,6 +150,7 @@ function serveApiDocs(options = {}) {
|
|
|
119
150
|
server.listen(port, '127.0.0.1', () => {
|
|
120
151
|
console.log(`DAxTA docs: http://127.0.0.1:${port}${docsBase}`);
|
|
121
152
|
console.log(`DAxTA OpenAPI: http://127.0.0.1:${port}${docsBase}/openapi.json`);
|
|
153
|
+
console.log(`DAxTA env: http://127.0.0.1:${port}${docsBase}/env.json`);
|
|
122
154
|
});
|
|
123
155
|
return server;
|
|
124
156
|
}
|
|
@@ -23,7 +23,7 @@ type LooseResponse = {
|
|
|
23
23
|
export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
|
|
24
24
|
/**
|
|
25
25
|
* Express / Nest handler that serves the DAxTA viewer under `/docs`
|
|
26
|
-
* (or `basePath`)
|
|
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
|
/**
|
package/dist/serve/middleware.js
CHANGED
|
@@ -6,6 +6,7 @@ const fs_1 = require("fs");
|
|
|
6
6
|
const paths_1 = require("./paths");
|
|
7
7
|
const proxy_1 = require("./proxy");
|
|
8
8
|
const spec_utils_1 = require("./spec-utils");
|
|
9
|
+
const viewer_store_1 = require("./viewer-store");
|
|
9
10
|
function requestPathname(req) {
|
|
10
11
|
const raw = req.originalUrl || req.url || req.path || '/';
|
|
11
12
|
try {
|
|
@@ -56,9 +57,47 @@ function bodyToBuffer(body) {
|
|
|
56
57
|
return Buffer.from(body);
|
|
57
58
|
return Buffer.from(JSON.stringify(body));
|
|
58
59
|
}
|
|
60
|
+
async function readRequestJson(req) {
|
|
61
|
+
if (req.body != null && req.body !== '') {
|
|
62
|
+
if (typeof req.body === 'string') {
|
|
63
|
+
try {
|
|
64
|
+
return JSON.parse(req.body);
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
return null;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
if (Buffer.isBuffer(req.body)) {
|
|
71
|
+
try {
|
|
72
|
+
return JSON.parse(req.body.toString('utf8'));
|
|
73
|
+
}
|
|
74
|
+
catch {
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
return req.body;
|
|
79
|
+
}
|
|
80
|
+
const stream = req;
|
|
81
|
+
if (typeof stream.on !== 'function' || stream.readableEnded)
|
|
82
|
+
return null;
|
|
83
|
+
const chunks = [];
|
|
84
|
+
await new Promise((resolve, reject) => {
|
|
85
|
+
stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
|
|
86
|
+
stream.on('end', () => resolve());
|
|
87
|
+
stream.on('error', reject);
|
|
88
|
+
});
|
|
89
|
+
if (!chunks.length)
|
|
90
|
+
return null;
|
|
91
|
+
try {
|
|
92
|
+
return JSON.parse(Buffer.concat(chunks).toString('utf8'));
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
59
98
|
/**
|
|
60
99
|
* Express / Nest handler that serves the DAxTA viewer under `/docs`
|
|
61
|
-
* (or `basePath`)
|
|
100
|
+
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
62
101
|
*/
|
|
63
102
|
function apiDocsHandler(options = {}) {
|
|
64
103
|
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
|
|
@@ -84,7 +123,36 @@ function apiDocsHandler(options = {}) {
|
|
|
84
123
|
}
|
|
85
124
|
const isDocsRoot = pathname === basePath || pathname === `${basePath}/`;
|
|
86
125
|
const isDocsSpec = pathname === `${basePath}/openapi.json`;
|
|
87
|
-
|
|
126
|
+
const isDocsEnv = pathname === `${basePath}/env.json`;
|
|
127
|
+
if (!isDocsRoot && !isDocsSpec && !isDocsEnv) {
|
|
128
|
+
next();
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
if (isDocsEnv) {
|
|
132
|
+
if (method === 'GET' || method === 'HEAD') {
|
|
133
|
+
const store = (0, viewer_store_1.readViewerEnvStore)();
|
|
134
|
+
write(res, 200, `${JSON.stringify(store ?? null)}\n`, {
|
|
135
|
+
'content-type': 'application/json; charset=utf-8',
|
|
136
|
+
'cache-control': 'no-store',
|
|
137
|
+
});
|
|
138
|
+
return;
|
|
139
|
+
}
|
|
140
|
+
if (method === 'PUT' || method === 'POST') {
|
|
141
|
+
try {
|
|
142
|
+
const payload = await readRequestJson(req);
|
|
143
|
+
const saved = (0, viewer_store_1.writeViewerEnvStore)(payload);
|
|
144
|
+
write(res, 200, `${JSON.stringify(saved)}\n`, {
|
|
145
|
+
'content-type': 'application/json; charset=utf-8',
|
|
146
|
+
'cache-control': 'no-store',
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
catch (error) {
|
|
150
|
+
write(res, 400, `${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n`, {
|
|
151
|
+
'content-type': 'application/json; charset=utf-8',
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
return;
|
|
155
|
+
}
|
|
88
156
|
next();
|
|
89
157
|
return;
|
|
90
158
|
}
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -2,6 +2,8 @@ export declare function getOutDir(): string;
|
|
|
2
2
|
export declare function getHtmlPath(): string;
|
|
3
3
|
export declare function getSpecJsonPath(): string;
|
|
4
4
|
export declare function getHitsJsonPath(): string;
|
|
5
|
+
/** Try-it env/headers — outside outDir so rebuild does not wipe it. */
|
|
6
|
+
export declare function getViewerStorePath(): string;
|
|
5
7
|
export declare function getViewerAssetPath(): string;
|
|
6
8
|
export declare function getFaviconAssetPath(): string;
|
|
7
9
|
export declare function getDocsBasePath(): string;
|
package/dist/serve/paths.js
CHANGED
|
@@ -37,6 +37,7 @@ exports.getOutDir = getOutDir;
|
|
|
37
37
|
exports.getHtmlPath = getHtmlPath;
|
|
38
38
|
exports.getSpecJsonPath = getSpecJsonPath;
|
|
39
39
|
exports.getHitsJsonPath = getHitsJsonPath;
|
|
40
|
+
exports.getViewerStorePath = getViewerStorePath;
|
|
40
41
|
exports.getViewerAssetPath = getViewerAssetPath;
|
|
41
42
|
exports.getFaviconAssetPath = getFaviconAssetPath;
|
|
42
43
|
exports.getDocsBasePath = getDocsBasePath;
|
|
@@ -54,6 +55,10 @@ function getSpecJsonPath() {
|
|
|
54
55
|
function getHitsJsonPath() {
|
|
55
56
|
return path.join(getOutDir(), 'hits.json');
|
|
56
57
|
}
|
|
58
|
+
/** Try-it env/headers — outside outDir so rebuild does not wipe it. */
|
|
59
|
+
function getViewerStorePath() {
|
|
60
|
+
return (0, config_1.getConfig)().viewerStoreFile;
|
|
61
|
+
}
|
|
57
62
|
function getViewerAssetPath() {
|
|
58
63
|
return path.join(__dirname, '..', '..', 'assets', 'viewer.html');
|
|
59
64
|
}
|
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
export declare function stripViewerExtensions(value: unknown): unknown;
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
4
|
-
*
|
|
3
|
+
* Build export path keys from sidebar tree segments (same order as docs),
|
|
4
|
+
* appending any `{param}` tail from the real URL so templates stay complete.
|
|
5
|
+
* Real URL is preserved on `x-daxta-url-path` when it differs.
|
|
6
|
+
*/
|
|
7
|
+
export declare function exportPathFromTree(urlPath: string, treeSegments: string[]): string;
|
|
8
|
+
/**
|
|
9
|
+
* Export OpenAPI with path keys ordered like the docs sidebar (`x-tree-segments`).
|
|
10
|
+
* Real request URLs stay on `x-daxta-url-path` when remapped.
|
|
5
11
|
*/
|
|
6
12
|
export declare function toTreeOrderedOpenApi(raw: Record<string, unknown>): Record<string, unknown>;
|
|
7
13
|
export declare function readStrippedOpenApiJson(): string | null;
|