scripts/
Helper scripts for local development, CI, and maintainer release automation.
Normative release policy: ADR-0009, ADR-0010. Runbook: release-pipeline.md.
Quick start
| Goal | Command |
|---|---|
| Publish a full release | python scripts/publish_release.py --align-develop |
| Dry-run the release flow | python scripts/publish_release.py --dry-run --bump patch |
| Bump only (manual path) | python scripts/bump_release.py --yes |
| Check branch CI before tag | python scripts/verify_release_ready.py --ref release/X.Y.Z --wait |
| Check tag CI before promote | python scripts/verify_release_ready.py --ref vX.Y.Z --profile tag --wait |
| Tag after branch CI is green | python scripts/tag_release.py --ref release/X.Y.Z --wait |
Check [web:NNN] tags vs mapping | python scripts/check_web_source_tags.py or a2c web-sources check |
| Fetch mapped web sources (ADR-0012) | python scripts/fetch_web_sources.py or a2c web-sources fetch |
| Recover mapping gaps (report only) | python scripts/recover_web_sources.py or a2c web-sources recover |
| Fetch to separate sources repo | python scripts/fetch_web_sources.py --archive-backend git --sources-repo PATH |
| Fetch to S3/MinIO | python scripts/fetch_web_sources.py --archive-backend s3 --s3-uri s3://bucket/prefix |
Set GITLAB_TOKEN (or GITLAB_SYNC_TOKEN) for GitLab API polling. In GitLab CI jobs, CI_JOB_TOKEN is used automatically.
Web source policy: ADR-0011, rules/15-web-source-tags.md.
Runnable scripts
Entrypoints you invoke from the shell (or from CI). Maintainer = human operator; AI = agent-driven release or maintenance; CI = run from .gitlab-ci.yml (optional = allow_failure job).
| Script | Purpose | Maintainer | AI | CI |
|---|---|---|---|---|
publish_release.py | End-to-end ADR-0009/0010 release orchestration | ✓ | ✓ | — |
bump_release.py | Propose/apply version bump and changelog finalization | ✓ | ✓ | — |
verify_release_ready.py | Poll GitLab until branch or tag CI gates pass | ✓ | ✓ | — |
tag_release.py | Verify branch CI, create and push annotated tag | ✓ | ✓ | — |
verify_release_version.py | Assert tag matches VERSION and package versions | — | — | ✓ |
registry_publish.py | Select TestPyPI rcU / assert PyPI slot available | — | — | ✓ |
build_packages.py | Build lockstep wheels/sdists (--publish-version for TestPyPI rc) | ✓ | — | ✓ |
build_a2c_cli_binary.py | PyInstaller a2c binary | ✓ | — | ✓ |
build_a2c_tui_binary.py | PyInstaller a2c-tui binary | ✓ | — | ✓ |
smoke_install_packages.py | Install/smoke wheels or index versions | ✓ | — | ✓ |
smoke-ollama-decompose.sh | Live Ollama integration smoke (Linux) | ✓ | — | opt |
smoke-ollama-decompose.ps1 | Live Ollama integration smoke (Windows) | ✓ | — | — |
setup-dev.sh | Install dev deps and git hooks (Unix/Git Bash) | ✓ | — | — |
setup-dev.ps1 | Install dev deps and git hooks (Windows) | ✓ | — | — |
fix-git-ssl.ps1 | Local Git SSL workaround (called from setup) | ✓ | — | — |
generate_tui_screenshots.py | Regenerate TUI SVG screenshots for docs | ✓ | — | — |
sync_task_fixture_json.py | Sync task workflow fixture JSON from markdown | ✓ | — | — |
check_web_source_tags.py | Lint [web:NNN] tags against docs/web-source-mapping.md | ✓ | ✓ | ✓ |
fetch_web_sources.py | Focused fetch of mapped URLs into sources/web/ + index | ✓ | ✓ | — |
recover_web_sources.py | Report mapping gaps; point to recovery prompt | ✓ | ✓ | — |
Import modules
Not run directly — imported by runnable scripts, build tooling, or tests.
| Module | Purpose | Used by |
|---|---|---|
release_version.py | Read/write VERSION, __version__, package pins | bump_release.py, build_packages.py, verify_release_version.py |
release_refs.py | release/X.Y.Z and tag naming helpers | bump_release.py, publish_release.py, verify_release_ready.py, tag_release.py |
release_ci_gates.py | Required GitLab job lists (branch vs tag) | verify_release_ready.py |
gitlab_api.py | Minimal GitLab REST API client | release_ci_gates.py |
web_source_mapping_lib.py | Parse docs/web-source-mapping.md | check_web_source_tags.py, fetch_web_sources.py |
web_robots_lib.py | robots.txt allow/deny checks for fetcher | fetch_web_sources.py |
web_archive_backends.py | Local, git-sources, and S3 archive backends | fetch_web_sources.py |
a2c_cli_entry.py | PyInstaller entrypoint for CLI | build_a2c_cli_binary.py |
a2c_tui_entry.py | PyInstaller entrypoint for TUI | build_a2c_tui_binary.py |
Planned layout
Future subfolders are described in release-orchestration.md. Until migration, all entrypoints remain at scripts/ root for stable paths in ADRs and CI.