BaseHarbor v0.4.11

BaseHarbor v0.4.11

v0.4.11 focuses on repository adoption and developer experience while preserving the provider-neutral BaseHarbor architecture.

Highlights

• Existing repositories can be inspected locally or through normal HTTPS/SSH Git URLs.
• baha app init continues to generate the smallest portable contract from deterministic evidence.
• baha up -e ENV / --environment ENV selects deployment context without rewriting portable application intent.
• Repository-aware shortcuts: baha plan, baha status, baha doctor.
• Secret-safe structured read-only output through -o json / --output json for inspect, plan, status and doctor.
• Optional bounded AGENTS.md integration through baha app init --agents.
• The existing Compose implementation is documented as the local BaseHarbor Playground: the same lifecycle, security, bindings, readiness and ownership model, not a separate toy runtime.
• New five-minute onboarding documentation in English and German.
• Bash, Zsh and Fish completion with descriptions and environment value completion.
• A shared human-output system with stable columns and semantic states such as READY, VERIFIED, UPDATED and DELETED.
• Delayed contextual progress for slow lifecycle operations with plain line-oriented CI/non-TTY fallback.
• Global --quiet/--silent, --verbose and --no-color controls.
• Redesigned status and doctor trust views with grouped sections, final health state and actionable next steps.
• A read-only baha tui dashboard with Overview, Status and Doctor tabs.
• --no-input/ --non-interactive for strict automation, --plain for styling-free human output and root baha --version.
• Terminal-width-aware result/help wrapping, TTY-only paging, typo suggestions, dynamic local app-name completion and silent broken-pipe handling.

Final acceptance hardening

The final v0.4.11 release candidate was exercised against a clean MailFlow repository through the real lifecycle rather than only unit-level paths.

Validated flows include:

• fresh repository adoption and startup;
• repeated READY baha up as a true no-op;
• down -> STOPPED -> up -> READY with persistent state preserved;
• encrypted application backup and verified restore;
• strict fast-forward baha app update;
• required/generated OpenBao secrets;
• runtime broker and TLS readiness;
• ownership-safe destroy and partial-runtime recovery behavior.

The acceptance round also closed several developer-experience gaps:

• configurable workload host ports are resolved before the first Compose start instead of waiting on a later bind failure;
• undeclared logs/metrics/traces/provider checks stay absent from normal output;
• development no longer invents log collection intent;
• fresh OpenBao recovery prompts render the question and shell-style path prompt reliably;
• Ctrl-C cancels long-running lifecycle work promptly and restores terminal state;
• status/doctor required-secret reads are batched instead of performing repeated full OpenBao scope/login/read cycles;
• baha app update --check explains the exact dirty Git paths and change classes that block an automatic update.

These changes preserve the same fail-closed ownership, secret and provider boundaries. Performance improvements do not skip security verification.

Repository adoption

Inspection remains read-only and classifies evidence as Detected, Suggested or Possible. Remote inspection clones into temporary state and delegates authentication to Git. BaseHarbor rejects remote URLs with embedded credentials.

Weak or ambiguous evidence is never silently promoted into application intent. Existing provider/runtime ownership remains explicit and is not silently replaced.

Structured output

The following forms are supported:

baha app inspect . -o json
baha plan -o json
baha status -o json
baha doctor -o json

Human, JSON and TUI status/doctor surfaces use the same readiness model, including repository TLS health. Doctor JSON is derived directly from preflight results. Required-secret output contains readiness metadata only and never secret values.

Structured doctor output is read-only; doctor --fix -o json is rejected.

Agent repository guidance

baha app init --agents

BaseHarbor creates or updates only the bounded BaseHarbor section in AGENTS.md. Existing unrelated instructions are preserved. Repeated runs are idempotent and malformed/ambiguous managed markers fail closed.

This is repository guidance only. The agent-native machine interface and MCP server remain planned for v0.4.12.

Terminal experience

v0.4.11 treats the CLI as a product surface rather than a stream of implementation logs.

Human output now follows a small semantic vocabulary:

