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.
|
loader rather than retaining the old flag parser as a compatibility layer.
|
||||||
Preserve useful application source and server controls through appropriate selectors.
|
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,
|
Enable temporary configuration overrides where the loader supports them,
|
||||||
passing native override records into loading. Named selectors and `--set` may
|
passing native override records into loading. Named selectors and `--set` may
|
||||||
be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics
|
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.
|
report availability, quiet behavior, and changed exit statuses.
|
||||||
|
|
||||||
The [implementation plan](implementation.md) owns task sequencing, concrete
|
The [implementation plan](implementation.md) owns task sequencing, concrete
|
||||||
adapter mappings, verification steps, and sprint status. There are no unresolved
|
adapter mappings, verification steps, and sprint status. Discovery preset
|
||||||
product decisions or selected-format accessor release prerequisite.
|
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 [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||||
the eventual breaking release version. This migration does not itself select
|
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.
|
are rejected by ConfigKit; neither record order nor `--set` grants precedence.
|
||||||
Preserve native diagnostics without local conflict filtering, deduplication, or
|
Preserve native diagnostics without local conflict filtering, deduplication, or
|
||||||
merging. This also applies independently to each comparison side, including
|
merging. This also applies independently to each comparison side, including
|
||||||
`--against-set`. Keep cwd-relative application path values, the existing discovery
|
`--against-set`. Keep cwd-relative application path values and source-relative
|
||||||
locations, and source-relative PromptKit resources.
|
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
|
### 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;
|
package and metadata/selection-error tests were previously reported passing;
|
||||||
the obsolete precedence test has not yet been updated.
|
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,
|
**Primary files:** `internal/config/{load,document,settings}.go`, their tests,
|
||||||
and CLI application-loading/source-selector helpers.
|
and CLI application-loading/source-selector helpers.
|
||||||
|
|
||||||
1. Retain one `configkit.Load` boundary returning its actual
|
1. Retain one `configkit.Load` boundary returning its actual
|
||||||
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
|
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
|
||||||
replacement: explicit config presence chooses `File`, omission chooses the
|
replacement: explicit config presence chooses `File`; omission chooses
|
||||||
existing ordered `SearchConfig`, imports remain enabled, and overlay and
|
`SearchConfig` with the agreed native directory presets and their filename
|
||||||
override records go directly into ConfigKit. Preserve wrapped error identity.
|
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
|
Respect the invocation context at the application boundary without claiming
|
||||||
ConfigKit's synchronous work can be forcibly interrupted.
|
ConfigKit's synchronous work can be forcibly interrupted.
|
||||||
2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed
|
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.
|
acceptable and must not alter effective configuration.
|
||||||
|
|
||||||
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty
|
**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
|
and native overrides, nonconflicting combinations, and native duplicate and
|
||||||
ancestor/descendant conflict rejection with diagnostic evidence. Also cover
|
ancestor/descendant conflict rejection with diagnostic evidence. Also cover
|
||||||
ordered source replacement, normalized values and their evidence, and removal
|
ordered source replacement, normalized values and their evidence, and removal
|
||||||
of `render_format`. Reuse existing import/search/source tests; do not reproduce
|
of `render_format`. Adapt existing search tests to the selected presets; reuse
|
||||||
ConfigKit's exhaustive composition matrix.
|
import/source coverage without reproducing ConfigKit's exhaustive discovery or
|
||||||
|
composition matrix.
|
||||||
|
|
||||||
## Stage 3: Install Native Configuration Scopes And Independent Comparison
|
## 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 |
|
| 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/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/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/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. |
|
| `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
|
4. Add a focused CLI migration guide under `docs/consumers/`, linked from the
|
||||||
CLI/consumer overview. Cover positional prompt selection; `render` and
|
CLI/consumer overview. Cover positional prompt selection; `render` and
|
||||||
`inspect` replacements; file versus literal inputs; repeated mappings without
|
`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,
|
stdout redirection in place of output-file flags; separate native reports,
|
||||||
optional report-format selection and upstream automatic rendering, and result
|
optional report-format selection and upstream automatic rendering, and result
|
||||||
availability; quiet behavior (omit quiet to capture main output); status
|
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
|
policy and report checks, commits, and any remaining work accurately. Do
|
||||||
not mark the migration complete while required acceptance behavior is missing.
|
not mark the migration complete while required acceptance behavior is missing.
|
||||||
|
|
||||||
There are no unresolved product questions. The optional upstream selected-format
|
Discovery preset selection and ordering remain to be settled. The optional
|
||||||
accessor is not a migration dependency or completion gate.
|
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-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
|
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||||
|
|||||||
Reference in New Issue
Block a user