4.7 KiB
Audita request: main-relative companion resources
Consumer requirements against ConfigKit v1.1.0. These complement the proposed main-relative underlays and overlays; that roadmap owns upstream API design and implementation planning.
What Audita is doing
Audita is a transcript-processing CLI adopting ConfigKit, PromptKit, and CommandKit's native loading and inspection workflows. ConfigKit should own discovery, imports, composition, overlays, and configuration resolution. Audita should receive the resolved configuration and then apply transcript-specific business logic.
The main application configuration is either an explicit file or the result of
native SearchConfig discovery. Companion resources should follow the directory
containing the selected main file, regardless of the process working directory:
| Resource | Intended location and use |
|---|---|
| Glossaries | Optional glossary.yml and recursive glossary/ imports, mounted at glossary_collections in an application underlay. |
| PromptKit definitions | Optional prompts.yml and recursive prompts/ imports, in an operator tier above embedded Audita prompts and PromptKit's bundled catalog. |
| Selected named overlay | Beside the main file, using native overlays/<name>.yml lookup. |
Both recursive imports select *.yml and *.yaml. Audita supplies their import
declarations, so operators need not repeat discovery boilerplate in every main
file or create a manifest just to use a resource directory. Each pair composes
as peers within its tier; native precedence and diagnostics remain authoritative.
Embedded assets retain their separate filesystem contexts.
For example, selecting /srv/campaign/audita.yml while running from /tmp
should use /srv/campaign/glossary/, /srv/campaign/prompts/, and
/srv/campaign/overlays/<name>.yml.
An aggregate overlays.yml was also suggested for symmetry. It is not supported
by today's named-overlay contract and is a separate possible enhancement, not
necessary to solve the directory-binding requirement described here.
Missing API support
In the current layered API, SearchConfig
selects the main during loading, while underlay filesystem contexts and
OverlayFilesystem must be supplied beforehand. Audita cannot bind these to
the selected directory without duplicating discovery or performing a preliminary
load. Imports in the main file would be peers, not the required lower-priority
underlay.
- Bind an underlay import context to the selected main directory. Audita needs this for an application-supplied mapping or bytes containing native import declarations, including optional file and recursive-directory imports and their destinations. A constructor for a required main-relative file alone would not cover this workflow. Resolve the relationship within one layered load, then let existing import machinery acquire and compose the resources.
- Derive the selected overlay context during that same load. Support an explicit request for main-relative lookup with either an explicit or discovered main file. Preserve native overlay naming, precedence, and errors. Audita's intended lookup base is the main file's directory; distinguish that choice from a potentially broader filesystem containment root.
- Make absent-main behavior explicit. Audita permits optional discovery to find no main file and still run with sufficient defaults and CLI settings. The API should allow an explicit policy for dependent resources in that case, without manufacturing a main source or guessing from unsuccessful candidates. A caller-supplied fallback directory is one useful option; whether Audita chooses the working directory or skips automatic companion imports remains an application decision. Failures reading a selected main must remain terminal.
PromptKit's separate engine can be constructed after application loading and use the selected main's recorded source context. Existing context inspection may already suffice there; this request does not require combining the two schemas or adding a second discovery API.
Completion from Audita's perspective
One native application load can discover the main, bind its companion imports and selected overlay, and return normal source evidence and errors. Changing only the invocation directory does not relocate companions of the same selected main. Processing and inspection share this behavior, with no Audita directory walker, configuration parser, discovery pass, or preliminary full load.
The API shape is ConfigKit's choice. The important addition is native context binding for both declared underlay imports and selected overlays.