From 7cddaf660872957b6bb3ddd965ea1d7ece17beb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacob=20Gro=C3=9F?= Date: Thu, 19 Nov 2026 14:32:35 +0100 Subject: [PATCH] Add JSON output for CLI automation --- README.md | 10 +++++++++- src/cli.ts | 36 +++++++++++++++++++----------------- src/formatters/index.ts | 4 +++- test/cli.test.ts | 10 ++++++++++ 4 files changed, 41 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 8e548d4..2f8550d 100644 --- a/README.md +++ b/README.md @@ -251,7 +251,7 @@ trace-engine-cli --help | Option | Type | Default | Description | | :--- | :--- | :--- | :--- | -| `-f, --format` | `'toon' \| 'md'` | `'toon'` | Output serialization format (`toon` or `md`) | +| `-f, --format` | `'toon' \| 'md' \| 'json'` | `'toon'` | Output serialization format | | `--time-range` | `string` | — | Filter window relative to trace start (e.g. `"3500,4200"`, `"3.5s,4.2s"`, `"100ms-500ms"`) | | `--absolute-timestamps` | `boolean` | `false` | Treat time ranges as raw absolute trace timestamps rather than relative to trace start | | `--trace-engine`| `string` | — | Path to a custom DevTools trace engine bundle | @@ -513,6 +513,14 @@ trace-engine-cli scan fixtures/ --name TracingStartedInBrowser --fields args.dat ### Markdown (`--format md`) Generates standard GitHub Flavored Markdown (GFM) tables and summary headings, ideal for terminal viewing or pasting into PR descriptions. +### JSON (`--format json`) +Prints the command result as JSON for scripts and automations. The default +overview omits its drill-down footer in this format. + +```bash +trace-engine-cli overview trace.json.gz --format json | jq '.mainThreadBreakdown.scriptingMs' +``` + --- ## Bundling Local DevTools Trace Engine diff --git a/src/cli.ts b/src/cli.ts index 712cce4..f088144 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -28,9 +28,11 @@ import { extractScheduling } from './engine/extractors/scheduling.js'; import { extractShifts } from './engine/extractors/shifts.js'; import { extractTasks } from './engine/extractors/tasks.js'; import { loadTraceFromFile } from './engine/loader.js'; -import { formatResult } from './formatters/index.js'; +import { type FormatOptions, formatResult } from './formatters/index.js'; import { parseTimeRange, parseTimeValue, resolveTimeRange } from './utils/filter.js'; +const DEFAULT_OUTPUT_FORMAT: FormatOptions['format'] = 'toon'; + /** * Splits a comma-separated argument into trimmed, non-empty tokens. */ @@ -52,9 +54,9 @@ export async function runCli(argv: string[]): Promise { .option('format', { alias: 'f', type: 'string', - choices: ['toon', 'md'] as const, - default: 'toon', - describe: 'Output format (toon or md)', + choices: ['toon', 'md', 'json'] satisfies FormatOptions['format'][], + default: DEFAULT_OUTPUT_FORMAT, + describe: 'Output format (toon, md, or json)', }) .option('trace-engine', { type: 'string', @@ -95,7 +97,7 @@ export async function runCli(argv: string[]): Promise { const isDefaultCmd = !args._.includes('overview'); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'overview', includeHint: isDefaultCmd, }), @@ -139,7 +141,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'insights', }), ); @@ -191,7 +193,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'tasks', }), ); @@ -237,7 +239,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'find', }), ); @@ -283,7 +285,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'profile', }), ); @@ -341,7 +343,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'diff', }), ); @@ -370,7 +372,7 @@ export async function runCli(argv: string[]): Promise { const result = extractScheduling(loaded, { timeRange }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'scheduling', }), ); @@ -421,7 +423,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'network', }), ); @@ -450,7 +452,7 @@ export async function runCli(argv: string[]): Promise { const result = extractInteractions(loaded, { timeRange }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'interactions', }), ); @@ -488,7 +490,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'shifts', }), ); @@ -554,7 +556,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'events', }), ); @@ -577,7 +579,7 @@ export async function runCli(argv: string[]): Promise { const result = extractNavigations(loaded); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'navigations', }), ); @@ -642,7 +644,7 @@ export async function runCli(argv: string[]): Promise { }); console.log( formatResult(result, { - format: args.format as 'toon' | 'md', + format: args.format, type: 'scan', }), ); diff --git a/src/formatters/index.ts b/src/formatters/index.ts index 4eca3ca..ed739f8 100644 --- a/src/formatters/index.ts +++ b/src/formatters/index.ts @@ -16,7 +16,7 @@ import { formatMarkdown } from './markdown.js'; import { formatToon } from './toon.js'; export interface FormatOptions { - format: 'toon' | 'md'; + format: 'toon' | 'md' | 'json'; type?: | 'overview' | 'insights' @@ -72,6 +72,8 @@ const NEXT_STEPS_HINT_MD = ` `.trim(); export function formatResult(data: unknown, options: FormatOptions): string { + if (options.format === 'json') return JSON.stringify(data, null, 2); + let output = ''; if (options.format === 'md') { output = formatMarkdown(data, options.type); diff --git a/test/cli.test.ts b/test/cli.test.ts index cdcded2..1a0820e 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -32,6 +32,16 @@ async function captureCliOutput(args: string[]): Promise { } describe('CLI Dispatcher', () => { + test('emits parseable JSON from the default overview command', async () => { + const fixture = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json'); + const args = ['node', 'trace-engine-cli', fixture, '--format', 'json']; + const output = await captureCliOutput(args); + const result: unknown = JSON.parse(output); + + assert.ok(result && typeof result === 'object' && 'mainUrl' in result); + assert.equal(result.mainUrl, 'https://example.com/test'); + }); + test('runs overview command by default for a trace file', async () => { const fixturePath = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json'); const output = await captureCliOutput(['node', 'trace-engine-cli', fixturePath]);