feat(miner): scaffold gittensory-miner package

[Helios531]

Summary

This PR implements #2287 by adding the initial gittensory-miner workspace package scaffold.
It mirrors the existing @jsonbored/gittensory-mcp packaging shape closely:

• public npm package metadata
• CLI bin entrypoint
• minimal --help / version behavior
• package README stub
• workspace installation/build wiring

Because #2287 requires the miner package to depend on @jsonbored/gittensory-engine, this PR also adds the smallest engine workspace placeholder needed to keep the workspace installable. It does not implement any real engine or miner runtime logic yet.

Related Issue

Closes: #2287

Change Type

• New feature
• Package scaffolding
• CLI foundation
• Test update
• Bug fix
• Database migration
• Docs-only change

Real Behavior Proof

Before

• @jsonbored/gittensory-miner did not exist as a workspace package
• there was no gittensory-miner CLI entrypoint
• the required workspace dependency on @jsonbored/gittensory-engine could not resolve because that package did not exist yet

After

• the repo installs with a discoverable @jsonbored/gittensory-miner workspace
• gittensory-miner --help prints the foundation CLI usage
• gittensory-miner version prints the package version and Node runtime
• the miner package builds successfully
• the minimal engine workspace exists so the miner dependency resolves cleanly

Validation

• Workspace install passes
• Miner workspace is discoverable
• Miner package build passes
• Engine placeholder build passes
• Focused unit tests pass
• Repo typecheck passes

Commands Run

npm install
npm ls --workspace @jsonbored/gittensory-miner
npm --workspace @jsonbored/gittensory-miner run build
npm --workspace @jsonbored/gittensory-engine run build
npx vitest run test/unit/miner-cli.test.ts
npm run typecheck

Checklist

• gittensory-miner workspace package added
• CLI bin mapping added
• --help behavior added
• version behavior added
• README stub added
• Local dependency on @jsonbored/gittensory-engine resolves
• Unit tests added
• Validation completed
• Branch pushed

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.71%. Comparing base (17d70b2) to head (fb8d120).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2389   +/-   ##
=======================================
  Coverage   95.71%   95.71%           
=======================================
  Files         222      222           
  Lines       24661    24661           
  Branches     8949     8949           
=======================================
  Hits        23605    23605           
  Misses        433      433           
  Partials      623      623           

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-02 03:55:52 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This PR cleanly adds the miner and placeholder engine workspace packages, with a minimal CLI entrypoint and focused helper tests for help, version, and unknown-command behavior. The visible code paths are coherent: package metadata resolves the CLI version, the bin wrapper dispatches supported commands before falling through to `runCli`, and the engine placeholder is importable through its package export. I do not see a reachable correctness or packaging break in the provided diff.

Nits — 6 non-blocking

• nit: `test/unit/miner-cli.test.ts:29` hard-codes `0.1.0`, so the test will need a manual edit on every legitimate package version bump instead of asserting the CLI reads the current package metadata.
• nit: `packages/gittensory-miner/lib/cli.js:20` reports an empty unknown command if `runCli([])` is called directly; the bin wrapper prevents that path today, but the exported helper is less clear in isolation.
• nit: `packages/gittensory-engine/package.json:3` and `packages/gittensory-miner/package.json:3` introduce publishable `0.1.0` packages without changelog or release-note scaffolding, which may matter if this repo expects package releases to follow the existing MCP package conventions.
• In `test/unit/miner-cli.test.ts:29`, compare the imported package version to the output from `printVersion` instead of a literal `0.1.0`, so future version bumps do not require updating the test assertion itself.
• In `packages/gittensory-miner/lib/cli.js:20`, consider making the direct helper path explicit with a fallback like `const command = cliArgs[0] ?? "<none>";` or keep `runCli` unexported until there are real subcommands.
• 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	✅ No-issue rationale	PR body explains why no issue is linked.
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:M; no linked issue context).
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: 111 registered-repo PR(s), 67 merged, 3 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	Helios531; Gittensor profile; 111 PR(s), 3 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: Helios531
• 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: 111 PR(s), 3 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (PR #2378)
• Related work: Titles/paths share 6 meaningful terms. (PR #2404)
• Related work: Titles/paths share 6 meaningful terms. (PR #2392)
• 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.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• 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

[Helios531]

@JSONbored I am going to contribute this project, Could u plz review my PR?

[JSONbored]

@JSONbored I am going to contribute this project, Could u plz review my PR?

Stop asking for reviews, otherwise you'll wait 5 days for reviews. I review them when I review them, be patient.

[JSONbored]

Merge conflicts, closing.

This branch has conflicts that must be resolved
Use the [web editor](https://github.com/JSONbored/gittensory/pull/2389/conflicts) or the command line to resolve conflicts before continuing.

package-lock.json
packages/gittensory-engine/package.json