chore(merge): update starbase (2026-07-22)

.github/workflows/check-renovate.yaml

@@ -24,6 +24,8 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 24
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
       - name: Install renovate
         run: npm install --global re2 renovate
       - name: Enable ssh access

.github/workflows/policy.yaml

@@ -14,4 +14,9 @@ jobs:
     name: Security scan
     uses: canonical/starflow/.github/workflows/scan-python.yaml@main
     with:
-      requirements-find-args: "! -path '*/tests/integration/*'"
+      osv-extra-args: "--config=osv-scanner.toml"
+      osv-exclude-paths: |
+        docs
+      uv-export-no-groups: |
+        docs
+        docs-sphinx-stack

.github/workflows/qa.yaml

@@ -9,6 +9,10 @@ on:
       - "renovate/*"
   pull_request:
 
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
   filter:
     runs-on: ubuntu-slim

.pre-commit-config.yaml

@@ -27,3 +27,8 @@ repos:
         files: ^(.\/?)*\.(yaml|yml|json|json5|css|md)$
         additional_dependencies:
           - prettier@3.6.0 # renovate: datasource=npm
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: "v3.13.1-1"
+    hooks:
+      - id: shfmt
+        exclude: '\.sh\.j2$'

.prettierignore

@@ -1,3 +1,4 @@
 # Ignore auto-generated schema files
 schema/
 docs/.sphinx
+docs/_dev

AGENTS.md

