Skip to content

Commit 6d29675

Browse files
committed
Improve query hints and lazy GDrive loading
1 parent 05826d9 commit 6d29675

13 files changed

Lines changed: 152 additions & 110 deletions

‎src/bash_extractors.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { hasBareBackgroundOrNewline, hasUnquotedOperator, isRedirectAmpersand }
99
import { dropFileLineRangesIfChanged, getFileLineRanges } from './session.js'
1010
import { escapeRegExp } from './util.js'
1111
import { FALSY_ENV_VALUES } from './env.js'
12-
import { leadWithCommand, docSectionHint, grepLinesHint, configGetCommand, quotedArg, quotedArgs } from './hint_suggestion_guard.js'
12+
import { leadWithCommand, docSectionHint, grepLinesHint, configGetCommand, quotedArg, quotedArgs, xmlQueryHint } from './hint_suggestion_guard.js'
1313
import type { HintTarget } from './hint_target.js'
1414

1515
// Defined beside preToolPathDeclined, the rule it applies, so hint_target.ts can gate a path without pulling this module into the core bundle.
@@ -47,7 +47,7 @@ export function surgicalHintFor(hintPath: string, isEnv: boolean, isConfig: bool
4747
//
4848
// A config file's name goes where its format takes it: a JSON/YAML key to the query command, a TOML/INI table to `section` (measured, `config-get "cfg.toml" tool` exits 1 on a table while `section "cfg.toml::tool"` returns it), a .properties key to config-get. A JSON property is never put in a `section` slot: `token-goat section "package.json::name"` exits 1.
4949
const outline = outlineCommand(hintPath)
50-
if (isXml) return leadWithCommand('token-goat xml-outline ' + quotedArg(hintPath), 'to inspect structure, or `token-goat xml-query ' + quotedArgs(hintPath, '<selector>').join(' ') + '` to query specific nodes', reason)
50+
if (isXml) return xmlQueryHint(hintPath, reason)
5151
if (isEnv) return leadWithCommand(configGetCommand(hintPath, target.name), 'to read a specific variable', reason)
5252
// .properties has no outline extractor (measured 2026-10-03: `outline app.properties` exits 1), so it gets config-get for a key it holds and a grep otherwise.
5353
if (isConfig && /\.properties$/i.test(hintPath)) {

‎src/canonical_skill.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ Sub-agent briefs must carry this gate verbatim: a sub-agent inherits none of thi
7676

7777
### Keep command output surgical
7878

79+
- For JSON and XML, inspect structure with `token-goat json-outline file` or `token-goat xml-outline file`, then query narrowly: `token-goat json-query file 'items[*].id' --head 20` or `token-goat xml-query file 'root.child'`. XPath goes in `--xpath`, for example `token-goat xml-query file --xpath '//root/child'`. JSON queries print arrays and objects directly, so PowerShell `ConvertFrom-Json` wrappers are unnecessary; use `token-goat web-output` for browser results.
7980
- For searches, set the match budget you can use: `token-goat grep 'pattern' src --max-lines 20`. Patterns are regexes; invalid regex syntax (such as an unfinished `addText(`) falls back to literal substring matching, while overlong or potentially stalling patterns are refused. Add `-C 2` only when nearby lines matter; add `--symbol` only when you need the enclosing declaration.
8081
- For a long document, read a bounded section: `token-goat section "README.md::Install" --max-lines 40`. Add `--grep 'pattern'` to keep matching body lines with their nearest sub-heading.
8182
- To locate a heading without reading its body, use `token-goat section README.md --list --grep 'Install'`.

‎src/canonical_skill.ts‎

Lines changed: 81 additions & 79 deletions
Large diffs are not rendered by default.

‎src/cli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,6 @@ import { COMPRESSION_PROFILES, parseCompressionProfile } from './config_types.js
7575
import { applyIndexingPriority } from './process_priority.js'
7676
import { runStats } from './cli_stats.js'
7777
import { runDoctorAndExit, runDoctorChecks } from './cli_doctor.js'
78-
import { fetchDoc, getDocSections, formatSections, getSectionContent } from './gdrive.js'
7978
import { runBenchCommand } from './cli_bench.js'
8079
import { expandGlobs } from './cli_diagnostics.js'
8180
export { expandGlobs }
@@ -866,6 +865,7 @@ async function cmdGdriveSections(fileId: string, opts: { heading?: string; fresh
866865
if (!loadConfig().gdrive.enabled) {
867866
throw new CliError('gdrive-sections is disabled by gdrive.enabled = false in this install')
868867
}
868+
const { fetchDoc, getDocSections, formatSections, getSectionContent } = await import('./gdrive.js')
869869
const fetchOpts = { fresh: opts.fresh === true }
870870
// Fetch the whole doc once up front (honoring --fresh) so its raw byte size is available as the "full source" side of the bytes-saved calculation below, mirroring cmdSessionOutline/ cmdSessionSlice's convention. fetchDoc() always writes its result to the on-disk web-output cache before returning, so the getSectionContent/getDocSections calls below can safely pass `fresh: false` -- they read through to the entry this call just (re)populated, guaranteeing exactly one network fetch even with --fresh, instead of two.
871871
const text = await fetchDoc(fileId, fetchOpts)

‎src/hint_suggestion_guard.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,32 @@ export function configGetCommand(shownPath: string, key: string): string {
294294
return 'token-goat config-get ' + quotedArgs(shownPath, key).join(' ')
295295
}
296296

297+
/** A runnable json-query example that caps a nested array projection to 20 results. */
298+
export function jsonQueryExample(shownPath: string): string {
299+
return 'token-goat json-query ' + quotedArgs(shownPath, 'items[*].id').join(' ') + ' --head 20'
300+
}
301+
302+
/** A runnable XPath query, keeping the file and expression under one safe quote mark. */
303+
export function xmlXPathQueryCommand(shownPath: string, expression: string): string {
304+
const [fileArg, expressionArg] = quotedArgs(shownPath, expression)
305+
return 'token-goat xml-query ' + fileArg + ' --xpath ' + expressionArg
306+
}
307+
308+
/** Runnable XML structure, dot-path, and XPath commands for one file. */
309+
export function xmlQueryExamples(shownPath: string): { outline: string; path: string; xpath: string } {
310+
return {
311+
outline: 'token-goat xml-outline ' + quotedArg(shownPath),
312+
path: 'token-goat xml-query ' + quotedArgs(shownPath, 'root.child').join(' '),
313+
xpath: xmlXPathQueryCommand(shownPath, '//root/child'),
314+
}
315+
}
316+
317+
/** A shared XML read hint with accurate dot-path and XPath syntax. */
318+
export function xmlQueryHint(shownPath: string, reason = ''): string {
319+
const examples = xmlQueryExamples(shownPath)
320+
return leadWithCommand(examples.outline, `to inspect the element structure, then \`${examples.path}\` for a dot path or \`${examples.xpath}\` for XPath`, reason)
321+
}
322+
297323
/** The hint for one section of a prose document: `section` with the `outline` alternative only where it runs, and a plain grep for a file type neither serves. */
298324
export function docSectionHint(shownPath: string, heading: string, reason = ''): string {
299325
const nav = docNavigation(shownPath)

‎src/hint_target.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { getHintTargetCandidates, setHintTargetCandidates, type HintTargetCandid
99
import { commandPathIsTouchable } from './vscode_path_gate.js'
1010
import { extractMarkdownHeadings, formatHeadingTreeParts, type MarkdownHeading } from './hints/markdown_hints.js'
1111
import { extractQuickSymbolSamples } from './hooks_read.js'
12-
import { stripUnsafeSuggestions, leadWithCommand, grepLinesHint, configGetCommand, quotedArg, quotedArgs } from './hint_suggestion_guard.js'
12+
import { stripUnsafeSuggestions, leadWithCommand, grepLinesHint, configGetCommand, quotedArg, quotedArgs, xmlQueryHint } from './hint_suggestion_guard.js'
1313
import { getCompactedAt, markHintShown, wasHintShown } from './session.js'
1414
import { shortFingerprint } from './fingerprint.js'
1515
import { sessionStateKey, type HookEvent } from './hook_registry.js'
@@ -337,7 +337,7 @@ export function fileQueryHint(shownPath: string, reason = '', grepSubject = 'pat
337337
return leadWithCommand('token-goat ' + format + '-outline ' + quotedArg(shownPath), 'to list the top-level keys, then `token-goat ' + format + '-query ' + quotedArgs(shownPath, '<key>').join(' ') + '` to read one value', reason)
338338
}
339339
if (/\.(toml|ini|cfg)$/i.test(shownPath)) return leadWithCommand(configGetCommand(shownPath, '<key>'),'to read one value', reason)
340-
if (/\.(xml|csproj)$/i.test(shownPath)) return leadWithCommand('token-goat xml-outline ' + quotedArg(shownPath), 'to see the element structure, then `token-goat xml-query ' + quotedArgs(shownPath, '<path>').join(' ') + '` to read one element', reason)
340+
if (/\.(xml|csproj)$/i.test(shownPath)) return xmlQueryHint(shownPath, reason)
341341
return grepLinesHint('<' + grepSubject + '>', shownPath, reason)
342342
}
343343

‎src/hints/file_type_handler.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { findHtmlHeadingMatches } from '../languages/common.js'
44
import { fenceUntrustedFileContent } from '../injection_scan.js'
55
import { loadConfig } from '../config.js'
66
import { redactSecrets } from '../secret_redact.js'
7-
import { canQuoteArg, fencedCommand, quotedArg, quotedArgs } from '../hint_suggestion_guard.js'
7+
import { canQuoteArg, fencedCommand, quotedArg, quotedArgs, xmlQueryExamples, xmlXPathQueryCommand } from '../hint_suggestion_guard.js'
88
import { displaySafePath } from '../paths.js'
99

1010
export interface FileTypeResult {
@@ -270,14 +270,15 @@ export function handleTxt(filePath: string, content: string, contentLengthHint?:
270270
export function handleSvg(filePath: string, content: string, contentLengthHint?: number): FileTypeResult {
271271
const length = contentLengthHint ?? content.length
272272
if (length < FILE_TYPE_THRESHOLDS.svg) return { shouldBlock: false, message: '' }
273+
const groupQuery = xmlXPathQueryCommand(filePath, '//g[@id]')
273274

274275
if (previewUnavailable(content, length)) {
275276
return {
276277
shouldBlock: true,
277278
message: [
278279
`Large SVG file (${formatBytes(length)}) — too large to preview (exceeds the in-hook scan cap).`,
279280
`Inspect structure: token-goat xml-outline ${quotedArg(filePath)}`,
280-
`Query layers/elements: token-goat xml-query ${quotedArgs(filePath, '//g[@id]').join(' ')}`,
281+
`Query layers/elements with XPath: ${groupQuery}`,
281282
].join('\n'),
282283
}
283284
}
@@ -304,7 +305,7 @@ export function handleSvg(filePath: string, content: string, contentLengthHint?:
304305
`Large SVG/diagram file (${formatBytes(length)}) — raw coordinate paths flood context.`,
305306
preview ? fenceUntrustedFileContent(preview) : '',
306307
`Inspect structure: token-goat xml-outline ${quotedArg(filePath)}`,
307-
`Query elements: token-goat xml-query ${quotedArgs(filePath, '//g[@id]').join(' ')}`,
308+
`Query elements with XPath: ${groupQuery}`,
308309
`Search text labels: token-goat grep ${labelPattern} --glob ${labelGlob}`,
309310
].filter(Boolean).join('\n'),
310311
}
@@ -317,15 +318,16 @@ export function handleXml(filePath: string, content: string, contentLengthHint?:
317318
const threshold = ext === 'dtsx' || ext === 'ampkg' || ext === 'xaml' ? FILE_TYPE_THRESHOLDS[ext] : FILE_TYPE_THRESHOLDS.xml
318319
if (length < threshold) return { shouldBlock: false, message: '' }
319320

321+
const queries = xmlQueryExamples(filePath)
320322
const typeLabel = ext === 'dtsx' ? 'SSIS package XML (.dtsx)' : ext === 'ampkg' ? 'workflow package XML (.ampkg)' : ext === 'xaml' ? 'XAML (.xaml)' : 'XML'
321323

322324
if (previewUnavailable(content, length)) {
323325
return {
324326
shouldBlock: true,
325327
message: [
326328
`Large ${typeLabel} file (${formatBytes(length)}) — too large to preview (exceeds the in-hook scan cap).`,
327-
`Inspect structure: token-goat xml-outline ${quotedArg(filePath)}`,
328-
`Query nodes: token-goat xml-query ${quotedArgs(filePath, '<selector>').join(' ')}`,
329+
`Inspect structure: ${queries.outline}`,
330+
`Query nodes: ${queries.path} (dot path) or ${queries.xpath} (XPath)`,
329331
].join('\n'),
330332
}
331333
}
@@ -334,8 +336,8 @@ export function handleXml(filePath: string, content: string, contentLengthHint?:
334336
shouldBlock: true,
335337
message: [
336338
`Large ${typeLabel} file (${formatBytes(length)}).`,
337-
`Inspect hierarchy: token-goat xml-outline ${quotedArg(filePath)}`,
338-
`Query specific elements: token-goat xml-query ${quotedArgs(filePath, '<selector>').join(' ')}`,
339+
`Inspect hierarchy: ${queries.outline}`,
340+
`Query specific elements: ${queries.path} (dot path) or ${queries.xpath} (XPath)`,
339341
].join('\n'),
340342
}
341343
}

‎src/hooks_bash.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
import type { HookEvent } from './hook_registry.js'
44
import { registerHook } from './hook_registry.js'
5-
import { leadWithCommand, docSectionHint, fileSubject, nameSubject, quotedArg, quotedArgs, sentenceStart, stripUnsafeSuggestions } from './hint_suggestion_guard.js'
5+
import { leadWithCommand, docSectionHint, fileSubject, nameSubject, quotedArg, quotedArgs, sentenceStart, stripUnsafeSuggestions, jsonQueryExample, xmlQueryExamples } from './hint_suggestion_guard.js'
66
import { contextOutput, denyOutput, passOutput, getCwd } from './hooks_common.js'
77
import { applyHintTracking, classifyBashHint, meetsSavingsFloor, logSuppressedDetection } from './hint_stats.js'
88
import type { HookOutput } from './types.js'
@@ -377,8 +377,9 @@ function preBashHandlerInner(event: HookEvent): HookOutput {
377377
const { filePath, toolOrScript } = terminalXml
378378
recordStat('session_hint', 0, 0)
379379
const target = filePath ? displaySafePath(cdStripped ? resolveCdHintPath(rawCmd, filePath, hintCwd) : filePath) : '<file>'
380+
const queries = xmlQueryExamples(target)
380381
return pathHint(filePath ? [target] : [],
381-
`token-goat available for this file type, consider \`token-goat xml-query ${quotedArgs(target, '<xpath>').join(' ')}\` or \`token-goat xml-outline ${quotedArg(target)}\` first instead of terminal XML parsing (${nameSubject('tool', toolOrScript)}).`,
382+
`token-goat available for this file type. Use \`${queries.outline}\` to inspect structure, then \`${queries.path}\` for a dot path or \`${queries.xpath}\` for XPath instead of terminal XML parsing (${nameSubject('tool', toolOrScript)}).`,
382383
)
383384
}
384385

@@ -478,11 +479,11 @@ function preBashHandlerInner(event: HookEvent): HookOutput {
478479
if (psJsonPipe.filePath) {
479480
const hintPath = displaySafePath(cdStripped ? resolveCdHintPath(rawCmd, psJsonPipe.filePath, hintCwd) : psJsonPipe.filePath)
480481
return pathHint(hintPath,
481-
'PowerShell `ConvertFrom-Json` pipeline detected. Use `token-goat json-query ' + quotedArgs(hintPath, '<selector>').join(' ') + '` to extract fields directly without shell conversion scripts.',
482+
'PowerShell `ConvertFrom-Json` pipeline detected. Use `' + jsonQueryExample(hintPath) + '` to select and print JSON values directly (arrays and objects included) without PowerShell conversion scripts.',
482483
)
483484
}
484485
return contextOutput(
485-
'PowerShell `ConvertFrom-Json` pipeline detected. Use `token-goat json-query <file> "<selector>"` or `token-goat web-output` to extract fields directly.',
486+
'PowerShell `ConvertFrom-Json` pipeline detected. For a file, use `' + jsonQueryExample('file.json') + '` to select and print JSON values directly (arrays and objects included); use `token-goat web-output` for browser results.',
486487
)
487488
}
488489

‎src/hooks_read.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import { applyHintTracking, classifyReadHint, logSuppressedDetection, meetsSavin
1111
import { preToolPathDeclined } from './vscode_path_gate.js'
1212
import { detectHarness } from './bridges/registry.js'
1313
import { readHintCrossesRule } from './rewrite_permission.js'
14-
import { leadWithCommand, docNavigation, fencedCommand, fileSubject, nameSubject, quotedArg, quotedArgs, configGetCommand, sentenceStart } from './hint_suggestion_guard.js'
14+
import { leadWithCommand, docNavigation, fencedCommand, fileSubject, nameSubject, quotedArg, quotedArgs, configGetCommand, sentenceStart, xmlQueryHint } from './hint_suggestion_guard.js'
1515
import { escapeHintName, headingTreeParts, hintTarget, sectionOrRangeCommand, sliceCommand, sliceForPath, fileQueryHint, HINT_PLACEHOLDERS } from './hint_target.js'
1616
import { addSectionReadReceipt } from './served_extent.js'
1717
import { isNodeModulesPath } from './path_containment.js'
@@ -292,7 +292,7 @@ function surgicalHint(filePath: string, basename: string, lineCount: number, fil
292292
const isXmlFile = /\.(xml|dtsx|ampkg|xaml)$/i.test(basename) && !basename.toLowerCase().endsWith('-meta.xml')
293293

294294
if (isXmlFile) {
295-
return leadWithCommand(`token-goat xml-outline ${quotedArg(filePath)}`, `for structure, or \`token-goat xml-query ${quotedArgs(filePath, '<selector>').join(' ')}\` for nodes`)
295+
return xmlQueryHint(filePath)
296296
} else if (isDocFile && !docNavigation(filePath).section) {
297297
// A .txt file has no headings, so `section` exits 1 on it; grep is the command that runs.
298298
return fileQueryHint(filePath, '', 'pattern')
@@ -1547,7 +1547,7 @@ function preReadHandlerInner(event: HookEvent): HookOutput {
15471547
: sectionOrRangeCommand(shown, target)
15481548
}
15491549
const nudge = isXmlNudge
1550-
? `Note: token-goat available for this file type, consider xml-query/xml-outline first: \`token-goat xml-outline ${quotedArg(shown)}\` or \`token-goat xml-query ${quotedArgs(shown, '<selector>').join(' ')}\``
1550+
? `Note: token-goat available for this file type. ${xmlQueryHint(shown)}`
15511551
: isDocNudge
15521552
? `Note: token-goat available for this file type, consider ${docSectionExhausted ? 'outline' : 'section'} first: \`${docSectionCommand}\``
15531553
: isTestFile

‎tests/bash_deny_names_a_runnable_target.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -196,10 +196,11 @@ describe('surgicalHintFor with a resolved target', () => {
196196
)
197197
})
198198

199-
it('leaves the xml selector a placeholder: it is an XPath expression, not a name the index holds', () => {
199+
it('shows runnable XML path and XPath query examples', () => {
200200
const xml = surgicalHintFor('a.xml', false, false, false, true, real('root', 'section'))
201201
expect(xml.startsWith('Run `token-goat xml-outline "a.xml"`')).toBe(true)
202-
expect(xml).toContain('<selector>')
202+
expect(xml).toContain('token-goat xml-query "a.xml" "root.child"')
203+
expect(xml).toContain('token-goat xml-query "a.xml" --xpath "//root/child"')
203204
})
204205
})
205206

0 commit comments

Comments
 (0)