@mcptoolshop/housekeeping 0.0.0 → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project are recorded here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.3.1] - 2026-09-30
+
+### Fixed
+
+- `CI_FAILING` no longer fires on a default branch whose only non-green checks
+  are cancelled runs replaced by a green run of the same check on the same
+  commit. GitHub's check rollup counts a cancelled run as a failure, so a
+  commit pushed twice read as red forever. `hk ci`, the MCP server and the
+  report read the same decision, and the finding now names the failing checks.
+
+## [1.3.0] - 2026-09-30
+
+The first release on npm, as `@mcptoolshop/housekeeping`.
+
+### Added
+
+- Publishable to npm as `@mcptoolshop/housekeeping`, with the `hk` and
+  `hk-mcp` commands. A release workflow publishes it with provenance when a
+  GitHub release is published, through npm Trusted Publishing.
+- `HK_HOME`: where data, reports and the config live. Unset, a clone keeps
+  them in itself as before, and an installed package keeps them in the
+  directory it runs from, never inside `node_modules`.
+- The default-branch CI findings say where a red run broke: the failed job and
+  step, matched to the workflow file by name. One REST call per red run.
+- With an Atlas map, the failed step is joined to the map's entry for it, and
+  a map finding recorded against that same step is cited as a prediction.
+- `run_failed_step` table.
+- This repository keeps its own Atlas map in `atlas/`, made by
+  `@dogfood-lab/atlas` 1.24.0 and checked in CI at the same version, as the
+  rule in `rules/atlas-map.md` asks of every repository that runs workflows.
+- The report's Atlas section lists each map's door findings (D1: a toolchain a
+  package refuses; D2: a lockfile without the job's platform) and the checks
+  Atlas could not judge, counted only among maps made by Atlas 1.24.0 or later.
+- The deploy rules take a job's environment from the Atlas map where the map
+  records one, and keep the workflow's own reading beside it
+  (`workflow_environment.source`, `.parsed`); the report counts disagreements.
+- The lockfile audit reads `pnpm-lock.yaml` (lockfile versions 5, 6 and 9) as
+  well as `package-lock.json`. In a 9.x lock, what ships is found by walking
+  the dependency graph from every workspace package's production
+  dependencies.
+
+### Changed
+
+- `ATLAS_ENGINE_BEHIND` is `low`, and counts in the health score, for a
+  snapshot taken after the first fleet pin-bump wave ended; an earlier
+  snapshot keeps it at `info`, so rebuilding it reproduces that day's
+  findings. The rule's Transition section says the same.
+- A new logo: a broom and a magnifier over a database. The README header,
+  the handbook's header mark and the favicon all use it, and the lockup
+  also ships at the repository root as `logo.png`, where the org's logo sync
+  finds it (not `readme.png`, which npm would pack as a README).
+
+### Fixed
+
+- The Atlas map record kept a command's `directory`, a key no map writes; it
+  now keeps `dir`, and keeps the door's `unresolvedChecks`. Cached records are
+  re-read once.
+
+## [1.2.0] - 2026-09-30
+
+The first public release.
+
+### Added
+
+- `hk help`, and `--help` / `-h` on any command. The help text is generated
+  from the table that dispatches the commands.
+- Structured errors: every failure prints `error [CODE] message` and a hint.
+- Exit codes: 0 ok, 1 user error, 2 runtime error, 3 partial.
+- Log levels: `--quiet`, `--verbose`, `--debug`, or `HK_LOG`.
+- `hk report [snapshot-id]` writes the audit report for a loaded snapshot.
+- `housekeeping.config.json`: the organization to sweep, and the repositories
+  that are not shipped products. A malformed file is an error.
+- `npm run verify`: the test suite, then a smoke run of the CLI.
+- The written rules the findings cite, under `rules/`.
+- A landing page and a handbook.
+
+### Changed
+
+- `hk refresh` writes the report itself, and exits 3 when the sweep finished
+  with collection errors or an incomplete cost pass. The snapshot and the
+  report are still written.
+- A sweep refused for lack of API quota exits 2, as `RATE_LIMITED`.
+- An unknown command is an error with exit 1. It used to print the usage text
+  and exit 0.
+- `HK_DB` selects the database for the CLI as well as the MCP server.
+- The MCP server returns every failure as a structured result.
+
+### Fixed
+
+- `hk sql` is read-only, as documented. It ran any statement on a writable
+  connection.
+- Running `hk help`, or mistyping a command, no longer creates a database.
+
+### Security
+
+- `fast-uri` 3.1.8 and `ip-address` 10.7.2, both advisory fixes in transitive
+  dependencies.
+- CI runs `npm audit --audit-level=high` as a blocking step.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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.es.md

@@ -0,0 +1,217 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/housekeeping/readme.png" alt="housekeeping" width="400" />
+</p>
+
+<h1 align="center">housekeeping</h1>
+
+<p align="center">
+  An operational-health warehouse for a GitHub organization.<br>
+  One sweep, one SQLite database, findings you can argue with.
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/housekeeping/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/housekeeping/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/housekeeping/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/housekeeping/handbook/"><img src="https://img.shields.io/badge/Handbook-read-blue" alt="Handbook" /></a>
+</p>
+
+Una sola ejecución recopila el estado de CI de cada repositorio, los problemas abiertos y las solicitudes de incorporación de código, las versiones, las etiquetas de versión, los archivos de flujo de trabajo, la protección de ramas, las alertas de seguridad, los archivos de bloqueo y la facturación de Actions en SQLite, y luego realiza una auditoría de todo ello en función de las reglas establecidas.
+
+Responde, para toda la organización a la vez:
+
+- ¿Cuáles son las ramas predeterminadas que muestran un estado crítico y se trata de una rama principal defectuosa o de un historial obsoleto?
+- ¿Cuáles son las solicitudes de incorporación de código que nunca se pueden fusionar, porque una comprobación requerida que no emite nada las está bloqueando?
+- ¿Cuáles son las implementaciones que los propios ajustes del repositorio rechazan?
+- ¿Dónde han divergido `package.json`, las etiquetas de Git y el registro de npm?
+- ¿Cuáles son los flujos de trabajo que infringen las reglas de coste de Actions, cuánto costaron y qué trabajos los utilizaron?
+- ¿Cuáles son los repositorios que contienen avisos que el recuento de alertas de GitHub no detecta?
+
+Es un instrumento de auditoría, no un corrector. Lee GitHub y no modifica nada.
+
+## Por qué tiene esta forma
+
+| Capa | Opción | Razón |
+|---|---|---|
+| Transporte | la CLI `gh` | Ya tiene su token. La herramienta nunca almacena ni solicita credenciales. |
+| Recopilación | GitHub GraphQL, con paginación | Una sola consulta devuelve metadatos, problemas abiertos, solicitudes de incorporación de código abiertas, versiones y árboles de archivos para una página de repositorios. Una página que sigue superando el tiempo de espera se divide a la mitad y se vuelve a solicitar desde el mismo cursor. |
+| Ejecuciones de Actions | REST | GraphQL no tiene una interfaz de Actions. |
+| Coste de Actions | API de facturación más duraciones por trabajo | La factura indica qué repositorio; solo los trabajos indican qué flujo de trabajo. Los puntos finales `/timing` de GitHub devuelven ceros, por lo que la suma por trabajo se reconstruye y luego se concilia con la factura. |
+| Tarifas de los ejecutores | se lee de la factura | Una tarifa facturada puede diferir del precio de lista, y una constante en el código fuente falsearía todos los números. |
+| Almacenamiento | SQLite a través del `node:sqlite` integrado | No hay un paso de compilación nativo. |
+| Fuente de la verdad | `data/snapshots/*.json` | Bruto, modificable y solo para anexar. La base de datos se deriva: `npm run rebuild` la reconstruye sin conexión. |
+| Registro de la ejecución | `data/sweeps.jsonl` | Una línea por ejecución, incluidas las ejecuciones que fallaron y las ejecuciones que no encontraron nada nuevo. |
+
+Las instantáneas son inmutables y aditivas, por lo que la desviación entre dos fechas es un `JOIN`.
+
+## Requisitos
+
+- Node.js 22.5 o posterior.
+- La [CLI de GitHub](https://cli.github.com/), con la sesión iniciada (`gh auth status`) como una
+cuenta que puede leer la organización. La lectura de la facturación y las alertas de seguridad
+requiere el acceso correspondiente; una ejecución sin ello registra "no medido" y
+continúa. Nunca registra un permiso faltante como un resultado válido.
+- Windows o Linux. Se desarrolla en Windows y sus pruebas se ejecutan en Linux en
+CI. macOS debería funcionar y no se ha probado.
+
+## Uso
+
+```bash
+npm install -g @mcptoolshop/housekeeping   # puts `hk` and `hk-mcp` on your path
+mkdir warehouse && cd warehouse            # housekeeping keeps its data here
+hk refresh your-org                        # collect, load, analyze, write reports/AUDIT-<date>.md
+```
+
+Para conservar la configuración entre las ejecuciones, coloque un `housekeeping.config.json` en ese directorio (consulte la sección Configuración); luego, `hk refresh` no necesita ningún argumento.
+
+O ejecútelo desde una copia, que conserva sus datos en la copia:
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/housekeeping.git
+cd housekeeping
+npm install
+npm link                 # puts `hk` on your path
+cp housekeeping.config.example.json housekeeping.config.json   # then set "org"
+hk refresh
+```
+
+Luego, realice una consulta:
+
+```bash
+hk summary               # portfolio totals
+hk ci                    # repositories whose default branch is red
+hk findings              # findings grouped by severity and code
+hk health                # per-repository health score, worst first
+hk repo <name>           # one repository in full
+hk prs                   # every open pull request by age
+hk versions              # package.json against git tag against npm
+hk actions               # every workflow and its rule flags
+hk cost                  # Actions cost, gross and net side by side
+hk sql "SELECT ..."      # one read-only statement
+hk help                  # every command and flag
+```
+
+En una copia sin `npm link`, cada `hk <command>` es `node src/cli.mjs <command>`.
+
+`npm run rebuild` vuelve a derivar la base de datos y el informe a partir de las instantáneas que ya
+existen en el disco, sin acceso a la red.
+
+Una ejecución completa realiza unos pocos cientos de llamadas a la API. No ejecute `refresh` en un bucle.
+
+Los resultados se envían a la salida estándar; el progreso y los errores se envían a la salida de error estándar. Cada
+error imprime un código y una pista. Códigos de salida: 0 correcto, 1 error de usuario, 2 error de tiempo de ejecución, 3 parcial (la ejecución se completó, con lagunas).
+
+## Configuración
+
+`housekeeping.config.json`, en el directorio en el que funciona la herramienta de limpieza (consulte a continuación):
+
+```json
+{
+  "org": "your-org",
+  "metaRepos": [".github"]
+}
+```
+
+- `org` es la organización que se va a analizar. `hk refresh <org>` lo anula. Si no se especifica ninguno de los dos, una ejecución se negará a iniciarse.
+- `metaRepos` son los repositorios que contienen los ajustes, los activos o
+las herramientas de la organización, no un producto comercializado. Están exentos de los hallazgos que solo
+tienen sentido para un producto: falta de archivos README, LICENSE y similares, no tener
+flujos de trabajo y no tener versiones.
+
+Un archivo con formato incorrecto es un error, nunca un valor predeterminado silencioso: una clave desconocida, un tipo incorrecto o un JSON dañado detienen la ejecución.
+
+Ejecute desde un clon; la herramienta de limpieza mantiene `data/`, `reports/` y el archivo de configuración
+en el clon. Ejecute como un paquete instalado; los mantiene en el directorio desde el que
+lo ejecuta, o en `HK_HOME` cuando se establece.
+
+Entorno: `HK_HOME` (donde residen los datos, los informes y la configuración),
+`HK_CONFIG` (ruta de configuración), `HK_DB` (ruta de la base de datos), `HK_LOG`
+(`silent`, `normal`, `verbose` o `debug`), `HK_COST_REPOS` y
+`HK_COST_BUDGET` (límites del paso del coste por trabajo), `GH_PATH` (ruta a `gh`).
+
+## Mantenga los datos privados
+
+**Lo que escribe una ejecución es confidencial. No incluya `data/` o `reports/` en un
+repositorio público.**
+
+Una instantánea registra los nombres y las descripciones de los repositorios privados, cada
+alerta de seguridad abierta con el paquete que menciona, los archivos de flujo de trabajo y la facturación de Actions. GitHub oculta deliberadamente las alertas de seguridad de un repositorio público a todos, excepto a sus mantenedores; una instantánea publicada entregaría esa lista.
+
+El `.gitignore` de este repositorio excluye `data/`, `reports/` y
+`housekeeping.config.json`. Para mantener el historial, que es el objetivo de las instantáneas,
+ejecute la herramienta desde un **repositorio privado** de su propiedad y guárdelas allí.
+
+## Servidor MCP
+
+`hk-mcp` (o `npm run mcp` en una copia) sirve los datos al programa a través de stdio, por lo que un asistente puede hacer preguntas sin leer una instantánea de varios megabytes:
+
+`hk_summary` · `hk_findings` · `hk_ci` · `hk_repo` · `hk_backlog` ·
+`hk_health` · `hk_cost` · `hk_sql` · `hk_schema`
+
+```json
+{
+  "mcpServers": {
+    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } }
+  }
+}
+```
+
+`HK_HOME` es el directorio desde el que se realiza la ejecución. Si utiliza una copia, use `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]` en su lugar.
+
+`hk_sql` acepta una sola instrucción `SELECT` o `WITH` y abre la base de datos
+en modo de solo lectura. Una llamada que falla devuelve un error estructurado, nunca un rastreo de pila.
+
+## Hallazgos
+
+Las reglas se encuentran en `src/analyze.mjs`. Cada una de ellas cita la regla escrita que aplica,
+por lo que un hallazgo se puede discutir en relación con un estándar y no con el gusto. Las reglas
+que incluye este repositorio se encuentran en [`rules/`](rules/):
+
+- [`rules/github-actions.md`](rules/github-actions.md): filtros de rutas, ejecutores, tamaño de la matriz, límite del archivo de flujo de trabajo, concurrencia.
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): la CI debe pasar, las etapas de lanzamiento, las versiones.
+- [`rules/repo-first.md`](rules/repo-first.md): la rama predeterminada.
+- [`rules/atlas-map.md`](rules/atlas-map.md): un mapa registrado de cada repositorio, verificado en la CI.
+
+Son los estándares de una organización. Si los suyos son diferentes, cambie el archivo de reglas y la regla al mismo tiempo.
+
+Las reglas se aseguran de mantener separados los elementos que parecen similares, porque combinarlos genera ruido:
+
+- **Una rama predeterminada roja no es una rama de solicitud de incorporación de cambios roja.** Una rama de Dependabot que falla es un elemento pendiente; una ejecución de `push` que falla en la rama predeterminada es un problema. El evento de la ejecución decide cuál es.
+- **El historial no es un problema.** Un flujo de trabajo que se mueve a desencadenadores solo para lanzamientos conserva su último fallo en la rama predeterminada para siempre. Un flujo de trabajo eliminado conserva sus ejecuciones. Ninguno de los dos es un defecto activo.
+- **Una comprobación requerida que nada puede emitir no es una comprobación que no se ejecutó aquí.** Una indica que se elimine el requisito; la otra indica que se corrija el desencadenador. Las correcciones se contradicen entre sí.
+- **Una ejecución fallida no es una ejecución cancelada.** `cancel-in-progress` existe para eliminar las ejecuciones obsoletas, por lo que los minutos cancelados suelen ser la regla de concurrencia en funcionamiento.
+- **El costo bruto no es el costo neto.** GitHub mide los repositorios públicos a precio completo y les aplica un descuento hasta cero. El bruto es la capacidad de cómputo real; el neto es el dinero real. Nunca se suman.
+- **Lo que no se mide no está limpio.** Un repositorio que GitHub no está analizando informa de cero alertas. Un repositorio para el que la verificación de costos no se realizó tiene una fila de costos nula. Ambos se informan como desconocidos.
+
+La gravedad impulsa una puntuación de estado: crítica 40, alta 15, media 6, baja 2, informativa 0, que se deduce de 100. La puntuación clasifica la atención, no la calidad.
+
+El [manual](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) enumera cada hallazgo, comando, código de error y tabla.
+
+## Seguridad
+
+- **Solo lectura.** El recopilador emite consultas GraphQL y solicitudes REST `GET`. Nunca combina, envía, lanza, publica ni edita una configuración.
+- **Sin credenciales.** La autenticación es lo que `gh` ya tiene. No se escribe nada sobre esto en el disco.
+- **Sin telemetría.** Los únicos hosts contactados son la API de GitHub, a través de `gh`, y el registro de npm, para buscar versiones y avisos.
+- **Lo que almacena** es la parte sensible: consulte "Mantenga los datos privados".
+
+Informe de una vulnerabilidad según lo descrito en [SECURITY.md](SECURITY.md).
+
+## Pruebas
+
+```bash
+npm test
+```
+
+Cada regla se prueba en ambas direcciones: la forma que debe activarse y la forma vecina que no debe activarse. Un verificador independiente vuelve a derivar una muestra de los hallazgos de GitHub en vivo a través de su propio transporte y omite, en voz alta, cuando no hay una base de datos o una red.
+
+## Licencia
+
+MIT. Consulte [LICENSE](LICENSE).
+
+---
+
+Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

package/README.fr.md

@@ -0,0 +1,195 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.md">English</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/housekeeping/readme.png" alt="housekeeping" width="400" />
+</p>
+
+<h1 align="center">housekeeping</h1>
+
+<p align="center">
+  An operational-health warehouse for a GitHub organization.<br>
+  One sweep, one SQLite database, findings you can argue with.
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/housekeeping/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/housekeeping/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/housekeeping/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/housekeeping/handbook/"><img src="https://img.shields.io/badge/Handbook-read-blue" alt="Handbook" /></a>
+</p>
+
+Une seule analyse collecte l’état du CI de chaque dépôt, les problèmes ouverts et les demandes de fusion, les versions, les étiquettes de version, les fichiers de flux de travail, la protection des branches, les alertes de sécurité, les fichiers de verrouillage et la facturation d’Actions dans SQLite, puis effectue un audit complet en fonction des règles définies.
+
+Il répond, pour l’ensemble de l’organisation :
+
+- Quelles sont les branches par défaut qui présentent des problèmes, et s’agit-il d’une branche principale défectueuse ou d’un historique obsolète ?
+- Quelles demandes de fusion ne peuvent jamais être fusionnées, car une vérification requise qui ne renvoie aucune donnée les bloque-t-elle ?
+- Quels déploiements les paramètres propres au dépôt refusent-ils ?
+- Où `package.json`, les étiquettes Git et le registre npm ont-ils divergé ?
+- Quels flux de travail enfreignent les règles de coût d’Actions, quel a été leur coût et quelles tâches ont consommé ces ressources ?
+- Quels dépôts contiennent des avis que le propre système d’alerte de GitHub ne détecte pas ?
+
+Il s’agit d’un outil d’audit, et non d’un correcteur. Il lit les données de GitHub et ne modifie rien.
+
+## Pourquoi il a cette structure
+
+| Couche | Choix | Raison |
+|---|---|---|
+| Transport | l’interface de ligne de commande `gh` | Il contient déjà votre jeton. L’outil ne stocke ni ne demande jamais d’informations d’identification. |
+| Collecte | GitHub GraphQL, avec pagination | Une seule requête renvoie les métadonnées, les problèmes ouverts, les demandes de fusion ouvertes, les versions et les arborescences de fichiers pour une page de dépôts. Une page dont le délai d’attente est constamment dépassé est divisée par deux et la requête est renvoyée à partir du même curseur. |
+| Exécutions d’Actions | REST | GraphQL ne dispose pas d’interface Actions. |
+| Coût d’Actions | API de facturation plus durées par tâche | La facture indique de quel dépôt il s’agit ; seules les tâches indiquent de quel flux de travail il s’agit. Les points de terminaison `/timing` de GitHub renvoient des zéros, de sorte que la somme par tâche est reconstruite, puis rapprochée de la facture. |
+| Tarifs des exécuteurs | lu dans la facture | Un tarif facturé peut différer du prix catalogue, et une constante dans la source fausserait tous les chiffres. |
+| Stockage | SQLite via l’outil `node:sqlite` intégré | Aucune étape de compilation native. |
+| Source de vérité | `data/snapshots/*.json` | Brut, diffusable et en ajout uniquement. La base de données est dérivée : `npm run rebuild` la reconstruit hors ligne. |
+| Journal d’analyse | `data/sweeps.jsonl` | Une ligne par analyse, y compris les analyses ayant échoué et les analyses n’ayant rien trouvé de nouveau. |
+
+Les instantanés sont immuables et additifs, de sorte que la dérive entre deux dates est un `JOIN`.
+
+## Exigences
+
+- Node.js 22.5 ou version ultérieure.
+- L’[interface de ligne de commande GitHub](https://cli.github.com/), connectée (`gh auth status`) avec un compte qui peut lire l’organisation. La lecture de la facturation et des alertes de sécurité nécessite les autorisations correspondantes ; une analyse sans ces autorisations enregistre « non mesuré » et continue. Elle n’enregistre jamais une autorisation manquante comme un résultat valide.
+- Windows ou Linux. Il est développé sur Windows et ses tests sont exécutés sur Linux dans le cadre de l’intégration continue. macOS devrait fonctionner et n’est pas testé.
+
+## Utilisation
+
+```bash
+npm install -g @mcptoolshop/housekeeping   # puts `hk` and `hk-mcp` on your path
+mkdir warehouse && cd warehouse            # housekeeping keeps its data here
+hk refresh your-org                        # collect, load, analyze, write reports/AUDIT-<date>.md
+```
+
+Pour conserver les paramètres entre les analyses, placez un fichier `housekeeping.config.json` dans ce répertoire (voir Configuration) ; ensuite, `hk refresh` n’aura besoin d’aucun argument.
+
+Ou exécutez-le à partir d’une copie, ce qui conserve ses données dans la copie :
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/housekeeping.git
+cd housekeeping
+npm install
+npm link                 # puts `hk` on your path
+cp housekeeping.config.example.json housekeeping.config.json   # then set "org"
+hk refresh
+```
+
+Ensuite, interrogez-la :
+
+```bash
+hk summary               # portfolio totals
+hk ci                    # repositories whose default branch is red
+hk findings              # findings grouped by severity and code
+hk health                # per-repository health score, worst first
+hk repo <name>           # one repository in full
+hk prs                   # every open pull request by age
+hk versions              # package.json against git tag against npm
+hk actions               # every workflow and its rule flags
+hk cost                  # Actions cost, gross and net side by side
+hk sql "SELECT ..."      # one read-only statement
+hk help                  # every command and flag
+```
+
+Dans une copie sans fichier `npm link`, chaque exécution de `hk <command>` est `node src/cli.mjs <command>`.
+
+`npm run rebuild` redérive la base de données et le rapport à partir des instantanés déjà présents sur le disque, sans accès au réseau.
+
+Une analyse complète effectue quelques centaines d’appels d’API. N’exécutez pas `refresh` en boucle.
+
+Les résultats sont envoyés vers la sortie standard ; les progrès et les erreurs sont envoyés vers la sortie d’erreur standard. Chaque erreur affiche un code et un indice. Codes de sortie : 0 (ok), 1 (erreur utilisateur), 2 (erreur d’exécution), 3 (partiel, l’analyse est terminée, mais avec des lacunes).
+
+## Configuration
+
+`housekeeping.config.json`, dans le répertoire dans lequel l’outil de maintenance fonctionne (voir ci-dessous) :
+
+```json
+{
+  "org": "your-org",
+  "metaRepos": [".github"]
+}
+```
+
+- `org` est l’organisation à analyser. `hk refresh <org>` le remplace. En l’absence des deux, une analyse refuse de démarrer.
+- `metaRepos` sont les dépôts qui contiennent les paramètres, les ressources ou les outils de l’organisation, et non un produit commercialisé. Ils sont exemptés des résultats qui ne sont pertinents que pour un produit : absence de fichiers README, LICENSE et similaires, absence de flux de travail et absence de versions.
+
+Un fichier malformé est une erreur, et non une valeur par défaut silencieuse : une clé inconnue, un type incorrect ou un JSON corrompu interrompent l’exécution.
+
+Exécution à partir d’un clone, l’outil de maintenance conserve `data/`, `reports/` et le fichier de configuration dans le clone. Exécution en tant que package installé, il les conserve dans le répertoire à partir duquel vous l’exécutez, ou dans `HK_HOME` si celui-ci est défini.
+
+Environnement : `HK_HOME` (où les données, les rapports et la configuration sont stockés), `HK_CONFIG` (chemin du fichier de configuration), `HK_DB` (chemin de la base de données), `HK_LOG` (`silent`, `normal`, `verbose` ou `debug`), `HK_COST_REPOS` et `HK_COST_BUDGET` (limites du coût par tâche), `GH_PATH` (chemin vers `gh`).
+
+## Gardez les données privées
+
+**Ce qu’une analyse écrit est sensible. Ne committez pas `data/` ou `reports/` dans un dépôt public.**
+
+Un instantané enregistre les noms et les descriptions des dépôts privés, chaque alerte de sécurité ouverte avec le package qu’elle mentionne, les fichiers de flux de travail et la facturation d’Actions. GitHub masque délibérément les alertes de sécurité d’un dépôt public à tous, sauf à ses responsables ; un instantané publié diffuserait cette liste.
+
+Le `.gitignore` de ce dépôt exclut `data/`, `reports/` et `housekeeping.config.json`. Pour conserver l’historique, ce qui est l’objectif des instantanés, exécutez l’outil à partir d’un **dépôt privé** et committez-les dans celui-ci.
+
+## Serveur MCP
+
+Le fichier `hk-mcp` (ou `npm run mcp` dans une copie) sert de référentiel via stdio, ce qui permet à un assistant de poser des questions sans avoir à lire un instantané de plusieurs mégaoctets :
+
+`hk_summary` · `hk_findings` · `hk_ci` · `hk_repo` · `hk_backlog` · `hk_health` · `hk_cost` · `hk_sql` · `hk_schema`
+
+```json
+{
+  "mcpServers": {
+    "housekeeping": { "command": "hk-mcp", "env": { "HK_HOME": "/path/to/warehouse" } }
+  }
+}
+```
+
+`HK_HOME` est le répertoire à partir duquel vous effectuez l’analyse. À partir d’une copie, utilisez `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]` à la place.
+
+`hk_sql` accepte une seule instruction `SELECT` ou `WITH` et ouvre la base de données en lecture seule. Un appel ayant échoué renvoie une erreur structurée, et non une trace de pile.
+
+## Résultats
+
+Les règles sont stockées dans `src/analyze.mjs`. Chacune d’entre elles fait référence à la règle écrite qu’elle applique, de sorte qu’un résultat peut être contesté par rapport à une norme et non par rapport au goût. Les règles fournies avec ce dépôt sont disponibles dans [`rules/`](rules/) :
+
+- [`rules/github-actions.md`](rules/github-actions.md) : filtres de chemins, exécuteurs, taille de la matrice, limite du fichier de flux de travail, concurrence.
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md) : l’intégration continue doit réussir, les étapes de validation, les versions.
+- [`rules/repo-first.md`](rules/repo-first.md) : la branche par défaut.
+- [`rules/atlas-map.md`](rules/atlas-map.md) : une carte validée de chaque dépôt, vérifiée dans l’intégration continue.
+
+Ce sont les normes d’une organisation. Si les vôtres sont différentes, modifiez le fichier de règle et la règle elle-même.
+
+Les règles veillent à séparer les éléments qui se ressemblent, car les regrouper crée du bruit :
+
+- **Une branche par défaut rouge n’est pas une branche de demande de fusion rouge.** Une branche Dependabot qui échoue est un élément en attente ; une exécution `push` qui échoue sur la branche par défaut est une erreur. L’événement de l’exécution détermine lequel.
+- **L’historique n’est pas une erreur.** Un flux de travail déplacé vers des déclencheurs de publication uniquement conserve son dernier échec de branche par défaut pour toujours. Un flux de travail supprimé conserve ses exécutions. Aucun n’est un défaut actif.
+- **Une vérification requise qui ne peut rien produire n’est pas une vérification qui n’a pas été exécutée ici.** L’une indique qu’il faut supprimer l’exigence ; l’autre indique qu’il faut corriger le déclencheur. Les corrections se contredisent.
+- **Une exécution ayant échoué n’est pas une exécution annulée.** `cancel-in-progress` sert à arrêter les exécutions obsolètes, de sorte que les minutes annulées correspondent généralement au fonctionnement de la règle de concurrence.
+- **Le coût brut n’est pas le coût net.** GitHub facture les dépôts publics au prix fort et les réduit à zéro. Le coût brut est la puissance de calcul réelle ; le coût net est l’argent réel. Ils ne sont jamais additionnés.
+- **Ce qui n’est pas mesuré n’est pas propre.** Un dépôt GitHub qui n’effectue pas d’analyse signale zéro alerte. Un dépôt pour lequel le seuil de coût n’a pas été atteint n’a pas de ligne de coût. Les deux sont signalés comme inconnus.
+
+La gravité détermine un score de santé : critique 40, élevé 15, moyen 6, faible 2, information 0, déduit de 100. Le score classe l’attention, et non la qualité.
+
+Le [manuel](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) répertorie chaque résultat, commande, code d’erreur et tableau.
+
+## Sécurité
+
+- **Lecture seule.** Le collecteur effectue des requêtes GraphQL et des requêtes REST `GET`. Il ne fusionne, ne pousse, ne publie, ne distribue ni ne modifie jamais un paramètre.
+- **Aucun identifiant.** L’authentification est ce que `gh` contient déjà. Rien n’est écrit sur le disque à ce sujet.
+- **Aucune télémétrie.** Les seuls hôtes contactés sont l’API GitHub, via `gh`, et le registre npm, pour les recherches de versions et de conseils.
+- **Ce qu’il stocke** est la partie sensible : voir « Conserver les données en privé ».
+
+Signalez une vulnérabilité comme décrit dans [SECURITY.md](SECURITY.md).
+
+## Tests
+
+```bash
+npm test
+```
+
+Chaque règle est testée dans les deux sens : la forme qui doit être déclenchée et la forme voisine qui ne doit pas l’être. Un vérificateur distinct redérive un échantillon de résultats à partir de GitHub en direct via son propre transport, et saute, bruyamment, lorsqu’il n’y a pas de base de données ou de réseau.
+
+## Licence
+
+MIT. Voir [LICENSE](LICENSE).
+
+---
+
+Créé par <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>