@mcptoolshop/housekeeping 0.0.0 → 1.3.0

package/README.hi.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.fr.md">Français</a> | <a href="README.md">English</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>
+
+एक बार स्कैन करने पर, प्रत्येक रिपॉजिटरी की सीआई स्थिति, खुली समस्याओं और पुल अनुरोधों, रिलीज़, संस्करण टैग, वर्कफ़्लो फ़ाइलों, शाखा सुरक्षा, सुरक्षा अलर्ट, लॉकफ़ाइलों और एक्शन बिलिंग को SQLite में एकत्र किया जाता है, फिर उन सभी का लिखित नियमों के अनुसार ऑडिट किया जाता है।
+
+यह एक साथ पूरी संस्था के लिए उत्तर देता है:
+
+- कौन सी डिफ़ॉल्ट शाखाएँ लाल हैं, और क्या यह एक टूटी हुई मुख्य शाखा या पुरानी इतिहास है?
+- कौन से पुल अनुरोध कभी भी मर्ज नहीं हो सकते, क्योंकि एक आवश्यक जाँच अवरुद्ध हो रही है?
+- रिपॉजिटरी की अपनी सेटिंग्स कौन से डिप्लॉय को अस्वीकार करती हैं?
+- `package.json`, गिट टैग और npm रजिस्ट्री कहाँ अलग हो गए हैं?
+- कौन से वर्कफ़्लो एक्शन लागत नियमों का उल्लंघन करते हैं, उनकी लागत क्या थी, और किन कार्यों ने इसे खर्च किया?
+- किन रिपॉजिटरी में ऐसी सलाहें हैं जिन्हें GitHub के अपने अलर्ट काउंट में शामिल नहीं किया गया है?
+
+यह एक ऑडिट उपकरण है, न कि एक सुधारक। यह GitHub को पढ़ता है और कुछ भी नहीं बदलता है।
+
+## यह इस तरह से क्यों बनाया गया है
+
+| लेयर | विकल्प | तर्क |
+|---|---|---|
+| परिवहन | `gh` CLI | इसमें पहले से ही आपका टोकन है। उपकरण कभी भी क्रेडेंशियल संग्रहीत या मांगता नहीं है। |
+| संग्रह | GitHub GraphQL, पेज किया गया | एक क्वेरी एक पृष्ठ की रिपॉजिटरी के लिए मेटाडेटा, खुली समस्याएं, खुले पुल अनुरोध, रिलीज़ और फ़ाइल ट्री लौटाती है। एक ऐसा पृष्ठ जो लगातार समय समाप्त हो रहा है, उसे आधा कर दिया जाता है और उसी कर्सर से फिर से पूछा जाता है। |
+| एक्शन रन | REST | GraphQL में कोई एक्शन सतह नहीं है। |
+| एक्शन लागत | बिलिंग API प्लस प्रति-कार्य अवधि | चालान में बताया गया है कि कौन सी रिपॉजिटरी है; केवल कार्यों में बताया गया है कि कौन सा वर्कफ़्लो। GitHub के `/timing` एंडपॉइंट शून्य लौटाते हैं, इसलिए प्रति-कार्य योग को फिर से बनाया जाता है और फिर चालान के साथ मिलान किया जाता है। |
+| रनर दरें | चालान से पढ़ें | एक बिल की गई दर सूची मूल्य से भिन्न हो सकती है, और स्रोत में एक स्थिर मान हर संख्या को गलत बताएगा। |
+| भंडारण | अंतर्निहित `node:sqlite` के माध्यम से SQLite | कोई देशी बिल्ड चरण नहीं। |
+| सत्य का स्रोत | `data/snapshots/*.json` | कच्चा, तुलना करने योग्य और केवल जोड़ने योग्य। डेटाबेस व्युत्पन्न है: `npm run rebuild` इसे ऑफ़लाइन पुनर्निर्मित करता है। |
+| स्कैन लॉग | `data/sweeps.jsonl` | प्रत्येक स्कैन के लिए एक पंक्ति, जिसमें वे स्कैन भी शामिल हैं जो विफल रहे और वे स्कैन जिनमें कुछ भी नया नहीं मिला। |
+
+स्नैपशॉट अपरिवर्तनीय और योज्य होते हैं, इसलिए दो तिथियों के बीच का विचलन `JOIN` है।
+
+## आवश्यकताएँ
+
+- Node.js 22.5 या बाद का संस्करण।
+- [GitHub CLI](https://cli.github.com/), साइन इन किया हुआ (`gh auth status`) एक ऐसे खाते के रूप में जो संगठन को पढ़ सकता है। बिलिंग और सुरक्षा अलर्ट पढ़ने के लिए संबंधित एक्सेस की आवश्यकता होती है; इसके बिना स्कैन "मापा नहीं गया" रिकॉर्ड करता है और आगे बढ़ता है। यह कभी भी गुम अनुमति को एक स्वच्छ परिणाम के रूप में रिकॉर्ड नहीं करता है।
+- विंडोज या लिनक्स। इसे विंडोज पर विकसित किया गया है और इसके परीक्षण CI में लिनक्स पर चलते हैं। macOS को काम करना चाहिए और इसका परीक्षण नहीं किया गया है।
+
+## उपयोग
+
+```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
+```
+
+सेटिंग्स को बनाए रखने के लिए, उस निर्देशिका में `housekeeping.config.json` रखें (कॉन्फ़िगरेशन देखें); फिर `hk refresh` को किसी तर्क की आवश्यकता नहीं होगी।
+
+या इसे क्लोन से चलाएं, जो अपने डेटा को क्लोन में रखता है:
+
+```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
+```
+
+फिर इसे क्वेरी करें:
+
+```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
+```
+
+एक क्लोन में जिसमें `npm link` नहीं है, प्रत्येक `hk <command>` `node src/cli.mjs <command>` होता है।
+
+`npm run rebuild` डेटाबेस और रिपोर्ट को डिस्क पर पहले से मौजूद स्नैपशॉट से पुनर्निर्मित करता है, बिना किसी नेटवर्क एक्सेस के।
+
+एक पूर्ण स्कैन कुछ सौ API कॉल करता है। `refresh` को लूप में न चलाएं।
+
+परिणाम मानक आउटपुट पर जाते हैं; प्रगति और त्रुटियां मानक त्रुटि पर जाती हैं। प्रत्येक त्रुटि एक कोड और एक संकेत प्रिंट करती है। निकास कोड: 0 ठीक, 1 उपयोगकर्ता त्रुटि, 2 रनटाइम त्रुटि, 3 आंशिक (स्कैन समाप्त हो गया, अंतराल के साथ)।
+
+## कॉन्फ़िगरेशन
+
+`housekeeping.config.json`, उस निर्देशिका में जिसमें हाउसकीपिंग काम करता है (नीचे देखें):
+
+```json
+{
+  "org": "your-org",
+  "metaRepos": [".github"]
+}
+```
+
+- `org` वह संगठन है जिसे स्कैन करना है। `hk refresh <org>` इसे ओवरराइड करता है। दोनों में से किसी के बिना, स्कैन शुरू करने से इनकार कर देगा।
+- `metaRepos` वे रिपॉजिटरी हैं जिनमें संगठन डिफ़ॉल्ट, संपत्ति या उपकरण होते हैं, न कि एक शिप किया गया उत्पाद। वे उन निष्कर्षों से छूट प्राप्त हैं जो केवल किसी उत्पाद के लिए समझ में आते हैं: गुम README, LICENSE और समान फ़ाइलें, कोई वर्कफ़्लो नहीं होना और कोई रिलीज़ नहीं होना।
+
+एक गलत फ़ाइल एक त्रुटि है, कभी भी एक मौन डिफ़ॉल्ट नहीं: एक अज्ञात कुंजी, एक गलत प्रकार या टूटा हुआ JSON रन को रोक देता है।
+
+एक क्लोन से चलाएं, हाउसकीपिंग `data/`, `reports/` और कॉन्फ़िगरेशन फ़ाइल को क्लोन में रखता है। एक स्थापित पैकेज के रूप में चलाएं, यह उन्हें उस निर्देशिका में रखता है जिससे आप इसे चलाते हैं, या `HK_HOME` में जब वह सेट हो।
+
+पर्यावरण: `HK_HOME` (जहां डेटा, रिपोर्ट और कॉन्फ़िगरेशन रहते हैं), `HK_CONFIG` (कॉन्फ़िगरेशन पथ), `HK_DB` (डेटाबेस पथ), `HK_LOG` (`silent`, `normal`, `verbose` या `debug`), `HK_COST_REPOS` और `HK_COST_BUDGET` (प्रति-कार्य लागत सीमा), `GH_PATH` (`gh` का पथ)।
+
+## डेटा को निजी रखें
+
+**एक स्कैन जो लिखता है वह संवेदनशील है। `data/` या `reports/` को सार्वजनिक रिपॉजिटरी में कमिट न करें।**
+
+एक स्नैपशॉट निजी रिपॉजिटरी के नाम और विवरण, प्रत्येक खुली सुरक्षा अलर्ट जिसमें वह पैकेज है जिसका वह उल्लेख करता है, वर्कफ़्लो फ़ाइलें और एक्शन बिलिंग रिकॉर्ड करता है। GitHub जानबूझकर एक सार्वजनिक रिपॉजिटरी की सुरक्षा अलर्ट को सभी से छिपा देता है, सिवाय इसके रखरखावकर्ताओं के; एक प्रकाशित स्नैपशॉट उस सूची को दे देगा।
+
+इस रिपॉजिटरी का `.gitignore` `data/`, `reports/` और `housekeeping.config.json` को बाहर करता है। इतिहास को बनाए रखने के लिए, जो स्नैपशॉट का बिंदु है, अपने स्वयं के एक निजी रिपॉजिटरी से उपकरण चलाएं और उन्हें वहां कमिट करें।
+
+## MCP सर्वर
+
+`hk-mcp` (या क्लोन में `npm run mcp`) stdio के माध्यम से डेटाबेस को सेवा प्रदान करता है, इसलिए एक सहायक बिना मल्टी-मेगाबाइट स्नैपशॉट पढ़े प्रश्न पूछ सकता है:
+
+`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` वह निर्देशिका है जिससे आप डेटा लेते हैं। क्लोन से, इसके बजाय `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]` का उपयोग करें।
+
+`hk_sql` एक एकल `SELECT` या `WITH` कथन स्वीकार करता है और डेटाबेस को केवल-पढ़ने के लिए खोलता है। एक विफल कॉल एक संरचित त्रुटि लौटाती है, कभी भी स्टैक ट्रेस नहीं।
+
+## निष्कर्ष
+
+नियम `src/analyze.mjs` में रहते हैं। प्रत्येक नियम उस लिखित नियम का हवाला देता है जिसे वह लागू करता है, इसलिए एक निष्कर्ष को एक मानक के खिलाफ तर्क दिया जा सकता है, न कि स्वाद के खिलाफ। इस रिपॉजिटरी में शिप किए गए नियम [`rules/`](rules/) में हैं:
+
+- [`rules/github-actions.md`](rules/github-actions.md): पाथ फ़िल्टर, रनर, मैट्रिक्स आकार, वर्कफ़्लो फ़ाइल सीमा, समवर्तीता।
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): सीआई को पास होना चाहिए, शिप गेट, संस्करण।
+- [`rules/repo-first.md`](rules/repo-first.md): डिफ़ॉल्ट शाखा।
+- [`rules/atlas-map.md`](rules/atlas-map.md): प्रत्येक रिपॉजिटरी का एक प्रतिबद्ध मानचित्र, सीआई में जांचा गया।
+
+ये किसी एक संगठन के मानक हैं। यदि आपके मानक अलग हैं, तो नियम फ़ाइल और नियम को बदलें।
+
+नियम उन चीजों को अलग रखने का ध्यान रखते हैं जो समान दिखती हैं, क्योंकि उन्हें एक साथ मिलाने से शोर उत्पन्न होता है:
+
+- **एक लाल डिफ़ॉल्ट शाखा, लाल पुल-अनुरोध शाखा नहीं है।** एक विफल डिपेंडबॉट शाखा बैकलॉग है; डिफ़ॉल्ट शाखा पर एक विफल `push` रन, खराबी है। रन का इवेंट यह तय करता है कि कौन सा।
+- **इतिहास खराबी नहीं है।** केवल रिलीज़ के लिए ट्रिगर करने वाले वर्कफ़्लो को स्थानांतरित करने से, इसकी पिछली डिफ़ॉल्ट-शाखा विफलता हमेशा बनी रहती है। एक हटाई गई वर्कफ़्लो अपनी रन को बरकरार रखती है। न तो यह कोई सक्रिय दोष है।
+- **एक आवश्यक जांच, जो कुछ भी उत्सर्जित नहीं कर सकती, वह जांच नहीं है जो यहां नहीं चली।** एक कहता है कि आवश्यकता को छोड़ दें; दूसरा कहता है कि ट्रिगर को ठीक करें। दोनों मरम्मत एक-दूसरे का खंडन करते हैं।
+- **एक विफल रन, रद्द किया गया रन नहीं है।** `cancel-in-progress` का उद्देश्य पुराने रन को समाप्त करना है, इसलिए रद्द किए गए मिनट आमतौर पर समवर्तीता नियम के काम करने का परिणाम होते हैं।
+- **कुल लागत, शुद्ध लागत नहीं है।** GitHub सार्वजनिक रिपॉजिटरी को पूरी कीमत पर मापता है और उन्हें शून्य पर छूट देता है। कुल वास्तविक कंप्यूट है; शुद्ध वास्तविक धन है। उन्हें कभी भी जोड़ा नहीं जाता है।
+- **जो मापा नहीं गया, वह साफ नहीं है।** एक रिपॉजिटरी जिसे GitHub स्कैन नहीं कर रहा है, उसमें शून्य अलर्ट होते हैं। एक रिपॉजिटरी जिसकी लागत सीमा तक नहीं पहुंची, उसमें कोई लागत पंक्ति नहीं है। दोनों को अज्ञात के रूप में रिपोर्ट किया जाता है।
+
+गंभीरता एक स्वास्थ्य स्कोर निर्धारित करती है: गंभीर 40, उच्च 15, मध्यम 6, निम्न 2, सूचना 0, जो 100 से घटाया जाता है। स्कोर गुणवत्ता के बजाय ध्यान को रैंक करता है।
+
+[हैंडबुक](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) में प्रत्येक निष्कर्ष, कमांड, त्रुटि कोड और तालिका सूचीबद्ध है।
+
+## सुरक्षा
+
+- **केवल पढ़ने के लिए।** कलेक्टर GraphQL क्वेरी और REST `GET` जारी करता है। यह कभी भी किसी सेटिंग को मर्ज, पुश, रिलीज़, प्रकाशित या संपादित नहीं करता है।
+- **कोई क्रेडेंशियल नहीं।** प्रमाणीकरण वह है जो `gh` पहले से ही रखता है। इसके बारे में कुछ भी डिस्क पर नहीं लिखा जाता है।
+- **कोई टेलीमेट्री नहीं।** संपर्क किए गए एकमात्र होस्ट GitHub API हैं, `gh` के माध्यम से, और संस्करण और सलाह की जानकारी के लिए npm रजिस्ट्री।
+- **यह जो संग्रहीत करता है** वह संवेदनशील भाग है: "डेटा को निजी रखें" देखें।
+
+[SECURITY.md](SECURITY.md) में वर्णित अनुसार किसी भेद्यता की रिपोर्ट करें।
+
+## परीक्षण
+
+```bash
+npm test
+```
+
+प्रत्येक नियम का दोनों दिशाओं में परीक्षण किया जाता है: वह आकार जो सक्रिय होना चाहिए, और पड़ोसी आकार जो सक्रिय नहीं होना चाहिए। एक अलग सत्यापनकर्ता, अपने स्वयं के परिवहन के माध्यम से, लाइव GitHub से निष्कर्षों का एक नमूना फिर से प्राप्त करता है, और जब कोई डेटाबेस या नेटवर्क नहीं होता है, तो जोर से छोड़ देता है।
+
+## लाइसेंस
+
+MIT. [LICENSE](LICENSE) देखें।
+
+---
+
+<a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> द्वारा निर्मित।

