Keep configuration commands native and refine discovery direction

This commit is contained in:
2026-11-20 04:07:40 +00:00
parent 9e5cc60d09
commit f88c679a06
2 changed files with 71 additions and 58 deletions

View File

@@ -72,27 +72,27 @@ their old counterparts without a compatibility parser.
| --- | --- |
| `--config` | Application main-source selection on every configuration-consuming command, including the `promptkit` scope and family. Preserve explicit presence, including an empty value. |
| `--overlay` | Pass the supplied value to ConfigKit's `Options.Overlay`. At v1.2.1 this is a name, not a filesystem path: native empty/default selection and `overlays/NAME.yml` lookup apply. Do not add a second overlay interpreter or a fallback root. |
| Repeated `--promptkit-source PATH` | Replace the complete `promptkit_sources` list during ConfigKit loading with the selected files/directories in occurrence order, as a native override. Retain the useful existing file/directory classification, without comma splitting. |
| `--schema-dir` | Presence-aware override of application `schema_dir`. |
| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides; available on `serve` and application-scope configuration inspection. |
| `config ... --set POINTER=JSON` | Native override records for `app`, passed alongside explicitly supplied named-selector overrides with ConfigKit's native conflict handling. Enable the feature only on `app`. |
| `config diff --against-*` | Independent right-side selections and corresponding application-selector overrides, initialized independently rather than inherited from the left. |
| `--promptkit-source`, `--schema-dir` | Retention outside `config` is under review. Do not install either flag on configuration commands. |
| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides on `serve` only. |
| `config ... --set POINTER=JSON` | Native override records for `app`, passed directly to ConfigKit with native conflict handling. Enable the feature only on `app`. |
| Native `config diff --against-config`, `--against-overlay`, `--against-set` | Independent right-side selections and supported native overrides. No application-defined `--against-*` flags. |
| `--run-timeout DURATION` on `run` | `time.ParseDuration`, then unchanged into `RunRequest.OperationTimeout`. Positive values add the native operation budget; zero and negative values add none under PromptKit v0.23.3. No second application timer or positivity restriction. |
| Native `--llm-timeout-seconds` / `--timeout-seconds` | Integer per-attempt timeout through the ckprompt execution binding; no old duration conversion. |
Framework selectors (`promptkit-source`, `schema-dir`) apply to both config
scopes and to the native PromptKit family. Server selectors apply to the `app`
scope only. Provide each config selector with its matching `AgainstName`, such
as `against-promptkit-source`, `against-schema-dir`, or `against-addr`.
`run` accepts the framework selectors, request controls, and delivery controls;
it does not need server-only flags. `serve` accepts framework and server
selectors, not generation request controls. The configured `transient_retries`
value remains an engine default; the native execution flag overrides a request.
Install no application-defined flags or commands under `config`, including
source/schema flags, HTTP flags, or their `AgainstName` counterparts. Application
configuration inspection can use native `--set`; framework inspection obtains its
application settings through native `--config` and `--overlay` selection.
`run` accepts native configuration selection, request controls, and delivery
controls; `serve` retains HTTP controls and excludes generation request controls.
Settle any additional source/schema controls before implementing them. The
configured `transient_retries` remains an engine default; the native execution
flag overrides a request.
ConfigKit remains responsible for loading and all precedence, resolution, and
inspection semantics. Named selectors and native `--set` records may be combined
for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records
are rejected by ConfigKit; neither record order nor `--set` grants precedence.
inspection semantics. Native `--set` records can address nonconflicting paths;
duplicate and ancestor/descendant-overlapping records are rejected by ConfigKit.
Record order does not grant precedence.
Preserve native diagnostics without local conflict filtering, deduplication, or
merging. This also applies independently to each comparison side, including
`--against-set`. Keep cwd-relative application path values and source-relative
@@ -210,16 +210,18 @@ paths against the selected commits. Final composed behavior is checked in Stage
**Status: In progress; override decision resolved.** Adopt ConfigKit v1.2.1's
native conflict behavior; no upstream change or dependency upgrade is required.
The real-library `TestApplicationSelectorsPreservePresenceOrderAndEvidence`
reproduces `override.duplicate` for a named `schema_dir` override and a native
assignment to the same path. Revise its precedence expectation to assert native
conflict rejection and complete the stage's remaining checks. Configuration
package and metadata/selection-error tests were previously reported passing;
the obsolete precedence test has not yet been updated.
The former named-selector/`--set` precedence test is obsolete: configuration
commands no longer expose named application overrides. Cover native override
conflicts directly and HTTP named overrides on `serve`. Previously reported
configuration and metadata/selection-error checks do not establish completion
of these revised requirements.
**Discovery decision:** use native ConfigKit discovery presets and filename
conventions. Select the applicable presets and their order before completing
this stage; ConfigKit supplies no implicit universal search order.
Recommended order: `WorkingDirectory`, `UserConfigDirectory`, `HomeDirectory`,
then `UnixSystemDirectories`, with native filename defaults. Source/schema
flags and the configured framework-source interface remain under review.
**Primary files:** `internal/config/{load,document,settings}.go`, their tests,
and CLI application-loading/source-selector helpers.
@@ -236,12 +238,12 @@ and CLI application-loading/source-selector helpers.
ConfigKit's synchronous work can be forcibly interrupted.
2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed
CommandKit bindings retaining `Supplied.Set`. Convert only supplied
application selectors into correctly labeled ConfigKit overrides and pass
them together with native `Selection.Overrides`. Let ConfigKit validate all
records and report conflicts without selecting a winner locally. Keep
source-list order and replacement. Use ordinary OS classification for
explicitly supplied source paths; do not load framework definitions during
application inspection.
HTTP flags on `serve` into correctly labeled ConfigKit overrides. Configuration
commands pass only native `Selection.Overrides`; they have no named application
overrides. Let ConfigKit validate records and report conflicts. Do not load
framework definitions during application inspection. Defer source/schema flag
mapping and any change to configured source selection until that interface
decision is settled.
Preserve the existing nonnegative `int64` domain for HTTP byte limits,
including zero as unlimited; do not narrow it to a platform `int` or add a cap.
3. Keep schema, defaults, normalization, and domain validation inside the
@@ -252,14 +254,15 @@ and CLI application-loading/source-selector helpers.
`AppSettings.DefaultRenderFormat`, associated normalization/validation, and
the resulting `internal/config` dependency on `internal/format`. Strict
ConfigKit decoding handles the retired field; add no compatibility mapping.
5. Retain shared engine construction from resolved settings: one ordered
underlay per app selector, import-enabled file inputs, directory expansion
5. The existing engine construction uses one ordered underlay per configured
source, import-enabled file inputs, directory expansion
through `promptkit.DirectoryInputs`, no implicit main, existing schema base
and engine retry setting, and the default upstream bundle. Do not change
collection traversal, peer composition, or whole-record replacement.
`DirectoryInputs` retains explicit directory-selector support; collection
discovery continues through the file source's ConfigKit import globs for
`collection.yml` and `collection.yaml`.
and engine retry setting, and the default upstream bundle. Retention of the
general file/directory source-list interface is under review. Collection
discovery is already satisfied by a framework entry file with ConfigKit import
globs for `collection.yml` and `collection.yaml`; it does not require a separate
directory-source mechanism or repeated source flag. Preserve native composition
semantics for the selected inputs.
6. Use fresh application input per comparison side and invocation-owned state
under the native factory lifecycle; comparison may share that state without
sharing either side's selected values. Start without an engine/config cache:
@@ -270,10 +273,10 @@ and CLI application-loading/source-selector helpers.
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty
config/overlay selection, the selected native discovery presets and filename
conventions, a supplied zero or empty app override, individual named
and native overrides, nonconflicting combinations, and native duplicate and
conventions, supplied zero or empty HTTP overrides on `serve`, native `--set`
records, nonconflicting combinations, and native duplicate and
ancestor/descendant conflict rejection with diagnostic evidence. Also cover
ordered source replacement, normalized values and their evidence, and removal
the settled framework-source mapping, normalized values and their evidence, and removal
of `render_format`. Adapt existing search tests to the selected presets; reuse
import/source coverage without reproducing ConfigKit's exhaustive discovery or
composition matrix.
@@ -290,8 +293,8 @@ composition matrix.
2. Mark only the application scope as supporting temporary overrides, passing
those records through Stage 2. Retain the PromptKit scope's native disabled
override feature, including native capability checks for all-scope requests.
3. Install selectors with their scopes and independent `AgainstName` bindings
from the mapping above. Use fresh `NewInput` results, not shared pointers.
3. Install no application selectors or `AgainstName` bindings. Use native
configuration/overlay/override selection and fresh per-side input where needed.
Each comparison loader must consume that side's `Selection` and input;
do not cache the first engine into the second side. Delegate comparisons
to the returned native adapters instead of assembling a synthetic document.
@@ -311,7 +314,8 @@ composition matrix.
framework inspection uses sources selected by `--config`/`--overlay`; native
show and explain agree with the resolved callback values. Exercise native
root/index/escaped-key paths and redaction through representative integration
cases, independent left/right configs/overlays/selectors, and diff-check status 3.
cases, independent left/right configs/overlays/native overrides, and diff-check
status 3. Verify custom configuration flags and comparison counterparts are absent.
Verify app overrides are available and framework overrides are not emulated.
## Stage 4: Install Native PromptKit Resources, Requirements, And Preview
@@ -366,7 +370,8 @@ upstream analysis or rendering suite.
helpers in `internal/adapter/cli`, and run integration tests.
1. Declare exactly one required positional `PROMPT_ID` with CommandKit, using
shared app config/overlay/framework-selector bindings. Reuse
shared native config/overlay selection and any separately agreed source
controls. Reuse
`ckprompt.NewResourceFlags` for profile and session selection,
`NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for
all native execution controls. Do not install the reusable prompt flag:
@@ -508,8 +513,8 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
constants, legacy `render`/`inspect` commands, custom source DTOs and
inspection writers, custom prepared/definition presentation, and unused
CLI report helpers. Delete `internal/format` if it has no remaining consumers;
preserve `internal/report` for HTTP. Keep the useful source-to-underlay wiring
in its new CLI home, not a resurrected framework facade.
preserve `internal/report` for HTTP. Implement the settled framework-source
mapping through native APIs without resurrecting a framework facade.
2. Replace obsolete tests with selected native integration protection from
Stages 2–7. Retain architectural import boundaries and HTTP regression tests.
Do not make intentionally retired snapshots or aliases pass by retaining
@@ -520,7 +525,7 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
| Owner | Required changes |
| --- | --- |
| `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, stdout redirection, separate report files with optional format selection, statuses, completion, explicit smoke tests. Link upstream for standard family details. |
| `docs/config.md` | Native discovery presets and filename conventions; removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics. |
| `docs/config.md` | Native discovery presets and filename conventions; removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection imports and describe the settled framework-source settings. |
| `docs/integrations/subprocess.md` | Artifact-first execution, native reports and result availability, content-bearing metadata reports, stream capture, partial delivery, cancellation, and caller responsibility. Link exact CLI syntax rather than duplicate it. |
| `docs/operations.md` | Updated discovery/preview/execution workflow, explicit smoke-test effects, potentially sensitive reports, file retention, server process lifecycle, unchanged HTTP limits. |
| `docs/internal/overview.md`, `adapters.md`, `sources.md` | Actual component inventory and data flow, native acquisition boundaries, CLI result versus retained HTTP observation report, selector/engine lifecycle. |
@@ -604,7 +609,8 @@ current documentation links resolve. Migration examples match the built CLI.
policy and report checks, commits, and any remaining work accurately. Do
not mark the migration complete while required acceptance behavior is missing.
Discovery preset selection and ordering remain to be settled. The optional
Confirm the recommended discovery order and settle source/schema controls and
framework-source selection before completing affected stages. The optional
upstream selected-format accessor is not a migration dependency or completion gate.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md