aviato 0.3.0__tar.gz

aviato-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Mattas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aviato-0.3.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: aviato
+Version: 0.3.0
+Summary: Reusable GitHub policy, CI, release, and onboarding conventions.
+License-Expression: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: zizmor==1.25.2
+Requires-Dist: bashlex==0.18
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: build==1.5.0; extra == "dev"
+Requires-Dist: mypy==2.1.0; extra == "dev"
+Requires-Dist: pytest==9.0.3; extra == "dev"
+Requires-Dist: pytest-cov==7.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.16; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260518; extra == "dev"
+Requires-Dist: setuptools>=69; extra == "dev"
+Requires-Dist: yamllint==1.35.1; extra == "dev"
+Dynamic: license-file

aviato-0.3.0/README.md

@@ -0,0 +1,331 @@
+<p align="center">
+  <img src="docs/assets/aviato.jpg" alt="Aviato — Where code takes flight" width="520">
+</p>
+
+# Aviato
+
+Aviato is a reusable GitHub policy, CI, release, and onboarding conventions
+library. It centralizes shared workflows, rulesets, and operator tooling without
+keeping a committed inventory of consumer repositories.
+
+## Policy
+
+`aviato/library/policy.yml` is the canonical source for policy constants (it lives
+inside the package so it ships in the wheel for installed ruleset rendering).
+
+Release tags must match:
+
+```text
+^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-(alpha|beta)[0-9]+)?$
+```
+
+Accepted examples: `1.2.3`, `1.2.3-alpha1`, `1.2.3-beta2`.
+
+Rejected examples: `v1.2.3` (no `v` prefix allowed), `1.2.3-beta.1`,
+`build-20260519.0215`.
+
+Release publishing is tag-only. Legacy `release/*` branches should be cleaned up
+in consumer repositories rather than supported by release publish workflows.
+
+## What Is Here
+
+- `aviato/library/policy.yml` - canonical policy constants (packaged; ships in the wheel).
+- `aviato/library/rulesets.yml` - ruleset manifest.
+- `aviato/library/rulesets/*.json` - GitHub ruleset templates.
+- `.github/workflows/reusable-*.yml` - reusable CI, release, deploy, and security workflows.
+- `templates/profile-*.yml`, `templates/consumer-automation.yml` - composed, copyable
+  caller-workflow examples for consumer repos (rendered from the scaffold bundles; they
+  include the always-on security baseline, §2.13). Use these composed callers rather than
+  hand-wiring a single reusable workflow, which can omit the required baseline.
+- `aviato/` - Python CLI implementation.
+- `scripts/*.sh` - compatibility wrappers and validation entrypoints.
+
+## Commands
+
+Install locally:
+
+```bash
+python3 -m pip install -e .[dev]
+```
+
+Audit repositories under a local root:
+
+```bash
+aviato audit .
+```
+
+Audit one repository:
+
+```bash
+aviato audit --repo /Users/amattas/GitHub/example
+```
+
+Dry-run the rulesets resolved from an adopted repository's declaration:
+
+```bash
+aviato apply-rulesets amattas/example --declaration /path/to/example/.github/aviato.yaml
+```
+
+Apply the reviewed declaration-resolved rulesets:
+
+```bash
+aviato apply-rulesets amattas/example --declaration /path/to/example/.github/aviato.yaml --apply
+```
+
+For a solo-maintainer repository, persist the liveness exception in its
+declaration rather than relying on an ephemeral CLI flag:
+
+```yaml
+overrides:
+  settings:
+    default_branch:
+      required_reviews: 0
+```
+
+Then dry-run and apply using `--declaration` as above. Remove that override
+before or in the same settings change that makes another reviewer eligible.
+
+Validate this repository:
+
+```bash
+./scripts/validate.sh
+```
+
+Onboard or provision consumers with an explicit published Library pin:
+
+```bash
+aviato onboard /path/to/repo --profile python-library --pin 1.2.3 --write
+aviato onboard amattas/example --profile python-library --pin 1.2.3 --open-pr  # adopt an existing repo via a reviewable scaffold PR
+aviato provision amattas/example --profile node-service --pin 1.2.3
+```
+
+Local mutation is always explicit. `onboard` plans by default; `--write` applies
+the plan, `--allow-dirty` acknowledges a non-clean worktree, and
+`--migrate-profile` authorizes changing an existing declaration's stable profile
+identity. Repeat `--var KEY=VALUE` for non-secret profile variables. Provisioning
+is private by default; add `--public` only when the new repository is intended to
+be public. `--override-version-pin` is the exceptional recovery switch for a
+recorded-pin mismatch; ordinary pin movement uses `aviato repin`.
+
+```bash
+aviato onboard /path/to/repo --profile python-service --pin 1.2.3 --docs --var serve-pages=true --write
+aviato onboard /path/to/repo --profile python-service --pin 1.2.3 --migrate-profile --allow-dirty --write
+aviato provision OWNER/REPO --profile node-service --pin 1.2.3 --var project-name=app --var language-variant=typescript --public
+aviato sync /path/to/repo --override-version-pin
+```
+
+`--docs` on `onboard`/`provision` composes the opt-in docs deploy.
+
+Fresh writes and provisioning refuse to invent a default pin. The requested pin
+must already resolve to a published Aviato tag or branch; use
+`--allow-unresolved-pin` only for intentional offline or test scaffolds. Already
+adopted repositories keep their recorded pin during onboarding; use
+`aviato repin` to move it.
+
+Consumer lifecycle commands (see `aviato <command> --help` for the full flags):
+
+```bash
+aviato render-rulesets                       # print rendered ruleset JSON
+aviato apply-rulesets OWNER/REPO --declaration /path/.github/aviato.yaml --apply  # override-aware apply: resolves checks/approvals through the consumer's declared overrides (what settings-drift remediation recommends)
+aviato doctor /path/to/consumer              # classify managed artifacts + probe health
+aviato sync /path/to/consumer                # materialize managed artifacts incl. caller workflows
+aviato scan /path/a /path/b [--fix --audit]  # fleet diagnosis; --fix opens managed-file proposals, --audit surfaces open settings-drift tracking issues
+aviato drift-report /path/to/consumer [--file-only|--settings-only] [--require-settings]  # file + settings drift report
+aviato reconcile /path/to/consumer ISSUE --confirm DIFF_ID  # operator-gated settings apply, diff-bound
+aviato complete-protection /path/to/consumer # idempotently (re-)apply full branch protection
+aviato repin /path/to/consumer 1.3.0 [--write | --open-pr]  # move the Library version pin; --open-pr opens a reviewable re-pin proposal
+aviato offboard /path/to/consumer [--write --delete-files | --open-pr]  # remove from Aviato management; --open-pr opens a reviewable removal proposal
+aviato next-version --current 1.2.3 --commit "feat: x"  # derive the next SemVer from Conventional Commits
+aviato bump-version 1.3.0 /path/to/consumer  # write the version into version-source locations
+aviato is-highest 1.2.3 1.0.0 1.2.3          # exit 0 iff arg1 is the highest release among the rest
+aviato lint-actions PATH                     # supply-chain pinning gate (zizmor + fail-closed curl|bash)
+aviato validate                              # validate this repository's policy infrastructure (source checkout only)
+```
+
+`scan` is read-only unless `--fix` is supplied; `--fix` opens managed-file
+proposals and `--audit` also reports the open settings-drift issue. `offboard
+--write` removes Aviato's declaration/management state but preserves managed
+files unless `--delete-files` is also supplied. If `doctor` reports missing or
+corrupt seed integrity state, inspect the files first, then explicitly accept the
+current seed-once contents as the new baseline:
+
+```bash
+aviato scan /path/to/fleet --fix --audit
+aviato offboard /path/to/consumer --write --delete-files
+aviato sync /path/to/consumer --rebaseline-seeds
+```
+
+### Operator setup and live verification
+
+Repository and service controls are deliberately operator-run. Apply the full
+rulesets first; on GitHub plans that do not support tag metadata restrictions,
+the command reports a loud degraded posture while retaining tag deletion and
+non-fast-forward protection. Any unrelated API failure remains fatal.
+
+```bash
+aviato apply-rulesets OWNER/REPO --apply --declaration /path/to/checkout/.github/aviato.yaml
+gh api --paginate repos/OWNER/REPO/rulesets
+# The list endpoint is only a summary. Fetch every full live payload for amattas/aviato:
+for id in $(gh api --paginate repos/amattas/aviato/rulesets --jq '.[].id'); do
+  gh api "repos/amattas/aviato/rulesets/${id}"
+done
+gh api --method PUT repos/OWNER/REPO/automated-security-fixes
+```
+
+For PyPI or TestPyPI Trusted Publishing, register the consumer repository's
+`.github/workflows/aviato-ci.yml` and protected `pypi` environment with the
+project. The publishing job must remain in that consumer workflow so its OIDC
+identity matches the registration; do not fall back to an API token.
+
+```bash
+# Required reviewers are an operator prerequisite; configure at least one in protection.json.
+gh api --method PUT repos/OWNER/REPO/environments/pypi --input protection.json
+gh api repos/OWNER/REPO/environments/pypi
+```
+
+In the PyPI/TestPyPI project UI, enter exactly: owner `OWNER`, repository
+`REPO`, workflow `aviato-ci.yml`, environment `pypi`. Registration is an
+out-of-band service operation; Aviato never stores a publishing credential.
+GitHub enforces the configured environment gate, and `aviato doctor` plus
+operator verification checks the required-reviewer posture when applicable.
+Only the App Store workflow has an additional explicit fail-closed runtime
+preflight of the environment's reviewer list; the PyPI publisher does not.
+
+Docs are always versioned onto `gh-pages` when `docs: true`. To serve them, set
+the non-secret profile variable `serve-pages: true`, configure Pages for the
+custom workflow build type, and verify the same release run contains a successful
+job ID `deploy`, with display name `Deploy GitHub Pages`. That job invokes the
+`actions/deploy-pages` action; `deploy-pages` is the action name, not Aviato's
+job/check name:
+
+```bash
+gh api --method PUT repos/OWNER/REPO/pages -f build_type=workflow
+gh api repos/OWNER/REPO/pages
+gh run list --repo OWNER/REPO --limit 20
+```
+
+Before treating a rollout as live-verified, run the local gate and inspect the
+exact external evidence (PR check/status SHA, full ruleset payloads, open CodeQL
+alerts, package index entry, Pages URL, and App Store receipt release asset):
+
+```bash
+AVIATO_STRICT_TOOLS=1 ./scripts/validate.sh
+aviato doctor .
+gh api --paginate repos/OWNER/REPO/code-scanning/alerts -f state=open -f tool_name=CodeQL --method GET
+gh pr view PR_NUMBER --repo OWNER/REPO --json mergeable,mergeStateStatus,statusCheckRollup
+gh release view RELEASE_TAG --repo OWNER/REPO --json url,assets
+```
+
+The legacy script names still work:
+
+```bash
+./scripts/audit-repos.sh .
+./scripts/apply-rulesets.sh --repo amattas/example --declaration /path/to/example/.github/aviato.yaml --apply
+```
+
+## Reusable Workflows
+
+- `reusable-python-ci.yml`
+- `reusable-node-ci.yml`
+- `reusable-swift-ci.yml`
+- `reusable-release.yml`
+- `reusable-release-gate.yml`
+- `reusable-docker-ghcr.yml`
+- `reusable-pypi-publish.yml`
+- `reusable-docs-pages.yml`
+- `reusable-app-store-connect.yml`
+- `reusable-security-baseline.yml`
+- `reusable-common-lint.yml`
+- `reusable-consumer-automation.yml`
+
+`reusable-release.yml` is split into a read-only derive job and a write release
+job. `reusable-release-gate.yml` exports the validated commit as a `gated-sha`
+output; the deploy workflows check out that exact commit — never the mutable
+tag — and re-verify the tag still points at it before publishing. The GHCR
+publish promotes the exact Trivy-scanned OCI archives by digest (no rebuild
+between scan and push), and the PyPI/GHCR publish jobs run in GitHub deployment
+environments (defaults `pypi`/`ghcr`).
+
+Language CI workflows share the same command contract:
+
+- `working-directory`
+- `install-command`
+- `lint-command`
+- `test-command`
+- `build-command`
+- `run-install`
+- `run-lint`
+- `run-tests`
+- `run-build`
+
+`reusable-node-ci.yml` defaults to Node 24 and blocks npm versions below 11.10
+(the floor for `min-release-age` support) before any install command. It sets
+`ignore-scripts=true`, `engine-strict=true`, and `min-release-age=7`; Node
+scaffolds also write those values into managed `.npmrc` files and declare
+`node >=24` / `npm >=11.10` in package manifests so local and CI installs share
+the same supply-chain posture. Node CI uses `npx --no-install` for local tool
+bins, and the common lint gate rejects unsafe plain `npx` registry fetches.
+
+## Profile Templates
+
+The `templates/profile-*.yml` files compose CI, security, release validation,
+and deployment jobs for common repo shapes:
+
+- `profile-python-service.yml`
+- `profile-python-library.yml`
+- `profile-python-component.yml`
+- `profile-node-service.yml`
+- `profile-swift-app.yml`
+
+These are **examples rendered from** the authoritative scaffold bundles
+(`aviato/library/scaffold/files/wf-*.yml`); `aviato validate` fails if they drift,
+and `python3 scripts/regen-templates.py` regenerates them. Prefer materializing the
+real workflows with `aviato sync` / `aviato onboard --write`; committed examples
+use the literal `EXAMPLE_PIN` placeholder instead of a production ref. Use
+`aviato onboard TARGET --profile PROFILE` to list the exact artifacts, secrets,
+rulesets, and protected deployment environments for a repository. The Python
+library plan requires `pypi`, container profiles require `ghcr`, and the Swift
+app plan requires the configured `environment-name` (`app-store-connect` by
+default); each named environment must exist with at
+least one required reviewer before deployment. Zero-deploy profiles explicitly
+report that none are required. The common scaffold also seeds `CONTRIBUTING.md`,
+`.github/CODEOWNERS`, and issue/PR templates (seed-once; the consumer owns them
+after seeding).
+
+When `docs: true`, Aviato scaffolds a **Zensical** docs site under `website/`,
+versioned onto a docs branch by a mike fork (Mermaid rendering and sitemap
+generation included; search is Zensical's built-in search, no external service).
+The docs publish workflow installs, versions, builds, and publishes the site
+on release refs;
+`docs-retention` defaults to 0, which keeps every released version's docs.
+
+The Library's own `.github/aviato.yaml` uses the internal `aviato-library`
+profile and `bootstrap: true`. `local-install: true` is valid only for this
+structural Library bootstrap path; reusable workflows fail before
+`pip install -e .` if a consumer tries to enable it.
+
+## App Store Connect
+
+The App Store Connect workflow runs on release tags, uses macOS, and must be
+called behind a protected deployment environment. Required secrets are:
+
+- `APP_STORE_CONNECT_ISSUER_ID`
+- `APP_STORE_CONNECT_KEY_ID`
+- `APP_STORE_CONNECT_API_PRIVATE_KEY`
+- `APPLE_CERTIFICATE_P12_BASE64`
+- `APPLE_CERTIFICATE_PASSWORD`
+- `APPLE_PROVISIONING_PROFILE_BASE64`
+
+The caller must provide project-specific Xcode inputs such as scheme, workspace
+or project, export options plist, and version/build-number command.
+
+Apple/App Store Connect credentials are scoped to the specific workflow steps
+that need them. The caller-controlled version command runs before signing assets
+are installed, so Apple secrets are not exposed to arbitrary versioning logic.
+
+## Architecture
+
+See `docs/requirements/` for outcomes and constraints,
+`docs/specifications/` for precise testable behavior, `docs/architecture/` for
+the current implementation map, and `docs/security/` for threats and controls.
+The § citation index remains `docs/requirements/README.md`.

aviato-0.3.0/aviato/__init__.py

@@ -0,0 +1,33 @@
+"""Aviato policy and repository tooling."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from importlib import metadata
+from pathlib import Path
+
+__all__ = ["__version__"]
+
+_SEMVER_RE = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:alpha|beta)[0-9]+)?$")
+
+
+def _source_version() -> str:
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    project = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("project")
+    version = project.get("version") if isinstance(project, dict) else None
+    if not isinstance(version, str):
+        raise RuntimeError(f"{pyproject} does not define project.version")
+    if _SEMVER_RE.fullmatch(version) is None:
+        raise RuntimeError(f"{pyproject} project.version is not valid SemVer: {version!r}")
+    return version
+
+
+def _runtime_version() -> str:
+    try:
+        return metadata.version("aviato")
+    except metadata.PackageNotFoundError:
+        return _source_version()
+
+
+__version__ = _runtime_version()

aviato-0.3.0/aviato/audit.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from . import github
+from .github import GitHubAPIError
+from .policy import release_tag_pattern
+from .repos import current_branch, discover_repos, normalize_slug, remote_url, tags, workflow_files
+
+# R3-14/§5.9/§6.1: a bare floating-major tag (`1`, `2`) is a SANCTIONED release alias (the tag
+# ruleset explicitly excludes it from the exact-SemVer pattern), so it is not an "invalid" tag.
+_FLOATING_MAJOR_RE = re.compile(r"[0-9]+")
+
+
+@dataclass
+class AuditRow:
+    path: str
+    slug: str
+    default_branch: str
+    local_branch: str
+    workflows: str
+    default_branch_requires_pr: str
+    force_push_blocked: str
+    tag_ruleset: str
+    invalid_tags: str
+
+
+def _requires_pr(rules: list[dict[str, Any]], protection: dict[str, Any]) -> bool:
+    rules_pr = any(rule.get("type") == "pull_request" for rule in rules)
+    classic_pr = (
+        "required_pull_request_reviews" in protection and protection.get("required_pull_request_reviews") is not None
+    )
+    return rules_pr or classic_pr
+
+
+def _force_push_blocked(rules: list[dict[str, Any]], protection: dict[str, Any]) -> bool:
+    rules_nff = any(rule.get("type") == "non_fast_forward" for rule in rules)
+    allow_force_pushes = protection.get("allow_force_pushes")
+    classic_force_blocked = isinstance(allow_force_pushes, dict) and allow_force_pushes.get("enabled") is not True
+    return rules_nff or classic_force_blocked
+
+
+def audit_repo(repo: Path, *, root: Path, policy: dict[str, Any]) -> AuditRow:
+    pattern = re.compile(release_tag_pattern(policy))
+    repo_path = repo.resolve()
+    root_path = root.resolve()
+    rel = "." if repo_path == root_path else str(repo_path).removeprefix(str(root_path) + "/")
+    remote = remote_url(repo)
+    slug = normalize_slug(remote)
+    invalid_tags = ",".join(
+        tag for tag in tags(repo) if not pattern.fullmatch(tag) and not _FLOATING_MAJOR_RE.fullmatch(tag)
+    )[:500]
+    local_branch = current_branch(repo)
+    workflows = workflow_files(repo)
+
+    if not slug:
+        return AuditRow(rel, "", "", local_branch, workflows, "NO_REMOTE", "NO_REMOTE", "NO_REMOTE", invalid_tags)
+
+    try:
+        default = github.default_branch(slug)
+    except GitHubAPIError:
+        default = ""
+
+    if not default:
+        return AuditRow(rel, slug, "", local_branch, workflows, "API_ERROR", "API_ERROR", "API_ERROR", invalid_tags)
+
+    # These reads fail closed (§2.7): an ambiguous (auth/5xx/rate-limit) read raises
+    # rather than reporting a false "no protection". Degrade the whole row to
+    # API_ERROR rather than crash the audit, so one flaky repo doesn't sink the run.
+    try:
+        rules = github.active_branch_rules(slug, default)
+        protection = github.classic_branch_protection(slug, default)
+        tag_rulesets = github.tag_ruleset_names(slug)
+    except GitHubAPIError:
+        err = "API_ERROR"
+        return AuditRow(rel, slug, default, local_branch, workflows, err, err, err, invalid_tags)
+
+    return AuditRow(
+        path=rel,
+        slug=slug,
+        default_branch=default,
+        local_branch=local_branch,
+        workflows=workflows,
+        default_branch_requires_pr="yes" if _requires_pr(rules, protection) else "no",
+        force_push_blocked="yes" if _force_push_blocked(rules, protection) else "no",
+        tag_ruleset=",".join(tag_rulesets) if tag_rulesets else "no",
+        invalid_tags=invalid_tags,
+    )
+
+
+def audit_repos(repos: Iterable[Path], *, root: Path, policy: dict[str, Any]) -> list[AuditRow]:
+    return [audit_repo(repo, root=root, policy=policy) for repo in repos]
+
+
+def discover_and_audit(root: Path, *, policy: dict[str, Any]) -> list[AuditRow]:
+    return audit_repos(discover_repos(root), root=root, policy=policy)
+
+
+def render_tsv(rows: list[AuditRow]) -> str:
+    fields = list(AuditRow.__dataclass_fields__.keys())
+    lines = ["\t".join(fields)]
+    for row in rows:
+        values = [str(getattr(row, field)) for field in fields]
+        lines.append("\t".join(values))
+    return "\n".join(lines)
+
+
+def render_json(rows: list[AuditRow]) -> str:
+    return json.dumps([asdict(row) for row in rows], indent=2)