From 5010f9a10268760b2140b3f7c2c0b856a7fb04da Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 00:54:51 +0000 Subject: [PATCH] Record ordinary Go numeric types for CLI JSON inputs --- docs/roadmap/future.md | 8 +++-- docs/roadmap/promptkit-v0.19.0.md | 56 ++++++++++++++++++++++++++----- 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 84df2ea..d8d4828 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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 diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index 079b93a..5f38217 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -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