@kirrosh/zond 0.21.0 → 0.22.0

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.
Files changed (52) hide show
  1. package/CHANGELOG.md +110 -3
  2. package/README.md +26 -15
  3. package/package.json +10 -6
  4. package/src/cli/commands/ci-init.ts +12 -6
  5. package/src/cli/commands/completions.ts +176 -0
  6. package/src/cli/commands/db.ts +2 -1
  7. package/src/cli/commands/generate.ts +0 -1
  8. package/src/cli/commands/init/agents-md.ts +61 -0
  9. package/src/cli/commands/init/bootstrap.ts +79 -0
  10. package/src/cli/commands/init/skills.ts +45 -0
  11. package/src/cli/commands/init/templates/agents.md +73 -0
  12. package/src/cli/commands/init/templates/markdown.d.ts +4 -0
  13. package/src/cli/commands/init/templates/skills/scenarios.md +97 -0
  14. package/src/cli/commands/init/templates/skills/zond.md +184 -0
  15. package/src/cli/commands/init/templates/zond-config.yml +15 -0
  16. package/src/cli/commands/init.ts +124 -31
  17. package/src/cli/commands/probe-methods.ts +108 -0
  18. package/src/cli/commands/probe-validation.ts +124 -0
  19. package/src/cli/commands/run.ts +99 -10
  20. package/src/cli/commands/serve.ts +52 -19
  21. package/src/cli/commands/sync.ts +0 -1
  22. package/src/cli/commands/update.ts +1 -1
  23. package/src/cli/commands/use.ts +57 -0
  24. package/src/cli/index.ts +21 -609
  25. package/src/cli/program.ts +655 -0
  26. package/src/cli/version.ts +3 -0
  27. package/src/core/context/current.ts +35 -0
  28. package/src/core/diagnostics/db-analysis.ts +11 -2
  29. package/src/core/diagnostics/render-md.ts +112 -0
  30. package/src/core/generator/chunker.ts +14 -2
  31. package/src/core/generator/data-factory.ts +50 -19
  32. package/src/core/generator/guide-builder.ts +1 -1
  33. package/src/core/generator/openapi-reader.ts +18 -0
  34. package/src/core/generator/serializer.ts +11 -2
  35. package/src/core/generator/suite-generator.ts +106 -7
  36. package/src/core/meta/types.ts +0 -2
  37. package/src/core/parser/schema.ts +3 -1
  38. package/src/core/parser/types.ts +10 -1
  39. package/src/core/parser/variables.ts +90 -2
  40. package/src/core/parser/yaml-parser.ts +50 -1
  41. package/src/core/probe/method-probe.ts +197 -0
  42. package/src/core/probe/negative-probe.ts +657 -0
  43. package/src/core/reporter/console.ts +29 -3
  44. package/src/core/reporter/index.ts +2 -2
  45. package/src/core/reporter/json.ts +5 -2
  46. package/src/core/runner/assertions.ts +4 -1
  47. package/src/core/runner/executor.ts +132 -37
  48. package/src/core/runner/http-client.ts +40 -5
  49. package/src/core/runner/rate-limiter.ts +131 -0
  50. package/src/core/setup-api.ts +4 -1
  51. package/src/core/workspace/root.ts +94 -0
  52. package/src/db/schema.ts +4 -1
package/src/cli/index.ts CHANGED
@@ -1,626 +1,38 @@
1
1
  #!/usr/bin/env bun
2
2
 
3
- import { runCommand } from "./commands/run.ts";
4
- import { validateCommand } from "./commands/validate.ts";
5
- import { serveCommand } from "./commands/serve.ts";
6
- import { coverageCommand } from "./commands/coverage.ts";
7
- import { ciInitCommand } from "./commands/ci-init.ts";
8
- import { initCommand } from "./commands/init.ts";
9
- import { describeCommand } from "./commands/describe.ts";
10
- import { dbCommand } from "./commands/db.ts";
11
- import { requestCommand } from "./commands/request.ts";
12
- import { guideCommand } from "./commands/guide.ts";
13
- import { generateCommand } from "./commands/generate.ts";
14
- import { exportCommand } from "./commands/export.ts";
15
- import { syncCommand } from "./commands/sync.ts";
16
- import { updateCommand } from "./commands/update.ts";
17
- import { catalogCommand } from "./commands/catalog.ts";
3
+ import { CommanderError } from "commander";
4
+ import { buildProgram, preprocessArgv } from "./program.ts";
18
5
  import { printError } from "./output.ts";
