Skip to content

fix: return structured JSON from docs ask/chat when --json is active #202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ssh-esh merged 5 commits into from
Apr 17, 2026
Merged

fix: return structured JSON from docs ask/chat when --json is active #202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c38796e
fix: buffer chunks and return JSON in ask --json mode
ssh-esh Apr 17, 2026
9164175
fix: buffer chunks and return JSON in chat --json mode
ssh-esh Apr 17, 2026
b51ead7
test: add --json output test for docs ask
ssh-esh Apr 17, 2026
f5e65ac
test: add --json output test for docs chat
ssh-esh Apr 17, 2026
993a831
Merge branch 'main' into fix/docs-json-output-v2
ssh-esh Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/docs/ask.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ export function createAskCommand (deps: AskDeps = defaultDeps): OpaqueCommandHan
const spinner = interactive ? startSpinner(deps.stderr, 'Thinking…') : undefined

try {
if (parsed.options['json'] === true) {
const chunks: string[] = []
for await (const event of deps.docsAskStream(question, conversationId)) {
if (event.kind === 'chunk') chunks.push(event.text)
}
return { answer: chunks.join('') }
}

Copy link
Copy Markdown
Member

@JoshMock JoshMock Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A good approach for now.

If there was a way to separate the input stream into chunks by sentence, paragraph or section, each chunk could be streamed to stdout as one JSON object per line. That way an agent could choose to kill the NDJSON stream early once it has its answer, rather than wasting tokens on content it doesn't need. That's likely a much more complex solution, though, so this works. 👍

const gen = deps.docsAskStream(question, conversationId)
await streamAnswer(gen, renderMarkdown, deps.stdout, spinner)
} catch (err) {
Expand Down
18 changes: 18 additions & 0 deletions src/docs/chat.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,24 @@ export function createChatCommand (deps: ChatDeps = defaultDeps): OpaqueCommandH
const interactive = process.stderr.isTTY === true && parsed.options['json'] !== true

const conversationId = newUuid()

if (parsed.options['json'] === true) {
const chunks: string[] = []
try {
for await (const event of deps.docsAskStream(question, conversationId)) {
if (event.kind === 'chunk') chunks.push(event.text)
}
} catch (err) {
return {
error: {
code: 'docs_error',
message: err instanceof Error ? err.message : String(err),
},
}
}
return { answer: chunks.join('') }
}

await askQuestion(question, conversationId, deps, interactive ? startSpinner(deps.stderr, 'Thinking…') : undefined)

if (interactive) {
Expand Down
23 changes: 23 additions & 0 deletions test/docs/ask.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,29 @@ describe('createAskCommand', () => {
}
})

it('returns structured JSON with buffered answer when --json is active', async () => {
const captured: string[] = []
const origWrite = process.stdout.write
process.stdout.write = ((s: string) => { captured.push(s); return true }) as typeof process.stdout.write
try {
const cmd = createAskCommand({
docsAskStream: streamFrom(['chunk1', ' chunk2']),
stdout: { write: () => true },
stderr: { write: () => true },
})
cmd.option('--json', 'output as JSON')
cmd.exitOverride()
cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} })
await cmd.parseAsync(['what is elasticsearch', '--json'], { from: 'user' })

const output = captured.join('')
const parsed = JSON.parse(output)
assert.equal(parsed.answer, 'chunk1 chunk2')
} finally {
process.stdout.write = origWrite
}
})

it('stringifies non-Error thrown values into the docs_error message', async () => {
const stderrWrites: string[] = []
const cmd = createAskCommand({
Expand Down
24 changes: 24 additions & 0 deletions test/docs/chat.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,30 @@ describe('createChatCommand', () => {
}
})

it('returns structured JSON with buffered answer when --json is active', async () => {
const captured: string[] = []
const origWrite = process.stdout.write
process.stdout.write = ((s: string) => { captured.push(s); return true }) as typeof process.stdout.write
try {
const cmd = createChatCommand({
docsAskStream: streamFrom(['chunk1', ' chunk2']),
stdout: { write: () => true },
stderr: { write: () => true },
getStdin: () => Readable.from([]),
})
cmd.option('--json', 'output as JSON')
cmd.exitOverride()
cmd.configureOutput({ writeOut: () => {}, writeErr: () => {} })
await cmd.parseAsync(['what is elasticsearch', '--json'], { from: 'user' })

const output = captured.join('')
const parsed = JSON.parse(output)
assert.equal(parsed.answer, 'chunk1 chunk2')
} finally {
process.stdout.write = origWrite
}
})

it('stringifies non-Error thrown values into the stderr message', async () => {
const stderrWrites: string[] = []
const cmd = createChatCommand({
Expand Down