github-agent-cli 1.2.1__tar.gz

github_agent_cli-1.2.1/.dockerignore

@@ -0,0 +1,36 @@
+# Version control and history
+.git
+.gitignore
+.gitattributes
+
+# Build outputs
+dist
+build
+*.egg-info
+*.whl
+*.tar.gz
+
+# Caches and generated state
+**/__pycache__
+**/*.py[cod]
+.ghagent
+.install.json
+.pytest_cache
+.mypy_cache
+.ruff_cache
+
+# Virtual environments
+.venv
+venv
+env
+
+# Local reports
+AUDIT.md
+report.md
+audit.json
+
+# Editors and OS
+.vscode
+.idea
+Thumbs.db
+desktop.ini

github_agent_cli-1.2.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

github_agent_cli-1.2.1/.ghagent.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "Configuration read by tools/ghagent.py; paths are relative to this file.",
+  "owner_repo": "paulmann/github-agent",
+  "default_branch": "main",
+  "readme": "README.md",
+  "agents": "AGENTS.md",
+  "changelog": "CHANGELOG.md",
+  "docs_dir": "docs",
+  "wiki_dir": "wiki",
+  "wiki_manifest": "wiki/wiki.json",
+  "ci_workflow": ".github/workflows/ci.yml",
+  "require_files": ["AGENTS.md", "LICENSE", "pyproject.toml", "tests/run_tests.py", "tools/ghagent.py"],
+  "ignore_rules": [],
+  "topic_min": 8,
+  "topic_max": 20,
+  "description_max": 200,
+  "changelog_style": "keepachangelog",
+  "language": "ru"
+}

github_agent_cli-1.2.1/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary

github_agent_cli-1.2.1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change needs a review from the maintainer.
+*       @paulmann

github_agent_cli-1.2.1/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,45 @@
+name: Bug report
+description: A command does not do what the documentation says
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, run the command with --json and paste its output: it names the rule
+        and the file without exposing file contents.
+  - type: input
+    id: version
+    attributes:
+      label: Pack version
+      description: Output of python tools/ghagent.py --version
+      placeholder: github-agent 1.0.0
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and OS
+      placeholder: Python 3.13.15 on Windows 11
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command and its output
+      description: The exact command, the exit code, and the output (use --json if possible)
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+  - type: checkboxes
+    id: hygiene
+    attributes:
+      label: Hygiene
+      options:
+        - label: The output contains no tokens, passwords or personal data
+          required: true

github_agent_cli-1.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security policy
+    url: https://github.com/paulmann/github-agent/security/policy
+    about: Report a vulnerability privately, not in a public issue.
+  - name: Support
+    url: https://github.com/paulmann/github-agent/blob/main/SUPPORT.md
+    about: What to include in a question so it can be answered once.

github_agent_cli-1.2.1/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: A check, a command or a template the pack does not have
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does it solve
+      description: A concrete repository situation, not a general wish
+    validations:
+      required: true
+  - type: textarea
+    id: proof
+    attributes:
+      label: How it can be proven
+      description: Which fixture should fail without the change, and which decoy must stay quiet
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind of change
+      options:
+        - New check
+        - New command
+        - Template or reference
+        - Documentation
+    validations:
+      required: true

github_agent_cli-1.2.1/.github/ISSUE_TEMPLATE/repository-audit.yml

@@ -0,0 +1,24 @@
+name: Repository audit request
+description: Ask for an audit of a public repository against these contracts
+labels: ["audit"]
+body:
+  - type: input
+    id: repo
+    attributes:
+      label: Repository
+      description: owner/name, public, with a README and CHANGELOG
+      placeholder: owner/name
+    validations:
+      required: true
+  - type: textarea
+    id: focus
+    attributes:
+      label: What to look at first
+      description: For example README structure, wiki navigation, changelog dates
+  - type: checkboxes
+    id: consent
+    attributes:
+      label: Consent
+      options:
+        - label: The repository is public and its audit may be discussed in this issue
+          required: true

github_agent_cli-1.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What changed
+
+<!-- One paragraph: what the pull request does and why. -->
+
+## Why
+
+<!-- The problem it solves. Link the issue if there is one. -->
+
+## How it was verified
+
+- [ ] `python tests/run_tests.py` — all checks pass
+- [ ] `python tools/ghagent.py doc --root .` — exit code 0
+- [ ] `python tools/ghagent.py audit .` — exit code 0
+
+## Checklist
+
+- [ ] One logical change; no unrelated edits
+- [ ] A new rule brought a fixture that fails without the change and a decoy that must stay quiet
+- [ ] Documentation updated (AGENTS.md / README.md) if behaviour changed
+- [ ] `[Unreleased]` in CHANGELOG.md mentions the user-visible change

github_agent_cli-1.2.1/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: chore

github_agent_cli-1.2.1/.github/release.yml

@@ -0,0 +1,25 @@
+changelog:
+  exclude:
+    labels:
+      - skip-changelog
+      - dependencies
+  categories:
+    - title: Added
+      labels:
+        - enhancement
+        - feature
+    - title: Fixed
+      labels:
+        - bug
+        - fix
+    - title: Changed
+      labels:
+        - documentation
+        - refactor
+        - performance
+    - title: Security
+      labels:
+        - security
+    - title: Other changes
+      labels:
+        - "*"

github_agent_cli-1.2.1/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  selftest:
+    name: Self-tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.13']
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run the pack self-tests
+        run: python tests/run_tests.py
+
+      - name: The CLI answers
+        run: python tools/ghagent.py --version
+
+  documents:
+    name: Documents and repository contracts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Markdown, links, anchors, privacy
+        run: python tools/ghagent.py doc --root .
+
+      - name: Repository hygiene and file contracts
+        run: python tools/ghagent.py audit . --min-score 80
+
+      - name: Changelog conformance
+        run: python tools/ghagent.py changelog check --repo paulmann/github-agent
+
+      - name: Banner and social preview
+        run: python tools/ghagent.py assets check
+
+      - name: Wiki builds and verifies
+        run: |
+          python tools/ghagent.py wiki build
+          python tools/ghagent.py wiki verify
+
+      - name: No BOM, no CRLF, no machine paths
+        run: python tools/ghagent.py privacy --root .
+
+  package:
+    name: Package (sdist, wheel, clean install)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Build sdist and wheel
+        run: |
+          set -euo pipefail
+          python -m pip install --disable-pip-version-check build twine
+          python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Version, wheel layout and sdist completeness
+        run: |
+          set -euo pipefail
+          EXPECTED_VERSION=$(python - <<'PY'
+          import pathlib
+          import re
+
+          text = pathlib.Path("tools/ghalib/util.py").read_text(encoding="utf-8")
+          print(re.search(r'^PACK_VERSION = "([^"]+)"', text, re.M).group(1))
+          PY
+          )
+          echo "expected version: $EXPECTED_VERSION"
+          test -f "dist/github_agent_cli-${EXPECTED_VERSION}-py3-none-any.whl"
+          test -f "dist/github_agent_cli-${EXPECTED_VERSION}.tar.gz"
+
+          python -m zipfile -l dist/*.whl | tee wheel-contents.txt
+          grep -q '^ghagent.py' wheel-contents.txt
+          grep -q '^ghalib/' wheel-contents.txt
+          if grep -q '^tools/' wheel-contents.txt; then
+            echo "::error::the wheel installs a top-level tools package"
+            exit 1
+          fi
+
+          python -m tarfile -l dist/*.tar.gz | tee sdist-contents.txt
+          for path in action.yml Dockerfile pyproject.toml tools/ghagent.py tests/run_tests.py \
+                      skills reference docs wiki assets; do
+            grep -q "/$path" sdist-contents.txt || {
+              echo "::error::the sdist is missing $path"
+              exit 1
+            }
+          done
+
+      - name: No third-party runtime dependency
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import email
+          import glob
+          import zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          with zipfile.ZipFile(wheel) as archive:
+              name = next(n for n in archive.namelist() if n.endswith(".dist-info/METADATA"))
+              metadata = email.message_from_bytes(archive.read(name))
+          requires = metadata.get_all("Requires-Dist") or []
+          print("Requires-Dist:", requires or "none")
+          unexpected = [item for item in requires if "extra ==" not in item]
+          if unexpected:
+              raise SystemExit(f"runtime dependencies found: {unexpected}")
+          PY
+
+      - name: Install the wheel in a clean virtual environment
+        run: |
+          set -euo pipefail
+          python -m venv "$RUNNER_TEMP/pkg-venv"
+          "$RUNNER_TEMP/pkg-venv/bin/python" -m pip install --disable-pip-version-check dist/*.whl
+          "$RUNNER_TEMP/pkg-venv/bin/python" -m pip list
+          EXPECTED_VERSION=$(python - <<'PY'
+          import pathlib
+          import re
+
+          text = pathlib.Path("tools/ghalib/util.py").read_text(encoding="utf-8")
+          print(re.search(r'^PACK_VERSION = "([^"]+)"', text, re.M).group(1))
+          PY
+          )
+          test "$("$RUNNER_TEMP/pkg-venv/bin/ghagent" --version)" = "github-agent $EXPECTED_VERSION"
+
+      - name: Smoke-test the installed CLI on this checkout
+        run: |
+          set -euo pipefail
+          VENV="$RUNNER_TEMP/pkg-venv"
+          "$VENV/bin/ghagent" doc --root .
+          "$VENV/bin/ghagent" audit . --min-score 80
+
+  container:
+    name: Container image (build and run)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build the image from the Dockerfile
+        run: docker build --tag ghagent:ci .
+
+      - name: The entry point answers
+        run: docker run --rm ghagent:ci --version
+
+      - name: The image audits this checkout
+        run: docker run --rm --volume "$PWD:/repo" ghagent:ci audit . --min-score 80
+
+      - name: The image lints the documents
+        run: docker run --rm --volume "$PWD:/repo" ghagent:ci doc --root .

github_agent_cli-1.2.1/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish
+
+# Manual only, on purpose: a publication is a human decision, and the trigger is flipped to
+# `release: published` only after the first successful upload.
+#
+# Authentication, in order of preference:
+#   1. Trusted Publishing (OIDC): add a trusted publisher for this project on PyPI, then delete
+#      the `password:` line below and the PYPI_API_TOKEN secret. Nothing long-lived is stored.
+#   2. API token: the PYPI_API_TOKEN repository secret (used here until the trusted publisher is
+#      configured). Rotate or revoke it after switching to OIDC.
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: Type "publish" to upload the built distributions to PyPI.
+        required: true
+        default: ""
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Build sdist and wheel
+        run: |
+          set -euo pipefail
+          python -m pip install --disable-pip-version-check build twine
+          python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.confirm == 'publish'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/github-agent-cli
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        # Pinned release, not a moving tag: the uploader holds the credential.
+        # `skip-existing` makes a retry after a partial network failure idempotent.
+        uses: pypa/gh-action-pypi-publish@v1.14.3
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+          print-hash: true

github_agent_cli-1.2.1/.gitignore

@@ -0,0 +1,26 @@
+# agent work directories
+.ghagent/
+.install.json
+
+# python
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# packaging
+dist/
+build/
+*.egg-info/
+.venv/
+.venv-*/
+
+# editors and OS
+.vscode/
+.idea/
+Thumbs.db
+desktop.ini
+
+# local reports
+AUDIT.md
+report.md
+audit.json

