Plan native ConfigKit discovery conventions
This commit is contained in:
@@ -172,6 +172,13 @@ 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.
|
||||
|
||||
For implicit application configuration discovery, adopt ConfigKit's built-in
|
||||
directory presets and their native filename conventions through `SearchConfig`.
|
||||
Replace the legacy two-file search. ConfigKit deliberately leaves preset
|
||||
selection and ordering to the application; settle that choice before completing
|
||||
the loader migration. Selection, exhaustion, and selected-file errors remain
|
||||
native ConfigKit behavior.
|
||||
|
||||
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
|
||||
@@ -328,8 +335,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. There are no unresolved
|
||||
product decisions or selected-format accessor release prerequisite.
|
||||
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.
|
||||
|
||||
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||
the eventual breaking release version. This migration does not itself select
|
||||
|
||||
@@ -95,8 +95,10 @@ for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records
|
||||
are rejected by ConfigKit; neither record order nor `--set` grants 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, the existing discovery
|
||||
locations, and source-relative PromptKit resources.
|
||||
`--against-set`. Keep cwd-relative application path values and source-relative
|
||||
PromptKit resources. Replace the legacy discovery paths with ConfigKit's native
|
||||
directory presets and filename conventions; preset selection and ordering are
|
||||
an explicit application choice still to be settled.
|
||||
|
||||
### Outcomes And Delivery
|
||||
|
||||
@@ -215,14 +217,21 @@ 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.
|
||||
|
||||
**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.
|
||||
|
||||
**Primary files:** `internal/config/{load,document,settings}.go`, their tests,
|
||||
and CLI application-loading/source-selector helpers.
|
||||
|
||||
1. Retain one `configkit.Load` boundary returning its actual
|
||||
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
|
||||
replacement: explicit config presence chooses `File`, omission chooses the
|
||||
existing ordered `SearchConfig`, imports remain enabled, and overlay and
|
||||
override records go directly into ConfigKit. Preserve wrapped error identity.
|
||||
replacement: explicit config presence chooses `File`; omission chooses
|
||||
`SearchConfig` with the agreed native directory presets and their filename
|
||||
defaults. Replace the two literal legacy paths instead of preserving their
|
||||
precedence or limiting filenames to `config.yml`. Keep native optional-search
|
||||
exhaustion and selected-file error behavior. Imports remain enabled; overlay
|
||||
and override records go directly into ConfigKit. Preserve wrapped error identity.
|
||||
Respect the invocation context at the application boundary without claiming
|
||||
ConfigKit's synchronous work can be forcibly interrupted.
|
||||
2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed
|
||||
@@ -260,12 +269,14 @@ and CLI application-loading/source-selector helpers.
|
||||
acceptable and must not alter effective configuration.
|
||||
|
||||
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty
|
||||
config/overlay selection, a supplied zero or empty app override, individual named
|
||||
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
|
||||
ancestor/descendant conflict rejection with diagnostic evidence. Also cover
|
||||
ordered source replacement, normalized values and their evidence, and removal
|
||||
of `render_format`. Reuse existing import/search/source tests; do not reproduce
|
||||
ConfigKit's exhaustive composition matrix.
|
||||
of `render_format`. Adapt existing search tests to the selected presets; reuse
|
||||
import/source coverage without reproducing ConfigKit's exhaustive discovery or
|
||||
composition matrix.
|
||||
|
||||
## Stage 3: Install Native Configuration Scopes And Independent Comparison
|
||||
|
||||
@@ -509,7 +520,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` | 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/source/default semantics. |
|
||||
| `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. |
|
||||
@@ -519,7 +530,8 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
|
||||
4. Add a focused CLI migration guide under `docs/consumers/`, linked from the
|
||||
CLI/consumer overview. Cover positional prompt selection; `render` and
|
||||
`inspect` replacements; file versus literal inputs; repeated mappings without
|
||||
comma splitting; `--overlay` names; endpoint and timeout spelling/units;
|
||||
comma splitting; native configuration discovery; `--overlay` names; endpoint
|
||||
and timeout spelling/units;
|
||||
stdout redirection in place of output-file flags; separate native reports,
|
||||
optional report-format selection and upstream automatic rendering, and result
|
||||
availability; quiet behavior (omit quiet to capture main output); status
|
||||
@@ -592,8 +604,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.
|
||||
|
||||
There are no unresolved product questions. The optional upstream selected-format
|
||||
accessor is not a migration dependency or completion gate.
|
||||
Discovery preset selection and ordering remain to be settled. 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
|
||||
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||
|
||||
Reference in New Issue
Block a user