[jaykv]

Stack 8 of 8. Base: feat/build-targets. Merge in order; each PR shows only its own changes.

Summary

Fixes the bugs that the audits of 0.7.0 found but could not fix in scope. Each fix has a regression test that was written first.

• cli validate now compiles and imports the generated code.
• The Click backend follows the documented meaning of params and supports types and config.
• Generated code is reproducible, and examples/generated is checked against the generator by a test.
• cliffy lints, type-checks and passes its tests without the optional extras; a CI job covers that.
• Every error found while code is generated is reported the same way by every command, as ~ error in <file>: command <name> ..., with no traceback.
• Running the test suite no longer extracts zipapps into ~/.shiv.

Bugs fixed

Bug	Fix
The test suite extracted zipapps into ~/.shiv and never cleaned up	A session fixture points SHIV_ROOT at the pytest temp directory; the docs snippet runner does the same
The cli init --raw template could not run its own tests	Both templates are tested end to end; the raw template gets one command and one test
cli validate passed manifests whose code did not import	It compiles and imports the code and builds the Typer command tree; errors name the command
cli --version printed rich-click's version	The version is passed explicitly
manifestVersion was never checked	v1, v2 and unknown values are errors in manifests, includes and blueprint specs; examples fixed
cli test counter could print "10 of 9"; $ and > were swapped in a message; results differed on CI	The counter counts test cases only; message corrected; assertions see output without terminal styling
Click backend: explicit params were always options; types and config were ignored	Parity with Typer; clear errors for Typer-only definitions; rich-click is optional
"Greet\nuser" became "Greetuser"	A line break becomes a space; paragraphs are kept
Name collisions (db-app and group db) and a var named my-var broke the generated module	Collision-free names; invalid var names are rejected
Non-string vars were rejected	Numbers and booleans are allowed and keep their type; schema regenerated
Vars were resolved in one pass	Transitive resolution with cycle detection
A Jinja error in a comment gave a traceback	Reported with file, line and text; comments stay part of the template (documented)
Corrupt metadata was listed as <name>.json, so cli rm could not remove it	Listed as <name>
Generated code started with a timestamp	Stable header; examples regenerated; make generate-clis only renders
Wrong field descriptions in the manifest models	Fixed at the source; the overrides in scripts/docs.py are gone
Installs without extras failed tests and mypy	Generated Click code falls back to plain click, cliffy/rich.py type-checks either way, the ai tests use importorskip, and a no-extras CI job is added
cli dev ignored the blueprint file	It watches the blueprint file and included manifests

Three reported bugs (inline Typer definitions in shorthand params, global_params on commands without params, include resolution order) were already fixed lower in the stack and have tests there.

Breaking changes

1. cli validate imports the generated code, so imports, functions and {expression} vars run during validation.
2. manifestVersion other than v3 is an error.
3. vars keys must be Python identifiers that the generated code does not use.
4. A self-referencing or circular var is an error; it used to stay as literal {{ }} text.
5. Click: an explicit param without -- is a positional argument (it was an option), matching Typer and the docs.
6. Click: a shorthand argument without ! is optional.
7. Click: config is applied; rich_help_panel becomes rich-click's panel and then requires rich-click.
8. Click: Typer definitions (in types, inline, or as a signature string) are rejected with a manifest-level error.
9. Both backends: a plain type in types is an alias. --n: N with N: int is an option; an explicit param keeps its default and help.
10. The first line of generated code is ## Generated <name> with cliffy <version>.
11. Generated Click code imports rich-click with a fallback to click; cli build ships rich-click and does not pin click separately.
12. Help text: line breaks become spaces instead of being removed.
13. Generation errors exit with ~ error in <file>: ... instead of raising ValueError.
14. cli test strips terminal styling before running a manifest's assertions.
15. cli init --raw output has a command and a test.
16. Makefile: generate-clis renders with scripts/examples.py; generate-cleanup is removed.
17. A corrupt metadata entry is named without .json.

All of these are in docs/project/changelog.md and docs/project/migration.md.

Integration with the build targets PR

This branch was developed in parallel and merged onto feat/build-targets. The points where the two met:

• One error path. A pybash or Python syntax error in a run block gives the same manifest-level message (command, line, column) from every command, cli validate included. A test asserts validate and render print the identical message once.
• Builder. It ships the new stable header unchanged, and detects the framework from the generated import (rich-click, typer or click) explicitly.
• Tests that pinned old behaviour were updated where the behaviour is one of the bugs above (help newlines, Click positional arguments, metadata name, ValueError versus a reported error). No test was deleted, skipped or xfailed, apart from the importorskip for the ai tests when the extra is absent.

How verified

• Python 3.11 and 3.15, fresh environments from the lock: ruff format --check, ruff check, mypy cliffy --strict, mypy tests, pytest -n auto (722 passed, 1 skipped: the opt-in native build), the same with GITHUB_ACTIONS=true, make docs-check, mkdocs build --strict.
• Without extras (uv sync --locked, Python 3.11): lint and mypy clean; 670 passed, 2 skipped (the ai tests and the native build).

Known issues left

Listed in docs/project/known-issues.md:

• cli load, render and build do not import the generated code; an unknown type name is only found by validate and test.
• cli test does not check the exit status of shell steps; a missing program ends the run with a traceback.
• cli init <name> without --raw rejects names with a hyphen.
• Includes fall back to the working directory.
• A full Typer definition in types replaces the param's own default, help and short.

Not verified: Click argument help= without rich-click on click older than 8.5 (the lock has 8.5.0; pyproject.toml allows >=8.2.1).

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @jaykv, your pull request is larger than the review limit of 150,000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: e65205aa-8b49-4c7b-b736-270e7f816416

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}