base-demo

Reference Base-managed project and representative demo environment.

This repository is the public reference project for Base-managed repositories. It demonstrates Base on a compact but credible project shape: small enough to inspect in one sitting, but substantial enough to represent the tools and runtime variety found in a medium-sized engineering organization.

The long-term direction is documented in Representative Environment Design. base-demo is intentionally positioned between a toy sample and banyanlabs: it borrows the shape of a realistic platform environment while keeping each service shallow so Base orchestration remains the point.

Binding promises between the manifest, demo, services, installer, CI, and docs are tracked in Contracts. Update that registry whenever a new invariant becomes part of the reference project.

Platform Requirements

macOS is the supported platform for the full interactive demo: setup, activation, human-readable check/doctor output, build/test orchestration, and the project-owned walkthrough.

Ubuntu and other Linux environments are supported in read-only CI mode via basectl ci check base-demo --format json. Brewfile reconciliation, Homebrew tools, mise setup, activation shells, and the full interactive demo require macOS.

For the full Base platform policy, see docs/linux-support.md in the Base repository.

Quick Start

Clone base and base-demo as peer directories:

git clone https://github.com/basefoundry/base.git
git clone https://github.com/basefoundry/base-demo.git

For a first Base setup, basectl onboard base-demo is the recommended guided path. It wraps the setup, profile, doctor, and project-discovery flow for new Base users. Run basectl onboard base-demo --dry-run to preview the steps without changing local state.

From the base-demo repository root on a machine where Base is already set up:

basectl projects list
basectl setup base-demo  # macOS only
basectl activate base-demo  # macOS only
basectl check base-demo  # macOS interactive path
basectl doctor base-demo  # macOS interactive path
basectl ci check base-demo --format json  # Ubuntu/Linux read-only CI path
basectl repo check .
basectl workspace status --manifest workspace.yaml.example
basectl run base-demo --list
basectl run base-demo hello
basectl run base-demo env
basectl run base-demo python-info -- info
basectl run base-demo python-info -- env
basectl run base-demo services -- status
basectl run base-demo environments -- list
basectl test base-demo
basectl logs --limit 3
basectl history --project base-demo --limit 5
basectl build base-demo
basectl demo base-demo  # macOS only
basectl docs --show-url
basectl export-context base-demo --format markdown --print

The commands above exercise the complete Base project loop:

• basectl projects list proves the repository is discoverable from the workspace.
• basectl setup base-demo reconciles the project manifest, Brewfile, and project virtual environment on macOS.
• basectl activate base-demo starts a macOS project shell with the activation source applied.
• basectl check base-demo and basectl doctor base-demo validate the local project environment from that activated macOS shell.
• basectl ci check base-demo --format json returns machine-readable project health for read-only CI pipelines, including Ubuntu/Linux checks.
• basectl repo check . validates the standard repository baseline files.
• basectl workspace status --manifest workspace.yaml.example shows a workspace-level view of the expected base, base-demo, optional base-platform-tools, and optional base-bash-libs peer repositories.
• basectl run base-demo --list shows the manifest-declared project commands.
• basectl run base-demo hello runs the hello command from the project root.
• basectl run base-demo env shows Base runtime metadata such as BASE_OS, BASE_PLATFORM, and BASE_HOST alongside project activation values.
• basectl run base-demo python-info -- info shows Base context values from base_cli.Context.
• basectl run base-demo python-info -- env shows the BASE_* environment visible to the Python command.
• basectl run base-demo services -- status shows the representative service catalog and current health state.
• basectl run base-demo environments -- list shows the modeled dev/staging/prod configuration set.
• basectl test base-demo runs the manifest-declared test command.
• basectl logs --limit 3 and basectl history --project base-demo --limit 5 show the local audit trail for recent Base activity.
• basectl build base-demo runs the default build target (info) declared in the manifest.
• basectl demo base-demo runs the macOS project-owned walkthrough.
• basectl docs --show-url prints the Base documentation home page URL without opening a browser.
• basectl export-context base-demo --format markdown --print prints the repository AI context bundle for assistant handoff.