• CREATED / UPDATED / DELETED / REMOVED for mutations;
• STARTED / STOPPED / READY for runtime state;
• VERIFIED for protocol or data-path verification;
• FAILED, DEGRADED and SKIPPED where appropriate;
• OK only for checks that have no more precise state verb.

Status and doctor are intentionally scan-oriented. They group information by application, services, workload, observability and exposure instead of emitting one flat technical list. Expected failures include next actions and keep the non-zero exit code without printing a second duplicate generic error block.

Progress is delayed so short commands do not flash. When work takes noticeable time, BaseHarbor shows what it is waiting for. It never invents percentages or ETAs.

Interactive terminals may use color and a compact activity animation. Non-TTY/CI output stays static and line-oriented. NO_COLOR, TERM=dumb, --no-color and BASEHARBOR_REDUCED_MOTION=1 are respected.

Shell completion

baha completion bash
baha completion zsh
baha completion fish

Completion is deterministic and read-only. It covers command/subcommand discovery, common flags and useful fixed values such as dev, test and prod.

Interactive TUI

baha tui

The v0.4.11 TUI is intentionally read-only. It reuses BaseHarbor's structured application Status and Doctor models instead of introducing a second lifecycle or diagnostic implementation.

Views:

• Overview — application/environment identity and compact overall health;
• Status — grouped services, workload, observability and exposure state;
• Doctor — structured checks and actionable next steps.

Keys: Tab / arrows switch views, r refreshes, and q / Esc / Ctrl-C exits.

The TUI requires a real application-repository terminal. It fails closed under --plain, --no-input, pipes and CI and directs automation to status -o json.

Final CLI ergonomics

--no-input guarantees no prompt can be opened by the guided startup/init/backup/restore/recovery paths. Missing operator decisions are returned as actionable usage errors instead of guessed.

--plain disables color and animated redraw while retaining semantic human output. Human detail rows and help descriptions wrap at terminal width, with continuation lines aligned under the detail column. Long help may use $PAGER only on an interactive TTY.

Configured application names can be completed from local BaseHarbor state without contacting providers. Common command and option typos provide nearest-match suggestions.

Deployment/runtime input precedence is documented as:

explicit CLI flag/input
  > process environment
  > protected local deployment state
  > safe BaseHarbor default

Portable application intent remains separate from these deployment choices.

Fast status snapshots

baha status is intentionally a fast snapshot, not a convergence or retry loop. Runtime-broker and provider checks are bounded by a short overall status budget; deeper diagnosis belongs to baha doctor and baha status --verbose.

Normal status output keeps implementation diagnostics such as Compose exec commands, curl invocations and raw OpenBao errors out of the primary view. Those details remain available in verbose mode.

Repository TLS state is rendered as a normal TLS section inside the same status hierarchy, so the final READY, STOPPED or DEGRADED summary is always the last state shown.

baha doctor follows the same rule. Normal doctor output summarizes actionable failure causes without leaking raw Compose commands, curl probes or OpenBao shell invocations; those details remain available with --verbose. Duplicate workload problem blocks and empty workload-service sections are omitted, TLS appears inside the doctor hierarchy, and the final health state remains last.

The TUI reuses the same concise human-detail mapping for its Status and Doctor views, keeping interactive output aligned with the CLI rather than exposing raw provider or Compose diagnostics.

Cross-command lifecycle audit

The final v0.4.11 audit tightened lifecycle consistency across repository commands rather than patching individual symptoms:

• rendered Compose security preflight now supplies non-sensitive placeholders only for BaseHarbor-declared required secrets, so security analysis never depends on reading the real OpenBao value;
• undeclared missing environment variables still fail closed;
• every repository workload start is guarded again immediately before start, covering apply, up, restore, backup restart and TLS reload/rollback paths;
• restore performs workload-security validation before destructive restore mutation;
• baha app preflight now includes repository workload security explicitly;
• doctor --fix uses the normal apply path after control-plane recovery; no repair-only security bypass remains;
• repository-manifest absence is represented by a typed sentinel error instead of parsing error-message text;
• legacy repair logic that parsed rendered [FAIL] output was removed completely;
• status/doctor JSON and the TUI now include the same TLS health used by human output.