Configuration¶
This page covers the config schema, where per-target config overlays team defaults. It also
covers how the schema resolves to an Effective config for one target, and the Git config source
(github:owner/repo@ref:path).
bajutsu.common.config
¶
Configuration — team defaults overlaid by per-target config.
Split along its four responsibilities (BE-0252), one submodule each, with a one-directional
dependency from resolution outward: input schema (schema) -> resolved output types
(effective) <- merge/derivation (resolve) and platform-narrowing accessors (accessors).
The public API is re-exported here, so from bajutsu.common.config import Effective, resolve,
require_ios, … is unchanged and no call site outside this package is touched.
AiConfig
dataclass
¶
The resolved ai block (BE-0047): which provider/model/endpoint/key the AI paths use.
Lives with the rest of the resolved config (not the AI client) so the deterministic core can
read the block without importing the periphery AI stack (BE-0112). Every field is optional — an
absent field falls back to the environment in the AI-client factory, so a config with no ai:
block behaves exactly as before. key_env holds the NAME of the env var that carries the key,
never the key itself.
AndroidConfig
dataclass
¶
Android (adb) target knobs (BE-0126 / BE-0007). On Effective only when platform is android.
DoctorThresholds
dataclass
¶
Configurable doctor id-coverage thresholds (BE-0024), grouped out of Effective (BE-0252).
Teams with many decorative elements can tune thresholds (often lowering ok and/or fail for leniency) without changing the tool.
Effective
dataclass
¶
The resolved config for one target.
platform
property
¶
The resolved platform (ios / android / web), derived from the sub-config's type (BE-0126).
schema_platform
property
¶
The platform the target declares, whose registered models shape its groups (BE-0452).
Unlike platform, which reads a fake target as iOS because it resolves to the iOS-shaped
sub-config, this keeps fake, so a scenario field is checked against the models the target
was validated with. A --backend fake override leaves it alone: the target still declares
its own platform.
app_identifier
property
¶
The bundle identifier or package the app installs under, or None for a web target.
Two targets sharing one are two builds of one app: installing either replaces the other on a device they share (BE-0447).
rebased(root, *, confine=True, confine_to=None)
¶
A copy with the relative path fields resolved against root.
The common path fields — scenarios / baselines / schemas / goldens — the iOS or
Android sub-config's app_path, and an iOS or Android target's seed_photos are rebased; a future
path field is rebased by adding it here. build (a shell command) is intentionally absent —
it is not rewritten but run from root, recorded as base_dir — and a component the
target's hooks call was already resolved against the config file when it loaded. Called
for a Git checkout (BE-0063), for an uploaded bundle, and — root the config file's own
directory — for a local config (BE-0242), so the caller's working directory no longer
decides where a config's paths point.
confine gates the escape check: when true, an absolute or ../ value that would leave the
confinement boundary raises ValueError, mirroring the serve-hardening path confinement
(BE-0051). That boundary is root itself by default — the same directory relative paths
resolve against — which is right for both a Git checkout and an uploaded bundle, though root
means a different tree to each. For a Git checkout root is the whole fetched tree and the
config may sit anywhere within it, so a sibling reference elsewhere in the checkout is
legitimate and only a path leaving the tree is refused. For an uploaded bundle root is
instead the config file's own directory (config_path.parent — the bundle root, or the single
wrapper subdirectory find_bundle_config accepts), so the config always sits at its top and a
../ reference to a sibling outside that directory is refused, not legitimate.
confine_to overrides just the confinement boundary, decoupling it from the resolution base,
for serve's local file-browser bind (bind_config): paths there still resolve against the
config file's own directory (root, matching state.binding.cwd), but are confined to --root
(confine_to) — the file-browser's own sandbox, not the narrower single directory the config
happens to live in — so a config at <root>/configs/x.yaml may still reference a sibling tree
like <root>/scenarios via ../scenarios, exactly as the CLI's unconfined --config would
resolve it, while a path leaving --root entirely is still refused.
A fetched Git config and an uploaded bundle always pass confine=True (boundary = root) —
either can carry attacker-authored path fields (a Git spec names any repo, an upload is any
zip), so their paths are confined regardless of who requested the bind. The two local-config
entry points diverge on this axis only: the CLI's --config (an operator typing a path at
their own terminal, BE-0121) passes confine=False and may point anywhere, while serve's
bind_config passes confine=True, confine_to=state.root as a defense-in-depth consistency
check — not because the file it binds is less trusted (bind_config only ever resolves a file
_confined_config_path already found inside --root, an operator-controlled tree, so its
content is no less trusted than the CLI's), but so a config's path fields can't point outside
that same already-sanctioned tree, regardless of bind source. This is independent of build:
trust (bajutsu.serve.operations.dispatch._build_trusted): bind_config keeps a local
config's build trusted exactly as the CLI path does, since neither can hand the host an
attacker-authored command the way an API-bound Git spec or upload can. That verdict covers
driver.runner.build too: rebasing makes its working directory root (#2277), but whether
it runs at all is serve's call — the spawned run refuses it for an untrusted binding
(#2282).
EvidenceDirs
dataclass
¶
The target's evidence directory overrides (BE-0252 grouping of Effective).
Each is the target's directory for that evidence kind (config-driven run/record). None
means "unset": scenarios then requires an explicit path, and each of baselines / schemas /
goldens falls back to the directory beside the scenario file (or the matching --<kind> flag).
IosConfig
dataclass
¶
iOS (XCUITest) target knobs (BE-0126). On Effective only when platform == "ios".
RunDefaults
dataclass
¶
Per-app run-behavior defaults (BE-0177), grouped out of Effective (BE-0252).
The layer the run consults when neither a CLI flag nor the scenario sets the value. The target's
hooks.interrupts is one list of three forms (BE-0473); it is split here by form, because each
form layers with the scenario's own entries by its own rule.
WebConfig
dataclass
¶
Web (Playwright) target knobs (BE-0126). On Effective only when platform == "web".
ResolvedPreconditions
dataclass
¶
One target's preconditions after the scenario's merged over the target's (BE-0452).
What a platform environment reads to install, launch, and seed the app. launch_env and
launch_args hold the scenario's own additions, which the environment merges over the target's
Effective.launch_env and appends after its launch_args; every other field is already merged.
erase
property
¶
Whether the run wipes the whole device: the top of the reinstall ladder.
with_erase(erase)
¶
These preconditions under an --erase / --no-erase flag (BE-0473).
--erase raises the ladder to erase; --no-erase lowers an erase to clean and leaves
overwrite and clean alone; None (no flag) keeps the merged value.
resolved_locale(target_locale)
¶
The locale this run uses: the scenario's own, else the target's.
AiSettings
¶
Bases: _Model
The ai block (BE-0047) — which provider/model/endpoint/key the AI paths use.
defaults.ai is overridable per targets.<name>.ai. Keys never live here: keyEnv is the NAME
of the env var holding the key, read at call time, so a secret never lands in the repo or an
uploaded bundle. Every field is optional; an unset field falls back to the environment in the
factory. extra="forbid" (from _Model) rejects a stray apiKey:-style field that would tempt
a literal key into config.
Config
¶
Bases: _Model
A parsed bajutsu.config.yaml: team defaults, per-target config, and team-wide settings.
defaults is merged into each target before the target is validated, so a field a target's
platform requires may come from defaults.platforms.<platform>. templates are named, partial
target blocks a target pulls in with extends, folded between defaults and the target itself
(BE-0471); a template is never a target, so it lives outside targets. reservedNamespaces and
doctor are team-wide rather than per target, so they sit at the top level.
The hosted multi-tenancy orgs: block is a serve concern the core does not model (BE-0129);
parse_config_dict drops it before validation so a run reading an org-bearing config keeps
working, and bajutsu.serve.orgs owns the org model.
Defaults
¶
Bases: _Model
Team-wide defaults under defaults:, merged into each target before it is validated.
The shared groups sit directly here; the platform-shaped groups sit under platforms.<platform>.
ai merges field by field in resolve; every other dictionary merges key by key, with the
target winning, and the lists replace except evidence.secrets and evidence.redact, which union.
DeviceProvider
¶
Bases: _Model
Where a target's devices come from (BE-0236).
No longer a target key (BE-0452): which grid serves a device is infrastructure, so an appium
environment in worker.yaml names it, and the command that drives the device fills this for the
targets of the grid's platform. kind selects the provider adapter from the device-provider
registry, defaulting to local — a locally-attached simulator / emulator / device, exactly
today's --udid path. endpoint carries the grid's address for appium. Like the mailbox
kind, an unknown value — or a required-but-missing endpoint — fails closed when the run
resolves the provider, not here: the deterministic config must not import a cloud SDK (BE-0112).
DoctorConfig
¶
Bases: _Model
Configurable thresholds for bajutsu doctor's id-coverage grading (BE-0024).
idCoverageOk is the minimum coverage to be eligible for "Ready"; idCoverageFail
is the ceiling below which the grade drops to "Blocked". Both must be in [0, 1] with
ok >= fail.
LaunchServer
¶
Bases: _Model
How to bring up the app's target server (the host behind baseUrl) for a run.
Unlike mockServer (which stubs the dependencies the app calls), this hosts the app under
test itself — e.g. the static page for demos/web, or the inner serve the WebUI dogfood
drives. run probes readyUrl first: if it already answers it reuses it (started externally),
else it runs cmd, waits on the readiness probe (a condition wait, never a fixed sleep), and
tears the process down afterwards.
Mailbox
¶
Bases: _Model
A mailbox the email step polls (targets.<name>.mailbox, BE-0046 / BE-0186).
kind selects the transport adapter (http, later imap) from the mailbox registry, defaulting
to http so a pre-BE-0186 block is unchanged; an unknown kind fails closed when the runner
resolves the mailbox, not here (the deterministic config must not import the registry, BE-0112).
url is the inbox endpoint (GET; commonly ${secrets.*}), headers any auth. The optional
response mapping absorbs a provider's JSON shape without per-provider code: messages is a
dotted path to the message array (empty = the response is the array), and fields maps each
normalized field (to / subject / body / receivedAt / id) to the provider's key,
defaulting to the field's own name.
MockServer
¶
Bases: _Model
A mock server that stubs the dependencies the app under test calls (mockServer: config).
NotifyEndpoint
¶
Bases: _Model
One webhook notification sink (notify: list entry, BE-0099).
PricingEntry
¶
Bases: _Model
Per-token rates for one (provider, model) in ai.pricing (BE-0196), USD per million tokens.
Overrides a shipped default. cacheWrite / cacheRead default to 0 for a provider that does
not price cache separately, so an entry may name only input / output.
TargetConfig
¶
Bases: _Model
One app's config under targets.<name>, after defaults has been merged into it.
platform decides the actuator and selects the models that validate the three platform-shaped
groups (subject, runsOn, and driver) from the registry, so the core names no platform here. Every model forbids extra keys, so a key another platform takes
fails as unknown, with the accepted fields listed.
XcuitestConfig
¶
Bases: _Model
Per-target XCUITest runner config (targets.<name>.xcuitest, BE-0019).
android_package(eff)
¶
The Android target's package, or "" for a non-Android target.
ios_bundle_id(eff)
¶
The iOS target's bundle id, or "" for a non-iOS target.
require_android(eff)
¶
The Android sub-config, narrowed for the type checker, or a loud failure (BE-0126 / BE-0007).
The Android counterpart of require_ios / require_web, for code already on an adb-only path
(the AndroidEnvironment lifecycle).
require_ios(eff)
¶
The iOS sub-config, narrowed for the type checker, or a loud failure (BE-0126).
For code already committed to an iOS-only path (the iOS/XCUITest environment, the idb doctor
probe): it narrows the platform union to IosConfig and fails fast rather than silently reading
a default if a non-iOS target ever reaches it. Code that has not committed to a platform must
narrow with isinstance / match instead — reading a platform's knobs off platform_config
without narrowing is a type error, which is the point of the split.
require_web(eff)
¶
The web sub-config, narrowed for the type checker, or a loud failure (BE-0126).
The web counterpart of require_ios, for code already on a web-only path (the web environment,
the Playwright doctor probe).
web_base_url(eff)
¶
The web target's base URL, or None for a non-web target.
web_engine(eff)
¶
The web target's rendering engine, or the chromium default for a non-web target.
xcuitest_pins_runner(eff)
¶
True when the target pins an explicit XCUITest runner (driver.runner.testRunner).
Every non-iOS target — and an iOS target that names no runner — is False. Such a target resolves to the wheel-bundled generic runner instead (BE-0292); consulted by the serve Server settings tab to report whether the bound config overrides that fallback (BE-0318).
xcuitest_targets_real_device(eff)
¶
True when the target drives a real iOS device via XCUITest (runsOn.ios.kind: device).
The Simulator default — and every non-iOS target — is False. Consulted by the capability narrowing that drops the simctl-backed DeviceControl / permission / interval-evidence tokens on a real device (BE-0238, BE-0467): simctl reaches only the Simulator, so those capabilities do not apply on a physical device.
check_preconditions(pre, targets, *, erase_flag=None, tip_kit=False)
¶
Every problem with pre against the targets a scenario drives, before any device work.
A field never goes ignored (BE-0452). A subject field that no driven target's platform has is a
problem, and so is a tipKit interrupt entry when no driven target is iOS. After merging, an iOS
target whose seedPhotos is non-empty needs an effective subject.reinstall: erase (the
scenario's, else the target's, then moved by the flag), because seeding happens only on the
erase path. An Android target needs none: it resets the directory it seeds.
A non-primary target with seeded photos is a problem too: the run seeds the photo library for
the primary alone. An Android locale needs API level 33, so a target whose apiLevel admits an
earlier level cannot set one (BE-0478); with apiLevel unset the device is checked at start.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pre
|
Preconditions
|
The scenario's preconditions, as written (before a command fills in run defaults). |
required |
targets
|
Sequence[Effective]
|
Every target the scenario drives, the primary first. |
required |
erase_flag
|
bool | None
|
The |
None
|
tip_kit
|
bool
|
Whether the scenario's own |
False
|
Returns:
| Type | Description |
|---|---|
list[str]
|
One message per problem, each naming the field; empty when the scenario is sound. |
command_preconditions(eff, *, erase)
¶
The target's own preconditions for a command that runs no scenario (record, crawl, repl).
The command's --erase / --no-erase moves the target's subject.reinstall along its ladder
(ResolvedPreconditions.with_erase); the target's subject.launch.deeplink and
runsOn.<platform>.seedPhotos still apply.
Raises:
| Type | Description |
|---|---|
ValueError
|
An iOS target seeds photos but the run does not erase, which would seed none. |
resolve_preconditions(eff, pre=None)
¶
Merge a scenario's preconditions over the target eff resolves.
A scenario value wins over the target's; unset falls through to the target and then to the
built-in default (reinstall: clean).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
eff
|
Effective
|
The target the scenario runs against. |
required |
pre
|
Preconditions | None
|
The scenario's preconditions; None for a command that runs no scenario. |
None
|
load_config(text, *, path=None, root=None)
¶
Parse a YAML config string into a Config (see parse_config_dict).
load_config_file(path, *, root=None)
¶
Read and parse the config file at path, resolving hook components against it.
Raises:
| Type | Description |
|---|---|
OSError
|
The file cannot be read. |
ValueError
|
The document does not match the schema (a pydantic |
parse_config_dict(data, *, path=None, root=None)
¶
Validate an already-parsed config document into a Config.
Top-level orgs: and ui: keys are dropped before validation: the hosted multi-tenancy org
model (BE-0129) and the serve UI's ui.default_theme (BE-0191) are serve concerns the
deterministic core does not model, and a run in the hosted topology legitimately reads a config
carrying them, so the core must ignore the keys rather than reject them under extra="forbid".
bajutsu.serve.orgs / bajutsu.serve.themes parse those blocks separately. A key starting with
x- is dropped too: it only hosts a YAML anchor that targets merge with << (BE-0473), and the
loader has already expanded every alias of it. Every other unknown key still fails loudly,
preserving the typo guard.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict[str, Any]
|
The parsed YAML document. |
required |
path
|
Path | None
|
The config file, which a component called from a target's |
None
|
root
|
Path | None
|
The suite root a component reference must stay inside (BE-0174): the checkout of a Git source, the bundle root of an upload or a composition. None means the config file's own directory. |
None
|
unknown_target(config, target, *, list_targets=True)
¶
The error for a target name targets: lacks, which says so when it names a template.
A template is a building block under templates: and never runnable (BE-0471), so a name that
matches one gets that reason rather than a bare "unknown".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
Config
|
The loaded config. |
required |
target
|
str
|
The name asked for. |
required |
list_targets
|
bool
|
Append every target the config declares. The server passes False: one config can hold several orgs' targets, and the list would show a caller the others'. |
True
|
bajutsu.common.config_source
¶
Acquire a config (and its scenario tree) from a Git source (BE-0063).
--config keeps accepting a local path; in addition it accepts a Git spec
(github:<owner>/<repo>[@<ref>][:<path>], or git+https://<host>/<owner>/<repo>.git[@<ref>][#<path>]).
The spec is materialized at an immutable commit SHA into a content-addressed cache, and the config's
relative paths resolve against that checkout root. Only acquisition changes — the schema, runner,
drivers, and the deterministic gate are untouched (DESIGN §6.5: git holds the history).
The GitHub transport (commits API + tarball endpoint) is the one external dependency; it is a small injectable seam so the materialization logic tests offline against a fake.
GitConfigSpec
dataclass
¶
A parsed Git config source: which repo subtree, at which ref, to load the config from.
Materialized
dataclass
¶
A repo subtree checked out at an immutable SHA: the config file, the checkout root, and the SHA.
Transport
¶
Bases: Protocol
The Git-host calls materialization makes — injected so the logic tests offline.
config_source_record(spec, config)
¶
The {kind, locator} record naming where a bound configuration came from (BE-0393 unit 6).
A Git source records the spec the caller asked for, not the commit it resolved to: an org that
bound a branch should come back to that branch, which is what a moving ref means. Anything else
is a local path. The reverse is config_spec_from_record; the two are a pair, because a record
that cannot be turned back into a --config value is a record nothing can restore from.
config_spec_from_record(source)
¶
The --config value a stored record names, or None when it names none (BE-0393 unit 6).
None rather than an exception for every malformed shape, and for an upload record, whose bytes
have no spec form and are restored by digest instead: the caller is a best-effort restore that
must degrade to "this session has no binding" rather than fail the request that triggered it.
The record reaches the org row from a client-shaped bind, so nothing here trusts its contents.
github_http_error_message(status, headers, spec)
¶
Turn a GitHub HTTPError into an actionable message that names the real cause (BE-0224).
The rate-limit and SSO sub-types are checked before the catch-all so neither is misreported as
missing repository access — more Contents: read permission fixes neither. The 404/other-403
fall-through names the most-likely-missing grant.
github_token()
¶
A GitHub token for private repos, else gh auth token, else None.
Checks the bajutsu-owned BAJUTSU_GIT_CONFIG_TOKEN (a serve-entered credential) first, then
GITHUB_TOKEN / GH_TOKEN, so a UI credential wins over an ambient token (BE-0224).
is_full_sha(ref)
¶
Whether ref is a full 40-hex commit SHA — the only ref that is an immutable, offline pin.
materialize(spec, *, transport=None, cache_root=None, offline=False, credential=None)
¶
Check out spec's subtree at its resolved commit SHA into a content-addressed cache.
The ref is resolved to an immutable SHA (the determinism anchor), then the tree is fetched once
and extracted under <cache>/<host>/<owner>/<repo>/<sha>/. Because the directory is keyed by the
SHA, a cache hit is always valid and a pinned-SHA run is offline after the first fetch.
With offline (the --config-offline switch) it never touches the network: the ref must already
be a full SHA (a branch/tag can't be resolved offline) and that SHA must already be cached.
credential is a stored UI credential (resolve_github_credential's stored).
parse_config_spec(value)
¶
Parse a --config value into a GitConfigSpec, or None when it is an ordinary local path.
A value with no recognized Git scheme is a local path, so every existing invocation is unchanged.
A repo of exactly . or .. is a same-segment traversal (BE-0124) and is refused here, so it
fails the same way an unparseable value does rather than reaching the cache path.
resolve_github_credential(spec, stored=None)
¶
The bearer token for spec, in documented precedence order (BE-0224).
A configured GitHub App installation first (a short-lived, per-installation, service-identity
token — the answer for an unattended host), then the GITHUB_TOKEN / GH_TOKEN / gh auth token
chain of github_token(), else anonymous. Resolved per acquisition (the transport is built
per materialize), so a rotated secret takes effect without a serve restart.
stored is the credential a user set in the serve UI, read from a store that keeps it out of
the environment (BE-0449). It takes the place BAJUTSU_GIT_CONFIG_TOKEN holds in that chain:
after the App, ahead of an ambient token.
source_provenance(spec, mat)
¶
The run-provenance stamp for a Git config source: repo + subtree + the ref asked for + the SHA.
Recording the resolved sha makes a branch-based run reproducible after the fact (BE-0063) — it
states the exact commit executed, not just the moving branch. path is the config's location
within the repository, empty when the spec named none (the repo's DEFAULT_CONFIG at the root):
it is what tells two configs of one repository apart, so a deployment's run-history label
partitions them instead of folding both onto the repository name (BE-0404 unit 2).