Retire the legacy CLI and document native operator workflows
This commit is contained in:
@@ -1,117 +1,55 @@
|
||||
# Source Internals
|
||||
|
||||
## Purpose
|
||||
This document covers application acquisition and the restricted HTTP artifact
|
||||
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
|
||||
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
own framework resources and execution semantics.
|
||||
|
||||
This document covers Scriptorium-owned source locations and the restricted HTTP
|
||||
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
|
||||
owned by the tagged
|
||||
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||
## Application Boundary And Engine Construction
|
||||
|
||||
## Application Source Locations
|
||||
`internal/config.Load` selects an explicit File or the ordered native SearchConfig
|
||||
presets and performs one ConfigKit load with imports, overlay selection, and
|
||||
explicit overrides. It returns the actual Result with native inspection evidence.
|
||||
Definition callbacks supply application defaults, record actual path/address
|
||||
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
|
||||
conversion consumes completed values without another merge or normalization pass.
|
||||
|
||||
`internal/config` resolves the ordered `promptkit_sources` sequence and
|
||||
`schema_dir` from application configuration and explicit CLI overrides. It
|
||||
owns selector-shape validation, not framework file parsing. During engine
|
||||
construction, `internal/adapter/cli` turns file selections into import-enabled
|
||||
ConfigKit inputs and expands directory selections with
|
||||
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
|
||||
configuration underlays, one per selector. Directory inputs retain the
|
||||
helper's strict-composition grouping; no selected source becomes an implicit
|
||||
framework main. The shared Promptkit engine receives the selected schema
|
||||
directory and retry setting, and the default OpenRouter bundle remains enabled.
|
||||
The typed application PromptKit section selects acquisition only. In
|
||||
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
|
||||
main Input; an empty path leaves Main nil. The schema base and retry default are
|
||||
passed directly, retaining the bundled underlay. There is no source-list parser,
|
||||
directory classification/expansion, or one-underlay-per-selector algorithm.
|
||||
|
||||
Promptkit uses ConfigKit to load and compose those framework inputs according
|
||||
to Promptkit's own schema and format. Scriptorium does not parse or validate
|
||||
Promptkit definitions. Promptkit owns definition selection and validation,
|
||||
profile built-ins and overlays, schema resolution, ordinary file artifacts,
|
||||
captured framework configuration inspection, and related error identities.
|
||||
Framework imports resolve within the native source context. Message resources
|
||||
are captured from their defining contexts at engine construction. Schema and
|
||||
request-artifact acquisition retain their preparation-time behavior.
|
||||
Independent collection checkouts are discovered by native file import globs,
|
||||
not application traversal. New invocations reload normally; a server retains
|
||||
its single engine until restart.
|
||||
|
||||
The [configuration reference](../config.md) owns Scriptorium's source-location
|
||||
fields and precedence. Maintained files under `examples/` are application
|
||||
inputs that use Promptkit's tagged formats.
|
||||
|
||||
## Application Configuration Boundary
|
||||
|
||||
`internal/config` contains the application-owned ConfigKit-native `Document`
|
||||
definition. Its fresh defaults come from Scriptorium's existing default
|
||||
constants; its resolver records only actual leaf-level trimming, path cleaning, and
|
||||
render-format normalization. The validator reports selector-shape, retry,
|
||||
size-limit, and format errors without mutating the document or exposing
|
||||
rejected values. Application path values keep working-directory-relative
|
||||
meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
|
||||
semantics. Framework configuration is separately loaded by PromptKit using
|
||||
the same ConfigKit release under PromptKit's own schema and source contract.
|
||||
|
||||
The `Load` boundary selects an explicit file or constructs a native ConfigKit
|
||||
search over the ordered implicit paths. Discovery exhaustion uses defaults;
|
||||
a selected-file error stops loading. One ConfigKit load enables imports,
|
||||
applies explicitly supplied application overrides after decoding and before
|
||||
resolution and validation, and returns the document and its frozen inspection
|
||||
records. `Settings` copies selectors in their resolved order into runtime
|
||||
settings; it does not read files or apply another merge. ConfigKit uses the selected file's
|
||||
canonical directory as the source root; the application does not widen it.
|
||||
Application path values retain process-working-directory-relative meaning.
|
||||
|
||||
Runtime conversion consumes the resolved application values through the
|
||||
existing `Settings` path. Promptkit receives selected framework sources only
|
||||
after application configuration has loaded and validated; its source merge,
|
||||
definition validation, and captured inspection view remain framework-owned.
|
||||
|
||||
Every configuration-loading command uses this boundary. The CLI maps only
|
||||
explicitly visited application flags to ConfigKit overrides and prints
|
||||
structured load diagnostics before engine construction. Application and
|
||||
framework load errors and warnings use their respective native writers. The old application
|
||||
YAML decoder and merge path have been removed.
|
||||
Application `config` inspection reuses the result's frozen effective,
|
||||
provenance, and history views without constructing an engine or reloading
|
||||
sources. It does not resolve credentials. `inspect configuration` separately
|
||||
constructs an engine and exposes Promptkit's captured framework view; only its
|
||||
framework `show` and `explain` reports receive Promptkit's native,
|
||||
credential-shaped redaction. Neither inspection family is a general-purpose
|
||||
filter for arbitrary sensitive values.
|
||||
Application-only inspection uses its completed result without framework
|
||||
acquisition. Framework inspection exposes the native captured view separately.
|
||||
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
|
||||
messages without combining evidence trees or effective documents. There is no
|
||||
per-invocation engine/config cache or cross-invocation snapshot guarantee.
|
||||
|
||||
## Restricted HTTP Artifact Reader
|
||||
|
||||
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
|
||||
requests. The `serve` path injects it with
|
||||
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
|
||||
inbound HTTP inputs.
|
||||
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
|
||||
injects it through the public option. Ordinary CLI artifact loading remains
|
||||
upstream-owned.
|
||||
|
||||
The reader:
|
||||
The reader accepts inline content without a root. File references need a root;
|
||||
relative paths resolve below it and absolute paths must be lexically contained.
|
||||
Traversal outside is rejected and the configured file byte limit applies, with
|
||||
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
|
||||
|
||||
- accepts inline references without an artifact root;
|
||||
- denies file references when no root is configured;
|
||||
- resolves relative paths below the configured root;
|
||||
- accepts absolute paths only when they are lexically within that root;
|
||||
- rejects lexical traversal outside the root;
|
||||
- applies the configured file byte limit, with zero meaning unlimited;
|
||||
- preserves content type, body, size, hash, name, and URI metadata; and
|
||||
- honors context cancellation.
|
||||
Containment does not resolve symlinks. The OS may follow a symlink inside the
|
||||
root to an outside target; this is not a filesystem sandbox or a defense against
|
||||
privileged concurrent filesystem modification. Reader errors retain identity
|
||||
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
|
||||
|
||||
Containment is lexical and does not resolve symlinks. The operating system
|
||||
follows symlinks after the check. The [HTTP API](../api.md) owns observable
|
||||
request outcomes, and [operations](../operations.md) owns safe deployment
|
||||
permissions and root selection.
|
||||
|
||||
Reader errors remain identifiable after Promptkit wraps them as artifact-load
|
||||
failures, allowing the HTTP adapter to preserve Scriptorium status and error
|
||||
codes.
|
||||
|
||||
## Verification And Change Recipe
|
||||
|
||||
Inspect:
|
||||
|
||||
- `internal/config/document_test.go`
|
||||
- `internal/config/load_test.go`
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
|
||||
When changing an application source location or HTTP artifact policy:
|
||||
|
||||
1. preserve strict configuration precedence and the Promptkit public boundary;
|
||||
2. keep containment and size policy in Scriptorium;
|
||||
3. update focused configuration, reader, and handler tests;
|
||||
4. update the [configuration](../config.md), [HTTP](../api.md), and
|
||||
[operations](../operations.md) contracts as applicable; and
|
||||
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.
|
||||
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
|
||||
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
|
||||
reader/handler tests own their respective boundaries; upstream owns exhaustive
|
||||
source traversal, format parsing, ordinary artifacts, and inspection semantics.
|
||||
|
||||
Reference in New Issue
Block a user