package/README.it.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.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.md">English</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>
+
+Un singolo ciclo di scansione raccoglie lo stato CI di ogni repository, le issue aperte e le richieste di pull, le release, i tag di versione, i file di workflow, le protezioni dei branch, gli avvisi di sicurezza, i file di blocco e i dati di fatturazione di Actions in SQLite, quindi esegue un controllo completo rispetto alle regole definite.
+
+Fornisce risposte, per l'intera organizzazione contemporaneamente:
+
+- Quali sono i branch predefiniti contrassegnati come problematici e si tratta di una branch principale interrotta o di una cronologia obsoleta?
+- Quali richieste di pull non possono essere unite, perché un controllo richiesto che non produce alcun risultato le sta bloccando?
+- Quali distribuzioni vengono rifiutate dalle impostazioni del repository stesso?
+- Dove sono divergenti `package.json`, i tag Git e il registro npm?
+- Quali workflow violano le regole sui costi di Actions, quanto sono costati e quali job hanno consumato tali costi?
+- Quali repository contengono avvisi che il sistema di avvisi di GitHub non rileva?
+
+È uno strumento di audit, non uno strumento di correzione. Legge i dati di GitHub e non apporta alcuna modifica.
+
+## Perché è strutturato in questo modo:
+
+| Livello | Scelta | Motivazione |
+|---|---|---|
+| Trasporto | L'interfaccia a riga di comando `gh` | Contiene già il token. Lo strumento non memorizza né richiede credenziali. |
+| Raccolta | GitHub GraphQL, con paginazione | Una singola query restituisce metadati, issue aperte, richieste di pull aperte, release e alberi di file per una pagina di repository. Una pagina che continua a superare il tempo limite viene dimezzata e la richiesta viene ripetuta dallo stesso cursore. |
+| Esecuzioni di Actions | REST | GraphQL non dispone di un'interfaccia per Actions. |
+| Costi di Actions | API di fatturazione più durate per singolo job | La fattura indica il repository; solo i job indicano il workflow. Gli endpoint `/timing` di GitHub restituiscono zeri, quindi la somma per singolo job viene ricostruita e quindi riconciliata con la fattura. |
+| Tariffe dei runner | lettura dalla fattura | Una tariffa fatturata può differire dal prezzo di listino e una costante nel codice sorgente falsificherebbe tutti i numeri. |
+| Archiviazione | SQLite tramite l'implementazione `node:sqlite` integrata | Nessun passaggio di compilazione nativo. |
+| Fonte di verità | `data/snapshots/*.json` | Dati grezzi, modificabili e con aggiunte successive. Il database viene derivato: `npm run rebuild` lo ricostruisce offline. |
+| Log della scansione | `data/sweeps.jsonl` | Una riga per ogni scansione, comprese le scansioni che hanno avuto esito negativo e le scansioni che non hanno trovato nuovi dati. |
+
+Gli snapshot sono immutabili e additivi, quindi la differenza tra due date è un `JOIN`.
+
+## Requisiti
+
+- Node.js 22.5 o successivo.
+- L'interfaccia a riga di comando di [GitHub](https://cli.github.com/), con accesso (`gh auth status`) come account in grado di leggere l'organizzazione. La lettura dei dati di fatturazione e degli avvisi di sicurezza richiede i permessi corrispondenti; una scansione senza tali permessi registra "non misurato" e continua. Non registra mai un permesso mancante come risultato valido.
+- Windows o Linux. È sviluppato su Windows e i test vengono eseguiti su Linux in CI. macOS dovrebbe funzionare e non è testato.
+
+## Utilizzo
+
+```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
+```
+
+Per conservare le impostazioni tra le diverse esecuzioni, inserire un file `housekeeping.config.json` in quella directory (vedere Configurazione); quindi `hk refresh` non richiede alcun argomento.
+
+Oppure eseguirlo da una copia, che conserva i suoi dati nella 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
+```
+
+Quindi, esegui una query:
+
+```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
+```
+
+In una copia senza il file `npm link`, ogni esecuzione di `hk <command>` è `node src/cli.mjs <command>`.
+
+`npm run rebuild` ricostruisce il database e il report dagli snapshot già presenti sul disco, senza accesso alla rete.
+
+Una scansione completa effettua alcune centinaia di chiamate API. Non eseguire `refresh` in un ciclo.
+
+I risultati vengono inviati all'output standard; i progressi e gli errori vengono inviati all'output di errore standard. Ogni errore stampa un codice e un suggerimento. Codici di uscita: 0 (tutto ok), 1 (errore utente), 2 (errore di runtime), 3 (parziale, la scansione è terminata, ma con delle lacune).
+
+## Configurazione
+
+`housekeeping.config.json`, nella directory in cui opera housekeeping (vedere di seguito):
+
+```json
+{
+  "org": "your-org",
+  "metaRepos": [".github"]
+}
+```
+
+- `org` è l'organizzazione da sottoporre a scansione. `hk refresh <org>` lo sovrascrive. In assenza di entrambi, la scansione non viene avviata.
+- `metaRepos` sono i repository che contengono le impostazioni predefinite dell'organizzazione, le risorse o gli strumenti, e non un prodotto distribuito. Sono esenti dai risultati che hanno senso solo per un prodotto: mancanza di file README, LICENSE e simili, assenza di workflow e assenza di release.
+
+Un file non valido è un errore, mai un valore predefinito silenzioso: una chiave sconosciuta, un tipo errato o un JSON non valido interrompono l'esecuzione.
+
+Esegui da una copia clonata, housekeeping mantiene `data/`, `reports/` e il file di configurazione nella copia clonata. Esegui come pacchetto installato, li mantiene nella directory da cui lo esegui o in `HK_HOME` quando è impostato.
+
+Ambiente: `HK_HOME` (dove risiedono i dati, i report e la configurazione), `HK_CONFIG` (percorso della configurazione), `HK_DB` (percorso del database), `HK_LOG` (`silent`, `normal`, `verbose` o `debug`), `HK_COST_REPOS` e `HK_COST_BUDGET` (limiti per il costo per singolo job), `GH_PATH` (percorso di `gh`).
+
+## Mantieni i dati privati
+
+**I dati scritti da una scansione sono sensibili. Non inserire `data/` o `reports/` in un repository pubblico.**
+
+Uno snapshot registra i nomi e le descrizioni dei repository privati, ogni avviso di sicurezza aperto con il pacchetto a cui si riferisce, i file di workflow e i dati di fatturazione di Actions. GitHub nasconde deliberatamente gli avvisi di sicurezza di un repository pubblico a tutti tranne che ai suoi manutentori; uno snapshot pubblicato fornirebbe tale elenco.
+
+Il `.gitignore` di questo repository esclude `data/`, `reports/` e `housekeeping.config.json`. Per mantenere la cronologia, che è lo scopo degli snapshot, esegui lo strumento da un repository **privato** di tua proprietà e inserisci gli snapshot lì.
+
+## Server MCP
+
+Il file `hk-mcp` (o `npm run mcp` in una copia) gestisce l’accesso al database tramite stdio, quindi un assistente può porre domande senza dover leggere un file di diversi megabyte:
+
+`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` è la directory da cui si avvia l’esecuzione. In caso di copia, utilizzare invece `"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`.
+
+`hk_sql` accetta una singola istruzione `SELECT` o `WITH` e apre il database in sola lettura. Una chiamata non riuscita restituisce un errore strutturato, mai una traccia dello stack.
+
+## Risultati
+
+Le regole sono contenute in `src/analyze.mjs`. Ognuna di esse fa riferimento alla regola scritta che applica, in modo che un risultato possa essere contestato rispetto a uno standard e non al gusto personale. Le regole fornite con questo repository sono in [`rules/`](rules/):
+
+- [`rules/github-actions.md`](rules/github-actions.md): filtri per i percorsi, runner, dimensione della matrice, limite del file di flusso di lavoro, concorrenza.
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): la CI deve essere superata, i controlli di rilascio, le versioni.
+- [`rules/repo-first.md`](rules/repo-first.md): il ramo predefinito.
+- [`rules/atlas-map.md`](rules/atlas-map.md): una mappa registrata di ciascun repository, verificata nella CI.
+
+Questi sono gli standard di un'organizzazione. Se i tuoi sono diversi, modifica il file delle regole e la regola stessa.
+
+Le regole si assicurano di mantenere separate le cose che sembrano simili, perché combinarle genera confusione:
+
+- **Un ramo predefinito "rosso" non è un ramo di richiesta di pull "rosso".** Un ramo di Dependabot che fallisce rappresenta un elemento in sospeso; un'esecuzione di `push` che fallisce sul ramo predefinito rappresenta un problema. L'evento dell'esecuzione determina quale sia.
+- **La cronologia non è un problema.** Un flusso di lavoro spostato in un trigger solo per i rilasci mantiene il suo ultimo errore sul ramo predefinito per sempre. Un flusso di lavoro eliminato mantiene le sue esecuzioni. Nessuno dei due è un difetto attivo.
+- **Un controllo obbligatorio che non può emettere nulla non è un controllo che non è stato eseguito qui.** Uno indica di eliminare il requisito; l'altro indica di correggere il trigger. Le correzioni si contraddicono a vicenda.
+- **Un'esecuzione fallita non è un'esecuzione annullata.** `cancel-in-progress` esiste per terminare le esecuzioni obsolete, quindi i minuti annullati sono solitamente la regola di concorrenza in funzione.
+- **Il costo lordo non è il costo netto.** GitHub calcola i costi dei repository pubblici al prezzo pieno e li riduce a zero. Il costo lordo è la potenza di calcolo reale; il costo netto è il denaro reale. Non vengono mai sommati.
+- **Se non viene misurato, non è corretto.** Un repository GitHub che non esegue la scansione segnala zero avvisi. Un repository per il quale il controllo dei costi non è stato raggiunto non ha una riga di costo. Entrambi vengono segnalati come sconosciuti.
+
+La gravità determina un punteggio di salute: critico 40, alto 15, medio 6, basso 2, informativo 0, dedotto da 100. Il punteggio classifica l'attenzione, non la qualità.
+
+Il [manuale](https://mcp-tool-shop-org.github.io/housekeeping/handbook/) elenca ogni riscontro, comando, codice di errore e tabella.
+
+## Sicurezza
+
+- **Solo lettura.** Il raccoglitore invia query GraphQL e richieste REST `GET`. Non esegue mai operazioni di merge, push, rilascio, pubblicazione o modifica di un'impostazione.
+- **Nessuna credenziale.** L'autenticazione è quella già presente in `gh`. Nulla viene scritto su disco al riguardo.
+- **Nessuna telemetria.** Gli unici host contattati sono l'API di GitHub, tramite `gh`, e il registro npm, per la ricerca di versioni e avvisi.
+- **Ciò che memorizza** è la parte sensibile: vedere "Mantenere i dati privati".
+
+Segnala una vulnerabilità come descritto in [SECURITY.md](SECURITY.md).
+
+## Test
+
+```bash
+npm test
+```
+
+Ogni regola viene testata in entrambe le direzioni: la forma che deve attivarsi e la forma adiacente che non deve attivarsi. Un verificatore separato deriva nuovamente un campione di risultati da GitHub in tempo reale tramite il proprio trasporto e salta, in modo evidente, quando non è presente un database o una rete.
+
+## Licenza
+
+MIT. Vedere [LICENSE](LICENSE).
+
+---
+
+Creato da <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

package/README.ja.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</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>
+
+1回のスキャンで、すべてのリポジトリのCIステータス、未解決の問題、プルリクエスト、リリース、バージョンタグ、ワークフローファイル、ブランチ保護、セキュリティアラート、ロックファイル、およびActionsの課金をSQLiteに収集し、次に、それらすべてを記述されたルールに対して監査します。
+
+これにより、組織全体に対して、以下のことが一度に回答されます。
+
+- どのデフォルトブランチが問題があり、それが壊れたメインラインまたは古い履歴ですか？
+- 必須チェックが何も実行されていないために、どのプルリクエストもマージできませんか？
+- リポジトリ自体の設定では、どのデプロイが拒否されますか？
+- `package.json`、Gitタグ、およびnpmレジストリは、どこで乖離していますか？
+- どのワークフローがActionsのコストルールに違反し、それらのコストはいくらで、どのジョブがそのコストを消費しましたか？
+- どのリポジトリに、GitHub自体のアラートカウントでは検出されないアドバイザリーが含まれていますか？
+
+これは監査ツールであり、修正ツールではありません。GitHubを読み取り、何も変更しません。
+
+## この構造になっている理由
+
+| レイヤー | 選択 | 理由 |
+|---|---|---|
+| 転送 | `gh` CLI | すでにトークンを保持しています。このツールは、認証情報を保存したり、要求したりすることはありません。 |
+| 収集 | GitHub GraphQL、ページング | 1つのクエリで、リポジトリの1ページのメタデータ、未解決の問題、未解決のプルリクエスト、リリース、およびファイルツリーが返されます。タイムアウトし続けるページは半分にされ、同じカーソルから再要求されます。 |
+| Actionsの実行 | REST | GraphQLにはActionsのインターフェースはありません。 |
+| Actionsのコスト | 請求APIと、ジョブごとの期間 | 請求書にはどのリポジトリであるかが記載されています。ジョブにはどのワークフローであるかが記載されています。GitHubの`/timing`エンドポイントはゼロを返すため、ジョブごとの合計を再計算し、次に請求書と照合します。 |
+| ランナーの料金 | 請求書から読み取ります | 請求される料金は、リスト価格と異なる場合があり、ソースに定数を使用すると、すべての数値が誤って表示されます。 |
+| ストレージ | 組み込みの`node:sqlite`を介したSQLite | ネイティブのビルドステップはありません。 |
+| 真実のソース | `data/snapshots/*.json` | 生の、差分化可能で、追加のみのデータ。データベースは派生したものです。`npm run rebuild`は、オフラインで再構築します。 |
+| スキャンログ | `data/sweeps.jsonl` | 1つのスキャンあたり1行。これには、失敗したスキャンと、新しいものが見つからなかったスキャンが含まれます。 |
+
+スナップショットは不変で追加されるため、2つの日付間のドリフトは`JOIN`です。
+
+## 要件
+
+- Node.js 22.5 or later.
+- The [GitHub CLI](https://cli.github.com/), signed in (`gh auth status`) as an
+  account that can read the organization. Reading billing and security alerts
+  needs the matching access; a sweep without it records "not measured" and
+  carries on. It never records a missing permission as a clean result.
+- Windows or Linux. It is developed on Windows and its tests run on Linux in
+  CI. macOS should work and is not tested.
+
+## 使用方法
+
+```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
+```
+
+スキャン間で設定を保持するには、そのディレクトリに`housekeeping.config.json`を配置します（構成を参照）。その後、`hk refresh`には引数は必要ありません。
+
+または、クローンから実行すると、そのデータがクローン内に保持されます。
+
+```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
+```
+
+次に、クエリを実行します。
+
+```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
+```
+
+`npm link`がないクローンでは、各`hk <command>`は`node src/cli.mjs <command>`になります。
+
+`npm run rebuild`は、ディスクにすでに存在するスナップショットからデータベースとレポートを再構築し、ネットワークアクセスは行いません。
+
+完全なスキャンでは、数百のAPI呼び出しが行われます。`refresh`をループで実行しないでください。
+
+結果は標準出力に出力され、進行状況とエラーは標準エラーに出力されます。すべてのエラーには、コードとヒントが出力されます。終了コード：0（正常）、1（ユーザーエラー）、2（実行時エラー）、3（部分的（スキャンは完了しましたが、ギャップがあります））。
+
+## 構成
+
+`housekeeping.config.json`は、ハウスキーピングが機能するディレクトリにあります（以下を参照）。
+
+```json
+{
+  "org": "your-org",
+  "metaRepos": [".github"]
+}
+```
+
+- `org`は、スキャンする組織です。`hk refresh <org>`でオーバーライドできます。どちらも指定されていない場合、スキャンは開始されません。
+- `metaRepos`は、組織のデフォルト、アセット、またはツールを保持するリポジトリであり、出荷される製品ではありません。これらは、README、LICENSEなどのファイルがない、ワークフローがない、リリースがないなど、製品にのみ意味がある結果から除外されます。
+
+形式が正しくないファイルはエラーであり、サイレントなデフォルトになることはありません。不明なキー、誤った型、または破損したJSONは、実行を停止します。
+
+クローンから実行する場合、ハウスキーピングは`data/`、`reports/`、および構成ファイルをクローンに保持します。インストールされたパッケージとして実行する場合、それらは実行するディレクトリまたは、設定されている場合は`HK_HOME`に保持されます。
+
+環境：`HK_HOME`（データ、レポート、および構成が保存される場所）、`HK_CONFIG`（構成パス）、`HK_DB`（データベースパス）、`HK_LOG`（`silent`、`normal`、`verbose`、または`debug`）、`HK_COST_REPOS`、および`HK_COST_BUDGET`（ジョブごとのコストの範囲）、`GH_PATH`（`gh`へのパス）。
+
+## データを非公開に保つ
+
+**スキャンによって書き込まれる内容は機密情報です。`data/`または`reports/`をパブリックリポジトリにコミットしないでください。**
+
+スナップショットには、プライベートリポジトリの名前と説明、パッケージ名を含むすべての未解決のセキュリティアラート、ワークフローファイル、およびActionsの課金が記録されます。GitHubは、パブリックリポジトリのセキュリティアラートを、そのリポジトリのメンテナー以外のすべてのユーザーから意図的に非表示にします。公開されたスナップショットは、そのリストを公開することになります。
+
+このリポジトリの`.gitignore`は、`data/`、`reports/`、および`housekeeping.config.json`を除外します。履歴を保持することがスナップショットの目的であるため、独自の**プライベート**リポジトリからツールを実行し、そこにコミットしてください。
+
+## MCPサーバー
+
+`hk-mcp`（またはクローン内の`npm run mcp`）は、標準入出力（stdio）を介してデータストアにアクセスするため、アシスタントは数メガバイトのデータ全体を読み込むことなく質問をすることができます。
+
+`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`は、スキャンを開始するディレクトリです。クローンから実行する場合は、代わりに`"command": "node", "args": ["/path/to/housekeeping/src/mcp.mjs"]`を使用します。
+
+`hk_sql`は、単一の`SELECT`または`WITH`ステートメントを受け入れ、データベースを読み取り専用で開きます。失敗した呼び出しは、スタックトレースではなく、構造化されたエラーを返します。
+
+## 検出結果
+
+ルールは`src/analyze.mjs`にあります。各ルールは、適用する記述されたルールを参照するため、検出結果は、好みに基づいてではなく、標準に対して議論することができます。このリポジトリに付属するルールは、[`rules/`](rules/)にあります。
+
+- [`rules/github-actions.md`](rules/github-actions.md): パスのフィルター、ランナー、マトリックスのサイズ、ワークフローファイルの制限、同時実行。
+- [`rules/shipcheck-product-standards.md`](rules/shipcheck-product-standards.md): CIに合格していること、出荷ゲート、バージョン。
+- [`rules/repo-first.md`](rules/repo-first.md): デフォルトブランチ。
+- [`rules/atlas-map.md`](rules/atlas-map.md): 各リポジトリのコミットされたマップ。CIでチェックされる。
+
+これらは、ある組織の標準です。もし貴社の標準と異なる場合は、ルールファイルとルールを合わせて変更してください。
+
+ルールは、見た目が似ているものを区別するように設計されており、それらをまとめてしまうとノイズが発生するためです。
+
+- **赤いデフォルトブランチは、赤いプルリクエストブランチではありません。** 失敗したDependabotブランチはバックログであり、デフォルトブランチで失敗した`push`の実行は、問題です。どちらであるかは、実行のイベントによって決まります。
+- **履歴は、問題ではありません。** リリース専用のトリガーに移動したワークフローは、最後のデフォルトブランチでの失敗を永久に保持します。削除されたワークフローは、その実行を保持します。どちらも、現在の欠陥ではありません。
+- **必須チェックで何も出力できない場合、それはここで実行されなかったチェックではありません。** 片方は、要件を削除すると言っています。もう片方は、トリガーを修正すると言っています。これらの修正は、互いに矛盾しています。
+- **失敗した実行は、キャンセルされた実行ではありません。** `cancel-in-progress`は、古い実行を停止するために存在するため、キャンセルされた時間は通常、同時実行ルールの動作によるものです。
+- **総コストは、純コストではありません。** GitHubは、パブリックリポジトリを定価で計測し、割引を適用してゼロにします。総コストは実際の計算量であり、純コストは実際の費用です。これらは決して合計されません。
+- **計測されていないものは、問題ありません。** GitHubがスキャンしていないリポジトリは、0件のアラートを報告します。コストのチェックに達していないリポジトリは、コストの行を持ちません。どちらも、不明として報告されます。
+
+重大度によって、健全性スコアが決まります。重大なものは40、高いものは15、中程度のものは6、低いものは2、情報提供のみのものは0。これらはすべて、100から差し引かれます。スコアは、品質ではなく、注意の優先順位を示します。
+
+[ハンドブック](https://mcp-tool-shop-org.github.io/housekeeping/handbook/)には、すべての検出結果、コマンド、エラーコード、およびテーブルがリストされています。
+
+## セキュリティ
+
+- **読み取り専用。** コレクターは、GraphQLクエリとREST `GET`を発行します。決してマージ、プッシュ、リリース、公開、または設定を編集することはありません。
+- **認証情報なし。** 認証は、`gh`がすでに保持しているものを使用します。それに関する情報はディスクに書き込まれません。
+- **テレメトリーなし。** 連絡するホストは、GitHub API（`gh`経由）と、バージョンおよびアドバイザリの検索のためのnpmレジストリのみです。
+- **保存する内容**が機密性の高い部分です。「データのプライバシーを保護する」を参照してください。
+
+[SECURITY.md]に記載されているように、脆弱性を報告してください。
+
+## テスト
+
+```bash
+npm test
+```
+
+すべてのルールは、両方向でテストされます。つまり、トリガーされるべき形状と、トリガーされるべきでない隣接する形状です。別の検証ツールは、独自のトランスポートを使用して、ライブGitHubから検出結果のサンプルを再構築し、データベースまたはネットワークがない場合は、エラーメッセージを大きく表示します。
+
+## ライセンス
+
+MIT。 [LICENSE](LICENSE)を参照してください。
+
+---
+
+<a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>によって作成されました。