docs: rewrite promo drafts for CLI scanner, health scores, dashboard features

dusan-maintains · dusan-maintains · commit 355b94da07c6 · 2026-03-17T21:54:56.000+05:00
diff --git a/docs/promo/DEVTO_ARTICLE_DRAFT.md b/docs/promo/DEVTO_ARTICLE_DRAFT.md
@@ -1,83 +1,96 @@
 ---
-title: "I built an automated public log to prove I'm actively maintaining OSS packages"
+title: "npm audit catches CVEs. Nothing catches abandoned packages. So I built a scanner."
 published: false
-description: "How I track 1.6M npm downloads/week across 7 abandoned packages using GitHub Actions, machine-readable evidence snapshots, and zero manual updates."
-tags: opensource, github, automation, devops
+description: "A zero-dependency CLI that scans package.json and scores every dependency 0-100 for maintenance health. Plus the full automated monitoring system behind it."
+tags: opensource, javascript, node, npm
 cover_image:
 ---
 
-There's a problem nobody talks about: thousands of npm packages are effectively abandoned while still serving millions of downloads per week. Maintainers disappear. Issues pile up. Security patches sit unmerged. And downstream teams have no way to know.
+## The problem nobody talks about
 
-I maintain 5 of these packages. The challenge: how do you *prove* ongoing maintenance work to upstream maintainers, grant committees, or employers — without private context?
+Thousands of npm packages are effectively abandoned while serving millions of downloads per week. Maintainers disappear. Issues pile up. Security patches sit unmerged. And `npm audit` won't tell you.
 
