feat(miner-packaging): add startup npm version nudge to gittensory-miner

[andriypolanski]

Summary

• Closes feat(miner-packaging): add version/compatibility check on gittensory-miner startup #2331.
• Adds @jsonbored/gittensory-miner workspace scaffold (CLI bin, --help / --version, engine placeholder dependency) so the packaging issue can extend a real entrypoint.
• On every gittensory-miner invocation, starts an async npm registry lookup (5s timeout, GITTENSORY_NPM_REGISTRY_URL override) and prints npm install -g @jsonbored/gittensory-miner@latest to stderr when the installed version is behind npm latest — without blocking or failing the requested command.
• Supports --no-update-check and GITTENSORY_MINER_NO_UPDATE_CHECK=1 for offline/air-gapped fleets; registry/network failures are silently swallowed.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run build:miner
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• Mirrors packages/gittensory-mcp/bin/gittensory-mcp.js lines 13–17 (packageVersion / npmRegistryUrl / upgradeCommand) and the semver/npm-latest helpers used by inspectInstallVersion.
• Overlaps with open PR feat(miner): scaffold gittensory-miner package #2389 (#2287 miner skeleton); this branch includes the minimal scaffold needed to wire the startup check. Rebase or coordinate if feat(miner): scaffold gittensory-miner package #2389 merges first.
• build:miner added to root test:ci so the new workspace package is syntax-checked in CI.

Files changed

Path	Purpose
packages/gittensory-engine/	Minimal workspace placeholder so miner dependency resolves
packages/gittensory-miner/bin/gittensory-miner.js	CLI entry; awaits parallel update check before exit
packages/gittensory-miner/lib/update-check.js	Registry fetch, semver compare, nudge + opt-out
packages/gittensory-miner/lib/cli.js	--help / unknown-command helpers
test/unit/miner-cli.test.ts	Stale/current/offline/opt-out coverage (#2331 deliverables)
test/unit/support/miner-cli-harness.ts	Local npm registry fixture + spawn helpers
package.json	build:miner script; wired into test:ci
package-lock.json	Workspace install metadata

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-02 04:51:17 UTC}

11 files · 1 AI reviewer · no blockers · readiness 55/100 · CI green · blocked

⏸️ Suggested Action - Manual Review

Review summary
The diff adds a new `@​jsonbored/gittensory-miner` workspace package with a minimal CLI, package metadata, npm version nudge logic, CI wiring, and focused tests. The startup check is intentionally non-fatal, validates the registry override before fetching, and the CLI exits promptly by racing the lookup against a short grace window. I do not see a reachable correctness break in the provided post-change files.

Nits — 6 non-blocking

• nit: packages/gittensory-miner/lib/update-check.js:46 accepts strings like `1.2.3not-semver` because the semver regex is not anchored, so tighten it if this helper is expected to stay semver-shaped outside package metadata.
• nit: test/unit/support/miner-cli-harness.ts:18 and :38 leave `run`, `runAsync`, and `tempEnvPrefix` unused in the new tests, so drop them or add the coverage that needs them before this harness grows stale.
• nit: packages/gittensory-miner/README.md:36 documents `GITTENSORY_NPM_REGISTRY_URL` but does not mention `GITTENSORY_MINER_NO_UPDATE_CHECK=1`, even though the CLI help and implementation support it.
• packages/gittensory-miner/lib/update-check.js:46: change the parser regex to require end-of-string after optional prerelease/build metadata, or delegate to a semver helper if this package later gains one.
• test/unit/miner-cli.test.ts:83: add one assertion for a registry override with a non-root path, since `resolveNpmRegistryUrl` preserves paths and `fetchLatestPackageVersion` appends the package path to that base.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2331
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (size label size:L; 1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 108 registered-repo PR(s), 72 merged, 5 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 108 PR(s), 5 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 108 PR(s), 5 issue(s).
• Related work: Items reference the same linked issue feat(miner-packaging): add version/compatibility check on gittensory-miner startup #2331. (issue #2331)
• Related work: Open PR work references issue feat(miner-packaging): add version/compatibility check on gittensory-miner startup #2331. (issue #2331)
• Related work: Titles/paths share 6 meaningful terms. (PR #2389)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.83%. Comparing base (28b345a) to head (ea52776).
⚠️ Report is 53 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2404   +/-   ##
=======================================
  Coverage   95.83%   95.83%           
=======================================
  Files         224      224           
  Lines       25006    25006           
  Branches     9094     9094           
=======================================
  Hits        23964    23964           
  Misses        428      428           
  Partials      614      614           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[andriypolanski]

Hi, @JSONbored
Could you please let me know what I have to fix as Gittensory Orb Review Agent reviewed?

[JSONbored]

It just told you.

[JSONbored]

Follow the blockers listed in the AI review. Once i enable automatic mode PRs will be closed automatically.

[andriypolanski]

Thanks for letting me know. I will fix righ now.

[superagent-security]

Superagent found 1 security concern(s).

[andriypolanski]

I just completed work, could you please review again?
Thanks

[JSONbored]

I just completed work, could you please review again? Thanks

Moving forward, please don't ask for reviews. I'm aware it needs a review, i'm working through them as time permits.

The code of conduct and contribution docs both mention +5 day waits for reviews for "review nagging" - just a heads up.