Exclude specs

[tylerclair]

Add --exclude-file support for excluding specs from processing

Replaces the hardcoded blacklist list in canvas_api_builder.py with a user-defined TOML file that can be passed via a --exclude-file CLI option. The same option is also available in canopy_docs to keep excluded specs out of generated LLM documentation.

Motivation

Some Canvas spec files contain malformed parameters that cause code generation to fail or produce invalid Python. Previously, the only way to skip these was to edit the blacklist variable directly in the source. This approach is user-friendly (no source edits required), portable (each user maintains their own local file), and consistent across both CLI tools.

Changes

canopy/scripts/canvas_api_builder.py

• Removed the blacklist: list[str] = [] module-level variable
• Added load_excluded_specs(exclude_file) — reads a TOML file using tomllib (stdlib, Python 3.11+) and returns a set[str]
• Added --exclude-file / -e option to build-all-apis, rebuild-apis, and update-spec-files
• Excluded specs are logged at runtime so it's easy to verify what's being skipped

canopy/scripts/canopy_docs.py

• Added load_excluded_specs() using the same implementation for consistency
• _collect_api_files() now accepts excluded_specs and filters by mapping the .py stem back to its source spec name (e.g. accounts_async.py → accounts.json)
• Added --exclude-file / -e option to generate-index and generate-all
• generate-llms intentionally has no --exclude-file as it writes a static framework description unrelated to individual specs

excluded_specs.toml.example (new)

• Reference file showing the format with commented-out examples and usage instructions
• Follows the same .example convention as .env.local.example

.gitignore

• Added excluded_specs.toml so each user's exclusion list stays local

README.md

• Added "Excluding specs from processing" section under the canvas_api_builder usage docs
• Added "Generating LLM documentation" section covering all canopy_docs commands and the --exclude-file option

Usage

# Copy the example and add specs to exclude
cp excluded_specs.toml.example excluded_specs.toml

# Pass it to any multi-spec command
canvas_api_builder build-all-apis \
    --specs-folder specs/ \
    --output-folder apis/ \
    --exclude-file excluded_specs.toml

canvas_api_builder rebuild-apis \
    --specs-folder specs/ \
    --apifolder-path apis/ \
    --exclude-file excluded_specs.toml

canvas_api_builder update-spec-files \
    --specs-folder specs/ \
    --exclude-file excluded_specs.toml

canopy_docs generate-all \
    --apis-folder apis/ \
    --exclude-file excluded_specs.toml

Notes

• No new dependencies — tomllib is part of the Python 3.12 stdlib already required by this project
• excluded_specs.toml is gitignored; excluded_specs.toml.example is committed as a reference