agent-hygiene-linter 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+## [1.0.1](https://github.com/oleg-koval/agent-hygiene-linter/compare/v1.0.0...v1.0.1) (2026-06-21)
+
+
+### Bug Fixes
+
+* exit cleanly on EPIPE when stdout is closed early ([80d31e3](https://github.com/oleg-koval/agent-hygiene-linter/commit/80d31e32a807c0815fd9624fc7e8e7cbdf1e59be))
+
+# 1.0.0 (2026-06-21)
+
+
+### Bug Fixes
+
+* disable release commit hooks in ci ([692de5d](https://github.com/oleg-koval/agent-hygiene-linter/commit/692de5d1fc8a6dc37f7dd9921dd18802b5c98dd0))
+* disable release hooks in github actions ([f28cb64](https://github.com/oleg-koval/agent-hygiene-linter/commit/f28cb64ca1752ea9b4a4908051f372c6e82bb170))
+* ignore generated changelog in prettier ([799586d](https://github.com/oleg-koval/agent-hygiene-linter/commit/799586d93f1bd819cce38d9dd5348f70fcdc6618))
+* skip npm publish in release workflow ([32f9653](https://github.com/oleg-koval/agent-hygiene-linter/commit/32f9653ada672cd0945cf9839360136b19107abe))
+
+
+### Features
+
+* **fix:** add --fix to scaffold missing agent-readiness files ([d9334c9](https://github.com/oleg-koval/agent-hygiene-linter/commit/d9334c9db33f4aeae262711eb8cbd9bf36f6f2c0))
+* publish playbook runner docs ([77405dc](https://github.com/oleg-koval/agent-hygiene-linter/commit/77405dcb7665f336af6cb6e3f0bae5d4797db36d))
+* regenerate readme icon ([f4897fe](https://github.com/oleg-koval/agent-hygiene-linter/commit/f4897fe7b57ef07feada777fb43c8be82a6f8e9b))
+* release ai refactor playbook runner ([8e63675](https://github.com/oleg-koval/agent-hygiene-linter/commit/8e63675f7822a44784cdc18c70a7f1f16f6e375d))
+
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+semantic-release manages entries from git tags and commit messages.
+
+## [1.1.0](https://github.com/oleg-koval/agent-hygiene-linter/compare/v1.0.2...v1.1.0) (2026-05-29)
+
+### Features
+
+* cleaned up project branding; removed dead refactor-runner code
+
+## [1.0.2](https://github.com/oleg-koval/agent-hygiene-linter/compare/v1.0.1...v1.0.2) (2026-05-29)
+
+### Bug Fixes
+
+* ignore generated changelog in prettier
+
+## [1.0.1](https://github.com/oleg-koval/agent-hygiene-linter/compare/v1.0.0...v1.0.1) (2026-05-29)
+
+### Bug Fixes
+
+* disable release hooks in github actions
+
+## 1.0.0 (2026-05-29)
+
+### Features
+
+* initial release of agent-hygiene-linter — scores repo hygiene for agents and humans

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg Koval
+
+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.

package/README.md

@@ -0,0 +1,157 @@
+<p align="center">
+  <a href="./.github/workflows/ci.yml"><img src="https://github.com/oleg-koval/agent-hygiene-linter/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/oleg-koval/agent-hygiene-linter/releases"><img src="https://img.shields.io/github/v/release/oleg-koval/agent-hygiene-linter" alt="GitHub release"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+  <a href="https://www.npmjs.com/package/agent-hygiene-linter"><img src="https://img.shields.io/npm/v/agent-hygiene-linter" alt="npm version"></a>
+</p>
+
+<p align="center">
+  <img src="./logo.svg" width="120" height="120" alt="Agent Hygiene Linter logo">
+</p>
+
+<h1 align="center">agent-hygiene-linter</h1>
+
+<p align="center">
+  Scan any repo and get a hygiene score in seconds<br>
+  <strong>README · AGENTS.md · docs · changelog · scripts · commit style — all in one pass</strong>
+</p>
+
+---
+
+## What it does
+
+`agent-hygiene-linter` runs a quick structural audit of any repository and emits a score from 0–100 along with categorised findings: **good**, **warning**, or **fix now**.
+
+It checks:
+
+| Finding code                                                     | What it looks for                                  |
+| ---------------------------------------------------------------- | -------------------------------------------------- |
+| `readme-present` / `readme-missing`                              | Top-level `README.md`                              |
+| `agent-doc-present` / `agent-doc-missing`                        | `AGENTS.md` or `CLAUDE.md`                         |
+| `docs-shape-present` / `docs-shape-missing`                      | At least one `.md` file under `docs/`              |
+| `changelog-present` / `changelog-missing`                        | `CHANGELOG.md` or `docs/changelog.md`              |
+| `package-scripts-good` / `package-scripts-missing`               | Standard `build`, `test`, `lint`, `ci` npm scripts |
+| `commit-style-good` / `commit-style-mixed` / `commit-style-weak` | Conventional Commits ratio over last 25 commits    |
+| `entrypoint-present` / `entrypoint-missing`                      | `src/index.ts`, `index.ts`, or `main.ts`           |
+
+**Scoring:** each `fix now` finding costs 18 points; each `warning` costs 8 points. Minimum score is 0.
+
+## Install
+
+```bash
+npm install -g agent-hygiene-linter
+```
+
+Or run without installing:
+
+```bash
+npx agent-hygiene-linter <path>
+```
+
+## Usage
+
+```bash
+# Scan the current directory (text output)
+agent-hygiene-linter .
+
+# Scan a specific repo
+agent-hygiene-linter /path/to/your/repo
+
+# Markdown report
+agent-hygiene-linter . --format markdown
+
+# JSON report (for CI pipelines / dashboards)
+agent-hygiene-linter . --format json
+
+# Save report to a file
+agent-hygiene-linter . --format markdown --output hygiene-report.md
+
+# Fail with exit code 1 if score is below threshold (default: 75)
+agent-hygiene-linter . --min-score 80
+
+# Auto-create the missing files it can generate safely, then re-scan
+agent-hygiene-linter . --fix
+
+# Preview what --fix would create without writing anything
+agent-hygiene-linter . --fix --dry-run
+```
+
+### `--fix`
+
+`--fix` closes the gaps it can close from the repo scan alone — it scaffolds any
+missing `README.md`, `AGENTS.md`, `docs/README.md`, and `CHANGELOG.md` from
+detected facts (package manager, scripts, entrypoint), then re-scans and prints
+the new score. It is deterministic and offline (no LLM), it **never overwrites**
+an existing file, and it is idempotent — a second run writes nothing. Everything
+it cannot generate safely (package scripts, commit history, the entrypoint) stays
+advisory in the report.
+
+## Example output
+
+```
+Agent hygiene score: 92/100
+Repo: my-project
+Path: /home/user/my-project
+Good: 6 | Warning: 1 | Fix now: 0
+
+[warning] Docs directory is thin
+  Add a small docs/ tree or module notes so the repo is easier to navigate.
+[good] Agent instructions exist
+  Found repo-level instructions for agent onboarding.
+[good] An obvious entrypoint exists
+  Found a clear code entrypoint for navigation.
+[good] Changelog or release notes exist
+  The repo has a visible change log path for updates.
+[good] Commit style is consistent
+  14 of 14 recent commits follow Conventional Commits.
+[good] Package scripts are predictable
+  Found 4 of the expected build/test/lint/ci scripts.
+[good] README exists
+  The repo has a top-level README for quick orientation.
+```
+
+## CI integration
+
+Add a hygiene gate to your pipeline:
+
+```yaml
+- name: Hygiene check
+  run: npx agent-hygiene-linter . --min-score 75
+```
+
+Exit code `0` = score is at or above the threshold. Exit code `1` = below threshold.
+
+## Programmatic API
+
+```typescript
+import { scanRepository, renderTextReport } from "agent-hygiene-linter";
+
+const report = await scanRepository("/path/to/repo");
+console.log(renderTextReport(report));
+// report.score, report.findings, report.counts
+```
+
+## System requirements
+
+- Node.js 20.10 or newer
+
+## Contributing
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Author
+
+Oleg Koval — [olegkoval.com](https://olegkoval.com)
+
+---
+
+<p align="center">
+  <a href="https://oleg-koval.github.io/agent-hygiene-linter/">Website</a> ·
+  <a href="https://github.com/oleg-koval/agent-hygiene-linter">GitHub</a> ·
+  <a href="https://github.com/oleg-koval/agent-hygiene-linter/releases">Releases</a> ·
+  <a href="https://github.com/oleg-koval/agent-hygiene-linter/issues">Issues</a>
+</p>

package/dist/cli-CWkfHViv.d.ts

@@ -0,0 +1,44 @@
+type HygieneBucket = "good" | "warning" | "fix now";
+interface HygieneFinding {
+    code: string;
+    bucket: HygieneBucket;
+    title: string;
+    detail: string;
+}
+interface HygieneCounts {
+    good: number;
+    warning: number;
+    fixNow: number;
+}
+interface HygieneReport {
+    repoPath: string;
+    repoName: string;
+    scannedAt: string;
+    score: number;
+    counts: HygieneCounts;
+    findings: HygieneFinding[];
+}
+interface CliOptions {
+    repoPath: string;
+    format: "text" | "markdown" | "json";
+    outputPath?: string;
+    minScore: number;
+    fix: boolean;
+    dryRun: boolean;
+}
+interface FixFacts {
+    repoName: string;
+    packageManager: string;
+    scripts: string[];
+    entrypoint: string | null;
+}
+interface FixResult {
+    before: HygieneReport;
+    after: HygieneReport;
+    planned: string[];
+    written: string[];
+}
+
+declare function parseCliArgs(argv: string[]): CliOptions;
+
+export { type CliOptions as C, type FixResult as F, type HygieneFinding as H, type HygieneReport as a, type FixFacts as b, type HygieneBucket as c, type HygieneCounts as d, parseCliArgs as p };

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { p as parseCliArgs } from './cli-CWkfHViv.js';