github-agent-cli 1.2.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ghagent.py +511 -0
- ghalib/__init__.py +5 -0
- ghalib/assets.py +475 -0
- ghalib/audit.py +649 -0
- ghalib/changelog.py +473 -0
- ghalib/config.py +52 -0
- ghalib/install.py +189 -0
- ghalib/mdcheck.py +424 -0
- ghalib/meta.py +274 -0
- ghalib/report.py +90 -0
- ghalib/util.py +522 -0
- ghalib/wiki.py +512 -0
- github_agent_cli-1.2.1.dist-info/METADATA +431 -0
- github_agent_cli-1.2.1.dist-info/RECORD +17 -0
- github_agent_cli-1.2.1.dist-info/WHEEL +4 -0
- github_agent_cli-1.2.1.dist-info/entry_points.txt +2 -0
- github_agent_cli-1.2.1.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: github-agent-cli
|
|
3
|
+
Version: 1.2.1
|
|
4
|
+
Summary: Repository and wiki steward: one command per documentation job, standard library only.
|
|
5
|
+
Project-URL: Homepage, https://github.com/paulmann/github-agent
|
|
6
|
+
Project-URL: Documentation, https://github.com/paulmann/github-agent/tree/main/docs
|
|
7
|
+
Project-URL: Repository, https://github.com/paulmann/github-agent
|
|
8
|
+
Project-URL: Changelog, https://github.com/paulmann/github-agent/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Issues, https://github.com/paulmann/github-agent/issues
|
|
10
|
+
Author: github-agent contributors
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: agent,changelog,documentation,github,lint,markdown,repository-audit,wiki
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Documentation
|
|
23
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
24
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Provides-Extra: png
|
|
27
|
+
Requires-Dist: pillow>=10.0; extra == 'png'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# github-agent
|
|
31
|
+
|
|
32
|
+
github-agent is a Python command-line steward for GitHub repositories and their wikis: it
|
|
33
|
+
scores the README, CHANGELOG and community contracts, lints documents, links, anchors and
|
|
34
|
+
tables, scans for leaked secrets, renders the banner and social preview, and keeps the wiki in
|
|
35
|
+
the repository — one command per job.
|
|
36
|
+
|
|
37
|
+
<!-- md-i18n:switcher -->
|
|
38
|
+
**Read this in:** English · [Deutsch](README.de.md) · [中文](README.zh.md) · [हिन्दी](README.hi.md) · [Español](README.es.md) · [Русский](README.ru.md)
|
|
39
|
+
|
|
40
|
+
[](https://github.com/paulmann/github-agent/actions/workflows/ci.yml)
|
|
41
|
+
[](https://www.python.org/)
|
|
42
|
+
[](LICENSE)
|
|
43
|
+
[](pyproject.toml)
|
|
44
|
+
[](tests/run_tests.py)
|
|
45
|
+
|
|
46
|
+
<img src="https://github.com/paulmann/github-agent/raw/main/assets/social-preview.png"
|
|
47
|
+
alt="github-agent — repository and wiki steward for AI agents"
|
|
48
|
+
width="100%">
|
|
49
|
+
|
|
50
|
+
[**Installation**](#installation) · [**Usage**](#usage) · [**Wiki**](https://github.com/paulmann/github-agent/wiki) · [**AGENTS.md**](AGENTS.md) · [**MIGRATION.md**](MIGRATION.md) · [**Packaging**](docs/PACKAGING.md) · [**Changelog**](CHANGELOG.md) · [**Issues**](https://github.com/paulmann/github-agent/issues) · [**Security**](SECURITY.md) · [**Русская версия**](README.ru.md)
|
|
51
|
+
|
|
52
|
+
A repository rarely fails on code; it fails on documentation. The README has no installation
|
|
53
|
+
section, the changelog has no dates, the wiki is three pages without navigation, the banner is
|
|
54
|
+
a broken image, the description is one word. `git push` succeeds, so the defect lives for years.
|
|
55
|
+
|
|
56
|
+
This pack puts a verifiable contract on each of those places and reduces the work to one
|
|
57
|
+
command. It does not write marketing copy and does not invent numbers: it checks what a human
|
|
58
|
+
wrote and refuses to publish what is broken.
|
|
59
|
+
|
|
60
|
+
> **Documentation status.** Every number in this README was measured on 2026-10-30 against
|
|
61
|
+
> version 1.2.0 with the commands named in the table. Long guides live in the
|
|
62
|
+
> [Wiki](https://github.com/paulmann/github-agent/wiki) and [`docs/`](docs/IMPORT.md); the
|
|
63
|
+
> protocol for agents is [`AGENTS.md`](AGENTS.md), the packaging and migration notes are
|
|
64
|
+
> [`docs/PACKAGING.md`](docs/PACKAGING.md) and [`MIGRATION.md`](MIGRATION.md).
|
|
65
|
+
|
|
66
|
+
> **For agents.** Start with [`AGENTS.md`](AGENTS.md): where the pack lives, how to prove the
|
|
67
|
+
> installation is intact, and the single command that replaces each multi-file investigation.
|
|
68
|
+
|
|
69
|
+
## Contents
|
|
70
|
+
|
|
71
|
+
- [Installation](#installation)
|
|
72
|
+
- [Usage](#usage)
|
|
73
|
+
- [What the pack does](#what-the-pack-does)
|
|
74
|
+
- [In numbers](#in-numbers)
|
|
75
|
+
- [Checks that run](#checks-that-run)
|
|
76
|
+
- [Images](#images)
|
|
77
|
+
- [Import into another agent](#import-into-another-agent)
|
|
78
|
+
- [Wiki as documentation](#wiki-as-documentation)
|
|
79
|
+
- [Languages of the documentation](#languages-of-the-documentation)
|
|
80
|
+
- [How it is built](#how-it-is-built)
|
|
81
|
+
- [Limitations](#limitations)
|
|
82
|
+
- [Development](#development)
|
|
83
|
+
- [Contributing](#contributing)
|
|
84
|
+
- [License](#license)
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Installation
|
|
89
|
+
|
|
90
|
+
Python 3.11 or newer is required; CI runs the suite on 3.11 and 3.13. There are no runtime
|
|
91
|
+
dependencies. Four install paths exist, and they are not interchangeable: the package managers
|
|
92
|
+
install the CLI, while the clone is what `ghagent install --profile ... --write` needs because
|
|
93
|
+
the wheel ships only the CLI.
|
|
94
|
+
|
|
95
|
+
### Package managers
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
uv tool install github-agent-cli # uv, isolated tool environment
|
|
99
|
+
pipx install github-agent-cli # pipx, isolated virtual environment
|
|
100
|
+
pip install github-agent-cli # pip into the active environment
|
|
101
|
+
ghagent --version
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
> **PyPI status.** These commands resolve after the first publication. Trusted Publishing is
|
|
105
|
+
> configured by the repository owner and the `Publish` workflow is triggered manually, so until
|
|
106
|
+
> then install the wheel from the [latest release](https://github.com/paulmann/github-agent/releases/latest)
|
|
107
|
+
> or use the source checkout below — both provide the same `ghagent` command.
|
|
108
|
+
|
|
109
|
+
The console script is `ghagent`; the distribution name is `github-agent`.
|
|
110
|
+
|
|
111
|
+
### Optional PNG support
|
|
112
|
+
|
|
113
|
+
`assets render` always writes the SVG. PNG output needs Pillow, which is an optional extra:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install "github-agent-cli[png]"
|
|
117
|
+
uv tool install --with pillow github-agent-cli
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Without Pillow the command says why no PNG exists instead of pretending a social preview is
|
|
121
|
+
ready.
|
|
122
|
+
|
|
123
|
+
### From source (clone)
|
|
124
|
+
|
|
125
|
+
The clone is the second install path and the only one that carries `tests/`, `skills/`,
|
|
126
|
+
`reference/`, `wiki/` and the templates, so it is also the one that `install`, `verify-install`,
|
|
127
|
+
`snippet` and `uninstall` need. An editable install adds the `ghagent` command to the checkout:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
git clone https://github.com/paulmann/github-agent.git
|
|
131
|
+
cd github-agent
|
|
132
|
+
pip install -e .
|
|
133
|
+
python tools/ghagent.py selftest
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Docker
|
|
137
|
+
|
|
138
|
+
The repository ships a `Dockerfile`; build it locally and mount the repository under test at
|
|
139
|
+
`/repo`, which is the image working directory:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
docker build -t ghagent .
|
|
143
|
+
docker run --rm -v "$PWD:/repo" ghagent audit .
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
On Windows PowerShell the same mount is `-v "${PWD}:/repo"`. The entry point is `ghagent`, so
|
|
147
|
+
the first argument after the image name is the command. No registry image is published as part
|
|
148
|
+
of 1.2.0 and CI does not build the container: the tag is a local convention. See
|
|
149
|
+
[examples/docker.md](examples/docker.md).
|
|
150
|
+
|
|
151
|
+
### GitHub Action
|
|
152
|
+
|
|
153
|
+
The composite action installs the pack from its own checkout, so it does not depend on a PyPI
|
|
154
|
+
release and works as soon as the tag exists:
|
|
155
|
+
|
|
156
|
+
```yaml
|
|
157
|
+
- uses: actions/checkout@v7
|
|
158
|
+
- uses: paulmann/github-agent@v1.2.1 # pin the release tag
|
|
159
|
+
with:
|
|
160
|
+
command: audit .
|
|
161
|
+
min-score: "80"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
| Input | Default | Purpose |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| `command` | `audit . --min-score 80` | any `ghagent` command, without the program name |
|
|
167
|
+
| `min-score` | `80` | score threshold, applied only when `command` starts with `audit` and passes no flag |
|
|
168
|
+
| `working-directory` | `.` | repository directory the command runs in, relative to `$GITHUB_WORKSPACE` |
|
|
169
|
+
| `python-version` | `3.13` | interpreter installed by `actions/setup-python` |
|
|
170
|
+
| `github-token` | `${{ github.token }}` | exported as `GITHUB_TOKEN` for metadata commands |
|
|
171
|
+
|
|
172
|
+
For a non-audit command the action runs exactly the given argument string, for example
|
|
173
|
+
`command: doc --root .`. There are no outputs: the step exit code is the result (`0` clean,
|
|
174
|
+
`1` findings, `2` usage or environment problem). A complete workflow, including a second job
|
|
175
|
+
that runs `doc` and a Docker alternative, is in [examples/ci-usage.md](examples/ci-usage.md).
|
|
176
|
+
|
|
177
|
+
### pre-commit
|
|
178
|
+
|
|
179
|
+
The repository is also a pre-commit hook source; the hooks are `ghagent-doc`,
|
|
180
|
+
`ghagent-audit`, `ghagent-privacy` and `ghagent-changelog`:
|
|
181
|
+
|
|
182
|
+
```yaml
|
|
183
|
+
repos:
|
|
184
|
+
- repo: https://github.com/paulmann/github-agent
|
|
185
|
+
rev: v1.2.1 # placeholder: pin the release tag you decide to trust
|
|
186
|
+
hooks:
|
|
187
|
+
- id: ghagent-doc
|
|
188
|
+
- id: ghagent-audit
|
|
189
|
+
- id: ghagent-privacy
|
|
190
|
+
- id: ghagent-changelog
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Install the hooks into the consuming repository with `pre-commit install`. The full consumer
|
|
194
|
+
file is [examples/pre-commit-config.yaml](examples/pre-commit-config.yaml); the hook
|
|
195
|
+
definitions are in [.pre-commit-hooks.yaml](.pre-commit-hooks.yaml). The hooks need a released
|
|
196
|
+
tag, because pre-commit builds the tool from the tagged tree.
|
|
197
|
+
|
|
198
|
+
### Verified installation
|
|
199
|
+
|
|
200
|
+
After any install, one command answers whether the CLI is the released build:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
ghagent --version # prints the version, for example github-agent 1.2.1
|
|
204
|
+
ghagent audit . # 0 clean, 1 findings at error level, 2 usage or environment problem
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
In a clone the full self-test suite runs; the wheel ships the CLI only, so `ghagent selftest`
|
|
208
|
+
there exits `2` with a message that points at the clone rather than reporting a false `PASS`:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
git clone https://github.com/paulmann/github-agent.git
|
|
212
|
+
cd github-agent
|
|
213
|
+
python tools/ghagent.py selftest # 173/173 checks passed
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Usage
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
ghagent audit . # score repository hygiene, exit 1 on errors
|
|
220
|
+
ghagent doc --root . # markdown, links, anchors, tables, table of contents
|
|
221
|
+
ghagent privacy --root . # tokens, private keys, machine paths, personal addresses
|
|
222
|
+
ghagent assets render --write # banner and social preview from the repository metadata
|
|
223
|
+
ghagent assets check # format, dimensions, alt text, referenced files
|
|
224
|
+
ghagent wiki build # rewrite links for the wiki namespace
|
|
225
|
+
ghagent wiki verify # every internal link resolves
|
|
226
|
+
ghagent changelog check # Keep a Changelog and SemVer
|
|
227
|
+
ghagent changelog release 1.2.0 --write
|
|
228
|
+
ghagent meta suggest # description and topics
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Every check command accepts `--json`; findings print as `file:line` with a rule id, so a caller
|
|
232
|
+
does not need to parse prose. `selftest` runs the suite, and `report` writes the combined markdown
|
|
233
|
+
file, so neither needs the machine format.
|
|
234
|
+
|
|
235
|
+
| Exit code | Meaning |
|
|
236
|
+
|---|---|
|
|
237
|
+
| `0` | no findings at error level |
|
|
238
|
+
| `1` | findings at error level, each printed with `file:line` |
|
|
239
|
+
| `2` | usage or environment problem: wrong path, missing file, missing `gh` or token |
|
|
240
|
+
|
|
241
|
+
Example `audit` output, from a deliberately failing repository and not from this tree:
|
|
242
|
+
|
|
243
|
+
```text
|
|
244
|
+
[ERROR] repo.contributing CONTRIBUTING.md is absent hint: add CONTRIBUTING.md
|
|
245
|
+
[WARN ] readme.badges only 1 badge(s) hint: 3-8 badges: CI, release, license, runtime
|
|
246
|
+
[ERROR] changelog.date-missing version 1.1.0 has no ISO date CHANGELOG.md:14
|
|
247
|
+
score: 72.5% (22 scored, 1 skipped)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## What the pack does
|
|
251
|
+
|
|
252
|
+
| Job | One command |
|
|
253
|
+
|---|---|
|
|
254
|
+
| Score a repository | `ghagent audit .` |
|
|
255
|
+
| Lint documents, links and anchors | `ghagent doc --root .` |
|
|
256
|
+
| Find secrets and machine paths | `ghagent privacy --root .` |
|
|
257
|
+
| Render the banner and social preview | `ghagent assets render --write` |
|
|
258
|
+
| Build, verify and publish the wiki | `ghagent wiki build`, `verify`, `publish --push` |
|
|
259
|
+
| Release a version | `ghagent changelog release 1.2.0 --write` |
|
|
260
|
+
| Fix description and topics | `ghagent meta apply --repo owner/name --write` |
|
|
261
|
+
| Install the skill into another agent | `ghagent install --profile harness --write` |
|
|
262
|
+
|
|
263
|
+
The CLI has 13 commands; the table names the ones used every day. The rest (`report`,
|
|
264
|
+
`snippet`, `verify-install`, `uninstall`, `selftest`, `assets suggest`, `changelog suggest`,
|
|
265
|
+
`changelog notes`, `meta suggest`, `wiki init`, `wiki publish`) carry their flags in
|
|
266
|
+
`ghagent --help`; the recurring jobs are mapped in [`AGENTS.md`](AGENTS.md).
|
|
267
|
+
|
|
268
|
+
## In numbers
|
|
269
|
+
|
|
270
|
+
Measured in this tree on 2026-10-30 against version 1.2.1:
|
|
271
|
+
|
|
272
|
+
| Surface | Value | Measurement source |
|
|
273
|
+
|---|---:|---|
|
|
274
|
+
| Self-tests | 173 | `python tests/run_tests.py` |
|
|
275
|
+
| CLI commands | 13 | `ghagent --help` |
|
|
276
|
+
| Library modules | 11 | `tools/ghalib/*.py` |
|
|
277
|
+
| Document rules examined on this tree | 17 | `ghagent doc --json`, field `rules_examined` |
|
|
278
|
+
| Runtime dependencies | 0 | `pyproject.toml`, `dependencies = []` |
|
|
279
|
+
| Platform traps recorded | 15 | the traps table in [docs/RULES.md](docs/RULES.md) |
|
|
280
|
+
| Python lines | 4176 | `wc -l tools/ghagent.py tools/ghalib/*.py` |
|
|
281
|
+
|
|
282
|
+
## Checks that run
|
|
283
|
+
|
|
284
|
+
| Group | Rules |
|
|
285
|
+
|---|---|
|
|
286
|
+
| Text | UTF-8 without BOM, LF instead of CRLF, final newline, no tab indentation |
|
|
287
|
+
| Structure | one `H1`, no skipped heading levels, closed code fences, language on every fence |
|
|
288
|
+
| Tables | the cell count of every row matches the header and the separator |
|
|
289
|
+
| Links | the relative file exists, the anchor exists (including Cyrillic) |
|
|
290
|
+
| Table of contents | every entry resolves, no `H2` is forgotten |
|
|
291
|
+
| Markup | the five alert types, alt text on images, no images over `http://` |
|
|
292
|
+
| Privacy | tokens, private keys, absolute machine paths, personal addresses |
|
|
293
|
+
| Images | banner referenced, preview is PNG/JPG/GIF, under 1 MB, at least 640×320 |
|
|
294
|
+
| Wiki | manifest and files agree, `Home`/`_Sidebar`/`_Footer` present, no `.md` links, no relative images |
|
|
295
|
+
| CHANGELOG | SemVer and ISO date per version, newest first, known types, no empty version, comparison links |
|
|
296
|
+
| Agents file | the canonical root `AGENTS.md` stays a map: above 120 lines is a warning and detail belongs in `docs/` |
|
|
297
|
+
| Metadata | description under 200 characters without a wasted prefix, 8–20 lowercase-hyphenated topics |
|
|
298
|
+
|
|
299
|
+
A rule that examined zero objects is not passed: it is reported as `coverage.skipped`, and an
|
|
300
|
+
empty tree is `doc.no-text-files`.
|
|
301
|
+
|
|
302
|
+
## Images
|
|
303
|
+
|
|
304
|
+
The banner at the top of this file is generated by the pack itself:
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
ghagent assets render --title "github-agent" \
|
|
308
|
+
--tagline "Repository and wiki steward for AI agents: one command per job." \
|
|
309
|
+
--command "ghagent audit ." --chips "python,github,wiki,lint" --write
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
- `assets/social-preview.png` — 1280×640, under 1 MB, ready for **Settings → Social preview**.
|
|
313
|
+
- `assets/social-preview.svg` — vector twin for the README, no dependency needed.
|
|
314
|
+
- `assets check` verifies format, byte size, dimensions, alt text and that every referenced file
|
|
315
|
+
exists. The repository copy is not the social preview automatically: that upload is a manual
|
|
316
|
+
step, and the check prints the reminder.
|
|
317
|
+
|
|
318
|
+
## Import into another agent
|
|
319
|
+
|
|
320
|
+
| Agent | Skill root | What to do |
|
|
321
|
+
|---|---|---|
|
|
322
|
+
| AutoClaw2 | `%USERPROFILE%\.pi\agent\skills` | `install --profile autoclaw --write`, then paste the `snippet` block into its `AGENTS.md` |
|
|
323
|
+
| HARNESS | `%USERPROFILE%\.dsh\skills` | `install --profile harness --write`, same block |
|
|
324
|
+
| SagaAI | any directory | `install --target <dir> --write` and the block from `snippet --target <dir>` |
|
|
325
|
+
|
|
326
|
+
The `snippet` block names the pack path, the verification command and one rule: one job, one
|
|
327
|
+
command. After import the agent must run `verify-install` and get `0`; anything else means the
|
|
328
|
+
installed copy is not the tested one. Import is the workflow that needs the clone rather than the
|
|
329
|
+
wheel, because the wheel ships only the CLI. Details: [docs/IMPORT.md](docs/IMPORT.md).
|
|
330
|
+
|
|
331
|
+
## Wiki as documentation
|
|
332
|
+
|
|
333
|
+
The wiki is maintained from the repository: pages live in `wiki/`, order is set by
|
|
334
|
+
`wiki/wiki.json`. `wiki build` rewrites links for the wiki namespace — internal links lose
|
|
335
|
+
`.md`, links into the repository tree become absolute, and a relative image is an error because
|
|
336
|
+
the wiki repository cannot see the project tree.
|
|
337
|
+
|
|
338
|
+
Built and verified with the pack's own commands. Publication needs one action in the GitHub
|
|
339
|
+
interface: `<repo>.wiki.git` does not exist until a first page is saved, and `git push` cannot
|
|
340
|
+
create it — `wiki publish` then returns `wiki.remote-missing` with that step. The full workflow
|
|
341
|
+
is in [docs/WIKI.md](docs/WIKI.md).
|
|
342
|
+
|
|
343
|
+
## Languages of the documentation
|
|
344
|
+
|
|
345
|
+
English files are canonical; Russian translations carry the `.ru.md` suffix, the convention
|
|
346
|
+
GitHub itself uses (`README.ru.md`, `AGENTS.ru.md`, `wiki/01-Why.ru.md`).
|
|
347
|
+
|
|
348
|
+
| English | Russian |
|
|
349
|
+
|---|---|
|
|
350
|
+
| [README.md](README.md) | [README.ru.md](README.ru.md) |
|
|
351
|
+
| [AGENTS.md](AGENTS.md) | [AGENTS.ru.md](AGENTS.ru.md) |
|
|
352
|
+
| [CHANGELOG.md](CHANGELOG.md) | [CHANGELOG.ru.md](CHANGELOG.ru.md) |
|
|
353
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md) |
|
|
354
|
+
| [SECURITY.md](SECURITY.md) | [SECURITY.ru.md](SECURITY.ru.md) |
|
|
355
|
+
| [SUPPORT.md](SUPPORT.md) | [SUPPORT.ru.md](SUPPORT.ru.md) |
|
|
356
|
+
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | [CODE_OF_CONDUCT.ru.md](CODE_OF_CONDUCT.ru.md) |
|
|
357
|
+
| [GOVERNANCE.md](GOVERNANCE.md) | [GOVERNANCE.ru.md](GOVERNANCE.ru.md) |
|
|
358
|
+
|
|
359
|
+
Translations are updated in the same commit as the original. A translation that silently lags is
|
|
360
|
+
a documentation defect, and the wiki carries both sets: English pages as canonical, Russian as
|
|
361
|
+
`*.ru.md` pages in their own navigation group.
|
|
362
|
+
|
|
363
|
+
## How it is built
|
|
364
|
+
|
|
365
|
+
```mermaid
|
|
366
|
+
flowchart LR
|
|
367
|
+
R["Repository<br/>README, CHANGELOG, docs"] --> A["audit"]
|
|
368
|
+
R --> D["doc"]
|
|
369
|
+
R --> I["assets"]
|
|
370
|
+
W["wiki/ + wiki.json"] --> B["wiki build"]
|
|
371
|
+
B --> V["wiki verify"]
|
|
372
|
+
V --> P["wiki publish --push"]
|
|
373
|
+
A --> O["report, --json"]
|
|
374
|
+
D --> O
|
|
375
|
+
I --> O
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
| Component | Responsibility |
|
|
379
|
+
|---|---|
|
|
380
|
+
| `tools/ghagent.py` | argument parsing, exit codes, report assembly |
|
|
381
|
+
| `tools/ghalib/mdcheck.py` | markdown, links, anchors, privacy |
|
|
382
|
+
| `tools/ghalib/audit.py` | required files, README and changelog contracts, score |
|
|
383
|
+
| `tools/ghalib/assets.py` | banner and social preview: render, check, suggest |
|
|
384
|
+
| `tools/ghalib/wiki.py` | manifest, link rewriting, sidebar and footer, publication |
|
|
385
|
+
| `tools/ghalib/changelog.py` | Keep a Changelog 2.0.0, release, draft from commits |
|
|
386
|
+
| `tools/ghalib/meta.py` | description, topics, homepage |
|
|
387
|
+
| `tools/ghalib/install.py` | skill installation, sha256 manifest, drift, removal |
|
|
388
|
+
| `tools/ghalib/report.py` | findings, severities, markdown and `--json` output |
|
|
389
|
+
| `tools/ghalib/config.py`, `tools/ghalib/util.py` | `.ghagent.json`, paths, text I/O, anchors |
|
|
390
|
+
| `tests/run_tests.py` | 173 self-tests with fixtures and decoys |
|
|
391
|
+
|
|
392
|
+
Anchors follow GitHub's rules: lowercase, punctuation dropped, spaces to hyphens, a repeated
|
|
393
|
+
heading gets `-1`. The rule was verified against a live table of contents: an em dash in a
|
|
394
|
+
heading produces a double hyphen. Architecture notes: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
395
|
+
|
|
396
|
+
## Limitations
|
|
397
|
+
|
|
398
|
+
- `audit --repo` and `meta` need `gh` or `GITHUB_TOKEN`. Without them the command returns an
|
|
399
|
+
error instead of an empty success.
|
|
400
|
+
- External links are not fetched: relative paths, anchors and structure are checked. A network
|
|
401
|
+
crawl is a separate decision, not a side effect of a linter.
|
|
402
|
+
- Wiki pages are barely discoverable through search engines: per GitHub documentation, only
|
|
403
|
+
wikis with 500+ stars and public editing disabled are indexed. Use GitHub Pages for discovery.
|
|
404
|
+
- `changelog suggest` is a draft. It does not know what matters to a user.
|
|
405
|
+
- PNG rendering needs Pillow. Without it the SVG is produced and the check says why no PNG
|
|
406
|
+
exists, instead of pretending a social preview is ready.
|
|
407
|
+
|
|
408
|
+
## Development
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
python tools/ghagent.py selftest
|
|
412
|
+
python tests/run_tests.py
|
|
413
|
+
python tools/ghagent.py doc --root .
|
|
414
|
+
python tools/ghagent.py audit .
|
|
415
|
+
python tools/ghagent.py assets check
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
A new rule arrives with a fixture that fails without it and a decoy that must stay quiet. A rule
|
|
419
|
+
without a fixture is removed: a check that cannot be proven is worse than no check. Packaging
|
|
420
|
+
and the wheel layout are described in [docs/PACKAGING.md](docs/PACKAGING.md); the 1.1.0 → 1.2.0
|
|
421
|
+
changes are in [MIGRATION.md](MIGRATION.md).
|
|
422
|
+
|
|
423
|
+
## Contributing
|
|
424
|
+
|
|
425
|
+
Before a pull request: `python tests/run_tests.py` and `python tools/ghagent.py doc --root .`
|
|
426
|
+
must be green. One change, one reason. Rules: [CONTRIBUTING.md](CONTRIBUTING.md), security
|
|
427
|
+
policy: [SECURITY.md](SECURITY.md).
|
|
428
|
+
|
|
429
|
+
## License
|
|
430
|
+
|
|
431
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
ghagent.py,sha256=W_ywmCY89ZUIHA4-siPYswtXh6kX8QCbsJ73f__ODlI,23238
|
|
2
|
+
ghalib/__init__.py,sha256=ur7kSxCjbmuv0oq97bo9bwE0a8QEDiDeVxxf7wACOAc,161
|
|
3
|
+
ghalib/assets.py,sha256=Wak4liTekNdDYHewKZMgZL1FOW11OhmEzoTHc9vPLRQ,21302
|
|
4
|
+
ghalib/audit.py,sha256=gaHcuP_FE_IDK6rAXDHQquoqcoKg1Btaz37U3uQpLDY,29290
|
|
5
|
+
ghalib/changelog.py,sha256=mMAQHZGUA59AXWWRA2qTHeqNfvOBz3oADYvpVX1PiPk,20357
|
|
6
|
+
ghalib/config.py,sha256=r_VoPi1vp8J5OZrd3Jf9Gmi5iCILwukZEx7Hr_Q02sA,1457
|
|
7
|
+
ghalib/install.py,sha256=RWku4z3pzCe76vWlERAzzJIkF-tT-ieZ_EQvIsIg3RI,7410
|
|
8
|
+
ghalib/mdcheck.py,sha256=k1raRBLMWUIZsT5jzy3abnk_EJ_FyheeCjurHKbYoME,20715
|
|
9
|
+
ghalib/meta.py,sha256=mIt6NZVxo6dZhaEHjCqunVZJ3QqA4S2voxiX17cgbGo,12481
|
|
10
|
+
ghalib/report.py,sha256=eljoa6UUnpwcCJ3zTSJSpKdMHiml2hSu4yMWZhQ-uEw,4098
|
|
11
|
+
ghalib/util.py,sha256=qryPQzoNiC1G3mu2E8wlZoAC8cY4PRd4lkKSavtk_9w,18246
|
|
12
|
+
ghalib/wiki.py,sha256=s0BxCxxU9v6WccjmIJdtPz5HM6uUG3slerDPS68LYJ0,22139
|
|
13
|
+
github_agent_cli-1.2.1.dist-info/METADATA,sha256=RYLlYlCtSvRdcsdkwmUi4IVarmmM-coavgP5LBTmFbA,20291
|
|
14
|
+
github_agent_cli-1.2.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
15
|
+
github_agent_cli-1.2.1.dist-info/entry_points.txt,sha256=ygzVll1rjzq2XexecCuJxEEfijExjJkWFtszftav9ys,41
|
|
16
|
+
github_agent_cli-1.2.1.dist-info/licenses/LICENSE,sha256=tI9-MOZ-IBbjmioMIxKVwx3x727NsJflGKEJV8seQUY,1082
|
|
17
|
+
github_agent_cli-1.2.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 github-agent contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|