feat(miner): add a level-aware logging abstraction for the CLI (#4835)

[cleanjunc]

Summary

Closes #4835.

The miner CLI had no logging dependency or abstraction at all — every command reached for ad hoc console.log/console.error, so an operator could neither quiet routine chatter nor turn on verbose diagnostics. This adds a minimal, dependency-light, level-aware logger the CLI configures once at startup and every command can share.

• lib/logger.js — a level-aware logger over an ordered severity scale (silent < error < warn < info < debug). A logger emits a method only when its severity is at or below the active level; error/warn go to stderr and info/debug to stdout, matching the CLI's existing stdout-output / stderr-nudge split. It is fully injectable (streams, now, env) so the level/format logic is pure and unit-testable. Extras: structured key=value fields (sorted, deterministic), child() context loggers, a pretty mode with a timestamp + level tag, and a process-wide instance via configureLogger/getLogger.
• Level is configurable via flag or env (acceptance criterion): --quiet → error, --verbose → debug, --log-level <silent|error|warn|info|debug>, or GITTENSORY_MINER_LOG_LEVEL. An explicit level wins, then quiet, then verbose, then env, then the info default; an unrecognized value is ignored rather than throwing. No -q/-v short aliases, since -v/-h are already --version/--help in the entrypoint.
• Wiring — bin/gittensory-miner.js peels the global logging flags off argv with extractLogOptions and calls configureLogger once at startup (so the stripped argv is what command dispatch sees, and every command shares one configured logger via getLogger). The new flags are documented in --help.

Migrating the remaining ad hoc console.* call sites onto this logger is intentionally left to follow-ups so this PR stays a focused, reviewable abstraction + wiring change.

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 a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• 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 audit --audit-level=moderate
• npm run build:miner and npm run miner:env-reference:check
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

New/changed behavior is fully unit-tested in test/unit/miner-logger.test.ts — every branch of logger.js is exercised (verified locally via lcov: 54/54 branches, 65/65 lines, 17/17 functions). The only backend files this touches are lib/logger.js (fully covered) and three branch-free help-text lines in lib/cli.js (covered by the existing printHelp test). Added lib/logger.js to build:miner's node --check list and regenerated packages/gittensory-miner/docs/env-reference.md for the new GITTENSORY_MINER_LOG_LEVEL read.

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. — N/A: no auth/session/network surface changes; the logger is offline and dependency-free.
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A: no API/OpenAPI/MCP surface change.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A: no UI change (CLI/terminal only).
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots. — N/A: this is a CLI/backend change with no visible frontend surface.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. — regenerated the miner env-reference doc; no changelog edit.

UI Evidence

N/A — this is a CLI/backend (packages/gittensory-miner) change with no visible UI, frontend, docs page, or extension surface.

Notes

The env-reference doc row (GITTENSORY_MINER_LOG_LEVEL) is generated by npm run miner:env-reference, not hand-edited.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.91%. Comparing base (f0b1840) to head (5b22405).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5550   +/-   ##
=======================================
  Coverage   94.90%   94.91%           
=======================================
  Files         569      570    +1     
  Lines       45260    45325   +65     
  Branches    14675    14675           
=======================================
+ Hits        42955    43020   +65     
  Misses       1571     1571           
  Partials      734      734           

Flag	Coverage Δ
shard-1	44.14% <0.00%> (-0.08%)	⬇️
shard-2	35.41% <0.00%> (-0.05%)	⬇️
shard-3	31.89% <0.00%> (-0.25%)	⬇️
shard-4	31.74% <0.00%> (+0.58%)	⬆️
shard-5	32.88% <100.00%> (-0.05%)	⬇️
shard-6	44.38% <0.00%> (+0.19%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/cli.js	100.00% <ø> (ø)
packages/gittensory-miner/lib/logger.js	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[gittensory-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 04:40:34 UTC}

7 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a clean, well-tested level-aware logger module with injectable streams/env/clock, plus wiring into the CLI entrypoint that peels off --quiet/--verbose/--log-level before dispatch. The implementation is correct: resolveLogLevel's precedence (explicit > quiet > verbose > env > default) matches the docs and tests, extractLogOptions correctly strips flags so downstream commands never see them, and the logger itself is pure/injectable and thoroughly unit-tested (218 lines covering constants, resolution, extraction, formatting, gating, fields/child, pretty mode, env, and the singleton). The PR is intentionally scoped to the abstraction + wiring only, leaving migration of existing console.* call sites to follow-ups as stated.

Nits — 5 non-blocking

• The new logger is configured and documented but no existing command actually uses getLogger() yet — every command still calls console.log/console.error directly, so the abstraction has no real callers in this diff; that's explicitly deferred per the description, just flagging it's not yet exercised in production code paths.
• packages/gittensory-miner/lib/logger.js: the external brief's 'magic number 8601' flag is a false positive — that's just the digits in the word 'ISO-8601' inside a comment, not a numeric literal.
• extractLogOptions silently drops a bare trailing `--log-level` with no value (test asserts `level` is `undefined`) rather than treating it as a usage error; worth a one-line doc note but not a functional problem given resolveLogLevel falls back to the default.
• Consider a follow-up issue tracking the console.* → logger migration so Add a real logging abstraction to the miner CLI #4835's abstraction actually gets adopted across commands.
• docs/env-reference.md is auto-generated (per its own header) and was correctly regenerated to include GITTENSORY_MINER_LOG_LEVEL — good attention to that contract.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#4835
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 69 registered-repo PR(s), 29 merged, 30 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	cleanjunc; Gittensor profile; 69 PR(s), 30 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The PR delivers a correctly-implemented, well-tested, and properly wired logging abstraction that closes the linked issue, though its value is capped until existing console.* call sites actually migrate onto it in follow-up work.

Linked issue satisfaction

Partially addressed
The PR adds a solid, well-tested level-aware logger with configurable level via flags/env (satisfying the acceptance criterion), but explicitly defers the deliverable of migrating existing CLI console.log/console.error call sites onto the new logger to a follow-up PR, so the shared module is not yet used consistently across CLI commands.

Review context

• Author: cleanjunc
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 69 PR(s), 30 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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

[gittensory-orb]

Gittensory approves — the gate is satisfied and CI is green.