{"id":50987919,"url":"https://github.com/fredericosanntana/midnight-doctor","last_synced_at":"2026-07-07T20:00:32.394Z","repository":{"id":354277110,"uuid":"1222991431","full_name":"fredericosanntana/midnight-doctor","owner":"fredericosanntana","description":"Pre-flight check for Midnight Network projects: catches version mismatches, duplicate ledgers, broken configs before silent debugging.","archived":false,"fork":false,"pushed_at":"2026-04-27T23:22:55.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T19:08:51.899Z","etag":null,"topics":["cli","compatibility","developer-tools","doctor","midnight","midnight-network","midnightntwrk","preflight","zero-knowledge","zk"],"latest_commit_sha":null,"homepage":"https://github.com/fredericosanntana/midnight-doctor","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fredericosanntana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T22:57:36.000Z","updated_at":"2026-05-25T07:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fredericosanntana/midnight-doctor","commit_stats":null,"previous_names":["fredericosanntana/midnight-doctor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fredericosanntana/midnight-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fredericosanntana%2Fmidnight-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fredericosanntana%2Fmidnight-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fredericosanntana%2Fmidnight-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fredericosanntana%2Fmidnight-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fredericosanntana","download_url":"https://codeload.github.com/fredericosanntana/midnight-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fredericosanntana%2Fmidnight-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35241029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","compatibility","developer-tools","doctor","midnight","midnight-network","midnightntwrk","preflight","zero-knowledge","zk"],"created_at":"2026-06-19T22:00:22.634Z","updated_at":"2026-07-07T20:00:32.387Z","avatar_url":"https://github.com/fredericosanntana.png","language":"JavaScript","funding_links":[],"categories":["Developer Tools"],"sub_categories":[],"readme":"# midnight-doctor\n\n\u003e Pre-flight check for Midnight Network projects. Catches version mismatches, duplicate ledgers, broken configs — **before** you spend 6 hours watching `waitForSyncedState()` run forever.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n\n## Why\n\nBuilding on [Midnight](https://midnight.network) is harder than it should be. Not because the protocol is wrong — Compact and the shielded/unshielded/dust split are genuinely good — but because the **information you need to align your stack is scattered across Discord pinned messages, GitHub READMEs, and conflicting tutorials**.\n\nSome real failure modes that cost the author days:\n\n- `wallet-sdk-facade@2.0.0` paired with `midnight-node:0.21.0` → `waitForSyncedState()` hangs forever, **no error**.\n- A community tutorial recommends `.npmrc` with `@midnight-ntwrk:registry=https://npm.midnight.network/` — that domain has **no DNS record**. `npm install` fails with ENOTFOUND, newbie quits.\n- Two versions of `@midnight-ntwrk/ledger-v7` end up in `node_modules` after a transitive bump → silent transaction failures.\n\nThis tool reads your project, your Docker containers, and your config files; cross-references them against a verified compatibility matrix; and tells you what's wrong **in seconds**, not hours.\n\n## Install\n\n```bash\n# global (recommended for CLI use)\nnpm install -g midnight-doctor\n\n# or run via npx without installing\nnpx midnight-doctor\n```\n\n## Usage\n\n```bash\n# Run against current directory\nmidnight-doctor\n\n# Run against a specific project\nmidnight-doctor ~/projects/my-midnight-app\n\n# Machine-readable output for CI\nmidnight-doctor --json | jq '.diagnostics[] | select(.severity == \"error\")'\n```\n\n### Example output\n\n```\n── midnight-doctor ──\nproject: /root/midnight-hello-world\n\n⚠ SDK track: Preprod 3.x (legacy, OK for existing apps)\n   Detected from wallet-sdk-facade@2.0.0.\n⚠ Track is deprecated\n   SDK 3.2 / facade 2.0 is 2 majors behind. Current is wallet-sdk@1.0.0 / facade@4.0.0\n   (released 2026-04-23). The WalletFacade.init({...}) constructor used in 2.0 has been\n   removed; 4.0 reverted to `new WalletFacade(s, u, d) + .start()`. Plan a migration.\n⚠ WalletFacade.init() in 2.x stalls on standalone dev nodes\n   In SDK 2.x, WalletFacade.init() subscribes to runtime version events that the\n   standalone node closes early. The wallet hangs in 'syncing' state forever with no error.\n   → fix: Either (a) develop against preprod once past hello-world, or (b) upgrade to\n     wallet-sdk-facade@4.0.0 which reverted to constructor + .start() pattern.\n✓ node: midnightntwrk/midnight-node:0.21.0\n✓ indexer: midnightntwrk/indexer-standalone:4.0.0-rc.4\n✓ proof-server: midnightntwrk/proof-server:7.0.0\n✓ midnight-node:0.21.0 matches SDK track\n\nsummary: 4 ok  3 warn  0 error  0 info\n\nStatus: workable, but warnings deserve a look.\n```\n\n## What it checks\n\n### Package alignment\n\n- Detects which **SDK track** your project is on (`current`, `preprod-3x`, `preprod-1x`)\n- Flags deprecated tracks with migration guidance\n- Detects **major-version mismatch** across `wallet-sdk-*` subpackages (silent type errors at runtime)\n- Walks `node_modules` to detect **duplicate installs** of `ledger-v7`, `compact-runtime`, etc.\n\n### Docker stack\n\n- Reads `docker ps` and identifies running `midnight-node`, `indexer-standalone`, `proof-server`\n- **Cross-references node tag with SDK track** — flags mismatches that cause silent sync failures\n\n### Config files\n\n- `.npmrc` — flags the bogus `npm.midnight.network` registry\n- `indexer.yml` — flags missing `subscription:` block (causes 4.x indexer crash loops)\n\n### Known issues\n\nThe matrix encodes specific bugs and their fixes:\n\n| ID | Severity | What it catches |\n|----|----------|-----------------|\n| `npmrc-bad-registry` | error | `npm.midnight.network` in `.npmrc` |\n| `duplicate-ledger-v7` | error | Two `@midnight-ntwrk/ledger-v7` in `node_modules` |\n| `duplicate-ledger-v8` | error | Two `@midnight-ntwrk/ledger-v8` in `node_modules` |\n| `ledger-v7-and-v8-coexist` | warn | Both ledger majors present (in-flight migration) |\n| `duplicate-runtime` | error | Two `@midnight-ntwrk/compact-runtime` in `node_modules` |\n| `facade-2x-init-bug` | warn | `wallet-sdk-facade@2.x` (standalone hang) |\n| `facade-major-mismatch` | error | `wallet-sdk-*` subpackages span multiple majors |\n| `proof-server-major-stale` | warn | `proof-server` major behind support matrix (pre-8.x) |\n| `node-major-stale` | warn | `midnight-node` older than 0.22.x line |\n| `indexer-subscription-block` | warn | Missing `subscription:` in `indexer.yml` |\n| `node-track-mismatch` | error | Docker node tag doesn't match SDK track |\n\n## Compatibility matrix\n\nThe verified matrix lives in [`data/compatibility-matrix.json`](data/compatibility-matrix.json) and is keyed by **track**. The `current` track mirrors the official Midnight support matrix at [docs.midnight.network/relnotes/support-matrix](https://docs.midnight.network/relnotes/support-matrix).\n\nVerified state (2026-04-27):\n\n| Component | Current track | Source |\n|-----------|--------------|--------|\n| `@midnight-ntwrk/wallet-sdk-facade` | `3.0.0` | docs |\n| `@midnight-ntwrk/midnight-js-*` | `4.0.4` | docs |\n| `@midnight-ntwrk/compact-runtime` | `0.15.0` | docs |\n| `@midnight-ntwrk/compact-js` | `2.5.0` | docs |\n| `@midnight-ntwrk/ledger-v8` | `8.0.3` | docs |\n| `midnight-node` (Docker) | `0.22.3` (Preview) / `0.22.2` (Preprod) / `0.22.1` (Mainnet) | docs |\n| `indexer-standalone` (Docker) | `4.0.1` | docs |\n| `proof-server` (Docker) | `8.0.3` | docs |\n| Compact compiler | `0.30.0` | docs |\n\nThe matrix also tracks:\n\n- **`preview`** — npm `latest` tags ahead of the support matrix (`wallet-sdk-facade@4.0.0`, `wallet-sdk@1.0.0`)\n- **`legacy-v7-facade-2`** — pre-v8-ledger stacks (the legacy track most existing apps live on)\n- **`archaeological-facade-1`** — pre-2.x SDK, unsupported\n\n\u003e The matrix is human-curated. To suggest updates, open a PR against `data/compatibility-matrix.json`.\n\n## Programmatic API\n\n```js\nimport { runDoctor } from 'midnight-doctor';\n\nconst result = await runDoctor({ projectDir: process.cwd() });\nconsole.log(result.diagnostics);\nconsole.log(result.report.text);\nconsole.log(result.report.counts); // { ok, warn, error, info }\n```\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | No errors (warnings allowed) |\n| 1 | At least one error found |\n| 2 | Internal failure |\n\nCI-friendly: fail your build if doctor reports errors.\n\n```yaml\n# .github/workflows/ci.yml\n- run: npx midnight-doctor\n```\n\n## Contributing\n\nThe most valuable contribution is **keeping the compatibility matrix current**. When `@midnight-ntwrk/*` packages bump or new known issues surface:\n\n1. Verify versions with `npm view @midnight-ntwrk/\u003cpkg\u003e version`\n2. Update `data/compatibility-matrix.json`\n3. Bump `verifiedAt` to today's date\n4. Add a regression test in `test/diagnose.test.js` if a new check is added\n\nRun tests:\n\n```bash\nnpm test\n```\n\n## Roadmap\n\n- [ ] Auto-detect monorepos (turbo / pnpm workspaces) and check each workspace\n- [ ] `--fix` flag that runs `npm dedupe` / removes bogus `.npmrc` automatically\n- [ ] Compact compiler version check (`compactc --version` vs `compact-runtime`)\n- [ ] Health probe — actually `curl` indexer/RPC/proof endpoints, not just Docker presence\n- [ ] Compatibility matrix fetched from a remote source so users don't need to update the package\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Author\n\nFrederico Santana ([@DPO2U](https://dpo2u.com)) — built while shipping 4 apps on Midnight (`midnight-hello-world`, `dpo2u-midnight-agents`, `dpo2u-wallet`, `dpo2u-midnight-lab`) and tired of debugging silent failures.\n\n## Acknowledgements\n\nThe Midnight devs in `#dev-help` on Discord — half the matrix entries came from their pinned messages and patient answers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffredericosanntana%2Fmidnight-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffredericosanntana%2Fmidnight-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffredericosanntana%2Fmidnight-doctor/lists"}