test(miner): verify package skeleton wiring (#2287)

[kiannidev]

Summary

• Add README local-checkout install parity with gittensory-mcp (npm link --workspace @jsonbored/gittensory-miner).
• Add contract tests verifying the miner package skeleton matches sibling packaging conventions: package.json fields, CLI shebang, workspace discovery, and --help/--version entry points.

Closes #2287

Conflict avoidance

Touches only packages/gittensory-miner/README.md and test/unit/miner-package-skeleton.test.ts. No overlap with open PRs #3623, #3625, #3651, or #3652.

Test plan

• test/unit/miner-package-skeleton.test.ts
• npm run typecheck
• npm run build --workspace @jsonbored/gittensory-miner

Made with Cursor

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 23:39:31 UTC}

2 files · 1 AI reviewer · no blockers · readiness 80/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This PR adds a contract test (miner-package-skeleton.test.ts) that pins gittensory-miner's package.json fields, CLI shebang, workspace discoverability, and --help/--version output against the sibling gittensory-mcp conventions, plus a matching README line documenting `npm link --workspace @​jsonbored/gittensory-miner` for local-checkout installs. The new test correctly reuses the existing `runCapture` harness from miner-cli.test.ts and its README assertion matches the exact string added to the README, so the test and the doc change are coherent with each other. This is narrow, test/doc-only scope tied to the referenced issue #2287, and CI (build/typecheck/tests) is green.

Nits — 4 non-blocking

• test/unit/miner-package-skeleton.test.ts imports the harness as "./support/miner-cli-harness.js" (with extension) while the sibling test/unit/miner-cli.test.ts imports the same module without the .js extension — worth aligning on one convention.
• The `npm ls --workspace ... --depth=0` shell-out in the 'is discoverable from the repo root workspace' test adds a real subprocess spawn per test run; consider whether a lighter check (e.g. reading root package.json workspaces or resolving the package via require.resolve) would be faster and less environment-dependent.
• Consider asserting `miner.files` more strictly (e.g. `toEqual(['bin','lib'])` or including expected exclusions) rather than `arrayContaining`, so an unexpected extra published path doesn't silently pass.
• Since this test intentionally diffs against gittensory-mcp's package.json, a short comment noting that intent (why mcp is the source of truth) would help future readers understand why failures here may indicate mcp drifted, not just miner.

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

Review context

• Author: kiannidev
• 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, MDX, C++, HTML, Rust
• Official Gittensor activity: 1485 PR(s), 48 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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.28%. Comparing base (c28d0ac) to head (3047b32).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3653   +/-   ##
=======================================
  Coverage   93.28%   93.28%           
=======================================
  Files         314      314           
  Lines       32054    32054           
  Branches    11747    11747           
=======================================
  Hits        29903    29903           
  Misses       1517     1517           
  Partials      634      634           

🚀 New features to boost your workflow:

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

[loopover-orb]

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