diff --git a/.ai-context/overview.md b/.ai-context/overview.md index 6d96187..99a6169 100644 --- a/.ai-context/overview.md +++ b/.ai-context/overview.md @@ -28,6 +28,13 @@ similar tools. Use that policy when interpreting the local `.mise.toml`, command-level `runner: uv`, `infra/compose.yaml`, and `.ai-context/` examples in this repository. +Local tooling-testbed policy lives in `docs/tooling-testbed.md`. It keeps +Brewfile, mise, uv, Docker Compose, and VS Code manifest fields in the active +Baseline while treating `devcontainer`, `devenv-report`, Nix/devenv, just, +Taskfile, direnv, asdf, chezmoi, dotbot, mani, gita, vcs2l, west, and future +docker-service work as optional, reference-only, or blocked until their issue +slice promotes them. + ## Purpose - Show what a well-structured `base_manifest.yaml` looks like @@ -63,6 +70,7 @@ in this repository. | `demo/demo.sh` | Interactive walkthrough | | `tests/validate.sh` | Baseline validation (the declared test command) | | `docs/representative-environment.md` | Direction for the multi-language representative environment | +| `docs/tooling-testbed.md` | Local matrix for active, optional, reference-only, and future external tool examples | ## Quick Loop diff --git a/CHANGELOG.md b/CHANGELOG.md index f265e43..7380807 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,9 @@ and versions are tracked in the repo-root `VERSION` file. - Added `.github/pull_request_template.md` for consistent PR descriptions. - Added WSL2 readiness guidance for the Ubuntu/Debian Base path and exposed `BASE_HOST_ENV` in the demo `env` command. +- Added `docs/tooling-testbed.md` and a tooling PR-train plan to separate + active baseline tools from optional wrappers, reference-only examples, and + future Base contracts. ### Changed diff --git a/README.md b/README.md index 1bed901..0d6e595 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,12 @@ Binding promises between the manifest, demo, services, installer, CI, and docs are tracked in [Contracts](docs/contracts.md). Update that registry whenever a new invariant becomes part of the reference project. +The external tooling direction is tracked in +[Tooling Test Bed](docs/tooling-testbed.md). That matrix separates active +baseline tools from optional wrappers, reference-only examples, and future Base +contracts so `base-demo` can test adoption paths without hiding new +requirements in the default demo. + ## Platform Requirements macOS is the supported platform for the full interactive demo: setup, @@ -250,6 +256,9 @@ deterministic without needing an interactive activated shell. `environments/prod.json` model environment-specific configuration. Only `dev` is operational by default. - `.mise.toml` declares tool versions (Python 3.13) managed by mise. +- `docs/tooling-testbed.md` defines how base-demo represents tools such as + direnv, asdf, chezmoi, dotbot, just, Taskfile, mani, gita, vcs2l, west, + devcontainers, Nix/devenv, and future Docker service support. - `demo/demo.sh` is the interactive walkthrough. - `tests/validate.sh` verifies that the repository baseline is intact. diff --git a/docs/contracts.md b/docs/contracts.md index 33c57dc..17ad5d1 100644 --- a/docs/contracts.md +++ b/docs/contracts.md @@ -29,6 +29,7 @@ depend on. | `ubuntu-ci` | The repository has an Ubuntu job that runs `basectl setup base --yes --no-notify`, validates `basectl setup base --profile dev --yes --no-notify`, verifies `bats`/`gh`/`shellcheck`, and runs `basectl check --ci base-demo --format json` against the pinned Base checkout. | `.github/workflows/tests.yml` | `tests/validate.sh`, GitHub Actions `validate-ubuntu` | Ubuntu support can drift from the documented Base setup, dev-profile, and read-only project health boundary. | CI | | `platform-boundary` | README and CONTRIBUTING document macOS full-demo support plus Ubuntu/Debian and WSL2 support for Base setup, dev-profile prerequisites, read-only project health checks, repo-location guidance, and the native-Windows non-goal. | `README.md`, `CONTRIBUTING.md` | `tests/validate.sh` | Developers on Linux or WSL2 follow macOS-only project setup or demo steps without a documented boundary. | Docs | | `ci-json-check` | The demo shows `basectl check --ci base-demo --format json` and asserts JSON status output. | `demo/demo.sh`, `README.md` | `tests/validate.sh`, `tests/demo_test.bats`, `.github/workflows/tests.yml` | The reference project stops demonstrating Base's CI-safe machine-readable check path. | CI | +| `tooling-testbed-boundary` | The tooling matrix separates active baseline tools, optional live wrappers, reference-only examples, Base-generated environment views, and blocked future Docker service support. | `docs/tooling-testbed.md`, `README.md`, `.ai-context/overview.md` | `tests/validate.sh` | base-demo can accidentally make external tools required, duplicate Base-owned behavior, or imply support before Base publishes the contract. | Docs | ## How To Use This Registry diff --git a/docs/superpowers/plans/2026-07-25-base-demo-tooling-testbed-train.md b/docs/superpowers/plans/2026-07-25-base-demo-tooling-testbed-train.md new file mode 100644 index 0000000..2e296bc --- /dev/null +++ b/docs/superpowers/plans/2026-07-25-base-demo-tooling-testbed-train.md @@ -0,0 +1,32 @@ +# Base Demo Tooling Test Bed Train + +Goal: keep `base-demo` in lockstep with Base while making it a practical test +bed for external development tools. + +Architecture: Base stays the operator-facing surface. Tools that are already +part of the Base path can be active in the baseline. Tools that alter shell +state, dotfiles, checkout synchronization, or package-manager behavior stay +reference-only until a separate issue promotes them. + +## Issue And PR Order + +| Order | Issue | PR intent | Notes | +| --- | --- | --- | --- | +| 1 | #178 Define base-demo tooling adapter matrix | Document the policy, register the contract, and add validation guards. | Foundation for the rest of the train. | +| 2 | #182 Demonstrate devcontainer and devenv-report against base-demo | Add CI-safe `basectl devcontainer` and `basectl devenv-report` examples. | Should not make containers or Nix/devenv the baseline runtime. | +| 3 | #180 Add optional just and Taskfile wrappers for Base commands | Add optional wrappers that delegate to `basectl`. | Keep Base commands authoritative. | +| 4 | #179 Add reference-only direnv asdf and dotfile tooling examples | Add inactive examples for `direnv`, `asdf`, `chezmoi`, and `dotbot`. | Avoid root-level files that mutate developer shell or home state. | +| 5 | #181 Add read-only multi-repo manager examples | Add inactive examples for `mani`, `gita`, `vcs2l`, and `west`. | Align examples to `workspace.yaml.example`. | +| Hold | #163 Track future Base docker-service adoption in base-demo | Adopt the future Base Docker service contract. | Blocked by basefoundry/base#124. | + +## Validation Pattern + +Each PR should update only the files needed for its slice and run: + +```bash +./tests/validate.sh +git diff --check +``` + +Add focused BATS or command-level validation when a slice changes demo behavior +or executable wrappers. diff --git a/docs/tooling-testbed.md b/docs/tooling-testbed.md new file mode 100644 index 0000000..957bdd2 --- /dev/null +++ b/docs/tooling-testbed.md @@ -0,0 +1,63 @@ +# Tooling Test Bed + +`base-demo` is the reference project for Base-managed repositories and the +place where Base proves how it coexists with common local development tools. +This document defines the adapter boundary for that test bed. + +Base remains the operator-facing entry point. External tools can be represented +in this repository when they teach a real adoption path, but they should not +become hidden requirements for the baseline demo unless Base itself owns that +contract. + +## Boundary Rules + +- Baseline tools are allowed in root-level active configuration when they are + already part of the supported Base path and are validated by CI. +- Optional live tools may add convenience wrappers or generated artifacts, but + they must delegate back to `basectl` and remain optional for the default + validation loop. +- Reference-only tools live under examples or docs until there is a deliberate + decision to make them active. Do not add root-level files that can change a + developer shell, home directory, checkout graph, or package manager behavior + without a separate issue. +- External tool configuration remains authoritative to the external tool. Base + can check, report, generate, or invoke it; Base should not silently import or + synchronize that state. +- The macOS full-demo path and the Ubuntu/Debian/WSL2 read-only health path are + the current platform boundary. Native Windows and future Docker service + support should stay explicitly scoped until Base publishes the contract. + +## Adapter Matrix + +| Layer | Tools | Current base-demo stance | Next action | +| --- | --- | --- | --- | +| Baseline | Brewfile, mise, uv, Docker Compose, VS Code manifest fields | Active. `Brewfile`, `.mise.toml`, command-level `runner: uv`, `infra/compose.yaml`, and `base_manifest.yaml` are part of the committed demo contract. | Keep validated through `tests/validate.sh`, BATS suites, and Base-backed CI. | +| Base-generated environment views | `basectl devcontainer`, `basectl devenv-report`, Nix/devenv policy | Not yet demonstrated locally. These should prove Base can describe the project for container and Nix/devenv-style environments without making either the baseline runtime. | Issue #182: add generated or dry-run artifacts and CI checks for the reports. | +| Optional live task wrappers | just, Taskfile | Not present. They are useful as ergonomic aliases, but they must call `basectl` rather than create a second command contract. | Issue #180: add optional wrappers and validation that they delegate to Base commands. | +| Reference-only shell and dotfile tools | direnv, asdf, chezmoi, dotbot | Not present. These tools can teach adoption boundaries, but root-level activation files would change developer state too aggressively for the baseline. | Issue #179: add reference examples and docs under an examples path, not active root files. | +| Reference-only multi-repo managers | mani, gita, vcs2l, west | Not present. Base's current workspace view is `workspace.yaml.example`; multi-repo managers should illustrate coexistence without owning checkout synchronization. | Issue #181: add read-only example configs that point at the Base workspace shape. | +| Future Docker service | `basectl docker-service` | Blocked upstream. `base-demo` already has Compose-backed services, but it should not invent a Base docker-service contract before Base lands it. | Issue #163 remains blocked on basefoundry/base#124. | + +## PR Train + +| Order | Issue | Purpose | Expected PR shape | +| --- | --- | --- | --- | +| 1 | #178 | Define the tooling adapter matrix. | Docs, contract registry, AI context, and validation guards. | +| 2 | #182 | Demonstrate Base-generated environment reports. | Add `devcontainer` and `devenv-report` dry-run or generated artifacts with CI-safe checks. | +| 3 | #180 | Add optional task-runner aliases. | Add `just` and Taskfile examples that delegate to `basectl` and are not required for baseline CI. | +| 4 | #179 | Add reference env and dotfile examples. | Add inactive examples for `direnv`, `asdf`, `chezmoi`, and `dotbot` with docs that explain trust and activation boundaries. | +| 5 | #181 | Add read-only multi-repo manager examples. | Add inactive examples for `mani`, `gita`, `vcs2l`, and `west` aligned to `workspace.yaml.example`. | +| Hold | #163 | Adopt future Base Docker service support. | Wait for basefoundry/base#124, then wire the contract through service docs and validation. | + +## Acceptance Policy + +A new tool graduates into the baseline only when all of these are true: + +- Base has a documented contract for the behavior. +- `base-demo` can demonstrate it without requiring privileged local state or a + long-running service by default. +- README, AI context, and `docs/contracts.md` describe the same boundary. +- `tests/validate.sh` or a focused test fails when the contract drifts. + +Until then, the tool belongs in optional wrappers, generated artifacts, or +reference-only examples. diff --git a/tests/validate.sh b/tests/validate.sh index 3b146b0..de93989 100755 --- a/tests/validate.sh +++ b/tests/validate.sh @@ -24,6 +24,7 @@ required_files=( workspace.yaml.example docs/contracts.md docs/representative-environment.md + docs/tooling-testbed.md base_manifest.yaml Brewfile .mise.toml @@ -766,7 +767,8 @@ for contract in \ ci-pinned-dependencies \ ubuntu-ci \ platform-boundary \ - ci-json-check + ci-json-check \ + tooling-testbed-boundary do grep -Fq "| \`$contract\` |" docs/contracts.md || { printf 'docs/contracts.md does not list contract %s.\n' "$contract" >&2 @@ -774,6 +776,45 @@ do } done +grep -Fq 'docs/tooling-testbed.md' README.md || { + printf 'README.md does not reference docs/tooling-testbed.md.\n' >&2 + exit 1 +} + +grep -Fq 'docs/tooling-testbed.md' .ai-context/overview.md || { + printf '.ai-context/overview.md does not reference docs/tooling-testbed.md.\n' >&2 + exit 1 +} + +for tooling_section in Baseline 'Optional live' 'Reference-only'; do + grep -Fq "$tooling_section" docs/tooling-testbed.md || { + printf 'docs/tooling-testbed.md does not document tooling section: %s.\n' "$tooling_section" >&2 + exit 1 + } +done + +for tooling_token in \ + direnv \ + asdf \ + chezmoi \ + dotbot \ + just \ + Taskfile \ + mani \ + gita \ + vcs2l \ + west \ + devcontainer \ + devenv-report \ + 'Nix/devenv' \ + docker-service +do + grep -Fq "$tooling_token" docs/tooling-testbed.md || { + printf 'docs/tooling-testbed.md does not document tooling token: %s.\n' "$tooling_token" >&2 + exit 1 + } +done + grep -Fq 'BASE_OS' README.md && grep -Fq 'BASE_PLATFORM' README.md && grep -Fq 'BASE_HOST_ENV' README.md && grep -Fq 'BASE_HOST' README.md || { printf 'README.md does not document the env command BASE_OS/BASE_PLATFORM/BASE_HOST_ENV/BASE_HOST output.\n' >&2 exit 1