fix: write CLI diagnostics to stderr so stdout carries results only

Author: johannschopplich

packages/cli/package.json

@@ -30,13 +30,13 @@
     "dist"
   ],
   "scripts": {
-    "dev": "node ./src/cli-entry.ts --help",
+    "dev": "node ./src/entry.ts --help",
     "build": "tsdown",
     "test": "vitest"
   },
   "dependencies": {
+    "ansis": "^4.3.1",
     "citty": "^0.2.2",
-    "consola": "^3.4.2",
     "tokenx": "^1.3.0"
   }
 }

packages/cli/src/conversion.ts

@@ -4,10 +4,10 @@ import type { InputSource } from './types.ts'
 import * as fsp from 'node:fs/promises'
 import * as path from 'node:path'
 import process from 'node:process'
-import { consola } from 'consola'
 import { estimateTokenCount } from 'tokenx'
 import { decodeStream, encode, encodeLines } from '../../toon/src/index.ts'
 import { jsonStreamFromEvents } from './json-from-events.ts'
+import * as log from './log.ts'
 import { formatInputLabel, readInput, readLinesFromSource } from './utils.ts'
 
 export async function encodeToToon(config: {
@@ -51,20 +51,19 @@ export async function encodeToToon(config: {
     if (config.output) {
       const relativeInputPath = formatInputLabel(config.input)
       const relativeOutputPath = path.relative(process.cwd(), config.output)
-      consola.success(`Encoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
+      log.success(`Encoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
     }
 
-    console.log()
-    consola.info(`Token estimates: ~${jsonTokens} (JSON) → ~${toonTokens} (TOON)`)
-    consola.success(`Saved ~${diff} tokens (-${percent}%)`)
+    log.info(`Token estimates: ~${jsonTokens} (JSON) → ~${toonTokens} (TOON)`)
+    log.success(`Saved ~${diff} tokens (-${percent}%)`)
   }
   else {
     await writeStream(encodeLines(data, encodeOptions), { outputPath: config.output, separator: '\n' })
 
     if (config.output) {
       const relativeInputPath = formatInputLabel(config.input)
       const relativeOutputPath = path.relative(process.cwd(), config.output)
-      consola.success(`Encoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
+      log.success(`Encoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
     }
   }
 }
@@ -90,7 +89,7 @@ export async function decodeToJson(config: {
   if (config.output) {
     const relativeInputPath = formatInputLabel(config.input)
     const relativeOutputPath = path.relative(process.cwd(), config.output)
-    consola.success(`Decoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
+    log.success(`Decoded \`${relativeInputPath}\` → \`${relativeOutputPath}\``)
   }
 }
 

packages/cli/src/cli-entry.ts packages/cli/src/entry.tspackages/cli/src/cli-entry.ts renamed to packages/cli/src/entry.ts

@@ -3,12 +3,12 @@ import type { InputSource } from './types.ts'
 import * as path from 'node:path'
 import process from 'node:process'
 import { defineCommand } from 'citty'
-import { consola } from 'consola'
 import { DEFAULT_DELIMITER } from '../../toon/src/index.ts'
 import { assertValidDelimiter } from '../../toon/src/shared/validation.ts'
 import pkg from '../package.json' with { type: 'json' }
 import { decodeToJson, encodeToToon } from './conversion.ts'
 import { formatError } from './format-error.ts'
+import * as log from './log.ts'
 import { detectMode } from './utils.ts'
 
 const { name, version } = pkg
@@ -76,17 +76,17 @@ export const mainCommand: CommandDef<ArgsDef> = defineCommand({
       : { type: 'file', path: path.resolve(input) }
     const outputPath = args.output ? path.resolve(args.output) : undefined
 
-    const indentSize = Number.parseInt(args.indent || '2', 10)
-    if (Number.isNaN(indentSize) || indentSize < 0) {
-      throw new Error(`Invalid indent value: ${args.indent}`)
-    }
+    try {
+      const indentSize = Number.parseInt(args.indent || '2', 10)
+      if (Number.isNaN(indentSize) || indentSize < 0) {
+        throw new Error(`Invalid indent value: ${args.indent}`)
+      }
 
-    const delimiter = args.delimiter || DEFAULT_DELIMITER
-    assertValidDelimiter(delimiter)
+      const delimiter = args.delimiter || DEFAULT_DELIMITER
+      assertValidDelimiter(delimiter)
 
-    const mode = detectMode(inputSource, args.encode, args.decode)
+      const mode = detectMode(inputSource, args.encode, args.decode)
 
-    try {
       if (mode === 'encode') {
         await encodeToToon({
           input: inputSource,
@@ -106,7 +106,7 @@ export const mainCommand: CommandDef<ArgsDef> = defineCommand({
       }
     }
     catch (error) {
-      consola.error(formatError(error, { isVerbose: args.verbose === true }))
+      log.error(formatError(error, { isVerbose: args.verbose === true }))
       // `process.exit` would discard whatever stdout has still buffered, which
       // truncates a piped conversion partway through
       process.exitCode = 1

packages/cli/src/index.ts

@@ -0,0 +1,24 @@
+import * as ansis from 'ansis'
+
+// Every level writes to stderr, so stdout carries results only
+
+export function error(message: string): void {
+  console.error(`${ansis.red('✖')} ${message}`)
+}
+
+export function warn(message: string): void {
+  console.error(`${ansis.yellow('⚠')} ${message}`)
+}
+
+export function info(message: string): void {
+  console.error(`${ansis.cyan('●')} ${message}`)
+}
+
+export function success(message: string): void {
+  console.error(`${ansis.green('✔')} ${message}`)
+}
+
+/** Separates report blocks – on stderr, like every level above. */
+export function blankLine(): void {
+  console.error('')
+}

packages/cli/src/log.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import { encode } from '../../toon/src/index.ts'
+import { version } from '../package.json' with { type: 'json' }
+import { runCliProcess, useTemporaryDirectories } from './utils.ts'
+
+const createDirectory = useTemporaryDirectories()
+
+// In-process runs observe neither citty's builtin flags, which `runMain` owns,
+// nor the exit code the shell sees.
+describe('toon CLI as a child process', () => {
+  it('prints its version', async () => {
+    const { stdout, exitCode } = await runCliProcess(['--version'])
+
+    expect(stdout).toBe(`${version}\n`)
+    expect(exitCode).toBe(0)
+  })
+
+  it('encodes a file and exits successfully', async () => {
+    const data = { items: ['alpha', 'beta'] }
+    const directory = createDirectory({ 'input.json': JSON.stringify(data) })
+
+    const { stdout, exitCode } = await runCliProcess(['input.json'], { cwd: directory })
+
+    expect(exitCode).toBe(0)
+    expect(stdout).toBe(`${encode(data)}\n`)
+  })
+
+  it('exits with a failure status for a missing input', async () => {
+    const directory = createDirectory()
+
+    const { stdout, stderr, exitCode } = await runCliProcess(['nonexistent.json'], { cwd: directory })
+
+    expect(exitCode).toBe(1)
+    expect(stdout).toBe('')
+    expect(stderr).toContain('nonexistent.json')
+  })
+})