Skip to content

BaseHarbor v0.4.18

BaseHarbor v0.4.18 completes the authoring and extension foundation that must exist before the v0.5 public-contract freeze.

The release adds a first-class greenfield developer path, reusable development Stack Profiles, four ecosystem-native reference Development Adapters, multi-repository workspace resolution, optional Backstage catalog emission, stronger lifecycle teardown, capability-subset acceptance, and runtime-aware host resource preflight.

Manifest v1 remains the portable application contract. Existing brownfield repositories continue to use the normal baha app init -> baha up -> READY path.

Greenfield application creation

baha app new is now the first-class greenfield entry point.

It creates a normal ecosystem-native project from application capability intent and validates the generated implementation against the resulting BaseHarbor contract.

Reference stacks in this release:

  • Go;
  • Next.js;
  • Python;
  • Quarkus.

Example:

baha app new catalog-api --stack go --http --sql --cache --telemetry
cd catalog-api
baha up

Generated applications use normal ecosystem libraries and configuration. BaseHarbor does not introduce an application framework or proprietary SDK.

The same creation flow has deterministic JSON output and a semantic MCP operation. Human CLI, structured output and MCP use the same development-domain result model.

Reusable Stack Profiles

Development preferences can be captured as reusable Stack Profiles without becoming portable deployment requirements.

baha stack list
baha stack show team-api
baha stack create

The guided baha stack create wizard and deterministic flags use the same profile model. Profiles can contain multiple stable development components and can compose existing profiles with explicit conflict handling.

Application requirements, development preferences, capability providers, placement, runtime and delivery remain separate concerns.

Development Extension Contract v1

v0.4.18 adds versioned machine-readable contracts for:

  • common extension descriptors;
  • provider descriptors;
  • Stack Profiles;
  • Development Plans.

Development Adapters implement deterministic Detect, Plan, Bootstrap and Validate semantics. The reference adapters prove round-trip behavior from contract to implementation and back to BaseHarbor inspection/evidence.

Provider and Development Extensions share packaging/discovery/trust mechanics where appropriate, but do not share lifecycle semantics merely for code reuse.

Multi-repository applications and workspace wizard

One logical application may now span:

  • one repository;
  • a monorepo with multiple components;
  • multiple already-present local repositories/worktrees;
  • a mixture of local sources and OCI images.

The portable source model is version controlled under .baseharbor/sources.yaml. Developer-local checkout paths remain XDG-local workspace metadata and never enter portable Application Intent.

baha app workspace
baha app workspace show
baha app workspace resolve

The no-subcommand form is the guided wizard. Deterministic init, map, show and resolve commands remain available for automation.

Application and Component identity are independent from the current working directory and from developer-local checkout paths. Missing worktrees fail before mutation with actionable diagnostics.

Automatic clone/fetch/checkout/sync remains deferred to the later managed-workspace lifecycle; v0.4.18 resolves only already-present local repositories/worktrees.

External developer portals by contract

Backstage is supported as the first reference portal consumer without becoming a BaseHarbor dependency.

baha app new can optionally emit a minimal application-owned catalog-info.yaml:

baha app new catalog-api \
  --stack go \
  --emit-backstage \
  --backstage-owner platform-team

Portal ownership is explicit and is never inferred from BaseHarbor ownership. Backstage lifecycle metadata is not derived from BaseHarbor dev/test/prod environment.

BaseHarbor does not embed a Backstage SDK, Catalog client, template interpreter or repository-publishing credential model. Portal integrations consume stable BaseHarbor JSON/evidence contracts and normal repository metadata.

Capability-subset acceptance

The reference demo now verifies a declarative capability matrix instead of assuming that a full-stack demo proves every smaller contract.

The matrix covers:

  • workload-only;
  • SQL and optional SQL management UI;
  • cache;
  • object storage;
  • secrets;
  • identity;
  • metrics;
  • logs;
  • telemetry;
  • mixed SQL/cache and developer-core profiles;
  • the full reference combination;
  • invalid cross-capability combinations that must fail before mutation.

