base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Record ordinary Go numeric types for CLI JSON inputs

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 00:54:51 +00:00
parent 3b6614605a
commit 5010f9a102
2 changed files with 52 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/roadmap/future.md
View File

@@ -104,9 +104,11 @@ public reusable `ckprompt` collections for standard and application-owned CLI
commands, composed through existing core bindings.
[Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar)
records the agreed canonical naming, scoped convenience aliases, integration
installation collection, and selected text/file input forms; those flag and alias
features need no core extension. Output-contract overrides and appended-message
flags are deferred below. These are CLI features; general-purpose helpers for
installation collection, selected text/file input forms, and CLI JSON number
policy. Numeric conversion uses ordinary Go types and a small internal helper
with policy comments. Those flag and alias features need no core extension.
Output-contract overrides and appended-message flags are deferred below.
These are CLI features; general-purpose helpers for
application-internal PromptKit use are outside CommandKit's ownership boundary.
- **Focused backend inspection.** Defer a standard backend detail command

56
docs/roadmap/promptkit-v0.19.0.md
View File

@@ -570,8 +570,8 @@ selection, JSON conventions for core serialization, original Go values for text
templates, no-template text rendering, universal formats, automatic selection,
safe YAML input conversion, aggregate configuration presentation, or joint
format delivery.
Report serialization does not settle the separate JSON input-number conversion
choices in OD-2 and OD-11.
Report serialization is separate from the agreed CLI JSON number policy in OD-2
and the remaining ConfigKit input-conversion decision in OD-11.
## Initial report implementation approach
@@ -749,6 +749,11 @@ Default tests remain offline and independent of real credentials.
- [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
inputs through the existing usage path, and do not leak state between runs.
Numeric decoding of provider JSON matches the selected strategy in OD-2.
- [ ] The small, centralized internal CLI JSON conversion helper documents the
numeric policy and its rationale in code comments. Cover integer boundaries,
decimal/exponent forms, nested objects/arrays, and range errors. Accept ordinary
floating-point approximation; do not add arbitrary-precision fallbacks or a
public/general-purpose numeric conversion API.
- [ ] The same public execution-flag collection works in a standard subcommand
and an application-owned command with its own typed input. Parsing, presence,
metadata, and selected subsets remain consistent; omitted retry values retain
@@ -888,10 +893,11 @@ The core ownership, JSON representation conventions, text printing/templates,
universal-format, automatic-selection, and joint format-delivery decisions are
now agreed above. Remaining details are listed under
[remaining core reporting implementation details](#remaining-core-reporting-implementation-details).
Outstanding integration choices are provider JSON decoding in OD-2, namespace
applicability in OD-3, empty comparison collections and binding design in OD-9,
and override grammar/acquisition details in OD-11. Exact helper names and report
layouts otherwise remain ordinary implementation choices, not unresolved scope.
Provider JSON number decoding is agreed in OD-2. Outstanding integration choices
are namespace applicability in OD-3, empty comparison collections and binding
design in OD-9, and override grammar/acquisition details in OD-11. Exact helper
names and report layouts otherwise remain ordinary implementation choices, not
unresolved scope.
### OD-1: Preview command and report presentation
@@ -921,9 +927,41 @@ dedicated preview template; a specialized template is not required for initial d
core APIs. Give validation and preview the applicable execution controls already
on smoke tests, and add a singleton `--llm-extra-params JSON` object option to
all three. Use native whole-map replacement, including native behavior for
empty maps. Specify JSON number decoding deliberately so supported values reach
PromptKit without accidental precision loss or new numeric guarantees. The
single-object form is selected over repeated key assignments.
empty maps. The single-object form is selected over repeated key assignments.
**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit.
Classify numbers by their written JSON syntax, not by whether their mathematical
value could be an integer:
- Integer syntax (no decimal point or exponent) becomes `int64`. Nonnegative
values above its range become `uint64` when representable. Reject integers
outside those ranges with a clear input error; do not fall back to floating point.
- Decimal or exponent syntax becomes `float64`: `42.0` and `1e3` remain floating
point even though their mathematical values are whole numbers. Accept ordinary
floating-point approximation; exact decimal representation is not required.
Report numeric range errors through the existing input-error path.
- Apply the same rules recursively inside JSON objects and arrays, preserving
other JSON value types. Decode with the standard library's `UseNumber` to avoid
premature floating-point conversion, then convert the temporary `json.Number`
values before handing the object to PromptKit.
Keep this in one small, centralized internal helper dedicated to CLI JSON input.
Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose
number conversion package, public conversion API, or extensible numeric framework
is selected. CommandKit is a Go library for Go applications and deliberately
accepts the precision and range of these Go types. It does not compensate for
their limits with alternate numeric representations.
**Required implementation comments:** document the syntax-based type selection,
the `int64`/`uint64`/`float64` choices, accepted floating-point approximation,
range-error behavior, and the rationale for this narrow boundary beside the
helper. The comments must make clear that ordinary Go numeric limits are an
intentional policy, not a missing feature to work around later.
This policy governs parsed CLI provider parameters, not application-supplied
runtime override values or core report serialization. ConfigKit input adaptation
remains a separate decision under OD-11; do not broaden the helper into a generic
conversion facility to anticipate that work.
Retain the authoritative-builder rule: standard flags seed a request, and an
application builder can return its complete replacement. Do not reapply CLI