2.0 KiB
G-064 lib.search machine-parsable returns (dict/json) and license surfacing option
Status: proposed Scope: src/modules/punk/mix/commandset/loadedlib-999999.0a1.0.tm, src/tests/modules/punk/mix/ (new testsuite), G-063 mapping module (as consumed) Goal: dev lib.search results are consumable by programs as well as humans: ansi-free -return options producing a Tcl dict and json with a documented structure (package name, available versions, present version as data fields), plus an option that surfaces each package's license indication in both the human table and the machine returns - so an agent piping 'dev lib.search -return json', or Tcl code using -return dict, needs no ansi stripping or list-position guessing. Acceptance: -return gains dict and json choices whose output contains no ansi escapes regardless of -highlight; the returned structure is documented in the command's punk::args definition; the present version is conveyed as a data field, not highlight markup; a license option adds a per-package license field (SPDX id, unresolved raw value, or unspecified - per the G-063 mapping) to table, dict and json returns; new tests pin dict/json shape, ansi-freeness, and the license option's unspecified fallback.
Context
Current -return choices are {table tableobject list lines}; list/lines embed ansi highlight codes unless -highlight 0 is passed, and the list structure is undocumented positional {name versions} pairs. G-049 (achieved 2026-07-10) established the machine-parsable -return dict pattern on punk::ns::cmdhelp; this goal applies it to lib.search and adds json for agent consumers (the G-017 piped-call direction).
Notes
- The dict/json returns do not depend on G-063 and can land first; the license field consumes G-063's mapping when present (progress tracked here if split).
- json serialization mechanism decided in the work: a quick sweep found no obvious json writer in-tree (options: minimal local serializer, vendored tcllib json::write, or a punk-native helper).