Contract-only matrix cases remain cheap and deterministic. Runtime acceptance starts only the providers needed by the selected reduced profile; it does not build the whole provider stack for every case.

Lifecycle and teardown hardening

Application stop/destroy now use observed runtime ownership rather than reconstructing successful apply-time state.

This means partially converged deployments can still be cleaned safely when a provider binding or later lifecycle step never completed.

Owned workload containers and networks are removed before deployment state is deleted, while repository/application-owned volumes are preserved according to ownership rules.

Additional v0.4.18 lifecycle hardening includes:

  • persisted workload-port fallback applied consistently;
  • repository workload startup fails fast on terminal runtime errors;
  • canonical development gateway/identity URLs preserve the effective persisted gateway port;
  • management UI readiness follows browser redirect chains rather than treating an initial redirect as failure.

Host resource preflight

Before local Docker or Podman mutation, BaseHarbor now evaluates runtime-host memory headroom using Linux:

  • MemAvailable;
  • swap state;
  • memory PSI where available;
  • a delta-aware estimate of the selected application/control-plane capabilities.

The result is classified as safe, tight or unsafe.

Unsafe headroom fails before runtime mutation. Tight headroom requires explicit interactive approval or the explicit --skip-memory-preflight override.

This evidence is deliberately runtime-scoped:

  • Docker and Podman use local runtime-host evidence;
  • Kubernetes/OpenShift do not use the CLI machine's /proc values.

Future Kubernetes/OpenShift providers must implement cluster-specific resource evidence covering capacity/allocatable resources, requests/limits, quotas and scheduling constraints.

Pre-release architecture

The release validation keeps every small demo gate individually runnable for diagnosis, but the release-wide runtime proof now reuses long-lived environments.

The complete runtime semantics are exercised on both reference runtimes in four parallel lanes:

  • Docker · Core Journey;
  • Docker · Operations;
  • Podman · Core Journey;
  • Podman · Operations.

Each lane builds/loads the exact candidate once and runs a sequence of already-targeted gates against the same environment where safe. This removes repeated provider/container setup without reducing Docker/Podman semantic coverage.

Targeted workflow runs are named by purpose, for example Docker · Capability Matrix, instead of internal branch/test terminology.

Dependency and toolchain decision

BaseHarbor v0.4.18 intentionally remains on:

go 1.25.0
golang.org/x/crypto v0.55.0

The available x/crypto v0.56/v0.57 line requires Go 1.26. Raising the project Go floor is a platform/toolchain decision rather than a routine dependency refresh, so that update is explicitly deferred to a later release together with the matching CI/support-documentation change.

The YAML v3 dependency has moved to the maintained go.yaml.in/yaml/v3 module.

Compatibility

  • Manifest v1 remains supported.
  • Existing brownfield repositories remain compatible.
  • Development metadata and local workspace mappings are additive authoring-time state.
  • Local filesystem paths do not become portable application identity.
  • Generated projects use ecosystem-native dependencies and standard service bindings.
  • Docker and Podman remain the two implemented local Runtime Providers.
  • Kubernetes/OpenShift Target definitions remain future-runtime contracts; local-host memory evidence is explicitly not reused for cluster capacity decisions.

Intentionally deferred

v0.4.18 does not add:

  • automatic Git clone/fetch/pull/checkout/worktree synchronization;
  • Kubernetes Runtime Provider execution;
  • OpenShift Runtime Provider execution;
  • a Backstage runtime/API dependency;
  • a BaseHarbor application framework;
  • an implicit Go 1.26 toolchain upgrade.

Those boundaries remain additive work after the v0.5 contract freeze rather than hidden requirements in the v0.4.18 application contract.

Release validation

Release-boundary evidence uses:

  • local/Hugging Face formatting, vet, source/package and contract validation first;
  • targeted Docker/Podman demo gates for failures that require real runtime evidence;
  • one final GitHub Pre-Release run against the exact v0.4.18 candidate and the immutable demo revision recorded in docs/releases/v0.4.18.demo-ref.

The successful final run is the immutable release approval used by the subsequent release/publish workflow.