basectl activate base-demo spawns a new subshell, sources .base/activate.sh, and updates the prompt to [base-demo: <branch>] ~/path $. Inside that shell, BASE_DEMO_ENV is baseline (set by activate.sh). Run exit or press Ctrl-D to return to the original shell. The environment changes disappear when the subshell exits — no explicit deactivation is needed.

Expected command output includes:

$ basectl run base-demo --list
Commands for project 'base-demo'

test                 ./tests/validate.sh
hello                ./src/hello.sh
env                  ./src/env.sh
manifest             ./src/manifest.sh
python-info          ./bin/base-demo-python-info
uv-info              uv run -- python src/uv-info.py
services             ./bin/base-demo-services
environments         ./bin/base-demo-environments

$ basectl run base-demo hello
hello from base-demo
BASE_PROJECT=base-demo
BASE_DEMO_ENV=baseline

$ basectl run base-demo env
BASE_PROJECT=base-demo
BASE_PROJECT_ROOT=/path/to/base-demo
BASE_PROJECT_MANIFEST=/path/to/base-demo/base_manifest.yaml
BASE_PROJECT_VENV_DIR=/path/to/base-demo/.venv
BASE_OS=macos
BASE_PLATFORM=macos
BASE_HOST=dev-host
BASE_DEMO_ENV=baseline
BASE_DEMO_ACTIVATED=true
BASE_DEMO_PROJECT_KIND=reference-demo

$ basectl run base-demo python-info -- info
base-demo python cli
project_name=base-demo
project_root=/path/to/base-demo
workspace_root=/path/to/work

$ basectl run base-demo python-info -- env
BASE_PROJECT=base-demo
BASE_DEMO_ENV=baseline

$ basectl test base-demo
Repository baseline is present.

BASE_DEMO_ENV Health Check

Normal green path: run basectl check base-demo and basectl doctor base-demo from the activated project shell, where BASE_DEMO_ENV=baseline has been set by .base/activate.sh.

Pre-activation diagnostic: if BASE_DEMO_ENV is missing, check and doctor can report that finding intentionally. That output teaches how health.required_env works; it does not mean the repository is corrupt. Activate the project shell, or export BASE_DEMO_ENV=baseline, before using check and doctor as green-path validation commands.

CI sets BASE_DEMO_ENV=baseline at the workflow level so automated validation is deterministic without needing an interactive activated shell.

Repository Shape

• base_manifest.yaml declares the project name, activation source, command, test command, and Brewfile location using current Base contracts.
• Brewfile is the Homebrew-owned place for ordinary macOS tools. The Brewfile currently installs mise, uv, Gradle, and Maven so setup can demonstrate tool-version management, command runners, and representative Java build tools.
• .base/activate.sh demonstrates project activation state.
• src/hello.sh, src/env.sh, src/manifest.sh, and src/build-info.sh are tiny command and build targets for basectl run and basectl build; src/env.sh also exposes Base runtime metadata such as BASE_OS, BASE_PLATFORM, and BASE_HOST.
• lib/python/base_demo_cli is a tiny Python command target that runs inside the Base-managed project environment.
• bin/base-demo-python-info is the Bash launcher that delegates the Python package to base-wrapper.
• src/uv-info.py is a tiny Python command routed through runner: uv.
• services/go-api is a tiny Go HTTP API with /healthz, /hello, and /info endpoints. It is also the representative Dockerized app service.
• services/python-api is a tiny standard-library Python HTTP API with the same health, hello, and info surface on port 8020.
• services/java-gradle-api and services/java-maven-api are tiny Java HTTP APIs that keep Gradle and Maven visible as representative build tools.
• services/c-service and services/cpp-service are tiny native compiled fixtures with Makefile-backed build and command health checks.
• services/demo-console is a small React/Vite operational console that reads the service catalog and shows the representative stack.
• bin/base-demo-services reads services/catalog.json and provides the services lifecycle command for the representative environment.
• bin/base-demo-environments lists, shows, and validates environment configuration.
• services/catalog.json is the initial catalog for representative services, infrastructure, and lifecycle checks.
• infra/compose.yaml defines local Postgres, MySQL, Redis, and the Dockerized Go API for the representative dev environment.
• environments/dev.json, environments/staging.json, and environments/prod.json model environment-specific configuration. Only dev is operational by default.
• .mise.toml declares tool versions (Python 3.13) managed by mise.
• demo/demo.sh is the interactive walkthrough.
• tests/validate.sh verifies that the repository baseline is intact.

