feat: add the flagship base-cli consumer

.github/workflows/tests.yml

@@ -19,3 +19,11 @@ jobs:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
       - name: Validate repository baseline
         run: ./tests/validate.sh
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install the reference consumer
+        run: python -m pip install ".[dev]"
+      - name: Run consumer tests
+        run: python -m pytest

CHANGELOG.md

@@ -10,3 +10,4 @@ and versions are tracked in the repo-root `VERSION` file.
 ### Added
 
 - Initialized the repository with the Base-managed repo baseline.
+- Added the Northstar reference consumer with nested status and release commands.

README.md

@@ -1,6 +1,90 @@
 # base-cli-demo
 
-Reference consumer and learning application for the base-cli Python framework.
+Reference consumer and learning application for the `base-cli` Python framework.
+
+This repository contains Northstar, a small offline operational CLI. It is
+designed to show how an application embeds Base-CLI while keeping its own
+command tree, domain policy, and local data model.
+
+Northstar does not require Base, Docker, cloud credentials, or network access
+after its dependencies are installed.
+
+## Quick start
+
+From a fresh checkout:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+northstar --help
+northstar --quiet status
+```
+
+The default environment is `dev`. Select another fixture environment with the
+framework lifecycle option:
+
+```bash
+northstar --quiet --environment staging status
+northstar --quiet --environment dev status --format json
+northstar --quiet --environment dev release plan --version 2.5.0
+northstar --quiet --environment dev --dry-run release reconcile --version 2.5.0 --format json
+```
+
+Base-CLI also provides the optional versioned lifecycle envelope:
+
+```bash
+northstar --quiet --environment dev --json status --format json
+```
+
+## What this demonstrates
+
+- `northstar status` reads consumer-owned, deterministic service fixtures.
+- `northstar release plan` is a nested command that produces a machine-readable
+  release plan.
+- `northstar release reconcile` uses the Base-CLI dry-run lifecycle boundary and
+  explicitly reports that the demo performs no external changes.
+- `--environment`, `--quiet`, `--debug`, `--config`, `--keep-temp`, and
+  `--log-file` are lifecycle options supplied by Base-CLI.
+- `--format` is a consumer-owned option that delegates rendering to the public
+  Base-CLI output API.
+- The `--json` option wraps command output in Base-CLI's versioned success or
+  error envelope.
+
+## Framework boundary
+
+The application uses only the public `import base_cli` facade. Base-CLI owns the
+invocation lifecycle, context, logging, runtime paths, cleanup, and structured
+output. Northstar owns the Click command tree, service fixture schema, release
+planning policy, and domain-facing messages.
+
+The generic consumer profile is explicit in `src/base_cli_demo/cli.py`. The demo
+does not inherit Base-specific manifest, project, history, or cache conventions.
+
+## Development
+
+Install the development extra and run the focused suite:
+
+```bash
+python -m pip install ".[dev]"
+python -m pytest
+./tests/validate.sh
+```
+
+The package requires Python 3.10 or newer and pins the supported Base-CLI line
+to `>=0.4.3,<0.5`. The repository intentionally keeps demo versioning separate
+from framework versioning.
+
+## Repository shape
+
+- `src/base_cli_demo/cli.py` contains the consumer-owned Click tree and the
+  Base-CLI attachment boundary.
+- `src/base_cli_demo/fixtures/services.json` contains deterministic local data.
+- `tests/test_cli.py` exercises the installed lifecycle through the public
+  testing helper.
+- `pyproject.toml` defines the installable `northstar` console script.
+- The generated Base repository files provide the project workflow and release
+  contract; the demo itself does not require Base at runtime.
 
 ## Base
 

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68,<77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "base-cli-demo"
+version = "0.1.0"
+description = "Reference consumer and learning application for the base-cli framework"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "base-cli>=0.4.3,<0.5",
+  "click>=8.1,<9",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+]
+
+[project.scripts]
+northstar = "base_cli_demo.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+base_cli_demo = ["fixtures/*.json"]

src/base_cli_demo/__init__.py

@@ -0,0 +1,5 @@
+"""A small, realistic consumer application for the base-cli framework."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"