github-agent-cli 1.2.2__tar.gz → 1.3.0__tar.gz

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/.ghagent.json

@@ -10,6 +10,8 @@
   "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"],
+  "exclude_dirs": ["site"],
+  "safe_email_domains": [],
   "ignore_rules": [],
   "topic_min": 8,
   "topic_max": 20,

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/.github/workflows/ci.yml

@@ -30,6 +30,25 @@ jobs:
       - name: The CLI answers
         run: python tools/ghagent.py --version
 
+  lint:
+    name: Static analysis (ruff, mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Install the analysers (development only)
+        run: python -m pip install --disable-pip-version-check ruff mypy
+
+      - name: ruff
+        run: python -m ruff check .
+
+      - name: mypy
+        run: python -m mypy
+
   documents:
     name: Documents and repository contracts
     runs-on: ubuntu-latest
@@ -170,3 +189,69 @@ jobs:
 
       - name: The image lints the documents
         run: docker run --rm --volume "$PWD:/repo" ghagent:ci doc --root .
+  manifests:
+    name: Package-manager manifests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Homebrew formula syntax
+        run: ruby -c packaging/homebrew/github-agent-cli.rb
+
+      - name: Homebrew formula downloads and verifies
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import hashlib
+          import json
+          import pathlib
+          import re
+          import urllib.request
+
+          text = pathlib.Path("packaging/homebrew/github-agent-cli.rb").read_text(encoding="utf-8")
+          url = re.search(r'^\s*url "([^"]+)"', text, re.M).group(1)
+          expected = re.search(r'^\s*sha256 "([0-9a-f]{64})"', text, re.M).group(1)
+          with urllib.request.urlopen(url, timeout=60) as response:
+              data = response.read()
+          actual = hashlib.sha256(data).hexdigest()
+          print(f"downloaded {url} ({len(data)} bytes), sha256 {actual}")
+          if actual != expected:
+              raise SystemExit("formula sha256 does not match the downloaded sdist")
+          version = re.search(r"github_agent_cli-([0-9.]+)\.tar\.gz", url).group(1)
+          pypi = json.load(urllib.request.urlopen("https://pypi.org/pypi/github-agent-cli/json", timeout=60))
+          if pypi["info"]["version"] != version:
+              raise SystemExit(f"formula pins {version}, PyPI serves {pypi['info']['version']}")
+          print(f"formula pins the current PyPI version {version}")
+          PY
+
+      - name: Scoop manifest downloads and verifies
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import hashlib
+          import io
+          import json
+          import pathlib
+          import urllib.request
+          import zipfile
+
+          manifest = json.loads(pathlib.Path("packaging/scoop/github-agent-cli.json").read_text(encoding="utf-8"))
+          with urllib.request.urlopen(manifest["url"], timeout=60) as response:
+              data = response.read()
+          actual = hashlib.sha256(data).hexdigest()
+          print(f"downloaded {manifest['url']} ({len(data)} bytes), sha256 {actual}")
+          if actual != manifest["hash"]:
+              raise SystemExit("scoop hash does not match the downloaded bundle")
+          with zipfile.ZipFile(io.BytesIO(data)) as archive:
+              names = archive.namelist()
+          required = f"{manifest['extract_dir']}/{manifest['bin']}"
+          if required not in names:
+              raise SystemExit(f"the bundle has no {required}")
+          if not any(name.startswith(f"{manifest['extract_dir']}/lib/ghagent.py") for name in names):
+              raise SystemExit("the bundle has no lib/ghagent.py")
+          print(f"bundle layout is valid, {len(names)} entries")
+          PY

github_agent_cli-1.3.0/.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "23 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4

github_agent_cli-1.3.0/.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      - "README.md"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build the site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install MkDocs Material
+        run: python -m pip install --disable-pip-version-check "mkdocs-material>=9.6,<10"
+
+      - name: Build
+        run: python -m mkdocs build --verbose
+
+      - name: Upload the artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    # A pull request must build the site but never publish it.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v5

github_agent_cli-1.3.0/.github/workflows/release-draft.yml

@@ -0,0 +1,81 @@
+name: Release draft
+
+# The recommendation was "automate releases with release-please or semantic-release". This
+# project cannot take either: the CHANGELOG is hand-written and machine-verified (Keep a
+# Changelog 2.0.0 with `[Unreleased]`), and release-please would own the file and rewrite the
+# history of the entries. What is left is the mechanical part — the release body — and that is
+# what this workflow automates, as a DRAFT release:
+#
+#   * a draft is not published, so `publish.yml` (triggered by `release: published`) does not
+#     fire and nothing reaches PyPI by accident;
+#   * the body is generated by `ghagent changelog notes <version>` from the CHANGELOG, so it
+#     cannot drift from the file;
+#   * a human reads the draft and presses Publish, which is the irreversible step.
+#
+# Signed commits are a repository setting (`git commit -S` + a key); automation cannot grant it,
+# so it stays a documented requirement in docs/PACKAGING.md rather than a workflow step.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to build the draft for (for example v1.3.0)"
+        required: true
+      prerelease:
+        description: "Mark as a pre-release"
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+jobs:
+  draft:
+    name: Draft the release notes from CHANGELOG
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Check out the tag
+        run: git checkout "${{ inputs.tag }}"
+
+      - name: The CHANGELOG knows this version
+        run: python tools/ghagent.py changelog check
+
+      - name: Render the body
+        run: |
+          set -euo pipefail
+          VERSION="${TAG#v}"
+          python tools/ghagent.py changelog notes "$VERSION" > release-notes.md
+          test -s release-notes.md
+          {
+            echo "## What changed"
+            echo
+            cat release-notes.md
+            echo
+            echo "## Verification"
+            echo
+            echo '```bash'
+            echo "ghagent --version   # github-agent $VERSION"
+            echo "python tests/run_tests.py"
+            echo '```'
+          } > body.md
+        env:
+          TAG: ${{ inputs.tag }}
+
+      - name: Create the draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          FLAGS=""
+          if [ "${{ inputs.prerelease }}" = "true" ]; then FLAGS="--prerelease"; fi
+          gh release create "${{ inputs.tag }}" --draft $FLAGS \
+            --title "${{ inputs.tag }}" --notes-file body.md
+          echo "::notice::Draft created. Read it, then press Publish to start publish.yml (PyPI)."

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/.gitignore

@@ -1,6 +1,7 @@
 # agent work directories
 .ghagent/
 .install.json
+.ragraf/
 
 # python
 __pycache__/
@@ -14,6 +15,10 @@ build/
 .venv/
 .venv-*/
 
+# documentation site (mkdocs build)
+site/
+.cache/
+
 # editors and OS
 .vscode/
 .idea/

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/AGENTS.md

@@ -23,7 +23,9 @@ uv tool install github-agent-cli            # recommended: isolated CLI
 pipx install github-agent-cli               # alternative
 pip install github-agent-cli                # Python 3.11+
 pip install "github-agent-cli[png]"         # optional Pillow: PNG banner output only
-ghagent --version                       # github-agent 1.2.2
+brew install paulmann/homebrew-github-agent-cli/github-agent-cli
+scoop bucket add github-agent-cli https://github.com/paulmann/scoop-github-agent-cli && scoop install github-agent-cli
+ghagent --version                       # github-agent 1.3.0
 ```
 
 The wheel ships the CLI only. The pack — `skills/`, `tools/`, `tests/`, `reference/`, `wiki/`,

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/AGENTS.ru.md

@@ -26,7 +26,9 @@ uv tool install github-agent-cli            # рекомендуется: изо
 pipx install github-agent-cli               # альтернатива
 pip install github-agent-cli                # Python 3.11+
 pip install "github-agent-cli[png]"         # необязательный Pillow: только PNG
-ghagent --version                       # github-agent 1.2.2
+brew install paulmann/homebrew-github-agent-cli/github-agent-cli
+scoop bucket add github-agent-cli https://github.com/paulmann/scoop-github-agent-cli && scoop install github-agent-cli
+ghagent --version                       # github-agent 1.3.0
 ```
 
 Wheel содержит только CLI. Пакет — `skills/`, `tools/`, `tests/`, `reference/`, `wiki/`,

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/CHANGELOG.md

@@ -6,6 +6,71 @@ All notable changes to this project are documented here. The format is
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-11-01
+
+### Added
+
+- `docs/FIELD-NOTES.md`: ten defects that real repositories found, anonymised — the symptom, the
+  cause, the rule that changed and the fixture that now holds it. Published as a page of the
+  documentation site.
+- A documentation site on GitHub Pages: `mkdocs.yml` (Material), `docs/index.md`,
+  `.github/workflows/docs.yml` (build on every pull request, deploy from `main`) and
+  `hooks/repo_links.py`, which points a link that leaves `docs/` at the repository instead of at a
+  page that does not exist.
+- `.github/workflows/codeql.yml` (CodeQL, security-and-quality queries) and a `lint` job in CI:
+  `ruff` and `mypy` with their configuration in `pyproject.toml`. Both are development tools — the
+  runtime dependency count stays zero.
+- `.github/workflows/release-draft.yml`: a manual workflow that renders the release body from the
+  CHANGELOG (`changelog notes`) and creates a **draft** release. A draft does not trigger
+  `publish.yml`, so nothing reaches PyPI before a human presses Publish.
+- `tools/make_demo.py` and `assets/demo.gif`: the README animation is rendered from the real
+  output of three commands, so it cannot show anything the tool did not print.
+- README sections **Why this exists** and **How it compares** (with `markdownlint`, `vale`,
+  `action-gh-release`, pre-commit, `release-please` and the community-health files) in all six
+  languages.
+- `.ghagent.json` keys `exclude_dirs` (build output whose name the pack cannot know, e.g. `site`)
+  and `safe_email_domains` (role domains of this repository).
+- `packaging/homebrew/github-agent-cli.rb`: a Homebrew formula that installs the PyPI sdist
+  `github_agent_cli-1.2.2.tar.gz` (sha256 `f60d17b1…e14ae`) into a virtualenv with `python@3.13`,
+  with `livecheck` reading the PyPI JSON API. Canonical copy: `paulmann/homebrew-github-agent-cli`.
+- `packaging/scoop/github-agent-cli.json`: a Scoop manifest for the Windows bundle
+  `github-agent-cli-1.2.2-windows-x64.zip` (sha256 `2676f33b…c85a4`), `depends: python`,
+  `checkver`/`autoupdate` from the PyPI JSON API and the release `SHA256SUMS.txt`. Canonical copy:
+  `paulmann/scoop-github-agent-cli`.
+- A Windows bundle in the release assets: `ghagent.cmd` plus the wheel contents under `lib/`. It was
+  executed on Windows before upload (`--version`, `audit . --min-score 90`).
+- CI job `manifests`: `ruby -c` for the formula, a real download of both URLs with the SHA-256
+  compared against the manifest, and a layout check of the bundle. A wrong hash or a stale version
+  fails the pull request.
+- `packaging/README.md`: what each manifest installs, where the canonical copy lives and the bump
+  procedure for both.
+
+### Changed
+
+- `md.link-local`: inside a wiki checkout — detected from `_Sidebar.md` or `_Footer.md` — a page
+  name resolves to `Page.md`, including names with dots (`Migration-3.x-to-4.0`). In an ordinary
+  repository the same link stays an error, because there it is a 404.
+- `md.h1`: `_Sidebar.md`, `_Footer.md` and `_Header.md` are wiki furniture and are reported as a
+  note, not as a document without a title.
+- `doc` and `privacy` share one walker, which skips every dot-directory except `.github/` and
+  `.well-known/`; `doc` also honours `ignore_rules` from `.ghagent.json`, which only `audit` read
+  before.
+- `changelog.link-refs`: missing link references are a warning, not an error — Keep a Changelog
+  makes them optional. `changelog.types`: a grouping subtitle is dropped before the lookup, so
+  `### Added — template language` is `Added`.
+- `assets render`: chips come from the declared keywords (languages are the fallback), emoji are
+  stripped from the title, and a title or tagline that would be cut is a warning that names the
+  limit.
+- `meta check --repo <slug>` reads the repository through `gh api` instead of validating the empty
+  arguments it was given.
+- `audit`: `wiki-source` is skipped, not failed, when the tree has no `wiki/` directory.
+- `wiki verify`: the target is an explicit `--out`, then a `--wiki-dir` that already looks like a
+  wiki checkout, then the build; the header names the directory that was read, and a repository
+  with neither sources nor a build gets one note instead of an error.
+- `docs/PACKAGING.md`: the Homebrew and Scoop section is no longer "deferred" — it lists both
+  manifests, the measured hashes and how the CI job verifies them.
+- The six READMEs and `AGENTS.md` gained the `brew` and `scoop` install commands.
+
 ## [1.2.2] - 2026-10-30
 
 ### Changed
@@ -135,7 +200,8 @@ All notable changes to this project are documented here. The format is
 
 - The pack ships without tokens, absolute machine paths or personal addresses; the privacy rule fails the build if one appears, and a self-test enforces it on the pack itself.
 
-[Unreleased]: https://github.com/paulmann/github-agent/compare/v1.2.2...HEAD
+[Unreleased]: https://github.com/paulmann/github-agent/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/paulmann/github-agent/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/paulmann/github-agent/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/paulmann/github-agent/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/paulmann/github-agent/compare/v1.1.0...v1.2.0

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/CHANGELOG.ru.md

@@ -6,6 +6,29 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-11-01
+
+### Добавлено
+
+- `packaging/homebrew/github-agent-cli.rb`: формула Homebrew, которая ставит sdist с PyPI
+  `github_agent_cli-1.2.2.tar.gz` (sha256 `f60d17b1…e14ae`) в virtualenv с `python@3.13`,
+  `livecheck` читает JSON API PyPI. Каноническая копия: `paulmann/homebrew-github-agent-cli`.
+- `packaging/scoop/github-agent-cli.json`: манифест Scoop для Windows-бандла
+  `github-agent-cli-1.2.2-windows-x64.zip` (sha256 `2676f33b…c85a4`), `depends: python`,
+  `checkver`/`autoupdate` из JSON API PyPI и `SHA256SUMS.txt` релиза. Каноническая копия:
+  `paulmann/scoop-github-agent-cli`.
+- Windows-бандл в ассетах релиза: `ghagent.cmd` плюс содержимое колеса в `lib/`. Перед загрузкой
+  он был запущен на Windows (`--version`, `audit . --min-score 90`).
+- CI-job `manifests`: `ruby -c` для формулы, реальная загрузка обоих URL со сверкой SHA-256 и
+  проверка раскладки бандла. Неверный хэш или устаревшая версия валят pull request.
+- `packaging/README.md`: что ставит каждый манифест, где каноническая копия и как обновлять.
+
+### Изменено
+
+- `docs/PACKAGING.md`: раздел про Homebrew и Scoop больше не «отложенный» — там оба манифеста,
+  измеренные хэши и проверка в CI.
+- В шесть README и `AGENTS.md` добавлены команды установки через `brew` и `scoop`.
+
 ## [1.2.2] - 2026-10-30
 
 ### Изменено
@@ -135,7 +158,8 @@
 
 - Пакет поставляется без токенов, абсолютных путей машины и личных адресов; правило приватности роняет сборку, если такое появится, а самопроверка следит за самим пакетом.
 
-[Unreleased]: https://github.com/paulmann/github-agent/compare/v1.2.2...HEAD
+[Unreleased]: https://github.com/paulmann/github-agent/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/paulmann/github-agent/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/paulmann/github-agent/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/paulmann/github-agent/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/paulmann/github-agent/compare/v1.1.0...v1.2.0

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/CITATION.cff

@@ -5,8 +5,8 @@ abstract: "Repository and wiki steward for AI agents: audits README, CHANGELOG a
 type: software
 authors:
   - name: "github-agent contributors"
-version: 1.2.2
-date-released: 2026-10-30
+version: 1.3.0
+date-released: 2026-11-01
 license: MIT
 repository-code: "https://github.com/paulmann/github-agent"
 keywords:

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/CONTRIBUTING.md

@@ -27,7 +27,7 @@ for the map, [docs/RULES.md](docs/RULES.md) for the rule catalogue and
 git clone https://github.com/paulmann/github-agent.git
 cd github-agent
 pip install -e .
-ghagent --version           # github-agent 1.2.2
+ghagent --version           # github-agent 1.3.0
 ghagent selftest            # must print PASS
 python tests/run_tests.py   # the same suite, full output
 ```

{github_agent_cli-1.2.2 → github_agent_cli-1.3.0}/CONTRIBUTING.ru.md

@@ -27,7 +27,7 @@
 git clone https://github.com/paulmann/github-agent.git
 cd github-agent
 pip install -e .
-ghagent --version           # github-agent 1.2.2
+ghagent --version           # github-agent 1.3.0
 ghagent selftest            # должно напечатать PASS
 python tests/run_tests.py   # тот же набор тестов, полный вывод
 ```