コンテンツにスキップ

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 --erase / --no-erase flag, or None when absent.

None
tip_kit bool

Whether the scenario's own interrupts carries a tipKit entry.

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 ValidationError) or is not valid YAML.

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 hooks resolves against. None for a document with no file, whose hooks may then call no component.

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).