Manifest Contract Map

base_manifest.yaml is the project contract Base reads. In this repository, each field maps to a visible Base workflow:

Manifest field	Demonstrated by	Purpose
schema_version	basectl setup base-demo	Declares the manifest contract version Base should parse.
project.name	basectl projects list	Gives Base the stable project name used by setup, check, doctor, run, test, activate, and demo.
brewfile	basectl setup base-demo	Delegates ordinary Homebrew dependencies to brew bundle; currently installs mise, uv, Gradle, and Maven.
health.required_env	basectl check base-demo	Declares env vars that must be set; green in an activated shell and intentionally reported missing as a pre-activation diagnostic.
health.required_ports	basectl check base-demo	Declares that the baseline go-api port 8010 should be free before services are started.
mise	basectl setup base-demo	Points to .mise.toml so Base installs declared tool versions (Python 3.13) via mise.
python.requires_python	basectl check base-demo	Lets Base verify Python 3.13 independently of the mise installer declaration.
activate.source	basectl activate base-demo	Sources project-owned shell state into the activated project shell.
ide.vscode	basectl setup base-demo	Declares VS Code Python extensions and auto-injects the project venv as python.defaultInterpreterPath when IDE setup is enabled.
commands	basectl run base-demo --list	Declares named project commands such as hello, env, manifest, python-info, uv-info, services, and environments.
commands[*].runner	basectl run base-demo uv-info	Routes only the uv-info command through uv run --, without making uv the project-wide Python manager.
build.targets	basectl build base-demo	Declares build targets; the info target runs src/build-info.sh.
build.targets[*].working_dir	basectl build base-demo go-api	Runs the Go build from services/go-api without the target command needing to change directories itself.
test.command	basectl test base-demo	Defines the project-owned validation command.
demo.script	basectl demo base-demo	Defines the project-owned interactive walkthrough.
artifacts	basectl setup base-demo	Requests the bats-core tool artifact; the project setup layer reports whether Homebrew already has it or would install it.

The demo now includes a shallow but representative environment: multi-language service fixtures, one Dockerized app service, a React/Vite UI, Compose-backed local databases and cache, and a lightweight dev/staging/prod configuration model. The services stay intentionally small and readable; deeper product and platform complexity belongs in Banyan Labs.

The environment model is present now:

basectl run base-demo environments -- list
basectl run base-demo environments -- show dev
basectl run base-demo environments -- validate --all

dev is the runnable local environment. staging and prod are modeled configuration examples that are validated structurally but not deployed.

The first representative-environment command is:

basectl run base-demo services -- status
basectl run base-demo services -- check
BASE_DEMO_SERVICES_DRY_RUN=1 basectl run base-demo services -- start

It reads services/catalog.json and reports the current catalog health. Local Postgres, MySQL, Redis, and the Dockerized Go API are declared through infra/compose.yaml; the Python API is managed as a local process by the same services command, as are the Java Gradle, Java Maven, C, C++, and React/Vite console services. They are representative dependencies and services, and they are optional in services check until started.

Both Gradle and Maven are present intentionally. They are common enough in real enterprise Java estates that a medium-shaped demo should exercise both build tool contracts, even when the service behavior stays hello-world small.

For CI or scripted validation, run the walkthrough without prompts:

basectl demo base-demo -- --non-interactive

CI also runs the representative BATS suites, validates every environment JSON file, checks the service catalog, and exercises service startup through BASE_DEMO_SERVICES_DRY_RUN=1. Docker and language-toolchain-heavy runtime checks remain optional locally so the baseline stays useful on a fresh machine.

License

base-demo is licensed under the MIT License so it can be freely copied as a small reference project for Base-managed workflows. See LICENSE for the full terms.