114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
# Adapter Internals
|
|
|
|
## Purpose
|
|
|
|
Adapters translate external inputs into domain requests, compose dependencies,
|
|
and translate domain results or errors back to their interface. They own IO and
|
|
presentation mechanics; use-case decisions remain in `internal/usecase`.
|
|
|
|
External contracts are canonical in the [CLI reference](../cli.md), [HTTP API
|
|
reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
|
|
|
|
## Components And Collaborators
|
|
|
|
- `cmd/scriptorium` passes process arguments and streams to
|
|
`internal/adapter/cli`.
|
|
- `internal/adapter/cli` parses commands, resolves application settings through
|
|
`internal/config`, constructs a runner, and owns process output handling.
|
|
- `internal/adapter/http` decodes DTOs, maps them to `domain.RunRequest`, calls
|
|
a runner interface, and maps errors and results to HTTP DTOs.
|
|
- The root `scriptorium` package maps its public types and options to internal
|
|
collaborators and maps selected internal errors to public sentinels.
|
|
- `internal/format` formats prepared runs for the CLI; `internal/llm`,
|
|
`internal/prompt`, and source packages supply runner dependencies.
|
|
|
|
## Wiring Flows
|
|
|
|
### CLI
|
|
|
|
The CLI resolves configuration before constructing dependencies. `run` builds a
|
|
runner with the ordinary composite artifact reader and invokes `Runner.Run`;
|
|
`render` uses the same wiring and invokes `Runner.Prepare`; `serve` replaces the
|
|
file reader with the restricted artifact reader, builds an HTTP handler, and
|
|
starts the server.
|
|
|
|
Parser state records whether numeric runtime values were explicitly supplied.
|
|
That presence is carried into `domain.ExecutionTargetOverride`, allowing the
|
|
runner to distinguish omitted values from explicit zero overrides.
|
|
|
|
### HTTP
|
|
|
|
The handler first enforces transport limits, strict JSON decoding, and the
|
|
minimal request shape. It maps DTO values to domain types without deciding
|
|
prompt selection, source behavior, or validation semantics. On success it maps
|
|
the domain result to the response DTO; on failure it uses `errors.Is` over
|
|
runner, source, artifact, and profile errors to choose the public error mapping.
|
|
|
|
The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
|
|
and externally observable limit behavior.
|
|
|
|
### Public Go Facade
|
|
|
|
`NewEngine` applies public options, selects filesystem, `fs.FS`, single-file,
|
|
or in-memory dependencies, and constructs a runner. The conversion functions
|
|
copy maps and slices across the boundary so callers do not receive internal
|
|
domain values. The facade maps selected internal errors to the public sentinel
|
|
set and keeps direct request API keys out of public results.
|
|
|
|
## Package-Local Guarantees
|
|
|
|
- Adapters do not embed runner orchestration or source-loading decisions.
|
|
- Configuration is resolved before adapter dependency composition.
|
|
- CLI and HTTP create runners without a repairer; a repairer is available only
|
|
through explicit internal runner construction.
|
|
- DTO conversion preserves explicit numeric-override presence.
|
|
- Error mapping matches error identities, not error text.
|
|
- No adapter creates durable run state; caller-selected output files are not
|
|
application state.
|
|
|
|
## Failure And Verification Boundaries
|
|
|
|
Keep external error payloads concise, preserve strict external decoding, and do
|
|
not serialize resolved secret values. Validation content failures remain result
|
|
state; runtime failures remain errors for the relevant adapter to map.
|
|
|
|
Inspect focused tests when changing this area:
|
|
|
|
- `internal/adapter/cli/run_test.go`
|
|
- `internal/adapter/http/handler_test.go`
|
|
- `engine_test.go`
|
|
- `internal/format/prepared_run_test.go`
|
|
|
|
Run the affected adapter package tests and recheck the relevant canonical
|
|
contract. The [testing policy](../policy/testing.md) owns global test
|
|
sufficiency guidance.
|
|
|
|
## Change Recipes
|
|
|
|
### Application Configuration Fields
|
|
|
|
1. Add the field to the relevant `internal/config` shape and default handling.
|
|
2. Parse and validate it, then preserve configuration and CLI-override
|
|
precedence while wiring it through its consuming adapter.
|
|
3. Add focused configuration and adapter tests for parsing, mapping, and
|
|
effective behavior.
|
|
4. Update the [configuration contract](../config.md) and any affected external
|
|
contract.
|
|
|
|
### CLI Flags
|
|
|
|
1. Add the flag to the relevant parser in `internal/adapter/cli/run.go`.
|
|
2. Keep command scope and application-configuration precedence intentional.
|
|
3. Add or update parser and command tests in
|
|
`internal/adapter/cli/run_test.go`.
|
|
4. Update the [CLI contract](../cli.md) and affected maintained examples.
|
|
|
|
### Adapter Capabilities
|
|
|
|
1. Define or reuse the appropriate domain or use-case interface boundary.
|
|
2. Implement translation and IO behavior without moving use-case decisions out
|
|
of `internal/usecase`.
|
|
3. Add focused mapping, parsing, and error-behavior tests.
|
|
4. Update this document and the affected public or integration contract. Update
|
|
[source internals](sources.md) when source-loading behavior changes.
|