feat(miner): add laptop-mode init and doctor commands

[9876543210-tc-0123456789]

Summary

• Closes feat(miner-packaging): add laptop-mode CLI entry (SQLite, no Docker, npm install-and-run) #2329 by adding zero-infra gittensory-miner init and gittensory-miner doctor commands to the packaged CLI.
• init now resolves the local config directory through GITTENSORY_MINER_CONFIG_DIR, XDG_CONFIG_HOME, then the homedir fallback, and always bootstraps the real SQLite-backed run-state store so an existing empty file is repaired instead of being treated as ready.
• doctor reports Node, config-dir, SQLite file/schema health, and Docker availability as informational only, and the README plus CLI/laptop-mode tests now cover the npm quickstart, idempotent bootstrap, and absent-Docker path.

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 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

If any required check was skipped, explain why:

• npm run test:coverage was exercised as npm run test:coverage -- --maxWorkers=4, which passed on the rebased branch and matches the CI-stable worker cap used during local validation.
• npm run test:ci was rerun from the rebased branch to smoke the full wrapper, but its uncapped npm run test:coverage leg is host-load-sensitive here; the required sub-checks above were still run and verified individually.

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.

UI Evidence

Required for visible UI, frontend, docs, or extension changes. Attach GitHub-hosted JPG/JPEG or PNG screenshots here; SVG screenshots are not accepted as review evidence. Use a compact table/grid of clickable thumbnails with a short state/title such as "Loaded state", "Empty state", "Error state", "Mobile layout", or "PR sidebar". Prefer annotated screenshots with a colored box, outline, arrow, or highlighter showing what changed. Recordings can be supplemental, but screenshots are still expected for visual review. Do not commit review-only screenshots, recordings, or docs/review-evidence/** files.

State / title	JPG/PNG evidence
No visible UI changes	N/A

Notes

• No visible UI changes in this PR.
• The generated apps/gittensory-ui/src/lib/selfhost-env-reference.ts line references were refreshed so the self-host env-reference check stays green.

[codecov]

❌ 4 Tests Failed:

Tests completed	Failed	Passed	Skipped
7785	4	7781	7

View the full list of 4 ❄️ flaky test(s)

test/unit/opportunity-branch-internals.test.ts > opportunity branch internals > issueAgeDays floors invalid timestamps to stale age

Flake rate in main: 66.67% (Passed 1 times, Failed 2 times)

Stack Traces | 0.0155s run time

AssertionError: expected +0 to be 9999 // Object.is equality

- Expected
+ Received

- 9999
+ 0

 ❯ test/unit/opportunity-branch-internals.test.ts:43:37

test/unit/opportunity-freshness.test.ts > computeOpportunityFreshness > accepts uppercase state labels and treats missing timestamps as stale

Flake rate in main: 66.67% (Passed 1 times, Failed 2 times)

Stack Traces | 0.0121s run time

AssertionError: expected 1 to be 0.05 // Object.is equality

- Expected
+ Received

- 0.05
+ 1

 ❯ test/unit/opportunity-freshness.test.ts:26:97

test/unit/opportunity-freshness.test.ts > computeOpportunityFreshness > falls back cleanly when timestamps are absent or non-string

Flake rate in main: 66.67% (Passed 1 times, Failed 2 times)

Stack Traces | 0.00132s run time

AssertionError: expected 1 to be 0.05 // Object.is equality

- Expected
+ Received

- 0.05
+ 1

 ❯ test/unit/opportunity-freshness.test.ts:51:7

test/unit/opportunity-metadata-signals.test.ts > opportunity metadata signals > freshness and competition helpers stay pure with injected clocks and safe inputs

Flake rate in main: 66.67% (Passed 1 times, Failed 2 times)

Stack Traces | 0.0159s run time

AssertionError: expected 1 to be 0.05 // Object.is equality

- Expected
+ Received

- 0.05
+ 1

 ❯ test/unit/opportunity-metadata-signals.test.ts:97:7

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-04 01:13:49 UTC}

8 files · 1 AI reviewer · no blockers · readiness 80/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

Review summary
This adds the miner laptop-mode module plus CLI wiring for init/doctor, using the existing run-state SQLite initializer so fresh and empty DB files are repaired on the real schema path. The visible implementation is coherent: config-dir resolution, DB inspection, Docker probing, README updates, and unit/bin tests line up with the stated zero-infra behavior. I did not find a reachable correctness break in the changed code; the remaining issues are scope and CLI polish rather than blockers.

Nits — 5 non-blocking

• nit: apps/gittensory-ui/src/lib/selfhost-env-reference.ts:1 is generated and unrelated to the miner laptop-mode change, so regenerate/split that drift to keep this PR scoped.
• nit: packages/gittensory-miner/lib/cli.js:39 and packages/gittensory-miner/lib/cli.js:51 let filesystem or SQLite failures bubble as raw CLI exceptions; consider catching them and printing a concise init/doctor failure message.
• nit: packages/gittensory-miner/lib/laptop-mode.js:40 creates new config directories with mode 0700 but leaves an already-existing overly broad directory untouched; consider warning in doctor or tightening permissions if privacy is part of the bootstrap contract.
• packages/gittensory-miner/lib/cli.js:39 should wrap initLaptopMode() in a small try/catch that writes the error detail to stderr and returns 1, matching normal CLI failure behavior.
• packages/gittensory-miner/lib/laptop-mode.js:84 could format a missing-but-creatable state DB as not initialized rather than sqlite unavailable, which would make doctor output clearer before init has run.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2329
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	❌ 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: 43 registered-repo PR(s), 22 merged, 3 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	DragunovX16; Gittensor profile; 43 PR(s), 3 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: DragunovX16
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, Python, JavaScript, Clojure, CSS, Cuda, HTML, Java
• Official Gittensor activity: 43 PR(s), 3 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs are re-reviewed automatically, so an inaccurate close may be reopened, but that does not guarantee it can merge (e.g. if conflicts or failing CI remain).