-So I built this: **[oss-maintenance-log](https://github.com/dusan-maintains/oss-maintenance-log)**
+I maintain 7 of these packages — combined 1.4M npm downloads/week. After getting burned by unmaintained transitive dependencies in my own projects, I built a scanner.
 
-## What it does
+## One command
 
-Every 6 hours, a GitHub Actions workflow:
+```bash
+npx github:dusan-maintains/oss-maintenance-log express lodash moment request
+```
 
-1. Polls the GitHub API for repo metadata (stars, forks, open issues, last push date)
-2. Pulls npm download counts (weekly rolling window)
-3. Tracks PR states, mergeability, and diff stats
-4. Monitors review SLA — flags when maintainer feedback has gone unanswered
-5. Generates a prioritized action queue
-6. Commits machine-readable JSON + human-readable Markdown snapshots
-7. Auto-updates README stats from the fresh data
+```
+  OSS Health Scan Results
+  ──────────────────────────────────────────────────
+  Scanned: 3 packages
+  Average health: 40.8/100
+  ● Critical: 0  ● Warning: 3  ● Healthy: 0
 
-Zero manual updates. Everything is public and auditable.
+   🟡 WARNING
 
-## The packages
+  react-hexgrid     ███████░░░░░░░░░░░░░ 35.1/100  last push 594d ago
+  jquery-modal      ████████░░░░░░░░░░░░ 40.5/100  last push 699d ago
+  rrule             █████████░░░░░░░░░░░ 46.8/100  last push 628d ago
+```
 
-Right now I'm tracking:
+## How the scoring works
 
-| Package | npm/week | Why it needs help |
-|---|---|---|
-| `rrule` | 1,374,236 | 210 open issues, last push 2024 |
-| `python-shell` | 194,847 | Maintainer publicly looking for help |
-| `jquery-modal` | 24,399 | "Maintainers Wanted" in README |
-| `jquery-tablesort` | 1,667 | "Maintainers Wanted" in README |
-| `react-hexgrid` | 1,702 | Maintainer-needed signal in issues |
+Each package gets a weighted health score (0–100):
 
-Combined: **1,596,851 npm downloads/week** across packages that would otherwise have no active maintenance.
+| Dimension | Weight | What it measures |
+|-----------|--------|-----------------|
+| **Maintenance** | 40% | Last push (exponential decay, 180-day half-life), last npm publish (365-day half-life), open issues ratio |
+| **Community** | 25% | Stars and forks (log₁₀ scaled — 100 stars matters more than the difference between 10k and 11k) |
+| **Popularity** | 20% | npm weekly downloads (log₁₀ scaled) |
+| **Risk** | 15% | Penalty-based: >365 days since push (-4), >100 open issues (-3), >2 years since publish (-2) |
 
-## Why public?
+Instant flags: `DEPRECATED` → 5/100, `ARCHIVED` → 8/100.
 
-Accountability. Anyone can verify the work without trusting me. The evidence files are auditable JSON — no private context required.
+The algorithm handles edge cases:
+- High-download packages with no maintainer score high on Popularity but get crushed on Maintenance and Risk
+- Boutique packages with active maintainers score high on Maintenance despite low download counts
+- Mega-repos like Grafana score moderately because their massive issue counts penalize the ratio
 
-It also creates a paper trail. When I open a PR to a package with 200 open issues, I can link to the evidence log to show I'm not a drive-by contributor.
+## Zero dependencies — on purpose
 
-## The architecture
+The tool uses only Node.js built-ins (`https`, `fs`, `path`). A dependency health scanner that itself depends on abandoned packages would be... ironic.
 
-```
-scripts/
-  update-evidence.ps1          # Per-repo PR tracking + npm stats
-  update-ecosystem-status.ps1  # Multi-repo aggregated health snapshot
-  update-review-sla.ps1        # Review response time monitoring
-  update-action-queue.ps1      # Prioritized action queue from SLA data
-  update-readme-stats.ps1      # Patches README with fresh numbers
-evidence/
-  *.json                       # Machine-readable snapshots
-  *.md                         # Human-readable reports
-.github/workflows/
-  evidence-daily.yml           # Cron: every 6 hours
+## CI integration
+
+```yaml
+# .github/workflows/health-check.yml
+name: Dependency Health Check
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  pull_request:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npx github:dusan-maintains/oss-maintenance-log --threshold 30
 ```
 
-PowerShell + GitHub Actions. Runs on both Windows and Linux (pwsh). No external dependencies beyond the GitHub and npm APIs.
+Exits with code 1 if any critical packages found — works as a PR gate.
 
-## Use it yourself
+## The full monitoring system
 
-The repo is marked as a template. Fork it, update the package list in 3 scripts, push — done. MIT licensed.
+The CLI is part of a bigger project. I also built:
 
-```powershell
-# Run locally
-./scripts/update-evidence.ps1
-./scripts/update-ecosystem-status.ps1
-./scripts/update-review-sla.ps1
-./scripts/update-action-queue.ps1
-```
+- **Health trend engine** — 180-day rolling history with 7-day and 30-day deltas. Detects packages that are improving or declining.
+- **Alert system** — Auto-creates GitHub Issues when packages drop below critical threshold.
+- **Review SLA tracker** — Flags when maintainer feedback has gone stale on your PRs.
+- **Interactive dashboard** — Dark-mode Chart.js dashboard with health gauges, radar charts, download distributions.
+
+![Dashboard](https://raw.githubusercontent.com/dusan-maintains/oss-maintenance-log/main/docs/dashboard-preview.png)
+
+Everything runs on GitHub Actions every 6 hours. Config-driven — just edit one JSON file with your packages.
 
-Live dashboard: https://dusan-maintains.github.io/oss-maintenance-log
+**Repo:** [github.com/dusan-maintains/oss-maintenance-log](https://github.com/dusan-maintains/oss-maintenance-log)
+**Live dashboard:** [dusan-maintains.github.io/oss-maintenance-log](https://dusan-maintains.github.io/oss-maintenance-log)
 
 ---
 
-Curious if others have built similar systems. Is there prior art I missed? And if you maintain packages that need help — open an issue, I'm actively looking for the next ones to adopt.
+What tools do you use to monitor dependency health? I'm curious about existing solutions I might have missed.
diff --git a/docs/promo/HN_POST_DRAFT.md b/docs/promo/HN_POST_DRAFT.md
@@ -1,26 +1,31 @@
-# Show HN: I built an automated public log to prove I'm actively maintaining OSS packages
+# Show HN: oss-health-scan — find abandoned npm dependencies before they become risks
 
-**Title:** Show HN: Automated public evidence log for OSS maintenance — self-updates every 6h via GitHub Actions
+**Title:** Show HN: Scan your package.json for abandoned npm packages — health scores 0-100
 
 ---
 
-I maintain 5 npm packages that were effectively abandoned but still serve ~1.6M downloads/week combined. The problem: there's no standard way to prove ongoing maintenance work to upstream maintainers, grant committees, or employers.
+21% of the top 50k npm packages depend on deprecated packages. npm audit catches security vulnerabilities, but not abandoned dependencies.
 
-So I built this: https://github.com/dusan-maintains/oss-maintenance-log
+I built a zero-dependency Node.js CLI that scores every dependency 0–100:
 
-Every 6 hours, GitHub Actions polls the GitHub API and npm, tracks PR states and review SLA, and commits machine-readable JSON + Markdown snapshots. Zero manual updates. The README stats update automatically too.
+    npx github:dusan-maintains/oss-maintenance-log lodash moment request
 
-**What it tracks:**
-- `rrule` — 1.37M npm downloads/week, 210 open issues, my PR fixing WeekdayStr serialization
-- `python-shell` — 195k downloads/week, maintainer publicly looking for help
-- `jquery-modal` / `jquery-tablesort` — both have "Maintainers Wanted" in their READMEs
-- `react-hexgrid` — maintainer-needed signal in issues
-- `grafana` — large-repo signal PR (privacy hardening for email templates)
+It checks:
+- When the repo was last pushed to
+- When the package was last published to npm
+- Open issues ratio
+- GitHub stars and forks (log-scaled)
+- npm download trends
+- Deprecated/archived flags (instant critical score)
 
-**Why public?** Accountability. Anyone can verify the work without private context. The evidence files are auditable JSON.
+Scored using a weighted model: Maintenance 40%, Community 25%, Popularity 20%, Risk 15%. Exponential decay for time-based metrics, logarithmic scaling for count-based ones.
 
-**Use as template:** It's marked as a template repo. Fork it, update the package list in 3 scripts, push — done.
+The tool is part of a larger system I built to track my own OSS maintenance work — I actively maintain 7 abandoned npm packages with 1.4M combined weekly downloads. The full system includes automated evidence collection, review SLA tracking, health trend analysis (180-day rolling window), and auto-alerts via GitHub Issues.
 
-Live dashboard: https://dusan-maintains.github.io/oss-maintenance-log
+Zero external npm dependencies — a health scanner shouldn't be a supply chain risk.
 
-Curious if others have built similar systems, or if there's prior art I missed.
+Repo: https://github.com/dusan-maintains/oss-maintenance-log
+Dashboard: https://dusan-maintains.github.io/oss-maintenance-log
+CLI README: https://github.com/dusan-maintains/oss-maintenance-log/tree/main/cli
+
+Curious about prior art in this space. I know about socket.dev (supply chain) and Snyk (CVEs), but I haven't found anything that specifically scores maintenance health of npm packages.
diff --git a/docs/promo/REDDIT_POST_DRAFT.md b/docs/promo/REDDIT_POST_DRAFT.md
@@ -1,33 +1,39 @@
-**Title:** I built a system that publicly tracks my OSS maintenance work — auto-updates every 6 hours
+**Title:** I built a CLI that scans your package.json for dying npm dependencies — health scores 0-100, zero deps, one command
 
 **Body:**
 
-I maintain 5 npm packages that were abandoned but still serve ~1.6M downloads/week combined. The problem: there's no standard way to prove ongoing maintenance work to upstream maintainers or grant committees.
+21% of the top 50k npm packages depend on deprecated packages. `npm audit` catches CVEs — but not abandoned ones. So I built a scanner.
 
-So I built this: https://github.com/dusan-maintains/oss-maintenance-log
+```
+npx github:dusan-maintains/oss-maintenance-log express lodash moment request
+```
 
-Every 6 hours, GitHub Actions polls GitHub API + npm, tracks PR states and review SLA, and commits machine-readable JSON + Markdown snapshots. Zero manual updates. README stats update automatically too.
+It scores every dependency 0–100 based on:
+- **Maintenance (40%)** — last push, last publish, open issues
+- **Community (25%)** — stars, forks (log-scaled)
+- **Popularity (20%)** — npm downloads/week
+- **Risk (15%)** — inactivity penalty, issue backlog
 
-**What it tracks:**
-- `rrule` — 1.37M npm downloads/week, 210 open issues
-- `python-shell` — 195k downloads/week, maintainer publicly looking for help
-- `jquery-modal` / `jquery-tablesort` — both have "Maintainers Wanted" in their READMEs
-- `react-hexgrid` — maintainer-needed signal in issues
-- `grafana` — large-repo signal PR (privacy hardening)
+DEPRECATED = instant 5/100. ARCHIVED = 8/100.
 
-**Why public?** Accountability. Anyone can verify the work without trusting me. The evidence files are auditable JSON.
+Output is terminal-friendly with colored bars, or `--json` for CI pipelines. Exits with code 1 if any critical packages found — works as a PR gate.
 
-It's also a template repo — fork it, update 3 scripts, push. Done.
+**Zero npm dependencies.** Uses only Node.js built-ins. A scanner for unhealthy dependencies shouldn't itself be a supply chain risk.
 
-Live dashboard: https://dusan-maintains.github.io/oss-maintenance-log
+The tool is part of a bigger system I built after I started maintaining 7 abandoned packages (1.4M npm downloads/week combined). The full system auto-tracks PRs, review SLA, generates health trend charts, and fires alerts when packages degrade. There's a live dark-mode dashboard too:
+
+Dashboard: https://dusan-maintains.github.io/oss-maintenance-log
+Repo: https://github.com/dusan-maintains/oss-maintenance-log
+
+Happy to answer questions about the scoring algorithm or the broader problem of abandoned OSS packages.
 
 ---
 
-**Suggested subreddits:**
-- r/opensource
-- r/github
-- r/devops
-- r/node (for the npm angle)
-- r/javascript
+**Subreddits:**
+- r/node — primary target (npm-focused)
+- r/javascript — broad JS audience
+- r/opensource — OSS health angle
+- r/webdev — dependency management pain
+- r/SideProject — for "Show Off Saturday" thread
 
 **Best posting time:** Tuesday–Thursday, 9–11am US Eastern