github_agent_cli-1.2.1/.pre-commit-hooks.yaml

@@ -0,0 +1,50 @@
+# pre-commit hooks for github-agent.
+#
+# Install once:
+#
+#   pip install pre-commit
+#   # .pre-commit-config.yaml in the consuming repository:
+#   repos:
+#     - repo: https://github.com/paulmann/github-agent
+#       rev: v1.2.1
+#       hooks:
+#         - id: ghagent-doc
+#         - id: ghagent-audit
+#         - id: ghagent-privacy
+#         - id: ghagent-changelog
+#
+# `language: python` makes pre-commit build the wheel from the tagged revision and expose
+# the `ghagent` console script; no separate installation step is needed.
+
+- id: ghagent-doc
+  name: ghagent doc
+  description: Markdown structure, links, anchors, tables and table-of-contents checks.
+  entry: ghagent doc --root .
+  language: python
+  types_or: [markdown]
+  pass_filenames: false
+  require_serial: true
+
+- id: ghagent-audit
+  name: ghagent audit
+  description: Repository hygiene and file contracts; fails below the score threshold.
+  entry: ghagent audit . --min-score 80
+  language: python
+  pass_filenames: false
+  always_run: true
+
+- id: ghagent-privacy
+  name: ghagent privacy
+  description: Secrets, absolute machine paths and personal e-mail addresses in the tree.
+  entry: ghagent privacy --root .
+  language: python
+  pass_filenames: false
+  always_run: true
+
+- id: ghagent-changelog
+  name: ghagent changelog
+  description: Keep a Changelog 2.0.0 conformance of CHANGELOG.md.
+  entry: ghagent changelog check
+  language: python
+  files: ^CHANGELOG\.md$
+  pass_filenames: false