Keep configuration commands native and refine discovery direction
This commit is contained in:
@@ -114,8 +114,8 @@ references use `--input-file`.
|
||||
Reuse applicable ckprompt resource, input, and execution bindings for `run`.
|
||||
Preserve explicit-value presence, including zero and empty values, and native
|
||||
repeated mapping semantics. Do not carry forward comma splitting or obsolete
|
||||
aliases merely because the old parser accepted them. Keep application source
|
||||
selectors, server settings, output destinations, and whole-operation deadlines
|
||||
aliases merely because the old parser accepted them. Keep application-only
|
||||
controls, including HTTP settings, reporting, and whole-operation deadlines,
|
||||
distinct from framework request controls.
|
||||
|
||||
Completion initially uses native command, flag, static-value, and path
|
||||
@@ -170,7 +170,11 @@ sources. Adopt native `--overlay` selection and upstream selection presence
|
||||
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
|
||||
not an arbitrary file path. Map selections through the application's ConfigKit
|
||||
loader rather than retaining the old flag parser as a compatibility layer.
|
||||
Preserve useful application source and server controls through appropriate selectors.
|
||||
Keep HTTP-related named flags on `serve`. The `config` family exposes only
|
||||
upstream commands and flags: add no application selectors or custom
|
||||
`--against-*` flags. Retain native `--against-config`, `--against-overlay`, and
|
||||
`--against-set` where supported. Retention of `--promptkit-source` and
|
||||
`--schema-dir` outside `config` remains under review.
|
||||
|
||||
For implicit application configuration discovery, adopt ConfigKit's built-in
|
||||
directory presets and their native filename conventions through `SearchConfig`.
|
||||
@@ -179,15 +183,18 @@ selection and ordering to the application; settle that choice before completing
|
||||
the loader migration. Selection, exhaustion, and selected-file errors remain
|
||||
native ConfigKit behavior.
|
||||
|
||||
The recommended preset order is `WorkingDirectory`, `UserConfigDirectory`,
|
||||
`HomeDirectory`, then `UnixSystemDirectories`, using each preset's native
|
||||
filename rules. This implements current-directory, user, then system discovery;
|
||||
the two user presets cover the platform configuration directory and home layout.
|
||||
|
||||
Enable temporary configuration overrides where the loader supports them,
|
||||
passing native override records into loading. Named selectors and `--set` may
|
||||
be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics
|
||||
for duplicate or ancestor/descendant-overlapping override records; `--set` does
|
||||
not supersede named selectors. Do not filter or merge conflicts locally.
|
||||
passing native override records into loading. ConfigKit owns rejection and
|
||||
diagnostics for duplicate or ancestor/descendant-overlapping records. Do not
|
||||
filter or merge conflicts locally.
|
||||
The reviewed PromptKit scope does not support these overrides; do not emulate
|
||||
them locally. Configuration comparison must support independent selections for
|
||||
both sides in both scopes, including corresponding application selectors where
|
||||
needed.
|
||||
both sides in both scopes through native flags alone.
|
||||
|
||||
Keep the established collection-discovery model: ConfigKit imports discover
|
||||
`collection.yml` and `collection.yaml` entry points; each independently
|
||||
@@ -335,9 +342,9 @@ documentation and examples describe the shipped interface. In particular:
|
||||
report availability, quiet behavior, and changed exit statuses.
|
||||
|
||||
The [implementation plan](implementation.md) owns task sequencing, concrete
|
||||
adapter mappings, verification steps, and sprint status. Discovery preset
|
||||
selection and ordering remain to be settled; the selected-format accessor is
|
||||
not a release prerequisite.
|
||||
adapter mappings, verification steps, and sprint status. Confirm the recommended
|
||||
discovery order and settle the remaining source/schema interface before completing
|
||||
the affected stages. The selected-format accessor is not a release prerequisite.
|
||||
|
||||
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||
the eventual breaking release version. This migration does not itself select
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user