@@ -0,0 +1,69 @@
+# Agents
+
+## Overview
+
+`canonical/debcraft` is a Python CLI tool for building Debian packages with the
+Crafting Experience.
+
+## Craft apps and libraries
+
+Debcraft is built on the following craft libraries:
+
+| Package             | Role                                                                                          |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `craft-application` | Application framework: CLI lifecycle, configuration, service management, remote build support |
+| `craft-archives`    | Repository and package archive management (apt sources, keyrings)                             |
+| `craft-cli`         | Terminal output, progress reporting, error formatting                                         |
+| `craft-grammar`     | Architecture and platform-conditional YAML in project files                                   |
+| `craft-parts`       | Part lifecycle (pull, build, overlay, stage, prime) steps, plugins                            |
+| `craft-platforms`   | Platform and architecture abstractions                                                        |
+| `craft-providers`   | Build environment manager for LXD and Multipass                                               |
+| `craft-store`       | Store API client: upload, release, track management                                           |
+
+The source code for these libraries is at https://github.com/canonical/<library>.
+
+These libraries are used by other craft apps, including Charmcraft, Imagecraft,
+Rockcraft, and Snapcraft.
+
+Fixes or features that are generic or would benefit other craft apps must be made in the
+correct craft library. Overriding an upstream function to fix a bug in the library isn't
+acceptable.
+
+## Development
+
+Debcraft uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+make setup
+```
+
+### Running tests
+
+```bash
+make test
+make test-fast
+uv run pytest tests/unit/path/to/test_file.py::test_name
+```
+
+Spread tests (`tests/spread/`) require additional setup and should be run for broad
+changes that cannot be fully covered by unit and integration tests.
+
+### Formatting and linting
+
+```bash
+make format
+make lint
+```
+
+### Documentation
+
+Documentation uses [Diátaxis](https://diataxis.fr) and the
+[Sphinx Stack](https://github.com/canonical/sphinx-stack). Follow the
+[Starcraft style guide](https://documentation.ubuntu.com/starflow/latest/how-to/starcraft-style-guide/)
+and the [Canonical style guide](https://documentation.ubuntu.com/style-guide/).
+
+```bash
+make setup-docs
+make docs
+make lint-docs
+```

CONTRIBUTING.md

@@ -153,9 +153,6 @@ documentation. If the feature warrants a new page in the documentation, propose
 [Diátaxis](https://diataxis.fr) category for the page. A Debcraft maintainer will
 review your proposal and, if everything looks complete, assign the issue to you.
 
-Certain high-value issues are allocated monetary bounties. If you're interested in
-taking one on, we welcome you to apply.
-
 ### Create a development branch
 
 Once you've settled on a topic to work on, it's time to set up a local branch.

Makefile

@@ -21,10 +21,10 @@ endif
 include common.mk
 
 .PHONY: format
-format: format-ruff format-codespell format-prettier format-pre-commit  ## Run all automatic formatters
+format: format-ruff format-codespell format-prettier format-shfmt format-pre-commit  ## Run all automatic formatters
 
 .PHONY: lint
-lint: lint-ruff lint-ty lint-codespell lint-prettier lint-shellcheck lint-docs lint-twine lint-uv-lockfile lint-actions  ## Run all linters
+lint: lint-ruff lint-ty lint-codespell lint-prettier lint-shfmt lint-shellcheck lint-docs lint-twine lint-uv-lockfile lint-actions  ## Run all linters
 
 .PHONY: pack
 pack: pack-pip  ## Build all packages

common.mk

@@ -4,11 +4,12 @@
 SOURCES=$(wildcard *.py) $(PROJECT) tests
 DOCS=docs
 
-# Env vars for the docs Starter Pack. They must be exported so make can pass them to the
+# Env vars for the docs Sphinx Stack. They must be exported so make can pass them to the
 # docs Makefile.
 export DOCS_BUILDDIR ?= _build
 export DOCS_VENVDIR ?= ../.venv
 export VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale
+export SPHINX_AUTOBUILD_OPTS ?= --ignore "$(DOCS_VENVDIR)/*" --ignore "reference/commands/*" -D=llms_txt_enabled=0
 
 ifneq ($(OS),Windows_NT)
 	OS := $(shell uname)
@@ -36,24 +37,12 @@ export UV_FROZEN := true
 
 .PHONY: help
 help: ## Show this help.
-	@printf "\e[1m%-30s\e[0m | \e[1m%s\e[0m\n" "Target" "Description"
-	printf "\e[2m%-30s + %-41s\e[0m\n" "------------------------------" "------------------------------------------------"
-	egrep '^[^:]+\: [^#]*##' $$(echo $(MAKEFILE_LIST) | tac --separator=' ') | sed -e 's/:[^#]*/ /' | sort -V | awk -F '[: ]*' \
-	'{
-		if ($$2 == "##")
-		{
-			$$1=sprintf(" %-28s", $$1);
-			$$2=" | ";
-			print $$0;
-		}
-		else
-		{
-			$$1=sprintf("  └ %-25s", $$1);
-			$$2=" | ";
-			$$3=sprintf(" └ %s", $$3);
-			print $$0;
-		}
-	}' | uniq
+	@printf "\033[1m%-30s\033[0m | \033[1m%s\033[0m\n" "Target" "Description"
+	@printf "\033[2m%-30s + %-41s\033[0m\n" "------------------------------" "------------------------------------------------"
+	@cat $$(echo $(MAKEFILE_LIST) | tac --separator=' ' 2>/dev/null || echo $(MAKEFILE_LIST)) | grep -E '^[^[:space:]][^:]*\:[^#]*##' | \
+	sed -e 's/:[^#]*/ /' | sort -V | \
+	awk -F '[: ]+' '{ if ($$2 == "##") { $$1=sprintf(" %-28s", $$1); $$2=" | "; print $$0; } else { $$1=sprintf("  └ %-25s", $$1); $$2=" | "; $$3=sprintf(" └ %s", $$3); print $$0; } }' | \
+	uniq
 
 .PHONY: setup
 setup: install-uv _setup-docs _setup-lint _setup-tests setup-precommit install-build-deps  ## Set up a development environment
@@ -77,7 +66,7 @@ setup-lint: _setup-lint  ##- Set up a linting-only environment
 	uv sync $(UV_LINT_GROUPS)
 
 .PHONY: _setup-lint
-_setup-lint: install-uv install-shellcheck install-pyright install-lint-build-deps install-actionlint
+_setup-lint: install-uv install-shellcheck install-shfmt install-pyright install-lint-build-deps install-actionlint
 
 .PHONY: setup-tests
 setup-tests: _setup-tests ##- Set up a testing environment without linters
@@ -129,6 +118,12 @@ format-pre-commit:  ##- Format the entire repository using pre-commit
 format-prettier: install-npm  ##- Format files with prettier
 	$(PRETTIER) --write $(PRETTIER_FILES)
 
+.PHONY: format-shfmt
+format-shfmt: install-shfmt ##- Format shell scripts
+	@# jinja2 shell script templates are mistakenly counted as "true" shell scripts due to their shebang,
+	@# so explicitly filter them out
+	git ls-files -z | xargs -0 sh -c 'for f; do case "$$f" in *.sh.j2) continue;; esac; file --mime-type -Nn -- "$$f" | grep -q shellscript && printf "%s\0" "$$f"; done' -- | xargs -0r shfmt -w
+
 .PHONY: lint-ruff
 lint-ruff: install-ruff  ##- Lint with ruff
 ifneq ($(CI),)
@@ -179,7 +174,7 @@ lint-ty: install-ty  ##- Check types with Astral ty
 ifneq ($(CI),)
 	@echo ::group::$@
 endif
-	ty check --python .venv/bin/python $(SOURCES)
+	ty check --python .venv $(SOURCES)
 ifneq ($(CI),)
 	@echo ::endgroup::
 endif
@@ -189,18 +184,31 @@ lint-uv-lockfile: install-uv  ##- Check that uv.lock matches expectations from p
 	unset UV_FROZEN
 	uv lock --check
 
+.PHONY: lint-shfmt
+lint-shfmt: install-shfmt  ##- Lint shell script formatting
+ifneq ($(CI),)
+	@echo ::group::$@
+endif
+	@# jinja2 shell script templates are mistakenly counted as "true" shell scripts due to their shebang,
+	@# so explicitly filter them out
+	git ls-files -z | xargs -0 sh -c 'for f; do case "$$f" in *.sh.j2) continue;; esac; file --mime-type -Nn -- "$$f" | grep -q shellscript && printf "%s\0" "$$f"; done' -- | xargs -0r shfmt --diff
+ifneq ($(CI),)
+	@echo ::endgroup::
+endif
+
 .PHONY: lint-shellcheck
 lint-shellcheck:  ##- Lint shell scripts
 ifneq ($(CI),)
 	@echo ::group::$@
 endif
 	@# jinja2 shell script templates are mistakenly counted as "true" shell scripts due to their shebang,
 	@# so explicitly filter them out
-	git ls-files | grep -vE "\.sh\.j2$$" | file --mime-type -Nnf- | grep shellscript | cut -f1 -d: | xargs -r shellcheck
+	git ls-files -z | xargs -0 sh -c 'for f; do case "$$f" in *.sh.j2) continue;; esac; file --mime-type -Nn -- "$$f" | grep -q shellscript && printf "%s\0" "$$f"; done' -- | xargs -0r shellcheck
 ifneq ($(CI),)
 	@echo ::endgroup::
 endif
 
+
 .PHONY: lint-prettier
 lint-prettier: install-npm  ##- Lint files with prettier
 ifneq ($(CI),)
@@ -223,7 +231,7 @@ endif
 
 # Legacy alias for linting docs
 .PHONY: lint-docs
-lint-docs: docs-lint  ##- Lint the documenation
+lint-docs: docs-lint  ##- Lint the documentation
 
 .PHONY: lint-twine
 lint-twine: pack-pip  ##- Lint Python packages with twine
@@ -248,7 +256,7 @@ test-slow:  ##- Run slow tests
 	uv run pytest -m 'slow'
 
 .PHONY: test-coverage
-test-coverage:  ## Generate coverage report
+test-coverage:  ##- Generate coverage report
 ifeq ($(COVERAGE_SOURCE),)
 	uv run coverage run --source $(PROJECT),tests -m pytest
 else
@@ -268,42 +276,49 @@ test-find-slow:  ##- Identify slow tests. Set cutoff time in seconds with SLOW_C
 # Alias for `html` target in docs project. We want to use our own `.venv`, so we
 # replace it.
 .PHONY: docs
-docs: docs-install  ## Render the documentation to disk
+docs:  ## Render the documentation to disk
 ifneq ($(CI),)
 	@echo ::group::$@
 endif
+	$(MAKE) docs-install
 	$(MAKE) -C docs html --no-print-directory
 ifneq ($(CI),)
 	@echo ::endgroup::
 endif
 
 # Alias for `serve` target in docs project
 .PHONY: docs-auto
-docs-auto: docs-install  ##- Render the documentation in a live session
+docs-auto:  ##- Render the documentation in a live session
+	$(MAKE) docs-install
 	$(MAKE) -C docs run --no-print-directory
 
 # Override for `install` target in docs project. We still need the Vale setup, so we
 # run that after the parent docs setup.
 .PHONY: docs-install
 docs-install: _setup-docs  ##- Set up documentation packages
 ifneq ($(CI),)
+ifeq ($(MAKELEVEL),0)
 	@echo ::group::$@
+endif
 endif
 	$(MAKE) -C docs vale-install --no-print-directory
 ifneq ($(CI),)
+ifeq ($(MAKELEVEL),0)
 	@echo ::endgroup::
 endif
+endif
 
 # Alias for `setup-docs`
 .PHONY: docs-setup
 docs-setup: setup-docs
 
-# Override for `clean` target in docs project. We don't want to touch `.venv`, so
-# we pass a null dir instead.
+# Override for `clean` target in docs project. We don't want to touch `.venv`.
 .PHONY: docs-clean
 docs-clean:  ##- Clean the temporary files used in documentation
-	VENVDIR=$(mktemp)
-	$(MAKE) -C docs clean --no-print-directory
+	$(MAKE) -C docs clean-doc --no-print-directory
+	rm -rf docs/_dev/node_modules/
+	rm -rf docs/_dev/styles
+	rm -f docs/_dev/vale.ini
 
 # Override for `help` target in docs project
 .PHONY: docs-help
@@ -324,17 +339,25 @@ docs-lint-md:
 
 # Passthrough for the rest of the targets in docs project
 .PHONY: docs-%
-docs-%: docs-install
+docs-%:
+ifneq ($(CI),)
+	@echo ::group::$@
+endif
+	$(MAKE) docs-install
 	$(MAKE) -C docs $(@:docs-%=%) --no-print-directory
+ifneq ($(CI),)
+	@echo ::endgroup::
+endif
 
 # Run our own docs linting, then pass to the docs
 .PHONY: docs-lint
-docs-lint: docs-install  ##- Lint the documentation
+docs-lint:  ##- Lint the documentation
 ifneq ($(CI),)
 	@echo ::group::$@
 endif
+	$(MAKE) docs-install
 	uv run $(UV_DOCS_GROUPS) sphinx-lint docs \
-	--ignore docs/.sphinx \
+	--ignore docs/_dev \
 	--ignore docs/_build \
 	--ignore docs/reference/commands \
 	--enable all \
@@ -427,6 +450,17 @@ else
 	$(warning Shellcheck not installed. Please install it yourself.)
 endif
 
+.PHONY: install-shfmt
+install-shfmt:
+ifneq ($(shell which shfmt),)
+else ifneq ($(shell which snap),)
+	sudo snap install shfmt
+else ifneq ($(shell which brew),)
+	brew install shfmt
+else
+	$(warning shfmt not installed. Please install it yourself.)
+endif
+
 .PHONY: install-ty
 install-ty:
 ifneq ($(shell which ty),)

docs/.custom_wordlist.txt

@@ -50,6 +50,7 @@ sitemapindex
 Sphinx
 Spread
 spread_test_example
+Starbase
 Starcraft
 subproject
 subprojects