Settle native discovery and single-file PromptKit configuration
This commit is contained in:
@@ -72,7 +72,7 @@ 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. |
|
||||
| `--promptkit-source`, `--schema-dir` | Retention outside `config` is under review. Do not install either flag on configuration commands. |
|
||||
| `--promptkit-source`, `--schema-dir` | Removed from every command; framework entry-file and schema-root settings come from application configuration. |
|
||||
| `--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. |
|
||||
@@ -85,9 +85,8 @@ configuration inspection can use native `--set`; framework inspection obtains it
|
||||
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.
|
||||
Do not add source/schema convenience flags. 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. Native `--set` records can address nonconflicting paths;
|
||||
@@ -97,8 +96,40 @@ 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
|
||||
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.
|
||||
directory presets and filename conventions in this order: `WorkingDirectory`,
|
||||
`UserConfigDirectory`, `HomeDirectory`, `UnixSystemDirectories`. Retain each
|
||||
preset's native filename rules, optional exhaustion, and terminal selected-file
|
||||
errors. One main file is selected; the discovered candidates are not layers.
|
||||
|
||||
### Framework Configuration Settings
|
||||
|
||||
Use the following application settings shape:
|
||||
|
||||
```yaml
|
||||
promptkit:
|
||||
configuration: ./promptkit/collections.yml
|
||||
schema_dir: ./schemas
|
||||
```
|
||||
|
||||
`promptkit.configuration` selects one external framework file. An omitted or
|
||||
empty value supplies no external main, preserving defaults-only engine loading.
|
||||
`promptkit.schema_dir` retains the existing schema-root default and semantics.
|
||||
Application path values remain cwd-relative; imports and resource references
|
||||
within the framework document retain their native source contexts. The existing
|
||||
`transient_retries` setting continues to supply the engine retry default.
|
||||
|
||||
Replace `promptkit_sources` and top-level `schema_dir`; do not retain aliases or
|
||||
a compatibility conversion. Load the external file as an import-enabled
|
||||
`configkit.Input` in `promptkit.ConfigurationSources.Main`. Its glob imports
|
||||
discover collection entry files; no application-managed source list or directory
|
||||
classification is needed. PromptKit retains its bundled configuration underlay.
|
||||
|
||||
The `promptkit` application section is acquisition settings, not an embedded
|
||||
PromptKit definition document. Embedding profiles, prompts, backends, or
|
||||
collections there is deferred until upstream supports a native handoff with the
|
||||
required resource context and inspection evidence. Do not emulate it by
|
||||
extracting and reloading application values; no upstream change is required for
|
||||
this migration.
|
||||
|
||||
### Outcomes And Delivery
|
||||
|
||||
@@ -216,15 +247,13 @@ 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.
|
||||
**Discovery and source decisions: Settled.** Implement the ordered native search
|
||||
and single external framework entry file specified above. Remove source/schema
|
||||
CLI flags and the general source-list interface. Embedded framework definitions
|
||||
remain deferred; they are not an upstream prerequisite for this stage.
|
||||
|
||||
**Primary files:** `internal/config/{load,document,settings}.go`, their tests,
|
||||
and CLI application-loading/source-selector helpers.
|
||||
and CLI application-loading/engine-construction helpers.
|
||||
|
||||
1. Retain one `configkit.Load` boundary returning its actual
|
||||
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
|
||||
@@ -241,9 +270,9 @@ and CLI application-loading/source-selector helpers.
|
||||
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.
|
||||
framework definitions during application inspection. Remove source/schema
|
||||
flag bindings, source-list override construction, and file/directory
|
||||
classification used by those flags.
|
||||
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,17 +281,20 @@ and CLI application-loading/source-selector helpers.
|
||||
of completed values, not another resolver or merger.
|
||||
4. Remove `Document.Defaults`, `DefaultsDocument`, `defaults.render_format`,
|
||||
`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. 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. 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.
|
||||
the resulting `internal/config` dependency on `internal/format`. Replace the
|
||||
source-selector list and top-level schema root with the typed `promptkit`
|
||||
settings above; move their applicable defaults, normalization, validation,
|
||||
and evidence paths into the new schema. Strict ConfigKit decoding handles
|
||||
retired fields; add no compatibility mapping.
|
||||
5. Build the shared engine from completed application settings. When configured,
|
||||
construct `configkit.File` from the resolved `promptkit.configuration` and
|
||||
pass it in an import-enabled native main input; otherwise leave `Sources.Main`
|
||||
nil. Supply the configured schema
|
||||
root and existing retry default, retaining PromptKit's bundled underlay.
|
||||
Remove application use of `DirectoryInputs` and one-underlay-per-source
|
||||
construction. The framework entry file imports both collection-entry globs;
|
||||
each collection supplies its namespace and relative imports. Keep native
|
||||
acquisition, composition, validation, and inspection evidence intact.
|
||||
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:
|
||||
@@ -276,9 +308,11 @@ config/overlay selection, the selected native discovery presets and filename
|
||||
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
|
||||
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
|
||||
the new settings shape, optional versus selected framework file loading,
|
||||
imported collection resources and their source contexts, normalized values and
|
||||
their evidence, and removal of retired fields and flags. 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
|
||||
@@ -370,8 +404,7 @@ 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 native config/overlay selection and any separately agreed source
|
||||
controls. Reuse
|
||||
shared native config/overlay selection. 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:
|
||||
@@ -513,8 +546,9 @@ 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. Implement the settled framework-source
|
||||
mapping through native APIs without resurrecting a framework facade.
|
||||
preserve `internal/report` for HTTP. Retire source/schema flags and the old
|
||||
file/directory selector machinery; acquire the single framework document
|
||||
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
|
||||
@@ -525,7 +559,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 imports and describe the settled framework-source settings. |
|
||||
| `docs/config.md` | Selected native discovery order and filenames; `promptkit.configuration` and `promptkit.schema_dir` replacing the source list and top-level schema root; removed render default; native overlay selection, overrides, scopes, and comparison. Preserve collection imports and document the separate framework file. |
|
||||
| `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. |
|
||||
@@ -535,7 +569,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; native configuration discovery; `--overlay` names; endpoint
|
||||
comma splitting; native configuration discovery; the new `promptkit` settings
|
||||
and removal of source/schema CLI flags; `--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
|
||||
@@ -545,7 +580,10 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
|
||||
editing published notes, tagging, pushing, or adding release gates. Eventual
|
||||
release notes must summarize the breaking change and link the guide under
|
||||
the existing release/OSS policies.
|
||||
5. Update maintained application configs to remove the retired render default.
|
||||
5. Update maintained application configs to the new `promptkit` settings and
|
||||
remove retired fields. Where an example previously selected multiple files
|
||||
or directories, revise it to use a framework entry file and native import
|
||||
semantics. Do not recreate the retired source-list precedence locally.
|
||||
Update `examples/render-markdown-summary.sh`, `render-v0.9-features.sh`,
|
||||
README/config examples, and collection workflows to native prepared preview,
|
||||
inspection, positional IDs, and preferred aliases. Existing example script
|
||||
@@ -609,9 +647,9 @@ 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.
|
||||
|
||||
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.
|
||||
Discovery, source selection, and schema controls are settled. The optional
|
||||
selected-format accessor and deferred embedded framework configuration are not
|
||||
migration dependencies or completion gates.
|
||||
|
||||
[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