19
- import { getRuntimeInfo } from "./runtime.ts";
20
- import { getDb } from "../db/schema.ts";
21
- import { findCollectionByNameOrId } from "../db/queries.ts";
22
- import type { ReporterName } from "../core/reporter/types.ts";
6
+ import { VERSION } from "./version.ts";
23
7
 
24
- import { version as pkgVersion } from "../../package.json";
25
- export const VERSION = pkgVersion;
8
+ export { VERSION };
26
9
 
27
- export interface ParsedArgs {
28
- command: string | undefined;
29
- positional: string[];
30
- flags: Record<string, string | boolean>;
31
- }
32
-
33
- /**
34
- * Strip MSYS/Git Bash automatic path conversion.
35
- * Git Bash on Windows converts "/foo" → "C:/Program Files/Git/foo".
36
- * Detect and reverse this for flags that expect API paths (e.g. --path /users).
37
- */
38
- const MSYS_PREFIX_RE = /^[A-Z]:[\\/](?:Program Files[\\/]Git|msys64|usr)[\\/]/i;
39
-
40
- function stripMsysPath(value: string): string {
41
- if (!MSYS_PREFIX_RE.test(value)) return value;
42
- // Extract the original path: "C:/Program Files/Git/products" → "/products"
43
- const stripped = value.replace(MSYS_PREFIX_RE, "/");
44
- return stripped;
45
- }
46
-
47
- /** Flags whose values are API paths, not filesystem paths — subject to MSYS fix */
48
- const API_PATH_FLAGS = new Set(["path", "json-path"]);
49
-
50
- export function parseArgs(argv: string[]): ParsedArgs {
51
- // argv: [bunPath, scriptPath, ...userArgs]
52
- const args = argv.slice(2);
53
- let command: string | undefined;
54
- const positional: string[] = [];
55
- const flags: Record<string, string | boolean> = {};
56
-
57
- let i = 0;
58
- while (i < args.length) {
59
- const arg = args[i]!;
60
-
61
- if (arg.startsWith("--")) {
62
- const eqIndex = arg.indexOf("=");
63
- if (eqIndex !== -1) {
64
- // --flag=value
65
- const key = arg.slice(2, eqIndex);
66
- let val = arg.slice(eqIndex + 1);
67
- if (API_PATH_FLAGS.has(key)) val = stripMsysPath(val);
68
- flags[key] = val;
69
- } else {
70
- const key = arg.slice(2);
71
- const next = args[i + 1];
72
- if (next !== undefined && !next.startsWith("-")) {
73
- flags[key] = API_PATH_FLAGS.has(key) ? stripMsysPath(next) : next;
74
- i++;
75
- } else {
76
- flags[key] = true;
77
- }
78
- }
79
- } else if (arg.startsWith("-") && arg.length === 2) {
80
- // Short flag: -h, -v
81
- flags[arg.slice(1)] = true;
82
- } else if (command === undefined) {
83
- command = arg;
84
- } else {
85
- positional.push(arg);
86
- }
87
-
88
- i++;
89
- }
90
-
91
- return { command, positional, flags };
92
- }
93
-
94
- function printUsage(): void {
95
- console.log(`zond - API Testing Platform
96
-
97
- Usage:
98
- zond run <path> Run API tests
99
- zond validate <path> Validate test files without running
100
- zond coverage Analyze API test coverage
101
- zond init Register a new API for testing
102
- zond describe <spec> Describe endpoints from OpenAPI spec
103
- zond db <subcommand> Query the test database
104
- zond request <method> <url> Send an ad-hoc HTTP request
105
- zond generate <spec> Generate test suites from OpenAPI spec
106
- zond guide <spec> Generate test generation guide from OpenAPI spec
107
- zond serve Start web dashboard
108
- zond ui Alias for 'serve --open' (start dashboard & open browser)
109
- zond ci init Generate CI/CD workflow (GitHub Actions, GitLab CI)
110
- zond export postman <path> Export YAML tests as Postman Collection v2.1
111
- zond catalog <spec> Generate API catalog (compact endpoint reference)
112
- zond sync <spec> Detect new/removed endpoints and generate tests for new ones
113
- zond update Check for updates and self-update the binary
114
-
115
- Options for 'run':
116
- --dry-run Show requests without sending them (exit code always 0)
117
- --env-var KEY=VALUE Inject env variable (repeatable, overrides env file)
118
- --api <name> Use API collection (resolves test path automatically)
119
- --env <name> Use environment file (.env.<name>.yaml)
120
- --report <format> Output format: console, json, junit (default: console)
121
- --timeout <ms> Override request timeout
122
- --bail Stop on first suite failure
123
- --no-db Do not save results to zond.db
124
- --db <path> Path to SQLite database file (default: zond.db)
125
- --auth-token <token> Auth token injected as {{auth_token}} variable
126
- --safe Run only GET tests (read-only, safe mode)
127
- --tag <tag> Filter suites by tag (repeatable, comma-separated, OR logic)
128
- --exclude-tag <tag> Exclude suites by tag (repeatable, comma-separated)
129
- --method <method> Filter tests by HTTP method (e.g. GET, POST)
130
-
131
- Options for 'init':
132
- --name <name> API name (auto-detected from spec title if omitted)
133
- --spec <path> Path to OpenAPI spec file
134
- --base-url <url> Override base URL
135
- --force Overwrite existing API collection
136
-
137
- Options for 'describe':
138
- --compact List all endpoints briefly
139
- --list-params List all unique parameters across all endpoints
140
- --method <method> HTTP method for single endpoint detail
141
- --path <path> Endpoint path for single endpoint detail
142
-
143
- Options for 'db':
144
- zond db collections List all API collections
145
- zond db runs [--limit N] List recent test runs
146
- zond db run <id> [--verbose] Show run details (--method GET, --status 403 to filter)
147
- zond db diagnose <id> Diagnose run failures (--limit N examples per group, --verbose for all)
148
- zond db compare <idA> <idB> Compare two runs
149
-
150
- Options for 'request':
151
- --header <H> Request header "Name: Value" (repeatable)
152
- --body <json> Request body (JSON string)
153
- --env <name> Environment for variable interpolation
154
- --api <name> Collection name (loads env from its directory)
155
- --json-path <path> Extract value from response (dot notation)
156
-
157
- Options for 'generate':
158
- --output <dir> Output directory for generated test files (required)
159
- --tag <tag> Generate only for endpoints with this tag
160
- --uncovered-only Skip endpoints already covered by existing tests
161
-
162
- Options for 'guide':
163
- --tests-dir <dir> Filter to uncovered endpoints only
164
- --tag <tag> Generate only for endpoints with this tag
165
-
166
- Options for 'coverage':
167
- --api <name> Use API collection (auto-resolves spec and tests dir)
168
- --spec <path> Path to OpenAPI spec (required unless --api used)
169
- --tests <dir> Path to test files directory (required unless --api used)
170
- --fail-on-coverage N Exit 1 when coverage percentage is below N (0–100)
171
- --run-id <number> Cross-reference with a test run for pass/fail/5xx breakdown
172
-
173
- Options for 'serve' / 'ui':
174
- --port <port> Server port (default: 8080)
175
- --host <host> Server host (default: 0.0.0.0)
176
- --db <path> Path to SQLite database file (default: zond.db)
177
- --open Open dashboard in browser after starting
178
- --watch Enable dev mode with hot reload (auto-refresh browser on file changes)
179
-
180
- Options for 'ci init':
181
- --github Generate GitHub Actions workflow
182
- --gitlab Generate GitLab CI config
183
- --dir <path> Project root directory (default: current directory)
184
- --force Overwrite existing CI config
185
-
186
- Options for 'export postman':
187
- --output <file> Output file path (default: collection.postman.json)
188
- --env <file> Also export .env.yaml as Postman environment
189
- --collection-name <name> Collection name (default: derived from path)
190
-
191
- Options for 'catalog':
192
- --output <dir> Output directory (default: current directory)
193
-
194
- Options for 'sync':
195
- --tests <dir> Path to test files directory (required)
196
- --dry-run Show what would be generated without writing files
197
- --tag <tag> Limit sync to endpoints with this tag
198
-
199
- Options for 'update':
200
- --check Only check for updates, do not download
201
-
202
- General:
203
- --json Output in JSON envelope format (available for all commands)
204
- --help, -h Show this help
205
- --version, -v Show version`);
206
- }
207
-
208
- const VALID_REPORTERS = new Set<string>(["console", "json", "junit"]);
209
-
210
- async function main(): Promise<number> {
211
- const { command, positional, flags } = parseArgs(process.argv);
212
- const jsonFlag = flags["json"] === true;
213
-
214
- // Help
215
- if (command === "help" || command === "--help" || flags["help"] === true || flags["h"] === true) {
216
- printUsage();
217
- return 0;
218
- }
219
-
220
- // Version
221
- if (command === "--version" || flags["version"] === true || flags["v"] === true) {
222
- console.log(`zond ${VERSION} (${getRuntimeInfo()})`);
223
- return 0;
224
- }
225
-
226
- if (!command) {
227
- printUsage();
228
- return 0;
229
- }
230
-
231
- switch (command) {
232
- case "run": {
233
- let path = positional[0];
234
- const apiFlag = typeof flags["api"] === "string" ? flags["api"] : undefined;
235
- if (!path && apiFlag) {
236
- try {
237
- getDb(typeof flags["db"] === "string" ? flags["db"] : undefined);
238
- const col = findCollectionByNameOrId(apiFlag);
239
- if (!col) { printError(`API '${apiFlag}' not found`); return 1; }
240
- path = col.test_path;
241
- } catch (err) {
242
- printError(`Failed to resolve --api: ${(err as Error).message}`);
243
- return 2;
244
- }
245
- }
246
- if (!path) {
247
- printError("Missing path argument. Usage: zond run <path> or zond run --api <name>");
248
- return 2;
249
- }
250
-
251
- const report = (flags["report"] as string) ?? "console";
252
- if (!VALID_REPORTERS.has(report)) {
253
- printError(`Unknown reporter: ${report}. Available: console, json, junit`);
254
- return 2;
255
- }
256
-
257
- const timeoutRaw = flags["timeout"];
258
- let timeout: number | undefined;
259
- if (typeof timeoutRaw === "string") {
260
- timeout = parseInt(timeoutRaw, 10);
261
- if (isNaN(timeout) || timeout <= 0) {
262
- printError(`Invalid timeout value: ${timeoutRaw}`);
263
- return 2;
264
- }
265
- }
266
-
267
- // Collect all --tag, --exclude-tag, and --env-var flags (parseArgs only stores last one, so re-parse)
268
- const tagValues: string[] = [];
269
- const excludeTagValues: string[] = [];
270
- const envVarValues: string[] = [];
271
- const rawRunArgs = process.argv.slice(2);
272
- for (let i = 0; i < rawRunArgs.length; i++) {
273
- const arg = rawRunArgs[i]!;
274
- if (arg === "--tag" && rawRunArgs[i + 1]) {
275
- tagValues.push(rawRunArgs[i + 1]!);
276
- i++;
277
- } else if (arg.startsWith("--tag=")) {
278
- tagValues.push(arg.slice("--tag=".length));
279
- } else if (arg === "--exclude-tag" && rawRunArgs[i + 1]) {
280
- excludeTagValues.push(rawRunArgs[i + 1]!);
281
- i++;
282
- } else if (arg.startsWith("--exclude-tag=")) {
283
- excludeTagValues.push(arg.slice("--exclude-tag=".length));
284
- } else if (arg === "--env-var" && rawRunArgs[i + 1]) {
285
- envVarValues.push(rawRunArgs[i + 1]!);
286
- i++;
287
- } else if (arg.startsWith("--env-var=")) {
288
- envVarValues.push(arg.slice("--env-var=".length));
289
- }
290
- }
291
- // Support comma-separated: --tag smoke,crud → ["smoke", "crud"]
292
- const tags = tagValues.flatMap(v => v.split(",")).filter(Boolean);
293
- const excludeTags = excludeTagValues.flatMap(v => v.split(",")).filter(Boolean);
294
-
295
- return runCommand({
296
- path,
297
- env: typeof flags["env"] === "string" ? flags["env"] : undefined,
298
- report: report as ReporterName,
299
- timeout,
300
- bail: flags["bail"] === true,
301
- noDb: flags["no-db"] === true,
302
- dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
303
- authToken: typeof flags["auth-token"] === "string" ? flags["auth-token"] : undefined,
304
- safe: flags["safe"] === true,
305
- tag: tags.length > 0 ? tags : undefined,
306
- excludeTag: excludeTags.length > 0 ? excludeTags : undefined,
307
- method: typeof flags["method"] === "string" ? flags["method"] : undefined,
308
- envVars: envVarValues.length > 0 ? envVarValues : undefined,
309
- dryRun: flags["dry-run"] === true,
310
- json: jsonFlag,
311
- });
312
- }
313
-
314
- case "validate": {
315
- const path = positional[0];
316
- if (!path) {
317
- printError("Missing path argument. Usage: zond validate <path>");
318
- return 2;
319
- }
320
-
321
- return validateCommand({ path, json: jsonFlag });
322
- }
323
-
324
- case "ui":
325
- case "serve": {
326
- const portRaw = flags["port"];
327
- let port: number | undefined;
328
- if (typeof portRaw === "string") {
329
- port = parseInt(portRaw, 10);
330
- if (isNaN(port) || port <= 0) {
331
- printError(`Invalid port value: ${portRaw}`);
332
- return 2;
333
- }
334
- }
335
- return serveCommand({
336
- port,
337
- host: typeof flags["host"] === "string" ? flags["host"] : undefined,
338
- dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
339
- watch: flags["watch"] === true,
340
- open: command === "ui" || flags["open"] === true,
341
- });
342
- }
343
-
344
- case "ci": {
345
- const ciSub = positional[0];
346
- if (ciSub !== "init") {
347
- printError("Usage: zond ci init [--github|--gitlab] [--force]");
348
- return 2;
349
- }
350
- let platform: "github" | "gitlab" | undefined;
351
- if (flags["github"] === true) platform = "github";
352
- else if (flags["gitlab"] === true) platform = "gitlab";
353
- return ciInitCommand({
354
- platform,
355
- force: flags["force"] === true,
356
- dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
357
- json: jsonFlag,
358
- });
359
- }
360
-
361
- case "coverage": {
362
- let spec = flags["spec"] as string | undefined;
363
- let tests = flags["tests"] as string | undefined;
364
- const coverageApiFlag = typeof flags["api"] === "string" ? flags["api"] : undefined;
365
-
366
- if (coverageApiFlag) {
367
- try {
368
- getDb(typeof flags["db"] === "string" ? flags["db"] : undefined);
369
- const col = findCollectionByNameOrId(coverageApiFlag);
370
- if (!col) { printError(`API '${coverageApiFlag}' not found`); return 1; }
371
- if (!spec && col.openapi_spec) spec = col.openapi_spec;
372
- if (!tests && col.test_path) tests = col.test_path;
373
- } catch (err) {
374
- printError(`Failed to resolve --api: ${(err as Error).message}`);
375
- return 2;
376
- }
377
- }
378
-
379
- if (typeof spec !== "string") {
380
- printError("Missing --spec <path>. Usage: zond coverage --spec <path> --tests <dir>");
381
- return 2;
382
- }
383
- if (typeof tests !== "string") {
384
- printError("Missing --tests <dir>. Usage: zond coverage --spec <path> --tests <dir>");
385
- return 2;
386
- }
387
- const failOnCoverageRaw = flags["fail-on-coverage"];
388
- let failOnCoverage: number | undefined;
389
- if (typeof failOnCoverageRaw === "string") {
390
- failOnCoverage = parseInt(failOnCoverageRaw, 10);
391
- if (isNaN(failOnCoverage) || failOnCoverage < 0 || failOnCoverage > 100) {
392
- printError(`Invalid --fail-on-coverage value: ${failOnCoverageRaw} (must be 0–100)`);
393
- return 2;
394
- }
395
- }
396
- const runIdRaw = flags["run-id"];
397
- let runId: number | undefined;
398
- if (typeof runIdRaw === "string") {
399
- runId = parseInt(runIdRaw, 10);
400
- if (isNaN(runId)) {
401
- printError(`Invalid --run-id value: ${runIdRaw} (must be a number)`);
402
- return 2;
403
- }
404
- }
405
- return coverageCommand({ spec, tests, failOnCoverage, runId, json: jsonFlag });
406
- }
407
-
408
- case "init": {
409
- return initCommand({
410
- name: typeof flags["name"] === "string" ? flags["name"] : undefined,
411
- spec: typeof flags["spec"] === "string" ? flags["spec"] : positional[0],
412
- baseUrl: typeof flags["base-url"] === "string" ? flags["base-url"] : undefined,
413
- dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
414
- force: flags["force"] === true,
415
- insecure: flags["insecure"] === true,
416
- dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
417
- json: jsonFlag,
418
- });
419
- }
420
-
421
- case "describe": {
422
- const specPath = positional[0];
423
- if (!specPath) {
424
- printError("Missing spec path. Usage: zond describe <spec> [--compact | --method <M> --path <P>]");
425
- return 2;
426
- }
427
- return describeCommand({
428
- specPath,
429
- compact: flags["compact"] === true,
430
- listParams: flags["list-params"] === true,
431
- method: typeof flags["method"] === "string" ? flags["method"] : undefined,
432
- path: typeof flags["path"] === "string" ? flags["path"] : undefined,
433
- json: jsonFlag,
434
- });
435
- }
436
-
437
- case "db": {
438
- const dbSub = positional[0];
439
- if (!dbSub) {
440
- printError("Missing subcommand. Usage: zond db <collections|runs|run|diagnose|compare> [args]");
441
- return 2;
442
- }
443
- const limitRaw = flags["limit"];
444
- let limit: number | undefined;
445
- if (typeof limitRaw === "string") {
446
- limit = parseInt(limitRaw, 10);
447
- if (isNaN(limit) || limit <= 0) limit = undefined;
448
- }
449
- const statusRaw = flags["status"];
450
- let statusFilter: number | undefined;
451
- if (typeof statusRaw === "string") {
452
- statusFilter = parseInt(statusRaw, 10);
453
- if (isNaN(statusFilter)) statusFilter = undefined;
454
- }
455
-
456
- return dbCommand({
457
- subcommand: dbSub,
458
- positional: positional.slice(1),
459
- limit,
460
- verbose: flags["verbose"] === true,
461
- dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
462
- json: jsonFlag,
463
- method: typeof flags["method"] === "string" ? flags["method"] : undefined,
464
- status: statusFilter,
465
- });
466
- }
467
-
468
- case "request": {
469
- const method = positional[0];
470
- const url = positional[1];
471
- if (!method || !url) {
472
- printError("Missing arguments. Usage: zond request <METHOD> <URL> [--header H] [--body JSON]");
473
- return 2;
474
- }
475
- // Collect all --header flags
476
- const headerValues: string[] = [];
477
- const rawArgs = process.argv.slice(2);
478
- for (let i = 0; i < rawArgs.length; i++) {
479
- const arg = rawArgs[i]!;
480
- if (arg === "--header" && rawArgs[i + 1]) {
481
- headerValues.push(rawArgs[i + 1]!);
482
- i++;
483
- } else if (arg.startsWith("--header=")) {
484
- headerValues.push(arg.slice("--header=".length));
485
- }
486
- }
487
-
488
- const timeoutRaw = flags["timeout"];
489
- let timeout: number | undefined;
490
- if (typeof timeoutRaw === "string") {
491
- timeout = parseInt(timeoutRaw, 10);
492
- if (isNaN(timeout) || timeout <= 0) timeout = undefined;
493
- }
494
-
495
- return requestCommand({
496
- method,
497
- url,
498
- headers: headerValues.length > 0 ? headerValues : undefined,
499
- body: typeof flags["body"] === "string" ? flags["body"] : undefined,
500
- timeout,
501
- env: typeof flags["env"] === "string" ? flags["env"] : undefined,
502
- api: typeof flags["api"] === "string" ? flags["api"] : undefined,
503
- jsonPath: typeof flags["json-path"] === "string" ? flags["json-path"] : undefined,
504
- dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
505
- json: jsonFlag,
506
- });
507
- }
508
-
509
- case "generate": {
510
- const specPath = positional[0];
511
- if (!specPath) {
512
- printError("Missing spec path. Usage: zond generate <spec> --output <dir> [--tag <tag>] [--uncovered-only] [--json]");
513
- return 2;
514
- }
515
- const output = typeof flags["output"] === "string" ? flags["output"] : undefined;
516
- if (!output) {
517
- printError("Missing --output <dir>. Usage: zond generate <spec> --output <dir>");
518
- return 2;
519
- }
520
- return generateCommand({
521
- specPath,
522
- output,
523
- tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
524
- uncoveredOnly: flags["uncovered-only"] === true,
525
- json: jsonFlag,
526
- });
527
- }
528
-
529
- case "catalog": {
530
- const specPath = positional[0];
531
- if (!specPath) {
532
- printError("Missing spec path. Usage: zond catalog <spec> [--output <dir>]");
533
- return 2;
534
- }
535
- return catalogCommand({
536
- specPath,
537
- output: typeof flags["output"] === "string" ? flags["output"] : undefined,
538
- json: jsonFlag,
539
- });
540
- }
541
-
542
- case "guide": {
543
- const specPath = positional[0];
544
- if (!specPath) {
545
- printError("Missing spec path. Usage: zond guide <spec> [--tests-dir <dir>] [--tag <tag>]");
546
- return 2;
547
- }
548
- return guideCommand({
549
- specPath,
550
- testsDir: typeof flags["tests-dir"] === "string" ? flags["tests-dir"] : undefined,
551
- tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
552
- json: jsonFlag,
553
- });
554
- }
555
-
556
- case "export": {
557
- const subcommand = positional[0];
558
- if (subcommand !== "postman") {
559
- printError(`Unknown export subcommand: ${subcommand ?? "(none)"}. Usage: zond export postman <path>`);
560
- return 2;
561
- }
562
- const testsPath = positional[1];
563
- if (!testsPath) {
564
- printError("Missing tests path. Usage: zond export postman <path> [--output <file>]");
565
- return 2;
566
- }
567
- return exportCommand({
568
- testsPath,
569
- output: typeof flags["output"] === "string" ? flags["output"] : "collection.postman.json",
570
- env: typeof flags["env"] === "string" ? flags["env"] : undefined,
571
- collectionName: typeof flags["collection-name"] === "string" ? flags["collection-name"] : undefined,
572
- json: jsonFlag,
573
- });
574
- }
575
-
576
- case "update":
577
- case "self-update": {
578
- return updateCommand({
579
- check: flags["check"] === true,
580
- json: jsonFlag,
581
- });
582
- }
583
-
584
- case "sync": {
585
- const specPath = positional[0];
586
- if (!specPath) {
587
- printError("Missing spec path. Usage: zond sync <spec> --tests <dir> [--dry-run] [--tag <tag>]");
588
- return 2;
589
- }
590
- const testsDir = typeof flags["tests"] === "string" ? flags["tests"] : undefined;
591
- if (!testsDir) {
592
- printError("Missing --tests <dir>. Usage: zond sync <spec> --tests <dir>");
593
- return 2;
10
+ async function main(): Promise<void> {
11
+ const program = buildProgram();
12
+ try {
13
+ await program.parseAsync(preprocessArgv(process.argv));
14
+ } catch (err) {
15
+ if (err instanceof CommanderError) {
16
+ // Help/version — commander prints content itself, exit 0
17
+ if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help") {
18
+ process.exitCode = 0;
19
+ return;
594
20
  }
595
- return syncCommand({
596
- specPath,
597
- testsDir,
598
- dryRun: flags["dry-run"] === true,
599
- tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
600
- json: jsonFlag,
601
- });
602
- }
603
-
604
- default: {
605
- printError(`Unknown command: ${command}`);
606
- printUsage();
607
- return 2;
21
+ // Unknown command / unknown option / missing argument — exit 2 (already printed by commander/showHelpAfterError)
22
+ process.exitCode = 2;
23
+ return;
608
24
  }
25
+ printError(err instanceof Error ? err.message : String(err));
26
+ process.exitCode = 2;
609
27
  }
610
28
  }
611
29
 
612
- // Only run when executed directly, not when imported
613
30
  const scriptPath = process.argv[1]?.replaceAll("\\", "/") ?? "";
614
31
  const metaFile = import.meta.filename?.replaceAll("\\", "/") ?? "";
615
32
  const isMain = scriptPath === metaFile
616
33
  || scriptPath.endsWith("cli/index.ts")
617
34
  || import.meta.main === true;
35
+
618
36
  if (isMain) {
619
- try {
620
- const code = await main();
621
- process.exitCode = code;
622
- } catch (err) {
623
- printError(err instanceof Error ? err.message : String(err));
624
- process.exitCode = 2;
625
- }
37
+ await main();
626
38
  }